@yeaft/webchat-agent 0.1.635 → 0.1.637

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.635",
+  "version": "0.1.637",
   "description": "Remote agent for Yeaft WebChat — connects worker machines to the central server",
   "main": "index.js",
   "type": "module",

package/unify/compact/orchestrator.js

@@ -28,7 +28,7 @@
  */
 
 import { groupTurns, pickCoolingGroups, indicesFromGroups } from './turn-group.js';
-import { writeSummary } from '../memory/scope-tree.js';
+import { writeSummary } from '../memory/store-v2.js';
 
 /**
  * @typedef {{

package/unify/engine.js

@@ -30,7 +30,7 @@ import { archiveTurn } from './archive/turn-archive.js';
 import { archiveToolResults } from './archive/tool-results.js';
 import { buildMemoryInjection } from './memory/layout.js';
 import { buildUserProfile } from './memory/user-memory-store.js';
-import { readSummary as readScopeSummary } from './memory/scope-tree.js';
+import { readSummary as readScopeSummary } from './memory/store-v2.js';
 import { runStopHooks } from './stop-hooks.js';
 import { getThreadStore, MAIN_THREAD_ID } from './threads/store.js';
 import { pickEffort, parseEffortPrefix } from './effort.js';

package/unify/index.js

@@ -23,15 +23,10 @@ export { Engine } from './engine.js';
 export { ConversationStore, parseMessage, estimateTokens } from './conversation/persist.js';
 export { searchMessages } from './conversation/search.js';
 export { MemoryStore, parseEntry, serializeEntry, MEMORY_KINDS } from './memory/store.js';
-export { recall, extractKeywords, computeFingerprint, clearRecallCache } from './memory/recall.js';
-export { extractMemories } from './memory/extract.js';
-export { consolidate, shouldConsolidate } from './memory/consolidate.js';
 
 // Phase 5: Advanced features
 export { KINDS, KIND_PRIORITY, KIND_DESCRIPTIONS, IMPORTANCE_LEVELS, validateEntry, parseScopePath, getAncestorScopes, areScopesRelated } from './memory/types.js';
 export { scanEntries, scoreEntry, findStaleEntries, findDuplicateGroups, summarizeScan } from './memory/scan.js';
-export { dream, checkDreamGate, readDreamState, writeDreamState, incrementQueryCount } from './memory/dream.js';
-export { buildOrientPrompt, buildGatherPrompt, buildMergePrompt, buildPrunePrompt, buildPromotePrompt } from './memory/dream-prompt.js';
 export { runStopHooks } from './stop-hooks.js';
 export { MCPManager, createMCPManager } from './mcp.js';
 export { SkillManager, createSkillManager, parseSkill, serializeSkill } from './skills.js';

package/unify/memory/dream-scheduler.js

@@ -24,8 +24,6 @@
 import { dreamShard } from './dream-shard.js';
 import { checkRecompression } from './recompression.js';
 import { runUserDreamJob } from './user-memory-store.js';
-import { runDreamTick } from '../dream-v2/tick.js';
-import { createScopeRefreshHook } from '../dream-v2/refresh.js';
 
 /** Default idle timeout before dream triggers (ms). */
 export const DREAM_IDLE_MS = 30 * 60 * 1000; // 30 min
@@ -160,34 +158,12 @@ export function createDreamScheduler(opts = {}) {
         // Non-fatal
       }
 
-      // Phase 8 PR-F: dream-v2 diff-gated scope-summary refresh
-      // (DESIGN.md §9.14). The legacy dreamShard pipeline above
-      // refreshed shard summaries; this final tick walks the scope
-      // tree (user/group/vp/task), computes per-scope sigs, and only
-      // re-runs the refresh hook for scopes whose content changed.
-      // Refresh-only in v1 (no prune/demote — DESIGN §8 line 395).
-      if (memoryDir) {
-        try {
-          const scopes = [{ kind: 'user', scopeDir: 'user' }];
-          if (group?.id) scopes.push({ kind: 'group', id: group.id, scopeDir: `groups/${group.id}` });
-          // PR-J: real refresh hook — read each scope's `index.md`,
-          // render a deterministic top-N synopsis, atomically write
-          // `summary.md`. No LLM, refresh-only (DESIGN.md §8 line 395).
-          const refresh = createScopeRefreshHook({ root: memoryDir });
-          const tickResult = await runDreamTick({
-            root: memoryDir,
-            scopes,
-            refresh,
-          });
-          result.dreamV2Tick = {
-            ran: tickResult.ran.length,
-            skipped: tickResult.skipped.length,
-            errors: tickResult.errors.length,
-          };
-        } catch {
-          // Non-fatal
-        }
-      }
+      // Phase 8 PR-F dream-v2 diff-gated scope-summary refresh has been
+      // removed (DESIGN-v2 §13: replaced by 12h / manual trigger model).
+      // The new v2 dream pipeline lives in dream-v2/runner.js, wired via
+      // dream-v2/session-wiring.js when config.memoryV2 is on. This
+      // legacy scheduler only runs for memoryV2=false and is itself
+      // slated for deletion alongside the rest of the R6 stack.
 
       messagesSinceLastDream = 0;
       lastDreamAt = Date.now();

package/unify/router/vp-planner.js

@@ -36,7 +36,7 @@
  *   }
  */
 
-import { isVpForeign } from '../memory/scope-tree.js';
+import { isVpForeign } from '../memory/store-v2.js';
 
 /** @typedef {{ userOriginal: string, intent: string }} ForwardQuery */
 /** @typedef {{ memoryPaths: string[], taskIds: string[] }} Preselect */

package/unify/session.js

@@ -37,8 +37,9 @@ import { seedDefaultVps } from './vp/seed-defaults.js';
 import { createDreamScheduler } from './memory/dream-scheduler.js';
 import { createV2DreamScheduler } from './dream-v2/session-wiring.js';
 import { getUserMemoryStore } from './memory/user-memory-store.js';
+import { migrateR6toV2 } from './memory/migrate-r6-to-v2.js';
 import { join } from 'path';
-import { existsSync as existsSyncSafe, readFileSync as readFileSyncSafe } from 'fs';
+import { existsSync as existsSyncSafe, readFileSync as readFileSyncSafe, writeFileSync as writeFileSyncSafe } from 'fs';
 
 /**
  * @typedef {Object} SessionOptions
@@ -135,6 +136,54 @@ export async function loadSession(options = {}) {
     }
   } catch { /* never let this warn path block session load */ }
 
+  // ─── 2.2 Auto-migrate R6 → v2 on first boot with memoryV2=on ──
+  //         If `memoryV2` is on AND a R6-shaped tree is on disk AND we
+  //         haven't already migrated, run the one-shot migration. The
+  //         migration is idempotent and concatenate-don't-synthesise, so
+  //         the worst case on re-run is "no R6 dirs found, exit clean".
+  //         Failure here MUST NOT block session boot — we log + continue;
+  //         dream will gradually backfill v2 from group diffs.
+  try {
+    if (config?.memoryV2 === true && !config?._readOnly) {
+      const memoryRoot = join(yeaftDir, 'memory');
+      const stateFile = join(yeaftDir, '.memory-v2-migration.json');
+      let alreadyMigrated = false;
+      if (existsSyncSafe(stateFile)) {
+        try {
+          const state = JSON.parse(readFileSyncSafe(stateFile, 'utf8') || '{}');
+          alreadyMigrated = Boolean(state && state.completedAt);
+        } catch { /* malformed state → re-run; migration is idempotent */ }
+      }
+      const hasR6 = existsSyncSafe(join(memoryRoot, 'groups'))
+                 || existsSyncSafe(join(memoryRoot, 'features'));
+      if (!alreadyMigrated && hasR6) {
+        console.log('[Yeaft] memoryV2 on + R6 layout detected — running one-shot migration…');
+        const result = await migrateR6toV2({ root: memoryRoot, apply: true });
+        try {
+          writeFileSyncSafe(stateFile, JSON.stringify({
+            completedAt: new Date().toISOString(),
+            migratedScopes: result.migratedScopes,
+            skippedScopes: result.skippedScopes,
+            errors: result.errors,
+            backedUpTo: result.backedUpTo,
+          }, null, 2));
+        } catch { /* state file write is best-effort */ }
+        console.log(`[Yeaft] memory v2 migration done — ${result.migratedScopes} scopes migrated, backup at ${result.backedUpTo}`);
+      } else if (!alreadyMigrated && !hasR6) {
+        // Fresh user, no R6 to migrate. Mark as done so we don't keep checking.
+        try {
+          writeFileSyncSafe(stateFile, JSON.stringify({
+            completedAt: new Date().toISOString(),
+            migratedScopes: 0,
+            note: 'no R6 layout present — fresh v2',
+          }, null, 2));
+        } catch { /* best-effort */ }
+      }
+    }
+  } catch (err) {
+    console.warn(`[Yeaft] memory v2 migration skipped due to error: ${err?.message || err}`);
+  }
+
   // ─── 2a. Permission pre-check ─────────────────────────
   //         If the data dir is not writable, mark session as read-only.
   //         Persistence (conversation, memory, dream) is skipped in this mode.

package/unify/dream-v2/diff-gate.js

@@ -1,89 +0,0 @@
-/**
- * dream-v2/diff-gate.js — DESIGN.md §9.14.
- *
- * Hourly dream tick is cheap by default: read a per-scope cursor, check
- * whether anything has changed since last pass, skip everything if not.
- *
- * The cursor is a tiny JSON file `<scopeDir>/.dream-cursor.json`:
- *
- *   { "lastTickAt": "<ISO>", "lastSeenSig": "<opaque>" }
- *
- * `lastSeenSig` is whatever the caller wants to put there — typically a
- * hash of the entries dir mtime + index.md mtime. The diff-gate doesn't
- * compute the signature; it just compares the supplied "current" against
- * the stored "last". That keeps signatures pluggable (mtime today, content
- * hash later, ETag on a remote scope etc.).
- */
-
-import { promises as fs } from 'fs';
-import { join, dirname } from 'path';
-
-const FILE = '.dream-cursor.json';
-
-/**
- * @param {string} root
- * @param {string} scopeDir
- * @returns {string}
- */
-export function cursorPath(root, scopeDir) {
-  if (!root || !scopeDir) throw new Error('cursorPath: root + scopeDir required');
-  return join(root, scopeDir, FILE);
-}
-
-/**
- * @param {{ root: string, scopeDir: string }} args
- * @returns {Promise<{ lastTickAt: string|null, lastSeenSig: string|null }>}
- */
-export async function readCursor({ root, scopeDir }) {
-  const path = cursorPath(root, scopeDir);
-  try {
-    const content = await fs.readFile(path, 'utf8');
-    const parsed = JSON.parse(content);
-    return {
-      lastTickAt: typeof parsed?.lastTickAt === 'string' ? parsed.lastTickAt : null,
-      lastSeenSig: typeof parsed?.lastSeenSig === 'string' ? parsed.lastSeenSig : null,
-    };
-  } catch (err) {
-    if (err && err.code === 'ENOENT') return { lastTickAt: null, lastSeenSig: null };
-    if (err instanceof SyntaxError) return { lastTickAt: null, lastSeenSig: null };
-    throw err;
-  }
-}
-
-/**
- * @param {{
- *   root: string,
- *   scopeDir: string,
- *   sig: string,
- *   tickAt?: string,
- * }} args
- */
-export async function writeCursor({ root, scopeDir, sig, tickAt }) {
-  if (typeof sig !== 'string') throw new Error('writeCursor: sig must be string');
-  const path = cursorPath(root, scopeDir);
-  await fs.mkdir(dirname(path), { recursive: true });
-  const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
-  await fs.writeFile(tmp, JSON.stringify({
-    lastTickAt: tickAt || new Date().toISOString(),
-    lastSeenSig: sig,
-  }), 'utf8');
-  await fs.rename(tmp, path);
-}
-
-/**
- * Diff-gate decision. Pure: takes (last, current) and returns whether
- * dream should run. Caller decides what `currentSig` means.
- *
- * @param {{ lastSeenSig: string|null }} last
- * @param {string} currentSig
- * @returns {{ skip: boolean, reason: string }}
- */
-export function shouldRunDream(last, currentSig) {
-  if (!last || last.lastSeenSig == null) {
-    return { skip: false, reason: 'no_cursor' };
-  }
-  if (last.lastSeenSig !== currentSig) {
-    return { skip: false, reason: 'diff' };
-  }
-  return { skip: true, reason: 'no_diff' };
-}

package/unify/dream-v2/refresh.js

@@ -1,109 +0,0 @@
-/**
- * dream-v2/refresh.js — DESIGN.md §9.14 refresh hook (Phase 8 PR-J).
- *
- * The PR-F wire-up plumbed `runDreamTick` into the scheduler with a v1
- * no-op refresh placeholder. PR-J makes the refresh real but stays
- * within the §8 v1 charter — "Thin: skip pruning/demotion; refresh-only
- * in v1, no LLM".
- *
- * What "refresh" does today:
- *   1. Read the scope's `index.md` rows (the entry catalog).
- *   2. Select the top-N most recent rows by `updated` timestamp
- *      (default 12 — enough to surface the active context without
- *      exploding Layer A token cost).
- *   3. Render a deterministic markdown synopsis (one bullet per row:
- *      `- <title> [<kind>; tags] (<updated>)`).
- *   4. Write to the scope's `summary.md` via `writeSummary` (atomic
- *      rename — readers never see a partial write).
- *
- * If the index is empty (cold-start scope), we leave `summary.md`
- * alone. Overwriting with an empty file would erase any human-written
- * synopsis a future tool may have placed there.
- *
- * No LLM call. No pruning. No tombstones. The cursor is advanced by
- * `runDreamTick` after this hook resolves, so a clean run of refresh
- * counts as "scope handled" and we won't re-run until the diff-gate
- * sees new content.
- *
- * Errors are propagated — `runDreamTick` already catches per-scope
- * failures and records them under `errors[]` without aborting siblings.
- */
-
-import { readIndex, writeSummary } from '../memory/scope-tree.js';
-
-/** Default number of recent entries surfaced on the synopsis. */
-export const DEFAULT_TOP_N = 12;
-
-/**
- * Render a deterministic markdown synopsis for a scope from its index rows.
- * Pure function — exported for unit tests.
- *
- * @param {{ kind: string, id?: string, scopeDir: string }} scope
- * @param {Array<{ path: string, title?: string, tags?: string[]|string, kind?: string, updated?: string }>} rows
- * @param {number} [topN]
- * @returns {string}
- */
-export function buildScopeSynopsis(scope, rows, topN = DEFAULT_TOP_N) {
-  if (!Array.isArray(rows) || rows.length === 0) return '';
-
-  // Sort by `updated` desc, then by path asc as a stable tiebreaker.
-  const sorted = [...rows].sort((a, b) => {
-    const u = (b.updated || '').localeCompare(a.updated || '');
-    return u !== 0 ? u : (a.path || '').localeCompare(b.path || '');
-  });
-  const top = sorted.slice(0, Math.max(1, topN | 0));
-
-  const header = `# ${scope.scopeDir} — recent context`;
-  const lines = top.map((r) => {
-    const title = (r.title || r.path || 'entry').trim();
-    const kind = r.kind ? `${r.kind}` : '';
-    const tagsRaw = Array.isArray(r.tags) ? r.tags : (typeof r.tags === 'string' ? r.tags.split(',') : []);
-    const tags = tagsRaw.map((t) => String(t).trim()).filter(Boolean);
-    const meta = [kind, ...tags].filter(Boolean).join('; ');
-    const metaPart = meta ? ` [${meta}]` : '';
-    const updated = r.updated ? ` (${r.updated})` : '';
-    return `- ${title}${metaPart}${updated}`;
-  });
-  return [header, '', ...lines, ''].join('\n');
-}
-
-/**
- * Translate a `runDreamTick` ScopeRef ({ kind, id?, scopeDir }) into a
- * `scope-tree.js` Scope ({ kind, id }). The two surfaces share the
- * `kind` enum but `runDreamTick` carries `scopeDir` as the canonical
- * identifier; scope-tree derives it from `kind`+`id`.
- *
- * @param {{ kind: string, id?: string, scopeDir: string }} ref
- * @returns {{ kind: string, id?: string }}
- */
-export function refToScope(ref) {
-  if (!ref || typeof ref !== 'object') {
-    throw new Error('refToScope: ref required');
-  }
-  if (ref.kind === 'user') return { kind: 'user' };
-  if (!ref.id) throw new Error(`refToScope: ${ref.kind} scope requires id`);
-  return { kind: ref.kind, id: ref.id };
-}
-
-/**
- * Build a refresh hook bound to a specific memory root. The returned
- * function is the `refresh` arg `runDreamTick` expects.
- *
- * @param {{ root: string, topN?: number }} args
- * @returns {(scope: { kind: string, id?: string, scopeDir: string }) => Promise<void>}
- */
-export function createScopeRefreshHook({ root, topN = DEFAULT_TOP_N } = {}) {
-  if (!root || typeof root !== 'string') {
-    throw new Error('createScopeRefreshHook: root required');
-  }
-  return async function refreshScopeSummary(scope) {
-    const target = refToScope(scope);
-    const rows = await readIndex(target, { root });
-    const body = buildScopeSynopsis(scope, rows, topN);
-    if (!body) {
-      // Cold-start scope: leave summary.md alone (see header docs).
-      return;
-    }
-    await writeSummary(target, body, { root });
-  };
-}

package/unify/dream-v2/scope-sig.js

@@ -1,42 +0,0 @@
-/**
- * dream-v2/scope-sig.js — DESIGN.md §9.14.
- *
- * Default signature for a scope dir: combine the mtimes of `entries/`,
- * `index.md`, `summary.md` into a stable opaque string. Cheap and
- * dependency-free — we explicitly stay out of "compute SHA over all
- * entry bodies" territory because the dream tick is meant to be
- * fingertip-cheap when nothing changed.
- *
- * Missing files contribute `0` to the signature, so cold-start scopes
- * have a stable "empty" signature until the first entry lands.
- */
-
-import { promises as fs } from 'fs';
-import { join } from 'path';
-
-/**
- * @param {{ root: string, scopeDir: string }} args
- * @returns {Promise<string>}
- */
-export async function computeScopeSig({ root, scopeDir }) {
-  if (!root || !scopeDir) throw new Error('computeScopeSig: root + scopeDir required');
-  const targets = [
-    join(root, scopeDir, 'entries'),
-    join(root, scopeDir, 'index.md'),
-    join(root, scopeDir, 'summary.md'),
-  ];
-  const stamps = [];
-  for (const p of targets) {
-    try {
-      const s = await fs.stat(p);
-      stamps.push(`${s.mtimeMs.toFixed(0)}:${s.size}`);
-    } catch (err) {
-      if (err && err.code === 'ENOENT') {
-        stamps.push('0:0');
-      } else {
-        throw err;
-      }
-    }
-  }
-  return stamps.join('|');
-}

package/unify/dream-v2/tick.js

@@ -1,99 +0,0 @@
-/**
- * dream-v2/tick.js — DESIGN.md §9.14 dream cadence.
- *
- * Hourly tick:
- *   1. For each registered scope, compute current signature.
- *   2. Read the scope cursor; if no diff, skip.
- *   3. On diff (or `force`), call the supplied `refresh(scope)` hook,
- *      which is responsible for rewriting `summary.md` / `index.md`.
- *      Any errors per scope are captured; other scopes still run.
- *   4. Write the new cursor.
- *
- * Phase 6 is intentionally refresh-only (DESIGN.md §8 line 395:
- * "Thin: skip pruning/demotion; refresh-only in v1"). The `refresh`
- * hook gets to decide what "refresh" means; this file just sequences
- * the diff-gated calls.
- */
-
-import { computeScopeSig } from './scope-sig.js';
-import { readCursor, writeCursor, shouldRunDream } from './diff-gate.js';
-
-/**
- * @typedef {{ kind: 'user'|'group'|'vp'|'task', id?: string, scopeDir: string }} ScopeRef
- */
-
-/**
- * @param {{
- *   root: string,
- *   scopes: ScopeRef[],
- *   refresh: (scope: ScopeRef) => Promise<void>,
- *   force?: boolean,
- *   computeSig?: (scope: ScopeRef) => Promise<string>,
- *   now?: () => string,
- * }} args
- * @returns {Promise<{
- *   ran: Array<{ scopeDir: string, reason: string }>,
- *   skipped: Array<{ scopeDir: string, reason: string }>,
- *   errors: Array<{ scopeDir: string, error: Error }>,
- * }>}
- */
-export async function runDreamTick({
-  root, scopes, refresh, force = false,
-  computeSig, now,
-}) {
-  if (!root) throw new Error('runDreamTick: root required');
-  if (!Array.isArray(scopes)) throw new Error('runDreamTick: scopes array required');
-  if (typeof refresh !== 'function') throw new Error('runDreamTick: refresh fn required');
-
-  const sigOf = typeof computeSig === 'function'
-    ? computeSig
-    : (s) => computeScopeSig({ root, scopeDir: s.scopeDir });
-  const stamp = typeof now === 'function' ? now : () => new Date().toISOString();
-
-  const ran = [];
-  const skipped = [];
-  const errors = [];
-
-  for (const scope of scopes) {
-    if (!scope || !scope.scopeDir) continue;
-    let sig;
-    try {
-      sig = await sigOf(scope);
-    } catch (err) {
-      errors.push({ scopeDir: scope.scopeDir, error: err });
-      continue;
-    }
-    const last = await readCursor({ root, scopeDir: scope.scopeDir });
-    const decision = force
-      ? { skip: false, reason: 'forced' }
-      : shouldRunDream(last, sig);
-
-    if (decision.skip) {
-      skipped.push({ scopeDir: scope.scopeDir, reason: decision.reason });
-      continue;
-    }
-
-    try {
-      await refresh(scope);
-      ran.push({ scopeDir: scope.scopeDir, reason: decision.reason });
-    } catch (err) {
-      errors.push({ scopeDir: scope.scopeDir, error: err });
-      // Do NOT advance the cursor on failure — next tick should retry.
-      continue;
-    }
-
-    // Recompute the sig AFTER refresh in case the refresh hook itself
-    // wrote files; this is the value we want to compare against next tick.
-    let postSig;
-    try {
-      postSig = await sigOf(scope);
-    } catch {
-      postSig = sig;
-    }
-    await writeCursor({
-      root, scopeDir: scope.scopeDir, sig: postSig, tickAt: stamp(),
-    });
-  }
-
-  return { ran, skipped, errors };
-}

package/unify/memory/scope-tree.js

@@ -1,520 +0,0 @@
-/**
- * memory/scope-tree.js — DESIGN.md Phase 2 (scoped memory tree).
- *
- * Implements the path-keyed scope tree described in DESIGN.md §2:
- *
- *   ~/.yeaft/memory/
- *     user/
- *       summary.md          — paragraph synopsis (Layer A)
- *       index.md            — markdown table, path-keyed
- *       entries/<yyyy-mm-dd>-<slug>.md
- *     groups/<groupId>/    — same shape
- *     vp/<vpId>/           — same shape
- *     features/<featureId>/ — same shape, plus archive/
- *
- * This module is concerned ONLY with on-disk shape + atomic writes. It does
- * NOT do any LLM work (extraction, summarisation, dream maintenance) — those
- * are higher layers (compact-orchestrator, dream).
- *
- * Atomicity contract:
- *   - Every write goes via `.tmp` + rename to avoid torn reads. A reader
- *     mid-rename sees either the old or the new file, never half of either.
- *   - `createEntry()` opens with `O_EXCL` so concurrent producers cannot
- *     clobber a slug collision; the second writer surfaces `slug_exists`.
- *   - `index.md` is rewritten in full (markdown table). Partial-row append
- *     would leave a torn header on crash; the whole file is small enough
- *     that full rewrite + atomic rename is fine.
- *
- * Concurrency rules (DESIGN.md §9.1):
- *   - Two workers writing different entries to the same scope are safe —
- *     they write to different files, then each updates index.md via the
- *     atomic rename. Last writer wins for the index; both entries are
- *     present on disk regardless.
- *   - `summary.md` written via the same atomic rename. Workers reading it
- *     mid-write see either the previous or the next paragraph.
- *
- * Path discipline:
- *   - All scope paths returned by helpers are filesystem-relative paths
- *     ROOTED at the memory dir, e.g. `groups/eng/entries/2026-04-21-foo.md`.
- *     This matches DESIGN.md §1.2.1 — paths self-document.
- */
-
-import {
-  promises as fsp,
-  existsSync,
-  mkdirSync,
-} from 'fs';
-import { join, dirname } from 'path';
-import { homedir } from 'os';
-
-/** Default memory root. Tests override via `opts.root`. */
-export const DEFAULT_MEMORY_ROOT = join(homedir(), '.yeaft', 'memory');
-
-/** @typedef {'user'|'group'|'vp'|'feature'} ScopeKind */
-/** @typedef {{kind: ScopeKind, id?: string}} Scope */
-
-/**
- * Compute the scope's path segment relative to the memory root.
- * `user/`, `groups/<id>/`, `vp/<id>/`, `features/<id>/`.
- *
- * @param {Scope} scope
- * @returns {string}
- */
-export function scopeDir(scope) {
-  if (!scope || typeof scope !== 'object') {
-    throw new Error('scopeDir: scope is required');
-  }
-  switch (scope.kind) {
-    case 'user':
-      return 'user';
-    case 'group':
-      if (!scope.id) throw new Error('scopeDir: group scope requires id');
-      return `groups/${scope.id}`;
-    case 'vp':
-      if (!scope.id) throw new Error('scopeDir: vp scope requires id');
-      return `vp/${scope.id}`;
-    case 'feature':
-      if (!scope.id) throw new Error('scopeDir: feature scope requires id');
-      return `features/${scope.id}`;
-    default:
-      throw new Error(`scopeDir: unknown kind ${JSON.stringify(scope.kind)}`);
-  }
-}
-
-/**
- * Atomic write: temp-file + rename. Creates parent directories on demand.
- * The rename is atomic on POSIX filesystems for paths on the same mount.
- *
- * @param {string} absPath
- * @param {string} content
- */
-async function atomicWrite(absPath, content) {
-  await fsp.mkdir(dirname(absPath), { recursive: true });
-  const tmp = `${absPath}.tmp.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}`;
-  await fsp.writeFile(tmp, content, 'utf8');
-  await fsp.rename(tmp, absPath);
-}
-
-/**
- * Slugify a free-form title for use in a filename. Lowercase, ASCII letters
- * + digits + dash. Empty / pathological input returns `entry`.
- *
- * @param {string} title
- * @returns {string}
- */
-export function slugify(title) {
-  const raw = (title || '')
-    .toString()
-    .toLowerCase()
-    .normalize('NFKD')
-    // eslint-disable-next-line no-misleading-character-class
-    .replace(/[̀-ͯ]/g, '') // strip combining marks
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '')
-    .slice(0, 60);
-  return raw || 'entry';
-}
-
-/**
- * Format a Date as `yyyy-mm-dd` in UTC. Used in entry filenames.
- *
- * @param {Date} [d=new Date()]
- * @returns {string}
- */
-export function isoDate(d = new Date()) {
-  const y = d.getUTCFullYear();
-  const m = String(d.getUTCMonth() + 1).padStart(2, '0');
-  const day = String(d.getUTCDate()).padStart(2, '0');
-  return `${y}-${m}-${day}`;
-}
-
-/**
- * Compute the canonical entry path for a (scope, title, date) triple.
- *
- * @param {Scope} scope
- * @param {string} title
- * @param {Date} [date]
- * @returns {string} relative to memory root
- */
-export function entryPathFor(scope, title, date) {
-  return `${scopeDir(scope)}/entries/${isoDate(date)}-${slugify(title)}.md`;
-}
-
-// ─── frontmatter ───────────────────────────────────────────────
-
-/**
- * Render YAML-ish frontmatter. Keys in deterministic order; string values
- * are JSON-stringified to handle quotes / newlines safely; arrays render as
- * `key: [a, b]`. Unknown values are skipped.
- *
- * @param {Record<string,*>} fm
- * @returns {string}
- */
-function renderFrontmatter(fm) {
-  if (!fm || typeof fm !== 'object') return '';
-  const order = ['title', 'kind', 'tags', 'source', 'createdAt', 'updatedAt'];
-  const seen = new Set();
-  const lines = ['---'];
-  for (const key of order) {
-    if (!(key in fm)) continue;
-    seen.add(key);
-    lines.push(renderFmLine(key, fm[key]));
-  }
-  for (const key of Object.keys(fm)) {
-    if (seen.has(key)) continue;
-    lines.push(renderFmLine(key, fm[key]));
-  }
-  lines.push('---');
-  return lines.filter(Boolean).join('\n');
-}
-
-function renderFmLine(key, value) {
-  if (value === null || value === undefined) return '';
-  if (Array.isArray(value)) {
-    const items = value.map(v => (typeof v === 'string' ? v : JSON.stringify(v)));
-    return `${key}: [${items.join(', ')}]`;
-  }
-  if (typeof value === 'string') {
-    // Quote when it contains anything non-trivial.
-    if (/^[\w\-./:]+$/.test(value)) return `${key}: ${value}`;
-    return `${key}: ${JSON.stringify(value)}`;
-  }
-  return `${key}: ${JSON.stringify(value)}`;
-}
-
-/**
- * Parse the frontmatter block from a markdown body. Returns `{frontmatter,
- * body}`; missing frontmatter ⇒ `frontmatter = {}` and `body` is the input.
- * Best-effort parser — accepts the lines this module emits and a few common
- * variants. Does NOT pull in a YAML dep.
- *
- * @param {string} content
- * @returns {{ frontmatter: Record<string,*>, body: string }}
- */
-export function parseEntry(content) {
-  if (typeof content !== 'string' || !content.startsWith('---')) {
-    return { frontmatter: {}, body: content || '' };
-  }
-  const end = content.indexOf('\n---', 4);
-  if (end === -1) return { frontmatter: {}, body: content };
-  const fmText = content.slice(4, end).trim();
-  const body = content.slice(end + 4).replace(/^\n+/, '');
-  const fm = {};
-  for (const rawLine of fmText.split('\n')) {
-    const line = rawLine.trim();
-    if (!line) continue;
-    const m = line.match(/^([A-Za-z_][\w-]*):\s*(.*)$/);
-    if (!m) continue;
-    const [, key, rest] = m;
-    fm[key] = parseFmValue(rest);
-  }
-  return { frontmatter: fm, body };
-}
-
-function parseFmValue(rest) {
-  if (rest === '') return '';
-  if (rest.startsWith('[') && rest.endsWith(']')) {
-    const inner = rest.slice(1, -1).trim();
-    if (!inner) return [];
-    return inner.split(',').map(s => {
-      const t = s.trim();
-      if (t.startsWith('"') && t.endsWith('"')) {
-        try { return JSON.parse(t); } catch { return t; }
-      }
-      return t;
-    });
-  }
-  if (rest.startsWith('"') && rest.endsWith('"')) {
-    try { return JSON.parse(rest); } catch { return rest.slice(1, -1); }
-  }
-  return rest;
-}
-
-// ─── entries ───────────────────────────────────────────────────
-
-/**
- * Create a new entry under (scope, title). Fails with `slug_exists` if the
- * computed path already exists. Returns the relative path written.
- *
- * @param {{
- *   scope: Scope,
- *   title: string,
- *   body: string,
- *   tags?: string[],
- *   kind?: string,
- *   source?: string,
- *   date?: Date,
- *   root?: string,
- * }} args
- * @returns {Promise<{ path: string, abs: string }>}
- */
-export async function createEntry(args) {
-  const { scope, title, body, tags, kind, source, date, root = DEFAULT_MEMORY_ROOT } = args;
-  if (!title || typeof title !== 'string') throw new Error('createEntry: title required');
-  if (typeof body !== 'string') throw new Error('createEntry: body required (string)');
-  const rel = entryPathFor(scope, title, date);
-  const abs = join(root, rel);
-  await fsp.mkdir(dirname(abs), { recursive: true });
-  const fm = renderFrontmatter({
-    title,
-    kind: kind || 'note',
-    tags: Array.isArray(tags) && tags.length ? tags : undefined,
-    source: source || undefined,
-    createdAt: isoDate(date),
-    updatedAt: isoDate(date),
-  });
-  const content = `${fm}\n\n${body.trim()}\n`;
-  // O_EXCL — fail loudly on slug collision (DESIGN.md §9.1 atomicity).
-  let handle;
-  try {
-    handle = await fsp.open(abs, 'wx');
-  } catch (err) {
-    if (err && err.code === 'EEXIST') {
-      const e = new Error('slug_exists');
-      e.code = 'slug_exists';
-      e.path = rel;
-      throw e;
-    }
-    throw err;
-  }
-  try {
-    await handle.writeFile(content, 'utf8');
-  } finally {
-    await handle.close();
-  }
-  return { path: rel, abs };
-}
-
-/**
- * Read an entry by its relative path; returns `null` if missing. Throws
- * `acl_blocked` when the caller's `currentVpId` is given and the path is
- * `vp/<other>/...` — the only hard ACL boundary.
- *
- * @param {string} relPath
- * @param {{ root?: string, currentVpId?: string }} [opts]
- * @returns {Promise<{ frontmatter: Record<string,*>, body: string, path: string } | null>}
- */
-export async function readEntry(relPath, opts = {}) {
-  const { root = DEFAULT_MEMORY_ROOT, currentVpId } = opts;
-  if (!relPath || typeof relPath !== 'string') throw new Error('readEntry: relPath required');
-  if (currentVpId && isVpForeign(relPath, currentVpId)) {
-    const e = new Error('acl_blocked');
-    e.code = 'acl_blocked';
-    e.path = relPath;
-    throw e;
-  }
-  const abs = join(root, relPath);
-  let raw;
-  try {
-    raw = await fsp.readFile(abs, 'utf8');
-  } catch (err) {
-    if (err && err.code === 'ENOENT') return null;
-    throw err;
-  }
-  const { frontmatter, body } = parseEntry(raw);
-  return { frontmatter, body: body.replace(/\n+$/, ''), path: relPath };
-}
-
-/**
- * @returns {boolean} true iff `relPath` is `vp/<other>/...` (other ≠ currentVpId).
- */
-export function isVpForeign(relPath, currentVpId) {
-  if (!relPath || !currentVpId) return false;
-  const m = /^vp\/([^/]+)\//.exec(relPath);
-  if (!m) return false;
-  return m[1] !== currentVpId;
-}
-
-// ─── index.md ──────────────────────────────────────────────────
-
-/**
- * Index row schema. `path` is the canonical, scope-rooted relative path.
- * `updated` is YYYY-MM-DD UTC. `tags` is a comma-joined string for the
- * markdown column; arrays are accepted as input and normalised.
- *
- * @typedef {{
- *   path: string,
- *   title: string,
- *   tags?: string | string[],
- *   kind?: string,
- *   updated?: string,
- * }} IndexRow
- */
-
-/**
- * Render the markdown table for `index.md` in a scope. Reverse-chronological
- * — newest `updated` first — matching DESIGN.md §9.3 ("append on top").
- *
- * @param {Scope} scope
- * @param {IndexRow[]} rows
- * @returns {string}
- */
-export function renderIndex(scope, rows) {
-  const dir = scopeDir(scope);
-  const sorted = [...(rows || [])].sort((a, b) => {
-    const ax = (b.updated || '').localeCompare(a.updated || '');
-    return ax !== 0 ? ax : (a.path || '').localeCompare(b.path || '');
-  });
-  const lines = [
-    `# index — ${dir}`,
-    '',
-    '| path | title | tags | kind | updated |',
-    '| ---- | ----- | ---- | ---- | ------- |',
-  ];
-  for (const r of sorted) {
-    const path = (r.path || '').replace(/\|/g, '\\|');
-    const title = (r.title || '').replace(/\|/g, '\\|');
-    const tags = Array.isArray(r.tags) ? r.tags.join(',') : (r.tags || '');
-    const kind = r.kind || '';
-    const updated = r.updated || '';
-    lines.push(`| ${path} | ${title} | ${tags} | ${kind} | ${updated} |`);
-  }
-  return lines.join('\n') + '\n';
-}
-
-/**
- * Parse `index.md` markdown table back into an array of rows. Tolerates
- * extra whitespace, missing optional columns, and the index header line.
- * Unknown / malformed lines are skipped silently.
- *
- * @param {string} content
- * @returns {IndexRow[]}
- */
-export function parseIndex(content) {
-  if (typeof content !== 'string' || !content) return [];
-  const out = [];
-  for (const rawLine of content.split('\n')) {
-    const line = rawLine.trim();
-    if (!line.startsWith('|')) continue;
-    if (/^\|\s*-+/.test(line)) continue; // separator row
-    const cols = line.split('|').slice(1, -1).map(s => s.trim());
-    if (cols.length < 2) continue;
-    const [path, title, tags = '', kind = '', updated = ''] = cols;
-    if (!path || path === 'path') continue; // header row
-    out.push({
-      path,
-      title,
-      tags: tags ? tags.split(',').map(s => s.trim()).filter(Boolean) : [],
-      kind: kind || undefined,
-      updated: updated || undefined,
-    });
-  }
-  return out;
-}
-
-/**
- * Read `index.md` for a scope and return the parsed rows. Missing index
- * returns `[]` (cold-start scope).
- *
- * @param {Scope} scope
- * @param {{ root?: string }} [opts]
- * @returns {Promise<IndexRow[]>}
- */
-export async function readIndex(scope, opts = {}) {
-  const { root = DEFAULT_MEMORY_ROOT } = opts;
-  const abs = join(root, scopeDir(scope), 'index.md');
-  let raw;
-  try { raw = await fsp.readFile(abs, 'utf8'); }
-  catch (err) {
-    if (err && err.code === 'ENOENT') return [];
-    throw err;
-  }
-  return parseIndex(raw);
-}
-
-/**
- * Atomically rewrite `index.md` for a scope.
- *
- * @param {Scope} scope
- * @param {IndexRow[]} rows
- * @param {{ root?: string }} [opts]
- */
-export async function writeIndex(scope, rows, opts = {}) {
-  const { root = DEFAULT_MEMORY_ROOT } = opts;
-  const abs = join(root, scopeDir(scope), 'index.md');
-  await atomicWrite(abs, renderIndex(scope, rows));
-}
-
-/**
- * Upsert a single row keyed by `path`. Existing row with the same path is
- * replaced; otherwise the row is prepended (kept in reverse-chronological
- * order via `renderIndex`'s sort). Returns the updated row list.
- *
- * @param {Scope} scope
- * @param {IndexRow} row
- * @param {{ root?: string }} [opts]
- * @returns {Promise<IndexRow[]>}
- */
-export async function upsertIndexRow(scope, row, opts = {}) {
-  if (!row || !row.path) throw new Error('upsertIndexRow: row.path required');
-  const rows = await readIndex(scope, opts);
-  const filtered = rows.filter(r => r.path !== row.path);
-  filtered.unshift(row);
-  await writeIndex(scope, filtered, opts);
-  return filtered;
-}
-
-/**
- * Cap the rows surfaced to the router (DESIGN.md §9.3). Reverse-chrono;
- * default K = 200. Caller passes the merged set; we trim and return.
- *
- * @param {IndexRow[]} rows
- * @param {number} [k=200]
- * @returns {IndexRow[]}
- */
-export function capIndexRows(rows, k = 200) {
-  if (!Array.isArray(rows)) return [];
-  if (rows.length <= k) return rows.slice();
-  return rows.slice(0, k);
-}
-
-// ─── summary.md ────────────────────────────────────────────────
-
-/**
- * Read the scope's `summary.md`. Empty / missing → ''.
- *
- * @param {Scope} scope
- * @param {{ root?: string }} [opts]
- * @returns {Promise<string>}
- */
-export async function readSummary(scope, opts = {}) {
-  const { root = DEFAULT_MEMORY_ROOT } = opts;
-  const abs = join(root, scopeDir(scope), 'summary.md');
-  try { return (await fsp.readFile(abs, 'utf8')).trim(); }
-  catch (err) {
-    if (err && err.code === 'ENOENT') return '';
-    throw err;
-  }
-}
-
-/**
- * Atomically rewrite the scope's `summary.md`. The body is trimmed; empty
- * input writes an empty file (callers that wanted "delete summary" can use
- * `fs.unlink` directly — we don't surface that here).
- *
- * @param {Scope} scope
- * @param {string} body
- * @param {{ root?: string }} [opts]
- */
-export async function writeSummary(scope, body, opts = {}) {
-  const { root = DEFAULT_MEMORY_ROOT } = opts;
-  const abs = join(root, scopeDir(scope), 'summary.md');
-  await atomicWrite(abs, `${(body || '').trim()}\n`);
-}
-
-// ─── ensure scope on disk ──────────────────────────────────────
-
-/**
- * Best-effort: ensure the scope's directory and an empty `entries/` exist.
- * Idempotent. Use at boot or on first write to avoid ENOENT cascades.
- *
- * @param {Scope} scope
- * @param {{ root?: string }} [opts]
- */
-export function ensureScopeSync(scope, opts = {}) {
-  const { root = DEFAULT_MEMORY_ROOT } = opts;
-  const dir = join(root, scopeDir(scope));
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-  const entries = join(dir, 'entries');
-  if (!existsSync(entries)) mkdirSync(entries, { recursive: true });
-}