enigma-memory 0.1.11 → 0.1.13

package/README.md

@@ -31,6 +31,14 @@ enigma setup --connect-installed --overwrite
 
 `--connect-installed` is the explicit client-config write path. It skips missing client configs instead of creating every default client config.
 
+## Enigma Proof Network
+
+Enigma Proof Network is the public proof layer for AI memory: local tools can package privacy-preserving roots, refs, counts, signatures, scoped capability grants, revocations, and benchmark attestations without exposing raw memory, prompts, transcripts, completions, embeddings, tenant names, private keys, provider responses, or provider credentials.
+
+The `enigma chain anchor|grant|revoke|attest|verify` commands are local planning and verification commands. They emit public-safe JSON with `transaction_submitted:false` and `raw_memory_on_chain:false`; they do not submit Solana transactions, deploy hosted SaaS, create accounts, or call external providers.
+
+Start with the category narrative in [`docs/market-category-narrative.md`](docs/market-category-narrative.md), then read the technical overview in [`docs/proof-network.md`](docs/proof-network.md), use its [Solana role](docs/proof-network.md#solana-role) section for the Solana-ready anchoring boundary, and read [`docs/proof-network-faq.md`](docs/proof-network-faq.md) for claim boundaries.
+
 ## Install once, use everywhere
 
 Prerequisites:

package/apps/cli/bin/enigma.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 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 { constants as fsConstants, realpathSync } from 'node:fs';
+import { access, mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
 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';
@@ -30,6 +30,19 @@ 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';
@@ -561,6 +574,86 @@ function minimumNodeMajor(range) {
   return match ? Number(match[1]) : 0;
 }
 
+function npmUserAgentCheck(userAgent = process.env.npm_config_user_agent) {
+  const raw = typeof userAgent === 'string' ? userAgent.trim() : '';
+  const npmToken = raw.split(/\s+/).find((token) => token.startsWith('npm/'));
+  const version = npmToken ? npmToken.slice(4) : null;
+  return {
+    ok: true,
+    detected: version !== null,
+    name: version === null ? null : 'npm',
+    version,
+    source: version === null ? null : 'npm_config_user_agent',
+  };
+}
+
+async function statIfExists(path) {
+  try {
+    return await stat(path);
+  } catch (error) {
+    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') return null;
+    throw error;
+  }
+}
+
+async function nearestExistingAncestor(path) {
+  let current = resolve(path);
+  for (;;) {
+    const stats = await statIfExists(current);
+    if (stats !== null) return { path: current, stats };
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function publicParentDisplay(path, label) {
+  const value = String(path);
+  if (/^<[^>]+>$/.test(value)) return `<${label}>`;
+  const parent = dirname(value);
+  return parent === '' ? '.' : publicPathDisplay(parent, label);
+}
+
+async function writableVaultPathCheck(bundleInput, displayInput = bundleInput) {
+  const bundlePath = resolve(String(bundleInput));
+  const parentPath = dirname(bundlePath);
+  const targetStats = await statIfExists(bundlePath);
+  const nearest = await nearestExistingAncestor(parentPath);
+  let ok = false;
+  let reason = null;
+  let parentExists = false;
+  let nearestExistingParent = null;
+  if (targetStats?.isDirectory()) {
+    reason = 'target_is_directory';
+  } else if (nearest === null) {
+    reason = 'no_existing_parent';
+  } else if (!nearest.stats.isDirectory()) {
+    reason = 'nearest_parent_not_directory';
+    nearestExistingParent = '<existing-parent-path>';
+  } else {
+    parentExists = nearest.path === parentPath;
+    nearestExistingParent = parentExists ? publicParentDisplay(displayInput, 'bundle-dir') : '<existing-parent-dir>';
+    try {
+      await access(nearest.path, fsConstants.W_OK);
+      ok = true;
+    } catch {
+      reason = 'parent_not_writable';
+    }
+  }
+  return {
+    ok,
+    path: publicPathDisplay(displayInput, 'bundle-path'),
+    parent: publicParentDisplay(displayInput, 'bundle-dir'),
+    parent_exists: parentExists,
+    nearest_existing_parent: nearestExistingParent,
+    target_exists: targetStats !== null,
+    target_is_directory: targetStats?.isDirectory() === true,
+    writable: ok,
+    reason,
+    hint: ok ? null : 'Choose a writable --bundle path or create a writable parent directory.',
+  };
+}
+
 async function schemaFiles() {
   return (await readdir(SPECS_URL)).filter((name) => name.endsWith('.schema.json')).sort();
 }
@@ -895,10 +988,19 @@ function setupNextCommands(bundleInput, exportDisplay, clients, writeConnectors)
     `enigma context --bundle ${commandPath(bundleInput)} --query "project context"`,
     `enigma verify --export ${commandPath(exportDisplay)}`,
   ];
-  if (!writeConnectors) commands.push(`enigma connect ${primaryClient} --bundle ${commandPath(bundleInput)}`);
+  if (!writeConnectors) commands.push(`enigma connect ${primaryClient} --bundle ${commandPath(bundleInput)} --dry-run`);
   return commands;
 }
 
+function doctorNextCommands(bundleDisplay, client) {
+  const clientId = client ?? DEFAULT_SETUP_CLIENTS[0];
+  return [
+    `enigma setup --bundle ${commandPath(bundleDisplay)}`,
+    `enigma doctor --bundle ${commandPath(bundleDisplay)} --client ${clientId}`,
+    `enigma connect ${clientId} --bundle ${commandPath(bundleDisplay)}`,
+  ];
+}
+
 async function setupDoctorChecks(flags, artifacts, clients, displays) {
   const packageJson = await readPackageJson();
   const requiredNodeMajor = minimumNodeMajor(packageJson.engines?.node);
@@ -925,12 +1027,15 @@ async function setupDoctorChecks(flags, artifacts, clients, displays) {
     const doctor = await doctorConnectors({ ...connectorBaseOptions, clientId: client });
     connectorClients.push(...doctor.clients);
   }
+  const vaultPath = await writableVaultPathCheck(artifacts.bundlePath, displays.bundle);
   const checks = {
     node: {
       ok: requiredNodeMajor === 0 || currentNodeMajor >= requiredNodeMajor,
       current: process.versions.node,
       required: packageJson.engines?.node ?? null,
     },
+    npm: npmUserAgentCheck(),
+    vault_path: vaultPath,
     package_bins: {
       ok: binEntries.every((entry) => entry.declared && entry.exists),
       required: REQUIRED_PACKAGE_BINS,
@@ -1518,7 +1623,7 @@ function testDriveNextCommands(bundleDisplay, crossModelReportDisplay) {
     `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',
+    'enigma setup --overwrite',
   ];
 }
 
@@ -1723,7 +1828,7 @@ export async function testDriveCommand(flags, io) {
     out_dir: outDirInput,
     bundle: bundleInput,
     install_command: `npm install -g ${packageJson.name ?? 'enigma-memory'}`,
-    release_target: '0.1.11',
+    release_target: '0.1.13',
     artifacts_written: !dryRun,
     client_configs_written: false,
     client_config_write_required: false,
@@ -1829,10 +1934,11 @@ export async function doctorCommand(flags, io) {
     };
   }));
   const schemas = await schemaFiles();
+  const bundleInput = pathFlag(flags, ['bundle', 'file'], DEFAULT_BUNDLE);
   const selectedClient = getFlag(flags, ['client']);
   const doctorOptions = selectedClient && selectedClient !== true
-    ? { ...connectorOptions(flags), clientId: String(selectedClient) }
-    : { ...connectorOptions(flags), clientId: undefined };
+    ? { ...connectorOptions(flags), clientId: String(selectedClient), redactPaths: true }
+    : { ...connectorOptions(flags), clientId: undefined, redactPaths: true };
   const connectorDoctor = await doctorConnectors(doctorOptions);
   const profile = getClientProfile(String(selectedClient && selectedClient !== true ? selectedClient : 'generic-mcp'), connectorOptions(flags));
   const checks = {
@@ -1841,6 +1947,7 @@ export async function doctorCommand(flags, io) {
       current: process.versions.node,
       required: packageJson.engines?.node ?? null,
     },
+    npm: npmUserAgentCheck(),
     package_bins: {
       ok: binEntries.every((entry) => entry.declared && entry.exists),
       required: REQUIRED_PACKAGE_BINS,
@@ -1851,8 +1958,9 @@ export async function doctorCommand(flags, io) {
     bundle_default_path: {
       ok: DEFAULT_BUNDLE === '.enigma/bundle.json',
       path: DEFAULT_BUNDLE,
-      resolved: resolve(String(getFlag(flags, ['bundle', 'file'], DEFAULT_BUNDLE))),
+      resolved: publicPathDisplay(resolve(bundleInput), 'bundle-path'),
     },
+    vault_path: await writableVaultPathCheck(resolve(bundleInput), publicPathDisplay(bundleInput, 'bundle-path')),
     schemas: {
       ok: schemas.length > 0,
       count: schemas.length,
@@ -1870,11 +1978,14 @@ export async function doctorCommand(flags, io) {
     ok,
     node: checks.node,
     package_bins: checks.package_bins,
+    npm: checks.npm,
+    vault_path: checks.vault_path,
     bundle_default_path: checks.bundle_default_path,
     schema_count: checks.schemas.count,
     schemas: checks.schemas,
     mcp_command_name: checks.mcp_command_name.command,
     connectors: checks.connectors,
+    next_commands: doctorNextCommands(checks.vault_path.path, String(selectedClient && selectedClient !== true ? selectedClient : 'generic-mcp')),
     checks,
   }, io);
   return ok ? 0 : 1;
@@ -2088,6 +2199,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'),
@@ -2306,6 +2640,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.',
@@ -2401,6 +2740,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.`,
@@ -2427,10 +2774,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 === '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'))) {
+  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;
   }
@@ -2472,6 +2819,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);

package/deploy/SIMULATION.md

@@ -0,0 +1,152 @@
+# Enigma Memory — Local Production Simulation
+
+**CLAIM BOUNDARY:** This is a `local-simulation` environment. It uses
+self-signed TLS, bind-mounted file "secrets", a mocked KMS, and a mocked SIEM.
+It is **not** a production deployment and must not be used as go-live evidence.
+
+## Public-looking domain (local testing only)
+
+The simulation is configured to answer on `sim.enigmamemory.com` so that the
+hosted-backend live validator accepts the non-localhost HTTPS probe URLs. For
+real go-live evidence the operator must point the chosen public domain at the
+deployment's public IP address; the local simulation uses a hosts-file or local
+DNS trick instead.
+
+On the host running Docker, map the domain to the loopback interface:
+
+```text
+127.0.0.1 sim.enigmamemory.com relay.sim.enigmamemory.com gateway.sim.enigmamemory.com
+```
+
+On Linux/macOS add that line to `/etc/hosts`; on Windows add it to
+`C:\Windows\System32\drivers\etc\hosts`. Then the following commands work from
+the host:
+
+```bash
+curl -k https://sim.enigmamemory.com:8443/readyz
+curl -k https://sim.enigmamemory.com:9443/readyz
+```
+
+The tls-proxy service also declares `extra_hosts` entries for the same domain
+names so that containers can resolve them locally when needed.
+
+## Quick start
+
+1. Generate secrets and a self-signed TLS certificate:
+
+   ```bash
+   node scripts/simulate-production-env.mjs
+   ```
+
+   Files are written to `deploy/secrets-simulation/` (gitignored).
+
+2. Start the simulation:
+
+   ```bash
+   docker compose -f deploy/docker-compose.local-production-simulation.yml up --build -d
+   ```
+
+3. Wait for the backend to become ready:
+
+   ```bash
+   node scripts/wait-for-backend-ready.mjs
+   ```
+
+4. Inspect readiness over HTTPS:
+
+   ```bash
+   curl -k https://localhost:8443/readyz
+   curl -k https://localhost:9443/readyz
+   curl -k https://sim.enigmamemory.com:8443/readyz
+   curl -k https://sim.enigmamemory.com:9443/readyz
+   ```
+
+## Stop
+
+```bash
+docker compose -f deploy/docker-compose.local-production-simulation.yml down
+```
+
+To also remove the Postgres volume and mock event data:
+
+```bash
+docker compose -f deploy/docker-compose.local-production-simulation.yml down -v
+```
+
+## Ports and routes
+
+| Service | Public port | Internal port | Health route | Notes |
+|--------|-------------|---------------|--------------|-------|
+| relay  | `8443` (HTTPS, loopback) | `8787` | `/readyz`, `/livez` | TLS terminated by `tls-proxy`; also answers on `sim.enigmamemory.com` and `relay.sim.enigmamemory.com` |
+| gateway | `9443` (HTTPS, loopback) | `8797` | `/readyz`, `/livez` | TLS terminated by `tls-proxy`; also answers on `sim.enigmamemory.com` and `gateway.sim.enigmamemory.com` |
+| postgres | not exposed | `5432` | — | Used as the simulated durable store |
+| kms-mock | not exposed | `3000` | `/healthz` | Serves a generated Ed25519 key ref |
+| siem-mock | not exposed | `3000` | `/healthz` | Accepts `POST /events`, writes minimized metadata to `/data/siem-events.jsonl` |
+
+## Verify secret files
+
+```bash
+node scripts/simulate-production-env.mjs --check
+```
+
+This reports whether all required files in `deploy/secrets-simulation/` exist
+and are non-empty.
+
+## Simulation-only behavior
+
+- `ENIGMA_OPERATOR_ACCEPTANCE_DECISION` is set to `go` so the readiness
+  endpoints can turn green locally. This is **not** real operator acceptance.
+- `ENIGMA_DISABLE_LOCAL_DEMO_FALLBACK` is `true`, but the "external" storage,
+  KMS, and SIEM are local mocks.
+- The TLS certificate is self-signed; curl requires `-k`/`--insecure`.
+- The certificate SAN list includes `localhost`, `127.0.0.1`,
+  `sim.enigmamemory.com`, `relay.sim.enigmamemory.com`,
+  `gateway.sim.enigmamemory.com`, and `*.sim.enigmamemory.com`.
+
+## Collect hosted backend live evidence
+
+The simulation can be probed as if it were a public hosted deployment by
+using the public-looking domain `sim.enigmamemory.com`. Because the domain
+has no real DNS record, the collector resolves it to `127.0.0.1` locally and
+accepts the self-signed certificate.
+
+1. Build a simulation operator acceptance packet:
+
+   ```bash
+   node scripts/build-operator-acceptance-packet.mjs \
+     --complete-fixture --decision go --packet-id sim-operator-acceptance \
+     --tenant enigma-sim --deployment-mode hosted --environment local-simulation \
+     --target-regions local --requested-go-live-date 2026-06-25 \
+     --evidence-repository https://github.com/enigma-memory/evidence/sim \
+     --packet-owner "Simulation Owner" \
+     --last-updated 2026-06-25T00:00:00.000Z \
+     --owners-json .enigma/sim-owner-overrides.json \
+     --evidence-refs .enigma/sim-evidence-overrides.json \
+     --out .enigma/sim-operator-acceptance.json --validate
+   ```
+
+2. Collect and validate live evidence:
+
+   ```bash
+   node .enigma/collect-sim-evidence.mjs \
+     --relay-url https://sim.enigmamemory.com:8443 \
+     --gateway-url https://sim.enigmamemory.com:9443 \
+     --refs-json .enigma/sim-hosted-refs.json \
+     --domain sim.enigmamemory.com --environment-id local-simulation \
+     --cloud-provider local --region local --owner enigma-sim \
+     --operator-decision go \
+     --operator-packet-ref .enigma/sim-operator-acceptance.json \
+     --operator-approved-at <iso8601> --operator-approved-by enigma-sim \
+     --out .enigma/hosted-backend-live-collection.json \
+     --evidence-out .enigma/hosted-backend-live-simulated.json
+
+   node scripts/validate-hosted-backend-live.mjs \
+     --evidence .enigma/hosted-backend-live-simulated.json
+   ```
+
+The expected result is `status: accepted` with all four probes observed and no
+blockers. The wrapper does not mutate DNS or deploy infrastructure and never
+sends credentials.
+
+Never commit `deploy/secrets-simulation/` or `*.pem` files. Both are
+`.gitignore`d.