@deepseek-ai/dsh-lsp 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/lsp/lsp/README.md
+README.md: bab312e73f746d0d782ab5771429fed1397255aa
+README.zh.md: 7ef95c725eba4a35f99014b446fc5648d8aab20a

package/README.md

@@ -0,0 +1,44 @@
+# @deepseek-ai/dsh-lsp
+
+English | [中文](README.zh.md)
+
+The **LSP capability seam**: an abstract `LspService` (`ctx.lsp`) defining WHAT semantic code navigation the harness has — go to definition, find references, find implementations, hover — over language-server providers, without binding the model contract to local subprocesses.
+
+This package owns the Service Definition role of the LSP capability:
+
+| Package | Role |
+|---|---|
+| `@deepseek-ai/dsh-lsp` (this) | Service Definition: the service, provider registry keyed by branded id + extension mapping, per-query selection, request/result vocabulary, the `LspError` taxonomy |
+| `@deepseek-ai/dsh-lsp-local` | Service provider: a generic local backend that registers configured stdio language-server providers |
+| `@deepseek-ai/dsh-tool-lsp` | Consumer: the model-facing `lsp` tool over `ctx.lsp` |
+
+The seam exposes exactly four semantic operations — `goToDefinition`, `findReferences`, `goToImplementation`, `hover` — and no generic JSON-RPC escape hatch, so no protocol payload or unreviewed command/mutation reaches a provider through `ctx.lsp`.
+
+## Service API (`ctx.lsp`)
+
+| Member | Semantics |
+|---|---|
+| `registerProvider(provider)` | Register a backend, atomically reserving its branded `id` and every normalized file extension. Any invalid input or conflict publishes nothing and throws `LspError` (`LSP_INVALID_PROVIDER` / `LSP_CONFLICT`). Returns a disposer releasing all reservations. Disposed with the calling fiber. |
+| `query(request, signal?)` | Select the provider by the file's final extension, derive the `languageId` from that provider's mapping, and run one query. No match throws `LspError` `LSP_UNAVAILABLE`. |
+
+Selection is per query and order-independent: a provider owns a set of extensions exclusively, so registration and HMR order never change routing. Extension keys normalize to lowercase, leading-dot form; the `languageId` only synchronizes the transient document, never participates in selection. The first version has no glob, language-id, or explicit route selector.
+
+Providers register **capabilities**, not tools. `dsh-tool-lsp` is the only owner of the model-facing name, description, prompt guidance, schema, and presentation.
+
+## Vocabulary
+
+`LspQueryRequest` (`operation`, `filePath`, `position`, `workspaceRoot`) — every field required, so no field needs implementation defaulting and there is no `resolve()` step. Positions and ranges are zero-based UTF-16, matching the protocol; the tool owns the one-based cursor convention. `findReferences` always includes declarations — providers enforce this internally, so callers get no flag. `LspQueryResult` is a CLOSED discriminated union: `{ kind: 'locations'; locations; resolvedWorkspaceUri }` for navigation, `{ kind: 'hover'; hover }` for hover (content or `null`) — consumers `switch` to exhaustiveness so a new arm breaks compilation until handled. `resolvedWorkspaceUri` is the provider's canonical workspace `file:` URI; callers relativize location URIs against it instead of applying host-platform path rules to the possibly symlinked request root. See `src/types.ts` for the full contracts and `src/index.ts` for the `LspError` codes, including `LSP_DISPOSED` and `LSP_MALFORMED_RESPONSE`.
+
+## Model Experience
+
+Indirectly, through `dsh-tool-lsp`, which owns the model-facing `lsp` schema, prompt, and rendered results while this registry contributes no prompt or schema itself.
+
+#### KV Cache effect
+
+No direct invalidation; `dsh-tool-lsp` owns request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **Exclusive extension ownership within one runtime** — two providers cannot both claim `.ts`, even with different language ids; overlaps fail registration. The intended extension is a deployment-configured selector above registrations, which can relax exclusive reservation without adding provider choice to model input ([seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)).
+- **Four operations only** — symbols and call hierarchy are deferred (they need different schemas); diagnostics need separate freshness/accumulation rules; mutations (rename, code actions, formatting) require separate tools with preview, permission, and write-policy integration.
+- **No observation surface** — availability is observed only by running `query()` and routing the thrown `LspError` codes; there is no provider-change event or capability-status query.

package/README.zh.md

@@ -0,0 +1,44 @@
+# @deepseek-ai/dsh-lsp
+
+[English](README.md) | 中文
+
+**LSP 能力 seam**：抽象 `LspService`（`ctx.lsp`）定义 harness 具备哪些语义代码导航能力（转到定义、查找引用、查找实现、悬停），并通过语言服务器提供方实现，不把模型约定绑定到本地子进程。
+
+本包承担 LSP 能力的 Service Definition 角色：
+
+| 包 | 职责 |
+|---|---|
+| `@deepseek-ai/dsh-lsp`（本包） | Service Definition：服务、以品牌化 id + 扩展名映射为 key 的提供方注册表、逐查询选择、请求／结果词汇、`LspError` 分类体系 |
+| `@deepseek-ai/dsh-lsp-local` | Service provider：通用本地后端，注册已配置的 stdio 语言服务器提供方 |
+| `@deepseek-ai/dsh-tool-lsp` | Consumer：面向模型的 `lsp` 工具，基于 `ctx.lsp` |
+
+该 seam 恰好公开四种语义操作：`goToDefinition`、`findReferences`、`goToImplementation`、`hover`，且没有通用 JSON-RPC 逃生口，因此任何协议载荷或未经评审的命令／修改都无法通过 `ctx.lsp` 到达提供方。
+
+## 服务 API（`ctx.lsp`）
+
+| 成员 | 语义 |
+|---|---|
+| `registerProvider(provider)` | 注册后端，以原子方式保留其品牌化 `id` 与每个规范化文件扩展名。任何无效输入或冲突都不会发布内容，并抛出 `LspError`（`LSP_INVALID_PROVIDER`／`LSP_CONFLICT`）。返回释放所有保留项的 disposer。随调用 fiber 释放。 |
+| `query(request, signal?)` | 按文件最终扩展名选择提供方，从该提供方的映射派生 `languageId`，并运行一次查询。没有匹配项时抛出 `LspError` `LSP_UNAVAILABLE`。 |
+
+选择逐查询进行且与顺序无关：一个提供方独占一组扩展名，因此注册和 HMR 顺序绝不会改变路由。扩展名 key 规范化为小写且以点开头；`languageId` 只用于同步临时文档，绝不参与选择。第一版没有 glob、language-id 或显式路由 selector。
+
+提供方注册的是**能力** 而非工具。`dsh-tool-lsp` 是面向模型名称、描述、提示词指引、schema 和呈现的唯一 owner。
+
+## 词汇
+
+`LspQueryRequest`（`operation`、`filePath`、`position`、`workspaceRoot`）：每个字段都必填，因此没有字段需要实现默认值，也不存在 `resolve()` 步骤。位置与范围使用从零开始的 UTF-16，与协议一致；工具拥有从 1 开始的光标约定。`findReferences` 始终包含声明，提供方在内部强制执行，因此调用方没有 flag。`LspQueryResult` 是封闭的判别联合：导航使用 `{ kind: 'locations'; locations; resolvedWorkspaceUri }`，悬停使用 `{ kind: 'hover'; hover }`（内容或 `null`）；消费方通过 `switch` 实现穷尽检查，因此新增分支会使编译失败，直到完成处理。`resolvedWorkspaceUri` 是提供方的规范工作区 `file:` URI；调用方相对化位置 URI 时以它为基准，而不是对可能含符号链接的请求根应用宿主平台路径规则。完整约定见 `src/types.ts`；`src/index.ts` 给出 `LspError` code，包括 `LSP_DISPOSED` 和 `LSP_MALFORMED_RESPONSE`。
+
+## 模型体验
+
+通过 `dsh-tool-lsp` 间接影响；该工具拥有面向模型的 `lsp` schema、提示词与渲染结果，本注册表自身不贡献提示词或 schema。
+
+#### KV Cache 影响
+
+不会直接失效；请求前缀变更由 `dsh-tool-lsp` 负责。
+
+## 已知限制与暂缓事项
+
+- **同一运行时内扩展名归属互斥**：两个提供方不能同时声明 `.ts`，即使 language id 不同；重叠会使注册失败。预期扩展是在注册之上增加部署配置的 selector；它可以放宽互斥保留，而无需把提供方选择加入模型输入（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)）。
+- **仅四种操作**：symbol 与 call hierarchy 暂缓（它们需要不同 schema）；diagnostics 需要独立的新鲜度／累积规则；修改操作（rename、code action、formatting）需要独立工具，并集成预览、权限和写入策略。
+- **没有观测表层**：可用性只能通过运行 `query()` 并按抛出的 `LspError` code 路由来观测；没有提供方变更事件或能力状态查询。

package/lib/index.js

@@ -0,0 +1,110 @@
+import { Service } from "@deepseek-ai/cordis";
+import { HarnessError } from "@deepseek-ai/dsh-llm";
+//#region lib/types/brand.js
+/**
+* dsh-lsp's owned branded id: {@link LspProviderId}, the opaque identity a provider reserves on
+* `ctx.lsp`. The `Branded<B>` primitive lives in `@deepseek-ai/dsh-brand`; keeping the type and its
+* factory together here lets `index.ts` re-export both under one name.
+* @module @deepseek-ai/dsh-lsp/brand
+*/
+/**
+* Brand a string as an {@link LspProviderId}. No validation — the registry rejects an empty id at
+* registration.
+* @param id - the provider's stable identifier.
+* @returns the same string, branded.
+*/
+function LspProviderId(id) {
+	return id;
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Service Definition for the LSP capability seam (`ctx.lsp`): a language-server provider registry and per-query,
+* order-independent selection over normalized goToDefinition/findReferences/goToImplementation/
+* hover queries.
+*
+* A provider reserves a branded id and an exclusive set of file extensions atomically:
+* {@link Lsp.registerProvider} validates and conflict-checks everything before mutating, so an
+* invalid or conflicting registration publishes nothing, and its disposer releases every
+* reservation together. Selection routes a query by the file's final extension; it never depends on
+* registration order. The seam exposes exactly the four operations and no JSON-RPC escape hatch.
+* @module @deepseek-ai/dsh-lsp
+*/
+/**
+* Structured LSP failure. Extends {@link HarnessError} with a stable `code`
+* (`LSP_INVALID_PROVIDER`, `LSP_CONFLICT`, `LSP_UNAVAILABLE`, `LSP_DISPOSED`,
+* `LSP_UNSUPPORTED_OPERATION`, `LSP_MALFORMED_RESPONSE`, …) that callers route on instead of
+* parsing `message`.
+*/
+var LspError = class extends HarnessError {};
+/**
+* Extract a file's final extension as a normalized, lowercase, leading-dot key (e.g. `Foo.TS` →
+* `.ts`, `foo.d.ts` → `.ts`). Returns `''` for a name with no extension or a leading-dot dotfile
+* (`.bashrc`), which no route ever matches. Splits on both `/` and `\` so a caller's path separator
+* does not change the result.
+* @param filePath - the source path to inspect.
+* @returns the normalized extension, or `''` when there is none.
+*/
+function finalExtension(filePath) {
+	const lastSlash = Math.max(filePath.lastIndexOf("/"), filePath.lastIndexOf("\\"));
+	const base = lastSlash >= 0 ? filePath.slice(lastSlash + 1) : filePath;
+	const dot = base.lastIndexOf(".");
+	if (dot <= 0) return "";
+	return base.slice(dot).toLowerCase();
+}
+/** A well-formed normalized extension: a dot followed by one or more non-dot, non-separator chars. */
+const EXTENSION_PATTERN = /^\.[^./\\]+$/;
+/**
+* `ctx.lsp`. Holds the id reservations and the extension→route table; both are populated and cleared
+* together per provider so a route always has a live provider.
+*/
+var Lsp = class extends Service {
+	providerIds = /* @__PURE__ */ new Set();
+	routes = /* @__PURE__ */ new Map();
+	constructor(ctx) {
+		super(ctx, "lsp");
+	}
+	registerProvider(provider) {
+		const id = provider.id;
+		if (id.trim() === "") throw new LspError("an LSP provider id must be a non-empty string", "LSP_INVALID_PROVIDER");
+		if (this.providerIds.has(id)) throw new LspError(`an LSP provider with id "${id}" is already registered`, "LSP_CONFLICT");
+		const entries = Object.entries(provider.extensionToLanguage);
+		if (entries.length === 0) throw new LspError(`LSP provider "${id}" registers no file extensions`, "LSP_INVALID_PROVIDER");
+		const pending = /* @__PURE__ */ new Map();
+		for (const [rawExt, languageId] of entries) {
+			const ext = normalizeExtension(rawExt);
+			if (!EXTENSION_PATTERN.test(ext)) throw new LspError(`LSP provider "${id}" maps an invalid extension "${rawExt}"`, "LSP_INVALID_PROVIDER");
+			if (languageId.trim() === "") throw new LspError(`LSP provider "${id}" maps extension "${ext}" to an empty language id`, "LSP_INVALID_PROVIDER");
+			if (pending.has(ext)) throw new LspError(`LSP provider "${id}" maps extension "${ext}" more than once`, "LSP_INVALID_PROVIDER");
+			pending.set(ext, {
+				provider,
+				languageId
+			});
+		}
+		for (const ext of pending.keys()) if (this.routes.has(ext)) throw new LspError(`extension "${ext}" is already handled by another LSP provider`, "LSP_CONFLICT");
+		const dispose = this.ctx.effect(function* () {
+			this.providerIds.add(id);
+			for (const [ext, route] of pending) this.routes.set(ext, route);
+			yield () => {
+				this.providerIds.delete(id);
+				for (const ext of pending.keys()) this.routes.delete(ext);
+			};
+		}.bind(this), "lsp.registerProvider()");
+		return () => void dispose();
+	}
+	async query(request, signal) {
+		const route = this.routes.get(finalExtension(request.filePath));
+		if (route === void 0) throw new LspError(`no LSP provider handles "${request.filePath}"`, "LSP_UNAVAILABLE");
+		return route.provider.query({
+			...request,
+			languageId: route.languageId
+		}, signal);
+	}
+};
+/** Lowercase an extension and ensure it carries a leading dot; `EXTENSION_PATTERN` rejects the rest. */
+function normalizeExtension(ext) {
+	const lower = ext.toLowerCase();
+	return lower.startsWith(".") ? lower : `.${lower}`;
+}
+//#endregion
+export { Lsp, Lsp as default, LspError, LspProviderId, finalExtension };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-lsp`.
+* @module @deepseek-ai/dsh-lsp/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-lsp";
+/** Cordis companion plugin name. */
+const name = "lsp-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: provider ids and extension routes are private, atomically updated state;
+* the seam exposes neither an enumerable snapshot nor lifecycle events to compare independently.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/brand.d.ts

@@ -0,0 +1,17 @@
+/**
+ * dsh-lsp's owned branded id: {@link LspProviderId}, the opaque identity a provider reserves on
+ * `ctx.lsp`. The `Branded<B>` primitive lives in `@deepseek-ai/dsh-brand`; keeping the type and its
+ * factory together here lets `index.ts` re-export both under one name.
+ * @module @deepseek-ai/dsh-lsp/brand
+ */
+import type { Branded } from '@deepseek-ai/dsh-brand';
+/** Opaque provider identity, reserved atomically with its extension mappings at registration. */
+export type LspProviderId = Branded<'LspProviderId'>;
+/**
+ * Brand a string as an {@link LspProviderId}. No validation — the registry rejects an empty id at
+ * registration.
+ * @param id - the provider's stable identifier.
+ * @returns the same string, branded.
+ */
+export declare function LspProviderId(id: string): LspProviderId;
+//# sourceMappingURL=brand.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Service Definition for the LSP capability seam (`ctx.lsp`): a language-server provider registry and per-query,
+ * order-independent selection over normalized goToDefinition/findReferences/goToImplementation/
+ * hover queries.
+ *
+ * A provider reserves a branded id and an exclusive set of file extensions atomically:
+ * {@link Lsp.registerProvider} validates and conflict-checks everything before mutating, so an
+ * invalid or conflicting registration publishes nothing, and its disposer releases every
+ * reservation together. Selection routes a query by the file's final extension; it never depends on
+ * registration order. The seam exposes exactly the four operations and no JSON-RPC escape hatch.
+ * @module @deepseek-ai/dsh-lsp
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import { HarnessError } from '@deepseek-ai/dsh-llm';
+import type { LspProvider, LspQueryRequest, LspQueryResult, LspService } from './types.ts';
+export { LspProviderId } from './brand.ts';
+export type { LspHover, LspLocation, LspOperation, LspPosition, LspProvider, LspProviderQuery, LspQueryRequest, LspQueryResult, LspRange, LspService, } from './types.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        lsp: LspService;
+    }
+}
+/**
+ * Structured LSP failure. Extends {@link HarnessError} with a stable `code`
+ * (`LSP_INVALID_PROVIDER`, `LSP_CONFLICT`, `LSP_UNAVAILABLE`, `LSP_DISPOSED`,
+ * `LSP_UNSUPPORTED_OPERATION`, `LSP_MALFORMED_RESPONSE`, …) that callers route on instead of
+ * parsing `message`.
+ */
+export declare class LspError extends HarnessError {
+}
+/**
+ * Extract a file's final extension as a normalized, lowercase, leading-dot key (e.g. `Foo.TS` →
+ * `.ts`, `foo.d.ts` → `.ts`). Returns `''` for a name with no extension or a leading-dot dotfile
+ * (`.bashrc`), which no route ever matches. Splits on both `/` and `\` so a caller's path separator
+ * does not change the result.
+ * @param filePath - the source path to inspect.
+ * @returns the normalized extension, or `''` when there is none.
+ */
+export declare function finalExtension(filePath: string): string;
+/**
+ * `ctx.lsp`. Holds the id reservations and the extension→route table; both are populated and cleared
+ * together per provider so a route always has a live provider.
+ */
+export declare class Lsp extends Service implements LspService {
+    private readonly providerIds;
+    private readonly routes;
+    constructor(ctx: Context);
+    registerProvider(provider: LspProvider): () => void;
+    query(request: LspQueryRequest, signal?: AbortSignal): Promise<LspQueryResult>;
+}
+export default Lsp;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-lsp`.
+ * @module @deepseek-ai/dsh-lsp/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "lsp-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/types.d.ts

@@ -0,0 +1,125 @@
+/**
+ * LSP seam vocabulary: the normalized request, provider, and result contracts. Types only — the
+ * {@link LspError} taxonomy and the {@link LspProviderId} brand factory are runtime and live in
+ * `index.ts`. Positions and ranges are zero-based UTF-16, matching the protocol; the model-facing
+ * tool owns the one-based cursor convention. The seam exposes no protocol types, process or document
+ * controls, or generic JSON-RPC escape hatch — only the four semantic operations.
+ * @module @deepseek-ai/dsh-lsp/types
+ */
+import type { LspProviderId } from './brand.ts';
+/**
+ * The four semantic queries the seam and model expose. A closed union: adding an operation is a
+ * compile-enforced change across the seam, providers, and the tool. Symbols and call hierarchy are
+ * not operations here; they need different schemas.
+ */
+export type LspOperation = 'goToDefinition' | 'findReferences' | 'goToImplementation' | 'hover';
+/** A zero-based UTF-16 cursor coordinate, matching the LSP wire convention. */
+export interface LspPosition {
+    /** Zero-based line. */
+    readonly line: number;
+    /** Zero-based UTF-16 code-unit offset within the line. */
+    readonly character: number;
+}
+/** A zero-based UTF-16 half-open range `[start, end)`. */
+export interface LspRange {
+    readonly start: LspPosition;
+    readonly end: LspPosition;
+}
+/**
+ * A caller's normalized query. Every field is required: `workspaceRoot` is caller-supplied,
+ * `languageId` comes from the provider registration (not here), and consumers own timeouts and
+ * result limits — so no field needs implementation defaulting and there is no `resolve()` step.
+ */
+export interface LspQueryRequest {
+    /** Which semantic query to run. */
+    readonly operation: LspOperation;
+    /** The source file to query (relative to `workspaceRoot` or absolute; the provider canonicalizes). */
+    readonly filePath: string;
+    /** The zero-based UTF-16 cursor position to query at. */
+    readonly position: LspPosition;
+    /** The workspace root the provider resolves against and indexes; required, never defaulted. */
+    readonly workspaceRoot: string;
+}
+/**
+ * A request as a provider receives it: the caller's {@link LspQueryRequest} plus the `languageId`
+ * the seam derived from the provider's extension mapping. The language id only synchronizes the
+ * transient document; it does not participate in selection.
+ */
+export interface LspProviderQuery extends LspQueryRequest {
+    /** The LSP language id for `filePath`, from this provider's extension mapping. */
+    readonly languageId: string;
+}
+/** One resolved location: a document URI and the range within it. */
+export interface LspLocation {
+    /** The target document URI (`file:` or otherwise), verbatim from the server. */
+    readonly uri: string;
+    /** The range within the target document. */
+    readonly range: LspRange;
+}
+/** Normalized hover content, or `null` for no hover at the position. */
+export interface LspHover {
+    /** The normalized hover text (markdown or plaintext, provider-joined). */
+    readonly contents: string;
+    /** The range the hover applies to, when the server supplied one. */
+    readonly range?: LspRange;
+}
+/**
+ * The closed result union. Navigation operations (`goToDefinition`, `findReferences`,
+ * `goToImplementation`) normalize to `locations`; `hover` normalizes to content or `null`.
+ * Consumers `switch` on `kind` to exhaustiveness so a new arm breaks compilation until handled.
+ *
+ * The `locations` variant carries `resolvedWorkspaceUri`: the provider's canonical `file:` URI for
+ * the request's workspace root. A caller that relativizes location URIs MUST use this, not parse the
+ * request's possibly symlinked process path with host-platform rules; the execution platform may
+ * differ from the caller's.
+ */
+export type LspQueryResult = {
+    readonly kind: 'locations';
+    readonly locations: readonly LspLocation[];
+    readonly resolvedWorkspaceUri: string;
+} | {
+    readonly kind: 'hover';
+    readonly hover: LspHover | null;
+};
+/**
+ * A language-server backend registered on `ctx.lsp`. Each provider owns a stable {@link
+ * LspProviderId} and an extension-to-language-id map (lowercase, leading-dot keys).
+ * `findReferences` always includes declarations — the provider enforces this internally; callers
+ * get no flag.
+ */
+export interface LspProvider {
+    /** Stable provider identity, reserved atomically with the extension mappings. */
+    readonly id: LspProviderId;
+    /** Lowercase leading-dot extension → LSP language id (e.g. `{ '.ts': 'typescript' }`). */
+    readonly extensionToLanguage: Readonly<Record<string, string>>;
+    /**
+     * Run one query. The seam has already selected this provider and derived `languageId`.
+     * @param request - the resolved provider query (caller request + derived language id).
+     * @param signal - optional cancellation; the provider stops its own work when it aborts.
+     * @returns the normalized, closed-union result.
+     */
+    query(request: LspProviderQuery, signal?: AbortSignal): Promise<LspQueryResult>;
+}
+/**
+ * The LSP capability seam (`ctx.lsp`). Owns provider registration/selection and normalized query
+ * execution; exposes exactly the four operations and no protocol escape hatch.
+ */
+export interface LspService {
+    /**
+     * Register a provider, atomically reserving its id and every normalized extension. Any conflict
+     * or invalid input publishes nothing and throws `LspError`; the returned disposer releases all
+     * reservations. Disposed with the calling fiber.
+     * @param provider - the backend to register.
+     * @returns a synchronous disposer releasing the id and all extension reservations.
+     */
+    registerProvider(provider: LspProvider): () => void;
+    /**
+     * Select a provider by the file's extension and run one query. Selection is per-query and
+     * order-independent; no match throws `LspError` `LSP_UNAVAILABLE`.
+     * @param request - the normalized query.
+     * @param signal - optional cancellation forwarded to the selected provider.
+     * @returns the normalized, closed-union result.
+     */
+    query(request: LspQueryRequest, signal?: AbortSignal): Promise<LspQueryResult>;
+}
+//# sourceMappingURL=types.d.ts.map

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@deepseek-ai/dsh-lsp",
+  "description": "Abstract LSP capability seam (ctx.lsp) for the DeepSeek Harness — language-server provider registry keyed by branded id and extension mapping, order-independent per-query selection, normalized definition/references/implementation/hover requests and results, and the LspError taxonomy",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/lsp/lsp"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-brand": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-brand": "^0.0.1-rc.1"
+  }
+}