@hotmeshio/hotmesh 0.26.0 → 0.26.1

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.26.0",
+    "version": "0.26.1",
     "description": "Durable Workflow",
     "main": "./build/index.js",
     "types": "./build/index.d.ts",

package/build/services/durable/handle.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WorkflowHandleService = void 0;
+const utils_1 = require("../../modules/utils");
 const exporter_1 = require("./exporter");
 /**
  * Handle to a running or completed workflow execution. Returned by
@@ -253,8 +254,13 @@ class WorkflowHandleService {
                     return complete(null, JSON.parse(state.metadata.err));
                 }
             }
-            //subscribe to 'done' topic
-            this.hotMesh.sub(topic, async (_topic, state) => {
+            //subscribe to 'done' topic. Await the registration: the getStatus
+            //fallback below only covers completions that land BEFORE it reads.
+            //Unawaited, a job that completes after the status read but before
+            //the subscription goes active is seen by neither arm and result()
+            //never settles — hit reliably when a bulk resolve completes many
+            //workflows in the same instant.
+            await this.hotMesh.sub(topic, async (_topic, state) => {
                 this.hotMesh.unsub(topic);
                 if (state.data.done && !state.data?.$error) {
                     await complete(state.data?.response);
@@ -267,10 +273,43 @@ class WorkflowHandleService {
                     return await complete(null, error);
                 }
             });
-            //check state in case completed during wiring
-            const status = await this.hotMesh.getStatus(this.workflowId);
-            if (status <= 0) {
-                await complete();
+            //check state in case completed during wiring. One read is not
+            //enough: the executed event commits before the status decrement,
+            //so a job caught mid-close shows status > 0 with its event already
+            //published — a subscriber wiring up in that window misses both
+            //arms. Escalating re-checks close the window (the status settles
+            //milliseconds after the publish), and the slow steady poll keeps
+            //result() live even if the notification itself is lost (NOTIFY
+            //carries no durability across connection drops).
+            const settleIfComplete = async () => {
+                if (isResolved)
+                    return true;
+                const status = await this.hotMesh.getStatus(this.workflowId);
+                if (isResolved)
+                    return true;
+                if (status <= 0) {
+                    await complete();
+                    this.hotMesh.unsub(topic);
+                    return true;
+                }
+                return false;
+            };
+            if (!(await settleIfComplete())) {
+                void (async () => {
+                    const RECHECK_DELAYS_MS = [250, 1000, 5000];
+                    for (const delay of RECHECK_DELAYS_MS) {
+                        await (0, utils_1.sleepFor)(delay);
+                        if (await settleIfComplete())
+                            return;
+                    }
+                    while (!isResolved) {
+                        await (0, utils_1.sleepFor)(30000);
+                        if (await settleIfComplete())
+                            return;
+                    }
+                })().catch(() => {
+                    //the subscription remains the primary completion arm
+                });
             }
         });
     }

package/build/services/escalations/client.d.ts

@@ -1,7 +1,7 @@
 import { HotMesh } from '../hotmesh';
 import { EventsConfig } from '../../types/system_events';
 import { Connection } from '../../types/durable';
-import { EscalationEntry, ClaimEscalationResult, ClaimByMetadataResult, ReleaseEscalationResult, ResolveEscalationResult, CancelEscalationResult, ListEscalationsParams, StatsEscalationsParams, EscalationStats, CreateEscalationParams, UpdateEscalationParams, AppendMilestonesParams, ClaimEscalationParams, ClaimByMetadataParams, ReleaseEscalationParams, ResolveEscalationParams, ResolveByMetadataParams, EscalateToRoleParams, MigrateEscalationParams, ClaimManyParams, EscalateManyToRoleParams, UpdateManyPriorityParams, ResolveManyParams, PruneEscalationsParams, PruneEscalationsResult } from '../../types/hmsh_escalations';
+import { EscalationEntry, ClaimEscalationResult, ClaimByMetadataResult, ReleaseEscalationResult, ResolveEscalationResult, CancelEscalationResult, ListEscalationsParams, StatsEscalationsParams, EscalationStats, CreateEscalationParams, UpdateEscalationParams, AppendMilestonesParams, ClaimEscalationParams, ClaimByMetadataParams, ReleaseEscalationParams, ResolveEscalationParams, ResolveByMetadataParams, EscalateToRoleParams, MigrateEscalationParams, ClaimManyParams, EscalateManyToRoleParams, UpdateManyPriorityParams, ResolveManyParams, ResolveAllOrNoneParams, ResolveAllOrNoneResult, PruneEscalationsParams, PruneEscalationsResult } from '../../types/hmsh_escalations';
 export type GetHotMeshFn = (topic: string | null, namespace?: string) => Promise<HotMesh>;
 export interface EscalationClientConfig {
     /** Postgres connection options — used when creating a standalone EscalationClient. */
@@ -226,6 +226,26 @@ export declare class EscalationClientService {
      * bulk resolution carries no wake and would strand the workflow.
      */
     resolveMany(params: ResolveManyParams): Promise<EscalationEntry[]>;
+    /**
+     * All-or-none bulk resolve with per-row payloads. Every item's escalation
+     * must be pending (and, when `assertAssignee` is set, currently assigned to
+     * that assignee) or NOTHING resolves — one atomic SQL statement locks the
+     * rows in deterministic order, applies each row's own `resolverPayload`,
+     * and commits each waiter's wake WITH its resolve (same durability contract
+     * as `resolve()`). Unlike `resolveMany()`, rows backing a live `condition()`
+     * waiter are first-class here: each receives its own payload as
+     * `condition()`'s return value.
+     *
+     * On `ok: false` no row was written and `failed` lists exactly the blocking
+     * rows with reasons (`not-found`, `already-resolved`, `already-cancelled`,
+     * `already-expired`, `assignee-mismatch`) — rows that were themselves
+     * resolvable stay pending and are not listed.
+     *
+     * Pass `params.metadata` to merge one shared outcome patch into every row's
+     * GIN-indexed `metadata` in the same statement. Ids must be unique; an empty
+     * `items` array returns `ok: true` with no entries.
+     */
+    resolveAllOrNone(params: ResolveAllOrNoneParams, namespace?: string): Promise<ResolveAllOrNoneResult>;
     /**
      * Returns dashboard-ready escalation counts. `period` controls the window
      * used for `created` and `resolved` counts (default `'24h'`). When `roles`

package/build/services/escalations/client.js

@@ -476,6 +476,74 @@ class EscalationClientService {
         this._emitMany('resolved', entries);
         return entries;
     }
+    /**
+     * All-or-none bulk resolve with per-row payloads. Every item's escalation
+     * must be pending (and, when `assertAssignee` is set, currently assigned to
+     * that assignee) or NOTHING resolves — one atomic SQL statement locks the
+     * rows in deterministic order, applies each row's own `resolverPayload`,
+     * and commits each waiter's wake WITH its resolve (same durability contract
+     * as `resolve()`). Unlike `resolveMany()`, rows backing a live `condition()`
+     * waiter are first-class here: each receives its own payload as
+     * `condition()`'s return value.
+     *
+     * On `ok: false` no row was written and `failed` lists exactly the blocking
+     * rows with reasons (`not-found`, `already-resolved`, `already-cancelled`,
+     * `already-expired`, `assignee-mismatch`) — rows that were themselves
+     * resolvable stay pending and are not listed.
+     *
+     * Pass `params.metadata` to merge one shared outcome patch into every row's
+     * GIN-indexed `metadata` in the same statement. Ids must be unique; an empty
+     * `items` array returns `ok: true` with no entries.
+     */
+    async resolveAllOrNone(params, namespace) {
+        const ns = (params.namespace ?? namespace) ?? factory_1.APP_ID;
+        const items = params.items ?? [];
+        if (!items.length)
+            return { ok: true, entries: [] };
+        const ids = items.map((i) => i.id);
+        if (new Set(ids).size !== ids.length) {
+            throw new Error('resolveAllOrNone: duplicate escalation ids in items');
+        }
+        const hm = await this._engine(null, ns);
+        const store = hm.engine.store;
+        //pre-build each waiter's wake so it commits INSIDE the resolve
+        //statement; signal routing (signal_key, topic) is immutable after
+        //creation, so the preview rows are authoritative for wake targeting
+        const payloadById = new Map(items.map((i) => [i.id, i.resolverPayload ?? {}]));
+        const previews = await store.listEscalations({
+            ids,
+            namespace: params.namespace,
+        });
+        const wakeCommands = [];
+        for (const row of previews) {
+            if (!row.signal_key)
+                continue;
+            const cmd = await this._buildWakeCommand(ns, row.topic, row.signal_key, payloadById.get(row.id) ?? {});
+            if (cmd)
+                wakeCommands.push(cmd);
+        }
+        const dbResult = await store.resolveAllOrNoneEscalations({
+            items,
+            namespace: params.namespace,
+            metadata: params.metadata,
+            assertAssignee: params.assertAssignee,
+        }, wakeCommands);
+        if (!dbResult.ok)
+            return { ok: false, failed: dbResult.failed };
+        //rows whose wake was not part of the commit (no hook rule deployed, or
+        //signal routing enriched after the preview) — deliver post-commit
+        const enqueuedKeys = new Set(wakeCommands.map((w) => w.forSignalKey));
+        for (const entry of dbResult.entries) {
+            if (entry.signal_key && !enqueuedKeys.has(entry.signal_key)) {
+                await this._deliverEscalationSignal(ns, entry.topic, {
+                    id: entry.signal_key,
+                    data: payloadById.get(entry.id) ?? {},
+                });
+            }
+        }
+        this._emitMany('resolved', dbResult.entries);
+        return { ok: true, entries: dbResult.entries };
+    }
     // ─── Aggregates ─────────────────────────────────────────────────────────────
     /**
      * Returns dashboard-ready escalation counts. `period` controls the window

package/build/services/store/providers/postgres/postgres.d.ts

@@ -328,6 +328,28 @@ declare class PostgresStoreService extends StoreService<ProviderClient, Provider
     escalateManyEscalationsToRole(params: import('../../../../types/hmsh_escalations').EscalateManyToRoleParams): Promise<number>;
     updateManyEscalationsPriority(params: import('../../../../types/hmsh_escalations').UpdateManyPriorityParams): Promise<number>;
     resolveManyEscalations(params: import('../../../../types/hmsh_escalations').ResolveManyParams): Promise<import('../../../../types/hmsh_escalations').EscalationEntry[]>;
+    /**
+     * All-or-none bulk resolve with per-row payloads. One SQL statement:
+     * the FOR UPDATE lock (ordered by id — deterministic acquisition, no
+     * deadlock between overlapping batches), the count-gated UPDATE, and
+     * the per-row wake INSERTs are one atomic unit. When ANY row is
+     * missing, non-pending, or fails the assignee assertion, the gate
+     * count mismatches, the UPDATE matches zero rows, no wake is written,
+     * and the statement degrades to a pure read — the returned snapshot
+     * names each blocking row and why. Same durability contract as
+     * `resolveEscalation`: each wake commits WITH its row's resolve.
+     */
+    resolveAllOrNoneEscalations(params: import('../../../../types/hmsh_escalations').ResolveAllOrNoneParams, wakeCommands?: import('../../../../types/hmsh_escalations').EscalationWakeCommand[]): Promise<{
+        ok: true;
+        entries: import('../../../../types/hmsh_escalations').EscalationEntry[];
+        wakeCount: number;
+    } | {
+        ok: false;
+        failed: Array<{
+            id: string;
+            reason: import('../../../../types/hmsh_escalations').ResolveAllOrNoneBlockReason;
+        }>;
+    }>;
     escalationStats(params?: import('../../../../types/hmsh_escalations').StatsEscalationsParams): Promise<import('../../../../types/hmsh_escalations').EscalationStats>;
     listDistinctEscalationTypes(namespace?: string): Promise<string[]>;
     releaseExpiredEscalations(_namespace?: string): Promise<number>;

package/build/services/store/providers/postgres/postgres.js

@@ -2222,6 +2222,117 @@ class PostgresStoreService extends __1.StoreService {
        RETURNING *`, namespace ? [payloadJson, ids, metaJson, namespace] : [payloadJson, ids, metaJson]);
         return result.rows;
     }
+    /**
+     * All-or-none bulk resolve with per-row payloads. One SQL statement:
+     * the FOR UPDATE lock (ordered by id — deterministic acquisition, no
+     * deadlock between overlapping batches), the count-gated UPDATE, and
+     * the per-row wake INSERTs are one atomic unit. When ANY row is
+     * missing, non-pending, or fails the assignee assertion, the gate
+     * count mismatches, the UPDATE matches zero rows, no wake is written,
+     * and the statement degrades to a pure read — the returned snapshot
+     * names each blocking row and why. Same durability contract as
+     * `resolveEscalation`: each wake commits WITH its row's resolve.
+     */
+    async resolveAllOrNoneEscalations(params, wakeCommands) {
+        const { items, namespace, metadata, assertAssignee } = params;
+        if (!items?.length)
+            return { ok: true, entries: [], wakeCount: 0 };
+        const ids = items.map((i) => i.id);
+        if (new Set(ids).size !== ids.length) {
+            throw new Error('resolveAllOrNoneEscalations: duplicate escalation ids in items');
+        }
+        const payloads = items.map((i) => i.resolverPayload ? JSON.stringify(i.resolverPayload) : null);
+        const metaJson = metadata ? JSON.stringify(metadata) : null;
+        const sqlParams = [ids, payloads, metaJson, assertAssignee ?? null];
+        let nsClause = '';
+        if (namespace) {
+            sqlParams.push(namespace);
+            nsClause = `AND e.namespace = $${sqlParams.length}`;
+        }
+        //per-row wakes: one engine_streams INSERT per resolved row whose
+        //signal_key matches its pre-built command; zero rows when the gate fails
+        let wakeCTE = '';
+        let wakeCount = '0::int AS wake_count';
+        if (wakeCommands?.length) {
+            const schemaName = this.kvsql().safeName(this.appId);
+            const base = sqlParams.length;
+            sqlParams.push(this.appId, wakeCommands.map((w) => w.forSignalKey), wakeCommands.map((w) => w.message));
+            wakeCTE = `,
+        wake AS (
+          INSERT INTO ${schemaName}.engine_streams (stream_name, message, priority)
+          SELECT $${base + 1}, w.message, 5
+          FROM unnest($${base + 2}::text[], $${base + 3}::text[]) AS w(signal_key, message)
+          JOIN resolved r ON r.signal_key = w.signal_key
+          RETURNING id
+        )`;
+            wakeCount = '(SELECT COUNT(*) FROM wake)::int AS wake_count';
+        }
+        const result = await this.pgClient.query(`
+      WITH input AS MATERIALIZED (
+        SELECT * FROM unnest($1::uuid[], $2::text[]) AS t(id, payload_text)
+      ),
+      target AS MATERIALIZED (
+        SELECT e.id, e.signal_key, e.topic, e.status, e.assigned_to
+        FROM public.hmsh_escalations e
+        WHERE e.id = ANY($1::uuid[]) ${nsClause}
+        ORDER BY e.id
+        FOR UPDATE
+      ),
+      eligible AS (
+        SELECT t.id FROM target t
+        WHERE t.status = 'pending'
+          AND ($4::text IS NULL OR t.assigned_to = $4::text)
+      ),
+      resolved AS (
+        UPDATE public.hmsh_escalations e
+        SET status = 'resolved', resolved_at = NOW(),
+            resolver_payload = i.payload_text::jsonb,
+            metadata = CASE WHEN $3::jsonb IS NOT NULL
+                            THEN COALESCE(e.metadata, '{}'::jsonb) || $3::jsonb
+                            ELSE e.metadata END,
+            updated_at = NOW()
+        FROM input i
+        WHERE e.id = i.id
+          AND e.status = 'pending'
+          AND (SELECT COUNT(*) FROM eligible) = (SELECT COUNT(*) FROM input)
+        RETURNING e.*
+      )${wakeCTE}
+      SELECT
+        i.id AS input_id,
+        t.status AS prior_status,
+        CASE
+          WHEN r.id IS NOT NULL THEN 'resolved'
+          WHEN t.id IS NULL THEN 'not-found'
+          WHEN t.status = 'cancelled' THEN 'already-cancelled'
+          WHEN t.status = 'expired' THEN 'already-expired'
+          WHEN t.status <> 'pending' THEN 'already-resolved'
+          WHEN $4::text IS NOT NULL AND t.assigned_to IS DISTINCT FROM $4::text THEN 'assignee-mismatch'
+          ELSE 'blocked-by-batch'
+        END AS outcome,
+        row_to_json(r.*) AS entry_json,
+        ${wakeCount}
+      FROM input i
+      LEFT JOIN target t ON t.id = i.id
+      LEFT JOIN resolved r ON r.id = i.id
+      ORDER BY i.id
+    `, sqlParams);
+        const rows = result.rows;
+        if (rows.length && rows.every((r) => r.outcome === 'resolved')) {
+            return {
+                ok: true,
+                entries: rows.map((r) => r.entry_json),
+                wakeCount: rows[0].wake_count,
+            };
+        }
+        return {
+            ok: false,
+            //'blocked-by-batch' rows were themselves resolvable — only the true
+            //blockers are reported; the caller re-gangs around exactly these
+            failed: rows
+                .filter((r) => r.outcome !== 'resolved' && r.outcome !== 'blocked-by-batch')
+                .map((r) => ({ id: r.input_id, reason: r.outcome })),
+        };
+    }
     async escalationStats(params = {}) {
         const { namespace, roles, period = '24h' } = params;
         if (roles !== undefined && roles.length === 0) {

package/build/types/hmsh_escalations.d.ts

@@ -352,6 +352,47 @@ export interface ResolveManyParams {
      */
     metadata?: Record<string, unknown>;
 }
+/** One member of a `resolveAllOrNone()` batch — its own `resolverPayload` is
+ * stored as that row's `resolver_payload` and delivered to that row's waiting
+ * workflow as `condition()`'s return value. */
+export interface ResolveAllOrNoneItem {
+    id: string;
+    resolverPayload?: Record<string, unknown>;
+}
+export interface ResolveAllOrNoneParams {
+    /** The batch. Ids must be unique; each item carries its own payload. */
+    items: ResolveAllOrNoneItem[];
+    namespace?: string;
+    /**
+     * Shared outcome patch merged (not replaced) into EVERY row's GIN-indexed
+     * `metadata` in the single atomic statement. See {@link ResolveEscalationParams.metadata}.
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * When provided, every row must currently be assigned to this assignee
+     * (`assigned_to` equality, asserted inside the same statement). Closes the
+     * claim-race window for claim-then-resolve flows: a row re-claimed by another
+     * principal between the caller's claim and this resolve blocks the batch.
+     */
+    assertAssignee?: string;
+}
+/** Why a specific row blocked a `resolveAllOrNone()` batch. */
+export type ResolveAllOrNoneBlockReason = 'not-found' | 'already-resolved' | 'already-cancelled' | 'already-expired' | 'assignee-mismatch';
+/**
+ * Result of `resolveAllOrNone()`. On `ok: false` NOTHING was written; `failed`
+ * lists only the rows that blocked the batch (rows that were themselves
+ * resolvable are not listed — they remain pending, untouched).
+ */
+export type ResolveAllOrNoneResult = {
+    ok: true;
+    entries: EscalationEntry[];
+} | {
+    ok: false;
+    failed: Array<{
+        id: string;
+        reason: ResolveAllOrNoneBlockReason;
+    }>;
+};
 /**
  * Full-fidelity migration params. Extends `CreateEscalationParams` with:
  * - `id` (required) — preserves the original UUID; no auto-generation

package/build/types/index.d.ts

@@ -25,5 +25,5 @@ export { ReclaimedMessageType, RetryPolicy, RouterConfig, StreamCode, StreamConf
 export { context, Context, Counter, Meter, metrics, propagation, SpanContext, Span, SpanStatus, SpanStatusCode, SpanKind, trace, Tracer, ValueType, } from './telemetry';
 export { WorkListTaskType } from './task';
 export { TransitionMatch, TransitionRule, Transitions } from './transition';
-export { ConditionQueueConfig, EscalationEntry, ClaimEscalationResult, ClaimByMetadataResult, ReleaseEscalationResult, ResolveEscalationResult, CancelEscalationResult, ListEscalationsParams, CreateEscalationParams, UpdateEscalationParams, AppendMilestonesParams, ClaimEscalationParams, ClaimByMetadataParams, ReleaseEscalationParams, ResolveEscalationParams, ResolveByMetadataParams, EscalateToRoleParams, MigrateEscalationParams, } from './hmsh_escalations';
+export { ConditionQueueConfig, EscalationEntry, ClaimEscalationResult, ClaimByMetadataResult, ReleaseEscalationResult, ResolveEscalationResult, CancelEscalationResult, ListEscalationsParams, CreateEscalationParams, UpdateEscalationParams, AppendMilestonesParams, ClaimEscalationParams, ClaimByMetadataParams, ReleaseEscalationParams, ResolveEscalationParams, ResolveByMetadataParams, ResolveAllOrNoneItem, ResolveAllOrNoneParams, ResolveAllOrNoneBlockReason, ResolveAllOrNoneResult, EscalateToRoleParams, MigrateEscalationParams, } from './hmsh_escalations';
 export { EscalationVerb, EngineVerb, WorkerVerb, SystemEvent, EventsConfig } from './system_events';

package/build/types/system_events.d.ts

@@ -143,8 +143,8 @@ export interface SystemEvent {
     span_id?: string;
     /**
      * Full committed row for escalation events; lifecycle metadata for
-     * engine/worker events. Long-tail and hike-mono each cherry-pick fields
-     * for their own event shape.
+     * engine/worker events. Each dependent cherry-picks fields for its
+     * own event shape.
      */
     data: Record<string, unknown>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/hotmesh",
-  "version": "0.26.0",
+  "version": "0.26.1",
   "description": "Durable Workflow",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",

package/OPTIMIZATIONS.md

@@ -1,128 +0,0 @@
-# HotMesh needs — from long-tail
-
-A needs document from the long-tail project: the usage patterns we run at
-production scale and the engine support that would let us run them well. Each item
-states what we do, the concrete access pattern, and the engine capability or
-guarantee we need. Ordered by leverage.
-
-Context: long-tail is a durable HITL escalation platform on Postgres. Escalations
-live in `public.hmsh_escalations` (engine-created); we layer a `public.lt_escalations`
-view and a few app-owned indexes on top. Our dominant runtime shape is
-**single-role** work-queue traffic — claim / available / count / settle scoped to
-one `role` — plus a per-role escalation form the resolve UI renders.
-
----
-
-## 1. Safe retention for terminal escalation rows
-
-**Usage.** An escalation is written once, resolved once, then read for audit. The
-pending working set stays small — a role-leading pending partial index keeps
-single-role claim/available queries `O(pending)` regardless of table size:
-
-```sql
-WHERE role = $1 AND status = 'pending'
-  AND (assigned_to IS NULL OR assigned_until <= NOW())
-  AND metadata @> $facets
-ORDER BY priority ASC, created_at ASC
-FOR UPDATE SKIP LOCKED
-```
-
-The terminal set (resolved / expired / cancelled) grows for the life of the
-deployment — the source of long-run table bloat, autovacuum load, and index growth.
-
-**Need.** A safe, engine-blessed way to age out terminal rows. Tell us what state
-the engine still reads once an escalation is terminal (replay, completion, audit),
-so we know what is inert, then one of:
-- a supported retention/archive call the engine owns; or
-- a documented contract that a row is safe to delete once its status is terminal
-  and older than a horizon; or
-- time sub-partitioning of the terminal set the engine can `DETACH`/`DROP`.
-
-`hmsh_escalations` stays a single physical table keyed by `id`/`signal_key` for
-the engine's lookups; retention touches only rows the engine confirms are inert. We
-can supply the horizon and exact DDL.
-
----
-
-## 2. Stable ownership of app-added indexes on `hmsh_escalations`
-
-**Usage.** We add indexes to the engine table via advisory-locked
-`CREATE INDEX CONCURRENTLY IF NOT EXISTS`:
-- a role-leading pending index `(role, priority, created_at) WHERE status='pending'`
-  for the claim/available order;
-- a **pending-scoped GIN** on `metadata` (`jsonb_path_ops`) `WHERE status='pending'`
-  — keeps the GIN sized to the working set and cuts write amplification on the
-  high-churn insert→resolve path;
-- covering partial indexes for resolved-row reads.
-
-**Need.** A stable contract that app-added indexes on `hmsh_escalations` survive
-engine migrations — the engine keeps the table in place across upgrades — or a
-documented post-migration hook we can register to re-ensure them. Shipping these
-index shapes in the engine itself also works; the requirement is that they persist.
-
----
-
-## 3. Atomic metadata write in the `condition()` Leg1 checkpoint
-
-**Usage.** A workflow surfaces a HITL wait with `condition(signalId, config)`. We
-pass the target `role`, claim/routing facets, and `metadata.schema_version` (the
-form version the resolve UI renders) in `config.metadata`. Claim/resolve-by-metadata
-and the dashboard read those facets via GIN `@>`; the resolve UI reads
-`schema_version` to render the exact form.
-
-**Need.** Guarantee — as a documented public contract — that `config.metadata` is
-written into the escalation row **atomically in the same Leg1 checkpoint** that
-creates the row (one commit, crash-safe). This is the foundation our JIT-versioned
-form pinning and metadata-driven routing stand on.
-
----
-
-## 4. Honored long-activity timeout + reclaim safety
-
-**Usage.** We run a batch pattern: a single proxyActivity loops internally for
-~60s (poll → reconcile → act), returning one durable checkpoint per call instead of
-one per step, so replay stays compact.
-
-**Need.** A documented guarantee that:
-- `proxyActivities({ startToCloseTimeout })` is honored for long (30–120s) activities;
-- the stream reclaim window (`HMSH_XCLAIM_DELAY_MS`) holds an in-flight activity for
-  the duration of its `startToCloseTimeout`, so a long activity is not reclaimed and
-  re-dispatched (duplicate execution) before it completes. Deriving the reclaim
-  window from `startToCloseTimeout` automatically makes a 60s+ activity safe by
-  default.
-
----
-
-## 5. Documented concurrent-condition bound for harvest fan-out
-
-**Usage.** A market-maker workflow opens N `condition()` waits and harvests them
-with `Promise.all`, chunked to stay within the safe concurrent-condition bound (a
-fast signaler can arrive before a later condition registers).
-
-**Need.** Publish the safe concurrent-condition bound as a stable number with the
-recommended chunking pattern, so we size harvest fan-out to spec rather than
-empirically — and raise it where the engine can.
-
----
-
-## 6. Signal buffering + startChild leader-keeps-seat as public contract
-
-**Usage.** Two behaviors our crash-safe patterns build on:
-- a signal delivered to a workflow **not yet parked** on that signalId is buffered
-  and delivered on the next `condition()` await;
-- `startChild` with a **duplicate workflowId** lets the sitting execution keep its
-  seat (leader-keeps-seat), enabling self-continuing link chains (`x-l1`, `x-l2`, …)
-  as an alternative to `continueAsNew`.
-
-**Need.** Elevate both to documented, stable public guarantees (including the signal
-buffering TTL), versioned as contract.
-
----
-
-### How we consume these
-
-Items 1–2 are the scale needs — retention for terminal rows, and durable app-owned
-indexes that keep the hot path `O(pending)`. Item 3 is the atomicity guarantee our
-versioned forms and metadata routing depend on. Items 4–6 are behaviors we already
-build on and want made explicit. We can provide `EXPLAIN` plans, row-count/latency
-profiles, and the exact DDL for any of these on request.

package/RELEASE-0.26.0.md

@@ -1,111 +0,0 @@
-# HotMesh v0.26.0 — for the long-tail project
-
-This release answers the needs document. Items 1–5 and the signal-buffering
-half of item 6 ship as published contracts with proving tests; the startChild
-contract (item 6b) is scheduled for its own follow-up release. Numbering below
-matches your document.
-
-## 1. Retention for terminal escalation rows — new API
-
-Terminal rows (`resolved`, `cancelled`, `expired`) are inert: every engine
-state transition guards on `status = 'pending'`, and the engine reads terminal
-rows only through `list()` / `get()` / `stats()`. Age them out with the new
-engine-owned call:
-
-```typescript
-let deleted: number;
-do {
-  ({ deleted } = await client.escalations.prune({ olderThan: '90 days' }));
-} while (deleted > 0);
-```
-
-- `olderThan` is a Postgres interval; rows qualify when
-  `updated_at < NOW() - olderThan`.
-- `statuses` narrows which terminal states are pruned (defaults to all three);
-  `namespace` scopes to one app; `limit` bounds rows per call (default 10,000,
-  cap 100,000) so vacuum pressure stays flat.
-- Each call is one atomic statement — candidate selection
-  (`FOR UPDATE SKIP LOCKED`) and the DELETE commit together, so concurrent
-  pruners cooperate and live waiters, claims, and signal delivery proceed
-  untouched. The proving test backdates a parked waiter 120 days, prunes, and
-  resolves it to completion.
-- If you run retention with your own tooling instead, the documented
-  safe-to-delete predicate is exactly the one `prune()` uses:
-  `status IN ('resolved','cancelled','expired') AND updated_at` older than
-  your horizon.
-- Choose a horizon at least as long as your reporting window: `stats()`
-  created/resolved counts and `get()` by id reflect the rows retained.
-
-## 2. App-added indexes survive engine migrations — published contract
-
-Engine migrations on `public.hmsh_escalations` are strictly additive
-(`CREATE TABLE / INDEX IF NOT EXISTS`, `ADD COLUMN IF NOT EXISTS`, advisory-
-locked), and the table persists in place across upgrades. The engine manages
-only indexes with the `idx_hmsh_esc_*` prefix; indexes under any other name
-are yours and persist. Your advisory-locked
-`CREATE INDEX CONCURRENTLY IF NOT EXISTS` pattern is the recommended one.
-
-Two notes on your shapes: the engine's `idx_hmsh_esc_available`
-(`(namespace, app_id, role, priority ASC, created_at ASC) WHERE
-status = 'pending'`) already serves the single-role claim/available order at
-`O(pending)`. Your pending-scoped GIN stays app-owned: the engine keeps its
-full-table GIN because resolver-merged metadata (v0.24.0) is read on resolved
-rows.
-
-## 3. Atomic metadata in the Leg1 checkpoint — published contract
-
-Every field of the `condition()` config — `metadata` facets included — is one
-INSERT committed inside the Leg1 checkpoint transaction: one commit,
-crash-safe. From the row's first visible moment it carries its complete
-routing context and metadata, so claim-by-metadata routing and
-`schema_version`-pinned forms can trust every row they read. The proving test
-tight-polls from workflow start and asserts the first sighting is complete.
-
-## 4. Long activities execute exactly once — published contract
-
-- `startToCloseTimeout` is honored for long activities (deadline enforcement
-  is covered by positive and negative tests).
-- While an activity runs, the consumer heartbeats its stream reservation at
-  half the base window, so the message stays leased for the full run —
-  your 60s batch loop (poll → reconcile → act, one checkpoint per call) is a
-  supported shape at default settings, for any duration. Redelivery happens
-  when a consumer crashes and stops heartbeating, and the collation ledger
-  settles a redelivered message as a duplicate before the activity function
-  re-executes.
-- The proving test runs a 45s activity against a 30s reservation window with
-  a second worker actively polling the same queue: exactly one execution.
-- Deployment note: standard Postgres connections have this lease extension.
-  A `securedWorker` connection (SECURITY DEFINER stored-proc mode) enforces
-  the adaptive reservation window instead — 30s base, scaling to 30 minutes
-  under load — so size activities to that window in secured mode.
-
-## 5. Concurrent-condition bound — the published number is a TTL
-
-Fan-out is sized by time, and by count it scales freely. A signal that races
-ahead of its `condition()` registration is buffered as a pending signal and
-delivered — crash-safe, in a single transaction — when the wait registers.
-The buffer holds a signal for **10 minutes** by default; pass `expire` to
-`signal()` (e.g. `'1h'`, `'30d'`) when signaling early on purpose.
-
-Chunk your harvest so every condition in a chunk registers within the TTL of
-its fastest signaler. The proving test opens 25 waits in one `Promise.all`
-and fires all 25 signals before any wait has registered: every signal is
-delivered to its own wait, in order.
-
-## 6. Contracts
-
-- **Signal buffering** is now a documented public guarantee (item 5 above,
-  TTL included).
-- **startChild leader-keeps-seat**: the sitting execution keeps its seat
-  today, and fire-and-forget `startChild` link chains (`x-l1`, `x-l2`, …)
-  work on that behavior. The *awaited* duplicate path (`executeChild` on an
-  id that already exists) gets defined semantics — a typed result rather
-  than an open wait — in a dedicated follow-up release; until then, treat
-  awaited duplicates as unspecified and build chains on the fire-and-forget
-  form.
-
-## Upgrading
-
-`npm install @hotmeshio/hotmesh@0.26.0`. Migrations are additive and run
-automatically under the existing advisory lock; your indexes and views
-persist. Full durable suite: 433 tests green.