@world-engines/tmw 0.1.0-alpha.0

package/dist/runtime-sav.js

@@ -0,0 +1,356 @@
+import { preSceneRuntimeContractHashV3, TMW_RUNTIME_GENERATION } from "./runtime-contract.js";
+import { canonicalDurableIntent } from "./durable-intent.js";
+import { canonicalAudioPresentationProjection } from "./audio-presentation-projection.js";
+import { emptyTmwGameplayStateV1, persistentTmwGameplayStateV1 } from "./gameplay-state.js";
+import { canonicalSchedulerSnapshot } from "./scheduler.js";
+import { canonicalTmwPendingSceneClockCrossingV1, canonicalTmwSceneStateV1, } from "./scene-state.js";
+import { canonicalTimelineRevision, } from "./timeline-revision.js";
+import { canonicalTmwJson, canonicalTmwJsonValue, requireTmwIdentifier, requireTmwSafeInteger, requireTmwSha256, tmwSha256Hex, } from "./runtime-trace.js";
+export const TMW_RUNTIME_SAV_EXTENSION_ID = "tmw.runtime.v3";
+export const TMW_RUNTIME_SAV_SCHEMA_VERSION = 3;
+export const TMW_RUNTIME_SAV_CODEC = "application/vnd.world-engines.tmw-runtime-v3+json;canonical=1";
+function canonicalBinding(input) {
+    if (input.runtimeGeneration !== 3)
+        throw new Error("unsupported_runtime_generation");
+    return Object.freeze({
+        epoch: requireTmwSafeInteger(input.epoch, "sav_epoch", 1),
+        runtimeGeneration: TMW_RUNTIME_GENERATION,
+        runtimeContractHash: requireTmwSha256(input.runtimeContractHash, "sav_contract_hash"),
+        artifactDigest: requireTmwSha256(input.artifactDigest, "sav_artifact_digest"),
+        sourceRevision: requireTmwIdentifier(input.sourceRevision, "sav_source_revision"),
+        activeTimelineRevision: requireTmwIdentifier(input.activeTimelineRevision, "sav_timeline_revision"),
+        turnId: requireTmwIdentifier(input.turnId, "sav_turn_id"),
+        preActivationTerminalDigest: requireTmwSha256(input.preActivationTerminalDigest, "sav_pre_activation_terminal_digest"),
+    });
+}
+function uniqueSortedIdentifiers(values, label) {
+    const canonical = values.map((value) => requireTmwIdentifier(value, label));
+    if (new Set(canonical).size !== canonical.length)
+        throw new Error(`tmw_${label}_duplicate`);
+    return Object.freeze([...canonical].sort());
+}
+function uniqueSortedDigests(values, label) {
+    const canonical = values.map((value) => requireTmwSha256(value, label));
+    if (new Set(canonical).size !== canonical.length)
+        throw new Error(`tmw_${label}_duplicate`);
+    return Object.freeze([...canonical].sort());
+}
+function canonicalRecoveryOperations(values) {
+    const byOperationId = new Map();
+    for (const value of values) {
+        const operation = canonicalTmwJsonValue(value, "sav_world_mutation_recovery_operation");
+        if (typeof operation !== "object" || operation === null || Array.isArray(operation)) {
+            throw new Error("tmw_sav_world_mutation_recovery_operation_invalid");
+        }
+        const operationRecord = operation;
+        const operationId = requireTmwIdentifier(operationRecord.operationId, "sav_world_mutation_recovery_operation_id");
+        if (byOperationId.has(operationId)) {
+            throw new Error("tmw_sav_world_mutation_recovery_operation_duplicate");
+        }
+        byOperationId.set(operationId, operation);
+    }
+    return Object.freeze([...byOperationId.entries()]
+        .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+        .map(([, operation]) => operation));
+}
+export function canonicalRuntimeSavPayload(input) {
+    if (input.schemaVersion !== 3)
+        throw new Error("unsupported_sav_generation");
+    const binding = canonicalBinding(input);
+    const scheduler = canonicalSchedulerSnapshot(input.scheduler);
+    const scene = input.scene === null ? null : canonicalTmwSceneStateV1(input.scene);
+    if (!Array.isArray(input.pendingSceneClockCrossings))
+        throw new Error("tmw_sav_pending_scene_crossings_invalid");
+    const pendingSceneClockCrossings = input.pendingSceneClockCrossings.map(canonicalTmwPendingSceneClockCrossingV1);
+    if (new Set(pendingSceneClockCrossings.map((item) => item.eventId)).size !== pendingSceneClockCrossings.length) {
+        throw new Error("tmw_sav_pending_scene_crossing_duplicate");
+    }
+    const projectedWorldTime = scheduler.cursor?.worldTime ?? null;
+    if (scene !== null && projectedWorldTime !== scene.worldTime) {
+        throw new Error("tmw_sav_scene_scheduler_world_time_mismatch");
+    }
+    const intents = input.durableIntents.map(canonicalDurableIntent).sort((left, right) => left.intentId < right.intentId ? -1 : left.intentId > right.intentId ? 1 : 0);
+    if (new Set(intents.map((value) => value.intentId)).size !== intents.length) {
+        throw new Error("tmw_sav_intent_duplicate");
+    }
+    for (const suspension of scheduler.suspensions) {
+        if (suspension.epoch !== binding.epoch
+            || suspension.runtimeContractHash !== binding.runtimeContractHash
+            || suspension.artifactDigest !== binding.artifactDigest
+            || suspension.sourceRevision !== binding.sourceRevision
+            || suspension.timelineRevision !== binding.activeTimelineRevision) {
+            throw new Error("tmw_sav_suspension_binding_mismatch");
+        }
+    }
+    for (const intent of intents) {
+        if (intent.epoch !== binding.epoch
+            || intent.runtimeContractHash !== binding.runtimeContractHash
+            || intent.artifactDigest !== binding.artifactDigest
+            || intent.sourceRevision !== binding.sourceRevision
+            || intent.timelineRevision !== binding.activeTimelineRevision) {
+            throw new Error("tmw_sav_intent_binding_mismatch");
+        }
+    }
+    const activeTimeline = canonicalTimelineRevision(input.activeTimeline);
+    if (activeTimeline.revisionId !== binding.activeTimelineRevision
+        || activeTimeline.active !== true
+        || activeTimeline.epoch !== binding.epoch
+        || activeTimeline.runtimeContractHash !== binding.runtimeContractHash
+        || activeTimeline.artifactDigest !== binding.artifactDigest
+        || activeTimeline.sourceRevision !== binding.sourceRevision
+        || activeTimeline.ledgerHead !== input.ledgerHead) {
+        throw new Error("tmw_sav_timeline_binding_mismatch");
+    }
+    return Object.freeze({
+        schemaVersion: 3,
+        ...binding,
+        activeTimeline,
+        ledgerHead: requireTmwSha256(input.ledgerHead, "sav_ledger_head"),
+        eventLedger: canonicalTmwJsonValue(input.eventLedger, "sav_event_ledger"),
+        narrative: canonicalTmwJsonValue(input.narrative, "sav_narrative"),
+        gameplayState: persistentTmwGameplayStateV1(input.gameplayState ?? emptyTmwGameplayStateV1()),
+        gameplayInitialState: persistentTmwGameplayStateV1(input.gameplayInitialState ?? input.gameplayState ?? emptyTmwGameplayStateV1()),
+        scene,
+        pendingSceneClockCrossings: Object.freeze(pendingSceneClockCrossings),
+        scheduler,
+        conditionState: canonicalTmwJsonValue(input.conditionState, "sav_condition_state"),
+        durableIntents: Object.freeze(intents),
+        presentationIntents: Object.freeze(input.presentationIntents.map((intent) => canonicalTmwJsonValue(intent, "sav_presentation_intent"))),
+        audioPresentation: input.audioPresentation == null
+            ? null
+            : canonicalAudioPresentationProjection(input.audioPresentation),
+        semanticVerdictRefs: uniqueSortedIdentifiers(input.semanticVerdictRefs, "sav_verdict_ref"),
+        candidateSetRevisions: uniqueSortedIdentifiers(input.candidateSetRevisions, "sav_candidate_revision"),
+        operationReceiptDigests: uniqueSortedDigests(input.operationReceiptDigests, "sav_operation_receipt_digest"),
+        completedOperationIds: uniqueSortedIdentifiers(input.completedOperationIds ?? [], "sav_completed_operation_id"),
+        worldMutationRecoveryOperations: canonicalRecoveryOperations(input.worldMutationRecoveryOperations),
+    });
+}
+function hexToBytes(hex) {
+    return Uint8Array.from(hex.match(/.{2}/g)?.map((pair) => Number.parseInt(pair, 16)) ?? []);
+}
+function bytesToHex(bytes) {
+    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+export async function runtimeSavSectionDigest(section) {
+    return await runtimeSavPayloadDigest(await decodeRuntimeSavSectionSelfBound(section));
+}
+export async function runtimeSavPayloadDigest(input) {
+    const payload = canonicalRuntimeSavPayload(input);
+    const { savSectionDigest: _selfDigest, ...timelineWithoutSelfDigest } = payload.activeTimeline;
+    return await tmwSha256Hex(canonicalTmwJson({
+        ...payload,
+        activeTimeline: timelineWithoutSelfDigest,
+    }));
+}
+function canonicalPublishedMigrationSide(input, label, requireCompiledPlan) {
+    const side = Object.freeze({
+        contentEpoch: requireTmwSafeInteger(input.contentEpoch, `${label}_epoch`, 1),
+        reviewedHeadDigest: requireTmwSha256(input.reviewedHeadDigest, `${label}_reviewed_head_digest`),
+        runtimeContractHash: requireTmwSha256(input.runtimeContractHash, `${label}_runtime_contract_hash`),
+        artifactDigest: requireTmwSha256(input.artifactDigest, `${label}_artifact_digest`),
+        sourceRevision: requireTmwIdentifier(input.sourceRevision, `${label}_source_revision`),
+        ...(requireCompiledPlan
+            ? { compiledPlanSha256: requireTmwSha256(input.compiledPlanSha256, `${label}_compiled_plan_sha256`) }
+            : {}),
+    });
+    return side;
+}
+/** Fail closed on a replay, cross-scenario, source, epoch, or plan identity drift. */
+export function canonicalPreSceneRuntimeSavPublishedMigrationV1(input) {
+    if (input.schemaVersion !== 1)
+        throw new Error("tmw_sav_published_migration_schema_unsupported");
+    const predecessor = canonicalPublishedMigrationSide(input.predecessor, "sav_migration_predecessor", false);
+    const successor = canonicalPublishedMigrationSide(input.successor, "sav_migration_successor", true);
+    if (predecessor.reviewedHeadDigest === successor.reviewedHeadDigest
+        || predecessor.contentEpoch !== successor.contentEpoch
+        || predecessor.runtimeContractHash === successor.runtimeContractHash) {
+        throw new Error("tmw_sav_published_migration_identity_invalid");
+    }
+    return Object.freeze({
+        schemaVersion: 1,
+        scenarioId: requireTmwIdentifier(input.scenarioId, "sav_migration_scenario_id"),
+        predecessor,
+        successor: successor,
+    });
+}
+/** Explicit pre-Scene migration; normal decoders never synthesize Scene from a malformed field. */
+export async function migratePreSceneRuntimeSavV3(legacyInput, authority) {
+    const raw = legacyInput;
+    if (Object.prototype.hasOwnProperty.call(raw, "scene")
+        || Object.prototype.hasOwnProperty.call(raw, "pendingSceneClockCrossings")) {
+        throw new Error("tmw_sav_scene_migration_not_legacy");
+    }
+    const expectedLegacyHash = await preSceneRuntimeContractHashV3();
+    const successorRuntimeContractHash = requireTmwSha256(authority.successorRuntimeContractHash, "sav_migration_successor_contract_hash");
+    const expectedLegacyArtifactDigest = requireTmwSha256(authority.expectedLegacyArtifactDigest, "sav_migration_legacy_artifact_digest");
+    if (legacyInput.runtimeContractHash !== expectedLegacyHash || expectedLegacyHash === successorRuntimeContractHash) {
+        throw new Error("tmw_sav_scene_migration_contract_mismatch");
+    }
+    if (legacyInput.artifactDigest !== expectedLegacyArtifactDigest) {
+        throw new Error("tmw_sav_scene_migration_artifact_mismatch");
+    }
+    const scheduler = canonicalSchedulerSnapshot(legacyInput.scheduler);
+    const scene = canonicalTmwSceneStateV1({
+        schemaVersion: 1,
+        sceneId: authority.sceneId,
+        revision: 0,
+        worldTime: scheduler.cursor?.worldTime ?? null,
+        presentEntityNodeIds: authority.presentEntityNodeIds,
+        spatialRef: authority.spatialRef,
+        manuscriptNotes: Object.freeze([]),
+    });
+    const validatedLegacy = canonicalRuntimeSavPayload({
+        ...legacyInput,
+        scene,
+        pendingSceneClockCrossings: Object.freeze([]),
+    });
+    const legacyPayloadDigest = await tmwSha256Hex(canonicalTmwJson(legacyInput));
+    const operationId = requireTmwIdentifier(authority.operationId, "sav_migration_operation_id");
+    const successorArtifactDigest = requireTmwSha256(authority.successorArtifactDigest, "sav_migration_successor_artifact_digest");
+    const successorRevision = `tmw3:scene-migration:${legacyPayloadDigest}`;
+    const provisional = Object.freeze({
+        ...validatedLegacy,
+        runtimeContractHash: successorRuntimeContractHash,
+        artifactDigest: successorArtifactDigest,
+        activeTimelineRevision: successorRevision,
+        turnId: requireTmwIdentifier(authority.turnId, "sav_migration_turn_id"),
+        preActivationTerminalDigest: legacyPayloadDigest,
+        activeTimeline: Object.freeze({
+            ...validatedLegacy.activeTimeline,
+            revisionId: successorRevision,
+            parentRevisionId: validatedLegacy.activeTimelineRevision,
+            revisionSequence: validatedLegacy.activeTimeline.revisionSequence + 1,
+            runtimeContractHash: successorRuntimeContractHash,
+            artifactDigest: successorArtifactDigest,
+            operationId,
+            savSectionDigest: "0".repeat(64),
+            createdFrom: "turn",
+        }),
+        scene,
+        pendingSceneClockCrossings: Object.freeze([]),
+        scheduler: Object.freeze({
+            cursor: scheduler.cursor ?? null,
+            suspensions: Object.freeze(scheduler.suspensions.map((suspension) => Object.freeze({
+                ...suspension,
+                runtimeContractHash: successorRuntimeContractHash,
+                artifactDigest: successorArtifactDigest,
+                timelineRevision: successorRevision,
+            }))),
+        }),
+        durableIntents: Object.freeze(validatedLegacy.durableIntents.map((intent) => Object.freeze({
+            ...intent,
+            runtimeContractHash: successorRuntimeContractHash,
+            artifactDigest: successorArtifactDigest,
+            timelineRevision: successorRevision,
+        }))),
+        operationReceiptDigests: Object.freeze([...validatedLegacy.operationReceiptDigests, legacyPayloadDigest]),
+        completedOperationIds: Object.freeze([...(validatedLegacy.completedOperationIds ?? []), operationId]),
+    });
+    const successorPayloadDigest = await runtimeSavPayloadDigest(provisional);
+    const payload = canonicalRuntimeSavPayload(Object.freeze({
+        ...provisional,
+        activeTimeline: Object.freeze({ ...provisional.activeTimeline, savSectionDigest: successorPayloadDigest }),
+    }));
+    return Object.freeze({ legacyPayloadDigest, successorPayloadDigest, payload });
+}
+export async function encodeRuntimeSavSection(input) {
+    const payload = canonicalRuntimeSavPayload(input);
+    const bytes = new TextEncoder().encode(canonicalTmwJson(payload));
+    const digest = await tmwSha256Hex(bytes);
+    return Object.freeze({
+        extension_id: TMW_RUNTIME_SAV_EXTENSION_ID,
+        schema_version: TMW_RUNTIME_SAV_SCHEMA_VERSION,
+        payload: bytes,
+        codec: TMW_RUNTIME_SAV_CODEC,
+        payload_sha256: hexToBytes(digest),
+        required: true,
+    });
+}
+function parsePayload(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error("tmw_sav_payload_invalid");
+    }
+    return canonicalRuntimeSavPayload(value);
+}
+export async function decodeRuntimeSavSection(section, expected) {
+    const payload = await decodeRuntimeSavSectionForScope(section, expected);
+    const binding = canonicalBinding(expected);
+    for (const [label, actual, wanted] of [
+        ["timeline", payload.activeTimelineRevision, binding.activeTimelineRevision],
+        ["turn", payload.turnId, binding.turnId],
+        [
+            "terminal",
+            payload.preActivationTerminalDigest,
+            binding.preActivationTerminalDigest,
+        ],
+    ]) {
+        if (actual !== wanted)
+            throw new Error(`tmw_sav_${label}_mismatch`);
+    }
+    return payload;
+}
+export async function decodeRuntimeSavSectionForScope(section, expected) {
+    const payload = await decodeRuntimeSavSectionSelfBound(section);
+    if (expected.runtimeGeneration !== 3)
+        throw new Error("unsupported_runtime_generation");
+    for (const [label, actual, wanted] of [
+        ["epoch", payload.epoch, expected.epoch],
+        ["contract", payload.runtimeContractHash, expected.runtimeContractHash],
+        ["artifact", payload.artifactDigest, expected.artifactDigest],
+        ["source", payload.sourceRevision, expected.sourceRevision],
+    ]) {
+        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_sav_${label}_mismatch`);
+        }
+    }
+    return payload;
+}
+export async function decodeRuntimeSavSectionSelfBound(section) {
+    if (section.extension_id !== TMW_RUNTIME_SAV_EXTENSION_ID)
+        throw new Error("sav_section_missing");
+    if (section.schema_version !== TMW_RUNTIME_SAV_SCHEMA_VERSION) {
+        throw new Error("unsupported_sav_generation");
+    }
+    if (section.codec !== TMW_RUNTIME_SAV_CODEC || section.required !== true) {
+        throw new Error("tmw_sav_section_contract_invalid");
+    }
+    const actualDigest = await tmwSha256Hex(section.payload);
+    if (bytesToHex(section.payload_sha256) !== actualDigest)
+        throw new Error("tmw_sav_payload_hash_mismatch");
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(section.payload));
+    }
+    catch (cause) {
+        throw new Error("tmw_sav_payload_decode_failed", { cause });
+    }
+    const payload = parsePayload(parsed);
+    return payload;
+}
+export async function requireRuntimeSavSection(sections, expected) {
+    const matches = sections.filter((section) => section.extension_id === TMW_RUNTIME_SAV_EXTENSION_ID);
+    if (matches.length === 0)
+        throw new Error("sav_section_missing");
+    if (matches.length !== 1)
+        throw new Error("tmw_sav_section_duplicate");
+    const section = matches[0];
+    if (section === undefined)
+        throw new Error("sav_section_missing");
+    return await decodeRuntimeSavSection(section, expected);
+}
+export async function requireRuntimeSavSectionForScope(sections, expected) {
+    const matches = sections.filter((section) => section.extension_id === TMW_RUNTIME_SAV_EXTENSION_ID);
+    if (matches.length === 0)
+        throw new Error("sav_section_missing");
+    if (matches.length !== 1)
+        throw new Error("tmw_sav_section_duplicate");
+    const section = matches[0];
+    if (section === undefined)
+        throw new Error("sav_section_missing");
+    return await decodeRuntimeSavSectionForScope(section, expected);
+}

package/dist/runtime-trace.d.ts

@@ -0,0 +1,44 @@
+export type TmwJsonPrimitive = null | boolean | number | string;
+export type TmwJsonValue = TmwJsonPrimitive | ReadonlyArray<TmwJsonValue> | Readonly<{
+    [key: string]: TmwJsonValue;
+}>;
+export interface RuntimeTraceEntry {
+    readonly sequence: number;
+    readonly kind: string;
+    readonly stableId: string;
+    readonly detail: Readonly<Record<string, TmwJsonValue>>;
+}
+export interface RuntimeTraceSnapshot {
+    readonly maxEntries: number;
+    readonly nextSequence: number;
+    readonly truncatedEntries: number;
+    readonly entries: ReadonlyArray<RuntimeTraceEntry>;
+}
+/** Content-free clock audit fields; payloads and author source never enter trace. */
+export interface RuntimeClockTraceDetail extends Readonly<Record<string, TmwJsonValue>> {
+    readonly clockDomain: "logical_seq" | "world_time" | "presentation_seq" | "real_time";
+    readonly observedValue: number | null;
+    readonly dueValue: number;
+    readonly previousObservedValue: number | null;
+    readonly crossingDirection: "forward" | "backward";
+}
+export declare class TmwRuntimeInvariantError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+export declare function requireTmwIdentifier(value: string, label: string): string;
+export declare function requireTmwSha256(value: string, label: string): string;
+export declare function requireTmwSafeInteger(value: number, label: string, minimum?: number): number;
+export declare function canonicalTmwJsonValue(value: unknown, label?: string): TmwJsonValue;
+export declare function canonicalTmwJson(value: unknown): string;
+export declare function tmwSha256Hex(value: unknown): Promise<string>;
+export declare class BoundedRuntimeTrace {
+    #private;
+    constructor(maxEntries?: number);
+    append(input: Readonly<{
+        kind: string;
+        stableId: string;
+        detail?: Readonly<Record<string, unknown>>;
+    }>): RuntimeTraceEntry;
+    snapshot(): RuntimeTraceSnapshot;
+}

package/dist/runtime-trace.js

@@ -0,0 +1,119 @@
+const IDENTIFIER = /^[^\0\r\n]{1,512}$/;
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+const DEFAULT_MAX_TRACE_ENTRIES = 256;
+const MAX_TRACE_ENTRIES = 4096;
+const TEXT_ENCODER = new TextEncoder();
+export class TmwRuntimeInvariantError extends Error {
+    code;
+    constructor(code) {
+        super(`tmw_runtime_${code}`);
+        this.name = "TmwRuntimeInvariantError";
+        this.code = code;
+    }
+}
+export function requireTmwIdentifier(value, label) {
+    if (typeof value !== "string" || !IDENTIFIER.test(value)) {
+        throw new TmwRuntimeInvariantError(`${label}_invalid`);
+    }
+    return value;
+}
+export function requireTmwSha256(value, label) {
+    if (typeof value !== "string" || !SHA256_HEX.test(value)) {
+        throw new TmwRuntimeInvariantError(`${label}_invalid`);
+    }
+    return value;
+}
+export function requireTmwSafeInteger(value, label, minimum = 0) {
+    if (!Number.isSafeInteger(value) || value < minimum) {
+        throw new TmwRuntimeInvariantError(`${label}_invalid`);
+    }
+    return value;
+}
+function canonicalizeJson(value, path, ancestors) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new TmwRuntimeInvariantError(`${path}_non_finite`);
+        return Object.is(value, -0) ? 0 : value;
+    }
+    if (typeof value !== "object")
+        throw new TmwRuntimeInvariantError(`${path}_non_json`);
+    if (ancestors.has(value))
+        throw new TmwRuntimeInvariantError(`${path}_cycle`);
+    const nextAncestors = new Set(ancestors);
+    nextAncestors.add(value);
+    if (Array.isArray(value)) {
+        return Object.freeze(value.map((item, index) => canonicalizeJson(item, `${path}_${index}`, nextAncestors)));
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new TmwRuntimeInvariantError(`${path}_prototype_invalid`);
+    }
+    const source = value;
+    const result = Object.create(null);
+    for (const key of Object.keys(source).sort()) {
+        requireTmwIdentifier(key, `${path}_key`);
+        if (source[key] === undefined)
+            throw new TmwRuntimeInvariantError(`${path}_${key}_undefined`);
+        result[key] = canonicalizeJson(source[key], `${path}_${key}`, nextAncestors);
+    }
+    return Object.freeze(result);
+}
+export function canonicalTmwJsonValue(value, label = "json") {
+    return canonicalizeJson(value, label, new Set());
+}
+export function canonicalTmwJson(value) {
+    return JSON.stringify(canonicalTmwJsonValue(value));
+}
+export async function tmwSha256Hex(value) {
+    const bytes = typeof value === "string"
+        ? TEXT_ENCODER.encode(value)
+        : value instanceof Uint8Array
+            ? value
+            : TEXT_ENCODER.encode(canonicalTmwJson(value));
+    const digest = await crypto.subtle.digest("SHA-256", Uint8Array.from(bytes).buffer);
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+export class BoundedRuntimeTrace {
+    #maxEntries;
+    #entries = [];
+    #nextSequence = 0;
+    #truncatedEntries = 0;
+    constructor(maxEntries = DEFAULT_MAX_TRACE_ENTRIES) {
+        this.#maxEntries = requireTmwSafeInteger(maxEntries, "trace_max_entries", 1);
+        if (this.#maxEntries > MAX_TRACE_ENTRIES) {
+            throw new TmwRuntimeInvariantError("trace_max_entries_exceeded");
+        }
+    }
+    append(input) {
+        if (this.#nextSequence === Number.MAX_SAFE_INTEGER) {
+            throw new TmwRuntimeInvariantError("trace_sequence_exhausted");
+        }
+        const detail = canonicalTmwJsonValue(input.detail ?? {}, "trace_detail");
+        if (detail === null || Array.isArray(detail) || typeof detail !== "object") {
+            throw new TmwRuntimeInvariantError("trace_detail_invalid");
+        }
+        const entry = Object.freeze({
+            sequence: this.#nextSequence,
+            kind: requireTmwIdentifier(input.kind, "trace_kind"),
+            stableId: requireTmwIdentifier(input.stableId, "trace_stable_id"),
+            detail: detail,
+        });
+        this.#nextSequence += 1;
+        if (this.#entries.length === this.#maxEntries) {
+            this.#entries.shift();
+            this.#truncatedEntries += 1;
+        }
+        this.#entries.push(entry);
+        return entry;
+    }
+    snapshot() {
+        return Object.freeze({
+            maxEntries: this.#maxEntries,
+            nextSequence: this.#nextSequence,
+            truncatedEntries: this.#truncatedEntries,
+            entries: Object.freeze([...this.#entries]),
+        });
+    }
+}