@auraindustry/aurajs 0.0.2 → 0.0.4

package/src/game-state-runtime.mjs

@@ -0,0 +1,1067 @@
+import { createHash } from 'node:crypto';
+
+export const GAME_STATE_SCHEMA_VERSION = 'aurajs.game-state.v1';
+
+const CANONICAL_TOP_LEVEL_ORDER = ['schemaVersion', 'export', 'state'];
+const CANONICAL_EXPORT_ORDER = ['mode', 'seed', 'frameIndex', 'elapsedSeconds', 'fingerprint', 'capturedAt'];
+const CANONICAL_STATE_SECTION_ORDER = ['globals', 'camera', 'scene3d', 'physics', 'ecs', 'tilemap'];
+const SUPPORTED_TOP_LEVEL_KEYS = new Set(CANONICAL_TOP_LEVEL_ORDER);
+const SUPPORTED_STATE_SECTION_KEYS = new Set(CANONICAL_STATE_SECTION_ORDER);
+const SUPPORTED_PATCH_MUTATION_OPS = new Set(['set', 'delete']);
+const DEFAULT_MUTATION_MAX_OPS = 128;
+const DEFAULT_MUTATION_MAX_BYTES = 262144;
+const DEFAULT_MUTATION_MAX_RUNTIME_MS = 200;
+
+export const STATE_MUTATION_ALLOWLIST_PREFIXES = Object.freeze([
+  '/state/globals',
+  '/state/camera',
+  '/state/scene3d',
+  '/state/physics',
+  '/state/ecs',
+  '/state/tilemap',
+]);
+
+export const DEFAULT_STATE_MUTATION_GUARDRAILS = Object.freeze({
+  maxMutations: DEFAULT_MUTATION_MAX_OPS,
+  maxPayloadBytes: DEFAULT_MUTATION_MAX_BYTES,
+  maxRuntimeMs: DEFAULT_MUTATION_MAX_RUNTIME_MS,
+  allowlistPrefixes: STATE_MUTATION_ALLOWLIST_PREFIXES,
+});
+
+export function createGameStateRuntimeHooks({ aura, mode = 'native' } = {}) {
+  if (!aura || typeof aura !== 'object') {
+    throw new Error('createGameStateRuntimeHooks requires an aura runtime object.');
+  }
+
+  return {
+    exportState(options = {}) {
+      return exportCanonicalGameState(aura, { ...options, mode: options.mode || mode });
+    },
+    applyState(payload, options = {}) {
+      return applyCanonicalGameState(aura, payload, options);
+    },
+    diffState(beforePayload, afterPayload) {
+      return diffCanonicalGameState(beforePayload, afterPayload);
+    },
+    patchState(payload, patchPayload, options = {}) {
+      return applyCanonicalStatePatch(payload, patchPayload, options);
+    },
+  };
+}
+
+export function exportCanonicalGameState(aura, options = {}) {
+  const normalizedMode = normalizeMode(options.mode);
+  const seed = normalizeInt(options.seed, 0);
+  const frameIndex = normalizeInt(options.frameIndex, 0);
+  const elapsedSeconds = normalizeElapsedSeconds(options.elapsedSeconds, aura);
+  const capturedAt = normalizeCapturedAt(options.capturedAt);
+
+  const state = collectStateSections(aura);
+  const fingerprint = sha256(stableStringify(state));
+
+  const payload = {
+    schemaVersion: GAME_STATE_SCHEMA_VERSION,
+    export: {
+      mode: normalizedMode,
+      seed,
+      frameIndex,
+      elapsedSeconds,
+      fingerprint,
+      capturedAt,
+    },
+    state,
+  };
+
+  return {
+    ok: true,
+    reasonCode: 'state_export_ok',
+    payload: orderPayload(payload),
+  };
+}
+
+export function applyCanonicalGameState(aura, payload, _options = {}) {
+  const validated = validateApplyPayload(payload);
+  if (!validated.ok) {
+    return validated;
+  }
+
+  const state = validated.state;
+  const unsupportedSections = [];
+
+  for (const sectionName of Object.keys(state)) {
+    if (sectionName === 'globals' || sectionName === 'camera') continue;
+    const handler = resolveSectionApplyHandler(aura, sectionName);
+    if (!handler) {
+      unsupportedSections.push(sectionName);
+    }
+  }
+
+  if (unsupportedSections.length > 0) {
+    return {
+      ok: false,
+      reasonCode: 'unsupported_state_section',
+      unsupportedSections: unsupportedSections.sort(),
+    };
+  }
+
+  const appliedSections = [];
+  for (const sectionName of CANONICAL_STATE_SECTION_ORDER) {
+    if (!Object.prototype.hasOwnProperty.call(state, sectionName)) continue;
+    const sectionValue = state[sectionName];
+    const result = applyStateSection(aura, sectionName, sectionValue);
+    if (!result.ok) {
+      return {
+        ok: false,
+        reasonCode: result.reasonCode || 'state_apply_failed',
+        failedSection: sectionName,
+        detail: result.detail || null,
+        appliedSections,
+      };
+    }
+    appliedSections.push(sectionName);
+  }
+
+  return {
+    ok: true,
+    reasonCode: 'state_apply_ok',
+    appliedSections,
+  };
+}
+
+export function diffCanonicalGameState(beforePayload, afterPayload) {
+  const beforeValidated = validateApplyPayload(beforePayload);
+  if (!beforeValidated.ok) {
+    return beforeValidated;
+  }
+  const afterValidated = validateApplyPayload(afterPayload);
+  if (!afterValidated.ok) {
+    return afterValidated;
+  }
+
+  const mutations = [];
+  collectDiffMutations('/state', beforeValidated.state, afterValidated.state, mutations);
+  const orderedMutations = mutations.map((mutation, index) => ({
+    order: (index + 1) * 10,
+    ...mutation,
+  }));
+
+  return {
+    ok: true,
+    reasonCode: 'state_diff_ok',
+    patch: {
+      schemaVersion: GAME_STATE_SCHEMA_VERSION,
+      baseFingerprint: resolveStateFingerprint(beforePayload, beforeValidated.state),
+      mutations: orderedMutations,
+    },
+  };
+}
+
+export function applyCanonicalStatePatch(payload, patchPayload, options = {}) {
+  const guardrails = normalizeMutationGuardrails(options);
+
+  const payloadBytes = jsonByteSize(payload);
+  const patchBytes = jsonByteSize(patchPayload);
+  if (payloadBytes > guardrails.maxPayloadBytes || patchBytes > guardrails.maxPayloadBytes) {
+    return {
+      ok: false,
+      reasonCode: 'state_payload_too_large',
+      detail: `payload bytes exceed maxPayloadBytes=${guardrails.maxPayloadBytes}`,
+      payloadBytes,
+      patchBytes,
+      maxPayloadBytes: guardrails.maxPayloadBytes,
+    };
+  }
+
+  const validatedPayload = validateApplyPayload(payload);
+  if (!validatedPayload.ok) {
+    return validatedPayload;
+  }
+
+  const validatedPatch = validatePatchPayload(patchPayload, guardrails);
+  if (!validatedPatch.ok) {
+    return validatedPatch;
+  }
+
+  const orderedPayload = orderPayload({
+    schemaVersion: GAME_STATE_SCHEMA_VERSION,
+    export: sanitizeExportPayload(payload.export),
+    state: validatedPayload.state,
+  });
+  const fingerprint = resolveStateFingerprint(orderedPayload, orderedPayload.state);
+  if (validatedPatch.baseFingerprint !== fingerprint) {
+    return {
+      ok: false,
+      reasonCode: 'mutation_conflict',
+      detail: 'Patch baseFingerprint does not match source payload.',
+      expectedFingerprint: fingerprint,
+      actualFingerprint: validatedPatch.baseFingerprint,
+    };
+  }
+
+  const working = cloneJson(orderedPayload);
+  const startedAt = Date.now();
+
+  for (let i = 0; i < validatedPatch.mutations.length; i += 1) {
+    if ((Date.now() - startedAt) >= guardrails.maxRuntimeMs) {
+      return {
+        ok: false,
+        reasonCode: 'state_apply_timeout',
+        detail: `patch apply exceeded maxRuntimeMs=${guardrails.maxRuntimeMs}`,
+        maxRuntimeMs: guardrails.maxRuntimeMs,
+        failedMutationIndex: i,
+      };
+    }
+    const mutation = validatedPatch.mutations[i];
+    const applyResult = applySinglePatchMutation(working, mutation);
+    if (!applyResult.ok) {
+      return {
+        ok: false,
+        reasonCode: applyResult.reasonCode,
+        detail: applyResult.detail || null,
+        failedMutationIndex: i,
+      };
+    }
+  }
+
+  const postValidate = validateApplyPayload(working);
+  if (!postValidate.ok) {
+    return postValidate;
+  }
+  working.state = postValidate.state;
+  working.export.fingerprint = sha256(stableStringify(working.state));
+
+  return {
+    ok: true,
+    reasonCode: 'state_patch_ok',
+    appliedMutations: validatedPatch.mutations.length,
+    maxRuntimeMs: guardrails.maxRuntimeMs,
+    payload: orderPayload(working),
+  };
+}
+
+function validateApplyPayload(payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    return { ok: false, reasonCode: 'invalid_schema_payload', detail: 'payload must be an object' };
+  }
+
+  if (payload.schemaVersion !== GAME_STATE_SCHEMA_VERSION) {
+    return {
+      ok: false,
+      reasonCode: 'schema_version_mismatch',
+      detail: `expected ${GAME_STATE_SCHEMA_VERSION}`,
+    };
+  }
+
+  const topLevelKeys = Object.keys(payload);
+  const unknownTopLevel = topLevelKeys.filter((key) => !SUPPORTED_TOP_LEVEL_KEYS.has(key));
+  if (unknownTopLevel.length > 0) {
+    return {
+      ok: false,
+      reasonCode: 'unknown_top_level_key',
+      unknownKeys: unknownTopLevel.sort(),
+    };
+  }
+
+  if (!payload.state || typeof payload.state !== 'object' || Array.isArray(payload.state)) {
+    return { ok: false, reasonCode: 'invalid_schema_payload', detail: 'state must be an object' };
+  }
+  if (!payload.export || typeof payload.export !== 'object' || Array.isArray(payload.export)) {
+    return { ok: false, reasonCode: 'invalid_schema_payload', detail: 'export must be an object' };
+  }
+  if (!payload.state.globals || typeof payload.state.globals !== 'object' || Array.isArray(payload.state.globals)) {
+    return { ok: false, reasonCode: 'missing_required_field', detail: 'state.globals is required' };
+  }
+
+  const stateKeys = Object.keys(payload.state);
+  const unknownStateSections = stateKeys.filter((key) => !SUPPORTED_STATE_SECTION_KEYS.has(key));
+  if (unknownStateSections.length > 0) {
+    return {
+      ok: false,
+      reasonCode: 'unknown_state_section',
+      unknownSections: unknownStateSections.sort(),
+    };
+  }
+
+  return {
+    ok: true,
+    state: collectCanonicalStateFromPayload(payload.state),
+  };
+}
+
+function applyStateSection(aura, sectionName, sectionValue) {
+  if (sectionName === 'globals') {
+    return applyGlobalsSection(aura, sectionValue);
+  }
+  if (sectionName === 'camera') {
+    return applyCameraSection(aura, sectionValue);
+  }
+
+  const handler = resolveSectionApplyHandler(aura, sectionName);
+  if (!handler) {
+    return { ok: false, reasonCode: 'unsupported_state_section' };
+  }
+
+  try {
+    const result = handler(sectionValue);
+    if (result === false) {
+      return { ok: false, reasonCode: 'state_apply_failed' };
+    }
+    if (result && typeof result === 'object' && result.ok === false) {
+      return {
+        ok: false,
+        reasonCode: typeof result.reasonCode === 'string' ? result.reasonCode : 'state_apply_failed',
+        detail: result.detail || result.error || null,
+      };
+    }
+    return { ok: true, reasonCode: 'state_apply_ok' };
+  } catch (error) {
+    return {
+      ok: false,
+      reasonCode: 'state_apply_failed',
+      detail: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+function applyGlobalsSection(aura, sectionValue) {
+  if (!sectionValue || typeof sectionValue !== 'object' || Array.isArray(sectionValue)) {
+    return { ok: false, reasonCode: 'invalid_state_section', detail: 'globals must be an object' };
+  }
+
+  const globalsMap = resolveGlobalsMap(aura);
+  globalsMap.clear();
+
+  const normalized = sanitizeObject(sectionValue);
+  for (const [key, value] of Object.entries(normalized)) {
+    globalsMap.set(key, value);
+  }
+
+  const storage = aura.storage && typeof aura.storage === 'object' ? aura.storage : null;
+  if (storage && typeof storage.set === 'function') {
+    for (const [key, value] of globalsMap.entries()) {
+      storage.set(key, value);
+    }
+  }
+
+  return { ok: true, reasonCode: 'state_apply_ok' };
+}
+
+function applyCameraSection(aura, sectionValue) {
+  if (!sectionValue || typeof sectionValue !== 'object' || Array.isArray(sectionValue)) {
+    return { ok: false, reasonCode: 'invalid_state_section', detail: 'camera must be an object' };
+  }
+  if (!aura.camera || typeof aura.camera !== 'object') {
+    return { ok: false, reasonCode: 'unsupported_state_section', detail: 'camera surface unavailable' };
+  }
+
+  const camera = aura.camera;
+  const nextX = sectionValue.x;
+  const nextY = sectionValue.y;
+  const nextZoom = sectionValue.zoom;
+  const nextRotation = sectionValue.rotation;
+
+  if (nextX != null && !Number.isFinite(nextX)) {
+    return { ok: false, reasonCode: 'invalid_state_section', detail: 'camera.x must be finite' };
+  }
+  if (nextY != null && !Number.isFinite(nextY)) {
+    return { ok: false, reasonCode: 'invalid_state_section', detail: 'camera.y must be finite' };
+  }
+  if (nextZoom != null && (!Number.isFinite(nextZoom) || nextZoom <= 0)) {
+    return { ok: false, reasonCode: 'invalid_state_section', detail: 'camera.zoom must be > 0' };
+  }
+  if (nextRotation != null && !Number.isFinite(nextRotation)) {
+    return { ok: false, reasonCode: 'invalid_state_section', detail: 'camera.rotation must be finite' };
+  }
+
+  if (nextX != null) camera.x = Number(nextX);
+  if (nextY != null) camera.y = Number(nextY);
+  if (nextZoom != null) camera.zoom = Number(nextZoom);
+  if (nextRotation != null) camera.rotation = Number(nextRotation);
+
+  return { ok: true, reasonCode: 'state_apply_ok' };
+}
+
+function resolveSectionApplyHandler(aura, sectionName) {
+  const section = aura[sectionName];
+  if (!section || typeof section !== 'object') {
+    return null;
+  }
+  if (typeof section.applyState === 'function') {
+    return (value) => section.applyState(value);
+  }
+  if (typeof section.importState === 'function') {
+    return (value) => section.importState(value);
+  }
+  if (sectionName === 'physics' && typeof section.restoreSnapshot === 'function') {
+    return (value) => section.restoreSnapshot(value);
+  }
+  return null;
+}
+
+function collectStateSections(aura) {
+  const globals = mapToObject(resolveGlobalsMap(aura));
+  const camera = collectCameraSnapshot(aura);
+
+  const raw = {
+    globals,
+    camera,
+    scene3d: collectObjectSection(aura.scene3d),
+    physics: collectObjectSection(aura.physics),
+    ecs: collectObjectSection(aura.ecs),
+    tilemap: collectObjectSection(aura.tilemap),
+  };
+
+  return collectCanonicalStateFromPayload(raw);
+}
+
+function collectCanonicalStateFromPayload(inputState) {
+  const out = {};
+
+  const globals = sanitizeObject(inputState.globals || {});
+  out.globals = globals;
+
+  for (const sectionName of CANONICAL_STATE_SECTION_ORDER) {
+    if (sectionName === 'globals') continue;
+    if (!Object.prototype.hasOwnProperty.call(inputState, sectionName)) continue;
+    const value = sanitizeJsonValue(inputState[sectionName]);
+    if (value == null) continue;
+    out[sectionName] = value;
+  }
+
+  return out;
+}
+
+function collectCameraSnapshot(aura) {
+  if (!aura.camera || typeof aura.camera !== 'object') {
+    return null;
+  }
+
+  let source = null;
+  if (typeof aura.camera.getState === 'function') {
+    try {
+      source = aura.camera.getState();
+    } catch {
+      source = null;
+    }
+  }
+
+  if (!source || typeof source !== 'object') {
+    source = {
+      x: aura.camera.x,
+      y: aura.camera.y,
+      zoom: aura.camera.zoom,
+      rotation: aura.camera.rotation,
+    };
+  }
+
+  if (!source || typeof source !== 'object') {
+    return null;
+  }
+
+  const camera = {};
+  if (Number.isFinite(source.x)) camera.x = Number(source.x);
+  if (Number.isFinite(source.y)) camera.y = Number(source.y);
+  if (Number.isFinite(source.zoom) && source.zoom > 0) camera.zoom = Number(source.zoom);
+  if (Number.isFinite(source.rotation)) camera.rotation = Number(source.rotation);
+  if (typeof source.following === 'boolean') camera.following = source.following;
+  if (Number.isInteger(source.activeEffects) && source.activeEffects >= 0) {
+    camera.activeEffects = Number(source.activeEffects);
+  }
+
+  return Object.keys(camera).length > 0 ? camera : null;
+}
+
+function collectObjectSection(section) {
+  if (!section || typeof section !== 'object') {
+    return null;
+  }
+  if (typeof section.getState === 'function') {
+    try {
+      const state = section.getState();
+      if (state && typeof state === 'object') {
+        return state;
+      }
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+function resolveGlobalsMap(aura) {
+  const storage = aura.storage && typeof aura.storage === 'object' ? aura.storage : null;
+  if (storage && storage._store instanceof Map) {
+    return storage._store;
+  }
+  if (aura.__gameStateGlobals instanceof Map) {
+    return aura.__gameStateGlobals;
+  }
+  aura.__gameStateGlobals = new Map();
+  return aura.__gameStateGlobals;
+}
+
+function mapToObject(map) {
+  const out = {};
+  const rows = [...map.entries()].map(([key, value]) => [String(key), sanitizeJsonValue(value)]);
+  rows.sort((a, b) => a[0].localeCompare(b[0]));
+  for (const [key, value] of rows) {
+    out[key] = value;
+  }
+  return out;
+}
+
+function sanitizeObject(value) {
+  const out = {};
+  const source = value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+  const keys = Object.keys(source).sort((a, b) => a.localeCompare(b));
+  for (const key of keys) {
+    const next = sanitizeJsonValue(source[key]);
+    if (next === undefined) continue;
+    out[key] = next;
+  }
+  return out;
+}
+
+function sanitizeJsonValue(value) {
+  if (value === null) return null;
+  if (typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? Number(value) : null;
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => sanitizeJsonValue(entry));
+  }
+  if (value && typeof value === 'object') {
+    return sanitizeObject(value);
+  }
+  return null;
+}
+
+function collectDiffMutations(path, beforeValue, afterValue, mutations) {
+  if (isDeepEqual(beforeValue, afterValue)) {
+    return;
+  }
+
+  const beforeIsObject = isPlainObject(beforeValue);
+  const afterIsObject = isPlainObject(afterValue);
+  if (beforeIsObject && afterIsObject) {
+    const beforeKeys = Object.keys(beforeValue).sort((a, b) => a.localeCompare(b));
+    const afterKeys = Object.keys(afterValue).sort((a, b) => a.localeCompare(b));
+    const afterKeySet = new Set(afterKeys);
+    const beforeKeySet = new Set(beforeKeys);
+
+    for (const key of beforeKeys) {
+      if (afterKeySet.has(key)) continue;
+      mutations.push({
+        op: 'delete',
+        path: `${path}/${escapeJsonPointerToken(key)}`,
+      });
+    }
+
+    for (const key of afterKeys) {
+      const nextPath = `${path}/${escapeJsonPointerToken(key)}`;
+      if (!beforeKeySet.has(key)) {
+        mutations.push({
+          op: 'set',
+          path: nextPath,
+          value: sanitizeJsonValue(afterValue[key]),
+        });
+        continue;
+      }
+      collectDiffMutations(nextPath, beforeValue[key], afterValue[key], mutations);
+    }
+    return;
+  }
+
+  if (Array.isArray(beforeValue) && Array.isArray(afterValue)) {
+    mutations.push({
+      op: 'set',
+      path,
+      value: sanitizeJsonValue(afterValue),
+    });
+    return;
+  }
+
+  mutations.push({
+    op: 'set',
+    path,
+    value: sanitizeJsonValue(afterValue),
+  });
+}
+
+function validatePatchPayload(patchPayload, guardrails) {
+  if (!patchPayload || typeof patchPayload !== 'object' || Array.isArray(patchPayload)) {
+    return { ok: false, reasonCode: 'invalid_schema_payload', detail: 'patch payload must be an object' };
+  }
+  if (patchPayload.schemaVersion !== GAME_STATE_SCHEMA_VERSION) {
+    return {
+      ok: false,
+      reasonCode: 'schema_version_mismatch',
+      detail: `expected ${GAME_STATE_SCHEMA_VERSION}`,
+    };
+  }
+
+  const baseFingerprint = typeof patchPayload.baseFingerprint === 'string'
+    ? patchPayload.baseFingerprint.trim()
+    : '';
+  if (!/^[a-f0-9]{64}$/.test(baseFingerprint)) {
+    return {
+      ok: false,
+      reasonCode: 'invalid_schema_payload',
+      detail: 'baseFingerprint must be a lowercase 64-char sha256 hex string',
+    };
+  }
+
+  if (!Array.isArray(patchPayload.mutations)) {
+    return {
+      ok: false,
+      reasonCode: 'missing_required_field',
+      detail: 'mutations must be an array',
+    };
+  }
+  if (patchPayload.mutations.length > guardrails.maxMutations) {
+    return {
+      ok: false,
+      reasonCode: 'mutation_budget_exceeded',
+      detail: `mutation count ${patchPayload.mutations.length} exceeds maxMutations=${guardrails.maxMutations}`,
+      mutationCount: patchPayload.mutations.length,
+      maxMutations: guardrails.maxMutations,
+    };
+  }
+
+  const normalizedMutations = [];
+  for (let i = 0; i < patchPayload.mutations.length; i += 1) {
+    const raw = patchPayload.mutations[i];
+    const normalized = normalizePatchMutation(raw, i, guardrails);
+    if (!normalized.ok) {
+      return normalized;
+    }
+    normalizedMutations.push(normalized.mutation);
+  }
+
+  normalizedMutations.sort((a, b) => {
+    if (a.order !== b.order) return a.order - b.order;
+    return a.originalIndex - b.originalIndex;
+  });
+
+  return {
+    ok: true,
+    baseFingerprint,
+    mutations: normalizedMutations,
+  };
+}
+
+function normalizePatchMutation(rawMutation, index, guardrails) {
+  if (!rawMutation || typeof rawMutation !== 'object' || Array.isArray(rawMutation)) {
+    return {
+      ok: false,
+      reasonCode: 'invalid_schema_payload',
+      detail: `mutation at index ${index} must be an object`,
+    };
+  }
+
+  const order = Number(rawMutation.order);
+  if (!Number.isInteger(order) || order < 0) {
+    return {
+      ok: false,
+      reasonCode: 'invalid_schema_payload',
+      detail: `mutation at index ${index} has invalid order`,
+    };
+  }
+
+  const op = typeof rawMutation.op === 'string' ? rawMutation.op : '';
+  if (!SUPPORTED_PATCH_MUTATION_OPS.has(op)) {
+    return {
+      ok: false,
+      reasonCode: 'unsupported_mutation_op',
+      detail: `mutation at index ${index} uses unsupported op "${op}"`,
+    };
+  }
+
+  const path = typeof rawMutation.path === 'string' ? rawMutation.path : '';
+  const tokens = parseJsonPointer(path);
+  if (!tokens) {
+    return {
+      ok: false,
+      reasonCode: 'invalid_json_pointer',
+      detail: `mutation at index ${index} has invalid path`,
+    };
+  }
+  const allowlistCheck = validateMutationPathAgainstGuards(tokens, path, index, guardrails);
+  if (!allowlistCheck.ok) {
+    return allowlistCheck;
+  }
+
+  const mutation = {
+    order,
+    op,
+    path,
+    originalIndex: index,
+  };
+
+  if (op === 'set') {
+    if (!Object.prototype.hasOwnProperty.call(rawMutation, 'value')) {
+      return {
+        ok: false,
+        reasonCode: 'missing_required_field',
+        detail: `mutation at index ${index} requires value for op=set`,
+      };
+    }
+    mutation.value = sanitizeJsonValue(rawMutation.value);
+  }
+
+  return { ok: true, mutation };
+}
+
+function validateMutationPathAgainstGuards(tokens, path, index, guardrails) {
+  if (tokens.length === 0 || tokens[0] !== 'state') {
+    return {
+      ok: false,
+      reasonCode: 'immutable_path',
+      detail: `mutation at index ${index} targets immutable path "${path}"`,
+    };
+  }
+  if (tokens.length < 2) {
+    return {
+      ok: false,
+      reasonCode: 'immutable_path',
+      detail: `mutation at index ${index} targets immutable path "${path}"`,
+    };
+  }
+
+  const normalizedPrefix = `/${escapeJsonPointerToken(tokens[0])}/${escapeJsonPointerToken(tokens[1])}`;
+  if (!guardrails.allowlistPrefixSet.has(normalizedPrefix)) {
+    return {
+      ok: false,
+      reasonCode: 'mutation_path_not_allowed',
+      detail: `mutation at index ${index} targets non-allowlisted path "${path}"`,
+      allowlistPrefixes: guardrails.allowlistPrefixes,
+    };
+  }
+
+  return { ok: true };
+}
+
+function applySinglePatchMutation(payload, mutation) {
+  const tokens = parseJsonPointer(mutation.path);
+  if (!tokens) {
+    return { ok: false, reasonCode: 'invalid_json_pointer' };
+  }
+  if (tokens.length === 0 || tokens[0] !== 'state') {
+    return { ok: false, reasonCode: 'immutable_path' };
+  }
+  if (mutation.op === 'delete' && (tokens.length === 1 || (tokens.length === 2 && tokens[1] === 'globals'))) {
+    return { ok: false, reasonCode: 'immutable_path' };
+  }
+
+  const target = resolvePointerTarget(payload, tokens);
+  if (!target.ok) {
+    return target;
+  }
+
+  if (mutation.op === 'set') {
+    return applySetMutation(target.parent, target.key, mutation.value);
+  }
+
+  if (mutation.op === 'delete') {
+    return applyDeleteMutation(target.parent, target.key);
+  }
+
+  return { ok: false, reasonCode: 'unsupported_mutation_op' };
+}
+
+function resolvePointerTarget(root, tokens) {
+  let cursor = root;
+  for (let i = 0; i < tokens.length - 1; i += 1) {
+    const token = tokens[i];
+    if (Array.isArray(cursor)) {
+      const index = parseArrayIndexToken(token);
+      if (index === null) return { ok: false, reasonCode: 'type_mismatch' };
+      if (index < 0 || index >= cursor.length) return { ok: false, reasonCode: 'path_not_found' };
+      cursor = cursor[index];
+      continue;
+    }
+    if (!isPlainObject(cursor)) {
+      return { ok: false, reasonCode: 'type_mismatch' };
+    }
+    if (!Object.prototype.hasOwnProperty.call(cursor, token)) {
+      return { ok: false, reasonCode: 'path_not_found' };
+    }
+    cursor = cursor[token];
+  }
+  return {
+    ok: true,
+    parent: cursor,
+    key: tokens[tokens.length - 1],
+  };
+}
+
+function applySetMutation(parent, key, value) {
+  if (Array.isArray(parent)) {
+    const index = parseArrayIndexToken(key);
+    if (index === null) return { ok: false, reasonCode: 'type_mismatch' };
+    if (index < 0 || index >= parent.length) return { ok: false, reasonCode: 'out_of_bounds' };
+    parent[index] = sanitizeJsonValue(value);
+    return { ok: true };
+  }
+
+  if (!isPlainObject(parent)) {
+    return { ok: false, reasonCode: 'type_mismatch' };
+  }
+  parent[key] = sanitizeJsonValue(value);
+  return { ok: true };
+}
+
+function applyDeleteMutation(parent, key) {
+  if (Array.isArray(parent)) {
+    const index = parseArrayIndexToken(key);
+    if (index === null) return { ok: false, reasonCode: 'type_mismatch' };
+    if (index < 0 || index >= parent.length) return { ok: false, reasonCode: 'out_of_bounds' };
+    parent.splice(index, 1);
+    return { ok: true };
+  }
+
+  if (!isPlainObject(parent)) {
+    return { ok: false, reasonCode: 'type_mismatch' };
+  }
+  if (!Object.prototype.hasOwnProperty.call(parent, key)) {
+    return { ok: false, reasonCode: 'path_not_found' };
+  }
+  delete parent[key];
+  return { ok: true };
+}
+
+function parseJsonPointer(path) {
+  if (typeof path !== 'string' || path.length === 0 || path[0] !== '/') {
+    return null;
+  }
+  const rawTokens = path.slice(1).split('/');
+  const tokens = [];
+  for (const token of rawTokens) {
+    if (/~(?![01])/u.test(token)) {
+      return null;
+    }
+    tokens.push(token.replace(/~1/g, '/').replace(/~0/g, '~'));
+  }
+  return tokens;
+}
+
+function parseArrayIndexToken(token) {
+  if (!/^(0|[1-9][0-9]*)$/u.test(token)) {
+    return null;
+  }
+  return Number(token);
+}
+
+function escapeJsonPointerToken(token) {
+  return String(token).replace(/~/g, '~0').replace(/\//g, '~1');
+}
+
+function sanitizeExportPayload(value) {
+  const source = isPlainObject(value) ? value : {};
+  const out = {};
+  for (const key of CANONICAL_EXPORT_ORDER) {
+    if (!Object.prototype.hasOwnProperty.call(source, key)) continue;
+    if (key === 'mode') {
+      out.mode = normalizeMode(source.mode);
+      continue;
+    }
+    if (key === 'seed' || key === 'frameIndex') {
+      out[key] = normalizeInt(source[key], 0);
+      continue;
+    }
+    if (key === 'elapsedSeconds') {
+      out.elapsedSeconds = Number.isFinite(source.elapsedSeconds) && source.elapsedSeconds >= 0
+        ? Number(source.elapsedSeconds)
+        : null;
+      continue;
+    }
+    if (key === 'fingerprint') {
+      out.fingerprint = typeof source.fingerprint === 'string' ? source.fingerprint : '';
+      continue;
+    }
+    if (key === 'capturedAt') {
+      out.capturedAt = normalizeCapturedAt(source.capturedAt);
+    }
+  }
+  if (!Object.prototype.hasOwnProperty.call(out, 'mode')) out.mode = 'native';
+  if (!Object.prototype.hasOwnProperty.call(out, 'seed')) out.seed = 0;
+  if (!Object.prototype.hasOwnProperty.call(out, 'frameIndex')) out.frameIndex = 0;
+  if (!Object.prototype.hasOwnProperty.call(out, 'elapsedSeconds')) out.elapsedSeconds = null;
+  if (!Object.prototype.hasOwnProperty.call(out, 'capturedAt')) out.capturedAt = null;
+  return out;
+}
+
+function resolveStateFingerprint(payload, canonicalState) {
+  const fingerprint = payload?.export?.fingerprint;
+  if (typeof fingerprint === 'string' && /^[a-f0-9]{64}$/.test(fingerprint)) {
+    return fingerprint;
+  }
+  return sha256(stableStringify(canonicalState));
+}
+
+function normalizeMutationGuardrails(options) {
+  const source = options && typeof options === 'object' ? options : {};
+  const maxMutations = normalizeNonNegativeInteger(
+    source.maxMutations,
+    DEFAULT_STATE_MUTATION_GUARDRAILS.maxMutations,
+  );
+  const maxPayloadBytes = normalizeNonNegativeInteger(
+    source.maxPayloadBytes,
+    DEFAULT_STATE_MUTATION_GUARDRAILS.maxPayloadBytes,
+  );
+  const maxRuntimeMs = normalizeNonNegativeInteger(
+    source.maxRuntimeMs,
+    DEFAULT_STATE_MUTATION_GUARDRAILS.maxRuntimeMs,
+  );
+  const allowlistPrefixes = normalizeAllowlistPrefixes(
+    source.allowlistPrefixes,
+    DEFAULT_STATE_MUTATION_GUARDRAILS.allowlistPrefixes,
+  );
+
+  return {
+    maxMutations,
+    maxPayloadBytes,
+    maxRuntimeMs,
+    allowlistPrefixes,
+    allowlistPrefixSet: new Set(allowlistPrefixes),
+  };
+}
+
+function normalizeAllowlistPrefixes(value, fallback) {
+  if (!Array.isArray(value) || value.length === 0) {
+    return [...fallback];
+  }
+  const normalized = [];
+  for (const raw of value) {
+    if (typeof raw !== 'string') continue;
+    const trimmed = raw.trim();
+    if (trimmed.length === 0 || !trimmed.startsWith('/')) continue;
+    normalized.push(trimmed);
+  }
+  if (normalized.length === 0) {
+    return [...fallback];
+  }
+  return [...new Set(normalized)].sort((a, b) => a.localeCompare(b));
+}
+
+function normalizeNonNegativeInteger(value, fallback) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    return fallback;
+  }
+  return parsed;
+}
+
+function jsonByteSize(value) {
+  let text = '';
+  try {
+    text = JSON.stringify(value);
+  } catch {
+    text = '';
+  }
+  return Buffer.byteLength(text || '', 'utf8');
+}
+
+function isPlainObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isDeepEqual(a, b) {
+  return stableStringify(a) === stableStringify(b);
+}
+
+function cloneJson(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function normalizeMode(value) {
+  const normalized = typeof value === 'string' ? value.trim().toLowerCase() : '';
+  if (normalized === 'native' || normalized === 'headless' || normalized === 'shim') {
+    return normalized;
+  }
+  return 'native';
+}
+
+function normalizeInt(value, fallback) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    return fallback;
+  }
+  return parsed;
+}
+
+function normalizeElapsedSeconds(value, aura) {
+  if (Number.isFinite(value) && value >= 0) {
+    return Number(value);
+  }
+  if (aura?.timer && typeof aura.timer.getTime === 'function') {
+    const timerValue = Number(aura.timer.getTime());
+    if (Number.isFinite(timerValue) && timerValue >= 0) {
+      return timerValue;
+    }
+  }
+  return null;
+}
+
+function normalizeCapturedAt(value) {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function stableStringify(value) {
+  return JSON.stringify(value, buildStableReplacer());
+}
+
+function buildStableReplacer() {
+  const seen = new WeakSet();
+  return function stableReplacer(_key, value) {
+    if (Array.isArray(value) || !value || typeof value !== 'object') {
+      return value;
+    }
+    if (seen.has(value)) {
+      return null;
+    }
+    seen.add(value);
+    const out = {};
+    for (const key of Object.keys(value).sort((a, b) => a.localeCompare(b))) {
+      out[key] = value[key];
+    }
+    return out;
+  };
+}
+
+function sha256(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function orderPayload(payload) {
+  const orderedExport = {};
+  for (const key of CANONICAL_EXPORT_ORDER) {
+    if (!Object.prototype.hasOwnProperty.call(payload.export, key)) continue;
+    orderedExport[key] = payload.export[key];
+  }
+
+  const orderedState = {};
+  for (const key of CANONICAL_STATE_SECTION_ORDER) {
+    if (!Object.prototype.hasOwnProperty.call(payload.state, key)) continue;
+    orderedState[key] = payload.state[key];
+  }
+
+  const out = {};
+  for (const key of CANONICAL_TOP_LEVEL_ORDER) {
+    if (key === 'export') {
+      out.export = orderedExport;
+      continue;
+    }
+    if (key === 'state') {
+      out.state = orderedState;
+      continue;
+    }
+    out[key] = payload[key];
+  }
+  return out;
+}