@hotmeshio/long-tail 0.22.0 → 0.22.1

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

@@ -1,5 +1,5 @@
 import { publishEscalationEvent } from '../../lib/events/publish';
-import type { LTEscalationRecord } from '../../types';
+import type { LTEscalationRecord, ScanAvailability } from '../../types';
 import type { CreateEscalationInput, ClaimResult } from './types';
 /**
  * Every escalation write publishes an event AND drops this container's cached
@@ -256,4 +256,4 @@ export interface ResolveByMetadataResult {
  * business logic over the shared table, so it runs as one atomic statement on
  * `hmsh_escalations` rather than through the generic SDK resolve.
  */
-export declare function resolveByMetadataAtomic(key: string, value: string, userId: string, resolverPayload: Record<string, any>, metadata?: Record<string, any>, writeAllRoles?: string[] | null, writeSelfRoles?: string[] | null, enforcingRoles?: string[] | null, assertId?: string | null, extraFacets?: Record<string, any> | null): Promise<ResolveByMetadataResult>;
+export declare function resolveByMetadataAtomic(key: string, value: string, userId: string, resolverPayload: Record<string, any>, metadata?: Record<string, any>, writeAllRoles?: string[] | null, writeSelfRoles?: string[] | null, enforcingRoles?: string[] | null, assertId?: string | null, extraFacets?: Record<string, any> | null, availability?: ScanAvailability | null): Promise<ResolveByMetadataResult>;

package/build/services/escalation/crud.js

@@ -28,6 +28,7 @@ exports.resolveByMetadataAtomic = resolveByMetadataAtomic;
 const db_1 = require("../../lib/db");
 const publish_1 = require("../../lib/events/publish");
 const escalation_wire_1 = require("../../lib/events/escalation-wire");
+const scan_code_1 = require("../../types/scan-code");
 const escalation_1 = require("../../types/escalation");
 const uuid_1 = require("../../lib/uuid");
 const client_1 = require("./client");
@@ -600,7 +601,7 @@ async function claimByMetadata(key, value, userId, durationMinutes = 30, metadat
  * business logic over the shared table, so it runs as one atomic statement on
  * `hmsh_escalations` rather than through the generic SDK resolve.
  */
-async function resolveByMetadataAtomic(key, value, userId, resolverPayload, metadata, writeAllRoles, writeSelfRoles, enforcingRoles, assertId, extraFacets) {
+async function resolveByMetadataAtomic(key, value, userId, resolverPayload, metadata, writeAllRoles, writeSelfRoles, enforcingRoles, assertId, extraFacets, availability) {
     await (0, client_1.ensureEscalationCompatView)();
     const pool = (0, db_1.getPool)();
     // The statement's filter is jsonb containment — extra facet guards simply
@@ -613,7 +614,8 @@ async function resolveByMetadataAtomic(key, value, userId, resolverPayload, meta
     const allRoles = writeAllRoles ?? null;
     const selfRoles = writeSelfRoles ?? null;
     const { rows } = await pool.query(sql_1.RESOLVE_BY_METADATA_ATOMIC, [filter, userId, payloadJson, metaPatch, allRoles, selfRoles,
-        enforcingRoles?.length ? enforcingRoles : null, assertId ?? null]);
+        enforcingRoles?.length ? enforcingRoles : null, assertId ?? null,
+        availability && availability !== scan_code_1.SCAN_AVAILABILITY.ANY ? availability : null]);
     if (rows.length === 0)
         return { outcome: 'not_found' };
     const row = rows[0];

package/build/services/escalation/facet-sql.js

@@ -47,6 +47,14 @@ function buildFacetWhere(q, params, opts = {}) {
         params.push(q.roles);
         clauses.push(`role = ANY($${params.length}::text[])`);
     }
+    if (q.types && q.types.length) {
+        params.push(q.types);
+        clauses.push(`type = ANY($${params.length}::text[])`);
+    }
+    if (q.subtypes && q.subtypes.length) {
+        params.push(q.subtypes);
+        clauses.push(`subtype = ANY($${params.length}::text[])`);
+    }
     if (q.status) {
         params.push(q.status);
         clauses.push(`status = $${params.length}`);

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

@@ -59,7 +59,9 @@ export declare function searchEscalationsQuery(orderBy: string): string;
  * $1 = metadata filter (jsonb), $2 = userId, $3 = resolver_payload (jsonb),
  * $4 = metadata patch (jsonb, nullable), $5 = write_all roles (text[], null = global /
  * no filter), $6 = write_self roles (text[], nullable), $7 = enforcing roles
- * (text[], null = none), $8 = assert id (uuid, nullable).
+ * (text[], null = none), $8 = assert id (uuid, nullable), $9 = claim state
+ * ('mine' | 'available' | 'claimed', null = any). 'mine' is a live claim held by
+ * $2 and picks the most recently claimed row first.
  *
  * Write-scope is folded into the same FOR UPDATE statement (no TOCTOU): the row
  * is resolvable if the caller has global access ($5 NULL), or the row's role is in
@@ -75,7 +77,7 @@ export declare function searchEscalationsQuery(orderBy: string): string;
  * resolution surfaces as zero rows → the caller's conflict handling). This is
  * the same pick-then-guarded-finish shape the signal outcomes already use.
  */
-export declare const RESOLVE_BY_METADATA_ATOMIC = "WITH target AS MATERIALIZED (\n  SELECT *\n  FROM public.hmsh_escalations\n  WHERE metadata @> $1::jsonb\n    AND status = 'pending'\n    AND (\n         $5::text[] IS NULL\n      OR role = ANY($5)\n      OR (role = ANY($6::text[]) AND assigned_to = $2)\n    )\n    AND ($8::uuid IS NULL OR id = $8::uuid)\n  ORDER BY priority ASC, created_at ASC\n  LIMIT 1\n  FOR UPDATE\n),\nwritten AS (\n  UPDATE public.hmsh_escalations e\n  SET assigned_to = COALESCE(e.assigned_to, $2),\n      claimed_at = COALESCE(e.claimed_at, NOW()),\n      assigned_until = CASE\n        WHEN e.assigned_to IS NOT NULL AND e.assigned_until > NOW() THEN e.assigned_until\n        ELSE NOW() + INTERVAL '5 minutes' END,\n      claim_expires_at = CASE\n        WHEN e.assigned_to IS NOT NULL AND e.assigned_until > NOW() THEN e.claim_expires_at\n        ELSE NOW() + INTERVAL '5 minutes' END,\n      metadata = CASE WHEN $4::jsonb IS NOT NULL\n        THEN COALESCE(e.metadata, '{}'::jsonb) || $4::jsonb\n        ELSE e.metadata END,\n      status = CASE WHEN (target.metadata->>'signal_id') IS NULL\n        THEN 'resolved' ELSE e.status END,\n      resolved_at = CASE WHEN (target.metadata->>'signal_id') IS NULL\n        THEN NOW() ELSE e.resolved_at END,\n      resolver_payload = CASE WHEN (target.metadata->>'signal_id') IS NULL\n        THEN $3 ELSE e.resolver_payload END,\n      updated_at = NOW()\n  FROM target\n  WHERE e.id = target.id\n    AND target.signal_key IS NULL\n    AND ($7::text[] IS NULL OR NOT (target.role = ANY($7)))\n  RETURNING e.*\n)\nSELECT\n  written.*,\n  target.id AS target_id,\n  target.role AS target_role,\n  target.metadata AS target_metadata,\n  target.envelope AS target_envelope,\n  target.escalation_payload AS target_escalation_payload,\n  target.metadata->>'signal_id' AS signal_id,\n  target.signal_key AS signal_key,\n  target.workflow_id AS target_workflow_id,\n  target.workflow_type AS target_workflow_type,\n  target.task_queue AS target_task_queue,\n  (target.assigned_to IS NOT NULL\n    AND target.assigned_until IS NOT NULL\n    AND target.assigned_until > NOW()) AS signal_already_claimed,\n  CASE\n    WHEN written.status = 'resolved' THEN 'resolved'\n    WHEN $7::text[] IS NOT NULL AND target.role = ANY($7) THEN 'validation_required'\n    ELSE 'signal_required'\n  END AS outcome\nFROM target\nLEFT JOIN written ON written.id = target.id";
+export declare const RESOLVE_BY_METADATA_ATOMIC = "WITH target AS MATERIALIZED (\n  SELECT *\n  FROM public.hmsh_escalations\n  WHERE metadata @> $1::jsonb\n    AND status = 'pending'\n    AND (\n         $5::text[] IS NULL\n      OR role = ANY($5)\n      OR (role = ANY($6::text[]) AND assigned_to = $2)\n    )\n    AND ($8::uuid IS NULL OR id = $8::uuid)\n    AND (\n         $9::text IS NULL\n      OR ($9 = 'mine' AND assigned_to = $2 AND assigned_until > NOW())\n      OR ($9 = 'available' AND (assigned_to IS NULL OR assigned_until IS NULL OR assigned_until <= NOW()))\n      OR ($9 = 'claimed' AND assigned_to IS NOT NULL AND assigned_until > NOW())\n    )\n  ORDER BY CASE WHEN $9 = 'mine' THEN claimed_at END DESC NULLS LAST, priority ASC, created_at ASC\n  LIMIT 1\n  FOR UPDATE\n),\nwritten AS (\n  UPDATE public.hmsh_escalations e\n  SET assigned_to = COALESCE(e.assigned_to, $2),\n      claimed_at = COALESCE(e.claimed_at, NOW()),\n      assigned_until = CASE\n        WHEN e.assigned_to IS NOT NULL AND e.assigned_until > NOW() THEN e.assigned_until\n        ELSE NOW() + INTERVAL '5 minutes' END,\n      claim_expires_at = CASE\n        WHEN e.assigned_to IS NOT NULL AND e.assigned_until > NOW() THEN e.claim_expires_at\n        ELSE NOW() + INTERVAL '5 minutes' END,\n      metadata = CASE WHEN $4::jsonb IS NOT NULL\n        THEN COALESCE(e.metadata, '{}'::jsonb) || $4::jsonb\n        ELSE e.metadata END,\n      status = CASE WHEN (target.metadata->>'signal_id') IS NULL\n        THEN 'resolved' ELSE e.status END,\n      resolved_at = CASE WHEN (target.metadata->>'signal_id') IS NULL\n        THEN NOW() ELSE e.resolved_at END,\n      resolver_payload = CASE WHEN (target.metadata->>'signal_id') IS NULL\n        THEN $3 ELSE e.resolver_payload END,\n      updated_at = NOW()\n  FROM target\n  WHERE e.id = target.id\n    AND target.signal_key IS NULL\n    AND ($7::text[] IS NULL OR NOT (target.role = ANY($7)))\n  RETURNING e.*\n)\nSELECT\n  written.*,\n  target.id AS target_id,\n  target.role AS target_role,\n  target.metadata AS target_metadata,\n  target.envelope AS target_envelope,\n  target.escalation_payload AS target_escalation_payload,\n  target.metadata->>'signal_id' AS signal_id,\n  target.signal_key AS signal_key,\n  target.workflow_id AS target_workflow_id,\n  target.workflow_type AS target_workflow_type,\n  target.task_queue AS target_task_queue,\n  (target.assigned_to IS NOT NULL\n    AND target.assigned_until IS NOT NULL\n    AND target.assigned_until > NOW()) AS signal_already_claimed,\n  CASE\n    WHEN written.status = 'resolved' THEN 'resolved'\n    WHEN $7::text[] IS NOT NULL AND target.role = ANY($7) THEN 'validation_required'\n    ELSE 'signal_required'\n  END AS outcome\nFROM target\nLEFT JOIN written ON written.id = target.id";
 /**
  * Live counts — pending, active claims, and priority (past-threshold) per role.
  *

package/build/services/escalation/sql.js

@@ -167,7 +167,9 @@ function searchEscalationsQuery(orderBy) {
  * $1 = metadata filter (jsonb), $2 = userId, $3 = resolver_payload (jsonb),
  * $4 = metadata patch (jsonb, nullable), $5 = write_all roles (text[], null = global /
  * no filter), $6 = write_self roles (text[], nullable), $7 = enforcing roles
- * (text[], null = none), $8 = assert id (uuid, nullable).
+ * (text[], null = none), $8 = assert id (uuid, nullable), $9 = claim state
+ * ('mine' | 'available' | 'claimed', null = any). 'mine' is a live claim held by
+ * $2 and picks the most recently claimed row first.
  *
  * Write-scope is folded into the same FOR UPDATE statement (no TOCTOU): the row
  * is resolvable if the caller has global access ($5 NULL), or the row's role is in
@@ -195,7 +197,13 @@ WITH target AS MATERIALIZED (
       OR (role = ANY($6::text[]) AND assigned_to = $2)
     )
     AND ($8::uuid IS NULL OR id = $8::uuid)
-  ORDER BY priority ASC, created_at ASC
+    AND (
+         $9::text IS NULL
+      OR ($9 = 'mine' AND assigned_to = $2 AND assigned_until > NOW())
+      OR ($9 = 'available' AND (assigned_to IS NULL OR assigned_until IS NULL OR assigned_until <= NOW()))
+      OR ($9 = 'claimed' AND assigned_to IS NOT NULL AND assigned_until > NOW())
+    )
+  ORDER BY CASE WHEN $9 = 'mine' THEN claimed_at END DESC NULLS LAST, priority ASC, created_at ASC
   LIMIT 1
   FOR UPDATE
 ),

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

@@ -1,5 +1,6 @@
 import type { ExecutionExportOptions, WorkflowExecution } from '@hotmeshio/hotmesh/build/types/exporter';
 import type { LTExportOptions, LTWorkflowExport } from '../../types';
+import { type WorkflowState } from '../workflow-state';
 import type { JobListParams, JobListResult } from './types';
 /**
  * Export the full workflow state for a given workflow (raw HotMesh format).
@@ -9,12 +10,14 @@ import type { JobListParams, JobListResult } from './types';
  */
 export declare function exportWorkflow(workflowId: string, taskQueue: string, workflowName: string, options?: LTExportOptions): Promise<LTWorkflowExport>;
 /**
- * Return only the status semaphore for a workflow.
- * 0 = complete, negative = interrupted.
+ * Return the status semaphore for a workflow (above 0 running, 0 closed,
+ * below 0 terminated) and the state it implies.
  */
 export declare function getWorkflowStatus(workflowId: string, taskQueue: string, workflowName: string): Promise<{
     workflow_id: string;
     status: number;
+    state: WorkflowState;
+    terminated: boolean;
 }>;
 /**
  * Export workflow state as a structured execution event history.
@@ -27,7 +30,9 @@ export declare function exportWorkflowExecution(workflowId: string, taskQueue: s
 /** The input/output envelope pair plus the derived run status. */
 export interface WorkflowEnvelopes {
     workflow_id: string;
-    status: 'running' | 'completed' | 'failed';
+    status: WorkflowState;
+    /** Present and true when an interrupt ended the run. */
+    terminated?: boolean;
     /** The workflow's input — the single LTEnvelope for one-arg workflows, else the args array. */
     input: unknown;
     /** The workflow's return envelope, or null while it is still running or when it failed. */

package/build/services/export/index.js

@@ -10,6 +10,7 @@ const db_1 = require("../../lib/db");
 const hotmesh_utils_1 = require("../hotmesh-utils");
 const client_1 = require("./client");
 const post_process_1 = require("./post-process");
+const workflow_state_1 = require("../workflow-state");
 /** Error thrown when a workflow job is not found (expired or never existed). */
 class WorkflowNotFoundError extends Error {
     constructor(workflowId) {
@@ -44,14 +45,14 @@ async function exportWorkflow(workflowId, taskQueue, workflowName, options) {
     }
 }
 /**
- * Return only the status semaphore for a workflow.
- * 0 = complete, negative = interrupted.
+ * Return the status semaphore for a workflow (above 0 running, 0 closed,
+ * below 0 terminated) and the state it implies.
  */
 async function getWorkflowStatus(workflowId, taskQueue, workflowName) {
     try {
         const handle = await (0, client_1.getHandle)(taskQueue, workflowName, workflowId);
         const status = await handle.status();
-        return { workflow_id: workflowId, status };
+        return { workflow_id: workflowId, status, state: (0, workflow_state_1.workflowStateFromStatus)(status), terminated: (0, workflow_state_1.isTerminated)(status) };
     }
     catch {
         throw new WorkflowNotFoundError(workflowId);
@@ -97,8 +98,8 @@ async function getWorkflowEnvelopes(workflowId, taskQueue, workflowName) {
     catch {
         throw new WorkflowNotFoundError(workflowId);
     }
-    const [statusCode, args] = await Promise.all([
-        handle.status(),
+    const [reading, args] = await Promise.all([
+        (0, workflow_state_1.readWorkflowState)(handle),
         handle.input().catch(() => undefined),
     ]).catch(() => {
         throw new WorkflowNotFoundError(workflowId);
@@ -106,28 +107,21 @@ async function getWorkflowEnvelopes(workflowId, taskQueue, workflowName) {
     // Long-tail workflows take a single LTEnvelope argument — unwrap it;
     // multi-arg workflows keep the args array verbatim.
     const input = Array.isArray(args) && args.length === 1 ? args[0] : args ?? null;
-    if (statusCode > 0) {
-        return { workflow_id: workflowId, status: 'running', input, output: null };
+    if (reading.state === workflow_state_1.WORKFLOW_STATES.RUNNING) {
+        return { workflow_id: workflowId, status: reading.state, input, output: null };
     }
-    try {
-        const output = await handle.output();
-        return {
-            workflow_id: workflowId,
-            status: statusCode === 0 ? 'completed' : 'failed',
-            input,
-            output: output ?? null,
-        };
-    }
-    catch (err) {
-        // output() throws the workflow's own error for failed runs — that IS the outcome.
+    if (reading.state === workflow_state_1.WORKFLOW_STATES.FAILED) {
         return {
             workflow_id: workflowId,
-            status: 'failed',
+            status: reading.state,
+            ...(reading.terminated ? { terminated: true } : {}),
             input,
             output: null,
-            error: err?.message ?? String(err),
+            ...(reading.error ? { error: reading.error } : {}),
         };
     }
+    const output = await handle.output().catch(() => null);
+    return { workflow_id: workflowId, status: reading.state, input, output: output ?? null };
 }
 /**
  * Return the current job state of a workflow.
@@ -225,7 +219,7 @@ async function listJobs(app_id, params) {
     const jobs = dataResult.rows.map((row) => ({
         workflow_id: row.key.replace(keyPrefix, ''),
         entity: row.entity,
-        status: (row.status > 0 ? 'running' : row.status === 0 ? 'completed' : 'failed'),
+        status: (0, workflow_state_1.workflowStateFromStatus)(row.status),
         is_live: row.is_live,
         created_at: row.created_at,
         updated_at: row.updated_at,

package/build/services/pipelines/events.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildEvents = buildEvents;
 const hotmesh_utils_1 = require("../hotmesh-utils");
+const workflow_state_1 = require("../workflow-state");
 /**
  * Transform raw activities + job context into a chronological event list
  * with back-references linking completions to their scheduled events.
@@ -84,7 +85,7 @@ function completionEvent(id, act, input, timelineKey, index) {
     };
 }
 function appendWorkflowTerminalEvent(events, nextId, ctx) {
-    const status = ctx.job.status > 0 ? 'running' : ctx.job.status === 0 ? 'completed' : 'failed';
+    const status = (0, workflow_state_1.workflowStateFromStatus)(ctx.job.status);
     if (status === 'completed') {
         events.push({
             event_id: nextId,

package/build/services/pipelines/execution-builder.js

@@ -6,6 +6,7 @@ const hotmesh_utils_1 = require("../hotmesh-utils");
 const enrichment_1 = require("./enrichment");
 const events_1 = require("./events");
 const sql_1 = require("./sql");
+const workflow_state_1 = require("../workflow-state");
 /**
  * Build a complete execution export for a YAML engine workflow job.
  *
@@ -88,7 +89,7 @@ function assembleExport(ctx, events, activities) {
         workflow_type: ctx.workflowTopic,
         workflow_name: ctx.workflowName,
         task_queue: ctx.appId,
-        status: ctx.job.status > 0 ? 'running' : ctx.job.status === 0 ? 'completed' : 'failed',
+        status: (0, workflow_state_1.workflowStateFromStatus)(ctx.job.status),
         start_time: startTime,
         close_time: closeTime,
         duration_ms: durationMs,

package/build/services/pipelines/queries.js

@@ -5,6 +5,7 @@ exports.listJobs = listJobs;
 const db_1 = require("../../lib/db");
 const hotmesh_utils_1 = require("../hotmesh-utils");
 const sql_1 = require("./sql");
+const workflow_state_1 = require("../workflow-state");
 const SORTABLE_COLUMNS = new Set(['created_at', 'updated_at', 'entity', 'status']);
 function buildOrderBy(sortBy, order) {
     if (!sortBy || !SORTABLE_COLUMNS.has(sortBy)) {
@@ -75,7 +76,7 @@ async function listJobs(params) {
     const jobs = dataResult.rows.map((row) => ({
         workflow_id: row.key.startsWith(keyPrefix) ? row.key.slice(keyPrefix.length) : row.key,
         entity: row.entity,
-        status: row.status > 0 ? 'running' : row.status === 0 ? 'completed' : 'failed',
+        status: (0, workflow_state_1.workflowStateFromStatus)(row.status),
         is_live: row.is_live,
         created_at: row.created_at,
         updated_at: row.updated_at,

package/build/services/scan-code/validate.js

@@ -157,6 +157,25 @@ function assertValidSteps(steps) {
             if (options?.containerRoles !== undefined && !Array.isArray(options.containerRoles)) {
                 throw new Error(`${at}: params.accumulate.containerRoles must be an array`);
             }
+            const container = options?.container;
+            if (container !== undefined) {
+                if (!container || typeof container !== 'object' || Array.isArray(container)) {
+                    throw new Error(`${at}: params.accumulate.container must be an object`);
+                }
+                for (const list of ['roles', 'types', 'subtypes']) {
+                    const value = container[list];
+                    if (value !== undefined && (!Array.isArray(value) || !value.every((v) => typeof v === 'string' && v))) {
+                        throw new Error(`${at}: params.accumulate.container.${list} must be an array of strings`);
+                    }
+                }
+                if (container.facets !== undefined
+                    && (!container.facets || typeof container.facets !== 'object' || Array.isArray(container.facets))) {
+                    throw new Error(`${at}: params.accumulate.container.facets must be an object`);
+                }
+                if (!options?.containerFacet) {
+                    throw new Error(`${at}: params.accumulate.container requires params.accumulate.containerFacet`);
+                }
+            }
             if (!options?.containerFacet && !step.params?.itemKey) {
                 throw new Error(`${at}: accumulate requires params.itemKey or params.accumulate.containerFacet`);
             }

package/build/services/workflow-state.d.ts

@@ -0,0 +1,21 @@
+import { WORKFLOW_STATES, isTerminated, workflowStateFromStatus, type WorkflowState } from '../shared/workflow-state';
+export { WORKFLOW_STATES, isTerminated, workflowStateFromStatus, type WorkflowState };
+export interface WorkflowStateReading {
+    /** HotMesh job status: above 0 running, 0 closed, below 0 terminated. */
+    status: number;
+    state: WorkflowState;
+    terminated: boolean;
+    /** The failure message, when the run closed with an error. */
+    error?: string;
+}
+interface StatusHandle {
+    status(): Promise<number>;
+    state(metadata?: boolean): Promise<Record<string, any> | undefined>;
+}
+/**
+ * A workflow's state from its handle. A running run needs only the status.
+ * A closed run can still have failed, so its outcome is read for `$error`.
+ * A terminated run keeps `$error` when HotMesh still holds it; a failed read
+ * of a terminated run carries no reason and is dropped.
+ */
+export declare function readWorkflowState(handle: StatusHandle): Promise<WorkflowStateReading>;

package/build/services/workflow-state.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.workflowStateFromStatus = exports.isTerminated = exports.WORKFLOW_STATES = void 0;
+exports.readWorkflowState = readWorkflowState;
+const workflow_state_1 = require("../shared/workflow-state");
+Object.defineProperty(exports, "WORKFLOW_STATES", { enumerable: true, get: function () { return workflow_state_1.WORKFLOW_STATES; } });
+Object.defineProperty(exports, "isTerminated", { enumerable: true, get: function () { return workflow_state_1.isTerminated; } });
+Object.defineProperty(exports, "workflowStateFromStatus", { enumerable: true, get: function () { return workflow_state_1.workflowStateFromStatus; } });
+function errorMessage(error) {
+    if (error && typeof error === 'object' && 'message' in error)
+        return String(error.message);
+    return typeof error === 'string' ? error : JSON.stringify(error);
+}
+/**
+ * A workflow's state from its handle. A running run needs only the status.
+ * A closed run can still have failed, so its outcome is read for `$error`.
+ * A terminated run keeps `$error` when HotMesh still holds it; a failed read
+ * of a terminated run carries no reason and is dropped.
+ */
+async function readWorkflowState(handle) {
+    const status = await handle.status();
+    if (status > 0)
+        return { status, state: workflow_state_1.WORKFLOW_STATES.RUNNING, terminated: false };
+    const terminated = (0, workflow_state_1.isTerminated)(status);
+    let failure;
+    try {
+        failure = (await handle.state())?.$error;
+    }
+    catch (err) {
+        if (!terminated)
+            failure = err;
+    }
+    const error = failure === undefined || failure === null ? undefined : errorMessage(failure);
+    if (terminated)
+        return { status, state: workflow_state_1.WORKFLOW_STATES.FAILED, terminated, ...(error ? { error } : {}) };
+    if (error)
+        return { status, state: workflow_state_1.WORKFLOW_STATES.FAILED, terminated, error };
+    return { status, state: workflow_state_1.WORKFLOW_STATES.COMPLETED, terminated };
+}

package/build/shared/workflow-state.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A workflow's lifecycle state, read from HotMesh's job status: above 0 the
+ * job is running, 0 it has closed, below 0 it was terminated (an interrupt
+ * lowers the status far below 0). A terminated run is failed. A run that
+ * closed at 0 can still have failed; `readWorkflowState` on the server tells
+ * the two apart from the job's outcome.
+ */
+export declare const WORKFLOW_STATES: {
+    readonly RUNNING: "running";
+    readonly COMPLETED: "completed";
+    readonly FAILED: "failed";
+};
+export type WorkflowState = (typeof WORKFLOW_STATES)[keyof typeof WORKFLOW_STATES];
+/** The state a job status implies, before any outcome is read. */
+export declare function workflowStateFromStatus(status: number): WorkflowState;
+/** Whether a job status means the run was terminated. */
+export declare function isTerminated(status: number): boolean;

package/build/shared/workflow-state.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WORKFLOW_STATES = void 0;
+exports.workflowStateFromStatus = workflowStateFromStatus;
+exports.isTerminated = isTerminated;
+/**
+ * A workflow's lifecycle state, read from HotMesh's job status: above 0 the
+ * job is running, 0 it has closed, below 0 it was terminated (an interrupt
+ * lowers the status far below 0). A terminated run is failed. A run that
+ * closed at 0 can still have failed; `readWorkflowState` on the server tells
+ * the two apart from the job's outcome.
+ */
+exports.WORKFLOW_STATES = {
+    RUNNING: 'running',
+    COMPLETED: 'completed',
+    FAILED: 'failed',
+};
+/** The state a job status implies, before any outcome is read. */
+function workflowStateFromStatus(status) {
+    if (status > 0)
+        return exports.WORKFLOW_STATES.RUNNING;
+    if (status === 0)
+        return exports.WORKFLOW_STATES.COMPLETED;
+    return exports.WORKFLOW_STATES.FAILED;
+}
+/** Whether a job status means the run was terminated. */
+function isTerminated(status) {
+    return status < 0;
+}

package/build/system/mcp-servers/admin/escalations.js

@@ -223,10 +223,14 @@ function registerEscalationTools(server) {
         title: 'Accumulate Item',
         description: 'Add ONE item to an open accumulator escalation. Interim adds answer outcome "accepted" with the ' +
             'count held and remaining slots; the add that reaches max completes the row and wakes the waiting ' +
-            'workflow with the ordered collection. A reciprocal row is written in the same statement, both or neither.',
+            'workflow with the ordered collection. A reciprocal row is written in the same statement, both or neither. ' +
+            'initiatedBy credits the person the add is for.',
         inputSchema: schemas_1.accumulateItemSchema,
     }, async (args) => {
-        const result = await escalationApi.accumulateItem({ id: args.id, itemKey: args.itemKey, payload: args.payload, metadata: args.metadata, reciprocal: args.reciprocal }, await systemAuth());
+        const result = await escalationApi.accumulateItem({
+            id: args.id, itemKey: args.itemKey, payload: args.payload, metadata: args.metadata,
+            reciprocal: args.reciprocal, initiatedBy: args.initiatedBy,
+        }, await systemAuth());
         if (result.error) {
             return { content: [{ type: 'text', text: JSON.stringify({ error: result.error, ...(result.data ?? {}) }) }], isError: true };
         }
@@ -236,10 +240,10 @@ function registerEscalationTools(server) {
     server.registerTool('remove_item', {
         title: 'Remove Item',
         description: 'Remove ONE held item from a pending open accumulator escalation. The row stays pending and the ' +
-            'waiting workflow is never woken.',
+            'waiting workflow is never woken. initiatedBy credits the person the removal is for.',
         inputSchema: schemas_1.removeItemSchema,
     }, async (args) => {
-        const result = await escalationApi.removeItem({ id: args.id, itemKey: args.itemKey, reciprocal: args.reciprocal }, await systemAuth());
+        const result = await escalationApi.removeItem({ id: args.id, itemKey: args.itemKey, reciprocal: args.reciprocal, initiatedBy: args.initiatedBy }, await systemAuth());
         if (result.error) {
             return { content: [{ type: 'text', text: JSON.stringify({ error: result.error, ...(result.data ?? {}) }) }], isError: true };
         }

package/build/system/mcp-servers/admin/schemas.d.ts

@@ -219,10 +219,12 @@ export declare const accumulateItemSchema: z.ZodObject<{
         signalKey?: string | undefined;
         payload?: Record<string, any> | undefined;
     }>>;
+    initiatedBy: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     id: string;
     itemKey: string;
     metadata?: Record<string, any> | undefined;
+    initiatedBy?: string | undefined;
     payload?: Record<string, any> | undefined;
     reciprocal?: {
         key?: string | undefined;
@@ -235,6 +237,7 @@ export declare const accumulateItemSchema: z.ZodObject<{
     id: string;
     itemKey: string;
     metadata?: Record<string, any> | undefined;
+    initiatedBy?: string | undefined;
     payload?: Record<string, any> | undefined;
     reciprocal?: {
         key?: string | undefined;
@@ -264,9 +267,11 @@ export declare const removeItemSchema: z.ZodObject<{
         id?: string | undefined;
         signalKey?: string | undefined;
     }>>;
+    initiatedBy: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     id: string;
     itemKey: string;
+    initiatedBy?: string | undefined;
     reciprocal?: {
         key?: string | undefined;
         value?: string | undefined;
@@ -276,6 +281,7 @@ export declare const removeItemSchema: z.ZodObject<{
 }, {
     id: string;
     itemKey: string;
+    initiatedBy?: string | undefined;
     reciprocal?: {
         key?: string | undefined;
         value?: string | undefined;
@@ -1720,6 +1726,8 @@ export declare const findOrphanedSignalsSchema: z.ZodObject<{
 /** A faceted query over a pond — filter/sort by columns and metadata facets. */
 export declare const facetQuerySchema: z.ZodObject<{
     role: z.ZodString;
+    types: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    subtypes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     status: z.ZodOptional<z.ZodString>;
     available: z.ZodOptional<z.ZodBoolean>;
     facets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
@@ -1742,6 +1750,8 @@ export declare const facetQuerySchema: z.ZodObject<{
     facets?: Record<string, any> | undefined;
     limit?: number | undefined;
     offset?: number | undefined;
+    types?: string[] | undefined;
+    subtypes?: string[] | undefined;
     orderBy?: {
         column: string;
         direction: "asc" | "desc";
@@ -1753,6 +1763,8 @@ export declare const facetQuerySchema: z.ZodObject<{
     facets?: Record<string, any> | undefined;
     limit?: number | undefined;
     offset?: number | undefined;
+    types?: string[] | undefined;
+    subtypes?: string[] | undefined;
     orderBy?: {
         column: string;
         direction: "asc" | "desc";
@@ -1773,6 +1785,8 @@ export declare const resolveByIdsSchema: z.ZodObject<{
 }>;
 export declare const searchByFacetsSchema: z.ZodObject<{
     role: z.ZodString;
+    types: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    subtypes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     status: z.ZodOptional<z.ZodString>;
     available: z.ZodOptional<z.ZodBoolean>;
     facets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
@@ -1795,6 +1809,8 @@ export declare const searchByFacetsSchema: z.ZodObject<{
     facets?: Record<string, any> | undefined;
     limit?: number | undefined;
     offset?: number | undefined;
+    types?: string[] | undefined;
+    subtypes?: string[] | undefined;
     orderBy?: {
         column: string;
         direction: "asc" | "desc";
@@ -1806,6 +1822,8 @@ export declare const searchByFacetsSchema: z.ZodObject<{
     facets?: Record<string, any> | undefined;
     limit?: number | undefined;
     offset?: number | undefined;
+    types?: string[] | undefined;
+    subtypes?: string[] | undefined;
     orderBy?: {
         column: string;
         direction: "asc" | "desc";
@@ -1814,6 +1832,8 @@ export declare const searchByFacetsSchema: z.ZodObject<{
 export declare const claimGroupsSchema: z.ZodObject<{
     query: z.ZodObject<{
         role: z.ZodString;
+        types: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        subtypes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         status: z.ZodOptional<z.ZodString>;
         available: z.ZodOptional<z.ZodBoolean>;
         facets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
@@ -1836,6 +1856,8 @@ export declare const claimGroupsSchema: z.ZodObject<{
         facets?: Record<string, any> | undefined;
         limit?: number | undefined;
         offset?: number | undefined;
+        types?: string[] | undefined;
+        subtypes?: string[] | undefined;
         orderBy?: {
             column: string;
             direction: "asc" | "desc";
@@ -1847,6 +1869,8 @@ export declare const claimGroupsSchema: z.ZodObject<{
         facets?: Record<string, any> | undefined;
         limit?: number | undefined;
         offset?: number | undefined;
+        types?: string[] | undefined;
+        subtypes?: string[] | undefined;
         orderBy?: {
             column: string;
             direction: "asc" | "desc";
@@ -1863,6 +1887,8 @@ export declare const claimGroupsSchema: z.ZodObject<{
         facets?: Record<string, any> | undefined;
         limit?: number | undefined;
         offset?: number | undefined;
+        types?: string[] | undefined;
+        subtypes?: string[] | undefined;
         orderBy?: {
             column: string;
             direction: "asc" | "desc";
@@ -1879,6 +1905,8 @@ export declare const claimGroupsSchema: z.ZodObject<{
         facets?: Record<string, any> | undefined;
         limit?: number | undefined;
         offset?: number | undefined;
+        types?: string[] | undefined;
+        subtypes?: string[] | undefined;
         orderBy?: {
             column: string;
             direction: "asc" | "desc";
@@ -1891,6 +1919,8 @@ export declare const claimGroupsSchema: z.ZodObject<{
 export declare const claimByFacetsSchema: z.ZodObject<{
     query: z.ZodObject<{
         role: z.ZodString;
+        types: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        subtypes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         status: z.ZodOptional<z.ZodString>;
         available: z.ZodOptional<z.ZodBoolean>;
         facets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
@@ -1913,6 +1943,8 @@ export declare const claimByFacetsSchema: z.ZodObject<{
         facets?: Record<string, any> | undefined;
         limit?: number | undefined;
         offset?: number | undefined;
+        types?: string[] | undefined;
+        subtypes?: string[] | undefined;
         orderBy?: {
             column: string;
             direction: "asc" | "desc";
@@ -1924,6 +1956,8 @@ export declare const claimByFacetsSchema: z.ZodObject<{
         facets?: Record<string, any> | undefined;
         limit?: number | undefined;
         offset?: number | undefined;
+        types?: string[] | undefined;
+        subtypes?: string[] | undefined;
         orderBy?: {
             column: string;
             direction: "asc" | "desc";
@@ -1940,6 +1974,8 @@ export declare const claimByFacetsSchema: z.ZodObject<{
         facets?: Record<string, any> | undefined;
         limit?: number | undefined;
         offset?: number | undefined;
+        types?: string[] | undefined;
+        subtypes?: string[] | undefined;
         orderBy?: {
             column: string;
             direction: "asc" | "desc";
@@ -1956,6 +1992,8 @@ export declare const claimByFacetsSchema: z.ZodObject<{
         facets?: Record<string, any> | undefined;
         limit?: number | undefined;
         offset?: number | undefined;
+        types?: string[] | undefined;
+        subtypes?: string[] | undefined;
         orderBy?: {
             column: string;
             direction: "asc" | "desc";