Audit Public Operation Contracts

Determine whether an operation is a bounded, truthful, composable mathematical instrument. Record the revision, operation IDs, inspected scope, and whether the request includes implementation. Audit-only work does not authorize repository or external mutations.

Design before implementation

Before adding a public operation or library abstraction, apply the vocabulary audit to the proposed boundary. Keep concise evidence in the existing issue or PR, reusing what is already established rather than creating a mandatory review form:

• State the exact mathematical postcondition and essential hypotheses.
• Name the nearest existing operation or composition and the specific result it cannot supply. Give a smallest separating example and a nearby case the proposal deliberately does not solve.
• Walk one input through its canonical result to an intended consumer. Decide only relevant questions about source identity, multiplicity, ordering, empty or degenerate carriers, finite versus infinite solution sets, and one witness versus exhaustive output.
• Choose the appropriate disposition: public operation, native-only function, shared representation, private helper, regression fixture, or caller reasoning. A composition or no-gap finding is a successful outcome, not a reason to manufacture another operation.

A justified boundary has one stable mathematical result, not a whole-proof API, assurance wrapper, workflow state, or compatibility metadata. Keep the existing composition and scale-first obligations below; a separating example motivates investigation but does not establish an admitted implementation.

Trace the contract

Treat request representation, canonical values, semantic admission, kernel, trusted result construction, and downstream consumers as one execution path. Inspect schemas, declarations, examples, and MCP errors when public projection is in scope. The implementation alone does not define the advertised contract.

Use the applicable sections of the operation library. For public admission, consult the admission contract; for a backend boundary, consult the backend contract. Record applicable evidence in the requested audit or existing issue/PR description; do not create a universal review form.

Follow shared interpretations through their consumers

When changing field/domain recognition, shape resolution, codec parsing or canonical conversion, identify the semantic owner and trace the actual callers that rely on its interpretation. Do not infer every possible producer-consumer pair from annotations. Similar-looking code may have different mathematical meanings: share an implementation when semantics are genuinely identical, or state and test a legitimate contextual difference instead of forcing reuse.

Run the same owner-local fixture through the relevant recognizer, resolver and consumer, with a useful accepted case and an invalid case that stays rejected. Cover alternate supported spellings, aliases/qualified forms, nesting and empty/zero/singleton cases only where they belong to that contract. For static checks, include binding and scope: unrelated guards, reassignment, destructured names and shadowing must not falsely establish the required property.

For example, the three-level annotation fixture in tests/tooling/test_before_validator_containers.py checks container recognition, nested shape resolution and the projection consumer together, including shallow projection, unrelated-guard and destructured-rebinding controls. Keep this at the owner boundary; add no duplicate runtime validation layer, generic ledger, transport abstraction or catalog-wide generated matrix.

Probe the plausible failures

Use small deterministic reproductions to test the suspected mechanism:

• accepted requests beyond the backend domain or admitted work/growth bounds;
• useful structured requests rejected by an ambient-size or expansion-based limit;
• repeated admission or computation during validation and result construction;
• lost units, multiplicities, axes, parents, witnesses, or reconstruction data;
• independently supplied claims accepted without establishing the needed property;
• incompatible producer/consumer values, including empty or singular cases;
• implicit changes of ring, field, parent, or axes; and
• advertised semantics that disagree with the typed result or kernel.

Check serialized producer-consumer composition when relevant. Defining-invariant proof belongs in tests or an admitted caller-claim operation, not replay during ordinary result construction. Use current official backend documentation and the pinned implementation for consequential backend claims.

For a representation, performance, admission-limit, or backend-selection investigation, read scale and backends. Audit what the contract unnecessarily excludes as well as what it unsafely accepts. Preserve the motivating request and exact invariant; a fast but weaker result is not a scale improvement.

Check a justified transformation

For a changed mathematical owner, choose a relevant invariant or equivariance and derive its expected effect before writing the test. Relabelling may preserve a scalar invariant while transporting indexed witnesses; row permutations must preserve the intended set or multiset semantics. Translation preserves planar squared circumradii, while scaling by nonzero c multiplies them by c². Translation preserves repeated differences; an invertible linear coordinate map transports their values and preserves their multiplicities. These are examples, not a requirement that every operation support every transformation. State when the transformation changes the problem or leaves the admitted domain.

Use the actual source and an independent defining-identity check, alongside the relation between transformed outputs. Include a negative control for an invalid invariance assumption or lost source indices/multiplicities. For a transformation or encoding operation, check that source identities, hypotheses and the intended relation survive the map: correct solver execution on the encoded problem does not establish that the mathematical model was valid.

Keep these tests with the affected owner. Do not introduce a catalog-wide matrix, generic assurance fields, or repeated expensive verification during result construction. A concrete example is tests/math/combinatorics/additive/test_difference_profile_equivariance.py: affine coordinate changes and source permutations are checked against exact source subtraction, with stale-index and noninjective-map controls.

Establish the finding and finish

After proving a defect, inspect the owner, shared helper, and its callers for the same mechanism, keeping adjacent candidates confirmed, disproved, or untested. Choose a repair at the invariant's owning boundary. Preserve a regression that fails on the base for the intended reason when feasible, using an independent oracle, defining identity, or adversarial composition rather than source-text assertions. Select validation through the contributor guide's owning lanes.

Report the public claim, reproduction and observed result, violated invariant, affected scope, smallest repair, and meaningful proof gaps. If implementation was authorized, complete the focused repair and affected checks before handing back; existing authorization persists, but local investigation does not grant permission for external writes.