@yeaft/webchat-agent 0.1.521 → 0.1.522

package/package.json

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

package/unify/groups/coordinator.js

@@ -0,0 +1,206 @@
+/**
+ * coordinator.js — Group Coordinator (task-334b).
+ *
+ * Consumes user/VP messages, persists them to the group's 334o jsonl-log,
+ * parses @-mentions (user-posted only), and dispatches to target RoleInstances'
+ * `inputQueue`. Aligned with architecture §5 / §6:
+ *
+ *   - Text @-mentions trigger routing ONLY for `role === 'user'` messages.
+ *     VP-authored @ mentions are surface noise; VPs dispatch via the
+ *     route_forward tool (334d), not free text.
+ *   - `@all` fans out to every roster member except the sender (perGroupFanOut
+ *     cap honoured via options).
+ *   - Unknown @-targets return `{ error: 'not_in_roster' }` in the dispatch
+ *     report; coordinator does not mutate roster on stranger mentions.
+ *   - No @-mention on a user message → falls back to `defaultVpId` via
+ *     resolveFallbackVp (architecture G2).
+ *   - taskId: if the inbound message carries `taskId`, dispatch is scoped to
+ *     task.members — passed in via `options.taskMembers` (task storage lives
+ *     in 334n; coordinator only enforces the filter when the caller provides
+ *     the member list).
+ *
+ * This module DOES NOT run the engine. It only:
+ *   1. Persists the message (via GroupHandle.appendMessage)
+ *   2. Resolves the list of target vpIds
+ *   3. Calls a user-supplied deliver(vpId, envelope) per target
+ *
+ * That lets 334c (RoleInstance/Engine) own how a target is actually woken up
+ * (inputQueue push, status transition, etc) without coordinator owning it.
+ */
+
+import { isMember, resolveFallbackVp } 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.
+ */
+export function parseMentions(text) {
+  if (!text || typeof text !== 'string') return [];
+  const out = [];
+  const seen = new Set();
+  MENTION_RE.lastIndex = 0;
+  let m;
+  while ((m = MENTION_RE.exec(text))) {
+    const id = m[2];
+    if (seen.has(id)) continue;
+    seen.add(id);
+    out.push(id);
+  }
+  return out;
+}
+
+/**
+ * Build a Group Coordinator bound to a single GroupHandle.
+ *
+ * @param {import('./group-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(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');
+    }
+    if (typeof input.text !== 'string') {
+      throw new Error('ingest: input.text required (string)');
+    }
+    const meta = group.getMeta();
+    if (!meta) throw new Error('group not initialised (call createGroup first)');
+
+    const fromUser = input.from === 'user' || input.role === 'user';
+    const mentions = parseMentions(input.text);
+
+    // Persist first — audit log / replay works even if dispatch has bugs.
+    const stored = group.appendMessage({
+      ...input,
+      mentions,
+      role: input.role || (fromUser ? 'user' : 'assistant'),
+    });
+
+    // VP-authored messages: persist but do NOT dispatch (§6: no text @ routing)
+    if (!fromUser) {
+      return {
+        message: stored,
+        dispatched: [],
+        fallback: null,
+        errors: [],
+        skipped: 'vp-author-no-text-routing',
+      };
+    }
+
+    // @all broadcast
+    if (mentions.includes('all')) {
+      const roster = meta.roster.filter((v) => v !== input.from).slice(0, fanOutCap);
+      const scoped = opts.taskMembers
+        ? roster.filter((v) => opts.taskMembers.includes(v))
+        : roster;
+      const envelope = makeEnvelope(stored, meta, 'broadcast');
+      for (const vpId of scoped) deliver(vpId, envelope);
+      return {
+        message: stored,
+        dispatched: scoped,
+        fallback: null,
+        errors: [],
+        broadcast: true,
+        truncatedAtFanOutCap: meta.roster.length - 1 > fanOutCap,
+      };
+    }
+
+    // Explicit @-mentions
+    if (mentions.length > 0) {
+      const dispatched = [];
+      const errors = [];
+      for (const vpId of mentions) {
+        if (!isMember(meta, vpId)) {
+          errors.push({ vpId, error: 'not_in_roster' });
+          continue;
+        }
+        if (opts.taskMembers && !opts.taskMembers.includes(vpId)) {
+          errors.push({ vpId, error: 'not_in_task_members' });
+          continue;
+        }
+        dispatched.push(vpId);
+        deliver(vpId, makeEnvelope(stored, meta, 'mention'));
+      }
+      return { message: stored, dispatched, fallback: null, errors };
+    }
+
+    // No @-mention → fallback
+    const fallback = resolveFallbackVp(meta);
+    if (!fallback) {
+      return {
+        message: stored,
+        dispatched: [],
+        fallback: null,
+        errors: [{ error: 'no_default_vp' }],
+      };
+    }
+    if (opts.taskMembers && !opts.taskMembers.includes(fallback)) {
+      return {
+        message: stored,
+        dispatched: [],
+        fallback: null,
+        errors: [{ vpId: fallback, error: 'not_in_task_members' }],
+      };
+    }
+    deliver(fallback, makeEnvelope(stored, meta, 'fallback'));
+    return { message: stored, dispatched: [fallback], fallback, errors: [] };
+  }
+
+  return {
+    group,
+    ingest,
+    parseMentions,
+  };
+}
+
+function makeEnvelope(msg, meta, trigger) {
+  return {
+    groupId: meta.id,
+    taskId: msg.taskId || null,
+    msg,
+    trigger, // 'broadcast' | 'mention' | 'fallback'
+  };
+}
+
+/**
+ * @typedef {Object} GroupCoordinator
+ * @property {import('./group-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/unify/groups/feature-flag.js

@@ -0,0 +1,49 @@
+/**
+ * feature-flag.js — Reads `config.unify.multiVp.enabled` from ~/.yeaft/config.json.
+ *
+ * Per architecture §11: multi-VP group mode is opt-in for MVP. The flag
+ * gates UI entry points and (later) migration. This module returns a plain
+ * boolean and never throws — missing/corrupt config falls back to `false`.
+ *
+ * A second helper `setMultiVpEnabled(dir, enabled)` writes through via
+ * writeAtomic so tests and future settings UI can toggle it.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { writeAtomic } from '../storage/index.js';
+
+const CONFIG_FILE = 'config.json';
+const FLAG_PATH = ['unify', 'multiVp', 'enabled'];
+
+function readConfig(yeaftDir) {
+  const path = join(yeaftDir, CONFIG_FILE);
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) || {};
+  } catch {
+    return {};
+  }
+}
+
+export function isMultiVpEnabled(yeaftDir) {
+  const cfg = readConfig(yeaftDir);
+  let cur = cfg;
+  for (const seg of FLAG_PATH) {
+    if (!cur || typeof cur !== 'object') return false;
+    cur = cur[seg];
+  }
+  return Boolean(cur);
+}
+
+export function setMultiVpEnabled(yeaftDir, enabled) {
+  const cfg = readConfig(yeaftDir);
+  let cur = cfg;
+  for (let i = 0; i < FLAG_PATH.length - 1; i++) {
+    const seg = FLAG_PATH[i];
+    if (!cur[seg] || typeof cur[seg] !== 'object') cur[seg] = {};
+    cur = cur[seg];
+  }
+  cur[FLAG_PATH[FLAG_PATH.length - 1]] = Boolean(enabled);
+  writeAtomic(join(yeaftDir, CONFIG_FILE), JSON.stringify(cfg, null, 2));
+}

package/unify/groups/group-store.js

@@ -0,0 +1,182 @@
+/**
+ * group-store.js — Per-group persistent store for task-334b.
+ *
+ * Layout (see architecture §2):
+ *   ~/.yeaft/groups/<group-id>/
+ *     group.json          # { id, name, roster: [vpId...], defaultVpId, createdAt }
+ *     messages/           # JSONL size-rotation log (334o openLog)
+ *       000001.jsonl
+ *       index.json
+ *     tasks/              # populated by 334n — reserved here
+ *     vps/                # populated by 334c RoleInstance runtime — reserved here
+ *
+ * This module owns only the group.json + messages/ log. Roster mutation
+ * logic lives in roster.js so coordinator and group-store both compose it.
+ *
+ * Hard constraint: the store does not parse @-mentions, does not dispatch,
+ * and has no knowledge of VP/RoleInstance. It is pure persistence over 334o.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  statSync,
+} from 'fs';
+import { join } from 'path';
+import { writeAtomic, openLog } from '../storage/index.js';
+import { nextMsgId, isReservedVpId, ReservedVpIdError } from './ids.js';
+
+const GROUP_FILE = 'group.json';
+const MESSAGES_DIR = 'messages';
+
+/**
+ * Load (or create) the directory for a single group.
+ *
+ * @param {string} groupsRoot  e.g. `${yeaftDir}/groups`
+ * @param {string} groupId
+ * @returns {GroupHandle}
+ */
+export function openGroup(groupsRoot, groupId) {
+  if (!groupId || typeof groupId !== 'string') {
+    throw new Error('openGroup: groupId required (string)');
+  }
+  const dir = join(groupsRoot, groupId);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  let meta = loadGroupMeta(dir);
+  if (!meta) {
+    // Fresh group — caller must call initGroup() next; we return a handle
+    // with meta=null so createGroup() can write the initial file.
+  }
+
+  const messagesDir = join(dir, MESSAGES_DIR);
+  if (!existsSync(messagesDir)) mkdirSync(messagesDir, { recursive: true });
+  const log = openLog(messagesDir);
+
+  return {
+    dir,
+    id: groupId,
+    /** Return current meta (reads fresh from memory after last save). */
+    getMeta() { return meta ? structuredClone(meta) : null; },
+    /** Overwrite group.json atomically. */
+    saveMeta(next) {
+      validateMeta(next);
+      meta = next;
+      writeAtomic(join(dir, GROUP_FILE), JSON.stringify(meta, null, 2));
+    },
+    /**
+     * Append a message to the group log. Assigns an id if absent.
+     * Returns the stored record (with id + ts).
+     */
+    appendMessage(record) {
+      if (!record || typeof record !== 'object') {
+        throw new Error('appendMessage: record required');
+      }
+      const stored = {
+        id: record.id || nextMsgId(),
+        ts: record.ts || new Date().toISOString(),
+        from: record.from,   // vpId | 'user'
+        role: record.role || (record.from === 'user' ? 'user' : 'assistant'),
+        text: record.text ?? '',
+        taskId: record.taskId || null,
+        mentions: Array.isArray(record.mentions) ? record.mentions.slice() : [],
+        meta: record.meta || {},
+      };
+      log.append(stored);
+      return stored;
+    },
+    /** Iterate all messages oldest→newest. */
+    *streamMessages() {
+      yield* log.streamAll();
+    },
+    /** Iterate a message id range inclusive. */
+    *readMessageRange(firstId, lastId) {
+      yield* log.readRange(firstId, lastId);
+    },
+    /** Flush + close underlying log (on shutdown). */
+    close() { log.close(); },
+  };
+}
+
+/**
+ * Create a fresh group on disk. Fails if group.json already exists.
+ * @returns {GroupHandle}
+ */
+export function createGroup(groupsRoot, spec) {
+  if (!spec || !spec.id) throw new Error('createGroup: spec.id required');
+  const h = openGroup(groupsRoot, spec.id);
+  if (h.getMeta()) {
+    throw new Error(`group ${spec.id} already exists`);
+  }
+  const roster = Array.isArray(spec.roster) ? spec.roster.slice() : [];
+  for (const v of roster) {
+    if (isReservedVpId(v)) throw new ReservedVpIdError(v);
+  }
+  if (spec.defaultVpId && isReservedVpId(spec.defaultVpId)) {
+    throw new ReservedVpIdError(spec.defaultVpId);
+  }
+  const meta = {
+    id: spec.id,
+    name: spec.name || spec.id,
+    roster,
+    defaultVpId: spec.defaultVpId || null,
+    createdAt: spec.createdAt || new Date().toISOString(),
+  };
+  h.saveMeta(meta);
+  return h;
+}
+
+/** Non-destructive load — returns null if group.json is missing/corrupt. */
+export function loadGroupMeta(dir) {
+  const path = join(dir, GROUP_FILE);
+  if (!existsSync(path)) return null;
+  try {
+    const raw = readFileSync(path, 'utf8');
+    const parsed = JSON.parse(raw);
+    validateMeta(parsed);
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/** List every group directory under `groupsRoot`. */
+export function listGroups(groupsRoot) {
+  if (!existsSync(groupsRoot)) return [];
+  const out = [];
+  for (const name of readdirSync(groupsRoot)) {
+    const p = join(groupsRoot, name);
+    try {
+      if (!statSync(p).isDirectory()) continue;
+    } catch { continue; }
+    const meta = loadGroupMeta(p);
+    if (meta) out.push(meta);
+  }
+  return out;
+}
+
+function validateMeta(meta) {
+  if (!meta || typeof meta !== 'object') throw new Error('group.json must be object');
+  if (!meta.id || typeof meta.id !== 'string') throw new Error('group.id required');
+  if (!Array.isArray(meta.roster)) throw new Error('group.roster must be array');
+  for (const v of meta.roster) {
+    if (typeof v !== 'string') throw new Error('group.roster must be string[]');
+  }
+  if (meta.defaultVpId != null && typeof meta.defaultVpId !== 'string') {
+    throw new Error('group.defaultVpId must be string|null');
+  }
+}
+
+/**
+ * @typedef {Object} GroupHandle
+ * @property {string} dir
+ * @property {string} id
+ * @property {() => any} getMeta
+ * @property {(next:any)=>void} saveMeta
+ * @property {(record:any)=>any} appendMessage
+ * @property {() => Generator<any>} streamMessages
+ * @property {(first:string,last:string)=>Generator<any>} readMessageRange
+ * @property {() => void} close
+ */

package/unify/groups/ids.js

@@ -0,0 +1,71 @@
+/**
+ * ids.js — ID generators for the groups slice.
+ *
+ * Per slice-spec §4 (ID format): groupId 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.
+ */
+
+import { randomBytes } from 'crypto';
+
+const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+
+function encode(num, len) {
+  let n = BigInt(num);
+  const out = [];
+  for (let i = 0; i < len; i++) {
+    out.unshift(CROCKFORD[Number(n & 31n)]);
+    n >>= 5n;
+  }
+  return out.join('');
+}
+
+function randEncoded(len) {
+  const bytes = randomBytes(Math.ceil(len * 5 / 8));
+  let n = 0n;
+  for (const b of bytes) n = (n << 8n) | BigInt(b);
+  return encode(n, len);
+}
+
+/** Monotonic ULID-lite (10 time chars + 16 random chars). */
+export function newUlidLite() {
+  const time = encode(Date.now(), 10);
+  return `${time}${randEncoded(16)}`;
+}
+
+export function nextMsgId() {
+  return `msg_${newUlidLite()}`;
+}
+
+export function nextGroupId(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}`;
+}
+
+/**
+ * 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).
+ *
+ * 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
+ * Engine and requiring a migration slice later.
+ */
+export const RESERVED_VP_IDS = Object.freeze(['all', 'user', 'system', 'everyone']);
+
+/** True iff `id` (case-insensitive) is a reserved vp identifier. */
+export function isReservedVpId(id) {
+  if (!id || typeof id !== 'string') return false;
+  return RESERVED_VP_IDS.includes(id.toLowerCase());
+}
+
+/** Thrown by CRUD entry points when a reserved vpId is supplied. */
+export class ReservedVpIdError extends Error {
+  constructor(vpId) {
+    super(`vpId "${vpId}" is reserved (${RESERVED_VP_IDS.join(', ')})`);
+    this.name = 'ReservedVpIdError';
+    this.vpId = vpId;
+  }
+}

package/unify/groups/index.js

@@ -0,0 +1,47 @@
+/**
+ * groups/ — Group Coordinator module (task-334b).
+ *
+ * Layered over 334o storage + 334a VP Registry. Provides:
+ *   - Persistent group directory (group.json + messages/ jsonl-log)
+ *   - Roster mutation helpers
+ *   - Coordinator that parses @-mentions on USER messages and dispatches to
+ *     target RoleInstances via a caller-supplied `deliver(vpId, envelope)`.
+ *   - Feature flag reader for `unify.multiVp.enabled`
+ *   - First-boot default group seeder
+ *
+ * See agent/unify/groups/coordinator.js for the dispatch contract.
+ */
+
+export {
+  openGroup,
+  createGroup,
+  loadGroupMeta,
+  listGroups,
+} from './group-store.js';
+export {
+  addVp,
+  removeVp,
+  setDefaultVp,
+  isMember,
+  resolveFallbackVp,
+} from './roster.js';
+export {
+  createCoordinator,
+  parseMentions,
+} from './coordinator.js';
+export {
+  isMultiVpEnabled,
+  setMultiVpEnabled,
+} from './feature-flag.js';
+export {
+  seedDefaultGroup,
+  DEFAULT_GROUP_ID,
+} from './seed-default.js';
+export {
+  nextMsgId,
+  nextGroupId,
+  newUlidLite,
+  isReservedVpId,
+  RESERVED_VP_IDS,
+  ReservedVpIdError,
+} from './ids.js';

package/unify/groups/roster.js

@@ -0,0 +1,60 @@
+/**
+ * roster.js — Pure roster mutation/query helpers.
+ *
+ * Roster = `string[]` of vpIds. `defaultVpId` is stored alongside on the
+ * group meta; helpers keep both in sync:
+ *   - addVp: appends if absent; preserves order.
+ *   - removeVp: drops and clears defaultVpId if it matched; falls back to
+ *     the first remaining entry by join order (§ D2 Fallback, G2 in arch).
+ *   - setDefaultVp: validates membership; throws on stranger.
+ *
+ * Emits no events directly — callers (group-store/coordinator) persist meta
+ * and optionally notify listeners.
+ */
+
+import { isReservedVpId, ReservedVpIdError } from './ids.js';
+
+/** Returns a cloned roster array with `vpId` appended if not already present. */
+export function addVp(meta, vpId) {
+  if (!vpId || typeof vpId !== 'string') {
+    throw new Error('addVp: vpId required (string)');
+  }
+  if (isReservedVpId(vpId)) {
+    throw new ReservedVpIdError(vpId);
+  }
+  const roster = meta.roster.slice();
+  if (!roster.includes(vpId)) roster.push(vpId);
+  const defaultVpId = meta.defaultVpId || roster[0] || null;
+  return { ...meta, roster, defaultVpId };
+}
+
+/** Remove a vpId. If it was default, pick the next join-order member. */
+export function removeVp(meta, vpId) {
+  const roster = meta.roster.filter((v) => v !== vpId);
+  let defaultVpId = meta.defaultVpId;
+  if (defaultVpId === vpId) {
+    defaultVpId = roster[0] || null;
+  }
+  return { ...meta, roster, defaultVpId };
+}
+
+/** Set default; throws if the vp is not in roster. */
+export function setDefaultVp(meta, vpId) {
+  if (!meta.roster.includes(vpId)) {
+    throw new Error(`setDefaultVp: ${vpId} not in roster`);
+  }
+  return { ...meta, defaultVpId: vpId };
+}
+
+/** True iff vpId is a roster member. */
+export function isMember(meta, vpId) {
+  return meta.roster.includes(vpId);
+}
+
+/**
+ * Resolve which VP should answer a message with no explicit @-mention.
+ * Per architecture G2: defaultVpId if set, else roster[0], else null.
+ */
+export function resolveFallbackVp(meta) {
+  return meta.defaultVpId || meta.roster[0] || null;
+}

package/unify/groups/seed-default.js

@@ -0,0 +1,47 @@
+/**
+ * seed-default.js — First-boot default group (architecture §10 D1).
+ *
+ * When multi-VP mode is first enabled for a user, seed a default group with
+ * the provided roster (typically `[defaultVpId]`). Idempotent: if the group
+ * already exists on disk, returns the existing handle without overwriting.
+ *
+ * Separation from group-store.createGroup:
+ *   - createGroup throws on duplicate; seed returns the existing handle.
+ *   - seed picks a stable id `grp_default` so UI can deep-link to it.
+ *   - seed is the only place that writes the "default group exists" side
+ *     effect during the bootstrap flow.
+ */
+
+import { existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { openGroup, createGroup, loadGroupMeta } from './group-store.js';
+
+export const DEFAULT_GROUP_ID = 'grp_default';
+
+/**
+ * @param {string} yeaftDir
+ * @param {{ defaultVpId?: string|null, roster?: string[], name?: string }} [spec]
+ * @returns {{ group: import('./group-store.js').GroupHandle, created: boolean }}
+ */
+export function seedDefaultGroup(yeaftDir, spec = {}) {
+  const groupsRoot = join(yeaftDir, 'groups');
+  if (!existsSync(groupsRoot)) mkdirSync(groupsRoot, { recursive: true });
+
+  const existingDir = join(groupsRoot, DEFAULT_GROUP_ID);
+  if (existsSync(existingDir) && loadGroupMeta(existingDir)) {
+    return { group: openGroup(groupsRoot, DEFAULT_GROUP_ID), created: false };
+  }
+
+  const roster = Array.isArray(spec.roster) && spec.roster.length
+    ? spec.roster.slice()
+    : (spec.defaultVpId ? [spec.defaultVpId] : []);
+  const defaultVpId = spec.defaultVpId || roster[0] || null;
+
+  const group = createGroup(groupsRoot, {
+    id: DEFAULT_GROUP_ID,
+    name: spec.name || 'Default',
+    roster,
+    defaultVpId,
+  });
+  return { group, created: true };
+}