@yeaft/webchat-agent 0.1.628 → 0.1.629

package/package.json

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

package/unify/memory/migrate-r6-to-v2.js

@@ -0,0 +1,462 @@
+/**
+ * memory/migrate-r6-to-v2.js — one-shot migration of R6 shard layout to v2.
+ *
+ * R6 layout (input):
+ *   ~/.yeaft/memory/
+ *     user/
+ *       MEMORY.md                      ← legacy R5 user profile (optional)
+ *       summary.md                     ← R6 paragraph synopsis (optional)
+ *       index.md                       ← R6 markdown table (optional)
+ *       memory-<shard>.md              ← R6 semantic shards (zero or more)
+ *       entries/<date>-<slug>.md       ← R6 entries (zero or more)
+ *       scopes.md                      ← legacy R5 scope index (optional)
+ *     groups/<id>/                     ← (R6 plural)  same shape
+ *     vp/<id>/                         ← same shape
+ *     features/<id>/                   ← (R6 plural)  same shape
+ *
+ * v2 layout (output):
+ *   ~/.yeaft/memory/
+ *     user/
+ *       memory.md
+ *       summary.md
+ *     vp/<id>/                         ← (singular)
+ *       memory.md
+ *       summary.md
+ *     group/<id>/                      ← (singular)
+ *       memory.md
+ *       summary.md
+ *     feature/<id>/                    ← (singular)
+ *       memory.md
+ *       summary.md
+ *
+ *   ~/.yeaft/memory.v1.bak/<ts>/...    ← snapshot of input prior to deletion
+ *
+ * Strategy:
+ *   - Concatenate, don't synthesise. We preserve every byte of the R6 data
+ *     by appending it to the new memory.md under labelled sections. The
+ *     first post-migration dream (PR-C) will rewrite into a clean form.
+ *     This means: zero LLM calls, zero data loss, fully deterministic.
+ *   - summary.md: prefer R6 summary.md verbatim if present; otherwise leave
+ *     empty for dream to fill.
+ *   - Topic scope: not generated by migration (no R6 source). Topic is a
+ *     pure v2 concept, populated only by future dreams.
+ *
+ * Modes:
+ *   - dryRun: true (default) → report planned writes, touch nothing
+ *   - apply: true            → actually write v2 files + take backup
+ *
+ * Output:
+ *   { plan: [...], backedUpTo: '...', migratedScopes: N, errors: [...] }
+ *
+ * This module performs no LLM work and does not depend on store-v2; it
+ * speaks raw filesystem so it can run before any v2 process initialises.
+ */
+
+import {
+  promises as fsp,
+  existsSync,
+} from 'fs';
+import { join, dirname } from 'path';
+
+const HEADER = `<!-- migrated from R6 by migrate-r6-to-v2.js -->`;
+
+/**
+ * Run migration.
+ *
+ * @param {{
+ *   root?: string,            // default ~/.yeaft/memory
+ *   backupRoot?: string,      // default ~/.yeaft/memory.v1.bak/<ts>
+ *   apply?: boolean,          // false = dry-run
+ *   onProgress?: (event: object) => void,
+ * }} [opts]
+ * @returns {Promise<{
+ *   plan: object[],
+ *   migratedScopes: number,
+ *   skippedScopes: string[],
+ *   errors: object[],
+ *   backedUpTo: string|null,
+ * }>}
+ */
+export async function migrateR6toV2(opts = {}) {
+  const root = opts.root;
+  if (!root) throw new Error('migrateR6toV2: opts.root is required');
+  const apply = !!opts.apply;
+  const onProgress = typeof opts.onProgress === 'function' ? opts.onProgress : () => {};
+  const backupRoot = opts.backupRoot
+    || join(dirname(root), 'memory.v1.bak', new Date().toISOString().replace(/[:.]/g, '-'));
+
+  const plan = [];
+  const errors = [];
+  const skippedScopes = [];
+
+  if (!existsSync(root)) {
+    return { plan, migratedScopes: 0, skippedScopes, errors, backedUpTo: null };
+  }
+
+  const scopeRoots = await discoverR6Scopes(root);
+  onProgress({ phase: 'discover', count: scopeRoots.length });
+
+  for (const sr of scopeRoots) {
+    try {
+      const action = await planScope(root, sr);
+      plan.push(action);
+      if (action.kind === 'skip') skippedScopes.push(sr.relPath);
+    } catch (err) {
+      errors.push({ scope: sr.relPath, error: err.message });
+    }
+  }
+
+  if (!apply) {
+    return { plan, migratedScopes: 0, skippedScopes, errors, backedUpTo: null };
+  }
+
+  // 1) backup the entire memory root before we mutate
+  await fsp.mkdir(backupRoot, { recursive: true });
+  await copyDir(root, backupRoot);
+  onProgress({ phase: 'backup', backupRoot });
+
+  // 2) write v2 files
+  let migrated = 0;
+  for (const action of plan) {
+    if (action.kind !== 'migrate') continue;
+    try {
+      await applyScope(root, action);
+      onProgress({ phase: 'migrated', scope: action.dstRelPath });
+      migrated += 1;
+    } catch (err) {
+      errors.push({ scope: action.dstRelPath, error: err.message });
+    }
+  }
+
+  // 3) delete R6 leftovers (only the files we knew about — we don't rm -rf)
+  for (const action of plan) {
+    if (action.kind !== 'migrate') continue;
+    try {
+      await purgeR6Leftovers(root, action);
+    } catch (err) {
+      errors.push({ scope: action.dstRelPath, error: `purge: ${err.message}` });
+    }
+  }
+
+  return { plan, migratedScopes: migrated, skippedScopes, errors, backedUpTo: backupRoot };
+}
+
+// ─── discovery ────────────────────────────────────────────────
+
+/**
+ * Walk the R6 memory root and return one entry per detected scope.
+ * Returns shapes:
+ *   { relPath: 'user',                  kind: 'user' }
+ *   { relPath: 'vp/<id>',               kind: 'vp', id }
+ *   { relPath: 'groups/<id>',           kind: 'group', id }
+ *   { relPath: 'features/<id>',         kind: 'feature', id }
+ *
+ * @returns {Promise<{relPath: string, kind: string, id?: string}[]>}
+ */
+async function discoverR6Scopes(root) {
+  const out = [];
+  if (existsSync(join(root, 'user'))) out.push({ relPath: 'user', kind: 'user' });
+
+  for (const [r6Folder, kind] of [
+    ['vp', 'vp'],
+    ['groups', 'group'],
+    ['features', 'feature'],
+    // Tolerate already-singular layouts (a partially migrated tree)
+    ['group', 'group'],
+    ['feature', 'feature'],
+  ]) {
+    const dir = join(root, r6Folder);
+    if (!existsSync(dir)) continue;
+    let names;
+    try { names = await fsp.readdir(dir, { withFileTypes: true }); }
+    catch { continue; }
+    for (const ent of names) {
+      if (!ent.isDirectory()) continue;
+      out.push({ relPath: `${r6Folder}/${ent.name}`, kind, id: ent.name, r6Folder });
+    }
+  }
+  return out;
+}
+
+// ─── plan ─────────────────────────────────────────────────────
+
+/**
+ * Build a migration action for one scope: where to read from, where to
+ * write to, and what content the new memory.md / summary.md will hold.
+ *
+ * @param {string} root
+ * @param {{relPath: string, kind: string, id?: string, r6Folder?: string}} sr
+ * @returns {Promise<object>}
+ */
+async function planScope(root, sr) {
+  const srcAbs = join(root, sr.relPath);
+
+  // v2 destination dir (singular paths)
+  let dstRel;
+  switch (sr.kind) {
+    case 'user': dstRel = 'user'; break;
+    case 'vp': dstRel = `vp/${sr.id}`; break;
+    case 'group': dstRel = `group/${sr.id}`; break;
+    case 'feature': dstRel = `feature/${sr.id}`; break;
+    default:
+      return { kind: 'skip', srcRelPath: sr.relPath, reason: 'unknown kind' };
+  }
+
+  const r6Files = await readR6Files(srcAbs);
+  if (!r6Files.hasAny) {
+    return { kind: 'skip', srcRelPath: sr.relPath, reason: 'no R6 content' };
+  }
+
+  // If destination already has v2 layout, skip — caller may have run
+  // migration before. We do NOT clobber.
+  const dstAbs = join(root, dstRel);
+  const dstHasV2 = existsSync(join(dstAbs, 'memory.md')) || existsSync(join(dstAbs, 'summary.md'));
+  if (dstHasV2) {
+    if (sr.relPath === dstRel) {
+      // src == dst (already-singular layout). The memory.md/summary.md at
+      // `dst` are the source's own R6 files — not a foreign v2 layout. Only
+      // skip if there is genuinely no R6-specific content to fold; otherwise
+      // proceed and concatenate the R6 surfaces into a fresh memory.md.
+      if (!r6Files.hasShards && !r6Files.hasEntries
+          && !r6Files.hasIndex && !r6Files.hasLegacyMemoryMd && !r6Files.hasScopesMd) {
+        return { kind: 'skip', srcRelPath: sr.relPath, reason: 'already v2' };
+      }
+      // fall through → migrate
+    } else {
+      return {
+        kind: 'skip',
+        srcRelPath: sr.relPath,
+        reason: 'destination already has v2 files; refusing to overwrite',
+      };
+    }
+  }
+
+  return {
+    kind: 'migrate',
+    srcRelPath: sr.relPath,
+    dstRelPath: dstRel,
+    files: r6Files,
+  };
+}
+
+/**
+ * Read every R6 surface file we might want to fold in.
+ * @param {string} dir absolute scope dir
+ */
+async function readR6Files(dir) {
+  const out = {
+    summaryMd: null,
+    indexMd: null,
+    legacyMemoryMd: null,   // R5 user profile
+    scopesMd: null,         // R5 scope index
+    shards: [],             // [{name, content}]
+    entries: [],            // [{name, content}]
+    hasShards: false,
+    hasEntries: false,
+    hasIndex: false,
+    hasLegacyMemoryMd: false,
+    hasScopesMd: false,
+    hasAny: false,
+  };
+
+  const safeRead = async (p) => {
+    try { return await fsp.readFile(p, 'utf8'); }
+    catch (err) { if (err && err.code === 'ENOENT') return null; throw err; }
+  };
+
+  out.summaryMd = await safeRead(join(dir, 'summary.md'));
+  out.indexMd   = await safeRead(join(dir, 'index.md'));
+  out.legacyMemoryMd = await safeRead(join(dir, 'MEMORY.md'));
+  out.scopesMd  = await safeRead(join(dir, 'scopes.md'));
+  out.hasIndex = !!out.indexMd;
+  out.hasLegacyMemoryMd = !!out.legacyMemoryMd;
+  out.hasScopesMd = !!out.scopesMd;
+
+  // memory-<shard>.md files (semantic shards). Skip the literal v2 file
+  // `memory.md` so a partially-migrated tree isn't double-counted.
+  let names;
+  try { names = await fsp.readdir(dir, { withFileTypes: true }); }
+  catch (err) { if (err && err.code === 'ENOENT') names = []; else throw err; }
+  for (const ent of names) {
+    if (!ent.isFile()) continue;
+    if (ent.name === 'memory.md') continue;
+    const m = /^memory-(.+)\.md(\.compacting)?$/.exec(ent.name);
+    if (!m) continue;
+    const content = await safeRead(join(dir, ent.name));
+    if (content !== null) out.shards.push({ name: ent.name, content });
+  }
+  out.hasShards = out.shards.length > 0;
+
+  // entries/*.md
+  const entriesDir = join(dir, 'entries');
+  if (existsSync(entriesDir)) {
+    let entryNames;
+    try { entryNames = (await fsp.readdir(entriesDir)).filter(n => n.endsWith('.md')).sort(); }
+    catch { entryNames = []; }
+    for (const n of entryNames) {
+      const content = await safeRead(join(entriesDir, n));
+      if (content !== null) out.entries.push({ name: n, content });
+    }
+  }
+  out.hasEntries = out.entries.length > 0;
+
+  out.hasAny = !!(out.summaryMd || out.indexMd || out.legacyMemoryMd || out.scopesMd
+                  || out.hasShards || out.hasEntries);
+  return out;
+}
+
+// ─── apply ────────────────────────────────────────────────────
+
+/**
+ * Execute one planned migrate action.
+ *
+ * @param {string} root
+ * @param {object} action
+ */
+async function applyScope(root, action) {
+  const dstAbs = join(root, action.dstRelPath);
+  await fsp.mkdir(dstAbs, { recursive: true });
+
+  const memoryMd = composeMemoryMd(action.files);
+  await atomicWrite(join(dstAbs, 'memory.md'), memoryMd);
+
+  const summary = (action.files.summaryMd || '').trim();
+  if (summary) {
+    await atomicWrite(join(dstAbs, 'summary.md'), `${summary}\n`);
+  } else {
+    // Initialise an empty summary.md so listScopes detects 1-level scopes.
+    await atomicWrite(join(dstAbs, 'summary.md'), '\n');
+  }
+}
+
+/**
+ * Compose the v2 memory.md by labelled-section concatenation. We keep
+ * everything; dream will rewrite later.
+ */
+function composeMemoryMd(files) {
+  const parts = [HEADER, ''];
+
+  if (files.legacyMemoryMd) {
+    parts.push('## Legacy MEMORY.md (R5 user profile)');
+    parts.push('');
+    parts.push(files.legacyMemoryMd.trim());
+    parts.push('');
+  }
+
+  if (files.shards.length > 0) {
+    parts.push('## R6 shards');
+    parts.push('');
+    for (const sh of files.shards) {
+      parts.push(`### ${sh.name}`);
+      parts.push('');
+      parts.push(sh.content.trim());
+      parts.push('');
+    }
+  }
+
+  if (files.entries.length > 0) {
+    parts.push('## R6 entries');
+    parts.push('');
+    for (const e of files.entries) {
+      parts.push(`### ${e.name}`);
+      parts.push('');
+      parts.push(e.content.trim());
+      parts.push('');
+    }
+  }
+
+  if (files.indexMd) {
+    parts.push('## R6 index.md (deprecated; preserved for first dream)');
+    parts.push('');
+    parts.push(files.indexMd.trim());
+    parts.push('');
+  }
+
+  if (files.scopesMd) {
+    parts.push('## Legacy scopes.md');
+    parts.push('');
+    parts.push(files.scopesMd.trim());
+    parts.push('');
+  }
+
+  parts.push('<!-- dream-state -->');
+  parts.push(`migratedAt: ${new Date().toISOString()}`);
+  parts.push('<!-- /dream-state -->');
+  parts.push('');
+
+  return parts.join('\n');
+}
+
+/**
+ * Remove the R6 surface files we just folded in. Leaves any unrelated files
+ * alone (for safety). Does NOT remove parent directories — listScopes will
+ * tolerate empty `groups/`, `features/`, `vp/` shells.
+ *
+ * @param {string} root
+ * @param {object} action
+ */
+async function purgeR6Leftovers(root, action) {
+  const srcAbs = join(root, action.srcRelPath);
+  // The destination may equal the source (already-singular vp/group/feature),
+  // in which case we must NOT delete memory.md / summary.md — those are the
+  // newly written v2 files. Track the v2 names as protected.
+  const dstAbs = join(root, action.dstRelPath);
+  const dstSame = srcAbs === dstAbs;
+
+  // shards
+  const names = await fsp.readdir(srcAbs);
+  for (const n of names) {
+    if (dstSame && (n === 'memory.md' || n === 'summary.md')) continue;
+    const full = join(srcAbs, n);
+    if (/^memory-.+\.md(\.compacting)?$/.test(n)) {
+      await fsp.unlink(full).catch(() => {});
+    } else if (n === 'index.md' || n === 'MEMORY.md' || n === 'scopes.md') {
+      await fsp.unlink(full).catch(() => {});
+    } else if (n === 'entries') {
+      await rmDir(full);
+    } else if (n === 'index.json') {
+      await fsp.unlink(full).catch(() => {});
+    } else if (!dstSame && (n === 'memory.md' || n === 'summary.md')) {
+      // Source dir differs from dst: these were the R6 originals, already
+      // folded into the new dst. Remove so the source dir can be rmdir'd.
+      await fsp.unlink(full).catch(() => {});
+    }
+  }
+
+  // If the source path differs from destination (groups/<id> → group/<id>),
+  // remove the now-empty source dir to avoid two parallel trees. Only when
+  // it's actually empty.
+  if (!dstSame) {
+    try {
+      const remaining = await fsp.readdir(srcAbs);
+      if (remaining.length === 0) await fsp.rmdir(srcAbs);
+    } catch { /* tolerate */ }
+  }
+}
+
+// ─── tiny fs helpers ──────────────────────────────────────────
+
+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);
+}
+
+async function copyDir(src, dst) {
+  await fsp.mkdir(dst, { recursive: true });
+  const entries = await fsp.readdir(src, { withFileTypes: true });
+  for (const e of entries) {
+    const s = join(src, e.name);
+    const d = join(dst, e.name);
+    if (e.isDirectory()) await copyDir(s, d);
+    else if (e.isFile()) await fsp.copyFile(s, d);
+    // ignore symlinks/sockets
+  }
+}
+
+async function rmDir(p) {
+  try {
+    await fsp.rm(p, { recursive: true, force: true });
+  } catch { /* tolerate */ }
+}

package/unify/memory/store-v2.js

@@ -0,0 +1,402 @@
+/**
+ * memory/store-v2.js — DESIGN-v2.md Part I: per-scope memory.md + summary.md.
+ *
+ * One pair of files per scope. No shards, no entries/, no index.md, no
+ * index.json. The five scope kinds — user, vp, group, feature, topic — share
+ * a single shape:
+ *
+ *   ~/.yeaft/memory/
+ *     user/                    memory.md  summary.md
+ *     vp/<vpId>/               memory.md  summary.md
+ *     group/<groupId>/         memory.md  summary.md
+ *     feature/<featureId>/     memory.md  summary.md
+ *     topic/<l1>[/<l2>]/       memory.md  summary.md     (≤ 2 levels)
+ *
+ * Atomicity contract:
+ *   - Every write goes via `.tmp.<rand>` + rename. Renames are atomic on a
+ *     single POSIX mount. A reader mid-write sees either the previous file
+ *     or the next, never half of either.
+ *   - Reading a missing file returns the empty string. The "scope exists"
+ *     question is answered by directory presence, not file presence.
+ *
+ * Concurrency rules:
+ *   - Two writers to the same memory.md: last-rename wins. Dream is the only
+ *     code path that overwrites memory.md in v2; daily writes append. Append
+ *     is a single fs.appendFile call that POSIX guarantees is atomic for
+ *     buffers ≤ PIPE_BUF (≥ 4KB on every supported platform), which fits a
+ *     single fragment.
+ *
+ * ACL:
+ *   - This module enforces ONE ACL: `vp/<other>` paths are blocked when
+ *     `currentVpId` is given and differs from `<other>`. Every other scope
+ *     boundary is ACL-free in v2 (DESIGN-v2 §3.2).
+ *
+ * What this module deliberately does NOT do:
+ *   - No frontmatter parsing. memory.md and summary.md are pure markdown;
+ *     the dream-state metadata block lives at the file's tail and is read
+ *     by `dream-v2/state.js`, not here.
+ *   - No LLM calls, no extraction, no summarisation. Pure I/O.
+ *   - No legacy R6 fallback. The old MemoryStore (memory/store.js) and
+ *     ScopeTree (memory/scope-tree.js) remain in service until PR-E swaps
+ *     callers; this module is additive.
+ *
+ * Reference: agent/unify/memory/DESIGN-v2.md §2, §5, §9.
+ */
+
+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');
+
+/** Scope kinds recognised by v2. */
+export const SCOPE_KINDS = Object.freeze(['user', 'vp', 'group', 'feature', 'topic']);
+
+/** @typedef {'user'|'vp'|'group'|'feature'|'topic'} ScopeKind */
+
+/**
+ * @typedef {Object} Scope
+ * @property {ScopeKind} kind
+ * @property {string} [id]      — required for vp / group / feature
+ * @property {string[]} [path]  — required for topic; 1–2 segments
+ */
+
+/**
+ * Compute a scope's directory path relative to the memory root.
+ * Returns POSIX-style separators on every platform — the segments compose
+ * by `/` for `path.join()` to normalise per-OS at the I/O boundary.
+ *
+ * @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 'vp':
+      if (!scope.id) throw new Error('scopeDir: vp scope requires id');
+      assertSafeSegment(scope.id, 'vp.id');
+      return `vp/${scope.id}`;
+    case 'group':
+      if (!scope.id) throw new Error('scopeDir: group scope requires id');
+      assertSafeSegment(scope.id, 'group.id');
+      return `group/${scope.id}`;
+    case 'feature':
+      if (!scope.id) throw new Error('scopeDir: feature scope requires id');
+      assertSafeSegment(scope.id, 'feature.id');
+      return `feature/${scope.id}`;
+    case 'topic': {
+      const segs = Array.isArray(scope.path) ? scope.path : [];
+      if (segs.length === 0 || segs.length > 2) {
+        throw new Error('scopeDir: topic.path must have 1 or 2 segments');
+      }
+      for (const s of segs) assertSafeSegment(s, 'topic.path');
+      return `topic/${segs.join('/')}`;
+    }
+    default:
+      throw new Error(`scopeDir: unknown kind ${JSON.stringify(scope.kind)}`);
+  }
+}
+
+/**
+ * Reject path segments that could escape the scope dir or hit reserved names.
+ * Allows letters, digits, underscore, dash, dot — but rejects `.` / `..` and
+ * any segment that contains a path separator. Reserved prefix `_` is allowed
+ * for system dirs (`_no-group`, `_proposals`) when called from internal sites,
+ * but disallowed for user-supplied ids by callers.
+ *
+ * @param {string} s
+ * @param {string} ctx
+ */
+function assertSafeSegment(s, ctx) {
+  if (typeof s !== 'string' || s.length === 0) {
+    throw new Error(`scopeDir: ${ctx} must be a non-empty string`);
+  }
+  if (s === '.' || s === '..') {
+    throw new Error(`scopeDir: ${ctx} cannot be "." or ".."`);
+  }
+  if (/[\\/]/.test(s)) {
+    throw new Error(`scopeDir: ${ctx} cannot contain path separators (got ${JSON.stringify(s)})`);
+  }
+  // Allow CJK + ASCII identifier-ish characters. Tighten over time if needed.
+  if (!/^[A-Za-z0-9_\-.一-鿿]+$/.test(s)) {
+    throw new Error(`scopeDir: ${ctx} contains disallowed characters: ${JSON.stringify(s)}`);
+  }
+}
+
+/**
+ * Validate topic depth without throwing on the structural-shape errors that
+ * `scopeDir` already covers. Returns true iff `kind=topic` and 1 ≤ path ≤ 2.
+ *
+ * @param {Scope} scope
+ * @returns {boolean}
+ */
+export function isValidTopic(scope) {
+  if (!scope || scope.kind !== 'topic') return false;
+  if (!Array.isArray(scope.path)) return false;
+  if (scope.path.length < 1 || scope.path.length > 2) return false;
+  for (const s of scope.path) {
+    if (typeof s !== 'string' || s.length === 0) return false;
+    if (s === '.' || s === '..') return false;
+    if (/[\\/]/.test(s)) return false;
+    if (!/^[A-Za-z0-9_\-.一-鿿]+$/.test(s)) return false;
+  }
+  return true;
+}
+
+// ─── ACL ───────────────────────────────────────────────────────
+
+/**
+ * The single ACL: `vp/<other>` is foreign when `currentVpId` is given.
+ *
+ * @param {string} relPath
+ * @param {string} currentVpId
+ * @returns {boolean}
+ */
+export function isVpForeign(relPath, currentVpId) {
+  if (!relPath || !currentVpId) return false;
+  const m = /^vp\/([^/]+)(?:\/|$)/.exec(relPath);
+  if (!m) return false;
+  return m[1] !== currentVpId;
+}
+
+function enforceVpAcl(rel, currentVpId) {
+  if (currentVpId && isVpForeign(rel, currentVpId)) {
+    const e = new Error('acl_blocked');
+    e.code = 'acl_blocked';
+    e.path = rel;
+    throw e;
+  }
+}
+
+// ─── atomic write ──────────────────────────────────────────────
+
+/**
+ * Atomic write: temp + rename. Creates parent directories on demand.
+ * @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);
+}
+
+// ─── memory.md ─────────────────────────────────────────────────
+
+/**
+ * Read a scope's memory.md. Missing → empty string.
+ *
+ * @param {Scope} scope
+ * @param {{ root?: string, currentVpId?: string }} [opts]
+ * @returns {Promise<string>}
+ */
+export async function readMemory(scope, opts = {}) {
+  const { root = DEFAULT_MEMORY_ROOT, currentVpId } = opts;
+  const rel = `${scopeDir(scope)}/memory.md`;
+  enforceVpAcl(rel, currentVpId);
+  const abs = join(root, rel);
+  try { return await fsp.readFile(abs, 'utf8'); }
+  catch (err) {
+    if (err && err.code === 'ENOENT') return '';
+    throw err;
+  }
+}
+
+/**
+ * Atomically rewrite a scope's memory.md.
+ *
+ * @param {Scope} scope
+ * @param {string} content
+ * @param {{ root?: string, currentVpId?: string }} [opts]
+ */
+export async function writeMemory(scope, content, opts = {}) {
+  const { root = DEFAULT_MEMORY_ROOT, currentVpId } = opts;
+  const rel = `${scopeDir(scope)}/memory.md`;
+  enforceVpAcl(rel, currentVpId);
+  const abs = join(root, rel);
+  await atomicWrite(abs, typeof content === 'string' ? content : '');
+}
+
+/**
+ * Append to a scope's memory.md. Used by the rare "direct write" path
+ * (DESIGN-v2 §7.1); main flow is dream-driven rewrites.
+ *
+ * Append is non-atomic with concurrent readers in the strict sense, but a
+ * single appendFile of a small buffer is atomic at the kernel level on POSIX
+ * — sufficient for fragment-sized appends. Two concurrent appenders may
+ * interleave bytes only if both buffers exceed PIPE_BUF; we keep callers in
+ * the single-buffer regime.
+ *
+ * @param {Scope} scope
+ * @param {string} chunk
+ * @param {{ root?: string, currentVpId?: string }} [opts]
+ */
+export async function appendMemory(scope, chunk, opts = {}) {
+  const { root = DEFAULT_MEMORY_ROOT, currentVpId } = opts;
+  const rel = `${scopeDir(scope)}/memory.md`;
+  enforceVpAcl(rel, currentVpId);
+  const abs = join(root, rel);
+  await fsp.mkdir(dirname(abs), { recursive: true });
+  const text = typeof chunk === 'string' ? chunk : '';
+  if (text.length === 0) return;
+  await fsp.appendFile(abs, text, 'utf8');
+}
+
+// ─── summary.md ────────────────────────────────────────────────
+
+/**
+ * Read a scope's summary.md (trimmed). Missing → empty string.
+ *
+ * @param {Scope} scope
+ * @param {{ root?: string, currentVpId?: string }} [opts]
+ * @returns {Promise<string>}
+ */
+export async function readSummary(scope, opts = {}) {
+  const { root = DEFAULT_MEMORY_ROOT, currentVpId } = opts;
+  const rel = `${scopeDir(scope)}/summary.md`;
+  enforceVpAcl(rel, currentVpId);
+  const abs = join(root, rel);
+  try { return (await fsp.readFile(abs, 'utf8')).trim(); }
+  catch (err) {
+    if (err && err.code === 'ENOENT') return '';
+    throw err;
+  }
+}
+
+/**
+ * Atomically rewrite a scope's summary.md. Empty body → empty file.
+ *
+ * @param {Scope} scope
+ * @param {string} body
+ * @param {{ root?: string, currentVpId?: string }} [opts]
+ */
+export async function writeSummary(scope, body, opts = {}) {
+  const { root = DEFAULT_MEMORY_ROOT, currentVpId } = opts;
+  const rel = `${scopeDir(scope)}/summary.md`;
+  enforceVpAcl(rel, currentVpId);
+  const abs = join(root, rel);
+  await atomicWrite(abs, `${(body || '').trim()}\n`);
+}
+
+// ─── scope discovery ───────────────────────────────────────────
+
+/**
+ * Best-effort: ensure a scope's directory exists. Idempotent.
+ *
+ * @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 });
+}
+
+/**
+ * Async variant of ensureScopeSync.
+ *
+ * @param {Scope} scope
+ * @param {{ root?: string }} [opts]
+ */
+export async function ensureScope(scope, opts = {}) {
+  const { root = DEFAULT_MEMORY_ROOT } = opts;
+  const dir = join(root, scopeDir(scope));
+  await fsp.mkdir(dir, { recursive: true });
+}
+
+/**
+ * Enumerate all scopes present on disk. Returns Scope shapes that round-trip
+ * back through `scopeDir`. Used by Triage (DESIGN-v2 §14) to list candidate
+ * scopes for a group's diff.
+ *
+ * Walks shallowly:
+ *   user/                       → { kind: 'user' }
+ *   vp/<id>/                    → { kind: 'vp', id }
+ *   group/<id>/                 → { kind: 'group', id }
+ *   feature/<id>/               → { kind: 'feature', id }
+ *   topic/<l1>/[<l2>/]          → { kind: 'topic', path: [...] }
+ *
+ * Skips entries that are not directories, and any name that fails segment
+ * validation (e.g. accidental `.tmp.*` files at scope root, dotfiles).
+ *
+ * @param {{ root?: string }} [opts]
+ * @returns {Promise<Scope[]>}
+ */
+export async function listScopes(opts = {}) {
+  const { root = DEFAULT_MEMORY_ROOT } = opts;
+  const out = [];
+  if (!existsSync(root)) return out;
+
+  // user/
+  if (existsSync(join(root, 'user'))) out.push({ kind: 'user' });
+
+  // vp/, group/, feature/ — single-level ids
+  for (const kind of ['vp', 'group', 'feature']) {
+    const dir = join(root, kind);
+    let names;
+    try { names = await fsp.readdir(dir, { withFileTypes: true }); }
+    catch (err) {
+      if (err && err.code === 'ENOENT') continue;
+      throw err;
+    }
+    for (const ent of names) {
+      if (!ent.isDirectory()) continue;
+      const id = ent.name;
+      if (!isSafeId(id)) continue;
+      out.push({ kind, id });
+    }
+  }
+
+  // topic/<l1>/[<l2>/]
+  const topicDir = join(root, 'topic');
+  let l1s;
+  try { l1s = await fsp.readdir(topicDir, { withFileTypes: true }); }
+  catch (err) {
+    if (err && err.code === 'ENOENT') l1s = [];
+    else throw err;
+  }
+  for (const l1ent of l1s) {
+    if (!l1ent.isDirectory()) continue;
+    if (!isSafeId(l1ent.name)) continue;
+    const l1 = l1ent.name;
+    // Read l2 entries; if l1 itself contains memory.md, treat as 1-level topic
+    const l1abs = join(topicDir, l1);
+    let l2s;
+    try { l2s = await fsp.readdir(l1abs, { withFileTypes: true }); }
+    catch { l2s = []; }
+    let hasL2 = false;
+    for (const l2ent of l2s) {
+      if (!l2ent.isDirectory()) continue;
+      if (!isSafeId(l2ent.name)) continue;
+      out.push({ kind: 'topic', path: [l1, l2ent.name] });
+      hasL2 = true;
+    }
+    // 1-level topic: present iff l1 has memory.md or summary.md directly
+    if (!hasL2) {
+      const hasMemory = existsSync(join(l1abs, 'memory.md'));
+      const hasSummary = existsSync(join(l1abs, 'summary.md'));
+      if (hasMemory || hasSummary) {
+        out.push({ kind: 'topic', path: [l1] });
+      }
+    }
+  }
+
+  return out;
+}
+
+function isSafeId(s) {
+  if (typeof s !== 'string' || s.length === 0) return false;
+  if (s === '.' || s === '..') return false;
+  if (/[\\/]/.test(s)) return false;
+  return /^[A-Za-z0-9_\-.一-鿿]+$/.test(s);
+}