@deftai/directive-core 0.95.0 → 0.97.0

package/dist/delivery-attempt/ledger.js

@@ -0,0 +1,758 @@
+/**
+ * Durable delivery-attempt unit ledger (#3143).
+ *
+ * Persists under `.deft/delivery-attempts/` so counters survive worker
+ * replacement, session restart, context compaction, and new revisions.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, unlinkSync, } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { ContainedWriteError, ContainedWriteErrorCode, containedWrite, } from "../fs/contained-write.js";
+import { assertWriteTargetSafe } from "../fs/projection-containment.js";
+import { DELIVERY_ATTEMPT_DIR, DELIVERY_ATTEMPT_SCHEMA_VERSION, deliveryUnitKey, utcIso, } from "./types.js";
+export function deliveryAttemptsDir(projectRoot) {
+    return join(projectRoot, ...DELIVERY_ATTEMPT_DIR.split("/"));
+}
+/**
+ * Stable collision-resistant filename for a unit key.
+ * Full SHA-256 hex (64 chars) — do not truncate base64 of the raw key (#3143 P1).
+ */
+export function unitLedgerFilename(scopeId, targetId, workflowId) {
+    const key = deliveryUnitKey(scopeId, targetId, workflowId);
+    const digest = createHash("sha256").update(key, "utf8").digest("hex");
+    return `${digest}.json`;
+}
+export function unitLedgerPath(projectRoot, scopeId, targetId, workflowId) {
+    return join(deliveryAttemptsDir(projectRoot), unitLedgerFilename(scopeId, targetId, workflowId));
+}
+export function newAttemptId(prefix = "att") {
+    return `${prefix}-${randomBytes(8).toString("hex")}`;
+}
+export function emptyUnitLedger(input) {
+    return {
+        schemaVersion: DELIVERY_ATTEMPT_SCHEMA_VERSION,
+        scopeId: input.scopeId,
+        targetId: input.targetId,
+        workflowId: input.workflowId,
+        phaseId: input.phaseId ?? "default",
+        attempts: [],
+        failedAttemptCount: 0,
+        sameFailureCounts: {},
+        totalElapsedSeconds: 0,
+        totalToolCallCount: 0,
+        totalHostTokenCount: null,
+        lastFailure: null,
+        lastMaterialDelta: [],
+        lastSourceRevision: null,
+        blockedDecision: null,
+        resumeCondition: null,
+        override: null,
+        updatedAt: utcIso(input.now),
+    };
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function readString(rec, key) {
+    const v = rec[key];
+    return typeof v === "string" && v.trim().length > 0 ? v.trim() : null;
+}
+function readNumber(rec, key) {
+    const v = rec[key];
+    return typeof v === "number" && Number.isFinite(v) ? v : null;
+}
+/**
+ * Parse a unit ledger from JSON. Returns null when required fields are invalid.
+ */
+export function parseUnitLedger(raw) {
+    if (!isRecord(raw))
+        return null;
+    const scopeId = readString(raw, "scopeId");
+    const targetId = readString(raw, "targetId");
+    const workflowId = readString(raw, "workflowId");
+    if (scopeId === null || targetId === null || workflowId === null)
+        return null;
+    const attemptsRaw = Array.isArray(raw.attempts) ? raw.attempts : [];
+    const attempts = [];
+    for (const a of attemptsRaw) {
+        const parsed = parseAttempt(a);
+        if (parsed !== null)
+            attempts.push(parsed);
+    }
+    const sameFailureCounts = {};
+    if (isRecord(raw.sameFailureCounts)) {
+        for (const [k, v] of Object.entries(raw.sameFailureCounts)) {
+            if (typeof v === "number" && Number.isFinite(v) && v >= 0) {
+                sameFailureCounts[k] = Math.floor(v);
+            }
+        }
+    }
+    return {
+        schemaVersion: DELIVERY_ATTEMPT_SCHEMA_VERSION,
+        scopeId,
+        targetId,
+        workflowId,
+        phaseId: readString(raw, "phaseId") ?? "default",
+        attempts,
+        failedAttemptCount: Math.max(0, Math.floor(readNumber(raw, "failedAttemptCount") ?? 0)),
+        sameFailureCounts,
+        totalElapsedSeconds: Math.max(0, Math.floor(readNumber(raw, "totalElapsedSeconds") ?? 0)),
+        totalToolCallCount: Math.max(0, Math.floor(readNumber(raw, "totalToolCallCount") ?? 0)),
+        totalHostTokenCount: raw.totalHostTokenCount === null || raw.totalHostTokenCount === undefined
+            ? null
+            : Math.max(0, Math.floor(readNumber(raw, "totalHostTokenCount") ?? 0)),
+        lastFailure: parseFailure(raw.lastFailure),
+        lastMaterialDelta: parseMaterialDeltas(raw.lastMaterialDelta),
+        lastSourceRevision: readString(raw, "lastSourceRevision"),
+        blockedDecision: readString(raw, "blockedDecision") ?? null,
+        resumeCondition: parseResume(raw.resumeCondition),
+        override: parseOverride(raw.override),
+        updatedAt: readString(raw, "updatedAt") ?? utcIso(),
+    };
+}
+function parseFailure(raw) {
+    if (!isRecord(raw))
+        return null;
+    const stage = readString(raw, "stage");
+    const fingerprint = readString(raw, "fingerprint");
+    const retryability = readString(raw, "retryability");
+    if (stage === null || fingerprint === null || retryability === null)
+        return null;
+    if (retryability !== "transient" &&
+        retryability !== "deterministic" &&
+        retryability !== "unknown") {
+        return null;
+    }
+    return {
+        stage,
+        code: readString(raw, "code"),
+        fingerprint,
+        retryability,
+        resourceClass: readString(raw, "resourceClass"),
+    };
+}
+function parseMaterialDeltas(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const item of raw) {
+        if (!isRecord(item))
+            continue;
+        const kind = readString(item, "kind");
+        const sourceRevision = readString(item, "sourceRevision");
+        if (kind === null || sourceRevision === null)
+            continue;
+        const addresses = Array.isArray(item.addresses)
+            ? item.addresses.filter((x) => typeof x === "string")
+            : [];
+        out.push({
+            kind: kind,
+            addresses,
+            sourceRevision,
+            note: readString(item, "note"),
+        });
+    }
+    return out;
+}
+function parseAttempt(raw) {
+    if (!isRecord(raw))
+        return null;
+    const attemptId = readString(raw, "attemptId");
+    const sourceRevision = readString(raw, "sourceRevision");
+    const trigger = readString(raw, "trigger");
+    const status = readString(raw, "status");
+    const startedAt = readString(raw, "startedAt");
+    if (attemptId === null ||
+        sourceRevision === null ||
+        trigger === null ||
+        status === null ||
+        startedAt === null) {
+        return null;
+    }
+    return {
+        attemptId,
+        sourceRevision,
+        trigger,
+        status,
+        failure: parseFailure(raw.failure),
+        materialDelta: parseMaterialDeltas(raw.materialDelta),
+        startedAt,
+        endedAt: readString(raw, "endedAt"),
+        elapsedSeconds: Math.max(0, Math.floor(readNumber(raw, "elapsedSeconds") ?? 0)),
+        toolCallCount: Math.max(0, Math.floor(readNumber(raw, "toolCallCount") ?? 0)),
+        hostTokenCount: raw.hostTokenCount === null || raw.hostTokenCount === undefined
+            ? null
+            : Math.max(0, Math.floor(readNumber(raw, "hostTokenCount") ?? 0)),
+        workerId: readString(raw, "workerId"),
+        externalRunId: readString(raw, "externalRunId"),
+    };
+}
+function parseResume(raw) {
+    if (!isRecord(raw))
+        return null;
+    const kind = readString(raw, "kind");
+    const description = readString(raw, "description");
+    if (kind === null || description === null)
+        return null;
+    return {
+        kind: kind,
+        description,
+        satisfied: raw.satisfied === true,
+    };
+}
+function parseOverride(raw) {
+    if (!isRecord(raw))
+        return null;
+    const overrideId = readString(raw, "overrideId");
+    const actor = readString(raw, "actor");
+    const rationale = readString(raw, "rationale");
+    const recordedAt = readString(raw, "recordedAt");
+    if (overrideId === null || actor === null || rationale === null || recordedAt === null) {
+        return null;
+    }
+    return {
+        overrideId,
+        actor,
+        rationale,
+        recordedAt,
+        allowedAttempts: Math.max(1, Math.floor(readNumber(raw, "allowedAttempts") ?? 1)),
+        expiresAt: readString(raw, "expiresAt"),
+        remainingAttempts: Math.max(0, Math.floor(readNumber(raw, "remainingAttempts") ?? 0)),
+    };
+}
+function writeJsonContained(projectRoot, targetPath, payload) {
+    const root = resolve(projectRoot);
+    const abs = resolve(targetPath);
+    assertWriteTargetSafe(root, abs);
+    mkdirSync(dirname(abs), { recursive: true });
+    const dir = dirname(abs);
+    const tmpBase = `.${basename(abs)}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    const tmp = join(dir, tmpBase);
+    try {
+        containedWrite({
+            root,
+            target: tmp,
+            data: `${JSON.stringify(payload, null, 2)}\n`,
+            mode: "create",
+        });
+        renameSync(tmp, abs);
+    }
+    catch (err) {
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch {
+            /* best-effort */
+        }
+        throw err;
+    }
+}
+/**
+ * Load unit ledger distinguishing missing vs corrupt.
+ * Corrupt persisted state MUST NOT be treated as a new empty unit (fail-closed).
+ */
+export function loadUnitLedgerResult(projectRoot, scopeId, targetId, workflowId) {
+    const path = unitLedgerPath(projectRoot, scopeId, targetId, workflowId);
+    if (!existsSync(path))
+        return { status: "missing" };
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        const ledger = parseUnitLedger(raw);
+        if (ledger === null) {
+            return { status: "corrupt", detail: `invalid ledger schema at ${path}` };
+        }
+        return { status: "ok", ledger };
+    }
+    catch (err) {
+        return {
+            status: "corrupt",
+            detail: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/**
+ * Load unit ledger from disk, or null if missing.
+ * Throws when the file exists but is corrupt (fail-closed circuit breaker).
+ */
+export function loadUnitLedger(projectRoot, scopeId, targetId, workflowId) {
+    const result = loadUnitLedgerResult(projectRoot, scopeId, targetId, workflowId);
+    if (result.status === "missing")
+        return null;
+    if (result.status === "corrupt") {
+        throw new Error(`delivery-attempt ledger corrupt for ${scopeId}/${targetId}/${workflowId}: ${result.detail}`);
+    }
+    return result.ledger;
+}
+/** Persist unit ledger atomically under project root. */
+export function saveUnitLedger(projectRoot, ledger) {
+    const path = unitLedgerPath(projectRoot, ledger.scopeId, ledger.targetId, ledger.workflowId);
+    writeJsonContained(projectRoot, path, ledger);
+}
+/**
+ * Exclusive unit lock for begin/complete on disk (#3143 concurrent-snapshot P1).
+ * Uses O_EXCL create of a lock file under the delivery-attempts dir.
+ */
+/** @deprecated Kept for API stability; live PIDs are never time-reclaimed. */
+export const UNIT_LOCK_STALE_MS = 5 * 60 * 1000;
+function isProcessAlive(pid) {
+    if (!Number.isFinite(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        // ESRCH → no such process (dead). EPERM → process exists but this user
+        // cannot signal it — treat as alive so we never reclaim a live foreign lock.
+        if (code === "EPERM")
+            return true;
+        return false;
+    }
+}
+function readLockRecord(lockPath) {
+    try {
+        const raw = JSON.parse(readFileSync(lockPath, "utf8"));
+        if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+            return null;
+        const rec = raw;
+        const pid = typeof rec.pid === "number" ? rec.pid : Number.NaN;
+        const token = typeof rec.token === "string" ? rec.token : "";
+        const startedAt = typeof rec.startedAt === "string" ? rec.startedAt : "";
+        if (!Number.isFinite(pid) || token.length === 0)
+            return null;
+        return { pid, token, startedAt };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether an existing lock may be reclaimed.
+ *
+ * **Live owner PID is never reclaimed** — including long critical sections and
+ * event-loop stalls. Only dead owners and corrupt/unreadable records are
+ * reclaimable. PID-reuse residual (dead owner, OS recycled the number onto an
+ * unrelated live process) requires manual `.lock` deletion.
+ */
+export function isUnitLockReclaimable(rec) {
+    if (rec === null)
+        return true;
+    return !isProcessAlive(rec.pid);
+}
+/**
+ * Exclusive lock create via containedWrite mode=create (O_EXCL under root).
+ * Maps CONTAINED_WRITE_EXISTS → EEXIST so reclaim callers keep errno checks.
+ */
+function writeLockExclusive(projectRoot, path, record) {
+    try {
+        containedWrite({
+            root: resolve(projectRoot),
+            target: path,
+            data: `${JSON.stringify(record)}\n`,
+            mode: "create",
+        });
+    }
+    catch (err) {
+        if (err instanceof ContainedWriteError && err.code === ContainedWriteErrorCode.EXISTS) {
+            const e = new Error(`EEXIST: file already exists, open '${path}'`);
+            e.code = "EEXIST";
+            e.path = path;
+            throw e;
+        }
+        throw err;
+    }
+}
+function unlinkIfOurs(path, token, pid) {
+    const rec = readLockRecord(path);
+    if (rec !== null && rec.token === token && rec.pid === pid) {
+        try {
+            unlinkSync(path);
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+}
+/**
+ * Acquire exclusive unit lock.
+ *
+ * Create is atomic: `containedWrite(..., mode: "create")` (O_EXCL) writes the
+ * owner record in the exclusive create (no empty-file window).
+ *
+ * Recovery when EEXIST (dead owner or corrupt record only):
+ * 1. Take an exclusive **reclaim ticket** (`*.lock.reclaim`) with create mode.
+ * 2. Under that ticket, re-read the lock; only unlink if still reclaimable
+ *    (owner still dead / corrupt). Live PIDs are never unlinked.
+ * 3. Create the replacement lock with create mode, then drop the ticket.
+ *
+ * The ticket serializes reclaimers so a delayed contender cannot unlink a
+ * live replacement lock.
+ */
+export function withUnitLock(projectRoot, scopeId, targetId, workflowId, fn, options) {
+    const dir = deliveryAttemptsDir(projectRoot);
+    mkdirSync(dir, { recursive: true });
+    const lockName = `${unitLedgerFilename(scopeId, targetId, workflowId)}.lock`;
+    const lockPath = join(dir, lockName);
+    const reclaimPath = `${lockPath}.reclaim`;
+    const root = resolve(projectRoot);
+    assertWriteTargetSafe(root, lockPath);
+    assertWriteTargetSafe(root, reclaimPath);
+    const nowMs = options?.nowMs ?? Date.now();
+    void options?.staleMs; // retained for call-site compatibility; unused
+    const token = randomBytes(8).toString("hex");
+    const record = {
+        pid: process.pid,
+        token,
+        startedAt: new Date(nowMs).toISOString(),
+    };
+    const unitLabel = `${scopeId}/${targetId}/${workflowId}`;
+    const heldError = (detail, cause) => new Error(`delivery-attempt unit lock held for ${unitLabel}${detail}`, cause ? { cause } : undefined);
+    const tryCreateLock = () => {
+        writeLockExclusive(projectRoot, lockPath, record);
+    };
+    const acquireReclaimTicket = () => {
+        try {
+            writeLockExclusive(projectRoot, reclaimPath, record);
+            return;
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "EEXIST")
+                throw err;
+        }
+        // Existing reclaim ticket — only take over if its owner PID is dead.
+        const existingReclaim = readLockRecord(reclaimPath);
+        if (!isUnitLockReclaimable(existingReclaim)) {
+            const pid = existingReclaim?.pid;
+            throw heldError(pid !== undefined ? ` (reclaim by pid ${pid})` : " (reclaim in progress)");
+        }
+        try {
+            unlinkSync(reclaimPath);
+        }
+        catch {
+            /* race */
+        }
+        try {
+            writeLockExclusive(projectRoot, reclaimPath, record);
+        }
+        catch (retryErr) {
+            throw heldError(" (reclaim in progress)", retryErr);
+        }
+    };
+    try {
+        tryCreateLock();
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "EEXIST")
+            throw err;
+        const existing = readLockRecord(lockPath);
+        if (!isUnitLockReclaimable(existing)) {
+            throw heldError(existing !== null ? ` by pid ${existing.pid}` : "");
+        }
+        // Serialize reclaim so we never unlink another worker's replacement lock.
+        acquireReclaimTicket();
+        try {
+            const again = readLockRecord(lockPath);
+            if (!isUnitLockReclaimable(again)) {
+                throw heldError(again !== null ? ` by pid ${again.pid}` : "");
+            }
+            try {
+                unlinkSync(lockPath);
+            }
+            catch {
+                /* already gone */
+            }
+            try {
+                tryCreateLock();
+            }
+            catch (retryErr) {
+                throw heldError("; retry after the other worker finishes", retryErr);
+            }
+        }
+        finally {
+            unlinkIfOurs(reclaimPath, token, process.pid);
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        unlinkIfOurs(lockPath, token, process.pid);
+    }
+}
+/**
+ * Load or create empty unit ledger.
+ * Creates only when the file is missing — never on corrupt state.
+ */
+export function loadOrCreateUnitLedger(projectRoot, input) {
+    const result = loadUnitLedgerResult(projectRoot, input.scopeId, input.targetId, input.workflowId);
+    if (result.status === "ok")
+        return result.ledger;
+    if (result.status === "corrupt") {
+        throw new Error(`delivery-attempt ledger corrupt for ${input.scopeId}/${input.targetId}/${input.workflowId}: ${result.detail}`);
+    }
+    return emptyUnitLedger(input);
+}
+export function listUnitLedgers(projectRoot) {
+    const dir = deliveryAttemptsDir(projectRoot);
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const name of readdirSync(dir)) {
+        if (!name.endsWith(".json"))
+            continue;
+        try {
+            const ledger = parseUnitLedger(JSON.parse(readFileSync(join(dir, name), "utf8")));
+            if (ledger !== null)
+                out.push(ledger);
+        }
+        catch {
+            /* skip corrupt */
+        }
+    }
+    return out;
+}
+export function activeAttempts(ledger) {
+    return ledger.attempts.filter((a) => a.status === "queued" || a.status === "running");
+}
+export function hasActiveAttempt(ledger) {
+    return activeAttempts(ledger).length > 0;
+}
+/**
+ * Open a new queued/running attempt. Caller must have passed evaluatePreDispatch.
+ * Does not re-check the gate (orchestrators own the order: evaluate → begin).
+ */
+export function beginAttempt(ledger, input) {
+    const now = utcIso(input.now);
+    const attempt = {
+        attemptId: input.attemptId ?? newAttemptId(),
+        sourceRevision: input.sourceRevision,
+        trigger: input.trigger,
+        status: input.status ?? "running",
+        failure: null,
+        materialDelta: input.materialDelta ?? [],
+        startedAt: now,
+        endedAt: null,
+        elapsedSeconds: 0,
+        toolCallCount: 0,
+        hostTokenCount: null,
+        workerId: input.workerId ?? null,
+        externalRunId: input.externalRunId ?? null,
+    };
+    // Consume override only when the pre-dispatch decision was ALLOW_OVERRIDE
+    // (caller sets consumeOverride). Trigger "override" alone is not sufficient —
+    // ordinary allows that happen to use that trigger must not burn quota.
+    let override = ledger.override;
+    if (input.consumeOverride === true && override !== null && override.remainingAttempts > 0) {
+        override = { ...override, remainingAttempts: override.remainingAttempts - 1 };
+    }
+    const next = {
+        ...ledger,
+        attempts: [...ledger.attempts, attempt],
+        lastSourceRevision: input.sourceRevision,
+        lastMaterialDelta: input.materialDelta && input.materialDelta.length > 0
+            ? input.materialDelta
+            : ledger.lastMaterialDelta,
+        blockedDecision: null,
+        override,
+        updatedAt: now,
+    };
+    return { ledger: next, attempt };
+}
+/**
+ * Record terminal outcome for an attempt. Increments budgets / sameFailureCounts
+ * on failure. Idempotent when the same externalRunId is already terminal.
+ */
+export function completeAttempt(ledger, input) {
+    const now = utcIso(input.now);
+    // Interrupted-run reconciliation: if an active attempt with this externalRunId
+    // exists, complete it. Only no-op when the run is already terminal AND no
+    // active attempt shares that externalRunId (CI re-runs may reuse ids — #3143).
+    if (input.externalRunId) {
+        const activeWithRun = ledger.attempts.find((a) => a.externalRunId === input.externalRunId &&
+            (a.status === "queued" || a.status === "running"));
+        if (activeWithRun === undefined) {
+            const terminalWithRun = ledger.attempts.find((a) => a.externalRunId === input.externalRunId &&
+                (a.status === "succeeded" ||
+                    a.status === "failed" ||
+                    a.status === "cancelled" ||
+                    a.status === "blocked"));
+            if (terminalWithRun !== undefined) {
+                return ledger;
+            }
+        }
+    }
+    let idx = -1;
+    if (input.attemptId) {
+        idx = ledger.attempts.findIndex((a) => a.attemptId === input.attemptId);
+    }
+    else if (input.externalRunId) {
+        idx = ledger.attempts.findIndex((a) => a.externalRunId === input.externalRunId &&
+            (a.status === "queued" || a.status === "running"));
+    }
+    else {
+        // Latest active
+        for (let i = ledger.attempts.length - 1; i >= 0; i--) {
+            const a = ledger.attempts[i];
+            if (a !== undefined && (a.status === "queued" || a.status === "running")) {
+                idx = i;
+                break;
+            }
+        }
+    }
+    if (idx < 0) {
+        // No open attempt — still allow recording a synthetic terminal for reconciliation.
+        const synthetic = {
+            attemptId: newAttemptId("rec"),
+            sourceRevision: ledger.lastSourceRevision ?? "unknown",
+            trigger: "automatic",
+            status: input.status,
+            failure: input.failure ?? null,
+            materialDelta: input.materialDelta ?? [],
+            startedAt: now,
+            endedAt: now,
+            elapsedSeconds: input.elapsedSeconds ?? 0,
+            toolCallCount: input.toolCallCount ?? 0,
+            hostTokenCount: input.hostTokenCount ?? null,
+            workerId: null,
+            externalRunId: input.externalRunId ?? null,
+        };
+        return applyTerminal(ledger, synthetic, input, now, true);
+    }
+    const prev = ledger.attempts[idx];
+    if (prev === undefined) {
+        return ledger;
+    }
+    if (prev.status === "succeeded" ||
+        prev.status === "failed" ||
+        prev.status === "cancelled" ||
+        prev.status === "blocked") {
+        // Already terminal — do not double-count.
+        return ledger;
+    }
+    const updated = {
+        ...prev,
+        status: input.status,
+        failure: input.failure ?? prev.failure,
+        materialDelta: input.materialDelta ?? prev.materialDelta,
+        endedAt: now,
+        elapsedSeconds: input.elapsedSeconds ?? prev.elapsedSeconds,
+        toolCallCount: input.toolCallCount ?? prev.toolCallCount,
+        hostTokenCount: input.hostTokenCount === undefined ? prev.hostTokenCount : input.hostTokenCount,
+        externalRunId: input.externalRunId ?? prev.externalRunId,
+    };
+    const attempts = ledger.attempts.slice();
+    attempts[idx] = updated;
+    const withAttempt = { ...ledger, attempts };
+    return applyTerminal(withAttempt, updated, input, now, false);
+}
+function applyTerminal(ledger, attempt, input, now, appendSynthetic) {
+    const failure = input.failure ?? attempt.failure;
+    const elapsed = input.elapsedSeconds ?? attempt.elapsedSeconds;
+    const tools = input.toolCallCount ?? attempt.toolCallCount;
+    const tokens = input.hostTokenCount === undefined ? attempt.hostTokenCount : input.hostTokenCount;
+    let failedAttemptCount = ledger.failedAttemptCount;
+    const sameFailureCounts = { ...ledger.sameFailureCounts };
+    if (input.status === "failed" || input.status === "blocked") {
+        failedAttemptCount += 1;
+        if (failure !== null) {
+            sameFailureCounts[failure.fingerprint] = (sameFailureCounts[failure.fingerprint] ?? 0) + 1;
+        }
+    }
+    let totalHost = ledger.totalHostTokenCount;
+    if (tokens !== null && tokens !== undefined) {
+        totalHost = (totalHost ?? 0) + tokens;
+    }
+    const attempts = appendSynthetic ? [...ledger.attempts, attempt] : ledger.attempts;
+    // Success closes the active failure identity for this unit (transient recovery
+    // path). Phase aggregate counters remain for observability / attempt budget.
+    const lastFailure = input.status === "succeeded" ? null : (failure ?? ledger.lastFailure);
+    return {
+        ...ledger,
+        attempts,
+        failedAttemptCount,
+        sameFailureCounts,
+        totalElapsedSeconds: ledger.totalElapsedSeconds + elapsed,
+        totalToolCallCount: ledger.totalToolCallCount + tools,
+        totalHostTokenCount: totalHost,
+        lastFailure,
+        lastMaterialDelta: input.materialDelta ?? attempt.materialDelta ?? ledger.lastMaterialDelta,
+        lastSourceRevision: attempt.sourceRevision,
+        blockedDecision: input.status === "succeeded" ? null : ledger.blockedDecision,
+        resumeCondition: input.status === "succeeded" ? null : ledger.resumeCondition,
+        updatedAt: now,
+    };
+}
+/** Mark unit blocked with resume condition (persisted before worker exit). */
+export function markBlocked(ledger, decision, resume, now) {
+    return {
+        ...ledger,
+        blockedDecision: decision,
+        resumeCondition: resume,
+        updatedAt: utcIso(now),
+    };
+}
+/** Clear block when resume condition is satisfied (caller sets satisfied=true). */
+export function clearBlockIfResumed(ledger, now) {
+    if (ledger.resumeCondition === null || !ledger.resumeCondition.satisfied) {
+        return ledger;
+    }
+    return {
+        ...ledger,
+        blockedDecision: null,
+        resumeCondition: { ...ledger.resumeCondition, satisfied: true },
+        updatedAt: utcIso(now),
+    };
+}
+/**
+ * Record an audited operator override. Preserves full attempt history.
+ * remainingAttempts starts at allowedAttempts.
+ */
+export function recordOperatorOverride(ledger, input) {
+    const now = utcIso(input.now);
+    const allowed = Math.max(1, input.allowedAttempts ?? 1);
+    const override = {
+        overrideId: `ovr-${randomBytes(6).toString("hex")}`,
+        actor: input.actor,
+        rationale: input.rationale,
+        recordedAt: now,
+        allowedAttempts: allowed,
+        expiresAt: input.expiresAt ?? null,
+        remainingAttempts: allowed,
+    };
+    return {
+        ...ledger,
+        override,
+        blockedDecision: null,
+        resumeCondition: {
+            kind: "operator-override",
+            description: `operator override by ${input.actor}: ${input.rationale}`,
+            satisfied: true,
+        },
+        updatedAt: now,
+    };
+}
+/** In-memory ledger store for tests and pure evaluation paths. */
+export class MemoryLedgerStore {
+    map = new Map();
+    get(scopeId, targetId, workflowId) {
+        return this.map.get(deliveryUnitKey(scopeId, targetId, workflowId)) ?? null;
+    }
+    set(ledger) {
+        this.map.set(deliveryUnitKey(ledger.scopeId, ledger.targetId, ledger.workflowId), ledger);
+    }
+    getOrCreate(input) {
+        const existing = this.get(input.scopeId, input.targetId, input.workflowId);
+        if (existing)
+            return existing;
+        const empty = emptyUnitLedger(input);
+        this.set(empty);
+        return empty;
+    }
+    clear() {
+        this.map.clear();
+    }
+}
+//# sourceMappingURL=ledger.js.map