@hotmeshio/long-tail 0.22.1 → 0.22.3

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

@@ -37,10 +37,15 @@ exports.executeScanCode = executeScanCode;
 const scanCodeService = __importStar(require("../../services/scan-code"));
 const identity_1 = require("./identity");
 const context_1 = require("./context");
+const grant_1 = require("./grant");
+const hold_1 = require("./hold");
 const locate_1 = require("./locate");
 const present_1 = require("./present");
+const subject_1 = require("./subject");
+const verb_fill_1 = require("./verb-fill");
 const verbs_1 = require("./verbs");
 const types_1 = require("../../types");
+const SUBJECT_STALE_MESSAGE = 'That one moved on. Scan it again.';
 /**
  * Execute a raw scan code: parse → load the rule → walk its steps in order.
  * The first step whose condition matches performs its verb and answers; a
@@ -77,45 +82,57 @@ async function executeScanCode(input, auth) {
         }
         // 2a. Identity schemes are the badge layer — they mint, never walk steps.
         if (scheme.kind === types_1.SCAN_SCHEME_KINDS.IDENTITY) {
-            return (0, identity_1.executeIdentityScan)(parsed, scheme, rule, input.previousActingToken);
+            return (0, identity_1.executeIdentityScan)(parsed, scheme, rule, input.previousActingToken, {
+                userId: auth.userId,
+                stationRole: typeof input.stationRole === 'string' ? input.stationRole : undefined,
+            });
         }
-        // 2b. A supplied acting grant is exchanged once, up front — the acting
-        // user's read scope must govern the locate as much as the mutation. A
-        // dead grant terminates loudly; silently degrading to the station
-        // identity would misattribute whatever follows.
-        let effectiveAuth = auth;
-        let acting = false;
+        // 2b. A supplied acting grant is read up front (not spent): the acting
+        // user's read scope governs the locate as much as the mutation. A dead
+        // grant terminates loudly; silently degrading to the station identity
+        // would misattribute whatever follows.
+        const ctx = {
+            scheme, rule, parsed, rawCode: input.code.trim(), scannedAt: new Date().toISOString(),
+            auth, stationAuth: auth, acting: false,
+        };
         if (input.actingToken) {
-            const resolved = await (0, identity_1.resolveActingAuth)(input.actingToken);
-            if (!resolved.ok) {
-                return {
-                    status: 200,
-                    data: {
-                        outcome: types_1.SCAN_OUTCOMES.NOT_PRIMED,
-                        parsed,
-                        notPrimed: rule.notPrimed,
-                        error: resolved.error,
-                    },
-                };
+            const peeked = await (0, grant_1.peekGrant)(input.actingToken);
+            if (!peeked.ok) {
+                return { status: 200, data: { ...(0, context_1.notPrimed)(ctx, peeked.error).data, parsed } };
             }
-            effectiveAuth = resolved.auth;
-            acting = true;
+            ctx.auth = peeked.auth;
+            ctx.acting = true;
+            ctx.grant = peeked.grant;
         }
+        // 2c. The held subject, re-derived from the station's pointer
+        const held = await (0, subject_1.resolveSubject)(input.subject, schemes, auth);
+        if (held?.ok)
+            ctx.subject = held.subject;
+        else if (held)
+            ctx.subjectStale = true;
         // 3. Walk the steps — first condition match wins
-        const ctx = {
-            scheme, rule, parsed, scannedAt: new Date().toISOString(),
-            auth: effectiveAuth, stationAuth: auth, acting,
-        };
-        for (let i = 0; i < rule.steps.length; i++) {
-            const result = await executeStep(rule.steps[i], i, ctx);
-            if (result)
-                return decorate(result, ctx, i);
+        let result = null;
+        for (let i = 0; i < rule.steps.length && !result; i++) {
+            const stepResult = await executeStep(rule.steps[i], ctx);
+            if (stepResult)
+                result = decorate((0, context_1.withDone)(stepResult, rule.steps[i], (0, context_1.templateContext)(ctx)), ctx, i);
         }
-        // 4. Nothing matched — the fallback screen is the answer
-        return {
-            status: 200,
-            data: decorateData({ outcome: types_1.SCAN_OUTCOMES.NO_MATCH_FALLBACK, fallback: rule.fallback }, ctx),
-        };
+        // 4. Nothing matched: a stale subject, or the fallback screen
+        if (!result) {
+            result = ctx.subjectStale
+                ? { status: 200, data: decorateData({ outcome: types_1.SCAN_OUTCOMES.SUBJECT_STALE, clearSubject: true, error: SUBJECT_STALE_MESSAGE }, ctx) }
+                : { status: 200, data: decorateData({ outcome: types_1.SCAN_OUTCOMES.NO_MATCH_FALLBACK, fallback: rule.fallback }, ctx) };
+        }
+        // 5. Settle the badge: refund a spend whose act did not land
+        const acting = await (0, grant_1.settleGrant)(ctx, result);
+        if (result.data && typeof result.data === 'object' && 'outcome' in result.data) {
+            result.data = {
+                ...result.data,
+                ...(acting ? { acting } : {}),
+                ...(ctx.subjectStale ? { clearSubject: true } : {}),
+            };
+        }
+        return result;
     }
     catch (err) {
         return { status: 500, error: err.message };
@@ -139,17 +156,34 @@ function decorateData(data, ctx) {
         },
     };
 }
+/**
+ * A subject step runs only while a subject from one of its schemes is held,
+ * and, when it declares facets, only while the held row carries them.
+ */
+function subjectGateOpen(step, ctx) {
+    if (!step.subject)
+        return true;
+    if (!ctx.subject || !step.subject.schemes.includes(ctx.subject.scheme.version))
+        return false;
+    const meta = (ctx.subject.row.metadata ?? {});
+    return Object.entries(step.subject.facets ?? {}).every(([key, value]) => meta[key] === value);
+}
 /**
  * Execute one step. Returns null when the step's condition matched nothing
  * (fall through) and an LTApiResult for every terminal outcome.
  */
-async function executeStep(step, index, ctx) {
+async function executeStep(step, ctx) {
+    if (!subjectGateOpen(step, ctx))
+        return null;
     // 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,
     // so the outcome is the rule's "scan your badge" screen, never a silent or
     // misattributed action.
-    if (step.requireActingIdentity && !(await (0, identity_1.actingIdentitySatisfied)(step, ctx))) {
+    // A subject step checks the pairing first and asks for the badge only when
+    // the pairing is right (see identityGate), so a wrong container is named
+    // at once.
+    if (step.requireActingIdentity && !step.subject && !(await (0, identity_1.actingIdentitySatisfied)(step, ctx))) {
         return (0, context_1.notPrimed)(ctx);
     }
     // Confirm steps and read verbs only locate — mutation happens after the
@@ -160,6 +194,8 @@ async function executeStep(step, index, ctx) {
     switch (step.verb) {
         case types_1.SCAN_VERBS.PRESENT:
             return (0, present_1.presentStep)(step, ctx);
+        case types_1.SCAN_VERBS.HOLD:
+            return (0, hold_1.holdStep)(step, ctx);
         case types_1.SCAN_VERBS.CLAIM:
         case types_1.SCAN_VERBS.CLAIM_SHOW_DETAIL:
             return (0, verbs_1.claimStep)(step, ctx);
@@ -173,6 +209,8 @@ async function executeStep(step, index, ctx) {
             return (0, verbs_1.cancelStep)(step, ctx);
         case types_1.SCAN_VERBS.ACCUMULATE:
             return (0, verbs_1.accumulateStep)(step, ctx);
+        case types_1.SCAN_VERBS.FILL:
+            return (0, verb_fill_1.fillStep)(step, ctx);
         default:
             throw new Error(`unknown scan verb "${step.verb}"`);
     }

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

@@ -0,0 +1,27 @@
+import { type ScanExecuteResponse, type ScanStep } from '../../types';
+import type { LTApiAuth, LTApiResult } from '../../types/sdk';
+import { type GrantLedger, type StepContext } from './context';
+export type PeekResult = {
+    ok: true;
+    auth: LTApiAuth;
+    grant: GrantLedger;
+} | {
+    ok: false;
+    error: string;
+};
+/** Read the grant without spending it. */
+export declare function peekGrant(token: string): Promise<PeekResult>;
+/**
+ * Spend the request's grant before a write. Returns null when the act may
+ * proceed (spent now, spent earlier in this request, or no grant rides it),
+ * and the not-primed result when the grant cannot cover this act. `ref` is
+ * the held subject the act lands on.
+ */
+export declare function spendGrant(ctx: StepContext, ref?: string | null): Promise<LTApiResult<ScanExecuteResponse> | null>;
+/** The step's identity requirement, checked at the moment it is about to act. */
+export declare function identityGate(step: ScanStep, ctx: StepContext): Promise<LTApiResult<ScanExecuteResponse> | null>;
+/**
+ * Close the request's books on the grant: refund a spend whose act did not
+ * land, and report the grant's state for the client to keep or retire.
+ */
+export declare function settleGrant(ctx: StepContext, result: LTApiResult<ScanExecuteResponse> | null): Promise<ScanExecuteResponse['acting'] | undefined>;

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

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.peekGrant = peekGrant;
+exports.spendGrant = spendGrant;
+exports.identityGate = identityGate;
+exports.settleGrant = settleGrant;
+const acting_identity_1 = require("../../services/iam/acting-identity");
+const types_1 = require("../../types");
+const context_1 = require("./context");
+const identity_1 = require("./identity");
+/** Read the grant without spending it. */
+async function peekGrant(token) {
+    const peeked = await (0, acting_identity_1.peekActingAuth)(token);
+    if (!peeked.ok)
+        return peeked;
+    return {
+        ok: true,
+        auth: peeked.auth,
+        grant: { token, peeked: { remaining: peeked.grant.remaining, bound: peeked.grant.bound }, spent: null },
+    };
+}
+/**
+ * Spend the request's grant before a write. Returns null when the act may
+ * proceed (spent now, spent earlier in this request, or no grant rides it),
+ * and the not-primed result when the grant cannot cover this act. `ref` is
+ * the held subject the act lands on.
+ */
+async function spendGrant(ctx, ref = ctx.subject?.row.id ?? null) {
+    const grant = ctx.grant;
+    if (!grant || grant.spent)
+        return null;
+    const consumed = await (0, acting_identity_1.consumeActingGrant)(grant.token, ref);
+    if (!consumed.ok)
+        return (0, context_1.notPrimed)(ctx, consumed.error);
+    grant.spent = { remaining: consumed.grant.remaining, bound: consumed.grant.bound };
+    return null;
+}
+/** The step's identity requirement, checked at the moment it is about to act. */
+async function identityGate(step, ctx) {
+    if (!step.requireActingIdentity || (await (0, identity_1.actingIdentitySatisfied)(step, ctx)))
+        return null;
+    return (0, context_1.notPrimed)(ctx);
+}
+/** True when the result is a write that landed. */
+function landed(result) {
+    const data = result?.data;
+    return !!data && data.outcome === types_1.SCAN_OUTCOMES.EXECUTED
+        && !!data.verb && types_1.SCAN_MUTATING_VERBS.includes(data.verb) && !data.already;
+}
+/**
+ * Close the request's books on the grant: refund a spend whose act did not
+ * land, and report the grant's state for the client to keep or retire.
+ */
+async function settleGrant(ctx, result) {
+    const grant = ctx.grant;
+    if (!grant)
+        return undefined;
+    if (grant.spent && !landed(result)) {
+        // Spending a bound grant cost nothing; spending an unbound one counted
+        // a use and may have bound it, so both come back.
+        if (!grant.peeked.bound)
+            await (0, acting_identity_1.refundActingGrant)(grant.token, grant.spent.bound);
+        grant.spent = null;
+    }
+    const state = grant.spent ?? grant.peeked;
+    return { consumed: !!grant.spent, remaining: state.remaining, bound: state.bound };
+}

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

@@ -0,0 +1,10 @@
+import { type LTEscalationRecord, type ScanExecuteResponse, type ScanStep } from '../../types';
+import type { LTApiResult } from '../../types/sdk';
+import { type StepContext } from './context';
+/**
+ * HOLD: locate the row and hand the station a subject to hold. The next
+ * scans (the badge, then the container) act on it. Writes nothing and spends
+ * no badge use. A live claim by someone else is reported, not refused: the
+ * bench says whose it is, and the act decides.
+ */
+export declare function holdStep(step: ScanStep, ctx: StepContext, located?: LTEscalationRecord): Promise<LTApiResult<ScanExecuteResponse> | null>;

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

@@ -0,0 +1,98 @@
+"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.holdStep = holdStep;
+const scanCodeService = __importStar(require("../../services/scan-code"));
+const types_1 = require("../../types");
+const context_1 = require("./context");
+const locate_1 = require("./locate");
+const subject_1 = require("./subject");
+/**
+ * HOLD: locate the row and hand the station a subject to hold. The next
+ * scans (the badge, then the container) act on it. Writes nothing and spends
+ * no badge use. A live claim by someone else is reported, not refused: the
+ * bench says whose it is, and the act decides.
+ */
+async function holdStep(step, ctx, located) {
+    const row = located ?? (await (0, locate_1.locateForStep)(step, ctx, 1))?.escalations[0];
+    if (!row)
+        return null;
+    return {
+        status: 200,
+        data: {
+            outcome: types_1.SCAN_OUTCOMES.HELD,
+            verb: step.verb,
+            escalation: row,
+            subject: await heldSubject(step, ctx, row),
+        },
+    };
+}
+async function heldSubject(step, ctx, row) {
+    const hold = step.params?.hold ?? {};
+    const tpl = { ...(0, context_1.templateContext)(ctx), item: row.metadata ?? {} };
+    const ttl = hold.ttlSeconds ?? types_1.SCAN_HOLD_TTL_DEFAULT_SECONDS;
+    const claimant = await (0, subject_1.claimedByOther)(row, ctx.acting ? ctx.auth.userId : null);
+    return {
+        code: ctx.rawCode ?? holdCode(ctx),
+        escalationId: row.id,
+        label: scanCodeService.renderScanCopy(hold.label ?? types_1.SCAN_TEMPLATE_TOKENS.TARGET, tpl),
+        ...optionalCopy('headline', hold.headline, tpl),
+        ...optionalCopy('subline', hold.subline, tpl),
+        expiresAt: new Date(Date.now() + ttl * 1000).toISOString(),
+        ...(hold.expect ? {
+            expect: {
+                schemes: hold.expect.schemes,
+                ...(hold.expect.prompt ? { prompt: scanCodeService.renderScanCopy(hold.expect.prompt, tpl) } : {}),
+            },
+        } : {}),
+        ...(claimant ? { claimedBy: claimant } : {}),
+    };
+}
+/** The canonical code for the held row, as the station would scan it. */
+function holdCode(ctx) {
+    const { scheme, parsed } = ctx;
+    if (scheme.encoding === 'delimited') {
+        const d = scheme.delimiter;
+        return `${parsed.version}${d}${parsed.category}${d}${parsed.target}`;
+    }
+    return `${parsed.version}${parsed.category}${parsed.target}`;
+}
+/** A rendered line, or nothing when the template is absent or renders empty. */
+function optionalCopy(key, template, tpl) {
+    if (!template)
+        return {};
+    const text = scanCodeService.renderScanCopy(template, tpl).trim();
+    return text ? { [key]: text } : {};
+}

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

@@ -1,13 +1,16 @@
 import { type ParsedScanCode, type ScanExecuteResponse, type ScanRule, type ScanScheme, type ScanStep } from '../../types';
 import type { LTApiResult } from '../../types/sdk';
 import type { StepContext } from './context';
-export { resolveActingAuth, type ActingAuthResult } from '../../services/iam/acting-identity';
+export { resolveActingAuth, peekActingAuth, type ActingAuthResult } from '../../services/iam/acting-identity';
 /**
  * Resolve an identity scan: badge → user → minted acting grant.
  * Identity schemes never walk steps; the rule's fallback is the
  * unknown-badge screen.
  */
-export declare function executeIdentityScan(parsed: ParsedScanCode, scheme: ScanScheme, rule: ScanRule, previousActingToken?: string): Promise<LTApiResult<ScanExecuteResponse>>;
+export declare function executeIdentityScan(parsed: ParsedScanCode, scheme: ScanScheme, rule: ScanRule, previousActingToken?: string, station?: {
+    userId: string;
+    stationRole?: string;
+}): Promise<LTApiResult<ScanExecuteResponse>>;
 /**
  * The identity pre-condition's satisfaction test. A primed grant always
  * satisfies; without one, the authenticated user satisfies only when their

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

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveActingAuth = void 0;
+exports.peekActingAuth = exports.resolveActingAuth = void 0;
 exports.executeIdentityScan = executeIdentityScan;
 exports.actingIdentitySatisfied = actingIdentitySatisfied;
 const userService = __importStar(require("../../services/user"));
@@ -41,8 +41,10 @@ const ephemeral_1 = require("../../services/iam/ephemeral");
 const metadata_1 = require("../escalations/metadata");
 const helpers_1 = require("../escalations/helpers");
 const types_1 = require("../../types");
+const badge_policy_1 = require("./badge-policy");
 var acting_identity_1 = require("../../services/iam/acting-identity");
 Object.defineProperty(exports, "resolveActingAuth", { enumerable: true, get: function () { return acting_identity_1.resolveActingAuth; } });
+Object.defineProperty(exports, "peekActingAuth", { enumerable: true, get: function () { return acting_identity_1.peekActingAuth; } });
 // ── Acting identity — the badge layer over the scan surface ────────────────
 //
 // A shared station device signs in as an ordinary read-capable account; the
@@ -58,8 +60,18 @@ Object.defineProperty(exports, "resolveActingAuth", { enumerable: true, get: fun
  * Identity schemes never walk steps; the rule's fallback is the
  * unknown-badge screen.
  */
-async function executeIdentityScan(parsed, scheme, rule, previousActingToken) {
-    const user = await userService.getUserByMetadataValue(scheme.target_facet, parsed.target);
+async function executeIdentityScan(parsed, scheme, rule, previousActingToken, station) {
+    // Two users bound to one badge is a configuration fault: refuse the badge
+    // and name the fault, never pick one of them.
+    let user;
+    let unknownReason = 'badge not recognized';
+    try {
+        user = await userService.getUserByMetadataValue(scheme.target_facet, parsed.target);
+    }
+    catch (err) {
+        user = null;
+        unknownReason = `badge is bound to more than one person: ${err.message}`;
+    }
     if (!user) {
         return {
             status: 200,
@@ -68,7 +80,7 @@ async function executeIdentityScan(parsed, scheme, rule, previousActingToken) {
                 parsed,
                 rule: { schemeVersion: rule.scheme_version, category: rule.category, name: rule.name },
                 fallback: rule.fallback,
-                error: 'badge not recognized',
+                error: unknownReason,
             },
         };
     }
@@ -79,12 +91,17 @@ async function executeIdentityScan(parsed, scheme, rule, previousActingToken) {
             await (0, ephemeral_1.revokeEphemeral)(prev.uuid).catch(() => { });
         }
     }
+    // The station decides the policy: its role's badge_grant, else the scheme's.
+    const policy = station
+        ? await (0, badge_policy_1.stationGrantPolicy)(scheme, station.userId, station.stationRole)
+        : { ttlSeconds: scheme.grant_ttl_seconds ?? 0, maxUses: scheme.grant_max_uses ?? 0, scope: scheme.grant_scope ?? types_1.SCAN_GRANT_SCOPES.ACTION };
     const uuid = await (0, ephemeral_1.storeEphemeral)(user.id, {
-        ttlSeconds: scheme.grant_ttl_seconds ?? undefined,
-        maxUses: scheme.grant_max_uses,
+        ttlSeconds: policy.ttlSeconds || undefined,
+        maxUses: policy.maxUses,
         label: types_1.ACTING_IDENTITY_LABEL,
+        bindOnUse: policy.scope === types_1.SCAN_GRANT_SCOPES.SUBJECT,
     });
-    const expiresAt = new Date(Date.now() + (scheme.grant_ttl_seconds ?? 0) * 1000).toISOString();
+    const expiresAt = new Date(Date.now() + policy.ttlSeconds * 1000).toISOString();
     return {
         status: 200,
         data: {
@@ -94,7 +111,8 @@ 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,
+            maxUses: policy.maxUses,
+            grantScope: policy.scope,
         },
     };
 }

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/subject.d.ts

@@ -0,0 +1,15 @@
+import { type LTEscalationRecord, type ScanScheme, type ScanSubjectRef } from '../../types';
+import type { LTApiAuth } from '../../types/sdk';
+import type { HeldSubject } from './context';
+export type SubjectResult = {
+    ok: true;
+    subject: HeldSubject;
+} | {
+    ok: false;
+};
+export declare function resolveSubject(ref: ScanSubjectRef | undefined, schemes: ScanScheme[], stationAuth: LTApiAuth): Promise<SubjectResult | null>;
+/** Who holds a live claim on the row, when that is someone other than `actorId`. */
+export declare function claimedByOther(row: LTEscalationRecord, actorId: string | null): Promise<{
+    id: string;
+    displayName: string;
+} | null>;

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

@@ -0,0 +1,68 @@
+"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.resolveSubject = resolveSubject;
+exports.claimedByOther = claimedByOther;
+const scanCodeService = __importStar(require("../../services/scan-code"));
+const escalationService = __importStar(require("../../services/escalation"));
+const userService = __importStar(require("../../services/user"));
+const uuid_1 = require("../../lib/uuid");
+const helpers_1 = require("../escalations/helpers");
+const types_1 = require("../../types");
+async function resolveSubject(ref, schemes, stationAuth) {
+    if (!ref)
+        return null;
+    if (typeof ref.code !== 'string' || !(0, uuid_1.isUuid)(ref.escalationId))
+        return { ok: false };
+    const parsed = scanCodeService.parseScanCode(ref.code, schemes);
+    if (!parsed.ok || parsed.scheme.kind !== types_1.SCAN_SCHEME_KINDS.ACTION)
+        return { ok: false };
+    const row = await escalationService.getEscalation(ref.escalationId);
+    if (!row || row.status !== 'pending')
+        return { ok: false };
+    if (await (0, helpers_1.assertReadAccess)(stationAuth.userId, row))
+        return { ok: false };
+    if (row.metadata?.[parsed.scheme.target_facet] !== parsed.parsed.target) {
+        return { ok: false };
+    }
+    return { ok: true, subject: { row, parsed: parsed.parsed, scheme: parsed.scheme, code: ref.code } };
+}
+/** Who holds a live claim on the row, when that is someone other than `actorId`. */
+async function claimedByOther(row, actorId) {
+    if (!row.assigned_to || !(0, types_1.isEffectivelyClaimed)(row) || row.assigned_to === actorId)
+        return null;
+    const user = await userService.getUser(row.assigned_to);
+    return { id: row.assigned_to, displayName: user?.display_name || user?.external_id || 'another associate' };
+}