Chord Package
Overview
Path-routing coverage: this doc owns packages/chord/**. Route questions about the @earendil-works/chord package, its src/ APIs, docs/ guides/design notes, test/ examples/tests, package entrypoints, and build/test metadata here.
packages/chord is the monorepo package for Chord v2, an object runtime for apps split across hosts such as servers, workers, browser tabs, and terminal clients. packages/…/package.json publishes the root @earendil-works/chord entry plus subpaths for portable kernel APIs (/context, /delta, /watch, /output, /sqlite, /sync), Node components (/http, /workers, /plugins, /app, /surfaces, /tui/launcher), browser/TUI/client bindings (/web, /react, /tui), and telemetry (/telemetry-sqlite, /telemetry-ingest). Optional peers are intentionally isolated by subpath: esbuild for plugins/surfaces/workers, ws for HTTP/TUI launcher, and react for React bindings.
The package root packages/…/index.ts re-exports the app-facing runtime: contracts, data/errors, documents, hosts/facets, jobs, links, registries, state helpers, store APIs, surface primitives, and telemetry schema. It also exposes a few store/document internals for adapters and sync (OwnerTable, StoreOwnerTables, document engine reads/writes, applyBatch), so changes to store internals can affect external adapter users even when they are marked internal. The README at packages/…/README.md is the public map of all entrypoints and includes quick-start code for defining a local contract, a facet, a host, and a live reference.
The portable runtime centers on contracts and hosts. packages/…/README.md describes object type declarations: local and remote contracts, hostKind addresses, schema helpers from @earendil-works/pi-schema, evolve, accepts, event members, keyed members, named queries, and memberNames. packages/…/README.md is the main operational spec for createHost, defineFacet, host.load, host.reload, host.hold/get, host.accept/connect/route, references, admission, routines, registries, stores, revocation, reload old-work handling, and onError. Objects are declared synchronously by facets; Chord activates them, follows dependencies, opens natives, and keeps references hydrated across local or remote links.
Remote communication is implemented under packages/chord/src/remote/, with packages/…/README.md documenting provider/consumer sides of a host link, relayed holds, origins, call/state/event windows, part limits, compression, revocation propagation, and how RemoteObject/Replica share one wire hold for compatible references. Link adapters and codecs live under packages/chord/src/link/ and are exported through packages/…/index.ts (memoryLinkPair, ipcLink, webSocketLink, binary/text codecs, part limits, compression). Watchable state is provided by packages/…/watch.ts: JSON Watch handles carry value frames with delta ops and recoverable failure calls, while NativeWatch handles in-process values without ops.
Durable state is layered through documents, Delta, and the store. packages/…/index.ts exports document definitions/handles/transactions for object-owned JSON state. packages/…/README.md documents the transactional JSON tracker and immutable replica rules used by watches and remote state; its biggest contract is ownership-based immutability rather than freezing. packages/…/README.md documents openStore, table definitions/evolution, query builders, live queries, named reads/lists/column sets, export/import, outbox, and adapter surfaces. SQLite portability is split between packages/…/index.ts, Node's node:sqlite adapter in packages/…/node.ts, and the structural Cloudflare Durable Object adapter in packages/…/cloudflare.ts.
Node-side integration components are in packages/chord/src/node/. packages/…/README.md documents createHttp, the Http and Authenticators registries, fetch-compatible request handling, route/wrap/socket contributions, security baseline, signed cookies, WebSocket links, and the Node listener/mounting adapter. packages/…/README.md documents createWorkers, one forked worker process per host address, bundled worker bases, route ownership, idle stopping, rollout steps, process locks, and worker-side workerMain. packages/…/README.md documents plugin discovery, esbuild builds, API/kind import rules, CSS modules/assets, VM evaluation, runtime loading/reloading, installs, watch marks, and testPlugin. packages/…/README.md documents the opinionated app kit (startServer, startWorker): data-directory layout, stores, HTTP, plugin roots, workers, sign-ins, owner links, pairing, files, export/import, base-build tracking, and web/TUI surface wiring.
Client surfaces are split between shared surface contracts and runtime bindings. packages/…/README.md documents script-set objects (WebScripts, TuiScripts), registered facet scripts, loaded-facet reconciliation, the reconnecting client loop, theme and language registries/preferences, and variant narrowing. Browser-side startPage lives under packages/chord/src/web/ and is documented in packages/…/README.md; it connects a client host over WebSocket, evaluates plugin scripts through the page bootstrap, follows themes/language, swaps plugin stylesheets, and optionally records page telemetry. packages/…/README.md documents optional React hooks (HostProvider, useHold, useWatch, useRegistry, useRefState, useVariant, useEvents, useMessages, usePageState). The terminal sandbox-side runtime is under packages/chord/src/tui/ and documented in packages/…/README.md; the trusted launcher is the Node subpath packages/chord/src/node/tui/.
Telemetry and sync are package-level support layers. packages/…/index.ts defines explicit invocation Context values carrying cancellation, typed values, and telemetry spans without ambient state. packages/…/index.ts implements a buffered SQLite TelemetryContext/TelemetryStore that flushes settled spans and 10-second metric intervals, supports ingest, and never closes the database it is given. packages/…/index.ts exports the page/worker telemetry recorder, batch contracts, ingest facet, and senders. packages/…/index.ts exports experimental store-outbox session sync: upload, pull, fold, remote/state interfaces, and directory-backed implementations.
Package docs are part of the module. packages/…/design.md is the authoritative target design for Chord v2 and is mirrored into source READMEs; packages/…/decisions.md and packages/…/slices.md track decision history and build slices. User-facing guides include packages/…/book.md, packages/…/plugin-authoring.md, and topic books for tutorials, store, theming, i18n, HTTP/workers, durable observers, dependencies, and flow control. Runnable references live in packages/chord/test/examples/ and cover the runtime progressively, from 01-objects.ts through plugins, HTTP, workers, app kit, web/TUI, telemetry, admission, named queries, lists, joins, and worker reports. The Vitest setup in packages/…/vitest.config.ts resolves workspace packages through the source condition; spawned processes and bundles still require built workspace packages.
Coupling
- If packages/…/package.json exports change, update both packages/…/README.md's entrypoint table and the corresponding src/…/index.ts or src/…/index.ts barrel. Consumers rely on package subpaths such as
/workers/child,/plugins/runtime,/sqlite/node, and/telemetry-sqlite/nodeto avoid loading optional peer dependencies. - If contract fingerprinting, schema normal form, member ordering, method/event encoding, or
NORMAL_FORM_VERSIONchanges inpackages/chord/src/contracts/, verifypackages/chord/src/remote/and stored compatibility tests underpackages/chord/test/schema/. Link bindings and accepted-version mappings use contract fingerprints and member indexes; a drift can make old consumers wait withcontract_mismatchor decode the wrong member. - If watch or Delta delivery semantics change in packages/…/watch.ts or
packages/chord/src/delta/, verifypackages/chord/src/remote/, packages/…/reference-source.ts, and store live-query paths. Remote state flow assumes one orderedWatchCallstream with foldedPendingOps, recoverable failure calls, and root replacements after overflow. - If store query planning or table write metadata changes in
packages/chord/src/store/, verify host live-query/named-query code in packages/…/query-reader.ts, packages/…/list.ts, and packages/…/named-query.ts. The host decides whether objects wake, park, or publish state based on store read refreshes and skip/probe behavior. - If worker exit or route-link handling changes in
packages/chord/src/node/workers/, verify packages/…/store.ts settling behavior and packages/…/route.ts.createWorkersrequires the server host's store so a worker's link is closed and queued commits settle before the exit is published. - If plugin build/evaluation rules change in
packages/chord/src/node/plugins/, update packages/…/plugin-authoring.md and examples underpackages/chord/test/examples/35-plugins/,37-plugin-imports/,49-plugin-api/,50-plugin-imports/, and52-test-plugin/. The docs are the contract plugin authors use for import boundaries, API versions, CSS modules, and failure behavior. - If surface script loading changes in
packages/chord/src/surfaces/,packages/chord/src/web/, orpackages/chord/src/tui/, verifypackages/chord/src/node/surfaces/and the app kit's web/TUI wiring in packages/…/README.md. Server-side script sets, client-sideLoadedFacets, base hashes, and plugin stylesheet/script URLs must stay in lockstep. - If HTTP authentication/admission behavior changes in
packages/chord/src/node/http/, verify the app kit sign-in, owner-link, pairing, and ephemeral-session code underpackages/chord/src/node/app/. The kit depends oncreateHttp's deny-by-default links endpoint, signed cookies,links.opened, andHttpRequest.remoteAddressfor pairing limits. - If telemetry schemas or batching change in packages/…/telemetry.ts,
packages/chord/src/telemetry-ingest/, orpackages/chord/src/telemetry-sqlite/, verify packages/…/README.md telemetry sections and the telemetry examples/tests. Page and worker ingest assumes bounded batches, server-side stamping/admission, and SQLite storage that ingests without overwriting existing spans.
Risks
- packages/…/README.md and packages/…/watch.ts: immutable JSON is enforced by ownership convention, not freezing. If code mutates a published revision, watch value, op payload, or immutable replay result, state can silently corrupt and remote replicas can diverge.
- packages/…/README.md documents a known styling limitation: plugin stylesheets are retired a frame after client reload, while object-contributed UI can remain on old object code until its successor is live. If a plugin contributes UI from objects rather than facets, a reload can temporarily show unstyled old UI; packages/…/styles.test.ts is noted as keeping this visible.
- packages/…/README.md documents an unresolved cross-host cycle gap: activation chains detect many cycles, but a ring across hosts whose objects start simultaneously can park until
readyTimeoutand only reportparked_long. If new dependency patterns add mutualself.get/route waits, verify they fail or report instead of silently parking. - packages/…/README.md warns device-pairing limits use
HttpRequest.remoteAddress. Behind a tunnel or relay, many remote clients can share one address, so hittinglimits.pairingsPerAddresscan block anonymous pairing for all of them for up to 10 minutes.