pi-mono/packages/chord/CHANGELOG.md

Changelog

[Unreleased]

Breaking Changes

• traceIn(options, fn, context) takes the context last (was traceIn(context, options, fn)), like the rest of the API.
• Watch listeners take one change object before the context: WatchHandle.start((change, context) => …) with change: WatchChange<T> = { value, ops, retired }, and NativeWatchHandle.start(({ value }, context) => …) with NativeWatchChange<T>. A change is plain data, those fields only; the frame's context is the second argument. Watch.advance(change, context) takes the same object, and a frame delivered alone, with nothing folded into it, reaches the listener as the object the source passed. Migration: start(async (value, ops, ctx) => …) becomes start(async ({ value, ops }, ctx) => …), start(async (value, ctx) => …) on a native watch start(async ({ value }, ctx) => …), and advance(value, ops, ctx) becomes advance({ value, ops, retired: false }, ctx).
• SqliteExecutor.runCounted(sql, ...params) runs one statement like run and resolves with the rows it inserted, updated or deleted, as SQLite's changes() counts them (index writes and rows changed by triggers do not count). The Node driver takes it from node:sqlite; the Durable Object driver reads SELECT changes() after the statement (the cursor's rowsWritten also counts index writes), so run stays as cheap as before. Migration: custom SqliteDatabase and SqliteExecutor implementations add runCounted.
• Retirement is a flag, not an end: WatchEnd loses retired, and Watch.retire(context) is removed. A source reports a retirement with advance({ value, ops, retired: true }, context), whose value is what the address shows after it, and the watch goes on: the next call has retired: true, folded with every other pending frame, so a document created at the address afterwards arrives in the same or a later call as [["r", value]]. endAfterDelivery() tells a watch its source sends nothing more: it takes no more frames, delivers what is pending, and ends ended after its last call returned, at once when nothing is pending and no call runs; it stays attached until then, so the source's end() (such as at its close), stop(), cancellation, or a throwing listener still end it first. Migration: a listener that waited for closed to give retired or tested for a null value tests change.retired; a source that called retire(ctx) calls advance({ value, ops, retired: true }, ctx), then endAfterDelivery() when its owner ends with the retirement.
• Watch listeners get a tagged call, and a watch stays open through a failure its source recovers from: WatchCall<T> is { kind: "value", value, ops, retired } or { kind: "failed", error }, and NativeWatchCall<T> is { kind: "value", value } or { kind: "failed", error } (replacing WatchChange<T> and NativeWatchChange<T>). After a failed call watch.value keeps the last value and the next value arrives as [["r", value]]; while the listener is busy, a failure drops the pending values (value then failed folds into the failure) and a value replaces a pending failure (failed then value folds into the value, as r). Watch.advance(call, context) takes a WatchCall, a value call delivered alone still reaches the listener as the object the source passed (no allocation), and Watch.fail(error, context) and NativeWatch.fail(error, context) send a failure. Migration: start(async ({ value, ops }, ctx) => …) becomes start(async (call, ctx) => { if (call.kind === "failed") return; const { value, ops } = call; … }), a native start(async ({ value }, ctx) => …) likewise; advance({ value, ops, retired }, ctx) becomes advance({ kind: "value", value, ops, retired }, ctx).
• WatchEnd is tagged by kind instead of reason, and a watch whose acquisition context is aborted ends aborted instead of cancelled: { kind: "stopped" | "aborted" | "ended" }, { kind: "listener_error", error }, or { kind: "failed", error } (a final failure only). Watch.cancel() is abort(), observeCancellation(signal) is observeAbort(signal), and end(failure?) takes the end: end({ kind: "ended" }) or end({ kind: "failed", error }). Migration: end.reason === "cancelled" becomes end.kind === "aborted", every other end.reason becomes end.kind; watch.end() becomes watch.end({ kind: "ended" }), watch.end({ error }) becomes watch.end({ kind: "failed", error }).

Added

• Chord v2 has a package export again, @earendil-works/chord/next (experimental): every layer's API for apps (contracts, data, documents, hosts, jobs, links, state, the store), and, marked internal, the store's surface for adapters (StoreOwnerTables, OwnerTable, the documents engine's reads and writes, the commit step, applyBatch). v2's store gains one id allocator for every id in it, claims per table and per document namespace, Durable's Storage semantics for a refused commit (it rejects that commit only; an unknown outcome stops the store), document histories none, latest and rewindable with reads at a point, archives carrying document revisions, and batch apply; v2 objects gain self.follow (another runtime's synchronous observers as sources) and persisted jobs (persist: { resume }, a stored abort(id, ctx), deferred state changes).
• Chord v2, experimental and not exported yet: the next object runtime in src/next (contracts, hosts and objects, documents, derives, links and relays, routines and jobs, the store), with its tests and runnable examples in test/next and its design in docs/next (design.md, the decision log decisions.md, the slice plan slices.md). Its API changes with every slice until it gets an entry point.
• NativeWatchable<T>: an in-process value that changes and can be watched (value, watch(context) returning a NativeWatchHandle<T>), the in-process counterpart of Watchable<T>.
• WatchHandle<T> and WatchEnd, the one watch API, moved from Durable: a serialized observation with value, start(listener), stop(), and closed; the listener gets a WatchChange<T> ({ value, ops, retired }) and the context. WatchEnd reasons are stopped, cancelled, ended, listener_error, and failed.
• Watch<T>, the one watch handle implementation, moved from Durable: a source creates one per watch and feeds it with advance(change, context) (retired: true for a retirement), end() or end({ error }), endAfterDelivery(), and observeCancellation(signal). Frames that arrive while the listener runs (or before start) are delivered in one call with the newest value, their ops folded by PendingOps and the newest frame's context; past 10,000 pending ops after folding, the call gets one root replacement [["r", newest]] instead (replaces the collapse after 100 undelivered frames); termination drops the listener and every reference into the source.
• Watchable<T>: a value that changes and can be watched (value, watch(context) returning a WatchHandle<T>), the common interface of documents, derives and other observable values.
• NativeWatchHandle<T> and its implementation NativeWatch<T>: the same lifecycle for in-process values, with listener ({ value }, context) (NativeWatchChange<T>) and no ops: one call per value in order, and past 100 pending values one call with the value of the optional replace() or the newest value.
• PendingOps and PendingTake in @earendil-works/chord/delta: the pending ops of one slow consumer, kept raw and folded while they wait (appends to one path join, a primitive set replaces earlier leaf ops on its path, r drops everything before it); size counts the pending ops after folding; take() empties the queue and hands over the folded ops, or replace past 10,000 pending ops. Received batches and op tuples are never mutated.
• ownedSlice(text, start, end?) in @earendil-works/chord/delta: a slice of a string that does not keep the whole string alive (#9265)
• appendText(draft, key, text) in @earendil-works/chord/delta: append to a string in a draft at O(text) cost, recorded as an append op without comparing the old and new strings (a plain draft[key] += text makes prepare() read the whole string, O(length) per change); StringKeys<T> names the keys it accepts (#9265)

Changed

• The delta tracker keeps its one open change in a plain field and needs a WeakRef only for a second change open at the same time (one per change before). A WeakRef target survives the scavenges of its job, so a run of changes in one job promoted every change's overlay to old space: 200,000 small changes in one job now promote 2 MB instead of 47.5 MB and take 3.1 µs each instead of 3.8 µs (3.0 instead of 3.5 µs when they span jobs). A draft dropped without prepare() or abort() now stays referenced by its tracker until the tracker's next beginChange() or adopt().
• applyImmutable(), applyImmutableBatches() and tracker revisions copy each container on a changed path with spread (or Object.assign() onto a null-prototype object) instead of one Object.defineProperty() per key, about 25 times faster per container (#9265)

Fixed

• The Node SQLite driver keeps the 256 most recently used prepared statements per connection instead of every statement it ever prepared, so callers generating SQL of unbounded shapes (a query builder) no longer grow memory without bound.
• Fixed append ops from the delta tracker and diffRevisions() keeping the whole string they were cut from alive (V8 represents a slice as a view of its source), so a delta chain, a watch backlog or a replica built from appends to a growing text held one copy of the text per commit (#9265)

[1.4.0] - 2026-10-21

Breaking Changes

• Custom Context implementations must provide telemetry: TelemetrySpan; use the no-op span NOOP_TELEMETRY_CONTEXT when disabled. withTelemetry() accepts spans, not adapters.

Added

• @earendil-works/chord/telemetry-sqlite: portable SQLite telemetry recording with bounded settled-span queues, ten-second metric aggregates, periodic flushes, and retention cleanup.
• Context.telemetry is an explicit, non-optional telemetry parent (no-op by default). withTelemetry(telemetry, context) derives it without changing values or cancellation; traceIn(context, options, fn) starts a child span and passes its derived context to the callback.
• @earendil-works/chord/sqlite: portable SQLite interfaces, atomic migration runner, and schema-prefix validation, with Node (/sqlite/node) and Cloudflare Durable Object (/sqlite/cloudflare) drivers. Moved from Durable, which keeps its storage implementations and re-exports the moved public names.
• @earendil-works/chord/output: Progress takes an optional ProgressClock (now, setTimer) to pace commits on, by default Date.now and setTimeout.

[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 gets 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)

[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