dsh-engram 0.4.0 → 0.5.1

package/lib/settings.js

@@ -1,27 +1,51 @@
 /**
  * dsh-engram: user settings binding (host half).
  *
- * Registers the `dsh-engram` settings namespace through DSH's own settings
- * service so the web GUI's Plugins configuration tab pairs the namespace with
- * the plugin's card automatically. Changes land live on `service.config`
- * (new sessions pick them up; blocks already frozen for a session stay frozen
- * by design — prefix stability wins over mid-session knobs).
+ * Two DSH settings generations are in the wild:
+ *  - ≤0.1.5 `settings.installSection(ctx, ns, schema, base, hooks)` mounts a
+ *    free-form namespace (`dsh-engram`) with its own storage + change hooks.
+ *  - ≥0.1.7 (and 0.2.x) forms are keyed by PROFILE ENTRY ID; editable fields
+ *    are `.volatile()` fields of the plugin's own `Config` schema, values live
+ *    in the profile row and hot-commit into the running volatile references
+ *    (`loader/volatile-update`), so the GUI card needs no separate mount call.
  *
- * The schema is schemastery (DSH's own schema engine), not zod: the settings
- * transport and the form renderers are all schemastery-native.
+ * This module therefore:
+ *  - exports `makeEngineConfigSchema(defaults)` — the plugin `Config`: every
+ *    DEFAULTS key so pre-existing profile-patch config survives schema
+ *    validation, with the curated SETTINGS_KEYS marked `.volatile()` so the
+ *    settings service exposes exactly the card's knobs as a form;
+ *  - `installEngramSettings` feature-detects the generation and exposes the
+ *    single `service.settings` seam `{ ns, describe, mutate, update }` the
+ *    `/api/dsh-engram/settings` routes use. The seam's `ns` is the ACTIVE
+ *    namespace — entry id `engram` on new DSH, legacy `dsh-engram` on old —
+ *    so the API layer never needs to know which generation it talks to.
+ *
+ * The client level keeps a stable wire label `dsh-engram`: api.js re-labels
+ * the describe view onto that label and lets the seam's active `ns` drive
+ * mutations, so the shipped client bundle works unchanged on both generations.
  */
 
 import z from "@deepseek-ai/schemastery";
 
-/** Namespace join key — must match the client card's `key`. */
+/** Active settings namespace on DSH ≥0.1.7 / 0.2.x — the profile ENTRY ID of
+ *  the plugin row (`id: engram` in cordis.patch.yml). Must match plugin name. */
+export const SETTINGS_NS = "engram";
+/** Legacy (≤0.1.5) free-form namespace, when installSection is present. */
+export const LEGACY_SETTINGS_NS = "dsh-engram";
+/** Stable wire label the client card filters on (unchanged across generations;
+ *  api.js re-labels the describe view onto it). */
+export const WIRE_SETTINGS_NS = "dsh-engram";
+/** Back-compat alias some call sites used for the old namespace constant. */
 export const SETTINGS_NS_NAME = "dsh-engram";
-// dsh-settings 0.1.5 exposes the namespace as a validated string at the
-// provider boundary; the legacy branding helper was removed.
-export const SETTINGS_NS = SETTINGS_NS_NAME;
 
 /** Fields the GUI exposes (a curated subset of the plugin DEFAULTS). */
 export const SETTINGS_KEYS = [
   "autoCapture",
+  "autoCapturePreferences",
+  "boundaryPrune",
+  "boundaryPruneThresholdChars",
+  "boundaryPruneIdleCadence",
+  "resultPack",
   "sessionSearch",
   "recallScope",
   "autoRecallOnStart",
@@ -58,6 +82,11 @@ export function settingsBaseFrom(defaults) {
 export function makeSettingsSchema(defaults) {
   return z.object({
     autoCapture: z.boolean().default(defaults.autoCapture),
+    autoCapturePreferences: z.boolean().default(defaults.autoCapturePreferences).description("用户纠正/偏好学习（零 LLM）：检测用户消息里的显式 prefer/avoid/switch-to 句式，自动沉淀为 preference 记忆并置顶 [ENGRAM] 索引（correx/PAHF 式偏好提取；关掉=只靠手动 engram_store）"),
+    boundaryPrune: z.boolean().default(defaults.boundaryPrune).description("ResultPack L1（BoundaryPrune 边界剪枝）：在 todo 完成推进 / goal 终态这些子任务边界，主动调用 DSH 的确定性 toolResultPruner 剪掉超阈值旧工具结果（SoL-Pi Online Context Compact；默认关）"),
+    boundaryPruneThresholdChars: z.natural().default(0).description("边界剪枝阈值覆盖（字符）：宿主 pruner 固定 8192；设更低（如 2048）可更早开剪——L0 仿真显示 T2048 净收益最高（+61.6Mc），前提是 L2 归档已开启可找回被剪中段；0=用宿主 8192"),
+    boundaryPruneIdleCadence: z.natural().default(0).description("空闲步数边界（请求计数）：最多每 N 个请求触发一次剪枝，覆盖无 todo/goal 的会话（约 62% 会话永不触发事件边界）；仍受偿还门约束；0=仅事件边界"),
+    resultPack: z.boolean().default(defaults.resultPack).description("ResultPack L2（结果归档召回）：BoundaryPrune 剪掉的中段脱敏归档到本地，剪枝节点尾部追加 handle，模型可用 result_recall(callId) 按页召回（完整 ObservationPack；需与 boundaryPrune 一起开，L2 本身默认关）"),
     sessionSearch: z.boolean().default(defaults.sessionSearch),
     recallScope: z.union(["workspace", "global"]).default(defaults.recallScope ?? "workspace").description("召回范围：workspace=严格按当前工作区隔离（默认、token 纪律）；global=本工作区命中弱/空时，从其它工作区池按 recency/origin 加权召回并标 [W:<workspace>] 来源。开启会打破跨工作区隔离，请按需选用"),
     autoRecallOnStart: z.boolean().default(defaults.autoRecallOnStart).description("新会话开始时，宿主按首条消息对工作区做确定性召回，把命中记忆直接注入 [RECALL] 块（无需模型自己想起调 engram_recall；关掉=回到纯拉取）"),
@@ -84,33 +113,80 @@ export function makeSettingsSchema(defaults) {
   });
 }
 
+/** schemastery prototype for ONE DEFAULTS entry, used for the plugin Config. */
+function configFieldType(value) {
+  if (typeof value === "boolean") return z.boolean();
+  if (typeof value === "number") return z.number();
+  if (typeof value === "string") return z.string();
+  if (Array.isArray(value)) return z.array(z.string());
+  return z.unknown();
+}
+
 /**
- * Wire the settings section into `ctx` and keep `live` (the plugin's mutable
- * config object) merged with what the user stored. Called from `apply()`.
+ * The plugin's full Config schema (schemastery), i.e. the schema DSH ≥0.1.7
+ * validates the `engram` profile row against and projects the settings form
+ * from.
+ *
+ * - EVERY DEFAULTS key is declared (non-volatile, with its default) so a
+ *   profile patch that sets an internal knob (e.g. `gcIntervalHours`,
+ *   `enabled`) survives schema validation instead of being stripped.
+ * - The curated SETTINGS_KEYS are additionally `.volatile()` — the settings
+ *   service then exposes exactly the card's knobs as an editable form keyed by
+ *   the entry id, and writes hot-commit into the running volatile references.
  *
- * When a `service` object is supplied, a normalized `service.settings` seam
- * ({ describe, mutate, update }) is exposed for the web API — this is the
- * single host-side adapter point: both the current and the legacy DSH
- * settings APIs reduce onto the same three calls, so `/api/dsh-engram/settings`
- * never needs to know which generation it is talking to.
+ * Exported as `Config` by lib/index.js (cordis reads `plugin.Config`).
+ */
+export function makeEngineConfigSchema(defaults) {
+  const fields = {};
+  for (const [key, value] of Object.entries(defaults)) {
+    let field = configFieldType(value).default(value);
+    if (SETTINGS_KEYS.includes(key)) field = field.volatile();
+    fields[key] = field;
+  }
+  return z.object(fields);
+}
+
+/**
+ * Wire the settings section into `ctx` and expose the normalized
+ * `service.settings` seam ({ ns, describe, mutate, update }) for the web API.
+ * Called from `apply()`.
+ *
+ * Generation-agnostic adapter (DSH ≥0.1.7 / 0.2.x on top):
+ *  - new DSH (≥0.1.7): the form is entry-keyed (`engram`) and its fields are
+ *    the plugin's volatile Config knobs — there is nothing to "mount":
+ *    `apply()` already received the validated volatile references and
+ *    re-syncs `live` on `loader/volatile-update`. The seam just forwards.
+ *  - legacy DSH (≤0.1.5): `installSection` mounts the free-form `dsh-engram`
+ *    namespace; the old onChange loop merges stored values onto `live`.
+ *
+ * When both APIs are absent (headless/other), the seam stays undefined and the
+ * /api/dsh-engram/settings routes answer 503 — same as before.
  */
 export function installEngramSettings(ctx, defaults, live, service) {
-  const base = settingsBaseFrom(defaults);
-  const schema = makeSettingsSchema(defaults);
-  let source = () => base;
   ctx.inject(["settings"], (settingsCtx) => {
-    // dsh-settings 0.1.5 moved the optional-consumer wiring onto the provider
-    // instance. Keeping the registration on the scoped context preserves the
-    // provider attach/detach lifecycle while avoiding a removed helper export.
     const provider = settingsCtx.settings;
-    if (service) {
-      service.settings = {
-        describe: () => provider.describe({ redactSecrets: true }),
-        mutate: (ns, ops, expectedRevision) => provider.mutate(ns, ops, expectedRevision),
-        update: (ns, patch, expectedRevision) => provider.update(ns, patch, expectedRevision),
-      };
+    if (!provider || typeof provider.describe !== "function") return;
+
+    // New generation: `configure()` exists and `installSection` is gone.
+    if (typeof provider.configure === "function") {
+      if (service) {
+        service.settings = {
+          ns: SETTINGS_NS,
+          describe: () => provider.describe({ redactSecrets: true }),
+          mutate: (ns, ops, expectedRevision) => provider.mutate(ns, ops, expectedRevision),
+          update: (ns, patch, expectedRevision) => provider.update(ns, patch, expectedRevision),
+        };
+      }
+      return;
     }
-    provider.installSection(ctx, SETTINGS_NS, schema, base, {
+
+    // Legacy generation: free-form namespace via installSection.
+    if (typeof provider.installSection !== "function") return;
+    const base = settingsBaseFrom(defaults);
+    const schema = makeSettingsSchema(defaults);
+    let source = () => base;
+    const ns = LEGACY_SETTINGS_NS;
+    provider.installSection(ctx, ns, schema, base, {
       setSource(current) {
         source = current;
       },
@@ -131,5 +207,13 @@ export function installEngramSettings(ctx, defaults, live, service) {
         void value;
       },
     });
+    if (service) {
+      service.settings = {
+        ns,
+        describe: () => provider.describe({ redactSecrets: true }),
+        mutate: (ns, ops, expectedRevision) => provider.mutate(ns, ops, expectedRevision),
+        update: (ns, patch, expectedRevision) => provider.update(ns, patch, expectedRevision),
+      };
+    }
   });
 }

package/lib/store.js

@@ -28,6 +28,7 @@ export const DOMAIN_VERSION = 1;
 
 /** Memory kinds, mapping to index prefixes. */
 const MEMORY_KINDS = [
+  "preference",
   "decision",
   "error",
   "procedure",

package/lib/tools.js

@@ -23,6 +23,7 @@ import { truncate, shortId, slugId, fmtDate, escapeLt, workspaceKey as wk, uuid
 import { hasCJK, searchSessionsCJK } from "./session-cjk.js";
 
 const KINDS = [
+  "preference",
   "decision",
   "error",
   "procedure",
@@ -99,7 +100,7 @@ function memoryLine(m, verbosity = "short", rel, homeWs) {
 }
 
 /** Stable kind display order for grouped recall output (matches MEMORY_KINDS). */
-const MEMORY_KIND_ORDER = ["decision", "error", "procedure", "fact", "insight", "handoff", "task"];
+const MEMORY_KIND_ORDER = ["preference", "decision", "error", "procedure", "fact", "insight", "handoff", "task"];
 
 /**
  * Render recall hits grouped by kind (MemoraX-style memory_type buckets):

package/lib/usage.js

@@ -7,8 +7,8 @@
  * on every engram/esr tool call, and a separate session-log scan that counted
  * tool calls (to include the built-in `todo` tool). Both are now ONE module:
  * both /stats and /toolstats answer from the canonical log stream
- * `~/.dsh/sessions/<bucket>/<sid>/session.jsonl.zstd`, decompressed on demand
- * with a short TTL cache. No tool call pays a write anymore (pure GUI-side
+ * `~/.dsh/sessions/<bucket>/<sid>/session[.v<N>].jsonl.zstd`, decompressed on
+ * demand with a short TTL cache. No tool call pays a write anymore (pure GUI-side
  * observability), and the log stream is the single source of truth.
  *
  * Zero external dependency: Node >=22.19 provides the zstd codec in
@@ -44,6 +44,49 @@ export function sessionsRoot() {
   return path.join(os.homedir(), ".dsh", "sessions");
 }
 
+/**
+ * Session log file names: current DSH stamps the session format version into
+ * the name (`session.v3.jsonl.zstd` on 0.1.x, `session.v4.jsonl.zstd` on 0.2);
+ * older releases used the unversioned `session.jsonl.zstd` (issue #8).
+ */
+const SESSION_LOG_RE = /^session(?:\.v\d+)?\.jsonl\.zstd$/;
+
+/**
+ * Resolve the log file inside one session directory.
+ *
+ * A directory normally holds exactly one log, but a session migrated across
+ * format versions can hold both a v3 and a v4 file (and a legacy unversioned
+ * one). The newest-mtime match wins — that is the file the host is currently
+ * appending to. When nothing matches, the historical unversioned name is
+ * returned so callers keep their existing ENOENT handling (`statSync` throws →
+ * session skipped) instead of silently scanning the wrong corpus.
+ */
+export function sessionLogFile(dir) {
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch {
+    return path.join(dir, "session.jsonl.zstd");
+  }
+  let best = null;
+  let bestMtime = -1;
+  for (const name of names) {
+    if (!SESSION_LOG_RE.test(name)) continue;
+    let st;
+    try {
+      st = fs.statSync(path.join(dir, name));
+    } catch {
+      continue; // unreadable entry: ignore
+    }
+    if (!st.isFile()) continue;
+    if (st.mtimeMs > bestMtime) {
+      bestMtime = st.mtimeMs;
+      best = name;
+    }
+  }
+  return path.join(dir, best ?? "session.jsonl.zstd");
+}
+
 /** Byte range of one structurally complete zstd frame in a concatenated stream. */
 function frameRanges(buffer) {
   const frames = [];
@@ -244,7 +287,7 @@ export function collectToolCounts({ root = sessionsRoot(), days = 14, now = Date
   for (const bucket of buckets) {
     const bdir = path.join(root, bucket);
     for (const sid of listDirOrEmpty(bdir)) {
-      const file = path.join(bdir, sid, "session.jsonl.zstd");
+      const file = sessionLogFile(path.join(bdir, sid));
       let st;
       try {
         st = fs.statSync(file);
@@ -330,7 +373,7 @@ export function collectUsageStats({ root = sessionsRoot(), days = 14, now = Date
   const buckets = listDirOrEmpty(root).filter((b) => b.startsWith("--"));
   for (const bucket of buckets) {
     for (const sid of listDirOrEmpty(path.join(root, bucket))) {
-      const file = path.join(root, bucket, sid, "session.jsonl.zstd");
+      const file = sessionLogFile(path.join(root, bucket, sid));
       let st;
       try {
         st = fs.statSync(file);

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "dsh-engram",
   "description": "Minimalist long-term memory for DeepSeek Harness, distilling symbolic-index + pi-esr ideas: zero-LLM auto-capture, a symbolic [ENGRAM] index with progressive disclosure, and an ESR-lite evidence-closure protocol (esr_task / esr_node / esr_close / esr_link). Real agent-behaviour telemetry (usage rollup + /stats) and a deterministic offline recall benchmark (npm run eval). Hot path is model-free; storage on ctx.storageDomain; web memory viewer, observability panel and config card through DSH's native settings slots.",
-  "version": "0.4.0",
+  "version": "0.5.1",
+  "packageManager": "pnpm@11.22.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -34,7 +35,7 @@
   ],
   "engines": {
     "node": ">=22.19.0",
-    "dsh": ">=0.1.2-alpha.2 <0.2.0-0"
+    "dsh": ">=0.1.2-alpha.2 <0.3.0-0"
   },
   "scripts": {
     "setup": "node scripts/setup-links.mjs",
@@ -74,12 +75,12 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-storage-domain": ">=0.1.2-alpha.2 <0.2.0-0",
-    "@deepseek-ai/dsh-settings": ">=0.1.2-alpha.2 <0.2.0-0",
+    "@deepseek-ai/dsh-storage-domain": ">=0.1.2-alpha.2 <0.3.0-0",
+    "@deepseek-ai/dsh-settings": ">=0.1.2-alpha.2 <0.3.0-0",
     "@deepseek-ai/schemastery": "^3.18.2",
-    "@deepseek-ai/dsh-compaction": ">=0.1.2-alpha.2 <0.2.0-0",
-    "@deepseek-ai/dsh-compaction-basic": ">=0.1.2-alpha.2 <0.2.0-0",
-    "@deepseek-ai/dsh-llm": ">=0.1.2-alpha.2 <0.2.0-0"
+    "@deepseek-ai/dsh-compaction": ">=0.1.2-alpha.2 <0.3.0-0",
+    "@deepseek-ai/dsh-compaction-basic": ">=0.1.2-alpha.2 <0.3.0-0",
+    "@deepseek-ai/dsh-llm": ">=0.1.2-alpha.2 <0.3.0-0"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/cordis": {

package/scripts/prepublish-check.mjs

@@ -24,8 +24,8 @@ const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const tmp = mkdtempSync(join(tmpdir(), "dsh-engram-pack-"));
 const PEERS = [
   "@deepseek-ai/cordis@^4.0.2",
-  "@deepseek-ai/dsh-settings@>=0.1.2-alpha.2 <0.2.0-0",
-  "@deepseek-ai/dsh-storage-domain@>=0.1.2-alpha.2 <0.2.0-0",
+  "@deepseek-ai/dsh-settings@>=0.1.2-alpha.2 <0.3.0-0",
+  "@deepseek-ai/dsh-storage-domain@>=0.1.2-alpha.2 <0.3.0-0",
   "@deepseek-ai/schemastery@^3.18.2",
 ];
 
@@ -85,8 +85,11 @@ try {
   const manifest = JSON.parse(readFileSync(join(installed, "package.json"), "utf8"));
   const host = await import(pathToFileURL(join(installed, manifest.main)).href);
   // resolveConfig is a deliberate public export (settings test builds the
-  // real DEFAULTS from it); widen the host surface consciously, not silently.
-  const expected = ["apply", "inject", "name", "resolveConfig"].sort().join(",");
+  // real DEFAULTS from it); Config is read by cordis as runtime.Config (the
+  // entry-id / volatile settings model); collectVolatileRefs/syncVolatileRefs
+  // back that model's live re-sync and are unit-tested directly. Widen the
+  // host surface consciously, not silently.
+  const expected = ["Config", "apply", "collectVolatileRefs", "inject", "name", "resolveConfig", "syncVolatileRefs"].sort().join(",");
   const actual = Object.keys(host).sort().join(",");
   if (actual !== expected) {
     throw new Error(`host exports mismatch: got ${actual}, want ${expected}`);