enigma-memory 0.1.0

package/scripts/release-provenance.mjs

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PROJECT_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const PACKAGE_ROOT_FILES = Object.freeze(['package.json', 'README.md', 'LICENSE']);
+const SCHEMA = 'enigma.release_provenance.v1';
+const SECRET_OR_LOCAL_BUNDLE_PATH = /(?:^|\/)(?:\.env(?:\.|$)|env\.local$|secrets?|credentials?|tokens?|api[-_]?keys?|private[-_]?keys?|private[-_]?local[-_]?memory|\.enigma|enigma[-_]?bundle|vault[-_]?bundle|local[-_]?bundle|bundle\.json|logs?|npm-debug\.log|yarn-error\.log|pnpm-debug\.log)(?:\/|$|[._-])|\.log(?:\.|$)/i;
+const SECRET_EXTENSION = /\.(?:pem|key|p12|pfx|jks|keystore)(?:\.|$)/i;
+const PRIVATE_PUBLIC_SITE_COLLATERAL = /(?:^|\/)(?:\d+[_-])?(?:private|internal|launch-code|executive|investor|partner|token(?:omics)?|sales|marketing|funnel|community|social|adoption|objections|faq|whitepaper|litepaper|pitch|demo[-_]?scripts?|content[-_]?calendar|brand[-_]?messaging)[^/]*\.(?:html|json|md|txt)$/i;
+const PUBLIC_SITE_MANIFEST_CANDIDATES = Object.freeze([
+  '_public_site/public-site-manifest.json',
+  '_public_site/manifest.json',
+  '_public_site/launch/manifest.json',
+  'public/public-site-manifest.json',
+  'public/manifest.json',
+  'site/public/public-site-manifest.json',
+  'site/public/manifest.json'
+]);
+
+function normalizeRel(rel) {
+  return String(rel).replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+/g, '/');
+}
+
+function safeProjectPath(rel) {
+  const normalized = normalizeRel(rel);
+  if (normalized.length === 0 || path.posix.isAbsolute(normalized) || normalized.split('/').includes('..')) {
+    throw new Error(`Refusing unsafe package path: ${rel}`);
+  }
+  assertSafeEvidencePath(normalized);
+  const full = path.resolve(PROJECT_ROOT, ...normalized.split('/'));
+  const relative = path.relative(PROJECT_ROOT, full);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) throw new Error(`Refusing path outside project root: ${rel}`);
+  return { normalized, full };
+}
+
+function assertSafeEvidencePath(rel) {
+  const normalized = normalizeRel(rel);
+  if (SECRET_OR_LOCAL_BUNDLE_PATH.test(normalized) || SECRET_EXTENSION.test(normalized) || PRIVATE_PUBLIC_SITE_COLLATERAL.test(normalized)) {
+    throw new Error(`Refusing release provenance over sensitive or private path: ${normalized}`);
+  }
+}
+
+function sortedObject(value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortedObject(value[key])]));
+}
+
+function sha256File(full) {
+  const hash = createHash('sha256');
+  hash.update(fs.readFileSync(full));
+  return hash.digest('hex');
+}
+
+function collectFiles(rel, out) {
+  const { normalized, full } = safeProjectPath(rel);
+  if (!fs.existsSync(full)) throw new Error(`Package files entry does not exist: ${normalized}`);
+  const stat = fs.lstatSync(full);
+  if (stat.isSymbolicLink()) throw new Error(`Refusing symlink in package surface: ${normalized}`);
+  if (stat.isDirectory()) {
+    for (const entry of fs.readdirSync(full).sort()) collectFiles(`${normalized.replace(/\/$/, '')}/${entry}`, out);
+    return out;
+  }
+  if (stat.isFile()) out.add(normalized);
+  return out;
+}
+
+function readPackageJson() {
+  const packagePath = path.join(PROJECT_ROOT, 'package.json');
+  return JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+}
+
+function collectPackageSurface(pkg) {
+  if (!Array.isArray(pkg.files)) throw new Error('package.json files must be an array');
+  const rels = new Set();
+  for (const rel of PACKAGE_ROOT_FILES) {
+    const { full, normalized } = safeProjectPath(rel);
+    if (fs.existsSync(full)) rels.add(normalized);
+  }
+  for (const rel of pkg.files) {
+    if (typeof rel !== 'string' || rel.length === 0) throw new Error('package.json files entries must be non-empty strings');
+    collectFiles(rel, rels);
+  }
+  return [...rels].sort();
+}
+
+function fileRecord(rel) {
+  const { full } = safeProjectPath(rel);
+  const stat = fs.statSync(full);
+  return {
+    path: rel,
+    bytes: stat.size,
+    sha256: `sha256:${sha256File(full)}`
+  };
+}
+
+function countFilesUnder(rel, predicate) {
+  const { full } = safeProjectPath(rel);
+  if (!fs.existsSync(full)) return 0;
+  let count = 0;
+  for (const entry of fs.readdirSync(full).sort()) {
+    const childRel = `${normalizeRel(rel).replace(/\/$/, '')}/${entry}`;
+    const childFull = path.join(full, entry);
+    const stat = fs.lstatSync(childFull);
+    if (stat.isSymbolicLink()) throw new Error(`Refusing symlink while counting: ${childRel}`);
+    if (stat.isDirectory()) count += countFilesUnder(childRel, predicate);
+    else if (stat.isFile() && predicate(childRel)) count += 1;
+  }
+  return count;
+}
+
+function optionalChecksum(rel) {
+  const { normalized, full } = safeProjectPath(rel);
+  if (!fs.existsSync(full)) return null;
+  const stat = fs.lstatSync(full);
+  if (stat.isSymbolicLink()) throw new Error(`Refusing symlink optional evidence: ${normalized}`);
+  if (!stat.isFile()) throw new Error(`Optional evidence is not a file: ${normalized}`);
+  return fileRecord(normalized);
+}
+
+function assertManifestPathStrings(value) {
+  if (typeof value === 'string') {
+    if (value.includes('/') || value.includes('\\') || /\.(?:css|html|js|json|md|mjs|png|svg|webp|log|pem|key)$/i.test(value)) {
+      assertSafeEvidencePath(value);
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) assertManifestPathStrings(item);
+    return;
+  }
+  if (value !== null && typeof value === 'object') {
+    for (const item of Object.values(value)) assertManifestPathStrings(item);
+  }
+}
+
+function validatePublicSiteManifest(rel) {
+  const { full } = safeProjectPath(rel);
+  const manifest = JSON.parse(fs.readFileSync(full, 'utf8'));
+  assertManifestPathStrings(manifest);
+}
+
+
+function publicSiteManifestChecksum() {
+  for (const rel of PUBLIC_SITE_MANIFEST_CANDIDATES) {
+    const record = optionalChecksum(rel);
+    if (record) {
+      validatePublicSiteManifest(record.path);
+      return record;
+    }
+  }
+  return null;
+}
+
+function rootHash(files) {
+  const hash = createHash('sha256');
+  for (const file of files) hash.update(`${file.sha256}  ${file.path}\n`, 'utf8');
+  return `sha256:${hash.digest('hex')}`;
+}
+
+function parseArgs(argv) {
+  let out = null;
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--out') {
+      if (out !== null) throw new Error('--out may only be provided once');
+      const value = argv[index + 1];
+      if (!value) throw new Error('--out requires a file path');
+      out = value;
+      index += 1;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  return { out };
+}
+
+function packageSummary(pkg) {
+  const bin = sortedObject(pkg.bin ?? {});
+  return {
+    name: pkg.name,
+    version: pkg.version,
+    type: pkg.type ?? null,
+    engines: sortedObject(pkg.engines ?? {}),
+    bin,
+    bins: bin,
+    exports: sortedObject(pkg.exports ?? {}),
+    scripts: sortedObject(pkg.scripts ?? {})
+  };
+}
+
+function buildProvenance() {
+  const pkg = readPackageJson();
+  const files = collectPackageSurface(pkg).map(fileRecord);
+  const ciWorkflow = optionalChecksum('.github/workflows/ci.yml');
+  const publicSiteManifest = publicSiteManifestChecksum();
+  const computedRootHash = rootHash(files);
+  const specCount = countFilesUnder('specs', (rel) => rel.endsWith('.json'));
+  const testCount = countFilesUnder('test', (rel) => rel.endsWith('.test.mjs') || rel.endsWith('.test.js') || rel.endsWith('.test.ts'));
+  return {
+    schema: SCHEMA,
+    evidence: {
+      kind: 'local_checksum_provenance',
+      claim_boundary: 'Local checksum/SBOM-style package evidence only; unsigned and not a registry, cloud, git, or compliance attestation.',
+      external_credentials_required: false,
+      git_required: false,
+      signed: false,
+      registry_attestation: false
+    },
+    package: packageSummary(pkg),
+    counts: {
+      files: files.length,
+      file_count: files.length,
+      specs: specCount,
+      spec_count: specCount,
+      tests: testCount,
+      test_count: testCount
+    },
+    file_count: files.length,
+    spec_count: specCount,
+    test_count: testCount,
+    ci_workflow: ciWorkflow,
+    public_site_manifest: publicSiteManifest,
+    root_hash: computedRootHash,
+    files
+  };
+}
+
+function writeJsonFile(outPath, value) {
+  const resolved = path.resolve(outPath);
+  fs.mkdirSync(path.dirname(resolved), { recursive: true });
+  fs.writeFileSync(resolved, `${JSON.stringify(value, null, 2)}\n`);
+  return resolved;
+}
+
+try {
+  const { out } = parseArgs(process.argv.slice(2));
+  const provenance = buildProvenance();
+  if (out) {
+    const written = writeJsonFile(out, provenance);
+    process.stdout.write(`${JSON.stringify({ ok: true, path: written, file_count: provenance.counts.files, root_hash: provenance.root_hash })}\n`);
+  } else {
+    process.stdout.write(`${JSON.stringify(provenance, null, 2)}\n`);
+  }
+} catch (error) {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+}

package/scripts/run-backend-readiness-smoke.mjs

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+import { once } from 'node:events';
+import { pathToFileURL } from 'node:url';
+import { createRelayServer } from '../apps/relay/src/server.mjs';
+import { createGatewayServer } from '../apps/gateway/src/server.mjs';
+
+export const BACKEND_READINESS_SMOKE_SCHEMA = 'enigma.backend_readiness_smoke.v1';
+
+const SECRET_OUTPUT_RE = /(?:Bearer\s+[A-Za-z0-9._~+/=-]{12,}|Basic\s+[A-Za-z0-9+/=-]{12,}|-----BEGIN [A-Z ]*PRIVATE KEY-----|https?:\/\/[^\s/@]+:[^\s/@]+@|raw memory|private prompt|full transcript|decrypted capsule|sk-[A-Za-z0-9_-]{16,}|AKIA[0-9A-Z]{16})/iu;
+const SHARED_READINESS_REFS = Object.freeze({
+  network_access_policy_ref: 'network-policy-smoke-ref',
+  kms_custody_ref: 'kms-custody-smoke-ref',
+  tenant_policy_approval_ref: 'tenant-policy-smoke-ref',
+  usage_metering_ref: 'usage-metering-smoke-ref',
+  service_settlement_ref: 'service-settlement-smoke-ref',
+  monitoring_alerting_ref: 'monitoring-alerting-smoke-ref',
+  public_site_security_ref: 'public-site-security-smoke-ref',
+  security_threat_model_ref: 'security-threat-model-smoke-ref',
+  legal_compliance_ref: 'legal-compliance-smoke-ref',
+  support_sla_ref: 'support-sla-smoke-ref',
+  incident_drill_ref: 'incident-drill-smoke-ref',
+  backup_restore_drill_ref: 'backup-restore-drill-smoke-ref',
+});
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const flags = new Map();
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--help') return { help: true };
+    if (!arg.startsWith('--')) continue;
+    if (!argv[index + 1] || argv[index + 1].startsWith('--')) flags.set(arg.slice(2), true);
+    else {
+      flags.set(arg.slice(2), argv[index + 1]);
+      index += 1;
+    }
+  }
+  return { help: false, flags };
+}
+
+function usage() {
+  return `Usage: node scripts/run-backend-readiness-smoke.mjs [--host 127.0.0.1]\n\nStarts in-process relay/gateway HTTP servers on loopback ephemeral ports, probes /livez and /readyz,\nand verifies fail-closed production readiness plus a fully referenced production-ready local fixture.\nIt does not expose admin/data routes, provision cloud resources, or prove hosted live infrastructure.\n`;
+}
+
+function listen(server, host) {
+  return new Promise((resolve, reject) => {
+    const onError = (error) => reject(error);
+    server.once('error', onError);
+    server.listen(0, host, () => {
+      server.off('error', onError);
+      resolve(server.address());
+    });
+  });
+}
+
+async function close(server) {
+  if (!server.listening) return;
+  server.close();
+  await once(server, 'close');
+}
+
+async function getJson(baseUrl, path) {
+  const response = await fetch(`${baseUrl}${path}`, { method: 'GET', headers: { accept: 'application/json' } });
+  const text = await response.text();
+  if (SECRET_OUTPUT_RE.test(text)) throw new Error(`${baseUrl}${path} emitted secret-looking output`);
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    throw new Error(`${baseUrl}${path} did not return JSON`);
+  }
+  return { status: response.status, body, byte_count: Buffer.byteLength(text) };
+}
+
+function missingCount(body) {
+  return Array.isArray(body?.missing_evidence_refs) ? body.missing_evidence_refs.length : null;
+}
+
+function allChecksOk(body) {
+  return Array.isArray(body?.checks) && body.checks.length > 0 && body.checks.every((check) => check.ok === true);
+}
+
+function isLoopbackHost(host) {
+  return host === '127.0.0.1' || host === '::1' || host === 'localhost';
+}
+
+function relayReadyOptions() {
+  return {
+    mode: 'production',
+    now: '1970-01-01T00:00:00.000Z',
+    backend_host_ref: 'relay-backend-host-smoke-ref',
+    dns_tls_ref: 'relay-dns-tls-smoke-ref',
+    runtime_auth_ref: 'relay-runtime-auth-smoke-ref',
+    durable_storage: { kind: 'postgres', ref: 'relay-durable-storage-smoke-ref' },
+    kms_ref: 'relay-kms-smoke-ref',
+    siem_ref: 'relay-siem-smoke-ref',
+    backup_target: 'relay-backup-smoke-ref',
+    monitoring_ref: 'relay-monitoring-smoke-ref',
+    ...SHARED_READINESS_REFS,
+    operator_acceptance: { decision: 'go', status: 'go', ref: 'relay-operator-acceptance-smoke-ref' },
+  };
+}
+
+function gatewayReadyOptions() {
+  return {
+    mode: 'production',
+    backend_host_ref: 'gateway-backend-host-smoke-ref',
+    dns_tls_ref: 'gateway-dns-tls-smoke-ref',
+    durable_storage: { kind: 'postgres', ref: 'gateway-durable-storage-smoke-ref' },
+    state_backend: { kind: 'postgres', ref: 'gateway-state-backend-smoke-ref' },
+    kms_ref: 'gateway-kms-smoke-ref',
+    siem_ref: 'gateway-siem-smoke-ref',
+    backup_target: 'gateway-backup-smoke-ref',
+    monitoring_ref: 'gateway-monitoring-smoke-ref',
+    admin_auth_ref: 'gateway-admin-auth-smoke-ref',
+    data_plane_auth_ref: 'gateway-data-plane-auth-smoke-ref',
+    ...SHARED_READINESS_REFS,
+    operator_acceptance: { decision: 'go', status: 'go', ref: 'gateway-operator-acceptance-smoke-ref' },
+  };
+}
+
+async function probeServer({ service, mode, serverFactory, host, expectedReadyStatus, expectedReadyOk }) {
+  const server = serverFactory();
+  try {
+    const address = await listen(server, host);
+    const baseUrl = `http://${address.address}:${address.port}`;
+    const livez = await getJson(baseUrl, '/livez');
+    const readyz = await getJson(baseUrl, '/readyz');
+    return {
+      service,
+      mode,
+      bind_host: address.address,
+      public_routes_probed: ['/livez', '/readyz'],
+      livez_status: livez.status,
+      livez_ok: livez.body?.ok === true,
+      readyz_status: readyz.status,
+      readyz_ok: readyz.body?.ok === true,
+      readyz_missing_evidence_ref_count: missingCount(readyz.body),
+      readyz_all_checks_ok: allChecksOk(readyz.body),
+      ok: livez.status === 200
+        && livez.body?.ok === true
+        && readyz.status === expectedReadyStatus
+        && readyz.body?.ok === expectedReadyOk,
+    };
+  } finally {
+    await close(server);
+  }
+}
+
+export async function runBackendReadinessSmoke(options = {}) {
+  const host = options.host ?? '127.0.0.1';
+  if (!isLoopbackHost(host)) throw new Error(`backend readiness smoke host must be loopback-only; received ${host}`);
+  const generatedAt = options.generated_at ?? options.generatedAt ?? new Date().toISOString();
+  const checks = [];
+  checks.push(await probeServer({
+    service: 'relay',
+    mode: 'production-fail-closed',
+    host,
+    expectedReadyStatus: 503,
+    expectedReadyOk: false,
+    serverFactory: () => createRelayServer({ mode: 'production', now: '1970-01-01T00:00:00.000Z' }),
+  }));
+  checks.push(await probeServer({
+    service: 'gateway',
+    mode: 'production-fail-closed',
+    host,
+    expectedReadyStatus: 503,
+    expectedReadyOk: false,
+    serverFactory: () => createGatewayServer({ mode: 'production' }),
+  }));
+  checks.push(await probeServer({
+    service: 'relay',
+    mode: 'production-referenced-fixture',
+    host,
+    expectedReadyStatus: 200,
+    expectedReadyOk: true,
+    serverFactory: () => createRelayServer(relayReadyOptions()),
+  }));
+  checks.push(await probeServer({
+    service: 'gateway',
+    mode: 'production-referenced-fixture',
+    host,
+    expectedReadyStatus: 200,
+    expectedReadyOk: true,
+    serverFactory: () => createGatewayServer(gatewayReadyOptions()),
+  }));
+  const result = {
+    schema: BACKEND_READINESS_SMOKE_SCHEMA,
+    generated_at: generatedAt,
+    ok: checks.every((check) => check.ok === true) && isLoopbackHost(host),
+    check_count: checks.length,
+    loopback_only: isLoopbackHost(host),
+    checks,
+    claim_boundary: [
+      'This smoke starts local in-process HTTP servers on loopback ephemeral ports only.',
+      'It verifies /livez and /readyz behavior, fail-closed production defaults, and fully referenced production fixture readiness.',
+      'It does not prove hosted DNS, TLS, Cloudflare, durable cloud storage, KMS, SIEM, backup, operator acceptance, or customer BYOC infrastructure is live.',
+    ],
+  };
+  if (SECRET_OUTPUT_RE.test(JSON.stringify(result))) throw new Error('backend readiness smoke output appears to contain a secret');
+  return result;
+}
+
+export async function runCli(argv = process.argv.slice(2), options = {}) {
+  const parsed = parseArgs(argv);
+  if (parsed.help) return { text: usage() };
+  const host = parsed.flags?.get('host') ?? options.host ?? '127.0.0.1';
+  return { json: await runBackendReadinessSmoke({ ...options, host }) };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    const result = await runCli();
+    if (result.text) process.stdout.write(result.text);
+    else process.stdout.write(`${JSON.stringify(result.json, null, 2)}\n`);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stdout.write(`${JSON.stringify({ schema: BACKEND_READINESS_SMOKE_SCHEMA, ok: false, error: { code: 'BACKEND_READINESS_SMOKE_ERROR', message } }, null, 2)}\n`);
+    process.exitCode = 1;
+  }
+}

package/scripts/validate-backup-restore-drill.mjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const BACKUP_RESTORE_DRILL_SCHEMA = 'enigma.backup_restore_drill.v1';
+export const BACKUP_RESTORE_DRILL_RESULT_SCHEMA = 'enigma.backup_restore_drill_result.v1';
+
+const SECRET_VALUE_RE = /(?:Bearer\s+[A-Za-z0-9._~+/=-]{12,}|Basic\s+[A-Za-z0-9+/=-]{12,}|-----BEGIN [A-Z ]*PRIVATE KEY-----|https?:\/\/[^\s/@]+:[^\s/@]+@|raw memory|private prompt|full transcript|decrypted capsule|sk-[A-Za-z0-9_-]{16,}|AKIA[0-9A-Z]{16})/iu;
+const SECRET_KEY_RE = /(?:password|passwd|pwd|token|api[_-]?key|private[_-]?key|secret|raw[_-]?memory|plaintext|plain[_-]?text|prompt|completion|transcript|embedding|provider[_-]?response)/iu;
+const SAFE_SECRET_NAMED_KEYS = new Set(['kms_or_secret_custody_ref']);
+const HASH_RE = /^sha256:[a-f0-9]{64}$/i;
+const STATUS_PASS = new Set(['pass', 'passed', 'go', 'verified']);
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function nonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function assertNoSecrets(value, path = 'drill') {
+  if (typeof value === 'string') {
+    if (!/\.claim_boundary\[\d+\]$/.test(path) && SECRET_VALUE_RE.test(value)) throw new Error(`${path} contains secret or raw-memory-looking data`);
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => assertNoSecrets(item, `${path}[${index}]`));
+    return;
+  }
+  if (!isPlainObject(value)) return;
+  for (const [key, child] of Object.entries(value)) {
+    if (SECRET_KEY_RE.test(key) && !SAFE_SECRET_NAMED_KEYS.has(key)) throw new Error(`${path}.${key} uses a forbidden field name`);
+    assertNoSecrets(child, `${path}.${key}`);
+  }
+}
+
+function blocker(message, path) {
+  return { message, path };
+}
+
+function positiveNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+
+function hashOk(value) {
+  return nonEmptyString(value) && HASH_RE.test(value);
+}
+
+export function validateBackupRestoreDrill(drill, options = {}) {
+  if (!isPlainObject(drill)) throw new Error('backup restore drill must be an object');
+  assertNoSecrets(drill);
+  const blockers = [];
+  if (drill.schema !== BACKUP_RESTORE_DRILL_SCHEMA) blockers.push(blocker('schema mismatch', 'schema'));
+  const metadata = drill.metadata;
+  if (!isPlainObject(metadata)) blockers.push(blocker('metadata is required', 'metadata'));
+  else {
+    for (const field of ['drill_id', 'environment', 'tenant', 'storage_engine', 'started_at', 'completed_at', 'operator', 'backup_owner', 'restore_owner']) {
+      if (!nonEmptyString(metadata[field])) blockers.push(blocker(`metadata.${field} is required`, `metadata.${field}`));
+    }
+    if (Number.isNaN(Date.parse(metadata.started_at ?? ''))) blockers.push(blocker('metadata.started_at must be ISO time', 'metadata.started_at'));
+    if (Number.isNaN(Date.parse(metadata.completed_at ?? ''))) blockers.push(blocker('metadata.completed_at must be ISO time', 'metadata.completed_at'));
+  }
+  const backup = drill.backup;
+  if (!isPlainObject(backup)) blockers.push(blocker('backup object is required', 'backup'));
+  else {
+    for (const field of ['backup_ref', 'scope_ref', 'storage_ref', 'kms_or_secret_custody_ref']) {
+      if (!nonEmptyString(backup[field])) blockers.push(blocker(`backup.${field} is required`, `backup.${field}`));
+    }
+    if (!hashOk(backup.source_snapshot_hash)) blockers.push(blocker('backup.source_snapshot_hash must be sha256', 'backup.source_snapshot_hash'));
+    if (!positiveNumber(backup.source_row_count)) blockers.push(blocker('backup.source_row_count must be non-negative number', 'backup.source_row_count'));
+  }
+  const restore = drill.restore;
+  if (!isPlainObject(restore)) blockers.push(blocker('restore object is required', 'restore'));
+  else {
+    for (const field of ['restore_ref', 'target_ref', 'restore_started_at', 'restore_completed_at']) {
+      if (!nonEmptyString(restore[field])) blockers.push(blocker(`restore.${field} is required`, `restore.${field}`));
+    }
+    if (!hashOk(restore.restored_snapshot_hash)) blockers.push(blocker('restore.restored_snapshot_hash must be sha256', 'restore.restored_snapshot_hash'));
+    if (!positiveNumber(restore.restored_row_count)) blockers.push(blocker('restore.restored_row_count must be non-negative number', 'restore.restored_row_count'));
+  }
+  const verification = drill.verification;
+  if (!isPlainObject(verification)) blockers.push(blocker('verification object is required', 'verification'));
+  else {
+    if (!STATUS_PASS.has(String(verification.status ?? '').toLowerCase())) blockers.push(blocker('verification.status must be pass', 'verification.status'));
+    if (!hashOk(verification.verifier_output_hash)) blockers.push(blocker('verification.verifier_output_hash must be sha256', 'verification.verifier_output_hash'));
+    if (!nonEmptyString(verification.verifier_ref)) blockers.push(blocker('verification.verifier_ref is required', 'verification.verifier_ref'));
+  }
+  const rpo = drill.rpo_rto;
+  if (!isPlainObject(rpo)) blockers.push(blocker('rpo_rto object is required', 'rpo_rto'));
+  else {
+    if (!positiveNumber(rpo.rpo_seconds)) blockers.push(blocker('rpo_rto.rpo_seconds must be non-negative number', 'rpo_rto.rpo_seconds'));
+    if (!positiveNumber(rpo.rto_seconds)) blockers.push(blocker('rpo_rto.rto_seconds must be non-negative number', 'rpo_rto.rto_seconds'));
+    if (!positiveNumber(rpo.max_rpo_seconds)) blockers.push(blocker('rpo_rto.max_rpo_seconds must be non-negative number', 'rpo_rto.max_rpo_seconds'));
+    if (!positiveNumber(rpo.max_rto_seconds)) blockers.push(blocker('rpo_rto.max_rto_seconds must be non-negative number', 'rpo_rto.max_rto_seconds'));
+    if (positiveNumber(rpo.rpo_seconds) && positiveNumber(rpo.max_rpo_seconds) && rpo.rpo_seconds > rpo.max_rpo_seconds) blockers.push(blocker('RPO exceeds maximum', 'rpo_rto.rpo_seconds'));
+    if (positiveNumber(rpo.rto_seconds) && positiveNumber(rpo.max_rto_seconds) && rpo.rto_seconds > rpo.max_rto_seconds) blockers.push(blocker('RTO exceeds maximum', 'rpo_rto.rto_seconds'));
+  }
+  if (isPlainObject(backup) && isPlainObject(restore) && hashOk(backup.source_snapshot_hash) && hashOk(restore.restored_snapshot_hash) && backup.source_snapshot_hash !== restore.restored_snapshot_hash) {
+    blockers.push(blocker('restored snapshot hash does not match source snapshot hash', 'restore.restored_snapshot_hash'));
+  }
+  if (isPlainObject(backup) && isPlainObject(restore) && positiveNumber(backup.source_row_count) && positiveNumber(restore.restored_row_count) && backup.source_row_count !== restore.restored_row_count) {
+    blockers.push(blocker('restored row count does not match source row count', 'restore.restored_row_count'));
+  }
+  const result = {
+    schema: BACKUP_RESTORE_DRILL_RESULT_SCHEMA,
+    generated_at: options.generated_at ?? options.generatedAt ?? new Date(0).toISOString(),
+    ok: blockers.length === 0,
+    status: blockers.length === 0 ? 'pass' : 'blocked',
+    blockers,
+    claim_boundary: [
+      'Backup restore drill validation checks declared evidence only; it does not access storage, secrets, or cloud resources.',
+      'A pass result is evidence for one named drill and does not prove all future restores.',
+      'Raw memory, credentials, private keys, prompts, transcripts, and decrypted content must remain outside drill artifacts.',
+    ],
+  };
+  assertNoSecrets(result, 'result');
+  return result;
+}
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const flags = new Map();
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg.startsWith('--')) continue;
+    const eq = arg.indexOf('=');
+    if (eq !== -1) flags.set(arg.slice(2, eq), arg.slice(eq + 1));
+    else if (!argv[index + 1] || argv[index + 1].startsWith('--')) flags.set(arg.slice(2), true);
+    else {
+      flags.set(arg.slice(2), argv[index + 1]);
+      index += 1;
+    }
+  }
+  return flags;
+}
+
+function getFlag(flags, names) {
+  for (const name of names) if (flags.has(name)) return flags.get(name);
+  return undefined;
+}
+
+async function main() {
+  const flags = parseArgs();
+  const drillPath = getFlag(flags, ['drill', 'in']);
+  if (!nonEmptyString(drillPath)) throw new Error('--drill <path> is required');
+  const drill = JSON.parse(await readFile(resolve(String(drillPath)), 'utf8'));
+  const result = validateBackupRestoreDrill(drill, { generated_at: new Date().toISOString() });
+  const out = getFlag(flags, ['out']);
+  const text = `${JSON.stringify(result, null, 2)}\n`;
+  if (out && out !== true) {
+    const outPath = resolve(String(out));
+    await mkdir(dirname(outPath), { recursive: true });
+    await writeFile(outPath, text, 'utf8');
+  }
+  process.stdout.write(text);
+  process.exitCode = result.ok ? 0 : 1;
+}
+
+const invokedPath = process.argv[1] ? resolve(process.argv[1]) : '';
+if (invokedPath === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    process.stderr.write(`${error.name ?? 'Error'}: ${error.message}\n`);
+    process.exitCode = 1;
+  });
+}