pi-mono/packages/chord/docs/next/slice-8.md

# Slice 8: registries and `host.root` (spec)

Status: **built** (2026-10-28; build review and two fix rounds by the same four reviewers,
`/tmp/s8-build-review-*.md`, `/tmp/s8-build-rereview-*.md`). Before: ready to build (2026-10-27; D1-D3, the registry failures and S1-S3 decided by the owner; two spec reviews,
`/tmp/s8-review{,2}-{astra,fable,opus,sol}.md`, found no remaining blocker; S3 refined after the second: with no value
after `load`, a reader fails at once, as `self.get` of a type not served here)

8 builds the extension point between plugins (registries), in-process values that change (`self.writable`), wake
signals for failed objects (`retryOn`), and the call scope for code outside objects (`host.root`). The harness object
is p3's base code; Chord shows it only in an example.

## What an app can do after this slice

```ts
// the defining plugin (e.g. http): the token, exported for other plugins
export const Http = defineRegistry<HttpContribution, Router>("chord.http", { version: 2 });   // shared: identity only
export default defineFacet((host, self) => {
  host.serve(Http, {                                              // the one provider (Q8), as for object types
    compose: (table, { report }) => buildRouter(table, report),   // pure; always a value; conflicts reported
    accepts: { 1: { contribution: (old: HttpContributionV1) => upgrade(old), value: (router) => routerV1(router) } },
  });
  host.serve(HttpServer, (_, self) => {
    const router = self.registry(Http);                           // a NativeWatchable of the composed value
    self.on(router, ({ value }, ctx) => …);
    return { … };
  });
});

// any plugin: a facet or a host-lifetime object contributes one value per registry
export default defineFacet((host, self) => {
  self.contribute(Http, { routes: { "GET /notes/export": exportNotes } });
});
host.serve(McpStore, (_, self) => {                               // local, empty params (R21)
  const ext = self.writable(mcpExtension([]));                    // an in-process value that changes
  self.contribute(HarnessExtensions, ext);
  self.on(mcp.tools, ({ value: tools }) => ext.set(mcpExtension(tools)));
  self.retryOn(self.registry(HarnessModels));                     // a model contribution wakes a failed attempt
  return {};
});

// code outside objects (a Durable tool, a CLI): a call scope
await host.root(async (ctx) => (await ctx.get(Notes, { session })).add(note, ctx), context);
```

## 1. Registries

- **Token and provider (D1, owner, 2026-10-27):** the token `defineRegistry<C, V>(name, { version })` is shared, as a
  contract: its name (as types, `[a-z0-9@/._~-]`), the contribution type `C`, the composed value type `V`, and the
  version the bundling plugin was built against. The defining plugin's facet provides it with `host.serve(R, {
  compose, accepts? })`, as it serves object types (adapters with the provider, never in the shared token, as
  `checkAccepts` for contracts); a second serve on a host is refused; a reload replaces it (slice 7).

- **Contributors** (R21): facets (by plugin name) and host-lifetime objects (`local`, empty params: by plugin name and
  type), at most one value per registry each; `self.contribute(R, value | Watchable | NativeWatchable)` in a facet setup
  or such an object's factory (a type error elsewhere; a declaration error at runtime). A facet's contribution is in the
  table while its plugin is loaded; an object's from `live` until it ends, fails or restarts.
- **The table:** an immutable list of `{ contributor, plugin, value }`, sorted by plugin name, then type (never load
  order); a contribution carries its token's version: an older one is adapted once with the declaration's `accepts`
  when the table is built, an older one without an adapter or a newer one is left out and reported (`HostError`
  `contribution_refused { registry, plugin, version }`).
- **Contributions:** a plain value, or a Chord watchable (a `writable`, a derive, a document member; another
  registry's value too, a cycle of registries reading each other refused when the second one serves or contributes (superseded by audit A2: caught at the first composition by the runtime guard, reported `contribution_failed`)), followed as a dependent of the table (its change recomposes), recognised by Chord's own mark; anything
  else is a plain value, whatever methods it has (a harness, a conversation handle or a runtime is contributed as a plain
  value, not followed; build review 2026-10-27, replacing "a foreign watchable is refused"). The table's entry is `{ plugin, type?, version, value }` (`type` for
  an object contributor; served types carry their plugin's name).
- **`compose(table, { report })`:** pure, lazy as a derive: the registry's value is marked when its table changes (a
  contributor goes live or ends, a watchable contribution changes) and composed when read or, while watched, in the
  owner's flush (W4: never by another owner's adoption itself; the flush after a commit step is where it runs). The first
  composition happens at the serve: the facets' setups of one `load` serve and contribute, then every served registry
  composes once in one batch at the end of the setups (an empty table composes too), so a served registry always has
  a value before any object activates. `report(conflict)` goes to `onError` as `registry_conflict { registry, message,
  plugins }`, once per conflict episode.
- **Failures (owner, 2026-10-27):** contributions never fail the registry. A contribution that is a watchable and fails
  is left out of the table and reported (`contribution_failed { registry, plugin, error }`), the table recomposes without
  it, and it is back once it heals. A `compose` that throws (the owner's bug) is reported (`registry_failed { registry,
  error }`), the composed value's watches get a `failed` call, and `.value` keeps the last good composition (an extension
  point stays available; derives keep their own rule, `.value` throwing while failed); the next good composition
  replaces it. Before any good composition `.value` throws the error.
- **Without a provider** (the defining plugin is not loaded): the registry has no value; contributions wait in the
  table; its serve composes it.
- **Reading is a dependency (S3, owner, 2026-10-27: "isn't self.registry meant to wait like self.get?"):**
  `self.registry(R)` in a factory declares the registry as a dependency of the attempt, as `self.get`: activation waits
  until it has a value; once `load`'s setups ran, a registry with no value cannot get one before a reload (a provider
  comes only with a plugin), so a reader then fails at once `transient` with `unavailable/undeclared` as the
  dependency's cause (as `self.get` of a type not served here fails at once, and the start barrier waits for no
  contribution) and is retried the moment the registry gets its first value (R18); a first `compose` that throws fails
  its readers the same way. It returns a `RegistryValue<V>` (a native source: a derive source, an `on` source, a `retryOn` source; never a
  state member); methods and routines read `.value` at use. Once the object is live, a later failure of the registry
  (a throwing `compose`) changes nothing for it: `.value` keeps the last good composition. Code outside objects:
  `await host.registry(R, ctx)` waits the same way.
- **Older readers (S2, owner, 2026-10-27):** a reader whose bundled token has an older version than the provider's gets
  the composed value mapped back with `accepts[old].value` (computed once per composition and version, while such a
  reader exists); without that mapping, or for a reader newer than the provider, its dependency fails
  `contract_mismatch` (reported). `accepts: { [old]: { contribution?: (old) => current, value?: (current) => old } }`.
  Adapters are the provider's code, guarded as `compose`: a `contribution` adapter that throws leaves that contribution
  out (reported `contribution_failed`); a `value` adapter that throws fails only that version's value, by the rules of a
  throwing `compose` (its readers keep the last good mapped value; before any, a reader of that version waiting at
  activation fails `transient`, retried when a mapped value arrives); current readers are never affected.
- **Helpers:** `keyed(table, entriesOf, report)` (a map, a duplicate key reported through `report`, the first by plugin
  name wins) and
  `ordered(table, itemsOf, orderOf?)`.
- **Use sites guard contributions** (Q8): Chord's helpers keep each entry's plugin name; the guide shows catching a
  contribution's throws and rejections, reporting the plugin, and continuing.
- **Registries carry natives** (design §17): a contribution may be any in-process value; an entry lives exactly as long
  as its contributor.

## 2. `self.writable(initial)` and native sources

A `NativeWatchable<T>` with `set(value)` (identity compared: `set` of the same value notifies nobody; a new value is a
new frame), owned by the attempt (dropped with it; `set` after the attempt's seal throws `released`); never a state
member; usable as a contribution, a derive source and an `on` source. `set` inside a batch marks it there; outside, it
opens its own batch. `writable`, `RegistryValue` and `ref.state` (a `NativeWatchable` since slice 3b, until now not derivable: design audit,
2026-10-27) are native sources: one base (`NativeSource`) the batch marks and derives depend on; `self.derive` takes JSON and native sources (its type and the source resolver widen), while the
member check still refuses a native as a state member.

## 3. `self.retryOn(...sources)`

In any object's factory, anywhere: Chord follows each source with watches owned by the object (under its context,
replaced by each attempt's declaration, stopped at the object's end; GC-tested), installed right after the factory
returns, before natives open, so a failed open still has them; a `value` call of a source while the object is failed
(`transient` or `broken`) retries it as `ref.retry()` does (backoff skipped, an attempt now, holders told `loading`);
a call while it activates is remembered and retries it at once if that attempt fails (decision S1); ignored while live. Sources
are those that live independently of the attempt: a `RegistryValue`, `constant`; anything else (a reference's member,
a `writable` of the same attempt) is refused at runtime (declaration policy; TypeScript cannot tell them apart).

**Which calls retry (D2, owner, 2026-10-27):** only `value` calls: a new value of a source wakes a failed object; a
`failed` call (a throwing `compose`) does nothing, its next good composition retries.

## 4. `host.root(fn, context, options?)`

**Signature and guarantees (D3, owner, 2026-10-27; design §26 #25):** `host.root<T>(fn: (ctx: Ctx) => Promise<T>,
context: Context, options?: { principal?: P }): Promise<T>`. `fn` gets a call context like a handler's: the host's
principal (or `options.principal`, a trusted same-host caller's choice, as base code acting for an authenticated
user), this host's incarnation, `context`'s telemetry and abort signal linked until `fn` settles
(`withLinkedAbortSignal`), and `ctx.get`. When `fn` settles or `context` aborts, the call context is sealed:
`ctx.abortSignal` aborted, `ctx.get` rejects `released`, every reference it took released (their calls reject
`released`, their watches end), so an uncooperative `fn` fails at its next use of Chord, as a handler after its caller
cancelled; work outside Chord runs on until then. `ctx.get` before `load` resolved parks like any reference;
`host.close` seals every open root scope (the host keeps them), so an `fn` waiting in `sleep(ms, ctx)` ends; `host.root`
after `host.close` rejects `released`. No span of its own until slice 9.

- `chord(fn, context)` is p3's helper over `host.root` (design §24); Chord ships none.

## 5. Durable on registries (examples, p3's pattern)

- Durable's `HarnessOptions.registry` takes a `RegistryReader` (`snapshot()`, `subscribe(listener)`, the listener
  called synchronously after every publication). A `RegistryValue` offers a synchronous observer of its compositions
  (`observe(observer, ctx)`, as Durable's `observeXXX`: `advance` inside the flush that composed, record only; an
  attached observer counts as watching, so the lazy compose runs for it); Durable's
  `registryReader(value)` (in its `src`) reads `.value` in `snapshot()` and forwards `observe` to `subscribe`. The
  harness object declares the extensions registry with `self.registry(...)`, so it activates (and opens Durable) only
  once the registry has a value. p3's `compose` builds Durable's snapshot without throwing (a duplicate task name is
  reported and the later extension left out).
- **Durable's views from other objects** (carry-over from 6b): the object that opens Durable contributes its harness to
  a registry (`HarnessRegistry`, p3's); another object declares it in its factory and follows a view through its value:

  ```ts
  const harness = self.registry(HarnessRegistry);          // a dependency: activation waits for it
  self.retryOn(harness);                                   // the new harness's contribution wakes the failed follower
  const view = self.follow((observer, ctx) => harness.value.observeConversation(id, observer, ctx));
  ```

  When that harness closes, Durable ends the observer `failed` (S1, a Durable change in this slice: a Session close
  ends observers `failed`, `ended` only when the observed owner ended), so the follower fails `transient` and its retry
  follows the new harness.
- Examples: Chord's `29-registries.ts` (a router registry with two contributing plugins, a conflict reported, a
  `writable` contribution, a missing provider healing) and `30-host-root.ts`; Durable's `test/examples/37-harness-
  registry.ts` (a Durable harness on the store, its extensions from a registry, its views followed by a second object)
  and the `registryReader` tests in Durable's tree. Durable's `subscribe` listeners then run inside Chord's flush:
  they only wake Durable's scheduler (no Chord call; a reentrant one would throw `invalid/reentrant`), which the
  `registryReader` test pins.

## 6. Carry-over

From `slices.md` "Slice 8": `host.root` (D3); `retryOn` (section 3); registries recomposing in the owner's flush (W4);
`host.activity` on the facet's host: not built (nothing needs it; dropped from the carry-over); Durable's views from
other objects (section 5). Left to slice 7: registries on reload (a reload replaces a contribution and a provider
atomically; staging composes nothing, decision D1 of "Review round 1"); `accepts` of contracts and jobs; a `writable`
across a pure swap; older registry readers across a reload of the provider.

**New names** (design §3, §5, the pinned reason list): the reason `unavailable/undeclared`; `HostError` kinds
`registry_conflict`, `registry_failed`, `contribution_failed`, `contribution_refused`, each reported once per episode.

## 7. Tests and cost

- One `describe` per mechanism: tokens and providers (two serves refused, a missing one healing), contributors
  (R21's type and runtime refusals, facet and object lifetimes, one value each), the table (order by plugin, versions
  adapted, refused versions reported), `compose` (in the flush, after a commit that changed a watchable contribution,
  conflicts reported, a throw as a failure call and its heal), reading (`self.registry` in derives and `on`, `.value` at
  use), `writable` (identity, batching, as a contribution), `retryOn` (a failed object retried by a contribution, value
  calls only, sources installed before natives), `host.root` (principal, release at settle, abort, before load, after
  close), `registryReader` with a Durable harness; GC for every table, writable and root scope.
- Cost guards: one compose per flush per changed table; no compose for an unchanged table; a `writable.set` of the same
  value costs one comparison.