@yeaft/webchat-agent 0.1.530 → 0.1.532

package/unify/memory/shard-store.js

@@ -0,0 +1,373 @@
+/**
+ * shard-store.js — task-334f R6 semantic-shard memory store (VP/task/user).
+ *
+ * This sits ON TOP OF 334o's `storage/shard-store.js` primitive. It adds:
+ *   - R6 entry schema (shard / sourceRef / supersedes / supersededBy / authoredBy)
+ *   - Frontmatter body serialisation (markdown-friendly, grep-able on disk)
+ *   - Supersede chain management (Δ26.2 Phase B)
+ *   - Atomic re-compression handoff (`memory-<shard>.md.compacting`)
+ *   - Migration stub from legacy R5 `memory-NNN.md` → semantic shards (334i)
+ *
+ * Hard boundaries (task-334f guardrails):
+ *   - does NOT touch 334o's jsonl-log layer
+ *   - does NOT run dream extract / re-compression decisions (334g)
+ *   - does NOT implement user-memory business logic (334l reuses this lib)
+ */
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync } from 'fs';
+import { join } from 'path';
+import { openShardStore, writeAtomic } from '../storage/index.js';
+import {
+  rebuildShardIndexFromDisk,
+  saveShardIndex,
+} from '../storage/shard-index.js';
+import {
+  buildShardSchema,
+  softCapFor,
+  PROJECT_DERIVE_THRESHOLD,
+  MAX_VP_SHARDS,
+  validateR6Entry,
+  AUTHORED_BY,
+} from './schema.js';
+
+const COMPACTING_SUFFIX = '.compacting';
+
+/**
+ * Open (or create) an R6 memory shard store rooted at `dir`.
+ *
+ * @param {string} dir   filesystem directory (e.g. `~/.yeaft/memory/vp/<vpId>`)
+ * @param {'vp'|'task'|'user'} kind
+ * @param {{ extraShards?: string[] }} [opts]
+ * @returns {object} handle with put/get/query/remove/compact/...
+ */
+export function openMemoryShardStore(dir, kind = 'vp', opts = {}) {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  // Hydrate any pre-existing project-* shards from disk so the schema
+  // allow-list recognises them on this open.
+  const extraShards = new Set(opts.extraShards || []);
+  for (const name of discoverOnDiskShards(dir)) {
+    if (!extraShards.has(name)) extraShards.add(name);
+  }
+  const schema = buildShardSchema(kind, { extraShards: [...extraShards] });
+  const inner = openShardStore(dir, schema);
+
+  /**
+   * Put an R6 entry. Merges the rich entry schema into `body` (frontmatter)
+   * and surfaces the 5 filter-worthy fields through `meta`.
+   */
+  function put(entry) {
+    validateR6Entry(entry);
+    const body = serialiseR6Body(entry);
+    const meta = pickMeta(entry);
+    const res = inner.put({
+      id: entry.id,
+      shard: entry.shard,
+      body,
+      meta,
+    });
+    return res;
+  }
+
+  /** Retrieve an R6 entry (returns the parsed frontmatter + body). */
+  function get(id) {
+    const raw = inner.get(id);
+    if (!raw) return null;
+    const parsed = parseR6Body(raw.body);
+    return {
+      ...parsed,
+      id: raw.id,
+      shard: raw.shard,
+      _meta: raw.meta || {},
+    };
+  }
+
+  /** Query. See storage/shard-store.js for the filter shape. */
+  function query(filter = {}) {
+    const res = inner.query(filter);
+    return {
+      results: res.results.map(mapRecordToThinEntry),
+      needsRecompression: res.needsRecompression.slice(),
+    };
+  }
+
+  /** Remove an entry; underlying shard compacts immediately. */
+  function remove(id) { return inner.remove(id); }
+
+  /**
+   * Supersede: create a new entry N that replaces olds M[...].
+   * Writes N with supersedes=M[...], then marks each M.supersededBy=N.
+   * Old entries are NOT removed — they stay for audit / memory_trace.
+   */
+  function supersede({ newEntry, oldIds }) {
+    validateR6Entry(newEntry);
+    if (!Array.isArray(oldIds) || oldIds.length === 0) {
+      throw new Error('supersede: oldIds required (non-empty)');
+    }
+    const supersedes = oldIds.slice();
+    const write = { ...newEntry, supersedes };
+    const r = put(write);
+
+    for (const oldId of oldIds) {
+      const existing = get(oldId);
+      if (!existing) continue;
+      const updated = { ...existing, supersededBy: newEntry.id };
+      put(updated);
+    }
+    return r;
+  }
+
+  /**
+   * Atomic re-compression handoff:
+   * caller writes the new shard body to `memory-<shard>.md.compacting`,
+   * then calls `commitRecompression(shard)` which atomically renames it
+   * over the live file. Readers always see either the old or the new file.
+   *
+   * Consumers (334g dream) build the new body themselves; we just manage
+   * the rename + stats recomputation.
+   */
+  function stageRecompression(shardName, newBody) {
+    const tmpPath = join(dir, `memory-${shardName}.md${COMPACTING_SUFFIX}`);
+    writeAtomic(tmpPath, newBody);
+    return tmpPath;
+  }
+
+  function commitRecompression(shardName) {
+    const livePath = join(dir, `memory-${shardName}.md`);
+    const tmpPath = join(dir, `memory-${shardName}.md${COMPACTING_SUFFIX}`);
+    if (!existsSync(tmpPath)) {
+      throw new Error(`commitRecompression: no tmp file at ${tmpPath}`);
+    }
+    renameSync(tmpPath, livePath);
+    // The caller-supplied body replaced the whole shard. The old index rows
+    // for this shard are stale (new ids / offsets). Rebuild that shard's
+    // index rows from disk by delegating to the storage primitive — it walks
+    // START/END markers and recomputes offsets. We keep other shards intact.
+    const schema = buildShardSchema(kind, { extraShards: [...extraShards] });
+    const rebuilt = rebuildShardIndexFromDisk(dir, schema);
+    const innerIndex = inner.getIndex();
+    // Swap this shard's rows + bucket.
+    innerIndex.entries = innerIndex.entries.filter(e => e.shard !== shardName)
+      .concat(rebuilt.entries.filter(e => e.shard === shardName));
+    if (rebuilt.shards[shardName]) {
+      innerIndex.shards[shardName] = rebuilt.shards[shardName];
+    }
+    saveShardIndex(dir, innerIndex);
+  }
+
+  function abortRecompression(shardName) {
+    const tmpPath = join(dir, `memory-${shardName}.md${COMPACTING_SUFFIX}`);
+    if (existsSync(tmpPath)) unlinkSync(tmpPath);
+  }
+
+  /** Return shard-level stats (byte count, entry count, soft cap). */
+  function stats() {
+    const raw = inner.stats();
+    const shards = {};
+    for (const [name, bucket] of Object.entries(raw.shards)) {
+      shards[name] = { ...bucket, softCap: softCapFor(name) };
+    }
+    return { shards, count: raw.count };
+  }
+
+  /**
+   * Hint for the dream layer — returns `project-<slug>` candidate when
+   * ≥ PROJECT_DERIVE_THRESHOLD entries share a groupId and no project
+   * shard exists for that slug yet. Returns `null` otherwise.
+   *
+   * The actual derive (creating the shard file + re-compressing entries
+   * into it) is 334g dream work; this slice only advertises the hint so
+   * dream can schedule.
+   */
+  function projectDeriveHint() {
+    const groupCounts = new Map();
+    const { results } = inner.query({});
+    for (const rec of results) {
+      const gid = rec.meta?.groupId;
+      if (!gid) continue;
+      groupCounts.set(gid, (groupCounts.get(gid) || 0) + 1);
+    }
+    for (const [gid, count] of groupCounts) {
+      if (count < PROJECT_DERIVE_THRESHOLD) continue;
+      const slug = slugify(gid);
+      const shardName = `project-${slug}`;
+      const shardNames = Object.keys(inner.stats().shards);
+      if (shardNames.includes(shardName)) continue;
+      if (shardNames.length >= MAX_VP_SHARDS) continue;
+      return { groupId: gid, shard: shardName, count };
+    }
+    return null;
+  }
+
+  function close() { /* underlying store is stateless (index saved on every op) */ }
+
+  return {
+    put,
+    get,
+    query,
+    remove,
+    supersede,
+    stageRecompression,
+    commitRecompression,
+    abortRecompression,
+    stats,
+    projectDeriveHint,
+    close,
+    _innerForTest: inner,
+  };
+}
+
+// ─── Serialisation ──────────────────────────────────────────────
+
+function serialiseR6Body(entry) {
+  const fm = ['---'];
+  fm.push(`id: ${entry.id}`);
+  if (entry.vp) fm.push(`vp: ${entry.vp}`);
+  if (entry.taskId) fm.push(`taskId: ${entry.taskId}`);
+  fm.push(`kind: ${entry.kind}`);
+  fm.push(`shard: ${entry.shard}`);
+  if (entry.sourceRef) {
+    fm.push('sourceRef:');
+    if (entry.sourceRef.groupId)     fm.push(`  groupId: ${entry.sourceRef.groupId}`);
+    if (entry.sourceRef.taskId)      fm.push(`  taskId: ${entry.sourceRef.taskId}`);
+    if (Array.isArray(entry.sourceRef.msgIds) && entry.sourceRef.msgIds.length) {
+      fm.push(`  msgIds: [${entry.sourceRef.msgIds.join(', ')}]`);
+    }
+    if (entry.sourceRef.timeWindow)  fm.push(`  timeWindow: ${entry.sourceRef.timeWindow}`);
+    if (entry.sourceRef.hint)        fm.push(`  hint: ${JSON.stringify(entry.sourceRef.hint)}`);
+  }
+  if (Array.isArray(entry.supersedes) && entry.supersedes.length) {
+    fm.push(`supersedes: [${entry.supersedes.join(', ')}]`);
+  }
+  if (entry.supersededBy) fm.push(`supersededBy: ${entry.supersededBy}`);
+  if (entry.pinned != null) fm.push(`pinned: ${entry.pinned ? 'true' : 'false'}`);
+  if (Array.isArray(entry.tags) && entry.tags.length) {
+    fm.push(`tags: [${entry.tags.join(', ')}]`);
+  }
+  if (entry.authoredBy) fm.push(`authoredBy: ${entry.authoredBy}`);
+  const now = new Date().toISOString();
+  fm.push(`createdAt: ${entry.createdAt || now}`);
+  fm.push(`updatedAt: ${now}`);
+  fm.push('---');
+  fm.push('');
+  fm.push(entry.body || entry.content || '');
+  return fm.join('\n');
+}
+
+function parseR6Body(raw) {
+  if (!raw || !raw.startsWith('---')) return { body: raw || '' };
+  const endIdx = raw.indexOf('\n---', 3);
+  if (endIdx === -1) return { body: raw };
+  const fm = raw.slice(4, endIdx).trim();
+  const body = raw.slice(endIdx + 4).replace(/^\n+/, '');
+  const out = { body };
+  let inSourceRef = false;
+  const sourceRef = {};
+  for (const line of fm.split('\n')) {
+    if (/^sourceRef:\s*$/.test(line)) { inSourceRef = true; continue; }
+    if (inSourceRef && /^\s+/.test(line)) {
+      const m = line.match(/^\s+(\w+):\s*(.*)$/);
+      if (!m) continue;
+      const [, k, v] = m;
+      if (k === 'msgIds') {
+        sourceRef.msgIds = v.replace(/^\[|\]$/g, '').split(',').map(s => s.trim()).filter(Boolean);
+      } else if (k === 'hint') {
+        try { sourceRef.hint = JSON.parse(v); } catch { sourceRef.hint = v; }
+      } else {
+        sourceRef[k] = v;
+      }
+      continue;
+    }
+    inSourceRef = false;
+    const m = line.match(/^(\w+):\s*(.*)$/);
+    if (!m) continue;
+    const [, k, v] = m;
+    switch (k) {
+      case 'id':            out.id = v; break;
+      case 'vp':            out.vp = v; break;
+      case 'taskId':        out.taskId = v; break;
+      case 'kind':          out.kind = v; break;
+      case 'shard':         out.shard = v; break;
+      case 'supersededBy':  out.supersededBy = v; break;
+      case 'pinned':        out.pinned = v === 'true'; break;
+      case 'authoredBy':    out.authoredBy = v; break;
+      case 'createdAt':     out.createdAt = v; break;
+      case 'updatedAt':     out.updatedAt = v; break;
+      case 'supersedes':
+        out.supersedes = v.replace(/^\[|\]$/g, '').split(',').map(s => s.trim()).filter(Boolean);
+        break;
+      case 'tags':
+        out.tags = v.replace(/^\[|\]$/g, '').split(',').map(s => s.trim()).filter(Boolean);
+        break;
+      default: break;
+    }
+  }
+  if (Object.keys(sourceRef).length > 0) out.sourceRef = sourceRef;
+  return out;
+}
+
+function pickMeta(entry) {
+  // Meta is only the fields the 334o query() layer filters on.
+  const meta = {};
+  if (entry.kind)   meta.kind = entry.kind;
+  if (entry.tags)   meta.tags = entry.tags.slice();
+  if (entry.pinned) meta.pinned = true;
+  if (entry.sourceRef?.groupId) meta.groupId = entry.sourceRef.groupId;
+  if (entry.sourceRef?.taskId)  meta.taskId  = entry.sourceRef.taskId;
+  if (entry.supersededBy) meta.supersededBy = entry.supersededBy;
+  return meta;
+}
+
+function mapRecordToThinEntry(rec) {
+  return {
+    id: rec.id,
+    shard: rec.shard,
+    kind: rec.meta?.kind,
+    tags: rec.meta?.tags || [],
+    pinned: Boolean(rec.meta?.pinned),
+    groupId: rec.meta?.groupId,
+    taskId: rec.meta?.taskId,
+    supersededBy: rec.meta?.supersededBy || null,
+  };
+}
+
+function slugify(s) {
+  return String(s || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40);
+}
+
+function discoverOnDiskShards(dir) {
+  try {
+    return readdirSync(dir)
+      .filter(f => /^memory-[A-Za-z0-9_-]+\.md$/.test(f))
+      .map(f => f.replace(/^memory-/, '').replace(/\.md$/, ''));
+  } catch { return []; }
+}
+
+// ─── Migration stub (§Δ23 / 334i) ───────────────────────────────
+
+/**
+ * Migration stub: map a legacy R5 `memory-NNN.md` shard file path into a
+ * semantic shard assignment. Actual batch migration runs in 334i; this
+ * slice only defines the classifier API so dependent code can stub it.
+ *
+ * @param {object} legacyEntry  parsed legacy entry { kind, scope, tags, ... }
+ * @returns {string}            semantic shard name ("skill" / "lessons" / ...)
+ */
+export function classifyLegacyEntryToShard(legacyEntry) {
+  if (!legacyEntry || typeof legacyEntry !== 'object') return 'skill';
+  const kind = legacyEntry.kind || 'fact';
+  switch (kind) {
+    case 'lesson':     return 'lessons';
+    case 'preference': return 'preferences';
+    case 'identity':   return 'preferences';
+    case 'relation':   return 'relations';
+    case 'skill':      return 'skill';
+    default:           return 'skill';
+  }
+}
+
+export { AUTHORED_BY };

package/unify/task-message.js

@@ -0,0 +1,144 @@
+/**
+ * task-message.js — R6 §Δ28 / §Δ31.6 task-scoped direct messaging.
+ *
+ * Replaces the withdrawn R3 `unify_task_private_chat` event with a simple
+ * echo-able `task_message` pair:
+ *
+ *   inbound  (web → agent):  `unify_task_message`
+ *     { type, groupId, taskId, vpId, text, mentions?, replyTo?, requestId? }
+ *   outbound (agent → web):  `task_message`
+ *     { type, groupId, taskId, vpId, msgId, text, mentions, replyTo,
+ *       ts, requestId? }
+ *
+ * This module owns only the *wire adapter* — the payload is validated,
+ * stamped with msgId + ts, and broadcast back so the sender's UI and any
+ * other connected views converge on the same record. Persistence + task
+ * ACL enforcement are deliberately deferred to task-334l (per PM dispatch:
+ * "user_memory_* 实际 ingestion 归 334l"); the parallel task-private
+ * storage hook follows the same phasing.
+ *
+ * Invariants:
+ *   • Never throws on the WS hot path — bad payloads reply with a
+ *     `task_message_rejected` event carrying a stable `code` string for
+ *     UI i18n (mirrors the vp_crud_result contract from 334-ui-g).
+ *   • The outbound event field order and keys are considered wire-frozen
+ *     per R6 §Δ31.6 table; additive fields only in future slices.
+ */
+
+import { nextMsgId, isValidVpId } from './groups/ids.js';
+
+/** Known `reject` codes — kept stable so 334-ui-* can key i18n on them. */
+export const TASK_MESSAGE_REJECT_CODES = Object.freeze({
+  MISSING_GROUP_ID: 'missing_group_id',
+  MISSING_TASK_ID: 'missing_task_id',
+  MISSING_VP_ID: 'missing_vp_id',
+  INVALID_VP_ID: 'invalid_vp_id',
+  EMPTY_TEXT: 'empty_text',
+  TEXT_TOO_LONG: 'text_too_long',
+});
+
+/** Soft body cap — matches the shard-entry cap used elsewhere in R6 (§Δ26.3). */
+export const MAX_TEXT_LENGTH = 16_384;
+
+/**
+ * Pure validator. Returns `{ ok: true, payload }` or `{ ok: false, code }`.
+ * No IO, no clock reads — safe to unit-test in isolation.
+ *
+ * @param {any} msg — raw WS message from the web client
+ */
+export function validateTaskMessage(msg) {
+  if (!msg || typeof msg !== 'object') {
+    return { ok: false, code: TASK_MESSAGE_REJECT_CODES.MISSING_GROUP_ID };
+  }
+  const { groupId, taskId, vpId, text } = msg;
+  if (!groupId || typeof groupId !== 'string') {
+    return { ok: false, code: TASK_MESSAGE_REJECT_CODES.MISSING_GROUP_ID };
+  }
+  if (!taskId || typeof taskId !== 'string') {
+    return { ok: false, code: TASK_MESSAGE_REJECT_CODES.MISSING_TASK_ID };
+  }
+  if (!vpId || typeof vpId !== 'string') {
+    return { ok: false, code: TASK_MESSAGE_REJECT_CODES.MISSING_VP_ID };
+  }
+  // Allow the reserved `user` sentinel as a speaker here — tasks can have
+  // human-user messages alongside VP messages. Any other vpId must pass
+  // the full shape check (rejects `all`, `system`, pure digits, etc.).
+  if (vpId !== 'user' && !isValidVpId(vpId)) {
+    return { ok: false, code: TASK_MESSAGE_REJECT_CODES.INVALID_VP_ID };
+  }
+  if (typeof text !== 'string' || text.length === 0) {
+    return { ok: false, code: TASK_MESSAGE_REJECT_CODES.EMPTY_TEXT };
+  }
+  if (text.length > MAX_TEXT_LENGTH) {
+    return { ok: false, code: TASK_MESSAGE_REJECT_CODES.TEXT_TOO_LONG };
+  }
+
+  const mentions = Array.isArray(msg.mentions)
+    ? msg.mentions.filter(m => typeof m === 'string' && m.length > 0).slice(0, 32)
+    : [];
+  const replyTo = typeof msg.replyTo === 'string' && msg.replyTo.length > 0
+    ? msg.replyTo
+    : null;
+
+  return {
+    ok: true,
+    payload: { groupId, taskId, vpId, text, mentions, replyTo },
+  };
+}
+
+/**
+ * Build the outbound `task_message` event from a validated payload.
+ * Exposed separately so tests can snapshot the wire shape without
+ * needing a live send fn.
+ *
+ * @param {{groupId:string,taskId:string,vpId:string,text:string,mentions:string[],replyTo:?string}} payload
+ * @param {{now?:()=>number, msgId?:()=>string, requestId?:string}} [opts]
+ */
+export function buildTaskMessageEvent(payload, opts = {}) {
+  const now = typeof opts.now === 'function' ? opts.now : Date.now;
+  const mkId = typeof opts.msgId === 'function' ? opts.msgId : nextMsgId;
+  const evt = {
+    type: 'task_message',
+    groupId: payload.groupId,
+    taskId: payload.taskId,
+    vpId: payload.vpId,
+    msgId: mkId(),
+    text: payload.text,
+    mentions: payload.mentions,
+    replyTo: payload.replyTo,
+    ts: now(),
+  };
+  if (opts.requestId) evt.requestId = opts.requestId;
+  return evt;
+}
+
+/**
+ * Build the outbound `task_message_rejected` event.
+ * @param {string} code — one of TASK_MESSAGE_REJECT_CODES
+ * @param {any} msg — original inbound msg (for requestId echo)
+ */
+export function buildTaskMessageRejected(code, msg) {
+  const evt = { type: 'task_message_rejected', code };
+  if (msg && typeof msg.requestId === 'string') evt.requestId = msg.requestId;
+  if (msg && typeof msg.groupId === 'string') evt.groupId = msg.groupId;
+  if (msg && typeof msg.taskId === 'string') evt.taskId = msg.taskId;
+  return evt;
+}
+
+/**
+ * WS handler entry point. Validates, echoes, never throws.
+ *
+ * @param {any} msg
+ * @param {(event:object)=>void} sendUnifyEvent
+ * @param {{now?:()=>number, msgId?:()=>string}} [opts] — test seams
+ */
+export function handleUnifyTaskMessage(msg, sendUnifyEvent, opts = {}) {
+  const result = validateTaskMessage(msg);
+  if (!result.ok) {
+    try { sendUnifyEvent(buildTaskMessageRejected(result.code, msg)); } catch { /* best-effort */ }
+    return;
+  }
+  const requestId = msg && typeof msg.requestId === 'string' ? msg.requestId : undefined;
+  const evt = buildTaskMessageEvent(result.payload, { ...opts, requestId });
+  try { sendUnifyEvent(evt); } catch { /* never crash WS pipeline */ }
+}

package/unify/tools/index.js

@@ -22,6 +22,8 @@ import memoryRead from './memory-read.js';
 import memoryWrite from './memory-write.js';
 import memorySearch, { memorySearchAlias } from './memory-search.js';
 import memoryQuery from './memory-query.js';
+import memoryTrace from './memory-trace.js';
+import openSourceMessage from './open-source-message.js';
 import webSearch from './web-search.js';
 import webFetch from './web-fetch.js';
 import historySearch from './history-search.js';
@@ -98,6 +100,8 @@ export const allTools = [
   memorySearch,
   memorySearchAlias,
   memoryQuery,
+  memoryTrace,
+  openSourceMessage,
   webSearch,
   webFetch,
   historySearch,

package/unify/tools/memory-trace.js

@@ -0,0 +1,135 @@
+/**
+ * memory-trace.js — task-334f R6 §Δ24.3.
+ *
+ * Given a memory id, return the full entry (including sourceRef) plus the
+ * original source messages referenced by sourceRef.msgIds / timeWindow.
+ *
+ * Hard guardrails (task-334f):
+ *   - Results are returned to the current turn ONLY. Nothing is written back
+ *     to memory; the extraction lane sees its own copy.
+ *   - Does not do cross-group fan-out. A trace is anchored to one groupId.
+ */
+
+import { defineTool } from './types.js';
+
+const MAX_BYTES = 64 * 1024;
+
+export default defineTool({
+  name: 'memory_trace',
+  description: `Trace a memory entry back to its original source messages.
+
+Use this when a recalled memory body is insufficient and you need the raw
+discussion. Returns the full memory entry (with sourceRef) plus the source
+messages from the group jsonl log.
+
+Parameters:
+  - memId (required): the memory id (from recall)
+  - expand: "full" (default, exact msgIds) | "window" (expand around timeWindow)
+
+Returns JSON: { memory, messages[], truncated? }.
+The result is NOT written back to memory — it is context for the current turn
+only.`,
+  parameters: {
+    type: 'object',
+    properties: {
+      memId:  { type: 'string', description: 'Memory entry id' },
+      expand: { type: 'string', enum: ['full', 'window'], default: 'full' },
+    },
+    required: ['memId'],
+  },
+  isConcurrencySafe: () => true,
+  isReadOnly: () => true,
+  async execute(input, ctx) {
+    const memId = input?.memId;
+    if (!memId || typeof memId !== 'string') {
+      return JSON.stringify({ error: 'memId required (string)' });
+    }
+    const expand = input?.expand === 'window' ? 'window' : 'full';
+
+    const store = ctx?.memoryShardStore;
+    if (!store) {
+      return JSON.stringify({ error: 'R6 memory shard store not initialised' });
+    }
+    const entry = store.get(memId);
+    if (!entry) {
+      return JSON.stringify({ error: `memory entry not found: ${memId}` });
+    }
+
+    const sourceRef = entry.sourceRef || null;
+    if (!sourceRef) {
+      return JSON.stringify({
+        memory: entry,
+        messages: [],
+        note: 'entry has no sourceRef (pure declaration)',
+      });
+    }
+
+    const coordinator = ctx?.coordinator;
+    const groupId = sourceRef.groupId;
+    if (!coordinator || !groupId) {
+      return JSON.stringify({
+        memory: entry,
+        messages: [],
+        note: 'no group coordinator available',
+      });
+    }
+
+    const group = typeof coordinator.openGroup === 'function'
+      ? coordinator.openGroup(groupId)
+      : null;
+    if (!group) {
+      return JSON.stringify({
+        memory: entry,
+        messages: [],
+        note: `group ${groupId} not resolvable`,
+      });
+    }
+
+    const messages = [];
+    let bytes = 0;
+    let truncated = false;
+
+    if (expand === 'full' && Array.isArray(sourceRef.msgIds) && sourceRef.msgIds.length) {
+      const targetSet = new Set(sourceRef.msgIds);
+      // Walk only the smallest overlapping range instead of streaming all.
+      const first = sourceRef.msgIds[0];
+      const last  = sourceRef.msgIds[sourceRef.msgIds.length - 1];
+      const iter = typeof group.readMessageRange === 'function'
+        ? group.readMessageRange(first, last)
+        : group.streamMessages();
+      for (const msg of iter) {
+        if (!targetSet.has(msg.id)) continue;
+        const chunk = estimateBytes(msg);
+        if (bytes + chunk > MAX_BYTES) { truncated = true; break; }
+        messages.push(msg);
+        bytes += chunk;
+      }
+    } else if (expand === 'window' && sourceRef.timeWindow) {
+      // timeWindow is "ISO..ISO"; best-effort textual compare works for ULIDs/ISO.
+      const [t0, t1] = String(sourceRef.timeWindow).split('..');
+      for (const msg of group.streamMessages()) {
+        const ts = msg.ts || '';
+        if (t0 && ts < t0) continue;
+        if (t1 && ts > t1) break;
+        const chunk = estimateBytes(msg);
+        if (bytes + chunk > MAX_BYTES) { truncated = true; break; }
+        messages.push(msg);
+        bytes += chunk;
+      }
+    }
+
+    return JSON.stringify({
+      memory: entry,
+      messages,
+      ...(truncated ? { truncated: true } : {}),
+    });
+  },
+});
+
+function estimateBytes(msg) {
+  try {
+    return Buffer.byteLength(JSON.stringify(msg), 'utf8');
+  } catch {
+    return 512;
+  }
+}