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

package/dist/document-query.js

@@ -0,0 +1,1106 @@
+import { createHash } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+import { AuthoringModelConnectionError } from "./authoring-model-connection.js";
+import { classifyDocumentRelationRole } from "./document-relation-role.js";
+import { enumerateDiverseGraphPaths } from "./graph-traversal.js";
+import { checkSelectedPathQuotes } from "./document-query-path-proof.js";
+import { canonicalizeSelectedProofPaths } from "./document-query-proof-paths.js";
+import { renderDocumentQueryPathOptions } from "./document-query-path-renderer.js";
+const REQUIRED_MODEL = "deepseek-v4-flash";
+const DEFAULT_DEPTH = 2;
+const MAX_DEPTH = 4;
+const DEFAULT_SEARCH_LIMIT = 12;
+const MAX_SEARCH_LIMIT = 32;
+const DEFAULT_PATH_LIMIT = 48;
+const MAX_PATH_LIMIT = 128;
+const DEFAULT_EVIDENCE_CHARACTERS = 16_000;
+const MAX_EVIDENCE_CHARACTERS = 60_000;
+const MAX_QUERY_CHARACTERS = 1_000;
+const MAX_PLANNED_QUERIES = 4;
+const MAX_PLANNED_RELATIONS = 16;
+const MAX_READBACK_IDS = 512;
+const MAX_QUOTE_CHARACTERS = 500;
+const GROUNDED_MAX_OUTPUT_TOKENS = 4_096;
+const SHA256 = /^[0-9a-f]{64}$/u;
+const IDENTIFIER = /^[^\0\r\n]{1,512}$/u;
+function pathIdentifier(path) {
+    return `path:${createHash("sha256").update(JSON.stringify([path.nodeIds, path.edges.map((edge) => JSON.stringify([edge.src, edge.dst, edge.kind]))])).digest("hex").slice(0, 24)}`;
+}
+function renderedPaths(paths, entities, relations) {
+    return renderDocumentQueryPathOptions({ paths: paths.map((path) => ({ ...path, pathId: pathIdentifier(path) })),
+        entities: new Map(entities.map((entity) => [entity.id, { id: entity.id, kind: entity.kind, props: record(entity.props, "readback_entity_props_invalid") }])),
+        relations: relations.map((edge) => ({ src: edge.src, dst: edge.dst, kind: edge.kind, props: record(edge.props, "readback_relation_props_invalid") })),
+    }).path_options;
+}
+// factory 的消息要求 NFC；仅转义含非 NFC 字节序列的 JSON 字符串，解码后原文不变。
+function modelJson(value) {
+    return JSON.stringify(value).replace(/"(?:\\.|[^"\\])*"/gu, (token) => token.normalize("NFC") === token ? token
+        : token.replace(/[^\x20-\x7e]/g, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`));
+}
+function quoteOptions(evidence) {
+    return Object.freeze(evidence.flatMap((source) => {
+        const options = [];
+        let start = 0;
+        while (start < source.text.length) {
+            let end = Math.min(start + MAX_QUOTE_CHARACTERS, source.text.length);
+            if (end < source.text.length) {
+                // 保留完整句边界；无句界的长句才在硬上限切分。
+                const prefix = source.text.slice(start, end);
+                const boundaries = [...prefix.matchAll(/[。！？!?；;][”’」』】）)"']*[ \t\r\n]*/gu)];
+                const last = boundaries.at(-1);
+                if (last !== undefined)
+                    end = start + last.index + last[0].length;
+                const previous = source.text.charCodeAt(end - 1);
+                const next = source.text.charCodeAt(end);
+                if ((previous >= 0xd800 && previous <= 0xdbff && next >= 0xdc00 && next <= 0xdfff)
+                    || (source.text[end - 1] === "\r" && source.text[end] === "\n"))
+                    end -= 1;
+            }
+            if (end <= start)
+                return fail("quote_option_boundary_invalid");
+            const text = source.text.slice(start, end);
+            const quoteId = `q:${createHash("sha256").update(JSON.stringify([source.evidenceId, source.contentSha256, start, end])).digest("hex")}`;
+            options.push(Object.freeze({ quoteId, evidenceId: source.evidenceId, start, end, text }));
+            start = end;
+        }
+        return options;
+    }));
+}
+function fail(code) {
+    throw new Error(`document_query:${code}`);
+}
+function record(value, code) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return fail(code);
+    return value;
+}
+function identifier(value, code) {
+    if (typeof value !== "string" || !IDENTIFIER.test(value) || value.trim() !== value || value.normalize("NFC") !== value)
+        return fail(code);
+    return value;
+}
+function boundedInteger(value, fallback, maximum, code) {
+    const resolved = value ?? fallback;
+    if (!Number.isSafeInteger(resolved) || resolved < 1 || resolved > maximum)
+        return fail(code);
+    return resolved;
+}
+function stringArray(value, code, maximum) {
+    if (!Array.isArray(value) || value.length < 1 || value.length > maximum)
+        return fail(code);
+    return Object.freeze(value.map((item) => identifier(item, code)));
+}
+function usageTotal(usages, providerId, modelId) {
+    return Object.freeze({
+        inputTokens: usages.reduce((sum, usage) => sum + usage.inputTokens, 0),
+        outputTokens: usages.reduce((sum, usage) => sum + usage.outputTokens, 0),
+        totalTokens: usages.reduce((sum, usage) => sum + usage.totalTokens, 0),
+        cachedInputTokens: usages.reduce((sum, usage) => sum + (usage.cachedInputTokens ?? 0), 0),
+        requests: usages.reduce((sum, usage) => sum + usage.requests, 0),
+        providerId,
+        modelId,
+    });
+}
+async function generate(connection, request, signal, usages) {
+    const result = await connection.structuredJson.generate({
+        ...request,
+        ...(signal === undefined ? {} : { signal }),
+    });
+    usages.push(result.usage);
+    return result.value;
+}
+function validatePlan(value, request, searchOnly = false) {
+    const candidate = record(value, "planner_output_invalid");
+    const searchQueries = stringArray(candidate.search_queries, "planner_queries_invalid", MAX_PLANNED_QUERIES);
+    if (searchQueries.some((query) => query.length > 256))
+        return fail("planner_query_too_long");
+    if (searchOnly)
+        return { search_queries: searchQueries, direction: "out", depth: request.maximumDepth, relation_kinds: [] };
+    if (candidate.direction !== "in" && candidate.direction !== "out" && candidate.direction !== "both")
+        return fail("planner_direction_invalid");
+    if (!Number.isSafeInteger(candidate.depth) || candidate.depth < 1 || candidate.depth > request.maximumDepth)
+        return fail("planner_depth_out_of_bounds");
+    const relationKinds = Array.isArray(candidate.relation_kinds) && candidate.relation_kinds.length === 0
+        ? Object.freeze([]) : stringArray(candidate.relation_kinds, "planner_relation_kinds_invalid", MAX_PLANNED_RELATIONS);
+    if (relationKinds.some((kind) => !request.allowedRelationKinds.has(kind)))
+        return fail("planner_relation_kind_forbidden");
+    return Object.freeze({ search_queries: searchQueries, direction: candidate.direction, depth: candidate.depth, relation_kinds: relationKinds });
+}
+function searchHits(value, scopeId) {
+    const root = record(value, "search_result_invalid");
+    if (!Array.isArray(root.results))
+        return fail("search_result_invalid");
+    return Object.freeze(root.results.map((entry) => {
+        const hit = record(entry, "search_hit_invalid");
+        const hitScope = hit.scopeId ?? hit.scope_id ?? null;
+        if (hitScope !== null && hitScope !== scopeId)
+            return fail("search_scope_mismatch");
+        const channels = Array.isArray(hit.channels) ? hit.channels.map((channel) => identifier(channel, "search_channel_invalid")) : [];
+        return Object.freeze({ id: identifier(hit.id, "search_id_invalid"), kind: identifier(hit.kind, "search_kind_invalid"), channels: Object.freeze(channels) });
+    }));
+}
+function graphPaths(value, seedIds, plan, pathLimit) {
+    const root = record(value, "traverse_result_invalid");
+    if (!Array.isArray(root.paths) || root.paths.length > pathLimit)
+        return fail("traverse_path_limit_exceeded");
+    return Object.freeze(root.paths.map((entry) => {
+        const path = record(entry, "traverse_path_invalid");
+        const nodeIds = stringArray(path.nodeIds ?? path.node_ids, "traverse_node_ids_invalid", plan.depth + 1);
+        const firstNodeId = nodeIds[0];
+        if (firstNodeId === undefined || !seedIds.has(firstNodeId) || nodeIds.length < 2 || new Set(nodeIds).size !== nodeIds.length)
+            return fail("traverse_path_out_of_bounds");
+        if (!Array.isArray(path.edges) || path.edges.length !== nodeIds.length - 1)
+            return fail("traverse_edges_invalid");
+        const edges = path.edges.map((entryValue, index) => {
+            const edge = record(entryValue, "traverse_edge_invalid");
+            const src = identifier(edge.src, "traverse_edge_src_invalid");
+            const dst = identifier(edge.dst, "traverse_edge_dst_invalid");
+            const kind = identifier(edge.kind, "traverse_edge_kind_invalid");
+            if (!plan.relation_kinds.includes(kind))
+                return fail("traverse_relation_kind_forbidden");
+            const left = nodeIds[index];
+            const right = nodeIds[index + 1];
+            if (left === undefined || right === undefined)
+                return fail("traverse_edge_out_of_bounds");
+            const forward = src === left && dst === right;
+            const backward = src === right && dst === left;
+            if ((plan.direction === "out" && !forward) || (plan.direction === "in" && !backward) || (plan.direction === "both" && !forward && !backward))
+                return fail("traverse_edge_direction_mismatch");
+            const props = edge.props === undefined ? undefined : record(edge.props, "traverse_edge_props_invalid");
+            const qualifiers = edge.qualifiers ?? props?.qualifiers;
+            if (qualifiers !== undefined && (typeof qualifiers !== "object" || qualifiers === null || Array.isArray(qualifiers)))
+                return fail("traverse_edge_qualifiers_invalid");
+            return Object.freeze({ src, dst, kind, ...(qualifiers === undefined ? {} : { qualifiers: qualifiers }) });
+        });
+        return Object.freeze({ nodeIds, edges: Object.freeze(edges) });
+    }));
+}
+function sourceBinding(schema) {
+    if (schema.project_id === undefined && schema.project_revision === undefined && schema.source_sha256 === undefined)
+        return null;
+    const projectId = identifier(schema.project_id, "schema_project_id_invalid");
+    if (!Number.isSafeInteger(schema.project_revision) || schema.project_revision < 0)
+        return fail("schema_project_revision_invalid");
+    if (typeof schema.source_sha256 !== "string" || !SHA256.test(schema.source_sha256))
+        return fail("schema_source_sha256_invalid");
+    return Object.freeze({ projectId, projectRevision: schema.project_revision, sourceSha256: schema.source_sha256 });
+}
+/**
+ * 外部 harness 的检索 seam：Host 只做 hybrid recall、物理图遍历、原文回读与完整性校验，
+ * 不调用 structured model，也不生成答案。结构理解、否定/时间推理由调用方基于 bundle 完成。
+ */
+export async function retrieveDocumentEvidenceBundle(host, request) {
+    if (typeof request.query !== "string" || request.query.trim().length === 0 || request.query.includes("\0") || request.query.normalize("NFC") !== request.query)
+        return fail("query_invalid");
+    if (request.query.length > MAX_QUERY_CHARACTERS)
+        return fail("query_too_long");
+    const query = request.query;
+    const searchMode = request.searchMode ?? "hybrid";
+    if (searchMode !== "keyword" && searchMode !== "hybrid")
+        return fail("search_mode_invalid");
+    const scopeId = identifier(request.scopeId, "scope_invalid");
+    const maximumDepth = boundedInteger(request.maxDepth, DEFAULT_DEPTH, MAX_DEPTH, "depth_out_of_bounds");
+    const searchLimit = boundedInteger(request.searchLimit, DEFAULT_SEARCH_LIMIT, MAX_SEARCH_LIMIT, "search_limit_out_of_bounds");
+    const pathLimit = boundedInteger(request.pathLimit, DEFAULT_PATH_LIMIT, MAX_PATH_LIMIT, "path_limit_out_of_bounds");
+    const evidenceBudget = boundedInteger(request.evidenceCharacterBudget, DEFAULT_EVIDENCE_CHARACTERS, MAX_EVIDENCE_CHARACTERS, "evidence_budget_out_of_bounds");
+    const queries = request.searchQueries === undefined ? Object.freeze([query])
+        : stringArray(request.searchQueries, "search_queries_invalid", MAX_PLANNED_QUERIES);
+    if (queries.some((value) => value.length > 256))
+        return fail("search_query_too_long");
+    const firstSchema = record(await host.dispatchTool({ name: "world_schema", input: {} }), "schema_invalid");
+    if (!Array.isArray(firstSchema.relation_kinds))
+        return fail("schema_relation_kinds_invalid");
+    const actualKinds = new Set(firstSchema.relation_kinds.map((kind) => identifier(kind, "schema_relation_kind_invalid")));
+    const allowedKinds = new Set(request.allowedRelationKinds ?? actualKinds);
+    if (request.allowedRelationKinds !== undefined && (allowedKinds.size < 1 || allowedKinds.size > 128))
+        return fail("allowed_relation_kinds_invalid");
+    for (const kind of allowedKinds)
+        if (!actualKinds.has(identifier(kind, "allowed_relation_kind_invalid")))
+            return fail("allowed_relation_kind_unknown");
+    const binding = sourceBinding(firstSchema);
+    const trace = [];
+    const candidates = [];
+    const seedIds = new Set();
+    const hitKinds = new Map();
+    const seedScores = new Map();
+    for (const searchQuery of queries) {
+        const hits = searchHits(await host.dispatchTool({ name: "world_search", input: {
+                query: searchQuery, mode: searchMode, limit: searchLimit, filters: { scope_id: scopeId },
+            } }), scopeId).slice(0, searchLimit);
+        for (const [rank, hit] of hits.entries()) {
+            candidates.push({ ...hit, query: searchQuery, rank });
+            if (hit.kind === "world_source_document" || hit.kind === "source_document")
+                continue;
+            seedIds.add(hit.id);
+            hitKinds.set(hit.id, hit.kind);
+            seedScores.set(hit.id, (seedScores.get(hit.id) ?? 0) + 1 / (rank + 1));
+        }
+        trace.push({ stage: "search", detail: { query: searchQuery, seedIds: hits.map((hit) => hit.id), channels: hits.map((hit) => hit.channels) } });
+    }
+    if (seedIds.size === 0) {
+        if (binding !== null) {
+            const after = sourceBinding(record(await host.dispatchTool({ name: "world_schema", input: {} }), "schema_invalid"));
+            if (after === null || !isDeepStrictEqual(after, binding))
+                return fail("source_changed_during_retrieval");
+        }
+        return Object.freeze({ query, scopeId, searchMode, candidates: Object.freeze(candidates), graphPaths: [], pathOptions: [], evidence: [],
+            integrity: Object.freeze({ sourceBinding: binding === null ? "unavailable" : "verified", evidenceCoverage: "empty", traversalTruncated: false }),
+            retrievalTrace: Object.freeze(trace) });
+    }
+    const seedReadback = await readGraph(host, seedIds, scopeId);
+    const sourceSeedIds = new Set([...hitKinds].filter(([, kind]) => kind === "world_source_chunk" || kind === "source_chunk").map(([id]) => id));
+    const seedAssertions = await readGraph(host, assertionIds([seedReadback], new Set(seedIds)), scopeId);
+    const semantic = semanticSeeds([seedReadback, seedAssertions], hitKinds);
+    const traversalValue = semantic.size === 0 ? { paths: [], truncated: false } : record(await host.dispatchTool({ name: "world_traverse", input: {
+            start_ids: [...semantic], scope_id: scopeId, direction: "both", depth: maximumDepth,
+            relation_kinds: [...allowedKinds], semantic_only: true, limit: pathLimit,
+        } }), "traverse_result_invalid");
+    const nativeTraversalTruncated = traversalValue.truncated === true;
+    const nativePaths = semantic.size === 0 ? [] : graphPaths(traversalValue, semantic, {
+        search_queries: queries, direction: "both", depth: maximumDepth, relation_kinds: [...allowedKinds],
+    }, pathLimit);
+    const nativeEdges = [...new Map(nativePaths.flatMap((path) => path.edges).map((edge) => [JSON.stringify([edge.src, edge.dst, edge.kind]), edge])).values()];
+    const enumerated = enumerateDiverseGraphPaths({ edges: nativeEdges, seeds: semantic, maximumDepth, limit: pathLimit });
+    const traversalTruncated = nativeTraversalTruncated || enumerated.truncated;
+    const candidateIds = new Set(enumerated.paths.flatMap((path) => path.nodeIds));
+    const rawPaths = graphPaths({ paths: enumerated.paths }, candidateIds, {
+        search_queries: queries, direction: "both", depth: maximumDepth, relation_kinds: [...allowedKinds],
+    }, pathLimit).filter((path) => path.nodeIds.some((id) => semantic.has(id)));
+    trace.push({ stage: "traverse", detail: { authority: "world_traverse_physical_relations", pathCount: rawPaths.length, truncated: traversalTruncated } });
+    const pathIds = new Set(rawPaths.flatMap((path) => path.nodeIds));
+    const pathReadback = await readGraph(host, pathIds, scopeId);
+    const pathAssertions = await readGraph(host, assertionIds([pathReadback], pathIds), scopeId);
+    const readbacks = [seedReadback, seedAssertions, pathReadback, pathAssertions];
+    const rankedChunkIds = [...rankedSourceChunkIds(readbacks, seedScores, rawPaths, rawPaths)];
+    for (const id of sourceSeedIds)
+        if (!rankedChunkIds.includes(id))
+            rankedChunkIds.push(id);
+    const chunksReadback = await readGraph(host, new Set(rankedChunkIds), scopeId);
+    readbacks.push(chunksReadback);
+    const allIds = new Set([...seedIds, ...pathIds, ...rankedChunkIds]);
+    const uniqueEntities = [...new Map(readbacks.flatMap((item) => item.entities).map((entity) => [entity.id, entity])).values()];
+    const evidenceById = new Map(evidenceFromReadback({ entities: uniqueEntities }, allIds, scopeId).map((item) => [item.evidenceId, item]));
+    const rankedEvidence = rankedChunkIds.flatMap((id) => evidenceById.get(id) ?? []);
+    const evidence = budgetEvidence(rankedEvidence, evidenceBudget);
+    const paths = supportedPaths(rawPaths, readbacks, evidence);
+    const relations = [...relationIndex(readbacks.flatMap((item) => item.relations)).values()];
+    const pathOptions = renderedPaths(paths, uniqueEntities, relations);
+    trace.push({ stage: "readback", detail: { evidenceIds: evidence.map((item) => item.evidenceId), usedCharacters: evidence.reduce((sum, item) => sum + item.text.length, 0),
+            supportedPathCount: paths.length, candidatePathCount: rawPaths.length } });
+    if (binding !== null) {
+        const after = sourceBinding(record(await host.dispatchTool({ name: "world_schema", input: {} }), "schema_invalid"));
+        if (after === null || !isDeepStrictEqual(after, binding))
+            return fail("source_changed_during_retrieval");
+    }
+    const fullySupportedPathCount = paths.filter((path) => path.edges.every((edge) => (edge.evidenceIds?.length ?? 0) > 0)).length;
+    const coverage = rankedEvidence.length === 0 ? "empty"
+        : (!traversalTruncated && evidence.length === rankedEvidence.length && fullySupportedPathCount === rawPaths.length ? "complete" : "partial");
+    return Object.freeze({ query, scopeId, searchMode, candidates: Object.freeze(candidates), graphPaths: Object.freeze(paths), pathOptions: Object.freeze(pathOptions),
+        evidence: Object.freeze(evidence), integrity: Object.freeze({ sourceBinding: binding === null ? "unavailable" : "verified", evidenceCoverage: coverage, traversalTruncated }),
+        retrievalTrace: Object.freeze(trace) });
+}
+function evidenceFromReadback(value, allowedIds, scopeId) {
+    const root = record(value, "readback_invalid");
+    if (!Array.isArray(root.entities))
+        return fail("readback_entities_invalid");
+    return Object.freeze(root.entities.flatMap((entry) => {
+        const entity = record(entry, "readback_entity_invalid");
+        const id = identifier(entity.id, "readback_entity_id_invalid");
+        if (!allowedIds.has(id))
+            return fail("readback_unknown_entity");
+        if (entity.kind !== "world_source_chunk" && entity.kind !== "source_chunk")
+            return [];
+        const props = record(entity.props, "readback_chunk_props_invalid");
+        const nodeScope = props.scopeId ?? props.scope_id ?? entity.scopeId ?? entity.scope_id;
+        if (nodeScope !== undefined && nodeScope !== scopeId)
+            return fail("readback_scope_mismatch");
+        if (props.generated_context === true || props.evidence_authority === "generated_context")
+            return [];
+        const text = props.index_text;
+        const documentId = props.documentId ?? props.document_id;
+        const startOffset = props.startOffset ?? props.start_offset;
+        const endOffset = props.endOffset ?? props.end_offset;
+        const contentSha256 = props.contentSha256 ?? props.content_sha256 ?? props.chunk_sha256;
+        if (typeof text !== "string" || text.length === 0)
+            return fail("readback_chunk_text_invalid");
+        if (!Number.isSafeInteger(startOffset) || !Number.isSafeInteger(endOffset) || startOffset < 0 || endOffset <= startOffset)
+            return fail("readback_chunk_offsets_invalid");
+        if (typeof contentSha256 !== "string" || !SHA256.test(contentSha256)
+            || createHash("sha256").update(text, "utf8").digest("hex") !== contentSha256)
+            return fail("readback_chunk_hash_invalid");
+        if (endOffset - startOffset !== text.length)
+            return fail("readback_chunk_offsets_invalid");
+        return [Object.freeze({
+                evidenceId: id,
+                documentId: identifier(documentId, "readback_document_id_invalid"),
+                startOffset: startOffset,
+                endOffset: endOffset,
+                contentSha256,
+                text,
+            })];
+    }));
+}
+function budgetEvidence(values, maximumCharacters) {
+    const result = [];
+    let used = 0;
+    for (const evidence of values) {
+        if (used + evidence.text.length > maximumCharacters)
+            continue;
+        used += evidence.text.length;
+        result.push(evidence);
+    }
+    return Object.freeze(result);
+}
+function relationIndex(relations) {
+    const result = new Map();
+    for (const edge of relations) {
+        const key = JSON.stringify([edge.src, edge.dst, edge.kind]);
+        const previous = result.get(key);
+        // 当前 physical identity 不含断言版本；不同限定/证据不能用 last-write-wins 猜一个事实。
+        if (previous !== undefined && !isDeepStrictEqual(previous.props, edge.props))
+            return fail("physical_relation_conflict");
+        result.set(key, edge);
+    }
+    return result;
+}
+async function readGraph(host, ids, scopeId) {
+    if (ids.size === 0)
+        return { entities: [], relations: [] };
+    if (ids.size > MAX_READBACK_IDS)
+        return fail("readback_limit_exceeded");
+    const root = record(await host.dispatchTool({ name: "world_get", input: { ids: [...ids], include_relations: true } }), "readback_invalid");
+    if (!Array.isArray(root.entities) || !Array.isArray(root.relations))
+        return fail("readback_invalid");
+    const entities = root.entities.map((value) => {
+        const entity = record(value, "readback_entity_invalid");
+        if (!ids.has(identifier(entity.id, "readback_entity_id_invalid")))
+            return fail("readback_unknown_entity");
+        const props = record(entity.props, "readback_entity_props_invalid");
+        const actualScope = props.scope_id ?? props.scopeId ?? entity.scope_id ?? entity.scopeId;
+        if (actualScope !== undefined && actualScope !== scopeId)
+            return fail("readback_scope_mismatch");
+        return entity;
+    });
+    const relations = root.relations.map((value) => {
+        const edge = record(value, "readback_relation_invalid");
+        const src = identifier(edge.src, "readback_relation_src_invalid");
+        const dst = identifier(edge.dst, "readback_relation_dst_invalid");
+        identifier(edge.kind, "readback_relation_kind_invalid");
+        if (!ids.has(src) && !ids.has(dst))
+            return fail("readback_relation_not_incident");
+        return edge;
+    });
+    return { entities, relations: [...relationIndex(relations).values()] };
+}
+/** 搜索之后才基于实际候选选择关系及物理遍历方向；候选本身不构成事实证据。 */
+async function refineRoute(host, input, dependencies, usages, trace) {
+    const readbacks = [];
+    const nodes = new Map();
+    const endpointNodes = new Map();
+    const loadedIds = new Set();
+    const edges = new Map();
+    const seen = new Set();
+    const nodeLimit = Math.min(MAX_READBACK_IDS, Math.max(input.seedIds.size, input.pathLimit * (input.maximumDepth + 1)));
+    const edgeLimit = Math.min(MAX_READBACK_IDS, input.pathLimit * input.maximumDepth);
+    let truncated = false;
+    let frontier = new Set([...input.seedIds].slice(0, nodeLimit));
+    const safeNode = (entity) => !String(entity.kind).includes("source_")
+        && entity.kind !== "world_ingestion_source_control" && entity.kind !== "world_document_statement" && entity.kind !== "world_document_edge_assertion";
+    const remember = (readback, requested) => {
+        for (const id of requested)
+            loadedIds.add(id);
+        for (const entity of readback.entities) {
+            const props = entity.props;
+            const scope = props.scope_id ?? props.scopeId ?? entity.scope_id ?? entity.scopeId;
+            if (scope !== input.scopeId)
+                return fail("route_scope_missing");
+            endpointNodes.set(entity.id, entity);
+            if (safeNode(entity)) {
+                if (nodes.has(entity.id) || nodes.size < nodeLimit)
+                    nodes.set(entity.id, entity);
+                else
+                    truncated = true;
+            }
+        }
+        readbacks.push({ entities: readback.entities.filter(safeNode), relations: readback.relations });
+    };
+    for (let round = 0; round <= input.maximumDepth && frontier.size > 0; round += 1) {
+        const readback = await readGraph(host, frontier, input.scopeId);
+        for (const id of frontier)
+            seen.add(id);
+        remember(readback, frontier);
+        const incident = readback.relations.filter((edge) => input.allowedKinds.has(edge.kind));
+        // 先回读端点再交给唯一角色分类器；unknown 不得当成 semantic，也不能沿 source hub 扩散。
+        const unresolved = new Set();
+        const byAssertion = [...incident].sort((left, right) => Number(typeof right.props?.assertion === "string") - Number(typeof left.props?.assertion === "string"));
+        for (const edge of byAssertion)
+            for (const value of [edge.src, edge.dst]) {
+                const id = identifier(value, "route_candidate_id_invalid");
+                if (loadedIds.has(id) || unresolved.has(id))
+                    continue;
+                if (loadedIds.size + unresolved.size >= MAX_READBACK_IDS) {
+                    truncated = true;
+                    continue;
+                }
+                unresolved.add(id);
+            }
+        if (unresolved.size > 0)
+            remember(await readGraph(host, unresolved, input.scopeId), unresolved);
+        const next = new Set();
+        for (const edge of incident) {
+            if (!nodes.has(edge.src) || !nodes.has(edge.dst))
+                continue;
+            if (classifyDocumentRelationRole({ relation: { kind: edge.kind, props: record(edge.props, "route_edge_props_invalid") },
+                endpoints: { srcKind: endpointNodes.get(edge.src)?.kind, dstKind: endpointNodes.get(edge.dst)?.kind } }) !== "semantic")
+                continue;
+            const key = JSON.stringify([edge.src, edge.dst, edge.kind]);
+            if (!edges.has(key) && edges.size >= edgeLimit) {
+                truncated = true;
+                continue;
+            }
+            const previous = edges.get(key);
+            if (previous !== undefined)
+                relationIndex([previous, edge]);
+            edges.set(key, edge);
+            if (round === input.maximumDepth)
+                continue;
+            for (const value of [edge.src, edge.dst]) {
+                const id = identifier(value, "route_candidate_id_invalid");
+                if (seen.has(id) || next.has(id))
+                    continue;
+                next.add(id);
+            }
+        }
+        frontier = next;
+    }
+    const candidates = [...edges.values()].filter((edge) => nodes.has(edge.src) && nodes.has(edge.dst));
+    const candidateIds = new Set(candidates.flatMap((edge) => [edge.src, edge.dst]));
+    const candidateSeeds = new Set([...input.seedIds].filter((id) => candidateIds.has(id)).slice(0, input.startLimit));
+    if (candidateSeeds.size < [...input.seedIds].filter((id) => candidateIds.has(id)).length)
+        truncated = true;
+    const enumerated = enumerateDiverseGraphPaths({
+        edges: candidates.map((edge) => ({ src: edge.src, dst: edge.dst, kind: edge.kind })),
+        seeds: candidateSeeds,
+        maximumDepth: input.maximumDepth,
+        limit: input.pathLimit,
+    });
+    truncated ||= enumerated.truncated;
+    const candidatePaths = graphPaths({ paths: enumerated.paths }, candidateIds, { search_queries: input.searchQueries, direction: "both", depth: input.maximumDepth, relation_kinds: [...input.allowedKinds] }, input.pathLimit);
+    if (candidatePaths.some((path) => !path.nodeIds.some((id) => candidateSeeds.has(id))))
+        return fail("route_path_anchor_missing");
+    const diagnostic = { phase: "route_refinement", candidateNodeCount: candidateIds.size, candidateEdgeCount: candidates.length, truncated, nodeLimit, edgeLimit,
+        endpointReadCount: loadedIds.size, endpointReadLimit: MAX_READBACK_IDS, candidatePathCount: candidatePaths.length,
+        candidatePathLengths: candidatePaths.map((path) => path.edges.length), pathAuthority: "world_get_physical_relations",
+        candidatePaths: candidatePaths.map((path) => ({ pathId: pathIdentifier(path), ...path })) };
+    if (candidatePaths.length === 0) {
+        trace.push({ stage: "plan", detail: { ...diagnostic, route: null } });
+        return { paths: [], candidates: candidatePaths, readbacks, truncated };
+    }
+    const optionById = new Map(candidatePaths.map((path) => [pathIdentifier(path), path]));
+    const selectionLimit = Math.min(input.startLimit, MAX_PLANNED_RELATIONS);
+    const routeSchema = { type: "object", additionalProperties: false, required: ["path_ids"], properties: {
+            path_ids: { type: "array", minItems: 0, maxItems: selectionLimit, items: { type: "string", enum: [...optionById.keys()] } },
+        } };
+    const payload = { query: input.query, scope_id: input.scopeId,
+        maximum_depth: input.maximumDepth, path_limit: input.pathLimit, candidate_truncated: truncated,
+        path_options: renderedPaths(candidatePaths, [...nodes.values()], candidates),
+    };
+    const payloadCharacters = modelJson(payload).length;
+    let feedback;
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const before = dependencies.modelConnection.usage().byProviderModel?.find((usage) => usage.providerId === dependencies.modelConnection.structuredJson.providerId && usage.modelId === REQUIRED_MODEL);
+        try {
+            const value = record(await generate(dependencies.modelConnection, {
+                schemaName: "document_query_route_v1", jsonSchema: routeSchema, taskMode: "simulation_retrieval", maxOutputTokens: 1_024,
+                messages: [
+                    { role: "system", content: "只根据用户问题选择优先回读原文的导航路径，不回答问题。每项hops自包含实际关系、端点标签及物理方向；相同label不同ref不能拼接。只返回少量相关path_ids，不生成节点、关系、方向或深度。优先选择覆盖问题锚点与待求事实的路径，无关旁支不要选；无法找到相关路线时path_ids=[]。导航只用于找证据和排序，不是事实，也不是最终答案必须引用的路径；作答阶段将在实际原文证据可用后另选proof_path_ids。候选截断不代表全图穷尽。" },
+                    { role: "user", content: modelJson({ ...payload, ...(feedback === undefined ? {} : { validation_error: feedback, instruction: "仅有这一次修复机会，严格选择已有候选并保留 scope、物理方向和请求上限。" }) }) },
+                ],
+            }, dependencies.signal, usages), "route_output_invalid");
+            if (Object.keys(value).some((key) => key !== "path_ids"))
+                return fail("route_fields_invalid");
+            const ids = Array.isArray(value.path_ids) && value.path_ids.length === 0 ? [] : stringArray(value.path_ids, "route_ids_invalid", selectionLimit);
+            const selected = [...new Set(ids)].map((id) => { const option = optionById.get(id); if (option === undefined)
+                return fail("route_id_forbidden"); return option; });
+            trace.push({ stage: "plan", detail: { ...diagnostic, payloadCharacters, attempt: attempt + 1, route: { selectedPathIds: [...new Set(ids)], selectedPathLengths: selected.map((path) => path.edges.length) } } });
+            return { paths: selected, candidates: candidatePaths, readbacks, truncated };
+        }
+        catch (error) {
+            const providerInvalid = error instanceof AuthoringModelConnectionError && error.code === "provider_response_invalid"
+                && (error.validationStage === "closed_schema" || error.validationStage === "response_parse" || error.validationStage === "response_shape");
+            if (!providerInvalid && !(error instanceof Error && /^document_query:(route_|planner_)/u.test(error.message)))
+                throw error;
+            if (providerInvalid) {
+                const after = dependencies.modelConnection.usage().byProviderModel?.find((usage) => usage.providerId === dependencies.modelConnection.structuredJson.providerId && usage.modelId === REQUIRED_MODEL);
+                if (after !== undefined && after.requests > (before?.requests ?? 0))
+                    usages.push({ inputTokens: after.inputTokens - (before?.inputTokens ?? 0), outputTokens: after.outputTokens - (before?.outputTokens ?? 0), totalTokens: after.totalTokens - (before?.totalTokens ?? 0), requests: after.requests - (before?.requests ?? 0), cachedInputTokens: (after.cachedInputTokens ?? 0) - (before?.cachedInputTokens ?? 0) });
+                feedback = { code: error.code, stage: error.validationStage, issues: error.validationIssues };
+            }
+            else
+                feedback = { code: error.message };
+            trace.push({ stage: "plan", detail: { ...diagnostic, attempt: attempt + 1, validationError: feedback } });
+            if (attempt === 1)
+                throw error;
+        }
+    }
+    return fail("route_output_invalid");
+}
+function addBounded(ids, value) {
+    if (ids.size < MAX_READBACK_IDS && typeof value === "string")
+        ids.add(identifier(value, "readback_reference_invalid"));
+}
+// 检索命中可能是原文或独立 assertion；先投影到语义端点，不能经 document hub 扩散。
+function semanticSeeds(readbacks, hits) {
+    const result = new Set();
+    for (const [id, kind] of hits) {
+        if (!kind.includes("source_") && kind !== "world_document_statement" && kind !== "world_document_edge_assertion")
+            addBounded(result, id);
+    }
+    for (const readback of readbacks) {
+        for (const entity of readback.entities) {
+            const props = entity.props;
+            if (entity.kind === "world_document_statement")
+                addBounded(result, props.subject_entity_id);
+            if (entity.kind === "world_document_edge_assertion") {
+                addBounded(result, props.source_entity_id);
+                addBounded(result, props.target_entity_id);
+            }
+        }
+        for (const relation of readback.relations) {
+            if (relation.kind === "mentions" && hits.has(relation.src))
+                addBounded(result, relation.dst);
+        }
+    }
+    return result;
+}
+function assertionIds(readbacks, nodeIds) {
+    const ids = new Set();
+    for (const readback of readbacks)
+        for (const relation of readback.relations) {
+            if ((relation.kind === "describes_source" || relation.kind === "describes_target" || relation.kind === "describes")
+                && nodeIds.has(relation.dst))
+                addBounded(ids, relation.src);
+            if (relation.kind === "supports" && nodeIds.has(relation.src))
+                addBounded(ids, relation.dst);
+        }
+    return ids;
+}
+function rankedSourceChunkIds(readbacks, seedScores, paths, candidates = []) {
+    const entities = new Map(readbacks.flatMap((readback) => readback.entities).map((entity) => [entity.id, entity]));
+    const edgeKey = (edge) => JSON.stringify([edge.src, edge.dst, edge.kind]);
+    const relations = relationIndex(readbacks.flatMap((readback) => readback.relations));
+    const pathEdges = new Set(paths.flatMap((path) => path.edges.map(edgeKey)));
+    const pathAssertions = new Set([...entities.values()].filter((entity) => {
+        const props = entity.props;
+        return entity.kind === "world_document_edge_assertion" && pathEdges.has(edgeKey({ src: props.source_entity_id, dst: props.target_entity_id, kind: props.predicate }));
+    }).map((entity) => entity.id));
+    const priorities = new Map();
+    const include = (value, tier, score) => {
+        const id = identifier(value, "readback_reference_invalid");
+        const previous = priorities.get(id);
+        if (previous === undefined)
+            priorities.set(id, { tier, score, order: priorities.size });
+        else if (tier < previous.tier)
+            priorities.set(id, { tier, score, order: previous.order });
+        else if (tier === previous.tier)
+            previous.score += score;
+    };
+    // 直接命中及其精确 supports 优先；图路径次之，普通 incident mentions 最后。
+    // world_get 返回顺序是 source 存储顺序，不能成为检索相关性或预算取舍依据。
+    for (const [id, score] of seedScores) {
+        const kind = entities.get(id)?.kind;
+        if (kind === "world_source_chunk" || kind === "source_chunk")
+            include(id, 0, score);
+    }
+    for (const relation of relations.values()) {
+        const score = seedScores.get(relation.dst);
+        const kind = entities.get(relation.dst)?.kind;
+        if (relation.kind === "supports" && score !== undefined
+            && (kind === "world_document_statement" || kind === "world_document_edge_assertion"))
+            include(relation.src, 0, score);
+    }
+    for (const path of paths)
+        for (const edge of path.edges) {
+            const relation = relations.get(edgeKey(edge));
+            const props = relation?.props;
+            if (Array.isArray(props?.source_chunk_ids))
+                for (const id of props.source_chunk_ids)
+                    include(id, 1, 0);
+        }
+    for (const path of paths)
+        for (const id of path.nodeIds) {
+            const kind = entities.get(id)?.kind;
+            if (kind === "world_source_chunk" || kind === "source_chunk")
+                include(id, 1, 0);
+        }
+    // 未优先导航的真实候选仍可由已有预算接纳；不能因导航为空而隐藏其原文或阻止后续重选。
+    for (const path of candidates)
+        for (const edge of path.edges) {
+            const props = relations.get(edgeKey(edge))?.props;
+            if (Array.isArray(props?.source_chunk_ids))
+                for (const id of props.source_chunk_ids)
+                    include(id, 2, 0);
+        }
+    for (const relation of relations.values()) {
+        if (relation.kind === "supports" && pathAssertions.has(relation.dst))
+            include(relation.src, 1, 0);
+        if (relation.kind === "supports" || relation.kind === "mentions")
+            include(relation.src, 2, seedScores.get(relation.dst) ?? 0);
+    }
+    return [...priorities].sort(([, left], [, right]) => left.tier - right.tier || right.score - left.score || left.order - right.order)
+        .slice(0, MAX_READBACK_IDS).map(([id]) => id);
+}
+function semanticEvidenceSpans(proof) {
+    return Array.isArray(proof.spans) ? proof.spans : proof.offset_semantics === "envelope_only" ? [] : [proof];
+}
+function supportedPaths(paths, readbacks, evidence) {
+    const entities = readbacks.flatMap((readback) => readback.entities);
+    const relations = [...relationIndex(readbacks.flatMap((readback) => readback.relations)).values()];
+    const byId = new Map(evidence.map((item) => [item.evidenceId, item]));
+    return paths.map((path) => ({ ...path, edges: path.edges.map((edge) => {
+            const assertions = entities.filter((entity) => {
+                const props = entity.props;
+                return entity.kind === "world_document_edge_assertion" && props.source_entity_id === edge.src
+                    && props.target_entity_id === edge.dst && props.predicate === edge.kind;
+            });
+            // 新导入直接把每跳 chunk IDs 放在语义边，旧图仍支持 assertion→supports 回溯。
+            for (const relation of relations) {
+                if (relation.src !== edge.src || relation.dst !== edge.dst || relation.kind !== edge.kind)
+                    continue;
+                const props = record(relation.props, "readback_relation_props_invalid");
+                if (!Array.isArray(props.source_chunk_ids))
+                    continue;
+                assertions.push({ id: `edge:${edge.src}:${edge.kind}:${edge.dst}`, props });
+            }
+            const evidenceIds = new Set();
+            for (const assertion of assertions) {
+                const props = assertion.props;
+                const proof = record(props.evidence, "assertion_evidence_invalid");
+                const chunkIds = Array.isArray(props.source_chunk_ids) ? props.source_chunk_ids
+                    : relations.filter((relation) => relation.kind === "supports" && relation.dst === assertion.id).map((relation) => relation.src);
+                const chunks = chunkIds.map((chunkId) => byId.get(chunkId)).filter((item) => item !== undefined)
+                    .sort((left, right) => left.startOffset - right.startOffset);
+                const unique = [...new Map(chunks.map((item) => [item.evidenceId, item])).values()];
+                if (unique.length === 0 || unique.some((item) => item.documentId !== unique[0].documentId))
+                    continue;
+                // 新 semantic evidence 的 offsets 只是 envelope，聚合 quote 不能按 envelope 切原文。
+                // 仅旧式连续证据可直接使用顶层 span；新格式缺失 spans 不得降级误用 envelope。
+                const spans = semanticEvidenceSpans(proof);
+                if (spans.length === 0)
+                    continue;
+                const supportedIds = new Set();
+                const allSpansSupported = spans.every((value) => {
+                    const span = record(value, "assertion_evidence_span_invalid");
+                    if (typeof span.quote !== "string" || !Number.isSafeInteger(span.start_offset) || !Number.isSafeInteger(span.end_offset))
+                        return false;
+                    const start = span.start_offset;
+                    const end = span.end_offset;
+                    if (start < 0 || end <= start || end - start !== span.quote.length)
+                        return false;
+                    const overlapping = unique.filter((chunk) => chunk.startOffset < end && chunk.endOffset > start);
+                    if (overlapping.length === 0 || start < overlapping[0].startOffset || end > overlapping.at(-1).endOffset)
+                        return false;
+                    if (overlapping.some((chunk, index) => index > 0 && overlapping[index - 1].endOffset !== chunk.startOffset))
+                        return false;
+                    const sourceText = overlapping.map((chunk) => chunk.text).join("");
+                    if (sourceText.slice(start - overlapping[0].startOffset, end - overlapping[0].startOffset) !== span.quote)
+                        return false;
+                    for (const chunk of overlapping)
+                        supportedIds.add(chunk.evidenceId);
+                    return true;
+                });
+                if (allSpansSupported)
+                    for (const id of supportedIds)
+                        evidenceIds.add(id);
+            }
+            const physical = relations.find((relation) => relation.src === edge.src && relation.dst === edge.dst && relation.kind === edge.kind);
+            const qualifiers = physical?.props?.qualifiers;
+            return { ...edge, ...(qualifiers === undefined ? {} : { qualifiers: record(qualifiers, "relation_qualifiers_invalid") }), evidenceIds: [...evidenceIds] };
+        }) }));
+}
+function quoteRequirementsForPaths(paths, readbacks, evidence, options) {
+    const edgeKey = (edge) => JSON.stringify([edge.src, edge.dst, edge.kind]);
+    const relations = relationIndex(readbacks.flatMap((item) => item.relations));
+    const byId = new Map(evidence.map((item) => [item.evidenceId, item]));
+    return paths.map((path) => {
+        const hops = path.edges.map((edge) => {
+            const missing = (reason) => ({ src: edge.src, dst: edge.dst, kind: edge.kind, status: "missing",
+                required_quotes: [], missing_reason: reason });
+            const relation = relations.get(edgeKey(edge));
+            if (relation === undefined)
+                return missing("physical_edge_unavailable");
+            const props = record(relation.props, "readback_relation_props_invalid");
+            if (props.evidence === undefined)
+                return missing("canonical_proof_unavailable");
+            const proof = record(props.evidence, "assertion_evidence_invalid");
+            const sourceIds = Array.isArray(props.source_chunk_ids) ? props.source_chunk_ids : edge.evidenceIds ?? [];
+            // 与 graphPaths 共用同一精确 span 校验，不能凭命中 chunk 或 envelope 宣称 proof 可用。
+            const validated = supportedPaths([{ nodeIds: [edge.src, edge.dst], edges: [edge] }], [{ entities: [], relations: [{ ...relation,
+                            props: { ...props, source_chunk_ids: sourceIds } }] }], evidence)[0].edges[0].evidenceIds ?? [];
+            if (validated.length === 0)
+                return missing("proof_not_fully_in_evidence");
+            const required = new Map();
+            for (const value of semanticEvidenceSpans(proof)) {
+                const span = record(value, "assertion_evidence_span_invalid");
+                const start = span.start_offset, end = span.end_offset;
+                const covering = options.filter((option) => {
+                    const source = byId.get(option.evidenceId);
+                    return source !== undefined && validated.includes(option.evidenceId)
+                        && source.startOffset + option.start < end && source.startOffset + option.end > start;
+                }).sort((left, right) => byId.get(left.evidenceId).startOffset + left.start - byId.get(right.evidenceId).startOffset - right.start);
+                let cursor = start;
+                for (const option of covering) {
+                    const source = byId.get(option.evidenceId);
+                    if (source.startOffset + option.start > cursor)
+                        return missing("quote_option_coverage_gap");
+                    cursor = Math.max(cursor, source.startOffset + option.end);
+                    required.set(option.quoteId, { evidence_id: option.evidenceId, quote_id: option.quoteId });
+                }
+                if (cursor < end)
+                    return missing("quote_option_coverage_gap");
+            }
+            return { src: edge.src, dst: edge.dst, kind: edge.kind, status: "available", required_quotes: [...required.values()], missing_reason: null };
+        });
+        return { path_id: pathIdentifier(path),
+            usable: hops.every((hop) => hop.status === "available"), hops };
+    });
+}
+function answerCitations(value, evidence, options) {
+    if (typeof value.answerable !== "boolean" || (value.answer !== null && typeof value.answer !== "string") || !Array.isArray(value.citations))
+        return fail("answer_output_invalid");
+    if (!value.answerable)
+        return [];
+    if (typeof value.answer !== "string" || value.answer.trim().length === 0)
+        return fail("answer_text_invalid");
+    if (value.citations.length === 0 || value.citations.length > 32)
+        return fail("answer_citation_required");
+    const byId = new Map(evidence.map((item) => [item.evidenceId, item]));
+    const optionById = new Map(options.map((item) => [item.quoteId, item]));
+    return Object.freeze(value.citations.map((entry) => {
+        const citation = record(entry, "citation_invalid");
+        const evidenceId = identifier(citation.evidence_id, "citation_id_invalid");
+        const source = byId.get(evidenceId);
+        if (source === undefined)
+            return fail("citation_unknown");
+        const quoteId = identifier(citation.quote_id, "citation_quote_id_invalid");
+        if (Object.keys(citation).some((key) => key !== "evidence_id" && key !== "quote_id"))
+            return fail("citation_fields_invalid");
+        const option = optionById.get(quoteId);
+        if (option === undefined)
+            return fail("citation_quote_id_unknown");
+        if (option.evidenceId !== evidenceId)
+            return fail("citation_quote_evidence_mismatch");
+        const quote = source.text.slice(option.start, option.end);
+        if (quote.length === 0 || quote.length > MAX_QUOTE_CHARACTERS || quote !== option.text)
+            return fail("citation_quote_not_in_evidence");
+        return Object.freeze({ evidenceId, documentId: source.documentId, startOffset: source.startOffset, endOffset: source.endOffset, contentSha256: source.contentSha256, quote });
+    }));
+}
+const PLANNER_SCHEMA = Object.freeze({
+    type: "object",
+    additionalProperties: false,
+    required: ["search_queries"],
+    properties: {
+        search_queries: { type: "array", minItems: 1, maxItems: MAX_PLANNED_QUERIES, items: { type: "string" } },
+    },
+});
+const ANSWER_SCHEMA = Object.freeze({
+    type: "object",
+    additionalProperties: false,
+    required: ["answerable", "answer", "citations"],
+    properties: {
+        answerable: { type: "boolean" },
+        // 生产 closed-schema 子集不接受联合 type；wire 用空串表示不可回答，公开结果仍为 null。
+        answer: { type: "string" },
+        citations: { type: "array", maxItems: 32, items: { type: "object", additionalProperties: false, required: ["evidence_id", "quote_id"], properties: { evidence_id: { type: "string" }, quote_id: { type: "string" } } } },
+    },
+});
+const VERIFIER_SCHEMA = Object.freeze({
+    type: "object",
+    additionalProperties: false,
+    required: ["supported", "supported_quote_ids", "missing_premises", "unsupported_quote_ids", "answers_question", "proof_path_ids"],
+    properties: {
+        supported: { type: "boolean" },
+        answers_question: { type: "boolean" },
+        supported_quote_ids: { type: "array", maxItems: 32, items: { type: "string" } },
+        missing_premises: { type: "array", maxItems: 8, items: { type: "string", minLength: 1, maxLength: 256 } },
+        unsupported_quote_ids: { type: "array", maxItems: 32, items: { type: "string" } },
+    },
+});
+/**
+ * D4F 只负责制定有界检索计划和基于回读证据回答；图路径始终来自 exact-21 Host。
+ * 原始 source_document、rawBase64 与 generated context 永不进入模型 evidence。
+ */
+export async function answerDocumentQuestion(host, request, dependencies) {
+    if (typeof request.query !== "string" || request.query.trim().length === 0 || request.query.includes("\0") || request.query.normalize("NFC") !== request.query)
+        return fail("query_invalid");
+    const query = request.query;
+    if (query.length > MAX_QUERY_CHARACTERS)
+        return fail("query_too_long");
+    const scopeId = identifier(request.scopeId, "scope_invalid");
+    const maximumDepth = boundedInteger(request.maxDepth, DEFAULT_DEPTH, MAX_DEPTH, "depth_out_of_bounds");
+    const searchLimit = boundedInteger(request.searchLimit, DEFAULT_SEARCH_LIMIT, MAX_SEARCH_LIMIT, "search_limit_out_of_bounds");
+    const pathLimit = boundedInteger(request.pathLimit, DEFAULT_PATH_LIMIT, MAX_PATH_LIMIT, "path_limit_out_of_bounds");
+    const evidenceBudget = boundedInteger(request.evidenceCharacterBudget, DEFAULT_EVIDENCE_CHARACTERS, MAX_EVIDENCE_CHARACTERS, "evidence_budget_out_of_bounds");
+    if (dependencies.modelConnection.structuredJson.modelId !== REQUIRED_MODEL)
+        return fail("structured_model_forbidden");
+    const schema = record(await host.dispatchTool({ name: "world_schema", input: {} }), "schema_invalid");
+    if (!Array.isArray(schema.relation_kinds))
+        return fail("schema_relation_kinds_invalid");
+    const actualKinds = new Set(schema.relation_kinds.map((kind) => identifier(kind, "schema_relation_kind_invalid")));
+    const allowedRelationKinds = new Set(request.allowedRelationKinds ?? actualKinds);
+    if (request.allowedRelationKinds !== undefined && (allowedRelationKinds.size < 1 || allowedRelationKinds.size > 128))
+        return fail("allowed_relation_kinds_invalid");
+    for (const kind of allowedRelationKinds) {
+        identifier(kind, "allowed_relation_kind_invalid");
+        if (!actualKinds.has(kind))
+            return fail("allowed_relation_kind_unknown");
+    }
+    const trace = [];
+    const usages = [];
+    let plan;
+    let plannerFeedback;
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const previousUsage = dependencies.modelConnection.usage().byProviderModel?.find((usage) => usage.providerId === dependencies.modelConnection.structuredJson.providerId && usage.modelId === REQUIRED_MODEL);
+        try {
+            const plannerValue = await generate(dependencies.modelConnection, {
+                schemaName: "document_query_plan_v1",
+                jsonSchema: PLANNER_SCHEMA,
+                taskMode: "simulation_retrieval",
+                maxOutputTokens: 1_024,
+                messages: [
+                    { role: "system", content: "你是搜索计划器。只分解用户问题并返回少量 search_queries，不回答问题，不编造节点 ID，不选择图关系、方向或目标答案。保留用户措辞，可补充适合原文的别名或繁体关键词。关系与方向将在读回真实候选图后另行确定，当前不需要猜测。" },
+                    { role: "user", content: modelJson({ query, scope_id: scopeId, maximum_depth: maximumDepth,
+                            constraints: { search_queries: { min_items: 1, max_items: MAX_PLANNED_QUERIES, max_characters: 256 } },
+                            ...(plannerFeedback === undefined ? {} : { validation_error: plannerFeedback, instruction: "上次计划未通过校验。这是唯一一次修复机会；只修正具体约束错误，保留原始 query、scope 和来源，不复制候选列表、不降级或改写用户问题。" }),
+                        }) },
+                ],
+            }, dependencies.signal, usages);
+            plan = validatePlan(plannerValue, { maximumDepth, allowedRelationKinds }, true);
+            break;
+        }
+        catch (error) {
+            const providerOutputInvalid = error instanceof AuthoringModelConnectionError && error.code === "provider_response_invalid"
+                && (error.validationStage === "closed_schema" || error.validationStage === "response_parse" || error.validationStage === "response_shape");
+            const planInvalid = error instanceof Error && error.message.startsWith("document_query:planner_");
+            if (!providerOutputInvalid && !planInvalid)
+                throw error;
+            if (providerOutputInvalid) {
+                // factory 在输出校验前已累计 provider usage；不能漏算这次已付费的失败响应。
+                const currentUsage = dependencies.modelConnection.usage().byProviderModel?.find((usage) => usage.providerId === dependencies.modelConnection.structuredJson.providerId && usage.modelId === REQUIRED_MODEL);
+                if (currentUsage !== undefined && currentUsage.requests > (previousUsage?.requests ?? 0))
+                    usages.push({
+                        inputTokens: currentUsage.inputTokens - (previousUsage?.inputTokens ?? 0), outputTokens: currentUsage.outputTokens - (previousUsage?.outputTokens ?? 0),
+                        totalTokens: currentUsage.totalTokens - (previousUsage?.totalTokens ?? 0), requests: currentUsage.requests - (previousUsage?.requests ?? 0),
+                        cachedInputTokens: (currentUsage.cachedInputTokens ?? 0) - (previousUsage?.cachedInputTokens ?? 0),
+                    });
+                plannerFeedback = { code: error.code, stage: error.validationStage, issues: error.validationIssues };
+            }
+            else
+                plannerFeedback = { code: error.message };
+            trace.push(Object.freeze({ stage: "plan", detail: { attempt: attempt + 1, validationError: plannerFeedback } }));
+            if (attempt === 1)
+                throw error;
+        }
+    }
+    if (plan === undefined)
+        return fail("planner_output_invalid");
+    trace.push(Object.freeze({ stage: "plan", detail: { phase: "search", queries: plan.search_queries } }));
+    const seedIds = new Set();
+    const hitKinds = new Map();
+    const seedScores = new Map();
+    for (const plannedQuery of plan.search_queries) {
+        const hits = searchHits(await host.dispatchTool({
+            name: "world_search",
+            input: { query: plannedQuery, mode: "hybrid", limit: searchLimit, filters: { scope_id: scopeId } },
+        }), scopeId);
+        for (const [rank, hit] of hits.slice(0, searchLimit).entries()) {
+            if (hit.kind !== "world_source_document" && hit.kind !== "source_document") {
+                seedIds.add(hit.id);
+                hitKinds.set(hit.id, hit.kind);
+                seedScores.set(hit.id, (seedScores.get(hit.id) ?? 0) + 1 / (rank + 1));
+            }
+        }
+        trace.push(Object.freeze({ stage: "search", detail: { query: plannedQuery, seedIds: hits.map((hit) => hit.id), channels: hits.map((hit) => hit.channels) } }));
+    }
+    if (seedIds.size === 0) {
+        return Object.freeze({ answerable: false, answer: null, citations: Object.freeze([]), graphPaths: Object.freeze([]), retrievalTrace: Object.freeze(trace), usage: usageTotal(usages, dependencies.modelConnection.structuredJson.providerId, REQUIRED_MODEL) });
+    }
+    if (seedIds.size > searchLimit * plan.search_queries.length)
+        return fail("seed_limit_exceeded");
+    const seedReadback = await readGraph(host, seedIds, scopeId);
+    const sourceSeedIds = new Set([...hitKinds].filter(([, kind]) => kind === "world_source_chunk" || kind === "source_chunk").map(([id]) => id));
+    const seedAssertions = await readGraph(host, assertionIds([seedReadback], sourceSeedIds), scopeId);
+    const semanticIds = semanticSeeds([seedReadback, seedAssertions], hitKinds);
+    const refined = await refineRoute(host, { query, scopeId, seedIds: semanticIds, allowedKinds: allowedRelationKinds, maximumDepth,
+        pathLimit, startLimit: searchLimit, searchQueries: plan.search_queries }, dependencies, usages, trace);
+    const navigationPaths = refined.paths;
+    const rawPaths = refined.candidates;
+    const navigationPathIds = navigationPaths.map(pathIdentifier);
+    trace.push(Object.freeze({ stage: "traverse", detail: { authority: "world_get_physical_relations", nativeTraverseCalled: false,
+            phase: "navigation_paths", selectedPathIds: navigationPathIds, pathCount: navigationPaths.length, paths: navigationPaths,
+            truncated: refined.truncated, candidateTruncated: refined.truncated, exhaustive: !refined.truncated } }));
+    const readbackIds = new Set([...seedIds, ...rawPaths.flatMap((path) => path.nodeIds)]);
+    const pathReadback = await readGraph(host, readbackIds, scopeId);
+    const legacyPathIds = new Set(rawPaths.flatMap((path) => path.edges.flatMap((edge) => {
+        const relation = pathReadback.relations.find((item) => item.src === edge.src && item.dst === edge.dst && item.kind === edge.kind);
+        return relation !== undefined && Array.isArray(relation.props?.source_chunk_ids) ? [] : [edge.src, edge.dst];
+    })));
+    const pathAssertions = await readGraph(host, assertionIds([pathReadback], legacyPathIds), scopeId);
+    const readbacks = [seedReadback, seedAssertions, ...refined.readbacks, pathReadback, pathAssertions];
+    const rankedChunkIds = rankedSourceChunkIds(readbacks, seedScores, navigationPaths, rawPaths);
+    const chunkIds = new Set(rankedChunkIds);
+    const chunksReadback = await readGraph(host, chunkIds, scopeId);
+    readbacks.push(chunksReadback);
+    const allIds = new Set([...readbackIds, ...chunkIds, ...readbacks.flatMap((item) => item.entities.map((entity) => entity.id))]);
+    const uniqueEntities = [...new Map([...chunksReadback.entities, ...readbacks.flatMap((item) => item.entities)].map((entity) => [entity.id, entity])).values()];
+    const evidenceById = new Map(evidenceFromReadback({ entities: uniqueEntities }, allIds, scopeId).map((item) => [item.evidenceId, item]));
+    const rankedEvidence = rankedChunkIds.flatMap((id) => {
+        const item = evidenceById.get(id);
+        return item === undefined ? [] : [item];
+    });
+    const evidence = budgetEvidence(rankedEvidence, evidenceBudget);
+    const paths = supportedPaths(rawPaths, readbacks, evidence);
+    trace.push(Object.freeze({ stage: "readback", detail: { requestedIds: [...allIds], sourceChunkIds: [...chunkIds], evidenceIds: evidence.map((item) => item.evidenceId),
+            droppedEvidenceIds: rankedEvidence.filter((item) => !evidence.includes(item)).map((item) => item.evidenceId),
+            supportedHopCount: paths.reduce((sum, path) => sum + path.edges.filter((edge) => (edge.evidenceIds?.length ?? 0) > 0).length, 0),
+            usedCharacters: evidence.reduce((sum, item) => sum + item.text.length, 0) } }));
+    if (evidence.length === 0) {
+        return Object.freeze({ answerable: false, answer: null, citations: Object.freeze([]), graphPaths: [], retrievalTrace: Object.freeze(trace), usage: usageTotal(usages, dependencies.modelConnection.structuredJson.providerId, REQUIRED_MODEL) });
+    }
+    const options = quoteOptions(evidence);
+    const evidencePayload = evidence.map(({ evidenceId, documentId, startOffset, endOffset, contentSha256 }) => ({ evidence_id: evidenceId, document_id: documentId,
+        start_offset: startOffset, end_offset: endOffset, content_sha256: contentSha256,
+        quote_options: options.filter((option) => option.evidenceId === evidenceId).map(({ quoteId, text }) => ({ quote_id: quoteId, text })) }));
+    const pathQuoteRequirements = quoteRequirementsForPaths(paths, readbacks, evidence, options);
+    const availablePathIds = new Set(pathQuoteRequirements.filter((path) => path.usable).map((path) => path.path_id));
+    const availablePaths = paths.filter((path) => availablePathIds.has(pathIdentifier(path)));
+    const availableById = new Map(availablePaths.map((path) => [pathIdentifier(path), path]));
+    const allRelations = [...relationIndex(readbacks.flatMap((item) => item.relations)).values()];
+    const proofSelectionLimit = Math.min(searchLimit, MAX_PLANNED_RELATIONS);
+    trace.push({ stage: "readback", detail: { phase: "path_quote_requirements", usablePathIds: pathQuoteRequirements.filter((path) => path.usable).map((path) => path.path_id),
+            missingPathIds: pathQuoteRequirements.filter((path) => !path.usable).map((path) => path.path_id) } });
+    let answerValue = { answerable: false, answer: null, citations: [] };
+    let citations = [];
+    let proofPaths = [];
+    let proofPathIds = [];
+    let repairFeedback;
+    const providerUsage = () => dependencies.modelConnection.usage().byProviderModel?.find((usage) => usage.providerId === dependencies.modelConnection.structuredJson.providerId && usage.modelId === REQUIRED_MODEL);
+    const structuredAttempt = async (modelRequest) => {
+        const before = providerUsage();
+        try {
+            return { value: await generate(dependencies.modelConnection, modelRequest, dependencies.signal, usages) };
+        }
+        catch (error) {
+            const invalid = error instanceof AuthoringModelConnectionError && error.code === "provider_response_invalid"
+                && (error.validationStage === "closed_schema" || error.validationStage === "response_parse" || error.validationStage === "response_shape");
+            if (!invalid)
+                throw error;
+            // factory 已消费但闭 schema 拒绝的响应也计入真实 usage，不能只计算被接受的 value。
+            const after = providerUsage();
+            if (after !== undefined && after.requests > (before?.requests ?? 0))
+                usages.push({
+                    inputTokens: after.inputTokens - (before?.inputTokens ?? 0), outputTokens: after.outputTokens - (before?.outputTokens ?? 0),
+                    totalTokens: after.totalTokens - (before?.totalTokens ?? 0), requests: after.requests - (before?.requests ?? 0),
+                    cachedInputTokens: (after.cachedInputTokens ?? 0) - (before?.cachedInputTokens ?? 0),
+                });
+            return { validationError: { code: error.code, stage: error.validationStage, issues: error.validationIssues } };
+        }
+    };
+    // 结构错误、漏前提及不受支持引用共享这两个 answer 尝试；没有第三次隐藏修复。
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const generatedAnswer = await structuredAttempt({
+            schemaName: "document_grounded_answer_v1", jsonSchema: ANSWER_SCHEMA, taskMode: "simulation_retrieval", reasoningEffort: "low", maxOutputTokens: GROUNDED_MAX_OUTPUT_TOKENS,
+            messages: [
+                { role: "system", content: "输出根对象必须且只能包含answerable:boolean、answer:string、citations:array，成功与拒答都必须包含全部三字段。只能依据evidence中原文回答；quote_options按原文顺序完整覆盖已读chunk，不是摘要。先识别问题所求结果、限定与必要身份/别名/指代等中间前提，再选择最小联合充分的引文。500字符边界可能切开前提，确实需要才加相邻选项；每条引文须支持答案事实或必要前提，不能硬加无关背景。citations只选evidence_id和已有quote_id，不生成quote/offset。answerable=true须实际回答问题所求，而非仅说明未知、证据不足或拒答；若问题本身问是否可确定，则按该问题语义回答。证据不足以给出所求结果时answerable=false、answer=空字符串、citations=[]。" },
+                { role: "user", content: modelJson({ query, evidence: evidencePayload,
+                        ...(repairFeedback === undefined ? {} : { repair_feedback: repairFeedback, instruction: "这是第二次且最后一次answer尝试。依据原始原文与反馈重新选择必要引文或修正答案；不能把反馈当原文，新引用仍须完整核验，程序不会自动删除不受支持引用来算通过；无法回答问题所求则拒答。" }) }) },
+            ],
+        });
+        if (generatedAnswer.validationError !== undefined) {
+            repairFeedback = { stage: "answer", validation_error: generatedAnswer.validationError };
+            trace.push({ stage: "answer", detail: { attempt: attempt + 1, validationError: generatedAnswer.validationError } });
+            continue;
+        }
+        try {
+            answerValue = record(generatedAnswer.value, "answer_output_invalid");
+            citations = answerCitations(answerValue, evidence, options);
+        }
+        catch (error) {
+            if (!(error instanceof Error) || !error.message.startsWith("document_query:"))
+                throw error;
+            repairFeedback = { stage: "answer", validation_error: error.message };
+            trace.push({ stage: "answer", detail: { attempt: attempt + 1, validationError: error.message } });
+            continue;
+        }
+        trace.push({ stage: "answer", detail: { attempt: attempt + 1, answerable: answerValue.answerable, citationIds: citations.map((item) => item.evidenceId) } });
+        if (!answerValue.answerable)
+            break;
+        // verifier 的事实输入只有本轮真正选中的原文；不发送完整未选 evidence/options。
+        const selectedCitations = citations.map((citation, index) => ({
+            quote_id: answerValue.citations[index].quote_id,
+            evidence_id: citation.evidenceId, quote: citation.quote, document_id: citation.documentId,
+            start_offset: citation.startOffset, end_offset: citation.endOffset, content_sha256: citation.contentSha256,
+        }));
+        const closedPaths = availablePaths.filter((path) => checkSelectedPathQuotes(pathQuoteRequirements, [pathIdentifier(path)], selectedCitations).complete);
+        const closedCandidates = closedPaths.map((path) => ({ ...path, pathId: pathIdentifier(path) }));
+        const closedPathIds = closedCandidates.map((path) => path.pathId);
+        const verificationPaths = renderedPaths(closedPaths, uniqueEntities, allRelations);
+        const verifierSchema = { ...VERIFIER_SCHEMA, properties: { ...VERIFIER_SCHEMA.properties, proof_path_ids: {
+                    type: "array", minItems: 0, maxItems: closedPathIds.length === 0 ? 0 : proofSelectionLimit,
+                    items: { type: "string", ...(closedPathIds.length === 0 ? {} : { enum: closedPathIds }) },
+                } } };
+        trace.push({ stage: "verify", detail: { phase: "closed_proof_candidates", attempt: attempt + 1, closedPathIds,
+                availablePathCount: availablePaths.length, closedPathCount: closedPaths.length, candidateTruncated: refined.truncated } });
+        const generatedVerifier = await structuredAttempt({
+            schemaName: "document_grounded_verifier_v1", jsonSchema: verifierSchema, taskMode: "simulation_retrieval", reasoningEffort: "low", maxOutputTokens: GROUNDED_MAX_OUTPUT_TOKENS,
+            messages: [
+                { role: "system", content: "按问题要求和答案实际断言的粒度核验，不得追加更细粒度的必要条件；答案自行增加的名称、数值或身份细节仍须逐项有原文支持。分别判断supported（原文是否支持答案断言）与answers_question（答案是否实际给出了query所求结果）；有据的未知/拒答陈述不等于回答了事实问题，但query本身若问是否可确定则按其语义判断，不能按词表判定。只能联合使用当前citations逐字quote，不得凭外部知识、图标签或上轮结果补前提。每条引文须支持答案事实或必要中间前提，不要求每条引文独立包含最终答案；核对身份、别名、指代、方向、否定、时间、归属。proof_path_options仅列当前引文已逐跳机械覆盖的真实路径，不代表与问题相关；选择其中实际连接问题锚点、必要前提与答案的完整路径ID到proof_path_ids，不要自动选全部、不要选无关背景。多关系问题有对应完整链时应选完整证明而非尾段；若只有原文直接证明且无相关路径，proof_path_ids=[]。相同标签不同ref不能拼接。supported_quote_ids与unsupported_quote_ids只能来自当前quote_id且不重复交叉；missing_premises仅简述真正缺失的必要前提，不编造事实或引文。所有选中引文均有支持时才能supported=true，不能仅删掉不支持的ID就当全部通过。" },
+                { role: "user", content: modelJson({ query, answer: answerValue.answer, citations: selectedCitations,
+                        proof_path_options: verificationPaths, graph_authority: "navigation_only_not_fact_evidence" }) },
+            ],
+        });
+        if (generatedVerifier.validationError !== undefined) {
+            repairFeedback = { stage: "verify", validation_error: generatedVerifier.validationError, previous_answer: answerValue.answer, previous_citations: answerValue.citations };
+            trace.push({ stage: "verify", detail: { attempt: attempt + 1, supported: false, validationError: generatedVerifier.validationError } });
+            continue;
+        }
+        const verifierValue = record(generatedVerifier.value, "verifier_output_invalid");
+        if (typeof verifierValue.supported !== "boolean" || typeof verifierValue.answers_question !== "boolean" || !Array.isArray(verifierValue.supported_quote_ids)
+            || !Array.isArray(verifierValue.unsupported_quote_ids) || !Array.isArray(verifierValue.missing_premises))
+            return fail("verifier_output_invalid");
+        if (verifierValue.supported_quote_ids.length > selectedCitations.length || verifierValue.unsupported_quote_ids.length > selectedCitations.length)
+            return fail("verifier_quotes_invalid");
+        const supportedQuoteIds = verifierValue.supported_quote_ids.map((id) => identifier(id, "verifier_quotes_invalid"));
+        const unsupportedQuoteIds = verifierValue.unsupported_quote_ids.map((id) => identifier(id, "verifier_quotes_invalid"));
+        const selectedQuoteIds = new Set(selectedCitations.map((citation) => citation.quote_id));
+        if ([...supportedQuoteIds, ...unsupportedQuoteIds].some((id) => !selectedQuoteIds.has(id)))
+            return fail("verifier_quote_unknown");
+        if (new Set([...supportedQuoteIds, ...unsupportedQuoteIds]).size !== supportedQuoteIds.length + unsupportedQuoteIds.length)
+            return fail("verifier_quotes_invalid");
+        const missingPremises = verifierValue.missing_premises;
+        if (missingPremises.length > 8 || missingPremises.some((value) => typeof value !== "string" || value.trim().length === 0 || value.length > 256))
+            return fail("verifier_feedback_invalid");
+        const requestedProofIds = Array.isArray(verifierValue.proof_path_ids) && verifierValue.proof_path_ids.length === 0 ? []
+            : stringArray(verifierValue.proof_path_ids, "verifier_proof_path_ids_invalid", proofSelectionLimit);
+        const canonical = canonicalizeSelectedProofPaths(closedCandidates, requestedProofIds);
+        proofPathIds = canonical.canonicalPathIds;
+        proofPaths = proofPathIds.map((id) => availableById.get(id));
+        const pathProof = checkSelectedPathQuotes(pathQuoteRequirements, proofPathIds, selectedCitations);
+        trace.push({ stage: "verify", detail: { phase: "proof_path_selection", attempt: attempt + 1, requestedProofPathIds: requestedProofIds,
+                canonicalProofPathIds: proofPathIds, mapping: canonical.mapping, ...pathProof } });
+        const supported = verifierValue.supported && verifierValue.answers_question && pathProof.complete && missingPremises.length === 0 && unsupportedQuoteIds.length === 0
+            && selectedCitations.every((citation) => supportedQuoteIds.includes(citation.quote_id));
+        const supportedIds = [...new Set(selectedCitations.filter((citation) => supportedQuoteIds.includes(citation.quote_id)).map((citation) => citation.evidence_id))];
+        trace.push({ stage: "verify", detail: { attempt: attempt + 1, supported, answersQuestion: verifierValue.answers_question,
+                supportedCitationIds: supportedIds, supportedQuoteIds, missingPremises, unsupportedQuoteIds } });
+        if (supported)
+            return Object.freeze({ answerable: true, answer: answerValue.answer, citations, graphPaths: proofPaths,
+                retrievalTrace: Object.freeze(trace), usage: usageTotal(usages, dependencies.modelConnection.structuredJson.providerId, REQUIRED_MODEL) });
+        repairFeedback = { stage: "verify", supported: false, reason: verifierValue.answers_question ? "unsupported" : "not_answered", answers_question: verifierValue.answers_question, missing_premises: missingPremises,
+            unsupported_quote_ids: [...new Set([...unsupportedQuoteIds, ...selectedCitations.filter((citation) => !supportedQuoteIds.includes(citation.quote_id)).map((citation) => citation.quote_id)])],
+            supported_quote_ids: supportedQuoteIds, previous_answer: answerValue.answer, previous_citations: answerValue.citations };
+    }
+    return Object.freeze({ answerable: false, answer: null, citations: Object.freeze([]), graphPaths: [],
+        retrievalTrace: Object.freeze(trace), usage: usageTotal(usages, dependencies.modelConnection.structuredJson.providerId, REQUIRED_MODEL) });
+}