gnomonlearn
Docs/Diagnostic namespace proposal

Diagnostic namespace 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.

Owner: spec and the compiler/tooling maintainers. Status: proposed; no normative code identities have been changed. The extracted control-plane stub has stopped emitting a conflicting M01600 informational finding.

Observed contracts

  • RFC-0000 §6.1 assigns M plus a two-digit RFC ID and three local digits. Its table gives RFC-0001 M01000–M01999, RFC-0014 M14000–M14999, and RFC-0019 M19000–M19999. The same table explicitly allocates F, L, and R exceptions, despite saying all codes use M.
  • Five Lean catalogs declare ranges inside RFC-0001’s M01000–M01999 allocation: RFC-0013 M01300–M01399 (20 catalog codes), RFC-0014 M01400–M01499 (seven codes in this range), RFC-0015 M01500–M01599 (17 codes), RFC-0016 M01600–M01699 (11 codes), and RFC-0019 M01900–M01999 (nine codes). No two Lean diagnostic entries currently define the same exact code across the 742 catalog entries, but the allocation ranges overlap. The nine active RFC-0019 diagnostics are M01901–M01907, M01910, and M01911; M01908 and M01909 are reserved. A search of RFC-0001’s authored and Lean catalog sources found no active M019xx definitions, but allocation ownership still overlaps.
  • RFC-0014 §8 and its Lean catalog assign M01400–M01499 compiler codes and M14800–M14899 semver lint codes. M014xx lies within RFC-0001’s allocation; M148xx lies within RFC-0014’s. RFC-0014 says L014xx must not be emitted before registration, while RFC-0000 §6.2 already lists L01400–L01499 as registered. RFC-0019 §9 requires L01401 to block publish for a breaking minor or patch change. RFC-0000 instead describes L01401 as a nonbreaking major change, and RFC-0014 assigns that latter warning meaning to M14801.
  • RFC-0006’s M06520 follows the M06 allocation. A leading zero after M alone does not establish that a code is malformed. The occurrence inventory records 654 distinct tokens and 1,404 source-line occurrences; it does not classify emitters or prove that two mentions with one code have the same meaning.
  • python3 tools/check_diagnostic_catalog.py reads the 55 Lean RFC modules. It now finds 742 exact diagnostic entries with no duplicate code, five overlapping declared ranges (RFC-0001 against RFC-0013–RFC-0016 and RFC-0019), and seven entries outside their module’s single declared range: RFC-0014’s M14800 and M14801, and RFC-0049’s five M491xx codes. The latter seven may belong to valid secondary allocations, but the current metadata cannot express them. The normative release gate now reports these findings rather than treating a duplicate-free catalog as collision-free.
  • kg/diagnostic-inventory.textproto is a deterministic protobuf snapshot of those 742 Lean definitions, including exact code, RFC catalog owner, description, severity, optional phase, and source hash. CI and the release gate check its drift. It is an observed source inventory, not yet the owner-approved normative code registry or proof of implementation emission.
  • The DIAGNOSTIC_COVERAGE.md narrative/catalog queue compares exact tokens against that snapshot: 545 shared, 109 narrative-only, and 197 catalog-only. Each unmatched token links to its source. These are review candidates, not automatic defects: ranges, reservations, examples, and structured-only definitions need individual classification.
  • RFC-0002 has a second exact-code conflict: §7.4 requires warning M02156 for a recreate migration needing explicit authoring intent, while §11 and the Lean diagnostic catalog define M02165 for that condition. The generated reference and RDF claims consequently carry both identities. The local source search found no executable emitter for either code; it cannot establish what stored or external consumers have seen. The companion QA records the owner decision needed.

The inherited narrative/decisions/diagnostic-codes.md decision record says allocated diagnostic IDs are permanent and describes M0xxxx as a legacy range. The consumer audit found an actual M01600 emitter collision: an INFO placeholder in the control plane used an RFC-0016 ERROR identity. The stub emitter has been removed. These facts supersede the earlier idea of routinely renumbering M013xx–M016xx and M019xx into new owner ranges with aliases.

Keep already assigned IDs as canonical identities with their existing meanings. Define an explicit source-owned registry for each exact code: owner, condition, severity, lifecycle status, provenance, and any documented alias. Register the inherited M013xx–M016xx and M019xx allocations as closed legacy exceptions inside RFC-0001’s broad historical band; reserve their unused numbers against RFC-0001 reuse. Use unambiguous two-digit owner ranges for new M codes and register intentional F, L, and R namespaces explicitly. Consumers must resolve owner through the registry, not infer it from the digits of a legacy ID. A range may describe capacity, but an exact code entry owns the public meaning.

For the semver gate, retain RFC-0014’s M14800 as the blocking diagnostic for a breaking minor or patch change and M14801 as the warning for a nonbreaking major bump. RFC-0019 currently gates on L01401 for the former condition, while RFC-0000 assigns L01401 the latter meaning. Do not emit L01401 until the owner selects one meaning. The owner confirmed that nothing is deployed, and a search of extracted implementation paths found no executable emitter for either L0140x or M1480x semver code. For the first release, the recommended reconciliation is therefore to use only the RFC-0014-authored M14800 and M14801 pair, update RFC-0019’s publish gate to those codes, and remove RFC-0000’s conflicting L0140x allocation. Do not add compatibility aliases merely for an undeployed contract. Keep the old code mentions in the historical record and verify the actual linter and publish paths before shipping them. If a persisted or external producer is later discovered, review its exact trigger and severity before assigning any alias; L01401 cannot safely mean two different conditions.

For that first-release choice, change RFC-0019 §2, §4, §8, and §9 from L01401 to M14800 for the blocking condition and from L01402 to M14801 for the warning. Make the same edits in its Lean catalog, RDF claims, generated reference, and Q&A. Remove the L01400–L01499 row from RFC-0000 §6.2 and its projection; RFC-0017’s LSP L allocation remains separate. Keep RFC-0014’s authored M14800/M14801 definitions and make its obsolete L-prefix governance note describe the chosen first-release contract. Regenerate diagnostic inventories and compare exact IDs and conditions before publication.

Acceptance before emission or release

  1. Classify each inventoried token as a definition, reserved range endpoint, alias, example, or cross-RFC reference; build a source-owned code registry with exact owner, condition, severity, and status.
  2. Audit compiler, linter, registry, MCP, and CI source consumers for the affected IDs. The owner reports no deployment, so no live-resource or stored-diagnostic migration is required for the first release.
  3. Approve permanent exact-code ownership for legacy M0xxxx IDs and the M14800/M14801 semver meanings after source-consumer review. Amend RFC-0000 and each affected RFC-0013–RFC-0016 and RFC-0019, their Lean catalogs, RDF projections, and generated references in one reviewed change.
  4. Extend range metadata to express every intentional secondary allocation, including RFC-0014 and RFC-0049. Add generation and collision checks that reject duplicate exact IDs, ambiguous aliases, incompatible meanings, and codes outside registered ranges. Test representative legacy-code inputs and new-code outputs through the actual compiler/publish path.

Rollback before publication is a source revert. After publication, keep allocated codes and their historical meanings stable; do not recycle them.

Snapshot freshness repair (2026-10-13)

The Lean catalogs remain the canonical inputs to the observed diagnostic snapshot. A fresh release check found stale RFC-0000 and RFC-0001 source hashes and the earlier M01002 description in that snapshot. Regeneration through tools/emit_diagnostic_inventory.py --write retains 742 entries from 55 catalogs and propagates the existing authored correction: composition or view declaration found in backend-only module. No code ID, severity, phase, or allocation changed in this repair.

The existing emitter and release drift checks correctly rejected the old snapshot. The narrative/catalog coverage consumer could still accept it, because it parsed the stored protobuf without validating its current source binding. It now requires exact canonical regeneration before consuming the snapshot. Seven focused tests cover missing snapshots, stale diagnostic or nondiagnostic source, modified stored entries or source hashes, and recovery after regeneration. CI runs those tests. The aggregate release checker reports a freshness failure as a gap while continuing its other checks.

The regenerated coverage remains 545 shared exact codes, 109 narrative-only tokens, and 197 catalog-only entries. The allocation audit still reports five overlapping ranges and seven entries outside a declared range, with no duplicate exact IDs. These remain owner-review gaps; freshness validation does not adopt the proposed normative registry or establish implementation emission.

Terminal command logs and their protobuf evidence record are preserved in build/evidence/diagnostic-inventory-20261013/. They record the original stale snapshot rejection, the former coverage acceptance, the strengthened consumer rejection, focused tests, regeneration, drift checks, and the release report. Normative release remains blocked by the other contract, proof, grammar, identity, and publication gaps.

Allocation gate classification proposal (2026-10-13)

This extends the existing open diagnostic namespace decision in RFC-0000’s Q&A. No additional owner question, allocation, alias, or code migration is introduced. The production audit is tools/check_diagnostic_catalog.py; there is no audit_diagnostic_ids.py in this spec checkout. Its current exit policy remains unchanged while the representation below is proposed.

What the current audit proves

The audit rejects duplicate exact catalog IDs. Its five interval overlaps and seven entries outside a Lean diagnosticRange are metadata observations. They are already unresolved findings in the normative release gate. A zero audit exit code does not establish valid allocation ownership.

ObservationAuthored source and classification
Five overlaps: RFC-0001 against RFC-0013–0016 and RFC-0019RFC-0000 §6.2 assigns those RFCs separate M13xxx–M16xxx and M19xxx ranges, but their Lean catalogs retain M013xx–M016xx and M019xx. The inherited diagnostic decision also calls M0xxxx permanent legacy IDs. These are the already open allocation/legacy conflicts, not authority to renumber or silently authorize them.
RFC-0014 M14800 and M14801 outside its single Lean M01400–M01499 fieldRFC-0014 §8 expressly owns both compiler M01400–M01499 and lint M14800–M14899; RFC-0000 §6.2 includes M148xx in RFC-0014’s M14000–M14999 interval. These two findings expose incomplete secondary-allocation metadata. The separate M014xx ownership conflict remains open.
RFC-0049 M49100, M49110, M49120, M49130, and M49140 outside its Lean M49000–M49099 fieldAll five are explicitly defined in the catalog to which authored RFC-0049’s Diagnostics section delegates. Their complete allocation is unrepresented, and RFC-0000’s table has no RFC-0049 row. Do not infer an approved M49000–M49999 registry entry from the digits.
An overlap that can be authorizedRFC-0000 §6.2 expressly delegates M08770–M08778 to RFC-0011 inside RFC-0008’s M08000–M08999 interval. Rejecting every overlapping interval would reject this authored delegation if both were represented.

The inherited external Spec.Corpus.Schema.Document.diagnosticRange is one optional string, described as a range the RFC owns. It cannot represent both RFC-0014 allocations or distinguish an authorized delegation from a conflicting claim. It must not be treated as a complete normative registry by assumption.

The source-bound probe also compares literal RFC-0000 §6.2 rows with the observed snapshot. The table has 36 rows for 34 distinct RFC owners plus the runtime row. Twenty catalog owners, RFC-0035–0054, have no table row, covering 247 entries. Another 113 entries lie outside a same-width interval for their catalog’s RFC, and six RFC-0017 entries have no matching prefix/width interval because the catalog uses four-digit L codes. These are review candidates, not 366 established allocation violations. Catalog placement does not itself prove public allocation ownership: RFC-0008’s catalog includes codes in other RFCs’ numeric bands, which still require definition-versus-reference review.

Use a Gnomon-owned protobuf registry with a flat repeated list of allocations and explicit exact-code ownership. An RFC may own multiple allocation records. The concrete, unadopted schema is proposals/diagnostic_ownership_registry.proto (repository access required). Each allocation has a stable record ID, owner, prefix, exact-width lower and upper digit strings, optional explicit parent allocation, and source-bound authority evidence. Exact-code records reference their allocation and separate defining catalog uses from cross-RFC references. The observed diagnostic snapshot remains an inventory of source catalogs until this registry is approved; its rfc_id must not be silently reinterpreted as allocation owner.

Recommend allowing an intersection across different owners only when the approved registry explicitly authorizes a nested delegation and identifies the parent capacity reserved for that child. Containment or similar digits alone would not authorize it. Legacy exceptions would need the same explicit source-owned authorization. Unrelated partial intersections or competing exact-code owners would fail. Overlap within one owner is a representation normalization issue, not automatically a conflicting public owner.

After approval, generate RFC-0000’s complete allocation table and the per-owner allocation views from that registry. Keep the inherited single Lean field as a documented partial view, or revise the external schema and pin through its maintainers; decide that integration explicitly. Do not edit the external type or relabel the current field as exhaustive as part of this proposal. Preserve historical code spelling and width, including leading zeros; no numeric comparison may pad, rename, or assign a public owner.

Acceptance before making allocation observations fatal

  1. Resolve the existing legacy and semver ownership questions, classify each catalog use as a definition or reference, and bind every chosen ownership decision to its source. Preserve exact IDs and meanings unless a separate public-contract change is approved.
  2. Represent all authored secondary allocations, including RFC-0014, and determine RFC-0049’s complete interval explicitly. Do not manufacture ranges from the largest observed code.
  3. Make the authoritative table complete for every registered owner and every exact code intended for emission, including RFC-0035–0054 and the RFC-0017 spelling question. Preserve RFC-0055/0056’s separate prose-only status rather than claiming this registry supplies their missing catalogs.
  4. Require valid equal-width bounds, resolved parent IDs, acyclic delegation, full child containment, explicit delegated capacity, unique exact owners, and exact membership in an approved allocation. Reject unauthorized intersections while accepting the authored RFC-0008/RFC-0011 delegation and multiple approved allocations for one owner.
  5. Add mutation tests for secondary allocations, valid delegation, unapproved overlap, missing/changed owner rows, missing parents, cycles, child escape, duplicate exact ownership, and preserved legacy spelling. Wire that ownership validator into both CI and release after its authority inputs and semantics are approved. Regenerate its table, catalogs, snapshots, references, and RDF from those inputs; require drift failures.

The existing audit is intentionally not changed to return failure for every metadata overlap or single-range nonmatch. That would add unsupported ownership semantics and still miss missing registry rows and contradictory per-RFC ownership. Six focused controls reproduce these limits without modifying source catalogs; their success means the counterexamples reproduced, not that allocation conformance passed. Persistent baseline logs, the compiled proposal descriptor, and typed byte bindings are in build/evidence/diagnostic-allocation-20261013/. The existing normative release report remains blocked on unresolved diagnostic ownership and its other recorded gaps.