@hotmeshio/long-tail 0.10.11 → 0.10.14

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/resolver-validation.d.ts

@@ -23,6 +23,6 @@ export interface ResolverSchemaViolationReport {
  * surface's task fallback); by default the row's own envelope column is used.
  * It is only invoked when the role actually enforces.
  */
-export declare function checkResolverPayload(escalation: ResolvableEscalationRow, resolverPayload: Record<string, any>, loadEnvelope?: () => Promise<Record<string, any>>): Promise<ResolverSchemaViolationReport | null>;
+export declare function checkResolverPayload(escalation: ResolvableEscalationRow, resolverPayload: Record<string, any>, loadEnvelope?: () => Promise<Record<string, any>>, resolvingUserId?: string): Promise<ResolverSchemaViolationReport | null>;
 /** The canonical 422 body for a violation report (types/validation.ts). */
 export declare function toValidationErrorBody(report: ResolverSchemaViolationReport): LTValidationErrorBody;

package/build/services/escalation/resolver-validation.js

@@ -22,6 +22,7 @@ exports.toValidationErrorBody = toValidationErrorBody;
  * the gate passes.
  */
 const form_validation_1 = require("../../shared/form-validation");
+const submit_guard_1 = require("./submit-guard");
 const enforcement_cache_1 = require("../role/enforcement-cache");
 const escalation_1 = require("../../types/escalation");
 const validation_1 = require("../../types/validation");
@@ -54,7 +55,7 @@ function pinnedVersionOf(metadata) {
  * surface's task fallback); by default the row's own envelope column is used.
  * It is only invoked when the role actually enforces.
  */
-async function checkResolverPayload(escalation, resolverPayload, loadEnvelope) {
+async function checkResolverPayload(escalation, resolverPayload, loadEnvelope, resolvingUserId) {
     const role = escalation.role;
     if (!role)
         return null;
@@ -72,15 +73,21 @@ async function checkResolverPayload(escalation, resolverPayload, loadEnvelope) {
     const envelope = loadEnvelope
         ? await loadEnvelope()
         : parseJsonOrNull(escalation.envelope) ?? {};
-    const violations = (0, form_validation_1.validateResolverPayload)(schema, resolverPayload, {
+    const ctx = {
         escalation: escalation,
         metadata,
         envelope,
         payload: parseJsonOrNull(escalation.escalation_payload),
-    });
-    if (violations.length === 0)
+    };
+    const violations = (0, form_validation_1.validateResolverPayload)(schema, resolverPayload, ctx);
+    // The query precondition (x-lt-submit-guard): reject while the embedded query
+    // still returns rows. Enforced on the same enforce_schema opt-in as the field
+    // contract, so a raw-API resolve honors the gate the dashboard shows.
+    const guardViolation = await (0, submit_guard_1.checkSubmitGuard)(schema, ctx, resolvingUserId);
+    const allViolations = guardViolation ? [...violations, guardViolation] : violations;
+    if (allViolations.length === 0)
         return null;
-    return { role, schemaVersion: pin, violations };
+    return { role, schemaVersion: pin, violations: allViolations };
 }
 /** The canonical 422 body for a violation report (types/validation.ts). */
 function toValidationErrorBody(report) {

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/escalation/submit-guard.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Server-side enforcement of the `x-lt-submit-guard` query precondition — the
+ * API-first counterpart of the dashboard's `useSubmitGuard`. Before an
+ * escalation resolves, if its form schema declares a submit guard, the same
+ * embedded query runs and the resolve is REJECTED while it still returns rows.
+ *
+ * Isomorphism with the dashboard is exact: the guard reuses `resolveScopedQuery`
+ * (the mapping the escalation-list embed uses) and runs it through
+ * `searchEscalationsFaceted` — the same faceted query the list API composes.
+ *
+ * Two deliberate rules:
+ *  - The count is taken with `global: true`, bypassing the resolver's read
+ *    scope, so a role that cannot SEE the children can never falsely clear the
+ *    gate. Only a real, empty result count clears it (the "403 ≠ empty" rule).
+ *  - A guard whose scope cannot be evaluated (e.g. `assigned:'me'` on a surface
+ *    with no resolving user, like an MCP resolve) is skipped here; the consuming
+ *    workflow's own verification remains the durable backstop.
+ */
+import { type ShowIfContext } from '../../shared/form-validation';
+import type { LTFieldViolation } from '../../types/validation';
+/** The synthetic violation field for a guard rejection — not a form field. */
+export declare const SUBMIT_GUARD_VIOLATION_FIELD = "_submitGuard";
+/**
+ * Returns a violation when the escalation's submit guard still matches rows, or
+ * null when there is no guard, its scope is inert, or the query is confirmed
+ * empty. The context carries the escalation domains the query facets and the
+ * message interpolate against.
+ */
+export declare function checkSubmitGuard(schema: Record<string, any> | null | undefined, ctx: ShowIfContext, resolvingUserId: string | undefined): Promise<LTFieldViolation | null>;

package/build/services/escalation/submit-guard.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUBMIT_GUARD_VIOLATION_FIELD = void 0;
+exports.checkSubmitGuard = checkSubmitGuard;
+/**
+ * Server-side enforcement of the `x-lt-submit-guard` query precondition — the
+ * API-first counterpart of the dashboard's `useSubmitGuard`. Before an
+ * escalation resolves, if its form schema declares a submit guard, the same
+ * embedded query runs and the resolve is REJECTED while it still returns rows.
+ *
+ * Isomorphism with the dashboard is exact: the guard reuses `resolveScopedQuery`
+ * (the mapping the escalation-list embed uses) and runs it through
+ * `searchEscalationsFaceted` — the same faceted query the list API composes.
+ *
+ * Two deliberate rules:
+ *  - The count is taken with `global: true`, bypassing the resolver's read
+ *    scope, so a role that cannot SEE the children can never falsely clear the
+ *    gate. Only a real, empty result count clears it (the "403 ≠ empty" rule).
+ *  - A guard whose scope cannot be evaluated (e.g. `assigned:'me'` on a surface
+ *    with no resolving user, like an MCP resolve) is skipped here; the consuming
+ *    workflow's own verification remains the durable backstop.
+ */
+const form_validation_1 = require("../../shared/form-validation");
+const queries_1 = require("./queries");
+/** The synthetic violation field for a guard rejection — not a form field. */
+exports.SUBMIT_GUARD_VIOLATION_FIELD = '_submitGuard';
+/**
+ * Returns a violation when the escalation's submit guard still matches rows, or
+ * null when there is no guard, its scope is inert, or the query is confirmed
+ * empty. The context carries the escalation domains the query facets and the
+ * message interpolate against.
+ */
+async function checkSubmitGuard(schema, ctx, resolvingUserId) {
+    const guard = (0, form_validation_1.readSubmitGuard)(schema);
+    if (!guard || guard.mustBeEmpty === false)
+        return null;
+    const scoped = (0, form_validation_1.resolveScopedQuery)(guard.query, ctx, resolvingUserId);
+    if (!scoped.enabled)
+        return null;
+    const { total } = await (0, queries_1.searchEscalationsFaceted)({
+        global: true,
+        facet: {
+            role: scoped.role,
+            status: scoped.status,
+            available: scoped.available,
+            facets: scoped.facets,
+        },
+        assigned_to: scoped.assigned_to,
+        limit: 1,
+        offset: 0,
+    });
+    if (total <= 0)
+        return null;
+    const template = guard.message ?? form_validation_1.SUBMIT_GUARD_DEFAULT_MESSAGE;
+    const message = (0, form_validation_1.interpolateHelp)(template.replace(/\{\{count\}\}/g, String(total)), ctx);
+    return { field: exports.SUBMIT_GUARD_VIOLATION_FIELD, message };
+}

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;

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`;