@hotmeshio/long-tail 0.10.11 → 0.10.13

package/build/api/scan-codes/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deleteScanRule = exports.upsertScanRule = exports.getScanRule = exports.listScanRules = exports.deleteScanScheme = exports.upsertScanScheme = exports.getScanScheme = exports.listScanSchemes = exports.executeScanCode = void 0;
+var execute_1 = require("./execute");
+Object.defineProperty(exports, "executeScanCode", { enumerable: true, get: function () { return execute_1.executeScanCode; } });
+var config_1 = require("./config");
+Object.defineProperty(exports, "listScanSchemes", { enumerable: true, get: function () { return config_1.listScanSchemes; } });
+Object.defineProperty(exports, "getScanScheme", { enumerable: true, get: function () { return config_1.getScanScheme; } });
+Object.defineProperty(exports, "upsertScanScheme", { enumerable: true, get: function () { return config_1.upsertScanScheme; } });
+Object.defineProperty(exports, "deleteScanScheme", { enumerable: true, get: function () { return config_1.deleteScanScheme; } });
+Object.defineProperty(exports, "listScanRules", { enumerable: true, get: function () { return config_1.listScanRules; } });
+Object.defineProperty(exports, "getScanRule", { enumerable: true, get: function () { return config_1.getScanRule; } });
+Object.defineProperty(exports, "upsertScanRule", { enumerable: true, get: function () { return config_1.upsertScanRule; } });
+Object.defineProperty(exports, "deleteScanRule", { enumerable: true, get: function () { return config_1.deleteScanRule; } });

package/build/lib/db/schemas/026_scan_codes.sql

@@ -0,0 +1,51 @@
+-- Migration 026: Scan-code schemes and rules
+--
+-- A scan code arrives from a physical input source (barcode scanner, RFID
+-- reader, manual entry) as a plain string encoding version:category:target.
+-- The leading digit (1-9) selects a SCHEME: which escalation metadata facet
+-- the target resolves against and how the string parses (delimited text or
+-- fixed-width digits). The two-digit category selects a RULE: an ordered
+-- list of condition/action steps evaluated against the escalation surface,
+-- plus a fallback screen when no step matches.
+--
+-- Rules are plain config consulted at execute time (like lt_config_workflows);
+-- nothing pins a historical rule, so there is no snapshot table. Provenance
+-- is stamped into escalation metadata by the execute path instead.
+
+CREATE TABLE IF NOT EXISTS lt_config_scan_schemes (
+  version       SMALLINT PRIMARY KEY CHECK (version BETWEEN 1 AND 9),
+  name          TEXT NOT NULL,
+  description   TEXT,
+  target_facet  TEXT NOT NULL,
+  encoding      TEXT NOT NULL DEFAULT 'fixed'
+                  CHECK (encoding IN ('fixed', 'delimited')),
+  delimiter     TEXT NOT NULL DEFAULT ':',
+  target_length SMALLINT,
+  enabled       BOOLEAN NOT NULL DEFAULT TRUE,
+  created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  -- fixed-width parsing needs to know where the target ends
+  CONSTRAINT chk_scan_scheme_fixed_length
+    CHECK (encoding <> 'fixed' OR target_length IS NOT NULL)
+);
+
+CREATE OR REPLACE TRIGGER trg_lt_config_scan_schemes_updated_at
+  BEFORE UPDATE ON lt_config_scan_schemes
+  FOR EACH ROW EXECUTE FUNCTION lt_set_updated_at();
+
+CREATE TABLE IF NOT EXISTS lt_config_scan_actions (
+  scheme_version SMALLINT NOT NULL
+                   REFERENCES lt_config_scan_schemes(version) ON DELETE CASCADE,
+  category       TEXT NOT NULL CHECK (category ~ '^[0-9]{2}$'),
+  name           TEXT NOT NULL,
+  steps          JSONB NOT NULL DEFAULT '[]',
+  fallback       JSONB NOT NULL DEFAULT '{}',
+  enabled        BOOLEAN NOT NULL DEFAULT TRUE,
+  created_at     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (scheme_version, category)
+);
+
+CREATE OR REPLACE TRIGGER trg_lt_config_scan_actions_updated_at
+  BEFORE UPDATE ON lt_config_scan_actions
+  FOR EACH ROW EXECUTE FUNCTION lt_set_updated_at();

package/build/lib/db/schemas/027_scan_codes_reindex.sql

@@ -0,0 +1,23 @@
+-- Migration 027: Scan-code numbering inversion
+--
+-- The scheme index moves to the leading TWO digits (10-99) and the category
+-- (rule) index to a single digit (0-9): a code now reads ##:#:target. Two
+-- reasons: a code never starts with a leading zero (some scanners choke on it),
+-- and the top-level "named item" you organize by (the scheme) gets the wider
+-- 90-slot space while each scheme's rules stay a small 0-9 set. The indices are
+-- assigned automatically; operators name entries, never pick numbers.
+--
+-- Old rows (single-digit version, two-digit category) cannot satisfy the new
+-- checks and their codes no longer parse, so the config is cleared and re-seeded.
+
+TRUNCATE lt_config_scan_actions, lt_config_scan_schemes;
+
+ALTER TABLE lt_config_scan_schemes
+  DROP CONSTRAINT IF EXISTS lt_config_scan_schemes_version_check;
+ALTER TABLE lt_config_scan_schemes
+  ADD CONSTRAINT lt_config_scan_schemes_version_check CHECK (version BETWEEN 10 AND 99);
+
+ALTER TABLE lt_config_scan_actions
+  DROP CONSTRAINT IF EXISTS lt_config_scan_actions_category_check;
+ALTER TABLE lt_config_scan_actions
+  ADD CONSTRAINT lt_config_scan_actions_category_check CHECK (category ~ '^[0-9]$');

package/build/lib/events/system-events.js

@@ -44,6 +44,10 @@ function mapSystemEvent(event) {
             escalationId: row.id || segments[2],
             originId: row.origin_id || event.origin_id || undefined,
             status: ESCALATION_STATUS_BY_VERB[verb] ?? verb,
+            // Assignment provenance rides the SystemEvent envelope, NOT the row (it is
+            // not a column). Forward it so a consumer can tell a born-assigned,
+            // system-directed hand-off (`claimed` with true) from an interactive claim.
+            assignedAtCreation: event.assigned_at_creation,
             data: row,
             timestamp: event.ts,
         };

package/build/modules/features.d.ts

@@ -21,6 +21,14 @@ export interface FeatureFlags {
      * one-time accounts (e.g. a customer resolving a single form).
      */
     publicPaceBoard: boolean;
+    /**
+     * Scan-code input on every login: the header scan affordance, the panel,
+     * and the global keyboard-wedge capture. Opt-IN: default false — a
+     * deployment turns it on with `features.scanCodes: true` when scanners are
+     * part of the floor workflow. The scan-code execute/config API stays
+     * available either way (the flag gates the dashboard surface).
+     */
+    scanCodes: boolean;
 }
 /** Merge a partial set of flags from the start config. Unspecified flags keep their default. */
 export declare function configureFeatureFlags(patch?: Partial<FeatureFlags>): void;

package/build/modules/features.js

@@ -5,6 +5,7 @@ exports.getFeatureFlags = getFeatureFlags;
 const DEFAULT_FLAGS = {
     dbMaintenance: true,
     publicPaceBoard: true,
+    scanCodes: false,
 };
 let flags = { ...DEFAULT_FLAGS };
 /** Merge a partial set of flags from the start config. Unspecified flags keep their default. */

package/build/routes/escalations/list.js

@@ -92,6 +92,7 @@ function registerListRoutes(router) {
             type: req.query.type,
             subtype: req.query.subtype,
             assigned_to: req.query.assigned_to,
+            parent_id: req.query.parent_id,
             claimed: req.query.claimed === 'true',
             priority: req.query.priority ? parseInt(req.query.priority, 10) : undefined,
             limit: req.query.limit ? parseInt(req.query.limit, 10) : undefined,

package/build/routes/index.js

@@ -36,6 +36,7 @@ const agents_1 = __importDefault(require("./agents"));
 const capabilities_1 = __importDefault(require("./capabilities"));
 const topics_1 = __importDefault(require("./topics"));
 const nats_credentials_1 = __importDefault(require("./nats-credentials"));
+const scan_codes_1 = __importDefault(require("./scan-codes"));
 const router = (0, express_1.Router)();
 // Public routes (no auth required — they handle their own auth)
 router.use('/auth', auth_2.default);
@@ -72,6 +73,7 @@ router.use('/knowledge', knowledge_1.default);
 router.use('/agents', agents_1.default);
 router.use('/capabilities', capabilities_1.default);
 router.use('/topics', topics_1.default);
+router.use('/scan-codes', scan_codes_1.default);
 const overview_1 = __importDefault(require("./overview"));
 router.use('/overview', overview_1.default);
 const diagnostics_1 = __importDefault(require("./diagnostics"));

package/build/routes/scan-codes.d.ts

@@ -0,0 +1,2 @@
+declare const router: import("express-serve-static-core").Router;
+export default router;

package/build/routes/scan-codes.js

@@ -0,0 +1,138 @@
+"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 });
+const express_1 = require("express");
+const api = __importStar(require("../api/scan-codes"));
+const auth_1 = require("../modules/auth");
+const router = (0, express_1.Router)();
+// ── Execute ───────────────────────────────────────────────────────────────
+/**
+ * POST /api/scan-codes/execute
+ * Execute a raw scan code (from any input source) as the calling user.
+ * Every terminal state is a structured 200 outcome.
+ */
+router.post('/execute', async (req, res) => {
+    const result = await api.executeScanCode({ code: req.body.code }, req.auth);
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
+// ── Scheme CRUD (admin, engineer, superadmin) ─────────────────────────────
+/**
+ * GET /api/scan-codes/schemes
+ * List all scan schemes.
+ */
+router.get('/schemes', async (_req, res) => {
+    const result = await api.listScanSchemes();
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
+/**
+ * GET /api/scan-codes/schemes/:version
+ * Get one scheme with its rules.
+ */
+router.get('/schemes/:version', async (req, res) => {
+    const result = await api.getScanScheme({ version: Number(req.params.version) });
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
+/**
+ * PUT /api/scan-codes/schemes/:version
+ * Create or replace a scan scheme. Admin, engineer, or superadmin.
+ */
+router.put('/schemes/:version', auth_1.requireRoleManager, async (req, res) => {
+    const result = await api.upsertScanScheme({
+        version: Number(req.params.version),
+        name: req.body.name,
+        description: req.body.description,
+        target_facet: req.body.target_facet,
+        encoding: req.body.encoding,
+        delimiter: req.body.delimiter,
+        target_length: req.body.target_length,
+        enabled: req.body.enabled,
+    });
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
+/**
+ * DELETE /api/scan-codes/schemes/:version
+ * Delete a scheme and its rules (cascade). Admin, engineer, or superadmin.
+ */
+router.delete('/schemes/:version', auth_1.requireRoleManager, async (req, res) => {
+    const result = await api.deleteScanScheme({ version: Number(req.params.version) });
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
+// ── Rule CRUD (admin, engineer, superadmin) ───────────────────────────────
+/**
+ * GET /api/scan-codes/schemes/:version/actions
+ * List a scheme's rules.
+ */
+router.get('/schemes/:version/actions', async (req, res) => {
+    const result = await api.listScanRules({ version: Number(req.params.version) });
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
+/**
+ * GET /api/scan-codes/schemes/:version/actions/:category
+ * Get one rule.
+ */
+router.get('/schemes/:version/actions/:category', async (req, res) => {
+    const result = await api.getScanRule({
+        version: Number(req.params.version),
+        category: req.params.category,
+    });
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
+/**
+ * PUT /api/scan-codes/schemes/:version/actions/:category
+ * Create or replace a rule. Admin, engineer, or superadmin.
+ */
+router.put('/schemes/:version/actions/:category', auth_1.requireRoleManager, async (req, res) => {
+    const result = await api.upsertScanRule({
+        scheme_version: Number(req.params.version),
+        category: req.params.category,
+        name: req.body.name,
+        steps: req.body.steps,
+        fallback: req.body.fallback,
+        enabled: req.body.enabled,
+    });
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
+/**
+ * DELETE /api/scan-codes/schemes/:version/actions/:category
+ * Delete a rule. Admin, engineer, or superadmin.
+ */
+router.delete('/schemes/:version/actions/:category', auth_1.requireRoleManager, async (req, res) => {
+    const result = await api.deleteScanRule({
+        version: Number(req.params.version),
+        category: req.params.category,
+    });
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
+exports.default = router;

package/build/sdk/index.d.ts

@@ -96,6 +96,7 @@ export declare function createClient(options?: LTClientOptions): {
             type?: string;
             subtype?: string;
             assigned_to?: string;
+            parent_id?: string;
             claimed?: boolean;
             priority?: number;
             limit?: number;
@@ -202,6 +203,7 @@ export declare function createClient(options?: LTClientOptions): {
             assignee?: string;
             metadata?: Record<string, any>;
             provisionIfAbsent?: import("../api/escalations/helpers").ProvisionIfAbsent;
+            restrictRoles?: string[];
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         resolveByMetadata: (input: {
             key: string;
@@ -209,6 +211,8 @@ export declare function createClient(options?: LTClientOptions): {
             resolverPayload: Record<string, any>;
             assignee?: string;
             metadata?: Record<string, any>;
+            restrictRoles?: string[];
+            extraFacets?: Record<string, any>;
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         searchByFacets: (input: import("..").FacetQuery, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         claimGroups: (input: {

package/build/services/escalation/crud.d.ts

@@ -241,4 +241,4 @@ export interface ResolveByMetadataResult {
  * business logic over the shared table, so it runs as one atomic statement on
  * `hmsh_escalations` rather than through the generic SDK resolve.
  */
-export declare function resolveByMetadataAtomic(key: string, value: string, userId: string, resolverPayload: Record<string, any>, metadata?: Record<string, any>, writeAllRoles?: string[] | null, writeSelfRoles?: string[] | null, enforcingRoles?: string[] | null, assertId?: string | null): Promise<ResolveByMetadataResult>;
+export declare function resolveByMetadataAtomic(key: string, value: string, userId: string, resolverPayload: Record<string, any>, metadata?: Record<string, any>, writeAllRoles?: string[] | null, writeSelfRoles?: string[] | null, enforcingRoles?: string[] | null, assertId?: string | null, extraFacets?: Record<string, any> | null): Promise<ResolveByMetadataResult>;

package/build/services/escalation/crud.js

@@ -554,10 +554,12 @@ async function claimByMetadata(key, value, userId, durationMinutes = 30, metadat
  * business logic over the shared table, so it runs as one atomic statement on
  * `hmsh_escalations` rather than through the generic SDK resolve.
  */
-async function resolveByMetadataAtomic(key, value, userId, resolverPayload, metadata, writeAllRoles, writeSelfRoles, enforcingRoles, assertId) {
+async function resolveByMetadataAtomic(key, value, userId, resolverPayload, metadata, writeAllRoles, writeSelfRoles, enforcingRoles, assertId, extraFacets) {
     await (0, client_1.ensureEscalationCompatView)();
     const pool = (0, db_1.getPool)();
-    const filter = JSON.stringify({ [key]: value });
+    // The statement's filter is jsonb containment — extra facet guards simply
+    // widen the containment object and ride the same atomic WHERE.
+    const filter = JSON.stringify({ [key]: value, ...(extraFacets ?? {}) });
     const payloadJson = JSON.stringify(resolverPayload);
     const metaPatch = metadata ? JSON.stringify(metadata) : null;
     // null write_all roles = global (no filter). A scoped caller passes its arrays

package/build/services/escalation/queries.d.ts

@@ -62,6 +62,7 @@ export declare function listEscalations(filters: {
     type?: string;
     subtype?: string;
     assigned_to?: string;
+    parent_id?: string;
     claimed?: boolean;
     priority?: number;
     limit?: number;

package/build/services/escalation/queries.js

@@ -298,6 +298,8 @@ async function listEscalations(filters) {
     };
     if (filters.assigned_to)
         where.assignedTo = filters.assigned_to;
+    if (filters.parent_id)
+        where.parentId = filters.parent_id;
     if (heldNow)
         where.available = false;
     if (filters.metadata)

package/build/services/escalation/sql.d.ts

@@ -26,13 +26,18 @@ export declare function searchEscalationsQuery(orderBy: string): string;
  * 3. `metadata.signal_id` present, row already claimed and claim not expired →
  *    a concurrent caller is handling the signal. `signal_already_claimed = true`;
  *    caller returns 409 without re-signaling.
- * 4. `signal_key` present (atomic conditionLT) → `claimed` and `resolved` both skip.
+ * 4. `signal_key` present (atomic conditionLT) → the write skips entirely.
  *    Caller invokes SDK resolve to atomically mark resolved + deliver the signal.
  *
- * Signal_id hardening: the `claimed` CTE runs for signal_id rows (previously excluded).
- * This stamps `assigned_to` on the row inside the FOR UPDATE transaction, so a
- * concurrent second caller sees `signal_already_claimed = true` and aborts.
- * The `resolved` CTE still skips signal_id rows — the workflow resolves durably.
+ * Signal_id hardening: the write runs for signal_id rows too, stamping
+ * `assigned_to` inside the FOR UPDATE transaction so a concurrent second caller
+ * sees `signal_already_claimed = true` and aborts. The resolve columns skip
+ * signal_id rows (CASE branches) — the workflow resolves durably.
+ *
+ * ONE UPDATE does both claim and resolve: Postgres does not support a second
+ * same-statement UPDATE of a row already updated by an earlier CTE (the second
+ * silently no-ops), so a chained claim→resolve pair leaves the row claimed but
+ * pending. The resolve columns ride the claim UPDATE as CASE branches instead.
  *
  * $1 = metadata filter (jsonb), $2 = userId, $3 = resolver_payload (jsonb),
  * $4 = metadata patch (jsonb, nullable), $5 = write_all roles (text[], null = global /
@@ -53,7 +58,7 @@ export declare function searchEscalationsQuery(orderBy: string): string;
  * resolution surfaces as zero rows → the caller's conflict handling). This is
  * the same pick-then-guarded-finish shape the signal outcomes already use.
  */
-export declare const RESOLVE_BY_METADATA_ATOMIC = "WITH target AS MATERIALIZED (\n  SELECT *\n  FROM public.hmsh_escalations\n  WHERE metadata @> $1::jsonb\n    AND status = 'pending'\n    AND (\n         $5::text[] IS NULL\n      OR role = ANY($5)\n      OR (role = ANY($6::text[]) AND assigned_to = $2)\n    )\n    AND ($8::uuid IS NULL OR id = $8::uuid)\n  ORDER BY priority ASC, created_at ASC\n  LIMIT 1\n  FOR UPDATE\n),\nclaimed AS (\n  UPDATE public.hmsh_escalations e\n  SET assigned_to = COALESCE(e.assigned_to, $2),\n      claimed_at = COALESCE(e.claimed_at, NOW()),\n      assigned_until = CASE\n        WHEN e.assigned_to IS NOT NULL AND e.assigned_until > NOW() THEN e.assigned_until\n        ELSE NOW() + INTERVAL '5 minutes' END,\n      claim_expires_at = CASE\n        WHEN e.assigned_to IS NOT NULL AND e.assigned_until > NOW() THEN e.claim_expires_at\n        ELSE NOW() + INTERVAL '5 minutes' END,\n      metadata = CASE WHEN $4::jsonb IS NOT NULL\n        THEN COALESCE(e.metadata, '{}'::jsonb) || $4::jsonb\n        ELSE e.metadata END,\n      updated_at = NOW()\n  FROM target\n  WHERE e.id = target.id\n    AND target.signal_key IS NULL\n    AND ($7::text[] IS NULL OR NOT (target.role = ANY($7)))\n  RETURNING e.*\n),\nresolved AS (\n  UPDATE public.hmsh_escalations e\n  SET status = 'resolved',\n      resolved_at = NOW(),\n      resolver_payload = $3,\n      updated_at = NOW()\n  FROM claimed\n  WHERE e.id = claimed.id\n    AND (claimed.metadata->>'signal_id') IS NULL\n  RETURNING e.*\n)\nSELECT\n  resolved.*,\n  target.id AS target_id,\n  target.role AS target_role,\n  target.metadata AS target_metadata,\n  target.envelope AS target_envelope,\n  target.escalation_payload AS target_escalation_payload,\n  target.metadata->>'signal_id' AS signal_id,\n  target.signal_key AS signal_key,\n  target.workflow_id AS target_workflow_id,\n  target.workflow_type AS target_workflow_type,\n  target.task_queue AS target_task_queue,\n  (target.assigned_to IS NOT NULL\n    AND target.assigned_until IS NOT NULL\n    AND target.assigned_until > NOW()) AS signal_already_claimed,\n  CASE\n    WHEN resolved.id IS NOT NULL THEN 'resolved'\n    WHEN $7::text[] IS NOT NULL AND target.role = ANY($7) THEN 'validation_required'\n    ELSE 'signal_required'\n  END AS outcome\nFROM target\nLEFT JOIN resolved ON resolved.id = target.id";
+export declare const RESOLVE_BY_METADATA_ATOMIC = "WITH target AS MATERIALIZED (\n  SELECT *\n  FROM public.hmsh_escalations\n  WHERE metadata @> $1::jsonb\n    AND status = 'pending'\n    AND (\n         $5::text[] IS NULL\n      OR role = ANY($5)\n      OR (role = ANY($6::text[]) AND assigned_to = $2)\n    )\n    AND ($8::uuid IS NULL OR id = $8::uuid)\n  ORDER BY priority ASC, created_at ASC\n  LIMIT 1\n  FOR UPDATE\n),\nwritten AS (\n  UPDATE public.hmsh_escalations e\n  SET assigned_to = COALESCE(e.assigned_to, $2),\n      claimed_at = COALESCE(e.claimed_at, NOW()),\n      assigned_until = CASE\n        WHEN e.assigned_to IS NOT NULL AND e.assigned_until > NOW() THEN e.assigned_until\n        ELSE NOW() + INTERVAL '5 minutes' END,\n      claim_expires_at = CASE\n        WHEN e.assigned_to IS NOT NULL AND e.assigned_until > NOW() THEN e.claim_expires_at\n        ELSE NOW() + INTERVAL '5 minutes' END,\n      metadata = CASE WHEN $4::jsonb IS NOT NULL\n        THEN COALESCE(e.metadata, '{}'::jsonb) || $4::jsonb\n        ELSE e.metadata END,\n      status = CASE WHEN (target.metadata->>'signal_id') IS NULL\n        THEN 'resolved' ELSE e.status END,\n      resolved_at = CASE WHEN (target.metadata->>'signal_id') IS NULL\n        THEN NOW() ELSE e.resolved_at END,\n      resolver_payload = CASE WHEN (target.metadata->>'signal_id') IS NULL\n        THEN $3 ELSE e.resolver_payload END,\n      updated_at = NOW()\n  FROM target\n  WHERE e.id = target.id\n    AND target.signal_key IS NULL\n    AND ($7::text[] IS NULL OR NOT (target.role = ANY($7)))\n  RETURNING e.*\n)\nSELECT\n  written.*,\n  target.id AS target_id,\n  target.role AS target_role,\n  target.metadata AS target_metadata,\n  target.envelope AS target_envelope,\n  target.escalation_payload AS target_escalation_payload,\n  target.metadata->>'signal_id' AS signal_id,\n  target.signal_key AS signal_key,\n  target.workflow_id AS target_workflow_id,\n  target.workflow_type AS target_workflow_type,\n  target.task_queue AS target_task_queue,\n  (target.assigned_to IS NOT NULL\n    AND target.assigned_until IS NOT NULL\n    AND target.assigned_until > NOW()) AS signal_already_claimed,\n  CASE\n    WHEN written.status = 'resolved' THEN 'resolved'\n    WHEN $7::text[] IS NOT NULL AND target.role = ANY($7) THEN 'validation_required'\n    ELSE 'signal_required'\n  END AS outcome\nFROM target\nLEFT JOIN written ON written.id = target.id";
 /**
  * Live counts — pending, active claims, and priority (past-threshold) per role.
  *

package/build/services/escalation/sql.js

@@ -108,13 +108,18 @@ function searchEscalationsQuery(orderBy) {
  * 3. `metadata.signal_id` present, row already claimed and claim not expired →
  *    a concurrent caller is handling the signal. `signal_already_claimed = true`;
  *    caller returns 409 without re-signaling.
- * 4. `signal_key` present (atomic conditionLT) → `claimed` and `resolved` both skip.
+ * 4. `signal_key` present (atomic conditionLT) → the write skips entirely.
  *    Caller invokes SDK resolve to atomically mark resolved + deliver the signal.
  *
- * Signal_id hardening: the `claimed` CTE runs for signal_id rows (previously excluded).
- * This stamps `assigned_to` on the row inside the FOR UPDATE transaction, so a
- * concurrent second caller sees `signal_already_claimed = true` and aborts.
- * The `resolved` CTE still skips signal_id rows — the workflow resolves durably.
+ * Signal_id hardening: the write runs for signal_id rows too, stamping
+ * `assigned_to` inside the FOR UPDATE transaction so a concurrent second caller
+ * sees `signal_already_claimed = true` and aborts. The resolve columns skip
+ * signal_id rows (CASE branches) — the workflow resolves durably.
+ *
+ * ONE UPDATE does both claim and resolve: Postgres does not support a second
+ * same-statement UPDATE of a row already updated by an earlier CTE (the second
+ * silently no-ops), so a chained claim→resolve pair leaves the row claimed but
+ * pending. The resolve columns ride the claim UPDATE as CASE branches instead.
  *
  * $1 = metadata filter (jsonb), $2 = userId, $3 = resolver_payload (jsonb),
  * $4 = metadata patch (jsonb, nullable), $5 = write_all roles (text[], null = global /
@@ -151,7 +156,7 @@ WITH target AS MATERIALIZED (
   LIMIT 1
   FOR UPDATE
 ),
-claimed AS (
+written AS (
   UPDATE public.hmsh_escalations e
   SET assigned_to = COALESCE(e.assigned_to, $2),
       claimed_at = COALESCE(e.claimed_at, NOW()),
@@ -164,26 +169,21 @@ claimed AS (
       metadata = CASE WHEN $4::jsonb IS NOT NULL
         THEN COALESCE(e.metadata, '{}'::jsonb) || $4::jsonb
         ELSE e.metadata END,
+      status = CASE WHEN (target.metadata->>'signal_id') IS NULL
+        THEN 'resolved' ELSE e.status END,
+      resolved_at = CASE WHEN (target.metadata->>'signal_id') IS NULL
+        THEN NOW() ELSE e.resolved_at END,
+      resolver_payload = CASE WHEN (target.metadata->>'signal_id') IS NULL
+        THEN $3 ELSE e.resolver_payload END,
       updated_at = NOW()
   FROM target
   WHERE e.id = target.id
     AND target.signal_key IS NULL
     AND ($7::text[] IS NULL OR NOT (target.role = ANY($7)))
   RETURNING e.*
-),
-resolved AS (
-  UPDATE public.hmsh_escalations e
-  SET status = 'resolved',
-      resolved_at = NOW(),
-      resolver_payload = $3,
-      updated_at = NOW()
-  FROM claimed
-  WHERE e.id = claimed.id
-    AND (claimed.metadata->>'signal_id') IS NULL
-  RETURNING e.*
 )
 SELECT
-  resolved.*,
+  written.*,
   target.id AS target_id,
   target.role AS target_role,
   target.metadata AS target_metadata,
@@ -198,12 +198,12 @@ SELECT
     AND target.assigned_until IS NOT NULL
     AND target.assigned_until > NOW()) AS signal_already_claimed,
   CASE
-    WHEN resolved.id IS NOT NULL THEN 'resolved'
+    WHEN written.status = 'resolved' THEN 'resolved'
     WHEN $7::text[] IS NOT NULL AND target.role = ANY($7) THEN 'validation_required'
     ELSE 'signal_required'
   END AS outcome
 FROM target
-LEFT JOIN resolved ON resolved.id = target.id`;
+LEFT JOIN written ON written.id = target.id`;
 // ---------------------------------------------------------------------------
 // Station metrics — split into two queries with very different cost profiles.
 //

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

@@ -0,0 +1,4 @@
+export { listScanSchemes, getScanScheme, listScanRules, getScanRule, } from './read';
+export { upsertScanScheme, deleteScanScheme, upsertScanRule, deleteScanRule, seedScanScheme, seedScanRule, 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

@@ -0,0 +1,21 @@
+"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;
+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; } });
+Object.defineProperty(exports, "listScanRules", { enumerable: true, get: function () { return read_1.listScanRules; } });
+Object.defineProperty(exports, "getScanRule", { enumerable: true, get: function () { return read_1.getScanRule; } });
+var write_1 = require("./write");
+Object.defineProperty(exports, "upsertScanScheme", { enumerable: true, get: function () { return write_1.upsertScanScheme; } });
+Object.defineProperty(exports, "deleteScanScheme", { enumerable: true, get: function () { return write_1.deleteScanScheme; } });
+Object.defineProperty(exports, "upsertScanRule", { enumerable: true, get: function () { return write_1.upsertScanRule; } });
+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; } });
+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; } });
+var validate_1 = require("./validate");
+Object.defineProperty(exports, "assertValidScheme", { enumerable: true, get: function () { return validate_1.assertValidScheme; } });
+Object.defineProperty(exports, "assertValidSteps", { enumerable: true, get: function () { return validate_1.assertValidSteps; } });

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

@@ -0,0 +1,35 @@
+import { type ParsedScanCode, type ScanScheme } from '../../types';
+export interface ScanParseFailure {
+    /** Why the code did not parse. */
+    reason: 'empty' | 'unknown_version' | 'scheme_disabled' | 'malformed';
+    detail: string;
+}
+export type ScanParseResult = {
+    ok: true;
+    parsed: ParsedScanCode;
+    scheme: ScanScheme;
+} | {
+    ok: false;
+    failure: ScanParseFailure;
+};
+/**
+ * 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)
+ */
+export declare function parseScanCode(raw: string, schemes: ScanScheme[]): ScanParseResult;
+export interface ScanTemplateContext {
+    target: string;
+    category: string;
+    scannedAt: string;
+}
+/**
+ * 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.
+ */
+export declare function interpolateScanTemplate<T>(value: T, ctx: ScanTemplateContext): T;