@tea-agent/loop-agent 0.39.0-beta.7 → 0.39.0-beta.9

package/dist/task/source-prepare/ledger.js

@@ -0,0 +1,545 @@
+import { createHash } from "node:crypto";
+import { buildFragmentInventory, FRAGMENT_ID_PATTERN, FRAGMENT_ID_PREFIX, normalizeFragmentText, sha256Text, } from "./fragment-inventory.js";
+import { mergeInventoryItems, reconcileLedgerFragments, } from "./ledger-reconciliation.js";
+import { LEDGER_SCHEMA_RECONCILER_VERSION, LEDGER_SCHEMA_VERSION, } from "./types.js";
+function canonicalizeJsonValue(value) {
+    if (value === null)
+        return "null";
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "number")
+        return String(value);
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalizeJsonValue).join(",")}]`;
+    }
+    if (typeof value === "object") {
+        const record = value;
+        return `{${Object.keys(record)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonicalizeJsonValue(record[key])}`)
+            .join(",")}}`;
+    }
+    return "undefined";
+}
+export function sha256OfCanonicalJson(value) {
+    return createHash("sha256").update(canonicalizeJsonValue(value)).digest("hex");
+}
+/**
+ * 输入 digest：规范化源文档（path+content）+ canonical requirements +
+ * schema/reconciler version 的确定性摘要；派生导航视图 需求.md 投影不参与键计算。
+ * 账本复用键：相同 digest → 不重建（复用）；不同 → 立即失效重建。
+ */
+export function computeLedgerInputDigest(input) {
+    return sha256OfCanonicalJson({
+        schemaVersion: input.schemaVersion ?? LEDGER_SCHEMA_VERSION,
+        reconcilerVersion: input.reconcilerVersion ?? LEDGER_SCHEMA_RECONCILER_VERSION,
+        sources: input.sourceDocuments
+            .map((doc) => ({ path: doc.path, content: doc.content.replace(/\r\n/g, "\n") }))
+            .sort((a, b) => a.path.localeCompare(b.path)),
+        canonicalRequirements: input.canonicalRequirements
+            .map((req) => ({ id: req.id, text: req.text }))
+            .sort((a, b) => a.id.localeCompare(b.id)),
+    });
+}
+export function isLedgerFresh(ledger, expectedInputDigest) {
+    return ledger.inputDigest === expectedInputDigest;
+}
+/**
+ * 从持久化 ledger 恢复 build 侧的权威输入合同（AC-DIGEST-001/002/003）：init-hybrid
+ * freshness 计算与 ledger build 使用完全相同的输入。canonical 侧按 build 顺序原样
+ * 保留输入 canonical requirements（id/text 逐字节），过滤物化 REQ-SRC-*（AC-HARD-002
+ * "物化不入键"不变量）即精确恢复 digest 输入集；source 侧原样返回权威 sourcePaths
+ * （repo-root relative POSIX，build 时 sourceDocuments 的路径集合）。
+ */
+export function recoverLedgerInputContract(ledger) {
+    return {
+        sourcePaths: [...ledger.sourcePaths],
+        canonicalRequirements: ledger.canonicalRequirements
+            .filter((requirement) => !requirement.id.startsWith(`${FRAGMENT_ID_PREFIX}-`))
+            .map((requirement) => ({
+            id: requirement.id,
+            text: requirement.text,
+        })),
+    };
+}
+/**
+ * 从派生 需求.md 中确定性移除 `## Source ledger` 区块，得到不含该区块的规范化
+ * 投影（供派生视图 requirementSha256 审计计算使用；不再参与 inputDigest）。
+ * 投影器写入的区块结构固定（标题 + 引用块 + 列表），故剥离是确定性的。
+ */
+export function stripLedgerSection(markdown) {
+    const lines = markdown.replace(/\r\n/g, "\n").split("\n");
+    const sectionStart = lines.findIndex((line) => /^##\s+Source ledger\s*$/u.test(line.trim()));
+    if (sectionStart < 0)
+        return markdown.replace(/\r\n/g, "\n");
+    let sectionEnd = lines.length;
+    for (let index = sectionStart + 1; index < lines.length; index += 1) {
+        if (/^##\s+/u.test(lines[index] ?? "")) {
+            sectionEnd = index;
+            break;
+        }
+    }
+    const kept = lines.slice(0, sectionStart);
+    // 移除区块前的一个空行分隔，再规范化尾部。
+    while (kept.length > 0 && kept[kept.length - 1]?.trim() === "") {
+        kept.pop();
+    }
+    return kept.join("\n") + "\n";
+}
+/**
+ * 与当前账本 conflict/fragment identity 匹配、human-confirmed 且带明确 decision
+ * 的 resolution 才有效（AC-008 / AC-FIDELITY-REPAIR-008）。stale（sourceRef 不匹配
+ * 任何当前冲突/片段）、伪造（decidedBy ≠ human）或缺少 decision 的 resolution 不生效。
+ */
+export function effectiveSourceResolutions(ledger) {
+    const conflictIds = new Set(ledger.conflicts.map((entry) => entry.id));
+    const fragmentIds = new Set(ledger.fragments.map((record) => record.id));
+    const effective = new Set();
+    for (const resolution of ledger.sourceResolutions ?? []) {
+        if (resolution.decidedBy !== "human")
+            continue;
+        if (!resolution.decision?.trim())
+            continue;
+        if (conflictIds.has(resolution.sourceRef) ||
+            fragmentIds.has(resolution.sourceRef)) {
+            effective.add(resolution.sourceRef);
+        }
+    }
+    return effective;
+}
+/**
+ * 显式 AC 冲突（AC-007 / AC-HARD-001）：同 ID 不同文本的每个冲突文本保留独立
+ * fragment identity（path/lineRange/sha256），绝不互相覆盖；同一规范化文本的多个
+ * 片段保留首个 identity（去重），texts 与 fragments 顺序一致、一一对应。
+ */
+function computeExplicitAcConflicts(input) {
+    const identityById = new Map();
+    for (const record of input.records) {
+        const explicit = /^AC(?:-[A-Z0-9]+)+$/iu.test(record.id)
+            ? record.id
+            : null;
+        if (!explicit)
+            continue;
+        const rawFragment = input.fragments.find((fragment) => fragment.id === record.id &&
+            fragment.path === record.path &&
+            fragment.lineRange.start === record.lineRange.start &&
+            fragment.lineRange.end === record.lineRange.end);
+        const rawText = rawFragment?.text ?? record.id;
+        const text = normalizeFragmentText(rawText);
+        const identities = identityById.get(explicit) ?? new Map();
+        if (!identities.has(text)) {
+            identities.set(text, {
+                path: record.path,
+                lineRange: record.lineRange,
+                sha256: record.sha256,
+                text: rawText,
+            });
+        }
+        identityById.set(explicit, identities);
+    }
+    return [...identityById.entries()]
+        .map(([id, identities]) => ({
+        id,
+        texts: [...identities.keys()],
+        fragments: [...identities.values()],
+    }))
+        .filter((entry) => entry.texts.length > 1);
+}
+/**
+ * 高维规范性 disposition（AC-002 / AC-HARD-002）：requirement/acceptance/
+ * constraint/non-goal/unresolved 可执行内容均为高风险，必须被表示/映射；
+ * context-only / duplicate 为排除类 disposition，不走高风险未覆盖判定。
+ */
+export const HIGH_RISK_FRAGMENT_DISPOSITIONS = new Set([
+    "requirement",
+    "acceptance",
+    "constraint",
+    "non-goal",
+    "unresolved",
+]);
+/**
+ * 物化稳定 REQ-SRC-* canonical requirement id（AC-002 / AC-HARD-002）：无既有
+ * canonical 匹配的高风险规范性片段由既有 generatedFragmentId 确定性哈希物化；
+ * 显式 AC id（如 AC-999）不在 canonical 集合时派生独立 REQ-SRC-* id。纯哈希派生、
+ * 不依赖遍历顺序，同一输入跨 run 恒等复现。
+ */
+export function materializedCanonicalRequirementId(record) {
+    if (/^REQ-SRC-/.test(record.id))
+        return record.id;
+    const digest = sha256Text(`materialized-canonical\u0000${record.id}\u0000${record.text}`);
+    return `${FRAGMENT_ID_PREFIX}-${digest.slice(0, 12).toUpperCase()}`;
+}
+/**
+ * 构建完整 requirement ledger：fragment inventory + disposition + 覆盖映射 + 统计。
+ * 完全确定性：相同输入产出 byte 一致结果（builtAt 由 inputDigest 确定性派生，
+ * 保证 DAG 生成期与 apply 期哈希一致）。reconcile executor 提供时仅叙述性/歧义
+ * 片段经顺序 reconciliation，失败即 fail closed。
+ */
+export async function buildRequirementLedger(input) {
+    const inventory = buildFragmentInventory({
+        documents: input.sourceDocuments,
+        canonicalRequirements: input.canonicalRequirements,
+    });
+    let records = inventory.records;
+    if (input.reconcile?.executor) {
+        const items = mergeInventoryItems({
+            records: inventory.records,
+            fragments: inventory.fragments,
+        });
+        const reconciled = await reconcileLedgerFragments({
+            fragments: items,
+            canonicalRequirements: input.canonicalRequirements,
+            executor: input.reconcile.executor,
+            ...(input.reconcile.budgetChars !== undefined
+                ? { budgetChars: input.reconcile.budgetChars }
+                : {}),
+        });
+        const shaById = new Map(inventory.records.map((record) => [record.id, record.sha256]));
+        records = reconciled.fragments.map((item) => ({
+            id: item.id,
+            path: item.path,
+            headingPath: item.headingPath,
+            lineRange: item.lineRange,
+            sha256: shaById.get(item.id) ?? sha256Text(item.text),
+            risk: item.risk,
+            disposition: item.disposition,
+            ...(item.reason ? { reason: item.reason } : {}),
+            canonicalRequirementIds: item.canonicalRequirementIds,
+        }));
+    }
+    const allResolutions = input.sourceResolutions ?? [];
+    // duplicate 保留全部来源：duplicate 片段仍计入 fragments 与 sourcePaths。
+    const duplicates = records.filter((record) => record.disposition === "duplicate");
+    const rawConflicts = computeExplicitAcConflicts({
+        records,
+        fragments: inventory.fragments,
+    });
+    const conflictIds = new Set(rawConflicts.map((entry) => entry.id));
+    const fragmentIds = new Set(records.map((record) => record.id));
+    // 有效 resolution：human-confirmed + 明确 decision + 匹配当前冲突/片段 identity。
+    const effectiveResolutions = allResolutions.filter((resolution) => resolution.decidedBy === "human" &&
+        resolution.decision?.trim().length > 0 &&
+        (conflictIds.has(resolution.sourceRef) ||
+            fragmentIds.has(resolution.sourceRef)));
+    const resolvedSourceRefs = new Set(effectiveResolutions.map((resolution) => resolution.sourceRef));
+    // 物化（AC-002 / AC-HARD-002）：无既有 canonical 匹配的高风险规范性片段
+    // （requirement/acceptance/constraint/non-goal/unresolved 可执行内容）确定性
+    // 物化为稳定 REQ-SRC-* canonical requirement，绝不保留空 canonicalRequirementIds。
+    // 物化结果只进入 ledger 输出（ledger.canonicalRequirements / fragmentsByRequirement），
+    // 不改 computeLedgerInputDigest 输入集合（避免 SOURCE_FIDELITY_LEDGER_STALE）。
+    const fragmentTextById = new Map(inventory.fragments.map((fragment) => [fragment.id, fragment.text]));
+    const materialized = [];
+    const materializedIds = new Set();
+    const materializedRecords = records.map((record) => {
+        if (HIGH_RISK_FRAGMENT_DISPOSITIONS.has(record.disposition) &&
+            !resolvedSourceRefs.has(record.id) &&
+            record.canonicalRequirementIds.length === 0) {
+            const rawText = fragmentTextById.get(record.id) ?? record.id;
+            const canonicalId = materializedCanonicalRequirementId({
+                id: record.id,
+                text: rawText,
+            });
+            if (!materializedIds.has(canonicalId)) {
+                materializedIds.add(canonicalId);
+                materialized.push({ id: canonicalId, text: rawText });
+            }
+            return { ...record, canonicalRequirementIds: [canonicalId] };
+        }
+        return record;
+    });
+    const unresolved = materializedRecords.filter((record) => record.disposition === "unresolved" &&
+        !resolvedSourceRefs.has(record.id));
+    // 高风险未覆盖：全部高维 disposition（AC-002），空映射保持阻断。
+    const highRiskUncovered = materializedRecords.filter((record) => {
+        if (resolvedSourceRefs.has(record.id))
+            return false;
+        return (HIGH_RISK_FRAGMENT_DISPOSITIONS.has(record.disposition) &&
+            record.canonicalRequirementIds.length === 0);
+    });
+    const conflicts = rawConflicts.filter((entry) => !resolvedSourceRefs.has(entry.id));
+    // canonical → fragments 映射（含物化 REQ-SRC-* canonical；任何已映射片段都
+    // 贡献来源证据，不再仅限 acceptance disposition）。
+    const fragmentsByRequirement = new Map();
+    for (const record of materializedRecords) {
+        for (const reqId of record.canonicalRequirementIds) {
+            const ids = fragmentsByRequirement.get(reqId) ?? [];
+            if (!ids.includes(record.id))
+                ids.push(record.id);
+            fragmentsByRequirement.set(reqId, ids);
+        }
+    }
+    const sourceRefsFor = (fragmentIdsForRequirement) => [
+        ...new Set(fragmentIdsForRequirement
+            .map((fragmentId) => materializedRecords.find((r) => r.id === fragmentId)
+            ?.path ?? "")
+            .filter((path) => path.length > 0)),
+    ];
+    const canonicalRequirements = [
+        ...input.canonicalRequirements.map((req) => ({
+            id: req.id,
+            text: req.text,
+            sourceFragmentIds: fragmentsByRequirement.get(req.id) ?? [],
+            sourceRefs: sourceRefsFor(fragmentsByRequirement.get(req.id) ?? []),
+        })),
+        // 物化 canonical requirement（确定性插入顺序 = 片段枚举顺序）。
+        ...materialized.map((req) => ({
+            id: req.id,
+            text: req.text,
+            sourceFragmentIds: fragmentsByRequirement.get(req.id) ?? [],
+            sourceRefs: sourceRefsFor(fragmentsByRequirement.get(req.id) ?? []),
+        })),
+    ];
+    const stats = {
+        fragmentCount: records.length,
+        canonicalRequirementCount: canonicalRequirements.length,
+        acceptanceCount: records.filter((record) => record.disposition === "acceptance").length,
+        requirementCount: records.filter((record) => record.disposition === "requirement").length,
+        contextOnlyCount: records.filter((record) => record.disposition === "context-only").length,
+        duplicateCount: duplicates.length,
+        unresolvedCount: unresolved.length,
+        conflictCount: conflicts.length,
+        highRiskUncoveredCount: highRiskUncovered.length,
+    };
+    const inputDigest = computeLedgerInputDigest({
+        sourceDocuments: input.sourceDocuments,
+        canonicalRequirements: input.canonicalRequirements,
+    });
+    // builtAt 必须是确定性的：若未显式给定，由 inputDigest 派生固定时间戳，
+    // 使同一输入在任意时间构建的账本字节一致（binding ledgerSha256 可比对）。
+    const builtAt = input.builtAt ??
+        new Date(1_600_000_000_000 + (parseInt(inputDigest.slice(0, 8), 16) % 300_000_000_000))
+            .toISOString();
+    return {
+        schemaVersion: LEDGER_SCHEMA_VERSION,
+        taskId: input.taskId,
+        inputDigest,
+        requirementSha256: input.requirementSha256,
+        sourcePaths: input.sourceDocuments
+            .map((doc) => doc.path)
+            .sort((a, b) => a.localeCompare(b)),
+        fragments: materializedRecords,
+        canonicalRequirements,
+        stats,
+        unresolved: unresolved.map((record) => ({
+            fragmentId: record.id,
+            reason: record.reason ?? "unresolved fragment",
+        })),
+        conflicts,
+        sourceResolutions: allResolutions,
+        schemaReconcilerVersion: LEDGER_SCHEMA_RECONCILER_VERSION,
+        builtAt,
+    };
+}
+/** 验证账本完整性：无效路径/行号/hash/伪造 fragment ID、缺失 canonical 覆盖、
+ * unresolved/conflict（有效 human resolution 覆盖的项不阻断）。 */
+export function validateRequirementLedger(ledger, options) {
+    const errors = [];
+    const allowedUnresolved = options?.allowedUnresolved ?? false;
+    const allowedConflicts = options?.allowedConflicts ?? false;
+    if (ledger.schemaVersion !== LEDGER_SCHEMA_VERSION) {
+        errors.push({
+            code: "SOURCE_FIDELITY_RECONCILIATION_FAILED",
+            message: `ledger schemaVersion ${ledger.schemaVersion} is not supported`,
+        });
+    }
+    if (ledger.schemaReconcilerVersion !== LEDGER_SCHEMA_RECONCILER_VERSION) {
+        errors.push({
+            code: "SOURCE_FIDELITY_RECONCILIATION_FAILED",
+            message: `ledger reconciler version ${ledger.schemaReconcilerVersion} does not match ${LEDGER_SCHEMA_RECONCILER_VERSION}`,
+        });
+    }
+    for (const record of ledger.fragments) {
+        if (!record.id ||
+            !record.path ||
+            !Number.isInteger(record.lineRange.start) ||
+            !Number.isInteger(record.lineRange.end) ||
+            record.lineRange.start < 1 ||
+            record.lineRange.end < record.lineRange.start) {
+            errors.push({
+                code: "SOURCE_FIDELITY_FRAGMENT_INVALID",
+                message: `fragment ${record.id} has invalid path/lineRange`,
+            });
+        }
+        if (!FRAGMENT_ID_PATTERN.test(record.id)) {
+            errors.push({
+                code: "SOURCE_FIDELITY_FRAGMENT_INVALID",
+                message: `fragment ${record.id} has a forged/unsupported fragment id (expected AC-* or REQ-SRC-*)`,
+            });
+        }
+        if (!/^[a-f0-9]{64}$/.test(record.sha256)) {
+            errors.push({
+                code: "SOURCE_FIDELITY_FRAGMENT_INVALID",
+                message: `fragment ${record.id} has invalid sha256`,
+            });
+        }
+        if ((record.disposition === "context-only" ||
+            record.disposition === "duplicate" ||
+            record.disposition === "unresolved") &&
+            !record.reason) {
+            errors.push({
+                code: "SOURCE_FIDELITY_CONTEXT_ONLY_UNREVIEWED",
+                message: `fragment ${record.id} (${record.disposition}) requires a complete exclusion reason`,
+            });
+        }
+    }
+    const canonicalIds = new Set(ledger.canonicalRequirements.map((req) => req.id));
+    // 高风险未覆盖（AC-002 / AC-HARD-002）：requirement/acceptance/constraint/
+    // non-goal/unresolved 高维 disposition 空映射即阻断；引用未知 canonical 同样阻断。
+    for (const record of ledger.fragments) {
+        if (!HIGH_RISK_FRAGMENT_DISPOSITIONS.has(record.disposition))
+            continue;
+        if (record.canonicalRequirementIds.length === 0) {
+            errors.push({
+                code: "SOURCE_FIDELITY_HIGH_RISK_UNCOVERED",
+                message: `high-risk ${record.disposition} fragment ${record.id} is not mapped to any canonical requirement`,
+            });
+        }
+        for (const reqId of record.canonicalRequirementIds) {
+            if (!canonicalIds.has(reqId)) {
+                errors.push({
+                    code: "SOURCE_FIDELITY_REQUIREMENT_NOT_COVERED",
+                    message: `fragment ${record.id} references unknown canonical requirement ${reqId}`,
+                });
+            }
+        }
+    }
+    for (const req of ledger.canonicalRequirements) {
+        if (req.sourceFragmentIds.length === 0) {
+            errors.push({
+                code: "SOURCE_FIDELITY_REQUIREMENT_NOT_COVERED",
+                message: `canonical requirement ${req.id} has no source fragment evidence`,
+            });
+        }
+        for (const fragmentId of req.sourceFragmentIds) {
+            const record = ledger.fragments.find((f) => f.id === fragmentId);
+            if (!record) {
+                errors.push({
+                    code: "SOURCE_FIDELITY_SOURCE_REF_INVALID",
+                    message: `requirement ${req.id} references missing fragment ${fragmentId}`,
+                });
+            }
+        }
+    }
+    // 有效 human resolution 覆盖的 unresolved/conflict 不阻断（audit 保留在
+    // ledger.sourceResolutions；stale/伪造/未确认 resolution 不生效）。
+    const effective = effectiveSourceResolutions(ledger);
+    const blockingUnresolved = ledger.unresolved.filter((entry) => !effective.has(entry.fragmentId));
+    if (!allowedUnresolved && blockingUnresolved.length > 0) {
+        errors.push({
+            code: "SOURCE_FIDELITY_UNRESOLVED",
+            message: `ledger has ${blockingUnresolved.length} unresolved fragment(s): ${blockingUnresolved
+                .map((entry) => entry.fragmentId)
+                .join(", ")}`,
+        });
+    }
+    const blockingConflicts = ledger.conflicts.filter((entry) => !effective.has(entry.id));
+    if (!allowedConflicts && blockingConflicts.length > 0) {
+        errors.push({
+            code: "SOURCE_FIDELITY_CONFLICT",
+            message: `ledger has ${blockingConflicts.length} conflict(s): ${blockingConflicts
+                .map((entry) => entry.id)
+                .join(", ")}`,
+        });
+    }
+    return errors;
+}
+/** 分级 gate：稳定错误码 + 阻断信息（AC-FIDELITY-003）。 */
+export function classifyLedgerGate(ledger, options) {
+    if (!isLedgerFresh(ledger, options?.expectedInputDigest ?? ledger.inputDigest)) {
+        return {
+            ok: false,
+            code: "SOURCE_FIDELITY_LEDGER_STALE",
+            message: "ledger inputDigest does not match current source input; rebuild required",
+            ledger,
+        };
+    }
+    const errors = validateRequirementLedger(ledger);
+    if (errors.length > 0) {
+        // 分级 fail-closed：按优先级表顺序取首个命中错误（AC-BLOCK-001：
+        // REQUIREMENT_NOT_COVERED 纳入优先级表；与 UNRESOLVED/CONFLICT 并存时仍由
+        // 表序决定 primary code，而不是 errors 数组顺序）。
+        const priority = [
+            "SOURCE_FIDELITY_UNRESOLVED",
+            "SOURCE_FIDELITY_CONFLICT",
+            "SOURCE_FIDELITY_HIGH_RISK_UNCOVERED",
+            "SOURCE_FIDELITY_REQUIREMENT_NOT_COVERED",
+            "SOURCE_FIDELITY_RECONCILIATION_FAILED",
+        ];
+        const first = priority
+            .map((code) => errors.find((error) => error.code === code))
+            .find((error) => error !== undefined) ?? errors[0];
+        return {
+            ok: false,
+            code: first.code,
+            message: errors.map((error) => error.message).join("; "),
+            ledger,
+        };
+    }
+    return { ok: true, ledger };
+}
+/** 安全摘要（Console/Inspect 展示，不泄漏敏感原文）。 */
+export function summarizeLedger(ledger, options) {
+    const exclusions = ledger.fragments
+        .filter((record) => record.disposition === "context-only" ||
+        record.disposition === "duplicate" ||
+        record.disposition === "unresolved")
+        .map((record) => ({
+        fragmentId: record.id,
+        reason: truncateReason(record.reason ?? record.disposition),
+    }));
+    return {
+        present: true,
+        fragmentCount: ledger.stats.fragmentCount,
+        canonicalRequirementCount: ledger.stats.canonicalRequirementCount,
+        contextOnlyCount: ledger.stats.contextOnlyCount,
+        duplicateCount: ledger.stats.duplicateCount,
+        unresolvedCount: ledger.stats.unresolvedCount,
+        conflictCount: ledger.stats.conflictCount,
+        gateStatus: options?.gateStatus ?? "unknown",
+        failureCode: options?.failureCode ?? null,
+        exclusions,
+    };
+}
+export function truncateReason(reason, max = 120) {
+    return reason.length > max ? `${reason.slice(0, max)}…` : reason;
+}
+export function ledgerStatsLine(ledger) {
+    const s = ledger.stats;
+    return [
+        `fragments=${s.fragmentCount}`,
+        `canonical=${s.canonicalRequirementCount}`,
+        `contextOnly=${s.contextOnlyCount}`,
+        `duplicate=${s.duplicateCount}`,
+        `unresolved=${s.unresolvedCount}`,
+        `conflict=${s.conflictCount}`,
+        `highRiskUncovered=${s.highRiskUncoveredCount}`,
+    ].join(" ");
+}
+/**
+ * 损坏/不支持 ledger 的结构化错误（AC-009 / AC-HARD-003）：稳定 SOURCE_FIDELITY_*
+ * 错误码 + 原因 message 的 envelope，替代裸 Error。routes 的 handleTaskLedger 解析
+ * 失败分支与 prewrite/init-hybrid 消费同一稳定码，杜绝字符串匹配裸 Error 文本。
+ */
+export class LedgerParseError extends Error {
+    code = "SOURCE_FIDELITY_LEDGER_STALE";
+    constructor(message, options) {
+        super(message, options);
+        this.name = "LedgerParseError";
+    }
+}
+export function parseLedgerJson(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new LedgerParseError("SOURCE_FIDELITY_LEDGER_STALE: requirement-ledger.json is not valid JSON");
+    }
+    const record = parsed;
+    if (record?.schemaVersion !== LEDGER_SCHEMA_VERSION) {
+        throw new LedgerParseError(`SOURCE_FIDELITY_LEDGER_STALE: unsupported requirement-ledger schemaVersion ${String(record?.schemaVersion)}`);
+    }
+    return parsed;
+}