dsh-engram 0.3.4 → 0.3.5

package/lib/tools.js

@@ -1,24 +1,25 @@
 /**
  * dsh-engram: model-facing tools.
  *
- * Eight small, tight-schema tools (deliberately fewer than the market's 8-12 —
- * tool schemas cost tokens in every request):
+ * Fourteen small, tight-schema tools (schemas cost tokens in every request):
  *   engram_store / engram_recall / engram_detail    — the engram memory surface
- *   esr_task / esr_node / esr_close / esr_link — the ESR-lite evidence surface
- *   esr_ready / esr_status                    — the pull surface (live state + hints)
- *   esr_gc                                    — pi-esr memory garbage collection
+ *   esr_task / esr_close / esr_link / esr_dep / esr_claim / esr_unclaim /
+ *   esr_node / esr_ready / esr_status / esr_gc / esr_model — ESR-lite surface
  *
  * Every call is recorded into the per-(workspace, day) usage rollup so the
  * GUI can report real ESR-proactivity and recall rates (see usage.js).
  *
  * All reads are deterministic local scans; `engram_recall` may additionally
- * fall back to `ctx.sessionQuery` FTS over past sessions when mounted.
+ * fall back to `ctx.sessionQuery` FTS over past sessions when mounted, and to
+ * a bounded CJK substring scan over the workspace's own session logs when the
+ * query is Chinese (see session-cjk.js).
  */
 
 import { z } from "zod";
 import { EngramError, hasCode } from "./store.js";
 import { buildEsrStatusView } from "./index-block.js";
 import { truncate, shortId, slugId, fmtDate, escapeLt, workspaceKey as wk, uuid } from "./util.js";
+import { hasCJK, searchSessionsCJK } from "./session-cjk.js";
 
 const KINDS = [
   "decision",
@@ -73,16 +74,20 @@ async function requireDomain(service) {
   }
 }
 
-function memoryLine(m, verbosity = "short") {
+function memoryLine(m, verbosity = "short", rel) {
   const tags = m.entity !== null ? ` · entity:${m.entity}` : "";
+  const relTail = rel
+    ? `${rel.supersededBy.has(m.id) ? ` · superseded by ${rel.supersededBy.get(m.id).id.slice(0, 8)}` : ""}${rel.contradictedBy.has(m.id) ? ` · contradicted by ${rel.contradictedBy.get(m.id).map((c) => c.id.slice(0, 8)).join(",")}` : ""}`
+    : "";
   if (verbosity === "full") {
     const access = m.lastAccessAt == null ? "never-accessed" : `lastAccess ${fmtDate(m.lastAccessAt)}`;
     const pathLine = m.filePath ? ` · path ${m.filePath}` : "";
-    return [`# ${m.id} [${m.kind}]`, escapeLt(m.text), `tags: ${(m.tags ?? []).join(", ")}${tags}`, `signal ${m.signal} · hits ${m.hits ?? 0} · ${fmtDate(m.createdAt)} · session ${m.sessionId}#${m.seq} · ${access}${pathLine}`, ""].join("\n");
+    const relLine = relTail.length > 0 ? relTail.trim() : "";
+    return [`# ${m.id} [${m.kind}]`, escapeLt(m.text), `tags: ${(m.tags ?? []).join(", ")}${tags}`, `signal ${m.signal} · hits ${m.hits ?? 0} · ${fmtDate(m.createdAt)} · session ${m.sessionId}#${m.seq} · ${access}${pathLine}${relLine ? ` · ${relLine}` : ""}`, ""].join("\n");
   }
   const date = fmtDate(m.createdAt ?? m.updatedAt);
   const path = m.filePath ? ` · ${truncate(m.filePath, 48)}` : "";
-  return `- ${m.id.slice(0, 8)} [${m.kind}] ${date} ${escapeLt(truncate(m.text, 200))}${tags}${m.hits > 0 ? ` · ×${m.hits}` : ""}${path}`;
+  return `- ${m.id.slice(0, 8)} [${m.kind}] ${date} ${escapeLt(truncate(m.text, 200))}${tags}${m.hits > 0 ? ` · ×${m.hits}` : ""}${path}${relTail}`;
 }
 
 /** Stable kind display order for grouped recall output (matches MEMORY_KINDS). */
@@ -95,7 +100,7 @@ const MEMORY_KIND_ORDER = ["decision", "error", "procedure", "fact", "insight",
  * Within a group the original (relevance) order is preserved; unknown kinds
  * (future-proof) trail the fixed order. Pure, deterministic.
  */
-function groupKindLines(items) {
+function groupKindLines(items, rel) {
   const buckets = new Map();
   for (const m of items) {
     const kind = typeof m.kind === "string" && m.kind.length > 0 ? m.kind : "unknown";
@@ -105,7 +110,7 @@ function groupKindLines(items) {
   const lines = [];
   const emit = (kind, group) => {
     lines.push(`## ${kind} (${group.length})`);
-    for (const m of group) lines.push(memoryLine(m));
+    for (const m of group) lines.push(memoryLine(m, "short", rel));
   };
   for (const kind of MEMORY_KIND_ORDER) if (buckets.has(kind)) emit(kind, buckets.get(kind));
   for (const [kind, group] of buckets) if (!MEMORY_KIND_ORDER.includes(kind)) emit(kind, group);
@@ -122,19 +127,21 @@ export function registerTools(ctx, service) {
       // ── engram_store ────────────────────────────────────────────────────
       registerTool({
         name: "engram_store",
-        description: "Store one memory: kind=(decision|error|procedure|fact|insight|handoff|task), text, optional entity anchor. Exact-duplicate text refreshes instead of adding; auto-capture already handles git/file/error events — use this for anything it misses.",
+        description: "Store one memory (kind, text, optional entity anchor + supersedes/contradicts id). Duplicate text refreshes; auto-capture covers git/file/error — use this for anything missed.",
         parameters: {
           type: "object",
           properties: {
             text: { type: "string", description: "Compact, information-dense memory text (required)" },
             ...p,
             file_path: { type: "string", description: "Optional absolute path this memory anchors to (e.g. the failing file)" },
+            supersedes: { type: "string", description: "Optional memory id this new statement replaces (old row stays, demoted in recall)" },
+            contradicts: { type: "string", description: "Optional memory id this new statement directly contradicts (both stay, flagged)" },
           },
           required: ["text"],
         },
         output: TEXT_OUTPUT,
         execute: async (raw, exec) => {
-          const args = parse(z.object({ text: z.string().min(1).max(2000), kind: z.enum(KINDS).optional(), tags: z.array(z.string()).optional(), entity: z.string().optional(), file_path: z.string().optional() }), raw, "engram_store");
+          const args = parse(z.object({ text: z.string().min(1).max(2000), kind: z.enum(KINDS).optional(), tags: z.array(z.string()).optional(), entity: z.string().optional(), file_path: z.string().optional(), supersedes: z.string().optional(), contradicts: z.string().optional() }), raw, "engram_store");
           const caller = callerOf(exec);
           const domain = await requireDomain(service);
           await domain.expireSweep(caller.cwd);
@@ -146,6 +153,8 @@ export function registerTools(ctx, service) {
               tags: args.tags ?? [],
               entity: args.entity ?? null,
               filePath: args.file_path ?? null,
+              supersedes: args.supersedes ?? null,
+              contradicts: args.contradicts ?? null,
               sessionId: caller.sessionId,
               seq: caller.seq,
               signal: 0.6,
@@ -161,14 +170,14 @@ export function registerTools(ctx, service) {
       // ── engram_recall ───────────────────────────────────────────────────
       registerTool({
         name: "engram_recall",
-        description: "Deterministic recall of this workspace's memories (BM25: exact tag first, recency ties). Literal, not semantic — query in the memory's likely language. query=filter, entity=timeline, search_sessions=true adds past-session FTS. limit/max_per_session/group_by_kind tune output.",
+        description: "Deterministic recall (BM25: exact tag first, recency ties). Literal, not semantic. query=filter, entity=timeline, search_sessions=true adds past-session FTS; limit/max_per_session/group_by_kind tune.",
         parameters: {
           type: "object",
           properties: {
             query: { type: "string", description: "Words to match against memory text and tags" },
             entity: { type: "string", description: "Return that entity's memories chronologically" },
             limit: { type: "integer", minimum: 1, maximum: 50, description: "Max memories (default 12)" },
-            max_per_session: { type: "integer", minimum: 1, maximum: 10, description: "Session-diversified cap: max memories kept per sessionId (default config.maxRecallPerSession=3; >1 sessions get to share the list)" },
+            max_per_session: { type: "integer", minimum: 1, maximum: 10, description: "Max memories kept per sessionId (default 3; sessions share the cap)" },
             group_by_kind: { type: "boolean", description: "Group recall hits by kind into sections (default true); false = one flat list" },
             search_sessions: { type: "boolean", description: "Also FTS search past sessions (requires the session-query index)" },
           },
@@ -196,7 +205,8 @@ export function registerTools(ctx, service) {
             items = domain.recall(caller.cwd, args.query, args.limit ?? 12, { maxPerSession });
             if (items.length === 0) zeroHits = true;
             lines.push(zeroHits ? `no active memories match ${JSON.stringify(args.query)} in this workspace` : `# recall: ${JSON.stringify(args.query)} (${items.length}) · ≤${maxPerSession}/session`);
-            lines.push(...(args.group_by_kind === false ? items.map((m) => memoryLine(m)) : groupKindLines(items)));
+            const rel = domain.memoryRelations(caller.cwd);
+            lines.push(...(args.group_by_kind === false ? items.map((m) => memoryLine(m, "short", rel)) : groupKindLines(items, rel)));
             await Promise.all(items.map((m) => domain.touchMemory(caller.cwd, m.id).catch(() => null)));
           } else {
             items = domain.listMemories(caller.cwd, args.limit ?? 12);
@@ -217,9 +227,23 @@ export function registerTools(ctx, service) {
           }
           const wantSessions = args.search_sessions === true || (zeroHits && service.config.sessionSearch !== false);
           if (wantSessions) {
-            const extra = await searchSessions(service, caller, args.query ?? args.entity ?? "", exec.signal);
-            if (extra.length > 0) lines.push("", "# past sessions (FTS fallback)", ...extra);
-            else if (zeroHits && lines.length === 1) lines[0] += " (no past-session hits either)";
+            const q = args.query ?? args.entity ?? "";
+            const extra = await searchSessions(service, caller, q, exec.signal);
+            if (extra.length > 0) {
+              lines.push("", "# past sessions (FTS fallback)", ...extra);
+            } else if (hasCJK(q)) {
+              // The host FTS index is tokenizer-blind to Chinese (unicode61
+              // keeps CJK runs as single tokens), so supplement it with a
+              // bounded substring scan over this workspace's own sessions.
+              const cjk = searchSessionsCJK({ cwd: caller.cwd, query: q });
+              if (cjk.length > 0) {
+                lines.push("", "# past sessions (CJK substring scan)", ...cjk.map((h, i) => `${i + 1}. session ${h.sessionId} · ${truncate(h.snippet, 160)}`));
+              } else if (zeroHits && lines.length === 1) {
+                lines[0] += " (no past-session hits either)";
+              }
+            } else if (zeroHits && lines.length === 1) {
+              lines[0] += " (no past-session hits either)";
+            }
           }
           return lines.join("\n");
         },
@@ -228,7 +252,7 @@ export function registerTools(ctx, service) {
       // ── engram_detail ───────────────────────────────────────────────────
       registerTool({
         name: "engram_detail",
-        description: "Full record of one memory id (from engram_recall): text, tags, entity, signal, hits, provenance session#seq.",
+        description: "Full record of one memory id: text, tags, entity, signal, hits, session#seq provenance.",
         parameters: {
           type: "object",
           properties: {
@@ -245,21 +269,21 @@ export function registerTools(ctx, service) {
           const m = domain.getMemory(caller.cwd, id);
           if (m === void 0) throw new EngramError("ENGRAM_NOT_FOUND", `no active memory "${args.id}" in this workspace`);
           await domain.touchMemory(caller.cwd, m.id).catch(() => null);
-          return memoryLine(m, "full");
+          return memoryLine(m, "full", domain.memoryRelations(caller.cwd));
         },
       }),
 
       // ── esr_task ──────────────────────────────────────────────────────
       registerTool({
         name: "esr_task",
-        description: "Create/update an engineering task (draft→active). A task is only 'done' with evidence — finish via esr_close (artifact + evaluation + memory_ref). Set id to update an existing task. Pass entity= to auto-create the node and link the task onto it (one call instead of esr_node+esr_link).",
+        description: "Create/update an engineering task (draft→active). Done only with evidence — esr_close (artifact+evaluation+memory_ref). id=update; entity=auto-create node + relates_to link.",
         parameters: {
           type: "object",
           properties: {
             name: { type: "string", description: "Task name (required on create)" },
             description: { type: "string", description: "What must be produced / satisfied" },
             id: { type: "string", description: "Existing task id to update" },
-            entity: { type: "string", description: "Optional domain object to hang this task on — auto-creates ent_<slug> node and links task --relates_to--> it" },
+            entity: { type: "string", description: "Domain object to hang this task on — auto-creates ent_<slug> node + task --relates_to--> edge" },
           },
           required: ["name"],
         },
@@ -307,12 +331,12 @@ export function registerTools(ctx, service) {
       // ── esr_close ─────────────────────────────────────────────────────
       registerTool({
         name: "esr_close",
-        description: "Close a task via the ESR evidence protocol: requires artifact (path/url), evaluation (how verified) and memory_ref (memory ids) — missing gates keep it active; force:true skips the on-disk artifact check. Auto-stores a closing memory.",
+        description: "Close a task via the ESR evidence protocol: artifact (path/url) + evaluation + memory_ref — missing gates keep it active; force:true skips the disk check. Stores a closing memory.",
         parameters: {
           type: "object",
           properties: {
             task_id: { type: "string", description: "Task id from [ESR] or esr_task" },
-            artifact: { type: "string", description: "Produced artifact (path/url). Paths are resolved against the workspace and must exist on disk unless force:true" },
+            artifact: { type: "string", description: "Produced artifact path/url. Resolved against workspace; must exist on disk unless force:true" },
             evaluation: { type: "string", description: "Verification evidence (test/review/benchmark)" },
             memory_refs: { type: "array", items: { type: "string" }, description: "Memory ids that record the decisions made" },
             force: { type: "boolean", description: "Skip the on-disk artifact existence check (gates are still required)" },
@@ -369,7 +393,7 @@ ${hint}` : ""}`;
       // ── esr_link ──────────────────────────────────────────────────────
       registerTool({
         name: "esr_link",
-        description: "Add a typed relation between two entities (depends_on/implements/refines/contradicts…). Feeds entity queries and the workspace link count.",
+        description: "Add a typed relation between entities (depends_on/implements/refines/contradicts…). Feeds entity queries + link count.",
         parameters: {
           type: "object",
           properties: {
@@ -403,7 +427,7 @@ ${hint}` : ""}`;
 
       registerTool({
         name: "esr_dep",
-        description: "Add a dependency edge between tasks: blocks (waits until dep closes), parent-of (child), relates-to (no blocking). Refuses self-deps and cycles.",
+        description: "Add a dependency edge between tasks: blocks (until dep closes), parent-of (child), relates-to (no blocking). Refuses self-deps/cycles.",
         parameters: {
           type: "object",
           properties: {
@@ -444,7 +468,7 @@ ${hint}` : ""}`;
       // ── esr_claim / esr_unclaim ─────────────────────────────────────
       registerTool({
         name: "esr_claim",
-        description: "Atomically claim a task (assignee+claimedAt, draft→active). Refuses when another agent holds it unless force:true. Find work with esr_ready.",
+        description: "Atomically claim a task (draft→active, assignee+claimedAt). Refuses when another agent holds it unless force:true. Find work with esr_ready.",
         parameters: {
           type: "object",
           properties: {
@@ -467,7 +491,7 @@ ${hint}` : ""}`;
       }),
       registerTool({
         name: "esr_unclaim",
-        description: "Release a claimed task's assignee back to null. Non-holder needs force:true. Inverse of esr_claim.",
+        description: "Release a claimed task's assignee to null. Non-holder needs force:true. Inverse of esr_claim.",
         parameters: {
           type: "object",
           properties: {
@@ -516,12 +540,12 @@ ${hint}` : ""}`;
       registerTool({
         name: "esr_status",
         description:
-          "Pull the live ESR state (deterministic snapshot + revision) plus decision-point hints (promote / root-cause / close / stale / escalate). Pass since_revision to skip unchanged state — returns a short response when nothing changed. The [ESR] block in the prompt is a session-start snapshot that never auto-refreshes; call this for the current truth.",
+          "Live ESR state (deterministic snapshot + revision) + decision-point hints (promote/root-cause/close/stale/escalate). Pass since_revision to skip unchanged state (short response). Prompt [ESR] is a frozen session-start snapshot — call this for current truth.",
         parameters: {
           type: "object",
           properties: {
             workspace: { type: "string", description: "Override the workspace key (default: current session cwd)" },
-            since_revision: { type: "string", description: "Last-seen ESR revision (from a previous esr_status response); unchanged state returns a short response" },
+            since_revision: { type: "string", description: "Last-seen ESR revision; unchanged state returns a short response" },
           },
         },
         output: TEXT_OUTPUT,
@@ -542,7 +566,7 @@ ${hint}` : ""}`;
       // ── esr_node ─────────────────────────────────────
       registerTool({
         name: "esr_node",
-        description: "Create/update an entity node — stable symbol for a recurring thing (package/service/doc/repo/person/bug/concept). Nodes anchor esr_link relations and memory entity. Same name updates; id = ent_<slug>.",
+        description: "Create/update an entity node — stable symbol for a recurring thing (package/service/doc/repo/person…). Anchors esr_link + memory entity; same name updates; id=ent_<slug>.",
         parameters: {
           type: "object",
           properties: {
@@ -584,7 +608,7 @@ ${hint}` : ""}`;
       // ── esr_gc ────────────────────────────────────────────────────────
       registerTool({
         name: "esr_gc",
-        description: "Run memory GC: archives TTL-expired, over-cap low-retention memories, stable tasks past retention, dangling links. Working set protected; archive-only (nothing hard-deleted). dry_run:true previews.",
+        description: "Run memory GC: archives TTL-expired, over-cap low-retention memories, stable tasks past retention, dangling links. Working set protected; archive-only, never hard-deletes. dry_run previews.",
         parameters: {
           type: "object",
           properties: {
@@ -605,7 +629,7 @@ ${hint}` : ""}`;
       // ── esr_model ─────────────────────────────────────────────────────
       registerTool({
         name: "esr_model",
-        description: "Precomputed mental model of the workspace (task counts, entity graph, top evidence-grounded beliefs, risks). Zero LLM. mode=brief → ~50-token one-liner; max_chars trims. Read before scattering recall.",
+        description: "Precomputed mental model (task counts, entity graph, top evidence-grounded beliefs, risks). Zero LLM. mode=brief → one-liner; max_chars trims. Read before scattering recall.",
         parameters: {
           type: "object",
           properties: {

package/lib/trigger.js

@@ -97,6 +97,8 @@ export function pendingTodos(args) {
 export function makeTriggerRecorder(config = {}) {
   const minTodosForPromote = config.minTodosForPromote ?? 2;
   const todoPromoteRatio = config.todoPromoteRatio ?? 1;
+  // Injectable clock (deterministic unit tests): default to the wall clock.
+  const now = typeof config.now === "function" ? config.now : Date.now;
   /** workspace -> Map<day, {mem, esr}> (live balance, replaces dead usage table). */
   const usage = new Map();
   /** workspace -> { sessionId, count, names, updatedAt } (pending-todo plan). */
@@ -130,7 +132,7 @@ export function makeTriggerRecorder(config = {}) {
     cur[key] += 1;
     buckets.set(day, cur);
     if (buckets.size > BALANCE_DAYS + 2) {
-      const oldest = dayKey(Date.now() - BALANCE_DAYS * DAY_MS);
+      const oldest = dayKey(now() - BALANCE_DAYS * DAY_MS);
       for (const d of [...buckets.keys()]) if (d < oldest) buckets.delete(d);
     }
     if (usage.size > WORKSPACE_CAP) {
@@ -160,7 +162,7 @@ export function makeTriggerRecorder(config = {}) {
       record(name, workspace);
       // P4 conversion: an esr_* call inside the window converts this
       // workspace's most recent pending hint.
-      if (ESR_TOOLS.includes(name)) attributeConversion(workspace, Date.now());
+      if (ESR_TOOLS.includes(name)) attributeConversion(workspace, now());
       if (name !== "todo_write") return;
       // Snapshot this session's pending plan. When a plan that had pending
       // todos transitioned to a fully-completed list, that is a natural
@@ -168,7 +170,7 @@ export function makeTriggerRecorder(config = {}) {
       const names = pendingTodos(exec?.arguments);
       const prev = todos.get(workspace);
       const prevCount = prev !== void 0 && prev.sessionId === sessionId ? prev.count : -1;
-      todos.set(workspace, { sessionId, count: names.length, names, updatedAt: Date.now() });
+      todos.set(workspace, { sessionId, count: names.length, names, updatedAt: now() });
       if (prevCount > 0 && names.length === 0) {
         workDone.add(`${workspace}::${sessionId}`);
       }
@@ -188,7 +190,7 @@ export function makeTriggerRecorder(config = {}) {
   function recentBalance(workspace) {
     const buckets = usage.get(workspace);
     if (buckets === void 0) return { memCalls: 0, esrCalls: 0, days: 0 };
-    const oldest = dayKey(Date.now() - BALANCE_DAYS * DAY_MS);
+    const oldest = dayKey(now() - BALANCE_DAYS * DAY_MS);
     let memCalls = 0;
     let esrCalls = 0;
     let days = 0;
@@ -225,7 +227,7 @@ export function makeTriggerRecorder(config = {}) {
 
   /** Drop hints past the conversion window (or when already attributed). */
   function prunePending() {
-    const cutoff = Date.now() - CONVERSION_WINDOW_MS;
+    const cutoff = now() - CONVERSION_WINDOW_MS;
     for (let i = pending.length - 1; i >= 0; i--) {
       if (pending[i].shownAt < cutoff) pending.splice(i, 1);
     }
@@ -243,7 +245,7 @@ export function makeTriggerRecorder(config = {}) {
     if (hintSeen.has(key)) return;
     hintSeen.add(key);
     bumpCount(shownCounts, workspace, kind, 1);
-    pending.push({ kind, ws: workspace, session: sessionId, shownAt: Date.now() });
+    pending.push({ kind, ws: workspace, session: sessionId, shownAt: now() });
     prunePending();
   }
 
@@ -368,8 +370,8 @@ export function makeTriggerRecorder(config = {}) {
       const key = `${workspace}::${sessionId}::${t.id}`;
       if (staleSeen.has(key)) continue;
       staleSeen.add(key);
-      const at = t.updatedAt ?? t.createdAt ?? Date.now();
-      const days = Math.max(1, Math.round((Date.now() - at) / DAY_MS));
+      const at = t.updatedAt ?? t.createdAt ?? now();
+      const days = Math.max(1, Math.round((now() - at) / DAY_MS));
       return `stale: ${t.id.slice(0, 6)} · ${truncate(t.name, 40)} — no update ${days}d, esr_close with evidence or drop the intent ${HINT_TAGS.stale}`;
     }
     return "";

package/lib/usage.js

@@ -47,6 +47,7 @@ function decodeZstd(file) {
     return "";
   }
 }
+export { decodeZstd };
 
 function listDirOrEmpty(dir) {
   try {