@hotmeshio/long-tail 0.13.0 → 0.13.1

package/build/api/auth-sso.d.ts

@@ -1,12 +1,15 @@
-import type { Request } from 'express';
+import type { Request, Response } from 'express';
 import type { LTApiResult } from '../types/sdk';
 /**
  * Exchange host authentication for a Long Tail JWT.
  *
- * Calls `sso.resolve(req)` to extract the host identity, JIT provisions
+ * Calls `sso.resolve(req, res)` to extract the host identity, JIT provisions
  * the user in `lt_users`, and returns a signed JWT the dashboard can
  * store for subsequent API calls.
  *
  * No request body required — the host's cookies/headers carry the auth.
+ * `res` gives cookie-owning hosts the response handle at the exchange
+ * boundary (login and every keepalive beat) to set/refresh their session
+ * cookie — headers only; the route writes the response body.
  */
-export declare function exchangeSSO(req: Request): Promise<LTApiResult>;
+export declare function exchangeSSO(req: Request, res?: Response): Promise<LTApiResult>;

package/build/api/auth-sso.js

@@ -7,19 +7,22 @@ const auth_1 = require("../modules/auth");
 /**
  * Exchange host authentication for a Long Tail JWT.
  *
- * Calls `sso.resolve(req)` to extract the host identity, JIT provisions
+ * Calls `sso.resolve(req, res)` to extract the host identity, JIT provisions
  * the user in `lt_users`, and returns a signed JWT the dashboard can
  * store for subsequent API calls.
  *
  * No request body required — the host's cookies/headers carry the auth.
+ * `res` gives cookie-owning hosts the response handle at the exchange
+ * boundary (login and every keepalive beat) to set/refresh their session
+ * cookie — headers only; the route writes the response body.
  */
-async function exchangeSSO(req) {
+async function exchangeSSO(req, res) {
     try {
         const ssoConfig = (0, sso_1.getSSOConfig)();
         if (!ssoConfig) {
             return { status: 404, error: 'SSO not configured' };
         }
-        const identity = await ssoConfig.resolve(req);
+        const identity = await ssoConfig.resolve(req, res);
         if (!identity) {
             return { status: 401, error: 'Host authentication required' };
         }

package/build/modules/auth.js

@@ -43,6 +43,7 @@ exports.signToken = signToken;
 const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
 const config_1 = require("./config");
 const sso_1 = require("./sso");
+const logger_1 = require("../lib/logger");
 const user_1 = require("../services/user");
 const sso_provision_1 = require("../services/user/sso-provision");
 const bot_api_key_1 = require("../services/auth/bot-api-key");
@@ -156,7 +157,10 @@ const requireAuth = async (req, res, next) => {
         const mw = _authMiddleware || createAuthMiddleware(new JwtAuthAdapter());
         return mw(req, res, next);
     }
-    // SSO fallback: no Bearer, but host may have authenticated via cookies/headers
+    // SSO fallback: no Bearer, but host may have authenticated via cookies/headers.
+    // `res` is deliberately NOT passed to resolve here: this path runs on every
+    // cookie-bearing request, and ambient API traffic must never slide the host
+    // session — only the explicit exchange (login + gated keepalive beat) does.
     const ssoConfig = (0, sso_1.getSSOConfig)();
     if (ssoConfig) {
         try {
@@ -177,8 +181,10 @@ const requireAuth = async (req, res, next) => {
                 return next();
             }
         }
-        catch {
-            // SSO resolve failed — fall through to 401
+        catch (err) {
+            // SSO resolve failed — fall through to 401, but leave a trace so host
+            // resolve errors are diagnosable.
+            logger_1.loggerRegistry.debug(`[long-tail] sso resolve failed on auth fallback: ${err?.message}`);
         }
     }
     // No Bearer, no SSO — delegate to standard middleware (returns 401)

package/build/routes/auth-sso.js

@@ -45,7 +45,12 @@ const router = (0, express_1.Router)();
  * login form with a transparent token exchange.
  */
 router.post('/sso', async (req, res) => {
-    const result = await api.exchangeSSO(req);
+    const result = await api.exchangeSSO(req, res);
+    // A host's resolve may only set headers on `res`; if one violates the
+    // contract and writes the response, degrade to a skipped beat instead of
+    // a headers-after-send crash.
+    if (res.headersSent)
+        return;
     res.status(result.status).json(result.data ?? { error: result.error });
 });
 exports.default = router;

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/start/workers.js

@@ -472,6 +472,58 @@ async function startWorkers(startConfig, workers, builtinMcpServerFactories) {
             (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).
     const { CallbackEventAdapter } = await Promise.resolve().then(() => __importStar(require('../lib/events/callback')));

package/build/types/auth.d.ts

@@ -1,4 +1,4 @@
-import type { Request } from 'express';
+import type { Request, Response } from 'express';
 /**
  * The identity payload extracted from an authenticated request.
  * All auth adapters must return this shape.
@@ -91,8 +91,17 @@ export interface LTSSOConfig {
     /** Extract user identity from the host's authenticated request.
      *  Return `null` if the request is not authenticated by the host.
      *  The `req` object carries cookies, headers, and any properties
-     *  attached by upstream middleware (e.g., `req.user`). */
-    resolve: (req: Request) => Promise<SSOIdentity | null> | (SSOIdentity | null);
+     *  attached by upstream middleware (e.g., `req.user`).
+     *
+     *  `res` is defined only during the explicit SSO exchange
+     *  (`POST /api/auth/sso` — the login exchange and every keepalive beat).
+     *  Hosts that own their session cookie set/refresh it here: headers only —
+     *  never write the status or body; the exchange route writes the response
+     *  after `resolve` returns. `res` is deliberately absent on the per-request
+     *  auth fallback, so ambient cookie-bearing API traffic (prefetches,
+     *  background fetches) never slides the host session — only the login
+     *  exchange and the visibility/idle-gated keepalive beat do. */
+    resolve: (req: Request, res?: Response) => Promise<SSOIdentity | null> | (SSOIdentity | null);
     /** Map host role names to LT role names.
      *  Key = host role, value = LT role name.
      *  A configured map is the COMPLETE contract: an unmapped host role means
@@ -114,10 +123,15 @@ export interface LTSSOConfig {
     /**
      * Session keepalive: while the dashboard is open and visible, the SPA
      * re-runs the credentialed SSO exchange (`POST /api/auth/sso`, host cookies
-     * included) every `keepaliveSeconds`, keeping a short-lived sliding host
-     * session warm exactly the way host-app navigation does. Each beat re-runs
-     * `resolve`, so a host that revokes access cuts the dashboard off at the
-     * next beat. 0/omitted = no keepalive. Values under 15s are clamped to 15s.
+     * included) every `keepaliveSeconds`. Each beat re-runs `resolve`, so a
+     * host that revokes access cuts the dashboard off at the next beat.
+     * 0/omitted = no keepalive. Values under 15s are clamped to 15s.
+     *
+     * Hosts whose middleware slides the session on any request get the sliding
+     * effect from the beat automatically. Hosts that mint the session cookie in
+     * their own login flow re-mint it inside `resolve` via the `res` parameter.
+     * Either way, pair a sliding TTL with an absolute session max-age — a
+     * sliding-only session is otherwise extendable indefinitely.
      */
     keepaliveSeconds?: number;
     /**

package/build/types/index.d.ts

@@ -17,7 +17,7 @@ export type { LTLoggerAdapter, } from './logger';
 export type { LTMaintenanceRule, LTMaintenanceConfig, } from './maintenance';
 export type { LTExportField, LTExportOptions, LTTimelineEntry, LTTransitionEntry, LTWorkflowExport, } from './export';
 export type { WorkflowExecution, WorkflowExecutionEvent, WorkflowExecutionStatus, WorkflowExecutionSummary, WorkflowEventType, WorkflowEventCategory, WorkflowEventAttributes, ExecutionExportOptions, ExportMode, ActivityDetail, JobExport, } from './export';
-export type { LTStartConfig, LTInstance, LTWorkerConfig, LTMcpServerConfig, LTAgentConfig, LTTopicConfig, LTRoleConfig, } from './startup';
+export type { LTStartConfig, LTInstance, LTWorkerConfig, LTMcpServerConfig, LTAgentConfig, LTTopicConfig, LTRoleConfig, LTScanSchemeConfig, LTScanRuleConfig, } from './startup';
 export type { LTMcpTransportType, LTMcpServerRecord, LTMcpServerStatus, LTMcpToolManifest, LTMcpAdapter, } from './mcp';
 export type { ResolutionContext, ResolutionDirective, LTEscalationStrategy, } from './escalation-strategy';
 export type { WorkflowCandidate, } from './discovery';

package/build/types/startup.d.ts

@@ -1,5 +1,6 @@
 import type { LoggerOptions } from 'pino';
 import type { LTAuthAdapter, LTSSOConfig } from './auth';
+import type { ScanEncoding, ScanSchemeKind, ScanStep, ScanRuleFallback } from './scan-code';
 import type { LTOAuthStartConfig } from './oauth';
 import type { LTTelemetryAdapter } from './telemetry';
 import type { LTEventAdapter } from './events';
@@ -211,6 +212,50 @@ export interface LTRoleConfig {
      */
     reset?: boolean;
 }
+/**
+ * One rule (category) of a declared scan scheme. Categories are single
+ * digits; a rule needs at least one step or a fallback.
+ */
+export interface LTScanRuleConfig {
+    /** Single digit '0'-'9'. */
+    category: string;
+    name: string;
+    steps: ScanStep[];
+    fallback?: ScanRuleFallback;
+    /** Shown when the scan arrives with no primed work surface. */
+    notPrimed?: ScanRuleFallback;
+    enabled?: boolean;
+}
+/**
+ * Declarative scan scheme registration — the scheme and its rules are one
+ * ownership unit, owned per `configSource` (overridable per entry with
+ * `reset`). Code-owned schemes are compared and applied on every boot;
+ * db-owned schemes are insert-if-absent.
+ */
+export interface LTScanSchemeConfig {
+    /** Scheme version prefix, 10-99. The scheme's identity. */
+    version: number;
+    name: string;
+    description?: string | null;
+    /** The escalation metadata facet a scanned target resolves against. */
+    target_facet: string;
+    encoding?: ScanEncoding;
+    delimiter?: string;
+    target_length?: number | null;
+    /** 'action' (default) or 'identity' (badge grants). */
+    kind?: ScanSchemeKind;
+    grant_ttl_seconds?: number | null;
+    grant_max_uses?: number;
+    enabled?: boolean;
+    /** The scheme's rules, one per category. */
+    rules?: LTScanRuleConfig[];
+    /**
+     * Per-entry ownership override for the scheme AND its rules. `true` →
+     * compared and applied on every boot; `false` → the DB owns the rows after
+     * first insert. Omitted → follows `configSource`.
+     */
+    reset?: boolean;
+}
 /**
  * Declarative graph (YAML/DAG) workflow registered at startup — the graph-form
  * peer of a `workers` entry (which registers a procedural workflow). Hand-author
@@ -469,6 +514,13 @@ export interface LTStartConfig {
      * escalation targets, and ops dials, owned per `configSource`.
      */
     roles?: LTRoleConfig[];
+    /**
+     * Declarative scan schemes (with their rules), owned per `configSource` /
+     * per-entry `reset`. Declaring schemes states intent — the pass runs
+     * whether or not the dashboard scan affordances (`features.scanCodes`) are
+     * enabled.
+     */
+    scanSchemes?: LTScanSchemeConfig[];
     /** Declarative topic catalog entries, owned per `configSource` / per-entry `reset`. */
     topics?: LTTopicConfig[];
     /** Declarative agent configurations, owned per `configSource` / per-entry `reset`. */

package/docs/auth.md

@@ -231,9 +231,34 @@ Response 200:
 }
 ```
 
+### Host Session on the Exchange
+
+The exchange is the session boundary between the host and Long Tail, and `resolve` receives the response handle there: `resolve(req, res)`. Hosts that own their session cookie set or refresh it inside `resolve` — headers only; Long Tail writes the response status and body after `resolve` returns.
+
+```typescript
+auth: {
+  sso: {
+    keepaliveSeconds: 300,
+    resolve: (req, res) => {
+      const session = validateHostCookie(req);
+      if (!session) return null;
+      // Slide the host session on every exchange — login and each keepalive beat.
+      res?.setHeader('Set-Cookie', mintHostCookie(session));
+      return { externalId: session.userId, roles: session.roles };
+    },
+  },
+},
+```
+
+With `keepaliveSeconds` set, the dashboard re-runs the exchange on a visibility- and idle-gated interval, so an active operator's host session slides exactly as it would under host-app navigation — hosts whose middleware slides on any request get this automatically, and cookie-minting hosts re-mint via `res`. Pair a sliding TTL with an absolute session max-age: a sliding-only session is otherwise extendable indefinitely.
+
+A resolve that slides the session makes this endpoint a session-refresh surface — give it the same CSRF posture as your own refresh route. `SameSite=Lax` or `Strict` session cookies cover it (cross-site POSTs carry no cookie); a host running `SameSite=None` should verify `Origin` or `Sec-Fetch-Site` inside `resolve` before sliding.
+
+`res` is present only on the explicit exchange (`POST /api/auth/sso`). The per-request fallback below calls `resolve(req)` without it, so ambient cookie-bearing API traffic — prefetches, background fetches — never slides the host session.
+
 ### requireAuth Fallback
 
-When SSO is configured and a request arrives without a Bearer token, `requireAuth` calls `sso.resolve(req)` as a fallback. This allows direct API calls from the host backend (which forward cookies but not Bearer tokens) to authenticate without an explicit exchange. The dashboard always uses Bearer after the initial exchange.
+When SSO is configured and a request arrives without a Bearer token, `requireAuth` calls `sso.resolve(req)` as a fallback. This allows direct API calls from the host backend (which forward cookies but not Bearer tokens) to authenticate without an explicit exchange. The dashboard always uses Bearer after the initial exchange. The fallback never passes `res` — session sliding belongs exclusively to the exchange.
 
 ### Role Mapping
 

package/docs/code-owned-configuration.md

@@ -63,6 +63,7 @@ The domain dictionary's override lives beside its path:
 | MCP servers | `mcp.serverFactories[].config` | description, tags, category, compile hints, credential providers | tool manifest, connection status |
 | Agents | `agents[]` | description, status, goals, rules, domain, schedules | capabilities, metadata, run history |
 | Agent subscriptions | `agents[].subscriptions` | reaction fields on (agent, topic) | `enabled` — the admin kill-switch |
+| Scan schemes | `scanSchemes[]` | whole scheme + its rules (one ownership unit; `enabled` is declarative here) | — |
 | Domain dictionary | `mcp.domainDictionaryPath` | whole document (version bumps once per change) | — |
 | Graph workflows | `graphWorkflows[]` | always compare-and-apply: description/schema sync, redeploy on YAML version bump | run history |
 
@@ -105,6 +106,32 @@ render keep working while new escalations pick up the new shape. Version
 lineage only grows — an apply never rewinds or rewrites an existing version.
 `list_schema` versions independently, exactly as it does from the dashboard.
 
+## Scan schemes: scheme + rules as one unit
+
+A scan scheme and its rules declare together — a rule cannot exist without its
+scheme, so the pair is the ownership unit and one `reset` covers both:
+
+```typescript
+scanSchemes: [
+  {
+    version: 12,
+    name: 'Serial locate',
+    target_facet: 'serialNumber',
+    encoding: 'fixed',
+    target_length: 8,
+    rules: [
+      { category: '1', name: 'Locate', steps: [{ verb: 'show-detail' }] },
+    ],
+  },
+],
+```
+
+The scheme applies before its rules so rule validation sees the scheme's kind.
+Rules present in the database but absent from a code-owned scheme's
+declaration are reported as `version/category` orphans. The pass runs whether
+or not the dashboard scan affordances (`features.scanCodes`) are enabled —
+declaring schemes states intent.
+
 ## The boot report
 
 Each surface logs one line summarizing its pass:

package/docs/scan-codes.md

@@ -360,6 +360,30 @@ The same CRUD rides `PUT/GET/DELETE /api/scan-codes/schemes/:version[/actions/:c
 rules fail the write with the exact problem — an `escalate` step names its
 `targetRole`, a `resolve` step carries its payload.
 
+## Declaring schemes in code
+
+Schemes and their rules declare on `LTStartConfig.scanSchemes` and follow the
+[code-owned configuration](code-owned-configuration.md) contract: under
+`configSource: 'code'` a changed scheme or rule in code is live after the next
+boot on every environment; under `'db'` (the default) the declaration seeds
+once and the admin surfaces own it afterward. Per-entry `reset` overrides the
+dial in either direction, covering the scheme and its rules together.
+
+```typescript
+scanSchemes: [
+  {
+    version: 12,
+    name: 'Serial locate',
+    target_facet: 'serialNumber',
+    encoding: 'fixed',
+    target_length: 8,
+    rules: [
+      { category: '1', name: 'Locate', steps: [{ verb: 'show-detail' }] },
+    ],
+  },
+],
+```
+
 ## The printer demo
 
 The example seed (`examples/seed-scan-codes.ts`) configures scheme 10 over

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/long-tail",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "Long Tail Workflows — Durable AI workflows with human-in-the-loop escalation. Powered by PostgreSQL.",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",