@hotmeshio/long-tail 0.10.11 → 0.10.14

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,11 @@
 export * from './derive-field-label';
 export * from './x-lt-bind';
 export * from './x-lt-help';
+export * from './x-lt-transition';
+export * from './x-lt-submit-on-claim';
+export * from './x-lt-labels';
+export * from './x-lt-query';
+export * from './x-lt-submit-guard';
 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,11 @@ 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-submit-on-claim"), exports);
+__exportStar(require("./x-lt-labels"), exports);
+__exportStar(require("./x-lt-query"), exports);
+__exportStar(require("./x-lt-submit-guard"), 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-labels.d.ts

@@ -0,0 +1,28 @@
+/**
+ * x-lt-labels — configurable copy for the standard escalation footer. A
+ * form_schema may declare, at its schema root, an object that renames the
+ * footer's action controls. Each key is a standard target; its value is the
+ * label to render in place of the default.
+ *
+ *   x-lt-labels   object — { claim, cancel, submit, escalate, release }
+ *
+ * ```jsonc
+ * { "x-lt-labels": { "claim": "Claim and Submit", "submit": "Approve" } }
+ * ```
+ *
+ * Only the five known targets are read; unknown keys and non-string values are
+ * ignored. Any target the schema omits keeps its default label, so a schema
+ * overrides just the controls it cares about.
+ */
+export declare const X_LT_LABELS = "x-lt-labels";
+/** The footer controls a schema may rename. */
+export declare const FOOTER_LABEL_TARGETS: readonly ["claim", "cancel", "submit", "escalate", "release"];
+export type FooterLabelTarget = (typeof FOOTER_LABEL_TARGETS)[number];
+/** A partial map of target → override label. Absent targets keep their default. */
+export type FooterLabels = Partial<Record<FooterLabelTarget, string>>;
+/**
+ * The schema's footer label overrides, or an empty map when none are declared.
+ * Reads only the known targets; a non-object `x-lt-labels`, unknown keys, and
+ * blank or non-string values are dropped.
+ */
+export declare function readFooterLabels(schema: Record<string, unknown> | null | undefined): FooterLabels;

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

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * x-lt-labels — configurable copy for the standard escalation footer. A
+ * form_schema may declare, at its schema root, an object that renames the
+ * footer's action controls. Each key is a standard target; its value is the
+ * label to render in place of the default.
+ *
+ *   x-lt-labels   object — { claim, cancel, submit, escalate, release }
+ *
+ * ```jsonc
+ * { "x-lt-labels": { "claim": "Claim and Submit", "submit": "Approve" } }
+ * ```
+ *
+ * Only the five known targets are read; unknown keys and non-string values are
+ * ignored. Any target the schema omits keeps its default label, so a schema
+ * overrides just the controls it cares about.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FOOTER_LABEL_TARGETS = exports.X_LT_LABELS = void 0;
+exports.readFooterLabels = readFooterLabels;
+exports.X_LT_LABELS = 'x-lt-labels';
+/** The footer controls a schema may rename. */
+exports.FOOTER_LABEL_TARGETS = ['claim', 'cancel', 'submit', 'escalate', 'release'];
+/**
+ * The schema's footer label overrides, or an empty map when none are declared.
+ * Reads only the known targets; a non-object `x-lt-labels`, unknown keys, and
+ * blank or non-string values are dropped.
+ */
+function readFooterLabels(schema) {
+    const raw = schema?.[exports.X_LT_LABELS];
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return {};
+    const source = raw;
+    const labels = {};
+    for (const target of exports.FOOTER_LABEL_TARGETS) {
+        const value = source[target];
+        if (typeof value === 'string' && value.trim().length > 0) {
+            labels[target] = value.trim();
+        }
+    }
+    return labels;
+}

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

@@ -0,0 +1,56 @@
+import type { ShowIfContext } from './x-lt-show-if';
+/**
+ * The embedded escalation query shape shared by `x-lt-query` (escalation-list
+ * widget) and `x-lt-submit-guard.query` (form-level submit gate). String
+ * values inside `facets` support `{{domain.path}}` token interpolation against
+ * the host escalation's context. Isomorphic: the dashboard renders embeds from
+ * it, and the API layer enforces the submit gate from the identical mapping.
+ *
+ * `assigned` is the ownership scope. Ownership is not a separate list — it is
+ * one more dimension of the same faceted query language the escalation API
+ * composes server-side ("claimed" is the implied status: pending, held, claim
+ * window live):
+ * - `"me"`  — rows claimed by the viewing user (the walk case: I walk what I own)
+ * - `"any"` — all matching rows regardless of claim state
+ * - omitted — available rows only (unclaimed, or claim window lapsed)
+ */
+export interface EmbedQuery {
+    role?: string;
+    status?: string;
+    facets?: Record<string, string>;
+    limit?: number;
+    assigned?: 'me' | 'any';
+    /** Superseded by `assigned`; honored only when `assigned` is omitted. */
+    available?: boolean;
+}
+/** Interpolate `{{domain.path}}` tokens in every string value of the facets map. */
+export declare function resolveQueryFacets(facets: Record<string, string> | undefined, ctx: ShowIfContext): Record<string, unknown>;
+/** The escalation-query params an EmbedQuery resolves to — the exact input
+ *  shape of `useEscalations`, so every embed surface queries identically. */
+export interface ScopedQueryParams {
+    role?: string;
+    status: string;
+    facets: Record<string, unknown>;
+    assigned_to?: string;
+    available?: boolean;
+    limit?: number;
+    enabled: boolean;
+}
+/**
+ * Resolve an EmbedQuery into concrete escalation-query params — the ONE
+ * mapping every embed surface (escalation-list, x-lt-actions, x-lt-submit-guard)
+ * consumes, so the visible rows and any count derived from the same query can
+ * never disagree.
+ *
+ * Ownership scope translates into the faceted query language:
+ * - `assigned: "me"`  → `assigned_to = viewer AND available = false` — the
+ *   implied "claimed" status (pending + live claim window held by the viewer)
+ * - `assigned: "any"` → no ownership constraint
+ * - omitted           → `available = true` (the unclaimed pool; a declared
+ *   legacy `available` value is honored)
+ *
+ * When `assigned: "me"` and no viewer id is supplied (a surface with no
+ * resolving user, e.g. an MCP resolve), the scope cannot be evaluated —
+ * `enabled` is false rather than silently widening to another scope.
+ */
+export declare function resolveScopedQuery(query: EmbedQuery, ctx: ShowIfContext, viewerId: string | undefined): ScopedQueryParams;

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

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveQueryFacets = resolveQueryFacets;
+exports.resolveScopedQuery = resolveScopedQuery;
+const x_lt_help_1 = require("./x-lt-help");
+/** Interpolate `{{domain.path}}` tokens in every string value of the facets map. */
+function resolveQueryFacets(facets, ctx) {
+    if (!facets)
+        return {};
+    const resolved = {};
+    for (const [k, v] of Object.entries(facets)) {
+        resolved[k] = typeof v === 'string' ? (0, x_lt_help_1.interpolateHelp)(v, ctx) : v;
+    }
+    return resolved;
+}
+/**
+ * Resolve an EmbedQuery into concrete escalation-query params — the ONE
+ * mapping every embed surface (escalation-list, x-lt-actions, x-lt-submit-guard)
+ * consumes, so the visible rows and any count derived from the same query can
+ * never disagree.
+ *
+ * Ownership scope translates into the faceted query language:
+ * - `assigned: "me"`  → `assigned_to = viewer AND available = false` — the
+ *   implied "claimed" status (pending + live claim window held by the viewer)
+ * - `assigned: "any"` → no ownership constraint
+ * - omitted           → `available = true` (the unclaimed pool; a declared
+ *   legacy `available` value is honored)
+ *
+ * When `assigned: "me"` and no viewer id is supplied (a surface with no
+ * resolving user, e.g. an MCP resolve), the scope cannot be evaluated —
+ * `enabled` is false rather than silently widening to another scope.
+ */
+function resolveScopedQuery(query, ctx, viewerId) {
+    const facets = resolveQueryFacets(query.facets, ctx);
+    const base = {
+        role: query.role,
+        status: query.status ?? 'pending',
+        facets,
+        limit: query.limit,
+        enabled: !!(query.role || Object.keys(facets).length),
+    };
+    if (query.assigned === 'me') {
+        return { ...base, assigned_to: viewerId, available: false, enabled: base.enabled && !!viewerId };
+    }
+    if (query.assigned === 'any') {
+        return base;
+    }
+    return { ...base, available: query.available ?? true };
+}

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

@@ -0,0 +1,46 @@
+/**
+ * x-lt-submit-guard — a query precondition on the resolve. A form_schema may
+ * declare, at its root, that the escalation cannot be resolved while an embedded
+ * escalation query still returns rows: the parent references a set of children
+ * (commonly claimed by the same person) that must all be completed first, a
+ * to-do list that empties as children resolve.
+ *
+ *   "x-lt-submit-guard": {
+ *     "query": { "role": "print-harvest", "status": "pending",
+ *                "assigned": "me",
+ *                "facets": { "walkId": "{{metadata.walkId}}" } },
+ *     "mustBeEmpty": true,               // the only mode today; defaults true
+ *     "message": "{{count}} plates still pending — bag them before closing.",
+ *     "autoResolveWhenEmpty": true       // auto-submit the parent once empty
+ *   }
+ *
+ * The gate is isomorphic. The dashboard disables the submit while the query
+ * returns rows (UI honesty), and the API layer enforces the same precondition
+ * for `enforce_schema` roles so a raw-API resolve is rejected too. Only a
+ * confirmed empty result (a successful read with zero rows) clears the gate — a
+ * 403 or any error never does.
+ *
+ * `autoResolveWhenEmpty` closes the loop: the moment the query is confirmed
+ * empty, the claimed parent auto-submits — checked on page-load and after each
+ * inline child-resolve — so a set of escalations completes with no extra click.
+ */
+import type { EmbedQuery } from './x-lt-query';
+export declare const X_LT_SUBMIT_GUARD = "x-lt-submit-guard";
+export interface SubmitGuardDef {
+    query: EmbedQuery;
+    /** The gate condition; defaults to true (the only supported mode today). */
+    mustBeEmpty?: boolean;
+    /** Shown beside the disabled submit. `{{count}}` and `{{domain.path}}` tokens interpolate. */
+    message?: string;
+    /** When true, auto-submit the claimed parent the moment the query is confirmed empty. */
+    autoResolveWhenEmpty?: boolean;
+}
+export declare const SUBMIT_GUARD_DEFAULT_MESSAGE = "{{count}} related items are still pending";
+/** The schema's submit-guard, or undefined when it declares none. */
+export declare function readSubmitGuard(schema: Record<string, unknown> | null | undefined): SubmitGuardDef | undefined;
+/**
+ * Whether a guard blocks the resolve given the query's row count. `mustBeEmpty`
+ * defaults to true, so any matching row blocks. A pure decision — the caller
+ * supplies the count from a confirmed read (never an error/loading state).
+ */
+export declare function guardBlocks(count: number, guard: SubmitGuardDef | undefined): boolean;

package/build/shared/form-validation/x-lt-submit-guard.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUBMIT_GUARD_DEFAULT_MESSAGE = exports.X_LT_SUBMIT_GUARD = void 0;
+exports.readSubmitGuard = readSubmitGuard;
+exports.guardBlocks = guardBlocks;
+exports.X_LT_SUBMIT_GUARD = 'x-lt-submit-guard';
+exports.SUBMIT_GUARD_DEFAULT_MESSAGE = '{{count}} related items are still pending';
+/** The schema's submit-guard, or undefined when it declares none. */
+function readSubmitGuard(schema) {
+    const raw = schema?.[exports.X_LT_SUBMIT_GUARD];
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return undefined;
+    const guard = raw;
+    if (!guard.query || typeof guard.query !== 'object')
+        return undefined;
+    return guard;
+}
+/**
+ * Whether a guard blocks the resolve given the query's row count. `mustBeEmpty`
+ * defaults to true, so any matching row blocks. A pure decision — the caller
+ * supplies the count from a confirmed read (never an error/loading state).
+ */
+function guardBlocks(count, guard) {
+    return !!guard && guard.mustBeEmpty !== false && count > 0;
+}

package/build/shared/form-validation/x-lt-submit-on-claim.d.ts

@@ -0,0 +1,22 @@
+/**
+ * x-lt-submit-on-claim — a one-gesture claim. A form_schema may declare, at its
+ * schema root, that claiming one of its escalations should also resolve it in
+ * the same gesture, submitting whatever the form currently holds (its seeded
+ * defaults). The person clicks Claim once and the work item advances — no
+ * second Submit step.
+ *
+ *   x-lt-submit-on-claim   boolean — opt in to claim-and-submit
+ *
+ * It is opt-in and defaults off. Pair it with `x-lt-labels` to rename the Claim
+ * button ("Claim and Submit") so the single gesture reads honestly. When the
+ * seeded defaults fail validation the claim still lands; the page drops into the
+ * normal claimed state with the field errors surfaced, so the person finishes
+ * the form by hand.
+ */
+export declare const X_LT_SUBMIT_ON_CLAIM = "x-lt-submit-on-claim";
+/**
+ * Whether the schema opts into claim-and-submit. Truthy `x-lt-submit-on-claim`
+ * turns it on; anything else (absent, false) leaves the standard two-step claim
+ * then submit.
+ */
+export declare function readSubmitOnClaim(schema: Record<string, unknown> | null | undefined): boolean;

package/build/shared/form-validation/x-lt-submit-on-claim.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * x-lt-submit-on-claim — a one-gesture claim. A form_schema may declare, at its
+ * schema root, that claiming one of its escalations should also resolve it in
+ * the same gesture, submitting whatever the form currently holds (its seeded
+ * defaults). The person clicks Claim once and the work item advances — no
+ * second Submit step.
+ *
+ *   x-lt-submit-on-claim   boolean — opt in to claim-and-submit
+ *
+ * It is opt-in and defaults off. Pair it with `x-lt-labels` to rename the Claim
+ * button ("Claim and Submit") so the single gesture reads honestly. When the
+ * seeded defaults fail validation the claim still lands; the page drops into the
+ * normal claimed state with the field errors surfaced, so the person finishes
+ * the form by hand.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.X_LT_SUBMIT_ON_CLAIM = void 0;
+exports.readSubmitOnClaim = readSubmitOnClaim;
+exports.X_LT_SUBMIT_ON_CLAIM = 'x-lt-submit-on-claim';
+/**
+ * Whether the schema opts into claim-and-submit. Truthy `x-lt-submit-on-claim`
+ * turns it on; anything else (absent, false) leaves the standard two-step claim
+ * then submit.
+ */
+function readSubmitOnClaim(schema) {
+    return !!schema?.[exports.X_LT_SUBMIT_ON_CLAIM];
+}

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)