@hotmeshio/long-tail 0.22.2 → 0.22.3

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

@@ -1,15 +1,22 @@
 import { type EscalationLookupRef } from '../../types/escalation';
+import type { LTEscalationRecord } from '../../types';
 import type { LTApiResult, LTApiAuth } from '../../types/sdk';
 /** The refs riding the row's envelope under the reserved key, or []. */
 export declare function readLookupRefs(envelope: string | null | undefined): EscalationLookupRef[];
+/**
+ * When a current ref is read: now for a pending row, the moment it closed
+ * otherwise, so a closed row shows the edition its work was done against.
+ */
+export declare function lookupAsOf(escalation: Pick<LTEscalationRecord, 'status' | 'resolved_at' | 'updated_at'>): string | null;
 /**
  * Resolve an escalation's versioned knowledge lookups.
  *
  * The refs on `envelope.lookups` ARE the grant: any user who may read the
  * escalation may read exactly the pinned editions it names — nothing else in
  * the knowledge store. Snapshots are immutable, so responses are served from
- * an in-process cache after the first read; a ref whose snapshot does not
- * exist answers with `missing: true` rather than failing the batch.
+ * an in-process cache after the first read; a current ref reads the newest
+ * edition (as of the close, for a closed row). A ref with no edition answers
+ * with `missing: true` rather than failing the batch.
  *
  * @param input.id — escalation UUID
  * @param auth — authenticated user context (must hold the escalation's role)

package/build/api/escalations/lookups.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.readLookupRefs = readLookupRefs;
+exports.lookupAsOf = lookupAsOf;
 exports.getEscalationLookups = getEscalationLookups;
 const escalationService = __importStar(require("../../services/escalation"));
 const knowledge_1 = require("../../services/knowledge");
@@ -55,14 +56,25 @@ function readLookupRefs(envelope) {
         return [];
     }
 }
+/**
+ * When a current ref is read: now for a pending row, the moment it closed
+ * otherwise, so a closed row shows the edition its work was done against.
+ */
+function lookupAsOf(escalation) {
+    if (escalation.status === 'pending')
+        return null;
+    const closed = escalation.resolved_at ?? escalation.updated_at;
+    return closed ? new Date(closed).toISOString() : null;
+}
 /**
  * Resolve an escalation's versioned knowledge lookups.
  *
  * The refs on `envelope.lookups` ARE the grant: any user who may read the
  * escalation may read exactly the pinned editions it names — nothing else in
  * the knowledge store. Snapshots are immutable, so responses are served from
- * an in-process cache after the first read; a ref whose snapshot does not
- * exist answers with `missing: true` rather than failing the batch.
+ * an in-process cache after the first read; a current ref reads the newest
+ * edition (as of the close, for a closed row). A ref with no edition answers
+ * with `missing: true` rather than failing the batch.
  *
  * @param input.id — escalation UUID
  * @param auth — authenticated user context (must hold the escalation's role)
@@ -81,7 +93,7 @@ async function getEscalationLookups(input, auth) {
         if (refs.length === 0) {
             return { status: 200, data: { lookups: [] } };
         }
-        const lookups = await (0, knowledge_1.resolveLookupRefs)(refs);
+        const lookups = await (0, knowledge_1.resolveLookupRefs)(refs, lookupAsOf(escalation));
         return { status: 200, data: { lookups } };
     }
     catch (err) {

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

@@ -37,6 +37,8 @@ export declare function claimByMetadata(input: {
     metadata?: Record<string, any>;
     provisionIfAbsent?: ProvisionIfAbsent;
     restrictRoles?: string[];
+    /** Claims only this row, when it still matches every other condition. */
+    assertId?: string;
 }, auth: LTApiAuth): Promise<LTApiResult>;
 /**
  * Resolve an escalation by metadata key-value pair.

package/build/api/escalations/metadata.js

@@ -94,6 +94,9 @@ async function claimByMetadata(input, auth) {
         if (!input.key || !input.value) {
             return { status: 400, error: 'key and value are required' };
         }
+        if (input.assertId !== undefined && !(0, uuid_1.isUuid)(input.assertId)) {
+            return { status: 404, error: 'No pending escalation found for this metadata' };
+        }
         const resolved = await (0, helpers_1.resolveAssignee)(input.assignee, auth, input.provisionIfAbsent);
         if ('error' in resolved)
             return resolved.error;
@@ -105,6 +108,12 @@ async function claimByMetadata(input, auth) {
         // (expected queues) intersects with the scope inside the same SQL filter.
         const writeScope = await (0, helpers_1.getEscalationWriteScope)(auth.userId);
         const allowedRoles = restrictScopeRoles(writeScope.allRoles, writeScope.global, input.restrictRoles);
+        if (input.assertId !== undefined) {
+            const asserted = await escalationService.claimAssertedByMetadata(input.assertId, input.key, input.value, claimUserId, input.durationMinutes, input.metadata, allowedRoles);
+            if (!asserted)
+                return { status: 404, error: 'No pending escalation found for this metadata' };
+            return { status: 200, data: asserted };
+        }
         const result = await escalationService.claimByMetadata(input.key, input.value, claimUserId, input.durationMinutes, input.metadata, allowedRoles);
         if (!result) {
             // No rows matched. Check if candidates existed (role mismatch vs no match).

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

@@ -61,6 +61,8 @@ async function locateForStep(step, ctx, limit) {
         return escalationService.listEscalations({
             metadata: facets,
             status,
+            type: step.query?.types?.[0],
+            subtype: step.query?.subtypes?.[0],
             assigned_to: ctx.auth.userId,
             visibleRoles: roles ?? undefined,
             limit,
@@ -71,6 +73,8 @@ async function locateForStep(step, ctx, limit) {
         return null;
     return escalationService.searchByFacets({
         roles: roles ?? undefined,
+        types: step.query?.types,
+        subtypes: step.query?.subtypes,
         facets,
         status,
         available: availability === types_1.SCAN_AVAILABILITY.AVAILABLE

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

@@ -1,6 +1,6 @@
 import { type ScanExecuteResponse, type ScanStep } from '../../types';
 import type { LTApiResult } from '../../types/sdk';
-import type { StepContext } from './context';
+import { type StepContext } from './context';
 /**
  * Locate the target and present the step's choices. Choices whose identity
  * requirement is unsatisfied come back withheld — the screen renders the

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

@@ -1,10 +1,52 @@
 "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.presentStep = presentStep;
+const scanCodeService = __importStar(require("../../services/scan-code"));
 const types_1 = require("../../types");
 const identity_1 = require("./identity");
 const locate_1 = require("./locate");
 const verbs_1 = require("./verbs");
+const context_1 = require("./context");
+/** The step's facts rendered against the presented row; unreadable tokens render empty. */
+function renderFacts(step, ctx, row) {
+    if (!step.facts)
+        return undefined;
+    const tpl = { ...(0, context_1.templateContext)(ctx), item: row.metadata ?? {} };
+    return step.facts.map((fact) => ({ label: fact.label, value: scanCodeService.renderScanCopy(fact.value, tpl) }));
+}
 // ── The info-choice outcome — locate → present reality + labeled choices ───
 //
 // Some objects carry one code for their whole life: the next action cannot be
@@ -52,6 +94,7 @@ async function presentStep(step, ctx) {
             verb: step.verb,
             escalation,
             choices,
+            ...(step.facts ? { facts: renderFacts(step, ctx, escalation) } : {}),
             notPrimed: ctx.rule.notPrimed,
             ...(autoSelect ? { autoSelect: true } : {}),
         },

package/build/api/scan-codes/verb-accumulate.js

@@ -41,6 +41,7 @@ const context_1 = require("./context");
 const grant_1 = require("./grant");
 const locate_1 = require("./locate");
 const verbs_subject_1 = require("./verbs-subject");
+const verb_into_subject_1 = require("./verb-into-subject");
 /**
  * Adds the scanned item to an accumulator. Two modes, one atomic write:
  *
@@ -66,7 +67,7 @@ async function accumulateStep(step, ctx) {
     if (options?.from === 'subject')
         return (0, verbs_subject_1.accumulateFromSubject)(step, ctx);
     if (options?.into === 'subject')
-        return (0, verbs_subject_1.accumulateIntoSubject)(step, ctx);
+        return (0, verb_into_subject_1.accumulateIntoSubject)(step, ctx);
     let item;
     if (options?.containerFacet) {
         const located = await (0, locate_1.locateForStep)(step, ctx, 1);
@@ -113,6 +114,9 @@ async function accumulateStep(step, ctx) {
             payload: rendered.payload,
             metadata: rendered.metadata,
             restrictRoles: step.query?.roles,
+            ...(step.query?.types || step.query?.subtypes
+                ? { container: { types: step.query.types, subtypes: step.query.subtypes } }
+                : {}),
         };
     }
     const notPrimed = await (0, grant_1.spendGrant)(ctx);

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

@@ -96,8 +96,11 @@ async function fillStep(step, ctx) {
         const markdown = declared.length
             ? `All ${declared.length} of these are already checked off.`
             : scanCodeService.renderScanCopy(step.refuse?.markdown ?? STOCK_UNEXPECTED, tpl);
+        const expected = ctx.scheme.encoding === types_1.SCAN_ENCODINGS.GTIN
+            ? tpl.fill.pending.map((code) => scanCodeService.displayGtin(code))
+            : tpl.fill.pending;
         return (0, context_1.refused)(markdown, {
-            refusal: { markdown, expected: tpl.fill.pending },
+            refusal: { markdown, expected },
             progress: progress(batch, 0),
         });
     }

package/build/api/scan-codes/verb-into-subject.d.ts

@@ -0,0 +1,12 @@
+import { type ScanExecuteResponse, type ScanStep } from '../../types';
+import type { LTApiResult } from '../../types/sdk';
+import { type StepContext } from './context';
+type ScanResult = LTApiResult<ScanExecuteResponse>;
+/**
+ * The held subject's row collects the scanned code. With `accumulate.item`,
+ * the code's own pending row is located and written as the reciprocal in the
+ * same statement, so the item's record and the subject's entry land together
+ * or not at all.
+ */
+export declare function accumulateIntoSubject(step: ScanStep, ctx: StepContext): Promise<ScanResult | null>;
+export {};

package/build/api/scan-codes/verb-into-subject.js

@@ -0,0 +1,157 @@
+"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.accumulateIntoSubject = accumulateIntoSubject;
+const scanCodeService = __importStar(require("../../services/scan-code"));
+const escalationService = __importStar(require("../../services/escalation"));
+const accumulate_1 = require("../escalations/accumulate");
+const helpers_1 = require("../escalations/helpers");
+const metadata_1 = require("../escalations/metadata");
+const escalation_1 = require("../../types/escalation");
+const types_1 = require("../../types");
+const context_1 = require("./context");
+const grant_1 = require("./grant");
+const subject_1 = require("./subject");
+const verbs_subject_1 = require("./verbs-subject");
+const STOCK_MISSING = 'That one is not waiting here.';
+const ITEM_GONE = ['reciprocal-not-found', 'reciprocal-not-accumulator'];
+/**
+ * The scanned code's own pending row: an accumulator carrying the scheme's
+ * target facet = the scanned target, within the selector and the actor's
+ * read scope. The held subject's row is never a candidate.
+ */
+async function locateItem(step, ctx) {
+    const selector = step.params.accumulate.item;
+    const scope = await (0, helpers_1.getEscalationReadScope)(ctx.auth.userId);
+    const roles = (0, metadata_1.restrictScopeRoles)(scope.allRoles, scope.global, selector.roles);
+    if (roles !== null && roles.length === 0)
+        return {};
+    const found = await escalationService.searchByFacets({
+        roles: roles ?? undefined,
+        types: selector.types,
+        subtypes: selector.subtypes,
+        facets: { ...selector.facets, [ctx.scheme.target_facet]: ctx.parsed.target },
+        status: 'pending',
+        exists: [escalation_1.ESCALATION_ACCUMULATE_KEYS.COUNT],
+        limit: 3,
+    }, { total: false });
+    const rows = found.escalations.filter((row) => row.id !== ctx.subject?.row.id);
+    return rows.length > 1 ? { ambiguous: true } : { row: rows[0] };
+}
+/** The missing-item answer: the rule's copy when declared, else fall through. */
+function missing(step, ctx) {
+    if (!step.refuse?.missing)
+        return null;
+    const copy = scanCodeService.renderScanCopy(step.refuse.missing, (0, verbs_subject_1.bags)(ctx, ctx.subject?.row));
+    return (0, context_1.refused)(copy, { clearSubject: false });
+}
+/** Progress of a bounded accumulator after an add; unbounded rows report none. */
+function progressOf(data) {
+    if (data.remaining === null || data.remaining === undefined)
+        return undefined;
+    return { filled: data.count, total: data.count + data.remaining, remaining: data.remaining };
+}
+/**
+ * The held subject's row collects the scanned code. With `accumulate.item`,
+ * the code's own pending row is located and written as the reciprocal in the
+ * same statement, so the item's record and the subject's entry land together
+ * or not at all.
+ */
+async function accumulateIntoSubject(step, ctx) {
+    const subject = ctx.subject;
+    const claimed = await (0, verbs_subject_1.claimGuard)(step, ctx, subject);
+    if (claimed)
+        return claimed;
+    // 1. Locate the scanned item's own row when the step names one
+    let item;
+    const wantsItem = !!step.params?.accumulate?.item;
+    if (wantsItem) {
+        const located = await locateItem(step, ctx);
+        if ('ambiguous' in located) {
+            return (0, context_1.conflict)(`more than one pending row carries ${ctx.scheme.target_facet} = ${ctx.parsed.target}`);
+        }
+        item = located.row;
+    }
+    // 2. Check the pairing before anything is written
+    if (wantsItem && !item)
+        return missing(step, ctx);
+    const mismatch = (0, verbs_subject_1.matchGuard)(step, ctx, subject.row, item);
+    if (mismatch)
+        return mismatch;
+    if (item && step.subject?.claimedByOther !== 'allow') {
+        const other = await (0, subject_1.claimedByOther)(item, ctx.auth.userId);
+        if (other)
+            return (0, context_1.refused)(`Claimed by **${other.displayName}**.`, { clearSubject: false });
+    }
+    // 3. Spend the badge, then write both rows in one statement
+    const values = (0, verbs_subject_1.rendered)(step, ctx, '{scan.target}', item);
+    if (!values)
+        return null;
+    const notPrimed = (await (0, grant_1.identityGate)(step, ctx)) ?? (await (0, grant_1.spendGrant)(ctx));
+    if (notPrimed)
+        return notPrimed;
+    const result = await (0, accumulate_1.accumulateItem)({
+        id: subject.row.id,
+        itemKey: values.itemKey,
+        payload: values.payload,
+        metadata: values.metadata,
+        ...(item ? { reciprocal: { id: item.id } } : {}),
+    }, ctx.auth);
+    // 4. Report
+    if (result.status !== 200) {
+        const outcome = result.data?.outcome;
+        if (outcome === 'duplicate-item')
+            return (0, verbs_subject_1.already)(step, subject.row, true);
+        if (item && outcome && ITEM_GONE.includes(outcome))
+            return missing(step, ctx) ?? (0, context_1.refused)(STOCK_MISSING, { clearSubject: false });
+        return (0, verbs_subject_1.failedAdd)(step, ctx, result, subject.row, !!item);
+    }
+    const data = result.data;
+    const progress = progressOf(data);
+    return (0, context_1.withDone)({
+        status: 200,
+        data: {
+            outcome: types_1.SCAN_OUTCOMES.EXECUTED,
+            verb: step.verb,
+            escalation: { id: subject.row.id, ...result.data },
+            clearSubject: data.outcome === 'completed',
+            ...(progress ? { progress } : {}),
+        },
+    }, step, (0, verbs_subject_1.bags)(ctx, afterAdd(subject.row, values.metadata, data.count), item));
+}
+/** The subject's row as the add left it, for `{container.…}` copy, without a re-read. */
+function afterAdd(row, patch, count) {
+    return { ...row, metadata: { ...(row.metadata ?? {}), ...patch, [escalation_1.ESCALATION_ACCUMULATE_KEYS.COUNT]: count } };
+}

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

@@ -1,14 +1,33 @@
+import * as scanCodeService from '../../services/scan-code';
 import { type LTEscalationRecord, type ScanExecuteResponse, type ScanStep } from '../../types';
 import type { LTApiResult } from '../../types/sdk';
-import { type StepContext } from './context';
+import { type HeldSubject, type StepContext } from './context';
 type ScanResult = LTApiResult<ScanExecuteResponse>;
+/** The step's template bags with the subject, the container, and the scanned item's row once located. */
+export declare function bags(ctx: StepContext, container?: LTEscalationRecord, item?: LTEscalationRecord): scanCodeService.ScanTemplateContext;
+/** Refuse the act when someone else holds a live claim on the subject. */
+export declare function claimGuard(step: ScanStep, ctx: StepContext, subject: HeldSubject): Promise<ScanResult | null>;
 /**
  * The pre-write guard. Returns the refusal when the pairing is wrong, null
  * when it holds (or the step declares no match).
  */
-export declare function matchGuard(step: ScanStep, ctx: StepContext, container?: LTEscalationRecord): ScanResult | null;
+export declare function matchGuard(step: ScanStep, ctx: StepContext, container?: LTEscalationRecord, item?: LTEscalationRecord): ScanResult | null;
+/**
+ * Map a failed add onto what the bench says. 404 falls through. `keepSubject`
+ * leaves the hold in place when the reciprocal was already placed (the
+ * subject is the container the actor is still filling).
+ */
+export declare function failedAdd(step: ScanStep, ctx: StepContext, result: LTApiResult, container?: LTEscalationRecord, keepSubject?: boolean): ScanResult | null;
+/** The step's itemKey, payload and metadata, or null when a template token has nothing to read. */
+export declare function rendered(step: ScanStep, ctx: StepContext, itemKeyDefault?: string, item?: LTEscalationRecord): {
+    itemKey: string;
+    payload: Record<string, any> | undefined;
+    metadata: {
+        [x: string]: any;
+    };
+} | null;
 /** The subject joins the scanned container; the subject's row is the reciprocal. */
 export declare function accumulateFromSubject(step: ScanStep, ctx: StepContext): Promise<ScanResult | null>;
-/** The subject's own row collects the scanned code. */
-export declare function accumulateIntoSubject(step: ScanStep, ctx: StepContext): Promise<ScanResult | null>;
+/** The item is already where the scan says: harmless, nothing written. */
+export declare function already(step: ScanStep, row: LTEscalationRecord, keepSubject?: boolean): ScanResult;
 export {};

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

@@ -33,9 +33,13 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.bags = bags;
+exports.claimGuard = claimGuard;
 exports.matchGuard = matchGuard;
+exports.failedAdd = failedAdd;
+exports.rendered = rendered;
 exports.accumulateFromSubject = accumulateFromSubject;
-exports.accumulateIntoSubject = accumulateIntoSubject;
+exports.already = already;
 const scanCodeService = __importStar(require("../../services/scan-code"));
 const escalationService = __importStar(require("../../services/escalation"));
 const accumulate_1 = require("../escalations/accumulate");
@@ -52,13 +56,18 @@ const subject_1 = require("./subject");
 // the pairing first (match), refusing with nothing written when it is wrong,
 // then writes by id in one atomic statement: the subject joins the scanned
 // container with its own row as the reciprocal (from: 'subject'), or the
-// subject's row collects the scanned code (into: 'subject').
+// subject's row collects the scanned code (into: 'subject', in
+// verb-into-subject.ts).
 const STOCK_REFUSAL = 'That is not where this one goes.';
 const STOCK_CONFLICT = 'That container just closed. Scan it again, or the next one.';
 const STOCK_PLACED = 'This one is already placed.';
-/** The step's template bags with the subject (and the container, once located). */
-function bags(ctx, container) {
-    return { ...(0, context_1.templateContext)(ctx), ...(container ? { container: container.metadata ?? {} } : {}) };
+/** The step's template bags with the subject, the container, and the scanned item's row once located. */
+function bags(ctx, container, item) {
+    return {
+        ...(0, context_1.templateContext)(ctx),
+        ...(container ? { container: container.metadata ?? {} } : {}),
+        ...(item ? { item: item.metadata ?? {} } : {}),
+    };
 }
 /** Refuse the act when someone else holds a live claim on the subject. */
 async function claimGuard(step, ctx, subject) {
@@ -82,10 +91,10 @@ async function locateContainer(step, ctx) {
         status: 'pending',
         exists: [escalation_1.ESCALATION_ACCUMULATE_KEYS.COUNT],
         limit: 2,
-    });
+    }, { total: false });
     return found.escalations.filter((row) => row.id !== ctx.subject?.row.id);
 }
-const WHOLE_BAG_TOKEN = /^\{(subject|container)\.([a-zA-Z0-9_]+)\}$/;
+const WHOLE_BAG_TOKEN = /^\{(subject|container|item)\.([a-zA-Z0-9_]+)\}$/;
 /**
  * One match.target template as the values it allows. A template that is a
  * single bag token naming a list facet (`{subject.offeredContainers}`) allows every
@@ -110,11 +119,11 @@ function expandTarget(template, tpl) {
  * The pre-write guard. Returns the refusal when the pairing is wrong, null
  * when it holds (or the step declares no match).
  */
-function matchGuard(step, ctx, container) {
+function matchGuard(step, ctx, container, item) {
     const match = step.match;
     if (!match)
         return null;
-    const tpl = bags(ctx, container);
+    const tpl = bags(ctx, container, item);
     const expected = (match.target ?? []).flatMap((t) => expandTarget(t, tpl));
     const targetOk = match.target === undefined || expected.includes(ctx.parsed.target);
     const subjectMeta = (ctx.subject?.row.metadata ?? {});
@@ -126,15 +135,20 @@ function matchGuard(step, ctx, container) {
     const markdown = scanCodeService.renderScanCopy(step.refuse?.markdown ?? STOCK_REFUSAL, tpl);
     return (0, context_1.refused)(markdown, { refusal: { markdown, ...(expected.length ? { expected } : {}) } });
 }
-/** Map a failed add onto what the bench says. 404 falls through. */
-function failedAdd(step, ctx, result, container) {
+const PLACED_OUTCOMES = ['reciprocal-terminal', 'reciprocal-full', 'reciprocal-duplicate'];
+/**
+ * Map a failed add onto what the bench says. 404 falls through. `keepSubject`
+ * leaves the hold in place when the reciprocal was already placed (the
+ * subject is the container the actor is still filling).
+ */
+function failedAdd(step, ctx, result, container, keepSubject = false) {
     const outcome = result.data?.outcome;
     if (result.status === 404)
         return null;
     if (result.status === 403)
         return (0, context_1.forbidden)(result.error);
-    if (outcome === 'reciprocal-terminal' || outcome === 'reciprocal-full' || outcome === 'reciprocal-duplicate') {
-        return (0, context_1.refused)(STOCK_PLACED, { clearSubject: true });
+    if (outcome && PLACED_OUTCOMES.includes(outcome)) {
+        return (0, context_1.refused)(STOCK_PLACED, { clearSubject: !keepSubject });
     }
     if (outcome === 'claimed-by-other' || outcome === 'claim-expired')
         return (0, context_1.conflict)(result.error);
@@ -145,8 +159,9 @@ function failedAdd(step, ctx, result, container) {
     }
     return (0, context_1.refused)(result.error ?? STOCK_REFUSAL);
 }
-function rendered(step, ctx, itemKeyDefault) {
-    const tpl = (0, context_1.templateContext)(ctx);
+/** The step's itemKey, payload and metadata, or null when a template token has nothing to read. */
+function rendered(step, ctx, itemKeyDefault, item) {
+    const tpl = bags(ctx, undefined, item);
     try {
         return {
             itemKey: scanCodeService.interpolateScanTemplate(step.params?.itemKey ?? itemKeyDefault ?? '', tpl),
@@ -217,46 +232,8 @@ async function accumulateFromSubject(step, ctx) {
         },
     }, step, bags(ctx, container));
 }
-/** The subject's own row collects the scanned code. */
-async function accumulateIntoSubject(step, ctx) {
-    const subject = ctx.subject;
-    const claimed = await claimGuard(step, ctx, subject);
-    if (claimed)
-        return claimed;
-    const mismatch = matchGuard(step, ctx);
-    if (mismatch)
-        return mismatch;
-    const values = rendered(step, ctx, '{scan.target}');
-    if (!values)
-        return null;
-    const notPrimed = (await (0, grant_1.identityGate)(step, ctx)) ?? (await (0, grant_1.spendGrant)(ctx));
-    if (notPrimed)
-        return notPrimed;
-    const result = await (0, accumulate_1.accumulateItem)({
-        id: subject.row.id,
-        itemKey: values.itemKey,
-        payload: values.payload,
-        metadata: values.metadata,
-    }, ctx.auth);
-    if (result.status !== 200) {
-        if (result.data?.outcome === 'duplicate-item') {
-            return already(step, subject.row);
-        }
-        return failedAdd(step, ctx, result);
-    }
-    const data = result.data;
-    return (0, context_1.withDone)({
-        status: 200,
-        data: {
-            outcome: types_1.SCAN_OUTCOMES.EXECUTED,
-            verb: step.verb,
-            escalation: { id: subject.row.id, ...result.data },
-            clearSubject: data.outcome === 'completed',
-        },
-    }, step, bags(ctx));
-}
 /** The item is already where the scan says: harmless, nothing written. */
-function already(step, row) {
+function already(step, row, keepSubject = false) {
     return {
         status: 200,
         data: {
@@ -264,7 +241,7 @@ function already(step, row) {
             verb: step.verb,
             escalation: { id: row.id },
             already: true,
-            clearSubject: true,
+            clearSubject: !keepSubject,
         },
     };
 }

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

@@ -1,21 +1,23 @@
 import { type ScanExecuteResponse, type ScanStep } from '../../types';
 import type { LTApiResult } from '../../types/sdk';
 import { type StepContext } from './context';
-export declare function claimStep(step: ScanStep, ctx: StepContext): Promise<LTApiResult<ScanExecuteResponse> | null>;
+/** Claims the scanned row; a presented choice passes the row it showed. */
+export declare function claimStep(step: ScanStep, ctx: StepContext, presentedId?: string): Promise<LTApiResult<ScanExecuteResponse> | null>;
 /**
  * Resolves the row the step's query names: the scanned target, the extra
  * facets, and the claim state, all inside the atomic statement. A presented
  * choice passes the row it showed, so the resolve lands on that row or misses.
  */
 export declare function resolveStep(step: ScanStep, ctx: StepContext, presentedId?: string): Promise<LTApiResult<ScanExecuteResponse> | null>;
-export declare function escalateStep(step: ScanStep, ctx: StepContext): Promise<LTApiResult<ScanExecuteResponse> | null>;
-export declare function releaseStep(step: ScanStep, ctx: StepContext): Promise<LTApiResult<ScanExecuteResponse> | null>;
+export declare function escalateStep(step: ScanStep, ctx: StepContext, presentedId?: string): Promise<LTApiResult<ScanExecuteResponse> | null>;
+export declare function releaseStep(step: ScanStep, ctx: StepContext, presentedId?: string): Promise<LTApiResult<ScanExecuteResponse> | null>;
 /**
- * Dispatch one CHOICE verb against an already-presented row. Unlike the step
- * walk (where a miss falls through to the next step), the screen showed this
- * exact row — so a miss answers with the truth: FORBIDDEN when the actor
- * holds no write scope here, CONFLICT when a concurrent actor won the race.
+ * Dispatch one CHOICE verb against an already-presented row. Every verb that
+ * writes the row writes that row by id, so a code shared by several rows
+ * never moves the write elsewhere. Unlike the step walk (where a miss falls
+ * through to the next step), a miss answers with the truth: FORBIDDEN when
+ * the actor holds no write scope here, CONFLICT when a concurrent actor won.
  */
 export declare function dispatchChoiceVerb(step: ScanStep, ctx: StepContext, row: Record<string, any>): Promise<LTApiResult<ScanExecuteResponse>>;
-export declare function cancelStep(step: ScanStep, ctx: StepContext): Promise<LTApiResult<ScanExecuteResponse> | null>;
+export declare function cancelStep(step: ScanStep, ctx: StepContext, presentedId?: string): Promise<LTApiResult<ScanExecuteResponse> | null>;
 export { accumulateStep } from './verb-accumulate';