@hotmeshio/hotmesh 0.25.5 → 0.26.0

package/OPTIMIZATIONS.md

@@ -0,0 +1,128 @@
+# 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

@@ -0,0 +1,111 @@
+# 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.

package/build/package.json

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

package/build/services/activities/hook.js

@@ -575,6 +575,9 @@ class Hook extends activity_1.Activity {
             this.context.metadata.jid = jobId;
             this.context.metadata.gid = gId;
             this.context.metadata.dad = dad;
+            //captured for the timeout disarm below: processEvent's state
+            //hydration replaces context.metadata before the disarm runs
+            const waiterJid = jobId;
             // Inline retry for FORBIDDEN: Leg2 arrived in the window between
             // setHookSignal (standalone) and Leg1 transaction.exec(). The 100B
             // ledger digit is not yet visible. Leg1 needs only milliseconds to
@@ -589,6 +592,25 @@ class Hook extends activity_1.Activity {
                     await this.processEvent(status, code, 'hook');
                     if (code === 200) {
                         await taskService.deleteWebHookSignal(this.config.hook.topic, data);
+                        //signal won the race: disarm the SLA timeout leg (the mirror
+                        //of the timeout-won path, which deletes the signal). The
+                        //armed timehook may not survive to fire against the settled
+                        //wait. Addressed by the SIGNAL's jid + dimensional address —
+                        //processEvent has since rehydrated this.context.
+                        if (this.config.sleep) {
+                            try {
+                                await this.store.expireTimeHook?.(waiterJid, this.metadata.aid);
+                            }
+                            catch (error) {
+                                //best-effort: a surviving timer fires once and is
+                                //consumed as an inactive-job event
+                                this.logger.warn('hook-timeout-disarm-error', {
+                                    jid: waiterJid,
+                                    aid: this.metadata.aid,
+                                    error,
+                                });
+                            }
+                        }
                         //clean up orphan pending on the sibling signal topic
                         //  wfs.wait delivered → remove wfs.signal pending
                         //  wfs.signal delivered → remove wfs.wait pending

package/build/services/durable/workflow/condition.d.ts

@@ -46,9 +46,12 @@ import { ConditionQueueConfig } from '../../../types/hmsh_escalations';
  * ## With escalation queue config
  *
  * Pass a {@link ConditionQueueConfig} as the second argument to surface the
- * pause as a claimable row in `public.hmsh_escalations`. The INSERT is
- * committed atomically with the workflow checkpoint — one write, no
- * enrichment step, no secondary round-trip.
+ * pause as a claimable row in `public.hmsh_escalations`. The INSERT — every
+ * field of the config, including `metadata` facets — is committed atomically
+ * with the workflow checkpoint: one write, 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 version-pinned facets (e.g. a
+ * `schema_version` the resolver UI renders) can trust every row they read.
  *
  * ```typescript
  * const decision = await Durable.workflow.condition<{ approved: boolean }>(
@@ -81,6 +84,14 @@ import { ConditionQueueConfig } from '../../../types/hmsh_escalations';
  * SLA-gated human waits in the workflow body and let hook functions report
  * back via `signal()`.
  *
+ * ## Early signals are buffered
+ *
+ * A signal delivered before its `condition()` registers — a fast signaler,
+ * or a payload deposited before the workflow starts — is buffered as a
+ * pending signal and delivered when the wait registers. The buffer holds a
+ * signal for 10 minutes by default; pass `expire` to `signal()` (e.g.
+ * `'1h'`, `'30d'`) to hold it longer when signaling early on purpose.
+ *
  * ## Fan-in: wait for multiple signals in parallel
  *
  * ```typescript
@@ -90,6 +101,12 @@ import { ConditionQueueConfig } from '../../../types/hmsh_escalations';
  * ]);
  * ```
  *
+ * Harvest fan-out scales the same way: open N waits with `Promise.all` and
+ * signal all of them at once. Buffering covers every signal that races
+ * ahead of registration, so size fan-out by the pending-signal TTL — how
+ * long a racing signal may wait for its condition to register — with no
+ * separate bound on the number of concurrent waits.
+ *
  * ## Paired with hook: spawn work, wait for its signal
  *
  * ```typescript

package/build/services/durable/workflow/condition.js

@@ -51,9 +51,12 @@ const didRun_1 = require("./didRun");
  * ## With escalation queue config
  *
  * Pass a {@link ConditionQueueConfig} as the second argument to surface the
- * pause as a claimable row in `public.hmsh_escalations`. The INSERT is
- * committed atomically with the workflow checkpoint — one write, no
- * enrichment step, no secondary round-trip.
+ * pause as a claimable row in `public.hmsh_escalations`. The INSERT — every
+ * field of the config, including `metadata` facets — is committed atomically
+ * with the workflow checkpoint: one write, 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 version-pinned facets (e.g. a
+ * `schema_version` the resolver UI renders) can trust every row they read.
  *
  * ```typescript
  * const decision = await Durable.workflow.condition<{ approved: boolean }>(
@@ -86,6 +89,14 @@ const didRun_1 = require("./didRun");
  * SLA-gated human waits in the workflow body and let hook functions report
  * back via `signal()`.
  *
+ * ## Early signals are buffered
+ *
+ * A signal delivered before its `condition()` registers — a fast signaler,
+ * or a payload deposited before the workflow starts — is buffered as a
+ * pending signal and delivered when the wait registers. The buffer holds a
+ * signal for 10 minutes by default; pass `expire` to `signal()` (e.g.
+ * `'1h'`, `'30d'`) to hold it longer when signaling early on purpose.
+ *
  * ## Fan-in: wait for multiple signals in parallel
  *
  * ```typescript
@@ -95,6 +106,12 @@ const didRun_1 = require("./didRun");
  * ]);
  * ```
  *
+ * Harvest fan-out scales the same way: open N waits with `Promise.all` and
+ * signal all of them at once. Buffering covers every signal that races
+ * ahead of registration, so size fan-out by the pending-signal TTL — how
+ * long a racing signal may wait for its condition to register — with no
+ * separate bound on the number of concurrent waits.
+ *
  * ## Paired with hook: spawn work, wait for its signal
  *
  * ```typescript

package/build/services/durable/workflow/proxyActivities.d.ts

@@ -111,6 +111,20 @@ declare function wrapActivity<T>(activityName: string, options?: ActivityConfig)
  * }
  * ```
  *
+ * ## Long-running activities execute exactly once
+ *
+ * `startToCloseTimeout` bounds an activity's run and is honored for long
+ * work (a 30–120s batch loop is a supported shape: poll → reconcile → act,
+ * one durable checkpoint per call). While the activity runs, the consumer
+ * heartbeats its stream reservation at half the base window, so the message
+ * stays leased for the full run — however long — and is redelivered to
+ * another worker only when the owning consumer crashes and stops
+ * heartbeating. The collation ledger then guarantees any redelivered
+ * message settles as a duplicate before re-executing the activity. With a
+ * `securedWorker` connection (SECURITY DEFINER stored-proc mode), lease
+ * extension is unavailable and an activity must finish within the adaptive
+ * reservation window instead.
+ *
  * @template ACT - The activity type map (use `typeof activities` for inline registration).
  * @param {ActivityConfig} [options] - Activity configuration including retry policy and routing.
  * @returns {ProxyType<ACT>} A typed proxy object mapping activity names to their durable wrappers.

package/build/services/durable/workflow/proxyActivities.js

@@ -230,6 +230,20 @@ exports.wrapActivity = wrapActivity;
  * }
  * ```
  *
+ * ## Long-running activities execute exactly once
+ *
+ * `startToCloseTimeout` bounds an activity's run and is honored for long
+ * work (a 30–120s batch loop is a supported shape: poll → reconcile → act,
+ * one durable checkpoint per call). While the activity runs, the consumer
+ * heartbeats its stream reservation at half the base window, so the message
+ * stays leased for the full run — however long — and is redelivered to
+ * another worker only when the owning consumer crashes and stops
+ * heartbeating. The collation ledger then guarantees any redelivered
+ * message settles as a duplicate before re-executing the activity. With a
+ * `securedWorker` connection (SECURITY DEFINER stored-proc mode), lease
+ * extension is unavailable and an activity must finish within the adaptive
+ * reservation window instead.
+ *
  * @template ACT - The activity type map (use `typeof activities` for inline registration).
  * @param {ActivityConfig} [options] - Activity configuration including retry policy and routing.
  * @returns {ProxyType<ACT>} A typed proxy object mapping activity names to their durable wrappers.

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 } 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, 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. */
@@ -73,9 +73,9 @@ export declare class EscalationClientService {
     private _hashConnection;
     private _deliverEscalationSignal;
     /**
-     * Builds the wake publish as a SQL command so the store can commit it
-     * INSIDE the resolve transaction — the wake becomes durable with the
-     * resolved row, closing the crash window between resolve commit and
+     * Builds the wake as a webhook message so the store can commit it
+     * INSIDE the resolve/cancel transaction — the wake becomes durable
+     * with the status change, closing the crash window between commit and
      * post-commit signal delivery. Mirrors `_deliverEscalationSignal`'s
      * topic fallback chain; returns null when no hook rule is deployed
      * for any candidate topic (the caller then keeps post-commit
@@ -93,6 +93,18 @@ export declare class EscalationClientService {
      * Uses the same filter parameters as `list()`.
      */
     count(params?: ListEscalationsParams): Promise<number>;
+    /**
+     * Retention: deletes terminal escalation rows (`resolved`/`cancelled`/`expired`)
+     * whose `updated_at` is older than the horizon (a Postgres interval string,
+     * e.g. `'90 days'`). Terminal rows are inert — every engine state transition
+     * guards on `status = 'pending'` — so pruning them is safe for live waiters,
+     * claims, and signal delivery; this call is the engine-blessed way to age
+     * out the audit backlog. Each call deletes at most `limit` rows (default
+     * 10,000) in one atomic statement; loop until `deleted` is 0 to drain a
+     * large backlog. `list()`/`get()`/`stats()` reads over windows older than
+     * the pruning horizon reflect only the rows retained.
+     */
+    prune(params: PruneEscalationsParams): Promise<PruneEscalationsResult>;
     /** Returns a single escalation row by UUID. Returns `null` if not found. */
     get(id: string, namespace?: string): Promise<EscalationEntry | null>;
     /** Looks up an escalation by `signal_key` — the value passed to `condition()`. */
@@ -132,10 +144,10 @@ export declare class EscalationClientService {
     /**
      * Cancels a pending escalation and delivers a cancellation signal to the
      * waiting workflow so that `condition()` returns `null`. Terminal rows
-     * return `already-terminal`. Signal delivery is best-effort post-commit —
-     * the committed cancelled row is the durable record; any missed delivery
-     * can be detected via a sweep of rows with `status = 'cancelled'` and a
-     * non-null `signal_key`.
+     * return `already-terminal`. The cancellation wake commits inside the
+     * cancel transaction (same durability contract as `resolve()`); when no
+     * hook rule is deployed for any candidate topic, delivery falls back to
+     * a best-effort post-commit publish.
      */
     cancel(id: string, namespace?: string): Promise<CancelEscalationResult>;
     /**
@@ -207,6 +219,12 @@ export declare class EscalationClientService {
      * (still-pending) row's GIN-indexed `metadata` in the single atomic UPDATE.
      * See {@link resolve}.
      */
+    /**
+     * Bulk-resolves standalone escalations (rows with `signal_key = null`).
+     * Rows backing a live `condition()` waiter are excluded — they stay
+     * pending so a targeted `resolve()`/`cancel()` can deliver their wake;
+     * bulk resolution carries no wake and would strand the workflow.
+     */
     resolveMany(params: ResolveManyParams): Promise<EscalationEntry[]>;
     /**
      * Returns dashboard-ready escalation counts. `period` controls the window

package/build/services/escalations/client.js

@@ -3,7 +3,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.EscalationClientService = void 0;
 const enums_1 = require("../../modules/enums");
 const utils_1 = require("../../modules/utils");
-const key_1 = require("../../modules/key");
 const hotmesh_1 = require("../hotmesh");
 const types_1 = require("../../types");
 const stream_1 = require("../../types/stream");
@@ -148,9 +147,9 @@ class EscalationClientService {
         return delivered;
     }
     /**
-     * Builds the wake publish as a SQL command so the store can commit it
-     * INSIDE the resolve transaction — the wake becomes durable with the
-     * resolved row, closing the crash window between resolve commit and
+     * Builds the wake as a webhook message so the store can commit it
+     * INSIDE the resolve/cancel transaction — the wake becomes durable
+     * with the status change, closing the crash window between commit and
      * post-commit signal delivery. Mirrors `_deliverEscalationSignal`'s
      * topic fallback chain; returns null when no hook rule is deployed
      * for any candidate topic (the caller then keeps post-commit
@@ -173,13 +172,10 @@ class EscalationClientService {
                     metadata: { guid: (0, utils_1.guid)(), aid, topic: candidate },
                     data: { id: signalKey, data },
                 };
-                const streamKey = engine.stream.mintKey(key_1.KeyType.STREAMS, {
-                    topic: null,
-                });
-                const { sql, params } = engine.stream._publishMessages(streamKey, [
-                    JSON.stringify(streamData),
-                ]);
-                return { forSignalKey: signalKey, sql, params };
+                return {
+                    forSignalKey: signalKey,
+                    message: JSON.stringify(streamData),
+                };
             }
             catch {
                 /* candidate not deployed — try the next topic */
@@ -205,6 +201,21 @@ class EscalationClientService {
         const hm = await this._engine(null, params?.namespace);
         return hm.engine.store.countEscalations(params ?? {});
     }
+    /**
+     * Retention: deletes terminal escalation rows (`resolved`/`cancelled`/`expired`)
+     * whose `updated_at` is older than the horizon (a Postgres interval string,
+     * e.g. `'90 days'`). Terminal rows are inert — every engine state transition
+     * guards on `status = 'pending'` — so pruning them is safe for live waiters,
+     * claims, and signal delivery; this call is the engine-blessed way to age
+     * out the audit backlog. Each call deletes at most `limit` rows (default
+     * 10,000) in one atomic statement; loop until `deleted` is 0 to drain a
+     * large backlog. `list()`/`get()`/`stats()` reads over windows older than
+     * the pruning horizon reflect only the rows retained.
+     */
+    async prune(params) {
+        const hm = await this._engine(null, params.namespace);
+        return hm.engine.store.pruneEscalations(params);
+    }
     /** Returns a single escalation row by UUID. Returns `null` if not found. */
     async get(id, namespace) {
         const hm = await this._engine(null, namespace);
@@ -286,18 +297,27 @@ class EscalationClientService {
     /**
      * Cancels a pending escalation and delivers a cancellation signal to the
      * waiting workflow so that `condition()` returns `null`. Terminal rows
-     * return `already-terminal`. Signal delivery is best-effort post-commit —
-     * the committed cancelled row is the durable record; any missed delivery
-     * can be detected via a sweep of rows with `status = 'cancelled'` and a
-     * non-null `signal_key`.
+     * return `already-terminal`. The cancellation wake commits inside the
+     * cancel transaction (same durability contract as `resolve()`); when no
+     * hook rule is deployed for any candidate topic, delivery falls back to
+     * a best-effort post-commit publish.
      */
     async cancel(id, namespace) {
         const ns = namespace ?? factory_1.APP_ID;
         const hm = await this._engine(null, ns);
-        const result = await hm.engine.store.cancelEscalation(id, namespace);
+        const store = hm.engine.store;
+        //pre-build the cancellation wake so it commits INSIDE the cancel
+        //transaction — condition() resumes with null even if the process
+        //dies the instant the cancel commits
+        let wakeCommand = null;
+        const preview = await store.getEscalation(id, namespace);
+        if (preview?.signal_key) {
+            wakeCommand = await this._buildWakeCommand(ns, preview.topic, preview.signal_key, { __escalation_cancelled: true });
+        }
+        const result = await store.cancelEscalation(id, namespace, wakeCommand ?? undefined);
         if (result.ok === true) {
             this._emit('cancelled', result.entry);
-            if (result.entry.signal_key) {
+            if (result.entry.signal_key && !result.wakeEnqueued) {
                 await this._deliverEscalationSignal(ns, result.entry.topic, {
                     id: result.entry.signal_key,
                     data: { __escalation_cancelled: true },
@@ -444,6 +464,12 @@ class EscalationClientService {
      * (still-pending) row's GIN-indexed `metadata` in the single atomic UPDATE.
      * See {@link resolve}.
      */
+    /**
+     * Bulk-resolves standalone escalations (rows with `signal_key = null`).
+     * Rows backing a live `condition()` waiter are excluded — they stay
+     * pending so a targeted `resolve()`/`cancel()` can deliver their wake;
+     * bulk resolution carries no wake and would strand the workflow.
+     */
     async resolveMany(params) {
         const hm = await this._engine(null, params.namespace);
         const entries = await hm.engine.store.resolveManyEscalations(params);