project-tiny-context-harness 0.2.85 → 0.6.0

package/dist/lib/long-task-state.js

@@ -0,0 +1,611 @@
+import { access, mkdir, open, readFile, readdir, rename, rm, writeFile, } from "node:fs/promises";
+import path from "node:path";
+import { canonicalJson, canonicalValueJson, sha256Hex, } from "./strict-codec.js";
+import { gitCommonDir, gitConfigGet, gitConfigSet, gitConfigUnset, gitPath, } from "./long-task-workspace.js";
+import { verifierAuthorityDiff } from "./long-task-verifier-authority.js";
+const RUNTIME_FOLDER = ".ty-context";
+const COMPILED_FILE = "compiled-contract.json";
+const PROGRESS_FOLDER = "progress";
+const AUTHORITY_PENDING_FILE = "authority-revision-pending.json";
+const AUTHORITY_APPROVED_FILE = "authority-revision-approved.json";
+const FINAL_FILE = "final-receipt.json";
+const CONTRACT_FILE = "delivery-contract.yaml";
+export function runtimePath(workdir, file = "") {
+    return path.join(path.resolve(workdir), RUNTIME_FOLDER, file);
+}
+export function worktreeIdentity(repositoryRoot) {
+    const normalized = normalizePath(repositoryRoot);
+    return `wt-${sha256Hex(normalized)}`;
+}
+export async function activeRecordPath(repositoryRoot) {
+    const identity = worktreeIdentity(repositoryRoot);
+    return path.join(await gitCommonDir(repositoryRoot), "ty-context", "long-task", "worktrees", identity, "active.json");
+}
+export async function activeAuthorityLockPath(repositoryRoot) {
+    return `${await activeRecordPath(repositoryRoot)}.lock`;
+}
+export async function activeAuthorityLockExists(repositoryRoot) {
+    return access(await activeAuthorityLockPath(repositoryRoot))
+        .then(() => true)
+        .catch(() => false);
+}
+export async function withActiveAuthorityLock(repositoryRoot, operation, action) {
+    return withActiveAuthorityLockInternal(repositoryRoot, operation, action, false);
+}
+async function withActiveAuthorityLockInternal(repositoryRoot, operation, action, breakStaleLock) {
+    const root = path.resolve(repositoryRoot);
+    const activeFile = await activeRecordPath(root);
+    await mkdir(path.dirname(activeFile), { recursive: true });
+    const lockFile = await activeAuthorityLockPath(root);
+    let lock;
+    try {
+        lock = await open(lockFile, "wx");
+    }
+    catch (error) {
+        if (error.code === "EEXIST" && breakStaleLock) {
+            await rm(lockFile, { force: true });
+            try {
+                lock = await open(lockFile, "wx");
+            }
+            catch (retryError) {
+                if (retryError.code === "EEXIST")
+                    throw new Error("active_authority_compare_and_swap_failed:lock_unavailable");
+                throw retryError;
+            }
+        }
+        else if (error.code === "EEXIST")
+            throw new Error("active_authority_compare_and_swap_failed:lock_unavailable");
+        else
+            throw error;
+    }
+    try {
+        await lock.writeFile(canonicalJson({
+            pid: process.pid,
+            operation,
+            created_at: new Date().toISOString(),
+        }), "utf8");
+        await lock.sync();
+        return await action();
+    }
+    finally {
+        await lock.close();
+        await rm(lockFile, { force: true });
+    }
+}
+export async function writeCompiledDeliveryContract(compiled) {
+    const staged = await stageCompiledDeliveryContract(compiled);
+    try {
+        await staged.publish();
+    }
+    catch (error) {
+        await staged.discard();
+        throw error;
+    }
+}
+export async function stageCompiledDeliveryContract(compiled) {
+    const target = runtimePath(compiled.workdir, COMPILED_FILE);
+    const temporary = await stageAtomicText(target, canonicalJson(compiled));
+    let consumed = false;
+    return {
+        async publish() {
+            if (consumed)
+                throw new Error("compiled_cache_stage_already_consumed");
+            await rename(temporary, target);
+            consumed = true;
+        },
+        async discard() {
+            if (consumed)
+                return;
+            consumed = true;
+            await rm(temporary, { force: true });
+        },
+    };
+}
+export async function readCompiledDeliveryContract(workdir) {
+    return validateCompiledDeliveryContract(await readJson(runtimePath(workdir, COMPILED_FILE)), path.resolve(workdir));
+}
+export async function loadActiveLongTaskAuthority(repositoryRoot, _options = {}) {
+    return loadActiveLongTaskAuthorityUnlocked(path.resolve(repositoryRoot));
+}
+async function loadActiveLongTaskAuthorityUnlocked(root) {
+    const identity = worktreeIdentity(root);
+    const [marker, raw] = await Promise.all([
+        gitConfigGet(root, markerKey(identity)),
+        readOptionalJson(await activeRecordPath(root)),
+    ]);
+    if (marker === null && raw === null)
+        return { authority: null, source: "none", migrated: false };
+    if (marker === null)
+        throw new Error("active_binding_marker_missing");
+    if (raw === null)
+        throw new Error("active_binding_record_missing");
+    const row = raw;
+    if (row.schema_version === "active-long-task-authority-v3")
+        return {
+            authority: await validateActiveAuthorityV3(root, identity, marker, row),
+            source: "active_authority_v3",
+            migrated: false,
+        };
+    if (row.schema_version === "active-long-task-binding-v2")
+        throw new Error("legacy_v2_active_authority_manual_required");
+    throw new Error("active_authority_invalid:schema_version");
+}
+export async function loadActiveCompiledAuthority(repositoryRoot, workdir, options = {}) {
+    const loaded = await loadActiveLongTaskAuthority(repositoryRoot, options);
+    if (!loaded.authority)
+        return null;
+    if (workdir &&
+        normalizePath(loaded.authority.workdir) !== normalizePath(workdir))
+        throw new Error("active_task_workdir_mismatch");
+    return loaded.authority.authority_snapshot;
+}
+export async function readActiveLongTaskBinding(repositoryRoot) {
+    return (await loadActiveLongTaskAuthority(repositoryRoot)).authority;
+}
+export async function inspectCompiledCache(authority) {
+    try {
+        const cache = await readCompiledDeliveryContract(authority.workdir);
+        return cache.compiled_identity === authority.active_authority_identity
+            ? "compiled_cache_matching"
+            : "compiled_cache_mismatched_ignored";
+    }
+    catch (error) {
+        return missingError(error)
+            ? "compiled_cache_missing_repairable"
+            : "compiled_cache_mismatched_ignored";
+    }
+}
+export async function commitActiveAuthority(options) {
+    const root = path.resolve(options.candidate.repository_root);
+    const initial = await loadActiveLongTaskAuthorityUnlocked(root);
+    const verifierDiff = initial.authority
+        ? verifierAuthorityDiff(initial.authority.verifier_identity, options.candidate.verifier_identity)
+        : null;
+    const operation = initial.authority &&
+        (verifierDiff?.verifier_content_changed ||
+            verifierDiff?.verifier_runtime_locator_changed)
+        ? "migrate"
+        : "commit";
+    return withActiveAuthorityLock(root, operation, async () => {
+        const current = await loadActiveLongTaskAuthorityUnlocked(root);
+        assertAuthorityCasCandidate(current.authority, options.candidate, options.expected_previous_identity);
+        await ensureRuntimeExcludes(root, options.candidate.workdir);
+        const authority = activeAuthorityFromCompiled(options.candidate, current.authority?.activated_at ?? new Date().toISOString());
+        await persistActiveAuthorityCasUnlocked(root, authority, options.expected_previous_identity);
+        return authority;
+    });
+}
+export async function activateDeliveryContract(compiled) {
+    const current = await loadActiveLongTaskAuthority(compiled.repository_root);
+    return commitActiveAuthority({
+        candidate: compiled,
+        expected_previous_identity: current.authority?.active_authority_identity ?? null,
+    });
+}
+export async function assertMatchingActiveBinding(compiled) {
+    const active = (await loadActiveLongTaskAuthority(compiled.repository_root, {
+        migrate_legacy: true,
+    })).authority;
+    if (!active)
+        throw new Error("active_task_missing");
+    if (normalizePath(active.workdir) !== normalizePath(compiled.workdir) ||
+        active.task_id !== compiled.task.id ||
+        active.active_authority_identity !== compiled.compiled_identity ||
+        active.authority_revision !== compiled.authority_revision ||
+        active.worktree_identity !== worktreeIdentity(compiled.repository_root) ||
+        !sameValue(active.verifier_identity, compiled.verifier_identity))
+        throw new Error("active_task_identity_mismatch");
+    return active;
+}
+async function validateActiveAuthorityV3(root, identity, marker, row) {
+    if (typeof row.task_id !== "string" ||
+        typeof row.repository_root !== "string" ||
+        typeof row.worktree_identity !== "string" ||
+        typeof row.workdir !== "string" ||
+        typeof row.active_authority_identity !== "string" ||
+        typeof row.authority_revision !== "number" ||
+        !Number.isInteger(row.authority_revision) ||
+        row.authority_revision < 1 ||
+        typeof row.activated_at !== "string" ||
+        typeof row.authority_snapshot_sha256 !== "string" ||
+        !row.initial_task_base ||
+        !row.verifier_identity ||
+        !row.authority_snapshot)
+        throw new Error("active_authority_invalid:shape");
+    const authority = row;
+    if (marker !== markerValue(authority))
+        throw new Error("marker_record_mismatch");
+    if (authority.worktree_identity !== identity)
+        throw new Error("active_authority_invalid:worktree_identity");
+    if (normalizePath(authority.repository_root) !== normalizePath(root))
+        throw new Error("active_authority_invalid:repository_identity");
+    const snapshot = validateCompiledDeliveryContract(authority.authority_snapshot, path.resolve(authority.workdir));
+    if (sha256Hex(canonicalValueJson(snapshot)) !==
+        authority.authority_snapshot_sha256)
+        throw new Error("active_authority_invalid:snapshot_hash");
+    if (authority.task_id !== snapshot.task.id ||
+        normalizePath(authority.repository_root) !==
+            normalizePath(snapshot.repository_root) ||
+        normalizePath(authority.workdir) !== normalizePath(snapshot.workdir) ||
+        authority.active_authority_identity !== snapshot.compiled_identity ||
+        authority.authority_revision !== snapshot.authority_revision ||
+        !sameValue(authority.initial_task_base, snapshot.initial_task_base) ||
+        !sameValue(authority.verifier_identity, snapshot.verifier_identity))
+        throw new Error("active_authority_invalid:snapshot_binding");
+    await assertActiveWorkdir(authority.workdir);
+    return authority;
+}
+function validateCompiledDeliveryContract(value, expectedWorkdir) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("compiled_contract_invalid:shape");
+    const compiled = value;
+    if (compiled.schema_version !== "compiled-long-task-delivery-v2" ||
+        typeof compiled.compiled_identity !== "string" ||
+        typeof compiled.repository_root !== "string" ||
+        typeof compiled.workdir !== "string")
+        throw new Error("compiled_contract_invalid:schema_version");
+    const { compiled_identity: compiledIdentity, ...unsigned } = compiled;
+    if (sha256Hex(canonicalValueJson(unsigned)) !== compiledIdentity)
+        throw new Error("compiled_contract_invalid:identity");
+    if (expectedWorkdir &&
+        normalizePath(expectedWorkdir) !== normalizePath(compiled.workdir))
+        throw new Error("compiled_contract_invalid:workdir");
+    return compiled;
+}
+function activeAuthorityFromCompiled(compiled, activatedAt) {
+    const authoritySnapshot = validateCompiledDeliveryContract(compiled, compiled.workdir);
+    return {
+        schema_version: "active-long-task-authority-v3",
+        task_id: authoritySnapshot.task.id,
+        repository_root: path.resolve(authoritySnapshot.repository_root),
+        worktree_identity: worktreeIdentity(authoritySnapshot.repository_root),
+        workdir: path.resolve(authoritySnapshot.workdir),
+        active_authority_identity: authoritySnapshot.compiled_identity,
+        authority_revision: authoritySnapshot.authority_revision,
+        initial_task_base: authoritySnapshot.initial_task_base,
+        verifier_identity: authoritySnapshot.verifier_identity,
+        activated_at: activatedAt,
+        authority_snapshot: authoritySnapshot,
+        authority_snapshot_sha256: sha256Hex(canonicalValueJson(authoritySnapshot)),
+    };
+}
+function assertAuthorityCasCandidate(current, candidate, expectedPreviousIdentity) {
+    const currentIdentity = current?.active_authority_identity ?? null;
+    if (currentIdentity !== expectedPreviousIdentity)
+        throw new Error("active_authority_compare_and_swap_failed");
+    if (!current) {
+        if (candidate.authority_revision !== 1)
+            throw new Error("active_authority_revision_invalid:new_task");
+        return;
+    }
+    if (normalizePath(current.workdir) !== normalizePath(candidate.workdir) ||
+        current.task_id !== candidate.task.id)
+        throw new Error(`active_task_exists:${current.workdir}`);
+    if (!sameValue(current.initial_task_base, candidate.initial_task_base))
+        throw new Error("active_authority_initial_task_base_changed");
+    if (currentIdentity === candidate.compiled_identity) {
+        if (candidate.authority_revision !== current.authority_revision)
+            throw new Error("active_authority_revision_invalid:unchanged_identity");
+        return;
+    }
+    if (candidate.authority_revision !== current.authority_revision + 1)
+        throw new Error("active_authority_revision_invalid:expected_increment");
+}
+async function persistActiveAuthorityCasUnlocked(root, authority, expectedPreviousIdentity) {
+    const activeFile = await activeRecordPath(root);
+    await mkdir(path.dirname(activeFile), { recursive: true });
+    const current = await loadActiveLongTaskAuthorityUnlocked(root);
+    assertAuthorityCasCandidate(current.authority, authority.authority_snapshot, expectedPreviousIdentity);
+    const identity = worktreeIdentity(root);
+    const key = markerKey(identity);
+    const [oldRecord, oldMarker] = await Promise.all([
+        readOptionalText(activeFile),
+        gitConfigGet(root, key),
+    ]);
+    try {
+        await atomicJson(activeFile, authority);
+        await gitConfigSet(root, key, markerValue(authority));
+    }
+    catch (error) {
+        try {
+            if (oldRecord === null)
+                await rm(activeFile, { force: true });
+            else
+                await atomicText(activeFile, oldRecord);
+            if (oldMarker === null)
+                await gitConfigUnset(root, key);
+            else
+                await gitConfigSet(root, key, oldMarker);
+        }
+        catch (rollbackError) {
+            throw new Error(`active_authority_commit_rollback_failed:${message(rollbackError)}`);
+        }
+        throw new Error(`active_authority_commit_failed:${message(error)}`);
+    }
+}
+async function assertActiveWorkdir(workdir) {
+    await access(workdir).catch(() => {
+        throw new Error("active_binding_workdir_missing");
+    });
+    await access(path.join(workdir, CONTRACT_FILE)).catch(() => {
+        throw new Error("active_binding_contract_missing");
+    });
+}
+function markerValue(authority) {
+    return [
+        authority.task_id,
+        String(authority.authority_revision),
+        authority.active_authority_identity,
+    ].join("|");
+}
+function sameValue(left, right) {
+    return canonicalValueJson(left) === canonicalValueJson(right);
+}
+export async function writeProgressRecord(workdir, record) {
+    await atomicJson(runtimePath(workdir, path.join(PROGRESS_FOLDER, `${record.check_internal_id}.json`)), record);
+}
+export async function readProgressRecords(workdir) {
+    const folder = runtimePath(workdir, PROGRESS_FOLDER);
+    const names = await readdir(folder).catch((error) => {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    });
+    const rows = {};
+    for (const name of names.filter((name) => name.endsWith(".json")).sort()) {
+        const value = (await readJson(path.join(folder, name)));
+        if (value.schema_version !== "long-task-progress-record-v2")
+            throw new Error(`progress_record_invalid:${name}`);
+        rows[value.check_internal_id] = value;
+    }
+    return rows;
+}
+export async function writePendingAuthorityRevision(workdir, pending) {
+    await atomicJson(runtimePath(workdir, AUTHORITY_PENDING_FILE), pending);
+    await rm(runtimePath(workdir, AUTHORITY_APPROVED_FILE), { force: true });
+}
+export async function readPendingAuthorityRevision(workdir) {
+    return (await readOptionalJson(runtimePath(workdir, AUTHORITY_PENDING_FILE)));
+}
+export async function approvePendingAuthorityRevision(workdir, revision) {
+    const pending = await readPendingAuthorityRevision(workdir);
+    if (!pending || pending.revision_identity !== revision)
+        throw new Error("authority_revision_not_found_or_mismatched");
+    await atomicJson(runtimePath(workdir, AUTHORITY_APPROVED_FILE), {
+        schema_version: "long-task-authority-revision-approved-v2",
+        revision_identity: revision,
+        approved_at: new Date().toISOString(),
+    });
+}
+export async function authorityRevisionApproved(workdir, revision) {
+    const value = (await readOptionalJson(runtimePath(workdir, AUTHORITY_APPROVED_FILE)));
+    return value?.revision_identity === revision;
+}
+export async function clearAuthorityRevision(workdir) {
+    await Promise.all([
+        rm(runtimePath(workdir, AUTHORITY_PENDING_FILE), { force: true }),
+        rm(runtimePath(workdir, AUTHORITY_APPROVED_FILE), { force: true }),
+    ]);
+}
+export async function invalidateDerivedProgress(workdir) {
+    await Promise.all([
+        rm(runtimePath(workdir, PROGRESS_FOLDER), { recursive: true, force: true }),
+        rm(runtimePath(workdir, FINAL_FILE), { force: true }),
+    ]);
+}
+export async function writeFinalReceipt(repositoryRoot, workdir, unsigned) {
+    const receipt = {
+        ...unsigned,
+        receipt_sha256: sha256Hex(canonicalValueJson(unsigned)),
+    };
+    const content = canonicalJson(receipt);
+    await Promise.all([
+        atomicText(runtimePath(workdir, FINAL_FILE), content),
+        atomicText(await auditReceiptPath(repositoryRoot), content),
+    ]);
+    return receipt;
+}
+export async function readFinalReceipt(_repositoryRoot, workdir) {
+    const value = await readOptionalJson(runtimePath(workdir, FINAL_FILE));
+    if (value === null)
+        return null;
+    const receipt = value;
+    const { receipt_sha256: receiptHash, ...unsigned } = receipt;
+    if (receipt.schema_version !== "long-task-final-receipt-v2" ||
+        receipt.authority_scope !== "audit_only" ||
+        receipt.reusable_for_acceptance !== false ||
+        sha256Hex(canonicalValueJson(unsigned)) !== receiptHash)
+        throw new Error("final_receipt_integrity_mismatch");
+    return receipt;
+}
+export function activeAuthorityIdentityMatches(authority, expected) {
+    return (authority.task_id === expected.task_id &&
+        authority.authority_revision === expected.authority_revision &&
+        authority.active_authority_identity === expected.compiled_identity &&
+        authority.worktree_identity ===
+            (expected.worktree_identity ?? authority.worktree_identity));
+}
+export async function clearActiveBindingCas(options) {
+    const root = path.resolve(options.repository_root);
+    return withActiveAuthorityLock(root, "clear", async () => clearActiveBindingCasUnlocked(root, options));
+}
+async function clearActiveBindingCasUnlocked(root, options) {
+    const loaded = await loadActiveLongTaskAuthorityUnlocked(root);
+    const active = loaded.authority;
+    if (!active ||
+        normalizePath(active.workdir) !== normalizePath(options.workdir) ||
+        !activeAuthorityIdentityMatches(active, options))
+        throw new Error("active_authority_clear_compare_and_swap_failed");
+    const activeFile = await activeRecordPath(root);
+    const key = markerKey(worktreeIdentity(root));
+    const [oldRecord, oldMarker] = await Promise.all([
+        readOptionalText(activeFile),
+        gitConfigGet(root, key),
+    ]);
+    try {
+        await rm(activeFile, { force: true });
+        await gitConfigUnset(root, key);
+    }
+    catch (error) {
+        try {
+            if (oldRecord !== null)
+                await atomicText(activeFile, oldRecord);
+            if (oldMarker !== null)
+                await gitConfigSet(root, key, oldMarker);
+        }
+        catch (rollbackError) {
+            throw new Error(`active_authority_clear_rollback_failed:${message(rollbackError)}`);
+        }
+        throw new Error(`active_authority_clear_failed:${message(error)}`);
+    }
+    return true;
+}
+export async function abandonLongTaskState(repositoryRoot, workdir) {
+    const root = path.resolve(repositoryRoot);
+    const resolved = assertContainedWorkdir(root, workdir);
+    await withActiveAuthorityLock(root, "abandon", async () => {
+        const loaded = await loadActiveLongTaskAuthorityUnlocked(root);
+        const active = loaded.authority;
+        if (!active)
+            throw new Error("active_task_missing");
+        if (normalizePath(active.workdir) !== normalizePath(resolved))
+            throw new Error("active_task_workdir_mismatch");
+        await clearActiveBindingCasUnlocked(root, {
+            repository_root: root,
+            workdir: resolved,
+            task_id: active.task_id,
+            authority_revision: active.authority_revision,
+            compiled_identity: active.active_authority_identity,
+            worktree_identity: active.worktree_identity,
+        });
+        await rm(runtimePath(resolved), { recursive: true, force: true });
+    });
+}
+export async function forceClearCorruptActiveState(repositoryRoot, workdir) {
+    const root = path.resolve(repositoryRoot);
+    const resolved = assertContainedWorkdir(root, workdir);
+    const lockPresent = await activeAuthorityLockExists(root);
+    let corruptState = lockPresent;
+    if (!corruptState)
+        try {
+            await loadActiveLongTaskAuthorityUnlocked(root);
+            corruptState = false;
+        }
+        catch {
+            corruptState = true;
+        }
+    if (!corruptState)
+        throw new Error("force_corrupt_state_requires_corrupt_active_state");
+    await withActiveAuthorityLockInternal(root, "abandon", async () => {
+        const activeFile = await activeRecordPath(root);
+        const key = markerKey(worktreeIdentity(root));
+        const [oldRecord, oldMarker] = await Promise.all([
+            readOptionalText(activeFile),
+            gitConfigGet(root, key),
+        ]);
+        try {
+            await rm(activeFile, { force: true });
+            await gitConfigUnset(root, key);
+        }
+        catch (error) {
+            try {
+                if (oldRecord !== null)
+                    await atomicText(activeFile, oldRecord);
+                if (oldMarker !== null)
+                    await gitConfigSet(root, key, oldMarker);
+            }
+            catch (rollbackError) {
+                throw new Error(`active_authority_force_clear_rollback_failed:${message(rollbackError)}`);
+            }
+            throw new Error(`active_authority_force_clear_failed:${message(error)}`);
+        }
+        await rm(runtimePath(resolved), { recursive: true, force: true });
+    }, true);
+}
+export async function clearFinalReceipt(repositoryRoot, workdir) {
+    await Promise.all([
+        rm(runtimePath(workdir, FINAL_FILE), { force: true }),
+        rm(await auditReceiptPath(repositoryRoot), { force: true }),
+    ]);
+}
+async function auditReceiptPath(repositoryRoot) {
+    return path.join(path.dirname(await activeRecordPath(repositoryRoot)), "last-final-receipt.json");
+}
+async function ensureRuntimeExcludes(repositoryRoot, workdir) {
+    const exclude = await gitPath(repositoryRoot, "info/exclude");
+    await mkdir(path.dirname(exclude), { recursive: true });
+    const existing = await readFile(exclude, "utf8").catch(() => "");
+    const relativeRuntime = `${path
+        .relative(repositoryRoot, runtimePath(workdir))
+        .replace(/\\/gu, "/")}/`;
+    if (!existing.split(/\r?\n/u).includes(relativeRuntime))
+        await writeFile(exclude, `${existing.replace(/\s*$/u, "")}\n${relativeRuntime}\n`, "utf8");
+}
+function markerKey(identity) {
+    return `ty-context.longTask.${identity}`;
+}
+function normalizePath(value) {
+    const normalized = path.resolve(value).replace(/\\/gu, "/");
+    return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+function assertContainedWorkdir(repositoryRoot, workdir) {
+    const root = path.resolve(repositoryRoot);
+    const resolved = path.resolve(workdir);
+    const relative = path.relative(root, resolved);
+    if (!relative ||
+        relative === ".." ||
+        relative.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relative))
+        throw new Error("long_task_workdir_outside_repository");
+    return resolved;
+}
+async function readJson(file) {
+    return JSON.parse(await readFile(file, "utf8"));
+}
+async function readOptionalJson(file) {
+    try {
+        return await readJson(file);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+async function readOptionalText(file) {
+    try {
+        return await readFile(file, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+async function atomicJson(file, value) {
+    await atomicText(file, canonicalJson(value));
+}
+async function atomicText(file, content) {
+    const temporary = await stageAtomicText(file, content);
+    await rename(temporary, file);
+}
+async function stageAtomicText(file, content) {
+    await mkdir(path.dirname(file), { recursive: true });
+    const temporary = `${file}.tmp-${process.pid}-${Date.now()}`;
+    const handle = await open(temporary, "wx");
+    try {
+        await handle.writeFile(content, "utf8");
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    return temporary;
+}
+function missingError(error) {
+    const value = message(error);
+    return value.includes("ENOENT") || value.includes("no such file");
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/lib/long-task-status-projection.d.ts

@@ -0,0 +1,21 @@
+import type { CompiledDeliveryContractV2, FinalReceiptV2, LongTaskFindingV2, OutcomeStatusV2, ProgressRecordV2, WorkspaceManifestV2 } from "./long-task-delivery-types.js";
+interface StatusProjectionInputV2 {
+    compiled: CompiledDeliveryContractV2;
+    manifest: WorkspaceManifestV2;
+    stale: string[];
+    progress: Record<string, ProgressRecordV2>;
+    receipt: FinalReceiptV2 | null;
+    receiptError: string | null;
+}
+export type AuditGateStatusV2 = "no_final_gate" | "last_gate_passed" | "last_gate_failed" | "last_gate_blocked" | "last_gate_inputs_stale";
+export declare function projectDeliveryStatus(input: StatusProjectionInputV2): {
+    finalResult: AuditGateStatusV2;
+    finalWorkflowStatus: FinalReceiptV2["workflow_status"] | null;
+    outcomes: Record<string, OutcomeStatusV2>;
+    readyOutcomes: string[];
+    needsReverify: string[];
+    progressPassing: string[];
+    progressFailing: string[];
+    findings: LongTaskFindingV2[];
+};
+export {};