gnomonlearn

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

  1. Every LSP capability is derived from the semantic model — completions come from the symbol table, hover from meaning fields, diagnostics from the same compiler that validates bundles
  2. The rule compiler feedback loop is interactive and non-blocking — authors write natural language and see the compiled constraint expression inline before accepting it
  3. Model declarations are first-class LSP citizens — the LSP can resolve, validate, and preview model bindings at authoring time
  4. The LSP contract is implementable without a full production compiler — a partial implementation can satisfy individual capabilities incrementally
  5. 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

  1. 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.
  2. 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.
  3. 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.
  4. The LSP MUST use the compiler.ruleCompiler model from project.gnm when available. It MUST NOT invoke a model not declared in the project.
  5. LSP diagnostics MUST use the same diagnostic codes (M0xxxx, F1xxxx) as the compiler. Custom LSP-only error codes are forbidden.
  6. The LSP MUST apply gnomon fmt formatting semantics for textDocument/formatting — it MUST produce output identical to gnomon fmt on 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:

  1. Locate project.gnm by walking up from the root URI
  2. Load the full symbol table for the project (all .gnm files reachable from project.gnm)
  3. Load the compiler block from project.gnm to determine the rule compiler model and template version
  4. Report the capabilities listed in §5 in the ServerCapabilities response

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:

  1. The ParseContext at the cursor position (RFC-0018 §6) — determines what kind of value is valid here
  2. The ScopeInfo.visible_symbols filtered by the IdentSetFilter for the current context (RFC-0018 §7.1)
  3. The PropertyRegistry for 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.detail
  • CompletionCandidate.documentation → CompletionItem.documentation (MarkupContent)
  • CompletionCandidate.insert_text → CompletionItem.insertText (snippet format)
  • Required properties (PropertySpec.required = true) → CompletionItem.sortText prefixed 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 QUALIFIED reference to its declaration site
  • import "..." path to the target file
  • model: ModelName to the model declaration
  • with ModelName in a rule or prompt statement to the model declaration
  • Flow state names (e.g., Active in -> Active by Employee) to the states [...] list in the flow declaration

5.4 textDocument/references

Find-all-references MUST return all sites where a declaration is referenced, including:

  • is, includes, flow, applies to, mustSatisfy references
  • Import references across files
  • @FacetName decorator references (RFC-0011)
  • model: and with ModelName references

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 diagnostics
  • textDocument/didSave → trigger synchronous session.flush() then push

Rule compiler diagnostics are asynchronous (the model call is non-blocking). The LSP maps CacheStatus to diagnostics:

CacheStatusLSP diagnostic
Pendinghint “Rule pending compilation”
Hitno diagnostic (compilation succeeded)
Stalehint L0022 “Rule cache stale — recompiling (model digest changed)”
Misshint “Rule not yet compiled — no rule compiler configured” (if M08791) or “Rule pending first compilation”
Unresolvableerror M08792 with reason text
Misclassifiedwarning M08793 with suggested destination
ModelUnavailablewarning 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:

DiagnosticCode 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:

  1. An author writes or modifies a rule "..." statement
  2. CompilerSession.rule_cache_status(rule_text) returns Miss, Stale, or Pending

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 statusGhost 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:

  1. “Commit compiled expression” — writes //compiled: and //compiled-by: structured comments into the source file immediately after the rule "..." line (see RFC-0018 §10.5). Provides offline reproducibility without re-invoking the LLM.

  2. “Convert to expr { }” — replaces the entire rule "..." line (and any existing //compiled: comment) with an expr { <expression> } block. This permanently removes the LLM dependency for this constraint.

  3. “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 with user-edited: true (RFC-0018 §10.5). A user-edited: true entry is never evicted from cache.

When CacheStatus is Unresolvable:

  1. “Add missing field” — if the UNRESOLVABLE reason names a missing field, inserts a stub field-decl in the appropriate entity declaration.

When CacheStatus is Misclassified as AuthorizationRule:

  1. “Move to policy declaration” — creates a new policy declaration stub with the rule text, or appends to an existing policy if one targets the same entity.

When CacheStatus is Misclassified as LifecycleRule:

  1. “Move to flow rules” — appends the rule to the rules block of the appropriate flow declaration.

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:

TokenSemantic type
Declaration keywords (entity, facet, flow, agent, etc.)keyword
Declaration namestype or class
Property keys (meaning, includes, flow, mustSatisfy, etc.)property
rule "..." text stringsstring with modifier compilation-pending or compilation-ok or compilation-error
prompt "..." text stringsstring with modifier runtime-prompt
note "..." text stringscomment
expr { } contentoperator / 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: and with references)

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

  1. The LSP MUST NOT execute any code from .gnm source files. It is a read-only analysis tool.
  2. 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.
  3. The .gnomon-cache/ directory MUST NOT be used to store credentials, tokens, or any data other than rule compilation cache entries.
  4. 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_KEY environment variable). The LSP MUST NOT store or transmit credentials.
  5. Rule text from .gnm files 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.