@earendil-works/chord 1.5.0 → 1.5.1

package/dist/jobs/records.d.ts

@@ -0,0 +1,231 @@
+import { type Context } from "../context/index.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 { JsonValue } from "../json.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/jobs/records.d.ts.map

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