@earendil-works/chord 1.3.0 → 1.5.0

package/dist/next/jobs/records.js

@@ -0,0 +1,869 @@
+// A job's records on its object (§15, slice 6a §1.2, slice 6b §4): its runs by id and by key, the active count, the
+// run state documents, `running` and the runs waiting for a live attempt, across the object's attempts. Records and
+// state documents change only in transactions on the object's line (staged changes adopted in the commit step); a
+// persisted job's also in its object's store, in the same commits, loaded once per object, and written back stopped by
+// the close writer when a clean stop cuts its runs off. Across a reload (slice 7b §8) the records take the new
+// declaration's definition and every run keeps its version: an older one is mapped forwards through `accepts`, one
+// without an adapter (or newer, or of a job the code no longer declares) is blocked `version` until a reload brings
+// matching code.
+import { withoutAbortSignal } from "../../context/index.js";
+import { ChordError } from "../data/index.js";
+import { check, validatorFor } from "../data/internal.js";
+import { Persistence } from "../documents/internal.js";
+import { uuidv7 } from "../host/internal.js";
+import { PersistedRuns } from "./persisted.js";
+import { JobRun } from "./run.js";
+import { RunStates } from "./run-states.js";
+import { Running } from "./running.js";
+import { outcomeOf, storedRun } from "./stored.js";
+const RESTART = { kind: "failed", error: { kind: "aborted", reason: "restart" } };
+const RELOAD = { kind: "failed", error: { kind: "aborted", reason: "reload" } };
+const ABORTED = { kind: "failed", error: { kind: "aborted", reason: "abort" } };
+/** A persisted run cut off this many times in a row ends `restart_limit` (D6, Durable's limit). */
+const RESTART_LIMIT = 5;
+/**
+ * The records of one job name on one object. The live attempt's `Job` invokes and finishes its runs; between live
+ * attempts, committed runs not yet invoked and runs whose outcome is recorded wait for the next one.
+ */
+export class JobRecords {
+    /** The latest declaration's definition: a reload's new attempt redefines it; each run keeps its own version. */
+    definition;
+    running;
+    #owner;
+    #states;
+    /** The store side of a persisted job's state documents; `undefined` in memory. */
+    #statePersistence;
+    /** The store side of a persisted job's runs; `undefined` in memory. */
+    #persisted;
+    #runs = new Map();
+    #keys = new Map();
+    /** Running and finishing runs: concurrency and keep-alive count them. */
+    #active = 0;
+    /** The live attempt's job; `undefined` between live attempts. */
+    #job;
+    /** Runs waiting for a live attempt: to be invoked (`invocation` pending) or finished (phase `finishing`). */
+    #waiting = new Set();
+    /** Runs a clean stop cut off whose record the close writer has not written `stopped` yet. */
+    #stopped = new Set();
+    /** Whether a persisted job's records were loaded (once per object). */
+    #loaded = false;
+    /** The object's end error, once it ended. */
+    #ended;
+    /** Whether the latest live attempt declares the job: its runs are blocked `version` while it does not. */
+    #declared = true;
+    constructor(definition, owner) {
+        this.definition = definition;
+        this.#owner = owner;
+        const { state, persist, name } = definition;
+        const store = persist === undefined ? undefined : owner.store;
+        const persistence = store === undefined ? undefined : new Persistence(store.store, store.owner, "chord.job-states", name);
+        this.#statePersistence = persistence;
+        this.#states = state === undefined ? undefined : this.#runStates(state);
+        this.#persisted =
+            store === undefined
+                ? undefined
+                : new PersistedRuns(new Persistence(store.store, store.owner, "chord.jobs", name), persistence);
+        this.running = new Running(owner.documents.batch, this.name);
+    }
+    /** The run state documents of `state`, reporting their changes to `running` and their held deadlines. */
+    #runStates(state) {
+        const owner = this.#owner;
+        const states = {
+            documents: owner.documents,
+            changed: (id, ops) => this.#stateChanged(id, ops),
+            held: (deadline) => owner.held(deadline),
+        };
+        return new RunStates(state, states, this.#statePersistence);
+    }
+    /**
+     * Refuses a declaration of this job that its records cannot take (slice 7b §8): the same version with another
+     * fingerprint (its args, result or state schema changed without a version bump), or a state document definition
+     * the run documents refuse (`SlotDefinition.check`). A reload's staging checks it too.
+     */
+    check(definition) {
+        const current = this.definition;
+        if (definition.version === current.version && definition.fingerprint !== current.fingerprint) {
+            throw new Error(`${this.name}: its schema changed without a version bump (version ${definition.version})`);
+        }
+        const { state } = definition;
+        const states = this.#states;
+        if (state !== undefined && states !== undefined && state !== states.definition.current) {
+            states.definition.check(state);
+        }
+    }
+    /**
+     * Takes a new attempt's declaration `definition` (another version after a reload, `ChordObject.checkJob` refused
+     * the same version with another fingerprint): new runs are of its version; the runs of others keep theirs, their
+     * `running` entries show their args mapped forwards (or blocked); their state documents keep their version until
+     * their run settles or moves to the new code.
+     */
+    redefine(definition) {
+        this.#declared = true;
+        if (definition === this.definition)
+            return;
+        this.definition = definition;
+        const { state } = definition;
+        if (state !== undefined) {
+            if (this.#states === undefined)
+                this.#states = this.#runStates(state);
+            else
+                this.#states.redefine(state);
+        }
+        if (this.#runs.size === 0)
+            return;
+        this.#owner.documents.batch.within(() => {
+            for (const run of this.#runs.values())
+                if (run.entry !== undefined)
+                    this.#replaceEntry(run);
+        }, this.#owner.context);
+    }
+    /**
+     * The latest live attempt does not declare the job (slice 7b §8): its runs not invoked and its finishing runs are
+     * blocked `version` (kept, not invoked) until a reload declares it again or they are aborted; a running
+     * invocation finishes and is blocked then.
+     */
+    undeclare() {
+        if (!this.#declared || this.#ended !== undefined)
+            return;
+        this.#declared = false;
+        this.#job = undefined;
+        const waiting = [...this.#waiting];
+        this.#waiting.clear();
+        for (const run of waiting)
+            void this.record(run, { kind: "block", run, reason: "version" });
+    }
+    /**
+     * A reload brought new code (its attempt is live): blocked runs are retried, once: a `finish_failed` one finishes
+     * again, a `version` one whose version the code now takes (its own, or an older one with an adapter) is invoked or
+     * finished; the others stay blocked. A persisted run blocked at its load has its state document read first.
+     */
+    async retryBlocked(context) {
+        if (!this.#declared || this.#ended !== undefined)
+            return;
+        const retried = [...this.#runs.values()].filter((run) => run.phase === "blocked" && (run.blocked === "finish_failed" || this.#takes(run)));
+        if (retried.length === 0)
+            return;
+        try {
+            for (const run of retried)
+                if (run.blockedPhase !== undefined)
+                    await this.#readBlockedState(run, context);
+        }
+        catch {
+            // Its state document cannot be read: it stays blocked (the next reload tries again).
+            return;
+        }
+        const { documents } = this.#owner;
+        try {
+            await documents.tx((tx) => {
+                for (const run of retried) {
+                    if (this.#runs.get(run.id) !== run || run.phase !== "blocked")
+                        continue;
+                    const phase = run.outcome !== undefined ? "finishing" : this.#persisted === undefined ? "running" : "pending";
+                    this.change(tx, { kind: "unblock", run, phase });
+                }
+            }, documents.own, this.#owner.context);
+        }
+        catch {
+            // The object ended.
+        }
+    }
+    /** Reads and decodes the state document of a persisted run blocked at its load, now that the code takes it. */
+    async #readBlockedState(run, context) {
+        const states = this.#states;
+        this.#persisted.forgetBlockedState(run.id);
+        if (states === undefined)
+            return;
+        const document = await states.persistence.read(run.id, context);
+        if (document === undefined)
+            return;
+        const { value, stored } = states.persistence.decode(document, states.definition.current, context);
+        states.create(run.id, value, stored);
+        if (run.outcome !== undefined)
+            run.outcome = { ...run.outcome, state: value };
+    }
+    /**
+     * Whether the current code takes `run`: of its version and fingerprint, or of an older version its `accepts` maps
+     * forwards; a newer one (a rollback) or an older one without an adapter is not (`blocked { version }`).
+     */
+    #takes(run) {
+        const { definition } = this;
+        if (run.version === definition.version)
+            return run.fingerprint === definition.fingerprint;
+        return run.version < definition.version && definition.accepts[run.version] !== undefined;
+    }
+    /**
+     * `run`'s args as the code of `definition` takes them (the current code's, or an invoking attempt's own): mapped
+     * forwards once per run and version when older.
+     */
+    argsOf(run, definition) {
+        if (run.version === definition.version)
+            return run.args;
+        const mapped = run.mapped;
+        if (mapped !== undefined && mapped.version === definition.version)
+            return mapped.args;
+        // `#takes` found the adapter; its result is the current args (the provider's mapping, not validated).
+        const args = definition.accepts[run.version].args(run.args);
+        run.mapped = { version: definition.version, args };
+        return args;
+    }
+    /**
+     * `run`'s outcome as the current code's `finish` gets it: an older run's args and result mapped forwards (once per
+     * run), its state document migrated to the current state definition.
+     */
+    outcomeOf(run, context) {
+        const outcome = run.outcome;
+        const { definition } = this;
+        if (run.version === definition.version)
+            return outcome;
+        const args = this.argsOf(run, definition);
+        const mapped = run.mapped;
+        if (mapped.outcome !== undefined)
+            return mapped.outcome;
+        const result = outcome.kind === "done"
+            ? { kind: "done", result: definition.accepts[run.version].result(outcome.result) }
+            : { kind: "failed", error: outcome.error };
+        const state = this.#states?.migrated(run.id, context) ?? outcome.state;
+        mapped.outcome = { id: outcome.id, args, state, ...result };
+        return mapped.outcome;
+    }
+    /** The job in errors: its object and its name. */
+    get name() {
+        return `${this.#owner.label} job ${this.definition.name}`;
+    }
+    /** Waits for the outcome of the unsettled run `id`; a settled or unknown id rejects `gone`. */
+    outcome(id, context) {
+        const run = this.#runs.get(id);
+        if (run === undefined) {
+            return Promise.reject(new ChordError({ code: "gone", message: `${this.name}: no unsettled run ${id}` }));
+        }
+        return run.handle.outcome(context);
+    }
+    /**
+     * Aborts run `id` (D7, Durable's `abortTask`): a blocked run is dropped; a finishing one is only marked; any other
+     * is marked (stored for a persisted job) in a transaction, its signal fired after the commit, outside the batch and
+     * the line, and the abort joins its invocation. `"marked"`, or `"terminal"` when no unsettled run has that id.
+     */
+    async abort(id, context) {
+        const run = this.#runs.get(id);
+        if (run === undefined || this.#ended !== undefined)
+            return "terminal";
+        if (run.phase === "blocked") {
+            await this.record(run, { kind: "drop", run });
+            return "marked";
+        }
+        if (!run.abortMarked)
+            await this.record(run, { kind: "update", run, fields: { abortMarked: true } });
+        // A finishing run's outcome stays: it is only marked.
+        if (run.phase === "finishing")
+            return "marked";
+        run.invocation?.abort.abort(new ChordError({ code: "aborted", message: `${this.name}: run ${id} aborted` }));
+        await run.over(context);
+        return "marked";
+    }
+    /** See `Job.stage`: the checks and the staged creation, against the object's runs. */
+    stage(tx, args, context, options) {
+        const definition = this.definition;
+        // Plugin code, not type-checked: the args are checked as a method's are (R7).
+        check(validatorFor(definition.args, context), args, "args", context);
+        const staged = tx.staged(this);
+        const { key } = options;
+        if (key !== undefined) {
+            const known = staged?.started.find((run) => run.key === key) ?? this.#keys.get(key);
+            if (known !== undefined && known !== staged?.finishing)
+                return known.handle;
+        }
+        const { concurrency } = definition;
+        const active = this.#active + (staged?.started.length ?? 0) - (staged?.finishing === undefined ? 0 : 1);
+        if (concurrency !== undefined && active >= concurrency) {
+            const message = `${this.name}: at its concurrency limit (${concurrency})`;
+            throw new ChordError({ code: "unavailable", reason: "busy", message });
+        }
+        const persisted = this.#persisted !== undefined;
+        const trace = persisted ? context.telemetry.propagation?.inject(context.telemetry) : undefined;
+        // Checked above: the args are JSON (the definition refuses bytes).
+        const run = new JobRun(uuidv7(), definition.version, definition.fingerprint, key, args, persisted ? "pending" : "running", trace);
+        const staging = this.staging(tx);
+        staging.started.push(run);
+        this.change(tx, { kind: "create", run });
+        const state = definition.state?.initial(context);
+        if (state !== undefined)
+            staging.adopts.push(this.#states.stageCreate(run.id, state, () => this.#store(tx)));
+        return run.handle;
+    }
+    /**
+     * Stages `change` in `tx`: in the job's staging, adopted in the commit step, and for a persisted job the run's record
+     * written with it (rule 8: serialized now), and for a settled run its state document retired.
+     */
+    change(tx, change) {
+        const staging = this.staging(tx);
+        staging.changes.push(change);
+        const { run } = change;
+        const states = this.#states;
+        const retires = change.kind === "delete" || change.kind === "drop";
+        if (retires && states?.current(run.id) !== undefined)
+            tx.retireSlot(states, run.id);
+        const persisted = this.#persisted;
+        if (persisted === undefined)
+            return;
+        const writes = this.#store(tx);
+        if (retires) {
+            staging.adopts.push(persisted.stageRetire(run.id, writes));
+            return;
+        }
+        const fields = recordFields(change);
+        staging.adopts.push(persisted.stage(run.id, storedRun(run, fields), writes));
+    }
+    /** This job's changes in `tx`, made on the first. */
+    staging(tx) {
+        return tx.stage(this, () => {
+            const changes = [];
+            const adopts = [];
+            return {
+                started: [],
+                changes,
+                adopts,
+                finishing: undefined,
+                adopt: () => {
+                    // A step admitted before the object ended adopts after it: the records are not changed any more.
+                    if (this.#ended !== undefined)
+                        return;
+                    // What is stored first: a new run's state document exists when its `running` entry is made.
+                    runAll(adopts);
+                    for (const change of changes)
+                        this.#adopt(change);
+                },
+                committed: () => {
+                    const ended = this.#ended;
+                    if (ended === undefined) {
+                        for (const change of changes)
+                            this.#committed(change);
+                        return;
+                    }
+                    // Its runs end as the object's other runs did.
+                    for (const change of changes)
+                        if (change.kind === "create")
+                            change.run.reject(ended);
+                },
+                discarded: () => {
+                    for (const change of changes)
+                        if (change.kind === "create")
+                            change.run.reject(this.#discarded());
+                },
+            };
+        });
+    }
+    /**
+     * A persisted job's runs, loaded once per object at its first activation (slice 6b §4.2), again only after a load
+     * failed (design §9): each record read; a record of another version or fingerprint blocked (`version`) as stored,
+     * its state document left undecoded; the others' state documents read and decoded, a run cut off while `running`
+     * counted (`restarts + 1`; at the limit it ends `restart_limit`, reported `job_interrupted`), `stopped` and
+     * `pending` ones made `pending` again. The runs and their activation changes are adopted in one commit, all before
+     * anything runs; a failure leaves nothing loaded.
+     */
+    async load(context) {
+        const persisted = this.#persisted;
+        if (persisted === undefined || this.#loaded)
+            return;
+        const restored = [];
+        try {
+            for (const loaded of await persisted.load(context))
+                restored.push(await this.#restored(loaded, context));
+            if (restored.length > 0) {
+                const { documents } = this.#owner;
+                await documents.tx((tx) => this.#restoreAll(tx, restored), documents.own, context);
+            }
+        }
+        catch (error) {
+            persisted.drop();
+            for (const { run } of restored)
+                this.#states?.retire(run.id);
+            throw error;
+        }
+        this.#loaded = true;
+        for (const { run, change } of restored) {
+            if (change?.kind === "outcome" &&
+                change.outcome.kind === "failed" &&
+                change.outcome.error.kind === "restart_limit") {
+                this.report({ kind: "job_interrupted", id: run.id, restarts: change.outcome.error.restarts });
+            }
+        }
+        for (const { run } of restored)
+            this.#need(run);
+    }
+    /** Stages the loaded runs in `tx`: each restored, then the activation changes (adopted after every restore). */
+    #restoreAll(tx, restored) {
+        const staging = this.staging(tx);
+        for (const { run } of restored)
+            staging.changes.push({ kind: "restore", run });
+        for (const { change } of restored)
+            if (change !== undefined)
+                this.change(tx, change);
+    }
+    /** `job`, of the attempt that went live, invokes and finishes the runs from now on; the waiting ones first. */
+    attach(job) {
+        if (this.#ended !== undefined)
+            return;
+        this.#job = job;
+        const waiting = [...this.#waiting];
+        this.#waiting.clear();
+        for (const run of waiting)
+            this.#dispatch(run, job);
+    }
+    /**
+     * `job`'s attempt was sealed: its running invocations are cut off (`cut`), the runs it was finishing wait for the
+     * next live attempt.
+     */
+    detach(job, finishing) {
+        if (this.#job === job)
+            this.#job = undefined;
+        for (const run of finishing)
+            this.#need(run);
+    }
+    /**
+     * A run whose reservation its sealed attempt never committed waits for the next live attempt (dispatched now when one
+     * is attached already: the sealed attempt was detached at its seal).
+     */
+    requeue(run) {
+        this.#need(run);
+    }
+    /** Records `run` running before its `run` is invoked (a persisted run's reservation: a crash after it counts). */
+    reserve(tx, run) {
+        this.change(tx, { kind: "update", run, fields: { phase: "running" } });
+    }
+    /** A state change of a run with restarts counted resets them in its commit (progress, D6). */
+    progressed(tx, run) {
+        if (run.restarts !== 0)
+            this.change(tx, { kind: "update", run, fields: { restarts: 0 } });
+    }
+    /**
+     * A run's invocation settled: its outcome is recorded (phase `finishing`) in a transaction of the object behind the
+     * state changes admitted before, so `outcome.state` has them; then it is finished on the live attempt.
+     */
+    settled(run, ended) {
+        void this.#recordOutcome(run, ended);
+    }
+    /**
+     * A running run whose attempt was sealed: its signal fires with `error`, its invocation is fenced (later state
+     * changes refused, the open one discarded, its settling ignored). In memory it ends `failed { aborted }` with
+     * `reason` (`reload` for a native restart, slice 7b §8), finished on the next live attempt; persisted it is stopped (R3), written back by the close writer and
+     * resumed by the next live attempt as after a clean close.
+     */
+    cut(run, error, reason) {
+        // Only an invoked run is cut: its current invocation is the one the seal stops.
+        const invocation = run.invocation;
+        invocation.settle();
+        this.#owner.documents.fence(invocation.token);
+        invocation.abort.abort(error);
+        if (this.#persisted !== undefined) {
+            run.phase = "stopped";
+            // Resumed per the job's `resume` (an `abandon` job's run ends `failed { aborted, restart }`).
+            run.resuming = true;
+            this.#stopped.add(run);
+            if (this.#ended === undefined)
+                this.#need(run);
+            return;
+        }
+        if (this.#ended === undefined)
+            void this.#recordOutcome(run, reason === "reload" ? RELOAD : RESTART);
+    }
+    /**
+     * Records `change` (a run's finish failure, its block, its drop) in a transaction of the object, if `run` is still
+     * one of its runs there. The object's end ends it.
+     */
+    async record(run, change) {
+        const { documents, context } = this.#owner;
+        try {
+            await documents.tx((tx) => {
+                if (this.#runs.get(run.id) === run)
+                    this.change(tx, change);
+            }, documents.own, context);
+        }
+        catch {
+            // The object ended: its runs went with it.
+        }
+    }
+    /**
+     * The close writer (slice 6b §4.2, Durable's `writeAtClose`): one commit past the seal writing the runs a clean stop
+     * cut off `stopped` and every held state change, straight to the store (the object's transactions are refused by
+     * now). Its failure is the store's; the records stay as they were (a crash counts them).
+     */
+    async writeAtClose(context) {
+        const persisted = this.#persisted;
+        if (persisted === undefined)
+            return;
+        const writes = [];
+        const adopts = [];
+        for (const run of this.#stopped) {
+            adopts.push(persisted.stage(run.id, storedRun(run), writes));
+        }
+        this.#stopped.clear();
+        for (const id of this.#states?.heldIds ?? []) {
+            const adopt = this.#states.stageHeld(id, writes);
+            if (adopt !== undefined)
+                adopts.push(adopt);
+        }
+        if (writes.length === 0)
+            return;
+        const fence = { admit: () => true, adopt: () => runAll(adopts) };
+        try {
+            await this.#owner.store.store.commit(writes, fence, withoutAbortSignal(context));
+        }
+        catch {
+            // The store failed or refused it (reported as the store's): a crash loses as much.
+        }
+    }
+    /** Stores every held state change whose deadline passed (`now`), in one transaction of the object (D8). */
+    async flushHeld(now) {
+        const states = this.#states;
+        if (states === undefined || states.heldIds.length === 0)
+            return;
+        const { documents, context } = this.#owner;
+        try {
+            await documents.tx((tx) => {
+                const staging = this.staging(tx);
+                for (const id of states.heldIds) {
+                    if (states.deadline(id) > now)
+                        continue;
+                    const adopt = states.stageHeld(id, this.#store(tx));
+                    if (adopt !== undefined)
+                        staging.adopts.push(adopt);
+                }
+            }, documents.own, context);
+        }
+        catch {
+            // The object is ending: its close writer stores what is held.
+        }
+    }
+    /** The earliest deadline of a held state change (`Infinity`: none). */
+    nextDeadline() {
+        const states = this.#states;
+        if (states === undefined)
+            return Number.POSITIVE_INFINITY;
+        return Math.min(Number.POSITIVE_INFINITY, ...states.heldIds.map((id) => states.deadline(id)));
+    }
+    /** The value of run `id`'s state document, `undefined` without one or once retired. */
+    stateOf(id) {
+        return this.#states?.value(id);
+    }
+    /** The run state documents, for `ctx.state.change`; `undefined` without a state definition. */
+    get states() {
+        return this.#states;
+    }
+    /** Whether the job persists its runs. */
+    get persisted() {
+        return this.#persisted !== undefined;
+    }
+    /**
+     * The object ends: running runs' signals fire, every waiter rejects with `error`; blocked in-memory runs are
+     * dropped (reported), persisted ones keep their records; nothing finishes. The records stay readable until `drop`.
+     */
+    end(error) {
+        if (this.#ended !== undefined)
+            return;
+        this.#ended = error;
+        this.#job = undefined;
+        this.#waiting.clear();
+        for (const run of this.#runs.values()) {
+            if (run.phase === "blocked" && this.#persisted === undefined)
+                this.report({ kind: "job_dropped", id: run.id });
+            const { invocation } = run;
+            invocation?.abort.abort(error);
+            run.reject(error);
+            if (invocation?.state !== "running")
+                invocation?.ended();
+        }
+        if (this.#active > 0)
+            this.#owner.countRuns(-this.#active);
+    }
+    /** Its object's documents are dropped: the runs, their state documents and `running`'s watches go. */
+    drop() {
+        this.#runs.clear();
+        this.#keys.clear();
+        this.#states?.drop();
+        this.#persisted?.drop();
+        this.running.end();
+    }
+    /** Reports a run's failure, drop or interruption to the host. */
+    report(error) {
+        this.#owner.host.report({ ...error, object: this.#owner.label, job: this.definition.name });
+    }
+    /** The store writes of `tx` (Chord's own documents of a persisted job). */
+    #store(tx) {
+        return tx.stageStore(this.#owner.store.store);
+    }
+    /**
+     * The run a loaded record stands for and the change its activation writes (D6): a record of another version or
+     * fingerprint blocked as stored (its state document only found, never decoded: slice 7 maps it); otherwise its state
+     * document read and decoded (migrated), pinned while it is unsettled, a crash counted, at the limit its outcome,
+     * marked resuming unless blocked or finishing.
+     */
+    async #restored(loaded, context) {
+        const { id, record } = loaded;
+        const { definition } = this;
+        const run = new JobRun(id, record.version, record.fingerprint, record.key, record.args, record.phase, record.trace);
+        run.restarts = record.restarts;
+        run.finishFailures = record.finishFailures;
+        run.abortMarked = record.abort === true;
+        const states = this.#states;
+        if (record.version !== definition.version || record.fingerprint !== definition.fingerprint) {
+            run.phase = "blocked";
+            run.blocked = "version";
+            // What the record says, for the reload that brings its version (`retryBlocked`).
+            run.blockedPhase = record.phase;
+            if (record.outcome !== undefined)
+                run.outcome = outcomeOf(record.outcome, id, record.args, undefined);
+            // What is stored of its state (also when this version declares none), so an abort drops it with the record.
+            await this.#persisted.findBlockedState(id, context);
+            return { run, change: undefined };
+        }
+        const document = await states?.persistence.read(id, context);
+        if (document !== undefined) {
+            const { value, stored } = states.persistence.decode(document, states.definition.current, context);
+            states.create(id, value, stored);
+        }
+        if (record.outcome !== undefined)
+            run.outcome = outcomeOf(record.outcome, id, record.args, this.stateOf(id));
+        run.blocked = record.blocked;
+        switch (record.phase) {
+            case "running": {
+                const restarts = record.restarts + 1;
+                run.resuming = true;
+                if (restarts < RESTART_LIMIT) {
+                    return { run, change: { kind: "update", run, fields: { phase: "pending", restarts } } };
+                }
+                run.restarts = restarts;
+                const outcome = this.#outcome(run, { kind: "failed", error: { kind: "restart_limit", restarts } });
+                return { run, change: { kind: "outcome", run, outcome } };
+            }
+            case "stopped":
+                run.resuming = true;
+                return { run, change: { kind: "update", run, fields: { phase: "pending" } } };
+            case "pending":
+                run.resuming = true;
+                return { run, change: undefined };
+            default:
+                return { run, change: undefined };
+        }
+    }
+    /** Records the outcome of `run` (with what its state holds, D8), then has it finished on the live attempt. */
+    async #recordOutcome(run, ended) {
+        const { documents, context } = this.#owner;
+        try {
+            await documents.tx((tx) => {
+                const outcome = this.#outcome(run, ended);
+                this.change(tx, { kind: "outcome", run, outcome });
+                // What its state holds is stored before the outcome is recorded (D8).
+                const adopt = this.#persisted === undefined ? undefined : this.#states?.stageHeld(run.id, this.#store(tx));
+                if (adopt !== undefined)
+                    this.staging(tx).adopts.push(adopt);
+            }, documents.own, context);
+        }
+        catch {
+            // The object ended: nothing finishes.
+            return;
+        }
+        finally {
+            // A run ending without an invocation (marked aborted, abandoned, cut off in memory) has none to wait for.
+            run.invocation?.ended();
+        }
+        this.#need(run);
+    }
+    /** `run`'s outcome for `ended`, with its args and its state as it is now. */
+    #outcome(run, ended) {
+        return { id: run.id, args: run.args, state: this.stateOf(run.id), ...ended };
+    }
+    /** `run` needs a live attempt (to be invoked or finished): now, or once one attaches. */
+    #need(run) {
+        if (this.#ended !== undefined || this.#runs.get(run.id) !== run)
+            return;
+        // A job the code no longer declares: blocked `version`, kept (slice 7b §8).
+        if (!this.#declared) {
+            if (run.phase !== "blocked")
+                void this.record(run, { kind: "block", run, reason: "version" });
+            return;
+        }
+        const job = this.#job;
+        if (job === undefined)
+            this.#waiting.add(run);
+        else
+            this.#dispatch(run, job);
+    }
+    /**
+     * Invokes or finishes `run` on `job`, as its record stands: a finishing run is finished; a run not invoked yet is
+     * invoked, unless it is marked aborted (it ends `aborted` without `run`) or resumes abandoned (`failed { aborted,
+     * reason: "restart" }`).
+     */
+    #dispatch(run, job) {
+        if (this.#runs.get(run.id) !== run || run.phase === "blocked")
+            return;
+        // Not of a version the code takes: blocked `version` until a reload brings matching code.
+        if (!this.#takes(run)) {
+            void this.record(run, { kind: "block", run, reason: "version" });
+            return;
+        }
+        if (run.phase === "finishing") {
+            job.finish(run);
+            return;
+        }
+        if (run.invoked)
+            return;
+        if (run.abortMarked) {
+            void this.#recordOutcome(run, ABORTED);
+            return;
+        }
+        if (run.resuming && this.definition.persist?.resume === "abandon") {
+            void this.#recordOutcome(run, RESTART);
+            return;
+        }
+        run.resuming = false;
+        job.invoke(run);
+    }
+    /**
+     * Adopts one record change, inside the commit step: the maps, the active count, `running`. A new run is counted for
+     * its object here, before the commit's publication (a link closing while it sends may release the object's last
+     * reference) and before any run of the same commit settles in `#committed`.
+     */
+    #adopt(change) {
+        const { run } = change;
+        switch (change.kind) {
+            case "create":
+            case "restore":
+                this.#runs.set(run.id, run);
+                if (run.key !== undefined)
+                    this.#keys.set(run.key, run);
+                if (run.phase !== "blocked") {
+                    this.#active++;
+                    this.#owner.countRuns(1);
+                }
+                run.entry = this.#entryOf(run);
+                this.running.add(run.entry);
+                return;
+            case "update":
+                Object.assign(run, change.fields);
+                this.#replaceEntry(run);
+                return;
+            case "outcome":
+                run.outcome = change.outcome;
+                run.phase = "finishing";
+                this.#replaceEntry(run);
+                return;
+            case "block":
+                run.phase = "blocked";
+                run.blocked = change.reason;
+                this.#active--;
+                this.#replaceEntry(run);
+                return;
+            case "unblock":
+                run.phase = change.phase;
+                run.blocked = undefined;
+                run.blockedPhase = undefined;
+                run.finishFailures = 0;
+                // A persisted run to be invoked again resumes per its job's `resume`, as after a stop.
+                if (change.phase === "pending")
+                    run.resuming = true;
+                this.#active++;
+                this.#owner.countRuns(1);
+                this.#replaceEntry(run);
+                return;
+            case "delete":
+            case "drop":
+                this.#runs.delete(run.id);
+                // The finishing run's key may name its successor already, started in the same commit.
+                if (run.key !== undefined && this.#keys.get(run.key) === run)
+                    this.#keys.delete(run.key);
+                if (change.kind === "delete")
+                    this.#active--;
+                this.running.remove(run.entry);
+                run.entry = undefined;
+                return;
+        }
+    }
+    /** The actions after a record change committed. */
+    #committed(change) {
+        const { run } = change;
+        switch (change.kind) {
+            case "create":
+                // After the commit, outside the batch, once the transaction settled; on the live attempt, or the next.
+                queueMicrotask(() => this.#need(run));
+                return;
+            case "restore":
+            case "update":
+            case "outcome":
+                return;
+            case "delete":
+                this.#owner.countRuns(-1);
+                run.resolve(run.outcome);
+                return;
+            case "block":
+                this.#owner.countRuns(-1);
+                return;
+            case "unblock":
+                this.#need(run);
+                return;
+            case "drop":
+                this.report({ kind: "job_dropped", id: run.id });
+                run.reject(new ChordError({ code: "aborted", message: `${this.name}: run ${run.id} dropped` }));
+                return;
+        }
+    }
+    /** A run's state document changed by `ops`, inside the commit step: its entry is replaced. */
+    #stateChanged(id, ops) {
+        const run = this.#runs.get(id);
+        // Its record may not be adopted yet (a start creates both in one commit; its entry takes the state then).
+        if (run?.entry === undefined)
+            return;
+        const before = run.entry;
+        run.entry = this.#entryOf(run);
+        this.running.stateChanged(before, run.entry, ops);
+    }
+    /** A run's record changed, inside the commit step: its entry is replaced. */
+    #replaceEntry(run) {
+        const before = run.entry;
+        run.entry = this.#entryOf(run);
+        this.running.replace(before, run.entry);
+    }
+    /**
+     * `run`'s `running` entry: blocked, or with its state and its args as the current code takes them (an older run's
+     * mapped; one the code does not take, or whose mapping throws, shows its own).
+     */
+    #entryOf(run) {
+        let args = run.args;
+        if (run.phase !== "blocked" && run.version !== this.definition.version && this.#takes(run)) {
+            try {
+                args = this.argsOf(run, this.definition);
+            }
+            catch {
+                // The provider's mapping threw: its own args (its finish meets the same throw and is retried).
+            }
+        }
+        return run.entryFor(this.stateOf(run.id), args);
+    }
+    #discarded() {
+        return new ChordError({
+            code: "released",
+            reason: "discarded",
+            message: `${this.name}: the start's transaction was discarded`,
+        });
+    }
+}
+/** Runs every adoption of `adopts`. */
+function runAll(adopts) {
+    for (const adopt of adopts)
+        adopt();
+}
+/** The record fields a change writes, its phase transitions included. */
+function recordFields(change) {
+    switch (change.kind) {
+        case "create":
+            return {};
+        case "update":
+            return change.fields;
+        case "outcome":
+            return { phase: "finishing", outcome: change.outcome };
+        case "block":
+            return { phase: "blocked", blocked: change.reason };
+        case "unblock":
+            return { phase: change.phase, blocked: undefined, finishFailures: 0 };
+    }
+}
+//# sourceMappingURL=records.js.map