gnomonlearn
Docs/RFC-0013 test contract proposal

RFC-0013 test contract proposal

Versioned draft snapshot

RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.

Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.

This is a trace and gap record from the pinned draft specification. It does not establish proof or implementation conformance.

Status: owner decision pending. Owners: language/compiler and developer experience. Nothing is deployed; no persisted test syntax needs migration for the first release.

Source conflict

RFC-0008 §6.9 and §8.12 define a test with ordered given, when, and expect blocks. when contains an actor attempts statement; expect contains allowed or denied and an optional reason. The extracted grammar/gnomon.ebnf and RFC-0008 Lean evidence repeat that form.

RFC-0013 §4 and §5 instead require exactly one given, when, and then block. Its when invokes exactly one declared action with an actor argument, and then contains Boolean constraint expressions. It also permits an optional mock block for external I/O. Its M01301–M01303 diagnostics and Lean statements assume that form. Under the current RFC-0008 grammar, every RFC-0013 then example is invalid, and an RFC-0008 expect example violates RFC-0013’s required structure. mock has no RFC-0008 grammar production.

There is a second semantic conflict. RFC-0008 §6.10 says action has no actor or authorization logic; those belong to procedure (§6.25). RFC-0013 §5.3 requires a principal kind on an action invocation and says the action’s policy rules run as at runtime. RFC-0008’s actor attempts transition example is an authorization test; RFC-0013’s action-only form cannot express that behavior as currently defined. RFC-0013’s companion Q&A says negative-path assertion syntax is absent, although RFC-0008 already has expect { denied }.

An exact-code search of the extracted framework found no executable Gnomon parser, harness, or diagnostic emitter for test-decl or M013xx. Its matches were copied spec and Lean derivation material. That is absence of a local implementation, not proof about external consumers.

Use a single test declaration with ordered given, when, and then blocks, as RFC-0013 proposes, because it can assert post-state and report specific failed expressions. Make the invocation target explicit: action for mutation behavior or procedure for an authorization boundary. An actor is required for a procedure invocation and must not be attributed to the action itself. Specify an explicit Boolean result or failure assertion for negative-path procedure tests; do not infer denial from an unchanged graph. Keep mock optional only with a precise grammar production and a no-real-I/O rule. This is a proposed contract, not an approved edit to either RFC.

The smaller alternative is to retain RFC-0008’s given/when/expect form as canonical, rewrite RFC-0013’s execution and diagnostics to it, and defer post-state assertions and mocks to a later language revision. That would discard much of RFC-0013’s current test model.

Acceptance after owner choice

  1. Align RFC-0008 §6.9/§8.12, RFC-0013 §§4–9, their companion Q&A, and the action/procedure distinction; remove examples that the chosen grammar cannot parse.
  2. Update grammar/gnomon.ebnf from the authored grammar, then add positive and negative fixtures for block order, invocation target, actor scope, Boolean assertions, denial, and optional mocks.
  3. Align both Lean catalogs, M013xx diagnostics, generated references, and claim/domain projection facts; review consumer-visible RDF changes.
  4. Implement the parser and test harness, and run the fixtures through the compiler and execution path. Keep RFC-0013 draft until those checks pass.