@hotmeshio/long-tail 0.10.9 → 0.10.10

package/build/services/persona/sql.js

@@ -0,0 +1,158 @@
+"use strict";
+// ─── Persona CRUD ─────────────────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENSURE_ROLES_EXIST = exports.GET_PERSONA_ID_BY_KEY = exports.GET_USER_COMPOSED_ROLES = exports.GET_USER_PERSONAS = exports.RECOMPUTE_PERSONA_MEMBERSHIPS = exports.LIST_SUSTAINED_USER_IDS = exports.LIST_PERSONA_HOLDER_IDS = exports.DELETE_USER_PERSONA = exports.INSERT_USER_PERSONA = exports.SYNC_PERSONA_ROLES = exports.DELETE_PERSONA_ROLE = exports.UPSERT_PERSONA_ROLE = exports.GET_PERSONA_ASSIGNEES = exports.DELETE_PERSONA = exports.UPDATE_PERSONA = exports.UPSERT_PERSONA = exports.CREATE_PERSONA = exports.GET_PERSONA_BY_KEY = exports.LIST_PERSONAS = void 0;
+/** Aggregated role links for one persona, as a JSON array column. */
+const ROLES_LATERAL = `LEFT JOIN LATERAL (
+     SELECT COALESCE(json_agg(json_build_object('role', pr.role, 'relationship', pr.relationship)
+                     ORDER BY pr.created_at, pr.role), '[]'::json) AS roles
+     FROM lt_persona_roles pr WHERE pr.persona_id = p.id
+   ) r ON true
+   LEFT JOIN LATERAL (
+     SELECT COUNT(*)::int AS user_count FROM lt_user_personas up WHERE up.persona_id = p.id
+   ) u ON true`;
+exports.LIST_PERSONAS = `SELECT p.id, p.key, p.title, p.description, r.roles, u.user_count, p.created_at, p.updated_at
+   FROM lt_personas p
+   ${ROLES_LATERAL}
+   ORDER BY p.key`;
+exports.GET_PERSONA_BY_KEY = `SELECT p.id, p.key, p.title, p.description, r.roles, u.user_count, p.created_at, p.updated_at
+   FROM lt_personas p
+   ${ROLES_LATERAL}
+   WHERE p.key = $1`;
+exports.CREATE_PERSONA = `INSERT INTO lt_personas (key, title, description) VALUES ($1, $2, $3)
+   RETURNING id, key, title, description, created_at, updated_at`;
+/** Declarative upsert for the seed pass — the spec is authoritative for title/description. */
+exports.UPSERT_PERSONA = `INSERT INTO lt_personas (key, title, description) VALUES ($1, $2, $3)
+   ON CONFLICT (key) DO UPDATE SET
+     title = EXCLUDED.title,
+     description = EXCLUDED.description,
+     updated_at = NOW()
+   RETURNING id`;
+/** PATCH semantics: $2/$4 are set-sentinels gating whether $3/$5 write. */
+exports.UPDATE_PERSONA = `UPDATE lt_personas SET
+     title       = CASE WHEN $2 THEN $3 ELSE title END,
+     description = CASE WHEN $4 THEN $5 ELSE description END,
+     updated_at  = NOW()
+   WHERE key = $1
+   RETURNING id, key, title, description, created_at, updated_at`;
+exports.DELETE_PERSONA = 'DELETE FROM lt_personas WHERE id = $1';
+exports.GET_PERSONA_ASSIGNEES = `SELECT us.id, us.external_id, us.display_name, us.email, up.created_at AS assigned_at
+   FROM lt_user_personas up
+   JOIN lt_users us ON us.id = up.user_id
+   WHERE up.persona_id = $1
+   ORDER BY up.created_at, us.external_id`;
+// ─── Role links ───────────────────────────────────────────────────────────────
+exports.UPSERT_PERSONA_ROLE = `INSERT INTO lt_persona_roles (persona_id, role, relationship) VALUES ($1, $2, $3)
+   ON CONFLICT (persona_id, role) DO UPDATE SET relationship = EXCLUDED.relationship
+   RETURNING role, relationship`;
+exports.DELETE_PERSONA_ROLE = 'DELETE FROM lt_persona_roles WHERE persona_id = $1 AND role = $2';
+/** Replace a persona's links declaratively: prune links not in $2, upsert the rest. */
+exports.SYNC_PERSONA_ROLES = `WITH incoming AS (
+     SELECT x.role, x.relationship
+     FROM unnest($2::text[], $3::text[]) AS x(role, relationship)
+   ), pruned AS (
+     DELETE FROM lt_persona_roles pr
+     WHERE pr.persona_id = $1 AND pr.role NOT IN (SELECT role FROM incoming)
+   )
+   INSERT INTO lt_persona_roles (persona_id, role, relationship)
+   SELECT $1, role, relationship FROM incoming
+   ON CONFLICT (persona_id, role) DO UPDATE SET relationship = EXCLUDED.relationship`;
+// ─── Assignment ───────────────────────────────────────────────────────────────
+exports.INSERT_USER_PERSONA = `INSERT INTO lt_user_personas (user_id, persona_id) VALUES ($1, $2)
+   ON CONFLICT DO NOTHING`;
+exports.DELETE_USER_PERSONA = 'DELETE FROM lt_user_personas WHERE user_id = $1 AND persona_id = $2';
+exports.LIST_PERSONA_HOLDER_IDS = 'SELECT user_id FROM lt_user_personas WHERE persona_id = $1';
+/** Users with a membership row still sustained by this persona (drift guard for delete). */
+exports.LIST_SUSTAINED_USER_IDS = 'SELECT DISTINCT user_id FROM lt_user_roles WHERE granted_by_persona = $1';
+// ─── Recompute: materialize persona grants into lt_user_roles ────────────────
+//
+// The single reconciliation statement behind assign, unassign, link edits,
+// persona deletion, and seeding. For every user in $1::uuid[], it derives the
+// highest-allowance union of the user's currently-held personas and reconciles
+// lt_user_roles against it:
+//
+//   removed   — persona-sustained rows no held persona still grants
+//   refreshed — persona-sustained rows overlaid fresh (union scope, re-homed
+//               provenance so unassigning one persona never drops a role a
+//               sibling persona still grants)
+//   raised    — DIRECT rows lifted to at least the union (highest allowance
+//               wins); scope is never lowered, type and provenance untouched
+//   granted   — missing rows inserted as scoped members
+//
+// Direct rows (granted_by_persona IS NULL) are never deleted here — persona
+// removal must not touch hand-tuned memberships. Write-rank encoding:
+// write-all=2 (all), write-self=1 (self), read-all=0 (none).
+exports.RECOMPUTE_PERSONA_MEMBERSHIPS = `WITH affected AS (
+     SELECT unnest($1::uuid[]) AS user_id
+   ), grants AS (
+     SELECT up.user_id, pr.role,
+            MAX(CASE pr.relationship WHEN 'write-all' THEN 2 WHEN 'write-self' THEN 1 ELSE 0 END) AS write_rank,
+            (MIN(pr.persona_id::text))::uuid AS sustaining_persona
+     FROM lt_user_personas up
+     JOIN lt_persona_roles pr ON pr.persona_id = up.persona_id
+     JOIN affected a ON a.user_id = up.user_id
+     GROUP BY up.user_id, pr.role
+   ), removed AS (
+     DELETE FROM lt_user_roles ur
+     USING affected a
+     WHERE ur.user_id = a.user_id
+       AND ur.granted_by_persona IS NOT NULL
+       AND NOT EXISTS (SELECT 1 FROM grants g WHERE g.user_id = ur.user_id AND g.role = ur.role)
+     RETURNING ur.user_id, ur.role
+   ), refreshed AS (
+     UPDATE lt_user_roles ur
+     SET read_scope = 'all',
+         write_scope = CASE g.write_rank WHEN 2 THEN 'all' WHEN 1 THEN 'self' ELSE 'none' END,
+         granted_by_persona = g.sustaining_persona
+     FROM grants g
+     WHERE ur.user_id = g.user_id AND ur.role = g.role
+       AND ur.granted_by_persona IS NOT NULL
+     RETURNING ur.user_id, ur.role
+   ), raised AS (
+     UPDATE lt_user_roles ur
+     SET read_scope = 'all',
+         write_scope = CASE
+           WHEN g.write_rank = 2 THEN 'all'
+           WHEN g.write_rank = 1 AND ur.write_scope = 'none' THEN 'self'
+           ELSE ur.write_scope
+         END
+     FROM grants g
+     WHERE ur.user_id = g.user_id AND ur.role = g.role
+       AND ur.granted_by_persona IS NULL
+       AND (ur.read_scope <> 'all'
+            OR g.write_rank > CASE ur.write_scope WHEN 'all' THEN 2 WHEN 'self' THEN 1 ELSE 0 END)
+     RETURNING ur.user_id, ur.role
+   ), granted AS (
+     INSERT INTO lt_user_roles (user_id, role, type, read_scope, write_scope, granted_by_persona)
+     SELECT g.user_id, g.role, 'member', 'all',
+            CASE g.write_rank WHEN 2 THEN 'all' WHEN 1 THEN 'self' ELSE 'none' END,
+            g.sustaining_persona
+     FROM grants g
+     WHERE NOT EXISTS (SELECT 1 FROM lt_user_roles ur WHERE ur.user_id = g.user_id AND ur.role = g.role)
+     RETURNING user_id, role
+   )
+   SELECT
+     (SELECT COUNT(*)::int FROM granted)   AS granted,
+     (SELECT COUNT(*)::int FROM refreshed) AS refreshed,
+     (SELECT COUNT(*)::int FROM raised)    AS raised,
+     (SELECT COUNT(*)::int FROM removed)   AS removed`;
+// ─── forUser ──────────────────────────────────────────────────────────────────
+exports.GET_USER_PERSONAS = `SELECT p.id, p.key, p.title, p.description, r.roles, up.created_at AS assigned_at
+   FROM lt_user_personas up
+   JOIN lt_personas p ON p.id = up.persona_id
+   LEFT JOIN LATERAL (
+     SELECT COALESCE(json_agg(json_build_object('role', pr.role, 'relationship', pr.relationship)
+                     ORDER BY pr.created_at, pr.role), '[]'::json) AS roles
+     FROM lt_persona_roles pr WHERE pr.persona_id = p.id
+   ) r ON true
+   WHERE up.user_id = $1
+   ORDER BY p.key`;
+/** The composed role/scope map: every membership with its sustaining persona key (null = direct). */
+exports.GET_USER_COMPOSED_ROLES = `SELECT ur.role, ur.read_scope, ur.write_scope, p.key AS granted_by_persona
+   FROM lt_user_roles ur
+   LEFT JOIN lt_personas p ON p.id = ur.granted_by_persona
+   WHERE ur.user_id = $1
+   ORDER BY ur.role`;
+// ─── Shared ───────────────────────────────────────────────────────────────────
+exports.GET_PERSONA_ID_BY_KEY = 'SELECT id FROM lt_personas WHERE key = $1';
+exports.ENSURE_ROLES_EXIST = `INSERT INTO lt_roles (role) SELECT DISTINCT unnest($1::text[]) ON CONFLICT DO NOTHING`;

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

@@ -0,0 +1,23 @@
+import type { LTPersonaRelationship, LTWriteScope } from '../../types';
+/**
+ * Canonical relationship values, ordered by allowance (highest first). A
+ * persona grant is always a `member` membership; the relationship selects the
+ * point on the work-surface scope lattice the membership stores.
+ */
+export declare const PERSONA_RELATIONSHIPS: LTPersonaRelationship[];
+/** Normalize an input relationship (canonical or alias) — null if unknown. */
+export declare function normalizeRelationship(value: string): LTPersonaRelationship | null;
+/**
+ * The membership scope a relationship grants. Read is always `all` (an
+ * observer sees the whole pond); write is the axis the relationship selects.
+ */
+export declare function relationshipToWriteScope(relationship: LTPersonaRelationship): LTWriteScope;
+export interface CreatePersonaInput {
+    key: string;
+    title?: string;
+    description?: string;
+}
+export interface UpdatePersonaInput {
+    title?: string | null;
+    description?: string | null;
+}

package/build/services/persona/types.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PERSONA_RELATIONSHIPS = void 0;
+exports.normalizeRelationship = normalizeRelationship;
+exports.relationshipToWriteScope = relationshipToWriteScope;
+/**
+ * Canonical relationship values, ordered by allowance (highest first). A
+ * persona grant is always a `member` membership; the relationship selects the
+ * point on the work-surface scope lattice the membership stores.
+ */
+exports.PERSONA_RELATIONSHIPS = ['write-all', 'write-self', 'read-all'];
+/** Input synonyms accepted at every surface and normalized to canonical values. */
+const RELATIONSHIP_ALIASES = {
+    'write-none': 'read-all',
+};
+/** Normalize an input relationship (canonical or alias) — null if unknown. */
+function normalizeRelationship(value) {
+    if (exports.PERSONA_RELATIONSHIPS.includes(value)) {
+        return value;
+    }
+    return RELATIONSHIP_ALIASES[value] ?? null;
+}
+/**
+ * The membership scope a relationship grants. Read is always `all` (an
+ * observer sees the whole pond); write is the axis the relationship selects.
+ */
+function relationshipToWriteScope(relationship) {
+    switch (relationship) {
+        case 'write-all': return 'all';
+        case 'write-self': return 'self';
+        case 'read-all': return 'none';
+    }
+}

package/build/services/user/sql.d.ts

@@ -1,7 +1,8 @@
 /** Ensure a role name exists in the lt_roles lookup table (FK target). */
 export declare const ENSURE_ROLE_EXISTS = "INSERT INTO lt_roles (role) VALUES ($1) ON CONFLICT DO NOTHING";
-/** Fetch roles for a single user, ordered by creation time. */
-export declare const GET_ROLES_BY_USER_ID = "SELECT role, type, read_scope, write_scope, created_at FROM lt_user_roles WHERE user_id = $1 ORDER BY created_at";
+/** Fetch roles for a single user, ordered by creation time. granted_by_persona
+ *  is the sustaining persona's key (null = direct grant). */
+export declare const GET_ROLES_BY_USER_ID = "SELECT r.role, r.type, r.read_scope, r.write_scope, r.created_at, p.key AS granted_by_persona\n   FROM lt_user_roles r\n   LEFT JOIN lt_personas p ON p.id = r.granted_by_persona\n   WHERE r.user_id = $1 ORDER BY r.created_at";
 /** Fetch a user row by external_id. */
 export declare const GET_USER_BY_EXTERNAL_ID = "SELECT * FROM lt_users WHERE external_id = $1";
 /**
@@ -23,9 +24,11 @@ export declare const VERIFY_USER_BY_ID = "SELECT id FROM lt_users WHERE id = $1
 export declare const GET_USER_WITH_ROLES = "SELECT u.id, u.external_id, u.display_name, u.status, u.metadata,\n          r.role, r.type AS role_type, r.read_scope, r.write_scope\n   FROM lt_users u\n   LEFT JOIN lt_user_roles r ON r.user_id = u.id\n   WHERE u.external_id = $1\n   ORDER BY r.created_at";
 export declare const DELETE_USER_BY_ID = "DELETE FROM lt_users WHERE id = $1";
 /** Batch-load roles for many users (avoids N+1). */
-export declare const GET_ROLES_BY_USER_IDS = "SELECT user_id, role, type, read_scope, write_scope, created_at FROM lt_user_roles WHERE user_id = ANY($1) ORDER BY created_at";
-/** Upsert a user–role assignment, promoting the type/scope if the row exists. */
-export declare const UPSERT_USER_ROLE = "INSERT INTO lt_user_roles (user_id, role, type, read_scope, write_scope) VALUES ($1, $2, $3, $4, $5)\n   ON CONFLICT (user_id, role) DO UPDATE SET\n     type = EXCLUDED.type,\n     read_scope = EXCLUDED.read_scope,\n     write_scope = EXCLUDED.write_scope\n   RETURNING role, type, read_scope, write_scope, created_at";
+export declare const GET_ROLES_BY_USER_IDS = "SELECT r.user_id, r.role, r.type, r.read_scope, r.write_scope, r.created_at, p.key AS granted_by_persona\n   FROM lt_user_roles r\n   LEFT JOIN lt_personas p ON p.id = r.granted_by_persona\n   WHERE r.user_id = ANY($1) ORDER BY r.created_at";
+/** Upsert a user–role assignment, promoting the type/scope if the row exists.
+ *  A direct grant takes the row over: granted_by_persona resets to NULL, so a
+ *  later persona unassign can never remove a membership an admin set by hand. */
+export declare const UPSERT_USER_ROLE = "INSERT INTO lt_user_roles (user_id, role, type, read_scope, write_scope) VALUES ($1, $2, $3, $4, $5)\n   ON CONFLICT (user_id, role) DO UPDATE SET\n     type = EXCLUDED.type,\n     read_scope = EXCLUDED.read_scope,\n     write_scope = EXCLUDED.write_scope,\n     granted_by_persona = NULL\n   RETURNING role, type, read_scope, write_scope, created_at";
 export declare const DELETE_USER_ROLE = "DELETE FROM lt_user_roles WHERE user_id = $1 AND role = $2";
 export declare const HAS_ROLE = "SELECT 1 FROM lt_user_roles WHERE user_id = $1 AND role = $2 LIMIT 1";
 export declare const HAS_ROLE_TYPE = "SELECT 1 FROM lt_user_roles WHERE user_id = $1 AND type = $2 LIMIT 1";

package/build/services/user/sql.js

@@ -4,8 +4,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.IS_GROUP_ADMIN = exports.GET_ROLE_SCOPE = exports.HAS_ROLE_TYPE = exports.HAS_ROLE = exports.DELETE_USER_ROLE = exports.UPSERT_USER_ROLE = exports.GET_ROLES_BY_USER_IDS = exports.DELETE_USER_BY_ID = exports.GET_USER_WITH_ROLES = exports.VERIFY_USER_BY_ID = exports.GET_USER_BY_ID = exports.GET_USER_BY_EMAIL = exports.CREATE_USER_WITH_ROLES = exports.GET_USER_BY_EXTERNAL_ID = exports.GET_ROLES_BY_USER_ID = exports.ENSURE_ROLE_EXISTS = void 0;
 /** Ensure a role name exists in the lt_roles lookup table (FK target). */
 exports.ENSURE_ROLE_EXISTS = 'INSERT INTO lt_roles (role) VALUES ($1) ON CONFLICT DO NOTHING';
-/** Fetch roles for a single user, ordered by creation time. */
-exports.GET_ROLES_BY_USER_ID = 'SELECT role, type, read_scope, write_scope, created_at FROM lt_user_roles WHERE user_id = $1 ORDER BY created_at';
+/** Fetch roles for a single user, ordered by creation time. granted_by_persona
+ *  is the sustaining persona's key (null = direct grant). */
+exports.GET_ROLES_BY_USER_ID = `SELECT r.role, r.type, r.read_scope, r.write_scope, r.created_at, p.key AS granted_by_persona
+   FROM lt_user_roles r
+   LEFT JOIN lt_personas p ON p.id = r.granted_by_persona
+   WHERE r.user_id = $1 ORDER BY r.created_at`;
 /** Fetch a user row by external_id. */
 exports.GET_USER_BY_EXTERNAL_ID = 'SELECT * FROM lt_users WHERE external_id = $1';
 // ─── User CRUD ───────────────────────────────────────────────────────────────
@@ -48,13 +52,19 @@ exports.GET_USER_WITH_ROLES = `SELECT u.id, u.external_id, u.display_name, u.sta
 exports.DELETE_USER_BY_ID = 'DELETE FROM lt_users WHERE id = $1';
 // ─── Role management ─────────────────────────────────────────────────────────
 /** Batch-load roles for many users (avoids N+1). */
-exports.GET_ROLES_BY_USER_IDS = 'SELECT user_id, role, type, read_scope, write_scope, created_at FROM lt_user_roles WHERE user_id = ANY($1) ORDER BY created_at';
-/** Upsert a user–role assignment, promoting the type/scope if the row exists. */
+exports.GET_ROLES_BY_USER_IDS = `SELECT r.user_id, r.role, r.type, r.read_scope, r.write_scope, r.created_at, p.key AS granted_by_persona
+   FROM lt_user_roles r
+   LEFT JOIN lt_personas p ON p.id = r.granted_by_persona
+   WHERE r.user_id = ANY($1) ORDER BY r.created_at`;
+/** Upsert a user–role assignment, promoting the type/scope if the row exists.
+ *  A direct grant takes the row over: granted_by_persona resets to NULL, so a
+ *  later persona unassign can never remove a membership an admin set by hand. */
 exports.UPSERT_USER_ROLE = `INSERT INTO lt_user_roles (user_id, role, type, read_scope, write_scope) VALUES ($1, $2, $3, $4, $5)
    ON CONFLICT (user_id, role) DO UPDATE SET
      type = EXCLUDED.type,
      read_scope = EXCLUDED.read_scope,
-     write_scope = EXCLUDED.write_scope
+     write_scope = EXCLUDED.write_scope,
+     granted_by_persona = NULL
    RETURNING role, type, read_scope, write_scope, created_at`;
 exports.DELETE_USER_ROLE = 'DELETE FROM lt_user_roles WHERE user_id = $1 AND role = $2';
 exports.HAS_ROLE = 'SELECT 1 FROM lt_user_roles WHERE user_id = $1 AND role = $2 LIMIT 1';

package/build/system/mcp-servers/admin/index.d.ts

@@ -11,6 +11,7 @@
  *   mcp-servers.ts         — routes/mcp.ts
  *   yaml-workflows.ts      — routes/yaml-workflows/
  *   users.ts               — routes/users.ts + routes/roles.ts
+ *   personas.ts            — routes/personas.ts + persona sub-routes on routes/users.ts
  *   maintenance.ts         — routes/dba.ts
  *   agents.ts              — routes/agents.ts
  *   agent-subscriptions.ts — routes/agents.ts (subscription sub-routes)

package/build/system/mcp-servers/admin/index.js

@@ -16,6 +16,7 @@ exports.stopAdminServer = stopAdminServer;
  *   mcp-servers.ts         — routes/mcp.ts
  *   yaml-workflows.ts      — routes/yaml-workflows/
  *   users.ts               — routes/users.ts + routes/roles.ts
+ *   personas.ts            — routes/personas.ts + persona sub-routes on routes/users.ts
  *   maintenance.ts         — routes/dba.ts
  *   agents.ts              — routes/agents.ts
  *   agent-subscriptions.ts — routes/agents.ts (subscription sub-routes)
@@ -44,6 +45,7 @@ const workflows_1 = require("./workflows");
 const mcp_servers_1 = require("./mcp-servers");
 const yaml_workflows_1 = require("./yaml-workflows");
 const users_1 = require("./users");
+const personas_1 = require("./personas");
 const maintenance_1 = require("./maintenance");
 const agents_1 = require("./agents");
 const agent_subscriptions_1 = require("./agent-subscriptions");
@@ -56,7 +58,7 @@ const exports_1 = require("./exports");
 const overview_1 = require("./overview");
 const diagnostics_1 = require("./diagnostics");
 const ortho_1 = require("./ortho");
-const TOOL_COUNT = 90;
+const TOOL_COUNT = 100;
 let server = null;
 async function createAdminServer(options) {
     if (server && !options?.fresh)
@@ -73,6 +75,7 @@ async function createAdminServer(options) {
     (0, mcp_servers_1.registerMcpServerTools)(instance); //  4 tools
     (0, yaml_workflows_1.registerYamlWorkflowTools)(instance); //  5 tools
     (0, users_1.registerUserTools)(instance); // 10 tools (users + roles + role schemas)
+    (0, personas_1.registerPersonaTools)(instance); // 10 tools (persona CRUD + links + assignment)
     (0, maintenance_1.registerMaintenanceTools)(instance); //  1 tool
     (0, agents_1.registerAgentTools)(instance); //  5 tools
     (0, agent_subscriptions_1.registerAgentSubscriptionTools)(instance); //  3 tools
@@ -85,7 +88,7 @@ async function createAdminServer(options) {
     (0, overview_1.registerOverviewTools)(instance); //  1 tool
     (0, diagnostics_1.registerDiagnosticsTools)(instance); //  3 tools
     (0, ortho_1.registerOrthoTools)(instance); //  4 tools
-    // Total: 90
+    // Total: 100
     logger_1.loggerRegistry.info(`[lt-mcp:admin] ${name} ready (${TOOL_COUNT} tools registered)`);
     return instance;
 }

package/build/system/mcp-servers/admin/personas.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Persona management tools — mirrors routes/personas.ts plus the persona
+ * sub-routes on routes/users.ts. A persona is a named bundle of roles with a
+ * per-role relationship scope; assigning one fans out to ordinary scoped role
+ * memberships (lt_user_roles stays the single source of authorization truth).
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerPersonaTools(server: McpServer): void;

package/build/system/mcp-servers/admin/personas.js

@@ -0,0 +1,186 @@
+"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 });
+exports.registerPersonaTools = registerPersonaTools;
+const personaService = __importStar(require("../../../services/persona"));
+const schemas_1 = require("./schemas");
+const PERSONA_KEY = /^[a-z][a-z0-9_-]*$/;
+function errorResult(message) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify({ error: message }) }],
+        isError: true,
+    };
+}
+function jsonResult(data) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data) }],
+    };
+}
+function registerPersonaTools(server) {
+    // mirrors GET /api/personas
+    server.registerTool('list_personas', {
+        title: 'List Personas',
+        description: 'List all personas — named role bundles with per-role relationship ' +
+            'scope — with their role links and holder counts.',
+        inputSchema: schemas_1.listPersonasSchema,
+    }, async (_args) => {
+        const personas = await personaService.listPersonas();
+        return jsonResult({ personas });
+    });
+    // mirrors GET /api/personas/:key
+    server.registerTool('get_persona', {
+        title: 'Get Persona',
+        description: 'Fetch one persona with its role links and current assignees.',
+        inputSchema: schemas_1.getPersonaSchema,
+    }, async (args) => {
+        const persona = await personaService.getPersona(args.key);
+        if (!persona)
+            return errorResult(`Persona '${args.key}' not found`);
+        return jsonResult(persona);
+    });
+    // mirrors POST /api/personas
+    server.registerTool('create_persona', {
+        title: 'Create Persona',
+        description: 'Create a persona. Link roles with link_persona_role, then assign ' +
+            'users with assign_persona.',
+        inputSchema: schemas_1.createPersonaSchema,
+    }, async (args) => {
+        const key = args.key.trim().toLowerCase();
+        if (!PERSONA_KEY.test(key)) {
+            return errorResult('key must start with a letter and contain only lowercase letters, numbers, hyphens, and underscores');
+        }
+        const persona = await personaService.createPersona({
+            key,
+            title: args.title,
+            description: args.description,
+        });
+        return jsonResult(persona);
+    });
+    // mirrors PATCH /api/personas/:key
+    server.registerTool('update_persona', {
+        title: 'Update Persona',
+        description: 'Update a persona\'s title/description with PATCH semantics — omitted fields keep their values; null clears.',
+        inputSchema: schemas_1.updatePersonaSchema,
+    }, async (args) => {
+        const persona = await personaService.updatePersona(args.key, {
+            title: args.title,
+            description: args.description,
+        });
+        if (!persona)
+            return errorResult(`Persona '${args.key}' not found`);
+        return jsonResult(persona);
+    });
+    // mirrors DELETE /api/personas/:key
+    server.registerTool('delete_persona', {
+        title: 'Delete Persona',
+        description: 'Delete a persona. Memberships it sustains are removed (or re-homed ' +
+            'to a sibling persona the user still holds); direct grants are never touched.',
+        inputSchema: schemas_1.deletePersonaSchema,
+    }, async (args) => {
+        const result = await personaService.deletePersona(args.key);
+        if (!result.deleted)
+            return errorResult(`Persona '${args.key}' not found`);
+        return jsonResult({ deleted: true, recompute: result.recompute });
+    });
+    // mirrors PUT /api/personas/:key/roles/:role
+    server.registerTool('link_persona_role', {
+        title: 'Link Persona Role',
+        description: 'Link a role to a persona (or change the link\'s relationship). Every ' +
+            'current holder\'s memberships are reconciled in the same transaction.',
+        inputSchema: schemas_1.linkPersonaRoleSchema,
+    }, async (args) => {
+        const relationship = personaService.normalizeRelationship(args.relationship);
+        if (!relationship) {
+            return errorResult('relationship must be write-all, write-self, or read-all (write-none is accepted as read-all)');
+        }
+        const result = await personaService.linkPersonaRole(args.key, args.role.trim().toLowerCase(), relationship);
+        if (!result)
+            return errorResult(`Persona '${args.key}' not found`);
+        return jsonResult(result);
+    });
+    // mirrors DELETE /api/personas/:key/roles/:role
+    server.registerTool('unlink_persona_role', {
+        title: 'Unlink Persona Role',
+        description: 'Remove a role link from a persona and reconcile every holder\'s memberships.',
+        inputSchema: schemas_1.unlinkPersonaRoleSchema,
+    }, async (args) => {
+        const result = await personaService.unlinkPersonaRole(args.key, args.role);
+        if (!result.personaFound)
+            return errorResult(`Persona '${args.key}' not found`);
+        if (!result.unlinked)
+            return errorResult(`Persona '${args.key}' does not link role '${args.role}'`);
+        return jsonResult({ unlinked: true, recompute: result.recompute });
+    });
+    // mirrors POST /api/users/:id/personas
+    server.registerTool('assign_persona', {
+        title: 'Assign Persona',
+        description: 'Assign a persona to a user — shorthand for adding the user to each ' +
+            'linked role at the linked scope. Idempotent: re-assigning overlays ' +
+            'fresh from the persona\'s current links. Highest allowance wins when ' +
+            'bundles overlap; direct grants are only ever raised, never lowered.',
+        inputSchema: schemas_1.assignPersonaSchema,
+    }, async (args) => {
+        const recompute = await personaService.assignPersona(args.user_id, args.key);
+        if (!recompute)
+            return errorResult(`Persona '${args.key}' not found`);
+        return jsonResult({ assigned: true, recompute });
+    });
+    // mirrors DELETE /api/users/:id/personas/:key
+    server.registerTool('unassign_persona', {
+        title: 'Unassign Persona',
+        description: '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.',
+        inputSchema: schemas_1.unassignPersonaSchema,
+    }, async (args) => {
+        const result = await personaService.unassignPersona(args.user_id, args.key);
+        if (!result.personaFound)
+            return errorResult(`Persona '${args.key}' not found`);
+        if (!result.unassigned)
+            return errorResult(`User does not hold persona '${args.key}'`);
+        return jsonResult({ unassigned: true, recompute: result.recompute });
+    });
+    // mirrors GET /api/users/:id/personas
+    server.registerTool('get_user_personas', {
+        title: 'Get User Personas',
+        description: 'The personas a user holds plus the composed role/scope map their ' +
+            'memberships form (each row names the sustaining persona, or null for ' +
+            'a direct grant).',
+        inputSchema: schemas_1.getUserPersonasSchema,
+    }, async (args) => {
+        const result = await personaService.getUserPersonas(args.user_id);
+        return jsonResult(result);
+    });
+}

package/build/system/mcp-servers/admin/schemas.d.ts

@@ -648,6 +648,97 @@ export declare const listRoleSchemaVersionsSchema: z.ZodObject<{
 }, {
     role: string;
 }>;
+export declare const listPersonasSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export declare const getPersonaSchema: z.ZodObject<{
+    key: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    key: string;
+}, {
+    key: string;
+}>;
+export declare const createPersonaSchema: z.ZodObject<{
+    key: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    key: string;
+    description?: string | undefined;
+    title?: string | undefined;
+}, {
+    key: string;
+    description?: string | undefined;
+    title?: string | undefined;
+}>;
+export declare const updatePersonaSchema: z.ZodObject<{
+    key: z.ZodString;
+    title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    key: string;
+    description?: string | null | undefined;
+    title?: string | null | undefined;
+}, {
+    key: string;
+    description?: string | null | undefined;
+    title?: string | null | undefined;
+}>;
+export declare const deletePersonaSchema: z.ZodObject<{
+    key: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    key: string;
+}, {
+    key: string;
+}>;
+export declare const linkPersonaRoleSchema: z.ZodObject<{
+    key: z.ZodString;
+    role: z.ZodString;
+    relationship: z.ZodEnum<["write-all", "write-self", "read-all", "write-none"]>;
+}, "strip", z.ZodTypeAny, {
+    role: string;
+    key: string;
+    relationship: "write-all" | "write-self" | "read-all" | "write-none";
+}, {
+    role: string;
+    key: string;
+    relationship: "write-all" | "write-self" | "read-all" | "write-none";
+}>;
+export declare const unlinkPersonaRoleSchema: z.ZodObject<{
+    key: z.ZodString;
+    role: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    role: string;
+    key: string;
+}, {
+    role: string;
+    key: string;
+}>;
+export declare const assignPersonaSchema: z.ZodObject<{
+    user_id: z.ZodString;
+    key: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    key: string;
+    user_id: string;
+}, {
+    key: string;
+    user_id: string;
+}>;
+export declare const unassignPersonaSchema: z.ZodObject<{
+    user_id: z.ZodString;
+    key: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    key: string;
+    user_id: string;
+}, {
+    key: string;
+    user_id: string;
+}>;
+export declare const getUserPersonasSchema: z.ZodObject<{
+    user_id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    user_id: string;
+}, {
+    user_id: string;
+}>;
 export declare const pruneSchema: z.ZodObject<{
     app_id: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     expire: z.ZodDefault<z.ZodOptional<z.ZodString>>;