RFC-0017 · Gnomon Language Server Protocol Contract
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.
| Status | Draft corpus. Reference catalogs and RDF projections have generation drift checks; Gnomon proofs and projection semantics remain unverified for release. |
|---|
View the generated reference catalog →
Read design questions and decisions →
Status: Draft Owners: DX, Compiler
1. Scope
Defines the normative contract for the Gnomon language server (gnomon lsp). This RFC extracts and expands the LSP stub in RFC-0012 §7 into a complete specification covering all LSP capabilities, the rule compiler feedback loop, model-aware completion, and the diagnostic pipeline.
This RFC governs the developer experience at authoring time. It does not define runtime behavior, formatter behavior (RFC-0012), or the rule compilation algorithm (RFC-0008 §11.3). It specifies what the LSP MUST do given a valid Gnomon project; it does not specify how the compiler is implemented.
2. Goals
- Every LSP capability is derived from the semantic model — completions come from the symbol table, hover from
meaningfields, diagnostics from the same compiler that validates bundles - The rule compiler feedback loop is interactive and non-blocking — authors write natural language and see the compiled constraint expression inline before accepting it
- Model declarations are first-class LSP citizens — the LSP can resolve, validate, and preview model bindings at authoring time
- The LSP contract is implementable without a full production compiler — a partial implementation can satisfy individual capabilities incrementally
- Editor independence — the contract is pure LSP; no editor-specific extensions are required
Linked References
The cross-RFC dependency graph is rendered in reference catalog § Linked References. Out-of-KG pointers to legacy code or external resources, when present, remain in this document under “Source-tree references” below.
3. Invariants
- All LSP responses MUST be derived from the same semantic model as the compiler. The LSP MUST NOT apply different validation rules than the compiler.
- The LSP MUST NOT modify source files without explicit user action. Applying a code action or accepting a rule compiler suggestion requires an explicit user gesture.
- Rule compiler interactions in the LSP MUST be non-blocking. The LSP MUST NOT block completions, hover, or other capabilities while waiting for the rule compiler model.
- The LSP MUST use the
compiler.ruleCompilermodel fromproject.gnmwhen available. It MUST NOT invoke a model not declared in the project. - LSP diagnostics MUST use the same diagnostic codes (M0xxxx, F1xxxx) as the compiler. Custom LSP-only error codes are forbidden.
- The LSP MUST apply
gnomon fmtformatting semantics fortextDocument/formatting— it MUST produce output identical tognomon fmton the same file.
4. Transport and Initialization
The Gnomon language server MUST implement LSP version 3.17 or later. It is distributed as part of the gnomon CLI toolchain and invoked as:
gnomon lsp [--stdio | --socket=PORT | --pipe=PATH]
Default transport is stdio.
4.1 Initialize
On initialize, the server MUST:
- Locate
project.gnmby walking up from the root URI - Load the full symbol table for the project (all
.gnmfiles reachable fromproject.gnm) - Load the
compilerblock fromproject.gnmto determine the rule compiler model and template version - Report the capabilities listed in §5 in the
ServerCapabilitiesresponse
If no project.gnm is found, the server operates in single-file mode: diagnostics and hover are available, but cross-file symbol resolution, completions, and go-to-definition are degraded.
4.2 Workspace Symbol Index
The LSP maintains an in-memory symbol index keyed by canonical path (e.g., benefits.entities.Employee). The index is updated incrementally on textDocument/didChange and textDocument/didSave. Full reindex is triggered by changes to project.gnm.
5. Required LSP Capabilities
The following capabilities MUST be implemented. Optional capabilities are defined in §6.
5.1 textDocument/completion
The LSP MUST implement completions by calling CompilerSession.completions_at(file, pos) (RFC-0018 §5). The compiler derives valid completions from:
- The
ParseContextat the cursor position (RFC-0018 §6) — determines what kind of value is valid here - The
ScopeInfo.visible_symbolsfiltered by theIdentSetFilterfor the current context (RFC-0018 §7.1) - The
PropertyRegistryfor the enclosing declaration kind (RFC-0018 §8) — drives property key completions
The LSP MUST NOT hardcode completion lists. All valid-property knowledge lives in the property registry; all valid-identifier knowledge comes from the symbol table filtered by scope and type. The LSP maps CompletionCandidate items (RFC-0018 §7.3) to LSP CompletionItem objects.
Key mapping behaviors:
CompletionCandidate.detail→CompletionItem.detailCompletionCandidate.documentation→CompletionItem.documentation(MarkupContent)CompletionCandidate.insert_text→CompletionItem.insertText(snippet format)- Required properties (
PropertySpec.required = true) →CompletionItem.sortTextprefixed with!to sort them first - Deprecated/epistemic symbols →
CompletionItem.deprecated = true
Trigger characters MUST include [, ., :, " (within with position), and @.
Inside an execute {} block (RFC-0008 §6.10), the LSP MUST provide completions for client operation bindings. When the cursor is after a client name and . trigger character (e.g., WorkOS.), the server MUST return all operation names defined on that client’s spec, ranked by relevance. The completion items MUST include: the operation name, its input schema as snippet placeholders, and its return type in the detail field. The ParseContext for execute block cursors is InExecuteBlock (RFC-0018 §6).
5.2 textDocument/hover
The LSP MUST implement hover by calling CompilerSession.hover_info(file, pos) (RFC-0018 §11.1). The HoverInfo struct is the source of truth; the LSP renders it as Markdown for LSP Hover.contents.
Required rendering:
**[DeclarationKind]** `CanonicalPath`
meaning: <meaning>
Visibility: public | internal
Epistemic: draft | deprecated | … (if present)
Defined in: <file>:<line>
For HoverInfo.model_info (model declarations), additionally render:
Provider: <provider> · Name: <name> · Pin: <digest/version>
Roles: <roles> · Reachable: ✓ / ✗
For HoverInfo.rule_info (rule "..." lines), additionally render:
Compiled expression: <expr or "pending compilation">
Cache: <status> · Compiled by: <model@digest template:version>
5.3 textDocument/definition
Go-to-definition MUST resolve:
- Any
QUALIFIEDreference to its declaration site import "..."path to the target filemodel: ModelNameto themodeldeclarationwith ModelNamein aruleorpromptstatement to themodeldeclaration- Flow state names (e.g.,
Activein-> Active by Employee) to thestates [...]list in theflowdeclaration
5.4 textDocument/references
Find-all-references MUST return all sites where a declaration is referenced, including:
is,includes,flow,applies to,mustSatisfyreferences- Import references across files
@FacetNamedecorator references (RFC-0011)model:andwith ModelNamereferences
5.5 textDocument/diagnostics
The LSP MUST serve diagnostics from CompilerSession.diagnostics(file) (RFC-0018 §13). Diagnostics MUST use M-codes defined in RFC-0008 §13, F-codes defined in RFC-0012 §8, and L-codes defined in RFC-0017 §10. The LSP MUST NOT suppress or remap them.
Update cadence:
textDocument/didChange→ trigger reanalysis after 300ms debounce; push updated diagnosticstextDocument/didSave→ trigger synchronoussession.flush()then push
Rule compiler diagnostics are asynchronous (the model call is non-blocking). The LSP maps CacheStatus to diagnostics:
| CacheStatus | LSP diagnostic |
|---|---|
Pending | hint “Rule pending compilation” |
Hit | no diagnostic (compilation succeeded) |
Stale | hint L0022 “Rule cache stale — recompiling (model digest changed)” |
Miss | hint “Rule not yet compiled — no rule compiler configured” (if M08791) or “Rule pending first compilation” |
Unresolvable | error M08792 with reason text |
Misclassified | warning M08793 with suggested destination |
ModelUnavailable | warning L0020 |
Rule diagnostics MUST be updated when compilation completes (the LSP subscribes to a compiler session notification, or polls on a 500ms interval while any rule is Pending).
5.6 textDocument/formatting
MUST apply gnomon fmt formatting semantics to the current file. The output MUST be identical to gnomon fmt CLI output on the same file. The LSP MUST call the gnomon-compiler library’s formatting entry point directly (RFC-0018 §4) — not spawn a subprocess — to avoid per-keystroke process overhead. The library interface is the single implementation; the CLI is a thin wrapper over it.
5.7 textDocument/codeAction
MUST offer fix suggestions for:
| Diagnostic | Code action |
|---|---|
M08702: missing meaning | “Add meaning field” — inserts meaning: "" with cursor inside the string |
| M08740: wrong casing | “Rename to <correct-casing>” — renames declaration and all references |
| M08790: bare natural-language line | “Convert to rule \"...\"” — wraps the line in rule "..." |
| M08791: uncompiled rule, no model | “Configure rule compiler in project.gnm” — inserts compiler { ruleCompiler: ... } stub |
| M08793: misclassified rule | “Move to policy declaration” or “Move to flow rules” |
| M08795: model missing version pin | “Add digest or version field” |
| M08780: draft reference warning | “Mark referencing declaration as draft” |
6. Rule Compiler Presentation
The rule compiler feedback loop is the primary interactive feature of the LSP. It surfaces the output of the rule compiler service (RFC-0018 §10) to the author inline during editing. This section specifies the LSP presentation layer only — model invocation, caching, and the //compiled: commit format are defined in RFC-0018.
6.1 Trigger
The feedback loop is triggered when:
- An author writes or modifies a
rule "..."statement CompilerSession.rule_cache_status(rule_text)returnsMiss,Stale, orPending
The LSP calls CompilerSession.compile_rule(...) asynchronously (RFC-0018 §10.2). This MUST NOT block any other LSP operation.
6.2 Ghost annotation (InlayHint)
The LSP MUST display an InlayHint immediately after the rule "..." line, reflecting the current CacheStatus:
| Cache status | Ghost annotation |
|---|---|
Pending | ⟩ compiling… |
Hit { user_edited: false } | ⟩ <compiled expression> |
Hit { user_edited: true } | ⟩ <compiled expression> [edited] |
Stale | ⟩ <stale expression> ⚠ stale — recompiling |
Miss | ⟩ pending first compilation |
Unresolvable | ⟩ ⚠ UNRESOLVABLE: <reason> |
Misclassified | ⟩ ⚠ <AuthorizationRule | LifecycleRule | Advisory>: move to <policy | flow> |
ModelUnavailable | ⟩ ✗ model unavailable: <reason> |
Ghost annotations are InlayHint items with kind: Type and paddingLeft: true. They MUST be visually distinct from authored source text (editors render them dimmed by convention).
6.3 Code actions on rule "..." lines
The LSP MUST offer the following code actions on any rule "..." line:
When CacheStatus is Hit:
-
“Commit compiled expression” — writes
//compiled:and//compiled-by:structured comments into the source file immediately after therule "..."line (see RFC-0018 §10.5). Provides offline reproducibility without re-invoking the LLM. -
“Convert to
expr { }” — replaces the entirerule "..."line (and any existing//compiled:comment) with anexpr { <expression> }block. This permanently removes the LLM dependency for this constraint. -
“Edit compiled expression” — opens an inline edit widget at the ghost annotation position, pre-filled with the compiled expression. On confirm, the modified expression is stored as a
//compiled:comment withuser-edited: true(RFC-0018 §10.5). Auser-edited: trueentry is never evicted from cache.
When CacheStatus is Unresolvable:
- “Add missing field” — if the UNRESOLVABLE reason names a missing field, inserts a stub
field-declin the appropriate entity declaration.
When CacheStatus is Misclassified as AuthorizationRule:
- “Move to policy declaration” — creates a new
policydeclaration stub with the rule text, or appends to an existing policy if one targets the same entity.
When CacheStatus is Misclassified as LifecycleRule:
- “Move to flow rules” — appends the rule to the
rulesblock of the appropriateflowdeclaration.
6.4 Debounce
Rule compilation is triggered after the author stops typing, with a debounce window of 1500ms (longer than the 300ms diagnostic debounce, to avoid excessive model calls during active typing). The debounce resets on each keystroke inside the rule "..." string.
7. textDocument/semanticTokens
The LSP SHOULD implement semantic token highlighting. Token types MUST include:
| Token | Semantic type |
|---|---|
Declaration keywords (entity, facet, flow, agent, etc.) | keyword |
| Declaration names | type or class |
Property keys (meaning, includes, flow, mustSatisfy, etc.) | property |
rule "..." text strings | string with modifier compilation-pending or compilation-ok or compilation-error |
prompt "..." text strings | string with modifier runtime-prompt |
note "..." text strings | comment |
expr { } content | operator / variable per expression token |
Model references (model: GPT4o) | class |
Epistemic modifiers (draft, deprecated, etc.) | modifier |
8. workspace/symbol
The LSP MUST implement workspace/symbol returning all top-level declarations in the project, grouped by kind. Each symbol MUST include its canonical path, file location, and meaning field (truncated to 80 characters).
9. Rename (textDocument/rename)
The LSP MUST implement rename for:
- Declaration names (renames declaration and all references across the project)
- Flow state names (renames state in
states [...]list and all->transition references) - Model names (renames model declaration and all
model:andwithreferences)
Rename MUST validate that the new name satisfies the casing convention for the declaration kind (RFC-0008 §10.3) and produce a pre-rename warning if it does not.
Diagnostics
The diagnostic catalog for this RFC is authored in the structured Lean module and
rendered in reference catalog § Diagnostics. Inline mentions in
the prose above (e.g., “rejected with MNNxxx”) cross-link to the catalog
at render time.
11. Security
- The LSP MUST NOT execute any code from
.gnmsource files. It is a read-only analysis tool. - The LSP MUST NOT invoke any model not declared in the project’s symbol table. It MUST NOT use a model URI constructed from user input.
- The
.gnomon-cache/directory MUST NOT be used to store credentials, tokens, or any data other than rule compilation cache entries. - When invoking Ollama or OpenAI APIs, the LSP MUST use the credentials from the standard provider configuration (Ollama: no credentials needed for localhost; OpenAI:
OPENAI_API_KEYenvironment variable). The LSP MUST NOT store or transmit credentials. - Rule text from
.gnmfiles is sent to the configured model for compilation. Authors MUST be aware that rule text is transmitted to the model provider. The LSP SHOULD display a one-time notice on first model invocation.