# probe-algebra — working notes for agents

A Rust workspace (root crate `boundary-spec`) built around one idea: run the code to
derive its spec, freeze the spec into committed files, and let CI fail on any drift.
Almost every artifact here is generated from a declaration and compared byte for byte.

Orientation: `README.md` is the front door, `docs/tour.md` the guided walk,
`docs/discovery.md` the discovery reference, `docs/compile-time.md` the compile-time
edge grammar, `docs/roadmap.md` the build history and what's next, `docs/experience.md`
the authoring program. Read the roadmap before designing anything new.

## The one rule

Never hand-edit a generated artifact. If a lock is stale, regenerate it and commit the
diff — the committed diff is the ratification. A missing lock counts as stale.

| Artifact | Regenerate with |
|---|---|
| `spec/<theory>.spec`, `.system.spec`, `.shape.spec`, `.world.spec`, `.mutation.spec` | `cargo run --example freeze_spec` |
| `spec/shapes.spec` (the law-language catalog) | `cargo run --example freeze_shapes` |
| `spec/gates.spec` and `.github/workflows/ci.yml` (the pipeline is a lock) | `cargo run --example freeze_gates` |
| `spec/qualify.spec` (public-surface census; build fails when stale) | `BLESS_QUALIFY=1 cargo build` |
| `spec/tiers.spec` (the derived tier partition; KERNEL only via `spec/kernel.register`) | `BLESS_TIERS=1 cargo build` |
| member crates' censuses (qualify + tiers) | `BLESS_<CRATE>_QUALIFY=1` / `BLESS_<CRATE>_TIERS=1` (`CREDIT_APP`, `RELAY_APP`, `FIXTURE`) |
| trybuild `.stderr` files (toolchain bumps only) | `TRYBUILD=overwrite` |

`genesis-demo/` and `relay-demo/` are workspace members generated by genesis from
`examples/genesis_demo.rs` / `examples/genesis_relay.rs`. Regenerate rather than edit;
deviations are recorded in their manifests.

## Gates

`cargo run --example gate` runs the every-change gates from the same declaration CI
executes (`discover::gates::GateRegistry`; ci.yml is rendered from it). Individually:
`cargo fmt --all --check`, `cargo clippy --workspace --all-targets --all-features --
-D warnings`, `cargo test --workspace --all-targets`. Always `--workspace` — the root
package alone silently skips the fixtures.

## Mutation testing

- PRs mutate changed lines only; the default branch mutates the diff since the
  `mutants-green` tag; a weekly sweep covers everything, sharded. All through
  `.github/mutants-gate.sh`. Timeouts count as detections, not survivors.
- The root sweep runs only `--lib`, `refusal_drill`, and `fire_drill` — a lock defended
  only in `tests/` is invisible to it. Give every lock a lib-side twin.
- A surviving mutant means a missing probe. For an equivalent mutant, prefer deleting
  the degree of freedom; ratify it in `.cargo/mutants.toml` (by function name, with a
  reason) only when you can't.
- Theories are also mutated in-process on every `cargo test` (`discover::mutation`);
  survivors there are spec degrees of freedom, ratified in `spec/<theory>.mutation.spec`.

## Conventions that bite

- New public items drift the qualify census: re-bless and commit the diff.
- Error messages and lock prose are byte-pinned by tests; changing wording means
  updating the pinned assertions in the same commit.
- The shape catalog is the engine: a new law shape is a new data stanza in
  `ShapeCatalog::inventory()` (slots, canonical terms, template, polarity), never new
  battery code.
- One vocabulary: declared expectations, genesis parsing, and the engine share
  `discover::expect::Expectation` and the catalog's templates. Don't restate a law's
  prose or equation anywhere else.
- `system!` has two arms (compact and full-grammar); both must generate `modules()`,
  `seams()`, `cohesions()`, and `placements()`.
- PRs land by squash merge. (Delete this line if the repo settings ever enforce it.)
- Field reports describe outside projects by what they taught, never by name.
- Prose is yours: match intensity to content. The high register in older git log
  entries and docs is history, not a style guide; don't inherit it by imitation.
- The toolchain is pinned in `discover::gates::TOOLCHAIN`.

## Honest frame

Discovery refutes; it never proves. Grids are bounded and batteries are samples, so a
green law is evidence, not certainty. Reports (distance, cohesion, placement) suggest;
locks gate; a timeout in the sweeps is a detection. Keep those distinctions when adding
anything.

## Open invitation

If you see something the method is missing — a lock it should have, a shape the catalog
cannot say, a friction worth dissolving — say so unprompted. Wrong ideas are cheap; the
roadmap catches the good ones.
