@hotmeshio/long-tail 0.10.1 → 0.10.2

package/build/api/me.d.ts

@@ -0,0 +1,16 @@
+import type { LTApiResult, LTApiAuth } from '../types/sdk';
+/**
+ * The caller's preferences document — a generic per-user JSON store for
+ * presentation state (pinned views are the first tenant). Always an object;
+ * an unset store reads as {}.
+ */
+export declare function getMyPreferences(auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Shallow-merge a patch into the caller's preferences. Top-level keys
+ * overwrite; a `null` value deletes its key. The patch and the merged
+ * document are both size-capped; the merge itself is a single guarded
+ * UPDATE (no read-then-write).
+ */
+export declare function patchMyPreferences(input: {
+    patch: unknown;
+}, auth: LTApiAuth): Promise<LTApiResult>;

package/build/api/me.js

@@ -0,0 +1,79 @@
+"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.getMyPreferences = getMyPreferences;
+exports.patchMyPreferences = patchMyPreferences;
+const userService = __importStar(require("../services/user"));
+// ── Self-service surface (/api/me) ─────────────────────────────────────────
+// Operations on the AUTHENTICATED user only — no ids, no admin gates.
+/**
+ * The caller's preferences document — a generic per-user JSON store for
+ * presentation state (pinned views are the first tenant). Always an object;
+ * an unset store reads as {}.
+ */
+async function getMyPreferences(auth) {
+    try {
+        const preferences = await userService.getPreferences(auth.userId);
+        return { status: 200, data: { preferences } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Shallow-merge a patch into the caller's preferences. Top-level keys
+ * overwrite; a `null` value deletes its key. The patch and the merged
+ * document are both size-capped; the merge itself is a single guarded
+ * UPDATE (no read-then-write).
+ */
+async function patchMyPreferences(input, auth) {
+    try {
+        const { patch } = input;
+        if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {
+            return { status: 400, error: 'Body must be a JSON object of preference keys' };
+        }
+        if (JSON.stringify(patch).length > userService.PREFERENCES_MAX_BYTES) {
+            return { status: 413, error: `Preferences patch exceeds ${userService.PREFERENCES_MAX_BYTES} bytes` };
+        }
+        const preferences = await userService.patchPreferences(auth.userId, patch);
+        if (preferences === null) {
+            return { status: 413, error: `Merged preferences would exceed ${userService.PREFERENCES_MAX_BYTES} bytes` };
+        }
+        return { status: 200, data: { preferences } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}

package/build/api/roles.d.ts

@@ -88,6 +88,12 @@ export declare function updateRole(input: {
     metadata_schema?: Record<string, any> | null;
     /** The escalation LIST schema — rich formatting for this role's list page. */
     list_schema?: Record<string, any> | null;
+    /** Pinned-view seeds for the role's members: [{ label, url, badge? }] or null to clear. */
+    default_pins?: {
+        label: string;
+        url: string;
+        badge?: boolean;
+    }[] | null;
     properties?: Record<string, any> | null;
     ops_visible?: boolean;
     parent_role?: string | null;

package/build/api/roles.js

@@ -228,6 +228,15 @@ async function updateRole(input) {
         if (input.parent_role != null && input.parent_role === input.role) {
             return { status: 400, error: 'parent_role must reference a different role' };
         }
+        if (input.default_pins != null) {
+            const pinsValid = Array.isArray(input.default_pins) && input.default_pins.every((p) => p && typeof p === 'object'
+                && typeof p.label === 'string' && p.label.trim() !== ''
+                && typeof p.url === 'string' && p.url.startsWith('/')
+                && (p.badge === undefined || typeof p.badge === 'boolean'));
+            if (!pinsValid) {
+                return { status: 400, error: 'default_pins must be [{ label, url, badge? }] with dashboard-relative urls' };
+            }
+        }
         if (input.upstream_roles != null) {
             if (!Array.isArray(input.upstream_roles) || input.upstream_roles.some((u) => typeof u !== 'string' || !u.trim())) {
                 return { status: 400, error: 'upstream_roles must be an array of role names' };
@@ -247,6 +256,7 @@ async function updateRole(input) {
             form_schema: input.form_schema,
             metadata_schema: input.metadata_schema,
             list_schema: input.list_schema,
+            default_pins: input.default_pins,
             properties: input.properties,
             ops_visible: input.ops_visible,
             parent_role: input.parent_role,

package/build/lib/db/schemas/022_user_preferences.sql

@@ -0,0 +1,18 @@
+-- Migration 022: Per-user preferences + role default pins
+--
+-- lt_users.preferences is a generic per-user JSON store (pinned views are the
+-- first tenant, not the schema): read via GET /api/me/preferences, written via
+-- PATCH with shallow top-level merge (null deletes a key), size-capped at the
+-- API layer. Preferences carry presentation state only — never data and never
+-- authorization; read-scope enforcement stays with the queries a preference
+-- may point at.
+--
+-- lt_roles.default_pins seeds a role's members with the persona's starting
+-- pinned views ([{ label, url, badge? }]). Users promote, hide, or reorder
+-- them through their own preferences.
+
+ALTER TABLE lt_users
+  ADD COLUMN IF NOT EXISTS preferences JSONB;
+
+ALTER TABLE lt_roles
+  ADD COLUMN IF NOT EXISTS default_pins JSONB;

package/build/routes/index.js

@@ -14,6 +14,7 @@ const escalations_1 = __importDefault(require("./escalations"));
 const workflows_1 = __importDefault(require("./workflows"));
 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 dba_1 = __importDefault(require("./dba"));
 const maintenance_1 = __importDefault(require("./maintenance"));
@@ -51,6 +52,7 @@ router.use('/workflows', workflows_1.default);
 router.use('/workflow-states', exports_1.default);
 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('/dba', dba_1.default);
 router.use('/mcp', mcp_1.default);

package/build/routes/me.d.ts

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

package/build/routes/me.js

@@ -0,0 +1,57 @@
+"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 api = __importStar(require("../api/me"));
+const router = (0, express_1.Router)();
+// ── Self-service (/api/me) — the authenticated user, no admin gates ─────────
+/**
+ * GET /api/me/preferences
+ * The caller's preferences document ({} when unset).
+ */
+router.get('/preferences', async (req, res) => {
+    const result = await api.getMyPreferences(req.auth);
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
+/**
+ * PATCH /api/me/preferences
+ * Shallow-merge the body into the caller's preferences; null deletes a key.
+ * Returns the merged document. 413 when the result would exceed the cap.
+ */
+router.patch('/preferences', async (req, res) => {
+    const result = await api.patchMyPreferences({ patch: req.body }, req.auth);
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
+exports.default = router;

package/build/sdk/index.d.ts

@@ -275,6 +275,12 @@ export declare function createClient(options?: LTClientOptions): {
         addRole: typeof usersApi.addUserRole;
         removeRole: typeof usersApi.removeUserRole;
     };
+    me: {
+        getPreferences: (callAuth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        patchPreferences: (input: {
+            patch: unknown;
+        }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+    };
     roles: {
         list: typeof rolesApi.listRoles;
         listWithDetails: typeof rolesApi.listRolesWithDetails;

package/build/sdk/index.js

@@ -39,6 +39,7 @@ const escalationsApi = __importStar(require("../api/escalations"));
 const workflowsApi = __importStar(require("../api/workflows"));
 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 authApi = __importStar(require("../api/auth"));
 const mcpApi = __importStar(require("../api/mcp"));
@@ -190,6 +191,16 @@ function createClient(options = {}) {
             addRole: usersApi.addUserRole,
             removeRole: usersApi.removeUserRole,
         },
+        // ── Me — the authenticated caller (preferences, presentation state) ────
+        me: {
+            getPreferences: (callAuth) => {
+                const resolved = callAuth ?? auth;
+                if (!resolved)
+                    return Promise.resolve({ status: 401, error: 'Auth context required' });
+                return meApi.getMyPreferences(resolved);
+            },
+            patchPreferences: bindAuth(meApi.patchMyPreferences, auth),
+        },
         // ── Roles ──────────────────────────────────────────────────────────────
         roles: {
             list: rolesApi.listRoles,

package/build/services/role/index.js

@@ -146,6 +146,7 @@ async function updateRoleMetadata(role, input) {
         input.change_summary ?? null,
         provided('upstream_roles'), upstreams,
         provided('list_schema'), input.list_schema != null ? JSON.stringify(input.list_schema) : null,
+        provided('default_pins'), input.default_pins != null ? JSON.stringify(input.default_pins) : null,
     ]);
     if (!rows[0])
         return null;

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

@@ -39,8 +39,11 @@ export declare const DELETE_ROLE = "\n  DELETE FROM lt_roles WHERE role = $1";
  * of the form/metadata pair: its own current_list_schema_version and its own
  * snapshot table (lt_role_list_schemas), so a list-view edit never advances the
  * resolve form's version. It shares $26 as the change summary.
+ *
+ * default_pins ($31 = provided sentinel, $32 = value) is unversioned config:
+ * the pinned-view seeds a role hands its members.
  */
-export declare const UPDATE_ROLE_METADATA = "\n  WITH updated AS (\n    UPDATE lt_roles SET\n      title           = CASE WHEN $2::boolean  THEN $3                                ELSE title           END,\n      description     = CASE WHEN $4::boolean  THEN $5                                ELSE description     END,\n      form_schema     = CASE WHEN $6::boolean  THEN $7::jsonb                         ELSE form_schema     END,\n      metadata_schema = CASE WHEN $8::boolean  THEN $9::jsonb                         ELSE metadata_schema END,\n      properties      = CASE WHEN $10::boolean THEN COALESCE($11::jsonb, '{}'::jsonb) ELSE properties      END,\n      ops_visible     = CASE WHEN $12::boolean THEN $13::boolean                      ELSE ops_visible     END,\n      parent_role     = CASE WHEN $14::boolean THEN $15                               ELSE parent_role     END,\n      sla_minutes     = CASE WHEN $16::boolean THEN $17::numeric                      ELSE sla_minutes     END,\n      target_per_hour = CASE WHEN $18::boolean THEN $19::numeric                      ELSE target_per_hour END,\n      worker_count    = CASE WHEN $20::boolean THEN $21::int                          ELSE worker_count    END,\n      priority_threshold_minutes\n                      = CASE WHEN $22::boolean THEN $23::numeric                      ELSE priority_threshold_minutes END,\n      priority_facet  = CASE WHEN $24::boolean THEN $25                               ELSE priority_facet  END,\n      list_schema     = CASE WHEN $29::boolean THEN $30::jsonb                        ELSE list_schema     END,\n      current_schema_version = CASE\n        WHEN ($6::boolean AND $7::jsonb IS DISTINCT FROM form_schema)\n          OR ($8::boolean AND $9::jsonb IS DISTINCT FROM metadata_schema)\n        THEN COALESCE(current_schema_version, 0) + 1\n        ELSE current_schema_version END,\n      current_list_schema_version = CASE\n        WHEN $29::boolean AND $30::jsonb IS DISTINCT FROM list_schema\n        THEN COALESCE(current_list_schema_version, 0) + 1\n        ELSE current_list_schema_version END\n    WHERE role = $1\n    RETURNING\n      role, title, description, form_schema, metadata_schema, properties,\n      ops_visible, parent_role, sla_minutes, target_per_hour, worker_count,\n      priority_threshold_minutes, priority_facet,\n      current_schema_version, list_schema, current_list_schema_version\n  ), snapshot AS (\n    INSERT INTO lt_role_schemas (role, version, form_schema, metadata_schema, change_summary)\n    SELECT role, current_schema_version, form_schema, metadata_schema, $26\n    FROM updated\n    WHERE ($6::boolean OR $8::boolean) AND current_schema_version IS NOT NULL\n    ON CONFLICT (role, version) DO NOTHING\n  ), list_snapshot AS (\n    INSERT INTO lt_role_list_schemas (role, version, list_schema, change_summary)\n    SELECT role, current_list_schema_version, list_schema, $26\n    FROM updated\n    WHERE $29::boolean AND current_list_schema_version IS NOT NULL\n    ON CONFLICT (role, version) DO NOTHING\n  ), upstream_prune AS (\n    DELETE FROM lt_role_upstreams\n    WHERE $27::boolean AND role = $1 AND upstream_role <> ALL($28::text[])\n  ), upstream_add AS (\n    INSERT INTO lt_role_upstreams (role, upstream_role)\n    SELECT $1, u FROM unnest($28::text[]) AS u\n    WHERE $27::boolean\n    ON CONFLICT DO NOTHING\n  )\n  SELECT * FROM updated";
+export declare const UPDATE_ROLE_METADATA = "\n  WITH updated AS (\n    UPDATE lt_roles SET\n      title           = CASE WHEN $2::boolean  THEN $3                                ELSE title           END,\n      description     = CASE WHEN $4::boolean  THEN $5                                ELSE description     END,\n      form_schema     = CASE WHEN $6::boolean  THEN $7::jsonb                         ELSE form_schema     END,\n      metadata_schema = CASE WHEN $8::boolean  THEN $9::jsonb                         ELSE metadata_schema END,\n      properties      = CASE WHEN $10::boolean THEN COALESCE($11::jsonb, '{}'::jsonb) ELSE properties      END,\n      ops_visible     = CASE WHEN $12::boolean THEN $13::boolean                      ELSE ops_visible     END,\n      parent_role     = CASE WHEN $14::boolean THEN $15                               ELSE parent_role     END,\n      sla_minutes     = CASE WHEN $16::boolean THEN $17::numeric                      ELSE sla_minutes     END,\n      target_per_hour = CASE WHEN $18::boolean THEN $19::numeric                      ELSE target_per_hour END,\n      worker_count    = CASE WHEN $20::boolean THEN $21::int                          ELSE worker_count    END,\n      priority_threshold_minutes\n                      = CASE WHEN $22::boolean THEN $23::numeric                      ELSE priority_threshold_minutes END,\n      priority_facet  = CASE WHEN $24::boolean THEN $25                               ELSE priority_facet  END,\n      list_schema     = CASE WHEN $29::boolean THEN $30::jsonb                        ELSE list_schema     END,\n      default_pins    = CASE WHEN $31::boolean THEN $32::jsonb                        ELSE default_pins    END,\n      current_schema_version = CASE\n        WHEN ($6::boolean AND $7::jsonb IS DISTINCT FROM form_schema)\n          OR ($8::boolean AND $9::jsonb IS DISTINCT FROM metadata_schema)\n        THEN COALESCE(current_schema_version, 0) + 1\n        ELSE current_schema_version END,\n      current_list_schema_version = CASE\n        WHEN $29::boolean AND $30::jsonb IS DISTINCT FROM list_schema\n        THEN COALESCE(current_list_schema_version, 0) + 1\n        ELSE current_list_schema_version END\n    WHERE role = $1\n    RETURNING\n      role, title, description, form_schema, metadata_schema, properties,\n      ops_visible, parent_role, sla_minutes, target_per_hour, worker_count,\n      priority_threshold_minutes, priority_facet,\n      current_schema_version, list_schema, current_list_schema_version,\n      default_pins\n  ), snapshot AS (\n    INSERT INTO lt_role_schemas (role, version, form_schema, metadata_schema, change_summary)\n    SELECT role, current_schema_version, form_schema, metadata_schema, $26\n    FROM updated\n    WHERE ($6::boolean OR $8::boolean) AND current_schema_version IS NOT NULL\n    ON CONFLICT (role, version) DO NOTHING\n  ), list_snapshot AS (\n    INSERT INTO lt_role_list_schemas (role, version, list_schema, change_summary)\n    SELECT role, current_list_schema_version, list_schema, $26\n    FROM updated\n    WHERE $29::boolean AND current_list_schema_version IS NOT NULL\n    ON CONFLICT (role, version) DO NOTHING\n  ), upstream_prune AS (\n    DELETE FROM lt_role_upstreams\n    WHERE $27::boolean AND role = $1 AND upstream_role <> ALL($28::text[])\n  ), upstream_add AS (\n    INSERT INTO lt_role_upstreams (role, upstream_role)\n    SELECT $1, u FROM unnest($28::text[]) AS u\n    WHERE $27::boolean\n    ON CONFLICT DO NOTHING\n  )\n  SELECT * FROM updated";
 export declare const GET_ROLE_FORM_SCHEMA = "\n  SELECT form_schema FROM lt_roles WHERE role = $1";
 export declare const GET_ROLE_METADATA_SCHEMA = "\n  SELECT metadata_schema FROM lt_roles WHERE role = $1";
 export declare const GET_ROLE_UPSTREAMS = "\n  SELECT upstream_role FROM lt_role_upstreams WHERE role = $1 ORDER BY upstream_role";
@@ -58,7 +61,7 @@ export declare const GET_ROLE_LIST_SCHEMA_VERSION = "\n  SELECT s.role, s.versio
  * never versioned its list schema still answers, with version NULL).
  */
 export declare const GET_ROLE_LIST_SCHEMA_CURRENT = "\n  SELECT r.role, r.current_list_schema_version AS version, r.list_schema,\n         s.change_summary, s.created_at,\n         r.current_list_schema_version AS latest_version\n  FROM lt_roles r\n  LEFT JOIN lt_role_list_schemas s\n    ON s.role = r.role AND s.version = r.current_list_schema_version\n  WHERE r.role = $1";
-export declare const LIST_ROLES_WITH_DETAILS = "\n  WITH\n  user_counts AS (\n    SELECT role, COUNT(DISTINCT user_id)::int AS cnt\n    FROM lt_user_roles\n    GROUP BY role\n  ),\n  chain_counts AS (\n    SELECT role, COUNT(*)::int AS cnt\n    FROM (\n      SELECT source_role AS role FROM lt_config_role_escalations\n      UNION ALL\n      SELECT target_role AS role FROM lt_config_role_escalations\n    ) c\n    GROUP BY role\n  ),\n  workflow_counts AS (\n    SELECT role, COUNT(*)::int AS cnt\n    FROM lt_config_roles\n    GROUP BY role\n  ),\n  upstreams AS (\n    SELECT role, array_agg(upstream_role ORDER BY upstream_role) AS ups\n    FROM lt_role_upstreams\n    GROUP BY role\n  )\n  SELECT\n    r.role,\n    r.title,\n    r.description,\n    r.form_schema,\n    r.metadata_schema,\n    r.properties,\n    r.ops_visible,\n    r.parent_role,\n    r.sla_minutes,\n    r.target_per_hour,\n    r.worker_count,\n    r.priority_threshold_minutes,\n    r.priority_facet,\n    r.current_schema_version,\n    r.list_schema,\n    r.current_list_schema_version,\n    COALESCE(up.ups, '{}') AS upstream_roles,\n    COALESCE(uc.cnt, 0) AS user_count,\n    COALESCE(cc.cnt, 0) AS chain_count,\n    COALESCE(wc.cnt, 0) AS workflow_count\n  FROM lt_roles r\n  LEFT JOIN user_counts uc ON uc.role = r.role\n  LEFT JOIN chain_counts cc ON cc.role = r.role\n  LEFT JOIN workflow_counts wc ON wc.role = r.role\n  LEFT JOIN upstreams up ON up.role = r.role\n  ORDER BY r.role";
+export declare const LIST_ROLES_WITH_DETAILS = "\n  WITH\n  user_counts AS (\n    SELECT role, COUNT(DISTINCT user_id)::int AS cnt\n    FROM lt_user_roles\n    GROUP BY role\n  ),\n  chain_counts AS (\n    SELECT role, COUNT(*)::int AS cnt\n    FROM (\n      SELECT source_role AS role FROM lt_config_role_escalations\n      UNION ALL\n      SELECT target_role AS role FROM lt_config_role_escalations\n    ) c\n    GROUP BY role\n  ),\n  workflow_counts AS (\n    SELECT role, COUNT(*)::int AS cnt\n    FROM lt_config_roles\n    GROUP BY role\n  ),\n  upstreams AS (\n    SELECT role, array_agg(upstream_role ORDER BY upstream_role) AS ups\n    FROM lt_role_upstreams\n    GROUP BY role\n  )\n  SELECT\n    r.role,\n    r.title,\n    r.description,\n    r.form_schema,\n    r.metadata_schema,\n    r.properties,\n    r.ops_visible,\n    r.parent_role,\n    r.sla_minutes,\n    r.target_per_hour,\n    r.worker_count,\n    r.priority_threshold_minutes,\n    r.priority_facet,\n    r.current_schema_version,\n    r.list_schema,\n    r.current_list_schema_version,\n    r.default_pins,\n    COALESCE(up.ups, '{}') AS upstream_roles,\n    COALESCE(uc.cnt, 0) AS user_count,\n    COALESCE(cc.cnt, 0) AS chain_count,\n    COALESCE(wc.cnt, 0) AS workflow_count\n  FROM lt_roles r\n  LEFT JOIN user_counts uc ON uc.role = r.role\n  LEFT JOIN chain_counts cc ON cc.role = r.role\n  LEFT JOIN workflow_counts wc ON wc.role = r.role\n  LEFT JOIN upstreams up ON up.role = r.role\n  ORDER BY r.role";
 export declare const COUNT_USER_ROLE_REFS = "\n  SELECT COUNT(*)::int AS cnt FROM lt_user_roles WHERE role = $1";
 export declare const COUNT_CHAIN_REFS = "\n  SELECT COUNT(*)::int AS cnt\n  FROM lt_config_role_escalations\n  WHERE source_role = $1 OR target_role = $1";
 export declare const COUNT_WORKFLOW_REFS = "\n  SELECT COUNT(*)::int AS cnt FROM lt_config_roles WHERE role = $1";

package/build/services/role/sql.js

@@ -73,6 +73,9 @@ exports.DELETE_ROLE = `
  * of the form/metadata pair: its own current_list_schema_version and its own
  * snapshot table (lt_role_list_schemas), so a list-view edit never advances the
  * resolve form's version. It shares $26 as the change summary.
+ *
+ * default_pins ($31 = provided sentinel, $32 = value) is unversioned config:
+ * the pinned-view seeds a role hands its members.
  */
 exports.UPDATE_ROLE_METADATA = `
   WITH updated AS (
@@ -91,6 +94,7 @@ exports.UPDATE_ROLE_METADATA = `
                       = CASE WHEN $22::boolean THEN $23::numeric                      ELSE priority_threshold_minutes END,
       priority_facet  = CASE WHEN $24::boolean THEN $25                               ELSE priority_facet  END,
       list_schema     = CASE WHEN $29::boolean THEN $30::jsonb                        ELSE list_schema     END,
+      default_pins    = CASE WHEN $31::boolean THEN $32::jsonb                        ELSE default_pins    END,
       current_schema_version = CASE
         WHEN ($6::boolean AND $7::jsonb IS DISTINCT FROM form_schema)
           OR ($8::boolean AND $9::jsonb IS DISTINCT FROM metadata_schema)
@@ -105,7 +109,8 @@ exports.UPDATE_ROLE_METADATA = `
       role, title, description, form_schema, metadata_schema, properties,
       ops_visible, parent_role, sla_minutes, target_per_hour, worker_count,
       priority_threshold_minutes, priority_facet,
-      current_schema_version, list_schema, current_list_schema_version
+      current_schema_version, list_schema, current_list_schema_version,
+      default_pins
   ), snapshot AS (
     INSERT INTO lt_role_schemas (role, version, form_schema, metadata_schema, change_summary)
     SELECT role, current_schema_version, form_schema, metadata_schema, $26
@@ -239,6 +244,7 @@ exports.LIST_ROLES_WITH_DETAILS = `
     r.current_schema_version,
     r.list_schema,
     r.current_list_schema_version,
+    r.default_pins,
     COALESCE(up.ups, '{}') AS upstream_roles,
     COALESCE(uc.cnt, 0) AS user_count,
     COALESCE(cc.cnt, 0) AS chain_count,

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

@@ -54,6 +54,17 @@ export interface RoleDetail {
     list_schema: Record<string, any> | null;
     /** Version of the live list_schema; null until the role first carries one. */
     current_list_schema_version: number | null;
+    /**
+     * Pinned-view seeds this role hands its members: [{ label, url, badge? }].
+     * On first render, a member without an own pin of the same label sees these
+     * in their Pinned nav section (marked role-provided); users promote, hide,
+     * or reorder them through their own preferences. URLs only — never data.
+     */
+    default_pins: {
+        label: string;
+        url: string;
+        badge?: boolean;
+    }[] | null;
     /**
      * Roles this station draws input from that live in OTHER sequences.
      * parent_role is the single "prior step" placing the role in one sequence;
@@ -109,6 +120,11 @@ export interface UpdateRoleInput {
     metadata_schema?: Record<string, any> | null;
     /** JSON contract that richly formats this role's escalation list page. */
     list_schema?: Record<string, any> | null;
+    default_pins?: {
+        label: string;
+        url: string;
+        badge?: boolean;
+    }[] | null;
     properties?: Record<string, any> | null;
     ops_visible?: boolean;
     parent_role?: string | null;

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

@@ -5,3 +5,4 @@ export { isSuperAdmin, isGroupAdmin, canManageRole, hasGlobalEscalationAccess, h
 export { READ_SCOPES, WRITE_SCOPES, DEFAULT_READ_SCOPE, DEFAULT_WRITE_SCOPE, isValidReadScope, isValidWriteScope, isValidScopePair, effectiveScope, } from './scope';
 export { verifyPassword } from './auth';
 export { seedAdmin } from './seed-admin';
+export { getPreferences, patchPreferences, PREFERENCES_MAX_BYTES } from './preferences';

package/build/services/user/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.seedAdmin = exports.verifyPassword = exports.effectiveScope = exports.isValidScopePair = exports.isValidWriteScope = exports.isValidReadScope = exports.DEFAULT_WRITE_SCOPE = exports.DEFAULT_READ_SCOPE = exports.WRITE_SCOPES = exports.READ_SCOPES = exports.getRoleWriteScope = exports.getRoleScope = exports.hasRolesAsAdmin = exports.hasGlobalEscalationAccess = exports.canManageRole = exports.isGroupAdmin = exports.isSuperAdmin = exports.hasRoleType = exports.hasRole = exports.getUserRoles = exports.removeUserRole = exports.addUserRole = exports.isValidRoleType = exports.listUsers = exports.deleteUser = exports.updateUser = exports.getUserByEmail = exports.getUserByExternalId = exports.getUser = exports.createUser = exports.VALID_ROLE_TYPES = void 0;
+exports.PREFERENCES_MAX_BYTES = exports.patchPreferences = exports.getPreferences = exports.seedAdmin = exports.verifyPassword = exports.effectiveScope = exports.isValidScopePair = exports.isValidWriteScope = exports.isValidReadScope = exports.DEFAULT_WRITE_SCOPE = exports.DEFAULT_READ_SCOPE = exports.WRITE_SCOPES = exports.READ_SCOPES = exports.getRoleWriteScope = exports.getRoleScope = exports.hasRolesAsAdmin = exports.hasGlobalEscalationAccess = exports.canManageRole = exports.isGroupAdmin = exports.isSuperAdmin = exports.hasRoleType = exports.hasRole = exports.getUserRoles = exports.removeUserRole = exports.addUserRole = exports.isValidRoleType = exports.listUsers = exports.deleteUser = exports.updateUser = exports.getUserByEmail = exports.getUserByExternalId = exports.getUser = exports.createUser = exports.VALID_ROLE_TYPES = void 0;
 var types_1 = require("./types");
 Object.defineProperty(exports, "VALID_ROLE_TYPES", { enumerable: true, get: function () { return types_1.VALID_ROLE_TYPES; } });
 var crud_1 = require("./crud");
@@ -39,3 +39,7 @@ var auth_1 = require("./auth");
 Object.defineProperty(exports, "verifyPassword", { enumerable: true, get: function () { return auth_1.verifyPassword; } });
 var seed_admin_1 = require("./seed-admin");
 Object.defineProperty(exports, "seedAdmin", { enumerable: true, get: function () { return seed_admin_1.seedAdmin; } });
+var preferences_1 = require("./preferences");
+Object.defineProperty(exports, "getPreferences", { enumerable: true, get: function () { return preferences_1.getPreferences; } });
+Object.defineProperty(exports, "patchPreferences", { enumerable: true, get: function () { return preferences_1.patchPreferences; } });
+Object.defineProperty(exports, "PREFERENCES_MAX_BYTES", { enumerable: true, get: function () { return preferences_1.PREFERENCES_MAX_BYTES; } });

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

@@ -0,0 +1,15 @@
+/**
+ * Per-user preferences — a generic JSON store for presentation state (pinned
+ * views are the first tenant, not the schema). Preferences carry URLs and UI
+ * choices only, never data and never authorization.
+ */
+/** Server-side ceiling on the stored document (the API rejects beyond it). */
+export declare const PREFERENCES_MAX_BYTES: number;
+export declare function getPreferences(userId: string): Promise<Record<string, unknown>>;
+/**
+ * Shallow-merge `patch` into the user's preferences in ONE guarded UPDATE:
+ * top-level keys overwrite, a `null` value deletes its key, and the statement
+ * refuses to commit a document over the size cap (returns null → 413 at the
+ * API). No read-then-write — concurrent patches serialize on the row.
+ */
+export declare function patchPreferences(userId: string, patch: Record<string, unknown>): Promise<Record<string, unknown> | null>;

package/build/services/user/preferences.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PREFERENCES_MAX_BYTES = void 0;
+exports.getPreferences = getPreferences;
+exports.patchPreferences = patchPreferences;
+const db_1 = require("../../lib/db");
+/**
+ * Per-user preferences — a generic JSON store for presentation state (pinned
+ * views are the first tenant, not the schema). Preferences carry URLs and UI
+ * choices only, never data and never authorization.
+ */
+/** Server-side ceiling on the stored document (the API rejects beyond it). */
+exports.PREFERENCES_MAX_BYTES = 32 * 1024;
+async function getPreferences(userId) {
+    const { rows } = await (0, db_1.getPool)().query('SELECT preferences FROM lt_users WHERE id = $1', [userId]);
+    return rows[0]?.preferences ?? {};
+}
+/**
+ * Shallow-merge `patch` into the user's preferences in ONE guarded UPDATE:
+ * top-level keys overwrite, a `null` value deletes its key, and the statement
+ * refuses to commit a document over the size cap (returns null → 413 at the
+ * API). No read-then-write — concurrent patches serialize on the row.
+ */
+async function patchPreferences(userId, patch) {
+    const deletions = Object.keys(patch).filter((k) => patch[k] === null);
+    const additions = {};
+    for (const [k, v] of Object.entries(patch)) {
+        if (v !== null)
+            additions[k] = v;
+    }
+    const { rows } = await (0, db_1.getPool)().query(`UPDATE lt_users u
+     SET preferences = ((COALESCE(u.preferences, '{}'::jsonb) || $2::jsonb) - $3::text[]),
+         updated_at = NOW()
+     WHERE u.id = $1
+       AND length(((COALESCE(u.preferences, '{}'::jsonb) || $2::jsonb) - $3::text[])::text) <= $4
+     RETURNING u.preferences`, [userId, JSON.stringify(additions), deletions, exports.PREFERENCES_MAX_BYTES]);
+    return rows[0]?.preferences ?? null;
+}

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

@@ -568,6 +568,20 @@ export declare const updateRoleSchema: z.ZodObject<{
     priority_threshold_minutes: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     priority_facet: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     upstream_roles: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString, "many">>>;
+    list_schema: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodAny>>>;
+    default_pins: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        url: z.ZodString;
+        badge: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        label: string;
+        badge?: boolean | undefined;
+    }, {
+        url: string;
+        label: string;
+        badge?: boolean | undefined;
+    }>, "many">>>;
     change_summary: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     role: string;
@@ -576,6 +590,12 @@ export declare const updateRoleSchema: z.ZodObject<{
     title?: string | null | undefined;
     properties?: Record<string, any> | null | undefined;
     metadata_schema?: Record<string, any> | null | undefined;
+    list_schema?: Record<string, any> | null | undefined;
+    default_pins?: {
+        url: string;
+        label: string;
+        badge?: boolean | undefined;
+    }[] | null | undefined;
     ops_visible?: boolean | undefined;
     parent_role?: string | null | undefined;
     sla_minutes?: number | null | undefined;
@@ -592,6 +612,12 @@ export declare const updateRoleSchema: z.ZodObject<{
     title?: string | null | undefined;
     properties?: Record<string, any> | null | undefined;
     metadata_schema?: Record<string, any> | null | undefined;
+    list_schema?: Record<string, any> | null | undefined;
+    default_pins?: {
+        url: string;
+        label: string;
+        badge?: boolean | undefined;
+    }[] | null | undefined;
     ops_visible?: boolean | undefined;
     parent_role?: string | null | undefined;
     sla_minutes?: number | null | undefined;

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

@@ -250,6 +250,12 @@ exports.updateRoleSchema = zod_1.z.object({
     priority_threshold_minutes: zod_1.z.number().min(0).nullable().optional().describe('Max age in minutes before a pending unclaimed escalation counts toward the Pace Board priority count. Falls back to sla_minutes when null.'),
     priority_facet: zod_1.z.string().regex(facet_sql_1.FACET_KEY).nullable().optional().describe('lt_escalations.metadata key holding the age origin for the priority count as an ISO 8601 UTC timestamp (e.g. authorized_at). Falls back to created_at when null. When set, items missing the key or holding an unparseable value are not counted.'),
     upstream_roles: zod_1.z.array(zod_1.z.string()).nullable().optional().describe('Replace the set of roles this station draws input from across other sequences (parent_role stays the single prior step in its own sequence). Omitted = preserve; null or [] = clear.'),
+    list_schema: zod_1.z.record(zod_1.z.any()).nullable().optional().describe('JSON contract (x-lt-* markup) that richly formats this role\'s escalation LIST page. Versioned independently of form_schema; the list always renders the latest version.'),
+    default_pins: zod_1.z.array(zod_1.z.object({
+        label: zod_1.z.string().describe('Pin label shown in the member\'s Pinned nav section'),
+        url: zod_1.z.string().describe('Dashboard-relative deep link (must start with /)'),
+        badge: zod_1.z.boolean().optional().describe('Render a live count beside the label (escalations-list URLs)'),
+    })).nullable().optional().describe('Pinned-view seeds handed to every member of this role. Members promote, hide, or reorder them via their own preferences. Null clears.'),
     change_summary: zod_1.z.string().optional().describe('Recorded on the schema version snapshot when this update changes form_schema or metadata_schema'),
 });
 exports.getRoleSchemaSchema = zod_1.z.object({

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

@@ -194,9 +194,10 @@ function registerUserTools(server) {
     server.registerTool('update_role', {
         title: 'Update Role',
         description: 'Update role metadata with PATCH semantics — omitted fields keep their ' +
-            'values. Covers display name, description, form/metadata schemas, the ' +
-            'free properties bag, ops_visible flag, parent role, and the typed ' +
-            'operational targets (sla_minutes, target_per_hour, worker_count, ' +
+            'values. Covers display name, description, form/metadata/list schemas, ' +
+            'the free properties bag, ops_visible flag, parent role, default_pins ' +
+            '(member pinned-view seeds), and the typed operational targets ' +
+            '(sla_minutes, target_per_hour, worker_count, ' +
             'priority_threshold_minutes, priority_facet).',
         inputSchema: schemas_1.updateRoleSchema,
     }, async (args) => {
@@ -214,6 +215,8 @@ function registerUserTools(server) {
             priority_threshold_minutes: args.priority_threshold_minutes,
             priority_facet: args.priority_facet,
             upstream_roles: args.upstream_roles,
+            list_schema: args.list_schema,
+            default_pins: args.default_pins,
             change_summary: args.change_summary,
         });
         if (!updated) {