@telorun/editor-protocol 0.1.0

package/LICENSE

@@ -0,0 +1,17 @@
+# SUSTAINABLE USE LICENSE (Fair-code)
+
+Copyright (c) 2026 CodeNet Sp. z o.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to use, copy, modify, and distribute the Software for any purpose—including commercial purposes—subject to the following conditions:
+
+1. ANTI-COMPETITION RESTRICTION: The Software may not be provided to third parties as a managed service, commercial SaaS (Software-as-a-Service), PaaS (Platform-as-a-Service), BaaS (Backend-as-a-Service), or similar offering where the primary value provided to the user is the functionality of the Software itself, without a separate commercial license from the copyright holder.
+
+2. PERMITTED COMMERCIAL USE: You are free to use the Software to build, host, and monetize your own commercial applications, products, and services, provided such use does not violate Clause 1.
+
+3. ATTRIBUTION: This copyright notice and license must be included in all copies or substantial portions of the Software.
+
+4. CONTRIBUTIONS: Contributions to the Software are welcome and encouraged. By contributing, you agree that your contributions may be incorporated into the Software and distributed under this license.
+
+5. DISCLAIMER: The Software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the Software or the use or other dealings in the Software.
+
+For commercial licensing, managed hosting exemptions, or enterprise inquiries, please contact <contact@codenet.pl>.

package/README.md

@@ -0,0 +1,197 @@
+# @telorun/editor-protocol
+
+The contract between an **editor host** (VS Code, telo studio, any LSP client)
+and a **telo language-server engine** — the part of the conversation LSP itself
+does not define. An editor edits a module against one chosen telo version; that
+version's engine produces every diagnostic and language feature, and the host
+supplies everything the engine cannot do itself: files, imports, the hub.
+
+This README is the specification. The TypeScript types in `src/index.ts` and
+[`editor-protocol-schema.json`](./editor-protocol-schema.json) (for hosts written
+in other languages) are its projections; the package has no dependencies.
+
+## The engine
+
+Telo `X` publishes its engine as `@telorun/language-server@X`: one
+self-contained ES module, `dist/language-server.mjs`, with no imports. Its
+`package.json` declares `teloEditorProtocol`, the protocol generation the engine
+speaks — a host offers only versions whose generation it speaks.
+
+The module exports one entry:
+
+```ts
+serve(port: { postMessage(message): void; addEventListener("message", (event) => void): void }): void
+```
+
+`port` carries **LSP JSON-RPC message objects** (not framed text) in both
+directions; the engine reads each message from `event.data`. A Web Worker scope,
+a `MessagePort` and a Node `parentPort` adapted to `addEventListener` all fit.
+The host loads the module into a worker, calls `serve(self)` there, and speaks
+LSP to the worker.
+
+**The engine performs no I/O of its own** — no `fetch`, no filesystem. Every
+byte it reads arrives through the `telo/*` requests below, which is what lets one
+build run in a browser, a desktop app and an extension host alike, and what
+leaves transports, credentials, caches and integrity checks with the host.
+
+## Handshake
+
+The host sends a standard `initialize`. The engine answers:
+
+- `serverInfo: { name: "telo", version: "<identity>" }` — the engine's
+  **identity**. For a release build it is `X`, the telo version the engine
+  implements (the surface generation `requires: telo:` ranges are written
+  against) and exactly the version of the `@telorun/language-server` package it
+  was published as. A build made while that release is still pending — a
+  development checkout, a main-branch deployment — reports `X+unreleased`: it
+  implements `X` but is not the `X` that will be published, so it never shares
+  an identity with a published engine. A host orders identities and tests them
+  against `requires: telo:` intervals by semver precedence (build metadata
+  ignored), and tells engines apart by the whole string.
+- `capabilities.experimental.telo.protocol: 1` — the generation it speaks.
+- The standard capabilities it serves: full text sync, completion, hover,
+  definition, rename with `prepareRename`, signature help, `semanticTokens/full`
+  (the legend is in the capabilities), `codeAction` (quick fixes),
+  `codeLens`, and `workspace/executeCommand` for the commands below.
+
+A host verifies every handshake: `serverInfo.name` is `telo`, the protocol is a
+generation the host speaks, and an engine the host downloaded as version `X`
+reports exactly `X`. An engine failing any of these is refused, not run.
+
+The engine reads the client's `workspace.codeLens.refreshSupport`,
+`workspace.semanticTokens.refreshSupport` and
+`workspace.didChangeWatchedFiles.dynamicRegistration` capabilities; with the
+last it registers a watcher for `**/*.yaml` and re-analyses what a changed file
+feeds.
+
+## URIs
+
+Documents are `file:` URIs; a remote module is named by its import source as
+written (`oci://host/repo@1.2.0`, `https://…`). One `file:` location has many
+spellings, so the protocol fixes **one canonical form** and identity is
+equality of canonical forms:
+
+- there is no query and no fragment;
+- a local file has an empty authority (`file:///…`; `file://localhost/…` is the
+  same location), and a file on a UNC share has the share's host as its
+  authority, ASCII-lowercased and percent-encoded like a path segment —
+  `\\ServerA\share\x` is `file://servera/share/x`, and the four-slash
+  spelling `file:////ServerA/share/x` folds to that same form;
+- the path is its UTF-8 bytes, each percent-encoded except the unreserved
+  characters `A–Z a–z 0–9 - . _ ~` and `/`, with uppercase hex digits —
+  `My Project (copy)` is `My%20Project%20%28copy%29`;
+- a local Windows drive is written `/<lowercase letter>%3A/` — `C:\Users\u` is
+  `file:///c%3A/Users/u`; the drive rule does not apply under a UNC host.
+
+An engine emits every `file:` URI in canonical form. A host compares URIs only
+by their canonical forms — a document the editor opened under another spelling
+of the same location is the same document — and does not rewrite the URIs in
+the messages it passes along.
+
+## Host-served requests (engine → host)
+
+A relative path is resolved against the **directory of the file** its `base`
+names.
+
+| Method | Params | Result |
+| --- | --- | --- |
+| `telo/read` | `{ uri }` | `{ uri, text }` — the text and the **canonical** location it was read from: a directory resolves to its `telo.yaml` (`TELO_MODULE_FILENAME`), an `oci://` tag to the reference the host resolved — or `null` when nothing exists at `uri`. |
+| `telo/exists` | `{ base, relative }` | `boolean` — whether a file or directory exists there. |
+| `telo/listDirectory` | `{ uri }` | `[{ name, kind }]`, or `null` when `uri` names nothing or a file. `kind` is `file`, `directory`, `symlink` or `other`, read without following links — a symbolic link is `symlink` whatever it points at. |
+| `telo/hub/searchRefs` | `{ query }` | `[{ ref, latestVersion, description? }]` — refs the configured hub matches `query` against. |
+| `telo/hub/listVersions` | `{ ref }` | `[{ version, integrity? }]`, newest first; `[]` for a ref the hub does not track. |
+
+Any other failure — an unreachable registry, a hub that did not answer, a
+permission error — is a **JSON-RPC error** carrying its reason, never a silent
+`null`: the engine reports it (a load failure becomes a diagnostic; a failed hub
+lookup is logged through `window/logMessage` and, where a user asked for it,
+shown). Hub lookups feed completion and upgrade lenses only.
+
+The engine expands `include:` globs itself, by walking `telo/listDirectory`
+from the including file's directory — collecting `file` entries and descending
+into `directory` ones, never through a link, as the kernel does — so a host
+serves directories, never patterns, and every host matches a glob exactly as the
+kernel does. `telo/read` and `telo/exists` do follow links.
+
+Remote modules are read through `telo/read` like any document: the host owns
+the transport (`oci://`, `https://`, a manifest cache) and any integrity check.
+A candidate version an import upgrade considers is read as its versioned ref
+(`oci://host/repo@1.3.0`).
+
+## `telo/requirements` (engine → host notification)
+
+Sent after each analysis of an **owner module** — a `telo.yaml`, or a manifest
+analysed standalone:
+
+```json
+{
+  "owner": "file:///ws/app/telo.yaml",
+  "documents": ["file:///ws/app/telo.yaml", "file:///ws/app/routes.yaml"],
+  "ranges": [
+    { "module": "file:///ws/app/telo.yaml", "text": ">=0.100.0",
+      "interval": { "min": { "version": "0.100.0", "inclusive": true } } },
+    { "module": "oci://ghcr.io/telorun/sql@0.25.0", "text": ">=0.90.0 <0.120.0",
+      "interval": { "min": { "version": "0.90.0", "inclusive": true },
+                    "max": { "version": "0.120.0", "inclusive": false } } }
+  ]
+}
+```
+
+- `owner` — the owner module's URI.
+- `documents` — the owner and every partial it includes. A host routes these
+  documents to the engine it chose for `owner`.
+- `ranges` — every `requires: telo:` range in the owner's import closure, one
+  per declaring module. The owner declares one exactly when an entry's `module`
+  equals `owner`. `interval` is the range reduced to its edges by the engine,
+  through the analyzer's own range reader; an absent edge is open. A host only
+  compares plain versions against it — it never parses a range.
+
+A range the analyzer refuses as malformed is reported as a diagnostic and does
+not appear here.
+
+## `Diagnostic.data`
+
+Every diagnostic the engine publishes may carry:
+
+```ts
+{ fix?: { replacement: string; tag?: "ref" | "cel" | "module-path" },
+  resource?: { kind: string; name: string },
+  path?: string }
+```
+
+`fix` is a mechanically applicable repair — the whole corrected value at the
+diagnostic's range, written behind the YAML tag `tag` when present. A host
+returns the diagnostic unchanged in a `textDocument/codeAction` request's
+context, and the engine answers with the quick fix that applies it. `resource`
+and `path` locate the offending value inside a manifest (a host may use them to
+place a diagnostic on a form field). `Diagnostic.tags` carries LSP's
+`Deprecated` / `Unnecessary`.
+
+## Commands
+
+| Command | Arguments | Effect |
+| --- | --- | --- |
+| `telo.upgradeImport` | `[{ uri, aliases }]` | Recomputes the document's import upgrades and applies those of `aliases` through `workspace/applyEdit`. |
+| `telo.upgradeAllImports` | `[{ uri, aliases }]` | Same, for every alias the summary lens named. |
+| `telo.refreshImportUpgrades` | — | Drops cached version lists and verdicts, then `workspace/codeLens/refresh`. |
+
+The engine's code lenses over an `imports:` block name the first two.
+
+## Generations
+
+`TELO_EDITOR_PROTOCOL` is the generation this package describes (`1`).
+**Additions within a generation are negotiated by capability**: a new request, a
+new optional field or a new command is advertised by the side that has it and
+used only when advertised, so an older host and a newer engine (or the reverse)
+keep working. **An incompatible change bumps the generation**: a host speaking
+generation `N` offers only engines whose `teloEditorProtocol` is `N`, and an
+engine refuses nothing — it simply is not selected.
+
+**A receiver must ignore what it does not know**, so that an addition within a
+generation never breaks the other side: a member it does not know is ignored,
+and an enumeration value it does not know is read as that enumeration's
+least-capable value — a `telo/listDirectory` entry `kind` as `other` (neither
+read as a file nor descended into), a `Diagnostic.data.fix.tag` as no fix
+offered. `editor-protocol-schema.json` is written the same way: its objects are
+open and its enumerations admit any string, so a message carrying a later
+addition still validates.

package/dist/index.d.ts

@@ -0,0 +1,159 @@
+/** The protocol generation this package describes. Additions within a
+ *  generation are negotiated by capability; an incompatible change bumps it. */
+export declare const TELO_EDITOR_PROTOCOL = 1;
+/** What an engine advertises under `ServerCapabilities.experimental`. */
+export interface TeloExperimentalCapabilities {
+    telo: TeloProtocolCapability;
+}
+export interface TeloProtocolCapability {
+    /** The generation the engine speaks. */
+    protocol: number;
+}
+/** The file a module directory is read as: `telo/read` of a directory answers
+ *  with this file inside it. */
+export declare const TELO_MODULE_FILENAME = "telo.yaml";
+/** `initialize`'s `serverInfo.name` for every telo engine. Its
+ *  `serverInfo.version` is the engine's identity: the telo version `X` for a
+ *  release build, `X+unreleased` for a build made while that release is still
+ *  pending. */
+export declare const TELO_SERVER_NAME = "telo";
+/** Method names of the requests an engine sends and a host serves, and of the
+ *  notification an engine sends. */
+export declare const TeloMethod: {
+    readonly read: "telo/read";
+    readonly exists: "telo/exists";
+    readonly listDirectory: "telo/listDirectory";
+    readonly hubSearchRefs: "telo/hub/searchRefs";
+    readonly hubListVersions: "telo/hub/listVersions";
+    readonly requirements: "telo/requirements";
+};
+export type TeloMethod = (typeof TeloMethod)[keyof typeof TeloMethod];
+/** `telo/read`: the text at `uri`. `uri` is a document URI (`file:///…`) or an
+ *  import source (`oci://host/repo@1.2.0`, `https://…`); the host reads it
+ *  through whatever transport it owns. */
+export interface ReadParams {
+    uri: string;
+}
+/** The text read, with the CANONICAL location it was read from — a directory
+ *  resolves to its {@link TELO_MODULE_FILENAME}, an `oci://` tag to the reference the host
+ *  resolved. `null` when nothing exists at `uri`; any other failure is a
+ *  JSON-RPC error carrying its reason. */
+export type ReadResult = {
+    uri: string;
+    text: string;
+} | null;
+/** `telo/exists`: whether a file or directory exists at `relative`, resolved
+ *  against the DIRECTORY of the file `base` names. */
+export interface ExistsParams {
+    base: string;
+    relative: string;
+}
+export type ExistsResult = boolean;
+/** `telo/listDirectory`: the entries of the directory at `uri`. */
+export interface ListDirectoryParams {
+    uri: string;
+}
+/** What a directory entry is, read WITHOUT following a link: a symbolic link
+ *  is `symlink` whatever it points at. A receiver reads a kind it does not know
+ *  as `other`. */
+export type DirectoryEntryKind = "file" | "directory" | "symlink" | "other";
+export interface DirectoryEntry {
+    name: string;
+    kind: DirectoryEntryKind;
+}
+/** `null` when `uri` names nothing or names a file. */
+export type ListDirectoryResult = DirectoryEntry[] | null;
+/** `telo/hub/searchRefs`: module refs the configured telo hub matches `query`
+ *  against (a substring over every registered ref). */
+export interface SearchRefsParams {
+    query: string;
+}
+export interface HubRef {
+    ref: string;
+    latestVersion: string;
+    description?: string;
+}
+export type SearchRefsResult = HubRef[];
+/** `telo/hub/listVersions`: every version the hub tracks for a location ref,
+ *  newest first, each with its import pin when the hub has one. `[]` for a ref
+ *  the hub does not track; an unreachable hub is a JSON-RPC error. */
+export interface ListVersionsParams {
+    ref: string;
+}
+export interface ModuleVersion {
+    version: string;
+    /** Canonical `sha256-<base64url>` pin. */
+    integrity?: string;
+}
+export type ListVersionsResult = ModuleVersion[];
+/** Params and result of every host-served request, by method. */
+export interface TeloHostRequests {
+    "telo/read": [ReadParams, ReadResult];
+    "telo/exists": [ExistsParams, ExistsResult];
+    "telo/listDirectory": [ListDirectoryParams, ListDirectoryResult];
+    "telo/hub/searchRefs": [SearchRefsParams, SearchRefsResult];
+    "telo/hub/listVersions": [ListVersionsParams, ListVersionsResult];
+}
+/** One edge of a version interval. */
+export interface VersionBound {
+    version: string;
+    inclusive: boolean;
+}
+/** A `requires: telo:` range reduced to its edges; an absent edge is open. */
+export interface VersionInterval {
+    min?: VersionBound;
+    max?: VersionBound;
+}
+export interface RequirementsRange {
+    /** URI of the module document declaring the range. */
+    module: string;
+    /** The range as written. */
+    text: string;
+    interval: VersionInterval;
+}
+/** `telo/requirements`: sent after each analysis of an owner module. */
+export interface RequirementsParams {
+    /** URI of the owner module's `telo.yaml` (or standalone manifest). */
+    owner: string;
+    /** URIs of the owner's member documents — the owner and every partial it
+     *  includes. A host routes these documents to the engine chosen for `owner`. */
+    documents: string[];
+    /** Every `requires: telo:` range in the owner's import closure. The owner
+     *  itself declares one exactly when an entry's `module` equals `owner`. */
+    ranges: RequirementsRange[];
+}
+/** The YAML tags a repair may write. A receiver that does not know a tag
+ *  offers no fix for it. */
+export type DiagnosticFixTag = "ref" | "cel" | "module-path";
+/** A mechanically applicable repair: the whole corrected value at the
+ *  diagnostic's range, written behind `tag` when one is present. */
+export interface DiagnosticFix {
+    replacement: string;
+    tag?: DiagnosticFixTag;
+}
+/** What an engine puts in `Diagnostic.data`. A host hands the diagnostic back
+ *  unchanged in `codeAction`'s context, which is how a fix round-trips. */
+export interface TeloDiagnosticData {
+    fix?: DiagnosticFix;
+    /** The resource the diagnostic is pinned to. */
+    resource?: {
+        kind: string;
+        name: string;
+    };
+    /** Dotted path of the offending value within that resource. */
+    path?: string;
+}
+/** `workspace/executeCommand` commands an engine serves. The two upgrade
+ *  commands take `[{ uri, aliases }]` and apply through `workspace/applyEdit`;
+ *  refresh takes no argument. */
+export declare const TeloCommand: {
+    readonly upgradeImport: "telo.upgradeImport";
+    readonly upgradeAllImports: "telo.upgradeAllImports";
+    readonly refreshImportUpgrades: "telo.refreshImportUpgrades";
+};
+export type TeloCommand = (typeof TeloCommand)[keyof typeof TeloCommand];
+export interface UpgradeImportsArguments {
+    uri: string;
+    aliases: string[];
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,34 @@
+// The Telo editor protocol: what an editor host and a telo language-server
+// engine say to each other beyond LSP itself. Zero dependencies and no runtime
+// beyond constants, so a host of any telo version — and a host in any language,
+// through `editor-protocol-schema.json` — can speak it. `README.md` is the spec.
+/** The protocol generation this package describes. Additions within a
+ *  generation are negotiated by capability; an incompatible change bumps it. */
+export const TELO_EDITOR_PROTOCOL = 1;
+/** The file a module directory is read as: `telo/read` of a directory answers
+ *  with this file inside it. */
+export const TELO_MODULE_FILENAME = "telo.yaml";
+/** `initialize`'s `serverInfo.name` for every telo engine. Its
+ *  `serverInfo.version` is the engine's identity: the telo version `X` for a
+ *  release build, `X+unreleased` for a build made while that release is still
+ *  pending. */
+export const TELO_SERVER_NAME = "telo";
+/** Method names of the requests an engine sends and a host serves, and of the
+ *  notification an engine sends. */
+export const TeloMethod = {
+    read: "telo/read",
+    exists: "telo/exists",
+    listDirectory: "telo/listDirectory",
+    hubSearchRefs: "telo/hub/searchRefs",
+    hubListVersions: "telo/hub/listVersions",
+    requirements: "telo/requirements",
+};
+// --- Commands --------------------------------------------------------------
+/** `workspace/executeCommand` commands an engine serves. The two upgrade
+ *  commands take `[{ uri, aliases }]` and apply through `workspace/applyEdit`;
+ *  refresh takes no argument. */
+export const TeloCommand = {
+    upgradeImport: "telo.upgradeImport",
+    upgradeAllImports: "telo.upgradeAllImports",
+    refreshImportUpgrades: "telo.refreshImportUpgrades",
+};

package/editor-protocol-schema.json

@@ -0,0 +1,373 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://telo.run/schemas/editor-protocol.json",
+  "title": "Telo editor protocol, generation 1",
+  "description": "The messages an editor host and a telo language-server engine exchange beyond LSP itself. Each host-served request (engine to host) has a `<Name>Params` and a `<Name>Result` definition; `RequirementsParams` is the engine-to-host `telo/requirements` notification; `TeloDiagnosticData` is what an engine puts in `Diagnostic.data`; `ExperimentalCapabilities` is what an engine advertises under `ServerCapabilities.experimental`. `x-telo-methods` maps each method name to its definitions. Objects are open and enumerations list the values known to this generation: a receiver ignores a member it does not know and reads an unknown enumeration value as its least-capable value (README.md, Generations). See README.md for the handshake and the generation rule.",
+  "x-telo-methods": {
+    "telo/read": {
+      "params": "#/$defs/ReadParams",
+      "result": "#/$defs/ReadResult"
+    },
+    "telo/exists": {
+      "params": "#/$defs/ExistsParams",
+      "result": "#/$defs/ExistsResult"
+    },
+    "telo/listDirectory": {
+      "params": "#/$defs/ListDirectoryParams",
+      "result": "#/$defs/ListDirectoryResult"
+    },
+    "telo/hub/searchRefs": {
+      "params": "#/$defs/SearchRefsParams",
+      "result": "#/$defs/SearchRefsResult"
+    },
+    "telo/hub/listVersions": {
+      "params": "#/$defs/ListVersionsParams",
+      "result": "#/$defs/ListVersionsResult"
+    },
+    "telo/requirements": {
+      "params": "#/$defs/RequirementsParams"
+    }
+  },
+  "$defs": {
+    "ExperimentalCapabilities": {
+      "type": "object",
+      "required": [
+        "telo"
+      ],
+      "properties": {
+        "telo": {
+          "type": "object",
+          "required": [
+            "protocol"
+          ],
+          "properties": {
+            "protocol": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "The protocol generation the engine speaks."
+            }
+          }
+        }
+      }
+    },
+    "ReadParams": {
+      "type": "object",
+      "required": [
+        "uri"
+      ],
+      "properties": {
+        "uri": {
+          "type": "string",
+          "description": "A document URI (`file:///…`) or an import source (`oci://…`, `https://…`)."
+        }
+      }
+    },
+    "ReadResult": {
+      "description": "The text and the canonical location it was read from (a directory resolves to its `telo.yaml`), or null when nothing exists at the URI.",
+      "oneOf": [
+        {
+          "type": "object",
+          "required": [
+            "uri",
+            "text"
+          ],
+          "properties": {
+            "uri": {
+              "type": "string"
+            },
+            "text": {
+              "type": "string"
+            }
+          }
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "ExistsParams": {
+      "type": "object",
+      "required": [
+        "base",
+        "relative"
+      ],
+      "properties": {
+        "base": {
+          "type": "string",
+          "description": "URI of a file; `relative` resolves against its directory."
+        },
+        "relative": {
+          "type": "string"
+        }
+      }
+    },
+    "ExistsResult": {
+      "type": "boolean"
+    },
+    "ListDirectoryParams": {
+      "type": "object",
+      "required": [
+        "uri"
+      ],
+      "properties": {
+        "uri": {
+          "type": "string"
+        }
+      }
+    },
+    "DirectoryEntry": {
+      "type": "object",
+      "required": [
+        "name",
+        "kind"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "kind": {
+          "description": "What the entry is, read without following a link: a symbolic link is `symlink` whatever it points at. A receiver reads a kind it does not know as `other`.",
+          "anyOf": [
+            {
+              "enum": [
+                "file",
+                "directory",
+                "symlink",
+                "other"
+              ]
+            },
+            {
+              "type": "string"
+            }
+          ]
+        }
+      }
+    },
+    "ListDirectoryResult": {
+      "description": "The entries, or null when the URI names nothing or names a file.",
+      "oneOf": [
+        {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/DirectoryEntry"
+          }
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "SearchRefsParams": {
+      "type": "object",
+      "required": [
+        "query"
+      ],
+      "properties": {
+        "query": {
+          "type": "string"
+        }
+      }
+    },
+    "HubRef": {
+      "type": "object",
+      "required": [
+        "ref",
+        "latestVersion"
+      ],
+      "properties": {
+        "ref": {
+          "type": "string"
+        },
+        "latestVersion": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        }
+      }
+    },
+    "SearchRefsResult": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/HubRef"
+      }
+    },
+    "ListVersionsParams": {
+      "type": "object",
+      "required": [
+        "ref"
+      ],
+      "properties": {
+        "ref": {
+          "type": "string"
+        }
+      }
+    },
+    "ModuleVersion": {
+      "type": "object",
+      "required": [
+        "version"
+      ],
+      "properties": {
+        "version": {
+          "type": "string"
+        },
+        "integrity": {
+          "type": "string",
+          "pattern": "^sha256-[A-Za-z0-9_-]{43}$",
+          "description": "Canonical import pin: `sha256-` and 43 base64url characters."
+        }
+      }
+    },
+    "ListVersionsResult": {
+      "description": "Newest first; empty for a ref the hub does not track.",
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/ModuleVersion"
+      }
+    },
+    "VersionBound": {
+      "type": "object",
+      "required": [
+        "version",
+        "inclusive"
+      ],
+      "properties": {
+        "version": {
+          "type": "string"
+        },
+        "inclusive": {
+          "type": "boolean"
+        }
+      }
+    },
+    "VersionInterval": {
+      "description": "A `requires: telo:` range reduced to its edges; an absent edge is open.",
+      "type": "object",
+      "properties": {
+        "min": {
+          "$ref": "#/$defs/VersionBound"
+        },
+        "max": {
+          "$ref": "#/$defs/VersionBound"
+        }
+      }
+    },
+    "RequirementsRange": {
+      "type": "object",
+      "required": [
+        "module",
+        "text",
+        "interval"
+      ],
+      "properties": {
+        "module": {
+          "type": "string",
+          "description": "URI of the module document declaring the range."
+        },
+        "text": {
+          "type": "string",
+          "description": "The range as written."
+        },
+        "interval": {
+          "$ref": "#/$defs/VersionInterval"
+        }
+      }
+    },
+    "RequirementsParams": {
+      "type": "object",
+      "required": [
+        "owner",
+        "documents",
+        "ranges"
+      ],
+      "properties": {
+        "owner": {
+          "type": "string"
+        },
+        "documents": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "ranges": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/RequirementsRange"
+          }
+        }
+      }
+    },
+    "DiagnosticFix": {
+      "type": "object",
+      "required": [
+        "replacement"
+      ],
+      "properties": {
+        "replacement": {
+          "type": "string"
+        },
+        "tag": {
+          "description": "The YAML tag the replacement is written behind. A receiver that does not know a tag offers no fix for it.",
+          "anyOf": [
+            {
+              "enum": [
+                "ref",
+                "cel",
+                "module-path"
+              ]
+            },
+            {
+              "type": "string"
+            }
+          ]
+        }
+      }
+    },
+    "TeloDiagnosticData": {
+      "type": "object",
+      "properties": {
+        "fix": {
+          "$ref": "#/$defs/DiagnosticFix"
+        },
+        "resource": {
+          "type": "object",
+          "required": [
+            "kind",
+            "name"
+          ],
+          "properties": {
+            "kind": {
+              "type": "string"
+            },
+            "name": {
+              "type": "string"
+            }
+          }
+        },
+        "path": {
+          "type": "string"
+        }
+      }
+    },
+    "UpgradeImportsArguments": {
+      "type": "object",
+      "required": [
+        "uri",
+        "aliases"
+      ],
+      "properties": {
+        "uri": {
+          "type": "string"
+        },
+        "aliases": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@telorun/editor-protocol",
+  "version": "0.1.0",
+  "description": "The Telo editor protocol: the contract between an editor host and a telo language-server engine — the telo/* requests, the telo/requirements notification and the protocol generation.",
+  "keywords": [
+    "telo",
+    "lsp",
+    "language-server",
+    "editor",
+    "protocol"
+  ],
+  "author": "Bartosz Pasiński <bartosz.pasinski@codenet.pl>",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/telorun/telo.git",
+    "directory": "packages/editor-protocol"
+  },
+  "homepage": "https://github.com/telorun/telo#readme",
+  "bugs": {
+    "url": "https://github.com/telorun/telo/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./editor-protocol-schema.json": "./editor-protocol-schema.json",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/**",
+    "src/**",
+    "editor-protocol-schema.json"
+  ],
+  "devDependencies": {
+    "ajv": "^8.17.1",
+    "typescript": "^5.0.0",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.lib.json",
+    "test": "vitest run"
+  }
+}

package/src/index.ts

@@ -0,0 +1,186 @@
+// The Telo editor protocol: what an editor host and a telo language-server
+// engine say to each other beyond LSP itself. Zero dependencies and no runtime
+// beyond constants, so a host of any telo version — and a host in any language,
+// through `editor-protocol-schema.json` — can speak it. `README.md` is the spec.
+
+/** The protocol generation this package describes. Additions within a
+ *  generation are negotiated by capability; an incompatible change bumps it. */
+export const TELO_EDITOR_PROTOCOL = 1;
+
+/** What an engine advertises under `ServerCapabilities.experimental`. */
+export interface TeloExperimentalCapabilities {
+  telo: TeloProtocolCapability;
+}
+
+export interface TeloProtocolCapability {
+  /** The generation the engine speaks. */
+  protocol: number;
+}
+
+/** The file a module directory is read as: `telo/read` of a directory answers
+ *  with this file inside it. */
+export const TELO_MODULE_FILENAME = "telo.yaml";
+
+/** `initialize`'s `serverInfo.name` for every telo engine. Its
+ *  `serverInfo.version` is the engine's identity: the telo version `X` for a
+ *  release build, `X+unreleased` for a build made while that release is still
+ *  pending. */
+export const TELO_SERVER_NAME = "telo";
+
+/** Method names of the requests an engine sends and a host serves, and of the
+ *  notification an engine sends. */
+export const TeloMethod = {
+  read: "telo/read",
+  exists: "telo/exists",
+  listDirectory: "telo/listDirectory",
+  hubSearchRefs: "telo/hub/searchRefs",
+  hubListVersions: "telo/hub/listVersions",
+  requirements: "telo/requirements",
+} as const;
+export type TeloMethod = (typeof TeloMethod)[keyof typeof TeloMethod];
+
+// --- Host-served requests (engine → host) ---------------------------------
+
+/** `telo/read`: the text at `uri`. `uri` is a document URI (`file:///…`) or an
+ *  import source (`oci://host/repo@1.2.0`, `https://…`); the host reads it
+ *  through whatever transport it owns. */
+export interface ReadParams {
+  uri: string;
+}
+
+/** The text read, with the CANONICAL location it was read from — a directory
+ *  resolves to its {@link TELO_MODULE_FILENAME}, an `oci://` tag to the reference the host
+ *  resolved. `null` when nothing exists at `uri`; any other failure is a
+ *  JSON-RPC error carrying its reason. */
+export type ReadResult = { uri: string; text: string } | null;
+
+/** `telo/exists`: whether a file or directory exists at `relative`, resolved
+ *  against the DIRECTORY of the file `base` names. */
+export interface ExistsParams {
+  base: string;
+  relative: string;
+}
+export type ExistsResult = boolean;
+
+/** `telo/listDirectory`: the entries of the directory at `uri`. */
+export interface ListDirectoryParams {
+  uri: string;
+}
+/** What a directory entry is, read WITHOUT following a link: a symbolic link
+ *  is `symlink` whatever it points at. A receiver reads a kind it does not know
+ *  as `other`. */
+export type DirectoryEntryKind = "file" | "directory" | "symlink" | "other";
+export interface DirectoryEntry {
+  name: string;
+  kind: DirectoryEntryKind;
+}
+/** `null` when `uri` names nothing or names a file. */
+export type ListDirectoryResult = DirectoryEntry[] | null;
+
+/** `telo/hub/searchRefs`: module refs the configured telo hub matches `query`
+ *  against (a substring over every registered ref). */
+export interface SearchRefsParams {
+  query: string;
+}
+export interface HubRef {
+  ref: string;
+  latestVersion: string;
+  description?: string;
+}
+export type SearchRefsResult = HubRef[];
+
+/** `telo/hub/listVersions`: every version the hub tracks for a location ref,
+ *  newest first, each with its import pin when the hub has one. `[]` for a ref
+ *  the hub does not track; an unreachable hub is a JSON-RPC error. */
+export interface ListVersionsParams {
+  ref: string;
+}
+export interface ModuleVersion {
+  version: string;
+  /** Canonical `sha256-<base64url>` pin. */
+  integrity?: string;
+}
+export type ListVersionsResult = ModuleVersion[];
+
+/** Params and result of every host-served request, by method. */
+export interface TeloHostRequests {
+  "telo/read": [ReadParams, ReadResult];
+  "telo/exists": [ExistsParams, ExistsResult];
+  "telo/listDirectory": [ListDirectoryParams, ListDirectoryResult];
+  "telo/hub/searchRefs": [SearchRefsParams, SearchRefsResult];
+  "telo/hub/listVersions": [ListVersionsParams, ListVersionsResult];
+}
+
+// --- Engine → host notification -------------------------------------------
+
+/** One edge of a version interval. */
+export interface VersionBound {
+  version: string;
+  inclusive: boolean;
+}
+
+/** A `requires: telo:` range reduced to its edges; an absent edge is open. */
+export interface VersionInterval {
+  min?: VersionBound;
+  max?: VersionBound;
+}
+
+export interface RequirementsRange {
+  /** URI of the module document declaring the range. */
+  module: string;
+  /** The range as written. */
+  text: string;
+  interval: VersionInterval;
+}
+
+/** `telo/requirements`: sent after each analysis of an owner module. */
+export interface RequirementsParams {
+  /** URI of the owner module's `telo.yaml` (or standalone manifest). */
+  owner: string;
+  /** URIs of the owner's member documents — the owner and every partial it
+   *  includes. A host routes these documents to the engine chosen for `owner`. */
+  documents: string[];
+  /** Every `requires: telo:` range in the owner's import closure. The owner
+   *  itself declares one exactly when an entry's `module` equals `owner`. */
+  ranges: RequirementsRange[];
+}
+
+// --- Diagnostic.data -------------------------------------------------------
+
+/** The YAML tags a repair may write. A receiver that does not know a tag
+ *  offers no fix for it. */
+export type DiagnosticFixTag = "ref" | "cel" | "module-path";
+
+/** A mechanically applicable repair: the whole corrected value at the
+ *  diagnostic's range, written behind `tag` when one is present. */
+export interface DiagnosticFix {
+  replacement: string;
+  tag?: DiagnosticFixTag;
+}
+
+/** What an engine puts in `Diagnostic.data`. A host hands the diagnostic back
+ *  unchanged in `codeAction`'s context, which is how a fix round-trips. */
+export interface TeloDiagnosticData {
+  fix?: DiagnosticFix;
+  /** The resource the diagnostic is pinned to. */
+  resource?: { kind: string; name: string };
+  /** Dotted path of the offending value within that resource. */
+  path?: string;
+}
+
+// --- Commands --------------------------------------------------------------
+
+/** `workspace/executeCommand` commands an engine serves. The two upgrade
+ *  commands take `[{ uri, aliases }]` and apply through `workspace/applyEdit`;
+ *  refresh takes no argument. */
+export const TeloCommand = {
+  upgradeImport: "telo.upgradeImport",
+  upgradeAllImports: "telo.upgradeAllImports",
+  refreshImportUpgrades: "telo.refreshImportUpgrades",
+} as const;
+export type TeloCommand = (typeof TeloCommand)[keyof typeof TeloCommand];
+
+export interface UpgradeImportsArguments {
+  uri: string;
+  aliases: string[];
+}