@hotmeshio/long-tail 0.17.2 → 0.18.0

package/docs/hitl/resolution.md

@@ -76,6 +76,39 @@ await lt.escalations.resolveBySignalKey({
 });
 ```
 
+### Batch items
+
+A batch escalation (a `conditional` wait declared with `batch: [...]` — see [Creating Escalations](escalation.md)) collects one submission per declared item key. Submit each item by id or by metadata facet:
+
+```typescript
+const first = await lt.escalations.resolveBatchItem({
+  id: escalationId,
+  itemKey: 'weld',
+  resolverPayload: { ok: true, notes: 'weld complete' },
+});
+// → { outcome: 'accepted', remaining: 2, escalationId }
+
+const second = await lt.escalations.resolveBatchItemBySignalKey({
+  signalKey: homeSignalId,           // the deterministic id the parent parked on
+  itemKey: 'weld',
+  resolverPayload: { ok: true },
+});
+
+const last = await lt.escalations.resolveBatchItemByMetadata({
+  key: 'orderId',
+  value: orderId,
+  itemKey: 'paint',
+  resolverPayload: { ok: true },
+});
+// → { outcome: 'completed', remaining: 0, signaled: true, workflowId }
+```
+
+Interim items return `accepted` with the remaining count and publish `escalation.updated` (progress rides `metadata.batch_pending`/`batch_count`); the LAST item returns `completed` — the row resolved with the assembled collection as `resolver_payload` and the workflow woke with it, in the same statement. Duplicate submissions return 409 (`duplicate-item`, safe under webhook retries); undeclared keys return 400.
+
+Each item validates against the same versioned role form a single-item resolve uses, canonical 422 included. Batch fills are claim-agnostic — a batch collects contributions from multiple principals, the same rationale as the signal-key path — while `assertClaim: true` (by-id form) opts into the caller's own live-claim assertion inside the guarded statement.
+
+Item keys are non-empty strings up to 128 characters; prefer URL-friendly names (`u1-L`). Payload keys inside each item are caller-owned — the platform reserves no names inside `batch_items` values. Every fill stamps `envelope.batch_filled_at[itemKey]` with the database clock in the same statement, so the row carries the collection timeline as row truth. After an SLA expiry (`conditional` returns `false`) the terminal row retains the partial `batch_items` and their timestamps — read them back with `GET /api/escalations/:id` or `getEscalationBySignalKey` from an activity.
+
 ### Resolving a set atomically
 
 When one decision settles a set of waits — each with its own payload — use `resolveAllOrNone`:

package/docs/sdk.md

@@ -63,7 +63,7 @@ The client mirrors the REST route structure:
 | Namespace | REST equivalent | Key operations |
 |-----------|----------------|----------------|
 | `lt.tasks` | `/api/tasks` | `list`, `get`, `listProcesses`, `getProcess`, `getProcessStats` |
-| `lt.escalations` | `/api/escalations` | `list`, `listAvailable`, `get`, `claim`, `release`, `resolve`, `escalate`, `bulkClaim`, `bulkAssign`, `findByMetadata`, `claimByMetadata`, `resolveByMetadata`, `aggregateByFacets`, `timelineByFacet` — see the [Escalations SDK reference](api/sdk/escalations.md) |
+| `lt.escalations` | `/api/escalations` | `list`, `listAvailable`, `get`, `claim`, `release`, `resolve`, `escalate`, `bulkClaim`, `bulkAssign`, `findByMetadata`, `claimByMetadata`, `resolveByMetadata`, `resolveBatchItem`, `resolveBatchItemBySignalKey`, `resolveBatchItemByMetadata`, `aggregateByFacets`, `timelineByFacet` — see the [Escalations SDK reference](api/sdk/escalations.md) |
 | `lt.workflows` | `/api/workflows` | `invoke`, `getStatus`, `getResult`, `terminate`, `listWorkers`, `listDiscovered`, `listConfigs`, `getConfig`, `upsertConfig` |
 | `lt.yamlWorkflows` | `/api/yaml-workflows` | `list`, `get`, `create`, `deploy`, `activate`, `invoke`, `archive` |
 | `lt.users` | `/api/users` | `list`, `get`, `create`, `update`, `delete`, `getRoles`, `addRole`, `removeRole` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/long-tail",
-  "version": "0.17.2",
+  "version": "0.18.0",
   "description": "Long Tail Workflows — Durable AI workflows with human-in-the-loop escalation. Powered by PostgreSQL.",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
@@ -73,7 +73,7 @@
     "@anthropic-ai/sdk": "^0.92.0",
     "@aws-sdk/client-s3": "^3.1017.0",
     "@aws-sdk/s3-request-presigner": "^3.1045.0",
-    "@hotmeshio/hotmesh": "^0.27.1",
+    "@hotmeshio/hotmesh": "^0.28.1",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@opentelemetry/exporter-trace-otlp-proto": "^0.215.0",
     "@opentelemetry/resources": "^2.5.1",

package/dashboard/dist/assets/metadata-display-DHjqWkLG.js

@@ -1,2 +0,0 @@
-const s=new Set(["form_schema"]);function a(e){return Object.entries(e??{}).filter(([t])=>!t.startsWith("_")&&!s.has(t))}export{a as d};
-//# sourceMappingURL=metadata-display-DHjqWkLG.js.map

package/dashboard/dist/assets/metadata-display-DHjqWkLG.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"metadata-display-DHjqWkLG.js","sources":["../../src/lib/metadata-display.ts"],"sourcesContent":["/** Metadata keys that are plumbing, not information for the person working the item. */\nconst HIDDEN_METADATA_KEYS = new Set(['form_schema']);\n\n/**\n * The metadata entries a person should see: platform plumbing (the embedded\n * form schema, underscore-prefixed keys) is filtered out of every facet\n * listing — the side panel, the scan info-choice screen, and any future\n * surface that walks a row's metadata.\n */\nexport function displayMetadataEntries(\n  metadata: Record<string, unknown> | null | undefined,\n): [string, unknown][] {\n  return Object.entries(metadata ?? {}).filter(\n    ([k]) => !k.startsWith('_') && !HIDDEN_METADATA_KEYS.has(k),\n  );\n}\n"],"names":["HIDDEN_METADATA_KEYS","displayMetadataEntries","metadata","k"],"mappings":"AACA,MAAMA,EAAuB,IAAI,IAAI,CAAC,aAAa,CAAC,EAQ7C,SAASC,EACdC,EACqB,CACrB,OAAO,OAAO,QAAQA,GAAY,CAAA,CAAE,EAAE,OACpC,CAAC,CAACC,CAAC,IAAM,CAACA,EAAE,WAAW,GAAG,GAAK,CAACH,EAAqB,IAAIG,CAAC,CAAA,CAE9D"}