@hotmeshio/long-tail 0.17.2 → 0.18.1

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/api/settings.js

@@ -8,6 +8,7 @@ const socketio_1 = require("../lib/events/socketio");
 const nats_ws_proxy_1 = require("../lib/events/nats-ws-proxy");
 const config_1 = require("../modules/config");
 const features_1 = require("../modules/features");
+const search_1 = require("../modules/search");
 const branding_1 = require("../modules/branding");
 const version_1 = require("../modules/version");
 const sso_1 = require("../modules/sso");
@@ -76,6 +77,7 @@ async function getSettings(req) {
                     enabled: (0, llm_1.hasLLMApiKey)(),
                 },
                 features: (0, features_1.getFeatureFlags)(),
+                search: (0, search_1.getSearchConfig)(),
                 branding: (0, branding_1.getBranding)(),
                 environment: {
                     longTailVersion: version_1.LONG_TAIL_VERSION,

package/build/index.js

@@ -172,6 +172,12 @@ async function main() {
             // The examples ship the full scan demo (schemes 10/11); surface it.
             scanCodes: true,
         },
+        search: {
+            // The examples surface the global search bar with the seed data's
+            // primary facet; escalationId/workflowId are always present.
+            enabled: true,
+            facets: ['orderId'],
+        },
         mcp: {
             server: { enabled: true },
         },

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

@@ -0,0 +1,21 @@
+/**
+ * Global search bar configuration surfaced to the dashboard via /api/settings.
+ *
+ * Opt-in (default off). `facets` lists the metadata facet names the search
+ * picklist offers; the dashboard prepends `escalationId` and `workflowId`
+ * unconditionally (long-tail-owned lookups), so `facets` is only the
+ * deployment's domain vocabulary. Configure through the `search` block of the
+ * `start()` config, or by env (`LT_SEARCH_BAR`, `LT_SEARCH_FACETS` csv) —
+ * env wins when set, so a deployment can flip the bar without a code change.
+ */
+export interface SearchConfig {
+    enabled: boolean;
+    facets: string[];
+}
+/**
+ * Apply the start-config block, then the env overrides. Called once at boot;
+ * callable again in tests.
+ */
+export declare function configureSearch(patch?: Partial<SearchConfig>): void;
+/** The resolved search configuration reported to the dashboard. */
+export declare function getSearchConfig(): SearchConfig;

package/build/modules/search.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * Global search bar configuration surfaced to the dashboard via /api/settings.
+ *
+ * Opt-in (default off). `facets` lists the metadata facet names the search
+ * picklist offers; the dashboard prepends `escalationId` and `workflowId`
+ * unconditionally (long-tail-owned lookups), so `facets` is only the
+ * deployment's domain vocabulary. Configure through the `search` block of the
+ * `start()` config, or by env (`LT_SEARCH_BAR`, `LT_SEARCH_FACETS` csv) —
+ * env wins when set, so a deployment can flip the bar without a code change.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configureSearch = configureSearch;
+exports.getSearchConfig = getSearchConfig;
+// Mirrors the facet-key rule enforced by the faceted-query surface.
+const FACET_KEY = /^[a-zA-Z0-9_]+$/;
+const DEFAULTS = { enabled: false, facets: [] };
+let search = { ...DEFAULTS };
+function sanitizeFacets(names) {
+    if (!Array.isArray(names))
+        return [];
+    const out = [];
+    for (const n of names) {
+        if (typeof n !== 'string')
+            continue;
+        const trimmed = n.trim();
+        if (!FACET_KEY.test(trimmed)) {
+            console.warn(`[lt-search] dropping invalid search facet name: '${trimmed}'`);
+            continue;
+        }
+        if (!out.includes(trimmed))
+            out.push(trimmed);
+    }
+    return out;
+}
+/**
+ * Apply the start-config block, then the env overrides. Called once at boot;
+ * callable again in tests.
+ */
+function configureSearch(patch) {
+    search = {
+        enabled: patch?.enabled ?? DEFAULTS.enabled,
+        facets: sanitizeFacets(patch?.facets ?? DEFAULTS.facets),
+    };
+    const envEnabled = process.env.LT_SEARCH_BAR;
+    if (envEnabled !== undefined)
+        search.enabled = envEnabled === 'true';
+    const envFacets = process.env.LT_SEARCH_FACETS;
+    if (envFacets !== undefined)
+        search.facets = sanitizeFacets(envFacets.split(','));
+}
+/** The resolved search configuration reported to the dashboard. */
+function getSearchConfig() {
+    return { enabled: search.enabled, facets: [...search.facets] };
+}

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>;