dsh-loci 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the project follows
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html) from 1.0.0.
 
+## [2.2.0] — 2026-11-15
+
+Four reviewers of an independent blind review named the same risk: `engines.dsh`
+admits the whole `>=0.2.2-rc.1 <0.3.0-0` range, but the only version ever booted was
+`0.2.2-rc.1`. A range is a promise nobody tested.
+
+### Added
+
+- **`scripts/compat-probe.mjs`** — reads the *installed* Host out of its `app.asar`
+  and asserts that every API this plugin touches still exists in the expected shape:
+  the section contract (`interpolate: false`, `order`), the `tools`, `commands` and
+  `connection` services with their registration calls, and the `turn/end` event.
+  Run against the installed **0.2.2-rc.3**: **5/5 passed**. It is not a boot test,
+  and the docs now say exactly which question it answers and which it does not.
+
+- **The store records the Host that opened it.** `DSH_INSTALL_DIR` is read at
+  activation, the version lands in `meta.host_version`, `stats` exposes it, the panel
+  shows it, and `loci doctor` prints
+  `[ok] host: last opened by DeepSeek Harness 0.2.2-rc.3`. Every user install now
+  produces the evidence the next compatibility table needs, instead of leaving the
+  answer to a range in a manifest.
+
+- CI gained a conditional probe step: it runs where a Host is installed and prints a
+  skip notice otherwise (the Host is not published to npm, so a stock runner has
+  nothing to read).
+
+### Changed
+
+- `dshReleases` gained a `0.2.2-rc.3` row with status `api-surface-verified` — a
+  deliberate third status between "verified" (booted) and "untested", so a range
+  entry can never again imply more than was actually checked.
+
 ## [2.1.0] — 2026-11-15
 
 Two findings from an independent blind review, where seven reviewers compared this

package/client.js

@@ -1076,6 +1076,7 @@ window.__ModuleLoader__.load({
                 { className: 'loci-kv' },
                 h('dt', null, 'path'), h('dd', null, data.memoryRoot ?? '—'),
                 h('dt', null, 'schema'), h('dd', null, `v${data.schemaVersion}`),
+                h('dt', null, 'host'), h('dd', null, data.hostVersion ?? 'unknown'),
                 h('dt', null, 'vector'), h('dd', null, `${vs.mode ?? 'off'}${vs.healthy ? ' · healthy' : ''}${vs.lastError ? ` · ${vs.lastError}` : ''}`),
                 h('dt', null, 'last injection'),
                 h('dd', null, data.lastInjection ? `${data.lastInjection.bytes} B · ${data.lastInjection.listed} listed · ${data.lastInjection.hidden} hidden` : '—'),

package/docs/COMPATIBILITY.md

@@ -8,8 +8,39 @@
 | 0.2.2-rc.1 (host) | **24.22.3** | Ubuntu 24.04 (WSL2) | **verified** — manifest gate, 38/38 tests, coverage 82.93%, benchmark p95 5.28 ms at 2k | `scripts/run-linux-ci.sh` (fetches Node 24, runs the same commands as CI) |
 | 0.2.2-rc.1 (host) | 22.23.0 | Ubuntu 24.04 (WSL2) | **verified** — same suite × 3 consecutive runs | recorded in `docs/ACCEPTANCE.md` §6 |
 | 0.2.2-rc.1 | 24 | Ubuntu (GitHub Actions) | the identical step list runs in `.github/workflows/ci.yml`; the host is not published, so Actions has not run it | `.github/workflows/ci.yml` |
+| **0.2.2-rc.3** | 24.21.0 | Windows 11 | **API surface verified** — the source-signature probe passes 5/5 against the installed `app.asar`; not a boot test | `node scripts/compat-probe.mjs --asar <install>/resources/app.asar` |
 | other 0.2.x | — | — | not verified | — |
 
+### What "API surface verified" does and does not mean
+
+A range in `engines.dsh` is a promise nobody tested. `scripts/compat-probe.mjs`
+reads the **installed** host package out of the shipped `app.asar` and asserts that
+every Host API this plugin touches is still present in the shape it expects:
+
+```text
+host      : 0.2.2-rc.3
+[ok  ] systemPrompt sections        interpolate: false, order, section(
+[ok  ] tools service + register     super(ctx, "tools"), register(
+[ok  ] session turn/end event       "turn/end"
+[ok  ] commands service + register  super(ctx, "commands"), register(
+[ok  ] connection service           super(ctx, "connection")
+5/5 checks passed
+```
+
+It catches a renamed service, a changed section contract, or a moved event — the
+failures that would otherwise show up as "the plugin silently stopped injecting" on
+a version we never booted. It does **not** prove activation, tool registration at
+runtime, or injection on a live session; those still require a real host, and rc.3
+has not had one in this repository yet.
+
+The plugin also records the host version it meets: `DSH_INSTALL_DIR` is read at
+activation, the value lands in `meta.host_version`, and `loci doctor` prints
+`[ok] host: last opened by DeepSeek Harness 0.2.2-rc.3`. That turns every user
+install into evidence for the next compatibility table.
+
+CI runs the probe **when a host is present** and prints a skip notice otherwise
+(the host is not published to npm, so a stock runner has nothing to read).
+
 `scripts/run-linux-ci.sh` exists so the Linux claim is reproducible on any machine
 with WSL: it downloads the newest Node 24 tarball to `/tmp` (nothing is installed
 system-wide), then runs `check-manifest`, the unit+integration suite, the coverage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-loci",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Layered long-term memory for DeepSeek Harness: the prompt sees only a stable index, full text is one lookup away. Bi-temporal facts, strict scope isolation, verified-only injection.",
   "type": "module",
   "license": "MIT",
@@ -64,6 +64,15 @@
       ],
       "status": "verified",
       "evidence": "docs/COMPATIBILITY.md#022-rc1"
+    },
+    {
+      "dsh": "0.2.2-rc.3",
+      "node": "24.21.0",
+      "os": [
+        "win32"
+      ],
+      "status": "api-surface-verified",
+      "evidence": "docs/COMPATIBILITY.md#what-api-surface-verified-does-and-does-not-mean"
     }
   ],
   "dependencies": {

package/scripts/cli.mjs

@@ -39,6 +39,9 @@ const PLUGIN_VERSION = JSON.parse(
   readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
 ).version;
 
+/** The shipped manifest, read once: version for reports, engines for the host check. */
+const MANIFEST = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+
 const rawArgv = process.argv.slice(2);
 
 /**
@@ -129,7 +132,9 @@ const diagnosticScope = () => {
 
 switch (command) {
   case 'doctor': {
-    const result = await withStore((store) => runDoctor({ store, paths, config: effectiveConfig({ home }) }));
+    const result = await withStore((store) =>
+        runDoctor({ store, paths, config: effectiveConfig({ home }), engines: MANIFEST.engines }),
+      );
     if (json) console.log(JSON.stringify(result, null, 2));
     else console.log(formatDoctor(result));
     process.exitCode = result.status === 'fail' ? 1 : 0;

package/src/host/doctor.js

@@ -21,7 +21,7 @@ function check(name, status, detail) {
  * @returns `{status, checks, summary}` where status is the worst check status.
  */
 export function runDoctor(options) {
-  const { store, paths, config } = options;
+  const { store, paths, config, engines } = options;
   const checks = [];
 
   const health = (() => {
@@ -63,6 +63,19 @@ export function runDoctor(options) {
   const lastMaintenance = Number(health.migration?.to === undefined ? 0 : 0);
   checks.push(check('rows', 'ok', `${health.counts.memory} revisions · ${health.counts.memory_head} entries · ${health.counts.entity} entities`));
 
+  // Which Harness opened this store. A range in engines.dsh is a promise; this row
+  // is what actually happened, and it is the first thing to ask for in a bug report.
+  try {
+    const hostVersion = store.hostVersion ?? null;
+    checks.push(
+      hostVersion === null
+        ? check('host', 'warn', `not recorded yet; this build declares engines.dsh ${engines?.dsh ?? 'unknown'}`)
+        : check('host', 'ok', `last opened by DeepSeek Harness ${hostVersion}`),
+    );
+  } catch (error) {
+    checks.push(check('host', 'warn', `could not read: ${String(error?.message ?? error)}`));
+  }
+
   try {
     accessSync(paths.root, constants.W_OK);
     checks.push(check('data directory', 'ok', paths.root));

package/src/host/host-version.js

@@ -0,0 +1,89 @@
+/**
+ * Which Harness version are we actually running on?
+ *
+ * `engines.dsh` is a range; a range is a promise nobody tested. This module resolves
+ * the *installed* host package at activation time and records it, so the panel and
+ * `doctor` can say "running on 0.2.2-rc.3" instead of leaving the user to guess
+ * which point release the plugin met. It is best-effort by design: a plugin that
+ * refuses to boot because it cannot read someone else's package.json is worse than
+ * one that says "unknown".
+ *
+ * @module dsh-loci/host-version
+ */
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+const CANDIDATE_PATHS = [
+  // The Host normally resolves as a peer dependency of the profile.
+  '@deepseek-ai/dsh/package.json',
+  // Desktop bundles keep it one level down.
+  'dsh/package.json',
+];
+
+/**
+ * Resolve the installed host version.
+ *
+ * @param from - module URL to resolve relative to (defaults to this module).
+ * @returns `{version, path}` when found, `undefined` otherwise.
+ */
+export function detectHostVersion(from = import.meta.url) {
+  // The Host sets this to its own package directory, and the plugin runs inside the
+  // Host process, where reading an `app.asar/...` path works.
+  const installDir = process.env.DSH_INSTALL_DIR;
+  if (typeof installDir === 'string' && installDir.length > 0) {
+    try {
+      const manifest = JSON.parse(readFileSync(join(installDir, 'package.json'), 'utf8'));
+      if (typeof manifest?.version === 'string' && manifest.version.length > 0) {
+        return { version: manifest.version, path: join(installDir, 'package.json') };
+      }
+    } catch {
+      /* fall through to resolution */
+    }
+  }
+
+  let require;
+  try {
+    require = createRequire(from);
+  } catch {
+    return undefined;
+  }
+  for (const candidate of CANDIDATE_PATHS) {
+    try {
+      const resolved = require.resolve(candidate);
+      const manifest = JSON.parse(readFileSync(resolved, 'utf8'));
+      if (typeof manifest?.version === 'string' && manifest.version.length > 0) {
+        return { version: manifest.version, path: resolved };
+      }
+    } catch {
+      /* try the next candidate */
+    }
+  }
+  // Last resort: a sibling directory named `dsh` next to a cordis install.
+  try {
+    const resolved = require.resolve('@deepseek-ai/cordis/package.json');
+    const sibling = join(dirname(dirname(resolved)), 'dsh', 'package.json');
+    const manifest = JSON.parse(readFileSync(sibling, 'utf8'));
+    if (typeof manifest?.version === 'string') return { version: manifest.version, path: sibling };
+  } catch {
+    /* nothing else to try */
+  }
+  return undefined;
+}
+
+/**
+ * Compare a version against the `engines.dsh` range in one coarse way: does the
+ * major/minor line match what this build declares it supports?
+ *
+ * Deliberately not a semver implementation — the plugin has no dependency on one.
+ * It answers the only question that matters for a support message: "is this an
+ * untested point release inside our declared range, or a different line entirely?"
+ *
+ * @param version - the detected host version.
+ * @returns 'same-line' | 'other-line' | 'unknown'.
+ */
+export function hostLineOf(version) {
+  const match = /^(\d+)\.(\d+)\./.exec(String(version ?? ''));
+  if (match === null) return 'unknown';
+  return `${match[1]}.${match[2]}` === '0.2' ? 'same-line' : 'other-line';
+}

package/src/host/index.js

@@ -18,11 +18,12 @@ import { registerTools } from './tools/tools.js';
 import { registerApiRoutes } from './api/routes.js';
 import { UpdateChecker } from './update.js';
 import { Extractor, completeViaHost } from './extract/extractor.js';
+import { detectHostVersion, hostLineOf } from './host-version.js';
 import { registerCommands } from './commands.js';
 import { runDoctor } from './doctor.js';
 
 /** Version stamped into the database and diagnostics. */
-export const VERSION = '2.1.0';
+export const VERSION = '2.2.0';
 
 /** Optional collaborators; without them the plugin still serves tools. */
 export const inject = ['systemPrompt', 'tools'];
@@ -98,15 +99,30 @@ export function apply(ctx, rawConfig = {}) {
   log.info(`loci: using ${memoryRoot}`);
 
   let capture;
+  // Record which Harness this store is actually running on. `engines.dsh` is a
+  // range; this field is the only one that says which point release met the file,
+  // so a support report can be checked instead of guessed at.
+  const detectedHost = detectHostVersion();
   const store = new Store({
     memoryRoot,
     paths,
     config,
     log,
     pluginVersion: VERSION,
+    hostVersion: detectedHost?.version,
     live: read,
     quoteVerifier: (quote, options) => capture?.verifyQuote(quote, options) ?? false,
   });
+  if (detectedHost !== undefined) {
+    try {
+      store.db
+        .prepare("INSERT INTO meta (key, value) VALUES ('host_version', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value")
+        .run(detectedHost.version);
+    } catch {
+      /* recording is best effort */
+    }
+    log?.info?.(`loci: host ${detectedHost.version} (${hostLineOf(detectedHost.version)})`);
+  }
 
   const updates = new UpdateChecker({
     currentVersion: VERSION,

package/src/host/store/schema.js

@@ -160,6 +160,8 @@ export const META_KEYS = Object.freeze({
   createdAt: 'created_at',
   indexRev: 'index_rev',
   lastMaintenance: 'last_maintenance',
+  /** The Harness version this store has been used with, recorded at activation. */
+  hostVersion: 'host_version',
 });
 
 /**

package/src/host/store/store.js

@@ -123,6 +123,8 @@ export class Store {
     this.now = options.now ?? (() => Date.now());
     this.quoteVerifier = options.quoteVerifier ?? (() => false);
     this.pluginVersion = options.pluginVersion ?? '0.0.0';
+    /** Recorded host version, so support can see which point release met this store. */
+    this.hostVersion = options.hostVersion ?? undefined;
     this.readOnly = options.readOnly === true;
     this.db = openDatabase({ file: this.paths.db, readOnly: this.readOnly });
     this.audit = this.readOnly
@@ -1059,6 +1061,9 @@ export class Store {
       byStatus,
       byKind,
       byScope,
+      // Which Harness point release this store has met. A range in engines.dsh is a
+      // promise; this is the record of what actually opened the file.
+      hostVersion: this.hostVersion ?? readMeta(this.db, META_KEYS.hostVersion) ?? null,
       pendingCandidates: pending,
       disputed,
       lastInjection:

package/src/mcp/store-facade.js

@@ -36,7 +36,7 @@ export function openFacadeStore(options = {}) {
     memoryRoot: root,
     paths,
     config,
-    pluginVersion: '2.1.0',
+    pluginVersion: '2.2.0',
     readOnly: options.readOnly === true,
   });
   return { store, paths };