@world-engines/project-host 0.1.0-alpha.0

package/dist/document-graph-extractor.js

@@ -0,0 +1,588 @@
+import { AuthoringModelConnectionError } from "./authoring-model-connection.js";
+export class DocumentGraphExtractionError extends Error {
+    code;
+    diagnostics;
+    name = "DocumentGraphExtractionError";
+    constructor(code, diagnostics) {
+        super(code);
+        this.code = code;
+        this.diagnostics = diagnostics;
+    }
+}
+const DEFAULT_EXTRACTION_MAX_OUTPUT_TOKENS = 32_768;
+const MAX_EXTRACTION_MAX_OUTPUT_TOKENS = 65_536;
+const NODE_KINDS = Object.freeze(["person", "place", "object", "organization", "event", "concept"]);
+const LOCAL_ID = /^[a-z][a-z0-9_]{0,127}$/u;
+const PREDICATE = /^[a-z][a-z0-9_]{0,127}$/u;
+const PREDICATE_ALIASES = Object.freeze({
+    based_in: "located_in", in: "located_in", located_at: "located_in",
+    father_of: "parent_of", mother_of: "parent_of", parent: "parent_of",
+    master_of: "teacher_of", teacher: "teacher_of",
+    owner_of: "owns", owned_by: "owned_by",
+    belongs_to: "member_of", member: "member_of",
+    participant_in: "participates_in", took_part_in: "participates_in",
+    occurred_at: "happened_at", occurs_at: "happened_at",
+});
+const EXTRACTION_SCHEMA = Object.freeze({
+    type: "object",
+    additionalProperties: false,
+    required: ["segments", "nodes", "edges"],
+    properties: {
+        segments: { type: "array", minItems: 1, items: { type: "object", additionalProperties: false,
+                required: ["start_unit_id", "end_unit_id", "title"], properties: {
+                    start_unit_id: { type: "string", minLength: 1 }, end_unit_id: { type: "string", minLength: 1 }, title: { type: "string", minLength: 1 },
+                } } },
+        nodes: { type: "array", items: { type: "object", additionalProperties: false,
+                required: ["local_id", "label", "kind", "aliases", "statements"], properties: {
+                    local_id: { type: "string", pattern: "^[a-z][a-z0-9_]{0,127}$" },
+                    label: { type: "string", minLength: 1 }, kind: { type: "string", enum: NODE_KINDS },
+                    aliases: { type: "array", items: { type: "string", minLength: 1 } },
+                    statements: { type: "array", items: { type: "object", additionalProperties: false,
+                            required: ["predicate", "assertion", "value_json", "qualifiers_json", "evidence_unit_ids"], properties: {
+                                predicate: { type: "string", pattern: "^[a-z][a-z0-9_]{0,127}$" }, assertion: { type: "string", minLength: 1 },
+                                value_json: { type: "string", minLength: 1 }, qualifiers_json: { type: "string", minLength: 2 },
+                                evidence_unit_ids: { type: "array", minItems: 1, items: { type: "string", minLength: 1 } },
+                            } },
+                    },
+                } } },
+        edges: { type: "array", items: { type: "object", additionalProperties: false,
+                required: ["source_local_id", "target_local_id", "predicate", "assertion", "qualifiers_json", "evidence_unit_ids"], properties: {
+                    source_local_id: { type: "string", minLength: 1 }, target_local_id: { type: "string", minLength: 1 },
+                    predicate: { type: "string", pattern: "^[a-z][a-z0-9_]{0,127}$" }, assertion: { type: "string", minLength: 1 },
+                    qualifiers_json: { type: "string", minLength: 2 }, evidence_unit_ids: { type: "array", minItems: 1, items: { type: "string", minLength: 1 } },
+                } } },
+    },
+});
+const SYSTEM_PROMPT = [
+    "你是 D4F 文档结构与知识图谱抽取器。只输出符合 schema 的单个裸 JSON 对象；禁止 Markdown 代码围栏、前言、解释和后记。",
+    "segments 必须按原顺序完整且恰好覆盖全部 core units，不得覆盖 context units，不得 gap/overlap。目标语义段约 500-1800 字，但不得拆开原子 unit，也不为凑长度伪造内容。",
+    "coreCoverage.singleSegmentRequired 为 true 时只输出一个 segment：start_unit_id 必须是 coreCoverage.firstCoreUnitId，end_unit_id 必须是 coreCoverage.lastCoreUnitId。所有 layout/control unit 也必须被相邻 segment 范围覆盖；不能跳过空白 unit。",
+    "context units 只用于消解 core 中跨句代词和承接；node/statement/edge 的 evidence 可含 context，但必须至少含一个 core unit。不要单独抽取只存在于 context 的事实。",
+    "node 是人物、地点、物件、组织、事件或概念；属性和事件细节写入 node.statements。edge 只用于两个 node 之间有方向的关系，绝不能把 node 本身当 edge。",
+    "两个实体之间的关系只写 edge，不要再把同一关系重复写成 node statement；statement 用于标量/JSON 属性、事件摘要及无法自然建模为两个实体的可检索陈述。",
+    "aliases 只放同一实体的真实别名、字号、旧称或简称，不放职业、类别、关系、地点或描述。",
+    "knownEntities 只是当前窗口命中的别名参考，不是事实证据。不要复述名单，也不要因参考提示重复输出同一身份或同一事实；仅抽取当前 core 支持的事实。",
+    "predicate 必须使用英文 lower_snake_case。优先通用语义与固定方向：is_a 实例→类别；located_in 对象→容器地点；parent_of 父母→子女；teacher_of 教师→学生；owns 所有者→所有物；member_of 成员→组织；part_of 部分→整体；rules 统治者→辖地；created_by 作品→创作者；participates_in 参与者→事件；happened_at 事件→地点；happened_before 较早事件→较晚事件。只有真正对称且更具体关系不存在时才用 related_to。",
+    "assertion 必须用自然语言明确说出主体、关系、客体或属性值。输出前结合 evidence 和 context 检查关系方向；quote/unit 存在本身不能证明方向正确。",
+    "qualifiers_json 必须是 JSON object 字符串，保留时间、说话人、否定、条件、传闻/不确定性等限定；无限定用 {}。statement.value_json 必须是任意合法 JSON 值的字符串。",
+    "local_id 仅在当前窗口内引用，禁止生成全局/stable ID。每条 edge 必须引用本次 nodes 中存在的 local_id。不得编造缺失事实；允许 nodes/edges 为空。",
+].join("\n");
+const SEMANTIC_NEGATION_V4_PROMPT = [
+    "否定的两个实体关系也必须写入 edge，不得只写成 node statement。",
+    "否定 edge 的 predicate 必须使用不带 not_ 前缀的正向 canonical predicate，并在 qualifiers_json 中显式写 negation:true；不得把否定关系输出成正向事实。",
+    "无法同时输出有当前 evidence 支持的两个 endpoint node 时，省略该关系；不得从 statement、代词或自然语言猜测补造 endpoint 或反转方向。",
+].join("\n");
+function systemPrompt(input) {
+    return input.methodVersion === "semantic-negation-v4" || input.methodVersion === "harness-v1"
+        ? `${SYSTEM_PROMPT}\n${SEMANTIC_NEGATION_V4_PROMPT}`
+        : SYSTEM_PROMPT;
+}
+function invariant(condition, code) { if (!condition)
+    throw new Error(code); }
+function record(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null ? value : undefined;
+}
+function hasOnlyKeys(value, keys) {
+    return value !== undefined && Object.keys(value).every((key) => keys.includes(key));
+}
+function text(value, maximum = 32_768) {
+    if (typeof value !== "string")
+        return undefined;
+    const normalized = value.trim().normalize("NFC");
+    return normalized.length > 0 && normalized.length <= maximum && !normalized.includes("\0") ? normalized : undefined;
+}
+function note(diagnostics, kind, reason) {
+    if (kind === "segment")
+        diagnostics.rejectedSegmentCount += 1;
+    else if (kind === "node")
+        diagnostics.rejectedNodeCount += 1;
+    else if (kind === "statement")
+        diagnostics.rejectedStatementCount += 1;
+    else
+        diagnostics.rejectedEdgeCount += 1;
+    diagnostics.rejectionReasons[reason] = (diagnostics.rejectionReasons[reason] ?? 0) + 1;
+}
+function rejectWithReasons(diagnostics, kind, reasons) {
+    if (kind === "node")
+        diagnostics.rejectedNodeCount += 1;
+    else if (kind === "statement")
+        diagnostics.rejectedStatementCount += 1;
+    else
+        diagnostics.rejectedEdgeCount += 1;
+    for (const reason of reasons)
+        diagnostics.rejectionReasons[reason] = (diagnostics.rejectionReasons[reason] ?? 0) + 1;
+}
+function jsonValue(value) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return true;
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every(jsonValue);
+    const input = record(value);
+    return input !== undefined && Object.values(input).every(jsonValue);
+}
+function parseJsonValue(value) {
+    if (typeof value !== "string")
+        return undefined;
+    try {
+        const decoded = JSON.parse(value);
+        return jsonValue(decoded) ? decoded : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseQualifiers(value) {
+    const decoded = parseJsonValue(value);
+    return record(decoded);
+}
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    const input = record(value);
+    if (input)
+        return `{${Object.keys(input).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(input[key])}`).join(",")}}`;
+    return JSON.stringify(value);
+}
+function normalizePredicate(value) {
+    const candidate = text(value, 128)?.toLowerCase();
+    if (!candidate || !PREDICATE.test(candidate))
+        return undefined;
+    return PREDICATE_ALIASES[candidate] ?? candidate;
+}
+function normalizeEdgePredicate(value, qualifiers, semanticNegation) {
+    const predicate = normalizePredicate(value);
+    if (!predicate || !semanticNegation || !predicate.startsWith("not_"))
+        return predicate === undefined ? Object.freeze({}) : Object.freeze({ predicate });
+    if (qualifiers?.negation !== true)
+        return Object.freeze({ reason: "edge_negation_not_explicit" });
+    const positive = predicate.slice(4);
+    if (!PREDICATE.test(positive) || positive.startsWith("not_"))
+        return Object.freeze({ reason: "edge_predicate_invalid" });
+    return Object.freeze({ predicate: PREDICATE_ALIASES[positive] ?? positive });
+}
+function diagnosticsValue(value) {
+    return Object.freeze({ ...value, rejectionReasons: Object.freeze(Object.fromEntries(Object.entries(value.rejectionReasons).sort())) });
+}
+function providerInvalidDetail(error) {
+    if (error.schemaIssue !== undefined)
+        return Object.freeze({
+            reason: `provider_schema_${error.schemaIssue.keyword}`,
+            repairIssue: Object.freeze({ stage: "closed_schema", validationIssues: error.validationIssues }),
+        });
+    const stage = error.validationStage === "closed_schema" ? "unknown" : error.validationStage ?? "unknown";
+    return Object.freeze({ reason: `provider_${stage}_invalid`, repairIssue: Object.freeze({ stage,
+            ...(error.parseIssue === undefined ? {} : { parseIssue: error.parseIssue }) }) });
+}
+function sourceUnits(input) {
+    const actualWindow = input.source.windows.find((candidate) => candidate.id === input.window.id);
+    invariant(actualWindow !== undefined, "document_graph_window_unknown");
+    invariant(actualWindow.coreUnitIds.join("\0") === input.window.coreUnitIds.join("\0")
+        && actualWindow.contextUnitIds.join("\0") === input.window.contextUnitIds.join("\0"), "document_graph_window_mismatch");
+    const unitById = new Map(input.source.units.map((unit) => [unit.id, unit]));
+    const allowedIds = new Set([...input.window.contextUnitIds, ...input.window.coreUnitIds]);
+    invariant(input.window.coreUnitIds.length > 0 && [...allowedIds].every((id) => unitById.has(id)), "document_graph_window_unit_unknown");
+    return Object.freeze({ unitById, coreIds: input.window.coreUnitIds, allowedIds, windowText: actualWindow.text });
+}
+function evidence(value, source) {
+    if (!Array.isArray(value) || value.length === 0 || !value.every((id) => typeof id === "string" && source.allowedIds.has(id)))
+        return undefined;
+    const requested = new Set(value);
+    if (!source.coreIds.some((id) => requested.has(id)))
+        return undefined;
+    const units = [...source.unitById.values()].filter((unit) => requested.has(unit.id));
+    if (units.length !== requested.size)
+        return undefined;
+    return Object.freeze({
+        unitIds: Object.freeze(units.map((unit) => unit.id)),
+        text: units.map((unit) => unit.text).join(""),
+        startOffset: units[0].startOffset,
+        endOffset: units.at(-1).endOffset,
+    });
+}
+function validateSegments(value, source, diagnostics) {
+    if (!Array.isArray(value) || value.length === 0) {
+        diagnostics.segmentationIssues = Object.freeze([{ segmentIndex: 0, kind: "missing_segments", expectedStartUnitId: source.coreIds[0] ?? null,
+                actualStartUnitId: null, actualEndUnitId: null }]);
+        note(diagnostics, "segment", "segments_required");
+        return undefined;
+    }
+    const indexes = new Map(source.coreIds.map((id, index) => [id, index]));
+    const output = [];
+    const issues = [];
+    let expectedStart = 0;
+    for (const [segmentIndex, candidate] of value.entries()) {
+        const input = record(candidate);
+        const start = typeof input?.start_unit_id === "string" ? indexes.get(input.start_unit_id) : undefined;
+        const end = typeof input?.end_unit_id === "string" ? indexes.get(input.end_unit_id) : undefined;
+        const title = text(input?.title, 512);
+        const bounds = { segmentIndex, expectedStartUnitId: source.coreIds[expectedStart] ?? null,
+            actualStartUnitId: start === undefined ? null : source.coreIds[start], actualEndUnitId: end === undefined ? null : source.coreIds[end] };
+        if (start === undefined || end === undefined || end < start) {
+            issues.push(Object.freeze({ ...bounds, kind: "invalid_bounds" }));
+            continue;
+        }
+        if (start !== expectedStart) {
+            issues.push(Object.freeze({ ...bounds, kind: start > expectedStart ? "gap" : "overlap",
+                affectedStartUnitId: source.coreIds[Math.min(start, expectedStart)],
+                affectedEndUnitId: source.coreIds[start > expectedStart ? start - 1 : Math.min(end, expectedStart - 1)],
+            }));
+        }
+        if (!title || !hasOnlyKeys(input, ["start_unit_id", "end_unit_id", "title"])) {
+            issues.push(Object.freeze({ ...bounds, kind: "invalid_title" }));
+        }
+        else
+            output.push(Object.freeze({ startUnitId: source.coreIds[start], endUnitId: source.coreIds[end], title }));
+        expectedStart = Math.max(expectedStart, end + 1);
+    }
+    if (expectedStart !== source.coreIds.length)
+        issues.push(Object.freeze({ segmentIndex: value.length, kind: "gap",
+            expectedStartUnitId: source.coreIds[expectedStart], actualStartUnitId: null, actualEndUnitId: null,
+            affectedStartUnitId: source.coreIds[expectedStart], affectedEndUnitId: source.coreIds.at(-1),
+        }));
+    if (issues.length > 0) {
+        diagnostics.segmentationIssues = Object.freeze(issues);
+        note(diagnostics, "segment", issues.length === 1 && issues[0].segmentIndex === value.length
+            ? "segment_coverage_incomplete" : "segment_order_or_coverage_invalid");
+        return undefined;
+    }
+    return Object.freeze(output);
+}
+function validateCandidate(value, source, diagnostics, refinedDiagnostics, semanticNegation) {
+    const before = diagnostics.rejectedSegmentCount + diagnostics.rejectedNodeCount + diagnostics.rejectedStatementCount + diagnostics.rejectedEdgeCount;
+    const root = record(value);
+    if (!hasOnlyKeys(root, ["segments", "nodes", "edges"]))
+        note(diagnostics, "segment", "response_shape_invalid");
+    const segments = validateSegments(root?.segments, source, diagnostics);
+    const rawNodes = Array.isArray(root?.nodes) ? root.nodes : [];
+    if (!Array.isArray(root?.nodes))
+        note(diagnostics, "node", "nodes_invalid");
+    const nodeByLocalId = new Map();
+    const nodeByIdentity = new Map();
+    for (const candidate of rawNodes) {
+        const input = record(candidate);
+        const localId = text(input?.local_id, 128);
+        const label = text(input?.label, 512);
+        const kind = NODE_KINDS.includes(input?.kind) ? input.kind : undefined;
+        const nodeReasons = [
+            ...(!localId || !LOCAL_ID.test(localId) ? ["node_local_id_invalid"] : []),
+            ...(localId && nodeByLocalId.has(localId) ? ["node_local_id_duplicate"] : []),
+            ...(!label ? ["node_label_invalid"] : []),
+            ...(!kind ? ["node_kind_invalid"] : []),
+            ...(!Array.isArray(input?.aliases) ? ["node_aliases_container_invalid"] : []),
+            ...(!Array.isArray(input?.statements) ? ["node_statements_container_invalid"] : []),
+            ...(!hasOnlyKeys(input, ["local_id", "label", "kind", "aliases", "statements"]) ? ["node_additional_property"] : []),
+        ];
+        if (nodeReasons.length > 0) {
+            if (refinedDiagnostics)
+                rejectWithReasons(diagnostics, "node", nodeReasons);
+            else
+                note(diagnostics, "node", "node_shape_invalid");
+            continue;
+        }
+        invariant(input !== undefined && localId !== undefined && label !== undefined && kind !== undefined
+            && Array.isArray(input.aliases) && Array.isArray(input.statements), "document_graph_node_validation_inconsistent");
+        const aliases = input.aliases.map((alias) => text(alias, 512));
+        if (aliases.some((alias) => !alias)) {
+            note(diagnostics, "node", "node_alias_invalid");
+            continue;
+        }
+        const identity = `${kind}\0${label.toLocaleLowerCase("zh-Hans")}`;
+        const canonical = nodeByIdentity.get(identity) ?? { localId, label, kind, aliases: new Set(), statements: [] };
+        if (!nodeByIdentity.has(identity))
+            nodeByIdentity.set(identity, canonical);
+        nodeByLocalId.set(localId, canonical.localId);
+        for (const alias of aliases)
+            if (alias !== label)
+                canonical.aliases.add(alias);
+        for (const statementValue of input.statements) {
+            const statement = record(statementValue);
+            const predicate = normalizePredicate(statement?.predicate);
+            const assertion = text(statement?.assertion);
+            const parsedValue = parseJsonValue(statement?.value_json);
+            const qualifiers = parseQualifiers(statement?.qualifiers_json);
+            const proven = evidence(statement?.evidence_unit_ids, source);
+            const statementReasons = [
+                ...(!predicate ? ["statement_predicate_invalid"] : []), ...(!assertion ? ["statement_assertion_invalid"] : []),
+                ...(parsedValue === undefined ? ["statement_value_json_invalid"] : []), ...(!qualifiers ? ["statement_qualifiers_invalid"] : []),
+                ...(!proven ? ["statement_evidence_invalid"] : []),
+                ...(!hasOnlyKeys(statement, ["predicate", "assertion", "value_json", "qualifiers_json", "evidence_unit_ids"])
+                    ? ["statement_additional_property"] : []),
+            ];
+            if (statementReasons.length > 0) {
+                if (refinedDiagnostics)
+                    rejectWithReasons(diagnostics, "statement", statementReasons);
+                else
+                    note(diagnostics, "statement", "node_statement_invalid");
+                continue;
+            }
+            invariant(predicate !== undefined && assertion !== undefined && parsedValue !== undefined && qualifiers !== undefined && proven !== undefined, "document_graph_statement_validation_inconsistent");
+            const normalized = Object.freeze({ predicate, assertion, value: parsedValue, qualifiers: Object.freeze(qualifiers), evidence: proven });
+            const key = `${predicate}\0${assertion}\0${canonicalJson(parsedValue)}\0${canonicalJson(qualifiers)}`;
+            if (!canonical.statements.some((item) => `${item.predicate}\0${item.assertion}\0${canonicalJson(item.value)}\0${canonicalJson(item.qualifiers)}` === key))
+                canonical.statements.push(normalized);
+        }
+    }
+    const nodes = Object.freeze([...nodeByIdentity.values()].map((node) => Object.freeze({
+        localId: node.localId, label: node.label, kind: node.kind,
+        aliases: Object.freeze([...node.aliases].sort((left, right) => left.localeCompare(right, "zh-Hans"))),
+        statements: Object.freeze(node.statements),
+    })));
+    const rawEdges = Array.isArray(root?.edges) ? root.edges : [];
+    if (!Array.isArray(root?.edges))
+        note(diagnostics, "edge", "edges_invalid");
+    const edgesByIdentity = new Map();
+    for (const candidate of rawEdges) {
+        const input = record(candidate);
+        const sourceLocalId = typeof input?.source_local_id === "string" ? nodeByLocalId.get(input.source_local_id) : undefined;
+        const targetLocalId = typeof input?.target_local_id === "string" ? nodeByLocalId.get(input.target_local_id) : undefined;
+        const assertion = text(input?.assertion);
+        const qualifiers = parseQualifiers(input?.qualifiers_json);
+        const normalizedPredicate = normalizeEdgePredicate(input?.predicate, qualifiers, semanticNegation);
+        const predicate = normalizedPredicate.predicate;
+        const proven = evidence(input?.evidence_unit_ids, source);
+        const edgeReasons = [
+            ...(!sourceLocalId ? ["edge_source_ref_missing"] : []), ...(!targetLocalId ? ["edge_target_ref_missing"] : []),
+            ...(sourceLocalId !== undefined && sourceLocalId === targetLocalId ? ["edge_self_edge"] : []),
+            ...(normalizedPredicate.reason !== undefined ? [normalizedPredicate.reason] : !predicate ? ["edge_predicate_invalid"] : []),
+            ...(!assertion ? ["edge_assertion_invalid"] : []),
+            ...(!qualifiers ? ["edge_qualifiers_invalid"] : []), ...(!proven ? ["edge_evidence_invalid"] : []),
+            ...(!hasOnlyKeys(input, ["source_local_id", "target_local_id", "predicate", "assertion", "qualifiers_json", "evidence_unit_ids"])
+                ? ["edge_additional_property"] : []),
+        ];
+        if (edgeReasons.length > 0) {
+            if (refinedDiagnostics)
+                rejectWithReasons(diagnostics, "edge", edgeReasons);
+            else
+                note(diagnostics, "edge", !sourceLocalId || !targetLocalId ? "edge_node_ref_invalid" : "edge_invalid");
+            continue;
+        }
+        invariant(sourceLocalId !== undefined && targetLocalId !== undefined && predicate !== undefined && assertion !== undefined
+            && qualifiers !== undefined && proven !== undefined, "document_graph_edge_validation_inconsistent");
+        const key = `${sourceLocalId}\0${targetLocalId}\0${predicate}\0${assertion}\0${canonicalJson(qualifiers)}`;
+        const previous = edgesByIdentity.get(key);
+        if (!previous)
+            edgesByIdentity.set(key, Object.freeze({ sourceLocalId, targetLocalId, predicate, assertion, qualifiers: Object.freeze(qualifiers), evidence: proven }));
+        else {
+            const merged = evidence([...previous.evidence.unitIds, ...proven.unitIds], source);
+            edgesByIdentity.set(key, Object.freeze({ ...previous, evidence: merged }));
+        }
+    }
+    const after = diagnostics.rejectedSegmentCount + diagnostics.rejectedNodeCount + diagnostics.rejectedStatementCount + diagnostics.rejectedEdgeCount;
+    return Object.freeze({ ...(segments === undefined ? {} : { segments }), nodes, edges: Object.freeze([...edgesByIdentity.values()]), issueCount: after - before });
+}
+function adaptiveRepairPayload(input, source) {
+    const previous = input.adaptiveRepair;
+    if (previous === undefined)
+        return undefined;
+    invariant(input.methodVersion === "adaptive-repair-v3" || input.methodVersion === "semantic-negation-v4" || input.methodVersion === "harness-v1", "document_graph_adaptive_method_invalid");
+    invariant(Number.isSafeInteger(previous.attempt) && previous.attempt >= 1 && previous.attempt < 3
+        && /^[0-9a-f]{64}$/u.test(previous.diagnosticFingerprint), "document_graph_adaptive_attempt_invalid");
+    const allowed = [...source.allowedIds];
+    invariant(previous.allowedEvidenceUnitIds.length === allowed.length
+        && new Set(previous.allowedEvidenceUnitIds).size === allowed.length
+        && previous.allowedEvidenceUnitIds.every((id) => source.allowedIds.has(id)), "document_graph_adaptive_units_mismatch");
+    const reasons = [...new Set(previous.reasons)].sort();
+    invariant(reasons.length > 0 && reasons.length <= 64 && reasons.every((reason) => /^[A-Za-z][A-Za-z0-9_]{0,127}$/u.test(reason)), "document_graph_adaptive_reasons_invalid");
+    invariant(new Set(previous.validLocalNodeIds).size === previous.validLocalNodeIds.length
+        && previous.validLocalNodeIds.every((id) => LOCAL_ID.test(id)), "document_graph_adaptive_node_ids_invalid");
+    invariant((previous.segmentationIssues ?? []).every((issue) => [issue.expectedStartUnitId, issue.actualStartUnitId, issue.actualEndUnitId,
+        issue.affectedStartUnitId, issue.affectedEndUnitId].every((id) => id === null || id === undefined || source.allowedIds.has(id))), "document_graph_adaptive_segmentation_invalid");
+    const strategies = [
+        ...(reasons.some((reason) => reason.startsWith("provider_")) ? ["closed_schema_regeneration"] : []),
+        ...(reasons.some((reason) => reason === "edge_source_ref_missing" || reason === "edge_target_ref_missing" || reason === "edge_node_ref_invalid") ? ["endpoint_closure"] : []),
+        ...(reasons.some((reason) => reason.startsWith("statement_") || reason.startsWith("edge_predicate_") || reason.startsWith("edge_assertion_")
+            || reason.startsWith("edge_qualifiers_") || reason.startsWith("edge_evidence_") || reason === "edge_invalid") ? ["invalid_record_repair"] : []),
+        ...(reasons.some((reason) => reason.startsWith("segment_")) ? ["segment_coverage_regeneration"] : []),
+        ...(reasons.some((reason) => reason.startsWith("node_")) ? ["node_shape_repair"] : []),
+    ];
+    return {
+        attempt: previous.attempt + 1,
+        previousDiagnosticFingerprint: previous.diagnosticFingerprint,
+        repeatedDiagnosticFingerprint: previous.repeatedDiagnosticFingerprint,
+        reasons,
+        strategies: [...new Set(strategies)],
+        constraints: [
+            "只修复 diagnostics 指向的无效 records；schema 要求仍需返回完整对象。",
+            "previousValidLocalNodeIds 只说明上次通过结构校验的 local id，不是事实金标；所有输出仍须由本窗口 source units 独立支持。",
+            "edge 两端必须同时出现在本次输出 nodes；无法由当前 evidence 支持端点时删除该 edge，不得补造 node、alias、事实或反转方向。",
+            "字段无法修复时删除该无效单项；不得把 scalar、职业、类别、地点或关系提升为 alias。",
+            "不得改变、删减或扩展 core/context source units；segments 仍须精确完整覆盖 core。",
+        ],
+        legalLocalIdPattern: "^[a-z][a-z0-9_]{0,127}$",
+        previousValidLocalNodeIds: previous.validLocalNodeIds,
+        allowedEvidenceUnitIds: previous.allowedEvidenceUnitIds,
+        sourceSpans: previous.allowedEvidenceUnitIds.map((id) => {
+            const unit = source.unitById.get(id);
+            invariant(unit !== undefined, "document_graph_adaptive_units_mismatch");
+            return { unitId: id, startOffset: unit.startOffset, endOffset: unit.endOffset, core: source.coreIds.includes(id) };
+        }),
+        segmentationIssues: previous.segmentationIssues ?? [],
+    };
+}
+function promptPayload(input, source, diagnostics) {
+    const unit = (id) => {
+        const value = source.unitById.get(id);
+        return { id: value.id, kind: value.kind, text: value.text, ...(value.chapterId === undefined ? {} : { chapterId: value.chapterId }) };
+    };
+    // NFC 仅用于匹配；source units 与发给模型的原文均保持原字节语义，不做简繁推断。
+    const windowText = source.windowText.normalize("NFC");
+    const knownEntities = new Map();
+    for (const entity of input.knownEntities ?? []) {
+        const names = [entity.label, ...(entity.aliases ?? [])];
+        if (!names.some((name) => name.length > 0 && windowText.includes(name.normalize("NFC"))))
+            continue;
+        const hint = { kind: entity.kind, label: entity.label, aliases: [...(entity.aliases ?? [])].sort() };
+        const identity = JSON.stringify(hint);
+        if (!knownEntities.has(identity))
+            knownEntities.set(identity, hint);
+    }
+    diagnostics.catalogProvided = input.knownEntities?.length ?? 0;
+    diagnostics.catalogIncluded = knownEntities.size;
+    const adaptiveRepair = adaptiveRepairPayload(input, source);
+    return {
+        window: { id: input.window.id, chapterId: input.window.chapterId ?? null },
+        coreCoverage: { firstCoreUnitId: source.coreIds[0], lastCoreUnitId: source.coreIds.at(-1), coreUnitCount: source.coreIds.length,
+            coreUtf16: input.window.coreEndOffset - input.window.coreStartOffset,
+            singleSegmentRequired: input.window.coreEndOffset - input.window.coreStartOffset < 1_800 },
+        contextUnits: input.window.contextUnitIds.map(unit), coreUnits: input.window.coreUnitIds.map(unit),
+        knownEntities: [...knownEntities.values()],
+        ...(adaptiveRepair === undefined ? {} : { adaptiveRepair }),
+    };
+}
+function createDiagnostics(initialMaxOutputTokens) {
+    invariant(Number.isSafeInteger(initialMaxOutputTokens) && initialMaxOutputTokens >= 1
+        && initialMaxOutputTokens <= MAX_EXTRACTION_MAX_OUTPUT_TOKENS, "document_graph_output_budget_invalid");
+    return { modelRequests: 0, repairAttempts: 0, rejectedSegmentCount: 0, rejectedNodeCount: 0,
+        rejectedStatementCount: 0, rejectedEdgeCount: 0, rejectionReasons: {}, initialMaxOutputTokens,
+        maxOutputTokens: initialMaxOutputTokens, outputBudgetRetries: 0, catalogProvided: 0, catalogIncluded: 0 };
+}
+function prepareRequest(input, diagnostics) {
+    const source = sourceUnits(input);
+    const payload = promptPayload(input, source, diagnostics);
+    return Object.freeze({
+        schemaName: "document_graph_segment_v1",
+        jsonSchema: EXTRACTION_SCHEMA,
+        messages: Object.freeze([
+            Object.freeze({ role: "system", content: systemPrompt(input) }),
+            Object.freeze({ role: "user", content: JSON.stringify(payload) }),
+        ]),
+        taskMode: "extraction",
+        maxOutputTokens: diagnostics.maxOutputTokens,
+    });
+}
+/** 外部 harness 消费的纯请求构造器；只暴露原文 unit、同一闭合 schema 与可验证约束，不发起模型调用。 */
+export function prepareDocumentGraphWindowRequest(input) {
+    return prepareRequest(input, createDiagnostics(input.maxOutputTokens ?? DEFAULT_EXTRACTION_MAX_OUTPUT_TOKENS));
+}
+/** 外部 harness 响应使用与 provider 路径相同的证据、分段、实体和关系 validator。 */
+export function validateDocumentGraphWindowCandidate(input, candidate) {
+    const diagnostics = createDiagnostics(input.maxOutputTokens ?? DEFAULT_EXTRACTION_MAX_OUTPUT_TOKENS);
+    // 同时验证 adaptive repair identity，并为诊断冻结 catalog 数量。
+    prepareRequest(input, diagnostics);
+    const source = sourceUnits(input);
+    const refinedDiagnostics = input.methodVersion === "adaptive-repair-v3"
+        || input.methodVersion === "semantic-negation-v4" || input.methodVersion === "harness-v1";
+    const semanticNegation = input.methodVersion === "semantic-negation-v4" || input.methodVersion === "harness-v1";
+    const validated = validateCandidate(candidate, source, diagnostics, refinedDiagnostics, semanticNegation);
+    const partial = validated.issueCount > 0 || validated.segments === undefined;
+    return Object.freeze({
+        windowId: input.window.id,
+        status: partial ? "partial" : "complete",
+        segments: validated.segments ?? Object.freeze([]),
+        nodes: validated.nodes,
+        edges: validated.edges,
+        diagnostics: diagnosticsValue(diagnostics),
+    });
+}
+async function generate(input, messages, diagnostics) {
+    if (input.signal?.aborted)
+        throw new AuthoringModelConnectionError("aborted", false);
+    diagnostics.modelRequests += 1;
+    try {
+        const result = await input.modelConnection.structuredJson.generate({
+            schemaName: "document_graph_segment_v1", jsonSchema: EXTRACTION_SCHEMA, messages,
+            taskMode: "extraction", maxOutputTokens: diagnostics.maxOutputTokens, timeoutMs: 300_000,
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+        });
+        if (result.framing === "single_json_fence")
+            diagnostics.jsonFenceUnwraps = (diagnostics.jsonFenceUnwraps ?? 0) + 1;
+        return result.value;
+    }
+    catch (error) {
+        if (!(error instanceof AuthoringModelConnectionError) || error.code !== "provider_output_truncated")
+            throw error;
+        diagnostics.rejectionReasons.provider_output_truncated = (diagnostics.rejectionReasons.provider_output_truncated ?? 0) + 1;
+        if (input.signal?.aborted)
+            throw new AuthoringModelConnectionError("aborted", false);
+        if (diagnostics.maxOutputTokens >= MAX_EXTRACTION_MAX_OUTPUT_TOKENS || diagnostics.outputBudgetRetries > 0) {
+            throw new DocumentGraphExtractionError("provider_output_truncated", diagnosticsValue(diagnostics));
+        }
+        // 全次窗口调用最多一次预算扩容；同一 messages/schema/model/source，不截删原文。
+        diagnostics.maxOutputTokens = MAX_EXTRACTION_MAX_OUTPUT_TOKENS;
+        diagnostics.outputBudgetRetries += 1;
+        return generate(input, messages, diagnostics);
+    }
+}
+/** D4F 分段、图抽取、证据回取、通用 predicate 归一化与一次 bounded repair 的唯一 Interface。 */
+export async function extractDocumentGraphWindow(input) {
+    invariant(input.modelConnection.structuredJson.modelId === "deepseek-v4-flash", "document_graph_model_invalid");
+    const initialMaxOutputTokens = input.maxOutputTokens === undefined ? DEFAULT_EXTRACTION_MAX_OUTPUT_TOKENS : input.maxOutputTokens;
+    const diagnostics = createDiagnostics(initialMaxOutputTokens);
+    const source = sourceUnits(input);
+    const prepared = prepareRequest(input, diagnostics);
+    const payload = JSON.parse(prepared.messages[1].content);
+    const initialMessages = prepared.messages;
+    let candidate;
+    try {
+        candidate = await generate(input, initialMessages, diagnostics);
+    }
+    catch (error) {
+        if (!(error instanceof AuthoringModelConnectionError) || error.code !== "provider_response_invalid")
+            throw error;
+        const invalid = providerInvalidDetail(error);
+        if (error.validationIssues.length > 0)
+            diagnostics.validationIssues = error.validationIssues;
+        diagnostics.repairAttempts = 1;
+        diagnostics.rejectionReasons[invalid.reason] = 1;
+        try {
+            candidate = await generate(input, [...initialMessages, { role: "user", content: JSON.stringify({ repair: true, issue: invalid.repairIssue }) }], diagnostics);
+        }
+        catch (repairError) {
+            if (!(repairError instanceof AuthoringModelConnectionError) || repairError.code !== "provider_response_invalid")
+                throw repairError;
+            const repairInvalid = providerInvalidDetail(repairError);
+            if (repairError.validationIssues.length > 0)
+                diagnostics.validationIssues = repairError.validationIssues;
+            diagnostics.rejectionReasons[repairInvalid.reason] = (diagnostics.rejectionReasons[repairInvalid.reason] ?? 0) + 1;
+            throw new DocumentGraphExtractionError("document_graph_provider_output_invalid", diagnosticsValue(diagnostics));
+        }
+    }
+    const refinedDiagnostics = input.methodVersion === "adaptive-repair-v3" || input.methodVersion === "semantic-negation-v4"
+        || input.methodVersion === "harness-v1";
+    const semanticNegation = input.methodVersion === "semantic-negation-v4" || input.methodVersion === "harness-v1";
+    let validated = validateCandidate(candidate, source, diagnostics, refinedDiagnostics, semanticNegation);
+    if (validated.issueCount > 0 && diagnostics.repairAttempts === 0) {
+        diagnostics.repairAttempts = 1;
+        const issues = Object.keys(diagnostics.rejectionReasons).sort();
+        candidate = await generate(input, [
+            { role: "system", content: systemPrompt(input) },
+            { role: "user", content: JSON.stringify(payload) },
+            { role: "user", content: JSON.stringify({ repair: true, issues,
+                    ...(diagnostics.segmentationIssues === undefined ? {} : { coverage: { ...record(payload.coreCoverage), issues: diagnostics.segmentationIssues } }),
+                    invalidCandidate: candidate }) },
+        ], diagnostics);
+        validated = validateCandidate(candidate, source, diagnostics, refinedDiagnostics, semanticNegation);
+    }
+    if (!validated.segments)
+        throw new DocumentGraphExtractionError("document_graph_segmentation_invalid", diagnosticsValue(diagnostics));
+    const partial = validated.issueCount > 0;
+    return Object.freeze({
+        windowId: input.window.id, status: partial ? "partial" : "complete", segments: validated.segments,
+        nodes: validated.nodes, edges: validated.edges, diagnostics: diagnosticsValue(diagnostics),
+    });
+}

package/dist/document-ingestion-journal.d.ts

@@ -0,0 +1,68 @@
+type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+type JournalPhase = "extracting" | "ready_to_commit" | "committing" | "committed";
+export type DocumentIngestionJournalErrorCode = "invalid_input" | "busy" | "identity_mismatch" | "corrupt" | "invalid_transition" | "lease_uncertain";
+export declare class DocumentIngestionJournalError extends Error {
+    readonly code: DocumentIngestionJournalErrorCode;
+    readonly name = "DocumentIngestionJournalError";
+    constructor(code: DocumentIngestionJournalErrorCode);
+}
+export interface DocumentIngestionJournalIdentity {
+    readonly operationId: string;
+    readonly sourceByteSha256: string;
+    readonly planSha256: string;
+    readonly modelId: string;
+    readonly expectedProjectRevision: number;
+    /** 旧 manifest 没有该字段；缺省必须按 legacy-v1 恢复，不能就地升级方法。 */
+    readonly method?: DocumentIngestionJournalMethodIdentity;
+}
+export interface DocumentIngestionJournalMethodIdentity {
+    readonly version: string;
+    readonly sha256: string;
+    readonly promptVersion: string;
+    readonly schemaVersion: string;
+    readonly mergeVersion: string;
+    readonly embeddingPolicy: string;
+    readonly validatorDiagnosticsVersion?: string;
+    readonly repairPolicyVersion?: string;
+}
+export interface DocumentIngestionJournalStatus extends DocumentIngestionJournalIdentity {
+    readonly phase: JournalPhase;
+    readonly completedSegmentIds: readonly string[];
+    readonly failedSegments: readonly Readonly<{
+        id: string;
+        attempts: number;
+        code: string;
+        retryable: boolean;
+    }>[];
+    readonly commitReceipt: JsonValue | null;
+}
+export interface DocumentIngestionJournal {
+    getStatus(): Promise<DocumentIngestionJournalStatus>;
+    readSegment(id: string): Promise<JsonValue | null>;
+    writeSegment(id: string, payload: JsonValue): Promise<Readonly<{
+        payloadSha256: string;
+    }>>;
+    clearSegmentFailure(id: string): Promise<void>;
+    recordSegmentFailure(id: string, failure: Readonly<{
+        code: string;
+        retryable: boolean;
+        attempts?: number;
+    }>): Promise<void>;
+    markPhase(phase: Exclude<JournalPhase, "committed">): Promise<void>;
+    recordCommitReceipt(receipt: JsonValue): Promise<void>;
+    close(): Promise<void>;
+}
+/** 只读 operational 状态；不获取 writer lease，也不修复或改写 manifest。 */
+export declare function readDocumentIngestionJournalStatus(projectRoot: string, operationId: string): Promise<DocumentIngestionJournalStatus>;
+export declare function openDocumentIngestionJournal(options: Readonly<{
+    projectRoot: string;
+    operationId: string;
+    sourceByteSha256: string;
+    planSha256: string;
+    modelId: string;
+    expectedProjectRevision: number;
+    method?: DocumentIngestionJournalMethodIdentity;
+}>): Promise<DocumentIngestionJournal>;
+export {};