@hotmeshio/long-tail 0.10.11 → 0.10.13

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

@@ -37,6 +37,7 @@ export declare function listEscalations(input: {
     type?: string;
     subtype?: string;
     assigned_to?: string;
+    parent_id?: string;
     claimed?: boolean;
     priority?: number;
     limit?: number;

package/build/api/escalations/list.js

@@ -115,6 +115,7 @@ async function listEscalations(input, auth) {
             type: input.type,
             subtype: input.subtype,
             assigned_to: input.assigned_to,
+            parent_id: input.parent_id,
             claimed: input.claimed,
             priority: input.priority,
             limit: input.limit,

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

@@ -1,5 +1,13 @@
 import { type ProvisionIfAbsent } from './helpers';
 import type { LTApiAuth, LTApiResult } from '../../types/sdk';
+/**
+ * Intersect the caller's scope roles with an optional caller-supplied
+ * restriction (e.g. a scan step's expected queues). Global scope with no
+ * restriction stays unfiltered (null); a restriction always applies. An
+ * empty intersection returns [] — which matches nothing in the SQL filter,
+ * the correct fail-closed outcome.
+ */
+export declare function restrictScopeRoles(scopeRoles: string[], global: boolean, restrictRoles?: string[]): string[] | null;
 /**
  * Find escalations by a metadata key-value pair.
  *
@@ -27,6 +35,7 @@ export declare function claimByMetadata(input: {
     assignee?: string;
     metadata?: Record<string, any>;
     provisionIfAbsent?: ProvisionIfAbsent;
+    restrictRoles?: string[];
 }, auth: LTApiAuth): Promise<LTApiResult>;
 /**
  * Resolve an escalation by metadata key-value pair.
@@ -46,4 +55,6 @@ export declare function resolveByMetadata(input: {
     resolverPayload: Record<string, any>;
     assignee?: string;
     metadata?: Record<string, any>;
+    restrictRoles?: string[];
+    extraFacets?: Record<string, any>;
 }, auth: LTApiAuth): Promise<LTApiResult>;

package/build/api/escalations/metadata.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.restrictScopeRoles = restrictScopeRoles;
 exports.findByMetadata = findByMetadata;
 exports.claimByMetadata = claimByMetadata;
 exports.resolveByMetadata = resolveByMetadata;
@@ -41,6 +42,20 @@ const helpers_1 = require("./helpers");
 const resolver_validation_1 = require("../../services/escalation/resolver-validation");
 const enforcement_cache_1 = require("../../services/role/enforcement-cache");
 const resolve_1 = require("./resolve");
+/**
+ * Intersect the caller's scope roles with an optional caller-supplied
+ * restriction (e.g. a scan step's expected queues). Global scope with no
+ * restriction stays unfiltered (null); a restriction always applies. An
+ * empty intersection returns [] — which matches nothing in the SQL filter,
+ * the correct fail-closed outcome.
+ */
+function restrictScopeRoles(scopeRoles, global, restrictRoles) {
+    if (!restrictRoles || restrictRoles.length === 0)
+        return global ? null : scopeRoles;
+    if (global)
+        return restrictRoles;
+    return scopeRoles.filter((r) => restrictRoles.includes(r));
+}
 /**
  * Find escalations by a metadata key-value pair.
  *
@@ -85,9 +100,10 @@ async function claimByMetadata(input, auth) {
         // Write-scope: global → no filter; otherwise restrict to write_all roles. The
         // SDK claim-by-metadata uses a flat role filter and cannot enforce write_self
         // ownership, so self-scope members are excluded from this path (their items
-        // are pre-claimed and acted on by id).
+        // are pre-claimed and acted on by id). An optional caller restriction
+        // (expected queues) intersects with the scope inside the same SQL filter.
         const writeScope = await (0, helpers_1.getEscalationWriteScope)(auth.userId);
-        const allowedRoles = writeScope.global ? null : writeScope.allRoles;
+        const allowedRoles = restrictScopeRoles(writeScope.allRoles, writeScope.global, input.restrictRoles);
         const result = await escalationService.claimByMetadata(input.key, input.value, claimUserId, input.durationMinutes, input.metadata, allowedRoles);
         if (!result) {
             // No rows matched. Check if candidates existed (role mismatch vs no match).
@@ -129,22 +145,26 @@ async function resolveByMetadata(input, auth) {
         // Write-scope folds into the atomic resolve SQL: global → no filter; otherwise
         // write_all roles match any item, write_self roles match only items assigned
         // to the resolver. A non-global caller cannot pass a foreign assignee, so the
-        // self-branch (assigned_to = resolveUserId) is the caller's own items.
+        // self-branch (assigned_to = resolveUserId) is the caller's own items. An
+        // optional caller restriction (expected queues) intersects with both arrays
+        // inside the same SQL filter.
         const writeScope = await (0, helpers_1.getEscalationWriteScope)(auth.userId);
-        const writeAllRoles = writeScope.global ? null : writeScope.allRoles;
-        const writeSelfRoles = writeScope.global ? null : writeScope.selfRoles;
+        const writeAllRoles = restrictScopeRoles(writeScope.allRoles, writeScope.global, input.restrictRoles);
+        const writeSelfRoles = writeScope.global
+            ? (input.restrictRoles?.length ? [] : null)
+            : restrictScopeRoles(writeScope.selfRoles, false, input.restrictRoles);
         // Schema enforcement rides the atomic statement: with the cached enforcing
         // set empty (the common case) the single-call behavior is unchanged. When
         // the picked row's role enforces, the statement returns the row WITHOUT
         // writing; the payload validates here, then a second asserted pass claims
         // + resolves the same row with pending re-checked inside the statement.
         const enforcing = await (0, enforcement_cache_1.getEnforcingRoles)();
-        let result = await escalationService.resolveByMetadataAtomic(input.key, input.value, resolveUserId, input.resolverPayload, input.metadata, writeAllRoles, writeSelfRoles, enforcing.size > 0 ? [...enforcing] : null);
+        let result = await escalationService.resolveByMetadataAtomic(input.key, input.value, resolveUserId, input.resolverPayload, input.metadata, writeAllRoles, writeSelfRoles, enforcing.size > 0 ? [...enforcing] : null, null, input.extraFacets);
         if (result.outcome === 'validation_required' && result.row) {
             const report = await (0, resolver_validation_1.checkResolverPayload)(result.row, input.resolverPayload);
             if (report)
                 return (0, resolve_1.validationFailure)(report);
-            result = await escalationService.resolveByMetadataAtomic(input.key, input.value, resolveUserId, input.resolverPayload, input.metadata, writeAllRoles, writeSelfRoles, null, result.row.id);
+            result = await escalationService.resolveByMetadataAtomic(input.key, input.value, resolveUserId, input.resolverPayload, input.metadata, writeAllRoles, writeSelfRoles, null, result.row.id, input.extraFacets);
             // The asserted row left pending between the two passes — a concurrent
             // resolution won the row; surface it as the conflict it is.
             if (result.outcome === 'not_found') {

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

@@ -0,0 +1,22 @@
+import * as scanCodeService from '../../services/scan-code';
+import type { LTApiResult } from '../../types/sdk';
+export declare function listScanSchemes(): Promise<LTApiResult>;
+export declare function getScanScheme(input: {
+    version: number;
+}): Promise<LTApiResult>;
+export declare function upsertScanScheme(input: scanCodeService.ScanSchemeInput): Promise<LTApiResult>;
+export declare function deleteScanScheme(input: {
+    version: number;
+}): Promise<LTApiResult>;
+export declare function listScanRules(input: {
+    version: number;
+}): Promise<LTApiResult>;
+export declare function getScanRule(input: {
+    version: number;
+    category: string;
+}): Promise<LTApiResult>;
+export declare function upsertScanRule(input: scanCodeService.ScanRuleInput): Promise<LTApiResult>;
+export declare function deleteScanRule(input: {
+    version: number;
+    category: string;
+}): Promise<LTApiResult>;

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

@@ -0,0 +1,136 @@
+"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.listScanSchemes = listScanSchemes;
+exports.getScanScheme = getScanScheme;
+exports.upsertScanScheme = upsertScanScheme;
+exports.deleteScanScheme = deleteScanScheme;
+exports.listScanRules = listScanRules;
+exports.getScanRule = getScanRule;
+exports.upsertScanRule = upsertScanRule;
+exports.deleteScanRule = deleteScanRule;
+const scanCodeService = __importStar(require("../../services/scan-code"));
+// ── Scheme CRUD ────────────────────────────────────────────────────────────
+// Admin gating happens at the transport layer (requireAdmin on routes, admin
+// MCP registration) — same convention as workflow config.
+async function listScanSchemes() {
+    try {
+        const schemes = await scanCodeService.listScanSchemes();
+        return { status: 200, data: { schemes } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+async function getScanScheme(input) {
+    try {
+        const scheme = await scanCodeService.getScanScheme(input.version);
+        if (!scheme)
+            return { status: 404, error: `No scan scheme for version ${input.version}` };
+        const rules = await scanCodeService.listScanRules(input.version);
+        return { status: 200, data: { scheme, rules } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+async function upsertScanScheme(input) {
+    try {
+        const scheme = await scanCodeService.upsertScanScheme(input);
+        return { status: 200, data: { scheme } };
+    }
+    catch (err) {
+        // Write-time invariant violations are caller errors, not server faults.
+        return { status: 400, error: err.message };
+    }
+}
+async function deleteScanScheme(input) {
+    try {
+        const deleted = await scanCodeService.deleteScanScheme(input.version);
+        if (!deleted)
+            return { status: 404, error: `No scan scheme for version ${input.version}` };
+        return { status: 200, data: { deleted: true } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+// ── Rule CRUD ──────────────────────────────────────────────────────────────
+async function listScanRules(input) {
+    try {
+        const rules = await scanCodeService.listScanRules(input.version);
+        return { status: 200, data: { rules } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+async function getScanRule(input) {
+    try {
+        const rule = await scanCodeService.getScanRule(input.version, input.category);
+        if (!rule) {
+            return { status: 404, error: `No scan rule for ${input.version}:${input.category}` };
+        }
+        return { status: 200, data: { rule } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+async function upsertScanRule(input) {
+    try {
+        const scheme = await scanCodeService.getScanScheme(input.scheme_version);
+        if (!scheme) {
+            return { status: 404, error: `No scan scheme for version ${input.scheme_version} — create the scheme first` };
+        }
+        const rule = await scanCodeService.upsertScanRule(input);
+        return { status: 200, data: { rule } };
+    }
+    catch (err) {
+        return { status: 400, error: err.message };
+    }
+}
+async function deleteScanRule(input) {
+    try {
+        const deleted = await scanCodeService.deleteScanRule(input.version, input.category);
+        if (!deleted) {
+            return { status: 404, error: `No scan rule for ${input.version}:${input.category}` };
+        }
+        return { status: 200, data: { deleted: true } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}

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

@@ -0,0 +1,9 @@
+import { type ScanExecuteRequest, type ScanExecuteResponse } from '../../types';
+import type { LTApiAuth, LTApiResult } from '../../types/sdk';
+/**
+ * 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
+ * step that matches nothing falls through to the next. Every terminal state
+ * is a structured 200 outcome — the scan surface reports, it doesn't throw.
+ */
+export declare function executeScanCode(input: ScanExecuteRequest, auth: LTApiAuth): Promise<LTApiResult<ScanExecuteResponse>>;

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

@@ -0,0 +1,372 @@
+"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.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 types_1 = require("../../types");
+/**
+ * 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
+ * step that matches nothing falls through to the next. Every terminal state
+ * is a structured 200 outcome — the scan surface reports, it doesn't throw.
+ */
+async function executeScanCode(input, auth) {
+    try {
+        if (!input.code || typeof input.code !== 'string') {
+            return { status: 400, error: 'code is required' };
+        }
+        // 1. Parse against the configured schemes
+        const schemes = await scanCodeService.listScanSchemes();
+        const parseResult = scanCodeService.parseScanCode(input.code, schemes);
+        if (!parseResult.ok) {
+            const { reason, detail } = parseResult.failure;
+            const outcome = reason === 'unknown_version' || reason === 'scheme_disabled'
+                ? types_1.SCAN_OUTCOMES.UNCONFIGURED
+                : types_1.SCAN_OUTCOMES.INVALID_CODE;
+            return { status: 200, data: { outcome, error: detail } };
+        }
+        const { parsed, scheme } = parseResult;
+        // 2. Load the rule for this category
+        const rule = await scanCodeService.getScanRule(parsed.version, parsed.category);
+        if (!rule || !rule.enabled) {
+            return {
+                status: 200,
+                data: {
+                    outcome: types_1.SCAN_OUTCOMES.UNCONFIGURED,
+                    parsed,
+                    error: `no scan rule configured for ${parsed.version}:${parsed.category}`,
+                },
+            };
+        }
+        // 3. Walk the steps — first condition match wins
+        const ctx = {
+            scheme, rule, parsed, scannedAt: new Date().toISOString(), auth,
+        };
+        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);
+        }
+        // 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),
+        };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/** Stamp rule identity + parsed code onto a step result. */
+function decorate(result, ctx, stepIndex) {
+    if (result.data && typeof result.data === 'object' && 'outcome' in result.data) {
+        result.data = { ...decorateData(result.data, ctx), stepIndex };
+    }
+    return result;
+}
+function decorateData(data, ctx) {
+    return {
+        ...data,
+        parsed: ctx.parsed,
+        rule: {
+            schemeVersion: ctx.rule.scheme_version,
+            category: ctx.rule.category,
+            name: ctx.rule.name,
+        },
+    };
+}
+/**
+ * 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) {
+    // 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);
+    }
+    switch (step.verb) {
+        case types_1.SCAN_VERBS.CLAIM:
+        case types_1.SCAN_VERBS.CLAIM_SHOW_DETAIL:
+            return claimStep(step, ctx);
+        case types_1.SCAN_VERBS.RESOLVE:
+            return resolveStep(step, ctx);
+        case types_1.SCAN_VERBS.ESCALATE:
+            return escalateStep(step, ctx);
+        case types_1.SCAN_VERBS.RELEASE:
+            return releaseStep(step, ctx);
+        case types_1.SCAN_VERBS.CANCEL:
+            return 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/index.d.ts

@@ -0,0 +1,2 @@
+export { executeScanCode } from './execute';
+export { listScanSchemes, getScanScheme, upsertScanScheme, deleteScanScheme, listScanRules, getScanRule, upsertScanRule, deleteScanRule, } from './config';