Design model

Platform spec article

Design model

Back to Diagnostic code registry ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (3)

1. 0001-feature-hub-authority Feature hub authority Accepted

   This feature hub owns normative MUST/SHOULD contract text for Diagnostic code registry.

   Context

   Sibling articles under this feature previously restated requirements in inconsistent forms.

   Decision

   This feature hub owns normative MUST/SHOULD contract text. Sibling articles must not redefine hub requirements and should link here for authority.

   Consequences

   Contract changes start on the hub or in linked ADRs, then propagate to articles and implementation anchors.

   Verification anchors

   • site/website/src/content/docs/platform-spec/compiler/semantic-pipeline/diagnostic-code-registry/index.mdx
   • article bundle under the same feature directory.

   Open full ADR page

2. 0002-spec-over-implementation-notes Specification over implementation notes Accepted

   Platform-spec text supersedes informal crate comments for Diagnostic code registry.

   Context

   Implementation crates accumulated informal notes that diverged from published contracts.

   Decision

   Normative platform-spec prose and ADRs under this feature supersede informal comments in implementation crates until explicitly migrated into spec text.

   Consequences

   Engineers file spec/ADR updates when behavior changes; crate comments are non-authoritative for conformance arguments.

   Verification anchors

   • compiler/crates/beskid_analysis/src/analysis/diagnostic_kinds.rs
   • compiler/crates/beskid_analysis/src/analysis
   • compiler/crates/beskid_analysis/src/doc/validate.rs

   Open full ADR page

3. 0003-codes-owned-in-analysis Diagnostic codes owned in analysis sources Accepted

   Rendered diagnostics drifted from semantic registry.

   Context

   Rendered diagnostics drifted from semantic registry.

   Decision

   Code-to-meaning mapping is normative in SemanticIssueKind::code() and diagnostic_kinds.rs, synchronized with trudoc verify scripts—not LSP presentation layers.

   Consequences

   Renaming codes requires migration notes; new issues need unique codes before release.

   Verification anchors

   • compiler/crates/beskid_analysis/src/analysis/diagnostic_kinds.rs
   • packages/trudoc/scripts/verify-diagnostics-spec-sync.mjs.

   Open full ADR page

Articles

• Contracts and edge cases Stability requirements and risky changes in the diagnostic registry. article Standard
• Design model Conceptual model for owning and evolving semantic diagnostic codes. article Standard
• Examples Representative registry update scenarios and expected outcomes. article Standard
• FAQ and troubleshooting Common registry maintenance questions and recovery guidance. article Standard
• Flow and algorithm Lifecycle of a semantic diagnostic code from definition to surfaced output. article Standard
• Verification and traceability Checks that keep diagnostic code docs and source synchronized. article Standard

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 0 SpecSection(s) · 4 H2 heading(s)

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Feature
  Diagnostic code registry

  Parent feature

• Feature
  Rules and diagnostics catalog

  Rules emit registry-defined code identities

• Area
  Compiler Mods

  Mod diagnostics parity and Mod SDK surfaces

The registry model is intentionally centralized:

• diagnostic_kinds.rs owns code identities and semantic categories.
• Rule modules reference kinds, not hard-coded code strings.
• Delivery adapters (CLI/LSP) preserve code identity while formatting messages.

This avoids drift between compiler internals and platform documentation, and it makes diagnostics easier to consume in editors and CI tooling.

Mod, manifest, and mod-host band (E1801–E1899)

The inclusive range E1801–E1899 is owned by compiler-mod manifest validation and mod-host failures. Ordinary semantic rules must not allocate inside this band. Register each allocated code in compiler/crates/beskid_analysis/src/analysis/diagnostic_kinds.rs and extend this table in the same change.

Code range	Owner	Intended failures (examples)
E1801–E1810	beskid_analysis::projects manifest parse	Unknown mod key, invalid maxGeneratorRounds, malformed capabilities list, Meta→Mod migration (see table below).
E1811–E1820	Workspace / graph resolution	Invalid Mod dependency topology, unresolved mod package, incompatible host/mod graph constraints.
E1821–E1835	Mod host / capabilities	Denied capability, exceeded maxGeneratorRounds, sandbox violation, AOT artifact load/bootstrap failure (see AOT artifact contract).
E1836–E1850	Typed merge / rewrite	Conflicting generator edits, illegal typed contribution, invalid typed rewrite, merge rollback.
E1851–E1870	Contract discovery / execution	Missing required contracts, invalid contract signatures, collector scope violations, analyzer/rewriter registration errors.
E1871–E1899	Reserved	Buffer for staged rollout; allocate in order and extend this table when used.

Meta→Mod migration and manifest parse (E1801–E1810, normative)

Code	When emitted
E1801	Unknown key inside project.mod.
E1802	maxGeneratorRounds missing, non-positive, or not an integer.
E1803	capabilities entry not in the closed vocabulary.
E1804	artifactPolicy value not in reuse / rebuild / clean_rebuild.
E1805	type: Mod project declares a target block (forbidden).
E1806	Compiler-mod contract item declared outside a type: Mod project.
E1807	Deprecated type: Meta or nested meta { } manifest section (use Mod / mod { }).
E1808	Removed attachTo key on mod/manifest (use Collector scope).
E1809	Removed entryModules key (use contract discovery).
E1810	Legacy max_meta_rounds or other removed mod keys.

Mod artifact load (E1821–E1835, normative)

Individual codes are defined in Mod host bridge / AOT artifact contract (E1821 missing artifact through E1835 bootstrap catch-all). Hosts must prefer the most specific code before E1835.

Typed merge (E1836–E1850, normative)

Code	When emitted
E1836	Two generators target the same declaration identity in one generation round.
E1837	Typed contribution fails well-formedness / parser re-check after merge.
E1838	Rewriter returned an illegal target node kind.
E1839	Merge rolled back — syntax tree unchanged after failure.
E1840–E1850	Reserved for additional merge/rewrite failures.

Contract discovery (E1851–E1870, normative)

Code	When emitted
E1851	Module-level meta item or other forbidden grammar in a Mod/host compilation unit.
E1852	Required Collector contract missing from artifact registrations.
E1853	contractId in descriptor not recognized by host.
E1854	Public type does not implement declared contractId.
E1855	entrySymbol missing from native export table.
E1856	Collector scope references unresolved compilation member.
E1857	Analyzer registration conflicts with capability set.
E1858	Rewriter generic instantiation does not match source node kind.
E1859–E1870	Reserved for contract execution failures.

Language macro expansion (E1901–E1999)

The inclusive range E1901–E1999 is owned by macro.expand and macro definition validation. Ordinary semantic rules must not allocate inside this band.

Code	When emitted
E1901	name! invocation with no resolving macro binding in scope.
E1902	Argument count does not match macro parameter list.
E1903	Actual argument shape does not match declared fragment kind.
E1904	$param reference in a non-macro body or unknown parameter name.
E1905	maxMacroExpansionDepth exceeded (default 32).
E1906	Expanded tree fails well-formedness / structural validation.
E1907	Ambiguous macro name (multiple macro bindings in scope).
E1908	macro definition with duplicate parameter names.
E1909	Invalid or unknown fragment kind keyword in macro parameter list.
E1910–E1999	Reserved for macro hygiene and item-splice failures.

See Language macros.

Documentation comment diagnostics (W1610–W1619, W1620–W1625)

The inclusive ranges W1610–W1619 and W1620–W1625 are reserved for leading documentation body validation (triple-slash mini-language: @ref, @arg, @returns, @variant, @par, and unknown directives). These warnings are produced from the document-analysis snapshot after name resolution succeeds; they must not use ad hoc string codes outside SemanticIssueKind. Hard errors for documentation are not allocated in v1; if a future policy introduces blocking documentation failures, allocate E1610–E1629 in this document and in diagnostic_kinds.rs before use.

Code	Meaning (summary)
W1610	@arg names a parameter that does not exist on the documented callable.
W1611	Duplicate @arg(name) for the same item.
W1612	@arg / @returns on an item that is not a supported callable.
W1613	@returns on a unit return (redundant).
W1614	Unknown documentation directive (@foo not in the supported registry).
W1615	Unresolved @ref(...) path.
W1616–W1619	Reserved for documentation-quality rules.
W1620	@variant(...) used outside an enum declaration’s leading documentation.
W1621	@variant(name) does not match any enum variant.
W1622	Duplicate @variant(name) in the same block.
W1623	@par(...) where the declaration has no generic type parameters.
W1624	@par(name) does not match a generic type parameter on the item.
W1625	Duplicate @par(name) in the same block.

Codes must be stable across patch releases once shipped; breaking message text is allowed only with a migration note in Rules and diagnostics catalog.

User FFI diagnostics (E1520–E1539, v0.3)

The inclusive range E1520–E1539 is owned by FFI and extern and Export and callbacks validation. These codes are normative in platform-spec v0.3; the reference compiler may still emit legacy T0901–T0904 until migration completes—tests must accept either code during the transition, then only E152x once diagnostic_kinds.rs maps TypeError::Extern* to SemanticIssueKind.

Code	When emitted	Reference compiler (transition)
E1520	Extern Abi is not "C"	T0901
E1521	Extern contract missing non-empty Library	T0902
E1522	Disallowed parameter type on extern method	T0903
E1523	Disallowed return type on extern method	T0904
E1524	Export on non-pub function or disallowed item	(planned)
E1525	Export signature uses disallowed FFI type	(planned)
E1526	Unknown Symbol override or duplicate export symbol	(planned)
E1527	Transfer / interop view misuse at boundary	(planned)
E1528	CLayout violation (v0.3.1)	(planned)
E1529	Callback type is not a permitted function-pointer shape	(planned)
E1530–E1539	Reserved	Buffer for link manifest and import CLI failures

Attribute placement errors remain in the E1508–E1510 band (E1510 = Extern on non-contract).