@auraindustry/aurajs 0.0.5 → 0.0.6

package/src/cli.mjs

@@ -9,7 +9,13 @@ import {
   formatBundleError,
   isBundleError,
 } from './bundler.mjs';
-import { scaffold, scaffoldGame, listCreateTemplates, normalizeCreateTemplate } from './scaffold.mjs';
+import {
+  scaffold,
+  scaffoldGame,
+  listCreateTemplates,
+  listCreateTemplateAliasHints,
+  normalizeCreateTemplate,
+} from './scaffold.mjs';
 import { packageAssets } from './asset-pack.mjs';
 import { writeBuildManifest, writeWebBuildArtifacts } from './build-contract.mjs';
 import {
@@ -29,6 +35,16 @@ import {
   DEFAULT_STATE_MUTATION_GUARDRAILS,
   STATE_MUTATION_ALLOWLIST_PREFIXES,
 } from './game-state-runtime.mjs';
+import {
+  StateArtifactError,
+  createStateArtifactEnvelope,
+  listStateArtifacts,
+  loadStateArtifact,
+  normalizeStateArtifactName,
+  resolveStateArtifactPath,
+  writeStateArtifactEnvelope,
+} from './state-artifacts.mjs';
+import { prepareDevStateRestoreEntry } from './state-dev-reload.mjs';
 
 // ---------------------------------------------------------------------------
 // Version
@@ -36,6 +52,9 @@ import {
 
 const PKG_PATH = new URL('../package.json', import.meta.url);
 const VERSION = JSON.parse(readFileSync(PKG_PATH, 'utf8')).version;
+const CREATE_TEMPLATE_OPTION_LIST = listCreateTemplates().join('|');
+const CREATE_TEMPLATE_ALIAS_HINT_LIST = listCreateTemplateAliasHints().join(', ');
+const CREATE_USAGE = `aura create <name> [--template <${CREATE_TEMPLATE_OPTION_LIST}>] [--skip-install]`;
 
 // ---------------------------------------------------------------------------
 // Command registry
@@ -45,10 +64,10 @@ const COMMANDS = {
   init: { description: 'Scaffold a new AuraJS project', usage: 'aura init <name>' },
   create: {
     description: 'Scaffold a full npm-ready AuraJS game',
-    usage: 'aura create <name> [--template <2d-shooter|3d-platformer|blank>] [--skip-install]',
+    usage: CREATE_USAGE,
     details: [
       '  Options:',
-      `    --template <${listCreateTemplates().join('|')}>   Choose starting game template (aliases: 2d, 3d, shooter, platformer)`,
+      `    --template <${CREATE_TEMPLATE_OPTION_LIST}>   Choose starting game template (aliases: ${CREATE_TEMPLATE_ALIAS_HINT_LIST})`,
       '    --skip-install                  Skip npm install after scaffold',
     ],
   },
@@ -57,11 +76,14 @@ const COMMANDS = {
     usage: 'aura dev [--target web]',
     details: [
       '  Options:',
-      '    --target web   Run browser web-build dev loop (default: native host loop)',
+      '    --target web   Run browser web-build rebuild loop for the current browser-backed subset',
+      '    --restore-slot <name>        Reapply a saved slot after each native dev restart',
+      '    --restore-checkpoint <name>  Reapply a saved checkpoint after each native dev restart',
       '',
       '  Notes:',
       '    - default `aura dev` preserves native host hot-reload semantics.',
-      '    - `aura dev --target web` rebuilds web artifacts + emits refresh diagnostics.',
+      '    - restore flags are native-only and reapply a persisted state artifact after setup.',
+      '    - `aura dev --target web` rebuilds `build/web` and emits refresh diagnostics; serve those artifacts in a browser.',
     ],
   },
   build: {
@@ -73,24 +95,39 @@ const COMMANDS = {
       '    --asset-mode <embed|sibling>      Package assets in pak or sibling assets/',
       '',
       '  Notes:',
-      '    - `--target web` emits browser artifacts under `build/web`.',
+      '    - `--target web` emits browser artifacts under `build/web` for the current browser-backed subset.',
       '    - Native targets are current host only in v1.',
       '    - `--target all` keeps current host output; use CI matrix for all platforms.',
+      '    - Browser runtime truth today: current 2D/input/assets/storage path is supported; `aura.state` and `aura.net` remain reason-coded unsupported.',
+    ],
+  },
+  run: {
+    description: 'Build and run the game',
+    usage: 'aura run',
+    details: [
+      '  Notes:',
+      '    - `aura run` is native-only in v1.',
+      '    - For web, use `aura build --target web` and serve `build/web` in a browser.',
     ],
   },
-  run: { description: 'Build and run the game', usage: 'aura run' },
   clean: { description: 'Delete build artifacts', usage: 'aura clean' },
   test: { description: 'Run game logic in headless mode', usage: 'aura test [file] [--width N] [--height N] [--frames N]' },
   conformance: { description: 'Run API conformance suites in headless mode', usage: 'aura conformance [--mode shim|native|both] [--json]' },
   state: {
     description: 'Export, diff, and patch canonical game-state snapshots',
-    usage: 'aura state <export|diff|patch|apply> [options]',
+    usage: 'aura state <export|diff|patch|apply|slot|checkpoint> [options]',
     details: [
       '  Subcommands:',
       '    export                         Emit canonical game-state-v1 JSON snapshot',
       '    diff <before.json> <after.json>  Emit deterministic patch payload',
       '    patch <state.json> <patch.json>  Apply patch payload to a state snapshot',
       '    apply <state.json>               Apply state payload via runtime hooks',
+      '    slot save <name>                Persist named save slot under .aura/state/slots/',
+      '    slot restore <name>             Reapply named save slot via runtime hooks',
+      '    slot list                       List named save slots with metadata',
+      '    checkpoint save <name>         Persist named checkpoint under .aura/state/checkpoints/',
+      '    checkpoint restore <name>      Reapply named checkpoint via runtime hooks',
+      '    checkpoint list                List named checkpoints with metadata',
       '',
       '  Options:',
       '    export:',
@@ -127,6 +164,20 @@ const COMMANDS = {
       '      --max-bytes <N>               Max payload bytes per input (default: 262144)',
       '      --max-runtime-ms <N>          Max mutation runtime budget in ms (default: 200)',
       '      --audit <path|->              Audit artifact path (default: .aura/state/state-apply-audit.json)',
+      '',
+      '    slot/checkpoint save:',
+      '      --report <path|->             Write command report JSON to file (or "-" for stdout)',
+      '      --artifact <path>             Override saved artifact path',
+      '      --note <text>                 Optional metadata note stored with the artifact',
+      '',
+      '    slot/checkpoint restore:',
+      '      --report <path|->             Write command report JSON to file (or "-" for stdout)',
+      '      --artifact <path>             Override artifact path to restore from',
+      '',
+      '    slot/checkpoint list:',
+      '      --report <path|->             Write listing JSON to file (or "-" for stdout)',
+      '      --compact                     Compact JSON output (single line)',
+      '      --pretty                      Pretty JSON output (default)',
     ],
   },
 };
@@ -270,14 +321,14 @@ function parseCreateArgs(args) {
       throw new Error(`Unknown option for create: ${arg}`);
     }
     if (name !== null) {
-      throw new Error(`Unexpected extra argument "${arg}". Usage: aura create <name> [--template <2d-shooter|3d-platformer|blank>] [--skip-install]`);
+      throw new Error(`Unexpected extra argument "${arg}". Usage: ${CREATE_USAGE}`);
     }
     name = arg;
   }
 
   const normalizedTemplate = normalizeCreateTemplate(template);
   if (!normalizedTemplate || !allowedTemplates.has(normalizedTemplate)) {
-    throw new Error(`Invalid --template "${template}". Supported templates: ${[...allowedTemplates].join(', ')} (aliases: 2d, 3d, shooter, platformer).`);
+    throw new Error(`Invalid --template "${template}". Supported templates: ${[...allowedTemplates].join(', ')} (aliases: ${CREATE_TEMPLATE_ALIAS_HINT_LIST}).`);
   }
 
   return { name, template: normalizedTemplate, skipInstall };
@@ -902,121 +953,640 @@ function parseStateApplyArgs(args) {
   return parsed;
 }
 
-function normalizeStateCommandInputPath(value, flagName, reasonCode) {
-  const normalized = String(value || '').trim();
-  if (normalized.length === 0) {
-    throw new StateExportError(reasonCode, `${flagName} requires a non-empty file path.`);
-  }
-  return resolve(process.cwd(), normalized);
-}
+function parseDevArgs(args) {
+  const parsed = {
+    target: null,
+    restoreKind: null,
+    restoreName: null,
+  };
 
-function normalizeStateCommandOutput(value, reasonCode) {
-  const normalized = String(value || '').trim();
-  if (normalized.length === 0) {
-    throw new StateExportError(reasonCode, '--output requires a non-empty path or "-".');
-  }
-  if (normalized === '-') {
-    return null;
-  }
-  return resolve(process.cwd(), normalized);
-}
+  for (let i = 0; i < args.length; i += 1) {
+    const token = args[i];
 
-function normalizeStateAuditOutput(value, reasonCode) {
-  const normalized = String(value || '').trim();
-  if (normalized.length === 0) {
-    throw new StateExportError(reasonCode, '--audit requires a non-empty path or "-".');
-  }
-  if (normalized === '-') {
-    return null;
+    if (token === '--target') {
+      const value = readRequiredOptionValue(args, i, '--target');
+      parsed.target = normalizeDevTarget(value);
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--target=')) {
+      parsed.target = normalizeDevTarget(token.slice('--target='.length));
+      continue;
+    }
+
+    if (token === '--restore-slot') {
+      const value = readRequiredOptionValue(args, i, '--restore-slot');
+      if (parsed.restoreKind) {
+        throw new StateExportError(
+          'invalid_dev_args',
+          'Use only one of --restore-slot or --restore-checkpoint.',
+        );
+      }
+      parsed.restoreKind = 'slot';
+      parsed.restoreName = normalizeStateArtifactName(value, { kind: 'slot' });
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--restore-slot=')) {
+      if (parsed.restoreKind) {
+        throw new StateExportError(
+          'invalid_dev_args',
+          'Use only one of --restore-slot or --restore-checkpoint.',
+        );
+      }
+      parsed.restoreKind = 'slot';
+      parsed.restoreName = normalizeStateArtifactName(token.slice('--restore-slot='.length), { kind: 'slot' });
+      continue;
+    }
+
+    if (token === '--restore-checkpoint') {
+      const value = readRequiredOptionValue(args, i, '--restore-checkpoint');
+      if (parsed.restoreKind) {
+        throw new StateExportError(
+          'invalid_dev_args',
+          'Use only one of --restore-slot or --restore-checkpoint.',
+        );
+      }
+      parsed.restoreKind = 'checkpoint';
+      parsed.restoreName = normalizeStateArtifactName(value, { kind: 'checkpoint' });
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--restore-checkpoint=')) {
+      if (parsed.restoreKind) {
+        throw new StateExportError(
+          'invalid_dev_args',
+          'Use only one of --restore-slot or --restore-checkpoint.',
+        );
+      }
+      parsed.restoreKind = 'checkpoint';
+      parsed.restoreName = normalizeStateArtifactName(
+        token.slice('--restore-checkpoint='.length),
+        { kind: 'checkpoint' },
+      );
+      continue;
+    }
+
+    if (token.startsWith('--')) {
+      throw new StateExportError('invalid_dev_args', `Unknown dev option: ${token}`);
+    }
   }
-  return resolve(process.cwd(), normalized);
-}
 
-function defaultStatePatchAuditPath(projectRoot) {
-  return resolve(projectRoot, '.aura/state/state-patch-audit.json');
+  return parsed;
 }
 
-function defaultStateApplyAuditPath(projectRoot) {
-  return resolve(projectRoot, '.aura/state/state-apply-audit.json');
+function normalizeDevTarget(value) {
+  const normalized = String(value || '').trim().toLowerCase();
+  if (normalized === 'macos' || normalized === 'darwin' || normalized === 'mac') return 'mac';
+  if (normalized === 'win' || normalized === 'win32' || normalized === 'windows') return 'windows';
+  if (normalized === 'browser' || normalized === 'web') return 'web';
+  if (normalized === 'linux') return 'linux';
+  throw new StateExportError(
+    'invalid_dev_args',
+    `Unsupported dev target "${value}". Supported values: web.`,
+  );
 }
 
-function readJsonInputFile(filePath, label, reasonCodePrefix) {
-  let text;
-  try {
-    text = readFileSync(filePath, 'utf8');
-  } catch (error) {
-    throw new StateExportError(
-      `${reasonCodePrefix}_read_failed`,
-      `Failed to read ${label} "${filePath}": ${error.message}`,
-    );
-  }
-  try {
-    return JSON.parse(text);
-  } catch (error) {
-    throw new StateExportError(
-      `${reasonCodePrefix}_invalid_json`,
-      `${label} "${filePath}" is not valid JSON: ${error.message}`,
-    );
-  }
-}
+function parseStateArtifactSaveArgs(kind, args) {
+  const normalizedKind = kind === 'slot' ? 'slot' : 'checkpoint';
+  const reasonCode = `invalid_state_${normalizedKind}_save_args`;
+  const parsed = {
+    kind: normalizedKind,
+    name: null,
+    artifactPath: null,
+    reportPath: null,
+    note: null,
+    file: null,
+    mode: 'headless',
+    frames: 1,
+    schemaVersion: GAME_STATE_SCHEMA_VERSION,
+    compact: false,
+  };
 
-function writeStateJsonOutput(filePath, jsonText, reasonCode) {
-  if (!filePath) {
-    process.stdout.write(jsonText);
-    return;
+  let formattingFlag = 'pretty';
+
+  for (let i = 0; i < args.length; i += 1) {
+    const token = args[i];
+
+    if (token === '--artifact') {
+      parsed.artifactPath = normalizeStateArtifactFilePath(
+        readRequiredOptionValue(args, i, '--artifact'),
+        '--artifact',
+        reasonCode,
+      );
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--artifact=')) {
+      parsed.artifactPath = normalizeStateArtifactFilePath(
+        token.slice('--artifact='.length),
+        '--artifact',
+        reasonCode,
+      );
+      continue;
+    }
+
+    if (token === '--report') {
+      parsed.reportPath = normalizeStateCommandOutput(
+        readRequiredOptionValue(args, i, '--report'),
+        reasonCode,
+      );
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--report=')) {
+      parsed.reportPath = normalizeStateCommandOutput(token.slice('--report='.length), reasonCode);
+      continue;
+    }
+
+    if (token === '--note') {
+      parsed.note = normalizeOptionalNote(readRequiredOptionValue(args, i, '--note'));
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--note=')) {
+      parsed.note = normalizeOptionalNote(token.slice('--note='.length));
+      continue;
+    }
+
+    if (token === '--mode') {
+      parsed.mode = normalizeStateExportMode(readRequiredOptionValue(args, i, '--mode'));
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--mode=')) {
+      parsed.mode = normalizeStateExportMode(token.slice('--mode='.length));
+      continue;
+    }
+
+    if (token === '--frames') {
+      parsed.frames = parseNonNegativeIntegerArg(readRequiredOptionValue(args, i, '--frames'), '--frames', reasonCode);
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--frames=')) {
+      parsed.frames = parseNonNegativeIntegerArg(token.slice('--frames='.length), '--frames', reasonCode);
+      continue;
+    }
+
+    if (token === '--schema' || token === '--schema-version') {
+      parsed.schemaVersion = normalizeStateExportSchemaVersion(readRequiredOptionValue(args, i, token));
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--schema=')) {
+      parsed.schemaVersion = normalizeStateExportSchemaVersion(token.slice('--schema='.length));
+      continue;
+    }
+    if (token.startsWith('--schema-version=')) {
+      parsed.schemaVersion = normalizeStateExportSchemaVersion(token.slice('--schema-version='.length));
+      continue;
+    }
+
+    if (token === '--compact') {
+      if (formattingFlag === 'pretty') {
+        parsed.compact = true;
+        formattingFlag = 'compact';
+        continue;
+      }
+      if (formattingFlag === 'compact') continue;
+      throw new StateExportError(reasonCode, 'Cannot use --compact and --pretty together.');
+    }
+    if (token === '--pretty') {
+      if (formattingFlag === 'compact') {
+        throw new StateExportError(reasonCode, 'Cannot use --compact and --pretty together.');
+      }
+      parsed.compact = false;
+      formattingFlag = 'pretty';
+      continue;
+    }
+
+    if (token === '--file') {
+      parsed.file = normalizeStateExportFile(readRequiredOptionValue(args, i, '--file'));
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--file=')) {
+      parsed.file = normalizeStateExportFile(token.slice('--file='.length));
+      continue;
+    }
+
+    if (token.startsWith('--')) {
+      throw new StateExportError(reasonCode, `Unknown ${normalizedKind} save option: ${token}`);
+    }
+
+    if (parsed.name !== null) {
+      throw new StateExportError(
+        reasonCode,
+        `Unexpected extra argument "${token}". Usage: aura state ${normalizedKind} save <name> [options]`,
+      );
+    }
+    parsed.name = normalizeStateArtifactName(token, { kind: normalizedKind });
   }
 
-  try {
-    mkdirSync(dirname(filePath), { recursive: true });
-    writeFileSync(filePath, jsonText, 'utf8');
-  } catch (error) {
+  if (!parsed.name) {
     throw new StateExportError(
       reasonCode,
-      `Failed to write state output "${filePath}": ${error.message}`,
+      `Missing ${normalizedKind} name. Usage: aura state ${normalizedKind} save <name> [options]`,
     );
   }
-}
-
-function writeStateMutationAudit(auditPath, payload) {
-  const text = `${JSON.stringify(payload, null, 2)}\n`;
-  if (auditPath === null) {
-    process.stdout.write(text);
-    return;
-  }
-  try {
-    mkdirSync(dirname(auditPath), { recursive: true });
-    writeFileSync(auditPath, text, 'utf8');
-  } catch (error) {
+  if (parsed.schemaVersion !== GAME_STATE_SCHEMA_VERSION) {
     throw new StateExportError(
-      'state_mutation_audit_write_failed',
-      `Failed to write state mutation audit "${auditPath}": ${error.message}`,
+      'schema_version_mismatch',
+      `Unsupported schema version "${parsed.schemaVersion}". Expected "${GAME_STATE_SCHEMA_VERSION}".`,
     );
   }
-}
 
-function jsonByteSize(value) {
-  let text = '';
-  try {
-    text = JSON.stringify(value);
-  } catch {
-    text = '';
-  }
-  return Buffer.byteLength(text || '', 'utf8');
+  return parsed;
 }
 
-function mutationGuardrailsFromParsed(parsed) {
-  return {
-    maxMutations: parsed.maxOps,
-    maxPayloadBytes: parsed.maxBytes,
-    maxRuntimeMs: parsed.maxRuntimeMs,
-    allowlistPrefixes: STATE_MUTATION_ALLOWLIST_PREFIXES,
+function parseStateArtifactRestoreArgs(kind, args) {
+  const normalizedKind = kind === 'slot' ? 'slot' : 'checkpoint';
+  const reasonCode = `invalid_state_${normalizedKind}_restore_args`;
+  const parsed = {
+    kind: normalizedKind,
+    name: null,
+    artifactPath: null,
+    reportPath: null,
+    file: null,
+    mode: 'headless',
+    frames: 1,
+    schemaVersion: GAME_STATE_SCHEMA_VERSION,
+    compact: false,
+    dryRun: false,
+    verify: false,
+    rollbackOnFail: false,
+    maxOps: DEFAULT_STATE_MUTATION_GUARDRAILS.maxMutations,
+    maxBytes: DEFAULT_STATE_MUTATION_GUARDRAILS.maxPayloadBytes,
+    maxRuntimeMs: DEFAULT_STATE_MUTATION_GUARDRAILS.maxRuntimeMs,
+    auditPath: defaultStateApplyAuditPath(process.cwd()),
   };
-}
 
-function readRequiredOptionValue(args, index, flagName) {
-  const value = args[index + 1];
-  if (!value) {
-    throw new StateExportError('invalid_state_export_args', `Missing value for ${flagName}.`);
+  let formattingFlag = 'pretty';
+
+  for (let i = 0; i < args.length; i += 1) {
+    const token = args[i];
+
+    if (token === '--artifact') {
+      parsed.artifactPath = normalizeStateArtifactFilePath(
+        readRequiredOptionValue(args, i, '--artifact'),
+        '--artifact',
+        reasonCode,
+      );
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--artifact=')) {
+      parsed.artifactPath = normalizeStateArtifactFilePath(
+        token.slice('--artifact='.length),
+        '--artifact',
+        reasonCode,
+      );
+      continue;
+    }
+
+    if (token === '--report') {
+      parsed.reportPath = normalizeStateCommandOutput(
+        readRequiredOptionValue(args, i, '--report'),
+        reasonCode,
+      );
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--report=')) {
+      parsed.reportPath = normalizeStateCommandOutput(token.slice('--report='.length), reasonCode);
+      continue;
+    }
+
+    if (token === '--file') {
+      parsed.file = normalizeStateExportFile(readRequiredOptionValue(args, i, '--file'));
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--file=')) {
+      parsed.file = normalizeStateExportFile(token.slice('--file='.length));
+      continue;
+    }
+
+    if (token === '--mode') {
+      parsed.mode = normalizeStateExportMode(readRequiredOptionValue(args, i, '--mode'));
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--mode=')) {
+      parsed.mode = normalizeStateExportMode(token.slice('--mode='.length));
+      continue;
+    }
+
+    if (token === '--frames') {
+      parsed.frames = parseNonNegativeIntegerArg(readRequiredOptionValue(args, i, '--frames'), '--frames', reasonCode);
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--frames=')) {
+      parsed.frames = parseNonNegativeIntegerArg(token.slice('--frames='.length), '--frames', reasonCode);
+      continue;
+    }
+
+    if (token === '--schema' || token === '--schema-version') {
+      parsed.schemaVersion = normalizeStateExportSchemaVersion(readRequiredOptionValue(args, i, token));
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--schema=')) {
+      parsed.schemaVersion = normalizeStateExportSchemaVersion(token.slice('--schema='.length));
+      continue;
+    }
+    if (token.startsWith('--schema-version=')) {
+      parsed.schemaVersion = normalizeStateExportSchemaVersion(token.slice('--schema-version='.length));
+      continue;
+    }
+
+    if (token === '--dry-run') {
+      parsed.dryRun = true;
+      continue;
+    }
+    if (token === '--verify') {
+      parsed.verify = true;
+      continue;
+    }
+    if (token === '--rollback-on-fail') {
+      parsed.rollbackOnFail = true;
+      continue;
+    }
+
+    if (token === '--max-ops') {
+      parsed.maxOps = parseNonNegativeIntegerArg(readRequiredOptionValue(args, i, '--max-ops'), '--max-ops', reasonCode);
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--max-ops=')) {
+      parsed.maxOps = parseNonNegativeIntegerArg(token.slice('--max-ops='.length), '--max-ops', reasonCode);
+      continue;
+    }
+
+    if (token === '--max-bytes') {
+      parsed.maxBytes = parseNonNegativeIntegerArg(readRequiredOptionValue(args, i, '--max-bytes'), '--max-bytes', reasonCode);
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--max-bytes=')) {
+      parsed.maxBytes = parseNonNegativeIntegerArg(token.slice('--max-bytes='.length), '--max-bytes', reasonCode);
+      continue;
+    }
+
+    if (token === '--max-runtime-ms') {
+      parsed.maxRuntimeMs = parseNonNegativeIntegerArg(readRequiredOptionValue(args, i, '--max-runtime-ms'), '--max-runtime-ms', reasonCode);
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--max-runtime-ms=')) {
+      parsed.maxRuntimeMs = parseNonNegativeIntegerArg(token.slice('--max-runtime-ms='.length), '--max-runtime-ms', reasonCode);
+      continue;
+    }
+
+    if (token === '--audit') {
+      parsed.auditPath = normalizeStateAuditOutput(readRequiredOptionValue(args, i, '--audit'), reasonCode);
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--audit=')) {
+      parsed.auditPath = normalizeStateAuditOutput(token.slice('--audit='.length), reasonCode);
+      continue;
+    }
+
+    if (token === '--compact') {
+      if (formattingFlag === 'pretty') {
+        parsed.compact = true;
+        formattingFlag = 'compact';
+        continue;
+      }
+      if (formattingFlag === 'compact') continue;
+      throw new StateExportError(reasonCode, 'Cannot use --compact and --pretty together.');
+    }
+    if (token === '--pretty') {
+      if (formattingFlag === 'compact') {
+        throw new StateExportError(reasonCode, 'Cannot use --compact and --pretty together.');
+      }
+      parsed.compact = false;
+      formattingFlag = 'pretty';
+      continue;
+    }
+
+    if (token.startsWith('--')) {
+      throw new StateExportError(reasonCode, `Unknown ${normalizedKind} restore option: ${token}`);
+    }
+
+    if (parsed.name !== null) {
+      throw new StateExportError(
+        reasonCode,
+        `Unexpected extra argument "${token}". Usage: aura state ${normalizedKind} restore <name> [options]`,
+      );
+    }
+    parsed.name = normalizeStateArtifactName(token, { kind: normalizedKind });
+  }
+
+  if (!parsed.name && !parsed.artifactPath) {
+    throw new StateExportError(
+      reasonCode,
+      `Missing ${normalizedKind} name. Usage: aura state ${normalizedKind} restore <name> [options]`,
+    );
+  }
+  if (parsed.schemaVersion !== GAME_STATE_SCHEMA_VERSION) {
+    throw new StateExportError(
+      'schema_version_mismatch',
+      `Unsupported schema version "${parsed.schemaVersion}". Expected "${GAME_STATE_SCHEMA_VERSION}".`,
+    );
+  }
+  if (parsed.dryRun && parsed.rollbackOnFail) {
+    throw new StateExportError(reasonCode, '--rollback-on-fail cannot be combined with --dry-run.');
+  }
+  if (!parsed.reportPath && parsed.auditPath === null) {
+    throw new StateExportError(
+      reasonCode,
+      '--audit - cannot be combined with report output to stdout; set --report <file> or --audit <file>.',
+    );
+  }
+
+  return parsed;
+}
+
+function parseStateArtifactListArgs(kind, args) {
+  const normalizedKind = kind === 'slot' ? 'slot' : 'checkpoint';
+  const reasonCode = `invalid_state_${normalizedKind}_list_args`;
+  const parsed = {
+    kind: normalizedKind,
+    reportPath: null,
+    compact: false,
+  };
+  let formattingFlag = 'pretty';
+
+  for (let i = 0; i < args.length; i += 1) {
+    const token = args[i];
+
+    if (token === '--report') {
+      parsed.reportPath = normalizeStateCommandOutput(
+        readRequiredOptionValue(args, i, '--report'),
+        reasonCode,
+      );
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--report=')) {
+      parsed.reportPath = normalizeStateCommandOutput(token.slice('--report='.length), reasonCode);
+      continue;
+    }
+    if (token === '--compact') {
+      if (formattingFlag === 'pretty') {
+        parsed.compact = true;
+        formattingFlag = 'compact';
+        continue;
+      }
+      if (formattingFlag === 'compact') continue;
+      throw new StateExportError(reasonCode, 'Cannot use --compact and --pretty together.');
+    }
+    if (token === '--pretty') {
+      if (formattingFlag === 'compact') {
+        throw new StateExportError(reasonCode, 'Cannot use --compact and --pretty together.');
+      }
+      parsed.compact = false;
+      formattingFlag = 'pretty';
+      continue;
+    }
+    throw new StateExportError(reasonCode, `Unknown ${normalizedKind} list option: ${token}`);
+  }
+
+  return parsed;
+}
+
+function normalizeStateCommandInputPath(value, flagName, reasonCode) {
+  const normalized = String(value || '').trim();
+  if (normalized.length === 0) {
+    throw new StateExportError(reasonCode, `${flagName} requires a non-empty file path.`);
+  }
+  return resolve(process.cwd(), normalized);
+}
+
+function normalizeStateCommandOutput(value, reasonCode) {
+  const normalized = String(value || '').trim();
+  if (normalized.length === 0) {
+    throw new StateExportError(reasonCode, '--output requires a non-empty path or "-".');
+  }
+  if (normalized === '-') {
+    return null;
+  }
+  return resolve(process.cwd(), normalized);
+}
+
+function normalizeStateAuditOutput(value, reasonCode) {
+  const normalized = String(value || '').trim();
+  if (normalized.length === 0) {
+    throw new StateExportError(reasonCode, '--audit requires a non-empty path or "-".');
+  }
+  if (normalized === '-') {
+    return null;
+  }
+  return resolve(process.cwd(), normalized);
+}
+
+function normalizeStateArtifactFilePath(value, flagName, reasonCode) {
+  const normalized = String(value || '').trim();
+  if (normalized.length === 0 || normalized === '-') {
+    throw new StateExportError(reasonCode, `${flagName} requires a writable file path.`);
+  }
+  return resolve(process.cwd(), normalized);
+}
+
+function normalizeOptionalNote(value) {
+  const normalized = String(value || '').trim();
+  return normalized.length > 0 ? normalized : null;
+}
+
+function defaultStatePatchAuditPath(projectRoot) {
+  return resolve(projectRoot, '.aura/state/state-patch-audit.json');
+}
+
+function defaultStateApplyAuditPath(projectRoot) {
+  return resolve(projectRoot, '.aura/state/state-apply-audit.json');
+}
+
+function readJsonInputFile(filePath, label, reasonCodePrefix) {
+  let text;
+  try {
+    text = readFileSync(filePath, 'utf8');
+  } catch (error) {
+    throw new StateExportError(
+      `${reasonCodePrefix}_read_failed`,
+      `Failed to read ${label} "${filePath}": ${error.message}`,
+    );
+  }
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    throw new StateExportError(
+      `${reasonCodePrefix}_invalid_json`,
+      `${label} "${filePath}" is not valid JSON: ${error.message}`,
+    );
+  }
+}
+
+function writeStateJsonOutput(filePath, jsonText, reasonCode) {
+  if (!filePath) {
+    process.stdout.write(jsonText);
+    return;
+  }
+
+  try {
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, jsonText, 'utf8');
+  } catch (error) {
+    throw new StateExportError(
+      reasonCode,
+      `Failed to write state output "${filePath}": ${error.message}`,
+    );
+  }
+}
+
+function writeStateMutationAudit(auditPath, payload) {
+  const text = `${JSON.stringify(payload, null, 2)}\n`;
+  if (auditPath === null) {
+    process.stdout.write(text);
+    return;
+  }
+  try {
+    mkdirSync(dirname(auditPath), { recursive: true });
+    writeFileSync(auditPath, text, 'utf8');
+  } catch (error) {
+    throw new StateExportError(
+      'state_mutation_audit_write_failed',
+      `Failed to write state mutation audit "${auditPath}": ${error.message}`,
+    );
+  }
+}
+
+function jsonByteSize(value) {
+  let text = '';
+  try {
+    text = JSON.stringify(value);
+  } catch {
+    text = '';
+  }
+  return Buffer.byteLength(text || '', 'utf8');
+}
+
+function mutationGuardrailsFromParsed(parsed) {
+  return {
+    maxMutations: parsed.maxOps,
+    maxPayloadBytes: parsed.maxBytes,
+    maxRuntimeMs: parsed.maxRuntimeMs,
+    allowlistPrefixes: STATE_MUTATION_ALLOWLIST_PREFIXES,
+  };
+}
+
+function readRequiredOptionValue(args, index, flagName) {
+  const value = args[index + 1];
+  if (!value) {
+    throw new StateExportError('invalid_state_export_args', `Missing value for ${flagName}.`);
   }
   return value;
 }
@@ -1199,7 +1769,7 @@ async function cmdInit(args) {
 async function cmdCreate(args) {
   const parsed = parseCreateArgs(args);
   if (!parsed.name) {
-    error('Missing project name. Usage: aura create <name> [--template <2d-shooter|3d-platformer|blank>] [--skip-install]');
+    error(`Missing project name. Usage: ${CREATE_USAGE}`);
   }
 
   const name = parsed.name;
@@ -1372,14 +1942,22 @@ async function cmdDevWeb(_args) {
   });
 }
 
-async function cmdDevNative() {
+async function cmdDevNative(devArgs = {}) {
   const projectRoot = process.cwd();
   const config = await loadConfig({ projectRoot, mode: 'dev' });
   const identity = resolveBuildIdentity(config);
   const hostBinary = resolveAndCacheHostBinary();
+  const devEntry = devArgs.restoreKind
+    ? prepareDevStateRestoreEntry({
+      projectRoot,
+      entryFile: config.build.entry,
+      artifactKind: devArgs.restoreKind,
+      artifactName: devArgs.restoreName,
+    })
+    : null;
   const incremental = createIncrementalBundler({
     projectRoot,
-    entryFile: config.build.entry,
+    entryFile: devEntry ? devEntry.entryFile : config.build.entry,
   });
 
   let shuttingDown = false;
@@ -1508,6 +2086,11 @@ async function cmdDevNative() {
   for (const diagnostic of hostBinary.diagnostics || []) {
     console.log(`  Host diagnostic: ${diagnostic}`);
   }
+  if (devEntry) {
+    console.log(`  Dev restore: ${devEntry.artifact.kind} "${devEntry.artifact.name}"`);
+    console.log(`  Dev restore artifact: ${devEntry.artifactPath}`);
+    console.log(`  Dev restore wrapper: ${devEntry.wrapperPath}`);
+  }
   startHost(initial.outFile, 'initial');
   console.log('\n  Watching src/ for changes... (Ctrl+C to stop)');
 
@@ -1553,12 +2136,19 @@ async function cmdDevNative() {
 }
 
 async function cmdDev(args) {
-  const target = parseTarget(args);
+  const parsed = parseDevArgs(args);
+  const target = parsed.target || parseTarget(args);
   if (target === 'web') {
+    if (parsed.restoreKind) {
+      throw new StateExportError(
+        'invalid_dev_args',
+        '--restore-slot and --restore-checkpoint are only supported for native `aura dev`.',
+      );
+    }
     await cmdDevWeb(args);
     return;
   }
-  await cmdDevNative(args);
+  await cmdDevNative(parsed);
 }
 
 async function cmdBuild(args) {
@@ -1805,8 +2395,7 @@ async function cmdTest(args) {
   console.log('');
 }
 
-async function cmdStateExport(args) {
-  const parsed = parseStateExportArgs(args);
+async function runStateExportPayload(parsed) {
   const projectRoot = process.cwd();
   const config = await loadConfig({ projectRoot, mode: 'build' });
   const file = parsed.file || config.build.entry;
@@ -1819,210 +2408,87 @@ async function cmdStateExport(args) {
       frames: parsed.frames,
       mode: parsed.mode,
       frameIndex: parsed.frames,
-    });
-  } catch (error) {
-    if (error instanceof HeadlessTestError) {
-      throw new StateExportError(
-        'state_export_runtime_failed',
-        error.message,
-      );
-    }
-    throw error;
-  }
-
-  const exportResult = runResult.exportResult;
-  if (!exportResult || typeof exportResult !== 'object') {
-    throw new StateExportError(
-      'state_export_runtime_failed',
-      'State export runtime returned an invalid export result.',
-    );
-  }
-  if (exportResult.ok !== true) {
-    throw new StateExportError(
-      typeof exportResult.reasonCode === 'string' ? exportResult.reasonCode : 'state_export_failed',
-      'State export hook returned a failure result.',
-      { exportResult },
-    );
-  }
-  if (!exportResult.payload || typeof exportResult.payload !== 'object') {
-    throw new StateExportError(
-      'state_export_invalid_payload',
-      'State export hook returned an invalid payload.',
-      { exportResult },
-    );
-  }
-  if (exportResult.payload.schemaVersion !== parsed.schemaVersion) {
-    throw new StateExportError(
-      'schema_version_mismatch',
-      `Exported schema "${exportResult.payload.schemaVersion}" does not match requested schema "${parsed.schemaVersion}".`,
-      { exported: exportResult.payload.schemaVersion, requested: parsed.schemaVersion },
-    );
-  }
-
-  const jsonText = parsed.compact
-    ? `${JSON.stringify(exportResult.payload)}\n`
-    : `${JSON.stringify(exportResult.payload, null, 2)}\n`;
-
-  writeStateJsonOutput(parsed.outputPath, jsonText, 'state_export_output_write_failed');
-}
-
-async function cmdStateDiff(args) {
-  const parsed = parseStateDiffArgs(args);
-  const beforePayload = readJsonInputFile(parsed.beforePath, 'state diff before payload', 'state_diff_before');
-  const afterPayload = readJsonInputFile(parsed.afterPath, 'state diff after payload', 'state_diff_after');
-
-  const diffResult = diffCanonicalGameState(beforePayload, afterPayload);
-  if (!diffResult.ok) {
-    throw new StateExportError(
-      typeof diffResult.reasonCode === 'string' ? diffResult.reasonCode : 'state_diff_failed',
-      'State diff operation failed.',
-      { diffResult },
-    );
-  }
-  if (!diffResult.patch || typeof diffResult.patch !== 'object') {
-    throw new StateExportError('state_diff_failed', 'State diff returned an invalid patch payload.');
-  }
-  if (diffResult.patch.schemaVersion !== parsed.schemaVersion) {
-    throw new StateExportError(
-      'schema_version_mismatch',
-      `Diff schema "${diffResult.patch.schemaVersion}" does not match requested schema "${parsed.schemaVersion}".`,
-    );
-  }
-
-  const jsonText = parsed.compact
-    ? `${JSON.stringify(diffResult.patch)}\n`
-    : `${JSON.stringify(diffResult.patch, null, 2)}\n`;
-  writeStateJsonOutput(parsed.outputPath, jsonText, 'state_diff_output_write_failed');
-}
-
-async function cmdStatePatch(args) {
-  const projectRoot = process.cwd();
-  let parsed = null;
-  let auditPath = defaultStatePatchAuditPath(projectRoot);
-  let pendingError = null;
-  const audit = {
-    schemaVersion: STATE_MUTATION_AUDIT_SCHEMA_VERSION,
-    command: 'state.patch',
-    ok: false,
-    reasonCode: 'state_patch_failed',
-    limits: {
-      maxOps: DEFAULT_STATE_MUTATION_GUARDRAILS.maxMutations,
-      maxBytes: DEFAULT_STATE_MUTATION_GUARDRAILS.maxPayloadBytes,
-      maxRuntimeMs: DEFAULT_STATE_MUTATION_GUARDRAILS.maxRuntimeMs,
-    },
-    allowlistPrefixes: [...STATE_MUTATION_ALLOWLIST_PREFIXES],
-    io: {
-      statePath: null,
-      patchPath: null,
-      outputPath: '-',
-      auditPath: auditPath,
-    },
-    metrics: {
-      statePayloadBytes: 0,
-      patchPayloadBytes: 0,
-      outputPayloadBytes: 0,
-      mutationCount: 0,
-      appliedMutations: 0,
-    },
-    detail: null,
-  };
-
-  try {
-    parsed = parseStatePatchArgs(args);
-    auditPath = parsed.auditPath;
-    audit.io.statePath = parsed.statePath;
-    audit.io.patchPath = parsed.patchPath;
-    audit.io.outputPath = parsed.outputPath || '-';
-    audit.io.auditPath = parsed.auditPath || '-';
-    audit.limits = {
-      maxOps: parsed.maxOps,
-      maxBytes: parsed.maxBytes,
-      maxRuntimeMs: parsed.maxRuntimeMs,
-    };
-
-    const statePayload = readJsonInputFile(parsed.statePath, 'state payload', 'state_patch_state');
-    const patchPayload = readJsonInputFile(parsed.patchPath, 'state patch payload', 'state_patch_patch');
-    audit.metrics.statePayloadBytes = jsonByteSize(statePayload);
-    audit.metrics.patchPayloadBytes = jsonByteSize(patchPayload);
-    audit.metrics.mutationCount = Array.isArray(patchPayload?.mutations) ? patchPayload.mutations.length : 0;
-
-    const patchResult = applyCanonicalStatePatch(
-      statePayload,
-      patchPayload,
-      mutationGuardrailsFromParsed(parsed),
-    );
-    if (!patchResult.ok) {
-      throw new StateExportError(
-        typeof patchResult.reasonCode === 'string' ? patchResult.reasonCode : 'state_patch_failed',
-        'State patch operation failed.',
-        { patchResult },
-      );
-    }
-    if (!patchResult.payload || typeof patchResult.payload !== 'object') {
-      throw new StateExportError('state_patch_failed', 'State patch returned an invalid payload.');
-    }
-    if (patchResult.payload.schemaVersion !== parsed.schemaVersion) {
-      throw new StateExportError(
-        'schema_version_mismatch',
-        `Patched schema "${patchResult.payload.schemaVersion}" does not match requested schema "${parsed.schemaVersion}".`,
-      );
-    }
-
-    const jsonText = parsed.compact
-      ? `${JSON.stringify(patchResult.payload)}\n`
-      : `${JSON.stringify(patchResult.payload, null, 2)}\n`;
-    writeStateJsonOutput(parsed.outputPath, jsonText, 'state_patch_output_write_failed');
-
-    audit.ok = true;
-    audit.reasonCode = 'state_patch_ok';
-    audit.metrics.outputPayloadBytes = jsonByteSize(patchResult.payload);
-    audit.metrics.appliedMutations = Number.isInteger(patchResult.appliedMutations) ? patchResult.appliedMutations : 0;
+    });
   } catch (error) {
-    pendingError = error;
-    audit.ok = false;
-    audit.reasonCode = error instanceof StateExportError
-      ? error.reasonCode
-      : 'state_patch_failed';
-    audit.detail = error instanceof Error ? error.message : String(error);
+    if (error instanceof HeadlessTestError) {
+      throw new StateExportError('state_export_runtime_failed', error.message);
+    }
+    throw error;
   }
 
-  writeStateMutationAudit(auditPath, audit);
-  if (pendingError) {
-    throw pendingError;
+  const exportResult = runResult.exportResult;
+  if (!exportResult || typeof exportResult !== 'object') {
+    throw new StateExportError(
+      'state_export_runtime_failed',
+      'State export runtime returned an invalid export result.',
+    );
+  }
+  if (exportResult.ok !== true) {
+    throw new StateExportError(
+      typeof exportResult.reasonCode === 'string' ? exportResult.reasonCode : 'state_export_failed',
+      'State export hook returned a failure result.',
+      { exportResult },
+    );
+  }
+  if (!exportResult.payload || typeof exportResult.payload !== 'object') {
+    throw new StateExportError(
+      'state_export_invalid_payload',
+      'State export hook returned an invalid payload.',
+      { exportResult },
+    );
+  }
+  if (exportResult.payload.schemaVersion !== parsed.schemaVersion) {
+    throw new StateExportError(
+      'schema_version_mismatch',
+      `Exported schema "${exportResult.payload.schemaVersion}" does not match requested schema "${parsed.schemaVersion}".`,
+      { exported: exportResult.payload.schemaVersion, requested: parsed.schemaVersion },
+    );
   }
+
+  return {
+    projectRoot,
+    file,
+    payload: exportResult.payload,
+  };
 }
 
-async function cmdStateApply(args) {
-  const projectRoot = process.cwd();
-  let parsed = null;
-  let auditPath = defaultStateApplyAuditPath(projectRoot);
-  let pendingError = null;
+async function executeStateApplyOperation({
+  parsed,
+  payload,
+  projectRoot = process.cwd(),
+  file,
+  outputPath = null,
+  auditPath = defaultStateApplyAuditPath(projectRoot),
+  inputPathLabel = null,
+  commandName = 'state.apply',
+  artifactMetadata = null,
+}) {
   const audit = {
     schemaVersion: STATE_MUTATION_AUDIT_SCHEMA_VERSION,
-    command: 'state.apply',
+    command: commandName,
     ok: false,
     reasonCode: 'state_apply_failed',
     limits: {
-      maxOps: DEFAULT_STATE_MUTATION_GUARDRAILS.maxMutations,
-      maxBytes: DEFAULT_STATE_MUTATION_GUARDRAILS.maxPayloadBytes,
-      maxRuntimeMs: DEFAULT_STATE_MUTATION_GUARDRAILS.maxRuntimeMs,
+      maxOps: parsed.maxOps,
+      maxBytes: parsed.maxBytes,
+      maxRuntimeMs: parsed.maxRuntimeMs,
     },
     allowlistPrefixes: [...STATE_MUTATION_ALLOWLIST_PREFIXES],
     io: {
-      statePath: null,
-      file: null,
-      outputPath: '-',
-      auditPath: auditPath,
+      statePath: inputPathLabel || '-',
+      file,
+      outputPath: outputPath || '-',
+      auditPath: auditPath || '-',
     },
     metrics: {
-      payloadBytes: 0,
+      payloadBytes: jsonByteSize(payload),
       outputPayloadBytes: 0,
       mutationCount: 0,
     },
     result: {
-      dryRun: false,
-      verify: false,
-      rollbackOnFail: false,
+      dryRun: parsed.dryRun === true,
+      verify: parsed.verify === true,
+      rollbackOnFail: parsed.rollbackOnFail === true,
       applied: false,
       verified: false,
       rolledBack: false,
@@ -2033,27 +2499,16 @@ async function cmdStateApply(args) {
     detail: null,
   };
 
-  try {
-    parsed = parseStateApplyArgs(args);
-    auditPath = parsed.auditPath;
-    audit.io.statePath = parsed.statePath;
-    audit.io.outputPath = parsed.outputPath || '-';
-    audit.io.auditPath = parsed.auditPath || '-';
-    audit.limits = {
-      maxOps: parsed.maxOps,
-      maxBytes: parsed.maxBytes,
-      maxRuntimeMs: parsed.maxRuntimeMs,
+  if (artifactMetadata) {
+    audit.artifact = {
+      kind: artifactMetadata.kind,
+      name: artifactMetadata.name,
+      path: artifactMetadata.path,
+      payloadFingerprint: artifactMetadata.payloadFingerprint || null,
     };
-    audit.result.dryRun = parsed.dryRun === true;
-    audit.result.verify = parsed.verify === true;
-    audit.result.rollbackOnFail = parsed.rollbackOnFail === true;
-
-    const config = await loadConfig({ projectRoot, mode: 'build' });
-    const file = parsed.file || config.build.entry;
-    audit.io.file = file;
-    const payload = readJsonInputFile(parsed.statePath, 'state apply payload', 'state_apply_input');
-    audit.metrics.payloadBytes = jsonByteSize(payload);
+  }
 
+  try {
     if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
       throw new StateExportError('invalid_schema_payload', 'State apply payload must be a JSON object.');
     }
@@ -2088,6 +2543,7 @@ async function cmdStateApply(args) {
     if (!runResult || typeof runResult !== 'object') {
       throw new StateExportError('state_apply_runtime_failed', 'State apply runtime returned an invalid result.');
     }
+
     if (runResult.ok !== true) {
       const failureReport = {
         ok: false,
@@ -2103,12 +2559,16 @@ async function cmdStateApply(args) {
         baselineFingerprint: runResult.baselineFingerprint || null,
         finalFingerprint: runResult.finalFingerprint || null,
       };
-      if (parsed.outputPath) {
+      if (artifactMetadata) {
+        failureReport.artifact = artifactMetadata;
+      }
+      if (outputPath) {
         const failureText = parsed.compact
           ? `${JSON.stringify(failureReport)}\n`
           : `${JSON.stringify(failureReport, null, 2)}\n`;
-        writeStateJsonOutput(parsed.outputPath, failureText, 'state_apply_output_write_failed');
+        writeStateJsonOutput(outputPath, failureText, 'state_apply_output_write_failed');
       }
+
       audit.ok = false;
       audit.reasonCode = failureReport.reasonCode;
       audit.metrics.mutationCount = failureReport.mutationCount;
@@ -2123,6 +2583,7 @@ async function cmdStateApply(args) {
         baselineFingerprint: failureReport.baselineFingerprint,
         finalFingerprint: failureReport.finalFingerprint,
       };
+
       throw new StateExportError(
         failureReport.reasonCode,
         'State apply operation failed.',
@@ -2143,15 +2604,17 @@ async function cmdStateApply(args) {
       baselineFingerprint: runResult.baselineFingerprint || null,
       finalFingerprint: runResult.finalFingerprint || null,
     };
-
     if (runResult.previewPatch && typeof runResult.previewPatch === 'object') {
       report.previewPatch = runResult.previewPatch;
     }
+    if (artifactMetadata) {
+      report.artifact = artifactMetadata;
+    }
 
     const jsonText = parsed.compact
       ? `${JSON.stringify(report)}\n`
       : `${JSON.stringify(report, null, 2)}\n`;
-    writeStateJsonOutput(parsed.outputPath, jsonText, 'state_apply_output_write_failed');
+    writeStateJsonOutput(outputPath, jsonText, 'state_apply_output_write_failed');
 
     audit.ok = true;
     audit.reasonCode = report.reasonCode;
@@ -2168,12 +2631,144 @@ async function cmdStateApply(args) {
       baselineFingerprint: report.baselineFingerprint,
       finalFingerprint: report.finalFingerprint,
     };
+
+    return report;
   } catch (error) {
-    pendingError = error;
-    if (error instanceof StateExportError) {
-      audit.reasonCode = error.reasonCode;
+    audit.reasonCode = error instanceof StateExportError ? error.reasonCode : 'state_apply_failed';
+    audit.detail = error instanceof Error ? error.message : String(error);
+    throw error;
+  } finally {
+    writeStateMutationAudit(auditPath, audit);
+  }
+}
+
+async function cmdStateExport(args) {
+  const parsed = parseStateExportArgs(args);
+  const { payload } = await runStateExportPayload(parsed);
+  const jsonText = parsed.compact
+    ? `${JSON.stringify(payload)}\n`
+    : `${JSON.stringify(payload, null, 2)}\n`;
+
+  writeStateJsonOutput(parsed.outputPath, jsonText, 'state_export_output_write_failed');
+}
+
+async function cmdStateDiff(args) {
+  const parsed = parseStateDiffArgs(args);
+  const beforePayload = readJsonInputFile(parsed.beforePath, 'state diff before payload', 'state_diff_before');
+  const afterPayload = readJsonInputFile(parsed.afterPath, 'state diff after payload', 'state_diff_after');
+
+  const diffResult = diffCanonicalGameState(beforePayload, afterPayload);
+  if (!diffResult.ok) {
+    throw new StateExportError(
+      typeof diffResult.reasonCode === 'string' ? diffResult.reasonCode : 'state_diff_failed',
+      'State diff operation failed.',
+      { diffResult },
+    );
+  }
+  if (!diffResult.patch || typeof diffResult.patch !== 'object') {
+    throw new StateExportError('state_diff_failed', 'State diff returned an invalid patch payload.');
+  }
+  if (diffResult.patch.schemaVersion !== parsed.schemaVersion) {
+    throw new StateExportError(
+      'schema_version_mismatch',
+      `Diff schema "${diffResult.patch.schemaVersion}" does not match requested schema "${parsed.schemaVersion}".`,
+    );
+  }
+
+  const jsonText = parsed.compact
+    ? `${JSON.stringify(diffResult.patch)}\n`
+    : `${JSON.stringify(diffResult.patch, null, 2)}\n`;
+  writeStateJsonOutput(parsed.outputPath, jsonText, 'state_diff_output_write_failed');
+}
+
+async function cmdStatePatch(args) {
+  const projectRoot = process.cwd();
+  let parsed = null;
+  let auditPath = defaultStatePatchAuditPath(projectRoot);
+  let pendingError = null;
+  const audit = {
+    schemaVersion: STATE_MUTATION_AUDIT_SCHEMA_VERSION,
+    command: 'state.patch',
+    ok: false,
+    reasonCode: 'state_patch_failed',
+    limits: {
+      maxOps: DEFAULT_STATE_MUTATION_GUARDRAILS.maxMutations,
+      maxBytes: DEFAULT_STATE_MUTATION_GUARDRAILS.maxPayloadBytes,
+      maxRuntimeMs: DEFAULT_STATE_MUTATION_GUARDRAILS.maxRuntimeMs,
+    },
+    allowlistPrefixes: [...STATE_MUTATION_ALLOWLIST_PREFIXES],
+    io: {
+      statePath: null,
+      patchPath: null,
+      outputPath: '-',
+      auditPath: auditPath,
+    },
+    metrics: {
+      statePayloadBytes: 0,
+      patchPayloadBytes: 0,
+      outputPayloadBytes: 0,
+      mutationCount: 0,
+      appliedMutations: 0,
+    },
+    detail: null,
+  };
+
+  try {
+    parsed = parseStatePatchArgs(args);
+    auditPath = parsed.auditPath;
+    audit.io.statePath = parsed.statePath;
+    audit.io.patchPath = parsed.patchPath;
+    audit.io.outputPath = parsed.outputPath || '-';
+    audit.io.auditPath = parsed.auditPath || '-';
+    audit.limits = {
+      maxOps: parsed.maxOps,
+      maxBytes: parsed.maxBytes,
+      maxRuntimeMs: parsed.maxRuntimeMs,
+    };
+
+    const statePayload = readJsonInputFile(parsed.statePath, 'state payload', 'state_patch_state');
+    const patchPayload = readJsonInputFile(parsed.patchPath, 'state patch payload', 'state_patch_patch');
+    audit.metrics.statePayloadBytes = jsonByteSize(statePayload);
+    audit.metrics.patchPayloadBytes = jsonByteSize(patchPayload);
+    audit.metrics.mutationCount = Array.isArray(patchPayload?.mutations) ? patchPayload.mutations.length : 0;
+
+    const patchResult = applyCanonicalStatePatch(
+      statePayload,
+      patchPayload,
+      mutationGuardrailsFromParsed(parsed),
+    );
+    if (!patchResult.ok) {
+      throw new StateExportError(
+        typeof patchResult.reasonCode === 'string' ? patchResult.reasonCode : 'state_patch_failed',
+        'State patch operation failed.',
+        { patchResult },
+      );
+    }
+    if (!patchResult.payload || typeof patchResult.payload !== 'object') {
+      throw new StateExportError('state_patch_failed', 'State patch returned an invalid payload.');
+    }
+    if (patchResult.payload.schemaVersion !== parsed.schemaVersion) {
+      throw new StateExportError(
+        'schema_version_mismatch',
+        `Patched schema "${patchResult.payload.schemaVersion}" does not match requested schema "${parsed.schemaVersion}".`,
+      );
     }
+
+    const jsonText = parsed.compact
+      ? `${JSON.stringify(patchResult.payload)}\n`
+      : `${JSON.stringify(patchResult.payload, null, 2)}\n`;
+    writeStateJsonOutput(parsed.outputPath, jsonText, 'state_patch_output_write_failed');
+
+    audit.ok = true;
+    audit.reasonCode = 'state_patch_ok';
+    audit.metrics.outputPayloadBytes = jsonByteSize(patchResult.payload);
+    audit.metrics.appliedMutations = Number.isInteger(patchResult.appliedMutations) ? patchResult.appliedMutations : 0;
+  } catch (error) {
+    pendingError = error;
     audit.ok = false;
+    audit.reasonCode = error instanceof StateExportError
+      ? error.reasonCode
+      : 'state_patch_failed';
     audit.detail = error instanceof Error ? error.message : String(error);
   }
 
@@ -2183,12 +2778,115 @@ async function cmdStateApply(args) {
   }
 }
 
+async function cmdStateApply(args) {
+  const projectRoot = process.cwd();
+  const parsed = parseStateApplyArgs(args);
+  const config = await loadConfig({ projectRoot, mode: 'build' });
+  const file = parsed.file || config.build.entry;
+  const payload = readJsonInputFile(parsed.statePath, 'state apply payload', 'state_apply_input');
+
+  await executeStateApplyOperation({
+    parsed,
+    payload,
+    projectRoot,
+    file,
+    outputPath: parsed.outputPath,
+    auditPath: parsed.auditPath,
+    inputPathLabel: parsed.statePath,
+    commandName: 'state.apply',
+  });
+}
+
+async function cmdStateArtifactSave(kind, args) {
+  const parsed = parseStateArtifactSaveArgs(kind, args);
+  const { projectRoot, file, payload } = await runStateExportPayload(parsed);
+  const artifactPath = parsed.artifactPath || resolveStateArtifactPath(projectRoot, parsed.kind, parsed.name);
+  const envelope = createStateArtifactEnvelope({
+    kind: parsed.kind,
+    name: parsed.name,
+    payload,
+    note: parsed.note,
+    source: {
+      mode: parsed.mode,
+      frames: parsed.frames,
+      file,
+      reportPath: parsed.reportPath || '-',
+    },
+  });
+  writeStateArtifactEnvelope(artifactPath, envelope);
+
+  const report = {
+    ok: true,
+    reasonCode: parsed.kind === 'slot' ? 'state_slot_saved' : 'state_checkpoint_saved',
+    artifact: {
+      kind: parsed.kind,
+      name: parsed.name,
+      path: artifactPath,
+      createdAt: envelope.createdAt,
+      note: envelope.note || null,
+      stateSchemaVersion: envelope.stateSchemaVersion,
+      payloadFingerprint: envelope.payloadFingerprint,
+      mode: payload?.export?.mode || null,
+      frameIndex: payload?.export?.frameIndex ?? null,
+      elapsedSeconds: payload?.export?.elapsedSeconds ?? null,
+    },
+  };
+
+  const jsonText = parsed.compact
+    ? `${JSON.stringify(report)}\n`
+    : `${JSON.stringify(report, null, 2)}\n`;
+  writeStateJsonOutput(parsed.reportPath, jsonText, 'state_artifact_report_write_failed');
+}
+
+async function cmdStateArtifactRestore(kind, args) {
+  const projectRoot = process.cwd();
+  const parsed = parseStateArtifactRestoreArgs(kind, args);
+  const artifact = loadStateArtifact({
+    projectRoot,
+    kind: parsed.kind,
+    name: parsed.name,
+    artifactPath: parsed.artifactPath,
+  });
+  const config = await loadConfig({ projectRoot, mode: 'build' });
+  const file = parsed.file || config.build.entry;
+
+  await executeStateApplyOperation({
+    parsed,
+    payload: artifact.envelope.payload,
+    projectRoot,
+    file,
+    outputPath: parsed.reportPath,
+    auditPath: parsed.auditPath,
+    inputPathLabel: artifact.filePath,
+    commandName: parsed.kind === 'slot' ? 'state.slot.restore' : 'state.checkpoint.restore',
+    artifactMetadata: artifact.metadata,
+  });
+}
+
+async function cmdStateArtifactList(kind, args) {
+  const projectRoot = process.cwd();
+  const parsed = parseStateArtifactListArgs(kind, args);
+  const listing = listStateArtifacts(projectRoot, parsed.kind);
+  const report = {
+    ok: true,
+    reasonCode: parsed.kind === 'slot' ? 'state_slot_list_ok' : 'state_checkpoint_list_ok',
+    kind: parsed.kind,
+    directory: listing.directory,
+    artifacts: listing.artifacts,
+    invalidArtifacts: listing.invalidArtifacts,
+  };
+  const jsonText = parsed.compact
+    ? `${JSON.stringify(report)}\n`
+    : `${JSON.stringify(report, null, 2)}\n`;
+  writeStateJsonOutput(parsed.reportPath, jsonText, 'state_artifact_report_write_failed');
+}
+
 async function cmdState(args) {
   const subcommand = args[0];
   if (!subcommand) {
     throw new StateExportError(
       'state_subcommand_required',
-      'Missing state subcommand. Usage: aura state <export|diff|patch> [options]',
+      'Missing state subcommand. Usage: aura state <export|diff|patch|apply|slot|checkpoint> [options]',
     );
   }
 
@@ -2212,9 +2910,35 @@ async function cmdState(args) {
     return;
   }
 
+  if (subcommand === 'slot' || subcommand === 'checkpoint') {
+    const artifactAction = args[1];
+    if (!artifactAction) {
+      throw new StateExportError(
+        'state_subcommand_unsupported',
+        `Missing ${subcommand} action. Supported actions: save, restore, list.`,
+      );
+    }
+    if (artifactAction === 'save') {
+      await cmdStateArtifactSave(subcommand, args.slice(2));
+      return;
+    }
+    if (artifactAction === 'restore') {
+      await cmdStateArtifactRestore(subcommand, args.slice(2));
+      return;
+    }
+    if (artifactAction === 'list') {
+      await cmdStateArtifactList(subcommand, args.slice(2));
+      return;
+    }
+    throw new StateExportError(
+      'state_subcommand_unsupported',
+      `Unknown ${subcommand} action "${artifactAction}". Supported actions: save, restore, list.`,
+    );
+  }
+
   throw new StateExportError(
     'state_subcommand_unsupported',
-    `Unknown state subcommand "${subcommand}". Supported subcommands: export, diff, patch, apply.`,
+    `Unknown state subcommand "${subcommand}". Supported subcommands: export, diff, patch, apply, slot, checkpoint.`,
   );
 }
 
@@ -2280,6 +3004,9 @@ async function main() {
     if (err instanceof StateExportError) {
       error(`${err.message} (reasonCode=${err.reasonCode})`, 6);
     }
+    if (err instanceof StateArtifactError) {
+      error(`${err.message} (reasonCode=${err.reasonCode})`, 6);
+    }
     if (err instanceof HeadlessTestError) {
       if (Array.isArray(err.details?.failures) && err.details.failures.length > 0) {
         console.error('\n  aura test failures:');