diff --git a/crates/windows-file-watcher-example-test-harness/DESIGN-RATIONALE.md b/crates/windows-file-watcher-example-test-harness/DESIGN-RATIONALE.md index 8ed884437..fb76056a8 100644 --- a/crates/windows-file-watcher-example-test-harness/DESIGN-RATIONALE.md +++ b/crates/windows-file-watcher-example-test-harness/DESIGN-RATIONALE.md @@ -4,7 +4,7 @@ and the reasoning. Keyed by decision ID. This file is consulted for "why" questions; it is not authoritative for current decisions (Tier 1 is). -## D-1: an example, not a framework +## D-1: an example, not a framework A framework that must *compose* with an arbitrary third party's other test infrastructure is an unsolvable problem (see the file-watcher testability discussion). So we do not ship one; we ship a @@ -13,13 +13,13 @@ legible exemplar that composes with nothing by design and is meant to be adapted most consumers will cut-and-paste rather than depend. Legibility beats completeness everywhere the two conflict. -## D-2: public `test-util` surface only +## D-2: public `test-util` surface only This is a forcing function: if the exemplar cannot be built from the public seam, that is a seam gap to fix in `windows-file-watcher`, not to paper over here. So the crate doubles as proof that the M13 seam is sufficient for a real harness. -## D-3: the handler is a trait; capture/replay are handler-linked +## D-3: the handler is a trait; capture/replay are handler-linked Both capture (find a schedule that breaks the handler) and replay (reproduce it) must run the consumer's handler *in-process*, and Rust cannot load an unknown third-party handler into a @@ -27,7 +27,7 @@ prebuilt binary. So this crate's `capture`/`replay` bins run against a **built-i handler**, and are themselves worked examples of how a third party writes their own bins against their own handler using the library. -## D-4: the wire format is harness-owned, not semver-covered +## D-4: the wire format is harness-owned, not semver-covered `windows-file-watcher` does not serialize `Notification`, so the harness defines its own serde-able description of a notification and converts it to a real `Notification` (via the @@ -35,20 +35,20 @@ serde-able description of a notification and converts it to a real `Notification schedule -- not a data contract; its shape may change in any release. Precedent: file-watcher D-71 and topology D-8. -## D-5: the generator emits only contract-legal schedules +## D-5: the generator emits only contract-legal schedules This is the D-83 fidelity principle lifted from values to *schedules*: perturbations (ordering, timing, loss) stay inside what file-watcher's documented contract permits (D-12 in-stream ordering, D-29 loss/backpressure via `Desync`), so a pathology the harness finds is one a real substrate could actually produce -- not a phantom manufactured by an impossible schedule. -## D-6: publication is gated on a published file-watcher with `test-util` +## D-6: publication is gated on a published file-watcher with `test-util` The crate builds in-workspace today via the path dependency, but it cannot be published to crates.io until `windows-file-watcher` is published with the `test-util` feature available. This is a release-ordering constraint, recorded so it is not discovered at publish time. -## D-7: the wire format is deliberately unvalidated +## D-7: the wire format is deliberately unvalidated The format can express schedules file-watcher would never produce (a `Batch` after that watch's `Completion { Cancelled }`, a `Desync { Overflow }` on a watch established `Coarse`, a diff --git a/crates/windows-waitable-queues/DESIGN-NOTES.md b/crates/windows-waitable-queues/DESIGN-NOTES.md index 84052949d..b3360cd1e 100644 --- a/crates/windows-waitable-queues/DESIGN-NOTES.md +++ b/crates/windows-waitable-queues/DESIGN-NOTES.md @@ -5,9 +5,22 @@ This file records the decisions this crate's code is built against. D-1 to D-9 w record nothing is obliged to read; D-10 onwards were taken while building the shapes those decisions called for, and record what the building settled or corrected. -The naming decision -- plural, and no `-sys` suffix -- lives in the workspace -[DESIGN-NOTES.md](../../DESIGN-NOTES.md#the-waitable-queues-crate-is-named-plural-and-carries-no-sys-suffix) -rather than here, since it was taken before this directory existed. +The naming decision -- plural, and no `-sys` suffix -- was taken before this +directory existed, and is summarised here because the full record has not landed +on `main` yet. + +**No `-sys` suffix.** In this workspace that suffix marks a layer: a +`windows-*-sys` crate makes an existing Win32 API memory-safe *without adding +policy*. This crate is a data structure with an opinion -- it chooses a slot +protocol, an overflow policy, and a signalling discipline that Win32 has no +equivalent of -- so `-sys` would misdescribe how much it decides on a caller's +behalf. The convention itself is stated in the repository +[README.md](../../README.md#crate-naming). + +**Plural, because it is a collection of peers rather than one facility.** SPSC +and the MPSC shapes are siblings and no single queue is the queue, which is why +there is deliberately no bare `Queue` type -- a crate named "queues" that +exported one would claim a primacy the name denies. ## Intent diff --git a/design-sessions/DESIGN-SESSION-2026-08-30-numa-sharded-io-execution-domains.md b/design-sessions/DESIGN-SESSION-2026-08-30-numa-sharded-io-execution-domains.md index 621162af6..2eb523c1f 100644 --- a/design-sessions/DESIGN-SESSION-2026-08-30-numa-sharded-io-execution-domains.md +++ b/design-sessions/DESIGN-SESSION-2026-08-30-numa-sharded-io-execution-domains.md @@ -998,9 +998,11 @@ and once there must also re-supply what `std` was doing for it, notably catching unwind at the entry so a panic does not cross an `extern "system"` boundary. Each of those steps is simple. Collectively they are a minefield nobody crosses, -which is the [SMOP principle](../DESIGN-NOTES.md#the-value-is-existence-not-cleverness) -exactly: the value is existence, and when the correct construction is difficult, -providing the constructor *is* the feature. +which is the SMOP principle exactly: the value is existence, and when the correct +construction is difficult, providing the constructor *is* the feature. [The link +here pointed at a workspace DESIGN-NOTES section that has not landed on `main`; +the principle is stated in full by the sentence itself, so the pointer is +dropped rather than left dangling.] **The line is ownership, not construction.** The facility helps *construct* a thread and never *owns* one: a builder assembles the attribute list, applies the