@world-engines/tmw 0.1.0-alpha.0

package/dist/builder-diagnostics.d.ts

@@ -0,0 +1,3 @@
+import { type TmwResult } from "./diagnostics.js";
+export declare const builderStableIdError: (stableId: string, path: string) => TmwResult<never> | null;
+export declare const builderFailure: <T>(code: string, path: string, message: string, relatedStableIds?: readonly string[]) => TmwResult<T>;

package/dist/builder-diagnostics.js

@@ -0,0 +1,8 @@
+import { tmwDiagnostic, tmwFailure } from "./diagnostics.js";
+const STABLE_ID = /^[a-z0-9](?:[a-z0-9._:-]{0,127})$/u;
+export const builderStableIdError = (stableId, path) => STABLE_ID.test(stableId) && stableId.normalize("NFC") === stableId
+    ? null
+    : tmwFailure([tmwDiagnostic("stable_id_invalid", path, "stable_id is required and must be canonical", stableId.length === 0 ? [] : [stableId])]);
+export const builderFailure = (code, path, message, relatedStableIds = []) => tmwFailure([
+    tmwDiagnostic(code, path, message, relatedStableIds),
+]);

package/dist/builder-node.d.ts

@@ -0,0 +1,178 @@
+import type { TriggerConditionNodeV3, TriggerEffectNodeV3, TriggerEventNodeV3, TriggerNodeV3, TriggerPresentationNodeV3 } from "./trigger-document-v3.js";
+import { z } from "zod";
+export declare const tmwStableIdSchema: z.ZodString;
+export declare const tmwBuilderCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    operation: z.ZodLiteral<"add_event">;
+    node: z.ZodObject<{
+        kind: z.ZodLiteral<"event">;
+        stable_id: z.ZodString;
+        enabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        event_type: z.ZodString;
+        hard_fact: z.ZodBoolean;
+        effective_time: z.ZodObject<{
+            domain: z.ZodEnum<{
+                logical_seq: "logical_seq";
+                world_time: "world_time";
+                presentation_seq: "presentation_seq";
+                real_time: "real_time";
+            }>;
+            due_value: z.ZodNumber;
+            effective_value: z.ZodNumber;
+            crossing_policy: z.ZodEnum<{
+                forward_only: "forward_only";
+                backward_only: "backward_only";
+                both_directions: "both_directions";
+            }>;
+            real_time_clock: z.ZodNullable<z.ZodEnum<{
+                monotonic_session: "monotonic_session";
+                active_play: "active_play";
+                wall_clock: "wall_clock";
+            }>>;
+            wall_clock_policy: z.ZodNullable<z.ZodEnum<{
+                elapse_while_suspended: "elapse_while_suspended";
+                active_session_only: "active_session_only";
+                reject: "reject";
+            }>>;
+        }, z.core.$strip>;
+        selector_json: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    operation: z.ZodLiteral<"add_condition">;
+    node: z.ZodObject<{
+        kind: z.ZodLiteral<"condition">;
+        stable_id: z.ZodString;
+        enabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        effective_time: z.ZodObject<{
+            domain: z.ZodEnum<{
+                logical_seq: "logical_seq";
+                world_time: "world_time";
+                presentation_seq: "presentation_seq";
+                real_time: "real_time";
+            }>;
+            due_value: z.ZodNumber;
+            effective_value: z.ZodNumber;
+            crossing_policy: z.ZodEnum<{
+                forward_only: "forward_only";
+                backward_only: "backward_only";
+                both_directions: "both_directions";
+            }>;
+            real_time_clock: z.ZodNullable<z.ZodEnum<{
+                monotonic_session: "monotonic_session";
+                active_play: "active_play";
+                wall_clock: "wall_clock";
+            }>>;
+            wall_clock_policy: z.ZodNullable<z.ZodEnum<{
+                elapse_while_suspended: "elapse_while_suspended";
+                active_session_only: "active_session_only";
+                reject: "reject";
+            }>>;
+        }, z.core.$strip>;
+        expression_json: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    operation: z.ZodLiteral<"add_effect">;
+    node: z.ZodObject<{
+        kind: z.ZodLiteral<"effect">;
+        stable_id: z.ZodString;
+        enabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        effective_time: z.ZodObject<{
+            domain: z.ZodEnum<{
+                logical_seq: "logical_seq";
+                world_time: "world_time";
+                presentation_seq: "presentation_seq";
+                real_time: "real_time";
+            }>;
+            due_value: z.ZodNumber;
+            effective_value: z.ZodNumber;
+            crossing_policy: z.ZodEnum<{
+                forward_only: "forward_only";
+                backward_only: "backward_only";
+                both_directions: "both_directions";
+            }>;
+            real_time_clock: z.ZodNullable<z.ZodEnum<{
+                monotonic_session: "monotonic_session";
+                active_play: "active_play";
+                wall_clock: "wall_clock";
+            }>>;
+            wall_clock_policy: z.ZodNullable<z.ZodEnum<{
+                elapse_while_suspended: "elapse_while_suspended";
+                active_session_only: "active_session_only";
+                reject: "reject";
+            }>>;
+        }, z.core.$strip>;
+        capability_id: z.ZodString;
+        selector_json: z.ZodNullable<z.ZodString>;
+        arguments_json: z.ZodString;
+        execution_policy: z.ZodEnum<{
+            attempt_once: "attempt_once";
+            ensure_until: "ensure_until";
+        }>;
+        rewrite_policy: z.ZodEnum<{
+            normal_only: "normal_only";
+            rewrite_only: "rewrite_only";
+            normal_and_rewrite: "normal_and_rewrite";
+        }>;
+        priority: z.ZodNumber;
+        idempotency_key: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    operation: z.ZodLiteral<"add_presentation">;
+    node: z.ZodObject<{
+        kind: z.ZodLiteral<"presentation">;
+        stable_id: z.ZodString;
+        enabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        effective_time: z.ZodObject<{
+            domain: z.ZodEnum<{
+                logical_seq: "logical_seq";
+                world_time: "world_time";
+                presentation_seq: "presentation_seq";
+                real_time: "real_time";
+            }>;
+            due_value: z.ZodNumber;
+            effective_value: z.ZodNumber;
+            crossing_policy: z.ZodEnum<{
+                forward_only: "forward_only";
+                backward_only: "backward_only";
+                both_directions: "both_directions";
+            }>;
+            real_time_clock: z.ZodNullable<z.ZodEnum<{
+                monotonic_session: "monotonic_session";
+                active_play: "active_play";
+                wall_clock: "wall_clock";
+            }>>;
+            wall_clock_policy: z.ZodNullable<z.ZodEnum<{
+                elapse_while_suspended: "elapse_while_suspended";
+                active_session_only: "active_session_only";
+                reject: "reject";
+            }>>;
+        }, z.core.$strip>;
+        intent_type: z.ZodString;
+        payload_json: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    operation: z.ZodLiteral<"connect">;
+    from_stable_id: z.ZodString;
+    to_stable_id: z.ZodString;
+}, z.core.$strip>], "operation">;
+export type TmwBuilderCommand = z.infer<typeof tmwBuilderCommandSchema>;
+export type TmwBuilderNodeCommand = Exclude<TmwBuilderCommand, {
+    readonly operation: "connect";
+}>;
+export type TmwBuilderNodeInput = {
+    readonly kind: "event";
+    readonly node: TriggerEventNodeV3;
+} | {
+    readonly kind: "condition";
+    readonly node: TriggerConditionNodeV3;
+} | {
+    readonly kind: "effect";
+    readonly node: TriggerEffectNodeV3;
+} | {
+    readonly kind: "presentation";
+    readonly node: TriggerPresentationNodeV3;
+};
+export declare const immutableBuilderNode: <T extends TriggerNodeV3>(node: T) => T;
+export declare const builderNodeStableId: (input: TmwBuilderNodeInput) => string;
+export declare const builderNodeKind: (node: TriggerNodeV3) => TmwBuilderNodeInput["kind"];
+export declare const tmwBuilderCommandFromNode: (node: TriggerNodeV3) => TmwBuilderCommand;
+export declare const tmwBuilderNodeFromCommand: (command: TmwBuilderNodeCommand) => TriggerNodeV3;

package/dist/builder-node.js

@@ -0,0 +1,212 @@
+import { canonicalTmwJson } from "./runtime-contract.js";
+import { z } from "zod";
+export const tmwStableIdSchema = z.string().regex(/^[a-z0-9](?:[a-z0-9._:-]{0,127})$/u);
+const canonicalJsonFragmentSchema = z.string()
+    .min(2)
+    .max(262_144)
+    .describe("canonical JSON fragment; object keys must be sorted and no insignificant whitespace is allowed");
+const effectiveTimeSchema = z.object({
+    domain: z.enum(["logical_seq", "world_time", "presentation_seq", "real_time"]),
+    due_value: z.number(),
+    effective_value: z.number(),
+    crossing_policy: z.enum(["forward_only", "backward_only", "both_directions"]),
+    real_time_clock: z.enum(["monotonic_session", "active_play", "wall_clock"]).nullable(),
+    wall_clock_policy: z.enum(["elapse_while_suspended", "active_session_only", "reject"]).nullable(),
+});
+const eventNodeInputSchema = z.object({
+    kind: z.literal("event"),
+    stable_id: tmwStableIdSchema,
+    enabled: z.boolean().optional().default(true),
+    event_type: tmwStableIdSchema,
+    hard_fact: z.boolean(),
+    effective_time: effectiveTimeSchema,
+    selector_json: canonicalJsonFragmentSchema.nullable(),
+});
+const conditionNodeInputSchema = z.object({
+    kind: z.literal("condition"),
+    stable_id: tmwStableIdSchema,
+    enabled: z.boolean().optional().default(true),
+    effective_time: effectiveTimeSchema,
+    expression_json: canonicalJsonFragmentSchema,
+});
+const effectNodeInputSchema = z.object({
+    kind: z.literal("effect"),
+    stable_id: tmwStableIdSchema,
+    enabled: z.boolean().optional().default(true),
+    effective_time: effectiveTimeSchema,
+    capability_id: tmwStableIdSchema,
+    selector_json: canonicalJsonFragmentSchema.nullable(),
+    arguments_json: canonicalJsonFragmentSchema,
+    execution_policy: z.enum(["attempt_once", "ensure_until"]),
+    rewrite_policy: z.enum(["normal_only", "rewrite_only", "normal_and_rewrite"]),
+    priority: z.number().int().nonnegative(),
+    idempotency_key: tmwStableIdSchema,
+});
+const presentationNodeInputSchema = z.object({
+    kind: z.literal("presentation"),
+    stable_id: tmwStableIdSchema,
+    enabled: z.boolean().optional().default(true),
+    effective_time: effectiveTimeSchema,
+    intent_type: tmwStableIdSchema,
+    payload_json: canonicalJsonFragmentSchema,
+});
+export const tmwBuilderCommandSchema = z.discriminatedUnion("operation", [
+    z.object({ operation: z.literal("add_event"), node: eventNodeInputSchema }),
+    z.object({ operation: z.literal("add_condition"), node: conditionNodeInputSchema }),
+    z.object({ operation: z.literal("add_effect"), node: effectNodeInputSchema }),
+    z.object({ operation: z.literal("add_presentation"), node: presentationNodeInputSchema }),
+    z.object({
+        operation: z.literal("connect"),
+        from_stable_id: tmwStableIdSchema,
+        to_stable_id: tmwStableIdSchema,
+    }),
+]);
+const cloneJson = (value) => structuredClone(value);
+const deepFreeze = (value) => {
+    if (typeof value !== "object" || value === null || Object.isFrozen(value))
+        return value;
+    for (const child of Object.values(value))
+        deepFreeze(child);
+    return Object.freeze(value);
+};
+export const immutableBuilderNode = (node) => deepFreeze(cloneJson(node));
+export const builderNodeStableId = (input) => input.node.stable_id;
+export const builderNodeKind = (node) => {
+    if (node.kind === "event"
+        || node.kind === "condition"
+        || node.kind === "effect"
+        || node.kind === "presentation") {
+        return node.kind;
+    }
+    throw new Error("tmw_builder_node_kind_invalid");
+};
+const encodeCanonicalJsonFragment = (value) => canonicalTmwJson(value);
+const parseCanonicalObject = (value, code) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw new Error(code);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error(code);
+    }
+    if (canonicalTmwJson(parsed) !== value)
+        throw new Error(code);
+    return parsed;
+};
+export const tmwBuilderCommandFromNode = (node) => {
+    switch (node.kind) {
+        case "event":
+            return {
+                operation: "add_event",
+                node: {
+                    kind: node.kind,
+                    stable_id: node.stable_id,
+                    enabled: node.enabled !== false,
+                    event_type: node.event_type,
+                    hard_fact: node.hard_fact,
+                    effective_time: node.effective_time,
+                    selector_json: node.selector === null
+                        ? null
+                        : encodeCanonicalJsonFragment(node.selector),
+                },
+            };
+        case "condition":
+            return {
+                operation: "add_condition",
+                node: {
+                    kind: node.kind,
+                    stable_id: node.stable_id,
+                    enabled: node.enabled !== false,
+                    effective_time: node.effective_time,
+                    expression_json: encodeCanonicalJsonFragment(node.expression),
+                },
+            };
+        case "effect":
+            return {
+                operation: "add_effect",
+                node: {
+                    kind: node.kind,
+                    stable_id: node.stable_id,
+                    enabled: node.enabled !== false,
+                    effective_time: node.effective_time,
+                    capability_id: node.capability_id,
+                    selector_json: node.selector === null
+                        ? null
+                        : encodeCanonicalJsonFragment(node.selector),
+                    arguments_json: encodeCanonicalJsonFragment(node.arguments),
+                    execution_policy: node.execution_policy,
+                    rewrite_policy: node.rewrite_policy,
+                    priority: node.priority,
+                    idempotency_key: node.idempotency_key,
+                },
+            };
+        case "presentation":
+            return {
+                operation: "add_presentation",
+                node: {
+                    kind: node.kind,
+                    stable_id: node.stable_id,
+                    enabled: node.enabled !== false,
+                    effective_time: node.effective_time,
+                    intent_type: node.intent_type,
+                    payload_json: encodeCanonicalJsonFragment(node.payload),
+                },
+            };
+    }
+};
+export const tmwBuilderNodeFromCommand = (command) => {
+    if (command.operation === "add_event") {
+        const { node } = command;
+        return {
+            kind: node.kind,
+            stable_id: node.stable_id,
+            enabled: node.enabled,
+            event_type: node.event_type,
+            hard_fact: node.hard_fact,
+            effective_time: node.effective_time,
+            selector: node.selector_json === null
+                ? null
+                : parseCanonicalObject(node.selector_json, "tmw_builder_selector_json_invalid"),
+        };
+    }
+    if (command.operation === "add_condition") {
+        const { node } = command;
+        return {
+            kind: node.kind,
+            stable_id: node.stable_id,
+            enabled: node.enabled,
+            effective_time: node.effective_time,
+            expression: parseCanonicalObject(node.expression_json, "tmw_builder_expression_json_invalid"),
+        };
+    }
+    if (command.operation === "add_effect") {
+        const { node } = command;
+        return {
+            kind: node.kind,
+            stable_id: node.stable_id,
+            enabled: node.enabled,
+            effective_time: node.effective_time,
+            capability_id: node.capability_id,
+            selector: node.selector_json === null
+                ? null
+                : parseCanonicalObject(node.selector_json, "tmw_builder_selector_json_invalid"),
+            arguments: parseCanonicalObject(node.arguments_json, "tmw_builder_arguments_json_invalid"),
+            execution_policy: node.execution_policy,
+            rewrite_policy: node.rewrite_policy,
+            priority: node.priority,
+            idempotency_key: node.idempotency_key,
+        };
+    }
+    const { node } = command;
+    return {
+        kind: node.kind,
+        stable_id: node.stable_id,
+        enabled: node.enabled,
+        effective_time: node.effective_time,
+        intent_type: node.intent_type,
+        payload: parseCanonicalObject(node.payload_json, "tmw_builder_payload_json_invalid"),
+    };
+};

package/dist/builder.d.ts

@@ -0,0 +1,32 @@
+import type { CanonicalTmwCapabilityRegistryV3 } from "./capability-registry.js";
+import { type TmwResult } from "./diagnostics.js";
+import { type SimulateTmw3Options, type SimulateTmw3Outcome } from "./simulator.js";
+import type { TriggerConditionNodeV3, TriggerDocumentV3, TriggerEdgeV3, TriggerEffectNodeV3, TriggerEventNodeV3, TriggerPresentationNodeV3 } from "./trigger-document-v3.js";
+export interface BeginTmwBuilderInput {
+    readonly runtime_contract_hash: string;
+    readonly registry: CanonicalTmwCapabilityRegistryV3;
+}
+interface BuilderState {
+    readonly events: readonly TriggerEventNodeV3[];
+    readonly conditions: readonly TriggerConditionNodeV3[];
+    readonly effects: readonly TriggerEffectNodeV3[];
+    readonly presentations: readonly TriggerPresentationNodeV3[];
+    readonly edges: readonly TriggerEdgeV3[];
+}
+export declare class TmwBuilder {
+    private readonly runtimeContractHash;
+    private readonly registry;
+    private readonly state;
+    constructor(runtimeContractHash: string, registry: CanonicalTmwCapabilityRegistryV3, state?: BuilderState);
+    private addNode;
+    addEvent(node: TriggerEventNodeV3): TmwResult<TmwBuilder>;
+    addCondition(node: TriggerConditionNodeV3): TmwResult<TmwBuilder>;
+    addEffect(node: TriggerEffectNodeV3): TmwResult<TmwBuilder>;
+    addPresentation(node: TriggerPresentationNodeV3): TmwResult<TmwBuilder>;
+    connect(fromStableId: string, toStableId: string): TmwResult<TmwBuilder>;
+    document(): TriggerDocumentV3;
+    build(): Promise<TmwResult<TriggerDocumentV3>>;
+    simulate(options?: SimulateTmw3Options): Promise<SimulateTmw3Outcome>;
+}
+export declare const beginTmwBuilder: (input: BeginTmwBuilderInput) => TmwBuilder;
+export {};

package/dist/builder.js

@@ -0,0 +1,127 @@
+import { TMW_RUNTIME_GENERATION } from "./runtime-contract.js";
+import { tmwSuccess } from "./diagnostics.js";
+import { simulateTmw3 } from "./simulator.js";
+import { validateTmw3 } from "./validator.js";
+import { builderFailure, builderStableIdError } from "./builder-diagnostics.js";
+import { immutableBuilderNode } from "./builder-node.js";
+const EMPTY_STATE = Object.freeze({
+    events: Object.freeze([]),
+    conditions: Object.freeze([]),
+    effects: Object.freeze([]),
+    presentations: Object.freeze([]),
+    edges: Object.freeze([]),
+});
+const freezeState = (state) => Object.freeze({
+    events: Object.freeze([...state.events]),
+    conditions: Object.freeze([...state.conditions]),
+    effects: Object.freeze([...state.effects]),
+    presentations: Object.freeze([...state.presentations]),
+    edges: Object.freeze(state.edges.map((edge) => Object.freeze({ ...edge }))),
+});
+const nodes = (state) => [
+    ...state.events,
+    ...state.conditions,
+    ...state.effects,
+    ...state.presentations,
+];
+export class TmwBuilder {
+    runtimeContractHash;
+    registry;
+    state;
+    constructor(runtimeContractHash, registry, state = EMPTY_STATE) {
+        this.runtimeContractHash = runtimeContractHash;
+        this.registry = registry;
+        this.state = freezeState(state);
+        Object.freeze(this);
+    }
+    addNode(node, path, append) {
+        if (typeof node !== "object" || node === null || typeof node.stable_id !== "string") {
+            return builderFailure("builder_node_invalid", path, "builder node must be a typed TMW3 node");
+        }
+        const stableIdError = builderStableIdError(node.stable_id, `${path}/stable_id`);
+        if (stableIdError !== null)
+            return stableIdError;
+        if (nodes(this.state).some((existing) => existing.stable_id === node.stable_id)) {
+            return builderFailure("duplicate_stable_id", path, "stable_id must be unique across all node kinds", [node.stable_id]);
+        }
+        const next = append(this.state, immutableBuilderNode(node));
+        return tmwSuccess(new TmwBuilder(this.runtimeContractHash, this.registry, next));
+    }
+    addEvent(node) {
+        return this.addNode(node, "$/events", (state, value) => ({
+            ...state,
+            events: [...state.events, value],
+        }));
+    }
+    addCondition(node) {
+        return this.addNode(node, "$/conditions", (state, value) => ({
+            ...state,
+            conditions: [...state.conditions, value],
+        }));
+    }
+    addEffect(node) {
+        if (typeof node !== "object" || node === null || typeof node.capability_id !== "string") {
+            return builderFailure("builder_effect_invalid", "$/effects", "effect must declare a capability_id");
+        }
+        if (!this.registry.capabilities.some((capability) => capability.capability_id === node.capability_id)) {
+            return builderFailure("unknown_capability", "$/effects/capability_id", "effect capability is not registered", [node.stable_id, node.capability_id]);
+        }
+        return this.addNode(node, "$/effects", (state, value) => ({
+            ...state,
+            effects: [...state.effects, value],
+        }));
+    }
+    addPresentation(node) {
+        return this.addNode(node, "$/presentations", (state, value) => ({
+            ...state,
+            presentations: [...state.presentations, value],
+        }));
+    }
+    connect(fromStableId, toStableId) {
+        const fromError = builderStableIdError(fromStableId, "$/edges/from_stable_id");
+        if (fromError !== null)
+            return fromError;
+        const toError = builderStableIdError(toStableId, "$/edges/to_stable_id");
+        if (toError !== null)
+            return toError;
+        const ids = new Set(nodes(this.state).map((node) => node.stable_id));
+        if (!ids.has(fromStableId)) {
+            return builderFailure("dangling_edge_source", "$/edges/from_stable_id", "edge source does not exist", [fromStableId]);
+        }
+        if (!ids.has(toStableId)) {
+            return builderFailure("dangling_edge_target", "$/edges/to_stable_id", "edge target does not exist", [toStableId]);
+        }
+        if (this.state.edges.some((edge) => edge.from_stable_id === fromStableId && edge.to_stable_id === toStableId)) {
+            return builderFailure("duplicate_edge", "$/edges", "edge must be unique", [fromStableId, toStableId]);
+        }
+        return tmwSuccess(new TmwBuilder(this.runtimeContractHash, this.registry, {
+            ...this.state,
+            edges: [...this.state.edges, { from_stable_id: fromStableId, to_stable_id: toStableId }],
+        }));
+    }
+    document() {
+        const byStableId = (items) => Object.freeze([...items].sort((left, right) => left.stable_id.localeCompare(right.stable_id, "en")));
+        return Object.freeze({
+            version: 3,
+            runtime_generation: TMW_RUNTIME_GENERATION,
+            runtime_contract_hash: this.runtimeContractHash,
+            registry_version: this.registry.registry_version,
+            events: byStableId(this.state.events),
+            conditions: byStableId(this.state.conditions),
+            effects: byStableId(this.state.effects),
+            presentations: byStableId(this.state.presentations),
+            edges: Object.freeze([...this.state.edges].sort((left, right) => (left.from_stable_id.localeCompare(right.from_stable_id, "en")
+                || left.to_stable_id.localeCompare(right.to_stable_id, "en")))),
+        });
+    }
+    build() {
+        return validateTmw3(this.document(), this.registry, {
+            expected_runtime_contract_hash: this.runtimeContractHash,
+        });
+    }
+    async simulate(options = {}) {
+        const built = await this.build();
+        return built.ok ? simulateTmw3(built.value, this.registry, options) : built;
+    }
+}
+export const beginTmwBuilder = (input) => new TmwBuilder(input.runtime_contract_hash, input.registry);

package/dist/capability-registry.d.ts

@@ -0,0 +1,32 @@
+import type { SelectorAstV3 } from "./selector-ast.js";
+import type { TmwJsonValue } from "./runtime-contract.js";
+export declare const TMW_CAPABILITY_REGISTRY_VERSION: "tmw.capabilities.v3";
+export type TmwCapabilityPolicy = "deterministic" | "semantic_verdict_required" | "presentation_only";
+export interface TmwCapabilityV3 {
+    readonly capability_id: string;
+    readonly effect_type: string;
+    readonly policy: TmwCapabilityPolicy;
+    /** Explicit temporal-rewrite safety authority for committed effects. */
+    readonly rewrite_safety: "reversible" | "external_irreversible";
+    readonly max_invocations_per_turn: number;
+    readonly argument_schema: TmwJsonValue;
+    readonly selector_required: boolean;
+}
+export interface TmwCapabilityRegistryV3 {
+    readonly registry_version: string;
+    readonly capabilities: readonly TmwCapabilityV3[];
+}
+declare const canonicalRegistryBrand: unique symbol;
+export type CanonicalTmwCapabilityRegistryV3 = TmwCapabilityRegistryV3 & {
+    readonly [canonicalRegistryBrand]: true;
+};
+/** 唯一受信 registry provider；调用方不能以自报 version/capability 对象取得 authority。 */
+export declare function getCanonicalTmwCapabilityRegistryV3(): CanonicalTmwCapabilityRegistryV3;
+export declare function isCanonicalTmwCapabilityRegistryV3(registry: TmwCapabilityRegistryV3): registry is CanonicalTmwCapabilityRegistryV3;
+export interface CapabilityCheckedEffectV3 {
+    readonly capability_id: string;
+    readonly selector: SelectorAstV3 | null;
+    readonly arguments: Readonly<Record<string, TmwJsonValue>>;
+}
+export declare function capabilityRegistryIndex(registry: TmwCapabilityRegistryV3): ReadonlyMap<string, TmwCapabilityV3>;
+export {};

package/dist/capability-registry.js

@@ -0,0 +1,33 @@
+import { TMW_SCENE_CAPABILITY_ARGUMENT_SCHEMAS } from "./scene-state.js";
+import { TMW_EVENT_CAPABILITY_ARGUMENT_SCHEMAS } from "./event-lifecycle.js";
+import { TMW_GAMEPLAY_CAPABILITY_ARGUMENT_SCHEMAS } from "./gameplay-state.js";
+export const TMW_CAPABILITY_REGISTRY_VERSION = "tmw.capabilities.v3";
+const CANONICAL_TMW_CAPABILITY_REGISTRY_V3 = Object.freeze({
+    registry_version: TMW_CAPABILITY_REGISTRY_VERSION,
+    capabilities: Object.freeze([
+        Object.freeze({ capability_id: "world.set_attribute", effect_type: "world.set_attribute", policy: "deterministic", rewrite_safety: "reversible", max_invocations_per_turn: 256, argument_schema: Object.freeze({ type: "object" }), selector_required: true }),
+        Object.freeze({ capability_id: "world.emit_event", effect_type: "world.emit_event", policy: "deterministic", rewrite_safety: "reversible", max_invocations_per_turn: 256, argument_schema: Object.freeze({ type: "object" }), selector_required: false }),
+        Object.freeze({ capability_id: "semantic.request_verdict", effect_type: "semantic.request_verdict", policy: "semantic_verdict_required", rewrite_safety: "reversible", max_invocations_per_turn: 32, argument_schema: Object.freeze({ type: "object" }), selector_required: false }),
+        Object.freeze({ capability_id: "presentation.show_overlay", effect_type: "presentation.show_overlay", policy: "presentation_only", rewrite_safety: "reversible", max_invocations_per_turn: 64, argument_schema: Object.freeze({ type: "object" }), selector_required: false }),
+        Object.freeze({ capability_id: "presentation.play_music", effect_type: "presentation.play_music", policy: "presentation_only", rewrite_safety: "reversible", max_invocations_per_turn: 32, argument_schema: Object.freeze({ type: "object" }), selector_required: false }),
+        ...Object.entries({ ...TMW_SCENE_CAPABILITY_ARGUMENT_SCHEMAS, ...TMW_EVENT_CAPABILITY_ARGUMENT_SCHEMAS, ...TMW_GAMEPLAY_CAPABILITY_ARGUMENT_SCHEMAS }).map(([capabilityId, argumentSchema]) => Object.freeze({
+            capability_id: capabilityId,
+            effect_type: capabilityId,
+            policy: "deterministic",
+            rewrite_safety: "reversible",
+            max_invocations_per_turn: 256,
+            argument_schema: argumentSchema,
+            selector_required: false,
+        })),
+    ]),
+});
+/** 唯一受信 registry provider；调用方不能以自报 version/capability 对象取得 authority。 */
+export function getCanonicalTmwCapabilityRegistryV3() {
+    return CANONICAL_TMW_CAPABILITY_REGISTRY_V3;
+}
+export function isCanonicalTmwCapabilityRegistryV3(registry) {
+    return registry === CANONICAL_TMW_CAPABILITY_REGISTRY_V3;
+}
+export function capabilityRegistryIndex(registry) {
+    return new Map(registry.capabilities.map((capability) => [capability.capability_id, capability]));
+}

package/dist/compile-target-profile.d.ts

@@ -0,0 +1,16 @@
+export declare const COMPILE_TARGET_PROFILE_SCHEMA_VERSION: 1;
+export interface CompileTargetStageVersion {
+    readonly stage_id: string;
+    readonly stage_version: string;
+}
+export interface CompileTargetProfile {
+    readonly schema_version: typeof COMPILE_TARGET_PROFILE_SCHEMA_VERSION;
+    readonly compiler_release: string;
+    readonly runtime_semantics: string;
+    readonly sdk_schema: string;
+    readonly artifact_format: string;
+    readonly stage_versions: readonly CompileTargetStageVersion[];
+}
+export declare function parseCompileTargetProfile(value: unknown): CompileTargetProfile;
+export declare function canonicalCompileTargetProfileBytes(profile: CompileTargetProfile): Uint8Array;
+export declare function compileTargetProfileDigest(profile: CompileTargetProfile): Promise<string>;