@hotmeshio/long-tail 0.10.10 → 0.10.13

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/role/index.js

@@ -149,6 +149,7 @@ async function updateRoleMetadata(role, input) {
         provided('list_schema'), input.list_schema != null ? JSON.stringify(input.list_schema) : null,
         provided('default_pins'), input.default_pins != null ? JSON.stringify(input.default_pins) : null,
         provided('enforce_schema'), input.enforce_schema ?? null,
+        provided('ops_home_default'), input.ops_home_default ?? null,
     ]);
     if (!rows[0])
         return null;

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

@@ -46,8 +46,12 @@ export declare const DELETE_ROLE = "\n  DELETE FROM lt_roles WHERE role = $1";
  * enforce_schema ($33 = provided sentinel, $34 = value) is unversioned config:
  * the server-side resolver-validation opt-in. The service layer invalidates
  * the enforcement cache after this statement commits.
+ *
+ * ops_home_default ($35 = provided sentinel, $36 = value) is single-holder:
+ * setting it true clears the flag on every other role in the same statement
+ * (the home_clear CTE touches only OTHER rows, so the two UPDATEs never meet).
  */
-export declare const UPDATE_ROLE_METADATA = "\n  WITH updated AS (\n    UPDATE lt_roles SET\n      title           = CASE WHEN $2::boolean  THEN $3                                ELSE title           END,\n      description     = CASE WHEN $4::boolean  THEN $5                                ELSE description     END,\n      form_schema     = CASE WHEN $6::boolean  THEN $7::jsonb                         ELSE form_schema     END,\n      metadata_schema = CASE WHEN $8::boolean  THEN $9::jsonb                         ELSE metadata_schema END,\n      properties      = CASE WHEN $10::boolean THEN COALESCE($11::jsonb, '{}'::jsonb) ELSE properties      END,\n      ops_visible     = CASE WHEN $12::boolean THEN $13::boolean                      ELSE ops_visible     END,\n      parent_role     = CASE WHEN $14::boolean THEN $15                               ELSE parent_role     END,\n      sla_minutes     = CASE WHEN $16::boolean THEN $17::numeric                      ELSE sla_minutes     END,\n      target_per_hour = CASE WHEN $18::boolean THEN $19::numeric                      ELSE target_per_hour END,\n      worker_count    = CASE WHEN $20::boolean THEN $21::int                          ELSE worker_count    END,\n      priority_threshold_minutes\n                      = CASE WHEN $22::boolean THEN $23::numeric                      ELSE priority_threshold_minutes END,\n      priority_facet  = CASE WHEN $24::boolean THEN $25                               ELSE priority_facet  END,\n      list_schema     = CASE WHEN $29::boolean THEN $30::jsonb                        ELSE list_schema     END,\n      default_pins    = CASE WHEN $31::boolean THEN $32::jsonb                        ELSE default_pins    END,\n      enforce_schema  = CASE WHEN $33::boolean THEN COALESCE($34::boolean, false)     ELSE enforce_schema  END,\n      current_schema_version = CASE\n        WHEN ($6::boolean AND $7::jsonb IS DISTINCT FROM form_schema)\n          OR ($8::boolean AND $9::jsonb IS DISTINCT FROM metadata_schema)\n        THEN COALESCE(current_schema_version, 0) + 1\n        ELSE current_schema_version END,\n      current_list_schema_version = CASE\n        WHEN $29::boolean AND $30::jsonb IS DISTINCT FROM list_schema\n        THEN COALESCE(current_list_schema_version, 0) + 1\n        ELSE current_list_schema_version END\n    WHERE role = $1\n    RETURNING\n      role, title, description, form_schema, metadata_schema, properties,\n      ops_visible, parent_role, sla_minutes, target_per_hour, worker_count,\n      priority_threshold_minutes, priority_facet,\n      current_schema_version, list_schema, current_list_schema_version,\n      default_pins, enforce_schema\n  ), snapshot AS (\n    INSERT INTO lt_role_schemas (role, version, form_schema, metadata_schema, change_summary)\n    SELECT role, current_schema_version, form_schema, metadata_schema, $26\n    FROM updated\n    WHERE ($6::boolean OR $8::boolean) AND current_schema_version IS NOT NULL\n    ON CONFLICT (role, version) DO NOTHING\n  ), list_snapshot AS (\n    INSERT INTO lt_role_list_schemas (role, version, list_schema, change_summary)\n    SELECT role, current_list_schema_version, list_schema, $26\n    FROM updated\n    WHERE $29::boolean AND current_list_schema_version IS NOT NULL\n    ON CONFLICT (role, version) DO NOTHING\n  ), upstream_prune AS (\n    DELETE FROM lt_role_upstreams\n    WHERE $27::boolean AND role = $1 AND upstream_role <> ALL($28::text[])\n  ), upstream_add AS (\n    INSERT INTO lt_role_upstreams (role, upstream_role)\n    SELECT $1, u FROM unnest($28::text[]) AS u\n    WHERE $27::boolean\n    ON CONFLICT DO NOTHING\n  )\n  SELECT * FROM updated";
+export declare const UPDATE_ROLE_METADATA = "\n  WITH home_clear AS (\n    UPDATE lt_roles SET ops_home_default = false\n    WHERE $35::boolean AND COALESCE($36::boolean, false) AND role <> $1 AND ops_home_default\n  ), updated AS (\n    UPDATE lt_roles SET\n      title           = CASE WHEN $2::boolean  THEN $3                                ELSE title           END,\n      description     = CASE WHEN $4::boolean  THEN $5                                ELSE description     END,\n      form_schema     = CASE WHEN $6::boolean  THEN $7::jsonb                         ELSE form_schema     END,\n      metadata_schema = CASE WHEN $8::boolean  THEN $9::jsonb                         ELSE metadata_schema END,\n      properties      = CASE WHEN $10::boolean THEN COALESCE($11::jsonb, '{}'::jsonb) ELSE properties      END,\n      ops_visible     = CASE WHEN $12::boolean THEN $13::boolean                      ELSE ops_visible     END,\n      parent_role     = CASE WHEN $14::boolean THEN $15                               ELSE parent_role     END,\n      sla_minutes     = CASE WHEN $16::boolean THEN $17::numeric                      ELSE sla_minutes     END,\n      target_per_hour = CASE WHEN $18::boolean THEN $19::numeric                      ELSE target_per_hour END,\n      worker_count    = CASE WHEN $20::boolean THEN $21::int                          ELSE worker_count    END,\n      priority_threshold_minutes\n                      = CASE WHEN $22::boolean THEN $23::numeric                      ELSE priority_threshold_minutes END,\n      priority_facet  = CASE WHEN $24::boolean THEN $25                               ELSE priority_facet  END,\n      list_schema     = CASE WHEN $29::boolean THEN $30::jsonb                        ELSE list_schema     END,\n      default_pins    = CASE WHEN $31::boolean THEN $32::jsonb                        ELSE default_pins    END,\n      enforce_schema  = CASE WHEN $33::boolean THEN COALESCE($34::boolean, false)     ELSE enforce_schema  END,\n      ops_home_default = CASE WHEN $35::boolean THEN COALESCE($36::boolean, false)    ELSE ops_home_default END,\n      current_schema_version = CASE\n        WHEN ($6::boolean AND $7::jsonb IS DISTINCT FROM form_schema)\n          OR ($8::boolean AND $9::jsonb IS DISTINCT FROM metadata_schema)\n        THEN COALESCE(current_schema_version, 0) + 1\n        ELSE current_schema_version END,\n      current_list_schema_version = CASE\n        WHEN $29::boolean AND $30::jsonb IS DISTINCT FROM list_schema\n        THEN COALESCE(current_list_schema_version, 0) + 1\n        ELSE current_list_schema_version END\n    WHERE role = $1\n    RETURNING\n      role, title, description, form_schema, metadata_schema, properties,\n      ops_visible, ops_home_default, parent_role, sla_minutes, target_per_hour, worker_count,\n      priority_threshold_minutes, priority_facet,\n      current_schema_version, list_schema, current_list_schema_version,\n      default_pins, enforce_schema\n  ), snapshot AS (\n    INSERT INTO lt_role_schemas (role, version, form_schema, metadata_schema, change_summary)\n    SELECT role, current_schema_version, form_schema, metadata_schema, $26\n    FROM updated\n    WHERE ($6::boolean OR $8::boolean) AND current_schema_version IS NOT NULL\n    ON CONFLICT (role, version) DO NOTHING\n  ), list_snapshot AS (\n    INSERT INTO lt_role_list_schemas (role, version, list_schema, change_summary)\n    SELECT role, current_list_schema_version, list_schema, $26\n    FROM updated\n    WHERE $29::boolean AND current_list_schema_version IS NOT NULL\n    ON CONFLICT (role, version) DO NOTHING\n  ), upstream_prune AS (\n    DELETE FROM lt_role_upstreams\n    WHERE $27::boolean AND role = $1 AND upstream_role <> ALL($28::text[])\n  ), upstream_add AS (\n    INSERT INTO lt_role_upstreams (role, upstream_role)\n    SELECT $1, u FROM unnest($28::text[]) AS u\n    WHERE $27::boolean\n    ON CONFLICT DO NOTHING\n  )\n  SELECT * FROM updated";
 export declare const GET_ROLE_FORM_SCHEMA = "\n  SELECT form_schema FROM lt_roles WHERE role = $1";
 /**
  * The set of roles with server-side resolver validation turned on. Small and
@@ -71,7 +75,7 @@ export declare const GET_ROLE_LIST_SCHEMA_VERSION = "\n  SELECT s.role, s.versio
  * never versioned its list schema still answers, with version NULL).
  */
 export declare const GET_ROLE_LIST_SCHEMA_CURRENT = "\n  SELECT r.role, r.current_list_schema_version AS version, r.list_schema,\n         s.change_summary, s.created_at,\n         r.current_list_schema_version AS latest_version\n  FROM lt_roles r\n  LEFT JOIN lt_role_list_schemas s\n    ON s.role = r.role AND s.version = r.current_list_schema_version\n  WHERE r.role = $1";
-export declare const LIST_ROLES_WITH_DETAILS = "\n  WITH\n  user_counts AS (\n    SELECT role, COUNT(DISTINCT user_id)::int AS cnt\n    FROM lt_user_roles\n    GROUP BY role\n  ),\n  chain_counts AS (\n    SELECT role, COUNT(*)::int AS cnt\n    FROM (\n      SELECT source_role AS role FROM lt_config_role_escalations\n      UNION ALL\n      SELECT target_role AS role FROM lt_config_role_escalations\n    ) c\n    GROUP BY role\n  ),\n  workflow_counts AS (\n    SELECT role, COUNT(*)::int AS cnt\n    FROM lt_config_roles\n    GROUP BY role\n  ),\n  upstreams AS (\n    SELECT role, array_agg(upstream_role ORDER BY upstream_role) AS ups\n    FROM lt_role_upstreams\n    GROUP BY role\n  )\n  SELECT\n    r.role,\n    r.title,\n    r.description,\n    r.form_schema,\n    r.metadata_schema,\n    r.properties,\n    r.ops_visible,\n    r.parent_role,\n    r.sla_minutes,\n    r.target_per_hour,\n    r.worker_count,\n    r.priority_threshold_minutes,\n    r.priority_facet,\n    r.current_schema_version,\n    r.list_schema,\n    r.current_list_schema_version,\n    r.default_pins,\n    r.enforce_schema,\n    COALESCE(up.ups, '{}') AS upstream_roles,\n    COALESCE(uc.cnt, 0) AS user_count,\n    COALESCE(cc.cnt, 0) AS chain_count,\n    COALESCE(wc.cnt, 0) AS workflow_count\n  FROM lt_roles r\n  LEFT JOIN user_counts uc ON uc.role = r.role\n  LEFT JOIN chain_counts cc ON cc.role = r.role\n  LEFT JOIN workflow_counts wc ON wc.role = r.role\n  LEFT JOIN upstreams up ON up.role = r.role\n  ORDER BY r.role";
+export declare const LIST_ROLES_WITH_DETAILS = "\n  WITH\n  user_counts AS (\n    SELECT role, COUNT(DISTINCT user_id)::int AS cnt\n    FROM lt_user_roles\n    GROUP BY role\n  ),\n  chain_counts AS (\n    SELECT role, COUNT(*)::int AS cnt\n    FROM (\n      SELECT source_role AS role FROM lt_config_role_escalations\n      UNION ALL\n      SELECT target_role AS role FROM lt_config_role_escalations\n    ) c\n    GROUP BY role\n  ),\n  workflow_counts AS (\n    SELECT role, COUNT(*)::int AS cnt\n    FROM lt_config_roles\n    GROUP BY role\n  ),\n  upstreams AS (\n    SELECT role, array_agg(upstream_role ORDER BY upstream_role) AS ups\n    FROM lt_role_upstreams\n    GROUP BY role\n  )\n  SELECT\n    r.role,\n    r.title,\n    r.description,\n    r.form_schema,\n    r.metadata_schema,\n    r.properties,\n    r.ops_visible,\n    r.ops_home_default,\n    r.parent_role,\n    r.sla_minutes,\n    r.target_per_hour,\n    r.worker_count,\n    r.priority_threshold_minutes,\n    r.priority_facet,\n    r.current_schema_version,\n    r.list_schema,\n    r.current_list_schema_version,\n    r.default_pins,\n    r.enforce_schema,\n    COALESCE(up.ups, '{}') AS upstream_roles,\n    COALESCE(uc.cnt, 0) AS user_count,\n    COALESCE(cc.cnt, 0) AS chain_count,\n    COALESCE(wc.cnt, 0) AS workflow_count\n  FROM lt_roles r\n  LEFT JOIN user_counts uc ON uc.role = r.role\n  LEFT JOIN chain_counts cc ON cc.role = r.role\n  LEFT JOIN workflow_counts wc ON wc.role = r.role\n  LEFT JOIN upstreams up ON up.role = r.role\n  ORDER BY r.role";
 export declare const COUNT_USER_ROLE_REFS = "\n  SELECT COUNT(*)::int AS cnt FROM lt_user_roles WHERE role = $1";
 export declare const COUNT_CHAIN_REFS = "\n  SELECT COUNT(*)::int AS cnt\n  FROM lt_config_role_escalations\n  WHERE source_role = $1 OR target_role = $1";
 export declare const COUNT_WORKFLOW_REFS = "\n  SELECT COUNT(*)::int AS cnt FROM lt_config_roles WHERE role = $1";

package/build/services/role/sql.js

@@ -80,9 +80,16 @@ exports.DELETE_ROLE = `
  * enforce_schema ($33 = provided sentinel, $34 = value) is unversioned config:
  * the server-side resolver-validation opt-in. The service layer invalidates
  * the enforcement cache after this statement commits.
+ *
+ * ops_home_default ($35 = provided sentinel, $36 = value) is single-holder:
+ * setting it true clears the flag on every other role in the same statement
+ * (the home_clear CTE touches only OTHER rows, so the two UPDATEs never meet).
  */
 exports.UPDATE_ROLE_METADATA = `
-  WITH updated AS (
+  WITH home_clear AS (
+    UPDATE lt_roles SET ops_home_default = false
+    WHERE $35::boolean AND COALESCE($36::boolean, false) AND role <> $1 AND ops_home_default
+  ), updated AS (
     UPDATE lt_roles SET
       title           = CASE WHEN $2::boolean  THEN $3                                ELSE title           END,
       description     = CASE WHEN $4::boolean  THEN $5                                ELSE description     END,
@@ -100,6 +107,7 @@ exports.UPDATE_ROLE_METADATA = `
       list_schema     = CASE WHEN $29::boolean THEN $30::jsonb                        ELSE list_schema     END,
       default_pins    = CASE WHEN $31::boolean THEN $32::jsonb                        ELSE default_pins    END,
       enforce_schema  = CASE WHEN $33::boolean THEN COALESCE($34::boolean, false)     ELSE enforce_schema  END,
+      ops_home_default = CASE WHEN $35::boolean THEN COALESCE($36::boolean, false)    ELSE ops_home_default END,
       current_schema_version = CASE
         WHEN ($6::boolean AND $7::jsonb IS DISTINCT FROM form_schema)
           OR ($8::boolean AND $9::jsonb IS DISTINCT FROM metadata_schema)
@@ -112,7 +120,7 @@ exports.UPDATE_ROLE_METADATA = `
     WHERE role = $1
     RETURNING
       role, title, description, form_schema, metadata_schema, properties,
-      ops_visible, parent_role, sla_minutes, target_per_hour, worker_count,
+      ops_visible, ops_home_default, parent_role, sla_minutes, target_per_hour, worker_count,
       priority_threshold_minutes, priority_facet,
       current_schema_version, list_schema, current_list_schema_version,
       default_pins, enforce_schema
@@ -247,6 +255,7 @@ exports.LIST_ROLES_WITH_DETAILS = `
     r.metadata_schema,
     r.properties,
     r.ops_visible,
+    r.ops_home_default,
     r.parent_role,
     r.sla_minutes,
     r.target_per_hour,

package/build/services/role/types.d.ts

@@ -20,6 +20,13 @@ export interface RoleDetail {
     /** Free-form user-owned bag. No reserved keys — use for icons, colors, tags, etc. */
     properties: Record<string, any>;
     ops_visible: boolean;
+    /**
+     * Marks this role's sequence as the HOME page's default Pace Board segment.
+     * Single-holder: setting it on one role clears it everywhere else. Only
+     * meaningful while ops_visible is on; unset anywhere → the home board shows
+     * the primary (first) segment.
+     */
+    ops_home_default: boolean;
     parent_role: string | null;
     /** Target resolution time (minutes). Part of the ops triangle. */
     sla_minutes: number | null;
@@ -134,6 +141,8 @@ export interface UpdateRoleInput {
     }[] | null;
     properties?: Record<string, any> | null;
     ops_visible?: boolean;
+    /** Make this role's sequence the home Pace Board's default segment (single-holder). */
+    ops_home_default?: boolean;
     parent_role?: string | null;
     sla_minutes?: number | null;
     target_per_hour?: number | null;

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