@world-engines/tmw 0.1.0-alpha.0

package/dist/neutral-source-compiler.js

@@ -0,0 +1,608 @@
+import { compileTargetProfileDigest, parseCompileTargetProfile, } from "./compile-target-profile.js";
+import { compilerStageContentCacheKey, compilerStageCacheKey, } from "./compiler-stage-cache.js";
+import { assertRegistryMatchesTargetProfile, buildCompilerStageRegistry, createPassThroughCompilerStage, } from "./compiler-stage-registry.js";
+import { orderTmwDiagnostics, tmwDiagnostic, } from "./diagnostics.js";
+import { getCanonicalTmwCapabilityRegistryV3, } from "./capability-registry.js";
+import { compileTmw3 } from "./compiler.js";
+import { initialTmwSceneFromMetadata } from "./scene-author-source.js";
+import { parseTriggerDocumentV3, } from "./trigger-document-v3.js";
+import { canonicalTmwBytes, isSha256Hex, runtimeContractHashV3, TMW_RUNTIME_GENERATION, TRIGGER_DOCUMENT_V3_VERSION, tmwSha256Hex, } from "./runtime-contract.js";
+import { SpatialTopologyV1_Kind, SpatialWorldSourceV1, } from "@world-engines/protocol-ts/v1/scenario_part_source";
+import { validatePlaneGeneration, } from "@world-engines/spatial-authoring/plane-generation";
+import { validateProceduralWorld, } from "@world-engines/spatial-authoring/procedural-city";
+import { validateRoadGeneration, } from "@world-engines/spatial-authoring/road-generation";
+import { validateSpatialTemplateConfiguration, } from "@world-engines/spatial-authoring/spatial-templates";
+export const NEUTRAL_SOURCE_COMPILER_RECEIPT_SCHEMA_VERSION = 1;
+export const TMW_TRIGGER_SEMANTICS_STAGE_VERSION = "3";
+export const NEUTRAL_SPATIAL_WORLD_STAGE_VERSION = "1";
+export const NEUTRAL_SPATIAL_WORLD_STAGE_ID = "neutral.spatial-world";
+export const CURRENT_NEUTRAL_COMPILER_STAGE_VERSIONS = Object.freeze([
+    Object.freeze({ stage_id: "neutral.metadata", stage_version: "1" }),
+    Object.freeze({ stage_id: "neutral.logical-graph", stage_version: "1" }),
+    Object.freeze({
+        stage_id: "tmw.trigger-semantics",
+        stage_version: TMW_TRIGGER_SEMANTICS_STAGE_VERSION,
+    }),
+    Object.freeze({ stage_id: "neutral.layout", stage_version: "1" }),
+    Object.freeze({ stage_id: "neutral.view-project", stage_version: "1" }),
+    Object.freeze({ stage_id: "neutral.resource-refs", stage_version: "1" }),
+    Object.freeze({ stage_id: "neutral.prompt-retrieval", stage_version: "1" }),
+]);
+/** 空间发布 profile 必须显式绑定新 stage，旧七阶段 profile 保持可重放。 */
+export const SPATIAL_NEUTRAL_COMPILER_STAGE_VERSIONS = Object.freeze([
+    ...CURRENT_NEUTRAL_COMPILER_STAGE_VERSIONS,
+    Object.freeze({ stage_id: NEUTRAL_SPATIAL_WORLD_STAGE_ID, stage_version: NEUTRAL_SPATIAL_WORLD_STAGE_VERSION }),
+]);
+const REQUIRED_SECTION_KEYS = Object.freeze([
+    "metadata",
+    "logical_graph",
+    "trigger_semantics",
+    "layout",
+    "view_project",
+    "resource_refs",
+    "prompt_retrieval",
+]);
+const SECTION_KEY_PATTERN = /^[a-z][a-z0-9_.-]{0,127}$/u;
+const HEX_PATTERN = /^[0-9a-f]{64}$/u;
+const strictDecoder = new TextDecoder("utf-8", { fatal: true });
+function compareAscii(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function bytesEqual(left, right) {
+    if (left.byteLength !== right.byteLength)
+        return false;
+    let difference = 0;
+    for (let index = 0; index < left.byteLength; index += 1) {
+        difference |= (left[index] ?? 0) ^ (right[index] ?? 0);
+    }
+    return difference === 0;
+}
+const NEUTRAL_TRIGGER_KEYS = Object.freeze([
+    "conditions",
+    "edges",
+    "effects",
+    "events",
+    "presentations",
+]);
+const EMPTY_NEUTRAL_TRIGGER_SEMANTICS = Object.freeze({
+    events: Object.freeze([]),
+    conditions: Object.freeze([]),
+    effects: Object.freeze([]),
+    presentations: Object.freeze([]),
+    edges: Object.freeze([]),
+});
+function plainObject(value, code) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error(code);
+    return value;
+}
+function parseSpatialTopologySettings(bytes) {
+    if (bytes.byteLength === 0)
+        return Object.freeze({});
+    let value;
+    try {
+        value = JSON.parse(strictDecoder.decode(bytes));
+    }
+    catch {
+        throw new Error("spatial_world_topology_settings_json_invalid");
+    }
+    return plainObject(value, "spatial_world_topology_settings_object_required");
+}
+function decodeSpatialWorldSection(section) {
+    if (section.media_type !== "application/x-protobuf"
+        || section.canonical_encoding !== "chat.v1.SpatialWorldSourceV1")
+        throw new Error("spatial_world_encoding_invalid");
+    let source;
+    try {
+        source = SpatialWorldSourceV1.decode(section.payload_bytes);
+    }
+    catch {
+        throw new Error("spatial_world_protobuf_invalid");
+    }
+    if (source.schema_version !== 1)
+        throw new Error("spatial_world_schema_version_unsupported");
+    const settings = source.topology === undefined
+        ? Object.freeze({})
+        : parseSpatialTopologySettings(source.topology.settings);
+    return Object.freeze({ source, settings });
+}
+function unsupportedSpatialWorld(reason) {
+    return Object.freeze({ player_programmatic_supported: false, reason });
+}
+export function createNeutralSpatialWorldCompilerStage() {
+    return {
+        descriptor: {
+            stage_id: NEUTRAL_SPATIAL_WORLD_STAGE_ID,
+            stage_version: NEUTRAL_SPATIAL_WORLD_STAGE_VERSION,
+            section_keys: ["spatial_world", "logical_graph"],
+            depends_on: [],
+        },
+        async execute(input) {
+            const section = input.sections.find(section => section.section_key === "spatial_world");
+            if (section === undefined || section.payload_bytes.byteLength === 0) {
+                throw new Error("spatial_world_section_missing");
+            }
+            let decoded;
+            try {
+                decoded = decodeSpatialWorldSection(section);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : "spatial_world_invalid";
+                return Object.freeze({
+                    ok: false,
+                    diagnostics: Object.freeze([tmwDiagnostic(message.split(":")[0] || "spatial_world_invalid", "$/sections/spatial_world", message)]),
+                });
+            }
+            const unsupported = (reason) => Object.freeze({
+                ok: true,
+                bytes: canonicalTmwBytes(unsupportedSpatialWorld(reason)),
+                diagnostics: Object.freeze([tmwDiagnostic("spatial_world_player_programmatic_unsupported", "$/sections/spatial_world", `spatial world is preserved but not exported to Player: ${reason}`, [], "warning")]),
+            });
+            if (decoded.source.topology === undefined)
+                return unsupported("topology_missing");
+            if (decoded.source.topology.kind !== SpatialTopologyV1_Kind.KIND_PLANE) {
+                return unsupported("topology_not_plane");
+            }
+            if (decoded.settings.generation === undefined)
+                return unsupported("generation_missing");
+            if (decoded.settings.procedural === undefined)
+                return unsupported("procedural_missing");
+            try {
+                const generation = validatePlaneGeneration(decoded.settings.generation);
+                if (generation.profile !== "plane-perlin-hydrology-v1")
+                    throw new Error("spatial_world_plane_profile_required");
+                if (decoded.settings.width !== generation.widthMeters
+                    || decoded.settings.height !== generation.heightMeters)
+                    throw new Error("spatial_world_generation_extent_mismatch");
+                const procedural = validateProceduralWorld(decoded.settings.procedural, {
+                    widthMeters: generation.widthMeters,
+                    heightMeters: generation.heightMeters,
+                });
+                if (procedural.worldSeed !== generation.seed) {
+                    throw new Error("spatial_world_procedural_seed_mismatch");
+                }
+                const roadGeneration = decoded.settings.roadGeneration === undefined
+                    ? undefined
+                    : validateRoadGeneration(decoded.settings.roadGeneration);
+                const templates = decoded.settings.templates === undefined
+                    ? undefined
+                    : validateSpatialTemplateConfiguration(decoded.settings.templates);
+                const controlledActorId = decoded.settings.controlledActorId;
+                if (controlledActorId != null) {
+                    if (typeof controlledActorId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u.test(controlledActorId))
+                        throw new Error("spatial_world_controlled_actor_invalid");
+                    const graphSection = input.sections.find(section => section.section_key === "logical_graph");
+                    if (!graphSection)
+                        throw new Error("spatial_world_controlled_actor_graph_missing");
+                    const graph = plainObject(JSON.parse(strictDecoder.decode(graphSection.payload_bytes)), "spatial_world_graph_invalid");
+                    const entities = graph.entities;
+                    if (!Array.isArray(entities) || !entities.some(entity => {
+                        const item = plainObject(entity, "spatial_world_graph_entity_invalid");
+                        return (item.entity_id ?? item.id) === controlledActorId;
+                    }))
+                        throw new Error("spatial_world_controlled_actor_not_found");
+                }
+                const digestInput = Object.freeze({
+                    generation,
+                    procedural,
+                    ...(roadGeneration === undefined ? {} : { roadGeneration }),
+                    ...(templates === undefined ? {} : { templates }),
+                    ...(controlledActorId == null ? {} : { controlledActorId }),
+                });
+                const compiled = Object.freeze({
+                    ...digestInput,
+                    baseDigest: await tmwSha256Hex(canonicalTmwBytes(digestInput)),
+                });
+                return Object.freeze({
+                    ok: true,
+                    bytes: canonicalTmwBytes(compiled),
+                    diagnostics: Object.freeze([]),
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : "spatial_world_semantics_invalid";
+                return Object.freeze({
+                    ok: false,
+                    diagnostics: Object.freeze([tmwDiagnostic(message.split(":")[0] || "spatial_world_semantics_invalid", "$/sections/spatial_world/topology/settings", message)]),
+                });
+            }
+        },
+    };
+}
+export function neutralTriggerSemanticsFromDocument(document) {
+    const parsed = parseTriggerDocumentV3(document);
+    if (!parsed.ok)
+        throw new Error("trigger_semantics_target_document_invalid");
+    return Object.freeze({
+        events: parsed.value.events,
+        conditions: parsed.value.conditions,
+        effects: parsed.value.effects,
+        presentations: parsed.value.presentations,
+        edges: parsed.value.edges,
+        ...(parsed.value.value_graph === undefined ? {} : { value_graph: parsed.value.value_graph }),
+    });
+}
+export async function materializeTmw3TriggerDocument(value) {
+    const source = plainObject(value, "trigger_semantics_object_required");
+    const actualKeys = Object.keys(source).sort();
+    const expectedKeys = source.value_graph === undefined ? NEUTRAL_TRIGGER_KEYS : [...NEUTRAL_TRIGGER_KEYS, "value_graph"].sort();
+    if (actualKeys.length !== expectedKeys.length
+        || actualKeys.some((key, index) => key !== expectedKeys[index])
+        || !Array.isArray(source.events)
+        || !Array.isArray(source.conditions)
+        || !Array.isArray(source.effects)
+        || !Array.isArray(source.presentations)
+        || !Array.isArray(source.edges)) {
+        throw new Error("trigger_semantics_fields_mismatch");
+    }
+    const registry = getCanonicalTmwCapabilityRegistryV3();
+    const document = {
+        version: TRIGGER_DOCUMENT_V3_VERSION,
+        runtime_generation: TMW_RUNTIME_GENERATION,
+        runtime_contract_hash: await runtimeContractHashV3(),
+        registry_version: registry.registry_version,
+        events: source.events,
+        conditions: source.conditions,
+        effects: source.effects,
+        presentations: source.presentations,
+        edges: source.edges,
+        ...(source.value_graph === undefined ? {} : { value_graph: source.value_graph }),
+    };
+    const parsed = parseTriggerDocumentV3(document);
+    if (!parsed.ok) {
+        throw new Error(`trigger_semantics_invalid:${parsed.diagnostics.map((item) => item.code).join(",")}`);
+    }
+    return parsed.value;
+}
+function requireString(value, code) {
+    if (typeof value !== "string"
+        || value.length === 0
+        || value !== value.trim().normalize("NFC"))
+        throw new Error(code);
+    return value;
+}
+function requireSha256(value, code) {
+    if (typeof value !== "string" || !HEX_PATTERN.test(value))
+        throw new Error(code);
+    return value;
+}
+function sha256BytesToHex(value, code) {
+    if (!(value instanceof Uint8Array) || value.byteLength !== 32)
+        throw new Error(code);
+    return Array.from(value, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function normalizeCompileInput(value) {
+    const root = plainObject(value, "neutral_compile_input_object_required");
+    const witness = plainObject(root.witness, "neutral_compile_input_witness_required");
+    const manifest = plainObject(root.manifest, "neutral_compile_input_manifest_required");
+    const scenarioId = requireString(witness.scenario_id, "neutral_compile_scenario_id_invalid");
+    if (manifest.scenario_id !== scenarioId)
+        throw new Error("neutral_compile_scenario_mismatch");
+    const manifestDigest = requireSha256(witness.manifest_digest, "neutral_compile_manifest_digest_invalid");
+    if (sha256BytesToHex(manifest.manifest_sha256, "neutral_compile_manifest_sha256_invalid") !== manifestDigest)
+        throw new Error("neutral_compile_manifest_digest_mismatch");
+    if (!Array.isArray(root.sections) || !Array.isArray(manifest.sections)) {
+        throw new Error("neutral_compile_sections_required");
+    }
+    const identities = new Map();
+    for (const [index, value] of manifest.sections.entries()) {
+        const identity = plainObject(value, `neutral_compile_section_identity_invalid:${index}`);
+        const sectionKey = requireString(identity.section_key, `neutral_compile_section_key_invalid:${index}`);
+        if (!SECTION_KEY_PATTERN.test(sectionKey)) {
+            throw new Error(`neutral_compile_section_key_invalid:${index}`);
+        }
+        if (identities.has(sectionKey))
+            throw new Error("neutral_compile_section_key_duplicate");
+        identities.set(sectionKey, identity);
+    }
+    const sections = root.sections.map((value, index) => {
+        const section = plainObject(value, `neutral_compile_section_invalid:${index}`);
+        const sectionKey = requireString(section.section_key, `neutral_compile_section_key_invalid:${index}`);
+        const identity = identities.get(sectionKey);
+        if (identity === undefined)
+            throw new Error("neutral_compile_section_identity_missing");
+        const mediaType = requireString(section.media_type, `neutral_compile_section_media_type_invalid:${sectionKey}`);
+        const canonicalEncoding = requireString(section.canonical_encoding, `neutral_compile_section_encoding_invalid:${sectionKey}`);
+        if (identity.media_type !== mediaType
+            || identity.canonical_encoding !== canonicalEncoding)
+            throw new Error(`neutral_compile_section_descriptor_mismatch:${sectionKey}`);
+        if (!(section.payload instanceof Uint8Array)) {
+            throw new Error(`neutral_compile_section_payload_invalid:${sectionKey}`);
+        }
+        if (typeof identity.byte_length !== "string" || !/^(?:0|[1-9][0-9]*)$/u.test(identity.byte_length)) {
+            throw new Error(`neutral_compile_section_byte_length_invalid:${sectionKey}`);
+        }
+        const byteLength = Number(identity.byte_length);
+        if (!Number.isSafeInteger(byteLength)) {
+            throw new Error(`neutral_compile_section_byte_length_invalid:${sectionKey}`);
+        }
+        return Object.freeze({
+            section_key: sectionKey,
+            media_type: mediaType,
+            canonical_encoding: canonicalEncoding,
+            byte_length: byteLength,
+            sha256: sha256BytesToHex(identity.sha256, `neutral_compile_section_sha256_invalid:${sectionKey}`),
+            payload_bytes: section.payload.slice(),
+        });
+    }).sort((left, right) => compareAscii(left.section_key, right.section_key));
+    if (sections.length !== identities.size
+        || new Set(sections.map((section) => section.section_key)).size !== sections.length)
+        throw new Error("neutral_compile_section_set_mismatch");
+    for (const required of REQUIRED_SECTION_KEYS) {
+        if (!identities.has(required))
+            throw new Error(`neutral_compile_required_section_missing:${required}`);
+    }
+    return Object.freeze({
+        scenario_id: scenarioId,
+        source_manifest_sha256: manifestDigest,
+        sections: Object.freeze(sections),
+    });
+}
+function cloneSection(section) {
+    return Object.freeze({ ...section, payload_bytes: section.payload_bytes.slice() });
+}
+function cloneDependency(output) {
+    return Object.freeze({ ...output, bytes: output.bytes.slice() });
+}
+async function readValidCacheEntry(cache, cacheKey) {
+    const entry = await cache.read(cacheKey);
+    if (entry === null)
+        return null;
+    if (entry.cache_key !== cacheKey
+        || !isSha256Hex(entry.output_sha256)
+        || await tmwSha256Hex(entry.bytes) !== entry.output_sha256
+        || entry.diagnostics.some((diagnostic) => diagnostic.severity === "error")) {
+        await cache.delete(cacheKey);
+        return null;
+    }
+    return entry;
+}
+function compilerFailure(error) {
+    const message = error instanceof Error ? error.message : "neutral_source_compile_failed";
+    const code = message.split(":")[0] || "neutral_source_compile_failed";
+    return Object.freeze({
+        ok: false,
+        diagnostics: Object.freeze([tmwDiagnostic(code, "$", message)]),
+    });
+}
+export async function compileNeutralScenarioSource(input, targetProfile, registry, cache) {
+    try {
+        const source = normalizeCompileInput(input);
+        // 初始 Scene 属于 metadata 原始 authority；在缓存读取前验证，输出保持逐字手稿。
+        const metadata = source.sections.find((section) => section.section_key === "metadata");
+        if (metadata !== undefined && metadata.payload_bytes.byteLength > 0
+            && metadata.media_type === "application/json") {
+            const metadataModel = plainObject(JSON.parse(strictDecoder.decode(metadata.payload_bytes)), "metadata_object_required");
+            if (metadataModel.metadata === null) {
+                if (metadataModel.initial_scene !== undefined && metadataModel.initial_scene !== null)
+                    throw new Error("metadata_object_required");
+                initialTmwSceneFromMetadata(Object.freeze({}));
+            }
+            else {
+                initialTmwSceneFromMetadata(metadataModel.metadata === undefined
+                    ? metadataModel : plainObject(metadataModel.metadata, "metadata_object_required"));
+            }
+        }
+        const profile = parseCompileTargetProfile(targetProfile);
+        assertRegistryMatchesTargetProfile(registry, profile);
+        const targetProfileSha256 = await compileTargetProfileDigest(profile);
+        const derivedObjects = [];
+        const stageReceipts = [];
+        const diagnostics = [];
+        const outputByStage = new Map();
+        const spatialSection = source.sections.find((section) => section.section_key === "spatial_world");
+        if (spatialSection !== undefined && spatialSection.payload_bytes.byteLength > 0
+            && !registry.stages.some(stage => stage.descriptor.stage_id === NEUTRAL_SPATIAL_WORLD_STAGE_ID)) {
+            throw new Error("spatial_world_compiler_profile_required");
+        }
+        for (const stage of registry.stages) {
+            const stageSections = stage.descriptor.section_keys.map((sectionKey) => {
+                const section = source.sections.find((candidate) => candidate.section_key === sectionKey);
+                if (section === undefined)
+                    throw new Error(`compiler_stage_section_missing:${sectionKey}`);
+                return section;
+            });
+            const dependencies = stage.descriptor.depends_on.map((stageId) => {
+                const output = outputByStage.get(stageId);
+                if (output === undefined)
+                    throw new Error(`compiler_stage_dependency_output_missing:${stageId}`);
+                return output;
+            });
+            const cacheIdentity = {
+                scenario_id: source.scenario_id,
+                source_manifest_sha256: source.source_manifest_sha256,
+                stage_id: stage.descriptor.stage_id,
+                stage_version: stage.descriptor.stage_version,
+                target_profile_sha256: targetProfileSha256,
+                section_sha256s: stageSections.map((section) => ({
+                    section_key: section.section_key,
+                    sha256: section.sha256,
+                })),
+                dependency_sha256s: dependencies.map((dependency) => ({
+                    stage_id: dependency.stage_id,
+                    sha256: dependency.sha256,
+                })),
+            };
+            const cacheKey = await compilerStageCacheKey(cacheIdentity);
+            const contentCacheKey = await compilerStageContentCacheKey(cacheIdentity);
+            let entry = await readValidCacheEntry(cache, contentCacheKey);
+            if (entry === null) {
+                const result = await stage.execute(Object.freeze({
+                    scenario_id: source.scenario_id,
+                    target_profile: profile,
+                    target_profile_sha256: targetProfileSha256,
+                    sections: Object.freeze(stageSections.map(cloneSection)),
+                    dependency_outputs: Object.freeze(dependencies.map(cloneDependency)),
+                }));
+                diagnostics.push(...result.diagnostics);
+                if (!result.ok || result.diagnostics.some((diagnostic) => diagnostic.severity === "error")) {
+                    return Object.freeze({
+                        ok: false,
+                        diagnostics: orderTmwDiagnostics(diagnostics),
+                    });
+                }
+                if (!(result.bytes instanceof Uint8Array))
+                    throw new Error("compiler_stage_output_bytes_invalid");
+                entry = Object.freeze({
+                    cache_key: contentCacheKey,
+                    bytes: result.bytes.slice(),
+                    output_sha256: await tmwSha256Hex(result.bytes),
+                    diagnostics: orderTmwDiagnostics(result.diagnostics),
+                });
+                await cache.writeOnce(entry);
+            }
+            else {
+                diagnostics.push(...entry.diagnostics);
+            }
+            const derivedObject = Object.freeze({
+                stage_id: stage.descriptor.stage_id,
+                stage_version: stage.descriptor.stage_version,
+                media_type: "application/octet-stream",
+                bytes: entry.bytes.slice(),
+                byte_length: entry.bytes.byteLength,
+                sha256: entry.output_sha256,
+            });
+            derivedObjects.push(derivedObject);
+            outputByStage.set(stage.descriptor.stage_id, Object.freeze({
+                stage_id: stage.descriptor.stage_id,
+                stage_version: stage.descriptor.stage_version,
+                bytes: entry.bytes.slice(),
+                sha256: entry.output_sha256,
+            }));
+            stageReceipts.push(Object.freeze({
+                stage_id: stage.descriptor.stage_id,
+                stage_version: stage.descriptor.stage_version,
+                cache_key: cacheKey,
+                content_cache_key: contentCacheKey,
+                input_sections: Object.freeze(stageSections.map((section) => Object.freeze({
+                    section_key: section.section_key,
+                    sha256: section.sha256,
+                }))),
+                dependency_outputs: Object.freeze(dependencies.map((dependency) => Object.freeze({
+                    stage_id: dependency.stage_id,
+                    sha256: dependency.sha256,
+                }))),
+                output_byte_length: entry.bytes.byteLength,
+                output_sha256: entry.output_sha256,
+            }));
+        }
+        const derivedObjectsSha256 = await tmwSha256Hex(canonicalTmwBytes(derivedObjects.map((object) => ({
+            stage_id: object.stage_id,
+            stage_version: object.stage_version,
+            media_type: object.media_type,
+            byte_length: object.byte_length,
+            sha256: object.sha256,
+        }))));
+        const receiptCore = Object.freeze({
+            receipt_schema_version: NEUTRAL_SOURCE_COMPILER_RECEIPT_SCHEMA_VERSION,
+            scenario_id: source.scenario_id,
+            source_manifest_sha256: source.source_manifest_sha256,
+            compiler_release: profile.compiler_release,
+            target_profile_sha256: targetProfileSha256,
+            stages: Object.freeze(stageReceipts),
+            derived_objects_sha256: derivedObjectsSha256,
+        });
+        const receipt = Object.freeze({
+            ...receiptCore,
+            receipt_sha256: await tmwSha256Hex(canonicalTmwBytes(receiptCore)),
+        });
+        return Object.freeze({
+            ok: true,
+            derived_objects: Object.freeze(derivedObjects),
+            receipt,
+            diagnostics: orderTmwDiagnostics(diagnostics),
+        });
+    }
+    catch (error) {
+        return compilerFailure(error);
+    }
+}
+export function canonicalNeutralSourceCompilerReceiptBytes(receipt) {
+    const { receipt_sha256: _digest, ...core } = receipt;
+    return canonicalTmwBytes(core);
+}
+function createTmw3TriggerCompilerStage() {
+    return {
+        descriptor: {
+            stage_id: "tmw.trigger-semantics",
+            stage_version: TMW_TRIGGER_SEMANTICS_STAGE_VERSION,
+            section_keys: ["trigger_semantics"],
+            depends_on: [],
+        },
+        async execute(input) {
+            const section = input.sections[0];
+            if (section === undefined)
+                throw new Error("trigger_semantics_section_missing");
+            const acceptedEmpty = section.payload_bytes.byteLength === 0
+                && section.media_type === "application/octet-stream"
+                && section.canonical_encoding === "opaque-bytes-v1";
+            if (!acceptedEmpty
+                && (section.media_type !== "application/json"
+                    || section.canonical_encoding !== "canonical-json-v1")) {
+                return Object.freeze({
+                    ok: false,
+                    diagnostics: Object.freeze([tmwDiagnostic("trigger_semantics_encoding_invalid", "$/sections/trigger_semantics", "trigger semantics must use canonical-json-v1 application/json")]),
+                });
+            }
+            let semantics;
+            if (acceptedEmpty) {
+                semantics = EMPTY_NEUTRAL_TRIGGER_SEMANTICS;
+            }
+            else {
+                try {
+                    semantics = JSON.parse(strictDecoder.decode(section.payload_bytes));
+                }
+                catch {
+                    return Object.freeze({
+                        ok: false,
+                        diagnostics: Object.freeze([tmwDiagnostic("trigger_semantics_json_invalid", "$/sections/trigger_semantics", "trigger semantics is not valid UTF-8 JSON")]),
+                    });
+                }
+                if (!bytesEqual(section.payload_bytes, canonicalTmwBytes(semantics))) {
+                    return Object.freeze({
+                        ok: false,
+                        diagnostics: Object.freeze([tmwDiagnostic("trigger_semantics_canonical_bytes_invalid", "$/sections/trigger_semantics", "trigger semantics bytes do not match canonical-json-v1")]),
+                    });
+                }
+            }
+            let document;
+            try {
+                document = await materializeTmw3TriggerDocument(semantics);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : "trigger_semantics_invalid";
+                return Object.freeze({
+                    ok: false,
+                    diagnostics: Object.freeze([tmwDiagnostic(message.split(":")[0] || "trigger_semantics_invalid", "$/sections/trigger_semantics", message)]),
+                });
+            }
+            const compiled = await compileTmw3(document, getCanonicalTmwCapabilityRegistryV3());
+            if (!compiled.ok)
+                return compiled;
+            return Object.freeze({
+                ok: true,
+                bytes: canonicalTmwBytes(compiled.plan),
+                diagnostics: compiled.diagnostics,
+            });
+        },
+    };
+}
+export function buildCurrentTmw3NeutralCompilerStageRegistry(profile) {
+    const passThrough = (stageId, sectionKey) => createPassThroughCompilerStage({
+        stage_id: stageId,
+        stage_version: "1",
+        section_keys: [sectionKey],
+        depends_on: [],
+    });
+    return buildCompilerStageRegistry([
+        passThrough("neutral.metadata", "metadata"),
+        passThrough("neutral.logical-graph", "logical_graph"),
+        createTmw3TriggerCompilerStage(),
+        passThrough("neutral.layout", "layout"),
+        passThrough("neutral.view-project", "view_project"),
+        passThrough("neutral.resource-refs", "resource_refs"),
+        passThrough("neutral.prompt-retrieval", "prompt_retrieval"),
+        ...(profile?.stage_versions.some(stage => stage.stage_id === NEUTRAL_SPATIAL_WORLD_STAGE_ID)
+            ? [createNeutralSpatialWorldCompilerStage()] : []),
+    ]);
+}

package/dist/presentation-intent.d.ts

@@ -0,0 +1,42 @@
+import type { TMW_RUNTIME_GENERATION } from "./runtime-contract.js";
+import type { TmwJsonValue } from "./runtime-contract.js";
+import type { TmwActivationCandidateV3, TmwActivationReceiptV3 } from "./activation.js";
+export type PresentationIntentKind = "view" | "atmosphere" | "music";
+export interface ViewPresentationPayloadV3 {
+    readonly kind: "view";
+    readonly overlay_id: string;
+    readonly visible: boolean;
+}
+export interface AtmospherePresentationPayloadV3 {
+    readonly kind: "atmosphere";
+    readonly atmosphere_id: string | null;
+    readonly intensity: number;
+}
+export interface MusicPresentationPayloadV3 {
+    readonly kind: "music";
+    readonly candidate_set_id: string;
+    readonly candidate_set_revision: number;
+    readonly preferred_resource_id: string | null;
+}
+export type PresentationPayloadV3 = ViewPresentationPayloadV3 | AtmospherePresentationPayloadV3 | MusicPresentationPayloadV3;
+export interface PresentationIntentV3 {
+    readonly schema: "presentation-intent.v3";
+    readonly generation: typeof TMW_RUNTIME_GENERATION;
+    readonly intent_id: string;
+    readonly epoch: number;
+    readonly artifact_digest: string;
+    readonly timeline_revision: string;
+    readonly activation_id: string;
+    readonly dedupe_key: string;
+    readonly sequence: number;
+    readonly payload: PresentationPayloadV3;
+    readonly metadata: Readonly<Record<string, TmwJsonValue>>;
+}
+export interface CommittedPresentationActivationV3 {
+    readonly candidate: TmwActivationCandidateV3;
+    readonly receipt: TmwActivationReceiptV3;
+}
+export declare const parsePresentationPayloadV3: (value: unknown) => PresentationPayloadV3 | null;
+export declare const parsePresentationIntentV3: (value: unknown) => PresentationIntentV3 | null;
+export declare const committedPresentationActivationError: (activation: CommittedPresentationActivationV3) => string | null;
+export declare const presentationIntentError: (intent: PresentationIntentV3, activation: CommittedPresentationActivationV3) => string | null;