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

package/dist/ladybug-runtime.js

@@ -0,0 +1,886 @@
+import { mkdir, open as openFile, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { buildChineseLexicalIndexProfile, buildLegacyChineseLexicalIndexProfileV1, buildLegacyChineseLexicalIndexProfileV2, buildLegacyChineseLexicalIndexProfileV3, CHINESE_LEXICAL_PROFILE_VERSION, LEGACY_CHINESE_LEXICAL_PROFILE_VERSION, LEGACY_CHINESE_LEXICAL_PROFILE_V2_VERSION, LEGACY_CHINESE_LEXICAL_PROFILE_V3_VERSION, lexicalize, lexicalizeQuery, } from "./chinese-lexical.js";
+import { classifyDocumentRelationRole } from "./document-relation-role.js";
+const require = createRequire(import.meta.url);
+const STATE_FILE = "extracted-graph.v1.json";
+const ENTITY_TABLE = "ExtractedEntity";
+const RELATION_TABLE = "ExtractedRelation";
+const VECTOR_INDEX = "extracted_entity_vector_idx";
+const FTS_INDEX = "extracted_entity_fts_idx";
+export const LADYBUG_WORLD_FACT_QUERY_PROFILE_ID = "world-fact-query/zh-v1";
+export const DEFAULT_LADYBUG_MAX_VECTOR_DISTANCE = 0.5;
+/** 仅编码一条查询；corpus 向量由显式准备流程负责，不由该 seam 补齐。 */
+export async function embedLadybugQuery(port, text) {
+    nonEmpty(text, "queryText");
+    const result = await port.embed([text], { inputKind: "query" });
+    invariant(result.length === 1, "embedding provider 必须为每个 query 返回一个向量");
+    return validateVector(result[0], port.dimensions, "provider query embedding");
+}
+let ownedWorkerUsers = 0;
+let workerLifecycleTail = Promise.resolve();
+async function serializeWorkerLifecycle(operation) {
+    const prior = workerLifecycleTail;
+    let release;
+    workerLifecycleTail = new Promise((resolve) => { release = resolve; });
+    await prior;
+    try {
+        return await operation();
+    }
+    finally {
+        release();
+    }
+}
+async function acquireOwnedWorker(variant) {
+    await serializeWorkerLifecycle(async () => {
+        if (ownedWorkerUsers === 0)
+            await variant.init();
+        ownedWorkerUsers += 1;
+    });
+}
+async function releaseOwnedWorker(variant) {
+    await serializeWorkerLifecycle(async () => {
+        invariant(ownedWorkerUsers > 0, "Ladybug worker lifecycle 引用计数无效");
+        ownedWorkerUsers -= 1;
+        if (ownedWorkerUsers === 0)
+            await variant.close();
+    });
+}
+function invariant(condition, message) {
+    if (!condition)
+        throw new Error(message);
+}
+function nonEmpty(value, label) {
+    invariant(typeof value === "string" && value.trim().length > 0, `${label} 必须是非空 string`);
+}
+function validateVector(vector, dimensions, label) {
+    invariant(Array.isArray(vector), `${label} 必须是 number[]`);
+    invariant(vector.length === dimensions, `${label} 维度必须为 ${dimensions}`);
+    invariant(vector.every((value) => typeof value === "number" && Number.isFinite(value)), `${label} 必须只包含有限数`);
+    invariant(vector.some((value) => value !== 0), `${label} 不得为零向量`);
+    return [...vector];
+}
+function validateSource(source) {
+    nonEmpty(source.sourceId, "source.sourceId");
+    invariant(/^[a-f\d]{64}$/iu.test(source.contentSha256), "source.contentSha256 必须是 SHA-256 hex");
+    invariant(Number.isSafeInteger(source.extractedAtMs) && source.extractedAtMs >= 0, "source.extractedAtMs 无效");
+    nonEmpty(source.extractor.harness, "source.extractor.harness");
+    nonEmpty(source.extractor.contractVersion, "source.extractor.contractVersion");
+}
+function relationKey(relation) {
+    return JSON.stringify([relation.src, relation.dst, relation.kind]);
+}
+function sourceKey(source) {
+    return JSON.stringify([source.sourceId, source.contentSha256, source.extractor.contractVersion]);
+}
+function scopeFromProps(props) {
+    if (typeof props.scope_id === "string" && props.scope_id.trim().length > 0)
+        return props.scope_id;
+    const fact = props.fact;
+    if (typeof fact === "object" && fact !== null && !Array.isArray(fact)) {
+        const scopeId = fact.scopeId;
+        if (typeof scopeId === "string" && scopeId.trim().length > 0)
+            return scopeId;
+    }
+    return null;
+}
+function entityScope(entity) {
+    if (typeof entity.scopeId === "string" && entity.scopeId.trim().length > 0)
+        return entity.scopeId;
+    return scopeFromProps(entity.props);
+}
+const DERIVED_VECTOR_PROP_KEYS = new Set([
+    "embedding",
+    "embedding_vector",
+    "embedding_model",
+    "embedding_provider",
+    "embedding_dimensions",
+    "embedding_text_hash",
+]);
+const GRAPH_SNAPSHOT_BATCH_SIZE = 128;
+export function normalizeLadybugGraphSnapshotProps(props) {
+    return Object.fromEntries(Object.entries(props).filter(([key]) => !DERIVED_VECTOR_PROP_KEYS.has(key)));
+}
+/** 兼容并行接线中的旧名称；唯一实现仍由 normalizeLadybugGraphSnapshotProps 持有。 */
+export const ladybugGraphSnapshotProps = normalizeLadybugGraphSnapshotProps;
+function edgeSnapshotKey(edge) {
+    return JSON.stringify([edge.src, edge.dst, edge.kind]);
+}
+function batches(values, size) {
+    const result = [];
+    for (let offset = 0; offset < values.length; offset += size)
+        result.push(values.slice(offset, offset + size));
+    return result;
+}
+function mergeSources(prior, source) {
+    const byKey = new Map(prior.map((entry) => [sourceKey(entry), entry]));
+    byKey.set(sourceKey(source), source);
+    return [...byKey.values()];
+}
+function emptyState(dimensions) {
+    return { schemaVersion: 1, dimensions, embeddingIdentity: null, appliedBatchIds: [], appliedBatchDigests: {}, lexicalProfile: null, entities: [], relations: [] };
+}
+function strings(value) {
+    if (typeof value === "string" && value.length > 0)
+        return [value];
+    return Array.isArray(value) ? value.filter((entry) => typeof entry === "string" && entry.length > 0) : [];
+}
+function lexicalProfileInputs(entities) {
+    const searchable = entities.filter((entity) => !isRetrievalExcluded(entity));
+    if (searchable.length === 0)
+        return null;
+    const entityLabels = [];
+    const aliases = [];
+    for (const entity of searchable) {
+        entityLabels.push(...strings(entity.props.label), ...strings(entity.props.name), ...strings(entity.props.title));
+        aliases.push(...strings(entity.props.alias), ...strings(entity.props.aliases), ...strings(entity.props.labels));
+    }
+    return { texts: searchable.map((entity) => entity.text), entityLabels, aliases };
+}
+function buildLexicalProfile(entities) {
+    const input = lexicalProfileInputs(entities);
+    return input === null ? null : buildChineseLexicalIndexProfile(input.texts, input);
+}
+function buildLegacyLexicalProfile(entities) {
+    const input = lexicalProfileInputs(entities);
+    return input === null ? null : buildLegacyChineseLexicalIndexProfileV1(input.texts, input);
+}
+function buildLegacyLexicalProfileV2(entities) {
+    const input = lexicalProfileInputs(entities);
+    return input === null ? null : buildLegacyChineseLexicalIndexProfileV2(input.texts, input);
+}
+function buildLegacyLexicalProfileV3(entities) {
+    const input = lexicalProfileInputs(entities);
+    return input === null ? null : buildLegacyChineseLexicalIndexProfileV3(input.texts, input);
+}
+function sameStableValue(left, right) {
+    return JSON.stringify(stableValue(left)) === JSON.stringify(stableValue(right));
+}
+function stableValue(value) {
+    if (Array.isArray(value))
+        return value.map(stableValue);
+    if (typeof value === "object" && value !== null) {
+        return Object.fromEntries(Object.entries(value)
+            .filter(([, entry]) => entry !== undefined)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, entry]) => [key, stableValue(entry)]));
+    }
+    return value;
+}
+function sha256Json(value) {
+    return createHash("sha256").update(JSON.stringify(stableValue(value))).digest("hex");
+}
+function batchContentDigest(batch) {
+    return sha256Json(batch);
+}
+function embeddingTextHash(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+function isRetrievalExcluded(entity) {
+    return entity.props.retrieval_excluded === true;
+}
+function parseState(raw, dimensions) {
+    const state = JSON.parse(raw);
+    invariant(state.schemaVersion === 1, "Ladybug state schemaVersion 不受支持");
+    invariant(state.dimensions === dimensions, `Ladybug state embedding 维度必须为 ${dimensions}`);
+    invariant("embeddingIdentity" in state, "Ladybug state 缺少 embedding model identity，必须重新 ingest");
+    if (state.embeddingIdentity !== null) {
+        nonEmpty(state.embeddingIdentity.providerId, "state embedding providerId");
+        nonEmpty(state.embeddingIdentity.modelId, "state embedding modelId");
+        invariant(state.embeddingIdentity.queryProfileId === LADYBUG_WORLD_FACT_QUERY_PROFILE_ID, "Ladybug state query profile 不受支持，必须重新 ingest");
+    }
+    invariant(Array.isArray(state.appliedBatchIds), "Ladybug state appliedBatchIds 无效");
+    const appliedBatchDigests = state.appliedBatchDigests ?? {};
+    invariant(typeof appliedBatchDigests === "object" && !Array.isArray(appliedBatchDigests), "Ladybug state appliedBatchDigests 无效");
+    invariant(Array.isArray(state.entities), "Ladybug state entities 无效");
+    invariant(Array.isArray(state.relations), "Ladybug state relations 无效");
+    for (const entity of state.entities) {
+        nonEmpty(entity.id, "state entity.id");
+        nonEmpty(entity.kind, "state entity.kind");
+        invariant(typeof entity.text === "string", "state entity.text 必须是 string");
+        if (!isRetrievalExcluded(entity))
+            nonEmpty(entity.text, "state entity.text");
+        if (entity.embedding !== null)
+            validateVector(entity.embedding, dimensions, `state entity ${entity.id} embedding`);
+        invariant(Array.isArray(entity.sources) && entity.sources.length > 0, `state entity ${entity.id} 缺少 provenance`);
+        entity.sources.forEach(validateSource);
+    }
+    const entities = state.entities.map((entity) => ({
+        ...entity,
+        scopeId: typeof entity.scopeId === "string" && entity.scopeId.trim().length > 0
+            ? entity.scopeId
+            : scopeFromProps(entity.props),
+    }));
+    const rebuiltProfile = buildLexicalProfile(entities);
+    const checkpointProfile = state.lexicalProfile;
+    if (checkpointProfile !== undefined) {
+        if (checkpointProfile === null) {
+            invariant(rebuiltProfile === null, "Ladybug lexical profile identity 与当前 Node/ICU/corpus 不一致，必须重建 checkpoint");
+        }
+        else {
+            invariant(typeof checkpointProfile === "object" && !Array.isArray(checkpointProfile), "Ladybug lexical profile 无效");
+            const version = checkpointProfile.version;
+            if (version === CHINESE_LEXICAL_PROFILE_VERSION) {
+                invariant(sameStableValue(checkpointProfile, rebuiltProfile), "Ladybug lexical profile identity 与当前 Node/ICU/corpus 不一致，必须重建 checkpoint");
+            }
+            else if (version === LEGACY_CHINESE_LEXICAL_PROFILE_VERSION) {
+                const rebuiltLegacyProfile = buildLegacyLexicalProfile(entities);
+                invariant(sameStableValue(checkpointProfile, rebuiltLegacyProfile), "Ladybug legacy lexical profile identity 与当前 Node/ICU/corpus 不一致，拒绝迁移");
+            }
+            else if (version === LEGACY_CHINESE_LEXICAL_PROFILE_V2_VERSION) {
+                const rebuiltLegacyProfile = buildLegacyLexicalProfileV2(entities);
+                invariant(sameStableValue(checkpointProfile, rebuiltLegacyProfile), "Ladybug legacy v2 lexical profile identity 与当前 Node/ICU/corpus 不一致，拒绝迁移");
+            }
+            else if (version === LEGACY_CHINESE_LEXICAL_PROFILE_V3_VERSION) {
+                const rebuiltLegacyProfile = buildLegacyLexicalProfileV3(entities);
+                invariant(sameStableValue(checkpointProfile, rebuiltLegacyProfile), "Ladybug legacy v3 lexical profile identity 与当前 Node/ICU/corpus 不一致，拒绝迁移");
+            }
+            else {
+                invariant(false, "Ladybug lexical profile version 不受支持");
+            }
+        }
+    }
+    return {
+        ...state,
+        appliedBatchDigests,
+        lexicalProfile: rebuiltProfile,
+        entities,
+    };
+}
+async function collect(result) {
+    if (!result.isSuccess()) {
+        const message = await result.getErrorMessage();
+        await result.close();
+        throw new Error(`LadybugDB statement failed: ${message}`);
+    }
+    const rows = await result.getAllObjects();
+    await result.close();
+    return rows;
+}
+async function query(connection, statement) {
+    return collect(await connection.query(statement));
+}
+async function execute(connection, statement, params) {
+    const prepared = await connection.prepare(statement);
+    if (!prepared.isSuccess()) {
+        const message = await prepared.getErrorMessage();
+        await prepared.close();
+        throw new Error(`LadybugDB prepare failed: ${message}`);
+    }
+    try {
+        return await collect(await connection.execute(prepared, params));
+    }
+    finally {
+        await prepared.close();
+    }
+}
+async function atomicWrite(path, contents) {
+    const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        await writeFile(tempPath, contents, { encoding: "utf8", flag: "wx" });
+        const handle = await openFile(tempPath, "r+");
+        try {
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(tempPath, path);
+    }
+    catch (error) {
+        await rm(tempPath, { force: true });
+        throw error;
+    }
+}
+/**
+ * LocalProjectHost 可消费的独立 Ladybug runtime。
+ * JSON 文件是可重建 projection checkpoint；每次 open 都把它装入真实 LadybugDB 并创建 FTS/HNSW 索引。
+ */
+export class LadybugProjectRuntime {
+    #statePath;
+    #dimensions;
+    #embeddingPort;
+    #variant;
+    #ownsWorkerLifecycle;
+    #state;
+    #projection;
+    #operation = Promise.resolve();
+    #closed = false;
+    constructor(options) {
+        this.#statePath = join(options.directory, STATE_FILE);
+        this.#dimensions = options.dimensions;
+        this.#embeddingPort = options.embeddingPort;
+        this.#variant = options.variant;
+        this.#ownsWorkerLifecycle = options.ownsWorkerLifecycle;
+        this.#state = emptyState(options.dimensions);
+    }
+    static async open(options) {
+        invariant(Number.isInteger(options.dimensions) && options.dimensions > 0, "dimensions 必须是正整数");
+        if (options.embeddingPort !== undefined) {
+            invariant(options.embeddingPort.dimensions === options.dimensions, "embedding provider 维度与 runtime 不一致");
+            nonEmpty(options.embeddingPort.providerId, "embedding providerId");
+            nonEmpty(options.embeddingPort.modelId, "embedding modelId");
+        }
+        await mkdir(options.directory, { recursive: true });
+        const variant = require("@ladybugdb/wasm-core/nodejs");
+        const ownsWorkerLifecycle = options.workerLifecycle !== "shared";
+        if (ownsWorkerLifecycle)
+            await acquireOwnedWorker(variant);
+        else
+            await variant.init();
+        const runtime = new LadybugProjectRuntime({ ...options, variant, ownsWorkerLifecycle });
+        let checkpointNeedsRewrite = false;
+        try {
+            const rawState = await readFile(runtime.#statePath, "utf8");
+            const checkpoint = JSON.parse(rawState);
+            checkpointNeedsRewrite = !("lexicalProfile" in checkpoint) || !("appliedBatchDigests" in checkpoint)
+                || (checkpoint.lexicalProfile !== null && typeof checkpoint.lexicalProfile === "object"
+                    && (checkpoint.lexicalProfile.version === LEGACY_CHINESE_LEXICAL_PROFILE_VERSION
+                        || checkpoint.lexicalProfile.version === LEGACY_CHINESE_LEXICAL_PROFILE_V2_VERSION
+                        || checkpoint.lexicalProfile.version === LEGACY_CHINESE_LEXICAL_PROFILE_V3_VERSION));
+            runtime.#state = parseState(rawState, options.dimensions);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                if (ownsWorkerLifecycle)
+                    await releaseOwnedWorker(variant);
+                throw error;
+            }
+        }
+        try {
+            if (runtime.#state.embeddingIdentity !== null && options.embeddingPort !== undefined) {
+                invariant(runtime.#state.embeddingIdentity.providerId === options.embeddingPort.providerId, "Ladybug state embedding provider identity 不匹配");
+                invariant(runtime.#state.embeddingIdentity.modelId === options.embeddingPort.modelId, "Ladybug state embedding model identity 不匹配");
+            }
+            runtime.#projection = await runtime.#buildProjection(runtime.#state);
+            if (checkpointNeedsRewrite)
+                await atomicWrite(runtime.#statePath, `${JSON.stringify(runtime.#state)}\n`);
+            return runtime;
+        }
+        catch (error) {
+            await runtime.#projection?.connection.close();
+            await runtime.#projection?.db.close();
+            runtime.#projection = undefined;
+            if (ownsWorkerLifecycle)
+                await releaseOwnedWorker(variant);
+            throw error;
+        }
+    }
+    async close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        await this.#operation;
+        const projection = this.#projection;
+        this.#projection = undefined;
+        await projection?.connection.close();
+        await projection?.db.close();
+        if (this.#ownsWorkerLifecycle)
+            await releaseOwnedWorker(this.#variant);
+    }
+    async ingest(batch) {
+        return this.#serialize(async () => {
+            invariant(!this.#closed, "Ladybug runtime 已关闭");
+            invariant(batch.schemaVersion === 1, "extraction batch schemaVersion 必须为 1");
+            nonEmpty(batch.batchId, "batchId");
+            const contentDigest = batchContentDigest(batch);
+            const priorDigest = this.#state.appliedBatchDigests[batch.batchId];
+            if (priorDigest !== undefined) {
+                invariant(priorDigest === contentDigest, `batchId ${batch.batchId} 已用于不同内容`);
+                return {
+                    batchId: batch.batchId,
+                    entityCount: this.#state.entities.length,
+                    relationCount: this.#state.relations.length,
+                    statePath: this.#statePath,
+                };
+            }
+            invariant(!this.#state.appliedBatchIds.includes(batch.batchId), `legacy batchId ${batch.batchId} 缺少内容 digest，不能安全 replay`);
+            const providerGenerated = this.#embeddingPort !== undefined
+                && batch.entities.some((entity) => entity.embedding === undefined && !isRetrievalExcluded(entity));
+            const prepared = await this.#prepareBatch(batch);
+            const next = this.#applyBatch(this.#state, prepared, providerGenerated, contentDigest);
+            const projection = await this.#buildProjection(next);
+            try {
+                await atomicWrite(this.#statePath, `${JSON.stringify(next)}\n`);
+            }
+            catch (error) {
+                await projection.connection.close();
+                await projection.db.close();
+                throw error;
+            }
+            const prior = this.#projection;
+            this.#projection = projection;
+            this.#state = next;
+            await prior?.connection.close();
+            await prior?.db.close();
+            return {
+                batchId: prepared.batchId,
+                entityCount: next.entities.length,
+                relationCount: next.relations.length,
+                statePath: this.#statePath,
+            };
+        });
+    }
+    async recall(request) {
+        return this.#serialize(async () => {
+            invariant(!this.#closed, "Ladybug runtime 已关闭");
+            nonEmpty(request.queryText, "queryText");
+            const topK = request.topK ?? 10;
+            invariant(Number.isInteger(topK) && topK > 0 && topK <= 100, "topK 必须位于 1..100");
+            if (request.scopeId !== undefined)
+                nonEmpty(request.scopeId, "scopeId");
+            const maxDistance = request.maxVectorDistance ?? DEFAULT_LADYBUG_MAX_VECTOR_DISTANCE;
+            invariant(Number.isFinite(maxDistance) && maxDistance >= 0 && maxDistance <= 2, "maxVectorDistance 必须位于 0..2");
+            const projection = this.#projection;
+            invariant(projection !== undefined, "Ladybug runtime 已关闭");
+            let semanticVector;
+            if (request.mode !== "keyword") {
+                semanticVector = request.queryEmbedding === undefined
+                    ? await this.#embedQuery(request.queryText)
+                    : validateVector(request.queryEmbedding, this.#dimensions, "queryEmbedding");
+            }
+            if (this.#state.entities.length === 0)
+                return [];
+            if (semanticVector !== undefined) {
+                invariant(this.#state.entities.some((entity) => entity.embedding !== null), "semantic/hybrid recall 没有任何真实 entity embedding 可查询");
+            }
+            const lexicalQuery = request.mode === "semantic" || this.#state.lexicalProfile === null
+                ? ""
+                : lexicalizeQuery(request.queryText, this.#state.lexicalProfile);
+            const keyword = lexicalQuery.length === 0
+                ? []
+                : await execute(projection.connection, `CALL QUERY_FTS_INDEX('${ENTITY_TABLE}', '${FTS_INDEX}', $query) ` +
+                    (request.scopeId === undefined ? "" : "WITH node, score WHERE node.scopeId = $scopeId ") +
+                    "RETURN node.id AS id, score ORDER BY score DESC LIMIT $resultK;", { query: lexicalQuery, scopeId: request.scopeId ?? "", resultK: topK });
+            let semantic = [];
+            if (semanticVector !== undefined) {
+                const candidateK = request.scopeId === undefined
+                    ? topK
+                    : this.#state.entities.reduce((count, entity) => count + (entity.embedding === null ? 0 : 1), 0);
+                semantic = await execute(projection.connection, `CALL QUERY_VECTOR_INDEX('${ENTITY_TABLE}', '${VECTOR_INDEX}', $query, $candidateK) ` +
+                    "YIELD node AS entity, distance " +
+                    (request.scopeId === undefined ? "" : "WITH entity, distance WHERE entity.scopeId = $scopeId ") +
+                    "RETURN entity.id AS id, distance ORDER BY distance LIMIT $resultK;", { query: semanticVector, candidateK, scopeId: request.scopeId ?? "", resultK: topK });
+            }
+            const scores = new Map();
+            keyword.forEach((row, rank) => {
+                const id = String(row.id);
+                scores.set(id, { score: 1 / (60 + rank + 1), channels: new Set(["keyword"]) });
+            });
+            semantic.forEach((row, rank) => {
+                const distance = Number(row.distance);
+                if (!Number.isFinite(distance) || distance > maxDistance)
+                    return;
+                const id = String(row.id);
+                const current = scores.get(id) ?? { score: 0, channels: new Set() };
+                current.score += 1 / (60 + rank + 1);
+                current.channels.add("semantic");
+                scores.set(id, current);
+            });
+            const byId = new Map(this.#state.entities.map((entity) => [entity.id, entity]));
+            return [...scores.entries()]
+                .sort((left, right) => right[1].score - left[1].score || left[0].localeCompare(right[0]))
+                .slice(0, topK)
+                .map(([id, scored]) => {
+                const entity = byId.get(id);
+                invariant(entity !== undefined, `Ladybug index 返回未知实体 ${id}`);
+                return {
+                    id: entity.id,
+                    kind: entity.kind,
+                    scopeId: entity.scopeId,
+                    text: entity.text,
+                    props: entity.props,
+                    score: scored.score,
+                    channels: [...scored.channels],
+                    sources: entity.sources,
+                };
+            });
+        });
+    }
+    async traverse(request) {
+        return this.#serialize(async () => {
+            invariant(!this.#closed, "Ladybug runtime 已关闭");
+            invariant(Array.isArray(request.startIds) && request.startIds.length > 0, "startIds 必须是非空 array");
+            invariant(request.startIds.length <= 100, "startIds 最多 100 个");
+            const startIds = request.startIds.map((id, index) => {
+                nonEmpty(id, `startIds[${index}]`);
+                return id;
+            });
+            invariant(new Set(startIds).size === startIds.length, "startIds 不得重复");
+            if (request.scopeId !== undefined)
+                nonEmpty(request.scopeId, "scopeId");
+            const direction = request.direction ?? "out";
+            invariant(direction === "out" || direction === "in" || direction === "both", "direction 必须是 out/in/both");
+            const maxHops = request.maxHops ?? 2;
+            invariant(Number.isInteger(maxHops) && maxHops >= 1 && maxHops <= 4, "maxHops 必须位于 1..4");
+            const maxPaths = request.maxPaths ?? 128;
+            invariant(Number.isInteger(maxPaths) && maxPaths >= 1 && maxPaths <= 1_000, "maxPaths 必须位于 1..1000");
+            const nodeBudget = request.nodeBudget ?? 256;
+            invariant(Number.isInteger(nodeBudget) && nodeBudget >= startIds.length && nodeBudget <= 1_000, "nodeBudget 必须覆盖 startIds 且不超过 1000");
+            const relationKinds = new Set(request.relationKinds ?? []);
+            invariant(relationKinds.size <= 64, "relationKinds 最多 64 个");
+            for (const kind of relationKinds)
+                nonEmpty(kind, "relationKinds[]");
+            invariant(request.semanticOnly === undefined || typeof request.semanticOnly === "boolean", "semanticOnly 必须是 boolean");
+            const semanticOnly = request.semanticOnly ?? false;
+            const projection = this.#projection;
+            invariant(projection !== undefined, "Ladybug runtime 已关闭");
+            for (const id of startIds) {
+                const rows = await execute(projection.connection, `MATCH (n:${ENTITY_TABLE} {id:$id}) RETURN n.id AS id, n.scopeId AS scopeId;`, { id });
+                invariant(rows.length === 1, `traverse start node 不存在：${id}`);
+                if (request.scopeId !== undefined) {
+                    invariant(rows[0].scopeId === request.scopeId, `traverse start node ${id} 不属于 scope ${request.scopeId}`);
+                }
+            }
+            const visited = new Set(startIds);
+            const results = [];
+            let frontier = startIds.map((id) => ({ nodeIds: [id], edges: [] }));
+            let truncated = false;
+            for (let hop = 0; hop < maxHops && frontier.length > 0; hop += 1) {
+                const nextFrontier = [];
+                for (const path of frontier) {
+                    const current = path.nodeIds[path.nodeIds.length - 1];
+                    const candidates = await this.#readAdjacentEdges(current, direction, request.scopeId);
+                    for (const candidate of candidates) {
+                        if (relationKinds.size > 0 && !relationKinds.has(candidate.edge.kind))
+                            continue;
+                        if (semanticOnly && classifyDocumentRelationRole({ relation: candidate.edge, endpoints: candidate.endpointKinds }) !== "semantic")
+                            continue;
+                        if (path.nodeIds.includes(candidate.nextId))
+                            continue;
+                        if (!visited.has(candidate.nextId) && visited.size >= nodeBudget) {
+                            truncated = true;
+                            continue;
+                        }
+                        visited.add(candidate.nextId);
+                        const nextPath = {
+                            nodeIds: [...path.nodeIds, candidate.nextId],
+                            edges: [...path.edges, candidate.edge],
+                        };
+                        results.push(nextPath);
+                        nextFrontier.push(nextPath);
+                        if (results.length >= maxPaths) {
+                            truncated = true;
+                            return { paths: results, visitedNodeIds: [...visited], truncated };
+                        }
+                    }
+                }
+                frontier = nextFrontier;
+            }
+            return { paths: results, visitedNodeIds: [...visited], truncated };
+        });
+    }
+    async readGraphSnapshot(request = {}) {
+        return this.#serialize(async () => {
+            invariant(!this.#closed, "Ladybug runtime 已关闭");
+            if (request.scopeId !== undefined)
+                nonEmpty(request.scopeId, "scopeId");
+            const projection = this.#projection;
+            invariant(projection !== undefined, "Ladybug runtime 已关闭");
+            const nodeCountRows = await execute(projection.connection, `MATCH (n:${ENTITY_TABLE}) ` +
+                (request.scopeId === undefined ? "" : "WHERE n.scopeId = $scopeId ") +
+                "RETURN count(n) AS count;", { scopeId: request.scopeId ?? "" });
+            const edgeCountRows = await execute(projection.connection, `MATCH (a:${ENTITY_TABLE})-[r:${RELATION_TABLE}]->(b:${ENTITY_TABLE}) ` +
+                (request.scopeId === undefined ? "" : "WHERE a.scopeId = $scopeId AND b.scopeId = $scopeId ") +
+                "RETURN count(r) AS count;", { scopeId: request.scopeId ?? "" });
+            const expectedNodeCount = Number(nodeCountRows[0]?.count ?? 0);
+            const expectedEdgeCount = Number(edgeCountRows[0]?.count ?? 0);
+            invariant(Number.isSafeInteger(expectedNodeCount) && expectedNodeCount >= 0, "Ladybug snapshot node count 无效");
+            invariant(Number.isSafeInteger(expectedEdgeCount) && expectedEdgeCount >= 0, "Ladybug snapshot edge count 无效");
+            const nodeIdentities = await execute(projection.connection, `MATCH (n:${ENTITY_TABLE}) ` +
+                (request.scopeId === undefined ? "" : "WHERE n.scopeId = $scopeId ") +
+                "RETURN n.id AS id, n.kind AS kind, n.scopeId AS scopeId ORDER BY n.id;", { scopeId: request.scopeId ?? "" });
+            const edgeIdentities = await execute(projection.connection, `MATCH (a:${ENTITY_TABLE})-[r:${RELATION_TABLE}]->(b:${ENTITY_TABLE}) ` +
+                (request.scopeId === undefined ? "" : "WHERE a.scopeId = $scopeId AND b.scopeId = $scopeId ") +
+                "RETURN a.id AS src, b.id AS dst, r.kind AS kind ORDER BY a.id, b.id, r.kind;", { scopeId: request.scopeId ?? "" });
+            invariant(nodeIdentities.length === expectedNodeCount, `Ladybug snapshot node identity count mismatch: expected ${expectedNodeCount}, got ${nodeIdentities.length}`);
+            invariant(edgeIdentities.length === expectedEdgeCount, `Ladybug snapshot edge identity count mismatch: expected ${expectedEdgeCount}, got ${edgeIdentities.length}`);
+            const nodeOrder = nodeIdentities.map((row) => ({ id: String(row.id), kind: String(row.kind), scopeId: row.scopeId == null ? null : String(row.scopeId) }));
+            invariant(new Set(nodeOrder.map((node) => node.id)).size === nodeOrder.length, "Ladybug snapshot node identity 重复");
+            const propsByNodeId = new Map();
+            for (const batch of batches(nodeOrder, GRAPH_SNAPSHOT_BATCH_SIZE)) {
+                const rows = await execute(projection.connection, `MATCH (n:${ENTITY_TABLE}) WHERE n.id IN $ids RETURN n.id AS id, n.props AS props;`, { ids: batch.map((node) => node.id) });
+                invariant(rows.length === batch.length, "Ladybug snapshot node props batch 缺页或包含重复行");
+                const expectedIds = new Set(batch.map((node) => node.id));
+                for (const row of rows) {
+                    const id = String(row.id);
+                    invariant(expectedIds.has(id), `Ladybug snapshot node props 返回额外 id: ${id}`);
+                    invariant(!propsByNodeId.has(id), `Ladybug snapshot node props 重复 id: ${id}`);
+                    propsByNodeId.set(id, JSON.parse(String(row.props)));
+                }
+            }
+            const snapshotNodes = nodeOrder.map((node) => {
+                const props = propsByNodeId.get(node.id);
+                invariant(props !== undefined, `Ladybug snapshot node props 缺少 id: ${node.id}`);
+                return { ...node, props: normalizeLadybugGraphSnapshotProps(props) };
+            });
+            const edgeOrder = edgeIdentities.map((row) => ({ src: String(row.src), dst: String(row.dst), kind: String(row.kind) }));
+            invariant(new Set(edgeOrder.map(edgeSnapshotKey)).size === edgeOrder.length, "Ladybug snapshot edge identity 重复");
+            const propsByEdgeKey = new Map();
+            for (const batch of batches(edgeOrder, GRAPH_SNAPSHOT_BATCH_SIZE)) {
+                const params = {};
+                const predicates = batch.map((edge, index) => {
+                    params[`src${index}`] = edge.src;
+                    params[`dst${index}`] = edge.dst;
+                    params[`kind${index}`] = edge.kind;
+                    return `(a.id = $src${index} AND b.id = $dst${index} AND r.kind = $kind${index})`;
+                });
+                const rows = await execute(projection.connection, `MATCH (a:${ENTITY_TABLE})-[r:${RELATION_TABLE}]->(b:${ENTITY_TABLE}) WHERE ${predicates.join(" OR ")} ` +
+                    "RETURN a.id AS src, b.id AS dst, r.kind AS kind, r.props AS props;", params);
+                invariant(rows.length === batch.length, "Ladybug snapshot edge props batch 缺页或包含重复行");
+                const expectedKeys = new Set(batch.map(edgeSnapshotKey));
+                for (const row of rows) {
+                    const key = edgeSnapshotKey({ src: String(row.src), dst: String(row.dst), kind: String(row.kind) });
+                    invariant(expectedKeys.has(key), `Ladybug snapshot edge props 返回额外 key: ${key}`);
+                    invariant(!propsByEdgeKey.has(key), `Ladybug snapshot edge props 重复 key: ${key}`);
+                    propsByEdgeKey.set(key, JSON.parse(String(row.props)));
+                }
+            }
+            const snapshotEdges = edgeOrder.map((edge) => {
+                const key = edgeSnapshotKey(edge);
+                const props = propsByEdgeKey.get(key);
+                invariant(props !== undefined, `Ladybug snapshot edge props 缺少 key: ${key}`);
+                return { ...edge, props: normalizeLadybugGraphSnapshotProps(props) };
+            });
+            return {
+                nodes: snapshotNodes,
+                edges: snapshotEdges,
+                nodeCount: expectedNodeCount,
+                edgeCount: expectedEdgeCount,
+            };
+        });
+    }
+    async #readAdjacentEdges(id, direction, scopeId) {
+        const projection = this.#projection;
+        invariant(projection !== undefined, "Ladybug runtime 已关闭");
+        const rows = [];
+        if (direction === "out" || direction === "both") {
+            const outgoing = await execute(projection.connection, `MATCH (a:${ENTITY_TABLE} {id:$id})-[r:${RELATION_TABLE}]->(b:${ENTITY_TABLE}) ` +
+                (scopeId === undefined ? "" : "WHERE b.scopeId = $scopeId ") +
+                "RETURN a.id AS src, b.id AS dst, a.kind AS srcKind, b.kind AS dstKind, b.id AS nextId, r.kind AS kind, r.props AS props, r.sources AS sources ORDER BY r.kind, b.id;", { id, scopeId: scopeId ?? "" });
+            rows.push(...outgoing.map((row) => ({ row, nextId: String(row.nextId) })));
+        }
+        if (direction === "in" || direction === "both") {
+            const incoming = await execute(projection.connection, `MATCH (a:${ENTITY_TABLE})-[r:${RELATION_TABLE}]->(b:${ENTITY_TABLE} {id:$id}) ` +
+                (scopeId === undefined ? "" : "WHERE a.scopeId = $scopeId ") +
+                "RETURN a.id AS src, b.id AS dst, a.kind AS srcKind, b.kind AS dstKind, a.id AS nextId, r.kind AS kind, r.props AS props, r.sources AS sources ORDER BY r.kind, a.id;", { id, scopeId: scopeId ?? "" });
+            rows.push(...incoming.map((row) => ({ row, nextId: String(row.nextId) })));
+        }
+        const seen = new Set();
+        const result = [];
+        for (const { row, nextId } of rows) {
+            const edge = {
+                src: String(row.src),
+                dst: String(row.dst),
+                kind: String(row.kind),
+                props: JSON.parse(String(row.props)),
+                sources: JSON.parse(String(row.sources)),
+            };
+            const key = JSON.stringify([nextId, edge.src, edge.dst, edge.kind]);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            result.push({ nextId, edge, endpointKinds: { srcKind: String(row.srcKind), dstKind: String(row.dstKind) } });
+        }
+        return result;
+    }
+    async #embedQuery(text) {
+        invariant(this.#embeddingPort !== undefined, "semantic/hybrid recall 需要 queryEmbedding 或真实 embedding provider");
+        invariant(this.#state.embeddingIdentity !== null, "持久化 embedding 缺少 provider/model identity，必须显式给出 queryEmbedding 或重新 ingest");
+        invariant(this.#state.embeddingIdentity.providerId === this.#embeddingPort.providerId, "query embedding provider 与持久化 entity embedding 不一致");
+        invariant(this.#state.embeddingIdentity.modelId === this.#embeddingPort.modelId, "query embedding model 与持久化 entity embedding 不一致");
+        return [...await embedLadybugQuery(this.#embeddingPort, text)];
+    }
+    async #prepareBatch(batch) {
+        invariant(batch.schemaVersion === 1, "extraction batch schemaVersion 必须为 1");
+        nonEmpty(batch.batchId, "batchId");
+        validateSource(batch.source);
+        invariant(Array.isArray(batch.entities), "batch.entities 必须是 array");
+        invariant(Array.isArray(batch.relations), "batch.relations 必须是 array");
+        const ids = new Set();
+        const missing = [];
+        batch.entities.forEach((entity, index) => {
+            nonEmpty(entity.id, `entities[${index}].id`);
+            nonEmpty(entity.kind, `entities[${index}].kind`);
+            invariant(typeof entity.text === "string", `entities[${index}].text 必须是 string`);
+            if (!isRetrievalExcluded(entity))
+                nonEmpty(entity.text, `entities[${index}].text`);
+            invariant(!ids.has(entity.id), `batch 中实体 id 重复：${entity.id}`);
+            ids.add(entity.id);
+            if (isRetrievalExcluded(entity)) {
+                invariant(entity.embedding === undefined, `retrieval_excluded source_document ${entity.id} 不得携带 embedding`);
+            }
+            else if (entity.embedding === undefined)
+                missing.push(index);
+            else
+                validateVector(entity.embedding, this.#dimensions, `entities[${index}].embedding`);
+        });
+        const generated = new Map();
+        if (missing.length > 0) {
+            if (this.#embeddingPort !== undefined) {
+                invariant(!batch.entities.some((entity) => entity.embedding !== undefined), "同一 ingest batch 不得混用 caller-supplied 与 provider-generated embedding");
+            }
+            if (this.#embeddingPort !== undefined && this.#state.entities.some((entity) => entity.embedding !== null)) {
+                invariant(this.#state.embeddingIdentity !== null, "已有 caller-supplied embedding 的 state 不得追加 provider-generated embedding");
+                invariant(this.#state.embeddingIdentity.providerId === this.#embeddingPort.providerId, "ingest embedding provider 与持久化 state 不一致");
+                invariant(this.#state.embeddingIdentity.modelId === this.#embeddingPort.modelId, "ingest embedding model 与持久化 state 不一致");
+            }
+            if (this.#embeddingPort !== undefined) {
+                const identityMatches = this.#state.embeddingIdentity?.providerId === this.#embeddingPort.providerId
+                    && this.#state.embeddingIdentity.modelId === this.#embeddingPort.modelId;
+                const cached = new Map();
+                if (identityMatches) {
+                    for (const entity of this.#state.entities) {
+                        if (entity.embedding !== null)
+                            cached.set(embeddingTextHash(entity.text), entity.embedding);
+                    }
+                }
+                const uncachedByHash = new Map();
+                for (const index of missing) {
+                    const text = batch.entities[index].text;
+                    const hash = embeddingTextHash(text);
+                    const reused = cached.get(hash);
+                    if (reused !== undefined) {
+                        generated.set(index, reused);
+                        continue;
+                    }
+                    const pending = uncachedByHash.get(hash) ?? { text, indexes: [] };
+                    pending.indexes.push(index);
+                    uncachedByHash.set(hash, pending);
+                }
+                const pending = [...uncachedByHash.values()];
+                const vectors = pending.length === 0 ? [] : await this.#embeddingPort.embed(pending.map((entry) => entry.text));
+                invariant(vectors.length === pending.length, "embedding provider 返回数量与输入不一致");
+                pending.forEach((entry, vectorIndex) => {
+                    const vector = validateVector(vectors[vectorIndex], this.#dimensions, `provider embedding[${vectorIndex}]`);
+                    entry.indexes.forEach((index) => generated.set(index, vector));
+                });
+            }
+        }
+        else if (batch.entities.some((entity) => entity.embedding !== undefined) && this.#state.embeddingIdentity !== null) {
+            throw new Error("已绑定 provider/model identity 的 state 不接受来源不明的 caller-supplied embedding");
+        }
+        const entities = batch.entities.map((entity, index) => ({
+            ...entity,
+            embedding: entity.embedding === undefined
+                ? (this.#embeddingPort === undefined
+                    ? undefined
+                    : (isRetrievalExcluded(entity)
+                        ? undefined
+                        : validateVector(generated.get(index), this.#dimensions, `provider entities[${index}].embedding`)))
+                : validateVector(entity.embedding, this.#dimensions, `entities[${index}].embedding`),
+        }));
+        const known = new Set([...this.#state.entities.map((entity) => entity.id), ...ids]);
+        const relationKeys = new Set();
+        batch.relations.forEach((relation, index) => {
+            nonEmpty(relation.src, `relations[${index}].src`);
+            nonEmpty(relation.dst, `relations[${index}].dst`);
+            nonEmpty(relation.kind, `relations[${index}].kind`);
+            invariant(known.has(relation.src) && known.has(relation.dst), `relation 两端实体必须存在：${relation.src} -> ${relation.dst}`);
+            const key = relationKey(relation);
+            invariant(!relationKeys.has(key), `batch 中 relation 重复：${key}`);
+            relationKeys.add(key);
+        });
+        return { ...batch, entities };
+    }
+    #applyBatch(state, batch, providerGenerated, contentDigest) {
+        const entities = new Map(state.entities.map((entity) => [entity.id, entity]));
+        for (const entity of batch.entities) {
+            const prior = entities.get(entity.id);
+            entities.set(entity.id, {
+                id: entity.id,
+                kind: entity.kind,
+                scopeId: entityScope(entity),
+                text: entity.text,
+                props: entity.props,
+                embedding: entity.embedding ?? null,
+                sources: mergeSources(prior?.sources ?? [], batch.source),
+            });
+        }
+        const relations = new Map(state.relations.map((relation) => [relationKey(relation), relation]));
+        for (const relation of batch.relations) {
+            const key = relationKey(relation);
+            const prior = relations.get(key);
+            relations.set(key, { ...relation, sources: mergeSources(prior?.sources ?? [], batch.source) });
+        }
+        const nextWithoutProfile = {
+            schemaVersion: 1,
+            dimensions: this.#dimensions,
+            embeddingIdentity: providerGenerated
+                ? {
+                    providerId: this.#embeddingPort.providerId,
+                    modelId: this.#embeddingPort.modelId,
+                    queryProfileId: LADYBUG_WORLD_FACT_QUERY_PROFILE_ID,
+                }
+                : state.embeddingIdentity,
+            appliedBatchIds: [...state.appliedBatchIds, batch.batchId],
+            appliedBatchDigests: { ...state.appliedBatchDigests, [batch.batchId]: contentDigest },
+            lexicalProfile: null,
+            entities: [...entities.values()].sort((left, right) => left.id.localeCompare(right.id)),
+            relations: [...relations.values()].sort((left, right) => relationKey(left).localeCompare(relationKey(right))),
+        };
+        return { ...nextWithoutProfile, lexicalProfile: buildLexicalProfile(nextWithoutProfile.entities) };
+    }
+    async #buildProjection(state) {
+        const db = new this.#variant.Database(":memory:");
+        await db.init();
+        const connection = new this.#variant.Connection(db);
+        await connection.init();
+        try {
+            await query(connection, `CREATE NODE TABLE ${ENTITY_TABLE}(id STRING, kind STRING, scopeId STRING, text STRING, lexicalText STRING, props STRING, sources STRING, embedding FLOAT[${this.#dimensions}], PRIMARY KEY(id));`);
+            await query(connection, `CREATE REL TABLE ${RELATION_TABLE}(FROM ${ENTITY_TABLE} TO ${ENTITY_TABLE}, kind STRING, props STRING, sources STRING);`);
+            let createEntity;
+            let createRelation;
+            try {
+                if (state.entities.length > 0) {
+                    createEntity = await connection.prepare(`CREATE (e:${ENTITY_TABLE} {id:$id, kind:$kind, scopeId:$scopeId, text:$text, lexicalText:$lexicalText, props:$props, sources:$sources, embedding:$embedding});`);
+                    if (!createEntity.isSuccess())
+                        throw new Error(`LadybugDB prepare failed: ${await createEntity.getErrorMessage()}`);
+                }
+                if (state.relations.length > 0) {
+                    createRelation = await connection.prepare(`MATCH (a:${ENTITY_TABLE} {id:$src}), (b:${ENTITY_TABLE} {id:$dst}) CREATE (a)-[:${RELATION_TABLE} {kind:$kind, props:$props, sources:$sources}]->(b);`);
+                    if (!createRelation.isSuccess())
+                        throw new Error(`LadybugDB prepare failed: ${await createRelation.getErrorMessage()}`);
+                }
+                for (const entity of state.entities) {
+                    invariant(createEntity !== undefined, "Ladybug entity prepared statement 缺失");
+                    await collect(await connection.execute(createEntity, { id: entity.id, kind: entity.kind, scopeId: entity.scopeId, text: entity.text, lexicalText: isRetrievalExcluded(entity) || state.lexicalProfile === null ? "" : lexicalize(entity.text, state.lexicalProfile), props: JSON.stringify(entity.props), sources: JSON.stringify(entity.sources), embedding: entity.embedding === null ? null : [...entity.embedding] }));
+                }
+                for (const relation of state.relations) {
+                    invariant(createRelation !== undefined, "Ladybug relation prepared statement 缺失");
+                    await collect(await connection.execute(createRelation, { src: relation.src, dst: relation.dst, kind: relation.kind, props: JSON.stringify(relation.props), sources: JSON.stringify(relation.sources) }));
+                }
+            }
+            finally {
+                await createRelation?.close();
+                await createEntity?.close();
+            }
+            if (state.lexicalProfile !== null) {
+                await query(connection, `CALL CREATE_FTS_INDEX('${ENTITY_TABLE}', '${FTS_INDEX}', ['lexicalText'], stemmer := 'none', tokenizer := 'simple');`);
+            }
+            if (state.entities.some((entity) => entity.embedding !== null)) {
+                await query(connection, `CALL CREATE_VECTOR_INDEX('${ENTITY_TABLE}', '${VECTOR_INDEX}', 'embedding', metric := 'cosine');`);
+            }
+            return { db, connection };
+        }
+        catch (error) {
+            await connection.close();
+            await db.close();
+            throw error;
+        }
+    }
+    async #serialize(operation) {
+        const prior = this.#operation;
+        let release;
+        this.#operation = new Promise((resolve) => { release = resolve; });
+        await prior;
+        try {
+            return await operation();
+        }
+        finally {
+            release();
+        }
+    }
+}