Problem
The diagnostics registry already classifies each code by Stability
(stable / experimental / addon), but the language constructs themselves — blocks,
g: directives, metadata keywords, endpoint forms — have no published stability
or deprecation tier. The README warns that 0.x public contracts can still change,
yet a user or tooling author has no per-construct contract telling them which
parts are stable, experimental, deprecated, or planned.
Relevant code:
internal/diagnostics/registry.go: Stability precedent on diagnostic codes
internal/view/directives.go: supported and deferred g: directives
internal/lang/lexer.go, internal/lang/completion.go: keywords and blocks
docs/language/spec.md: prose deferrals scattered across sections
Scope
Define a per-construct stability tier (stable / experimental / deprecated /
planned) covering blocks, g: directives, metadata keywords, and endpoint
declaration forms. Publish it as a single table in the spec, align the
deferred-directive diagnostics with the tier, and optionally expose it through
existing tooling (gowdk explain / docs output).
Acceptance Criteria
- A stability table covers every supported block,
g: directive, and metadata
keyword.
- Deferred or unsupported constructs are listed as planned/deprecated together
with the diagnostic code emitted when used.
docs/language/spec.md references the table as the per-construct contract.
- Deferred-directive diagnostics and the table stay consistent (tested where a
registry/table mapping exists).
Verification
go test ./internal/view ./internal/lang
# plus doc review of docs/language/spec.md
Problem
The diagnostics registry already classifies each code by
Stability(stable / experimental / addon), but the language constructs themselves — blocks,
g:directives, metadata keywords, endpoint forms — have no published stabilityor deprecation tier. The README warns that 0.x public contracts can still change,
yet a user or tooling author has no per-construct contract telling them which
parts are stable, experimental, deprecated, or planned.
Relevant code:
internal/diagnostics/registry.go:Stabilityprecedent on diagnostic codesinternal/view/directives.go: supported and deferredg:directivesinternal/lang/lexer.go,internal/lang/completion.go: keywords and blocksdocs/language/spec.md: prose deferrals scattered across sectionsScope
Define a per-construct stability tier (stable / experimental / deprecated /
planned) covering blocks,
g:directives, metadata keywords, and endpointdeclaration forms. Publish it as a single table in the spec, align the
deferred-directive diagnostics with the tier, and optionally expose it through
existing tooling (
gowdk explain/ docs output).Acceptance Criteria
g:directive, and metadatakeyword.
with the diagnostic code emitted when used.
docs/language/spec.mdreferences the table as the per-construct contract.registry/table mapping exists).
Verification