@celilo/e2e 0.7.13 → 0.7.15

package/config/dns/knot-namecheap.conf

@@ -10,8 +10,8 @@ zone:
     file: "/config/celilo.computer.zone"
     storage: "/var/lib/knot"
 
-  - domain: "lunacycle.net"
-    file: "/config/lunacycle.net.zone"
+  - domain: "example.net"
+    file: "/config/example.net.zone"
     storage: "/var/lib/knot"
 
   - domain: "park-your-domain.com"

package/config/dns/net.zone

@@ -7,5 +7,5 @@ $TTL 86400
 
 net.                    IN NS   tld-dns.lab.
 
-lunacycle               IN NS   ns1.lunacycle.net.
-ns1.lunacycle.net.      IN A    100.64.0.55
+example                 IN NS   ns1.example.net.
+ns1.example.net.      IN A    100.64.0.55

package/config/dns/{lunacycle.net.zone → templates/example.net.zone}

@@ -1,7 +1,7 @@
-$ORIGIN lunacycle.net.
+$ORIGIN example.net.
 $TTL 300
 
-@ IN SOA ns1.lunacycle.net. admin.lunacycle.net. (
+@ IN SOA ns1.example.net. admin.example.net. (
     2024020108 300 60 604800 300
 )
 
@@ -10,7 +10,7 @@ $TTL 300
 ; private IPs are unreachable from outside. All public-facing names
 ; resolve to the firewall's external IP (100.100.0.100), which DNATs
 ; inbound to the right internal host.
-@       IN NS   ns1.lunacycle.net.
+@       IN NS   ns1.example.net.
 ns1     IN A    100.64.0.55
 @       IN A    100.100.0.100
 www     IN A    100.100.0.100

package/config/resolver/unbound.conf

@@ -34,11 +34,11 @@ stub-zone:
     stub-addr: 100.64.0.55
 
 stub-zone:
-    name: "lunacycle.net."
+    name: "example.net."
     stub-addr: 100.64.0.55
 
 # celilo.computer hosts the website + install.sh (served by the website-sim).
-# Without this stub it falls through to the real internet (71.36.115.155), so the
+# Without this stub it falls through to the real internet (203.0.113.11), so the
 # website-sim's ACME challenge can't be validated in-topology and the bake's
 # `curl https://celilo.computer/install.sh` never sees a cert. Covers
 # www.celilo.computer too. (ISS-0063)

package/config/routing/observer-setup.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+# Observer vantage setup (ISS-0117).
+#
+# Installs the routing profile that makes this container a FAITHFUL vantage — the
+# load-bearing part of the framework. A vantage's correctness is its routing table:
+# an internalDevice must reach a fronted service only via the firewall natIp, never a
+# segmented-zone container IP directly. Driven by env from the compose generator:
+#   OBSERVER_GATEWAY   - default route (the home router for internalDevice, the zone
+#                        firewall for dmz/app/secure, fw-ext for publicInternet)
+#   OBSERVER_INTERZONE - "1" to add the management-style explicit inter-zone routes
+#                        (the all-VLAN trap). "0" for every faithful consumer vantage.
+#   OBSERVER_RESOLVERS - space-separated nameservers for /etc/resolv.conf, in order
+set -u
+
+GATEWAY="${OBSERVER_GATEWAY:?OBSERVER_GATEWAY is required}"
+INTERZONE="${OBSERVER_INTERZONE:-0}"
+RESOLVERS="${OBSERVER_RESOLVERS:-100.100.0.1}"
+
+echo "Observer starting: gateway=${GATEWAY} interzone=${INTERZONE} resolvers='${RESOLVERS}'"
+
+# --- Default route ---
+# Docker seeds a default via the network's own gateway; replace it with the gateway a
+# real device at this location would use.
+ip route del default 2>/dev/null || true
+ip route add default via "${GATEWAY}"
+
+# --- Inter-zone routes (the management trap; only when explicitly requested) ---
+# A real consumer vantage NEVER has these — that is the whole point. Present only so a
+# `management`-style all-VLAN box can be modelled deliberately.
+if [ "${INTERZONE}" = "1" ]; then
+  ip route add 10.0.10.0/24 via 192.168.0.254 2>/dev/null || true  # dmz via fw-main
+  ip route add 10.0.20.0/24 via 192.168.0.254 2>/dev/null || true  # app via fw-main
+  ip route add 10.0.30.0/24 via 192.168.0.254 2>/dev/null || true  # secure via fw-main
+fi
+
+# --- Resolver ---
+: > /etc/resolv.conf
+for ns in ${RESOLVERS}; do
+  echo "nameserver ${ns}" >> /etc/resolv.conf
+done
+
+# --- Pebble runtime ACME root CA ---
+# Pebble mints a fresh root each startup, so the build-time CA can't verify certs Caddy
+# obtained at runtime. Fetch the live root so curl/openssl can validate real chains —
+# the no-self-signed / CA-provenance assertions depend on a correct trust store.
+echo "Fetching Pebble ACME root CA..."
+for _ in $(seq 1 30); do
+  if curl -sk https://100.64.0.100:15000/roots/0 -o /usr/local/share/ca-certificates/pebble-acme-root.crt 2>/dev/null; then
+    if [ -s /usr/local/share/ca-certificates/pebble-acme-root.crt ]; then
+      update-ca-certificates 2>/dev/null
+      echo "Pebble ACME root CA installed"
+      break
+    fi
+  fi
+  sleep 2
+done
+
+echo "Observer ready: $(hostname)"
+ip route
+sleep infinity

package/config/routing/resolver-internal-routes.sh

@@ -9,9 +9,9 @@ CADDY_IP="${CADDY_IP:-10.0.10.10}"
 # DOMAINS: comma-separated list of e2e test domains that should be
 # split-horizon redirected to caddy. Default covers the canonical
 # (iamtheinternet.org) plus the cross-domain test's second domain
-# (lunacycle.net). Tests can override via DEFAULT_GATEWAY/DOMAINS env
+# (example.net). Tests can override via DEFAULT_GATEWAY/DOMAINS env
 # vars in docker-compose.
-DOMAINS="${DOMAINS:-iamtheinternet.org,lunacycle.net}"
+DOMAINS="${DOMAINS:-iamtheinternet.org,example.net}"
 
 # Routing — reach comcast-resolver (100.100.0.1) via fw-main or fw-isp.
 # DEFAULT_GATEWAY is set by docker-compose from the topology config.

package/docker/Dockerfile.observer

@@ -0,0 +1,26 @@
+# Observer — a passive vantage-point spy (ISS-0117).
+#
+# Carries the full probe toolbox (dig, curl, openssl, nc, ping, ip) so a single image
+# can be injected at any network location and assert resolve/reach/TLS from that seat.
+# It runs NO services and deploys NO modules — it never perturbs the system under test.
+# Its faithfulness as a vantage comes from the routing profile installed at startup
+# (see config/routing/observer-setup.sh), driven by the OBSERVER_* env the compose
+# generator sets per vantage.
+FROM ubuntu:22.04
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+RUN apt-get update && apt-get install -y \
+    dnsutils \
+    curl \
+    openssl \
+    netcat-openbsd \
+    iputils-ping \
+    iproute2 \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY config/routing/observer-setup.sh /startup.sh
+RUN chmod +x /startup.sh
+
+CMD ["/startup.sh"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/e2e",
-  "version": "0.7.13",
+  "version": "0.7.15",
   "description": "E2E test infrastructure for Celilo-deployed applications. Provides a simulated internet with DNS hierarchy, ACME server, firewalls, and target machines in Docker.",
   "type": "module",
   "main": "./src/index.ts",
@@ -37,7 +37,7 @@
   ],
   "dependencies": {
     "@celilo/cli-display": "^0.1.9",
-    "@celilo/event-bus": "^0.1.5",
+    "@celilo/event-bus": "^0.1.7",
     "yaml": "^2.8.0",
     "zod": "^3.24.1"
   },

package/src/cli/command-registry.ts

@@ -23,15 +23,21 @@ export interface FlagDef {
 export const COMMANDS: CommandDef[] = [
   {
     name: 'run',
-    description: 'Run e2e tests — pass a module path or pattern, or --all-modules',
+    description: 'Run e2e tests — pass a module path or pattern, or --all / --all-modules',
     flags: [
+      { name: '--all', description: 'Run the full regression: every module suite + top-level e2e/tests/' },
+      { name: '--all-modules', description: 'Run e2e tests for all modules with e2e/ directories' },
       { name: '--keep', description: 'Keep network running after tests' },
       { name: '--reuse', description: 'Reuse existing network if running' },
       { name: '--live', description: 'Use live (non-simulated) internet' },
       { name: '--published', description: 'Use published .netapp packages' },
-      { name: '--all-modules', description: 'Run e2e tests for all modules with e2e/ directories' },
     ],
   },
+  {
+    name: 'list',
+    description: 'List every discoverable Docker e2e test (module + top-level)',
+    flags: [{ name: '--paths', description: 'Also show each test file path' }],
+  },
   {
     name: 'up',
     description: 'Start interactive test network',
@@ -93,7 +99,7 @@ export const COMMANDS: CommandDef[] = [
 
 export const UP_PRESETS = ['--caddy', '--full-stack', '--infrastructure'];
 
-export const RUN_FLAGS = ['--keep', '--reuse', '--live', '--published', '--all-modules'];
+export const RUN_FLAGS = ['--all', '--all-modules', '--keep', '--reuse', '--live', '--published'];
 
 export const DOWN_FLAGS = ['--keep', '--all'];
 

package/src/cli/completion.ts

@@ -56,6 +56,11 @@ export function getCompletions(words: string[], current: number): string[] {
     );
   }
 
+  if (command === 'list' && currentIndex >= 1) {
+    const used = new Set(args.slice(1));
+    return filterSuggestions(['--paths'].filter((f) => !used.has(f)), args[currentIndex] || '');
+  }
+
   if (command === 'completion' && currentIndex === 1) {
     return filterSuggestions(['zsh', 'bash'], args[1] || '');
   }
@@ -108,13 +113,17 @@ _cele2e() {
       case $line[1] in
         run)
           _arguments \\
+            '--all[Run the full regression: every module suite + top-level e2e/tests/]' \\
+            '--all-modules[Run e2e tests for all modules with e2e/ directories]' \\
             '--keep[Keep network running after tests]' \\
             '--reuse[Reuse existing network if running]' \\
             '--live[Use live (non-simulated) internet]' \\
             '--published[Use published .netapp packages]' \\
-            '--all-modules[Run e2e tests for all modules with e2e/ directories]' \\
             '*::test name or module path:_cele2e_run_args'
           ;;
+        list)
+          _arguments '--paths[Also show each test file path]'
+          ;;
         up)
           _arguments '1: :_cele2e_up_presets'
           ;;
@@ -137,7 +146,7 @@ _cele2e() {
         completion)
           _arguments '1: :_cele2e_completion_shells'
           ;;
-        status|load|clear-timing)
+        status|load|clear-timing|list)
           ;;
       esac
       ;;
@@ -147,6 +156,7 @@ _cele2e() {
 _cele2e_commands() {
   local commands=(
     'run:Run e2e tests (pattern filters by test file name)'
+    'list:List every discoverable Docker e2e test (module + top-level)'
     'up:Start interactive test network'
     'down:Tear down running network'
     'build-infra:Rebuild @celilo/e2e Docker images and standard module .netapps'

package/src/cli/index.ts

@@ -16,7 +16,7 @@
  */
 
 import { spawnSync } from 'node:child_process';
-import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, rmSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { parse as parseYaml } from 'yaml';
 import { runBuild } from './build';
@@ -55,6 +55,53 @@ function detectTestDir(): { stateDir: string; testsPath: string } {
   return { stateDir: cwd, testsPath: join(cwd, 'tests') };
 }
 
+/**
+ * Resolve the repo root to scan for the full e2e suite (`run --all` / `list`).
+ *
+ * The workspace `./cele2e` wrapper cd's into packages/e2e before exec'ing, so
+ * process.cwd() points at the e2e package — useless for module discovery. The
+ * wrapper exports E2E_INVOKE_CWD with the operator's real PWD; we walk up from
+ * there (or process.cwd() as a fallback) to the nearest ancestor that has a
+ * `modules/` directory, which is the infra repo root. This is what makes the
+ * full-regression command immune to the wrapper's internal cd (ISS-0013).
+ */
+function resolveSuiteRoot(): string {
+  const start = resolve(process.env.E2E_INVOKE_CWD || process.cwd());
+  let dir = start;
+  for (;;) {
+    if (existsSync(join(dir, 'modules'))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return start;
+}
+
+/**
+ * Enumerate every discoverable Docker e2e test (all module suites + the repo's
+ * top-level e2e/tests/) as `{ name, file }`, sorted, with module tests first.
+ */
+function discoverSuiteTests(suiteRoot: string): { name: string; file: string; group: string }[] {
+  const out: { name: string; file: string; group: string }[] = [];
+  for (const moduleDir of findAllModules(suiteRoot)) {
+    const tp = join(moduleDir, 'e2e');
+    const testsDir = existsSync(join(moduleDir, 'manifest.yml'))
+      ? resolve(moduleDir, readManifestTestsDir(join(moduleDir, 'manifest.yml')) ?? 'e2e')
+      : tp;
+    if (!existsSync(testsDir)) continue;
+    for (const f of readdirSync(testsDir).filter((f) => f.endsWith('.test.ts')).sort()) {
+      out.push({ name: f.replace(/\.test\.ts$/, ''), file: join(testsDir, f), group: basename(moduleDir) });
+    }
+  }
+  const topLevel = join(suiteRoot, 'e2e', 'tests');
+  if (existsSync(topLevel)) {
+    for (const f of readdirSync(topLevel).filter((f) => f.endsWith('.test.ts')).sort()) {
+      out.push({ name: f.replace(/\.test\.ts$/, ''), file: join(topLevel, f), group: '(top-level)' });
+    }
+  }
+  return out;
+}
+
 function runScript(script: string, args: string[], env?: Record<string, string>): never {
   const result = spawnSync(join(BIN_DIR, script), args, {
     stdio: 'inherit',
@@ -72,6 +119,8 @@ Usage:
 
 Commands:
   run [pattern]     Run e2e tests (pattern filters by test file name)
+  run --all         Run the FULL regression: every module suite + top-level e2e/tests/
+  list              List every discoverable Docker e2e test (module + top-level)
   up [preset]       Start interactive test network
   down              Tear down running network
   build-infra [dirs...] Rebuild Docker images and package all modules as .netapps
@@ -84,6 +133,8 @@ Commands:
   completion <shell> Generate shell completion script (zsh|bash)
 
 Options for \`run\`:
+  --all             Run every module suite AND the top-level e2e/tests/ (full regression)
+  --all-modules     Run every module suite (no top-level tests)
   --keep            Keep network running after tests
   --reuse           Reuse existing network if running
   --live            Use live (non-simulated) internet
@@ -103,6 +154,8 @@ Options for \`build-infra\`:
   --skip-modules    Skip .netapp packaging (only rebuild Docker images)
 
 Examples:
+  cele2e run --all                  # FULL regression: every module suite + top-level e2e/tests/
+  cele2e list                       # enumerate every discoverable Docker e2e test
   cele2e run                        # in a module: run its tests; outside: run all modules' tests
   cele2e run deploy                 # run tests matching "deploy"
   cele2e run caddy-direct-internet  # from modules/, finds the matching module automatically
@@ -130,6 +183,34 @@ if (command === '--get-completions') {
 
 switch (command) {
   case 'run': {
+    // Full-suite modes (ISS-0013). `--all` runs every module suite AND the
+    // repo's top-level e2e/tests/ in one invocation; `--all-modules` runs just
+    // the module suites. Both resolve the repo root via resolveSuiteRoot() so
+    // they work through the `./cele2e` wrapper's cd into packages/e2e.
+    if (args.includes('--all') || args.includes('--all-modules')) {
+      const wantTopLevel = args.includes('--all');
+      const suiteRoot = resolveSuiteRoot();
+      const allModules = findAllModules(suiteRoot);
+      const env: Record<string, string> = {
+        E2E_TEST_DIR: join(suiteRoot, 'e2e'),
+        E2E_MODULE_DIRS: allModules.join('\n'),
+      };
+      const topLevel = join(suiteRoot, 'e2e', 'tests');
+      if (wantTopLevel && existsSync(topLevel)) {
+        env.E2E_TOP_LEVEL_TESTS = topLevel;
+      }
+      if (allModules.length === 0 && !env.E2E_TOP_LEVEL_TESTS) {
+        console.error(`No e2e tests found under ${suiteRoot}`);
+        console.error('Run from the infra repo root (or set E2E_INVOKE_CWD to it).');
+        process.exit(1);
+      }
+      runScript(
+        'e2e-run',
+        args.filter((a) => a !== '--all' && a !== '--all-modules'),
+        env,
+      );
+    }
+
     // Check if any non-flag arg is a module path (has manifest.yml)
     const modulePath = args
       .filter((a) => !a.startsWith('--'))
@@ -180,6 +261,29 @@ switch (command) {
     break;
   }
 
+  case 'list': {
+    // Enumerate every discoverable Docker e2e test (module + top-level) so the
+    // suite is inspectable without reading runner.ts (ISS-0013).
+    const suiteRoot = resolveSuiteRoot();
+    const tests = discoverSuiteTests(suiteRoot);
+    if (tests.length === 0) {
+      console.error(`No e2e tests found under ${suiteRoot}`);
+      console.error('Run from the infra repo root (or set E2E_INVOKE_CWD to it).');
+      process.exit(1);
+    }
+    const wantPaths = args.includes('--paths');
+    let lastGroup = '';
+    for (const t of tests) {
+      if (t.group !== lastGroup) {
+        console.log(`\n${t.group}:`);
+        lastGroup = t.group;
+      }
+      console.log(wantPaths ? `  ${t.name}  ${t.file}` : `  ${t.name}`);
+    }
+    console.log(`\n${tests.length} tests. Run all: cele2e run --all`);
+    process.exit(0);
+  }
+
   case 'up':
     runScript('e2e-up', args);
 

package/src/container-manager.ts

@@ -16,7 +16,7 @@ import type {
   ProxyOptions,
   SocksProxyHandle,
 } from './types';
-import { CeliloCommandError, ZONE_GATEWAYS, ZONE_SUBNETS } from './types';
+import { CeliloCommandError, internalNatIp, ZONE_GATEWAYS, ZONE_SUBNETS } from './types';
 
 /** Package root — where docker/, config/, simulators/ live */
 const PACKAGE_ROOT = join(__dirname, '..');
@@ -137,7 +137,7 @@ const SHARED_CONTAINERS = new Set([
  * set (useful for --keep debugging).
  */
 async function scrubDnsZones(): Promise<void> {
-  const zones = ['iamtheinternet.org', 'lunacycle.net'];
+  const zones = ['iamtheinternet.org', 'example.net'];
   const composeDir = PACKAGE_ROOT;
 
   for (const zone of zones) {
@@ -675,7 +675,7 @@ export async function startNetwork(config: NetworkConfig): Promise<NetworkHandle
     async deployFirewall(opts = {}): Promise<void> {
       const zones = opts.zones ?? ['dmz', 'app', 'secure'];
       const firewallIp = ZONE_GATEWAYS.internal; // fw-main on internal
-      const natIp = opts.natIp ?? '192.168.0.253';
+      const natIp = opts.natIp ?? internalNatIp();
       const providedNetworks = zones.map((zone) => ({
         zone,
         subnet: ZONE_SUBNETS[zone],
@@ -950,7 +950,7 @@ export function reconnectNetwork(projectName: string): NetworkHandle {
     async deployFirewall(opts = {}): Promise<void> {
       const zones = opts.zones ?? ['dmz', 'app', 'secure'];
       const firewallIp = ZONE_GATEWAYS.internal; // fw-main on internal
-      const natIp = opts.natIp ?? '192.168.0.253';
+      const natIp = opts.natIp ?? internalNatIp();
       const providedNetworks = zones.map((zone) => ({
         zone,
         subnet: ZONE_SUBNETS[zone],

package/src/docker-compose-generator.ts

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { stringify } from 'yaml';
+import { normalizeObservers, observerEnv, observerPlacement } from './observer';
 import { SIMULATOR_IPS } from './simulator-ips';
 import type { MachineSpec, NetworkConfig, TopologyPreset } from './types';
 import { ZONE_GATEWAYS } from './types';
@@ -216,7 +217,7 @@ export function generateSharedInfraYaml(): string {
     // `test123` still applies to any domain not listed.
     environment: {
       DDNS_PASSWORDS:
-        '{"iamtheinternet.org":"test123","celilo.computer":"test456","lunacycle.net":"test789"}',
+        '{"iamtheinternet.org":"test123","celilo.computer":"test456","example.net":"test789"}',
     },
     volumes: [
       './config/dns/knot-namecheap.conf:/config/knot.conf:ro',
@@ -227,7 +228,7 @@ export function generateSharedInfraYaml(): string {
       // namecheap-startup.sh for the full rationale).
       './config/dns/iamtheinternet.org.zone:/seed/iamtheinternet.org.zone:ro',
       './config/dns/celilo.computer.zone:/seed/celilo.computer.zone:ro',
-      './config/dns/lunacycle.net.zone:/seed/lunacycle.net.zone:ro',
+      './config/dns/example.net.zone:/seed/example.net.zone:ro',
       './config/dns/park-your-domain.com.zone:/seed/park-your-domain.com.zone:ro',
     ],
   });
@@ -504,6 +505,20 @@ export function generateTestComposeYaml(config: NetworkConfig, celiloRoot?: stri
     });
   }
 
+  // --- Observer vantages (passive spies; ISS-0117) ---
+  // Each is the SAME image at a different network location with a routing profile that
+  // mirrors a real device there — that routing profile is what makes it a faithful seat
+  // to assert from, rather than the all-VLAN management trap.
+  for (const spec of normalizeObservers(config.observers ?? [])) {
+    const p = observerPlacement(spec.vantage);
+    services[p.service] = baseService({
+      build: { context: '.', dockerfile: 'docker/Dockerfile.observer' },
+      networks: { [p.network]: { ipv4_address: p.ip } },
+      cap_add: ['NET_ADMIN'],
+      environment: observerEnv(p),
+    });
+  }
+
   const compose = { networks, volumes, services };
   return stringify(compose, { lineWidth: 120 });
 }
@@ -619,7 +634,7 @@ export function generateComposeYaml(config: NetworkConfig, celiloRoot = '..'): s
     // `test123` still applies to any domain not listed.
     environment: {
       DDNS_PASSWORDS:
-        '{"iamtheinternet.org":"test123","celilo.computer":"test456","lunacycle.net":"test789"}',
+        '{"iamtheinternet.org":"test123","celilo.computer":"test456","example.net":"test789"}',
     },
     volumes: [
       './config/dns/knot-namecheap.conf:/config/knot.conf:ro',
@@ -630,7 +645,7 @@ export function generateComposeYaml(config: NetworkConfig, celiloRoot = '..'): s
       // namecheap-startup.sh for the full rationale).
       './config/dns/iamtheinternet.org.zone:/seed/iamtheinternet.org.zone:ro',
       './config/dns/celilo.computer.zone:/seed/celilo.computer.zone:ro',
-      './config/dns/lunacycle.net.zone:/seed/lunacycle.net.zone:ro',
+      './config/dns/example.net.zone:/seed/example.net.zone:ro',
       './config/dns/park-your-domain.com.zone:/seed/park-your-domain.com.zone:ro',
     ],
   });

package/src/index.ts

@@ -37,6 +37,8 @@ export type {
   ExecResult,
   MachineSpec,
   Zone,
+  Vantage,
+  ObserverSpec,
   TopologyPreset,
   ProxyOptions,
   SocksProxyHandle,
@@ -44,7 +46,32 @@ export type {
   BrowserHandle,
   BrowserLauncher,
 } from './types';
-export { CeliloCommandError, ZONE_GATEWAYS, ZONE_SUBNETS } from './types';
+export {
+  CeliloCommandError,
+  greenwaveRouterIp,
+  internalNatIp,
+  internalResolverIp,
+  publicResolverIp,
+  ZONE_GATEWAYS,
+  ZONE_SUBNETS,
+} from './types';
+
+// Vantage-point network assertions (ISS-0117)
+export { VantageProbe, VantageAssertionError } from './vantage';
+export type {
+  ProbeTransport,
+  ResolveMethod,
+  ResolveResult,
+  HttpsResult,
+  CertInfo,
+  ResolutionInspection,
+  ExpectedZone,
+} from './vantage';
+export { createObserverTransport, vantageContainer, OBSERVER_PLACEMENTS } from './observer';
+export { classifyIp, isSegmentedZoneIp, isPublicLeakSafe } from './zone-classifier';
+export type { ZoneClass } from './zone-classifier';
+export { assertFrontedServicePositives, assertFrontedHostnames } from './vantage-helpers';
+export type { FrontedServiceExpectation } from './vantage-helpers';
 
 // Common fixtures
 export {

package/src/network-builder.ts

@@ -2,7 +2,7 @@ import { execSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { startNetwork } from './container-manager';
-import type { NetworkConfig, NetworkHandle, TopologyPreset } from './types';
+import type { NetworkConfig, NetworkHandle, TopologyPreset, Vantage } from './types';
 
 /**
  * If a mounted path looks like a celilo module (has scripts/package.json),
@@ -39,6 +39,7 @@ export class NetworkBuilder {
     secureMachines: [],
     internalMachines: [],
     dhcpClient: false,
+    observers: [],
     domain: 'iamtheinternet.org',
     ddnsPassword: 'test123',
     verifyRouting: process.env.VERIFY_ROUTING === '1',
@@ -104,6 +105,22 @@ export class NetworkBuilder {
     return this;
   }
 
+  /**
+   * Inject one or more observer vantages (ISS-0117) — passive spies carrying the probe
+   * toolbox, each placed at its vantage's network location with a routing profile that
+   * mirrors a real device there. Drive them via `createObserverTransport(handle)` +
+   * `VantageProbe`. `management` is not injectable (that vantage reuses the real
+   * management container).
+   *
+   *   network().dmz({ caddy: '10.0.10.10' }).observe('internalDevice', 'publicInternet')
+   */
+  observe(...vantages: Vantage[]): this {
+    for (const vantage of vantages) {
+      (this.config.observers ??= []).push({ vantage });
+    }
+    return this;
+  }
+
   domain(domain: string): this {
     this.config.domain = domain;
     return this;