@hotmeshio/long-tail 0.21.1 → 0.22.0

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/build/lib/db/index.d.ts

@@ -1,12 +1,17 @@
-import { Client, Pool } from 'pg';
+import { Client, Pool, type ClientConfig } from 'pg';
+/** `pg.Client` that carries an 'error' listener from construction. */
+declare class GuardedClient extends Client {
+    constructor(config?: string | ClientConfig);
+}
 export declare function getPool(): Pool;
 export declare function closePool(): Promise<void>;
 /**
- * HotMesh connection descriptor: `{ class: Client, options: postgres_options }`.
+ * HotMesh connection descriptor: `{ class: GuardedClient, options: postgres_options }`.
  * Use this everywhere HotMesh / Durable APIs need a connection config
  * instead of importing `pg` and `postgres_options` directly.
  */
 export declare function getConnection(): {
-    class: typeof Client;
+    class: typeof GuardedClient;
     options: Record<string, unknown>;
 };
+export {};

package/build/lib/db/index.js

@@ -5,10 +5,29 @@ exports.closePool = closePool;
 exports.getConnection = getConnection;
 const pg_1 = require("pg");
 const config_1 = require("../../modules/config");
+const logger_1 = require("../logger");
+/** A new connection that cannot be established within this window fails instead of hanging. */
+const CONNECT_TIMEOUT_MS = 10_000;
 let pool = null;
+/** A lost socket fails the pending query; its 'error' event must never end the process. */
+function onConnectionError(error) {
+    logger_1.loggerRegistry.debug(`[lt-db] connection error: ${error.message}`);
+}
+function onIdleConnectionLost(error) {
+    logger_1.loggerRegistry.warn(`[lt-db] pooled connection lost: ${error.message}`);
+}
+/** `pg.Client` that carries an 'error' listener from construction. */
+class GuardedClient extends pg_1.Client {
+    constructor(config) {
+        super(config);
+        this.on('error', onConnectionError);
+    }
+}
 function getPool() {
     if (!pool) {
         pool = new pg_1.Pool({
+            connectionTimeoutMillis: CONNECT_TIMEOUT_MS,
+            keepAlive: true,
             ...config_1.postgres_options,
             // Long-tail's shared tables live in public. Postgres's default
             // search_path is `"$user", public`: if any schema shares the connecting
@@ -20,6 +39,9 @@ function getPool() {
             // the engine fully qualifies its app schemas.
             options: '-c search_path=public',
         });
+        pool.on('error', onIdleConnectionLost);
+        // pg-pool drops its own listener while a client is checked out
+        pool.on('connect', (client) => client.on('error', onConnectionError));
     }
     return pool;
 }
@@ -30,10 +52,10 @@ async function closePool() {
     }
 }
 /**
- * HotMesh connection descriptor: `{ class: Client, options: postgres_options }`.
+ * HotMesh connection descriptor: `{ class: GuardedClient, options: postgres_options }`.
  * Use this everywhere HotMesh / Durable APIs need a connection config
  * instead of importing `pg` and `postgres_options` directly.
  */
 function getConnection() {
-    return { class: pg_1.Client, options: config_1.postgres_options };
+    return { class: GuardedClient, options: config_1.postgres_options };
 }

package/build/services/escalation/facets.js

@@ -36,7 +36,10 @@ function ensureFacetReady() {
         ready = (async () => {
             await (0, client_1.ensureEscalationCompatView)(); // hmsh_escalations + lt_escalations view
             await (0, db_1.getPool)().query(facet_sql_1.ENSURE_ORIGIN_INDEX);
-        })();
+        })().catch((err) => {
+            ready = null;
+            throw err;
+        });
     }
     return ready;
 }

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

@@ -704,13 +704,13 @@ export declare const patchUserPropertiesSchema: z.ZodObject<{
     rename: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
     user_id: string;
-    set?: Record<string, any> | undefined;
     remove?: string[] | undefined;
+    set?: Record<string, any> | undefined;
     rename?: Record<string, string> | undefined;
 }, {
     user_id: string;
-    set?: Record<string, any> | undefined;
     remove?: string[] | undefined;
+    set?: Record<string, any> | undefined;
     rename?: Record<string, string> | undefined;
 }>;
 export declare const listRolesSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;

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.22.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",
@@ -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.30.0",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@opentelemetry/exporter-trace-otlp-proto": "^0.215.0",
     "@opentelemetry/resources": "^2.5.1",