pi-mono/packages/chord/docs/slice-7a.md

Slice 7a: the dependency model (spec)

Status: ready to build (owner, 2026-10-29: the model decided, "just build this"). Slice 7 is split: 7a builds the dependency model on what exists (one load per host, links, routes, relays); 7b builds reload and rollout on top of it (removal, dropped versions, installs, own-code reloads, loader D).

Read in full before writing code: dependencies/model.md (the model as decided; its section numbers are cited below as M§), design.md, decisions.md (the entries of 2026-10-28/29: "No client providers", "Every remote type declares its placement", "hostAddress instead of placement", "Only hosts with an address serve remote types", "Getters wait through waiting", "Cycles across hosts: no probe, a diagnostic", "The dependency model is decided"), slices.md (slice 7's carry-over: 7a takes none of it unless named here; 7b takes the rest), the explainer dependencies/book.md for the scenarios (its catalogs are test material).

1. Requests and the unbound index (M§1)

• Every reference is a request with one holder (attempt, call, outside code, a link's peer). It ends only when its holder ends it; never because its provider is missing or does not fit.
• The destination by address is built (host/destination.ts, slice 7a's predecessor commit 5ec241882). Add: version checks only against the selected provider (no #assertRoute comparison with a same-name registration on the consumer's host); a local type not served here is no longer a throw at self.get/host.hold/getters but an unbound request.
• The publication gate: a request made on this host, or a hold arriving on its links, before the host's first publication is not placed: loading, placed by the publication. pendingLoad no longer gates Hold.start or #hold beyond the publication (it ends the startup deadlock: Sol's probe /tmp/dep-graph-sol-barrier.log becomes a regression test that passes with fake timers never advanced).
• Unbound reasons (M§1's table): unpublished (loading), not_served and version (failed { waiting }), compose for registries (failed { waiting }), no_link on a path (loading); authorize refused or invalid params stay broken, never indexed. Indexes per host by name (local requests; refused holds that arrived over links, kept as today's refused state in remote/hold.ts); entries removed when the request ends (release, call settled, getter gave up, closed { origin }, link close, revocation). GC tests.

2. States (M§2)

• FailureCause gains { kind: "waiting"; error } (no retryAt). The wire's failed cause schema carries it; the pinned list and its test change; PROTOCOL_VERSION stays 1.
• The mapping of M§2's table: loading for activating, unpublished, no link (and installing, 7b); failed { waiting } for not served, version, compose, and a dependent whose dependency failed.
• A remote refusal for not served / version is failed { waiting } instead of broken; the provider keeps the refused hold (it does today) and the consumer never retries it by itself (no backoff).

3. Parked attempts (M§3)

• Order: factory, persisted singleton hydration (as today), requests made; the attempt is parked while any dependency (self.get local or remote, self.registry, keyed pins) is not live and hydrated. self.follow is not a dependency (its attach is an own step).
• What it shows: loading while blockers are only loading; failed { waiting, "waiting for X: <cause>" } (nearest blocker plus root cause, 500-character rule) when one failed; broken when one failed with invalid/cycle (off-ring dependents) or ended.
• No timer while parked: no dependency deadline, no identity backoff for dependency failures; the attempt's readyTimeout deadline is paused while parked (as eager migrations pause it) and resumes with the budget left. The identity backoff stays for the object's own transient failures only.
• The dependency check is the boundary: once all are live, the own steps run (natives, follow attaches, member checks, derives) under the deadline; a dependency leaving live afterwards is treated as after live (R18): the attempt goes on.
• Wakes on every state change of a dependency (live, loading, failed, a new cause compared by value, ended): re-evaluate what the object shows, leave parking when all are live; never re-run the factory while parked; coalesce per object after the batch that caused them; remember changes during own steps or teardown.
• Retry passes on: ref.retry() on a failed { waiting } object retries its broken and transient blockers hop by hop (the existing retry message), once per operation (an id dedupes diamonds); waiting blockers pass it on. A retryOn value call while parked waiting does nothing.

4. Wakes (M§4)

Two events: a target changes state (the requests bound to it and their dependents); a name becomes usable on a host (in 7a: load's publication serving types and registries, a registry's value turning usable at a version): the unbound requests indexed under it, and refused holds, which re-run their start and send loading, then bound or failed. No new message kind.

5. Startup (M§6)

• load runs the setups, publishes them in one batch (types, registries served and composed once, contributions), wakes after that batch, then activates host-lifetime objects.
• The barrier, decision (a): load resolves when every host-lifetime object of the load has a first outcome: live, failed by its own cause, or parked with no blocker that is a local object still without its first outcome (local = executing on this host, keyed pins still loading here included). One firstOutcome signal per object, separate from the readiness dependents wait for; counted once; an object of the cohort that ends before its first outcome settles as ended; host.close settles a waiting load.

6. Getters, holds, calls (M§8, decision "Getters wait through waiting")

• host.hold returns a reference at once; only invalid params throw (also before load); a missing local type gives loading before the publication, failed { waiting } after it, before and after load alike.
• host.get, ctx.get, host.registry: resolve when live; wait through loading, failed { transient } and failed { waiting } until their readyTimeout, then reject with the last cause and release; reject at once only on failed { broken }.
• Calls: park on loading (bounded, as today); reject at once on failed; never resent.

7. Registries (M§9)

A reader's request: bound while R is served and has a usable value at its version; otherwise unbound not_served, version (S2's newer or unmapped reader: waiting, not broken) or compose (first compose or the version mapping threw), loading before the publication. Woken at every transition to usable (#valued's latch goes). The last good value is kept only while every contribution it was built from is still in the table (decision 5): when one leaves, the last good value is dropped and .value throws until compose succeeds.

8. Keep-alive, revocation, cycles (M§7, M§10)

• A request over a link counts once in host.activity.references from arrival to end, bound or unbound; host.references lists bound references only.
• Revocation ends the requests of a revoked principal, bound and unbound, at every hop.
• gone only for revocation (a closing provider host sends nothing, as today).
• Cycles: the walk at self.get on one host, through parked attempts too; the activation chains across hosts as today. Remove the dependency deadline (no fallback). Add HostError parked_long { object, waitingFor, since }: once per parking episode, when an attempt has been parked longer than its readyTimeout on a remote attempt that is itself only loading. The guide (host README) states the four authoring rules of M§7.

9. Not in 7a (7b)

Removal and re-serving of types (local re-binding of a Binding, a failed on a bound hold unbinding it, window slots), a dropped accepted version, installing and install ends, own-code reloads and the parked-attempt handover, pure swaps parking (decision 4), rollout, loader D. 7a's code must leave those paths possible, not build them.

10. Tests and cost

• One describe per mechanism; the four catalogs in dependencies/book.md (chapters XIV-XVII) are the scenario list: every row that 7a's scope reaches becomes a test (memory links; relays; fake timers where a test proves no timer runs). Must include: the startup deadlock without readyTimeout; a hold before the publication placed here, not via the parent; a missing local type on self.get, host.hold, host.get (waits, then rejects with the cause); a remote refusal kept and re-run when the provider's late load publishes; a parked three-level chain across hosts woken in order; wakes on every state change with causes updated; retry passing on through a diamond once; the barrier's first-outcome rule (CodeMode → Harness waits; a remote blocker ends the pass); a cohort object ending before its outcome; registries' waiting reader, wake after a provider arrives, last good dropped when a contribution leaves; keep-alive counting unbound holds; revocation of unbound holds; parked_long reported once; GC tests for the indexes and a parked chain released from the top.
• Benchmarks (the bar of "The performance and memory bar"): calls, activation churn, a watched derive, links against HEAD, pinned, alternating, a HEAD copy at a path of the same length; results in benchmarks.md.
• Examples: 31-parked-dependencies.ts (a missing provider arrives; causes shown; no timers), 32-startup.ts (two hosts that would have deadlocked).
• Docs: fold the model into design.md (§3, §6, §7, §17, §21's 7a parts) in the same change as the build; mark dependencies/model.md as built for 7a.