@earendil-works/chord 1.4.0 → 1.5.1

package/dist/host/presence.js

@@ -0,0 +1,117 @@
+// Presence (§19): `host.references(Type)`, a JSON watchable of the references to objects of one type on this host, one
+// entry per reference with the object's params, the reference's principal (remote types) and its incarnation.
+import { Source } from "../state/internal.js";
+/**
+ * The references of one type, made by the host for its first `host.references(Type)` and kept from then on: one entry
+ * per reference, added when it binds and removed when it ends, in the batch where that happens (derives over it
+ * recompute there). While watched, a batch's changes are folded into the published list once, with one splice op per
+ * removal and one for the additions; otherwise the list is built on its next read.
+ */
+export class References extends Source {
+    #entries = new Map();
+    /** The list as last published or read; `undefined` once it changed while nobody watched it. */
+    #list;
+    /** Entries added since `#list`, in order (only while it is defined). */
+    #added = [];
+    /** Entries of `#list` removed since. */
+    #removed = new Set();
+    /** The ops folding `#list` forward, for the current batch's frame. */
+    #ops = [];
+    get value() {
+        this.#fold();
+        // Entries are JSON: params, a principal and a string.
+        return this.#list;
+    }
+    /** `holder` references `object`, added in the batch running now or the next one. */
+    add(object, holder, context) {
+        this.batch.within(() => {
+            const entry = this.record(object, holder);
+            if (this.#follows())
+                this.#added.push(entry);
+            this.changed();
+        }, context);
+    }
+    /** `holders` of `object` ended, removed in one batch. */
+    remove(holders, context) {
+        this.batch.within(() => {
+            const follows = this.#follows();
+            for (const holder of holders) {
+                const entry = this.#entries.get(holder);
+                if (entry === undefined)
+                    continue;
+                this.#entries.delete(holder);
+                if (!follows)
+                    continue;
+                const added = this.#added.indexOf(entry);
+                if (added === -1)
+                    this.#removed.add(entry);
+                else
+                    this.#added.splice(added, 1);
+            }
+            this.changed();
+        }, context);
+    }
+    /** Records `holder` without a batch (the list being made) and returns its entry. */
+    record(object, holder) {
+        const { principal, incarnation } = holder.caller;
+        const entry = {
+            params: object.params,
+            ...(object.served.kind === "remote" && principal !== undefined ? { principal } : {}),
+            incarnation,
+        };
+        this.#entries.set(holder, entry);
+        return entry;
+    }
+    deliver(context) {
+        const value = this.value;
+        const ops = this.#ops;
+        this.#ops = [];
+        // Listed once per change: the batch's first delivery carries all of them.
+        if (ops.length > 0)
+            this.publish(value, ops, false, context);
+    }
+    /**
+     * Whether a change is folded into the published list: while watched (a watch read the list first). Otherwise the
+     * list is dropped and built on its next read.
+     */
+    #follows() {
+        if (this.watched && this.#list !== undefined)
+            return true;
+        this.#list = undefined;
+        return false;
+    }
+    /**
+     * Folds the changes since `#list` into a new list, once: a removal is one splice op at its index, the additions one
+     * splice op at the end. Builds the list from the entries when there is none.
+     */
+    #fold() {
+        if (this.#list === undefined) {
+            this.#list = [...this.#entries.values()];
+            this.#added = [];
+            this.#removed.clear();
+            this.#ops = [];
+            return;
+        }
+        if (this.#added.length === 0 && this.#removed.size === 0)
+            return;
+        let list = this.#list;
+        if (this.#removed.size > 0) {
+            const kept = [];
+            for (const entry of list) {
+                if (this.#removed.has(entry))
+                    this.#ops.push(["p", [], kept.length, 1, []]);
+                else
+                    kept.push(entry);
+            }
+            this.#removed.clear();
+            list = kept;
+        }
+        if (this.#added.length > 0) {
+            this.#ops.push(["p", [], list.length, 0, this.#added]);
+            list = [...list, ...this.#added];
+            this.#added = [];
+        }
+        this.#list = list;
+    }
+}
+//# sourceMappingURL=presence.js.map

package/dist/host/presence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presence.js","sourceRoot":"","sources":["../../src/host/presence.ts"],"names":[],"mappings":"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","sourcesContent":["// Presence (§19): `host.references(Type)`, a JSON watchable of the references to objects of one type on this host, one\n// entry per reference with the object's params, the reference's principal (remote types) and its incarnation.\n\nimport type { Context } from \"../context/index.ts\";\nimport type { Contract, ParamsOf } from \"../contracts/index.ts\";\nimport type { Principal } from \"../data/index.ts\";\nimport type { Op } from \"../delta/index.ts\";\nimport type { JsonValue } from \"../json.ts\";\nimport { Source } from \"../state/internal.ts\";\nimport type { ChordObject, Holder } from \"./object.ts\";\n\n/**\n * One reference to an object of `C`: the object's params, the principal it acts as (for a remote type), and its\n * incarnation: the host that made it as its caller sees it (a hold's caller over a link; two tabs are two\n * incarnations), the word `ctx.incarnation` uses.\n */\nexport type Presence<C extends Contract = Contract, P extends Principal = Principal> = {\n\treadonly params: ParamsOf<C>;\n\treadonly principal?: P;\n\treadonly incarnation: string;\n};\n\n/**\n * The references of one type, made by the host for its first `host.references(Type)` and kept from then on: one entry\n * per reference, added when it binds and removed when it ends, in the batch where that happens (derives over it\n * recompute there). While watched, a batch's changes are folded into the published list once, with one splice op per\n * removal and one for the additions; otherwise the list is built on its next read.\n */\nexport class References extends Source {\n\treadonly #entries = new Map<Holder, Presence>();\n\t/** The list as last published or read; `undefined` once it changed while nobody watched it. */\n\t#list: readonly Presence[] | undefined;\n\t/** Entries added since `#list`, in order (only while it is defined). */\n\t#added: Presence[] = [];\n\t/** Entries of `#list` removed since. */\n\treadonly #removed = new Set<Presence>();\n\t/** The ops folding `#list` forward, for the current batch's frame. */\n\t#ops: Op[] = [];\n\n\tget value(): JsonValue {\n\t\tthis.#fold();\n\t\t// Entries are JSON: params, a principal and a string.\n\t\treturn this.#list as unknown as JsonValue;\n\t}\n\n\t/** `holder` references `object`, added in the batch running now or the next one. */\n\tadd(object: ChordObject, holder: Holder, context: Context): void {\n\t\tthis.batch.within(() => {\n\t\t\tconst entry = this.record(object, holder);\n\t\t\tif (this.#follows()) this.#added.push(entry);\n\t\t\tthis.changed();\n\t\t}, context);\n\t}\n\n\t/** `holders` of `object` ended, removed in one batch. */\n\tremove(holders: Iterable<Holder>, context: Context): void {\n\t\tthis.batch.within(() => {\n\t\t\tconst follows = this.#follows();\n\t\t\tfor (const holder of holders) {\n\t\t\t\tconst entry = this.#entries.get(holder);\n\t\t\t\tif (entry === undefined) continue;\n\t\t\t\tthis.#entries.delete(holder);\n\t\t\t\tif (!follows) continue;\n\t\t\t\tconst added = this.#added.indexOf(entry);\n\t\t\t\tif (added === -1) this.#removed.add(entry);\n\t\t\t\telse this.#added.splice(added, 1);\n\t\t\t}\n\t\t\tthis.changed();\n\t\t}, context);\n\t}\n\n\t/** Records `holder` without a batch (the list being made) and returns its entry. */\n\trecord(object: ChordObject, holder: Holder): Presence {\n\t\tconst { principal, incarnation } = holder.caller;\n\t\tconst entry: Presence = {\n\t\t\tparams: object.params,\n\t\t\t...(object.served.kind === \"remote\" && principal !== undefined ? { principal } : {}),\n\t\t\tincarnation,\n\t\t};\n\t\tthis.#entries.set(holder, entry);\n\t\treturn entry;\n\t}\n\n\tdeliver(context: Context): void {\n\t\tconst value = this.value;\n\t\tconst ops = this.#ops;\n\t\tthis.#ops = [];\n\t\t// Listed once per change: the batch's first delivery carries all of them.\n\t\tif (ops.length > 0) this.publish(value, ops, false, context);\n\t}\n\n\t/**\n\t * Whether a change is folded into the published list: while watched (a watch read the list first). Otherwise the\n\t * list is dropped and built on its next read.\n\t */\n\t#follows(): boolean {\n\t\tif (this.watched && this.#list !== undefined) return true;\n\t\tthis.#list = undefined;\n\t\treturn false;\n\t}\n\n\t/**\n\t * Folds the changes since `#list` into a new list, once: a removal is one splice op at its index, the additions one\n\t * splice op at the end. Builds the list from the entries when there is none.\n\t */\n\t#fold(): void {\n\t\tif (this.#list === undefined) {\n\t\t\tthis.#list = [...this.#entries.values()];\n\t\t\tthis.#added = [];\n\t\t\tthis.#removed.clear();\n\t\t\tthis.#ops = [];\n\t\t\treturn;\n\t\t}\n\t\tif (this.#added.length === 0 && this.#removed.size === 0) return;\n\t\tlet list = this.#list;\n\t\tif (this.#removed.size > 0) {\n\t\t\tconst kept: Presence[] = [];\n\t\t\tfor (const entry of list) {\n\t\t\t\tif (this.#removed.has(entry)) this.#ops.push([\"p\", [], kept.length, 1, []]);\n\t\t\t\telse kept.push(entry);\n\t\t\t}\n\t\t\tthis.#removed.clear();\n\t\t\tlist = kept;\n\t\t}\n\t\tif (this.#added.length > 0) {\n\t\t\tthis.#ops.push([\"p\", [], list.length, 0, this.#added as unknown as JsonValue[]]);\n\t\t\tlist = [...list, ...this.#added];\n\t\t\tthis.#added = [];\n\t\t}\n\t\tthis.#list = list;\n\t}\n}\n"]}

package/dist/host/readiness.d.ts

@@ -0,0 +1,27 @@
+import { type Context } from "../context/index.ts";
+import type { FailureCause } from "../data/index.ts";
+import type { Caller } from "./ctx.ts";
+import type { AnyHost } from "./host.ts";
+import type { Request } from "./staging.ts";
+/**
+ * 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 declare class Readiness {
+    #private;
+    constructor(host: AnyHost, caller: Caller, requests: readonly Request[], shows: (cause: FailureCause | undefined) => void, context: Context);
+    /** What the successor waits for now: a request refused for good, or `waiting` for the first failed one. */
+    get cause(): FailureCause | undefined;
+    /**
+     * 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(): void;
+    /** Resolves once every request is ready, or at `due` (`Date.now()` time), whichever is first. */
+    ready(due: number): Promise<void>;
+    /** The successor's own requests bound: its bindings are let go (a dependency held only by them never ends). */
+    release(): void;
+}
+//# sourceMappingURL=readiness.d.ts.map

package/dist/host/readiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.d.ts","sourceRoot":"","sources":["../../src/host/readiness.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,OAAO,EAAmB,MAAM,qBAAqB,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C;;;;;GAKG;AACH,qBAAa,SAAS;;IAerB,YACC,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,SAAS,OAAO,EAAE,EAC5B,KAAK,EAAE,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,KAAK,IAAI,EAChD,OAAO,EAAE,OAAO,EAOhB;IAED,2GAA2G;IAC3G,IAAI,KAAK,IAAI,YAAY,GAAG,SAAS,CAEpC;IAED;;;OAGG;IACH,KAAK,IAAI,IAAI,CAyBZ;IAED,iGAAiG;IAC3F,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQtC;IAED,+GAA+G;IAC/G,OAAO,IAAI,IAAI,CAGd;CA6BD"}

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"}