@hotmeshio/long-tail 0.10.10 → 0.10.13

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

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listScanSchemes = listScanSchemes;
+exports.getScanScheme = getScanScheme;
+exports.listScanRules = listScanRules;
+exports.getScanRule = getScanRule;
+const db_1 = require("../../lib/db");
+const sql_1 = require("./sql");
+function mapScheme(row) {
+    return {
+        version: row.version,
+        name: row.name,
+        description: row.description ?? null,
+        target_facet: row.target_facet,
+        encoding: row.encoding,
+        delimiter: row.delimiter,
+        target_length: row.target_length ?? null,
+        enabled: row.enabled,
+        created_at: row.created_at,
+        updated_at: row.updated_at,
+    };
+}
+function mapRule(row) {
+    return {
+        scheme_version: row.scheme_version,
+        category: row.category,
+        name: row.name,
+        steps: row.steps ?? [],
+        fallback: row.fallback ?? {},
+        enabled: row.enabled,
+        created_at: row.created_at,
+        updated_at: row.updated_at,
+    };
+}
+async function listScanSchemes() {
+    const { rows } = await (0, db_1.getPool)().query(sql_1.LIST_SCHEMES);
+    return rows.map(mapScheme);
+}
+async function getScanScheme(version) {
+    const { rows } = await (0, db_1.getPool)().query(sql_1.GET_SCHEME, [version]);
+    return rows.length ? mapScheme(rows[0]) : null;
+}
+async function listScanRules(schemeVersion) {
+    const { rows } = await (0, db_1.getPool)().query(sql_1.LIST_ACTIONS, [schemeVersion]);
+    return rows.map(mapRule);
+}
+async function getScanRule(schemeVersion, category) {
+    const { rows } = await (0, db_1.getPool)().query(sql_1.GET_ACTION, [schemeVersion, category]);
+    return rows.length ? mapRule(rows[0]) : null;
+}

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

@@ -0,0 +1,10 @@
+export declare const LIST_SCHEMES = "SELECT * FROM lt_config_scan_schemes ORDER BY version";
+export declare const GET_SCHEME = "SELECT * FROM lt_config_scan_schemes WHERE version = $1";
+export declare const LIST_ACTIONS = "SELECT * FROM lt_config_scan_actions WHERE scheme_version = $1 ORDER BY category";
+export declare const GET_ACTION = "SELECT * FROM lt_config_scan_actions WHERE scheme_version = $1 AND category = $2";
+export declare const UPSERT_SCHEME = "INSERT INTO lt_config_scan_schemes\n  (version, name, description, target_facet, encoding, delimiter, target_length, enabled)\nVALUES ($1, $2, $3, $4, $5, $6, $7, $8)\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  enabled = EXCLUDED.enabled\nRETURNING *";
+export declare const DELETE_SCHEME = "DELETE FROM lt_config_scan_schemes WHERE version = $1";
+export declare const UPSERT_ACTION = "INSERT INTO lt_config_scan_actions\n  (scheme_version, category, name, steps, fallback, enabled)\nVALUES ($1, $2, $3, $4, $5, $6)\nON CONFLICT (scheme_version, category) DO UPDATE SET\n  name = EXCLUDED.name,\n  steps = EXCLUDED.steps,\n  fallback = EXCLUDED.fallback,\n  enabled = EXCLUDED.enabled\nRETURNING *";
+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, enabled)\nVALUES ($1, $2, $3, $4, $5, $6, $7, $8)\nON CONFLICT (version) DO NOTHING";
+export declare const SEED_ACTION = "INSERT INTO lt_config_scan_actions\n  (scheme_version, category, name, steps, fallback, enabled)\nVALUES ($1, $2, $3, $4, $5, $6)\nON CONFLICT (scheme_version, category) DO NOTHING";

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

@@ -0,0 +1,57 @@
+"use strict";
+// ------------------------------------------------------------------ //
+// 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.LIST_SCHEMES = `\
+SELECT * FROM lt_config_scan_schemes ORDER BY version`;
+exports.GET_SCHEME = `\
+SELECT * FROM lt_config_scan_schemes WHERE version = $1`;
+exports.LIST_ACTIONS = `\
+SELECT * FROM lt_config_scan_actions WHERE scheme_version = $1 ORDER BY category`;
+exports.GET_ACTION = `\
+SELECT * FROM lt_config_scan_actions WHERE scheme_version = $1 AND category = $2`;
+// ------------------------------------------------------------------ //
+// Write / upsert queries                                             //
+// ------------------------------------------------------------------ //
+exports.UPSERT_SCHEME = `\
+INSERT INTO lt_config_scan_schemes
+  (version, name, description, target_facet, encoding, delimiter, target_length, enabled)
+VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+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,
+  enabled = EXCLUDED.enabled
+RETURNING *`;
+exports.DELETE_SCHEME = `\
+DELETE FROM lt_config_scan_schemes WHERE version = $1`;
+exports.UPSERT_ACTION = `\
+INSERT INTO lt_config_scan_actions
+  (scheme_version, category, name, steps, fallback, enabled)
+VALUES ($1, $2, $3, $4, $5, $6)
+ON CONFLICT (scheme_version, category) DO UPDATE SET
+  name = EXCLUDED.name,
+  steps = EXCLUDED.steps,
+  fallback = EXCLUDED.fallback,
+  enabled = EXCLUDED.enabled
+RETURNING *`;
+exports.DELETE_ACTION = `\
+DELETE FROM lt_config_scan_actions WHERE scheme_version = $1 AND category = $2`;
+// ------------------------------------------------------------------ //
+// Seed (insert-if-absent — used at startup, DB is source of truth)   //
+// ------------------------------------------------------------------ //
+exports.SEED_SCHEME = `\
+INSERT INTO lt_config_scan_schemes
+  (version, name, description, target_facet, encoding, delimiter, target_length, enabled)
+VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+ON CONFLICT (version) DO NOTHING`;
+exports.SEED_ACTION = `\
+INSERT INTO lt_config_scan_actions
+  (scheme_version, category, name, steps, fallback, enabled)
+VALUES ($1, $2, $3, $4, $5, $6)
+ON CONFLICT (scheme_version, category) DO NOTHING`;

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

@@ -0,0 +1,12 @@
+import { type ScanScheme, type ScanStep } from '../../types';
+/**
+ * Reject incoherent scheme config at write time. Throws with the exact
+ * problem — a bad scheme silently misparsing every scan is far worse
+ * than a loud upsert failure.
+ */
+export declare function assertValidScheme(scheme: Partial<ScanScheme>): void;
+/**
+ * Reject incoherent rule steps at write time: a rule that can never
+ * execute its verb must fail the upsert, not the factory-floor scan.
+ */
+export declare function assertValidSteps(steps: ScanStep[]): void;

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

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertValidScheme = assertValidScheme;
+exports.assertValidSteps = assertValidSteps;
+const types_1 = require("../../types");
+const VALID_VERBS = new Set(Object.values(types_1.SCAN_VERBS));
+/**
+ * Reject incoherent scheme config at write time. Throws with the exact
+ * problem — a bad scheme silently misparsing every scan is far worse
+ * than a loud upsert failure.
+ */
+function assertValidScheme(scheme) {
+    if (!Number.isInteger(scheme.version) || scheme.version < 10 || scheme.version > 99) {
+        throw new Error('scheme version must be a two-digit integer between 10 and 99');
+    }
+    if (!scheme.name)
+        throw new Error('scheme name is required');
+    if (!scheme.target_facet)
+        throw new Error('scheme target_facet is required');
+    const encoding = scheme.encoding ?? types_1.SCAN_ENCODINGS.FIXED;
+    if (encoding === types_1.SCAN_ENCODINGS.FIXED) {
+        if (!Number.isInteger(scheme.target_length) || scheme.target_length < 1) {
+            throw new Error('fixed encoding requires a positive integer target_length');
+        }
+    }
+    if (encoding === types_1.SCAN_ENCODINGS.DELIMITED) {
+        const delimiter = scheme.delimiter ?? ':';
+        if (delimiter.length !== 1) {
+            throw new Error('delimited encoding requires a single-character delimiter');
+        }
+        if (/[0-9]/.test(delimiter)) {
+            throw new Error('delimiter must not be a digit');
+        }
+    }
+}
+/**
+ * Reject incoherent rule steps at write time: a rule that can never
+ * execute its verb must fail the upsert, not the factory-floor scan.
+ */
+function assertValidSteps(steps) {
+    if (!Array.isArray(steps))
+        throw new Error('steps must be an array');
+    steps.forEach((step, i) => {
+        const at = `step ${i + 1}`;
+        if (!step || typeof step !== 'object')
+            throw new Error(`${at} must be an object`);
+        if (!VALID_VERBS.has(step.verb)) {
+            throw new Error(`${at}: unknown verb "${step.verb}"`);
+        }
+        if (step.confirm && !types_1.SCAN_MUTATING_VERBS.includes(step.verb)) {
+            throw new Error(`${at}: confirm applies only to mutating verbs`);
+        }
+        if (step.confirm && !step.confirm.prompt) {
+            throw new Error(`${at}: confirm requires a prompt`);
+        }
+        if (step.verb === types_1.SCAN_VERBS.ESCALATE && !step.params?.targetRole) {
+            throw new Error(`${at}: escalate requires params.targetRole`);
+        }
+        if (step.verb === types_1.SCAN_VERBS.RESOLVE && !step.params?.resolverPayload) {
+            throw new Error(`${at}: resolve requires params.resolverPayload`);
+        }
+        if (step.query && step.query.roles && !Array.isArray(step.query.roles)) {
+            throw new Error(`${at}: query.roles must be an array`);
+        }
+        // Claim and cancel lock via claim-by-metadata, whose SQL filter is the
+        // target facet + roles only — extra facet guards would be silently
+        // ignored there, so reject them at write time. (Locate, resolve, and
+        // escalate steps carry facet guards inside their own atomic filters.)
+        const claimLocked = step.verb === types_1.SCAN_VERBS.CLAIM
+            || step.verb === types_1.SCAN_VERBS.CLAIM_SHOW_DETAIL
+            || step.verb === types_1.SCAN_VERBS.CANCEL
+            || (step.verb === types_1.SCAN_VERBS.ESCALATE && step.params?.closeCurrent === 'cancel');
+        if (claimLocked && !step.confirm
+            && step.query?.facets && Object.keys(step.query.facets).length) {
+            throw new Error(`${at}: facet guards are not supported on claim-locked steps (${step.verb})`);
+        }
+    });
+}

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

@@ -0,0 +1,26 @@
+import { type ScanScheme, type ScanRule, type ScanStep, type ScanRuleFallback } from '../../types';
+export interface ScanSchemeInput {
+    version: number;
+    name: string;
+    description?: string | null;
+    target_facet: string;
+    encoding?: ScanScheme['encoding'];
+    delimiter?: string;
+    target_length?: number | null;
+    enabled?: boolean;
+}
+export interface ScanRuleInput {
+    scheme_version: number;
+    category: string;
+    name: string;
+    steps: ScanStep[];
+    fallback?: ScanRuleFallback;
+    enabled?: boolean;
+}
+export declare function upsertScanScheme(input: ScanSchemeInput): Promise<ScanScheme>;
+export declare function deleteScanScheme(version: number): Promise<boolean>;
+export declare function upsertScanRule(input: ScanRuleInput): Promise<ScanRule>;
+export declare function deleteScanRule(schemeVersion: number, category: string): Promise<boolean>;
+/** 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>;

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

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.upsertScanScheme = upsertScanScheme;
+exports.deleteScanScheme = deleteScanScheme;
+exports.upsertScanRule = upsertScanRule;
+exports.deleteScanRule = deleteScanRule;
+exports.seedScanScheme = seedScanScheme;
+exports.seedScanRule = seedScanRule;
+const db_1 = require("../../lib/db");
+const types_1 = require("../../types");
+const sql_1 = require("./sql");
+const validate_1 = require("./validate");
+function schemeParams(input) {
+    return [
+        input.version,
+        input.name,
+        input.description ?? null,
+        input.target_facet,
+        input.encoding ?? types_1.SCAN_ENCODINGS.FIXED,
+        input.delimiter ?? ':',
+        input.target_length ?? null,
+        input.enabled ?? true,
+    ];
+}
+function ruleParams(input) {
+    return [
+        input.scheme_version,
+        input.category,
+        input.name,
+        JSON.stringify(input.steps),
+        JSON.stringify(input.fallback ?? {}),
+        input.enabled ?? true,
+    ];
+}
+async function upsertScanScheme(input) {
+    (0, validate_1.assertValidScheme)(input);
+    const { rows } = await (0, db_1.getPool)().query(sql_1.UPSERT_SCHEME, schemeParams(input));
+    return rows[0];
+}
+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) {
+    if (!/^[0-9]$/.test(input.category)) {
+        throw new Error('category must be a single digit (0-9)');
+    }
+    if (!input.name)
+        throw new Error('rule name is required');
+    (0, validate_1.assertValidSteps)(input.steps);
+    if (input.steps.length === 0 && !input.fallback?.markdown && !input.fallback?.route) {
+        throw new Error('a rule needs at least one step or a fallback');
+    }
+    const { rows } = await (0, db_1.getPool)().query(sql_1.UPSERT_ACTION, ruleParams(input));
+    return rows[0];
+}
+async function deleteScanRule(schemeVersion, category) {
+    const { rowCount } = await (0, db_1.getPool)().query(sql_1.DELETE_ACTION, [schemeVersion, category]);
+    return (rowCount ?? 0) > 0;
+}
+/** Insert-if-absent seeding — DB is the source of truth, never overwrite. */
+async function seedScanScheme(input) {
+    (0, validate_1.assertValidScheme)(input);
+    const { rowCount } = await (0, db_1.getPool)().query(sql_1.SEED_SCHEME, schemeParams(input));
+    return (rowCount ?? 0) > 0;
+}
+async function seedScanRule(input) {
+    (0, validate_1.assertValidSteps)(input.steps);
+    const { rowCount } = await (0, db_1.getPool)().query(sql_1.SEED_ACTION, ruleParams(input));
+    return (rowCount ?? 0) > 0;
+}

package/build/shared/form-validation/index.d.ts

@@ -7,6 +7,7 @@
 export * from './derive-field-label';
 export * from './x-lt-bind';
 export * from './x-lt-help';
+export * from './x-lt-transition';
 export * from './x-lt-show-if';
 export * from './field-validator';
 export * from './validate-resolver-payload';

package/build/shared/form-validation/index.js

@@ -23,6 +23,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./derive-field-label"), exports);
 __exportStar(require("./x-lt-bind"), exports);
 __exportStar(require("./x-lt-help"), exports);
+__exportStar(require("./x-lt-transition"), exports);
 __exportStar(require("./x-lt-show-if"), exports);
 __exportStar(require("./field-validator"), exports);
 __exportStar(require("./validate-resolver-payload"), exports);

package/build/shared/form-validation/x-lt-transition.d.ts

@@ -0,0 +1,47 @@
+/**
+ * x-lt-transition — post-submit hand-off UX. A form_schema may declare, at its
+ * schema root, that submitting one of its escalations should pause on a wait
+ * screen instead of returning to the previous page — because a follow-on
+ * escalation is about to be born assigned to the submitter (a chained hand-off).
+ *
+ *   x-lt-transition                    boolean  — opt in to the wait screen
+ *   x-lt-transition-message            markdown — shown on the wait screen
+ *   x-lt-transition-max-wait-seconds   number   — how long to wait for the
+ *                                        follow-on before running the fallback
+ *                                        query (clamped to a sane range)
+ *
+ * These tokens control ONLY the UX. Navigation to the follow-on is driven by the
+ * engine's born-assigned `claimed` event (assigned_to + parent_id +
+ * assigned_at_creation); the schema carries no navigation target and no metadata
+ * is used.
+ */
+export declare const X_LT_TRANSITION = "x-lt-transition";
+export declare const X_LT_TRANSITION_MESSAGE = "x-lt-transition-message";
+export declare const X_LT_TRANSITION_MAX_WAIT_SECONDS = "x-lt-transition-max-wait-seconds";
+export declare const X_LT_TRANSITION_DONE = "x-lt-transition-done";
+export interface TransitionConfig {
+    /** Markdown shown on the wait screen. */
+    message: string;
+    /** Seconds to wait for the follow-on before the fallback query runs. */
+    maxWaitSeconds: number;
+}
+/**
+ * The schema's transition config, or null when the schema does not opt in.
+ * `x-lt-transition` must be truthy; message and max-wait fall back to defaults.
+ */
+export declare function readTransitionConfig(schema: Record<string, unknown> | null | undefined): TransitionConfig | null;
+/**
+ * Where to go when this step ends without a further hand-off — the terminal
+ * step of a chain (submitting it), or a transition step whose follow-on never
+ * arrives (the wait times out). Independent of `x-lt-transition`, so a terminal
+ * form can declare it without opting into the wait screen.
+ *
+ * The value is an href template using the same `{{domain.path}}` syntax and
+ * routing conventions as `x-lt-href` (see LinkWidget): an internal path
+ * (`/escalations/available?role=…`) navigates in-app; anything else opens
+ * externally. A page reached via a forward transition can't rely on
+ * `history.back()`, so this states the destination explicitly. Returns the raw
+ * template (interpolate it against the escalation context before navigating),
+ * or null when absent.
+ */
+export declare function readTransitionDone(schema: Record<string, unknown> | null | undefined): string | null;

package/build/shared/form-validation/x-lt-transition.js

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * x-lt-transition — post-submit hand-off UX. A form_schema may declare, at its
+ * schema root, that submitting one of its escalations should pause on a wait
+ * screen instead of returning to the previous page — because a follow-on
+ * escalation is about to be born assigned to the submitter (a chained hand-off).
+ *
+ *   x-lt-transition                    boolean  — opt in to the wait screen
+ *   x-lt-transition-message            markdown — shown on the wait screen
+ *   x-lt-transition-max-wait-seconds   number   — how long to wait for the
+ *                                        follow-on before running the fallback
+ *                                        query (clamped to a sane range)
+ *
+ * These tokens control ONLY the UX. Navigation to the follow-on is driven by the
+ * engine's born-assigned `claimed` event (assigned_to + parent_id +
+ * assigned_at_creation); the schema carries no navigation target and no metadata
+ * is used.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.X_LT_TRANSITION_DONE = exports.X_LT_TRANSITION_MAX_WAIT_SECONDS = exports.X_LT_TRANSITION_MESSAGE = exports.X_LT_TRANSITION = void 0;
+exports.readTransitionConfig = readTransitionConfig;
+exports.readTransitionDone = readTransitionDone;
+exports.X_LT_TRANSITION = 'x-lt-transition';
+exports.X_LT_TRANSITION_MESSAGE = 'x-lt-transition-message';
+exports.X_LT_TRANSITION_MAX_WAIT_SECONDS = 'x-lt-transition-max-wait-seconds';
+exports.X_LT_TRANSITION_DONE = 'x-lt-transition-done';
+const DEFAULT_MESSAGE = 'Submitted. Preparing your next step…';
+const DEFAULT_MAX_WAIT_SECONDS = 30;
+const MIN_MAX_WAIT_SECONDS = 5;
+const MAX_MAX_WAIT_SECONDS = 300;
+function clampWaitSeconds(value) {
+    const n = typeof value === 'number' ? value : Number(value);
+    if (!Number.isFinite(n) || n <= 0)
+        return DEFAULT_MAX_WAIT_SECONDS;
+    return Math.min(MAX_MAX_WAIT_SECONDS, Math.max(MIN_MAX_WAIT_SECONDS, Math.round(n)));
+}
+/**
+ * The schema's transition config, or null when the schema does not opt in.
+ * `x-lt-transition` must be truthy; message and max-wait fall back to defaults.
+ */
+function readTransitionConfig(schema) {
+    if (!schema || !schema[exports.X_LT_TRANSITION])
+        return null;
+    const rawMessage = schema[exports.X_LT_TRANSITION_MESSAGE];
+    const message = typeof rawMessage === 'string' && rawMessage.trim().length > 0 ? rawMessage : DEFAULT_MESSAGE;
+    return { message, maxWaitSeconds: clampWaitSeconds(schema[exports.X_LT_TRANSITION_MAX_WAIT_SECONDS]) };
+}
+/**
+ * Where to go when this step ends without a further hand-off — the terminal
+ * step of a chain (submitting it), or a transition step whose follow-on never
+ * arrives (the wait times out). Independent of `x-lt-transition`, so a terminal
+ * form can declare it without opting into the wait screen.
+ *
+ * The value is an href template using the same `{{domain.path}}` syntax and
+ * routing conventions as `x-lt-href` (see LinkWidget): an internal path
+ * (`/escalations/available?role=…`) navigates in-app; anything else opens
+ * externally. A page reached via a forward transition can't rely on
+ * `history.back()`, so this states the destination explicitly. Returns the raw
+ * template (interpolate it against the escalation context before navigating),
+ * or null when absent.
+ */
+function readTransitionDone(schema) {
+    const raw = schema?.[exports.X_LT_TRANSITION_DONE];
+    return typeof raw === 'string' && raw.trim().length > 0 ? raw : null;
+}

package/build/system/mcp-servers/admin/index.d.ts

@@ -21,6 +21,7 @@
  *   topics.ts              — routes/topics.ts
  *   settings.ts            — routes/settings.ts
  *   exports.ts             — routes/exports.ts
+ *   scan-codes.ts          — routes/scan-codes.ts
  *
  * This server replaces three previously separate servers:
  *   - long-tail-db-query (read-only task/escalation/health queries)

package/build/system/mcp-servers/admin/index.js

@@ -26,6 +26,7 @@ exports.stopAdminServer = stopAdminServer;
  *   topics.ts              — routes/topics.ts
  *   settings.ts            — routes/settings.ts
  *   exports.ts             — routes/exports.ts
+ *   scan-codes.ts          — routes/scan-codes.ts
  *
  * This server replaces three previously separate servers:
  *   - long-tail-db-query (read-only task/escalation/health queries)
@@ -58,7 +59,8 @@ const exports_1 = require("./exports");
 const overview_1 = require("./overview");
 const diagnostics_1 = require("./diagnostics");
 const ortho_1 = require("./ortho");
-const TOOL_COUNT = 100;
+const scan_codes_1 = require("./scan-codes");
+const TOOL_COUNT = 105;
 let server = null;
 async function createAdminServer(options) {
     if (server && !options?.fresh)
@@ -88,7 +90,8 @@ async function createAdminServer(options) {
     (0, overview_1.registerOverviewTools)(instance); //  1 tool
     (0, diagnostics_1.registerDiagnosticsTools)(instance); //  3 tools
     (0, ortho_1.registerOrthoTools)(instance); //  4 tools
-    // Total: 100
+    (0, scan_codes_1.registerScanCodeTools)(instance); //  5 tools (scan schemes + rules + execute)
+    // Total: 105
     logger_1.loggerRegistry.info(`[lt-mcp:admin] ${name} ready (${TOOL_COUNT} tools registered)`);
     return instance;
 }

package/build/system/mcp-servers/admin/scan-codes.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Scan-code tools — mirrors routes/scan-codes.ts
+ *
+ * Schemes map a code's leading two digits (10-99) to a target metadata facet
+ * and parse shape; rules map a single-digit category (0-9) to ordered
+ * condition/action steps over the escalation surface. execute_scan_code runs a raw code as
+ * the lt-system principal (see escalations.ts for the principal rationale).
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerScanCodeTools(server: McpServer): void;

package/build/system/mcp-servers/admin/scan-codes.js

@@ -0,0 +1,111 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerScanCodeTools = registerScanCodeTools;
+const scanCodesApi = __importStar(require("../../../api/scan-codes"));
+const iam_1 = require("../../../services/iam");
+const schemas_1 = require("./schemas");
+let systemPrincipalId = null;
+async function systemAuth() {
+    if (!systemPrincipalId)
+        systemPrincipalId = await (0, iam_1.ensureSystemBot)();
+    return { userId: systemPrincipalId, role: 'superadmin' };
+}
+function asText(payload) {
+    return { content: [{ type: 'text', text: JSON.stringify(payload) }] };
+}
+function registerScanCodeTools(server) {
+    // mirrors POST /api/scan-codes/execute
+    server.registerTool('execute_scan_code', {
+        title: 'Execute Scan Code',
+        description: 'Execute a raw scan code (version:category:target). Parses against the ' +
+            'configured schemes, walks the rule\'s condition/action steps, and returns ' +
+            'a structured outcome (executed, confirm_required, matched_list, ' +
+            'no_match_fallback, unconfigured, invalid_code, forbidden, conflict).',
+        inputSchema: schemas_1.executeScanCodeSchema,
+    }, async (args) => {
+        const result = await scanCodesApi.executeScanCode({ code: args.code }, await systemAuth());
+        return asText(result.data ?? { error: result.error });
+    });
+    // mirrors GET /api/scan-codes/schemes
+    server.registerTool('list_scan_schemes', {
+        title: 'List Scan Schemes',
+        description: 'List all scan-code schemes (version, name, target facet, encoding).',
+        inputSchema: schemas_1.listScanSchemesSchema,
+    }, async (_args) => {
+        const result = await scanCodesApi.listScanSchemes();
+        return asText(result.data ?? { error: result.error });
+    });
+    // mirrors PUT /api/scan-codes/schemes/:version
+    server.registerTool('upsert_scan_scheme', {
+        title: 'Upsert Scan Scheme',
+        description: 'Create or replace a scan scheme: which metadata facet the scanned target ' +
+            'resolves against and how the code string parses (fixed digits or delimited text).',
+        inputSchema: schemas_1.upsertScanSchemeSchema,
+    }, async (args) => {
+        const result = await scanCodesApi.upsertScanScheme(args);
+        return asText(result.data ?? { error: result.error });
+    });
+    // mirrors PUT /api/scan-codes/schemes/:version/actions/:category
+    server.registerTool('upsert_scan_rule', {
+        title: 'Upsert Scan Rule',
+        description: 'Create or replace a scan rule for a scheme category: a friendly name, ' +
+            'ordered condition/action steps (first matching query wins its verb), and ' +
+            'a fallback screen when nothing matches.',
+        inputSchema: schemas_1.upsertScanRuleSchema,
+    }, async (args) => {
+        const result = await scanCodesApi.upsertScanRule({
+            scheme_version: args.scheme_version,
+            category: args.category,
+            name: args.name,
+            steps: args.steps,
+            fallback: args.fallback,
+            enabled: args.enabled,
+        });
+        return asText(result.data ?? { error: result.error });
+    });
+    // mirrors DELETE /api/scan-codes/schemes/:version/actions/:category
+    server.registerTool('delete_scan_rule', {
+        title: 'Delete Scan Rule',
+        description: 'Delete one scan rule (scheme version + two-digit category).',
+        inputSchema: schemas_1.deleteScanRuleSchema,
+    }, async (args) => {
+        const result = await scanCodesApi.deleteScanRule({
+            version: args.scheme_version,
+            category: args.category,
+        });
+        return asText(result.data ?? { error: result.error });
+    });
+}