@hotmeshio/long-tail 0.17.2 → 0.18.0

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

@@ -5,6 +5,7 @@ export { getEscalationLookups } from './lookups';
 export { claimEscalation, releaseEscalation } from './claim';
 export { releaseExpiredClaims, updatePriority, bulkClaim, bulkAssign, bulkUnassign, bulkEscalate, bulkTriage } from './bulk';
 export { resolveEscalation, resolveBySignalKey, resolveByIds, resolveAllOrNone } from './resolve';
+export { resolveBatchItem, resolveBatchItemBySignalKey, resolveBatchItemByMetadata } from './resolve-batch';
 export { findByMetadata, claimByMetadata, resolveByMetadata } from './metadata';
 export { cancelSingleEscalation, bulkCancel } from './cancel';
 export { searchByFacets, claimGroups, claimByFacets } from './facets';

package/build/api/escalations/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.timelineByFacet = exports.aggregateByFacets = exports.claimByFacets = exports.claimGroups = exports.searchByFacets = exports.bulkCancel = exports.cancelSingleEscalation = exports.resolveByMetadata = exports.claimByMetadata = exports.findByMetadata = exports.resolveAllOrNone = exports.resolveByIds = exports.resolveBySignalKey = exports.resolveEscalation = exports.bulkTriage = exports.bulkEscalate = exports.bulkUnassign = exports.bulkAssign = exports.bulkClaim = exports.updatePriority = exports.releaseExpiredClaims = exports.releaseEscalation = exports.claimEscalation = exports.getEscalationLookups = exports.escalateToRole = exports.getEscalationsByWorkflowId = exports.getEscalation = exports.getStationMetrics = exports.getEscalationStats = exports.listFacetKeys = exports.listDistinctTypes = exports.listAvailableEscalations = exports.listEscalations = exports.createEscalation = void 0;
+exports.timelineByFacet = exports.aggregateByFacets = exports.claimByFacets = exports.claimGroups = exports.searchByFacets = exports.bulkCancel = exports.cancelSingleEscalation = exports.resolveByMetadata = exports.claimByMetadata = exports.findByMetadata = exports.resolveBatchItemByMetadata = exports.resolveBatchItemBySignalKey = exports.resolveBatchItem = exports.resolveAllOrNone = exports.resolveByIds = exports.resolveBySignalKey = exports.resolveEscalation = exports.bulkTriage = exports.bulkEscalate = exports.bulkUnassign = exports.bulkAssign = exports.bulkClaim = exports.updatePriority = exports.releaseExpiredClaims = exports.releaseEscalation = exports.claimEscalation = exports.getEscalationLookups = exports.escalateToRole = exports.getEscalationsByWorkflowId = exports.getEscalation = exports.getStationMetrics = exports.getEscalationStats = exports.listFacetKeys = exports.listDistinctTypes = exports.listAvailableEscalations = exports.listEscalations = exports.createEscalation = void 0;
 var create_1 = require("./create");
 Object.defineProperty(exports, "createEscalation", { enumerable: true, get: function () { return create_1.createEscalation; } });
 var list_1 = require("./list");
@@ -32,6 +32,10 @@ Object.defineProperty(exports, "resolveEscalation", { enumerable: true, get: fun
 Object.defineProperty(exports, "resolveBySignalKey", { enumerable: true, get: function () { return resolve_1.resolveBySignalKey; } });
 Object.defineProperty(exports, "resolveByIds", { enumerable: true, get: function () { return resolve_1.resolveByIds; } });
 Object.defineProperty(exports, "resolveAllOrNone", { enumerable: true, get: function () { return resolve_1.resolveAllOrNone; } });
+var resolve_batch_1 = require("./resolve-batch");
+Object.defineProperty(exports, "resolveBatchItem", { enumerable: true, get: function () { return resolve_batch_1.resolveBatchItem; } });
+Object.defineProperty(exports, "resolveBatchItemBySignalKey", { enumerable: true, get: function () { return resolve_batch_1.resolveBatchItemBySignalKey; } });
+Object.defineProperty(exports, "resolveBatchItemByMetadata", { enumerable: true, get: function () { return resolve_batch_1.resolveBatchItemByMetadata; } });
 var metadata_1 = require("./metadata");
 Object.defineProperty(exports, "findByMetadata", { enumerable: true, get: function () { return metadata_1.findByMetadata; } });
 Object.defineProperty(exports, "claimByMetadata", { enumerable: true, get: function () { return metadata_1.claimByMetadata; } });

package/build/api/escalations/resolve-batch.d.ts

@@ -0,0 +1,58 @@
+import type { LTApiAuth, LTApiResult } from '../../types/sdk';
+/**
+ * Submit ONE declared item of a batch escalation (a `conditional` wait created
+ * with `batch: [...]`). Interim submissions are cheap atomic fills — the row
+ * stays pending and `remaining` reports progress. The LAST item completes the
+ * escalation: the row resolves and the waiting workflow wakes with the full
+ * collection, in the same statement.
+ *
+ * Each item validates against the SAME versioned form schema a single-item
+ * resolver gets (metadata.form_schema → pinned lt_role_schemas → live role
+ * schema), including the submit guard.
+ *
+ * Claim semantics: claim-agnostic by default — a batch accumulates
+ * contributions from multiple principals, so the single-owner claim lock is
+ * not asserted (same rationale as resolve-by-signal-key). Pass
+ * `assertClaim: true` to require the caller's own live claim, asserted
+ * atomically inside the SDK's guarded statement.
+ */
+export declare function resolveBatchItem(input: {
+    id: string;
+    itemKey: string;
+    resolverPayload: Record<string, any>;
+    metadata?: Record<string, any>;
+    assertClaim?: boolean;
+}, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Submit one batch item selecting the escalation by its `signal_key` — the
+ * deterministic home signal id the waiting workflow parked on. For callers
+ * that already own that identity (a child workflow calling home, a webhook),
+ * so no UUID lookup and no facet duplication. Mirrors resolve-by-signal-key:
+ * claim-agnostic, write-scope gated with 404 non-disclosure.
+ */
+export declare function resolveBatchItemBySignalKey(input: {
+    signalKey: string;
+    itemKey: string;
+    resolverPayload: Record<string, any>;
+    metadata?: Record<string, any>;
+}, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Submit one batch item selecting the escalation by metadata facet — the
+ * faceted sibling of {@link resolveBatchItem}, mirroring resolve-by-metadata.
+ * RBAC folds into the SDK's atomic facet selection as a flat role filter
+ * (write_all roles; self-scope members act on their items by id).
+ *
+ * Schema enforcement is two-phase when enforcing roles exist: the item's
+ * schema is a function of the SELECTED row's role and version pin, so the row
+ * is picked first (scoped, priority-ordered), validated, then filled by
+ * asserted id — the SDK statement re-checks pending/batch state atomically,
+ * and a row that went terminal between phases surfaces as a 409.
+ */
+export declare function resolveBatchItemByMetadata(input: {
+    key: string;
+    value: string;
+    itemKey: string;
+    resolverPayload: Record<string, any>;
+    metadata?: Record<string, any>;
+    restrictRoles?: string[];
+}, auth: LTApiAuth): Promise<LTApiResult>;

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

@@ -0,0 +1,247 @@
+"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.resolveBatchItem = resolveBatchItem;
+exports.resolveBatchItemBySignalKey = resolveBatchItemBySignalKey;
+exports.resolveBatchItemByMetadata = resolveBatchItemByMetadata;
+const escalationService = __importStar(require("../../services/escalation"));
+const resolver_validation_1 = require("../../services/escalation/resolver-validation");
+const enforcement_cache_1 = require("../../services/role/enforcement-cache");
+const escalation_1 = require("../../types/escalation");
+const helpers_1 = require("./helpers");
+const resolve_1 = require("./resolve");
+const metadata_1 = require("./metadata");
+/**
+ * Submit ONE declared item of a batch escalation (a `conditional` wait created
+ * with `batch: [...]`). Interim submissions are cheap atomic fills — the row
+ * stays pending and `remaining` reports progress. The LAST item completes the
+ * escalation: the row resolves and the waiting workflow wakes with the full
+ * collection, in the same statement.
+ *
+ * Each item validates against the SAME versioned form schema a single-item
+ * resolver gets (metadata.form_schema → pinned lt_role_schemas → live role
+ * schema), including the submit guard.
+ *
+ * Claim semantics: claim-agnostic by default — a batch accumulates
+ * contributions from multiple principals, so the single-owner claim lock is
+ * not asserted (same rationale as resolve-by-signal-key). Pass
+ * `assertClaim: true` to require the caller's own live claim, asserted
+ * atomically inside the SDK's guarded statement.
+ */
+async function resolveBatchItem(input, auth) {
+    try {
+        const { id, itemKey, resolverPayload, metadata } = input;
+        if (!itemKey)
+            return { status: 400, error: 'itemKey is required' };
+        if (!resolverPayload)
+            return { status: 400, error: 'resolverPayload is required' };
+        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' };
+        // 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];
+        if (!Array.isArray(pending)) {
+            return { status: 400, error: 'Escalation is not a batch' };
+        }
+        // Hybrid RBAC, identical to single-resolve: non-disclosure 404 for rows the
+        // caller cannot see; informative 403 for rows they see but cannot act on.
+        if (await (0, helpers_1.assertReadAccess)(auth.userId, escalation)) {
+            return { status: 404, error: 'Escalation not found' };
+        }
+        const denied = await (0, helpers_1.assertWriteAccess)(auth.userId, escalation);
+        if (denied)
+            return denied;
+        // Per-item schema enforcement — the exact validation path single-resolve
+        // runs, against the row's pinned schema version.
+        const violation = await (0, resolver_validation_1.checkResolverPayload)(escalation, resolverPayload, undefined, auth.userId);
+        if (violation)
+            return (0, resolve_1.validationFailure)(violation);
+        const redacted = await (0, resolve_1.redactPasswords)(resolverPayload, escalation.metadata?.form_schema);
+        // resolved_by merges on every fill; the completing fill's stamp is the
+        // resolution provenance, matching single-resolve. $resolution rides the
+        // completing item's signal only.
+        const result = await escalationService.resolveBatchItem(escalation.id, itemKey, redacted, { ...metadata, resolved_by: auth.userId }, input.assertClaim ? auth.userId : undefined, await (0, resolve_1.resolverIdentity)(auth));
+        return batchOutcomeResult(result, itemKey, escalation.workflow_id);
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Submit one batch item selecting the escalation by its `signal_key` — the
+ * deterministic home signal id the waiting workflow parked on. For callers
+ * that already own that identity (a child workflow calling home, a webhook),
+ * so no UUID lookup and no facet duplication. Mirrors resolve-by-signal-key:
+ * claim-agnostic, write-scope gated with 404 non-disclosure.
+ */
+async function resolveBatchItemBySignalKey(input, auth) {
+    try {
+        const { signalKey, itemKey, resolverPayload, metadata } = input;
+        if (!signalKey)
+            return { status: 400, error: 'signalKey is required' };
+        if (!itemKey)
+            return { status: 400, error: 'itemKey is required' };
+        if (!resolverPayload)
+            return { status: 400, error: 'resolverPayload is required' };
+        const escalation = await escalationService.getEscalationBySignalKey(signalKey);
+        if (!escalation)
+            return { status: 404, error: 'Escalation not found' };
+        if (escalation.status !== 'pending')
+            return { status: 409, error: 'Escalation not available for resolution' };
+        const pending = escalation.metadata?.[escalation_1.ESCALATION_BATCH_KEYS.PENDING];
+        if (!Array.isArray(pending)) {
+            return { status: 400, error: 'Escalation is not a batch' };
+        }
+        // Write verb on a system ingress surface — scope-gate with non-disclosure.
+        const denied = await (0, helpers_1.assertWriteAccess)(auth.userId, escalation);
+        if (denied)
+            return { status: 404, error: 'Escalation not found' };
+        const violation = await (0, resolver_validation_1.checkResolverPayload)(escalation, resolverPayload, undefined, auth.userId);
+        if (violation)
+            return (0, resolve_1.validationFailure)(violation);
+        const redacted = await (0, resolve_1.redactPasswords)(resolverPayload, escalation.metadata?.form_schema);
+        const result = await escalationService.resolveBatchItemBySignalKey(signalKey, itemKey, redacted, { ...metadata, resolved_by: auth.userId }, await (0, resolve_1.resolverIdentity)(auth));
+        return batchOutcomeResult(result, itemKey, escalation.workflow_id);
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Submit one batch item selecting the escalation by metadata facet — the
+ * faceted sibling of {@link resolveBatchItem}, mirroring resolve-by-metadata.
+ * RBAC folds into the SDK's atomic facet selection as a flat role filter
+ * (write_all roles; self-scope members act on their items by id).
+ *
+ * Schema enforcement is two-phase when enforcing roles exist: the item's
+ * schema is a function of the SELECTED row's role and version pin, so the row
+ * is picked first (scoped, priority-ordered), validated, then filled by
+ * asserted id — the SDK statement re-checks pending/batch state atomically,
+ * and a row that went terminal between phases surfaces as a 409.
+ */
+async function resolveBatchItemByMetadata(input, auth) {
+    try {
+        const { key, value, itemKey, resolverPayload, metadata } = input;
+        if (!key || !value)
+            return { status: 400, error: 'key and value are required' };
+        if (!itemKey)
+            return { status: 400, error: 'itemKey is required' };
+        if (!resolverPayload)
+            return { status: 400, error: 'resolverPayload is required' };
+        const writeScope = await (0, helpers_1.getEscalationWriteScope)(auth.userId);
+        const allowedRoles = (0, metadata_1.restrictScopeRoles)(writeScope.allRoles, writeScope.global, input.restrictRoles);
+        const resolvedBy = await (0, resolve_1.resolverIdentity)(auth);
+        const outcome = { ...metadata, resolved_by: auth.userId };
+        const enforcing = await (0, enforcement_cache_1.getEnforcingRoles)();
+        if (enforcing.size === 0) {
+            // Single atomic call — selection, fill, and (on the last item) the
+            // resolve + wake all inside the SDK statement.
+            const result = await escalationService.resolveBatchItemByMetadata(key, value, itemKey, resolverPayload, allowedRoles ?? undefined, outcome, resolvedBy);
+            return batchOutcomeResult(result, itemKey, result.escalation?.workflow_id ?? null);
+        }
+        // Phase 1: pick the row the fill would target (scoped, priority-ordered)
+        // and validate against ITS schema when its role enforces. The role
+        // restriction folds into the scoped query — never a client-side filter.
+        const found = await escalationService.findByMetadata(key, value, 'pending', 1, 0, allowedRoles === null ? undefined : { allRoles: allowedRoles, meUserId: auth.userId });
+        const row = found.escalations[0];
+        if (!row)
+            return { status: 404, error: 'No pending escalation found for this metadata' };
+        if (enforcing.has(row.role)) {
+            const report = await (0, resolver_validation_1.checkResolverPayload)(row, resolverPayload, undefined, auth.userId);
+            if (report)
+                return (0, resolve_1.validationFailure)(report);
+        }
+        // Phase 2: fill by asserted id. The SDK statement re-checks pending +
+        // batch state; a row that went terminal between phases maps to 409.
+        const redacted = await (0, resolve_1.redactPasswords)(resolverPayload, row.metadata?.form_schema);
+        const result = await escalationService.resolveBatchItem(row.id, itemKey, redacted, outcome, undefined, resolvedBy);
+        if (result.outcome === 'not-found') {
+            return { status: 409, error: 'A concurrent resolution is already in progress for this escalation' };
+        }
+        return batchOutcomeResult(result, itemKey, row.workflow_id);
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/** Maps the SDK batch outcome vocabulary onto HTTP results. */
+function batchOutcomeResult(result, itemKey, workflowId) {
+    switch (result.outcome) {
+        case 'completed':
+            return {
+                status: 200,
+                data: {
+                    outcome: 'completed',
+                    remaining: 0,
+                    signaled: !!result.escalation?.signal_key,
+                    escalationId: result.escalation?.id,
+                    workflowId,
+                },
+            };
+        case 'accepted':
+            return {
+                status: 200,
+                data: {
+                    outcome: 'accepted',
+                    remaining: result.remaining,
+                    escalationId: result.escalation?.id,
+                },
+            };
+        case 'duplicate-item':
+            return {
+                status: 409,
+                error: 'Batch item already submitted',
+                data: { error: 'Batch item already submitted', itemKey },
+            };
+        case 'claimed-by-other':
+            return { status: 409, error: 'Escalation is claimed by another user' };
+        case 'claim-expired':
+            return { status: 409, error: 'Your claim has expired — re-claim this escalation to resolve it' };
+        case 'not-found':
+            return { status: 404, error: 'Escalation not found' };
+        case 'unknown-item':
+            return { status: 400, error: 'itemKey is not in the declared batch' };
+        case 'not-batch':
+            return { status: 400, error: 'Escalation is not a batch' };
+        default:
+            // already-resolved / already-cancelled / already-expired
+            return { status: 409, error: 'Escalation not available for resolution' };
+    }
+}

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

@@ -73,6 +73,15 @@ export declare function resolveAllOrNone(input: {
     metadata?: Record<string, any>;
     requireClaimed?: boolean;
 }, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * The resolving principal's identity for `$resolution` delivery. The email is
+ * best-effort (one indexed read, tolerated failure) — the id alone satisfies
+ * the provenance contract.
+ */
+export declare function resolverIdentity(auth: LTApiAuth): Promise<{
+    id: string;
+    email?: string;
+}>;
 /**
  * The canonical 422 for a schema-validation rejection. The full body rides in
  * `data` (routes serialize `data ?? { error }`), so every transport — HTTP,
@@ -80,3 +89,5 @@ export declare function resolveAllOrNone(input: {
  * role, schemaVersion. `code` also sits on the envelope for SDK branching.
  */
 export declare function validationFailure(report: ResolverSchemaViolationReport): LTApiResult;
+/** Replace password fields with ephemeral tokens so plaintext never enters the signal store. */
+export declare function redactPasswords(payload: Record<string, any>, formSchema: any): Promise<Record<string, any>>;

package/build/api/escalations/resolve.js

@@ -37,7 +37,9 @@ exports.resolveEscalation = resolveEscalation;
 exports.resolveBySignalKey = resolveBySignalKey;
 exports.resolveByIds = resolveByIds;
 exports.resolveAllOrNone = resolveAllOrNone;
+exports.resolverIdentity = resolverIdentity;
 exports.validationFailure = validationFailure;
+exports.redactPasswords = redactPasswords;
 const escalationService = __importStar(require("../../services/escalation"));
 const userService = __importStar(require("../../services/user"));
 const taskService = __importStar(require("../../services/task"));

package/build/lib/events/publish.d.ts

@@ -40,7 +40,7 @@ export declare function publishTaskEvent(params: {
  * role hops (`system.escalation.*.{id}.>`).
  */
 export declare function publishEscalationEvent(params: {
-    type: 'escalation.created' | 'escalation.resolved' | 'escalation.claimed' | 'escalation.released' | 'escalation.cancelled' | 'escalation.reassigned';
+    type: 'escalation.created' | 'escalation.resolved' | 'escalation.claimed' | 'escalation.released' | 'escalation.cancelled' | 'escalation.reassigned' | 'escalation.updated';
     source: string;
     workflowId: string;
     workflowName: string;

package/build/routes/escalations/metadata.js

@@ -86,4 +86,23 @@ function registerMetadataRoutes(router) {
         }, req.auth);
         res.status(result.status).json(result.data ?? { error: result.error });
     });
+    /**
+     * POST /api/escalations/resolve-batch-item-by-metadata
+     * Submit one declared item of a batch escalation selected by metadata facet.
+     * Interim items return { outcome: 'accepted', remaining }; the LAST item
+     * completes the escalation and wakes the waiting workflow with the full
+     * collection.
+     * Body: { key, value, itemKey, resolverPayload, metadata?, restrictRoles? }
+     */
+    router.post('/resolve-batch-item-by-metadata', async (req, res) => {
+        const result = await api.resolveBatchItemByMetadata({
+            key: req.body?.key,
+            value: req.body?.value,
+            itemKey: req.body?.itemKey,
+            resolverPayload: req.body?.resolverPayload,
+            metadata: req.body?.metadata,
+            restrictRoles: req.body?.restrictRoles,
+        }, req.auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
 }

package/build/routes/escalations/resolve.js

@@ -85,6 +85,47 @@ function registerResolveRoutes(router) {
         }, req.auth);
         res.status(result.status).json(result.data ?? { error: result.error });
     });
+    /**
+     * POST /api/escalations/resolve-batch-item-by-signal-key
+     * Submit ONE declared item of a batch escalation by its signal_key — the
+     * deterministic home signal id the waiting workflow parked on. For callers
+     * that already own that identity (a child calling home, a webhook).
+     * Literal single-segment path — registered before /:id routes.
+     * Body: { signalKey: string, itemKey: string, resolverPayload: Record<string, any>,
+     *         metadata?: Record<string, any> }
+     */
+    router.post('/resolve-batch-item-by-signal-key', async (req, res) => {
+        const result = await api.resolveBatchItemBySignalKey({
+            signalKey: req.body?.signalKey,
+            itemKey: req.body?.itemKey,
+            resolverPayload: req.body?.resolverPayload,
+            metadata: req.body?.metadata,
+        }, req.auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
+    /**
+     * POST /api/escalations/:id/resolve-batch-item
+     * Submit ONE declared item of a batch escalation. Interim items return
+     * { outcome: 'accepted', remaining }; the LAST item completes the
+     * escalation and wakes the waiting workflow with the full collection.
+     * Claim-agnostic by default; assertClaim: true requires the caller's own
+     * live claim, asserted atomically.
+     * Body: { itemKey: string, resolverPayload: Record<string, any>,
+     *         metadata?: Record<string, any>, assertClaim?: boolean }
+     */
+    router.post('/:id/resolve-batch-item', async (req, res) => {
+        const auth = await (0, acting_1.effectiveWorkAuth)(req, res);
+        if (!auth)
+            return;
+        const result = await api.resolveBatchItem({
+            id: req.params.id,
+            itemKey: req.body?.itemKey,
+            resolverPayload: req.body?.resolverPayload,
+            metadata: req.body?.metadata,
+            assertClaim: req.body?.assertClaim,
+        }, auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
     /**
      * POST /api/escalations/:id/resolve
      * Resolve a pending escalation with a human-provided payload. Routes by

package/build/sdk/index.d.ts

@@ -222,6 +222,27 @@ export declare function createClient(options?: LTClientOptions): {
             restrictRoles?: string[];
             extraFacets?: Record<string, any>;
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        resolveBatchItem: (input: {
+            id: string;
+            itemKey: string;
+            resolverPayload: Record<string, any>;
+            metadata?: Record<string, any>;
+            assertClaim?: boolean;
+        }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        resolveBatchItemBySignalKey: (input: {
+            signalKey: string;
+            itemKey: string;
+            resolverPayload: Record<string, any>;
+            metadata?: Record<string, any>;
+        }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        resolveBatchItemByMetadata: (input: {
+            key: string;
+            value: string;
+            itemKey: string;
+            resolverPayload: Record<string, any>;
+            metadata?: Record<string, any>;
+            restrictRoles?: string[];
+        }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         searchByFacets: (input: import("..").FacetQuery, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         claimGroups: (input: {
             query: import("..").FacetQuery;

package/build/sdk/index.js

@@ -143,6 +143,9 @@ function createClient(options = {}) {
             findByMetadata: bindAuth(escalationsApi.findByMetadata, auth),
             claimByMetadata: bindAuth(escalationsApi.claimByMetadata, auth),
             resolveByMetadata: bindAuth(escalationsApi.resolveByMetadata, auth),
+            resolveBatchItem: bindAuth(escalationsApi.resolveBatchItem, auth),
+            resolveBatchItemBySignalKey: bindAuth(escalationsApi.resolveBatchItemBySignalKey, auth),
+            resolveBatchItemByMetadata: bindAuth(escalationsApi.resolveBatchItemByMetadata, auth),
             // Faceted-routing surface (pond search + batch claim), RBAC-scoped to the caller's role.
             searchByFacets: bindAuth(escalationsApi.searchByFacets, auth),
             claimGroups: bindAuth(escalationsApi.claimGroups, auth),

package/build/services/escalation/batch.d.ts

@@ -0,0 +1,38 @@
+import type { BatchItemOutcome, LTEscalationRecord } from '../../types';
+export interface ResolveBatchItemOutcome {
+    outcome: BatchItemOutcome;
+    /** Items still awaiting submission after this call (0 exactly when completed). */
+    remaining: number;
+    /** The post-fill row on `completed`/`accepted`; null on every failure outcome. */
+    escalation: LTEscalationRecord | null;
+}
+/**
+ * Fills one declared item of a batch escalation in a single atomic SDK
+ * statement (guarded fill + facet recompute + resolve-and-wake on the last
+ * item). Interim fills publish `escalation.updated` with progress; the
+ * completing fill publishes the standard `escalation.resolved`. Failure
+ * outcomes publish nothing — the row was untouched.
+ */
+export declare function resolveBatchItem(id: string, itemKey: string, payload: Record<string, any>, metadata?: Record<string, any>, assertClaim?: string, resolvedBy?: {
+    id: string;
+    email?: string;
+}): Promise<ResolveBatchItemOutcome>;
+/**
+ * Batch-item fill selecting the row by its `signal_key` — the deterministic
+ * home signal id the parent parked on. For callers that already own that
+ * identity (a child calling home, a webhook), skipping both the UUID lookup
+ * and any facet duplication. Same event contract as {@link resolveBatchItem}.
+ */
+export declare function resolveBatchItemBySignalKey(signalKey: string, itemKey: string, payload: Record<string, any>, metadata?: Record<string, any>, resolvedBy?: {
+    id: string;
+    email?: string;
+}): Promise<ResolveBatchItemOutcome>;
+/**
+ * Batch-item fill selecting the row by metadata facet — the highest-priority
+ * pending row whose metadata contains the key/value, scoped by `roles`.
+ * Same event contract as {@link resolveBatchItem}.
+ */
+export declare function resolveBatchItemByMetadata(key: string, value: unknown, itemKey: string, payload: Record<string, any>, roles?: string[], metadata?: Record<string, any>, resolvedBy?: {
+    id: string;
+    email?: string;
+}): Promise<ResolveBatchItemOutcome>;

package/build/services/escalation/batch.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveBatchItem = resolveBatchItem;
+exports.resolveBatchItemBySignalKey = resolveBatchItemBySignalKey;
+exports.resolveBatchItemByMetadata = resolveBatchItemByMetadata;
+const escalation_wire_1 = require("../../lib/events/escalation-wire");
+const client_1 = require("./client");
+const crud_1 = require("./crud");
+const map_1 = require("./map");
+/**
+ * Fills one declared item of a batch escalation in a single atomic SDK
+ * statement (guarded fill + facet recompute + resolve-and-wake on the last
+ * item). Interim fills publish `escalation.updated` with progress; the
+ * completing fill publishes the standard `escalation.resolved`. Failure
+ * outcomes publish nothing — the row was untouched.
+ */
+async function resolveBatchItem(id, itemKey, payload, metadata, assertClaim, resolvedBy) {
+    const client = await (0, client_1.escalations)();
+    const result = await client.resolveBatchItem({
+        id,
+        itemKey,
+        payload,
+        metadata,
+        assertClaim,
+        resolvedBy,
+    });
+    return settleBatchOutcome(result, itemKey);
+}
+/**
+ * Batch-item fill selecting the row by its `signal_key` — the deterministic
+ * home signal id the parent parked on. For callers that already own that
+ * identity (a child calling home, a webhook), skipping both the UUID lookup
+ * and any facet duplication. Same event contract as {@link resolveBatchItem}.
+ */
+async function resolveBatchItemBySignalKey(signalKey, itemKey, payload, metadata, resolvedBy) {
+    const client = await (0, client_1.escalations)();
+    const result = await client.resolveBatchItem({
+        signalKey,
+        itemKey,
+        payload,
+        metadata,
+        resolvedBy,
+    });
+    return settleBatchOutcome(result, itemKey);
+}
+/**
+ * Batch-item fill selecting the row by metadata facet — the highest-priority
+ * pending row whose metadata contains the key/value, scoped by `roles`.
+ * Same event contract as {@link resolveBatchItem}.
+ */
+async function resolveBatchItemByMetadata(key, value, itemKey, payload, roles, metadata, resolvedBy) {
+    const client = await (0, client_1.escalations)();
+    const result = await client.resolveBatchItemByMetadata({
+        key,
+        value,
+        roles,
+        itemKey,
+        payload,
+        metadata,
+        resolvedBy,
+    });
+    return settleBatchOutcome(result, itemKey);
+}
+function settleBatchOutcome(result, itemKey) {
+    if (!result.ok) {
+        return { outcome: result.outcome, remaining: -1, escalation: null };
+    }
+    const escalation = (0, map_1.toEscalationRecord)(result.entry);
+    const completed = result.outcome === 'completed';
+    (0, crud_1.publishEscalationChange)({
+        type: completed ? 'escalation.resolved' : 'escalation.updated',
+        source: 'service',
+        workflowId: escalation.workflow_id || '',
+        workflowName: escalation.workflow_type || '',
+        taskQueue: escalation.task_queue || '',
+        escalationId: escalation.id,
+        role: escalation.role,
+        status: completed ? 'resolved' : 'pending',
+        data: (0, escalation_wire_1.escalationEventData)(escalation, {
+            item_key: itemKey,
+            remaining: result.remaining,
+        }),
+    });
+    return { outcome: result.outcome, remaining: result.remaining, escalation };
+}

package/build/services/escalation/crud.d.ts

@@ -1,5 +1,12 @@
+import { publishEscalationEvent } from '../../lib/events/publish';
 import type { LTEscalationRecord } from '../../types';
 import type { CreateEscalationInput, ClaimResult } from './types';
+/**
+ * Every escalation write publishes an event AND drops this container's cached
+ * aggregates — the event triggers a dashboard refetch, which must observe the
+ * write rather than a pre-change aggregate held for up to a cache TTL.
+ */
+export declare function publishEscalationChange(...args: Parameters<typeof publishEscalationEvent>): Promise<void>;
 export declare function createEscalation(input: CreateEscalationInput): Promise<LTEscalationRecord>;
 /**
  * Atomic claim. Implicit model — status stays 'pending'; "claimed" is

package/build/services/escalation/crud.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.publishEscalationChange = publishEscalationChange;
 exports.createEscalation = createEscalation;
 exports.claimEscalation = claimEscalation;
 exports.resolveEscalation = resolveEscalation;

package/build/services/escalation/index.d.ts

@@ -1,5 +1,6 @@
 export * from './types';
 export * from './crud';
+export * from './batch';
 export * from './bulk';
 export * from './queries';
 export * from './resolver-validation';