@world-engines/tmw 0.1.0-alpha.0

package/dist/durable-intent.js

@@ -0,0 +1,60 @@
+import { TMW_RUNTIME_GENERATION } from "./runtime-contract.js";
+import { canonicalTmwJsonValue, requireTmwIdentifier, requireTmwSafeInteger, requireTmwSha256, } from "./runtime-trace.js";
+const ALLOWED_TRANSITIONS = Object.freeze({
+    active: new Set(["blocked", "applying", "cancelled", "superseded", "invalidated", "failed"]),
+    blocked: new Set(["active", "applying", "cancelled", "superseded", "invalidated", "failed"]),
+    applying: new Set(["blocked", "satisfied", "cancelled", "superseded", "invalidated", "failed"]),
+    satisfied: new Set(),
+    cancelled: new Set(),
+    superseded: new Set(),
+    invalidated: new Set(),
+    failed: new Set(),
+});
+export function canonicalDurableIntent(input) {
+    if (input.runtimeGeneration !== 3)
+        throw new Error("unsupported_runtime_generation");
+    if (!(input.state in ALLOWED_TRANSITIONS))
+        throw new Error("tmw_intent_state_invalid");
+    return Object.freeze({
+        intentId: requireTmwIdentifier(input.intentId, "intent_id"),
+        epoch: requireTmwSafeInteger(input.epoch, "intent_epoch", 1),
+        runtimeGeneration: TMW_RUNTIME_GENERATION,
+        runtimeContractHash: requireTmwSha256(input.runtimeContractHash, "intent_contract_hash"),
+        artifactDigest: requireTmwSha256(input.artifactDigest, "intent_artifact_digest"),
+        sourceRevision: requireTmwIdentifier(input.sourceRevision, "intent_source_revision"),
+        timelineRevision: requireTmwIdentifier(input.timelineRevision, "intent_timeline_revision"),
+        turnId: requireTmwIdentifier(input.turnId, "intent_turn_id"),
+        operationId: requireTmwIdentifier(input.operationId, "intent_operation_id"),
+        capabilityId: requireTmwIdentifier(input.capabilityId, "intent_capability_id"),
+        idempotencyKey: requireTmwIdentifier(input.idempotencyKey, "intent_idempotency_key"),
+        conflictKey: requireTmwIdentifier(input.conflictKey, "intent_conflict_key"),
+        priority: requireTmwSafeInteger(input.priority, "intent_priority"),
+        state: input.state,
+        selectorSnapshotHash: requireTmwSha256(input.selectorSnapshotHash, "intent_selector_snapshot_hash"),
+        payload: canonicalTmwJsonValue(input.payload, "intent_payload"),
+        lastReceiptDigest: input.lastReceiptDigest === null
+            ? null
+            : requireTmwSha256(input.lastReceiptDigest, "intent_receipt_digest"),
+        reasonCode: input.reasonCode === null
+            ? null
+            : requireTmwIdentifier(input.reasonCode, "intent_reason_code"),
+    });
+}
+export function transitionDurableIntent(currentInput, next) {
+    const current = canonicalDurableIntent(currentInput);
+    if (next.state === current.state) {
+        if (next.lastReceiptDigest !== current.lastReceiptDigest || next.reasonCode !== current.reasonCode) {
+            throw new Error("tmw_intent_same_state_rewrite_forbidden");
+        }
+        return current;
+    }
+    if (!ALLOWED_TRANSITIONS[current.state].has(next.state)) {
+        throw new Error("tmw_intent_transition_forbidden");
+    }
+    return canonicalDurableIntent({
+        ...current,
+        state: next.state,
+        lastReceiptDigest: next.lastReceiptDigest,
+        reasonCode: next.reasonCode,
+    });
+}

package/dist/effect-flow.d.ts

@@ -0,0 +1,69 @@
+import { type TmwJsonValue } from "./runtime-trace.js";
+import type { SelectorAstV3 } from "./selector-ast.js";
+import type { EffectEffectiveTime } from "./time-domains.js";
+export type EffectExecutionPolicy = "attempt_once" | "ensure_until";
+export type EffectRewritePolicy = "normal_only" | "rewrite_only" | "normal_and_rewrite";
+export type EffectMergePolicy = "replace" | "max" | "min" | "union" | "intersection" | "reject";
+export interface CapabilityDescriptorView {
+    readonly capabilityId: string;
+    readonly profileIds: ReadonlyArray<string>;
+    readonly executorKind: "command" | "reconciler";
+    readonly conflictKey: string;
+    readonly mergePolicy: EffectMergePolicy;
+    readonly allowsExternalSideEffect: boolean;
+    readonly selectorRequired: boolean;
+}
+export interface CapabilityRegistryView {
+    resolve(capabilityId: string): CapabilityDescriptorView | null;
+}
+export interface EffectInvocation {
+    readonly effectId: string;
+    readonly capabilityId: string;
+    readonly selector: SelectorAstV3 | null;
+    readonly effectiveTime: EffectEffectiveTime;
+    readonly input: TmwJsonValue;
+    readonly executionPolicy: EffectExecutionPolicy;
+    readonly rewritePolicy: EffectRewritePolicy;
+    readonly priority: number;
+    readonly idempotencyKey: string;
+}
+export interface EffectFlowInput {
+    readonly epoch: number;
+    readonly runtimeContractHash: string;
+    readonly artifactDigest: string;
+    readonly sourceRevision: string;
+    readonly timelineRevision: string;
+    readonly turnId: string;
+    readonly capabilityProfileId: string;
+    readonly mode: "normal" | "rewrite";
+    readonly conditionTruth: "true" | "false" | "unknown";
+    readonly effects: ReadonlyArray<EffectInvocation>;
+    readonly maxEffects: number;
+}
+export interface PlannedEffect {
+    readonly planIndex: number;
+    readonly effectId: string;
+    readonly capabilityId: string;
+    readonly selector: SelectorAstV3 | null;
+    readonly effectiveTime: EffectEffectiveTime;
+    readonly input: TmwJsonValue;
+    readonly executionPolicy: EffectExecutionPolicy;
+    readonly rewritePolicy: EffectRewritePolicy;
+    readonly priority: number;
+    readonly idempotencyKey: string;
+    readonly conflictKey: string;
+    readonly mergePolicy: EffectMergePolicy;
+    readonly externalSideEffect: boolean;
+}
+export interface EffectPlan {
+    readonly status: "ready" | "skipped" | "suspended";
+    readonly reason: "condition_true" | "condition_false" | "condition_unknown";
+    readonly epoch: number;
+    readonly runtimeContractHash: string;
+    readonly artifactDigest: string;
+    readonly sourceRevision: string;
+    readonly timelineRevision: string;
+    readonly turnId: string;
+    readonly effects: ReadonlyArray<PlannedEffect>;
+}
+export declare function planEffectFlow(input: EffectFlowInput, registry: CapabilityRegistryView): EffectPlan;

package/dist/effect-flow.js

@@ -0,0 +1,98 @@
+import { canonicalTmwJsonValue, requireTmwIdentifier, requireTmwSafeInteger, requireTmwSha256, } from "./runtime-trace.js";
+function policyAllows(policy, mode) {
+    return policy === "normal_and_rewrite"
+        || (policy === "normal_only" && mode === "normal")
+        || (policy === "rewrite_only" && mode === "rewrite");
+}
+function requireExecutionPolicy(value) {
+    if (value !== "attempt_once" && value !== "ensure_until") {
+        throw new Error("tmw_effect_execution_policy_invalid");
+    }
+    return value;
+}
+function requireRewritePolicy(value) {
+    if (value !== "normal_only" && value !== "rewrite_only" && value !== "normal_and_rewrite") {
+        throw new Error("tmw_effect_rewrite_policy_invalid");
+    }
+    return value;
+}
+export function planEffectFlow(input, registry) {
+    const binding = {
+        epoch: requireTmwSafeInteger(input.epoch, "effect_epoch", 1),
+        runtimeContractHash: requireTmwSha256(input.runtimeContractHash, "effect_contract_hash"),
+        artifactDigest: requireTmwSha256(input.artifactDigest, "effect_artifact_digest"),
+        sourceRevision: requireTmwIdentifier(input.sourceRevision, "effect_source_revision"),
+        timelineRevision: requireTmwIdentifier(input.timelineRevision, "effect_timeline_revision"),
+        turnId: requireTmwIdentifier(input.turnId, "effect_turn_id"),
+    };
+    const maxEffects = requireTmwSafeInteger(input.maxEffects, "effect_max_effects", 1);
+    if (input.effects.length > maxEffects)
+        throw new Error("tmw_effect_budget_exhausted");
+    if (input.conditionTruth !== "true") {
+        return Object.freeze({
+            status: input.conditionTruth === "unknown" ? "suspended" : "skipped",
+            reason: input.conditionTruth === "unknown"
+                ? "condition_unknown"
+                : "condition_false",
+            ...binding,
+            effects: Object.freeze([]),
+        });
+    }
+    const profileId = requireTmwIdentifier(input.capabilityProfileId, "effect_profile_id");
+    const seenIds = new Set();
+    const seenIdempotency = new Set();
+    const planned = [];
+    for (const effect of input.effects) {
+        const effectId = requireTmwIdentifier(effect.effectId, "effect_id");
+        if (seenIds.has(effectId))
+            throw new Error("tmw_effect_id_duplicate");
+        seenIds.add(effectId);
+        const idempotencyKey = requireTmwIdentifier(effect.idempotencyKey, "effect_idempotency_key");
+        if (seenIdempotency.has(idempotencyKey))
+            throw new Error("tmw_effect_idempotency_duplicate");
+        seenIdempotency.add(idempotencyKey);
+        const executionPolicy = requireExecutionPolicy(effect.executionPolicy);
+        const rewritePolicy = requireRewritePolicy(effect.rewritePolicy);
+        const priority = requireTmwSafeInteger(effect.priority, "effect_priority");
+        const canonicalInput = canonicalTmwJsonValue(effect.input, "effect_input");
+        if (!policyAllows(rewritePolicy, input.mode))
+            continue;
+        const capabilityId = requireTmwIdentifier(effect.capabilityId, "effect_capability_id");
+        const capability = registry.resolve(capabilityId);
+        if (capability === null)
+            throw new Error("tmw_effect_capability_unknown");
+        if (capability.capabilityId !== capabilityId)
+            throw new Error("tmw_effect_capability_identity_mismatch");
+        if (!capability.profileIds.includes(profileId))
+            throw new Error("tmw_effect_capability_forbidden");
+        if (capability.selectorRequired && effect.selector === null) {
+            throw new Error("tmw_effect_selector_required");
+        }
+        if (executionPolicy === "ensure_until" && capability.executorKind !== "reconciler") {
+            throw new Error("tmw_effect_ensure_until_requires_reconciler");
+        }
+        planned.push(Object.freeze({
+            planIndex: planned.length,
+            effectId,
+            capabilityId,
+            selector: effect.selector,
+            effectiveTime: effect.effectiveTime,
+            input: canonicalInput,
+            executionPolicy,
+            rewritePolicy,
+            priority,
+            idempotencyKey,
+            conflictKey: requireTmwIdentifier(capability.conflictKey, "effect_conflict_key"),
+            mergePolicy: capability.mergePolicy,
+            externalSideEffect: capability.allowsExternalSideEffect,
+        }));
+    }
+    planned.sort((left, right) => right.priority - left.priority
+        || (left.effectId < right.effectId ? -1 : left.effectId > right.effectId ? 1 : 0));
+    return Object.freeze({
+        status: "ready",
+        reason: "condition_true",
+        ...binding,
+        effects: Object.freeze(planned.map((effect, index) => Object.freeze({ ...effect, planIndex: index }))),
+    });
+}

package/dist/event-fabric.d.ts

@@ -0,0 +1,81 @@
+import { TMW_RUNTIME_GENERATION } from "./runtime-contract.js";
+import { type RuntimeTraceSnapshot, type TmwJsonValue } from "./runtime-trace.js";
+import { type CrossingDirection, type EventEffectiveTime, type RealTimeClock } from "./time-domains.js";
+export { crossingPolicyAllows } from "./time-domains.js";
+export type { CrossingDirection, CrossingPolicy, RealTimeClock, TmwClockDomain, WallClockPolicy, } from "./time-domains.js";
+export interface EventScope {
+    readonly scenarioId: string;
+    readonly saveId: string;
+    readonly worldlineId: string;
+}
+export interface PresentationCoordinate {
+    readonly planId: string;
+    readonly segmentId: string;
+    readonly cursor: number;
+    readonly eventSeq: number;
+}
+export interface RealTimeCoordinate {
+    readonly clock: RealTimeClock;
+    readonly value: number;
+}
+export interface EventTimeCoordinates {
+    readonly logicalSeq: number;
+    readonly worldTime: number | null;
+    readonly presentation: PresentationCoordinate | null;
+    readonly realTime: RealTimeCoordinate | null;
+}
+export interface CommittedEventEnvelope {
+    readonly eventId: string;
+    readonly eventType: string;
+    readonly hardFact: boolean;
+    readonly epoch: number;
+    readonly runtimeGeneration: typeof TMW_RUNTIME_GENERATION;
+    readonly runtimeContractHash: string;
+    readonly artifactDigest: string;
+    readonly sourceRevision: string;
+    readonly timelineRevision: string;
+    readonly scope: EventScope;
+    readonly coordinates: EventTimeCoordinates;
+    readonly effectiveTime: EventEffectiveTime;
+    readonly crossingDirection: CrossingDirection;
+    readonly correlationId: string;
+    readonly causationId: string | null;
+    readonly replacementLineage: ReadonlyArray<string>;
+    readonly payloadHash: string;
+    readonly payload: TmwJsonValue;
+    readonly commitReceiptDigest: string;
+}
+export interface EventFabricAppendReceipt {
+    readonly status: "appended" | "duplicate";
+    readonly ledgerSequence: number;
+    readonly eventId: string;
+    readonly dedupeKey: string;
+    readonly ledgerHead: string;
+}
+export declare const TMW_EMPTY_LEDGER_HEAD: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+export interface EventFabricSnapshot {
+    readonly epoch: number;
+    readonly runtimeContractHash: string;
+    readonly artifactDigest: string;
+    readonly timelineRevision: string;
+    readonly ledgerHead: string;
+    readonly events: ReadonlyArray<CommittedEventEnvelope>;
+    readonly trace: RuntimeTraceSnapshot;
+}
+export declare function canonicalCommittedEvent(input: CommittedEventEnvelope): CommittedEventEnvelope;
+export declare function eventFabricDedupeKey(event: CommittedEventEnvelope): string;
+export declare function compareCommittedEvents(left: CommittedEventEnvelope, right: CommittedEventEnvelope): number;
+export declare class EventFabric {
+    #private;
+    constructor(input: Readonly<{
+        epoch: number;
+        runtimeContractHash: string;
+        artifactDigest: string;
+        timelineRevision: string;
+        traceLimit?: number;
+    }>);
+    appendCommitted(input: CommittedEventEnvelope): Promise<EventFabricAppendReceipt>;
+    restoreLedgerHead(ledgerHeadInput: string): void;
+    orderedEvents(): ReadonlyArray<CommittedEventEnvelope>;
+    snapshot(): EventFabricSnapshot;
+}

package/dist/event-fabric.js

@@ -0,0 +1,227 @@
+import { TMW_RUNTIME_GENERATION } from "./runtime-contract.js";
+import { BoundedRuntimeTrace, canonicalTmwJson, canonicalTmwJsonValue, requireTmwIdentifier, requireTmwSafeInteger, requireTmwSha256, tmwSha256Hex, } from "./runtime-trace.js";
+import { canonicalTmwEffectiveTime, compareTmwEffectiveTime, crossingPolicyAllows, } from "./time-domains.js";
+export { crossingPolicyAllows } from "./time-domains.js";
+export const TMW_EMPTY_LEDGER_HEAD = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+function requireFiniteCoordinate(value, label) {
+    if (!Number.isFinite(value))
+        throw new Error(`tmw_event_${label}_invalid`);
+    return Object.is(value, -0) ? 0 : value;
+}
+function canonicalScope(scope) {
+    return Object.freeze({
+        scenarioId: requireTmwIdentifier(scope.scenarioId, "event_scenario_id"),
+        saveId: requireTmwIdentifier(scope.saveId, "event_save_id"),
+        worldlineId: requireTmwIdentifier(scope.worldlineId, "event_worldline_id"),
+    });
+}
+function canonicalPresentation(value) {
+    if (value === null)
+        return null;
+    return Object.freeze({
+        planId: requireTmwIdentifier(value.planId, "event_presentation_plan_id"),
+        segmentId: requireTmwIdentifier(value.segmentId, "event_presentation_segment_id"),
+        cursor: requireTmwSafeInteger(value.cursor, "event_presentation_cursor"),
+        eventSeq: requireTmwSafeInteger(value.eventSeq, "event_presentation_event_seq"),
+    });
+}
+function canonicalRealTime(value) {
+    if (value === null)
+        return null;
+    if (!["monotonic_session", "active_play", "wall_clock"].includes(value.clock)) {
+        throw new Error("tmw_event_real_time_clock_invalid");
+    }
+    return Object.freeze({ clock: value.clock, value: requireFiniteCoordinate(value.value, "real_time") });
+}
+export function canonicalCommittedEvent(input) {
+    if (input.runtimeGeneration !== 3)
+        throw new Error("unsupported_runtime_generation");
+    if (input.crossingDirection !== "forward" && input.crossingDirection !== "backward") {
+        throw new Error("tmw_event_crossing_direction_invalid");
+    }
+    const effectiveTime = canonicalTmwEffectiveTime(input.effectiveTime);
+    if (!crossingPolicyAllows(effectiveTime.crossing_policy, input.crossingDirection)) {
+        throw new Error("tmw_event_crossing_direction_forbidden");
+    }
+    const replacementLineage = Object.freeze(input.replacementLineage.map((id) => requireTmwIdentifier(id, "event_replacement_lineage")));
+    if (new Set(replacementLineage).size !== replacementLineage.length) {
+        throw new Error("tmw_event_replacement_lineage_duplicate");
+    }
+    const payload = canonicalTmwJsonValue(input.payload, "event_payload");
+    const coordinates = Object.freeze({
+        logicalSeq: requireTmwSafeInteger(input.coordinates.logicalSeq, "event_logical_seq"),
+        worldTime: input.coordinates.worldTime === null
+            ? null
+            : requireFiniteCoordinate(input.coordinates.worldTime, "world_time"),
+        presentation: canonicalPresentation(input.coordinates.presentation),
+        realTime: canonicalRealTime(input.coordinates.realTime),
+    });
+    const observedEffectiveValue = effectiveTime.domain === "logical_seq"
+        ? coordinates.logicalSeq
+        : effectiveTime.domain === "world_time"
+            ? coordinates.worldTime
+            : effectiveTime.domain === "presentation_seq"
+                ? coordinates.presentation?.eventSeq ?? null
+                : coordinates.realTime?.clock === effectiveTime.real_time_clock
+                    ? coordinates.realTime.value
+                    : null;
+    if (observedEffectiveValue === null || observedEffectiveValue !== effectiveTime.effective_value) {
+        throw new Error("tmw_event_effective_coordinate_mismatch");
+    }
+    return Object.freeze({
+        eventId: requireTmwIdentifier(input.eventId, "event_id"),
+        eventType: requireTmwIdentifier(input.eventType, "event_type"),
+        hardFact: (() => {
+            if (typeof input.hardFact !== "boolean")
+                throw new Error("tmw_event_hard_fact_invalid");
+            return input.hardFact;
+        })(),
+        epoch: requireTmwSafeInteger(input.epoch, "event_epoch", 1),
+        runtimeGeneration: TMW_RUNTIME_GENERATION,
+        runtimeContractHash: requireTmwSha256(input.runtimeContractHash, "event_contract_hash"),
+        artifactDigest: requireTmwSha256(input.artifactDigest, "event_artifact_digest"),
+        sourceRevision: requireTmwIdentifier(input.sourceRevision, "event_source_revision"),
+        timelineRevision: requireTmwIdentifier(input.timelineRevision, "event_timeline_revision"),
+        scope: canonicalScope(input.scope),
+        coordinates,
+        effectiveTime,
+        crossingDirection: input.crossingDirection,
+        correlationId: requireTmwIdentifier(input.correlationId, "event_correlation_id"),
+        causationId: input.causationId === null
+            ? null
+            : requireTmwIdentifier(input.causationId, "event_causation_id"),
+        replacementLineage,
+        payloadHash: requireTmwSha256(input.payloadHash, "event_payload_hash"),
+        payload,
+        commitReceiptDigest: requireTmwSha256(input.commitReceiptDigest, "event_commit_receipt_digest"),
+    });
+}
+export function eventFabricDedupeKey(event) {
+    return [
+        event.epoch,
+        event.timelineRevision,
+        event.sourceRevision,
+        event.eventId,
+        event.replacementLineage.join(","),
+    ].join(":");
+}
+export function compareCommittedEvents(left, right) {
+    if (left.coordinates.logicalSeq !== right.coordinates.logicalSeq) {
+        return left.coordinates.logicalSeq - right.coordinates.logicalSeq;
+    }
+    const effectiveOrder = compareTmwEffectiveTime(left.effectiveTime, right.effectiveTime);
+    if (effectiveOrder !== 0)
+        return effectiveOrder;
+    if (left.eventId !== right.eventId)
+        return left.eventId < right.eventId ? -1 : 1;
+    if (left.payloadHash !== right.payloadHash)
+        return left.payloadHash < right.payloadHash ? -1 : 1;
+    return 0;
+}
+async function nextLedgerHead(previous, event, sequence) {
+    return await tmwSha256Hex(canonicalTmwJson({
+        previous,
+        sequence,
+        eventId: event.eventId,
+        payloadHash: event.payloadHash,
+        commitReceiptDigest: event.commitReceiptDigest,
+    }));
+}
+export class EventFabric {
+    #epoch;
+    #runtimeContractHash;
+    #artifactDigest;
+    #timelineRevision;
+    #events = [];
+    #dedupe = new Map();
+    #trace;
+    #ledgerHead = TMW_EMPTY_LEDGER_HEAD;
+    #appendTail = Promise.resolve();
+    constructor(input) {
+        this.#epoch = requireTmwSafeInteger(input.epoch, "fabric_epoch", 1);
+        this.#runtimeContractHash = requireTmwSha256(input.runtimeContractHash, "fabric_contract_hash");
+        this.#artifactDigest = requireTmwSha256(input.artifactDigest, "fabric_artifact_digest");
+        this.#timelineRevision = requireTmwIdentifier(input.timelineRevision, "fabric_timeline_revision");
+        this.#trace = new BoundedRuntimeTrace(input.traceLimit);
+    }
+    async appendCommitted(input) {
+        let releaseAppend;
+        const precedingAppend = this.#appendTail;
+        this.#appendTail = new Promise((resolve) => {
+            releaseAppend = resolve;
+        });
+        await precedingAppend;
+        try {
+            const event = canonicalCommittedEvent(input);
+            this.#assertBinding(event);
+            const dedupeKey = eventFabricDedupeKey(event);
+            const previous = this.#dedupe.get(dedupeKey);
+            if (previous !== undefined) {
+                const existing = this.#events[previous.ledgerSequence];
+                if (existing?.payloadHash !== event.payloadHash
+                    || existing.commitReceiptDigest !== event.commitReceiptDigest) {
+                    throw new Error("tmw_event_dedupe_identity_conflict");
+                }
+                this.#trace.append({ kind: "event_duplicate", stableId: event.eventId, detail: { dedupeKey } });
+                return Object.freeze({ ...previous, status: "duplicate" });
+            }
+            const sequence = this.#events.length;
+            this.#ledgerHead = await nextLedgerHead(this.#ledgerHead, event, sequence);
+            this.#events.push(event);
+            const receipt = Object.freeze({
+                status: "appended",
+                ledgerSequence: sequence,
+                eventId: event.eventId,
+                dedupeKey,
+                ledgerHead: this.#ledgerHead,
+            });
+            this.#dedupe.set(dedupeKey, receipt);
+            this.#trace.append({
+                kind: "event_committed",
+                stableId: event.eventId,
+                detail: {
+                    ledgerSequence: sequence,
+                    clockDomain: event.effectiveTime.domain,
+                    effectiveValue: event.effectiveTime.effective_value,
+                },
+            });
+            return receipt;
+        }
+        finally {
+            releaseAppend();
+        }
+    }
+    restoreLedgerHead(ledgerHeadInput) {
+        if (this.#events.length !== 0 || this.#dedupe.size !== 0
+            || this.#ledgerHead !== TMW_EMPTY_LEDGER_HEAD) {
+            throw new Error("tmw_event_fabric_restore_barrier_closed");
+        }
+        this.#ledgerHead = requireTmwSha256(ledgerHeadInput, "fabric_ledger_head");
+    }
+    orderedEvents() {
+        return Object.freeze([...this.#events].sort(compareCommittedEvents));
+    }
+    snapshot() {
+        return Object.freeze({
+            epoch: this.#epoch,
+            runtimeContractHash: this.#runtimeContractHash,
+            artifactDigest: this.#artifactDigest,
+            timelineRevision: this.#timelineRevision,
+            ledgerHead: this.#ledgerHead,
+            events: Object.freeze([...this.#events]),
+            trace: this.#trace.snapshot(),
+        });
+    }
+    #assertBinding(event) {
+        if (event.epoch !== this.#epoch)
+            throw new Error("stale_content_epoch");
+        if (event.runtimeContractHash !== this.#runtimeContractHash) {
+            throw new Error("runtime_contract_hash_mismatch");
+        }
+        if (event.artifactDigest !== this.#artifactDigest)
+            throw new Error("tmw_event_artifact_mismatch");
+        if (event.timelineRevision !== this.#timelineRevision) {
+            throw new Error("tmw_event_timeline_revision_mismatch");
+        }
+    }
+}

package/dist/event-lifecycle.d.ts

@@ -0,0 +1,59 @@
+import type { CompiledPlanV3 } from "./compiled-plan.js";
+import type { DurableIntentV3 } from "./durable-intent.js";
+import type { PlannedEffect } from "./effect-flow.js";
+import type { CommittedEventEnvelope } from "./event-fabric.js";
+import { type TmwJsonPrimitive, type TmwJsonValue } from "./runtime-trace.js";
+import { type TmwPendingSceneClockCrossingV1 } from "./scene-state.js";
+import { TmwScheduler, type SuspensionRecord } from "./scheduler.js";
+export declare const TMW_EVENT_MAX_BROADCAST_COUNT = 256;
+export declare const TMW_EVENT_MAX_CAUSATION_DEPTH = 32;
+export declare const TMW_EVENT_MAX_VIEW_VISIBLE_FIELDS = 64;
+export declare const TMW_EVENT_CAPABILITY_ARGUMENT_SCHEMAS: Readonly<{
+    "event.create": Readonly<{
+        type: "object";
+        additionalProperties: false;
+        properties: Record<string, unknown>;
+        required: string[];
+    }>;
+    "event.delete": Readonly<{
+        type: "object";
+        additionalProperties: false;
+        properties: Record<string, unknown>;
+        required: string[];
+    }>;
+    "event.stop": Readonly<{
+        type: "object";
+        additionalProperties: false;
+        properties: Record<string, unknown>;
+        required: string[];
+    }>;
+    "event.start": Readonly<{
+        type: "object";
+        additionalProperties: false;
+        properties: Record<string, unknown>;
+        required: string[];
+    }>;
+    "event.broadcast": Readonly<{
+        type: "object";
+        additionalProperties: false;
+        properties: Record<string, unknown>;
+        required: string[];
+    }>;
+}>;
+export declare function canonicalTmwEventViewVisiblePayload(value: TmwJsonValue | undefined): Readonly<Record<string, TmwJsonPrimitive>> | null;
+export declare function isTmwEventLifecycleCapability(id: string): boolean;
+export declare function isTmwEventBroadcastSuspension(value: SuspensionRecord): boolean;
+export declare function isTmwEventDefinitionActive(nodeId: string, intents: ReadonlyArray<DurableIntentV3>): boolean;
+/** 事件定义始终来自已编译 world graph；这里只保存运行态与未来投递，不修改事实 ledger。 */
+export declare function reduceTmwEventLifecycle(input: Readonly<{
+    plan: CompiledPlanV3;
+    event: CommittedEventEnvelope;
+    effects: ReadonlyArray<PlannedEffect>;
+    intents: ReadonlyArray<DurableIntentV3>;
+    scheduler: TmwScheduler;
+    dueBroadcasts: ReadonlyArray<SuspensionRecord>;
+    pending: ReadonlyArray<TmwPendingSceneClockCrossingV1>;
+}>): Promise<Readonly<{
+    intents: ReadonlyArray<DurableIntentV3>;
+    pending: ReadonlyArray<TmwPendingSceneClockCrossingV1>;
+}>>;