@hotmeshio/long-tail 0.12.1 → 0.13.0

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

@@ -0,0 +1,21 @@
+import type { LTRoleConfig } from '../../types/startup';
+export type RoleApplyOutcome = 'applied' | 'unchanged' | 'db-owned';
+/** Recorded on schema snapshots written by the startup apply. */
+export declare const STARTUP_CHANGE_SUMMARY = "startup apply (code)";
+/**
+ * Roles carrying real configuration (title or form schema) — the candidate
+ * set for the startup orphan report. Bare FK-ensured rows are excluded.
+ */
+export declare function listConfiguredRoles(): Promise<string[]>;
+/**
+ * Register one declared role at startup.
+ *
+ * The role is created if missing. Under code ownership its declared fields
+ * are compared against the stored row and written through the versioned
+ * PATCH path when they differ — a changed form/metadata schema advances the
+ * role's schema version and snapshots the pair; an unchanged declaration is
+ * a no-op. Under db ownership the metadata is written exactly once (at
+ * creation); afterwards the DB owns the row and drift is warn-logged only.
+ * Escalation targets use replace semantics when declared.
+ */
+export declare function applyRoleConfig(cfg: LTRoleConfig, codeOwned: boolean): Promise<RoleApplyOutcome>;

package/build/services/role/seed.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STARTUP_CHANGE_SUMMARY = void 0;
+exports.listConfiguredRoles = listConfiguredRoles;
+exports.applyRoleConfig = applyRoleConfig;
+const node_util_1 = require("node:util");
+const db_1 = require("../../lib/db");
+const logger_1 = require("../../lib/logger");
+const index_1 = require("./index");
+const sql_1 = require("./sql");
+/** Recorded on schema snapshots written by the startup apply. */
+exports.STARTUP_CHANGE_SUMMARY = 'startup apply (code)';
+/** Metadata fields shared 1:1 between LTRoleConfig and UpdateRoleInput. */
+const METADATA_FIELDS = [
+    'title', 'description', 'form_schema', 'metadata_schema', 'list_schema',
+    'properties', 'ops_visible', 'ops_home_default', 'parent_role',
+    'upstream_roles', 'default_pins', 'enforce_schema', 'sla_minutes',
+    'target_per_hour', 'worker_count', 'priority_threshold_minutes',
+    'priority_facet', 'entity_facet', 'entity_state_source',
+];
+/**
+ * Compare one declared field against the stored row. jsonb round-trips lose
+ * key order, so structured values must be compared as parsed values — never
+ * by string. Arrays compare order-insensitively (sorted).
+ */
+function fieldDiffers(field, declared, row) {
+    const stored = row[field];
+    if (Array.isArray(declared)) {
+        const a = [...declared].sort();
+        const b = Array.isArray(stored) ? [...stored].sort() : [];
+        return !(0, node_util_1.isDeepStrictEqual)(a, b);
+    }
+    if (declared !== null && typeof declared === 'object') {
+        return !(0, node_util_1.isDeepStrictEqual)(declared, stored ?? null);
+    }
+    // Numeric columns round-trip as strings from the driver — compare as numbers
+    // or every declared dial would read as changed on every boot.
+    if (typeof declared === 'number') {
+        return stored == null || Number(stored) !== declared;
+    }
+    return declared !== (stored ?? undefined);
+}
+/** The declared fields that differ from the stored row (PATCH-shaped). */
+function diffDeclaredFields(cfg, row) {
+    const changed = {};
+    for (const field of METADATA_FIELDS) {
+        const declared = cfg[field];
+        if (declared === undefined)
+            continue;
+        if (fieldDiffers(field, declared, row)) {
+            changed[field] = declared;
+        }
+    }
+    return changed;
+}
+/**
+ * Roles carrying real configuration (title or form schema) — the candidate
+ * set for the startup orphan report. Bare FK-ensured rows are excluded.
+ */
+async function listConfiguredRoles() {
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.LIST_CONFIGURED_ROLES);
+    return rows.map((r) => r.role);
+}
+/**
+ * Register one declared role at startup.
+ *
+ * The role is created if missing. Under code ownership its declared fields
+ * are compared against the stored row and written through the versioned
+ * PATCH path when they differ — a changed form/metadata schema advances the
+ * role's schema version and snapshots the pair; an unchanged declaration is
+ * a no-op. Under db ownership the metadata is written exactly once (at
+ * creation); afterwards the DB owns the row and drift is warn-logged only.
+ * Escalation targets use replace semantics when declared.
+ */
+async function applyRoleConfig(cfg, codeOwned) {
+    const created = await (0, index_1.createRole)(cfg.role);
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.GET_ROLE_ROW, [cfg.role]);
+    const row = rows[0];
+    const changed = diffDeclaredFields(cfg, row);
+    const changedFields = Object.keys(changed);
+    const declaredTargets = cfg.escalation_targets != null ? [...cfg.escalation_targets].sort() : null;
+    const storedTargets = declaredTargets != null ? await (0, index_1.getEscalationTargets)(cfg.role) : null;
+    const targetsDiffer = declaredTargets != null && !(0, node_util_1.isDeepStrictEqual)(declaredTargets, [...storedTargets].sort());
+    if (!codeOwned) {
+        if (created) {
+            // First boot for this role — write the declared metadata once. From
+            // here the DB owns the row (the dependents' "only if unconfigured"
+            // guard, moved into core).
+            if (changedFields.length > 0) {
+                await (0, index_1.updateRoleMetadata)(cfg.role, changed);
+            }
+            if (targetsDiffer)
+                await (0, index_1.replaceEscalationTargets)(cfg.role, declaredTargets);
+            return 'applied';
+        }
+        if (changedFields.length > 0 || targetsDiffer) {
+            const drifts = [...changedFields, ...(targetsDiffer ? ['escalation_targets'] : [])];
+            logger_1.loggerRegistry.warn(`[long-tail] config drift: role ${cfg.role} — ${drifts.join(', ')} differ between code and DB`);
+        }
+        return 'db-owned';
+    }
+    if (changedFields.length === 0 && !targetsDiffer)
+        return 'unchanged';
+    if (changedFields.length > 0) {
+        await (0, index_1.updateRoleMetadata)(cfg.role, { ...changed, change_summary: exports.STARTUP_CHANGE_SUMMARY });
+    }
+    if (targetsDiffer) {
+        await (0, index_1.replaceEscalationTargets)(cfg.role, declaredTargets);
+    }
+    return 'applied';
+}

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

@@ -14,6 +14,14 @@ export declare const DELETE_ESCALATION_CHAINS_BY_SOURCE = "\n  DELETE FROM lt_co
 export declare const CHECK_ESCALATION_CHAIN_EXISTS = "\n  SELECT 1\n  FROM lt_config_role_escalations\n  WHERE source_role = $1 AND target_role = $2";
 export declare const ENSURE_ROLE_EXISTS = "\n  INSERT INTO lt_roles (role) VALUES ($1)\n  ON CONFLICT DO NOTHING";
 export declare const LIST_ROLES = "\n  SELECT role FROM lt_roles ORDER BY role";
+/**
+ * Roles carrying real configuration (a title or a form schema). Bare FK rows
+ * and membership-only roles are excluded — the startup orphan report uses
+ * this so auto-ensured rows never read as drift.
+ */
+export declare const LIST_CONFIGURED_ROLES = "\n  SELECT role FROM lt_roles\n  WHERE title IS NOT NULL OR form_schema IS NOT NULL\n  ORDER BY role";
+/** One role's full metadata row (plus upstream inputs) for startup diffing. */
+export declare const GET_ROLE_ROW = "\n  SELECT\n    r.role, r.title, r.description, r.form_schema, r.metadata_schema,\n    r.properties, r.ops_visible, r.ops_home_default, r.parent_role,\n    r.sla_minutes, r.target_per_hour, r.worker_count,\n    r.priority_threshold_minutes, r.priority_facet,\n    r.entity_facet, r.entity_state_source,\n    r.list_schema, r.default_pins, r.enforce_schema,\n    r.current_schema_version, r.current_list_schema_version,\n    COALESCE((SELECT array_agg(u.upstream_role ORDER BY u.upstream_role)\n              FROM lt_role_upstreams u WHERE u.role = r.role), '{}') AS upstream_roles\n  FROM lt_roles r\n  WHERE r.role = $1";
 export declare const DELETE_ROLE = "\n  DELETE FROM lt_roles WHERE role = $1";
 /**
  * PATCH semantics in ONE atomic statement: each column has a boolean

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_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_PROPERTIES = exports.GET_ROLE_METADATA_SCHEMA = exports.LIST_ENFORCING_ROLES = 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_PROPERTIES = exports.GET_ROLE_METADATA_SCHEMA = exports.LIST_ENFORCING_ROLES = exports.GET_ROLE_FORM_SCHEMA = exports.UPDATE_ROLE_METADATA = exports.DELETE_ROLE = exports.GET_ROLE_ROW = exports.LIST_CONFIGURED_ROLES = 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
@@ -47,6 +47,29 @@ exports.ENSURE_ROLE_EXISTS = `
   ON CONFLICT DO NOTHING`;
 exports.LIST_ROLES = `
   SELECT role FROM lt_roles ORDER BY role`;
+/**
+ * Roles carrying real configuration (a title or a form schema). Bare FK rows
+ * and membership-only roles are excluded — the startup orphan report uses
+ * this so auto-ensured rows never read as drift.
+ */
+exports.LIST_CONFIGURED_ROLES = `
+  SELECT role FROM lt_roles
+  WHERE title IS NOT NULL OR form_schema IS NOT NULL
+  ORDER BY role`;
+/** One role's full metadata row (plus upstream inputs) for startup diffing. */
+exports.GET_ROLE_ROW = `
+  SELECT
+    r.role, r.title, r.description, r.form_schema, r.metadata_schema,
+    r.properties, r.ops_visible, r.ops_home_default, r.parent_role,
+    r.sla_minutes, r.target_per_hour, r.worker_count,
+    r.priority_threshold_minutes, r.priority_facet,
+    r.entity_facet, r.entity_state_source,
+    r.list_schema, r.default_pins, r.enforce_schema,
+    r.current_schema_version, r.current_list_schema_version,
+    COALESCE((SELECT array_agg(u.upstream_role ORDER BY u.upstream_role)
+              FROM lt_role_upstreams u WHERE u.role = r.role), '{}') AS upstream_roles
+  FROM lt_roles r
+  WHERE r.role = $1`;
 exports.DELETE_ROLE = `
   DELETE FROM lt_roles WHERE role = $1`;
 /**

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

@@ -20,6 +20,8 @@ export interface TopicSubscriber {
     topic: string;
     reaction_type: string;
 }
+/** Config-declared topic names — the startup orphan report's candidate set. */
+export declare function listConfigTopicNames(): Promise<string[]>;
 export declare function listTopics(filters?: {
     category?: string;
     search?: string;

package/build/services/topics/index.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.listConfigTopicNames = listConfigTopicNames;
 exports.listTopics = listTopics;
 exports.getTopic = getTopic;
 exports.createTopic = createTopic;
@@ -10,6 +11,12 @@ exports.seedTopic = seedTopic;
 exports.resetTopic = resetTopic;
 const db_1 = require("../../lib/db");
 const sql_1 = require("./sql");
+/** Config-declared topic names — the startup orphan report's candidate set. */
+async function listConfigTopicNames() {
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.LIST_CONFIG_TOPIC_NAMES);
+    return rows.map((r) => r.topic);
+}
 async function listTopics(filters = {}) {
     const pool = (0, db_1.getPool)();
     const limit = filters.limit ?? 50;

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

@@ -1,5 +1,7 @@
 export declare const LIST_TOPICS = "\n  SELECT t.*,\n    COALESCE(s.sub_count, 0)::int AS subscriber_count\n  FROM lt_topic_catalog t\n  LEFT JOIN LATERAL (\n    SELECT COUNT(*)::int AS sub_count\n    FROM lt_agent_subscriptions\n    WHERE enabled = true\n      AND (\n        topic = t.topic\n        OR t.topic LIKE REPLACE(REPLACE(topic, '*', '%'), '>', '%')\n      )\n  ) s ON true\n  WHERE ($1::text IS NULL OR t.category = $1)\n    AND ($2::text IS NULL OR t.topic ILIKE '%' || $2 || '%' OR t.description ILIKE '%' || $2 || '%')\n  ORDER BY t.category, t.topic\n  LIMIT $3 OFFSET $4\n";
 export declare const COUNT_TOPICS = "\n  SELECT COUNT(*)::int AS total FROM lt_topic_catalog\n  WHERE ($1::text IS NULL OR category = $1)\n    AND ($2::text IS NULL OR topic ILIKE '%' || $2 || '%' OR description ILIKE '%' || $2 || '%')\n";
+/** Config-declared topic names — the startup orphan report's candidate set. */
+export declare const LIST_CONFIG_TOPIC_NAMES = "\n  SELECT topic FROM lt_topic_catalog WHERE source = 'config' ORDER BY topic\n";
 export declare const GET_TOPIC = "\n  SELECT * FROM lt_topic_catalog WHERE topic = $1\n";
 export declare const INSERT_TOPIC = "\n  INSERT INTO lt_topic_catalog\n    (topic, description, category, payload_schema, example_payload, source, tags)\n  VALUES ($1, $2, $3, $4, $5, $6, $7)\n  RETURNING *\n";
 export declare const UPDATE_TOPIC = "\n  UPDATE lt_topic_catalog SET\n    description = COALESCE($2, description),\n    category = COALESCE($3, category),\n    payload_schema = COALESCE($4, payload_schema),\n    example_payload = COALESCE($5, example_payload),\n    tags = COALESCE($6, tags)\n  WHERE topic = $1\n  RETURNING *\n";

package/build/services/topics/sql.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LIST_SUBSCRIBERS = exports.RESET_TOPIC = exports.SEED_TOPIC = exports.UPSERT_ON_PUBLISH = exports.DELETE_TOPIC = exports.UPDATE_TOPIC = exports.INSERT_TOPIC = exports.GET_TOPIC = exports.COUNT_TOPICS = exports.LIST_TOPICS = void 0;
+exports.LIST_SUBSCRIBERS = exports.RESET_TOPIC = exports.SEED_TOPIC = exports.UPSERT_ON_PUBLISH = exports.DELETE_TOPIC = exports.UPDATE_TOPIC = exports.INSERT_TOPIC = exports.GET_TOPIC = exports.LIST_CONFIG_TOPIC_NAMES = exports.COUNT_TOPICS = exports.LIST_TOPICS = void 0;
 exports.LIST_TOPICS = `
   SELECT t.*,
     COALESCE(s.sub_count, 0)::int AS subscriber_count
@@ -24,6 +24,10 @@ exports.COUNT_TOPICS = `
   WHERE ($1::text IS NULL OR category = $1)
     AND ($2::text IS NULL OR topic ILIKE '%' || $2 || '%' OR description ILIKE '%' || $2 || '%')
 `;
+/** Config-declared topic names — the startup orphan report's candidate set. */
+exports.LIST_CONFIG_TOPIC_NAMES = `
+  SELECT topic FROM lt_topic_catalog WHERE source = 'config' ORDER BY topic
+`;
 exports.GET_TOPIC = `
   SELECT * FROM lt_topic_catalog WHERE topic = $1
 `;

package/build/services/topics/system-topics.d.ts

@@ -2,6 +2,7 @@ import type { LTTopicConfig } from '../../types';
 export declare function seedSystemTopics(): Promise<void>;
 /**
  * Seed user-declared topics from startConfig.topics[].
- * Respects `reset: true` — overwrites DB from config on every boot.
+ * Ownership per entry: `reset ?? defaultReset` — code-owned topics are
+ * overwritten from config on every boot; db-owned topics are insert-if-absent.
  */
-export declare function seedConfigTopics(topics: LTTopicConfig[]): Promise<void>;
+export declare function seedConfigTopics(topics: LTTopicConfig[], defaultReset?: boolean): Promise<void>;

package/build/services/topics/system-topics.js

@@ -314,9 +314,10 @@ async function seedSystemTopics() {
 }
 /**
  * Seed user-declared topics from startConfig.topics[].
- * Respects `reset: true` — overwrites DB from config on every boot.
+ * Ownership per entry: `reset ?? defaultReset` — code-owned topics are
+ * overwritten from config on every boot; db-owned topics are insert-if-absent.
  */
-async function seedConfigTopics(topics) {
+async function seedConfigTopics(topics, defaultReset = false) {
     for (const def of topics) {
         try {
             const payload = {
@@ -328,7 +329,7 @@ async function seedConfigTopics(topics) {
                 source: 'config',
                 tags: def.tags ?? [],
             };
-            if (def.reset) {
+            if (def.reset ?? defaultReset) {
                 await (0, index_1.resetTopic)(payload);
                 logger_1.loggerRegistry.info(`[long-tail] topic reset: ${def.topic} (config)`);
             }

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

@@ -1,6 +1,6 @@
 export { CreateUserInput, UpdateUserInput, VALID_ROLE_TYPES } from './types';
 export { createUser, getUser, getUserByExternalId, getUserByEmail, getUserByMetadataValue, updateUser, deleteUser, listUsers, } from './crud';
-export { isValidRoleType, addUserRole, removeUserRole, getUserRoles, hasRole, hasRoleType, } from './roles';
+export { isValidRoleType, addUserRole, grantRoleIfAbsent, removeUserRole, getUserRoles, hasRole, hasRoleType, } from './roles';
 export { isSuperAdmin, isGroupAdmin, canManageRole, hasGlobalEscalationAccess, hasRolesAsAdmin, getRoleScope, getRoleWriteScope } from './rbac';
 export { READ_SCOPES, WRITE_SCOPES, DEFAULT_READ_SCOPE, DEFAULT_WRITE_SCOPE, isValidReadScope, isValidWriteScope, isValidScopePair, effectiveScope, } from './scope';
 export { verifyPassword } from './auth';

package/build/services/user/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-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.getUserByMetadataValue = 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.grantRoleIfAbsent = exports.addUserRole = exports.isValidRoleType = exports.listUsers = exports.deleteUser = exports.updateUser = exports.getUserByMetadataValue = 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");
@@ -15,6 +15,7 @@ Object.defineProperty(exports, "listUsers", { enumerable: true, get: function ()
 var roles_1 = require("./roles");
 Object.defineProperty(exports, "isValidRoleType", { enumerable: true, get: function () { return roles_1.isValidRoleType; } });
 Object.defineProperty(exports, "addUserRole", { enumerable: true, get: function () { return roles_1.addUserRole; } });
+Object.defineProperty(exports, "grantRoleIfAbsent", { enumerable: true, get: function () { return roles_1.grantRoleIfAbsent; } });
 Object.defineProperty(exports, "removeUserRole", { enumerable: true, get: function () { return roles_1.removeUserRole; } });
 Object.defineProperty(exports, "getUserRoles", { enumerable: true, get: function () { return roles_1.getUserRoles; } });
 Object.defineProperty(exports, "hasRole", { enumerable: true, get: function () { return roles_1.hasRole; } });

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

@@ -6,6 +6,14 @@ export interface RoleScopeInput {
     write_scope?: LTWriteScope;
 }
 export declare function addUserRole(userId: string, role: string, type: LTRoleType, scope?: RoleScopeInput): Promise<LTUserRole>;
+/**
+ * Grant a role ONLY when the user does not already hold it — the scope-safe
+ * add for sync paths (SSO provisioning, claim-time provisioning). An existing
+ * grant is never touched: identity sync adds missing memberships, it never
+ * mutates the type/scope/provenance an admin set. Returns the inserted row, or
+ * null when the membership already existed.
+ */
+export declare function grantRoleIfAbsent(userId: string, role: string, type: LTRoleType, scope?: RoleScopeInput): Promise<LTUserRole | null>;
 export declare function removeUserRole(userId: string, role: string): Promise<boolean>;
 export declare function getUserRoles(userId: string): Promise<LTUserRole[]>;
 export declare function hasRole(userId: string, role: string): Promise<boolean>;

package/build/services/user/roles.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isValidRoleType = isValidRoleType;
 exports.addUserRole = addUserRole;
+exports.grantRoleIfAbsent = grantRoleIfAbsent;
 exports.removeUserRole = removeUserRole;
 exports.getUserRoles = getUserRoles;
 exports.hasRole = hasRole;
@@ -36,6 +37,34 @@ async function addUserRole(userId, role, type, scope) {
         client.release();
     }
 }
+/**
+ * Grant a role ONLY when the user does not already hold it — the scope-safe
+ * add for sync paths (SSO provisioning, claim-time provisioning). An existing
+ * grant is never touched: identity sync adds missing memberships, it never
+ * mutates the type/scope/provenance an admin set. Returns the inserted row, or
+ * null when the membership already existed.
+ */
+async function grantRoleIfAbsent(userId, role, type, scope) {
+    const eff = (0, scope_1.effectiveScope)(type, scope?.read_scope ?? scope_1.DEFAULT_READ_SCOPE, scope?.write_scope ?? scope_1.DEFAULT_WRITE_SCOPE);
+    const pool = (0, db_1.getPool)();
+    // Same ensure-role + insert transaction as addUserRole: the FK target and the
+    // assignment commit together.
+    const client = await pool.connect();
+    try {
+        await client.query('BEGIN');
+        await client.query(sql_1.ENSURE_ROLE_EXISTS, [role]);
+        const { rows } = await client.query(sql_1.INSERT_USER_ROLE_IF_ABSENT, [userId, role, type, eff.read, eff.write]);
+        await client.query('COMMIT');
+        return rows[0] ?? null;
+    }
+    catch (err) {
+        await client.query('ROLLBACK');
+        throw err;
+    }
+    finally {
+        client.release();
+    }
+}
 async function removeUserRole(userId, role) {
     const pool = (0, db_1.getPool)();
     const { rowCount } = await pool.query(sql_1.DELETE_USER_ROLE, [userId, role]);

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

@@ -37,6 +37,12 @@ export declare const GET_ROLES_BY_USER_IDS = "SELECT r.user_id, r.role, r.type,
  *  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";
+/** Insert a user–role assignment ONLY when absent. The scope-safe grant for
+ *  sync paths (SSO, claim-time provisioning): an existing row — whatever its
+ *  type/scope/provenance — is left untouched; zero rows return on conflict.
+ *  Identity sync may add a missing membership but never mutates authorization
+ *  an admin already set. */
+export declare const INSERT_USER_ROLE_IF_ABSENT = "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 NOTHING\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

@@ -1,7 +1,7 @@
 "use strict";
 // ─── Shared queries (used by multiple modules) ──────────────────────────────
 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_USERS_BY_METADATA_VALUE = 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;
+exports.IS_GROUP_ADMIN = exports.GET_ROLE_SCOPE = exports.HAS_ROLE_TYPE = exports.HAS_ROLE = exports.DELETE_USER_ROLE = exports.INSERT_USER_ROLE_IF_ABSENT = 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_USERS_BY_METADATA_VALUE = 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. granted_by_persona
@@ -74,6 +74,14 @@ exports.UPSERT_USER_ROLE = `INSERT INTO lt_user_roles (user_id, role, type, read
      write_scope = EXCLUDED.write_scope,
      granted_by_persona = NULL
    RETURNING role, type, read_scope, write_scope, created_at`;
+/** Insert a user–role assignment ONLY when absent. The scope-safe grant for
+ *  sync paths (SSO, claim-time provisioning): an existing row — whatever its
+ *  type/scope/provenance — is left untouched; zero rows return on conflict.
+ *  Identity sync may add a missing membership but never mutates authorization
+ *  an admin already set. */
+exports.INSERT_USER_ROLE_IF_ABSENT = `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 NOTHING
+   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';
 exports.HAS_ROLE_TYPE = 'SELECT 1 FROM lt_user_roles WHERE user_id = $1 AND type = $2 LIMIT 1';

package/build/services/user/sso-provision.js

@@ -49,13 +49,21 @@ async function ssoProvision(identity, ssoConfig) {
         throw err;
     }
 }
-/** Ensure all resolved roles exist on an already-provisioned user. */
+/**
+ * Ensure all resolved roles exist on an already-provisioned user.
+ *
+ * SSO synchronizes IDENTITY, never authorization scope: a missing membership
+ * is added, an existing one is left exactly as the admin set it (type, scope,
+ * persona provenance). The has-check keeps the steady-state login read-only;
+ * `grantRoleIfAbsent` (INSERT … DO NOTHING) is the database-level guarantee
+ * for anything that races past it.
+ */
 async function syncExistingUser(userId, ltRoles) {
     const currentRoles = await (0, roles_1.getUserRoles)(userId);
     for (const lr of ltRoles) {
         const has = currentRoles.some((r) => r.role === lr.role);
         if (!has) {
-            await (0, roles_1.addUserRole)(userId, lr.role, lr.type);
+            await (0, roles_1.grantRoleIfAbsent)(userId, lr.role, lr.type);
         }
     }
     const updatedRoles = await (0, roles_1.getUserRoles)(userId);
@@ -69,8 +77,11 @@ function resolveRoles(hostRoles, defaultRoleType, roleMap) {
     const mapped = roleMap
         ? hostRoles.filter((r) => roleMap[r]).map((r) => roleMap[r])
         : hostRoles;
+    // A configured roleMap is the complete contract: an unmapped host role means
+    // "no LT role" — never an injected default. The default membership applies
+    // only when no roleMap exists (raw host roles pass through, empty = default).
     if (mapped.length === 0) {
-        return [{ role: defaultRoleType, type: defaultRoleType }];
+        return roleMap ? [] : [{ role: defaultRoleType, type: defaultRoleType }];
     }
     return mapped.map((role) => ({
         role,

package/build/start/apply-report.d.ts

@@ -0,0 +1,26 @@
+/** Who owns declared configuration after first boot. */
+export type ConfigSource = 'code' | 'db';
+/**
+ * Effective ownership for one declared entry: the per-entry `reset` flag wins
+ * in either direction; otherwise the global `configSource` decides.
+ */
+export declare function ownedByCode(reset: boolean | undefined, source: ConfigSource): boolean;
+/** Outcome of one entry's startup pass. */
+export type ApplyOutcome = 'applied' | 'unchanged' | 'db-owned';
+/** Per-surface tally of a boot's config pass. */
+export interface SurfaceReport {
+    applied: string[];
+    unchanged: string[];
+    dbOwned: string[];
+    /** DB rows of this surface not declared in code (reported, never deleted). */
+    orphans: string[];
+}
+export declare function newSurfaceReport(): SurfaceReport;
+/** Record one entry's outcome on the surface report. */
+export declare function recordOutcome(report: SurfaceReport, name: string, outcome: ApplyOutcome): void;
+export declare function withConfigLock<T>(fn: () => Promise<T>): Promise<T>;
+/**
+ * One boot line per surface. Warn level when orphans exist so operators see
+ * "declared set no longer matches the DB" without grepping.
+ */
+export declare function logSurfaceReport(surface: string, report: SurfaceReport): void;

package/build/start/apply-report.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ownedByCode = ownedByCode;
+exports.newSurfaceReport = newSurfaceReport;
+exports.recordOutcome = recordOutcome;
+exports.withConfigLock = withConfigLock;
+exports.logSurfaceReport = logSurfaceReport;
+const db_1 = require("../lib/db");
+const logger_1 = require("../lib/logger");
+/**
+ * Effective ownership for one declared entry: the per-entry `reset` flag wins
+ * in either direction; otherwise the global `configSource` decides.
+ */
+function ownedByCode(reset, source) {
+    return reset ?? source === 'code';
+}
+function newSurfaceReport() {
+    return { applied: [], unchanged: [], dbOwned: [], orphans: [] };
+}
+/** Record one entry's outcome on the surface report. */
+function recordOutcome(report, name, outcome) {
+    if (outcome === 'applied')
+        report.applied.push(name);
+    else if (outcome === 'unchanged')
+        report.unchanged.push(name);
+    else
+        report.dbOwned.push(name);
+}
+/**
+ * Serializes multi-statement config writes (role-list replaces, escalation
+ * target replaces) across concurrently booting containers. Single-statement
+ * upserts are individually race-safe; the lock exists for the replace
+ * transactions and keeps boot reports coherent. Distinct from the migration
+ * lock so a slow migration on one container never blocks another's config
+ * pass behind two locks at once.
+ */
+const CONFIG_APPLY_LOCK_ID = 8675310;
+async function withConfigLock(fn) {
+    const pool = (0, db_1.getPool)();
+    const client = await pool.connect();
+    try {
+        await client.query(`SELECT pg_advisory_lock(${CONFIG_APPLY_LOCK_ID})`);
+        return await fn();
+    }
+    finally {
+        await client
+            .query(`SELECT pg_advisory_unlock(${CONFIG_APPLY_LOCK_ID})`)
+            .catch(() => { });
+        client.release();
+    }
+}
+/**
+ * One boot line per surface. Warn level when orphans exist so operators see
+ * "declared set no longer matches the DB" without grepping.
+ */
+function logSurfaceReport(surface, report) {
+    const counts = `applied ${report.applied.length}, unchanged ${report.unchanged.length}, ` +
+        `db-owned ${report.dbOwned.length}`;
+    if (report.orphans.length > 0) {
+        logger_1.loggerRegistry.warn(`[long-tail] config apply (${surface}): ${counts}, orphans: [${report.orphans.join(', ')}]`);
+    }
+    else {
+        logger_1.loggerRegistry.info(`[long-tail] config apply (${surface}): ${counts}`);
+    }
+}

package/build/start/config.js

@@ -103,7 +103,14 @@ async function applyServerAuthConfig(startConfig) {
     // SSO — store config for requireAuth fallback and /api/auth/sso exchange
     if (startConfig.auth?.sso) {
         const { setSSOConfig } = await Promise.resolve().then(() => __importStar(require('../modules/sso')));
-        setSSOConfig(startConfig.auth.sso);
+        const sso = { ...startConfig.auth.sso };
+        // A keepalive beat re-runs resolve + provisioning per tab; clamp runaway
+        // intervals (a 1s misconfiguration = one exchange per second per tab).
+        if (sso.keepaliveSeconds != null && sso.keepaliveSeconds > 0 && sso.keepaliveSeconds < 15) {
+            logger_1.loggerRegistry.warn(`[long-tail] sso.keepaliveSeconds ${sso.keepaliveSeconds}s clamped to 15s`);
+            sso.keepaliveSeconds = 15;
+        }
+        setSSOConfig(sso);
         logger_1.loggerRegistry.info('[long-tail] SSO enabled — host auth will be trusted');
     }
 }