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

package/dist/document-query-path-proof.d.ts

@@ -0,0 +1,30 @@
+export interface DocumentQueryQuoteReference {
+    readonly evidence_id: string;
+    readonly quote_id: string;
+}
+export interface DocumentQueryPathProofRequirement {
+    readonly path_id: string;
+    readonly usable: boolean;
+    readonly hops: readonly Readonly<{
+        src: string;
+        dst: string;
+        kind: string;
+        status: "available" | "missing";
+        required_quotes: readonly DocumentQueryQuoteReference[];
+        missing_reason: string | null;
+    }>[];
+}
+export interface SelectedPathQuotesCheck {
+    readonly complete: boolean;
+    /** 所选但未闭合的路径，包含缺引文或上游判定不可用的路径。 */
+    readonly missingPathIds: readonly string[];
+    readonly missingQuotes: readonly Readonly<DocumentQueryQuoteReference & {
+        path_id: string;
+    }>[];
+    readonly unavailablePathIds: readonly string[];
+}
+/**
+ * 只核对本轮选择与上游已经算好的逐跳引文要求，不推断关系语义，也不重算 span／offset。
+ * 同一 chunk 的另一 quote、或相同 quote ID 对应的另一 evidence，都不能替代要求的精确引用对。
+ */
+export declare function checkSelectedPathQuotes(requirements: readonly DocumentQueryPathProofRequirement[], selectedPathIds: readonly string[], selectedCitations: readonly DocumentQueryQuoteReference[]): SelectedPathQuotesCheck;

package/dist/document-query-path-proof.js

@@ -0,0 +1,34 @@
+/**
+ * 只核对本轮选择与上游已经算好的逐跳引文要求，不推断关系语义，也不重算 span／offset。
+ * 同一 chunk 的另一 quote、或相同 quote ID 对应的另一 evidence，都不能替代要求的精确引用对。
+ */
+export function checkSelectedPathQuotes(requirements, selectedPathIds, selectedCitations) {
+    const byId = new Map(requirements.map((requirement) => [requirement.path_id, requirement]));
+    const selectedIds = [...new Set(selectedPathIds)];
+    for (const id of selectedIds)
+        if (!byId.has(id))
+            throw new Error("document_query:selected_path_unknown");
+    const pairKey = (quote) => JSON.stringify([quote.evidence_id, quote.quote_id]);
+    const citedPairs = new Set(selectedCitations.map(pairKey));
+    const missingPathIds = [];
+    const unavailablePathIds = [];
+    const missingQuotes = [];
+    for (const pathId of selectedIds) {
+        const path = byId.get(pathId);
+        const unavailable = !path.usable || path.hops.length === 0 || path.hops.some((hop) => hop.status !== "available" || hop.required_quotes.length === 0);
+        const missingPairs = new Map();
+        for (const hop of path.hops)
+            for (const quote of hop.required_quotes) {
+                const key = pairKey(quote);
+                if (!citedPairs.has(key))
+                    missingPairs.set(key, quote);
+            }
+        if (unavailable)
+            unavailablePathIds.push(pathId);
+        if (unavailable || missingPairs.size > 0)
+            missingPathIds.push(pathId);
+        for (const quote of missingPairs.values())
+            missingQuotes.push({ path_id: pathId, evidence_id: quote.evidence_id, quote_id: quote.quote_id });
+    }
+    return { complete: missingPathIds.length === 0, missingPathIds, missingQuotes, unavailablePathIds };
+}

package/dist/document-query-path-renderer.d.ts

@@ -0,0 +1,50 @@
+/** 给模型的路径展示只消费已验证物理图；不生成关系、证据或路径候选。 */
+export type DocumentQueryRenderEntity = Readonly<{
+    id: string;
+    kind: string;
+    props: Readonly<Record<string, unknown>>;
+}>;
+export type DocumentQueryRenderRelation = Readonly<{
+    src: string;
+    dst: string;
+    kind: string;
+    props: Readonly<Record<string, unknown>>;
+}>;
+export type DocumentQueryRenderPath = Readonly<{
+    pathId: string;
+    nodeIds: readonly string[];
+    edges: readonly Readonly<{
+        src: string;
+        dst: string;
+        kind: string;
+    }>[];
+}>;
+export type DocumentQueryRenderedEndpoint = Readonly<{
+    ref: string;
+    label: string | null;
+    kind: string;
+    label_truncated?: true;
+}>;
+export type DocumentQueryRenderedHop = Readonly<{
+    /** 始终为物理边的 source → target，不能因路径逆向行走而互换。 */
+    source: DocumentQueryRenderedEndpoint;
+    target: DocumentQueryRenderedEndpoint;
+    kind: string;
+    assertion: string | null;
+    /** 只透传实际物理关系限定；不从 kind 前缀推断否定。 */
+    qualifiers?: unknown;
+    assertion_truncated?: true;
+    walk_direction: "forward" | "reverse";
+}>;
+export type DocumentQueryRenderedPathOption = Readonly<{
+    path_id: string;
+    hops: readonly DocumentQueryRenderedHop[];
+}>;
+/** 输出替换旧 nodes/edges 平行表；每一跳独立含端点与实际断言，局部 ref 按物理 ID 分配。 */
+export declare function renderDocumentQueryPathOptions(input: Readonly<{
+    paths: readonly DocumentQueryRenderPath[];
+    entities: ReadonlyMap<string, DocumentQueryRenderEntity>;
+    relations: readonly DocumentQueryRenderRelation[];
+}>): Readonly<{
+    path_options: readonly DocumentQueryRenderedPathOption[];
+}>;

package/dist/document-query-path-renderer.js

@@ -0,0 +1,75 @@
+// 仅限制展示字段；候选数量、深度与 path identity 由 query owner 验证。
+const LABEL_UTF16_LIMIT = 256;
+const ASSERTION_UTF16_LIMIT = 512;
+function fail(code) {
+    throw new Error(`document_query_path_renderer:${code}`);
+}
+function relationKey(relation) {
+    return JSON.stringify([relation.src, relation.dst, relation.kind]);
+}
+/** 保留原字符与换行，不在高低 surrogate 中间截断，也不伪造省略后的尾部事实。 */
+function displayText(value, maximum) {
+    if (typeof value !== "string")
+        return { text: null, truncated: false };
+    let text = "";
+    for (const character of value) {
+        if (text.length + character.length > maximum)
+            return { text, truncated: true };
+        text += character;
+    }
+    return { text, truncated: false };
+}
+/** 输出替换旧 nodes/edges 平行表；每一跳独立含端点与实际断言，局部 ref 按物理 ID 分配。 */
+export function renderDocumentQueryPathOptions(input) {
+    const references = new Map();
+    const pathIds = new Set();
+    for (const path of input.paths) {
+        if (path.pathId.length === 0 || pathIds.has(path.pathId))
+            fail("path_identity_invalid");
+        pathIds.add(path.pathId);
+        if (path.edges.length === 0 || path.nodeIds.length !== path.edges.length + 1)
+            fail("path_shape_invalid");
+        for (const nodeId of path.nodeIds)
+            if (!references.has(nodeId))
+                references.set(nodeId, `n${references.size}`);
+    }
+    const actualRelations = new Map();
+    for (const relation of input.relations) {
+        const key = relationKey(relation);
+        if (actualRelations.has(key))
+            fail("duplicate_physical_relation");
+        actualRelations.set(key, relation);
+    }
+    const endpoints = new Map();
+    const endpoint = (nodeId) => {
+        const cached = endpoints.get(nodeId);
+        if (cached !== undefined)
+            return cached;
+        const actual = input.entities.get(nodeId);
+        const ref = references.get(nodeId);
+        if (actual === undefined || actual.id !== nodeId || ref === undefined)
+            return fail("physical_endpoint_missing");
+        const label = displayText(actual.props.label, LABEL_UTF16_LIMIT);
+        const rendered = Object.freeze({ ref, label: label.text, kind: actual.kind,
+            ...(label.truncated ? { label_truncated: true } : {}) });
+        endpoints.set(nodeId, rendered);
+        return rendered;
+    };
+    const options = input.paths.map((path) => {
+        const hops = path.edges.map((edge, index) => {
+            const actual = actualRelations.get(relationKey(edge));
+            if (actual === undefined)
+                return fail("physical_relation_missing");
+            const from = path.nodeIds[index];
+            const to = path.nodeIds[index + 1];
+            const walkDirection = edge.src === from && edge.dst === to ? "forward"
+                : edge.dst === from && edge.src === to ? "reverse" : fail("path_physical_discontinuity");
+            const assertion = displayText(actual.props.assertion, ASSERTION_UTF16_LIMIT);
+            return Object.freeze({ source: endpoint(actual.src), target: endpoint(actual.dst), kind: actual.kind,
+                assertion: assertion.text, ...(actual.props.qualifiers === undefined ? {} : { qualifiers: actual.props.qualifiers }),
+                ...(assertion.truncated ? { assertion_truncated: true } : {}), walk_direction: walkDirection });
+        });
+        return Object.freeze({ path_id: path.pathId, hops: Object.freeze(hops) });
+    });
+    return Object.freeze({ path_options: Object.freeze(options) });
+}

package/dist/document-query-proof-paths.d.ts

@@ -0,0 +1,22 @@
+export interface ProofPathCandidate {
+    readonly pathId: string;
+    readonly nodeIds: readonly string[];
+    readonly edges: readonly Readonly<{
+        src: string;
+        dst: string;
+        kind: string;
+    }>[];
+}
+export interface CanonicalSelectedProofPaths {
+    readonly canonicalPathIds: readonly string[];
+    readonly canonicalPaths: readonly ProofPathCandidate[];
+    readonly mapping: readonly Readonly<{
+        selectedPathId: string;
+        canonicalPathIds: readonly string[];
+    }>[];
+}
+/**
+ * 候选已由上游绑定 source/scope、depth/path 预算及证据；这里不读图、不扩预算、不生成路径。
+ * 只以当前明确选中的物理边替换为候选中已有的完整路径，之后仍须重新做逐跳 quote 校验。
+ */
+export declare function canonicalizeSelectedProofPaths(candidates: readonly ProofPathCandidate[], selectedPathIds: readonly string[]): CanonicalSelectedProofPaths;

package/dist/document-query-proof-paths.js

@@ -0,0 +1,71 @@
+function edgeKey(edge) {
+    return JSON.stringify([edge.src, edge.dst, edge.kind]);
+}
+function simpleConnected(path) {
+    return path.nodeIds.length >= 2 && path.edges.length === path.nodeIds.length - 1
+        && new Set(path.nodeIds).size === path.nodeIds.length
+        && path.edges.every((edge, index) => (edge.src === path.nodeIds[index] && edge.dst === path.nodeIds[index + 1])
+            || (edge.dst === path.nodeIds[index] && edge.src === path.nodeIds[index + 1]));
+}
+/** 可反向遍历同一片段，但绝不改写每条物理边的 src/dst/kind。 */
+function containsFragment(container, fragment) {
+    if (fragment.nodeIds.length > container.nodeIds.length)
+        return false;
+    for (let start = 0; start <= container.nodeIds.length - fragment.nodeIds.length; start += 1) {
+        for (const reverse of [false, true]) {
+            if (!fragment.nodeIds.every((_id, index) => container.nodeIds[start + index]
+                === fragment.nodeIds[reverse ? fragment.nodeIds.length - 1 - index : index]))
+                continue;
+            if (fragment.edges.every((_edge, index) => edgeKey(container.edges[start + index])
+                === edgeKey(fragment.edges[reverse ? fragment.edges.length - 1 - index : index])))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * 候选已由上游绑定 source/scope、depth/path 预算及证据；这里不读图、不扩预算、不生成路径。
+ * 只以当前明确选中的物理边替换为候选中已有的完整路径，之后仍须重新做逐跳 quote 校验。
+ */
+export function canonicalizeSelectedProofPaths(candidates, selectedPathIds) {
+    const byId = new Map(candidates.map((path) => [path.pathId, path]));
+    if (byId.size !== candidates.length)
+        throw new Error("document_query:proof_path_candidates_invalid");
+    const selected = [...new Set(selectedPathIds)].map((id) => {
+        const path = byId.get(id);
+        if (path === undefined)
+            throw new Error("document_query:selected_path_unknown");
+        if (!simpleConnected(path))
+            throw new Error("document_query:selected_path_invalid");
+        return path;
+    });
+    const selectedEdges = new Set(selected.flatMap((path) => path.edges.map(edgeKey)));
+    const promotions = candidates.flatMap((path, candidateIndex) => {
+        if (!simpleConnected(path) || path.edges.some((edge) => !selectedEdges.has(edgeKey(edge))))
+            return [];
+        const fragments = selected.filter((fragment) => containsFragment(path, fragment));
+        if (!fragments.some((fragment) => fragment.edges.length < path.edges.length))
+            return [];
+        return [{ path, fragments, candidateIndex }];
+    }).sort((left, right) => right.path.edges.length - left.path.edges.length
+        || right.fragments.length - left.fragments.length || left.candidateIndex - right.candidateIndex);
+    const covered = new Set();
+    const canonicalPaths = [];
+    for (const promotion of promotions) {
+        // 每条输出必须新覆盖至少一个已选片段，故不会增加已选路径总数。
+        if (!promotion.fragments.some((path) => !covered.has(path.pathId)))
+            continue;
+        canonicalPaths.push(promotion.path);
+        for (const fragment of promotion.fragments)
+            covered.add(fragment.pathId);
+    }
+    for (const path of selected)
+        if (!covered.has(path.pathId))
+            canonicalPaths.push(path);
+    return {
+        canonicalPathIds: canonicalPaths.map((path) => path.pathId),
+        canonicalPaths,
+        mapping: selected.map((path) => ({ selectedPathId: path.pathId,
+            canonicalPathIds: canonicalPaths.filter((canonical) => containsFragment(canonical, path)).map((canonical) => canonical.pathId) })),
+    };
+}

package/dist/document-query.d.ts

@@ -0,0 +1,97 @@
+import type { AuthoringToolCall } from "@world-engines/authoring-bridge";
+import type { AuthoringModelConnection, AuthoringModelUsage } from "./authoring-model-connection.js";
+export interface DocumentQueryHost {
+    dispatchTool(call: AuthoringToolCall): Promise<unknown>;
+}
+export interface DocumentQuestionRequest {
+    readonly query: string;
+    readonly scopeId: string;
+    readonly maxDepth?: number;
+    readonly searchLimit?: number;
+    readonly pathLimit?: number;
+    readonly evidenceCharacterBudget?: number;
+    /** Planner 只能从此集合选择关系；缺省使用 world_schema 的实际语义关系。 */
+    readonly allowedRelationKinds?: readonly string[];
+}
+export interface DocumentCitation {
+    readonly evidenceId: string;
+    readonly documentId: string;
+    readonly startOffset: number;
+    readonly endOffset: number;
+    readonly contentSha256: string;
+    readonly quote: string;
+}
+export interface DocumentGraphEdge {
+    readonly src: string;
+    readonly dst: string;
+    readonly kind: string;
+    /** 原始限定词；parent_of 加 negation:true 不是正向家长事实。 */
+    readonly qualifiers?: Readonly<Record<string, unknown>>;
+    readonly evidenceIds?: readonly string[];
+}
+export interface DocumentGraphPath {
+    readonly nodeIds: readonly string[];
+    readonly edges: readonly DocumentGraphEdge[];
+}
+export interface DocumentRetrievalTraceEntry {
+    readonly stage: "plan" | "search" | "traverse" | "readback" | "answer" | "verify";
+    readonly detail: Readonly<Record<string, unknown>>;
+}
+export interface DocumentQuestionAnswer {
+    readonly answerable: boolean;
+    readonly answer: string | null;
+    readonly citations: readonly DocumentCitation[];
+    readonly graphPaths: readonly DocumentGraphPath[];
+    readonly retrievalTrace: readonly DocumentRetrievalTraceEntry[];
+    readonly usage: AuthoringModelUsage;
+}
+export interface DocumentQuestionDependencies {
+    readonly modelConnection: AuthoringModelConnection;
+    readonly signal?: AbortSignal;
+}
+export interface DocumentEvidenceRequest extends DocumentQuestionRequest {
+    /** 外部 harness 可提供自身规划结果；缺省时直接以原问题做一次 hybrid 检索。 */
+    readonly searchQueries?: readonly string[];
+    /** benchmark/离线诊断可显式选择 keyword；缺省仍是需要已准备真实向量的 hybrid。 */
+    readonly searchMode?: "keyword" | "hybrid";
+}
+export interface DocumentEvidenceBundle {
+    readonly query: string;
+    readonly scopeId: string;
+    readonly searchMode: "keyword" | "hybrid";
+    readonly candidates: readonly Readonly<{
+        id: string;
+        kind: string;
+        channels: readonly string[];
+        query: string;
+        rank: number;
+    }>[];
+    readonly graphPaths: readonly DocumentGraphPath[];
+    readonly pathOptions: readonly unknown[];
+    readonly evidence: readonly Readonly<Evidence>[];
+    readonly integrity: Readonly<{
+        sourceBinding: "verified" | "unavailable";
+        evidenceCoverage: "complete" | "partial" | "empty";
+        traversalTruncated: boolean;
+    }>;
+    readonly retrievalTrace: readonly DocumentRetrievalTraceEntry[];
+}
+type Evidence = Readonly<{
+    evidenceId: string;
+    documentId: string;
+    startOffset: number;
+    endOffset: number;
+    contentSha256: string;
+    text: string;
+}>;
+/**
+ * 外部 harness 的检索 seam：Host 只做 hybrid recall、物理图遍历、原文回读与完整性校验，
+ * 不调用 structured model，也不生成答案。结构理解、否定/时间推理由调用方基于 bundle 完成。
+ */
+export declare function retrieveDocumentEvidenceBundle(host: DocumentQueryHost, request: DocumentEvidenceRequest): Promise<DocumentEvidenceBundle>;
+/**
+ * D4F 只负责制定有界检索计划和基于回读证据回答；图路径始终来自 exact-21 Host。
+ * 原始 source_document、rawBase64 与 generated context 永不进入模型 evidence。
+ */
+export declare function answerDocumentQuestion(host: DocumentQueryHost, request: DocumentQuestionRequest, dependencies: DocumentQuestionDependencies): Promise<DocumentQuestionAnswer>;
+export {};