@yeaft/webchat-agent 0.1.628 → 0.1.630

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);
+}