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

# Slice 7b: reload in the kernel (spec)

Status: **built** (2026-10-29; the rules folded into `design.md` §21, §6, §7, §15, §17, §22, §27). Spec: owner,
2026-10-29, the brief `slice-7b/` and its six points decided as recommended, decision "Slice 7b's open points, as
recommended"; decisions of the build, below each section where they apply (owner, 2026-10-29). 7b builds `host.reload` and everything an object, a reference, a job and a
registry does across it, on one host. Facets are passed in imported (tests import them statically); the bundler and
the dev loop are slice 7c, the rollout across hosts is the app's.

Read in full before writing code: this spec, the brief `slice-7b/book.md` (chapters "One Host Reloads" to "Across
Hosts"), `dependencies/model.md` (decided; built for 7a, its 7b parts are listed in its status line), `design.md` (§5,
§6, §9, §14, §15, §17, §21, §22, §27), `decisions.md` (the 2026-10-29 entries; R15, R16, Q10, "The seal fence", "Job runs
belong to the object", "A native restart drains first", "Slice 8 D1"), `slices.md` (slice 7b's carry-over: every entry
is in this spec or named as out of scope in §12).

## 1. The API

```ts
interface Host<P> {
  load(facets: readonly PluginFacet<P>[], context: Context): Promise<void>;                 // once, first
  reload(facets: readonly PluginFacet<P>[], context: Context): Promise<ReloadReport>;      // after load, any number
}
type PluginFacet<P> = { readonly name: string; readonly facet: Facet<P> };

type ReloadReport = {
  readonly plugins: { readonly added: readonly string[]; readonly changed: readonly string[]; readonly removed: readonly string[] };
  readonly objects: readonly ReloadedObject[];                  // every live, activating, parked or failed object of a reloaded plugin
};
type ReloadedObject = { readonly object: string } & (
  | { readonly kind: "swapped" }                                // pure, in place
  | { readonly kind: "restarted" }                              // natives: drained, closed (`reload`), activated again
  | { readonly kind: "ended" }                                  // its type is gone
  | { readonly kind: "parked"; readonly cause: FailureCause }   // the new code waits for a dependency (decision 4)
  | { readonly kind: "retried" }                                // it was failed or parked; a new attempt runs on the new code
);
```

- `facets` is the host's **complete new plugin set**: a plugin in it and not loaded is added; one in it and loaded is
  changed (Chord compares no code), unless its facet is the very same object as the loaded one (`===`): that plugin
  is unchanged, untouched and not in the report (owner, 2026-10-29); one loaded and not in it is removed. The core
  facet is a plugin like the others; base code passes the same facet value every time.
- `reload` resolves once the commit happened and every object has taken its fate (§4): swaps done, restarts and retries
  started (it does not wait for them to go live; their outcome is in their `ref.state`). It rejects with the code error
  when load or staging fails, and nothing has changed. Reloads are serialized per host (a second call waits for the
  first). Before `load` resolved: throws; after `host.close`: rejects `released/closed`. `context` bounds the reload
  (decision 4: no install watchdog); its abort before the commit rejects `aborted` and changes nothing; after the commit
  it only ends the wait.

## 2. Staging (all or nothing; **superseded** 2026-10-30 by "Per plugin at startup and reload": a failing plugin keeps its old code, slice 7c §4)

1. **Setups.** Every facet's setup runs into a **staged** table, beside the live one: served types (with their factory,
   options and `bindProvider(contract, options.accepts)`, which runs `checkAccepts`), served registries (provider
   with `compose` and `accepts`), facet contributions. The checks of `load` apply (plugin names, a type or registry
   served twice, a remote type on a host without principal or address).
2. **Factories.** For every object of a changed or removed plugin's types that exists now (live, activating, parked,
   failed), and whose type is still served: the new factory runs against a **recording `self`**, with the object's
   params (and principal), and declares only: what it opens (`self.open`), the documents and tables it declares with
   their versions, its jobs with their versions, its contributions, its requests. Nothing is activated, bound or
   opened; handles from a recording `self` are inert. This gives each object's fate (§4) before the commit.
3. **Any throw** (a setup, a factory, `checkAccepts`, a declaration error) rejects `reload` with that error, names the
   plugin (and object), and the host stays entirely on its old code: the staged table is dropped.
4. **While staging,** the host is **installing** (model §1): a hold that arrives for a type or version that the running
   code does not serve waits `installing` (`loading`) instead of `not_served`/`version`, and is re-evaluated when the
   reload ends, by its commit or its rejection.

## 3. The commit (one batch)

In one `batch.commit`, synchronous:

- The served types table becomes the staged one: added and changed types replace their entries (factory, provider,
  `linger`); removed types are dropped.
- **Registries** (slice 8 §6): a changed or added plugin's provider replaces the old one (`RegistryRecord.serve` refuses
  a second serve today: it becomes `replace` for a reload); a removed plugin's provider goes (its readers become
  unbound `not_served`); the reloaded plugins' facet contributions replace theirs, by plugin; object contributions stay
  with their objects (they follow the objects' fates); every changed table recomposes once, lazily, as today. The record
  keeps the provider, facet contributions by plugin and object contributions by object apart.
- **The publication** (model §4): after the batch, the unbound requests waiting for the names the reload serves (types,
  registries, versions) are re-evaluated (`UnboundIndex.wake(names)`, per name: the carry-over "Publications wake per
  name"), refused holds for those names re-run their start, and `installing` holds are re-evaluated against the new
  code.
- `host.references(Type)` of a removed type is dropped (carry-over from 4b).

## 4. Fates

Each object of a changed or removed plugin's types takes one fate, decided in staging (design §21, decisions above):

| The object | Fate |
| --- | --- |
| its type is removed | **ended**: as an object end today (natives close with reason `end`, callers of running calls rejected `released`, handlers drained); its requests are released; its holders' requests become unbound `not_served` (§6) |
| failed or parked | **retried**: its attempt is replaced by one of the new factory (a parked attempt in one handover: the new requests bind before the old ones are released; the mechanism 7a removed comes back here, carry-over) |
| live, old and new code open no natives, and no table of the new factory is at a newer version | **swapped** in place (§5) |
| live, otherwise | **restarted**: new calls park (the gate closes, holders see `loading`), running calls drain (bounded by `closeTimeout`; a call outliving the drain is cut off by the seal fence), the attempt is sealed, natives close (reason `reload`), the new factory's attempt activates (documents stay; eager table migrations run as at activation) |
| any of the above whose new factory declares a dependency that is not there | **parked** on it (decision 4): the gate stays closed, holders see `loading` or `failed { waiting }`; no overlap of old and new code |

- A restarted object gets a new instance id (an old activation chain must not match it, carry-over from 4b); a swapped
  object keeps it; a retried one keeps it, as any retry does (slice 4b; fix round 1, Opus F3).
- Objects of plugins not in the reload are untouched; their requests to changed types follow §6.
- Host-lifetime objects of an added plugin start after the commit as at `load` (no barrier: `reload` does not wait for
  first outcomes).

## 5. The pure swap

A pure swap is not a replacement (decision "The seal fence"): the old attempt is not sealed while its calls run.

- **Gate.** For the swap itself the gate closes; new calls park (bounded) until the new attempt is live.
- **New attempt.** The new factory's attempt is made with the same object: same documents and line (they are the
  object's), same job records. Its requests are made and bound before the old attempt's are released: a request equal
  to an old one (same type, params, principal, version) binds to the same target with no gap. It parks if a new
  dependency is not live (§4, parked). It runs its own steps (no natives by definition: derives, member checks), its
  members re-bind by name (`#rebind` exists: one frame from the last value per member; a member the new variant lacks
  fails `invalid/member`), its contributions replace the old attempt's in the registries in one batch, its routines
  start after the handover (below), its jobs take over the job records (§8).
- **Old calls.** Running calls finish on the old attempt with its handles valid (their transactions commit) until they
  settle, except R15: an old call touching a document whose version rose throws once (the document intact, the call
  not resent); the same for a table whose version rose (old table handles' version fence, carry-over from 6a: old code
  never issues SQL for a dropped column). Once the old attempt's calls settled, it is sealed and its references are
  released.
- **Routines** hand over per object: the old attempt's routines are aborted; the new ones start once the old routine
  calls finished, bounded by `closeTimeout` (a stuck one is reported and the new ones start anyway); calls never wait for
  it; each old routine invocation is fenced on its own (carry-over from 6a).
- **Derives** have no names: exposed derives are matched by member name (references move to the new instance's members, §13
  item 11); internal ones are rebuilt.
- **In-memory documents** migrate through their definition's `migrate` when the new code declares a higher version
  (6a built the slot version check; carry-over).
- **`self.writable`** starts at its new initial value (decision 2).
- **`retryOn`** sources are re-declared by the new factory.

## 6. References across a reload

**Provider side** (holds this host serves, and bindings on this host):

| The reload | A hold or binding |
| --- | --- |
| the object is swapped, its version still accepted | kept; re-subscribed through the version's mappings; one `[["r", value]]` per member whose value changed |
| the object is restarted, version still accepted | kept; `loading`, then a fresh `bound` (a `bound` on a bound hold, which 4a's consumer applies as a re-binding) |
| the new code no longer accepts the hold's version | unbound `version` (`failed { waiting }`); the object and its other holds stay |
| the type is removed | unbound `not_served` (`failed { waiting }`) |

- **Over a link,** a `failed` on a bound hold unbinds it (model §5): the consumer applies it as `#startOver` plus
  `failed`; the provider detaches the hold's sources, drops its unsent pending ops and a queued `bound`, keeps the ack
  slots of `bound`/`state` messages already sent until their `ack` or the link's loss, and rejects the calls in flight on
  it once. `Hold.moved` and `ProviderSide.unbind` handle bound and binding holds (carry-over from 3a/6a). A served hold
  whose object leaves `live` while its `bound` waits for a slot goes back to pending.
- **On the same host,** a `Binding` whose target ended by removal becomes unbound and accepts a second `bind` (model
  §5): the reference moves its members to the next object by name (§13 item 11), keyed pins re-pin, parked calls flush or reject, presence lists it again.
- **The consumer's own reload:** the new factory makes new requests (§5's handover). A reference made by outside code
  (`host.hold`) keeps the token its caller passed; Chord reloads no caller code.
- **A remote object that leaves `live`** (`RemoteObject.failed` ignores a failure while live today): handled by the
  unbinding above.

## 7. Versions in use (`accepts`)

- `host.serve(Type, factory, { accepts, linger })`: today every provider is bound with an empty table
  (`bindProvider(contract, {})`); 7b passes `options.accepts`, checked by `checkAccepts` at the setup (a declaration
  error rejects the reload or the load).
- **Binding an older consumer:** a hold whose version is accepted binds through the mappings of that version (Q10):
  state members through `(current) => old`, served like a derive of the provider's member per object and version
  (adapted bindings get diffs: the last adapted value per object and version, `diffRevisions`, never a whole value per
  commit; §13.11); method calls through
  `checkArgs`: `{ kind: "method", args, result? }` runs the handler and maps the result back with `result`; `{ kind:
  "call", args, call }` runs the provider's replacement (L1 built the check; 7b invokes it). Removed state members with
  `"refuse"` and removed methods with `"refuse"` fail the binding or the call `contract_mismatch`.
- **Keyed members** are mapped per key (carry-over from 6a), only on `local` contracts.

## 8. Jobs across a reload

- **Job records** keep the definition of the version their runs were started with; the new attempt's `self.job(Def,
  impl)` at another version no longer throws (`ChordObject.jobRecords` today): the records take the new definition, and
  each run keeps its own version.
- A run started on an older version and still running finishes on its old code across a pure swap (its invocation keeps
  the old implementation); `finish` runs on the new code with the outcome's args and result mapped forwards through
  `accepts[old]` (once per run); `running` shows its args mapped.
- No adapter for a run's version, or a run of a newer version (a rollback): the run is `blocked { version }` until a
  reload brings matching code; blocked runs (also `finish_failed` ones) are retried on every reload.
- A native restart aborts running runs (`aborted { reason: "reload" }`); `finish` runs on the new code.
- A job the new code no longer declares: its runs are `blocked { version }` (kept, not invoked) until a reload declares
  it again or they are aborted; a persisted run of another version or fingerprint stays blocked with its record as
  stored and is resolved by the reload that brings its version.
- A `finish` in flight across a reload completes on the code it started with; the next one runs on the new code.
- A job's fingerprint covers args, result and state: a schema change without a version bump is refused at declaration
  (as documents).
- An older run's state document migrates through its own `migrate` only once its run settled or moved to the new code
  (the old code keeps writing the version it knows).

## 9. Errors, cycles, presence

- A broken object of a reloaded plugin is retried (as `ref.retry()`), whatever broke it.
- Cycles: the walk and chains as today, checked again for the new attempts; `parked_long` unchanged.
- Presence: holds kept across a swap stay listed; a restart lists them again when they re-bind.

## 10. Telemetry and reports

`onError` gets what fails after the commit as today (`activation_failed`, `close_failed`, `routine_failed`, …). No new
`HostError` kind; the report returned by `reload` is the summary.

## 11. Tests, examples, cost

- One `describe` per mechanism: the API (serialized, before load, after close, abort before and after the commit);
  staging (each kind of throw leaves the host unchanged; recorded declarations decide the fate); the commit (types,
  registries, per-name wakes, `installing` holds); each fate (swap, restart, end, retry, parked, a new dependency
  missing); the swap (old calls on old handles, R15 for documents and tables, the handover of references without a gap,
  member re-binding, routines handed over and fenced, derives, in-memory migrate, a writable back to initial);
  references (each provider-side row over a memory link and through a relay, the window full while unbinding, a
  removed-then-re-served type with a live local dependent and with a remote one); `accepts` (state mapped per object and version as
  diffs, old args mapped, a result mapped back, a replacement `call`, `"refuse"`, keyed members per key); jobs (each
  rule of §8, in memory and persisted); registries (provider replaced, contributions by plugin replaced, a reader of an
  older version); a three-host scenario (server, worker, tab) reloaded in the app's order, as an example's test.
- Examples: `33-reload.ts` (a pure swap, a restart and a removal, with old calls and holders shown) and `34-versions.ts`
  (a contract and a job at v2 with `accepts`, an old tab and an old run carried across).
- Benchmarks: the hot paths against HEAD (calls, commits through a watched derive, activation, links) within the bar;
  plus a reload benchmark (one plugin of 20 reloaded on a host with 1,000 live objects, swap and restart) reported in
  `benchmarks.md`.
- GC tests: an old attempt and its closures collected after its calls settled; a removed type's objects, providers
  and registry entries collected; an old facet's code collected after a reload (the precondition for loader D).

## 12. Out of scope

Slice 7c: the bundler and loader (`chord/loader`), the dev loop (`chord/dev`), plugin discovery and npm
dependencies. The app: the rollout across hosts (decision 3: it calls `host.reload` per host in order). Slices 10 and
11: the app kit. `rebuild` of tables (key or column-type changes): only if a case needs it (carry-over stays).

## 13. Decisions of the build (owner, 2026-10-29; 11 is the builder's, reported for review)

1. An object of a reloaded plugin that is activating but not parked (its own steps), or waiting for its backoff, is
   `retried` (an activating attempt sealed, its natives closed `reload`).
2. The report's `parked` is for swaps and retries whose new attempt's first dependency check is not live (`reload`
   waits for that check, not for live); restarts are reported `restarted` at once (their check follows the drain). A
   blocker that is only loading gives the cause `waiting` "waiting for X: X is loading".
3. A swapped-out attempt is sealed once its running calls settled (bounded by `closeTimeout`, `drain_timeout`) and
   the swap ended; its references are released then. Its job invocations finish on their old code. Retiring
   attempts are bounded by `closeTimeout` each; a later swap does not wait for them (several may retire at once after
   quick reloads), a restart, an end and the host's close do (an end rejects their callers at once). (Fix round 1:
   Fable, Opus F1.)
4. A stuck old routine call past the handover is reported `drain_timeout`; the old attempt's routine calls share one
   fence token, sealed when the new routines start.
5. A swap whose new factory picks another variant sends its holds a fresh `bound`; so does one after which a hold's
   version is an older one (adapted members).
6. A native restart: in-memory runs end `aborted { reason: "reload" }` and finish on the new code; persisted runs
   follow 6b R3 (a seal while the object continues is a clean stop): written back stopped, resumed per `resume` by the
   new attempt without counting a restart.
7. Staging is synchronous; `installing` is built and tested from inside a staged factory.
8. ~~A removed object's member sources and pinned keys are frozen and handed over to the next object of its identity.~~
   **Superseded** (owner, 2026-10-29, decision "References are the only indirection"): references keep their last
   values while unbound and move their subscriptions to the next object; nothing is handed between objects.
9. A loaded plugin passed as the same facet object is unchanged (§1).
10. Keyed members' versions (§7) are built with L1's keyed edits (`keyed`, `addKeyed`, `removeKeyed`) and an accepts
    section `keyed: { member: (current) => old | "refuse" }` (removed ones: `"refuse"`).
11. Adapted state members are shared per object instance and version (not per binding): one cached value and one diff
    per commit for every consumer of a version; each hold encodes its own ops. Fix rounds 1 to 7 built sources owned by
    (identity, version) that outlived their object and moved to the next one (`host/handover.ts`), and kept finding
    edge cases in that hand-over. **Replaced** (owner, 2026-10-29, decision "References are the only indirection"): a
    consumer's watches and derives attach through the reference's member, which passes them straight to the object's
    own document or derive and moves them when the reference's target changes (one frame); while unbound the reference
    keeps its last values (watches get one `failed` call); an older consumer attaches to the instance's shared mapping
    for its version (made on first use, dropped when no reference of the version is left, gone with the instance).
    Nothing outlives its object instance.