@earendil-works/chord 1.4.0 → 1.5.0

package/dist/next/jobs/persisted.js

@@ -0,0 +1,95 @@
+// A persisted job's run records in its object's store (slice 6b §4.1, D5): the record document of each unsettled run
+// (namespace `chord.jobs`, kind the job name, key the run id, `history: none`), written whole in the transactions that
+// change the run, and read once per object when it first activates; for a run of another job version, also what is
+// stored of its state document (`chord.job-states`), never decoded, so its drop retires it whatever the code declares.
+import { changeDocument, createDocument, retireDocument } from "../store/engine.js";
+import { RUN_RECORD, recordOf } from "./stored.js";
+/** The keys a load reads per page. */
+const KEYS_PAGE = 100;
+/** The record documents of one persisted job's runs, and what is stored of each. */
+export class PersistedRuns {
+    #records;
+    #states;
+    #stored = new Map();
+    /** What is stored of the state documents of runs of another job version, by run id. */
+    #blockedStates = new Map();
+    /** `records` and `states` are the job's record and state documents' store sides (`chord.jobs`, `chord.job-states`). */
+    constructor(records, states) {
+        this.#records = records;
+        this.#states = states;
+    }
+    /**
+     * Stages run `id`'s record `record` into `writes` (rule 8: serialized now): its creation, or a new base of what is
+     * stored; returns the adoption, which takes what the commit stored.
+     */
+    stage(id, record, writes) {
+        const text = JSON.stringify(record);
+        const stored = this.#stored.get(id);
+        const { version, fingerprint } = RUN_RECORD;
+        const value = record;
+        if (stored === undefined) {
+            const created = { id: 0 };
+            writes.push(createDocument(this.#records.at(id), { version, fingerprint, value }, text, (made) => {
+                created.id = made;
+            }));
+            return () => this.#stored.set(id, { id: created.id, revision: 1, version, deltasSinceBase: 0 });
+        }
+        writes.push(changeDocument(stored.id, stored.revision, { kind: "base", version, fingerprint, value }, text));
+        return () => this.#stored.set(id, { ...stored, revision: stored.revision + 1 });
+    }
+    /**
+     * Stages the retirement of run `id`'s record into `writes` (the run settled or was dropped), and of its state
+     * document when the run is of another job version; the adoption forgets them.
+     */
+    stageRetire(id, writes) {
+        const stored = this.#stored.get(id);
+        if (stored !== undefined)
+            writes.push(retireDocument(stored.id, stored.revision));
+        const state = this.#blockedStates.get(id);
+        if (state !== undefined)
+            writes.push(retireDocument(state.id, state.revision));
+        return () => {
+            this.#stored.delete(id);
+            this.#blockedStates.delete(id);
+        };
+    }
+    /** Finds what is stored of run `id`'s state document (a run of another job version), keeping it for the drop. */
+    async findBlockedState(id, context) {
+        const found = await this.#states.find(id, context);
+        if (found !== undefined)
+            this.#blockedStates.set(id, found.stored);
+    }
+    /**
+     * A run of another job version that a reload's code now takes (`retryBlocked`): its state document is the job's
+     * again (read, decoded and retired with its record as any run's), no longer one to retire undecoded.
+     */
+    forgetBlockedState(id) {
+        this.#blockedStates.delete(id);
+    }
+    /** Every stored record of the job, in run id order, page by page with plain reads (activation holds the line). */
+    async load(context) {
+        const loaded = [];
+        let after;
+        for (;;) {
+            const keys = await this.#records.keys(after, KEYS_PAGE, context);
+            for (const id of keys) {
+                const document = await this.#records.read(id, context);
+                if (document === undefined)
+                    continue;
+                const { record: stored, value, deltasSinceBase } = document;
+                const found = { id: stored.id, revision: stored.revision, version: stored.version, deltasSinceBase };
+                this.#stored.set(id, found);
+                loaded.push({ id, record: recordOf(value), stored: found });
+            }
+            if (keys.length < KEYS_PAGE)
+                return loaded;
+            after = keys.at(-1);
+        }
+    }
+    /** The object's documents are dropped: nothing is known of the store any more. */
+    drop() {
+        this.#stored.clear();
+        this.#blockedStates.clear();
+    }
+}
+//# sourceMappingURL=persisted.js.map

package/dist/next/jobs/persisted.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persisted.js","sourceRoot":"","sources":["../../../src/next/jobs/persisted.ts"],"names":[],"mappings":"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","sourcesContent":["// A persisted job's run records in its object's store (slice 6b §4.1, D5): the record document of each unsettled run\n// (namespace `chord.jobs`, kind the job name, key the run id, `history: none`), written whole in the transactions that\n// change the run, and read once per object when it first activates; for a run of another job version, also what is\n// stored of its state document (`chord.job-states`), never decoded, so its drop retires it whatever the code declares.\n\nimport type { Context } from \"../../context/index.ts\";\nimport type { JsonObject } from \"../documents/index.ts\";\nimport type { Persistence, Stored } from \"../documents/internal.ts\";\nimport { changeDocument, createDocument, retireDocument } from \"../store/engine.ts\";\nimport type { StagedWrite } from \"../store/step.ts\";\nimport { RUN_RECORD, recordOf, type StoredRun } from \"./stored.ts\";\n\n/** A run record as a load found it: its run id, the record and what is stored of it. */\nexport type LoadedRecord = { readonly id: string; readonly record: StoredRun; readonly stored: Stored };\n\n/** The keys a load reads per page. */\nconst KEYS_PAGE = 100;\n\n/** The record documents of one persisted job's runs, and what is stored of each. */\nexport class PersistedRuns {\n\treadonly #records: Persistence;\n\treadonly #states: Persistence;\n\treadonly #stored = new Map<string, Stored>();\n\t/** What is stored of the state documents of runs of another job version, by run id. */\n\treadonly #blockedStates = new Map<string, Stored>();\n\n\t/** `records` and `states` are the job's record and state documents' store sides (`chord.jobs`, `chord.job-states`). */\n\tconstructor(records: Persistence, states: Persistence) {\n\t\tthis.#records = records;\n\t\tthis.#states = states;\n\t}\n\n\t/**\n\t * Stages run `id`'s record `record` into `writes` (rule 8: serialized now): its creation, or a new base of what is\n\t * stored; returns the adoption, which takes what the commit stored.\n\t */\n\tstage(id: string, record: StoredRun, writes: StagedWrite[]): () => void {\n\t\tconst text = JSON.stringify(record);\n\t\tconst stored = this.#stored.get(id);\n\t\tconst { version, fingerprint } = RUN_RECORD;\n\t\tconst value = record as unknown as JsonObject;\n\t\tif (stored === undefined) {\n\t\t\tconst created = { id: 0 };\n\t\t\twrites.push(\n\t\t\t\tcreateDocument(this.#records.at(id), { version, fingerprint, value }, text, (made) => {\n\t\t\t\t\tcreated.id = made;\n\t\t\t\t}),\n\t\t\t);\n\t\t\treturn () => this.#stored.set(id, { id: created.id, revision: 1, version, deltasSinceBase: 0 });\n\t\t}\n\t\twrites.push(changeDocument(stored.id, stored.revision, { kind: \"base\", version, fingerprint, value }, text));\n\t\treturn () => this.#stored.set(id, { ...stored, revision: stored.revision + 1 });\n\t}\n\n\t/**\n\t * Stages the retirement of run `id`'s record into `writes` (the run settled or was dropped), and of its state\n\t * document when the run is of another job version; the adoption forgets them.\n\t */\n\tstageRetire(id: string, writes: StagedWrite[]): () => void {\n\t\tconst stored = this.#stored.get(id);\n\t\tif (stored !== undefined) writes.push(retireDocument(stored.id, stored.revision));\n\t\tconst state = this.#blockedStates.get(id);\n\t\tif (state !== undefined) writes.push(retireDocument(state.id, state.revision));\n\t\treturn () => {\n\t\t\tthis.#stored.delete(id);\n\t\t\tthis.#blockedStates.delete(id);\n\t\t};\n\t}\n\n\t/** Finds what is stored of run `id`'s state document (a run of another job version), keeping it for the drop. */\n\tasync findBlockedState(id: string, context: Context): Promise<void> {\n\t\tconst found = await this.#states.find(id, context);\n\t\tif (found !== undefined) this.#blockedStates.set(id, found.stored);\n\t}\n\n\t/**\n\t * A run of another job version that a reload's code now takes (`retryBlocked`): its state document is the job's\n\t * again (read, decoded and retired with its record as any run's), no longer one to retire undecoded.\n\t */\n\tforgetBlockedState(id: string): void {\n\t\tthis.#blockedStates.delete(id);\n\t}\n\n\t/** Every stored record of the job, in run id order, page by page with plain reads (activation holds the line). */\n\tasync load(context: Context): Promise<LoadedRecord[]> {\n\t\tconst loaded: LoadedRecord[] = [];\n\t\tlet after: string | undefined;\n\t\tfor (;;) {\n\t\t\tconst keys = await this.#records.keys(after, KEYS_PAGE, context);\n\t\t\tfor (const id of keys) {\n\t\t\t\tconst document = await this.#records.read(id, context);\n\t\t\t\tif (document === undefined) continue;\n\t\t\t\tconst { record: stored, value, deltasSinceBase } = document;\n\t\t\t\tconst found = { id: stored.id, revision: stored.revision, version: stored.version, deltasSinceBase };\n\t\t\t\tthis.#stored.set(id, found);\n\t\t\t\tloaded.push({ id, record: recordOf(value as JsonObject), stored: found });\n\t\t\t}\n\t\t\tif (keys.length < KEYS_PAGE) return loaded;\n\t\t\tafter = keys.at(-1);\n\t\t}\n\t}\n\n\t/** The object's documents are dropped: nothing is known of the store any more. */\n\tdrop(): void {\n\t\tthis.#stored.clear();\n\t\tthis.#blockedStates.clear();\n\t}\n}\n"]}

package/dist/next/jobs/records.d.ts

@@ -0,0 +1,231 @@
+import { type Context } from "../../context/index.ts";
+import type { JsonValue } from "../../json.ts";
+import { ChordError } from "../data/index.ts";
+import type { JsonObject } from "../documents/index.ts";
+import { type Documents, type Staged, type Transaction } from "../documents/internal.ts";
+import type { AnyHost } from "../host/internal.ts";
+import type { ChordStore } from "../store/store.ts";
+import type { JobDefinition, JobError } from "./definition.ts";
+import type { CutReason, Job, StartOptions } from "./job.ts";
+import { type AnyOutcome, type BlockedReason, JobRun, type Phase, type Run } from "./run.ts";
+import { RunStates } from "./run-states.ts";
+import { Running } from "./running.ts";
+/** What a job's records need of their object. */
+export type RecordsOwner = {
+    readonly label: string;
+    readonly host: AnyHost;
+    /** The object's context, without an abort signal: outcomes are recorded under it. */
+    readonly context: Context;
+    readonly documents: Documents;
+    /** The host's store and the object's owner name in it, when the object may persist (P3). */
+    readonly store: {
+        readonly store: ChordStore;
+        readonly owner: string;
+    } | undefined;
+    /** Counts running and finishing runs: they keep the object alive (`host.activity.jobs`). */
+    countRuns(delta: number): void;
+    /** A held state change must be stored by `deadline`: the object's one timer flushes it (D8). */
+    held(deadline: number): void;
+};
+/** How a run's invocation ended, before its outcome is recorded. */
+export type Settled = {
+    readonly kind: "done";
+    readonly result: unknown;
+} | {
+    readonly kind: "failed";
+    readonly error: JobError;
+};
+/** What a change sets on a run's record besides its phase transitions below (D6, D7, the finish failure count). */
+type RunFields = {
+    readonly phase?: Phase;
+    readonly restarts?: number;
+    readonly finishFailures?: number;
+    readonly abortMarked?: true;
+};
+/** A change of the records, staged in a transaction and adopted in its commit step. */
+type RecordChange = {
+    readonly kind: "create";
+    readonly run: JobRun;
+} | {
+    readonly kind: "update";
+    readonly run: JobRun;
+    readonly fields: RunFields;
+} | {
+    readonly kind: "outcome";
+    readonly run: JobRun;
+    readonly outcome: AnyOutcome;
+} | {
+    readonly kind: "block";
+    readonly run: JobRun;
+    readonly reason: BlockedReason;
+}
+/** A blocked run is retried (a reload): back to `phase` (finishing with its outcome, or to be invoked). */
+ | {
+    readonly kind: "unblock";
+    readonly run: JobRun;
+    readonly phase: Phase;
+} | {
+    readonly kind: "delete";
+    readonly run: JobRun;
+} | {
+    readonly kind: "drop";
+    readonly run: JobRun;
+};
+/** What a commit step adopts of the records: a change, or a loaded run taken into memory as stored. */
+type Adopted = RecordChange | {
+    readonly kind: "restore";
+    readonly run: JobRun;
+};
+/** One transaction's changes of one job: the runs it started (dedupe, concurrency) and whose finish it is. */
+export type Staging = Staged & {
+    readonly started: JobRun[];
+    readonly changes: Adopted[];
+    /** What the transaction's store writes leave in memory, adopted with the changes. */
+    readonly adopts: (() => void)[];
+    finishing: JobRun | undefined;
+};
+/**
+ * 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 declare class JobRecords {
+    #private;
+    /** The latest declaration's definition: a reload's new attempt redefines it; each run keeps its own version. */
+    definition: JobDefinition<unknown, unknown, unknown>;
+    readonly running: Running;
+    constructor(definition: JobDefinition<unknown, unknown, unknown>, owner: RecordsOwner);
+    /**
+     * 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: JobDefinition<unknown, unknown, unknown>): void;
+    /**
+     * 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: JobDefinition<unknown, unknown, unknown>): void;
+    /**
+     * 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(): void;
+    /**
+     * 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.
+     */
+    retryBlocked(context: Context): Promise<void>;
+    /**
+     * `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: JobRun, definition: JobDefinition<unknown, unknown, unknown>): JsonValue;
+    /**
+     * `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: JobRun, context: Context): AnyOutcome;
+    /** The job in errors: its object and its name. */
+    get name(): string;
+    /** Waits for the outcome of the unsettled run `id`; a settled or unknown id rejects `gone`. */
+    outcome(id: string, context: Context): Promise<AnyOutcome>;
+    /**
+     * 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.
+     */
+    abort(id: string, context: Context): Promise<"marked" | "terminal">;
+    /** See `Job.stage`: the checks and the staged creation, against the object's runs. */
+    stage(tx: Transaction, args: unknown, context: Context, options: StartOptions): Run<AnyOutcome>;
+    /**
+     * 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: Transaction, change: RecordChange): void;
+    /** This job's changes in `tx`, made on the first. */
+    staging(tx: Transaction): Staging;
+    /**
+     * 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.
+     */
+    load(context: Context): Promise<void>;
+    /** `job`, of the attempt that went live, invokes and finishes the runs from now on; the waiting ones first. */
+    attach(job: Job): void;
+    /**
+     * `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: Job, finishing: Iterable<JobRun>): void;
+    /**
+     * 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: JobRun): void;
+    /** Records `run` running before its `run` is invoked (a persisted run's reservation: a crash after it counts). */
+    reserve(tx: Transaction, run: JobRun): void;
+    /** A state change of a run with restarts counted resets them in its commit (progress, D6). */
+    progressed(tx: Transaction, run: JobRun): void;
+    /**
+     * 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: JobRun, ended: Settled): void;
+    /**
+     * 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: JobRun, error: ChordError, reason: CutReason): void;
+    /**
+     * 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.
+     */
+    record(run: JobRun, change: RecordChange): Promise<void>;
+    /**
+     * 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).
+     */
+    writeAtClose(context: Context): Promise<void>;
+    /** Stores every held state change whose deadline passed (`now`), in one transaction of the object (D8). */
+    flushHeld(now: number): Promise<void>;
+    /** The earliest deadline of a held state change (`Infinity`: none). */
+    nextDeadline(): number;
+    /** The value of run `id`'s state document, `undefined` without one or once retired. */
+    stateOf(id: string): JsonObject | undefined;
+    /** The run state documents, for `ctx.state.change`; `undefined` without a state definition. */
+    get states(): RunStates | undefined;
+    /** Whether the job persists its runs. */
+    get persisted(): boolean;
+    /**
+     * 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: ChordError): void;
+    /** Its object's documents are dropped: the runs, their state documents and `running`'s watches go. */
+    drop(): void;
+    /** Reports a run's failure, drop or interruption to the host. */
+    report(error: {
+        readonly kind: "job_failed" | "job_finish_failed";
+        readonly id: string;
+        readonly error: unknown;
+    } | {
+        readonly kind: "job_dropped";
+        readonly id: string;
+    } | {
+        readonly kind: "job_interrupted";
+        readonly id: string;
+        readonly restarts: number;
+    }): void;
+}
+export {};
+//# sourceMappingURL=records.d.ts.map

package/dist/next/jobs/records.d.ts.map

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