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.

9.8 KiB Raw Blame History