From 9cbeb241198763131e48be800db286b80e3d4e34 Mon Sep 17 00:00:00 2001 From: Mike Grier Date: Sun, 6 Sep 2026 23:13:40 -0400 Subject: [PATCH] docs: repair nine dangling anchors, found by sweeping the class One broken link was known -- `windows-waitable-queues`' design notes pointed at a workspace DESIGN-NOTES section explaining its own name, and that section has never been on `main`. Sweeping every anchored markdown link in the repository rather than fixing the reported one found **nine** broken across three files, with three distinct causes needing three distinct fixes. **Seven: heading slugs that do not match the ids linked to.** `windows-file-watcher-example-test-harness`' DESIGN-NOTES links `#d-1` .. `#d-7` into its DESIGN-RATIONALE, whose headings read `## D-1: an example, not a framework` and therefore slug to `#d-1-an-example-not-a-framework`. Fixed by giving those headings explicit `` anchors -- the convention already used in the DESIGN-NOTES that link to them, and stable against the heading text being reworded later, which is exactly what would break them again. **One: the waitable-queues naming decision, which is not on `main`.** The full record is 88 lines and lives on a feature branch. Rather than link to it or delete the pointer, the crate's notes now state the substance -- why no `-sys` suffix, why plural -- and cite the README's crate-naming section, which does exist here. A reader gets the answer instead of a 404. **One: a Tier-3 design session citing a section that never existed.** The 2026-08-30 session linked `#the-value-is-existence-not-cleverness`, which is not in any DESIGN-NOTES on any branch. The sentence around it already states the principle in full, so the link is dropped and annotated in brackets rather than the session being rewritten -- dated records are not edited to look like they were always right. Two further findings, deliberately not changed: - `crates/windows-ioring-sys/PLANS.md` links `COMPLETED-PLANS.md`, which does not exist. The prose says "once there are any", so it is a deliberate forward reference rather than an oversight. Left as-is; noted so the next sweep does not re-litigate it. - The remaining hits were inside inline-code examples, where a checker matching link syntax cannot tell an illustration from a link. A limitation of the sweep, not defects. After: 273 anchored links across 130 markdown files, zero broken. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../DESIGN-RATIONALE.md | 14 +++++++------- .../windows-waitable-queues/DESIGN-NOTES.md | 19 ++++++++++++++++--- ...08-30-numa-sharded-io-execution-domains.md | 8 +++++--- 3 files changed, 28 insertions(+), 13 deletions(-) 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