pi-mono/packages/chord/docs/next/slice-3a.md

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

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/next/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/next/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.