@orkestrel/scaffold 0.0.66 → 0.0.68

package/dist/host/agents/templates/brief.md

@@ -41,6 +41,15 @@ _Name each applicable rule file, the dispatch-named skill and its required refer
 governing guide or spec. Write `none` in a slot that is genuinely empty rather than dropping the
 slot._
 
+**Installed primitives.** ORKESTREL_PACKAGES_WITH_SURFACE_POINTERS.
+
+_Name every installed `@orkestrel/*` package whose exports the unit's owned files may overlap —
+`@orkestrel/test` and `@orkestrel/contract` for any unit that owns a `tests/**` or `src/**` file —
+with the pointer the unit reads first: the package's guide `## Surface` section in the scaffold
+checkout, or its declaration under `node_modules`. State that a helper, guard, wait, recorder, or
+deferred whose job an installed export does is a defect, and give the audit's checker the
+export-name probe over the diff._
+
 **Host.** SHELL, WORKING_PATH, NETWORK_AND_SANDBOX_LIMITS.
 
 _Name the shell, the working path, and the sandbox, network, and approval limits the unit's commands

package/dist/host/claude/agents/orkestrel.md

@@ -46,7 +46,7 @@ so network-controlled descriptions never enter agent instruction context.
 | Package                 | Version  | Layer | Runtime dependencies                                                                                                                                                                                                                                                                                                       | Peer dependencies                                              |
 | ----------------------- | -------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
 | `@orkestrel/abort`      | `0.0.10` | L1    | `@orkestrel/contract` `^0.0.17`                                                                                                                                                                                                                                                                                            |                                                                |
-| `@orkestrel/agent`      | `0.0.21` | L5    | `@orkestrel/abort` `^0.0.10`, `@orkestrel/budget` `^0.0.10`, `@orkestrel/contract` `^0.0.17`, `@orkestrel/database` `^0.0.14`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/queue` `^0.0.13`, `@orkestrel/timeout` `^0.0.10`, `@orkestrel/tool` `^0.0.14`, `@orkestrel/workflow` `^0.0.18`, `@orkestrel/workspace` `^0.0.8` |                                                                |
+| `@orkestrel/agent`      | `0.0.22` | L5    | `@orkestrel/abort` `^0.0.10`, `@orkestrel/budget` `^0.0.10`, `@orkestrel/contract` `^0.0.17`, `@orkestrel/database` `^0.0.14`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/queue` `^0.0.13`, `@orkestrel/timeout` `^0.0.10`, `@orkestrel/tool` `^0.0.14`, `@orkestrel/workflow` `^0.0.18`, `@orkestrel/workspace` `^0.0.8` |                                                                |
 | `@orkestrel/brief`      | `0.0.8`  | L4    | `@orkestrel/reason` `^0.0.10`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/contract` `^0.0.17`, `@orkestrel/interpret` `^0.0.13`                                                                                                                                                                                           |                                                                |
 | `@orkestrel/browser`    | `0.0.16` | L3    | `@orkestrel/html` `^0.0.9`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/contract` `^0.0.17`, `@orkestrel/websocket` `^0.0.12`                                                                                                                                                                                              |                                                                |
 | `@orkestrel/budget`     | `0.0.10` | L1    | `@orkestrel/contract` `^0.0.17`                                                                                                                                                                                                                                                                                            |                                                                |
@@ -57,19 +57,19 @@ so network-controlled descriptions never enter agent instruction context.
 | `@orkestrel/database`   | `0.0.14` | L2    | `@orkestrel/contract` `^0.0.17`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/indexeddb` `^0.0.11`, `@orkestrel/sqlite` `^0.0.11`                                                                                                                                                                                           |                                                                |
 | `@orkestrel/emitter`    | `0.0.10` | L1    | `@orkestrel/contract` `^0.0.17`                                                                                                                                                                                                                                                                                            |                                                                |
 | `@orkestrel/form`       | `0.0.6`  | L2    | `@orkestrel/contract` `^0.0.17`, `@orkestrel/emitter` `^0.0.10`                                                                                                                                                                                                                                                            |                                                                |
-| `@orkestrel/guide`      | `0.0.18` | L3    | `@orkestrel/contract` `^0.0.17`, `@orkestrel/markdown` `^0.0.14`                                                                                                                                                                                                                                                           |                                                                |
+| `@orkestrel/guide`      | `0.0.19` | L3    | `@orkestrel/contract` `^0.0.17`, `@orkestrel/markdown` `^0.0.14`                                                                                                                                                                                                                                                           |                                                                |
 | `@orkestrel/html`       | `0.0.9`  | L1    | `@orkestrel/contract` `^0.0.17`                                                                                                                                                                                                                                                                                            |                                                                |
 | `@orkestrel/indexeddb`  | `0.0.11` | L1    | `@orkestrel/contract` `^0.0.17`                                                                                                                                                                                                                                                                                            |                                                                |
 | `@orkestrel/interpret`  | `0.0.13` | L3    | `@orkestrel/reason` `^0.0.10`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/contract` `^0.0.17`, `@orkestrel/template` `^0.0.7`                                                                                                                                                                                             |                                                                |
-| `@orkestrel/lsp`        | `0.0.7`  | L3    | `@orkestrel/emitter` `^0.0.10`, `@orkestrel/process` `^0.0.11`, `@orkestrel/contract` `^0.0.17`                                                                                                                                                                                                                            |                                                                |
+| `@orkestrel/lsp`        | `0.0.8`  | L3    | `@orkestrel/emitter` `^0.0.10`, `@orkestrel/process` `^0.0.12`, `@orkestrel/contract` `^0.0.17`                                                                                                                                                                                                                            |                                                                |
 | `@orkestrel/markdown`   | `0.0.14` | L2    | `@orkestrel/contract` `^0.0.17`, `@orkestrel/html` `^0.0.9`                                                                                                                                                                                                                                                                |                                                                |
-| `@orkestrel/mcp`        | `0.0.29` | L4    | `@orkestrel/sse` `^0.0.7`, `@orkestrel/tool` `^0.0.14`, `@orkestrel/codec` `^0.0.3`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/process` `^0.0.11`, `@orkestrel/contract` `^0.0.17`, `@orkestrel/websocket` `^0.0.12`                                                                                                     | `@orkestrel/router` `^0.0.14`, `@orkestrel/server` `^0.0.19`   |
+| `@orkestrel/mcp`        | `0.0.30` | L4    | `@orkestrel/sse` `^0.0.7`, `@orkestrel/tool` `^0.0.14`, `@orkestrel/codec` `^0.0.3`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/process` `^0.0.12`, `@orkestrel/contract` `^0.0.17`, `@orkestrel/websocket` `^0.0.12`                                                                                                     | `@orkestrel/router` `^0.0.14`, `@orkestrel/server` `^0.0.19`   |
 | `@orkestrel/middleware` | `0.0.20` | L4    | `@orkestrel/abort` `^0.0.10`, `@orkestrel/budget` `^0.0.10`, `@orkestrel/contract` `^0.0.17`, `@orkestrel/timeout` `^0.0.10`                                                                                                                                                                                               | `@orkestrel/database` `^0.0.14`, `@orkestrel/server` `^0.0.19` |
 | `@orkestrel/msg`        | `0.0.10` | L0    |                                                                                                                                                                                                                                                                                                                            |                                                                |
 | `@orkestrel/ndjson`     | `0.0.10` | L1    | `@orkestrel/contract` `^0.0.17`                                                                                                                                                                                                                                                                                            |                                                                |
-| `@orkestrel/ollama`     | `0.0.15` | L6    | `@orkestrel/agent` `^0.0.21`, `@orkestrel/budget` `^0.0.10`, `@orkestrel/contract` `^0.0.17`, `@orkestrel/ndjson` `^0.0.10`, `@orkestrel/timeout` `^0.0.10`, `@orkestrel/tool` `^0.0.14`                                                                                                                                   |                                                                |
+| `@orkestrel/ollama`     | `0.0.16` | L6    | `@orkestrel/tool` `^0.0.14`, `@orkestrel/agent` `^0.0.22`, `@orkestrel/budget` `^0.0.10`, `@orkestrel/ndjson` `^0.0.10`, `@orkestrel/contract` `^0.0.17`                                                                                                                                                                   |                                                                |
 | `@orkestrel/pool`       | `0.0.11` | L2    | `@orkestrel/emitter` `^0.0.10`                                                                                                                                                                                                                                                                                             |                                                                |
-| `@orkestrel/probe`      | `0.0.13` | L5    | `@orkestrel/contract` `^0.0.17`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/lsp` `^0.0.7`, `@orkestrel/mcp` `^0.0.29`, `@orkestrel/queue` `^0.0.13`, `@orkestrel/timeout` `^0.0.10`, `@orkestrel/tool` `^0.0.14`                                                                                                          | `oxlint` `^1.82.0`, `typescript` `^6.0.3`, `vitest` `^4.1.11`  |
+| `@orkestrel/probe`      | `0.0.14` | L5    | `@orkestrel/contract` `^0.0.17`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/lsp` `^0.0.8`, `@orkestrel/mcp` `^0.0.30`, `@orkestrel/queue` `^0.0.13`, `@orkestrel/timeout` `^0.0.10`, `@orkestrel/tool` `^0.0.14`                                                                                                          | `oxlint` `^1.82.0`, `typescript` `^6.0.3`, `vitest` `^4.1.11`  |
 | `@orkestrel/process`    | `0.0.12` | L2    | `@orkestrel/contract` `^0.0.17`, `@orkestrel/emitter` `^0.0.10`                                                                                                                                                                                                                                                            |                                                                |
 | `@orkestrel/program`    | `0.0.13` | L4    | `@orkestrel/contract` `^0.0.17`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/qualifier` `^0.0.14`, `@orkestrel/rater` `^0.0.14`, `@orkestrel/reason` `^0.0.10`                                                                                                                                                             |                                                                |
 | `@orkestrel/qualifier`  | `0.0.14` | L3    | `@orkestrel/contract` `^0.0.17`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/reason` `^0.0.10`                                                                                                                                                                                                                             |                                                                |
@@ -78,8 +78,8 @@ so network-controlled descriptions never enter agent instruction context.
 | `@orkestrel/reason`     | `0.0.10` | L2    | `@orkestrel/contract` `^0.0.17`, `@orkestrel/emitter` `^0.0.10`                                                                                                                                                                                                                                                            |                                                                |
 | `@orkestrel/relation`   | `0.0.12` | L3    | `@orkestrel/contract` `^0.0.17`, `@orkestrel/database` `^0.0.14`, `@orkestrel/emitter` `^0.0.10`                                                                                                                                                                                                                           |                                                                |
 | `@orkestrel/router`     | `0.0.14` | L2    | `@orkestrel/abort` `^0.0.10`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/contract` `^0.0.17`                                                                                                                                                                                                                              |                                                                |
-| `@orkestrel/scaffold`   | `0.0.65` | L3    | `@orkestrel/console` `^0.0.13`, `@orkestrel/contract` `^0.0.17`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/markdown` `^0.0.14`, `@orkestrel/process` `^0.0.11`, `@orkestrel/template` `^0.0.7`                                                                                                                           |                                                                |
-| `@orkestrel/sea`        | `0.0.15` | L3    | `@orkestrel/contract` `^0.0.17`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/process` `^0.0.11`                                                                                                                                                                                                                            |                                                                |
+| `@orkestrel/scaffold`   | `0.0.67` | L3    | `@orkestrel/console` `^0.0.13`, `@orkestrel/contract` `^0.0.17`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/markdown` `^0.0.14`, `@orkestrel/process` `^0.0.12`, `@orkestrel/template` `^0.0.7`                                                                                                                           |                                                                |
+| `@orkestrel/sea`        | `0.0.16` | L3    | `@orkestrel/contract` `^0.0.17`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/process` `^0.0.12`                                                                                                                                                                                                                            |                                                                |
 | `@orkestrel/server`     | `0.0.19` | L3    | `@orkestrel/abort` `^0.0.10`, `@orkestrel/codec` `^0.0.3`, `@orkestrel/router` `^0.0.14`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/timeout` `^0.0.10`, `@orkestrel/contract` `^0.0.17`                                                                                                                                  |                                                                |
 | `@orkestrel/sqlite`     | `0.0.11` | L1    | `@orkestrel/contract` `^0.0.17`                                                                                                                                                                                                                                                                                            |                                                                |
 | `@orkestrel/sse`        | `0.0.7`  | L0    |                                                                                                                                                                                                                                                                                                                            |                                                                |

package/dist/host/claude/rules/names.md

@@ -121,6 +121,21 @@ The root design laws in `AGENTS.md` — one term per concept, boolean behavior s
 - Outside a declared wire body, a mirrored name never uses `kind` or `type` as a member name, and never uses a word § Rejected naming lists. A Compound File Binary (CFB) directory entry's object-type byte takes a named discriminant.
 - A declared wire body — a type whose members transliterate an external wire format field for field — keeps the external field names, `type` and `kind` included, and its TSDoc names the format it transliterates. The package's own domain type carries neither word, and the package owns the projection between the wire body and the domain type.
 
+## Fleet name ownership
+
+Give every bare exported name one owning package across the `@orkestrel` fleet. A bare name is the identifier alone, case included: the same identifier in another environment, or on another kind of declaration, is the same name, and the same word in another case is a different name.
+
+Check a public name against the fleet's published guides before adding it. The `surface` policy rule reports a name another package's guide already claims, and `.claude/rules/workspace.md` § Policy instruments fixes the instrument that reports it.
+
+The rule grandfathers a source name the target's own hosted guide claims, because that guide is the target's own claim to it. It grandfathers no root `tests/setup*.ts` export, so clear a colliding setup export before adopting the scaffold release that carries the rule. A vendored `tests/setup*.ts` module a scaffold release stages sits outside the inspected population.
+
+Resolve a reported collision with these rules, in order.
+
+1. **Reuse before renaming.** Where the colliding declarations carry the same contract, delete this one and import the owner's export. Declare the dependency that import needs, or stop and report that the dependency is not authorized.
+2. **The subject keeps the name.** Where the contracts differ, leave the name with the package whose domain the name describes, and rename the other declaration for the thing it is. Refuse a rename that makes the renamed declaration vaguer; name its own contract instead.
+3. **Qualify rather than extract.** Extract a shared package only where a proof shows the colliding declarations interchangeable and the dependency change is authorized. Otherwise qualify the name in place for the domain it serves, and route the extraction through a design round rather than renaming by fiat.
+4. **Close the collision in the code.** Change a declaration; the rule reads no allowlist a target can add a name to, and it carries no suppression. The committed `host.json` inventory in the `@orkestrel/scaffold` checkout records the collisions that predate this rule, and a release build refuses a staged collision that record does not already hold. Shrink that record by closing a collision, and never widen it to admit one. Never suppress the violation, and never edit a vendored policy instrument to clear it.
+
 ## Acronyms
 
 Keep canonical case:

package/dist/host/claude/rules/tests.md

@@ -172,7 +172,7 @@ A test that spawns a process, packs, installs, or drives a real build is a proof
 
 Test helpers are shared infrastructure, not local test-file clutter.
 
-`@orkestrel/test` owns the helpers every workspace repeats: the call recorder, the real delay, the JSON and async collectors, and the owned scratch directory. Import them from `@orkestrel/test`, and its Node-only helpers from `@orkestrel/test/server`. Write a helper of your own only where the package exports none for the job. The following shapes are the contract a workspace codes against, not source to copy.
+`@orkestrel/test` owns the helpers every workspace repeats: the call recorder, the real delay, the JSON and async collectors, and the owned scratch directory. Import them from `@orkestrel/test`, and its Node-only helpers from `@orkestrel/test/server`. Before declaring a helper in a `tests/setup*.ts` module, read the installed surface — `guides/test.md` § Surface in the scaffold checkout, or the package's own declaration under `node_modules` — and declare only what no export does. A setup-module export whose name or job matches an installed export is a defect, whichever file declared it first. The following shapes are the contract a workspace codes against, not source to copy.
 
 - For the vendored test set (`tests/setupPolicy.ts`, `tests/policy.test.ts`, and
   `tests/config.test.ts`), keep shared helpers within that set instead of importing them from
@@ -219,9 +219,38 @@ function waitForDelay(ms?: number): Promise<void>
 Use it to yield, never to wait for something another process produces. A fixed delay chosen to
 outlast a child's startup is a race whose loss looks like a product defect: the test measures
 interpreter bootstrap rather than the behaviour it names, and it fails on a loaded host and passes on
-an idle one. Wait until a named condition holds instead, polling with `waitForDelay` inside a budget
-measured by `performance.now()`, and fail with the condition's own description when the budget
-expires.
+an idle one. Wait for a named condition, an event, or an abort with the helpers under
+§ Condition instead.
+
+### Condition
+
+Import `waitForCondition`, `waitForEvent`, `waitForAbort`, and `retryUntil` from
+`@orkestrel/test`. A polling loop, a deadline read, or a deferred that observes an abort or an
+event in a test or a setup module is a defect: `waitForCondition` owns the poll, `waitForEvent`
+the deferred on an event, and `waitForAbort` the deferred on a signal. A guide fence transcribed
+byte for byte into `tests/guides.test.ts` is the consumer's code and stays as the guide shows it.
+Each timed wait takes a `description` the timeout error names and `WaitOptions` (`budget`,
+`interval`, `signal`):
+
+```ts
+function waitForCondition(
+	description: string,
+	condition: () => boolean | Promise<boolean>,
+	options?: WaitOptions,
+): Promise<void>
+function waitForEvent<TArgs extends readonly unknown[]>(
+	subscribe: EventSubscriber<TArgs>,
+	description: string,
+	options?: WaitOptions,
+): Promise<TArgs>
+function waitForAbort(signal: AbortSignal): Promise<void>
+function retryUntil<T>(
+	description: string,
+	produce: () => T | Promise<T>,
+	satisfied: (value: T) => boolean,
+	options?: RetryOptions,
+): Promise<T>
+```
 
 ### Scratch
 

package/dist/host/claude/rules/workspace.md

@@ -264,8 +264,20 @@ Policy instruments:
   a named module-scope `report{Noun}` function. Never write rule logic inline in the table. That
   arrow is the sanctioned exception to the in-body function-expression limits in
   `.claude/rules/architecture.md` for exactly that table.
-- Name no individual rule id here. This section fixes the instruments and how work is assigned
-  between them; each rule's substance stays with the law it enforces.
+- Name an individual rule id here only where the rule reads its evidence from outside the workspace
+  its instrument runs in. This section fixes the instruments and how work is assigned between them;
+  each rule's substance stays with the law it enforces.
+- `surface` is that rule, and the sweep owns it. It reads the fleet's published guides — a target
+  reads `node_modules/@orkestrel/scaffold/dist/host/guides/`, and a scaffold checkout reads its own
+  `guides/` — and compares every bare name their `## Surface` tables claim against the target's live
+  barrel exports and its own root `tests/setup*.ts` exports. `.claude/rules/names.md` § Fleet name
+  ownership defines the bare name that comparison matches and decides which declaration gives a
+  claimed name up.
+- Keep every barrel statement in the form `.claude/rules/architecture.md` § Barrel exports fixes.
+  The sweep refuses a barrel population it cannot read whole and reports that refusal as a `surface`
+  violation rather than passing over the statements it did read. A catalog row with no hosted guide,
+  and a missing hosted guide root, refuse the same way.
+- Change the code when an instrument reports a violation.
 
 ## Text integrity
 

package/dist/host/dotfiles/prettierignore

@@ -12,3 +12,6 @@ demo/showcase.html
 
 # Fetched-bytes mirrors keep their upstream bytes and stay out of the formatter.
 tests/mirrors/
+
+# The vendored host inventory: `npm run build` regenerates it (`stageInventory`), so its bytes are the generator's, not the formatter's.
+host.json

package/dist/host/guides/README.md

@@ -0,0 +1,65 @@
+# Guides
+
+An index into this repository's guides, by concept and by directory, following the
+documentation contract in [`.claude/rules/documentation.md`](../.claude/rules/documentation.md).
+
+## By concept
+
+| Concept  | Spec                         | Source                                                   | Tests                                                                            |
+| -------- | ---------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| Scaffold | [`scaffold.md`](scaffold.md) | [`src/core`](../src/core), [`src/server`](../src/server) | [`tests/src/core`](../tests/src/core), [`tests/src/server`](../tests/src/server) |
+
+`scaffold.md` documents the union of the package's library faces: the pure core
+([`src/core`](../src/core)) and the server face ([`src/server`](../src/server)). The server face
+carries the `Materializer` that writes a target, the `Upstream` reader that fetches releases and
+guide mirrors, and the `WriteTransaction` those writes stage through. The `scaffold` executable
+([`src/bin`](../src/bin)) publishes no barrel, so it is documented in prose and sits outside the
+surface bijection.
+
+That bijection is the row's contract, and [`tests/guides.test.ts`](../tests/guides.test.ts)
+enforces it: every symbol the guide documents exists in the core barrel or the server barrel, and
+every symbol either barrel exports is documented.
+
+## By directory
+
+| Directory    | Guide                        |
+| ------------ | ---------------------------- |
+| `src/core`   | [`scaffold.md`](scaffold.md) |
+| `src/server` | [`scaffold.md`](scaffold.md) |
+| `src/bin`    | [`scaffold.md`](scaffold.md) |
+
+## Line reference
+
+This repository vendors a byte-identical guide mirror for **every published `@orkestrel/*`
+package**, not only its own dependencies. Scaffold is the line's blueprint compiler: `new` seeds a
+workspace with the mirrors named by `SEED_GUIDE_PATHS`. The `catalog` command refreshes the
+mirrors — the declared set by default, or the complete published line under `--all`. Each mirror is
+fetched from its own repository's `main` at `guides/<name>.md`.
+
+Every file in this directory ships inside the published package as well, at
+`dist/host/guides/<name>.md`, so an installed `@orkestrel/scaffold` carries the whole line as
+readable data. `catalog` writes that staged copy into a target whose mirror is absent and whose
+upstream read returned no bytes, and the `surface` policy rule reads the same set to decide which
+package owns an exported name.
+
+These subsets carry extra weight:
+
+- **Runtime dependencies** — `@orkestrel/console` ([`console.md`](console.md)),
+  `@orkestrel/contract` ([`contract.md`](contract.md)), `@orkestrel/emitter`
+  ([`emitter.md`](emitter.md)), `@orkestrel/markdown` ([`markdown.md`](markdown.md)),
+  `@orkestrel/process` ([`process.md`](process.md)), and `@orkestrel/template`
+  ([`template.md`](template.md)). The library faces reach contract, emitter, markdown, and
+  template; the `scaffold` executable reaches console, contract, markdown, and process.
+- **Development** — `@orkestrel/guide` ([`guide.md`](guide.md)) backs this repository's
+  guides-parity suite, [`tests/guides.test.ts`](../tests/guides.test.ts); the
+  `readSurfaceCollisions` helper in the server face, which loads it at call time; and the `surface`
+  rule in [`tests/setupPolicy.ts`](../tests/setupPolicy.ts). A consumer calling
+  `readSurfaceCollisions` supplies the package itself, because scaffold declares it for development
+  alone.
+
+Every mirror documents **that package's** surface, not anything sourced in this repository. A mirror
+that drifts from its upstream `main` is a defect: refresh it rather than editing it here.
+
+## See also
+
+- [`AGENTS.md`](../AGENTS.md) and [`.claude/rules/documentation.md`](../.claude/rules/documentation.md) — the repository rules and documentation contract.

package/dist/host/guides/abort.md

@@ -0,0 +1,169 @@
+# Abort
+
+> The cancellation primitive: a thin, traceable wrapper over a native `AbortController` that
+> carries a trace `id`, exposes a standard `AbortSignal`, and links to a parent signal so one
+> cancellation cascades through a tree of handles.
+
+The native signal is the complete observation contract: hand it to any cancellable API, inspect
+`aborted` and `reason`, or subscribe to its standard `abort` event. Where a parent was given, that
+signal fires when either the handle's own `abort()` is called or the parent aborts, with no
+listener bookkeeping to write. Async layers bound their work against a `signal`. Deliberately
+thin. It does **not** re-implement cancellation machinery — the native `AbortController` is the
+engine; `Abort` only adds a traceable `id` and parent-linking on top. It does **not** wrap the
+signal in a bespoke interface, so it stays interoperable with `fetch`, streams, and every Web API
+that already speaks `AbortSignal`. Source: [`src/core`](../src/core). Surfaced through the
+`@src/core` barrel.
+
+## Surface
+
+Create a cancellation handle, hand its `signal` to cancellable work, and `abort()` to cancel:
+
+```ts
+import { createAbort } from '@orkestrel/abort'
+
+const abort = createAbort({ id: 'fetch-user' })
+const response = await fetch(url, { signal: abort.signal })
+abort.abort() // cancels the in-flight fetch through the native signal; `aborted` flips true
+```
+
+The `signal` is a plain `AbortSignal`, so it drops into anything that takes one. Call `abort()` to cancel and `abort(reason)` to attach a value the cancelled work can read off `signal.reason`. Aborting is idempotent — the first call wins, and a second is a safe no-op. Pass a parent `signal` to link cancellation: the child's `signal` then fires when the parent aborts, so one cancellation cascades to every linked handle (through `AbortSignal.any`, no listener bookkeeping). Pass `id` to label a handle for tracing, or let it default to a random UUID.
+
+Construction is a strict JavaScript boundary. `validateAbortOptions` normalizes omitted options to a fresh empty object; otherwise it requires a plain record, reads `id` and `signal` exactly once inside a contained boundary, and returns a fresh copy omitting absent keys. A provided `id` must be a string and a provided parent `signal` must be native. Invalid values fail immediately with a coded `ContractError`: malformed or unreadable options use `bound`, a nonstring id uses `literal`, and a nonnative option signal uses `placement`, with exact `options`, `options.id`, or `options.signal` context, limits, safe previews, and the originating cause for unreadable records. Direct `linkSignal` calls independently validate `own` and `parent` as native signals with `placement` context. An `undefined` `id` still generates a UUID, while an empty string remains a valid explicit id.
+
+### Factories
+
+| API           | Kind     | Summary                                                                                                                                                                                                                                       |
+| ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `createAbort` | function | Creates a cancellation handle from validated options and returns it as an `AbortInterface` — a resolved trace `id` and a `signal` already linked to any parent given, so a caller holds the published contract rather than the `Abort` class. |
+
+### Helpers
+
+| API                    | Kind     | Summary                                                                                                                     |
+| ---------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `validateAbortOptions` | function | Validates once-read abort construction options and returns a fresh normalized copy omitting absent optional keys.           |
+| `linkSignal`           | function | Links an own `AbortSignal` to an optional parent signal, returning `AbortSignal.any([own, parent])` when a parent is given. |
+
+### Validators
+
+In a guard table a `Shape` cell holds the type the guard narrows to.
+
+| API             | Kind     | Shape         | Summary                                                                                                                       |
+| --------------- | -------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `isAbortSignal` | function | `AbortSignal` | Determines whether a value is a native `AbortSignal`, staying total for structural spoofs and for hostile or revoked proxies. |
+
+### Classes
+
+| API     | Kind  | Summary                                                                                                                                                                                                |
+| ------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `Abort` | class | Implements `AbortInterface` over a private `AbortController` the instance owns, resolving the trace `id` at construction and exposing either that controller's own `signal` or one linked to a parent. |
+
+### Types
+
+A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`.
+
+| Type             | Kind      | Shape                                | Summary                                                                                                                                                                                                |
+| ---------------- | --------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `AbortOptions`   | interface | `{ id?, signal? }`                   | Represents the options for `createAbort` and `Abort` construction.                                                                                                                                     |
+| `AbortInterface` | interface | `{ id, signal, aborted } plus abort` | Represents the cancellation contract a consumer holds — a traceable `id`, the exposed `AbortSignal`, an `aborted` reading of it, and an idempotent `abort` that cancels the work bound to that signal. |
+
+The `id`, `signal`, and `aborted` members of `AbortInterface` are `readonly` data members (Surface rows, earlier) — its call-signature method is documented under [Methods](#methods).
+
+## Methods
+
+The public methods of `AbortInterface` — every call-signature member listed (its `readonly` data members `id` / `signal` / `aborted` stay Surface rows). `Abort` implements the interface exactly, so this doubles as the class's instance-method surface (see `.claude/rules/documentation.md` § Parity).
+
+#### `AbortInterface`
+
+`abort` is the lifecycle verb `.claude/rules/names.md` § Fixed lifecycle vocabulary fixes as "Cancel with signal propagation" — it aborts the underlying controller, flipping `aborted` and firing `signal`.
+
+| Method  | Returns | Summary                                                                                                                                                     |
+| ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `abort` | `void`  | Aborts the underlying controller, flipping `aborted` and firing `signal`. Aborting is idempotent — the first reason sticks and every later call is a no-op. |
+
+## Contract
+
+These invariants hold across `src/core` ↔ `abort.md`:
+
+1. **DOC ↔ SOURCE bijection.** Every `function` / `class` / `interface` / `type` row in the `## Surface` tables is a real export of the aborts module, and every export appears as a Surface row — exhaustive, both directions (see `.claude/rules/documentation.md` § Parity).
+2. **Native wrapper.** `Abort` owns a private `AbortController`; `abort(reason?)` delegates to `controller.abort(reason)`, and `aborted` reads the exposed `signal.aborted`. No re-implemented cancellation machinery.
+3. **Parent linking through `AbortSignal.any`.** With a parent `signal`, the exposed `signal` is `AbortSignal.any([own, parent])`, so it fires on EITHER the own `abort()` or the parent aborting — and the own `abort()` does NOT abort the parent. Without a parent, `signal` is the own controller's signal directly.
+4. **Reason propagates.** `abort(reason)` forwards the reason to the controller, so `signal.reason` is the value passed in — when the own `abort()` is what fired the signal. Any DEFINED reason is preserved by identity, including falsy ones (`null`, `0`, `''`, `false`, `NaN`) — never `if (reason)`-gated. When the reason is `undefined` (or omitted), the host substitutes a default `AbortError` `DOMException`, so cancelled work always has a reason to inspect rather than `undefined`. On a linked handle whose PARENT aborted first, `signal.reason` is the parent's reason instead (correct `AbortSignal.any` semantics: the signal carries the reason of whichever source fired it).
+5. **Idempotent — first reason sticks.** A handle aborts at most once: a second (or third) `abort(reason2)` neither re-fires `signal` nor overwrites `reason`, even when the first reason was a falsy `0` / `''`. A handle linked to a parent that has ALREADY aborted at construction is born aborted (`aborted === true`, carrying the parent's reason) — its own later `abort()` is then a safe no-op.
+6. **Traceable identity.** `id` is a stable string for the handle's lifetime — caller-supplied through `options.id`, or a `crypto.randomUUID()` default that is unique across instances (verified across a large batch).
+7. **Native observation contract.** The exposed `AbortSignal` is the complete observation surface: consumers read `aborted` / `reason` and subscribe to the standard `abort` event. The package adds no parallel event system.
+8. **Strict JavaScript boundaries.** `validateAbortOptions` normalizes omission to a fresh object; otherwise it requires a plain readable record, reads each declared option exactly once, validates a defined string `id` and native parent `signal`, and returns a fresh normalized copy without absent keys before controller allocation or link composition. Invalid options use `bound`, invalid ids use `literal`, and invalid option signals use `placement`, with exact paths, limits, safe previews, and preserved causes for unreadable records. `linkSignal` separately guards its direct `own` and `parent` inputs with `placement` errors and native-signal limits. Structural spoofs and hostile or revoked proxies are rejected without leaking native errors.
+9. **DOC ↔ SOURCE method bijection.** The `## Methods` table lists exactly `AbortInterface`'s public methods — exhaustive, both directions — and `Abort` exposes the same public methods, no more (see `.claude/rules/documentation.md` § Parity).
+
+## Patterns
+
+### Create and abort
+
+Create a handle, hand its `signal` to cancellable work, and call `abort(reason)` to cancel it:
+
+```ts
+import { createAbort } from '@orkestrel/abort'
+
+const abort = createAbort()
+const stream = openStream({ signal: abort.signal })
+// later, to cancel:
+abort.abort('user navigated away') // signal.reason carries the value
+```
+
+### Link to a parent (cascading cancellation)
+
+A child handle linked to a parent `signal` fires when the parent aborts — one cancellation cascades to every linked handle, without manual listener wiring.
+
+```ts
+import { createAbort } from '@orkestrel/abort'
+
+const parent = createAbort({ id: 'request' })
+const child = createAbort({ id: 'sub-task', signal: parent.signal })
+
+parent.abort() // child.aborted is now true; child.signal has fired
+// the child can still be aborted on its own without touching the parent
+```
+
+### Race work against the signal
+
+The cleanest bound is to thread `signal` straight into work that already accepts one — then a single `abort()` cancels the whole chain natively, no race to write:
+
+```ts
+import { createAbort } from '@orkestrel/abort'
+
+const abort = createAbort()
+const rows = await query(sql, { signal: abort.signal }) // cancels at the source on abort
+```
+
+When the work does NOT take a signal, race it against the abort. The native `signal.reason` is what `abort(reason)` stored (or the default `AbortError`), so reject with it directly:
+
+```ts
+import { createAbort } from '@orkestrel/abort'
+
+async function run<T>(work: Promise<T>, abort = createAbort()): Promise<T> {
+	const cancelled = new Promise<never>((_, reject) =>
+		abort.signal.addEventListener('abort', () => reject(abort.signal.reason), { once: true }),
+	)
+	return Promise.race([work, cancelled])
+}
+```
+
+### Practices
+
+- **Hand off the `signal`, keep the handle** — pass `abort.signal` into cancellable APIs (`fetch`, a stream, a worker); keep the `Abort` to call `abort()`. Prefer threading the signal into work that accepts one over racing it yourself.
+- **Link, don't re-wire** — pass a parent `signal` to cascade cancellation; `AbortSignal.any` does the bookkeeping, so never hand-roll `addEventListener` chains between handles.
+- **Carry a reason** — pass a value to `abort(reason)`; it surfaces on `signal.reason` for the cancelled work to inspect. Any defined value is kept as-is (even a falsy `0` / `''`); only `undefined` is replaced with a default `AbortError`.
+- **Label for tracing** — set `id` on long-lived or correlated handles; let it default to a UUID otherwise.
+- **Observe the native signal** — inspect `aborted` / `reason` or subscribe to the standard `abort` event; no parallel event abstraction is needed.
+
+## Tests
+
+- [`tests/guides.test.ts`](../tests/guides.test.ts) — the `## Surface` ↔ `src/core` bijection (value + type exports), the `AbortInterface` ↔ `Abort` method bijection, and the equality gate: every `Summary` cell against its declaration's description paragraph, the titled `Create and abort` fence against the `@example` block of that title (pinned so the titled pair cannot be retired silently), and the README pitch against this guide's tagline. It also runs the flagship fences and asserts the values their comments claim.
+- [`tests/src/core/Abort.test.ts`](../tests/src/core/Abort.test.ts) — `abort()` flips `aborted` and fires `signal`, `abort(reason)` propagates the reason, a second/third `abort(reason2)` is an idempotent no-op (`signal.reason` stays the first reason), a fresh handle is not aborted, parent linking (the signal fires on the parent's abort and on its own; a parent that aborts first propagates the parent's reason), and `id` is honored / stable / unique (across a 1,000-instance batch). Edge cases: every reason type (`undefined`/omitted → a default `AbortError` `DOMException`; string / object / the falsy-but-defined `null` / `0` / `''` / `false` / `NaN` preserved by identity; first falsy reason still sticks), a parent already aborted at construction (born aborted, carrying the parent's reason, own `abort()` then inert), chained Aborts (an `Abort` parented to another's `signal`, 2–3 levels: a root abort fans down with its reason, a mid/leaf abort never flows up), `new Abort` ↔ `createAbort` parity, and proportionate public-constructor boundary integration.
+- [`tests/src/core/factories.test.ts`](../tests/src/core/factories.test.ts) — `createAbort` returns a working `AbortInterface` and honors `id` / a parent `signal`.
+- [`tests/src/core/helpers.test.ts`](../tests/src/core/helpers.test.ts) — `validateAbortOptions` fresh normalization, optional-key omission, exactly-once reads, hostile getter containment, and exact taxonomy/context; plus `linkSignal` own/parent composition and exact direct-call placement errors.
+- [`tests/src/core/validators.test.ts`](../tests/src/core/validators.test.ts) — `isAbortSignal` accepts a native signal and remains total for structural spoofs and revoked proxies.
+
+## See also
+
+- [`AGENTS.md`](../AGENTS.md) — the pointer to the `@orkestrel/scaffold` coding contract, whose § Fixed lifecycle vocabulary, § Entity-scoped names, and § Parity rules govern this guide.
+- [`README.md`](README.md) — the guides index.