@sigrun/sigrun 0.0.0-stage → 0.1.1

package/dist/jobs/index.js

@@ -0,0 +1,228 @@
+/**
+ * Jobs Task 3 — the `JobsService`: the service surface over the three
+ * job record families (spec §8.3 + §8.4's service half; Task 4 owns the
+ * routes).
+ *
+ * ONE object per opened harness, constructed at boot and exposed as
+ * `OpenedHarness.jobs`. Every method is a thin composition over the
+ * Task-2 primitives (`writeJobChange`, `scanJobs`, `listRuns`,
+ * `listRevisions`, `patchJob`, `pruneHistory`) plus the Task-3
+ * reconciliation (`reconcileJobs` — every API write reconciles that one
+ * job) and `fireJob` (run-now).
+ *
+ * - `list`/`get`/`runs`/`revisions` READ records only — the job record
+ *   is the listing table; task records are never enumerated for
+ *   listing, and `runs`/`revisions` still answer for a RETIRED job
+ *   until retention trims them.
+ * - `createApi`/`updateApi`/`deleteApi`/`transfer` WRITE through
+ *   `writeJobChange` (version bump + revision, one commit); declared
+ *   ids (`file:`/`ext:`) throw {@link JobDeclaredError}.
+ * - `runNow` fires `fireJob` with the manual fire key.
+ * - `reconcile` delegates to {@link reconcileJobs} (boot's post-resume
+ *   call and the ownership participant's follow-up).
+ *
+ * `access` on the wire rows is NOT computed here — the route derives it
+ * per principal (§5.9 `accessOf`); the service serves raw rows.
+ */
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { JobDoc, listRevisions, listRuns, pruneHistory, readJob, scanJobs, writeJobChange, } from "./docs.js";
+import { fireJob } from "./fire.js";
+import { reconcileJobs, } from "./reconcile.js";
+import { specHash } from "./spec.js";
+/** Thrown when an API write targets a `file:`/`ext:` job id (409 `job_declared`). */
+export class JobDeclaredError extends Error {
+    constructor(id) {
+        super(`job ${id} is declared by its source — edit the source instead`);
+        this.name = "JobDeclaredError";
+    }
+}
+/** Thrown when an API write targets a missing job. */
+export class JobNotFoundError extends Error {
+    constructor(id) {
+        super(`job ${id} does not exist`);
+        this.name = "JobNotFoundError";
+    }
+}
+/** The live `jobHistory` limits (spec §8.1, ruling 14 — read per call). */
+function historyLimits(settings) {
+    const jobHistory = settings().jobHistory;
+    return {
+        runs: jobHistory?.runs ?? 50,
+        revisions: jobHistory?.revisions ?? 50,
+    };
+}
+/** The wire row of a record (access left for the caller: the ROUTE
+ *  computes it per principal; the raw row carries the neutral default).
+ *  Exported for boot's `job.changed` publication (W4 Task 4). */
+export function jobWireOf(id, record) {
+    return {
+        id,
+        name: record.spec.name,
+        source: record.source,
+        ...(record.owner === undefined ? {} : { owner: record.owner }),
+        ...(record.sharing === undefined
+            ? {}
+            : { sharing: JSON.parse(JSON.stringify(record.sharing)) }),
+        schedule: record.spec.schedule,
+        action: record.spec.action,
+        enabled: record.enabled,
+        state: record.state,
+        ...(record.reason === undefined ? {} : { reason: record.reason }),
+        version: record.version,
+        ...(record.nextRun === undefined ? {} : { nextRun: record.nextRun }),
+        ...(record.lastRun === undefined
+            ? {}
+            : { lastRun: record.lastRun }),
+        // The route computes access per principal; the service's raw row
+        // carries the neutral default.
+        access: "write",
+    };
+}
+/** Create the service (boot constructs exactly one per opened harness). */
+export function createJobsService(deps) {
+    const ctx = BACKGROUND_CONTEXT;
+    const limits = () => historyLimits(deps.settings);
+    // `job.changed` observation (W4 Task 4): ONE commit subscription over
+    // the `sigrun.job` family invokes the injected hook after EVERY record
+    // change — the service's own API writes, the executor's status patches
+    // (task.ts), the run-settle observers, the ownership transfer, and
+    // reconciliation's declared upserts/retires all land through
+    // `harness.commit` on this doc family, so no call-site threading can
+    // miss a path. Per-call-site hooks would double-publish against this;
+    // the subscription is the only publish trigger.
+    if (deps.onChange !== undefined) {
+        const onChange = deps.onChange;
+        deps.harness.subscribeCommits((publication) => {
+            const seen = new Set();
+            for (const change of publication.changes) {
+                if (change.type !== "document")
+                    continue;
+                if (change.record.kind !== JobDoc.definition.kind)
+                    continue;
+                const jobId = change.record.key;
+                if (jobId === undefined || seen.has(jobId))
+                    continue;
+                seen.add(jobId);
+                onChange(jobId);
+            }
+        });
+    }
+    /** Reconcile that one job's executor after a write. */
+    const reconcileOne = async () => await reconcileJobs({
+        harness: deps.harness,
+        storage: deps.storage,
+        runtime: deps.runtime,
+        rootId: deps.rootId,
+        sources: deps.sources,
+    }, ctx);
+    return {
+        async list() {
+            const records = await scanJobs(deps.storage, ctx);
+            return records.map(({ id, record }) => jobWireOf(id, record));
+        },
+        async get(id) {
+            const record = await readJob(deps.harness, id, ctx);
+            return record === undefined ? undefined : jobWireOf(id, record);
+        },
+        async createApi(spec, owner) {
+            const id = `api:${crypto.randomUUID()}`;
+            const hash = specHash(id, spec);
+            const nowIso = new Date(deps.runtime.now()).toISOString();
+            await deps.harness.commit(async (tx) => {
+                await writeJobChange(tx, id, {
+                    source: "api",
+                    spec: JSON.parse(JSON.stringify(spec)),
+                    // The record's owner is the SERVER-STAMPED creator (the
+                    // route passes principal.user; a body-carried spec.owner
+                    // never reaches here — the route strips it, §5.9). The
+                    // record's sharing mirrors spec.sharing exactly like a
+                    // declared record (the PATCH share surface).
+                    ...(owner === undefined ? {} : { owner }),
+                    ...(spec.sharing === undefined ? {} : { sharing: spec.sharing }),
+                    enabled: spec.enabled ?? true,
+                    createdAt: nowIso,
+                    hash,
+                    state: "waiting",
+                }, owner ?? "api", nowIso);
+            }, ctx);
+            await pruneHistory(deps.storage, deps.harness, id, limits(), ctx);
+            await reconcileOne();
+            const record = await readJob(deps.harness, id, ctx);
+            if (record === undefined)
+                throw new JobNotFoundError(id);
+            return jobWireOf(id, record);
+        },
+        async updateApi(id, patch, changedBy) {
+            const prior = await readJob(deps.harness, id, ctx);
+            if (prior === undefined)
+                throw new JobNotFoundError(id);
+            if (prior.source !== "api")
+                throw new JobDeclaredError(id);
+            const spec = {
+                ...prior.spec,
+                ...patch,
+            };
+            const enabled = patch.enabled ?? prior.enabled;
+            const hash = specHash(id, spec);
+            const nowIso = new Date(deps.runtime.now()).toISOString();
+            await deps.harness.commit(async (tx) => {
+                await writeJobChange(tx, id, {
+                    source: "api",
+                    spec: JSON.parse(JSON.stringify(spec)),
+                    // The record's owner is preserved (the transfer path and
+                    // the create stamp own it; a PATCH body carrying `owner` is
+                    // rejected at the route, §5.9's server-stamped posture),
+                    // while sharing mirrors the MERGED spec's sharing — the
+                    // PATCH share surface (a patch without `sharing` keeps the
+                    // prior share through the spread merge).
+                    ...(prior.owner === undefined ? {} : { owner: prior.owner }),
+                    ...(spec.sharing === undefined ? {} : { sharing: spec.sharing }),
+                    enabled,
+                    createdAt: prior.createdAt,
+                    hash,
+                    // Status fields the caller omitted are preserved
+                    // by writeJobChange's draft-merge; state resets to
+                    // waiting so a re-enable's executor re-derives it.
+                    state: enabled ? "waiting" : "disabled",
+                }, changedBy, nowIso);
+            }, ctx);
+            await pruneHistory(deps.storage, deps.harness, id, limits(), ctx);
+            await reconcileOne();
+            const record = await readJob(deps.harness, id, ctx);
+            if (record === undefined)
+                throw new JobNotFoundError(id);
+            return jobWireOf(id, record);
+        },
+        async runs(id, limit) {
+            return await listRuns(deps.storage, id, Math.max(0, limit), ctx);
+        },
+        async revisions(id) {
+            return await listRevisions(deps.storage, id, ctx);
+        },
+        async deleteApi(id, changedBy) {
+            const prior = await readJob(deps.harness, id, ctx);
+            if (prior === undefined)
+                throw new JobNotFoundError(id);
+            if (prior.source !== "api")
+                throw new JobDeclaredError(id);
+            const nowIso = new Date(deps.runtime.now()).toISOString();
+            await deps.harness.commit(async (tx) => {
+                // The final `enabled:false` revision, then the retire.
+                await writeJobChange(tx, id, { ...prior, enabled: false }, changedBy, nowIso);
+                await tx.retireDoc(JobDoc, id);
+            }, ctx);
+            await reconcileOne();
+        },
+        async runNow(id) {
+            // ONE clock reading: the manual fire key and the run's fireAt must
+            // agree — the settle path re-derives the run-record key from
+            // fireAt, and two readings would write the settle under a
+            // different key than the fire stored the run under.
+            const now = deps.runtime.now();
+            const fireKey = `${id}:manual:${now}`;
+            return await fireJob(deps.runtime, id, fireKey, now, ctx);
+        },
+        reconcile: reconcileOne,
+    };
+}
+export { reconcileJobs } from "./reconcile.js";

package/dist/jobs/observe.js

@@ -0,0 +1,165 @@
+/**
+ * Jobs Task 3 (spec §8.1 "Run status"): the two run-settle observers.
+ *
+ * - **The `runSettled` handler** (registered on the event bus as
+ *   `sigrun:jobs`): a settled run whose conversation's `SessionMeta`
+ *   carries a `jobId` settles the job's RUNNING run record matching that
+ *   `conversationId` — `succeeded` (answered) or `failed` (unanswered,
+ *   `error: reason`) + `settledAt` — refreshes the job record's
+ *   `lastRun` copy, then prunes history. It sees ONLY prompt runs (the
+ *   bus derives settled runs from `submission` writes).
+ * - **The `taskSettled` listener** (the host-event reduction the bus
+ *   emits from terminal `task` table writes): settles `task`-action run
+ *   records whose `taskId` matches — `completed` → `succeeded`, any
+ *   other terminal → `failed` + the error text — then the same
+ *   lastRun/prune refresh.
+ *
+ * Both are idempotent by construction: they settle only a run whose
+ * outcome is still `running`, so a re-delivery (the bus's at-least-once
+ * posture) is a no-op. Failures are caught and logged — an observer must
+ * never break the run or the drain loop.
+ */
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { SessionMetaDoc } from "../server/session-meta.js";
+import { JobDoc, JobRunDoc, listRuns, patchJob, pruneHistory, scanJobs } from "./docs.js";
+/** The `sigrun.job.run` key a run record was written under. */
+function runKeyOf(run) {
+    if (run.manual) {
+        return `${run.jobId}:manual:${Date.parse(run.startedAt)}`;
+    }
+    return `${run.jobId}:${Date.parse(run.fireAt)}`;
+}
+/** The retention limits read live per prune (§8.1 ruling 14). */
+function limitsOf(settings) {
+    const jobHistory = settings().jobHistory;
+    return {
+        runs: jobHistory?.runs ?? 50,
+        revisions: jobHistory?.revisions ?? 50,
+    };
+}
+/** Settle one run record + the job's lastRun copy + prune. */
+async function settleRun(deps, run, settled, ctx) {
+    await deps.harness.commit(async (tx) => {
+        // The seed only applies when the doc is absent (it never is — the
+        // fire created it); mutate the LIVE draft instead. Carried field by
+        // field so a concurrent writer's fields cannot be lost wholesale.
+        // SAFETY: the draft is the JsonObject-backed JobRunWire draft —
+        // pi-durable's Draft<T> tracks mutations on the same object, so the
+        // Object.assign lands in the tracked doc, not a copy.
+        const draft = await tx.doc(JobRunDoc, runKeyOf(run), settled);
+        Object.assign(draft, settled);
+    }, ctx);
+    await patchJob(deps.harness, run.jobId, (draft) => {
+        draft.lastRun = settled;
+    }, ctx);
+    await pruneHistory(deps.storage, deps.harness, run.jobId, limitsOf(deps.settings), ctx);
+}
+/**
+ * Register both observers (boot calls this after the bus opens, before
+ * `resume()` — recovery settles are observed). Returns the unsubscribe.
+ */
+export function registerJobObservers(deps) {
+    const ctx = BACKGROUND_CONTEXT;
+    const nowIso = () => new Date(deps.runtime.now()).toISOString();
+    // The runSettled handler (prompt runs): registered as `sigrun:jobs`,
+    // install order = run order (after every loaded extension, like the
+    // auto-namer — a job observation never delays an extension's).
+    const runSettled = async (event) => {
+        try {
+            const meta = await deps.harness.snapshot(SessionMetaDoc, event.conversationId, ctx);
+            const jobId = meta?.jobId;
+            if (typeof jobId !== "string")
+                return;
+            const runs = await listRuns(deps.storage, jobId, Number.MAX_SAFE_INTEGER, ctx);
+            const run = runs.find((one) => one.outcome === "running" &&
+                // SAFETY: ConversationId is the branded number the run record's
+                // plain `conversationId` field carries; compared across both forms.
+                one.conversationId === event.conversationId);
+            if (run === undefined)
+                return;
+            const answered = event.outcome.status === "answered";
+            const settled = {
+                ...run,
+                outcome: answered ? "succeeded" : "failed",
+                settledAt: nowIso(),
+                ...(answered || event.outcome.status !== "unanswered"
+                    ? {}
+                    : { error: event.outcome.reason }),
+            };
+            await settleRun(deps, run, settled, ctx);
+        }
+        catch (error) {
+            console.error("jobs: runSettled observer failed:", error);
+        }
+    };
+    const unregister = deps.eventBus.registerExtension("sigrun:jobs", {
+        runSettled,
+    });
+    // The taskSettled listener (task runs): the host-event reduction the
+    // bus emits synchronously from terminal task-table writes. The settle
+    // work runs on a microtask side lane (the listener contract is
+    // no-blocking-work); each settle is idempotent, so ordering with the
+    // drain loop's deliveries does not matter.
+    //
+    // LOAD GUARD: tool-call tasks (every bash/read/write a conversation
+    // runs) also produce terminal task writes — a jobs-harnessing scan per
+    // terminal task would tax every busy conversation. The listener first
+    // checks `jobsMayExist`, a conservative flag: false only until the
+    // first `sigrun.job` document write is observed (the commit
+    // subscription below — job records appear ONLY through writes), and
+    // never reset afterwards (retirement is not a return to no-jobs for
+    // this process). A no-jobs harness pays ONE boolean check per terminal
+    // task, never a scan.
+    let jobsMayExist = false;
+    const offJobWrites = deps.harness.subscribeCommits((publication) => {
+        for (const change of publication.changes) {
+            if (change.type !== "document")
+                continue;
+            if (change.record.kind === JobDoc.definition.kind) {
+                jobsMayExist = true;
+                return;
+            }
+        }
+    });
+    const offTaskSettled = deps.eventBus.onHostEvent((event) => {
+        if (event.type !== "taskSettled")
+            return;
+        if (!jobsMayExist)
+            return;
+        const { taskId, status, error } = event;
+        void (async () => {
+            try {
+                // The run records' jobId is unknown here (the event carries
+                // only the task id) — scan every live job's running runs and
+                // match by taskId. Household scale: one scan over the runs of
+                // jobs whose action is `task` would need the record read per
+                // job; the scan below walks ALL live job records once, then
+                // each one's runs (the same shape reconcile's pass-2 uses).
+                const jobs = await scanJobs(deps.storage, ctx);
+                for (const { id } of jobs) {
+                    const runs = await listRuns(deps.storage, id, Number.MAX_SAFE_INTEGER, ctx);
+                    const run = runs.find((one) => one.outcome === "running" && one.taskId === taskId);
+                    if (run === undefined)
+                        continue;
+                    const succeeded = status === "completed";
+                    const settled = {
+                        ...run,
+                        outcome: succeeded ? "succeeded" : "failed",
+                        settledAt: nowIso(),
+                        ...(succeeded || error === undefined ? {} : { error }),
+                    };
+                    await settleRun(deps, run, settled, ctx);
+                    return;
+                }
+            }
+            catch (error) {
+                console.error("jobs: taskSettled observer failed:", error);
+            }
+        })();
+    });
+    return () => {
+        unregister();
+        offTaskSettled();
+        offJobWrites();
+    };
+}

package/dist/jobs/reconcile.js

@@ -0,0 +1,245 @@
+/**
+ * Jobs Task 3 (spec §8.3 "Records → tasks"): reconciliation — the ONE
+ * function that maps job RECORDS onto schedule-task EXECUTORS.
+ *
+ * Two passes, in order:
+ *
+ * 1. **Declared → records.** Every file (settings.json `jobs[]`) and
+ *    extension (factory-result `jobs[]`) declaration upserts its record
+ *    through `writeJobChange` — `changedBy` = `"file"` /
+ *    `"extension:<slug>"`, so a change bumps `version` and writes a
+ *    revision; an UNCHANGED declaration (same source, spec, owner,
+ *    sharing, enabled, hash) writes nothing. Records whose declaration
+ *    vanished are RETIRED (a final `enabled:false` revision rides the
+ *    same commit). `api` records are never touched here — the API owns
+ *    them.
+ *
+ * 2. **Records → tasks.** Live tasks come from
+ *    `storage.scanTasks({kind: "sigrun.schedule"})`, paged, filtered
+ *    in-memory to non-terminal — used ONLY to match executors, never
+ *    for listing (the job record is the listing table). For every
+ *    record:
+ *    - enabled with no live task of the matching `hash` → abort any
+ *      live task for that `jobId`, then create one (a single
+ *      `harness.commit` carrying `tx.createTask`, conversation-owned on
+ *      the ROOT conversation, `background: true`);
+ *    - a live task whose record is retired, disabled, or hash-mismatched
+ *      → `harness.abortTask` (the task's own stale-executor rule then
+ *      settles it honestly);
+ *    - disabled records get `state: "disabled"`.
+ *
+ * Boot calls `reconcile` immediately before `resume()` (the scheduler
+ * starts executors at resume, the next line — awaiting anything after
+ * resume would race post-boot registry installs against recovered agent
+ * resolution); every API write calls it for
+ * one job. It is IDEMPOTENT — a second run with unchanged state creates
+ * nothing, aborts nothing, writes nothing.
+ */
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { JobDoc, patchJob, scanJobs, writeJobChange, } from "./docs.js";
+import { nextFireAt } from "./schedule.js";
+import { specHash } from "./spec.js";
+import { createScheduleTask } from "./task.js";
+const SCAN_PAGE = 500;
+/** The file id of a declared name. */
+export function fileJobId(name) {
+    return `file:${name}`;
+}
+/** The extension id of a declared name. */
+export function extensionJobId(slug, name) {
+    return `ext:${slug}:${name}`;
+}
+/** Every non-terminal schedule task, keyed by jobId. */
+export async function liveScheduleTasksByJob(storage, ctx) {
+    const byJob = new Map();
+    let cursor;
+    for (;;) {
+        const page = await storage.scanTasks({ kind: "sigrun.schedule" }, SCAN_PAGE, cursor, ctx);
+        for (const record of page.items) {
+            if (record.state.status === "terminal" ||
+                record.state.status === "completing") {
+                continue;
+            }
+            // An abort-marked task is not a live executor: `abortTask`
+            // returns "marked" and completes asynchronously, so a pending
+            // abort must not count as the job's executor (reconcile would
+            // skip creating the replacement, or re-abort a settling task).
+            if (record.abortRequested === true)
+                continue;
+            const jobId = record.input.jobId;
+            if (typeof jobId !== "string")
+                continue;
+            const list = byJob.get(jobId) ?? [];
+            list.push(record);
+            byJob.set(jobId, list);
+        }
+        if (page.next === undefined)
+            return byJob;
+        cursor = page.next;
+    }
+}
+/** The record a declaration reconciles to (omitted status fields preserved). */
+function declaredRecord(id, spec, hash, nowIso) {
+    return {
+        source: id.startsWith("ext:") ? "extension" : "file",
+        spec,
+        ...(spec.owner === undefined ? {} : { owner: spec.owner }),
+        ...(spec.sharing === undefined ? {} : { sharing: spec.sharing }),
+        enabled: spec.enabled ?? true,
+        createdAt: nowIso,
+        hash,
+        state: "waiting",
+    };
+}
+/** Whether a record already mirrors a declaration exactly (no write). */
+function mirrorsDeclaration(record, id, spec, hash) {
+    return (record.hash === hash &&
+        record.source === (id.startsWith("ext:") ? "extension" : "file") &&
+        record.spec.name === spec.name &&
+        JSON.stringify(record.spec) === JSON.stringify(spec) &&
+        record.enabled === (spec.enabled ?? true) &&
+        record.owner === spec.owner &&
+        (record.sharing === undefined) === (spec.sharing === undefined) &&
+        (record.sharing === undefined ||
+            JSON.stringify(record.sharing) === JSON.stringify(spec.sharing)));
+}
+/**
+ * Reconcile every source into records, then every record into tasks.
+ * See the module doc for the pass order and semantics.
+ */
+export async function reconcileJobs(deps, ctx = BACKGROUND_CONTEXT) {
+    const nowIso = new Date(deps.runtime.now()).toISOString();
+    // ── Pass 1: declared → records ───────────────────────────────────
+    const declared = [
+        ...deps.sources().file.map((spec) => ({
+            id: fileJobId(spec.name),
+            spec,
+            declaredBy: "file",
+        })),
+        ...deps.sources().extensions.flatMap(({ extension, jobs }) => jobs.map((spec) => ({
+            id: extensionJobId(extension, spec.name),
+            spec,
+            declaredBy: `extension:${extension}`,
+        }))),
+    ];
+    const declaredIds = new Set(declared.map((job) => job.id));
+    const records = new Map();
+    for (const { id, record } of await scanRecords(deps.storage, ctx)) {
+        records.set(id, record);
+    }
+    for (const job of declared) {
+        const hash = specHash(job.id, job.spec);
+        const prior = records.get(job.id);
+        if (prior === undefined) {
+            await deps.harness.commit(async (tx) => {
+                await writeJobChange(tx, job.id, declaredRecord(job.id, job.spec, hash, nowIso), job.declaredBy, nowIso);
+            }, ctx);
+            continue;
+        }
+        if (mirrorsDeclaration(prior, job.id, job.spec, hash))
+            continue;
+        // A changed declaration (or a re-appeared retired record):
+        // writeJobChange carries `next` over the draft, preserving the
+        // status fields (state/reason/nextRun/lastRun) the declaration
+        // does not own — "lastRun is preserved".
+        await deps.harness.commit(async (tx) => {
+            await writeJobChange(tx, job.id, declaredRecord(job.id, job.spec, hash, nowIso), job.declaredBy, nowIso);
+        }, ctx);
+    }
+    // Retire declared-source records whose declaration is gone.
+    for (const [id, record] of records) {
+        if (record.source === "api")
+            continue;
+        if (declaredIds.has(id))
+            continue;
+        await retireRecord(deps.harness, id, record, nowIso, ctx);
+    }
+    // ── Pass 2: records → tasks ─────────────────────────────────────
+    const after = new Map();
+    for (const { id, record } of await scanRecords(deps.storage, ctx)) {
+        after.set(id, record);
+    }
+    const liveByJob = await liveScheduleTasksByJob(deps.storage, ctx);
+    // Retired ids first: a record retired this pass (or on an earlier
+    // boot/crash) no longer appears in `after`, so its live executor — if
+    // any survived — must be aborted here, keyed on the live-task scan.
+    for (const [id, tasks] of liveByJob) {
+        if (after.has(id))
+            continue;
+        for (const task of tasks) {
+            await deps.harness.abortTask(task.id, ctx);
+        }
+    }
+    for (const [id, record] of after) {
+        const live = liveByJob.get(id) ?? [];
+        const matching = live.filter((task) => task.input.hash === record.hash);
+        if (record.enabled) {
+            if (matching.length === 0) {
+                for (const task of live) {
+                    await deps.harness.abortTask(task.id, ctx);
+                }
+                await createExecutor(deps, id, record, ctx);
+            }
+            // A matching live task exists: leave it (the same task id
+            // survives an unchanged reboot). Extra stale live tasks for
+            // the same id are still pruned.
+            for (const task of live) {
+                if (task.input.hash !== record.hash) {
+                    await deps.harness.abortTask(task.id, ctx);
+                }
+            }
+        }
+        else {
+            for (const task of live) {
+                await deps.harness.abortTask(task.id, ctx);
+            }
+            if (record.state !== "disabled") {
+                await patchRecord(deps.harness, id, (draft) => {
+                    draft.state = "disabled";
+                }, ctx);
+            }
+        }
+    }
+}
+/** All live job records (the records-only scan). */
+async function scanRecords(storage, ctx) {
+    // scanJobs already pages + reads current values.
+    return scanJobs(storage, ctx);
+}
+/** Retire one declared-source record with a final `enabled:false` revision. */
+async function retireRecord(harness, id, record, nowIso, ctx) {
+    if (!record.enabled) {
+        // Already disabled (a prior delete-style revision exists): just
+        // retire the record.
+        await harness.commit(async (tx) => {
+            await tx.retireDoc(JobDoc, id);
+        }, ctx);
+        return;
+    }
+    await harness.commit(async (tx) => {
+        await writeJobChange(tx, id, {
+            ...record,
+            enabled: false,
+        }, "retire", nowIso);
+        await tx.retireDoc(JobDoc, id);
+    }, ctx);
+}
+/** One small status edit (state/reason) — no version bump. */
+async function patchRecord(harness, id, change, ctx) {
+    await patchJob(harness, id, change, ctx);
+}
+/** Create the schedule task for one enabled record (ONE commit). */
+async function createExecutor(deps, id, record, ctx) {
+    const firstAt = nextFireAt(record.spec.schedule, deps.runtime.now(), deps.runtime.defaultTz);
+    await deps.harness.commit(async (tx) => {
+        await tx.createTask(createScheduleTask(deps.runtime), {
+            jobId: id,
+            hash: record.hash,
+            ...(firstAt === undefined ? {} : { firstAt }),
+        }, {
+            ownership: { kind: "conversation" },
+            conversationId: deps.rootId,
+            background: true,
+        });
+    }, ctx);
+}