@world-engines/tmw 0.1.0-alpha.0

package/dist/presentation-intent.js

@@ -0,0 +1,137 @@
+const SHA256_HEX = /^[a-f0-9]{64}$/;
+const STABLE_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isTmwJsonValue = (value) => {
+    if (value === null || typeof value === "boolean" || typeof value === "string")
+        return true;
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every(isTmwJsonValue);
+    return isRecord(value) && Object.values(value).every(isTmwJsonValue);
+};
+const exactKeys = (value, keys) => Object.keys(value).sort().join("\0") === [...keys].sort().join("\0");
+export const parsePresentationPayloadV3 = (value) => {
+    if (!isRecord(value))
+        return null;
+    if (value.kind === "view") {
+        if (!exactKeys(value, ["kind", "overlay_id", "visible"]))
+            return null;
+        if (typeof value.overlay_id !== "string" || !STABLE_ID.test(value.overlay_id))
+            return null;
+        if (typeof value.visible !== "boolean")
+            return null;
+    }
+    else if (value.kind === "atmosphere") {
+        if (!exactKeys(value, ["atmosphere_id", "intensity", "kind"]))
+            return null;
+        if (value.atmosphere_id !== null
+            && (typeof value.atmosphere_id !== "string" || !STABLE_ID.test(value.atmosphere_id)))
+            return null;
+        if (typeof value.intensity !== "number" || !Number.isFinite(value.intensity)
+            || value.intensity < 0 || value.intensity > 1)
+            return null;
+    }
+    else if (value.kind === "music") {
+        if (!exactKeys(value, [
+            "candidate_set_id",
+            "candidate_set_revision",
+            "kind",
+            "preferred_resource_id"
+        ]))
+            return null;
+        if (typeof value.candidate_set_id !== "string" || !STABLE_ID.test(value.candidate_set_id))
+            return null;
+        if (typeof value.candidate_set_revision !== "number"
+            || !Number.isSafeInteger(value.candidate_set_revision)
+            || value.candidate_set_revision <= 0)
+            return null;
+        if (value.preferred_resource_id !== null
+            && (typeof value.preferred_resource_id !== "string" || !STABLE_ID.test(value.preferred_resource_id)))
+            return null;
+    }
+    else
+        return null;
+    return value;
+};
+export const parsePresentationIntentV3 = (value) => {
+    if (!isRecord(value) || !exactKeys(value, [
+        "activation_id",
+        "artifact_digest",
+        "dedupe_key",
+        "epoch",
+        "generation",
+        "intent_id",
+        "metadata",
+        "payload",
+        "schema",
+        "sequence",
+        "timeline_revision"
+    ]))
+        return null;
+    if (value.schema !== "presentation-intent.v3" || value.generation !== 3)
+        return null;
+    if (typeof value.intent_id !== "string" || !STABLE_ID.test(value.intent_id)
+        || typeof value.activation_id !== "string" || !STABLE_ID.test(value.activation_id)
+        || typeof value.dedupe_key !== "string" || !STABLE_ID.test(value.dedupe_key)
+        || typeof value.timeline_revision !== "string" || !STABLE_ID.test(value.timeline_revision))
+        return null;
+    if (!Number.isSafeInteger(value.epoch) || value.epoch <= 0)
+        return null;
+    if (typeof value.artifact_digest !== "string" || !SHA256_HEX.test(value.artifact_digest))
+        return null;
+    if (!Number.isSafeInteger(value.sequence) || value.sequence < 0)
+        return null;
+    if (parsePresentationPayloadV3(value.payload) === null
+        || !isRecord(value.metadata)
+        || !isTmwJsonValue(value.metadata))
+        return null;
+    return value;
+};
+export const committedPresentationActivationError = (activation) => {
+    const { candidate, receipt } = activation;
+    if (receipt.status !== "committed" && receipt.status !== "already_committed") {
+        return "presentation_activation_not_committed";
+    }
+    if (receipt.operationId !== candidate.operationId
+        || receipt.activeHead.revisionId !== candidate.timeline.revisionId
+        || receipt.activeHead.revisionSequence !== candidate.timeline.revisionSequence
+        || receipt.activeHead.ledgerHead !== candidate.timeline.ledgerHead) {
+        return "presentation_activation_mismatch";
+    }
+    if (receipt.atomicWriteCount !== 5)
+        return "presentation_activation_atomic_write_count_invalid";
+    if (!SHA256_HEX.test(receipt.candidateDigest) || !SHA256_HEX.test(receipt.receiptDigest)) {
+        return "presentation_activation_receipt_digest_invalid";
+    }
+    return null;
+};
+export const presentationIntentError = (intent, activation) => {
+    const { candidate, receipt } = activation;
+    const activationError = committedPresentationActivationError(activation);
+    if (activationError !== null)
+        return activationError;
+    if (intent.schema !== "presentation-intent.v3" || intent.generation !== 3)
+        return "presentation_intent_generation_invalid";
+    if (!STABLE_ID.test(intent.intent_id) || !STABLE_ID.test(intent.activation_id) || !STABLE_ID.test(intent.dedupe_key)) {
+        return "presentation_intent_identity_invalid";
+    }
+    if (!Number.isSafeInteger(intent.epoch) || intent.epoch <= 0 || intent.epoch !== candidate.epoch)
+        return "stale_content_epoch";
+    if (!SHA256_HEX.test(intent.artifact_digest) || intent.artifact_digest !== candidate.artifactDigest) {
+        return "presentation_artifact_mismatch";
+    }
+    if (!STABLE_ID.test(intent.timeline_revision))
+        return "presentation_timeline_revision_invalid";
+    if (intent.timeline_revision !== candidate.timeline.revisionId
+        || receipt.activeHead.revisionId !== candidate.timeline.revisionId
+        || intent.activation_id !== candidate.operationId
+        || receipt.operationId !== candidate.operationId) {
+        return "presentation_activation_mismatch";
+    }
+    if (!Number.isSafeInteger(intent.sequence) || intent.sequence < 0)
+        return "presentation_sequence_invalid";
+    if (parsePresentationPayloadV3(intent.payload) === null)
+        return "presentation_payload_invalid";
+    return null;
+};

package/dist/recall-query-envelope.d.ts

@@ -0,0 +1,32 @@
+import { TMW_RUNTIME_GENERATION } from "./runtime-contract.js";
+import { type TmwJsonValue } from "./runtime-trace.js";
+export interface RecallQueryEnvelopeV3 {
+    readonly schemaVersion: 3;
+    readonly epoch: number;
+    readonly runtimeGeneration: typeof TMW_RUNTIME_GENERATION;
+    readonly runtimeContractHash: string;
+    readonly runtimeLeaseId: string;
+    readonly artifactDigest: string;
+    readonly artifactRevision: string;
+    readonly sourceRevision: string;
+    readonly timelineRevision: string;
+    readonly turnId: string;
+    readonly operationId: string;
+    readonly queryId: string;
+    readonly generation: number;
+    readonly query: TmwJsonValue;
+    readonly queryCanonicalJson: string;
+    readonly queryDigest: string;
+}
+export declare function canonicalRecallQueryEnvelope(input: RecallQueryEnvelopeV3): RecallQueryEnvelopeV3;
+export declare function assertRecallQueryBinding(envelopeInput: RecallQueryEnvelopeV3, expected: Readonly<{
+    epoch: number;
+    runtimeContractHash: string;
+    runtimeLeaseId: string;
+    artifactDigest: string;
+    artifactRevision: string;
+    sourceRevision: string;
+    timelineRevision: string;
+    turnId: string;
+    generation: number;
+}>): RecallQueryEnvelopeV3;

package/dist/recall-query-envelope.js

@@ -0,0 +1,51 @@
+import { TMW_RUNTIME_GENERATION } from "./runtime-contract.js";
+import { canonicalTmwJson, canonicalTmwJsonValue, requireTmwIdentifier, requireTmwSafeInteger, requireTmwSha256, } from "./runtime-trace.js";
+export function canonicalRecallQueryEnvelope(input) {
+    if (input.schemaVersion !== 3 || input.runtimeGeneration !== 3) {
+        throw new Error("unsupported_runtime_generation");
+    }
+    const query = canonicalTmwJsonValue(input.query, "recall_query");
+    const queryCanonicalJson = canonicalTmwJson(query);
+    if (input.queryCanonicalJson !== queryCanonicalJson) {
+        throw new Error("recall_query_canonical_json_mismatch");
+    }
+    return Object.freeze({
+        schemaVersion: 3,
+        epoch: requireTmwSafeInteger(input.epoch, "recall_epoch", 1),
+        runtimeGeneration: TMW_RUNTIME_GENERATION,
+        runtimeContractHash: requireTmwSha256(input.runtimeContractHash, "recall_contract_hash"),
+        runtimeLeaseId: requireTmwIdentifier(input.runtimeLeaseId, "recall_runtime_lease_id"),
+        artifactDigest: requireTmwSha256(input.artifactDigest, "recall_artifact_digest"),
+        artifactRevision: requireTmwIdentifier(input.artifactRevision, "recall_artifact_revision"),
+        sourceRevision: requireTmwIdentifier(input.sourceRevision, "recall_source_revision"),
+        timelineRevision: requireTmwIdentifier(input.timelineRevision, "recall_timeline_revision"),
+        turnId: requireTmwIdentifier(input.turnId, "recall_turn_id"),
+        operationId: requireTmwIdentifier(input.operationId, "recall_operation_id"),
+        queryId: requireTmwIdentifier(input.queryId, "recall_query_id"),
+        generation: requireTmwSafeInteger(input.generation, "recall_generation", 1),
+        query,
+        queryCanonicalJson,
+        queryDigest: requireTmwSha256(input.queryDigest, "recall_query_digest"),
+    });
+}
+export function assertRecallQueryBinding(envelopeInput, expected) {
+    const envelope = canonicalRecallQueryEnvelope(envelopeInput);
+    if (envelope.epoch !== expected.epoch)
+        throw new Error("stale_content_epoch");
+    if (envelope.runtimeContractHash !== expected.runtimeContractHash) {
+        throw new Error("runtime_contract_hash_mismatch");
+    }
+    for (const [label, actual, wanted] of [
+        ["runtime_lease_id", envelope.runtimeLeaseId, expected.runtimeLeaseId],
+        ["artifact_digest", envelope.artifactDigest, expected.artifactDigest],
+        ["artifact_revision", envelope.artifactRevision, expected.artifactRevision],
+        ["source_revision", envelope.sourceRevision, expected.sourceRevision],
+        ["timeline_revision", envelope.timelineRevision, expected.timelineRevision],
+        ["turn_id", envelope.turnId, expected.turnId],
+        ["generation", envelope.generation, expected.generation],
+    ]) {
+        if (actual !== wanted)
+            throw new Error(`tmw_recall_${label}_mismatch`);
+    }
+    return envelope;
+}

package/dist/rewrite-compensation.d.ts

@@ -0,0 +1,28 @@
+import type { TemporalRewriteCompensationProposalV3 } from "./temporal-rewrite.js";
+export interface RewriteCompensationReceiptV3 {
+    readonly operationId: string;
+    readonly sourceTimelineRevision: string;
+    readonly targetTimelineRevision: string;
+    readonly externalEffectId: string;
+    readonly policy: TemporalRewriteCompensationProposalV3["policy"];
+    readonly status: "recorded";
+    readonly reasonCode: string;
+    readonly receiptDigest: string;
+}
+export interface RewriteCompensationReceiptSetV3 {
+    readonly receipts: ReadonlyArray<RewriteCompensationReceiptV3>;
+    readonly receiptSetDigest: string;
+}
+export declare function createRewriteCompensationReceipts(input: Readonly<{
+    operationId: string;
+    sourceTimelineRevision: string;
+    targetTimelineRevision: string;
+    proposals: ReadonlyArray<TemporalRewriteCompensationProposalV3>;
+}>): Promise<RewriteCompensationReceiptSetV3>;
+export declare function recordRewriteCompensations(input: Readonly<{
+    operationId: string;
+    sourceTimelineRevision: string;
+    targetTimelineRevision: string;
+    proposals: ReadonlyArray<TemporalRewriteCompensationProposalV3>;
+    receiptDigests: Readonly<Record<string, string>>;
+}>): ReadonlyArray<RewriteCompensationReceiptV3>;

package/dist/rewrite-compensation.js

@@ -0,0 +1,85 @@
+import { canonicalTmwJson, requireTmwIdentifier, requireTmwSha256, tmwSha256Hex, } from "./runtime-trace.js";
+function canonicalPolicy(value) {
+    if (value !== "retain_fact" && value !== "project_only" && value !== "requires_confirmation") {
+        throw new Error("tmw_compensation_policy_invalid");
+    }
+    return value;
+}
+function canonicalReceiptImage(input) {
+    if (input.status !== "recorded")
+        throw new Error("tmw_compensation_status_invalid");
+    return Object.freeze({
+        operationId: requireTmwIdentifier(input.operationId, "compensation_operation_id"),
+        sourceTimelineRevision: requireTmwIdentifier(input.sourceTimelineRevision, "compensation_source_timeline"),
+        targetTimelineRevision: requireTmwIdentifier(input.targetTimelineRevision, "compensation_target_timeline"),
+        externalEffectId: requireTmwIdentifier(input.externalEffectId, "compensation_external_effect_id"),
+        policy: canonicalPolicy(input.policy),
+        status: "recorded",
+        reasonCode: requireTmwIdentifier(input.reasonCode, "compensation_reason_code"),
+    });
+}
+export async function createRewriteCompensationReceipts(input) {
+    const operationId = requireTmwIdentifier(input.operationId, "compensation_operation_id");
+    const sourceTimelineRevision = requireTmwIdentifier(input.sourceTimelineRevision, "compensation_source_timeline");
+    const targetTimelineRevision = requireTmwIdentifier(input.targetTimelineRevision, "compensation_target_timeline");
+    const seen = new Set();
+    const receipts = [];
+    for (const proposal of [...input.proposals].sort((left, right) => left.externalEffectId < right.externalEffectId
+        ? -1
+        : left.externalEffectId > right.externalEffectId
+            ? 1
+            : 0)) {
+        const externalEffectId = requireTmwIdentifier(proposal.externalEffectId, "compensation_external_effect_id");
+        if (seen.has(externalEffectId))
+            throw new Error("tmw_compensation_effect_duplicate");
+        seen.add(externalEffectId);
+        const image = canonicalReceiptImage({
+            operationId,
+            sourceTimelineRevision,
+            targetTimelineRevision,
+            externalEffectId,
+            policy: proposal.policy,
+            status: "recorded",
+            reasonCode: proposal.reasonCode,
+        });
+        receipts.push(Object.freeze({
+            ...image,
+            receiptDigest: await tmwSha256Hex(canonicalTmwJson(image)),
+        }));
+    }
+    const receiptSetDigest = await tmwSha256Hex(canonicalTmwJson(receipts.map((receipt) => receipt.receiptDigest)));
+    return Object.freeze({
+        receipts: Object.freeze(receipts),
+        receiptSetDigest,
+    });
+}
+export function recordRewriteCompensations(input) {
+    const operationId = requireTmwIdentifier(input.operationId, "compensation_operation_id");
+    const sourceTimelineRevision = requireTmwIdentifier(input.sourceTimelineRevision, "compensation_source_timeline");
+    const targetTimelineRevision = requireTmwIdentifier(input.targetTimelineRevision, "compensation_target_timeline");
+    const seen = new Set();
+    return Object.freeze([...input.proposals]
+        .sort((left, right) => left.externalEffectId < right.externalEffectId ? -1 : 1)
+        .map((proposal) => {
+        const externalEffectId = requireTmwIdentifier(proposal.externalEffectId, "compensation_external_effect_id");
+        if (seen.has(externalEffectId))
+            throw new Error("tmw_compensation_effect_duplicate");
+        seen.add(externalEffectId);
+        const receiptDigest = input.receiptDigests[externalEffectId];
+        if (receiptDigest === undefined)
+            throw new Error("tmw_compensation_receipt_missing");
+        const image = canonicalReceiptImage({
+            operationId,
+            sourceTimelineRevision,
+            targetTimelineRevision,
+            externalEffectId,
+            policy: canonicalPolicy(proposal.policy),
+            status: "recorded",
+            reasonCode: requireTmwIdentifier(proposal.reasonCode, "compensation_reason_code"),
+        });
+        return Object.freeze({
+            ...image,
+            receiptDigest: requireTmwSha256(receiptDigest, "compensation_receipt_digest"),
+        });
+    }));
+}

package/dist/runtime-contract.d.ts

@@ -0,0 +1,56 @@
+export declare const TMW_RUNTIME_GENERATION: 3;
+export declare const TRIGGER_DOCUMENT_V3_VERSION: 3;
+export declare const TMW_COMPILED_PLAN_VERSION: 3;
+export declare const AUTHOR_SCENARIO_SOURCE_V3_SCHEMA_VERSION: 3;
+export declare const TMW_CONDITION_EXPRESSION_REVISION: 2;
+export declare const TMW_SEMANTIC_JUDGE_RECEIPT_REVISION: 2;
+export declare const TMW_SEMANTIC_CONFIDENCE_THRESHOLD_MILLIONTHS: 600000;
+export declare const TMW_NODE_ENABLEMENT_REVISION: 1;
+export declare const TMW_SCENE_SEMANTICS_REVISION: 1;
+export declare const TMW_VALUE_GRAPH_SEMANTICS_REVISION: 1;
+export declare const TMW_EVENT_LIFECYCLE_SEMANTICS_REVISION: 1;
+/** committed event 到 View SDK 的显式、仅下行投影合同。 */
+export declare const TMW_VIEW_EVENT_DELIVERY_SEMANTICS_REVISION: 1;
+/** Last deployed canonical contract before Scene became Runtime SAV authority. */
+export declare const TMW_PRE_SCENE_RUNTIME_CONTRACT_V3: Readonly<{
+    runtime_generation: 3;
+    trigger_document_version: 3;
+    compiled_plan_version: 3;
+    author_source_schema_version: 3;
+    condition_expression_revision: 2;
+    semantic_judge_receipt_revision: 2;
+    semantic_confidence_threshold_millionths: 600000;
+    node_enablement_revision: 1;
+    time_domains: readonly ["event", "condition", "effect", "presentation"];
+    rejection_codes: readonly ["content_epoch_required", "stale_content_epoch", "tmw3_required", "unsupported_runtime_generation", "unsupported_sav_generation", "sav_section_missing", "runtime_contract_hash_mismatch"];
+}>;
+export type TmwJsonPrimitive = null | boolean | number | string;
+export type TmwJsonValue = TmwJsonPrimitive | readonly TmwJsonValue[] | {
+    readonly [key: string]: TmwJsonValue;
+};
+export declare const TMW_RUNTIME_CONTRACT_V3: Readonly<{
+    runtime_generation: 3;
+    trigger_document_version: 3;
+    compiled_plan_version: 3;
+    author_source_schema_version: 3;
+    condition_expression_revision: 2;
+    semantic_judge_receipt_revision: 2;
+    semantic_confidence_threshold_millionths: 600000;
+    node_enablement_revision: 1;
+    scene_semantics_revision: 1;
+    gameplay_state_semantics_revision: 1;
+    value_graph_semantics_revision: 1;
+    event_lifecycle_semantics_revision: 1;
+    view_event_delivery_semantics_revision: 1;
+    value_graph_schema_version: 1;
+    time_domains: readonly ["event", "condition", "effect", "presentation"];
+    rejection_codes: readonly ["content_epoch_required", "stale_content_epoch", "tmw3_required", "unsupported_runtime_generation", "unsupported_sav_generation", "sav_section_missing", "runtime_contract_hash_mismatch"];
+}>;
+export type TmwRuntimeRejectionCode = typeof TMW_RUNTIME_CONTRACT_V3.rejection_codes[number];
+export declare function canonicalTmwJson(value: TmwJsonValue | object): string;
+export declare function canonicalTmwBytes(value: TmwJsonValue | object): Uint8Array;
+export declare function tmwSha256Hex(bytes: Uint8Array, subtle?: SubtleCrypto): Promise<string>;
+export declare function canonicalRuntimeContractV3Bytes(): Uint8Array;
+export declare function runtimeContractHashV3(subtle?: SubtleCrypto): Promise<string>;
+export declare function preSceneRuntimeContractHashV3(subtle?: SubtleCrypto): Promise<string>;
+export declare function isSha256Hex(value: unknown): value is string;

package/dist/runtime-contract.js

@@ -0,0 +1,96 @@
+export const TMW_RUNTIME_GENERATION = 3;
+export const TRIGGER_DOCUMENT_V3_VERSION = 3;
+export const TMW_COMPILED_PLAN_VERSION = 3;
+export const AUTHOR_SCENARIO_SOURCE_V3_SCHEMA_VERSION = 3;
+export const TMW_CONDITION_EXPRESSION_REVISION = 2;
+export const TMW_SEMANTIC_JUDGE_RECEIPT_REVISION = 2;
+export const TMW_SEMANTIC_CONFIDENCE_THRESHOLD_MILLIONTHS = 600_000;
+export const TMW_NODE_ENABLEMENT_REVISION = 1;
+export const TMW_SCENE_SEMANTICS_REVISION = 1;
+export const TMW_VALUE_GRAPH_SEMANTICS_REVISION = 1;
+export const TMW_EVENT_LIFECYCLE_SEMANTICS_REVISION = 1;
+/** committed event 到 View SDK 的显式、仅下行投影合同。 */
+export const TMW_VIEW_EVENT_DELIVERY_SEMANTICS_REVISION = 1;
+/** Last deployed canonical contract before Scene became Runtime SAV authority. */
+export const TMW_PRE_SCENE_RUNTIME_CONTRACT_V3 = Object.freeze({
+    runtime_generation: TMW_RUNTIME_GENERATION,
+    trigger_document_version: TRIGGER_DOCUMENT_V3_VERSION,
+    compiled_plan_version: TMW_COMPILED_PLAN_VERSION,
+    author_source_schema_version: AUTHOR_SCENARIO_SOURCE_V3_SCHEMA_VERSION,
+    condition_expression_revision: TMW_CONDITION_EXPRESSION_REVISION,
+    semantic_judge_receipt_revision: TMW_SEMANTIC_JUDGE_RECEIPT_REVISION,
+    semantic_confidence_threshold_millionths: TMW_SEMANTIC_CONFIDENCE_THRESHOLD_MILLIONTHS,
+    node_enablement_revision: TMW_NODE_ENABLEMENT_REVISION,
+    time_domains: Object.freeze(["event", "condition", "effect", "presentation"]),
+    rejection_codes: Object.freeze([
+        "content_epoch_required", "stale_content_epoch", "tmw3_required",
+        "unsupported_runtime_generation", "unsupported_sav_generation", "sav_section_missing",
+        "runtime_contract_hash_mismatch",
+    ]),
+});
+export const TMW_RUNTIME_CONTRACT_V3 = Object.freeze({
+    runtime_generation: TMW_RUNTIME_GENERATION,
+    trigger_document_version: TRIGGER_DOCUMENT_V3_VERSION,
+    compiled_plan_version: TMW_COMPILED_PLAN_VERSION,
+    author_source_schema_version: AUTHOR_SCENARIO_SOURCE_V3_SCHEMA_VERSION,
+    condition_expression_revision: TMW_CONDITION_EXPRESSION_REVISION,
+    semantic_judge_receipt_revision: TMW_SEMANTIC_JUDGE_RECEIPT_REVISION,
+    semantic_confidence_threshold_millionths: TMW_SEMANTIC_CONFIDENCE_THRESHOLD_MILLIONTHS,
+    node_enablement_revision: TMW_NODE_ENABLEMENT_REVISION,
+    scene_semantics_revision: TMW_SCENE_SEMANTICS_REVISION,
+    gameplay_state_semantics_revision: 1,
+    value_graph_semantics_revision: TMW_VALUE_GRAPH_SEMANTICS_REVISION,
+    event_lifecycle_semantics_revision: TMW_EVENT_LIFECYCLE_SEMANTICS_REVISION,
+    view_event_delivery_semantics_revision: TMW_VIEW_EVENT_DELIVERY_SEMANTICS_REVISION,
+    value_graph_schema_version: 1,
+    time_domains: Object.freeze(["event", "condition", "effect", "presentation"]),
+    rejection_codes: Object.freeze([
+        "content_epoch_required",
+        "stale_content_epoch",
+        "tmw3_required",
+        "unsupported_runtime_generation",
+        "unsupported_sav_generation",
+        "sav_section_missing",
+        "runtime_contract_hash_mismatch",
+    ]),
+});
+function canonicalValue(value, path) {
+    if (value === null || typeof value === "boolean" || typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new Error(`${path}: canonical_number_not_finite`);
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((item, index) => canonicalValue(item, `${path}/${index}`)).join(",")}]`;
+    }
+    if (typeof value !== "object" || value === null)
+        throw new Error(`${path}: canonical_value_invalid`);
+    const record = value;
+    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonicalValue(record[key], `${path}/${key}`)}`).join(",")}}`;
+}
+export function canonicalTmwJson(value) {
+    return canonicalValue(value, "$");
+}
+export function canonicalTmwBytes(value) {
+    return new TextEncoder().encode(canonicalTmwJson(value));
+}
+export async function tmwSha256Hex(bytes, subtle = globalThis.crypto.subtle) {
+    const digestInput = new Uint8Array(bytes.byteLength);
+    digestInput.set(bytes);
+    const digest = await subtle.digest("SHA-256", digestInput);
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+export function canonicalRuntimeContractV3Bytes() {
+    return canonicalTmwBytes(TMW_RUNTIME_CONTRACT_V3);
+}
+export async function runtimeContractHashV3(subtle) {
+    return tmwSha256Hex(canonicalRuntimeContractV3Bytes(), subtle);
+}
+export async function preSceneRuntimeContractHashV3(subtle) {
+    return tmwSha256Hex(canonicalTmwBytes(TMW_PRE_SCENE_RUNTIME_CONTRACT_V3), subtle);
+}
+export function isSha256Hex(value) {
+    return typeof value === "string" && /^[0-9a-f]{64}$/u.test(value);
+}

package/dist/runtime-domain-capabilities.d.ts

@@ -0,0 +1,12 @@
+import type { TmwClockDomain } from "./time-domains.js";
+export type TmwRuntimeCapabilityTarget = "production" | "simulation";
+export interface TmwRuntimeDomainCapability {
+    readonly target: TmwRuntimeCapabilityTarget;
+    readonly produced_clock_domains: readonly TmwClockDomain[];
+}
+/**
+ * TMW 时钟 producer 的单一 capability authority。
+ * production 不接受作者输入扩权；simulation 仅表示显式人工观察可用于预览。
+ */
+export declare function getTmwRuntimeDomainCapability(target: TmwRuntimeCapabilityTarget): TmwRuntimeDomainCapability;
+export declare function tmwRuntimeProducesClockDomain(target: TmwRuntimeCapabilityTarget, domain: TmwClockDomain): boolean;

package/dist/runtime-domain-capabilities.js

@@ -0,0 +1,20 @@
+const CAPABILITIES = Object.freeze({
+    production: Object.freeze({
+        target: "production",
+        produced_clock_domains: Object.freeze(["logical_seq", "world_time"]),
+    }),
+    simulation: Object.freeze({
+        target: "simulation",
+        produced_clock_domains: Object.freeze(["logical_seq", "world_time", "presentation_seq", "real_time"]),
+    }),
+});
+/**
+ * TMW 时钟 producer 的单一 capability authority。
+ * production 不接受作者输入扩权；simulation 仅表示显式人工观察可用于预览。
+ */
+export function getTmwRuntimeDomainCapability(target) {
+    return CAPABILITIES[target];
+}
+export function tmwRuntimeProducesClockDomain(target, domain) {
+    return getTmwRuntimeDomainCapability(target).produced_clock_domains.includes(domain);
+}

package/dist/runtime-sav.d.ts

@@ -0,0 +1,117 @@
+import { TMW_RUNTIME_GENERATION } from "./runtime-contract.js";
+import { type DurableIntentV3 } from "./durable-intent.js";
+import { type AudioPresentationProjectionV1 } from "./audio-presentation-projection.js";
+import { type TmwGameplayStateV1 } from "./gameplay-state.js";
+import { type SchedulerSnapshot } from "./scheduler.js";
+import { type TmwPendingSceneClockCrossingV1, type TmwSceneStateV1 } from "./scene-state.js";
+import { type TimelineRevisionV3 } from "./timeline-revision.js";
+import { type TmwJsonValue } from "./runtime-trace.js";
+export declare const TMW_RUNTIME_SAV_EXTENSION_ID: "tmw.runtime.v3";
+export declare const TMW_RUNTIME_SAV_SCHEMA_VERSION: 3;
+export declare const TMW_RUNTIME_SAV_CODEC = "application/vnd.world-engines.tmw-runtime-v3+json;canonical=1";
+/** Structural mirror of SaveGeneration.extension_sections; protobuf remains authoritative. */
+export interface RuntimeSavExtensionSectionV3 {
+    readonly extension_id: string;
+    readonly schema_version: number;
+    readonly payload: Uint8Array;
+    readonly codec: string;
+    readonly payload_sha256: Uint8Array;
+    readonly required: boolean;
+}
+export interface RuntimeSavBindingV3 {
+    readonly epoch: number;
+    readonly runtimeGeneration: typeof TMW_RUNTIME_GENERATION;
+    readonly runtimeContractHash: string;
+    readonly artifactDigest: string;
+    readonly sourceRevision: string;
+    readonly activeTimelineRevision: string;
+    readonly turnId: string;
+    readonly preActivationTerminalDigest: string;
+}
+export interface RuntimeSavRestoreScopeV3 {
+    readonly epoch: number;
+    readonly runtimeGeneration: typeof TMW_RUNTIME_GENERATION;
+    readonly runtimeContractHash: string;
+    readonly artifactDigest: string;
+    readonly sourceRevision: string;
+}
+export interface RuntimeSavPayloadV3 extends RuntimeSavBindingV3 {
+    readonly schemaVersion: 3;
+    readonly activeTimeline: TimelineRevisionV3;
+    readonly ledgerHead: string;
+    readonly eventLedger: TmwJsonValue;
+    readonly narrative: TmwJsonValue;
+    /** 玩法变量与实体状态随同 activation CAS 持久化；执行域变量不进入存档。 */
+    readonly gameplayState?: TmwGameplayStateV1;
+    readonly gameplayInitialState?: TmwGameplayStateV1;
+    /** Canonical transient scene authority. null means no active scene. */
+    readonly scene: TmwSceneStateV1 | null;
+    readonly pendingSceneClockCrossings: ReadonlyArray<TmwPendingSceneClockCrossingV1>;
+    readonly scheduler: SchedulerSnapshot;
+    readonly conditionState: TmwJsonValue;
+    readonly durableIntents: ReadonlyArray<DurableIntentV3>;
+    readonly presentationIntents: ReadonlyArray<TmwJsonValue>;
+    /** Optional for pre-Spec-017 saves; when present it is the committed plan/cue projection. */
+    readonly audioPresentation?: AudioPresentationProjectionV1 | null;
+    readonly semanticVerdictRefs: ReadonlyArray<string>;
+    readonly candidateSetRevisions: ReadonlyArray<string>;
+    readonly operationReceiptDigests: ReadonlyArray<string>;
+    /** Durable operation guard. Optional only for decoding pre-clock Runtime3 saves. */
+    readonly completedOperationIds?: ReadonlyArray<string>;
+    /** Exact WASM operations whose finalized readback must survive an activation/finalize crash. */
+    readonly worldMutationRecoveryOperations: ReadonlyArray<TmwJsonValue>;
+}
+export declare function canonicalRuntimeSavPayload(input: RuntimeSavPayloadV3): RuntimeSavPayloadV3;
+export declare function runtimeSavSectionDigest(section: RuntimeSavExtensionSectionV3): Promise<string>;
+export declare function runtimeSavPayloadDigest(input: RuntimeSavPayloadV3): Promise<string>;
+export interface PreSceneRuntimeSavMigrationAuthorityV1 {
+    readonly expectedLegacyArtifactDigest: string;
+    readonly successorRuntimeContractHash: string;
+    readonly successorArtifactDigest: string;
+    readonly sceneId: string;
+    readonly presentEntityNodeIds: ReadonlyArray<string>;
+    readonly spatialRef: TmwSceneStateV1["spatialRef"];
+    readonly operationId: string;
+    readonly turnId: string;
+}
+/**
+ * Server-issued, immutable publication relation for the one explicit pre-Scene
+ * SAV upgrade.  This is deliberately an identity record, not a hint carried by
+ * a SAV: callers must obtain it from the finalized-publication resolver.
+ */
+export interface PreSceneRuntimeSavPublishedMigrationV1 {
+    readonly schemaVersion: 1;
+    readonly scenarioId: string;
+    readonly predecessor: Readonly<{
+        readonly contentEpoch: number;
+        readonly reviewedHeadDigest: string;
+        readonly runtimeContractHash: string;
+        readonly artifactDigest: string;
+        readonly sourceRevision: string;
+    }>;
+    readonly successor: Readonly<{
+        readonly contentEpoch: number;
+        readonly reviewedHeadDigest: string;
+        readonly runtimeContractHash: string;
+        readonly artifactDigest: string;
+        readonly sourceRevision: string;
+        readonly compiledPlanSha256: string;
+    }>;
+}
+/** Fail closed on a replay, cross-scenario, source, epoch, or plan identity drift. */
+export declare function canonicalPreSceneRuntimeSavPublishedMigrationV1(input: PreSceneRuntimeSavPublishedMigrationV1): PreSceneRuntimeSavPublishedMigrationV1;
+export interface PreSceneRuntimeSavMigrationReceiptV1 {
+    readonly legacyPayloadDigest: string;
+    readonly successorPayloadDigest: string;
+    readonly payload: RuntimeSavPayloadV3;
+}
+/** Explicit pre-Scene migration; normal decoders never synthesize Scene from a malformed field. */
+export declare function migratePreSceneRuntimeSavV3(legacyInput: Omit<RuntimeSavPayloadV3, "scene" | "pendingSceneClockCrossings"> & Readonly<{
+    scene?: never;
+}>, authority: PreSceneRuntimeSavMigrationAuthorityV1): Promise<PreSceneRuntimeSavMigrationReceiptV1>;
+export declare function encodeRuntimeSavSection(input: RuntimeSavPayloadV3): Promise<RuntimeSavExtensionSectionV3>;
+export declare function decodeRuntimeSavSection(section: RuntimeSavExtensionSectionV3, expected: RuntimeSavBindingV3): Promise<RuntimeSavPayloadV3>;
+export declare function decodeRuntimeSavSectionForScope(section: RuntimeSavExtensionSectionV3, expected: RuntimeSavRestoreScopeV3): Promise<RuntimeSavPayloadV3>;
+export declare function decodeRuntimeSavSectionSelfBound(section: RuntimeSavExtensionSectionV3): Promise<RuntimeSavPayloadV3>;
+export declare function requireRuntimeSavSection(sections: ReadonlyArray<RuntimeSavExtensionSectionV3>, expected: RuntimeSavBindingV3): Promise<RuntimeSavPayloadV3>;
+export declare function requireRuntimeSavSectionForScope(sections: ReadonlyArray<RuntimeSavExtensionSectionV3>, expected: RuntimeSavRestoreScopeV3): Promise<RuntimeSavPayloadV3>;