@earendil-works/chord 1.5.0 → 1.5.1

package/dist/host/reference-source.js

@@ -0,0 +1,285 @@
+// A reference's member as consumers follow it (decision "References are the only indirection", §7): a consumer's
+// watches and derives over `ref.member` (or a key of a keyed member) attach here, and this passes them straight through
+// to the object instance's own document or derive (its watches and subscribers subscribe there: no extra hop on
+// commits, the commit's value and ops by reference). When the reference's target moves to a new instance (or a new
+// object of its identity), it moves them and sends one frame, a diff from the last value; while it points at nothing it
+// keeps the last value (a pointer, no copy), with one `failed` call when its target failed (none while it loads).
+import { diffRevisions } from "../delta/index.js";
+import { handedOut, Source, } from "../state/internal.js";
+import { Watch } from "../watch.js";
+const ENDED = { kind: "ended" };
+/** No failure told: a held value's `failure` while its target loads. */
+const NO_FAILURE = undefined;
+/**
+ * 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 class ReferenceSource extends Source {
+    #state = { kind: "unbound" };
+    /**
+     * Its watches and subscribers, each subscribed to the bound member while bound; held, they get nothing. Made by the
+     * first.
+     */
+    #passed;
+    /** What its watches had at a re-bind (`undefined` for no value: they had a failure), until the re-bind's frame. */
+    #framed;
+    /** Its reference: what a read throws while it never had a value (its failure, `not_ready`, or `released`). */
+    #owner;
+    constructor(batch, owner) {
+        super(batch);
+        this.#owner = owner;
+    }
+    /** Whether it never had a value (a watch waits for its reference's values first). */
+    get unbound() {
+        return this.#state.kind === "unbound";
+    }
+    get value() {
+        const state = this.#state;
+        switch (state.kind) {
+            case "bound":
+                return state.source.value;
+            case "held":
+                // A derive over a failed reference's member computes on its last value too (owner, G2: A).
+                return state.value;
+            case "unbound":
+                throw this.#owner.none();
+            default:
+                throw state.error;
+        }
+    }
+    /** What a new watch starts at: the bound member's start, the held value (after its failure), or the failure. */
+    start() {
+        const state = this.#state;
+        switch (state.kind) {
+            case "bound":
+                return state.source instanceof Source ? state.source.start() : { kind: "value", value: state.source.value };
+            case "held":
+                return state.failure === NO_FAILURE
+                    ? { kind: "value", value: state.value }
+                    : { kind: "failed", error: state.failure, last: state.value };
+            case "failed":
+                return { kind: "failed", error: state.error, last: state.last };
+            case "unbound":
+                throw this.#owner.none();
+            case "ended":
+                throw state.error;
+        }
+    }
+    /**
+     * 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) {
+        this.batch.assertOutside("watch");
+        const start = this.start();
+        if (start.kind === "failed" && start.last === undefined)
+            throw start.error;
+        const value = start.kind === "value" ? start.value : start.last;
+        const watch = new Watch(value, () => this.unsubscribe(watch), this.batch.reportListener);
+        this.subscribe(watch);
+        if (context.abortSignal !== undefined)
+            watch.observeAbort(context.abortSignal);
+        if (start.kind === "failed")
+            watch.fail(handedOut(start.error), context);
+        return watch;
+    }
+    /** Whether anything follows it: a watch, a subscriber or a derive (moving or ending it then needs a batch). */
+    get inUse() {
+        return this.watched || this.dependents.size > 0;
+    }
+    /** Whether a watch or a subscriber follows it (through the bound member). */
+    get watched() {
+        return (this.#passed?.size ?? 0) > 0;
+    }
+    /** Feeds `subscriber` the bound member's frames (it subscribes there) and the moves' frames. */
+    subscribe(subscriber) {
+        this.#passed ??= new Set();
+        this.#passed.add(subscriber);
+        const state = this.#state;
+        if (state.kind === "bound" && state.source instanceof Source)
+            state.source.subscribe(subscriber);
+    }
+    /** As `Source.unsubscribe`. */
+    unsubscribe(subscriber) {
+        this.#passed?.delete(subscriber);
+        const state = this.#state;
+        if (state.kind === "bound" && state.source instanceof Source)
+            state.source.unsubscribe(subscriber);
+    }
+    /** The bound member changed: its dependents are marked (its frames reach the subscribers directly). */
+    invalidate() {
+        for (const dependent of this.dependents)
+            dependent.invalidate();
+    }
+    /** The bound member's document was retired: its dependents carry the flag on. */
+    sourceRetired(visited) {
+        for (const dependent of this.dependents)
+            dependent.sourceRetired(visited);
+    }
+    /**
+     * 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) {
+        const state = this.#state;
+        if (state.kind === "ended" || (state.kind === "bound" && state.source === source))
+            return;
+        this.#leave();
+        if (this.watched)
+            this.#framed = { value: this.#shown() };
+        this.#state = { kind: "bound", source };
+        this.#hook(source);
+        // Marks the derives downstream: a failed one recomputes too (self-healing).
+        this.changed();
+    }
+    /** Its target loads (a restart, a retry, a new object not live yet): it keeps its last value, and tells nothing. */
+    hold() {
+        const state = this.#state;
+        if (state.kind === "held") {
+            // Its watches had the failure: the next value stays whole (`told`).
+            if (state.failure !== NO_FAILURE)
+                this.#state = { ...state, failure: NO_FAILURE };
+            return;
+        }
+        if (state.kind === "bound")
+            this.#keep(NO_FAILURE);
+    }
+    /**
+     * 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, context) {
+        // Kept: its stack made text now, so it keeps none of the failed instance's frames.
+        handedOut(error);
+        const state = this.#state;
+        if (state.kind === "held") {
+            if (state.failure !== NO_FAILURE)
+                return;
+            this.#state = { kind: "held", value: state.value, failure: error, told: true };
+        }
+        else if (state.kind === "bound") {
+            if (!this.#keep(error))
+                return;
+        }
+        else {
+            return;
+        }
+        this.#call({ kind: "failed", error }, context);
+    }
+    /**
+     * 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, context) {
+        const state = this.#state;
+        if (state.kind === "ended")
+            return;
+        const last = state.kind === "unbound" ? undefined : this.#lastGood();
+        this.#leave();
+        this.#state = { kind: "failed", error: handedOut(error), last };
+        this.#call({ kind: "failed", error }, context);
+        this.changed();
+    }
+    /**
+     * 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) {
+        this.#leave();
+        this.#state = { kind: "ended", error };
+        this.#framed = undefined;
+        // A copy: an ending watch unsubscribes itself.
+        const passed = this.#passed;
+        this.#passed = undefined;
+        if (passed !== undefined)
+            for (const subscriber of [...passed])
+                subscriber.end(ENDED);
+        for (const dependent of this.dependents)
+            dependent.invalidate();
+    }
+    /** Delivers a move's frame: the diff from the watches' value to the new member's. */
+    deliver(context) {
+        const framed = this.#framed;
+        this.#framed = undefined;
+        if (framed === undefined)
+            return;
+        let after;
+        try {
+            after = this.value;
+        }
+        catch (error) {
+            if (framed.value !== undefined)
+                this.#call({ kind: "failed", error: handedOut(error) }, context);
+            return;
+        }
+        const before = framed.value;
+        if (after === before)
+            return;
+        // After a failure (no value framed): whole, even when unchanged.
+        const ops = before === undefined ? [["r", after]] : diffRevisions(before, after);
+        if (ops.length > 0)
+            this.#call({ kind: "value", value: after, ops, retired: false }, context);
+    }
+    /**
+     * Stops following the bound member and keeps its value (`failure`: the failure it is held with); a member whose value
+     * throws becomes failed. Whether it holds a value.
+     */
+    #keep(failure) {
+        const state = this.#state;
+        const start = state.source instanceof Source ? state.source.start() : undefined;
+        this.#leave();
+        if (start === undefined || start.kind === "value") {
+            const value = start === undefined ? state.source.value : start.value;
+            this.#state = { kind: "held", value, failure, told: failure !== NO_FAILURE };
+            return true;
+        }
+        this.#state = { kind: "failed", error: handedOut(start.error), last: start.last };
+        return false;
+    }
+    /** A call of its own (a move's frame, a failure) to its watches and subscribers. */
+    #call(call, context) {
+        if (this.#passed !== undefined)
+            for (const subscriber of this.#passed)
+                subscriber.advance(call, context);
+    }
+    /**
+     * The value its watches have before a move; `undefined` when they had a failure since it (their next value is whole,
+     * `[["r", value]]`, even when unchanged).
+     */
+    #shown() {
+        const state = this.#state;
+        if (state.kind === "unbound" || (state.kind === "held" && state.told))
+            return undefined;
+        const start = this.start();
+        return start.kind === "value" ? start.value : undefined;
+    }
+    /** Its last good value, which watches opened while it is failed start at; `undefined` when it never had one. */
+    #lastGood() {
+        const start = this.start();
+        return start.kind === "value" ? start.value : start.last;
+    }
+    /** Starts reading `source`: its changes mark this source's dependents, its frames reach the subscribers. */
+    #hook(source) {
+        if (!(source instanceof Source))
+            return;
+        source.dependents.add(this);
+        if (this.#passed !== undefined)
+            for (const subscriber of this.#passed)
+                source.subscribe(subscriber);
+    }
+    /** Stops following the bound source, when bound: no more marks or frames from it. */
+    #leave() {
+        const state = this.#state;
+        if (state.kind !== "bound")
+            return;
+        const { source } = state;
+        if (!(source instanceof Source))
+            return;
+        source.dependents.delete(this);
+        if (this.#passed !== undefined)
+            for (const subscriber of this.#passed)
+                source.unsubscribe(subscriber);
+    }
+}
+//# sourceMappingURL=reference-source.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reference-source.js","sourceRoot":"","sources":["../../src/host/reference-source.ts"],"names":[],"mappings":"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","sourcesContent":["// A reference's member as consumers follow it (decision \"References are the only indirection\", §7): a consumer's\n// watches and derives over `ref.member` (or a key of a keyed member) attach here, and this passes them straight through\n// to the object instance's own document or derive (its watches and subscribers subscribe there: no extra hop on\n// commits, the commit's value and ops by reference). When the reference's target moves to a new instance (or a new\n// object of its identity), it moves them and sends one frame, a diff from the last value; while it points at nothing it\n// keeps the last value (a pointer, no copy), with one `failed` call when its target failed (none while it loads).\n\nimport type { Context } from \"../context/index.ts\";\nimport type { ChordError } from \"../data/index.ts\";\nimport { diffRevisions, type Op } from \"../delta/index.ts\";\nimport type { JsonValue } from \"../json.ts\";\nimport {\n\ttype Batch,\n\ttype Dependent,\n\ttype DeriveSource,\n\thandedOut,\n\tSource,\n\ttype Subscriber,\n\ttype WatchStart,\n} from \"../state/internal.ts\";\nimport { Watch, type WatchCall, type WatchEnd } from \"../watch.ts\";\n\n/**\n * Where a reference's source stands: never had a value (`unbound`: reads throw what its reference has instead),\n * following an instance's member, holding its last value while pointing at nothing (`failure` while its target is\n * failed: new watches start with it; `told`: its watches got a failure since that value, so the next is whole), failed\n * (a member its target's live variant lacks, or its compute threw when it was held: reads throw, `last` is the last\n * good value) or ended with its reference (nothing kept).\n */\ntype SourceState =\n\t| { readonly kind: \"unbound\" }\n\t| { readonly kind: \"bound\"; readonly source: DeriveSource }\n\t| { readonly kind: \"held\"; readonly value: JsonValue; readonly failure: unknown; readonly told: boolean }\n\t| { readonly kind: \"failed\"; readonly error: unknown; readonly last: JsonValue | undefined }\n\t| { readonly kind: \"ended\"; readonly error: ChordError };\n\n/** A reference owning its sources: what a read of one that never had a value throws. */\nexport interface SourceOwner {\n\tnone(): ChordError;\n}\n\nconst ENDED: WatchEnd = { kind: \"ended\" };\n\n/** No failure told: a held value's `failure` while its target loads. */\nconst NO_FAILURE = undefined;\n\n/**\n * One member (or key) of one reference. Bound, it is a dependent of the instance's member (its own dependents are\n * marked with it); its watches and subscribers subscribe to that member itself, so the member's frames reach them as\n * they are, and a derive member stays lazy while nothing follows it; holding or moving moves them.\n */\nexport class ReferenceSource extends Source implements Dependent {\n\t#state: SourceState = { kind: \"unbound\" };\n\t/**\n\t * Its watches and subscribers, each subscribed to the bound member while bound; held, they get nothing. Made by the\n\t * first.\n\t */\n\t#passed: Set<Subscriber> | undefined;\n\t/** What its watches had at a re-bind (`undefined` for no value: they had a failure), until the re-bind's frame. */\n\t#framed: { readonly value: JsonValue | undefined } | undefined;\n\t/** Its reference: what a read throws while it never had a value (its failure, `not_ready`, or `released`). */\n\treadonly #owner: SourceOwner;\n\n\tconstructor(batch: Batch, owner: SourceOwner) {\n\t\tsuper(batch);\n\t\tthis.#owner = owner;\n\t}\n\n\t/** Whether it never had a value (a watch waits for its reference's values first). */\n\tget unbound(): boolean {\n\t\treturn this.#state.kind === \"unbound\";\n\t}\n\n\tget value(): JsonValue {\n\t\tconst state = this.#state;\n\t\tswitch (state.kind) {\n\t\t\tcase \"bound\":\n\t\t\t\treturn state.source.value;\n\t\t\tcase \"held\":\n\t\t\t\t// A derive over a failed reference's member computes on its last value too (owner, G2: A).\n\t\t\t\treturn state.value;\n\t\t\tcase \"unbound\":\n\t\t\t\tthrow this.#owner.none();\n\t\t\tdefault:\n\t\t\t\tthrow state.error;\n\t\t}\n\t}\n\n\t/** What a new watch starts at: the bound member's start, the held value (after its failure), or the failure. */\n\tstart(): WatchStart {\n\t\tconst state = this.#state;\n\t\tswitch (state.kind) {\n\t\t\tcase \"bound\":\n\t\t\t\treturn state.source instanceof Source ? state.source.start() : { kind: \"value\", value: state.source.value };\n\t\t\tcase \"held\":\n\t\t\t\treturn state.failure === NO_FAILURE\n\t\t\t\t\t? { kind: \"value\", value: state.value }\n\t\t\t\t\t: { kind: \"failed\", error: state.failure, last: state.value };\n\t\t\tcase \"failed\":\n\t\t\t\treturn { kind: \"failed\", error: state.error, last: state.last };\n\t\t\tcase \"unbound\":\n\t\t\t\tthrow this.#owner.none();\n\t\t\tcase \"ended\":\n\t\t\t\tthrow state.error;\n\t\t}\n\t}\n\n\t/**\n\t * A watch subscribed to the bound member itself (as `Source.openWatch` starts one: on a failed member at its last\n\t * good value, the failure first).\n\t */\n\topenWatch(context: Context): Watch<JsonValue> {\n\t\tthis.batch.assertOutside(\"watch\");\n\t\tconst start = this.start();\n\t\tif (start.kind === \"failed\" && start.last === undefined) throw start.error;\n\t\tconst value = start.kind === \"value\" ? start.value : start.last!;\n\t\tconst watch: Watch<JsonValue> = new Watch(value, () => this.unsubscribe(watch), this.batch.reportListener);\n\t\tthis.subscribe(watch);\n\t\tif (context.abortSignal !== undefined) watch.observeAbort(context.abortSignal);\n\t\tif (start.kind === \"failed\") watch.fail(handedOut(start.error), context);\n\t\treturn watch;\n\t}\n\n\t/** Whether anything follows it: a watch, a subscriber or a derive (moving or ending it then needs a batch). */\n\tget inUse(): boolean {\n\t\treturn this.watched || this.dependents.size > 0;\n\t}\n\n\t/** Whether a watch or a subscriber follows it (through the bound member). */\n\tget watched(): boolean {\n\t\treturn (this.#passed?.size ?? 0) > 0;\n\t}\n\n\t/** Feeds `subscriber` the bound member's frames (it subscribes there) and the moves' frames. */\n\tsubscribe(subscriber: Subscriber): void {\n\t\tthis.#passed ??= new Set();\n\t\tthis.#passed.add(subscriber);\n\t\tconst state = this.#state;\n\t\tif (state.kind === \"bound\" && state.source instanceof Source) state.source.subscribe(subscriber);\n\t}\n\n\t/** As `Source.unsubscribe`. */\n\tunsubscribe(subscriber: Subscriber): void {\n\t\tthis.#passed?.delete(subscriber);\n\t\tconst state = this.#state;\n\t\tif (state.kind === \"bound\" && state.source instanceof Source) state.source.unsubscribe(subscriber);\n\t}\n\n\t/** The bound member changed: its dependents are marked (its frames reach the subscribers directly). */\n\tinvalidate(): void {\n\t\tfor (const dependent of this.dependents) dependent.invalidate();\n\t}\n\n\t/** The bound member's document was retired: its dependents carry the flag on. */\n\tsourceRetired(visited: Set<Dependent>): void {\n\t\tfor (const dependent of this.dependents) dependent.sourceRetired(visited);\n\t}\n\n\t/**\n\t * Follows `source`, an instance's member, inside a batch: watches get one frame from the last value (a full one\n\t * after a failure); derives downstream are marked and recompute, a failed one included (self-healing).\n\t */\n\tbind(source: DeriveSource): void {\n\t\tconst state = this.#state;\n\t\tif (state.kind === \"ended\" || (state.kind === \"bound\" && state.source === source)) return;\n\t\tthis.#leave();\n\t\tif (this.watched) this.#framed = { value: this.#shown() };\n\t\tthis.#state = { kind: \"bound\", source };\n\t\tthis.#hook(source);\n\t\t// Marks the derives downstream: a failed one recomputes too (self-healing).\n\t\tthis.changed();\n\t}\n\n\t/** Its target loads (a restart, a retry, a new object not live yet): it keeps its last value, and tells nothing. */\n\thold(): void {\n\t\tconst state = this.#state;\n\t\tif (state.kind === \"held\") {\n\t\t\t// Its watches had the failure: the next value stays whole (`told`).\n\t\t\tif (state.failure !== NO_FAILURE) this.#state = { ...state, failure: NO_FAILURE };\n\t\t\treturn;\n\t\t}\n\t\tif (state.kind === \"bound\") this.#keep(NO_FAILURE);\n\t}\n\n\t/**\n\t * Its target failed (`error`: its cause's, a refused version's, a removed type's), inside a batch: it keeps its last\n\t * value, its watches and subscribers get one failure call (once per failure) and stay open.\n\t */\n\tfail(error: ChordError, context: Context): void {\n\t\t// Kept: its stack made text now, so it keeps none of the failed instance's frames.\n\t\thandedOut(error);\n\t\tconst state = this.#state;\n\t\tif (state.kind === \"held\") {\n\t\t\tif (state.failure !== NO_FAILURE) return;\n\t\t\tthis.#state = { kind: \"held\", value: state.value, failure: error, told: true };\n\t\t} else if (state.kind === \"bound\") {\n\t\t\tif (!this.#keep(error)) return;\n\t\t} else {\n\t\t\treturn;\n\t\t}\n\t\tthis.#call({ kind: \"failed\", error }, context);\n\t}\n\n\t/**\n\t * Its target's live variant lacks the member, inside a batch: reads throw `error`; watches and subscribers get one\n\t * failure call and stay open (a later instance may bring the member back, as `[[\"r\", value]]`).\n\t */\n\tvanish(error: ChordError, context: Context): void {\n\t\tconst state = this.#state;\n\t\tif (state.kind === \"ended\") return;\n\t\tconst last = state.kind === \"unbound\" ? undefined : this.#lastGood();\n\t\tthis.#leave();\n\t\tthis.#state = { kind: \"failed\", error: handedOut(error), last };\n\t\tthis.#call({ kind: \"failed\", error }, context);\n\t\tthis.changed();\n\t}\n\n\t/**\n\t * Its reference ended, inside a batch: reads throw `error`, watches end `ended`, and derives over it are marked\n\t * (their next read throws it, no cached value stays).\n\t */\n\tend(error: ChordError): void {\n\t\tthis.#leave();\n\t\tthis.#state = { kind: \"ended\", error };\n\t\tthis.#framed = undefined;\n\t\t// A copy: an ending watch unsubscribes itself.\n\t\tconst passed = this.#passed;\n\t\tthis.#passed = undefined;\n\t\tif (passed !== undefined) for (const subscriber of [...passed]) subscriber.end(ENDED);\n\t\tfor (const dependent of this.dependents) dependent.invalidate();\n\t}\n\n\t/** Delivers a move's frame: the diff from the watches' value to the new member's. */\n\tdeliver(context: Context): void {\n\t\tconst framed = this.#framed;\n\t\tthis.#framed = undefined;\n\t\tif (framed === undefined) return;\n\t\tlet after: JsonValue;\n\t\ttry {\n\t\t\tafter = this.value;\n\t\t} catch (error) {\n\t\t\tif (framed.value !== undefined) this.#call({ kind: \"failed\", error: handedOut(error) }, context);\n\t\t\treturn;\n\t\t}\n\t\tconst before = framed.value;\n\t\tif (after === before) return;\n\t\t// After a failure (no value framed): whole, even when unchanged.\n\t\tconst ops: readonly Op[] = before === undefined ? [[\"r\", after]] : diffRevisions(before, after);\n\t\tif (ops.length > 0) this.#call({ kind: \"value\", value: after, ops, retired: false }, context);\n\t}\n\n\t/**\n\t * Stops following the bound member and keeps its value (`failure`: the failure it is held with); a member whose value\n\t * throws becomes failed. Whether it holds a value.\n\t */\n\t#keep(failure: unknown): boolean {\n\t\tconst state = this.#state as Extract<SourceState, { readonly kind: \"bound\" }>;\n\t\tconst start = state.source instanceof Source ? state.source.start() : undefined;\n\t\tthis.#leave();\n\t\tif (start === undefined || start.kind === \"value\") {\n\t\t\tconst value = start === undefined ? state.source.value : start.value;\n\t\t\tthis.#state = { kind: \"held\", value, failure, told: failure !== NO_FAILURE };\n\t\t\treturn true;\n\t\t}\n\t\tthis.#state = { kind: \"failed\", error: handedOut(start.error), last: start.last };\n\t\treturn false;\n\t}\n\n\t/** A call of its own (a move's frame, a failure) to its watches and subscribers. */\n\t#call(call: WatchCall<JsonValue>, context: Context): void {\n\t\tif (this.#passed !== undefined) for (const subscriber of this.#passed) subscriber.advance(call, context);\n\t}\n\n\t/**\n\t * The value its watches have before a move; `undefined` when they had a failure since it (their next value is whole,\n\t * `[[\"r\", value]]`, even when unchanged).\n\t */\n\t#shown(): JsonValue | undefined {\n\t\tconst state = this.#state;\n\t\tif (state.kind === \"unbound\" || (state.kind === \"held\" && state.told)) return undefined;\n\t\tconst start = this.start();\n\t\treturn start.kind === \"value\" ? start.value : undefined;\n\t}\n\n\t/** Its last good value, which watches opened while it is failed start at; `undefined` when it never had one. */\n\t#lastGood(): JsonValue | undefined {\n\t\tconst start = this.start();\n\t\treturn start.kind === \"value\" ? start.value : start.last;\n\t}\n\n\t/** Starts reading `source`: its changes mark this source's dependents, its frames reach the subscribers. */\n\t#hook(source: DeriveSource): void {\n\t\tif (!(source instanceof Source)) return;\n\t\tsource.dependents.add(this);\n\t\tif (this.#passed !== undefined) for (const subscriber of this.#passed) source.subscribe(subscriber);\n\t}\n\n\t/** Stops following the bound source, when bound: no more marks or frames from it. */\n\t#leave(): void {\n\t\tconst state = this.#state;\n\t\tif (state.kind !== \"bound\") return;\n\t\tconst { source } = state;\n\t\tif (!(source instanceof Source)) return;\n\t\tsource.dependents.delete(this);\n\t\tif (this.#passed !== undefined) for (const subscriber of this.#passed) source.unsubscribe(subscriber);\n\t}\n}\n"]}

package/dist/host/reference.d.ts

@@ -0,0 +1,321 @@
+import { type Context } from "../context/index.ts";
+import type { Contract, Implementation, ParamsOf } from "../contracts/index.ts";
+import { type CurrentVariants, type ShapeOf, type VariantImplementation } from "../contracts/internal.ts";
+import { ChordError, type FailureCause, type Principal } from "../data/index.ts";
+import { type KeyedSlot } from "../documents/internal.ts";
+import type { JsonValue } from "../json.ts";
+import { type Batch, type DeriveSource } from "../state/internal.ts";
+import type { NativeWatchable, Watch } from "../watch.ts";
+import type { PinnedKey } from "./attempt.ts";
+import { type Caller } from "./ctx.ts";
+import type { KeyedBinding } from "./members.ts";
+import type { ChordObject, Holder, Removal } from "./object.ts";
+import { type RefState } from "./ref-state.ts";
+import type { UnboundRequest } from "./unbound.ts";
+/**
+ * A reference: a local contract's members, or for a remote contract the members of the variant its object chose,
+ * narrowed by `variant`; and its state, `retry()` and `release()`. Every use after release throws.
+ */
+export type Reference<C extends Contract> = ShapeOf<C>["kind"] extends "local" ? Implementation<C> & Lifecycle : InVariants<C, never>;
+/** What `host.hold` returns: a reference whose `variant` is `undefined` until its first binding. */
+export type Held<C extends Contract> = ShapeOf<C>["kind"] extends "local" ? Implementation<C> & Lifecycle : InVariants<C, undefined>;
+/** A remote reference narrowed to some of its variants. */
+export type RefIn<C extends Contract, V extends string> = Extract<Reference<C>, {
+    readonly variant: V;
+}>;
+/** One member of a remote reference's union per variant; `Unbound` is what `variant` may also be. */
+type InVariants<C extends Contract, Unbound> = {
+    [V in keyof CurrentVariants<C>]: {
+        readonly variant: V | Unbound;
+    } & VariantImplementation<CurrentVariants<C>[V]> & Lifecycle;
+}[keyof CurrentVariants<C>];
+/** What every reference has besides its members. */
+type Lifecycle = {
+    /** The reference's state: loading, live, failed or released; watches get every change. */
+    readonly state: NativeWatchable<RefState>;
+    /**
+     * Asks a failed object for an attempt now (the backoff skipped, a broken one renewed); an object parked on failed
+     * dependencies passes it on to them, once; otherwise nothing.
+     */
+    retry(): void;
+    release(): void;
+};
+/**
+ * What a binding is bound to: an object on this host (`ChordObject`), or an object held over a path, the parent link
+ * or a route address (`RemoteObject`). It tells its holders of each change of `state`.
+ */
+export interface Target {
+    /** Where it is: an object on this host, or one held over a link (another host decides what it serves). */
+    readonly kind: "local" | "remote";
+    /** The object in errors: its type, and its params key when it has params. */
+    readonly label: string;
+    /** Its state as its references show it. */
+    readonly state: RefState;
+    /**
+     * Its state as a reference of `version` and `fingerprint` sees it: on this host `live` also while a restart's open
+     * old attempt binds that version (decision "Reload restarts every affected object", rule 5); `state` over a link.
+     */
+    stateFor(version: number, fingerprint: string): RefState;
+    /** Whether its state members have values: live once, for a remote object bound once. */
+    readonly hydrated: boolean;
+    /** The variant bound last; `undefined` for a local object and before the first binding. */
+    readonly variant: string | undefined;
+    /** The error of its last failure (an attempt's, or the dependencies it is parked on) while none went live since. */
+    readonly lastFailure: ChordError | undefined;
+    /** Its instance id while it activates on this host (Q5); `undefined` otherwise and over a link. */
+    readonly activationId: string | undefined;
+    /**
+     * Whether it holds up this host's start barrier: an object here without its first outcome (decision (a)); a remote
+     * object never does.
+     */
+    readonly blocksFirstPass: boolean;
+    /** Counts `binding` as a reference; the binding reads `state` itself. */
+    hold(binding: Binding): void;
+    /** `binding` was released. */
+    unhold(binding: Binding): void;
+    /** Calls a method of the live object for `caller`, bound at `version` (an older one is mapped, Q10). */
+    call(method: string, args: unknown, context: Context, caller: Caller, version: number): Promise<unknown>;
+    /**
+     * What a reference of `version` follows for state member `member` now (decision "References are the only
+     * indirection"): the live instance's member (a replica over a link), or nothing (`loading`, or `failed` with the
+     * cause's error), with the member a reference takes its last value from.
+     */
+    followed(member: string, version: number): Followed;
+    /** The instance its references follow now (they attach to it); `undefined` once it stopped changing. */
+    readonly attachable: Attachable | undefined;
+    /** Its live instance (a reference's keys pin there; a new one, they pin again); `undefined` when not live. */
+    readonly instance: unknown;
+    /** The keyed member `member` of the live object: its ultimate slot (slice 6a §12; only local objects have any). */
+    keyedMember(member: string): KeyedSlot;
+    /**
+     * How a consumer of `version` reads keyed member `member`'s documents: mapped back to its version when older
+     * (slice 7b §7), `undefined` when as they are; `contract_mismatch` when the provider refuses it.
+     */
+    keyedMapping(member: string, version: number): ((current: JsonValue) => JsonValue) | undefined;
+    /**
+     * Pins `key` of keyed member `member` on the live instance, loaded, as a consumer of `version` reads it (mapped when
+     * older); only a live local object has keyed members.
+     */
+    pinKey(member: string, key: string, version: number, context: Context): Promise<PinnedKey>;
+    /**
+     * `ref.retry()`, as one step of `walk`: an attempt now if failed; an object parked on failed dependencies passes it
+     * on; ignored otherwise.
+     */
+    retry(walk: RetryWalk): void;
+    /**
+     * The chain of activation waits from this object to `target`, both included (Q5); `undefined` when there is none.
+     * `visited` keeps a search over shared dependencies linear in the waits.
+     */
+    pathTo(target: ChordObject, visited: Set<Target>): ChordObject[] | undefined;
+}
+/** An instance a reference attaches to (`Target.attachable`): it keeps last values in that instance's variant. */
+export type Attachable = {
+    readonly variant: string | undefined;
+};
+/**
+ * What a reference follows of its target for one state member (`Target.followed`): the member of the instance it
+ * follows (`instance`, still changing), a member its live variant lacks (`invalid/member`), or nothing: its target loads
+ * (no call) or failed (one `failed` call with the cause's error); `last` is the member of `instance`, which stopped
+ * changing, that a reference attached to it takes a last value from (never one it never attached to).
+ */
+export type Followed = {
+    readonly kind: "live";
+    readonly source: DeriveSource;
+    readonly instance: unknown;
+} | {
+    readonly kind: "lacking";
+    readonly error: ChordError;
+} | {
+    readonly kind: "loading";
+    readonly last: DeriveSource | undefined;
+    readonly instance: unknown;
+} | {
+    readonly kind: "failed";
+    readonly error: ChordError;
+    readonly last: DeriveSource | undefined;
+    readonly instance: unknown;
+};
+/**
+ * One retry's walk through parked objects on this host (dependency model §3.7, audit A5): the objects it reached (one
+ * reached again, through a diamond, ignores it) and the hop budget a `retry` message to another host carries (none is
+ * sent at 0, so a waiting ring of hosts stops).
+ */
+export type RetryWalk = {
+    readonly visited: Set<ChordObject>;
+    readonly hops: number;
+};
+/** A walk starting here: `ref.retry()`'s, with the first host's budget, or a `retry` message's, with one hop less. */
+export declare function retryWalk(hops?: number): RetryWalk;
+/** A reference's params as L1 checked them, with their identity key. */
+export type CheckedParams = {
+    readonly params: ParamsOf<Contract>;
+    readonly key: string;
+};
+/**
+ * A reference's binding to its object: counted by the object as one of its references while bound, and told of each
+ * change of its state. Calls run while live, park while loading (sent in order once live) and reject while failed.
+ * Released, or ended with its object, it ends the watches taken through it and rejects the calls made through it.
+ */
+export declare class Binding implements Holder, UnboundRequest {
+    #private;
+    readonly reference: Reference<Contract>;
+    /** Who calls through this reference: the principal it was got as, and this host's incarnation. */
+    readonly caller: Caller;
+    constructor(contract: Contract, batch: Batch, dependent: ChordObject | undefined, caller: Caller, parkTimeout: number);
+    /** The consumer's contract: its version is the binding's. Only an unreleased binding is asked. */
+    get contract(): Contract;
+    /** The object whose attempt declared this reference, until it is released. */
+    get dependent(): ChordObject | undefined;
+    /** Whom it acts for (the unbound index's revocation). */
+    get principal(): Principal | undefined;
+    /** The reference's state. */
+    get refState(): RefState;
+    /** The object it is bound to; `undefined` while it is not bound. */
+    get target(): Target | undefined;
+    /** The object in errors: its label once bound, else the contract's name. */
+    get label(): string;
+    /** The error of the object's last failure while none went live since, or of the check that left it unbound. */
+    get lastFailure(): ChordError | undefined;
+    /**
+     * Binds to `target`, which counts this binding as a reference; its members and keys follow what `target` shows now
+     * (one frame from their last values), and the reference takes its state.
+     */
+    bind(target: Target): void;
+    /** Whether its members or keys were used: `retarget` moves them (in a batch). */
+    get following(): boolean;
+    /**
+     * Inside a batch when `following`: its members and keys follow what its object shows now (`Target.followed`): the live instance's
+     * members (moved there, one frame each), or their last values (one `failed` call for a failure). The first time it
+     * points at nothing, every member of its version gets its last value, read or not.
+     */
+    retarget(): void;
+    /**
+     * Its object left it (slice 7b §6): its type was removed, or its provider no longer binds its version. The request
+     * waits unbound with `removal.cause` in the host's index, its members and keys keeping their last values (taken from
+     * the instance it leaves; one `failed` call), and binds again, by name, when a publication serves it: its members
+     * move to the next object's instance and its keys pin there again (one frame each); parked calls flush or reject;
+     * presence lists it again.
+     */
+    removed(removal: Removal): void;
+    /**
+     * Leaves the reference unbound in the host's unbound index (`leave` takes it out): `loading` before the publication
+     * (no `cause`), else `failed` with `cause` (`waiting`); `place` checks it again when the index wakes it.
+     */
+    wait(cause: FailureCause | undefined, place: () => void, leave: () => void): void;
+    /** Woken by the unbound index (out of it already): checked again where it goes. */
+    wake(): void;
+    /**
+     * A reference that cannot be bound (where it goes refused it): failed broken with `cause` until `ref.retry()` runs
+     * `bind` again (a route's `authorize` may admit it later).
+     */
+    refuse(cause: FailureCause, bind: () => void): void;
+    /**
+     * The state may have changed: `ref.state`'s watches are told; live sends the parked calls in order, failed
+     * rejects them with the cause; waits for a state decide; the object whose attempt declared it re-evaluates.
+     */
+    moved(): void;
+    /** Whether presence lists show it (§19). */
+    get listed(): boolean;
+    /** Keeps it out of presence lists, before it binds: a restart's readiness binding is no consumer of its own. */
+    unlist(): void;
+    /** Resolves once `done(state)` holds, checked now and at every change; rejects at its end or `context`'s abort. */
+    until(done: (state: RefState) => boolean, context: Context): Promise<void>;
+    /** Resolves when the reference is live; rejects with a broken failure's error, or its end. Getters wait for it. */
+    live(context: Context): Promise<void>;
+    /**
+     * The state member behind `member`, as consumers follow it (`ReferenceSource`): the instance's member while its
+     * object is live, its last value while it points at nothing; reads throw `released`, the failure's error, or
+     * `not_ready` when it never had a value.
+     */
+    member(member: string): DeriveSource;
+    /** What a read of a member that never had a value throws: `released`, the failure's error, or `not_ready`. */
+    none(): ChordError;
+    /** The keyed member `member`'s slot (slice 6a §12), as `member` resolves a state member. */
+    keyedSlot(member: string): KeyedSlot;
+    /** How this reference reads keyed member `member`'s documents (`Target.keyedMapping`), as `keyedSlot` resolves. */
+    keyedMapping(member: string): ((current: JsonValue) => JsonValue) | undefined;
+    /**
+     * Holds `key` of keyed member `member` (a key watch, a factory's `at(key)`, an object re-exposing this member): its
+     * source, pinned on the live instance and following its object's instances (`ReferenceKeys`); `release` once.
+     */
+    pinKey(member: string, key: string, context: Context): Promise<PinnedKey>;
+    /**
+     * A watch of `member` that ends when this reference is released, through its member (`ReferenceSource`): opened at
+     * once once it has a value (its last one while its object is not live, frames again when it is); before its first
+     * value it waits for its object's (`firstValues`: through failures, until the reference ends or `context` aborts).
+     */
+    watch(member: string, context: Context): Promise<Watch<JsonValue>>;
+    /**
+     * Resolves once its object's members have values (its first binding, for a watch on a reference that never had any);
+     * rejects only when the reference ends (released, revoked, its host closed) or `context` aborts: a failure is waited
+     * through (Opus G3).
+     */
+    firstValues(context: Context): Promise<void>;
+    /** Resolves once the object's members have values; rejects when the reference fails or is released first. */
+    hydrated(context: Context): Promise<void>;
+    /**
+     * Ends `watch` when this reference is released; returns it. A watch opened while the reference was released (an
+     * async keyed watch racing `release`) is ended at once, its pin with it, and the caller gets `released`.
+     */
+    follow<W extends Watch<JsonValue>>(watch: W): W;
+    /**
+     * `ref.member.at(key)`: only while its object's factory runs (the reference not yet bound); pinned once bound
+     * (`pinKeys`), released with the reference.
+     */
+    at(member: string, key: string): KeyedMemberAt;
+    /** Whether its object's factory pinned keys on it (`at(key)`). */
+    get pinsKeys(): boolean;
+    /**
+     * Pins the keys of `at(key)` on the live object's keyed members and loads those not in memory, before the
+     * dependent goes live (slice 6a §12); `undefined` when there are none. A failed load rejects.
+     */
+    pinKeys(context: Context): Promise<void> | undefined;
+    /**
+     * `ref.retry()`, as a step of `walk` (a new one for `ref.retry()`, passed on through parked objects): the object is
+     * asked for an attempt now (ignored unless failed; a parked one passes it on); a refused reference is placed again;
+     * one waiting in the index is left as it is (an event wakes it).
+     */
+    retry(walk?: RetryWalk): void;
+    /** Releases the reference (idempotent); the object may end when it was its last. */
+    release(): void;
+    /**
+     * Ends the reference without releasing it from its object (it ended): watches end, calls (running and parked)
+     * reject with `error`, `ref.state` is `ended` with it; the object whose attempt declared it checks again.
+     */
+    end(error: ChordError): void;
+}
+/**
+ * `ref.member.at(key)`: the key's source across the object's attempts once the reference is bound and the key held
+ * (`pin`), until the reference ends (`release`, exactly once): then it drops the source (a retained reference keeps no
+ * provider).
+ */
+declare class KeyedMemberAt {
+    #private;
+    readonly member: string;
+    readonly key: string;
+    constructor(binding: Binding, member: string, key: string);
+    /** The key's source; `not_ready` before it is held, `released` after. */
+    get source(): DeriveSource;
+    get value(): JsonValue;
+    watch(context: Context): Promise<Watch<JsonValue>>;
+    /**
+     * Holds the key through `binding` (once), loaded, mapped to an older binding's version (slice 7b §7); nothing once
+     * released (a hold that lands then is released).
+     */
+    pin(binding: Binding, context: Context): Promise<void>;
+    /** Releases the pin and drops the source (once). */
+    release(): void;
+}
+/**
+ * What a keyed member's value is (slice 6a §12): a keyed document handle's slot, or a reference's keyed member
+ * (re-exposed); `undefined` for anything else.
+ */
+export declare function resolveKeyed(value: unknown): KeyedBinding | undefined;
+/**
+ * The watchable Chord follows behind a state member or a derive source (Q14): a source or a constant itself, a
+ * singleton handle's slot, a reference member's provider member, a keyed member's pinned key (a key source itself for
+ * `handle.at(key)`); `undefined` for anything else, a native watchable included.
+ */
+export declare function resolveWatchable(value: unknown): DeriveSource | undefined;
+export {};
+//# sourceMappingURL=reference.d.ts.map