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.