@auraindustry/aurajs 0.0.6 → 0.1.0

package/src/state-artifacts.mjs

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import {
   existsSync,
   mkdirSync,
@@ -8,13 +9,28 @@ import {
 } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 
+import { GAME_STATE_SCHEMA_VERSION } from './game-state-runtime.mjs';
+
 export const STATE_ARTIFACT_SCHEMA_VERSION = 'aurajs.state-artifact.v1';
 export const STATE_ARTIFACT_KINDS = Object.freeze(['slot', 'checkpoint']);
+export const STATE_ARTIFACT_VERSION = 2;
 
 const STATE_ARTIFACT_DIRECTORY_NAMES = Object.freeze({
   slot: 'slots',
   checkpoint: 'checkpoints',
 });
+const LEGACY_STATE_ARTIFACT_VERSION = 1;
+const LEGACY_GAME_STATE_SCHEMA_VERSION = 'aurajs.game-state.v0';
+const STATE_SECTION_NAMES = Object.freeze([
+  'globals',
+  'camera',
+  'project',
+  'scene3d',
+  'physics',
+  'ecs',
+  'tilemap',
+]);
+const DEFAULT_STATE_ARTIFACT_MIGRATION_REASON_CODE = 'state_artifact_migrated';
 
 export class StateArtifactError extends Error {
   constructor(reasonCode, message, details = {}) {
@@ -25,6 +41,525 @@ export class StateArtifactError extends Error {
   }
 }
 
+function isPlainObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function parsePositiveInteger(value) {
+  if (Number.isInteger(value) && value > 0) {
+    return value;
+  }
+  if (typeof value === 'string' && /^[0-9]+$/.test(value.trim())) {
+    const parsed = Number.parseInt(value.trim(), 10);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : null;
+  }
+  return null;
+}
+
+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 (isPlainObject(value)) {
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+      const next = sanitizeJsonValue(value[key]);
+      if (next === undefined) continue;
+      out[key] = next;
+    }
+    return out;
+  }
+  return null;
+}
+
+function sanitizeJsonObject(value) {
+  return isPlainObject(value) ? sanitizeJsonValue(value) : {};
+}
+
+function stableStringify(value) {
+  if (value === null || typeof value !== 'object') {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => stableStringify(entry)).join(',')}]`;
+  }
+  const keys = Object.keys(value).sort();
+  return `{${keys.map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`;
+}
+
+function sha256(value) {
+  return createHash('sha256').update(String(value)).digest('hex');
+}
+
+function resolveEnvelopeStateSchemaVersion(envelope) {
+  if (typeof envelope?.stateSchemaVersion === 'string' && envelope.stateSchemaVersion.trim().length > 0) {
+    return envelope.stateSchemaVersion.trim();
+  }
+  if (typeof envelope?.payload?.schemaVersion === 'string' && envelope.payload.schemaVersion.trim().length > 0) {
+    return envelope.payload.schemaVersion.trim();
+  }
+  return null;
+}
+
+function normalizeMigrationSteps(steps) {
+  if (!Array.isArray(steps)) return [];
+  const seen = new Set();
+  const output = [];
+  for (const step of steps) {
+    if (typeof step !== 'string') continue;
+    const normalized = step.trim();
+    if (normalized.length === 0 || seen.has(normalized)) continue;
+    seen.add(normalized);
+    output.push(normalized);
+  }
+  return output;
+}
+
+function normalizeStateArtifactMigrationMetadata(
+  migration,
+  {
+    artifactVersion = STATE_ARTIFACT_VERSION,
+    stateSchemaVersion = GAME_STATE_SCHEMA_VERSION,
+  } = {},
+) {
+  const normalizedArtifactVersion = parsePositiveInteger(artifactVersion) || STATE_ARTIFACT_VERSION;
+  const normalizedStateSchemaVersion = typeof stateSchemaVersion === 'string' && stateSchemaVersion.trim().length > 0
+    ? stateSchemaVersion.trim()
+    : GAME_STATE_SCHEMA_VERSION;
+  const input = isPlainObject(migration) ? migration : {};
+  const sourceArtifactVersion = parsePositiveInteger(input.sourceArtifactVersion) || normalizedArtifactVersion;
+  const sourceStateSchemaVersion = typeof input.sourceStateSchemaVersion === 'string'
+    && input.sourceStateSchemaVersion.trim().length > 0
+    ? input.sourceStateSchemaVersion.trim()
+    : normalizedStateSchemaVersion;
+  const steps = normalizeMigrationSteps(input.steps);
+  const applied = input.applied === true
+    || steps.length > 0
+    || sourceArtifactVersion !== normalizedArtifactVersion
+    || sourceStateSchemaVersion !== normalizedStateSchemaVersion;
+  return {
+    applied,
+    sourceArtifactVersion,
+    targetArtifactVersion: normalizedArtifactVersion,
+    sourceStateSchemaVersion,
+    targetStateSchemaVersion: normalizedStateSchemaVersion,
+    steps,
+    reasonCode: typeof input.reasonCode === 'string' && input.reasonCode.trim().length > 0
+      ? input.reasonCode.trim()
+      : (applied ? DEFAULT_STATE_ARTIFACT_MIGRATION_REASON_CODE : null),
+  };
+}
+
+function mergeStateArtifactMigrationMetadata(
+  base,
+  delta,
+  {
+    artifactVersion = STATE_ARTIFACT_VERSION,
+    stateSchemaVersion = GAME_STATE_SCHEMA_VERSION,
+  } = {},
+) {
+  const targetArtifactVersion = parsePositiveInteger(artifactVersion) || STATE_ARTIFACT_VERSION;
+  const targetStateSchemaVersion = typeof stateSchemaVersion === 'string' && stateSchemaVersion.trim().length > 0
+    ? stateSchemaVersion.trim()
+    : GAME_STATE_SCHEMA_VERSION;
+  const normalizedBase = normalizeStateArtifactMigrationMetadata(base, {
+    artifactVersion: targetArtifactVersion,
+    stateSchemaVersion: targetStateSchemaVersion,
+  });
+  const normalizedDelta = normalizeStateArtifactMigrationMetadata(delta, {
+    artifactVersion: targetArtifactVersion,
+    stateSchemaVersion: targetStateSchemaVersion,
+  });
+  const sourceArtifactVersion = Math.min(
+    normalizedBase.sourceArtifactVersion,
+    normalizedDelta.sourceArtifactVersion,
+  );
+  const sourceStateSchemaVersion = normalizedBase.applied
+    ? normalizedBase.sourceStateSchemaVersion
+    : normalizedDelta.sourceStateSchemaVersion;
+  const steps = normalizeMigrationSteps([
+    ...normalizedBase.steps,
+    ...normalizedDelta.steps,
+  ]);
+  const applied = normalizedBase.applied || normalizedDelta.applied || steps.length > 0;
+  return {
+    applied,
+    sourceArtifactVersion,
+    targetArtifactVersion,
+    sourceStateSchemaVersion,
+    targetStateSchemaVersion,
+    steps,
+    reasonCode: normalizedDelta.reasonCode
+      || normalizedBase.reasonCode
+      || (applied ? DEFAULT_STATE_ARTIFACT_MIGRATION_REASON_CODE : null),
+  };
+}
+
+function normalizeMigrationHookMap(input, defaults = new Map()) {
+  const map = new Map(defaults);
+  if (input instanceof Map) {
+    for (const [key, handler] of input.entries()) {
+      if (typeof handler === 'function') {
+        map.set(key, handler);
+      }
+    }
+    return map;
+  }
+  if (isPlainObject(input)) {
+    for (const [key, handler] of Object.entries(input)) {
+      if (typeof handler === 'function') {
+        map.set(key, handler);
+      }
+    }
+  }
+  return map;
+}
+
+function normalizeMigrationHooks(migrationHooks = null) {
+  const input = isPlainObject(migrationHooks) ? migrationHooks : {};
+  return {
+    artifactVersions: normalizeMigrationHookMap(
+      input.artifactVersions,
+      new Map([
+        [LEGACY_STATE_ARTIFACT_VERSION, migrateArtifactEnvelopeV1ToV2],
+      ]),
+    ),
+    stateSchemas: normalizeMigrationHookMap(
+      input.stateSchemas,
+      new Map([
+        [LEGACY_GAME_STATE_SCHEMA_VERSION, migrateLegacyGameStatePayloadV0ToV1],
+      ]),
+    ),
+  };
+}
+
+function normalizeStateArtifactReadOptions({
+  targetArtifactVersion = STATE_ARTIFACT_VERSION,
+  targetStateSchemaVersion = GAME_STATE_SCHEMA_VERSION,
+  migrationHooks = null,
+  exportDefaults = null,
+} = {}) {
+  return {
+    targetArtifactVersion: parsePositiveInteger(targetArtifactVersion) || STATE_ARTIFACT_VERSION,
+    targetStateSchemaVersion: typeof targetStateSchemaVersion === 'string' && targetStateSchemaVersion.trim().length > 0
+      ? targetStateSchemaVersion.trim()
+      : GAME_STATE_SCHEMA_VERSION,
+    migrationHooks: normalizeMigrationHooks(migrationHooks),
+    exportDefaults: normalizeStateArtifactExportDefaults(exportDefaults),
+  };
+}
+
+function normalizeStateArtifactExportDefaults(exportDefaults = null) {
+  const input = isPlainObject(exportDefaults) ? exportDefaults : {};
+  return {
+    mode: typeof input.mode === 'string' && input.mode.trim().length > 0
+      ? input.mode.trim().toLowerCase()
+      : null,
+    seed: Number.isInteger(input.seed) && input.seed >= 0 ? input.seed : 0,
+    frameIndex: Number.isInteger(input.frameIndex) && input.frameIndex >= 0 ? input.frameIndex : 0,
+    elapsedSeconds: Number.isFinite(input.elapsedSeconds) && input.elapsedSeconds >= 0
+      ? Number(input.elapsedSeconds)
+      : null,
+    capturedAt: typeof input.capturedAt === 'string' && input.capturedAt.trim().length > 0
+      ? input.capturedAt.trim()
+      : null,
+  };
+}
+
+function migrateArtifactEnvelopeV1ToV2({ envelope }) {
+  const sourceStateSchemaVersion = resolveEnvelopeStateSchemaVersion(envelope) || GAME_STATE_SCHEMA_VERSION;
+  return {
+    envelope: {
+      ...envelope,
+      artifactVersion: STATE_ARTIFACT_VERSION,
+    },
+    migration: {
+      applied: true,
+      sourceArtifactVersion: LEGACY_STATE_ARTIFACT_VERSION,
+      targetArtifactVersion: STATE_ARTIFACT_VERSION,
+      sourceStateSchemaVersion,
+      targetStateSchemaVersion: sourceStateSchemaVersion,
+      steps: ['state_artifact_version_backfill'],
+      reasonCode: DEFAULT_STATE_ARTIFACT_MIGRATION_REASON_CODE,
+    },
+  };
+}
+
+function migrateLegacyGameStatePayloadV0ToV1({ envelope, exportDefaults = null }) {
+  const rawState = isPlainObject(envelope?.payload?.state)
+    ? envelope.payload.state
+    : (isPlainObject(envelope?.payload) ? envelope.payload : {});
+  const normalizedExportDefaults = normalizeStateArtifactExportDefaults(exportDefaults);
+  const migratedState = {
+    globals: sanitizeJsonObject(rawState.globals),
+  };
+  for (const sectionName of STATE_SECTION_NAMES) {
+    if (sectionName === 'globals') continue;
+    if (!Object.prototype.hasOwnProperty.call(rawState, sectionName)) continue;
+    const normalizedValue = sanitizeJsonValue(rawState[sectionName]);
+    if (normalizedValue == null) continue;
+    migratedState[sectionName] = normalizedValue;
+  }
+  if (isPlainObject(migratedState.camera)) {
+    if (typeof migratedState.camera.following !== 'boolean') {
+      migratedState.camera.following = false;
+    }
+    if (!Number.isInteger(migratedState.camera.activeEffects) || migratedState.camera.activeEffects < 0) {
+      migratedState.camera.activeEffects = 0;
+    }
+  }
+
+  const exportMode = normalizedExportDefaults.mode
+    || (typeof envelope?.source?.mode === 'string' && envelope.source.mode.trim().length > 0
+      ? envelope.source.mode.trim().toLowerCase()
+      : 'headless');
+  const exportElapsedSeconds = normalizedExportDefaults.elapsedSeconds != null
+    ? normalizedExportDefaults.elapsedSeconds
+    : (exportMode === 'headless' ? 0 : null);
+
+  const migratedPayload = {
+    schemaVersion: GAME_STATE_SCHEMA_VERSION,
+    export: {
+      mode: exportMode,
+      seed: normalizedExportDefaults.seed,
+      frameIndex: normalizedExportDefaults.frameIndex,
+      elapsedSeconds: exportElapsedSeconds,
+      fingerprint: sha256(stableStringify(migratedState)),
+      capturedAt: normalizedExportDefaults.capturedAt,
+    },
+    state: migratedState,
+  };
+
+  return {
+    envelope: {
+      ...envelope,
+      stateSchemaVersion: GAME_STATE_SCHEMA_VERSION,
+      payload: migratedPayload,
+    },
+    migration: {
+      applied: true,
+      sourceArtifactVersion: parsePositiveInteger(envelope?.artifactVersion) || LEGACY_STATE_ARTIFACT_VERSION,
+      targetArtifactVersion: parsePositiveInteger(envelope?.artifactVersion) || STATE_ARTIFACT_VERSION,
+      sourceStateSchemaVersion: LEGACY_GAME_STATE_SCHEMA_VERSION,
+      targetStateSchemaVersion: GAME_STATE_SCHEMA_VERSION,
+      steps: ['game_state_payload_v0_to_v1'],
+      reasonCode: DEFAULT_STATE_ARTIFACT_MIGRATION_REASON_CODE,
+    },
+  };
+}
+
+function applyArtifactVersionMigrations(
+  envelope,
+  {
+    filePath = null,
+    targetArtifactVersion = STATE_ARTIFACT_VERSION,
+    migrationHooks,
+    migration,
+  } = {},
+) {
+  let working = envelope;
+  let currentVersion = parsePositiveInteger(working?.artifactVersion) || LEGACY_STATE_ARTIFACT_VERSION;
+  let currentMigration = normalizeStateArtifactMigrationMetadata(migration, {
+    artifactVersion: currentVersion,
+    stateSchemaVersion: resolveEnvelopeStateSchemaVersion(working) || GAME_STATE_SCHEMA_VERSION,
+  });
+
+  if (currentVersion > targetArtifactVersion) {
+    throw new StateArtifactError(
+      'state_artifact_version_unsupported',
+      `State artifact${filePath ? ` "${filePath}"` : ''} uses artifactVersion "${currentVersion}", expected <= "${targetArtifactVersion}".`,
+      {
+        filePath,
+        sourceArtifactVersion: currentVersion,
+        targetArtifactVersion,
+      },
+    );
+  }
+
+  while (currentVersion < targetArtifactVersion) {
+    const migrate = migrationHooks.artifactVersions.get(currentVersion);
+    if (typeof migrate !== 'function') {
+      throw new StateArtifactError(
+        'state_artifact_migration_unavailable',
+        `State artifact${filePath ? ` "${filePath}"` : ''} cannot migrate artifactVersion "${currentVersion}" to "${targetArtifactVersion}".`,
+        {
+          filePath,
+          sourceArtifactVersion: currentVersion,
+          targetArtifactVersion,
+        },
+      );
+    }
+
+    let result;
+    try {
+      result = migrate({ envelope: working, filePath });
+    } catch (error) {
+      throw new StateArtifactError(
+        'state_artifact_migration_failed',
+        `State artifact${filePath ? ` "${filePath}"` : ''} migration from artifactVersion "${currentVersion}" failed: ${error.message}`,
+        {
+          filePath,
+          sourceArtifactVersion: currentVersion,
+          targetArtifactVersion,
+        },
+      );
+    }
+
+    if (!isPlainObject(result?.envelope)) {
+      throw new StateArtifactError(
+        'state_artifact_migration_failed',
+        `State artifact${filePath ? ` "${filePath}"` : ''} migration from artifactVersion "${currentVersion}" returned an invalid envelope.`,
+        {
+          filePath,
+          sourceArtifactVersion: currentVersion,
+          targetArtifactVersion,
+        },
+      );
+    }
+
+    working = result.envelope;
+    const nextVersion = parsePositiveInteger(working.artifactVersion);
+    if (!nextVersion || nextVersion <= currentVersion) {
+      throw new StateArtifactError(
+        'state_artifact_migration_failed',
+        `State artifact${filePath ? ` "${filePath}"` : ''} migration from artifactVersion "${currentVersion}" did not advance the artifactVersion.`,
+        {
+          filePath,
+          sourceArtifactVersion: currentVersion,
+          targetArtifactVersion,
+          nextArtifactVersion: nextVersion,
+        },
+      );
+    }
+
+    currentVersion = nextVersion;
+    currentMigration = mergeStateArtifactMigrationMetadata(currentMigration, result.migration, {
+      artifactVersion: currentVersion,
+      stateSchemaVersion: resolveEnvelopeStateSchemaVersion(working) || GAME_STATE_SCHEMA_VERSION,
+    });
+  }
+
+  return {
+    envelope: working,
+    migration: currentMigration,
+  };
+}
+
+function applyStateSchemaMigrations(
+  envelope,
+  {
+    filePath = null,
+    targetStateSchemaVersion = GAME_STATE_SCHEMA_VERSION,
+    migrationHooks,
+    migration,
+    exportDefaults = null,
+  } = {},
+) {
+  let working = envelope;
+  let currentStateSchemaVersion = resolveEnvelopeStateSchemaVersion(working);
+  if (!currentStateSchemaVersion) {
+    throw new StateArtifactError(
+      'invalid_state_artifact_payload',
+      `State artifact${filePath ? ` "${filePath}"` : ''} stateSchemaVersion must be a non-empty string.`,
+      { filePath },
+    );
+  }
+
+  const currentArtifactVersion = parsePositiveInteger(working?.artifactVersion) || STATE_ARTIFACT_VERSION;
+  let currentMigration = normalizeStateArtifactMigrationMetadata(migration, {
+    artifactVersion: currentArtifactVersion,
+    stateSchemaVersion: currentStateSchemaVersion,
+  });
+
+  const seenSchemas = new Set([currentStateSchemaVersion]);
+  while (currentStateSchemaVersion !== targetStateSchemaVersion) {
+    const migrate = migrationHooks.stateSchemas.get(currentStateSchemaVersion);
+    if (typeof migrate !== 'function') {
+      throw new StateArtifactError(
+        'state_artifact_state_schema_migration_unavailable',
+        `State artifact${filePath ? ` "${filePath}"` : ''} cannot migrate state schema "${currentStateSchemaVersion}" to "${targetStateSchemaVersion}".`,
+        {
+          filePath,
+          sourceArtifactVersion: currentArtifactVersion,
+          targetArtifactVersion: currentArtifactVersion,
+          sourceStateSchemaVersion: currentStateSchemaVersion,
+          targetStateSchemaVersion,
+        },
+      );
+    }
+
+    let result;
+    try {
+      result = migrate({
+        envelope: working,
+        filePath,
+        targetStateSchemaVersion,
+        exportDefaults,
+      });
+    } catch (error) {
+      throw new StateArtifactError(
+        'state_artifact_state_schema_migration_failed',
+        `State artifact${filePath ? ` "${filePath}"` : ''} state schema migration from "${currentStateSchemaVersion}" failed: ${error.message}`,
+        {
+          filePath,
+          sourceArtifactVersion: currentArtifactVersion,
+          targetArtifactVersion: currentArtifactVersion,
+          sourceStateSchemaVersion: currentStateSchemaVersion,
+          targetStateSchemaVersion,
+        },
+      );
+    }
+
+    if (!isPlainObject(result?.envelope)) {
+      throw new StateArtifactError(
+        'state_artifact_state_schema_migration_failed',
+        `State artifact${filePath ? ` "${filePath}"` : ''} state schema migration from "${currentStateSchemaVersion}" returned an invalid envelope.`,
+        {
+          filePath,
+          sourceArtifactVersion: currentArtifactVersion,
+          targetArtifactVersion: currentArtifactVersion,
+          sourceStateSchemaVersion: currentStateSchemaVersion,
+          targetStateSchemaVersion,
+        },
+      );
+    }
+
+    working = result.envelope;
+    const nextStateSchemaVersion = resolveEnvelopeStateSchemaVersion(working);
+    if (!nextStateSchemaVersion || seenSchemas.has(nextStateSchemaVersion)) {
+      throw new StateArtifactError(
+        'state_artifact_state_schema_migration_failed',
+        `State artifact${filePath ? ` "${filePath}"` : ''} state schema migration from "${currentStateSchemaVersion}" did not advance toward "${targetStateSchemaVersion}".`,
+        {
+          filePath,
+          sourceArtifactVersion: currentArtifactVersion,
+          targetArtifactVersion: currentArtifactVersion,
+          sourceStateSchemaVersion: currentStateSchemaVersion,
+          targetStateSchemaVersion,
+          nextStateSchemaVersion,
+        },
+      );
+    }
+
+    currentStateSchemaVersion = nextStateSchemaVersion;
+    seenSchemas.add(currentStateSchemaVersion);
+    currentMigration = mergeStateArtifactMigrationMetadata(currentMigration, result.migration, {
+      artifactVersion: parsePositiveInteger(working?.artifactVersion) || currentArtifactVersion,
+      stateSchemaVersion: currentStateSchemaVersion,
+    });
+  }
+
+  return {
+    envelope: working,
+    migration: currentMigration,
+  };
+}
+
 export function normalizeStateArtifactKind(value) {
   const normalized = String(value || '').trim().toLowerCase();
   if (!STATE_ARTIFACT_KINDS.includes(normalized)) {
@@ -98,6 +633,7 @@ export function createStateArtifactEnvelope({
   const output = {
     schemaVersion: STATE_ARTIFACT_SCHEMA_VERSION,
     artifactType: normalizedKind,
+    artifactVersion: STATE_ARTIFACT_VERSION,
     name: normalizedName,
     createdAt: typeof createdAt === 'string' && createdAt.trim().length > 0
       ? createdAt
@@ -108,6 +644,10 @@ export function createStateArtifactEnvelope({
       : null,
     source: normalizeArtifactSource(source),
     payload,
+    migration: normalizeStateArtifactMigrationMetadata(null, {
+      artifactVersion: STATE_ARTIFACT_VERSION,
+      stateSchemaVersion: payload.schemaVersion,
+    }),
   };
 
   if (typeof note === 'string' && note.trim().length > 0) {
@@ -124,7 +664,7 @@ export function writeStateArtifactEnvelope(filePath, envelope) {
   return validated;
 }
 
-export function readStateArtifactEnvelope(filePath) {
+export function readStateArtifactEnvelope(filePath, options = {}) {
   let text = '';
   try {
     text = readFileSync(filePath, 'utf8');
@@ -147,10 +687,19 @@ export function readStateArtifactEnvelope(filePath) {
     );
   }
 
-  return normalizeStateArtifactEnvelope(parsed, { filePath });
+  return normalizeStateArtifactEnvelope(parsed, { filePath, ...options });
 }
 
-export function loadStateArtifact({ projectRoot, kind, name, artifactPath = null } = {}) {
+export function loadStateArtifact({
+  projectRoot,
+  kind,
+  name,
+  artifactPath = null,
+  targetArtifactVersion = STATE_ARTIFACT_VERSION,
+  targetStateSchemaVersion = GAME_STATE_SCHEMA_VERSION,
+  migrationHooks = null,
+  exportDefaults = null,
+} = {}) {
   const resolvedPath = artifactPath
     ? resolve(projectRoot, artifactPath)
     : resolveStateArtifactPath(projectRoot, kind, name);
@@ -161,7 +710,15 @@ export function loadStateArtifact({ projectRoot, kind, name, artifactPath = null
       { filePath: resolvedPath },
     );
   }
-  const envelope = readStateArtifactEnvelope(resolvedPath);
+  const envelope = readStateArtifactEnvelope(
+    resolvedPath,
+    normalizeStateArtifactReadOptions({
+      targetArtifactVersion,
+      targetStateSchemaVersion,
+      migrationHooks,
+      exportDefaults,
+    }),
+  );
   return {
     filePath: resolvedPath,
     envelope,
@@ -169,9 +726,24 @@ export function loadStateArtifact({ projectRoot, kind, name, artifactPath = null
   };
 }
 
-export function listStateArtifacts(projectRoot, kind) {
+export function listStateArtifacts(
+  projectRoot,
+  kind,
+  {
+    targetArtifactVersion = STATE_ARTIFACT_VERSION,
+    targetStateSchemaVersion = GAME_STATE_SCHEMA_VERSION,
+    migrationHooks = null,
+    exportDefaults = null,
+  } = {},
+) {
   const normalizedKind = normalizeStateArtifactKind(kind);
   const directory = resolveStateArtifactDirectory(projectRoot, normalizedKind);
+  const readOptions = normalizeStateArtifactReadOptions({
+    targetArtifactVersion,
+    targetStateSchemaVersion,
+    migrationHooks,
+    exportDefaults,
+  });
   if (!existsSync(directory)) {
     return {
       kind: normalizedKind,
@@ -187,7 +759,7 @@ export function listStateArtifacts(projectRoot, kind) {
     if (!entry.endsWith('.json')) continue;
     const filePath = join(directory, entry);
     try {
-      const envelope = readStateArtifactEnvelope(filePath);
+      const envelope = readStateArtifactEnvelope(filePath, readOptions);
       if (envelope.artifactType !== normalizedKind) {
         throw new StateArtifactError(
           'state_artifact_kind_mismatch',
@@ -203,6 +775,14 @@ export function listStateArtifacts(projectRoot, kind) {
           ? error.reasonCode
           : 'state_artifact_invalid',
         detail: error instanceof Error ? error.message : String(error),
+        migration: error instanceof StateArtifactError && isPlainObject(error.details)
+          ? {
+            sourceArtifactVersion: error.details.sourceArtifactVersion ?? null,
+            targetArtifactVersion: error.details.targetArtifactVersion ?? null,
+            sourceStateSchemaVersion: error.details.sourceStateSchemaVersion ?? null,
+            targetStateSchemaVersion: error.details.targetStateSchemaVersion ?? null,
+          }
+          : null,
       });
     }
   }
@@ -215,7 +795,16 @@ export function listStateArtifacts(projectRoot, kind) {
   };
 }
 
-function normalizeStateArtifactEnvelope(envelope, { filePath = null } = {}) {
+function normalizeStateArtifactEnvelope(
+  envelope,
+  {
+    filePath = null,
+    targetArtifactVersion = STATE_ARTIFACT_VERSION,
+    targetStateSchemaVersion = GAME_STATE_SCHEMA_VERSION,
+    migrationHooks = normalizeMigrationHooks(),
+    exportDefaults = normalizeStateArtifactExportDefaults(),
+  } = {},
+) {
   if (!envelope || typeof envelope !== 'object' || Array.isArray(envelope)) {
     throw new StateArtifactError(
       'invalid_state_artifact_payload',
@@ -231,26 +820,58 @@ function normalizeStateArtifactEnvelope(envelope, { filePath = null } = {}) {
     );
   }
 
-  const normalizedKind = normalizeStateArtifactKind(envelope.artifactType);
-  const normalizedName = normalizeStateArtifactName(envelope.name, { kind: normalizedKind });
-  if (!envelope.payload || typeof envelope.payload !== 'object' || Array.isArray(envelope.payload)) {
+  let working = envelope;
+  let migration = normalizeStateArtifactMigrationMetadata(working.migration, {
+    artifactVersion: parsePositiveInteger(working.artifactVersion) || LEGACY_STATE_ARTIFACT_VERSION,
+    stateSchemaVersion: resolveEnvelopeStateSchemaVersion(working) || GAME_STATE_SCHEMA_VERSION,
+  });
+  const artifactMigration = applyArtifactVersionMigrations(working, {
+    filePath,
+    targetArtifactVersion,
+    migrationHooks,
+    migration,
+  });
+  working = artifactMigration.envelope;
+  migration = artifactMigration.migration;
+  const stateSchemaMigration = applyStateSchemaMigrations(working, {
+    filePath,
+    targetStateSchemaVersion,
+    migrationHooks,
+    migration,
+    exportDefaults,
+  });
+  working = stateSchemaMigration.envelope;
+  migration = stateSchemaMigration.migration;
+
+  const normalizedKind = normalizeStateArtifactKind(working.artifactType);
+  const normalizedName = normalizeStateArtifactName(working.name, { kind: normalizedKind });
+  if (!working.payload || typeof working.payload !== 'object' || Array.isArray(working.payload)) {
     throw new StateArtifactError(
       'invalid_state_artifact_payload',
       `State artifact${filePath ? ` "${filePath}"` : ''} payload must be an object.`,
       { filePath },
     );
   }
-  if (typeof envelope.stateSchemaVersion !== 'string' || envelope.stateSchemaVersion.trim().length === 0) {
+  const artifactVersion = parsePositiveInteger(working.artifactVersion);
+  if (!artifactVersion) {
+    throw new StateArtifactError(
+      'invalid_state_artifact_payload',
+      `State artifact${filePath ? ` "${filePath}"` : ''} artifactVersion must be a positive integer.`,
+      { filePath },
+    );
+  }
+  const stateSchemaVersion = resolveEnvelopeStateSchemaVersion(working);
+  if (typeof stateSchemaVersion !== 'string' || stateSchemaVersion.trim().length === 0) {
     throw new StateArtifactError(
       'invalid_state_artifact_payload',
       `State artifact${filePath ? ` "${filePath}"` : ''} stateSchemaVersion must be a non-empty string.`,
       { filePath },
     );
   }
-  if (envelope.payload.schemaVersion !== envelope.stateSchemaVersion) {
+  if (working.payload.schemaVersion !== stateSchemaVersion) {
     throw new StateArtifactError(
       'state_artifact_schema_mismatch',
-      `State artifact${filePath ? ` "${filePath}"` : ''} payload schema "${envelope.payload.schemaVersion}" does not match declared stateSchemaVersion "${envelope.stateSchemaVersion}".`,
+      `State artifact${filePath ? ` "${filePath}"` : ''} payload schema "${working.payload.schemaVersion}" does not match declared stateSchemaVersion "${stateSchemaVersion}".`,
       { filePath },
     );
   }
@@ -258,22 +879,34 @@ function normalizeStateArtifactEnvelope(envelope, { filePath = null } = {}) {
   const output = {
     schemaVersion: STATE_ARTIFACT_SCHEMA_VERSION,
     artifactType: normalizedKind,
+    artifactVersion,
     name: normalizedName,
-    createdAt: typeof envelope.createdAt === 'string' && envelope.createdAt.trim().length > 0
-      ? envelope.createdAt
+    createdAt: typeof working.createdAt === 'string' && working.createdAt.trim().length > 0
+      ? working.createdAt
       : null,
-    stateSchemaVersion: envelope.stateSchemaVersion,
-    payloadFingerprint: typeof envelope.payloadFingerprint === 'string'
-      ? envelope.payloadFingerprint
-      : (typeof envelope?.payload?.export?.fingerprint === 'string'
-        ? envelope.payload.export.fingerprint
+    stateSchemaVersion,
+    payloadFingerprint: typeof working?.payload?.export?.fingerprint === 'string'
+      ? working.payload.export.fingerprint
+      : (typeof working.payloadFingerprint === 'string'
+        ? working.payloadFingerprint
         : null),
-    source: normalizeArtifactSource(envelope.source),
-    payload: envelope.payload,
+    source: normalizeArtifactSource(working.source),
+    payload: working.payload,
+    migration: mergeStateArtifactMigrationMetadata(
+      normalizeStateArtifactMigrationMetadata(working.migration, {
+        artifactVersion,
+        stateSchemaVersion,
+      }),
+      migration,
+      {
+        artifactVersion,
+        stateSchemaVersion,
+      },
+    ),
   };
 
-  if (typeof envelope.note === 'string' && envelope.note.trim().length > 0) {
-    output.note = envelope.note.trim();
+  if (typeof working.note === 'string' && working.note.trim().length > 0) {
+    output.note = working.note.trim();
   }
 
   return output;
@@ -283,12 +916,17 @@ function createArtifactMetadata(filePath, envelope) {
   const stat = statSync(filePath);
   return {
     kind: envelope.artifactType,
+    artifactVersion: envelope.artifactVersion,
     name: envelope.name,
     path: filePath,
     createdAt: envelope.createdAt,
     note: envelope.note || null,
     stateSchemaVersion: envelope.stateSchemaVersion,
     payloadFingerprint: envelope.payloadFingerprint,
+    migration: normalizeStateArtifactMigrationMetadata(envelope.migration, {
+      artifactVersion: envelope.artifactVersion,
+      stateSchemaVersion: envelope.stateSchemaVersion,
+    }),
     mode: typeof envelope?.payload?.export?.mode === 'string' ? envelope.payload.export.mode : null,
     frameIndex: Number.isInteger(envelope?.payload?.export?.frameIndex) ? envelope.payload.export.frameIndex : null,
     elapsedSeconds: Number.isFinite(envelope?.payload?.export?.elapsedSeconds)