@world-engines/tmw 0.1.0-alpha.0

package/dist/scheduler.d.ts

@@ -0,0 +1,55 @@
+import { TMW_RUNTIME_GENERATION } from "./runtime-contract.js";
+import type { EventScope, PresentationCoordinate, RealTimeCoordinate } from "./event-fabric.js";
+import { type CrossingDirection, type TmwEffectiveTime } from "./time-domains.js";
+import { type RuntimeClockTraceDetail, type TmwJsonValue } from "./runtime-trace.js";
+export interface SchedulerCoordinates {
+    readonly logicalSeq: number;
+    readonly worldTime: number | null;
+    readonly presentation: PresentationCoordinate | null;
+    readonly realTime: Readonly<Partial<Record<RealTimeCoordinate["clock"], number>>>;
+}
+export interface SuspensionRecord {
+    readonly suspensionId: string;
+    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 effectiveTime: TmwEffectiveTime;
+    readonly resumeNodeId: string;
+    readonly correlationId: string;
+    readonly cancellationKey: string | null;
+    readonly createdSnapshotHash: string;
+    readonly durablePayload: TmwJsonValue;
+}
+export interface SchedulerDueReceipt {
+    readonly suspensionId: string;
+    readonly status: "due" | "pending" | "direction_filtered" | "wall_clock_rejected";
+    readonly effectiveTime: TmwEffectiveTime;
+    readonly observedValue: number | null;
+    readonly crossingDirection: CrossingDirection;
+    readonly clockTrace: RuntimeClockTraceDetail;
+}
+export interface SchedulerSnapshot {
+    /** Last authority-observed coordinates. Missing on pre-clock Runtime3 saves. */
+    readonly cursor?: SchedulerCoordinates | null;
+    readonly suspensions: ReadonlyArray<SuspensionRecord>;
+}
+export declare function canonicalSchedulerCoordinates(input: SchedulerCoordinates): SchedulerCoordinates;
+export declare function mergeSchedulerCoordinates(previousInput: SchedulerCoordinates | null, observedInput: SchedulerCoordinates, crossingDirection: CrossingDirection): SchedulerCoordinates;
+export declare function canonicalSchedulerSnapshot(input: SchedulerSnapshot): SchedulerSnapshot;
+export declare function canonicalSuspension(input: SuspensionRecord): SuspensionRecord;
+export declare function evaluateSuspensionDue(suspensionInput: SuspensionRecord, coordinates: SchedulerCoordinates, crossingDirection: CrossingDirection, previousCoordinates?: SchedulerCoordinates | null): SchedulerDueReceipt;
+export declare class TmwScheduler {
+    #private;
+    constructor(snapshot?: SchedulerSnapshot);
+    schedule(input: SuspensionRecord): SuspensionRecord;
+    cancel(cancellationKey: string): ReadonlyArray<SuspensionRecord>;
+    poll(coordinates: SchedulerCoordinates, crossingDirection: CrossingDirection): ReadonlyArray<SchedulerDueReceipt>;
+    /** Advances only from caller-provided coordinates; it never samples a host clock. */
+    advance(coordinatesInput: SchedulerCoordinates, crossingDirection: CrossingDirection): ReadonlyArray<SchedulerDueReceipt>;
+    consumeDue(suspensionId: string): SuspensionRecord;
+    snapshot(): SchedulerSnapshot;
+}

package/dist/scheduler.js

@@ -0,0 +1,235 @@
+import { TMW_RUNTIME_GENERATION } from "./runtime-contract.js";
+import { canonicalTmwClockCoordinate, canonicalTmwEffectiveTime, crossingPolicyAllows, tmwEffectiveTimeCrossedDue, } from "./time-domains.js";
+import { canonicalTmwJsonValue, requireTmwIdentifier, requireTmwSafeInteger, requireTmwSha256, } from "./runtime-trace.js";
+function finiteCoordinate(value, label) {
+    if (!Number.isFinite(value) || Object.is(value, -0)) {
+        throw new Error(`tmw_scheduler_${label}_invalid`);
+    }
+    return value;
+}
+export function canonicalSchedulerCoordinates(input) {
+    const realTime = Object.create(null);
+    for (const clock of ["monotonic_session", "active_play", "wall_clock"]) {
+        const value = input.realTime[clock];
+        if (value !== undefined)
+            realTime[clock] = finiteCoordinate(value, `real_time_${clock}`);
+    }
+    return Object.freeze({
+        logicalSeq: canonicalTmwClockCoordinate(input.logicalSeq, "logical_seq"),
+        worldTime: input.worldTime === null
+            ? null
+            : canonicalTmwClockCoordinate(input.worldTime, "world_time"),
+        presentation: input.presentation === null
+            ? null
+            : Object.freeze({
+                planId: requireTmwIdentifier(input.presentation.planId, "scheduler_presentation_plan_id"),
+                segmentId: requireTmwIdentifier(input.presentation.segmentId, "scheduler_presentation_segment_id"),
+                cursor: canonicalTmwClockCoordinate(input.presentation.cursor, "presentation_seq"),
+                eventSeq: canonicalTmwClockCoordinate(input.presentation.eventSeq, "presentation_seq"),
+            }),
+        realTime: Object.freeze(realTime),
+    });
+}
+function mergePresentation(previous, observed) {
+    if (observed === null)
+        return previous;
+    if (previous !== null
+        && previous.planId === observed.planId
+        && previous.segmentId === observed.segmentId
+        && (observed.cursor < previous.cursor || observed.eventSeq < previous.eventSeq)) {
+        throw new Error("tmw_scheduler_presentation_clock_regressed");
+    }
+    return observed;
+}
+export function mergeSchedulerCoordinates(previousInput, observedInput, crossingDirection) {
+    const observed = canonicalSchedulerCoordinates(observedInput);
+    if (previousInput === null)
+        return observed;
+    const previous = canonicalSchedulerCoordinates(previousInput);
+    if (observed.logicalSeq < previous.logicalSeq) {
+        throw new Error("tmw_scheduler_logical_clock_regressed");
+    }
+    if (observed.worldTime !== null && previous.worldTime !== null
+        && ((crossingDirection === "forward" && observed.worldTime < previous.worldTime)
+            || (crossingDirection === "backward" && observed.worldTime > previous.worldTime))) {
+        throw new Error("tmw_scheduler_world_clock_direction_mismatch");
+    }
+    const realTime = {
+        ...previous.realTime,
+    };
+    for (const clock of ["monotonic_session", "active_play", "wall_clock"]) {
+        const value = observed.realTime[clock];
+        if (value === undefined)
+            continue;
+        const prior = previous.realTime[clock];
+        if (prior !== undefined && value < prior) {
+            throw new Error(`tmw_scheduler_real_time_clock_regressed:${clock}`);
+        }
+        realTime[clock] = value;
+    }
+    return Object.freeze({
+        logicalSeq: observed.logicalSeq,
+        worldTime: observed.worldTime ?? previous.worldTime,
+        presentation: mergePresentation(previous.presentation, observed.presentation),
+        realTime: Object.freeze(realTime),
+    });
+}
+export function canonicalSchedulerSnapshot(input) {
+    const suspensions = input.suspensions.map(canonicalSuspension).sort((left, right) => left.suspensionId < right.suspensionId ? -1 : left.suspensionId > right.suspensionId ? 1 : 0);
+    if (new Set(suspensions.map((item) => item.suspensionId)).size !== suspensions.length) {
+        throw new Error("tmw_scheduler_suspension_duplicate");
+    }
+    return Object.freeze({
+        cursor: input.cursor === undefined || input.cursor === null
+            ? null
+            : canonicalSchedulerCoordinates(input.cursor),
+        suspensions: Object.freeze(suspensions),
+    });
+}
+function canonicalScope(scope) {
+    return Object.freeze({
+        scenarioId: requireTmwIdentifier(scope.scenarioId, "scheduler_scenario_id"),
+        saveId: requireTmwIdentifier(scope.saveId, "scheduler_save_id"),
+        worldlineId: requireTmwIdentifier(scope.worldlineId, "scheduler_worldline_id"),
+    });
+}
+export function canonicalSuspension(input) {
+    if (input.runtimeGeneration !== 3)
+        throw new Error("unsupported_runtime_generation");
+    const effectiveTime = canonicalTmwEffectiveTime(input.effectiveTime);
+    return Object.freeze({
+        suspensionId: requireTmwIdentifier(input.suspensionId, "scheduler_suspension_id"),
+        epoch: requireTmwSafeInteger(input.epoch, "scheduler_epoch", 1),
+        runtimeGeneration: TMW_RUNTIME_GENERATION,
+        runtimeContractHash: requireTmwSha256(input.runtimeContractHash, "scheduler_contract_hash"),
+        artifactDigest: requireTmwSha256(input.artifactDigest, "scheduler_artifact_digest"),
+        sourceRevision: requireTmwIdentifier(input.sourceRevision, "scheduler_source_revision"),
+        timelineRevision: requireTmwIdentifier(input.timelineRevision, "scheduler_timeline_revision"),
+        scope: canonicalScope(input.scope),
+        effectiveTime,
+        resumeNodeId: requireTmwIdentifier(input.resumeNodeId, "scheduler_resume_node_id"),
+        correlationId: requireTmwIdentifier(input.correlationId, "scheduler_correlation_id"),
+        cancellationKey: input.cancellationKey === null
+            ? null
+            : requireTmwIdentifier(input.cancellationKey, "scheduler_cancellation_key"),
+        createdSnapshotHash: requireTmwSha256(input.createdSnapshotHash, "scheduler_snapshot_hash"),
+        durablePayload: canonicalTmwJsonValue(input.durablePayload, "scheduler_payload"),
+    });
+}
+function presentationValue(value) {
+    return value?.eventSeq ?? null;
+}
+function observedValue(suspension, coordinates) {
+    switch (suspension.effectiveTime.domain) {
+        case "logical_seq": return coordinates.logicalSeq;
+        case "world_time": return coordinates.worldTime;
+        case "presentation_seq": return presentationValue(coordinates.presentation);
+        case "real_time": {
+            const clock = suspension.effectiveTime.real_time_clock;
+            if (clock === null)
+                throw new Error("tmw_scheduler_real_time_clock_missing");
+            return coordinates.realTime[clock] ?? null;
+        }
+    }
+}
+function previousObservedValue(suspension, cursor) {
+    return cursor === null
+        ? suspension.effectiveTime.effective_value
+        : observedValue(suspension, cursor) ?? suspension.effectiveTime.effective_value;
+}
+export function evaluateSuspensionDue(suspensionInput, coordinates, crossingDirection, previousCoordinates = null) {
+    if (crossingDirection !== "forward" && crossingDirection !== "backward") {
+        throw new Error("tmw_scheduler_crossing_direction_invalid");
+    }
+    const suspension = canonicalSuspension(suspensionInput);
+    const observed = observedValue(suspension, coordinates);
+    const previousObserved = previousObservedValue(suspension, previousCoordinates);
+    let status = "pending";
+    if (!crossingPolicyAllows(suspension.effectiveTime.crossing_policy, crossingDirection)) {
+        status = "direction_filtered";
+    }
+    else if (suspension.effectiveTime.real_time_clock === "wall_clock"
+        && suspension.effectiveTime.wall_clock_policy === "reject") {
+        status = "wall_clock_rejected";
+    }
+    else if (observed !== null && tmwEffectiveTimeCrossedDue(suspension.effectiveTime, previousObserved, observed, crossingDirection)) {
+        status = "due";
+    }
+    return Object.freeze({
+        suspensionId: suspension.suspensionId,
+        status,
+        effectiveTime: suspension.effectiveTime,
+        observedValue: observed,
+        crossingDirection,
+        clockTrace: Object.freeze({
+            clockDomain: suspension.effectiveTime.domain,
+            observedValue: observed,
+            dueValue: suspension.effectiveTime.due_value,
+            previousObservedValue: previousObserved,
+            crossingDirection,
+        }),
+    });
+}
+export class TmwScheduler {
+    #suspensions = new Map();
+    #cursor = null;
+    constructor(snapshot) {
+        if (snapshot === undefined)
+            return;
+        const canonical = canonicalSchedulerSnapshot(snapshot);
+        this.#cursor = canonical.cursor ?? null;
+        for (const suspension of canonical.suspensions) {
+            this.#suspensions.set(suspension.suspensionId, suspension);
+        }
+    }
+    schedule(input) {
+        const suspension = canonicalSuspension(input);
+        const existing = this.#suspensions.get(suspension.suspensionId);
+        if (existing !== undefined) {
+            if (JSON.stringify(existing) !== JSON.stringify(suspension)) {
+                throw new Error("tmw_scheduler_suspension_identity_conflict");
+            }
+            return existing;
+        }
+        this.#suspensions.set(suspension.suspensionId, suspension);
+        return suspension;
+    }
+    cancel(cancellationKey) {
+        const key = requireTmwIdentifier(cancellationKey, "scheduler_cancellation_key");
+        const cancelled = [];
+        for (const [id, suspension] of this.#suspensions) {
+            if (suspension.cancellationKey !== key)
+                continue;
+            this.#suspensions.delete(id);
+            cancelled.push(suspension);
+        }
+        return Object.freeze(cancelled.sort((left, right) => left.suspensionId < right.suspensionId ? -1 : left.suspensionId > right.suspensionId ? 1 : 0));
+    }
+    poll(coordinates, crossingDirection) {
+        return Object.freeze([...this.#suspensions.values()]
+            .sort((left, right) => left.effectiveTime.due_value - right.effectiveTime.due_value
+            || (left.suspensionId < right.suspensionId ? -1 : 1))
+            .map((suspension) => evaluateSuspensionDue(suspension, coordinates, crossingDirection, this.#cursor)));
+    }
+    /** Advances only from caller-provided coordinates; it never samples a host clock. */
+    advance(coordinatesInput, crossingDirection) {
+        const coordinates = mergeSchedulerCoordinates(this.#cursor, coordinatesInput, crossingDirection);
+        const receipts = this.poll(coordinates, crossingDirection);
+        this.#cursor = coordinates;
+        return receipts;
+    }
+    consumeDue(suspensionId) {
+        const id = requireTmwIdentifier(suspensionId, "scheduler_suspension_id");
+        const suspension = this.#suspensions.get(id);
+        if (suspension === undefined)
+            throw new Error("tmw_scheduler_suspension_missing");
+        this.#suspensions.delete(id);
+        return suspension;
+    }
+    snapshot() {
+        return Object.freeze({
+            cursor: this.#cursor,
+            suspensions: Object.freeze([...this.#suspensions.values()].sort((left, right) => left.suspensionId < right.suspensionId ? -1 : left.suspensionId > right.suspensionId ? 1 : 0)),
+        });
+    }
+}

package/dist/selector-ast.d.ts

@@ -0,0 +1,24 @@
+import type { TmwJsonPrimitive } from "./runtime-contract.js";
+export type SelectorComparisonOperator = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "contains";
+export type SelectorAstV3 = {
+    readonly op: "entity_id";
+    readonly entity_id: string;
+} | {
+    readonly op: "entity_kind";
+    readonly entity_kind: string;
+} | {
+    readonly op: "attribute";
+    readonly source: SelectorAstV3;
+    readonly path: readonly string[];
+    readonly comparison: SelectorComparisonOperator;
+    readonly value: TmwJsonPrimitive;
+} | {
+    readonly op: "union" | "intersection";
+    readonly selectors: readonly SelectorAstV3[];
+} | {
+    readonly op: "difference";
+    readonly left: SelectorAstV3;
+    readonly right: SelectorAstV3;
+};
+export declare const SELECTOR_AST_V3_OPS: readonly ["entity_id", "entity_kind", "attribute", "union", "intersection", "difference"];
+export declare function selectorAstStableIdentity(selector: SelectorAstV3): string;

package/dist/selector-ast.js

@@ -0,0 +1,18 @@
+export const SELECTOR_AST_V3_OPS = Object.freeze([
+    "entity_id",
+    "entity_kind",
+    "attribute",
+    "union",
+    "intersection",
+    "difference",
+]);
+export function selectorAstStableIdentity(selector) {
+    switch (selector.op) {
+        case "entity_id": return `entity_id:${selector.entity_id}`;
+        case "entity_kind": return `entity_kind:${selector.entity_kind}`;
+        case "attribute": return `attribute:${selectorAstStableIdentity(selector.source)}:${selector.path.join(".")}:${selector.comparison}:${JSON.stringify(selector.value)}`;
+        case "union":
+        case "intersection": return `${selector.op}:${selector.selectors.map(selectorAstStableIdentity).sort().join("|")}`;
+        case "difference": return `difference:${selectorAstStableIdentity(selector.left)}:${selectorAstStableIdentity(selector.right)}`;
+    }
+}

package/dist/semantic-verdict.d.ts

@@ -0,0 +1,48 @@
+import { TMW_RUNTIME_GENERATION } from "./runtime-contract.js";
+export type SemanticTruth = "true" | "false" | "unknown";
+export type SemanticVerdictState = "pending" | "accepted" | "rejected" | "failed";
+export interface SemanticVerdictV3 {
+    readonly schemaVersion: 3;
+    readonly epoch: number;
+    readonly runtimeGeneration: typeof TMW_RUNTIME_GENERATION;
+    readonly runtimeContractHash: string;
+    readonly artifactDigest: string;
+    readonly scenarioId: string;
+    readonly sourceRevision: string;
+    readonly timelineRevision: string;
+    readonly turnId: string;
+    readonly operationId: string;
+    readonly intentId: string;
+    readonly idempotencyKey: string;
+    readonly evidenceSetDigest: string;
+    readonly budgetReceiptDigest: string;
+    readonly state: SemanticVerdictState;
+    readonly truth: SemanticTruth;
+    readonly confidenceMillionths: number;
+    readonly reasonCode: string;
+    readonly providerOperationId: string;
+    readonly providerReceiptDigest: string;
+    readonly verdictDigest: string;
+}
+export interface SemanticVerdictStore {
+    read(idempotencyKey: string): Promise<SemanticVerdictV3 | null>;
+    putIfAbsent(verdict: SemanticVerdictV3): Promise<Readonly<{
+        status: "stored" | "exists";
+        verdict: SemanticVerdictV3;
+    }>>;
+}
+export declare function parseSemanticVerdict(value: unknown): SemanticVerdictV3;
+export declare function storeSemanticVerdict(candidateInput: unknown, expected: Readonly<{
+    epoch: number;
+    runtimeContractHash: string;
+    artifactDigest: string;
+    scenarioId: string;
+    sourceRevision: string;
+    timelineRevision: string;
+    turnId: string;
+    operationId: string;
+    intentId: string;
+    idempotencyKey: string;
+    evidenceSetDigest: string;
+    budgetReceiptDigest: string;
+}>, store: SemanticVerdictStore): Promise<SemanticVerdictV3>;

package/dist/semantic-verdict.js

@@ -0,0 +1,101 @@
+import { TMW_RUNTIME_GENERATION } from "./runtime-contract.js";
+import { canonicalTmwJson, requireTmwIdentifier, requireTmwSafeInteger, requireTmwSha256, tmwSha256Hex, } from "./runtime-trace.js";
+const VERDICT_KEYS = [
+    "artifactDigest",
+    "budgetReceiptDigest",
+    "confidenceMillionths",
+    "epoch",
+    "evidenceSetDigest",
+    "idempotencyKey",
+    "intentId",
+    "operationId",
+    "providerOperationId",
+    "providerReceiptDigest",
+    "reasonCode",
+    "runtimeContractHash",
+    "runtimeGeneration",
+    "scenarioId",
+    "schemaVersion",
+    "sourceRevision",
+    "state",
+    "timelineRevision",
+    "truth",
+    "turnId",
+    "verdictDigest",
+];
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function parseSemanticVerdict(value) {
+    if (!isRecord(value))
+        throw new Error("tmw_semantic_verdict_object_required");
+    if (Object.keys(value).sort().join("\0") !== [...VERDICT_KEYS].sort().join("\0")) {
+        throw new Error("tmw_semantic_verdict_exact_keys_invalid");
+    }
+    if (value.schemaVersion !== 3 || value.runtimeGeneration !== 3) {
+        throw new Error("unsupported_runtime_generation");
+    }
+    if (value.state !== "pending" && value.state !== "accepted"
+        && value.state !== "rejected" && value.state !== "failed") {
+        throw new Error("tmw_semantic_verdict_state_invalid");
+    }
+    if (value.truth !== "true" && value.truth !== "false" && value.truth !== "unknown") {
+        throw new Error("tmw_semantic_verdict_truth_invalid");
+    }
+    const confidenceMillionths = requireTmwSafeInteger(value.confidenceMillionths, "semantic_confidence");
+    if (confidenceMillionths > 1_000_000)
+        throw new Error("tmw_semantic_confidence_invalid");
+    return Object.freeze({
+        schemaVersion: 3,
+        epoch: requireTmwSafeInteger(value.epoch, "semantic_epoch", 1),
+        runtimeGeneration: TMW_RUNTIME_GENERATION,
+        runtimeContractHash: requireTmwSha256(value.runtimeContractHash, "semantic_contract_hash"),
+        artifactDigest: requireTmwSha256(value.artifactDigest, "semantic_artifact_digest"),
+        scenarioId: requireTmwIdentifier(value.scenarioId, "semantic_scenario_id"),
+        sourceRevision: requireTmwIdentifier(value.sourceRevision, "semantic_source_revision"),
+        timelineRevision: requireTmwIdentifier(value.timelineRevision, "semantic_timeline_revision"),
+        turnId: requireTmwIdentifier(value.turnId, "semantic_turn_id"),
+        operationId: requireTmwIdentifier(value.operationId, "semantic_operation_id"),
+        intentId: requireTmwIdentifier(value.intentId, "semantic_intent_id"),
+        idempotencyKey: requireTmwIdentifier(value.idempotencyKey, "semantic_idempotency_key"),
+        evidenceSetDigest: requireTmwSha256(value.evidenceSetDigest, "semantic_evidence_digest"),
+        budgetReceiptDigest: requireTmwSha256(value.budgetReceiptDigest, "semantic_budget_digest"),
+        state: value.state,
+        truth: value.truth,
+        confidenceMillionths,
+        reasonCode: requireTmwIdentifier(value.reasonCode, "semantic_reason_code"),
+        providerOperationId: requireTmwIdentifier(value.providerOperationId, "semantic_provider_operation_id"),
+        providerReceiptDigest: requireTmwSha256(value.providerReceiptDigest, "semantic_provider_receipt_digest"),
+        verdictDigest: requireTmwSha256(value.verdictDigest, "semantic_verdict_digest"),
+    });
+}
+export async function storeSemanticVerdict(candidateInput, expected, store) {
+    const candidate = parseSemanticVerdict(candidateInput);
+    const { verdictDigest: _claimedDigest, ...digestImage } = candidate;
+    const computedDigest = await tmwSha256Hex(canonicalTmwJson(digestImage));
+    if (computedDigest !== candidate.verdictDigest) {
+        throw new Error("tmw_semantic_verdict_digest_mismatch");
+    }
+    for (const [label, actual, wanted] of [
+        ["epoch", candidate.epoch, expected.epoch],
+        ["contract", candidate.runtimeContractHash, expected.runtimeContractHash],
+        ["artifact", candidate.artifactDigest, expected.artifactDigest],
+        ["scenario", candidate.scenarioId, expected.scenarioId],
+        ["source", candidate.sourceRevision, expected.sourceRevision],
+        ["timeline", candidate.timelineRevision, expected.timelineRevision],
+        ["turn", candidate.turnId, expected.turnId],
+        ["operation", candidate.operationId, expected.operationId],
+        ["intent", candidate.intentId, expected.intentId],
+        ["idempotency", candidate.idempotencyKey, expected.idempotencyKey],
+        ["evidence", candidate.evidenceSetDigest, expected.evidenceSetDigest],
+        ["budget", candidate.budgetReceiptDigest, expected.budgetReceiptDigest],
+    ]) {
+        if (actual !== wanted)
+            throw new Error(`tmw_semantic_${label}_mismatch`);
+    }
+    const outcome = await store.putIfAbsent(candidate);
+    if (outcome.verdict.verdictDigest !== candidate.verdictDigest) {
+        throw new Error("tmw_semantic_verdict_identity_conflict");
+    }
+    return outcome.verdict;
+}

package/dist/simulator.d.ts

@@ -0,0 +1,45 @@
+import type { CanonicalTmwCapabilityRegistryV3 } from "./capability-registry.js";
+import type { TmwDiagnostic } from "./diagnostics.js";
+import type { TmwJsonValue } from "./runtime-contract.js";
+import type { TriggerDocumentV3 } from "./trigger-document-v3.js";
+import type { EffectExecutionPolicy, EffectRewritePolicy } from "./effect-flow.js";
+import type { CrossingPolicy, RealTimeClock, TmwClockDomain, WallClockPolicy } from "./time-domains.js";
+import { type ConditionEvaluationResult } from "./condition-graph.js";
+import type { TmwValueContextV1 } from "./value-graph.js";
+export interface SimulateTmw3Options {
+    readonly max_steps?: number;
+    readonly max_trace_entries?: number;
+    readonly event_payload?: Readonly<Record<string, TmwJsonValue>>;
+    readonly value_context?: TmwValueContextV1;
+}
+export interface TmwSimulationTraceEntry {
+    readonly step: number;
+    readonly stable_id: string;
+    readonly kind: "event" | "condition" | "effect" | "presentation";
+    readonly clock_domain: TmwClockDomain;
+    readonly due_value: number;
+    readonly effective_value: number;
+    readonly crossing_policy: CrossingPolicy;
+    readonly real_time_clock: RealTimeClock | null;
+    readonly wall_clock_policy: WallClockPolicy | null;
+    readonly execution_policy: EffectExecutionPolicy | null;
+    readonly rewrite_policy: EffectRewritePolicy | null;
+    readonly priority: number | null;
+    readonly idempotency_key: string | null;
+    readonly read_set: readonly string[];
+    readonly disposition: "evaluated" | "planned";
+    readonly condition_result: ConditionEvaluationResult | null;
+}
+export interface TmwSimulationResult {
+    readonly ok: true;
+    readonly plan_sha256: string;
+    readonly trace: readonly TmwSimulationTraceEntry[];
+    readonly steps_used: number;
+    readonly side_effect_receipts: readonly never[];
+    readonly diagnostics: readonly TmwDiagnostic[];
+}
+export type SimulateTmw3Outcome = TmwSimulationResult | {
+    readonly ok: false;
+    readonly diagnostics: readonly TmwDiagnostic[];
+};
+export declare function simulateTmw3(document: TriggerDocumentV3 | unknown, registry: CanonicalTmwCapabilityRegistryV3, options?: SimulateTmw3Options): Promise<SimulateTmw3Outcome>;

package/dist/simulator.js

@@ -0,0 +1,58 @@
+import { compileTmw3 } from "./compiler.js";
+import { evaluateConditionGraph } from "./condition-graph.js";
+import { buildTmwConditionExpressionSnapshotV3 } from "./runtime.js";
+export async function simulateTmw3(document, registry, options = {}) {
+    const compiled = await compileTmw3(document, registry, { runtime_target: "simulation" });
+    if (!compiled.ok)
+        return compiled;
+    const maxSteps = options.max_steps ?? 10_000;
+    const maxTrace = options.max_trace_entries ?? 1_000;
+    if (!Number.isSafeInteger(maxSteps) || maxSteps < 1 || !Number.isSafeInteger(maxTrace) || maxTrace < 1)
+        throw new Error("simulation_budget_invalid");
+    const trace = [];
+    let step = 0;
+    for (const node of compiled.plan.nodes) {
+        step += 1;
+        if (step > maxSteps)
+            throw new Error("simulation_step_budget_exceeded");
+        const conditionResult = node.kind !== "condition"
+            ? null
+            : (() => {
+                const payload = node.canonical_payload;
+                const snapshot = buildTmwConditionExpressionSnapshotV3(payload.expression, options.event_payload ?? Object.freeze({}), node.stable_id, new Set(), options.value_context ?? {}, compiled.plan.value_graph);
+                return evaluateConditionGraph(snapshot.graph, {
+                    snapshotHash: compiled.plan.document_sha256,
+                    values: snapshot.values,
+                    evidenceRefs: Object.freeze({}),
+                    frozenFacts: options.event_payload ?? Object.freeze({}),
+                });
+            })();
+        if (trace.length < maxTrace)
+            trace.push(Object.freeze({
+                step,
+                stable_id: node.stable_id,
+                kind: node.kind,
+                clock_domain: node.effective_time.domain,
+                due_value: node.effective_time.due_value,
+                effective_value: node.effective_time.effective_value,
+                crossing_policy: node.effective_time.crossing_policy,
+                real_time_clock: node.effective_time.real_time_clock,
+                wall_clock_policy: node.effective_time.wall_clock_policy,
+                execution_policy: node.kind === "effect" ? node.execution_policy : null,
+                rewrite_policy: node.kind === "effect" ? node.rewrite_policy : null,
+                priority: node.kind === "effect" ? node.priority : null,
+                idempotency_key: node.kind === "effect" ? node.idempotency_key : null,
+                read_set: node.dependencies,
+                disposition: node.kind === "effect" || node.kind === "presentation" ? "planned" : "evaluated",
+                condition_result: conditionResult,
+            }));
+    }
+    return Object.freeze({
+        ok: true,
+        plan_sha256: compiled.plan.plan_sha256,
+        trace: Object.freeze(trace),
+        steps_used: step,
+        side_effect_receipts: Object.freeze([]),
+        diagnostics: compiled.diagnostics,
+    });
+}

package/dist/source-canonical.d.ts

@@ -0,0 +1,4 @@
+import type { AuthenticatedCreateNewSourceInput, AuthorScenarioSourceV3 } from "./author-scenario-source-v3.js";
+export declare function createCanonicalEmptyAuthorScenarioSourceV3(input: AuthenticatedCreateNewSourceInput): Promise<AuthorScenarioSourceV3>;
+export declare function canonicalAuthorScenarioSourceV3Bytes(source: AuthorScenarioSourceV3): Uint8Array;
+export declare function authorScenarioSourceV3Digest(source: AuthorScenarioSourceV3): Promise<string>;

package/dist/source-canonical.js

@@ -0,0 +1,51 @@
+import { canonicalTmwBytes, runtimeContractHashV3, tmwSha256Hex, TMW_RUNTIME_GENERATION, TRIGGER_DOCUMENT_V3_VERSION, AUTHOR_SCENARIO_SOURCE_V3_SCHEMA_VERSION } from "./runtime-contract.js";
+function canonicalId(value, code) {
+    if (value.length === 0 || value.trim() !== value || value.normalize("NFC") !== value)
+        throw new Error(code);
+    return value;
+}
+export async function createCanonicalEmptyAuthorScenarioSourceV3(input) {
+    if (input.operation !== "create-new")
+        throw new Error("source_create_new_required");
+    const ownerId = canonicalId(input.owner_id, "source_owner_invalid");
+    if (canonicalId(input.auth_principal_id, "source_principal_invalid") !== ownerId)
+        throw new Error("source_owner_forbidden");
+    const scenarioId = canonicalId(input.scenario_id, "source_scenario_invalid");
+    const registryVersion = canonicalId(input.registry_version, "source_registry_version_invalid");
+    if (!Number.isSafeInteger(input.epoch) || input.epoch < 1)
+        throw new Error("content_epoch_required");
+    return Object.freeze({
+        schema_version: AUTHOR_SCENARIO_SOURCE_V3_SCHEMA_VERSION,
+        runtime_generation: TMW_RUNTIME_GENERATION,
+        owner_id: ownerId,
+        scenario_id: scenarioId,
+        epoch: input.epoch,
+        source_revision: 1,
+        previous_revision_digest: null,
+        trigger_document: Object.freeze({
+            version: TRIGGER_DOCUMENT_V3_VERSION,
+            runtime_generation: TMW_RUNTIME_GENERATION,
+            runtime_contract_hash: await runtimeContractHashV3(),
+            registry_version: registryVersion,
+            events: Object.freeze([]),
+            conditions: Object.freeze([]),
+            effects: Object.freeze([]),
+            presentations: Object.freeze([]),
+            edges: Object.freeze([]),
+        }),
+        view_interaction_mobile: null,
+        view_interaction_pc: null,
+        music_candidate_source: Object.freeze({
+            schema: "music-candidate-source.v3",
+            generation: TMW_RUNTIME_GENERATION,
+            candidates: Object.freeze([]),
+        }),
+        source_metadata: Object.freeze({}),
+    });
+}
+export function canonicalAuthorScenarioSourceV3Bytes(source) {
+    return canonicalTmwBytes(source);
+}
+export async function authorScenarioSourceV3Digest(source) {
+    return tmwSha256Hex(canonicalAuthorScenarioSourceV3Bytes(source));
+}