RFC-0017 · Reference catalog
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.
Generated reference catalog. This page renders structured Lean data for RFC-0017: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in
RFC-0017.This page is generated from the
lean/Gnomon/Spec/module for RFC-0017. Edit that source and regenerate this catalog.
Title: Gnomon Language Server Protocol Contract
Status: draft
Owners: Compiler, DX
Proof citations in source: 19 / 19. Standalone proof verification is pending.
Definitions
(none defined)
Diagnostics
| Code | Severity | Description |
|---|---|---|
L0010 | Warning | project.gnm not found; LSP operating in single-file mode |
L0011 | Warning | Symbol index load failed for file; cross-file references may be unresolved |
L0020 | Warning | Rule compiler model not reachable (Ollama not running, API key missing, etc.); rule compilation disabled |
L0021 | Warning | Rule compiler response did not match expected format; treating as UNRESOLVABLE |
L0022 | Info | Rule compilation cache is stale (model digest mismatch); re-compilation scheduled |
L0030 | Warning | Model invocation timed out (>30s); rule compiler result deferred |
Invariants
- All LSP responses MUST be derived from the same semantic model as the compiler; the LSP MUST NOT apply different validation rules. (enforced by: compile-time)
- LSP diagnostics MUST use the same M-, F-, and L-codes as the compiler; custom LSP-only error codes are forbidden. (enforced by: compile-time)
- Rule compiler interactions in the LSP MUST be non-blocking and MUST NOT block completions, hover, or other capabilities. (enforced by: runtime)
- The .gnomon-cache/ directory MUST NOT store credentials, tokens, or any data other than rule compilation cache entries. (enforced by: runtime)
- The LSP MUST NOT execute any code from .gnm source files; it is a read-only analysis tool. (enforced by: runtime)
- The LSP MUST NOT invoke any model not declared in the project’s symbol table or constructed from user input. (enforced by: runtime)
- The LSP MUST NOT modify source files without an explicit user gesture such as accepting a code action or rule suggestion. (enforced by: runtime)
- The LSP MUST apply gnomon fmt formatting semantics for textDocument/formatting and produce output identical to gnomon fmt CLI on the same file. (enforced by: runtime)
- The LSP MUST use standard provider configuration when invoking model APIs and MUST NOT store or transmit credentials. (enforced by: runtime)
- The LSP MUST use the compiler.ruleCompiler model from project.gnm and MUST NOT invoke a model not declared in the project. (enforced by: runtime)
Normative Statements
Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.
Failure Modes and Diagnostics
- MUST — Completions referencing declarations in erroneous files MUST be offered with a warning prefix indicating possible invalidity
- MUST — Diagnostics for erroneous files MUST be emitted (proof citation:
rfc0017_b53_grounded; verification pending) - MUST — When the project has compiler errors, the LSP MUST continue to provide completions, hover, and definition from the partial symbol table
Invariants
- MUST — All LSP responses MUST be derived from the same semantic model as the compiler
- MUST — LSP diagnostics MUST use the same diagnostic codes (M0xxxx, F1xxxx) as the compiler (proof citation:
rfc0017_b9_grounded; verification pending) - MUST — Rule compiler interactions in the LSP MUST be non-blocking
- MUST_NOT — The LSP MUST NOT apply different validation rules than the compiler (proof citation:
rfc0017_b25_grounded; verification pending) - MUST_NOT — The LSP MUST NOT invoke a model not declared in the project (proof citation:
rfc0017_b40_grounded; verification pending) - MUST_NOT — The LSP MUST NOT modify source files without explicit user action
- MUST — The LSP MUST apply gnomon fmt formatting semantics for textDocument/formatting (proof citation:
rfc0017_b58_grounded; verification pending) - MUST — The LSP MUST use the compiler.ruleCompiler model from project.gnm when available (proof citation:
rfc0017_b11_grounded; verification pending)
Rename (textDocument/rename)
- MUST — Rename MUST validate the new name against casing convention and produce a pre-rename warning if it does not satisfy
- MUST — The LSP MUST implement rename for declaration names, flow state names, and model names (proof citation:
rfc0017_b14_grounded; verification pending)
Required LSP Capabilities
- MUST — Completion trigger characters MUST include [, ., :, ”, and @
- MUST — Find-all-references MUST return all sites where a declaration is referenced
- MUST — Go-to-definition MUST resolve qualified references, imports, model references, and flow state names
- MUST — Inside an execute {} block, the LSP MUST provide completions for client operation bindings
- MUST — Rule diagnostics MUST be updated when compilation completes via subscription or 500ms polling
- MUST_NOT — The LSP MUST NOT hardcode completion lists (proof citation:
rfc0017_b3_grounded; verification pending) - MUST — The LSP MUST implement completions by calling CompilerSession.completions_at(file, pos) (proof citation:
rfc0017_b34_grounded; verification pending) - MUST — The LSP MUST implement hover by calling CompilerSession.hover_info(file, pos)
- MUST — The LSP MUST offer code actions for documented diagnostics (M08702, M08740, M08790, M08791, M08793, M08795, M08780) (proof citation:
rfc0017_b36_grounded; verification pending) - MUST — The LSP MUST serve diagnostics from CompilerSession.diagnostics(file) using M, F, and L codes without remapping (proof citation:
rfc0017_b32_grounded; verification pending) - MUST — textDocument/formatting output MUST be identical to gnomon fmt CLI output on the same file
Rule Compiler Presentation
- MUST_NOT — Calling CompilerSession.compile_rule asynchronously MUST NOT block any other LSP operation
- MUST — Ghost annotations MUST be visually distinct from authored source text
- MUST — The LSP MUST display an InlayHint immediately after each rule ”…” line reflecting the current CacheStatus
- MUST — The LSP MUST offer Commit/Convert/Edit code actions on rule ”…” lines according to CacheStatus
Scope
- MUST — Specifies what the LSP must do given a valid Gnomon project, not how the compiler is implemented (proof citation:
rfc0017_b1_grounded; verification pending)
Security
- MUST_NOT — The .gnomon-cache/ directory MUST NOT store credentials, tokens, or any data other than rule compilation cache entries (proof citation:
rfc0017_b38_grounded; verification pending) - MUST_NOT — The LSP MUST NOT execute any code from .gnm source files
- MUST_NOT — The LSP MUST NOT invoke any model not declared in the project’s symbol table (proof citation:
rfc0017_b43_grounded; verification pending) - MUST_NOT — The LSP MUST NOT store or transmit credentials when invoking Ollama or OpenAI APIs
- MUST_NOT — The LSP MUST NOT use a model URI constructed from user input
- SHOULD — The LSP SHOULD display a one-time notice on first model invocation that rule text is transmitted to the model provider
Transport and Initialization
- MUST — On initialize, the server MUST locate project.gnm, load the full symbol table, load the compiler block, and report capabilities (proof citation:
rfc0017_b21_grounded; verification pending) - MUST — The Gnomon language server MUST implement LSP version 3.17 or later (proof citation:
rfc0017_b50_grounded; verification pending)
textDocument/semanticTokens
- MUST — Semantic token types MUST include the listed declaration, property, rule, prompt, note, expr, model, and epistemic categories (proof citation:
rfc0017_b47_grounded; verification pending) - SHOULD — The LSP SHOULD implement semantic token highlighting (proof citation:
rfc0017_b30_grounded; verification pending)
workspace/symbol
- MUST — Each symbol MUST include canonical path, file location, and meaning field truncated to 80 characters
- MUST — The LSP MUST implement workspace/symbol returning all top-level declarations grouped by kind (proof citation:
rfc0017_b27_grounded; verification pending)
Linked References
(no cross-RFC dependencies)