fix: verify isolated docker integration and refine system health replay

Author: Gabriel Jang

README.md

@@ -148,13 +148,14 @@ Local setup:
 cp infra/.env.example infra/.env
 chmod 0600 infra/.env
 # Replace placeholder values in infra/.env without committing the file.
+# If 8000/5173 are already occupied, set FABOPS_API_PORT/FABOPS_WEB_PORT to free loopback ports.
 
 docker compose --env-file infra/.env -f infra/docker-compose.yml config --quiet
-docker compose --env-file infra/.env -f infra/docker-compose.yml up -d --build
-curl -fsS http://127.0.0.1:8000/health/ready
-docker compose --env-file infra/.env -f infra/docker-compose.yml down
+uv run python -m evaluation.m6_integration --output /tmp/fabops-m6-container-integration.json --check
 ```
 
+The M6 integration verifier reads only the non-secret `FABOPS_API_PORT` setting needed for its loopback readiness probe and defaults to `8000` for backward compatibility. It never copies `infra/.env` contents into evidence. Canonical verification also injects isolated free `FABOPS_E2E_API_PORT` / `FABOPS_E2E_WEB_PORT` values into Playwright so unrelated listeners on the normal development ports are not reused or stopped. Direct `npm run test:e2e` behavior remains unchanged and still defaults to `8000/5173` unless those E2E variables are provided.
+
 ## Canonical verification
 
 The project has one release verification entry point:

evaluation/canonical_verify.py

@@ -6,6 +6,7 @@
 import platform
 import shlex
 import shutil
+import socket
 import subprocess
 import tarfile
 import tempfile
@@ -40,17 +41,21 @@ def _run(
     *,
     cwd: Path = ROOT,
     extra_paths: list[Path] | None = None,
+    env_overrides: dict[str, str] | None = None,
     timeout: int = 900,
 ) -> dict[str, Any]:
     started = time.perf_counter()
+    environment = os.environ.copy()
+    if env_overrides:
+        environment.update(env_overrides)
     completed = subprocess.run(
         arguments,
         cwd=cwd,
         capture_output=True,
         text=True,
         timeout=timeout,
         check=False,
-        env=os.environ.copy(),
+        env=environment,
     )
     duration = time.perf_counter() - started
     output = "\n".join([completed.stdout, completed.stderr]).strip()
@@ -66,6 +71,48 @@ def _run(
     }
 
 
+def _allocate_loopback_port(excluded: set[int]) -> int:
+    for _ in range(32):
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe:
+            probe.bind(("127.0.0.1", 0))
+            port = int(probe.getsockname()[1])
+        if port not in excluded:
+            return port
+    raise RuntimeError("unable to allocate an isolated loopback port")
+
+
+def _select_isolated_e2e_ports() -> dict[str, int]:
+    excluded = {8000, 5173}
+    api_port = _allocate_loopback_port(excluded)
+    excluded.add(api_port)
+    web_port = _allocate_loopback_port(excluded)
+    return {"api_port": api_port, "web_port": web_port}
+
+
+def _run_frontend_e2e(npm: str) -> tuple[dict[str, Any], dict[str, int]]:
+    ports: dict[str, int] = {}
+    step: dict[str, Any] = {}
+    for attempt in range(3):
+        ports = _select_isolated_e2e_ports()
+        step = _run(
+            "frontend-e2e",
+            [npm, "run", "test:e2e"],
+            cwd=ROOT / "systems/web",
+            env_overrides={
+                "FABOPS_E2E_API_PORT": str(ports["api_port"]),
+                "FABOPS_E2E_WEB_PORT": str(ports["web_port"]),
+            },
+            timeout=300,
+        )
+        if step["exit_code"] == 0:
+            return step, ports
+        output = step.get("output_tail", "").lower()
+        port_conflict = "address already in use" in output or "eaddrinuse" in output
+        if not port_conflict or attempt == 2:
+            return step, ports
+    return step, ports
+
+
 def _clean_setup(uv: str, npm: str, temp_root: Path) -> dict[str, Any]:
     archive = temp_root / "source.tar"
     snapshot = temp_root / "snapshot"
@@ -133,14 +180,19 @@ def verify(output: Path) -> dict[str, Any]:
             _run("frontend-component-tests", [npm, "run", "test"], cwd=ROOT / "systems/web"),
             _run("frontend-build", [npm, "run", "build"], cwd=ROOT / "systems/web"),
             _run("frontend-audit", [npm, "audit", "--audit-level=high"], cwd=ROOT / "systems/web"),
-            _run("frontend-e2e", [npm, "run", "test:e2e"], cwd=ROOT / "systems/web", timeout=300),
-            _run(
-                "architecture-fitness",
-                [uv, "run", "python", "-m", "evaluation.m6_fitness", "--output-dir", str(temp_fitness)],
-                extra_paths=[temp_dir],
-            ),
-            _run("release-manifest-consistency", [uv, "run", "python", "-m", "evaluation.release_manifest", "--check"]),
         ]
+        e2e_step, e2e_ports = _run_frontend_e2e(npm)
+        steps.extend(
+            [
+                e2e_step,
+                _run(
+                    "architecture-fitness",
+                    [uv, "run", "python", "-m", "evaluation.m6_fitness", "--output-dir", str(temp_fitness)],
+                    extra_paths=[temp_dir],
+                ),
+                _run("release-manifest-consistency", [uv, "run", "python", "-m", "evaluation.release_manifest", "--check"]),
+            ]
+        )
 
         docker_info = _run("docker-info", [docker, "info"], timeout=30)
         docker_available = docker_info["exit_code"] == 0
@@ -197,6 +249,7 @@ def verify(output: Path) -> dict[str, Any]:
             "expected_evaluation_hash": expected_evaluation_hash,
             "evaluation_identity_passed": evaluation_identity_passed,
             "steps": steps,
+            "e2e_ports": e2e_ports,
             "docker_integration": docker_status,
             "clean_setup": clean_setup,
             "policy": {

evaluation/m6_integration.py

@@ -12,6 +12,33 @@
 
 INTEGRATION_VERSION = "m6-container-integration-v1"
 COMPOSE = ["docker", "compose", "--env-file", "infra/.env", "-f", "infra/docker-compose.yml"]
+ENV_FILE = Path("infra/.env")
+DEFAULT_API_PORT = 8000
+
+
+def _validate_port(raw_value: str, *, source: str) -> int:
+    try:
+        port = int(raw_value)
+    except ValueError as exc:
+        raise ValueError(f"{source} must be an integer in range 1-65535") from exc
+    if not 1 <= port <= 65535:
+        raise ValueError(f"{source} must be an integer in range 1-65535")
+    return port
+
+
+def resolve_api_port(env_file: Path = ENV_FILE, *, explicit_port: str | None = None) -> int:
+    if explicit_port is not None:
+        return _validate_port(explicit_port, source="--api-port")
+    if not env_file.exists():
+        return DEFAULT_API_PORT
+    for raw_line in env_file.read_text(encoding="utf-8").splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        if key.strip() == "FABOPS_API_PORT":
+            return _validate_port(value.strip(), source="FABOPS_API_PORT")
+    return DEFAULT_API_PORT
 
 
 def _run(arguments: list[str], *, timeout: int = 300) -> dict[str, Any]:
@@ -27,18 +54,19 @@ def _run(arguments: list[str], *, timeout: int = 300) -> dict[str, Any]:
     }
 
 
-def _read_health(timeout_seconds: float = 60.0) -> dict[str, Any] | None:
+def _read_health(host: str, port: int, timeout_seconds: float = 60.0) -> dict[str, Any] | None:
     deadline = time.monotonic() + timeout_seconds
+    health_url = f"http://{host}:{port}/health/ready"
     while time.monotonic() < deadline:
         try:
-            with urllib.request.urlopen("http://127.0.0.1:8000/health/ready", timeout=3) as response:
+            with urllib.request.urlopen(health_url, timeout=3) as response:
                 return json.load(response)
         except (OSError, urllib.error.URLError, json.JSONDecodeError):
             time.sleep(1.0)
     return None
 
 
-def generate(output: Path, *, keep_up: bool = False) -> dict[str, Any]:
+def generate(output: Path, *, keep_up: bool = False, api_port_override: str | None = None) -> dict[str, Any]:
     generated_at = datetime.now(timezone.utc).isoformat()
     commands: list[dict[str, Any]] = []
     docker_info = _run(["docker", "info"], timeout=30)
@@ -68,6 +96,55 @@ def generate(output: Path, *, keep_up: bool = False) -> dict[str, Any]:
         output.write_text(json.dumps(result, indent=2, sort_keys=True) + "\n", encoding="utf-8")
         return result
 
+    if not ENV_FILE.exists():
+        result = {
+            "schema_version": INTEGRATION_VERSION,
+            "generated_at": generated_at,
+            "status": "unverified",
+            "reason": "Local server-only infra/.env unavailable; container-backed integration was not executed",
+            "compose_config_verified": False,
+            "postgres_runtime_verified": False,
+            "redpanda_runtime_verified": False,
+            "neo4j_runtime_verified": False,
+            "container_integration_verified": False,
+            "api_restart_verified": False,
+            "docker_daemon_available": True,
+            "api_port": DEFAULT_API_PORT,
+            "commands": [{"command": "docker info", "exit_code": docker_info["exit_code"]}],
+            "reproduction_commands": [
+                "cp infra/.env.example infra/.env",
+                "chmod 0600 infra/.env",
+                "docker compose --env-file infra/.env -f infra/docker-compose.yml config --quiet",
+            ],
+        }
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(json.dumps(result, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+        return result
+
+    try:
+        api_port = resolve_api_port(ENV_FILE, explicit_port=api_port_override)
+    except ValueError:
+        result = {
+            "schema_version": INTEGRATION_VERSION,
+            "generated_at": generated_at,
+            "status": "unverified",
+            "reason": "Invalid integration API port configuration; expected an integer in range 1-65535",
+            "compose_config_verified": False,
+            "postgres_runtime_verified": False,
+            "redpanda_runtime_verified": False,
+            "neo4j_runtime_verified": False,
+            "container_integration_verified": False,
+            "api_restart_verified": False,
+            "docker_daemon_available": True,
+            "commands": [{"command": "docker info", "exit_code": docker_info["exit_code"]}],
+            "reproduction_commands": [
+                "docker compose --env-file infra/.env -f infra/docker-compose.yml config --quiet",
+            ],
+        }
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(json.dumps(result, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+        return result
+
     compose_config = _run([*COMPOSE, "config", "--quiet"], timeout=30)
     commands.append({key: value for key, value in compose_config.items() if key not in {"stdout_tail", "stderr_tail"}})
     compose_config_verified = compose_config["exit_code"] == 0
@@ -84,6 +161,7 @@ def generate(output: Path, *, keep_up: bool = False) -> dict[str, Any]:
             "container_integration_verified": False,
             "api_restart_verified": False,
             "docker_daemon_available": True,
+            "api_port": api_port,
             "commands": commands,
             "reproduction_commands": [compose_config["command"]],
         }
@@ -99,7 +177,7 @@ def generate(output: Path, *, keep_up: bool = False) -> dict[str, Any]:
     restart: dict[str, Any] = {"exit_code": 1, "command": "not executed", "duration_seconds": 0.0}
     try:
         if up["exit_code"] == 0:
-            health = _read_health()
+            health = _read_health("127.0.0.1", api_port)
             integration_test = _run(
                 [
                     *COMPOSE,
@@ -120,7 +198,7 @@ def generate(output: Path, *, keep_up: bool = False) -> dict[str, Any]:
             restart = _run([*COMPOSE, "restart", "api"], timeout=60)
             commands.append({key: value for key, value in restart.items() if key not in {"stdout_tail", "stderr_tail"}})
             if restart["exit_code"] == 0:
-                restart_health = _read_health()
+                restart_health = _read_health("127.0.0.1", api_port)
     finally:
         if not keep_up:
             down = _run([*COMPOSE, "down"], timeout=120)
@@ -149,6 +227,7 @@ def generate(output: Path, *, keep_up: bool = False) -> dict[str, Any]:
         "status": "verified" if container_verified else "degraded",
         "reason": None if container_verified else "one or more container-backed runtime checks failed",
         "docker_daemon_available": True,
+        "api_port": api_port,
         "compose_config_verified": compose_config_verified,
         "postgres_runtime_verified": postgres_verified,
         "redpanda_runtime_verified": redpanda_verified,
@@ -181,9 +260,10 @@ def main() -> None:
     parser = argparse.ArgumentParser(description="Verify the isolated M6 Docker Compose integration stack.")
     parser.add_argument("--output", type=Path, default=Path("evidence/m6/integration-summary.json"))
     parser.add_argument("--keep-up", action="store_true")
+    parser.add_argument("--api-port", help="Override the loopback API port used for readiness probes.")
     parser.add_argument("--check", action="store_true")
     args = parser.parse_args()
-    result = generate(args.output, keep_up=args.keep_up)
+    result = generate(args.output, keep_up=args.keep_up, api_port_override=args.api_port)
     if args.check and result["docker_daemon_available"] and not result["container_integration_verified"]:
         raise SystemExit("M6 container integration verification failed")
 

evidence/m6/container-integration-20260823T233451Z-local-arm64.json

@@ -0,0 +1,44 @@
+{
+  "schema_version": "m6-container-integration-evidence-v1",
+  "generated_at": "2026-08-23T23:34:51.108261+00:00",
+  "verification_source_git_sha": "6d02cdf628cfd61d685f078b8a2c15b6857c0bcf",
+  "platform": {
+    "machine": "arm64",
+    "runtime": "Docker Desktop",
+    "docker_architecture": "aarch64"
+  },
+  "loopback_ports": {
+    "api": 18090,
+    "web": 15190,
+    "conflict_avoidance": "Existing unrelated default-port listener was preserved; isolated FabOps loopback ports were used instead."
+  },
+  "status": "verified",
+  "compose_project": "fabops-decision-lab-m6",
+  "compose_config_verified": true,
+  "postgres_runtime_verified": true,
+  "redpanda_runtime_verified": true,
+  "neo4j_runtime_verified": true,
+  "neo4j_memory_limit": "768m",
+  "container_integration_verified": true,
+  "container_pytest": {
+    "exit_code": 0,
+    "result": "4 passed"
+  },
+  "api_restart_verified": true,
+  "actual_equipment_control": false,
+  "duration_seconds": 79.253,
+  "cleanup": {
+    "compose_down_completed": true,
+    "volumes_removed": false
+  },
+  "reproduction_commands": [
+    "docker compose --env-file infra/.env -f infra/docker-compose.yml config --quiet",
+    "uv run python -m evaluation.m6_integration --output /tmp/fabops-m6-container-integration-final.json --check",
+    "docker compose --env-file infra/.env -f infra/docker-compose.yml down"
+  ],
+  "sanitization": {
+    "env_contents_included": false,
+    "credentials_included": false,
+    "credential_bearing_dsns_included": false
+  }
+}

systems/web/src/App.test.tsx

@@ -155,9 +155,20 @@ describe("FabOps workbench", () => {
     expect(await screen.findByRole("heading", {name: "Event-backed decision trace"})).toBeInTheDocument();
     expect(screen.getByLabelText("Replay scrubber")).toHaveValue("0");
     expect(screen.getByText("process.measurement.recorded.v1")).toBeInTheDocument();
+    const timeline = screen.getByRole("list", {name: "Case replay event timeline"});
+    const inspector = screen.getByRole("article", {name: "Selected replay event"});
+    const metadata = screen.getByRole("region", {name: "Selected source event metadata"});
+    const payload = screen.getByRole("region", {name: "Recorded payload"});
+    expect(timeline.parentElement).toHaveClass("replay-trace-layout");
+    expect(inspector).toContainElement(metadata);
+    expect(inspector).toContainElement(payload);
+    expect(metadata).toHaveTextContent("local-event-adapter");
+    expect(payload).toHaveTextContent("Recorded payload");
     fireEvent.click(screen.getByRole("button", {name: "Next"}));
     expect(screen.getByRole("heading", {name: "case.detected"})).toBeInTheDocument();
     expect(screen.getByText("decision-audit")).toBeInTheDocument();
+    expect(metadata).toHaveTextContent("decision-audit");
+    expect(payload).not.toHaveTextContent('"sensor_name": "rf_power"');
   });
 });
 

systems/web/src/screens.tsx

@@ -763,17 +763,19 @@ export function ReplayOperations({replay, trace = null}: {replay: ReplayResponse
             <span>{item.phase.replaceAll("_", " ")}</span><strong>{item.event_type.replaceAll(".v1", "")}</strong><small>{item.event_time ? item.event_time.slice(11, 19) : `#${item.sequence} order`}</small>
           </button>
         </li>)}</ol>
-        <article className="replay-event-inspector">
+        <article className="replay-event-inspector" aria-label="Selected replay event">
           {replayItem ? <>
-            <div className="replay-event-inspector__title"><span>{replayItem.kind.replaceAll("_", " ")}</span><h3>{replayItem.event_type}</h3><small>{replayItem.event_time ?? "No persisted wall-clock timestamp"}</small></div>
-            <dl>
-              <div><dt>Phase</dt><dd>{replayItem.phase}</dd></div>
-              <div><dt>Source</dt><dd>{replayItem.source}</dd></div>
-              <div><dt>Time semantics</dt><dd>{replayItem.time_semantics.replaceAll("_", " ")}</dd></div>
-              <div><dt>Delivery</dt><dd>{replayItem.delivery_status ?? "not applicable"}</dd></div>
-              <div><dt>Event ID</dt><dd>{replayItem.event_id ?? "not an authoritative source event"}</dd></div>
-            </dl>
-            <div className="replay-payload"><span>Recorded payload</span><pre>{JSON.stringify(replayItem.payload, null, 2)}</pre></div>
+            <section className="replay-event-metadata" aria-label="Selected source event metadata">
+              <div className="replay-event-inspector__title"><span>{replayItem.kind.replaceAll("_", " ")}</span><h3>{replayItem.event_type}</h3><small>{replayItem.event_time ?? "No persisted wall-clock timestamp"}</small></div>
+              <dl>
+                <div><dt>Phase</dt><dd>{replayItem.phase}</dd></div>
+                <div><dt>Source</dt><dd>{replayItem.source}</dd></div>
+                <div><dt>Time semantics</dt><dd>{replayItem.time_semantics.replaceAll("_", " ")}</dd></div>
+                <div><dt>Delivery</dt><dd>{replayItem.delivery_status ?? "not applicable"}</dd></div>
+                <div><dt>Event ID</dt><dd>{replayItem.event_id ?? "not an authoritative source event"}</dd></div>
+              </dl>
+            </section>
+            <section className="replay-payload" aria-label="Recorded payload"><span>Recorded payload</span><pre>{JSON.stringify(replayItem.payload, null, 2)}</pre></section>
           </> : <p>No replay item is available for the selected case.</p>}
         </article>
       </div>