@hotmeshio/long-tail 0.10.13 → 0.11.0

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

@@ -35,11 +35,11 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.executeScanCode = executeScanCode;
 const scanCodeService = __importStar(require("../../services/scan-code"));
-const escalationService = __importStar(require("../../services/escalation"));
-const metadata_1 = require("../escalations/metadata");
-const create_1 = require("../escalations/create");
-const claim_1 = require("../escalations/claim");
-const helpers_1 = require("../escalations/helpers");
+const identity_1 = require("./identity");
+const context_1 = require("./context");
+const locate_1 = require("./locate");
+const present_1 = require("./present");
+const verbs_1 = require("./verbs");
 const types_1 = require("../../types");
 /**
  * Execute a raw scan code: parse → load the rule → walk its steps in order.
@@ -75,9 +75,36 @@ 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);
+        }
+        // 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;
+        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,
+                    },
+                };
+            }
+            effectiveAuth = resolved.auth;
+            acting = true;
+        }
         // 3. Walk the steps — first condition match wins
         const ctx = {
-            scheme, rule, parsed, scannedAt: new Date().toISOString(), auth,
+            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);
@@ -117,256 +144,34 @@ function decorateData(data, ctx) {
  * (fall through) and an LTApiResult for every terminal outcome.
  */
 async function executeStep(step, index, ctx) {
+    // The identity pre-condition: the effective actor must be a real acting
+    // identity — a badge grant, or an authenticated user whose own write scope
+    // covers the step. A write-incapable shared account can never self-satisfy,
+    // 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))) {
+        return (0, context_1.notPrimed)(ctx);
+    }
     // Confirm steps and read verbs only locate — mutation happens after the
     // user confirms, through the standard per-id endpoints.
     if (step.confirm || step.verb === types_1.SCAN_VERBS.SHOW_DETAIL || step.verb === types_1.SCAN_VERBS.SHOW_LIST) {
-        return locateStep(step, ctx);
+        return (0, locate_1.locateStep)(step, ctx);
     }
     switch (step.verb) {
+        case types_1.SCAN_VERBS.PRESENT:
+            return (0, present_1.presentStep)(step, ctx);
         case types_1.SCAN_VERBS.CLAIM:
         case types_1.SCAN_VERBS.CLAIM_SHOW_DETAIL:
-            return claimStep(step, ctx);
+            return (0, verbs_1.claimStep)(step, ctx);
         case types_1.SCAN_VERBS.RESOLVE:
-            return resolveStep(step, ctx);
+            return (0, verbs_1.resolveStep)(step, ctx);
         case types_1.SCAN_VERBS.ESCALATE:
-            return escalateStep(step, ctx);
+            return (0, verbs_1.escalateStep)(step, ctx);
         case types_1.SCAN_VERBS.RELEASE:
-            return releaseStep(step, ctx);
+            return (0, verbs_1.releaseStep)(step, ctx);
         case types_1.SCAN_VERBS.CANCEL:
-            return cancelStep(step, ctx);
+            return (0, verbs_1.cancelStep)(step, ctx);
         default:
             throw new Error(`unknown scan verb "${step.verb}"`);
     }
 }
-// ── Shared pieces ──────────────────────────────────────────────────────────
-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 };
-}
-function provenance(ctx) {
-    return {
-        [types_1.SCAN_PROVENANCE_KEYS.SCHEME]: ctx.scheme.version,
-        [types_1.SCAN_PROVENANCE_KEYS.CATEGORY]: ctx.parsed.category,
-        [types_1.SCAN_PROVENANCE_KEYS.ACTION_NAME]: ctx.rule.name,
-        [types_1.SCAN_PROVENANCE_KEYS.SCANNED_AT]: ctx.scannedAt,
-    };
-}
-function executed(escalation, step) {
-    return { status: 200, data: { outcome: types_1.SCAN_OUTCOMES.EXECUTED, verb: step.verb, escalation } };
-}
-// ── Locate (show-detail, show-list, confirm phase 1) ───────────────────────
-async function locateStep(step, ctx) {
-    const scope = await (0, helpers_1.getEscalationReadScope)(ctx.auth.userId);
-    const availability = step.query?.availability ?? types_1.SCAN_AVAILABILITY.ANY;
-    const status = step.query?.status ?? 'pending';
-    const wantMany = step.verb === types_1.SCAN_VERBS.SHOW_LIST
-        || step.cardinality === types_1.SCAN_CARDINALITY.MANY;
-    const limit = wantMany ? 50 : 2;
-    const facets = targetFilter(step, ctx);
-    let escalations;
-    let total;
-    if (availability === types_1.SCAN_AVAILABILITY.MINE) {
-        // "mine" = assigned to the caller; self-scope roles qualify because the
-        // assigned_to predicate satisfies their visibility branch.
-        const readable = [...scope.allRoles, ...scope.selfRoles];
-        const roles = (0, metadata_1.restrictScopeRoles)(readable, scope.global, step.query?.roles);
-        if (roles !== null && roles.length === 0)
-            return null;
-        const result = await escalationService.listEscalations({
-            metadata: facets,
-            status,
-            assigned_to: ctx.auth.userId,
-            visibleRoles: roles ?? undefined,
-            limit,
-        });
-        escalations = result.escalations;
-        total = result.total;
-    }
-    else {
-        const roles = (0, metadata_1.restrictScopeRoles)(scope.allRoles, scope.global, step.query?.roles);
-        if (roles !== null && roles.length === 0)
-            return null;
-        const result = await escalationService.searchByFacets({
-            roles: roles ?? undefined,
-            facets,
-            status,
-            available: availability === types_1.SCAN_AVAILABILITY.AVAILABLE
-                ? true
-                : availability === types_1.SCAN_AVAILABILITY.CLAIMED ? false : undefined,
-            limit,
-        });
-        escalations = result.escalations;
-        total = result.total;
-    }
-    if (escalations.length === 0)
-        return null;
-    if (step.confirm) {
-        const target = escalations[0];
-        const interpolated = step.params
-            ? scanCodeService.interpolateScanTemplate(step.params, templateContext(ctx))
-            : undefined;
-        return {
-            status: 200,
-            data: {
-                outcome: types_1.SCAN_OUTCOMES.CONFIRM_REQUIRED,
-                verb: step.verb,
-                escalation: target,
-                pendingAction: {
-                    escalationId: target.id,
-                    verb: step.verb,
-                    prompt: step.confirm.prompt,
-                    params: interpolated,
-                },
-            },
-        };
-    }
-    if (wantMany) {
-        return {
-            status: 200,
-            data: {
-                outcome: types_1.SCAN_OUTCOMES.MATCHED_LIST,
-                verb: step.verb,
-                escalations,
-                total,
-                listQuery: {
-                    ...step.query,
-                    targetFacet: ctx.scheme.target_facet,
-                    target: ctx.parsed.target,
-                },
-            },
-        };
-    }
-    return executed(escalations[0], step);
-}
-// ── Mutating verbs — each a single atomic operation under the caller's RBAC ─
-async function claimStep(step, ctx) {
-    const result = await (0, metadata_1.claimByMetadata)({
-        key: ctx.scheme.target_facet,
-        value: ctx.parsed.target,
-        durationMinutes: step.params?.durationMinutes,
-        metadata: { ...interpolatedMetadata(step, ctx), ...provenance(ctx) },
-        restrictRoles: step.query?.roles,
-    }, ctx.auth);
-    if (result.status === 404)
-        return null;
-    if (result.status === 403)
-        return forbidden(result.error);
-    if (result.status !== 200)
-        return result;
-    return executed(result.data.escalation, step);
-}
-async function resolveStep(step, ctx) {
-    const result = await (0, metadata_1.resolveByMetadata)({
-        key: ctx.scheme.target_facet,
-        value: ctx.parsed.target,
-        resolverPayload: scanCodeService.interpolateScanTemplate(step.params?.resolverPayload ?? {}, templateContext(ctx)),
-        metadata: { ...interpolatedMetadata(step, ctx), ...provenance(ctx) },
-        restrictRoles: step.query?.roles,
-        extraFacets: step.query?.facets,
-    }, ctx.auth);
-    if (result.status === 404)
-        return null;
-    if (result.status === 403)
-        return forbidden(result.error);
-    if (result.status === 409)
-        return conflict(result.error);
-    if (result.status !== 200)
-        return result;
-    const escalation = result.data.escalation
-        ?? (result.data.escalationId ? { id: result.data.escalationId } : undefined);
-    return executed(escalation, step);
-}
-async function escalateStep(step, ctx) {
-    // Close the located escalation first when configured — the close doubles as
-    // the condition check AND the double-scan guard (second scan finds nothing
-    // to close and falls through).
-    if (step.params?.closeCurrent === 'resolve') {
-        const closed = await resolveStep({ ...step, params: { ...step.params, resolverPayload: step.params?.resolverPayload ?? {} } }, ctx);
-        if (closed === null)
-            return null;
-        if (closed.data?.outcome !== types_1.SCAN_OUTCOMES.EXECUTED)
-            return closed;
-    }
-    else if (step.params?.closeCurrent === 'cancel') {
-        const cancelled = await cancelStep(step, ctx);
-        if (cancelled === null)
-            return null;
-        if (cancelled.data?.outcome !== types_1.SCAN_OUTCOMES.EXECUTED)
-            return cancelled;
-    }
-    const created = await (0, create_1.createEscalation)({
-        type: step.params?.escalationType ?? 'scan',
-        role: step.params.targetRole,
-        description: step.params?.description ?? ctx.rule.name,
-        metadata: {
-            [ctx.scheme.target_facet]: ctx.parsed.target,
-            ...interpolatedMetadata(step, ctx),
-            ...provenance(ctx),
-        },
-    }, ctx.auth);
-    if (created.status === 403)
-        return forbidden(created.error);
-    if (created.status !== 201)
-        return created;
-    return executed(created.data, step);
-}
-async function releaseStep(step, ctx) {
-    // Locate the caller's own claim; release-by-id re-asserts the assignee
-    // inside the SDK, so a lost race resolves to 409, never a foreign release.
-    const scope = await (0, helpers_1.getEscalationReadScope)(ctx.auth.userId);
-    const readable = [...scope.allRoles, ...scope.selfRoles];
-    const roles = (0, metadata_1.restrictScopeRoles)(readable, scope.global, step.query?.roles);
-    if (roles !== null && roles.length === 0)
-        return null;
-    const { escalations } = await escalationService.listEscalations({
-        metadata: targetFilter(step, ctx),
-        status: 'pending',
-        assigned_to: ctx.auth.userId,
-        visibleRoles: roles ?? undefined,
-        limit: 1,
-    });
-    if (escalations.length === 0)
-        return null;
-    const result = await (0, claim_1.releaseEscalation)({ id: escalations[0].id }, ctx.auth);
-    if (result.status === 403)
-        return forbidden(result.error);
-    if (result.status === 409)
-        return conflict(result.error);
-    if (result.status !== 200)
-        return result;
-    return executed(result.data.escalation, step);
-}
-async function cancelStep(step, ctx) {
-    // Claim-as-lock: the atomic claim pins the row to this caller (or extends
-    // their claim), serializing concurrent double-scans before the cancel.
-    const claimed = await (0, metadata_1.claimByMetadata)({
-        key: ctx.scheme.target_facet,
-        value: ctx.parsed.target,
-        metadata: provenance(ctx),
-        restrictRoles: step.query?.roles,
-    }, ctx.auth);
-    if (claimed.status === 404)
-        return null;
-    if (claimed.status === 403)
-        return forbidden(claimed.error);
-    if (claimed.status !== 200)
-        return claimed;
-    const cancelled = await escalationService.cancelEscalation(claimed.data.escalation.id);
-    if (!cancelled)
-        return conflict('Escalation is not cancellable (already terminal)');
-    return executed(cancelled, step);
-}
-// ── Small result helpers ───────────────────────────────────────────────────
-function interpolatedMetadata(step, ctx) {
-    return step.params?.metadata
-        ? scanCodeService.interpolateScanTemplate(step.params.metadata, templateContext(ctx))
-        : {};
-}
-function forbidden(error) {
-    return { status: 200, data: { outcome: types_1.SCAN_OUTCOMES.FORBIDDEN, error } };
-}
-function conflict(error) {
-    return { status: 200, data: { outcome: types_1.SCAN_OUTCOMES.CONFLICT, error } };
-}

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

@@ -0,0 +1,18 @@
+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';
+/**
+ * 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>>;
+/**
+ * The identity pre-condition's satisfaction test. A primed grant always
+ * satisfies; without one, the authenticated user satisfies only when their
+ * OWN write scope covers the step's roles — their login IS a person identity
+ * with authority there. A write-incapable shared account can never
+ * self-satisfy.
+ */
+export declare function actingIdentitySatisfied(step: Pick<ScanStep, 'query'>, ctx: StepContext): Promise<boolean>;

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

@@ -0,0 +1,116 @@
+"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.resolveActingAuth = void 0;
+exports.executeIdentityScan = executeIdentityScan;
+exports.actingIdentitySatisfied = actingIdentitySatisfied;
+const userService = __importStar(require("../../services/user"));
+const ephemeral_1 = require("../../services/iam/ephemeral");
+const metadata_1 = require("../escalations/metadata");
+const helpers_1 = require("../escalations/helpers");
+const types_1 = require("../../types");
+var acting_identity_1 = require("../../services/iam/acting-identity");
+Object.defineProperty(exports, "resolveActingAuth", { enumerable: true, get: function () { return acting_identity_1.resolveActingAuth; } });
+// ── Acting identity — the badge layer over the scan surface ────────────────
+//
+// A shared station device signs in as an ordinary read-capable account; the
+// person supplies identity by scanning a badge under an identity-kind scheme.
+// The badge token is an opaque printed credential resolved against a
+// server-side binding (scheme.target_facet names the lt_users.metadata key it
+// matches — never external_id, so a printed username can never impersonate).
+// A match MINTS a grant through the ephemeral keystore: short-TTL, optionally
+// n-use, useless unless exchanged server-side. The grant confers ATTRIBUTION,
+// never privilege — verbs later run under the acting user's own live RBAC.
+/**
+ * Resolve an identity scan: badge → user → minted acting grant.
+ * 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);
+    if (!user) {
+        return {
+            status: 200,
+            data: {
+                outcome: types_1.SCAN_OUTCOMES.IDENTITY_UNKNOWN,
+                parsed,
+                rule: { schemeVersion: rule.scheme_version, category: rule.category, name: rule.name },
+                fallback: rule.fallback,
+                error: 'badge not recognized',
+            },
+        };
+    }
+    // The station is swapping people — the outgoing grant dies now, not at TTL.
+    if (previousActingToken) {
+        const prev = (0, ephemeral_1.parseEphemeralToken)(previousActingToken);
+        if (prev && prev.label === types_1.ACTING_IDENTITY_LABEL) {
+            await (0, ephemeral_1.revokeEphemeral)(prev.uuid).catch(() => { });
+        }
+    }
+    const uuid = await (0, ephemeral_1.storeEphemeral)(user.id, {
+        ttlSeconds: scheme.grant_ttl_seconds ?? undefined,
+        maxUses: scheme.grant_max_uses,
+        label: types_1.ACTING_IDENTITY_LABEL,
+    });
+    const expiresAt = new Date(Date.now() + (scheme.grant_ttl_seconds ?? 0) * 1000).toISOString();
+    return {
+        status: 200,
+        data: {
+            outcome: types_1.SCAN_OUTCOMES.IDENTITY_PRIMED,
+            parsed,
+            rule: { schemeVersion: rule.scheme_version, category: rule.category, name: rule.name },
+            actor: { id: user.id, displayName: user.display_name || user.external_id },
+            actingToken: (0, ephemeral_1.formatEphemeralToken)(uuid, types_1.ACTING_IDENTITY_LABEL),
+            expiresAt,
+        },
+    };
+}
+/**
+ * The identity pre-condition's satisfaction test. A primed grant always
+ * satisfies; without one, the authenticated user satisfies only when their
+ * OWN write scope covers the step's roles — their login IS a person identity
+ * with authority there. A write-incapable shared account can never
+ * self-satisfy.
+ */
+async function actingIdentitySatisfied(step, ctx) {
+    if (ctx.acting)
+        return true;
+    const scope = await (0, helpers_1.getEscalationWriteScope)(ctx.stationAuth.userId);
+    if (scope.global)
+        return true;
+    const writable = [...scope.allRoles, ...scope.selfRoles];
+    const roles = (0, metadata_1.restrictScopeRoles)(writable, scope.global, step.query?.roles);
+    return roles === null || roles.length > 0;
+}

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

@@ -1,2 +1,4 @@
 export { executeScanCode } from './execute';
+export { executeScanChoice } from './choice';
+export { executeIdentityScan, resolveActingAuth } from './identity';
 export { listScanSchemes, getScanScheme, upsertScanScheme, deleteScanScheme, listScanRules, getScanRule, upsertScanRule, deleteScanRule, } from './config';

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

@@ -1,8 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.deleteScanRule = exports.upsertScanRule = exports.getScanRule = exports.listScanRules = exports.deleteScanScheme = exports.upsertScanScheme = exports.getScanScheme = exports.listScanSchemes = exports.executeScanCode = void 0;
+exports.deleteScanRule = exports.upsertScanRule = exports.getScanRule = exports.listScanRules = exports.deleteScanScheme = exports.upsertScanScheme = exports.getScanScheme = exports.listScanSchemes = exports.resolveActingAuth = exports.executeIdentityScan = exports.executeScanChoice = exports.executeScanCode = void 0;
 var execute_1 = require("./execute");
 Object.defineProperty(exports, "executeScanCode", { enumerable: true, get: function () { return execute_1.executeScanCode; } });
+var choice_1 = require("./choice");
+Object.defineProperty(exports, "executeScanChoice", { enumerable: true, get: function () { return choice_1.executeScanChoice; } });
+var identity_1 = require("./identity");
+Object.defineProperty(exports, "executeIdentityScan", { enumerable: true, get: function () { return identity_1.executeIdentityScan; } });
+Object.defineProperty(exports, "resolveActingAuth", { enumerable: true, get: function () { return identity_1.resolveActingAuth; } });
 var config_1 = require("./config");
 Object.defineProperty(exports, "listScanSchemes", { enumerable: true, get: function () { return config_1.listScanSchemes; } });
 Object.defineProperty(exports, "getScanScheme", { enumerable: true, get: function () { return config_1.getScanScheme; } });

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

@@ -0,0 +1,14 @@
+import { type LTEscalationRecord, type ScanExecuteResponse, type ScanStep } from '../../types';
+import type { LTApiResult } from '../../types/sdk';
+import { type StepContext } from './context';
+/**
+ * The scoped locate every read path shares: the scanned target pinned to the
+ * scheme's facet, the step's extra guards, and the EFFECTIVE actor's read
+ * scope. Returns null when the caller's scope leaves no roles to search.
+ */
+export declare function locateForStep(step: ScanStep, ctx: StepContext, limit: number): Promise<{
+    escalations: LTEscalationRecord[];
+    total: number;
+} | null>;
+/** Locate for show-detail, show-list, and the confirm phase. */
+export declare function locateStep(step: ScanStep, ctx: StepContext): Promise<LTApiResult<ScanExecuteResponse> | null>;

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

@@ -0,0 +1,127 @@
+"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.locateForStep = locateForStep;
+exports.locateStep = locateStep;
+const scanCodeService = __importStar(require("../../services/scan-code"));
+const escalationService = __importStar(require("../../services/escalation"));
+const metadata_1 = require("../escalations/metadata");
+const helpers_1 = require("../escalations/helpers");
+const types_1 = require("../../types");
+const context_1 = require("./context");
+/**
+ * The scoped locate every read path shares: the scanned target pinned to the
+ * scheme's facet, the step's extra guards, and the EFFECTIVE actor's read
+ * scope. Returns null when the caller's scope leaves no roles to search.
+ */
+async function locateForStep(step, ctx, limit) {
+    const scope = await (0, helpers_1.getEscalationReadScope)(ctx.auth.userId);
+    const availability = step.query?.availability ?? types_1.SCAN_AVAILABILITY.ANY;
+    const status = step.query?.status ?? 'pending';
+    const facets = (0, context_1.targetFilter)(step, ctx);
+    if (availability === types_1.SCAN_AVAILABILITY.MINE) {
+        // "mine" = assigned to the caller; self-scope roles qualify because the
+        // assigned_to predicate satisfies their visibility branch.
+        const readable = [...scope.allRoles, ...scope.selfRoles];
+        const roles = (0, metadata_1.restrictScopeRoles)(readable, scope.global, step.query?.roles);
+        if (roles !== null && roles.length === 0)
+            return null;
+        return escalationService.listEscalations({
+            metadata: facets,
+            status,
+            assigned_to: ctx.auth.userId,
+            visibleRoles: roles ?? undefined,
+            limit,
+        });
+    }
+    const roles = (0, metadata_1.restrictScopeRoles)(scope.allRoles, scope.global, step.query?.roles);
+    if (roles !== null && roles.length === 0)
+        return null;
+    return escalationService.searchByFacets({
+        roles: roles ?? undefined,
+        facets,
+        status,
+        available: availability === types_1.SCAN_AVAILABILITY.AVAILABLE
+            ? true
+            : availability === types_1.SCAN_AVAILABILITY.CLAIMED ? false : undefined,
+        limit,
+    });
+}
+/** Locate for show-detail, show-list, and the confirm phase. */
+async function locateStep(step, ctx) {
+    const wantMany = step.verb === types_1.SCAN_VERBS.SHOW_LIST
+        || step.cardinality === types_1.SCAN_CARDINALITY.MANY;
+    const result = await locateForStep(step, ctx, wantMany ? 50 : 2);
+    if (!result || result.escalations.length === 0)
+        return null;
+    const { escalations, total } = result;
+    if (step.confirm) {
+        const target = escalations[0];
+        const interpolated = step.params
+            ? scanCodeService.interpolateScanTemplate(step.params, (0, context_1.templateContext)(ctx))
+            : undefined;
+        return {
+            status: 200,
+            data: {
+                outcome: types_1.SCAN_OUTCOMES.CONFIRM_REQUIRED,
+                verb: step.verb,
+                escalation: target,
+                pendingAction: {
+                    escalationId: target.id,
+                    verb: step.verb,
+                    prompt: step.confirm.prompt,
+                    params: interpolated,
+                },
+            },
+        };
+    }
+    if (wantMany) {
+        return {
+            status: 200,
+            data: {
+                outcome: types_1.SCAN_OUTCOMES.MATCHED_LIST,
+                verb: step.verb,
+                escalations,
+                total,
+                listQuery: {
+                    ...step.query,
+                    targetFacet: ctx.scheme.target_facet,
+                    target: ctx.parsed.target,
+                },
+            },
+        };
+    }
+    return (0, context_1.executed)(escalations[0], step);
+}

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

@@ -0,0 +1,9 @@
+import { type ScanExecuteResponse, type ScanStep } from '../../types';
+import type { LTApiResult } from '../../types/sdk';
+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
+ * rule's "scan your badge" affordance beside them instead of a dead button.
+ */
+export declare function presentStep(step: ScanStep, ctx: StepContext): Promise<LTApiResult<ScanExecuteResponse> | null>;