enigma-memory 0.1.10 → 0.1.12

package/apps/cli/bin/enigma.mjs

@@ -3,7 +3,7 @@ import { createHash } from 'node:crypto';
 import { createServer as createHttpServer } from 'node:http';
 import { realpathSync } from 'node:fs';
 import { access, mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
-import { dirname, resolve } from 'node:path';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { createVault, remember, recall, updateMemory, deleteMemory, exportBundle } from '../../../packages/vault/src/index.js';
 import { createPassport, compileContextPack } from '../../../packages/passport/src/index.js';
@@ -30,8 +30,24 @@ import {
   createSettlementBatch,
   verifyServiceSettlementReceipt,
 } from '../../../packages/settlement/src/index.js';
+import {
+  assertNoPrivateProofPayload,
+  createBenchmarkAttestation,
+  createCapabilityGrant,
+  createCapabilityRevocation,
+  createProofNetworkAnchorBatch,
+  sha256Json as proofNetworkSha256Json,
+  validateBenchmarkAttestation,
+  validateCapabilityGrant,
+  validateCapabilityRevocation,
+  validateProofNetworkAnchorBatch,
+  validateProofNetworkPacket,
+} from '../../../packages/proof-network/src/index.js';
 
 const DEFAULT_BUNDLE = '.enigma/bundle.json';
+const DEFAULT_TEST_DRIVE_DIR = '.enigma/test-drive';
+const DEFAULT_TEST_DRIVE_BUNDLE_NAME = 'bundle.json';
+const DEFAULT_TEST_DRIVE_CROSS_MODEL_REPORT_NAME = 'cross-model-report.json';
 export const DEFAULT_RELAY_PORT = 8787;
 export const DEFAULT_GATEWAY_PORT = 8797;
 const DEFAULT_QUICKSTART_MEMORY = 'Enigma quickstart demo memory: local proof bundles can be created and verified without provider or cloud credentials.';
@@ -279,10 +295,10 @@ function quickstartOutputs(bundleInput, outDirInput) {
   };
 }
 
-async function buildQuickstartArtifacts(flags, { bundleInput = DEFAULT_BUNDLE, outDirInput = dirname(bundleInput), overwrite = false, write = true } = {}) {
+async function buildQuickstartArtifacts(flags, { bundleInput = DEFAULT_BUNDLE, outDirInput = dirname(bundleInput), overwrite = false, write = true, checkExisting = true } = {}) {
   const paths = quickstartOutputs(bundleInput, outDirInput);
   ensureDistinctOutputPaths(paths.outputs.map((output) => output.path));
-  await assertCanWriteQuickstartOutputs(paths.outputs, overwrite);
+  if (checkExisting) await assertCanWriteQuickstartOutputs(paths.outputs, overwrite);
 
   const vault = createVault({
     subjectId: String(getFlag(flags, ['subject', 'subject-id'], 'local-user')),
@@ -1133,6 +1149,39 @@ export async function quickstartCommand(flags, io) {
   return artifacts.verifyReport.ok === true ? 0 : 1;
 }
 
+function buildCrossModelProfileSummaries({ vault, passport, demoMemoryAddr, limit }) {
+  const profiles = [];
+  for (const profile of CROSS_MODEL_PROFILES) {
+    const pack = compileContextPack({
+      vault,
+      passport,
+      provider: profile.provider,
+      model: profile.model,
+      query: 'memory follows me across models',
+      purpose: `cross_model_demo:${profile.id}`,
+      memory_addresses: [demoMemoryAddr],
+      limit,
+    });
+    const contextPack = publicContextPackSummary(pack);
+    profiles.push({
+      profile: profile.id,
+      label: profile.label,
+      provider: profile.provider,
+      model: profile.model,
+      context_pack_ref: contextPack.context_pack_ref,
+      context_pack_id: contextPack.context_pack_id,
+      context_pack_digest: contextPack.context_pack_digest,
+      context_pack: contextPack,
+      receipt_count: contextPack.receipt_count,
+      memory_count: contextPack.memory_count,
+      provider_native_memory_canonical: false,
+      receipts: contextPack.receipts,
+      claim_boundaries: { ...CROSS_MODEL_CLAIM_BOUNDARIES },
+    });
+  }
+  return profiles;
+}
+
 export async function crossModelDemoCommand(flags, io) {
   const bundleFlag = getFlag(flags, ['bundle', 'file']);
   if (bundleFlag === true || bundleFlag === '') throw new Error('Missing required --bundle.');
@@ -1189,35 +1238,7 @@ export async function crossModelDemoCommand(flags, io) {
   const limit = integerFlag(flags, ['limit'], 'limit', 1);
   if (limit < 1) throw new Error('--limit must be at least 1.');
   const receiptCountBeforeProfiles = Array.isArray(vault.receipts) ? vault.receipts.length : 0;
-  const profiles = [];
-  for (const profile of CROSS_MODEL_PROFILES) {
-    const pack = compileContextPack({
-      vault,
-      passport,
-      provider: profile.provider,
-      model: profile.model,
-      query: 'memory follows me across models',
-      purpose: `cross_model_demo:${profile.id}`,
-      memory_addresses: [demoMemoryAddr],
-      limit,
-    });
-    const contextPack = publicContextPackSummary(pack);
-    profiles.push({
-      profile: profile.id,
-      label: profile.label,
-      provider: profile.provider,
-      model: profile.model,
-      context_pack_ref: contextPack.context_pack_ref,
-      context_pack_id: contextPack.context_pack_id,
-      context_pack_digest: contextPack.context_pack_digest,
-      context_pack: contextPack,
-      receipt_count: contextPack.receipt_count,
-      memory_count: contextPack.memory_count,
-      provider_native_memory_canonical: false,
-      receipts: contextPack.receipts,
-      claim_boundaries: { ...CROSS_MODEL_CLAIM_BOUNDARIES },
-    });
-  }
+  const profiles = buildCrossModelProfileSummaries({ vault, passport, demoMemoryAddr, limit });
 
   const bundle = await persistState(bundlePath, vault);
   const report = {
@@ -1327,20 +1348,14 @@ async function contextCommand(flags, io) {
 }
 
 
-async function searchCommand(flags, io) {
-  const bundlePath = resolve(String(getFlag(flags, ['bundle', 'file'], DEFAULT_BUNDLE)));
-  const query = String(requireFlag(flags, ['query', 'q'], 'query'));
-  const limit = integerFlag(flags, ['limit'], 'limit', 8);
-  if (limit < 0) throw new Error('--limit must be non-negative.');
-  const includeContent = getFlag(flags, ['include-content', 'includeContent']) === true || getFlag(flags, ['include-content', 'includeContent']) === 'true';
-  const { vault } = await loadState(bundlePath);
+function memorySearchReport({ bundlePath, vault, query, limit, includeContent = false, now = '2026-01-01T00:00:00.000Z' }) {
   const roots = vault.__computeRoots();
   const queryTokens = searchTokensFrom(query);
   const { candidates, byAddress } = searchCandidates(vault, queryTokens);
   const plan = createMemoryOptimizationPlan({
     candidates,
     prompt: query,
-    now: getFlag(flags, ['now'], '2026-01-01T00:00:00.000Z'),
+    now,
   });
   const planIndex = new Map(plan.items.map((item, index) => [item.address, index]));
   const selectedItems = plan.items
@@ -1381,7 +1396,7 @@ async function searchCommand(flags, io) {
       ...(includeContent ? { content: hit.content } : {}),
     };
   });
-  print({
+  return {
     ok: true,
     schema: 'enigma.memory_search.v1',
     bundle: bundlePath,
@@ -1395,18 +1410,33 @@ async function searchCommand(flags, io) {
     claim_boundary: includeContent
       ? 'Search ran against the selected local bundle and includes plaintext only because --include-content was explicit; this does not prove provider deletion, provider-native memory state, or model forgetting.'
       : 'Search ran against the selected local bundle and redacts plaintext by default; refs, scores, tags, roots, and receipt refs are not provider deletion proof or model forgetting proof.',
-  }, io);
-  return 0;
+  };
 }
 
-async function statusCommand(flags, io) {
+async function searchCommand(flags, io) {
   const bundlePath = resolve(String(getFlag(flags, ['bundle', 'file'], DEFAULT_BUNDLE)));
-  const { stored, vault, passport } = await loadState(bundlePath);
+  const query = String(requireFlag(flags, ['query', 'q'], 'query'));
+  const limit = integerFlag(flags, ['limit'], 'limit', 8);
+  if (limit < 0) throw new Error('--limit must be non-negative.');
+  const includeContent = getFlag(flags, ['include-content', 'includeContent']) === true || getFlag(flags, ['include-content', 'includeContent']) === 'true';
+  const { vault } = await loadState(bundlePath);
+  print(memorySearchReport({
+    bundlePath,
+    vault,
+    query,
+    limit,
+    includeContent,
+    now: getFlag(flags, ['now'], '2026-01-01T00:00:00.000Z'),
+  }), io);
+  return 0;
+}
+
+function passportStatusReport({ bundlePath, stored = {}, vault, passport }) {
   const roots = vault.__computeRoots();
   const activeCount = activeMemoryCount(vault);
   const tombstoneCount = vault.tombstones instanceof Map ? vault.tombstones.size : 0;
   const receiptCount = Array.isArray(vault.receipts) ? vault.receipts.length : 0;
-  print({
+  return {
     ok: true,
     schema: 'enigma.passport_status.v1',
     bundle: bundlePath,
@@ -1434,10 +1464,317 @@ async function statusCommand(flags, io) {
       `enigma connect <client> --bundle "${bundlePath}"`,
     ],
     claim_boundary: 'Status reports local bundle counters, owner display fields, connector readiness hints, and commitment roots only; it does not expose raw memory, certify compliance, prove provider deletion, or prove model forgetting.',
-  }, io);
+  };
+}
+
+async function statusCommand(flags, io) {
+  const bundlePath = resolve(String(getFlag(flags, ['bundle', 'file'], DEFAULT_BUNDLE)));
+  const { stored, vault, passport } = await loadState(bundlePath);
+  print(passportStatusReport({ bundlePath, stored, vault, passport }), io);
   return 0;
 }
 
+function testDrivePathDisplay(outDirInput, name) {
+  return isAbsolute(outDirInput) ? join(outDirInput, name) : quickstartPathDisplay(outDirInput, name);
+}
+
+function testDriveBundleDisplay(outDirInput) {
+  return testDrivePathDisplay(outDirInput, DEFAULT_TEST_DRIVE_BUNDLE_NAME);
+}
+
+function testDriveOutputs(outDirInput, bundleInput = testDriveBundleDisplay(outDirInput)) {
+  const quickstart = quickstartOutputs(bundleInput, outDirInput);
+  const contextPackDisplay = testDrivePathDisplay(outDirInput, QUICKSTART_ARTIFACT_NAMES.contextPack);
+  const exportDisplay = testDrivePathDisplay(outDirInput, QUICKSTART_ARTIFACT_NAMES.export);
+  const verifyReportDisplay = testDrivePathDisplay(outDirInput, QUICKSTART_ARTIFACT_NAMES.verifyReport);
+  const crossModelReportDisplay = testDrivePathDisplay(outDirInput, DEFAULT_TEST_DRIVE_CROSS_MODEL_REPORT_NAME);
+  const crossModelReportPath = resolve(quickstart.outDirPath, DEFAULT_TEST_DRIVE_CROSS_MODEL_REPORT_NAME);
+  const artifacts = [
+    { role: 'bundle', path: quickstart.bundlePath, display: bundleInput, schema: 'enigma.bundle.v1' },
+    { role: 'context_pack', path: quickstart.contextPackPath, display: contextPackDisplay, schema: 'enigma.context_pack.v1' },
+    { role: 'export', path: quickstart.exportPath, display: exportDisplay, schema: 'enigma.bundle.v1' },
+    { role: 'verify_report', path: quickstart.verifyReportPath, display: verifyReportDisplay, schema: 'enigma.verify_report.v1' },
+    { role: 'cross_model_report', path: crossModelReportPath, display: crossModelReportDisplay, schema: 'enigma.cross_model_demo.v1' },
+  ];
+  return {
+    ...quickstart,
+    contextPackDisplay,
+    exportDisplay,
+    verifyReportDisplay,
+    crossModelReportPath,
+    crossModelReportDisplay,
+    artifacts,
+    outputs: artifacts.map((artifact) => ({ path: artifact.path, display: artifact.display })),
+  };
+}
+
+function testDriveFileSummaries(artifacts, written) {
+  return artifacts.map((artifact) => ({
+    role: artifact.role,
+    path: artifact.display,
+    schema: artifact.schema,
+    written: Boolean(written),
+  }));
+}
+
+function firstActiveMemoryAddress(vault) {
+  if (!(vault.activeAddresses instanceof Set)) throw new Error('Test drive vault did not expose an active memory set.');
+  const first = vault.activeAddresses.values().next();
+  if (first.done) throw new Error('Test drive vault did not create a demo memory.');
+  return first.value;
+}
+
+function testDriveNextCommands(bundleDisplay, crossModelReportDisplay) {
+  const quotedBundle = commandPath(bundleDisplay);
+  const quotedReport = commandPath(crossModelReportDisplay);
+  return [
+    `enigma status --bundle ${quotedBundle}`,
+    `enigma search --bundle ${quotedBundle} --query "local proof bundle"`,
+    `enigma demo cross-model --bundle ${quotedBundle} --out ${quotedReport}`,
+    'node scripts/run-memory-benchmarks.mjs',
+  ];
+}
+
+function testDriveFlowCommands({ bundleDisplay, outDirInput, crossModelReportDisplay, overwrite }) {
+  const overwriteSuffix = overwrite ? ' --overwrite' : '';
+  const quotedBundle = commandPath(bundleDisplay);
+  const quotedOutDir = commandPath(outDirInput);
+  const quotedReport = commandPath(crossModelReportDisplay);
+  return [
+    `enigma quickstart --bundle ${quotedBundle} --out-dir ${quotedOutDir}${overwriteSuffix}`,
+    `enigma status --bundle ${quotedBundle}`,
+    `enigma search --bundle ${quotedBundle} --query "local proof bundle"`,
+    `enigma demo cross-model --bundle ${quotedBundle} --out ${quotedReport}`,
+  ];
+}
+
+function testDriveBenchmarkPointers() {
+  return [
+    {
+      command: 'node scripts/run-memory-benchmarks.mjs',
+      public_safe: true,
+      planned_only: true,
+      requires_repo_checkout: true,
+      external_provider_calls: false,
+      raw_memory_included: false,
+      claim_boundary: 'Runs deterministic local fixture operations only; it is not a provider comparison, hosted service proof, benchmark leadership claim, ROI claim, provider deletion proof, or model forgetting proof.',
+    },
+    {
+      command: 'node scripts/download-standard-benchmarks.mjs --dry-run',
+      public_safe: true,
+      planned_only: true,
+      requires_repo_checkout: true,
+      external_provider_calls: false,
+      raw_memory_included: false,
+      claim_boundary: 'Plans official dataset downloads without fetching by default; raw benchmark records are not included in the public plan.',
+    },
+    {
+      command: 'node scripts/run-standard-memory-benchmarks.mjs --locomo <path> --longmemeval <path>',
+      public_safe: true,
+      planned_only: true,
+      requires_repo_checkout: true,
+      external_provider_calls: false,
+      raw_memory_included: false,
+      claim_boundary: 'Runs local deterministic retrieval proxies against operator-supplied dataset files; it emits no provider API calls, competitor scores, benchmark leadership claim, or model-forgetting claim.',
+    },
+  ];
+}
+
+function testDriveClaimBoundaries() {
+  return {
+    local_only: true,
+    credentials_required: false,
+    external_provider_calls: false,
+    client_config_writes_performed: false,
+    plaintext_memory_echoed: false,
+    hosted_saas_live_claim: false,
+    provider_native_memory_canonical: false,
+    provider_deletion_proof: false,
+    model_forgetting_proof: false,
+    benchmark_leadership_claim: false,
+    compliance_certification: false,
+  };
+}
+
+function publicTestDriveStatusSummary(summary, bundleDisplay) {
+  return {
+    ...summary,
+    bundle: bundleDisplay,
+    connector_readiness: {
+      ...summary.connector_readiness,
+      bundle: bundleDisplay,
+    },
+    next_recommended_commands: [
+      `enigma remember --bundle ${commandPath(bundleDisplay)} --text-file <path>`,
+      `enigma search --bundle ${commandPath(bundleDisplay)} --query <text>`,
+      `enigma context --bundle ${commandPath(bundleDisplay)} --query <text>`,
+      `enigma verify --bundle ${commandPath(bundleDisplay)}`,
+      `enigma connect <client> --bundle ${commandPath(bundleDisplay)}`,
+    ],
+  };
+}
+
+function publicTestDriveSearchSummary(summary, bundleDisplay) {
+  return {
+    ...summary,
+    bundle: bundleDisplay,
+  };
+}
+
+function staticSetupSelection(requestedSelection) {
+  return {
+    ...requestedSelection,
+    fallback_used: false,
+    selected: requestedSelection.clients.map((clientId) => {
+      const profile = getClientProfile(clientId);
+      return publicSetupClientSelectionEntry({ client_id: clientId, display_name: profile.display_name }, requestedSelection.mode === 'default' ? 'default_setup_client' : 'explicit_client');
+    }),
+    skipped: [],
+    connectable_client_ids: null,
+  };
+}
+
+export async function testDriveCommand(flags, io) {
+  const outDirInput = pathFlag(flags, ['out-dir', 'outDir'], DEFAULT_TEST_DRIVE_DIR);
+  const bundleInput = pathFlag(flags, ['bundle', 'file'], testDriveBundleDisplay(outDirInput));
+  const overwrite = booleanFlag(flags, ['overwrite'], false);
+  const dryRun = booleanFlag(flags, ['dry-run', 'dryRun'], false);
+  const outputs = testDriveOutputs(outDirInput, bundleInput);
+  ensureDistinctOutputPaths(outputs.outputs.map((output) => output.path));
+  if (!dryRun) await assertCanWriteQuickstartOutputs(outputs.outputs, overwrite);
+
+  const artifacts = await buildQuickstartArtifacts(flags, {
+    bundleInput,
+    outDirInput,
+    overwrite,
+    write: false,
+    checkExisting: false,
+  });
+  const requestedSelection = setupClientIds(flags);
+  const selection = requestedSelection.auto
+    ? await setupAutoClientSelection(flags, artifacts, DEFAULT_SETUP_CLIENTS, 'auto')
+    : staticSetupSelection(requestedSelection);
+  const demoMemoryAddr = firstActiveMemoryAddress(artifacts.vault);
+  const crossModelLimit = integerFlag(flags, ['limit'], 'limit', 1);
+  if (crossModelLimit < 1) throw new Error('--limit must be at least 1.');
+  const receiptCountBeforeProfiles = Array.isArray(artifacts.vault.receipts) ? artifacts.vault.receipts.length : 0;
+  const profiles = buildCrossModelProfileSummaries({
+    vault: artifacts.vault,
+    passport: artifacts.passport,
+    demoMemoryAddr,
+    limit: crossModelLimit,
+  });
+  const finalExport = exportBundle({ vault: artifacts.vault, includePlaintext: false });
+  const finalBundle = finalExport.bundle ?? finalExport;
+  const finalVerifyReport = verifyBundle(finalBundle);
+  const crossModelReport = {
+    ok: true,
+    schema: 'enigma.cross_model_demo.v1',
+    command: 'enigma demo cross-model',
+    story: 'One local Enigma memory is packaged as public-safe context pack references and receipts for ChatGPT, Claude, Kimi, Cursor, and a local LLM. No provider is called.',
+    bundle_ref: bundleInput,
+    bundle_supplied: true,
+    bundle_created: true,
+    demo_only_vault: true,
+    memory_source: 'test_drive_demo',
+    demo_memory_addr: demoMemoryAddr,
+    profile_count: profiles.length,
+    profiles,
+    memory_count: activeMemoryCount(artifacts.vault),
+    receipt_count: Array.isArray(finalBundle.receipts) ? finalBundle.receipts.length : 0,
+    generated_receipt_count: (Array.isArray(finalBundle.receipts) ? finalBundle.receipts.length : 0) - receiptCountBeforeProfiles,
+    provider_credentials_required: false,
+    provider_native_memory_canonical: false,
+    out_written: !dryRun,
+    claim_boundaries: { ...CROSS_MODEL_CLAIM_BOUNDARIES },
+  };
+  const rawStatusSummary = passportStatusReport({
+    bundlePath: outputs.bundlePath,
+    vault: artifacts.vault,
+    passport: artifacts.passport,
+    stored: {
+      owner: {
+        subject_id: artifacts.vault.subject_id,
+        display_name: artifacts.vault.display_name,
+      },
+    },
+  });
+  const statusSummary = publicTestDriveStatusSummary(rawStatusSummary, bundleInput);
+  const rawSearchSummary = memorySearchReport({
+    bundlePath: outputs.bundlePath,
+    vault: artifacts.vault,
+    query: 'local proof bundle',
+    limit: 3,
+    includeContent: false,
+    now: getFlag(flags, ['now'], '2026-01-01T00:00:00.000Z'),
+  });
+  const searchSummary = publicTestDriveSearchSummary(rawSearchSummary, bundleInput);
+
+  if (!dryRun) {
+    await writeJson(outputs.bundlePath, finalBundle);
+    await writeJson(outputs.contextPackPath, publicContextPackSummary(artifacts.contextPack));
+    await writeJson(outputs.exportPath, finalBundle);
+    await writeJson(outputs.verifyReportPath, finalVerifyReport);
+    await writeJson(outputs.crossModelReportPath, crossModelReport);
+  }
+
+  const flowCommands = testDriveFlowCommands({
+    bundleDisplay: bundleInput,
+    outDirInput,
+    crossModelReportDisplay: outputs.crossModelReportDisplay,
+    overwrite,
+  });
+  const nextCommands = testDriveNextCommands(bundleInput, outputs.crossModelReportDisplay);
+  const files = testDriveFileSummaries(outputs.artifacts, !dryRun);
+  const packageJson = await readPackageJson();
+  const ok = finalVerifyReport.ok === true && crossModelReport.ok === true && statusSummary.ok === true && searchSummary.ok === true;
+  print({
+    ok,
+    schema: 'enigma.test_drive.v1',
+    command: 'enigma test-drive',
+    dry_run: dryRun,
+    out_dir: outDirInput,
+    bundle: bundleInput,
+    install_command: `npm install -g ${packageJson.name ?? 'enigma-memory'}`,
+    release_target: '0.1.12',
+    artifacts_written: !dryRun,
+    client_configs_written: false,
+    client_config_write_required: false,
+    memory_plaintext_echoed: false,
+    provider_credentials_required: false,
+    hosted_saas_live: false,
+    files,
+    files_written: dryRun ? [] : files.map((file) => file.path),
+    files_planned: files.map((file) => file.path),
+    commands_run: dryRun ? [] : flowCommands,
+    commands_planned: dryRun ? flowCommands : [],
+    next_commands: nextCommands,
+    benchmark_pointers: testDriveBenchmarkPointers(),
+    setup_summary: {
+      schema: 'enigma.setup.v1',
+      artifacts_written: !dryRun,
+      bundle: bundleInput,
+      context_pack: outputs.contextPackDisplay,
+      export: outputs.exportDisplay,
+      verify_report: outputs.verifyReportDisplay,
+      selected_clients: selection.clients,
+      client_selection: publicSetupClientSelection(selection),
+      client_configs_written: false,
+      provider_credentials_required: false,
+      memory_plaintext_echoed: false,
+      memory_count: Array.isArray(finalBundle.memory_objects) ? finalBundle.memory_objects.length : 0,
+      receipt_count: Array.isArray(finalBundle.receipts) ? finalBundle.receipts.length : 0,
+      context_item_count: Array.isArray(artifacts.contextPack.memories) ? artifacts.contextPack.memories.length : 0,
+      verify_ok: finalVerifyReport.ok === true,
+    },
+    status_summary: statusSummary,
+    search_summary: searchSummary,
+    cross_model_summary: crossModelReport,
+    claim_boundaries: testDriveClaimBoundaries(),
+  }, io);
+  return ok ? 0 : 1;
+}
+
 async function exportCommand(flags, io) {
   const bundlePath = resolve(String(getFlag(flags, ['bundle', 'file'], DEFAULT_BUNDLE)));
   const { vault } = await loadState(bundlePath);
@@ -1764,6 +2101,229 @@ function integerFlag(flags, names, label = names[0], fallback = undefined) {
   return number;
 }
 
+function flagValues(flags, names) {
+  const values = [];
+  for (const name of names) {
+    const value = getFlag(flags, [name]);
+    const entries = Array.isArray(value) ? value : [value];
+    for (const entry of entries) {
+      if (entry === undefined || entry === true || entry === '') continue;
+      for (const item of String(entry).split(',')) {
+        const trimmed = item.trim();
+        if (trimmed) values.push(trimmed);
+      }
+    }
+  }
+  return values;
+}
+
+function chainWriteOrPrint(flags, io, artifact, summary) {
+  if (flags.has('out')) {
+    const outPath = resolve(String(requireFlag(flags, ['out'])));
+    return writeJson(outPath, artifact).then(() => {
+      print({
+        ok: true,
+        path: publicPathDisplay(String(requireFlag(flags, ['out'])), 'proof-network-artifact'),
+        transaction_submitted: false,
+        raw_memory_on_chain: false,
+        ...summary,
+      }, io);
+      return 0;
+    });
+  }
+  print(artifact, io);
+  return 0;
+}
+
+async function sha256PublicFile(path) {
+  const bytes = await readFile(path);
+  try {
+    assertNoPrivateProofPayload(JSON.parse(bytes.toString('utf8')));
+  } catch (error) {
+    if (error instanceof SyntaxError) return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+    throw new Error('Report file contains private proof payload markers.');
+  }
+  return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+
+function scoreFlags(flags) {
+  const scores = {};
+  for (const value of flagValues(flags, ['score', 'scores', 'metric', 'metrics'])) {
+    const eq = value.indexOf('=');
+    if (eq <= 0) throw new Error('--score values must use name=value.');
+    const key = value.slice(0, eq).trim();
+    const raw = value.slice(eq + 1).trim();
+    if (!key || !raw) throw new Error('--score values must use name=value.');
+    const numeric = Number(raw);
+    scores[key] = Number.isFinite(numeric) && raw !== '' ? numeric : raw;
+  }
+  return scores;
+}
+
+
+function assertChainArtifact(validate, artifact) {
+  const result = chainValidationResult(validate, artifact);
+  if (!result.ok) throw new Error(result.errors?.join('; ') || 'Invalid proof-network artifact.');
+  return artifact;
+}
+function chainValidationResult(validate, artifact) {
+  assertNoPrivateProofPayload(artifact);
+  const result = validate(artifact);
+  if (result === false) return { ok: false };
+  if (result && typeof result === 'object') return { ok: result.ok !== false, ...result };
+  return { ok: true };
+}
+
+function chainArtifactValidator(artifact) {
+  const schema = String(artifact?.schema ?? artifact?.type ?? artifact?.artifact_type ?? '');
+  if (schema === 'enigma.proof_network.anchor_batch.v1') return [schema, validateProofNetworkAnchorBatch];
+  if (schema === 'enigma.proof_network.capability_grant.v1') return [schema, validateCapabilityGrant];
+  if (schema === 'enigma.proof_network.capability_revocation.v1') return [schema, validateCapabilityRevocation];
+  if (schema === 'enigma.proof_network.benchmark_attestation.v1') return [schema, validateBenchmarkAttestation];
+  if (schema === 'enigma.proof_network.packet.v1') return [schema, validateProofNetworkPacket];
+  throw new Error(`Unsupported proof-network artifact schema: ${schema || 'missing'}.`);
+}
+
+export async function chainAnchorCommand(flags, io) {
+  const roots = flagValues(flags, ['root', 'roots', 'memory-root', 'memoryRoot', 'receipt-root', 'receiptRoot', 'context-root', 'contextRoot', 'memory-commitment-root', 'memoryCommitmentRoot']);
+  if (roots.length === 0) throw new Error('Missing required --root.');
+  const refs = flagValues(flags, ['ref', 'refs', 'public-ref', 'publicRef']);
+  const publicChainRef = getFlag(flags, ['public-chain-ref', 'publicChainRef', 'chain-ref', 'chainRef'], 'solana:local-plan');
+  const batch = createProofNetworkAnchorBatch({
+    roots,
+    root_count: roots.length,
+    commitment_count: roots.length,
+    refs,
+    public_chain_ref: publicChainRef,
+    authority_ref: getFlag(flags, ['authority', 'authority-ref', 'authorityRef']),
+    batch_ref: getFlag(flags, ['batch-ref', 'batchRef']),
+    created_at: getFlag(flags, ['created-at', 'createdAt']),
+    transaction_submitted: false,
+    raw_memory_on_chain: false,
+  });
+  assertChainArtifact(validateProofNetworkAnchorBatch, batch);
+  return chainWriteOrPrint(flags, io, batch, {
+    artifact_type: batch.schema,
+    anchor_batch_id: batch.anchor_batch_id,
+    anchor_batch_hash: batch.anchor_batch_hash ?? proofNetworkSha256Json(batch),
+  });
+}
+
+export async function chainGrantCommand(flags, io) {
+  const resourceRefs = flagValues(flags, ['resource-root', 'resource-roots', 'resourceRoot', 'resourceRoots', 'resource-ref', 'resource-refs', 'resourceRef', 'resourceRefs', 'ref', 'refs']);
+  const capability = requireFlag(flags, ['capability', 'capability-id', 'capabilityId'], 'capability');
+  const scope = requireFlag(flags, ['scope', 'scope-ref', 'scopeRef', 'capability-scope', 'capabilityScope'], 'scope');
+  const policyHash = getFlag(flags, ['policy-hash', 'policyHash'], proofNetworkSha256Json({ capability, scope, resource_refs: resourceRefs }));
+  const grant = createCapabilityGrant({
+    issuer_ref: getFlag(flags, ['issuer', 'issuer-ref', 'issuerRef'], 'issuer:local-cli'),
+    subject_ref: requireFlag(flags, ['subject', 'subject-ref', 'subjectRef'], 'subject'),
+    capability,
+    scope,
+    scopes: scope,
+    capability_scope: scope,
+    resource_roots: resourceRefs.length ? resourceRefs : [policyHash],
+    policy_hash: policyHash,
+    expires_at: requireFlag(flags, ['expires-at', 'expiresAt'], 'expires-at'),
+    grant_ref: getFlag(flags, ['grant-ref', 'grantRef']),
+    issued_at: getFlag(flags, ['issued-at', 'issuedAt', 'created-at', 'createdAt']),
+    transaction_submitted: false,
+    raw_memory_on_chain: false,
+  });
+  assertChainArtifact(validateCapabilityGrant, grant);
+  return chainWriteOrPrint(flags, io, grant, {
+    artifact_type: grant.schema,
+    capability_grant_id: grant.capability_grant_id,
+    capability_grant_hash: grant.capability_grant_hash ?? proofNetworkSha256Json(grant),
+  });
+}
+
+export async function chainRevokeCommand(flags, io) {
+  const grantValue = getFlag(flags, ['grant']);
+  let grantHash = getFlag(flags, ['grant-hash', 'grantHash']);
+  let grantId = getFlag(flags, ['grant-id', 'grantId']);
+  if (grantValue !== undefined && grantValue !== true && grantValue !== '') {
+    const grantString = String(grantValue);
+    if (grantString.startsWith('sha256:')) {
+      grantHash = grantHash ?? grantString;
+    } else {
+      const grantArtifact = await readJson(resolve(grantString));
+      const grantValidation = validateCapabilityGrant(grantArtifact);
+      if (!grantValidation.ok) throw new Error(`Grant artifact is invalid: ${grantValidation.errors.join('; ')}`);
+      grantHash = grantHash ?? grantArtifact.capability_grant_hash;
+      grantId = grantId ?? grantArtifact.capability_grant_id;
+    }
+  }
+  const nullifierValue = getFlag(flags, ['nullifier-root', 'nullifierRoot', 'nullifier-ref', 'nullifierRef', 'nullifier']);
+  const revocation = createCapabilityRevocation({
+    grant_id: grantId,
+    grant_hash: grantHash ?? requireFlag(flags, ['grant-hash', 'grantHash'], 'grant-hash'),
+    reason_ref: requireFlag(flags, ['reason', 'revocation-reason', 'revocationReason'], 'reason'),
+    revocation_reason: getFlag(flags, ['reason', 'revocation-reason', 'revocationReason']),
+    revocation_ref: getFlag(flags, ['revocation-ref', 'revocationRef']),
+    nullifier_root: nullifierValue && String(nullifierValue).startsWith('sha256:') ? nullifierValue : undefined,
+    nullifier_ref: nullifierValue && !String(nullifierValue).startsWith('sha256:') ? nullifierValue : undefined,
+    revoked_at: getFlag(flags, ['revoked-at', 'revokedAt']),
+    transaction_submitted: false,
+    raw_memory_on_chain: false,
+  });
+  assertChainArtifact(validateCapabilityRevocation, revocation);
+  return chainWriteOrPrint(flags, io, revocation, {
+    artifact_type: revocation.schema,
+    capability_revocation_id: revocation.capability_revocation_id,
+    capability_revocation_hash: revocation.capability_revocation_hash ?? proofNetworkSha256Json(revocation),
+  });
+}
+
+export async function chainAttestCommand(flags, io) {
+  const reportHash = getFlag(flags, ['report-hash', 'reportHash']);
+  const reportFile = getFlag(flags, ['report-file', 'reportFile']);
+  const resolvedReportHash = reportHash || (reportFile ? await sha256PublicFile(resolve(String(reportFile))) : undefined);
+  if (!resolvedReportHash) throw new Error('Missing required --report-hash or --report-file.');
+  const scores = scoreFlags(flags);
+  const metricsHash = getFlag(flags, ['metrics-hash', 'metricsHash'], proofNetworkSha256Json({ scores }));
+  const attestation = createBenchmarkAttestation({
+    report_hash: resolvedReportHash,
+    report_file_hash: resolvedReportHash,
+    dataset_ref: requireFlag(flags, ['dataset-ref', 'datasetRef', 'dataset-manifest', 'datasetManifest'], 'dataset-ref'),
+    runner_ref: requireFlag(flags, ['runner-ref', 'runnerRef'], 'runner-ref'),
+    package_ref: requireFlag(flags, ['package-ref', 'packageRef'], 'package-ref'),
+    metrics: scores,
+    metrics_hash: metricsHash,
+    attestation_ref: getFlag(flags, ['attestation-ref', 'attestationRef']),
+    created_at: getFlag(flags, ['created-at', 'createdAt']),
+    transaction_submitted: false,
+    raw_memory_on_chain: false,
+  });
+  assertChainArtifact(validateBenchmarkAttestation, attestation);
+  return chainWriteOrPrint(flags, io, attestation, {
+    artifact_type: attestation.schema,
+    benchmark_attestation_id: attestation.benchmark_attestation_id,
+    benchmark_attestation_hash: attestation.benchmark_attestation_hash ?? proofNetworkSha256Json(attestation),
+  });
+}
+
+export async function chainVerifyCommand(flags, io, positionalFile = undefined) {
+  const inPath = resolve(String(requireFileArg(flags, ['file', 'in'], positionalFile, 'file')));
+  const artifact = await readJson(inPath);
+  const [schema, validate] = chainArtifactValidator(artifact);
+  let result;
+  try {
+    result = chainValidationResult(validate, artifact);
+  } catch (error) {
+    result = { ok: false, error: { code: 'PROOF_NETWORK_INVALID', message: error.message } };
+  }
+  print({
+    ok: result.ok === true,
+    artifact_type: schema,
+    artifact_hash: proofNetworkSha256Json(artifact),
+    transaction_submitted: false,
+    raw_memory_on_chain: false,
+    validation: result,
+  }, io);
+  return result.ok === true ? 0 : 1;
+}
+
+
 export async function meterEventCommand(flags, io) {
   const event = createUsageEvent({
     tenant_id: requireFlag(flags, ['tenant', 'tenant-id', 'tenantId'], 'tenant'),
@@ -1945,6 +2505,7 @@ function usage() {
       'init',
       'setup',
       'quickstart',
+      'test-drive',
       'demo cross-model',
       'doctor',
       'install',
@@ -1981,6 +2542,11 @@ function usage() {
       'settlement receipt',
       'settlement verify',
       'settlement batch',
+      'chain anchor',
+      'chain grant',
+      'chain revoke',
+      'chain attest',
+      'chain verify',
     ],
     connector_options: {
       '--bundle <path>': 'Absolute local Enigma vault bundle path rendered as ENIGMA_BUNDLE.',
@@ -2024,6 +2590,13 @@ function usage() {
       '--memory-text <text>': 'Inline demo memory text for non-private demos only.',
       '--overwrite': 'Replace existing quickstart output files.',
     },
+    test_drive_options: {
+      '--out-dir <path>': `Isolated demo directory. Defaults to ${DEFAULT_TEST_DRIVE_DIR}.`,
+      '--bundle <path>': `Bundle JSON to create. Defaults to ${DEFAULT_TEST_DRIVE_DIR}/${DEFAULT_TEST_DRIVE_BUNDLE_NAME}.`,
+      '--client <id|auto>': 'Client setup planning passthrough. No client config files are written by test-drive.',
+      '--overwrite': 'Replace existing test-drive artifact files.',
+      '--dry-run': 'Plan the local test drive without writing artifacts.',
+    },
     cross_model_demo_options: {
       '--bundle <path>': `Reuse a local Enigma bundle. If omitted, ${DEFAULT_CROSS_MODEL_DEMO_BUNDLE} is recreated as a demo-only local vault.`,
       '--memory-file <path>': 'Seed the demo from a local file without echoing plaintext. Alias: --text-file.',
@@ -2069,6 +2642,14 @@ function usage() {
       batch: 'enigma settlement batch --receipts <receipts.json> --batch-ref <ref> [--asset <asset>] [--out <file>]',
       boundary: 'Settlement artifacts contain commitment roots, capacity profiles, hashes, refs, prices, and claim boundaries only; no raw memory, prompts, provider responses, credentials, token ROI/profit, decentralization, or provider-invoice savings claim.',
     },
+    chain: {
+      anchor: 'enigma chain anchor --root <sha256:...> [--root <sha256:...>] [--ref <public-ref>] [--authority <public-authority-ref>] [--batch-ref <ref>] [--out <file>]',
+      grant: 'enigma chain grant --subject <public-subject-ref> --capability <capability-id> --scope <scope-id> [--resource-ref <sha256:...>] [--policy-hash <sha256:...>] --expires-at <iso> [--grant-ref <public-ref>] [--out <file>]',
+      revoke: 'enigma chain revoke --grant-hash <sha256:...> --reason <public-reason-code> [--revocation-ref <public-ref>] [--out <file>]',
+      attest: 'enigma chain attest (--report-hash <sha256:...> | --report-file <report.json>) --dataset-ref <sha256:...> --runner-ref <public-runner-ref> --package-ref <public-package-ref> [--score name=value] [--out <file>]',
+      verify: 'enigma chain verify --file <proof-artifact.json>',
+      boundary: 'Proof Network chain commands are local planning commands only. They write public-safe hashes, roots, refs, counts, signatures, and booleans; they do not submit Solana transactions or put raw memory on chain.',
+    },
     relay_gateway_options: {
       '--host <host>': 'Bind host. Defaults to 127.0.0.1.',
       '--port <port>': `Bind port. Defaults to ${DEFAULT_RELAY_PORT} for relay and ${DEFAULT_GATEWAY_PORT} for gateway.`,
@@ -2095,10 +2676,10 @@ export async function main(argv = process.argv.slice(2), io = { stdout: process.
     print(usage(), io);
     return 0;
   }
-  const twoPartCommands = ['boundary', 'mcp', 'mesh', 'enterprise', 'capsule', 'relay', 'gateway', 'connect', 'disconnect', 'import', 'native-host', 'meter', 'settlement', 'demo', 'passport'];
+  const twoPartCommands = ['boundary', 'mcp', 'mesh', 'enterprise', 'capsule', 'relay', 'gateway', 'connect', 'disconnect', 'import', 'native-host', 'meter', 'settlement', 'chain', 'demo', 'passport'];
   const flags = parseArgs(twoPartCommands.includes(command) ? argv.slice(2) : argv.slice(1));
   const positionalFile = optionalPositional(argv[2]);
-  if ((flags.has('help') || argv.includes('-h')) && (command === 'setup' || command === 'search' || command === 'status' || (command === 'passport' && subcommand === 'status') || ((command === 'relay' || command === 'gateway') && (subcommand === 'serve' || subcommand === 'demo')) || (command === 'native-host' && (subcommand === 'manifest' || subcommand === 'install-plan')) || (command === 'demo' && subcommand === 'cross-model'))) {
+  if ((command === 'chain' && (!subcommand || subcommand === '--help' || subcommand === '-h' || flags.has('help'))) || ((flags.has('help') || argv.includes('-h')) && (command === 'setup' || command === 'test-drive' || command === 'search' || command === 'status' || (command === 'passport' && subcommand === 'status') || ((command === 'relay' || command === 'gateway') && (subcommand === 'serve' || subcommand === 'demo')) || (command === 'native-host' && (subcommand === 'manifest' || subcommand === 'install-plan')) || (command === 'demo' && subcommand === 'cross-model')))) {
     print(usage(), io);
     return 0;
   }
@@ -2106,6 +2687,7 @@ export async function main(argv = process.argv.slice(2), io = { stdout: process.
     if (command === 'init') return await initCommand(flags, io);
     if (command === 'setup') return await setupCommand(flags, io);
     if (command === 'quickstart') return await quickstartCommand(flags, io);
+    if (command === 'test-drive') return await testDriveCommand(flags, io);
     if (command === 'demo' && subcommand === 'cross-model') return await crossModelDemoCommand(flags, io);
     if (command === 'doctor') return await doctorCommand(flags, io);
     if (command === 'install') return await installCommand(flags, io);
@@ -2139,6 +2721,11 @@ export async function main(argv = process.argv.slice(2), io = { stdout: process.
     if (command === 'settlement' && subcommand === 'receipt') return await settlementReceiptCommand(flags, io);
     if (command === 'settlement' && subcommand === 'verify') return await settlementVerifyCommand(flags, io);
     if (command === 'settlement' && subcommand === 'batch') return await settlementBatchCommand(flags, io, positionalFile);
+    if (command === 'chain' && subcommand === 'anchor') return await chainAnchorCommand(flags, io);
+    if (command === 'chain' && subcommand === 'grant') return await chainGrantCommand(flags, io);
+    if (command === 'chain' && subcommand === 'revoke') return await chainRevokeCommand(flags, io);
+    if (command === 'chain' && subcommand === 'attest') return await chainAttestCommand(flags, io);
+    if (command === 'chain' && subcommand === 'verify') return await chainVerifyCommand(flags, io, positionalFile);
     if (command === 'native-host' && subcommand === 'install-plan') return await nativeHostInstallPlanCommand(flags, io);
     if (command === 'mesh' && subcommand === 'demo') return await meshDemoCommand(flags, io);
     if (command === 'enterprise' && subcommand === 'demo') return await enterpriseDemoCommand(flags, io);