@world-engines/tmw 0.1.0-alpha.0

package/dist/timeline-revision.d.ts

@@ -0,0 +1,28 @@
+import { TMW_RUNTIME_GENERATION } from "./runtime-contract.js";
+export interface TimelineRevisionV3 {
+    readonly revisionId: string;
+    readonly parentRevisionId: string | null;
+    readonly revisionSequence: number;
+    readonly epoch: number;
+    readonly runtimeGeneration: typeof TMW_RUNTIME_GENERATION;
+    readonly runtimeContractHash: string;
+    readonly artifactDigest: string;
+    readonly sourceRevision: string;
+    readonly worldlineId: string;
+    readonly operationId: string;
+    readonly ledgerHead: string;
+    readonly narrativeDigest: string;
+    readonly savSectionDigest: string;
+    readonly intentSetDigest: string;
+    readonly presentationIntentSetDigest: string;
+    readonly createdFrom: "fresh" | "turn" | "temporal_rewrite";
+    readonly active: boolean;
+}
+export interface TimelineHeadV3 {
+    readonly revisionId: string;
+    readonly revisionSequence: number;
+    readonly ledgerHead: string;
+}
+export declare function canonicalTimelineRevision(input: TimelineRevisionV3): TimelineRevisionV3;
+export declare function assertTimelineSuccessor(current: TimelineHeadV3 | null, candidateInput: TimelineRevisionV3): TimelineRevisionV3;
+export declare function timelineHead(revisionInput: TimelineRevisionV3): TimelineHeadV3;

package/dist/timeline-revision.js

@@ -0,0 +1,59 @@
+import { TMW_RUNTIME_GENERATION } from "./runtime-contract.js";
+import { requireTmwIdentifier, requireTmwSafeInteger, requireTmwSha256, } from "./runtime-trace.js";
+export function canonicalTimelineRevision(input) {
+    if (input.runtimeGeneration !== 3)
+        throw new Error("unsupported_runtime_generation");
+    if (input.createdFrom !== "fresh" && input.createdFrom !== "turn"
+        && input.createdFrom !== "temporal_rewrite") {
+        throw new Error("tmw_timeline_created_from_invalid");
+    }
+    if (typeof input.active !== "boolean")
+        throw new Error("tmw_timeline_active_invalid");
+    return Object.freeze({
+        revisionId: requireTmwIdentifier(input.revisionId, "timeline_revision_id"),
+        parentRevisionId: input.parentRevisionId === null
+            ? null
+            : requireTmwIdentifier(input.parentRevisionId, "timeline_parent_revision_id"),
+        revisionSequence: requireTmwSafeInteger(input.revisionSequence, "timeline_revision_sequence"),
+        epoch: requireTmwSafeInteger(input.epoch, "timeline_epoch", 1),
+        runtimeGeneration: TMW_RUNTIME_GENERATION,
+        runtimeContractHash: requireTmwSha256(input.runtimeContractHash, "timeline_contract_hash"),
+        artifactDigest: requireTmwSha256(input.artifactDigest, "timeline_artifact_digest"),
+        sourceRevision: requireTmwIdentifier(input.sourceRevision, "timeline_source_revision"),
+        worldlineId: requireTmwIdentifier(input.worldlineId, "timeline_worldline_id"),
+        operationId: requireTmwIdentifier(input.operationId, "timeline_operation_id"),
+        ledgerHead: requireTmwSha256(input.ledgerHead, "timeline_ledger_head"),
+        narrativeDigest: requireTmwSha256(input.narrativeDigest, "timeline_narrative_digest"),
+        savSectionDigest: requireTmwSha256(input.savSectionDigest, "timeline_sav_digest"),
+        intentSetDigest: requireTmwSha256(input.intentSetDigest, "timeline_intent_digest"),
+        presentationIntentSetDigest: requireTmwSha256(input.presentationIntentSetDigest, "timeline_presentation_intent_digest"),
+        createdFrom: input.createdFrom,
+        active: input.active,
+    });
+}
+export function assertTimelineSuccessor(current, candidateInput) {
+    const candidate = canonicalTimelineRevision(candidateInput);
+    if (!candidate.active)
+        throw new Error("tmw_timeline_candidate_not_active");
+    if (current === null) {
+        if (candidate.parentRevisionId !== null || candidate.revisionSequence !== 0) {
+            throw new Error("tmw_timeline_fresh_parent_invalid");
+        }
+        return candidate;
+    }
+    if (candidate.parentRevisionId !== current.revisionId) {
+        throw new Error("tmw_timeline_parent_mismatch");
+    }
+    if (candidate.revisionSequence !== current.revisionSequence + 1) {
+        throw new Error("tmw_timeline_sequence_mismatch");
+    }
+    return candidate;
+}
+export function timelineHead(revisionInput) {
+    const revision = canonicalTimelineRevision(revisionInput);
+    return Object.freeze({
+        revisionId: revision.revisionId,
+        revisionSequence: revision.revisionSequence,
+        ledgerHead: revision.ledgerHead,
+    });
+}

package/dist/trigger-document-v3.d.ts

@@ -0,0 +1,99 @@
+import type { CapabilityCheckedEffectV3 } from "./capability-registry.js";
+import type { TmwResult } from "./diagnostics.js";
+import { TMW_RUNTIME_GENERATION, TRIGGER_DOCUMENT_V3_VERSION, type TmwJsonPrimitive } from "./runtime-contract.js";
+import type { SelectorAstV3 } from "./selector-ast.js";
+import { type ConditionEffectiveTime, type EffectEffectiveTime, type EventEffectiveTime, type PresentationEffectiveTime } from "./time-domains.js";
+import type { EffectExecutionPolicy, EffectRewritePolicy } from "./effect-flow.js";
+import { type PresentationPayloadV3 } from "./presentation-intent.js";
+import { type TmwValueGraphV1, type TmwSceneValueFieldV1 } from "./value-graph.js";
+export interface TmwNaturalLanguageConditionV3 {
+    readonly op: "nl_condition";
+    /** Stable leaf identity within the owning condition expression. */
+    readonly stable_id: string;
+    readonly text: string;
+    readonly locale: string;
+    readonly anchor?: SelectorAstV3;
+}
+export type TmwSemanticConditionExpressionV3 = TmwNaturalLanguageConditionV3;
+export type TmwConditionExpressionV3 = {
+    readonly op: "literal";
+    readonly value: boolean;
+} | {
+    readonly op: "value_input";
+    readonly port: "value";
+} | {
+    readonly op: "scene_field";
+    readonly field: TmwSceneValueFieldV1;
+    readonly comparison: "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "contains";
+    readonly value: import("./runtime-contract.js").TmwJsonValue;
+} | {
+    readonly op: "event_field";
+    readonly path: readonly string[];
+    readonly comparison: "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "contains";
+    readonly value: TmwJsonPrimitive;
+} | {
+    readonly op: "selector_exists";
+    readonly selector: SelectorAstV3;
+} | TmwNaturalLanguageConditionV3 | {
+    readonly op: "not";
+    readonly value: TmwConditionExpressionV3;
+} | {
+    readonly op: "all" | "any";
+    readonly values: readonly TmwConditionExpressionV3[];
+};
+export interface TriggerEventNodeV3 {
+    readonly kind: "event";
+    readonly stable_id: string;
+    /** Canonical authoring/runtime gate. Missing legacy input materializes as true. */
+    readonly enabled?: boolean;
+    readonly event_type: string;
+    /** Explicit rewrite-retention authority; never inferred from downstream capabilities. */
+    readonly hard_fact: boolean;
+    readonly effective_time: EventEffectiveTime;
+    readonly selector: SelectorAstV3 | null;
+}
+export interface TriggerConditionNodeV3 {
+    readonly kind: "condition";
+    readonly stable_id: string;
+    readonly enabled?: boolean;
+    readonly effective_time: ConditionEffectiveTime;
+    readonly expression: TmwConditionExpressionV3;
+}
+export interface TriggerEffectNodeV3 extends CapabilityCheckedEffectV3 {
+    readonly kind: "effect";
+    readonly stable_id: string;
+    readonly enabled?: boolean;
+    readonly effective_time: EffectEffectiveTime;
+    readonly execution_policy: EffectExecutionPolicy;
+    readonly rewrite_policy: EffectRewritePolicy;
+    readonly priority: number;
+    readonly idempotency_key: string;
+}
+export interface TriggerPresentationNodeV3 {
+    readonly kind: "presentation";
+    readonly stable_id: string;
+    readonly enabled?: boolean;
+    readonly effective_time: PresentationEffectiveTime;
+    readonly intent_type: string;
+    readonly payload: PresentationPayloadV3;
+}
+export type TriggerNodeV3 = TriggerEventNodeV3 | TriggerConditionNodeV3 | TriggerEffectNodeV3 | TriggerPresentationNodeV3;
+export type TriggerNodeKindV3 = "event" | "condition" | "effect" | "presentation";
+export interface TriggerEdgeV3 {
+    readonly from_stable_id: string;
+    readonly to_stable_id: string;
+}
+export interface TriggerDocumentV3 {
+    readonly version: typeof TRIGGER_DOCUMENT_V3_VERSION;
+    readonly runtime_generation: typeof TMW_RUNTIME_GENERATION;
+    readonly runtime_contract_hash: string;
+    readonly registry_version: string;
+    readonly events: readonly TriggerEventNodeV3[];
+    readonly conditions: readonly TriggerConditionNodeV3[];
+    readonly effects: readonly TriggerEffectNodeV3[];
+    readonly presentations: readonly TriggerPresentationNodeV3[];
+    readonly edges: readonly TriggerEdgeV3[];
+    readonly value_graph?: TmwValueGraphV1;
+}
+export declare function parseTriggerDocumentV3(value: unknown): TmwResult<TriggerDocumentV3>;
+export declare function allTriggerNodesV3(document: TriggerDocumentV3): readonly TriggerNodeV3[];

package/dist/trigger-document-v3.js

@@ -0,0 +1,334 @@
+import { orderTmwDiagnostics, tmwDiagnostic, tmwFailure, tmwSuccess } from "./diagnostics.js";
+import { isSha256Hex, TMW_RUNTIME_GENERATION, TRIGGER_DOCUMENT_V3_VERSION } from "./runtime-contract.js";
+import { isTmwEffectiveTime } from "./time-domains.js";
+import { parsePresentationPayloadV3 } from "./presentation-intent.js";
+import { isTmwTypedValueV1, parseTmwValueGraphV1 } from "./value-graph.js";
+const ROOT_KEYS = ["conditions", "edges", "effects", "events", "presentations", "registry_version", "runtime_contract_hash", "runtime_generation", "version"];
+const IDENTIFIER = /^[a-z0-9](?:[a-z0-9._:-]{0,127})$/u;
+const CONDITION_COMPARISONS = new Set(["eq", "neq", "gt", "gte", "lt", "lte", "contains"]);
+const MAX_CONDITION_DEPTH = 32;
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+}
+function exactKeys(value, keys) {
+    return Object.keys(value).sort().join("\0") === [...keys].sort().join("\0");
+}
+function identifier(value) {
+    return typeof value === "string" && IDENTIFIER.test(value) && value.normalize("NFC") === value;
+}
+function jsonPrimitive(value) {
+    return value === null
+        || typeof value === "string"
+        || typeof value === "boolean"
+        || (typeof value === "number" && Number.isFinite(value));
+}
+function canonicalLocale(value) {
+    if (typeof value !== "string" || value.length === 0 || value.normalize("NFC") !== value)
+        return false;
+    try {
+        const canonical = Intl.getCanonicalLocales(value);
+        return canonical.length === 1 && canonical[0] === value;
+    }
+    catch {
+        return false;
+    }
+}
+function parseSelector(value, path, diagnostics, depth = 0) {
+    if (depth > 32) {
+        diagnostics.push(tmwDiagnostic("selector_depth_exceeded", path, "selector depth exceeds 32"));
+        return null;
+    }
+    const node = record(value);
+    if (node === null || typeof node.op !== "string") {
+        diagnostics.push(tmwDiagnostic("selector_invalid", path, "selector must be an object with op"));
+        return null;
+    }
+    if (node.op === "entity_id" || node.op === "entity_kind") {
+        const key = node.op === "entity_id" ? "entity_id" : "entity_kind";
+        if (!exactKeys(node, ["op", key]) || !identifier(node[key]))
+            diagnostics.push(tmwDiagnostic("selector_invalid", path, `invalid ${node.op}`));
+    }
+    else if (node.op === "attribute") {
+        if (!exactKeys(node, ["comparison", "op", "path", "source", "value"]) || !Array.isArray(node.path) || node.path.length === 0 || !node.path.every(identifier)) {
+            diagnostics.push(tmwDiagnostic("selector_invalid", path, "invalid attribute selector"));
+        }
+        else
+            parseSelector(node.source, `${path}/source`, diagnostics, depth + 1);
+    }
+    else if (node.op === "union" || node.op === "intersection") {
+        if (!exactKeys(node, ["op", "selectors"]) || !Array.isArray(node.selectors) || node.selectors.length === 0)
+            diagnostics.push(tmwDiagnostic("selector_invalid", path, "selector set must be non-empty"));
+        else
+            node.selectors.forEach((item, index) => parseSelector(item, `${path}/selectors/${index}`, diagnostics, depth + 1));
+    }
+    else if (node.op === "difference") {
+        if (!exactKeys(node, ["left", "op", "right"]))
+            diagnostics.push(tmwDiagnostic("selector_invalid", path, "invalid difference selector"));
+        else {
+            parseSelector(node.left, `${path}/left`, diagnostics, depth + 1);
+            parseSelector(node.right, `${path}/right`, diagnostics, depth + 1);
+        }
+    }
+    else
+        diagnostics.push(tmwDiagnostic("selector_unknown_op", `${path}/op`, `unknown selector op ${node.op}`));
+    return node;
+}
+function parseConditionExpression(value, path, diagnostics, depth = 0, visiting = new WeakSet(), semanticStableIds = new Set()) {
+    if (depth >= MAX_CONDITION_DEPTH) {
+        diagnostics.push(tmwDiagnostic("condition_depth_exceeded", path, `condition depth exceeds ${MAX_CONDITION_DEPTH}`));
+        return null;
+    }
+    const node = record(value);
+    if (node === null || typeof node.op !== "string") {
+        diagnostics.push(tmwDiagnostic("condition_expression_invalid", path, "condition must be an object with op"));
+        return null;
+    }
+    if (visiting.has(node)) {
+        diagnostics.push(tmwDiagnostic("condition_cycle", path, "condition expression must be acyclic"));
+        return null;
+    }
+    visiting.add(node);
+    try {
+        if (node.op === "value_input") {
+            if (!exactKeys(node, ["op", "port"]) || node.port !== "value") {
+                diagnostics.push(tmwDiagnostic("condition_value_input_invalid", path, "value_input requires the boolean value port"));
+                return null;
+            }
+            return Object.freeze({ op: "value_input", port: "value" });
+        }
+        if (node.op === "scene_field") {
+            if (!exactKeys(node, ["op", "field", "comparison", "value"]) || !["world_time", "location", "scene_id", "present_entity_ids"].includes(String(node.field)) || !CONDITION_COMPARISONS.has(String(node.comparison))) {
+                diagnostics.push(tmwDiagnostic("condition_scene_field_invalid", path, "scene_field requires a supported Scene field and comparison"));
+                return null;
+            }
+            const expectedValid = node.field === "world_time" ? typeof node.value === "number" && Number.isFinite(node.value)
+                : node.field === "scene_id" ? typeof node.value === "string"
+                    : node.field === "present_entity_ids" ? node.comparison === "contains" ? typeof node.value === "string" : Array.isArray(node.value) && node.value.every((v) => typeof v === "string")
+                        : node.value === null || isTmwTypedValueV1("spatial_ref", node.value);
+            const comparisonValid = node.field === "world_time" ? node.comparison !== "contains" : node.field === "location" ? ["eq", "neq"].includes(String(node.comparison)) : ["eq", "neq", "contains"].includes(String(node.comparison));
+            if (!expectedValid || !comparisonValid) {
+                diagnostics.push(tmwDiagnostic("condition_scene_field_type_invalid", path, "Scene comparison operand type mismatch"));
+                return null;
+            }
+            return Object.freeze({ op: "scene_field", field: node.field, comparison: node.comparison, value: node.value });
+        }
+        if (node.op === "literal") {
+            if (!exactKeys(node, ["op", "value"]) || typeof node.value !== "boolean") {
+                diagnostics.push(tmwDiagnostic("condition_literal_invalid", path, "literal requires exactly a boolean value"));
+                return null;
+            }
+            return Object.freeze({ op: "literal", value: node.value });
+        }
+        if (node.op === "event_field") {
+            if (!exactKeys(node, ["comparison", "op", "path", "value"])
+                || !Array.isArray(node.path)
+                || node.path.length === 0
+                || !node.path.every(identifier)
+                || !CONDITION_COMPARISONS.has(String(node.comparison))
+                || !jsonPrimitive(node.value)) {
+                diagnostics.push(tmwDiagnostic("condition_event_field_invalid", path, "event_field has invalid, missing, or unknown fields"));
+                return null;
+            }
+            return Object.freeze({
+                op: "event_field",
+                path: Object.freeze([...node.path]),
+                comparison: node.comparison,
+                value: node.value,
+            });
+        }
+        if (node.op === "selector_exists") {
+            if (!exactKeys(node, ["op", "selector"])) {
+                diagnostics.push(tmwDiagnostic("condition_selector_invalid", path, "selector_exists has invalid, missing, or unknown fields"));
+                return null;
+            }
+            const selector = parseSelector(node.selector, `${path}/selector`, diagnostics);
+            return selector === null ? null : Object.freeze({ op: "selector_exists", selector });
+        }
+        if (node.op === "nl_condition") {
+            const keys = node.anchor === undefined
+                ? ["locale", "op", "stable_id", "text"]
+                : ["anchor", "locale", "op", "stable_id", "text"];
+            if (!exactKeys(node, keys)
+                || !identifier(node.stable_id)
+                || typeof node.text !== "string"
+                || node.text.length === 0
+                || node.text.trim() !== node.text
+                || node.text.normalize("NFC") !== node.text
+                || !canonicalLocale(node.locale)) {
+                diagnostics.push(tmwDiagnostic("condition_nl_invalid", path, "nl_condition has invalid, missing, or unknown fields"));
+                return null;
+            }
+            if (semanticStableIds.has(node.stable_id)) {
+                diagnostics.push(tmwDiagnostic("condition_nl_stable_id_duplicate", `${path}/stable_id`, "nl_condition stable_id must be unique within its condition expression", [node.stable_id]));
+                return null;
+            }
+            semanticStableIds.add(node.stable_id);
+            const anchor = node.anchor === undefined
+                ? undefined
+                : parseSelector(node.anchor, `${path}/anchor`, diagnostics);
+            if (node.anchor !== undefined && anchor === null)
+                return null;
+            if (anchor === undefined || anchor === null)
+                return Object.freeze({
+                    op: "nl_condition",
+                    stable_id: node.stable_id,
+                    text: node.text,
+                    locale: node.locale,
+                });
+            return Object.freeze({
+                op: "nl_condition",
+                stable_id: node.stable_id,
+                text: node.text,
+                locale: node.locale,
+                anchor,
+            });
+        }
+        if (node.op === "not") {
+            if (!exactKeys(node, ["op", "value"])) {
+                diagnostics.push(tmwDiagnostic("condition_not_invalid", path, "not requires exactly one value"));
+                return null;
+            }
+            const child = parseConditionExpression(node.value, `${path}/value`, diagnostics, depth + 1, visiting, semanticStableIds);
+            return child === null ? null : Object.freeze({ op: "not", value: child });
+        }
+        if (node.op === "all" || node.op === "any") {
+            if (!exactKeys(node, ["op", "values"]) || !Array.isArray(node.values) || node.values.length === 0) {
+                diagnostics.push(tmwDiagnostic("condition_values_invalid", path, `${node.op} requires a non-empty values array and no unknown fields`));
+                return null;
+            }
+            const values = node.values.map((item, index) => parseConditionExpression(item, `${path}/values/${index}`, diagnostics, depth + 1, visiting, semanticStableIds));
+            if (values.some((item) => item === null))
+                return null;
+            return Object.freeze({
+                op: node.op,
+                values: Object.freeze(values),
+            });
+        }
+        diagnostics.push(tmwDiagnostic("condition_unknown_op", `${path}/op`, `unknown condition op ${node.op}`));
+        return null;
+    }
+    finally {
+        visiting.delete(node);
+    }
+}
+function parseNodeArray(value, kind, path, diagnostics) {
+    if (!Array.isArray(value)) {
+        diagnostics.push(tmwDiagnostic("node_array_required", path, "expected an array"));
+        return [];
+    }
+    return value.flatMap((item, index) => {
+        const nodePath = `${path}/${index}`;
+        const rawNode = record(item);
+        if (rawNode === null || !identifier(rawNode.stable_id)) {
+            diagnostics.push(tmwDiagnostic("stable_id_invalid", `${nodePath}/stable_id`, "stable_id is required and must be canonical"));
+            return [];
+        }
+        const stableId = rawNode.stable_id;
+        const node = {
+            ...rawNode,
+            enabled: rawNode.enabled === undefined ? true : rawNode.enabled,
+        };
+        if (typeof node.enabled !== "boolean") {
+            diagnostics.push(tmwDiagnostic("node_enabled_invalid", `${nodePath}/enabled`, "enabled must be boolean", [stableId]));
+        }
+        if (node.kind !== kind)
+            diagnostics.push(tmwDiagnostic("node_kind_invalid", `${nodePath}/kind`, `node kind must equal ${kind}`, [stableId]));
+        if (!isTmwEffectiveTime(node.effective_time))
+            diagnostics.push(tmwDiagnostic("effective_time_invalid", `${nodePath}/effective_time`, "expected a canonical TMW3 clock coordinate", [stableId]));
+        if (kind === "event") {
+            if (!exactKeys(node, ["effective_time", "enabled", "event_type", "hard_fact", "kind", "selector", "stable_id"])
+                || !identifier(node.event_type)
+                || typeof node.hard_fact !== "boolean")
+                diagnostics.push(tmwDiagnostic("event_node_invalid", nodePath, "event node has invalid or unknown fields", [stableId]));
+            if (node.selector !== null)
+                parseSelector(node.selector, `${nodePath}/selector`, diagnostics);
+        }
+        else if (kind === "condition") {
+            if (!exactKeys(node, ["effective_time", "enabled", "expression", "kind", "stable_id"])) {
+                diagnostics.push(tmwDiagnostic("condition_node_invalid", nodePath, "condition node has invalid or unknown fields", [stableId]));
+            }
+            const expression = parseConditionExpression(node.expression, `${nodePath}/expression`, diagnostics);
+            if (expression !== null)
+                node.expression = expression;
+        }
+        else if (kind === "effect") {
+            if (!exactKeys(node, ["arguments", "capability_id", "effective_time", "enabled", "execution_policy", "idempotency_key", "kind", "priority", "rewrite_policy", "selector", "stable_id"])
+                || !identifier(node.capability_id)
+                || record(node.arguments) === null
+                || (node.execution_policy !== "attempt_once" && node.execution_policy !== "ensure_until")
+                || (node.rewrite_policy !== "normal_only" && node.rewrite_policy !== "rewrite_only" && node.rewrite_policy !== "normal_and_rewrite")
+                || !Number.isSafeInteger(node.priority)
+                || node.priority < 0
+                || !identifier(node.idempotency_key)) {
+                diagnostics.push(tmwDiagnostic("effect_node_invalid", nodePath, "effect node has invalid, missing, or unknown fields", [stableId]));
+            }
+            if (node.selector !== null)
+                parseSelector(node.selector, `${nodePath}/selector`, diagnostics);
+        }
+        else {
+            const presentationPayload = parsePresentationPayloadV3(node.payload);
+            if (!exactKeys(node, ["effective_time", "enabled", "intent_type", "kind", "payload", "stable_id"]) || !identifier(node.intent_type) || presentationPayload === null || node.intent_type !== presentationPayload.kind)
+                diagnostics.push(tmwDiagnostic("presentation_node_invalid", nodePath, "presentation node has invalid fields or mismatched intent type", [stableId]));
+        }
+        return [node];
+    });
+}
+export function parseTriggerDocumentV3(value) {
+    const diagnostics = [];
+    const root = record(value);
+    if (root === null)
+        return tmwFailure([tmwDiagnostic("tmw3_required", "$", "TriggerDocumentV3 object required")]);
+    if (!exactKeys(root, root.value_graph === undefined ? ROOT_KEYS : [...ROOT_KEYS, "value_graph"]))
+        diagnostics.push(tmwDiagnostic("document_exact_keys_invalid", "$", "TriggerDocumentV3 contains missing or unknown fields"));
+    if (root.version !== TRIGGER_DOCUMENT_V3_VERSION)
+        diagnostics.push(tmwDiagnostic("tmw3_required", "$/version", "version must equal 3"));
+    if (root.runtime_generation !== TMW_RUNTIME_GENERATION)
+        diagnostics.push(tmwDiagnostic("unsupported_runtime_generation", "$/runtime_generation", "runtime_generation must equal 3"));
+    if (!isSha256Hex(root.runtime_contract_hash))
+        diagnostics.push(tmwDiagnostic("runtime_contract_hash_invalid", "$/runtime_contract_hash", "expected lowercase SHA-256"));
+    if (!identifier(root.registry_version))
+        diagnostics.push(tmwDiagnostic("registry_version_invalid", "$/registry_version", "registry_version must be canonical"));
+    const events = parseNodeArray(root.events, "event", "$/events", diagnostics);
+    const conditions = parseNodeArray(root.conditions, "condition", "$/conditions", diagnostics);
+    const effects = parseNodeArray(root.effects, "effect", "$/effects", diagnostics);
+    const presentations = parseNodeArray(root.presentations, "presentation", "$/presentations", diagnostics);
+    const edges = [];
+    let valueGraph;
+    if (root.value_graph !== undefined) {
+        try {
+            valueGraph = parseTmwValueGraphV1(root.value_graph);
+        }
+        catch (error) {
+            diagnostics.push(tmwDiagnostic("value_graph_invalid", "$/value_graph", error instanceof Error ? error.message : "invalid value graph"));
+        }
+    }
+    if (!Array.isArray(root.edges))
+        diagnostics.push(tmwDiagnostic("edge_array_required", "$/edges", "expected an array"));
+    else
+        root.edges.forEach((item, index) => {
+            const edge = record(item);
+            const path = `$/edges/${index}`;
+            if (edge === null || !exactKeys(edge, ["from_stable_id", "to_stable_id"]) || !identifier(edge.from_stable_id) || !identifier(edge.to_stable_id))
+                diagnostics.push(tmwDiagnostic("edge_invalid", path, "edge has invalid or unknown fields"));
+            else
+                edges.push(edge);
+        });
+    const ordered = orderTmwDiagnostics(diagnostics);
+    if (ordered.some((diagnostic) => diagnostic.severity === "error"))
+        return tmwFailure(ordered);
+    return tmwSuccess(Object.freeze({
+        version: TRIGGER_DOCUMENT_V3_VERSION,
+        runtime_generation: TMW_RUNTIME_GENERATION,
+        runtime_contract_hash: root.runtime_contract_hash,
+        registry_version: root.registry_version,
+        events: Object.freeze(events),
+        conditions: Object.freeze(conditions),
+        effects: Object.freeze(effects),
+        presentations: Object.freeze(presentations),
+        edges: Object.freeze(edges),
+        ...(valueGraph === undefined ? {} : { value_graph: valueGraph }),
+    }), ordered);
+}
+export function allTriggerNodesV3(document) {
+    return [...document.events, ...document.conditions, ...document.effects, ...document.presentations];
+}

package/dist/turn-commit.d.ts

@@ -0,0 +1,56 @@
+import { TMW_RUNTIME_GENERATION } from "./runtime-contract.js";
+import { type TmwJsonValue } from "./runtime-trace.js";
+export type TurnCommitTerminalKind = "committed" | "failed" | "aborted" | "disposed";
+export interface TurnCommitIdentity {
+    readonly operationId: string;
+    readonly turnId: string;
+    readonly epoch: number;
+    readonly runtimeGeneration: typeof TMW_RUNTIME_GENERATION;
+    readonly runtimeContractHash: string;
+    readonly artifactDigest: string;
+    readonly sourceRevision: string;
+    readonly timelineRevision: string;
+    readonly leaseId: string;
+}
+export interface TurnCommitTerminalReceipt extends TurnCommitIdentity {
+    readonly schemaVersion: 3;
+    readonly terminal: TurnCommitTerminalKind;
+    readonly reasonCode: string | null;
+    readonly operationDigest: string;
+    readonly budgetReceiptDigest: string;
+    readonly stageDigests: Readonly<Record<string, string>>;
+    readonly activationReceiptDigest: string | null;
+    readonly preActivationTerminalDigest: string;
+}
+export interface TurnCommitTerminalStore {
+    read(operationId: string): Promise<TurnCommitTerminalReceipt | null>;
+    putIfAbsent(operationId: string, receipt: TurnCommitTerminalReceipt): Promise<Readonly<{
+        status: "stored" | "exists";
+        receipt: TurnCommitTerminalReceipt;
+    }>>;
+}
+export interface TurnCommitOperationSnapshot {
+    readonly identity: TurnCommitIdentity;
+    readonly operationDigest: string;
+    readonly stageDigests: Readonly<Record<string, string>>;
+    readonly terminal: TurnCommitTerminalReceipt | null;
+}
+export declare class DurableTurnCommitOperation {
+    #private;
+    private constructor();
+    static open(input: Readonly<{
+        identity: TurnCommitIdentity;
+        operation: TmwJsonValue;
+        store: TurnCommitTerminalStore;
+    }>): Promise<DurableTurnCommitOperation>;
+    recordStage(stageInput: string, digestInput: string): void;
+    commit(input: Readonly<{
+        budgetReceiptDigest: string;
+        activationReceiptDigest: string;
+    }>): Promise<TurnCommitTerminalReceipt>;
+    fail(reasonCode: string, budgetReceiptDigest: string): Promise<TurnCommitTerminalReceipt>;
+    abort(reasonCode: string, budgetReceiptDigest: string): Promise<TurnCommitTerminalReceipt>;
+    dispose(reasonCode: string, budgetReceiptDigest: string): Promise<TurnCommitTerminalReceipt>;
+    snapshot(): TurnCommitOperationSnapshot;
+    previewCommittedTerminalDigest(budgetReceiptDigestInput: string): Promise<string>;
+}