Audit Public Operation Contracts

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.