@hotmeshio/long-tail 0.30.3 → 0.30.5

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

@@ -8,6 +8,7 @@ export { resolveEscalation, resolveBySignalKey, resolveByIds, resolveAllOrNone }
 export { resolveBatchItem, resolveBatchItemBySignalKey, resolveBatchItemByMetadata } from './resolve-batch';
 export { flagBatchItem, unflagBatchItem } from './batch-flag';
 export { runRosterAction, ROSTER_ACTION_OUTCOMES } from './roster-action';
+export { runRosterScan, ROSTER_SCAN_OUTCOMES } from './roster-scan';
 export { accumulateItem, accumulateItemBySignalKey, accumulateItemByMetadata, removeItem, removeItemBySignalKey, removeItemByMetadata, getEscalationItems, getEscalationItemsBySignalKey, itemsView, } from './accumulate';
 export { findByMetadata, claimByMetadata, resolveByMetadata } from './metadata';
 export { cancelSingleEscalation, bulkCancel } from './cancel';

package/build/api/escalations/index.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-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.ROSTER_ACTION_OUTCOMES = exports.runRosterAction = exports.unflagBatchItem = exports.flagBatchItem = 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.getRelatedRows = exports.getRelatedAggregates = exports.timelineByFacet = void 0;
+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.ROSTER_SCAN_OUTCOMES = exports.runRosterScan = exports.ROSTER_ACTION_OUTCOMES = exports.runRosterAction = exports.unflagBatchItem = exports.flagBatchItem = 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.getRelatedRows = exports.getRelatedAggregates = exports.timelineByFacet = exports.aggregateByFacets = exports.claimByFacets = void 0;
 var create_1 = require("./create");
 Object.defineProperty(exports, "createEscalation", { enumerable: true, get: function () { return create_1.createEscalation; } });
 var list_1 = require("./list");
@@ -44,6 +44,9 @@ Object.defineProperty(exports, "unflagBatchItem", { enumerable: true, get: funct
 var roster_action_1 = require("./roster-action");
 Object.defineProperty(exports, "runRosterAction", { enumerable: true, get: function () { return roster_action_1.runRosterAction; } });
 Object.defineProperty(exports, "ROSTER_ACTION_OUTCOMES", { enumerable: true, get: function () { return roster_action_1.ROSTER_ACTION_OUTCOMES; } });
+var roster_scan_1 = require("./roster-scan");
+Object.defineProperty(exports, "runRosterScan", { enumerable: true, get: function () { return roster_scan_1.runRosterScan; } });
+Object.defineProperty(exports, "ROSTER_SCAN_OUTCOMES", { enumerable: true, get: function () { return roster_scan_1.ROSTER_SCAN_OUTCOMES; } });
 var accumulate_1 = require("./accumulate");
 Object.defineProperty(exports, "accumulateItem", { enumerable: true, get: function () { return accumulate_1.accumulateItem; } });
 Object.defineProperty(exports, "accumulateItemBySignalKey", { enumerable: true, get: function () { return accumulate_1.accumulateItemBySignalKey; } });

package/build/api/escalations/roster-action.d.ts

@@ -1,4 +1,5 @@
 import type { LTApiAuth, LTApiResult } from '../../types/sdk';
+import type { LTEscalationRecord } from '../../types';
 /** Outcomes a roster action answers with besides the act's own result. */
 export declare const ROSTER_ACTION_OUTCOMES: {
     /** The action is limited to roles the person acting does not hold, and no badge rode the request. */
@@ -35,3 +36,13 @@ export interface RosterActionInput {
  * act that does not land returns the use.
  */
 export declare function runRosterAction(input: RosterActionInput, auth: LTApiAuth): Promise<LTApiResult>;
+/** The host row and one field of its pinned form, or null when the row is gone or unreadable. */
+export declare function loadHostField(id: string, field: string, auth: LTApiAuth): Promise<{
+    host: LTEscalationRecord;
+    fieldSchema: Record<string, unknown> | undefined;
+} | null>;
+/** Spend the badge, run the act, and return the use when the act does not land. */
+export declare function spendAndRun(actingToken: string | undefined, run: () => Promise<LTApiResult>): Promise<LTApiResult>;
+/** The person acting: the badge's person when one rides the request, read without spending it. */
+export declare function actorFor(actingToken: string | undefined, auth: LTApiAuth): Promise<LTApiAuth | LTApiResult>;
+export declare function refusal(status: number, outcome: string, error: string): LTApiResult;

package/build/api/escalations/roster-action.js

@@ -35,6 +35,10 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ROSTER_ACTION_OUTCOMES = void 0;
 exports.runRosterAction = runRosterAction;
+exports.loadHostField = loadHostField;
+exports.spendAndRun = spendAndRun;
+exports.actorFor = actorFor;
+exports.refusal = refusal;
 const escalationService = __importStar(require("../../services/escalation"));
 const userService = __importStar(require("../../services/user"));
 const roster_1 = require("../../services/escalation/roster");
@@ -77,14 +81,10 @@ async function runRosterAction(input, auth) {
             return { status: 400, error: 'id, field, action and entry are required' };
         }
         // 1. The host row and its form, as the page that offered the action read them
-        const detail = await escalationService.getEscalationWithFormSchema(input.id);
-        if (!detail || (await (0, helpers_1.assertReadAccess)(auth.userId, detail.escalation))) {
+        const loaded = await loadHostField(input.id, input.field, auth);
+        if (!loaded)
             return { status: 404, error: 'Escalation not found' };
-        }
-        const host = detail.escalation;
-        const embedded = host.metadata?.form_schema;
-        const schema = (embedded && typeof embedded === 'object' ? embedded : detail.form_schema);
-        const fieldSchema = schema?.properties?.[input.field];
+        const { host, fieldSchema } = loaded;
         const def = (0, form_validation_1.readRosterDef)(fieldSchema);
         const action = (0, form_validation_1.readRosterActions)(fieldSchema)[input.action];
         if (!def || !action)
@@ -104,40 +104,57 @@ async function runRosterAction(input, auth) {
             return { status: 422, error, data: { error, outcome: 'code_mismatch' } };
         }
         // 3. The person acting: the badge's person when one rides the request, read without spending it
-        let actor = auth;
-        if (input.actingToken) {
-            const peeked = await (0, acting_identity_1.peekActingAuth)(input.actingToken);
-            if (!peeked.ok)
-                return refusal(401, exports.ROSTER_ACTION_OUTCOMES.NOT_PRIMED, peeked.error);
-            actor = peeked.auth;
-        }
+        const actor = await actorFor(input.actingToken, auth);
+        if ('status' in actor)
+            return actor;
         if (!(await holdsRole(action, actor.userId))) {
             return input.actingToken
                 ? refusal(403, exports.ROSTER_ACTION_OUTCOMES.ROLE_REFUSED, (0, form_validation_1.actionRefusal)(action))
                 : refusal(403, exports.ROSTER_ACTION_OUTCOMES.NEEDS_BADGE, (0, form_validation_1.actionRefusal)(action));
         }
         // 4. Spend the badge, run the act, and return the use when it does not land
-        let remaining;
-        if (input.actingToken) {
-            const spent = await (0, acting_identity_1.consumeActingGrant)(input.actingToken);
-            if (!spent.ok)
-                return refusal(401, exports.ROSTER_ACTION_OUTCOMES.NOT_PRIMED, spent.error);
-            remaining = spent.grant.remaining;
-        }
-        const result = await runAct(kind, action, entry, host.id, ctx, input.code, actor);
-        if (input.actingToken && result.status >= 300) {
-            await (0, acting_identity_1.refundActingGrant)(input.actingToken, false);
-            return result;
-        }
-        if (input.actingToken && result.data && typeof result.data === 'object') {
-            result.data = { ...result.data, acting: { remaining } };
-        }
-        return result;
+        return spendAndRun(input.actingToken, () => runAct(kind, action, entry, host.id, ctx, input.code, actor));
     }
     catch (err) {
         return { status: 500, error: err.message };
     }
 }
+/** The host row and one field of its pinned form, or null when the row is gone or unreadable. */
+async function loadHostField(id, field, auth) {
+    const detail = await escalationService.getEscalationWithFormSchema(id);
+    if (!detail || (await (0, helpers_1.assertReadAccess)(auth.userId, detail.escalation)))
+        return null;
+    const host = detail.escalation;
+    const embedded = host.metadata?.form_schema;
+    const schema = (embedded && typeof embedded === 'object' ? embedded : detail.form_schema);
+    return { host, fieldSchema: schema?.properties?.[field] };
+}
+/** Spend the badge, run the act, and return the use when the act does not land. */
+async function spendAndRun(actingToken, run) {
+    let remaining;
+    if (actingToken) {
+        const spent = await (0, acting_identity_1.consumeActingGrant)(actingToken);
+        if (!spent.ok)
+            return refusal(401, exports.ROSTER_ACTION_OUTCOMES.NOT_PRIMED, spent.error);
+        remaining = spent.grant.remaining;
+    }
+    const result = await run();
+    if (actingToken && result.status >= 300) {
+        await (0, acting_identity_1.refundActingGrant)(actingToken, false);
+        return result;
+    }
+    if (actingToken && result.data && typeof result.data === 'object') {
+        result.data = { ...result.data, acting: { remaining } };
+    }
+    return result;
+}
+/** The person acting: the badge's person when one rides the request, read without spending it. */
+async function actorFor(actingToken, auth) {
+    if (!actingToken)
+        return auth;
+    const peeked = await (0, acting_identity_1.peekActingAuth)(actingToken);
+    return peeked.ok ? peeked.auth : refusal(401, exports.ROSTER_ACTION_OUTCOMES.NOT_PRIMED, peeked.error);
+}
 async function holdsRole(action, userId) {
     if (!action.roles?.length)
         return true;

package/build/api/escalations/roster-scan.d.ts

@@ -0,0 +1,26 @@
+import type { LTApiAuth, LTApiResult } from '../../types/sdk';
+/** Outcomes a roster scan answers with besides the fill's own result. */
+export declare const ROSTER_SCAN_OUTCOMES: {
+    /** The field takes no scans, or not this code's scheme. */
+    readonly NOT_ACCEPTED: "not_accepted";
+    /** No open entry on the list is this code. */
+    readonly UNEXPECTED: "unexpected";
+};
+export interface RosterScanInput {
+    /** The host row: the escalation whose form declares the roster. */
+    id: string;
+    /** The roster field. */
+    field: string;
+    /** The code as scanned. */
+    code: string;
+    /** A badge grant: the fill runs as its person. */
+    actingToken?: string;
+}
+/**
+ * A scan into a batch roster on an open form. The field must declare
+ * `x-lt-scan` accepting the code's scheme; the scan fills the first open
+ * entry whose key is that code, as the person acting, with `scannedCode` as
+ * the entry's payload. Nothing about the request is trusted: the roster and
+ * its entries are re-read from the host row.
+ */
+export declare function runRosterScan(input: RosterScanInput, auth: LTApiAuth): Promise<LTApiResult>;

package/build/api/escalations/roster-scan.js

@@ -0,0 +1,114 @@
+"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.ROSTER_SCAN_OUTCOMES = void 0;
+exports.runRosterScan = runRosterScan;
+const scanCodeService = __importStar(require("../../services/scan-code"));
+const roster_1 = require("../../services/escalation/roster");
+const form_validation_1 = require("../../shared/form-validation");
+const types_1 = require("../../types");
+const roster_action_1 = require("./roster-action");
+const resolve_batch_1 = require("./resolve-batch");
+/** Outcomes a roster scan answers with besides the fill's own result. */
+exports.ROSTER_SCAN_OUTCOMES = {
+    /** The field takes no scans, or not this code's scheme. */
+    NOT_ACCEPTED: 'not_accepted',
+    /** No open entry on the list is this code. */
+    UNEXPECTED: 'unexpected',
+};
+const STOCK_UNEXPECTED = 'Not one of the items expected here.';
+/** A batch fill whose key was filled since the roster was read. */
+const DUPLICATE_ITEM = 'duplicate-item';
+function refused(status, outcome, error) {
+    return { status, error, data: { error, outcome } };
+}
+/**
+ * A scan into a batch roster on an open form. The field must declare
+ * `x-lt-scan` accepting the code's scheme; the scan fills the first open
+ * entry whose key is that code, as the person acting, with `scannedCode` as
+ * the entry's payload. Nothing about the request is trusted: the roster and
+ * its entries are re-read from the host row.
+ */
+async function runRosterScan(input, auth) {
+    try {
+        if (!input?.id || typeof input.field !== 'string' || typeof input.code !== 'string' || !input.code.trim()) {
+            return { status: 400, error: 'id, field and code are required' };
+        }
+        // 1. The host row and a batch roster that takes this code's scheme
+        const loaded = await (0, roster_action_1.loadHostField)(input.id, input.field, auth);
+        if (!loaded)
+            return { status: 404, error: 'Escalation not found' };
+        const def = (0, form_validation_1.readRosterDef)(loaded.fieldSchema);
+        const sink = (0, form_validation_1.readScanSink)(loaded.fieldSchema);
+        if (!def || !('batch' in def.expected) || !sink) {
+            return refused(409, exports.ROSTER_SCAN_OUTCOMES.NOT_ACCEPTED, 'This list takes no scans');
+        }
+        const parsed = scanCodeService.parseScanCode(input.code.trim(), await scanCodeService.listScanSchemes());
+        if (!parsed.ok || parsed.scheme.kind !== types_1.SCAN_SCHEME_KINDS.ACTION || !sink.schemes.includes(parsed.parsed.version)) {
+            return refused(422, exports.ROSTER_SCAN_OUTCOMES.NOT_ACCEPTED, 'This list takes no code like that');
+        }
+        const value = sink.value === 'code' ? (parsed.parsed.raw ?? input.code.trim()) : parsed.parsed.target;
+        // 2. The open entries this code names, on the roster the server computes
+        const { escalation, metadata, envelope, payload } = (0, form_validation_1.rosterRowContext)(loaded.host);
+        const ctx = { escalation, metadata, envelope, payload };
+        const roster = await (0, roster_1.loadRoster)(def, ctx);
+        const named = roster.entries.filter((e) => (0, form_validation_1.enteredCodeMatches)(value, e.key, def.countedBy));
+        const open = named.filter((e) => e.state !== form_validation_1.ROSTER_STATES.IN);
+        if (open.length === 0) {
+            const error = named.length ? `All ${named.length} of these are already checked off.` : STOCK_UNEXPECTED;
+            return refused(422, exports.ROSTER_SCAN_OUTCOMES.UNEXPECTED, error);
+        }
+        // 3. Fill as the person acting; an entry taken since the read moves to the next
+        const actor = await (0, roster_action_1.actorFor)(input.actingToken, auth);
+        if ('status' in actor)
+            return actor;
+        return (0, roster_action_1.spendAndRun)(input.actingToken, async () => {
+            let result = { status: 409, error: 'Those entries were just checked off' };
+            for (const entry of open) {
+                result = await (0, resolve_batch_1.resolveBatchItem)({
+                    id: loaded.host.id,
+                    itemKey: entry.key,
+                    resolverPayload: { scannedCode: input.code.trim() },
+                }, actor);
+                if (result.data?.outcome !== DUPLICATE_ITEM)
+                    return result;
+            }
+            return result;
+        });
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}

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

@@ -1,5 +1,5 @@
 import * as scanCodeService from '../../services/scan-code';
-import { type LTEscalationRecord, type ParsedScanCode, type ScanExecuteResponse, type ScanRule, type ScanScheme, type ScanStep } from '../../types';
+import { type LTEscalationRecord, type ParsedScanCode, type ScanDoneCopy, type ScanExecuteResponse, type ScanRule, type ScanScheme, type ScanStep } from '../../types';
 import type { LTApiAuth, LTApiResult } from '../../types/sdk';
 /** The held subject, re-derived from the client's pointer on this request. */
 export interface HeldSubject {
@@ -42,6 +42,10 @@ export interface StepContext {
     subject?: HeldSubject;
     /** The station sent a subject pointer that no longer checks out. */
     subjectStale?: boolean;
+    /** The scanned code's own pending row, read once a step's copy or Open asks for it; null when none. */
+    located?: LTEscalationRecord | null;
+    /** The located row's role title. */
+    locatedTitle?: string | null;
 }
 export declare function targetFilter(step: ScanStep, ctx: StepContext): Record<string, any>;
 /**
@@ -51,6 +55,8 @@ export declare function targetFilter(step: ScanStep, ctx: StepContext): Record<s
  */
 export declare function targetValue(ctx: Pick<StepContext, 'scheme' | 'parsed'>): string | string[];
 export declare function templateContext(ctx: StepContext): scanCodeService.ScanTemplateContext;
+/** The `{located.x}` bag: the row's metadata plus its id, role and role title. */
+export declare function locatedBag(row: LTEscalationRecord, title?: string | null): Record<string, unknown>;
 /** The `{subject.x}` bag: the held row's metadata plus its id. */
 export declare function subjectBag(row: LTEscalationRecord): Record<string, unknown>;
 /**
@@ -85,6 +91,8 @@ export declare function templated<T>(step: ScanStep, ctx: StepContext, render: (
  * batch); an unreadable token renders empty rather than failing the act.
  */
 export declare function withDone(result: LTApiResult<ScanExecuteResponse>, step: Pick<ScanStep, 'done'>, tpl: scanCodeService.ScanTemplateContext): LTApiResult<ScanExecuteResponse>;
+/** A done copy rendered for the station: the markdown, its pause, and the line under it. */
+export declare function renderDone(done: ScanDoneCopy, tpl: scanCodeService.ScanTemplateContext): ScanDoneCopy;
 /**
  * Attach the step's `follow` to a write that completed the held subject: the
  * code the station replays and the target it waits for, so the subject's

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

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.targetFilter = targetFilter;
 exports.targetValue = targetValue;
 exports.templateContext = templateContext;
+exports.locatedBag = locatedBag;
 exports.subjectBag = subjectBag;
 exports.liveClaimMetadata = liveClaimMetadata;
 exports.stepTemplate = stepTemplate;
@@ -48,6 +49,7 @@ exports.notPrimed = notPrimed;
 exports.refused = refused;
 exports.templated = templated;
 exports.withDone = withDone;
+exports.renderDone = renderDone;
 exports.withFollow = withFollow;
 const scanCodeService = __importStar(require("../../services/scan-code"));
 const escalationService = __importStar(require("../../services/escalation"));
@@ -70,8 +72,13 @@ function templateContext(ctx) {
         scannedAt: ctx.scannedAt,
         code: ctx.parsed.raw ?? ctx.parsed.target,
         ...(ctx.subject ? { subject: subjectBag(ctx.subject.row) } : {}),
+        ...(ctx.located ? { located: locatedBag(ctx.located, ctx.locatedTitle) } : {}),
     };
 }
+/** The `{located.x}` bag: the row's metadata plus its id, role and role title. */
+function locatedBag(row, title) {
+    return { ...(row.metadata ?? {}), id: row.id, role: row.role, roleTitle: title || row.role };
+}
 /** The `{subject.x}` bag: the held row's metadata plus its id. */
 function subjectBag(row) {
     return { ...(row.metadata ?? {}), id: row.id };
@@ -168,7 +175,15 @@ function withDone(result, step, tpl) {
     const data = result.data;
     if (!step.done || !data || data.outcome !== types_1.SCAN_OUTCOMES.EXECUTED || data.already || data.done)
         return result;
-    return { ...result, data: { ...data, done: { markdown: scanCodeService.renderScanCopy(step.done.markdown, tpl) } } };
+    return { ...result, data: { ...data, done: renderDone(step.done, tpl) } };
+}
+/** A done copy rendered for the station: the markdown, its pause, and the line under it. */
+function renderDone(done, tpl) {
+    return {
+        markdown: scanCodeService.renderScanCopy(done.markdown, tpl),
+        ...(done.afterSeconds !== undefined ? { afterSeconds: done.afterSeconds } : {}),
+        ...(done.nextPrompt ? { nextPrompt: scanCodeService.renderScanCopy(done.nextPrompt, tpl) } : {}),
+    };
 }
 /**
  * Attach the step's `follow` to a write that completed the held subject: the

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

@@ -39,7 +39,9 @@ const identity_1 = require("./identity");
 const context_1 = require("./context");
 const grant_1 = require("./grant");
 const hold_1 = require("./hold");
+const located_1 = require("./located");
 const locate_1 = require("./locate");
+const open_1 = require("./open");
 const present_1 = require("./present");
 const subject_1 = require("./subject");
 const verb_fill_1 = require("./verb-fill");
@@ -116,7 +118,8 @@ async function executeScanCode(input, auth) {
             const stepResult = await executeStep(rule.steps[i], ctx);
             if (stepResult) {
                 const step = rule.steps[i];
-                result = decorate((0, context_1.withFollow)((0, context_1.withDone)(stepResult, step, (0, context_1.templateContext)(ctx)), step, ctx), ctx, i);
+                const answered = (0, context_1.withFollow)((0, context_1.withDone)(stepResult, step, (0, context_1.templateContext)(ctx)), step, ctx);
+                result = decorate(await (0, open_1.withOpen)(answered, step, ctx), ctx, i);
             }
         }
         // 4. Nothing matched: a stale subject, or the fallback screen
@@ -177,6 +180,8 @@ function subjectGateOpen(step, ctx) {
 async function executeStep(step, ctx) {
     if (!subjectGateOpen(step, ctx))
         return null;
+    if ((0, located_1.readsLocated)(step))
+        await (0, located_1.loadLocated)(ctx);
     // The identity pre-condition: the effective actor must be a real acting
     // identity — a badge grant, or an authenticated user whose own write scope
     // covers the step. A write-incapable shared account can never self-satisfy,

package/build/api/scan-codes/fill-labels.d.ts

@@ -3,6 +3,14 @@ import { type LTEscalationRecord, type ScanFillParams, type ScanScheme } from '.
 export type EntryLabeler = (key: string, code: string) => string;
 /** The code as the package prints it on a GTIN scheme, as scanned otherwise. */
 export declare function printedCode(code: string, scheme: ScanScheme): string;
+/** A per-key map the batch row carries (`envelope.<map>` or `metadata.<map>`); empty when absent. */
+export declare function rowMap(path: string, row: LTEscalationRecord): Record<string, unknown>;
+/**
+ * The open keys in the order a fill tries them. With `prefer`, the keys whose
+ * mapped value equals (or, for a list, contains) the held subject's target
+ * come first; the rest keep the row's order.
+ */
+export declare function preferredKeys(keys: string[], fill: ScanFillParams, row: LTEscalationRecord, heldTarget: string | undefined): string[];
 /**
  * The labeler a fill step declares, or null without `labels`. The map is
  * read from the batch row (`envelope.<map>` or `metadata.<map>`) and keyed by

package/build/api/scan-codes/fill-labels.js

@@ -34,6 +34,8 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.printedCode = printedCode;
+exports.rowMap = rowMap;
+exports.preferredKeys = preferredKeys;
 exports.entryLabeler = entryLabeler;
 exports.pendingLabels = pendingLabels;
 const scanCodeService = __importStar(require("../../services/scan-code"));
@@ -63,6 +65,26 @@ function asObject(v) {
 function printedCode(code, scheme) {
     return scheme.encoding === types_1.SCAN_ENCODINGS.GTIN ? scanCodeService.displayGtin(code) : code;
 }
+/** A per-key map the batch row carries (`envelope.<map>` or `metadata.<map>`); empty when absent. */
+function rowMap(path, row) {
+    const map = (0, ctx_path_1.resolveCtxPath)(path, { envelope: asObject(row.envelope), metadata: asObject(row.metadata) });
+    return isRecord(map) ? map : {};
+}
+/**
+ * The open keys in the order a fill tries them. With `prefer`, the keys whose
+ * mapped value equals (or, for a list, contains) the held subject's target
+ * come first; the rest keep the row's order.
+ */
+function preferredKeys(keys, fill, row, heldTarget) {
+    if (!fill.prefer || heldTarget === undefined)
+        return keys;
+    const owners = rowMap(fill.prefer, row);
+    const owns = (key) => {
+        const value = owners[key];
+        return (Array.isArray(value) ? value : [value]).some((v) => v !== null && v !== undefined && String(v) === heldTarget);
+    };
+    return [...keys.filter(owns), ...keys.filter((key) => !owns(key))];
+}
 /**
  * The labeler a fill step declares, or null without `labels`. The map is
  * read from the batch row (`envelope.<map>` or `metadata.<map>`) and keyed by
@@ -73,8 +95,7 @@ function printedCode(code, scheme) {
 function entryLabeler(fill, row, scheme) {
     if (!fill.labels)
         return null;
-    const map = (0, ctx_path_1.resolveCtxPath)(fill.labels, { envelope: asObject(row.envelope), metadata: asObject(row.metadata) });
-    const labels = isRecord(map) ? map : {};
+    const labels = rowMap(fill.labels, row);
     return (key, code) => {
         const printed = printedCode(code, scheme);
         const value = labels[key];

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

@@ -79,6 +79,8 @@ async function heldSubject(step, ctx, row) {
         } : {}),
         ...(claimant ? { claimedBy: claimant } : {}),
         ...(hold.show ? { show: hold.show } : {}),
+        ...(hold.release ? { release: hold.release } : {}),
+        ...(hold.whenAllIn ? { whenAllIn: (0, context_1.renderDone)(hold.whenAllIn, tpl) } : {}),
     };
 }
 /** The canonical code for the held row, as the station would scan it. */

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

@@ -0,0 +1,10 @@
+import type { ScanStep } from '../../types';
+import { type StepContext } from './context';
+/** True when the step's copy or Open reads the scanned code's own pending row. */
+export declare function readsLocated(step: ScanStep): boolean;
+/**
+ * The scanned code's own pending row, read once per request: the newest
+ * pending row whose scheme facet holds the scanned target, in any role the
+ * actor may read, other than the held subject. Sets null when there is none.
+ */
+export declare function loadLocated(ctx: StepContext): Promise<void>;

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

@@ -0,0 +1,74 @@
+"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.readsLocated = readsLocated;
+exports.loadLocated = loadLocated;
+const scanCodeService = __importStar(require("../../services/scan-code"));
+const escalationService = __importStar(require("../../services/escalation"));
+const role_1 = require("../../services/role");
+const helpers_1 = require("../escalations/helpers");
+const metadata_1 = require("../escalations/metadata");
+const context_1 = require("./context");
+/** True when the step's copy or Open reads the scanned code's own pending row. */
+function readsLocated(step) {
+    return step.open?.target === 'located'
+        || scanCodeService.mentionsLocatedToken(step.refuse)
+        || scanCodeService.mentionsLocatedToken(step.done);
+}
+/**
+ * The scanned code's own pending row, read once per request: the newest
+ * pending row whose scheme facet holds the scanned target, in any role the
+ * actor may read, other than the held subject. Sets null when there is none.
+ */
+async function loadLocated(ctx) {
+    if (ctx.located !== undefined)
+        return;
+    const scope = await (0, helpers_1.getEscalationReadScope)(ctx.auth.userId);
+    const roles = (0, metadata_1.restrictScopeRoles)(scope.allRoles, scope.global);
+    if (roles !== null && roles.length === 0) {
+        ctx.located = null;
+        return;
+    }
+    const found = await escalationService.searchByFacets({
+        roles: roles ?? undefined,
+        facets: { [ctx.scheme.target_facet]: (0, context_1.targetValue)(ctx) },
+        status: 'pending',
+        orderBy: [{ field: 'created_at', direction: 'desc' }],
+        limit: 2,
+    }, { total: false });
+    const row = found.escalations.find((r) => r.id !== ctx.subject?.row.id) ?? null;
+    ctx.located = row;
+    ctx.locatedTitle = row ? await (0, role_1.getRoleTitle)(row.role) : null;
+}

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

@@ -0,0 +1,9 @@
+import { type ScanExecuteResponse, type ScanStep } from '../../types';
+import type { LTApiResult } from '../../types/sdk';
+import type { StepContext } from './context';
+/**
+ * Attach the step's Open button to the answer: on the held subject for a
+ * hold, so it stays while the row is held, else on the response. A target
+ * with no row, or a list facet the row does not carry, offers no button.
+ */
+export declare function withOpen(result: LTApiResult<ScanExecuteResponse>, step: Pick<ScanStep, 'open'>, ctx: StepContext): Promise<LTApiResult<ScanExecuteResponse>>;