@earendil-works/chord 1.4.0 → 1.5.1

package/dist/host/ctx.js

@@ -0,0 +1,200 @@
+// The `ctx` a method handler gets (§8): its call's context, who called, the calling host's incarnation, call-scoped
+// references and child spans (`ctx.trace`, slice 9), its node of the call chain (old work during a reload); and the
+// abort signal of a call's context, linked to long-lived sources until it settles.
+import { withAbortSignal, withoutAbortSignal, withTelemetry } from "../context/index.js";
+import { ChordError } from "../data/index.js";
+import { ended, untraced } from "../telemetry.js";
+import { CALL_CHAIN } from "./old-work.js";
+/**
+ * The ctx of one handler run (or root scope): its references are released by `settle` when it settled. A method
+ * call's ctx is its own node of the call chain (`on`: the attempt it runs on), so the chain costs no allocation.
+ */
+export class CallContext {
+    principal;
+    incarnation;
+    #context;
+    #host;
+    /** The attempt a method call runs on; `undefined` for a root scope, a routine or a job run (no chain node). */
+    #on;
+    /** The references taken with `get`; `undefined` once the handler settled. */
+    #references = [];
+    /** Aborted when the handler settles: a `get` still waiting gives up and releases its reference. By the first. */
+    #settling;
+    constructor(context, caller, host, on) {
+        this.#context = context;
+        this.principal = caller.principal;
+        this.incarnation = caller.incarnation;
+        this.#host = host;
+        this.#on = on;
+    }
+    get abortSignal() {
+        return this.#context.abortSignal;
+    }
+    get telemetry() {
+        return this.#context.telemetry;
+    }
+    value(key) {
+        // A method call's ctx is its chain node; the key's type is `CallNode`, which this is.
+        if (key.token === CALL_CHAIN.token && this.#on !== undefined)
+            return this;
+        return this.#context.value(key);
+    }
+    /** The attempt its handler runs on (only read through `CALL_CHAIN`, which a method call's ctx answers). */
+    get on() {
+        return this.#on;
+    }
+    /** The chain of the call that made this one. */
+    up() {
+        return this.#context.value(CALL_CHAIN);
+    }
+    toString() {
+        return `${this.#context}.Ctx`;
+    }
+    /** Its host's `chord.host`, for its child spans. */
+    get spanHost() {
+        return this.#host.spanHost;
+    }
+    async get(Type, params, options = {}) {
+        // A settled scope refuses `released` whatever aborted it; an aborted call creates nothing.
+        if (this.#references === undefined)
+            throw settled(Type);
+        this.#context.abortSignal?.throwIfAborted();
+        // Made for the caller: its principal and its origin's incarnation travel with the reference's holds.
+        const caller = { principal: this.principal, incarnation: this.incarnation };
+        this.#settling ??= new AbortController();
+        // Under this ctx itself: the getter belongs to the call's chain (old work during a reload).
+        const scoped = withLinkedAbortSignal(this.#settling.signal, this);
+        let binding;
+        try {
+            binding = await this.#host.acquire(Type, params, caller, scoped.context, options);
+        }
+        catch (error) {
+            throw this.#references === undefined ? settled(Type) : error;
+        }
+        finally {
+            scoped.release();
+        }
+        // A get that finished in the turn its handler settled: nobody releases its reference later.
+        if (this.#references === undefined) {
+            binding.release();
+            throw settled(Type);
+        }
+        this.#references.push(binding);
+        // The binding was built from `Type`'s members.
+        return binding.reference;
+    }
+    trace(name, attributes, fn) {
+        return traceUnder(this, name, attributes, fn);
+    }
+    /** Its child under `span` (`ctx.trace`), every member kept. */
+    traced(span) {
+        return new SpanCtx(this, span);
+    }
+    /** The handler settled: its references are released, waiting gets give up, and `get` throws from now on. */
+    settle() {
+        const references = this.#references ?? [];
+        this.#references = undefined;
+        this.#settling?.abort();
+        for (const binding of references)
+            binding.release();
+    }
+}
+/**
+ * `ctx.trace` of `ctx`: `fn` in a child span with its child ctx; with nothing recorded, `fn` with `ctx` itself. Either
+ * way a synchronous throw of `fn` rejects (review L5: recording changes nothing `fn` sees but its span).
+ */
+function traceUnder(ctx, name, attributes, fn) {
+    const parent = ctx.telemetry;
+    // Plugin code: a synchronous throw becomes the rejection.
+    if (untraced(parent))
+        return (async () => fn(ctx))();
+    return parent.startSpan({ name, attributes: { "chord.host": ctx.spanHost, ...attributes } }, async (span) => {
+        try {
+            return await fn(ctx.traced(span));
+        }
+        catch (error) {
+            ended(span, "trace_failed", error, ctx.abortSignal);
+            throw error;
+        }
+    });
+}
+/** A ctx under a child span (`ctx.trace`): its parent's caller, signal and references, `telemetry` the span. */
+export class SpanCtx {
+    #parent;
+    #context;
+    constructor(parent, span) {
+        this.#parent = parent;
+        this.#context = withTelemetry(span, parent);
+    }
+    /** Its host's `chord.host`, for its child spans. */
+    get spanHost() {
+        return this.#parent.spanHost;
+    }
+    get principal() {
+        return this.#parent.principal;
+    }
+    get incarnation() {
+        return this.#parent.incarnation;
+    }
+    get abortSignal() {
+        return this.#context.abortSignal;
+    }
+    get telemetry() {
+        return this.#context.telemetry;
+    }
+    value(key) {
+        return this.#context.value(key);
+    }
+    toString() {
+        return `${this.#parent}.Trace`;
+    }
+    get(Type, params, options) {
+        return this.#parent.get(Type, params, options);
+    }
+    trace(name, attributes, fn) {
+        return traceUnder(this, name, attributes, fn);
+    }
+    /** Its child under `span`, of its own kind. */
+    traced(span) {
+        return new SpanCtx(this, span);
+    }
+}
+function settled(Type) {
+    return new ChordError({
+        code: "released",
+        reason: "settled",
+        message: `${Type.name}: ctx.get after its call settled`,
+    });
+}
+/**
+ * A child of `context` aborted by `signal` and by the caller's signal (the caller's reason first) until `release()`,
+ * which the call runs when it settles. Not `AbortSignal.any`: before Node 24.16.0 it keeps cleanup entries per call for
+ * as long as its sources live (nodejs/node#62367), and a call's sources (its attempt, its reference) live long.
+ * Without a caller's signal the child is aborted by `signal` itself and `release` does nothing.
+ */
+export function withLinkedAbortSignal(signal, context) {
+    const caller = context.abortSignal;
+    if (caller === undefined)
+        return { context: withAbortSignal(signal, context), release: NOTHING };
+    const linked = new AbortController();
+    const listeners = [caller, signal].map((source) => {
+        const forward = () => {
+            release();
+            linked.abort(source.reason);
+        };
+        return [source, forward];
+    });
+    const release = () => {
+        for (const [source, forward] of listeners)
+            source.removeEventListener("abort", forward);
+    };
+    const aborted = listeners.find(([source]) => source.aborted);
+    if (aborted !== undefined)
+        linked.abort(aborted[0].reason);
+    else
+        for (const [source, forward] of listeners)
+            source.addEventListener("abort", forward, { once: true });
+    return { context: withAbortSignal(linked.signal, withoutAbortSignal(context)), release };
+}
+const NOTHING = () => { };
+//# sourceMappingURL=ctx.js.map

package/dist/host/ctx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ctx.js","sourceRoot":"","sources":["../../src/host/ctx.ts"],"names":[],"mappings":"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","sourcesContent":["// The `ctx` a method handler gets (§8): its call's context, who called, the calling host's incarnation, call-scoped\n// references and child spans (`ctx.trace`, slice 9), its node of the call chain (old work during a reload); and the\n// abort signal of a call's context, linked to long-lived sources until it settles.\n\nimport type { SpanAttributes, TelemetrySpan } from \"@earendil-works/pi-telemetry\";\nimport { type Context, type ContextKey, withAbortSignal, withoutAbortSignal, withTelemetry } from \"../context/index.ts\";\nimport type { Contract, ParamsOf } from \"../contracts/index.ts\";\nimport { ChordError, type Principal } from \"../data/index.ts\";\nimport { ended, untraced } from \"../telemetry.ts\";\nimport type { AnyHost, GetOptions } from \"./host.ts\";\nimport { CALL_CHAIN, type CallNode, type OldWorkSource } from \"./old-work.ts\";\nimport type { Binding, Reference } from \"./reference.ts\";\n\n/** A handler's context. */\nexport interface Ctx<P extends Principal = Principal> extends Context {\n\t/** The caller as its link stamped it; on a local object's handler the host's principal (none on a client). */\n\treadonly principal: P | undefined;\n\t/** The calling host's incarnation over a link, this host's otherwise (R20). */\n\treadonly incarnation: string;\n\t/**\n\t * A reference as the caller (`principal`) sees it, released when the handler settles; afterwards `get` throws\n\t * `released`.\n\t */\n\tget<C extends Contract>(Type: C, params: ParamsOf<C>, options?: GetOptions): Promise<Reference<C>>;\n\t/**\n\t * Runs `fn` in a child span `name` of this ctx's span (`telemetry`) with its host's `chord.host` and `attributes`:\n\t * `fn` gets a child ctx (the same principal, incarnation, signal and `get`, its references this ctx's), so calls\n\t * inside are parented under it. A throw marks the span failed (`trace_failed`; a cancel keeps it ok) and is rethrown.\n\t * Without an adapter that records, `fn` gets this ctx.\n\t */\n\ttrace<T>(name: string, attributes: SpanAttributes, fn: (ctx: Ctx<P>) => Promise<T>): Promise<T>;\n}\n\n/** Who makes a call: the principal it acts as and its host's incarnation. */\nexport type Caller = { readonly principal: Principal | undefined; readonly incarnation: string };\n\n/**\n * The ctx of one handler run (or root scope): its references are released by `settle` when it settled. A method\n * call's ctx is its own node of the call chain (`on`: the attempt it runs on), so the chain costs no allocation.\n */\nexport class CallContext implements Ctx, CallNode {\n\treadonly principal: Principal | undefined;\n\treadonly incarnation: string;\n\treadonly #context: Context;\n\treadonly #host: AnyHost;\n\t/** The attempt a method call runs on; `undefined` for a root scope, a routine or a job run (no chain node). */\n\treadonly #on: OldWorkSource | undefined;\n\t/** The references taken with `get`; `undefined` once the handler settled. */\n\t#references: Binding[] | undefined = [];\n\t/** Aborted when the handler settles: a `get` still waiting gives up and releases its reference. By the first. */\n\t#settling: AbortController | undefined;\n\n\tconstructor(context: Context, caller: Caller, host: AnyHost, on?: OldWorkSource) {\n\t\tthis.#context = context;\n\t\tthis.principal = caller.principal;\n\t\tthis.incarnation = caller.incarnation;\n\t\tthis.#host = host;\n\t\tthis.#on = on;\n\t}\n\n\tget abortSignal(): AbortSignal | undefined {\n\t\treturn this.#context.abortSignal;\n\t}\n\n\tget telemetry(): Context[\"telemetry\"] {\n\t\treturn this.#context.telemetry;\n\t}\n\n\tvalue<T>(key: ContextKey<T>): T | undefined {\n\t\t// A method call's ctx is its chain node; the key's type is `CallNode`, which this is.\n\t\tif (key.token === CALL_CHAIN.token && this.#on !== undefined) return this as unknown as T;\n\t\treturn this.#context.value(key);\n\t}\n\n\t/** The attempt its handler runs on (only read through `CALL_CHAIN`, which a method call's ctx answers). */\n\tget on(): OldWorkSource {\n\t\treturn this.#on!;\n\t}\n\n\t/** The chain of the call that made this one. */\n\tup(): CallNode | undefined {\n\t\treturn this.#context.value(CALL_CHAIN);\n\t}\n\n\ttoString(): string {\n\t\treturn `${this.#context}.Ctx`;\n\t}\n\n\t/** Its host's `chord.host`, for its child spans. */\n\tget spanHost(): string {\n\t\treturn this.#host.spanHost;\n\t}\n\n\tasync get<C extends Contract>(Type: C, params: ParamsOf<C>, options: GetOptions = {}): Promise<Reference<C>> {\n\t\t// A settled scope refuses `released` whatever aborted it; an aborted call creates nothing.\n\t\tif (this.#references === undefined) throw settled(Type);\n\t\tthis.#context.abortSignal?.throwIfAborted();\n\t\t// Made for the caller: its principal and its origin's incarnation travel with the reference's holds.\n\t\tconst caller = { principal: this.principal, incarnation: this.incarnation };\n\t\tthis.#settling ??= new AbortController();\n\t\t// Under this ctx itself: the getter belongs to the call's chain (old work during a reload).\n\t\tconst scoped = withLinkedAbortSignal(this.#settling.signal, this);\n\t\tlet binding: Binding;\n\t\ttry {\n\t\t\tbinding = await this.#host.acquire(Type, params, caller, scoped.context, options);\n\t\t} catch (error) {\n\t\t\tthrow this.#references === undefined ? settled(Type) : error;\n\t\t} finally {\n\t\t\tscoped.release();\n\t\t}\n\t\t// A get that finished in the turn its handler settled: nobody releases its reference later.\n\t\tif (this.#references === undefined) {\n\t\t\tbinding.release();\n\t\t\tthrow settled(Type);\n\t\t}\n\t\tthis.#references.push(binding);\n\t\t// The binding was built from `Type`'s members.\n\t\treturn binding.reference as Reference<C>;\n\t}\n\n\ttrace<T>(name: string, attributes: SpanAttributes, fn: (ctx: Ctx) => Promise<T>): Promise<T> {\n\t\treturn traceUnder(this, name, attributes, fn);\n\t}\n\n\t/** Its child under `span` (`ctx.trace`), every member kept. */\n\ttraced(span: TelemetrySpan): Ctx {\n\t\treturn new SpanCtx(this, span);\n\t}\n\n\t/** The handler settled: its references are released, waiting gets give up, and `get` throws from now on. */\n\tsettle(): void {\n\t\tconst references = this.#references ?? [];\n\t\tthis.#references = undefined;\n\t\tthis.#settling?.abort();\n\t\tfor (const binding of references) binding.release();\n\t}\n}\n\n/**\n * A ctx that makes its child under a span (`ctx.trace`): the same kind of ctx (a job's has `jobId` and `state`), and\n * its host's `chord.host`.\n */\ntype Traceable = Ctx & { readonly spanHost: string; traced(span: TelemetrySpan): Ctx };\n\n/**\n * `ctx.trace` of `ctx`: `fn` in a child span with its child ctx; with nothing recorded, `fn` with `ctx` itself. Either\n * way a synchronous throw of `fn` rejects (review L5: recording changes nothing `fn` sees but its span).\n */\nfunction traceUnder<T>(\n\tctx: Traceable,\n\tname: string,\n\tattributes: SpanAttributes,\n\tfn: (ctx: Ctx) => Promise<T>,\n): Promise<T> {\n\tconst parent = ctx.telemetry;\n\t// Plugin code: a synchronous throw becomes the rejection.\n\tif (untraced(parent)) return (async () => fn(ctx))();\n\treturn parent.startSpan({ name, attributes: { \"chord.host\": ctx.spanHost, ...attributes } }, async (span) => {\n\t\ttry {\n\t\t\treturn await fn(ctx.traced(span));\n\t\t} catch (error) {\n\t\t\tended(span, \"trace_failed\", error, ctx.abortSignal);\n\t\t\tthrow error;\n\t\t}\n\t});\n}\n\n/** A ctx under a child span (`ctx.trace`): its parent's caller, signal and references, `telemetry` the span. */\nexport class SpanCtx implements Ctx {\n\treadonly #parent: Traceable;\n\treadonly #context: Context;\n\n\tconstructor(parent: Traceable, span: TelemetrySpan) {\n\t\tthis.#parent = parent;\n\t\tthis.#context = withTelemetry(span, parent);\n\t}\n\n\t/** Its host's `chord.host`, for its child spans. */\n\tget spanHost(): string {\n\t\treturn this.#parent.spanHost;\n\t}\n\n\tget principal(): Principal | undefined {\n\t\treturn this.#parent.principal;\n\t}\n\n\tget incarnation(): string {\n\t\treturn this.#parent.incarnation;\n\t}\n\n\tget abortSignal(): AbortSignal | undefined {\n\t\treturn this.#context.abortSignal;\n\t}\n\n\tget telemetry(): Context[\"telemetry\"] {\n\t\treturn this.#context.telemetry;\n\t}\n\n\tvalue<T>(key: ContextKey<T>): T | undefined {\n\t\treturn this.#context.value(key);\n\t}\n\n\ttoString(): string {\n\t\treturn `${this.#parent}.Trace`;\n\t}\n\n\tget<C extends Contract>(Type: C, params: ParamsOf<C>, options?: GetOptions): Promise<Reference<C>> {\n\t\treturn this.#parent.get(Type, params, options);\n\t}\n\n\ttrace<T>(name: string, attributes: SpanAttributes, fn: (ctx: Ctx) => Promise<T>): Promise<T> {\n\t\treturn traceUnder(this, name, attributes, fn);\n\t}\n\n\t/** Its child under `span`, of its own kind. */\n\ttraced(span: TelemetrySpan): Ctx {\n\t\treturn new SpanCtx(this, span);\n\t}\n}\n\nfunction settled(Type: Contract): ChordError {\n\treturn new ChordError({\n\t\tcode: \"released\",\n\t\treason: \"settled\",\n\t\tmessage: `${Type.name}: ctx.get after its call settled`,\n\t});\n}\n\n/**\n * A child of `context` aborted by `signal` and by the caller's signal (the caller's reason first) until `release()`,\n * which the call runs when it settles. Not `AbortSignal.any`: before Node 24.16.0 it keeps cleanup entries per call for\n * as long as its sources live (nodejs/node#62367), and a call's sources (its attempt, its reference) live long.\n * Without a caller's signal the child is aborted by `signal` itself and `release` does nothing.\n */\nexport function withLinkedAbortSignal(\n\tsignal: AbortSignal,\n\tcontext: Context,\n): { readonly context: Context; release(): void } {\n\tconst caller = context.abortSignal;\n\tif (caller === undefined) return { context: withAbortSignal(signal, context), release: NOTHING };\n\tconst linked = new AbortController();\n\tconst listeners = [caller, signal].map((source) => {\n\t\tconst forward = (): void => {\n\t\t\trelease();\n\t\t\tlinked.abort(source.reason);\n\t\t};\n\t\treturn [source, forward] as const;\n\t});\n\tconst release = (): void => {\n\t\tfor (const [source, forward] of listeners) source.removeEventListener(\"abort\", forward);\n\t};\n\tconst aborted = listeners.find(([source]) => source.aborted);\n\tif (aborted !== undefined) linked.abort(aborted[0].reason);\n\telse for (const [source, forward] of listeners) source.addEventListener(\"abort\", forward, { once: true });\n\treturn { context: withAbortSignal(linked.signal, withoutAbortSignal(context)), release };\n}\n\nconst NOTHING = (): void => {};\n"]}

package/dist/host/deadline.d.ts

@@ -0,0 +1,12 @@
+/** A deadline of `ms` calling `expired` once when reached; paused time does not count. */
+export declare class Deadline {
+    #private;
+    constructor(ms: number, expired: () => void);
+    /** Stops the clock; `resume` restarts it with the budget left. */
+    pause(): void;
+    /** Restarts a paused clock. */
+    resume(): void;
+    /** Ends the deadline: `expired` is never called. */
+    clear(): void;
+}
+//# sourceMappingURL=deadline.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"deadline.d.ts","sourceRoot":"","sources":["../../src/host/deadline.ts"],"names":[],"mappings":"AAGA,0FAA0F;AAC1F,qBAAa,QAAQ;;IAQpB,YAAY,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,EAI1C;IAED,kEAAkE;IAClE,KAAK,IAAI,IAAI,CAKZ;IAED,+BAA+B;IAC/B,MAAM,IAAI,IAAI,CAEb;IAED,oDAAoD;IACpD,KAAK,IAAI,IAAI,CAIZ;CAMD"}

package/dist/host/deadline.js

@@ -0,0 +1,40 @@
+// An activation's `readyTimeout` deadline (slice 6a §9): one timer that eager migration work pauses and resumes with
+// the budget it had left, so a long migration does not fail its object while other activations keep their bounds.
+/** A deadline of `ms` calling `expired` once when reached; paused time does not count. */
+export class Deadline {
+    #expired;
+    /** The budget left when the timer last started (or paused). */
+    #remaining;
+    #started = 0;
+    #timer;
+    #cleared = false;
+    constructor(ms, expired) {
+        this.#expired = expired;
+        this.#remaining = ms;
+        this.#start();
+    }
+    /** Stops the clock; `resume` restarts it with the budget left. */
+    pause() {
+        if (this.#timer === undefined)
+            return;
+        clearTimeout(this.#timer);
+        this.#timer = undefined;
+        this.#remaining = Math.max(0, this.#remaining - (Date.now() - this.#started));
+    }
+    /** Restarts a paused clock. */
+    resume() {
+        if (this.#timer === undefined && !this.#cleared)
+            this.#start();
+    }
+    /** Ends the deadline: `expired` is never called. */
+    clear() {
+        clearTimeout(this.#timer);
+        this.#timer = undefined;
+        this.#cleared = true;
+    }
+    #start() {
+        this.#started = Date.now();
+        this.#timer = setTimeout(this.#expired, this.#remaining);
+    }
+}
+//# sourceMappingURL=deadline.js.map

package/dist/host/deadline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deadline.js","sourceRoot":"","sources":["../../src/host/deadline.ts"],"names":[],"mappings":"AAAA,qHAAqH;AACrH,kHAAkH;AAElH,0FAA0F;AAC1F,MAAM,OAAO,QAAQ;IACX,QAAQ,CAAa;IAC9B,+DAA+D;IAC/D,UAAU,CAAS;IACnB,QAAQ,GAAG,CAAC,CAAC;IACb,MAAM,CAA4C;IAClD,QAAQ,GAAG,KAAK,CAAC;IAEjB,YAAY,EAAU,EAAE,OAAmB;QAC1C,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACxB,IAAI,CAAC,UAAU,GAAG,EAAE,CAAC;QACrB,IAAI,CAAC,MAAM,EAAE,CAAC;IACf,CAAC;IAED,kEAAkE;IAClE,KAAK;QACJ,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;YAAE,OAAO;QACtC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;QACxB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,UAAU,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC/E,CAAC;IAED,+BAA+B;IAC/B,MAAM;QACL,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,QAAQ;YAAE,IAAI,CAAC,MAAM,EAAE,CAAC;IAChE,CAAC;IAED,oDAAoD;IACpD,KAAK;QACJ,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;QACxB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;IACtB,CAAC;IAED,MAAM;QACL,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC3B,IAAI,CAAC,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IAC1D,CAAC;CACD","sourcesContent":["// An activation's `readyTimeout` deadline (slice 6a §9): one timer that eager migration work pauses and resumes with\n// the budget it had left, so a long migration does not fail its object while other activations keep their bounds.\n\n/** A deadline of `ms` calling `expired` once when reached; paused time does not count. */\nexport class Deadline {\n\treadonly #expired: () => void;\n\t/** The budget left when the timer last started (or paused). */\n\t#remaining: number;\n\t#started = 0;\n\t#timer: ReturnType<typeof setTimeout> | undefined;\n\t#cleared = false;\n\n\tconstructor(ms: number, expired: () => void) {\n\t\tthis.#expired = expired;\n\t\tthis.#remaining = ms;\n\t\tthis.#start();\n\t}\n\n\t/** Stops the clock; `resume` restarts it with the budget left. */\n\tpause(): void {\n\t\tif (this.#timer === undefined) return;\n\t\tclearTimeout(this.#timer);\n\t\tthis.#timer = undefined;\n\t\tthis.#remaining = Math.max(0, this.#remaining - (Date.now() - this.#started));\n\t}\n\n\t/** Restarts a paused clock. */\n\tresume(): void {\n\t\tif (this.#timer === undefined && !this.#cleared) this.#start();\n\t}\n\n\t/** Ends the deadline: `expired` is never called. */\n\tclear(): void {\n\t\tclearTimeout(this.#timer);\n\t\tthis.#timer = undefined;\n\t\tthis.#cleared = true;\n\t}\n\n\t#start(): void {\n\t\tthis.#started = Date.now();\n\t\tthis.#timer = setTimeout(this.#expired, this.#remaining);\n\t}\n}\n"]}

package/dist/host/dependencies.d.ts

@@ -0,0 +1,65 @@
+import { ChordError, type FailureCause } from "../data/index.ts";
+import type { RegistryValueSource } from "../registries/internal.ts";
+import type { ChordObject } from "./object.ts";
+import { type Failed, type RefState } from "./ref-state.ts";
+import type { Binding } from "./reference.ts";
+/** One declared dependency: a reference (`self.get`) or a registry's value (`self.registry`). */
+export type Dependency = {
+    readonly kind: "reference";
+    readonly binding: Binding;
+} | {
+    readonly kind: "registry";
+    readonly value: RegistryValueSource;
+};
+/** A blocker as `parked_long` names it: a reference's label or `registry <name>`, and whether it loads or failed. */
+export type Blocker = {
+    readonly label: string;
+    readonly state: "loading" | "failed";
+};
+/**
+ * What the dependencies say. `live`: every one is live (hydrated: a reference's members have values). `parked`: what
+ * the attempt shows (`loading`, or `failed { waiting }` naming its first failed blocker), whether its first pass is
+ * over (`firstPass`: no blocker, loading or failed, is an object here still without its first outcome), and its first
+ * blocker in declaration order (`parked_long` names it). `broken`: one failed for a cycle (`invalid/cycle`), for
+ * authority (`forbidden`) or ended: it never comes back by itself.
+ */
+export type Check = {
+    readonly kind: "live";
+} | {
+    readonly kind: "parked";
+    readonly shown: RefState;
+    readonly firstPass: boolean;
+    readonly blocker: Blocker;
+    /** The first blocker in declaration order that is only loading (a reload's report names it). */
+    readonly loadingOn: string | undefined;
+} | {
+    readonly kind: "broken";
+    readonly error: ChordError;
+};
+/** Checks `dependencies` in declaration order (the first failed one is the one the attempt names). */
+export declare function checkDependencies(dependencies: readonly Dependency[]): Check;
+/**
+ * What a reload reports for a parked attempt (slice 7b §4): its failure's cause, or for a blocker that is only
+ * loading a `waiting` cause naming it.
+ */
+export declare function parkedCause(check: Extract<Check, {
+    readonly kind: "parked";
+}>): FailureCause;
+/** A parked attempt's state for a blocker `label` that failed with `error`. */
+export declare function waitingOn(label: string, error: ChordError): Failed;
+/**
+ * The `parked_long` report of one parking episode (dependency model §7, audit A11): once, when the attempt has been
+ * parked longer than `readyTimeout`, whatever its blocker (a ring across hosts started at the same moment stays parked
+ * so, and so does a long wait; nothing fails or retries). The clock and the report's `since` start when the episode
+ * does (its pinned keys' loading included); the report names the blocker of the latest check. Its one timer runs until
+ * the report or the episode's end (`stop`).
+ */
+export declare class ParkedLong {
+    #private;
+    constructor(object: ChordObject);
+    /** What the latest check found blocking. */
+    blockedBy(blocker: Blocker): void;
+    /** The episode ended: no report from now on. */
+    stop(): void;
+}
+//# sourceMappingURL=dependencies.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dependencies.d.ts","sourceRoot":"","sources":["../../src/host/dependencies.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,UAAU,EAAE,KAAK,YAAY,EAAgB,MAAM,kBAAkB,CAAC;AAE/E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,KAAK,MAAM,EAAW,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACrE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAE9C,iGAAiG;AACjG,MAAM,MAAM,UAAU,GACnB;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GACzD;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAA;CAAE,CAAC;AAEtE,qHAAqH;AACrH,MAAM,MAAM,OAAO,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,QAAQ,CAAA;CAAE,CAAC;AAEvF;;;;;;GAMG;AACH,MAAM,MAAM,KAAK,GACd;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IACA,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,gGAAgG;IAChG,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;CAAE,CAAC;AAI3D,sGAAsG;AACtG,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,SAAS,UAAU,EAAE,GAAG,KAAK,CAuC5E;AAWD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC,GAAG,YAAY,CAK5F;AAED,+EAA+E;AAC/E,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,CAElE;AAED;;;;;;GAMG;AACH,qBAAa,UAAU;;IAMtB,YAAY,MAAM,EAAE,WAAW,EAa9B;IAED,4CAA4C;IAC5C,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAEhC;IAED,gDAAgD;IAChD,IAAI,IAAI,IAAI,CAEX;CACD"}

package/dist/host/dependencies.js

@@ -0,0 +1,115 @@
+// Parked attempts (dependency model §3, §7): the dependency check, what an attempt's declared dependencies (`self.get`
+// references and `self.registry` values) say at one moment: all live, or what the parked attempt shows while one is not
+// (`loading`, `failed { waiting }` naming the nearest blocker and the root cause, or `broken` for a cycle, authority or
+// an ended dependency), whether this host's first pass can count it (no blocker here still without its first outcome,
+// decision (a)), and its first blocker; and the `parked_long` report of a long parking episode.
+import { ChordError, isChordError } from "../data/index.js";
+import { asChordError, waitingFor } from "../data/internal.js";
+import { LOADING } from "./ref-state.js";
+const LIVE = { kind: "live" };
+/** Checks `dependencies` in declaration order (the first failed one is the one the attempt names). */
+export function checkDependencies(dependencies) {
+    let failed;
+    let firstPass = true;
+    let blocker;
+    let loadingOn;
+    for (const dependency of dependencies) {
+        if (dependency.kind === "registry") {
+            const { value } = dependency;
+            const start = value.start();
+            if (start.kind === "value" || start.last !== undefined)
+                continue;
+            const label = `registry ${value.name}`;
+            failed ??= waitingOn(label, asChordError(start.error, label));
+            blocker ??= { label, state: "failed" };
+            continue;
+        }
+        const { binding } = dependency;
+        const state = binding.refState;
+        switch (state.kind) {
+            case "live":
+                continue;
+            case "ended":
+                return { kind: "broken", error: state.error };
+            case "failed": {
+                const { error } = state.cause;
+                if (healsNever(error))
+                    return { kind: "broken", error };
+                failed ??= waitingOn(binding.label, error);
+                blocker ??= { label: binding.label, state: "failed" };
+                // Parked `waiting` on something here still in its first attempt: no first outcome yet (fix round 1).
+                if (binding.target?.blocksFirstPass === true)
+                    firstPass = false;
+                continue;
+            }
+            case "loading":
+                loadingOn ??= binding.label;
+                blocker ??= { label: binding.label, state: "loading" };
+                if (binding.target?.blocksFirstPass === true)
+                    firstPass = false;
+        }
+    }
+    if (blocker === undefined)
+        return LIVE;
+    return { kind: "parked", shown: failed ?? LOADING, firstPass, blocker, loadingOn };
+}
+/**
+ * Whether a dependency failed with `error` never heals by itself, so its dependent breaks too: a cycle
+ * (`invalid/cycle`: it would wait on a ring) or authority (`forbidden`: an `authorize` that refused, M§3.6; only
+ * `retry()` or a reload helps).
+ */
+function healsNever(error) {
+    return (isChordError(error, "invalid") && error.reason === "cycle") || isChordError(error, "forbidden");
+}
+/**
+ * What a reload reports for a parked attempt (slice 7b §4): its failure's cause, or for a blocker that is only
+ * loading a `waiting` cause naming it.
+ */
+export function parkedCause(check) {
+    const { shown } = check;
+    if (shown.kind === "failed")
+        return shown.cause;
+    const label = check.loadingOn ?? "a dependency";
+    return waitingFor(label, new ChordError({ code: "unavailable", message: `${label} is loading` }));
+}
+/** A parked attempt's state for a blocker `label` that failed with `error`. */
+export function waitingOn(label, error) {
+    return { kind: "failed", cause: waitingFor(label, error), retryAt: undefined };
+}
+/**
+ * The `parked_long` report of one parking episode (dependency model §7, audit A11): once, when the attempt has been
+ * parked longer than `readyTimeout`, whatever its blocker (a ring across hosts started at the same moment stays parked
+ * so, and so does a long wait; nothing fails or retries). The clock and the report's `since` start when the episode
+ * does (its pinned keys' loading included); the report names the blocker of the latest check. Its one timer runs until
+ * the report or the episode's end (`stop`).
+ */
+export class ParkedLong {
+    #since = Date.now();
+    #timer;
+    /** The blocker the latest check found. */
+    #blocker;
+    constructor(object) {
+        this.#timer = setTimeout(() => {
+            const blocker = this.#blocker;
+            if (blocker === undefined)
+                return;
+            const { label, state } = blocker;
+            object.host.report({
+                kind: "parked_long",
+                object: object.label,
+                waitingFor: label,
+                state,
+                since: this.#since,
+            });
+        }, object.host.timeouts.ready);
+    }
+    /** What the latest check found blocking. */
+    blockedBy(blocker) {
+        this.#blocker = blocker;
+    }
+    /** The episode ended: no report from now on. */
+    stop() {
+        clearTimeout(this.#timer);
+    }
+}
+//# sourceMappingURL=dependencies.js.map

package/dist/host/dependencies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependencies.js","sourceRoot":"","sources":["../../src/host/dependencies.ts"],"names":[],"mappings":"AAAA,uHAAuH;AACvH,wHAAwH;AACxH,wHAAwH;AACxH,sHAAsH;AACtH,gGAAgG;AAEhG,OAAO,EAAE,UAAU,EAAqB,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAC/E,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAG/D,OAAO,EAAe,OAAO,EAAiB,MAAM,gBAAgB,CAAC;AA8BrE,MAAM,IAAI,GAAU,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAErC,sGAAsG;AACtG,MAAM,UAAU,iBAAiB,CAAC,YAAmC;IACpE,IAAI,MAA0B,CAAC;IAC/B,IAAI,SAAS,GAAG,IAAI,CAAC;IACrB,IAAI,OAA4B,CAAC;IACjC,IAAI,SAA6B,CAAC;IAClC,KAAK,MAAM,UAAU,IAAI,YAAY,EAAE,CAAC;QACvC,IAAI,UAAU,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YACpC,MAAM,EAAE,KAAK,EAAE,GAAG,UAAU,CAAC;YAC7B,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC;YAC5B,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;gBAAE,SAAS;YACjE,MAAM,KAAK,GAAG,YAAY,KAAK,CAAC,IAAI,EAAE,CAAC;YACvC,MAAM,KAAK,SAAS,CAAC,KAAK,EAAE,YAAY,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;YAC9D,OAAO,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;YACvC,SAAS;QACV,CAAC;QACD,MAAM,EAAE,OAAO,EAAE,GAAG,UAAU,CAAC;QAC/B,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAC;QAC/B,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;YACpB,KAAK,MAAM;gBACV,SAAS;YACV,KAAK,OAAO;gBACX,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;YAC/C,KAAK,QAAQ,EAAE,CAAC;gBACf,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC;gBAC9B,IAAI,UAAU,CAAC,KAAK,CAAC;oBAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;gBACxD,MAAM,KAAK,SAAS,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;gBAC3C,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;gBACtD,qGAAqG;gBACrG,IAAI,OAAO,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI;oBAAE,SAAS,GAAG,KAAK,CAAC;gBAChE,SAAS;YACV,CAAC;YACD,KAAK,SAAS;gBACb,SAAS,KAAK,OAAO,CAAC,KAAK,CAAC;gBAC5B,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;gBACvD,IAAI,OAAO,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI;oBAAE,SAAS,GAAG,KAAK,CAAC;QAClE,CAAC;IACF,CAAC;IACD,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACvC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,IAAI,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;AACpF,CAAC;AAED;;;;GAIG;AACH,SAAS,UAAU,CAAC,KAAiB;IACpC,OAAO,CAAC,YAAY,CAAC,KAAK,EAAE,SAAS,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,OAAO,CAAC,IAAI,YAAY,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;AACzG,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,KAAkD;IAC7E,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC;IACxB,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC,KAAK,CAAC;IAChD,MAAM,KAAK,GAAG,KAAK,CAAC,SAAS,IAAI,cAAc,CAAC;IAChD,OAAO,UAAU,CAAC,KAAK,EAAE,IAAI,UAAU,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,GAAG,KAAK,aAAa,EAAE,CAAC,CAAC,CAAC;AACnG,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,SAAS,CAAC,KAAa,EAAE,KAAiB;IACzD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;AAChF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,OAAO,UAAU;IACb,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACpB,MAAM,CAAgC;IAC/C,0CAA0C;IAC1C,QAAQ,CAAsB;IAE9B,YAAY,MAAmB;QAC9B,IAAI,CAAC,MAAM,GAAG,UAAU,CAAC,GAAG,EAAE;YAC7B,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC;YAC9B,IAAI,OAAO,KAAK,SAAS;gBAAE,OAAO;YAClC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;YACjC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;gBAClB,IAAI,EAAE,aAAa;gBACnB,MAAM,EAAE,MAAM,CAAC,KAAK;gBACpB,UAAU,EAAE,KAAK;gBACjB,KAAK;gBACL,KAAK,EAAE,IAAI,CAAC,MAAM;aAClB,CAAC,CAAC;QACJ,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;IAED,4CAA4C;IAC5C,SAAS,CAAC,OAAgB;QACzB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,gDAAgD;IAChD,IAAI;QACH,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC3B,CAAC;CACD","sourcesContent":["// Parked attempts (dependency model §3, §7): the dependency check, what an attempt's declared dependencies (`self.get`\n// references and `self.registry` values) say at one moment: all live, or what the parked attempt shows while one is not\n// (`loading`, `failed { waiting }` naming the nearest blocker and the root cause, or `broken` for a cycle, authority or\n// an ended dependency), whether this host's first pass can count it (no blocker here still without its first outcome,\n// decision (a)), and its first blocker; and the `parked_long` report of a long parking episode.\n\nimport { ChordError, type FailureCause, isChordError } from \"../data/index.ts\";\nimport { asChordError, waitingFor } from \"../data/internal.ts\";\nimport type { RegistryValueSource } from \"../registries/internal.ts\";\nimport type { ChordObject } from \"./object.ts\";\nimport { type Failed, LOADING, type RefState } from \"./ref-state.ts\";\nimport type { Binding } from \"./reference.ts\";\n\n/** One declared dependency: a reference (`self.get`) or a registry's value (`self.registry`). */\nexport type Dependency =\n\t| { readonly kind: \"reference\"; readonly binding: Binding }\n\t| { readonly kind: \"registry\"; readonly value: RegistryValueSource };\n\n/** A blocker as `parked_long` names it: a reference's label or `registry <name>`, and whether it loads or failed. */\nexport type Blocker = { readonly label: string; readonly state: \"loading\" | \"failed\" };\n\n/**\n * What the dependencies say. `live`: every one is live (hydrated: a reference's members have values). `parked`: what\n * the attempt shows (`loading`, or `failed { waiting }` naming its first failed blocker), whether its first pass is\n * over (`firstPass`: no blocker, loading or failed, is an object here still without its first outcome), and its first\n * blocker in declaration order (`parked_long` names it). `broken`: one failed for a cycle (`invalid/cycle`), for\n * authority (`forbidden`) or ended: it never comes back by itself.\n */\nexport type Check =\n\t| { readonly kind: \"live\" }\n\t| {\n\t\t\treadonly kind: \"parked\";\n\t\t\treadonly shown: RefState;\n\t\t\treadonly firstPass: boolean;\n\t\t\treadonly blocker: Blocker;\n\t\t\t/** The first blocker in declaration order that is only loading (a reload's report names it). */\n\t\t\treadonly loadingOn: string | undefined;\n\t  }\n\t| { readonly kind: \"broken\"; readonly error: ChordError };\n\nconst LIVE: Check = { kind: \"live\" };\n\n/** Checks `dependencies` in declaration order (the first failed one is the one the attempt names). */\nexport function checkDependencies(dependencies: readonly Dependency[]): Check {\n\tlet failed: Failed | undefined;\n\tlet firstPass = true;\n\tlet blocker: Blocker | undefined;\n\tlet loadingOn: string | undefined;\n\tfor (const dependency of dependencies) {\n\t\tif (dependency.kind === \"registry\") {\n\t\t\tconst { value } = dependency;\n\t\t\tconst start = value.start();\n\t\t\tif (start.kind === \"value\" || start.last !== undefined) continue;\n\t\t\tconst label = `registry ${value.name}`;\n\t\t\tfailed ??= waitingOn(label, asChordError(start.error, label));\n\t\t\tblocker ??= { label, state: \"failed\" };\n\t\t\tcontinue;\n\t\t}\n\t\tconst { binding } = dependency;\n\t\tconst state = binding.refState;\n\t\tswitch (state.kind) {\n\t\t\tcase \"live\":\n\t\t\t\tcontinue;\n\t\t\tcase \"ended\":\n\t\t\t\treturn { kind: \"broken\", error: state.error };\n\t\t\tcase \"failed\": {\n\t\t\t\tconst { error } = state.cause;\n\t\t\t\tif (healsNever(error)) return { kind: \"broken\", error };\n\t\t\t\tfailed ??= waitingOn(binding.label, error);\n\t\t\t\tblocker ??= { label: binding.label, state: \"failed\" };\n\t\t\t\t// Parked `waiting` on something here still in its first attempt: no first outcome yet (fix round 1).\n\t\t\t\tif (binding.target?.blocksFirstPass === true) firstPass = false;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tcase \"loading\":\n\t\t\t\tloadingOn ??= binding.label;\n\t\t\t\tblocker ??= { label: binding.label, state: \"loading\" };\n\t\t\t\tif (binding.target?.blocksFirstPass === true) firstPass = false;\n\t\t}\n\t}\n\tif (blocker === undefined) return LIVE;\n\treturn { kind: \"parked\", shown: failed ?? LOADING, firstPass, blocker, loadingOn };\n}\n\n/**\n * Whether a dependency failed with `error` never heals by itself, so its dependent breaks too: a cycle\n * (`invalid/cycle`: it would wait on a ring) or authority (`forbidden`: an `authorize` that refused, M§3.6; only\n * `retry()` or a reload helps).\n */\nfunction healsNever(error: ChordError): boolean {\n\treturn (isChordError(error, \"invalid\") && error.reason === \"cycle\") || isChordError(error, \"forbidden\");\n}\n\n/**\n * What a reload reports for a parked attempt (slice 7b §4): its failure's cause, or for a blocker that is only\n * loading a `waiting` cause naming it.\n */\nexport function parkedCause(check: Extract<Check, { readonly kind: \"parked\" }>): FailureCause {\n\tconst { shown } = check;\n\tif (shown.kind === \"failed\") return shown.cause;\n\tconst label = check.loadingOn ?? \"a dependency\";\n\treturn waitingFor(label, new ChordError({ code: \"unavailable\", message: `${label} is loading` }));\n}\n\n/** A parked attempt's state for a blocker `label` that failed with `error`. */\nexport function waitingOn(label: string, error: ChordError): Failed {\n\treturn { kind: \"failed\", cause: waitingFor(label, error), retryAt: undefined };\n}\n\n/**\n * The `parked_long` report of one parking episode (dependency model §7, audit A11): once, when the attempt has been\n * parked longer than `readyTimeout`, whatever its blocker (a ring across hosts started at the same moment stays parked\n * so, and so does a long wait; nothing fails or retries). The clock and the report's `since` start when the episode\n * does (its pinned keys' loading included); the report names the blocker of the latest check. Its one timer runs until\n * the report or the episode's end (`stop`).\n */\nexport class ParkedLong {\n\treadonly #since = Date.now();\n\treadonly #timer: ReturnType<typeof setTimeout>;\n\t/** The blocker the latest check found. */\n\t#blocker: Blocker | undefined;\n\n\tconstructor(object: ChordObject) {\n\t\tthis.#timer = setTimeout(() => {\n\t\t\tconst blocker = this.#blocker;\n\t\t\tif (blocker === undefined) return;\n\t\t\tconst { label, state } = blocker;\n\t\t\tobject.host.report({\n\t\t\t\tkind: \"parked_long\",\n\t\t\t\tobject: object.label,\n\t\t\t\twaitingFor: label,\n\t\t\t\tstate,\n\t\t\t\tsince: this.#since,\n\t\t\t});\n\t\t}, object.host.timeouts.ready);\n\t}\n\n\t/** What the latest check found blocking. */\n\tblockedBy(blocker: Blocker): void {\n\t\tthis.#blocker = blocker;\n\t}\n\n\t/** The episode ended: no report from now on. */\n\tstop(): void {\n\t\tclearTimeout(this.#timer);\n\t}\n}\n"]}

package/dist/host/destination.d.ts

@@ -0,0 +1,48 @@
+import type { Context } from "../context/index.ts";
+import type { Address, Contract, ParamsOf } from "../contracts/index.ts";
+import { ChordError, type Principal } from "../data/index.ts";
+import type { WireAddress } from "../link/internal.ts";
+import type { HoldRequest, HostLink, Path } from "../remote/internal.ts";
+import type { Route } from "./route.ts";
+/** Where something is placed: here, or over a path (with the host address it was computed or named with). */
+export type Placed = {
+    readonly kind: "here";
+} | {
+    readonly kind: "path";
+    readonly path: Path;
+    readonly address: WireAddress;
+};
+/** A host's destinations: its address, its routes and its parent path, as the host keeps them. */
+export declare class Destination {
+    #private;
+    constructor(address: Address | undefined, routes: ReadonlyMap<string, Route>, parent: Path);
+    /**
+     * Where a reference to `Type` with `params` made as `principal` goes: here for a local type, and for a remote type
+     * whose host address is this host's, served here or not (the check against what is served is the host's); otherwise
+     * over the route of its host address's kind, or over the parent link (the host address decides where an object
+     * lives: a worker reaches another worker's object of a type it serves too). Throws `invalid/host_address` for a host
+     * address whose params do not fit its kind, `forbidden` when the route refuses, and what a `hostAddress` or
+     * `authorize` throws.
+     */
+    reference(Type: Contract, params: ParamsOf<Contract>, principal: Principal | undefined, context: Context): Placed;
+    /**
+     * Whether a reference to `Type` with `params` goes here: a local type, or a remote one whose host address is this
+     * host's. A `hostAddress` that throws, throws.
+     */
+    placedHere(Type: Contract, params: ParamsOf<Contract>): boolean;
+    /**
+     * Where a hold arriving on `link` acting as `principal` goes, by the address it names: here when it is this host's
+     * (a relay never captures a hold for serving the same name); over the route of its kind; else over the parent link
+     * (waiting for it while it is down), unless it came on the parent link or this host never had one (`unavailable`).
+     * Throws as `reference` does.
+     */
+    hold(request: HoldRequest, link: HostLink, principal: Principal | undefined, context: Context): Placed;
+    /**
+     * The provider's own check of a request placed here for the remote `Type` it serves, with `params` (checked):
+     * `invalid/host_address` when its `hostAddress` puts the object on another host (code skew: the consumer computed
+     * this host), `undefined` when it lives here. A `hostAddress` that throws throws (the provider's own code). The
+     * address a request names only routes it.
+     */
+    misplaced(Type: Contract, params: ParamsOf<Contract>): ChordError | undefined;
+}
+//# sourceMappingURL=destination.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"destination.d.ts","sourceRoot":"","sources":["../../src/host/destination.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEzE,OAAO,EAAE,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AACzE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,6GAA6G;AAC7G,MAAM,MAAM,MAAM,GACf;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;CAAE,CAAC;AAEjF,kGAAkG;AAClG,qBAAa,WAAW;;IAKvB,YAAY,OAAO,EAAE,OAAO,GAAG,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,IAAI,EAIzF;IAED;;;;;;;OAOG;IACH,SAAS,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,EAAE,SAAS,GAAG,SAAS,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAKhH;IAED;;;OAGG;IACH,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,OAAO,CAE9D;IAED;;;;;OAKG;IACH,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,GAAG,SAAS,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CASrG;IAED;;;;;OAKG;IACH,SAAS,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,UAAU,GAAG,SAAS,CAK5E;CAeD"}