@earendil-works/chord 1.5.0 → 1.5.1

package/dist/host/routines.js

@@ -0,0 +1,398 @@
+// Routines (§14): the standing behaviour an object or a facet declares, `self.on(source, fn)` and `self.onLive(fn)`.
+// They start once their owner went live and stop when it ends (their ctx aborted, the drain waits for running calls);
+// each call gets its own ctx and its own `chord.routine` root span; a call that throws is reported and called again
+// after a backoff.
+import { withTelemetry } from "../context/index.js";
+import { PendingOps } from "../delta/index.js";
+import { NativeSource, Source } from "../state/internal.js";
+import { capped, ended, OpenSpan, untraced } from "../telemetry.js";
+import { NativeWatch, } from "../watch.js";
+import { nextDelay } from "./backoff.js";
+import { CallContext } from "./ctx.js";
+import { resolveWatchable } from "./reference.js";
+import { sleep } from "./sleep.js";
+const DONE = { kind: "done" };
+/** What `#failing` says of a source failed now. */
+const FAILING = { kind: "failed" };
+/** One run of an `onLive` that lasted this long resets its backoff. */
+const LONG_RUN = 60_000;
+/** An owner's routines: declared while its factory (or setup) runs, started once when it went live. */
+export class Routines {
+    #declared = [];
+    #ons = 0;
+    #lives = 0;
+    /** Declares `on(source, fn)`; whether the source is JSON or native is decided by its watch (`OnRoutine`). */
+    on(source, fn) {
+        this.#declared.push({ kind: "on", at: { kind: "on", position: ++this.#ons }, source, fn });
+    }
+    /** Whether nothing was declared. */
+    get empty() {
+        return this.#declared.length === 0;
+    }
+    /** Declares `onLive(fn)`. */
+    onLive(fn) {
+        this.#declared.push({ kind: "onLive", at: { kind: "onLive", position: ++this.#lives }, fn });
+    }
+    /**
+     * Starts every routine for `owner`, which went live; they stop when its context is aborted. A routine whose
+     * synchronous start ends the owner (an `onLive` releasing its last reference) starts none of the later ones.
+     */
+    start(owner) {
+        for (const declaration of this.#declared) {
+            if (owner.context.abortSignal?.aborted)
+                return;
+            if (declaration.kind === "on")
+                void new OnRoutine(owner, declaration).start();
+            else
+                void live(owner, declaration);
+        }
+    }
+}
+/**
+ * Runs `onLive`'s handler until it returns or its owner ends; a throw is reported and the handler restarts after the
+ * backoff.
+ */
+async function live(owner, { at, fn }) {
+    let delay;
+    while (!owner.context.abortSignal?.aborted) {
+        const started = Date.now();
+        const end = await call(owner, at, fn, undefined);
+        const { called } = end;
+        if (called.kind === "done" || owner.context.abortSignal?.aborted) {
+            callEnded(end, owner, undefined);
+            return;
+        }
+        failed(owner, at, called.error);
+        delay = nextDelay(Date.now() - started >= LONG_RUN ? undefined : delay);
+        callEnded(end, owner, delay);
+        try {
+            await sleep(delay, owner.context);
+        }
+        catch {
+            return;
+        }
+    }
+}
+/**
+ * Runs one routine call under its own ctx (its `ctx.get` references released when it settles) in its `chord.routine`
+ * root span, linked to `trigger` (the span of the commit that changed its source, when known), admitted to the owner's
+ * drain before the handler runs: a handler may end its own owner before its first await. Resolves with how it ended and
+ * its span, still open (`callEnded`); never rejects.
+ */
+function call(owner, at, invoke, trigger) {
+    const { host, context } = owner;
+    const span = untraced(host.telemetry)
+        ? undefined
+        : new OpenSpan(host.telemetry, "chord.routine", {
+            "chord.host": host.spanHost,
+            type: owner.type,
+            object: capped(owner.label),
+            routine: at.kind,
+            position: at.position,
+        });
+    if (span !== undefined && trigger !== undefined && !untraced(trigger))
+        span.span.addLink({ context: trigger });
+    const ctx = new CallContext(span === undefined ? context : withTelemetry(span.span, context), owner.caller, host);
+    const settled = Promise.withResolvers();
+    owner.admit(settled.promise, () => ctx.settle());
+    const finish = (called) => {
+        ctx.settle();
+        settled.resolve({ called, span });
+    };
+    // Plugin code: a synchronous throw becomes the rejection.
+    (async () => invoke(ctx))().then(() => finish(DONE), (error) => finish({ kind: "failed", error }));
+    return settled.promise;
+}
+/**
+ * A routine call's span ends: `ok`, `aborted` (a cancel), or `error` with `routine_failed` and, when its routine calls
+ * again after a backoff, a `chord.retry` event with that delay.
+ */
+function callEnded({ called, span }, owner, backoff) {
+    if (span === undefined)
+        return;
+    if (called.kind === "done") {
+        span.span.setAttributes({ outcome: "ok" });
+    }
+    else {
+        const outcome = ended(span.span, "routine_failed", called.error, owner.context.abortSignal);
+        if (outcome === "error" && backoff !== undefined)
+            span.span.addEvent("chord.retry", { backoff });
+        span.span.setAttributes({ outcome });
+    }
+    span.end();
+}
+/** Reports a failed routine call or source. */
+function failed(owner, routine, error) {
+    owner.host.report({ kind: "routine_failed", object: owner.label, routine, error });
+}
+/**
+ * One `on` routine. Its watch's listener never throws (a throwing listener would end the watch) and never waits: it
+ * keeps the newest frame, folding JSON ops, and the routine makes one call at a time from it, the first call and the
+ * retries after a throw through the same pending frame.
+ */
+class OnRoutine {
+    #owner;
+    #declaration;
+    #state = { kind: "starting" };
+    /** A native source's watch yields values without ops; decided by its watch's class. */
+    #native = false;
+    /** The newest value no call got yet. */
+    #pending;
+    /** The ops of the frames since the last call (JSON sources), folded. */
+    #ops = new PendingOps();
+    /** One of the frames since the last call was a retirement (JSON sources). */
+    #retired = false;
+    #basis = "none";
+    /** The value of the last call: a retry after a throw calls with it. */
+    #last;
+    /** The last call reported a retirement: a retry after a throw reports it again. */
+    #lastRetired = false;
+    #delay;
+    /** The source failed after its last value: no call until its next value (a retry waits too). */
+    #failed = false;
+    /** The span of the commit that made the newest frame (a frame's context), linked from the next call's span. */
+    #trigger;
+    constructor(owner, declaration) {
+        this.#owner = owner;
+        this.#declaration = declaration;
+    }
+    /**
+     * Takes the watch and calls with its value. On a failed Chord source it waits for its first good value instead (a
+     * source that never had one is followed until it has). A source that cannot be watched otherwise is reported; an
+     * owner or source that ended meanwhile ends the routine. Never rejects.
+     */
+    async start() {
+        const { source, at } = this.#declaration;
+        let failing = this.#failing();
+        while (failing?.kind === "no_value") {
+            if (!(await this.#firstValue(failing.source))) {
+                this.#state = { kind: "ended" };
+                return;
+            }
+            // Asked again: a failure may have followed the first value before this resumed (one receive turn).
+            failing = this.#failing();
+        }
+        let watch;
+        try {
+            watch = await source.watch(this.#owner.context);
+        }
+        catch (error) {
+            this.#state = { kind: "ended" };
+            if (!this.#aborted())
+                failed(this.#owner, at, error);
+            return;
+        }
+        this.#native = watch instanceof NativeWatch;
+        void watch.closed.then((end) => this.#end(end));
+        try {
+            // Both listeners return at once.
+            watch.start((call, frame) => {
+                if (call.kind === "value")
+                    this.#frame(call, frame.telemetry);
+                else
+                    this.#failure();
+                return Promise.resolve();
+            });
+        }
+        catch {
+            // The watch ended while it was taken (the owner or the source ended): `closed` says how.
+            return;
+        }
+        // A watch opened on a failed source holds its last good value, a stale one: its first call is the failure.
+        if (failing?.kind === "failed") {
+            this.#state = { kind: "idle" };
+            return;
+        }
+        this.#pending = { value: watch.value };
+        this.#next();
+    }
+    /**
+     * Whether the source is a Chord source failed now (`failed`), or a JSON one with no value yet (`no_value`, with the
+     * source to follow); `undefined` otherwise (Durable's views tell their failures through their watches).
+     */
+    #failing() {
+        const declared = this.#declaration.source;
+        // A native source opens its watch at its last good value while failed (a registry whose `compose` threw): its
+        // first call is the failure, not that stale value.
+        if (declared instanceof NativeSource)
+            return declared.start().kind === "failed" ? FAILING : undefined;
+        let source;
+        try {
+            source = resolveWatchable(this.#declaration.source);
+        }
+        catch {
+            // Not bound or ended: the watch says so.
+            return undefined;
+        }
+        if (!(source instanceof Source))
+            return undefined;
+        let start;
+        try {
+            start = source.start();
+        }
+        catch {
+            return undefined;
+        }
+        if (start.kind === "value")
+            return undefined;
+        return start.last === undefined ? { kind: "no_value", source } : { kind: "failed" };
+    }
+    /**
+     * Follows `source`, failed with no value, until its first good value (`true`), or until it or the owner ends
+     * (`false`): a subscriber of its own, since a watch has nothing to start at.
+     */
+    #firstValue(source) {
+        const signal = this.#owner.context.abortSignal;
+        return new Promise((resolve) => {
+            const done = (got) => {
+                source.unsubscribe(subscriber);
+                signal?.removeEventListener("abort", aborted);
+                resolve(got);
+            };
+            const subscriber = {
+                advance: (call) => {
+                    if (call.kind === "value")
+                        done(true);
+                },
+                end: () => done(false),
+                endAfterDelivery: () => done(false),
+            };
+            const aborted = () => done(false);
+            signal?.addEventListener("abort", aborted, { once: true });
+            if (signal?.aborted)
+                aborted();
+            else
+                source.subscribe(subscriber);
+        });
+    }
+    /**
+     * The source failed: what was pending goes (a value a failure followed is stale), a pending retry or settle is
+     * dropped, and the next call waits for the next value, as a whole value; a running call runs on.
+     */
+    #failure() {
+        const state = this.#state;
+        if (state.kind === "ended")
+            return;
+        this.#failed = true;
+        this.#pending = undefined;
+        this.#ops.take();
+        this.#basis = "none";
+        if (state.kind === "backoff" || state.kind === "settling") {
+            clearTimeout(state.timer);
+            this.#state = { kind: "idle" };
+        }
+    }
+    /**
+     * A frame of the watch: kept as the newest; it is called at once when nothing runs or waits, during a backoff too
+     * (the backoff ends); while a call runs or settles it waits for the next call.
+     */
+    #frame(call, trigger) {
+        const state = this.#state;
+        if (state.kind === "ended")
+            return;
+        this.#failed = false;
+        this.#pending = { value: call.value };
+        this.#trigger = trigger;
+        if (!this.#native) {
+            // A JSON watch's call, as its class decided.
+            const { ops, retired } = call;
+            this.#ops.push(ops);
+            if (retired)
+                this.#retired = true;
+        }
+        if (state.kind === "backoff")
+            clearTimeout(state.timer);
+        if (state.kind === "backoff" || state.kind === "idle")
+            this.#next();
+    }
+    /** Makes the next call from the pending frame, if there is one and the owner still runs; otherwise idles. */
+    #next() {
+        const pending = this.#pending;
+        if (pending === undefined || this.#aborted()) {
+            this.#state = { kind: "idle" };
+            return;
+        }
+        this.#pending = undefined;
+        const { value } = pending;
+        this.#state = { kind: "calling" };
+        this.#last = value;
+        const trigger = this.#trigger;
+        this.#trigger = undefined;
+        void call(this.#owner, this.#declaration.at, this.#invocation(value), trigger).then((end) => this.#called(end));
+    }
+    /**
+     * The handler's call with `value`: a native one with the value alone, a JSON one with the folded ops or the whole
+     * value, and whether a retirement came since the last call.
+     */
+    #invocation(value) {
+        const { fn } = this.#declaration;
+        // The overloads typed `fn` for its source's kind, which the watch decided.
+        if (this.#native)
+            return (ctx) => fn({ kind: "value", value }, ctx);
+        const taken = this.#ops.take();
+        // A JSON source's values are JSON.
+        const ops = this.#basis === "none" || taken.kind === "replace" ? [["r", value]] : taken.ops;
+        const retired = this.#retired;
+        this.#retired = false;
+        this.#lastRetired = retired;
+        return (ctx) => fn({ kind: "value", value, ops, retired }, ctx);
+    }
+    /**
+     * A call settled. After a success the next frame's ops build on it, and changes that arrived during the call are
+     * called after one macrotask (`settling`). After a throw (reported) the backoff always starts, also when changes
+     * arrived during the call (a handler that changes its own source and throws would feed itself otherwise); its timer
+     * calls with the newest value, or the last call's, as a whole value.
+     */
+    #called(end) {
+        const { called } = end;
+        if (this.#state.kind === "ended" || called.kind === "done" || this.#aborted())
+            callEnded(end, this.#owner, undefined);
+        if (this.#state.kind === "ended")
+            return;
+        if (called.kind === "done") {
+            this.#basis = "last";
+            this.#delay = undefined;
+            if (this.#pending === undefined)
+                this.#state = { kind: "idle" };
+            else
+                this.#state = { kind: "settling", timer: setTimeout(() => this.#next(), 0) };
+            return;
+        }
+        if (this.#aborted())
+            return;
+        failed(this.#owner, this.#declaration.at, called.error);
+        this.#basis = "none";
+        // The handler may not have applied the retirement either.
+        if (this.#lastRetired)
+            this.#retired = true;
+        this.#delay = nextDelay(this.#delay);
+        // The source failed meanwhile: the retry waits for its next value, never the stale last one.
+        if (this.#failed) {
+            callEnded(end, this.#owner, undefined);
+            this.#state = { kind: "idle" };
+            return;
+        }
+        callEnded(end, this.#owner, this.#delay);
+        const timer = setTimeout(() => {
+            this.#pending ??= { value: this.#last };
+            this.#next();
+        }, this.#delay);
+        this.#state = { kind: "backoff", timer };
+    }
+    /** The watch ended: the owner ended (aborted), or the source ended (no report) or failed (reported once). */
+    #end(end) {
+        const state = this.#state;
+        this.#state = { kind: "ended" };
+        if (state.kind === "settling" || state.kind === "backoff")
+            clearTimeout(state.timer);
+        this.#pending = undefined;
+        this.#ops.take();
+        this.#retired = false;
+        if (end.kind === "failed" && !this.#aborted())
+            failed(this.#owner, this.#declaration.at, end.error);
+    }
+    #aborted() {
+        return this.#owner.context.abortSignal?.aborted === true;
+    }
+}
+//# sourceMappingURL=routines.js.map

package/dist/host/routines.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routines.js","sourceRoot":"","sources":["../../src/host/routines.ts"],"names":[],"mappings":"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","sourcesContent":["// Routines (§14): the standing behaviour an object or a facet declares, `self.on(source, fn)` and `self.onLive(fn)`.\n// They start once their owner went live and stop when it ends (their ctx aborted, the drain waits for running calls);\n// each call gets its own ctx and its own `chord.routine` root span; a call that throws is reported and called again\n// after a backoff.\n\nimport type { TelemetryContext } from \"@earendil-works/pi-telemetry\";\nimport { type Context, withTelemetry } from \"../context/index.ts\";\nimport type { Principal } from \"../data/index.ts\";\nimport { type Op, PendingOps } from \"../delta/index.ts\";\nimport type { JsonValue } from \"../json.ts\";\nimport { NativeSource, Source } from \"../state/internal.ts\";\nimport { capped, ended, OpenSpan, untraced } from \"../telemetry.ts\";\nimport {\n\tNativeWatch,\n\ttype NativeWatchable,\n\ttype NativeWatchCall,\n\ttype Watchable,\n\ttype WatchCall,\n\ttype WatchEnd,\n} from \"../watch.ts\";\nimport { nextDelay } from \"./backoff.ts\";\nimport { CallContext, type Caller, type Ctx } from \"./ctx.ts\";\nimport type { AnyHost, Position } from \"./host.ts\";\nimport { resolveWatchable } from \"./reference.ts\";\nimport { sleep } from \"./sleep.ts\";\n\n/**\n * Where routines run: their owner's label (for reports), its host, whom their calls act for, and the context of their\n * calls, aborted when the owner ends. `admit` adds a running call to the owner's drain.\n */\nexport type RoutineOwner = {\n\treadonly label: string;\n\t/** Its type's name (routine spans). */\n\treadonly type: string;\n\treadonly host: AnyHost;\n\treadonly caller: Caller;\n\treadonly context: Context;\n\t/**\n\t * Adds a running call to the drain; `cleanup` (its bookkeeping) runs once, when it settles or when the attempt ends\n\t * with it still running.\n\t */\n\tadmit(running: Promise<unknown>, cleanup: () => void): void;\n};\n\n/**\n * A routine's handler of a JSON source: the value call (the value, the ops since the previous call, whether the\n * source's document was retired since then) and the call's ctx. Failures are not calls of a handler (design §11): the\n * routine waits for the next value.\n */\nexport type OnHandler<T, C extends Ctx = Ctx> = (call: WatchValueCall<T>, ctx: C) => void | Promise<void>;\n\n/** A JSON watch's value call: what an `on` handler gets. */\nexport type WatchValueCall<T> = Extract<WatchCall<T>, { readonly kind: \"value\" }>;\n\n/** A native watch's value call. */\nexport type NativeWatchValueCall<T> = Extract<NativeWatchCall<T>, { readonly kind: \"value\" }>;\n\n/** A routine's handler of a native source: the value call (the value) and the call's ctx. */\nexport type OnNativeHandler<T, C extends Ctx = Ctx> = (call: NativeWatchValueCall<T>, ctx: C) => void | Promise<void>;\n\n/** An `onLive` routine: called once its owner is live. */\nexport type OnLiveHandler<C extends Ctx = Ctx> = (ctx: C) => void | Promise<void>;\n\n/** What the declarations of an owner (`on`, `onLive`) take; part of the factory's `self` and the facet's. */\nexport interface RoutineDeclarations<P extends Principal = Principal> {\n\t/**\n\t * A routine over `source`: `fn` gets its current value first (ops `[[\"r\", value]]`), then one call per change,\n\t * never overlapping: changes during a call fold into one next call (the newest value, the ops since the previous\n\t * call, `retired` when any of them was a retirement). After a call that threw, it is called again with the whole\n\t * newest value (`retired` again if the call that threw had it) after a backoff (1 s doubling to 60 s), or at once on\n\t * a change during the backoff. Ends with its source. A JSON watchable is one whose watch is Chord's shared `Watch`\n\t * (every Chord and Durable source).\n\t */\n\ton<T>(source: Watchable<T>, fn: OnHandler<T, Ctx<P>>): void;\n\t/**\n\t * A routine over a native source (a registry value, `ref.state`): one whose watch is Chord's shared `NativeWatch`.\n\t * As above without ops: after a busy call, one call with the newest value.\n\t */\n\ton<T>(source: NativeWatchable<T>, fn: OnNativeHandler<T, Ctx<P>>): void;\n\t/**\n\t * A routine called once its owner is live. Returning ends it; a throw is reported and restarts it after a backoff\n\t * (1 s doubling to 60 s, reset after a run of a minute); the owner's end aborts its ctx.\n\t */\n\tonLive(fn: OnLiveHandler<Ctx<P>>): void;\n}\n\n/** A declared routine: its kind and position in reports (`{ kind: \"on\", position: 2 }`), its source and its handler. */\ntype Declaration =\n\t| {\n\t\t\treadonly kind: \"on\";\n\t\t\treadonly at: RoutinePosition;\n\t\t\treadonly source: Watchable<unknown> | NativeWatchable<unknown>;\n\t\t\treadonly fn: (...args: never[]) => void | Promise<void>;\n\t  }\n\t| { readonly kind: \"onLive\"; readonly at: RoutinePosition; readonly fn: OnLiveHandler };\n\n/** A routine's kind and position (`Position`, a routine's). */\ntype RoutinePosition = Position & { readonly kind: \"on\" | \"onLive\" };\n\n/** How one routine call ended. */\ntype Called = { readonly kind: \"done\" } | { readonly kind: \"failed\"; readonly error: unknown };\n\nconst DONE: Called = { kind: \"done\" };\n\n/** One routine call: how it ended, and its span, which its routine ends once it knows whether a retry follows. */\ntype CallEnd = { readonly called: Called; readonly span: OpenSpan<\"chord.routine\"> | undefined };\n\n/** What `#failing` says of a source failed now. */\nconst FAILING = { kind: \"failed\" } as const;\n\n/** One run of an `onLive` that lasted this long resets its backoff. */\nconst LONG_RUN = 60_000;\n\n/** An owner's routines: declared while its factory (or setup) runs, started once when it went live. */\nexport class Routines {\n\treadonly #declared: Declaration[] = [];\n\t#ons = 0;\n\t#lives = 0;\n\n\t/** Declares `on(source, fn)`; whether the source is JSON or native is decided by its watch (`OnRoutine`). */\n\ton(source: Watchable<unknown> | NativeWatchable<unknown>, fn: (...args: never[]) => void | Promise<void>): void {\n\t\tthis.#declared.push({ kind: \"on\", at: { kind: \"on\", position: ++this.#ons }, source, fn });\n\t}\n\n\t/** Whether nothing was declared. */\n\tget empty(): boolean {\n\t\treturn this.#declared.length === 0;\n\t}\n\n\t/** Declares `onLive(fn)`. */\n\tonLive(fn: OnLiveHandler): void {\n\t\tthis.#declared.push({ kind: \"onLive\", at: { kind: \"onLive\", position: ++this.#lives }, fn });\n\t}\n\n\t/**\n\t * Starts every routine for `owner`, which went live; they stop when its context is aborted. A routine whose\n\t * synchronous start ends the owner (an `onLive` releasing its last reference) starts none of the later ones.\n\t */\n\tstart(owner: RoutineOwner): void {\n\t\tfor (const declaration of this.#declared) {\n\t\t\tif (owner.context.abortSignal?.aborted) return;\n\t\t\tif (declaration.kind === \"on\") void new OnRoutine(owner, declaration).start();\n\t\t\telse void live(owner, declaration);\n\t\t}\n\t}\n}\n\n/**\n * Runs `onLive`'s handler until it returns or its owner ends; a throw is reported and the handler restarts after the\n * backoff.\n */\nasync function live(owner: RoutineOwner, { at, fn }: Extract<Declaration, { kind: \"onLive\" }>): Promise<void> {\n\tlet delay: number | undefined;\n\twhile (!owner.context.abortSignal?.aborted) {\n\t\tconst started = Date.now();\n\t\tconst end = await call(owner, at, fn, undefined);\n\t\tconst { called } = end;\n\t\tif (called.kind === \"done\" || owner.context.abortSignal?.aborted) {\n\t\t\tcallEnded(end, owner, undefined);\n\t\t\treturn;\n\t\t}\n\t\tfailed(owner, at, called.error);\n\t\tdelay = nextDelay(Date.now() - started >= LONG_RUN ? undefined : delay);\n\t\tcallEnded(end, owner, delay);\n\t\ttry {\n\t\t\tawait sleep(delay, owner.context);\n\t\t} catch {\n\t\t\treturn;\n\t\t}\n\t}\n}\n\n/**\n * Runs one routine call under its own ctx (its `ctx.get` references released when it settles) in its `chord.routine`\n * root span, linked to `trigger` (the span of the commit that changed its source, when known), admitted to the owner's\n * drain before the handler runs: a handler may end its own owner before its first await. Resolves with how it ended and\n * its span, still open (`callEnded`); never rejects.\n */\nfunction call(\n\towner: RoutineOwner,\n\tat: RoutinePosition,\n\tinvoke: (ctx: Ctx) => void | Promise<void>,\n\ttrigger: TelemetryContext | undefined,\n): Promise<CallEnd> {\n\tconst { host, context } = owner;\n\tconst span = untraced(host.telemetry)\n\t\t? undefined\n\t\t: new OpenSpan(host.telemetry, \"chord.routine\", {\n\t\t\t\t\"chord.host\": host.spanHost,\n\t\t\t\ttype: owner.type,\n\t\t\t\tobject: capped(owner.label),\n\t\t\t\troutine: at.kind,\n\t\t\t\tposition: at.position,\n\t\t\t});\n\tif (span !== undefined && trigger !== undefined && !untraced(trigger)) span.span.addLink({ context: trigger });\n\tconst ctx = new CallContext(span === undefined ? context : withTelemetry(span.span, context), owner.caller, host);\n\tconst settled = Promise.withResolvers<CallEnd>();\n\towner.admit(settled.promise, () => ctx.settle());\n\tconst finish = (called: Called): void => {\n\t\tctx.settle();\n\t\tsettled.resolve({ called, span });\n\t};\n\t// Plugin code: a synchronous throw becomes the rejection.\n\t(async () => invoke(ctx))().then(\n\t\t() => finish(DONE),\n\t\t(error: unknown) => finish({ kind: \"failed\", error }),\n\t);\n\treturn settled.promise;\n}\n\n/**\n * A routine call's span ends: `ok`, `aborted` (a cancel), or `error` with `routine_failed` and, when its routine calls\n * again after a backoff, a `chord.retry` event with that delay.\n */\nfunction callEnded({ called, span }: CallEnd, owner: RoutineOwner, backoff: number | undefined): void {\n\tif (span === undefined) return;\n\tif (called.kind === \"done\") {\n\t\tspan.span.setAttributes({ outcome: \"ok\" });\n\t} else {\n\t\tconst outcome = ended(span.span, \"routine_failed\", called.error, owner.context.abortSignal);\n\t\tif (outcome === \"error\" && backoff !== undefined) span.span.addEvent(\"chord.retry\", { backoff });\n\t\tspan.span.setAttributes({ outcome });\n\t}\n\tspan.end();\n}\n\n/** Reports a failed routine call or source. */\nfunction failed(owner: RoutineOwner, routine: Position, error: unknown): void {\n\towner.host.report({ kind: \"routine_failed\", object: owner.label, routine, error });\n}\n\n/**\n * Where an `on` routine stands. `starting`: taking its watch; `idle`: waiting for a change; `calling`: a call runs\n * (changes meanwhile wait, folded, for the next); `settling`: a call succeeded while changes arrived, and the next one\n * waits for one macrotask, so every value its watch still buffers (a native watch replays them one per microtask) is\n * taken first; `backoff`: the last call threw and its timer calls again, unless a change during the backoff calls\n * first; `ended`: its watch ended (the owner ended, or the source ended or failed).\n */\ntype OnState =\n\t| { readonly kind: \"starting\" | \"idle\" | \"calling\" | \"ended\" }\n\t| { readonly kind: \"settling\" | \"backoff\"; readonly timer: ReturnType<typeof setTimeout> };\n\n/**\n * What the next call's ops are relative to: `none` before the first call and after a throw (the handler may not have\n * applied what it got: the next call gets the whole value), `last` after a call that succeeded.\n */\ntype Basis = \"none\" | \"last\";\n\n/**\n * One `on` routine. Its watch's listener never throws (a throwing listener would end the watch) and never waits: it\n * keeps the newest frame, folding JSON ops, and the routine makes one call at a time from it, the first call and the\n * retries after a throw through the same pending frame.\n */\nclass OnRoutine {\n\treadonly #owner: RoutineOwner;\n\treadonly #declaration: Extract<Declaration, { kind: \"on\" }>;\n\t#state: OnState = { kind: \"starting\" };\n\t/** A native source's watch yields values without ops; decided by its watch's class. */\n\t#native = false;\n\t/** The newest value no call got yet. */\n\t#pending: { readonly value: unknown } | undefined;\n\t/** The ops of the frames since the last call (JSON sources), folded. */\n\treadonly #ops = new PendingOps();\n\t/** One of the frames since the last call was a retirement (JSON sources). */\n\t#retired = false;\n\t#basis: Basis = \"none\";\n\t/** The value of the last call: a retry after a throw calls with it. */\n\t#last: unknown;\n\t/** The last call reported a retirement: a retry after a throw reports it again. */\n\t#lastRetired = false;\n\t#delay: number | undefined;\n\t/** The source failed after its last value: no call until its next value (a retry waits too). */\n\t#failed = false;\n\t/** The span of the commit that made the newest frame (a frame's context), linked from the next call's span. */\n\t#trigger: TelemetryContext | undefined;\n\n\tconstructor(owner: RoutineOwner, declaration: Extract<Declaration, { kind: \"on\" }>) {\n\t\tthis.#owner = owner;\n\t\tthis.#declaration = declaration;\n\t}\n\n\t/**\n\t * Takes the watch and calls with its value. On a failed Chord source it waits for its first good value instead (a\n\t * source that never had one is followed until it has). A source that cannot be watched otherwise is reported; an\n\t * owner or source that ended meanwhile ends the routine. Never rejects.\n\t */\n\tasync start(): Promise<void> {\n\t\tconst { source, at } = this.#declaration;\n\t\tlet failing = this.#failing();\n\t\twhile (failing?.kind === \"no_value\") {\n\t\t\tif (!(await this.#firstValue(failing.source))) {\n\t\t\t\tthis.#state = { kind: \"ended\" };\n\t\t\t\treturn;\n\t\t\t}\n\t\t\t// Asked again: a failure may have followed the first value before this resumed (one receive turn).\n\t\t\tfailing = this.#failing();\n\t\t}\n\t\tlet watch: Awaited<ReturnType<typeof source.watch>>;\n\t\ttry {\n\t\t\twatch = await source.watch(this.#owner.context);\n\t\t} catch (error) {\n\t\t\tthis.#state = { kind: \"ended\" };\n\t\t\tif (!this.#aborted()) failed(this.#owner, at, error);\n\t\t\treturn;\n\t\t}\n\t\tthis.#native = watch instanceof NativeWatch;\n\t\tvoid watch.closed.then((end) => this.#end(end));\n\t\ttry {\n\t\t\t// Both listeners return at once.\n\t\t\twatch.start((call: WatchCall<unknown> | NativeWatchCall<unknown>, frame: Context) => {\n\t\t\t\tif (call.kind === \"value\") this.#frame(call, frame.telemetry);\n\t\t\t\telse this.#failure();\n\t\t\t\treturn Promise.resolve();\n\t\t\t});\n\t\t} catch {\n\t\t\t// The watch ended while it was taken (the owner or the source ended): `closed` says how.\n\t\t\treturn;\n\t\t}\n\t\t// A watch opened on a failed source holds its last good value, a stale one: its first call is the failure.\n\t\tif (failing?.kind === \"failed\") {\n\t\t\tthis.#state = { kind: \"idle\" };\n\t\t\treturn;\n\t\t}\n\t\tthis.#pending = { value: watch.value };\n\t\tthis.#next();\n\t}\n\n\t/**\n\t * Whether the source is a Chord source failed now (`failed`), or a JSON one with no value yet (`no_value`, with the\n\t * source to follow); `undefined` otherwise (Durable's views tell their failures through their watches).\n\t */\n\t#failing(): { readonly kind: \"failed\" } | { readonly kind: \"no_value\"; readonly source: Source } | undefined {\n\t\tconst declared = this.#declaration.source;\n\t\t// A native source opens its watch at its last good value while failed (a registry whose `compose` threw): its\n\t\t// first call is the failure, not that stale value.\n\t\tif (declared instanceof NativeSource) return declared.start().kind === \"failed\" ? FAILING : undefined;\n\t\tlet source: unknown;\n\t\ttry {\n\t\t\tsource = resolveWatchable(this.#declaration.source);\n\t\t} catch {\n\t\t\t// Not bound or ended: the watch says so.\n\t\t\treturn undefined;\n\t\t}\n\t\tif (!(source instanceof Source)) return undefined;\n\t\tlet start: ReturnType<Source[\"start\"]>;\n\t\ttry {\n\t\t\tstart = source.start();\n\t\t} catch {\n\t\t\treturn undefined;\n\t\t}\n\t\tif (start.kind === \"value\") return undefined;\n\t\treturn start.last === undefined ? { kind: \"no_value\", source } : { kind: \"failed\" };\n\t}\n\n\t/**\n\t * Follows `source`, failed with no value, until its first good value (`true`), or until it or the owner ends\n\t * (`false`): a subscriber of its own, since a watch has nothing to start at.\n\t */\n\t#firstValue(source: Source): Promise<boolean> {\n\t\tconst signal = this.#owner.context.abortSignal;\n\t\treturn new Promise((resolve) => {\n\t\t\tconst done = (got: boolean): void => {\n\t\t\t\tsource.unsubscribe(subscriber);\n\t\t\t\tsignal?.removeEventListener(\"abort\", aborted);\n\t\t\t\tresolve(got);\n\t\t\t};\n\t\t\tconst subscriber = {\n\t\t\t\tadvance: (call: WatchCall<JsonValue>) => {\n\t\t\t\t\tif (call.kind === \"value\") done(true);\n\t\t\t\t},\n\t\t\t\tend: () => done(false),\n\t\t\t\tendAfterDelivery: () => done(false),\n\t\t\t};\n\t\t\tconst aborted = (): void => done(false);\n\t\t\tsignal?.addEventListener(\"abort\", aborted, { once: true });\n\t\t\tif (signal?.aborted) aborted();\n\t\t\telse source.subscribe(subscriber);\n\t\t});\n\t}\n\n\t/**\n\t * The source failed: what was pending goes (a value a failure followed is stale), a pending retry or settle is\n\t * dropped, and the next call waits for the next value, as a whole value; a running call runs on.\n\t */\n\t#failure(): void {\n\t\tconst state = this.#state;\n\t\tif (state.kind === \"ended\") return;\n\t\tthis.#failed = true;\n\t\tthis.#pending = undefined;\n\t\tthis.#ops.take();\n\t\tthis.#basis = \"none\";\n\t\tif (state.kind === \"backoff\" || state.kind === \"settling\") {\n\t\t\tclearTimeout(state.timer);\n\t\t\tthis.#state = { kind: \"idle\" };\n\t\t}\n\t}\n\n\t/**\n\t * A frame of the watch: kept as the newest; it is called at once when nothing runs or waits, during a backoff too\n\t * (the backoff ends); while a call runs or settles it waits for the next call.\n\t */\n\t#frame(call: WatchValueCall<unknown> | NativeWatchValueCall<unknown>, trigger: TelemetryContext): void {\n\t\tconst state = this.#state;\n\t\tif (state.kind === \"ended\") return;\n\t\tthis.#failed = false;\n\t\tthis.#pending = { value: call.value };\n\t\tthis.#trigger = trigger;\n\t\tif (!this.#native) {\n\t\t\t// A JSON watch's call, as its class decided.\n\t\t\tconst { ops, retired } = call as WatchValueCall<unknown>;\n\t\t\tthis.#ops.push(ops);\n\t\t\tif (retired) this.#retired = true;\n\t\t}\n\t\tif (state.kind === \"backoff\") clearTimeout(state.timer);\n\t\tif (state.kind === \"backoff\" || state.kind === \"idle\") this.#next();\n\t}\n\n\t/** Makes the next call from the pending frame, if there is one and the owner still runs; otherwise idles. */\n\t#next(): void {\n\t\tconst pending = this.#pending;\n\t\tif (pending === undefined || this.#aborted()) {\n\t\t\tthis.#state = { kind: \"idle\" };\n\t\t\treturn;\n\t\t}\n\t\tthis.#pending = undefined;\n\t\tconst { value } = pending;\n\t\tthis.#state = { kind: \"calling\" };\n\t\tthis.#last = value;\n\t\tconst trigger = this.#trigger;\n\t\tthis.#trigger = undefined;\n\t\tvoid call(this.#owner, this.#declaration.at, this.#invocation(value), trigger).then((end) => this.#called(end));\n\t}\n\n\t/**\n\t * The handler's call with `value`: a native one with the value alone, a JSON one with the folded ops or the whole\n\t * value, and whether a retirement came since the last call.\n\t */\n\t#invocation(value: unknown): (ctx: Ctx) => void | Promise<void> {\n\t\tconst { fn } = this.#declaration;\n\t\t// The overloads typed `fn` for its source's kind, which the watch decided.\n\t\tif (this.#native) return (ctx) => (fn as OnNativeHandler<unknown>)({ kind: \"value\", value }, ctx);\n\t\tconst taken = this.#ops.take();\n\t\t// A JSON source's values are JSON.\n\t\tconst ops: readonly Op[] =\n\t\t\tthis.#basis === \"none\" || taken.kind === \"replace\" ? [[\"r\", value as JsonValue]] : taken.ops;\n\t\tconst retired = this.#retired;\n\t\tthis.#retired = false;\n\t\tthis.#lastRetired = retired;\n\t\treturn (ctx) => (fn as OnHandler<unknown>)({ kind: \"value\", value, ops, retired }, ctx);\n\t}\n\n\t/**\n\t * A call settled. After a success the next frame's ops build on it, and changes that arrived during the call are\n\t * called after one macrotask (`settling`). After a throw (reported) the backoff always starts, also when changes\n\t * arrived during the call (a handler that changes its own source and throws would feed itself otherwise); its timer\n\t * calls with the newest value, or the last call's, as a whole value.\n\t */\n\t#called(end: CallEnd): void {\n\t\tconst { called } = end;\n\t\tif (this.#state.kind === \"ended\" || called.kind === \"done\" || this.#aborted())\n\t\t\tcallEnded(end, this.#owner, undefined);\n\t\tif (this.#state.kind === \"ended\") return;\n\t\tif (called.kind === \"done\") {\n\t\t\tthis.#basis = \"last\";\n\t\t\tthis.#delay = undefined;\n\t\t\tif (this.#pending === undefined) this.#state = { kind: \"idle\" };\n\t\t\telse this.#state = { kind: \"settling\", timer: setTimeout(() => this.#next(), 0) };\n\t\t\treturn;\n\t\t}\n\t\tif (this.#aborted()) return;\n\t\tfailed(this.#owner, this.#declaration.at, called.error);\n\t\tthis.#basis = \"none\";\n\t\t// The handler may not have applied the retirement either.\n\t\tif (this.#lastRetired) this.#retired = true;\n\t\tthis.#delay = nextDelay(this.#delay);\n\t\t// The source failed meanwhile: the retry waits for its next value, never the stale last one.\n\t\tif (this.#failed) {\n\t\t\tcallEnded(end, this.#owner, undefined);\n\t\t\tthis.#state = { kind: \"idle\" };\n\t\t\treturn;\n\t\t}\n\t\tcallEnded(end, this.#owner, this.#delay);\n\t\tconst timer = setTimeout(() => {\n\t\t\tthis.#pending ??= { value: this.#last };\n\t\t\tthis.#next();\n\t\t}, this.#delay);\n\t\tthis.#state = { kind: \"backoff\", timer };\n\t}\n\n\t/** The watch ended: the owner ended (aborted), or the source ended (no report) or failed (reported once). */\n\t#end(end: WatchEnd): void {\n\t\tconst state = this.#state;\n\t\tthis.#state = { kind: \"ended\" };\n\t\tif (state.kind === \"settling\" || state.kind === \"backoff\") clearTimeout(state.timer);\n\t\tthis.#pending = undefined;\n\t\tthis.#ops.take();\n\t\tthis.#retired = false;\n\t\tif (end.kind === \"failed\" && !this.#aborted()) failed(this.#owner, this.#declaration.at, end.error);\n\t}\n\n\t#aborted(): boolean {\n\t\treturn this.#owner.context.abortSignal?.aborted === true;\n\t}\n}\n"]}

package/dist/host/sleep.d.ts

@@ -0,0 +1,9 @@
+import type { Context } from "../context/index.ts";
+/**
+ * Resolves after `ms` milliseconds; rejects with the abort reason once `context` is aborted, clearing its timer and
+ * listener. Delays above the timer limit (2^31-1 ms) are chained timers.
+ */
+export declare function sleep(ms: number, context: Context): Promise<void>;
+/** Resolves once `context` is aborted (never without an abort signal); leaves no listener behind. */
+export declare function untilAborted(context: Context): Promise<void>;
+//# sourceMappingURL=sleep.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sleep.d.ts","sourceRoot":"","sources":["../../src/host/sleep.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAKnD;;;GAGG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAsBjE;AAED,qGAAqG;AACrG,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAK5D"}

package/dist/host/sleep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep.js","sourceRoot":"","sources":["../../src/host/sleep.ts"],"names":[],"mappings":"AAAA,kHAAkH;AAClH,+FAA+F;AAI/F,sEAAsE;AACtE,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AAE9B;;;GAGG;AACH,MAAM,UAAU,KAAK,CAAC,EAAU,EAAE,OAAgB;IACjD,MAAM,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IACnC,IAAI,MAAM,EAAE,OAAO;QAAE,OAAO,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC1D,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,aAAa,EAAQ,CAAC;IACnE,IAAI,KAAgD,CAAC;IACrD,MAAM,KAAK,GAAG,GAAS,EAAE;QACxB,YAAY,CAAC,KAAK,CAAC,CAAC;QACpB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxB,CAAC,CAAC;IACF,MAAM,IAAI,GAAG,CAAC,IAAY,EAAQ,EAAE;QACnC,KAAK,GAAG,UAAU,CACjB,GAAG,EAAE;YACJ,IAAI,IAAI,GAAG,SAAS;gBAAE,OAAO,IAAI,CAAC,IAAI,GAAG,SAAS,CAAC,CAAC;YACpD,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;YAC5C,OAAO,EAAE,CAAC;QACX,CAAC,EACD,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,CACzB,CAAC;IACH,CAAC,CAAC;IACF,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IACzD,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,OAAO,OAAO,CAAC;AAChB,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,YAAY,CAAC,OAAgB;IAC5C,MAAM,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IACnC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,IAAI,OAAO,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACvD,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC7C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;AACpG,CAAC","sourcesContent":["// Waiting helpers for routines, jobs and handlers (§14): `sleep(ms, ctx)` and `untilAborted(ctx)`, which end with\n// their context, leaving no timer or listener behind. Portable: timers and `AbortSignal` only.\n\nimport type { Context } from \"../context/index.ts\";\n\n/** The longest delay one timer takes (a longer one fires at once). */\nconst MAX_TIMER = 2 ** 31 - 1;\n\n/**\n * Resolves after `ms` milliseconds; rejects with the abort reason once `context` is aborted, clearing its timer and\n * listener. Delays above the timer limit (2^31-1 ms) are chained timers.\n */\nexport function sleep(ms: number, context: Context): Promise<void> {\n\tconst signal = context.abortSignal;\n\tif (signal?.aborted) return Promise.reject(signal.reason);\n\tconst { promise, resolve, reject } = Promise.withResolvers<void>();\n\tlet timer: ReturnType<typeof setTimeout> | undefined;\n\tconst abort = (): void => {\n\t\tclearTimeout(timer);\n\t\treject(signal?.reason);\n\t};\n\tconst wait = (left: number): void => {\n\t\ttimer = setTimeout(\n\t\t\t() => {\n\t\t\t\tif (left > MAX_TIMER) return wait(left - MAX_TIMER);\n\t\t\t\tsignal?.removeEventListener(\"abort\", abort);\n\t\t\t\tresolve();\n\t\t\t},\n\t\t\tMath.min(left, MAX_TIMER),\n\t\t);\n\t};\n\tsignal?.addEventListener(\"abort\", abort, { once: true });\n\twait(ms);\n\treturn promise;\n}\n\n/** Resolves once `context` is aborted (never without an abort signal); leaves no listener behind. */\nexport function untilAborted(context: Context): Promise<void> {\n\tconst signal = context.abortSignal;\n\tif (signal === undefined) return new Promise(() => {});\n\tif (signal.aborted) return Promise.resolve();\n\treturn new Promise((resolve) => signal.addEventListener(\"abort\", () => resolve(), { once: true }));\n}\n"]}

package/dist/host/staging.d.ts

@@ -0,0 +1,94 @@
+import type { Context } from "../context/index.ts";
+import type { Contract, ParamsOf } from "../contracts/index.ts";
+import type { Principal } from "../data/index.ts";
+import type { AnyDefinition } from "../documents/internal.ts";
+import type { JobDefinition } from "../jobs/index.ts";
+import type { Registry, RegistryProvider } from "../registries/index.ts";
+import type { TableDefinition } from "../store/table.ts";
+import type { Watchable } from "../watch.ts";
+import { type Facet, type FacetContribution } from "./facet.ts";
+import type { ChordObject, Served } from "./object.ts";
+import type { Presence } from "./presence.ts";
+/** A plugin's facet as `load` and `reload` take it: its name (its `package.json` name) and its facet. */
+export type PluginFacet<P extends Principal = Principal> = {
+    readonly name: string;
+    readonly facet: Facet<P>;
+};
+/** A registry a staged plugin serves: the defining plugin, the token and its provider. */
+export type StagedRegistry = {
+    readonly plugin: string;
+    readonly registry: Registry<unknown, unknown>;
+    readonly provider: RegistryProvider<unknown, unknown>;
+};
+/** One plugin's setup, run and checked: what it serves and contributes, nothing published yet. */
+export type StagedPlugin = {
+    readonly name: string;
+    /** The served types by name, each with its plugin, factory, provider (its `accepts` checked) and `linger`. */
+    readonly types: ReadonlyMap<string, Served>;
+    /** The served registries by name. */
+    readonly registries: ReadonlyMap<string, StagedRegistry>;
+    /** The facet contributions, in the setup's order. */
+    readonly contributions: readonly FacetContribution[];
+};
+/** A plugin set's staged plugins, merged: what they serve, by name, and each plugin's own table. */
+export type Staged = {
+    readonly types: Map<string, Served>;
+    readonly registries: Map<string, StagedRegistry>;
+    readonly plugins: Map<string, StagedPlugin>;
+};
+/** What staging needs of its host: whom it acts as, where it lives, and its presence lists for setups. */
+export type StagingHost = {
+    readonly principal: Principal | undefined;
+    readonly address: unknown;
+    references<C extends Contract>(Type: C): Watchable<readonly Presence<C, Principal>[]>;
+};
+/** Whether `name` is a valid plugin name: an npm package name, scoped or not (the plugins component checks it too). */
+export declare function isPluginName(name: string): boolean;
+/**
+ * Throws for the first plugin of `facets` whose name is no npm package name: a programming error, so `load` and
+ * `reload` throw before they change anything (decision "Mistakes that wait are reported at once" (d)).
+ */
+export declare function checkPluginNames(facets: readonly {
+    readonly name: string;
+}[]): void;
+/** A staged table with nothing in it. */
+export declare function emptyStaged(): Staged;
+/**
+ * Runs one plugin's setup (its name checked by `checkPluginNames` before) and checks what it declared: a type or
+ * registry it serves twice, a remote type on a host without a principal or address, every provider's `accepts`
+ * (`checkAccepts`) and every registry provider's shape. Throws the first error, naming the plugin.
+ */
+export declare function stagePlugin<P extends Principal>({ name, facet }: PluginFacet<P>, host: StagingHost): StagedPlugin;
+/**
+ * Merges `plugin` into `staged`; a type or registry another plugin serves there already refuses it (its error
+ * returned, nothing merged).
+ */
+export declare function addStaged(staged: Staged, plugin: StagedPlugin): Error | undefined;
+/** What a recorded factory declared: what a reload's fate and checks need, nothing activated. */
+export type Recorded = {
+    readonly documents: readonly AnyDefinition[];
+    readonly tables: readonly TableDefinition[];
+    readonly jobs: readonly JobDefinition<unknown, unknown, unknown>[];
+    readonly contributions: readonly Registry<unknown, unknown>[];
+    /** Its requests: the types it gets (`self.get`, with their checked params) and the registries it reads (`self.registry`). */
+    readonly requests: readonly Request[];
+};
+/** A recorded request, with the contract version it was made at: a type and its params, or a registry. */
+export type Request = {
+    readonly kind: "type";
+    readonly contract: Contract;
+    readonly params: ParamsOf<Contract>;
+} | {
+    readonly kind: "registry";
+    readonly registry: Registry<unknown, unknown>;
+};
+/**
+ * Runs `served`'s factory for `object` (its params and principal) against a recording `self` and returns what it
+ * declared. Every declaration check an attempt makes runs, without effects (declared twice; persisted data in a type
+ * without a stable identity, on a host without a store, or claimed by another owner; contributions outside
+ * host-lifetime objects, or twice; `retryOn` sources that do not outlive the attempt; params; a document or job
+ * declared at an older version than the object's, or at its version with another schema); a throw is the factory's.
+ * Handles it hands out are inert, except registry values (the host's own, which `retryOn` checks by kind).
+ */
+export declare function recordFactory(object: ChordObject, served: Served, context: Context): Recorded;
+//# sourceMappingURL=staging.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"staging.d.ts","sourceRoot":"","sources":["../../src/host/staging.ts"],"names":[],"mappings":"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"}