Verify

CLAUDE.md "END TO END TESTING": HTTP 200 is not proof. A runtime that says it's live may still be unable to answer real requests. Verification means proving the package's primary surface actually works.

Three verification depths

Depth	Command	What it proves
1. Bootstrap	mx run . --check	The factory loaded and started without throwing
2. Bus reachability	hivecast invoke <mount> <op> '{}'	An actor at the expected mount answers a known op
3. End-to-end	Browser flow / Playwright / prove-*.ts	The full user-visible surface works

1. Bootstrap-only with --check

mx run . --env dev --check

Source: packages/mx-cli/src/commands/run.ts:451-464. The runner:

1. Loads the manifest, environment, and factory.
2. Calls the factory.
3. Immediately calls shutdownAll.
4. Prints a "Validated bootstrap" line (or JSON if --json).

This catches "the factory throws on import" or "the factory fails to mount its actors". It does not catch ops-handler bugs, config errors that surface only on the first request, or wire-format issues with peers.

2. Bus reachability with hivecast invoke

hivecast invoke system.runtimes runtimes.list '{"limit":5}' \
  --home /tmp/matrix-home

Source: packages/host-service/src/cli.ts:254-265. The CLI constructs an envelope and sends it to the named mount. A response proves:

• The mount is registered.
• The actor is processing inbox messages.
• The op is recognized and returns within the default 5s timeout.

Use this to verify domain ops (e.g. hivecast invoke chat conversation.list '{}') once the runtime is up.

3. End-to-end smoke

For browser packages, browse the gateway:

curl -I http://127.0.0.1:3100/apps/<appName>/
# 200 is necessary but not sufficient

Then run a real browser. CLAUDE.md "feedback_end_to_end_testing": log in as a user, navigate to the app, watch the JS console, and confirm there are no NATS permission errors. HTTP 200 alone has historically been a misleading signal because the bootstrap can silently fail to connect.

For full reproducibility, use the existing proof scripts:

node projects/matrix-3/scripts/prove-fresh-device-link.ts \
  --route-key codex-proof-$(date -u +%Y%m%d-%H%M) \
  --cloud https://hivecast.ai

These scripts exercise specific lifecycle pathways (device link, package up/down) and exit non-zero on any deviation. They are the canonical "did this change break a known good flow?" check.

Verification before commit

CLAUDE.md Rule 8 lists the steps that must precede a commit to master:

1. The change is internally complete.
2. The relevant package tests pass locally.
3. You have verified the change does what it should — actual behavior check, not just "compiles". For UI changes that means loading the page; for actor changes that means an invoke against a running runtime.
4. git fetch --all first, then push that exact verified HEAD.

The mapping to verification depths:

• For build-only changes: depth 1 (mx run . --check).
• For new/changed actor ops: depth 2 (hivecast invoke).
• For UI or end-to-end behavior: depth 3 (browser/Playwright proof script).

Common verification mistakes

Mistake	Why it lies
Running --check instead of full bootstrap	The factory may run fine but its actors might not handle real traffic
Reading /healthz and stopping there	/healthz only confirms the Host is up; runtimes may be down
Running mx invoke from a stale shell whose env points to the wrong Host home	You'll talk to the wrong Host; pass --home <host-home> explicitly
Forgetting to rebuild before verifying	Tests use dist/; stale builds give false signals
Treating a green Playwright run with no NATS load as proof	Some bugs surface only when actors collaborate; pair with hivecast invoke

See also

• Running → Health
• Running → Logs
• Running → hivecast up
• Local Development → Test
• Deployment Profiles → Verification

Source: projects/matrix-3/packages/mx-cli/src/commands/run.ts implements --check; packages/host-service/src/cli.ts:254-265 implements invoke; proof scripts live under projects/matrix-3/scripts/.