intentdna 1.8.6 → 1.8.7

package/dist/runtime/run-store.js

@@ -0,0 +1,725 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, open, readFile, readdir, rename, rm, stat, utimes, } from "node:fs/promises";
+import { dirname, join } from "node:path";
+export const RUN_STORE_SCHEMA_VERSION = 1;
+export const RUN_STATUS_VALUES = [
+    "active",
+    "cancelling",
+    "succeeded",
+    "failed",
+    "cancelled",
+];
+export class RunStoreError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "RunStoreError";
+        this.code = code;
+    }
+}
+const DEFAULT_LOCK_WAIT_MS = 5_000;
+const DEFAULT_LOCK_STALE_MS = 5 * 60_000;
+const DEFAULT_LOCK_RETRY_MS = 25;
+const LEDGER_FILE_NAME = "ledger.json";
+const LOCK_OWNER_FILE_NAME = "owner";
+const LOCK_LEASE_FILE_NAME = "lease";
+const DIRECTORY_MODE = 0o700;
+const FILE_MODE = 0o600;
+function assertPositiveInteger(name, value) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new RunStoreError("invalid_options", `${name} must be a positive safe integer`);
+    }
+}
+function resolveOptions(options) {
+    if (!options.root_directory.trim()) {
+        throw new RunStoreError("invalid_options", "root_directory must not be empty");
+    }
+    const lockStaleMs = options.lock_stale_ms ?? DEFAULT_LOCK_STALE_MS;
+    const lockHeartbeatMs = options.lock_heartbeat_ms ?? Math.max(1, Math.floor(lockStaleMs / 3));
+    const resolved = {
+        root_directory: options.root_directory,
+        lock_wait_ms: options.lock_wait_ms ?? DEFAULT_LOCK_WAIT_MS,
+        lock_stale_ms: lockStaleMs,
+        lock_retry_ms: options.lock_retry_ms ?? DEFAULT_LOCK_RETRY_MS,
+        lock_heartbeat_ms: lockHeartbeatMs,
+    };
+    assertPositiveInteger("lock_wait_ms", resolved.lock_wait_ms);
+    assertPositiveInteger("lock_stale_ms", resolved.lock_stale_ms);
+    assertPositiveInteger("lock_retry_ms", resolved.lock_retry_ms);
+    assertPositiveInteger("lock_heartbeat_ms", resolved.lock_heartbeat_ms);
+    if (resolved.lock_heartbeat_ms >= resolved.lock_stale_ms) {
+        throw new RunStoreError("invalid_options", "lock_heartbeat_ms must be less than lock_stale_ms");
+    }
+    return resolved;
+}
+function runStorageKey(runId) {
+    return createHash("sha256").update(runId, "utf8").digest("hex");
+}
+function isErrno(error, code) {
+    return (error instanceof Error &&
+        "code" in error &&
+        error.code === code);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function stableJson(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(stableJson).join(",")}]`;
+    }
+    if (value !== null && typeof value === "object") {
+        const entries = Object.entries(value)
+            .filter(([, entry]) => entry !== undefined)
+            .sort(([left], [right]) => left.localeCompare(right));
+        return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${stableJson(entry)}`).join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+function recordsEqual(left, right) {
+    return stableJson(left) === stableJson(right);
+}
+function assertString(value, label) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new RunStoreError("invalid_record", `${label} must be a non-empty string`);
+    }
+}
+function assertRunRecord(record, expectedRunId) {
+    assertString(record.run_id, "run.run_id");
+    assertString(record.workflow_id, "run.workflow_id");
+    assertString(record.plan_digest, "run.plan_digest");
+    assertString(record.created_at, "run.created_at");
+    assertString(record.updated_at, "run.updated_at");
+    if (expectedRunId !== undefined && record.run_id !== expectedRunId) {
+        throw new RunStoreError("identity_conflict", `run record ${record.run_id} does not match ${expectedRunId}`);
+    }
+    if (!RUN_STATUS_VALUES.includes(record.status)) {
+        throw new RunStoreError("invalid_record", `unsupported run status: ${String(record.status)}`);
+    }
+    if (record.status === "active" && record.terminal !== null) {
+        throw new RunStoreError("invalid_record", "an active run cannot contain a terminal record");
+    }
+    if (["succeeded", "failed", "cancelled"].includes(record.status) &&
+        record.terminal === null) {
+        throw new RunStoreError("invalid_record", `terminal run status ${record.status} requires a terminal record`);
+    }
+    if (record.terminal !== null &&
+        (record.status !== record.terminal.status ||
+            !["succeeded", "failed", "cancelled"].includes(record.status))) {
+        throw new RunStoreError("invalid_record", "run status and terminal status must agree");
+    }
+}
+function assertCorrelatedRunId(actual, expected, label) {
+    if (actual !== expected) {
+        throw new RunStoreError("identity_conflict", `${label} belongs to run ${actual}, expected ${expected}`);
+    }
+}
+function assertSnapshot(value, expectedRunId) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new RunStoreError("invalid_record", "run ledger must be a JSON object");
+    }
+    const candidate = value;
+    if (candidate.schema_version !== RUN_STORE_SCHEMA_VERSION) {
+        throw new RunStoreError("unsupported_schema", `unsupported run-store schema version: ${String(candidate.schema_version)}`);
+    }
+    if (!Number.isSafeInteger(candidate.record_version) ||
+        (candidate.record_version ?? 0) < 1) {
+        throw new RunStoreError("invalid_record", "record_version must be a positive safe integer");
+    }
+    if (!candidate.run ||
+        !Array.isArray(candidate.tasks) ||
+        !Array.isArray(candidate.attempts) ||
+        !Array.isArray(candidate.claims) ||
+        !Array.isArray(candidate.events) ||
+        !Array.isArray(candidate.results)) {
+        throw new RunStoreError("invalid_record", "run ledger is missing a required record collection");
+    }
+    assertString(candidate.created_at, "ledger.created_at");
+    assertString(candidate.updated_at, "ledger.updated_at");
+    assertRunRecord(candidate.run, expectedRunId);
+    validateCollections(candidate);
+    return candidate;
+}
+function validateCollections(snapshot) {
+    const runId = snapshot.run.run_id;
+    const taskByStep = new Map();
+    for (const task of snapshot.tasks) {
+        assertCorrelatedRunId(task.run_id, runId, "task");
+        if (taskByStep.has(task.step_id)) {
+            throw new RunStoreError("identity_conflict", `duplicate task for step ${task.step_id}`);
+        }
+        taskByStep.set(task.step_id, task);
+    }
+    const attemptById = new Map();
+    const attemptByWorker = new Map();
+    for (const attempt of snapshot.attempts) {
+        assertCorrelatedRunId(attempt.run_id, runId, "attempt");
+        if (attempt.process_id !== undefined
+            && attempt.process_id !== null
+            && (!Number.isSafeInteger(attempt.process_id)
+                || attempt.process_id <= 0)) {
+            throw new RunStoreError("invalid_record", `attempt ${attempt.attempt_id} has an invalid process_id`);
+        }
+        if (attemptById.has(attempt.attempt_id)) {
+            throw new RunStoreError("identity_conflict", `duplicate attempt ${attempt.attempt_id}`);
+        }
+        if (attemptByWorker.has(attempt.worker_session_id)) {
+            throw new RunStoreError("identity_conflict", `worker session ${attempt.worker_session_id} is bound to multiple attempts`);
+        }
+        if (!taskByStep.has(attempt.step_id)) {
+            throw new RunStoreError("invalid_record", `attempt ${attempt.attempt_id} has no task`);
+        }
+        attemptById.set(attempt.attempt_id, attempt);
+        attemptByWorker.set(attempt.worker_session_id, attempt);
+    }
+    const claims = new Set();
+    for (const claim of snapshot.claims) {
+        assertCorrelatedRunId(claim.run_id, runId, "claim");
+        if (claims.has(claim.claim_token)) {
+            throw new RunStoreError("identity_conflict", `duplicate claim token ${claim.claim_token}`);
+        }
+        const attempt = attemptById.get(claim.attempt_id);
+        if (!attempt ||
+            attempt.step_id !== claim.step_id ||
+            attempt.worker_session_id !== claim.worker_session_id) {
+            throw new RunStoreError("invalid_record", `claim ${claim.claim_token} does not match its attempt`);
+        }
+        claims.add(claim.claim_token);
+    }
+    const eventIds = new Set();
+    const eventKeys = new Set();
+    let previousSequence = 0;
+    for (const event of snapshot.events) {
+        assertCorrelatedRunId(event.run_id, runId, "event");
+        if (eventIds.has(event.event_id) || eventKeys.has(event.idempotency_key)) {
+            throw new RunStoreError("event_conflict", `duplicate stored event ${event.event_id}`);
+        }
+        if (!Number.isSafeInteger(event.sequence) ||
+            event.sequence !== previousSequence + 1) {
+            throw new RunStoreError("invalid_record", `event ${event.event_id} has non-contiguous sequence ${event.sequence}`);
+        }
+        eventIds.add(event.event_id);
+        eventKeys.add(event.idempotency_key);
+        previousSequence = event.sequence;
+    }
+    const results = new Set();
+    const resultById = new Map();
+    const resultByAttempt = new Map();
+    for (const result of snapshot.results) {
+        assertCorrelatedRunId(result.run_id, runId, "result");
+        if (results.has(result.result_id)) {
+            throw new RunStoreError("result_conflict", `duplicate committed result ${result.result_id}`);
+        }
+        const attempt = attemptById.get(result.attempt_id);
+        if (!attempt ||
+            attempt.phase !== "terminal" ||
+            attempt.step_id !== result.step_id ||
+            attempt.worker_session_id !== result.worker_session_id) {
+            throw new RunStoreError("invalid_record", `result ${result.result_id} does not match a terminal attempt`);
+        }
+        if (resultByAttempt.has(result.attempt_id)) {
+            throw new RunStoreError("result_conflict", `attempt ${result.attempt_id} has multiple committed results`);
+        }
+        results.add(result.result_id);
+        resultById.set(result.result_id, result);
+        resultByAttempt.set(result.attempt_id, result);
+    }
+    for (const task of snapshot.tasks) {
+        if (task.current_attempt_id !== null &&
+            attemptById.get(task.current_attempt_id)?.step_id !== task.step_id) {
+            throw new RunStoreError("invalid_record", `task ${task.step_id} references an unknown current attempt`);
+        }
+        if (task.committed_result_id !== null &&
+            resultById.get(task.committed_result_id)?.step_id !== task.step_id) {
+            throw new RunStoreError("invalid_record", `task ${task.step_id} references an unknown committed result`);
+        }
+    }
+}
+function eventReplayEquivalent(existing, incoming) {
+    return recordsEqual({
+        run_id: existing.run_id,
+        step_id: existing.step_id,
+        attempt_id: existing.attempt_id,
+        worker_session_id: existing.worker_session_id,
+        result_id: existing.result_id,
+        idempotency_key: existing.idempotency_key,
+        type: existing.type,
+        payload: existing.payload,
+    }, {
+        run_id: incoming.run_id,
+        step_id: incoming.step_id,
+        attempt_id: incoming.attempt_id,
+        worker_session_id: incoming.worker_session_id,
+        result_id: incoming.result_id,
+        idempotency_key: incoming.idempotency_key,
+        type: incoming.type,
+        payload: incoming.payload,
+    });
+}
+function upsertRecords(existing, incoming, keyOf, assertMutable) {
+    const records = [...existing];
+    const indexes = new Map(records.map((record, index) => [keyOf(record), index]));
+    let changed = false;
+    for (const record of incoming) {
+        const key = keyOf(record);
+        const index = indexes.get(key);
+        if (index === undefined) {
+            indexes.set(key, records.length);
+            records.push(record);
+            changed = true;
+            continue;
+        }
+        const current = records[index];
+        if (recordsEqual(current, record))
+            continue;
+        assertMutable(current, record);
+        records[index] = record;
+        changed = true;
+    }
+    return { records, changed };
+}
+function applyUpdate(current, update) {
+    const runId = current.run.run_id;
+    assertCorrelatedRunId(update.run_id, runId, "update");
+    let changed = false;
+    let run = current.run;
+    if (update.run) {
+        assertRunRecord(update.run, runId);
+        if (!recordsEqual(run, update.run)) {
+            if (run.terminal !== null) {
+                throw new RunStoreError("immutable_record", `terminal run ${runId} cannot be changed`);
+            }
+            if (run.workflow_id !== update.run.workflow_id ||
+                run.workflow_version !== update.run.workflow_version ||
+                run.plan_digest !== update.run.plan_digest ||
+                run.created_at !== update.run.created_at) {
+                throw new RunStoreError("identity_conflict", `run ${runId} cannot change its plan binding or creation identity`);
+            }
+            run = update.run;
+            changed = true;
+        }
+    }
+    const tasks = upsertRecords(current.tasks, update.tasks ?? [], (task) => task.step_id, (existing, incoming) => {
+        if (existing.run_id !== incoming.run_id ||
+            existing.step_id !== incoming.step_id ||
+            existing.created_at !== incoming.created_at) {
+            throw new RunStoreError("identity_conflict", `task ${existing.step_id} cannot change its identity`);
+        }
+        if (["succeeded", "failed", "skipped", "cancelled"].includes(existing.state)) {
+            throw new RunStoreError("immutable_record", `terminal task ${existing.step_id} cannot be changed`);
+        }
+    });
+    changed ||= tasks.changed;
+    const attempts = upsertRecords(current.attempts, update.attempts ?? [], (attempt) => attempt.attempt_id, (existing, incoming) => {
+        if (existing.run_id !== incoming.run_id ||
+            existing.step_id !== incoming.step_id ||
+            existing.worker_session_id !== incoming.worker_session_id ||
+            existing.attempt_number !== incoming.attempt_number ||
+            existing.claim_token !== incoming.claim_token) {
+            throw new RunStoreError("identity_conflict", `attempt ${existing.attempt_id} cannot change its identity`);
+        }
+        if (existing.phase === "terminal") {
+            throw new RunStoreError("immutable_record", `terminal attempt ${existing.attempt_id} cannot be changed`);
+        }
+    });
+    changed ||= attempts.changed;
+    const claims = upsertRecords(current.claims, update.claims ?? [], (claim) => claim.claim_token, (existing, incoming) => {
+        if (existing.run_id !== incoming.run_id ||
+            existing.step_id !== incoming.step_id ||
+            existing.attempt_id !== incoming.attempt_id ||
+            existing.worker_session_id !== incoming.worker_session_id ||
+            existing.owner_id !== incoming.owner_id ||
+            existing.claimed_record_version !== incoming.claimed_record_version ||
+            existing.lease.acquired_at !== incoming.lease.acquired_at) {
+            throw new RunStoreError("identity_conflict", `claim ${existing.claim_token} cannot change its ownership identity`);
+        }
+    });
+    changed ||= claims.changed;
+    const events = [...current.events];
+    const eventById = new Map(events.map((event) => [event.event_id, event]));
+    const eventByKey = new Map(events.map((event) => [event.idempotency_key, event]));
+    const duplicateEventIds = [];
+    for (const event of update.events ?? []) {
+        assertCorrelatedRunId(event.run_id, runId, "event");
+        const byId = eventById.get(event.event_id);
+        const byKey = eventByKey.get(event.idempotency_key);
+        const existing = byId ?? byKey;
+        if (existing) {
+            if ((byId && byKey && byId.event_id !== byKey.event_id) ||
+                !eventReplayEquivalent(existing, event)) {
+                throw new RunStoreError("event_conflict", `event ${event.event_id} conflicts with a stored event identity`);
+            }
+            duplicateEventIds.push(existing.event_id);
+            continue;
+        }
+        const expectedSequence = events.length + 1;
+        if (event.sequence !== expectedSequence) {
+            throw new RunStoreError("event_conflict", `event ${event.event_id} sequence ${event.sequence} must be ${expectedSequence}`);
+        }
+        events.push(event);
+        eventById.set(event.event_id, event);
+        eventByKey.set(event.idempotency_key, event);
+        changed = true;
+    }
+    const results = [...current.results];
+    const resultById = new Map(results.map((result) => [result.result_id, result]));
+    const resultByAttempt = new Map(results.map((result) => [result.attempt_id, result]));
+    const duplicateResultIds = [];
+    for (const result of update.results ?? []) {
+        assertCorrelatedRunId(result.run_id, runId, "result");
+        const existing = resultById.get(result.result_id);
+        if (existing) {
+            if (!recordsEqual(existing, result)) {
+                throw new RunStoreError("result_conflict", `committed result ${result.result_id} is immutable`);
+            }
+            duplicateResultIds.push(existing.result_id);
+            continue;
+        }
+        const attemptResult = resultByAttempt.get(result.attempt_id);
+        if (attemptResult) {
+            throw new RunStoreError("result_conflict", `attempt ${result.attempt_id} already committed result ${attemptResult.result_id}`);
+        }
+        results.push(result);
+        resultById.set(result.result_id, result);
+        resultByAttempt.set(result.attempt_id, result);
+        changed = true;
+    }
+    const now = new Date().toISOString();
+    const candidate = {
+        schema_version: RUN_STORE_SCHEMA_VERSION,
+        record_version: changed
+            ? current.record_version + 1
+            : current.record_version,
+        run,
+        tasks: tasks.records,
+        attempts: attempts.records,
+        claims: claims.records,
+        events,
+        results,
+        created_at: current.created_at,
+        updated_at: changed ? now : current.updated_at,
+    };
+    validateCollections(candidate);
+    return {
+        snapshot: candidate,
+        changed,
+        duplicate_event_ids: duplicateEventIds,
+        duplicate_result_ids: duplicateResultIds,
+    };
+}
+function isUnsupportedDirectorySync(error) {
+    if (!(error instanceof Error) || !("code" in error))
+        return false;
+    const code = error.code;
+    return (code === "EINVAL" ||
+        code === "ENOTSUP" ||
+        code === "EISDIR" ||
+        (code === "EPERM" && process.platform === "win32"));
+}
+async function syncParentDirectory(filePath) {
+    let handle;
+    try {
+        handle = await open(dirname(filePath), "r");
+    }
+    catch (error) {
+        if (isUnsupportedDirectorySync(error))
+            return;
+        throw error;
+    }
+    try {
+        await handle.sync();
+    }
+    catch (error) {
+        if (!isUnsupportedDirectorySync(error))
+            throw error;
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function writeAtomic(filePath, data) {
+    await mkdir(dirname(filePath), { recursive: true, mode: DIRECTORY_MODE });
+    const temporaryPath = `${filePath}.tmp.${process.pid}.${randomUUID()}`;
+    let handle;
+    try {
+        handle = await open(temporaryPath, "wx", FILE_MODE);
+        await handle.writeFile(data, "utf8");
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await rename(temporaryPath, filePath);
+        await syncParentDirectory(filePath);
+    }
+    catch (error) {
+        await handle?.close().catch(() => undefined);
+        await rm(temporaryPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+async function readLockOwner(ownerPath) {
+    try {
+        return (await readFile(ownerPath, "utf8")).trim();
+    }
+    catch (error) {
+        if (isErrno(error, "ENOENT"))
+            return null;
+        throw error;
+    }
+}
+async function lockIsStale(lockDirectory, staleMs) {
+    try {
+        const lease = await stat(join(lockDirectory, LOCK_LEASE_FILE_NAME));
+        return Date.now() - lease.mtimeMs > staleMs;
+    }
+    catch (error) {
+        if (!isErrno(error, "ENOENT"))
+            return false;
+    }
+    try {
+        const lock = await stat(lockDirectory);
+        return Date.now() - lock.mtimeMs > staleMs;
+    }
+    catch {
+        return false;
+    }
+}
+async function recoverStaleLock(lockDirectory, staleMs) {
+    if (!(await lockIsStale(lockDirectory, staleMs)))
+        return false;
+    const quarantine = `${lockDirectory}.reclaimed.${randomUUID()}`;
+    try {
+        await rename(lockDirectory, quarantine);
+    }
+    catch (error) {
+        if (isErrno(error, "ENOENT"))
+            return true;
+        throw error;
+    }
+    await rm(quarantine, { recursive: true, force: true });
+    return true;
+}
+async function withRunLock(lockDirectory, options, operation) {
+    const ownerToken = `${process.pid}.${Date.now()}.${randomUUID()}`;
+    const ownerPath = join(lockDirectory, LOCK_OWNER_FILE_NAME);
+    const leasePath = join(lockDirectory, LOCK_LEASE_FILE_NAME);
+    const deadline = Date.now() + options.lock_wait_ms;
+    await mkdir(dirname(lockDirectory), {
+        recursive: true,
+        mode: DIRECTORY_MODE,
+    });
+    while (true) {
+        try {
+            await mkdir(lockDirectory, { mode: DIRECTORY_MODE });
+            try {
+                const owner = await open(ownerPath, "wx", FILE_MODE);
+                await owner.writeFile(ownerToken, "utf8");
+                await owner.sync();
+                await owner.close();
+                const lease = await open(leasePath, "wx", FILE_MODE);
+                await lease.writeFile(ownerToken, "utf8");
+                await lease.sync();
+                await lease.close();
+            }
+            catch (error) {
+                await rm(lockDirectory, { recursive: true, force: true });
+                throw error;
+            }
+            break;
+        }
+        catch (error) {
+            if (!isErrno(error, "EEXIST"))
+                throw error;
+            if (await recoverStaleLock(lockDirectory, options.lock_stale_ms))
+                continue;
+            if (Date.now() >= deadline) {
+                throw new RunStoreError("lock_timeout", `timed out acquiring run-store lock ${lockDirectory}`);
+            }
+            await sleep(options.lock_retry_ms);
+        }
+    }
+    let heartbeatRunning = false;
+    let lostOwnership = false;
+    const refresh = async () => {
+        if (heartbeatRunning || lostOwnership)
+            return;
+        heartbeatRunning = true;
+        try {
+            if ((await readLockOwner(ownerPath)) !== ownerToken) {
+                lostOwnership = true;
+                return;
+            }
+            const now = new Date();
+            await utimes(leasePath, now, now);
+        }
+        catch {
+            lostOwnership = true;
+        }
+        finally {
+            heartbeatRunning = false;
+        }
+    };
+    const timer = setInterval(() => void refresh(), options.lock_heartbeat_ms);
+    timer.unref();
+    const lock = {
+        async assertOwned() {
+            if (lostOwnership ||
+                (await readLockOwner(ownerPath)) !== ownerToken) {
+                lostOwnership = true;
+                throw new RunStoreError("lock_lost", `run-store lock ownership was lost for ${lockDirectory}`);
+            }
+        },
+    };
+    try {
+        return await operation(lock);
+    }
+    finally {
+        clearInterval(timer);
+        while (heartbeatRunning)
+            await sleep(1);
+        if ((await readLockOwner(ownerPath).catch(() => null)) === ownerToken) {
+            await rm(lockDirectory, { recursive: true, force: true });
+        }
+    }
+}
+export class DurableRunStore {
+    options;
+    constructor(options) {
+        this.options = resolveOptions(options);
+    }
+    runDirectory(runId) {
+        return join(this.options.root_directory, "runs", runStorageKey(runId));
+    }
+    ledgerPath(runId) {
+        return join(this.runDirectory(runId), LEDGER_FILE_NAME);
+    }
+    lockDirectory(runId) {
+        return join(this.options.root_directory, ".locks", `${runStorageKey(runId)}.lock`);
+    }
+    async readSnapshot(runId) {
+        try {
+            const raw = await readFile(this.ledgerPath(runId), "utf8");
+            return assertSnapshot(JSON.parse(raw), runId);
+        }
+        catch (error) {
+            if (isErrno(error, "ENOENT"))
+                return null;
+            if (error instanceof SyntaxError) {
+                throw new RunStoreError("invalid_record", `run ${runId} contains invalid JSON`);
+            }
+            throw error;
+        }
+    }
+    async createRun(input) {
+        assertRunRecord(input.run);
+        const runId = input.run.run_id;
+        return withRunLock(this.lockDirectory(runId), this.options, async (lock) => {
+            if (await this.readSnapshot(runId)) {
+                throw new RunStoreError("run_exists", `run ${runId} already exists`);
+            }
+            const now = new Date().toISOString();
+            const snapshot = {
+                schema_version: RUN_STORE_SCHEMA_VERSION,
+                record_version: 1,
+                run: input.run,
+                tasks: [...(input.tasks ?? [])],
+                attempts: [],
+                claims: [],
+                events: [],
+                results: [],
+                created_at: now,
+                updated_at: now,
+            };
+            validateCollections(snapshot);
+            await lock.assertOwned();
+            await writeAtomic(this.ledgerPath(runId), `${JSON.stringify(snapshot, null, 2)}\n`);
+            return snapshot;
+        });
+    }
+    async loadRun(runId) {
+        assertString(runId, "run_id");
+        return this.readSnapshot(runId);
+    }
+    async requireRun(runId) {
+        const snapshot = await this.loadRun(runId);
+        if (!snapshot) {
+            throw new RunStoreError("run_not_found", `run ${runId} was not found`);
+        }
+        return snapshot;
+    }
+    async updateRun(update) {
+        assertString(update.run_id, "run_id");
+        if (!Number.isSafeInteger(update.expected_record_version) ||
+            update.expected_record_version < 1) {
+            throw new RunStoreError("invalid_record", "expected_record_version must be a positive safe integer");
+        }
+        return withRunLock(this.lockDirectory(update.run_id), this.options, async (lock) => {
+            const current = await this.readSnapshot(update.run_id);
+            if (!current) {
+                throw new RunStoreError("run_not_found", `run ${update.run_id} was not found`);
+            }
+            let applied;
+            try {
+                applied = applyUpdate(current, update);
+            }
+            catch (error) {
+                if (current.record_version !== update.expected_record_version) {
+                    throw new RunStoreError("version_conflict", `run ${update.run_id} is at version ${current.record_version}, expected ${update.expected_record_version}`);
+                }
+                throw error;
+            }
+            if (!applied.changed) {
+                return {
+                    snapshot: current,
+                    applied: false,
+                    duplicate_event_ids: applied.duplicate_event_ids,
+                    duplicate_result_ids: applied.duplicate_result_ids,
+                };
+            }
+            if (current.record_version !== update.expected_record_version) {
+                throw new RunStoreError("version_conflict", `run ${update.run_id} is at version ${current.record_version}, expected ${update.expected_record_version}`);
+            }
+            await lock.assertOwned();
+            await writeAtomic(this.ledgerPath(update.run_id), `${JSON.stringify(applied.snapshot, null, 2)}\n`);
+            return {
+                snapshot: applied.snapshot,
+                applied: true,
+                duplicate_event_ids: applied.duplicate_event_ids,
+                duplicate_result_ids: applied.duplicate_result_ids,
+            };
+        });
+    }
+    /**
+     * Reads every valid run ledger after restart. No worker-session directory is
+     * consulted, and this store intentionally exposes no worker cleanup operation.
+     */
+    async loadAllRuns() {
+        const runsDirectory = join(this.options.root_directory, "runs");
+        let entries;
+        try {
+            entries = await readdir(runsDirectory, { withFileTypes: true });
+        }
+        catch (error) {
+            if (isErrno(error, "ENOENT"))
+                return [];
+            throw error;
+        }
+        const snapshots = [];
+        for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+            if (!entry.isDirectory())
+                continue;
+            const ledgerPath = join(runsDirectory, entry.name, LEDGER_FILE_NAME);
+            try {
+                const raw = await readFile(ledgerPath, "utf8");
+                snapshots.push(assertSnapshot(JSON.parse(raw)));
+            }
+            catch (error) {
+                if (isErrno(error, "ENOENT"))
+                    continue;
+                if (error instanceof SyntaxError) {
+                    throw new RunStoreError("invalid_record", `run ledger ${ledgerPath} contains invalid JSON`);
+                }
+                throw error;
+            }
+        }
+        return snapshots;
+    }
+}