@hotmeshio/long-tail 0.22.1 → 0.22.2

package/build/api/escalations/accumulate.js

@@ -68,6 +68,15 @@ function isBatch(escalation) {
     return Array.isArray(escalation.metadata?.[escalation_1.ESCALATION_BATCH_KEYS.PENDING]);
 }
 const NO_ACCUMULATOR_FOR_FACET = 'No pending accumulator found for this metadata';
+/** The add's item-key error, or null when the key is usable. */
+function itemKeyError(itemKey) {
+    if (!itemKey)
+        return { status: 400, error: 'itemKey is required' };
+    if (typeof itemKey !== 'string' || itemKey.length > escalation_1.ESCALATION_ITEM_KEY_MAX_LENGTH) {
+        return { status: 400, error: `itemKey must be a string of at most ${escalation_1.ESCALATION_ITEM_KEY_MAX_LENGTH} characters` };
+    }
+    return null;
+}
 /**
  * The container a facet names: the highest priority pending row that carries
  * the facet AND the accumulator declaration, within the given roles (null =
@@ -199,18 +208,22 @@ async function gatePayload(escalation, payload, userId) {
 async function accumulateItem(input, auth) {
     try {
         const { id, itemKey, metadata } = input;
-        if (!itemKey)
-            return { status: 400, error: 'itemKey is required' };
+        const keyError = itemKeyError(itemKey);
+        if (keyError)
+            return keyError;
         const initiator = await resolveActor(input.initiatedBy, auth);
         if ('error' in initiator)
             return initiator.error;
         const escalation = await escalationService.getEscalation(id);
         if (!escalation)
             return { status: 404, error: 'Escalation not found' };
-        if (escalation.status === 'cancelled')
-            return { status: 409, error: 'Escalation is cancelled' };
-        if (escalation.status !== 'pending')
-            return { status: 409, error: 'Escalation not available for accumulation' };
+        if (escalation.status === 'cancelled') {
+            return { status: 409, error: 'Escalation is cancelled', data: { error: 'Escalation is cancelled', outcome: 'already-cancelled' } };
+        }
+        if (escalation.status !== 'pending') {
+            const error = 'Escalation not available for accumulation';
+            return { status: 409, error, data: { error, outcome: `already-${escalation.status}` } };
+        }
         if (!isAccumulator(escalation))
             return { status: 400, error: 'Escalation is not an accumulator' };
         if (await (0, helpers_1.assertReadAccess)(auth.userId, escalation)) {
@@ -250,8 +263,9 @@ async function accumulateItemBySignalKey(input, auth) {
         const { signalKey, itemKey, metadata } = input;
         if (!signalKey)
             return { status: 400, error: 'signalKey is required' };
-        if (!itemKey)
-            return { status: 400, error: 'itemKey is required' };
+        const keyError = itemKeyError(itemKey);
+        if (keyError)
+            return keyError;
         const initiator = await resolveActor(input.initiatedBy, auth);
         if ('error' in initiator)
             return initiator.error;
@@ -301,8 +315,9 @@ async function accumulateItemByMetadata(input, auth) {
         const { key, value, itemKey, metadata } = input;
         if (!key || !value)
             return { status: 400, error: 'key and value are required' };
-        if (!itemKey)
-            return { status: 400, error: 'itemKey is required' };
+        const keyError = itemKeyError(itemKey);
+        if (keyError)
+            return keyError;
         const initiator = await resolveActor(input.initiatedBy, auth);
         if ('error' in initiator)
             return initiator.error;
@@ -574,21 +589,21 @@ function accumulateOutcomeResult(result, itemKey, workflowId) {
                 },
             };
         case 'duplicate-item':
-            return { status: 409, error: 'Item already held', data: { error: 'Item already held', itemKey } };
+            return { status: 409, error: 'Item already held', data: { error: 'Item already held', itemKey, outcome: 'duplicate-item' } };
         case 'full':
-            return { status: 409, error: 'Accumulator is full', data: { error: 'Accumulator is full', itemKey } };
+            return { status: 409, error: 'Accumulator is full', data: { error: 'Accumulator is full', itemKey, outcome: 'full' } };
         case 'claimed-by-other':
-            return { status: 409, error: 'Escalation is claimed by another user' };
+            return { status: 409, error: 'Escalation is claimed by another user', data: { error: 'Escalation is claimed by another user', outcome: 'claimed-by-other' } };
         case 'claim-expired':
-            return { status: 409, error: 'Your claim has expired; re-claim this escalation to add to it' };
+            return { status: 409, error: 'Your claim has expired; re-claim this escalation to add to it', data: { error: 'Your claim has expired; re-claim this escalation to add to it', outcome: 'claim-expired' } };
         case 'not-found':
-            return { status: 404, error: 'Escalation not found' };
+            return { status: 404, error: 'Escalation not found', data: { error: 'Escalation not found', outcome: 'not-found' } };
         case 'not-accumulator':
-            return { status: 400, error: 'Escalation is not an accumulator' };
+            return { status: 400, error: 'Escalation is not an accumulator', data: { error: 'Escalation is not an accumulator', outcome: 'not-accumulator' } };
         case 'reciprocal-not-found':
-            return { status: 404, error: 'Reciprocal escalation not found' };
+            return { status: 404, error: 'Reciprocal escalation not found', data: { error: 'Reciprocal escalation not found', outcome: 'reciprocal-not-found' } };
         case 'reciprocal-not-accumulator':
-            return { status: 400, error: 'Reciprocal escalation is not an accumulator' };
+            return { status: 400, error: 'Reciprocal escalation is not an accumulator', data: { error: 'Reciprocal escalation is not an accumulator', outcome: 'reciprocal-not-accumulator' } };
         case 'reciprocal-duplicate':
             return { status: 409, error: 'Reciprocal escalation already holds this container', data: { error: 'Reciprocal escalation already holds this container', outcome: result.outcome } };
         case 'reciprocal-full':
@@ -596,7 +611,11 @@ function accumulateOutcomeResult(result, itemKey, workflowId) {
         case 'reciprocal-terminal':
             return { status: 409, error: 'Reciprocal escalation is no longer pending', data: { error: 'Reciprocal escalation is no longer pending', outcome: result.outcome } };
         default:
-            return { status: 409, error: 'Escalation not available for accumulation' };
+            return {
+                status: 409,
+                error: 'Escalation not available for accumulation',
+                data: { error: 'Escalation not available for accumulation', outcome: result.outcome },
+            };
     }
 }
 function removeOutcomeResult(result, itemKey) {

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

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

package/build/api/roles.js

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

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

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

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

@@ -0,0 +1,72 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stationGrantPolicy = stationGrantPolicy;
+const roleService = __importStar(require("../../services/role"));
+const userService = __importStar(require("../../services/user"));
+const badge_grant_1 = require("../../services/role/badge-grant");
+const types_1 = require("../../types");
+function schemePolicy(scheme) {
+    return {
+        ttlSeconds: scheme.grant_ttl_seconds ?? 0,
+        maxUses: scheme.grant_max_uses ?? 0,
+        scope: scheme.grant_scope ?? types_1.SCAN_GRANT_SCOPES.ACTION,
+    };
+}
+/** The policy a badge scanned on this device mints under. */
+async function stationGrantPolicy(scheme, stationUserId, stationRole) {
+    const fallback = schemePolicy(scheme);
+    const user = await userService.getUser(stationUserId);
+    const memberRoles = (user?.roles ?? []).map((r) => r.role);
+    const candidates = stationRole
+        ? memberRoles.filter((r) => r === stationRole)
+        : memberRoles;
+    const declared = [];
+    for (const role of candidates) {
+        const grant = (0, badge_grant_1.readBadgeGrant)(await roleService.getRoleProperties(role));
+        if (grant)
+            declared.push({ role, grant });
+    }
+    const distinct = new Set(declared.map((d) => JSON.stringify(d.grant)));
+    if (distinct.size !== 1)
+        return fallback;
+    const { role, grant } = declared[0];
+    return {
+        ttlSeconds: grant.ttl_seconds ?? fallback.ttlSeconds,
+        maxUses: grant.max_uses ?? fallback.maxUses,
+        scope: grant.scope ?? fallback.scope,
+        role,
+    };
+}

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

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

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

@@ -1,11 +1,34 @@
 import * as scanCodeService from '../../services/scan-code';
 import { type LTEscalationRecord, type ParsedScanCode, 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 {
+    row: LTEscalationRecord;
+    parsed: ParsedScanCode;
+    scheme: ScanScheme;
+    code: string;
+}
+/** The acting grant riding the request, and whether this request spent it. */
+export interface GrantLedger {
+    token: string;
+    /** Before this request touched it. */
+    peeked: {
+        remaining: number | null;
+        bound: boolean;
+    };
+    /** Set once this request spends a use; null until then. */
+    spent: {
+        remaining: number | null;
+        bound: boolean;
+    } | null;
+}
 /** Everything a step executor needs about the scan that reached it. */
 export interface StepContext {
     scheme: ScanScheme;
     rule: ScanRule;
     parsed: ParsedScanCode;
+    /** The code as the station scanned it; absent when a choice re-derived the target. */
+    rawCode?: string;
     scannedAt: string;
     /** The effective actor — the acting (badged) user when a grant rode the request. */
     auth: LTApiAuth;
@@ -13,9 +36,17 @@ export interface StepContext {
     stationAuth: LTApiAuth;
     /** True when `auth` came from an acting-identity grant. */
     acting: boolean;
+    /** The grant behind `acting`; spent only when an act lands. */
+    grant?: GrantLedger;
+    /** The subject the station holds, when its pointer still checks out. */
+    subject?: HeldSubject;
+    /** The station sent a subject pointer that no longer checks out. */
+    subjectStale?: boolean;
 }
 export declare function targetFilter(step: ScanStep, ctx: StepContext): Record<string, any>;
 export declare function templateContext(ctx: StepContext): scanCodeService.ScanTemplateContext;
+/** The `{subject.x}` bag: the held row's metadata plus its id. */
+export declare function subjectBag(row: LTEscalationRecord): Record<string, unknown>;
 /**
  * The metadata of the acting user's single live claim, or undefined when
  * they hold none or more than one. One scoped list query, read before the
@@ -34,4 +65,17 @@ export declare function interpolatedMetadata(step: ScanStep, ctx: StepContext, t
 export declare function executed(escalation: LTEscalationRecord | Record<string, any> | undefined, step: Pick<ScanStep, 'verb'>): LTApiResult<ScanExecuteResponse>;
 export declare function forbidden(error?: string): LTApiResult<ScanExecuteResponse>;
 export declare function conflict(error?: string): LTApiResult<ScanExecuteResponse>;
-export declare function notPrimed(ctx: StepContext): LTApiResult<ScanExecuteResponse>;
+export declare function notPrimed(ctx: StepContext, error?: string): LTApiResult<ScanExecuteResponse>;
+/** Nothing was written; say why, and name what the step expected. */
+export declare function refused(markdown: string, extra?: Partial<ScanExecuteResponse>): LTApiResult<ScanExecuteResponse>;
+/**
+ * Interpolates a step's params, or falls through when a `{claim.…}` or
+ * `{item.…}` token has nothing to read: a literal token never reaches a row.
+ */
+export declare function templated<T>(step: ScanStep, ctx: StepContext, render: (tpl: scanCodeService.ScanTemplateContext) => T, item?: LTEscalationRecord): Promise<T | null>;
+/**
+ * Attach the step's `done` copy to a write that landed. `tpl` carries the
+ * bags the copy may read (the container a subject step located, a fill's
+ * batch); an unreadable token renders empty rather than failing the act.
+ */
+export declare function withDone(result: LTApiResult<ScanExecuteResponse>, step: ScanStep, tpl: scanCodeService.ScanTemplateContext): LTApiResult<ScanExecuteResponse>;

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

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.targetFilter = targetFilter;
 exports.templateContext = templateContext;
+exports.subjectBag = subjectBag;
 exports.liveClaimMetadata = liveClaimMetadata;
 exports.stepTemplate = stepTemplate;
 exports.provenance = provenance;
@@ -43,6 +44,9 @@ exports.executed = executed;
 exports.forbidden = forbidden;
 exports.conflict = conflict;
 exports.notPrimed = notPrimed;
+exports.refused = refused;
+exports.templated = templated;
+exports.withDone = withDone;
 const scanCodeService = __importStar(require("../../services/scan-code"));
 const escalationService = __importStar(require("../../services/escalation"));
 const types_1 = require("../../types");
@@ -50,7 +54,17 @@ function targetFilter(step, ctx) {
     return { [ctx.scheme.target_facet]: ctx.parsed.target, ...(step.query?.facets ?? {}) };
 }
 function templateContext(ctx) {
-    return { target: ctx.parsed.target, category: ctx.parsed.category, scannedAt: ctx.scannedAt };
+    return {
+        target: ctx.parsed.target,
+        category: ctx.parsed.category,
+        scannedAt: ctx.scannedAt,
+        code: ctx.parsed.raw ?? ctx.parsed.target,
+        ...(ctx.subject ? { subject: subjectBag(ctx.subject.row) } : {}),
+    };
+}
+/** The `{subject.x}` bag: the held row's metadata plus its id. */
+function subjectBag(row) {
+    return { ...(row.metadata ?? {}), id: row.id };
 }
 /**
  * The metadata of the acting user's single live claim, or undefined when
@@ -102,13 +116,47 @@ function forbidden(error) {
 function conflict(error) {
     return { status: 200, data: { outcome: types_1.SCAN_OUTCOMES.CONFLICT, error } };
 }
-function notPrimed(ctx) {
+function notPrimed(ctx, error) {
     return {
         status: 200,
         data: {
             outcome: types_1.SCAN_OUTCOMES.NOT_PRIMED,
             notPrimed: ctx.rule.notPrimed,
-            error: 'an acting identity is required — scan your badge',
+            replayable: true,
+            error: error ?? 'an acting identity is required — scan your badge',
         },
     };
 }
+/** Nothing was written; say why, and name what the step expected. */
+function refused(markdown, extra = {}) {
+    return {
+        status: 200,
+        data: { outcome: types_1.SCAN_OUTCOMES.REFUSED, refusal: { markdown }, error: markdown, ...extra },
+    };
+}
+/**
+ * Interpolates a step's params, or falls through when a `{claim.…}` or
+ * `{item.…}` token has nothing to read: a literal token never reaches a row.
+ */
+async function templated(step, ctx, render, item) {
+    const tpl = await stepTemplate(step, ctx, item);
+    try {
+        return render(tpl);
+    }
+    catch (err) {
+        if (err instanceof scanCodeService.ScanTemplateError)
+            return null;
+        throw err;
+    }
+}
+/**
+ * Attach the step's `done` copy to a write that landed. `tpl` carries the
+ * bags the copy may read (the container a subject step located, a fill's
+ * batch); an unreadable token renders empty rather than failing the act.
+ */
+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) } } };
+}

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}"`);
     }