martin-loop 0.1.4 → 1.3.0

package/dist/vendor/core/workflow-artifacts.js

@@ -0,0 +1,668 @@
+import { createHash } from "node:crypto";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { reportedTotalUsd } from "../contracts/index.js";
+import { signAgentReceipt } from "./agent/receipts.js";
+import { assertSafeLoopId } from "./persistence/checkpoint.js";
+import { signFileAttestation, verifyFileAttestation } from "./attestation/sign.js";
+import { computeContextUtilityScore } from "./context-utility.js";
+export function resolveWorkflowArtifactPaths(runsRoot, loopId) {
+    assertSafeLoopId(loopId);
+    const runRoot = join(runsRoot, loopId);
+    return {
+        runRoot,
+        contractPath: join(runRoot, "contract.json"),
+        statePath: join(runRoot, "state.json"),
+        loopRecordPath: join(runRoot, "loop-record.json"),
+        loopRecordSignaturePath: join(runRoot, "loop-record.signature.json"),
+        loopRecordPublicKeyPath: join(runRoot, "loop-record.public.pem"),
+        ledgerPath: join(runRoot, "ledger.jsonl"),
+        artifactsRoot: join(runRoot, "artifacts"),
+        contextUtilityScorePath: join(runRoot, "context-utility-score.json"),
+        workflowReceiptPath: join(runRoot, "workflow-receipt.json"),
+        workflowHandoffJsonPath: join(runRoot, "workflow-handoff.json"),
+        workflowHandoffMarkdownPath: join(runRoot, "workflow-handoff.md")
+    };
+}
+export async function persistWorkflowArtifacts(input) {
+    const paths = resolveWorkflowArtifactPaths(input.runsRoot, input.loop.loopId);
+    await persistContextUtilityScore(paths, input.martinHome, input.loop.updatedAt);
+    const ledgerHash = await computeLedgerHash(paths.ledgerPath);
+    const compaction = await compactWorkflowHandoffSources(paths);
+    const receipt = await signAgentReceipt(buildLocalWorkflowReceipt(input.loop, ledgerHash), {
+        martinHome: input.martinHome
+    });
+    const handoff = buildWorkflowHandoffArtifact(input.loop, paths, ledgerHash, compaction);
+    await mkdir(paths.runRoot, { recursive: true });
+    await writeJson(paths.workflowReceiptPath, receipt);
+    await writeJson(paths.workflowHandoffJsonPath, handoff);
+    await writeFile(paths.workflowHandoffMarkdownPath, renderWorkflowHandoffMarkdown(handoff), "utf8");
+    await signFileAttestation(paths.workflowHandoffJsonPath, {
+        martinHome: input.martinHome,
+        now: input.loop.updatedAt
+    });
+    return {
+        paths,
+        ledgerHash,
+        receipt,
+        handoff
+    };
+}
+export function buildWorkflowHandoffArtifact(loop, paths, ledgerHash, compaction) {
+    return {
+        schemaVersion: "martin.workflow.handoff.v1",
+        loopId: loop.loopId,
+        workspaceId: loop.workspaceId,
+        projectId: loop.projectId,
+        status: loop.status,
+        lifecycleState: loop.lifecycleState,
+        objective: loop.task.objective,
+        verificationPlan: resolveRenderedVerificationPlan(loop, compaction),
+        attemptCount: loop.attempts.length,
+        actualUsd: loop.cost.actualUsd,
+        reportedTotalUsd: reportedTotalUsd(loop.cost),
+        ledgerHash,
+        verificationStatus: loop.lifecycleState === "completed" ? "passed" : "blocked",
+        nextAction: determineNextAction(loop.lifecycleState),
+        runRoot: paths.runRoot,
+        loopRecordPath: paths.loopRecordPath,
+        workflowReceiptPath: paths.workflowReceiptPath,
+        ledgerPath: paths.ledgerPath,
+        compaction,
+        createdAt: loop.createdAt,
+        updatedAt: loop.updatedAt
+    };
+}
+export function renderWorkflowHandoffMarkdown(handoff) {
+    const verificationPlan = handoff.compaction.verificationPlan;
+    return [
+        "# Martin Loop Workflow Handoff",
+        "",
+        `- Loop: \`${handoff.loopId}\``,
+        `- Workspace: \`${handoff.workspaceId}\``,
+        `- Project: \`${handoff.projectId}\``,
+        `- Status: \`${handoff.status}\` / \`${handoff.lifecycleState}\``,
+        `- Verification: \`${handoff.verificationStatus}\``,
+        `- Attempts: ${String(handoff.attemptCount)}`,
+        `- Spend: $${handoff.actualUsd.toFixed(4)} actual / $${handoff.reportedTotalUsd.toFixed(4)} reported`,
+        `- Next action: ${handoff.nextAction}`,
+        "",
+        "## Objective",
+        handoff.objective,
+        "",
+        "## Verification Plan",
+        ...(verificationPlan
+            ? [
+                `- Tier: \`${verificationPlan.tier ?? "standard"}\``,
+                `- Must pass all: \`${verificationPlan.mustPassAll ? "yes" : "no"}\``,
+                `- Summary: ${verificationPlan.summary}`
+            ]
+            : []),
+        ...(handoff.verificationPlan.length > 0
+            ? handoff.verificationPlan.map((command) => `- \`${command}\``)
+            : ["- No verification plan recorded."]),
+        "",
+        "## Touched Surfaces",
+        ...(handoff.compaction.touchedSurfaces.length > 0
+            ? handoff.compaction.touchedSurfaces.map((surface) => `- \`${surface}\``)
+            : ["- No touched surfaces recorded."]),
+        "",
+        "## Blockers",
+        ...(handoff.compaction.blockers.length > 0
+            ? handoff.compaction.blockers.map((blocker) => `- ${blocker}`)
+            : ["- No blockers recorded."]),
+        "",
+        "## Verification State",
+        `- Status: \`${handoff.compaction.verification.status}\``,
+        `- Summary: ${handoff.compaction.verification.summary}`,
+        "",
+        "## Context Utility",
+        ...(handoff.compaction.contextUtility
+            ? renderContextUtilityMarkdown(handoff.compaction.contextUtility)
+            : ["- No context utility score recorded."]),
+        "",
+        "## Next Prompt",
+        "```text",
+        handoff.compaction.nextPrompt,
+        "```",
+        "",
+        "## Canonical Paths",
+        `- Run root: \`${handoff.runRoot}\``,
+        `- Contract: \`${normalizePath(join(handoff.runRoot, "contract.json"))}\``,
+        `- Loop record: \`${handoff.loopRecordPath}\``,
+        `- Workflow receipt: \`${handoff.workflowReceiptPath}\``,
+        `- Ledger: \`${handoff.ledgerPath}\``,
+        "",
+        `Ledger hash: \`${handoff.ledgerHash}\``,
+        ""
+    ].join("\n");
+}
+export async function computeLedgerHash(ledgerPath) {
+    const raw = await readFile(ledgerPath, "utf8").catch(() => "");
+    return createHash("sha256").update(raw, "utf8").digest("hex");
+}
+export async function compactWorkflowHandoffSources(paths) {
+    const [contract, state, ledger, sources, touchedSurfaces, verificationPlan] = await Promise.all([
+        readJsonIfExists(paths.contractPath),
+        readJsonIfExists(paths.statePath),
+        readLedgerEvents(paths.ledgerPath),
+        collectWorkflowSourceDigests(paths),
+        collectTouchedSurfaces(paths.artifactsRoot),
+        loadLatestVerificationPlan(paths)
+    ]);
+    const contextUtility = await loadLatestContextUtilityScore(paths);
+    const verification = deriveVerification(ledger);
+    const blockers = deriveBlockers({ state, ledger, verification });
+    return {
+        schemaVersion: "martin.workflow.handoff.compaction.v1",
+        sourceManifestDigest: hashCanonicalJson(sources),
+        sources,
+        state: {
+            phase: state?.phase,
+            currentAttempt: state?.currentAttempt,
+            activeModel: state?.activeModel,
+            lastFailureSurface: state?.lastFailureSurface,
+            openAlerts: [...(state?.openAlerts ?? [])]
+        },
+        verification,
+        ...(verificationPlan ? { verificationPlan } : {}),
+        ...(contextUtility ? { contextUtility } : {}),
+        touchedSurfaces,
+        blockers,
+        nextPrompt: buildNextPrompt({
+            contract,
+            state,
+            verification,
+            verificationPlan,
+            contextUtility,
+            touchedSurfaces,
+            blockers
+        })
+    };
+}
+export async function verifyWorkflowHandoffForResume(runRoot) {
+    const paths = resolveWorkflowArtifactPathsFromRunRoot(runRoot);
+    const attestation = await verifyFileAttestation(paths.workflowHandoffJsonPath);
+    if (!attestation.ok) {
+        return {
+            ok: false,
+            reason: attestation.reason ?? "Workflow handoff attestation failed.",
+            changedSources: [],
+            attestation
+        };
+    }
+    const handoff = await readJsonIfExists(paths.workflowHandoffJsonPath);
+    if (!handoff?.compaction) {
+        return {
+            ok: false,
+            reason: "Workflow handoff compaction is missing.",
+            changedSources: [],
+            attestation
+        };
+    }
+    let currentCompaction;
+    try {
+        currentCompaction = await compactWorkflowHandoffSources(paths);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: error instanceof Error ? error.message : "Workflow handoff compaction could not be rebuilt.",
+            changedSources: [],
+            attestation
+        };
+    }
+    const changedSources = diffWorkflowSources(handoff.compaction.sources, currentCompaction.sources);
+    if (handoff.compaction.sourceManifestDigest !== currentCompaction.sourceManifestDigest ||
+        changedSources.length > 0) {
+        return {
+            ok: false,
+            reason: changedSources.length > 0
+                ? `Workflow handoff pack is stale relative to persisted workflow sources: ${changedSources.join(", ")}`
+                : "Workflow handoff pack is stale relative to persisted workflow sources.",
+            changedSources,
+            attestation
+        };
+    }
+    if (hashCanonicalJson(handoff.compaction) !== hashCanonicalJson(currentCompaction)) {
+        return {
+            ok: false,
+            reason: "Workflow handoff compaction no longer matches the rebuilt persisted workflow state.",
+            changedSources: [],
+            attestation
+        };
+    }
+    return {
+        ok: true,
+        changedSources: [],
+        attestation
+    };
+}
+function buildLocalWorkflowReceipt(loop, ledgerHash) {
+    return {
+        receiptId: `receipt_${loop.loopId}`,
+        runId: loop.loopId,
+        quoteId: `local-quote:${loop.workspaceId}`,
+        mandateId: `local-operator:${loop.projectId}`,
+        status: mapReceiptStatus(loop.lifecycleState),
+        ledgerHash,
+        createdAt: loop.updatedAt,
+        actualUsd: loop.cost.actualUsd,
+        attempts: loop.attempts.length
+    };
+}
+function mapReceiptStatus(lifecycleState) {
+    switch (lifecycleState) {
+        case "completed":
+            return "completed";
+        case "human_escalation":
+            return "denied";
+        case "session_timeout":
+        case "wall_clock_exceeded":
+            return "expired";
+        default:
+            return "failed";
+    }
+}
+function determineNextAction(lifecycleState) {
+    switch (lifecycleState) {
+        case "completed":
+            return "Review receipt and merge only after verifier evidence is accepted.";
+        case "human_escalation":
+            return "Human review required before any follow-up run.";
+        case "session_timeout":
+        case "wall_clock_exceeded":
+            return "Resume from checkpoint or narrow the task before re-running.";
+        case "stagnation_detected":
+        case "diminishing_returns":
+        case "stuck_exit":
+            return "Tighten the task or switch the route before retrying.";
+        default:
+            return "Inspect the handoff, verify the loop record, and decide whether to retry.";
+    }
+}
+async function writeJson(path, value) {
+    await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+async function readJsonIfExists(path) {
+    try {
+        const raw = await readFile(path, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readLedgerEvents(path) {
+    const raw = await readFile(path, "utf8").catch(() => "");
+    if (raw.trim().length === 0) {
+        return [];
+    }
+    return raw
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .flatMap((line) => {
+        try {
+            return [JSON.parse(line)];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+async function collectWorkflowSourceDigests(paths) {
+    const sources = [];
+    await pushSourceDigest(sources, paths.runRoot, paths.contractPath, "contract");
+    await pushSourceDigest(sources, paths.runRoot, paths.statePath, "state");
+    await pushSourceDigest(sources, paths.runRoot, paths.ledgerPath, "ledger");
+    await pushSourceDigest(sources, paths.runRoot, paths.contextUtilityScorePath, "artifact");
+    const artifactFiles = await collectArtifactFiles(paths.artifactsRoot);
+    for (const artifactPath of artifactFiles) {
+        await pushSourceDigest(sources, paths.runRoot, artifactPath, "artifact");
+    }
+    return sources.sort((left, right) => left.path.localeCompare(right.path));
+}
+async function pushSourceDigest(sources, runRoot, filePath, kind) {
+    const raw = await readFile(filePath).catch(() => undefined);
+    if (!raw) {
+        return;
+    }
+    sources.push({
+        path: normalizeRelativePath(runRoot, filePath),
+        kind,
+        sha256: createHash("sha256").update(raw).digest("hex")
+    });
+}
+async function collectArtifactFiles(root) {
+    const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+    const files = [];
+    for (const entry of entries) {
+        const entryPath = join(root, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await collectArtifactFiles(entryPath)));
+            continue;
+        }
+        if (entry.isFile() &&
+            !entry.name.endsWith(".signature.json") &&
+            !entry.name.endsWith(".public.pem")) {
+            files.push(entryPath);
+        }
+    }
+    return files.sort((left, right) => normalizePath(left).localeCompare(normalizePath(right)));
+}
+async function collectTouchedSurfaces(artifactsRoot) {
+    const artifactFiles = await collectArtifactFiles(artifactsRoot);
+    const surfaces = new Set();
+    for (const artifactPath of artifactFiles) {
+        if (!artifactPath.endsWith("scope-surface.json")) {
+            continue;
+        }
+        const scopeSurface = await readJsonIfExists(artifactPath);
+        if (!scopeSurface) {
+            continue;
+        }
+        for (const surface of [
+            ...(scopeSurface.allChangedPaths ?? []),
+            ...(scopeSurface.trackedChangedPaths ?? []),
+            ...(scopeSurface.deletedPaths ?? []),
+            ...(scopeSurface.newUntrackedPaths ?? [])
+        ]) {
+            if (typeof surface === "string" && surface.trim().length > 0) {
+                surfaces.add(normalizePath(surface));
+            }
+        }
+    }
+    return [...surfaces].sort((left, right) => left.localeCompare(right));
+}
+function deriveVerification(ledger) {
+    const event = [...ledger]
+        .reverse()
+        .find((entry) => entry.kind === "verification.completed");
+    const passed = event?.payload["passed"] === true;
+    const summary = asText(event?.payload["summary"]) ??
+        (passed ? "Verification passed." : "No verification result recorded.");
+    return {
+        status: passed ? "verified" : "unverified",
+        summary,
+        ...(event?.attemptIndex !== undefined ? { attemptIndex: event.attemptIndex } : {})
+    };
+}
+function deriveBlockers(input) {
+    const blockers = new Map();
+    const lastDecisionEvent = [...input.ledger]
+        .reverse()
+        .find((event) => event.kind === "attempt.discarded" || event.kind === "attempt.rejected");
+    const exitEvent = [...input.ledger]
+        .reverse()
+        .find((event) => event.kind === "run.exited");
+    if (input.verification.status !== "verified") {
+        const decisionReason = asText(lastDecisionEvent?.payload["reason"]);
+        if (decisionReason) {
+            blockers.set(decisionReason, true);
+        }
+        const exitReason = asText(exitEvent?.payload["reason"]);
+        if (exitReason) {
+            blockers.set(exitReason, true);
+        }
+        for (const alert of input.state?.openAlerts ?? []) {
+            blockers.set(alert, true);
+        }
+        const lastPolicyReason = input.state?.policyHistory.at(-1)?.reason;
+        if (lastPolicyReason) {
+            blockers.set(lastPolicyReason, true);
+        }
+    }
+    return [...blockers.keys()];
+}
+function buildNextPrompt(input) {
+    const objective = input.contract?.task.objective ?? "Objective unavailable.";
+    const verificationPlan = input.verificationPlan;
+    const phase = input.state?.phase ?? "UNKNOWN";
+    const nextStep = input.verification.status === "verified"
+        ? "Review the persisted evidence and prepare the verified handoff."
+        : "Resume from persisted evidence only, keep the patch bounded to the touched surfaces, and clear the highest-priority blocker before re-running verification.";
+    return [
+        "Resume Martin Loop from persisted workflow evidence only.",
+        `Objective: ${objective}`,
+        `Phase: ${phase}`,
+        `Verification: ${input.verification.status} - ${input.verification.summary}`,
+        ...(verificationPlan
+            ? [
+                `Verification tier: ${verificationPlan.tier ?? "standard"} (${verificationPlan.mustPassAll ? "must-pass-all" : "best-effort"})`,
+                `Verification summary: ${verificationPlan.summary}`
+            ]
+            : []),
+        `Context utility: ${formatContextUtilityPromptLine(input.contextUtility)}`,
+        ...formatContextUtilityActionLines(input.contextUtility),
+        `Touched surfaces: ${input.touchedSurfaces.length > 0 ? input.touchedSurfaces.join(", ") : "none recorded"}`,
+        `Blockers: ${input.blockers.length > 0 ? input.blockers.join("; ") : "none recorded"}`,
+        "Verification plan:",
+        ...(verificationPlan
+            ? [
+                ...verificationPlan.requiredChecks.map((command) => `- required: ${command}`),
+                ...verificationPlan.optionalChecks.map((command) => `- optional: ${command}`)
+            ]
+            : (input.contract?.task.verificationPlan ?? []).map((command) => `- ${command}`)),
+        ...(verificationPlan || (input.contract?.task.verificationPlan?.length ?? 0) > 0
+            ? []
+            : ["- No verification plan recorded."]),
+        `Next step: ${nextStep}`
+    ].join("\n");
+}
+function resolveRenderedVerificationPlan(loop, compaction) {
+    if (!compaction.verificationPlan) {
+        return [...loop.task.verificationPlan];
+    }
+    return [
+        ...compaction.verificationPlan.requiredChecks,
+        ...compaction.verificationPlan.optionalChecks.map((command) => `${command} (optional)`)
+    ];
+}
+function diffWorkflowSources(expected, actual) {
+    const actualByPath = new Map(actual.map((entry) => [entry.path, entry]));
+    const changed = new Set();
+    for (const expectedEntry of expected) {
+        const actualEntry = actualByPath.get(expectedEntry.path);
+        if (!actualEntry ||
+            actualEntry.kind !== expectedEntry.kind ||
+            actualEntry.sha256 !== expectedEntry.sha256) {
+            changed.add(expectedEntry.path);
+        }
+    }
+    const expectedPaths = new Set(expected.map((entry) => entry.path));
+    for (const actualEntry of actual) {
+        if (!expectedPaths.has(actualEntry.path)) {
+            changed.add(actualEntry.path);
+        }
+    }
+    return [...changed].sort((left, right) => left.localeCompare(right));
+}
+function resolveWorkflowArtifactPathsFromRunRoot(runRoot) {
+    const normalizedRunRoot = runRoot.replace(/[\\\/]+$/u, "");
+    return {
+        runRoot: normalizedRunRoot,
+        contractPath: join(normalizedRunRoot, "contract.json"),
+        statePath: join(normalizedRunRoot, "state.json"),
+        loopRecordPath: join(normalizedRunRoot, "loop-record.json"),
+        loopRecordSignaturePath: join(normalizedRunRoot, "loop-record.signature.json"),
+        loopRecordPublicKeyPath: join(normalizedRunRoot, "loop-record.public.pem"),
+        ledgerPath: join(normalizedRunRoot, "ledger.jsonl"),
+        artifactsRoot: join(normalizedRunRoot, "artifacts"),
+        contextUtilityScorePath: join(normalizedRunRoot, "context-utility-score.json"),
+        workflowReceiptPath: join(normalizedRunRoot, "workflow-receipt.json"),
+        workflowHandoffJsonPath: join(normalizedRunRoot, "workflow-handoff.json"),
+        workflowHandoffMarkdownPath: join(normalizedRunRoot, "workflow-handoff.md")
+    };
+}
+function renderContextUtilityMarkdown(contextUtility) {
+    return [
+        `- Score: ${String(contextUtility.utilityScore)}/100 (\`${contextUtility.utilityBand}\`)`,
+        `- Summary: ${contextUtility.summary}`,
+        `- Evidence: ${String(contextUtility.evidenceCounts.memoryEntryCount)} memory, ${String(contextUtility.evidenceCounts.requiredCheckCount)} required checks, ${String(contextUtility.evidenceCounts.optionalCheckCount)} optional checks, ${String(contextUtility.evidenceCounts.anomalyCount)} anomalies, ${String(contextUtility.evidenceCounts.touchedSurfaceCount)} touched surfaces`,
+        ...contextUtility.actions.map((action) => `- ${formatContextUtilityAction(action)}`)
+    ];
+}
+function formatContextUtilityPromptLine(contextUtility) {
+    if (!contextUtility) {
+        return "not recorded";
+    }
+    return `${String(contextUtility.utilityScore)}/100 (${contextUtility.utilityBand}) - ${contextUtility.summary}`;
+}
+function formatContextUtilityActionLines(contextUtility) {
+    if (!contextUtility || contextUtility.actions.length === 0) {
+        return [];
+    }
+    return contextUtility.actions.map((action) => `Context action: ${formatContextUtilityAction(action)}`);
+}
+function formatContextUtilityAction(action) {
+    const drawerIds = action.drawerIds && action.drawerIds.length > 0
+        ? ` [${action.drawerIds.join(", ")}]`
+        : "";
+    return `${action.type}${drawerIds}: ${action.message}`;
+}
+async function persistContextUtilityScore(paths, martinHome, now) {
+    const latestAttemptIndex = await resolveLatestAttemptIndex(paths.artifactsRoot);
+    if (latestAttemptIndex === undefined) {
+        return;
+    }
+    const attemptRoot = join(paths.artifactsRoot, formatAttemptDir(latestAttemptIndex));
+    const compiledContext = await readRequiredJson(join(attemptRoot, "compiled-context.json"), `compiled context for latest attempt ${formatAttemptLabel(latestAttemptIndex)}`);
+    const score = computeContextUtilityScore({
+        attemptIndex: latestAttemptIndex,
+        compiledContext: compiledContext,
+        verificationPlan: await readJsonIfExists(join(attemptRoot, "verification-plan.json")),
+        patterns: await readJsonIfExists(join(attemptRoot, "patterns.json")),
+        scopeSurface: await readJsonIfExists(join(attemptRoot, "scope-surface.json"))
+    });
+    await writeJson(paths.contextUtilityScorePath, score);
+    await signFileAttestation(paths.contextUtilityScorePath, {
+        martinHome,
+        now
+    });
+}
+async function loadLatestContextUtilityScore(paths) {
+    const latestAttemptIndex = await resolveLatestAttemptIndex(paths.artifactsRoot);
+    if (latestAttemptIndex === undefined) {
+        return undefined;
+    }
+    const score = await readRequiredJson(paths.contextUtilityScorePath, `context utility score for latest attempt ${formatAttemptLabel(latestAttemptIndex)}`);
+    if (score.schemaVersion !== "martin.context-utility-score.v1") {
+        throw new Error("Context utility score artifact has an unsupported schema version.");
+    }
+    if (score.attemptIndex !== latestAttemptIndex) {
+        throw new Error(`Context utility score does not match the latest attempt ${formatAttemptLabel(latestAttemptIndex)}; refusing to reuse a stale older score.`);
+    }
+    return score;
+}
+async function loadLatestVerificationPlan(paths) {
+    const latestAttemptIndex = await resolveLatestAttemptIndex(paths.artifactsRoot);
+    if (latestAttemptIndex === undefined) {
+        return undefined;
+    }
+    const attemptRoot = join(paths.artifactsRoot, formatAttemptDir(latestAttemptIndex));
+    const rawPlan = await readJsonIfExists(join(attemptRoot, "verification-plan.json"));
+    return normalizeVerificationPlanSummary(rawPlan);
+}
+async function resolveLatestAttemptIndex(artifactsRoot) {
+    const entries = await readdir(artifactsRoot, { withFileTypes: true }).catch(() => []);
+    const attemptIndexes = entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => parseAttemptIndex(entry.name))
+        .filter((value) => value !== undefined);
+    if (attemptIndexes.length === 0) {
+        return undefined;
+    }
+    return Math.max(...attemptIndexes);
+}
+function parseAttemptIndex(name) {
+    const match = /^attempt-(\d+)$/u.exec(name);
+    return match ? Number.parseInt(match[1] ?? "", 10) : undefined;
+}
+function formatAttemptDir(attemptIndex) {
+    return `attempt-${String(attemptIndex).padStart(3, "0")}`;
+}
+function formatAttemptLabel(attemptIndex) {
+    return formatAttemptDir(attemptIndex);
+}
+async function readRequiredJson(path, label) {
+    try {
+        const raw = await readFile(path, "utf8");
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`Unable to read ${label}: ${detail}`);
+    }
+}
+function normalizeRelativePath(root, path) {
+    return normalizePath(relative(root, path));
+}
+function normalizePath(value) {
+    return value.replace(/\\/g, "/");
+}
+function hashCanonicalJson(value) {
+    return createHash("sha256")
+        .update(JSON.stringify(value), "utf8")
+        .digest("hex");
+}
+function asText(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+function normalizeVerificationPlanSummary(value) {
+    if (!value || typeof value !== "object") {
+        return undefined;
+    }
+    const candidate = value;
+    const requiredChecks = uniqueStrings([
+        ...readStringArray(candidate["requiredChecks"]),
+        ...readStringArray(candidate["requiredCommands"]),
+        ...readStringArray(candidate["verificationPlan"])
+    ]);
+    const optionalChecks = uniqueStrings([
+        ...readStringArray(candidate["optionalChecks"]),
+        ...readStringArray(candidate["optionalCommands"])
+    ]).filter((command) => !requiredChecks.includes(command));
+    const requiredVerifiers = uniqueStrings(readStringArray(candidate["requiredVerifiers"]));
+    const tier = asText(candidate["tier"]);
+    const mustPassAll = candidate["mustPassAll"] === true;
+    const summary = asText(candidate["summary"]) ??
+        buildVerificationPlanSummary({
+            tier,
+            mustPassAll,
+            requiredChecks,
+            optionalChecks,
+            requiredVerifiers
+        });
+    if (requiredChecks.length === 0 &&
+        optionalChecks.length === 0 &&
+        requiredVerifiers.length === 0) {
+        return undefined;
+    }
+    return {
+        ...(tier ? { tier } : {}),
+        mustPassAll,
+        requiredChecks,
+        optionalChecks,
+        requiredVerifiers,
+        summary
+    };
+}
+function buildVerificationPlanSummary(input) {
+    return [
+        `${input.tier ?? "standard"} verification`,
+        input.mustPassAll ? "must pass all required checks" : "permits best-effort optional checks",
+        `${String(input.requiredChecks.length)} required command(s)`,
+        `${String(input.optionalChecks.length)} optional command(s)`,
+        `${String(input.requiredVerifiers.length)} verifier role(s)`
+    ].join(", ");
+}
+function uniqueStrings(values) {
+    return [...new Set(values.filter((value) => value.trim().length > 0))];
+}
+function readStringArray(value) {
+    return Array.isArray(value)
+        ? value.filter((entry) => typeof entry === "string")
+        : [];
+}
+//# sourceMappingURL=workflow-artifacts.js.map