@hotmeshio/long-tail 0.10.11 → 0.10.13

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

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseScanCode = parseScanCode;
+exports.interpolateScanTemplate = interpolateScanTemplate;
+const types_1 = require("../../types");
+/**
+ * Parse a raw scan string against the configured schemes. Pure — no I/O.
+ *
+ * The leading TWO digits pick the scheme (10-99, so a code never starts with a
+ * leading zero); the scheme then defines how the remainder splits into a
+ * single-digit category (0-9) and the target:
+ * - delimited: `10:1:ABC-123` (delimiter from the scheme row)
+ * - fixed:     `1017554332` (one category digit, then target_length digits)
+ */
+function parseScanCode(raw, schemes) {
+    const code = raw.trim();
+    if (!code) {
+        return { ok: false, failure: { reason: 'empty', detail: 'empty scan code' } };
+    }
+    const versionToken = code.slice(0, 2);
+    const version = Number(versionToken);
+    if (!/^[0-9]{2}$/.test(versionToken) || version < 10 || version > 99) {
+        return {
+            ok: false,
+            failure: { reason: 'unknown_version', detail: `code must start with a two-digit scheme 10-99, got "${versionToken}"` },
+        };
+    }
+    const scheme = schemes.find((s) => s.version === version);
+    if (!scheme) {
+        return {
+            ok: false,
+            failure: { reason: 'unknown_version', detail: `no scan scheme configured for version ${version}` },
+        };
+    }
+    if (!scheme.enabled) {
+        return {
+            ok: false,
+            failure: { reason: 'scheme_disabled', detail: `scan scheme ${version} ("${scheme.name}") is disabled` },
+        };
+    }
+    if (scheme.encoding === types_1.SCAN_ENCODINGS.DELIMITED) {
+        return parseDelimited(code, version, scheme);
+    }
+    return parseFixed(code, version, scheme);
+}
+function parseDelimited(code, version, scheme) {
+    const d = scheme.delimiter;
+    // version(2 digits) <d> category(1 digit) <d> target(rest, non-empty)
+    if (code[2] !== d) {
+        return malformed(scheme, `expected "${d}" after the two-digit scheme`);
+    }
+    const category = code.slice(3, 4);
+    if (!/^[0-9]$/.test(category)) {
+        return malformed(scheme, 'category must be a single digit');
+    }
+    if (code[4] !== d) {
+        return malformed(scheme, `expected "${d}" after the category`);
+    }
+    const target = code.slice(5);
+    if (!target) {
+        return malformed(scheme, 'target is empty');
+    }
+    return { ok: true, parsed: { version, category, target }, scheme };
+}
+function parseFixed(code, version, scheme) {
+    const targetLength = scheme.target_length ?? 0;
+    const expected = 2 + 1 + targetLength;
+    // UPC-A wedges deliver the trailing check digit too; accept it as slack.
+    if (!/^[0-9]+$/.test(code)) {
+        return malformed(scheme, 'fixed encoding accepts digits only');
+    }
+    if (code.length !== expected && code.length !== expected + 1) {
+        return malformed(scheme, `expected ${expected} digits (or ${expected + 1} with check digit), got ${code.length}`);
+    }
+    const category = code.slice(2, 3);
+    const target = code.slice(3, 3 + targetLength);
+    return { ok: true, parsed: { version, category, target }, scheme };
+}
+function malformed(scheme, detail) {
+    return {
+        ok: false,
+        failure: { reason: 'malformed', detail: `scheme ${scheme.version} ("${scheme.name}"): ${detail}` },
+    };
+}
+/**
+ * Replace SCAN_TEMPLATE_TOKENS inside string values of a params object.
+ * Deep, pure, non-mutating. Only exact-token and in-string replacement of
+ * the three known tokens — no expression language.
+ */
+function interpolateScanTemplate(value, ctx) {
+    if (typeof value === 'string') {
+        return value
+            .split(types_1.SCAN_TEMPLATE_TOKENS.TARGET).join(ctx.target)
+            .split(types_1.SCAN_TEMPLATE_TOKENS.CATEGORY).join(ctx.category)
+            .split(types_1.SCAN_TEMPLATE_TOKENS.SCANNED_AT).join(ctx.scannedAt);
+    }
+    if (Array.isArray(value)) {
+        return value.map((v) => interpolateScanTemplate(v, ctx));
+    }
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = interpolateScanTemplate(v, ctx);
+        }
+        return out;
+    }
+    return value;
+}

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

@@ -0,0 +1,5 @@
+import type { ScanScheme, ScanRule } from '../../types';
+export declare function listScanSchemes(): Promise<ScanScheme[]>;
+export declare function getScanScheme(version: number): Promise<ScanScheme | null>;
+export declare function listScanRules(schemeVersion: number): Promise<ScanRule[]>;
+export declare function getScanRule(schemeVersion: number, category: string): Promise<ScanRule | null>;

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;