@yeaft/webchat-agent 0.1.874 → 0.1.875

package/yeaft/sessions/coordinator.js

@@ -1,33 +1,59 @@
 /**
- * sessions/coordinator.js — Session Coordinator.
+ * coordinator.js — Group Coordinator (task-334b).
  *
- * Ported from groups/coordinator.js as part of the chat+group → session
- * unification. Persists envelopes to a SessionHandle's jsonl-log and
- * dispatches user-text turns to target VPs via pre-flow's selection
- * matrix.
+ * Consumes user/VP messages, persists them to the group's 334o jsonl-log,
+ * and dispatches user-text turns to target RoleInstances'
+ * `inputQueue`.
  *
- * N=1 (the old "chat") and N>1 (the old "group") are handled by the same
- * logic — chat is just the degenerate case where pre-flow's @-mention
- * matrix always falls back to the lone roster member.
+ * As of GC.1 Commit B, VP-selection (parseMentions + dispatch matrix:
+ * mention / @all / fallback / vp-author no-op) lives in
+ * `groups/pre-flow.js` so the same logic can be invoked directly by
+ * the parallel fan-out path in web-bridge.js. Coordinator's job is now
+ * narrower: persist the message and translate the selection result
+ * into deliver() calls.
  *
- * This module does NOT run the engine. It only:
- *   1. Persists the message (via SessionHandle.appendMessage)
- *   2. Asks pre-flow which VPs should respond
- *   3. Calls deliver(vpId, envelope) per target
+ * This module DOES NOT run the engine. It only:
+ *   1. Persists the message (via GroupHandle.appendMessage)
+ *   2. Asks pre-flow for the list of target vpIds
+ *   3. Calls a user-supplied deliver(vpId, envelope) per target
  */
 
 import { parseMentions, selectRespondingVps } from './pre-flow.js';
 
+// Re-export so existing importers (`createCoordinator(...).parseMentions`,
+// or modules importing `parseMentions` from coordinator) keep working
+// without churn. New code should import from `./pre-flow.js` directly.
 export { parseMentions };
 
 /**
- * @param {import('./session-store.js').SessionHandle} sessionHandle
- * @param {{ deliver?: (vpId:string, envelope:any) => void, perGroupFanOut?: number }} [options]
+ * Build a Group Coordinator bound to a single GroupHandle.
+ *
+ * @param {import('./session-store.js').GroupHandle} group
+ * @param {Object} [options]
+ * @param {(vpId:string, envelope:any)=>void} [options.deliver]  called per target
+ * @param {number} [options.perGroupFanOut=16]   @all cap (arch §5.3)
+ * @returns {GroupCoordinator}
  */
-export function createCoordinator(sessionHandle, options = {}) {
+export function createCoordinator(group, options = {}) {
   const deliver = options.deliver || (() => {});
   const fanOutCap = options.perGroupFanOut ?? 16;
 
+  /**
+   * Ingest one message. Returns a dispatch report describing what would/did
+   * go out to RoleInstances.
+   *
+   * @param {{
+   *   from: string,              // 'user' | vpId
+   *   role?: 'user'|'assistant',
+   *   text: string,
+   *   taskId?: string|null,
+   *   meta?: any,
+   *   id?: string, ts?: string,
+   * }} input
+   * @param {{ taskMembers?: string[] }} [opts]
+   *   When taskId is set, restricts dispatch to vps in taskMembers (334n owns
+   *   the list). If omitted, coordinator will not filter.
+   */
   function ingest(input, opts = {}) {
     if (!input || typeof input !== 'object') {
       throw new Error('ingest: input required');
@@ -35,15 +61,37 @@ export function createCoordinator(sessionHandle, options = {}) {
     if (typeof input.text !== 'string') {
       throw new Error('ingest: input.text required (string)');
     }
-    const meta = sessionHandle.getMeta();
-    if (!meta) throw new Error('session not initialised (call createSession first)');
+    const meta = group.getMeta();
+    if (!meta) throw new Error('group not initialised (call createSession first)');
 
+    // `fromUser` drives `selectRespondingVps` — when true, the @-mention
+    // matrix runs (mention/broadcast/fallback). When false, VPs cannot
+    // text-@-route (VP-authored free text is surface noise per arch §6).
+    //
+    // route_forward injection is a special case: the message is VP-authored
+    // (role='assistant') but it MUST trigger dispatch (target VP needs to
+    // run). We detect it via `meta.injectedBy === 'route_forward'` and
+    // treat it as "user-like" for dispatch purposes only. Persistence still
+    // honours the caller's `role` field so the on-disk record correctly
+    // attributes the turn to the sending VP, not to the user.
     const isRouteForwardInjection = input?.meta?.injectedBy === 'route_forward';
     const fromUser = input.from === 'user'
       || input.role === 'user'
       || isRouteForwardInjection;
     const mentions = parseMentions(input.text);
 
+    // Persist first — audit log / replay works even if dispatch has bugs.
+    //
+    // Convention: any field on `input` that starts with `_` is treated
+    // as ephemeral and is forwarded to the envelope (so per-turn driver
+    // payloads — image base64 blocks, prompt suffixes — reach the LLM
+    // call) but is NEVER passed to appendMessage. The jsonl-log must
+    // stay lean: base64 in audit history would blow up replay.
+    //
+    // The split is enforced structurally — see the assertion below the
+    // partition loop. Don't loosen it. If a new ephemeral key is added,
+    // it gets the `_` prefix at its source and inherits the protection
+    // for free; no allowlist to maintain.
     const persistInput = {};
     const ephemeral = {};
     for (const [k, v] of Object.entries(input)) {
@@ -53,18 +101,22 @@ export function createCoordinator(sessionHandle, options = {}) {
         persistInput[k] = v;
       }
     }
+    // Structural guarantee: nothing with a `_` prefix may reach the
+    // jsonl-log via `persistInput`. If this ever throws, the `_` rule
+    // got bypassed — fix the caller, not this assertion.
     {
       const leaked = Object.keys(persistInput).filter((k) => typeof k === 'string' && k.startsWith('_'));
       if (leaked.length > 0) {
         throw new Error(`coordinator.ingest: ephemeral fields leaked into persisted record: ${leaked.join(', ')}`);
       }
     }
-    const stored = sessionHandle.appendMessage({
+    const stored = group.appendMessage({
       ...persistInput,
       mentions,
       role: input.role || (fromUser ? 'user' : 'assistant'),
     });
 
+    // Ask pre-flow which VPs (if any) should respond.
     const selection = selectRespondingVps({
       meta,
       fromUser,
@@ -74,6 +126,7 @@ export function createCoordinator(sessionHandle, options = {}) {
       taskMembers: opts.taskMembers,
     });
 
+    // VP-authored: persist but no dispatch.
     if (selection.reason === 'vp-author-no-text-routing') {
       return {
         message: stored,
@@ -119,6 +172,7 @@ export function createCoordinator(sessionHandle, options = {}) {
       };
     }
 
+    // no-default / nothing to dispatch
     return {
       message: stored,
       dispatched: [],
@@ -128,7 +182,7 @@ export function createCoordinator(sessionHandle, options = {}) {
   }
 
   return {
-    session: sessionHandle,
+    group,
     ingest,
     parseMentions,
   };
@@ -139,7 +193,29 @@ function makeEnvelope(msg, meta, trigger, ephemeral = {}) {
     sessionId: meta.id,
     taskId: msg.taskId || null,
     msg,
-    trigger,
+    trigger, // 'broadcast' | 'mention' | 'fallback'
+    // Ephemeral fields (any `_`-prefixed key on coord.ingest input).
+    // Used to ferry per-turn payloads (e.g. image base64 blocks) that
+    // must reach the driver but must NOT be persisted to the group log.
     ...ephemeral,
   };
 }
+
+/**
+ * @typedef {Object} GroupCoordinator
+ * @property {import('./session-store.js').GroupHandle} group
+ * @property {(input:any, opts?:any)=>DispatchReport} ingest
+ * @property {(text:string)=>string[]} parseMentions
+ */
+
+/**
+ * @typedef {Object} DispatchReport
+ * @property {any}       message
+ * @property {string[]}  dispatched
+ * @property {string|null} fallback
+ * @property {Array<{vpId?:string, error:string}>} errors
+ * @property {boolean=}  broadcast
+ * @property {boolean=}  truncatedAtFanOutCap
+ * @property {string=}   skipped
+ */
+

package/yeaft/{groups → sessions}/ids.js

@@ -1,7 +1,7 @@
 /**
  * ids.js — ID generators for the groups slice.
  *
- * Per slice-spec §4 (ID format): groupId uses a slug, msgId uses ULID-ish
+ * Per slice-spec §4 (ID format): sessionId uses a slug, msgId uses ULID-ish
  * lexicographic-sortable form. We implement a small crockford-base32 timestamp
  * + randomness scheme that works cross-platform without external deps.
  */
@@ -37,7 +37,7 @@ export function nextMsgId() {
   return `msg_${newUlidLite()}`;
 }
 
-export function nextGroupId(slug = 'default') {
+export function nextSessionId(slug = 'default') {
   // Slug-tolerant: lowercase a-z0-9_- only.
   const safe = String(slug).toLowerCase().replace(/[^a-z0-9_-]+/g, '-').slice(0, 32) || 'group';
   return `grp_${safe}`;
@@ -47,7 +47,7 @@ export function nextGroupId(slug = 'default') {
  * Reserved vpIds that must never be used as actual VP identifiers — they
  * collide with coordinator-level sentinels (`@all` broadcast, `user`/`system`
  * sender roles) and would cause silent footguns (a vpId=`all` VP would be
- * absorbed into broadcast). Enforced at CRUD boundaries (addVp, createGroup).
+ * absorbed into broadcast). Enforced at CRUD boundaries (addVp, createSession).
  *
  * prev-1 nit #4 (blocker-fix): @foo/@all/@user are the mental bedrock of all
  * future UI — protecting the names here prevents dirty data from reaching the

package/yeaft/{groups → sessions}/index.js

@@ -9,15 +9,15 @@
  *   - Feature flag reader for `yeaft.multiVp.enabled`
  *   - First-boot default group seeder
  *
- * See agent/yeaft/groups/coordinator.js for the dispatch contract.
+ * See agent/yeaft/sessions/coordinator.js for the dispatch contract.
  */
 
 export {
-  openGroup,
-  createGroup,
-  loadGroupMeta,
-  listGroups,
-} from './group-store.js';
+  openSession,
+  createSession,
+  loadSessionMeta,
+  listSessions,
+} from './session-store.js';
 export {
   addVp,
   removeVp,
@@ -34,35 +34,35 @@ export {
   setMultiVpEnabled,
 } from './feature-flag.js';
 export {
-  seedDefaultGroup,
-  DEFAULT_GROUP_ID,
+  seedDefaultSession,
+  DEFAULT_SESSION_ID,
 } from './seed-default.js';
 export {
-  GroupCrudError,
-  makeGroupId,
-  ensureDefaultGroupIfEmpty,
-  createGroupFromSpec,
-  renameGroup,
-  archiveGroup,
-  deleteGroup,
-  purgeArchivedGroups,
+  SessionCrudError,
+  makeSessionId,
+  ensureDefaultSessionIfEmpty,
+  createSessionFromSpec,
+  renameSession,
+  archiveSession,
+  deleteSession,
+  purgeArchivedSessions,
   addMember,
   removeMember,
-  setGroupDefaultVp,
-  snapshotGroups,
-  updateGroupConfig,
-  updateGroupAnnouncement,
-} from './group-crud.js';
+  setSessionDefaultVp,
+  snapshotSessions,
+  updateSessionConfig,
+  updateSessionAnnouncement,
+} from './session-crud.js';
 export {
-  loadGroupConfig,
-  saveGroupConfig,
-  resolveGroupConfig,
-  validateGroupConfig,
-  GroupConfigError,
-} from './group-config.js';
+  loadSessionConfig,
+  saveSessionConfig,
+  resolveSessionConfig,
+  validateSessionConfig,
+  SessionConfigError,
+} from './session-config.js';
 export {
   nextMsgId,
-  nextGroupId,
+  nextSessionId,
   newUlidLite,
   isReservedVpId,
   RESERVED_VP_IDS,

package/yeaft/sessions/pre-flow.js

@@ -1,21 +1,40 @@
 /**
- * sessions/pre-flow.js — explicit pre-flow stage for Yeaft (session-scoped).
+ * groups/pre-flow.js — explicit pre-flow stage for Yeaft.
  *
- * Ported from groups/pre-flow.js as part of the chat+group → session
- * unification. Scope strings use the unified `session/<id>` /
- * `session/<id>/vp/<vp>` shape instead of the legacy
- * `group/<g>` / `chat/<c>` shapes.
+ * Pre-flow is the "before any VP runs" stage. It owns:
  *
- * NOTE: the old groups/pre-flow.js is still in place — callers (web-bridge,
- * coordinator) will switch over in Phase A6/A7. Do not delete the old file
- * until every importer has been migrated.
+ *   (1) VP selection — which VP(s) respond to this user turn?
+ *       Pure function `selectRespondingVps({meta, fromUser, mentions,
+ *       sender, taskMembers, fanOutCap})` that mirrors the legacy
+ *       coordinator dispatch matrix: mention → broadcast → fallback to
+ *       defaultVpId, with VP-authored messages routed via the explicit
+ *       route_forward tool instead of free-text @-mentions.
+ *
+ *   (2) Memory recall — what memory gets pre-injected into each
+ *       responding VP's prompt? Thin wrapper around
+ *       memory/preflow.js's FTS5 recall.
+ *
+ * Commit C will flip the caller (web-bridge.js) to fan out responding
+ * VPs in parallel via Promise.all.
+ *
+ * Why one module: a single import surface for the full pre-flow stage,
+ * a stable seam for the engine, and a place to format FTS hits into the
+ * {profile, entries, formatted} shape the engine already consumes.
  */
 
 import { runPreflow as runFtsPreflow } from '../memory/preflow.js';
+import { resolveFallbackVp, resolveMemberId } from './roster.js';
 
 /** Matches `@vp-id` where id is [A-Za-z0-9_-]+. Captures the id. */
 const MENTION_RE = /(^|\s)@([A-Za-z0-9_][A-Za-z0-9_-]*)/g;
 
+/**
+ * Extract an ordered, unique list of @-mentions from a text string.
+ * Recognises the literal token `@all` as broadcast.
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
 export function parseMentions(text) {
   if (!text || typeof text !== 'string') return [];
   const out = [];
@@ -32,30 +51,42 @@ export function parseMentions(text) {
 }
 
 /**
- * Pure VP-selection for a session. Returns the list of VP ids that should
- * respond to a user turn — mention / @all / fallback to first roster
- * member. (Sessions have no `defaultVpId` field; the first VP in `vpIds`
- * is the fallback.)
- *
- * @param {{
- *   meta: { id: string, vpIds: string[] },
- *   fromUser: boolean,
- *   mentions: string[],
- *   sender?: string,
- *   fanOutCap?: number,
- *   taskMembers?: string[],
- * }} input
+ * @typedef {object} SelectionInput
+ * @property {object}   meta          GroupHandle meta (roster + defaultVpId)
+ * @property {boolean}  fromUser      true = user-authored; false = VP-authored
+ * @property {string[]} mentions      Already-parsed @-mentions
+ * @property {string=}  sender        VP id when fromUser=false
+ * @property {number}   [fanOutCap=16]
+ * @property {string[]=} taskMembers  When set, restricts dispatch to this list
+ */
+
+/**
+ * @typedef {object} SelectionResult
+ * @property {string[]} dispatched              VP ids that should respond
+ * @property {string|null} fallback             The fallback vp, if any
+ * @property {Array<{vpId?:string,error:string}>} errors
+ * @property {'mention'|'broadcast'|'fallback'|'vp-author-no-text-routing'|'no-default'} reason
+ * @property {boolean=} truncatedAtFanOutCap
+ */
+
+/**
+ * Pure VP-selection step of pre-flow. Returns ids only — caller owns
+ * persistence + envelope construction + deliver().
+ *
+ * @param {SelectionInput} input
+ * @returns {SelectionResult}
  */
 export function selectRespondingVps(input) {
-  const meta = input?.meta;
+  const meta = input.meta;
   if (!meta) {
-    return { dispatched: [], fallback: null, errors: [{ error: 'no_session_meta' }], reason: 'no-default' };
+    return { dispatched: [], fallback: null, errors: [{ error: 'no_group_meta' }], reason: 'no-default' };
   }
   const fanOutCap = Number.isFinite(input.fanOutCap) ? input.fanOutCap : 16;
   const taskMembers = Array.isArray(input.taskMembers) ? input.taskMembers : null;
   const mentions = Array.isArray(input.mentions) ? input.mentions : [];
-  const roster = Array.isArray(meta.vpIds) ? meta.vpIds : [];
 
+  // VP-authored messages: never auto-route through @-mentions; VPs hand
+  // off through the explicit route_forward tool instead.
   if (!input.fromUser) {
     return {
       dispatched: [],
@@ -65,36 +96,41 @@ export function selectRespondingVps(input) {
     };
   }
 
+  // @all broadcast — fan out to every roster member except the sender,
+  // honouring fanOutCap and taskMembers.
   if (mentions.includes('all')) {
-    const expanded = roster.filter((v) => v !== input.sender).slice(0, fanOutCap);
-    const scoped = taskMembers ? expanded.filter((v) => taskMembers.includes(v)) : expanded;
+    const roster = meta.roster.filter((v) => v !== input.sender).slice(0, fanOutCap);
+    const scoped = taskMembers ? roster.filter((v) => taskMembers.includes(v)) : roster;
     return {
       dispatched: scoped,
       fallback: null,
       errors: [],
       reason: 'broadcast',
-      truncatedAtFanOutCap: roster.length - 1 > fanOutCap,
+      truncatedAtFanOutCap: meta.roster.length - 1 > fanOutCap,
     };
   }
 
+  // Explicit @-mentions
   if (mentions.length > 0) {
     const dispatched = [];
     const errors = [];
     for (const vpId of mentions) {
-      if (!roster.includes(vpId)) {
+      const canonicalVpId = resolveMemberId(meta, vpId);
+      if (!canonicalVpId) {
         errors.push({ vpId, error: 'not_in_roster' });
         continue;
       }
-      if (taskMembers && !taskMembers.includes(vpId)) {
+      if (taskMembers && !taskMembers.includes(canonicalVpId)) {
         errors.push({ vpId, error: 'not_in_task_members' });
         continue;
       }
-      if (!dispatched.includes(vpId)) dispatched.push(vpId);
+      if (!dispatched.includes(canonicalVpId)) dispatched.push(canonicalVpId);
     }
     return { dispatched, fallback: null, errors, reason: 'mention' };
   }
 
-  const fallback = roster[0] || null;
+  // No @-mention → fallback to defaultVpId (architecture G2)
+  const fallback = resolveFallbackVp(meta);
   if (!fallback) {
     return {
       dispatched: [],
@@ -119,19 +155,63 @@ export function selectRespondingVps(input) {
   };
 }
 
+
+/**
+ * Build the heading for a single scope's formatted memory block.
+ *
+ * Heading style is the original recall-v2 format, kept so the system
+ * prompt the LLM sees stays stable across the FTS migration.
+ *
+ * @param {string} scope
+ * @returns {string}
+ */
 function scopeHeading(scope) {
   if (scope === 'user') return '## Memory: User';
-  let m = /^session\/([^/]+)\/vp\/(.+)$/.exec(scope);
+  // Nested chat scopes first.
+  let m = /^chat\/([^/]+)\/vp\/(.+)$/.exec(scope);
+  if (m) return `## Memory: VP ${m[2]}`;
+  m = /^chat\/([^/]+)$/.exec(scope);
+  if (m) return `## Memory: Chat ${m[1]}`;
+  // Nested session scopes (current).
+  m = /^session\/([^/]+)\/vp\/(.+)$/.exec(scope);
   if (m) return `## Memory: VP ${m[2]}`;
-  m = /^session\/([^/]+)$/.exec(scope);
-  if (m) return `## Memory: Session ${m[1]}`;
+  m = /^session\/([^/]+)\/user$/.exec(scope);
+  if (m) return `## Memory: Session ${m[1]} (user)`;
+  m = /^session\/([^/]+)\/feature\/(.+)$/.exec(scope);
+  if (m) return `## Memory: Feature ${m[2]}`;
+  m = /^session\/([^/]+)\/topic\/(.+)$/.exec(scope);
+  if (m) return `## Memory: Topic ${m[2]}`;
+  // Legacy nested group scopes (un-migrated data).
+  m = /^group\/([^/]+)\/vp\/(.+)$/.exec(scope);
+  if (m) return `## Memory: VP ${m[2]}`;
+  m = /^group\/([^/]+)\/user$/.exec(scope);
+  if (m) return `## Memory: Session ${m[1]} (user)`;
+  m = /^group\/([^/]+)\/feature\/(.+)$/.exec(scope);
+  if (m) return `## Memory: Feature ${m[2]}`;
+  m = /^group\/([^/]+)\/topic\/(.+)$/.exec(scope);
+  if (m) return `## Memory: Topic ${m[2]}`;
+  if (scope.startsWith('session/')) return `## Memory: Session ${scope.slice(8)}`;
+  if (scope.startsWith('group/')) return `## Memory: Session ${scope.slice(6)}`;
   if (scope.startsWith('vp/')) return `## Memory: VP ${scope.slice(3)}`;
+  if (scope.startsWith('feature/')) return `## Memory: Feature ${scope.slice(8)}`;
+  if (scope.startsWith('topic/')) return `## Memory: Topic ${scope.slice(6)}`;
   return `## Memory: ${scope}`;
 }
 
+/**
+ * Format FTS picked segments into the prompt-ready string.
+ *
+ * Picked segments are grouped by scope (preserving the FTS rerank
+ * order within each scope group), then rendered as markdown blocks
+ * with one heading per scope.
+ *
+ * @param {Array<{scope: string, body: string, tags?: string[], kind?: string}>} picked
+ * @returns {string}
+ */
 export function formatPickedForInjection(picked) {
   if (!picked || picked.length === 0) return '';
   const byScope = new Map();
+  // Preserve insertion order (which is rerank order within each scope).
   for (const seg of picked) {
     const scope = seg.scope || 'unknown';
     if (!byScope.has(scope)) byScope.set(scope, []);
@@ -144,22 +224,60 @@ export function formatPickedForInjection(picked) {
       const body = (s.body || '').trim();
       if (body) parts.push(body);
     }
-    parts.push('');
+    parts.push('');   // blank line between scopes
   }
   return parts.join('\n').trim();
 }
 
 /**
- * Canonical scope list for a session VP turn:
- *   ['user', 'session/<id>', 'session/<id>/vp/<vp>']
+ * @typedef {object} MemoryPreflowOptions
+ * @property {string}         userMsg              The user's message
+ * @property {string}         [sessionId]            Active group, if any
+ * @property {string}         [vpId]               Responding VP id, if any
+ * @property {string}         [featureId]          Active feature, if any
+ * @property {string[]}       [extraScopes]        Additional scopes to include
+ * @property {string[]}       [currentTags]        Contextual tags for rerank
+ * @property {number}         [topK]               Max FTS rows fetched (default 50)
+ * @property {number}         [budgetTokens]       Token budget for picked segments
+ */
+
+/**
+ * @typedef {object} MemoryPreflowResult
+ * @property {string}                   profile      User-scope summary (best-effort)
+ * @property {object[]}                 entries      Picked segments (raw)
+ * @property {string}                   formatted    Prompt-ready string
+ * @property {object}                   meta         Raw FTS preflow metadata
+ */
+
+/**
+ * Build the canonical scope list for a given (sessionId, vpId).
+ * Always includes 'user'. The order is significant — preflow.js's scope
+ * filter accepts/rejects by membership, and the formatter renders in
+ * order.
+ *
+ * (2026-05-13: `featureId` scope dropped along with the Feature system.)
  *
- * @param {{ sessionId?: string, vpId?: string, extra?: string[] }} ctx
+ * @param {{sessionId?: string, vpId?: string, extra?: string[]}} ctx
+ * @returns {string[]}
  */
-export function buildRelevantScopes({ sessionId, vpId, extra } = {}) {
+export function buildRelevantScopes({ sessionId, chatId, vpId, extra } = {}) {
   const scopes = ['user'];
-  if (sessionId) {
+  if (chatId) {
+    scopes.push(`chat/${chatId}`);
+    if (vpId) scopes.push(`chat/${chatId}/vp/${vpId}`);
+  } else if (sessionId) {
+    // Read both legacy `group/<id>` and new `session/<id>` scopes so recall
+    // works regardless of which path the writers used for a given session.
+    // (Writers still emit `group/<id>` for back-compat; migration may have
+    // rewritten on-disk data to `session/<id>`.)
     scopes.push(`session/${sessionId}`);
-    if (vpId) scopes.push(`session/${sessionId}/vp/${vpId}`);
+    scopes.push(`session/${sessionId}/user`);
+    scopes.push(`group/${sessionId}`);
+    scopes.push(`group/${sessionId}/user`);
+    if (vpId) {
+      scopes.push(`session/${sessionId}/vp/${vpId}`);
+      scopes.push(`group/${sessionId}/vp/${vpId}`);
+    }
   }
   if (Array.isArray(extra)) {
     for (const s of extra) {
@@ -169,6 +287,21 @@ export function buildRelevantScopes({ sessionId, vpId, extra } = {}) {
   return scopes;
 }
 
+/**
+ * Run memory pre-flow for one VP turn. Thin wrapper around
+ * `memory/preflow.js::runPreflow` that:
+ *
+ *   - resolves canonical scope list from {sessionId, vpId, featureId},
+ *   - invokes FTS5 recall,
+ *   - formats picked segments for prompt injection.
+ *
+ * Returns the engine-consumable {profile, entries, formatted, meta}
+ * shape so the existing recall pipeline can swap in without changes.
+ *
+ * @param {import('../memory/index-db.js').SegmentIndex} index
+ * @param {MemoryPreflowOptions} opts
+ * @returns {MemoryPreflowResult}
+ */
 export function runMemoryPreflow(index, opts) {
   if (!index) {
     return { profile: '', entries: [], formatted: '', meta: { skipped: 'no-index' } };
@@ -180,6 +313,7 @@ export function runMemoryPreflow(index, opts) {
 
   const relevantScopes = buildRelevantScopes({
     sessionId: opts.sessionId,
+    chatId: opts.chatId,
     vpId: opts.vpId,
     extra: opts.extraScopes,
   });
@@ -193,8 +327,10 @@ export function runMemoryPreflow(index, opts) {
     budgetTokens: opts.budgetTokens,
   });
 
-  const userSeg = (result.picked || []).find((p) => p.scope === 'user');
+  // Best-effort profile: pick any user-scope segment body.
+  const userSeg = (result.picked || []).find(p => p.scope === 'user');
   const profile = userSeg ? (userSeg.body || '').trim() : '';
+
   const formatted = formatPickedForInjection(result.picked || []);
 
   return {