@earendil-works/chord 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+## [1.3.0] - 2026-10-15
+
+### Breaking Changes
+
+- Terminology follows the concepts: a reference (what `get` returns) is `Ref<C>` (was `Handle<C>`), its status `RefStatus` (was `HandleStatus`); what a factory returns is `ImplementationOf<C>` (was `BehaviorOf<C>`); a resource's options are a `ResourceDeclaration` (was `ResourceSpec`); epochs are code versions: `Ctx.codeVersion`, `RootOptions.codeVersion`, `Host.codeVersion`/`previousCodeVersion`, and the `codeVersion` fields of frames and reload reports (all were `epoch`). Docs and messages say object (was record) and reference (was handle and hold); the `hold` and `release` frame types keep their names
+- A remote object's variant is named `variant` (was `kind`): factories return `{ variant: "editor", … }`, references expose `ref.variant` and `shape.variant`, and the `shape` frame carries `variant`. `variant` is reserved as a member name; `kind` no longer is
+- Links have a protocol version (`PROTOCOL_VERSION`, now 2), announced in `hello`. Peers of different versions do not talk: the side that notices closes the link with reason `protocol-version <n>`, and both sides report it through `LinkOptions.onProtocolMismatch`. Peers without a version (older Chord) are refused
+- `serve(…, { lifetime })` replaces `eager`: `"referenced"` (the default) creates an object at the first `get` of its address and disposes it after the last reference is released (plus `linger`); `"host"` creates the type's one object when its facet loads and keeps it until the host closes or a reload removes its facet. `lifetime: "host"` is refused at `serve` for remote types, for inputs that do not accept `{}` and together with `linger`; every `get` of such a type reaches its one object, created for the host principal, and another input is `invalid/input`. `eager: { input }` and the extra objects host-principal `get`s with other inputs created are gone. Only `"host"` objects may register (reason `invalid/not_host_lifetime`, was `not_eager`). `LoadOptions.awaitHostObjects` replaces `awaitEager`
+- Declarations are calls by name: `self.state(name, schema, initial, { version?, migrate? })` returns the cell, `self.resource(name, { version, deps?, exclusive?, open, close? })` the resource (`rev` is now `version`), `self.on(name, source, [select,] handler)` declares a listener; `self.derive(sources, fn)` and `self.task(fn)` take no name. `cell()`, `derivation()`, `resource()`, `listener()`, `self.resources`, `self.listen`, `self.tasks` and the declaration maps are gone, and so are the types `CellDecl`, `ResourceDecl`, `DerivationDecl`, `ListenerDecl`. A repeated name of one kind in a run is `invalid/duplicate`
+- State versions belong to cells: `ServeOptions.state` is gone; a cell's `version` (default 1) and `migrate(old, from)` replace it. A raised version migrates only that cell; a lowered one refuses the reload
+- A derivation is new at every reload (computed at the commit) instead of kept with its function replaced. A listener whose state source a reload replaced subscribes again and gets the current value again: listeners on state must reconcile. Listeners on state subscribe when they activate, so they get the value current then
+- `method(args?, result?)`: without arguments a method is called `ref.name(ctx?)` and implemented `(ctx) => …`; without a result it is void (callers get `undefined`). Descriptions record both by leaving `args`/`result` out (fingerprints of such methods change), `call` frames omit `args` and `result` frames `value` for them. Coverage requires both sides to agree on arguments; a void consumer accepts a result
+- Remote contracts declare where their objects live, and callers no longer name a host: `remote(name, { …, host: hostNamed("server") })` or `host: hostFamily("session:", "session")` (the host `session:` + the input's required string field `session`, checked by TypeScript). `host` is required on remote contracts; `GetOptions.at` is removed. A `get` normalizes the input, resolves the host, and acquires locally or over the link to it. `serve` refuses a type whose placement does not include the host (also at a reload), a host refuses a hold whose input its own contract places elsewhere (`invalid/placement`), and a relay refuses a hold whose target disagrees with its contract token. The placement is part of the description and fingerprint; coverage requires equal placements, and `accepts` adapters do not bridge placements. Remote references are addressed by type, normalized input and principal, without a host name. `PROTOCOL_VERSION` is 3 (remote tokens carry `host`; a hold's input is normalized). New exports: `hostNamed`, `hostFamily`, `Placement`, `PlacementFor`, `HostNamed`, `HostFamily`
+- `FacetApi` has a `signal` (below): code that builds a `FacetApi` by hand, for example to wrap `serve`, must pass it on
+- Principals are typed and supplied by the app: `createHost<P>`, `Host<P>`, `defineFacet<P>`, `FacetApi<P>`, `Serve<P>`, `Factory<C, P>`, `Self<P>`, `Ctx<P>`, `GetOptions<P>`, `RootOptions<P>`, `Route<P>`, `AcceptOptions<P>` and `PrincipalMatch<P>` take the app's principal type (default `unknown`), so factories, methods, listeners and tasks narrow on it without casts. Chord invents no principals any more: `createHost({ self })` (required) is the principal of the host's own code, replacing the built-in `hostPrincipal` (`{ host: true }`, removed); `connect(link, { principal })` (required) is what the parent's own requests act as, replacing `{ host: <parent name> }`; `Route.principal` is required, replacing the default `{ host: <host name> }`. `HostOptions.upstream` is `{ link, principal, ...LinkOptions }` (was a link, with `upstreamOptions`). The host's own principal is recognized by `principalKey`, not object identity. The `Principal` type is gone; `ConnectOptions` and `PrincipalPattern` are new
+- `serve(type, factory, { lifetime: "host" })` compiles only for a local type whose input has no required fields, and without `linger`; `serve` still refuses the rest at runtime. `ServeOptions` is a union of `ReferencedServeOptions` and `HostServeOptions`, and `serve` takes `ServeOptionsFor<C>`
+- An awaited reference has its state, local or remote. `ctx.get` and `host.get` are async: they resolve once the reference is live and every state member of its variant has its first snapshot, and reject with the activation error, `aborted` (the ctx aborted or its call settled; `host.get`'s `signal`) or `unavailable/ready_timeout` after `HostOptions.readyTimeout` (default 60000 ms), releasing only that reference. `host.hold` is the synchronous form (possibly `loading`) for UI runtimes; `ref.ready` stays. `self.get` stays synchronous: an object goes live only once its references are ready and hydrated, and the state it exposes or derives from (also forwarded from a remote reference held another way) has its values; activation and reload prepare wait at most `readyTimeout` (a reference cycle across hosts fails with a hint instead of hanging)
+- State members are typed `T` (was `T | undefined`) and `StateSource<T>` is `Readable<T>`. Reading state before the first hydration throws `not_ready`, outside the current variant `not_in_variant`, after the reference ended its end error. A remote reference is a union discriminated by `variant`: another variant's members are reachable only after narrowing. `MembersOf` is gone. A listener added before a member is readable gets its snapshot then (no `undefined` snapshot first)
+- A remote reference stays subscribed to its variant's state while held, with or without listeners (it no longer forgets its value when the last listener leaves). `GetOptions.state: false` makes a method-only reference: no state unless another reference to the object wants it, ready once live
+- `Shape.codeVersion` and the `shape` frame's `codeVersion` are gone
+- `PROTOCOL_VERSION` is 4: a `hold` implies the state of its variant (`state: false` opts out until `sub`; `unsub` stops it); the provider answers with units, a `shape` listing the members the consumer lacks (`state`) followed by their snapshots; `state` frames are addressed by hold and member (`hold`, `m`) with `as: "snap" | "reset" | "ops" | "error"` and `value` (absent: `undefined`); `sub`/`unsub` take a hold; `resync` asks for a member again; `again` marks a re-hold after a link loss; `origin` (replacing `client`) names the client connection a hold comes from
+
+### Added
+
+- `@earendil-works/chord/output`: `OutputBuffer`, which keeps a head or tail window of a stream at a cost proportional to each chunk, `Progress`, which paces commits of a changing value by their size, plus `boundOutput`, `sanitizeOutput`, `characterEnd`, `utf8ByteLength`, and the `OutputLimits`, `BoundedOutput`, `OutputSlice`, and `OutputSkip` types. Moved from `@earendil-works/pi-durable`, which now uses them from here.
+- Remote references to one object share one binding per host and key (type, normalized input identity, principal key, contract fingerprint): one hold, one stream per state member, calls over the same hold; every reference keeps its own status, observers and `release`. `HostOptions.linger` (`{ types: { [typeName]: ms }, cap }`, cap default 4) keeps a binding held and hydrated after its last reference is released, so a reference taken again meanwhile costs nothing on the link
+- Holds from clients carry an opaque `origin`: the id the accepting host gave the client connection, forwarded by relays and honored only from the parent link, so a host can tell client connections apart; a disconnect releases that client's holds at once
+- Flow control by units: the first unit of a new reference passes the window, so a `get` never waits behind other references' state; units for reloads and re-holds wait, built lazily from the current values; waiting ops are capped per link (`LinkOptions.pendingCap`, default four windows), beyond which the oldest streams become resets (a relay asks downstream with `resync`)
+- `StateOptions`, `EventOf`, `ValueOf` and `Lifetime` types
+- `self.state(name, schema, { init }, options?)`: a cell whose first value comes from its source. `init(ctx)` (may be async) runs once the object's resources are open and its references live, before the object goes live, so no method, listener, task or subscriber sees another value; a throw or an invalid value fails the activation. A reload keeps the cell without running `init`; a cell a reload adds runs it while the reload prepares (a failure refuses the reload). Until then the cell's `value` throws `not_ready`. `StateInit` type
+- Links are flow controlled end to end: peers acknowledge what they processed (`ack` frames, announced with `acks` in `hello`), and while a window of frames is unacknowledged (`window` in `LinkOptions`, default 256 KiB), state frames wait at the sender, coalesced per subscription, instead of queuing in front of call results. A stalled peer costs a bounded slot per subscription; a slot that outgrows it becomes a reset. Calls, results and control frames are never held back, so under load a result can arrive before state changes made before it
+- `maxCalls` in `AcceptOptions` limits the calls a peer may have in progress on a link; further ones are answered at once with `unavailable` (reason `too_many_calls`) and the link stays open
+- `FacetApi.signal` aborts once that run of the facet is no longer installed: a committed reload replaced or removed it, the reload that loaded it aborted, or the host closed. While a reload prepares, the installed and the candidate run are both live
+- `HostOptions.taskStopDeadline` (default 5000 ms) bounds how long a reload waits for aborted tasks before it starts their replacements
+- Links deflate call arguments, results and state snapshots whose JSON exceeds `PACK_THRESHOLD` (64K characters): over IPC as a base64 field, over WebSockets as a binary message. Relaying hosts forward the deflated bytes unread; the host that uses the payload inflates it. `webSocketLink(socket, { compress, acceptPacked })` (`WebSocketLinkOptions`) controls sending and accepting packed frames (servers should refuse them from untrusted clients), and `inflateMessage` turns a packed WebSocket message back into a text frame
+
+### Changed
+
+- `Link.send` returns the encoded frame's size as sent (deflated payloads count as sent) when the transport knows it (memory and WebSocket links); flow control counts these sizes, so links that return nothing (IPC, custom links) are not windowed
+- A reload starts an object's new tasks only after its aborted ones finished (at most `taskStopDeadline`, then anyway, reported); before, the old and the new run of a task worked side by side
+- When a reload forces the retirement of the previous code version, it first aborts the roots still running on it (their `ctx.signal`, reason `superseded`) and gives them up to 1 s to stop before it closes what only that code used; a call with such a ctx is `superseded`. Before, resources were closed under running roots, which were never told
+
+### Fixed
+
+- `nodeLoader` registers every facet's directory before importing any, so a facet that imports a file of a facet listed after it gets the same module copy as that facet; before, the load order could produce duplicates.
+- A link that is already closed when a host accepts or routes to it is no longer kept as a connection: before, a route that returned a dead link (a child process that exited before its link was wrapped) made every later call to that host name fail with `unavailable` until restart, and leaked the connection's ping timer.
+- Fixed `processLock()` failing with `listen EINVAL` on macOS and the BSDs when the temporary directory is too deep for a socket path (sun_path holds 104 bytes); the lock socket then lives in a private per-user directory, `/tmp/chord2-<uid>`
+- A child host whose hello arrived while a cluster reload ran was marked in step without taking part, so it stayed on the old code version and every call to it failed `superseded` until it reconnected. It is now synced or reconciled when the reload ends; a child already behind is fenced at once, so its roots' calls up are admitted meanwhile. A reconciliation that is running when a reload starts likewise syncs its child only after that reload, against the committed code version
+- A child host retired its previous code version as soon as a cluster reload's `prepare` arrived, before its parent did, so the parent's old roots got `superseded` on it. The coordinator now retires before it sends `prepare`, a child waits for its parent's `retire` (at most `retireDeadline`), and a child coming in step (or about to be reconciled) is told which code versions the parent retired before
+- Disposed objects stayed reachable from the host until an object with the same address was created again (every distinct guest, session or input leaked one object, its references and the code they bind)
+- References kept every code version's services, and with them the factory code of every reload, reachable for as long as they lived (held references, objects of lifetime `"host"`); old code generations could never be collected
+- Call, task and root contexts were linked to long-lived signals with `AbortSignal.any`; Node keeps such dependants reachable while they have abort listeners, so a listener on `ctx.signal` kept its closure (and its code generation) alive for the object's lifetime. Contexts now detach when they close
+- IPC links and the host manager's control channel wrote to a peer process that had exited without a callback, so the `EPIPE` Node reports for a write in the gap between the exit and `disconnect` (an `ack` sent just after a worker shut down) became an unhandled `error` event that crashed the process. The link now ends on a failed write (reason `ipc send failed: EPIPE`), and control messages to a gone peer are dropped
+- A relayed call ran under the origin's cancel signal only, so a forced retirement of the relaying host could not cancel it before closing the old code's resources; it now follows its root's signal
+- A resource kept across a reload closed with the `close` of the factory run that first opened it, and kept that run's code reachable; it now adopts the newest declaration at commit
+- `forkDriver` passed its own `CHORD2_LOCK` to forked children, so a child host that forked its own children made those without a lock of their own fail with `locked`
+- A call through a remote reference accepted a ctx from another host, or an object not made by Chord, and carried its root over the link; it now rejects it with `invalid/foreign_ctx` like a local reference ([#10959](https://github.com/earendil-works/pi/issues/10959))
+
+## [1.2.0] - 2026-10-12
+
+### Breaking Changes
+
+- Replaced the facet and service runtime with a typed host runtime: contracts (`local`, `remote`, `method`, `opaque`) are runtime values described with TypeBox schemas, objects are served by hosts (`createHost`, `defineFacet`, `defineRegistry`) and reached through handles, and hosts exchange JSON frames over memory, Node IPC, or WebSocket links (`memoryLinkPair`, `ipcLink`, `webSocketLink`, `acceptWebSockets`), with hot reload of plugins. See `docs/tutorial.md` and `docs/guide.md`
+- Removed `defineService`, `createFacetHost`, `createRemoteServiceBinding`, `createStaticFacetLoader`, `combineFacetLoaders`, the remote-service endpoint, provider, error, and wire helpers, and their types. The old `defineFacet`, `Facet`, and `FacetLoader` are replaced by the new runtime's names of the same spelling
+- Removed the `./bundler` export and the facet bundle loaders of `./node`; `./node` now exports the child host manager (`createHostManager`, `forkDriver`, `childControl`, `processLock`) and the facet module loader `nodeLoader`
+- Removed `@earendil-works/pi-client`, `@earendil-works/pi-protocol`, and `@earendil-works/pi-server`, which served only the old runtime; they are no longer released
+
+### Changed
+
+- `replicatedState`, `copyJson`, `isJsonValue`, `Context`, `JsonValue`, `JsonRepresentation`, `Draft`, and the replicated state types keep their names on the root export; `./context` and `./delta` are unchanged, and `./context` also exports the `Context` and `ContextKey` types
+- Depends on `typebox` instead of `esbuild`
+
+### Fixed
+
+- Fixed appending to an array costing a walk over the whole array: the delta tracker now plans inserts and removals that keep the remaining elements in order from the changed ranges alone, and `applyImmutable` builds an appended array in one copy instead of two. 32,000 one-item appends, one commit each, take 1.4 s instead of 11.3 s
+

package/README.md

@@ -1,108 +1,70 @@
 # @earendil-works/chord
 
-Chord is an application-composition runtime for systems assembled from
-plugins/extensions. It provides facets, services, replicated state, and a
-pluggable remote-service boundary. It is developed as a standalone package in
-the Pi monorepo, but it is not a Pi package: it does not depend on any other Pi
-workspace package and can be used by unrelated applications.
+Chord builds applications out of **objects** that live in several processes (a server, workers, browser tabs) and can be **hot reloaded** while they run.
 
-## What Chord is for
+- An **object** is state plus code at an address. It is created on demand and lives while someone references it.
+- Everyone gets a **reference**, never the object. References work the same locally and across processes, and survive reloads.
+- Every object knows its **principal**: an owner and a guest get different objects, with different methods.
+- **State** is observable JSON. Remote viewers get a snapshot followed by deltas.
+- **Hot reload** swaps code while it runs. Work in flight finishes on the code it started with, state is kept, and incompatible changes migrate at a safe point.
 
-A single application feature may need to run in several environments: for
-example, an agent worker, a terminal UI, and a remote WebUI.  Chord provides the
-generic machinery to write such extensions in a way that is both delightful for
-humans as well as agents.
+Contracts are runtime values described with [TypeBox](https://github.com/sinclairzx81/typebox) schemas. Hosts exchange JSON frames over links: in memory, a Node IPC channel, or a WebSocket.
 
-The design has a few connected pieces:
+## Entry points
 
-- **Plugins** are synchronous setup units that declare the services they provide
-  and require. After every plugin has declared its shape, a host validates the
-  complete dependency graph, binds services, activates providers before consumers,
-  and disposes resources in reverse dependency order.  These units are called
-  *facets*.
+| Import | Contents | Runs in |
+|--------|----------|---------|
+| `@earendil-works/chord` | Contracts (`local`, `remote`, `method`, `opaque`), declarations (through the factory's `self`: `state`, `derive`, `resource`, `on`, `task`), hosts (`createHost`, `defineFacet`, `defineRegistry`), links (`memoryLinkPair`, `ipcLink`, `webSocketLink`, `acceptWebSockets`), errors (`ChordError`, `isChordError`, `forbidden`, `invalid`). Also the shared base: `Context`, `JsonValue`, `JsonRepresentation`, `Draft`, `copyJson`, `isJsonValue`, and `replicatedState` with its types. | Node and browsers |
+| `@earendil-works/chord/node` | Child host processes: `createHostManager`, `forkDriver`, `childControl`, `processLock`; the facet module loader `nodeLoader`. | Node |
+| `@earendil-works/chord/context` | Explicit cancellation and invocation values: `BACKGROUND_CONTEXT`, `withCancel`, `withAbortSignal`, `withoutAbortSignal`, `withContextValue`, `awaitWithContext`. | Node and browsers |
+| `@earendil-works/chord/delta` | The transactional JSON tracker, structural diff, immutable apply, and the wire encoder/decoder for operation batches. | Node and browsers |
+| `@earendil-works/chord/output` | Bounded output streams and paced progress: `OutputBuffer` (head or tail window of a stream, `OutputLimits`, `OutputSkip`), `boundOutput`, `sanitizeOutput`, `utf8ByteLength`, and `Progress` (adaptive commits of a changing value). | Node and browsers |
 
-- **Facets** are parts of a plugin.  Each facet is bundled up separately and runs
-  in the process or environment where it's supposed to run.  You can use facets
-  to split a plugin into separate pieces that need to be loaded into different
-  processes and environments (think backend, browser, TUI etc.)
+## Quick start
 
-- **Services** are typed, stable tokens with either one provider (**singleton**)
-  or dynamic keyed instances (**keyed**).  A service can be process-local, with
-  an unrestricted JavaScript contract, or remotely exposable. Consumers retain a
-  stable facade while a provider disconnects or is replaced.
-
-- **Replicated state** exposes authoritative state to local and remote
-  connected consumers. Producers publish atomic overlay transactions with
-  `change(context, callback)`; consumers receive complete immutable values. Draft
-  proxies exist only during the callback and become unusable afterward. Preparation
-  materializes a structurally shared immutable candidate and one exact decoded
-  operation batch, while each remote client/state stream owns independent path-codec
-  state. Replicas become unready on disconnect or replacement until rehydrated.
-
-- **Delta tracking** records and coalesces operations over tracked plain JSON.
-  It preserves common string and array operations, supports durable base
-  batches, and validates untrusted operations as they are applied. Batches
-  guarantee convergence but are not canonical or necessarily minimal.
-
-- **Remote service sources** advertise services available outside a facet host
-  and open bindings for the services its facets require. Bindings carry logical
-  calls and subscriptions through an application-supplied adapter. Chord
-  requires strict-JSON arguments, results, snapshots, updates, and catalogues,
-  but does not prescribe framing, routing, transport, or an application wire
-  envelope. `JsonRepresentation<T>` derives a wire-safe type for application data
-  with unknown payloads, while `isJsonValue()` validates received values at an
-  adapter boundary. Symmetric RPC peers are planned as one optional
-  implementation of this boundary.
-
-- **Context** Chord provides a Go-like context system for cancellation and
-  invocation-scoped application values. Applications can carry permissions or
-  telemetry through those values without Chord depending on either.
-
-The current runtime exports service tokens, singleton and keyed providers,
-remote bindings, replicated state, facet hosts, and facet loaders from
-`@earendil-works/chord`. Import public types and general runtime APIs from the
-package root. Context constants and functions live in
-`@earendil-works/chord/context` because their generic names should not pollute
-the root API.
-Chord-owned identifiers use the `chord.*` namespace and its reserved service
-prefix is `$chord.*`.
-
-## Remote service adapters
+```ts
+import { Type } from "typebox";
+import { createHost, hostNamed, method, remote } from "@earendil-works/chord";
+
+// contract.ts: shared by provider and consumers
+export const Counter = remote("demo.counter", {
+	version: 1,
+	input: Type.Object({ name: Type.String() }),
+	host: hostNamed("server"), // where its objects live; callers never name a host
+	variants: {
+		default: {
+			state: { count: Type.Number() },
+			methods: { increment: method(Type.Object({ by: Type.Number() })) },
+		},
+	},
+});
 
-Chord owns its transport-independent service wire grammar. Consumer adapters
-use `createServiceCatalogueCall()`, `createServiceSubscribeCall()`, and
-`createServiceUnsubscribeCall()` for `$chord.service` control calls.
-`createRemoteServiceEndpoint()` handles those calls for one provider consumer,
-including subscription activation and cleanup. `parseServiceCall()`,
-`parseServiceCatalogue()`, and the decoded/wire snapshot and update parsers
-validate Chord semantics after an adapter has established a strict-JSON
-boundary. `RemoteServiceErrorCode` and `REMOTE_SERVICE_ERROR_CODES` define the
-service errors that may cross that boundary.
+const host = createHost({ name: "server", self: { kind: "server" } });
+
+host.serve(Counter, ({ name }, _principal, self) => {
+	const count = self.state("count", Type.Number(), 0);
+	return {
+		variant: "default",
+		count,
+		increment: async ({ by }, ctx) => {
+			count.change(ctx, (n) => n + by);
+		},
+	};
+});
 
-Replicated state operations use one `createServiceStateEncoder()` at the
-provider side and one `createServiceStateDecoder()` at the consumer side for
-each subscription. Those registries create an independent Delta path dictionary
-for every instance/member state and reset it on replacement, unavailability,
-close, or fresh hydration. Applications may place these values inside any
-routing, request, response, or event envelope; Chord does not prescribe that
-outer protocol.
+await host.root(async (ctx) => {
+	const clicks = await ctx.get(Counter, { name: "clicks" }); // ready, with its state; released when this root ends
+	clicks.count.subscribe((n) => console.log("count", n));
+	await clicks.increment({ by: 2 }, ctx); // logs 0, then 2
+});
+```
 
-Provider subscriptions atomically capture a snapshot and buffer subsequent
-updates until activation. Activation and reentrant publication use the same FIFO.
-The provider retains at most 100 pending updates per subscription, excluding the
-running delivery. Adding update 101 replaces the entire pending queue with
-`{ type: "reset", snapshot }`: a current full subscription snapshot whose state
-members contain `[["r", value]]` and their new sequence baselines. It also captures
-current instance membership, so discarded spawn/close/replacement events cannot
-leave stale instances behind. Live keyed generations retain their existing handles.
-The reset carries the context of the publication that triggered overflow.
+## Documentation
 
-Consumers and codecs must handle this explicit reset before accepting subsequent
-ordinary deltas. A root operation in an ordinary `state` update does **not** permit
-a sequence gap. Resets restart the subscription's path dictionaries, and later
-deltas must be contiguous from each reset baseline. Transport adapters must
-preserve snapshot/reset/update order; they must not drop encoded delta batches or
-assume their own asynchronous queues are bounded by the provider's queue.
+- [Tutorial](docs/tutorial.md): a shared todo list, built up section by section. Every example runs as `test/tutorial.test.ts`.
+- [Usage guide](docs/guide.md): API reference for contracts, objects, state, roots, lifetime, plugins, hot reload, hosts, and links.
+- [Specification](docs/spec.md): compatibility, lifetime, and reload semantics, plus known limitations and implementation decisions.
+- [Delta guide](src/delta/README.md): ownership, lifecycle, operation, and replica contracts of `@earendil-works/chord/delta`.
 
 ## Tracking JSON deltas
 
@@ -131,16 +93,19 @@ freezing. `track(initial)`, `prepareReplace(value)`, `replicatedState(initial)`,
 `replace(context, value)` take ownership of alias-free strict-JSON roots without
 walking them. Callers must not mutate transferred or published data. Values placed
 through drafts are already copied, so that walk also rejects non-strict JSON before
-the draft changes. Published values are not frozen. In-process loopback consumers
-may share their containers with the provider; mutating a consumed value violates
-the contract and can corrupt authority. Clone or serialize at any mutable trust
-boundary.
+the draft changes. Published values are not frozen. In-process consumers may share
+their containers with the provider; mutating a consumed value violates the contract
+and can corrupt authority. Clone or serialize at any mutable trust boundary.
 
-Replicated state provides the same model through a callback:
+Replicated state provides the same model through a callback. `replicatedState` is a
+standalone observable value, independent of hosts; Durable uses it for document,
+view, and task-graph states:
 
 ```ts
+import { replicatedState } from "@earendil-works/chord";
+
 const initial = { output: "", count: 0 };
-const status = env.replicatedState(initial); // transfers ownership of initial
+const status = replicatedState(initial); // transfers ownership of initial
 status.change(context, (draft) => {
 	draft.output += "done\n";
 	draft.count += 1;
@@ -148,11 +113,14 @@ status.change(context, (draft) => {
 ```
 
 A successful `change()` publishes exactly one atomic revision. If its callback
-throws, the original value and sequence remain unchanged. Draft handles become
-unusable when the callback returns. Chord emits string append and front-truncate
-operations, array splices and permutations, sets, and deletes; large edit sets may
-fold into a complete replacement. Remote connection plumbing encodes each batch
-independently for every client/state pairing.
+throws, the original value and sequence remain unchanged. Draft references become
+unusable when the callback returns. The tracker emits string append and
+front-truncate operations, array splices and permutations, sets, and deletes; large
+edit sets may fold into a complete replacement.
+
+`replicatedState(source, { onError })` instead attaches a publication-only state to
+an authoritative revision source (`ReplicatedStateSource`): it captures a snapshot,
+then publishes every committed frame in cursor order.
 
 ### Public state subscriptions
 
@@ -166,99 +134,15 @@ Each subscription retains at most 100 pending complete-value deliveries, excludi
 the running callback. On overflow, only the newest pending value, context, and
 delivery metadata are retained; a not-yet-started initial hydration is preserved.
 Thus public delivery sequences may skip. This is a frame-count policy, not a byte
-limit. Internal exact-operation subscriptions remain synchronous and receive every
-revision, independently of slow public callbacks.
+limit.
 
 The returned unsubscribe function immediately discards pending work and prevents
 new callbacks. It neither aborts nor waits for the running callback. Synchronous
 throws and promise rejections are observed, reported, and do not stop other
-subscriptions or subsequent callbacks. Attached sources and remote bindings use
-their `onError` handler; local mutable states (and attached sources without a
-handler) report failures by throwing in a microtask. Unsubscribing does not hide a
-later rejection from the running callback.
-
-The standalone [Delta guide](src/delta/README.md) defines the complete ownership,
-lifecycle, operation, and replica contracts.
-
-## Bundling and loading facets
-
-`@earendil-works/chord/bundler` uses esbuild to turn ESM or TypeScript application
-entries into independent, content-addressed CommonJS files. The package-level API
-reads plugin identity and build configuration from `package.json`, then applies
-facet path conventions supplied by the host application:
-
-```json
-{
-  "name": "@example/my-plugin",
-  "version": "1.0.0",
-  "type": "module",
-  "peerDependencies": {
-    "@earendil-works/chord": "^0.84.4"
-  },
-  "chord": {
-    "facets": {
-      "worker": "./src/custom-worker.ts",
-      "presentation": false
-    }
-  }
-}
-```
-
-```ts
-import { bundleFacetPackage } from "@earendil-works/chord/bundler";
-
-await bundleFacetPackage({
-	packagePath: "/path/to/my-plugin",
-	outdir: "/application-owned/plugin-builds/my-plugin",
-	defaultFacets: {
-		worker: "src/worker.ts",
-		presentation: "src/presentation.ts",
-	},
-});
-```
-
-Existing conventional files become entries unless `chord.facets` overrides or
-disables them. Peer dependencies are externalized and resolved against the host
-when loading. Chord never installs dependencies or runs package lifecycle
-scripts. `bundleFacets()` remains available as the lower-level API for callers
-that already have explicit plugin identity and entry mappings.
-
-The output directory contains one `.cjs` file per entry plus
-`chord-facets.json`. Load one application-selected entry through the Node-only
-loader:
-
-```ts
-import { createFacetBundleLoader } from "@earendil-works/chord/node";
-
-const loader = createFacetBundleLoader({
-	manifestPath: "/application-owned/plugin-builds/my-plugin/chord-facets.json",
-	entry: "worker",
-	resolveExternal: (specifier) => import.meta.resolve(specifier),
-});
-const loaded = await loader.load();
-```
-
-Each `load()` verifies SHA-256 integrity and compiles the CommonJS body directly
-with `node:vm` instead of putting the plugin into Node's CommonJS or ESM module
-cache. Externals are resolved by the host and loaded through a restricted
-`require`; esbuild lowers dynamic imports so they use the same path. Disposing a
-retired generation releases the loader's facet references, making its compiled
-code eligible for garbage collection once plugin-owned resources are also gone.
-
-For transport to another Node host, `readFacetBundleArtifact()` packages one
-verified manifest entry with its source, and `createFacetBundleArtifactLoader()`
-materializes fresh temporary generations while resolving externals against the
-receiving host.
-
-To reload, load a candidate, pass its facets to `FacetHost.reload()`, dispose the
-candidate on failure, and dispose the retired `LoadedFacets` only after a
-successful cutover. The host activates and validates the candidate while the
-currently active providers remain routed, then replaces each singleton directly
-without an unavailable interval. Stable service handles therefore do not become
-disconnected during an ordinary reload. Keyed instances
-remain incarnation-specific and replacements receive fresh generations. The
-bundler writes a complete temporary directory before replacing the previous
-output, so loaders do not observe partially built generations.
+subscriptions or subsequent callbacks. Attached sources use their `onError`
+handler; mutable states (and attached sources without a handler) report failures
+by throwing in a microtask. Unsubscribing does not hide a later rejection from the
+running callback.
 
-See [PLANNING.md](PLANNING.md) for the broader RPC and generation-loading
-architecture.
+Cells of Chord objects and their remote readables have their own subscription
+model; see [State](docs/guide.md#state) in the usage guide.

package/dist/cell.d.ts

@@ -0,0 +1,122 @@
+import type { TSchema } from "typebox";
+import { type Draft } from "./delta/index.ts";
+import { ChordError } from "./errors.ts";
+import type { Ctx, Readable, StateEvent } from "./types.ts";
+export interface SourceOptions {
+    readonly dev: boolean;
+    readonly report: (error: unknown) => void;
+}
+/** Checks that `ctx` may write an object's cells now; throws otherwise. */
+export type WriteGuard = (ctx: Ctx) => void;
+/** Fans out values and delta events; listener errors are reported, not thrown to the writer. */
+declare class Fanout<T> {
+    #private;
+    constructor(report: (error: unknown) => void);
+    subscribe(listener: (value: T) => void, current: T): () => void;
+    events(listener: (event: StateEvent<T>) => void, current: T): () => void;
+    /**
+     * Queues delivery to the listeners subscribed now. A listener that subscribes later already got this revision in
+     * its snapshot; one that unsubscribes before delivery is skipped.
+     */
+    emit(event: StateEvent<T>): void;
+}
+/**
+ * Whether a state source has its value (entry 8): a remote reference's member before its first snapshot has none, and
+ * neither has anything derived from or forwarding it. Sources without this symbol always have their value.
+ */
+export declare const HYDRATION: unique symbol;
+export interface Hydration {
+    readonly hydrated: boolean;
+    /** Resolves once hydrated; rejects if the source ends first. */
+    whenHydrated(): Promise<void>;
+}
+/** The hydration of a readable, or undefined for a source that always has its value. */
+export declare function hydrationOf(value: unknown): Hydration | undefined;
+/** The hydrations of `sources` that are not hydrated yet. */
+export declare const unhydrated: (sources: Iterable<unknown>) => Hydration[];
+/** An object-owned state source (cell or derivation). Writes recompute dependents atomically. */
+export declare abstract class Source<T> implements Readable<T> {
+    readonly key: string;
+    readonly seq: number;
+    readonly dependents: Set<Derived<unknown>>;
+    /** Schemas of remote state members currently exposing this source (checked per write in dev mode). */
+    schemas: readonly TSchema[];
+    protected readonly options: SourceOptions;
+    protected readonly fanout: Fanout<T>;
+    constructor(key: string, options: SourceOptions);
+    abstract get value(): T;
+    subscribe(listener: (value: T) => void): () => void;
+    events(listener: (event: StateEvent<T>) => void): () => void;
+    /** Per-write validation, dev mode only. */
+    validate(value: unknown): void;
+    protected ownSchemas(): readonly TSchema[];
+}
+/** A state cell holding any JSON value, validated against its schema at creation and (dev mode) on writes. */
+export declare class Cell<T> extends Source<T> {
+    #private;
+    /** Replaced at a reload commit that changes the schema (state-version bump). */
+    schema: TSchema;
+    /**
+     * `initial` is always validated against `schema`; ownership moves to the cell. Without `initial`, the cell has no
+     * value until `initialize` (a cell declared with `init`, filled before its object goes live).
+     */
+    constructor(key: string, schema: TSchema, initial: {
+        readonly value: T;
+    } | undefined, guard: WriteGuard, options: SourceOptions);
+    /** Sets the first value of a cell declared with `init` (validated; ownership moves to the cell). Publishes nothing. */
+    initialize(value: T): void;
+    protected ownSchemas(): readonly TSchema[];
+    get value(): T;
+    /**
+     * Mutates a draft (only mutated paths are published), or returns a new value (`n => n + 1`). A returned value is
+     * always validated against the schema. The draft is unusable after `fn` returns.
+     */
+    change(ctx: Ctx, fn: (draft: Draft<T>) => T): void;
+    change(ctx: Ctx, fn: (draft: Draft<T>) => void): void;
+    /**
+     * Replaces the whole value. Ownership of `value` moves to the cell: never mutate it afterwards.
+     *
+     * Subscribers get a structural diff (`diffRevisions`) when `diff` is true, or by default when the new value shares
+     * containers with the old one (a new immutable revision of the same state, e.g. mirrored from another store);
+     * otherwise a single `r` op. The resulting value is the same either way; only the ops differ.
+     */
+    replace(ctx: Ctx, value: T, options?: {
+        readonly diff?: boolean;
+    }): void;
+    /**
+     * Installs a migrated value and its schema (reload commit). The caller validated the value and the derivations
+     * over it against every schema that will apply, so nothing is checked here. Subscribers receive a reset.
+     */
+    reset(value: T, schema: TSchema): void;
+}
+export type Sources = readonly Readable<unknown>[];
+export type SourceValues<S extends Sources> = {
+    [K in keyof S]: S[K] extends Readable<infer T> ? T : never;
+};
+/**
+ * A synchronous derivation. Sources are object cells/derivations (recomputed atomically with the write) or other
+ * readables such as reference state members (recomputed when they publish). Subscribers receive diffs.
+ */
+export declare class Derived<T> extends Source<T> {
+    #private;
+    readonly sources: readonly Readable<unknown>[];
+    constructor(key: string, sources: Sources, fn: (...values: never[]) => unknown, options: SourceOptions);
+    get value(): T;
+    /** Hydrated once every source is (a derivation over a remote member waits for its snapshot). */
+    get [HYDRATION](): Hydration | undefined;
+    /**
+     * Computes the first value (or takes it from `precomputed`, a reload's validated dry run) and starts following
+     * the sources (at install, never inside a factory).
+     */
+    attach(precomputed?: ReadonlyMap<unknown, unknown>): void;
+    detach(): void;
+    compute(read: (source: Readable<unknown>) => unknown): T;
+    /** Recomputes and republishes, including dependents. Errors are reported (the source write already happened). */
+    refresh(): void;
+    install(next: T): void;
+}
+export declare const isSource: (value: unknown) => value is Cell<unknown> | Derived<unknown>;
+/** Thrown by placeholders used before activation finished. */
+export declare const notReady: (what: string) => ChordError;
+export {};
+//# sourceMappingURL=cell.d.ts.map

package/dist/cell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell.d.ts","sourceRoot":"","sources":["../src/cell.ts"],"names":[],"mappings":"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"}