@hotmeshio/long-tail 0.10.9 → 0.10.11

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/db/schemas/025_ops_home_default.sql

@@ -0,0 +1,11 @@
+-- Migration 025: Home Pace Board default segment
+--
+-- ops_home_default marks the role whose sequence leads the HOME page's Pace
+-- Board. The board's full view lives on /operations; the home embed shows one
+-- segment, and this flag lets an operator pick which one — a subordinate
+-- setting under ops_visible on Role Detail. Single-holder: setting it on one
+-- role clears it everywhere else in the same atomic statement. When no role
+-- carries it, the home board falls back to the primary (first) segment.
+
+ALTER TABLE lt_roles
+  ADD COLUMN IF NOT EXISTS ops_home_default BOOLEAN NOT NULL DEFAULT false;

package/build/modules/features.d.ts

@@ -12,6 +12,15 @@ export interface FeatureFlags {
      * Default: true. Set `features.dbMaintenance: false` in start config to hide it.
      */
     dbMaintenance: boolean;
+    /**
+     * The Pace Board is readable by every authenticated user: station metrics
+     * (aggregate queue-shape counts and trends — never item content) span all
+     * roles for any login, and the board leads everyone's home page. Default:
+     * true. Set `features.publicPaceBoard: false` to scope metrics back to role
+     * membership — the right call for deployments that provision external
+     * one-time accounts (e.g. a customer resolving a single form).
+     */
+    publicPaceBoard: boolean;
 }
 /** Merge a partial set of flags from the start config. Unspecified flags keep their default. */
 export declare function configureFeatureFlags(patch?: Partial<FeatureFlags>): void;

package/build/modules/features.js

@@ -4,6 +4,7 @@ exports.configureFeatureFlags = configureFeatureFlags;
 exports.getFeatureFlags = getFeatureFlags;
 const DEFAULT_FLAGS = {
     dbMaintenance: true,
+    publicPaceBoard: true,
 };
 let flags = { ...DEFAULT_FLAGS };
 /** Merge a partial set of flags from the start config. Unspecified flags keep their default. */

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,

package/build/services/persona/index.d.ts

@@ -0,0 +1,92 @@
+import type { LTPersonaRecord, LTPersonaRelationship, LTPersonaSpec, LTUserPersona, LTComposedRoleScope } from '../../types';
+import type { CreatePersonaInput, UpdatePersonaInput } from './types';
+export { PERSONA_RELATIONSHIPS, normalizeRelationship, relationshipToWriteScope, } from './types';
+export type { CreatePersonaInput, UpdatePersonaInput } from './types';
+/** Counts from one membership reconciliation pass. */
+export interface PersonaRecomputeResult {
+    granted: number;
+    refreshed: number;
+    raised: number;
+    removed: number;
+}
+/** An assignee row on the persona detail surface. */
+export interface PersonaAssignee {
+    id: string;
+    external_id: string;
+    display_name: string | null;
+    email: string | null;
+    assigned_at: Date;
+}
+export declare function listPersonas(): Promise<LTPersonaRecord[]>;
+export declare function getPersona(key: string): Promise<(LTPersonaRecord & {
+    assignees: PersonaAssignee[];
+}) | null>;
+export declare function createPersona(input: CreatePersonaInput): Promise<LTPersonaRecord>;
+export declare function updatePersona(key: string, input: UpdatePersonaInput): Promise<LTPersonaRecord | null>;
+/**
+ * Delete a persona. Holds are removed and memberships reconciled BEFORE the
+ * persona row is deleted, so rows it sustained are dropped (or re-homed to a
+ * sibling persona) rather than silently converting into direct grants.
+ */
+export declare function deletePersona(key: string): Promise<{
+    deleted: boolean;
+    recompute?: PersonaRecomputeResult;
+}>;
+/**
+ * Link a role to a persona (or update the link's relationship). The role is
+ * ensured as an FK target, and every current holder's memberships are
+ * reconciled in the same transaction.
+ */
+export declare function linkPersonaRole(key: string, role: string, relationship: LTPersonaRelationship): Promise<{
+    role: string;
+    relationship: LTPersonaRelationship;
+    recompute: PersonaRecomputeResult;
+} | null>;
+/** Unlink a role from a persona and reconcile every holder's memberships. */
+export declare function unlinkPersonaRole(key: string, role: string): Promise<{
+    unlinked: boolean;
+    personaFound: boolean;
+    recompute?: PersonaRecomputeResult;
+}>;
+/**
+ * Assign a persona to a user. Idempotent: re-assigning overlays fresh — the
+ * user's memberships are reconciled against the persona's CURRENT role links
+ * (union with every other persona they hold; direct grants only ever raised,
+ * never lowered or removed).
+ */
+export declare function assignPersona(userId: string, key: string): Promise<PersonaRecomputeResult | null>;
+/**
+ * Unassign a persona from a user. Removes only memberships the persona
+ * sustains — rows another held persona still grants are re-homed to it, and
+ * direct grants are never touched.
+ */
+export declare function unassignPersona(userId: string, key: string): Promise<{
+    unassigned: boolean;
+    personaFound: boolean;
+    recompute?: PersonaRecomputeResult;
+}>;
+/** The personas a user holds plus the composed role/scope map their memberships form. */
+export declare function getUserPersonas(userId: string): Promise<{
+    personas: LTUserPersona[];
+    roles: LTComposedRoleScope[];
+}>;
+/**
+ * Declarative, idempotent persona seeding — the static-config twin of the API
+ * surface (like roles + default_pins in the same seed pass). Each spec is
+ * authoritative for its persona: title/description overlaid, role links synced
+ * (links absent from the spec are pruned), linked roles ensured as FK targets,
+ * and every holder of a seeded persona reconciled — re-running the seed after
+ * editing a spec re-applies it to everyone holding the persona.
+ *
+ * Relationships must be canonical (normalize aliases at the API boundary).
+ */
+export declare function seedPersonas(specs: (Omit<LTPersonaSpec, 'roles'> & {
+    roles: {
+        role: string;
+        relationship: LTPersonaRelationship;
+    }[];
+})[]): Promise<{
+    personas: number;
+    links: number;
+    recompute: PersonaRecomputeResult;
+}>;

package/build/services/persona/index.js

@@ -0,0 +1,217 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.relationshipToWriteScope = exports.normalizeRelationship = exports.PERSONA_RELATIONSHIPS = void 0;
+exports.listPersonas = listPersonas;
+exports.getPersona = getPersona;
+exports.createPersona = createPersona;
+exports.updatePersona = updatePersona;
+exports.deletePersona = deletePersona;
+exports.linkPersonaRole = linkPersonaRole;
+exports.unlinkPersonaRole = unlinkPersonaRole;
+exports.assignPersona = assignPersona;
+exports.unassignPersona = unassignPersona;
+exports.getUserPersonas = getUserPersonas;
+exports.seedPersonas = seedPersonas;
+const db_1 = require("../../lib/db");
+const sql_1 = require("./sql");
+var types_1 = require("./types");
+Object.defineProperty(exports, "PERSONA_RELATIONSHIPS", { enumerable: true, get: function () { return types_1.PERSONA_RELATIONSHIPS; } });
+Object.defineProperty(exports, "normalizeRelationship", { enumerable: true, get: function () { return types_1.normalizeRelationship; } });
+Object.defineProperty(exports, "relationshipToWriteScope", { enumerable: true, get: function () { return types_1.relationshipToWriteScope; } });
+const EMPTY_RECOMPUTE = { granted: 0, refreshed: 0, raised: 0, removed: 0 };
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+/** Run `work` inside a single transaction on a dedicated client. */
+async function withTransaction(work) {
+    const client = await (0, db_1.getPool)().connect();
+    try {
+        await client.query('BEGIN');
+        const result = await work((text, params) => client.query(text, params));
+        await client.query('COMMIT');
+        return result;
+    }
+    catch (err) {
+        await client.query('ROLLBACK').catch(() => { });
+        throw err;
+    }
+    finally {
+        client.release();
+    }
+}
+/** Reconcile lt_user_roles for a set of users against their held personas. */
+async function recomputeMemberships(query, userIds) {
+    if (userIds.length === 0)
+        return { ...EMPTY_RECOMPUTE };
+    const { rows } = await query(sql_1.RECOMPUTE_PERSONA_MEMBERSHIPS, [userIds]);
+    return rows[0];
+}
+async function resolvePersonaId(query, key) {
+    const { rows } = await query(sql_1.GET_PERSONA_ID_BY_KEY, [key]);
+    return rows[0]?.id ?? null;
+}
+// ─── Persona CRUD ─────────────────────────────────────────────────────────────
+async function listPersonas() {
+    const { rows } = await (0, db_1.getPool)().query(sql_1.LIST_PERSONAS);
+    return rows;
+}
+async function getPersona(key) {
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.GET_PERSONA_BY_KEY, [key]);
+    if (rows.length === 0)
+        return null;
+    const { rows: assignees } = await pool.query(sql_1.GET_PERSONA_ASSIGNEES, [rows[0].id]);
+    return { ...rows[0], assignees };
+}
+async function createPersona(input) {
+    const { rows } = await (0, db_1.getPool)().query(sql_1.CREATE_PERSONA, [
+        input.key,
+        input.title ?? null,
+        input.description ?? null,
+    ]);
+    return { ...rows[0], roles: [], user_count: 0 };
+}
+async function updatePersona(key, input) {
+    const { rows } = await (0, db_1.getPool)().query(sql_1.UPDATE_PERSONA, [
+        key,
+        input.title !== undefined, input.title ?? null,
+        input.description !== undefined, input.description ?? null,
+    ]);
+    if (rows.length === 0)
+        return null;
+    const detail = await getPersona(key);
+    return detail;
+}
+/**
+ * Delete a persona. Holds are removed and memberships reconciled BEFORE the
+ * persona row is deleted, so rows it sustained are dropped (or re-homed to a
+ * sibling persona) rather than silently converting into direct grants.
+ */
+async function deletePersona(key) {
+    return withTransaction(async (query) => {
+        const personaId = await resolvePersonaId(query, key);
+        if (!personaId)
+            return { deleted: false };
+        const { rows: holders } = await query(`DELETE FROM lt_user_personas WHERE persona_id = $1 RETURNING user_id`, [personaId]);
+        // Guard against drift: also reconcile any user with a row still sustained
+        // by this persona, even if no hold record remained.
+        const { rows: sustained } = await query(sql_1.LIST_SUSTAINED_USER_IDS, [personaId]);
+        const affected = [...new Set([...holders, ...sustained].map((r) => r.user_id))];
+        const recompute = await recomputeMemberships(query, affected);
+        await query(sql_1.DELETE_PERSONA, [personaId]);
+        return { deleted: true, recompute };
+    });
+}
+// ─── Role links ───────────────────────────────────────────────────────────────
+/**
+ * Link a role to a persona (or update the link's relationship). The role is
+ * ensured as an FK target, and every current holder's memberships are
+ * reconciled in the same transaction.
+ */
+async function linkPersonaRole(key, role, relationship) {
+    return withTransaction(async (query) => {
+        const personaId = await resolvePersonaId(query, key);
+        if (!personaId)
+            return null;
+        await query(sql_1.ENSURE_ROLES_EXIST, [[role]]);
+        const { rows } = await query(sql_1.UPSERT_PERSONA_ROLE, [personaId, role, relationship]);
+        const { rows: holders } = await query(sql_1.LIST_PERSONA_HOLDER_IDS, [personaId]);
+        const recompute = await recomputeMemberships(query, holders.map((r) => r.user_id));
+        return { ...rows[0], recompute };
+    });
+}
+/** Unlink a role from a persona and reconcile every holder's memberships. */
+async function unlinkPersonaRole(key, role) {
+    return withTransaction(async (query) => {
+        const personaId = await resolvePersonaId(query, key);
+        if (!personaId)
+            return { unlinked: false, personaFound: false };
+        const { rowCount } = await query(sql_1.DELETE_PERSONA_ROLE, [personaId, role]);
+        if ((rowCount ?? 0) === 0)
+            return { unlinked: false, personaFound: true };
+        const { rows: holders } = await query(sql_1.LIST_PERSONA_HOLDER_IDS, [personaId]);
+        const recompute = await recomputeMemberships(query, holders.map((r) => r.user_id));
+        return { unlinked: true, personaFound: true, recompute };
+    });
+}
+// ─── Assignment ───────────────────────────────────────────────────────────────
+/**
+ * Assign a persona to a user. Idempotent: re-assigning overlays fresh — the
+ * user's memberships are reconciled against the persona's CURRENT role links
+ * (union with every other persona they hold; direct grants only ever raised,
+ * never lowered or removed).
+ */
+async function assignPersona(userId, key) {
+    return withTransaction(async (query) => {
+        const personaId = await resolvePersonaId(query, key);
+        if (!personaId)
+            return null;
+        await query(sql_1.INSERT_USER_PERSONA, [userId, personaId]);
+        return recomputeMemberships(query, [userId]);
+    });
+}
+/**
+ * Unassign a persona from a user. Removes only memberships the persona
+ * sustains — rows another held persona still grants are re-homed to it, and
+ * direct grants are never touched.
+ */
+async function unassignPersona(userId, key) {
+    return withTransaction(async (query) => {
+        const personaId = await resolvePersonaId(query, key);
+        if (!personaId)
+            return { unassigned: false, personaFound: false };
+        const { rowCount } = await query(sql_1.DELETE_USER_PERSONA, [userId, personaId]);
+        if ((rowCount ?? 0) === 0)
+            return { unassigned: false, personaFound: true };
+        const recompute = await recomputeMemberships(query, [userId]);
+        return { unassigned: true, personaFound: true, recompute };
+    });
+}
+/** The personas a user holds plus the composed role/scope map their memberships form. */
+async function getUserPersonas(userId) {
+    const pool = (0, db_1.getPool)();
+    const [{ rows: personas }, { rows: roles }] = await Promise.all([
+        pool.query(sql_1.GET_USER_PERSONAS, [userId]),
+        pool.query(sql_1.GET_USER_COMPOSED_ROLES, [userId]),
+    ]);
+    return { personas, roles };
+}
+// ─── Declarative seed ─────────────────────────────────────────────────────────
+/**
+ * Declarative, idempotent persona seeding — the static-config twin of the API
+ * surface (like roles + default_pins in the same seed pass). Each spec is
+ * authoritative for its persona: title/description overlaid, role links synced
+ * (links absent from the spec are pruned), linked roles ensured as FK targets,
+ * and every holder of a seeded persona reconciled — re-running the seed after
+ * editing a spec re-applies it to everyone holding the persona.
+ *
+ * Relationships must be canonical (normalize aliases at the API boundary).
+ */
+async function seedPersonas(specs) {
+    if (specs.length === 0)
+        return { personas: 0, links: 0, recompute: { ...EMPTY_RECOMPUTE } };
+    return withTransaction(async (query) => {
+        const allRoles = [...new Set(specs.flatMap((s) => s.roles.map((r) => r.role)))];
+        if (allRoles.length > 0) {
+            await query(sql_1.ENSURE_ROLES_EXIST, [allRoles]);
+        }
+        const personaIds = [];
+        let links = 0;
+        for (const spec of specs) {
+            const { rows } = await query(sql_1.UPSERT_PERSONA, [
+                spec.key,
+                spec.title ?? null,
+                spec.description ?? null,
+            ]);
+            const personaId = rows[0].id;
+            personaIds.push(personaId);
+            await query(sql_1.SYNC_PERSONA_ROLES, [
+                personaId,
+                spec.roles.map((r) => r.role),
+                spec.roles.map((r) => r.relationship),
+            ]);
+            links += spec.roles.length;
+        }
+        const { rows: holders } = await query('SELECT DISTINCT user_id FROM lt_user_personas WHERE persona_id = ANY($1::uuid[])', [personaIds]);
+        const recompute = await recomputeMemberships(query, holders.map((r) => r.user_id));
+        return { personas: specs.length, links, recompute };
+    });
+}