gnomonlearn
Docs/RFC-0013/Reference catalog

RFC-0013 · Reference catalog

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.

← Read the authored RFC

Generated reference catalog. This page renders structured Lean data for RFC-0013: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in RFC-0013.

This page is generated from the lean/Gnomon/Spec/ module for RFC-0013. Edit that source and regenerate this catalog.


Title: Test Execution Model
Status: draft
Owners: Compiler, DX
Diagnostic range: M01300-M01399

Proof citations in source: 8 / 8. Standalone proof verification is pending.


Definitions

(none defined)

Diagnostics

CodeSeverityDescription
M01300Errortest declaration found in bundle with ciState: ready. Test declarations are not permitted in production builds.
M01301Errortest block has invalid structure: missing or reordered given, when, or then block.
M01302Errorwhen references an identifier that is not an action declaration, or references more than one action.
M01303ErrorExpression in then block is not boolean-valued.
M01304ErrorDuplicate test name within the same module.
M01305Errorgiven block references an unknown entity kind.
M01306Errorgiven initializer references a field that does not exist on the entity kind.
M01307ErrorRequired field (no default) is absent from given initializer.
M01308ErrorDuplicate entity ID within the same given block.
M01309ErrorCross-entity reference in given block uses an ID not declared within the same given block.
M01310ErrorUnknown enum variant in given initializer.
M01311Erroractor in when block does not match any principal kind declared on the action.
M01312ErrorRequired argument missing from when invocation.
M01313ErrorUnknown argument supplied to when invocation.
M01314ErrorAmbiguous dot-path in then expression: multiple entities of the same kind without an ID qualifier.
M01315ErrorTest execution exceeded GNOMON_TEST_TIMEOUT_MS. The test is reported as failing in TAP output.
M01316Warningtest declaration found in a file that also contains declarations with ciState: ready.
M01317Errorgiven block is empty.
M01318Warningthen block contains only one assertion; consider additional post-conditions.
M01319Errorgiven {} state does not satisfy the action’s preconditions. Test failure reported in TAP output.

Invariants

  1. A test declaration must not be included in any compiled bundle artifact where ciState is ready. (enforced by: compile-time)
  2. Cross-entity references in a given block must use a quoted string id that resolves to another entity declared in the same given block. (enforced by: compile-time)
  3. Dot-paths in then expressions over an entity kind with multiple instances in the given graph must be qualified with an id predicate. (enforced by: compile-time)
  4. Each test declaration must contain exactly one given, one when, and one then block in that order. (enforced by: parse-time)
  5. Every entity initializer in a given block must have a string-literal id field, and ids must be unique within the block. (enforced by: compile-time)
  6. Every expression in the then block must be boolean-valued per the constraint expression language. (enforced by: compile-time)
  7. TAP output must be emitted to stdout while diagnostics and harness warnings must go to stderr. (enforced by: runtime)
  8. Test names must be unique within a module. (enforced by: compile-time)
  9. The gnomon test harness must exit 0 only when all tests pass, 1 when any test fails, and 2 when any test file has a compile error. (enforced by: runtime)
  10. The in-memory object graph seeded by given is isolated per test and shares no state across test executions. (enforced by: runtime)
  11. The test harness must not make real network calls; external I/O within an action’s execute block must be stubbed via mock or omitted. (enforced by: runtime)
  12. The when block must reference exactly one declared action. (enforced by: compile-time)
  13. gnomon test must be a required, blocking, unfiltered CI step in every project pipeline with no waiver mechanism. (enforced by: governance)

Normative Statements

Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.

CI Enforcement

  1. MUST — CI MUST run gnomon test with default TAP reporter for machine-parseable output.
  2. MUST_NOT — Projects MUST NOT use —filter as a substitute for the unfiltered required step. (proof citation: rfc0013_b10_grounded; verification pending)
  3. SHOULD — TAP output SHOULD be captured by the CI system’s test result parser.
  4. MUST — The CI step MUST fail if gnomon test exits with code 1 or 2.
  5. MUST — gnomon test MUST be a required, blocking step in every project’s CI pipeline.

Invariants

  1. MUST_NOT — A test declaration MUST NOT be included in any compiled bundle artifact where ciState: ready.
  2. MUST — Each test declaration MUST contain exactly one given, one when, and one then block, in that order.
  3. MUST — Every expression in the then block MUST be boolean-valued per RFC-0008 §8.22. (proof citation: rfc0013_b26_grounded; verification pending)
  4. MUST — TAP output MUST be emitted to stdout and diagnostics to stderr.
  5. MUST — Test names MUST be unique within a module.
  6. MUST — The gnomon test harness MUST exit 0 only when all tests pass; 1 on failure; 2 on compile error.
  7. MUST — The in-memory object graph seeded by given MUST be isolated per test with no state leakage.
  8. MUST — The when block MUST reference exactly one declared action. (proof citation: rfc0013_b3_grounded; verification pending)

Output Format

  1. MUST_NOT — The pretty reporter MUST NOT be used in CI environments.

Relation to the Install Plan

  1. MUST — Test declarations encountered in production build mode MUST raise a hard error (M01300). (proof citation: rfc0013_b5_grounded; verification pending)

Scope

  1. MUST_NOT — Test declarations MUST NOT appear in any artifact with ciState: ready.

Test Declaration Anatomy

  1. MUST — All required action arguments MUST be supplied; extras are forbidden. (proof citation: rfc0013_b17_grounded; verification pending)
  2. MUST — Ambiguous dot-paths in then expressions MUST be qualified with an ID predicate.
  3. MUST — EntityKind in given block MUST refer to a declared entity kind in scope. (proof citation: rfc0013_b28_grounded; verification pending)
  4. MUST — Every field listed in a given initializer MUST exist on the declared entity kind. (proof citation: rfc0013_b24_grounded; verification pending)
  5. SHOULD — Test names SHOULD describe the invariant being verified, not the mechanism.
  6. MUST — The actor field is required and MUST match a principal kind declared on the action. (proof citation: rfc0013_b20_grounded; verification pending)
  7. MUST — The id field MUST be a string literal and unique within a given block.
  8. MUST_NOT — The test harness MUST NOT make real network calls; external I/O in execute{} MUST be stubbed or omitted.

Test Harness CLI

  1. MUST_NOT — —reporter pretty MUST NOT be used in CI.

Linked References

(no cross-RFC dependencies)