@hotmeshio/long-tail 0.22.0 → 0.22.2

package/build/index.d.ts

@@ -12,6 +12,7 @@ export * as TaskService from './services/task';
 export * as EscalationService from './services/escalation';
 export * as ConfigService from './services/config';
 export * as UserService from './services/user';
+export { assertValidScheme as assertValidScanScheme, assertValidSteps as assertValidScanSteps, assertValidIdentityRule as assertValidScanIdentityRule, isValidGtin, normalizeGtin, type ScanSchemeInput, type ScanRuleInput, } from './services/scan-code';
 export * as TopicService from './services/topics';
 export { seedSystemTopics, seedConfigTopics } from './services/topics/system-topics';
 export { ltConfig } from './modules/ltconfig';

package/build/index.js

@@ -36,8 +36,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.McpEscalationStrategy = exports.DefaultEscalationStrategy = exports.escalationStrategyRegistry = exports.McpVisionServer = exports.McpTranslationServer = exports.McpServer = exports.McpClient = exports.McpService = exports.BuiltInMcpAdapter = exports.mcpRegistry = exports.defaultMaintenanceConfig = exports.maintenanceRegistry = exports.PinoLoggerAdapter = exports.loggerRegistry = exports.HoneycombTelemetryAdapter = exports.telemetryRegistry = exports.publishKnowledgeEvent = exports.publishAgentEvent = exports.publishWorkflowEvent = exports.publishActivityEvent = exports.publishEscalationEvent = exports.publishTaskEvent = exports.publishMilestoneEvent = exports.SocketIOEventAdapter = exports.InMemoryEventAdapter = exports.NatsEventAdapter = exports.eventRegistry = exports.ltConfig = exports.seedConfigTopics = exports.seedSystemTopics = exports.TopicService = exports.UserService = exports.ConfigService = exports.EscalationService = exports.TaskService = exports.setAuthAdapter = exports.signToken = exports.requireAdmin = exports.requireAuth = exports.createAuthMiddleware = exports.JwtAuthAdapter = exports.conditionalAccumulator = exports.conditionLT = exports.conditional = exports.executeLT = exports.createLTActivityInterceptor = exports.createLTInterceptor = exports.registerLT = exports.midnightTheme = exports.start = void 0;
-exports.LTExpressAdapter = exports.api = exports.KnowledgeApi = exports.resolveCredential = exports.mimeFromPath = exports.getStorageBackend = exports.listOAuthConnections = exports.getFreshAccessToken = exports.createClient = exports.CallbackEventAdapter = exports.builtinMcpServerFactories = exports.getSystemAgents = exports.getSystemWorkers = exports.registerMcpTool = exports.getToolContext = exports.getActivityIdentity = void 0;
+exports.McpServer = exports.McpClient = exports.McpService = exports.BuiltInMcpAdapter = exports.mcpRegistry = exports.defaultMaintenanceConfig = exports.maintenanceRegistry = exports.PinoLoggerAdapter = exports.loggerRegistry = exports.HoneycombTelemetryAdapter = exports.telemetryRegistry = exports.publishKnowledgeEvent = exports.publishAgentEvent = exports.publishWorkflowEvent = exports.publishActivityEvent = exports.publishEscalationEvent = exports.publishTaskEvent = exports.publishMilestoneEvent = exports.SocketIOEventAdapter = exports.InMemoryEventAdapter = exports.NatsEventAdapter = exports.eventRegistry = exports.ltConfig = exports.seedConfigTopics = exports.seedSystemTopics = exports.TopicService = exports.normalizeGtin = exports.isValidGtin = exports.assertValidScanIdentityRule = exports.assertValidScanSteps = exports.assertValidScanScheme = exports.UserService = exports.ConfigService = exports.EscalationService = exports.TaskService = exports.setAuthAdapter = exports.signToken = exports.requireAdmin = exports.requireAuth = exports.createAuthMiddleware = exports.JwtAuthAdapter = exports.conditionalAccumulator = exports.conditionLT = exports.conditional = exports.executeLT = exports.createLTActivityInterceptor = exports.createLTInterceptor = exports.registerLT = exports.midnightTheme = exports.start = void 0;
+exports.LTExpressAdapter = exports.api = exports.KnowledgeApi = exports.resolveCredential = exports.mimeFromPath = exports.getStorageBackend = exports.listOAuthConnections = exports.getFreshAccessToken = exports.createClient = exports.CallbackEventAdapter = exports.builtinMcpServerFactories = exports.getSystemAgents = exports.getSystemWorkers = exports.registerMcpTool = exports.getToolContext = exports.getActivityIdentity = exports.McpEscalationStrategy = exports.DefaultEscalationStrategy = exports.escalationStrategyRegistry = exports.McpVisionServer = exports.McpTranslationServer = void 0;
 const config_1 = require("./modules/config");
 const logger_1 = require("./lib/logger");
 const midnight_1 = require("./themes/midnight");
@@ -70,6 +70,12 @@ exports.TaskService = __importStar(require("./services/task"));
 exports.EscalationService = __importStar(require("./services/escalation"));
 exports.ConfigService = __importStar(require("./services/config"));
 exports.UserService = __importStar(require("./services/user"));
+var scan_code_1 = require("./services/scan-code");
+Object.defineProperty(exports, "assertValidScanScheme", { enumerable: true, get: function () { return scan_code_1.assertValidScheme; } });
+Object.defineProperty(exports, "assertValidScanSteps", { enumerable: true, get: function () { return scan_code_1.assertValidSteps; } });
+Object.defineProperty(exports, "assertValidScanIdentityRule", { enumerable: true, get: function () { return scan_code_1.assertValidIdentityRule; } });
+Object.defineProperty(exports, "isValidGtin", { enumerable: true, get: function () { return scan_code_1.isValidGtin; } });
+Object.defineProperty(exports, "normalizeGtin", { enumerable: true, get: function () { return scan_code_1.normalizeGtin; } });
 exports.TopicService = __importStar(require("./services/topics"));
 var system_topics_1 = require("./services/topics/system-topics");
 Object.defineProperty(exports, "seedSystemTopics", { enumerable: true, get: function () { return system_topics_1.seedSystemTopics; } });

package/build/lib/cli/commands/workflows.js

@@ -45,6 +45,7 @@ exports.terminateWorkflow = terminateWorkflow;
 const picocolors_1 = __importDefault(require("picocolors"));
 const client_1 = require("../client");
 const format_1 = require("../format");
+const workflow_state_1 = require("../../../shared/workflow-state");
 const COLUMNS = [
     { key: 'workflow_type', label: 'Type', width: 24 },
     { key: 'task_queue', label: 'Queue', width: 16 },
@@ -72,13 +73,17 @@ async function invokeWorkflow(type, opts) {
     console.log(`\n  ${picocolors_1.default.green('✓')} Started ${picocolors_1.default.bold(type)} → ${picocolors_1.default.dim(data.workflowId)}\n`);
 }
 async function getWorkflowStatus(id, opts) {
-    const data = await (0, client_1.apiFetch)(`/workflows/status/${id}`);
+    const data = await (0, client_1.apiFetch)(`/workflows/${encodeURIComponent(id)}/status`);
     if (opts.json) {
         console.log(JSON.stringify(data, null, 2));
         return;
     }
-    const status = data.status === 0 ? picocolors_1.default.green('completed') : picocolors_1.default.blue('running');
-    console.log(`\n  ${data.workflowId}  ${status}\n`);
+    const state = data.state === workflow_state_1.WORKFLOW_STATES.COMPLETED
+        ? picocolors_1.default.green('completed')
+        : data.state === workflow_state_1.WORKFLOW_STATES.FAILED
+            ? picocolors_1.default.red(data.terminated ? 'failed (terminated)' : 'failed')
+            : picocolors_1.default.blue('running');
+    console.log(`\n  ${data.workflowId}  ${state}${data.error ? picocolors_1.default.dim(`  ${data.error}`) : ''}\n`);
 }
 async function getWorkflowResult(id, opts) {
     const { server, token } = await (await Promise.resolve().then(() => __importStar(require('../auth')))).resolveAuth();
@@ -121,6 +126,6 @@ async function getWorkflowEnvelopes(id, opts) {
     console.log();
 }
 async function terminateWorkflow(id) {
-    await (0, client_1.apiFetch)(`/workflows/terminate/${id}`, { method: 'POST' });
+    await (0, client_1.apiFetch)(`/workflows/${encodeURIComponent(id)}/terminate`, { method: 'POST' });
     console.log(`\n  ${picocolors_1.default.green('✓')} Terminated ${picocolors_1.default.dim(id)}\n`);
 }

package/build/lib/db/schemas/037_scan_gtin_and_subject_grants.sql

@@ -0,0 +1,27 @@
+-- Migration 037: GTIN scan schemes and subject-bound acting grants
+--
+-- encoding 'gtin': a scheme whose codes are manufacturer barcodes (UPC-A,
+-- EAN-13, EAN-8, GTIN-14). The code carries no scheme or category; the
+-- check digit identifies it, and the scheme's single rule is category '0'.
+--
+-- grant_scope (identity kind only):
+--   'action'  each mutating act spends one use of the grant.
+--   'subject' the first act binds the grant to the held subject (the item
+--             the station is holding); further acts on that same subject do
+--             not count, and the grant cannot act on any other subject.
+--
+-- lt_ephemeral_credentials.bind_on_use / bound_ref carry that binding.
+
+ALTER TABLE lt_config_scan_schemes
+  DROP CONSTRAINT IF EXISTS lt_config_scan_schemes_encoding_check;
+ALTER TABLE lt_config_scan_schemes
+  ADD CONSTRAINT lt_config_scan_schemes_encoding_check
+    CHECK (encoding IN ('fixed', 'delimited', 'gtin'));
+
+ALTER TABLE lt_config_scan_schemes
+  ADD COLUMN IF NOT EXISTS grant_scope TEXT NOT NULL DEFAULT 'action'
+    CHECK (grant_scope IN ('action', 'subject'));
+
+ALTER TABLE lt_ephemeral_credentials
+  ADD COLUMN IF NOT EXISTS bind_on_use BOOLEAN NOT NULL DEFAULT FALSE,
+  ADD COLUMN IF NOT EXISTS bound_ref TEXT;

package/build/routes/escalations/accumulate.js

@@ -45,7 +45,7 @@ function registerAccumulateRoutes(router) {
     /**
      * POST /api/escalations/accumulate-by-signal-key
      * Add one item to an accumulator escalation by its signal_key.
-     * Body: { signalKey, itemKey, payload?, metadata?, reciprocal? }
+     * Body: { signalKey, itemKey, payload?, metadata?, reciprocal?, initiatedBy? }
      */
     router.post('/accumulate-by-signal-key', async (req, res) => {
         const result = await api.accumulateItemBySignalKey({
@@ -54,6 +54,7 @@ function registerAccumulateRoutes(router) {
             payload: req.body?.payload,
             metadata: req.body?.metadata,
             reciprocal: req.body?.reciprocal,
+            initiatedBy: req.body?.initiatedBy,
         }, req.auth);
         res.status(result.status).json(result.data ?? { error: result.error });
     });
@@ -61,7 +62,7 @@ function registerAccumulateRoutes(router) {
      * POST /api/escalations/accumulate-by-metadata
      * Add one item to the highest priority pending accumulator whose metadata
      * contains the key/value.
-     * Body: { key, value, itemKey, payload?, metadata?, restrictRoles?, reciprocal? }
+     * Body: { key, value, itemKey, payload?, metadata?, restrictRoles?, container?, reciprocal?, initiatedBy? }
      */
     router.post('/accumulate-by-metadata', async (req, res) => {
         const result = await api.accumulateItemByMetadata({
@@ -71,25 +72,28 @@ function registerAccumulateRoutes(router) {
             payload: req.body?.payload,
             metadata: req.body?.metadata,
             restrictRoles: req.body?.restrictRoles,
+            container: req.body?.container,
             reciprocal: req.body?.reciprocal,
+            initiatedBy: req.body?.initiatedBy,
         }, req.auth);
         res.status(result.status).json(result.data ?? { error: result.error });
     });
     /**
      * POST /api/escalations/remove-item-by-signal-key
-     * Body: { signalKey, itemKey, reciprocal? }
+     * Body: { signalKey, itemKey, reciprocal?, initiatedBy? }
      */
     router.post('/remove-item-by-signal-key', async (req, res) => {
         const result = await api.removeItemBySignalKey({
             signalKey: req.body?.signalKey,
             itemKey: req.body?.itemKey,
             reciprocal: req.body?.reciprocal,
+            initiatedBy: req.body?.initiatedBy,
         }, req.auth);
         res.status(result.status).json(result.data ?? { error: result.error });
     });
     /**
      * POST /api/escalations/remove-item-by-metadata
-     * Body: { key, value, itemKey, restrictRoles?, reciprocal? }
+     * Body: { key, value, itemKey, restrictRoles?, reciprocal?, initiatedBy? }
      */
     router.post('/remove-item-by-metadata', async (req, res) => {
         const result = await api.removeItemByMetadata({
@@ -98,6 +102,7 @@ function registerAccumulateRoutes(router) {
             itemKey: req.body?.itemKey,
             restrictRoles: req.body?.restrictRoles,
             reciprocal: req.body?.reciprocal,
+            initiatedBy: req.body?.initiatedBy,
         }, req.auth);
         res.status(result.status).json(result.data ?? { error: result.error });
     });
@@ -115,7 +120,7 @@ function registerAccumulateRoutes(router) {
      * the add that reaches max answers { outcome: 'completed', signaled } and the
      * waiting workflow resumes with the collection. Claim-agnostic unless
      * assertClaim: true.
-     * Body: { itemKey, payload?, metadata?, assertClaim?, reciprocal? }
+     * Body: { itemKey, payload?, metadata?, assertClaim?, reciprocal?, initiatedBy? }
      */
     router.post('/:id/accumulate', async (req, res) => {
         const auth = await (0, acting_1.effectiveWorkAuth)(req, res);
@@ -128,13 +133,14 @@ function registerAccumulateRoutes(router) {
             metadata: req.body?.metadata,
             assertClaim: req.body?.assertClaim,
             reciprocal: req.body?.reciprocal,
+            initiatedBy: req.body?.initiatedBy,
         }, auth);
         res.status(result.status).json(result.data ?? { error: result.error });
     });
     /**
      * POST /api/escalations/:id/remove-item
      * Remove one held item; the row stays pending and the waiter never wakes.
-     * Body: { itemKey, reciprocal? }
+     * Body: { itemKey, reciprocal?, initiatedBy? }
      */
     router.post('/:id/remove-item', async (req, res) => {
         const auth = await (0, acting_1.effectiveWorkAuth)(req, res);
@@ -144,6 +150,7 @@ function registerAccumulateRoutes(router) {
             id: req.params.id,
             itemKey: req.body?.itemKey,
             reciprocal: req.body?.reciprocal,
+            initiatedBy: req.body?.initiatedBy,
         }, auth);
         res.status(result.status).json(result.data ?? { error: result.error });
     });

package/build/routes/escalations/acting.d.ts

@@ -2,6 +2,11 @@ import type { Request, Response } from 'express';
 import type { LTApiAuth } from '../../types/sdk';
 /** The header a shared station device rides its badge grant on. */
 export declare const ACTING_TOKEN_HEADER = "x-lt-acting-token";
+/**
+ * Uses the grant has left after this request spent one: a count, or
+ * `unbounded` while only the TTL limits it. The client retires its grant on 0.
+ */
+export declare const ACTING_REMAINING_HEADER = "x-lt-acting-remaining";
 /**
  * The effective actor for an escalation WORK verb (claim, release, resolve):
  * the badged person when an acting grant rides the request, otherwise the

package/build/routes/escalations/acting.js

@@ -1,10 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ACTING_TOKEN_HEADER = void 0;
+exports.ACTING_REMAINING_HEADER = exports.ACTING_TOKEN_HEADER = void 0;
 exports.effectiveWorkAuth = effectiveWorkAuth;
 const acting_identity_1 = require("../../services/iam/acting-identity");
 /** The header a shared station device rides its badge grant on. */
 exports.ACTING_TOKEN_HEADER = 'x-lt-acting-token';
+/**
+ * Uses the grant has left after this request spent one: a count, or
+ * `unbounded` while only the TTL limits it. The client retires its grant on 0.
+ */
+exports.ACTING_REMAINING_HEADER = 'x-lt-acting-remaining';
 /**
  * The effective actor for an escalation WORK verb (claim, release, resolve):
  * the badged person when an acting grant rides the request, otherwise the
@@ -21,5 +26,7 @@ async function effectiveWorkAuth(req, res) {
         res.status(401).json({ error: resolved.error });
         return null;
     }
+    const { remaining } = resolved.grant;
+    res.setHeader(exports.ACTING_REMAINING_HEADER, remaining === null ? 'unbounded' : String(remaining));
     return resolved.auth;
 }

package/build/routes/scan-codes.js

@@ -49,6 +49,8 @@ router.post('/execute', async (req, res) => {
         code: req.body.code,
         actingToken: req.body.actingToken,
         previousActingToken: req.body.previousActingToken,
+        subject: req.body.subject,
+        stationRole: req.body.stationRole,
     }, req.auth);
     res.status(result.status).json(result.data ?? { error: result.error });
 });
@@ -102,6 +104,7 @@ router.put('/schemes/:version', auth_1.requireRoleManager, async (req, res) => {
         kind: req.body.kind,
         grant_ttl_seconds: req.body.grant_ttl_seconds,
         grant_max_uses: req.body.grant_max_uses,
+        grant_scope: req.body.grant_scope,
         enabled: req.body.enabled,
     });
     res.status(result.status).json(result.data ?? { error: result.error });

package/build/sdk/index.d.ts

@@ -222,6 +222,8 @@ export declare function createClient(options?: LTClientOptions): {
             metadata?: Record<string, any>;
             restrictRoles?: string[];
             extraFacets?: Record<string, any>;
+            availability?: import("..").ScanAvailability;
+            assertId?: string;
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         resolveBatchItem: (input: {
             id: string;
@@ -254,6 +256,7 @@ export declare function createClient(options?: LTClientOptions): {
             key: string;
             value: string;
             restrictRoles?: string[];
+            container?: import("..").ContainerSelector;
         } & Omit<import("../api/escalations/accumulate").AccumulateItemInput, "assertClaim">, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         removeItem: (input: {
             id: string;

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/iam/acting-identity.d.ts

@@ -1,16 +1,41 @@
 import type { LTApiAuth } from '../../types/sdk';
+/** What the client needs to know about a grant after a request touched it. */
+export interface ActingGrantState {
+    /** True when this request spent a use. */
+    consumed: boolean;
+    /** Uses left; null = bounded only by TTL (or bound to one subject). */
+    remaining: number | null;
+    /** True once the grant is bound to one subject. */
+    bound: boolean;
+}
 /** The acting-auth resolution result: an auth to act as, or the loud reason not to. */
 export type ActingAuthResult = {
     ok: true;
     auth: LTApiAuth;
+    grant: ActingGrantState;
 } | {
     ok: false;
     error: string;
 };
+export declare const ACTING_ERRORS: {
+    readonly NOT_A_GRANT: "actingToken is not an acting-identity grant";
+    readonly EXPIRED: "acting identity expired — scan your badge again";
+    readonly INACTIVE: "acting identity is no longer an active user";
+    readonly OTHER_SUBJECT: "this badge already acted on another item; scan your badge again";
+};
+/**
+ * Read a supplied acting grant without spending it. A token that fails
+ * (wrong label, expired, exhausted, or a vanished user) is a terminal error,
+ * never a silent fall-back to the session identity: that would misattribute
+ * whatever follows.
+ */
+export declare function peekActingAuth(actingToken: string): Promise<ActingAuthResult>;
 /**
- * Exchange a supplied acting grant for the person it names. A supplied token
- * that fails — wrong label, expired, exhausted, or a vanished user — is a
- * terminal error, never a silent fall-back to the session identity: that
- * would misattribute whatever follows.
+ * Spend one use of the grant for an act. `ref` names the subject the act
+ * lands on; a subject-scoped grant binds to it on first spend.
  */
+export declare function consumeActingGrant(actingToken: string, ref?: string | null): Promise<ActingAuthResult>;
+/** Return a use whose act missed. `unbind` when that spend bound the grant. */
+export declare function refundActingGrant(actingToken: string, unbind: boolean): Promise<void>;
+/** Spend the grant up front: the escalation work routes always act. */
 export declare function resolveActingAuth(actingToken: string): Promise<ActingAuthResult>;