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

package/dist/document-ingestion.js

@@ -0,0 +1,976 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+import { DocumentGraphExtractionError, extractDocumentGraphWindow, } from "./document-graph-extractor.js";
+import { openDocumentIngestionJournal, readDocumentIngestionJournalStatus, } from "./document-ingestion-journal.js";
+import { buildDocumentSource, documentSourceBytes, validateDocumentPlan, } from "./document-source.js";
+import { createCachedEmbeddingPort } from "./embedding-cache.js";
+import { assertSafeExistingProjectPath, safeProjectPath } from "./safe-project-path.js";
+const CONTROL_KIND = "world_document_ingestion_source_control";
+const DOCUMENT_KIND = "world_source_document";
+const CHUNK_KIND = "world_source_chunk";
+const SOURCE_DESCRIPTOR_ID = "__document_source_descriptor__";
+const PARTIAL_ATTEMPT_PREFIX = "__document_partial_attempt__:";
+const RETRY_COMPLETE_PREFIX = "__document_retry_complete__:";
+const HARNESS_ACCEPTANCE_PREFIX = "__document_harness_acceptance__:";
+const MAX_PARTIAL_ATTEMPTS = 3;
+export const DOCUMENT_INGESTION_CHECKPOINT_IDS = Object.freeze({
+    sourceDescriptorId: SOURCE_DESCRIPTOR_ID,
+    partialAttemptPrefix: PARTIAL_ATTEMPT_PREFIX,
+    retryCompletePrefix: RETRY_COMPLETE_PREFIX,
+    harnessAcceptancePrefix: HARNESS_ACCEPTANCE_PREFIX,
+    maxPartialAttempts: MAX_PARTIAL_ATTEMPTS,
+});
+const GENERIC_ENTITY_LABEL = /^(?:大王|那怪|此怪|妖怪|行者|长老|师父|陛下|公主|国王|夫人|老者|童子|道人|菩萨|佛祖|魔王)$/u;
+const METHOD_PAYLOADS = Object.freeze({
+    "legacy-v1": Object.freeze({ version: "legacy-v1", promptVersion: "document-graph-prompt-v1",
+        schemaVersion: "document_graph_segment_v1", mergeVersion: "evidenced-alias-union-v1", embeddingPolicy: "immediate" }),
+    "deferred-v2": Object.freeze({ version: "deferred-v2", promptVersion: "document-graph-prompt-v1",
+        schemaVersion: "document_graph_segment_v1", mergeVersion: "evidenced-alias-union-v1", embeddingPolicy: "deferred_review" }),
+    "adaptive-repair-v3": Object.freeze({ version: "adaptive-repair-v3", promptVersion: "document-graph-prompt-v1+adaptive-repair-v3",
+        schemaVersion: "document_graph_segment_v1", mergeVersion: "evidenced-alias-union-v1", embeddingPolicy: "deferred_review",
+        validatorDiagnosticsVersion: "document-graph-diagnostics-v3", repairPolicyVersion: "bounded-adaptive-repair-v3" }),
+    "semantic-negation-v4": Object.freeze({ version: "semantic-negation-v4", promptVersion: "document-graph-prompt-v2+semantic-negation-v4",
+        schemaVersion: "document_graph_segment_v1", mergeVersion: "evidenced-alias-union-v1+explicit-negation-edge-v4", embeddingPolicy: "deferred_review",
+        validatorDiagnosticsVersion: "document-graph-diagnostics-v4", repairPolicyVersion: "bounded-adaptive-repair-v3" }),
+    "harness-v1": Object.freeze({ version: "harness-v1", promptVersion: "document-graph-prompt-v2+harness-v1",
+        schemaVersion: "document_graph_segment_v1", mergeVersion: "evidenced-alias-union-v1+explicit-negation-edge-v4", embeddingPolicy: "deferred_review",
+        validatorDiagnosticsVersion: "document-graph-diagnostics-v4", repairPolicyVersion: "bounded-harness-repair-v1" }),
+});
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function stableJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    const record = value;
+    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`).join(",")}}`;
+}
+function ingestionMethod(version) {
+    const payload = METHOD_PAYLOADS[version];
+    return Object.freeze({ ...payload, sha256: sha256(stableJson(payload)) });
+}
+function parseIngestionMethod(value, fallbackLegacy) {
+    if (value === undefined && fallbackLegacy)
+        return ingestionMethod("legacy-v1");
+    const candidate = record(value, "document_ingestion_descriptor_invalid");
+    const version = candidate.version;
+    if (version !== "legacy-v1" && version !== "deferred-v2" && version !== "adaptive-repair-v3" && version !== "semantic-negation-v4"
+        && version !== "harness-v1") {
+        throw new Error("document_ingestion_descriptor_invalid");
+    }
+    const expected = ingestionMethod(version);
+    if (candidate.sha256 !== expected.sha256 || candidate.prompt_version !== expected.promptVersion
+        || candidate.schema_version !== expected.schemaVersion || candidate.merge_version !== expected.mergeVersion
+        || candidate.embedding_policy !== expected.embeddingPolicy
+        || candidate.validator_diagnostics_version !== expected.validatorDiagnosticsVersion
+        || candidate.repair_policy_version !== expected.repairPolicyVersion)
+        throw new Error("document_ingestion_descriptor_identity_mismatch");
+    return expected;
+}
+function id(prefix, ...parts) {
+    return `${prefix}:${sha256(stableJson(parts))}`;
+}
+function record(value, code) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error(code);
+    return value;
+}
+function asJson(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function sameBytes(left, right) {
+    return left.byteLength === right.byteLength && left.every((byte, index) => byte === right[index]);
+}
+export async function readDocumentIngestionCheckpoint(projectRoot, operationId, segmentId) {
+    const operationKey = sha256(operationId);
+    const segmentKey = sha256(segmentId);
+    const path = await safeProjectPath(projectRoot, `.worldengine/staging/document-ingestion/${operationKey}/segments/${segmentKey}.json`);
+    await assertSafeExistingProjectPath(projectRoot, path);
+    const envelope = record(JSON.parse(await readFile(path, "utf8")), "document_ingestion_checkpoint_invalid");
+    if (envelope.schema_version !== 1 || envelope.id !== segmentId || typeof envelope.payload_json !== "string"
+        || typeof envelope.payload_sha256 !== "string" || sha256(envelope.payload_json) !== envelope.payload_sha256) {
+        throw new Error("document_ingestion_checkpoint_invalid");
+    }
+    return JSON.parse(envelope.payload_json);
+}
+/** descriptor 是输入元数据，不能算作一个已完成的模型窗口。 */
+export async function readLosslessDocumentStatus(projectRoot, operationId) {
+    const status = await readDocumentIngestionJournalStatus(projectRoot, operationId);
+    const descriptor = await readStagedDocumentInput(projectRoot, operationId);
+    const completedSegmentIds = [];
+    for (const id of status.completedSegmentIds) {
+        if (id === SOURCE_DESCRIPTOR_ID || id.startsWith(PARTIAL_ATTEMPT_PREFIX) || id.startsWith(HARNESS_ACCEPTANCE_PREFIX))
+            continue;
+        if (id.startsWith(RETRY_COMPLETE_PREFIX)) {
+            const windowId = id.slice(RETRY_COMPLETE_PREFIX.length);
+            if (graphSegment(await readDocumentIngestionCheckpoint(projectRoot, operationId, id), windowId).status !== "complete") {
+                throw new Error("document_ingestion_checkpoint_invalid");
+            }
+            completedSegmentIds.push(windowId);
+            continue;
+        }
+        const value = await readDocumentIngestionCheckpoint(projectRoot, operationId, id);
+        const candidate = record(value, "document_ingestion_checkpoint_invalid");
+        if (candidate.status !== "partial" || status.method === undefined)
+            completedSegmentIds.push(id);
+    }
+    return Object.freeze({ ...status,
+        ...(descriptor.input.sourcePath === undefined ? {} : { sourcePath: descriptor.input.sourcePath }),
+        ...(descriptor.input.sourceStoragePath === undefined ? {} : { sourceStoragePath: descriptor.input.sourceStoragePath }),
+        completedSegmentIds: Object.freeze([...new Set(completedSegmentIds)].sort()) });
+}
+export async function resumeLosslessDocument(host, operationId, capability) {
+    const descriptor = await readStagedDocumentInput(capability.projectRoot, operationId);
+    if (capability.sourceOptions !== undefined && stableJson(capability.sourceOptions) !== stableJson(descriptor.sourceOptions)) {
+        throw new Error("document_ingestion_descriptor_identity_mismatch");
+    }
+    if (capability.methodVersion !== undefined && capability.methodVersion !== descriptor.method.version) {
+        throw new Error("document_ingestion_descriptor_identity_mismatch");
+    }
+    return ingestLosslessDocumentWithMethod(host, descriptor.input, { ...capability, ...(descriptor.sourceOptions === undefined ? {} : { sourceOptions: descriptor.sourceOptions }) }, descriptor.method);
+}
+/** 上传流或原文件已释放时，以 operationId 只读恢复 journal 中已校验的不可变原始输入。 */
+export async function readStagedDocumentInput(projectRoot, operationId) {
+    if (typeof operationId !== "string" || operationId.length === 0 || operationId.length > 512 || operationId.trim() !== operationId
+        || operationId.normalize("NFC") !== operationId || /[\u0000-\u001f\u007f]/u.test(operationId))
+        throw new Error("document_ingestion_operation_id_invalid");
+    const operationKey = sha256(operationId);
+    const segmentKey = sha256(SOURCE_DESCRIPTOR_ID);
+    const path = await safeProjectPath(projectRoot, `.worldengine/staging/document-ingestion/${operationKey}/segments/${segmentKey}.json`);
+    await assertSafeExistingProjectPath(projectRoot, path);
+    const envelope = record(JSON.parse(await readFile(path, "utf8")), "document_ingestion_descriptor_invalid");
+    if (envelope.schema_version !== 1 || envelope.id !== SOURCE_DESCRIPTOR_ID || typeof envelope.payload_json !== "string"
+        || typeof envelope.payload_sha256 !== "string" || sha256(envelope.payload_json) !== envelope.payload_sha256)
+        throw new Error("document_ingestion_descriptor_invalid");
+    const payload = record(JSON.parse(envelope.payload_json), "document_ingestion_descriptor_invalid");
+    const storedInput = record(payload.input, "document_ingestion_descriptor_invalid");
+    // 已落盘的旧 checkpoint 只读兼容；新 descriptor 只写 snake_case，不重复保存全文。
+    const canonical = payload.schema_version === 1 || payload.schema_version === 2;
+    const encodedInput = canonical ? { rawBase64: storedInput.raw_base64, scopeId: storedInput.scope_id,
+        sourceId: storedInput.source_id, sourceRevision: storedInput.source_revision, sourcePath: storedInput.source_path,
+        sourceStoragePath: storedInput.source_storage_path } : storedInput;
+    const schemaVersion = canonical ? payload.schema_version : payload.schemaVersion;
+    const storedOperationId = canonical ? payload.operation_id : payload.operationId;
+    const planSha256 = canonical ? payload.plan_sha256 : payload.planSha256;
+    const sourceOptions = canonical ? payload.source_options : payload.sourceOptions;
+    if ((schemaVersion !== 1 && schemaVersion !== 2) || storedOperationId !== operationId || typeof planSha256 !== "string"
+        || typeof encodedInput.rawBase64 !== "string" || typeof encodedInput.scopeId !== "string" || typeof encodedInput.sourceId !== "string"
+        || typeof encodedInput.sourceRevision !== "string" || (encodedInput.sourcePath !== undefined && typeof encodedInput.sourcePath !== "string")
+        || (encodedInput.sourceStoragePath !== undefined && typeof encodedInput.sourceStoragePath !== "string")) {
+        throw new Error("document_ingestion_descriptor_invalid");
+    }
+    const method = parseIngestionMethod(canonical ? payload.method : payload.method, schemaVersion === 1 && payload.method === undefined);
+    const bytes = Uint8Array.from(Buffer.from(encodedInput.rawBase64, "base64"));
+    const descriptor = Object.freeze({ schemaVersion, operationId,
+        input: Object.freeze({ bytes, scopeId: encodedInput.scopeId, sourceId: encodedInput.sourceId, sourceRevision: encodedInput.sourceRevision,
+            ...(encodedInput.sourcePath === undefined ? {} : { sourcePath: encodedInput.sourcePath }),
+            ...(encodedInput.sourceStoragePath === undefined ? {} : { sourceStoragePath: encodedInput.sourceStoragePath }) }),
+        ...(sourceOptions === undefined ? {} : { sourceOptions: record(sourceOptions, "document_ingestion_descriptor_invalid") }),
+        planSha256, method });
+    const rebuilt = buildDocumentSource({ bytes: descriptor.input.bytes, scopeId: descriptor.input.scopeId, sourceId: descriptor.input.sourceId,
+        sourceRevision: descriptor.input.sourceRevision, ...(descriptor.sourceOptions === undefined ? {} : { options: descriptor.sourceOptions }) });
+    if (sourcePlan(rebuilt, descriptor.method).sha256 !== descriptor.planSha256 || operationIdentity(rebuilt, descriptor.method) !== operationId) {
+        throw new Error("document_ingestion_descriptor_identity_mismatch");
+    }
+    return descriptor;
+}
+function sourcePlan(source, method) {
+    const value = asJson({
+        schemaVersion: 1,
+        documentId: source.documentId,
+        windows: source.windows.map((window) => ({ id: window.id, coreUnitIds: window.coreUnitIds })),
+        ...(method.version === "legacy-v1" ? {} : { method }),
+    });
+    return Object.freeze({ sha256: sha256(stableJson(value)), value });
+}
+function operationIdentity(source, method) {
+    const sourceIdentity = [source.scopeId, source.sourceId, source.sourceRevision, source.sourceSha256];
+    return method.version === "legacy-v1"
+        ? `document-ingest:${sha256(stableJson(sourceIdentity))}`
+        : `document-ingest:v2:${sha256(stableJson([...sourceIdentity, method.sha256]))}`;
+}
+function adaptiveDiagnosticFingerprint(method, windowId, segment) {
+    const reasons = Object.keys(segment.diagnostics.rejectionReasons).sort();
+    const segmentationIssues = segment.diagnostics.segmentationIssues?.map((issue) => Object.freeze({ ...issue }));
+    const fingerprintPayload = { methodSha256: method.sha256, windowId, reasons,
+        segmentationIssues: segmentationIssues ?? [] };
+    return sha256(stableJson(fingerprintPayload));
+}
+function adaptivePreviousAttempt(method, source, windowId, segment, attempt, priorSegment) {
+    if (method.version !== "adaptive-repair-v3" && method.version !== "semantic-negation-v4" && method.version !== "harness-v1")
+        return undefined;
+    const window = source.windows.find((candidate) => candidate.id === windowId);
+    if (window === undefined)
+        throw new Error("document_graph_window_unknown");
+    const reasons = Object.keys(segment.diagnostics.rejectionReasons).sort();
+    const segmentationIssues = segment.diagnostics.segmentationIssues?.map((issue) => Object.freeze({ ...issue }));
+    const diagnosticFingerprint = adaptiveDiagnosticFingerprint(method, windowId, segment);
+    return Object.freeze({ attempt, diagnosticFingerprint,
+        repeatedDiagnosticFingerprint: priorSegment !== undefined && adaptiveDiagnosticFingerprint(method, windowId, priorSegment) === diagnosticFingerprint,
+        reasons: Object.freeze(reasons),
+        validLocalNodeIds: Object.freeze(segment.nodes.map((node) => node.localId).sort()),
+        allowedEvidenceUnitIds: Object.freeze([...window.contextUnitIds, ...window.coreUnitIds]),
+        ...(segmentationIssues === undefined ? {} : { segmentationIssues: Object.freeze(segmentationIssues) }) });
+}
+function markerId(scopeId, sourceId) {
+    return id("world-document-source-control", scopeId, sourceId);
+}
+async function readMarker(host, scopeId, sourceId) {
+    const expectedId = markerId(scopeId, sourceId);
+    const response = record(await host.dispatchTool({ name: "world_get", input: { ids: [expectedId], include_relations: true } }), "document_ingestion_world_get_invalid");
+    if (!Array.isArray(response.entities))
+        throw new Error("document_ingestion_world_get_invalid");
+    const entity = response.entities.map((value) => record(value, "document_ingestion_marker_invalid"))
+        .find((value) => value.id === expectedId);
+    if (entity === undefined)
+        return null;
+    if (entity.kind !== CONTROL_KIND)
+        throw new Error("document_ingestion_marker_kind_mismatch");
+    const props = record(entity.props, "document_ingestion_marker_invalid");
+    if (props.scope_id !== scopeId || props.source_id !== sourceId || typeof props.operation_id !== "string" || typeof props.source_revision !== "string"
+        || typeof props.source_sha256 !== "string" || !Array.isArray(props.managed_entity_ids)
+        || !Array.isArray(props.managed_relations) || (props.source_path !== undefined && typeof props.source_path !== "string")
+        || (props.source_storage_path !== undefined && typeof props.source_storage_path !== "string"))
+        throw new Error("document_ingestion_marker_invalid");
+    const managedEntityIds = props.managed_entity_ids.map((value) => {
+        if (typeof value !== "string")
+            throw new Error("document_ingestion_marker_invalid");
+        return value;
+    });
+    const managedRelations = props.managed_relations.map((value) => {
+        const relation = record(value, "document_ingestion_marker_invalid");
+        if (typeof relation.src !== "string" || typeof relation.dst !== "string" || typeof relation.kind !== "string") {
+            throw new Error("document_ingestion_marker_invalid");
+        }
+        return Object.freeze({ src: relation.src, dst: relation.dst, kind: relation.kind });
+    });
+    let commitSummary;
+    if (props.commit_summary !== undefined) {
+        const summary = record(props.commit_summary, "document_ingestion_marker_invalid");
+        const embedding = record(summary.embedding_status, "document_ingestion_marker_invalid");
+        if ((summary.graph_status !== "partial" && summary.graph_status !== "complete")
+            || !Number.isSafeInteger(summary.processed_windows) || !Number.isSafeInteger(summary.node_count) || !Number.isSafeInteger(summary.edge_count)
+            || (embedding.status !== "pending" && embedding.status !== "complete") || typeof embedding.providerId !== "string" || typeof embedding.modelId !== "string"
+            || !Number.isSafeInteger(embedding.dimensions) || !Number.isSafeInteger(summary.previous_project_revision)
+            || !Number.isSafeInteger(summary.next_project_revision))
+            throw new Error("document_ingestion_marker_invalid");
+        const embeddingStatus = Object.freeze({ status: embedding.status, providerId: embedding.providerId,
+            modelId: embedding.modelId, dimensions: embedding.dimensions,
+            hits: Number.isSafeInteger(embedding.hits) ? embedding.hits : 0,
+            misses: Number.isSafeInteger(embedding.misses) ? embedding.misses : 0,
+            remoteTexts: Number.isSafeInteger(embedding.remoteTexts) ? embedding.remoteTexts : 0,
+            writes: Number.isSafeInteger(embedding.writes) ? embedding.writes : 0 });
+        commitSummary = Object.freeze({ graphStatus: summary.graph_status, processedWindows: summary.processed_windows,
+            nodeCount: summary.node_count, edgeCount: summary.edge_count,
+            embeddingStatus,
+            previousProjectRevision: summary.previous_project_revision, nextProjectRevision: summary.next_project_revision });
+    }
+    return Object.freeze({
+        id: expectedId, operationId: props.operation_id,
+        sourceRevision: props.source_revision,
+        sourceSha256: props.source_sha256,
+        ...(props.source_path === undefined ? {} : { sourcePath: props.source_path }),
+        ...(props.source_storage_path === undefined ? {} : { sourceStoragePath: props.source_storage_path }),
+        managedEntityIds: Object.freeze(managedEntityIds),
+        managedRelations: Object.freeze(managedRelations),
+        ...(commitSummary === undefined ? {} : { commitSummary }),
+    });
+}
+async function readManagedSnapshot(host, marker) {
+    if (marker === null || marker.managedEntityIds.length === 0)
+        return Object.freeze({
+            entities: new Map(),
+            externalReferenceEntityIds: new Set(),
+        });
+    const response = record(await host.dispatchTool({ name: "world_get", input: { ids: marker.managedEntityIds, include_relations: true } }), "document_ingestion_world_get_invalid");
+    if (!Array.isArray(response.entities) || !Array.isArray(response.relations))
+        throw new Error("document_ingestion_world_get_invalid");
+    const entities = new Map();
+    for (const value of response.entities) {
+        const entity = record(value, "document_ingestion_managed_entity_invalid");
+        if (typeof entity.id !== "string" || typeof entity.kind !== "string")
+            throw new Error("document_ingestion_managed_entity_invalid");
+        entities.set(entity.id, Object.freeze({ id: entity.id, kind: entity.kind, props: record(entity.props, "document_ingestion_managed_entity_invalid") }));
+    }
+    const ownedRelations = new Set(marker.managedRelations.map(relationKey));
+    const managedIds = new Set(marker.managedEntityIds);
+    const externalReferenceEntityIds = new Set();
+    for (const value of response.relations) {
+        const relation = record(value, "document_ingestion_managed_relation_invalid");
+        if (typeof relation.src !== "string" || typeof relation.dst !== "string" || typeof relation.kind !== "string")
+            throw new Error("document_ingestion_managed_relation_invalid");
+        if (ownedRelations.has(relationKey(relation)))
+            continue;
+        if (managedIds.has(relation.src))
+            externalReferenceEntityIds.add(relation.src);
+        if (managedIds.has(relation.dst))
+            externalReferenceEntityIds.add(relation.dst);
+    }
+    return Object.freeze({ entities, externalReferenceEntityIds });
+}
+export function graphSegment(value, windowId) {
+    const candidate = record(value, "document_ingestion_checkpoint_invalid");
+    if (candidate.windowId !== windowId || (candidate.status !== "complete" && candidate.status !== "partial")
+        || !Array.isArray(candidate.segments) || !Array.isArray(candidate.nodes) || !Array.isArray(candidate.edges)
+        || typeof candidate.diagnostics !== "object" || candidate.diagnostics === null) {
+        throw new Error("document_ingestion_checkpoint_invalid");
+    }
+    return candidate;
+}
+function errorCode(error) {
+    const candidate = error;
+    const code = typeof candidate.code === "string" && /^[a-z0-9_:-]{1,128}$/u.test(candidate.code)
+        ? candidate.code
+        : error instanceof Error && /^[a-z0-9_:-]{1,128}$/u.test(error.message) ? error.message : "document_window_failed";
+    return Object.freeze({ code, retryable: candidate.retryable === true });
+}
+class UnionFind {
+    parent = new Map();
+    add(value) { if (!this.parent.has(value))
+        this.parent.set(value, value); }
+    find(value) {
+        const parent = this.parent.get(value);
+        if (parent === undefined)
+            throw new Error("document_entity_union_unknown");
+        if (parent === value)
+            return value;
+        const root = this.find(parent);
+        this.parent.set(value, root);
+        return root;
+    }
+    union(left, right) {
+        const a = this.find(left), b = this.find(right);
+        if (a !== b)
+            this.parent.set(a.localeCompare(b) <= 0 ? b : a, a.localeCompare(b) <= 0 ? a : b);
+    }
+}
+function evidencedAliases(candidate) {
+    const evidence = candidate.node.statements.map((statement) => statement.evidence.text);
+    return new Set(candidate.node.aliases.filter((alias) => evidence.some((text) => text.includes(candidate.node.label) && text.includes(alias))));
+}
+function mergeEntities(source, segments) {
+    const candidates = segments.flatMap((segment) => segment.nodes.map((node) => Object.freeze({ key: `${segment.windowId}\0${node.localId}`, windowId: segment.windowId, node })));
+    const unions = new UnionFind();
+    candidates.forEach((candidate) => unions.add(candidate.key));
+    const aliases = new Map(candidates.map((candidate) => [candidate.key, evidencedAliases(candidate)]));
+    for (let leftIndex = 0; leftIndex < candidates.length; leftIndex += 1) {
+        for (let rightIndex = leftIndex + 1; rightIndex < candidates.length; rightIndex += 1) {
+            const left = candidates[leftIndex], right = candidates[rightIndex];
+            if (left.node.kind !== right.node.kind)
+                continue;
+            const explicit = aliases.get(left.key).has(right.node.label) || aliases.get(right.key).has(left.node.label)
+                || [...aliases.get(left.key)].some((alias) => aliases.get(right.key).has(alias));
+            if (explicit)
+                unions.union(left.key, right.key);
+        }
+    }
+    const groups = new Map();
+    for (const candidate of candidates) {
+        const root = unions.find(candidate.key);
+        const group = groups.get(root) ?? [];
+        group.push(candidate);
+        groups.set(root, group);
+    }
+    const entities = [...groups.values()].map((group) => {
+        const ordered = [...group].sort((a, b) => a.key.localeCompare(b.key));
+        const labels = new Set(ordered.flatMap((candidate) => [candidate.node.label, ...candidate.node.aliases]));
+        const primary = ordered.map((candidate) => candidate.node.label).sort((a, b) => a.localeCompare(b, "zh-Hans"))[0];
+        const identityParts = [source.scopeId, source.sourceId, ordered[0].node.kind, ...[...labels].sort()];
+        if (ordered.length === 1 || GENERIC_ENTITY_LABEL.test(primary))
+            identityParts.push(...ordered.map((candidate) => candidate.key));
+        return Object.freeze({
+            id: id("world-document-entity", ...identityParts),
+            label: primary,
+            kind: ordered[0].node.kind,
+            aliases: Object.freeze([...labels].filter((label) => label !== primary).sort((a, b) => a.localeCompare(b, "zh-Hans"))),
+            statements: Object.freeze(ordered.flatMap((candidate) => candidate.node.statements)),
+            candidates: Object.freeze(ordered),
+        });
+    });
+    const localToStable = new Map();
+    for (const entity of entities)
+        for (const candidate of entity.candidates)
+            localToStable.set(candidate.key, entity.id);
+    return Object.freeze({ entities: Object.freeze(entities), localToStable });
+}
+export function knownDocumentGraphEntities(source, segments) {
+    return mergeEntities(source, segments).entities.map((entity) => Object.freeze({
+        stableId: entity.id, label: entity.label, kind: entity.kind, aliases: entity.aliases,
+    }));
+}
+function relationKey(value) {
+    return `${value.src}\0${value.dst}\0${value.kind}`;
+}
+/** 旧 immutable checkpoint 只存聚合 quote；装配时由原始 units 补齐精确片段，禁止填补证据间隙。 */
+function documentEvidenceResolver(source) {
+    const units = new Map(source.units.map((unit) => [unit.id, unit]));
+    const resolved = new Map();
+    return (evidence) => {
+        const cached = resolved.get(evidence);
+        if (cached !== undefined)
+            return cached;
+        if (!Array.isArray(evidence.unitIds) || evidence.unitIds.length === 0)
+            throw new Error("document_ingestion_evidence_units_invalid");
+        let previousEnd = -1;
+        const seen = new Set();
+        const spans = evidence.unitIds.map((unitId) => {
+            const unit = units.get(unitId);
+            if (unit === undefined || seen.has(unitId) || unit.startOffset < previousEnd)
+                throw new Error("document_ingestion_evidence_units_invalid");
+            seen.add(unitId);
+            previousEnd = unit.endOffset;
+            return Object.freeze({ unit_id: unit.id, quote: unit.text, start_offset: unit.startOffset, end_offset: unit.endOffset });
+        });
+        const quote = spans.map((span) => span.quote).join("");
+        if (quote !== evidence.text || spans[0].start_offset !== evidence.startOffset || spans.at(-1).end_offset !== evidence.endOffset) {
+            throw new Error("document_ingestion_evidence_source_mismatch");
+        }
+        const canonical = Object.freeze({ unit_ids: Object.freeze([...evidence.unitIds]), quote,
+            start_offset: evidence.startOffset, end_offset: evidence.endOffset, offset_semantics: "envelope_only", spans: Object.freeze(spans) });
+        resolved.set(evidence, canonical);
+        return canonical;
+    };
+}
+async function assemble(source, planSha256, segments, cache, signal, sourcePath, sourceStoragePath) {
+    const semanticPlan = Object.freeze({
+        schemaVersion: 1,
+        documentId: source.documentId,
+        segments: Object.freeze(segments.flatMap((segment) => segment.segments.map((item) => Object.freeze({ ...item })))),
+    });
+    const plan = validateDocumentPlan(source, semanticPlan);
+    const resolveEvidence = documentEvidenceResolver(source);
+    const evidenceProps = (evidence) => asJson(resolveEvidence(evidence));
+    const merged = mergeEntities(source, segments);
+    const documentId = id("world-source-document", source.scopeId, source.sourceId, source.sourceRevision, source.sourceSha256);
+    const chunkIds = plan.segments.map((chunk) => id("world-source-chunk", source.scopeId, source.sourceId, chunk.startUnitId, chunk.endUnitId));
+    const chunkEmbeddingText = plan.segments.map((chunk) => chunk.indexText.normalize("NFC").trim());
+    const semanticIndexText = new Map(merged.entities.map((entity) => [entity.id,
+        [entity.label, ...entity.aliases, entity.kind].join("\n").normalize("NFC").trim()]));
+    const statementNodes = merged.entities.flatMap((entity) => entity.statements.map((statement) => ({
+        id: id("world-document-statement", source.scopeId, source.sourceId, entity.id, stableJson(statement)),
+        entityId: entity.id,
+        statement,
+        evidence: resolveEvidence(statement.evidence),
+        indexText: [entity.label, statement.assertion, statement.evidence.text].join("\n").normalize("NFC").trim(),
+    })));
+    const edgeAssertionNodes = segments.flatMap((segment) => segment.edges.map((edge) => {
+        const src = merged.localToStable.get(`${segment.windowId}\0${edge.sourceLocalId}`);
+        const dst = merged.localToStable.get(`${segment.windowId}\0${edge.targetLocalId}`);
+        if (src === undefined || dst === undefined)
+            throw new Error("document_ingestion_edge_endpoint_missing");
+        return { id: id("world-document-edge-assertion", source.scopeId, source.sourceId, src, dst, stableJson(edge)), src, dst, edge, evidence: resolveEvidence(edge.evidence),
+            indexText: [edge.assertion, edge.evidence.text].join("\n").normalize("NFC").trim() };
+    }));
+    const searchable = Object.freeze([
+        ...plan.segments.flatMap((_chunk, index) => chunkEmbeddingText[index].length === 0 ? [] : [{ id: chunkIds[index], kind: "chunk", text: chunkEmbeddingText[index] }]),
+        ...merged.entities.map((entity) => ({
+            id: entity.id,
+            kind: "entity",
+            text: semanticIndexText.get(entity.id),
+        })),
+        ...statementNodes.map((statement) => ({ id: statement.id, kind: "statement", text: statement.indexText })),
+        ...edgeAssertionNodes.map((assertion) => ({ id: assertion.id, kind: "edge_assertion", text: assertion.indexText })),
+    ]);
+    const vectors = cache === undefined || searchable.length === 0 ? [] : await cache.embed(searchable.map((entry) => entry.text), signal === undefined ? {} : { signal });
+    if (cache === undefined && vectors.length !== 0)
+        throw new Error("document_ingestion_embedding_unexpected");
+    if (cache !== undefined && vectors.length !== searchable.length)
+        throw new Error("document_ingestion_embedding_count_invalid");
+    const vectorById = new Map(searchable.map((entry, index) => [entry.id, vectors[index]]));
+    const embeddingProps = (entityId) => cache === undefined
+        ? {}
+        : { embedding: vectorById.get(entityId), embedding_provider_id: cache.providerId,
+            embedding_model_id: cache.modelId, embedding_dimensions: cache.dimensions };
+    const entities = [{
+            type: "upsert_entity", id: documentId, kind: DOCUMENT_KIND,
+            props: asJson({
+                scope_id: source.scopeId, source_id: source.sourceId, source_revision: source.sourceRevision,
+                source_path: sourcePath ?? null, raw_base64: source.originalBytesBase64, byte_sha256: source.sourceSha256,
+                source_storage_path: sourceStoragePath ?? null,
+                raw_byte_length: source.byteLength, utf16_length: source.utf16Length, encoding: "utf-8",
+                utf8_bom: source.utf8Bom, offset_domain: source.offsetDomain, plan_digest: planSha256,
+                source_revision_active: true, retrieval_excluded: true,
+            }),
+        }];
+    for (const [index, chunk] of plan.segments.entries())
+        entities.push({
+            type: "upsert_entity", id: chunkIds[index], kind: CHUNK_KIND,
+            props: asJson({
+                scope_id: source.scopeId, source_id: source.sourceId, source_revision: source.sourceRevision,
+                document_id: documentId, ordinal: index, title: chunk.title, start_unit_id: chunk.startUnitId,
+                end_unit_id: chunk.endUnitId, start_offset: chunk.startOffset, end_offset: chunk.endOffset,
+                index_text: chunk.indexText, content_sha256: sha256(new TextEncoder().encode(chunk.indexText)),
+                source_revision_active: true,
+                ...(chunkEmbeddingText[index].length === 0 ? { retrieval_excluded: true } : embeddingProps(chunkIds[index])),
+            }),
+        });
+    for (const entity of merged.entities)
+        entities.push({
+            type: "upsert_entity", id: entity.id, kind: `world_document_${entity.kind}`,
+            props: asJson({
+                scope_id: source.scopeId, source_id: source.sourceId, source_revision: source.sourceRevision,
+                label: entity.label, aliases: entity.aliases, statements: entity.statements.map((statement) => ({ ...statement, evidence: resolveEvidence(statement.evidence) })),
+                index_text: semanticIndexText.get(entity.id), source_revision_active: true, ...embeddingProps(entity.id),
+            }),
+        });
+    for (const item of statementNodes)
+        entities.push({ type: "upsert_entity", id: item.id, kind: "world_document_statement", props: asJson({
+                scope_id: source.scopeId, source_id: source.sourceId, source_revision: source.sourceRevision, subject_entity_id: item.entityId,
+                predicate: item.statement.predicate, assertion: item.statement.assertion, value: item.statement.value,
+                qualifiers: item.statement.qualifiers, evidence: item.evidence, index_text: item.indexText,
+                source_revision_active: true, ...embeddingProps(item.id),
+            }) });
+    for (const item of edgeAssertionNodes)
+        entities.push({ type: "upsert_entity", id: item.id, kind: "world_document_edge_assertion", props: asJson({
+                scope_id: source.scopeId, source_id: source.sourceId, source_revision: source.sourceRevision, source_entity_id: item.src,
+                target_entity_id: item.dst, predicate: item.edge.predicate, assertion: item.edge.assertion, qualifiers: item.edge.qualifiers,
+                evidence: item.evidence, index_text: item.indexText, source_revision_active: true, ...embeddingProps(item.id),
+            }) });
+    const relations = new Map();
+    const addRelation = (relation) => relations.set(relationKey(relation), relation);
+    plan.segments.forEach((_chunk, index) => {
+        addRelation({ type: "upsert_relation", src: chunkIds[index], dst: documentId, kind: "part_of", props: asJson({ ordinal: index }) });
+        if (index > 0)
+            addRelation({ type: "upsert_relation", src: chunkIds[index - 1], dst: chunkIds[index], kind: "next_chunk", props: {} });
+    });
+    const chunksForEvidence = (evidence) => {
+        const spans = resolveEvidence(evidence).spans;
+        const ids = plan.segments.flatMap((chunk, index) => spans.some((span) => chunk.startOffset < span.end_offset && chunk.endOffset > span.start_offset) ? [chunkIds[index]] : []);
+        if (ids.length === 0)
+            throw new Error("document_ingestion_evidence_chunk_missing");
+        return ids;
+    };
+    for (const entity of merged.entities)
+        for (const statement of entity.statements) {
+            const statementId = id("world-document-statement", source.scopeId, source.sourceId, entity.id, stableJson(statement));
+            addRelation({ type: "upsert_relation", src: statementId, dst: entity.id, kind: "describes", props: {} });
+            for (const chunkId of chunksForEvidence(statement.evidence)) {
+                addRelation({ type: "upsert_relation", src: chunkId, dst: entity.id, kind: "mentions", props: evidenceProps(statement.evidence) });
+                addRelation({ type: "upsert_relation", src: chunkId, dst: statementId, kind: "supports", props: evidenceProps(statement.evidence) });
+            }
+        }
+    for (const segment of segments)
+        for (const edge of segment.edges) {
+            const src = merged.localToStable.get(`${segment.windowId}\0${edge.sourceLocalId}`);
+            const dst = merged.localToStable.get(`${segment.windowId}\0${edge.targetLocalId}`);
+            if (src === undefined || dst === undefined)
+                throw new Error("document_ingestion_edge_endpoint_missing");
+            addRelation({ type: "upsert_relation", src, dst, kind: edge.predicate, props: asJson({ assertion: edge.assertion, qualifiers: edge.qualifiers,
+                    evidence: evidenceProps(edge.evidence), source_chunk_ids: chunksForEvidence(edge.evidence) }) });
+            const assertionId = id("world-document-edge-assertion", source.scopeId, source.sourceId, src, dst, stableJson(edge));
+            addRelation({ type: "upsert_relation", src: assertionId, dst: src, kind: "describes_source", props: {} });
+            addRelation({ type: "upsert_relation", src: assertionId, dst, kind: "describes_target", props: {} });
+            for (const chunkId of chunksForEvidence(edge.evidence)) {
+                addRelation({ type: "upsert_relation", src: chunkId, dst: assertionId, kind: "supports", props: evidenceProps(edge.evidence) });
+            }
+        }
+    return Object.freeze({
+        operations: Object.freeze([...entities, ...relations.values()]),
+        entityIds: Object.freeze(entities.filter((operation) => operation.type === "upsert_entity").map((operation) => operation.id)),
+        relations: Object.freeze([...relations.values()].map(({ src, dst, kind }) => Object.freeze({ src, dst, kind }))),
+        nodeCount: entities.length,
+        edgeCount: relations.size,
+        plan,
+        embeddingTexts: searchable,
+    });
+}
+export async function prepareDocumentGraphEmbedding(projectRoot, operationId) {
+    const descriptor = await readStagedDocumentInput(projectRoot, operationId);
+    const rawStatus = await readDocumentIngestionJournalStatus(projectRoot, operationId);
+    const status = await readLosslessDocumentStatus(projectRoot, operationId);
+    if (status.phase !== "committed")
+        throw new Error("document_ingestion_graph_not_ready");
+    const journalMethod = status.method === undefined ? ingestionMethod("legacy-v1") : status.method;
+    if (status.sourceByteSha256 !== sha256(descriptor.input.bytes) || status.planSha256 !== descriptor.planSha256
+        || stableJson(journalMethod) !== stableJson(descriptor.method))
+        throw new Error("document_ingestion_descriptor_identity_mismatch");
+    const source = buildDocumentSource({ bytes: descriptor.input.bytes, scopeId: descriptor.input.scopeId, sourceId: descriptor.input.sourceId,
+        sourceRevision: descriptor.input.sourceRevision, ...(descriptor.sourceOptions === undefined ? {} : { options: descriptor.sourceOptions }) });
+    const segments = [];
+    for (const window of source.windows) {
+        if (!status.completedSegmentIds.includes(window.id))
+            throw new Error("document_ingestion_graph_not_ready");
+        const retryCompleteId = `${RETRY_COMPLETE_PREFIX}${window.id}`;
+        const segmentId = rawStatus.completedSegmentIds.includes(retryCompleteId) ? retryCompleteId : window.id;
+        const segment = graphSegment(await readDocumentIngestionCheckpoint(projectRoot, operationId, segmentId), window.id);
+        if (segment.status !== "complete")
+            throw new Error("document_ingestion_graph_not_ready");
+        segments.push(segment);
+    }
+    const assembled = await assemble(source, descriptor.planSha256, segments, undefined, undefined, descriptor.input.sourcePath, descriptor.input.sourceStoragePath);
+    const texts = Object.freeze(assembled.embeddingTexts.map((entry) => Object.freeze({ ...entry })));
+    return Object.freeze({
+        schemaVersion: 1,
+        operationId,
+        method: descriptor.method,
+        sourceIdentity: Object.freeze({ scopeId: source.scopeId, sourceId: source.sourceId, sourceRevision: source.sourceRevision, sourceSha256: source.sourceSha256 }),
+        planSha256: descriptor.planSha256,
+        graphSha256: sha256(stableJson({ methodSha256: descriptor.method.sha256, planSha256: descriptor.planSha256, texts })),
+        graphStatus: "complete",
+        texts,
+    });
+}
+function emptyEmbeddingStatus(connection) {
+    return Object.freeze({ status: "pending", providerId: connection.embedding.providerId, modelId: connection.embedding.modelId,
+        dimensions: connection.embedding.dimensions, hits: 0, misses: 0, remoteTexts: 0, writes: 0 });
+}
+function receiptFromStored(value) {
+    const candidate = record(value, "document_ingestion_receipt_invalid");
+    if (candidate.schemaVersion !== 1 || typeof candidate.operationId !== "string"
+        || (candidate.status !== "committed" && candidate.status !== "already_committed"))
+        throw new Error("document_ingestion_receipt_invalid");
+    return Object.freeze({ ...candidate, status: "already_committed" });
+}
+/**
+ * 全文导入的唯一编排入口。模型与 embedding 结果先进入 journal/cache；只有所有窗口
+ * 都有已校验 checkpoint 时，才以最初捕获的 revision 做一次原子 world_apply。
+ */
+export async function ingestLosslessDocument(host, input, capability) {
+    return ingestLosslessDocumentWithMethod(host, input, capability, ingestionMethod(capability.methodVersion ?? "semantic-negation-v4"));
+}
+async function ingestLosslessDocumentWithMethod(host, input, capability, method) {
+    const dependencies = {
+        extractWindow: capability.dependencies?.extractWindow ?? extractDocumentGraphWindow,
+        openJournal: capability.dependencies?.openJournal ?? openDocumentIngestionJournal,
+        createEmbeddingCache: capability.dependencies?.createEmbeddingCache ?? createCachedEmbeddingPort,
+    };
+    const observed = await host.inspect();
+    if (!Number.isSafeInteger(observed.project_revision) || observed.project_revision < 0)
+        throw new Error("document_ingestion_revision_invalid");
+    const marker = await readMarker(host, input.scopeId, input.sourceId);
+    const source = buildDocumentSource({ bytes: input.bytes, sourceId: input.sourceId, sourceRevision: input.sourceRevision, scopeId: input.scopeId,
+        ...(capability.sourceOptions === undefined ? {} : { options: capability.sourceOptions }) });
+    const roundtripVerified = sameBytes(documentSourceBytes(source), input.bytes);
+    if (!roundtripVerified)
+        throw new Error("document_ingestion_roundtrip_failed");
+    if (marker?.sourceRevision === input.sourceRevision && marker.sourceSha256 !== source.sourceSha256) {
+        throw new Error("document_ingestion_source_revision_mismatch");
+    }
+    const extractionPlan = sourcePlan(source, method);
+    const modelId = capability.modelConnection.structuredJson.modelId;
+    const operationId = operationIdentity(source, method);
+    const documentId = id("world-source-document", source.scopeId, source.sourceId, source.sourceRevision, source.sourceSha256);
+    const emitProgress = async (progress) => {
+        await capability.onProgress?.(Object.freeze({ schemaVersion: 1, operationId, totalWindows: source.windows.length, ...progress }));
+    };
+    if (marker?.operationId === operationId && marker.sourceRevision === input.sourceRevision && marker.sourceSha256 === source.sourceSha256) {
+        if (marker.commitSummary === undefined)
+            throw new Error("document_ingestion_marker_commit_summary_missing");
+        const recovered = Object.freeze({ schemaVersion: 1, operationId, documentId, status: "already_committed", rawByteSha256: source.sourceSha256,
+            rawByteLength: source.byteLength,
+            ...(marker.sourcePath === undefined ? {} : { sourcePath: marker.sourcePath }),
+            ...(marker.sourceStoragePath === undefined ? {} : { sourceStoragePath: marker.sourceStoragePath }),
+            roundtripVerified, sourceCoverage: Object.freeze({ status: "complete", utf16Length: source.utf16Length,
+                unitCount: source.units.length, coveredUnitCount: source.units.length }), graphStatus: marker.commitSummary.graphStatus,
+            processedWindows: marker.commitSummary.processedWindows, pendingWindows: Object.freeze([]), failedWindows: Object.freeze([]),
+            nodeCount: marker.commitSummary.nodeCount, edgeCount: marker.commitSummary.edgeCount, embeddingStatus: marker.commitSummary.embeddingStatus,
+            previousProjectRevision: marker.commitSummary.previousProjectRevision, nextProjectRevision: marker.commitSummary.nextProjectRevision });
+        let stagedStatus;
+        try {
+            stagedStatus = await readLosslessDocumentStatus(capability.projectRoot, operationId);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        if (stagedStatus?.phase === "committing") {
+            const recoveryJournal = await dependencies.openJournal({ projectRoot: capability.projectRoot, operationId,
+                sourceByteSha256: source.sourceSha256, planSha256: extractionPlan.sha256, modelId: stagedStatus.modelId,
+                expectedProjectRevision: marker.commitSummary.previousProjectRevision,
+                ...(method.version === "legacy-v1" ? {} : { method }) });
+            try {
+                await recoveryJournal.recordCommitReceipt(asJson(recovered));
+            }
+            finally {
+                await recoveryJournal.close();
+            }
+        }
+        await emitProgress({ event: "phase_changed", phase: "committed", processedWindows: recovered.processedWindows });
+        return recovered;
+    }
+    let expectedProjectRevision = observed.project_revision;
+    try {
+        expectedProjectRevision = (await readLosslessDocumentStatus(capability.projectRoot, operationId)).expectedProjectRevision;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const journal = await dependencies.openJournal({ projectRoot: capability.projectRoot, operationId,
+        sourceByteSha256: source.sourceSha256, planSha256: extractionPlan.sha256, modelId,
+        expectedProjectRevision, ...(method.version === "legacy-v1" ? {} : { method }) });
+    try {
+        let status = await journal.getStatus();
+        if (status.phase === "committed") {
+            const receipt = Object.freeze({ ...receiptFromStored(status.commitReceipt), documentId });
+            await emitProgress({ event: "phase_changed", phase: "committed", processedWindows: receipt.processedWindows });
+            return receipt;
+        }
+        if (observed.project_revision !== expectedProjectRevision) {
+            throw Object.assign(new Error("document_ingestion_project_revision_conflict"), { code: "E_STALE_PROJECT_REVISION",
+                expected_project_revision: expectedProjectRevision, actual_project_revision: observed.project_revision });
+        }
+        if (status.phase === "extracting") {
+            if (await journal.readSegment(SOURCE_DESCRIPTOR_ID) === null) {
+                const descriptor = asJson({ schema_version: method.version === "legacy-v1" ? 1 : 2, operation_id: operationId, input: { raw_base64: source.originalBytesBase64, scope_id: input.scopeId,
+                        source_id: input.sourceId, source_revision: input.sourceRevision, ...(input.sourcePath === undefined ? {} : { source_path: input.sourcePath }),
+                        ...(input.sourceStoragePath === undefined ? {} : { source_storage_path: input.sourceStoragePath }) },
+                    ...(capability.sourceOptions === undefined ? {} : { source_options: capability.sourceOptions }), plan_sha256: extractionPlan.sha256,
+                    ...(method.version === "legacy-v1" ? {} : { method: { version: method.version, sha256: method.sha256,
+                            prompt_version: method.promptVersion, schema_version: method.schemaVersion, merge_version: method.mergeVersion,
+                            embedding_policy: method.embeddingPolicy,
+                            ...(method.validatorDiagnosticsVersion === undefined ? {} : { validator_diagnostics_version: method.validatorDiagnosticsVersion }),
+                            ...(method.repairPolicyVersion === undefined ? {} : { repair_policy_version: method.repairPolicyVersion }) } }) });
+                await journal.writeSegment(SOURCE_DESCRIPTOR_ID, descriptor);
+            }
+            status = await journal.getStatus();
+        }
+        const completed = new Map();
+        const partialCheckpoints = new Map();
+        const partialAttemptCounts = new Map();
+        let clearedRecoveredFailure = false;
+        for (const window of source.windows) {
+            const retryCompleteId = `${RETRY_COMPLETE_PREFIX}${window.id}`;
+            if (status.completedSegmentIds.includes(retryCompleteId)) {
+                const saved = await journal.readSegment(retryCompleteId);
+                if (saved === null)
+                    throw new Error("document_ingestion_checkpoint_missing");
+                const segment = graphSegment(saved, window.id);
+                if (segment.status !== "complete")
+                    throw new Error("document_ingestion_checkpoint_invalid");
+                completed.set(window.id, segment);
+                if (status.failedSegments.some((failure) => failure.id === window.id)) {
+                    await journal.clearSegmentFailure(window.id);
+                    clearedRecoveredFailure = true;
+                }
+                continue;
+            }
+            if (!status.completedSegmentIds.includes(window.id))
+                continue;
+            const saved = await journal.readSegment(window.id);
+            if (saved === null)
+                throw new Error("document_ingestion_checkpoint_missing");
+            const segment = graphSegment(saved, window.id);
+            if (method.version !== "legacy-v1" && segment.status === "partial")
+                partialCheckpoints.set(window.id, segment);
+            else
+                completed.set(window.id, segment);
+        }
+        if (method.version !== "legacy-v1")
+            for (const window of source.windows) {
+                const prefix = `${PARTIAL_ATTEMPT_PREFIX}${window.id}:`;
+                const archivedIds = status.completedSegmentIds.filter((id) => id.startsWith(prefix))
+                    .sort((left, right) => Number(left.slice(prefix.length)) - Number(right.slice(prefix.length)));
+                if (archivedIds.length > 0) {
+                    const latest = await journal.readSegment(archivedIds.at(-1));
+                    if (latest === null)
+                        throw new Error("document_ingestion_checkpoint_missing");
+                    partialCheckpoints.set(window.id, graphSegment(latest, window.id));
+                }
+                const archivedAttempt = archivedIds.length === 0 ? 0 : Number(archivedIds.at(-1).slice(prefix.length));
+                if (!Number.isSafeInteger(archivedAttempt) || archivedAttempt < 0)
+                    throw new Error("document_ingestion_checkpoint_invalid");
+                partialAttemptCounts.set(window.id, Math.max(archivedAttempt, partialCheckpoints.has(window.id) ? 1 : 0));
+            }
+        if (method.version !== "legacy-v1")
+            for (const window of source.windows) {
+                const attempts = partialAttemptCounts.get(window.id) ?? 0;
+                const failure = status.failedSegments.find((candidate) => candidate.id === window.id);
+                if (attempts >= MAX_PARTIAL_ATTEMPTS && failure?.code !== "document_graph_partial_retry_exhausted") {
+                    await journal.recordSegmentFailure(window.id, { code: "document_graph_partial_retry_exhausted", retryable: false, attempts });
+                    clearedRecoveredFailure = true;
+                }
+            }
+        if (clearedRecoveredFailure)
+            status = await journal.getStatus();
+        const exhausted = new Set(status.failedSegments.filter((failure) => failure.code === "document_graph_partial_retry_exhausted").map((failure) => failure.id));
+        const remaining = source.windows.filter((window) => !completed.has(window.id) && !exhausted.has(window.id));
+        const requiredPorts = [];
+        if (remaining.length > 0)
+            requiredPorts.push("structured");
+        if (method.embeddingPolicy === "immediate")
+            requiredPorts.push("embedding");
+        if (requiredPorts.length > 0)
+            capability.modelConnection.assertAvailable?.(requiredPorts);
+        await emitProgress({ event: "source_staged", phase: status.phase, processedWindows: completed.size });
+        if (status.phase === "extracting") {
+            const previouslyTruncated = new Set(status.failedSegments.filter((failure) => failure.code === "provider_output_truncated").map((failure) => failure.id));
+            const concurrency = capability.concurrency ?? 4;
+            if (!Number.isSafeInteger(concurrency) || concurrency < 1 || concurrency > 16)
+                throw new Error("document_ingestion_concurrency_invalid");
+            for (let offset = 0; offset < remaining.length; offset += concurrency) {
+                if (capability.signal?.aborted)
+                    break;
+                const catalog = knownDocumentGraphEntities(source, [...completed.values()]);
+                const outcomes = await Promise.allSettled(remaining.slice(offset, offset + concurrency).map(async (window) => {
+                    let failure;
+                    const previousPartial = partialCheckpoints.get(window.id);
+                    const previousAttemptCount = partialAttemptCounts.get(window.id) ?? 0;
+                    try {
+                        let priorPartial;
+                        const adaptiveMethod = method.version === "adaptive-repair-v3" || method.version === "semantic-negation-v4" || method.version === "harness-v1";
+                        if (adaptiveMethod && previousAttemptCount > 1) {
+                            const prior = await journal.readSegment(`${PARTIAL_ATTEMPT_PREFIX}${window.id}:${previousAttemptCount - 1}`);
+                            if (prior !== null)
+                                priorPartial = graphSegment(prior, window.id);
+                        }
+                        const extracted = await dependencies.extractWindow({ window, source, knownEntities: catalog, modelConnection: capability.modelConnection,
+                            ingestionMethod: method,
+                            ...(adaptiveMethod ? { methodVersion: method.version } : {}),
+                            ...(!adaptiveMethod || previousPartial === undefined ? {} : {
+                                adaptiveRepair: adaptivePreviousAttempt(method, source, window.id, previousPartial, previousAttemptCount, priorPartial),
+                            }),
+                            ...(previouslyTruncated.has(window.id) ? { maxOutputTokens: 65_536 } : {}),
+                            ...(capability.signal === undefined ? {} : { signal: capability.signal }) });
+                        if (method.version !== "legacy-v1" && extracted.status === "partial") {
+                            const attempts = (partialAttemptCounts.get(window.id) ?? 0) + 1;
+                            if (previousPartial !== undefined && attempts === 2) {
+                                await journal.writeSegment(`${PARTIAL_ATTEMPT_PREFIX}${window.id}:1`, asJson(previousPartial));
+                            }
+                            await journal.writeSegment(`${PARTIAL_ATTEMPT_PREFIX}${window.id}:${attempts}`, asJson(extracted));
+                            partialAttemptCounts.set(window.id, attempts);
+                            failure = Object.freeze({ code: attempts >= MAX_PARTIAL_ATTEMPTS
+                                    ? "document_graph_partial_retry_exhausted" : "document_graph_partial", retryable: attempts < MAX_PARTIAL_ATTEMPTS });
+                            await journal.recordSegmentFailure(window.id, { ...failure, attempts });
+                        }
+                        else {
+                            if (previousPartial !== undefined) {
+                                if ((partialAttemptCounts.get(window.id) ?? 0) === 1) {
+                                    await journal.writeSegment(`${PARTIAL_ATTEMPT_PREFIX}${window.id}:1`, asJson(previousPartial));
+                                }
+                                await journal.writeSegment(`${RETRY_COMPLETE_PREFIX}${window.id}`, asJson(extracted));
+                                await journal.clearSegmentFailure(window.id);
+                            }
+                            else {
+                                await journal.writeSegment(window.id, asJson(extracted));
+                            }
+                            partialCheckpoints.delete(window.id);
+                            completed.set(window.id, extracted);
+                        }
+                    }
+                    catch (error) {
+                        if ((method.version === "adaptive-repair-v3" || method.version === "semantic-negation-v4" || method.version === "harness-v1")
+                            && error instanceof DocumentGraphExtractionError) {
+                            const attempts = previousAttemptCount + 1;
+                            const diagnosticCheckpoint = Object.freeze({ windowId: window.id, status: "partial", segments: Object.freeze([]),
+                                nodes: Object.freeze([]), edges: Object.freeze([]), diagnostics: error.diagnostics });
+                            await journal.writeSegment(`${PARTIAL_ATTEMPT_PREFIX}${window.id}:${attempts}`, asJson(diagnosticCheckpoint));
+                            partialAttemptCounts.set(window.id, attempts);
+                            partialCheckpoints.set(window.id, diagnosticCheckpoint);
+                            failure = Object.freeze({ code: attempts >= MAX_PARTIAL_ATTEMPTS
+                                    ? "document_graph_partial_retry_exhausted" : "document_graph_partial", retryable: attempts < MAX_PARTIAL_ATTEMPTS });
+                            await journal.recordSegmentFailure(window.id, { ...failure, attempts });
+                        }
+                        else {
+                            failure = errorCode(error);
+                            await journal.recordSegmentFailure(window.id, failure);
+                        }
+                    }
+                    // consumer 错误不冒充模型失败；当前并发批次全部收敛后再关闭 journal。
+                    await emitProgress({ event: failure === undefined ? "window_completed" : "window_failed", phase: "extracting",
+                        processedWindows: completed.size, windowId: window.id, ...(failure === undefined ? {} : { failure: Object.freeze(failure) }) });
+                }));
+                const failed = outcomes.find((outcome) => outcome.status === "rejected");
+                if (failed !== undefined)
+                    throw failed.reason;
+            }
+            status = await journal.getStatus();
+        }
+        const pendingWindows = source.windows.filter((window) => !completed.has(window.id)).map((window) => window.id);
+        const failedWindows = status.failedSegments.filter((failure) => pendingWindows.includes(failure.id));
+        const sourceCoverage = Object.freeze({ status: "complete", utf16Length: source.utf16Length, unitCount: source.units.length, coveredUnitCount: source.units.length });
+        if (pendingWindows.length > 0)
+            return Object.freeze({
+                schemaVersion: 1, operationId, documentId, status: "staged", rawByteSha256: source.sourceSha256, rawByteLength: source.byteLength,
+                ...(input.sourcePath === undefined ? {} : { sourcePath: input.sourcePath }),
+                ...(input.sourceStoragePath === undefined ? {} : { sourceStoragePath: input.sourceStoragePath }),
+                roundtripVerified, sourceCoverage, graphStatus: [...partialAttemptCounts.values()].some((attempts) => attempts > 0) || completed.size > 0 ? "partial" : "pending",
+                processedWindows: completed.size, pendingWindows: Object.freeze(pendingWindows), failedWindows: Object.freeze(failedWindows),
+                nodeCount: 0, edgeCount: 0, embeddingStatus: emptyEmbeddingStatus(capability.modelConnection),
+            });
+        if (status.phase === "extracting") {
+            await journal.markPhase("ready_to_commit");
+            status = await journal.getStatus();
+            await emitProgress({ event: "phase_changed", phase: status.phase, processedWindows: completed.size });
+        }
+        const orderedSegments = source.windows.map((window) => completed.get(window.id));
+        const cache = method.embeddingPolicy === "immediate"
+            ? await dependencies.createEmbeddingCache({ projectRoot: capability.projectRoot, embedding: capability.modelConnection.embedding,
+                ...(capability.embeddingOrigin === undefined ? {} : { origin: capability.embeddingOrigin }) })
+            : undefined;
+        const managedSnapshot = await readManagedSnapshot(host, marker);
+        const assembled = await assemble(source, extractionPlan.sha256, orderedSegments, cache, capability.signal, input.sourcePath, input.sourceStoragePath);
+        const currentEntityIds = new Set(assembled.entityIds);
+        const currentRelationKeys = new Set(assembled.relations.map(relationKey));
+        const deletes = [
+            ...(marker?.managedRelations ?? []).filter((relation) => !currentRelationKeys.has(relationKey(relation))).map((relation) => ({ type: "delete_relation", ...relation })),
+            ...(marker?.managedEntityIds ?? []).filter((entityId) => !currentEntityIds.has(entityId) && !managedSnapshot.externalReferenceEntityIds.has(entityId))
+                .map((entityId) => ({ type: "delete_entity", id: entityId })),
+        ];
+        const retainedExternalEntities = [...managedSnapshot.externalReferenceEntityIds]
+            .filter((entityId) => !currentEntityIds.has(entityId))
+            .flatMap((entityId) => {
+            const entity = managedSnapshot.entities.get(entityId);
+            return entity === undefined ? [] : [{ type: "upsert_entity", id: entity.id, kind: entity.kind,
+                    props: asJson({ ...entity.props, retrieval_excluded: true, source_revision_active: false }) }];
+        });
+        const counts = cache?.getCounts() ?? { hits: 0, misses: 0, remoteTexts: 0, writes: 0 };
+        const graphStatus = orderedSegments.every((segment) => segment.status === "complete") ? "complete" : "partial";
+        const embeddingStatus = Object.freeze({ status: cache === undefined ? "pending" : "complete",
+            providerId: cache?.providerId ?? capability.modelConnection.embedding.providerId,
+            modelId: cache?.modelId ?? capability.modelConnection.embedding.modelId,
+            dimensions: cache?.dimensions ?? capability.modelConnection.embedding.dimensions, ...counts });
+        const markerOperation = { type: "upsert_entity", id: markerId(input.scopeId, input.sourceId), kind: CONTROL_KIND, props: asJson({
+                scope_id: input.scopeId, source_id: input.sourceId, source_revision: input.sourceRevision, source_sha256: source.sourceSha256,
+                ...(input.sourcePath === undefined ? {} : { source_path: input.sourcePath }),
+                ...(input.sourceStoragePath === undefined ? {} : { source_storage_path: input.sourceStoragePath }),
+                operation_id: operationId, managed_entity_ids: assembled.entityIds, managed_relations: assembled.relations,
+                method_version: method.version, method_sha256: method.sha256,
+                commit_summary: { graph_status: graphStatus, processed_windows: source.windows.length, node_count: assembled.nodeCount,
+                    edge_count: assembled.edgeCount, embedding_status: embeddingStatus, previous_project_revision: expectedProjectRevision,
+                    next_project_revision: expectedProjectRevision + 1 },
+                retrieval_excluded: true,
+            }) };
+        if (status.phase === "ready_to_commit") {
+            await journal.markPhase("committing");
+            await emitProgress({ event: "phase_changed", phase: "committing", processedWindows: completed.size });
+        }
+        const apply = record(await host.dispatchTool({ name: "world_apply", input: { operations: [...deletes, ...retainedExternalEntities, ...assembled.operations, markerOperation] },
+            effect_identity: { operation_id: operationId, expected_project_revision: expectedProjectRevision } }), "document_ingestion_apply_receipt_invalid");
+        if (apply.schema_version !== 1 || apply.operation_id !== operationId || apply.previous_project_revision !== expectedProjectRevision
+            || !Number.isSafeInteger(apply.next_project_revision) || apply.readback_verified !== true)
+            throw new Error("document_ingestion_apply_receipt_invalid");
+        const receipt = Object.freeze({
+            schemaVersion: 1, operationId, documentId, status: "committed", rawByteSha256: source.sourceSha256, rawByteLength: source.byteLength,
+            ...(input.sourcePath === undefined ? {} : { sourcePath: input.sourcePath }),
+            ...(input.sourceStoragePath === undefined ? {} : { sourceStoragePath: input.sourceStoragePath }),
+            roundtripVerified, sourceCoverage, graphStatus, processedWindows: source.windows.length, pendingWindows: Object.freeze([]), failedWindows: Object.freeze([]),
+            nodeCount: assembled.nodeCount, edgeCount: assembled.edgeCount,
+            embeddingStatus,
+            previousProjectRevision: expectedProjectRevision, nextProjectRevision: apply.next_project_revision,
+        });
+        await journal.recordCommitReceipt(asJson(receipt));
+        await emitProgress({ event: "phase_changed", phase: "committed", processedWindows: completed.size });
+        return receipt;
+    }
+    finally {
+        await journal.close();
+    }
+}
+/** harness 工作流的稳定 adapter：复用唯一 ingestion journal、合并与 CAS commit authority。 */
+export async function ingestHarnessDocument(host, input, capability) {
+    return ingestLosslessDocumentWithMethod(host, input, capability, ingestionMethod("harness-v1"));
+}
+/** operation descriptor 是恢复时的唯一 method authority；不得由 CLI 参数原地升级。 */
+export async function resumeHarnessDocument(host, operationId, capability) {
+    const descriptor = await readStagedDocumentInput(capability.projectRoot, operationId);
+    if (descriptor.method.version !== "harness-v1") {
+        throw new AuthoringBridgeError("E_VALIDATION_FAILED", "该 operation 需要对应 legacy provider capability", {
+            failure: "E_CAPABILITY_UNAVAILABLE", method_version: descriptor.method.version,
+        });
+    }
+    return ingestLosslessDocumentWithMethod(host, descriptor.input, { ...capability, ...(descriptor.sourceOptions === undefined ? {} : { sourceOptions: descriptor.sourceOptions }) }, descriptor.method);
+}