@hotmeshio/long-tail 0.12.1 → 0.13.1

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');
     }
 }

package/build/start/workers.js

@@ -50,6 +50,7 @@ const cron_1 = require("../services/cron");
 const mcp_1 = require("../services/mcp");
 const yamlWorkflowWorkers = __importStar(require("../services/yaml-workflow/workers"));
 const migrate_1 = require("../lib/db/migrate");
+const apply_report_1 = require("./apply-report");
 /**
  * Create a named no-op workflow function for readonly/observer workers.
  * The function name is used by `registerWorker` for discovery.
@@ -116,6 +117,54 @@ async function startWorkers(startConfig, workers, builtinMcpServerFactories) {
     // Seed MCP service account (idempotent)
     const { seedMcpServiceAccount } = await Promise.resolve().then(() => __importStar(require('../services/mcp/seed-service-account')));
     await seedMcpServiceAccount();
+    // Who owns declared configuration after first boot ('db' = insert-if-absent).
+    const configSource = startConfig.configSource ?? 'db';
+    const codeOwnedBoot = configSource === 'code';
+    // Register declared roles (every container — roles are independent of workers).
+    if (startConfig.roles?.length) {
+        const { applyRoleConfig, listConfiguredRoles } = await Promise.resolve().then(() => __importStar(require('../services/role/seed')));
+        const roleReport = (0, apply_report_1.newSurfaceReport)();
+        await (0, apply_report_1.withConfigLock)(async () => {
+            for (const roleCfg of startConfig.roles) {
+                try {
+                    const outcome = await applyRoleConfig(roleCfg, (0, apply_report_1.ownedByCode)(roleCfg.reset, configSource));
+                    (0, apply_report_1.recordOutcome)(roleReport, roleCfg.role, outcome);
+                    if (outcome === 'applied')
+                        logger_1.loggerRegistry.info(`[long-tail] role applied: ${roleCfg.role}`);
+                }
+                catch (err) {
+                    logger_1.loggerRegistry.warn(`[long-tail] role apply failed for ${roleCfg.role}: ${err.message}`);
+                }
+            }
+        });
+        if (codeOwnedBoot && !startConfig.examples) {
+            // Orphans = configured roles (title or form schema set) neither declared
+            // here nor referenced by a declared workflow profile. Bare FK rows and
+            // membership-only roles never count. Skipped under examples — the demo
+            // seeders own their roles.
+            const declared = new Set(['reviewer', 'superadmin', 'system']);
+            for (const r of startConfig.roles) {
+                declared.add(r.role);
+                if (r.parent_role)
+                    declared.add(r.parent_role);
+                for (const t of r.escalation_targets ?? [])
+                    declared.add(t);
+                for (const u of r.upstream_roles ?? [])
+                    declared.add(u);
+            }
+            for (const w of workers) {
+                if (!w.config)
+                    continue;
+                declared.add(w.config.defaultRole ?? 'reviewer');
+                for (const role of [...(w.config.roles ?? []), ...(w.config.invocationRoles ?? [])]) {
+                    declared.add(role);
+                }
+            }
+            roleReport.orphans = (await listConfiguredRoles()).filter((r) => !declared.has(r));
+        }
+        if (codeOwnedBoot)
+            (0, apply_report_1.logSurfaceReport)('roles', roleReport);
+    }
     const connection = buildConnection();
     // Readonly mode: all user-provided workers are observers — skip crons, triggers, and agent seeding.
     // System workers (mcpQuery, etc.) are always added by collectWorkers, so check the original config.
@@ -160,16 +209,19 @@ async function startWorkers(startConfig, workers, builtinMcpServerFactories) {
             (0, registry_1.registerWorker)(w.workflow.name, w.taskQueue);
         }
         logger_1.loggerRegistry.info(`[long-tail] workers started on queues: ${workers.map((w) => w.taskQueue).join(', ')}`);
-        // Seed workflow configs (insert-if-absent — DB is source of truth)
+        // Register workflow configs — ownership per configSource / per-entry reset.
+        // Code-owned profiles are diffed and applied; db-owned profiles keep the
+        // insert-if-absent contract (DB is source of truth after first boot).
         const workersWithConfig = workers.filter((w) => w.config);
         if (workersWithConfig.length) {
-            const { seedWorkflowConfig } = await Promise.resolve().then(() => __importStar(require('../services/config/write')));
+            const { seedWorkflowConfig, applyWorkflowConfig } = await Promise.resolve().then(() => __importStar(require('../services/config/write')));
             const { ltConfig } = await Promise.resolve().then(() => __importStar(require('../modules/ltconfig')));
-            for (const w of workersWithConfig) {
-                const workflowType = w.workflow.name;
-                const c = w.config;
-                try {
-                    const inserted = await seedWorkflowConfig({
+            const wfReport = (0, apply_report_1.newSurfaceReport)();
+            await (0, apply_report_1.withConfigLock)(async () => {
+                for (const w of workersWithConfig) {
+                    const workflowType = w.workflow.name;
+                    const c = w.config;
+                    const declaration = {
                         workflow_type: workflowType,
                         task_queue: w.taskQueue,
                         invocable: c.invocable ?? false,
@@ -184,13 +236,33 @@ async function startWorkers(startConfig, workers, builtinMcpServerFactories) {
                         resolver_schema: c.resolverSchema ?? null,
                         cron_schedule: c.cronSchedule ?? null,
                         execute_as: c.executeAs ?? null,
-                    });
-                    if (inserted)
-                        logger_1.loggerRegistry.info(`[long-tail] config seeded: ${workflowType}`);
-                }
-                catch (err) {
-                    logger_1.loggerRegistry.warn(`[long-tail] config seed failed for ${workflowType}: ${err.message}`);
+                    };
+                    try {
+                        if ((0, apply_report_1.ownedByCode)(c.reset, configSource)) {
+                            const outcome = await applyWorkflowConfig(declaration);
+                            (0, apply_report_1.recordOutcome)(wfReport, workflowType, outcome);
+                            if (outcome === 'applied')
+                                logger_1.loggerRegistry.info(`[long-tail] config applied: ${workflowType}`);
+                        }
+                        else {
+                            const inserted = await seedWorkflowConfig(declaration);
+                            (0, apply_report_1.recordOutcome)(wfReport, workflowType, 'db-owned');
+                            if (inserted)
+                                logger_1.loggerRegistry.info(`[long-tail] config seeded: ${workflowType}`);
+                        }
+                    }
+                    catch (err) {
+                        logger_1.loggerRegistry.warn(`[long-tail] config seed failed for ${workflowType}: ${err.message}`);
+                    }
                 }
+            });
+            if (codeOwnedBoot) {
+                const { listWorkflowConfigs } = await Promise.resolve().then(() => __importStar(require('../services/config/read')));
+                const registered = new Set(workers.map((w) => w.workflow.name));
+                wfReport.orphans = (await listWorkflowConfigs())
+                    .map((cfg) => cfg.workflow_type)
+                    .filter((t) => !registered.has(t));
+                (0, apply_report_1.logSurfaceReport)('workflows', wfReport);
             }
             ltConfig.invalidate();
         }
@@ -211,7 +283,7 @@ async function startWorkers(startConfig, workers, builtinMcpServerFactories) {
         // Register MCP server factories: built-in (from system/) + user-provided
         // Both system and user factories can carry inline config for DB seeding.
         const { registerBuiltinServer } = await Promise.resolve().then(() => __importStar(require('../services/mcp/client')));
-        const { seedMcpServer, cleanStaleBuiltinServers } = await Promise.resolve().then(() => __importStar(require('../services/mcp/db')));
+        const { seedMcpServer, applyMcpServer, cleanStaleBuiltinServers } = await Promise.resolve().then(() => __importStar(require('../services/mcp/db')));
         const userFactories = startConfig.mcp?.serverFactories ?? {};
         // Resolve user factories — plain function or { factory, config }
         const resolvedUserFactories = {};
@@ -236,19 +308,33 @@ async function startWorkers(startConfig, workers, builtinMcpServerFactories) {
         // Set exposure config for the /mcp endpoint
         const { setExposureConfig } = await Promise.resolve().then(() => __importStar(require('../services/mcp/exposure')));
         setExposureConfig(startConfig.mcp?.exposure);
-        // 2. Seed MCP server configs (insert-if-absent + drift log)
+        // 2. Register MCP server configs — ownership per configSource / per-entry
+        // reset. Code-owned entries apply the config fields (runtime state stays
+        // untouched); db-owned entries keep insert-if-absent + drift log.
+        const mcpReport = (0, apply_report_1.newSurfaceReport)();
         for (const [name, entry] of Object.entries(allFactories)) {
             if (entry.config) {
                 try {
-                    const inserted = await seedMcpServer({ name, ...entry.config });
-                    if (inserted)
-                        logger_1.loggerRegistry.info(`[long-tail] MCP server seeded: ${name}`);
+                    if ((0, apply_report_1.ownedByCode)(entry.config.reset, configSource)) {
+                        const outcome = await applyMcpServer({ name, ...entry.config });
+                        (0, apply_report_1.recordOutcome)(mcpReport, name, outcome);
+                        if (outcome === 'applied')
+                            logger_1.loggerRegistry.info(`[long-tail] MCP server applied: ${name}`);
+                    }
+                    else {
+                        const inserted = await seedMcpServer({ name, ...entry.config });
+                        (0, apply_report_1.recordOutcome)(mcpReport, name, 'db-owned');
+                        if (inserted)
+                            logger_1.loggerRegistry.info(`[long-tail] MCP server seeded: ${name}`);
+                    }
                 }
                 catch (err) {
                     logger_1.loggerRegistry.warn(`[long-tail] MCP server seed failed for ${name}: ${err.message}`);
                 }
             }
         }
+        if (codeOwnedBoot)
+            (0, apply_report_1.logSurfaceReport)('mcp-servers', mcpReport);
         // 3. Clean stale builtin servers no longer in factory list
         await cleanStaleBuiltinServers(Object.keys(allFactories));
         // Seed static graph (YAML/DAG) workflows — the graph-form peer of `workers`.
@@ -268,16 +354,34 @@ async function startWorkers(startConfig, workers, builtinMcpServerFactories) {
         // Register workers for active YAML (deterministic) workflows
         await yamlWorkflowWorkers.registerAllActiveWorkers();
     }
-    // Seed topic catalog (system topics + user-declared topics)
+    // Seed topic catalog (system topics + user-declared topics). Declared
+    // topics follow configSource; per-entry `reset` overrides in either direction.
     const { seedSystemTopics, seedConfigTopics } = await Promise.resolve().then(() => __importStar(require('../services/topics/system-topics')));
     await seedSystemTopics();
     if (startConfig.topics?.length)
-        await seedConfigTopics(startConfig.topics);
-    // Seed the domain dictionary (every container, workers or not) — insert-if-
-    // absent with warn-only reference validation; the DB row is runtime truth.
+        await seedConfigTopics(startConfig.topics, codeOwnedBoot);
+    if (codeOwnedBoot) {
+        const { listConfigTopicNames } = await Promise.resolve().then(() => __importStar(require('../services/topics')));
+        const declaredTopics = new Set((startConfig.topics ?? []).map((t) => t.topic));
+        if (startConfig.examples) {
+            try {
+                const { EXAMPLE_TOPICS } = await Promise.resolve().then(() => __importStar(require('../examples')));
+                for (const t of EXAMPLE_TOPICS ?? [])
+                    declaredTopics.add(t.topic);
+            }
+            catch { /* examples not available */ }
+        }
+        const orphanTopics = (await listConfigTopicNames()).filter((t) => !declaredTopics.has(t));
+        if (orphanTopics.length) {
+            logger_1.loggerRegistry.warn(`[long-tail] config apply (topics): orphans: [${orphanTopics.join(', ')}]`);
+        }
+    }
+    // Seed the domain dictionary (every container, workers or not). Db-owned:
+    // insert-if-absent, the DB row is runtime truth. Code-owned: the file is
+    // compared and applied, bumping the version once per changed document.
     if (startConfig.mcp?.domainDictionaryPath) {
         const { seedDomainDictionary } = await Promise.resolve().then(() => __importStar(require('../services/domain')));
-        await seedDomainDictionary(startConfig.mcp.domainDictionaryPath);
+        await seedDomainDictionary(startConfig.mcp.domainDictionaryPath, startConfig.mcp.domainDictionaryReset ?? codeOwnedBoot);
     }
     // Seed example topics when examples are enabled
     if (startConfig.examples) {
@@ -294,9 +398,11 @@ async function startWorkers(startConfig, workers, builtinMcpServerFactories) {
         : [];
     const allAgentConfigs = [...(startConfig.agents ?? []), ...systemAgents];
     if (allAgentConfigs.length > 0) {
-        const { seedAgent } = await Promise.resolve().then(() => __importStar(require('../services/agent')));
-        const { seedSubscription } = await Promise.resolve().then(() => __importStar(require('../services/agent/subscriptions')));
+        const { seedAgent, applyAgent, listAgentIds } = await Promise.resolve().then(() => __importStar(require('../services/agent')));
+        const { seedSubscription, applySubscription, listSubscriptions } = await Promise.resolve().then(() => __importStar(require('../services/agent/subscriptions')));
+        const agentReport = (0, apply_report_1.newSurfaceReport)();
         for (const agentConfig of allAgentConfigs) {
+            const codeOwned = (0, apply_report_1.ownedByCode)(agentConfig.reset, configSource);
             try {
                 // Map flat schedules into behaviors.schedules for DB storage
                 const behaviors = {};
@@ -304,7 +410,7 @@ async function startWorkers(startConfig, workers, builtinMcpServerFactories) {
                     behaviors.schedules = agentConfig.schedules;
                     behaviors.cron = agentConfig.schedules[0].cron;
                 }
-                const inserted = await seedAgent({
+                const declaration = {
                     id: agentConfig.name,
                     description: agentConfig.description,
                     goals: agentConfig.goals,
@@ -313,27 +419,110 @@ async function startWorkers(startConfig, workers, builtinMcpServerFactories) {
                     knowledge_domain: agentConfig.knowledge_domain,
                     behaviors,
                     workflow_type: agentConfig.schedules?.[0]?.workflow_type,
-                });
-                if (inserted)
-                    logger_1.loggerRegistry.info(`[long-tail] agent seeded: ${agentConfig.name}`);
-                // Seed subscriptions for this agent — id IS the name
+                };
+                if (codeOwned) {
+                    const outcome = await applyAgent(declaration);
+                    (0, apply_report_1.recordOutcome)(agentReport, agentConfig.name, outcome);
+                    if (outcome === 'applied')
+                        logger_1.loggerRegistry.info(`[long-tail] agent applied: ${agentConfig.name}`);
+                }
+                else {
+                    const inserted = await seedAgent(declaration);
+                    (0, apply_report_1.recordOutcome)(agentReport, agentConfig.name, 'db-owned');
+                    if (inserted)
+                        logger_1.loggerRegistry.info(`[long-tail] agent seeded: ${agentConfig.name}`);
+                }
+                // Subscriptions for this agent — id IS the name
                 if (agentConfig.subscriptions?.length) {
                     for (const sub of agentConfig.subscriptions) {
                         try {
-                            const subInserted = await seedSubscription(agentConfig.name, sub);
-                            if (subInserted)
-                                logger_1.loggerRegistry.info(`[long-tail] subscription seeded: ${agentConfig.name}/${sub.topic}`);
+                            if (codeOwned) {
+                                const outcome = await applySubscription(agentConfig.name, sub);
+                                if (outcome === 'applied')
+                                    logger_1.loggerRegistry.info(`[long-tail] subscription applied: ${agentConfig.name}/${sub.topic}`);
+                            }
+                            else {
+                                const subInserted = await seedSubscription(agentConfig.name, sub);
+                                if (subInserted)
+                                    logger_1.loggerRegistry.info(`[long-tail] subscription seeded: ${agentConfig.name}/${sub.topic}`);
+                            }
                         }
                         catch (subErr) {
                             logger_1.loggerRegistry.warn(`[long-tail] subscription seed failed: ${agentConfig.name}/${sub.topic}: ${subErr.message}`);
                         }
                     }
                 }
+                // Undeclared subscriptions on a code-owned agent are reported, never
+                // deleted — disabling or removing one stays a deliberate act.
+                if (codeOwned) {
+                    const declaredSubs = new Set((agentConfig.subscriptions ?? []).map((s) => s.topic));
+                    const existingSubs = await listSubscriptions(agentConfig.name);
+                    agentReport.orphans.push(...existingSubs
+                        .filter((s) => !declaredSubs.has(s.topic))
+                        .map((s) => `${agentConfig.name}/${s.topic}`));
+                }
             }
             catch (err) {
                 logger_1.loggerRegistry.warn(`[long-tail] agent seed failed for ${agentConfig.name}: ${err.message}`);
             }
         }
+        if (codeOwnedBoot) {
+            const declaredAgents = new Set(allAgentConfigs.map((a) => a.name));
+            agentReport.orphans.push(...(await listAgentIds()).filter((id) => !declaredAgents.has(id)));
+            (0, apply_report_1.logSurfaceReport)('agents', agentReport);
+        }
+    }
+    // Register declared scan schemes (with their rules) — ownership per
+    // configSource / per-entry reset. A scheme and its rules are one ownership
+    // unit; the scheme applies first so rule validation sees its kind.
+    if (startConfig.scanSchemes?.length) {
+        const { seedScanScheme, seedScanRule, applyScanScheme, applyScanRule, listScanSchemes, listScanRules, } = await Promise.resolve().then(() => __importStar(require('../services/scan-code')));
+        const scanReport = (0, apply_report_1.newSurfaceReport)();
+        for (const scheme of startConfig.scanSchemes) {
+            const codeOwned = (0, apply_report_1.ownedByCode)(scheme.reset, configSource);
+            const { rules, reset: _reset, ...schemeInput } = scheme;
+            try {
+                if (codeOwned) {
+                    let outcome = await applyScanScheme(schemeInput);
+                    for (const rule of rules ?? []) {
+                        const ruleOutcome = await applyScanRule({ scheme_version: scheme.version, ...rule });
+                        if (ruleOutcome === 'applied')
+                            outcome = 'applied';
+                    }
+                    (0, apply_report_1.recordOutcome)(scanReport, `scheme ${scheme.version}`, outcome);
+                    if (outcome === 'applied')
+                        logger_1.loggerRegistry.info(`[long-tail] scan scheme applied: ${scheme.version}`);
+                    // Undeclared rules on a code-owned scheme are reported, never deleted.
+                    const declaredCategories = new Set((rules ?? []).map((r) => r.category));
+                    const existingRules = await listScanRules(scheme.version);
+                    scanReport.orphans.push(...existingRules
+                        .filter((r) => !declaredCategories.has(r.category))
+                        .map((r) => `${scheme.version}/${r.category}`));
+                }
+                else {
+                    const inserted = await seedScanScheme(schemeInput);
+                    for (const rule of rules ?? []) {
+                        await seedScanRule({ scheme_version: scheme.version, ...rule });
+                    }
+                    (0, apply_report_1.recordOutcome)(scanReport, `scheme ${scheme.version}`, 'db-owned');
+                    if (inserted)
+                        logger_1.loggerRegistry.info(`[long-tail] scan scheme seeded: ${scheme.version}`);
+                }
+            }
+            catch (err) {
+                logger_1.loggerRegistry.warn(`[long-tail] scan scheme seed failed for ${scheme.version}: ${err.message}`);
+            }
+        }
+        if (codeOwnedBoot && !startConfig.examples) {
+            // Schemes in the DB not declared here (demo seeds own theirs under examples).
+            const declaredVersions = new Set(startConfig.scanSchemes.map((s) => s.version));
+            scanReport.orphans.push(...(await listScanSchemes())
+                .map((s) => s.version)
+                .filter((v) => !declaredVersions.has(v))
+                .map(String));
+        }
+        if (codeOwnedBoot)
+            (0, apply_report_1.logSurfaceReport)('scan-schemes', scanReport);
     }
     // Register the in-process callback adapter for agent event triggers.
     // Reuse existing instance if already registered (e.g., from SDK createClient).