@hotmeshio/long-tail 0.10.8 → 0.10.10

package/build/lib/cli/commands/personas.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listPersonas = listPersonas;
+exports.getPersona = getPersona;
+exports.assignPersona = assignPersona;
+exports.unassignPersona = unassignPersona;
+exports.getUserPersonas = getUserPersonas;
+const client_1 = require("../client");
+const format_1 = require("../format");
+const COLUMNS = [
+    { key: 'key', label: 'Key', width: 20 },
+    { key: 'title', label: 'Title', width: 24 },
+    {
+        key: 'roles', label: 'Roles', width: 8,
+        format: (v) => String(Array.isArray(v) ? v.length : 0),
+    },
+    { key: 'user_count', label: 'Users', width: 6, format: (v) => String(v ?? 0) },
+    { key: 'description', label: 'Description', width: 40 },
+];
+async function listPersonas(opts) {
+    const data = await (0, client_1.apiFetch)('/personas');
+    (0, format_1.output)(data, data.personas || [], COLUMNS, opts, 'key');
+}
+async function getPersona(key, opts) {
+    const data = await (0, client_1.apiFetch)(`/personas/${encodeURIComponent(key)}`);
+    console.log(JSON.stringify(data, null, 2));
+}
+async function assignPersona(key, userId, opts) {
+    const data = await (0, client_1.apiFetch)(`/users/${encodeURIComponent(userId)}/personas`, {
+        method: 'POST',
+        body: JSON.stringify({ persona: key }),
+    });
+    console.log(JSON.stringify(data, null, 2));
+}
+async function unassignPersona(key, userId, opts) {
+    const data = await (0, client_1.apiFetch)(`/users/${encodeURIComponent(userId)}/personas/${encodeURIComponent(key)}`, { method: 'DELETE' });
+    console.log(JSON.stringify(data, null, 2));
+}
+async function getUserPersonas(userId, opts) {
+    const data = await (0, client_1.apiFetch)(`/users/${encodeURIComponent(userId)}/personas`);
+    console.log(JSON.stringify(data, null, 2));
+}

package/build/lib/db/schemas/024_personas.sql

@@ -0,0 +1,53 @@
+-- Migration 024: Personas — named role bundles with per-role relationship scope
+--
+-- A persona is a suggestion, the same way a default pin is: shorthand for "add
+-- this user to these roles with these scoped privileges." Assigning a persona
+-- fans out to ordinary lt_user_roles memberships (one per linked role, mapped
+-- from the persona's relationship onto the read/write scope lattice), so
+-- lt_user_roles remains the single source of authorization truth — no second
+-- ACL path, no hot-path changes.
+--
+-- lt_personas          — the bundle: stable key, display title, description.
+-- lt_persona_roles     — the bundle's role links; relationship maps onto the
+--                        membership scope lattice: write-all → (all, all),
+--                        write-self → (all, self), read-all → (all, none).
+-- lt_user_personas     — who holds which persona (the auditable "why").
+-- lt_user_roles.granted_by_persona — provenance: NULL means the membership was
+--                        granted directly; non-NULL names the persona currently
+--                        sustaining the row. Unassigning a persona removes only
+--                        rows it sustains (re-homing rows another held persona
+--                        still grants); direct grants are never touched, and a
+--                        direct grant on a persona-sustained role takes the row
+--                        over (provenance flips to NULL).
+
+CREATE TABLE IF NOT EXISTS lt_personas (
+  id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  key           TEXT NOT NULL UNIQUE,
+  title         TEXT,
+  description   TEXT,
+  created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at    TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE IF NOT EXISTS lt_persona_roles (
+  persona_id    UUID NOT NULL REFERENCES lt_personas(id) ON DELETE CASCADE,
+  role          TEXT NOT NULL REFERENCES lt_roles(role) ON DELETE CASCADE,
+  relationship  TEXT NOT NULL CHECK (relationship IN ('write-all', 'write-self', 'read-all')),
+  created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (persona_id, role)
+);
+
+CREATE TABLE IF NOT EXISTS lt_user_personas (
+  user_id       UUID NOT NULL REFERENCES lt_users(id) ON DELETE CASCADE,
+  persona_id    UUID NOT NULL REFERENCES lt_personas(id) ON DELETE CASCADE,
+  created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (user_id, persona_id)
+);
+
+ALTER TABLE lt_user_roles
+  ADD COLUMN IF NOT EXISTS granted_by_persona UUID REFERENCES lt_personas(id) ON DELETE SET NULL;
+
+CREATE INDEX IF NOT EXISTS idx_lt_persona_roles_role ON lt_persona_roles (role);
+CREATE INDEX IF NOT EXISTS idx_lt_user_personas_persona ON lt_user_personas (persona_id);
+CREATE INDEX IF NOT EXISTS idx_lt_user_roles_granted_by_persona
+  ON lt_user_roles (granted_by_persona) WHERE granted_by_persona IS NOT NULL;

package/build/lib/events/matching.d.ts

@@ -10,4 +10,14 @@
  * - `app.epic.apis.createorder.error` matches `app.epic.>`
  * - `app.epic.apis.createorder.error` does NOT match `app.vendor.>`
  */
+/**
+ * Make a value safe to embed as ONE token of a dot-delimited subject.
+ *
+ * Dots would splinter the token into extra subject levels; `*`, `>`, spaces,
+ * and other non-token characters would corrupt pattern matching (and are
+ * illegal in NATS subjects). Each run of unsafe characters collapses to a
+ * single `-`. An empty or missing value yields `none` so the subject always
+ * keeps its arity.
+ */
+export declare function sanitizeSubjectToken(value: string | null | undefined): string;
 export declare function subjectMatchesPattern(subject: string, pattern: string): boolean;

package/build/lib/events/matching.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeSubjectToken = sanitizeSubjectToken;
 exports.subjectMatchesPattern = subjectMatchesPattern;
 /**
  * Match a dot-delimited subject against a pattern with NATS-style wildcards.
@@ -13,6 +14,19 @@ exports.subjectMatchesPattern = subjectMatchesPattern;
  * - `app.epic.apis.createorder.error` matches `app.epic.>`
  * - `app.epic.apis.createorder.error` does NOT match `app.vendor.>`
  */
+/**
+ * Make a value safe to embed as ONE token of a dot-delimited subject.
+ *
+ * Dots would splinter the token into extra subject levels; `*`, `>`, spaces,
+ * and other non-token characters would corrupt pattern matching (and are
+ * illegal in NATS subjects). Each run of unsafe characters collapses to a
+ * single `-`. An empty or missing value yields `none` so the subject always
+ * keeps its arity.
+ */
+function sanitizeSubjectToken(value) {
+    const cleaned = (value ?? '').replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '');
+    return cleaned || 'none';
+}
 function subjectMatchesPattern(subject, pattern) {
     if (pattern === '*')
         return true;

package/build/lib/events/publish.d.ts

@@ -32,16 +32,22 @@ export declare function publishTaskEvent(params: {
 }): Promise<void>;
 /**
  * Publish an escalation lifecycle event.
- * Subject: system.escalation.{escalationId}.{action}
+ * Subject: system.escalation.{role}.{escalationId}.{action}
+ *
+ * The role token makes the queue the organizing level of the hierarchy:
+ * subscribers scope to one role (`system.escalation.{role}.>`), one verb
+ * across roles (`system.escalation.*.*.created`), or one item regardless of
+ * role hops (`system.escalation.*.{id}.>`).
  */
 export declare function publishEscalationEvent(params: {
-    type: 'escalation.created' | 'escalation.resolved' | 'escalation.claimed' | 'escalation.released' | 'escalation.cancelled';
+    type: 'escalation.created' | 'escalation.resolved' | 'escalation.claimed' | 'escalation.released' | 'escalation.cancelled' | 'escalation.reassigned';
     source: string;
     workflowId: string;
     workflowName: string;
     taskQueue: string;
     taskId?: string;
     escalationId: string;
+    role: string;
     originId?: string;
     status: string;
     data?: Record<string, any>;

package/build/lib/events/publish.js

@@ -9,6 +9,7 @@ exports.publishFileEvent = publishFileEvent;
 exports.publishAgentEvent = publishAgentEvent;
 exports.publishWorkflowEvent = publishWorkflowEvent;
 const index_1 = require("./index");
+const matching_1 = require("./matching");
 const logger_1 = require("../logger");
 /**
  * Fire-and-forget publish helper. Swallows errors (best-effort).
@@ -62,13 +63,19 @@ function publishTaskEvent(params) {
 }
 /**
  * Publish an escalation lifecycle event.
- * Subject: system.escalation.{escalationId}.{action}
+ * Subject: system.escalation.{role}.{escalationId}.{action}
+ *
+ * The role token makes the queue the organizing level of the hierarchy:
+ * subscribers scope to one role (`system.escalation.{role}.>`), one verb
+ * across roles (`system.escalation.*.*.created`), or one item regardless of
+ * role hops (`system.escalation.*.{id}.>`).
  */
 function publishEscalationEvent(params) {
     const action = params.type.split('.')[1];
     return fireAndForget({
-        type: `system.escalation.${params.escalationId}.${action}`,
+        type: `system.escalation.${(0, matching_1.sanitizeSubjectToken)(params.role)}.${params.escalationId}.${action}`,
         source: params.source,
+        role: params.role,
         workflowId: params.workflowId,
         workflowName: params.workflowName,
         taskQueue: params.taskQueue,

package/build/lib/events/socketio.d.ts

@@ -8,8 +8,14 @@ export type SocketIOAuthenticator = (token: string) => boolean | Promise<boolean
 /**
  * Socket.IO event adapter for browser clients.
  *
- * Publishes LTEvent payloads to all connected Socket.IO clients
- * on channels following the pattern: `lt.events.{event.type}`
+ * Publishes LTEvent payloads to connected Socket.IO clients on channels
+ * following the pattern: `lt.events.{event.type}`.
+ *
+ * Delivery is scoped per socket: a client registers NATS-style subject
+ * patterns with `lt.subscribe` / `lt.unsubscribe` messages and receives only
+ * matching events — the server filters, the wire carries only what the page
+ * asked for. A socket that never registers a pattern receives every event
+ * (the broadcast contract external consumers may rely on).
  *
  * The HTTP server must be attached via `attachServer()` before
  * `connect()` is called. The startup flow handles this automatically

package/build/lib/events/socketio.js

@@ -3,11 +3,18 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SocketIOEventAdapter = void 0;
 const socket_io_1 = require("socket.io");
 const logger_1 = require("../logger");
+const matching_1 = require("./matching");
 /**
  * Socket.IO event adapter for browser clients.
  *
- * Publishes LTEvent payloads to all connected Socket.IO clients
- * on channels following the pattern: `lt.events.{event.type}`
+ * Publishes LTEvent payloads to connected Socket.IO clients on channels
+ * following the pattern: `lt.events.{event.type}`.
+ *
+ * Delivery is scoped per socket: a client registers NATS-style subject
+ * patterns with `lt.subscribe` / `lt.unsubscribe` messages and receives only
+ * matching events — the server filters, the wire carries only what the page
+ * asked for. A socket that never registers a pattern receives every event
+ * (the broadcast contract external consumers may rely on).
  *
  * The HTTP server must be attached via `attachServer()` before
  * `connect()` is called. The startup flow handles this automatically
@@ -75,6 +82,19 @@ class SocketIOEventAdapter {
         }
         this.io.on('connection', (socket) => {
             logger_1.loggerRegistry.info(`[lt-events:socketio] client connected (${socket.id})`);
+            // Per-socket subject-pattern scope. Registering the first pattern
+            // switches the socket from broadcast to scoped delivery.
+            const patterns = new Set();
+            socket.data.ltPatterns = patterns;
+            socket.on('lt.subscribe', (pattern) => {
+                if (typeof pattern === 'string' && pattern.length > 0 && pattern.length <= 256) {
+                    patterns.add(pattern);
+                }
+            });
+            socket.on('lt.unsubscribe', (pattern) => {
+                if (typeof pattern === 'string')
+                    patterns.delete(pattern);
+            });
             socket.on('disconnect', () => {
                 logger_1.loggerRegistry.debug(`[lt-events:socketio] client disconnected (${socket.id})`);
             });
@@ -85,7 +105,20 @@ class SocketIOEventAdapter {
         if (!this.io)
             return;
         const channel = `lt.events.${event.type}`;
-        this.io.emit(channel, event);
+        for (const socket of this.io.of('/').sockets.values()) {
+            const patterns = socket.data.ltPatterns;
+            if (!patterns || patterns.size === 0) {
+                // Legacy scope: a socket with no registered patterns gets everything.
+                socket.emit(channel, event);
+                continue;
+            }
+            for (const pattern of patterns) {
+                if ((0, matching_1.subjectMatchesPattern)(channel, pattern)) {
+                    socket.emit(channel, event);
+                    break;
+                }
+            }
+        }
     }
     async disconnect() {
         if (this.io) {

package/build/lib/events/system-events.js

@@ -4,6 +4,7 @@ exports.systemEventsConfig = void 0;
 exports.mapSystemEvent = mapSystemEvent;
 exports.onSystemEvent = onSystemEvent;
 const index_1 = require("./index");
+const matching_1 = require("./matching");
 /** Verb → long-tail event status, matching the manual publishEscalationEvent convention. */
 const ESCALATION_STATUS_BY_VERB = {
     created: 'pending',
@@ -27,9 +28,16 @@ function mapSystemEvent(event) {
     if (domain === 'escalation') {
         const row = (event.data ?? {});
         const verb = segments[3] ?? '';
+        // The SDK forms `system.escalation.{id}.{verb}`; long-tail's canonical
+        // subject carries the role as the organizing token. The committed row
+        // rides in `data`, so the role is lifted from it and the subject is
+        // rewritten to `system.escalation.{role}.{id}.{verb}` — the same shape
+        // publishEscalationEvent produces for the service-mediated path.
+        const role = row.role || undefined;
         return {
-            type: event.type,
+            type: `system.escalation.${(0, matching_1.sanitizeSubjectToken)(role)}.${segments[2]}.${verb}`,
             source: 'sdk',
+            role,
             workflowId: row.workflow_id || event.workflow_id || undefined,
             workflowName: row.workflow_type || undefined,
             taskQueue: row.task_queue || undefined,

package/build/routes/index.js

@@ -16,6 +16,7 @@ const exports_1 = __importDefault(require("./exports"));
 const users_1 = __importDefault(require("./users"));
 const me_1 = __importDefault(require("./me"));
 const roles_1 = __importDefault(require("./roles"));
+const personas_1 = __importDefault(require("./personas"));
 const dba_1 = __importDefault(require("./dba"));
 const maintenance_1 = __importDefault(require("./maintenance"));
 const mcp_1 = __importDefault(require("./mcp"));
@@ -54,6 +55,7 @@ router.use('/config/maintenance', maintenance_1.default);
 router.use('/users', users_1.default);
 router.use('/me', me_1.default);
 router.use('/roles', roles_1.default);
+router.use('/personas', personas_1.default);
 router.use('/dba', dba_1.default);
 router.use('/mcp', mcp_1.default);
 router.use('/insight', insight_1.default);

package/build/routes/personas.d.ts

@@ -0,0 +1,2 @@
+declare const router: import("express-serve-static-core").Router;
+export default router;

package/build/routes/personas.js

@@ -0,0 +1,118 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const express_1 = require("express");
+const auth_1 = require("../modules/auth");
+const api = __importStar(require("../api/personas"));
+const router = (0, express_1.Router)();
+// Personas are role bundles — a management surface. Reads and writes share the
+// role-management gate (admin type, superadmin, engineer), the same audience
+// that manages roles and users.
+router.use(auth_1.requireRoleManager);
+/**
+ * GET /api/personas
+ * List all personas with role links and holder counts.
+ */
+router.get('/', async (_req, res) => {
+    const result = await api.listPersonas();
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
+/**
+ * POST /api/personas
+ * Create a persona.
+ * Body: { key, title?, description? }
+ */
+router.post('/', async (req, res) => {
+    const result = await api.createPersona(req.body || {});
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
+/**
+ * POST /api/personas/seed
+ * Declarative, idempotent seed — upsert personas, sync role links, reconcile holders.
+ * Body: { personas: [{ key, title?, description?, roles: [{ role, relationship }] }] }
+ */
+router.post('/seed', async (req, res) => {
+    const result = await api.seedPersonas(req.body || {});
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
+/**
+ * GET /api/personas/:key
+ * Get one persona with role links and assignees.
+ */
+router.get('/:key', async (req, res) => {
+    const result = await api.getPersona({ key: req.params.key });
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
+/**
+ * PATCH /api/personas/:key
+ * Update title/description (PATCH semantics; null clears).
+ */
+router.patch('/:key', async (req, res) => {
+    const result = await api.updatePersona({ key: req.params.key, ...(req.body || {}) });
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
+/**
+ * DELETE /api/personas/:key
+ * Delete a persona. Sustained memberships are removed or re-homed; direct grants untouched.
+ */
+router.delete('/:key', async (req, res) => {
+    const result = await api.deletePersona({ key: req.params.key });
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
+/**
+ * PUT /api/personas/:key/roles/:role
+ * Link a role (or change its relationship).
+ * Body: { relationship: 'write-all' | 'write-self' | 'read-all' } ('write-none' = read-all)
+ */
+router.put('/:key/roles/:role', async (req, res) => {
+    const result = await api.linkPersonaRole({
+        key: req.params.key,
+        role: req.params.role,
+        relationship: (req.body || {}).relationship,
+    });
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
+/**
+ * DELETE /api/personas/:key/roles/:role
+ * Unlink a role from a persona.
+ */
+router.delete('/:key/roles/:role', async (req, res) => {
+    const result = await api.unlinkPersonaRole({
+        key: req.params.key,
+        role: req.params.role,
+    });
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
+exports.default = router;

package/build/routes/users.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const express_1 = require("express");
 const auth_1 = require("../modules/auth");
 const api = __importStar(require("../api/users"));
+const personasApi = __importStar(require("../api/personas"));
 const router = (0, express_1.Router)();
 // ── User CRUD ─────────────────────────────────────────────────────────────────
 /**
@@ -144,4 +145,38 @@ router.delete('/:id/roles/:role', auth_1.requireAdmin, async (req, res) => {
     const result = await api.removeUserRole({ id: req.params.id, role: req.params.role });
     res.status(result.status).json(result.data ?? { error: result.error });
 });
+// ── Persona assignment ───────────────────────────────────────────────────────
+// A persona assignment is shorthand for scoped role memberships, so the gate is
+// the persona-management gate (admin type, superadmin, engineer).
+/**
+ * GET /api/users/:id/personas
+ * The personas a user holds plus the composed role/scope map.
+ */
+router.get('/:id/personas', async (req, res) => {
+    const result = await personasApi.getUserPersonas({ id: req.params.id });
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
+/**
+ * POST /api/users/:id/personas
+ * Assign a persona to a user (idempotent; re-assigning overlays fresh).
+ * Body: { persona: '<key>' }
+ */
+router.post('/:id/personas', auth_1.requireRoleManager, async (req, res) => {
+    const result = await personasApi.assignPersona({
+        id: req.params.id,
+        key: (req.body || {}).persona,
+    });
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
+/**
+ * DELETE /api/users/:id/personas/:key
+ * Unassign a persona — removes only memberships the persona sustains.
+ */
+router.delete('/:id/personas/:key', auth_1.requireRoleManager, async (req, res) => {
+    const result = await personasApi.unassignPersona({
+        id: req.params.id,
+        key: req.params.key,
+    });
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
 exports.default = router;

package/build/sdk/index.d.ts

@@ -4,6 +4,7 @@ import * as workflowsApi from '../api/workflows';
 import * as yamlWorkflowsApi from '../api/yaml-workflows';
 import * as usersApi from '../api/users';
 import * as rolesApi from '../api/roles';
+import * as personasApi from '../api/personas';
 import * as authApi from '../api/auth';
 import * as mcpApi from '../api/mcp';
 import * as pipelinesApi from '../api/pipelines';
@@ -299,6 +300,20 @@ export declare function createClient(options?: LTClientOptions): {
         getEscalationTargets: typeof rolesApi.getEscalationTargets;
         replaceEscalationTargets: typeof rolesApi.replaceEscalationTargets;
     };
+    personas: {
+        list: typeof personasApi.listPersonas;
+        get: typeof personasApi.getPersona;
+        create: typeof personasApi.createPersona;
+        update: typeof personasApi.updatePersona;
+        delete: typeof personasApi.deletePersona;
+        linkRole: typeof personasApi.linkPersonaRole;
+        unlinkRole: typeof personasApi.unlinkPersonaRole;
+        assign: typeof personasApi.assignPersona;
+        unassign: typeof personasApi.unassignPersona;
+        forUser: typeof personasApi.getUserPersonas;
+        /** Declarative, idempotent seed — the static-config twin of the API surface. */
+        seed: (personas: Parameters<typeof personasApi.seedPersonas>[0]["personas"]) => Promise<LTApiResult<any>>;
+    };
     auth: {
         login: typeof authApi.login;
     };

package/build/sdk/index.js

@@ -42,6 +42,7 @@ const yamlWorkflowsApi = __importStar(require("../api/yaml-workflows"));
 const usersApi = __importStar(require("../api/users"));
 const meApi = __importStar(require("../api/me"));
 const rolesApi = __importStar(require("../api/roles"));
+const personasApi = __importStar(require("../api/personas"));
 const authApi = __importStar(require("../api/auth"));
 const mcpApi = __importStar(require("../api/mcp"));
 const pipelinesApi = __importStar(require("../api/pipelines"));
@@ -217,6 +218,21 @@ function createClient(options = {}) {
             getEscalationTargets: rolesApi.getEscalationTargets,
             replaceEscalationTargets: rolesApi.replaceEscalationTargets,
         },
+        // ── Personas — role bundles with per-role relationship scope ───────────
+        personas: {
+            list: personasApi.listPersonas,
+            get: personasApi.getPersona,
+            create: personasApi.createPersona,
+            update: personasApi.updatePersona,
+            delete: personasApi.deletePersona,
+            linkRole: personasApi.linkPersonaRole,
+            unlinkRole: personasApi.unlinkPersonaRole,
+            assign: personasApi.assignPersona,
+            unassign: personasApi.unassignPersona,
+            forUser: personasApi.getUserPersonas,
+            /** Declarative, idempotent seed — the static-config twin of the API surface. */
+            seed: (personas) => personasApi.seedPersonas({ personas }),
+        },
         // ── Auth ───────────────────────────────────────────────────────────────
         auth: {
             login: authApi.login,