@earendil-works/chord 1.5.0 → 1.5.1

package/dist/host/readiness.js

@@ -0,0 +1,134 @@
+// A restart's readiness (decision "Reload restarts every affected object; old work finishes on old code", rule 3):
+// the requests its new factory made in staging, bound once every fate of the reload started (every served type is the
+// new one then), and held until the successor's own requests bound. The old attempt is sealed only once they are
+// ready, so old work that reaches the object meanwhile still finds its old attempt open.
+import { withAbortSignal } from "../context/index.js";
+import { asChordError, checkParams, waitingFor } from "../data/internal.js";
+/**
+ * One restart's readiness: ready once each recorded type request is live (an open old instance that binds its version
+ * counts) or failed for a reason other than another host's version skew (which heals by itself), or at its bound.
+ * Registry requests are served by facets in the commit and kept by the old attempt's contributions until its seal: it
+ * does not wait for them. Its failure follows the requests: `shows` gets each change of it.
+ */
+export class Readiness {
+    #host;
+    #caller;
+    #requests;
+    #shows;
+    #context;
+    #bindings = [];
+    #started = Promise.withResolvers();
+    /** Ends the waits on its bindings at its release. */
+    #abort = new AbortController();
+    /** A request refused for good at the start (an authority, a host address): it heals with no change of a binding. */
+    #refused;
+    /** The failed request's cause `shows` got last (`from`), as the successor waits for it (`waiting`). */
+    #failed;
+    constructor(host, caller, requests, shows, context) {
+        this.#host = host;
+        this.#caller = caller;
+        this.#requests = requests;
+        this.#shows = shows;
+        this.#context = context;
+    }
+    /** What the successor waits for now: a request refused for good, or `waiting` for the first failed one. */
+    get cause() {
+        return this.#refused ?? this.#failed?.waiting;
+    }
+    /**
+     * Binds the recorded type requests as the object's own would be (once every fate of the reload started), kept out
+     * of presence lists (they are no consumers of their own), and follows them: `shows` gets each change of `cause`.
+     */
+    start() {
+        const following = withAbortSignal(this.#abort.signal, this.#context);
+        for (const request of this.#requests) {
+            if (request.kind !== "type")
+                continue;
+            const { contract, params } = request;
+            const binding = this.#host.reference(contract, undefined, this.#caller, {});
+            binding.unlist();
+            this.#bindings.push(binding);
+            try {
+                this.#host.bind(binding, contract, checkParams(contract, params, this.#context), this.#context);
+            }
+            catch (error) {
+                // Refused for good (an authority, a host address): the successor's factory meets the same refusal.
+                this.#refused ??= { kind: "broken", error: asChordError(error, contract.name) };
+                continue;
+            }
+            // Checked at every change of the binding until the release (never done): the failure shown follows it.
+            binding
+                .until(() => {
+                this.#changed();
+                return false;
+            }, following)
+                .catch(() => { });
+        }
+        this.#changed();
+        this.#started.resolve();
+    }
+    /** Resolves once every request is ready, or at `due` (`Date.now()` time), whichever is first. */
+    async ready(due) {
+        const timer = Promise.withResolvers();
+        const timeout = setTimeout(timer.resolve, Math.max(0, due - Date.now()));
+        try {
+            await Promise.race([timer.promise, this.#allReady()]);
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    /** The successor's own requests bound: its bindings are let go (a dependency held only by them never ends). */
+    release() {
+        this.#abort.abort();
+        for (const binding of this.#bindings.splice(0))
+            binding.release();
+    }
+    /** A binding changed: `shows` gets the failure if it is another one now. */
+    #changed() {
+        const before = this.cause;
+        const failed = this.#firstFailed();
+        if (failed?.cause !== this.#failed?.from) {
+            this.#failed = failed && { from: failed.cause, waiting: waitingFor(failed.label, failed.cause.error) };
+        }
+        const cause = this.cause;
+        if (cause !== before)
+            this.#shows(cause);
+    }
+    /** The first request failed for a reason other than another host's version skew, with its cause. */
+    #firstFailed() {
+        for (const binding of this.#bindings) {
+            const state = binding.refState;
+            if (state.kind === "failed" && !versionSkew(binding))
+                return { label: binding.label, cause: state.cause };
+        }
+        return undefined;
+    }
+    async #allReady() {
+        await this.#started.promise;
+        const context = withAbortSignal(this.#abort.signal, this.#context);
+        // A wait ends with the binding (released) or the abort: either way nothing waits any more.
+        const waits = this.#bindings.map((binding) => binding.until(() => isReady(binding), context).catch(() => { }));
+        await Promise.all(waits);
+    }
+}
+/** Whether a request is ready: live, ended, or failed for a reason other than a version skew. */
+function isReady(binding) {
+    const state = binding.refState;
+    if (state.kind === "failed")
+        return !versionSkew(binding);
+    return state.kind !== "loading";
+}
+/**
+ * Whether `binding` failed for another host's version refusal (its own, or a dependency's along the chain: `waiting`
+ * causes keep the reason): that heals when the other host's reload lands, so the old attempt stays open meanwhile,
+ * bounded as always. A refusal on this host heals by no other reload: it is no skew.
+ */
+function versionSkew(binding) {
+    const state = binding.refState;
+    if (state.kind !== "failed" || binding.target?.kind !== "remote")
+        return false;
+    const { error } = state.cause;
+    return error.code === "contract_mismatch" || (error.code === "unavailable" && error.reason === "version");
+}
+//# sourceMappingURL=readiness.js.map

package/dist/host/readiness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.js","sourceRoot":"","sources":["../../src/host/readiness.ts"],"names":[],"mappings":"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","sourcesContent":["// A restart's readiness (decision \"Reload restarts every affected object; old work finishes on old code\", rule 3):\n// the requests its new factory made in staging, bound once every fate of the reload started (every served type is the\n// new one then), and held until the successor's own requests bound. The old attempt is sealed only once they are\n// ready, so old work that reaches the object meanwhile still finds its old attempt open.\n\nimport { type Context, withAbortSignal } from \"../context/index.ts\";\nimport type { FailureCause } from \"../data/index.ts\";\nimport { asChordError, checkParams, waitingFor } from \"../data/internal.ts\";\nimport type { Caller } from \"./ctx.ts\";\nimport type { AnyHost } from \"./host.ts\";\nimport type { Binding } from \"./reference.ts\";\nimport type { Request } from \"./staging.ts\";\n\n/**\n * One restart's readiness: ready once each recorded type request is live (an open old instance that binds its version\n * counts) or failed for a reason other than another host's version skew (which heals by itself), or at its bound.\n * Registry requests are served by facets in the commit and kept by the old attempt's contributions until its seal: it\n * does not wait for them. Its failure follows the requests: `shows` gets each change of it.\n */\nexport class Readiness {\n\treadonly #host: AnyHost;\n\treadonly #caller: Caller;\n\treadonly #requests: readonly Request[];\n\treadonly #shows: (cause: FailureCause | undefined) => void;\n\treadonly #context: Context;\n\treadonly #bindings: Binding[] = [];\n\treadonly #started = Promise.withResolvers<void>();\n\t/** Ends the waits on its bindings at its release. */\n\treadonly #abort = new AbortController();\n\t/** A request refused for good at the start (an authority, a host address): it heals with no change of a binding. */\n\t#refused: FailureCause | undefined;\n\t/** The failed request's cause `shows` got last (`from`), as the successor waits for it (`waiting`). */\n\t#failed: { readonly from: FailureCause; readonly waiting: FailureCause } | undefined;\n\n\tconstructor(\n\t\thost: AnyHost,\n\t\tcaller: Caller,\n\t\trequests: readonly Request[],\n\t\tshows: (cause: FailureCause | undefined) => void,\n\t\tcontext: Context,\n\t) {\n\t\tthis.#host = host;\n\t\tthis.#caller = caller;\n\t\tthis.#requests = requests;\n\t\tthis.#shows = shows;\n\t\tthis.#context = context;\n\t}\n\n\t/** What the successor waits for now: a request refused for good, or `waiting` for the first failed one. */\n\tget cause(): FailureCause | undefined {\n\t\treturn this.#refused ?? this.#failed?.waiting;\n\t}\n\n\t/**\n\t * Binds the recorded type requests as the object's own would be (once every fate of the reload started), kept out\n\t * of presence lists (they are no consumers of their own), and follows them: `shows` gets each change of `cause`.\n\t */\n\tstart(): void {\n\t\tconst following = withAbortSignal(this.#abort.signal, this.#context);\n\t\tfor (const request of this.#requests) {\n\t\t\tif (request.kind !== \"type\") continue;\n\t\t\tconst { contract, params } = request;\n\t\t\tconst binding = this.#host.reference(contract, undefined, this.#caller, {});\n\t\t\tbinding.unlist();\n\t\t\tthis.#bindings.push(binding);\n\t\t\ttry {\n\t\t\t\tthis.#host.bind(binding, contract, checkParams(contract, params, this.#context), this.#context);\n\t\t\t} catch (error) {\n\t\t\t\t// Refused for good (an authority, a host address): the successor's factory meets the same refusal.\n\t\t\t\tthis.#refused ??= { kind: \"broken\", error: asChordError(error, contract.name) };\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\t// Checked at every change of the binding until the release (never done): the failure shown follows it.\n\t\t\tbinding\n\t\t\t\t.until(() => {\n\t\t\t\t\tthis.#changed();\n\t\t\t\t\treturn false;\n\t\t\t\t}, following)\n\t\t\t\t.catch(() => {});\n\t\t}\n\t\tthis.#changed();\n\t\tthis.#started.resolve();\n\t}\n\n\t/** Resolves once every request is ready, or at `due` (`Date.now()` time), whichever is first. */\n\tasync ready(due: number): Promise<void> {\n\t\tconst timer = Promise.withResolvers<void>();\n\t\tconst timeout = setTimeout(timer.resolve, Math.max(0, due - Date.now()));\n\t\ttry {\n\t\t\tawait Promise.race([timer.promise, this.#allReady()]);\n\t\t} finally {\n\t\t\tclearTimeout(timeout);\n\t\t}\n\t}\n\n\t/** The successor's own requests bound: its bindings are let go (a dependency held only by them never ends). */\n\trelease(): void {\n\t\tthis.#abort.abort();\n\t\tfor (const binding of this.#bindings.splice(0)) binding.release();\n\t}\n\n\t/** A binding changed: `shows` gets the failure if it is another one now. */\n\t#changed(): void {\n\t\tconst before = this.cause;\n\t\tconst failed = this.#firstFailed();\n\t\tif (failed?.cause !== this.#failed?.from) {\n\t\t\tthis.#failed = failed && { from: failed.cause, waiting: waitingFor(failed.label, failed.cause.error) };\n\t\t}\n\t\tconst cause = this.cause;\n\t\tif (cause !== before) this.#shows(cause);\n\t}\n\n\t/** The first request failed for a reason other than another host's version skew, with its cause. */\n\t#firstFailed(): { readonly label: string; readonly cause: FailureCause } | undefined {\n\t\tfor (const binding of this.#bindings) {\n\t\t\tconst state = binding.refState;\n\t\t\tif (state.kind === \"failed\" && !versionSkew(binding)) return { label: binding.label, cause: state.cause };\n\t\t}\n\t\treturn undefined;\n\t}\n\n\tasync #allReady(): Promise<void> {\n\t\tawait this.#started.promise;\n\t\tconst context = withAbortSignal(this.#abort.signal, this.#context);\n\t\t// A wait ends with the binding (released) or the abort: either way nothing waits any more.\n\t\tconst waits = this.#bindings.map((binding) => binding.until(() => isReady(binding), context).catch(() => {}));\n\t\tawait Promise.all(waits);\n\t}\n}\n\n/** Whether a request is ready: live, ended, or failed for a reason other than a version skew. */\nfunction isReady(binding: Binding): boolean {\n\tconst state = binding.refState;\n\tif (state.kind === \"failed\") return !versionSkew(binding);\n\treturn state.kind !== \"loading\";\n}\n\n/**\n * Whether `binding` failed for another host's version refusal (its own, or a dependency's along the chain: `waiting`\n * causes keep the reason): that heals when the other host's reload lands, so the old attempt stays open meanwhile,\n * bounded as always. A refusal on this host heals by no other reload: it is no skew.\n */\nfunction versionSkew(binding: Binding): boolean {\n\tconst state = binding.refState;\n\tif (state.kind !== \"failed\" || binding.target?.kind !== \"remote\") return false;\n\tconst { error } = state.cause;\n\treturn error.code === \"contract_mismatch\" || (error.code === \"unavailable\" && error.reason === \"version\");\n}\n"]}

package/dist/host/ref-state.d.ts

@@ -0,0 +1,53 @@
+import { type Context } from "../context/index.ts";
+import type { ChordError, FailureCause } from "../data/index.ts";
+import { type Batch, NativeSource } from "../state/internal.ts";
+import { NativeWatch } from "../watch.ts";
+/**
+ * Where a reference stands. `loading`: its object activates, retries or is parked on dependencies still under way, it
+ * waits for its host's publication or a parent link, or its link is down (the reference's coarser view of its object's
+ * waiting and activating); `failed`: its object failed and no attempt runs (`transient`: `retryAt` is when its backoff
+ * retries it; `broken`: no automatic retry), or nothing fits it or its object is parked on a failed dependency
+ * (`waiting`: an event wakes it, `retryAt` undefined); `live`: bound; `ended`: for good, with the error that says why
+ * (`released` without a reason: released by its holder; `released/ended`: its object ended; `released/closed`: its
+ * host closed; `forbidden/revoked`).
+ */
+export type RefState = {
+    readonly kind: "loading";
+} | {
+    readonly kind: "live";
+} | {
+    readonly kind: "failed";
+    readonly cause: FailureCause;
+    readonly retryAt: number | undefined;
+} | {
+    readonly kind: "ended";
+    readonly error: ChordError;
+};
+/** A failed reference's state. */
+export type Failed = Extract<RefState, {
+    readonly kind: "failed";
+}>;
+/** An ended reference's state. */
+export type Ended = Extract<RefState, {
+    readonly kind: "ended";
+}>;
+/** The states without fields, one object each: a change of state is a new object (a native watch compares by identity). */
+export declare const LOADING: RefState;
+export declare const LIVE: RefState;
+/**
+ * `ref.state`, a native source: its value is the reference's state, read through `read`; each watch gets every new
+ * state, in its own context (not one call per batch, as a followed source's), and ends `ended` when the reference is
+ * released (the end is the notification). Derives reading it are marked in a batch of its own when it changes.
+ */
+export declare class ReferenceState extends NativeSource<RefState> {
+    #private;
+    constructor(read: () => RefState, batch: Batch | undefined);
+    get value(): RefState;
+    /** Every state in order: a watch sees each step it went through. */
+    watch(context: Context): Promise<NativeWatch<RefState>>;
+    /** The reference's state may have changed: every watch gets it when it is another state, derives are marked. */
+    moved(): void;
+    /** The reference ended (`ended`, the reference's state): every watch ends `ended`, derives are marked a last time. */
+    released(ended: Ended): void;
+}
+//# sourceMappingURL=ref-state.d.ts.map

package/dist/host/ref-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref-state.d.ts","sourceRoot":"","sources":["../../src/host/ref-state.ts"],"names":[],"mappings":"AAGA,OAAO,EAAsB,KAAK,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACjE,OAAO,EAAE,KAAK,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;;;;GAQG;AACH,MAAM,MAAM,QAAQ,GACjB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GAC/F;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;CAAE,CAAC;AAE1D,kCAAkC;AAClC,MAAM,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC,CAAC;AAEpE,kCAAkC;AAClC,MAAM,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAElE,2HAA2H;AAC3H,eAAO,MAAM,OAAO,EAAE,QAA8B,CAAC;AAErD,eAAO,MAAM,IAAI,EAAE,QAA2B,CAAC;AAE/C;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,YAAY,CAAC,QAAQ,CAAC;;IAOzD,YAAY,IAAI,EAAE,MAAM,QAAQ,EAAE,KAAK,EAAE,KAAK,GAAG,SAAS,EAIzD;IAED,IAAI,KAAK,IAAI,QAAQ,CAEpB;IAED,oEAAoE;IAC9D,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAc5D;IAED,gHAAgH;IAChH,KAAK,IAAI,IAAI,CAMZ;IAED,sHAAsH;IACtH,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAe3B;CASD"}

package/dist/host/ref-state.js

@@ -0,0 +1,83 @@
+// The state of a reference (§7): loading, live, failed or ended; and `ref.state`, the native watchable that follows
+// it.
+import { BACKGROUND_CONTEXT } from "../context/index.js";
+import { NativeSource } from "../state/internal.js";
+import { NativeWatch } from "../watch.js";
+/** The states without fields, one object each: a change of state is a new object (a native watch compares by identity). */
+export const LOADING = { kind: "loading" };
+export const LIVE = { kind: "live" };
+/**
+ * `ref.state`, a native source: its value is the reference's state, read through `read`; each watch gets every new
+ * state, in its own context (not one call per batch, as a followed source's), and ends `ended` when the reference is
+ * released (the end is the notification). Derives reading it are marked in a batch of its own when it changes.
+ */
+export class ReferenceState extends NativeSource {
+    #read;
+    /** The watches with the contexts they were taken in, which their frames carry. */
+    #watches = new Map();
+    /** The state the watches have: a change is announced only when the state is another object. */
+    #last;
+    constructor(read, batch) {
+        super(batch);
+        this.#read = read;
+        this.#last = read();
+    }
+    get value() {
+        return this.#read();
+    }
+    /** Every state in order: a watch sees each step it went through. */
+    async watch(context) {
+        const state = this.#read();
+        const batch = this.batch;
+        // An ended reference has nothing more to announce, and keeps no host to report to.
+        if (batch === undefined || state.kind === "ended") {
+            const ended = new NativeWatch(state, IGNORE, IGNORE);
+            ended.end({ kind: "ended" });
+            return ended;
+        }
+        batch.assertOutside("watch");
+        const watch = new NativeWatch(state, () => this.#watches.delete(watch), batch.reportListener);
+        this.#watches.set(watch, context);
+        if (context.abortSignal !== undefined)
+            watch.observeAbort(context.abortSignal);
+        return watch;
+    }
+    /** The reference's state may have changed: every watch gets it when it is another state, derives are marked. */
+    moved() {
+        const state = this.#read();
+        if (state === this.#last)
+            return;
+        this.#last = state;
+        for (const [watch, context] of this.#watches)
+            watch.advance(state, context);
+        if (this.dependents.size > 0)
+            this.#mark();
+    }
+    /** The reference ended (`ended`, the reference's state): every watch ends `ended`, derives are marked a last time. */
+    released(ended) {
+        // An ended reference keeps nothing of its object: not the last failure's error, not the host.
+        this.#last = ended;
+        // Ending detaches, which deletes the current entry (safe while iterating) and runs no listener.
+        for (const watch of this.#watches.keys())
+            watch.end({ kind: "ended" });
+        const batch = this.batch;
+        if (batch === undefined || this.dependents.size === 0) {
+            this.end();
+            return;
+        }
+        // Ended where the marks run: a release while a batch's flushes send marks in the next commit, after this.
+        batch.within(() => {
+            this.changed();
+            this.end();
+        }, BACKGROUND_CONTEXT);
+    }
+    /**
+     * Marks the derives reading it, in the batch running now or one of its own (apart from `moved`: a closure there
+     * would allocate on every state change). A reference has no context of its own: the background context.
+     */
+    #mark() {
+        this.batch?.within(() => this.changed(), BACKGROUND_CONTEXT);
+    }
+}
+const IGNORE = () => { };
+//# sourceMappingURL=ref-state.js.map

package/dist/host/ref-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref-state.js","sourceRoot":"","sources":["../../src/host/ref-state.ts"],"names":[],"mappings":"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","sourcesContent":["// The state of a reference (§7): loading, live, failed or ended; and `ref.state`, the native watchable that follows\n// it.\n\nimport { BACKGROUND_CONTEXT, type Context } from \"../context/index.ts\";\nimport type { ChordError, FailureCause } from \"../data/index.ts\";\nimport { type Batch, NativeSource } from \"../state/internal.ts\";\nimport { NativeWatch } from \"../watch.ts\";\n\n/**\n * Where a reference stands. `loading`: its object activates, retries or is parked on dependencies still under way, it\n * waits for its host's publication or a parent link, or its link is down (the reference's coarser view of its object's\n * waiting and activating); `failed`: its object failed and no attempt runs (`transient`: `retryAt` is when its backoff\n * retries it; `broken`: no automatic retry), or nothing fits it or its object is parked on a failed dependency\n * (`waiting`: an event wakes it, `retryAt` undefined); `live`: bound; `ended`: for good, with the error that says why\n * (`released` without a reason: released by its holder; `released/ended`: its object ended; `released/closed`: its\n * host closed; `forbidden/revoked`).\n */\nexport type RefState =\n\t| { readonly kind: \"loading\" }\n\t| { readonly kind: \"live\" }\n\t| { readonly kind: \"failed\"; readonly cause: FailureCause; readonly retryAt: number | undefined }\n\t| { readonly kind: \"ended\"; readonly error: ChordError };\n\n/** A failed reference's state. */\nexport type Failed = Extract<RefState, { readonly kind: \"failed\" }>;\n\n/** An ended reference's state. */\nexport type Ended = Extract<RefState, { readonly kind: \"ended\" }>;\n\n/** The states without fields, one object each: a change of state is a new object (a native watch compares by identity). */\nexport const LOADING: RefState = { kind: \"loading\" };\n\nexport const LIVE: RefState = { kind: \"live\" };\n\n/**\n * `ref.state`, a native source: its value is the reference's state, read through `read`; each watch gets every new\n * state, in its own context (not one call per batch, as a followed source's), and ends `ended` when the reference is\n * released (the end is the notification). Derives reading it are marked in a batch of its own when it changes.\n */\nexport class ReferenceState extends NativeSource<RefState> {\n\treadonly #read: () => RefState;\n\t/** The watches with the contexts they were taken in, which their frames carry. */\n\treadonly #watches = new Map<NativeWatch<RefState>, Context>();\n\t/** The state the watches have: a change is announced only when the state is another object. */\n\t#last: RefState;\n\n\tconstructor(read: () => RefState, batch: Batch | undefined) {\n\t\tsuper(batch);\n\t\tthis.#read = read;\n\t\tthis.#last = read();\n\t}\n\n\tget value(): RefState {\n\t\treturn this.#read();\n\t}\n\n\t/** Every state in order: a watch sees each step it went through. */\n\tasync watch(context: Context): Promise<NativeWatch<RefState>> {\n\t\tconst state = this.#read();\n\t\tconst batch = this.batch;\n\t\t// An ended reference has nothing more to announce, and keeps no host to report to.\n\t\tif (batch === undefined || state.kind === \"ended\") {\n\t\t\tconst ended = new NativeWatch<RefState>(state, IGNORE, IGNORE);\n\t\t\tended.end({ kind: \"ended\" });\n\t\t\treturn ended;\n\t\t}\n\t\tbatch.assertOutside(\"watch\");\n\t\tconst watch = new NativeWatch<RefState>(state, () => this.#watches.delete(watch), batch.reportListener);\n\t\tthis.#watches.set(watch, context);\n\t\tif (context.abortSignal !== undefined) watch.observeAbort(context.abortSignal);\n\t\treturn watch;\n\t}\n\n\t/** The reference's state may have changed: every watch gets it when it is another state, derives are marked. */\n\tmoved(): void {\n\t\tconst state = this.#read();\n\t\tif (state === this.#last) return;\n\t\tthis.#last = state;\n\t\tfor (const [watch, context] of this.#watches) watch.advance(state, context);\n\t\tif (this.dependents.size > 0) this.#mark();\n\t}\n\n\t/** The reference ended (`ended`, the reference's state): every watch ends `ended`, derives are marked a last time. */\n\treleased(ended: Ended): void {\n\t\t// An ended reference keeps nothing of its object: not the last failure's error, not the host.\n\t\tthis.#last = ended;\n\t\t// Ending detaches, which deletes the current entry (safe while iterating) and runs no listener.\n\t\tfor (const watch of this.#watches.keys()) watch.end({ kind: \"ended\" });\n\t\tconst batch = this.batch;\n\t\tif (batch === undefined || this.dependents.size === 0) {\n\t\t\tthis.end();\n\t\t\treturn;\n\t\t}\n\t\t// Ended where the marks run: a release while a batch's flushes send marks in the next commit, after this.\n\t\tbatch.within(() => {\n\t\t\tthis.changed();\n\t\t\tthis.end();\n\t\t}, BACKGROUND_CONTEXT);\n\t}\n\n\t/**\n\t * Marks the derives reading it, in the batch running now or one of its own (apart from `moved`: a closure there\n\t * would allocate on every state change). A reference has no context of its own: the background context.\n\t */\n\t#mark(): void {\n\t\tthis.batch?.within(() => this.changed(), BACKGROUND_CONTEXT);\n\t}\n}\n\nconst IGNORE = (): void => {};\n"]}

package/dist/host/reference-keys.d.ts

@@ -0,0 +1,36 @@
+import { type Context } from "../context/index.ts";
+import { ChordError } from "../data/index.ts";
+import type { Batch } from "../state/internal.ts";
+import type { PinnedKey } from "./attempt.ts";
+import type { Target } from "./reference.ts";
+/** What a reference's keys need of it. */
+export interface KeyHolder {
+    readonly batch: Batch;
+    /** Its contract version: keys are mapped to it. */
+    readonly version: number;
+    /** The object it is bound to; `undefined` while unbound. */
+    target(): Target | undefined;
+    /** What a read throws while a key never had a value. */
+    none(): ChordError;
+}
+/** A reference's held keys; every instance pin below them released exactly once. */
+export declare class ReferenceKeys {
+    #private;
+    constructor(holder: KeyHolder);
+    /**
+     * Holds `key` of keyed member `member`: its source once pinned and loaded on the live instance; `context` ends only
+     * this caller's wait. `release` (once) lets it go with its last holder.
+     */
+    hold(member: string, key: string, context: Context): Promise<PinnedKey>;
+    /**
+     * Its reference's target changed, inside a batch: a key pins again on a new live instance (last value meanwhile);
+     * while the target is not live it follows the instance it is pinned on as long as the object does (a commit admitted
+     * there still shows), then keeps its last value (one `failed` call for a failure) and its pin goes.
+     */
+    follow(context: Context): void;
+    /** Its reference left its object (`error`: why it waits), inside a batch: keys keep their last values, pins go. */
+    fail(error: ChordError, context: Context): void;
+    /** Its reference ended, inside a batch: every key ends with `error` and releases its pin. */
+    end(error: ChordError): void;
+}
+//# sourceMappingURL=reference-keys.d.ts.map

package/dist/host/reference-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-keys.d.ts","sourceRoot":"","sources":["../../src/host/reference-keys.ts"],"names":[],"mappings":"AAQA,OAAO,EAAwC,KAAK,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACzF,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAG7C,0CAA0C;AAC1C,MAAM,WAAW,SAAS;IACzB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,mDAAmD;IACnD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,4DAA4D;IAC5D,MAAM,IAAI,MAAM,GAAG,SAAS,CAAC;IAC7B,wDAAwD;IACxD,IAAI,IAAI,UAAU,CAAC;CACnB;AAgBD,oFAAoF;AACpF,qBAAa,aAAa;;IAIzB,YAAY,MAAM,EAAE,SAAS,EAE5B;IAED;;;OAGG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,CAAC,CAgB5E;IAED;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAkB7B;IAED,mHAAmH;IACnH,IAAI,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAO9C;IAED,6FAA6F;IAC7F,GAAG,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAQ3B;CA8ED"}

package/dist/host/reference-keys.js

@@ -0,0 +1,168 @@
+// The keys a reference holds (slice 6a §12; decision "References are the only indirection" (4)): its key watches and
+// its factory's pins (`at(key)`) of its object's keyed members, one source per member and key shared by them, pinned on
+// the object's live instance (loaded, mapped to the reference's version). While the object still follows the instance a
+// key is pinned on (a restart's open old attempt, a live failure's admitted commits) the key follows it on,
+// as members do. When the reference moves to a new instance or a new object it pins the key there again, keeping the
+// last value until that pin loads, then one frame; while it points at nothing the key keeps its last value (one
+// `failed` call when its target failed, none while it loads).
+import { awaitWithContext, BACKGROUND_CONTEXT } from "../context/index.js";
+import { ChordError } from "../data/index.js";
+import { asChordError } from "../data/internal.js";
+import { ReferenceSource } from "./reference-source.js";
+/** A reference's held keys; every instance pin below them released exactly once. */
+export class ReferenceKeys {
+    #holder;
+    #entries = new Map();
+    constructor(holder) {
+        this.#holder = holder;
+    }
+    /**
+     * Holds `key` of keyed member `member`: its source once pinned and loaded on the live instance; `context` ends only
+     * this caller's wait. `release` (once) lets it go with its last holder.
+     */
+    async hold(member, key, context) {
+        const entry = this.#entry(member, key);
+        entry.holders++;
+        let released = false;
+        const release = () => {
+            if (released)
+                return;
+            released = true;
+            this.#release(entry);
+        };
+        try {
+            if (entry.pin === undefined)
+                await awaitWithContext(this.#pin(entry), context);
+        }
+        catch (error) {
+            release();
+            throw error;
+        }
+        return { source: entry.source, release };
+    }
+    /**
+     * Its reference's target changed, inside a batch: a key pins again on a new live instance (last value meanwhile);
+     * while the target is not live it follows the instance it is pinned on as long as the object does (a commit admitted
+     * there still shows), then keeps its last value (one `failed` call for a failure) and its pin goes.
+     */
+    follow(context) {
+        const target = this.#holder.target();
+        const instance = target?.instance;
+        const attachable = target?.attachable;
+        for (const byKey of this.#entries.values()) {
+            for (const entry of byKey.values()) {
+                if (instance !== undefined) {
+                    // A failed load shows on the key (`failed`); nobody waits on this pin.
+                    if (entry.instance !== instance)
+                        this.#pin(entry).catch(() => { });
+                    continue;
+                }
+                if (attachable !== undefined && entry.instance === attachable)
+                    continue;
+                const state = target?.state;
+                if (state?.kind === "failed")
+                    entry.source.fail(state.cause.error, context);
+                else
+                    entry.source.hold();
+                this.#unpin(entry);
+            }
+        }
+    }
+    /** Its reference left its object (`error`: why it waits), inside a batch: keys keep their last values, pins go. */
+    fail(error, context) {
+        for (const byKey of this.#entries.values()) {
+            for (const entry of byKey.values()) {
+                entry.source.fail(error, context);
+                this.#unpin(entry);
+            }
+        }
+    }
+    /** Its reference ended, inside a batch: every key ends with `error` and releases its pin. */
+    end(error) {
+        for (const byKey of this.#entries.values()) {
+            for (const entry of byKey.values()) {
+                entry.source.end(error);
+                this.#unpin(entry);
+            }
+        }
+        this.#entries.clear();
+    }
+    /** The entry of `member` and `key`, made by the first holder. */
+    #entry(member, key) {
+        let byKey = this.#entries.get(member);
+        if (byKey === undefined) {
+            byKey = new Map();
+            this.#entries.set(member, byKey);
+        }
+        let entry = byKey.get(key);
+        if (entry === undefined) {
+            const source = new ReferenceSource(this.#holder.batch, this.#holder);
+            entry = { member, key, source, holders: 0, instance: undefined, pin: undefined, loading: undefined };
+            byKey.set(key, entry);
+        }
+        return entry;
+    }
+    /**
+     * Pins `entry`'s key on the target's live instance (once per instance): the source keeps its last value meanwhile,
+     * follows the pin when it lands (one frame) and releases the previous one; a failed load shows as its failure.
+     */
+    #pin(entry) {
+        const { batch, version } = this.#holder;
+        const target = this.#holder.target();
+        const instance = target?.instance;
+        if (target === undefined || instance === undefined)
+            return Promise.reject(this.#holder.none());
+        if (entry.instance === instance && entry.loading !== undefined)
+            return entry.loading;
+        entry.instance = instance;
+        // No frames from the old instance while the new one loads the key.
+        entry.source.hold();
+        const loading = target.pinKey(entry.member, entry.key, version, BACKGROUND_CONTEXT).then((pin) => {
+            if (entry.instance !== instance || entry.holders === 0) {
+                pin.release();
+                return;
+            }
+            const previous = entry.pin;
+            entry.pin = pin;
+            batch.within(() => entry.source.bind(pin.source), BACKGROUND_CONTEXT);
+            previous?.release();
+        }, (error) => {
+            if (entry.instance === instance) {
+                entry.instance = undefined;
+                entry.loading = undefined;
+                const failure = asChordError(error, target.label);
+                batch.within(() => entry.source.fail(failure, BACKGROUND_CONTEXT), BACKGROUND_CONTEXT);
+            }
+            throw error;
+        });
+        entry.loading = loading;
+        return loading;
+    }
+    /** One holder of `entry` left; the last drops it and its pin. */
+    #release(entry) {
+        if (--entry.holders > 0)
+            return;
+        const byKey = this.#entries.get(entry.member);
+        if (byKey?.get(entry.key) !== entry)
+            return;
+        byKey.delete(entry.key);
+        if (byKey.size === 0)
+            this.#entries.delete(entry.member);
+        // Its source ends: it leaves the document, whose other holders would keep it and its reference (Astra, GC).
+        const released = new ChordError({ code: "released", message: `${entry.member}.at(${entry.key}): released` });
+        const end = () => entry.source.end(released);
+        if (entry.source.inUse)
+            this.#holder.batch.within(end, BACKGROUND_CONTEXT);
+        else
+            end();
+        this.#unpin(entry);
+    }
+    /** Releases the pin `entry` follows or awaits: it points at nothing until pinned again. */
+    #unpin(entry) {
+        entry.pin?.release();
+        entry.pin = undefined;
+        entry.instance = undefined;
+        entry.loading = undefined;
+    }
+}
+//# sourceMappingURL=reference-keys.js.map

package/dist/host/reference-keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-keys.js","sourceRoot":"","sources":["../../src/host/reference-keys.ts"],"names":[],"mappings":"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","sourcesContent":["// The keys a reference holds (slice 6a §12; decision \"References are the only indirection\" (4)): its key watches and\n// its factory's pins (`at(key)`) of its object's keyed members, one source per member and key shared by them, pinned on\n// the object's live instance (loaded, mapped to the reference's version). While the object still follows the instance a\n// key is pinned on (a restart's open old attempt, a live failure's admitted commits) the key follows it on,\n// as members do. When the reference moves to a new instance or a new object it pins the key there again, keeping the\n// last value until that pin loads, then one frame; while it points at nothing the key keeps its last value (one\n// `failed` call when its target failed, none while it loads).\n\nimport { awaitWithContext, BACKGROUND_CONTEXT, type Context } from \"../context/index.ts\";\nimport { ChordError } from \"../data/index.ts\";\nimport { asChordError } from \"../data/internal.ts\";\nimport type { Batch } from \"../state/internal.ts\";\nimport type { PinnedKey } from \"./attempt.ts\";\nimport type { Target } from \"./reference.ts\";\nimport { ReferenceSource } from \"./reference-source.ts\";\n\n/** What a reference's keys need of it. */\nexport interface KeyHolder {\n\treadonly batch: Batch;\n\t/** Its contract version: keys are mapped to it. */\n\treadonly version: number;\n\t/** The object it is bound to; `undefined` while unbound. */\n\ttarget(): Target | undefined;\n\t/** What a read throws while a key never had a value. */\n\tnone(): ChordError;\n}\n\n/** One key of one keyed member held by the reference: its source, its users, and the instance pin it follows. */\ntype KeyEntry = {\n\treadonly member: string;\n\treadonly key: string;\n\treadonly source: ReferenceSource;\n\tholders: number;\n\t/** The live instance its pin is (or is being) taken on; `undefined` while it points at nothing. */\n\tinstance: unknown;\n\t/** The pin it follows. */\n\tpin: PinnedKey | undefined;\n\t/** The pin in flight, settled once the source follows it. */\n\tloading: Promise<void> | undefined;\n};\n\n/** A reference's held keys; every instance pin below them released exactly once. */\nexport class ReferenceKeys {\n\treadonly #holder: KeyHolder;\n\treadonly #entries = new Map<string, Map<string, KeyEntry>>();\n\n\tconstructor(holder: KeyHolder) {\n\t\tthis.#holder = holder;\n\t}\n\n\t/**\n\t * Holds `key` of keyed member `member`: its source once pinned and loaded on the live instance; `context` ends only\n\t * this caller's wait. `release` (once) lets it go with its last holder.\n\t */\n\tasync hold(member: string, key: string, context: Context): Promise<PinnedKey> {\n\t\tconst entry = this.#entry(member, key);\n\t\tentry.holders++;\n\t\tlet released = false;\n\t\tconst release = (): void => {\n\t\t\tif (released) return;\n\t\t\treleased = true;\n\t\t\tthis.#release(entry);\n\t\t};\n\t\ttry {\n\t\t\tif (entry.pin === undefined) await awaitWithContext(this.#pin(entry), context);\n\t\t} catch (error) {\n\t\t\trelease();\n\t\t\tthrow error;\n\t\t}\n\t\treturn { source: entry.source, release };\n\t}\n\n\t/**\n\t * Its reference's target changed, inside a batch: a key pins again on a new live instance (last value meanwhile);\n\t * while the target is not live it follows the instance it is pinned on as long as the object does (a commit admitted\n\t * there still shows), then keeps its last value (one `failed` call for a failure) and its pin goes.\n\t */\n\tfollow(context: Context): void {\n\t\tconst target = this.#holder.target();\n\t\tconst instance = target?.instance;\n\t\tconst attachable = target?.attachable;\n\t\tfor (const byKey of this.#entries.values()) {\n\t\t\tfor (const entry of byKey.values()) {\n\t\t\t\tif (instance !== undefined) {\n\t\t\t\t\t// A failed load shows on the key (`failed`); nobody waits on this pin.\n\t\t\t\t\tif (entry.instance !== instance) this.#pin(entry).catch(() => {});\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tif (attachable !== undefined && entry.instance === attachable) continue;\n\t\t\t\tconst state = target?.state;\n\t\t\t\tif (state?.kind === \"failed\") entry.source.fail(state.cause.error, context);\n\t\t\t\telse entry.source.hold();\n\t\t\t\tthis.#unpin(entry);\n\t\t\t}\n\t\t}\n\t}\n\n\t/** Its reference left its object (`error`: why it waits), inside a batch: keys keep their last values, pins go. */\n\tfail(error: ChordError, context: Context): void {\n\t\tfor (const byKey of this.#entries.values()) {\n\t\t\tfor (const entry of byKey.values()) {\n\t\t\t\tentry.source.fail(error, context);\n\t\t\t\tthis.#unpin(entry);\n\t\t\t}\n\t\t}\n\t}\n\n\t/** Its reference ended, inside a batch: every key ends with `error` and releases its pin. */\n\tend(error: ChordError): void {\n\t\tfor (const byKey of this.#entries.values()) {\n\t\t\tfor (const entry of byKey.values()) {\n\t\t\t\tentry.source.end(error);\n\t\t\t\tthis.#unpin(entry);\n\t\t\t}\n\t\t}\n\t\tthis.#entries.clear();\n\t}\n\n\t/** The entry of `member` and `key`, made by the first holder. */\n\t#entry(member: string, key: string): KeyEntry {\n\t\tlet byKey = this.#entries.get(member);\n\t\tif (byKey === undefined) {\n\t\t\tbyKey = new Map();\n\t\t\tthis.#entries.set(member, byKey);\n\t\t}\n\t\tlet entry = byKey.get(key);\n\t\tif (entry === undefined) {\n\t\t\tconst source = new ReferenceSource(this.#holder.batch, this.#holder);\n\t\t\tentry = { member, key, source, holders: 0, instance: undefined, pin: undefined, loading: undefined };\n\t\t\tbyKey.set(key, entry);\n\t\t}\n\t\treturn entry;\n\t}\n\n\t/**\n\t * Pins `entry`'s key on the target's live instance (once per instance): the source keeps its last value meanwhile,\n\t * follows the pin when it lands (one frame) and releases the previous one; a failed load shows as its failure.\n\t */\n\t#pin(entry: KeyEntry): Promise<void> {\n\t\tconst { batch, version } = this.#holder;\n\t\tconst target = this.#holder.target();\n\t\tconst instance = target?.instance;\n\t\tif (target === undefined || instance === undefined) return Promise.reject(this.#holder.none());\n\t\tif (entry.instance === instance && entry.loading !== undefined) return entry.loading;\n\t\tentry.instance = instance;\n\t\t// No frames from the old instance while the new one loads the key.\n\t\tentry.source.hold();\n\t\tconst loading = target.pinKey(entry.member, entry.key, version, BACKGROUND_CONTEXT).then(\n\t\t\t(pin) => {\n\t\t\t\tif (entry.instance !== instance || entry.holders === 0) {\n\t\t\t\t\tpin.release();\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tconst previous = entry.pin;\n\t\t\t\tentry.pin = pin;\n\t\t\t\tbatch.within(() => entry.source.bind(pin.source), BACKGROUND_CONTEXT);\n\t\t\t\tprevious?.release();\n\t\t\t},\n\t\t\t(error: unknown) => {\n\t\t\t\tif (entry.instance === instance) {\n\t\t\t\t\tentry.instance = undefined;\n\t\t\t\t\tentry.loading = undefined;\n\t\t\t\t\tconst failure = asChordError(error, target.label);\n\t\t\t\t\tbatch.within(() => entry.source.fail(failure, BACKGROUND_CONTEXT), BACKGROUND_CONTEXT);\n\t\t\t\t}\n\t\t\t\tthrow error;\n\t\t\t},\n\t\t);\n\t\tentry.loading = loading;\n\t\treturn loading;\n\t}\n\n\t/** One holder of `entry` left; the last drops it and its pin. */\n\t#release(entry: KeyEntry): void {\n\t\tif (--entry.holders > 0) return;\n\t\tconst byKey = this.#entries.get(entry.member);\n\t\tif (byKey?.get(entry.key) !== entry) return;\n\t\tbyKey.delete(entry.key);\n\t\tif (byKey.size === 0) this.#entries.delete(entry.member);\n\t\t// Its source ends: it leaves the document, whose other holders would keep it and its reference (Astra, GC).\n\t\tconst released = new ChordError({ code: \"released\", message: `${entry.member}.at(${entry.key}): released` });\n\t\tconst end = (): void => entry.source.end(released);\n\t\tif (entry.source.inUse) this.#holder.batch.within(end, BACKGROUND_CONTEXT);\n\t\telse end();\n\t\tthis.#unpin(entry);\n\t}\n\n\t/** Releases the pin `entry` follows or awaits: it points at nothing until pinned again. */\n\t#unpin(entry: KeyEntry): void {\n\t\tentry.pin?.release();\n\t\tentry.pin = undefined;\n\t\tentry.instance = undefined;\n\t\tentry.loading = undefined;\n\t}\n}\n"]}

package/dist/host/reference-source.d.ts

@@ -0,0 +1,65 @@
+import type { Context } from "../context/index.ts";
+import type { ChordError } from "../data/index.ts";
+import type { JsonValue } from "../json.ts";
+import { type Batch, type Dependent, type DeriveSource, Source, type Subscriber, type WatchStart } from "../state/internal.ts";
+import { Watch } from "../watch.ts";
+/** A reference owning its sources: what a read of one that never had a value throws. */
+export interface SourceOwner {
+    none(): ChordError;
+}
+/**
+ * One member (or key) of one reference. Bound, it is a dependent of the instance's member (its own dependents are
+ * marked with it); its watches and subscribers subscribe to that member itself, so the member's frames reach them as
+ * they are, and a derive member stays lazy while nothing follows it; holding or moving moves them.
+ */
+export declare class ReferenceSource extends Source implements Dependent {
+    #private;
+    constructor(batch: Batch, owner: SourceOwner);
+    /** Whether it never had a value (a watch waits for its reference's values first). */
+    get unbound(): boolean;
+    get value(): JsonValue;
+    /** What a new watch starts at: the bound member's start, the held value (after its failure), or the failure. */
+    start(): WatchStart;
+    /**
+     * A watch subscribed to the bound member itself (as `Source.openWatch` starts one: on a failed member at its last
+     * good value, the failure first).
+     */
+    openWatch(context: Context): Watch<JsonValue>;
+    /** Whether anything follows it: a watch, a subscriber or a derive (moving or ending it then needs a batch). */
+    get inUse(): boolean;
+    /** Whether a watch or a subscriber follows it (through the bound member). */
+    get watched(): boolean;
+    /** Feeds `subscriber` the bound member's frames (it subscribes there) and the moves' frames. */
+    subscribe(subscriber: Subscriber): void;
+    /** As `Source.unsubscribe`. */
+    unsubscribe(subscriber: Subscriber): void;
+    /** The bound member changed: its dependents are marked (its frames reach the subscribers directly). */
+    invalidate(): void;
+    /** The bound member's document was retired: its dependents carry the flag on. */
+    sourceRetired(visited: Set<Dependent>): void;
+    /**
+     * Follows `source`, an instance's member, inside a batch: watches get one frame from the last value (a full one
+     * after a failure); derives downstream are marked and recompute, a failed one included (self-healing).
+     */
+    bind(source: DeriveSource): void;
+    /** Its target loads (a restart, a retry, a new object not live yet): it keeps its last value, and tells nothing. */
+    hold(): void;
+    /**
+     * Its target failed (`error`: its cause's, a refused version's, a removed type's), inside a batch: it keeps its last
+     * value, its watches and subscribers get one failure call (once per failure) and stay open.
+     */
+    fail(error: ChordError, context: Context): void;
+    /**
+     * Its target's live variant lacks the member, inside a batch: reads throw `error`; watches and subscribers get one
+     * failure call and stay open (a later instance may bring the member back, as `[["r", value]]`).
+     */
+    vanish(error: ChordError, context: Context): void;
+    /**
+     * Its reference ended, inside a batch: reads throw `error`, watches end `ended`, and derives over it are marked
+     * (their next read throws it, no cached value stays).
+     */
+    end(error: ChordError): void;
+    /** Delivers a move's frame: the diff from the watches' value to the new member's. */
+    deliver(context: Context): void;
+}
+//# sourceMappingURL=reference-source.d.ts.map

package/dist/host/reference-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-source.d.ts","sourceRoot":"","sources":["../../src/host/reference-source.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EACN,KAAK,KAAK,EACV,KAAK,SAAS,EACd,KAAK,YAAY,EAEjB,MAAM,EACN,KAAK,UAAU,EACf,KAAK,UAAU,EACf,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,KAAK,EAAiC,MAAM,aAAa,CAAC;AAgBnE,wFAAwF;AACxF,MAAM,WAAW,WAAW;IAC3B,IAAI,IAAI,UAAU,CAAC;CACnB;AAOD;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,MAAO,YAAW,SAAS;;IAY/D,YAAY,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAG3C;IAED,qFAAqF;IACrF,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,IAAI,KAAK,IAAI,SAAS,CAarB;IAED,gHAAgH;IAChH,KAAK,IAAI,UAAU,CAgBlB;IAED;;;OAGG;IACH,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,KAAK,CAAC,SAAS,CAAC,CAU5C;IAED,+GAA+G;IAC/G,IAAI,KAAK,IAAI,OAAO,CAEnB;IAED,6EAA6E;IAC7E,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,gGAAgG;IAChG,SAAS,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAKtC;IAED,+BAA+B;IAC/B,WAAW,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAIxC;IAED,uGAAuG;IACvG,UAAU,IAAI,IAAI,CAEjB;IAED,iFAAiF;IACjF,aAAa,CAAC,OAAO,EAAE,GAAG,CAAC,SAAS,CAAC,GAAG,IAAI,CAE3C;IAED;;;OAGG;IACH,IAAI,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAS/B;IAED,oHAAoH;IACpH,IAAI,IAAI,IAAI,CAQX;IAED;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAa9C;IAED;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAQhD;IAED;;;OAGG;IACH,GAAG,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAS3B;IAED,qFAAqF;IACrF,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAgB9B;CAyDD"}