@hotmeshio/long-tail 0.22.0 → 0.22.2

package/build/services/iam/acting-identity.js

@@ -33,28 +33,71 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ACTING_ERRORS = void 0;
+exports.peekActingAuth = peekActingAuth;
+exports.consumeActingGrant = consumeActingGrant;
+exports.refundActingGrant = refundActingGrant;
 exports.resolveActingAuth = resolveActingAuth;
 const userService = __importStar(require("../user"));
 const ephemeral_1 = require("./ephemeral");
 const types_1 = require("../../types");
+exports.ACTING_ERRORS = {
+    NOT_A_GRANT: 'actingToken is not an acting-identity grant',
+    EXPIRED: 'acting identity expired — scan your badge again',
+    INACTIVE: 'acting identity is no longer an active user',
+    OTHER_SUBJECT: 'this badge already acted on another item; scan your badge again',
+};
+function isActingGrant(actingToken) {
+    const parsed = (0, ephemeral_1.parseEphemeralToken)(actingToken);
+    return parsed && parsed.label === types_1.ACTING_IDENTITY_LABEL ? parsed.uuid : null;
+}
+async function toAuth(grant, consumed) {
+    const user = await userService.getUser(grant.value);
+    if (!user || user.status !== 'active')
+        return { ok: false, error: exports.ACTING_ERRORS.INACTIVE };
+    return {
+        ok: true,
+        auth: { userId: user.id },
+        grant: { consumed, remaining: grant.remaining, bound: grant.bound },
+    };
+}
 /**
- * Exchange a supplied acting grant for the person it names. A supplied token
- * that fails — wrong label, expired, exhausted, or a vanished user — is a
- * terminal error, never a silent fall-back to the session identity: that
- * would misattribute whatever follows.
+ * Read a supplied acting grant without spending it. A token that fails
+ * (wrong label, expired, exhausted, or a vanished user) is a terminal error,
+ * never a silent fall-back to the session identity: that would misattribute
+ * whatever follows.
  */
-async function resolveActingAuth(actingToken) {
-    const parsed = (0, ephemeral_1.parseEphemeralToken)(actingToken);
-    if (!parsed || parsed.label !== types_1.ACTING_IDENTITY_LABEL) {
-        return { ok: false, error: 'actingToken is not an acting-identity grant' };
-    }
-    const userId = await (0, ephemeral_1.exchangeEphemeralToken)(actingToken);
-    if (!userId) {
-        return { ok: false, error: 'acting identity expired — scan your badge again' };
-    }
-    const user = await userService.getUser(userId);
-    if (!user || user.status !== 'active') {
-        return { ok: false, error: 'acting identity is no longer an active user' };
+async function peekActingAuth(actingToken) {
+    const uuid = isActingGrant(actingToken);
+    if (!uuid)
+        return { ok: false, error: exports.ACTING_ERRORS.NOT_A_GRANT };
+    const grant = await (0, ephemeral_1.peekEphemeral)(uuid);
+    if (!grant)
+        return { ok: false, error: exports.ACTING_ERRORS.EXPIRED };
+    return toAuth(grant, false);
+}
+/**
+ * Spend one use of the grant for an act. `ref` names the subject the act
+ * lands on; a subject-scoped grant binds to it on first spend.
+ */
+async function consumeActingGrant(actingToken, ref = null) {
+    const uuid = isActingGrant(actingToken);
+    if (!uuid)
+        return { ok: false, error: exports.ACTING_ERRORS.NOT_A_GRANT };
+    const grant = await (0, ephemeral_1.consumeEphemeral)(uuid, ref);
+    if (!grant) {
+        const live = ref ? await (0, ephemeral_1.peekEphemeral)(uuid) : null;
+        return { ok: false, error: live?.bound ? exports.ACTING_ERRORS.OTHER_SUBJECT : exports.ACTING_ERRORS.EXPIRED };
     }
-    return { ok: true, auth: { userId: user.id } };
+    return toAuth(grant, true);
+}
+/** Return a use whose act missed. `unbind` when that spend bound the grant. */
+async function refundActingGrant(actingToken, unbind) {
+    const uuid = isActingGrant(actingToken);
+    if (uuid)
+        await (0, ephemeral_1.refundEphemeral)(uuid, unbind);
+}
+/** Spend the grant up front: the escalation work routes always act. */
+async function resolveActingAuth(actingToken) {
+    return consumeActingGrant(actingToken);
 }

package/build/services/iam/ephemeral.d.ts

@@ -21,6 +21,8 @@ export interface StoreEphemeralOptions {
     ttlSeconds?: number;
     /** Human-readable label for debugging. */
     label?: string;
+    /** The first ref-carrying spend binds the token to that ref (see consumeEphemeral). */
+    bindOnUse?: boolean;
 }
 /**
  * Store a sensitive value. Returns the raw token UUID.
@@ -40,6 +42,25 @@ export declare function storeEphemeral(value: string, opts?: StoreEphemeralOptio
  * - Row is deleted when use_count reaches max_uses (if max_uses > 0)
  */
 export declare function exchangeEphemeral(token: string): Promise<string | null>;
+/** A live token's value and how many uses it has left (null = unbounded). */
+export interface EphemeralGrant {
+    value: string;
+    remaining: number | null;
+    /** True once the token is bound to a ref; it then acts only on that ref. */
+    bound: boolean;
+}
+/** Read a live token without spending a use. */
+export declare function peekEphemeral(token: string): Promise<EphemeralGrant | null>;
+/**
+ * Spend one use of a token. A token stored with `bindOnUse` binds to `ref`
+ * on its first ref-carrying spend; after that it spends freely on that ref
+ * and never on another. Returns null when expired, exhausted, or bound
+ * elsewhere. An exhausted row stays until its TTL so a spend whose act
+ * missed can be refunded.
+ */
+export declare function consumeEphemeral(token: string, ref?: string | null): Promise<EphemeralGrant | null>;
+/** Undo one spend whose act did not land. `unbind` undoes the binding that spend made. */
+export declare function refundEphemeral(token: string, unbind: boolean): Promise<void>;
 /**
  * Explicitly revoke a token before expiry/exhaustion.
  */

package/build/services/iam/ephemeral.js

@@ -7,6 +7,9 @@ exports.exchangeEphemeralToken = exchangeEphemeralToken;
 exports.exchangeTokensInArgs = exchangeTokensInArgs;
 exports.storeEphemeral = storeEphemeral;
 exports.exchangeEphemeral = exchangeEphemeral;
+exports.peekEphemeral = peekEphemeral;
+exports.consumeEphemeral = consumeEphemeral;
+exports.refundEphemeral = refundEphemeral;
 exports.revokeEphemeral = revokeEphemeral;
 exports.cleanupExpired = cleanupExpired;
 const db_1 = require("../../lib/db");
@@ -81,7 +84,7 @@ async function storeEphemeral(value, opts = {}) {
     const expiresAt = opts.ttlSeconds
         ? `NOW() + ${opts.ttlSeconds} * INTERVAL '1 second'`
         : 'NULL';
-    const { rows } = await pool.query((0, sql_1.INSERT_EPHEMERAL)(expiresAt), [Buffer.from(encrypted, 'base64'), opts.label || null, maxUses]);
+    const { rows } = await pool.query((0, sql_1.INSERT_EPHEMERAL)(expiresAt), [Buffer.from(encrypted, 'base64'), opts.label || null, maxUses, opts.bindOnUse ?? false]);
     return rows[0].token;
 }
 /**
@@ -106,6 +109,34 @@ async function exchangeEphemeral(token) {
     }
     return (0, crypto_1.decrypt)(buf.toString('base64'));
 }
+function toGrant(row) {
+    const bound = row.bound_ref !== null;
+    return {
+        value: (0, crypto_1.decrypt)(row.value.toString('base64')),
+        remaining: bound || row.max_uses === 0 ? null : Math.max(0, row.max_uses - row.use_count),
+        bound,
+    };
+}
+/** Read a live token without spending a use. */
+async function peekEphemeral(token) {
+    const { rows } = await (0, db_1.getPool)().query(sql_1.PEEK_EPHEMERAL, [token]);
+    return rows.length ? toGrant(rows[0]) : null;
+}
+/**
+ * Spend one use of a token. A token stored with `bindOnUse` binds to `ref`
+ * on its first ref-carrying spend; after that it spends freely on that ref
+ * and never on another. Returns null when expired, exhausted, or bound
+ * elsewhere. An exhausted row stays until its TTL so a spend whose act
+ * missed can be refunded.
+ */
+async function consumeEphemeral(token, ref = null) {
+    const { rows } = await (0, db_1.getPool)().query(sql_1.CONSUME_EPHEMERAL, [token, ref]);
+    return rows.length ? toGrant(rows[0]) : null;
+}
+/** Undo one spend whose act did not land. `unbind` undoes the binding that spend made. */
+async function refundEphemeral(token, unbind) {
+    await (0, db_1.getPool)().query(sql_1.REFUND_EPHEMERAL, [token, unbind]);
+}
 /**
  * Explicitly revoke a token before expiry/exhaustion.
  */

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

@@ -1,6 +1,16 @@
 /** Build INSERT for ephemeral credentials. expiresExpr is a SQL expression like 'NULL' or "NOW() + N * INTERVAL '1 second'". */
 export declare const INSERT_EPHEMERAL: (expiresExpr: string) => string;
 export declare const EXCHANGE_EPHEMERAL = "\n  UPDATE lt_ephemeral_credentials\n  SET use_count = use_count + 1\n  WHERE token = $1\n    AND (expires_at IS NULL OR expires_at > NOW())\n    AND (max_uses = 0 OR use_count < max_uses)\n  RETURNING value, use_count, max_uses";
+/** Validity check without spending a use. A bound grant stays live until its TTL. */
+export declare const PEEK_EPHEMERAL = "\n  SELECT value, use_count, max_uses, bound_ref\n  FROM lt_ephemeral_credentials\n  WHERE token = $1\n    AND (expires_at IS NULL OR expires_at > NOW())\n    AND (bound_ref IS NOT NULL OR max_uses = 0 OR use_count < max_uses)";
+/**
+ * Spend one use, binding a bind_on_use grant to $2 on its first spend.
+ * A bound grant acts again on its own ref without counting, and never on
+ * another ref. Without a ref ($2 NULL) the grant counts like any other.
+ */
+export declare const CONSUME_EPHEMERAL = "\n  UPDATE lt_ephemeral_credentials\n  SET use_count = CASE WHEN bound_ref IS NOT NULL THEN use_count ELSE use_count + 1 END,\n      bound_ref = CASE WHEN bind_on_use AND bound_ref IS NULL THEN $2::text ELSE bound_ref END\n  WHERE token = $1\n    AND (expires_at IS NULL OR expires_at > NOW())\n    AND (\n      (bound_ref IS NOT NULL AND bound_ref = $2::text)\n      OR (bound_ref IS NULL AND (max_uses = 0 OR use_count < max_uses))\n    )\n  RETURNING value, use_count, max_uses, bound_ref";
+/** Return a use an act spent but did not land; $2 also undoes the binding that spend made. */
+export declare const REFUND_EPHEMERAL = "\n  UPDATE lt_ephemeral_credentials\n  SET use_count = GREATEST(use_count - 1, 0),\n      bound_ref = CASE WHEN $2::boolean THEN NULL ELSE bound_ref END\n  WHERE token = $1";
 export declare const DELETE_EPHEMERAL = "\n  DELETE FROM lt_ephemeral_credentials WHERE token = $1";
 export declare const CLEANUP_EXPIRED_EPHEMERAL = "\n  DELETE FROM lt_ephemeral_credentials\n  WHERE expires_at IS NOT NULL AND expires_at < NOW()";
 export declare const LIST_BOTS = "\n  SELECT * FROM lt_users\n  WHERE account_type = 'bot'\n    AND ($3::text IS NULL OR status = $3)\n    AND ($4::text IS NULL\n      OR display_name ILIKE '%' || $4 || '%'\n      OR external_id ILIKE '%' || $4 || '%'\n      OR metadata->>'description' ILIKE '%' || $4 || '%')\n  ORDER BY created_at DESC\n  LIMIT $1 OFFSET $2";

package/build/services/iam/sql.js

@@ -1,11 +1,11 @@
 "use strict";
 // ─── Ephemeral credentials ──────────────────────────────────────────────────
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GET_USER_WITH_ROLES_FLEXIBLE = exports.GET_USER_BY_EXTERNAL_ID = exports.SET_ACCOUNT_TYPE_BOT = exports.COUNT_BOTS = exports.LIST_BOTS = exports.CLEANUP_EXPIRED_EPHEMERAL = exports.DELETE_EPHEMERAL = exports.EXCHANGE_EPHEMERAL = exports.INSERT_EPHEMERAL = void 0;
+exports.GET_USER_WITH_ROLES_FLEXIBLE = exports.GET_USER_BY_EXTERNAL_ID = exports.SET_ACCOUNT_TYPE_BOT = exports.COUNT_BOTS = exports.LIST_BOTS = exports.CLEANUP_EXPIRED_EPHEMERAL = exports.DELETE_EPHEMERAL = exports.REFUND_EPHEMERAL = exports.CONSUME_EPHEMERAL = exports.PEEK_EPHEMERAL = exports.EXCHANGE_EPHEMERAL = exports.INSERT_EPHEMERAL = void 0;
 /** Build INSERT for ephemeral credentials. expiresExpr is a SQL expression like 'NULL' or "NOW() + N * INTERVAL '1 second'". */
 const INSERT_EPHEMERAL = (expiresExpr) => `
-  INSERT INTO lt_ephemeral_credentials (value, label, max_uses, expires_at)
-  VALUES ($1, $2, $3, ${expiresExpr})
+  INSERT INTO lt_ephemeral_credentials (value, label, max_uses, bind_on_use, expires_at)
+  VALUES ($1, $2, $3, $4, ${expiresExpr})
   RETURNING token`;
 exports.INSERT_EPHEMERAL = INSERT_EPHEMERAL;
 exports.EXCHANGE_EPHEMERAL = `
@@ -15,6 +15,35 @@ exports.EXCHANGE_EPHEMERAL = `
     AND (expires_at IS NULL OR expires_at > NOW())
     AND (max_uses = 0 OR use_count < max_uses)
   RETURNING value, use_count, max_uses`;
+/** Validity check without spending a use. A bound grant stays live until its TTL. */
+exports.PEEK_EPHEMERAL = `
+  SELECT value, use_count, max_uses, bound_ref
+  FROM lt_ephemeral_credentials
+  WHERE token = $1
+    AND (expires_at IS NULL OR expires_at > NOW())
+    AND (bound_ref IS NOT NULL OR max_uses = 0 OR use_count < max_uses)`;
+/**
+ * Spend one use, binding a bind_on_use grant to $2 on its first spend.
+ * A bound grant acts again on its own ref without counting, and never on
+ * another ref. Without a ref ($2 NULL) the grant counts like any other.
+ */
+exports.CONSUME_EPHEMERAL = `
+  UPDATE lt_ephemeral_credentials
+  SET use_count = CASE WHEN bound_ref IS NOT NULL THEN use_count ELSE use_count + 1 END,
+      bound_ref = CASE WHEN bind_on_use AND bound_ref IS NULL THEN $2::text ELSE bound_ref END
+  WHERE token = $1
+    AND (expires_at IS NULL OR expires_at > NOW())
+    AND (
+      (bound_ref IS NOT NULL AND bound_ref = $2::text)
+      OR (bound_ref IS NULL AND (max_uses = 0 OR use_count < max_uses))
+    )
+  RETURNING value, use_count, max_uses, bound_ref`;
+/** Return a use an act spent but did not land; $2 also undoes the binding that spend made. */
+exports.REFUND_EPHEMERAL = `
+  UPDATE lt_ephemeral_credentials
+  SET use_count = GREATEST(use_count - 1, 0),
+      bound_ref = CASE WHEN $2::boolean THEN NULL ELSE bound_ref END
+  WHERE token = $1`;
 exports.DELETE_EPHEMERAL = `
   DELETE FROM lt_ephemeral_credentials WHERE token = $1`;
 exports.CLEANUP_EXPIRED_EPHEMERAL = `

package/build/services/pipelines/events.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildEvents = buildEvents;
 const hotmesh_utils_1 = require("../hotmesh-utils");
+const workflow_state_1 = require("../workflow-state");
 /**
  * Transform raw activities + job context into a chronological event list
  * with back-references linking completions to their scheduled events.
@@ -84,7 +85,7 @@ function completionEvent(id, act, input, timelineKey, index) {
     };
 }
 function appendWorkflowTerminalEvent(events, nextId, ctx) {
-    const status = ctx.job.status > 0 ? 'running' : ctx.job.status === 0 ? 'completed' : 'failed';
+    const status = (0, workflow_state_1.workflowStateFromStatus)(ctx.job.status);
     if (status === 'completed') {
         events.push({
             event_id: nextId,

package/build/services/pipelines/execution-builder.js

@@ -6,6 +6,7 @@ const hotmesh_utils_1 = require("../hotmesh-utils");
 const enrichment_1 = require("./enrichment");
 const events_1 = require("./events");
 const sql_1 = require("./sql");
+const workflow_state_1 = require("../workflow-state");
 /**
  * Build a complete execution export for a YAML engine workflow job.
  *
@@ -88,7 +89,7 @@ function assembleExport(ctx, events, activities) {
         workflow_type: ctx.workflowTopic,
         workflow_name: ctx.workflowName,
         task_queue: ctx.appId,
-        status: ctx.job.status > 0 ? 'running' : ctx.job.status === 0 ? 'completed' : 'failed',
+        status: (0, workflow_state_1.workflowStateFromStatus)(ctx.job.status),
         start_time: startTime,
         close_time: closeTime,
         duration_ms: durationMs,

package/build/services/pipelines/queries.js

@@ -5,6 +5,7 @@ exports.listJobs = listJobs;
 const db_1 = require("../../lib/db");
 const hotmesh_utils_1 = require("../hotmesh-utils");
 const sql_1 = require("./sql");
+const workflow_state_1 = require("../workflow-state");
 const SORTABLE_COLUMNS = new Set(['created_at', 'updated_at', 'entity', 'status']);
 function buildOrderBy(sortBy, order) {
     if (!sortBy || !SORTABLE_COLUMNS.has(sortBy)) {
@@ -75,7 +76,7 @@ async function listJobs(params) {
     const jobs = dataResult.rows.map((row) => ({
         workflow_id: row.key.startsWith(keyPrefix) ? row.key.slice(keyPrefix.length) : row.key,
         entity: row.entity,
-        status: row.status > 0 ? 'running' : row.status === 0 ? 'completed' : 'failed',
+        status: (0, workflow_state_1.workflowStateFromStatus)(row.status),
         is_live: row.is_live,
         created_at: row.created_at,
         updated_at: row.updated_at,

package/build/services/role/badge-grant.d.ts

@@ -0,0 +1,5 @@
+import { type RoleBadgeGrant } from './types';
+/** The problem with a `properties.badge_grant` value, or null when it is usable (or absent). */
+export declare function badgeGrantError(value: unknown): string | null;
+/** The role's badge policy from its properties bag, or null when it declares none (or an unusable one). */
+export declare function readBadgeGrant(properties: Record<string, unknown> | null | undefined): RoleBadgeGrant | null;

package/build/services/role/badge-grant.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.badgeGrantError = badgeGrantError;
+exports.readBadgeGrant = readBadgeGrant;
+const types_1 = require("./types");
+const SCOPES = ['action', 'subject'];
+/** The problem with a `properties.badge_grant` value, or null when it is usable (or absent). */
+function badgeGrantError(value) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value !== 'object' || Array.isArray(value))
+        return 'properties.badge_grant must be an object';
+    const grant = value;
+    const known = new Set(['ttl_seconds', 'max_uses', 'scope']);
+    const extra = Object.keys(grant).filter((k) => !known.has(k));
+    if (extra.length)
+        return `properties.badge_grant has unknown key(s): ${extra.join(', ')}`;
+    if (grant.ttl_seconds !== undefined
+        && (!Number.isInteger(grant.ttl_seconds) || grant.ttl_seconds < 1 || grant.ttl_seconds > 86_400)) {
+        return 'properties.badge_grant.ttl_seconds must be an integer from 1 to 86400';
+    }
+    if (grant.max_uses !== undefined && (!Number.isInteger(grant.max_uses) || grant.max_uses < 0)) {
+        return 'properties.badge_grant.max_uses must be a non-negative integer';
+    }
+    if (grant.scope !== undefined && !SCOPES.includes(grant.scope)) {
+        return `properties.badge_grant.scope must be one of ${SCOPES.join(', ')}`;
+    }
+    return null;
+}
+/** The role's badge policy from its properties bag, or null when it declares none (or an unusable one). */
+function readBadgeGrant(properties) {
+    const value = properties?.[types_1.ROLE_PROPERTY_KEYS.BADGE_GRANT];
+    if (value === undefined || value === null || badgeGrantError(value))
+        return null;
+    return value;
+}

package/build/services/role/seed.js

@@ -8,6 +8,8 @@ const db_1 = require("../../lib/db");
 const logger_1 = require("../../lib/logger");
 const index_1 = require("./index");
 const sql_1 = require("./sql");
+const badge_grant_1 = require("./badge-grant");
+const types_1 = require("./types");
 /** Recorded on schema snapshots written by the startup apply. */
 exports.STARTUP_CHANGE_SUMMARY = 'startup apply (code)';
 /** Metadata fields shared 1:1 between LTRoleConfig and UpdateRoleInput. */
@@ -79,6 +81,9 @@ async function listConfiguredRoles() {
  * Escalation targets use replace semantics when declared.
  */
 async function applyRoleConfig(cfg, codeOwned) {
+    const grantError = (0, badge_grant_1.badgeGrantError)(cfg.properties?.[types_1.ROLE_PROPERTY_KEYS.BADGE_GRANT]);
+    if (grantError)
+        throw new Error(`role ${cfg.role}: ${grantError}`);
     const created = await (0, index_1.createRole)(cfg.role);
     const pool = (0, db_1.getPool)();
     const { rows } = await pool.query(sql_1.GET_ROLE_ROW, [cfg.role]);

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

@@ -15,6 +15,10 @@ export interface EscalationChain {
  *    MEMBER of exactly this one role, the dashboard drops the left nav, the
  *    role's escalation list becomes home, and navigation is held to the list,
  *    the detail page, and the scan screens. Multi-role users get full chrome.
+ *  - BADGE_GRANT: RoleBadgeGrant — the badge policy at this role's stations.
+ *    A badge scanned on a device signed in as a member of this role mints
+ *    its acting grant under this policy instead of the badge scheme's own
+ *    (see api/scan-codes/badge-policy.ts).
  *  - LINK_VARIABLES: RoleLinkVariable[] — metadata facet names members bind
  *    per device. Pins may reference `{lt:name}` as a whole facet value
  *    (e.g. `facets={"region":"{lt:region}"}`); the dashboard substitutes
@@ -27,7 +31,17 @@ export declare const ROLE_PROPERTY_KEYS: {
     readonly WORKED_BY: "worked_by";
     readonly KIOSK: "kiosk";
     readonly LINK_VARIABLES: "link_variables";
+    readonly BADGE_GRANT: "badge_grant";
 };
+/** A station role's badge policy. Absent fields keep the badge scheme's value. */
+export interface RoleBadgeGrant {
+    /** How long a badge scan stays primed (1-86400 s). */
+    ttl_seconds?: number;
+    /** 0 = TTL-bound; n = the grant covers n acts. */
+    max_uses?: number;
+    /** 'action' spends a use per act; 'subject' binds to one held item. */
+    scope?: 'action' | 'subject';
+}
 /**
  * One link-variable declaration inside `properties.link_variables`. `name` is
  * the metadata facet key (facet-key charset); `label` is the human annotation

package/build/services/role/types.js

@@ -14,6 +14,10 @@ exports.PORTAL_KEY = exports.PORTAL_LIMITS = exports.ROLE_PROPERTY_KEYS = void 0
  *    MEMBER of exactly this one role, the dashboard drops the left nav, the
  *    role's escalation list becomes home, and navigation is held to the list,
  *    the detail page, and the scan screens. Multi-role users get full chrome.
+ *  - BADGE_GRANT: RoleBadgeGrant — the badge policy at this role's stations.
+ *    A badge scanned on a device signed in as a member of this role mints
+ *    its acting grant under this policy instead of the badge scheme's own
+ *    (see api/scan-codes/badge-policy.ts).
  *  - LINK_VARIABLES: RoleLinkVariable[] — metadata facet names members bind
  *    per device. Pins may reference `{lt:name}` as a whole facet value
  *    (e.g. `facets={"region":"{lt:region}"}`); the dashboard substitutes
@@ -26,6 +30,7 @@ exports.ROLE_PROPERTY_KEYS = {
     WORKED_BY: 'worked_by',
     KIOSK: 'kiosk',
     LINK_VARIABLES: 'link_variables',
+    BADGE_GRANT: 'badge_grant',
 };
 /** Bounds for a role's portals: how many, and the matrix of each (rows of cells, each cell a pin). */
 exports.PORTAL_LIMITS = {

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

@@ -1,4 +1,5 @@
 export { listScanSchemes, getScanScheme, listScanRules, getScanRule, } from './read';
 export { upsertScanScheme, deleteScanScheme, upsertScanRule, deleteScanRule, seedScanScheme, seedScanRule, applyScanScheme, applyScanRule, type ScanSchemeInput, type ScanRuleInput, } from './write';
-export { parseScanCode, interpolateScanTemplate, mentionsClaimToken, ScanTemplateError, type ScanParseResult, type ScanParseFailure, type ScanTemplateContext, } from './parse';
-export { assertValidScheme, assertValidSteps } from './validate';
+export { parseScanCode, interpolateScanTemplate, mentionsClaimToken, renderScanCopy, ScanTemplateError, type ScanParseResult, type ScanParseFailure, type ScanTemplateContext, } from './parse';
+export { assertValidScheme, assertValidSteps, assertValidIdentityRule, assertSchemesCoexist, } from './validate';
+export { isValidGtin, normalizeGtin } from '../../shared/scan-code';

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.assertValidSteps = exports.assertValidScheme = exports.ScanTemplateError = exports.mentionsClaimToken = exports.interpolateScanTemplate = exports.parseScanCode = exports.applyScanRule = exports.applyScanScheme = exports.seedScanRule = exports.seedScanScheme = exports.deleteScanRule = exports.upsertScanRule = exports.deleteScanScheme = exports.upsertScanScheme = exports.getScanRule = exports.listScanRules = exports.getScanScheme = exports.listScanSchemes = void 0;
+exports.normalizeGtin = exports.isValidGtin = exports.assertSchemesCoexist = exports.assertValidIdentityRule = exports.assertValidSteps = exports.assertValidScheme = exports.ScanTemplateError = exports.renderScanCopy = exports.mentionsClaimToken = exports.interpolateScanTemplate = exports.parseScanCode = exports.applyScanRule = exports.applyScanScheme = 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; } });
@@ -19,7 +19,13 @@ 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; } });
 Object.defineProperty(exports, "mentionsClaimToken", { enumerable: true, get: function () { return parse_1.mentionsClaimToken; } });
+Object.defineProperty(exports, "renderScanCopy", { enumerable: true, get: function () { return parse_1.renderScanCopy; } });
 Object.defineProperty(exports, "ScanTemplateError", { enumerable: true, get: function () { return parse_1.ScanTemplateError; } });
 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; } });
+Object.defineProperty(exports, "assertValidIdentityRule", { enumerable: true, get: function () { return validate_1.assertValidIdentityRule; } });
+Object.defineProperty(exports, "assertSchemesCoexist", { enumerable: true, get: function () { return validate_1.assertSchemesCoexist; } });
+var scan_code_1 = require("../../shared/scan-code");
+Object.defineProperty(exports, "isValidGtin", { enumerable: true, get: function () { return scan_code_1.isValidGtin; } });
+Object.defineProperty(exports, "normalizeGtin", { enumerable: true, get: function () { return scan_code_1.normalizeGtin; } });

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

@@ -1,9 +1,6 @@
+import { type ScanParseFailure } from '../../shared/scan-code';
 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 { ScanParseFailure };
 export type ScanParseResult = {
     ok: true;
     parsed: ParsedScanCode;
@@ -12,26 +9,26 @@ export type ScanParseResult = {
     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)
- */
+/** Parse a raw scan string against the configured schemes. Pure; see shared/scan-code. */
 export declare function parseScanCode(raw: string, schemes: ScanScheme[]): ScanParseResult;
 export interface ScanTemplateContext {
     target: string;
     category: string;
     scannedAt: string;
+    /** The code as scanned; defaults to the target. */
+    code?: string;
     /** The acting user's single live claim, its metadata; absent when none or ambiguous. */
     claim?: Record<string, unknown>;
-    /** The row an item-mode accumulate step located, its metadata. */
+    /** The row the step located (item-mode accumulate, hold), its metadata. */
     item?: Record<string, unknown>;
+    /** The held subject's row: its metadata plus `id`. */
+    subject?: Record<string, unknown>;
+    /** The container a subject step located, its metadata. */
+    container?: Record<string, unknown>;
+    /** The batch a fill step read: `pending`, `total`, `filled`. */
+    fill?: Record<string, unknown>;
 }
-/** A `{claim.x}` or `{item.x}` token the context cannot resolve. */
+/** A bag token the context cannot resolve. */
 export declare class ScanTemplateError extends Error {
     readonly token: string;
     readonly reason: string;
@@ -41,9 +38,15 @@ export declare class ScanTemplateError extends Error {
 export declare function mentionsClaimToken(value: unknown): boolean;
 /**
  * Replace the template tokens inside string values of a params object.
- * Deep, pure, non-mutating. The three scan tokens are plain text
- * replacement; `{claim.<facet>}` and `{item.<facet>}` read the context's
- * facet bags and throw {@link ScanTemplateError} when they cannot resolve,
- * so a literal token never reaches a row. No expression language.
+ * Deep, pure, non-mutating. The scan tokens are plain text replacement; the
+ * bag tokens (`{claim.x}`, `{item.x}`, `{subject.x}`, `{container.x}`,
+ * `{fill.x}`) read the context's facet bags and throw
+ * {@link ScanTemplateError} when they cannot resolve, so a literal token
+ * never reaches a row. No expression language.
  */
 export declare function interpolateScanTemplate<T>(value: T, ctx: ScanTemplateContext): T;
+/**
+ * Render refusal copy, degrading instead of failing: a token with nothing to
+ * read becomes an empty string, so a refusal always has words to show.
+ */
+export declare function renderScanCopy(markdown: string, ctx: ScanTemplateContext): string;