@hotmeshio/long-tail 0.22.0 → 0.22.2

package/build/api/escalations/accumulate.d.ts

@@ -1,4 +1,4 @@
-import type { AccumulatedItem, LTEscalationRecord } from '../../types';
+import type { AccumulatedItem, ContainerSelector, LTEscalationRecord } from '../../types';
 import type { LTApiAuth, LTApiResult } from '../../types/sdk';
 /** Names the second row of a reciprocal add or removal. Exactly one selector. */
 export interface ReciprocalInput {
@@ -16,6 +16,11 @@ export interface AccumulateItemInput {
     metadata?: Record<string, any>;
     assertClaim?: boolean;
     reciprocal?: ReciprocalInput;
+    /**
+     * The person who caused the add, when a trusted service performs it for
+     * them. Recorded as the entry's actor; the caller's rights still gate the write.
+     */
+    initiatedBy?: string;
 }
 /**
  * Add ONE item to an accumulator escalation (a `conditional` wait declared
@@ -59,10 +64,14 @@ export declare function accumulateItemByMetadata(input: {
     key: string;
     value: string;
     restrictRoles?: string[];
+    /** Narrows the container beyond the facet: type, subtype, extra facet guards. */
+    container?: ContainerSelector;
 } & Omit<AccumulateItemInput, 'assertClaim'>, auth: LTApiAuth): Promise<LTApiResult>;
 export interface RemoveItemInput {
     itemKey: string;
     reciprocal?: Omit<ReciprocalInput, 'payload'>;
+    /** The person who caused the removal; see {@link AccumulateItemInput.initiatedBy}. */
+    initiatedBy?: string;
 }
 /**
  * Remove ONE held item from a pending accumulator escalation, one guarded

package/build/api/escalations/accumulate.js

@@ -44,6 +44,8 @@ exports.getEscalationItems = getEscalationItems;
 exports.getEscalationItemsBySignalKey = getEscalationItemsBySignalKey;
 const escalationService = __importStar(require("../../services/escalation"));
 const resolver_validation_1 = require("../../services/escalation/resolver-validation");
+const userService = __importStar(require("../../services/user"));
+const uuid_1 = require("../../lib/uuid");
 const enforcement_cache_1 = require("../../services/role/enforcement-cache");
 const escalation_1 = require("../../types/escalation");
 const helpers_1 = require("./helpers");
@@ -66,23 +68,73 @@ function isBatch(escalation) {
     return Array.isArray(escalation.metadata?.[escalation_1.ESCALATION_BATCH_KEYS.PENDING]);
 }
 const NO_ACCUMULATOR_FOR_FACET = 'No pending accumulator found for this metadata';
+/** The add's item-key error, or null when the key is usable. */
+function itemKeyError(itemKey) {
+    if (!itemKey)
+        return { status: 400, error: 'itemKey is required' };
+    if (typeof itemKey !== 'string' || itemKey.length > escalation_1.ESCALATION_ITEM_KEY_MAX_LENGTH) {
+        return { status: 400, error: `itemKey must be a string of at most ${escalation_1.ESCALATION_ITEM_KEY_MAX_LENGTH} characters` };
+    }
+    return null;
+}
 /**
  * The container a facet names: the highest priority pending row that carries
  * the facet AND the accumulator declaration, within the given roles (null =
- * unscoped). A release or remediation row sharing the facet is never a
- * candidate, so a by-facet add lands on the open container or nowhere.
+ * unscoped) and the selector's guards. A release or remediation row sharing
+ * the facet is never a candidate, and neither is the add's own reciprocal row,
+ * so a by-facet add lands on the open container or nowhere.
  */
-async function pickAccumulatorByFacet(key, value, roles) {
+async function pickAccumulatorByFacet(key, value, roles, selector, excludeId) {
     if (roles !== null && roles.length === 0)
         return null;
     const found = await escalationService.searchByFacets({
         roles: roles ?? undefined,
-        facets: { [key]: value },
+        types: selector?.types,
+        subtypes: selector?.subtypes,
+        facets: { ...selector?.facets, [key]: value },
         status: 'pending',
         exists: [escalation_1.ESCALATION_ACCUMULATE_KEYS.COUNT],
-        limit: 1,
+        limit: excludeId ? 2 : 1,
     });
-    return found.escalations[0] ?? null;
+    return found.escalations.find((row) => row.id !== excludeId) ?? null;
+}
+const isStringList = (v) => Array.isArray(v) && v.every((s) => typeof s === 'string' && s.length > 0);
+/** The selector's shape error, or null when it is absent or well formed. */
+function containerSelectorError(selector) {
+    if (selector === undefined)
+        return null;
+    if (!selector || typeof selector !== 'object' || Array.isArray(selector))
+        return 'container must be an object';
+    if (selector.types !== undefined && !isStringList(selector.types))
+        return 'container.types must be an array of strings';
+    if (selector.subtypes !== undefined && !isStringList(selector.subtypes))
+        return 'container.subtypes must be an array of strings';
+    if (selector.facets !== undefined && (!selector.facets || typeof selector.facets !== 'object' || Array.isArray(selector.facets))) {
+        return 'container.facets must be an object';
+    }
+    return null;
+}
+function isNarrowed(selector) {
+    return !!(selector?.types?.length || selector?.subtypes?.length
+        || (selector?.facets && Object.keys(selector.facets).length));
+}
+/**
+ * The entry's actor: the caller, or the user a global-access caller names as
+ * the initiator. Attribution only; it never widens what the caller may write.
+ */
+async function resolveActor(initiatedBy, auth) {
+    if (initiatedBy === undefined || initiatedBy === auth.userId)
+        return { actor: auth.userId };
+    if (typeof initiatedBy !== 'string' || !(0, uuid_1.isUuid)(initiatedBy)) {
+        return { error: { status: 400, error: 'initiatedBy must be a user id' } };
+    }
+    if (!(await userService.hasGlobalEscalationAccess(auth.userId))) {
+        return { error: { status: 403, error: 'initiatedBy requires global escalation access' } };
+    }
+    if (!(await userService.getUser(initiatedBy))) {
+        return { error: { status: 400, error: 'initiatedBy names no user' } };
+    }
+    return { actor: initiatedBy };
 }
 function reciprocalSelectorCount(r) {
     return (r.id ? 1 : 0) + (r.signalKey ? 1 : 0) + (r.key !== undefined ? 1 : 0);
@@ -156,15 +208,22 @@ async function gatePayload(escalation, payload, userId) {
 async function accumulateItem(input, auth) {
     try {
         const { id, itemKey, metadata } = input;
-        if (!itemKey)
-            return { status: 400, error: 'itemKey is required' };
+        const keyError = itemKeyError(itemKey);
+        if (keyError)
+            return keyError;
+        const initiator = await resolveActor(input.initiatedBy, auth);
+        if ('error' in initiator)
+            return initiator.error;
         const escalation = await escalationService.getEscalation(id);
         if (!escalation)
             return { status: 404, error: 'Escalation not found' };
-        if (escalation.status === 'cancelled')
-            return { status: 409, error: 'Escalation is cancelled' };
-        if (escalation.status !== 'pending')
-            return { status: 409, error: 'Escalation not available for accumulation' };
+        if (escalation.status === 'cancelled') {
+            return { status: 409, error: 'Escalation is cancelled', data: { error: 'Escalation is cancelled', outcome: 'already-cancelled' } };
+        }
+        if (escalation.status !== 'pending') {
+            const error = 'Escalation not available for accumulation';
+            return { status: 409, error, data: { error, outcome: `already-${escalation.status}` } };
+        }
         if (!isAccumulator(escalation))
             return { status: 400, error: 'Escalation is not an accumulator' };
         if (await (0, helpers_1.assertReadAccess)(auth.userId, escalation)) {
@@ -183,7 +242,7 @@ async function accumulateItem(input, auth) {
             itemKey,
             payload: payload.payload,
             metadata: { ...metadata, resolved_by: auth.userId },
-            actor: auth.userId,
+            actor: initiator.actor,
             assertClaim: input.assertClaim ? auth.userId : undefined,
             resolvedBy: await (0, resolve_1.resolverIdentity)(auth),
             reciprocal: reciprocal.reciprocal,
@@ -204,8 +263,12 @@ async function accumulateItemBySignalKey(input, auth) {
         const { signalKey, itemKey, metadata } = input;
         if (!signalKey)
             return { status: 400, error: 'signalKey is required' };
-        if (!itemKey)
-            return { status: 400, error: 'itemKey is required' };
+        const keyError = itemKeyError(itemKey);
+        if (keyError)
+            return keyError;
+        const initiator = await resolveActor(input.initiatedBy, auth);
+        if ('error' in initiator)
+            return initiator.error;
         const escalation = await escalationService.getEscalationBySignalKey(signalKey);
         if (!escalation)
             return { status: 404, error: 'Escalation not found' };
@@ -226,7 +289,7 @@ async function accumulateItemBySignalKey(input, auth) {
             itemKey,
             payload: payload.payload,
             metadata: { ...metadata, resolved_by: auth.userId },
-            actor: auth.userId,
+            actor: initiator.actor,
             resolvedBy: await (0, resolve_1.resolverIdentity)(auth),
             reciprocal: reciprocal.reciprocal,
         });
@@ -252,8 +315,15 @@ async function accumulateItemByMetadata(input, auth) {
         const { key, value, itemKey, metadata } = input;
         if (!key || !value)
             return { status: 400, error: 'key and value are required' };
-        if (!itemKey)
-            return { status: 400, error: 'itemKey is required' };
+        const keyError = itemKeyError(itemKey);
+        if (keyError)
+            return keyError;
+        const initiator = await resolveActor(input.initiatedBy, auth);
+        if ('error' in initiator)
+            return initiator.error;
+        const selectorError = containerSelectorError(input.container);
+        if (selectorError)
+            return { status: 400, error: selectorError };
         const writeScope = await (0, helpers_1.getEscalationWriteScope)(auth.userId);
         const allowedRoles = (0, metadata_1.restrictScopeRoles)(writeScope.allRoles, writeScope.global, input.restrictRoles);
         const reciprocal = await gateReciprocal(input.reciprocal, auth);
@@ -261,13 +331,17 @@ async function accumulateItemByMetadata(input, auth) {
             return reciprocal.error;
         const resolvedBy = await (0, resolve_1.resolverIdentity)(auth);
         const outcome = { ...metadata, resolved_by: auth.userId };
+        // A narrowed selector picks in Long Tail, then adds by id; the by-id
+        // statement re-checks pending under its lock, and type, subtype and the
+        // accumulator declaration are fixed at creation.
         const enforcing = await (0, enforcement_cache_1.getEnforcingRoles)();
-        if (enforcing.size === 0 || input.payload === undefined) {
+        const narrowed = isNarrowed(input.container);
+        if (!narrowed && (enforcing.size === 0 || input.payload === undefined)) {
             const result = await escalationService.accumulateItemByMetadata(key, value, {
                 itemKey,
                 payload: input.payload,
                 metadata: outcome,
-                actor: auth.userId,
+                actor: initiator.actor,
                 resolvedBy,
                 roles: allowedRoles ?? undefined,
                 reciprocal: reciprocal.reciprocal,
@@ -276,7 +350,7 @@ async function accumulateItemByMetadata(input, auth) {
                 return { status: 404, error: NO_ACCUMULATOR_FOR_FACET };
             return accumulateOutcomeResult(result, itemKey, result.escalation?.workflow_id ?? null);
         }
-        const row = await pickAccumulatorByFacet(key, value, allowedRoles);
+        const row = await pickAccumulatorByFacet(key, value, allowedRoles, input.container, reciprocal.reciprocal?.id);
         if (!row)
             return { status: 404, error: NO_ACCUMULATOR_FOR_FACET };
         if (!isAccumulator(row))
@@ -288,7 +362,7 @@ async function accumulateItemByMetadata(input, auth) {
             itemKey,
             payload: payload.payload,
             metadata: outcome,
-            actor: auth.userId,
+            actor: initiator.actor,
             resolvedBy,
             reciprocal: reciprocal.reciprocal,
         });
@@ -311,6 +385,9 @@ async function removeItem(input, auth) {
         const { id, itemKey } = input;
         if (!itemKey)
             return { status: 400, error: 'itemKey is required' };
+        const initiator = await resolveActor(input.initiatedBy, auth);
+        if ('error' in initiator)
+            return initiator.error;
         const escalation = await escalationService.getEscalation(id);
         if (!escalation)
             return { status: 404, error: 'Escalation not found' };
@@ -328,7 +405,7 @@ async function removeItem(input, auth) {
         if ('error' in reciprocal)
             return reciprocal.error;
         const result = await escalationService.removeAccumulatedItem(escalation.id, {
-            itemKey, actor: auth.userId, reciprocal: reciprocal.reciprocal,
+            itemKey, actor: initiator.actor, reciprocal: reciprocal.reciprocal,
         });
         return removeOutcomeResult(result, itemKey);
     }
@@ -343,6 +420,9 @@ async function removeItemBySignalKey(input, auth) {
             return { status: 400, error: 'signalKey is required' };
         if (!itemKey)
             return { status: 400, error: 'itemKey is required' };
+        const initiator = await resolveActor(input.initiatedBy, auth);
+        if ('error' in initiator)
+            return initiator.error;
         const escalation = await escalationService.getEscalationBySignalKey(signalKey);
         if (!escalation)
             return { status: 404, error: 'Escalation not found' };
@@ -357,7 +437,7 @@ async function removeItemBySignalKey(input, auth) {
         if ('error' in reciprocal)
             return reciprocal.error;
         const result = await escalationService.removeAccumulatedItemBySignalKey(signalKey, {
-            itemKey, actor: auth.userId, reciprocal: reciprocal.reciprocal,
+            itemKey, actor: initiator.actor, reciprocal: reciprocal.reciprocal,
         });
         return removeOutcomeResult(result, itemKey);
     }
@@ -372,13 +452,16 @@ async function removeItemByMetadata(input, auth) {
             return { status: 400, error: 'key and value are required' };
         if (!itemKey)
             return { status: 400, error: 'itemKey is required' };
+        const initiator = await resolveActor(input.initiatedBy, auth);
+        if ('error' in initiator)
+            return initiator.error;
         const writeScope = await (0, helpers_1.getEscalationWriteScope)(auth.userId);
         const allowedRoles = (0, metadata_1.restrictScopeRoles)(writeScope.allRoles, writeScope.global, input.restrictRoles);
         const reciprocal = await gateReciprocal(input.reciprocal, auth);
         if ('error' in reciprocal)
             return reciprocal.error;
         const result = await escalationService.removeAccumulatedItemByMetadata(key, value, {
-            itemKey, actor: auth.userId, roles: allowedRoles ?? undefined, reciprocal: reciprocal.reciprocal,
+            itemKey, actor: initiator.actor, roles: allowedRoles ?? undefined, reciprocal: reciprocal.reciprocal,
         });
         if (result.outcome === 'not-found')
             return { status: 404, error: NO_ACCUMULATOR_FOR_FACET };
@@ -506,21 +589,21 @@ function accumulateOutcomeResult(result, itemKey, workflowId) {
                 },
             };
         case 'duplicate-item':
-            return { status: 409, error: 'Item already held', data: { error: 'Item already held', itemKey } };
+            return { status: 409, error: 'Item already held', data: { error: 'Item already held', itemKey, outcome: 'duplicate-item' } };
         case 'full':
-            return { status: 409, error: 'Accumulator is full', data: { error: 'Accumulator is full', itemKey } };
+            return { status: 409, error: 'Accumulator is full', data: { error: 'Accumulator is full', itemKey, outcome: 'full' } };
         case 'claimed-by-other':
-            return { status: 409, error: 'Escalation is claimed by another user' };
+            return { status: 409, error: 'Escalation is claimed by another user', data: { error: 'Escalation is claimed by another user', outcome: 'claimed-by-other' } };
         case 'claim-expired':
-            return { status: 409, error: 'Your claim has expired; re-claim this escalation to add to it' };
+            return { status: 409, error: 'Your claim has expired; re-claim this escalation to add to it', data: { error: 'Your claim has expired; re-claim this escalation to add to it', outcome: 'claim-expired' } };
         case 'not-found':
-            return { status: 404, error: 'Escalation not found' };
+            return { status: 404, error: 'Escalation not found', data: { error: 'Escalation not found', outcome: 'not-found' } };
         case 'not-accumulator':
-            return { status: 400, error: 'Escalation is not an accumulator' };
+            return { status: 400, error: 'Escalation is not an accumulator', data: { error: 'Escalation is not an accumulator', outcome: 'not-accumulator' } };
         case 'reciprocal-not-found':
-            return { status: 404, error: 'Reciprocal escalation not found' };
+            return { status: 404, error: 'Reciprocal escalation not found', data: { error: 'Reciprocal escalation not found', outcome: 'reciprocal-not-found' } };
         case 'reciprocal-not-accumulator':
-            return { status: 400, error: 'Reciprocal escalation is not an accumulator' };
+            return { status: 400, error: 'Reciprocal escalation is not an accumulator', data: { error: 'Reciprocal escalation is not an accumulator', outcome: 'reciprocal-not-accumulator' } };
         case 'reciprocal-duplicate':
             return { status: 409, error: 'Reciprocal escalation already holds this container', data: { error: 'Reciprocal escalation already holds this container', outcome: result.outcome } };
         case 'reciprocal-full':
@@ -528,7 +611,11 @@ function accumulateOutcomeResult(result, itemKey, workflowId) {
         case 'reciprocal-terminal':
             return { status: 409, error: 'Reciprocal escalation is no longer pending', data: { error: 'Reciprocal escalation is no longer pending', outcome: result.outcome } };
         default:
-            return { status: 409, error: 'Escalation not available for accumulation' };
+            return {
+                status: 409,
+                error: 'Escalation not available for accumulation',
+                data: { error: 'Escalation not available for accumulation', outcome: result.outcome },
+            };
     }
 }
 function removeOutcomeResult(result, itemKey) {

package/build/api/escalations/metadata.d.ts

@@ -1,5 +1,6 @@
 import { type ProvisionIfAbsent } from './helpers';
 import type { LTApiAuth, LTApiResult } from '../../types/sdk';
+import type { ScanAvailability } from '../../types';
 /**
  * Intersect the caller's scope roles with an optional caller-supplied
  * restriction (e.g. a scan step's expected queues). Global scope with no
@@ -57,4 +58,8 @@ export declare function resolveByMetadata(input: {
     metadata?: Record<string, any>;
     restrictRoles?: string[];
     extraFacets?: Record<string, any>;
+    /** Narrows the pick to a claim state; 'mine' is the resolver's live claim. */
+    availability?: ScanAvailability;
+    /** Resolves only this row, when it still matches every other condition. */
+    assertId?: string;
 }, auth: LTApiAuth): Promise<LTApiResult>;

package/build/api/escalations/metadata.js

@@ -42,6 +42,7 @@ const helpers_1 = require("./helpers");
 const resolver_validation_1 = require("../../services/escalation/resolver-validation");
 const enforcement_cache_1 = require("../../services/role/enforcement-cache");
 const resolve_1 = require("./resolve");
+const uuid_1 = require("../../lib/uuid");
 /**
  * Intersect the caller's scope roles with an optional caller-supplied
  * restriction (e.g. a scan step's expected queues). Global scope with no
@@ -138,6 +139,9 @@ async function resolveByMetadata(input, auth) {
         if (!input.resolverPayload) {
             return { status: 400, error: 'resolverPayload is required' };
         }
+        if (input.assertId !== undefined && !(0, uuid_1.isUuid)(input.assertId)) {
+            return { status: 404, error: 'No pending escalation found for this metadata, or insufficient role permissions' };
+        }
         const resolved = await (0, helpers_1.resolveAssignee)(input.assignee, auth);
         if ('error' in resolved)
             return resolved.error;
@@ -159,12 +163,12 @@ async function resolveByMetadata(input, auth) {
         // writing; the payload validates here, then a second asserted pass claims
         // + resolves the same row with pending re-checked inside the statement.
         const enforcing = await (0, enforcement_cache_1.getEnforcingRoles)();
-        let result = await escalationService.resolveByMetadataAtomic(input.key, input.value, resolveUserId, input.resolverPayload, input.metadata, writeAllRoles, writeSelfRoles, enforcing.size > 0 ? [...enforcing] : null, null, input.extraFacets);
+        let result = await escalationService.resolveByMetadataAtomic(input.key, input.value, resolveUserId, input.resolverPayload, input.metadata, writeAllRoles, writeSelfRoles, enforcing.size > 0 ? [...enforcing] : null, input.assertId ?? null, input.extraFacets, input.availability);
         if (result.outcome === 'validation_required' && result.row) {
             const report = await (0, resolver_validation_1.checkResolverPayload)(result.row, input.resolverPayload, undefined, resolveUserId);
             if (report)
                 return (0, resolve_1.validationFailure)(report);
-            result = await escalationService.resolveByMetadataAtomic(input.key, input.value, resolveUserId, input.resolverPayload, input.metadata, writeAllRoles, writeSelfRoles, null, result.row.id, input.extraFacets);
+            result = await escalationService.resolveByMetadataAtomic(input.key, input.value, resolveUserId, input.resolverPayload, input.metadata, writeAllRoles, writeSelfRoles, null, result.row.id, input.extraFacets, input.availability);
             // The asserted row left pending between the two passes — a concurrent
             // resolution won the row; surface it as the conflict it is.
             if (result.outcome === 'not_found') {

package/build/api/escalations/resolve-batch.js

@@ -70,10 +70,13 @@ async function resolveBatchItem(input, auth) {
         const escalation = await escalationService.getEscalation(id);
         if (!escalation)
             return { status: 404, error: 'Escalation not found' };
-        if (escalation.status === 'cancelled')
-            return { status: 409, error: 'Escalation is cancelled' };
-        if (escalation.status !== 'pending')
-            return { status: 409, error: 'Escalation not available for resolution' };
+        if (escalation.status === 'cancelled') {
+            return { status: 409, error: 'Escalation is cancelled', data: { error: 'Escalation is cancelled', outcome: 'already-cancelled' } };
+        }
+        if (escalation.status !== 'pending') {
+            const error = 'Escalation not available for resolution';
+            return { status: 409, error, data: { error, outcome: `already-${escalation.status}` } };
+        }
         // Advisory shape gate — cheap, readable rejection. The SDK's guarded
         // statement re-checks and is the atomic arbiter (outcome 'not-batch').
         const pending = escalation.metadata?.[escalation_1.ESCALATION_BATCH_KEYS.PENDING];
@@ -228,20 +231,24 @@ function batchOutcomeResult(result, itemKey, workflowId) {
             return {
                 status: 409,
                 error: 'Batch item already submitted',
-                data: { error: 'Batch item already submitted', itemKey },
+                data: { error: 'Batch item already submitted', itemKey, outcome: 'duplicate-item' },
             };
         case 'claimed-by-other':
-            return { status: 409, error: 'Escalation is claimed by another user' };
+            return { status: 409, error: 'Escalation is claimed by another user', data: { error: 'Escalation is claimed by another user', outcome: 'claimed-by-other' } };
         case 'claim-expired':
-            return { status: 409, error: 'Your claim has expired — re-claim this escalation to resolve it' };
+            return { status: 409, error: 'Your claim has expired — re-claim this escalation to resolve it', data: { error: 'Your claim has expired — re-claim this escalation to resolve it', outcome: 'claim-expired' } };
         case 'not-found':
-            return { status: 404, error: 'Escalation not found' };
+            return { status: 404, error: 'Escalation not found', data: { error: 'Escalation not found', outcome: 'not-found' } };
         case 'unknown-item':
-            return { status: 400, error: 'itemKey is not in the declared batch' };
+            return { status: 400, error: 'itemKey is not in the declared batch', data: { error: 'itemKey is not in the declared batch', outcome: 'unknown-item' } };
         case 'not-batch':
-            return { status: 400, error: 'Escalation is not a batch' };
+            return { status: 400, error: 'Escalation is not a batch', data: { error: 'Escalation is not a batch', outcome: 'not-batch' } };
         default:
             // already-resolved / already-cancelled / already-expired
-            return { status: 409, error: 'Escalation not available for resolution' };
+            return {
+                status: 409,
+                error: 'Escalation not available for resolution',
+                data: { error: 'Escalation not available for resolution', outcome: result.outcome },
+            };
     }
 }

package/build/api/roles.js

@@ -49,6 +49,7 @@ exports.listRoleListSchemaVersions = listRoleListSchemaVersions;
 exports.deleteRole = deleteRole;
 const roleService = __importStar(require("../services/role"));
 const types_1 = require("../services/role/types");
+const badge_grant_1 = require("../services/role/badge-grant");
 const facet_sql_1 = require("../services/escalation/facet-sql");
 /**
  * List all distinct role names in the system.
@@ -291,6 +292,9 @@ async function updateRole(input) {
                 return { status: 400, error: 'default_pins must be [{ label, url, badge? }] with dashboard-relative urls' };
             }
         }
+        const grantError = (0, badge_grant_1.badgeGrantError)(input.properties?.[types_1.ROLE_PROPERTY_KEYS.BADGE_GRANT]);
+        if (grantError)
+            return { status: 400, error: grantError };
         if (input.portals != null && !isPortalList(input.portals)) {
             return {
                 status: 400,

package/build/api/scan-codes/badge-policy.d.ts

@@ -0,0 +1,10 @@
+import { type ScanGrantScope, type ScanScheme } from '../../types';
+export interface GrantPolicy {
+    ttlSeconds: number;
+    maxUses: number;
+    scope: ScanGrantScope;
+    /** The station role whose policy applied; absent when the scheme's did. */
+    role?: string;
+}
+/** The policy a badge scanned on this device mints under. */
+export declare function stationGrantPolicy(scheme: ScanScheme, stationUserId: string, stationRole?: string): Promise<GrantPolicy>;

package/build/api/scan-codes/badge-policy.js

@@ -0,0 +1,72 @@
+"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 });
+exports.stationGrantPolicy = stationGrantPolicy;
+const roleService = __importStar(require("../../services/role"));
+const userService = __importStar(require("../../services/user"));
+const badge_grant_1 = require("../../services/role/badge-grant");
+const types_1 = require("../../types");
+function schemePolicy(scheme) {
+    return {
+        ttlSeconds: scheme.grant_ttl_seconds ?? 0,
+        maxUses: scheme.grant_max_uses ?? 0,
+        scope: scheme.grant_scope ?? types_1.SCAN_GRANT_SCOPES.ACTION,
+    };
+}
+/** The policy a badge scanned on this device mints under. */
+async function stationGrantPolicy(scheme, stationUserId, stationRole) {
+    const fallback = schemePolicy(scheme);
+    const user = await userService.getUser(stationUserId);
+    const memberRoles = (user?.roles ?? []).map((r) => r.role);
+    const candidates = stationRole
+        ? memberRoles.filter((r) => r === stationRole)
+        : memberRoles;
+    const declared = [];
+    for (const role of candidates) {
+        const grant = (0, badge_grant_1.readBadgeGrant)(await roleService.getRoleProperties(role));
+        if (grant)
+            declared.push({ role, grant });
+    }
+    const distinct = new Set(declared.map((d) => JSON.stringify(d.grant)));
+    if (distinct.size !== 1)
+        return fallback;
+    const { role, grant } = declared[0];
+    return {
+        ttlSeconds: grant.ttl_seconds ?? fallback.ttlSeconds,
+        maxUses: grant.max_uses ?? fallback.maxUses,
+        scope: grant.scope ?? fallback.scope,
+        role,
+    };
+}

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

@@ -38,6 +38,7 @@ const scanCodeService = __importStar(require("../../services/scan-code"));
 const escalationService = __importStar(require("../../services/escalation"));
 const types_1 = require("../../types");
 const identity_1 = require("./identity");
+const grant_1 = require("./grant");
 const context_1 = require("./context");
 const locate_1 = require("./locate");
 const verbs_1 = require("./verbs");
@@ -69,19 +70,19 @@ async function executeScanChoice(input, auth) {
                 data: { outcome: types_1.SCAN_OUTCOMES.UNCONFIGURED, error: 'the presented choice is no longer configured' },
             };
         }
-        // 2. The acting grant, exchanged before anything reads or writes.
+        // 2. The acting grant, read (not spent) before anything reads or writes.
         let effectiveAuth = auth;
-        let acting = false;
+        let grant;
         if (input.actingToken) {
-            const resolved = await (0, identity_1.resolveActingAuth)(input.actingToken);
-            if (!resolved.ok) {
+            const peeked = await (0, grant_1.peekGrant)(input.actingToken);
+            if (!peeked.ok) {
                 return {
                     status: 200,
-                    data: { outcome: types_1.SCAN_OUTCOMES.NOT_PRIMED, notPrimed: rule.notPrimed, error: resolved.error },
+                    data: { outcome: types_1.SCAN_OUTCOMES.NOT_PRIMED, notPrimed: rule.notPrimed, replayable: true, error: peeked.error },
                 };
             }
-            effectiveAuth = resolved.auth;
-            acting = true;
+            effectiveAuth = peeked.auth;
+            grant = peeked.grant;
         }
         // 3. The row anchors the target: the scheme's facet on the escalation the
         // screen presented. A missing binding is loud misconfiguration.
@@ -100,7 +101,8 @@ async function executeScanChoice(input, auth) {
             scannedAt: new Date().toISOString(),
             auth: effectiveAuth,
             stationAuth: auth,
-            acting,
+            acting: !!grant,
+            grant,
         };
         // 4. The identity gate, per the choice.
         if (choice.requireActingIdentity && !(await (0, identity_1.actingIdentitySatisfied)(step, ctx))) {
@@ -110,13 +112,18 @@ async function executeScanChoice(input, auth) {
         // showed. A row that moved on (resolved, claimed away, re-routed) is the
         // same double-actor race a second scan loses.
         const located = await (0, locate_1.locateForStep)(step, ctx, 2);
-        if (!located || !located.escalations.some((e) => e.id === input.escalationId)) {
+        const presented = located?.escalations.find((e) => e.id === input.escalationId);
+        if (!presented) {
             return decorate((0, context_1.conflict)('the item is no longer in the presented state'), ctx, input);
         }
         // 6. Dispatch through the same atomic executors a direct scan uses.
         const synthesized = { query: step.query, verb: choice.verb, params: choice.params };
-        const result = await (0, verbs_1.dispatchChoiceVerb)(synthesized, ctx, located.escalations[0]);
-        return decorate(result, ctx, input);
+        const result = decorate(await (0, verbs_1.dispatchChoiceVerb)(synthesized, ctx, presented), ctx, input);
+        // 7. Settle the badge: refund a spend whose act did not land
+        const acting = await (0, grant_1.settleGrant)(ctx, result);
+        if (acting && result.data)
+            result.data = { ...result.data, acting };
+        return result;
     }
     catch (err) {
         return { status: 500, error: err.message };