@hotmeshio/long-tail 0.8.5 → 0.9.0

package/build/api/roles.d.ts

@@ -86,6 +86,8 @@ export declare function updateRole(input: {
     /** The escalation resolve FORM schema (the JIT UI). Fields may carry x-lt-bind. */
     form_schema?: Record<string, any> | null;
     metadata_schema?: Record<string, any> | null;
+    /** The escalation LIST schema — rich formatting for this role's list page. */
+    list_schema?: Record<string, any> | null;
     properties?: Record<string, any> | null;
     ops_visible?: boolean;
     parent_role?: string | null;
@@ -129,6 +131,25 @@ export declare function getRoleSchema(input: {
 export declare function listRoleSchemaVersions(input: {
     role: string;
 }): Promise<LTApiResult>;
+/**
+ * Fetch a role's LIST schema (independent version lineage from the form schema).
+ * With `version`, returns that immutable snapshot — a missing version is a 404.
+ * Without `version`, returns the live (latest) list schema with its version.
+ *
+ * @returns `{ status: 200, data: RoleListSchemaVersion }` on success
+ */
+export declare function getRoleListSchema(input: {
+    role: string;
+    version?: number;
+}): Promise<LTApiResult>;
+/**
+ * List a role's LIST schema version history, newest first.
+ *
+ * @returns `{ status: 200, data: { versions: RoleListSchemaVersionSummary[] } }`
+ */
+export declare function listRoleListSchemaVersions(input: {
+    role: string;
+}): Promise<LTApiResult>;
 /**
  * Delete a role from the system. Requires admin privileges.
  *

package/build/api/roles.js

@@ -44,6 +44,8 @@ exports.replaceEscalationTargets = replaceEscalationTargets;
 exports.updateRole = updateRole;
 exports.getRoleSchema = getRoleSchema;
 exports.listRoleSchemaVersions = listRoleSchemaVersions;
+exports.getRoleListSchema = getRoleListSchema;
+exports.listRoleListSchemaVersions = listRoleListSchemaVersions;
 exports.deleteRole = deleteRole;
 const roleService = __importStar(require("../services/role"));
 const facet_sql_1 = require("../services/escalation/facet-sql");
@@ -244,6 +246,7 @@ async function updateRole(input) {
             description: input.description,
             form_schema: input.form_schema,
             metadata_schema: input.metadata_schema,
+            list_schema: input.list_schema,
             properties: input.properties,
             ops_visible: input.ops_visible,
             parent_role: input.parent_role,
@@ -320,6 +323,53 @@ async function listRoleSchemaVersions(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Fetch a role's LIST schema (independent version lineage from the form schema).
+ * With `version`, returns that immutable snapshot — a missing version is a 404.
+ * Without `version`, returns the live (latest) list schema with its version.
+ *
+ * @returns `{ status: 200, data: RoleListSchemaVersion }` on success
+ */
+async function getRoleListSchema(input) {
+    try {
+        if (!input.role) {
+            return { status: 400, error: 'role is required' };
+        }
+        if (input.version !== undefined && (!Number.isInteger(input.version) || input.version < 1)) {
+            return { status: 400, error: 'version must be a positive integer' };
+        }
+        const schema = await roleService.getRoleListSchema(input.role, input.version);
+        if (!schema) {
+            return {
+                status: 404,
+                error: input.version !== undefined
+                    ? `List schema version ${input.version} not found for role '${input.role}'`
+                    : `Role '${input.role}' not found`,
+            };
+        }
+        return { status: 200, data: schema };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * List a role's LIST schema version history, newest first.
+ *
+ * @returns `{ status: 200, data: { versions: RoleListSchemaVersionSummary[] } }`
+ */
+async function listRoleListSchemaVersions(input) {
+    try {
+        if (!input.role) {
+            return { status: 400, error: 'role is required' };
+        }
+        const versions = await roleService.listRoleListSchemaVersions(input.role);
+        return { status: 200, data: { versions } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
 /**
  * Delete a role from the system. Requires admin privileges.
  *

package/build/lib/db/schemas/021_role_list_schema.sql

@@ -0,0 +1,27 @@
+-- Migration 021: Role escalations LIST schema
+--
+-- list_schema is the list-page analog of form_schema: it richly formats the
+-- escalation LIST page when the list is scoped to exactly one role that owns a
+-- list_schema (opt-in — absent leaves the engineer table unchanged). Unlike
+-- form_schema it is NOT pinned per-escalation; the list always renders the
+-- role's latest.
+--
+-- It versions INDEPENDENTLY of form_schema / metadata_schema: its own snapshot
+-- table (lt_role_list_schemas) and its own counter (current_list_schema_version),
+-- so editing the list view never advances the resolve form's version. The write
+-- rides the same atomic UPDATE_ROLE_METADATA statement (services/role/sql.ts),
+-- which bumps current_list_schema_version and appends a snapshot only when the
+-- provided list_schema actually differs.
+
+ALTER TABLE lt_roles
+  ADD COLUMN IF NOT EXISTS list_schema JSONB,
+  ADD COLUMN IF NOT EXISTS current_list_schema_version INTEGER;
+
+CREATE TABLE IF NOT EXISTS lt_role_list_schemas (
+  role           TEXT NOT NULL REFERENCES lt_roles(role) ON DELETE CASCADE,
+  version        INTEGER NOT NULL,
+  list_schema    JSONB,
+  change_summary TEXT,
+  created_at     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (role, version)
+);

package/build/routes/roles.js

@@ -123,6 +123,26 @@ router.get('/:role/schema/versions', async (req, res) => {
     const result = await api.listRoleSchemaVersions({ role: req.params.role });
     res.status(result.status).json(result.data ?? { error: result.error });
 });
+/**
+ * GET /api/roles/:role/list-schema
+ * Fetch the role's LIST schema (rich list-page formatting). `?version=N` pins a
+ * snapshot; omitted, the live (latest) list schema is returned with its version.
+ * Versions independently from the resolve form schema.
+ */
+router.get('/:role/list-schema', async (req, res) => {
+    const versionParam = req.query.version;
+    const version = versionParam !== undefined ? Number(versionParam) : undefined;
+    const result = await api.getRoleListSchema({ role: req.params.role, version });
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
+/**
+ * GET /api/roles/:role/list-schema/versions
+ * List the role's LIST schema version history (newest first).
+ */
+router.get('/:role/list-schema/versions', async (req, res) => {
+    const result = await api.listRoleListSchemaVersions({ role: req.params.role });
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
 /**
  * GET /api/roles/:role/escalation-targets
  * Get allowed escalation targets for a specific role.

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

@@ -1,4 +1,4 @@
-import type { EscalationChain, RoleDetail, RoleSchemaVersion, RoleSchemaVersionSummary, UpdateRoleInput } from './types';
+import type { EscalationChain, RoleDetail, RoleSchemaVersion, RoleSchemaVersionSummary, RoleListSchemaVersion, RoleListSchemaVersionSummary, UpdateRoleInput } from './types';
 /**
  * Get the roles a given source role can escalate to.
  */
@@ -60,6 +60,18 @@ export declare function listRoleSchemaVersions(role: string): Promise<RoleSchema
  * Returns null when the role (or the requested version) does not exist.
  */
 export declare function getRoleSchema(role: string, version?: number): Promise<RoleSchemaVersion | null>;
+/**
+ * List the list-schema version history for a role (newest first). The schema is
+ * elided — presence flag only; fetch a full snapshot via getRoleListSchema.
+ */
+export declare function listRoleListSchemaVersions(role: string): Promise<RoleListSchemaVersionSummary[]>;
+/**
+ * Fetch a role's list schema. With a version, reads the immutable snapshot from
+ * lt_role_list_schemas; without one, the live (latest) column — a role that has
+ * never versioned its list schema still answers with version null. Returns null
+ * when the role (or the requested version) does not exist.
+ */
+export declare function getRoleListSchema(role: string, version?: number): Promise<RoleListSchemaVersion | null>;
 /**
  * Fetch a role's live form_schema — the escalation form the dashboard renders.
  */

package/build/services/role/index.js

@@ -13,6 +13,8 @@ exports.updateRoleMetadata = updateRoleMetadata;
 exports.getRoleUpstreams = getRoleUpstreams;
 exports.listRoleSchemaVersions = listRoleSchemaVersions;
 exports.getRoleSchema = getRoleSchema;
+exports.listRoleListSchemaVersions = listRoleListSchemaVersions;
+exports.getRoleListSchema = getRoleListSchema;
 exports.getRoleFormSchema = getRoleFormSchema;
 exports.getRoleMetadataSchema = getRoleMetadataSchema;
 exports.deleteRole = deleteRole;
@@ -143,6 +145,7 @@ async function updateRoleMetadata(role, input) {
         provided('priority_facet'), input.priority_facet ?? null,
         input.change_summary ?? null,
         provided('upstream_roles'), upstreams,
+        provided('list_schema'), input.list_schema != null ? JSON.stringify(input.list_schema) : null,
     ]);
     if (!rows[0])
         return null;
@@ -184,6 +187,30 @@ async function getRoleSchema(role, version) {
         return null;
     return { ...rows[0], role };
 }
+/**
+ * List the list-schema version history for a role (newest first). The schema is
+ * elided — presence flag only; fetch a full snapshot via getRoleListSchema.
+ */
+async function listRoleListSchemaVersions(role) {
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.LIST_ROLE_LIST_SCHEMA_VERSIONS, [role]);
+    return rows;
+}
+/**
+ * Fetch a role's list schema. With a version, reads the immutable snapshot from
+ * lt_role_list_schemas; without one, the live (latest) column — a role that has
+ * never versioned its list schema still answers with version null. Returns null
+ * when the role (or the requested version) does not exist.
+ */
+async function getRoleListSchema(role, version) {
+    const pool = (0, db_1.getPool)();
+    const { rows } = version != null
+        ? await pool.query(sql_1.GET_ROLE_LIST_SCHEMA_VERSION, [role, version])
+        : await pool.query(sql_1.GET_ROLE_LIST_SCHEMA_CURRENT, [role]);
+    if (!rows[0])
+        return null;
+    return { ...rows[0], role };
+}
 /**
  * Fetch a role's live form_schema — the escalation form the dashboard renders.
  */

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

@@ -34,8 +34,13 @@ export declare const DELETE_ROLE = "\n  DELETE FROM lt_roles WHERE role = $1";
  * touching the same row: the DELETE only removes rows leaving the set, and the
  * INSERT's ON CONFLICT DO NOTHING skips rows that stay (delete+insert of the
  * SAME key in one statement would silently drop it — CTEs share a snapshot).
+ *
+ * The list_schema ($29 = provided sentinel, $30 = value) versions INDEPENDENTLY
+ * 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.
  */
-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      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    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\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  ), 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      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 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";
@@ -46,7 +51,14 @@ export declare const GET_ROLE_SCHEMA_VERSION = "\n  SELECT s.role, s.version, s.
  * versioned its schema still answers, with version NULL).
  */
 export declare const GET_ROLE_SCHEMA_CURRENT = "\n  SELECT r.role, r.current_schema_version AS version, r.form_schema,\n         r.metadata_schema, s.change_summary, s.created_at,\n         r.current_schema_version AS latest_version\n  FROM lt_roles r\n  LEFT JOIN lt_role_schemas s\n    ON s.role = r.role AND s.version = r.current_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    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_ROLE_LIST_SCHEMA_VERSIONS = "\n  SELECT\n    s.version,\n    s.list_schema IS NOT NULL AS has_list_schema,\n    s.change_summary,\n    s.created_at,\n    s.version = r.current_list_schema_version AS is_current\n  FROM lt_role_list_schemas s\n  JOIN lt_roles r ON r.role = s.role\n  WHERE s.role = $1\n  ORDER BY s.version DESC";
+export declare const GET_ROLE_LIST_SCHEMA_VERSION = "\n  SELECT s.role, s.version, s.list_schema,\n         s.change_summary, s.created_at, r.current_list_schema_version AS latest_version\n  FROM lt_role_list_schemas s\n  JOIN lt_roles r ON r.role = s.role\n  WHERE s.role = $1 AND s.version = $2";
+/**
+ * Latest list schema resolves from the live lt_roles column (a role that has
+ * 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 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

@@ -1,7 +1,7 @@
 "use strict";
 // ─── Escalation chain queries ───────────────────────────────────────────────
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.COUNT_ACTIVE_ESCALATION_REFS = exports.COUNT_WORKFLOW_REFS = exports.COUNT_CHAIN_REFS = exports.COUNT_USER_ROLE_REFS = exports.LIST_ROLES_WITH_DETAILS = exports.GET_ROLE_SCHEMA_CURRENT = exports.GET_ROLE_SCHEMA_VERSION = exports.LIST_ROLE_SCHEMA_VERSIONS = exports.GET_ROLE_UPSTREAMS = exports.GET_ROLE_METADATA_SCHEMA = exports.GET_ROLE_FORM_SCHEMA = exports.UPDATE_ROLE_METADATA = exports.DELETE_ROLE = exports.LIST_ROLES = exports.ENSURE_ROLE_EXISTS = exports.CHECK_ESCALATION_CHAIN_EXISTS = exports.DELETE_ESCALATION_CHAINS_BY_SOURCE = exports.DELETE_ESCALATION_CHAIN = exports.ADD_ESCALATION_CHAIN = exports.INSERT_ESCALATION_CHAIN = exports.GET_ALL_ESCALATION_CHAINS = exports.GET_ESCALATION_TARGETS = void 0;
+exports.COUNT_ACTIVE_ESCALATION_REFS = exports.COUNT_WORKFLOW_REFS = exports.COUNT_CHAIN_REFS = exports.COUNT_USER_ROLE_REFS = exports.LIST_ROLES_WITH_DETAILS = exports.GET_ROLE_LIST_SCHEMA_CURRENT = exports.GET_ROLE_LIST_SCHEMA_VERSION = exports.LIST_ROLE_LIST_SCHEMA_VERSIONS = exports.GET_ROLE_SCHEMA_CURRENT = exports.GET_ROLE_SCHEMA_VERSION = exports.LIST_ROLE_SCHEMA_VERSIONS = exports.GET_ROLE_UPSTREAMS = exports.GET_ROLE_METADATA_SCHEMA = exports.GET_ROLE_FORM_SCHEMA = exports.UPDATE_ROLE_METADATA = exports.DELETE_ROLE = exports.LIST_ROLES = exports.ENSURE_ROLE_EXISTS = exports.CHECK_ESCALATION_CHAIN_EXISTS = exports.DELETE_ESCALATION_CHAINS_BY_SOURCE = exports.DELETE_ESCALATION_CHAIN = exports.ADD_ESCALATION_CHAIN = exports.INSERT_ESCALATION_CHAIN = exports.GET_ALL_ESCALATION_CHAINS = exports.GET_ESCALATION_TARGETS = void 0;
 exports.GET_ESCALATION_TARGETS = `
   SELECT target_role
   FROM lt_config_role_escalations
@@ -68,6 +68,11 @@ exports.DELETE_ROLE = `
  * touching the same row: the DELETE only removes rows leaving the set, and the
  * INSERT's ON CONFLICT DO NOTHING skips rows that stay (delete+insert of the
  * SAME key in one statement would silently drop it — CTEs share a snapshot).
+ *
+ * The list_schema ($29 = provided sentinel, $30 = value) versions INDEPENDENTLY
+ * 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.
  */
 exports.UPDATE_ROLE_METADATA = `
   WITH updated AS (
@@ -85,23 +90,34 @@ exports.UPDATE_ROLE_METADATA = `
       priority_threshold_minutes
                       = 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,
       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)
         THEN COALESCE(current_schema_version, 0) + 1
-        ELSE current_schema_version END
+        ELSE current_schema_version END,
+      current_list_schema_version = CASE
+        WHEN $29::boolean AND $30::jsonb IS DISTINCT FROM list_schema
+        THEN COALESCE(current_list_schema_version, 0) + 1
+        ELSE current_list_schema_version END
     WHERE role = $1
     RETURNING
       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
+      current_schema_version, list_schema, current_list_schema_version
   ), 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
     FROM updated
     WHERE ($6::boolean OR $8::boolean) AND current_schema_version IS NOT NULL
     ON CONFLICT (role, version) DO NOTHING
+  ), list_snapshot AS (
+    INSERT INTO lt_role_list_schemas (role, version, list_schema, change_summary)
+    SELECT role, current_list_schema_version, list_schema, $26
+    FROM updated
+    WHERE $29::boolean AND current_list_schema_version IS NOT NULL
+    ON CONFLICT (role, version) DO NOTHING
   ), upstream_prune AS (
     DELETE FROM lt_role_upstreams
     WHERE $27::boolean AND role = $1 AND upstream_role <> ALL($28::text[])
@@ -149,6 +165,36 @@ exports.GET_ROLE_SCHEMA_CURRENT = `
   LEFT JOIN lt_role_schemas s
     ON s.role = r.role AND s.version = r.current_schema_version
   WHERE r.role = $1`;
+// ─── Versioned role LIST schemas (independent version lineage) ──────────────
+exports.LIST_ROLE_LIST_SCHEMA_VERSIONS = `
+  SELECT
+    s.version,
+    s.list_schema IS NOT NULL AS has_list_schema,
+    s.change_summary,
+    s.created_at,
+    s.version = r.current_list_schema_version AS is_current
+  FROM lt_role_list_schemas s
+  JOIN lt_roles r ON r.role = s.role
+  WHERE s.role = $1
+  ORDER BY s.version DESC`;
+exports.GET_ROLE_LIST_SCHEMA_VERSION = `
+  SELECT s.role, s.version, s.list_schema,
+         s.change_summary, s.created_at, r.current_list_schema_version AS latest_version
+  FROM lt_role_list_schemas s
+  JOIN lt_roles r ON r.role = s.role
+  WHERE s.role = $1 AND s.version = $2`;
+/**
+ * Latest list schema resolves from the live lt_roles column (a role that has
+ * never versioned its list schema still answers, with version NULL).
+ */
+exports.GET_ROLE_LIST_SCHEMA_CURRENT = `
+  SELECT r.role, r.current_list_schema_version AS version, r.list_schema,
+         s.change_summary, s.created_at,
+         r.current_list_schema_version AS latest_version
+  FROM lt_roles r
+  LEFT JOIN lt_role_list_schemas s
+    ON s.role = r.role AND s.version = r.current_list_schema_version
+  WHERE r.role = $1`;
 // ─── Role detail aggregation ────────────────────────────────────────────────
 exports.LIST_ROLES_WITH_DETAILS = `
   WITH
@@ -191,6 +237,8 @@ exports.LIST_ROLES_WITH_DETAILS = `
     r.priority_threshold_minutes,
     r.priority_facet,
     r.current_schema_version,
+    r.list_schema,
+    r.current_list_schema_version,
     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

@@ -46,6 +46,14 @@ export interface RoleDetail {
      * role first carries a schema.
      */
     current_schema_version: number | null;
+    /**
+     * JSON contract (x-lt-* markup) that richly formats the escalation LIST page
+     * when it is scoped to just this role. Opt-in and versioned INDEPENDENTLY of
+     * form_schema — a display template, always rendered at its latest version.
+     */
+    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;
     /**
      * Roles this station draws input from that live in OTHER sequences.
      * parent_role is the single "prior step" placing the role in one sequence;
@@ -77,11 +85,30 @@ export interface RoleSchemaVersionSummary {
     created_at: string;
     is_current: boolean;
 }
+/** One immutable snapshot of a role's LIST schema (independent version lineage). */
+export interface RoleListSchemaVersion {
+    role: string;
+    version: number | null;
+    list_schema: Record<string, any> | null;
+    change_summary: string | null;
+    created_at: string | null;
+    latest_version: number | null;
+}
+/** Listing row for the list-schema version history (schema elided). */
+export interface RoleListSchemaVersionSummary {
+    version: number;
+    has_list_schema: boolean;
+    change_summary: string | null;
+    created_at: string;
+    is_current: boolean;
+}
 export interface UpdateRoleInput {
     title?: string | null;
     description?: string | null;
     form_schema?: Record<string, any> | null;
     metadata_schema?: Record<string, any> | null;
+    /** JSON contract that richly formats this role's escalation list page. */
+    list_schema?: Record<string, any> | null;
     properties?: Record<string, any> | null;
     ops_visible?: boolean;
     parent_role?: string | null;

package/dashboard/dist/assets/{AdminDashboard-RrSvb8d-.js → AdminDashboard-5bWcBxyS.js}

@@ -1,2 +1,2 @@
-import{j as o}from"./vendor-query-B2UbickB.js";import{c as n}from"./tasks-GG8c_U9w.js";import{t as m}from"./index-B_aFcGv9.js";import{f as c}from"./useEventHooks-82IiMmOc.js";import{u}from"./mcp-B4F-T-7R.js";import{P as d}from"./PageHeaderWithStats-W3akV6nB.js";import"./vendor-react-CXumBFUA.js";import"./vendor-icons-DOIDKgo6.js";function j(){var a;c();const{data:s}=n({limit:1}),{data:e}=m({status:"pending",limit:1}),{data:t}=u(),r=((a=t==null?void 0:t.servers)==null?void 0:a.filter(i=>i.status==="connected").length)??0,l=t?`${r}/${t.total}`:"—";return o.jsx("div",{children:o.jsx(d,{title:"Admin",stats:[{label:"Tasks",value:(s==null?void 0:s.total)??"—"},{label:"Pending Escalations",value:(e==null?void 0:e.total)??"—",dotClass:"bg-status-pending"},{label:"MCP Servers",value:l},{label:"System",value:"Healthy",dotClass:"bg-status-success"}]})})}export{j as AdminDashboard};
-//# sourceMappingURL=AdminDashboard-RrSvb8d-.js.map
+import{j as o}from"./vendor-query-B2UbickB.js";import{c as n}from"./tasks-BYz490un.js";import{j as m}from"./index-C9moIiIq.js";import{f as c}from"./useEventHooks-ZT6RV2Gj.js";import{u}from"./mcp-CH8Tj9Pw.js";import{P as d}from"./PageHeaderWithStats-87STTAJX.js";import"./vendor-react-CXumBFUA.js";import"./vendor-icons-BXhWQC7l.js";function S(){var a;c();const{data:s}=n({limit:1}),{data:e}=m({status:"pending",limit:1}),{data:t}=u(),r=((a=t==null?void 0:t.servers)==null?void 0:a.filter(i=>i.status==="connected").length)??0,l=t?`${r}/${t.total}`:"—";return o.jsx("div",{children:o.jsx(d,{title:"Admin",stats:[{label:"Tasks",value:(s==null?void 0:s.total)??"—"},{label:"Pending Escalations",value:(e==null?void 0:e.total)??"—",dotClass:"bg-status-pending"},{label:"MCP Servers",value:l},{label:"System",value:"Healthy",dotClass:"bg-status-success"}]})})}export{S as AdminDashboard};
+//# sourceMappingURL=AdminDashboard-5bWcBxyS.js.map

package/dashboard/dist/assets/{AdminDashboard-RrSvb8d-.js.map → AdminDashboard-5bWcBxyS.js.map}

@@ -1 +1 @@
-{"version":3,"file":"AdminDashboard-RrSvb8d-.js","sources":["../../src/pages/admin/AdminDashboard.tsx"],"sourcesContent":["import { useTasks } from '../../api/tasks';\nimport { useEscalations } from '../../api/escalations';\nimport { useEscalationListEvents } from '../../hooks/useEventHooks';\nimport { useMcpServers } from '../../api/mcp';\nimport { PageHeaderWithStats } from '../../components/common/layout/PageHeaderWithStats';\n\nexport function AdminDashboard() {\n  useEscalationListEvents();\n  const { data: taskData } = useTasks({ limit: 1 });\n  const { data: pendingEsc } = useEscalations({ status: 'pending', limit: 1 });\n  const { data: mcpData } = useMcpServers();\n\n  const connectedServers =\n    mcpData?.servers?.filter((s) => s.status === 'connected').length ?? 0;\n  const mcpLabel = mcpData ? `${connectedServers}/${mcpData.total}` : '—';\n\n  return (\n    <div>\n      <PageHeaderWithStats\n        title=\"Admin\"\n        stats={[\n          { label: 'Tasks', value: taskData?.total ?? '—' },\n          { label: 'Pending Escalations', value: pendingEsc?.total ?? '—', dotClass: 'bg-status-pending' },\n          { label: 'MCP Servers', value: mcpLabel },\n          { label: 'System', value: 'Healthy', dotClass: 'bg-status-success' },\n        ]}\n      />\n    </div>\n  );\n}\n"],"names":["AdminDashboard","useEscalationListEvents","taskData","useTasks","pendingEsc","useEscalations","mcpData","useMcpServers","connectedServers","_a","s","mcpLabel","jsx","PageHeaderWithStats"],"mappings":"4UAMO,SAASA,GAAiB,OAC/BC,EAAA,EACA,KAAM,CAAE,KAAMC,CAAA,EAAaC,EAAS,CAAE,MAAO,EAAG,EAC1C,CAAE,KAAMC,CAAA,EAAeC,EAAe,CAAE,OAAQ,UAAW,MAAO,EAAG,EACrE,CAAE,KAAMC,CAAA,EAAYC,EAAA,EAEpBC,IACJC,EAAAH,GAAA,YAAAA,EAAS,UAAT,YAAAG,EAAkB,OAAQC,GAAMA,EAAE,SAAW,aAAa,SAAU,EAChEC,EAAWL,EAAU,GAAGE,CAAgB,IAAIF,EAAQ,KAAK,GAAK,IAEpE,aACG,MAAA,CACC,SAAAM,EAAAA,IAACC,EAAA,CACC,MAAM,QACN,MAAO,CACL,CAAE,MAAO,QAAS,OAAOX,GAAA,YAAAA,EAAU,QAAS,GAAA,EAC5C,CAAE,MAAO,sBAAuB,OAAOE,GAAA,YAAAA,EAAY,QAAS,IAAK,SAAU,mBAAA,EAC3E,CAAE,MAAO,cAAe,MAAOO,CAAA,EAC/B,CAAE,MAAO,SAAU,MAAO,UAAW,SAAU,mBAAA,CAAoB,CACrE,CAAA,EAEJ,CAEJ"}
+{"version":3,"file":"AdminDashboard-5bWcBxyS.js","sources":["../../src/pages/admin/AdminDashboard.tsx"],"sourcesContent":["import { useTasks } from '../../api/tasks';\nimport { useEscalations } from '../../api/escalations';\nimport { useEscalationListEvents } from '../../hooks/useEventHooks';\nimport { useMcpServers } from '../../api/mcp';\nimport { PageHeaderWithStats } from '../../components/common/layout/PageHeaderWithStats';\n\nexport function AdminDashboard() {\n  useEscalationListEvents();\n  const { data: taskData } = useTasks({ limit: 1 });\n  const { data: pendingEsc } = useEscalations({ status: 'pending', limit: 1 });\n  const { data: mcpData } = useMcpServers();\n\n  const connectedServers =\n    mcpData?.servers?.filter((s) => s.status === 'connected').length ?? 0;\n  const mcpLabel = mcpData ? `${connectedServers}/${mcpData.total}` : '—';\n\n  return (\n    <div>\n      <PageHeaderWithStats\n        title=\"Admin\"\n        stats={[\n          { label: 'Tasks', value: taskData?.total ?? '—' },\n          { label: 'Pending Escalations', value: pendingEsc?.total ?? '—', dotClass: 'bg-status-pending' },\n          { label: 'MCP Servers', value: mcpLabel },\n          { label: 'System', value: 'Healthy', dotClass: 'bg-status-success' },\n        ]}\n      />\n    </div>\n  );\n}\n"],"names":["AdminDashboard","useEscalationListEvents","taskData","useTasks","pendingEsc","useEscalations","mcpData","useMcpServers","connectedServers","_a","s","mcpLabel","jsx","PageHeaderWithStats"],"mappings":"4UAMO,SAASA,GAAiB,OAC/BC,EAAA,EACA,KAAM,CAAE,KAAMC,CAAA,EAAaC,EAAS,CAAE,MAAO,EAAG,EAC1C,CAAE,KAAMC,CAAA,EAAeC,EAAe,CAAE,OAAQ,UAAW,MAAO,EAAG,EACrE,CAAE,KAAMC,CAAA,EAAYC,EAAA,EAEpBC,IACJC,EAAAH,GAAA,YAAAA,EAAS,UAAT,YAAAG,EAAkB,OAAQC,GAAMA,EAAE,SAAW,aAAa,SAAU,EAChEC,EAAWL,EAAU,GAAGE,CAAgB,IAAIF,EAAQ,KAAK,GAAK,IAEpE,aACG,MAAA,CACC,SAAAM,EAAAA,IAACC,EAAA,CACC,MAAM,QACN,MAAO,CACL,CAAE,MAAO,QAAS,OAAOX,GAAA,YAAAA,EAAU,QAAS,GAAA,EAC5C,CAAE,MAAO,sBAAuB,OAAOE,GAAA,YAAAA,EAAY,QAAS,IAAK,SAAU,mBAAA,EAC3E,CAAE,MAAO,cAAe,MAAOO,CAAA,EAC/B,CAAE,MAAO,SAAU,MAAO,UAAW,SAAU,mBAAA,CAAoB,CACrE,CAAA,EAEJ,CAEJ"}