tapimo 0.10.2 → 0.12.0

package/src/internal/Webhooks.ts

@@ -3,6 +3,7 @@ import { Hash, Hex } from 'ox'
 import type * as app_Webhooks from '../apps/data/routes/webhooks.js'
 import type * as Db from '../db/Db.js'
 import * as WebhookDeliveries from '../db/tables/webhookDeliveries.js'
+import * as WebhookQueueCompletions from '../db/tables/webhookQueueCompletions.js'
 import * as WebhookQueueEvents from '../db/tables/webhookQueueEvents.js'
 import * as WebhookSubscriptions from '../db/tables/webhookSubscriptions.js'
 import type * as Metrics from '../Metrics.js'
@@ -49,6 +50,16 @@ export type Owner =
       type: 'mpp'
     }
 
+/** API-key scope applied when managing private-resource subscriptions. */
+export type Access = {
+  /** API-key environment. */
+  environment: 'production' | 'sandbox'
+  /** Project attribution, when the key is project-scoped. */
+  projectId?: string | undefined
+  /** API-key scopes used to authorize private resource reads. */
+  scopes: readonly string[]
+}
+
 /**
  * Optional human context describing what a subscription is for. Carried onto
  * every delivered {@link Envelope} and surfaced by destinations (Slack header +
@@ -73,6 +84,8 @@ export type Subscription = {
   createdAt: string
   /** Where matched events are delivered (URL or Slack channel). */
   destination: WebhookDestination.Destination
+  /** API-key environment captured when the subscription was created. */
+  environment?: 'production' | 'sandbox' | undefined
   /** Event type the subscription listens to. */
   eventType: EventType
   /** ISO expiry timestamp; set for MPP-owned subscriptions (TTL-bounded). */
@@ -83,15 +96,19 @@ export type Subscription = {
   filters: Record<string, unknown>
   /** Subscription id (`wh_…`). */
   id: string
-  /** ISO timestamp of the last successful delivery, if any. */
+  /** ISO timestamp of the last successful delivery, if any. Display only:
+   * refreshed at most once per precision window. */
   lastDeliveryAt?: string | undefined
   /** Authenticated owner. */
   owner: Owner
+  /** Project attribution captured from the creating API key. */
+  projectId?: string | undefined
   /** HMAC signing secret. Returned once at creation; never exposed by reads. */
   secret: string
   /** Lifecycle status. */
   status: Status
-  /** ISO timestamp of the last mutation. */
+  /** ISO timestamp of the last mutation. May lag repeat deliveries; see
+   * `lastDeliveryAt`. */
   updatedAt: string
 }
 
@@ -103,12 +120,16 @@ export type CreateInput = {
   context?: Context | undefined
   /** Where matched events are delivered. `url` destinations are SSRF-validated. */
   destination: WebhookDestination.Destination
+  /** API-key environment used to isolate private resource events. */
+  environment?: 'production' | 'sandbox' | undefined
   /** Event type to listen to. */
   eventType: EventType
   /** Event-type-specific filter predicates. */
   filters?: Record<string, unknown> | undefined
   /** Owner derived from the request principal. */
   owner: Owner
+  /** Project attribution used to isolate private resource events. */
+  projectId?: string | undefined
   /** Time-to-live in milliseconds; set the subscription to expire (MPP TTL). */
   ttl?: number | undefined
 }
@@ -181,7 +202,7 @@ export async function createSubscription(
   const now = (options.now ?? (() => new Date()))()
   const iso = now.toISOString()
   // A one-field checkpoint records the live creation head without claiming it
-  // was scanned. The poller expands it using its confirmation depth.
+  // was scanned; it anchors the fanout boundary for the new subscription.
   const pollerCursor =
     options.startBlockNumber === undefined ? undefined : Cursor.encode([options.startBlockNumber])
 
@@ -190,11 +211,13 @@ export async function createSubscription(
     ...(input.context === undefined ? {} : { context: input.context }),
     createdAt: iso,
     destination: input.destination,
+    ...(input.environment === undefined ? {} : { environment: input.environment }),
     eventType: input.eventType,
     failureCount: 0,
     filters: input.filters ?? {},
     id: generateId(now),
     owner: input.owner,
+    ...(input.projectId === undefined ? {} : { projectId: input.projectId }),
     secret: generateSecret(),
     status: 'active',
     updatedAt: iso,
@@ -236,8 +259,14 @@ export async function getSubscription(
   db: Db.Db,
   owner: Owner,
   id: string,
+  options: getSubscription.Options = {},
 ): Promise<Subscription | null> {
-  return WebhookSubscriptions.get(db, owner, id, new Date().toISOString())
+  return WebhookSubscriptions.get(db, owner, id, new Date().toISOString(), options.access)
+}
+
+export declare namespace getSubscription {
+  /** Private-resource visibility options. */
+  type Options = { access?: Access | undefined }
 }
 
 /**
@@ -255,6 +284,8 @@ export async function listSubscriptions(
 export declare namespace listSubscriptions {
   /** Options for {@link listSubscriptions}. */
   type Options = {
+    /** Private-resource visibility scope. */
+    access?: Access | undefined
     /** Return subscriptions older than this id (keyset paging, newest first). */
     cursor?: string | undefined
     /** Maximum subscriptions to return. */
@@ -269,13 +300,22 @@ export declare namespace listSubscriptions {
  * since the per-owner set is bounded by `maxPerOwner`. Feeds the opt-in
  * `meta.totalCount` on `GET /webhooks`.
  */
-export async function countSubscriptions(db: Db.Db, owner: Owner): Promise<number> {
-  return WebhookSubscriptions.count(db, owner, new Date().toISOString())
+export async function countSubscriptions(
+  db: Db.Db,
+  owner: Owner,
+  options: countSubscriptions.Options = {},
+): Promise<number> {
+  return WebhookSubscriptions.count(db, owner, new Date().toISOString(), options.access)
+}
+
+export declare namespace countSubscriptions {
+  /** Private-resource visibility options. */
+  type Options = { access?: Access | undefined }
 }
 
 /**
  * Patches an owner's subscription, re-validating the URL when changed.
- * Returns null when absent. The status column drives the poller's partial
+ * Returns null when absent. The status column drives the partial active
  * index, so no secondary-index maintenance is needed.
  */
 export async function updateSubscription(
@@ -285,7 +325,12 @@ export async function updateSubscription(
   patch: PatchInput,
   options: updateSubscription.Options = {},
 ): Promise<Subscription | null> {
-  const current = await getSubscription(db, owner, id)
+  const current = await getSubscription(
+    db,
+    owner,
+    id,
+    options.access === undefined ? {} : { access: options.access },
+  )
   if (!current) return null
 
   if (current.destination.type !== 'url' && patch.destination?.type === 'url')
@@ -307,43 +352,29 @@ export async function updateSubscription(
 export declare namespace updateSubscription {
   /** Options for {@link updateSubscription}. */
   type Options = {
+    /** Private-resource visibility scope. */
+    access?: Access | undefined
     /** Clock used for timestamps (injectable for tests). */
     now?: (() => Date) | undefined
   }
 }
 
 /** Deletes an owner's subscription; its delivery rows cascade via the FK. */
-export async function deleteSubscription(db: Db.Db, owner: Owner, id: string): Promise<boolean> {
-  return WebhookSubscriptions.remove(db, owner, id, new Date().toISOString())
-}
-
-/**
- * Lists active subscriptions for a `(chainId, eventType)` stream. Used by the
- * poller; one indexed query (the partial status index replaces the old
- * secondary key space).
- */
-export async function listActive(
+export async function deleteSubscription(
   db: Db.Db,
-  chainId: number,
-  eventType: EventType,
-): Promise<Subscription[]> {
-  const pairs = await listActiveWithCursors(db, chainId, eventType)
-  return pairs.map((pair) => pair.subscription)
+  owner: Owner,
+  id: string,
+  options: deleteSubscription.Options = {},
+): Promise<boolean> {
+  return WebhookSubscriptions.remove(db, owner, id, new Date().toISOString(), options.access)
 }
 
-/**
- * Lists a stream's live active subscriptions paired with their poller cursors,
- * from one query. The poller's per-tick lookup.
- */
-export async function listActiveWithCursors(
-  db: Db.Db,
-  chainId: number,
-  eventType: EventType,
-): Promise<{ cursor: string | null; subscription: Subscription }[]> {
-  return WebhookSubscriptions.listActive(db, chainId, eventType, new Date().toISOString())
+export declare namespace deleteSubscription {
+  /** Private-resource visibility options. */
+  type Options = { access?: Access | undefined }
 }
 
-/** Reads every live active subscription on a chain in one poller query. */
+/** Reads every live active subscription on a chain in one query. */
 export async function listActiveForChain(
   db: Db.Db,
   options: listActiveForChain.Options,
@@ -356,29 +387,10 @@ export async function listActiveForChain(
 }
 
 export declare namespace listActiveForChain {
-  /** Filters for the poller's chain-level subscription read. */
+  /** Filters for the chain-level subscription read. */
   type Options = Pick<WebhookSubscriptions.listActiveForChain.Options, 'chainId' | 'eventTypes'>
 }
 
-/**
- * Reads the freshest cursor block across a chain's active subscriptions, or
- * null when none carry a cursor. Creation checkpoints count at their recorded
- * head, so a brand-new subscription reads as fresh.
- */
-export async function maxCursorBlock(db: Db.Db, chainId: number): Promise<number | null> {
-  const cursors = await WebhookSubscriptions.listActiveCursors(
-    db,
-    chainId,
-    new Date().toISOString(),
-  )
-  let max: number | null = null
-  for (const cursor of cursors) {
-    const block = cursorBlock(cursor)
-    if (block !== undefined && (max === null || block > max)) max = block
-  }
-  return max
-}
-
 /** Decodes the block component of a subscription cursor, if any. */
 export function cursorBlock(cursor: string | null): number | undefined {
   if (cursor === null) return undefined
@@ -392,47 +404,23 @@ export async function getCursor(db: Db.Db, subscriptionId: string): Promise<stri
   return WebhookSubscriptions.getCursor(db, subscriptionId)
 }
 
-/** Writes a cursor only when its stored value matches the expected cursor. */
-export async function compareAndSetCursor(
-  db: Db.Db,
-  options: compareAndSetCursor.Options,
-): Promise<boolean> {
-  return WebhookSubscriptions.compareAndSetCursor(db, options)
-}
-
-export declare namespace compareAndSetCursor {
-  /** Options for {@link compareAndSetCursor}. */
-  type Options = WebhookSubscriptions.compareAndSetCursor.Options
-}
-
-/** Writes cursors whose stored values match their expected cursors. */
-export async function compareAndSetCursors(
-  db: Db.Db,
-  options: compareAndSetCursors.Options,
-): Promise<Set<string>> {
-  return WebhookSubscriptions.compareAndSetCursors(db, options)
-}
-
-export declare namespace compareAndSetCursors {
-  /** Options for {@link compareAndSetCursors}. */
-  type Options = WebhookSubscriptions.compareAndSetCursors.Options
-}
-
-/** Writes a subscription's keyset cursor. */
-export async function setCursor(db: Db.Db, subscriptionId: string, cursor: string): Promise<void> {
-  await WebhookSubscriptions.setCursor(db, subscriptionId, cursor)
-}
-
 /**
  * Deletes expired MPP-owned subscriptions (delivery rows cascade) and
- * deliveries past retention. Reads already filter expiry at query time — this
- * is the janitor reclaiming space, called best-effort per poller tick.
+ * deliveries past retention. Reads already filter expiry at query time; this
+ * is the janitor reclaiming space, run best-effort on a schedule.
  */
-export async function pruneExpired(db: Db.Db, options: pruneExpired.Options = {}): Promise<void> {
+export async function pruneExpired(
+  db: Db.Db,
+  options: pruneExpired.Options = {},
+): Promise<pruneExpired.Result> {
   const iso = (options.now ?? (() => new Date()))().toISOString()
-  await WebhookDeliveries.pruneExpired(db, iso)
-  await WebhookQueueEvents.pruneExpired(db, iso)
-  await WebhookSubscriptions.pruneExpired(db, iso)
+  // Sequential on purpose: the subscription delete cascades into the other
+  // tables, so overlapping it with their prunes risks deadlocks.
+  return {
+    completions: await WebhookQueueCompletions.pruneExpired(db, iso),
+    deliveries: await WebhookDeliveries.pruneExpired(db, iso),
+    subscriptions: await WebhookSubscriptions.pruneExpired(db, iso),
+  }
 }
 
 export declare namespace pruneExpired {
@@ -441,6 +429,16 @@ export declare namespace pruneExpired {
     /** Clock used for expiry evaluation; injectable for tests. */
     now?: (() => Date) | undefined
   }
+
+  /** Rows deleted per table; a count pinned at the batch bound means expiry is outpacing pruning. */
+  type Result = {
+    /** Deleted `webhook_queue_completions` rows. */
+    completions: number
+    /** Deleted `webhook_deliveries` rows. */
+    deliveries: number
+    /** Deleted `webhook_subscriptions` rows. */
+    subscriptions: number
+  }
 }
 
 /**
@@ -449,6 +447,13 @@ export declare namespace pruneExpired {
  */
 export const deliveryRetentionMs = 7 * 24 * 60 * 60 * 1_000
 
+/**
+ * Completions dedupe window: replays of a completed obligation are suppressed
+ * this long. Deliberately its own literal so per-deployment log-retention
+ * tuning cannot move it.
+ */
+export const dedupeRetentionMs = 7 * 24 * 60 * 60 * 1_000
+
 /** A compact Cloudflare Queue message referencing a durable staged envelope. */
 export type QueueReference = {
   /** Idempotent event id of the staged envelope. */
@@ -463,8 +468,6 @@ export type QueueEvent = QueueReference & {
   createdAt: string
   /** Full envelope loaded by the Queue consumer. */
   envelope: Envelope
-  /** ISO timestamp after which an unconsumed envelope may be pruned. */
-  expiresAt: string
 }
 
 /** A claim newer than this counts as an in-flight attempt; above the 10s destination timeout default. */
@@ -489,16 +492,17 @@ export async function ensureQueueEvents(
   options: ensureQueueEvents.Options = {},
 ): Promise<ensureQueueEvents.Result> {
   const now = (options.now ?? (() => new Date()))()
-  const expiresAt = new Date(now.getTime() + (options.ttl ?? deliveryRetentionMs)).toISOString()
+  // Carried so the delivery worker can measure observation-to-attempt without
+  // re-reading the block; replays have no observation and stay null.
+  const observedAt =
+    options.observedAt === undefined ? null : new Date(options.observedAt).toISOString()
   const events = dispatchables.map(({ envelope, subscription }) => ({
     createdAt: now.toISOString(),
     envelope,
     eventId: envelope.id,
-    // Inert while pending; the meaningful dedupe deadline is stamped at
-    // terminal transitions.
-    expiresAt,
     // Due immediately; the value orders the sweep so it is never null here.
     nextAttemptAt: now.toISOString(),
+    observedAt,
     subscriptionId: subscription.id,
   }))
   return {
@@ -516,12 +520,12 @@ export declare namespace ensureQueueEvents {
     subscription: Subscription
   }
 
-  /** Staged-envelope retention options. */
+  /** Staging options. */
   type Options = {
     /** Clock used for staging timestamps. */
     now?: (() => Date) | undefined
-    /** Staged-envelope TTL in ms; defaults to {@link deliveryRetentionMs}. */
-    ttl?: number | undefined
+    /** Epoch ms the head owing these events was observed; absent on replays. */
+    observedAt?: number | undefined
   }
 
   /** Created-row count plus references for every requested obligation. */
@@ -557,7 +561,7 @@ export function completeQueueEvent(
 ): Promise<boolean> {
   return WebhookQueueEvents.complete(db, reference, {
     ...options,
-    expiresAt: new Date(Date.now() + deliveryRetentionMs).toISOString(),
+    expiresAt: new Date(Date.now() + dedupeRetentionMs).toISOString(),
   })
 }
 
@@ -567,7 +571,7 @@ export declare namespace completeQueueEvent {
     /** Claim marker from the claimed record's `attemptingAt`. */
     claimedAt: string
     /** Terminal obligation outcome. */
-    status: WebhookQueueEvents.TerminalStatus
+    status: WebhookQueueCompletions.TerminalStatus
   }
 }
 
@@ -652,10 +656,13 @@ export async function deliverClaimedAndRecord(
     new Date().toISOString(),
   )
   if (!subscription || subscription.status !== 'active') return { status: 'skipped' }
+  // A staged row predating the observation column, or a replay, reads null.
+  const observedAt = claimed.observedAt ? Date.parse(claimed.observedAt) : Number.NaN
   return {
     result: await deliverAndRecord(db, subscription, claimed.envelope, {
       ...options,
       dequeuedAt,
+      ...(Number.isNaN(observedAt) ? {} : { observedAt }),
       subscriptionReadMs: Date.now() - subscriptionReadStartedAt,
     }),
     status: 'delivered',
@@ -667,6 +674,8 @@ export declare namespace deliverClaimedAndRecord {
   type Claimed = {
     /** Immutable event envelope to deliver. */
     envelope: Envelope
+    /** ISO head-observation stamp carried by the staged row; null on replays. */
+    observedAt?: string | null | undefined
     /** Subscription re-resolved for current status and secret. */
     subscriptionId: string
   }
@@ -714,7 +723,7 @@ export async function recordDelivery(
 ): Promise<void> {
   const ttl = options.ttl ?? deliveryRetentionMs
   // The retention deadline replaces the old store TTL: reads filter on it at
-  // query time and the poller prunes past it. Anchored to write time (not the
+  // query time and pruning reclaims past it. Anchored to write time (not the
   // row's `createdAt`, which tests pin) — exactly like the old `put` TTL.
   const expiresAt = new Date(Date.now() + ttl).toISOString()
   await WebhookDeliveries.insert(db, delivery, expiresAt)
@@ -772,14 +781,21 @@ export async function getDelivery(
 
 /**
  * Default number of consecutive delivery failures after which a subscription
- * auto-disables (and is dropped from the poller's active index).
+ * auto-disables (and is dropped from the partial active index).
  */
 export const maxFailures = 10
 
+/**
+ * How stale `lastDeliveryAt` may get before a success rewrites it. Read only
+ * for display, so exactness is traded for not rewriting the row per delivery.
+ */
+const lastDeliveryPrecisionMs = 60_000
+
 /**
  * Records a successful delivery: resets the consecutive-failure counter and
- * stamps `lastDeliveryAt`. A column-targeted update, so a concurrent patch is
- * never clobbered by the stale copy carried through the delivery queue.
+ * refreshes `lastDeliveryAt` at most once per precision window. Returns the
+ * written row, or the caller's snapshot when the write was skipped or the row
+ * deleted.
  */
 export async function recordSuccess(
   db: Db.Db,
@@ -787,11 +803,13 @@ export async function recordSuccess(
   options: recordSuccess.Options = {},
 ): Promise<Subscription> {
   const now = (options.now ?? (() => new Date()))()
-  const iso = now.toISOString()
-  const next = await WebhookSubscriptions.recordSuccess(db, subscription.id, iso)
-  // A concurrently deleted subscription is not resurrected; return the
-  // optimistic next state so the caller still observes the outcome.
-  return next ?? { ...subscription, failureCount: 0, lastDeliveryAt: iso, updatedAt: iso }
+  const next = await WebhookSubscriptions.recordSuccess(db, subscription.id, {
+    now: now.toISOString(),
+    staleBefore: new Date(now.getTime() - lastDeliveryPrecisionMs).toISOString(),
+  })
+  // No row means the write was skipped or the row was deleted; neither
+  // resurrects, so keep the caller's timestamps.
+  return next ?? { ...subscription, failureCount: 0 }
 }
 
 export declare namespace recordSuccess {
@@ -805,8 +823,10 @@ export declare namespace recordSuccess {
 /**
  * Records a failed delivery: atomically increments the consecutive-failure
  * counter and, once it reaches `maxFailures`, sets `status: 'disabled'` so the
- * subscription drops out of the poller's partial index (surfaced via the API).
- * Returns the updated subscription.
+ * subscription drops out of the partial active index (surfaced via the API).
+ * Once disabled at the cap the row is left alone, so an outage's in-flight
+ * failures stop contending on its lock. Returns the written row, or the
+ * caller's snapshot advanced optimistically.
  */
 export async function recordFailure(
   db: Db.Db,
@@ -818,14 +838,14 @@ export async function recordFailure(
   const max = options.maxFailures ?? maxFailures
   const next = await WebhookSubscriptions.recordFailure(db, subscription.id, max, iso)
   if (next) return next
-  // A concurrently deleted subscription is not resurrected; return the
-  // optimistic next state so the caller still observes the outcome.
-  const failureCount = subscription.failureCount + 1
+  // No row means skipped (already disabled at the cap) or deleted; neither
+  // resurrects, so keep the caller's timestamps. Capped so chained skips
+  // cannot grow the counter past what the store would hold.
+  const failureCount = Math.min(subscription.failureCount + 1, max)
   return {
     ...subscription,
     failureCount,
     ...(failureCount >= max ? { status: 'disabled' as const } : {}),
-    updatedAt: iso,
   }
 }
 
@@ -868,23 +888,32 @@ export async function deliverAndRecord(
       return { error: 'delivery failed before request', ok: false }
     }
   })()
-  const stateWriteStartedAt = Date.now()
-  if (result.ok) await recordSuccess(db, subscription, options)
-  else await recordFailure(db, subscription, options)
-  const stateWriteMs = Date.now() - stateWriteStartedAt
-
+  // Overlapped: the two writes touch different rows and the log carries the
+  // immutable pre-attempt subscription, so it never reads the state write's
+  // result. Sequentially they cost two Postgres round trips per delivery.
+  const writeStartedAt = Date.now()
   // Append a delivery-log row. Best-effort: a logging failure must never change
   // the delivery outcome the caller (Queue consumer / inline path) acts on.
-  const deliveryLogStartedAt = Date.now()
-  try {
-    await recordDelivery(
-      db,
-      buildDelivery({ attempt, envelope, result, subscription }, options),
-      options.deliveryRetentionMs === undefined ? {} : { ttl: options.deliveryRetentionMs },
-    )
-  } catch {
-    // delivery logging is best-effort
-  }
+  const deliveryLog = (async () => {
+    try {
+      await recordDelivery(
+        db,
+        buildDelivery({ attempt, envelope, result, subscription }, options),
+        options.deliveryRetentionMs === undefined ? {} : { ttl: options.deliveryRetentionMs },
+      )
+    } catch {
+      // delivery logging is best-effort
+    }
+    return Date.now() - writeStartedAt
+  })()
+  const stateWrite = (async () => {
+    if (result.ok) await recordSuccess(db, subscription, options)
+    else await recordFailure(db, subscription, options)
+    return Date.now() - writeStartedAt
+  })()
+  // A state-write rejection still propagates to the caller's retry path; the
+  // log promise never rejects, so it cannot mask it or go unhandled.
+  const [stateWriteMs, deliveryLogMs] = await Promise.all([stateWrite, deliveryLog])
   const completedAt = Date.now()
 
   // Emit after all delivery work so the timings cover every stage. The
@@ -901,19 +930,34 @@ export async function deliverAndRecord(
       subscription,
       attempt,
       timings: {
-        deliveryLogMs: completedAt - deliveryLogStartedAt,
+        deliveryLogMs,
         envelopeToQueueMs:
           options.queuedAt === undefined || Number.isNaN(envelopeAt)
             ? undefined
             : Math.max(0, options.queuedAt - envelopeAt),
         endToEndMs: eventAt === undefined ? undefined : Math.max(0, completedAt - eventAt),
+        // The attempt leaving, not bookkeeping finishing: everything after
+        // `startedAt` is either the subscriber's time or our own recording,
+        // neither of which delays the event reaching them. Gated on a request
+        // actually being made, so a failure before send (formatting, invalid
+        // destination) does not report an attempt that never left.
+        eventToAttemptMs:
+          eventAt === undefined || result.durationMs === undefined
+            ? undefined
+            : Math.max(0, startedAt - eventAt),
         eventToEnvelopeMs:
           eventAt === undefined || Number.isNaN(envelopeAt)
             ? undefined
             : Math.max(0, envelopeAt - eventAt),
+        observedToAttemptMs:
+          options.observedAt === undefined || result.durationMs === undefined
+            ? undefined
+            : Math.max(0, startedAt - options.observedAt),
+        preflightMs: Math.max(0, startedAt - dequeuedAt),
         processingMs: Math.max(0, completedAt - dequeuedAt),
         queueWaitMs:
           options.queuedAt === undefined ? undefined : Math.max(0, dequeuedAt - options.queuedAt),
+        settleMs: Math.max(0, completedAt - writeStartedAt),
         stateWriteMs,
         subscriptionReadMs: options.subscriptionReadMs,
       },
@@ -960,6 +1004,8 @@ export declare namespace deliverAndRecord {
     metrics?: Metrics.Metrics | undefined
     /** Clock used for timestamps; injectable for tests. */
     now?: (() => Date) | undefined
+    /** Epoch ms the head owing this event was observed; absent on replays. */
+    observedAt?: number | undefined
     /** Cloudflare Queue delivery attempt, starting at one; absent for inline delivery paths. */
     queueAttempt?: number | undefined
     /** Queue enqueue time as epoch milliseconds, used to isolate queue wait. */
@@ -1044,8 +1090,11 @@ function buildDelivery(
  * re-deliveries are dedupable by the receiver.
  */
 export function eventId(options: eventId.Options): string {
-  const input = `${options.chainId}:${options.eventType}:${options.blockNumber}:${options.logIndex}`
-  return `evt_${Hash.sha256(Hex.fromString(input)).slice(2)}`
+  return eventIdFromKey({
+    chainId: options.chainId,
+    eventType: options.eventType,
+    key: `${options.blockNumber}:${options.logIndex}`,
+  })
 }
 
 export declare namespace eventId {
@@ -1062,6 +1111,24 @@ export declare namespace eventId {
   }
 }
 
+/** Computes a stable event id from an event-type-specific identity key. */
+export function eventIdFromKey(options: eventIdFromKey.Options): string {
+  const input = `${options.chainId}:${options.eventType}:${options.key}`
+  return `evt_${Hash.sha256(Hex.fromString(input)).slice(2)}`
+}
+
+export declare namespace eventIdFromKey {
+  /** Stable identity inputs for a webhook event. */
+  type Options = {
+    /** Chain the event belongs to. */
+    chainId: number
+    /** Event type. */
+    eventType: EventType
+    /** Stable event-type-specific identity. */
+    key: string
+  }
+}
+
 /** The JSON envelope delivered to subscribers. */
 export type Envelope = {
   /** Chain the event occurred on. */
@@ -1115,6 +1182,38 @@ export declare namespace buildEnvelope {
   }
 }
 
+/** Builds a delivery envelope from a stable application-event identity. */
+export function buildKeyedEnvelope(options: buildKeyedEnvelope.Options): Envelope {
+  const { subscription } = options
+  return {
+    chainId: subscription.chainId,
+    ...(subscription.context === undefined ? {} : { context: subscription.context }),
+    createdAt: (options.createdAt ?? new Date()).toISOString(),
+    data: options.data,
+    id: eventIdFromKey({
+      chainId: subscription.chainId,
+      eventType: subscription.eventType,
+      key: options.key,
+    }),
+    subscriptionId: subscription.id,
+    type: subscription.eventType,
+  }
+}
+
+export declare namespace buildKeyedEnvelope {
+  /** Application-event envelope fields. */
+  type Options = {
+    /** Timestamp to stamp on the envelope; defaults to now. */
+    createdAt?: Date | undefined
+    /** Public event payload. */
+    data: unknown
+    /** Stable event-type-specific identity. */
+    key: string
+    /** Subscription the event matched. */
+    subscription: Subscription
+  }
+}
+
 /**
  * Builds a synthetic `ping` envelope so an owner can test a subscription's
  * endpoint (connectivity, TLS, signature verification) without waiting for a real