@hotmeshio/long-tail 0.10.14 → 0.11.0

package/build/services/role/sql.js

@@ -84,6 +84,14 @@ exports.DELETE_ROLE = `
  * 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).
+ *
+ * entity_facet ($37 = provided sentinel, $38 = value) is unversioned config:
+ * the metadata key naming the entity that moves through this role (powers the
+ * analytics surfaces — entity counts, per-entity dwell, timelines).
+ *
+ * entity_state_source ($39 = provided sentinel, $40 = value) is unversioned
+ * config: 'role' | 'subtype' — how this role names its contribution to the
+ * entity's state space (the station itself, or its subtypes).
  */
 exports.UPDATE_ROLE_METADATA = `
   WITH home_clear AS (
@@ -104,6 +112,9 @@ exports.UPDATE_ROLE_METADATA = `
       priority_threshold_minutes
                       = CASE WHEN $22::boolean THEN $23::numeric                      ELSE priority_threshold_minutes END,
       priority_facet  = CASE WHEN $24::boolean THEN $25                               ELSE priority_facet  END,
+      entity_facet    = CASE WHEN $37::boolean THEN $38                               ELSE entity_facet    END,
+      entity_state_source
+                      = CASE WHEN $39::boolean THEN COALESCE($40, 'role')             ELSE entity_state_source END,
       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,
@@ -121,7 +132,7 @@ exports.UPDATE_ROLE_METADATA = `
     RETURNING
       role, title, description, form_schema, metadata_schema, properties,
       ops_visible, ops_home_default, parent_role, sla_minutes, target_per_hour, worker_count,
-      priority_threshold_minutes, priority_facet,
+      priority_threshold_minutes, priority_facet, entity_facet, entity_state_source,
       current_schema_version, list_schema, current_list_schema_version,
       default_pins, enforce_schema
   ), snapshot AS (
@@ -262,6 +273,8 @@ exports.LIST_ROLES_WITH_DETAILS = `
     r.worker_count,
     r.priority_threshold_minutes,
     r.priority_facet,
+    r.entity_facet,
+    r.entity_state_source,
     r.current_schema_version,
     r.list_schema,
     r.current_list_schema_version,

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

@@ -46,6 +46,19 @@ export interface RoleDetail {
      * an unparseable value are not counted.
      */
     priority_facet: string | null;
+    /**
+     * lt_escalations.metadata key identifying the ENTITY that moves through
+     * this role (e.g. serialNumber, orderId). Powers the analytics surfaces —
+     * distinct-entity counts, per-entity dwell, entity timelines. Null = the
+     * role has no entity notion.
+     */
+    entity_facet: string | null;
+    /**
+     * How this role names its contribution to the entity's state space:
+     * 'role' (the station itself is the state) or 'subtype' (the role's
+     * subtypes are its states). Only meaningful while entity_facet is set.
+     */
+    entity_state_source: 'role' | 'subtype';
     /**
      * Version of the live form_schema. Advances whenever the form (or
      * metadata_schema) changes; each version is snapshotted in lt_role_schemas so
@@ -149,6 +162,9 @@ export interface UpdateRoleInput {
     worker_count?: number | null;
     priority_threshold_minutes?: number | null;
     priority_facet?: string | null;
+    entity_facet?: string | null;
+    /** 'role' | 'subtype' — null resets to the 'role' default. */
+    entity_state_source?: 'role' | 'subtype' | null;
     /** Turn server-side resolver schema validation on/off for this role. */
     enforce_schema?: boolean;
     /**

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

@@ -15,6 +15,9 @@ function mapScheme(row) {
         encoding: row.encoding,
         delimiter: row.delimiter,
         target_length: row.target_length ?? null,
+        kind: row.kind ?? 'action',
+        grant_ttl_seconds: row.grant_ttl_seconds ?? null,
+        grant_max_uses: row.grant_max_uses ?? 0,
         enabled: row.enabled,
         created_at: row.created_at,
         updated_at: row.updated_at,
@@ -27,6 +30,7 @@ function mapRule(row) {
         name: row.name,
         steps: row.steps ?? [],
         fallback: row.fallback ?? {},
+        notPrimed: row.not_primed ?? {},
         enabled: row.enabled,
         created_at: row.created_at,
         updated_at: row.updated_at,

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

@@ -2,9 +2,9 @@ export declare const LIST_SCHEMES = "SELECT * FROM lt_config_scan_schemes ORDER
 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 UPSERT_SCHEME = "INSERT INTO lt_config_scan_schemes\n  (version, name, description, target_facet, encoding, delimiter, target_length,\n   kind, grant_ttl_seconds, grant_max_uses, enabled)\nVALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)\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  kind = EXCLUDED.kind,\n  grant_ttl_seconds = EXCLUDED.grant_ttl_seconds,\n  grant_max_uses = EXCLUDED.grant_max_uses,\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 UPSERT_ACTION = "INSERT INTO lt_config_scan_actions\n  (scheme_version, category, name, steps, fallback, not_primed, enabled)\nVALUES ($1, $2, $3, $4, $5, $6, $7)\nON CONFLICT (scheme_version, category) DO UPDATE SET\n  name = EXCLUDED.name,\n  steps = EXCLUDED.steps,\n  fallback = EXCLUDED.fallback,\n  not_primed = EXCLUDED.not_primed,\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";
+export declare const SEED_SCHEME = "INSERT INTO lt_config_scan_schemes\n  (version, name, description, target_facet, encoding, delimiter, target_length,\n   kind, grant_ttl_seconds, grant_max_uses, enabled)\nVALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)\nON CONFLICT (version) DO NOTHING";
+export declare const SEED_ACTION = "INSERT INTO lt_config_scan_actions\n  (scheme_version, category, name, steps, fallback, not_primed, enabled)\nVALUES ($1, $2, $3, $4, $5, $6, $7)\nON CONFLICT (scheme_version, category) DO NOTHING";

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

@@ -17,8 +17,9 @@ SELECT * FROM lt_config_scan_actions WHERE scheme_version = $1 AND category = $2
 // ------------------------------------------------------------------ //
 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)
+  (version, name, description, target_facet, encoding, delimiter, target_length,
+   kind, grant_ttl_seconds, grant_max_uses, enabled)
+VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)
 ON CONFLICT (version) DO UPDATE SET
   name = EXCLUDED.name,
   description = EXCLUDED.description,
@@ -26,18 +27,22 @@ ON CONFLICT (version) DO UPDATE SET
   encoding = EXCLUDED.encoding,
   delimiter = EXCLUDED.delimiter,
   target_length = EXCLUDED.target_length,
+  kind = EXCLUDED.kind,
+  grant_ttl_seconds = EXCLUDED.grant_ttl_seconds,
+  grant_max_uses = EXCLUDED.grant_max_uses,
   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)
+  (scheme_version, category, name, steps, fallback, not_primed, enabled)
+VALUES ($1, $2, $3, $4, $5, $6, $7)
 ON CONFLICT (scheme_version, category) DO UPDATE SET
   name = EXCLUDED.name,
   steps = EXCLUDED.steps,
   fallback = EXCLUDED.fallback,
+  not_primed = EXCLUDED.not_primed,
   enabled = EXCLUDED.enabled
 RETURNING *`;
 exports.DELETE_ACTION = `\
@@ -47,11 +52,12 @@ DELETE FROM lt_config_scan_actions WHERE scheme_version = $1 AND category = $2`;
 // ------------------------------------------------------------------ //
 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)
+  (version, name, description, target_facet, encoding, delimiter, target_length,
+   kind, grant_ttl_seconds, grant_max_uses, enabled)
+VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)
 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)
+  (scheme_version, category, name, steps, fallback, not_primed, enabled)
+VALUES ($1, $2, $3, $4, $5, $6, $7)
 ON CONFLICT (scheme_version, category) DO NOTHING`;

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

@@ -5,6 +5,8 @@ import { type ScanScheme, type ScanStep } from '../../types';
  * than a loud upsert failure.
  */
 export declare function assertValidScheme(scheme: Partial<ScanScheme>): void;
+/** Identity rules never walk steps — their fallback is the unknown-badge screen. */
+export declare function assertValidIdentityRule(steps: ScanStep[]): void;
 /**
  * Reject incoherent rule steps at write time: a rule that can never
  * execute its verb must fail the upsert, not the factory-floor scan.

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

@@ -1,9 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.assertValidScheme = assertValidScheme;
+exports.assertValidIdentityRule = assertValidIdentityRule;
 exports.assertValidSteps = assertValidSteps;
 const types_1 = require("../../types");
 const VALID_VERBS = new Set(Object.values(types_1.SCAN_VERBS));
+/** Double-scan selection tokens — short, label-printable, never scheme-shaped. */
+const CHOICE_CODE = /^[A-Za-z0-9_-]{1,32}$/;
 /**
  * Reject incoherent scheme config at write time. Throws with the exact
  * problem — a bad scheme silently misparsing every scan is far worse
@@ -32,6 +35,64 @@ function assertValidScheme(scheme) {
             throw new Error('delimiter must not be a digit');
         }
     }
+    const kind = scheme.kind ?? types_1.SCAN_SCHEME_KINDS.ACTION;
+    if (kind !== types_1.SCAN_SCHEME_KINDS.ACTION && kind !== types_1.SCAN_SCHEME_KINDS.IDENTITY) {
+        throw new Error(`unknown scheme kind "${kind}"`);
+    }
+    if (kind === types_1.SCAN_SCHEME_KINDS.IDENTITY) {
+        const ttl = scheme.grant_ttl_seconds;
+        if (!Number.isInteger(ttl) || ttl < 1 || ttl > 86_400) {
+            throw new Error('identity schemes require grant_ttl_seconds between 1 and 86400');
+        }
+        if (!Number.isInteger(scheme.grant_max_uses ?? 0) || (scheme.grant_max_uses ?? 0) < 0) {
+            throw new Error('grant_max_uses must be a non-negative integer');
+        }
+    }
+    else if (scheme.grant_ttl_seconds != null || (scheme.grant_max_uses ?? 0) !== 0) {
+        throw new Error('grant policy applies only to identity schemes');
+    }
+}
+/** Identity rules never walk steps — their fallback is the unknown-badge screen. */
+function assertValidIdentityRule(steps) {
+    if (Array.isArray(steps) && steps.length > 0) {
+        throw new Error('identity-scheme rules must have no steps (the fallback is the unknown-badge screen)');
+    }
+}
+/** Per-choice validation — a choice is a step verb with a label, minus locate concerns. */
+function assertValidChoices(choices, at) {
+    if (!Array.isArray(choices) || choices.length === 0) {
+        throw new Error(`${at}: present requires a non-empty choices array`);
+    }
+    const codes = new Set();
+    choices.forEach((choice, j) => {
+        const cat = `${at} choice ${j + 1}`;
+        if (!choice || typeof choice !== 'object')
+            throw new Error(`${cat} must be an object`);
+        if (!choice.label)
+            throw new Error(`${cat}: label is required`);
+        if (!VALID_VERBS.has(choice.verb))
+            throw new Error(`${cat}: unknown verb "${choice.verb}"`);
+        if (choice.verb === types_1.SCAN_VERBS.PRESENT || choice.verb === types_1.SCAN_VERBS.SHOW_LIST) {
+            throw new Error(`${cat}: ${choice.verb} cannot be a choice verb`);
+        }
+        if (choice.confirm && !choice.confirm.prompt) {
+            throw new Error(`${cat}: confirm requires a prompt`);
+        }
+        if (choice.verb === types_1.SCAN_VERBS.ESCALATE && !choice.params?.targetRole) {
+            throw new Error(`${cat}: escalate requires params.targetRole`);
+        }
+        if (choice.verb === types_1.SCAN_VERBS.RESOLVE && !choice.params?.resolverPayload) {
+            throw new Error(`${cat}: resolve requires params.resolverPayload`);
+        }
+        if (choice.code !== undefined) {
+            if (!CHOICE_CODE.test(choice.code)) {
+                throw new Error(`${cat}: code must be 1-32 letters, digits, underscore, or dash`);
+            }
+            if (codes.has(choice.code))
+                throw new Error(`${cat}: duplicate code "${choice.code}"`);
+            codes.add(choice.code);
+        }
+    });
 }
 /**
  * Reject incoherent rule steps at write time: a rule that can never
@@ -53,6 +114,31 @@ function assertValidSteps(steps) {
         if (step.confirm && !step.confirm.prompt) {
             throw new Error(`${at}: confirm requires a prompt`);
         }
+        // The classic confirm flow completes through per-id endpoints as the
+        // logged-in principal — it cannot carry an acting identity. Identity-gated
+        // ask-first flows are authored as PRESENT choices with confirm.
+        if (step.confirm && step.requireActingIdentity) {
+            throw new Error(`${at}: confirm and requireActingIdentity are incompatible — use a present step with a confirming choice`);
+        }
+        if (step.verb === types_1.SCAN_VERBS.PRESENT) {
+            if (step.confirm)
+                throw new Error(`${at}: present steps cannot carry confirm (choices confirm individually)`);
+            if (step.cardinality === 'many')
+                throw new Error(`${at}: present locates a single row (cardinality first)`);
+            assertValidChoices(step.choices, at);
+            if (step.autoSelectSingle && step.choices.length !== 1) {
+                throw new Error(`${at}: autoSelectSingle requires exactly one choice`);
+            }
+            if (step.autoSelectSingle && step.choices[0].confirm) {
+                throw new Error(`${at}: autoSelectSingle cannot skip a confirming choice — drop the confirm or the auto-select`);
+            }
+        }
+        else {
+            if (step.choices !== undefined)
+                throw new Error(`${at}: choices apply only to present steps`);
+            if (step.autoSelectSingle)
+                throw new Error(`${at}: autoSelectSingle applies only to present steps`);
+        }
         if (step.verb === types_1.SCAN_VERBS.ESCALATE && !step.params?.targetRole) {
             throw new Error(`${at}: escalate requires params.targetRole`);
         }

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

@@ -7,6 +7,9 @@ export interface ScanSchemeInput {
     encoding?: ScanScheme['encoding'];
     delimiter?: string;
     target_length?: number | null;
+    kind?: ScanScheme['kind'];
+    grant_ttl_seconds?: number | null;
+    grant_max_uses?: number;
     enabled?: boolean;
 }
 export interface ScanRuleInput {
@@ -15,6 +18,7 @@ export interface ScanRuleInput {
     name: string;
     steps: ScanStep[];
     fallback?: ScanRuleFallback;
+    notPrimed?: ScanRuleFallback;
     enabled?: boolean;
 }
 export declare function upsertScanScheme(input: ScanSchemeInput): Promise<ScanScheme>;

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

@@ -10,6 +10,7 @@ const db_1 = require("../../lib/db");
 const types_1 = require("../../types");
 const sql_1 = require("./sql");
 const validate_1 = require("./validate");
+const read_1 = require("./read");
 function schemeParams(input) {
     return [
         input.version,
@@ -19,6 +20,9 @@ function schemeParams(input) {
         input.encoding ?? types_1.SCAN_ENCODINGS.FIXED,
         input.delimiter ?? ':',
         input.target_length ?? null,
+        input.kind ?? types_1.SCAN_SCHEME_KINDS.ACTION,
+        input.grant_ttl_seconds ?? null,
+        input.grant_max_uses ?? 0,
         input.enabled ?? true,
     ];
 }
@@ -29,9 +33,19 @@ function ruleParams(input) {
         input.name,
         JSON.stringify(input.steps),
         JSON.stringify(input.fallback ?? {}),
+        JSON.stringify(input.notPrimed ?? {}),
         input.enabled ?? true,
     ];
 }
+/** Identity-scheme rules never walk steps; validated against the OWNING scheme's kind. */
+async function assertStepsForScheme(input) {
+    const scheme = await (0, read_1.getScanScheme)(input.scheme_version);
+    if (scheme?.kind === types_1.SCAN_SCHEME_KINDS.IDENTITY) {
+        (0, validate_1.assertValidIdentityRule)(input.steps);
+        return;
+    }
+    (0, validate_1.assertValidSteps)(input.steps);
+}
 async function upsertScanScheme(input) {
     (0, validate_1.assertValidScheme)(input);
     const { rows } = await (0, db_1.getPool)().query(sql_1.UPSERT_SCHEME, schemeParams(input));
@@ -47,7 +61,7 @@ async function upsertScanRule(input) {
     }
     if (!input.name)
         throw new Error('rule name is required');
-    (0, validate_1.assertValidSteps)(input.steps);
+    await assertStepsForScheme(input);
     if (input.steps.length === 0 && !input.fallback?.markdown && !input.fallback?.route) {
         throw new Error('a rule needs at least one step or a fallback');
     }
@@ -65,7 +79,7 @@ async function seedScanScheme(input) {
     return (rowCount ?? 0) > 0;
 }
 async function seedScanRule(input) {
-    (0, validate_1.assertValidSteps)(input.steps);
+    await assertStepsForScheme(input);
     const { rowCount } = await (0, db_1.getPool)().query(sql_1.SEED_ACTION, ruleParams(input));
     return (rowCount ?? 0) > 0;
 }

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

@@ -5,6 +5,12 @@ export declare function createUser(input: CreateUserInput): Promise<LTUserRecord
 export declare function getUser(id: string): Promise<LTUserRecord | null>;
 export declare function getUserByExternalId(externalId: string): Promise<LTUserRecord | null>;
 export declare function getUserByEmail(email: string): Promise<LTUserRecord | null>;
+/**
+ * Resolve an ACTIVE user by a metadata binding (e.g. metadata.badge_id).
+ * Two users carrying the same value is a configuration fault, not a pick —
+ * it throws so the binding gets fixed instead of misattributing work.
+ */
+export declare function getUserByMetadataValue(key: string, value: string): Promise<LTUserRecord | null>;
 export declare function updateUser(id: string, input: UpdateUserInput): Promise<LTUserRecord | null>;
 export declare function deleteUser(id: string): Promise<boolean>;
 export declare function listUsers(filters: {

package/build/services/user/crud.js

@@ -8,6 +8,7 @@ exports.createUser = createUser;
 exports.getUser = getUser;
 exports.getUserByExternalId = getUserByExternalId;
 exports.getUserByEmail = getUserByEmail;
+exports.getUserByMetadataValue = getUserByMetadataValue;
 exports.updateUser = updateUser;
 exports.deleteUser = deleteUser;
 exports.listUsers = listUsers;
@@ -93,6 +94,21 @@ async function getUserByEmail(email) {
         return null;
     return attachRoles(rows[0]);
 }
+/**
+ * Resolve an ACTIVE user by a metadata binding (e.g. metadata.badge_id).
+ * Two users carrying the same value is a configuration fault, not a pick —
+ * it throws so the binding gets fixed instead of misattributing work.
+ */
+async function getUserByMetadataValue(key, value) {
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.GET_USERS_BY_METADATA_VALUE, [key, value]);
+    if (rows.length === 0)
+        return null;
+    if (rows.length > 1) {
+        throw new Error(`metadata binding "${key}" is ambiguous — multiple users carry the same value`);
+    }
+    return attachRoles(rows[0]);
+}
 async function updateUser(id, input) {
     const pool = (0, db_1.getPool)();
     const sets = [];

package/build/services/user/index.d.ts

@@ -1,5 +1,5 @@
 export { CreateUserInput, UpdateUserInput, VALID_ROLE_TYPES } from './types';
-export { createUser, getUser, getUserByExternalId, getUserByEmail, updateUser, deleteUser, listUsers, } from './crud';
+export { createUser, getUser, getUserByExternalId, getUserByEmail, getUserByMetadataValue, updateUser, deleteUser, listUsers, } from './crud';
 export { isValidRoleType, addUserRole, removeUserRole, getUserRoles, hasRole, hasRoleType, } from './roles';
 export { isSuperAdmin, isGroupAdmin, canManageRole, hasGlobalEscalationAccess, hasRolesAsAdmin, getRoleScope, getRoleWriteScope } from './rbac';
 export { READ_SCOPES, WRITE_SCOPES, DEFAULT_READ_SCOPE, DEFAULT_WRITE_SCOPE, isValidReadScope, isValidWriteScope, isValidScopePair, effectiveScope, } from './scope';

package/build/services/user/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PREFERENCES_MAX_BYTES = exports.patchPreferences = exports.getPreferences = exports.seedAdmin = exports.verifyPassword = exports.effectiveScope = exports.isValidScopePair = exports.isValidWriteScope = exports.isValidReadScope = exports.DEFAULT_WRITE_SCOPE = exports.DEFAULT_READ_SCOPE = exports.WRITE_SCOPES = exports.READ_SCOPES = exports.getRoleWriteScope = exports.getRoleScope = exports.hasRolesAsAdmin = exports.hasGlobalEscalationAccess = exports.canManageRole = exports.isGroupAdmin = exports.isSuperAdmin = exports.hasRoleType = exports.hasRole = exports.getUserRoles = exports.removeUserRole = exports.addUserRole = exports.isValidRoleType = exports.listUsers = exports.deleteUser = exports.updateUser = exports.getUserByEmail = exports.getUserByExternalId = exports.getUser = exports.createUser = exports.VALID_ROLE_TYPES = void 0;
+exports.PREFERENCES_MAX_BYTES = exports.patchPreferences = exports.getPreferences = exports.seedAdmin = exports.verifyPassword = exports.effectiveScope = exports.isValidScopePair = exports.isValidWriteScope = exports.isValidReadScope = exports.DEFAULT_WRITE_SCOPE = exports.DEFAULT_READ_SCOPE = exports.WRITE_SCOPES = exports.READ_SCOPES = exports.getRoleWriteScope = exports.getRoleScope = exports.hasRolesAsAdmin = exports.hasGlobalEscalationAccess = exports.canManageRole = exports.isGroupAdmin = exports.isSuperAdmin = exports.hasRoleType = exports.hasRole = exports.getUserRoles = exports.removeUserRole = exports.addUserRole = exports.isValidRoleType = exports.listUsers = exports.deleteUser = exports.updateUser = exports.getUserByMetadataValue = exports.getUserByEmail = exports.getUserByExternalId = exports.getUser = exports.createUser = exports.VALID_ROLE_TYPES = void 0;
 var types_1 = require("./types");
 Object.defineProperty(exports, "VALID_ROLE_TYPES", { enumerable: true, get: function () { return types_1.VALID_ROLE_TYPES; } });
 var crud_1 = require("./crud");
@@ -8,6 +8,7 @@ Object.defineProperty(exports, "createUser", { enumerable: true, get: function (
 Object.defineProperty(exports, "getUser", { enumerable: true, get: function () { return crud_1.getUser; } });
 Object.defineProperty(exports, "getUserByExternalId", { enumerable: true, get: function () { return crud_1.getUserByExternalId; } });
 Object.defineProperty(exports, "getUserByEmail", { enumerable: true, get: function () { return crud_1.getUserByEmail; } });
+Object.defineProperty(exports, "getUserByMetadataValue", { enumerable: true, get: function () { return crud_1.getUserByMetadataValue; } });
 Object.defineProperty(exports, "updateUser", { enumerable: true, get: function () { return crud_1.updateUser; } });
 Object.defineProperty(exports, "deleteUser", { enumerable: true, get: function () { return crud_1.deleteUser; } });
 Object.defineProperty(exports, "listUsers", { enumerable: true, get: function () { return crud_1.listUsers; } });

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

@@ -18,6 +18,14 @@ export declare const GET_USER_BY_EXTERNAL_ID = "SELECT * FROM lt_users WHERE ext
 export declare const CREATE_USER_WITH_ROLES = "WITH new_user AS (\n     INSERT INTO lt_users (external_id, email, display_name, status, metadata, password_hash, oauth_provider, oauth_provider_id)\n     VALUES ($1, $2, $3, $4, $5, $6, $7, $8)\n     RETURNING *\n   ), ensured_roles AS (\n     INSERT INTO lt_roles (role)\n     SELECT DISTINCT unnest($9::text[])\n     ON CONFLICT DO NOTHING\n   ), assigned_roles AS (\n     INSERT INTO lt_user_roles (user_id, role, type, read_scope, write_scope)\n     SELECT (SELECT id FROM new_user), x.role, x.type, x.read_scope, x.write_scope\n     FROM unnest($9::text[], $10::text[], $11::text[], $12::text[]) AS x(role, type, read_scope, write_scope)\n     ON CONFLICT DO NOTHING\n   )\n   SELECT * FROM new_user";
 export declare const GET_USER_BY_EMAIL = "SELECT * FROM lt_users WHERE email = $1 LIMIT 1";
 export declare const GET_USER_BY_ID = "SELECT * FROM lt_users WHERE id = $1";
+/**
+ * Lookup by a caller-named metadata key (e.g. a badge binding). LIMIT 2 so an
+ * ambiguous binding — two users carrying the same value — is detectable and
+ * can fail loudly rather than silently picking one. Seq scan by design: this
+ * is the people table (small); revisit with a GIN index on metadata if a
+ * deployment ever holds tens of thousands of users.
+ */
+export declare const GET_USERS_BY_METADATA_VALUE = "SELECT * FROM lt_users WHERE metadata->>$1 = $2 AND status = 'active' LIMIT 2";
 /** Check if a user exists by id. Lightweight — returns only the id column. */
 export declare const VERIFY_USER_BY_ID = "SELECT id FROM lt_users WHERE id = $1 LIMIT 1";
 /** Fetch user + roles in a single query. Returns one row per role (or one row with nulls if no roles). */

package/build/services/user/sql.js

@@ -1,7 +1,7 @@
 "use strict";
 // ─── Shared queries (used by multiple modules) ──────────────────────────────
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.IS_GROUP_ADMIN = exports.GET_ROLE_SCOPE = exports.HAS_ROLE_TYPE = exports.HAS_ROLE = exports.DELETE_USER_ROLE = exports.UPSERT_USER_ROLE = exports.GET_ROLES_BY_USER_IDS = exports.DELETE_USER_BY_ID = exports.GET_USER_WITH_ROLES = exports.VERIFY_USER_BY_ID = exports.GET_USER_BY_ID = exports.GET_USER_BY_EMAIL = exports.CREATE_USER_WITH_ROLES = exports.GET_USER_BY_EXTERNAL_ID = exports.GET_ROLES_BY_USER_ID = exports.ENSURE_ROLE_EXISTS = void 0;
+exports.IS_GROUP_ADMIN = exports.GET_ROLE_SCOPE = exports.HAS_ROLE_TYPE = exports.HAS_ROLE = exports.DELETE_USER_ROLE = exports.UPSERT_USER_ROLE = exports.GET_ROLES_BY_USER_IDS = exports.DELETE_USER_BY_ID = exports.GET_USER_WITH_ROLES = exports.VERIFY_USER_BY_ID = exports.GET_USERS_BY_METADATA_VALUE = exports.GET_USER_BY_ID = exports.GET_USER_BY_EMAIL = exports.CREATE_USER_WITH_ROLES = exports.GET_USER_BY_EXTERNAL_ID = exports.GET_ROLES_BY_USER_ID = exports.ENSURE_ROLE_EXISTS = void 0;
 /** Ensure a role name exists in the lt_roles lookup table (FK target). */
 exports.ENSURE_ROLE_EXISTS = 'INSERT INTO lt_roles (role) VALUES ($1) ON CONFLICT DO NOTHING';
 /** Fetch roles for a single user, ordered by creation time. granted_by_persona
@@ -40,6 +40,14 @@ exports.CREATE_USER_WITH_ROLES = `WITH new_user AS (
    SELECT * FROM new_user`;
 exports.GET_USER_BY_EMAIL = `SELECT * FROM lt_users WHERE email = $1 LIMIT 1`;
 exports.GET_USER_BY_ID = 'SELECT * FROM lt_users WHERE id = $1';
+/**
+ * Lookup by a caller-named metadata key (e.g. a badge binding). LIMIT 2 so an
+ * ambiguous binding — two users carrying the same value — is detectable and
+ * can fail loudly rather than silently picking one. Seq scan by design: this
+ * is the people table (small); revisit with a GIN index on metadata if a
+ * deployment ever holds tens of thousands of users.
+ */
+exports.GET_USERS_BY_METADATA_VALUE = `SELECT * FROM lt_users WHERE metadata->>$1 = $2 AND status = 'active' LIMIT 2`;
 /** Check if a user exists by id. Lightweight — returns only the id column. */
 exports.VERIFY_USER_BY_ID = 'SELECT id FROM lt_users WHERE id = $1 LIMIT 1';
 /** Fetch user + roles in a single query. Returns one row per role (or one row with nulls if no roles). */

package/build/system/mcp-servers/admin/escalations.js

@@ -259,6 +259,40 @@ function registerEscalationTools(server) {
         }
         return { content: [{ type: 'text', text: JSON.stringify(result.data) }] };
     });
+    // mirrors POST /api/escalations/aggregate-by-facets
+    server.registerTool('aggregate_by_facets', {
+        title: 'Aggregate by Facets',
+        description: 'Grouped analytics over the escalation intervals. Every escalation is one open ' +
+            'interval [created_at, ended_at); this tool reads it two ways: membership (rows or, ' +
+            'with distinctBy, distinct entities open at an instant — a past asOf reconstructs the ' +
+            'live set then) and dwell (open-seconds per group within a half-open [from,to) window). ' +
+            'Group by role/subtype/status columns plus metadata facet keys; optional states[] label ' +
+            'each group. One call replaces N per-filter count round-trips. The filter takes the WHAT ' +
+            'fields only — status/available/jeopardy are rejected (liveness derives from the measure).',
+        inputSchema: schemas_1.aggregateByFacetsSchema,
+    }, async (args) => {
+        const result = await escalationApi.aggregateByFacets(args, await systemAuth());
+        if (result.error) {
+            return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(result.data) }] };
+    });
+    // mirrors POST /api/escalations/timeline-by-facet
+    server.registerTool('timeline_by_facet', {
+        title: 'Timeline by Facet',
+        description: 'One entity\'s ordered interval sequence — every escalation the entity facet ' +
+            '(e.g. a machine id) appeared in, as [startedAt, endedAt) spans with durations, in ' +
+            'created_at order. Open intervals report endedAt: null. Gaps between consecutive ' +
+            'intervals are untracked time and are preserved, not filled. The entity facet value ' +
+            'must be stored as a JSON string (GIN containment match).',
+        inputSchema: schemas_1.timelineByFacetSchema,
+    }, async (args) => {
+        const result = await escalationApi.timelineByFacet(args, await systemAuth());
+        if (result.error) {
+            return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(result.data) }] };
+    });
     // mirrors POST /api/escalations/claim-groups
     server.registerTool('claim_groups', {
         title: 'Claim Groups',

package/build/system/mcp-servers/admin/scan-codes.js

@@ -56,7 +56,23 @@ function registerScanCodeTools(server) {
             'no_match_fallback, unconfigured, invalid_code, forbidden, conflict).',
         inputSchema: schemas_1.executeScanCodeSchema,
     }, async (args) => {
-        const result = await scanCodesApi.executeScanCode({ code: args.code }, await systemAuth());
+        const result = await scanCodesApi.executeScanCode({
+            code: args.code,
+            actingToken: args.actingToken,
+            previousActingToken: args.previousActingToken,
+        }, await systemAuth());
+        return asText(result.data ?? { error: result.error });
+    });
+    // mirrors POST /api/scan-codes/execute-choice
+    server.registerTool('execute_scan_choice', {
+        title: 'Execute Scan Choice',
+        description: 'Execute one choice presented by a PRESENT step (the info-choice screen). ' +
+            'The pointer (scheme/category/step/choice + escalationId) is re-validated ' +
+            'against live config, the row\'s current state, the acting-identity gate, ' +
+            'and RBAC before the verb runs.',
+        inputSchema: schemas_1.executeScanChoiceSchema,
+    }, async (args) => {
+        const result = await scanCodesApi.executeScanChoice(args, await systemAuth());
         return asText(result.data ?? { error: result.error });
     });
     // mirrors GET /api/scan-codes/schemes