@world-engines/tmw 0.1.0-alpha.0

package/dist/source-crypto.d.ts

@@ -0,0 +1,20 @@
+export interface AuthorSourceCryptoPort {
+    encrypt(plaintext: Uint8Array): Promise<Readonly<{
+        algorithm: string;
+        key_id: string;
+        ciphertext: Uint8Array;
+    }>>;
+    decrypt(input: Readonly<{
+        algorithm: string;
+        key_id: string;
+        ciphertext: Uint8Array;
+    }>): Promise<Uint8Array>;
+}
+export interface EncryptedAuthorSourcePayloadV3 {
+    readonly algorithm: string;
+    readonly key_id: string;
+    readonly ciphertext: Uint8Array;
+    readonly ciphertext_sha256: string;
+}
+export declare function encryptAuthorSourcePayloadV3(plaintext: Uint8Array, cryptoPort: AuthorSourceCryptoPort): Promise<EncryptedAuthorSourcePayloadV3>;
+export declare function decryptAuthorSourcePayloadV3(payload: EncryptedAuthorSourcePayloadV3, cryptoPort: AuthorSourceCryptoPort): Promise<Uint8Array>;

package/dist/source-crypto.js

@@ -0,0 +1,17 @@
+import { tmwSha256Hex } from "./runtime-contract.js";
+export async function encryptAuthorSourcePayloadV3(plaintext, cryptoPort) {
+    const encrypted = await cryptoPort.encrypt(plaintext.slice());
+    if (encrypted.algorithm.length === 0 || encrypted.key_id.length === 0 || encrypted.ciphertext.length === 0)
+        throw new Error("source_encryption_invalid");
+    return Object.freeze({
+        algorithm: encrypted.algorithm,
+        key_id: encrypted.key_id,
+        ciphertext: encrypted.ciphertext.slice(),
+        ciphertext_sha256: await tmwSha256Hex(encrypted.ciphertext),
+    });
+}
+export async function decryptAuthorSourcePayloadV3(payload, cryptoPort) {
+    if (await tmwSha256Hex(payload.ciphertext) !== payload.ciphertext_sha256)
+        throw new Error("source_ciphertext_hash_mismatch");
+    return cryptoPort.decrypt({ algorithm: payload.algorithm, key_id: payload.key_id, ciphertext: payload.ciphertext.slice() });
+}

package/dist/source-revision.d.ts

@@ -0,0 +1,22 @@
+import type { AuthorScenarioSourceV3, AuthorSourceIdentityV3 } from "./author-scenario-source-v3.js";
+import { type AuthorSourceCryptoPort, type EncryptedAuthorSourcePayloadV3 } from "./source-crypto.js";
+export interface EncryptedAuthorSourceRevisionV3 extends AuthorSourceIdentityV3, EncryptedAuthorSourcePayloadV3 {
+    readonly revision_schema_version: 3;
+    readonly previous_head_digest: string | null;
+    readonly revision_digest: string;
+}
+export interface AuthorSourceReadbackReceiptV3 extends AuthorSourceIdentityV3 {
+    readonly revision_digest: string;
+    readonly ciphertext_sha256: string;
+    readonly head_digest: string;
+}
+export declare function buildEncryptedAuthorSourceRevisionV3(source: AuthorScenarioSourceV3, previousHeadDigest: string | null, cryptoPort: AuthorSourceCryptoPort): Promise<EncryptedAuthorSourceRevisionV3>;
+export declare function readbackAuthorSourceRevisionV3(revision: EncryptedAuthorSourceRevisionV3, expected: Readonly<{
+    owner_id: string;
+    scenario_id: string;
+    epoch: number;
+    head_digest: string;
+}>, cryptoPort: AuthorSourceCryptoPort): Promise<Readonly<{
+    source: AuthorScenarioSourceV3;
+    receipt: AuthorSourceReadbackReceiptV3;
+}>>;

package/dist/source-revision.js

@@ -0,0 +1,43 @@
+import { authorScenarioSourceV3Digest, canonicalAuthorScenarioSourceV3Bytes } from "./source-canonical.js";
+import { decryptAuthorSourcePayloadV3, encryptAuthorSourcePayloadV3 } from "./source-crypto.js";
+export async function buildEncryptedAuthorSourceRevisionV3(source, previousHeadDigest, cryptoPort) {
+    const sourceSha256 = await authorScenarioSourceV3Digest(source);
+    const payload = await encryptAuthorSourcePayloadV3(canonicalAuthorScenarioSourceV3Bytes(source), cryptoPort);
+    const revisionDigest = await authorScenarioSourceV3Digest(Object.freeze({ ...source, previous_revision_digest: previousHeadDigest }));
+    return Object.freeze({
+        revision_schema_version: 3,
+        owner_id: source.owner_id,
+        scenario_id: source.scenario_id,
+        epoch: source.epoch,
+        source_revision: source.source_revision,
+        source_sha256: sourceSha256,
+        previous_head_digest: previousHeadDigest,
+        revision_digest: revisionDigest,
+        ...payload,
+    });
+}
+export async function readbackAuthorSourceRevisionV3(revision, expected, cryptoPort) {
+    if (revision.owner_id !== expected.owner_id || revision.scenario_id !== expected.scenario_id)
+        throw new Error("source_identity_mismatch");
+    if (revision.epoch !== expected.epoch)
+        throw new Error("stale_content_epoch");
+    const plaintext = await decryptAuthorSourcePayloadV3(revision, cryptoPort);
+    const source = JSON.parse(new TextDecoder().decode(plaintext));
+    if (await authorScenarioSourceV3Digest(source) !== revision.source_sha256)
+        throw new Error("source_hash_mismatch");
+    if (source.owner_id !== revision.owner_id || source.scenario_id !== revision.scenario_id || source.epoch !== revision.epoch || source.source_revision !== revision.source_revision)
+        throw new Error("source_revision_identity_mismatch");
+    return Object.freeze({
+        source,
+        receipt: Object.freeze({
+            owner_id: revision.owner_id,
+            scenario_id: revision.scenario_id,
+            epoch: revision.epoch,
+            source_revision: revision.source_revision,
+            source_sha256: revision.source_sha256,
+            revision_digest: revision.revision_digest,
+            ciphertext_sha256: revision.ciphertext_sha256,
+            head_digest: expected.head_digest,
+        }),
+    });
+}

package/dist/spatial-impact-receipt.d.ts

@@ -0,0 +1,38 @@
+export declare const SPATIAL_IMPACT_RECEIPT_VERSION: 1;
+export type SpatialImpactMetricV1 = "straight_line" | "reachable";
+export interface SpatialImpactPoseV1 {
+    readonly subjectId: string;
+    readonly spatialId: string;
+    readonly frameId: string;
+    readonly xMeters: number;
+    readonly yMeters: number;
+    readonly elevationMeters: number;
+    readonly revision: number;
+}
+export interface SpatialImpactReceiptV1 {
+    readonly version: typeof SPATIAL_IMPACT_RECEIPT_VERSION;
+    readonly eventId: string;
+    readonly mapRevision: string;
+    readonly selectorId: string;
+    readonly metric: SpatialImpactMetricV1;
+    readonly distanceMeters: number | null;
+    readonly poses: ReadonlyArray<SpatialImpactPoseV1>;
+    readonly affectedIds: ReadonlyArray<string>;
+    readonly digest: string;
+}
+export interface FreezeSpatialImpactInputV1 {
+    readonly eventId: string;
+    readonly mapRevision: string;
+    readonly selectorId: string;
+    readonly metric: SpatialImpactMetricV1;
+    readonly distanceMeters?: number;
+    readonly poses: ReadonlyArray<SpatialImpactPoseV1>;
+    readonly affectedIds: ReadonlyArray<string>;
+}
+/**
+ * Freezes spatial inputs before an effect executes. Replay accepts this receipt
+ * as the authority and therefore never re-queries live poses or map state.
+ */
+export declare function freezeSpatialImpactReceiptV1(input: FreezeSpatialImpactInputV1): Promise<SpatialImpactReceiptV1>;
+/** Fails closed when journal/debug/player readback data was modified in transit. */
+export declare function verifySpatialImpactReceiptV1(receipt: SpatialImpactReceiptV1): Promise<boolean>;

package/dist/spatial-impact-receipt.js

@@ -0,0 +1,67 @@
+import { canonicalTmwJson, requireTmwIdentifier, requireTmwSafeInteger, requireTmwSha256, tmwSha256Hex, } from "./runtime-trace.js";
+export const SPATIAL_IMPACT_RECEIPT_VERSION = 1;
+function finite(value, label, minimum = Number.NEGATIVE_INFINITY) {
+    if (!Number.isFinite(value) || value < minimum) {
+        throw new Error(`spatial_impact_${label}_invalid`);
+    }
+    return Object.is(value, -0) ? 0 : value;
+}
+function canonicalPose(pose) {
+    return Object.freeze({
+        subjectId: requireTmwIdentifier(pose.subjectId, "spatial_impact_pose_subject"),
+        spatialId: requireTmwIdentifier(pose.spatialId, "spatial_impact_pose_spatial"),
+        frameId: requireTmwIdentifier(pose.frameId, "spatial_impact_pose_frame"),
+        xMeters: finite(pose.xMeters, "pose_x"),
+        yMeters: finite(pose.yMeters, "pose_y"),
+        elevationMeters: finite(pose.elevationMeters, "pose_elevation"),
+        revision: requireTmwSafeInteger(pose.revision, "spatial_impact_pose_revision"),
+    });
+}
+function canonicalPoses(poses) {
+    const bySubject = new Map();
+    for (const pose of poses) {
+        const next = canonicalPose(pose);
+        const existing = bySubject.get(next.subjectId);
+        if (existing !== undefined && canonicalTmwJson(existing) !== canonicalTmwJson(next)) {
+            throw new Error("spatial_impact_pose_subject_conflict");
+        }
+        bySubject.set(next.subjectId, next);
+    }
+    return Object.freeze([...bySubject.values()].sort((left, right) => left.subjectId.localeCompare(right.subjectId)));
+}
+function canonicalAffectedIds(ids) {
+    return Object.freeze([...new Set(ids.map((id) => requireTmwIdentifier(id, "spatial_impact_affected_id")))].sort());
+}
+/**
+ * Freezes spatial inputs before an effect executes. Replay accepts this receipt
+ * as the authority and therefore never re-queries live poses or map state.
+ */
+export async function freezeSpatialImpactReceiptV1(input) {
+    const distanceMeters = input.distanceMeters === undefined
+        ? null
+        : finite(input.distanceMeters, "distance_meters", 0);
+    const unsigned = Object.freeze({
+        version: SPATIAL_IMPACT_RECEIPT_VERSION,
+        eventId: requireTmwIdentifier(input.eventId, "spatial_impact_event"),
+        mapRevision: requireTmwIdentifier(input.mapRevision, "spatial_impact_map_revision"),
+        selectorId: requireTmwIdentifier(input.selectorId, "spatial_impact_selector"),
+        metric: input.metric,
+        distanceMeters,
+        poses: canonicalPoses(input.poses),
+        affectedIds: canonicalAffectedIds(input.affectedIds),
+    });
+    if (unsigned.metric !== "straight_line" && unsigned.metric !== "reachable") {
+        throw new Error("spatial_impact_metric_invalid");
+    }
+    const digest = await tmwSha256Hex(canonicalTmwJson(unsigned));
+    return Object.freeze({ ...unsigned, digest });
+}
+/** Fails closed when journal/debug/player readback data was modified in transit. */
+export async function verifySpatialImpactReceiptV1(receipt) {
+    const { digest: _digest, distanceMeters, ...frozen } = receipt;
+    const rebuilt = await freezeSpatialImpactReceiptV1({
+        ...frozen,
+        ...(distanceMeters === null ? {} : { distanceMeters }),
+    });
+    return requireTmwSha256(receipt.digest, "spatial_impact_digest") === rebuilt.digest;
+}

package/dist/temporal-rewrite.d.ts

@@ -0,0 +1,59 @@
+import { TMW_RUNTIME_GENERATION } from "./runtime-contract.js";
+import { type TmwJsonValue } from "./runtime-trace.js";
+export interface TemporalRewriteInterval {
+    readonly fromWorldTime: number;
+    readonly toWorldTime: number;
+    readonly targetWorldTime: number;
+}
+export interface TemporalRewriteEventV3 {
+    readonly eventId: string;
+    readonly eventType: string;
+    readonly effectiveWorldTime: number;
+    readonly capabilityIds: ReadonlyArray<string>;
+    readonly payload: TmwJsonValue;
+    readonly payloadHash: string;
+    readonly replacementOf: ReadonlyArray<string>;
+}
+export interface TemporalRewriteCompensationProposalV3 {
+    readonly externalEffectId: string;
+    readonly policy: "retain_fact" | "project_only" | "requires_confirmation";
+    readonly reasonCode: string;
+}
+export interface TemporalRewriteDraftV3 {
+    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 idempotencyKey: string;
+    readonly interval: TemporalRewriteInterval;
+    readonly narrative: TmwJsonValue;
+    readonly narrativeDigest: string;
+    readonly events: ReadonlyArray<TemporalRewriteEventV3>;
+    readonly replacedEventIds: ReadonlyArray<string>;
+    readonly conflictCodes: ReadonlyArray<string>;
+    readonly evidenceRefs: ReadonlyArray<string>;
+    readonly compensationProposals: ReadonlyArray<TemporalRewriteCompensationProposalV3>;
+    readonly draftDigest: string;
+}
+export declare function canonicalTemporalRewriteEvent(value: unknown): TemporalRewriteEventV3;
+export declare function verifyTemporalRewriteEvent(value: unknown): Promise<TemporalRewriteEventV3>;
+export declare function parseTemporalRewriteDraft(value: unknown): TemporalRewriteDraftV3;
+export declare function verifyTemporalRewriteDraft(value: unknown): Promise<TemporalRewriteDraftV3>;
+export declare function assertTemporalRewriteBinding(draftInput: unknown, expected: Readonly<{
+    epoch: number;
+    runtimeContractHash: string;
+    artifactDigest: string;
+    scenarioId: string;
+    sourceRevision: string;
+    timelineRevision: string;
+    turnId: string;
+    operationId: string;
+    idempotencyKey: string;
+    interval: TemporalRewriteInterval;
+}>): Promise<TemporalRewriteDraftV3>;

package/dist/temporal-rewrite.js

@@ -0,0 +1,214 @@
+import { TMW_RUNTIME_GENERATION } from "./runtime-contract.js";
+import { canonicalTmwJson, canonicalTmwJsonValue, requireTmwIdentifier, requireTmwSafeInteger, requireTmwSha256, tmwSha256Hex, } from "./runtime-trace.js";
+const DRAFT_KEYS = [
+    "artifactDigest",
+    "compensationProposals",
+    "conflictCodes",
+    "draftDigest",
+    "epoch",
+    "events",
+    "evidenceRefs",
+    "idempotencyKey",
+    "interval",
+    "narrative",
+    "narrativeDigest",
+    "operationId",
+    "replacedEventIds",
+    "runtimeContractHash",
+    "runtimeGeneration",
+    "scenarioId",
+    "schemaVersion",
+    "sourceRevision",
+    "timelineRevision",
+    "turnId",
+];
+function worldSecond(value, label) {
+    return requireTmwSafeInteger(value, `rewrite_${label}`);
+}
+function exactRecord(value, keys, label) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`tmw_rewrite_${label}_object_required`);
+    }
+    const record = value;
+    if (Object.keys(record).sort().join("\0") !== [...keys].sort().join("\0")) {
+        throw new Error(`tmw_rewrite_${label}_exact_keys_invalid`);
+    }
+    return record;
+}
+function identifierArray(value, label) {
+    if (!Array.isArray(value))
+        throw new Error(`tmw_rewrite_${label}_array_required`);
+    const result = value.map((item) => requireTmwIdentifier(item, `rewrite_${label}`));
+    if (new Set(result).size !== result.length)
+        throw new Error(`tmw_rewrite_${label}_duplicate`);
+    return Object.freeze([...result].sort());
+}
+export function canonicalTemporalRewriteEvent(value) {
+    const record = exactRecord(value, [
+        "capabilityIds",
+        "effectiveWorldTime",
+        "eventId",
+        "eventType",
+        "payload",
+        "payloadHash",
+        "replacementOf",
+    ], "event");
+    return Object.freeze({
+        eventId: requireTmwIdentifier(record.eventId, "rewrite_event_id"),
+        eventType: requireTmwIdentifier(record.eventType, "rewrite_event_type"),
+        effectiveWorldTime: worldSecond(record.effectiveWorldTime, "event_world_time"),
+        capabilityIds: identifierArray(record.capabilityIds, "capability_ids"),
+        payload: canonicalTmwJsonValue(record.payload, "rewrite_event_payload"),
+        payloadHash: requireTmwSha256(record.payloadHash, "rewrite_event_payload_hash"),
+        replacementOf: identifierArray(record.replacementOf, "replacement_of"),
+    });
+}
+export async function verifyTemporalRewriteEvent(value) {
+    const event = canonicalTemporalRewriteEvent(value);
+    const payloadHash = await tmwSha256Hex(canonicalTmwJson(event.payload));
+    if (payloadHash !== event.payloadHash) {
+        throw new Error("tmw_rewrite_event_payload_hash_mismatch");
+    }
+    return event;
+}
+function parseCompensation(value) {
+    const record = exactRecord(value, ["externalEffectId", "policy", "reasonCode"], "compensation");
+    if (record.policy !== "retain_fact"
+        && record.policy !== "project_only"
+        && record.policy !== "requires_confirmation") {
+        throw new Error("tmw_rewrite_compensation_policy_invalid");
+    }
+    return Object.freeze({
+        externalEffectId: requireTmwIdentifier(record.externalEffectId, "rewrite_external_effect_id"),
+        policy: record.policy,
+        reasonCode: requireTmwIdentifier(record.reasonCode, "rewrite_reason_code"),
+    });
+}
+export function parseTemporalRewriteDraft(value) {
+    const record = exactRecord(value, DRAFT_KEYS, "draft");
+    if (record.schemaVersion !== 3 || record.runtimeGeneration !== 3) {
+        throw new Error("unsupported_runtime_generation");
+    }
+    const interval = exactRecord(record.interval, ["fromWorldTime", "targetWorldTime", "toWorldTime"], "interval");
+    const canonicalInterval = Object.freeze({
+        fromWorldTime: worldSecond(interval.fromWorldTime, "from_world_time"),
+        toWorldTime: worldSecond(interval.toWorldTime, "to_world_time"),
+        targetWorldTime: worldSecond(interval.targetWorldTime, "target_world_time"),
+    });
+    if (canonicalInterval.fromWorldTime > canonicalInterval.targetWorldTime
+        || canonicalInterval.targetWorldTime > canonicalInterval.toWorldTime) {
+        throw new Error("tmw_rewrite_interval_invalid");
+    }
+    if (!Array.isArray(record.events) || !Array.isArray(record.compensationProposals)) {
+        throw new Error("tmw_rewrite_collections_invalid");
+    }
+    const events = record.events.map(canonicalTemporalRewriteEvent);
+    const eventIds = events.map((event) => event.eventId);
+    if (new Set(eventIds).size !== eventIds.length)
+        throw new Error("tmw_rewrite_event_id_duplicate");
+    events.sort((left, right) => left.effectiveWorldTime - right.effectiveWorldTime
+        || (left.eventId < right.eventId ? -1 : 1));
+    for (const event of events) {
+        if (event.effectiveWorldTime < canonicalInterval.fromWorldTime
+            || event.effectiveWorldTime > canonicalInterval.targetWorldTime) {
+            throw new Error("tmw_rewrite_event_outside_target_interval");
+        }
+    }
+    const replacedEventIds = identifierArray(record.replacedEventIds, "replaced_event_ids");
+    const replacementClaims = events.flatMap((event) => event.replacementOf);
+    if (new Set(replacementClaims).size !== replacementClaims.length) {
+        throw new Error("tmw_rewrite_replacement_source_duplicate");
+    }
+    const canonicalClaims = [...replacementClaims].sort();
+    if (canonicalClaims.length !== replacedEventIds.length
+        || canonicalClaims.some((eventId, index) => eventId !== replacedEventIds[index])) {
+        throw new Error("tmw_rewrite_replaced_event_set_mismatch");
+    }
+    if (eventIds.some((eventId) => replacedEventIds.includes(eventId))) {
+        throw new Error("tmw_rewrite_source_replacement_event_id_collision");
+    }
+    const compensationProposals = record.compensationProposals.map(parseCompensation);
+    const compensationIds = compensationProposals.map((proposal) => proposal.externalEffectId);
+    if (new Set(compensationIds).size !== compensationIds.length) {
+        throw new Error("tmw_rewrite_compensation_effect_duplicate");
+    }
+    compensationProposals.sort((left, right) => left.externalEffectId < right.externalEffectId
+        ? -1
+        : left.externalEffectId > right.externalEffectId
+            ? 1
+            : 0);
+    return Object.freeze({
+        schemaVersion: 3,
+        epoch: requireTmwSafeInteger(record.epoch, "rewrite_epoch", 1),
+        runtimeGeneration: TMW_RUNTIME_GENERATION,
+        runtimeContractHash: requireTmwSha256(record.runtimeContractHash, "rewrite_contract_hash"),
+        artifactDigest: requireTmwSha256(record.artifactDigest, "rewrite_artifact_digest"),
+        scenarioId: requireTmwIdentifier(record.scenarioId, "rewrite_scenario_id"),
+        sourceRevision: requireTmwIdentifier(record.sourceRevision, "rewrite_source_revision"),
+        timelineRevision: requireTmwIdentifier(record.timelineRevision, "rewrite_timeline_revision"),
+        turnId: requireTmwIdentifier(record.turnId, "rewrite_turn_id"),
+        operationId: requireTmwIdentifier(record.operationId, "rewrite_operation_id"),
+        idempotencyKey: requireTmwIdentifier(record.idempotencyKey, "rewrite_idempotency_key"),
+        interval: canonicalInterval,
+        narrative: canonicalTmwJsonValue(record.narrative, "rewrite_narrative"),
+        narrativeDigest: requireTmwSha256(record.narrativeDigest, "rewrite_narrative_digest"),
+        events: Object.freeze(events),
+        replacedEventIds,
+        conflictCodes: identifierArray(record.conflictCodes, "conflict_codes"),
+        evidenceRefs: identifierArray(record.evidenceRefs, "evidence_refs"),
+        compensationProposals: Object.freeze(compensationProposals),
+        draftDigest: requireTmwSha256(record.draftDigest, "rewrite_draft_digest"),
+    });
+}
+export async function verifyTemporalRewriteDraft(value) {
+    const draft = parseTemporalRewriteDraft(value);
+    const narrativeDigest = await tmwSha256Hex(canonicalTmwJson(draft.narrative));
+    if (narrativeDigest !== draft.narrativeDigest) {
+        throw new Error("tmw_rewrite_narrative_digest_mismatch");
+    }
+    for (const event of draft.events) {
+        await verifyTemporalRewriteEvent(event);
+    }
+    const { draftDigest: _claimedDigest, ...digestImage } = draft;
+    const computedDigest = await tmwSha256Hex(canonicalTmwJson(digestImage));
+    if (computedDigest !== draft.draftDigest)
+        throw new Error("tmw_rewrite_draft_digest_mismatch");
+    return draft;
+}
+export async function assertTemporalRewriteBinding(draftInput, expected) {
+    const draft = await verifyTemporalRewriteDraft(draftInput);
+    for (const [label, actual, wanted] of [
+        ["epoch", draft.epoch, expected.epoch],
+        ["contract", draft.runtimeContractHash, expected.runtimeContractHash],
+        ["artifact", draft.artifactDigest, expected.artifactDigest],
+        ["scenario", draft.scenarioId, expected.scenarioId],
+        ["source", draft.sourceRevision, expected.sourceRevision],
+        ["timeline", draft.timelineRevision, expected.timelineRevision],
+        ["turn", draft.turnId, expected.turnId],
+        ["operation", draft.operationId, expected.operationId],
+        ["idempotency", draft.idempotencyKey, expected.idempotencyKey],
+    ]) {
+        if (actual !== wanted) {
+            if (label === "epoch")
+                throw new Error("stale_content_epoch");
+            if (label === "contract")
+                throw new Error("runtime_contract_hash_mismatch");
+            throw new Error(`tmw_rewrite_${label}_mismatch`);
+        }
+    }
+    const expectedInterval = Object.freeze({
+        fromWorldTime: worldSecond(expected.interval.fromWorldTime, "expected_from_world_time"),
+        toWorldTime: worldSecond(expected.interval.toWorldTime, "expected_to_world_time"),
+        targetWorldTime: worldSecond(expected.interval.targetWorldTime, "expected_target_world_time"),
+    });
+    if (expectedInterval.fromWorldTime > expectedInterval.targetWorldTime
+        || expectedInterval.targetWorldTime > expectedInterval.toWorldTime) {
+        throw new Error("tmw_rewrite_expected_interval_invalid");
+    }
+    if (draft.interval.fromWorldTime !== expectedInterval.fromWorldTime
+        || draft.interval.toWorldTime !== expectedInterval.toWorldTime
+        || draft.interval.targetWorldTime !== expectedInterval.targetWorldTime) {
+        throw new Error("tmw_rewrite_interval_mismatch");
+    }
+    return draft;
+}

package/dist/time-domains.d.ts

@@ -0,0 +1,37 @@
+export declare const TMW_CLOCK_DOMAINS: readonly ["logical_seq", "world_time", "presentation_seq", "real_time"];
+/** @deprecated Use TMW_CLOCK_DOMAINS. Kept as a source-compatible export name. */
+export declare const TMW_TIME_DOMAINS: readonly ["logical_seq", "world_time", "presentation_seq", "real_time"];
+export type TmwClockDomain = (typeof TMW_CLOCK_DOMAINS)[number];
+/** @deprecated Use TmwClockDomain. */
+export type TmwTimeDomain = TmwClockDomain;
+export type CrossingDirection = "forward" | "backward";
+export type CrossingPolicy = "forward_only" | "backward_only" | "both_directions";
+export type RealTimeClock = "monotonic_session" | "active_play" | "wall_clock";
+export type WallClockPolicy = "elapse_while_suspended" | "active_session_only" | "reject";
+/**
+ * A trigger node's kind is intentionally not encoded here. Effective time is a
+ * clock coordinate shared by event, condition, effect and presentation nodes.
+ */
+export interface TmwEffectiveTime<D extends TmwClockDomain = TmwClockDomain> {
+    readonly domain: D;
+    readonly due_value: number;
+    readonly effective_value: number;
+    readonly crossing_policy: CrossingPolicy;
+    readonly real_time_clock: D extends "real_time" ? RealTimeClock : null;
+    readonly wall_clock_policy: D extends "real_time" ? WallClockPolicy : null;
+}
+export type EventEffectiveTime = TmwEffectiveTime;
+export type ConditionEffectiveTime = TmwEffectiveTime;
+export type EffectEffectiveTime = TmwEffectiveTime;
+export type PresentationEffectiveTime = TmwEffectiveTime;
+export declare function canonicalTmwClockCoordinate(value: number, domain: TmwClockDomain): number;
+export declare function isTmwEffectiveTime<D extends TmwClockDomain = TmwClockDomain>(value: unknown, expectedDomain?: D): value is TmwEffectiveTime<D>;
+export declare function canonicalTmwEffectiveTime<D extends TmwClockDomain>(value: TmwEffectiveTime<D>, expectedDomain?: D): TmwEffectiveTime<D>;
+export declare function compareTmwEffectiveTime(left: TmwEffectiveTime, right: TmwEffectiveTime): number;
+export declare function crossingPolicyAllows(policy: CrossingPolicy, direction: CrossingDirection): boolean;
+/** Materializes an authored due coordinate against a host-observed clock value. */
+export declare function observeTmwEffectiveTime<D extends TmwClockDomain>(authored: TmwEffectiveTime<D>, observedValue: number): TmwEffectiveTime<D>;
+/** Point-in-time eligibility. Repeated delivery is handled by operation identity. */
+export declare function tmwEffectiveTimeIsDue(effectiveTimeInput: TmwEffectiveTime, observedValue: number, direction: CrossingDirection): boolean;
+/** Strict boundary crossing used by durable scheduler continuations. */
+export declare function tmwEffectiveTimeCrossedDue(effectiveTimeInput: TmwEffectiveTime, previousObservedValue: number, observedValue: number, direction: CrossingDirection): boolean;

package/dist/time-domains.js

@@ -0,0 +1,142 @@
+export const TMW_CLOCK_DOMAINS = Object.freeze([
+    "logical_seq",
+    "world_time",
+    "presentation_seq",
+    "real_time",
+]);
+/** @deprecated Use TMW_CLOCK_DOMAINS. Kept as a source-compatible export name. */
+export const TMW_TIME_DOMAINS = TMW_CLOCK_DOMAINS;
+const EFFECTIVE_TIME_KEYS = Object.freeze([
+    "crossing_policy",
+    "domain",
+    "due_value",
+    "effective_value",
+    "real_time_clock",
+    "wall_clock_policy",
+]);
+const DOMAIN_ORDER = Object.freeze({
+    logical_seq: 0,
+    world_time: 1,
+    presentation_seq: 2,
+    real_time: 3,
+});
+function exactKeys(value, keys) {
+    return Object.keys(value).sort().join("\0") === [...keys].sort().join("\0");
+}
+function isFiniteCoordinate(value) {
+    return typeof value === "number" && Number.isFinite(value) && !Object.is(value, -0);
+}
+export function canonicalTmwClockCoordinate(value, domain) {
+    if (!isFiniteCoordinate(value))
+        throw new Error("tmw_clock_coordinate_invalid");
+    if ((domain === "logical_seq" || domain === "presentation_seq")
+        && (!Number.isSafeInteger(value) || value < 0)) {
+        throw new Error("tmw_clock_coordinate_invalid");
+    }
+    return value;
+}
+function isClockDomain(value) {
+    return typeof value === "string"
+        && TMW_CLOCK_DOMAINS.includes(value);
+}
+function isCrossingPolicy(value) {
+    return value === "forward_only" || value === "backward_only" || value === "both_directions";
+}
+function isRealTimeClock(value) {
+    return value === "monotonic_session" || value === "active_play" || value === "wall_clock";
+}
+function isWallClockPolicy(value) {
+    return value === "elapse_while_suspended" || value === "active_session_only" || value === "reject";
+}
+export function isTmwEffectiveTime(value, expectedDomain) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const record = value;
+    if (!exactKeys(record, EFFECTIVE_TIME_KEYS)
+        || !isClockDomain(record.domain)
+        || (expectedDomain !== undefined && record.domain !== expectedDomain)
+        || !isFiniteCoordinate(record.due_value)
+        || !isFiniteCoordinate(record.effective_value)
+        || !isCrossingPolicy(record.crossing_policy)) {
+        return false;
+    }
+    if ((record.domain === "logical_seq" || record.domain === "presentation_seq")
+        && (!Number.isSafeInteger(record.due_value)
+            || record.due_value < 0
+            || !Number.isSafeInteger(record.effective_value)
+            || record.effective_value < 0)) {
+        return false;
+    }
+    if (record.domain !== "real_time") {
+        return record.real_time_clock === null && record.wall_clock_policy === null;
+    }
+    if (!isRealTimeClock(record.real_time_clock) || !isWallClockPolicy(record.wall_clock_policy)) {
+        return false;
+    }
+    return record.real_time_clock === "wall_clock"
+        || record.wall_clock_policy === "active_session_only";
+}
+export function canonicalTmwEffectiveTime(value, expectedDomain) {
+    if (!isTmwEffectiveTime(value, expectedDomain))
+        throw new Error("tmw_effective_time_invalid");
+    return Object.freeze({
+        domain: value.domain,
+        due_value: value.due_value,
+        effective_value: value.effective_value,
+        crossing_policy: value.crossing_policy,
+        real_time_clock: value.real_time_clock,
+        wall_clock_policy: value.wall_clock_policy,
+    });
+}
+export function compareTmwEffectiveTime(left, right) {
+    return DOMAIN_ORDER[left.domain] - DOMAIN_ORDER[right.domain]
+        || left.due_value - right.due_value
+        || left.effective_value - right.effective_value
+        || left.crossing_policy.localeCompare(right.crossing_policy)
+        || String(left.real_time_clock).localeCompare(String(right.real_time_clock))
+        || String(left.wall_clock_policy).localeCompare(String(right.wall_clock_policy));
+}
+export function crossingPolicyAllows(policy, direction) {
+    if (!isCrossingPolicy(policy))
+        throw new Error("tmw_crossing_policy_invalid");
+    if (direction !== "forward" && direction !== "backward") {
+        throw new Error("tmw_crossing_direction_invalid");
+    }
+    return policy === "both_directions"
+        || (policy === "forward_only" && direction === "forward")
+        || (policy === "backward_only" && direction === "backward");
+}
+/** Materializes an authored due coordinate against a host-observed clock value. */
+export function observeTmwEffectiveTime(authored, observedValue) {
+    const canonical = canonicalTmwEffectiveTime(authored);
+    return canonicalTmwEffectiveTime(Object.freeze({
+        ...canonical,
+        effective_value: canonicalTmwClockCoordinate(observedValue, canonical.domain),
+    }));
+}
+/** Point-in-time eligibility. Repeated delivery is handled by operation identity. */
+export function tmwEffectiveTimeIsDue(effectiveTimeInput, observedValue, direction) {
+    const effectiveTime = canonicalTmwEffectiveTime(effectiveTimeInput);
+    const observed = canonicalTmwClockCoordinate(observedValue, effectiveTime.domain);
+    if (!crossingPolicyAllows(effectiveTime.crossing_policy, direction))
+        return false;
+    return direction === "forward"
+        ? observed >= effectiveTime.due_value
+        : observed <= effectiveTime.due_value;
+}
+/** Strict boundary crossing used by durable scheduler continuations. */
+export function tmwEffectiveTimeCrossedDue(effectiveTimeInput, previousObservedValue, observedValue, direction) {
+    const effectiveTime = canonicalTmwEffectiveTime(effectiveTimeInput);
+    const previous = canonicalTmwClockCoordinate(previousObservedValue, effectiveTime.domain);
+    const observed = canonicalTmwClockCoordinate(observedValue, effectiveTime.domain);
+    if (!crossingPolicyAllows(effectiveTime.crossing_policy, direction))
+        return false;
+    if (direction === "forward") {
+        return observed >= previous
+            && previous < effectiveTime.due_value
+            && effectiveTime.due_value <= observed;
+    }
+    return observed <= previous
+        && observed <= effectiveTime.due_value
+        && effectiveTime.due_value < previous;
+}