gnomonlearn
Docs/Learn/Reading the spec

Reading the spec

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.

The RFCs state intended contracts. Their status, formal evidence, and implementation coverage must be checked separately.

Current project update — October 23, 2026

The upstream formal-model repair in PR #81 is merged, and the v0.9.0 source tag is published. Registry release and Gnomon adoption of the corrected pin remain open, along with the normative specification gates. A published upstream source tag does not establish a released or verified Gnomon framework.

Snapshot notes below. The corpus, counts, proof observations, and pending/draft labels below describe pinned Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. They preserve that revision’s history, including the earlier draft-PR status, and do not track subsequent roadmap decisions.

Snapshot notes: source and status

The authored corpus consists of 57 flat rfc-NNNN.md files in the pinned spec revision. 55 also have generated reference catalogs from structured Lean data. Each RFC page links to its catalog when one exists. RFC-0055, RFC-0056 have no generated reference catalog yet.

Each RFC also has a design Q&A companion. A recorded answer explains a design decision; an open question or review-pending notice is unresolved work. The companions are linked from their RFC pages. The RFC-0056 transform taxonomy proposal and module import syntax proposal record unresolved contract choices.

RFC-0000 also requires seven content areas per RFC. The authoring structure audit records where the current topic-specific layouts differ from those named sections; heading counts alone do not establish whether an RFC covers an obligation.

The latest QA and catalog alignment corrects companion diagnostic references and existing warning guidance without establishing canonical AST or compiler-adapter conformance. Its scoped checks cover 303 questions, 120 section citations, and 742 diagnostic entries. These corrections leave the unresolved contracts and formal release blockers in place.

The adopted status and diagnostic corrections retain the authored import-preflight condition for M06530, distinguish the existing serialization envelope from pending canonical AST and compiler adapters, and count all 42 extracted annotation blocks. The recorded verification includes 55 Lean data modules and both actual contradictions in the unchanged formal pin. Data generation and preview integrity do not establish sound normative proofs or a release.

The pinned source review covers all 6,962 projection nodes, with 2,259 mismatches and zero unreviewed nodes. The ClaimStatus projection repair restores the already adopted requirement that a permitted regression also be explicitly reversible. The conditional batch adoption applies the ten-procedure limit when batching is implemented. Its generated reference now matches that conditional rule after data-only Lean regeneration and drift checks; these source corrections establish no runtime or proof acceptance.

The approved RFC-0053 adoption repairs 58 owner references and qualifies two indexing claims, closing 47 source-review findings. The remaining domain inventory has 940 unresolved links to 456 identities. Projection findings measure differences between the RFC, Lean catalog, and RDF; they do not count independent runtime failures. The adoption record preserves the separate security, lifecycle, and transaction findings and their acceptance requirements.

Normative language

RFC-0000 defines the terminology and use of MUST, SHOULD, and MAY. Read the surrounding rationale for context, but use the RFC text to identify the actual requirement.

Snapshot notes: diagnostic codes

Diagnostic codes are intended to identify stable conditions, but the current RFCs disagree about several legacy owner ranges and semver lint codes. The occurrence inventory lists codes mentioned in authored RFCs; it is not a registry of emitted codes. The namespace proposal and consumer audit record the unresolved ownership decision and observed implementation use. Eleven repeated term names also have differing definitions; the term drift review traces each to its source RFC, and the proposed resolution is open for owner review. Check release evidence before depending on a diagnostic or term identity in automation.

The observed diagnostic snapshot contains 742 entries from 55 Lean catalogs. Its coverage queue compares 545 shared exact codes, 109 narrative-only tokens, and 197 catalog-only entries. The freshness repair evidence records rejection of stale source bindings and seven passing mutation tests. Regeneration preserves code identities, severities, and phases. Five range overlaps and seven entries outside a declared range remain under review; fresh source bindings do not establish a normative registry or implementation emission.

The allocation classification proposal and its source-backed controls explain why metadata overlaps and single-range nonmatches cannot all be treated as invalid allocations. Authored secondary allocations and delegated ranges need explicit representation, and the central owner table is incomplete. The proposed registry remains an open decision; no public diagnostic IDs, ranges, or ownership rules were adopted by these controls.

Snapshot notes: proof and implementation evidence

Preview ZIP verification now independently checks the producer's pinned external framework commit. The integrity repair evidence preserves three focused tests using synthetic metadata controls, including rejection of a self-consistent foreign pin. Those controls do not contain actual Lean compilation or framework build evidence, and they do not establish normative conformance or release readiness.

The pinned authored EBNF bundle generates a PEG grammar that compiles with pinned Peggy and passes focused syntax probes. The inherited example audit currently passes 0 of 14 .gnm files against that PEG. Broad RFC-0008 compiler fixtures and AST comparisons remain open. The framework’s YAML graph modules use .graph.yaml; .gnm is reserved for the keyword DSL. See the grammar gate, project manifest syntax review, and source-format boundary before treating module build tests as DSL conformance.

The RFC-0026 RDF proposal shows how gRPC mode, auth, and TLS conditions can be represented without changing claim IRIs. It is a proposed graph change, and the gRPC client binding remains a draft contract.

The RFC-0020 RDF proposal records five remaining subscription relationship mismatches and a measured local query counterfactual. Its runtime type identities remain proposed.

Grammar fixtures will compare successful ASTs and failing diagnostics. The AST-stage proposal records the remaining parsed-versus-desugared choice. Its executable parsed-AST candidate has typed protobuf messages for all 36 authored declaration forms, 32 handwritten AST expectations, and three proposal rejections. The proposal corpus retains 175 of 180 syntax productions. A separate source artifact proposal binds exact comments and top-level UTF-8 ranges to the input digest, with unambiguous leading documentation owners and six handwritten source expectations. Canonical stage and identity approval, ambiguous documentation attachment, complete formatter maps, grammar gaps and rule reachability, independent typed compiler emission, and semantic and desugaring checks remain open.

The independent Lean frontend audit records 17 native accepts, 18 native rejections, and no runtime failures at framework commit 4a7fa0fda365466b94c51c45faf6020f3c993543. A slash tokenization correction resolves the division-input stall; 34 other observations are unchanged. The original baseline preserves its 16 accepts, 18 rejections, and bounded runtime failure. All three proposal-negative inputs are still accepted. The current native tree discards required punctuation and documentation and lacks independent source mappings. These are parser observations; the typed AST, source equality, approved diagnostic codes and spans, and compiler conformance gates remain unresolved.

All 85 RFC-0054 claims have source-bound reviews; 47 have text or identity mismatches after the ownership audit. The DDL claim review and execution proposal cover transaction boundaries, destructive-operation policy, and compatibility risk. These are specification findings, not verified runtime guarantees.

The PostgreSQL adapter’s 204 claim and domain nodes have source-bound reviews: 132 match and 72 mismatch. Its claim review and domain review identify stale summaries, physical database objects typed as source declarations, and backend calls typed as algebra operations. The class proposal and consumer inventory describe the pending correction. Source matches do not verify live database behavior.

The platform catalog’s 154 claim and domain nodes are reviewed: 114 match and 40 mismatch. The claim review and domain review identify an install dependency cycle and conflicting visibility rules. The bootstrap proposal and identity proposal await owner decisions; the consumer inventory bounds the RDF changes.

The identity ownership audit found 1,105 unresolved references and corrected 611 earlier match verdicts. The PostgreSQL evidence reproduces view authorization and materialized-policy failures; its security correction awaits a contract decision. Read the view claim review, domain review, identity mappings, and lifecycle proposal for scope and acceptance criteria.

The projection algebra’s 196 claim and domain nodes are reviewed: 139 match and 57 mismatch. Its claim review and domain review identify endpoint closure, authorization, aggregate results, and wire absence gaps. The closure proposal and identity repairs remain proposed. A separate executor investigation found template composition runs after commit despite the authored transactional contract; rollback conformance remains unverified.

The versioning review and agent runtime review are complete source reviews. Their caret warning and dispatch sequence repairs remain proposed. The test report proposal includes a protobuf envelope and a pinned TAP consumer check; it does not establish an implemented DSL test harness.

The 55 reference catalogs are checked-in generated outputs. Their generation and drift tool belongs to Spec. The current catalogs pass that data-only workflow; the projection review record documents the refresh and remaining semantic findings. Claim and domain RDF projections regenerate from protobuf sources with a drift check, and source-bound review covers all projection nodes. Semantic mismatches and unresolved domain references still block normative release. The projection review record tracks source-bound verdicts, the filename literal review identifies inherited source-name drift, the RFC-0001 claim-model proposal shows two pending RDF corrections, the module-type value proposal identifies permitted values currently modeled as declarations, and the consumer impact record shows measured local query changes. The ClaimStatus migration record explains a corrected RFC-0035 contract and the unresolved consumer audit. Gnomon derivations compile with deferred proofs allowed, but the strict release gate rejects those deferred cases; reviewed mismatches are recorded as deferred proof obligations, and the three current no-sorry candidates have source-bound proposition-to-claim matches under external assumptions. The pinned framework also derives False from a contradictory nonempty-kind premise; compilation cannot establish sound normative guarantees for proofs importing those inputs. The proof-status record, per-RFC inventory, and authored theorem link audit give the current counts. Proof citations are not verified guarantees. A specified API or diagnostic does not establish that a release implements it; check the relevant repository tests and release notes.

The current derivation inventory accounts for 722 RDF derivations: 721 generated entries and RFC-0049's separately linked structural theorem, with no missing or orphaned entries. A conditional write-time XOR proof replaces one deferred obligation under unchanged AX-008; 718 deferred bodies remain. The numeric-ID citation review now records a mismatch because distinct tagged identities can carry equal raw IDs, bringing the authored citation ledger to 715 mismatches. The actual compiled consistency observation independently shows that the pinned inputs derive False without sorry or a new axiom. Strict proof and release gates explicitly reject that known pin, even if deferred bodies later reach zero.

The admission repair proposal separates raw inputs, valid values, and a shared admitted population. Its preserved observations include a second contradiction involving statement identity. The upstream source repair is published as draft PR #81; its 18 formal modules compile under the recorded toolchain, with 92 remaining assumptions. No corrected release or replacement Gnomon pin has been adopted.

The separate complete consumer candidate compiles all 17 authored source calls with 775 declarations, 12 explicit authored deferrals, and zero unassigned sorry tokens. The generated stream retains 718 deferrals; these two counts cannot be added as unique claims. The comment correction preserves compiled code while removing unsupported completion claims. These are diagnostic and source-review results. Proof acceptance, general consistency, backend conformance, and normative release remain open.