@hotmeshio/long-tail 0.21.1 → 0.21.2

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

@@ -46,8 +46,11 @@ export declare function accumulateItemBySignalKey(input: {
 } & Omit<AccumulateItemInput, 'assertClaim'>, auth: LTApiAuth): Promise<LTApiResult>;
 /**
  * Add selecting the container by metadata facet, the faceted sibling of
- * {@link accumulateItem}. RBAC folds into the SDK's atomic facet selection
- * as a flat role filter. Schema enforcement is two-phase when enforcing
+ * {@link accumulateItem}. The facet names a container, so only pending rows
+ * carrying the accumulator declaration are candidates: a release or
+ * remediation row that shares the facet is never picked, and when no open
+ * container shares it the answer is 404. RBAC folds into the SDK's atomic
+ * facet selection as a flat role filter. Schema enforcement is two-phase when enforcing
  * roles exist and a payload is present: the row is picked first, validated
  * against ITS schema, then written by asserted id; a row that went terminal
  * between phases surfaces as a 409.

package/build/api/escalations/accumulate.js

@@ -65,6 +65,25 @@ function isAccumulator(escalation) {
 function isBatch(escalation) {
     return Array.isArray(escalation.metadata?.[escalation_1.ESCALATION_BATCH_KEYS.PENDING]);
 }
+const NO_ACCUMULATOR_FOR_FACET = 'No pending accumulator found for this metadata';
+/**
+ * The container a facet names: the highest priority pending row that carries
+ * the facet AND the accumulator declaration, within the given roles (null =
+ * unscoped). A release or remediation row sharing the facet is never a
+ * candidate, so a by-facet add lands on the open container or nowhere.
+ */
+async function pickAccumulatorByFacet(key, value, roles) {
+    if (roles !== null && roles.length === 0)
+        return null;
+    const found = await escalationService.searchByFacets({
+        roles: roles ?? undefined,
+        facets: { [key]: value },
+        status: 'pending',
+        exists: [escalation_1.ESCALATION_ACCUMULATE_KEYS.COUNT],
+        limit: 1,
+    });
+    return found.escalations[0] ?? null;
+}
 function reciprocalSelectorCount(r) {
     return (r.id ? 1 : 0) + (r.signalKey ? 1 : 0) + (r.key !== undefined ? 1 : 0);
 }
@@ -89,8 +108,7 @@ async function gateReciprocal(input, auth) {
     }
     else {
         const writeScope = await (0, helpers_1.getEscalationWriteScope)(auth.userId);
-        const found = await escalationService.findByMetadata(input.key, String(input.value), 'pending', 1, 0, writeScope.global ? undefined : { allRoles: writeScope.allRoles, meUserId: auth.userId });
-        row = found.escalations[0] ?? null;
+        row = await pickAccumulatorByFacet(input.key, String(input.value), writeScope.global ? null : writeScope.allRoles);
     }
     if (!row)
         return { error: { status: 404, error: 'Reciprocal escalation not found' } };
@@ -220,8 +238,11 @@ async function accumulateItemBySignalKey(input, auth) {
 }
 /**
  * Add selecting the container by metadata facet, the faceted sibling of
- * {@link accumulateItem}. RBAC folds into the SDK's atomic facet selection
- * as a flat role filter. Schema enforcement is two-phase when enforcing
+ * {@link accumulateItem}. The facet names a container, so only pending rows
+ * carrying the accumulator declaration are candidates: a release or
+ * remediation row that shares the facet is never picked, and when no open
+ * container shares it the answer is 404. RBAC folds into the SDK's atomic
+ * facet selection as a flat role filter. Schema enforcement is two-phase when enforcing
  * roles exist and a payload is present: the row is picked first, validated
  * against ITS schema, then written by asserted id; a row that went terminal
  * between phases surfaces as a 409.
@@ -251,12 +272,13 @@ async function accumulateItemByMetadata(input, auth) {
                 roles: allowedRoles ?? undefined,
                 reciprocal: reciprocal.reciprocal,
             });
+            if (result.outcome === 'not-found')
+                return { status: 404, error: NO_ACCUMULATOR_FOR_FACET };
             return accumulateOutcomeResult(result, itemKey, result.escalation?.workflow_id ?? null);
         }
-        const found = await escalationService.findByMetadata(key, value, 'pending', 1, 0, allowedRoles === null ? undefined : { allRoles: allowedRoles, meUserId: auth.userId });
-        const row = found.escalations[0];
+        const row = await pickAccumulatorByFacet(key, value, allowedRoles);
         if (!row)
-            return { status: 404, error: 'No pending escalation found for this metadata' };
+            return { status: 404, error: NO_ACCUMULATOR_FOR_FACET };
         if (!isAccumulator(row))
             return { status: 400, error: 'Escalation is not an accumulator' };
         const payload = await gatePayload(row, input.payload, auth.userId);
@@ -358,6 +380,8 @@ async function removeItemByMetadata(input, auth) {
         const result = await escalationService.removeAccumulatedItemByMetadata(key, value, {
             itemKey, actor: auth.userId, roles: allowedRoles ?? undefined, reciprocal: reciprocal.reciprocal,
         });
+        if (result.outcome === 'not-found')
+            return { status: 404, error: NO_ACCUMULATOR_FOR_FACET };
         return removeOutcomeResult(result, itemKey);
     }
     catch (err) {

package/docs/accumulator.md

@@ -67,6 +67,8 @@ A batch wait may add `partialOnTimeout: true`; it stores `envelope.batch_partial
 | Read the collection | `GET /api/escalations/:id/items`, `GET /api/escalations/items-by-signal-key` | `getItems`, `getItemsBySignalKey` | `get_escalation_items` (admin; `id` or `signalKey`) |
 | Scan | the `accumulate` verb; item mode answers `no_open_container` when the container closed; templates read `{claim.<facet>}` and `{item.<facet>}` | | |
 
+A facet selector (`accumulateByMetadata`, `removeItemByMetadata`, a reciprocal named by `key` + `value`, the scan verb's item mode) considers only pending rows that carry the accumulator declaration, ordered by priority then age. A release or remediation row sharing the container's facet is never picked; with no open container the answer is `not-found`, and the scan answers `no_open_container`.
+
 An add takes `itemKey` (1 to 128 characters), an optional `payload` (validated against the container role's versioned form when present), an optional `metadata` patch (reserved keys rejected), `assertClaim` (by id), and an optional `reciprocal`.
 
 ### Outcomes
@@ -78,7 +80,7 @@ An add takes `itemKey` (1 to 128 characters), an optional `payload` (validated a
 | `duplicate-item` | 409 | the key is already held (`unique`), row untouched |
 | `full` | 409 | `max` held and the key is new (`resolveAtMax: false`, or a race with the completing add) |
 | `not-accumulator` | 400 | the row carries no `accumulate` declaration |
-| `not-found` | 404 | unknown row, or outside the caller's scope on the ingress forms |
+| `not-found` | 404 | unknown row, outside the caller's scope on the ingress forms, or (by facet) no pending accumulator shares the facet; rows without the declaration are never candidates |
 | `already-resolved`, `already-expired`, `already-cancelled` | 409 | the row is terminal |
 | `claimed-by-other`, `claim-expired` | 409 | the `assertClaim` assertion failed |
 | `reciprocal-not-found` | 404 | the reciprocal selector matched nothing the caller may act on |
@@ -110,4 +112,4 @@ Every accepted add and removal publishes `escalation.updated` for the container
 
 ## Versions
 
-HotMesh 0.29.0 (`accumulate`, `partialOnTimeout`, timeout delivery, reciprocal statement) and long-tail 0.21.1 (root export of `conditionalAccumulator`, `no_open_container`, claim and item template tokens, items by signal key).
+HotMesh 0.29.0 (`accumulate`, `partialOnTimeout`, timeout delivery, reciprocal statement) and long-tail 0.21.1 (root export of `conditionalAccumulator`, `no_open_container`, claim and item template tokens, items by signal key); HotMesh 0.29.1 and long-tail 0.21.2 (facet selectors pick pending accumulators only).

package/docs/api/http/escalations.md

@@ -1166,7 +1166,7 @@ Add ONE item to an open accumulator escalation (a `conditionalAccumulator` wait
 | `assertClaim` | `boolean` | By id only. Require the caller's own live claim, asserted atomically |
 | `reciprocal` | `object` | A second accumulator row written in the same statement, both or neither. Exactly one of `id`, `signalKey`, or `key` + `value`; optional `payload` stored on its entry |
 
-**By signal key:** `{ signalKey, itemKey, payload?, metadata?, reciprocal? }`. **By metadata:** `{ key, value, itemKey, payload?, metadata?, restrictRoles?, reciprocal? }` selects the highest priority pending accumulator whose metadata contains the key/value, within the caller's write scope intersected with `restrictRoles`.
+**By signal key:** `{ signalKey, itemKey, payload?, metadata?, reciprocal? }`. **By metadata:** `{ key, value, itemKey, payload?, metadata?, restrictRoles?, reciprocal? }` selects the highest priority pending accumulator whose metadata contains the key/value, within the caller's write scope intersected with `restrictRoles`. Only rows carrying the accumulator declaration are candidates: a release or remediation row that shares the facet is never picked, and when no open container shares it the answer is 404 `No pending accumulator found for this metadata`. The same rule selects a reciprocal named by `key` + `value`.
 
 **Response 200 (interim):**
 

package/docs/api/sdk/escalations.md

@@ -887,7 +887,7 @@ await lt.escalations.accumulateByMetadata({ key: 'binKey', value: binKey, itemKe
 | `metadata` | `object` | No | Merge patch for the container metadata, same statement; reserved `accumulate_*` keys rejected |
 | `assertClaim` | `boolean` | No | By id only: require the caller's own live claim |
 | `reciprocal` | `object` | No | `{ id \| signalKey \| key + value, payload? }`: a second accumulator row written in the same statement, both or neither |
-| `restrictRoles` | `string[]` | No | By metadata only: expected queues, intersected with the caller's write scope |
+| `restrictRoles` | `string[]` | No | By metadata only: expected queues, intersected with the caller's write scope. The facet selects among pending accumulator rows only; other rows sharing it are never candidates, and none open answers 404 |
 
 **Returns:** `LTApiResult<{ outcome: 'accepted' \| 'completed', count, remaining, escalationId, signaled?, workflowId?, reciprocal? }>`. `remaining` is `null` on an unbounded accumulator. 409 on `Item already held`, `Accumulator is full`, claim blocks, terminal rows, and reciprocal blocks; 400 on a non-accumulator; 404 non-disclosure.
 

package/docs/scan-codes.md

@@ -118,7 +118,9 @@ through the scheme facet, reads that facet from the row (a bag row carrying
 `binKey: "B-7"`), and adds the target to the pending accumulator whose
 metadata carries the same value, writing the item's row as the reciprocal in
 the same statement (`reciprocal: false` skips it; `containerRoles` names the
-container queues). Without it the scanned target is the CONTAINER and the step
+container queues). The container pick considers only pending rows that carry
+the accumulator declaration, so a release row sharing the facet during a
+pack-out is never the target. Without it the scanned target is the CONTAINER and the step
 adds `params.itemKey` (a template) to it. An item with no row or no container
 facet falls through to the next step; a container already holding the item
 reports a conflict. When the item's row exists but no pending container

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/long-tail",
-  "version": "0.21.1",
+  "version": "0.21.2",
   "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",
@@ -75,7 +75,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.29.0",
+    "@hotmeshio/hotmesh": "^0.29.1",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@opentelemetry/exporter-trace-otlp-proto": "^0.215.0",
     "@opentelemetry/resources": "^2.5.1",