@holoscript/holosystem 0.2.2 → 0.2.3

package/bin/holosystem.mjs

@@ -3,10 +3,19 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 
 import {
+  buildSubstrateClosure,
   createHoloSystemConfig,
   discoverConsumptionSurfaceCatalog,
   discoverSourceLineage,
+  importDebianPackageSnapshot,
+  importNpmPackageLock,
+  inspectNativeBuildSource,
   inspectHoloSystemConfig,
+  inspectVmExecutor,
+  inspectVmLaunchAsset,
+  runNativeBuild,
+  runVmLaunch,
+  runWhpxVmLaunch,
 } from '../src/index.mjs';
 
 const CLI_RECEIPT_SCHEMA = 'holoscript.holosystem.cli-receipt.v1';
@@ -18,13 +27,22 @@ Usage:
   holosystem inspect [file|-] [--json]
   holosystem catalog --seeds <file> --portfolio <file> --manifest <file> [--lineage <file>] [--active-batches <file>] [--promotions <file>] [--output <file>] [--json]
   holosystem lineage --portfolio <file> [--concurrency <1-12>] [--output <file>] [--json]
+  holosystem substrate-import --lock <package-lock.json> --config <file> [--output <file>] [--force] [--json]
+  holosystem substrate-import-debian --status <status> (--packages <Packages> | --sources <json>) --maintainer-scripts <json> --config <file> [--output <file>] [--force] [--json]
+  holosystem native-build-source --source <directory> [--json]
+  holosystem native-build --plan <file> --source <directory> --executor <file> --artifact-dir <directory> [--output <receipt>] [--force] [--json]
+  holosystem vm-executor --runtime <directory> [--json]
+  holosystem vm-asset --kind <kernel|initrd> --file <file> [--json]
+  holosystem vm-launch --plan <file> --runtime <directory> --kernel <file> --initrd <file> [--output <receipt>] [--force] [--json]
+  holosystem vm-launch-whpx --plan <file> --runtime <directory> --kernel <file> --initrd <file> [--output <receipt>] [--force] [--json]
+  holosystem substrate --input <file> [--output <file>] [--force] [--json]
   holosystem --help
   holosystem --version
 
 Defaults:
   create writes holosystem.config.json and never overwrites it without --force.
   inspect reads holosystem.config.json. Use - to read JSON from stdin.
-  catalog and lineage read caller-owned evidence and never read credentials.
+  catalog, lineage, substrate imports, and substrate read caller-owned evidence and never read credentials.
 `;
 
 function die(message, { json = false, code = 1 } = {}) {
@@ -143,9 +161,42 @@ function readOptionalJsonFile(path, fallback) {
   return JSON.parse(readFileSync(resolve(process.cwd(), path), 'utf8').replace(/^\uFEFF/u, ''));
 }
 
+function readTextFile(path, label) {
+  if (!path) throw new Error(`--${label} is required.`);
+  return readFileSync(resolve(process.cwd(), path), 'utf8').replace(/^\uFEFF/u, '');
+}
+
+function readDebianSources(path) {
+  const manifest = readJsonFile(path, 'sources');
+  const entries = Array.isArray(manifest) ? manifest : manifest?.sources;
+  if (!Array.isArray(entries) || entries.length === 0) {
+    throw new Error('--sources must contain a non-empty JSON array.');
+  }
+  return entries.map((entry, index) => {
+    if (!entry?.packages) {
+      throw new Error(`sources[${index}].packages is required.`);
+    }
+    return {
+      packagesIndex: readTextFile(entry.packages, `sources[${index}].packages`),
+      repository: entry.repository
+        ? {
+            ...entry.repository,
+            authentication: entry.authentication || entry.repository.authentication,
+          }
+        : {
+            uri: entry.uri,
+            packagesIndexDigest: entry.packagesIndexDigest,
+            authentication: entry.authentication,
+          },
+      custody: entry.custody,
+    };
+  });
+}
+
 function writeJsonOutput(path, value, { force = false } = {}) {
   const absolute = resolve(process.cwd(), path);
-  if (existsSync(absolute) && !force) throw new Error(`${path} already exists; use --force to replace it.`);
+  if (existsSync(absolute) && !force)
+    throw new Error(`${path} already exists; use --force to replace it.`);
   writeFileSync(absolute, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
 }
 
@@ -200,7 +251,8 @@ async function runCatalog(args) {
     die(error.message, { json: args.includes('--json') });
   }
   const { options, positionals } = parsed;
-  if (positionals.length > 0) die('catalog does not accept positional arguments.', { json: options.json });
+  if (positionals.length > 0)
+    die('catalog does not accept positional arguments.', { json: options.json });
   let catalog;
   try {
     const seeds = readJsonFile(options.seeds, 'seeds');
@@ -214,8 +266,12 @@ async function runCatalog(args) {
       portfolio,
       manifest,
       lineage,
-      activeProofBatches: Array.isArray(activeProofBatches) ? activeProofBatches : activeProofBatches.batches,
-      promotionHistory: Array.isArray(promotionHistory) ? promotionHistory : promotionHistory.promotions,
+      activeProofBatches: Array.isArray(activeProofBatches)
+        ? activeProofBatches
+        : activeProofBatches.batches,
+      promotionHistory: Array.isArray(promotionHistory)
+        ? promotionHistory
+        : promotionHistory.promotions,
       evidence: {
         operatingSet: options.manifest,
         packageAdmission: options.portfolio,
@@ -230,7 +286,9 @@ async function runCatalog(args) {
   else {
     process.stdout.write(`Catalog: ${catalog.status}\n`);
     for (const [id, rail] of Object.entries(catalog.rails)) {
-      process.stdout.write(`${id}: published=${rail.published} ready=${rail.consumerReady} gaps=${rail.gaps}\n`);
+      process.stdout.write(
+        `${id}: published=${rail.published} ready=${rail.consumerReady} gaps=${rail.gaps}\n`
+      );
     }
     if (options.output) process.stdout.write(`Wrote ${options.output}\n`);
   }
@@ -251,7 +309,8 @@ async function runLineage(args) {
     die(error.message, { json: args.includes('--json') });
   }
   const { options, positionals } = parsed;
-  if (positionals.length > 0) die('lineage does not accept positional arguments.', { json: options.json });
+  if (positionals.length > 0)
+    die('lineage does not accept positional arguments.', { json: options.json });
   let lineage;
   try {
     const portfolio = readJsonFile(options.portfolio, 'portfolio');
@@ -273,6 +332,346 @@ async function runLineage(args) {
   if (lineage.status !== 'complete') process.exitCode = 2;
 }
 
+function runSubstrateImport(args) {
+  let parsed;
+  try {
+    parsed = parseArguments(args, {
+      lock: 'value',
+      config: 'value',
+      output: 'value',
+      force: 'boolean',
+      json: 'boolean',
+    });
+  } catch (error) {
+    die(error.message, { json: args.includes('--json') });
+  }
+  const { options, positionals } = parsed;
+  if (positionals.length > 0) {
+    die('substrate-import does not accept positional arguments.', { json: options.json });
+  }
+
+  let imported;
+  try {
+    const lockfile = readJsonFile(options.lock, 'lock');
+    const config = readJsonFile(options.config, 'config');
+    imported = importNpmPackageLock({
+      lockfile,
+      root: config.root,
+      verificationPolicy: config.verificationPolicy,
+      includeDev: config.includeDev,
+      externalCustody: config.externalCustody,
+    });
+    if (options.output) writeJsonOutput(options.output, imported.input, { force: options.force });
+  } catch (error) {
+    die(`Cannot import npm substrate: ${error.message}`, {
+      json: options.json,
+      code: 2,
+    });
+  }
+
+  if (options.json) outputJson(imported);
+  else {
+    process.stdout.write(
+      `Substrate import: ${imported.status} components=${imported.summary.components} dependencies=${imported.summary.dependencies} missing-attestations=${imported.summary.missingAttestations}\n`
+    );
+    for (const item of imported.issues) {
+      process.stdout.write(`BLOCK ${item.code} ${item.path}: ${item.message}\n`);
+    }
+    if (options.output) process.stdout.write(`Wrote ${options.output}\n`);
+  }
+  if (!imported.importable) process.exitCode = 2;
+}
+
+function runDebianSubstrateImport(args) {
+  let parsed;
+  try {
+    parsed = parseArguments(args, {
+      status: 'value',
+      packages: 'value',
+      sources: 'value',
+      'maintainer-scripts': 'value',
+      config: 'value',
+      output: 'value',
+      force: 'boolean',
+      json: 'boolean',
+    });
+  } catch (error) {
+    die(error.message, { json: args.includes('--json') });
+  }
+  const { options, positionals } = parsed;
+  if (positionals.length > 0) {
+    die('substrate-import-debian does not accept positional arguments.', { json: options.json });
+  }
+  if (Boolean(options.packages) === Boolean(options.sources)) {
+    die('Provide exactly one of --packages or --sources.', { json: options.json });
+  }
+
+  let imported;
+  try {
+    const status = readTextFile(options.status, 'status');
+    const packagesIndex = options.packages ? readTextFile(options.packages, 'packages') : null;
+    const sources = options.sources ? readDebianSources(options.sources) : null;
+    const maintainerScripts = readJsonFile(options['maintainer-scripts'], 'maintainer-scripts');
+    const config = readJsonFile(options.config, 'config');
+    imported = importDebianPackageSnapshot({
+      status,
+      sources,
+      packagesIndex,
+      maintainerScripts,
+      repository: sources ? null : config.repository,
+      root: config.root,
+      verificationPolicy: config.verificationPolicy,
+      externalCustody: config.externalCustody,
+    });
+    if (options.output) writeJsonOutput(options.output, imported.input, { force: options.force });
+  } catch (error) {
+    die(`Cannot import Debian substrate: ${error.message}`, {
+      json: options.json,
+      code: 2,
+    });
+  }
+
+  if (options.json) outputJson(imported);
+  else {
+    process.stdout.write(
+      `Debian substrate import: ${imported.status} packages=${imported.summary.installedPackages} dependencies=${imported.summary.dependencies} maintainer-script-packages=${imported.summary.maintainerScriptPackages}\n`
+    );
+    for (const item of imported.issues) {
+      process.stdout.write(`BLOCK ${item.code} ${item.path}: ${item.message}\n`);
+    }
+    if (options.output) process.stdout.write(`Wrote ${options.output}\n`);
+  }
+  if (!imported.importable) process.exitCode = 2;
+}
+
+function runSubstrate(args) {
+  let parsed;
+  try {
+    parsed = parseArguments(args, {
+      input: 'value',
+      output: 'value',
+      force: 'boolean',
+      json: 'boolean',
+    });
+  } catch (error) {
+    die(error.message, { json: args.includes('--json') });
+  }
+  const { options, positionals } = parsed;
+  if (positionals.length > 0) {
+    die('substrate does not accept positional arguments.', { json: options.json });
+  }
+
+  let substrate;
+  try {
+    const input = readJsonFile(options.input, 'input');
+    substrate = buildSubstrateClosure(input);
+    if (options.output) writeJsonOutput(options.output, substrate, { force: options.force });
+  } catch (error) {
+    die(`Cannot build substrate closure: ${error.message}`, {
+      json: options.json,
+      code: 2,
+    });
+  }
+
+  if (options.json) outputJson(substrate);
+  else {
+    process.stdout.write(
+      `Substrate: ${substrate.status} components=${substrate.summary.components} dependencies=${substrate.summary.dependencies} external=${substrate.summary.external}\n`
+    );
+    for (const boundary of substrate.sovereignty.externalBoundaries) {
+      process.stdout.write(
+        `EXTERNAL ${boundary.id} kind=${boundary.kind} owner=${boundary.owner}\n`
+      );
+    }
+    for (const item of substrate.issues) {
+      process.stdout.write(`BLOCK ${item.code} ${item.path}: ${item.message}\n`);
+    }
+    if (options.output) process.stdout.write(`Wrote ${options.output}\n`);
+  }
+  if (!substrate.ready) process.exitCode = 2;
+}
+
+function runNativeBuildSource(args) {
+  let parsed;
+  try {
+    parsed = parseArguments(args, { source: 'value', json: 'boolean' });
+  } catch (error) {
+    die(error.message, { json: args.includes('--json') });
+  }
+  const { options, positionals } = parsed;
+  if (positionals.length > 0) {
+    die('native-build-source does not accept positional arguments.', { json: options.json });
+  }
+  const report = inspectNativeBuildSource({ sourceDirectory: options.source });
+  if (options.json) outputJson(report);
+  else {
+    process.stdout.write(
+      `Native source: ${report.ready ? 'ready' : 'blocked'} files=${report.summary.files} bytes=${report.summary.bytes}\n`
+    );
+    if (report.digest) process.stdout.write(`Digest: ${report.digest}\n`);
+    for (const item of report.issues) {
+      process.stdout.write(`BLOCK ${item.code} ${item.path}: ${item.message}\n`);
+    }
+  }
+  if (!report.ready) process.exitCode = 2;
+}
+
+function runNativeBuildCommand(args) {
+  let parsed;
+  try {
+    parsed = parseArguments(args, {
+      plan: 'value',
+      source: 'value',
+      executor: 'value',
+      'artifact-dir': 'value',
+      output: 'value',
+      force: 'boolean',
+      json: 'boolean',
+    });
+  } catch (error) {
+    die(error.message, { json: args.includes('--json') });
+  }
+  const { options, positionals } = parsed;
+  if (positionals.length > 0) {
+    die('native-build does not accept positional arguments.', { json: options.json });
+  }
+
+  let nativeBuild;
+  try {
+    const plan = readJsonFile(options.plan, 'plan');
+    if (!options.source) throw new Error('--source is required.');
+    if (!options.executor) throw new Error('--executor is required.');
+    if (!options['artifact-dir']) throw new Error('--artifact-dir is required.');
+    nativeBuild = runNativeBuild({
+      plan,
+      sourceDirectory: options.source,
+      outputDirectory: options['artifact-dir'],
+      executorPath: options.executor,
+    });
+    if (options.output) writeJsonOutput(options.output, nativeBuild, { force: options.force });
+  } catch (error) {
+    die(`Cannot run native build: ${error.message}`, { json: options.json, code: 2 });
+  }
+
+  if (options.json) outputJson(nativeBuild);
+  else {
+    process.stdout.write(
+      `Native build: ${nativeBuild.status} reproducible=${nativeBuild.reproducible ? 'yes' : 'no'} verified=${nativeBuild.verified ? 'yes' : 'no'}\n`
+    );
+    if (nativeBuild.output.digest) {
+      process.stdout.write(`Artifact: ${nativeBuild.output.path} ${nativeBuild.output.digest}\n`);
+    }
+    for (const item of nativeBuild.issues) {
+      process.stdout.write(`BLOCK ${item.code} ${item.path}: ${item.message}\n`);
+    }
+    if (options.output) process.stdout.write(`Wrote ${options.output}\n`);
+  }
+  if (!nativeBuild.verified) process.exitCode = 2;
+}
+
+function runVmExecutor(args) {
+  let parsed;
+  try {
+    parsed = parseArguments(args, { runtime: 'value', json: 'boolean' });
+  } catch (error) {
+    die(error.message, { json: args.includes('--json') });
+  }
+  const { options, positionals } = parsed;
+  if (positionals.length > 0) {
+    die('vm-executor does not accept positional arguments.', { json: options.json });
+  }
+  const report = inspectVmExecutor({ executorDirectory: options.runtime });
+  if (options.json) outputJson(report);
+  else {
+    process.stdout.write(
+      `VM executor: ${report.ready ? 'ready' : 'blocked'} files=${report.summary.files} bytes=${report.summary.bytes}\n`
+    );
+    if (report.digest) process.stdout.write(`Digest: ${report.digest}\n`);
+    for (const item of report.issues) {
+      process.stdout.write(`BLOCK ${item.code} ${item.path}: ${item.message}\n`);
+    }
+  }
+  if (!report.ready) process.exitCode = 2;
+}
+
+function runVmAsset(args) {
+  let parsed;
+  try {
+    parsed = parseArguments(args, { kind: 'value', file: 'value', json: 'boolean' });
+  } catch (error) {
+    die(error.message, { json: args.includes('--json') });
+  }
+  const { options, positionals } = parsed;
+  if (positionals.length > 0) {
+    die('vm-asset does not accept positional arguments.', { json: options.json });
+  }
+  const report = inspectVmLaunchAsset({ assetPath: options.file, kind: options.kind });
+  if (options.json) outputJson(report);
+  else {
+    process.stdout.write(
+      `VM asset: ${report.ready ? 'ready' : 'blocked'} kind=${report.kind || 'invalid'} bytes=${report.bytes ?? 0}\n`
+    );
+    if (report.digest) process.stdout.write(`Digest: ${report.digest}\n`);
+    for (const item of report.issues) {
+      process.stdout.write(`BLOCK ${item.code} ${item.path}: ${item.message}\n`);
+    }
+  }
+  if (!report.ready) process.exitCode = 2;
+}
+
+function runVmLaunchCommand(args, { launcher = runVmLaunch, commandName = 'vm-launch' } = {}) {
+  let parsed;
+  try {
+    parsed = parseArguments(args, {
+      plan: 'value',
+      runtime: 'value',
+      kernel: 'value',
+      initrd: 'value',
+      output: 'value',
+      force: 'boolean',
+      json: 'boolean',
+    });
+  } catch (error) {
+    die(error.message, { json: args.includes('--json') });
+  }
+  const { options, positionals } = parsed;
+  if (positionals.length > 0) {
+    die(`${commandName} does not accept positional arguments.`, { json: options.json });
+  }
+
+  let launch;
+  try {
+    const plan = readJsonFile(options.plan, 'plan');
+    if (!options.runtime) throw new Error('--runtime is required.');
+    if (!options.kernel) throw new Error('--kernel is required.');
+    if (!options.initrd) throw new Error('--initrd is required.');
+    launch = launcher({
+      plan,
+      executorDirectory: options.runtime,
+      kernelPath: options.kernel,
+      initrdPath: options.initrd,
+    });
+    if (options.output) writeJsonOutput(options.output, launch, { force: options.force });
+  } catch (error) {
+    die(`Cannot run VM launch: ${error.message}`, { json: options.json, code: 2 });
+  }
+
+  if (options.json) outputJson(launch);
+  else {
+    process.stdout.write(
+      `VM launch: ${launch.status} deterministic=${launch.deterministic ? 'yes' : 'no'} hardware-backed=${launch.hardwareBacked ? 'yes' : 'no'} host-isolated=${launch.isolation?.verified ? 'yes' : 'no'}\n`
+    );
+    if (launch.measurementDigest) {
+      process.stdout.write(`Measurement: ${launch.measurementDigest}\n`);
+    }
+    for (const item of launch.issues) {
+      process.stdout.write(`BLOCK ${item.code} ${item.path}: ${item.message}\n`);
+    }
+    if (options.output) process.stdout.write(`Wrote ${options.output}\n`);
+  }
+  if (!launch.verified) process.exitCode = 2;
+}
+
 const argv = process.argv.slice(2);
 const command = argv[0];
 if (!command || command === '--help' || command === '-h' || command === 'help') {
@@ -288,6 +687,27 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
   await runCatalog(argv.slice(1));
 } else if (command === 'lineage') {
   await runLineage(argv.slice(1));
+} else if (command === 'substrate-import') {
+  runSubstrateImport(argv.slice(1));
+} else if (command === 'substrate-import-debian') {
+  runDebianSubstrateImport(argv.slice(1));
+} else if (command === 'native-build-source') {
+  runNativeBuildSource(argv.slice(1));
+} else if (command === 'native-build') {
+  runNativeBuildCommand(argv.slice(1));
+} else if (command === 'vm-executor') {
+  runVmExecutor(argv.slice(1));
+} else if (command === 'vm-asset') {
+  runVmAsset(argv.slice(1));
+} else if (command === 'vm-launch') {
+  runVmLaunchCommand(argv.slice(1));
+} else if (command === 'vm-launch-whpx') {
+  runVmLaunchCommand(argv.slice(1), {
+    launcher: runWhpxVmLaunch,
+    commandName: 'vm-launch-whpx',
+  });
+} else if (command === 'substrate') {
+  runSubstrate(argv.slice(1));
 } else {
   die(`Unknown command ${command}. Run holosystem --help.`);
 }

package/docs/native-build-threat-model.md

@@ -0,0 +1,150 @@
+# Native-build threat model
+
+This threat model covers `holoscript.holosystem.native-build-plan.v1` and the
+Docker executor in `@holoscript/holosystem`. Its security objective is narrow:
+compile a caller-pinned source snapshot into one reproducible Linux AMD64 ELF
+artifact without giving the plan a general process-execution language.
+
+It does not establish that a compiler image is benevolent, that Docker or the
+host kernel is uncompromised, or that two runs under one image are independent
+rebuilds. Those claims require separately governed trust roots and the existing
+signed rebuild-attestation gate.
+
+## Trust assumptions
+
+- The caller establishes the expected source, Docker executable, compiler-image,
+  and final artifact digests through a control plane outside the build plan.
+- The host filesystem, Docker daemon, kernel, CPU, and cryptographic primitives
+  are trusted to execute their documented behavior.
+- An immutable OCI manifest digest identifies stable image bytes; it does not
+  prove publisher identity or compiler correctness.
+- The independent builder reviews the native receipt before signing the existing
+  rebuild-attestation payload. A receipt hash is content integrity, not a
+  signature or organizational-independence proof.
+
+## Adversary classes
+
+| Adversary                        | Capability                                                             | Goal                                                                                            | Measurable success                                                                                           |
+| -------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| Plan-language attacker           | Controls every JSON plan field                                         | Reach a shell, arbitrary executable, network, privilege, host mount, or free-form compiler flag | A supplied field changes process identity or weakens a fixed Docker policy                                   |
+| Source-race attacker             | Mutates caller source while a build starts                             | Compile bytes different from the pinned source digest                                           | Mounted snapshot digest differs from the plan while the receipt is `verified`                                |
+| Executor-substitution attacker   | Replaces or redirects the Docker executable                            | Run a different host program under an accepted plan                                             | Process launch occurs after executable type or digest mismatch                                               |
+| Output-smuggling attacker        | Controls compiler behavior inside the container                        | Export undeclared files, links, oversized data, or the wrong machine format                     | A non-declared or non-AMD64-ELF artifact reaches the caller output directory                                 |
+| Reproducibility attacker         | Makes clean builds diverge                                             | Obtain coverage for unstable or environment-dependent output                                    | The receipt includes `native-build` when two run digests differ                                              |
+| Diagnostic-exfiltration attacker | Places secrets or host paths in compiler output                        | Copy sensitive diagnostics into a portable receipt                                              | Receipt JSON contains raw stdout, stderr, source contents, or operational paths                              |
+| Compiler-image attacker          | Publishes a malicious but digest-pinned image                          | Exploit Docker/kernel or emit reproducible malware                                              | Outside the runner's prevention boundary; detected only by independent rebuild and image-governance controls |
+| Host-control attacker            | Controls Docker daemon, host kernel, or same-user filesystem namespace | Forge all observations or race executable/output paths                                          | Explicitly out of scope for this receipt; requires measured host/boot custody                                |
+
+## Attack specifications and defenses
+
+### A1: shell and option injection
+
+Precondition: the attacker can submit a plan. They add `command`, `args`, an
+image tag, a traversal path, a compiler plugin flag, or a weaker network/user
+policy. Success means any attacker text is forwarded as executable or shell
+input.
+
+Defense: the plan rejects unknown fields, exposes only GCC/C11 plus a small
+optimization enum, and generates the complete Docker and compiler argv. The
+production API binds directly to `spawnSync`; its test process adapter is not
+exported from the package root. Docker receives `shell: false`, an overridden
+`/usr/local/bin/gcc` entrypoint, no network, no IPC namespace sharing, a
+read-only root and source, no capabilities, no-new-privileges, and a non-root
+uid/gid.
+
+Regression evidence: `inspects a closed declarative build vocabulary`, `does
+not publish process-runner injection through the package API`.
+
+### A2: source time-of-check/time-of-use swap
+
+Precondition: the attacker can mutate the source directory during launch. They
+replace a translation unit or introduce a link after the initial digest scan.
+Success means different bytes reach GCC while the plan's source digest remains
+accepted.
+
+Defense: the runner rejects links and special files, copies only the inspected
+manifest into a private temporary snapshot, re-hashes that snapshot, and mounts
+the snapshot read-only for both builds. A mismatch blocks before Docker starts.
+
+Regression evidence: source digest and snapshot validation are exercised by
+every successful and source-mismatch build test.
+
+### A3: executor replacement
+
+Precondition: the attacker changes the host executable or points at a link.
+Success means the supplied program starts before its identity is rejected.
+
+Defense: the operational executor must be a regular non-link file and match the
+plan's SHA-256 digest. The runner then copies it into its private custody
+directory, re-hashes that copy, and launches only the copy. A later replacement
+of the caller's executable path cannot change either rebuild. Operational paths
+never enter the receipt.
+
+Regression evidence: `blocks an executor substitution before process launch`,
+`launches a private executor snapshot immune to later path substitution`.
+
+### A4: artifact smuggling
+
+Precondition: the compiler image is malicious or the translation unit triggers
+unexpected compiler behavior. It creates extra files, a symbolic link, a large
+artifact, or a binary for another architecture. Success means any such output
+is retained as verified.
+
+Defense: each run gets a fresh output directory. The runner accepts exactly the
+declared relative path, rejects links and special files, caps artifact size,
+parses the ELF class/endian/machine header, and copies output into a newly
+created caller directory only after all checks pass.
+
+Regression evidence: `blocks non-reproducible and unexpected build outputs`,
+`blocks a reproducible artifact for the wrong machine target`, `requires a new
+output directory and redacts compiler diagnostics`.
+
+### A5: reproducible but unpinned output
+
+Precondition: a compromised compiler emits the same malicious artifact twice.
+Success means same-toolchain reproducibility is treated as published-artifact or
+independent-rebuild trust.
+
+Defense: the first reproducible build is only `artifact-pin-required` and does
+not include the `native-build` layer. A second plan must carry an externally
+selected `expectedArtifactDigest`. Even a verified native receipt is only input
+to the existing signed rebuild payload; the substrate gate still demands
+caller-owned independent trust roots.
+
+Regression evidence: `requires an artifact pin before claiming native-build
+coverage`, `turns a verified native result into the existing signed rebuild
+payload`.
+
+### A6: diagnostic exfiltration
+
+Precondition: source or compiler emits secrets and absolute paths on stdout or
+stderr. Success means those bytes appear in portable JSON.
+
+Defense: logs are bounded and represented only by byte counts and SHA-256
+digests. Errors use fixed messages and relative schema paths. Source content,
+executor path, source path, artifact directory, stdout, and stderr are absent.
+
+Regression evidence: `requires a new output directory and redacts compiler
+diagnostics` plus the receipt path-redaction assertions in the successful build
+test.
+
+## Resource and isolation contract
+
+The runner fixes `--pull never`, `--platform linux/amd64`, `--network none`,
+`--ipc none`, `--read-only`, `--cap-drop ALL`, `no-new-privileges`, uid/gid
+65534, read-only source, bounded tmpfs, PIDs, memory plus swap, CPU quota, log
+buffer, and wall-clock timeout. These settings reduce container reach; they are
+not a proof against a Docker, kernel, CPU, or compiler exploit.
+
+## Residual work
+
+The next trust layers are intentionally separate contracts:
+
+1. independently governed compiler-image and builder signing roots;
+2. VM/hypervisor isolation and measured launch receipts;
+3. UEFI, Secure Boot, TPM, bootloader, firmware, and microcode measurements;
+4. ISA-specific code generation and bare-metal runtime admission;
+5. physical-device identity, hardware telemetry, and recovery receipts.
+
+Combining those into a broader `command` field would erase the security model.
+Each layer must add a typed target and a verifier that can fail closed.