# CX contributor front door — test

> **GENERATED FILE.** Source: `docs-src/llm/contributor-test.md.tmpl`, the
> Makefile's `TEST_TARGETS` and `DOC_TARGETS`, and the umbrella test files of
> the pinned checkouts, assembled by `scripts/gen_docs/primer_build.cx`. The
> two tables are projections; the procedure is the rules, each citing its
> decision. Edit the template or the Makefile, never this file.

- The corpus is the executable truth: a behaviour is a `[case …]` in a `.cxd`
  file, graded against the binary; a fix lands its failing case first
  (AGENTS.md rule 2, RULED: CFG-1).
- `cx corpus FILE.cxd` grades any corpus file with the binary alone — the
  same PASS/FAIL lines and summary as the in-tree graders (RULED: RS-16).
- Run what your change selects, not everything: `scripts/test_changed.sh
  <base> --dry-run` prints the steps whose inputs your diff touches; the full
  `make test` union is the post-merge run's (RULED: RUN-1, INT-5).
- A step that reads a file the tree derives it from refuses to vouch for an
  empty derivation; a check over the empty set would pass forever
  (RULED: 1350-b).

## 1. Grading the corpus

```console
$ cx corpus conformance/llm/antipatterns.cxd      # one file, this binary, its PASS/FAIL lines and summary
$ cx corpus --quiet deps/cx-core-code/conformance/stdlib/json.cxd
$ make fixtures                                    # every module corpus, sharded, one census line
$ make fixtures FIXTURE_FILES="<file> …"            # just the files your branch touched
```

- A case is judged on `[out-text]`, `[out-multiset]` or `[out-err]` under its
  own `grant=`, `argv=`, `tol=`; a case naming a pack this profile does not
  carry is SKIPPED by name, never graded (`cx corpus --help`).
- A case id in `conformance/code.cxd` uses a prefix registered for its
  `level=` in `scripts/check_code_fixtures.cx`; `check-code-fixtures` grades
  that file alone.
- A new `.cxd` belongs to a shard (`fixture_shards.cxd`) or
  `check-fixture-shard-manifest` refuses it.
- A `ring=1` case is graded at EVERY profile, including the ones without the
  platform packs; read a response's status as `$r@status`.
- A changed fixture that a generated document cites carries its `make docs`
  in the same commit — `docs-check` replays every cited case.

## 2. Choosing the steps — the computed selection

| Situation | What runs pre-merge | Decision |
|---|---|---|
| the diff touches ordinary inputs | `scripts/test_changed.sh <base> --dry-run` → the steps it lists, and the `test-vcx-suite` files it names | RULED: RUN-1 |
| the diff touches the Makefile, `vcx/Makefile`, `scripts/`, `VERSION` or `devbox*` (ESCALATED) | the COMPUTED selection: the diff MINUS those paths as a `--changed-files` list, each selected step as its own row; the escalated union is the post-merge run's, never queued pre-merge | RULED: RUN-4, INT-5 |
| the diff adds or edits a `scripts/*.cx` | `make reader-parity` as an own step (the computed selection strips `scripts/` before it is asked) | RULED: CXF-5 |
| the diff adds a `TEST_TARGETS` step | `make check-selection-manifest`: every step has an input row in `scripts/test_changed.sh` | RULED: RUN-1 |
| the diff touches only documentation | the doc pipeline (`make test-docs`, the steps marked below) is the post-merge run's; your own steps are unchanged | RULED: INT-10 |
| a step fails at the same commit with no code change | a flaky test: a known one is retried once; a new one gets a flaky-test issue — never a loosened bound or a skipped case | RULED: DG-1 |

A failed post-merge run names EVERY failed step (`make test` runs its storm with
`-k`), so the fix for a failed head carries every class the log names
(RULED: RUN-2).

## 3. The umbrellas — where a test function goes

Test files, not functions, are the compile cost: every `*_test.v` links the
whole module graph. A new test is a function in the umbrella that owns the
area; the roster is `scripts/consolidation/<area>.files` and
`scripts/consolidate_tests.sh absorb <area>` folds a stray file in.

<sub>Generated by `scripts/gen_docs/contributor_facts.cx` from the `*_umbrella_test.v` files in the front door and its pinned checkouts (16 rows) — do not edit here: change the source, run `make docs`.</sub>

| umbrella (path in its repository) | repository |
|---|---|
| `vcx/tests/async_conc_umbrella_test.v` | `cx-core-code` |
| `vcx/tests/canonical_umbrella_test.v` | `cx-core-code` |
| `vcx/tests/cli_umbrella_test.v` | `cx-core-code` |
| `vcx/tests/code_units_umbrella_test.v` | `cx-core-code` |
| `vcx/tests/diagram_umbrella_test.v` | `cx-core-code` |
| `vcx/tests/lint_lsp_umbrella_test.v` | `cx-core-code` |
| `vcx/tests/parser_units_umbrella_test.v` | `cx-core-code` |
| `vcx/tests/table_stream_umbrella_test.v` | `cx-core-code` |
| `vcx/code/code_module_umbrella_test.v` | `cx-core-code` |
| `vcx/tests/http_umbrella_test.v` | `cx-platform-net` |
| `vcx/tests/net_umbrella_test.v` | `cx-platform-net` |
| `vcx/tests/real_services_umbrella_test.v` | `cx-platform-net` |
| `vcx/tests/store_core_umbrella_test.v` | `cx-platform-store` |
| `vcx/tests/store_remote_umbrella_test.v` | `cx-platform-store` |
| `vcx/tests/fabric_umbrella_test.v` | `cx-platform-fabric` |
| `vcx/tests/xap_umbrella_test.v` | `cx-platform-xap` |

A Ring-0 change (lexer, parser, evaluator, emitter, loader) runs, as its own
steps, every umbrella that reads a module it touched
(`grep -l '<module>' deps/*/vcx/tests/*_umbrella_test.v`) and those modules'
`vcx/cx/*_test.v` (RULED: VERIFY-2); a code change runs its umbrellas the same
way, with `make check-effect-alignment`.

## 4. The census trio — a corpus file that gains or loses cases

A branch that adds or removes cases in a top-level `conformance/*.cxd` moves
three baselines together, deliberately, naming each id:

| Baseline | Step | What moves it |
|---|---|---|
| the parser's full-corpus census | `vcx/tests/parser_units_umbrella_test.v` (its `cxparse_full_corpus_diff` section) | every new `in-cx` input — bump its pinned count, naming the ids |
| the headline rebless scope | `vcx/tests/cxparse_headline_rebless_scan_test.v` | regenerate with `CX_REBLESS_SCAN_WRITE=1`, commit the scope file |
| the Tier-2 address baseline | `make address-baseline-gate` | an extraction or a case removal: `make address-baseline-capture`, the ids named in the commit |

The ids are named because a count that moves silently hides a case that was
lost with one that was added (RULED: RS-12).

## 5. The two runners

| Runner | Runs | Holds |
|---|---|---|
| pre-merge — the branch's own | its builds, lints, graders, umbrellas and docs checks, under its own `CX_BUILD_SLOT` through `scripts/build_slot.cx`; load-sensitive steps (memory gauges, bench, real-socket tests) one at a time on the shared slot | the branch's own tree: every own step passed once on the final tree before merge (RULED: INT-8, OL-3) |
| post-merge — the loop on each new head | `make test-changed BASE=<last passed head>`, escalating to the full union on an infra change; the full union daily on an idle runner | the integration branch: a failed run gets a fix, never a revert of the gate (RULED: RUN-1, RUN-3) |

Read a status directly, never through an inner shell that `devbox run` wraps
— that shape answers 0 for a program that failed; `check-exit-status-probe`
holds the line (AGENTS.md, "Exit statuses"; RULED: CFG-1).

## 6. The step roster

The union `make test` runs, in order. A step marked in the doc pipeline also
runs in `make test-docs` (RULED: INT-10); the third column is where to start
reading what the step checks.

<sub>Generated by `scripts/gen_docs/contributor_facts.cx` from the Makefile's `TEST_TARGETS` (in order), `DOC_TARGETS`, the targets `docs-src/flow/docs.flow.cx` names, and each step's own rule (136 rows) — do not edit here: change the source, run `make docs`.</sub>

| # | step | in the doc pipeline | the first program its recipe names |
|---|---|---|---|
| 1 | `docs-voice-check` | yes, in the docs flow | `scripts/gen_site/docs_voice_check.cx` |
| 2 | `docs-vocabulary-check` |  | `scripts/gen_site/docs_vocabulary_check.cx` |
| 3 | `nav-shape-check` |  | `scripts/gen_guide/nav_shape_check.cx` |
| 4 | `ring-svg-check` | yes, in the docs flow | `scripts/gen_site/ring_svg.cx` |
| 5 | `check-no-ai-attribution` |  | `scripts/check_no_ai_attribution.cx` |
| 6 | `check-public-history-replace` |  | `scripts/public_history_replace_selftest.cx` |
| 7 | `check-vcache-soundness` |  | `scripts/vcache_soundness_memo.cx` |
| 8 | `check-vcache-soundness-selftest` |  | `scripts/vcache_soundness_memo_selftest.cx` |
| 9 | `check-build-failure-classifier` |  | `scripts/classify_v_build_failure.cx` |
| 10 | `test-vcx-timing` |  | `v test deps/cx-core-code/vcx/timing/` |
| 11 | `check-conformance-coverage` |  | `scripts/check_conformance_coverage.cx` |
| 12 | `check-shim-archives` |  | `scripts/check_archive_alignment.cx` |
| 13 | `abi-c-test` |  | — |
| 14 | `check-v-fork` |  | `scripts/check_v_fork_patches.cx` |
| 15 | `check-portable-links` |  | `scripts/check_portable_links.cx` |
| 16 | `check-release-asset-links` |  | `scripts/release_asset_links_gate.cx` |
| 17 | `check-serial-retry-rosters` |  | — |
| 18 | `check-fixture-shard-manifest` |  | `scripts/check_fixture_shard_manifest.cx` |
| 19 | `check-consolidation-manifests` |  | `scripts/consolidate_tests.sh` |
| 20 | `check-bare-head-calls` |  | `scripts/bare_head_calls_selftest.cx` |
| 21 | `test-vcx-suite` |  | `scripts/fixtures_census.cx` |
| 22 | `test-vcx-code` |  | — |
| 23 | `test-vcx-cmd` |  | `v test vcx/cmd/` |
| 24 | `test-vcx-cx` |  | `v test deps/cx-core-data/vcx/fixtures/` |
| 25 | `test-vcx-conform` |  | `make -C deps/cx-core-code/vcx conform-all` |
| 26 | `test-vcx-columnar` |  | `make -C deps/cx-core-code/vcx arrow-shim` |
| 27 | `test-vcx-sqlite` |  | `v test deps/cx-platform-store/vcx/store/store_sqlite_test.v` |
| 28 | `check-prod-build` |  | `make -C deps/cx-core-code/vcx check-prod` |
| 29 | `check-no-legacy-try` |  | `scripts/check_no_legacy_try.cx` |
| 30 | `check-pipefail-pipes` |  | `scripts/pipefail_pipe_gate.cx` |
| 31 | `check-exec-redirect` |  | `scripts/exec_redirect_gate.cx` |
| 32 | `check-exit-status-probe` |  | `scripts/exit_status_probe_gate.cx` |
| 33 | `check-build-slot` |  | `scripts/build_slot_selftest.cx` |
| 34 | `check-bench-isolation` |  | `scripts/bench_isolation_selftest.cx` |
| 35 | `check-no-infix-range` |  | `scripts/check_no_infix_range.cx` |
| 36 | `check-no-cxl-token` |  | `scripts/check_no_cxl_token.cx` |
| 37 | `listener-bind-gate` |  | `scripts/listener_bind_gate.cx` |
| 38 | `check-no-consumer-terms` |  | `scripts/check_no_consumer_terms.cx` |
| 39 | `secrets-scan` |  | `scripts/secrets_scan.cx` |
| 40 | `check-version-consistency` | yes | `scripts/check_version_consistency.cx` |
| 41 | `check-effect-alignment` |  | `v test deps/cx-core-code/vcx/tests/code_units_umbrella_test.v` |
| 42 | `check-null-absence-conflation` |  | `scripts/check_null_absence_conflation.cx` |
| 43 | `check-docs-tier1-guardrail` |  | `scripts/check_docs_tier1_guardrail.cx` |
| 44 | `check-no-adr-citations` |  | `scripts/check_no_adr_citations.cx` |
| 45 | `check-no-stub-impl` |  | `scripts/check_no_stub_impl.cx` |
| 46 | `check-completions-drift` |  | `scripts/check_completions_drift.cx` |
| 47 | `check-editor-surface-parity` |  | `scripts/check_editor_surface_parity.cx` |
| 48 | `guide-check` | yes, in the docs flow | `scripts/gen_guide/stdlib_docs_check.cx` |
| 49 | `guide-snippets-check` |  | `scripts/gen_guide/snippet_check.cx` |
| 50 | `guide-render-gate` |  | `scripts/gen_guide/theme_check.cx` |
| 51 | `site-check` | yes, in the docs flow | `scripts/gen_site/site_assemble.cx` |
| 52 | `directive-docs-check` |  | `scripts/gen_guide/directive_docs_check.cx` |
| 53 | `verify-doc-blocks` | yes, in the docs flow | `tools/verify-doc-blocks.sh` |
| 54 | `verify-doc-links` | yes, in the docs flow | `tools/verify-doc-links.sh` |
| 55 | `verify-examples` |  | `tools/verify-examples.sh` |
| 56 | `verify-playground-examples` |  | `scripts/gen_guide/playground/gen_examples.cx` |
| 57 | `docs-check` | yes, in the docs flow | `scripts/gen_docs/primer_build.cx` |
| 58 | `primer-platform-check` | yes, in the docs flow | `scripts/gen_docs/primer_platform.cx` |
| 59 | `ring-import-gate` |  | `scripts/ring_import_gate.cx` |
| 60 | `gates-manifest-gate` |  | `scripts/gates_manifest_gate.cx` |
| 61 | `advisory-audit` |  | `scripts/advisory_audit_check.cx` |
| 62 | `property-gate` |  | `scripts/property_gate.cx` |
| 63 | `spec-invariant-gate` |  | `scripts/spec_invariants.cx` |
| 64 | `ring-tag-gate` |  | `scripts/ring_query.cx` |
| 65 | `cxer-registry-gate` |  | `scripts/cxer_registry_report.cx` |
| 66 | `diagnostics-census-check` |  | `scripts/diagnostics_census_check.cx` |
| 67 | `spec-freeze-gate` | yes | `scripts/spec_freeze_gate.cx` |
| 68 | `test-extraction-gate` |  | — |
| 69 | `abi-gc-gate` |  | — |
| 70 | `libcx-abi-gate` |  | `tools/libcx-abi-gate.sh` |
| 71 | `test-profile-gate` |  | `make -C deps/cx-core-code/vcx test-profile-gate` |
| 72 | `check-code-spec-consistency` |  | `scripts/check_code_spec_consistency.cx` |
| 73 | `check-code-fixtures` |  | `scripts/check_code_fixtures.cx` |
| 74 | `reader-parity` |  | `v test vcx/tests/reader_parity_test.v` |
| 75 | `stdlib-catalog-gate` |  | `scripts/stdlib_catalog_gate.cx` |
| 76 | `placement-gate` |  | `scripts/placement_gate.cx` |
| 77 | `repos-allocation-gate` |  | `scripts/repos_allocation_gate.cx` |
| 78 | `product-import-gate` |  | `scripts/product_import_gate.cx` |
| 79 | `test-deps-pins` |  | `scripts/check_deps_pins_fixtures.cx` |
| 80 | `check-deps-bootstrap-token` |  | `scripts/deps_bootstrap.sh` |
| 81 | `test-bundle-sources` |  | `scripts/check_bundle_sources_fixtures.cx` |
| 82 | `test-docs-fragment` |  | `scripts/check_docs_fragment_fixtures.cx` |
| 83 | `test-migrate-namespace` |  | `scripts/check_migrate_namespace_fixtures.cx` |
| 84 | `store-session-dep-gate` |  | `scripts/store_session_dep_gate.cx` |
| 85 | `flow-vocabulary-gate` |  | `deps/cx-platform-flow/scripts/flow_vocabulary_gate.cx` |
| 86 | `flow-dogfood-gate` |  | `deps/cx-platform-flow/scripts/flow_dogfood_gate.cx` |
| 87 | `docs-flow-gate` | yes | `scripts/ci_flow_gate.cx` |
| 88 | `release-flow-gate` |  | `scripts/ci_flow_gate.cx` |
| 89 | `test-flow-umbrella` |  | — |
| 90 | `address-baseline-gate` |  | `v run deps/cx-core-code/vcx/tests/runners/address_baseline/address_baseline.v` |
| 91 | `tools-export-gate` |  | — |
| 92 | `test-code-diagram` |  | `scripts/check_code_diagram_fixtures.cx` |
| 93 | `test-playground-mermaid` |  | `scripts/test_playground_mermaid.mjs` |
| 94 | `test-playground-nav` |  | `scripts/test_playground_nav.mjs` |
| 95 | `test-playground-search` |  | `scripts/test_playground_search.mjs` |
| 96 | `test-playground-readings` |  | `scripts/gen_guide/playground/readings_check.cx` |
| 97 | `test-oriel` |  | `deps/cx-platform-ux/scripts/oriel_real.sh` |
| 98 | `test-agent-real` |  | — |
| 99 | `test-connector-real` |  | — |
| 100 | `test-xap-umbrella` |  | — |
| 101 | `test-fabric-umbrella` |  | — |
| 102 | `test-mail-real` |  | — |
| 103 | `test-net-real` |  | — |
| 104 | `test-web-component-offline` |  | `scripts/test_web_component_offline.cx` |
| 105 | `bench-code-pattern-compile` |  | — |
| 106 | `test-db-real` |  | — |
| 107 | `test-sso-interop` |  | `deps/cx-platform-sso/scripts/sso_interop.sh` |
| 108 | `test-xpath-parity-cx` |  | `scripts/check_xpath_parity_fixtures.cx` |
| 109 | `corpus-audit` |  | `scripts/corpus_audit.cx` |
| 110 | `repr-guard` |  | `bench/repr/run.cx` |
| 111 | `repr-guard-selftest` |  | `scripts/repr_guard_selftest.cx` |
| 112 | `check-inmodule-test-roster` |  | — |
| 113 | `check-build-input-roster` |  | `make -C deps/cx-core-code/vcx check-build-input-roster` |
| 114 | `check-sync-cmd-split` |  | `scripts/sync_cmd_split_selftest.cx` |
| 115 | `check-gitconfig-home` |  | `scripts/gitconfig_home_selftest.cx` |
| 116 | `check-selection-manifest` |  | `scripts/check_selection_manifest.cx` |
| 117 | `fmt-sweep-gate` |  | `scripts/fmt_corpus_sweep.cx` |
| 118 | `test-playground-wasm-traps` |  | `scripts/test_playground_wasm_traps.mjs` |
| 119 | `test-site-phone-width` |  | `scripts/test_site_phone_width.mjs` |
| 120 | `test-playground-primer` |  | `scripts/test_playground_primer.mjs` |
| 121 | `site-live-check` |  | `scripts/site_live_check.cx` |
| 122 | `site-links-selftest` |  | `scripts/gen_site/check_external_links.cx` |
| 123 | `issue-label-gate` |  | `scripts/issue_label_gate.cx` |
| 124 | `conformance-suites` |  | `scripts/conformance_suites.cx` |
| 125 | `ledger-index-check` | yes | `scripts/ledger_index.cx` |
| 126 | `ledger-edit-map-check` | yes | `scripts/ledger_edit_map_check.cx` |
| 127 | `check-profile-gate-selection` |  | `scripts/profile_gate_selection_selftest.cx` |
| 128 | `check-verification-budget` |  | `scripts/check_verification_budget.cx` |
| 129 | `check-verification-budget-selftest` |  | `scripts/verification_budget_selftest.cx` |
| 130 | `check-perf-settle-selftest` |  | `scripts/perf_settle_selftest.cx` |
| 131 | `premerge-record` |  | `scripts/premerge_record.cx` |
| 132 | `check-storm-keep-going` |  | `scripts/storm_keep_going_selftest.cx` |
| 133 | `check-verification-timings` |  | `scripts/verification_timings_selftest.cx` |
| 134 | `check-bench-runners-compile` |  | `bench/probe` |
| 135 | `check-flow-doc-lines` |  | `scripts/check_flow_doc_lines_selftest.cx` |
| 136 | `perf-pair` |  | `scripts/compare_bench.cx` |