# Language server protocol

Describes Keryn 0.5.2 and keryn-rules 0.8.0.

> keryn lsp --stdio: the protocol for editor plugin authors.

Source: https://keryn.dev/docs/reference/lsp/

Audience: authors of editor plugins (JetBrains, Zed, Neovim, Helix, Sublime, anything with an LSP client).

## Launch

```
keryn lsp --stdio
```

* Transport: stdio, standard LSP framing (`Content-Length: N\r\n\r\n` + UTF-8 JSON-RPC 2.0). stdout carries **only** framed messages; stderr is silent in normal operation, except one line at start-up when the installation has no Deep engine (`keryn lsp: Deep unavailable (<reason>); Keryn pattern rules only`).
* No network access, ever. No telemetry.
* Requires Node.js 22 or later for the npm package; the single binary and the container need nothing else.
* Exit code: `0` after `shutdown` + `exit` (or stdin EOF), `1` for `exit` without `shutdown` or a framing error, `2` for bad arguments.
* Languages to attach to: none are required. The server analyses the whole workspace (Python, TypeScript/JavaScript, Java, C#, Rust, PHP, Go, Kotlin, Swift, Ruby, C, C++, Scala, Solidity, OCaml, Bash sources, Dockerfiles, JSON/YAML configuration, Terraform, `package.json`, `requirements*.txt`, etc.), so register it for every file type you want diagnostics in, or attach it per project root without a file-type filter.

## Lifecycle and capabilities

Standard `initialize` / `initialized` / `shutdown` / `exit`. The workspace root is `workspaceFolders[0].uri`, else `rootUri`, else `rootPath`; one root per server process (start one server per project). Requests before `initialize` fail with `-32002`.

`initialize` result:

```json
{
  "capabilities": {
    "positionEncoding": "utf-16",
    "textDocumentSync": {"openClose": true, "change": 1, "save": {"includeText": false}},
    "executeCommandProvider": {"commands": ["keryn.scan", "keryn.aibom"]},
    "codeActionProvider": {"codeActionKinds": ["quickfix"]},
    "experimental": {"keryn": {"protocol": 1, "requests": ["keryn/aibom", "keryn/sarif", "keryn/bundle", "keryn/scan"], "notifications": ["keryn/scanFinished"]}}
  },
  "serverInfo": {"name": "keryn", "version": "0.0.1 (keryn-scout-engine/0.1.0 ...)"}
}
```

`initializationOptions` (all optional):

| Option | Default | Meaning |
|---|---|---|
| `diagnostics` | `"workspace"` | `"workspace"`: publish diagnostics for every file with a hit. `"open"`: only for open documents. |
| `scanOnStart` | `true` | Scan once after `initialized`. |
| `debounceMs` | `400` | Delay after `didChange`/watched-file events before rescanning. |
| `deltaBase` | `""` | Base every automatic scan diffs against (VS Code `keryn.delta.base`): `""` = none, `"merge-base"`, a git ref or a CycloneDX `.json` path. Order: the request's `base`, then `deltaBase`, then `.keryn.yml` `base`. Changed later with `workspace/didChangeConfiguration {"settings": {"keryn": {"deltaBase": "..."}}}`. |
| `deep` | `true` | Run Deep (the Rust engine compiled to WASM) after Keryn pattern analysis on every scan, when the server has it; see "Deep" below. Changed later with `workspace/didChangeConfiguration {"settings": {"keryn": {"deep": false}}}`. |
| `symlinks` | `"skip"` | Reserved; symlinks are skipped (never followed outside the root). |

Text sync is **full** (`change: 1`): send the whole document in `contentChanges[0].text`. Positions are UTF-16 code units (the only encoding offered).

## Diagnostics

Source: `textDocument/publishDiagnostics`, pushed per file URI after every scan; superseded scans are discarded, and files that stop having hits receive an empty array.

| Field | Value |
|---|---|
| `source` | `"keryn"` |
| `code` | the rule id (`keryn.inv.lib.openai`) or policy rule id (`approved-llm-providers`) |
| `message` | rule message / policy violation text, always citing the component |
| `severity` | Semgrep `ERROR`->1 Error, `WARNING`->2 Warning, `INFO`->3 Information; policy `error/warning/info` likewise |
| `range` | rule findings: exact start/end (0-based line, UTF-16 character). Policy violations: the evidence line, full line width. Deep findings without a line (`metadata.granularity: "file"`) sit at the top of their file and their message ends in ` (file-level finding)`. |
| `relatedInformation` | the finding's flow, when the engine has one: the taint source (`"taint source"`), and for a finding proven at rung 3 or higher every hop (`"flow step N (<text>)"`), each a clickable location. |

Every finding's message ends in ` [proof N: <rung>]`, the proof-ladder rung it is proven at (0 inventory .. 5 reproduced; independent of the rule's confidence tier), then the rule ids keryn-core folded into it, if any. Deep findings carry the code `seceng/<findingClass>`.

Inventory rules (the AI-BOM pack) report **Information**-level diagnostics: "this line references component X". Policy violations are Error/Warning according to the policy file. Editors that show Information noisily can filter on `source == "keryn"` and `severity <= 2`.

Scans cover the on-disk tree **overlaid with the editor's unsaved buffers** (`didOpen`/`didChange`), honouring `.keryn.yml` in the root (rules, policy, include/exclude, limits). A broken `.keryn.yml` raises one `window/showMessage` (type Error) and the default configuration is used until it is fixed.

## Custom requests

All custom methods require `initialize` first. Parameters are ignored today (reserved: send `{}`).

### Deep (Keryn pattern analysis first, Deep merged)

The server runs Deep itself (there is no request for it). Every scan runs Keryn pattern analysis, then its facts
(`keryn.dev/ir-facts/v1`), then the Rust engine compiled to WASM, then the D-4 merge rule (a Deep pattern hit is dropped where a
Keryn pattern rule of the same class already reports in that file), then the same collapse, roles, suppression and keryn-core identity as
the pattern findings. Deep findings have `engine: "seceng"`, the code `seceng/<findingClass>`, `metadata.granularity: "file" | "line"`,
and a `proof` rung and `trace` like every other finding. Deep starts 1.5 s after pattern analysis finishes, and a rescan aborts a running Deep,
so typing never queues one Deep run per keystroke.

A client sees two publishes per scan: pattern diagnostics as soon as Keryn pattern analysis is done, with a `keryn/scanFinished` carrying
`deepPending: true`, then the whole report (Keryn pattern analysis + Deep) replacing them, with the final `keryn/scanFinished`. `keryn/aibom`,
`keryn/sarif` and `keryn/bundle` wait for the whole report. The summary gains `deep: {returned, kept, shadowed, corroborated, noPath, ms, error?}`
(`corroborated`: pattern findings Deep proved a flow to, whose message ends "confirmed by Deep"; `noPath`: flow-dependent pattern findings
Deep found no flow to, published at Information severity with "needs review: Deep found no data flow to it");
`error` means the Deep run failed and the pattern findings stand (the scan never fails because of Deep). `deep: false` in
`initializationOptions`, or `workspace/didChangeConfiguration {"settings": {"keryn": {"deep": false}}}`, makes every scan Keryn pattern analysis without Deep
(one publish, no `deep` in the summary); so does an installation without the Deep engine (one stderr line at start-up).

`keryn/deepFindings` (a client pushing Deep's JSON findings into the server) was removed with this change without a protocol bump:
no client outside this repository used it, and the 0.3.1 VS Code extension that did is replaced together with its server. A
client that still sends it gets `-32601`.

### `keryn/aibom` (request)

Returns the **CycloneDX 1.6 BOM object** for the workspace as it is now (it waits for a pending debounced rescan, so it reflects unsaved buffers). The BOM validates against the CycloneDX 1.6 JSON schema; its timestamp is the fixed epoch `1970-01-01T00:00:00Z`, so identical inputs give identical bytes. Coverage statement and the "absence is not evidence of absence" caveat are in `metadata.properties` (`keryn:coverage.rules`, `keryn:coverage.files`, `keryn:caveat`). Component evidence is in `components[].evidence.occurrences[]` (`location`, `line`); services carry `keryn:occurrences` (`path:line;...`).

### `keryn/sarif` (request)

Returns the **SARIF 2.1.0 log object** of the current report: exactly what `keryn scan --sarif` writes (driver `keryn-scout`, `partialFingerprints["keryn/fingerprint/v1"]`, suppressed results with `suppressions`, taint `codeFlows`). Inventory-only findings are not SARIF results.

### `keryn/bundle` (request)

`params: {timestamp?: string}` (RFC 3339). Returns the **evidence bundle** (`seceng.evidence_bundle.v2`) that keryn-core builds from the result document, the SARIF and the CycloneDX of the current report: a SHA256SUMS over the embedded documents and a content digest on every anchored finding. Given the same `timestamp` the bytes are identical; without one `createdAt` is the server's clock. A `timestamp` that does not parse is `-32602`. `keryn verify-bundle <file>` checks a saved bundle.

### `textDocument/codeAction` (request)

For every diagnostic in `context.diagnostics` that is a rule finding of the current report (same `code`, same first line; policy diagnostics and file-level Deep findings are skipped) the server returns one `quickfix` titled `Suppress with nosemgrep: <ruleId>` whose `edit` inserts the language's `nosemgrep: <ids>` comment on the line above the finding at its indentation. The comment lists the rules keryn-core collapsed into the finding (`alsoMatched`) too, so the next scan drops all of them into `suppressed`.

### `keryn/scan` (request) and `workspace/executeCommand`

`keryn/scan` and `workspace/executeCommand {command: "keryn.scan"}` force a fresh scan, publish diagnostics, and return the summary:

```json
{"subject": "my-repo", "components": 13, "findings": 16, "violations": 3, "policyPass": false,
 "core": "keryn-core/0.3.1", "fingerprints": {"n": 16, "sha256": "…"},
 "coverage": "29/29 rules executed (0 unsupported, 0 partial, 0 timed out); 4 files scanned, 0 skipped.",
 "complete": true, "deep": {"returned": 3, "kept": 2, "shadowed": 1, "ms": 1810}, "elapsedMs": 42}
```

`core` is the keryn-core version that fingerprinted the scan and `fingerprints` the count and SHA-256 of the sorted fingerprints
(what the cross-shell receipts compare); `deep` is present only when Deep ran (see "Deep").

`workspace/executeCommand {command: "keryn.aibom"}` returns the same BOM as `keryn/aibom`. Unknown commands fail with `-32602`; unknown methods with `-32601`.

### Diff against a base (`keryn/scan {base}`, `.keryn.yml` `base`)

`keryn/scan` accepts `{"base": "<git ref | path/to/bom.json>"}`. The server reads the ref from the **local** clone (never
fetches; a shallow clone yields a logged `window/logMessage` and the scan runs without a diff) or the CycloneDX file inside
the workspace, scans the base with the same rules, and the summary gains

```json
"diff": {"components": {"added": [{"key": "library:ollama", "kind": "library", "name": "ollama", "category": "local-inference"}], "removed": []}, "findings": {"added": 1, "removed": 0}}
```

Findings the base did not have are published with their message prefixed `[new] `, so an editor's Problems view shows
what this change introduced. A base of `merge-base` is resolved by the server: the common ancestor of HEAD and origin's default branch
(`refs/remotes/origin/HEAD`, else `origin/main`, `origin/master`, `main`, `master`; local refs only, nothing fetched; none found = a logged
`window/logMessage` and no diff). `components.changed` (prompts and models whose content or id changed, T5 WP7) is
`[{"key", "change": "prompt|model", "reason", "name", "from", "riskScore"?}]`, and `findings.items` lists the added findings (at most 500;
`findings.added` is the full count), in report order:

```json
"findings": {"added": 1, "removed": 0, "items": [{"id": "<keryn-fp/v1 fingerprint>", "ruleId": "...", "path": "src/a.py", "line": 12, "endLine": 12, "severity": "error", "message": "...", "proof": "proof 3 (path-cross-file)"}]}
```

`id` is the finding's identity (its fingerprint, else rule + file + matched text); `line`/`endLine` are 1-based; `proof` is the shared
`proofText` line and is absent without a proof. `.keryn.yml` `base:` makes every automatic scan a diff. VS Code: "Keryn: AI components added
by this change"; the **Keryn change** Explorer view (`keryn.delta`, shown while `keryn.delta.base` is set) lists components added / removed / changed, the added findings and prompt / model changes.

### `keryn/scanFinished` (notification, server -> client)

Sent after every published scan with the same summary object as above; when Deep runs, once after the pattern-analysis publish with `deepPending: true` and once with the whole report. Use it for a status-bar item ("13 AI components, 3 violations · Deep 2") and to refresh a BOM view by then calling `keryn/aibom`.

## Notifications the server handles

`textDocument/didOpen`, `didChange`, `didSave`, `didClose`, `workspace/didChangeWatchedFiles`, `workspace/didChangeConfiguration` (rescan; a boolean `settings.keryn.deep` switches Deep), `initialized`, `exit`. Anything else (including `$/...`) is ignored.

## Errors

JSON-RPC error objects `{code, message}`: `-32002` not initialized, `-32601` method not found, `-32602` invalid params (bad command, no workspace root, workspace cannot be opened), `-32603` internal (scan failed; also logged via `window/logMessage` type 1). Scan failures never kill the server.

## Minimal client recipes

Neovim (0.10+):

```lua
vim.lsp.start({
  name = 'keryn',
  cmd = {'node', '/path/to/keryn/bin/keryn.mjs', 'lsp', '--stdio'},   -- or {'keryn', 'lsp', '--stdio'} once packaged
  root_dir = vim.fs.root(0, {'.keryn.yml', '.git'}),
  init_options = {diagnostics = 'workspace'},
})
-- BOM: vim.lsp.get_clients({name = 'keryn'})[1].request_sync('keryn/aibom', {}, 20000)
```

Helix `languages.toml`:

```toml
[language-server.keryn]
command = "keryn"
args = ["lsp", "--stdio"]
```

Zed (extension `language_server_command`) and Sublime LSP (`"command": ["keryn", "lsp", "--stdio"]`, `"selector": "source"`) are the same command line. JetBrains (2023.2+ LSP API / LSP4IJ): `ProjectWizardServerDescriptor` with `GeneralCommandLine("keryn", "lsp", "--stdio")`; for the BOM tool window send the custom request `keryn/aibom` through the plugin's LSP request API.

## Compatibility promise

The shapes above are protocol version **1** (`experimental.keryn.protocol`). New optional fields and new methods may appear; existing ones change only with a protocol bump, announced in the same `experimental.keryn` capability.
