@world-engines/tmw 0.1.0-alpha.0

package/dist/natural-language-chunking.d.ts

@@ -0,0 +1,10 @@
+import type { NaturalLanguageChunk } from "./natural-language-world-types.js";
+export interface NaturalLanguageChunkingOptions {
+    readonly maximumCharacters?: number;
+    readonly overlapCharacters?: number;
+}
+/**
+ * 生成覆盖全文的确定性 chunk。offset 使用 JavaScript/DOM 通用的 UTF-16 code unit，
+ * 且绝不切开 surrogate pair。
+ */
+export declare function chunkNaturalLanguageSource(text: string, options?: NaturalLanguageChunkingOptions): Promise<readonly NaturalLanguageChunk[]>;

package/dist/natural-language-chunking.js

@@ -0,0 +1,62 @@
+import { tmwSha256Hex } from "./runtime-trace.js";
+function canonicalBoundary(text, candidate) {
+    if (candidate > 0 && candidate < text.length
+        && /[\uD800-\uDBFF]/u.test(text[candidate - 1])
+        && /[\uDC00-\uDFFF]/u.test(text[candidate]))
+        return candidate - 1;
+    return candidate;
+}
+function chooseEnd(text, start, maximum) {
+    const hardEnd = Math.min(text.length, start + maximum);
+    if (hardEnd === text.length)
+        return text.length;
+    const minimumSoftEnd = start + Math.floor(maximum / 2);
+    for (const separator of ["\n\n", "\n", "。", ". ", " "]) {
+        const found = text.lastIndexOf(separator, hardEnd - separator.length);
+        if (found >= minimumSoftEnd)
+            return canonicalBoundary(text, found + separator.length);
+    }
+    return canonicalBoundary(text, hardEnd);
+}
+/**
+ * 生成覆盖全文的确定性 chunk。offset 使用 JavaScript/DOM 通用的 UTF-16 code unit，
+ * 且绝不切开 surrogate pair。
+ */
+export async function chunkNaturalLanguageSource(text, options = {}) {
+    if (typeof text !== "string" || text.length === 0)
+        throw new Error("natural_language_source_empty");
+    const maximum = options.maximumCharacters ?? 6_000;
+    const overlap = options.overlapCharacters ?? 400;
+    if (!Number.isSafeInteger(maximum) || maximum < 256)
+        throw new Error("natural_language_chunk_maximum_invalid");
+    if (!Number.isSafeInteger(overlap) || overlap < 0 || overlap >= maximum / 2) {
+        throw new Error("natural_language_chunk_overlap_invalid");
+    }
+    const chunks = [];
+    let start = 0;
+    while (start < text.length) {
+        const end = chooseEnd(text, start, maximum);
+        if (end <= start)
+            throw new Error("natural_language_chunk_no_progress");
+        const chunkText = text.slice(start, end);
+        chunks.push(Object.freeze({
+            index: chunks.length,
+            startOffset: start,
+            endOffset: end,
+            text: chunkText,
+            sha256: await tmwSha256Hex(chunkText),
+        }));
+        if (end === text.length)
+            break;
+        start = canonicalBoundary(text, Math.max(start + 1, end - overlap));
+    }
+    if (chunks[0]?.startOffset !== 0 || chunks.at(-1)?.endOffset !== text.length) {
+        throw new Error("natural_language_chunk_coverage_incomplete");
+    }
+    for (let index = 1; index < chunks.length; index += 1) {
+        if (chunks[index].startOffset > chunks[index - 1].endOffset) {
+            throw new Error("natural_language_chunk_coverage_gap");
+        }
+    }
+    return Object.freeze(chunks);
+}

package/dist/natural-language-ingestion.d.ts

@@ -0,0 +1,14 @@
+import { type NaturalLanguageChunkingOptions } from "./natural-language-chunking.js";
+import { type TypedWorldAuthorityPort, type WorldFactExtractionPort, type WorldOperations } from "./natural-language-world-types.js";
+export * from "./natural-language-world-types.js";
+export { chunkNaturalLanguageSource } from "./natural-language-chunking.js";
+export type { NaturalLanguageChunkingOptions } from "./natural-language-chunking.js";
+export { decodeWorldFactExtractionResult } from "./natural-language-structured-decode.js";
+export interface NaturalLanguageWorldOperationsOptions {
+    readonly authority: TypedWorldAuthorityPort;
+    readonly extractor: WorldFactExtractionPort;
+    readonly chunking?: NaturalLanguageChunkingOptions;
+    readonly maximumConcurrentExtractions?: number;
+    readonly clock?: () => number;
+}
+export declare function createNaturalLanguageWorldOperations(options: NaturalLanguageWorldOperationsOptions): WorldOperations;

package/dist/natural-language-ingestion.js

@@ -0,0 +1,128 @@
+import { canonicalTmwJson, requireTmwIdentifier, requireTmwSha256, tmwSha256Hex } from "./runtime-trace.js";
+import { chunkNaturalLanguageSource } from "./natural-language-chunking.js";
+import { decodeWorldFactExtractionResult } from "./natural-language-structured-decode.js";
+import { WORLD_FACT_EXTRACTION_REQUEST_SCHEMA, WORLD_FACT_EXTRACTION_RESULT_SCHEMA, } from "./natural-language-world-types.js";
+export * from "./natural-language-world-types.js";
+export { chunkNaturalLanguageSource } from "./natural-language-chunking.js";
+export { decodeWorldFactExtractionResult } from "./natural-language-structured-decode.js";
+function canonicalText(value, code, maximum) {
+    if (typeof value !== "string" || value.length === 0 || value.length > maximum || value.trim() !== value || value.normalize("NFC") !== value)
+        throw new Error(code);
+    return value;
+}
+function sourceText(value) {
+    if (typeof value !== "string" || value.length === 0 || value.length > 10_000_000 || value.normalize("NFC") !== value || value.includes("\0"))
+        throw new Error("natural_language_source_invalid");
+    return value;
+}
+async function factIdentity(scopeId, fact) {
+    return tmwSha256Hex(canonicalTmwJson({ scopeId, kind: fact.kind, subject: fact.subject, predicate: fact.predicate, object: fact.object, qualifiers: fact.qualifiers }));
+}
+function orderProvenance(values) {
+    const unique = new Map(values.map((value) => [canonicalTmwJson(value), value]));
+    return Object.freeze([...unique.values()].sort((left, right) => left.startOffset - right.startOffset || left.endOffset - right.endOffset || left.chunkIndex - right.chunkIndex));
+}
+function renderedObject(fact) {
+    if (fact.object.type === "entity")
+        return fact.object.value.label;
+    if (fact.object.type === "json")
+        return canonicalTmwJson(fact.object.value);
+    return String(fact.object.value);
+}
+async function extractDocument(source, sourceSha256, extractor, chunking, maximumConcurrentExtractions) {
+    const chunks = await chunkNaturalLanguageSource(source.text, chunking);
+    const extractedByChunk = new Array(chunks.length);
+    const concurrency = Math.min(chunks.length, maximumConcurrentExtractions ?? 4);
+    let cursor = 0;
+    await Promise.all(Array.from({ length: concurrency }, async () => {
+        while (cursor < chunks.length) {
+            const index = cursor;
+            cursor += 1;
+            const chunk = chunks[index];
+            extractedByChunk[index] = { chunk, facts: decodeWorldFactExtractionResult(await extractor.extract(Object.freeze({
+                    schema: WORLD_FACT_EXTRACTION_REQUEST_SCHEMA,
+                    source: Object.freeze({ scopeId: source.scopeId, sourceId: source.sourceId, sourceRevision: source.sourceRevision, sourceSha256 }),
+                    chunk, outputSchema: WORLD_FACT_EXTRACTION_RESULT_SCHEMA,
+                })), chunk) };
+        }
+    }));
+    const byId = new Map();
+    for (const { chunk, facts } of extractedByChunk)
+        for (const candidate of facts) {
+            const core = Object.freeze({ kind: candidate.kind, subject: candidate.subject, predicate: candidate.predicate, object: candidate.object, qualifiers: candidate.qualifiers });
+            const factId = await factIdentity(source.scopeId, core);
+            const provenance = Object.freeze({
+                sourceId: source.sourceId, sourceRevision: source.sourceRevision, sourceSha256,
+                chunkIndex: chunk.index, chunkSha256: chunk.sha256,
+                startOffset: chunk.startOffset + candidate.evidence.startOffset,
+                endOffset: chunk.startOffset + candidate.evidence.endOffset, quote: candidate.evidence.quote,
+            });
+            const previous = byId.get(factId);
+            byId.set(factId, Object.freeze({ factId, scopeId: source.scopeId, ...core,
+                confidence: Math.max(previous?.confidence ?? 0, candidate.confidence),
+                provenance: orderProvenance([...(previous?.provenance ?? []), provenance]),
+            }));
+        }
+    return Object.freeze({ chunks: chunks.length, facts: Object.freeze([...byId.values()].sort((a, b) => a.factId.localeCompare(b.factId))) });
+}
+const graphEntityId = (scopeId, sourceEntityId) => `${scopeId}:${sourceEntityId}`;
+function buildLadybugBatch(input) {
+    const entities = new Map();
+    const ensureEntity = (id, label) => {
+        const graphId = graphEntityId(input.source.scopeId, id);
+        if (!entities.has(graphId))
+            entities.set(graphId, { id: graphId, label, facts: [] });
+        return entities.get(graphId);
+    };
+    const relations = [];
+    for (const fact of input.facts) {
+        ensureEntity(fact.subject.id, fact.subject.label).facts.push(fact);
+        if (fact.kind === "relation" && fact.object.type === "entity") {
+            const destination = ensureEntity(fact.object.value.id, fact.object.value.label);
+            relations.push(Object.freeze({ src: graphEntityId(input.source.scopeId, fact.subject.id), dst: destination.id, kind: fact.predicate, props: Object.freeze({ scopeId: fact.scopeId, factId: fact.factId, qualifiers: fact.qualifiers, confidence: fact.confidence, provenance: fact.provenance }) }));
+        }
+    }
+    return Object.freeze({
+        schemaVersion: 1, batchId: input.batchId,
+        source: Object.freeze({ sourceId: input.source.sourceId, ...(input.source.sourcePath === undefined ? {} : { sourcePath: input.source.sourcePath }), contentSha256: input.sourceSha256, extractedAtMs: input.extractedAtMs, extractor: Object.freeze({ harness: input.extractor.harness, ...(input.extractor.model === undefined ? {} : { model: input.extractor.model }), contractVersion: input.extractor.contractVersion }) }),
+        entities: Object.freeze([...entities.values()].sort((a, b) => a.id.localeCompare(b.id)).map((entity) => Object.freeze({ id: entity.id, kind: "world_entity", scopeId: input.source.scopeId, text: [entity.label, ...entity.facts.map((fact) => `${fact.predicate}: ${renderedObject(fact)}`)].join("\n"), props: Object.freeze({ scopeId: input.source.scopeId, sourceEntityId: entity.id.slice(input.source.scopeId.length + 1), label: entity.label, facts: entity.facts }) }))),
+        relations: Object.freeze(relations.sort((a, b) => `${a.src}\0${a.dst}\0${a.kind}`.localeCompare(`${b.src}\0${b.dst}\0${b.kind}`))),
+    });
+}
+export function createNaturalLanguageWorldOperations(options) {
+    canonicalText(options.extractor.harness, "world_fact_extractor_harness_invalid", 512);
+    canonicalText(options.extractor.contractVersion, "world_fact_extractor_contract_invalid", 512);
+    if (options.extractor.model !== undefined)
+        canonicalText(options.extractor.model, "world_fact_extractor_model_invalid", 512);
+    if (options.maximumConcurrentExtractions !== undefined && (!Number.isSafeInteger(options.maximumConcurrentExtractions) || options.maximumConcurrentExtractions < 1 || options.maximumConcurrentExtractions > 16))
+        throw new Error("world_fact_extraction_concurrency_invalid");
+    return Object.freeze({
+        async commit(sourceInput) {
+            const source = Object.freeze({ scopeId: requireTmwIdentifier(sourceInput.scopeId, "world_fact_scope_id"), sourceId: requireTmwIdentifier(sourceInput.sourceId, "world_fact_source_id"), sourceRevision: requireTmwIdentifier(sourceInput.sourceRevision, "world_fact_source_revision"), text: sourceText(sourceInput.text), ...(sourceInput.sourcePath === undefined ? {} : { sourcePath: canonicalText(sourceInput.sourcePath, "world_fact_source_path_invalid", 4_096) }), mediaType: sourceInput.mediaType ?? "text/plain" });
+            if (source.mediaType !== "text/plain" && source.mediaType !== "text/markdown")
+                throw new Error("natural_language_media_type_invalid");
+            const sourceSha256 = requireTmwSha256(await tmwSha256Hex(source.text), "world_fact_source_sha256");
+            const extracted = await extractDocument(source, sourceSha256, options.extractor, options.chunking, options.maximumConcurrentExtractions);
+            const batchId = await tmwSha256Hex(canonicalTmwJson({ schemaVersion: 1, scopeId: source.scopeId, sourceId: source.sourceId, sourceRevision: source.sourceRevision, sourceSha256, harness: options.extractor.harness, model: options.extractor.model ?? null, contractVersion: options.extractor.contractVersion }));
+            const extractedAtMs = (options.clock ?? Date.now)();
+            if (!Number.isSafeInteger(extractedAtMs) || extractedAtMs < 0)
+                throw new Error("world_fact_extracted_at_invalid");
+            const result = await options.authority.commit(buildLadybugBatch({ source, sourceSha256, extractedAtMs, extractor: options.extractor, batchId, facts: extracted.facts }));
+            return Object.freeze({ status: result.status, version: result.version, batchId, sourceSha256, chunkCount: extracted.chunks, factCount: extracted.facts.length });
+        },
+        async read(input) {
+            return options.authority.read({ scopeId: requireTmwIdentifier(input.scopeId, "world_fact_scope_id"), factId: requireTmwSha256(input.factId, "world_fact_id") });
+        },
+        async resolve(input) {
+            const limit = input.limit ?? 8;
+            const minimumRelevance = input.minimumRelevance ?? 0.55;
+            if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100)
+                throw new Error("world_fact_recall_limit_invalid");
+            if (!Number.isFinite(minimumRelevance) || minimumRelevance < 0 || minimumRelevance > 1)
+                throw new Error("world_fact_recall_minimum_relevance_invalid");
+            const scopeId = requireTmwIdentifier(input.scopeId, "world_fact_scope_id");
+            const hits = await options.authority.resolve({ scopeId, query: canonicalText(input.query, "world_fact_query_invalid", 8_192), mode: "semantic", limit, minimumRelevance });
+            return Object.freeze(hits.filter((hit) => hit.fact.scopeId === scopeId && hit.relevance >= minimumRelevance && hit.channels.includes("semantic")).sort((left, right) => right.relevance - left.relevance).slice(0, limit));
+        },
+    });
+}

package/dist/natural-language-structured-decode.d.ts

@@ -0,0 +1,2 @@
+import { type ExtractedWorldFact, type NaturalLanguageChunk } from "./natural-language-world-types.js";
+export declare function decodeWorldFactExtractionResult(value: unknown, chunk: NaturalLanguageChunk): readonly ExtractedWorldFact[];

package/dist/natural-language-structured-decode.js

@@ -0,0 +1,69 @@
+import { canonicalTmwJsonValue, requireTmwIdentifier } from "./runtime-trace.js";
+import { WORLD_FACT_EXTRACTION_RESULT_SCHEMA } from "./natural-language-world-types.js";
+function record(value, code) {
+    if (typeof value !== "object" || value === null || Array.isArray(value) || (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null))
+        throw new Error(code);
+    return value;
+}
+function exactKeys(value, keys, code) {
+    const actual = Object.keys(value).sort();
+    const expected = [...keys].sort();
+    if (actual.length !== expected.length || actual.some((key, index) => key !== expected[index]))
+        throw new Error(code);
+}
+function text(value, code, maximum = 4_096) {
+    if (typeof value !== "string" || value.length === 0 || value.length > maximum || value.trim() !== value || value.normalize("NFC") !== value)
+        throw new Error(code);
+    return value;
+}
+function decodeEntity(value, code) {
+    const input = record(value, code);
+    exactKeys(input, ["id", "label"], code);
+    return Object.freeze({ id: requireTmwIdentifier(text(input.id, code), code), label: text(input.label, code) });
+}
+function decodeValue(value) {
+    const input = record(value, "world_fact_object_invalid");
+    exactKeys(input, ["type", "value"], "world_fact_object_shape_invalid");
+    switch (input.type) {
+        case "string": return Object.freeze({ type: "string", value: text(input.value, "world_fact_string_invalid", 32_768) });
+        case "number":
+            if (typeof input.value !== "number" || !Number.isFinite(input.value))
+                throw new Error("world_fact_number_invalid");
+            return Object.freeze({ type: "number", value: Object.is(input.value, -0) ? 0 : input.value });
+        case "boolean":
+            if (typeof input.value !== "boolean")
+                throw new Error("world_fact_boolean_invalid");
+            return Object.freeze({ type: "boolean", value: input.value });
+        case "entity": return Object.freeze({ type: "entity", value: decodeEntity(input.value, "world_fact_entity_object_invalid") });
+        case "json": return Object.freeze({ type: "json", value: canonicalTmwJsonValue(input.value, "world_fact_json") });
+        default: throw new Error("world_fact_object_type_invalid");
+    }
+}
+export function decodeWorldFactExtractionResult(value, chunk) {
+    const input = record(value, "world_fact_extraction_result_invalid");
+    exactKeys(input, ["schema", "facts"], "world_fact_extraction_result_shape_invalid");
+    if (input.schema !== WORLD_FACT_EXTRACTION_RESULT_SCHEMA || !Array.isArray(input.facts))
+        throw new Error("world_fact_extraction_result_schema_invalid");
+    return Object.freeze(input.facts.map((item, index) => {
+        const fact = record(item, `world_fact_${index}_invalid`);
+        exactKeys(fact, ["kind", "subject", "predicate", "object", "qualifiers", "confidence", "evidence"], `world_fact_${index}_shape_invalid`);
+        if (fact.kind !== "entity" && fact.kind !== "attribute" && fact.kind !== "relation" && fact.kind !== "event")
+            throw new Error(`world_fact_${index}_kind_invalid`);
+        if (typeof fact.confidence !== "number" || !Number.isFinite(fact.confidence) || fact.confidence < 0 || fact.confidence > 1)
+            throw new Error(`world_fact_${index}_confidence_invalid`);
+        const evidence = record(fact.evidence, `world_fact_${index}_evidence_invalid`);
+        exactKeys(evidence, ["startOffset", "endOffset", "quote"], `world_fact_${index}_evidence_shape_invalid`);
+        if (!Number.isSafeInteger(evidence.startOffset) || !Number.isSafeInteger(evidence.endOffset))
+            throw new Error(`world_fact_${index}_evidence_offset_invalid`);
+        const startOffset = evidence.startOffset;
+        const endOffset = evidence.endOffset;
+        if (startOffset < 0 || endOffset <= startOffset || endOffset > chunk.text.length)
+            throw new Error(`world_fact_${index}_evidence_range_invalid`);
+        if (typeof evidence.quote !== "string" || chunk.text.slice(startOffset, endOffset) !== evidence.quote)
+            throw new Error(`world_fact_${index}_evidence_quote_mismatch`);
+        const qualifiersValue = canonicalTmwJsonValue(fact.qualifiers, `world_fact_${index}_qualifiers`);
+        if (typeof qualifiersValue !== "object" || qualifiersValue === null || Array.isArray(qualifiersValue))
+            throw new Error(`world_fact_${index}_qualifiers_invalid`);
+        return Object.freeze({ kind: fact.kind, subject: decodeEntity(fact.subject, `world_fact_${index}_subject_invalid`), predicate: requireTmwIdentifier(text(fact.predicate, `world_fact_${index}_predicate_invalid`), `world_fact_${index}_predicate`), object: decodeValue(fact.object), qualifiers: qualifiersValue, confidence: fact.confidence, evidence: Object.freeze({ startOffset, endOffset, quote: evidence.quote }) });
+    }));
+}

package/dist/natural-language-world-types.d.ts

@@ -0,0 +1,142 @@
+import type { TmwJsonValue } from "./runtime-contract.js";
+import type { LadybugExtractionBatch } from "@world-engines/protocol-ts";
+export type { LadybugExtractionBatch } from "@world-engines/protocol-ts";
+export declare const WORLD_FACT_EXTRACTION_REQUEST_SCHEMA: "tmw-world-fact-extraction-request.v1";
+export declare const WORLD_FACT_EXTRACTION_RESULT_SCHEMA: "tmw-world-fact-extraction-result.v1";
+export type WorldFactKind = "entity" | "attribute" | "relation" | "event";
+export type WorldFactValue = Readonly<{
+    type: "string";
+    value: string;
+}> | Readonly<{
+    type: "number";
+    value: number;
+}> | Readonly<{
+    type: "boolean";
+    value: boolean;
+}> | Readonly<{
+    type: "entity";
+    value: Readonly<{
+        id: string;
+        label: string;
+    }>;
+}> | Readonly<{
+    type: "json";
+    value: TmwJsonValue;
+}>;
+export interface NaturalLanguageSource {
+    readonly scopeId: string;
+    readonly sourceId: string;
+    readonly sourcePath?: string;
+    readonly sourceRevision: string;
+    readonly text: string;
+    readonly mediaType?: "text/plain" | "text/markdown";
+}
+export interface NaturalLanguageChunk {
+    readonly index: number;
+    readonly startOffset: number;
+    readonly endOffset: number;
+    readonly text: string;
+    readonly sha256: string;
+}
+export interface ExtractedWorldFact {
+    readonly kind: WorldFactKind;
+    readonly subject: Readonly<{
+        id: string;
+        label: string;
+    }>;
+    readonly predicate: string;
+    readonly object: WorldFactValue;
+    readonly qualifiers: Readonly<Record<string, TmwJsonValue>>;
+    readonly confidence: number;
+    readonly evidence: Readonly<{
+        startOffset: number;
+        endOffset: number;
+        quote: string;
+    }>;
+}
+export interface WorldFactProvenance {
+    readonly sourceId: string;
+    readonly sourceRevision: string;
+    readonly sourceSha256: string;
+    readonly chunkIndex: number;
+    readonly chunkSha256: string;
+    readonly startOffset: number;
+    readonly endOffset: number;
+    readonly quote: string;
+}
+export interface WorldFactRecord {
+    readonly factId: string;
+    readonly scopeId: string;
+    readonly kind: WorldFactKind;
+    readonly subject: Readonly<{
+        id: string;
+        label: string;
+    }>;
+    readonly predicate: string;
+    readonly object: WorldFactValue;
+    readonly qualifiers: Readonly<Record<string, TmwJsonValue>>;
+    readonly confidence: number;
+    readonly provenance: readonly WorldFactProvenance[];
+}
+export interface WorldFactExtractionRequest {
+    readonly schema: typeof WORLD_FACT_EXTRACTION_REQUEST_SCHEMA;
+    readonly source: Readonly<{
+        scopeId: string;
+        sourceId: string;
+        sourceRevision: string;
+        sourceSha256: string;
+    }>;
+    readonly chunk: NaturalLanguageChunk;
+    readonly outputSchema: typeof WORLD_FACT_EXTRACTION_RESULT_SCHEMA;
+}
+export interface WorldFactExtractionPort {
+    readonly harness: string;
+    readonly model?: string;
+    readonly contractVersion: string;
+    /** 必须调用真实用户 harness/LLM；返回值会按 closed schema 严格解码。 */
+    extract(request: WorldFactExtractionRequest): Promise<unknown>;
+}
+export interface WorldFactCommitReceipt {
+    readonly status: "committed" | "already_committed";
+    readonly version: string;
+    readonly batchId: string;
+    readonly sourceSha256: string;
+    readonly chunkCount: number;
+    readonly factCount: number;
+}
+export interface WorldFactRecallHit {
+    readonly fact: WorldFactRecord;
+    readonly relevance: number;
+    readonly channels: readonly ("keyword" | "semantic")[];
+}
+/** 只能由 ProjectHost 在 writer lease 内以 typedworld_apply 实现；Ladybug projection/cache 不是 authority。 */
+export interface TypedWorldAuthorityPort {
+    commit(batch: LadybugExtractionBatch): Promise<Readonly<{
+        status: "committed" | "already_committed";
+        version: string;
+    }>>;
+    read(input: Readonly<{
+        scopeId: string;
+        factId: string;
+    }>): Promise<WorldFactRecord | null>;
+    resolve(input: Readonly<{
+        scopeId: string;
+        query: string;
+        mode: "semantic";
+        limit: number;
+        minimumRelevance: number;
+    }>): Promise<readonly WorldFactRecallHit[]>;
+}
+export interface WorldOperations {
+    commit(source: NaturalLanguageSource): Promise<WorldFactCommitReceipt>;
+    read(input: Readonly<{
+        scopeId: string;
+        factId: string;
+    }>): Promise<WorldFactRecord | null>;
+    resolve(input: Readonly<{
+        scopeId: string;
+        query: string;
+        limit?: number;
+        minimumRelevance?: number;
+    }>): Promise<readonly WorldFactRecallHit[]>;
+}

package/dist/natural-language-world-types.js

@@ -0,0 +1,2 @@
+export const WORLD_FACT_EXTRACTION_REQUEST_SCHEMA = "tmw-world-fact-extraction-request.v1";
+export const WORLD_FACT_EXTRACTION_RESULT_SCHEMA = "tmw-world-fact-extraction-result.v1";

package/dist/neutral-source-compiler.d.ts

@@ -0,0 +1,135 @@
+import { type CompileTargetProfile } from "./compile-target-profile.js";
+import { type CompilerStageCache } from "./compiler-stage-cache.js";
+import { type CompilerStage, type CompilerStageRegistry } from "./compiler-stage-registry.js";
+import { type TmwDiagnostic } from "./diagnostics.js";
+import { type TriggerConditionNodeV3, type TriggerDocumentV3, type TriggerEdgeV3, type TriggerEffectNodeV3, type TriggerEventNodeV3, type TriggerPresentationNodeV3 } from "./trigger-document-v3.js";
+import { type PlaneGenerationV1 } from "@world-engines/spatial-authoring/plane-generation";
+import { type ProceduralWorldV1 } from "@world-engines/spatial-authoring/procedural-city";
+import { type RoadGenerationV1 } from "@world-engines/spatial-authoring/road-generation";
+import { type SpatialTemplateConfigurationV1 } from "@world-engines/spatial-authoring/spatial-templates";
+export declare const NEUTRAL_SOURCE_COMPILER_RECEIPT_SCHEMA_VERSION: 1;
+export declare const TMW_TRIGGER_SEMANTICS_STAGE_VERSION: "3";
+export declare const NEUTRAL_SPATIAL_WORLD_STAGE_VERSION: "1";
+export declare const NEUTRAL_SPATIAL_WORLD_STAGE_ID: "neutral.spatial-world";
+export declare const CURRENT_NEUTRAL_COMPILER_STAGE_VERSIONS: readonly (Readonly<{
+    stage_id: "neutral.metadata";
+    stage_version: "1";
+}> | Readonly<{
+    stage_id: "neutral.logical-graph";
+    stage_version: "1";
+}> | Readonly<{
+    stage_id: "tmw.trigger-semantics";
+    stage_version: "3";
+}> | Readonly<{
+    stage_id: "neutral.layout";
+    stage_version: "1";
+}> | Readonly<{
+    stage_id: "neutral.view-project";
+    stage_version: "1";
+}> | Readonly<{
+    stage_id: "neutral.resource-refs";
+    stage_version: "1";
+}> | Readonly<{
+    stage_id: "neutral.prompt-retrieval";
+    stage_version: "1";
+}>)[];
+/** 空间发布 profile 必须显式绑定新 stage，旧七阶段 profile 保持可重放。 */
+export declare const SPATIAL_NEUTRAL_COMPILER_STAGE_VERSIONS: readonly (Readonly<{
+    stage_id: "neutral.metadata";
+    stage_version: "1";
+}> | Readonly<{
+    stage_id: "neutral.logical-graph";
+    stage_version: "1";
+}> | Readonly<{
+    stage_id: "tmw.trigger-semantics";
+    stage_version: "3";
+}> | Readonly<{
+    stage_id: "neutral.layout";
+    stage_version: "1";
+}> | Readonly<{
+    stage_id: "neutral.view-project";
+    stage_version: "1";
+}> | Readonly<{
+    stage_id: "neutral.resource-refs";
+    stage_version: "1";
+}> | Readonly<{
+    stage_id: "neutral.prompt-retrieval";
+    stage_version: "1";
+}> | Readonly<{
+    stage_id: "neutral.spatial-world";
+    stage_version: "1";
+}>)[];
+export interface NeutralSourceDerivedObject {
+    readonly stage_id: string;
+    readonly stage_version: string;
+    readonly media_type: "application/octet-stream";
+    readonly bytes: Uint8Array;
+    readonly byte_length: number;
+    readonly sha256: string;
+}
+export interface NeutralSourceCompilerStageReceipt {
+    readonly stage_id: string;
+    readonly stage_version: string;
+    readonly cache_key: string;
+    readonly content_cache_key: string;
+    readonly input_sections: readonly Readonly<{
+        section_key: string;
+        sha256: string;
+    }>[];
+    readonly dependency_outputs: readonly Readonly<{
+        stage_id: string;
+        sha256: string;
+    }>[];
+    readonly output_byte_length: number;
+    readonly output_sha256: string;
+}
+export interface NeutralSourceCompilerReceiptCore {
+    readonly receipt_schema_version: typeof NEUTRAL_SOURCE_COMPILER_RECEIPT_SCHEMA_VERSION;
+    readonly scenario_id: string;
+    readonly source_manifest_sha256: string;
+    readonly compiler_release: string;
+    readonly target_profile_sha256: string;
+    readonly stages: readonly NeutralSourceCompilerStageReceipt[];
+    readonly derived_objects_sha256: string;
+}
+export interface NeutralSourceCompilerReceipt extends NeutralSourceCompilerReceiptCore {
+    readonly receipt_sha256: string;
+}
+export type CompileNeutralScenarioSourceOutcome = {
+    readonly ok: true;
+    readonly derived_objects: readonly NeutralSourceDerivedObject[];
+    readonly receipt: NeutralSourceCompilerReceipt;
+    readonly diagnostics: readonly TmwDiagnostic[];
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly TmwDiagnostic[];
+};
+export interface NeutralTriggerSemantics {
+    readonly value_graph?: import("./value-graph.js").TmwValueGraphV1;
+    readonly events: readonly TriggerEventNodeV3[];
+    readonly conditions: readonly TriggerConditionNodeV3[];
+    readonly effects: readonly TriggerEffectNodeV3[];
+    readonly presentations: readonly TriggerPresentationNodeV3[];
+    readonly edges: readonly TriggerEdgeV3[];
+}
+export interface NeutralCompiledSpatialBase {
+    readonly generation: PlaneGenerationV1;
+    readonly procedural: ProceduralWorldV1;
+    /** 缺席时严格保留 procedural-world-v1 的既有道路语义。 */
+    readonly roadGeneration?: RoadGenerationV1;
+    /** 仅 active template snapshot；作者 templateLibrary 不进入 Player 产物。 */
+    readonly templates?: SpatialTemplateConfigurationV1;
+    readonly baseDigest: string;
+    readonly controlledActorId?: string;
+}
+export type NeutralSpatialWorldUnsupportedReason = "topology_missing" | "topology_not_plane" | "generation_missing" | "procedural_missing";
+export interface NeutralSpatialWorldUnsupported {
+    readonly player_programmatic_supported: false;
+    readonly reason: NeutralSpatialWorldUnsupportedReason;
+}
+export declare function createNeutralSpatialWorldCompilerStage(): CompilerStage;
+export declare function neutralTriggerSemanticsFromDocument(document: TriggerDocumentV3): NeutralTriggerSemantics;
+export declare function materializeTmw3TriggerDocument(value: unknown): Promise<TriggerDocumentV3>;
+export declare function compileNeutralScenarioSource(input: unknown, targetProfile: CompileTargetProfile, registry: CompilerStageRegistry, cache: CompilerStageCache): Promise<CompileNeutralScenarioSourceOutcome>;
+export declare function canonicalNeutralSourceCompilerReceiptBytes(receipt: NeutralSourceCompilerReceipt): Uint8Array;
+export declare function buildCurrentTmw3NeutralCompilerStageRegistry(profile?: CompileTargetProfile): CompilerStageRegistry;