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

package/dist/harness-callback-transport.d.ts

@@ -0,0 +1,17 @@
+import type { DesktopAuthoringCapabilities } from "./desktop-authoring-runtime.js";
+export interface HarnessCallbackEnvironment {
+    readonly WORLDENGINE_HARNESS_CALLBACK_PIPE?: string;
+    readonly WORLDENGINE_HARNESS_CALLBACK_CHALLENGE_ID?: string;
+    readonly WORLDENGINE_HARNESS_CALLBACK_CHALLENGE?: string;
+    readonly WORLDENGINE_HARNESS_CALLBACK_EXPIRES_AT_MS?: string;
+}
+export interface HarnessCallbackTransportDependencies {
+    readonly now?: () => number;
+    readonly currentWindowsSid?: () => Promise<string>;
+    readonly request?: (pipeName: string, payload: string) => Promise<unknown>;
+}
+/**
+ * Desktop 启动器可注入短期、project-bound named-pipe capability。没有 broker 时返回空能力，
+ * ProjectHost/MCP 会把三个 callback 标记为 unavailable，绝不伪造 GUI 或用户回答。
+ */
+export declare function createHarnessCallbackCapabilities(projectId: string, environment?: HarnessCallbackEnvironment, dependencies?: HarnessCallbackTransportDependencies): Promise<DesktopAuthoringCapabilities>;

package/dist/harness-callback-transport.js

@@ -0,0 +1,128 @@
+import { execFile } from "node:child_process";
+import { createConnection } from "node:net";
+import { promisify } from "node:util";
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+const execFileAsync = promisify(execFile);
+const CALLBACK_PIPE_PATTERN = /^\\\\\.\\pipe\\worldengine-harness-callback-[a-f0-9]{64}$/i;
+const CALLBACK_RESPONSE_LIMIT = 4 * 1024 * 1024;
+const CALLBACK_TIMEOUT_MS = 5 * 60_000;
+function unavailable(toolName, reason) {
+    throw new AuthoringBridgeError("E_VALIDATION_FAILED", `E_CAPABILITY_UNAVAILABLE: ${toolName} ${reason}`, {
+        failure: "E_CAPABILITY_UNAVAILABLE",
+        tool_name: toolName,
+    });
+}
+function capabilityFromEnvironment(environment, now) {
+    const values = [
+        environment.WORLDENGINE_HARNESS_CALLBACK_PIPE,
+        environment.WORLDENGINE_HARNESS_CALLBACK_CHALLENGE_ID,
+        environment.WORLDENGINE_HARNESS_CALLBACK_CHALLENGE,
+        environment.WORLDENGINE_HARNESS_CALLBACK_EXPIRES_AT_MS,
+    ];
+    if (values.every((value) => value === undefined))
+        return undefined;
+    const [pipeName, challengeId, challenge, expires] = values;
+    const expiresAtMs = Number(expires);
+    if (pipeName === undefined || !CALLBACK_PIPE_PATTERN.test(pipeName)
+        || challengeId === undefined || !/^[0-9a-f-]{36}$/i.test(challengeId)
+        || challenge === undefined || challenge.length < 32 || challenge.length > 256
+        || !Number.isSafeInteger(expiresAtMs) || expiresAtMs <= now) {
+        throw new AuthoringBridgeError("E_AUTH_REQUIRED", "Harness callback capability 无效或已过期");
+    }
+    return { pipeName, challengeId, challenge, expiresAtMs };
+}
+async function currentWindowsSid() {
+    if (process.platform !== "win32")
+        throw new AuthoringBridgeError("E_AUTH_REQUIRED", "Harness callback broker 仅支持 Windows");
+    const { stdout } = await execFileAsync("whoami", ["/user", "/fo", "csv", "/nh"], { windowsHide: true });
+    const sid = stdout.split(",").map((value) => value.trim().replace(/^"|"$/g, ""))
+        .find((value) => /^S-1-[0-9-]+$/i.test(value));
+    if (sid === undefined)
+        throw new AuthoringBridgeError("E_AUTH_REQUIRED", "Harness callback Windows identity 不可用");
+    return sid;
+}
+async function pipeRequest(pipeName, payload) {
+    return new Promise((resolvePromise, rejectPromise) => {
+        const socket = createConnection(pipeName);
+        const chunks = [];
+        let total = 0;
+        const fail = () => {
+            socket.destroy();
+            rejectPromise(new AuthoringBridgeError("E_VALIDATION_FAILED", "Harness callback broker 不可用", {
+                failure: "E_CAPABILITY_UNAVAILABLE",
+            }));
+        };
+        socket.setTimeout(CALLBACK_TIMEOUT_MS, fail);
+        socket.once("connect", () => socket.write(`${payload}\n`));
+        socket.on("data", (chunk) => {
+            total += chunk.byteLength;
+            if (!Number.isSafeInteger(total) || total > CALLBACK_RESPONSE_LIMIT)
+                fail();
+            else
+                chunks.push(chunk);
+        });
+        socket.once("error", fail);
+        socket.once("end", () => {
+            try {
+                resolvePromise(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+            }
+            catch {
+                fail();
+            }
+        });
+    });
+}
+function callbackResult(toolName, response) {
+    if (typeof response !== "object" || response === null || Array.isArray(response))
+        unavailable(toolName, "响应无效");
+    const record = response;
+    if (record.ok === true && Object.hasOwn(record, "result"))
+        return record.result;
+    if (record.ok === false && record.error === "E_PREVIEW_NOT_RUNNING") {
+        throw new AuthoringBridgeError("E_PREVIEW_NOT_RUNNING", "Preview 尚未运行");
+    }
+    unavailable(toolName, "被 UI broker 拒绝");
+}
+/**
+ * Desktop 启动器可注入短期、project-bound named-pipe capability。没有 broker 时返回空能力，
+ * ProjectHost/MCP 会把三个 callback 标记为 unavailable，绝不伪造 GUI 或用户回答。
+ */
+export async function createHarnessCallbackCapabilities(projectId, environment = process.env, dependencies = {}) {
+    if (!/^[A-Za-z0-9_-]{1,256}$/.test(projectId))
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "project_id 无效");
+    const now = dependencies.now ?? Date.now;
+    const capability = capabilityFromEnvironment(environment, now());
+    if (capability === undefined)
+        return Object.freeze({});
+    const windowsSid = await (dependencies.currentWindowsSid ?? currentWindowsSid)();
+    const request = dependencies.request ?? pipeRequest;
+    const call = async (toolName, input) => {
+        if (capability.expiresAtMs <= now())
+            unavailable(toolName, "capability 已过期");
+        const payload = JSON.stringify({
+            namespace: "worldengine.harness_callbacks.v1",
+            project_id: projectId,
+            windows_sid: windowsSid,
+            challenge_id: capability.challengeId,
+            challenge: capability.challenge,
+            tool_name: toolName,
+            input,
+        });
+        if (Buffer.byteLength(payload, "utf8") > CALLBACK_RESPONSE_LIMIT) {
+            throw new AuthoringBridgeError("E_SCHEMA_INVALID", "Harness callback 请求过大");
+        }
+        try {
+            return callbackResult(toolName, await request(capability.pipeName, payload));
+        }
+        catch (error) {
+            if (error instanceof AuthoringBridgeError)
+                throw error;
+            unavailable(toolName, "transport 不可用");
+        }
+    };
+    return Object.freeze({
+        ask_user: (input) => call("ask_user", input),
+        preview_inspect: (input) => call("preview_inspect", input),
+        preview_interact: (input) => call("preview_interact", input),
+    });
+}

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

@@ -0,0 +1,77 @@
+import { type PreparedDocumentGraphWindowRequest } from "./document-graph-extractor.js";
+import { type LosslessDocumentIngestionHost, type LosslessDocumentIngestionReceipt, type LosslessDocumentInput } from "./document-ingestion.js";
+import { type DocumentSourceOptions } from "./document-source.js";
+export type HarnessDocumentIngestionRequest = Readonly<{
+    schemaVersion: 1;
+    operationId: string;
+    requestId: string;
+    windowId: string;
+    attempt: number;
+    maximumAttempts: number;
+    rawByteSha256: string;
+    planSha256: string;
+    methodSha256: string;
+    evidenceUnits: readonly Readonly<{
+        id: string;
+        kind: string;
+        text: string;
+        core: boolean;
+        startOffset: number;
+        endOffset: number;
+    }>[];
+    structuredRequest: PreparedDocumentGraphWindowRequest;
+}>;
+export type HarnessDocumentIngestionNext = Readonly<{
+    schemaVersion: 1;
+    state: "request";
+    processedWindows: number;
+    totalWindows: number;
+    sourcePath?: string;
+    sourceStoragePath?: string;
+    request: HarnessDocumentIngestionRequest;
+}> | Readonly<{
+    schemaVersion: 1;
+    state: "ready_to_commit" | "committed";
+    processedWindows: number;
+    totalWindows: number;
+    sourcePath?: string;
+    sourceStoragePath?: string;
+}> | Readonly<{
+    schemaVersion: 1;
+    state: "repair_exhausted";
+    processedWindows: number;
+    totalWindows: number;
+    sourcePath?: string;
+    sourceStoragePath?: string;
+    windowId: string;
+    attempts: number;
+    reasons: readonly string[];
+}>;
+export type HarnessDocumentIngestionAcceptance = Readonly<{
+    schemaVersion: 1;
+    operationId: string;
+    requestId: string;
+    windowId: string;
+    attempt: number;
+    accepted: boolean;
+    graphStatus: "complete" | "partial";
+    next: HarnessDocumentIngestionNext;
+}>;
+/** 只保存用户选定的最终成书原文字节；不接收或记录 harness 对话。 */
+export declare function prepareHarnessDocumentIngestion(host: LosslessDocumentIngestionHost, input: LosslessDocumentInput, options: Readonly<{
+    projectRoot: string;
+    sourceOptions?: DocumentSourceOptions;
+}>): Promise<Readonly<{
+    receipt: LosslessDocumentIngestionReceipt;
+    next: HarnessDocumentIngestionNext;
+}>>;
+/** 跨 CLI/MCP 调用可重复计算的下一请求；函数只读，不持久化 prompt 或聊天日志。 */
+export declare function nextHarnessDocumentIngestion(projectRoot: string, operationId: string): Promise<HarnessDocumentIngestionNext>;
+/** requestId 是对 source/method/checkpoint/prompt 的 CAS；只把校验后的 GraphSegment 写入 journal。 */
+export declare function acceptHarnessDocumentIngestion(projectRoot: string, operationId: string, requestId: string, candidate: unknown, 
+/** 仅用于模块测试模拟 ledger 与 checkpoint 之间的进程中断；产品调用必须省略。 */
+dependencies?: Readonly<{
+    afterAcceptanceLedgerPersist?(): void | Promise<void>;
+}>): Promise<HarnessDocumentIngestionAcceptance>;
+/** 所有窗口 complete 后复用 losslessDocument 的唯一 assemble + world_apply CAS commit。 */
+export declare function commitHarnessDocumentIngestion(host: LosslessDocumentIngestionHost, projectRoot: string, operationId: string): Promise<LosslessDocumentIngestionReceipt>;

package/dist/harness-document-ingestion.js

@@ -0,0 +1,343 @@
+import { createHash } from "node:crypto";
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+import { prepareDocumentGraphWindowRequest, validateDocumentGraphWindowCandidate, } from "./document-graph-extractor.js";
+import { DOCUMENT_INGESTION_CHECKPOINT_IDS, graphSegment, ingestHarnessDocument, knownDocumentGraphEntities, readDocumentIngestionCheckpoint, readStagedDocumentInput, resumeHarnessDocument, } from "./document-ingestion.js";
+import { openDocumentIngestionJournal, readDocumentIngestionJournalStatus } from "./document-ingestion-journal.js";
+import { buildDocumentSource } from "./document-source.js";
+const HARNESS_MODEL_ID = "external-project-harness-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 asJson(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function fail(code, message, failure, details = {}) {
+    throw new AuthoringBridgeError(code, message, Object.freeze({ failure, ...details }));
+}
+function normalizedCandidate(value) {
+    let encoded;
+    try {
+        encoded = JSON.stringify(value);
+    }
+    catch {
+        fail("E_SCHEMA_INVALID", "harness response 不是可序列化 JSON", "HARNESS_RESPONSE_SCHEMA_INVALID");
+    }
+    if (encoded === undefined || encoded.length > 16 * 1024 * 1024) {
+        fail("E_SCHEMA_INVALID", "harness response 不是有效 JSON 或超过大小上限", "HARNESS_RESPONSE_SCHEMA_INVALID");
+    }
+    const parsed = JSON.parse(encoded);
+    return Object.freeze({ value: parsed, sha256: sha256(stableJson(parsed)) });
+}
+function acceptanceCheckpointId(requestId) {
+    return `${DOCUMENT_INGESTION_CHECKPOINT_IDS.harnessAcceptancePrefix}${sha256(requestId)}`;
+}
+function parseAcceptanceLedger(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        fail("E_OPERATION_ID_CONFLICT", "harness acceptance ledger 已损坏", "HARNESS_ACCEPTANCE_LEDGER_CORRUPT");
+    }
+    const input = value;
+    if (input.schema_version !== 1 || typeof input.operation_id !== "string" || typeof input.request_id !== "string"
+        || typeof input.candidate_sha256 !== "string" || !/^[0-9a-f]{64}$/u.test(input.candidate_sha256)
+        || typeof input.segment_sha256 !== "string" || !/^[0-9a-f]{64}$/u.test(input.segment_sha256)
+        || typeof input.window_id !== "string" || !Number.isSafeInteger(input.attempt) || input.attempt < 1
+        || typeof input.accepted !== "boolean" || (input.graph_status !== "complete" && input.graph_status !== "partial")
+        || typeof input.checkpoint_id !== "string" || input.accepted !== (input.graph_status === "complete")) {
+        fail("E_OPERATION_ID_CONFLICT", "harness acceptance ledger 已损坏", "HARNESS_ACCEPTANCE_LEDGER_CORRUPT");
+    }
+    return Object.freeze({ schemaVersion: 1, operationId: input.operation_id, requestId: input.request_id,
+        candidateSha256: input.candidate_sha256, segmentSha256: input.segment_sha256, windowId: input.window_id,
+        attempt: input.attempt, accepted: input.accepted, graphStatus: input.graph_status,
+        checkpointId: input.checkpoint_id });
+}
+async function readAcceptanceLedger(projectRoot, operationId, requestId) {
+    try {
+        const ledger = parseAcceptanceLedger(await readDocumentIngestionCheckpoint(projectRoot, operationId, acceptanceCheckpointId(requestId)));
+        if (ledger.operationId !== operationId || ledger.requestId !== requestId) {
+            fail("E_OPERATION_ID_CONFLICT", "harness acceptance ledger identity 不匹配", "HARNESS_ACCEPTANCE_LEDGER_CONFLICT");
+        }
+        return ledger;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function unavailableModelCall() {
+    return Promise.reject(new AuthoringBridgeError("E_VALIDATION_FAILED", "harness workflow 没有也不会调用 provider model port", {
+        failure: "E_CAPABILITY_UNAVAILABLE",
+    }));
+}
+function unavailableModelConnection() {
+    return Object.freeze({
+        embedding: Object.freeze({ providerId: "none", modelId: HARNESS_MODEL_ID, dimensions: 0,
+            embed: unavailableModelCall }),
+        structuredJson: Object.freeze({ providerId: "project-harness", modelId: HARNESS_MODEL_ID,
+            generate: unavailableModelCall }),
+        usage: () => Object.freeze({ inputTokens: 0, outputTokens: 0, totalTokens: 0, requests: 0 }),
+    });
+}
+async function loadState(projectRoot, operationId) {
+    const descriptor = await readStagedDocumentInput(projectRoot, operationId);
+    if (descriptor.method.version !== "harness-v1") {
+        fail("E_VALIDATION_FAILED", "该 operation 不是 harness ingestion；需要对应 legacy provider capability", "E_CAPABILITY_UNAVAILABLE", { method_version: descriptor.method.version });
+    }
+    const status = await readDocumentIngestionJournalStatus(projectRoot, operationId);
+    if (status.modelId !== HARNESS_MODEL_ID || status.sourceByteSha256 !== sha256(descriptor.input.bytes)
+        || status.planSha256 !== descriptor.planSha256 || status.method?.sha256 !== descriptor.method.sha256) {
+        fail("E_OPERATION_ID_CONFLICT", "harness operation descriptor 与 journal identity 不匹配", "HARNESS_OPERATION_IDENTITY_CONFLICT");
+    }
+    const source = buildDocumentSource({ bytes: descriptor.input.bytes, sourceId: descriptor.input.sourceId,
+        sourceRevision: descriptor.input.sourceRevision, scopeId: descriptor.input.scopeId,
+        ...(descriptor.sourceOptions === undefined ? {} : { options: descriptor.sourceOptions }) });
+    const completed = new Map();
+    for (const window of source.windows) {
+        const retryId = `${DOCUMENT_INGESTION_CHECKPOINT_IDS.retryCompletePrefix}${window.id}`;
+        const checkpointId = status.completedSegmentIds.includes(retryId) ? retryId
+            : status.completedSegmentIds.includes(window.id) ? window.id : undefined;
+        if (checkpointId === undefined)
+            continue;
+        const segment = graphSegment(await readDocumentIngestionCheckpoint(projectRoot, operationId, checkpointId), window.id);
+        if (segment.status === "complete")
+            completed.set(window.id, segment);
+    }
+    return Object.freeze({ source, descriptor, status, completed });
+}
+function partialIds(status, windowId) {
+    const prefix = `${DOCUMENT_INGESTION_CHECKPOINT_IDS.partialAttemptPrefix}${windowId}:`;
+    return Object.freeze(status.completedSegmentIds.filter((id) => id.startsWith(prefix))
+        .sort((left, right) => Number(left.slice(prefix.length)) - Number(right.slice(prefix.length))));
+}
+function diagnosticFingerprint(methodSha256, segment) {
+    return sha256(stableJson({ methodSha256, windowId: segment.windowId,
+        reasons: Object.keys(segment.diagnostics.rejectionReasons).sort(),
+        segmentationIssues: segment.diagnostics.segmentationIssues ?? [] }));
+}
+async function previousAttempt(projectRoot, state, window, ids) {
+    const latestId = ids.at(-1);
+    if (latestId === undefined)
+        return undefined;
+    const latest = graphSegment(await readDocumentIngestionCheckpoint(projectRoot, state.descriptor.operationId, latestId), window.id);
+    const previousId = ids.at(-2);
+    const previous = previousId === undefined ? undefined
+        : graphSegment(await readDocumentIngestionCheckpoint(projectRoot, state.descriptor.operationId, previousId), window.id);
+    const fingerprint = diagnosticFingerprint(state.descriptor.method.sha256, latest);
+    return Object.freeze({
+        attempt: ids.length,
+        diagnosticFingerprint: fingerprint,
+        repeatedDiagnosticFingerprint: previous !== undefined
+            && diagnosticFingerprint(state.descriptor.method.sha256, previous) === fingerprint,
+        reasons: Object.freeze(Object.keys(latest.diagnostics.rejectionReasons).sort()),
+        validLocalNodeIds: Object.freeze(latest.nodes.map((node) => node.localId).sort()),
+        allowedEvidenceUnitIds: Object.freeze([...window.contextUnitIds, ...window.coreUnitIds]),
+        ...(latest.diagnostics.segmentationIssues === undefined ? {}
+            : { segmentationIssues: Object.freeze(latest.diagnostics.segmentationIssues.map((issue) => Object.freeze({ ...issue }))) }),
+    });
+}
+async function requestFor(projectRoot, state, window, ids) {
+    const adaptiveRepair = await previousAttempt(projectRoot, state, window, ids);
+    const structuredRequest = prepareDocumentGraphWindowRequest({ window, source: state.source,
+        knownEntities: knownDocumentGraphEntities(state.source, [...state.completed.values()]), methodVersion: "harness-v1",
+        ...(adaptiveRepair === undefined ? {} : { adaptiveRepair }) });
+    const attempt = ids.length + 1;
+    const requestId = `document-harness-request:${sha256(stableJson({ operationId: state.descriptor.operationId,
+        windowId: window.id, attempt, sourceSha256: state.source.sourceSha256, planSha256: state.descriptor.planSha256,
+        methodSha256: state.descriptor.method.sha256, structuredRequest }))}`;
+    const core = new Set(window.coreUnitIds);
+    const allowed = new Set([...window.contextUnitIds, ...window.coreUnitIds]);
+    const evidenceUnits = state.source.units.filter((unit) => allowed.has(unit.id)).map((unit) => Object.freeze({
+        id: unit.id, kind: unit.kind, text: unit.text, core: core.has(unit.id), startOffset: unit.startOffset, endOffset: unit.endOffset,
+    }));
+    return Object.freeze({ schemaVersion: 1, operationId: state.descriptor.operationId, requestId, windowId: window.id,
+        attempt, maximumAttempts: DOCUMENT_INGESTION_CHECKPOINT_IDS.maxPartialAttempts, rawByteSha256: state.source.sourceSha256,
+        planSha256: state.descriptor.planSha256, methodSha256: state.descriptor.method.sha256,
+        evidenceUnits: Object.freeze(evidenceUnits), structuredRequest });
+}
+async function nextFromState(projectRoot, state) {
+    const summary = { schemaVersion: 1, processedWindows: state.completed.size, totalWindows: state.source.windows.length,
+        ...(state.descriptor.input.sourcePath === undefined ? {} : { sourcePath: state.descriptor.input.sourcePath }),
+        ...(state.descriptor.input.sourceStoragePath === undefined ? {} : { sourceStoragePath: state.descriptor.input.sourceStoragePath }) };
+    if (state.status.phase === "committed")
+        return Object.freeze({ ...summary, state: "committed" });
+    for (const window of state.source.windows) {
+        if (state.completed.has(window.id))
+            continue;
+        const ids = partialIds(state.status, window.id);
+        if (ids.length >= DOCUMENT_INGESTION_CHECKPOINT_IDS.maxPartialAttempts) {
+            const last = graphSegment(await readDocumentIngestionCheckpoint(projectRoot, state.descriptor.operationId, ids.at(-1)), window.id);
+            return Object.freeze({ ...summary, state: "repair_exhausted", windowId: window.id, attempts: ids.length,
+                reasons: Object.freeze(Object.keys(last.diagnostics.rejectionReasons).sort()) });
+        }
+        return Object.freeze({ ...summary, state: "request", request: await requestFor(projectRoot, state, window, ids) });
+    }
+    return Object.freeze({ ...summary, state: "ready_to_commit" });
+}
+/** 只保存用户选定的最终成书原文字节；不接收或记录 harness 对话。 */
+export async function prepareHarnessDocumentIngestion(host, input, options) {
+    const abort = new AbortController();
+    abort.abort();
+    const receipt = await ingestHarnessDocument(host, input, { projectRoot: options.projectRoot,
+        modelConnection: unavailableModelConnection(), signal: abort.signal, concurrency: 1,
+        ...(options.sourceOptions === undefined ? {} : { sourceOptions: options.sourceOptions }) });
+    return Object.freeze({ receipt, next: await nextHarnessDocumentIngestion(options.projectRoot, receipt.operationId) });
+}
+/** 跨 CLI/MCP 调用可重复计算的下一请求；函数只读，不持久化 prompt 或聊天日志。 */
+export async function nextHarnessDocumentIngestion(projectRoot, operationId) {
+    return nextFromState(projectRoot, await loadState(projectRoot, operationId));
+}
+async function validateCandidateForRequest(projectRoot, state, request, candidate) {
+    const window = state.source.windows.find((item) => item.id === request.windowId);
+    if (window === undefined)
+        fail("E_REFERENCE_MISSING", "harness request window 不存在", "HARNESS_WINDOW_MISSING");
+    const ids = partialIds(state.status, window.id).slice(0, request.attempt - 1);
+    const adaptiveRepair = await previousAttempt(projectRoot, state, window, ids);
+    try {
+        return validateDocumentGraphWindowCandidate({ window, source: state.source,
+            knownEntities: knownDocumentGraphEntities(state.source, [...state.completed.values()]), methodVersion: "harness-v1",
+            ...(adaptiveRepair === undefined ? {} : { adaptiveRepair }) }, candidate);
+    }
+    catch (error) {
+        if (error instanceof AuthoringBridgeError)
+            throw error;
+        fail("E_OPERATION_ID_CONFLICT", "harness request validation context 已损坏", "HARNESS_VALIDATION_CONTEXT_CONFLICT");
+    }
+}
+function ledgerPayload(ledger) {
+    return asJson({ schema_version: 1, operation_id: ledger.operationId, request_id: ledger.requestId,
+        candidate_sha256: ledger.candidateSha256, segment_sha256: ledger.segmentSha256, window_id: ledger.windowId,
+        attempt: ledger.attempt, accepted: ledger.accepted, graph_status: ledger.graphStatus, checkpoint_id: ledger.checkpointId });
+}
+async function acceptanceResult(projectRoot, ledger) {
+    return Object.freeze({ schemaVersion: 1, operationId: ledger.operationId, requestId: ledger.requestId,
+        windowId: ledger.windowId, attempt: ledger.attempt, accepted: ledger.accepted, graphStatus: ledger.graphStatus,
+        next: await nextHarnessDocumentIngestion(projectRoot, ledger.operationId) });
+}
+async function replayAcceptance(projectRoot, ledger, candidate) {
+    if (ledger.candidateSha256 !== candidate.sha256) {
+        fail("E_OPERATION_ID_CONFLICT", "同一 harness request_id 已绑定不同 response", "HARNESS_RESPONSE_DIGEST_CONFLICT", { request_id: ledger.requestId });
+    }
+    const state = await loadState(projectRoot, ledger.operationId);
+    let checkpoint;
+    try {
+        checkpoint = graphSegment(await readDocumentIngestionCheckpoint(projectRoot, ledger.operationId, ledger.checkpointId), ledger.windowId);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    if (checkpoint !== undefined) {
+        if (sha256(stableJson(asJson(checkpoint))) !== ledger.segmentSha256 || checkpoint.status !== ledger.graphStatus) {
+            fail("E_OPERATION_ID_CONFLICT", "harness acceptance checkpoint 与 ledger 不匹配", "HARNESS_ACCEPTANCE_LEDGER_CONFLICT");
+        }
+        return acceptanceResult(projectRoot, ledger);
+    }
+    if (state.status.phase !== "extracting") {
+        fail("E_OPERATION_ID_CONFLICT", "harness acceptance ledger 缺少对应 checkpoint", "HARNESS_ACCEPTANCE_LEDGER_CORRUPT");
+    }
+    const requestState = await nextFromState(projectRoot, state);
+    if (requestState.state !== "request" || requestState.request.requestId !== ledger.requestId) {
+        fail("E_OPERATION_ID_CONFLICT", "harness acceptance 恢复点已变化", "HARNESS_REQUEST_STALE");
+    }
+    const segment = await validateCandidateForRequest(projectRoot, state, requestState.request, candidate.value);
+    if (sha256(stableJson(asJson(segment))) !== ledger.segmentSha256 || segment.status !== ledger.graphStatus) {
+        fail("E_OPERATION_ID_CONFLICT", "harness response 无法重建 ledger 中的校验结果", "HARNESS_ACCEPTANCE_LEDGER_CONFLICT");
+    }
+    const journal = await openDocumentIngestionJournal({ projectRoot, operationId: ledger.operationId,
+        sourceByteSha256: state.status.sourceByteSha256, planSha256: state.status.planSha256,
+        modelId: state.status.modelId, expectedProjectRevision: state.status.expectedProjectRevision,
+        ...(state.status.method === undefined ? {} : { method: state.status.method }) });
+    try {
+        if (await journal.readSegment(ledger.checkpointId) === null) {
+            await journal.writeSegment(ledger.checkpointId, asJson(segment));
+            if (segment.status === "partial") {
+                await journal.recordSegmentFailure(ledger.windowId, { code: ledger.attempt >= DOCUMENT_INGESTION_CHECKPOINT_IDS.maxPartialAttempts
+                        ? "document_graph_partial_retry_exhausted" : "document_graph_partial",
+                    retryable: ledger.attempt < DOCUMENT_INGESTION_CHECKPOINT_IDS.maxPartialAttempts, attempts: ledger.attempt });
+            }
+            else
+                await journal.clearSegmentFailure(ledger.windowId);
+        }
+    }
+    finally {
+        await journal.close();
+    }
+    return acceptanceResult(projectRoot, ledger);
+}
+/** requestId 是对 source/method/checkpoint/prompt 的 CAS；只把校验后的 GraphSegment 写入 journal。 */
+export async function acceptHarnessDocumentIngestion(projectRoot, operationId, requestId, candidate, 
+/** 仅用于模块测试模拟 ledger 与 checkpoint 之间的进程中断；产品调用必须省略。 */
+dependencies = {}) {
+    const normalized = normalizedCandidate(candidate);
+    const existing = await readAcceptanceLedger(projectRoot, operationId, requestId);
+    if (existing !== null)
+        return replayAcceptance(projectRoot, existing, normalized);
+    const state = await loadState(projectRoot, operationId);
+    const next = await nextFromState(projectRoot, state);
+    if (next.state !== "request" || next.request.requestId !== requestId || next.request.operationId !== operationId) {
+        fail("E_OPERATION_ID_CONFLICT", "harness request_id 已过期或不属于该 operation", "HARNESS_REQUEST_STALE", { operation_id: operationId });
+    }
+    const request = next.request;
+    const window = state.source.windows.find((item) => item.id === request.windowId);
+    const ids = partialIds(state.status, window.id);
+    const segment = await validateCandidateForRequest(projectRoot, state, request, normalized.value);
+    const checkpointId = segment.status === "partial"
+        ? `${DOCUMENT_INGESTION_CHECKPOINT_IDS.partialAttemptPrefix}${window.id}:${request.attempt}`
+        : request.attempt === 1 ? window.id : `${DOCUMENT_INGESTION_CHECKPOINT_IDS.retryCompletePrefix}${window.id}`;
+    const ledger = Object.freeze({ schemaVersion: 1, operationId, requestId,
+        candidateSha256: normalized.sha256, segmentSha256: sha256(stableJson(asJson(segment))), windowId: window.id,
+        attempt: request.attempt, accepted: segment.status === "complete", graphStatus: segment.status, checkpointId });
+    const journal = await openDocumentIngestionJournal({ projectRoot, operationId,
+        sourceByteSha256: state.status.sourceByteSha256, planSha256: state.status.planSha256,
+        modelId: state.status.modelId, expectedProjectRevision: state.status.expectedProjectRevision,
+        ...(state.status.method === undefined ? {} : { method: state.status.method }) });
+    let concurrentLedger;
+    try {
+        const current = await journal.getStatus();
+        const currentIds = partialIds(current, window.id);
+        const retryId = `${DOCUMENT_INGESTION_CHECKPOINT_IDS.retryCompletePrefix}${window.id}`;
+        const ledgerValue = await journal.readSegment(acceptanceCheckpointId(requestId));
+        if (ledgerValue !== null) {
+            concurrentLedger = parseAcceptanceLedger(ledgerValue);
+            if (concurrentLedger.candidateSha256 !== normalized.sha256) {
+                fail("E_OPERATION_ID_CONFLICT", "同一 harness request_id 已绑定不同 response", "HARNESS_RESPONSE_DIGEST_CONFLICT", { request_id: requestId });
+            }
+        }
+        else {
+            if (current.phase !== "extracting" || currentIds.length !== ids.length
+                || current.completedSegmentIds.includes(window.id) || current.completedSegmentIds.includes(retryId)) {
+                fail("E_OPERATION_ID_CONFLICT", "harness request_id 已过期", "HARNESS_REQUEST_STALE", { request_id: requestId });
+            }
+            // 先持久化不含原始 response 的 digest ledger；进程若在下一写入前退出，重复 accept 可安全补齐 checkpoint。
+            await journal.writeSegment(acceptanceCheckpointId(requestId), ledgerPayload(ledger));
+            await dependencies.afterAcceptanceLedgerPersist?.();
+            await journal.writeSegment(checkpointId, asJson(segment));
+            if (segment.status === "partial") {
+                await journal.recordSegmentFailure(window.id, { code: request.attempt >= request.maximumAttempts
+                        ? "document_graph_partial_retry_exhausted" : "document_graph_partial", retryable: request.attempt < request.maximumAttempts,
+                    attempts: request.attempt });
+            }
+            else
+                await journal.clearSegmentFailure(window.id);
+        }
+    }
+    finally {
+        await journal.close();
+    }
+    return concurrentLedger === undefined ? acceptanceResult(projectRoot, ledger) : replayAcceptance(projectRoot, concurrentLedger, normalized);
+}
+/** 所有窗口 complete 后复用 losslessDocument 的唯一 assemble + world_apply CAS commit。 */
+export async function commitHarnessDocumentIngestion(host, projectRoot, operationId) {
+    const next = await nextHarnessDocumentIngestion(projectRoot, operationId);
+    if (next.state !== "ready_to_commit" && next.state !== "committed") {
+        fail("E_VALIDATION_FAILED", "harness ingestion 尚未完成全部窗口校验", "HARNESS_INGESTION_NOT_READY", { state: next.state });
+    }
+    return resumeHarnessDocument(host, operationId, { projectRoot, modelConnection: unavailableModelConnection(), concurrency: 1 });
+}

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+export * from "./cli-command.js";
+export * from "./mcp.js";
+export * from "./public-error.js";
+export * from "./project-host.js";
+export * from "./scenario-writer.js";
+export * from "./desktop-authoring-runtime.js";
+export * from "./ladybug-runtime.js";
+export * from "./trigger-runtime.js";
+export * from "./authoring-model-connection.js";
+export * from "./account-model-proxy.js";
+export * from "./local-account-embedding.js";
+export * from "./authoring-ingestion.js";
+export * from "./document-source.js";
+export * from "./document-graph-extractor.js";
+export * from "./document-ingestion-journal.js";
+export * from "./document-ingestion.js";
+export * from "./harness-document-ingestion.js";
+export * from "./document-query.js";
+export * from "./graph-traversal.js";
+export * from "./retrieval-benchmark.js";
+export * from "./document-dump.js";
+export * from "./embedding-cache.js";
+export * from "./prepared-embedding-cache.js";
+export * from "./preview-browser-adapter.js";
+export * from "./chromium-preview-browser-driver.js";
+export * from "./prepared-embedding-cache.js";
+export * from "./desktop-sidecar.js";
+export * from "./local-gui-contract.js";
+export * from "./local-gui-auth.js";
+export * from "./local-gui-server.js";
+export * from "./local-gui-workspace.js";
+export * from "./project-auth.js";
+export * from "./project-auth-transport.js";
+export * from "./project-git.js";
+export * from "./project-git-cli.js";
+export * from "./preview-runtime.js";
+export * from "./preview-browser-adapter.js";
+export * from "./frozen-review.js";
+export * from "./frozen-review-local-pipeline.js";
+export * from "./cli/review.js";
+export * from "./transfer-types.js";
+export * from "./transfer.js";
+export * from "./view-watcher.js";

package/dist/index.js

@@ -0,0 +1,43 @@
+export * from "./cli-command.js";
+export * from "./mcp.js";
+export * from "./public-error.js";
+export * from "./project-host.js";
+export * from "./scenario-writer.js";
+export * from "./desktop-authoring-runtime.js";
+export * from "./ladybug-runtime.js";
+export * from "./trigger-runtime.js";
+export * from "./authoring-model-connection.js";
+export * from "./account-model-proxy.js";
+export * from "./local-account-embedding.js";
+export * from "./authoring-ingestion.js";
+export * from "./document-source.js";
+export * from "./document-graph-extractor.js";
+export * from "./document-ingestion-journal.js";
+export * from "./document-ingestion.js";
+export * from "./harness-document-ingestion.js";
+export * from "./document-query.js";
+export * from "./graph-traversal.js";
+export * from "./retrieval-benchmark.js";
+export * from "./document-dump.js";
+export * from "./embedding-cache.js";
+export * from "./prepared-embedding-cache.js";
+export * from "./preview-browser-adapter.js";
+export * from "./chromium-preview-browser-driver.js";
+export * from "./prepared-embedding-cache.js";
+export * from "./desktop-sidecar.js";
+export * from "./local-gui-contract.js";
+export * from "./local-gui-auth.js";
+export * from "./local-gui-server.js";
+export * from "./local-gui-workspace.js";
+export * from "./project-auth.js";
+export * from "./project-auth-transport.js";
+export * from "./project-git.js";
+export * from "./project-git-cli.js";
+export * from "./preview-runtime.js";
+export * from "./preview-browser-adapter.js";
+export * from "./frozen-review.js";
+export * from "./frozen-review-local-pipeline.js";
+export * from "./cli/review.js";
+export * from "./transfer-types.js";
+export * from "./transfer.js";
+export * from "./view-watcher.js";