@hotmeshio/long-tail 0.12.1 → 0.13.1

package/build/services/mcp/db.js

@@ -10,6 +10,7 @@ exports.listMcpServers = listMcpServers;
 exports.getAutoConnectServers = getAutoConnectServers;
 exports.findServersByTags = findServersByTags;
 exports.seedMcpServer = seedMcpServer;
+exports.applyMcpServer = applyMcpServer;
 exports.cleanStaleBuiltinServers = cleanStaleBuiltinServers;
 const db_1 = require("../../lib/db");
 const logger_1 = require("../../lib/logger");
@@ -190,6 +191,29 @@ async function seedMcpServer(input) {
     }
     return inserted;
 }
+/**
+ * Apply an MCP server declaration at startup (code is source of truth).
+ * Config fields — description, tags, category, compile hints, credential
+ * providers — are written when they differ; runtime state (tool manifest,
+ * connection status) is never touched. Returns 'applied' when the row was
+ * inserted or updated, 'unchanged' when the declaration already matches.
+ */
+async function applyMcpServer(input) {
+    const pool = (0, db_1.getPool)();
+    const { rowCount } = await pool.query(sql_1.APPLY_MCP_SERVER, [
+        input.name,
+        input.description || null,
+        'stdio',
+        JSON.stringify({ builtin: true, process: 'in-memory' }),
+        JSON.stringify(input.toolManifest || []),
+        JSON.stringify({ builtin: true }),
+        input.tags || [],
+        input.compileHints || null,
+        input.credentialProviders || [],
+        input.category || null,
+    ]);
+    return (rowCount ?? 0) > 0 ? 'applied' : 'unchanged';
+}
 /**
  * Remove builtin MCP servers that are no longer declared in factory config.
  */

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

@@ -19,3 +19,11 @@ export declare const DELETE_STALE_BUILTIN_SERVERS = "\n  DELETE FROM lt_mcp_serv
 export declare const UPSERT_MCP_SERVER = "\n  INSERT INTO lt_mcp_servers\n    (name, description, transport_type, transport_config, auto_connect, status, tool_manifest, metadata, tags, compile_hints, credential_providers, last_connected_at)\n  VALUES ($1, $2, $3, $4, true, 'connected', $5, $6, $7, $8, $9, NOW())\n  ON CONFLICT (name) DO UPDATE SET\n    tool_manifest = EXCLUDED.tool_manifest,\n    metadata = EXCLUDED.metadata,\n    description = EXCLUDED.description,\n    tags = EXCLUDED.tags,\n    compile_hints = EXCLUDED.compile_hints,\n    credential_providers = EXCLUDED.credential_providers,\n    status = 'connected',\n    last_connected_at = NOW()";
 /** Seed — insert-if-absent. DB is source of truth after first boot. */
 export declare const SEED_MCP_SERVER = "\n  INSERT INTO lt_mcp_servers\n    (name, description, transport_type, transport_config, auto_connect, status, tool_manifest, metadata, tags, compile_hints, credential_providers, category, last_connected_at)\n  VALUES ($1, $2, $3, $4, true, 'connected', $5, $6, $7, $8, $9, $10, NOW())\n  ON CONFLICT (name) DO NOTHING";
+/**
+ * Apply — code is source of truth for the CONFIG fields only. On conflict the
+ * update rewrites description/tags/category/compile_hints/credential_providers
+ * and leaves runtime state (tool_manifest, status, last_connected_at,
+ * transport_config) untouched; the IS DISTINCT FROM guard makes an unchanged
+ * declaration a zero-row no-op. `(xmax = 0)` distinguishes insert from update.
+ */
+export declare const APPLY_MCP_SERVER = "\n  INSERT INTO lt_mcp_servers\n    (name, description, transport_type, transport_config, auto_connect, status, tool_manifest, metadata, tags, compile_hints, credential_providers, category, last_connected_at)\n  VALUES ($1, $2, $3, $4, true, 'connected', $5, $6, $7, $8, $9, $10, NOW())\n  ON CONFLICT (name) DO UPDATE SET\n    description = EXCLUDED.description,\n    tags = EXCLUDED.tags,\n    category = EXCLUDED.category,\n    compile_hints = EXCLUDED.compile_hints,\n    credential_providers = EXCLUDED.credential_providers\n  WHERE (lt_mcp_servers.description, lt_mcp_servers.tags, lt_mcp_servers.category,\n         lt_mcp_servers.compile_hints, lt_mcp_servers.credential_providers)\n    IS DISTINCT FROM\n        (EXCLUDED.description, EXCLUDED.tags, EXCLUDED.category,\n         EXCLUDED.compile_hints, EXCLUDED.credential_providers)\n  RETURNING (xmax = 0) AS inserted";

package/build/services/mcp/sql.js

@@ -1,7 +1,7 @@
 "use strict";
 // ─── MCP server CRUD ────────────────────────────────────────────────────────
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SEED_MCP_SERVER = exports.UPSERT_MCP_SERVER = exports.DELETE_STALE_BUILTIN_SERVERS = exports.HEALTH_DURABLE_WORKFLOWS = exports.HEALTH_WORKFLOW_CONFIGS = exports.HEALTH_COMPILED_WORKFLOWS = exports.HEALTH_MCP_SERVER_LIST = exports.HEALTH_MCP_SERVERS = exports.HEALTH_RECENT_ACTIVITY = exports.HEALTH_ACTIVE_WORKFLOW_TYPES = exports.HEALTH_ESCALATION_COUNTS = exports.HEALTH_TASK_COUNTS = exports.GET_AUTO_CONNECT_SERVERS = exports.UPDATE_STATUS = exports.UPDATE_STATUS_CONNECTED = exports.DELETE_MCP_SERVER = exports.GET_MCP_SERVER_BY_NAME = exports.GET_MCP_SERVER = exports.CREATE_MCP_SERVER = void 0;
+exports.APPLY_MCP_SERVER = exports.SEED_MCP_SERVER = exports.UPSERT_MCP_SERVER = exports.DELETE_STALE_BUILTIN_SERVERS = exports.HEALTH_DURABLE_WORKFLOWS = exports.HEALTH_WORKFLOW_CONFIGS = exports.HEALTH_COMPILED_WORKFLOWS = exports.HEALTH_MCP_SERVER_LIST = exports.HEALTH_MCP_SERVERS = exports.HEALTH_RECENT_ACTIVITY = exports.HEALTH_ACTIVE_WORKFLOW_TYPES = exports.HEALTH_ESCALATION_COUNTS = exports.HEALTH_TASK_COUNTS = exports.GET_AUTO_CONNECT_SERVERS = exports.UPDATE_STATUS = exports.UPDATE_STATUS_CONNECTED = exports.DELETE_MCP_SERVER = exports.GET_MCP_SERVER_BY_NAME = exports.GET_MCP_SERVER = exports.CREATE_MCP_SERVER = void 0;
 exports.CREATE_MCP_SERVER = `
   INSERT INTO lt_mcp_servers
     (name, description, transport_type, transport_config, auto_connect, metadata, tags, compile_hints, credential_providers)
@@ -97,3 +97,26 @@ exports.SEED_MCP_SERVER = `
     (name, description, transport_type, transport_config, auto_connect, status, tool_manifest, metadata, tags, compile_hints, credential_providers, category, last_connected_at)
   VALUES ($1, $2, $3, $4, true, 'connected', $5, $6, $7, $8, $9, $10, NOW())
   ON CONFLICT (name) DO NOTHING`;
+/**
+ * Apply — code is source of truth for the CONFIG fields only. On conflict the
+ * update rewrites description/tags/category/compile_hints/credential_providers
+ * and leaves runtime state (tool_manifest, status, last_connected_at,
+ * transport_config) untouched; the IS DISTINCT FROM guard makes an unchanged
+ * declaration a zero-row no-op. `(xmax = 0)` distinguishes insert from update.
+ */
+exports.APPLY_MCP_SERVER = `
+  INSERT INTO lt_mcp_servers
+    (name, description, transport_type, transport_config, auto_connect, status, tool_manifest, metadata, tags, compile_hints, credential_providers, category, last_connected_at)
+  VALUES ($1, $2, $3, $4, true, 'connected', $5, $6, $7, $8, $9, $10, NOW())
+  ON CONFLICT (name) DO UPDATE SET
+    description = EXCLUDED.description,
+    tags = EXCLUDED.tags,
+    category = EXCLUDED.category,
+    compile_hints = EXCLUDED.compile_hints,
+    credential_providers = EXCLUDED.credential_providers
+  WHERE (lt_mcp_servers.description, lt_mcp_servers.tags, lt_mcp_servers.category,
+         lt_mcp_servers.compile_hints, lt_mcp_servers.credential_providers)
+    IS DISTINCT FROM
+        (EXCLUDED.description, EXCLUDED.tags, EXCLUDED.category,
+         EXCLUDED.compile_hints, EXCLUDED.credential_providers)
+  RETURNING (xmax = 0) AS inserted`;

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/scan-code/index.d.ts

@@ -1,4 +1,4 @@
 export { listScanSchemes, getScanScheme, listScanRules, getScanRule, } from './read';
-export { upsertScanScheme, deleteScanScheme, upsertScanRule, deleteScanRule, seedScanScheme, seedScanRule, type ScanSchemeInput, type ScanRuleInput, } from './write';
+export { upsertScanScheme, deleteScanScheme, upsertScanRule, deleteScanRule, seedScanScheme, seedScanRule, applyScanScheme, applyScanRule, type ScanSchemeInput, type ScanRuleInput, } from './write';
 export { parseScanCode, interpolateScanTemplate, type ScanParseResult, type ScanParseFailure, type ScanTemplateContext, } from './parse';
 export { assertValidScheme, assertValidSteps } from './validate';

package/build/services/scan-code/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.assertValidSteps = exports.assertValidScheme = exports.interpolateScanTemplate = exports.parseScanCode = exports.seedScanRule = exports.seedScanScheme = exports.deleteScanRule = exports.upsertScanRule = exports.deleteScanScheme = exports.upsertScanScheme = exports.getScanRule = exports.listScanRules = exports.getScanScheme = exports.listScanSchemes = void 0;
+exports.assertValidSteps = exports.assertValidScheme = exports.interpolateScanTemplate = exports.parseScanCode = exports.applyScanRule = exports.applyScanScheme = exports.seedScanRule = exports.seedScanScheme = exports.deleteScanRule = exports.upsertScanRule = exports.deleteScanScheme = exports.upsertScanScheme = exports.getScanRule = exports.listScanRules = exports.getScanScheme = exports.listScanSchemes = void 0;
 var read_1 = require("./read");
 Object.defineProperty(exports, "listScanSchemes", { enumerable: true, get: function () { return read_1.listScanSchemes; } });
 Object.defineProperty(exports, "getScanScheme", { enumerable: true, get: function () { return read_1.getScanScheme; } });
@@ -13,6 +13,8 @@ Object.defineProperty(exports, "upsertScanRule", { enumerable: true, get: functi
 Object.defineProperty(exports, "deleteScanRule", { enumerable: true, get: function () { return write_1.deleteScanRule; } });
 Object.defineProperty(exports, "seedScanScheme", { enumerable: true, get: function () { return write_1.seedScanScheme; } });
 Object.defineProperty(exports, "seedScanRule", { enumerable: true, get: function () { return write_1.seedScanRule; } });
+Object.defineProperty(exports, "applyScanScheme", { enumerable: true, get: function () { return write_1.applyScanScheme; } });
+Object.defineProperty(exports, "applyScanRule", { enumerable: true, get: function () { return write_1.applyScanRule; } });
 var parse_1 = require("./parse");
 Object.defineProperty(exports, "parseScanCode", { enumerable: true, get: function () { return parse_1.parseScanCode; } });
 Object.defineProperty(exports, "interpolateScanTemplate", { enumerable: true, get: function () { return parse_1.interpolateScanTemplate; } });

package/build/services/scan-code/sql.d.ts

@@ -8,3 +8,10 @@ export declare const UPSERT_ACTION = "INSERT INTO lt_config_scan_actions\n  (sch
 export declare const DELETE_ACTION = "DELETE FROM lt_config_scan_actions WHERE scheme_version = $1 AND category = $2";
 export declare const SEED_SCHEME = "INSERT INTO lt_config_scan_schemes\n  (version, name, description, target_facet, encoding, delimiter, target_length,\n   kind, grant_ttl_seconds, grant_max_uses, enabled)\nVALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)\nON CONFLICT (version) DO NOTHING";
 export declare const SEED_ACTION = "INSERT INTO lt_config_scan_actions\n  (scheme_version, category, name, steps, fallback, not_primed, enabled)\nVALUES ($1, $2, $3, $4, $5, $6, $7)\nON CONFLICT (scheme_version, category) DO NOTHING";
+/**
+ * Apply — same column set as the upsert, guarded by IS DISTINCT FROM so an
+ * unchanged declaration is a zero-row no-op. `(xmax = 0)` distinguishes
+ * insert from update. jsonb columns compare content-wise in SQL.
+ */
+export declare const APPLY_SCHEME = "INSERT INTO lt_config_scan_schemes\n  (version, name, description, target_facet, encoding, delimiter, target_length,\n   kind, grant_ttl_seconds, grant_max_uses, enabled)\nVALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)\nON CONFLICT (version) DO UPDATE SET\n  name = EXCLUDED.name,\n  description = EXCLUDED.description,\n  target_facet = EXCLUDED.target_facet,\n  encoding = EXCLUDED.encoding,\n  delimiter = EXCLUDED.delimiter,\n  target_length = EXCLUDED.target_length,\n  kind = EXCLUDED.kind,\n  grant_ttl_seconds = EXCLUDED.grant_ttl_seconds,\n  grant_max_uses = EXCLUDED.grant_max_uses,\n  enabled = EXCLUDED.enabled,\n  updated_at = NOW()\nWHERE (lt_config_scan_schemes.name, lt_config_scan_schemes.description,\n       lt_config_scan_schemes.target_facet, lt_config_scan_schemes.encoding,\n       lt_config_scan_schemes.delimiter, lt_config_scan_schemes.target_length,\n       lt_config_scan_schemes.kind, lt_config_scan_schemes.grant_ttl_seconds,\n       lt_config_scan_schemes.grant_max_uses, lt_config_scan_schemes.enabled)\n  IS DISTINCT FROM\n      (EXCLUDED.name, EXCLUDED.description, EXCLUDED.target_facet,\n       EXCLUDED.encoding, EXCLUDED.delimiter, EXCLUDED.target_length,\n       EXCLUDED.kind, EXCLUDED.grant_ttl_seconds, EXCLUDED.grant_max_uses,\n       EXCLUDED.enabled)\nRETURNING (xmax = 0) AS inserted";
+export declare const APPLY_ACTION = "INSERT INTO lt_config_scan_actions\n  (scheme_version, category, name, steps, fallback, not_primed, enabled)\nVALUES ($1, $2, $3, $4, $5, $6, $7)\nON CONFLICT (scheme_version, category) DO UPDATE SET\n  name = EXCLUDED.name,\n  steps = EXCLUDED.steps,\n  fallback = EXCLUDED.fallback,\n  not_primed = EXCLUDED.not_primed,\n  enabled = EXCLUDED.enabled,\n  updated_at = NOW()\nWHERE (lt_config_scan_actions.name, lt_config_scan_actions.steps,\n       lt_config_scan_actions.fallback, lt_config_scan_actions.not_primed,\n       lt_config_scan_actions.enabled)\n  IS DISTINCT FROM\n      (EXCLUDED.name, EXCLUDED.steps, EXCLUDED.fallback,\n       EXCLUDED.not_primed, EXCLUDED.enabled)\nRETURNING (xmax = 0) AS inserted";

package/build/services/scan-code/sql.js

@@ -3,7 +3,7 @@
 // Read queries                                                       //
 // ------------------------------------------------------------------ //
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SEED_ACTION = exports.SEED_SCHEME = exports.DELETE_ACTION = exports.UPSERT_ACTION = exports.DELETE_SCHEME = exports.UPSERT_SCHEME = exports.GET_ACTION = exports.LIST_ACTIONS = exports.GET_SCHEME = exports.LIST_SCHEMES = void 0;
+exports.APPLY_ACTION = exports.APPLY_SCHEME = exports.SEED_ACTION = exports.SEED_SCHEME = exports.DELETE_ACTION = exports.UPSERT_ACTION = exports.DELETE_SCHEME = exports.UPSERT_SCHEME = exports.GET_ACTION = exports.LIST_ACTIONS = exports.GET_SCHEME = exports.LIST_SCHEMES = void 0;
 exports.LIST_SCHEMES = `\
 SELECT * FROM lt_config_scan_schemes ORDER BY version`;
 exports.GET_SCHEME = `\
@@ -61,3 +61,57 @@ INSERT INTO lt_config_scan_actions
   (scheme_version, category, name, steps, fallback, not_primed, enabled)
 VALUES ($1, $2, $3, $4, $5, $6, $7)
 ON CONFLICT (scheme_version, category) DO NOTHING`;
+// ------------------------------------------------------------------ //
+// Apply (code-owned startup pass — code is source of truth)          //
+// ------------------------------------------------------------------ //
+/**
+ * Apply — same column set as the upsert, guarded by IS DISTINCT FROM so an
+ * unchanged declaration is a zero-row no-op. `(xmax = 0)` distinguishes
+ * insert from update. jsonb columns compare content-wise in SQL.
+ */
+exports.APPLY_SCHEME = `\
+INSERT INTO lt_config_scan_schemes
+  (version, name, description, target_facet, encoding, delimiter, target_length,
+   kind, grant_ttl_seconds, grant_max_uses, enabled)
+VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)
+ON CONFLICT (version) DO UPDATE SET
+  name = EXCLUDED.name,
+  description = EXCLUDED.description,
+  target_facet = EXCLUDED.target_facet,
+  encoding = EXCLUDED.encoding,
+  delimiter = EXCLUDED.delimiter,
+  target_length = EXCLUDED.target_length,
+  kind = EXCLUDED.kind,
+  grant_ttl_seconds = EXCLUDED.grant_ttl_seconds,
+  grant_max_uses = EXCLUDED.grant_max_uses,
+  enabled = EXCLUDED.enabled,
+  updated_at = NOW()
+WHERE (lt_config_scan_schemes.name, lt_config_scan_schemes.description,
+       lt_config_scan_schemes.target_facet, lt_config_scan_schemes.encoding,
+       lt_config_scan_schemes.delimiter, lt_config_scan_schemes.target_length,
+       lt_config_scan_schemes.kind, lt_config_scan_schemes.grant_ttl_seconds,
+       lt_config_scan_schemes.grant_max_uses, lt_config_scan_schemes.enabled)
+  IS DISTINCT FROM
+      (EXCLUDED.name, EXCLUDED.description, EXCLUDED.target_facet,
+       EXCLUDED.encoding, EXCLUDED.delimiter, EXCLUDED.target_length,
+       EXCLUDED.kind, EXCLUDED.grant_ttl_seconds, EXCLUDED.grant_max_uses,
+       EXCLUDED.enabled)
+RETURNING (xmax = 0) AS inserted`;
+exports.APPLY_ACTION = `\
+INSERT INTO lt_config_scan_actions
+  (scheme_version, category, name, steps, fallback, not_primed, enabled)
+VALUES ($1, $2, $3, $4, $5, $6, $7)
+ON CONFLICT (scheme_version, category) DO UPDATE SET
+  name = EXCLUDED.name,
+  steps = EXCLUDED.steps,
+  fallback = EXCLUDED.fallback,
+  not_primed = EXCLUDED.not_primed,
+  enabled = EXCLUDED.enabled,
+  updated_at = NOW()
+WHERE (lt_config_scan_actions.name, lt_config_scan_actions.steps,
+       lt_config_scan_actions.fallback, lt_config_scan_actions.not_primed,
+       lt_config_scan_actions.enabled)
+  IS DISTINCT FROM
+      (EXCLUDED.name, EXCLUDED.steps, EXCLUDED.fallback,
+       EXCLUDED.not_primed, EXCLUDED.enabled)
+RETURNING (xmax = 0) AS inserted`;

package/build/services/scan-code/write.d.ts

@@ -28,3 +28,11 @@ export declare function deleteScanRule(schemeVersion: number, category: string):
 /** Insert-if-absent seeding — DB is the source of truth, never overwrite. */
 export declare function seedScanScheme(input: ScanSchemeInput): Promise<boolean>;
 export declare function seedScanRule(input: ScanRuleInput): Promise<boolean>;
+/**
+ * Apply a scheme declaration at startup (code is source of truth). Same
+ * validation as the upsert; the IS DISTINCT FROM guard makes an unchanged
+ * declaration a zero-row no-op.
+ */
+export declare function applyScanScheme(input: ScanSchemeInput): Promise<'applied' | 'unchanged'>;
+/** Apply a rule declaration at startup (code is source of truth). */
+export declare function applyScanRule(input: ScanRuleInput): Promise<'applied' | 'unchanged'>;

package/build/services/scan-code/write.js

@@ -6,6 +6,8 @@ exports.upsertScanRule = upsertScanRule;
 exports.deleteScanRule = deleteScanRule;
 exports.seedScanScheme = seedScanScheme;
 exports.seedScanRule = seedScanRule;
+exports.applyScanScheme = applyScanScheme;
+exports.applyScanRule = applyScanRule;
 const db_1 = require("../../lib/db");
 const types_1 = require("../../types");
 const sql_1 = require("./sql");
@@ -55,7 +57,8 @@ async function deleteScanScheme(version) {
     const { rowCount } = await (0, db_1.getPool)().query(sql_1.DELETE_SCHEME, [version]);
     return (rowCount ?? 0) > 0;
 }
-async function upsertScanRule(input) {
+/** Shared rule-input validation — the upsert and startup-apply paths enforce the same contract. */
+async function assertValidRuleInput(input) {
     if (!/^[0-9]$/.test(input.category)) {
         throw new Error('category must be a single digit (0-9)');
     }
@@ -65,6 +68,9 @@ async function upsertScanRule(input) {
     if (input.steps.length === 0 && !input.fallback?.markdown && !input.fallback?.route) {
         throw new Error('a rule needs at least one step or a fallback');
     }
+}
+async function upsertScanRule(input) {
+    await assertValidRuleInput(input);
     const { rows } = await (0, db_1.getPool)().query(sql_1.UPSERT_ACTION, ruleParams(input));
     return rows[0];
 }
@@ -83,3 +89,19 @@ async function seedScanRule(input) {
     const { rowCount } = await (0, db_1.getPool)().query(sql_1.SEED_ACTION, ruleParams(input));
     return (rowCount ?? 0) > 0;
 }
+/**
+ * Apply a scheme declaration at startup (code is source of truth). Same
+ * validation as the upsert; the IS DISTINCT FROM guard makes an unchanged
+ * declaration a zero-row no-op.
+ */
+async function applyScanScheme(input) {
+    (0, validate_1.assertValidScheme)(input);
+    const { rowCount } = await (0, db_1.getPool)().query(sql_1.APPLY_SCHEME, schemeParams(input));
+    return (rowCount ?? 0) > 0 ? 'applied' : 'unchanged';
+}
+/** Apply a rule declaration at startup (code is source of truth). */
+async function applyScanRule(input) {
+    await assertValidRuleInput(input);
+    const { rowCount } = await (0, db_1.getPool)().query(sql_1.APPLY_ACTION, ruleParams(input));
+    return (rowCount ?? 0) > 0 ? 'applied' : 'unchanged';
+}

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>;