@hotmeshio/long-tail 0.10.6 → 0.10.7

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

@@ -33,19 +33,31 @@ export declare function bulkClaim(input: {
     durationMinutes?: number;
 }, auth: LTApiAuth): Promise<LTApiResult>;
 /**
- * Assign multiple escalations to a specific user.
+ * Assign multiple escalations to a specific user — by id-set OR by query
+ * (exactly one).
+ *
+ * The query form (`{ role, facets? }`) is one atomic statement: selection and
+ * claim happen in the same UPDATE, so a row that re-parks between a search and
+ * an ids-assign is still captured. Use it whenever the population is
+ * describable by filter (e.g. a walk's plates by `walkId` facet).
  *
  * Non-superadmin callers must verify the target user holds each
- * escalation's role. Publishes claim events for assigned items.
+ * escalation's role (the query form requires exactly the declared role).
+ * Publishes claim events for assigned items.
  *
- * @param input.ids — array of escalation UUIDs
+ * @param input.ids — array of escalation UUIDs (ids form)
+ * @param input.query — `{ role, facets? }` selector (query form)
  * @param input.targetUserId — user to assign to
  * @param input.durationMinutes — assignment duration (default: 30)
  * @param auth — authenticated user context
  * @returns `{ status: 200, data: { assigned, skipped } }`
  */
 export declare function bulkAssign(input: {
-    ids: string[];
+    ids?: string[];
+    query?: {
+        role: string;
+        facets?: Record<string, unknown>;
+    };
     targetUserId: string;
     durationMinutes?: number;
 }, auth: LTApiAuth): Promise<LTApiResult>;

package/build/api/escalations/bulk.js

@@ -117,12 +117,20 @@ async function bulkClaim(input, auth) {
     }
 }
 /**
- * Assign multiple escalations to a specific user.
+ * Assign multiple escalations to a specific user — by id-set OR by query
+ * (exactly one).
+ *
+ * The query form (`{ role, facets? }`) is one atomic statement: selection and
+ * claim happen in the same UPDATE, so a row that re-parks between a search and
+ * an ids-assign is still captured. Use it whenever the population is
+ * describable by filter (e.g. a walk's plates by `walkId` facet).
  *
  * Non-superadmin callers must verify the target user holds each
- * escalation's role. Publishes claim events for assigned items.
+ * escalation's role (the query form requires exactly the declared role).
+ * Publishes claim events for assigned items.
  *
- * @param input.ids — array of escalation UUIDs
+ * @param input.ids — array of escalation UUIDs (ids form)
+ * @param input.query — `{ role, facets? }` selector (query form)
  * @param input.targetUserId — user to assign to
  * @param input.durationMinutes — assignment duration (default: 30)
  * @param auth — authenticated user context
@@ -130,13 +138,40 @@ async function bulkClaim(input, auth) {
  */
 async function bulkAssign(input, auth) {
     try {
-        const { ids, targetUserId, durationMinutes } = input;
-        if (!(0, helpers_1.validateIds)(ids)) {
-            return { status: 400, error: 'ids must be a non-empty array' };
-        }
+        const { ids, query, targetUserId, durationMinutes } = input;
         if (!targetUserId || typeof targetUserId !== 'string') {
             return { status: 400, error: 'targetUserId is required' };
         }
+        const hasIds = Array.isArray(ids) && ids.length > 0;
+        const hasQuery = !!query && typeof query === 'object';
+        if (hasIds === hasQuery) {
+            return { status: 400, error: 'provide exactly one of ids or query' };
+        }
+        if (hasQuery) {
+            if (!query.role || typeof query.role !== 'string') {
+                return { status: 400, error: 'query.role is required' };
+            }
+            // RBAC, query form: the caller must hold the queried role (or global),
+            // and the target user must hold it — one role check instead of per-id.
+            const hasGlobal = await (0, helpers_1.hasGlobalEscalationAccess)(auth.userId);
+            if (!hasGlobal) {
+                const callerHasRole = await userService.hasRole(auth.userId, query.role);
+                if (!callerHasRole) {
+                    return { status: 404, error: 'One or more escalations not found' };
+                }
+                const targetHasRole = await userService.hasRole(targetUserId, query.role);
+                if (!targetHasRole) {
+                    return { status: 400, error: `Target user does not hold the "${query.role}" role` };
+                }
+            }
+            const result = await escalationService.bulkAssignEscalationsByQuery({ role: query.role, facets: query.facets }, targetUserId, durationMinutes ?? 30);
+            if (result.assigned > 0)
+                (0, helpers_1.publishBulkClaimEvents)(result.ids, targetUserId);
+            return { status: 200, data: { assigned: result.assigned, skipped: 0 } };
+        }
+        if (!(0, helpers_1.validateIds)(ids)) {
+            return { status: 400, error: 'ids must be a non-empty array' };
+        }
         const perm = await (0, helpers_1.checkBulkPermission)(auth.userId, ids);
         if (!perm.allowed)
             return perm;

package/build/api/escalations/resolve.js

@@ -39,6 +39,7 @@ exports.resolveByIds = resolveByIds;
 exports.resolveAllOrNone = resolveAllOrNone;
 exports.validationFailure = validationFailure;
 const escalationService = __importStar(require("../../services/escalation"));
+const userService = __importStar(require("../../services/user"));
 const taskService = __importStar(require("../../services/task"));
 const escalation_strategy_1 = require("../../services/escalation-strategy");
 const ephemeral_1 = require("../../services/iam/ephemeral");
@@ -103,7 +104,14 @@ async function resolveEscalation(input, auth) {
         // The resolver payload is stored exactly as submitted — its shape is the
         // workflow's contract, formed by the caller (the React app maps the form to
         // the payload via x-lt-bind before submitting). No server-side transform.
-        // `metadata` (the outcome patch) is never written separately — it rides WITH the
+        // Resolution provenance, both surfaces at once: `resolvedBy` rides the
+        // signal to the waiting workflow ($resolution — see conditionLT), and
+        // `resolved_by` merges into the row's GIN-indexed metadata inside the same
+        // atomic resolve, making "who resolved it" `@>`-queryable without a
+        // follow-up read.
+        const resolvedBy = await resolverIdentity(auth);
+        const outcome = { ...metadata, resolved_by: auth.userId };
+        // `outcome` (the outcome patch) is never written separately — it rides WITH the
         // resolverPayload to whichever path performs the resolve, so it merges inside the
         // single status='pending'-guarded UPDATE (HotMesh `resolve(metadata)`). Paths that
         // resolve here pass it as the 3rd arg; paths that resume a workflow carry it on the
@@ -111,19 +119,19 @@ async function resolveEscalation(input, auth) {
         // Path A: conditionLT signal
         const metadataSignalId = escalation.metadata?.signal_id;
         if (metadataSignalId && escalation.workflow_id && escalation.task_queue && escalation.workflow_type) {
-            return resolveViaConditionSignal(escalation, resolverPayload, metadata);
+            return resolveViaConditionSignal(escalation, resolverPayload, outcome, resolvedBy);
         }
         // Path B: waitFor signal routing
         const signalRouting = escalation.metadata?.signal_routing;
         if (signalRouting?.signalId) {
-            return resolveViaSignalRouting(escalation, resolverPayload, metadata);
+            return resolveViaSignalRouting(escalation, resolverPayload, outcome, resolvedBy);
         }
         // Path 0: efficient (atomic) escalation — signal_key resumes in place.
         // The row was written inside the workflow's Leg1 checkpoint via
         // `condition(signalId, config)`. The SDK's resolve marks it resolved AND
         // delivers the signal to `signal_key`, resuming THIS job — no re-run.
         if (escalation.signal_key) {
-            return resolveViaSignalKey(escalation, resolverPayload, metadata, auth.userId);
+            return resolveViaSignalKey(escalation, resolverPayload, outcome, auth.userId, resolvedBy);
         }
         // Path C: escalation strategy may redirect to triage
         const envelope = await reconstructEnvelope(escalation);
@@ -131,19 +139,19 @@ async function resolveEscalation(input, auth) {
         if (strategy) {
             const directive = await strategy.onResolution({ escalation, resolverPayload, envelope });
             if (directive.action === 'triage') {
-                return resolveViaTriage(escalation, resolverPayload, directive.triageEnvelope, metadata);
+                return resolveViaTriage(escalation, resolverPayload, directive.triageEnvelope, outcome);
             }
         }
         // Path D: notification-only — no workflow to restart. One atomic resolve.
         if (!escalation.workflow_type || !escalation.task_queue) {
-            const resolved = await escalationService.resolveEscalation(escalation.id, resolverPayload, metadata, auth.userId);
+            const resolved = await escalationService.resolveEscalation(escalation.id, resolverPayload, outcome, auth.userId);
             if (!resolved) {
                 return { status: 409, error: 'Escalation not available for resolution' };
             }
             return { status: 200, data: { acknowledged: true, escalationId: escalation.id } };
         }
         // Path E: standard re-run
-        return resolveViaRerun(escalation, envelope, resolverPayload, metadata);
+        return resolveViaRerun(escalation, envelope, resolverPayload, outcome);
     }
     catch (err) {
         return { status: 500, error: err.message };
@@ -178,7 +186,11 @@ async function resolveBySignalKey(input, auth) {
             return validationFailure(violation);
         // The payload is delivered as the signal the parked workflow's condition()
         // receives — stored exactly as submitted (the caller formed its shape).
-        return resolveViaSignalKey(escalation, resolverPayload, metadata);
+        // Same provenance contract as the interactive path: identity on the signal,
+        // resolved_by in the row metadata.
+        const resolvedBy = await resolverIdentity(auth);
+        const outcome = { ...metadata, resolved_by: auth.userId };
+        return resolveViaSignalKey(escalation, resolverPayload, outcome, undefined, resolvedBy);
     }
     catch (err) {
         return { status: 500, error: err.message };
@@ -243,7 +255,7 @@ async function resolveByIds(input, auth) {
                     return bulkValidationFailure(failed);
             }
         }
-        const resolved = await escalationService.resolveEscalationsByIds(ids, resolverPayload, metadata);
+        const resolved = await escalationService.resolveEscalationsByIds(ids, resolverPayload, { ...metadata, resolved_by: auth.userId });
         return { status: 200, data: { resolved: resolved.length, escalationIds: resolved.map((e) => e.id) } };
     }
     catch (err) {
@@ -347,7 +359,7 @@ async function resolveAllOrNone(input, auth) {
             id: item.id,
             resolverPayload: await redactPasswords(item.resolverPayload, rowById.get(item.id)?.metadata?.form_schema),
         })));
-        const result = await escalationService.resolveEscalationsAllOrNone(serviceItems, metadata, requireClaimed ? auth.userId : undefined);
+        const result = await escalationService.resolveEscalationsAllOrNone(serviceItems, { ...metadata, resolved_by: auth.userId }, requireClaimed ? auth.userId : undefined, await resolverIdentity(auth));
         if (!result.ok) {
             const error = 'One or more escalations blocked the batch; nothing was resolved';
             return {
@@ -367,17 +379,20 @@ async function resolveAllOrNone(input, auth) {
 }
 // ── Resolution paths ─────────────────────────────────────────────────────
 /** Path A: lightweight conditionLT signal — inject $escalation_id and signal the running workflow. */
-async function resolveViaConditionSignal(escalation, resolverPayload, metadata) {
+async function resolveViaConditionSignal(escalation, resolverPayload, metadata, resolvedBy) {
     const signalId = escalation.metadata.signal_id;
     const client = (0, workers_1.createClient)();
     const handle = await client.workflow.getHandle(escalation.task_queue, escalation.workflow_type, escalation.workflow_id);
     // The row is resolved downstream by the workflow's `conditionLT` → `ltResolveEscalation`.
     // Carry the outcome patch on the signal ($escalation_metadata, symmetric to $escalation_id)
     // so it merges inside that single atomic resolve — never a separate write here.
+    // $resolution (provenance) is surfaced to the workflow by conditionLT and stripped
+    // from the stored resolver_payload, same as the other $-control keys.
     await handle.signal(signalId, {
         ...resolverPayload,
         $escalation_id: escalation.id,
         ...(metadata ? { $escalation_metadata: metadata } : {}),
+        ...(resolvedBy ? { $resolution: resolutionOf(escalation.id, resolvedBy) } : {}),
     });
     // Event published by service layer (services/escalation/crud.ts)
     return signaledResult(escalation, escalation.workflow_id);
@@ -388,13 +403,14 @@ async function resolveViaConditionSignal(escalation, resolverPayload, metadata)
  * transaction, so the original job resumes in place (no re-run, no separate
  * resolve activity). Password fields are redacted before they enter the signal.
  */
-async function resolveViaSignalKey(escalation, resolverPayload, metadata, assertClaim) {
+async function resolveViaSignalKey(escalation, resolverPayload, metadata, assertClaim, resolvedBy) {
     const signalPayload = await redactPasswords(resolverPayload, escalation.metadata?.form_schema);
     // One atomic call: status→resolved, signal delivered, and the outcome patch merged
     // into the GIN-indexed metadata — all inside the single WHERE-guarded UPDATE.
     // `assertClaim` (interactive path only) makes the claim-liveness gate part of
     // that same UPDATE; the webhook path (resolveBySignalKey) stays claim-agnostic.
-    const resolved = await escalationService.resolveEscalation(escalation.id, signalPayload, metadata, assertClaim);
+    // `resolvedBy` rides the SDK signal as $resolution — never the stored payload.
+    const resolved = await escalationService.resolveEscalation(escalation.id, signalPayload, metadata, assertClaim, resolvedBy);
     if (!resolved) {
         return { status: 409, error: 'Escalation not available for resolution' };
     }
@@ -402,7 +418,7 @@ async function resolveViaSignalKey(escalation, resolverPayload, metadata, assert
     return signaledResult(escalation, escalation.workflow_id || '');
 }
 /** Path B: waitFor signal escalation — signal via YAML engine or Durable handle. */
-async function resolveViaSignalRouting(escalation, resolverPayload, metadata) {
+async function resolveViaSignalRouting(escalation, resolverPayload, metadata, resolvedBy) {
     const signalRouting = escalation.metadata.signal_routing;
     const signalPayload = await redactPasswords(resolverPayload, escalation.metadata?.form_schema);
     if (signalRouting.engine === 'yaml' && signalRouting.hookTopic && signalRouting.appId) {
@@ -419,7 +435,11 @@ async function resolveViaSignalRouting(escalation, resolverPayload, metadata) {
     else if (signalRouting.workflowId) {
         const client = (0, workers_1.createClient)();
         const handle = await client.workflow.getHandle(signalRouting.taskQueue, signalRouting.workflowType, signalRouting.workflowId);
-        await handle.signal(signalRouting.signalId, signalPayload);
+        // Provenance rides the SIGNAL only — the resolve below persists the clean payload.
+        await handle.signal(signalRouting.signalId, {
+            ...signalPayload,
+            ...(resolvedBy ? { $resolution: resolutionOf(escalation.id, resolvedBy) } : {}),
+        });
     }
     // Durable resolves here — one atomic call carries the outcome patch.
     // Persist the SAME redacted payload that was delivered to the signal: the raw
@@ -497,6 +517,28 @@ async function resolveViaRerun(escalation, envelope, resolverPayload, metadata)
     };
 }
 // ── Shared helpers ───────────────────────────────────────────────────────
+/**
+ * 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.
+ */
+async function resolverIdentity(auth) {
+    try {
+        const user = await userService.getUser(auth.userId);
+        return { id: auth.userId, ...(user?.email ? { email: user.email } : {}) };
+    }
+    catch {
+        return { id: auth.userId };
+    }
+}
+/** The `$resolution` provenance object injected into legacy-path signals. */
+function resolutionOf(escalationId, resolvedBy) {
+    return {
+        escalationId,
+        resolvedBy: resolvedBy.id,
+        ...(resolvedBy.email ? { resolvedByEmail: resolvedBy.email } : {}),
+    };
+}
 function signaledResult(escalation, workflowId) {
     return {
         status: 200,

package/build/routes/escalations/bulk.js

@@ -51,6 +51,7 @@ function registerBulkRoutes(router) {
     router.post('/bulk-assign', async (req, res) => {
         const result = await api.bulkAssign({
             ids: req.body?.ids,
+            query: req.body?.query,
             targetUserId: req.body?.targetUserId,
             durationMinutes: req.body?.durationMinutes,
         }, req.auth);

package/build/sdk/index.d.ts

@@ -171,7 +171,11 @@ export declare function createClient(options?: LTClientOptions): {
             durationMinutes?: number;
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         bulkAssign: (input: {
-            ids: string[];
+            ids?: string[];
+            query?: {
+                role: string;
+                facets?: Record<string, unknown>;
+            };
             targetUserId: string;
             durationMinutes?: number;
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;

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

@@ -15,6 +15,20 @@ export declare function bulkAssignEscalations(ids: string[], targetUserId: strin
     assigned: number;
     skipped: number;
 }>;
+/**
+ * Bulk assign by query: one atomic UPDATE selects and claims every pending,
+ * claimable row matching role + facet containment — no search-then-assign
+ * window. A row that re-parks between a search and an ids-assign is invisible
+ * to the ids form but claimed by this one. Returns the assigned row ids so
+ * callers can publish per-row events.
+ */
+export declare function bulkAssignEscalationsByQuery(query: {
+    role: string;
+    facets?: Record<string, unknown>;
+}, targetUserId: string, durationMinutes?: number): Promise<{
+    assigned: number;
+    ids: string[];
+}>;
 /**
  * Bulk reassign escalations to a different role.
  * Clears assignment on all affected rows.

package/build/services/escalation/bulk.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.bulkClaimEscalations = bulkClaimEscalations;
 exports.bulkAssignEscalations = bulkAssignEscalations;
+exports.bulkAssignEscalationsByQuery = bulkAssignEscalationsByQuery;
 exports.bulkEscalateToRole = bulkEscalateToRole;
 exports.bulkCancelEscalations = bulkCancelEscalations;
 exports.bulkResolveForTriage = bulkResolveForTriage;
@@ -32,6 +33,22 @@ async function bulkAssignEscalations(ids, targetUserId, durationMinutes = 30) {
     });
     return { assigned: claimed, skipped };
 }
+/**
+ * Bulk assign by query: one atomic UPDATE selects and claims every pending,
+ * claimable row matching role + facet containment — no search-then-assign
+ * window. A row that re-parks between a search and an ids-assign is invisible
+ * to the ids form but claimed by this one. Returns the assigned row ids so
+ * callers can publish per-row events.
+ */
+async function bulkAssignEscalationsByQuery(query, targetUserId, durationMinutes = 30) {
+    const client = await (0, client_1.escalations)();
+    const { claimed, entries } = await client.claimManyByQuery({
+        query: { role: query.role, metadata: query.facets },
+        assignee: targetUserId,
+        durationMinutes,
+    });
+    return { assigned: claimed, ids: entries.map((e) => e.id) };
+}
 /**
  * Bulk reassign escalations to a different role.
  * Clears assignment on all affected rows.

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

@@ -19,8 +19,16 @@ export declare function claimEscalation(id: string, userId: string, durationMinu
  * results) into the `@>`-queryable surface alongside the creation metadata
  * ("what was intended"). Distinct from `resolverPayload`, which is delivered to
  * the waiting workflow as `condition()`'s return value and is not GIN-indexed.
+ *
+ * `resolvedBy` (optional) is delivered to the waiting workflow under the
+ * reserved `$resolution` signal key — resolution provenance for the workflow's
+ * next step (e.g. assign follow-on work to whoever resolved). Never written to
+ * the stored `resolver_payload`.
  */
-export declare function resolveEscalation(id: string, resolverPayload: Record<string, any>, metadata?: Record<string, any>, assertClaim?: string): Promise<LTEscalationRecord | null>;
+export declare function resolveEscalation(id: string, resolverPayload: Record<string, any>, metadata?: Record<string, any>, assertClaim?: string, resolvedBy?: {
+    id: string;
+    email?: string;
+}): Promise<LTEscalationRecord | null>;
 /**
  * Resolve a SET of escalations by id in ONE guarded statement
  * (`UPDATE … WHERE id = ANY($ids) AND status='pending'`). Returns the rows that
@@ -56,7 +64,10 @@ export declare function resolveEscalationsByIds(ids: string[], resolverPayload:
 export declare function resolveEscalationsAllOrNone(items: Array<{
     id: string;
     resolverPayload: Record<string, any>;
-}>, metadata?: Record<string, any>, assertAssignee?: string): Promise<{
+}>, metadata?: Record<string, any>, assertAssignee?: string, resolvedBy?: {
+    id: string;
+    email?: string;
+}): Promise<{
     ok: true;
     escalations: LTEscalationRecord[];
 } | {

package/build/services/escalation/crud.js

@@ -114,14 +114,19 @@ async function claimEscalation(id, userId, durationMinutes = 30) {
  * results) into the `@>`-queryable surface alongside the creation metadata
  * ("what was intended"). Distinct from `resolverPayload`, which is delivered to
  * the waiting workflow as `condition()`'s return value and is not GIN-indexed.
+ *
+ * `resolvedBy` (optional) is delivered to the waiting workflow under the
+ * reserved `$resolution` signal key — resolution provenance for the workflow's
+ * next step (e.g. assign follow-on work to whoever resolved). Never written to
+ * the stored `resolver_payload`.
  */
-async function resolveEscalation(id, resolverPayload, metadata, assertClaim) {
+async function resolveEscalation(id, resolverPayload, metadata, assertClaim, resolvedBy) {
     const client = await (0, client_1.escalations)();
     // `assertClaim` rides the SDK's guarded UPDATE: no active claim lock may
     // stand against this assignee, or the resolve blocks (claim-expired /
     // claimed-by-other). The API layer's advisory pre-check (assertLiveClaimant)
     // rejects early; this assertion is the atomic arbiter.
-    const result = await client.resolve({ id, resolverPayload, metadata, assertClaim });
+    const result = await client.resolve({ id, resolverPayload, metadata, assertClaim, resolvedBy });
     if (!result.ok)
         return null;
     const escalation = (0, map_1.toEscalationRecord)(result.entry);
@@ -188,11 +193,11 @@ async function resolveEscalationsByIds(ids, resolverPayload, metadata) {
  * to that principal, asserted inside the same guarded statement — closing the
  * claim-race window for claim-then-resolve flows.
  */
-async function resolveEscalationsAllOrNone(items, metadata, assertAssignee) {
+async function resolveEscalationsAllOrNone(items, metadata, assertAssignee, resolvedBy) {
     if (items.length === 0)
         return { ok: true, escalations: [] };
     const client = await (0, client_1.escalations)();
-    const result = await client.resolveAllOrNone({ items, metadata, assertAssignee });
+    const result = await client.resolveAllOrNone({ items, metadata, assertAssignee, resolvedBy });
     if (!result.ok)
         return { ok: false, failed: result.failed };
     const records = (0, map_1.toEscalationRecords)(result.entries);

package/build/services/orchestrator/condition.d.ts

@@ -73,6 +73,26 @@ export type ConditionEscalationConfig = Types.ConditionQueueConfig & {
  * }
  * ```
  *
+ * **Resolution provenance — the reserved `$resolution` key.** When the resolve
+ * carries the resolver's identity (the API layer supplies it for interactive
+ * and webhook resolves), the payload delivered here includes
+ * `$resolution: { escalationId, resolvedBy, resolvedByEmail? }`. Declare it in
+ * the generic to consume it — e.g. assign follow-on work to whoever resolved:
+ *
+ * ```typescript
+ * import type { EscalationResolution } from '@hotmeshio/hotmesh/types';
+ *
+ * const decision = await conditionLT<{
+ *   approved: boolean;
+ *   $resolution?: EscalationResolution;
+ * }>(signalId, { role: 'print-operator' });
+ * const resolver = decision && decision.$resolution?.resolvedBy;
+ * ```
+ *
+ * `$resolution` never lands in the stored `resolver_payload` audit column —
+ * on the legacy path below it is stripped before the durable resolve and
+ * re-attached to the returned payload.
+ *
  * **Legacy (two-step) — no config.** Create the escalation first (e.g. via
  * `ltCreateEscalation`) with `signal_id`/`signal_routing` metadata, then wait.
  * On resume the signal payload carries an injected `$escalation_id`; this helper

package/build/services/orchestrator/condition.js

@@ -112,6 +112,26 @@ function toEngineConfig(escalation) {
  * }
  * ```
  *
+ * **Resolution provenance — the reserved `$resolution` key.** When the resolve
+ * carries the resolver's identity (the API layer supplies it for interactive
+ * and webhook resolves), the payload delivered here includes
+ * `$resolution: { escalationId, resolvedBy, resolvedByEmail? }`. Declare it in
+ * the generic to consume it — e.g. assign follow-on work to whoever resolved:
+ *
+ * ```typescript
+ * import type { EscalationResolution } from '@hotmeshio/hotmesh/types';
+ *
+ * const decision = await conditionLT<{
+ *   approved: boolean;
+ *   $resolution?: EscalationResolution;
+ * }>(signalId, { role: 'print-operator' });
+ * const resolver = decision && decision.$resolution?.resolvedBy;
+ * ```
+ *
+ * `$resolution` never lands in the stored `resolver_payload` audit column —
+ * on the legacy path below it is stripped before the durable resolve and
+ * re-attached to the returned payload.
+ *
  * **Legacy (two-step) — no config.** Create the escalation first (e.g. via
  * `ltCreateEscalation`) with `signal_id`/`signal_routing` metadata, then wait.
  * On resume the signal payload carries an injected `$escalation_id`; this helper
@@ -138,17 +158,21 @@ async function conditionLT(signalId, escalation) {
             taskQueue: LT_ACTIVITY_QUEUE,
             retry: { maximumAttempts: 3 },
         });
-        // Strip the injected control keys ($escalation_id, $escalation_metadata) before the
-        // payload is returned to the caller. The outcome patch ($escalation_metadata, set by
-        // the resolve orchestrator's signal paths) rides INTO the single atomic resolve below
-        // so it merges in the same guarded UPDATE — never a separate write.
-        const { $escalation_id: _id, $escalation_metadata: metadata, ...resolverPayload } = raw;
+        // Strip the injected control keys ($escalation_id, $escalation_metadata,
+        // $resolution) before the payload is stored. The outcome patch
+        // ($escalation_metadata, set by the resolve orchestrator's signal paths)
+        // rides INTO the single atomic resolve below so it merges in the same
+        // guarded UPDATE — never a separate write. $resolution is provenance for
+        // the CALLER, not the audit column: it re-attaches to the returned payload.
+        const { $escalation_id: _id, $escalation_metadata: metadata, $resolution: resolution, ...resolverPayload } = raw;
         await ltResolveEscalation({
             escalationId,
             resolverPayload: resolverPayload,
             metadata: metadata,
         });
-        return resolverPayload;
+        return (resolution
+            ? { ...resolverPayload, $resolution: resolution }
+            : resolverPayload);
     }
     return raw;
 }

package/build/types/escalation.d.ts

@@ -1,3 +1,11 @@
+import type { Types } from '@hotmeshio/hotmesh';
+/**
+ * Resolution provenance delivered to a waiting workflow under the reserved
+ * `$resolution` signal key — who resolved the escalation and which row
+ * delivered it. Declare it in the `conditionLT` payload generic to consume it.
+ * Re-exported from the HotMesh SDK so workflow authors import one package.
+ */
+export type EscalationResolution = Types.EscalationResolution;
 /**
  * Reserved keys inside `lt_escalations.metadata`. Everything else in the bag
  * is caller-owned. These ride the GIN-indexed surface so they survive the

package/dashboard/dist/assets/{AdminDashboard-B5B8cf1A.js → AdminDashboard-CYlm0_J0.js}

@@ -1,2 +1,2 @@
-import{j as o}from"./vendor-query-B2UbickB.js";import{c as n}from"./tasks-B7QVagGw.js";import{K as m}from"./index-BmsZnbW1.js";import{f as c}from"./useEventHooks-CKpFrpjc.js";import{u}from"./mcp-C4upVuuP.js";import{P as d}from"./PageHeaderWithStats-BMhnR3-9.js";import"./vendor-react-BpdAFEQc.js";import"./vendor-icons-BE_WrH2z.js";function j(){var a;c();const{data:s}=n({limit:1}),{data:e}=m({status:"pending",limit:1}),{data:t}=u(),r=((a=t==null?void 0:t.servers)==null?void 0:a.filter(i=>i.status==="connected").length)??0,l=t?`${r}/${t.total}`:"—";return o.jsx("div",{children:o.jsx(d,{title:"Admin",stats:[{label:"Tasks",value:(s==null?void 0:s.total)??"—"},{label:"Pending Escalations",value:(e==null?void 0:e.total)??"—",dotClass:"bg-status-pending"},{label:"MCP Servers",value:l},{label:"System",value:"Healthy",dotClass:"bg-status-success"}]})})}export{j as AdminDashboard};
-//# sourceMappingURL=AdminDashboard-B5B8cf1A.js.map
+import{j as o}from"./vendor-query-B2UbickB.js";import{c as n}from"./tasks-CnC1xEaD.js";import{K as m}from"./index-C6UuVkz7.js";import{f as c}from"./useEventHooks-Cyq4DiQA.js";import{u}from"./mcp-BwjeqkHn.js";import{P as d}from"./PageHeaderWithStats-BMhnR3-9.js";import"./vendor-react-BpdAFEQc.js";import"./vendor-icons-BE_WrH2z.js";function j(){var a;c();const{data:s}=n({limit:1}),{data:e}=m({status:"pending",limit:1}),{data:t}=u(),r=((a=t==null?void 0:t.servers)==null?void 0:a.filter(i=>i.status==="connected").length)??0,l=t?`${r}/${t.total}`:"—";return o.jsx("div",{children:o.jsx(d,{title:"Admin",stats:[{label:"Tasks",value:(s==null?void 0:s.total)??"—"},{label:"Pending Escalations",value:(e==null?void 0:e.total)??"—",dotClass:"bg-status-pending"},{label:"MCP Servers",value:l},{label:"System",value:"Healthy",dotClass:"bg-status-success"}]})})}export{j as AdminDashboard};
+//# sourceMappingURL=AdminDashboard-CYlm0_J0.js.map

package/dashboard/dist/assets/{AdminDashboard-B5B8cf1A.js.map → AdminDashboard-CYlm0_J0.js.map}

@@ -1 +1 @@
-{"version":3,"file":"AdminDashboard-B5B8cf1A.js","sources":["../../src/pages/admin/AdminDashboard.tsx"],"sourcesContent":["import { useTasks } from '../../api/tasks';\nimport { useEscalations } from '../../api/escalations';\nimport { useEscalationListEvents } from '../../hooks/useEventHooks';\nimport { useMcpServers } from '../../api/mcp';\nimport { PageHeaderWithStats } from '../../components/common/layout/PageHeaderWithStats';\n\nexport function AdminDashboard() {\n  useEscalationListEvents();\n  const { data: taskData } = useTasks({ limit: 1 });\n  const { data: pendingEsc } = useEscalations({ status: 'pending', limit: 1 });\n  const { data: mcpData } = useMcpServers();\n\n  const connectedServers =\n    mcpData?.servers?.filter((s) => s.status === 'connected').length ?? 0;\n  const mcpLabel = mcpData ? `${connectedServers}/${mcpData.total}` : '—';\n\n  return (\n    <div>\n      <PageHeaderWithStats\n        title=\"Admin\"\n        stats={[\n          { label: 'Tasks', value: taskData?.total ?? '—' },\n          { label: 'Pending Escalations', value: pendingEsc?.total ?? '—', dotClass: 'bg-status-pending' },\n          { label: 'MCP Servers', value: mcpLabel },\n          { label: 'System', value: 'Healthy', dotClass: 'bg-status-success' },\n        ]}\n      />\n    </div>\n  );\n}\n"],"names":["AdminDashboard","useEscalationListEvents","taskData","useTasks","pendingEsc","useEscalations","mcpData","useMcpServers","connectedServers","_a","s","mcpLabel","jsx","PageHeaderWithStats"],"mappings":"4UAMO,SAASA,GAAiB,OAC/BC,EAAA,EACA,KAAM,CAAE,KAAMC,CAAA,EAAaC,EAAS,CAAE,MAAO,EAAG,EAC1C,CAAE,KAAMC,CAAA,EAAeC,EAAe,CAAE,OAAQ,UAAW,MAAO,EAAG,EACrE,CAAE,KAAMC,CAAA,EAAYC,EAAA,EAEpBC,IACJC,EAAAH,GAAA,YAAAA,EAAS,UAAT,YAAAG,EAAkB,OAAQC,GAAMA,EAAE,SAAW,aAAa,SAAU,EAChEC,EAAWL,EAAU,GAAGE,CAAgB,IAAIF,EAAQ,KAAK,GAAK,IAEpE,aACG,MAAA,CACC,SAAAM,EAAAA,IAACC,EAAA,CACC,MAAM,QACN,MAAO,CACL,CAAE,MAAO,QAAS,OAAOX,GAAA,YAAAA,EAAU,QAAS,GAAA,EAC5C,CAAE,MAAO,sBAAuB,OAAOE,GAAA,YAAAA,EAAY,QAAS,IAAK,SAAU,mBAAA,EAC3E,CAAE,MAAO,cAAe,MAAOO,CAAA,EAC/B,CAAE,MAAO,SAAU,MAAO,UAAW,SAAU,mBAAA,CAAoB,CACrE,CAAA,EAEJ,CAEJ"}
+{"version":3,"file":"AdminDashboard-CYlm0_J0.js","sources":["../../src/pages/admin/AdminDashboard.tsx"],"sourcesContent":["import { useTasks } from '../../api/tasks';\nimport { useEscalations } from '../../api/escalations';\nimport { useEscalationListEvents } from '../../hooks/useEventHooks';\nimport { useMcpServers } from '../../api/mcp';\nimport { PageHeaderWithStats } from '../../components/common/layout/PageHeaderWithStats';\n\nexport function AdminDashboard() {\n  useEscalationListEvents();\n  const { data: taskData } = useTasks({ limit: 1 });\n  const { data: pendingEsc } = useEscalations({ status: 'pending', limit: 1 });\n  const { data: mcpData } = useMcpServers();\n\n  const connectedServers =\n    mcpData?.servers?.filter((s) => s.status === 'connected').length ?? 0;\n  const mcpLabel = mcpData ? `${connectedServers}/${mcpData.total}` : '—';\n\n  return (\n    <div>\n      <PageHeaderWithStats\n        title=\"Admin\"\n        stats={[\n          { label: 'Tasks', value: taskData?.total ?? '—' },\n          { label: 'Pending Escalations', value: pendingEsc?.total ?? '—', dotClass: 'bg-status-pending' },\n          { label: 'MCP Servers', value: mcpLabel },\n          { label: 'System', value: 'Healthy', dotClass: 'bg-status-success' },\n        ]}\n      />\n    </div>\n  );\n}\n"],"names":["AdminDashboard","useEscalationListEvents","taskData","useTasks","pendingEsc","useEscalations","mcpData","useMcpServers","connectedServers","_a","s","mcpLabel","jsx","PageHeaderWithStats"],"mappings":"4UAMO,SAASA,GAAiB,OAC/BC,EAAA,EACA,KAAM,CAAE,KAAMC,CAAA,EAAaC,EAAS,CAAE,MAAO,EAAG,EAC1C,CAAE,KAAMC,CAAA,EAAeC,EAAe,CAAE,OAAQ,UAAW,MAAO,EAAG,EACrE,CAAE,KAAMC,CAAA,EAAYC,EAAA,EAEpBC,IACJC,EAAAH,GAAA,YAAAA,EAAS,UAAT,YAAAG,EAAkB,OAAQC,GAAMA,EAAE,SAAW,aAAa,SAAU,EAChEC,EAAWL,EAAU,GAAGE,CAAgB,IAAIF,EAAQ,KAAK,GAAK,IAEpE,aACG,MAAA,CACC,SAAAM,EAAAA,IAACC,EAAA,CACC,MAAM,QACN,MAAO,CACL,CAAE,MAAO,QAAS,OAAOX,GAAA,YAAAA,EAAU,QAAS,GAAA,EAC5C,CAAE,MAAO,sBAAuB,OAAOE,GAAA,YAAAA,EAAY,QAAS,IAAK,SAAU,mBAAA,EAC3E,CAAE,MAAO,cAAe,MAAOO,CAAA,EAC/B,CAAE,MAAO,SAAU,MAAO,UAAW,SAAU,mBAAA,CAAoB,CACrE,CAAA,EAEJ,CAEJ"}