@githolon/dsl 0.51.0 → 0.52.0

package/lsp_server.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded QuickJS engine}.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+// `githolon lsp` launcher — the twin of `check_package.mjs`: resolve `tsx` (the caller's, else the
+// DSL's own dependency) and run `src/lsp_main.ts` under it. The server imports the tenant's TS domain
+// modules IN-PROCESS on every re-check (needs the tsx ESM loader). stdio is inherited so the LSP wire
+// (stdin/stdout, JSON-RPC) passes through untouched; the editor spawns this and talks to it directly.
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const DSL_DIR = path.dirname(fileURLToPath(import.meta.url));
+const MAIN = path.join(DSL_DIR, "src", "lsp_main.ts");
+
+function resolvePkgDir(name, fromDir) {
+  try {
+    const req = createRequire(pathToFileURL(path.join(fromDir, "noop.js")));
+    return path.dirname(req.resolve(`${name}/package.json`));
+  } catch {
+    return undefined;
+  }
+}
+
+const tsxDir = resolvePkgDir("tsx", process.cwd()) ?? resolvePkgDir("tsx", DSL_DIR);
+if (!tsxDir) {
+  console.error("githolon lsp: tsx not found — reinstall @githolon/dsl (tsx is one of its dependencies)");
+  process.exit(1);
+}
+const tsxPkg = JSON.parse(readFileSync(path.join(tsxDir, "package.json"), "utf8"));
+const tsxBinRel = typeof tsxPkg.bin === "string" ? tsxPkg.bin : tsxPkg.bin?.tsx;
+const tsxCli = path.join(tsxDir, tsxBinRel ?? "dist/cli.mjs");
+
+// spawn (not execFileSync) so the long-lived server's stdio streams stay connected for the session.
+const child = spawn(process.execPath, [tsxCli, MAIN, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  cwd: process.cwd(),
+});
+child.on("exit", (code) => process.exit(code ?? 0));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.51.0",
+  "version": "0.52.0",
   "type": "module",
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
   "license": "SEE LICENSE IN LICENSE.md",
@@ -47,7 +47,8 @@
     "!dart/.dart_tool",
     "!dart/build",
     "compile_package.mjs",
-    "check_package.mjs"
+    "check_package.mjs",
+    "lsp_server.mjs"
   ],
   "publishConfig": {
     "access": "public"
@@ -59,6 +60,8 @@
   "dependencies": {
     "esbuild": "0.24.2",
     "tsx": "^4.19.2",
+    "vscode-languageserver": "^9.0.1",
+    "vscode-languageserver-textdocument": "^1.0.12",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/src/check_package_main.ts

@@ -17,6 +17,7 @@ import { pathToFileURL } from "node:url";
 import { composeDomainModule, type Mod } from "./build_package.js";
 import type { DomainModule } from "./codegen_dart.js";
 import { checkDomainModules, formatFindings, hasRefusal, type Finding } from "./law_check.js";
+import { LawSourceMap } from "./law_source_map.js";
 import {
   currentEvolveLaw,
   evolveDiff,
@@ -48,28 +49,46 @@ function fail(msg: string): never {
  * applies the secondary-ensure auto-declare). Returns the composed modules ready for the twins.
  */
 export async function loadComposedModules(configArg: string): Promise<DomainModule[]> {
+  return (await loadComposedModulesWithSources(configArg)).modules;
+}
+
+/**
+ * Like {@link loadComposedModules}, but ALSO returns the domain-key → ORDERED module file paths map
+ * (the source map's input — the composed DomainModule does not retain source paths, so the check/LSP
+ * lane threads them through). The config is the one place that names both the domain key and its files.
+ */
+export async function loadComposedModulesWithSources(
+  configArg: string,
+): Promise<{ modules: DomainModule[]; domainFiles: Map<string, string[]> }> {
   const configPath = path.resolve(process.cwd(), configArg);
   if (!existsSync(configPath)) fail(`config not found: ${configPath}`);
   const cfgDir = path.dirname(configPath);
-  const cfgModule = (await import(pathToFileURL(configPath).href)) as { default?: PackageConfig };
+  // Cache-bust the config import so a re-load (the LSP re-check) sees edits, not the first-import cache.
+  const cfgUrl = `${pathToFileURL(configPath).href}?t=${Date.now()}`;
+  const cfgModule = (await import(cfgUrl)) as { default?: PackageConfig };
   const cfg = cfgModule.default;
   if (!cfg || typeof cfg.name !== "string" || !Array.isArray(cfg.domains) || cfg.domains.length === 0) {
     fail(`config must default-export { name, domains: [{ key, modules }, ...] }`);
   }
   const composed: DomainModule[] = [];
+  const domainFiles = new Map<string, string[]>();
   for (const d of cfg.domains) {
     if (typeof d.key !== "string" || !Array.isArray(d.modules) || d.modules.length === 0) {
       fail(`each domain needs { key, modules: [path, ...] }; got ${JSON.stringify(d)}`);
     }
     const mods: Mod[] = [];
+    const files: string[] = [];
     for (const rel of d.modules) {
       const abs = path.resolve(cfgDir, rel);
       if (!existsSync(abs)) fail(`domain '${d.key}': module not found: ${abs}`);
-      mods.push((await import(pathToFileURL(abs).href)) as Mod);
+      files.push(abs);
+      // Cache-bust so a re-import (the LSP re-check after an edit) re-evaluates the edited module.
+      mods.push((await import(`${pathToFileURL(abs).href}?t=${Date.now()}`)) as Mod);
     }
+    domainFiles.set(d.key, files);
     composed.push(composeDomainModule({ name: d.name ?? d.key, domain: d.key, modules: mods }));
   }
-  return composed;
+  return { modules: composed, domainFiles };
 }
 
 /**
@@ -148,7 +167,9 @@ async function main(): Promise<void> {
       ? argv[againstIdx + 1]
       : argv.find((a) => a.startsWith("--against="))?.slice("--against=".length);
 
-  const modules = await loadComposedModules(configArg);
+  const asJson = argv.includes("--json");
+
+  const { modules, domainFiles } = await loadComposedModulesWithSources(configArg);
   const findings: Finding[] = [...checkDomainModules(modules)];
 
   // ── EVOLVE PREVIEW (--against): diff the current build against a prior law + pre-fire the gate. ──
@@ -158,19 +179,38 @@ async function main(): Promise<void> {
       fail(`--against needs a path: --against <build/<name>.deploy.json | build dir | nomos.stable-ids.json>`);
     }
     const lock = loadCwdLockfile(configArg);
-    if (lock === undefined) {
+    if (lock === undefined && !asJson) {
       console.log(
         "githolon check: --against — no nomos.stable-ids.json in the config dir; the current law's stable ids " +
           "fall back to NAMES (a rename would read as removal+add). Run `githolon compile` first for a sid-accurate preview.",
       );
     }
     const prior = loadPriorEvolveLaw(againstArg);
-    if (prior.note !== undefined) console.log(`githolon check: --against note — ${prior.note}`);
+    if (prior.note !== undefined && !asJson) console.log(`githolon check: --against note — ${prior.note}`);
     const current = currentEvolveLaw(modules, lock);
     const diff = evolveDiff(prior.law, current);
     findings.push(...diff.findings);
     if (Object.keys(diff.dispositions).length > 0) evolveDispositions = diff.dispositions;
-    console.log(`githolon check: evolve preview against ${prior.source}`);
+    if (!asJson) console.log(`githolon check: evolve preview against ${prior.source}`);
+  }
+
+  // ── --json: emit the findings as a machine-readable array (the LSP + tooling surface). Each finding
+  //    is enriched with its source {file, line, column} when the source map can locate the declaration.
+  if (asJson) {
+    const srcMap = new LawSourceMap(domainFiles);
+    const out = findings.map((f) => {
+      const loc = srcMap.locate(f.domain, f.directiveId);
+      return {
+        domain: f.domain,
+        ...(f.directiveId !== undefined ? { directiveId: f.directiveId } : {}),
+        level: f.level,
+        what: f.what,
+        fix: f.fix,
+        ...(loc !== undefined ? { file: loc.file, line: loc.line, column: loc.column, fallback: loc.fallback } : {}),
+      };
+    });
+    process.stdout.write(JSON.stringify(out) + "\n");
+    process.exit(hasRefusal(findings) ? 1 : 0);
   }
 
   console.log(`githolon check: ${findings.length} finding(s)`);

package/src/law_source_map.ts

@@ -0,0 +1,146 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded QuickJS engine}.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * SOURCE MAPPING for `githolon check` findings (architecture/author_time_gate.md, slice 3 — the LSP).
+ *
+ * A {@link Finding} carries `{domain, directiveId?}` but no source LOCATION — the probe knows WHICH
+ * directive/aggregate/read is at fault, not WHERE it is written. This module recovers the location by
+ * scanning the domain's own TS module source text for the DECLARATION of the named entity:
+ * `directive("<id>")`, `aggregate("<Id>", …)`, `query("<id>")`, `count("<id>")`, `sum(...)`, … — a
+ * regex on the STRING LITERAL, robust across formatting (multi-line, spacing, quote style).
+ *
+ * The id in a finding may name a directive, a read decl (query/count/sum/min/max/exists/spatial), a
+ * workspace invariant, or — for a domain-wide finding with no `directiveId` — an aggregate. We do NOT
+ * know which kind, so we scan for the id as the FIRST string argument of ANY declaration call. When
+ * nothing resolves (a domain-wide finding, an id we can't find, an exotic layout) we fall back to
+ * line 1 of the domain's FIRST module — a squiggle at the top of the file beats no squiggle.
+ *
+ * Pure + synchronous: the caller supplies the domain→module-file-paths map (the config knows it — the
+ * composed DomainModule does not retain source paths, so the check/LSP lane threads them through) and
+ * the file READS are memoized per source map instance.
+ */
+import { readFileSync } from "node:fs";
+
+/** A resolved 1-based source location (LSP-friendly: `line`/`column` are 1-based, editors 0-base them). */
+export interface SourceLocation {
+  /** Absolute path of the module file the declaration lives in. */
+  readonly file: string;
+  /** 1-based line of the declaration's id string literal (or 1 on fallback). */
+  readonly line: number;
+  /** 1-based column of the id string literal's opening quote (or 1 on fallback). */
+  readonly column: number;
+  /** True when this is the top-of-file fallback (the id could not be located precisely). */
+  readonly fallback: boolean;
+}
+
+/** The declaration VERBS whose first string argument names an entity a finding can point at. */
+const DECL_VERBS = [
+  "directive",
+  "aggregate",
+  "query",
+  "count",
+  "sum",
+  "min",
+  "max",
+  "exists",
+  "spatial",
+  "workspaceInvariant",
+  "valueObject",
+  "derived",
+  "combined",
+  "first",
+  "take",
+  "relation",
+] as const;
+
+/** Escape a string for literal use inside a RegExp. */
+function escapeRe(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Compute the 1-based {line, column} of a character offset in `text` (column = chars into the line + 1). */
+function offsetToLineCol(text: string, offset: number): { line: number; column: number } {
+  let line = 1;
+  let lineStart = 0;
+  for (let i = 0; i < offset; i++) {
+    if (text.charCodeAt(i) === 10 /* \n */) {
+      line++;
+      lineStart = i + 1;
+    }
+  }
+  return { line, column: offset - lineStart + 1 };
+}
+
+/**
+ * A source map over a single domain's module files. Reads + memoizes the source text lazily and
+ * resolves an entity id (or an aggregate/whole-domain fallback) to a {@link SourceLocation}.
+ */
+export class DomainSourceMap {
+  private readonly texts = new Map<string, string | null>();
+
+  /** `files` — the ORDERED module paths composing the domain (config order; first is the fallback anchor). */
+  constructor(private readonly files: readonly string[]) {}
+
+  private text(file: string): string | null {
+    if (!this.texts.has(file)) {
+      try {
+        this.texts.set(file, readFileSync(file, "utf8"));
+      } catch {
+        this.texts.set(file, null);
+      }
+    }
+    return this.texts.get(file) ?? null;
+  }
+
+  /** The top-of-file fallback: line 1, column 1 of the domain's first readable module. */
+  private fallbackLocation(): SourceLocation | undefined {
+    const file = this.files[0];
+    if (file === undefined) return undefined;
+    return { file, line: 1, column: 1, fallback: true };
+  }
+
+  /**
+   * Locate the declaration of `id` across the domain's modules — the first `<verb>("<id>"…)` /
+   * `<verb>('<id>'…)` / <verb>(`<id>`…) match, scanned in config module order. Falls back to the top
+   * of the first module when `id` is undefined (a domain-wide finding) or cannot be located.
+   */
+  locate(id: string | undefined): SourceLocation | undefined {
+    if (id !== undefined) {
+      const idRe = escapeRe(id);
+      // <verb> ( <optional ws> <quote> id <same quote>  — the id as the first string arg of a decl call.
+      const verbs = DECL_VERBS.join("|");
+      const re = new RegExp(`\\b(?:${verbs})\\s*\\(\\s*(["'\`])${idRe}\\1`, "g");
+      for (const file of this.files) {
+        const text = this.text(file);
+        if (text === null) continue;
+        const m = re.exec(text);
+        if (m !== null) {
+          // Column points at the opening QUOTE of the id literal (m.index is at the verb).
+          const quoteOffset = m.index + m[0].length - id.length - 1;
+          const { line, column } = offsetToLineCol(text, quoteOffset);
+          return { file, line, column, fallback: false };
+        }
+        re.lastIndex = 0;
+      }
+    }
+    return this.fallbackLocation();
+  }
+}
+
+/** A source map over a whole package — one {@link DomainSourceMap} per domain key. */
+export class LawSourceMap {
+  private readonly perDomain = new Map<string, DomainSourceMap>();
+
+  /** `domainFiles` — domain key → its ORDERED module file paths (absolute), as the config declares them. */
+  constructor(domainFiles: ReadonlyMap<string, readonly string[]>) {
+    for (const [domain, files] of domainFiles) this.perDomain.set(domain, new DomainSourceMap([...files]));
+  }
+
+  /** Resolve a finding's `{domain, directiveId?}` to a source location, or `undefined` when unmappable. */
+  locate(domain: string, id?: string): SourceLocation | undefined {
+    return this.perDomain.get(domain)?.locate(id);
+  }
+}

package/src/lsp_main.ts

@@ -0,0 +1,14 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded QuickJS engine}.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * `githolon lsp` (stdio) — the language-server entry. Starts the author-time-gate server
+ * ({@link startServer}); it speaks LSP over stdin/stdout to any editor (VS Code, Neovim, …).
+ * Run under tsx (the launcher `lsp_server.mjs`) so it can import the tenant's TS domain modules
+ * in-process. See architecture/author_time_gate.md (slice 3).
+ */
+import { startServer } from "./lsp_server.js";
+
+startServer();

package/src/lsp_server.ts

@@ -0,0 +1,404 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded QuickJS engine}.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * `githolon lsp` — THE AUTHOR-TIME GATE AS A LANGUAGE SERVER (architecture/author_time_gate.md,
+ * slice 3). A thin `vscode-languageserver` (stdio) wrapper over the SAME static-twin machinery
+ * `githolon check` runs: on open/save/change of a `.ts` under a `nomos.package.mjs`'s domain graph,
+ * it composes the package IN-PROCESS (cache-busted TS re-import under tsx — no per-keystroke process
+ * spawn), runs {@link checkDomainModules}, maps findings to source ranges ({@link LawSourceMap}), and
+ * publishes diagnostics (refuse→Error, warn→Warning, note→Information).
+ *
+ * IN-PROCESS, not subprocess: spawning `check_package.mjs` (tsx+node cold start ≈ 150–300 ms) per
+ * keystroke is too slow for red squiggles. The check machinery is pure TS we import directly; the
+ * only cost is re-evaluating changed modules, which the `?t=` cache-bust query forces (proven under
+ * tsx). Composition is memoized per config keyed by the module files' mtimes so an UNCHANGED package
+ * re-checks without re-importing (the cheap warm win).
+ *
+ * Multi-root: each document resolves to its NEAREST `nomos.package.mjs` (walk up), so a repo with
+ * several packages diagnoses each against its own config.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL, fileURLToPath } from "node:url";
+
+import {
+  createConnection,
+  Diagnostic,
+  DiagnosticSeverity,
+  DidChangeConfigurationNotification,
+  StreamMessageReader,
+  StreamMessageWriter,
+  TextDocuments,
+  TextDocumentSyncKind,
+  type InitializeParams,
+} from "vscode-languageserver/node.js";
+import { TextDocument } from "vscode-languageserver-textdocument";
+
+import { composeDomainModule, type Mod } from "./build_package.js";
+import type { DomainModule } from "./codegen_dart.js";
+import { checkDomainModules, type Finding } from "./law_check.js";
+import { LawSourceMap } from "./law_source_map.js";
+import {
+  currentEvolveLaw,
+  evolveDiff,
+  evolveLawFromDeployJson,
+  evolveLawFromLockfile,
+  type EvolveLaw,
+  type StableIdLockfile,
+} from "./evolve_preview.js";
+
+interface DomainConfig {
+  key: string;
+  name?: string;
+  modules: string[];
+}
+interface PackageConfig {
+  name: string;
+  domains: DomainConfig[];
+}
+
+/** A finding enriched with the resolved source file (absolute) it belongs to. */
+interface LocatedFinding {
+  readonly finding: Finding;
+  readonly file: string;
+  readonly line: number; // 1-based
+  readonly column: number; // 1-based
+}
+
+/** The result of one package check pass. */
+export interface CheckPassResult {
+  /** Findings across the package, each located to a source file. */
+  readonly located: LocatedFinding[];
+  /** A load/compose error (bad config, module that failed to import) — reported on the config file. */
+  readonly error?: string;
+  /** The absolute module file paths in the package (so the caller can clear stale diagnostics). */
+  readonly files: string[];
+  /** The config file path (the anchor for a whole-package load error). */
+  readonly configPath: string;
+}
+
+/** Walk up from `startDir` to find the nearest `nomos.package.mjs`; `undefined` at the filesystem root. */
+export function findNearestConfig(startDir: string): string | undefined {
+  let dir = startDir;
+  for (;;) {
+    const candidate = path.join(dir, "nomos.package.mjs");
+    if (existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+/** A composed package + its provenance, memoized per config keyed by the module files' mtimes. */
+interface ComposedCache {
+  readonly mtimeKey: string;
+  readonly modules: DomainModule[];
+  readonly domainFiles: Map<string, string[]>;
+}
+const composedCache = new Map<string, ComposedCache>();
+
+function mtimeKey(files: readonly string[]): string {
+  return files
+    .map((f) => {
+      try {
+        return `${f}:${statSync(f).mtimeMs}`;
+      } catch {
+        return `${f}:missing`;
+      }
+    })
+    .join("|");
+}
+
+/**
+ * Compose a package's domain modules IN-PROCESS from its config. Cache-busts each `import()` so an
+ * edited module re-evaluates, and memoizes the whole composition by the module files' mtimes so an
+ * unchanged package returns instantly. Throws on a bad config / a module that fails to import.
+ */
+async function composePackage(
+  configPath: string,
+): Promise<{ modules: DomainModule[]; domainFiles: Map<string, string[]> }> {
+  const cfgDir = path.dirname(configPath);
+  const cfgModule = (await import(`${pathToFileURL(configPath).href}?t=${Date.now()}`)) as {
+    default?: PackageConfig;
+  };
+  const cfg = cfgModule.default;
+  if (!cfg || typeof cfg.name !== "string" || !Array.isArray(cfg.domains) || cfg.domains.length === 0) {
+    throw new Error("config must default-export { name, domains: [{ key, modules }, ...] }");
+  }
+
+  // Resolve every module file first so we can compute the mtime cache key before importing.
+  const perDomainFiles: { key: string; name: string | undefined; files: string[] }[] = [];
+  const allFiles: string[] = [];
+  for (const d of cfg.domains) {
+    if (typeof d.key !== "string" || !Array.isArray(d.modules) || d.modules.length === 0) {
+      throw new Error(`each domain needs { key, modules: [path, ...] }; got ${JSON.stringify(d)}`);
+    }
+    const files: string[] = [];
+    for (const rel of d.modules) {
+      const abs = path.resolve(cfgDir, rel);
+      if (!existsSync(abs)) throw new Error(`domain '${d.key}': module not found: ${abs}`);
+      files.push(abs);
+      allFiles.push(abs);
+    }
+    perDomainFiles.push({ key: d.key, name: d.name, files });
+  }
+
+  const key = `${statSync(configPath).mtimeMs}::${mtimeKey(allFiles)}`;
+  const cached = composedCache.get(configPath);
+  if (cached !== undefined && cached.mtimeKey === key) {
+    return { modules: cached.modules, domainFiles: cached.domainFiles };
+  }
+
+  const composed: DomainModule[] = [];
+  const domainFiles = new Map<string, string[]>();
+  for (const d of perDomainFiles) {
+    const mods: Mod[] = [];
+    for (const abs of d.files) {
+      mods.push((await import(`${pathToFileURL(abs).href}?t=${Date.now()}`)) as Mod);
+    }
+    domainFiles.set(d.key, d.files);
+    composed.push(composeDomainModule({ name: d.name ?? d.key, domain: d.key, modules: mods }));
+  }
+  composedCache.set(configPath, { mtimeKey: key, modules: composed, domainFiles });
+  return { modules: composed, domainFiles };
+}
+
+/** Load the `--against` prior evolve law from a deploy.json / build dir / lockfile (LSP variant — throws). */
+function loadPriorEvolveLaw(arg: string, cfgDir: string): EvolveLaw | undefined {
+  const abs = path.isAbsolute(arg) ? arg : path.resolve(cfgDir, arg);
+  if (!existsSync(abs)) return undefined;
+  let file = abs;
+  if (statSync(abs).isDirectory()) {
+    const buildDir = path.join(abs, "build");
+    const scan = (d: string): string | undefined => {
+      if (!existsSync(d)) return undefined;
+      const hit = readdirSync(d).find((f) => f.endsWith(".deploy.json"));
+      return hit !== undefined ? path.join(d, hit) : undefined;
+    };
+    const deploy = scan(abs) ?? scan(buildDir);
+    const lock = path.join(abs, "nomos.stable-ids.json");
+    if (deploy !== undefined) file = deploy;
+    else if (existsSync(lock)) file = lock;
+    else return undefined;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return undefined;
+  }
+  const p = parsed as Record<string, unknown>;
+  if (p.domains !== undefined && p.interface === undefined && p.packageUsda === undefined) {
+    return evolveLawFromLockfile(parsed as StableIdLockfile);
+  }
+  return evolveLawFromDeployJson(parsed as never);
+}
+
+/** Read the committed `nomos.stable-ids.json` lockfile beside the config (the CURRENT identity). */
+function loadCwdLockfile(cfgDir: string): StableIdLockfile | undefined {
+  const lockPath = path.join(cfgDir, "nomos.stable-ids.json");
+  if (!existsSync(lockPath)) return undefined;
+  try {
+    return JSON.parse(readFileSync(lockPath, "utf8")) as StableIdLockfile;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Run the full author-time check for one package config IN-PROCESS and locate every finding. `against`
+ * (optional, from `nomos.lsp.against`) folds the evolve-preview findings in. Never throws — a load
+ * error is returned as {@link CheckPassResult.error} so the LSP can surface it on the config file.
+ */
+export async function runCheckPass(configPath: string, against?: string): Promise<CheckPassResult> {
+  const cfgDir = path.dirname(configPath);
+  let modules: DomainModule[];
+  let domainFiles: Map<string, string[]>;
+  try {
+    ({ modules, domainFiles } = await composePackage(configPath));
+  } catch (e) {
+    return { located: [], error: (e as Error).message, files: [], configPath };
+  }
+
+  const findings: Finding[] = [...checkDomainModules(modules)];
+
+  if (against !== undefined && against.trim().length > 0) {
+    try {
+      const prior = loadPriorEvolveLaw(against, cfgDir);
+      if (prior !== undefined) {
+        const current = currentEvolveLaw(modules, loadCwdLockfile(cfgDir));
+        findings.push(...evolveDiff(prior, current).findings);
+      }
+    } catch {
+      /* evolve preview is best-effort — never block the base check */
+    }
+  }
+
+  const srcMap = new LawSourceMap(domainFiles);
+  const located: LocatedFinding[] = findings.map((f) => {
+    const loc = srcMap.locate(f.domain, f.directiveId);
+    return {
+      finding: f,
+      file: loc?.file ?? configPath,
+      line: loc?.line ?? 1,
+      column: loc?.column ?? 1,
+    };
+  });
+
+  const files: string[] = [];
+  for (const fs of domainFiles.values()) files.push(...fs);
+  return { located, files, configPath };
+}
+
+/** Map a finding level to an LSP diagnostic severity. */
+function severityOf(level: Finding["level"]): DiagnosticSeverity {
+  return level === "refuse"
+    ? DiagnosticSeverity.Error
+    : level === "warn"
+      ? DiagnosticSeverity.Warning
+      : DiagnosticSeverity.Information;
+}
+
+/** Build the diagnostic for a located finding — a range covering the declaration line's token. */
+function diagnosticFor(lf: LocatedFinding): Diagnostic {
+  const line = Math.max(0, lf.line - 1);
+  const col = Math.max(0, lf.column - 1);
+  return {
+    severity: severityOf(lf.finding.level),
+    range: { start: { line, character: col }, end: { line, character: col + 1 } },
+    source: "githolon",
+    message: `${lf.finding.what} — fix: ${lf.finding.fix}`,
+  };
+}
+
+/** Group located findings by absolute file path into LSP diagnostics. */
+export function groupDiagnostics(located: readonly LocatedFinding[]): Map<string, Diagnostic[]> {
+  const byFile = new Map<string, Diagnostic[]>();
+  for (const lf of located) {
+    const list = byFile.get(lf.file) ?? [];
+    list.push(diagnosticFor(lf));
+    byFile.set(lf.file, list);
+  }
+  return byFile;
+}
+
+/**
+ * Start the language server on stdio. Exported so the launcher (`lsp_main.ts`) and tests can drive it;
+ * the connection is created from `process.stdin`/`process.stdout` by default.
+ */
+export function startServer(): void {
+  // Bind explicitly to stdio (an editor may or may not pass `--stdio`; the streams are unambiguous).
+  const connection = createConnection(
+    new StreamMessageReader(process.stdin),
+    new StreamMessageWriter(process.stdout),
+  );
+  const documents = new TextDocuments(TextDocument);
+
+  let against: string | undefined;
+  // Per config: the set of files we last published diagnostics for (to clear stale ones on re-check).
+  const publishedByConfig = new Map<string, Set<string>>();
+  const debounceTimers = new Map<string, NodeJS.Timeout>();
+
+  connection.onInitialize((params: InitializeParams) => {
+    const init = params.initializationOptions as { against?: string } | undefined;
+    if (init?.against !== undefined) against = init.against;
+    return {
+      capabilities: {
+        textDocumentSync: TextDocumentSyncKind.Incremental,
+      },
+    };
+  });
+
+  connection.onInitialized(() => {
+    void connection.client
+      .register(DidChangeConfigurationNotification.type, undefined)
+      .catch(() => {/* client without config support — the initializationOptions value stands */});
+  });
+
+  connection.onDidChangeConfiguration((change) => {
+    const settings = change.settings as { nomos?: { lsp?: { against?: string } } } | undefined;
+    const next = settings?.nomos?.lsp?.against;
+    if (next !== undefined) {
+      against = next;
+      // Re-check every open TS document under a config.
+      for (const doc of documents.all()) scheduleCheck(doc.uri, 0);
+    }
+  });
+
+  /** Run the check for the config that owns `uri` and publish/clear diagnostics across the package. */
+  async function checkForUri(uri: string): Promise<void> {
+    let fsPath: string;
+    try {
+      fsPath = fileURLToPath(uri);
+    } catch {
+      return;
+    }
+    if (!fsPath.endsWith(".ts")) return;
+    const configPath = findNearestConfig(path.dirname(fsPath));
+    if (configPath === undefined) return;
+
+    const result = await runCheckPass(configPath, against);
+
+    if (result.error !== undefined) {
+      // A whole-package load error → one diagnostic on the config file.
+      connection.sendDiagnostics({
+        uri: pathToFileURL(configPath).href,
+        diagnostics: [
+          {
+            severity: DiagnosticSeverity.Error,
+            range: { start: { line: 0, character: 0 }, end: { line: 0, character: 1 } },
+            source: "githolon",
+            message: `githolon check could not load the package: ${result.error}`,
+          },
+        ],
+      });
+      return;
+    }
+    // Clear any prior config-file load error.
+    connection.sendDiagnostics({ uri: pathToFileURL(configPath).href, diagnostics: [] });
+
+    const byFile = groupDiagnostics(result.located);
+    const nowPublished = new Set<string>();
+    for (const [file, diags] of byFile) {
+      connection.sendDiagnostics({ uri: pathToFileURL(file).href, diagnostics: diags });
+      nowPublished.add(file);
+    }
+    // Clear diagnostics for files that had findings last time but are now clean.
+    const prev = publishedByConfig.get(configPath) ?? new Set<string>();
+    for (const file of prev) {
+      if (!nowPublished.has(file)) {
+        connection.sendDiagnostics({ uri: pathToFileURL(file).href, diagnostics: [] });
+      }
+    }
+    // Also make sure every module file with NO findings is cleared (fresh-open case).
+    for (const file of result.files) {
+      if (!nowPublished.has(file)) {
+        connection.sendDiagnostics({ uri: pathToFileURL(file).href, diagnostics: [] });
+      }
+    }
+    publishedByConfig.set(configPath, nowPublished);
+  }
+
+  function scheduleCheck(uri: string, delayMs: number): void {
+    const existing = debounceTimers.get(uri);
+    if (existing !== undefined) clearTimeout(existing);
+    debounceTimers.set(
+      uri,
+      setTimeout(() => {
+        debounceTimers.delete(uri);
+        void checkForUri(uri).catch((e) => connection.console.error(`githolon lsp: ${String(e)}`));
+      }, delayMs),
+    );
+  }
+
+  // Open + save are immediate; change is debounced (~500 ms) so we don't re-check every keystroke.
+  documents.onDidOpen((e) => scheduleCheck(e.document.uri, 0));
+  documents.onDidSave((e) => scheduleCheck(e.document.uri, 0));
+  documents.onDidChangeContent((e) => scheduleCheck(e.document.uri, 500));
+
+  documents.listen(connection);
+  connection.listen();
+}