@tea-agent/loop-agent 0.40.0-next.2 → 0.40.0-next.4

package/dist/task/source-prepare/fragment-inventory.js

@@ -0,0 +1,474 @@
+import { createHash } from "node:crypto";
+// ---------------------------------------------------------------------------
+// Deterministic fragment inventory (AC-001 / AC-FIDELITY-001)
+// 对 .md/.markdown/.txt 按标题、段落、列表项、checklist、表格行确定性切分。
+// 稳定 fragment ID：显式 AC ID 原样保留（含 `#### AC-*` 标题式）；无 ID 片段生成
+// 跨文档稳定 REQ-SRC-*（基于 path+行号+文本的确定性哈希，与文档枚举顺序无关，
+// 消除 per-document counter reset 碰撞）。不按文档前 24K 字符裁剪——尾部片段仍
+// 进入 inventory（覆盖统计证明）。
+// ---------------------------------------------------------------------------
+export const FRAGMENT_ID_PREFIX = "REQ-SRC";
+/** 生成 fragment ID 的合法形态（防伪造：拒绝自由格式 ID）。 */
+export const FRAGMENT_ID_PATTERN = /^(?:AC(?:-[A-Z0-9]+)+|REQ-SRC-[A-Z0-9-]+)$/;
+const ACCEPTANCE_HEADING_RE = /(?:^|\s)(?:验收标准|acceptance criteria|acceptance|完成标准|完成定义|验收条件|验收准则|dod|definition of done|验收)(?:\s|$)/iu;
+const CONSTRAINT_HEADING_RE = /(?:^|\s)(?:约束|constraints|invariants|不变式)(?:\s|$)/iu;
+const NON_GOAL_HEADING_RE = /(?:^|\s)(?:非目标|out of scope|non-goals|non goals)(?:\s|$)/iu;
+const OBJECTIVE_HEADING_RE = /(?:^|\s)(?:目标|objective|问题与目标|业务目标|需求概述)(?:\s|$)/iu;
+/** 可执行片段启发式（AC 风格/祈使语气）：命中则不可按 context-only 降级。 */
+const EXECUTABLE_HINT_RE = /(?:必须|应当|应支持|需要|需|不得|should|must|shall|will|require|support|implement|provide|ensure|verify|当.*?时|when.*?then)/iu;
+/** 显式 AC 式 ID 前缀：AC-001 / AC-FE-001 / AC-FE-INS-001 等（允许 bullet 标记后空格
+ * 与 checklist 勾选框）。收紧解析（AC-001 / AC-HARD-001）：AC 后必须跟分隔符
+ * （-/_）+ 大写字母/数字 id 形态（含可选 FE/BE/UI/API 作用域前缀与 V4 `#### AC-*`
+ * 标题归属）；`## Acceptance Criteria` / `## Acceptance` / Ac 开头普通单词永不产生
+ * 伪造 id（ACCEPTANCE 类 id 全量消失）。捕获组 1 = AC id，捕获组 2 = 余下文本。 */
+const EXPLICIT_AC_ID_RE = /^\s*(?:[-*+]|\d+[.)])\s+(?:\[[ xX]\]\s+)?(AC(?:[-_](?:FE|BE|UI|API))?[-_][A-Z0-9]+(?:[-_][A-Z0-9]+)*)\s*[:：]?\s*(.*)$/iu;
+/** 显式 AC 标题式：`#### AC-FE-001 Save nickname` / `### AC-001：正文`。
+ * AC 后必须跟分隔符（-/_）+ id 形态；普通单词（Acceptance Criteria / Acceptance）
+ * 永不匹配，按 ACCEPTANCE_HEADING_RE 章节分类生成稳定 REQ-SRC-* 片段。
+ * 捕获组 1 = AC id，捕获组 2 = 标题余下文本。 */
+const EXPLICIT_AC_HEADING_RE = /^\s*(AC(?:[-_](?:FE|BE|UI|API))?[-_][A-Z0-9]+(?:[-_][A-Z0-9]+)*)\s*[:：]?\s*(.*)$/iu;
+/** Markdown 表格数据行（非分隔行）。 */
+const TABLE_DATA_ROW_RE = /^\s*\|.*\|\s*$/;
+const TABLE_SEPARATOR_ROW_RE = /^\s*\|[\s:|-]+\|\s*$/;
+/** 表格表头行：数据行且下一行是分隔行（`| 列 | 列 |` + `| --- | --- |`）。 */
+function isTableHeaderRow(line, nextLine) {
+    return isTableDataRow(line) && TABLE_SEPARATOR_ROW_RE.test(nextLine.trim());
+}
+/** 表格行首格显式 AC ID：`| AC-001 | 订单列表加载完成 |` → id=AC-001, rest=订单列表加载完成。 */
+function matchTableRowAcId(line) {
+    const trimmed = line.trim().replace(/^\|/, "");
+    const cells = trimmed.split("|");
+    const first = cells[0]?.trim() ?? "";
+    const idMatch = EXPLICIT_AC_HEADING_RE.exec(first);
+    if (!idMatch)
+        return null;
+    const id = (idMatch[1] ?? "").trim().toUpperCase().replace(/_/g, "-");
+    if (!id)
+        return null;
+    const rest = cells
+        .slice(1)
+        .join("|")
+        .replace(/\|\s*$/, "")
+        .trim();
+    return { id, rest: rest || id };
+}
+export function sha256Text(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+export function normalizeFragmentText(text) {
+    return text
+        .replace(/\r\n/g, "\n")
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .join(" ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+export function matchExplicitAcId(line) {
+    const match = EXPLICIT_AC_ID_RE.exec(line.trim());
+    if (!match)
+        return null;
+    const rawId = match[1] ?? "";
+    const id = rawId.trim().toUpperCase().replace(/_/g, "-");
+    if (!id)
+        return null;
+    return { id, rest: (match[2] ?? "").trim() };
+}
+/** V4 显式 AC 标题式匹配：`#### AC-FE-001 Save nickname` → id=AC-FE-001, rest=Save nickname。 */
+export function matchExplicitAcHeading(headingText) {
+    const match = EXPLICIT_AC_HEADING_RE.exec(headingText.trim());
+    if (!match)
+        return null;
+    const rawId = match[1] ?? "";
+    const id = rawId.trim().toUpperCase().replace(/_/g, "-");
+    if (!id)
+        return null;
+    return { id, rest: (match[2] ?? "").trim() };
+}
+function isAtxHeading(line) {
+    const match = /^(#{1,6})\s+(.+?)\s*$/u.exec(line);
+    if (!match)
+        return null;
+    return { level: match[1].length, text: match[2].trim() };
+}
+function isListItem(line) {
+    return /^\s*(?:[-*+]|\d+[.)])\s+(?:\[(?: |x|X)\]\s+)?/.test(line);
+}
+function isTableDataRow(line) {
+    const trimmed = line.trim();
+    return TABLE_DATA_ROW_RE.test(trimmed) && !TABLE_SEPARATOR_ROW_RE.test(trimmed);
+}
+function classifySectionHeading(headingPath) {
+    const normalized = headingPath.toLowerCase();
+    if (ACCEPTANCE_HEADING_RE.test(normalized))
+        return "acceptance";
+    if (CONSTRAINT_HEADING_RE.test(normalized))
+        return "constraint";
+    if (NON_GOAL_HEADING_RE.test(normalized))
+        return "non-goal";
+    if (OBJECTIVE_HEADING_RE.test(normalized))
+        return "objective";
+    return "other";
+}
+/**
+ * 确定性生成 fragment ID：REQ-SRC-<sha256(path+行号+文本) 前 12 位大写>。
+ * 与文档枚举顺序无关（跨文档不碰撞、重排不换 ID），相同输入恒等复现。
+ */
+export function generatedFragmentId(pathValue, lineRange, text) {
+    const digest = sha256Text(`${pathValue}\u0000${lineRange.start}\u0000${lineRange.end}\u0000${text}`);
+    return `${FRAGMENT_ID_PREFIX}-${digest.slice(0, 12).toUpperCase()}`;
+}
+/**
+ * 将单个文档切分为标题段落（section），再按列表项/段落/表格行切分为原始片段。
+ * 完全确定性：相同输入总是产出相同片段序列。generated ID 使用跨文档稳定哈希，
+ * 不依赖文档内自增 counter（消除多文档 counter reset 碰撞）。
+ */
+export function splitDocumentIntoFragments(doc) {
+    const normalized = doc.content.replace(/\r\n/g, "\n");
+    const lines = normalized.split("\n");
+    const sections = [];
+    const headingStack = [];
+    let current = null;
+    const flushSection = (endLine) => {
+        if (!current)
+            return;
+        current.endLine = Math.max(current.startLine, endLine);
+        current.lines = lines.slice(current.startLine - 1, Math.min(current.endLine, lines.length));
+        sections.push(current);
+        current = null;
+    };
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index] ?? "";
+        const heading = isAtxHeading(line);
+        if (heading) {
+            flushSection(index - 1);
+            while (headingStack.length > 0 &&
+                headingStack[headingStack.length - 1].level >= heading.level) {
+                headingStack.pop();
+            }
+            headingStack.push({ level: heading.level, text: heading.text });
+            current = {
+                headingPath: headingStack.map((h) => h.text).join(" > "),
+                level: heading.level,
+                startLine: index + 1,
+                endLine: index + 1,
+                lines: [],
+            };
+            continue;
+        }
+        if (!current) {
+            current = {
+                headingPath: "",
+                level: 0,
+                startLine: index + 1,
+                endLine: index + 1,
+                lines: [],
+            };
+        }
+    }
+    flushSection(lines.length);
+    const rawFragments = [];
+    for (const section of sections) {
+        // V4 显式 AC 标题（`#### AC-*`）本身即验收段：标题行的 ID 原样保留。
+        const lastHeadingSegment = section.headingPath.split(" > ").pop() ?? section.headingPath;
+        const explicitSectionAc = matchExplicitAcHeading(lastHeadingSegment);
+        const sectionKind = classifySectionHeading(section.headingPath);
+        const effectiveKind = explicitSectionAc ? "acceptance" : sectionKind;
+        const bodyStart = section.headingPath
+            ? section.startLine + (explicitSectionAc ? 0 : 1)
+            : section.startLine;
+        const bodyEnd = section.endLine;
+        const bodyLines = lines.slice(Math.max(0, bodyStart - 1), Math.min(bodyEnd, lines.length));
+        // 当前验收章节内最近的显式 AC ID（V4 标题或 AC 条目），正文片段继承它。
+        let pendingAcId = null;
+        const emit = (fragment) => {
+            const explicit = fragment.explicitId ?? null;
+            let id = explicit;
+            if (!id) {
+                id = generatedFragmentId(doc.path, fragment.lineRange, fragment.text);
+            }
+            rawFragments.push({
+                id,
+                path: doc.path,
+                headingPath: fragment.headingPath,
+                lineRange: fragment.lineRange,
+                text: fragment.text,
+                ...(explicit
+                    ? {}
+                    : fragment.inheritAcId && pendingAcId
+                        ? { explicitAcId: pendingAcId }
+                        : {}),
+            });
+        };
+        if (explicitSectionAc) {
+            // 标题式 AC 段：标题行本身是一个 acceptance 片段（ID 原样保留）。
+            pendingAcId = explicitSectionAc.id;
+            emit({
+                headingPath: section.headingPath,
+                lineRange: { start: section.startLine, end: section.startLine },
+                text: explicitSectionAc.rest || explicitSectionAc.id,
+                explicitId: explicitSectionAc.id,
+            });
+        }
+        if (effectiveKind === "acceptance") {
+            // acceptance 章节：每个列表项/checklist/AC 标题行/表格数据行 = 一个片段。
+            let paragraphStart = null;
+            const flushParagraph = (endLine) => {
+                if (paragraphStart === null)
+                    return;
+                const text = lines
+                    .slice(paragraphStart - 1, Math.min(endLine, lines.length))
+                    .map((line) => line.trim())
+                    .filter(Boolean)
+                    .join(" ")
+                    .trim();
+                if (text) {
+                    emit({
+                        headingPath: section.headingPath,
+                        lineRange: { start: paragraphStart, end: Math.max(paragraphStart, endLine) },
+                        text,
+                        inheritAcId: true,
+                    });
+                }
+                paragraphStart = null;
+            };
+            for (let index = bodyStart; index <= bodyEnd; index += 1) {
+                const line = lines[index - 1] ?? "";
+                const trimmed = line.trim();
+                if (!trimmed) {
+                    flushParagraph(index - 1);
+                    continue;
+                }
+                if (TABLE_SEPARATOR_ROW_RE.test(trimmed)) {
+                    // 表格分隔行不进入 inventory。
+                    flushParagraph(index - 1);
+                    continue;
+                }
+                const heading = isAtxHeading(trimmed);
+                if (heading) {
+                    flushParagraph(index - 1);
+                    const explicit = matchExplicitAcHeading(heading.text);
+                    if (explicit) {
+                        pendingAcId = explicit.id;
+                        emit({
+                            headingPath: section.headingPath,
+                            lineRange: { start: index, end: index },
+                            text: explicit.rest || explicit.id,
+                            explicitId: explicit.id,
+                        });
+                    }
+                    else {
+                        pendingAcId = null;
+                    }
+                    continue;
+                }
+                if (isTableDataRow(trimmed)) {
+                    const nextLine = lines[index] ?? "";
+                    if (isTableHeaderRow(trimmed, nextLine)) {
+                        // 表头行（后随分隔行）不进入 inventory。
+                        flushParagraph(index - 1);
+                        continue;
+                    }
+                    flushParagraph(index - 1);
+                    const rowExplicit = matchTableRowAcId(trimmed);
+                    emit({
+                        headingPath: section.headingPath,
+                        lineRange: { start: index, end: index },
+                        text: rowExplicit ? rowExplicit.rest : trimmed,
+                        explicitId: rowExplicit?.id,
+                        ...(rowExplicit ? {} : { inheritAcId: true }),
+                    });
+                    continue;
+                }
+                if (isListItem(trimmed)) {
+                    flushParagraph(index - 1);
+                    const explicit = matchExplicitAcId(trimmed);
+                    // 列表项自包含：显式 AC ID 只属于该项，不改变 heading 作用域
+                    // （pendingAcId 仅由 V4 `#### AC-*` 标题设置）。
+                    const text = explicit
+                        ? explicit.rest
+                        : trimmed.replace(/^\s*(?:[-*+]|\d+[.)])\s+/, "");
+                    if (text.trim()) {
+                        emit({
+                            headingPath: section.headingPath,
+                            lineRange: { start: index, end: index },
+                            text: text.trim(),
+                            explicitId: explicit?.id,
+                            ...(explicit ? {} : { inheritAcId: true }),
+                        });
+                    }
+                    continue;
+                }
+                if (paragraphStart === null)
+                    paragraphStart = index;
+            }
+            flushParagraph(bodyEnd);
+            continue;
+        }
+        // 非 acceptance 章节：连续非空行 = 一个段落片段（空行分隔）；表格数据行独立成片。
+        let paragraphStart = null;
+        const flushParagraph = (endLine) => {
+            if (paragraphStart === null)
+                return;
+            const text = lines
+                .slice(paragraphStart - 1, Math.min(endLine, lines.length))
+                .map((line) => line.trim())
+                .filter(Boolean)
+                .join(" ")
+                .trim();
+            if (text) {
+                emit({
+                    headingPath: section.headingPath,
+                    lineRange: { start: paragraphStart, end: Math.max(paragraphStart, endLine) },
+                    text,
+                });
+            }
+            paragraphStart = null;
+        };
+        for (let index = bodyStart; index <= bodyEnd; index += 1) {
+            const line = lines[index - 1] ?? "";
+            const trimmed = line.trim();
+            if (!trimmed) {
+                flushParagraph(index - 1);
+                continue;
+            }
+            if (isAtxHeading(trimmed)) {
+                flushParagraph(index - 1);
+                continue;
+            }
+            if (TABLE_SEPARATOR_ROW_RE.test(trimmed)) {
+                flushParagraph(index - 1);
+                continue;
+            }
+            if (isTableDataRow(trimmed)) {
+                const nextLine = lines[index] ?? "";
+                if (isTableHeaderRow(trimmed, nextLine)) {
+                    flushParagraph(index - 1);
+                    continue;
+                }
+                flushParagraph(index - 1);
+                emit({
+                    headingPath: section.headingPath,
+                    lineRange: { start: index, end: index },
+                    text: trimmed,
+                });
+                continue;
+            }
+            if (paragraphStart === null)
+                paragraphStart = index;
+        }
+        flushParagraph(bodyEnd);
+    }
+    return rawFragments;
+}
+/**
+ * 对多个原始文档确定性切分并做 disposition 分类（AC-001）。
+ * 每个非空有效片段携带稳定 fragment ID、原始路径、标题路径、行号、原文哈希、
+ * 分级风险与且仅一个 disposition。duplicate 保留全部来源。文档先按 path 排序，
+ * 使 duplicate 判定与文档枚举顺序无关（同一输入恒等复现）。
+ */
+export function buildFragmentInventory(input) {
+    const sortedDocuments = [...input.documents].sort((a, b) => a.path.localeCompare(b.path));
+    const fragments = [];
+    for (const doc of sortedDocuments) {
+        fragments.push(...splitDocumentIntoFragments(doc));
+    }
+    const canonicalById = new Map(input.canonicalRequirements.map((req) => [req.id, req.text]));
+    const canonicalTextSet = new Set(input.canonicalRequirements.map((req) => normalizeFragmentText(req.text)));
+    const seenText = new Map();
+    const records = fragments.map((fragment) => {
+        const text = normalizeFragmentText(fragment.text);
+        const sectionKind = classifySectionHeading(fragment.headingPath);
+        // 切分器已把显式 AC ID 放入 fragment.id 并从文本剥离前缀；此处从 id 恢复。
+        const explicitIdFromId = /^AC(?:-[A-Z0-9]+)+$/iu.test(fragment.id)
+            ? fragment.id
+            : null;
+        const explicit = explicitIdFromId
+            ? { id: explicitIdFromId, rest: fragment.text }
+            : matchExplicitAcId(fragment.text);
+        // V4 标题/条目下正文继承的显式 AC ID（不生成取代它的 REQ-SRC-*）。
+        const inherited = !explicit && fragment.explicitAcId
+            ? { id: fragment.explicitAcId, rest: fragment.text }
+            : null;
+        const effectiveExplicit = explicit ?? inherited;
+        const mappedIds = [];
+        if (effectiveExplicit && canonicalById.has(effectiveExplicit.id)) {
+            mappedIds.push(effectiveExplicit.id);
+        }
+        else if (effectiveExplicit && !canonicalById.has(effectiveExplicit.id)) {
+            // 显式 AC ID 但不在 canonical 集合：按文本匹配兜底，仍不中则 unresolved。
+            if (canonicalTextSet.has(text)) {
+                for (const req of input.canonicalRequirements) {
+                    if (normalizeFragmentText(req.text) === text) {
+                        mappedIds.push(req.id);
+                    }
+                }
+            }
+        }
+        else if (canonicalTextSet.has(text)) {
+            for (const req of input.canonicalRequirements) {
+                if (normalizeFragmentText(req.text) === text) {
+                    mappedIds.push(req.id);
+                }
+            }
+        }
+        let disposition;
+        let reason;
+        if (effectiveExplicit && canonicalById.has(effectiveExplicit.id) && mappedIds.length === 0) {
+            disposition = "acceptance";
+            reason = `explicit id ${effectiveExplicit.id} declared in source but canonical requirement has no fragment text match`;
+        }
+        else if (sectionKind === "acceptance" || effectiveExplicit) {
+            disposition = mappedIds.length > 0 ? "acceptance" : "unresolved";
+            if (disposition === "unresolved") {
+                reason =
+                    effectiveExplicit && !canonicalById.has(effectiveExplicit.id)
+                        ? `explicit AC id ${effectiveExplicit.id} not present in canonical requirements`
+                        : "acceptance fragment without a canonical requirement mapping";
+            }
+        }
+        else if (sectionKind === "objective") {
+            disposition = "requirement";
+        }
+        else if (sectionKind === "constraint") {
+            disposition = "constraint";
+        }
+        else if (sectionKind === "non-goal") {
+            disposition = "non-goal";
+        }
+        else {
+            const executable = EXECUTABLE_HINT_RE.test(text);
+            disposition = executable ? "unresolved" : "context-only";
+            if (disposition === "unresolved") {
+                reason = "executable fragment outside recognized requirement/acceptance section";
+            }
+            else {
+                reason = "context-only fragment; excluded from canonical requirement coverage";
+            }
+        }
+        const priorId = seenText.get(text);
+        if (priorId) {
+            disposition = "duplicate";
+            reason = `duplicate of fragment ${priorId} (duplicate 保留全部来源)`;
+        }
+        else if (!priorId && text) {
+            seenText.set(text, fragment.id);
+        }
+        const risk = disposition === "context-only" || disposition === "duplicate"
+            ? "low"
+            : "high";
+        return {
+            id: fragment.id,
+            path: fragment.path,
+            headingPath: fragment.headingPath,
+            lineRange: fragment.lineRange,
+            sha256: sha256Text(fragment.text),
+            risk,
+            disposition,
+            ...(reason ? { reason } : {}),
+            canonicalRequirementIds: mappedIds,
+        };
+    });
+    return { fragments, records, documents: sortedDocuments };
+}

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

@@ -7,4 +7,7 @@ export * from "./semantic-intake.js";
 export * from "./reference-integrity.js";
 export * from "./completeness.js";
 export * from "./build-draft.js";
+export * from "./ledger-reconciliation.js";
+export * from "./ledger-review.js";
+export * from "./source-fidelity-pi.js";
 export * from "./prepare.js";

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

@@ -0,0 +1,127 @@
+import { normalizeFragmentText } from "./fragment-inventory.js";
+// ---------------------------------------------------------------------------
+// 顺序 reconciliation（AC-006 / AC-FIDELITY-REPAIR-006）
+// 结构化确定性片段走代码映射（显式 AC ID / 文本精确匹配），绝不调用 executor；
+// 仅叙述性/歧义 chunk 调用可注入 executor，按标题顺序串行、逐块有界处理
+// （budgetChars 按 chunk 截断，绝不整文件裁 24K）。executor 超时/异常/无效
+// 返回/identity 越界一律 fail closed（SOURCE_FIDELITY_RECONCILIATION_FAILED），
+// 不回退 heuristics。
+// ---------------------------------------------------------------------------
+export const LEDGER_RECONCILIATION_DEFAULT_BUDGET_CHARS = 4000;
+export const LEDGER_RECONCILIATION_FAILED_CODE = "SOURCE_FIDELITY_RECONCILIATION_FAILED";
+/** reconciliation 失败（executor 错误/无效输出/identity 越界/重复失败）。 */
+export class LedgerReconciliationError extends Error {
+    code = LEDGER_RECONCILIATION_FAILED_CODE;
+    constructor(message, options) {
+        super(message, options);
+        this.name = "LedgerReconciliationError";
+    }
+}
+const VALID_DISPOSITIONS = new Set([
+    "requirement",
+    "acceptance",
+    "constraint",
+    "non-goal",
+    "duplicate",
+    "context-only",
+    "unresolved",
+]);
+function isExclusionDisposition(disposition) {
+    return (disposition === "context-only" ||
+        disposition === "duplicate" ||
+        disposition === "unresolved");
+}
+/**
+ * 结构化确定性片段判定：显式 AC ID 存在于 canonical 集合，或文本与任一
+ * canonical requirement 规范化后精确一致。命中则走代码映射，不调 executor。
+ */
+export function isStructuredMappableFragment(item, canonicalById, canonicalTexts) {
+    if (item.canonicalRequirementIds.length > 0)
+        return true;
+    if (/^AC(?:-[A-Z0-9]+)+$/iu.test(item.id) && canonicalById.has(item.id))
+        return true;
+    const text = normalizeFragmentText(item.text);
+    return canonicalTexts.has(text);
+}
+/**
+ * 顺序 reconciliation：仅叙述性/歧义片段（无结构化映射）调用 executor，按输入
+ * 顺序（标题顺序）串行、逐块有界。返回更新后的片段与调用日志（fixture 断言顺序）。
+ */
+export async function reconcileLedgerFragments(input) {
+    const { canonicalRequirements, executor, budgetChars = LEDGER_RECONCILIATION_DEFAULT_BUDGET_CHARS, } = input;
+    const calls = input.calls ?? [];
+    const canonicalById = new Map(canonicalRequirements.map((req) => [req.id, req.text]));
+    const canonicalTexts = new Set(canonicalRequirements.map((req) => normalizeFragmentText(req.text)));
+    const canonicalIds = new Set(canonicalById.keys());
+    const reconciled = [];
+    for (const fragment of input.fragments) {
+        if (isStructuredMappableFragment(fragment, canonicalById, canonicalTexts)) {
+            reconciled.push(fragment);
+            continue;
+        }
+        const request = {
+            fragment: {
+                id: fragment.id,
+                path: fragment.path,
+                headingPath: fragment.headingPath,
+                lineRange: fragment.lineRange,
+                text: fragment.text.slice(0, budgetChars),
+            },
+            canonicalRequirements,
+            budgetChars,
+        };
+        let result;
+        try {
+            result = await executor(request);
+        }
+        catch (error) {
+            throw new LedgerReconciliationError(`reconciliation executor failed for fragment ${fragment.id}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (!result ||
+            typeof result !== "object" ||
+            !Array.isArray(result.mappedIds) ||
+            !VALID_DISPOSITIONS.has(result.disposition)) {
+            throw new LedgerReconciliationError(`reconciliation executor returned an invalid result for fragment ${fragment.id}`);
+        }
+        const outOfBounds = result.mappedIds.filter((id) => !canonicalIds.has(id));
+        if (outOfBounds.length > 0) {
+            throw new LedgerReconciliationError(`reconciliation executor returned out-of-bounds canonical ids for fragment ${fragment.id}: ${outOfBounds.join(", ")}`);
+        }
+        if (isExclusionDisposition(result.disposition) && !result.reason?.trim()) {
+            throw new LedgerReconciliationError(`reconciliation executor omitted the required exclusion reason for fragment ${fragment.id} (${result.disposition})`);
+        }
+        calls.push(fragment.id);
+        // 风险不降级（AC-003 / AC-HARD-003）：风险保留为 max(原始 risk, disposition
+        // 派生 risk)；context-only / duplicate 不再把高风险片段降为 low。
+        const derivedRisk = result.disposition === "context-only" ||
+            result.disposition === "duplicate"
+            ? "low"
+            : "high";
+        const risk = fragment.risk === "high" || derivedRisk === "high"
+            ? "high"
+            : "low";
+        reconciled.push({
+            ...fragment,
+            disposition: result.disposition,
+            ...(result.reason ? { reason: result.reason } : {}),
+            risk,
+            canonicalRequirementIds: result.mappedIds,
+        });
+    }
+    return { fragments: reconciled, calls };
+}
+/** 供 ledger.ts 接入：把 inventory records 与 raw fragments 合并为可 reconciliation 项。 */
+export function mergeInventoryItems(input) {
+    const textById = new Map(input.fragments.map((fragment) => [fragment.id, fragment.text]));
+    return input.records.map((record) => ({
+        id: record.id,
+        path: record.path,
+        headingPath: record.headingPath,
+        lineRange: record.lineRange,
+        text: textById.get(record.id) ?? "",
+        disposition: record.disposition,
+        ...(record.reason ? { reason: record.reason } : {}),
+        risk: record.risk,
+        canonicalRequirementIds: record.canonicalRequirementIds,
+    }));
+}