fix(plugin): support validated DSH 0.2 preview APIs

apps/memos-local-plugin/CHANGELOG.md

@@ -5,6 +5,15 @@ for the full per-commit history use `git log` or the GitHub releases page.
 
 ## Index
 
+- Unreleased — Admit DSH `0.1.7-rc.2`, `0.2.0-rc.2`, and `0.2.1-rc.2/rc.3`
+  through explicit, bounded optional peer ranges; retain the `2.0.21` V4
+  producer-owned message sources. Stop importing the moved `JsonValue` type
+  from `dsh-tools`, align the development host stack to `0.2.1-rc.3`, and
+  synchronize both package-manager lockfiles. Add an isolated compile/build/
+  adapter-test matrix with an installable `0.1.0-rc.6` legacy baseline; the
+  unavailable `0.1.0-rc.5` core packages are no longer advertised. npm `2.0.21`
+  still has the old startup version restriction until a new release ships.
+  Reinstall released packages instead of carrying hand-edited `dist/` patches.
 - `2.0.16` (unreleased) — Add the out-of-tree DeepSeek Harness Cordis
   bundle with capture, six memory tools, DSH profile-aware storage, and one
   automatic recall for every accepted, non-empty direct-user turn. Same-turn

apps/memos-local-plugin/adapters/deepseek-harness/COMPATIBILITY.md

@@ -0,0 +1,74 @@
+# DSH compatibility diagnosis and validation
+
+Validated on 2026-10-29, macOS arm64, Node.js 25.1.0, npm 11.6.2,
+pnpm 10.21.0. Scope: the local plugin; the Cloud plugin is separate.
+Related: MemOS issue #2520 and PR #2541.
+
+## Diagnosis
+
+The local plugin's six optional host-service peers excluded DSH 0.2.x.
+DSH 0.2.1 actively skips an incompatible bundle before mounting any plugin
+row. `failOnStartupError: false` cannot help because this check precedes
+the adapter's `apply()` function. The V4 message-source fix in 2.0.21 does
+not change this version gate.
+
+An independent compile against 0.2.1-rc.3 also failed with:
+
+```text
+tools.ts(4,27): error TS2614: Module '"@deepseek-ai/dsh-tools"' has no exported member 'JsonValue'.
+```
+
+The fix adds bounded prerelease comparator sets, replaces that moved type
+with the equivalent local JSON shape, and aligns the entire development
+stack and both lockfiles. The V4 source implementation is unchanged.
+The old rc.5 API baseline is no longer declared because its core packages
+cannot be retrieved from npm; rc.6 is the installable legacy baseline.
+
+## Regression evidence
+
+Before the manifest change, the package regression suite failed for all
+four newly targeted previews: 0.1.7-rc.2, 0.2.0-rc.2, 0.2.1-rc.2/rc.3.
+After the change, each of the five API stacks in `npm run test:dsh-compat`
+passed type checking, a TypeScript production build, and 71 adapter tests.
+The matrix installs the complete matching host peer graph, without borrowing
+DSH packages from the checkout. The native session admission/snapshot tests
+preserve the producer-owned recall source on the legacy and modern stacks.
+
+Official DSH 0.2.1-rc.3 CLI smoke test: install the published CLI with
+`--ignore-scripts` in a temporary directory; create an isolated `DSH_HOME`,
+initialize a `compat` profile from `web`, and register a staged local bundle
+in `dsh.profile.bundles`. Run `--profile compat --dump-config` with the old
+and new peer declarations, holding all other bundle files constant:
+
+| Declaration | Incompatible warning | MemOS row in composed tree |
+| --- | --- | --- |
+| Old `>=0.1.0-rc.5 <0.2.0` | Yes; exact-version exemption inactive | Absent |
+| New bounded ranges | No | Present |
+
+Both commands exit 0: exit status alone cannot detect a skipped bundle.
+No version exemption, live profile, credential, or customer session was used.
+The installed Desktop 0.2.0-rc.2 loader accepted both declarations, so it
+cannot reproduce the newer 0.2.1 startup gate.
+
+Other real command results:
+
+```text
+make format: All checks passed! / 630 files left unchanged
+npm test: Test Files 191 passed (191)
+          Tests 1655 passed | 3 skipped (1658)
+npm run lint: passed
+npm run build:package: passed (TypeScript and Viewer)
+npm ci --ignore-scripts --no-audit --no-fund: added 211 packages
+npm ls --all: exit 0, no invalid peers
+pnpm install --lockfile-only --frozen-lockfile --strict-peer-dependencies --ignore-scripts: passed
+npm run lock:check: SQLite 13.0.3 lock metadata verified
+```
+
+The first sandboxed full run failed when HTTP tests could not bind localhost
+(`listen EPERM`). The full result above comes from a rerun with local port
+access. Package installation scripts were disabled; the unchanged SQLite
+13.0.3 native build was reused for testing.
+
+These checks do not constitute a fresh authenticated model conversation on
+every Desktop/Web/CLI platform. The compatibility change is unreleased;
+installing npm 2.0.21 still has the old startup restriction.

apps/memos-local-plugin/adapters/deepseek-harness/README.md

@@ -7,11 +7,11 @@ background capture, and on-demand memory tools to a DSH profile without
 modifying the DSH repository.
 
 > [!IMPORTANT]
-> DeepSeek Harness is currently a developer preview. The initial compatibility
-> target for this adapter is DSH `0.1.0-rc.5`; record the exact DSH version in
-> every release's validation because later preview releases may require adapter
-> changes. Unit compilation and contract tests currently use the published DSH
-> `0.1.0-rc.6` packages; the end-to-end host below is the rc.5 source checkout.
+> DeepSeek Harness is currently a developer preview. The development API stack
+> is pinned to `0.2.1-rc.3`. The compatibility matrix compiles, builds, and tests
+> this adapter against the published `0.1.0-rc.6`, `0.1.7-rc.2`, `0.2.0-rc.2`,
+> `0.2.1-rc.2`, and `0.2.1-rc.3` packages. These are API/contract checks, not a
+> substitute for validating each packaged Desktop/Web/CLI release.
 
 ## How it works
 
@@ -115,9 +115,8 @@ the MemOS JSON-RPC bridge or a sidecar daemon.
 
 Prerequisites:
 
-- A Node.js version accepted by the DSH release. DSH `0.1.0-rc.5` requires
-  Node.js `^22.19.0 || >=24.0.0`; this stricter host requirement takes
-  precedence over the MemOS package's standalone `>=22` engine.
+- Node.js `>=22` in the actual host runtime, also satisfying the selected DSH
+  release's engine constraint. Desktop uses its bundled Node/Electron runtime.
 - A working DSH installation. The recommended one-command installer prepares
   an isolated `pnpm@11.7.0` for the install when pnpm is absent. Lower-level
   direct `dsh plugin` commands still require pnpm on `PATH`.
@@ -610,22 +609,66 @@ npx vitest run tests/unit/adapters/deepseek-harness-{bridge,host-llm,runtime}.te
 ```
 
 These tests use the published `@deepseek-ai/dsh-session-format-v3-to-v4`
-`0.2.0-rc.2` codec, without a DSH desktop installation, account, or network
+`0.2.1-rc.3` codec, without a DSH desktop installation, account, or network
 calls during testing. They check real recall and host-LLM messages through
 both `assertV4RowAdmission` and `encodeEvent`, including a pre-step inbox
 batch and rejection of retired `kind: "plugin"` sources. The codec is a dev
-dependency only. Its Cordis peer is satisfied by the development range;
-existing DSH brand/protocol peers remain pinned to the older adapter test
-stack. This validates V4 attribution, not general compatibility with every
-DSH API in the codec's release line.
+dependency only. All DSH development packages, including brand/protocol peers,
+use the same `0.2.1-rc.3` stack and Cordis `~4.0.5`.
+
+For the compatibility matrix, run:
+
+```sh
+npm run test:dsh-compat
+# Or select a specific published API stack:
+npm run test:dsh-compat -- 0.2.1-rc.3
+```
+
+The script needs npm registry access. It installs each real host peer graph in
+its own temporary directory, then type-checks and builds the plugin and runs
+the adapter tests. Non-host test/build dependencies reuse the checkout's
+installation. It retains fixtures for inspection and does not touch DSH
+profiles, credentials, sessions, or the checkout's dependency installation.
+The native session boundary tests also check that the producer-owned source
+survives the old host's admission and snapshot paths.
+
+## Version compatibility and upgrades
+
+The six optional DSH service peers intentionally declare separate prerelease
+lines:
+
+```text
+>=0.1.0-rc.6 <0.2.0 || >=0.1.7-rc.2 <0.1.8 || >=0.2.0-rc.2 <0.2.1 || >=0.2.1-rc.2 <0.2.2
+```
+
+npm semver only admits a prerelease when a comparator explicitly names its
+`major.minor.patch` tuple. Simply changing `<0.2.0` to `<0.3.0` would still
+exclude `0.2.1-rc.3`. Unvalidated `0.2.2` and `0.3.x` remain excluded.
+The former `0.1.0-rc.5` API baseline is no longer advertised: its core packages
+are unavailable from npm, so it cannot be revalidated by this matrix.
+
+There are two independent checks to distinguish:
+
+- **Startup: bundle skipped as incompatible.** Plugin `2.0.20` and `2.0.21`
+  declare peers below `0.2.0`; neither version's manifest admits DSH 0.2.x.
+  This change updates that declaration together with the adapter's moved JSON
+  type and synchronized npm/pnpm locks. It does not change the Cloud plugin.
+- **Runtime: V4 rejects `source.kind: "plugin"`.** Fixed in `2.0.21`; this
+  adapter retains that producer-owned source implementation and codec tests.
+
+After a release containing these compatibility changes is published, update
+the plugin in each DSH profile that uses it and fully restart that host. If
+you patched `dist/` by hand, reinstall the released package: a profile install
+can overwrite those patches. A successful `allow-version` exemption alone
+does not verify runtime compatibility. Until this change is released,
+installing npm `2.0.21` still leaves the startup version restriction in place.
 
 ## Known limitations
 
-1. **Developer-preview compatibility.** The initial compatibility target is
-   DSH `0.1.0-rc.5`; verify the packaged artifact against that exact host
-   before publishing results. Its optional DSH peer range is
-   `>=0.1.0-rc.5 <0.2.0`, but that range is not a guarantee across preview
-   breaking changes.
+1. **Developer-preview compatibility.** The supported prerelease lines and
+   repeatable API matrix are listed above. New DSH lines need explicit
+   validation before the peer range is expanded. Automated adapter tests do
+   not validate every platform's native dependencies or Desktop packaging.
 2. **Eventual consistency and abrupt-crash replay gap.** Per-turn foreground
    recall never waits for prior capture, relation, or intent work. A completed
    background result is visible to later automatic recalls and explicit tool

apps/memos-local-plugin/adapters/deepseek-harness/tools.ts

@@ -1,7 +1,7 @@
 /** Read-oriented MemOS tools exposed through DeepSeek Harness. */
 
 import type { Context } from "@deepseek-ai/cordis";
-import { defineTool, type JsonValue } from "@deepseek-ai/dsh-tools";
+import { defineTool } from "@deepseek-ai/dsh-tools";
 
 import type {
   RetrievalQueryDTO,
@@ -26,6 +26,12 @@ import {
   waitForDeepSeekHarnessDeadline,
 } from "./deadline.js";
 
+// DSH 0.2 moved JsonValue out of dsh-tools. Keep this structural output
+// boundary local so the adapter compiles with both the 0.1 and 0.2 APIs.
+type JsonValue = null | boolean | number | string | JsonValue[] | {
+  [key: string]: JsonValue;
+};
+
 export interface DeepSeekHarnessToolsOptions {
   core: MemoryCore;
   profileId: string;