gnomonlearn
Docs/RFC-0035 standard-library error contract proposal

RFC-0035 standard-library error 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: source review and first-release proposal, 2026-10-03. Owners: compiler, module platform, runtime, and API server bindings. No Gnomon deployment exists; no stored-value migration is required.

Source-bound review

All 61 RFC-0035 domain nodes have source-bound reviews: 60 match and one mismatches. core.errors.ValidationError.fields is authored in §4.1 as List<FieldViolation> with no required modifier. RDF instead sets fieldType directly to FieldViolation and isRequired true. This loses the list container and asserts a requiredness the syntax does not state.

The core.claims module summary had also retained a pre-decision statement that it defined claim status. The owner-approved ClaimStatus flow belongs to RFC-0006; RFC-0035 defines evidence record types only. The summary literal has now been corrected in the protobuf source and regenerated Turtle, with the same subject IRI. The other 60 nodes agree with the current prose and Lean at source level. These reviews do not prove compiler or runtime behavior.

Error-shape decision

ValidationError means one or more fields failed validation (§4.1), but its authored fields: List<FieldViolation> has neither required nor a nonempty constraint. For the first release, require the field and at least one FieldViolation, keep its RDF type as a list with a typed element, and add a compiler/runtime validation rule. If zero field-specific violations are possible, use a distinct general error rather than an empty ValidationError. The emitted RDF should represent container type and element type separately instead of collapsing List<T> to T.

The RFC also defines Unauthorized as both unauthenticated and lacking scope, while Forbidden is authenticated but not permitted. RFC-0034’s handler pipeline separates authentication from authorization. Resolve the response taxonomy before publishing API error contracts: reserve Unauthorized for failed or absent authentication and Forbidden for an authenticated caller without permission; decide whether requiredScope belongs on Forbidden. The HTTP binding should map these to its corresponding protocol responses. RFC-0033’s example currently imports gnomon.errors, while the canonical standard library is core.errors; align that example and its referenced error identities. Since nothing is deployed, do not add aliases or value conversion for the old example namespace.

Acceptance

  1. Align RFC-0033/0034/0035 and the HTTP binding on error identity, authorization semantics, status mapping, and ValidationError shape.
  2. Align the Gnomon source, Lean catalog, RDF source, and generated Turtle; rebind source-bound reviews and compare checked-in SPARQL results.
  3. Compile and serialize a nonempty validation error; reject an empty one; exercise unauthenticated and authenticated-but-forbidden requests and check the distinct response types. No production migration test is needed.