oh-my-super-agent 0.1.0

package/dist/src/audit/run-ledger.js

@@ -0,0 +1,1655 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { assertActorId, assertLockId, assertOpaqueId } from "../domain/records.js";
+import { assertFileInside, openStableDirectory, readImmutableFile, writeImmutableFile, } from "../evidence/immutable-file.js";
+import { assertRunCertificationAuthorityReference, assertRunCertificationAuthorityResolver, } from "../outbox/store.js";
+import { findPackageRoot } from "../package-root.js";
+import { acquireDirectoryLock, assertRecoveredLock } from "../runtime/lock.js";
+import { currentProcessInstanceId } from "../runtime/process-identity.js";
+import { assertSchema, loadJsonSchema } from "../runtime/schema.js";
+import { createStableId } from "../runtime/stable-id.js";
+import { systemBootId, systemClockSample } from "../runtime/system-clock.js";
+import { isRecord } from "../utils/fs.js";
+const MAX_ENTRY_BYTES = 1024 * 1024;
+const SHA256_PATTERN = /^[a-f0-9]{64}$/;
+const RUN_ID_PATTERN = /^run-[a-f0-9]{48}$/;
+const ENTRY_ID_PATTERN = /^audit-[a-f0-9]{48}$/;
+const RUN_LEDGER = Symbol("OMS run ledger");
+const RUN_LEDGERS = new WeakMap();
+const AUDIT_RUN_TERMINAL_WRITER = Symbol("OMS audit run terminal writer");
+const AUDIT_RUN_TERMINAL_WRITERS = new WeakMap();
+const LIVE_RUN_WRITER = Symbol("OMS live run writer");
+const LIVE_RUN_WRITERS = new WeakMap();
+const RUN_CERTIFICATION_SNAPSHOT = Symbol("OMS run certification snapshot");
+const RUN_CERTIFICATION_SNAPSHOTS = new WeakSet();
+const TWELVE_HOURS_MS = 12 * 60 * 60 * 1000;
+const TWENTY_FOUR_HOURS_MS = 24 * 60 * 60 * 1000;
+const MAX_RESTART_GAP_MS = 30 * 60 * 1000;
+export class RunLedgerConflictError extends Error {
+    constructor(operationId) {
+        super(`run ledger operation conflicts with immutable content: ${operationId}`);
+        this.name = "RunLedgerConflictError";
+    }
+}
+export function createLiveRunLedger(options) {
+    const captured = {
+        ledgerRoot: options.ledgerRoot,
+        locksRoot: options.locksRoot,
+        packageRoot: options.packageRoot,
+    };
+    return createRunLedger(captured, {
+        clockClass: "live",
+        processId: process.pid,
+        processInstanceId: currentProcessInstanceId(),
+        bootId: systemBootId(),
+        sample: () => {
+            const sampled = systemClockSample();
+            return { wallTime: sampled.wallTime, monotonicNs: sampled.monotonicNs };
+        },
+    });
+}
+export function createNonCertifyingRunLedger(options) {
+    const captured = {
+        ledgerRoot: options.ledgerRoot,
+        locksRoot: options.locksRoot,
+        clock: options.clock,
+        packageRoot: options.packageRoot,
+    };
+    const sample = captured.clock.sample;
+    if (typeof sample !== "function")
+        throw new Error("non-certifying run ledger requires a clock sample function");
+    return createRunLedger(captured, {
+        clockClass: "synthetic",
+        processId: process.pid,
+        processInstanceId: createStableId("synthetic", randomUUID().toLowerCase()),
+        bootId: createStableId("synthetic-boot", randomUUID().toLowerCase()),
+        sample: () => sample(),
+    });
+}
+export function assertRunLedger(value) {
+    if (typeof value !== "object" || value === null || !RUN_LEDGERS.has(value)) {
+        throw new Error("run audit requires a real OMS RunLedgerStore");
+    }
+    if (!Object.isFrozen(value))
+        throw new Error("run ledger lost its frozen authority boundary");
+}
+export function createAuditRunTerminalWriter(ledger) {
+    assertRunLedger(ledger);
+    const metadata = RUN_LEDGERS.get(ledger);
+    if (!metadata)
+        throw new Error("audit run terminal writer metadata is unavailable");
+    const writer = Object.freeze({
+        [AUDIT_RUN_TERMINAL_WRITER]: true,
+        appendAtHead(input) {
+            const captured = captureAppendAtHeadInput(input);
+            if (captured.entryKind !== "run-completed" && captured.entryKind !== "run-aborted") {
+                throw new Error("audit run terminal writer accepts only terminal entries");
+            }
+            return metadata.internal.append(captured, "audit", captured.expectedHeadSha256);
+        },
+    });
+    AUDIT_RUN_TERMINAL_WRITERS.set(writer, metadata.internal);
+    return writer;
+}
+export function assertAuditRunTerminalWriter(value) {
+    if (typeof value !== "object" || value === null || !AUDIT_RUN_TERMINAL_WRITERS.has(value)) {
+        throw new Error("audit run termination requires a real OMS terminal writer");
+    }
+    if (!Object.isFrozen(value))
+        throw new Error("audit run terminal writer lost its frozen authority boundary");
+}
+/** Generic ledgers are deliberately audit-only, including live-clock ledgers. */
+export function assertCertifyingRunLedger(_value, _head) {
+    throw new Error("certifying a run requires a real typed OMS LiveRunWriter");
+}
+export function createLiveRunWriter(options) {
+    const captured = { ledger: options.ledger, authority: options.authority };
+    assertRunLedger(captured.ledger);
+    assertRunCertificationAuthorityResolver(captured.authority);
+    const metadata = RUN_LEDGERS.get(captured.ledger);
+    if (!metadata || metadata.clockClass !== "live") {
+        throw new Error("live run writer requires a production live-clock ledger");
+    }
+    const writer = Object.freeze({
+        [LIVE_RUN_WRITER]: true,
+        start(input) {
+            const start = captureStartLiveInput(input);
+            if (start.runKind !== "12h" && start.runKind !== "24h") {
+                throw new Error("certifying runs must use the 12h or 24h run kind");
+            }
+            const runId = assertRunId(createStableId("run", start.operationId));
+            const authority = captured.authority.resolve(start.source);
+            const previous = resolvePreviousCanaryForStart(writer, start, authority);
+            assertAuthorityBinding(authority, {
+                action: "start",
+                runId,
+                operationId: start.operationId,
+                runKind: start.runKind,
+                policyDigest: start.policyDigest,
+                ticketSetDigest: start.ticketSetDigest,
+                servicePlanDigest: start.servicePlanDigest,
+                expectedHead: null,
+                previousCanary: previous,
+            });
+            const payload = {
+                authority,
+                previous_canary: previous,
+                service_plan_digest: assertSha256(start.servicePlanDigest, "run service plan digest"),
+                ticket_set_digest: assertSha256(start.ticketSetDigest, "run ticket set digest"),
+            };
+            const written = metadata.internal.start(start, "trusted-live", payload);
+            assertAuthorityPrecedesEntry(authority, written.entry);
+            return written;
+        },
+        heartbeat(input) {
+            return appendAuthorityEvent(metadata.internal, captured.authority, input, "heartbeat", "heartbeat");
+        },
+        recordProcessRestart(input) {
+            const event = captureLiveEventInput(input);
+            const entries = trustedRecords(metadata.internal, event.runId);
+            const authority = captured.authority.resolve(event.source);
+            const existing = entries.find((entry) => entry.entry.operation_id === event.operationId);
+            if (existing) {
+                const previous = entries[existing.entry.sequence - 1];
+                if (!previous || existing.entry.entry_kind !== "process-restarted") {
+                    throw new RunLedgerConflictError(event.operationId);
+                }
+                assertAuthorityForHistory(authority, "process-restart", entries, previous.ref, event.operationId);
+                if (!sameJson(existing.entry.payload.authority, authority))
+                    throw new RunLedgerConflictError(event.operationId);
+                return result("replayed", existing);
+            }
+            const last = requiredLast(entries);
+            if (isTerminal(last.entry.entry_kind))
+                throw new Error(`trusted run ledger is terminal: ${event.runId}`);
+            assertAuthorityForHistory(authority, "process-restart", entries, last.ref, event.operationId);
+            assertAuthorityAfterHead(authority, last.entry);
+            return metadata.internal.append({
+                runId: event.runId,
+                operationId: event.operationId,
+                entryKind: "process-restarted",
+                payload: {
+                    authority,
+                    previous_process_instance_id: last.entry.process_instance_id,
+                },
+            }, "trusted-live", last.ref.sha256);
+        },
+        recordLockRecovery(input) {
+            const capturedInput = {
+                runId: input.runId,
+                operationId: input.operationId,
+                recovery: input.recovery,
+            };
+            const runId = assertRunId(capturedInput.runId);
+            const operationId = assertOpaqueId(capturedInput.operationId, "run entry operation id");
+            assertRecoveredLock(capturedInput.recovery);
+            const entries = trustedRecords(metadata.internal, runId);
+            const last = requiredLast(entries);
+            if (isTerminal(last.entry.entry_kind))
+                throw new Error(`trusted run ledger is terminal: ${runId}`);
+            const recovery = captureRecoveryEvidence(capturedInput.recovery);
+            return metadata.internal.append({
+                runId,
+                operationId,
+                entryKind: "outbox-lock-recovered",
+                payload: { lock_recovery: recovery },
+            }, "trusted-live", last.ref.sha256);
+        },
+        complete(input) {
+            const completion = captureCompleteInput(input);
+            const entries = trustedRecords(metadata.internal, completion.runId);
+            const first = requiredFirst(entries);
+            const last = requiredLast(entries);
+            if (first.entry.run_kind !== completion.expectedRunKind) {
+                throw new Error("run completion expected kind does not match the trusted run");
+            }
+            const authority = captured.authority.resolve(completion.source);
+            const existing = entries.find((entry) => entry.entry.operation_id === completion.operationId);
+            if (existing) {
+                const previous = entries[existing.entry.sequence - 1];
+                if (!previous
+                    ||
+                        existing.entry.entry_kind !== "run-completed"
+                    || existing.entry.provenance_class !== "trusted-live"
+                    || !sameJson(existing.entry.payload.authority, authority)) {
+                    throw new RunLedgerConflictError(completion.operationId);
+                }
+                assertAuthorityForHistory(authority, "complete", entries, previous.ref, completion.operationId);
+                return writer.certify(existing.ref);
+            }
+            if (isTerminal(last.entry.entry_kind))
+                throw new Error(`trusted run ledger is terminal: ${completion.runId}`);
+            assertAuthorityForHistory(authority, "complete", entries, last.ref, completion.operationId);
+            assertAuthorityAfterHead(authority, last.entry);
+            const minimumDurationMs = minimumDuration(completion.expectedRunKind);
+            const previousCanary = first.entry.payload.previous_canary;
+            const written = metadata.internal.append({
+                runId: completion.runId,
+                operationId: completion.operationId,
+                entryKind: "run-completed",
+                payload: {},
+            }, "trusted-live", last.ref.sha256, ({ entries: lockedEntries, sampled }) => {
+                const prospective = prospectiveObservation(lockedEntries, completion.operationId, "run-completed", sampled, metadata.internal.clock);
+                const timeline = analyzeTimeline([...lockedEntries.map(toObservation), prospective]);
+                assertMinimumDuration(timeline, minimumDurationMs);
+                const digest = certificationDigest(lockedEntries, prospective, authority, completion.expectedRunKind, minimumDurationMs, previousCanary);
+                return {
+                    authority,
+                    expected_run_kind: completion.expectedRunKind,
+                    metrics_sha256: digest,
+                    minimum_duration_ms: minimumDurationMs,
+                    previous_canary: previousCanary,
+                };
+            });
+            return writer.certify(written.ref);
+        },
+        certify(head) {
+            return certifyTrustedRun(writer, captureReference(head));
+        },
+    });
+    LIVE_RUN_WRITERS.set(writer, { ledger: captured.ledger, authority: captured.authority, internal: metadata.internal });
+    return writer;
+}
+export function assertLiveRunWriter(value) {
+    if (typeof value !== "object" || value === null || !LIVE_RUN_WRITERS.has(value)) {
+        throw new Error("run certification requires a real OMS LiveRunWriter");
+    }
+    if (!Object.isFrozen(value))
+        throw new Error("live run writer lost its frozen authority boundary");
+}
+export function assertRunCertificationSnapshot(value) {
+    if (typeof value !== "object" || value === null || !RUN_CERTIFICATION_SNAPSHOTS.has(value)) {
+        throw new Error("run certification requires a real OMS RunCertificationSnapshot");
+    }
+    if (!Object.isFrozen(value))
+        throw new Error("run certification snapshot lost its frozen authority boundary");
+}
+function createRunLedger(options, clock) {
+    const captured = {
+        ledgerRoot: options.ledgerRoot,
+        locksRoot: options.locksRoot,
+        packageRoot: options.packageRoot,
+    };
+    const ledgerRoot = openStableDirectory(captured.ledgerRoot, "run ledger root");
+    const locksDirectory = openStableDirectory(captured.locksRoot, "run ledger locks root");
+    if (ledgerRoot.path === locksDirectory.path) {
+        throw new Error("run ledger and locks roots must be different directories");
+    }
+    const schema = loadJsonSchema(join(captured.packageRoot ?? findPackageRoot(), "schemas", "run-ledger-entry.schema.json"));
+    function start(input, provenance = "audit", suppliedPayload) {
+        const startInput = captureStartInput(input);
+        const operationId = assertOpaqueId(startInput.operationId, "run start operation id");
+        const runKind = assertRunKind(startInput.runKind);
+        const policyDigest = assertSha256(startInput.policyDigest, "run policy digest");
+        const ticketSetDigest = assertSha256(startInput.ticketSetDigest, "run ticket set digest");
+        const servicePlanDigest = assertSha256(startInput.servicePlanDigest, "run service plan digest");
+        if (provenance === "trusted-live" && clock.clockClass !== "live") {
+            throw new Error("synthetic clocks can never create trusted run provenance");
+        }
+        const payload = canonicalizeObject(suppliedPayload ?? {
+            service_plan_digest: servicePlanDigest,
+            ticket_set_digest: ticketSetDigest,
+        }, "run start payload");
+        if (payload.ticket_set_digest !== ticketSetDigest || payload.service_plan_digest !== servicePlanDigest) {
+            throw new Error("run start payload does not match its materialized digests");
+        }
+        const runId = assertRunId(createStableId("run", operationId));
+        const operationDigest = operationSha256({
+            entryKind: "run-started",
+            runId,
+            runKind,
+            operationId,
+            policyDigest,
+            clockClass: clock.clockClass,
+            provenance,
+            payload,
+        });
+        locksDirectory.assertUnchanged();
+        const lock = acquireDirectoryLock({
+            locksRoot: locksDirectory.path,
+            lockId: runLockId(runId),
+            ownerId: "run-ledger",
+            note: `run-start:${runId}`,
+        });
+        try {
+            locksDirectory.assertUnchanged();
+            const existing = readRun(runId, schema, ledgerRoot);
+            if (existing.length > 0) {
+                const replay = findReplay(existing, operationId, operationDigest, clock.clockClass, provenance);
+                if (replay)
+                    return result("replayed", replay);
+                throw new RunLedgerConflictError(operationId);
+            }
+            const entry = makeEntry({
+                runId,
+                sequence: 0,
+                entryKind: "run-started",
+                runKind,
+                operationId,
+                operationDigest,
+                policyDigest,
+                clock,
+                provenance,
+                sampled: sampleClock(clock),
+                previousSha256: null,
+                payload,
+            });
+            const written = writeEntry(entry, schema, ledgerRoot);
+            validateRun(readRun(runId, schema, ledgerRoot));
+            return result(written.status, written.stored);
+        }
+        finally {
+            lock.release();
+            locksDirectory.assertUnchanged();
+        }
+    }
+    function append(input, provenance = "audit", expectedHeadSha256, payloadFactory) {
+        const capturedInput = captureAppendInput(input);
+        const runId = assertRunId(capturedInput.runId);
+        const operationId = assertOpaqueId(capturedInput.operationId, "run entry operation id");
+        const entryKind = assertAppendEntryKind(capturedInput.entryKind);
+        const fixedPayload = payloadFactory ? undefined : canonicalizeObject(capturedInput.payload, "run entry payload");
+        locksDirectory.assertUnchanged();
+        const lock = acquireDirectoryLock({
+            locksRoot: locksDirectory.path,
+            lockId: runLockId(runId),
+            ownerId: "run-ledger",
+            note: `run-append:${runId}`,
+        });
+        try {
+            locksDirectory.assertUnchanged();
+            const entries = readRun(runId, schema, ledgerRoot);
+            validateRun(entries);
+            const first = requiredFirst(entries);
+            const last = requiredLast(entries);
+            const existingOperation = entries.find((entry) => entry.entry.operation_id === operationId);
+            if (existingOperation && payloadFactory)
+                throw new RunLedgerConflictError(operationId);
+            if (existingOperation && fixedPayload) {
+                const digest = operationSha256({
+                    entryKind,
+                    runId,
+                    runKind: first.entry.run_kind,
+                    operationId,
+                    policyDigest: first.entry.policy_sha256,
+                    clockClass: clock.clockClass,
+                    provenance,
+                    payload: fixedPayload,
+                });
+                const replay = findReplay(entries, operationId, digest, clock.clockClass, provenance);
+                if (replay)
+                    return result("replayed", replay);
+            }
+            if (isTerminal(last.entry.entry_kind))
+                throw new Error(`run ledger is terminal: ${runId}`);
+            if (expectedHeadSha256 !== undefined && last.ref.sha256 !== assertSha256(expectedHeadSha256, "expected run head digest")) {
+                throw new Error("run ledger trusted head advanced concurrently");
+            }
+            if (first.entry.clock_class !== clock.clockClass) {
+                throw new Error("run ledger clock class cannot change across processes");
+            }
+            if (first.entry.provenance_class !== provenance) {
+                throw new Error("run ledger provenance class cannot change within a run");
+            }
+            if (provenance === "trusted-live") {
+                if (clock.clockClass !== "live" || entries.some((entry) => entry.entry.provenance_class !== "trusted-live")) {
+                    throw new Error("trusted run history cannot descend from audit-only or synthetic provenance");
+                }
+                if (entries.some((entry) => entry.entry.boot_id !== clock.bootId)) {
+                    throw new Error("trusted run cannot continue across a system boot identity change");
+                }
+                const changedProcess = last.entry.process_instance_id !== clock.processInstanceId;
+                if (changedProcess !== (entryKind === "process-restarted")) {
+                    throw new Error(changedProcess
+                        ? "new process must append a typed process-restarted entry first"
+                        : "process-restarted requires a fresh process instance");
+                }
+            }
+            const sampled = sampleClock(clock);
+            assertClockAdvances(last.entry, sampled, clock);
+            const payload = canonicalizeObject(payloadFactory ? payloadFactory({ entries, sampled }) : fixedPayload ?? {}, "run entry payload");
+            const operationDigest = operationSha256({
+                entryKind,
+                runId,
+                runKind: first.entry.run_kind,
+                operationId,
+                policyDigest: first.entry.policy_sha256,
+                clockClass: clock.clockClass,
+                provenance,
+                payload,
+            });
+            const entry = makeEntry({
+                runId,
+                sequence: last.entry.sequence + 1,
+                entryKind,
+                runKind: first.entry.run_kind,
+                operationId,
+                operationDigest,
+                policyDigest: first.entry.policy_sha256,
+                clock,
+                provenance,
+                sampled,
+                previousSha256: last.ref.sha256,
+                payload,
+            });
+            const written = writeEntry(entry, schema, ledgerRoot);
+            validateRun(readRun(runId, schema, ledgerRoot));
+            return result(written.status, written.stored);
+        }
+        finally {
+            lock.release();
+            locksDirectory.assertUnchanged();
+        }
+    }
+    const store = Object.freeze({
+        [RUN_LEDGER]: true,
+        start(input) {
+            return start(input, "audit");
+        },
+        append(input) {
+            const capturedInput = captureAppendInput(input);
+            if (isTerminal(capturedInput.entryKind)) {
+                throw new Error("generic run ledger cannot append controller terminal entries");
+            }
+            return append(capturedInput, "audit");
+        },
+        appendAtHead(input) {
+            const capturedInput = captureAppendAtHeadInput(input);
+            if (isTerminal(capturedInput.entryKind)) {
+                throw new Error("generic run ledger cannot append controller terminal entries");
+            }
+            return append(capturedInput, "audit", capturedInput.expectedHeadSha256);
+        },
+        read(ref) {
+            return readReference(captureReference(ref), schema, ledgerRoot).entry;
+        },
+        list(runId) {
+            const entries = readRun(assertRunId(runId), schema, ledgerRoot);
+            validateRun(entries);
+            return deepFreeze(entries.map((entry) => entry.entry));
+        },
+        listRunIds() {
+            return listStoredRunIds(schema, ledgerRoot);
+        },
+        head(runId) {
+            const entries = readRun(assertRunId(runId), schema, ledgerRoot);
+            validateRun(entries);
+            return entries.at(-1)?.ref;
+        },
+        deriveMetrics(head) {
+            const pinned = readReference(captureReference(head), schema, ledgerRoot);
+            const entries = readRun(pinned.entry.run_id, schema, ledgerRoot);
+            validateRun(entries);
+            const latest = requiredLast(entries);
+            if (!sameReference(latest.ref, pinned.ref)) {
+                throw new Error("run ledger head is stale or does not identify the latest entry");
+            }
+            return deriveMetrics(entries, false);
+        },
+    });
+    const internal = { clock, start, append, records(runId) {
+            const entries = readRun(assertRunId(runId), schema, ledgerRoot);
+            validateRun(entries);
+            return entries;
+        } };
+    RUN_LEDGERS.set(store, { clockClass: clock.clockClass, internal });
+    return store;
+}
+function appendAuthorityEvent(internal, resolver, input, entryKind, authorityAction) {
+    const event = captureLiveEventInput(input);
+    const entries = trustedRecords(internal, event.runId);
+    const authority = resolver.resolve(event.source);
+    const existing = entries.find((entry) => entry.entry.operation_id === event.operationId);
+    if (existing) {
+        const previous = entries[existing.entry.sequence - 1];
+        if (!previous || existing.entry.entry_kind !== entryKind)
+            throw new RunLedgerConflictError(event.operationId);
+        assertAuthorityForHistory(authority, authorityAction, entries, previous.ref, event.operationId);
+        if (!sameJson(existing.entry.payload.authority, authority))
+            throw new RunLedgerConflictError(event.operationId);
+        return result("replayed", existing);
+    }
+    const last = requiredLast(entries);
+    if (isTerminal(last.entry.entry_kind))
+        throw new Error(`trusted run ledger is terminal: ${event.runId}`);
+    assertAuthorityForHistory(authority, authorityAction, entries, last.ref, event.operationId);
+    assertAuthorityAfterHead(authority, last.entry);
+    return internal.append({
+        runId: event.runId,
+        operationId: event.operationId,
+        entryKind,
+        payload: { authority },
+    }, "trusted-live", last.ref.sha256);
+}
+function certifyTrustedRun(writer, head) {
+    assertLiveRunWriter(writer);
+    const metadata = LIVE_RUN_WRITERS.get(writer);
+    if (!metadata)
+        throw new Error("live run writer metadata is unavailable");
+    const entries = metadata.internal.records(head.run_id);
+    const latest = requiredLast(entries);
+    if (!sameReference(latest.ref, head))
+        throw new Error("certification requires the canonical latest trusted head");
+    if (entries.some((entry) => entry.entry.clock_class !== "live" || entry.entry.provenance_class !== "trusted-live")) {
+        throw new Error("audit-only or synthetic provenance cannot be certified");
+    }
+    if (latest.entry.entry_kind !== "run-completed") {
+        throw new Error("only a terminal run-completed entry may certify a run");
+    }
+    validatePersistedAuthorities(metadata.authority, entries);
+    const first = requiredFirst(entries);
+    const completion = latest.entry.payload;
+    const expectedKind = assertCertifyingRunKind(completion.expected_run_kind);
+    if (expectedKind !== first.entry.run_kind)
+        throw new Error("terminal expected run kind does not match run history");
+    const expectedMinimum = minimumDuration(expectedKind);
+    if (completion.minimum_duration_ms !== expectedMinimum)
+        throw new Error("terminal minimum duration is not policy-derived");
+    const timeline = analyzeTimeline(entries.map(toObservation));
+    assertMinimumDuration(timeline, expectedMinimum);
+    const expectedDigest = certificationDigest(entries.slice(0, -1), toObservation(latest), assertResolvedAuthority(completion.authority), expectedKind, expectedMinimum, completion.previous_canary);
+    if (completion.metrics_sha256 !== expectedDigest)
+        throw new Error("terminal certification metrics digest is invalid");
+    validateCanaryChain(writer, entries);
+    const metrics = deriveMetrics(entries, true);
+    const snapshot = deepFreeze({
+        [RUN_CERTIFICATION_SNAPSHOT]: true,
+        reference: {
+            run_id: metrics.run_id,
+            head: metrics.head,
+            metrics_sha256: metrics.metrics_sha256,
+        },
+        entry: latest.entry,
+        metrics,
+    });
+    RUN_CERTIFICATION_SNAPSHOTS.add(snapshot);
+    return snapshot;
+}
+function validateCanaryChain(writer, entries) {
+    const first = requiredFirst(entries);
+    const previousValue = first.entry.payload.previous_canary;
+    const terminalPrevious = requiredLast(entries).entry.payload.previous_canary;
+    if (!sameJson(previousValue, terminalPrevious))
+        throw new Error("terminal previous canary binding changed");
+    if (first.entry.run_kind === "12h") {
+        if (previousValue !== null)
+            throw new Error("12h canary must not depend on another canary");
+        return;
+    }
+    if (first.entry.run_kind !== "24h")
+        throw new Error("only 12h and 24h runs can certify");
+    const previousRef = parseCertificationReference(previousValue);
+    const previousMetrics = certifyTrustedRun(writer, previousRef.head).metrics;
+    if (previousMetrics.run_id !== previousRef.run_id
+        || previousMetrics.metrics_sha256 !== previousRef.metrics_sha256
+        || previousMetrics.run_kind !== "12h"
+        || previousMetrics.status !== "completed") {
+        throw new Error("24h run does not reference a certified terminal 12h canary");
+    }
+    if (!previousMetrics.ended_at || previousMetrics.ended_at > first.entry.recorded_at) {
+        throw new Error("24h run began before its 12h canary completed");
+    }
+    const currentProcesses = new Set(entries.map((entry) => entry.entry.process_instance_id));
+    if (previousMetrics.process_instance_ids.some((processId) => currentProcesses.has(processId))) {
+        throw new Error("24h run must use processes separate from its 12h canary");
+    }
+    if (previousMetrics.ticket_set_digest === first.entry.payload.ticket_set_digest) {
+        throw new Error("24h run must use a fresh ticket set after its 12h canary");
+    }
+}
+function resolvePreviousCanaryForStart(writer, input, authority) {
+    if (input.runKind === "12h") {
+        if (input.previousCanary !== null)
+            throw new Error("12h canary must not depend on another canary");
+        return null;
+    }
+    if (input.previousCanary === null)
+        throw new Error("24h run requires a certified 12h canary");
+    const previousRef = captureCertificationReference(input.previousCanary);
+    const metrics = certifyTrustedRun(writer, previousRef.head).metrics;
+    if (metrics.run_id !== previousRef.run_id
+        || metrics.metrics_sha256 !== previousRef.metrics_sha256
+        || metrics.run_kind !== "12h"
+        || metrics.status !== "completed") {
+        throw new Error("24h run requires a certified terminal 12h canary");
+    }
+    if (!metrics.ended_at || metrics.ended_at > authority.occurred_at) {
+        throw new Error("24h authority was issued before the 12h canary completed");
+    }
+    if (metrics.process_instance_ids.includes(currentProcessInstanceId())) {
+        throw new Error("24h run must use a process separate from its 12h canary");
+    }
+    if (metrics.ticket_set_digest === input.ticketSetDigest) {
+        throw new Error("24h run must use a fresh ticket set after its 12h canary");
+    }
+    return serializeCertificationReference(previousRef);
+}
+function trustedRecords(internal, runIdValue) {
+    const entries = internal.records(assertRunId(runIdValue));
+    if (entries.length === 0)
+        throw new Error("trusted run ledger does not exist");
+    if (entries.some((entry) => entry.entry.clock_class !== "live" || entry.entry.provenance_class !== "trusted-live")) {
+        throw new Error("trusted writer refuses an audit-only or synthetic run history");
+    }
+    return entries;
+}
+function validatePersistedAuthorities(resolver, entries) {
+    for (let index = 0; index < entries.length; index += 1) {
+        const stored = entries[index];
+        if (!stored)
+            throw new Error("trusted run authority entry is missing");
+        const entry = stored.entry;
+        if (entry.entry_kind === "outbox-lock-recovered") {
+            validateStoredRecovery(entry.payload.lock_recovery);
+            continue;
+        }
+        const storedAuthority = assertResolvedAuthority(entry.payload.authority);
+        const resolved = resolver.resolveStored(storedAuthority.reference);
+        if (!sameJson(storedAuthority, resolved))
+            throw new Error("persisted authority no longer matches immutable outbox evidence");
+        const previous = entries[index - 1];
+        const action = authorityAction(entry.entry_kind);
+        assertAuthorityForHistory(resolved, action, entries, previous?.ref ?? null, entry.operation_id);
+        if (previous)
+            assertAuthorityAfterHead(resolved, previous.entry);
+        assertAuthorityPrecedesEntry(resolved, entry);
+    }
+}
+function authorityAction(entryKind) {
+    if (entryKind === "run-started")
+        return "start";
+    if (entryKind === "heartbeat")
+        return "heartbeat";
+    if (entryKind === "process-restarted")
+        return "process-restart";
+    if (entryKind === "run-completed")
+        return "complete";
+    throw new Error(`trusted entry kind has no certification authority action: ${entryKind}`);
+}
+function assertAuthorityForHistory(authority, action, entries, expectedHead, operationId) {
+    const first = requiredFirst(entries);
+    assertAuthorityBinding(authority, {
+        action,
+        runId: first.entry.run_id,
+        operationId,
+        runKind: assertCertifyingRunKind(first.entry.run_kind),
+        policyDigest: first.entry.policy_sha256,
+        ticketSetDigest: assertSha256(first.entry.payload.ticket_set_digest, "trusted ticket set digest"),
+        servicePlanDigest: assertSha256(first.entry.payload.service_plan_digest, "trusted service plan digest"),
+        expectedHead,
+        previousCanary: first.entry.payload.previous_canary,
+    });
+}
+function assertAuthorityBinding(authority, expected) {
+    const expectedBinding = {
+        schema_version: 1,
+        action: expected.action,
+        completion_semantics: expected.action === "start"
+            ? "begin-run"
+            : expected.action === "heartbeat"
+                ? "append-heartbeat"
+                : expected.action === "process-restart"
+                    ? "record-process-restart"
+                    : "terminal-run-completed",
+        run_id: expected.runId,
+        operation_id: expected.operationId,
+        run_kind: expected.runKind,
+        policy_sha256: expected.policyDigest,
+        ticket_set_digest: expected.ticketSetDigest,
+        service_plan_digest: expected.servicePlanDigest,
+        expected_head: expected.expectedHead,
+        previous_canary: expected.previousCanary,
+    };
+    if (!sameJson(authority.binding, expectedBinding)) {
+        throw new Error("certification authority does not bind the exact canonical run transition");
+    }
+}
+function captureRecoveryEvidence(recovery) {
+    const captured = {
+        lockId: recovery.lock_id,
+        generationId: recovery.generation_id,
+        recoveredBy: recovery.recovered_by,
+        previousOwner: recovery.previousOwner,
+        archivedPath: recovery.archivedPath,
+        recoveryEvidencePath: recovery.recoveryEvidencePath,
+    };
+    const lockId = assertLockId(captured.lockId, "recovered lock id");
+    const generationId = assertOpaqueId(captured.generationId, "recovered lock generation id");
+    const recoveredBy = assertActorId(captured.recoveredBy, "lock recovery actor");
+    if (dirname(captured.recoveryEvidencePath) !== captured.archivedPath) {
+        throw new Error("lock recovery evidence escaped its immutable archive");
+    }
+    const bytes = readImmutableFile(captured.recoveryEvidencePath, MAX_ENTRY_BYTES);
+    const evidence = parseJson(bytes);
+    if (!isRecord(evidence)
+        || evidence.lock_id !== lockId
+        || evidence.generation_id !== generationId
+        || evidence.recovered_by !== recoveredBy) {
+        throw new Error("lock recovery evidence does not match its branded recovery result");
+    }
+    const previousProcess = captured.previousOwner?.process_instance_id ?? null;
+    if (!sameJson(evidence.previous_owner, captured.previousOwner)) {
+        throw new Error("lock recovery previous owner does not match immutable evidence");
+    }
+    return deepFreeze({
+        lock_id: lockId,
+        generation_id: generationId,
+        recovered_by: recoveredBy,
+        previous_process_instance_id: previousProcess,
+        recovery_evidence_path: captured.recoveryEvidencePath,
+        recovery_evidence_sha256: sha256(bytes),
+    });
+}
+function validateStoredRecovery(value) {
+    if (!isRecord(value))
+        throw new Error("trusted lock recovery payload must be an object");
+    assertExactKeys(value, [
+        "lock_id",
+        "generation_id",
+        "previous_process_instance_id",
+        "recovered_by",
+        "recovery_evidence_path",
+        "recovery_evidence_sha256",
+    ], "trusted lock recovery payload");
+    const lockId = assertLockId(value.lock_id, "recovered lock id");
+    const generationId = assertOpaqueId(value.generation_id, "recovered lock generation id");
+    const recoveredBy = assertActorId(value.recovered_by, "lock recovery actor");
+    const path = value.recovery_evidence_path;
+    if (typeof path !== "string")
+        throw new Error("invalid lock recovery evidence path");
+    const bytes = readImmutableFile(path, MAX_ENTRY_BYTES);
+    if (sha256(bytes) !== assertSha256(value.recovery_evidence_sha256, "lock recovery evidence digest")) {
+        throw new Error("lock recovery evidence digest changed");
+    }
+    const evidence = parseJson(bytes);
+    if (!isRecord(evidence)
+        || evidence.lock_id !== lockId
+        || evidence.generation_id !== generationId
+        || evidence.recovered_by !== recoveredBy) {
+        throw new Error("persisted lock recovery evidence does not match the trusted entry");
+    }
+    const previousProcess = isRecord(evidence.previous_owner) ? evidence.previous_owner.process_instance_id : null;
+    if (previousProcess !== value.previous_process_instance_id) {
+        throw new Error("persisted lock recovery previous process binding changed");
+    }
+}
+function makeEntry(input) {
+    return deepFreeze({
+        schema_version: 1,
+        entry_id: createStableId("audit", input.runId, input.operationId),
+        run_id: input.runId,
+        sequence: input.sequence,
+        entry_kind: input.entryKind,
+        run_kind: input.runKind,
+        operation_id: input.operationId,
+        operation_sha256: input.operationDigest,
+        policy_sha256: input.policyDigest,
+        clock_class: input.clock.clockClass,
+        provenance_class: input.provenance,
+        recorded_at: input.sampled.wallTime,
+        monotonic_ns: input.sampled.monotonicNs.toString(),
+        process_id: input.clock.processId,
+        process_instance_id: input.clock.processInstanceId,
+        boot_id: input.clock.bootId,
+        previous_entry_sha256: input.previousSha256,
+        payload: input.payload,
+    });
+}
+function writeEntry(entry, schema, root) {
+    const normalized = validateEntry(entry, schema);
+    const bytes = canonicalJson(normalized);
+    if (bytes.byteLength > MAX_ENTRY_BYTES)
+        throw new Error(`run ledger entry exceeds ${MAX_ENTRY_BYTES} bytes`);
+    const ref = referenceFor(normalized, bytes);
+    const path = join(root.path, ref.file_name);
+    assertFileInside(root, path);
+    const status = writeImmutableFile(path, bytes);
+    return { status, stored: readReference(ref, schema, root) };
+}
+function readReference(ref, schema, root) {
+    const normalizedRef = validateReference(ref);
+    const path = join(root.path, normalizedRef.file_name);
+    assertFileInside(root, path);
+    const bytes = readImmutableFile(path, MAX_ENTRY_BYTES);
+    root.assertUnchanged();
+    if (sha256(bytes) !== normalizedRef.sha256)
+        throw new Error("run ledger entry digest mismatch");
+    const entry = validateEntry(parseJson(bytes), schema);
+    if (entry.entry_id !== normalizedRef.entry_id
+        || entry.run_id !== normalizedRef.run_id
+        || entry.sequence !== normalizedRef.sequence) {
+        throw new Error("run ledger reference does not match its entry");
+    }
+    return deepFreeze({ entry, ref: normalizedRef, bytes });
+}
+function readRun(runId, schema, root) {
+    root.assertUnchanged();
+    const directoryEntries = readdirSync(root.path, { withFileTypes: true })
+        .sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+    root.assertUnchanged();
+    const entries = [];
+    for (const directoryEntry of directoryEntries) {
+        if (!directoryEntry.name.endsWith(".json"))
+            continue;
+        root.assertUnchanged();
+        if (!directoryEntry.isFile())
+            throw new Error(`unsafe run ledger directory entry: ${directoryEntry.name}`);
+        const entryId = directoryEntry.name.slice(0, -".json".length);
+        if (!ENTRY_ID_PATTERN.test(entryId) || `${entryId}.json` !== directoryEntry.name) {
+            throw new Error(`invalid run ledger filename: ${directoryEntry.name}`);
+        }
+        const path = join(root.path, directoryEntry.name);
+        assertFileInside(root, path);
+        const bytes = readImmutableFile(path, MAX_ENTRY_BYTES);
+        root.assertUnchanged();
+        const entry = validateEntry(parseJson(bytes), schema);
+        if (entry.entry_id !== entryId)
+            throw new Error("run ledger filename does not match entry id");
+        if (entry.run_id === runId)
+            entries.push(deepFreeze({ entry, ref: referenceFor(entry, bytes), bytes }));
+    }
+    root.assertUnchanged();
+    entries.sort((left, right) => left.entry.sequence - right.entry.sequence);
+    return deepFreeze(entries);
+}
+function listStoredRunIds(schema, root) {
+    root.assertUnchanged();
+    const runIds = new Set();
+    for (const entry of readdirSync(root.path, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
+        if (!entry.name.endsWith(".json"))
+            continue;
+        if (!entry.isFile())
+            throw new Error(`unsafe run ledger directory entry: ${entry.name}`);
+        const bytes = readImmutableFile(join(root.path, entry.name), MAX_ENTRY_BYTES);
+        const parsed = validateEntry(parseJson(bytes), schema);
+        if (`${parsed.entry_id}.json` !== entry.name)
+            throw new Error("run ledger filename does not match entry id");
+        runIds.add(parsed.run_id);
+    }
+    const result = [...runIds].sort((left, right) => left.localeCompare(right));
+    for (const runId of result)
+        validateRun(readRun(runId, schema, root));
+    root.assertUnchanged();
+    return Object.freeze(result);
+}
+function validateRun(entries) {
+    if (entries.length === 0)
+        return;
+    const first = requiredFirst(entries);
+    if (first.entry.sequence !== 0 || first.entry.entry_kind !== "run-started") {
+        throw new Error("run ledger must begin with run-started at sequence zero");
+    }
+    validateStartPayload(first.entry);
+    const operationIds = new Set();
+    for (let index = 0; index < entries.length; index += 1) {
+        const current = entries[index];
+        if (!current)
+            throw new Error("run ledger entry is missing");
+        const previous = entries[index - 1];
+        if (current.entry.sequence !== index)
+            throw new Error("run ledger sequence is not contiguous");
+        if (current.entry.run_id !== first.entry.run_id)
+            throw new Error("run ledger contains another run id");
+        if (current.entry.run_kind !== first.entry.run_kind)
+            throw new Error("run kind changed within ledger");
+        if (current.entry.policy_sha256 !== first.entry.policy_sha256)
+            throw new Error("run policy changed within ledger");
+        if (current.entry.clock_class !== first.entry.clock_class)
+            throw new Error("run clock class changed within ledger");
+        if (current.entry.provenance_class !== first.entry.provenance_class) {
+            throw new Error("run ledger provenance class changed within ledger");
+        }
+        if (operationIds.has(current.entry.operation_id))
+            throw new Error("run ledger operation ids must be unique");
+        operationIds.add(current.entry.operation_id);
+        if (current.entry.previous_entry_sha256 !== (previous?.ref.sha256 ?? null)) {
+            throw new Error("run ledger hash chain is broken");
+        }
+        if (previous) {
+            if (timestampEpoch(current.entry.recorded_at) < timestampEpoch(previous.entry.recorded_at)) {
+                throw new Error("run ledger wall clock moved backwards");
+            }
+            if (current.entry.boot_id === previous.entry.boot_id
+                && BigInt(current.entry.monotonic_ns) <= BigInt(previous.entry.monotonic_ns)) {
+                throw new Error("run ledger system monotonic clock did not advance");
+            }
+            if (isTerminal(previous.entry.entry_kind))
+                throw new Error("run ledger contains entries after a terminal entry");
+        }
+        const expectedOperation = operationSha256({
+            entryKind: current.entry.entry_kind,
+            runId: current.entry.run_id,
+            runKind: current.entry.run_kind,
+            operationId: current.entry.operation_id,
+            policyDigest: current.entry.policy_sha256,
+            clockClass: current.entry.clock_class,
+            provenance: current.entry.provenance_class,
+            payload: current.entry.payload,
+        });
+        if (current.entry.operation_sha256 !== expectedOperation)
+            throw new Error("run ledger operation digest is invalid");
+        validateTrustedPayload(current.entry);
+    }
+    const terminal = entries.at(-1);
+    if (terminal?.entry.provenance_class === "trusted-live" && terminal.entry.entry_kind === "run-completed") {
+        const payload = terminal.entry.payload;
+        const expectedKind = assertCertifyingRunKind(payload.expected_run_kind);
+        const minimum = minimumDuration(expectedKind);
+        if (payload.minimum_duration_ms !== minimum)
+            throw new Error("terminal minimum duration is not policy-derived");
+        const digest = certificationDigest(entries.slice(0, -1), toObservation(terminal), assertResolvedAuthority(payload.authority), expectedKind, minimum, payload.previous_canary);
+        if (payload.metrics_sha256 !== digest)
+            throw new Error("terminal certification metrics digest is invalid");
+    }
+}
+function validateEntry(value, schema) {
+    assertSchema(value, schema, "run ledger entry");
+    const entry = value;
+    assertRunId(entry.run_id);
+    if (!ENTRY_ID_PATTERN.test(entry.entry_id))
+        throw new Error("invalid run ledger entry id");
+    assertOpaqueId(entry.operation_id, "run ledger operation id");
+    assertOpaqueId(entry.process_instance_id, "run ledger process instance id");
+    assertOpaqueId(entry.boot_id, "run ledger boot id");
+    assertSha256(entry.operation_sha256, "run ledger operation digest");
+    assertSha256(entry.policy_sha256, "run ledger policy digest");
+    if (entry.previous_entry_sha256 !== null)
+        assertSha256(entry.previous_entry_sha256, "previous run entry digest");
+    if (entry.entry_id !== createStableId("audit", entry.run_id, entry.operation_id)) {
+        throw new Error("run ledger entry id does not match its operation identity");
+    }
+    assertTimestamp(entry.recorded_at);
+    if (!Number.isSafeInteger(entry.process_id) || entry.process_id < 0)
+        throw new Error("invalid run ledger process id");
+    if (!Number.isSafeInteger(entry.sequence) || entry.sequence < 0)
+        throw new Error("invalid run ledger sequence");
+    assertJsonValue(entry.payload, "run ledger payload");
+    if (entry.entry_kind === "run-started")
+        validateStartPayload(entry);
+    const expectedOperation = operationSha256({
+        entryKind: entry.entry_kind,
+        runId: entry.run_id,
+        runKind: entry.run_kind,
+        operationId: entry.operation_id,
+        policyDigest: entry.policy_sha256,
+        clockClass: entry.clock_class,
+        provenance: entry.provenance_class,
+        payload: entry.payload,
+    });
+    if (entry.operation_sha256 !== expectedOperation)
+        throw new Error("run ledger operation digest is invalid");
+    return deepFreeze(structuredClone(entry));
+}
+function validateStartPayload(entry) {
+    if (entry.provenance_class === "audit") {
+        assertExactKeys(entry.payload, ["service_plan_digest", "ticket_set_digest"], "audit run-started payload");
+    }
+    else {
+        if (entry.clock_class !== "live")
+            throw new Error("trusted provenance requires a live clock");
+        assertExactKeys(entry.payload, [
+            "authority",
+            "previous_canary",
+            "service_plan_digest",
+            "ticket_set_digest",
+        ], "trusted run-started payload");
+        assertResolvedAuthority(entry.payload.authority);
+        if (entry.run_kind === "12h" && entry.payload.previous_canary !== null) {
+            throw new Error("12h canary must not depend on another canary");
+        }
+        if (entry.run_kind === "24h")
+            parseCertificationReference(entry.payload.previous_canary);
+        if (entry.run_kind === "until-empty")
+            throw new Error("until-empty runs cannot use trusted certification provenance");
+    }
+    assertSha256(entry.payload.ticket_set_digest, "run ticket set digest");
+    assertSha256(entry.payload.service_plan_digest, "run service plan digest");
+}
+function validateTrustedPayload(entry) {
+    if (entry.provenance_class !== "trusted-live")
+        return;
+    if (entry.clock_class !== "live")
+        throw new Error("trusted provenance requires a live clock");
+    switch (entry.entry_kind) {
+        case "run-started":
+            return;
+        case "heartbeat":
+            assertExactKeys(entry.payload, ["authority"], "trusted heartbeat payload");
+            assertResolvedAuthority(entry.payload.authority);
+            return;
+        case "process-restarted":
+            assertExactKeys(entry.payload, ["authority", "previous_process_instance_id"], "trusted restart payload");
+            assertResolvedAuthority(entry.payload.authority);
+            assertOpaqueId(entry.payload.previous_process_instance_id, "previous run process instance id");
+            return;
+        case "outbox-lock-recovered":
+            assertExactKeys(entry.payload, ["lock_recovery"], "trusted lock recovery entry payload");
+            if (!isRecord(entry.payload.lock_recovery))
+                throw new Error("trusted lock recovery payload must be an object");
+            return;
+        case "run-completed":
+            assertExactKeys(entry.payload, [
+                "authority",
+                "expected_run_kind",
+                "metrics_sha256",
+                "minimum_duration_ms",
+                "previous_canary",
+            ], "trusted run completion payload");
+            assertResolvedAuthority(entry.payload.authority);
+            assertCertifyingRunKind(entry.payload.expected_run_kind);
+            assertSha256(entry.payload.metrics_sha256, "certification metrics digest");
+            return;
+        default:
+            throw new Error(`entry kind cannot carry trusted certification provenance: ${entry.entry_kind}`);
+    }
+}
+function deriveMetrics(entries, certifying) {
+    const first = requiredFirst(entries);
+    const last = requiredLast(entries);
+    const observations = entries.map(toObservation);
+    const timeline = analyzeTimeline(observations);
+    const checkpoints = entries.filter((entry, index) => (index === 0 || entry.entry.entry_kind === "heartbeat" || index === entries.length - 1));
+    let maxHeartbeatGapMs = 0;
+    for (let index = 1; index < checkpoints.length; index += 1) {
+        const previous = checkpoints[index - 1];
+        const current = checkpoints[index];
+        if (previous && current) {
+            maxHeartbeatGapMs = Math.max(maxHeartbeatGapMs, timestampEpoch(current.entry.recorded_at) - timestampEpoch(previous.entry.recorded_at));
+        }
+    }
+    const terminal = last.entry.entry_kind;
+    const status = terminal === "run-completed" ? "completed" : terminal === "run-aborted" ? "aborted" : "running";
+    const metricsDigest = certifying
+        ? assertSha256(last.entry.payload.metrics_sha256, "certification metrics digest")
+        : sha256(canonicalJson({
+            clock_class: first.entry.clock_class,
+            elapsed_ms: timeline.elapsedMs,
+            entry_count: entries.length,
+            head_sha256: last.ref.sha256,
+            monotonic_elapsed_ms: timeline.monotonicElapsedMs,
+            policy_sha256: first.entry.policy_sha256,
+            restart_continuity_valid: timeline.restartContinuityValid,
+            run_id: first.entry.run_id,
+            run_kind: first.entry.run_kind,
+            status,
+        }));
+    return deepFreeze({
+        run_id: first.entry.run_id,
+        run_kind: first.entry.run_kind,
+        policy_sha256: first.entry.policy_sha256,
+        clock_class: first.entry.clock_class,
+        certifying,
+        status,
+        started_at: first.entry.recorded_at,
+        ended_at: status === "running" ? null : last.entry.recorded_at,
+        elapsed_ms: timeline.elapsedMs,
+        monotonic_elapsed_ms: timeline.monotonicElapsedMs,
+        entry_count: entries.length,
+        heartbeat_count: countKind(entries, "heartbeat"),
+        max_heartbeat_gap_ms: maxHeartbeatGapMs,
+        recovery_count: countKind(entries, "lease-recovered")
+            + countKind(entries, "controller-lock-recovered")
+            + countKind(entries, "outbox-lock-recovered"),
+        quota_park_count: countKind(entries, "quota-parked"),
+        quota_resume_count: countKind(entries, "quota-resumed"),
+        restart_count: timeline.restartCount,
+        restart_continuity_valid: timeline.restartContinuityValid,
+        metrics_sha256: metricsDigest,
+        process_instance_ids: timeline.processInstanceIds,
+        ticket_set_digest: assertSha256(first.entry.payload.ticket_set_digest, "run ticket set digest"),
+        service_plan_digest: assertSha256(first.entry.payload.service_plan_digest, "run service plan digest"),
+        head: last.ref,
+    });
+}
+export function analyzeRunContinuity(samples) {
+    const captured = samples.map((sample, sequence) => ({
+        entry_id: `sample-${sequence}`,
+        sequence,
+        entry_kind: assertTimelineEntryKind(sample.entryKind),
+        operation_id: `sample-${sequence}`,
+        recorded_at: assertTimestamp(sample.recordedAt),
+        monotonic_ns: assertMonotonicNs(sample.monotonicNs),
+        process_instance_id: assertOpaqueId(sample.processInstanceId, "run continuity process instance id"),
+        boot_id: assertOpaqueId(sample.bootId, "run continuity boot id"),
+    }));
+    return analyzeTimeline(captured);
+}
+function analyzeTimeline(entries) {
+    const first = entries[0];
+    const last = entries.at(-1);
+    if (!first || !last)
+        throw new Error("cannot analyze an empty run timeline");
+    const processIds = [first.process_instance_id];
+    const seen = new Set(processIds);
+    let monotonicElapsedMs = 0;
+    let restartCount = 0;
+    let valid = true;
+    for (let index = 1; index < entries.length; index += 1) {
+        const previous = entries[index - 1];
+        const current = entries[index];
+        if (!previous || !current)
+            continue;
+        const changed = current.process_instance_id !== previous.process_instance_id;
+        const delta = BigInt(current.monotonic_ns) - BigInt(previous.monotonic_ns);
+        if (current.boot_id !== previous.boot_id || delta <= 0n)
+            valid = false;
+        if (changed) {
+            restartCount += 1;
+            const gap = timestampEpoch(current.recorded_at) - timestampEpoch(previous.recorded_at);
+            if (current.entry_kind !== "process-restarted"
+                || gap < 0
+                || gap > MAX_RESTART_GAP_MS
+                || seen.has(current.process_instance_id)) {
+                valid = false;
+            }
+            seen.add(current.process_instance_id);
+            processIds.push(current.process_instance_id);
+        }
+        else {
+            if (current.entry_kind === "process-restarted")
+                valid = false;
+        }
+    }
+    if (entries.every((entry) => entry.boot_id === first.boot_id)) {
+        const totalMonotonic = BigInt(last.monotonic_ns) - BigInt(first.monotonic_ns);
+        if (totalMonotonic > 0n)
+            monotonicElapsedMs = Number(totalMonotonic / 1000000n);
+    }
+    return deepFreeze({
+        elapsedMs: timestampEpoch(last.recorded_at) - timestampEpoch(first.recorded_at),
+        monotonicElapsedMs,
+        restartCount,
+        restartContinuityValid: valid,
+        processInstanceIds: processIds,
+    });
+}
+function certificationDigest(entriesBeforeTerminal, terminal, authority, expectedRunKind, minimumDurationMs, previousCanary) {
+    const first = requiredFirst(entriesBeforeTerminal);
+    const observations = [...entriesBeforeTerminal.map(toObservation), terminal];
+    const timeline = analyzeTimeline(observations);
+    return sha256(canonicalJson({
+        authority,
+        boot_ids: [...new Set(observations.map((entry) => entry.boot_id))],
+        ended_at: terminal.recorded_at,
+        entry_count: observations.length,
+        expected_run_kind: expectedRunKind,
+        heartbeat_count: entriesBeforeTerminal.filter((entry) => entry.entry.entry_kind === "heartbeat").length,
+        monotonic_elapsed_ms: timeline.monotonicElapsedMs,
+        minimum_duration_ms: minimumDurationMs,
+        policy_sha256: first.entry.policy_sha256,
+        previous_canary: previousCanary,
+        process_instance_ids: timeline.processInstanceIds,
+        restart_continuity_valid: timeline.restartContinuityValid,
+        restart_count: timeline.restartCount,
+        run_id: first.entry.run_id,
+        service_plan_digest: first.entry.payload.service_plan_digest,
+        started_at: first.entry.recorded_at,
+        terminal_entry_id: terminal.entry_id,
+        terminal_operation_id: terminal.operation_id,
+        terminal_previous_entry_sha256: requiredLast(entriesBeforeTerminal).ref.sha256,
+        ticket_set_digest: first.entry.payload.ticket_set_digest,
+        wall_elapsed_ms: timeline.elapsedMs,
+    }));
+}
+function prospectiveObservation(entries, operationId, entryKind, sampled, clock) {
+    const first = requiredFirst(entries);
+    return deepFreeze({
+        entry_id: createStableId("audit", first.entry.run_id, operationId),
+        sequence: requiredLast(entries).entry.sequence + 1,
+        entry_kind: entryKind,
+        operation_id: operationId,
+        recorded_at: sampled.wallTime,
+        monotonic_ns: sampled.monotonicNs.toString(),
+        process_instance_id: clock.processInstanceId,
+        boot_id: clock.bootId,
+    });
+}
+function toObservation(stored) {
+    const entry = stored.entry;
+    return deepFreeze({
+        entry_id: entry.entry_id,
+        sequence: entry.sequence,
+        entry_kind: entry.entry_kind,
+        operation_id: entry.operation_id,
+        recorded_at: entry.recorded_at,
+        monotonic_ns: entry.monotonic_ns,
+        process_instance_id: entry.process_instance_id,
+        boot_id: entry.boot_id,
+    });
+}
+function assertMinimumDuration(timeline, minimumMs) {
+    if (!timeline.restartContinuityValid)
+        throw new Error("run restart continuity is not certifiable");
+    if (timeline.elapsedMs < minimumMs)
+        throw new Error("run wall duration is below its certification minimum");
+    if (timeline.monotonicElapsedMs < minimumMs) {
+        throw new Error("run monotonic segment duration is below its certification minimum");
+    }
+}
+function findReplay(entries, operationId, operationDigest, clockClass, provenance) {
+    const existing = entries.find((entry) => entry.entry.operation_id === operationId);
+    if (!existing)
+        return undefined;
+    if (existing.entry.operation_sha256 !== operationDigest)
+        throw new RunLedgerConflictError(operationId);
+    if (existing.entry.clock_class !== clockClass || existing.entry.provenance_class !== provenance) {
+        throw new Error("run ledger operation cannot be replayed through another clock or provenance class");
+    }
+    return existing;
+}
+function operationSha256(input) {
+    return sha256(canonicalJson({
+        clock_class: input.clockClass,
+        entry_kind: input.entryKind,
+        operation_id: input.operationId,
+        payload: input.payload,
+        policy_sha256: input.policyDigest,
+        provenance_class: input.provenance,
+        run_id: input.runId,
+        run_kind: input.runKind,
+    }));
+}
+function referenceFor(entry, bytes) {
+    return deepFreeze({
+        entry_id: entry.entry_id,
+        run_id: entry.run_id,
+        sequence: entry.sequence,
+        sha256: sha256(bytes),
+        file_name: `${entry.entry_id}.json`,
+    });
+}
+function captureReference(value) {
+    const captured = {
+        entry_id: value.entry_id,
+        run_id: value.run_id,
+        sequence: value.sequence,
+        sha256: value.sha256,
+        file_name: value.file_name,
+    };
+    return validateReference(captured);
+}
+function validateReference(value) {
+    if (!isRecord(value))
+        throw new Error("run ledger reference must be an object");
+    const entryId = value.entry_id;
+    const runId = value.run_id;
+    if (typeof entryId !== "string" || !ENTRY_ID_PATTERN.test(entryId))
+        throw new Error("invalid run ledger reference entry id");
+    assertRunId(runId);
+    if (!Number.isSafeInteger(value.sequence) || value.sequence < 0)
+        throw new Error("invalid run ledger reference sequence");
+    assertSha256(value.sha256, "run ledger reference digest");
+    if (value.file_name !== `${entryId}.json`)
+        throw new Error("invalid run ledger reference filename");
+    return deepFreeze({ entry_id: entryId, run_id: runId, sequence: value.sequence, sha256: value.sha256, file_name: value.file_name });
+}
+function captureStartInput(input) {
+    return {
+        operationId: input.operationId,
+        runKind: input.runKind,
+        policyDigest: input.policyDigest,
+        ticketSetDigest: input.ticketSetDigest,
+        servicePlanDigest: input.servicePlanDigest,
+    };
+}
+function captureStartLiveInput(input) {
+    return {
+        operationId: input.operationId,
+        runKind: input.runKind,
+        policyDigest: input.policyDigest,
+        ticketSetDigest: input.ticketSetDigest,
+        servicePlanDigest: input.servicePlanDigest,
+        source: captureAuthorityReference(input.source),
+        previousCanary: input.previousCanary,
+    };
+}
+function captureAppendInput(input) {
+    return {
+        runId: input.runId,
+        operationId: input.operationId,
+        entryKind: input.entryKind,
+        payload: input.payload,
+    };
+}
+function captureAppendAtHeadInput(input) {
+    return {
+        ...captureAppendInput(input),
+        expectedHeadSha256: assertSha256(input.expectedHeadSha256, "expected run head digest"),
+    };
+}
+function captureLiveEventInput(input) {
+    return {
+        runId: assertRunId(input.runId),
+        operationId: assertOpaqueId(input.operationId, "run entry operation id"),
+        source: captureAuthorityReference(input.source),
+    };
+}
+function captureCompleteInput(input) {
+    return {
+        ...captureLiveEventInput(input),
+        expectedRunKind: assertCertifyingRunKind(input.expectedRunKind),
+    };
+}
+function captureAuthorityReference(input) {
+    assertRunCertificationAuthorityReference(input);
+    return input;
+}
+function captureCertificationReference(input) {
+    const captured = {
+        run_id: input.run_id,
+        head: captureReference(input.head),
+        metrics_sha256: input.metrics_sha256,
+    };
+    assertRunId(captured.run_id);
+    if (captured.head.run_id !== captured.run_id)
+        throw new Error("canary reference head belongs to another run");
+    assertSha256(captured.metrics_sha256, "canary metrics digest");
+    return deepFreeze(captured);
+}
+function serializeCertificationReference(input) {
+    return deepFreeze({
+        head: {
+            entry_id: input.head.entry_id,
+            file_name: input.head.file_name,
+            run_id: input.head.run_id,
+            sequence: input.head.sequence,
+            sha256: input.head.sha256,
+        },
+        metrics_sha256: input.metrics_sha256,
+        run_id: input.run_id,
+    });
+}
+function parseCertificationReference(value) {
+    if (!isRecord(value) || !isRecord(value.head))
+        throw new Error("invalid prior canary reference");
+    assertExactKeys(value, ["head", "metrics_sha256", "run_id"], "prior canary reference");
+    const head = value.head;
+    assertExactKeys(head, ["entry_id", "file_name", "run_id", "sequence", "sha256"], "prior canary head reference");
+    return captureCertificationReference({
+        run_id: value.run_id,
+        metrics_sha256: value.metrics_sha256,
+        head: {
+            entry_id: head.entry_id,
+            file_name: head.file_name,
+            run_id: head.run_id,
+            sequence: head.sequence,
+            sha256: head.sha256,
+        },
+    });
+}
+function assertResolvedAuthority(value) {
+    if (!isRecord(value))
+        throw new Error("trusted authority payload must be an object");
+    assertExactKeys(value, [
+        "authorized_by",
+        "binding",
+        "decision_id",
+        "event_sha256",
+        "occurred_at",
+        "processed_at",
+        "receipt_sha256",
+        "reference",
+    ], "trusted authority payload");
+    if (!isRecord(value.reference) || !isRecord(value.binding))
+        throw new Error("trusted authority references are invalid");
+    assertExactKeys(value.reference, ["consumer_id", "event_id"], "trusted authority reference");
+    if (value.reference.consumer_id !== "run-ledger-authority")
+        throw new Error("invalid trusted authority consumer");
+    const binding = value.binding;
+    assertExactKeys(binding, [
+        "action",
+        "completion_semantics",
+        "expected_head",
+        "operation_id",
+        "policy_sha256",
+        "previous_canary",
+        "run_id",
+        "run_kind",
+        "schema_version",
+        "service_plan_digest",
+        "ticket_set_digest",
+    ], "trusted authority binding");
+    const action = binding.action;
+    if (action !== "start" && action !== "heartbeat" && action !== "process-restart" && action !== "complete") {
+        throw new Error("invalid trusted authority action");
+    }
+    const expectedSemantics = action === "start"
+        ? "begin-run"
+        : action === "heartbeat"
+            ? "append-heartbeat"
+            : action === "process-restart"
+                ? "record-process-restart"
+                : "terminal-run-completed";
+    if (binding.schema_version !== 1 || binding.completion_semantics !== expectedSemantics) {
+        throw new Error("trusted authority completion semantics changed");
+    }
+    assertRunId(binding.run_id);
+    assertOpaqueId(binding.operation_id, "authorized run operation id");
+    assertCertifyingRunKind(binding.run_kind);
+    assertSha256(binding.policy_sha256, "authorized run policy digest");
+    assertSha256(binding.ticket_set_digest, "authorized ticket set digest");
+    assertSha256(binding.service_plan_digest, "authorized service plan digest");
+    if (binding.expected_head !== null) {
+        if (!isRecord(binding.expected_head))
+            throw new Error("invalid trusted authority expected head");
+        validateReference(binding.expected_head);
+    }
+    if (binding.previous_canary !== null)
+        parseCertificationReference(binding.previous_canary);
+    assertOpaqueId(value.reference.event_id, "authority event id");
+    assertOpaqueId(value.decision_id, "authority decision id");
+    assertActorId(value.authorized_by, "authority actor");
+    assertSha256(value.event_sha256, "authority event digest");
+    assertSha256(value.receipt_sha256, "authority receipt digest");
+    assertTimestamp(value.occurred_at);
+    assertTimestamp(value.processed_at);
+    return deepFreeze(structuredClone(value));
+}
+function assertAuthorityAfterHead(authority, head) {
+    if (timestampEpoch(authority.occurred_at) < timestampEpoch(head.recorded_at)) {
+        throw new Error("live transition authority predates the canonical trusted head");
+    }
+}
+function assertAuthorityPrecedesEntry(authority, entry) {
+    if (timestampEpoch(authority.processed_at) > timestampEpoch(entry.recorded_at)) {
+        throw new Error("live transition was recorded before its authority receipt");
+    }
+}
+function countKind(entries, kind) {
+    return entries.filter((entry) => entry.entry.entry_kind === kind).length;
+}
+function result(status, stored) {
+    return deepFreeze({ status, ref: stored.ref, entry: stored.entry });
+}
+function requiredFirst(entries) {
+    const first = entries[0];
+    if (!first)
+        throw new Error("run ledger does not exist");
+    return first;
+}
+function requiredLast(entries) {
+    const last = entries.at(-1);
+    if (!last)
+        throw new Error("run ledger does not exist");
+    return last;
+}
+function runLockId(runId) {
+    return assertLockId(`run-${assertRunId(runId)}`, "run ledger lock id");
+}
+function minimumDuration(kind) {
+    return kind === "12h" ? TWELVE_HOURS_MS : TWENTY_FOUR_HOURS_MS;
+}
+function assertRunId(value) {
+    if (typeof value !== "string" || !RUN_ID_PATTERN.test(value))
+        throw new Error("invalid run id");
+    return value;
+}
+function assertRunKind(value) {
+    if (value !== "12h" && value !== "24h" && value !== "until-empty")
+        throw new Error("invalid run kind");
+    return value;
+}
+function assertCertifyingRunKind(value) {
+    if (value !== "12h" && value !== "24h")
+        throw new Error("invalid certifying run kind");
+    return value;
+}
+function assertAppendEntryKind(value) {
+    const kinds = [
+        "heartbeat",
+        "session-started",
+        "session-stopped",
+        "session-stalled",
+        "process-restarted",
+        "ticket-transition",
+        "quota-parked",
+        "quota-resumed",
+        "lease-recovered",
+        "controller-lock-recovered",
+        "outbox-lock-recovered",
+        "live-call-observed",
+        "run-completed",
+        "run-aborted",
+    ];
+    if (!kinds.includes(value))
+        throw new Error("invalid append run entry kind");
+    return value;
+}
+function assertTimelineEntryKind(value) {
+    return value === "run-started" ? value : assertAppendEntryKind(value);
+}
+function assertMonotonicNs(value) {
+    if (typeof value !== "string" || !/^(?:0|[1-9][0-9]*)$/.test(value)) {
+        throw new Error("invalid run continuity monotonic time");
+    }
+    return value;
+}
+function isTerminal(kind) {
+    return kind === "run-completed" || kind === "run-aborted";
+}
+function sameReference(left, right) {
+    return left.entry_id === right.entry_id
+        && left.run_id === right.run_id
+        && left.sequence === right.sequence
+        && left.sha256 === right.sha256
+        && left.file_name === right.file_name;
+}
+function sampleClock(clock) {
+    const sample = clock.sample();
+    if (!isRecord(sample))
+        throw new Error("run ledger clock sample must be an object");
+    const wallTime = assertTimestamp(sample.wallTime);
+    if (typeof sample.monotonicNs !== "bigint" || sample.monotonicNs < 0n) {
+        throw new Error("run ledger monotonic clock must be a non-negative bigint");
+    }
+    return { wallTime, monotonicNs: sample.monotonicNs };
+}
+function assertClockAdvances(previous, sampled, clock) {
+    if (timestampEpoch(sampled.wallTime) < timestampEpoch(previous.recorded_at)) {
+        throw new Error("run ledger wall clock moved backwards");
+    }
+    if (previous.boot_id === clock.bootId && sampled.monotonicNs <= BigInt(previous.monotonic_ns)) {
+        throw new Error("run ledger system monotonic clock did not advance");
+    }
+}
+function assertExactKeys(value, expected, label) {
+    const actual = Object.keys(value).sort();
+    const sortedExpected = [...expected].sort();
+    if (actual.length !== sortedExpected.length || actual.some((key, index) => key !== sortedExpected[index])) {
+        throw new Error(`${label} has invalid fields`);
+    }
+}
+function assertSha256(value, label) {
+    if (typeof value !== "string" || !SHA256_PATTERN.test(value))
+        throw new Error(`invalid ${label}`);
+    return value;
+}
+function assertTimestamp(value) {
+    if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value)) {
+        throw new Error("invalid run ledger timestamp");
+    }
+    const epoch = Date.parse(value);
+    if (!Number.isFinite(epoch) || new Date(epoch).toISOString() !== value)
+        throw new Error("invalid run ledger timestamp");
+    return value;
+}
+function timestampEpoch(value) {
+    assertTimestamp(value);
+    return Date.parse(value);
+}
+function canonicalJson(value) {
+    return Buffer.from(`${JSON.stringify(canonicalizeJson(value), null, 2)}\n`, "utf8");
+}
+function canonicalizeObject(value, label) {
+    const canonical = canonicalizeJson(value, label);
+    if (!isRecord(canonical) || Array.isArray(canonical))
+        throw new Error(`${label} must be an object`);
+    return canonical;
+}
+function canonicalizeJson(value, label = "JSON value", seen = new Set(), depth = 0) {
+    if (depth > 32)
+        throw new Error(`${label} exceeds maximum nesting depth`);
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new Error(`${label} contains a non-finite number`);
+        return value;
+    }
+    if (Array.isArray(value)) {
+        if (seen.has(value))
+            throw new Error(`${label} contains a cycle`);
+        seen.add(value);
+        const result = value.map((item) => canonicalizeJson(item, label, seen, depth + 1));
+        seen.delete(value);
+        return result;
+    }
+    if (!isRecord(value))
+        throw new Error(`${label} contains a non-JSON value`);
+    if (seen.has(value))
+        throw new Error(`${label} contains a cycle`);
+    seen.add(value);
+    const result = {};
+    for (const key of Object.keys(value).sort()) {
+        const child = value[key];
+        if (child === undefined)
+            throw new Error(`${label} contains undefined`);
+        result[key] = canonicalizeJson(child, label, seen, depth + 1);
+    }
+    seen.delete(value);
+    return result;
+}
+function assertJsonValue(value, label) {
+    canonicalizeJson(value, label);
+}
+function parseJson(bytes) {
+    try {
+        return JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        throw new Error("run ledger entry contains invalid JSON");
+    }
+}
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function sameJson(left, right) {
+    try {
+        return canonicalJson(left).equals(canonicalJson(right));
+    }
+    catch {
+        return false;
+    }
+}
+function deepFreeze(value, seen = new Set()) {
+    if (typeof value !== "object" || value === null || seen.has(value))
+        return value;
+    if (ArrayBuffer.isView(value))
+        return value;
+    seen.add(value);
+    for (const child of Object.values(value))
+        deepFreeze(child, seen);
+    return Object.freeze(value);
+}
+//# sourceMappingURL=run-ledger.js.map