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.

Preflight the Docker daemon capacity required by concurrent artifact lanes.

Low-space failures must be detected before launch, after safe unused-cache

reclamation, with architecture-specific logs that are fully flushed before the

gate reports failure.

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.