@earendil-works/chord 0.0.0

package/README.md

@@ -0,0 +1,205 @@
+# @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.
+
+## What Chord is for
+
+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.
+
+The design has a few connected pieces:
+
+- **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*.
+
+- **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.)
+
+- **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 mutate the tracked `state` proxy and call
+  `publish(context)`; consumers receive complete immutable values. Chord flushes
+  one decoded operation batch per publication, while each remote client/state
+  stream owns independent path-codec state. Replicas become unready on disconnect
+  or replacement until they are rehydrated.
+
+- **Delta tracking** derives compact operations from tracked plain JSON at
+  flush time. It preserves string append/front-truncation and array-append
+  behavior without retaining mutation history, supports durable base batches,
+  and validates untrusted operations as they are applied.
+
+- **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
+
+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.
+
+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.
+
+## Tracking JSON deltas
+
+Import the standalone delta primitive from `@earendil-works/chord/delta`:
+
+```ts
+import { apply, track } from "@earendil-works/chord/delta";
+
+const changes = track({ output: "", count: 0 });
+changes.flush(); // opening base batch
+changes.state.output += "done\n";
+changes.state.count += 1;
+
+const ops = changes.flush();
+const replica = apply({ output: "", count: 0 }, ops);
+```
+
+The first flush is always a complete base batch. Later flushes contain path-based
+changes. `applyImmutable()` applies those batches while preserving prior replica
+revisions. `replicatedState(initial)` uses tracking directly:
+
+```ts
+const status = env.replicatedState({ output: "", count: 0 });
+status.state.output += "done\n";
+status.state.count += 1;
+status.publish(context);
+```
+
+`publish()` flushes once; remote connection plumbing encodes that operation batch
+independently for every client/state pairing. String assignments preserve pure
+appends and rolling-window movement as append and front-truncate operations;
+unrelated rewrites fall back to a set. Values inserted into tracked state become
+tracker-owned and must subsequently be mutated only through `state`. See the
+[Delta guide](src/delta/README.md) for mutation, array, lifecycle, and
+consumer-ownership rules.
+
+## 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 old
+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.
+
+See [PLANNING.md](PLANNING.md) for the broader RPC and generation-loading
+architecture.

package/dist/api.d.ts

@@ -0,0 +1,15 @@
+import type { Facet, FacetHost, FacetLoader, FacetOptions, MutableReplicatedState, RemoteServiceBinding, RemoteServiceBindingOptions, RemoteServiceContract, Service } from "./types.ts";
+/** Create an active host for one complete set of facets. */
+export declare function createFacetHost(options: FacetOptions): Promise<FacetHost>;
+export declare function createStaticFacetLoader(facets: readonly Facet[]): FacetLoader;
+export declare function combineFacetLoaders(loaders: readonly FacetLoader[]): FacetLoader;
+export declare function defineFacet(facet: Facet): Facet;
+export declare function defineService<T>(id: string, options: {
+    readonly local: true;
+}): Service<T>;
+export declare function defineService<T>(id: string, ...options: [RemoteServiceContract<T>] extends [never] ? readonly [options: never] : readonly [options?: {
+    readonly local?: false;
+}]): Service<T>;
+export declare function createRemoteServiceBinding(options: RemoteServiceBindingOptions): RemoteServiceBinding;
+export declare function replicatedState<T extends object>(initial: T): MutableReplicatedState<T>;
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACX,KAAK,EACL,SAAS,EACT,WAAW,EACX,YAAY,EAEZ,sBAAsB,EACtB,oBAAoB,EACpB,2BAA2B,EAC3B,qBAAqB,EACrB,OAAO,EACP,MAAM,YAAY,CAAC;AAEpB,4DAA4D;AAC5D,wBAAsB,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,CAAC,CAQ/E;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,WAAW,CAO7E;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,WAAW,CA0BhF;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAE/C;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAA;CAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAC5F,wBAAgB,aAAa,CAAC,CAAC,EAC9B,EAAE,EAAE,MAAM,EACV,GAAG,OAAO,EAAE,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GACnD,SAAS,CAAC,OAAO,EAAE,KAAK,CAAC,GACzB,SAAS,CAAC,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC,GAChD,OAAO,CAAC,CAAC,CAAC,CAAC;AAQd,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,2BAA2B,GAAG,oBAAoB,CAErG;AAED,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,sBAAsB,CAAC,CAAC,CAAC,CAEvF","sourcesContent":["import { FacetKernel } from \"./facets/host.ts\";\nimport { disposeLoadedFacets } from \"./facets/loader.ts\";\nimport { RemoteServiceBindingImpl } from \"./services/consumer.ts\";\nimport { MutableReplicatedStateImpl } from \"./services/state.ts\";\nimport type {\n\tFacet,\n\tFacetHost,\n\tFacetLoader,\n\tFacetOptions,\n\tLoadedFacets,\n\tMutableReplicatedState,\n\tRemoteServiceBinding,\n\tRemoteServiceBindingOptions,\n\tRemoteServiceContract,\n\tService,\n} from \"./types.ts\";\n\n/** Create an active host for one complete set of facets. */\nexport async function createFacetHost(options: FacetOptions): Promise<FacetHost> {\n\tconst kernel = new FacetKernel(options);\n\tawait kernel.activate();\n\treturn Object.freeze({\n\t\tservices: kernel.provider,\n\t\treload: (facets: readonly Facet[]) => kernel.reload(facets),\n\t\tdispose: () => kernel.dispose(),\n\t});\n}\n\nexport function createStaticFacetLoader(facets: readonly Facet[]): FacetLoader {\n\tconst loadedFacets = Object.freeze([...facets]);\n\treturn {\n\t\tasync load() {\n\t\t\treturn { facets: loadedFacets, async dispose() {} };\n\t\t},\n\t};\n}\n\nexport function combineFacetLoaders(loaders: readonly FacetLoader[]): FacetLoader {\n\treturn {\n\t\tasync load() {\n\t\t\tconst loaded: LoadedFacets[] = [];\n\t\t\ttry {\n\t\t\t\tfor (const loader of loaders) loaded.push(await loader.load());\n\t\t\t} catch (error) {\n\t\t\t\tconst cleanupErrors = await disposeLoadedFacets(loaded.reverse());\n\t\t\t\tif (cleanupErrors.length > 0) {\n\t\t\t\t\tthrow new AggregateError([error, ...cleanupErrors], \"Facet loading and cleanup failed\");\n\t\t\t\t}\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t\tlet disposed = false;\n\t\t\treturn {\n\t\t\t\tfacets: Object.freeze(loaded.flatMap(({ facets }) => facets)),\n\t\t\t\tasync dispose() {\n\t\t\t\t\tif (disposed) return;\n\t\t\t\t\tdisposed = true;\n\t\t\t\t\tconst errors = await disposeLoadedFacets([...loaded].reverse());\n\t\t\t\t\tif (errors.length === 1) throw errors[0];\n\t\t\t\t\tif (errors.length > 1) throw new AggregateError(errors, \"Failed to dispose loaded facets\");\n\t\t\t\t},\n\t\t\t};\n\t\t},\n\t};\n}\n\nexport function defineFacet(facet: Facet): Facet {\n\treturn facet;\n}\n\nexport function defineService<T>(id: string, options: { readonly local: true }): Service<T>;\nexport function defineService<T>(\n\tid: string,\n\t...options: [RemoteServiceContract<T>] extends [never]\n\t\t? readonly [options: never]\n\t\t: readonly [options?: { readonly local?: false }]\n): Service<T>;\nexport function defineService(id: string, options?: { readonly local?: boolean }): Service<unknown> {\n\tif (id.length === 0) throw new TypeError(\"Service ID must not be empty\");\n\t// TODO: check if the reserved namespace should be part of Chord.\n\tif (id.startsWith(\"$chord.\")) throw new TypeError(\"Service IDs beginning with $chord. are reserved\");\n\treturn Object.freeze({ id, local: options?.local ?? false });\n}\n\nexport function createRemoteServiceBinding(options: RemoteServiceBindingOptions): RemoteServiceBinding {\n\treturn new RemoteServiceBindingImpl(options);\n}\n\nexport function replicatedState<T extends object>(initial: T): MutableReplicatedState<T> {\n\treturn new MutableReplicatedStateImpl(initial);\n}\n"]}

package/dist/api.js

@@ -0,0 +1,72 @@
+import { FacetKernel } from "./facets/host.js";
+import { disposeLoadedFacets } from "./facets/loader.js";
+import { RemoteServiceBindingImpl } from "./services/consumer.js";
+import { MutableReplicatedStateImpl } from "./services/state.js";
+/** Create an active host for one complete set of facets. */
+export async function createFacetHost(options) {
+    const kernel = new FacetKernel(options);
+    await kernel.activate();
+    return Object.freeze({
+        services: kernel.provider,
+        reload: (facets) => kernel.reload(facets),
+        dispose: () => kernel.dispose(),
+    });
+}
+export function createStaticFacetLoader(facets) {
+    const loadedFacets = Object.freeze([...facets]);
+    return {
+        async load() {
+            return { facets: loadedFacets, async dispose() { } };
+        },
+    };
+}
+export function combineFacetLoaders(loaders) {
+    return {
+        async load() {
+            const loaded = [];
+            try {
+                for (const loader of loaders)
+                    loaded.push(await loader.load());
+            }
+            catch (error) {
+                const cleanupErrors = await disposeLoadedFacets(loaded.reverse());
+                if (cleanupErrors.length > 0) {
+                    throw new AggregateError([error, ...cleanupErrors], "Facet loading and cleanup failed");
+                }
+                throw error;
+            }
+            let disposed = false;
+            return {
+                facets: Object.freeze(loaded.flatMap(({ facets }) => facets)),
+                async dispose() {
+                    if (disposed)
+                        return;
+                    disposed = true;
+                    const errors = await disposeLoadedFacets([...loaded].reverse());
+                    if (errors.length === 1)
+                        throw errors[0];
+                    if (errors.length > 1)
+                        throw new AggregateError(errors, "Failed to dispose loaded facets");
+                },
+            };
+        },
+    };
+}
+export function defineFacet(facet) {
+    return facet;
+}
+export function defineService(id, options) {
+    if (id.length === 0)
+        throw new TypeError("Service ID must not be empty");
+    // TODO: check if the reserved namespace should be part of Chord.
+    if (id.startsWith("$chord."))
+        throw new TypeError("Service IDs beginning with $chord. are reserved");
+    return Object.freeze({ id, local: options?.local ?? false });
+}
+export function createRemoteServiceBinding(options) {
+    return new RemoteServiceBindingImpl(options);
+}
+export function replicatedState(initial) {
+    return new MutableReplicatedStateImpl(initial);
+}
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAcjE,4DAA4D;AAC5D,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,OAAqB,EAAsB;IAChF,MAAM,MAAM,GAAG,IAAI,WAAW,CAAC,OAAO,CAAC,CAAC;IACxC,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC;IACxB,OAAO,MAAM,CAAC,MAAM,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,MAAM,EAAE,CAAC,MAAwB,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;QAC3D,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE;KAC/B,CAAC,CAAC;AAAA,CACH;AAED,MAAM,UAAU,uBAAuB,CAAC,MAAwB,EAAe;IAC9E,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;IAChD,OAAO;QACN,KAAK,CAAC,IAAI,GAAG;YACZ,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,CAAC,OAAO,GAAG,EAAC,CAAC,EAAE,CAAC;QAAA,CACpD;KACD,CAAC;AAAA,CACF;AAED,MAAM,UAAU,mBAAmB,CAAC,OAA+B,EAAe;IACjF,OAAO;QACN,KAAK,CAAC,IAAI,GAAG;YACZ,MAAM,MAAM,GAAmB,EAAE,CAAC;YAClC,IAAI,CAAC;gBACJ,KAAK,MAAM,MAAM,IAAI,OAAO;oBAAE,MAAM,CAAC,IAAI,CAAC,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;YAChE,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAChB,MAAM,aAAa,GAAG,MAAM,mBAAmB,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;gBAClE,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBAC9B,MAAM,IAAI,cAAc,CAAC,CAAC,KAAK,EAAE,GAAG,aAAa,CAAC,EAAE,kCAAkC,CAAC,CAAC;gBACzF,CAAC;gBACD,MAAM,KAAK,CAAC;YACb,CAAC;YACD,IAAI,QAAQ,GAAG,KAAK,CAAC;YACrB,OAAO;gBACN,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC;gBAC7D,KAAK,CAAC,OAAO,GAAG;oBACf,IAAI,QAAQ;wBAAE,OAAO;oBACrB,QAAQ,GAAG,IAAI,CAAC;oBAChB,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;oBAChE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;wBAAE,MAAM,MAAM,CAAC,CAAC,CAAC,CAAC;oBACzC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;wBAAE,MAAM,IAAI,cAAc,CAAC,MAAM,EAAE,iCAAiC,CAAC,CAAC;gBAAA,CAC3F;aACD,CAAC;QAAA,CACF;KACD,CAAC;AAAA,CACF;AAED,MAAM,UAAU,WAAW,CAAC,KAAY,EAAS;IAChD,OAAO,KAAK,CAAC;AAAA,CACb;AASD,MAAM,UAAU,aAAa,CAAC,EAAU,EAAE,OAAsC,EAAoB;IACnG,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,8BAA8B,CAAC,CAAC;IACzE,iEAAiE;IACjE,IAAI,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,iDAAiD,CAAC,CAAC;IACrG,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,IAAI,KAAK,EAAE,CAAC,CAAC;AAAA,CAC7D;AAED,MAAM,UAAU,0BAA0B,CAAC,OAAoC,EAAwB;IACtG,OAAO,IAAI,wBAAwB,CAAC,OAAO,CAAC,CAAC;AAAA,CAC7C;AAED,MAAM,UAAU,eAAe,CAAmB,OAAU,EAA6B;IACxF,OAAO,IAAI,0BAA0B,CAAC,OAAO,CAAC,CAAC;AAAA,CAC/C","sourcesContent":["import { FacetKernel } from \"./facets/host.ts\";\nimport { disposeLoadedFacets } from \"./facets/loader.ts\";\nimport { RemoteServiceBindingImpl } from \"./services/consumer.ts\";\nimport { MutableReplicatedStateImpl } from \"./services/state.ts\";\nimport type {\n\tFacet,\n\tFacetHost,\n\tFacetLoader,\n\tFacetOptions,\n\tLoadedFacets,\n\tMutableReplicatedState,\n\tRemoteServiceBinding,\n\tRemoteServiceBindingOptions,\n\tRemoteServiceContract,\n\tService,\n} from \"./types.ts\";\n\n/** Create an active host for one complete set of facets. */\nexport async function createFacetHost(options: FacetOptions): Promise<FacetHost> {\n\tconst kernel = new FacetKernel(options);\n\tawait kernel.activate();\n\treturn Object.freeze({\n\t\tservices: kernel.provider,\n\t\treload: (facets: readonly Facet[]) => kernel.reload(facets),\n\t\tdispose: () => kernel.dispose(),\n\t});\n}\n\nexport function createStaticFacetLoader(facets: readonly Facet[]): FacetLoader {\n\tconst loadedFacets = Object.freeze([...facets]);\n\treturn {\n\t\tasync load() {\n\t\t\treturn { facets: loadedFacets, async dispose() {} };\n\t\t},\n\t};\n}\n\nexport function combineFacetLoaders(loaders: readonly FacetLoader[]): FacetLoader {\n\treturn {\n\t\tasync load() {\n\t\t\tconst loaded: LoadedFacets[] = [];\n\t\t\ttry {\n\t\t\t\tfor (const loader of loaders) loaded.push(await loader.load());\n\t\t\t} catch (error) {\n\t\t\t\tconst cleanupErrors = await disposeLoadedFacets(loaded.reverse());\n\t\t\t\tif (cleanupErrors.length > 0) {\n\t\t\t\t\tthrow new AggregateError([error, ...cleanupErrors], \"Facet loading and cleanup failed\");\n\t\t\t\t}\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t\tlet disposed = false;\n\t\t\treturn {\n\t\t\t\tfacets: Object.freeze(loaded.flatMap(({ facets }) => facets)),\n\t\t\t\tasync dispose() {\n\t\t\t\t\tif (disposed) return;\n\t\t\t\t\tdisposed = true;\n\t\t\t\t\tconst errors = await disposeLoadedFacets([...loaded].reverse());\n\t\t\t\t\tif (errors.length === 1) throw errors[0];\n\t\t\t\t\tif (errors.length > 1) throw new AggregateError(errors, \"Failed to dispose loaded facets\");\n\t\t\t\t},\n\t\t\t};\n\t\t},\n\t};\n}\n\nexport function defineFacet(facet: Facet): Facet {\n\treturn facet;\n}\n\nexport function defineService<T>(id: string, options: { readonly local: true }): Service<T>;\nexport function defineService<T>(\n\tid: string,\n\t...options: [RemoteServiceContract<T>] extends [never]\n\t\t? readonly [options: never]\n\t\t: readonly [options?: { readonly local?: false }]\n): Service<T>;\nexport function defineService(id: string, options?: { readonly local?: boolean }): Service<unknown> {\n\tif (id.length === 0) throw new TypeError(\"Service ID must not be empty\");\n\t// TODO: check if the reserved namespace should be part of Chord.\n\tif (id.startsWith(\"$chord.\")) throw new TypeError(\"Service IDs beginning with $chord. are reserved\");\n\treturn Object.freeze({ id, local: options?.local ?? false });\n}\n\nexport function createRemoteServiceBinding(options: RemoteServiceBindingOptions): RemoteServiceBinding {\n\treturn new RemoteServiceBindingImpl(options);\n}\n\nexport function replicatedState<T extends object>(initial: T): MutableReplicatedState<T> {\n\treturn new MutableReplicatedStateImpl(initial);\n}\n"]}

package/dist/bundler.d.ts

@@ -0,0 +1,6 @@
+export type { BundleFacetsOptions, BundleFacetsResult, FacetBundlePlatform, } from "./node/bundle.ts";
+export { bundleFacets } from "./node/bundle.ts";
+export type { FacetBundleEntry, FacetBundleManifest } from "./node/manifest.ts";
+export type { BundleFacetPackageOptions, BundleFacetPackageResult } from "./node/package.ts";
+export { bundleFacetPackage } from "./node/package.ts";
+//# sourceMappingURL=bundler.d.ts.map

package/dist/bundler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundler.d.ts","sourceRoot":"","sources":["../src/bundler.ts"],"names":[],"mappings":"AAAA,YAAY,EACX,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,YAAY,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAChF,YAAY,EAAE,yBAAyB,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAC7F,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC","sourcesContent":["export type {\n\tBundleFacetsOptions,\n\tBundleFacetsResult,\n\tFacetBundlePlatform,\n} from \"./node/bundle.ts\";\nexport { bundleFacets } from \"./node/bundle.ts\";\nexport type { FacetBundleEntry, FacetBundleManifest } from \"./node/manifest.ts\";\nexport type { BundleFacetPackageOptions, BundleFacetPackageResult } from \"./node/package.ts\";\nexport { bundleFacetPackage } from \"./node/package.ts\";\n"]}

package/dist/bundler.js

@@ -0,0 +1,3 @@
+export { bundleFacets } from "./node/bundle.js";
+export { bundleFacetPackage } from "./node/package.js";
+//# sourceMappingURL=bundler.js.map

package/dist/bundler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundler.js","sourceRoot":"","sources":["../src/bundler.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAGhD,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC","sourcesContent":["export type {\n\tBundleFacetsOptions,\n\tBundleFacetsResult,\n\tFacetBundlePlatform,\n} from \"./node/bundle.ts\";\nexport { bundleFacets } from \"./node/bundle.ts\";\nexport type { FacetBundleEntry, FacetBundleManifest } from \"./node/manifest.ts\";\nexport type { BundleFacetPackageOptions, BundleFacetPackageResult } from \"./node/package.ts\";\nexport { bundleFacetPackage } from \"./node/package.ts\";\n"]}

package/dist/context/index.d.ts

@@ -0,0 +1,24 @@
+import type { Context, ContextKey } from "../types.ts";
+export declare const BACKGROUND_CONTEXT: Context;
+export declare const TODO_CONTEXT: Context;
+export declare function createContextKey<T>(description: string): ContextKey<T>;
+/** Derive a context containing one additional or replaced value. */
+export declare function withContextValue<T>(key: ContextKey<T>, value: T, parent: Context): Context;
+/**
+ * Derive a context cancelled by either the parent signal or the supplied signal.
+ * The parent context remains unchanged.
+ */
+export declare function withAbortSignal(signal: AbortSignal, context: Context): Context;
+/** Derive a context retaining all values except caller cancellation. Intended for mandatory cleanup only. */
+export declare function withoutAbortSignal(context: Context): Context;
+/** Derive an independently cancellable child context. */
+export declare function withCancel(context: Context): {
+    readonly context: Context;
+    readonly cancel: (reason?: unknown) => void;
+};
+/**
+ * Observe a promise until it settles or the invocation is cancelled.
+ * Cancellation rejects only this waiter; it does not cancel the underlying promise.
+ */
+export declare function awaitWithContext<T>(promise: Promise<T>, context: Context): Promise<T>;
+//# sourceMappingURL=index.d.ts.map

package/dist/context/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAsDvD,eAAO,MAAM,kBAAkB,EAAE,OAA0D,CAAC;AAC5F,eAAO,MAAM,YAAY,EAAE,OAAoD,CAAC;AAEhF,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,CAEtE;AAED,oEAAoE;AACpE,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAE1F;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAI9E;AAED,6GAA6G;AAC7G,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAE5D;AAED,yDAAyD;AACzD,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG;IAC7C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CAC5C,CAMA;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAkBrF","sourcesContent":["import type { Context, ContextKey } from \"../types.ts\";\n\nconst ABORT_SIGNAL_CONTEXT_KEY: ContextKey<AbortSignal | undefined> = Object.freeze({\n\ttoken: Symbol(\"chord.abortSignal\"),\n});\n\nabstract class BaseContext implements Context {\n\tabstract value<T>(key: ContextKey<T>): T | undefined;\n\tabstract toString(): string;\n\n\tget abortSignal(): AbortSignal | undefined {\n\t\treturn this.value(ABORT_SIGNAL_CONTEXT_KEY);\n\t}\n}\n\nclass EmptyContext extends BaseContext {\n\treadonly #name: string;\n\n\tconstructor(name: string) {\n\t\tsuper();\n\t\tthis.#name = name;\n\t}\n\n\tvalue<T>(_key: ContextKey<T>): T | undefined {\n\t\treturn undefined;\n\t}\n\n\ttoString(): string {\n\t\treturn this.#name;\n\t}\n}\n\nclass ContextValue<T> extends BaseContext {\n\treadonly #parent: Context;\n\treadonly #key: ContextKey<T>;\n\treadonly #value: T;\n\n\tconstructor(parent: Context, key: ContextKey<T>, value: T) {\n\t\tsuper();\n\t\tthis.#parent = parent;\n\t\tthis.#key = key;\n\t\tthis.#value = value;\n\t}\n\n\tvalue<Value>(key: ContextKey<Value>): Value | undefined {\n\t\tif (key.token === this.#key.token) return this.#value as unknown as Value;\n\t\treturn this.#parent.value(key);\n\t}\n\n\ttoString(): string {\n\t\treturn `${this.#parent}.WithValue(${this.#key.token.description ?? \"anonymous\"})`;\n\t}\n}\n\nexport const BACKGROUND_CONTEXT: Context = new EmptyContext(\"[Context BACKGROUND_CONTEXT]\");\nexport const TODO_CONTEXT: Context = new EmptyContext(\"[Context TODO_CONTEXT]\");\n\nexport function createContextKey<T>(description: string): ContextKey<T> {\n\treturn Object.freeze({ token: Symbol(description) });\n}\n\n/** Derive a context containing one additional or replaced value. */\nexport function withContextValue<T>(key: ContextKey<T>, value: T, parent: Context): Context {\n\treturn new ContextValue(parent, key, value);\n}\n\n/**\n * Derive a context cancelled by either the parent signal or the supplied signal.\n * The parent context remains unchanged.\n */\nexport function withAbortSignal(signal: AbortSignal, context: Context): Context {\n\tconst parentSignal = context.abortSignal;\n\tconst combined = parentSignal === undefined ? signal : AbortSignal.any([parentSignal, signal]);\n\treturn withContextValue(ABORT_SIGNAL_CONTEXT_KEY, combined, context);\n}\n\n/** Derive a context retaining all values except caller cancellation. Intended for mandatory cleanup only. */\nexport function withoutAbortSignal(context: Context): Context {\n\treturn withContextValue(ABORT_SIGNAL_CONTEXT_KEY, undefined, context);\n}\n\n/** Derive an independently cancellable child context. */\nexport function withCancel(context: Context): {\n\treadonly context: Context;\n\treadonly cancel: (reason?: unknown) => void;\n} {\n\tconst controller = new AbortController();\n\treturn {\n\t\tcontext: withAbortSignal(controller.signal, context),\n\t\tcancel: (reason?: unknown) => controller.abort(reason),\n\t};\n}\n\n/**\n * Observe a promise until it settles or the invocation is cancelled.\n * Cancellation rejects only this waiter; it does not cancel the underlying promise.\n */\nexport function awaitWithContext<T>(promise: Promise<T>, context: Context): Promise<T> {\n\tconst signal = context.abortSignal;\n\tif (signal === undefined) return promise;\n\tif (signal.aborted) return Promise.reject(abortError(signal));\n\treturn new Promise<T>((resolve, reject) => {\n\t\tconst onAbort = (): void => reject(abortError(signal));\n\t\tsignal.addEventListener(\"abort\", onAbort, { once: true });\n\t\tvoid promise.then(\n\t\t\t(value) => {\n\t\t\t\tsignal.removeEventListener(\"abort\", onAbort);\n\t\t\t\tresolve(value);\n\t\t\t},\n\t\t\t(error: unknown) => {\n\t\t\t\tsignal.removeEventListener(\"abort\", onAbort);\n\t\t\t\treject(error);\n\t\t\t},\n\t\t);\n\t});\n}\n\nfunction abortError(signal: AbortSignal): Error {\n\tconst reason: unknown = signal.reason;\n\treturn reason instanceof Error ? reason : new DOMException(\"The operation was aborted\", \"AbortError\");\n}\n"]}

package/dist/context/index.js

@@ -0,0 +1,97 @@
+const ABORT_SIGNAL_CONTEXT_KEY = Object.freeze({
+    token: Symbol("chord.abortSignal"),
+});
+class BaseContext {
+    get abortSignal() {
+        return this.value(ABORT_SIGNAL_CONTEXT_KEY);
+    }
+}
+class EmptyContext extends BaseContext {
+    #name;
+    constructor(name) {
+        super();
+        this.#name = name;
+    }
+    value(_key) {
+        return undefined;
+    }
+    toString() {
+        return this.#name;
+    }
+}
+class ContextValue extends BaseContext {
+    #parent;
+    #key;
+    #value;
+    constructor(parent, key, value) {
+        super();
+        this.#parent = parent;
+        this.#key = key;
+        this.#value = value;
+    }
+    value(key) {
+        if (key.token === this.#key.token)
+            return this.#value;
+        return this.#parent.value(key);
+    }
+    toString() {
+        return `${this.#parent}.WithValue(${this.#key.token.description ?? "anonymous"})`;
+    }
+}
+export const BACKGROUND_CONTEXT = new EmptyContext("[Context BACKGROUND_CONTEXT]");
+export const TODO_CONTEXT = new EmptyContext("[Context TODO_CONTEXT]");
+export function createContextKey(description) {
+    return Object.freeze({ token: Symbol(description) });
+}
+/** Derive a context containing one additional or replaced value. */
+export function withContextValue(key, value, parent) {
+    return new ContextValue(parent, key, value);
+}
+/**
+ * Derive a context cancelled by either the parent signal or the supplied signal.
+ * The parent context remains unchanged.
+ */
+export function withAbortSignal(signal, context) {
+    const parentSignal = context.abortSignal;
+    const combined = parentSignal === undefined ? signal : AbortSignal.any([parentSignal, signal]);
+    return withContextValue(ABORT_SIGNAL_CONTEXT_KEY, combined, context);
+}
+/** Derive a context retaining all values except caller cancellation. Intended for mandatory cleanup only. */
+export function withoutAbortSignal(context) {
+    return withContextValue(ABORT_SIGNAL_CONTEXT_KEY, undefined, context);
+}
+/** Derive an independently cancellable child context. */
+export function withCancel(context) {
+    const controller = new AbortController();
+    return {
+        context: withAbortSignal(controller.signal, context),
+        cancel: (reason) => controller.abort(reason),
+    };
+}
+/**
+ * Observe a promise until it settles or the invocation is cancelled.
+ * Cancellation rejects only this waiter; it does not cancel the underlying promise.
+ */
+export function awaitWithContext(promise, context) {
+    const signal = context.abortSignal;
+    if (signal === undefined)
+        return promise;
+    if (signal.aborted)
+        return Promise.reject(abortError(signal));
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(abortError(signal));
+        signal.addEventListener("abort", onAbort, { once: true });
+        void promise.then((value) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+        });
+    });
+}
+function abortError(signal) {
+    const reason = signal.reason;
+    return reason instanceof Error ? reason : new DOMException("The operation was aborted", "AbortError");
+}
+//# sourceMappingURL=index.js.map

package/dist/context/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Context, ContextKey } from \"../types.ts\";\n\nconst ABORT_SIGNAL_CONTEXT_KEY: ContextKey<AbortSignal | undefined> = Object.freeze({\n\ttoken: Symbol(\"chord.abortSignal\"),\n});\n\nabstract class BaseContext implements Context {\n\tabstract value<T>(key: ContextKey<T>): T | undefined;\n\tabstract toString(): string;\n\n\tget abortSignal(): AbortSignal | undefined {\n\t\treturn this.value(ABORT_SIGNAL_CONTEXT_KEY);\n\t}\n}\n\nclass EmptyContext extends BaseContext {\n\treadonly #name: string;\n\n\tconstructor(name: string) {\n\t\tsuper();\n\t\tthis.#name = name;\n\t}\n\n\tvalue<T>(_key: ContextKey<T>): T | undefined {\n\t\treturn undefined;\n\t}\n\n\ttoString(): string {\n\t\treturn this.#name;\n\t}\n}\n\nclass ContextValue<T> extends BaseContext {\n\treadonly #parent: Context;\n\treadonly #key: ContextKey<T>;\n\treadonly #value: T;\n\n\tconstructor(parent: Context, key: ContextKey<T>, value: T) {\n\t\tsuper();\n\t\tthis.#parent = parent;\n\t\tthis.#key = key;\n\t\tthis.#value = value;\n\t}\n\n\tvalue<Value>(key: ContextKey<Value>): Value | undefined {\n\t\tif (key.token === this.#key.token) return this.#value as unknown as Value;\n\t\treturn this.#parent.value(key);\n\t}\n\n\ttoString(): string {\n\t\treturn `${this.#parent}.WithValue(${this.#key.token.description ?? \"anonymous\"})`;\n\t}\n}\n\nexport const BACKGROUND_CONTEXT: Context = new EmptyContext(\"[Context BACKGROUND_CONTEXT]\");\nexport const TODO_CONTEXT: Context = new EmptyContext(\"[Context TODO_CONTEXT]\");\n\nexport function createContextKey<T>(description: string): ContextKey<T> {\n\treturn Object.freeze({ token: Symbol(description) });\n}\n\n/** Derive a context containing one additional or replaced value. */\nexport function withContextValue<T>(key: ContextKey<T>, value: T, parent: Context): Context {\n\treturn new ContextValue(parent, key, value);\n}\n\n/**\n * Derive a context cancelled by either the parent signal or the supplied signal.\n * The parent context remains unchanged.\n */\nexport function withAbortSignal(signal: AbortSignal, context: Context): Context {\n\tconst parentSignal = context.abortSignal;\n\tconst combined = parentSignal === undefined ? signal : AbortSignal.any([parentSignal, signal]);\n\treturn withContextValue(ABORT_SIGNAL_CONTEXT_KEY, combined, context);\n}\n\n/** Derive a context retaining all values except caller cancellation. Intended for mandatory cleanup only. */\nexport function withoutAbortSignal(context: Context): Context {\n\treturn withContextValue(ABORT_SIGNAL_CONTEXT_KEY, undefined, context);\n}\n\n/** Derive an independently cancellable child context. */\nexport function withCancel(context: Context): {\n\treadonly context: Context;\n\treadonly cancel: (reason?: unknown) => void;\n} {\n\tconst controller = new AbortController();\n\treturn {\n\t\tcontext: withAbortSignal(controller.signal, context),\n\t\tcancel: (reason?: unknown) => controller.abort(reason),\n\t};\n}\n\n/**\n * Observe a promise until it settles or the invocation is cancelled.\n * Cancellation rejects only this waiter; it does not cancel the underlying promise.\n */\nexport function awaitWithContext<T>(promise: Promise<T>, context: Context): Promise<T> {\n\tconst signal = context.abortSignal;\n\tif (signal === undefined) return promise;\n\tif (signal.aborted) return Promise.reject(abortError(signal));\n\treturn new Promise<T>((resolve, reject) => {\n\t\tconst onAbort = (): void => reject(abortError(signal));\n\t\tsignal.addEventListener(\"abort\", onAbort, { once: true });\n\t\tvoid promise.then(\n\t\t\t(value) => {\n\t\t\t\tsignal.removeEventListener(\"abort\", onAbort);\n\t\t\t\tresolve(value);\n\t\t\t},\n\t\t\t(error: unknown) => {\n\t\t\t\tsignal.removeEventListener(\"abort\", onAbort);\n\t\t\t\treject(error);\n\t\t\t},\n\t\t);\n\t});\n}\n\nfunction abortError(signal: AbortSignal): Error {\n\tconst reason: unknown = signal.reason;\n\treturn reason instanceof Error ? reason : new DOMException(\"The operation was aborted\", \"AbortError\");\n}\n"]}

package/dist/delta/index.d.ts

@@ -0,0 +1,119 @@
+import type { JsonValue } from "../types.ts";
+export type { JsonValue } from "../types.ts";
+export type Seg = string | number;
+export type Path = readonly Seg[];
+export type NonEmptyPath = readonly [Seg, ...Seg[]];
+/** A path inline, or an id assigned by the encoder on second use. */
+export type PathRef<P extends Path = Path> = P | number;
+/**
+ * Tuples are the form — in memory, on the wire, on disk.
+ *
+ * `r` is the ONLY op that replaces a whole value. `s`/`d`/`a`/`t` cannot target
+ * the root: the type forbids it. `p` may, and only because a tracked value can
+ * itself be an array — but a `p` that replaces its entire target is normalised to
+ * `r`/`s` at flush time, so a root `p` is always a partial modification.
+ *
+ * `Op` knows nothing about the path dictionary. Interning, id references and
+ * omitted paths live in `WireOp` and exist only between `encode` and `decode`.
+ */
+export type Op = readonly ["r", JsonValue] | readonly ["s", NonEmptyPath, JsonValue] | readonly ["d", NonEmptyPath] | readonly ["a", NonEmptyPath, string] | readonly ["t", NonEmptyPath, number] | readonly ["p", Path, number, number, JsonValue[]];
+/**
+ * What crosses a boundary. Adds two compressions and nothing else:
+ *
+ *   ["#", id, path]    defines an id, emitted on a path's SECOND use
+ *   a numeric PathRef  references a previously defined id
+ *   a shortened tuple  reuses the previous op's path; arity disambiguates
+ *
+ * ["r", value] carries no path, so it encodes to itself — which is why isBase
+ * works unchanged on either vocabulary.
+ */
+export type WireOp = readonly ["r", JsonValue] | readonly ["s", PathRef<NonEmptyPath>, JsonValue] | readonly ["s", JsonValue] | readonly ["d", PathRef<NonEmptyPath>] | readonly ["d"] | readonly ["a", PathRef<NonEmptyPath>, string] | readonly ["a", string] | readonly ["t", PathRef<NonEmptyPath>, number] | readonly ["t", number] | readonly ["p", PathRef, number, number, JsonValue[]] | readonly ["p", number, number, JsonValue[]] | readonly ["#", number, Path];
+export declare const isReplace: (op: Op | WireOp) => boolean;
+/**
+ * A batch begins with a replacement. Flush guarantees `r` is at index 0 or absent,
+ * so this is exact rather than a heuristic.
+ */
+export declare const isBase: (ops: readonly (Op | WireOp)[]) => boolean;
+/**
+ * Longest suffix of `a` that is a prefix of `b`. Probes with indexOf and verifies
+ * exact substring equality, so the hot loops are native. A hand-written KMP is
+ * asymptotically equivalent and much slower in practice.
+ *
+ * Always correct: the returned n satisfies a.slice(a.length - n) === b.slice(0, n).
+ */
+export declare function overlap(a: string, b: string, scan: number, probe?: number, maxCandidates?: number): number;
+export interface TrackerOptions {
+    maxOverlapScan?: number;
+}
+export interface Tracker<T extends object> {
+    /**
+     * The tracked value. Mutate and read state only through this proxy. Values
+     * inserted into it are adopted: callers may retain read-only references, but
+     * must not mutate them outside this proxy.
+     */
+    state: T;
+    /** The untracked current value. Mutating it bypasses change tracking. */
+    readonly target: T;
+    flush(): Op[];
+    /** Make the next flush a complete base batch without changing the value. */
+    rebase(): void;
+    /** Accept pending mutations locally without emitting them. */
+    discard(): void;
+    readonly dirty: boolean;
+}
+export declare function track<T extends object>(root: T, options?: TrackerOptions): Tracker<T>;
+/**
+ * Segments that reach the prototype chain.
+ *
+ * `JSON.parse` is safe on its own — it makes `__proto__` an own property. What is
+ * not safe is `parent[key] = value`, which is exactly what an applier does, and
+ * paths are data: `["s", ["__proto__", "isAdmin"], true]` pollutes
+ * `Object.prototype` for the whole process.
+ *
+ * Ops arrive from a facet, a plugin compartment, or a tool whose details may echo
+ * model output, so none of it is trusted input.
+ */
+export declare const RESERVED_SEGMENTS: ReadonlySet<string>;
+export declare class UnsafePathError extends Error {
+    readonly segment: Seg;
+    constructor(segment: Seg);
+}
+/**
+ * Verb, arity and payload shape for a **decoded** op: paths inline, no `#`, no
+ * short forms. `apply` uses this.
+ *
+ * Validating `Op` against the wire grammar would be laxer than the type: a
+ * two-element `["s", value]` would pass, and `apply` would then read the value as
+ * a path. Each vocabulary gets the validator that matches it.
+ */
+export declare function assertValidOp(op: unknown): asserts op is Op;
+/** The same, for the wire grammar: ids and short forms are legal here. */
+export declare function assertValidWireOp(op: unknown): asserts op is WireOp;
+export declare function assertSafePath(path: Path): void;
+export declare class PathError extends Error {
+    readonly path: Path | number;
+    constructor(path: Path | number);
+}
+/**
+ * Apply ops to a plain mutable value. Returns the value, because `r` replaces it
+ * outright and cannot be done in place.
+ *
+ * Takes decoded ops. Path ids and omitted paths are a wire concern — run
+ * `decode` first if the ops came from a boundary.
+ */
+export declare function apply<T>(target: T | undefined, ops: readonly Op[]): T;
+/** Apply decoded operations without mutating the previous immutable value. */
+export declare function applyImmutable<T>(target: T | undefined, ops: readonly Op[]): T;
+export interface Encoder {
+    encode(ops: readonly Op[]): WireOp[];
+}
+/**
+ * Intern on SECOND use. A definition costs more than the path it replaces, so
+ * interning on first use loses on the many paths written exactly once.
+ */
+export declare function encoder(): Encoder;
+export interface Decoder {
+    decode(wire: readonly WireOp[]): Op[];
+}
+export declare function decoder(): Decoder;
+//# sourceMappingURL=index.d.ts.map