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

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,
+    }));
+}

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

@@ -0,0 +1,214 @@
+import { mergeInventoryItems } from "./ledger-reconciliation.js";
+// ---------------------------------------------------------------------------
+// 独立 reviewer（AC-007 / AC-FIDELITY-REPAIR-007）
+// context-only / duplicate / conflicts 由独立可注入 reviewer 审核，与 reconciler
+// 是不同调用阶段（fixture 断言调用顺序，杜绝共享一次输出冒充独立审核）。
+// 最多一次有界修订；review/revision 失败或第二次不通过 fail closed。低风险
+// context-only 仅 reviewer pass 放行，高风险 context-only 始终阻断；duplicate
+// 保留全部来源但审核失败（含修订后仍拒绝）以稳定码 fail closed。
+// ---------------------------------------------------------------------------
+/** review 片段原文按 budget 有界截断（AC-004 / AC-HARD-004），禁止整文档入
+ * prompt；沿用 MAX_SOURCE_EXCERPT_CHARS 边界语义。 */
+export const LEDGER_REVIEW_DEFAULT_BUDGET_CHARS = 2000;
+export const LEDGER_REVIEW_MAX_REVISIONS = 1;
+/** review 失败（reviewer 异常/第二次不通过）统一稳定错误码。 */
+export class LedgerReviewError extends Error {
+    code = "SOURCE_FIDELITY_RECONCILIATION_FAILED";
+    constructor(message, options) {
+        super(message, options);
+        this.name = "LedgerReviewError";
+    }
+}
+/**
+ * 独立 reviewer 编排：仅 context-only（低风险）、duplicate 与 conflict 进入审核。
+ * - context-only high risk：始终阻断（不调 reviewer，fail closed）。
+ * - context-only low：仅 reviewer pass 放行；否则（一次修订后仍失败）阻断。
+ * - duplicate：进入审核并记录；duplicate 保留全部来源，失败不升级为阻断。
+ * - conflict：需 reviewer pass 或存在有效 human resolution，否则阻断。
+ * reviewer 异常即 fail closed，不回退。
+ */
+export async function reviewLedgerFragments(input) {
+    const { canonicalRequirements, reviewer, maxRevisions = LEDGER_REVIEW_MAX_REVISIONS, conflictIds = new Set(), resolvedConflictIds = new Set(), } = input;
+    const calls = input.calls ?? [];
+    const reasons = [];
+    const reviewed = [];
+    for (const fragment of input.fragments) {
+        let kind = null;
+        if (fragment.disposition === "context-only")
+            kind = "context-only";
+        else if (fragment.disposition === "duplicate")
+            kind = "duplicate";
+        else if (conflictIds.has(fragment.id))
+            kind = "conflict";
+        if (!kind)
+            continue;
+        // 高风险 context-only：始终阻断，不进入 reviewer。
+        if (kind === "context-only" && fragment.risk === "high") {
+            reviewed.push({
+                fragmentId: fragment.id,
+                kind,
+                approved: false,
+                revisionUsed: false,
+            });
+            reasons.push(`high-risk context-only fragment ${fragment.id} always blocks; reviewer cannot waive it`);
+            return {
+                approved: false,
+                code: "SOURCE_FIDELITY_HIGH_RISK_UNCOVERED",
+                reasons,
+                reviewed,
+                calls,
+            };
+        }
+        const resolutionAvailable = kind === "conflict" && resolvedConflictIds.has(fragment.id);
+        // AC-002：已被绑定当前 inputDigest 的有效 human resolution 覆盖的 conflict
+        // （resolutionAvailable=true）直接 approved（revisionUsed=false），注入的
+        // reviewer（含模型 reviewer）零调用：calls 不出现该 fragment 条目，reviewed
+        // audit 保留该条目。其余 fragment（unresolved / context-only / duplicate /
+        // 未解决的 conflict）的 reviewer 调用、修订与审核行为完全不变。
+        if (resolutionAvailable) {
+            reviewed.push({
+                fragmentId: fragment.id,
+                kind,
+                approved: true,
+                revisionUsed: false,
+            });
+            continue;
+        }
+        let current = fragment;
+        let approved = false;
+        let revisionUsed = false;
+        let revisionsRemaining = maxRevisions;
+        for (;;) {
+            const request = {
+                kind,
+                fragment: current,
+                canonicalRequirements,
+                resolutionAvailable,
+            };
+            let response;
+            try {
+                response = await reviewer(request);
+            }
+            catch (error) {
+                throw new LedgerReviewError(`independent reviewer failed for ${kind} fragment ${fragment.id}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            calls.push(fragment.id);
+            if (response?.approved === true) {
+                approved = true;
+                break;
+            }
+            // 最多一次有界修订：仅当 reviewer 给出 revision 建议且还有配额时采纳。
+            if (revisionsRemaining > 0 && response?.revision) {
+                current = {
+                    ...current,
+                    ...(response.revision.disposition
+                        ? { disposition: response.revision.disposition }
+                        : {}),
+                    ...(response.revision.reason
+                        ? { reason: response.revision.reason }
+                        : {}),
+                };
+                revisionsRemaining -= 1;
+                revisionUsed = true;
+                continue;
+            }
+            approved = false;
+            break;
+        }
+        reviewed.push({
+            fragmentId: fragment.id,
+            kind,
+            approved,
+            revisionUsed,
+        });
+        if (approved)
+            continue;
+        if (kind === "duplicate") {
+            // duplicate 保留全部来源，但审核失败（含 LEDGER_REVIEW_MAX_REVISIONS=1
+            // 单次有界修订后仍拒绝）即 fail closed（稳定码阻断，绝不静默放行未确认
+            // 的重复排除；ledger 保留全部 duplicate 来源记录不丢失）。
+            reasons.push(`duplicate fragment ${fragment.id} not approved by independent reviewer${revisionUsed ? " after one bounded revision" : ""}`);
+            return {
+                approved: false,
+                code: "SOURCE_FIDELITY_RECONCILIATION_FAILED",
+                reasons,
+                reviewed,
+                calls,
+            };
+        }
+        reasons.push(`${kind} fragment ${fragment.id} not approved by independent reviewer${revisionUsed ? " after one bounded revision" : ""}`);
+        return {
+            approved: false,
+            code: kind === "context-only"
+                ? "SOURCE_FIDELITY_CONTEXT_ONLY_UNREVIEWED"
+                : "SOURCE_FIDELITY_CONFLICT",
+            reasons,
+            reviewed,
+            calls,
+        };
+    }
+    return { approved: true, code: null, reasons, reviewed, calls };
+}
+/**
+ * 仓库内确定性默认 reviewer（无模型依赖）：context-only 需完整排除理由且低风险；
+ * duplicate 需完整理由；conflict 需有效 human resolution。prepare 在未注入外部
+ * reviewer 时使用该实现，保证 frontend task 的 ledger 评审语义 fail closed。
+ */
+export const defaultLedgerReviewer = async (request) => {
+    if (request.kind === "context-only") {
+        const complete = Boolean(request.fragment.reason?.trim());
+        return {
+            approved: complete && request.fragment.risk === "low",
+            reason: complete
+                ? "context-only 排除理由完整且低风险"
+                : "context-only fragment 缺少完整排除理由",
+        };
+    }
+    if (request.kind === "duplicate") {
+        const complete = Boolean(request.fragment.reason?.trim());
+        return {
+            approved: complete,
+            reason: complete
+                ? "duplicate 排除理由完整（保留全部来源）"
+                : "duplicate fragment 缺少完整排除理由",
+        };
+    }
+    return {
+        approved: request.resolutionAvailable,
+        reason: request.resolutionAvailable
+            ? "conflict 已被绑定当前 inputDigest 的有效 human resolution 覆盖"
+            : "conflict 无有效 human resolution 覆盖，保持阻断",
+    };
+};
+/** 供 prepare.ts 接入：从 ledger fragments 中挑选需审核的条目，复用
+ * mergeInventoryItems 的 id→原文映射，按 budgetChars 有界截断后传入 reviewer
+ * （AC-004 / AC-HARD-004）：请求携带非空有界原文与精确 fragment id，完整文档
+ * 绝不进入下游 prompt；原文不可得时退化为 reason / id 保证非空。 */
+export function ledgerReviewItemsFromRecords(records, input) {
+    const budgetChars = input?.budgetChars ?? LEDGER_REVIEW_DEFAULT_BUDGET_CHARS;
+    const merged = input?.fragments
+        ? mergeInventoryItems({ records, fragments: input.fragments })
+        : records.map((record) => ({
+            id: record.id,
+            path: "",
+            headingPath: record.headingPath,
+            lineRange: record.lineRange,
+            text: "",
+            disposition: record.disposition,
+            ...(record.reason ? { reason: record.reason } : {}),
+            risk: record.risk,
+            canonicalRequirementIds: record.canonicalRequirementIds,
+        }));
+    return merged.map((item) => {
+        const bounded = item.text.slice(0, budgetChars);
+        const text = bounded.trim() || item.reason?.trim() || item.id;
+        return {
+            id: item.id,
+            text,
+            disposition: item.disposition,
+            ...(item.reason ? { reason: item.reason } : {}),
+            risk: item.risk,
+            canonicalRequirementIds: item.canonicalRequirementIds,
+        };
+    });
+}