@substrat-run/kernel 0.114.0 → 0.117.0

package/dist/job-run.d.ts

@@ -0,0 +1,493 @@
+import { type ModuleId } from '@substrat-run/contracts';
+import { type ExecutorRetryPolicy, type ScopeStub } from './scope-host.js';
+/**
+ * The fourth driver (#1577): long, resumable, coalesced work.
+ *
+ * Three drivers already move work off a request, and each is correct for what it
+ * is. `registerExecutor` + `drainDue` retries ONE delivery, whole. A declared
+ * schedule + `runDueSchedules` fires ONE operation inside a cadence window, which
+ * must then finish. `runPlatformSweep` does a pass of per-unit maintenance and
+ * reports it. None of them covers the shape this file names:
+ *
+ *   Walk 100 000 objects in an external system. It takes an hour. It must survive a
+ *   worker eviction, a deploy and a transient upstream failure by CONTINUING WHERE IT
+ *   STOPPED. Only one walk per source may run at a time, and asking for a second while
+ *   one is in flight must join the first. When it ends the outcome has to be legible.
+ *
+ * ## The model, in four words: run, pass, step, cursor
+ *
+ * A **run** is the durable record — one `_substrat_job_runs` row, in the scope, with
+ * its status, its resume cursor, a counter bag, its start/end and its last error. It
+ * is what an operator reads afterwards, and it is the thing coalescing joins.
+ *
+ * A **pass** is one invocation of the job's handler. A pass does a BOUNDED chunk of
+ * the walk and hands a cursor forward; the next pass resumes from it. That is the
+ * whole of resume at the outer level, and it is why a 100 000-object walk is not a
+ * single hour-long call anybody has to keep alive.
+ *
+ * A **step** is a named unit inside a pass. Its result is committed as it completes,
+ * so a step that already succeeded is NOT re-run — not on a retry of the step after
+ * it, and not after the process was killed mid-pass. That is resume at the inner
+ * level, and it is what "no step before it repeated" means.
+ *
+ * A **cursor** is whatever the handler says the next pass should resume from — an id,
+ * a page token, an offset. Opaque to the driver, stored as JSON, held to the payload
+ * rule below because it has to survive the same trip.
+ *
+ * **The step ledger is per PASS, and that is deliberate.** When a pass commits, its
+ * step rows are dropped: the next pass is new work, named by the new cursor, and a
+ * ledger that accumulated across an hour-long walk would be the unbounded table this
+ * design exists to avoid. The cursor carries progress BETWEEN passes; the ledger
+ * carries it WITHIN one.
+ *
+ * ## The determinism rule, and the half of it that is mechanical
+ *
+ * Step names must be a pure function of the payload and prior results. If a name
+ * varies between passes — a timestamp in it, a random suffix — the memo never hits,
+ * every resume replays work that already happened, and resume is a lie told in a
+ * green test. That rule cannot be fully checked from here; what CAN be checked is
+ * the sharpest way to break it, and is: two `step()` calls under ONE name in ONE
+ * pass are refused (`JOB_STEP_REUSED`), because the second would read the first's
+ * memo and silently skip its own work.
+ *
+ * ## Coalescing is the DRIVER's, never a unique index
+ *
+ * One run in flight per `(module, job, instance)`. `startJobRun` looks for a live row
+ * and RETURNS it rather than inserting a second. It is not a `UNIQUE` constraint, and
+ * that is the point: a run whose process was killed is still `running`, and it must be
+ * restartable — a uniqueness constraint would be "one row ever", which would refuse
+ * the re-import that has to happen next year as loudly as it refuses the duplicate.
+ * `_substrat_sweep_runs` is a RECEIPT and carries such a constraint; a cursor is not a
+ * receipt, and the two must not be re-merged (#1571, #1572).
+ *
+ * ## One driver per scope at a time — a stated bound, not a mechanism
+ *
+ * Coalescing stops duplicate RUNS. It does not stop two concurrent callers of
+ * `runDueJobs` from picking the same run out of the due read and advancing it at the
+ * same time: there is no lease, and a lease is not smuggled in here. The topology the
+ * driver is built for has one tick per scope — `runPlatformSweep` enumerates scopes
+ * and does one call each, a scope DO's alarm fires for its own scope — so the bound
+ * is satisfied by construction rather than defended against.
+ *
+ * What the overlap would cost, if a deployment did drive one scope twice at once: the
+ * step ledger absorbs most of it (a step already committed returns its memo to both),
+ * so the exposure is a step neither pass has finished yet, which both would run. That
+ * is the same at-least-once residue an executor already has and which handlers already
+ * have to absorb — but it is NOT what "only one walk per source at a time" promises,
+ * so it is written down rather than implied. Adding a lease is a real design with a
+ * real expiry question behind it (a leaked lease is a run nothing will ever touch
+ * again), and it wants a consumer's numbers before it gets one.
+ *
+ * ## What this is NOT
+ *
+ * Not a workflow engine: no branching, no fan-out, no BPMN, no timers between steps.
+ * A linear, resumable, coalesced sequence of steps with a cursor — the smallest thing
+ * that makes an hour-long import survivable. A use case that needs branching is a
+ * different issue and probably a different answer.
+ */
+/**
+ * The run table and its step ledger, as both adapters build them.
+ *
+ * Shared rather than spelled twice for the reason `IDEMPOTENCY_DDL` and
+ * `SCHEDULE_STATE_DDL` are: `lint:spine-ddl` compares what each adapter's
+ * `KERNEL_DDL` executes, and one definition is what keeps the self-hosted store
+ * and the hosted store the same shape rather than merely the same intention.
+ * Spine — kernel-written, `_substrat_*`, never a module migration.
+ */
+export declare const JOB_RUN_DDL = "\n  CREATE TABLE IF NOT EXISTS _substrat_job_runs (\n    id TEXT PRIMARY KEY,\n    -- The coalescing key: one LIVE run per (module_id, job, instance). Not a UNIQUE\n    -- index, deliberately -- see this file's header. instance names WHAT is being\n    -- walked (a source id, a mapping version); a job with one walk per scope uses\n    -- the 'default' the input schema fills in.\n    module_id TEXT NOT NULL,\n    job TEXT NOT NULL,\n    instance TEXT NOT NULL,\n    -- What start() was handed, as JSON. Held to the queue-safety rule\n    -- (assertQueueSafe): ids and configuration, never bytes, class instances or\n    -- functions, because this value has to survive a queue message unchanged.\n    payload TEXT NOT NULL,\n    -- 'running' | 'done' | 'failed'. A killed run stays 'running' and is picked up\n    -- again by the next drive -- which is exactly what makes it restartable.\n    status TEXT NOT NULL,\n    -- What the last COMMITTED pass handed forward, as JSON. NULL = no pass has\n    -- committed yet, which is a fact ('start from the beginning'), not missing data.\n    cursor TEXT,\n    -- The run's counter bag (JSON object of numbers), merged on each commit. An\n    -- uncommitted pass's counts are discarded with the rest of the pass.\n    counters TEXT NOT NULL DEFAULT '{}',\n    -- CONSECUTIVE failed passes. Reset to 0 whenever a pass commits, so this reads\n    -- as \"how stuck is it now\", not \"how much work has it done\".\n    attempts INTEGER NOT NULL DEFAULT 0,\n    -- The error the last failed pass left. Retained after the run goes 'failed' --\n    -- the record is the evidence, so it must still say why.\n    last_error TEXT,\n    started_at TEXT NOT NULL,\n    updated_at TEXT NOT NULL,\n    -- When the next pass may run, on the executor's own backoff curve. NULL = now\n    -- (or terminal), which is why the due read tests IS NULL as well as <= now.\n    next_attempt_at TEXT,\n    -- When the run reached 'done' or 'failed'. NULL while it is still running.\n    ended_at TEXT\n  );\n  -- The drive's read: WHERE status = 'running' AND (next_attempt_at IS NULL OR <= ?)\n  -- ORDER BY id. Leading with status makes the live runs a seekable range over a\n  -- table that RETAINS every finished run, so the cost tracks how much is in flight\n  -- rather than how much the scope has ever imported.\n  CREATE INDEX IF NOT EXISTS _substrat_job_runs_due ON _substrat_job_runs (status, next_attempt_at, id);\n  -- Coalescing's read, and the operator read's filter.\n  CREATE INDEX IF NOT EXISTS _substrat_job_runs_key ON _substrat_job_runs (module_id, job, instance, id);\n  -- The step ledger of the pass currently in flight. Rows are written as each step\n  -- COMPLETES and dropped when the pass COMMITS, so this holds one pass's worth of\n  -- steps and never grows with the length of the walk.\n  --\n  -- A FAILED run keeps its last pass's rows, deliberately: they are the difference\n  -- between \"it got nowhere\" and \"it got three quarters of the way and then the\n  -- provider went down\", which the run row's single last_error cannot say. Still\n  -- bounded -- one pass's worth per failed run -- because a restart is a NEW run\n  -- with a new id and therefore its own ledger.\n  CREATE TABLE IF NOT EXISTS _substrat_job_steps (\n    run_id TEXT NOT NULL,\n    step TEXT NOT NULL,\n    -- The step's return value as JSON. NOT NULL is what MEANS completed: a step that\n    -- threw leaves the row with a NULL result and a raised attempts count, so the\n    -- next pass runs it again rather than reading a success that never happened. A\n    -- step returning nothing stores the JSON text 'null', which is not SQL NULL.\n    result TEXT,\n    attempts INTEGER NOT NULL DEFAULT 0,\n    last_error TEXT,\n    recorded_at TEXT NOT NULL,\n    PRIMARY KEY (run_id, step)\n  );\n";
+/** Where a run is. A killed run is `running` — that is what makes it resumable. */
+export type JobRunStatus = 'running' | 'done' | 'failed';
+/** The coalescing key: one LIVE run per triple. */
+export interface JobRunKey {
+    moduleId: ModuleId;
+    /** The job's name, as `registerJob` declared it. */
+    job: string;
+    /** What is being walked — a source id, a mapping version. `'default'` when there is one. */
+    instance: string;
+}
+/** The durable run record, as an operator reads it. */
+export interface JobRun extends JobRunKey {
+    id: string;
+    status: JobRunStatus;
+    /** What `startJobRun` was handed. */
+    payload: unknown;
+    /** What the last COMMITTED pass handed forward; null before the first commit. */
+    cursor: unknown;
+    counters: Record<string, number>;
+    /** Consecutive failed passes; 0 after any commit. */
+    attempts: number;
+    lastError: string | null;
+    startedAt: string;
+    updatedAt: string;
+    nextAttemptAt: string | null;
+    endedAt: string | null;
+    /**
+     * Why this row could not be read whole, or null — which is the ordinary case and
+     * what every run written by this driver carries.
+     *
+     * Present because the read and the DRIVER want opposite things from a malformed
+     * row, and both are right. A pass cannot run on a payload it cannot decode, so the
+     * driver fails the run and records why. The READ exists so an operator can see
+     * exactly that — and a read that threw on the one row being investigated would
+     * take every other run on the scope with it, since this returns a list. So the
+     * decode here is tolerant and SAYS SO: the undecodable columns come back empty
+     * (`null` / `{}`) with the parse error named here, rather than a silent `null`
+     * that reads as "no cursor".
+     *
+     * Reachable without any forge: `importDump` replays a dump's rows verbatim, so a
+     * dump from another world or edited by hand is enough.
+     */
+    decodeError: string | null;
+}
+/** What `startJobRun` is handed. */
+export interface StartJobRunInput {
+    moduleId: ModuleId;
+    job: string;
+    /** Defaults to `'default'` — a job with one walk per scope needs no instance. */
+    instance?: string;
+    /** Ids and configuration. Refused at this boundary if it is anything else. */
+    payload?: unknown;
+}
+/** The operator read's filter. Every field narrows; none is required. */
+export interface JobRunFilter {
+    moduleId?: ModuleId;
+    job?: string;
+    instance?: string;
+    status?: JobRunStatus;
+    /** Default `JOB_RUN_LIST_LIMIT`. */
+    limit?: number;
+}
+/** Rows one `jobRuns` read returns by default. */
+export declare const JOB_RUN_LIST_LIMIT = 50;
+/** The most rows one `jobRuns` read will ever return, whatever the caller asks for. */
+export declare const JOB_RUN_LIST_MAX = 500;
+/**
+ * The row budget for one operator read, normalised before it reaches SQL.
+ *
+ * `JobRunFilter.limit` comes from a caller and was bound straight to `LIMIT`, where
+ * SQLite reads a NEGATIVE value as unbounded, refuses a fractional one outright, and
+ * honours an oversized one. Since finished runs are retained, "unbounded" means the
+ * scope's entire history in one response — a read whose cost grows with retention,
+ * reachable by passing `-1`. Clamped here rather than in each adapter so the pure and
+ * the hosted read cannot answer the same filter differently.
+ */
+export declare function jobRunListLimit(limit: number | undefined): number;
+/** Runs one `runDueJobs` call picks up by default. */
+export declare const JOB_DRIVE_LIMIT = 50;
+/**
+ * Rows one `runDueJobs` call will READ while looking for runnable ones.
+ *
+ * The drive skips runs whose job this host does not register, so "read `limit` rows"
+ * and "find `limit` runs to drive" are different numbers, and a scope can hold an
+ * arbitrary number of the unrunnable kind. This caps the difference: past it the call
+ * drives what it found and returns, rather than scanning a scope's whole history on a
+ * maintenance tick.
+ */
+export declare const JOB_DRIVE_SCAN_MAX = 500;
+/** What a handler says at the end of a pass. */
+export interface JobPassResult {
+    /**
+     * What the NEXT pass resumes from. Omitted keeps the cursor the last pass
+     * committed — which is how a pass that only did steps, and moved nothing on,
+     * says so. Held to the same queue-safety rule as the payload.
+     */
+    cursor?: unknown;
+    /** True when the walk is finished: the run goes `done` and is never driven again. */
+    done?: boolean;
+}
+/** What one pass of a job is given. */
+export interface JobPassContext {
+    /** This run's id and coalescing key. */
+    readonly run: JobRunKey & {
+        id: string;
+    };
+    /** What `startJobRun` was handed, decoded. */
+    readonly payload: unknown;
+    /** What the last committed pass handed forward; `null` on the first pass. */
+    readonly cursor: unknown;
+    /** The counter bag as of the last commit. `count()` adds to the pass's copy. */
+    readonly counters: Readonly<Record<string, number>>;
+    /**
+     * Run one NAMED step, at most once per run-pass.
+     *
+     * A step whose result is already committed returns it WITHOUT running `fn` —
+     * that is the memo, and it is what survives both a retry of a later step and a
+     * process kill mid-pass. A step that throws records its attempt and fails the
+     * pass; the next pass replays the handler, skips every committed step above,
+     * and runs this one again until its own `retry` is exhausted.
+     *
+     * `name` must be a pure function of the payload and prior results. Two calls
+     * under one name in one pass are refused rather than silently memo-aliased.
+     *
+     * **AT-LEAST-ONCE. `fn` must be idempotent, and this is not a formality.** The
+     * ledger row is written AFTER `fn` resolves, which is the only ordering that is
+     * safe — claiming the step first would make it at-most-once and lose the effect on
+     * any crash in between. The cost is the opposite window: a stop after `fn`'s effect
+     * lands and before `recordStep` commits leaves no memo, so the next pass runs that
+     * effect a second time. It is the same trade, made the same way and for the same
+     * reason, as `recordExecutorDelivery` in the executor journal — whose docblock says
+     * it plainly — and like an executor handler, a step body absorbs the residue.
+     *
+     * `value` is round-tripped through its stored JSON before being returned, so what a
+     * handler sees is identical whether the step just ran or was replayed from the memo.
+     */
+    step<T>(name: string, fn: () => T | Promise<T>, retry?: ExecutorRetryPolicy): Promise<T>;
+    /** Add to a counter. Committed with the pass; discarded if the pass fails. */
+    count(name: string, by?: number): void;
+    /**
+     * The scope, through the SYSTEM door — the same `getSystemScope` a declared
+     * schedule invokes through, so a job's writes are attributed `{ system: moduleId }`
+     * and gated by an ordinary `ctx.check` against `system:<moduleId>` grants. Opened
+     * on first call, then reused for the rest of the pass.
+     */
+    scope(): Promise<ScopeStub>;
+}
+/**
+ * A job's body: one pass, given where the last one stopped.
+ *
+ * HOST code, never module code — a walk of an external system holds credentials and
+ * makes network calls, which is exactly what module code may not do. It reaches the
+ * scope the way a schedule does, through `pass.scope()`.
+ */
+export type JobHandler = (pass: JobPassContext) => JobPassResult | void | Promise<JobPassResult | void>;
+/** What `runDueJobs` did in one call. */
+export interface JobDriveReport {
+    /** Runs this call picked up — due, and `running`. */
+    attempted: number;
+    /** Passes that COMMITTED with the run still going. With `maxPasses > 1`, more than one per run. */
+    advanced: number;
+    /** Runs that reported `done` this call. */
+    completed: number;
+    /** Passes that failed with retries left — the run stays `running`, due after its backoff. */
+    retrying: number;
+    /** Runs whose step exhausted its retries this call. Terminal: `failed`, with the error on the record. */
+    failed: number;
+    /** Per-run failures, the same shape `ScheduleRunReport.errors` has: what failed and why. */
+    errors: {
+        runId: string;
+        error: string;
+    }[];
+}
+/** The `_substrat_job_runs` row, as both adapters' SQL returns it. */
+export interface JobRunRow {
+    readonly id: string;
+    readonly module_id: string;
+    readonly job: string;
+    readonly instance: string;
+    readonly payload: string;
+    readonly status: string;
+    readonly cursor: string | null;
+    readonly counters: string;
+    readonly attempts: number;
+    readonly last_error: string | null;
+    readonly started_at: string;
+    readonly updated_at: string;
+    readonly next_attempt_at: string | null;
+    readonly ended_at: string | null;
+}
+/** The `_substrat_job_steps` row, as both adapters' SQL returns it. */
+export interface JobStepRow {
+    readonly step: string;
+    readonly result: string | null;
+    readonly attempts: number;
+    readonly last_error: string | null;
+}
+/** Everything a pass writes onto the run row, in one statement — never a partial update. */
+export interface JobRunPatch {
+    readonly status: JobRunStatus;
+    readonly cursor: string | null;
+    readonly counters: string;
+    readonly attempts: number;
+    readonly lastError: string | null;
+    readonly updatedAt: string;
+    readonly nextAttemptAt: string | null;
+    readonly endedAt: string | null;
+}
+/**
+ * The storage the driver runs against — the ONE thing each adapter supplies.
+ *
+ * D-14's two drivers are two implementations of this and nothing else: the pure
+ * adapter's is direct SQL on the scope db, the hosted adapter's is RPC to the scope
+ * DO. Every decision — what coalescing means, when a step is skipped, when a run
+ * fails — lives in the functions below, so the two drivers cannot disagree about
+ * any of it. What they may legitimately differ on is only how a row is read.
+ *
+ * **Each step commits on its own round trip**, and that is not an accident of the
+ * port's shape. Batching a pass's steps into one write at the end would lose exactly
+ * the work a mid-pass kill is supposed to keep.
+ */
+export interface JobRunStore {
+    /**
+     * The coalescing decision itself, as ONE operation: return the live (`running`)
+     * run for `row`'s key if there is one, otherwise insert `row` and return it.
+     *
+     * **Atomic, and it has to be.** Split into a lookup and an insert — which is how
+     * this was first written — two concurrent starts both see no live row and both
+     * insert, and the schema deliberately carries no constraint that could reject the
+     * second. The result is two runs walking one source: exactly what "a start against
+     * a live key joins it" promises not to happen, defeated by the promise's own
+     * mechanism. Nothing underneath made it safe: no unique index (by design), no
+     * transaction, and neither the pure host's actor queue nor a single DO RPC wrapped
+     * the pair.
+     *
+     * It is the port's job rather than the kernel's because atomicity is the one thing
+     * only the adapter can supply — a transaction on the pure side, a single RPC on the
+     * DO side, where the input gate makes one round trip indivisible.
+     */
+    startOrJoin(key: JobRunKey, row: JobRunRow): Promise<JobRunRow>;
+    /** One run by id, whatever its status. */
+    get(id: string): Promise<JobRunRow | null>;
+    /**
+     * `running` runs whose `next_attempt_at` has passed (or is NULL), oldest first,
+     * starting strictly after `afterId` when one is given.
+     *
+     * The cursor exists for starvation, not for paging convenience: the driver skips
+     * runs whose job this host does not register, and without a cursor those rows sit
+     * at the head of every batch forever, so a scope holding `limit` of them never
+     * drives anything newer. See `runDueJobRuns`.
+     */
+    due(now: string, limit: number, afterId?: string): Promise<JobRunRow[]>;
+    list(filter: JobRunFilter): Promise<JobRunRow[]>;
+    patch(id: string, patch: JobRunPatch): Promise<void>;
+    /**
+     * A COMMITTED pass: write the run's new state and drop its step ledger together,
+     * indivisibly.
+     *
+     * Two statements, one operation, for the reason `startOrJoin` is one: a stop
+     * between them leaves the advanced cursor beside the finished pass's memo rows,
+     * and the next pass — which is entitled to reuse a step name, since the
+     * determinism rule binds names to the payload and prior results, NOT to the
+     * cursor — reads that stale memo and skips work it never did. The first cut of
+     * this file ordered the two calls carefully and explained in a comment why the
+     * gap was harmless. The comment was wrong; only atomicity makes it true.
+     */
+    commitPass(id: string, patch: JobRunPatch): Promise<void>;
+    step(runId: string, name: string): Promise<JobStepRow | null>;
+    recordStep(runId: string, name: string, result: string | null, attempts: number, lastError: string | null, at: string): Promise<void>;
+}
+/** `conflict` reason: two `step()` calls under one name in one pass. */
+export declare const JOB_STEP_REUSED = "job_step_reused";
+/**
+ * Refuse anything that cannot survive a queue message, naming the path.
+ *
+ * What may be handed to a run, and handed forward by one, is **ids and
+ * configuration**: JSON's own values, nothing else. Bytes, class instances and
+ * functions are refused — and so, less obviously, are `undefined` in a nested
+ * position, a non-finite number and a cycle, because JSON turns each of those into
+ * something else without saying so. A payload silently reshaped on its way to
+ * storage is the failure this rule exists to prevent: the run resumes against a
+ * value that is not the one it was started with, and nothing anywhere reports it.
+ *
+ * `validation_failed` with the offending path in `errors`, exactly as an operation's
+ * own input failure arrives, so a transport renders it with no special case.
+ *
+ * Held against the payload at `start` and against the cursor at every commit —
+ * the two values that cross the boundary and land on the record. NOT held against a
+ * step's result, deliberately: that value is the handler's own, round-tripped to
+ * itself on resume, and the common shape of a step done for its effect is to return
+ * nothing at all — which this would refuse.
+ */
+export declare function assertQueueSafe(value: unknown, root: string): void;
+/**
+ * A row, decoded into the record an operator reads — TOLERANTLY, and saying so.
+ *
+ * The status, the attempts, the timestamps and the `last_error` are columns and
+ * always readable; only `payload`, `cursor` and `counters` are JSON, and a row whose
+ * JSON will not parse still has to be visible. It comes back with those three empty
+ * and `decodeError` naming the parse failure — never a bare `null` cursor, which a
+ * reader would take for "no pass has committed yet".
+ *
+ * This is deliberately NOT what the driver does with the same row: a pass cannot run
+ * on a payload it cannot decode, so `runJobPass` treats the parse failure as a failed
+ * pass and lets the run retry and then fail with the reason on its record. Strict
+ * where work happens, tolerant where evidence is read.
+ */
+export declare function jobRunOf(row: JobRunRow): JobRun;
+/**
+ * Start a run, or JOIN the one already in flight (#1577's first acceptance).
+ *
+ * The payload is refused here, before a row exists, so a run is never recorded
+ * carrying a value it cannot resume from.
+ *
+ * The join returns the LIVE run unchanged — its cursor, its counters, its start
+ * time. A second caller therefore learns the id of the walk that is already
+ * happening and can watch it, which is what "joins the first" has to mean for the
+ * caller to be able to do anything with the answer.
+ *
+ * **The lookup and the insert are ONE store operation** (`startOrJoin`), not two.
+ * As two, concurrent starts both find no live run and both insert — and there is no
+ * unique index to catch the second, deliberately, because a crashed run must stay
+ * restartable. The coalescing guarantee would then be false exactly when it is load
+ * bearing: two callers asking at once, which is the case it exists for.
+ */
+export declare function startJobRun(store: JobRunStore, input: StartJobRunInput, mintId: () => string, now: () => string): Promise<JobRunRow>;
+/** What one pass did, as the drive loop reads it. */
+export interface JobPassOutcome {
+    status: 'advanced' | 'completed' | 'retrying' | 'failed';
+    /** The error left on the record. Present exactly on `retrying` and `failed`. */
+    error?: string;
+}
+/**
+ * Run ONE pass of one run, and write what happened.
+ *
+ * The whole of the contract is here, which is why both adapters call it rather than
+ * porting it:
+ *
+ * - A committed pass writes the new cursor and counters, clears `attempts` and
+ *   `last_error`, and DROPS the step ledger — a new pass is new work.
+ * - A failed pass writes NOTHING the handler produced: the cursor and counters stay
+ *   where the last commit left them, so a partially-walked chunk is never mistaken
+ *   for a committed one. The step ledger SURVIVES, which is what stops the next pass
+ *   repeating the steps that did succeed.
+ * - A step at its `maxAttempts` fails the RUN: status `failed`, the step's error on
+ *   the record, `ended_at` stamped. It is reported, never thrown — a driver that
+ *   let one run's failure escape would take down every run behind it, which is the
+ *   failure `runDueSchedules` already refuses for schedules.
+ */
+export declare function runJobPass(options: {
+    store: JobRunStore;
+    run: JobRunRow;
+    handler: JobHandler;
+    /** The job's own retry policy — a step may narrow it, none may widen past its own. */
+    retry?: ExecutorRetryPolicy;
+    now: () => string;
+    /** Opens the system door for this run's module. Called at most once per pass. */
+    openScope: () => Promise<ScopeStub>;
+}): Promise<JobPassOutcome>;
+/**
+ * Advance every due run on one scope — the driver both adapters expose as
+ * `runDueJobs`.
+ *
+ * Bounded on both axes, because a maintenance tick has a budget: `limit` runs per
+ * call, `maxPasses` passes per run. A run that still has work left after its budget
+ * is simply left `running` and due, and the next call takes it — the same "reported
+ * rather than looped" shape the event drain's `incomplete` has. Default `maxPasses`
+ * is 1, so a caller gets one predictable unit of work unless it asks for more.
+ *
+ * **`limit` counts RUNNABLE runs, not rows read**, and that distinction is a fix
+ * rather than a nicety. Runs whose job this host does not register are skipped, and
+ * when the budget was applied to the query instead, a scope holding `limit` such rows
+ * at the head of the due order returned the same unrunnable batch on every call —
+ * nothing newer was ever reached, and the report said `attempted: 0` forever with no
+ * indication why. So the read pages past them, bounded by `JOB_DRIVE_SCAN_MAX` rows
+ * examined so one scope full of orphans cannot turn a tick into a table scan.
+ *
+ * The starvation was spotted while re-reading this file, judged unlikely and left
+ * alone — and then found independently by a reviewer. The judgement may even have
+ * been right; recording it only in the author's head was not, because a decision
+ * nobody can see is indistinguishable from an oversight. Hence the fix and hence
+ * this paragraph.
+ */
+export declare function runDueJobRuns(options: {
+    store: JobRunStore;
+    /** job name → its handler and policy, as `registerJob` recorded them. */
+    handlerFor: (run: JobRunRow) => {
+        handler: JobHandler;
+        retry?: ExecutorRetryPolicy;
+    } | undefined;
+    now: () => string;
+    openScope: (run: JobRunRow) => Promise<ScopeStub>;
+    maxPasses?: number;
+    limit?: number;
+}): Promise<JobDriveReport>;
+//# sourceMappingURL=job-run.d.ts.map

package/dist/job-run.d.ts.map

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