@hotmeshio/long-tail 0.21.0 → 0.21.2

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

@@ -46,8 +46,11 @@ export declare function accumulateItemBySignalKey(input: {
 } & Omit<AccumulateItemInput, 'assertClaim'>, auth: LTApiAuth): Promise<LTApiResult>;
 /**
  * Add selecting the container by metadata facet, the faceted sibling of
- * {@link accumulateItem}. RBAC folds into the SDK's atomic facet selection
- * as a flat role filter. Schema enforcement is two-phase when enforcing
+ * {@link accumulateItem}. The facet names a container, so only pending rows
+ * carrying the accumulator declaration are candidates: a release or
+ * remediation row that shares the facet is never picked, and when no open
+ * container shares it the answer is 404. RBAC folds into the SDK's atomic
+ * facet selection as a flat role filter. Schema enforcement is two-phase when enforcing
  * roles exist and a payload is present: the row is picked first, validated
  * against ITS schema, then written by asserted id; a row that went terminal
  * between phases surfaces as a 409.
@@ -94,3 +97,11 @@ export declare function itemsView(escalation: LTEscalationRecord): EscalationIte
 export declare function getEscalationItems(input: {
     id: string;
 }, auth: LTApiAuth): Promise<LTApiResult<EscalationItemsView>>;
+/**
+ * GET the held items of an accumulator or batch row by its `signal_key`, the
+ * deterministic home signal id a workflow knows without a row id. Read scope
+ * gates it; anything the caller may not see answers 404.
+ */
+export declare function getEscalationItemsBySignalKey(input: {
+    signalKey: string;
+}, auth: LTApiAuth): Promise<LTApiResult<EscalationItemsView>>;

package/build/api/escalations/accumulate.js

@@ -41,6 +41,7 @@ exports.removeItemBySignalKey = removeItemBySignalKey;
 exports.removeItemByMetadata = removeItemByMetadata;
 exports.itemsView = itemsView;
 exports.getEscalationItems = getEscalationItems;
+exports.getEscalationItemsBySignalKey = getEscalationItemsBySignalKey;
 const escalationService = __importStar(require("../../services/escalation"));
 const resolver_validation_1 = require("../../services/escalation/resolver-validation");
 const enforcement_cache_1 = require("../../services/role/enforcement-cache");
@@ -64,6 +65,25 @@ function isAccumulator(escalation) {
 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 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.
+ */
+async function pickAccumulatorByFacet(key, value, roles) {
+    if (roles !== null && roles.length === 0)
+        return null;
+    const found = await escalationService.searchByFacets({
+        roles: roles ?? undefined,
+        facets: { [key]: value },
+        status: 'pending',
+        exists: [escalation_1.ESCALATION_ACCUMULATE_KEYS.COUNT],
+        limit: 1,
+    });
+    return found.escalations[0] ?? null;
+}
 function reciprocalSelectorCount(r) {
     return (r.id ? 1 : 0) + (r.signalKey ? 1 : 0) + (r.key !== undefined ? 1 : 0);
 }
@@ -88,8 +108,7 @@ async function gateReciprocal(input, auth) {
     }
     else {
         const writeScope = await (0, helpers_1.getEscalationWriteScope)(auth.userId);
-        const found = await escalationService.findByMetadata(input.key, String(input.value), 'pending', 1, 0, writeScope.global ? undefined : { allRoles: writeScope.allRoles, meUserId: auth.userId });
-        row = found.escalations[0] ?? null;
+        row = await pickAccumulatorByFacet(input.key, String(input.value), writeScope.global ? null : writeScope.allRoles);
     }
     if (!row)
         return { error: { status: 404, error: 'Reciprocal escalation not found' } };
@@ -219,8 +238,11 @@ async function accumulateItemBySignalKey(input, auth) {
 }
 /**
  * Add selecting the container by metadata facet, the faceted sibling of
- * {@link accumulateItem}. RBAC folds into the SDK's atomic facet selection
- * as a flat role filter. Schema enforcement is two-phase when enforcing
+ * {@link accumulateItem}. The facet names a container, so only pending rows
+ * carrying the accumulator declaration are candidates: a release or
+ * remediation row that shares the facet is never picked, and when no open
+ * container shares it the answer is 404. RBAC folds into the SDK's atomic
+ * facet selection as a flat role filter. Schema enforcement is two-phase when enforcing
  * roles exist and a payload is present: the row is picked first, validated
  * against ITS schema, then written by asserted id; a row that went terminal
  * between phases surfaces as a 409.
@@ -250,12 +272,13 @@ async function accumulateItemByMetadata(input, auth) {
                 roles: allowedRoles ?? undefined,
                 reciprocal: reciprocal.reciprocal,
             });
+            if (result.outcome === 'not-found')
+                return { status: 404, error: NO_ACCUMULATOR_FOR_FACET };
             return accumulateOutcomeResult(result, itemKey, result.escalation?.workflow_id ?? null);
         }
-        const found = await escalationService.findByMetadata(key, value, 'pending', 1, 0, allowedRoles === null ? undefined : { allRoles: allowedRoles, meUserId: auth.userId });
-        const row = found.escalations[0];
+        const row = await pickAccumulatorByFacet(key, value, allowedRoles);
         if (!row)
-            return { status: 404, error: 'No pending escalation found for this metadata' };
+            return { status: 404, error: NO_ACCUMULATOR_FOR_FACET };
         if (!isAccumulator(row))
             return { status: 400, error: 'Escalation is not an accumulator' };
         const payload = await gatePayload(row, input.payload, auth.userId);
@@ -357,6 +380,8 @@ async function removeItemByMetadata(input, auth) {
         const result = await escalationService.removeAccumulatedItemByMetadata(key, value, {
             itemKey, actor: auth.userId, roles: allowedRoles ?? undefined, reciprocal: reciprocal.reciprocal,
         });
+        if (result.outcome === 'not-found')
+            return { status: 404, error: NO_ACCUMULATOR_FOR_FACET };
         return removeOutcomeResult(result, itemKey);
     }
     catch (err) {
@@ -419,6 +444,30 @@ async function getEscalationItems(input, auth) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * GET the held items of an accumulator or batch row by its `signal_key`, the
+ * deterministic home signal id a workflow knows without a row id. Read scope
+ * gates it; anything the caller may not see answers 404.
+ */
+async function getEscalationItemsBySignalKey(input, auth) {
+    try {
+        if (!input.signalKey)
+            return { status: 400, error: 'signalKey is required' };
+        const escalation = await escalationService.getEscalationBySignalKey(input.signalKey);
+        if (!escalation)
+            return { status: 404, error: 'Escalation not found' };
+        if (await (0, helpers_1.assertReadAccess)(auth.userId, escalation)) {
+            return { status: 404, error: 'Escalation not found' };
+        }
+        const view = itemsView(escalation);
+        if (!view)
+            return { status: 400, error: 'Escalation holds no items' };
+        return { status: 200, data: view };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
 function sideData(side) {
     return {
         outcome: side.outcome,

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

@@ -6,7 +6,7 @@ export { claimEscalation, releaseEscalation } from './claim';
 export { releaseExpiredClaims, updatePriority, bulkClaim, bulkAssign, bulkUnassign, bulkEscalate, bulkTriage } from './bulk';
 export { resolveEscalation, resolveBySignalKey, resolveByIds, resolveAllOrNone } from './resolve';
 export { resolveBatchItem, resolveBatchItemBySignalKey, resolveBatchItemByMetadata } from './resolve-batch';
-export { accumulateItem, accumulateItemBySignalKey, accumulateItemByMetadata, removeItem, removeItemBySignalKey, removeItemByMetadata, getEscalationItems, itemsView, } from './accumulate';
+export { accumulateItem, accumulateItemBySignalKey, accumulateItemByMetadata, removeItem, removeItemBySignalKey, removeItemByMetadata, getEscalationItems, getEscalationItemsBySignalKey, itemsView, } from './accumulate';
 export { findByMetadata, claimByMetadata, resolveByMetadata } from './metadata';
 export { cancelSingleEscalation, bulkCancel } from './cancel';
 export { searchByFacets, claimGroups, claimByFacets } from './facets';

package/build/api/escalations/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.timelineByFacet = exports.aggregateByFacets = exports.claimByFacets = exports.claimGroups = exports.searchByFacets = exports.bulkCancel = exports.cancelSingleEscalation = exports.resolveByMetadata = exports.claimByMetadata = exports.findByMetadata = exports.itemsView = exports.getEscalationItems = exports.removeItemByMetadata = exports.removeItemBySignalKey = exports.removeItem = exports.accumulateItemByMetadata = exports.accumulateItemBySignalKey = exports.accumulateItem = exports.resolveBatchItemByMetadata = exports.resolveBatchItemBySignalKey = exports.resolveBatchItem = exports.resolveAllOrNone = exports.resolveByIds = exports.resolveBySignalKey = exports.resolveEscalation = exports.bulkTriage = exports.bulkEscalate = exports.bulkUnassign = exports.bulkAssign = exports.bulkClaim = exports.updatePriority = exports.releaseExpiredClaims = exports.releaseEscalation = exports.claimEscalation = exports.getEscalationLookups = exports.escalateToRole = exports.getEscalationsByWorkflowId = exports.getEscalation = exports.getStationMetrics = exports.getEscalationStats = exports.listFacetValues = exports.listFacetKeys = exports.listDistinctTypes = exports.listAvailableEscalations = exports.listEscalations = exports.createEscalation = void 0;
+exports.timelineByFacet = exports.aggregateByFacets = exports.claimByFacets = exports.claimGroups = exports.searchByFacets = exports.bulkCancel = exports.cancelSingleEscalation = exports.resolveByMetadata = exports.claimByMetadata = exports.findByMetadata = exports.itemsView = exports.getEscalationItemsBySignalKey = exports.getEscalationItems = exports.removeItemByMetadata = exports.removeItemBySignalKey = exports.removeItem = exports.accumulateItemByMetadata = exports.accumulateItemBySignalKey = exports.accumulateItem = exports.resolveBatchItemByMetadata = exports.resolveBatchItemBySignalKey = exports.resolveBatchItem = exports.resolveAllOrNone = exports.resolveByIds = exports.resolveBySignalKey = exports.resolveEscalation = exports.bulkTriage = exports.bulkEscalate = exports.bulkUnassign = exports.bulkAssign = exports.bulkClaim = exports.updatePriority = exports.releaseExpiredClaims = exports.releaseEscalation = exports.claimEscalation = exports.getEscalationLookups = exports.escalateToRole = exports.getEscalationsByWorkflowId = exports.getEscalation = exports.getStationMetrics = exports.getEscalationStats = exports.listFacetValues = exports.listFacetKeys = exports.listDistinctTypes = exports.listAvailableEscalations = exports.listEscalations = exports.createEscalation = void 0;
 var create_1 = require("./create");
 Object.defineProperty(exports, "createEscalation", { enumerable: true, get: function () { return create_1.createEscalation; } });
 var list_1 = require("./list");
@@ -45,6 +45,7 @@ Object.defineProperty(exports, "removeItem", { enumerable: true, get: function (
 Object.defineProperty(exports, "removeItemBySignalKey", { enumerable: true, get: function () { return accumulate_1.removeItemBySignalKey; } });
 Object.defineProperty(exports, "removeItemByMetadata", { enumerable: true, get: function () { return accumulate_1.removeItemByMetadata; } });
 Object.defineProperty(exports, "getEscalationItems", { enumerable: true, get: function () { return accumulate_1.getEscalationItems; } });
+Object.defineProperty(exports, "getEscalationItemsBySignalKey", { enumerable: true, get: function () { return accumulate_1.getEscalationItemsBySignalKey; } });
 Object.defineProperty(exports, "itemsView", { enumerable: true, get: function () { return accumulate_1.itemsView; } });
 var metadata_1 = require("./metadata");
 Object.defineProperty(exports, "findByMetadata", { enumerable: true, get: function () { return metadata_1.findByMetadata; } });

package/build/api/scan-codes/context.d.ts

@@ -16,8 +16,21 @@ export interface StepContext {
 }
 export declare function targetFilter(step: ScanStep, ctx: StepContext): Record<string, any>;
 export declare function templateContext(ctx: StepContext): scanCodeService.ScanTemplateContext;
+/**
+ * The metadata of the acting user's single live claim, or undefined when
+ * they hold none or more than one. One scoped list query, read before the
+ * guarded write; the write re-checks everything under lock.
+ */
+export declare function liveClaimMetadata(ctx: StepContext): Promise<Record<string, unknown> | undefined>;
+/**
+ * The template context for one step: the scan tokens, the located item row's
+ * metadata when the verb has one, and the actor's live claim when the step's
+ * params mention `{claim.…}` (the lookup costs one query, so it runs only
+ * then).
+ */
+export declare function stepTemplate(step: ScanStep, ctx: StepContext, item?: LTEscalationRecord): Promise<scanCodeService.ScanTemplateContext>;
 export declare function provenance(ctx: StepContext): Record<string, any>;
-export declare function interpolatedMetadata(step: ScanStep, ctx: StepContext): Record<string, any>;
+export declare function interpolatedMetadata(step: ScanStep, ctx: StepContext, tpl?: scanCodeService.ScanTemplateContext): Record<string, any>;
 export declare function executed(escalation: LTEscalationRecord | Record<string, any> | undefined, step: Pick<ScanStep, 'verb'>): LTApiResult<ScanExecuteResponse>;
 export declare function forbidden(error?: string): LTApiResult<ScanExecuteResponse>;
 export declare function conflict(error?: string): LTApiResult<ScanExecuteResponse>;

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

@@ -35,6 +35,8 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.targetFilter = targetFilter;
 exports.templateContext = templateContext;
+exports.liveClaimMetadata = liveClaimMetadata;
+exports.stepTemplate = stepTemplate;
 exports.provenance = provenance;
 exports.interpolatedMetadata = interpolatedMetadata;
 exports.executed = executed;
@@ -42,6 +44,7 @@ exports.forbidden = forbidden;
 exports.conflict = conflict;
 exports.notPrimed = notPrimed;
 const scanCodeService = __importStar(require("../../services/scan-code"));
+const escalationService = __importStar(require("../../services/escalation"));
 const types_1 = require("../../types");
 function targetFilter(step, ctx) {
     return { [ctx.scheme.target_facet]: ctx.parsed.target, ...(step.query?.facets ?? {}) };
@@ -49,6 +52,31 @@ function targetFilter(step, ctx) {
 function templateContext(ctx) {
     return { target: ctx.parsed.target, category: ctx.parsed.category, scannedAt: ctx.scannedAt };
 }
+/**
+ * The metadata of the acting user's single live claim, or undefined when
+ * they hold none or more than one. One scoped list query, read before the
+ * guarded write; the write re-checks everything under lock.
+ */
+async function liveClaimMetadata(ctx) {
+    const { escalations } = await escalationService.listEscalations({
+        assigned_to: ctx.auth.userId,
+        status: 'pending',
+        limit: 2,
+    });
+    const live = escalations.filter(types_1.isEffectivelyClaimed);
+    return live.length === 1 ? (live[0].metadata ?? {}) : undefined;
+}
+/**
+ * The template context for one step: the scan tokens, the located item row's
+ * metadata when the verb has one, and the actor's live claim when the step's
+ * params mention `{claim.…}` (the lookup costs one query, so it runs only
+ * then).
+ */
+async function stepTemplate(step, ctx, item) {
+    const base = templateContext(ctx);
+    const claim = scanCodeService.mentionsClaimToken(step.params) ? await liveClaimMetadata(ctx) : undefined;
+    return { ...base, ...(item ? { item: item.metadata ?? {} } : {}), ...(claim ? { claim } : {}) };
+}
 function provenance(ctx) {
     return {
         [types_1.SCAN_PROVENANCE_KEYS.SCHEME]: ctx.scheme.version,
@@ -60,9 +88,9 @@ function provenance(ctx) {
         ...(ctx.acting ? { [types_1.SCAN_PROVENANCE_KEYS.STATION]: ctx.stationAuth.userId } : {}),
     };
 }
-function interpolatedMetadata(step, ctx) {
+function interpolatedMetadata(step, ctx, tpl = templateContext(ctx)) {
     return step.params?.metadata
-        ? scanCodeService.interpolateScanTemplate(step.params.metadata, templateContext(ctx))
+        ? scanCodeService.interpolateScanTemplate(step.params.metadata, tpl)
         : {};
 }
 function executed(escalation, step) {

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

@@ -94,6 +94,7 @@ async function executeIdentityScan(parsed, scheme, rule, previousActingToken) {
             actor: { id: user.id, displayName: user.display_name || user.external_id },
             actingToken: (0, ephemeral_1.formatEphemeralToken)(uuid, types_1.ACTING_IDENTITY_LABEL),
             expiresAt,
+            maxUses: scheme.grant_max_uses ?? 0,
         },
     };
 }

package/build/api/scan-codes/verbs.d.ts

@@ -20,11 +20,17 @@ export declare function cancelStep(step: ScanStep, ctx: StepContext): Promise<LT
  *   item's own pending row through the scheme facet, reads the container
  *   facet value it carries, and adds the target to the container that shares
  *   it, writing the item row as the reciprocal in the same statement. An
- *   item with no row, or no container facet, falls through.
+ *   item with no row, or no container facet, falls through. An item whose
+ *   container has closed and whose successor has not parked yet answers
+ *   `no_open_container` with the item row, so the station can say "scan
+ *   again" instead of showing the bag with no hint.
  * - Container-locate (no `containerFacet`): the scan locates the container
  *   by the scheme facet and adds `params.itemKey` (template).
  *
- * The write is the SDK's guarded statement; the locate only picks ids. A
- * container already holding the item answers conflict, never a second add.
+ * Templates may read `{claim.<facet>}` (the actor's live claim) and, in item
+ * mode, `{item.<facet>}` (the located row); an unresolvable token falls
+ * through. The write is the SDK's guarded statement; the locate only picks
+ * ids. A container already holding the item answers conflict, never a
+ * second add.
  */
 export declare function accumulateStep(step: ScanStep, ctx: StepContext): Promise<LTApiResult<ScanExecuteResponse> | null>;

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

@@ -54,12 +54,30 @@ const locate_1 = require("./locate");
 // ctx.auth is the effective actor: the badged person when a grant rode the
 // request, otherwise the authenticated principal. Attribution and write
 // scoping both derive from it, live, inside the escalation APIs.
+/**
+ * Interpolates a step's params, or falls through when a `{claim.…}` or
+ * `{item.…}` token has nothing to read: a literal token never reaches a row.
+ */
+async function templated(step, ctx, render, item) {
+    const tpl = await (0, context_1.stepTemplate)(step, ctx, item);
+    try {
+        return render(tpl);
+    }
+    catch (err) {
+        if (err instanceof scanCodeService.ScanTemplateError)
+            return null;
+        throw err;
+    }
+}
 async function claimStep(step, ctx) {
+    const metadata = await templated(step, ctx, (tpl) => (0, context_1.interpolatedMetadata)(step, ctx, tpl));
+    if (metadata === null)
+        return null;
     const result = await (0, metadata_1.claimByMetadata)({
         key: ctx.scheme.target_facet,
         value: ctx.parsed.target,
         durationMinutes: step.params?.durationMinutes,
-        metadata: { ...(0, context_1.interpolatedMetadata)(step, ctx), ...(0, context_1.provenance)(ctx) },
+        metadata: { ...metadata, ...(0, context_1.provenance)(ctx) },
         restrictRoles: step.query?.roles,
     }, ctx.auth);
     if (result.status === 404)
@@ -71,11 +89,17 @@ async function claimStep(step, ctx) {
     return (0, context_1.executed)(result.data.escalation, step);
 }
 async function resolveStep(step, ctx) {
+    const rendered = await templated(step, ctx, (tpl) => ({
+        resolverPayload: scanCodeService.interpolateScanTemplate(step.params?.resolverPayload ?? {}, tpl),
+        metadata: (0, context_1.interpolatedMetadata)(step, ctx, tpl),
+    }));
+    if (rendered === null)
+        return null;
     const result = await (0, metadata_1.resolveByMetadata)({
         key: ctx.scheme.target_facet,
         value: ctx.parsed.target,
-        resolverPayload: scanCodeService.interpolateScanTemplate(step.params?.resolverPayload ?? {}, (0, context_1.templateContext)(ctx)),
-        metadata: { ...(0, context_1.interpolatedMetadata)(step, ctx), ...(0, context_1.provenance)(ctx) },
+        resolverPayload: rendered.resolverPayload,
+        metadata: { ...rendered.metadata, ...(0, context_1.provenance)(ctx) },
         restrictRoles: step.query?.roles,
         extraFacets: step.query?.facets,
     }, ctx.auth);
@@ -213,35 +237,52 @@ async function cancelStep(step, ctx) {
  *   item's own pending row through the scheme facet, reads the container
  *   facet value it carries, and adds the target to the container that shares
  *   it, writing the item row as the reciprocal in the same statement. An
- *   item with no row, or no container facet, falls through.
+ *   item with no row, or no container facet, falls through. An item whose
+ *   container has closed and whose successor has not parked yet answers
+ *   `no_open_container` with the item row, so the station can say "scan
+ *   again" instead of showing the bag with no hint.
  * - Container-locate (no `containerFacet`): the scan locates the container
  *   by the scheme facet and adds `params.itemKey` (template).
  *
- * The write is the SDK's guarded statement; the locate only picks ids. A
- * container already holding the item answers conflict, never a second add.
+ * Templates may read `{claim.<facet>}` (the actor's live claim) and, in item
+ * mode, `{item.<facet>}` (the located row); an unresolvable token falls
+ * through. The write is the SDK's guarded statement; the locate only picks
+ * ids. A container already holding the item answers conflict, never a
+ * second add.
  */
 async function accumulateStep(step, ctx) {
-    const tpl = (0, context_1.templateContext)(ctx);
-    const payload = step.params?.resolverPayload
-        ? scanCodeService.interpolateScanTemplate(step.params.resolverPayload, tpl)
-        : undefined;
-    const metadata = { ...(0, context_1.interpolatedMetadata)(step, ctx), ...(0, context_1.provenance)(ctx) };
     const options = step.params?.accumulate;
-    let request;
+    let item;
     if (options?.containerFacet) {
         const located = await (0, locate_1.locateForStep)(step, ctx, 1);
-        const item = located?.escalations[0];
+        item = located?.escalations[0];
         if (!item)
             return null;
+    }
+    const rendered = await templated(step, ctx, (tpl) => ({
+        payload: step.params?.resolverPayload
+            ? scanCodeService.interpolateScanTemplate(step.params.resolverPayload, tpl)
+            : undefined,
+        metadata: { ...(0, context_1.interpolatedMetadata)(step, ctx, tpl), ...(0, context_1.provenance)(ctx) },
+        itemKey: options?.containerFacet
+            ? ctx.parsed.target
+            : scanCodeService.interpolateScanTemplate(step.params.itemKey, tpl),
+    }), item);
+    if (rendered === null)
+        return null;
+    let request;
+    let container;
+    if (options?.containerFacet && item) {
         const containerValue = item.metadata?.[options.containerFacet];
         if (containerValue === undefined || containerValue === null || containerValue === '')
             return null;
+        container = { facet: options.containerFacet, value: String(containerValue) };
         request = {
-            key: options.containerFacet,
-            value: String(containerValue),
-            itemKey: ctx.parsed.target,
-            payload,
-            metadata,
+            key: container.facet,
+            value: container.value,
+            itemKey: rendered.itemKey,
+            payload: rendered.payload,
+            metadata: rendered.metadata,
             restrictRoles: options.containerRoles,
             ...(options.reciprocal === false ? {} : { reciprocal: { id: item.id } }),
         };
@@ -250,15 +291,28 @@ async function accumulateStep(step, ctx) {
         request = {
             key: ctx.scheme.target_facet,
             value: ctx.parsed.target,
-            itemKey: scanCodeService.interpolateScanTemplate(step.params.itemKey, tpl),
-            payload,
-            metadata,
+            itemKey: rendered.itemKey,
+            payload: rendered.payload,
+            metadata: rendered.metadata,
             restrictRoles: step.query?.roles,
         };
     }
     const result = await (0, accumulate_1.accumulateItemByMetadata)(request, ctx.auth);
-    if (result.status === 404)
-        return null;
+    if (result.status === 404) {
+        if (!container || !item)
+            return null;
+        return {
+            status: 200,
+            data: {
+                outcome: types_1.SCAN_OUTCOMES.NO_OPEN_CONTAINER,
+                verb: step.verb,
+                escalation: item,
+                container,
+                fallback: ctx.rule.fallback,
+                error: `No open container carries ${container.facet} = ${container.value}`,
+            },
+        };
+    }
     if (result.status === 403)
         return (0, context_1.forbidden)(result.error);
     if (result.status === 409)

package/build/index.d.ts

@@ -3,7 +3,8 @@ export { midnightTheme } from './themes/midnight';
 export { registerLT, createLTInterceptor } from './services/interceptor';
 export { createLTActivityInterceptor } from './services/interceptor/activity-interceptor';
 export { executeLT } from './services/orchestrator';
-export { conditional, conditionLT } from './services/orchestrator/condition';
+export { conditional, conditionLT, conditionalAccumulator } from './services/orchestrator/condition';
+export type { ConditionEscalationConfig, ConditionAccumulatorConfig } from './services/orchestrator/condition';
 export type { ExecuteLTOptions } from './services/orchestrator/types';
 export { JwtAuthAdapter, createAuthMiddleware, requireAuth, requireAdmin, signToken, setAuthAdapter } from './modules/auth';
 export * from './types';

package/build/index.js

@@ -36,8 +36,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getActivityIdentity = exports.McpEscalationStrategy = exports.DefaultEscalationStrategy = exports.escalationStrategyRegistry = exports.McpVisionServer = exports.McpTranslationServer = exports.McpServer = exports.McpClient = exports.McpService = exports.BuiltInMcpAdapter = exports.mcpRegistry = exports.defaultMaintenanceConfig = exports.maintenanceRegistry = exports.PinoLoggerAdapter = exports.loggerRegistry = exports.HoneycombTelemetryAdapter = exports.telemetryRegistry = exports.publishKnowledgeEvent = exports.publishAgentEvent = exports.publishWorkflowEvent = exports.publishActivityEvent = exports.publishEscalationEvent = exports.publishTaskEvent = exports.publishMilestoneEvent = exports.SocketIOEventAdapter = exports.InMemoryEventAdapter = exports.NatsEventAdapter = exports.eventRegistry = exports.ltConfig = exports.seedConfigTopics = exports.seedSystemTopics = exports.TopicService = exports.UserService = exports.ConfigService = exports.EscalationService = exports.TaskService = exports.setAuthAdapter = exports.signToken = exports.requireAdmin = exports.requireAuth = exports.createAuthMiddleware = exports.JwtAuthAdapter = exports.conditionLT = exports.conditional = exports.executeLT = exports.createLTActivityInterceptor = exports.createLTInterceptor = exports.registerLT = exports.midnightTheme = exports.start = void 0;
-exports.LTExpressAdapter = exports.api = exports.KnowledgeApi = exports.resolveCredential = exports.mimeFromPath = exports.getStorageBackend = exports.listOAuthConnections = exports.getFreshAccessToken = exports.createClient = exports.CallbackEventAdapter = exports.builtinMcpServerFactories = exports.getSystemAgents = exports.getSystemWorkers = exports.registerMcpTool = exports.getToolContext = void 0;
+exports.McpEscalationStrategy = exports.DefaultEscalationStrategy = exports.escalationStrategyRegistry = exports.McpVisionServer = exports.McpTranslationServer = exports.McpServer = exports.McpClient = exports.McpService = exports.BuiltInMcpAdapter = exports.mcpRegistry = exports.defaultMaintenanceConfig = exports.maintenanceRegistry = exports.PinoLoggerAdapter = exports.loggerRegistry = exports.HoneycombTelemetryAdapter = exports.telemetryRegistry = exports.publishKnowledgeEvent = exports.publishAgentEvent = exports.publishWorkflowEvent = exports.publishActivityEvent = exports.publishEscalationEvent = exports.publishTaskEvent = exports.publishMilestoneEvent = exports.SocketIOEventAdapter = exports.InMemoryEventAdapter = exports.NatsEventAdapter = exports.eventRegistry = exports.ltConfig = exports.seedConfigTopics = exports.seedSystemTopics = exports.TopicService = exports.UserService = exports.ConfigService = exports.EscalationService = exports.TaskService = exports.setAuthAdapter = exports.signToken = exports.requireAdmin = exports.requireAuth = exports.createAuthMiddleware = exports.JwtAuthAdapter = exports.conditionalAccumulator = exports.conditionLT = exports.conditional = exports.executeLT = exports.createLTActivityInterceptor = exports.createLTInterceptor = exports.registerLT = exports.midnightTheme = exports.start = void 0;
+exports.LTExpressAdapter = exports.api = exports.KnowledgeApi = exports.resolveCredential = exports.mimeFromPath = exports.getStorageBackend = exports.listOAuthConnections = exports.getFreshAccessToken = exports.createClient = exports.CallbackEventAdapter = exports.builtinMcpServerFactories = exports.getSystemAgents = exports.getSystemWorkers = exports.registerMcpTool = exports.getToolContext = exports.getActivityIdentity = void 0;
 const config_1 = require("./modules/config");
 const logger_1 = require("./lib/logger");
 const midnight_1 = require("./themes/midnight");
@@ -57,6 +57,7 @@ Object.defineProperty(exports, "executeLT", { enumerable: true, get: function ()
 var condition_1 = require("./services/orchestrator/condition");
 Object.defineProperty(exports, "conditional", { enumerable: true, get: function () { return condition_1.conditional; } });
 Object.defineProperty(exports, "conditionLT", { enumerable: true, get: function () { return condition_1.conditionLT; } });
+Object.defineProperty(exports, "conditionalAccumulator", { enumerable: true, get: function () { return condition_1.conditionalAccumulator; } });
 var auth_1 = require("./modules/auth");
 Object.defineProperty(exports, "JwtAuthAdapter", { enumerable: true, get: function () { return auth_1.JwtAuthAdapter; } });
 Object.defineProperty(exports, "createAuthMiddleware", { enumerable: true, get: function () { return auth_1.createAuthMiddleware; } });

package/build/routes/escalations/accumulate.js

@@ -101,6 +101,14 @@ function registerAccumulateRoutes(router) {
         }, req.auth);
         res.status(result.status).json(result.data ?? { error: result.error });
     });
+    /**
+     * GET /api/escalations/items-by-signal-key?signalKey=…
+     * The held items of an accumulator or batch row by its signal_key.
+     */
+    router.get('/items-by-signal-key', async (req, res) => {
+        const result = await api.getEscalationItemsBySignalKey({ signalKey: String(req.query.signalKey ?? '') }, req.auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
     /**
      * POST /api/escalations/:id/accumulate
      * Add one item. Interim adds answer { outcome: 'accepted', count, remaining };

package/build/sdk/index.d.ts

@@ -269,6 +269,9 @@ export declare function createClient(options?: LTClientOptions): {
         getItems: (input: {
             id: string;
         }, auth?: LTApiAuth) => Promise<LTApiResult<import("../api/escalations/accumulate").EscalationItemsView>>;
+        getItemsBySignalKey: (input: {
+            signalKey: string;
+        }, auth?: LTApiAuth) => Promise<LTApiResult<import("../api/escalations/accumulate").EscalationItemsView>>;
         searchByFacets: (input: import("..").FacetQuery, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         claimGroups: (input: {
             query: import("..").FacetQuery;

package/build/sdk/index.js

@@ -154,6 +154,7 @@ function createClient(options = {}) {
             removeItemBySignalKey: bindAuth(escalationsApi.removeItemBySignalKey, auth),
             removeItemByMetadata: bindAuth(escalationsApi.removeItemByMetadata, auth),
             getItems: bindAuth(escalationsApi.getEscalationItems, auth),
+            getItemsBySignalKey: bindAuth(escalationsApi.getEscalationItemsBySignalKey, auth),
             // Faceted-routing surface (pond search + batch claim), RBAC-scoped to the caller's role.
             searchByFacets: bindAuth(escalationsApi.searchByFacets, auth),
             claimGroups: bindAuth(escalationsApi.claimGroups, auth),

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

@@ -1,4 +1,4 @@
 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, type ScanParseResult, type ScanParseFailure, type ScanTemplateContext, } from './parse';
+export { parseScanCode, interpolateScanTemplate, mentionsClaimToken, ScanTemplateError, type ScanParseResult, type ScanParseFailure, type ScanTemplateContext, } from './parse';
 export { assertValidScheme, assertValidSteps } from './validate';

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.assertValidSteps = exports.assertValidScheme = 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.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;
 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; } });
@@ -18,6 +18,8 @@ Object.defineProperty(exports, "applyScanRule", { enumerable: true, get: functio
 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, "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; } });

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

@@ -26,10 +26,24 @@ export interface ScanTemplateContext {
     target: string;
     category: string;
     scannedAt: 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. */
+    item?: Record<string, unknown>;
 }
+/** A `{claim.x}` or `{item.x}` token the context cannot resolve. */
+export declare class ScanTemplateError extends Error {
+    readonly token: string;
+    readonly reason: string;
+    constructor(token: string, reason: string);
+}
+/** True when any string in the params mentions a `{claim.…}` token. */
+export declare function mentionsClaimToken(value: unknown): boolean;
 /**
- * Replace SCAN_TEMPLATE_TOKENS inside string values of a params object.
- * Deep, pure, non-mutating. Only exact-token and in-string replacement of
- * the three known tokens — no expression language.
+ * 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.
  */
 export declare function interpolateScanTemplate<T>(value: T, ctx: ScanTemplateContext): T;

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

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScanTemplateError = void 0;
 exports.parseScanCode = parseScanCode;
+exports.mentionsClaimToken = mentionsClaimToken;
 exports.interpolateScanTemplate = interpolateScanTemplate;
 const types_1 = require("../../types");
 /**
@@ -82,17 +84,48 @@ function malformed(scheme, detail) {
         failure: { reason: 'malformed', detail: `scheme ${scheme.version} ("${scheme.name}"): ${detail}` },
     };
 }
+/** A `{claim.x}` or `{item.x}` token the context cannot resolve. */
+class ScanTemplateError extends Error {
+    constructor(token, reason) {
+        super(`scan template ${token}: ${reason}`);
+        this.token = token;
+        this.reason = reason;
+        this.name = 'ScanTemplateError';
+    }
+}
+exports.ScanTemplateError = ScanTemplateError;
+const BAG_TOKEN = /\{(claim|item)\.([a-zA-Z0-9_]+)\}/g;
+/** True when any string in the params mentions a `{claim.…}` token. */
+function mentionsClaimToken(value) {
+    return JSON.stringify(value ?? null).includes(`{${types_1.SCAN_TEMPLATE_BAGS.CLAIM}.`);
+}
+function resolveBagToken(ctx, bag, facet, token) {
+    const source = bag === types_1.SCAN_TEMPLATE_BAGS.CLAIM ? ctx.claim : ctx.item;
+    if (!source) {
+        throw new ScanTemplateError(token, bag === types_1.SCAN_TEMPLATE_BAGS.CLAIM
+            ? 'the actor holds no single live claim'
+            : 'no located item row on this step');
+    }
+    const v = source[facet];
+    if (v === undefined || v === null || v === '') {
+        throw new ScanTemplateError(token, `facet ${facet} is absent`);
+    }
+    return typeof v === 'object' ? JSON.stringify(v) : String(v);
+}
 /**
- * Replace SCAN_TEMPLATE_TOKENS inside string values of a params object.
- * Deep, pure, non-mutating. Only exact-token and in-string replacement of
- * the three known tokens — no expression language.
+ * 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.
  */
 function interpolateScanTemplate(value, ctx) {
     if (typeof value === 'string') {
-        return value
+        const scanned = value
             .split(types_1.SCAN_TEMPLATE_TOKENS.TARGET).join(ctx.target)
             .split(types_1.SCAN_TEMPLATE_TOKENS.CATEGORY).join(ctx.category)
             .split(types_1.SCAN_TEMPLATE_TOKENS.SCANNED_AT).join(ctx.scannedAt);
+        return scanned.replace(BAG_TOKEN, (token, bag, facet) => resolveBagToken(ctx, bag, facet, token));
     }
     if (Array.isArray(value)) {
         return value.map((v) => interpolateScanTemplate(v, ctx));