@earendil-works/chord 1.4.0 → 1.5.1

package/docs/slice-3a.md

@@ -0,0 +1,296 @@
+# Slice 3a: remote objects over one link (spec, for the owner's approval)
+
+Status: **approved (owner, 2026-10-22)**, after Astra's and Fable's spec reviews. Guiding rule (owner): **simple, fast,
+correct**; where a choice was open, this spec takes the simplest option that is correct and cheap per hop.
+
+Slice 3 of the plan is split: **3a** (this) gets two hosts talking over one link; **3b** makes the link survive drops
+(re-holds, parking, `ref.state`, `host.hold`, `ref.retry()`, `linger`, `host.root`, `state: false`). Flow control, size
+limits, compression, relays, routing by address and IPC/WebSocket stay in slice 4; trace carriers (R5) in slice 9. The
+single source for building 3a, together with the feature map in `slices.md`, `design.md` read in full (most relevant:
+§3 links and values, §4, §5, §7, §8, §22), the decision log (R1, R4, R6, R20, Q1, Q4, W1, D11), the carry-over (L5,
+L6) and the root `AGENTS.md` style section. Builds on L1 and slices 1-2 (`da3a16e9f`).
+
+## What an app can do after this slice
+
+```ts
+type P = { kind: "owner" } | { kind: "guest"; session: string } | { kind: "server" };
+
+const Notes = remote("notes", {
+  version: 1,
+  params: { session: str() },
+  variants: {
+    editor: { state: { notes: arr(Note), count: int() }, methods: { add: method(obj({ text: str() })) } },
+    reader: { state: { notes: arr(PublicNote), count: int() } },
+  },
+});
+
+const facet = defineFacet<P>((host) => {
+  host.serve(Notes, ({ session }, principal, self) => {
+    const store = self.get(NoteStore, { session });          // a local shared store (slice 1)
+    const count = self.derive([store.notes], ([n]) => n.length);
+    if (principal.kind === "guest") {
+      return { variant: "reader", members: { notes: self.derive([store.notes], redact), count } };
+    }
+    return { variant: "editor", members: { notes: store.notes, count, add: async (args, ctx) => store.add(args, ctx) } };
+  });
+});
+
+const server = createHost<P>({ principal: { kind: "server" }, onError });
+await server.load([{ name: "@app/notes", facet }], ctx);
+server.accept(link.a, { principal: { kind: "guest", session: "S1" } });   // the entry point authenticated it
+
+const client = createHost<P>({ onError });                 // a tab: no principal of its own
+await client.load([], ctx);
+client.connect(link.b, { principal: { kind: "server" } });
+const notes = await client.get(Notes, { session: "S1" }, ctx);
+if (notes.variant === "reader") console.log(notes.notes.value);   // narrowed by variant
+```
+
+## 1. Hosts and links
+
+- `createHost({ principal?, principalKey?, onError, … })`: a host with a `principal` acts as it for its own requests;
+  a host without one (a client) has no principal. `principalKey` defaults to L1's canonical JSON.
+- **A link** is an ordered, bidirectional channel of `Uint8Array` messages: `send(message)`, `onMessage(listener)`,
+  `close()`, `onClose(listener)`. This slice ships `memoryLinkPair()`, which delivers each message one task later (as
+  every link kind will). `send` after close is a no-op.
+- `host.accept(link, { principal })`: a link from a child. Every hold and call arriving on it acts as `principal`,
+  stamped by this host. `host.connect(link, { principal })`: this host's parent link (at most one; a second `connect`
+  throws). In 3a a host serves over `accept` links and requests over its `connect` link; the `connect` principal is
+  stored for 3b and slice 4 (nothing arrives for it yet).
+- **Handshake:** each side sends `hello { protocol, incarnation }` first and nothing else until it received the
+  peer's. A message before `hello`, a second `hello`, or another `PROTOCOL_VERSION` (L1) closes the link. `incarnation`
+  is a uuidv7 minted per host; calls arriving on an `accept` link get the peer's as `ctx.incarnation` (R20).
+- **Where a reference goes:**
+
+  | Type | Served on this host | Not served here |
+  | --- | --- | --- |
+  | `local` | local (slices 1-2) | fails `unavailable` (local types never cross a link) |
+  | `remote` | local, as the requester's principal (table below) | over the `connect` link; without one, `unavailable` |
+
+  Any object may reference remote types, local objects included (a client's local view may `self.get` a server type).
+  Remote objects live while referenced, also with empty params; `load` never activates them (Q-A).
+- **Which principal a same-host remote reference uses:**
+
+  | Requester | Principal |
+  | --- | --- |
+  | `host.get` | the host's `principal` (a host without one fails `forbidden`) |
+  | `ctx.get` in a handler | `ctx.principal` (a guest's call gets the guest's view); a local handler: the host's |
+  | `self.get` in a remote object's factory | that object's principal |
+  | `self.get` in a local object's factory or a facet | the host's |
+
+- **Closing:** a link closing (either side) ends what was bound over it: on the consumer, references through it end
+  (`released`, watches `ended`) and pending calls and gets reject `unavailable`; on the provider, its holds are
+  released. `host.close` closes its links first, then ends its objects (no `gone` to closed links). Surviving a drop
+  is slice 3b.
+
+## 2. Messages (R1, R4, Q1, Q4, §22)
+
+```
+| u32 header length, big-endian | header JSON (UTF-8) | part 0 | part 1 | … |
+```
+
+- **One format on every link.** The header is a JSON object, a tagged union over `kind`, defined as a schema (TypeBox then, pi-schema since the schema switch);
+  every received header is checked with the compiled schema (the wire is a trust boundary; skipping it on trusted IPC
+  links comes with IPC in slice 4). The header lists its parts: `parts: [{ json, bytes }]`, the JSON text's byte length and
+  the byte lengths of the segments that follow it (`bytes: []` for state parts and arguments without bytes).
+- **Kinds,** consumer → provider: `hello`, `hold { hold, type, version, fingerprint, params }`, `release { hold }`,
+  `call { call, hold, method }` (1 part: the arguments), `cancel { call }`. Provider → consumer: `hello`, `bound {
+  hold, variant, failed? }` (1 part: the snapshot), `state { holds: [{ hold, failed? }] }` (1 part per listed hold),
+  `failed { hold, cause }`, `result { call }` (1 part), `error { call, error }`, `gone { hold, error }`.
+- **Ids** are numbers chosen by the sender, unique per link and direction, never reused while in use (a counter).
+  Ids a receiver does not know are ignored (Q1: a `result` crossing a `cancel`, a `state` part crossing a `release`).
+  A `hold` or `call` reusing a live id is a protocol error.
+- **One Delta encoder per state member** (owner, 2026-10-22, after the code review): the snapshot part is `{ [member]:
+  value }` (each member's encoder restarted); a `state` part is `{ [member]: WireOp[] }` with only the members that
+  changed (a derive's change is its `diffRevisions` ops; a retired singleton is `[["r", initial]]`).
+- **A failed member** is listed in the header (`failed: [{ member, error }]`) of the `bound` or `state` that carries the
+  failure, never in the part; the consumer's replica of that member then fails (reads throw the error, watches end
+  `failed`), the others keep updating (W1).
+- **Argument and result parts** are JSON text followed by raw byte segments: a `Uint8Array` leaf is written as
+  `{"$bytes": i}`, segment `i`'s length in the part's header entry. Decoding replaces each reference with a `subarray`
+  view of the received buffer (no copy). Example: `upload({ name: "chart.png", data: <1 MiB>, thumbs: [<2 KiB>, <512 B>]
+  })` travels as header `…"parts":[{"json":74,"bytes":[1048576,2048,512]}]`, then the JSON
+  `{"name":"chart.png","data":{"$bytes":0},"thumbs":[{"$bytes":1},{"$bytes":2}]}`, then the three raw segments. Encoding uses the
+  `JSON.stringify` replacer only for methods whose schema contains a `bytes()` leaf (decided once per method); others
+  are plain `JSON.stringify`. The key `$bytes` is reserved in those methods only (see below). State parts are plain JSON (state is JSON
+  only).
+- **Protocol errors close the link:** a header failing the schema, a part that is not valid JSON or whose wire ops fail
+  Delta's checks, an id reused while live, traffic before or a second `hello`. These are structural checks of the wire,
+  never checks of application state (state is never validated).
+- **Errors on the wire** are a tagged union: `{ kind: "chord", error }` (a `ChordError`'s JSON, L1) or `{ kind:
+  "plugin", code, message, details? }` (open point 3). Never a stack or a cause.
+
+## 2b. Codecs, the `Message` type and checks (owner, 2026-10-22, after the code review)
+
+Replaces the JSON-header framing of section 2 (`| u32 header length | header JSON | parts |`); the message kinds, ids,
+races and rules of section 2 stay.
+
+- **`Message`** is a tagged union defined once as a schema (TypeBox then, pi-schema since the schema switch) (`MESSAGE`; `type Message = Static<typeof
+  MESSAGE>`): `hello { protocol, incarnation }`, `hold { hold, type, version, fingerprint, params }`, `release { hold
+  }`, `call { call, hold, method, args? }`, `cancel { call }`, `bound { hold, variant, members: [{ member, value }],
+  failed: [{ member, error }] }`, `state { holds: [{ hold, members: [{ member, ops }], failed: [...] }] }`, `failed {
+  hold, cause }`, `result { call, value? }`, `error { call, error }`, `gone { hold, error }`. Values (`params`, `value`,
+  `ops`, arguments) are `unknown()` in the schema. `args` absent: a method without arguments; `value` absent: `null`.
+  A payload that may carry bytes is marked so by the protocol layer (decided once per method from its schema).
+- **Names are indexes:** `member`, `method` and `variant` are indexes into the **hold's bound version's** names,
+  sorted per variant. Both sides hold that version's description (version and fingerprint matched at `hold`). An index
+  is valid only while its hold is bound to that version; a provider that stops accepting a version ends that version's
+  holds with `gone` (contract_mismatch) before its new code serves anything (slice 7 builds the reload side; carry-over).
+- **`Codec { name, encode(message): Uint8Array, decode(bytes): Message }`**, chosen per link
+  (`host.accept(link, { principal, codec? }, context)`, `host.connect(...)`, default `binaryCodec`); both ends use the
+  same; a mismatch fails the first `hello` (a protocol error naming the expected codec). No negotiation.
+  - **`binaryCodec`:** a kind byte, then that kind's fields as unsigned varints (ids, indexes, counts, lengths),
+    length-prefixed UTF-8 strings, the incarnation as 16 raw bytes and the fingerprint as 8 raw bytes; values as varint
+    length plus JSON text; byte segments (payloads marked as carrying bytes) as a count, lengths, raw bytes, referenced
+    from the JSON by `{"$bytes": i}`. No outer length (links deliver whole messages).
+  - **`textCodec`:** one JSON tuple per message, Delta style (a short kind tag, positional fields, no field names):
+    `["h", protocol, incarnation]`, `["H", hold, type, version, fingerprint, params]`, `["R", hold]`, `["c", call, hold,
+    method, args?]`, `["x", call]`, `["b", hold, variant, [[member, value]…], [[member, error]…]?]`, `["s", [[hold,
+    [[member, ops]…], [[member, error]…]?]…]]`, `["f", hold, "t"|"b", error]`, `["r", call, value?]`, `["e", call,
+    error]`, `["g", hold, error]`; byte segments follow the tuple (their lengths in it).
+  - `describeMessage(message)` prints any message readably (the text tuple form) for logs and tests.
+- **Who checks what** (layers 1-3 failing is a protocol error that closes the link):
+
+  | Layer | Checks |
+  | --- | --- |
+  | 1. codec `decode` | lengths and varints fit, the buffer consumed exactly, a known kind, strict UTF-8, each JSON value parses, segment counts and references valid and only in payloads with bytes |
+  | 2. `MESSAGE` schema (protocol layer, after any codec) | the envelope: kinds, ids and indexes are integers, lists and error shapes; not the values |
+  | 3. the hold's bound version (protocol layer) | ids not reused while live (unknown ids ignored), indexes within the bound version's lists, order (`hello` first, `bound` before `state`) |
+  | 4. owners | `params`: `checkParams` (a broken `failed`, link stays); arguments: `checkArgs` (`error { call, invalid/args }`, link stays); ops: Delta's decoder and `applyImmutable` before anything is adopted (protocol error); errors: `chordErrorFromJson` (protocol error); snapshots and results: never validated (R9) |
+
+- **Memory link:** delivers with `queueMicrotask` (portable, asynchronous, no reentrancy); no Node-specific APIs.
+
+## 3. Remote objects (§4, §5, §6)
+
+- `host.serve(remoteContract, (params, principal, self) => ({ variant, members }))`: the factory returns one variant of
+  the contract with exactly that variant's members. L1's `Implementation<C>` for a remote contract becomes the tagged
+  union `{ [V in Variants]: { variant: V; members: VariantImplementation<V> } }[Variants]` (an L1 change); a local
+  contract's stays its members. An unknown variant, or missing or extra members of the chosen variant, fails the
+  activation broken (the member check, slice 1).
+- Identity: `(type, params key, principal key)` (L1 `identityKey`).
+- **Calls are checked against the binding's variant:** a call whose method is not in that variant fails
+  `invalid/member` before anything else (a reader cannot call `add` by forging a message); then L1's `checkArgs` checks
+  the arguments with the current version.
+- **Contract match (R6):** a `hold` binds only when its version and fingerprint equal the provider's current ones
+  (`accepts` is slice 7); otherwise `failed { hold, cause: broken contract_mismatch }`.
+- **A hold's activation** follows slice 2 on the provider: a broken failure is sent as `failed { hold, cause }` and is
+  final (the provider releases the hold); a transient one is sent as `failed { hold, cause }` with the hold kept
+  pending while the object retries; going live sends `bound`. The provider has no deadline of its own for a hold: the
+  consumer's getter deadline decides (it releases the hold when it gives up). A hold arriving before `load` resolved
+  waits for it; one arriving while the previous instance of its identity tears down waits for that (slice 2).
+
+## 4. References over a link (§7)
+
+- `host.get(Remote, params, ctx, { readyTimeout? })` sends `hold` and resolves with a live, hydrated reference on
+  `bound`. A `failed` with a broken cause rejects at once; a transient one is remembered while the get keeps waiting;
+  at its deadline (or cancellation) the get sends `release` and rejects with the last cause's error (or `unavailable`
+  if none arrived). `self.get(Remote)` follows slice 2 (R18): its object waits for `bound`, and a broken or transient
+  `failed` fails it as a failed dependency.
+- `ref.variant` is the variant's name and the discriminant TypeScript narrows on; a local reference has no `variant`.
+- **Replicas:** each state member of a remote reference is a watchable on the consumer, built from the snapshot and
+  then by Delta's `applyImmutable` of its ops (no validation, no copy). One `state` message is applied as **one batch**
+  of the consumer host, for all its holds, before any watch frame, so no consumer sees half a provider commit (W1).
+- `ref.method(args, ctx)` (or `ref.method(ctx)` without arguments) sends `call` and resolves with its `result`, or
+  rejects with its `error`. A call before `bound` cannot be made (the reference does not exist yet); a forged one is
+  answered `error { call, not_ready }`. The caller's cancellation sends `cancel` and rejects the caller at once; the
+  provider aborts that call's context.
+- **Release** (open point 1): `ref.release()` rejects the pending calls made through that reference with `released`,
+  sends `release`, and the provider aborts the handler contexts of that hold's calls and unholds (an object with params
+  ends with its last reference, local or remote). The same rule applies to local references (a change from slices
+  1-2, where a release left its pending calls running).
+- `gone { hold, error }` (the provider object ended): the reference ends (`released`, watches `ended`) and its pending
+  calls reject with the error; no per-call errors are sent.
+- Two references to one object from one host are two holds, each with its own encoder (two tabs are two clients).
+
+## 5. The provider side: one message per link per commit (W1)
+
+- A hold attaches to its object's state members as a **synchronous subscriber**: `Source` gets a second set of
+  subscribers besides its watches, fed `(value, ops)` inside the batch's delivery; a hold counts as watching, so exposed
+  derives recompute in the batch. Taking the snapshot and attaching happen in one synchronous step, so the first
+  `state` part continues exactly from the snapshot.
+- During a batch each touched hold collects its members' ops; at the **end of the batch** (a hook `Batch.commit` runs
+  after its delivery loop) each touched hold encodes its collected ops **once** into its part, and each link with
+  touched holds sends **one** `state` message. A link that closed meanwhile drops it.
+- A hold whose object ends sends `gone`; a failed member is announced once in the next `state` (or the `bound`).
+
+## 6. `ctx` (§8)
+
+`ctx.principal` (the stamped caller; on a local handler the host's), `ctx.incarnation` (the calling host's over a link,
+the own host's otherwise, R20), `ctx.get(Type, params)` (a reference released when the **handler** settles; a
+`ctx.get` after that throws `released`), the abort signal and telemetry.
+
+## Races
+
+1. A `result` crossing a `cancel`; a `call` crossing `gone`; a `state` crossing a `release`; a `bound` crossing a
+   `release` (the consumer ignores a `bound` for a hold it released): ignored by id (Q1).
+2. A commit between binding a hold and sending `bound`: the snapshot and the subscription are taken in one synchronous
+   step.
+3. A forged call before `bound`: `error { call, not_ready }` (parking is slice 3b).
+4. The provider object ends with calls pending: `gone`; the consumer rejects those calls itself.
+5. The consumer releases with calls pending: rejected locally `released`; the provider aborts the hold's calls.
+6. `release` while the provider is still activating for that hold: unhold (may end the object, slice 2); `bound` is
+   never sent.
+7. A `hold` while the previous instance of its identity tears down: waits (slice 2's endings).
+8. One object held over two links, one link closes: only that link's holds are released; the other keeps updating.
+9. A link closing during a batch: its `state` message is dropped; holds and calls on it end (section 1).
+10. A handshake that never completes: nothing else is accepted; a get over it waits up to its deadline.
+11. A `ctx.get` finishing after its handler settled: the late reference is released at once.
+12. A failed member and healthy members of several holds in one batch: each hold's part carries its healthy ops, its
+    header the failure.
+
+## Benchmarks (owner: light benchmarks for memory, timing and wire size)
+
+A script `packages/chord/test/bench/links.ts` (run by hand, not in CI) prints one table **per codec, side by
+side** (owner: both codecs, memory and compute); results are recorded in `packages/chord/docs/benchmarks.md` for
+later slices to compare against. Per case and codec: wire bytes per message; compute (encode and decode time per
+message over many messages, and commit-to-frame time end to end); memory (heap allocated per message while encoding and
+decoding 10,000 messages, measured with `--expose-gc`, and memory retained per hold). Payloads modelled on p2:
+
+| Case | Measured |
+| --- | --- |
+| hold of a notes list of 1,000 items; of a 500 KB document | snapshot encode/decode time, wire bytes |
+| one appended item, one changed field, one removed item | commit-to-frame time on the consumer, wire bytes per message, encodes per hold |
+| a streamed reply: 2,000 small text appends to one entry | time and bytes per append, total bytes |
+| 1 and 10 holds of one object on one link | memory per hold (encoder and replica), messages per commit |
+| a call with a small argument; with a 1 MiB `bytes()` argument | round trip, wire bytes (about 1 MiB, not 1.33) |
+
+## Carry-over taken by this slice
+
+L6: `PROTOCOL_VERSION` in the handshake; one message per link per commit; bytes as raw segments; a malformed error
+envelope closes the link; the plugin error shape. L5: `ctx.get`, `ctx.principal`. Moved to 3b in the feature map:
+`host.root`, C8 (`state: false`).
+
+## Tests
+
+- Messages: every kind round-trips; parts with byte segments; `$bytes` refused in methods with bytes and plain data elsewhere; each protocol error closes
+  the link; unknown ids ignored; id reuse refused.
+- Handshake: traffic before `hello`, a second `hello`, protocol mismatch; incarnations stamped.
+- Remote objects: variant per principal; identity per principal key; a call outside the binding's variant fails
+  `invalid/member` (forged at the wire, not just in types); arguments checked; contract mismatch; invalid variant or
+  members fail activation broken; remote objects with empty params are not activated by `load`.
+- Principals: the four same-host cases of section 1.
+- References: hydrated on get; broken `failed` rejects at once; transient `failed` keeps waiting and the deadline
+  rejects with the last cause and releases the hold; replicas apply one message as one batch (a consumer derive over two
+  members never sees half a commit); calls, results, cancel, errors of both kinds; release rejects pending calls (local
+  and remote); `gone`.
+- One message per commit: three holds on one link, one message; a derive with its source; two links, two messages.
+- Every race above.
+- Cost guards: one encode per hold part; no validation or copy of state on either side.
+- GC: a closed link and a released reference, **retained** by the test, hold no holds, encoders, replicas or objects.
+- Examples: `08-remote.ts` (two hosts, variants per principal), `09-calls.ts` (calls, results, errors, cancellation,
+  release).
+
+## Decided with the owner (2026-10-22)
+
+Slice 3 is split into 3a and 3b; a remote factory returns `{ variant, members }`; `ref.variant` is the discriminant
+(C15: no `inVariant`/`expectVariant`; `variant` reserved as a member name); headers are checked on every link for now.
+Release rejects the calls made through the released reference, locally and over links (their handlers' contexts are
+aborted). `$bytes` is reserved in the arguments and results of methods whose schema has a `bytes()` leaf (encoding
+refuses it with `invalid/args`); elsewhere it is plain data, since only parts with byte segments resolve references
+(owner, 2026-10-22, narrowing the first decision). Plugin errors: `new PluginError(code, message, details?)`; any other thrown value crosses
+as `{ kind: "plugin", code: "internal", message }`; only code, message and details cross; same-host callers get the
+thrown value; the consumer rethrows a `PluginError`.
+
+## Size
+
+About 1,500-2,000 source lines (both reviewers), including the L1 change and the batch's subscriber hook.

package/docs/slice-3b.md

@@ -0,0 +1,197 @@
+# Slice 3b: surviving drops (spec, for the owner's approval)
+
+Status: **approved (owner, 2026-10-22)**, after Astra's and Fable's spec reviews. Guiding rule (owner): simple, fast,
+correct. The single source for building 3b, together with the feature map in `slices.md` (entries assigned to 3b),
+`design.md` read in full (most relevant: §3 links, recovery and timeouts, §4, §6, §7 references, §8, §19, §22), the
+decision log, the carry-over (L4, L5, L6) and the root `AGENTS.md` style section. Builds on L1 and slices 1, 2 and 3a
+(`76b32ed2d`).
+
+## What an app can do after this slice
+
+```ts
+const notes = host.hold(Notes, { session: "S1" }, ctx);        // a reference at once, not awaited
+notes.state.value;                                              // { kind: "loading" }
+const w = await notes.state.watch(ctx);                         // the current state, then every change
+w.start(async (state) => render(state));                        // loading → live → loading (link dropped) → live …
+
+await notes.add({ text: "milk" }, ctx);                         // parks while loading, sent once live
+if (notes.state.value.kind === "failed") notes.retry();         // a Retry button
+
+client.connect(newLink, { principal: { kind: "server" } }, ctx);  // after a drop: every reference re-holds
+
+host.serve(Notes, factory, { linger: 5 * 60_000 });             // a just-released object stays warm for 5 minutes
+```
+
+## 1. Reference state (§7)
+
+- Every reference has `ref.state`, a `NativeWatchable<RefState>` (in-process: it holds errors; open point 1):
+
+  ```ts
+  type RefState =
+    | { kind: "loading" }
+    | { kind: "live" }
+    | { kind: "failed"; cause: FailureCause; retryAt: number | undefined }   // undefined: broken, no automatic retry
+    | { kind: "released" };
+  ```
+
+  `ref.state.watch(ctx)` delivers the current state, then every change. On release the state becomes `released` and
+  the watch ends `ended` (the end is the notification; a native watch drops undelivered frames when it ends).
+- **One rule for both sides:** a reference is `loading` while its object is activating or retrying, while it waits for
+  `load` or a parent link, and while its link is down; `failed` while its object is failed and no attempt runs; `live`
+  when bound; `released` once released. `variant` is `undefined` before the first binding and keeps the last bound
+  variant while `loading` or `failed`.
+
+  | State | Calls | State members |
+  | --- | --- | --- |
+  | `loading` | park (section 3) | readable: the last value; before the first binding a read throws `not_ready` and a `watch` waits for the first value |
+  | `live` | run | readable |
+  | `failed` | reject at once with the cause's error | reads throw the cause's error; existing watches stay open |
+  | `released` | throw `released` | reads throw `released`; watches end `ended` |
+
+- Member watches survive `loading` and `failed` (reference states): they get the next frame when the reference is live
+  again. They end only when the reference is released, the member itself fails (W1, `failed`), or the member is not in a
+  newly bound variant (`ended`).
+- **Retry** (open point 2): `ref.retry()` asks the object for an attempt now, skipping the backoff window and renewing a
+  broken object's readiness (carry-over L5); one attempt runs at a time, so a retry during one is ignored. Local: the
+  object's `attempt()`. Remote: a new message `retry { hold }`; the provider does the same for the held object, for all
+  its holders. On `live` and `released` references `retry()` does nothing; without an open parent link the next
+  `connect` re-holds anyway.
+- **Attempt notice** (open point 2): when a failed object starts a new attempt (backoff, retry, or a dependency going
+  live), its holds get `loading { hold }`, so remote references move `failed → loading` and park calls exactly like local
+  ones. `failed { hold, cause, retryIn? }` carries the remaining delay of the provider's window (`until - now`, from a
+  new `until` on slice 2's backoff entry, carry-over L4) as advice for `retryAt`; the attempt itself is announced by
+  `loading`.
+
+## 2. Acquiring: `hold` and `get` (§7)
+
+| Situation | `host.hold(Type, params, ctx, options?)` | `host.get(…)` |
+| --- | --- | --- |
+| invalid params, a local type not served here, no principal for a same-host remote type | throws at once (made before `load`: `failed` broken once `load` resolved, since the types are known only then) | rejects at once |
+| before `load` resolved, or no parent link yet (remote) | `loading` | waits |
+| the object activates | `loading` | waits |
+| a transient failure | `failed` (with `retryAt`), then `loading` on the next attempt | waits; at its deadline it releases the reference and rejects with the last cause |
+| a broken failure | `failed` | releases the reference and rejects at once with the cause |
+| the link drops before the first binding | `loading`, re-held on the next `connect` | keeps waiting within its one deadline |
+| live | `live` | resolves |
+| the caller's context is aborted | (no effect on a `hold`) | releases the reference and rejects |
+
+A `hold` follows its object until released and never rejects. A `get` has one deadline (`readyTimeout`, per get) from
+the moment it is called, across reconnects.
+
+## 3. Parking (§3, §7)
+
+- A call made on a `loading` reference is queued with its own deadline, measured from the moment it was called (a
+  reconnect never renews it). When the reference goes `live`, queued calls are **sent** in the order they were made,
+  before any later call (a new call cannot overtake queued ones); their completions may arrive in any order. When the
+  reference goes `failed` they reject with the cause; at its deadline a call rejects `unavailable/park_timeout`; the
+  caller's cancellation rejects it at once; release rejects them `released`.
+- A queued call is resolved against the binding it is sent on: after a reconnect that bound another variant, a method
+  the new variant lacks rejects `invalid/member`; indexes are taken from the new binding.
+- Calls already **sent** when the link drops fail `unavailable` (never resent, §7).
+- **The park deadline is `readyTimeout`** (owner, 2026-10-22; C13's two host timeouts stay): a queued call waits at most
+  the reference's `readyTimeout` (host default 60 s, per `get`/`hold` override), then rejects `unavailable/park_timeout`.
+
+## 4. Link drops and re-holds (§3 recovery, §4, §22)
+
+- **One owner of remote objects across links:** the host keeps its remote references (their objects) independent of any
+  one link; each `connect` creates a link with fresh id counters (ids are link-local) and re-holds every non-released
+  remote reference on it; a closed link's tables are dropped, and nothing of an old link (a late callback) touches the
+  new one.
+- **On a drop:** every non-released remote reference goes `loading` (also a `failed` one), sent calls fail
+  `unavailable`, new calls queue. `host.connect(link, …)` may be called again once the previous parent link has closed
+  (open point 6); while one is open it throws.
+- **The re-hold:** a new `hold` (new id); on its `bound`, in **one batch** of this host and before any queued call is
+  sent: each member of the bound variant gets the snapshot value with one frame `[["r", value]]` and a fresh Delta
+  decoder (open point 4); members not in the bound variant end (`ended`, derives over them fail); new members get their
+  first value; failed members listed in `bound` fail (W1); `variant` is updated. A different variant is the normal result
+  of a changed grant (design §4: reconnect, authenticate anew, re-hold). Then queued calls are sent.
+- **The provider side** is unchanged: a closed link releases its holds (objects with params end with their last
+  reference unless they linger, section 5); a reconnecting child is a new `accept` with new holds.
+- **References a host's objects hold** (`self.get` of a remote type) go `loading` the same way; a **live** dependent
+  stays live (R18: a dependency leaving `live` does not change it) and its calls through them queue. An **activating**
+  dependent keeps waiting for the dependency; its own `readyTimeout` bounds it (slice 2), and R18 retries it on `bound`.
+- Who reconnects is the app (its link adapter calls `connect` again); Chord only re-holds.
+
+## 5. `linger` (§3, §6, §19, D8, C7)
+
+`host.serve(Type, factory, { linger })` (milliseconds, default 0): a **live** object with params whose last reference
+is released stays live for `linger`, keeping its own dependencies; a `get`, `hold` or arriving `hold` message within
+that time reuses it; otherwise it ends. An object that is waiting, activating or failed when its last reference goes
+ends at once (slice 2). A failed state member is not a failed object and does not end a lingering one. `host.close`
+ends lingering objects at once. Host-lifetime objects (`local`, empty params) never end by references; a remote type
+with empty params lingers like any other.
+
+## Races (listed before sizing)
+
+1. A sent call when the link drops: fails `unavailable`, never resent.
+2. A call made while `loading`: queued with its deadline; sent once live, in order; `park_timeout`; cancellation;
+   release.
+3. A reference released while `loading` (no link): nothing sent; not re-held; queued calls reject `released`.
+4. `connect` while the previous parent link has not finished closing: throws.
+5. A drop during a re-hold's handshake or before its `bound`: stays `loading`; the next `connect` re-holds again.
+6. The re-hold finds the object failed: `failed` with `retryIn`; the provider's next attempt sends `loading`, then
+   `bound` when live.
+7. A reconnect creates a fresh object (the old one ended without linger): new snapshot; the old in-memory documents are
+   gone (documented).
+8. A get or an arriving `hold` within `linger` versus the linger timer: a reuse cancels the timer; the holder count
+   decides, so an expiry never ends an object that has a holder again; no grace period.
+9. A failing object without references ends at once, never lingers; the last release during activation ends it.
+10. `host.close` with queued calls and loading references: queued calls reject `released`, references go `released`.
+11. `ref.retry()` during an attempt or a pending re-hold: ignored.
+12. Shared remote retry: two consumers hold one failed object; one retries; both get `loading`, then `bound` or
+    `failed`.
+13. A broken object held by another consumer: a `retry` renews it for everyone.
+14. A reconnect binds another variant (a changed grant): replicas rebuilt in one batch; vanished members' watches end;
+    queued calls checked against the new variant.
+15. A release or a call's deadline while a snapshot is being adopted or queued calls are being sent: the reference's
+    state decides at each step; nothing is sent for a released reference.
+16. A member `watch` before the first binding: waits; rejects on `failed` (cause) or release.
+17. A re-hold arrives while the previous instance (released by the drop, no linger) still tears down: waits for that
+    ending (slice 2), then a fresh object.
+18. An activating dependent whose remote dependency's link drops: it fails transient at the drop (the dependency's
+    pending outcome rejects `unavailable`); R18 retries it when the dependency is bound again.
+19. A drop while `failed`: `loading`, re-held on the next `connect`.
+
+## Cost per hop
+
+Nothing changes for live references (calls, commits, frames as 3a). A drop costs one `hold` and one snapshot per
+reference on reconnect; a queued call holds its arguments until sent; `ref.state` is created lazily on first access.
+
+## Benchmarks
+
+Extend `test/bench/links.ts` (both codecs): reconnect with 1 and 100 references (time to all live, bytes), 1,000
+queued calls flushed on reconnect (time, order), and the live paths of 3a unchanged (regression rows).
+
+## Carry-over taken by this slice
+
+L4: `retryAt` (backoff `until`). L5: `ref.retry()` renewing a broken object's readiness; calls on a failed reference
+reject with its cause; C8. L6: `linger`, `ref.state`, `ref.retry()`, `host.hold`. Moved out: a second `bound` as a reset
+(slice 4 for `reset` after overflow, slice 7 for restarted objects); the park deadline's per-type override is not
+built.
+
+## Tests
+
+- `ref.state`: every transition for local and remote references, watched (first value, each change, the end on
+  release); `variant` before, during and after bindings.
+- `hold` and `get`: every row of the table in section 2.
+- Parking: queue order, one deadline across reconnects, cancellation, release, failure, a variant change.
+- Drops and re-holds: references go loading; sent calls fail; reconnect re-holds with fresh ids; one batch per bound
+  with `[["r", value]]` frames; another variant on reconnect; old-link callbacks never touch the new link.
+- Retry: local and remote; shared across consumers; broken renewed; ignored during an attempt; `loading` notices.
+- `linger`: reuse within the window, end after it, only live objects linger, failed members do not end it,
+  `host.close`, reconnect within linger keeps in-memory documents.
+- Every race above, both codecs where a link is involved.
+- GC: a released `hold` reference, a reference across a drop, a closed link's tables, a lingering object after expiry.
+- Examples: `10-drops.ts` (drop, park, reconnect, re-hold, `ref.state`), `11-linger-and-retry.ts`.
+
+## Decided with the owner (2026-10-22)
+
+`ref.state` is a `NativeWatchable<RefState>` (the `NativeWatchable` interface joins `Watchable` in `src/watch.ts`,
+upstream first); remote retries use two new messages, `retry { hold }` and `loading { hold }`; parked calls wait at most
+`readyTimeout` (no third host timeout); a re-hold replaces each member with `[["r", value]]`; C8 (`state: false`) is
+cut; `connect` may be called again once the previous parent link has closed; `host.root` moves to slice 8.
+
+## Size
+
+About 1,100-1,400 source lines (reference state, acquisition, parking with its queue, re-holds with variant changes,
+retry and loading notices, `linger`).