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

package/dist/document-ingestion-journal.js

@@ -0,0 +1,471 @@
+import { createHash, randomUUID } from "node:crypto";
+import { open, readFile, rename, rm, stat } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { assertSafeExistingProjectPath, assertSafeProjectParent, ensureSafeProjectDirectory, safeProjectPath, } from "./safe-project-path.js";
+export class DocumentIngestionJournalError extends Error {
+    code;
+    name = "DocumentIngestionJournalError";
+    constructor(code) {
+        super(`document_ingestion_journal:${code}`);
+        this.code = code;
+    }
+}
+const SHA256 = /^[0-9a-f]{64}$/u;
+const PHASE_ORDER = ["extracting", "ready_to_commit", "committing", "committed"];
+function fail(code) {
+    throw new DocumentIngestionJournalError(code);
+}
+function text(value, maximum = 512) {
+    if (typeof value !== "string" || value.length === 0 || value.length > maximum || value.trim() !== value
+        || value.normalize("NFC") !== value || /[\u0000-\u001f\u007f]/u.test(value))
+        fail("invalid_input");
+    return value;
+}
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function json(value) {
+    let encoded;
+    try {
+        encoded = JSON.stringify(value);
+    }
+    catch {
+        fail("invalid_input");
+    }
+    if (encoded === undefined)
+        fail("invalid_input");
+    return encoded;
+}
+function parseJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        fail("corrupt");
+    }
+}
+async function ensureDirectory(root, relative) {
+    try {
+        return await ensureSafeProjectDirectory(root, relative);
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        return await assertSafeExistingProjectPath(root, join(root, ...relative.split("/")));
+    }
+}
+async function atomicWrite(root, path, bytes) {
+    await assertSafeProjectParent(root, path);
+    const temporary = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
+    const handle = await open(temporary, "wx");
+    try {
+        await handle.writeFile(bytes, "utf8");
+        await handle.sync();
+    }
+    catch (error) {
+        await handle.close();
+        await rm(temporary, { force: true });
+        throw error;
+    }
+    await handle.close();
+    try {
+        await assertSafeProjectParent(root, path);
+        await rename(temporary, path);
+    }
+    catch (error) {
+        await rm(temporary, { force: true });
+        throw error;
+    }
+}
+function identityFrom(options) {
+    const method = options.method === undefined ? undefined : Object.freeze({
+        version: text(options.method.version),
+        sha256: options.method.sha256,
+        promptVersion: text(options.method.promptVersion),
+        schemaVersion: text(options.method.schemaVersion),
+        mergeVersion: text(options.method.mergeVersion),
+        embeddingPolicy: text(options.method.embeddingPolicy),
+        ...(options.method.validatorDiagnosticsVersion === undefined ? {} : { validatorDiagnosticsVersion: text(options.method.validatorDiagnosticsVersion) }),
+        ...(options.method.repairPolicyVersion === undefined ? {} : { repairPolicyVersion: text(options.method.repairPolicyVersion) }),
+    });
+    const identity = Object.freeze({
+        operationId: text(options.operationId),
+        sourceByteSha256: options.sourceByteSha256,
+        planSha256: options.planSha256,
+        modelId: text(options.modelId),
+        expectedProjectRevision: options.expectedProjectRevision,
+        ...(method === undefined ? {} : { method }),
+    });
+    if (!SHA256.test(identity.sourceByteSha256) || !SHA256.test(identity.planSha256)
+        || !Number.isSafeInteger(identity.expectedProjectRevision) || identity.expectedProjectRevision < 0
+        || (method !== undefined && !SHA256.test(method.sha256)))
+        fail("invalid_input");
+    return identity;
+}
+function newManifest(identity) {
+    return {
+        schema_version: 1,
+        identity: {
+            operation_id: identity.operationId,
+            source_byte_sha256: identity.sourceByteSha256,
+            plan_sha256: identity.planSha256,
+            model_id: identity.modelId,
+            expected_project_revision: identity.expectedProjectRevision,
+            ...(identity.method === undefined ? {} : { method: {
+                    version: identity.method.version,
+                    sha256: identity.method.sha256,
+                    prompt_version: identity.method.promptVersion,
+                    schema_version: identity.method.schemaVersion,
+                    merge_version: identity.method.mergeVersion,
+                    embedding_policy: identity.method.embeddingPolicy,
+                    ...(identity.method.validatorDiagnosticsVersion === undefined ? {} : { validator_diagnostics_version: identity.method.validatorDiagnosticsVersion }),
+                    ...(identity.method.repairPolicyVersion === undefined ? {} : { repair_policy_version: identity.method.repairPolicyVersion }),
+                } }),
+        },
+        phase: "extracting",
+        segments: {},
+        failures: {},
+        commit_receipt_json: null,
+        commit_receipt_sha256: null,
+    };
+}
+function validateManifest(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        fail("corrupt");
+    const manifest = value;
+    const identity = manifest.identity;
+    const method = identity?.method;
+    if (manifest.schema_version !== 1 || identity === undefined || typeof identity !== "object"
+        || typeof identity.operation_id !== "string" || !SHA256.test(identity.source_byte_sha256 ?? "")
+        || !SHA256.test(identity.plan_sha256 ?? "") || typeof identity.model_id !== "string"
+        || !Number.isSafeInteger(identity.expected_project_revision) || !PHASE_ORDER.includes(manifest.phase)
+        || (method !== undefined && (typeof method !== "object" || typeof method.version !== "string" || !SHA256.test(method.sha256 ?? "")
+            || typeof method.prompt_version !== "string" || typeof method.schema_version !== "string"
+            || typeof method.merge_version !== "string" || typeof method.embedding_policy !== "string"
+            || (method.validator_diagnostics_version !== undefined && typeof method.validator_diagnostics_version !== "string")
+            || (method.repair_policy_version !== undefined && typeof method.repair_policy_version !== "string")))
+        || typeof manifest.segments !== "object" || manifest.segments === null || Array.isArray(manifest.segments)
+        || typeof manifest.failures !== "object" || manifest.failures === null || Array.isArray(manifest.failures)
+        || !Object.values(manifest.segments).every((entry) => typeof entry === "object" && entry !== null && SHA256.test(entry.payload_sha256))
+        || !Object.values(manifest.failures).every((entry) => typeof entry === "object" && entry !== null
+            && Number.isSafeInteger(entry.attempts) && entry.attempts > 0 && typeof entry.code === "string" && typeof entry.retryable === "boolean")
+        || (manifest.commit_receipt_json !== null && typeof manifest.commit_receipt_json !== "string")
+        || (manifest.commit_receipt_sha256 !== null && !SHA256.test(manifest.commit_receipt_sha256 ?? "")))
+        fail("corrupt");
+    if ((manifest.commit_receipt_json === null) !== (manifest.commit_receipt_sha256 === null)
+        || (manifest.commit_receipt_json !== null && sha256(manifest.commit_receipt_json) !== manifest.commit_receipt_sha256))
+        fail("corrupt");
+    return manifest;
+}
+function assertIdentity(manifest, expected) {
+    const actual = manifest.identity;
+    if (actual.operation_id !== expected.operationId || actual.source_byte_sha256 !== expected.sourceByteSha256
+        || actual.plan_sha256 !== expected.planSha256 || actual.model_id !== expected.modelId
+        || actual.expected_project_revision !== expected.expectedProjectRevision)
+        fail("identity_mismatch");
+    if (expected.method === undefined) {
+        if (actual.method !== undefined)
+            fail("identity_mismatch");
+        return;
+    }
+    if (actual.method === undefined || actual.method.version !== expected.method.version || actual.method.sha256 !== expected.method.sha256
+        || actual.method.prompt_version !== expected.method.promptVersion || actual.method.schema_version !== expected.method.schemaVersion
+        || actual.method.merge_version !== expected.method.mergeVersion || actual.method.embedding_policy !== expected.method.embeddingPolicy
+        || actual.method.validator_diagnostics_version !== expected.method.validatorDiagnosticsVersion
+        || actual.method.repair_policy_version !== expected.method.repairPolicyVersion)
+        fail("identity_mismatch");
+}
+function methodFromManifest(manifest) {
+    const method = manifest.identity.method;
+    return method === undefined ? undefined : Object.freeze({
+        version: method.version,
+        sha256: method.sha256,
+        promptVersion: method.prompt_version,
+        schemaVersion: method.schema_version,
+        mergeVersion: method.merge_version,
+        embeddingPolicy: method.embedding_policy,
+        ...(method.validator_diagnostics_version === undefined ? {} : { validatorDiagnosticsVersion: method.validator_diagnostics_version }),
+        ...(method.repair_policy_version === undefined ? {} : { repairPolicyVersion: method.repair_policy_version }),
+    });
+}
+function pidAlive(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+async function acquireLease(root, relativeDirectory, operationId) {
+    const path = await safeProjectPath(root, `${relativeDirectory}/active.lock`);
+    const token = randomUUID();
+    const body = `${JSON.stringify({ schema_version: 1, token, operation_id: operationId, pid: process.pid })}\n`;
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            const handle = await open(path, "wx");
+            try {
+                await handle.writeFile(body, "utf8");
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            return Object.freeze({ path, token });
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            await assertSafeExistingProjectPath(root, path);
+            let existing;
+            try {
+                existing = JSON.parse(await readFile(path, "utf8"));
+            }
+            catch {
+                fail("corrupt");
+            }
+            if (existing.schema_version !== 1 || typeof existing.token !== "string" || existing.operation_id !== operationId
+                || !Number.isSafeInteger(existing.pid))
+                fail("corrupt");
+            if (pidAlive(existing.pid))
+                fail("busy");
+            const before = await stat(path);
+            const recoveredPath = await safeProjectPath(root, `${relativeDirectory}/recovered-lock-${existing.token}.json`);
+            const after = await stat(path);
+            if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs)
+                fail("lease_uncertain");
+            await assertSafeProjectParent(root, path);
+            await rename(path, recoveredPath);
+        }
+    }
+    fail("busy");
+}
+async function releaseLease(root, lease) {
+    await assertSafeExistingProjectPath(root, lease.path);
+    let value;
+    try {
+        value = JSON.parse(await readFile(lease.path, "utf8"));
+    }
+    catch {
+        fail("lease_uncertain");
+    }
+    if (value.token !== lease.token)
+        fail("lease_uncertain");
+    await rm(lease.path);
+}
+/** 只读 operational 状态；不获取 writer lease，也不修复或改写 manifest。 */
+export async function readDocumentIngestionJournalStatus(projectRoot, operationId) {
+    const canonicalId = text(operationId);
+    const path = await safeProjectPath(projectRoot, `.worldengine/staging/document-ingestion/${sha256(canonicalId)}/manifest.json`);
+    await assertSafeExistingProjectPath(projectRoot, path);
+    const manifest = validateManifest(JSON.parse(await readFile(path, "utf8")));
+    if (manifest.identity.operation_id !== canonicalId)
+        fail("identity_mismatch");
+    const method = methodFromManifest(manifest);
+    return Object.freeze({
+        operationId: canonicalId, sourceByteSha256: manifest.identity.source_byte_sha256,
+        planSha256: manifest.identity.plan_sha256, modelId: manifest.identity.model_id,
+        expectedProjectRevision: manifest.identity.expected_project_revision, phase: manifest.phase,
+        ...(method === undefined ? {} : { method }),
+        completedSegmentIds: Object.freeze(Object.keys(manifest.segments).sort()),
+        failedSegments: Object.freeze(Object.entries(manifest.failures).sort(([left], [right]) => left.localeCompare(right))
+            .map(([id, failure]) => Object.freeze({ id, ...failure }))),
+        commitReceipt: manifest.commit_receipt_json === null ? null : parseJson(manifest.commit_receipt_json),
+    });
+}
+export async function openDocumentIngestionJournal(options) {
+    const identity = identityFrom(options);
+    const operationKey = sha256(identity.operationId);
+    const relativeDirectory = `.worldengine/staging/document-ingestion/${operationKey}`;
+    await ensureDirectory(options.projectRoot, relativeDirectory);
+    await ensureDirectory(options.projectRoot, `${relativeDirectory}/segments`);
+    const lease = await acquireLease(options.projectRoot, relativeDirectory, identity.operationId);
+    const manifestPath = await safeProjectPath(options.projectRoot, `${relativeDirectory}/manifest.json`);
+    let manifest;
+    try {
+        try {
+            await assertSafeExistingProjectPath(options.projectRoot, manifestPath);
+            manifest = validateManifest(JSON.parse(await readFile(manifestPath, "utf8")));
+            assertIdentity(manifest, identity);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            manifest = newManifest(identity);
+            await atomicWrite(options.projectRoot, manifestPath, `${JSON.stringify(manifest)}\n`);
+        }
+    }
+    catch (error) {
+        await releaseLease(options.projectRoot, lease);
+        throw error;
+    }
+    let closed = false;
+    let closing = false;
+    let closePromise;
+    let queue = Promise.resolve();
+    const requireOpen = () => { if (closed || closing)
+        fail("invalid_transition"); };
+    const persist = async () => atomicWrite(options.projectRoot, manifestPath, `${JSON.stringify(manifest)}\n`);
+    const exclusive = async (action) => {
+        requireOpen();
+        const previous = queue;
+        let release;
+        queue = new Promise((resolve) => { release = resolve; });
+        await previous;
+        try {
+            return await action();
+        }
+        finally {
+            release();
+        }
+    };
+    const segmentPath = async (id) => safeProjectPath(options.projectRoot, `${relativeDirectory}/segments/${sha256(text(id))}.json`);
+    return Object.freeze({
+        async getStatus() {
+            return exclusive(async () => Object.freeze({
+                ...identity,
+                phase: manifest.phase,
+                completedSegmentIds: Object.freeze(Object.keys(manifest.segments).sort()),
+                failedSegments: Object.freeze(Object.entries(manifest.failures).sort(([left], [right]) => left.localeCompare(right))
+                    .map(([id, failure]) => Object.freeze({ id, ...failure }))),
+                commitReceipt: manifest.commit_receipt_json === null ? null : parseJson(manifest.commit_receipt_json),
+            }));
+        },
+        async readSegment(id) {
+            return exclusive(async () => {
+                const canonicalId = text(id);
+                const path = await segmentPath(canonicalId);
+                try {
+                    await assertSafeExistingProjectPath(options.projectRoot, path);
+                }
+                catch (error) {
+                    if (error.code === "ENOENT")
+                        return null;
+                    throw error;
+                }
+                let envelope;
+                try {
+                    envelope = JSON.parse(await readFile(path, "utf8"));
+                }
+                catch {
+                    fail("corrupt");
+                }
+                if (envelope.schema_version !== 1 || envelope.id !== canonicalId || typeof envelope.payload_json !== "string"
+                    || typeof envelope.payload_sha256 !== "string" || sha256(envelope.payload_json) !== envelope.payload_sha256)
+                    fail("corrupt");
+                const listed = manifest.segments[canonicalId];
+                if (listed !== undefined && listed.payload_sha256 !== envelope.payload_sha256)
+                    fail("corrupt");
+                if (listed === undefined) {
+                    manifest.segments[canonicalId] = { payload_sha256: envelope.payload_sha256 };
+                    delete manifest.failures[canonicalId];
+                    await persist();
+                }
+                return parseJson(envelope.payload_json);
+            });
+        },
+        async writeSegment(id, payload) {
+            return exclusive(async () => {
+                if (manifest.phase !== "extracting")
+                    fail("invalid_transition");
+                const canonicalId = text(id);
+                const payloadJson = json(payload);
+                const payloadSha256 = sha256(payloadJson);
+                const path = await segmentPath(canonicalId);
+                try {
+                    await assertSafeExistingProjectPath(options.projectRoot, path);
+                    let existing;
+                    try {
+                        existing = JSON.parse(await readFile(path, "utf8"));
+                    }
+                    catch {
+                        fail("corrupt");
+                    }
+                    if (existing.schema_version !== 1 || existing.id !== canonicalId || typeof existing.payload_json !== "string"
+                        || typeof existing.payload_sha256 !== "string" || sha256(existing.payload_json) !== existing.payload_sha256)
+                        fail("corrupt");
+                    if (existing.payload_sha256 !== payloadSha256)
+                        fail("identity_mismatch");
+                }
+                catch (error) {
+                    if (error.code !== "ENOENT")
+                        throw error;
+                    await atomicWrite(options.projectRoot, path, `${JSON.stringify({ schema_version: 1, id: canonicalId, payload_json: payloadJson, payload_sha256: payloadSha256 })}\n`);
+                }
+                manifest.segments[canonicalId] = { payload_sha256: payloadSha256 };
+                delete manifest.failures[canonicalId];
+                await persist();
+                return Object.freeze({ payloadSha256 });
+            });
+        },
+        async clearSegmentFailure(id) {
+            await exclusive(async () => {
+                if (manifest.phase !== "extracting")
+                    fail("invalid_transition");
+                const canonicalId = text(id);
+                delete manifest.failures[canonicalId];
+                await persist();
+            });
+        },
+        async recordSegmentFailure(id, failure) {
+            await exclusive(async () => {
+                if (manifest.phase !== "extracting")
+                    fail("invalid_transition");
+                const canonicalId = text(id);
+                const code = text(failure.code, 128);
+                const previousAttempts = manifest.failures[canonicalId]?.attempts ?? 0;
+                const attempts = failure.attempts ?? previousAttempts + 1;
+                if (!Number.isSafeInteger(attempts) || attempts < previousAttempts || attempts < 1)
+                    fail("invalid_input");
+                manifest.failures[canonicalId] = { attempts, code, retryable: failure.retryable === true };
+                await persist();
+            });
+        },
+        async markPhase(phase) {
+            await exclusive(async () => {
+                const current = PHASE_ORDER.indexOf(manifest.phase);
+                const next = PHASE_ORDER.indexOf(phase);
+                if (next < current || next > current + 1)
+                    fail("invalid_transition");
+                if (phase === "ready_to_commit" && Object.keys(manifest.failures).length > 0)
+                    fail("invalid_transition");
+                manifest.phase = phase;
+                await persist();
+            });
+        },
+        async recordCommitReceipt(receipt) {
+            await exclusive(async () => {
+                if (manifest.phase !== "committing")
+                    fail("invalid_transition");
+                const receiptJson = json(receipt);
+                manifest.commit_receipt_json = receiptJson;
+                manifest.commit_receipt_sha256 = sha256(receiptJson);
+                manifest.phase = "committed";
+                await persist();
+            });
+        },
+        async close() {
+            if (closed)
+                return;
+            if (closePromise !== undefined)
+                return closePromise;
+            closing = true;
+            closePromise = (async () => {
+                await queue;
+                await releaseLease(options.projectRoot, lease);
+                closed = true;
+                closing = false;
+            })();
+            try {
+                await closePromise;
+            }
+            catch (error) {
+                closing = false;
+                closePromise = undefined;
+                throw error;
+            }
+        },
+    });
+}

package/dist/document-ingestion.d.ts

@@ -0,0 +1,183 @@
+import { type AuthoringToolCall } from "@world-engines/authoring-bridge";
+import type { AuthoringModelConnection } from "./authoring-model-connection.js";
+import { extractDocumentGraphWindow, type GraphSegment, type GraphSegmentationIssue, type KnownGraphEntity } from "./document-graph-extractor.js";
+import { openDocumentIngestionJournal, type DocumentIngestionJournalStatus } from "./document-ingestion-journal.js";
+import { type DocumentSource, type DocumentSourceOptions } from "./document-source.js";
+import { createCachedEmbeddingPort } from "./embedding-cache.js";
+type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export interface LosslessDocumentIngestionHost {
+    inspect(): Promise<Readonly<{
+        project_revision: number;
+    }>>;
+    dispatchTool(call: AuthoringToolCall): Promise<unknown>;
+}
+export type LosslessDocumentInput = Readonly<{
+    bytes: Uint8Array;
+    scopeId: string;
+    sourceId: string;
+    sourceRevision: string;
+    sourcePath?: string;
+    sourceStoragePath?: string;
+}>;
+export type StagedDocumentInputDescriptor = Readonly<{
+    schemaVersion: 1 | 2;
+    operationId: string;
+    input: LosslessDocumentInput;
+    sourceOptions?: DocumentSourceOptions;
+    planSha256: string;
+    method: DocumentIngestionMethodIdentity;
+}>;
+export type DocumentIngestionMethodVersion = "legacy-v1" | "deferred-v2" | "adaptive-repair-v3" | "semantic-negation-v4" | "harness-v1";
+export type DocumentIngestionMethodIdentity = Readonly<{
+    version: DocumentIngestionMethodVersion;
+    sha256: string;
+    promptVersion: string;
+    schemaVersion: string;
+    mergeVersion: string;
+    embeddingPolicy: "immediate" | "deferred_review";
+    validatorDiagnosticsVersion?: string;
+    repairPolicyVersion?: string;
+}>;
+export type DocumentEmbeddingStatus = Readonly<{
+    status: "pending" | "complete";
+    providerId: string;
+    modelId: string;
+    dimensions: number;
+    hits: number;
+    misses: number;
+    remoteTexts: number;
+    writes: number;
+}>;
+export type LosslessDocumentIngestionReceipt = Readonly<{
+    schemaVersion: 1;
+    operationId: string;
+    documentId?: string;
+    status: "staged" | "committed" | "already_committed";
+    rawByteSha256: string;
+    rawByteLength: number;
+    sourcePath?: string;
+    sourceStoragePath?: string;
+    roundtripVerified: boolean;
+    sourceCoverage: Readonly<{
+        status: "complete";
+        utf16Length: number;
+        unitCount: number;
+        coveredUnitCount: number;
+    }>;
+    graphStatus: "pending" | "partial" | "complete";
+    processedWindows: number;
+    pendingWindows: readonly string[];
+    failedWindows: readonly Readonly<{
+        id: string;
+        code: string;
+        retryable: boolean;
+        attempts: number;
+    }>[];
+    nodeCount: number;
+    edgeCount: number;
+    embeddingStatus: DocumentEmbeddingStatus;
+    previousProjectRevision?: number;
+    nextProjectRevision?: number;
+}>;
+export type DocumentGraphEmbeddingText = Readonly<{
+    id: string;
+    kind: "chunk" | "entity" | "statement" | "edge_assertion";
+    text: string;
+}>;
+/** 提审 consumer 的只读输入；这里只冻结文本与 identity，不执行 embedding 或写图。 */
+export type DocumentGraphEmbeddingPreparation = Readonly<{
+    schemaVersion: 1;
+    operationId: string;
+    method: DocumentIngestionMethodIdentity;
+    sourceIdentity: Readonly<{
+        scopeId: string;
+        sourceId: string;
+        sourceRevision: string;
+        sourceSha256: string;
+    }>;
+    planSha256: string;
+    graphSha256: string;
+    graphStatus: "complete";
+    texts: readonly DocumentGraphEmbeddingText[];
+}>;
+type Dependencies = Readonly<{
+    extractWindow: (input: Parameters<typeof extractDocumentGraphWindow>[0] & Readonly<{
+        ingestionMethod: DocumentIngestionMethodIdentity;
+        adaptiveRepair?: AdaptiveRepairPreviousAttempt;
+    }>) => ReturnType<typeof extractDocumentGraphWindow>;
+    openJournal: typeof openDocumentIngestionJournal;
+    createEmbeddingCache: typeof createCachedEmbeddingPort;
+}>;
+export type AdaptiveRepairPreviousAttempt = Readonly<{
+    attempt: number;
+    diagnosticFingerprint: string;
+    repeatedDiagnosticFingerprint: boolean;
+    reasons: readonly string[];
+    validLocalNodeIds: readonly string[];
+    allowedEvidenceUnitIds: readonly string[];
+    segmentationIssues?: readonly GraphSegmentationIssue[];
+}>;
+/** 仅发布已持久化进度；不含正文、路径、凭据或 provider 原始响应。 */
+export type LosslessDocumentIngestionProgress = Readonly<{
+    schemaVersion: 1;
+    operationId: string;
+    event: "source_staged" | "window_completed" | "window_failed" | "phase_changed";
+    phase: DocumentIngestionJournalStatus["phase"];
+    totalWindows: number;
+    processedWindows: number;
+    windowId?: string;
+    failure?: Readonly<{
+        code: string;
+        retryable: boolean;
+    }>;
+}>;
+export type LosslessDocumentIngestionStatus = DocumentIngestionJournalStatus & Readonly<{
+    sourcePath?: string;
+    sourceStoragePath?: string;
+}>;
+export type LosslessDocumentIngestionCapability = Readonly<{
+    projectRoot: string;
+    modelConnection: AuthoringModelConnection;
+    embeddingOrigin?: string;
+    signal?: AbortSignal;
+    concurrency?: number;
+    sourceOptions?: DocumentSourceOptions;
+    /** 仅用于显式创建 legacy operation；恢复时 descriptor 是唯一方法 authority。 */
+    methodVersion?: DocumentIngestionMethodVersion;
+    /** 等待 consumer 完成投递；consumer 失败会在安全 checkpoint 边界终止本次调用。 */
+    onProgress?: (progress: LosslessDocumentIngestionProgress) => void | Promise<void>;
+    /** 仅供模块测试替换真实外部端口；产品调用必须省略。 */
+    dependencies?: Partial<Dependencies>;
+}>;
+export declare const DOCUMENT_INGESTION_CHECKPOINT_IDS: Readonly<{
+    sourceDescriptorId: "__document_source_descriptor__";
+    partialAttemptPrefix: "__document_partial_attempt__:";
+    retryCompletePrefix: "__document_retry_complete__:";
+    harnessAcceptancePrefix: "__document_harness_acceptance__:";
+    maxPartialAttempts: 3;
+}>;
+export declare function readDocumentIngestionCheckpoint(projectRoot: string, operationId: string, segmentId: string): Promise<JsonValue>;
+/** descriptor 是输入元数据，不能算作一个已完成的模型窗口。 */
+export declare function readLosslessDocumentStatus(projectRoot: string, operationId: string): Promise<LosslessDocumentIngestionStatus>;
+export declare function resumeLosslessDocument(host: LosslessDocumentIngestionHost, operationId: string, capability: LosslessDocumentIngestionCapability): Promise<LosslessDocumentIngestionReceipt>;
+/** 上传流或原文件已释放时，以 operationId 只读恢复 journal 中已校验的不可变原始输入。 */
+export declare function readStagedDocumentInput(projectRoot: string, operationId: string): Promise<StagedDocumentInputDescriptor>;
+export declare function graphSegment(value: JsonValue, windowId: string): GraphSegment;
+export declare function knownDocumentGraphEntities(source: DocumentSource, segments: readonly GraphSegment[]): readonly KnownGraphEntity[];
+export declare function prepareDocumentGraphEmbedding(projectRoot: string, operationId: string): Promise<DocumentGraphEmbeddingPreparation>;
+/**
+ * 全文导入的唯一编排入口。模型与 embedding 结果先进入 journal/cache；只有所有窗口
+ * 都有已校验 checkpoint 时，才以最初捕获的 revision 做一次原子 world_apply。
+ */
+export declare function ingestLosslessDocument(host: LosslessDocumentIngestionHost, input: LosslessDocumentInput, capability: LosslessDocumentIngestionCapability): Promise<LosslessDocumentIngestionReceipt>;
+/** harness 工作流的稳定 adapter：复用唯一 ingestion journal、合并与 CAS commit authority。 */
+export declare function ingestHarnessDocument(host: LosslessDocumentIngestionHost, input: LosslessDocumentInput, capability: Omit<LosslessDocumentIngestionCapability, "methodVersion" | "modelConnection"> & Readonly<{
+    modelConnection: AuthoringModelConnection;
+}>): Promise<LosslessDocumentIngestionReceipt>;
+/** operation descriptor 是恢复时的唯一 method authority；不得由 CLI 参数原地升级。 */
+export declare function resumeHarnessDocument(host: LosslessDocumentIngestionHost, operationId: string, capability: Omit<LosslessDocumentIngestionCapability, "methodVersion" | "modelConnection"> & Readonly<{
+    modelConnection: AuthoringModelConnection;
+}>): Promise<LosslessDocumentIngestionReceipt>;
+export {};