Ironbank

Ironbank

Ironbank is Capsem's full black-box ledger discipline. Use it for release, VM, network, model, MCP, credential broker, package-manager, doctor, benchmark, and security acceptance work.

Core Rule

Do not look at Rust/product internals to decide expected behavior. Ironbank tests are written from public contracts, CLI help, docs, route responses, generated schemas, hermetic fixture definitions, logs, DB rows, and installed package metadata. If the contract is missing, write the RED test for the missing contract.

Ironbank parity rule

The Ironbank parity rule is that every portable release gate belongs in just test. Local just test rebuilds both artifact families and runs the complete recipe. Binary and profile release CI reuse the same checked-in modules while pulling the unchanged artifact family; green split jobs do not replace those modules. The shared entrypoints include workspace/runtime tests, coverage floors, capsem-doctor, Ironbank acceptance, benchmarks, artifact checks, all web surfaces, and Docker/systemd Linux install plus a real guest-shell proof. Only unavoidable platform boundaries may remain outside, and each must be named with its authoritative final gate.

just test is the strict superset of portable CI work. CI workflows may run a smaller relevant slice, but no portable artifact may be built only in workflow YAML. In particular, VM asset publication uses the same just _build-kernel and just _build-rootfs primitives owned by just test through just _gate-assets; the canonical gate rebuilds every profile for arm64 and x86_64, validates every required artifact and manifest, and boots each rebuilt host-architecture image to a guest-shell marker. Input-contract tests are not a substitute for testing the artifact that was actually built.

The accounting applies to host packages too: macOS-local just test must build the real release-mode .pkg and both release-mode Linux .deb architectures, then execute the production host-SBOM generator over those exact packages. Linux-only Rust branches must run locally in Docker as a non-root user through the same checked-in runner used by Linux CI. Generated files must pass a generate-and-compare idempotence gate; silently refreshing stale outputs is not a green test.

Hardcoded release selection is also unaccounted state. The canonical gate must run the grep-backed selection guard covering current and planned profile names (code, co-work/cowork, terminal, termional, and gui), public channel names, manifest URLs, user-facing request bodies, native postinstall scripts, and both serialized release commands. Defaults may be declared explicitly at API boundaries, but downstream profile/channel routes must carry the selected value and damaged packages must fail closed instead of falling back to stable.

For multi-architecture packages, required applies to the package matching the release host. Cross artifacts are still built and structurally validated, but must not fail early merely because they cannot execute natively on the opposite-architecture runner. Tagged arm64 CI must install and verify its exact package/service even though that hosted runner lacks KVM; x86_64 CI additionally owns the mandatory exact-package guest-shell proof.

An exact gate that routinely approaches the hosted runner's observed lifetime is not release proof. Runtime headroom is part of the ledger: record stage durations, treat repeated same-age termination as a deterministic budget bug, and require the expensive production rail to pass locally before spending another CI run. Parallel work is acceptable only when its hidden workspaces, container tags, outputs, and cleanup are isolated and covered by a test.

Enforce Docker caches through /dev-cache and the common typed registry before concurrent artifact lanes start. The policy owns each cache's description, scope, warm size, maximum size, and prune strategy; acceptance code must not inspect Docker's data root or recreate backend-specific capacity logic.

Required Shape

• Suite home: tests/ironbank/.
• Runner: Python black-box tests through Capsem, capsem-doctor, VM sessions, hermetic local services, UDS routes, HTTP routes, logs, and SQLite ledgers.
• One deterministic stimulus asserts the full path: client result, parsed facts, CEL/security decision, detection/enforcement rows, protocol rows, structured logs, status counters, UDS route, HTTP route, and UI JSON shape.
• Every emitted field is exact-value asserted, typed-invariant asserted, or explicitly marked not applicable.
• Unknown DB/log/route fields fail the test until the field ledger is updated.

Forbidden

• Rust parser/unit proof as an Ironbank gate.
• Public-network dependencies.
• Mocks of the Capsem path.
• Fallback routes.
• Status-code-only replay.
• Row-exists checks.
• skip, skipif, slow, optional markers, or manual OAuth/client dances as release proof.

Package Managers

Installing is not proof. For apt, npm, uv, pip, node, or profile package rails, assert binary presence/version/hash where relevant and run a command that proves the package does its job. Example: zstd must compress and decompress known bytes and match the original.