@ultimat3/core 11.3.0 → 13.0.0

package/CLAUDE.md

@@ -121,6 +121,7 @@ shape against a locally declared sample interface for exactly that reason.
 | how many at once | `flight-gate.ts` | hand-over on release, refusal past `maxQueued`, injectable `overflow:` refusal |
 | whether an answer still applies | `generation-fence.ts` | `X_SUPERSEDED` / `isSuperseded`; nothing else in the tree had one |
 | which HTTP statuses are worth repeating | `retryable-status.ts` | `>= 500` plus 408, 409, 425, 429 — the two byte-identical copies' set |
+| how long this request has left | `request-budget.ts` (`Ctx.deadlineAt`, `REQUEST_TIMEOUT_HEADER`) | `@ultimat3/http`'s `startDeadline` is the one production writer of the instant; `traceHeaders()` is the one writer of the header. It lives here because the READER is tier 2 and the WRITER is a typed client in tier 0, and a second literal for the header name is a propagation that stops working the day either string is edited. A spent budget sends nothing rather than `0` — the far side ignores anything under 1ms and falls back to its own, which is the failure the header exists to prevent, one hop later |
 | the five above, composed into one typed-client call | `client-flight.ts` + `client-wire.ts` | `@ultimat3/action` and `@ultimat3/query` both project a typed client and are both tier 3, so neither could import the other: it shipped as a byte-identical 288-line + 85-line copy in each, policed by a `client-twin.test.ts` in both. Both packages re-export these names, so their public surface is unchanged. Declares NO code of its own — `X_SUPERSEDED`, `X_TIMEOUT` and `X_FLIGHT_GATE_OVERLOADED` are already here |
 | is this `unknown` a keyed record? | `json-object.ts` | `isJsonObject`, which was the same three terms in both those packages' `stable.ts`. A `Date` and a class instance PASS: it narrows a shape, it does not certify provenance |
 | a value that must not be printed | `secret.ts` | redacted by VALUE; `revealSecret()` is the one way out, on purpose greppable |
@@ -449,6 +450,32 @@ Gotchas:
   where an app reads an undeclared service, which is the point, but `examples/dummy` ships one
   such read and it would land on the app gate's ratchet. Land it as its own change, alone, with a
   full `bun run verify` — never folded into another branch.
+- **`Ctx extends CtxFacts, CtxServices`, and `createContext` holds the framework's ONE irreducible
+  assertion** (`As of 2026-08-24`). Different hole from the bullet above, and the note there —
+  "an augmentation adds NAMED members and `Ctx extends CtxServices` picks them up with no index
+  signature at all" — is exactly why: those NAMED members are then REQUIRED of every value typed
+  `Ctx`, and no framework function can obtain them. They arrive through `init.services` (a
+  `ServiceBag`, string-indexed) and through `installedServices()`, which returns the same. So
+  `createContext` cannot type-check its own literal against `Ctx`, and neither could
+  `@ultimat3/http`'s `createRequestContext`, which failed to compile inside `examples/dummy` with
+  `TS2739: missing posts, orgs` while this repo's own gate — augmenting nothing — stayed green.
+
+  `CtxFacts` is everything the FRAMEWORK sets; `Ctx` is that plus `CtxServices`. Structurally
+  identical for a reader, and everything for a constructor. It bought two deletions: the `preview`
+  assertion is gone (that value is honestly a `CtxFacts`, which is also what a `ServiceFactory`
+  receives — a factory has never been able to read a sibling service and the type now says so),
+  and `@ultimat3/http` has **no assertion at all**, because `createRequestContext` composes
+  `createContext()` instead of building a second context beside it.
+
+  **One `as Ctx` remains and four alternatives were built and measured before it was kept.**
+  `Partial<CtxServices>` removes it and makes `ctx.posts` `PostRepo | undefined` for every app —
+  true, and a breaking change to the documented seam. Typing `CtxInit.services` as `CtxServices`
+  moves the proof to the caller and breaks every internal `createContext()` in an app's program,
+  because an app typechecks this tree's sources through its project references. A generic
+  `createContext<S>` returns a context no framework caller can pass where a `Ctx` is wanted. An
+  overload whose implementation signature returns the looser type compiles only through
+  TypeScript's documented bivariance hole — the same assertion, laundered. The file header carries
+  this list; the structural repair is a major and belongs with the index-signature deletion above.
 - Tests that touch the registry, the lifecycle or the listener table must call
   `resetErrorCodes()` / `resetLifecycle()` / `resetListeners()`.
 - `onShutdown`'s return value is the unregister, and every caller that can be started twice owns

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "11.3.0",
+  "version": "13.0.0",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
   "license": "MIT",
   "type": "module",

package/src/client-wire.ts

@@ -1,6 +1,7 @@
 /**
- * What a typed client puts on the wire and reads back off it: the W3C trace header, the
- * problem+json body, and the immutable answer one dispatch hands to every caller sharing it.
+ * What a typed client puts on the wire and reads back off it: the ambient call context as
+ * headers — the W3C trace and the remaining request budget — the problem+json body, and the
+ * immutable answer one dispatch hands to every caller sharing it.
  *
  * Tier 0 because `@ultimat3/action` and `@ultimat3/query` need this identical file and are both
  * tier 3, so neither may import the other — the shape `canonical-json.ts` is already here for.
@@ -11,6 +12,7 @@
 import type { ErrorRetry } from './error-retry';
 import { declaredErrorRetry } from './error-retry';
 import { isJsonObject } from './json-object';
+import { budgetHeaders } from './request-budget';
 import { isRetryableStatus } from './retryable-status';
 import { currentSpanContext, traceparent } from './telemetry';
 
@@ -30,17 +32,31 @@ const TRACE_ID = /^[0-9a-f]{32}$/;
 const SPAN_ID = /^[0-9a-f]{16}$/;
 
 /**
- * The current trace, as the W3C header — or nothing at all. `currentSpanContext()` answers with
- * an empty `spanId` when a request context exists but no span is active, and `00-<trace>--01` is
- * a header every collector drops, so an incomplete context sends none. In a browser there is no
- * ambient context and this is always empty, which is also what keeps a cross-origin call from
- * acquiring a CORS preflight it did not have.
+ * Everything this process knows about the call in flight, as headers: the W3C trace, and how much
+ * of the request budget is left. Both callers (`@ultimat3/action`'s `postOnce` and
+ * `@ultimat3/query`'s reader) spread it BEFORE the caller's own headers, so an explicit value
+ * still wins.
+ *
+ * The trace half: `currentSpanContext()` answers with an empty `spanId` when a request context
+ * exists but no span is active, and `00-<trace>--01` is a header every collector drops, so an
+ * incomplete context sends none. In a browser there is no ambient context and this is always
+ * empty, which is also what keeps a cross-origin call from acquiring a CORS preflight it did not
+ * have.
+ *
+ * The budget half is independent of it, and that is deliberate: a deadline must propagate through
+ * a hop that is not being traced. `budgetHeaders()` answers `{}` outside a request and for a
+ * context with no deadline, so a browser and a job are unchanged — the header only appears where
+ * something really is waiting on a socket.
+ *
+ * The name is the trace half's alone for one reason: renaming it means editing
+ * `packages/{action,query}/src/client.ts`, and both spell it as a value import.
  */
 export function traceHeaders(): Record<string, string> {
+  const budget = budgetHeaders();
   const context = currentSpanContext();
-  if (context === undefined) return {};
-  if (!TRACE_ID.test(context.traceId) || !SPAN_ID.test(context.spanId)) return {};
-  return { traceparent: traceparent(context) };
+  if (context === undefined) return budget;
+  if (!TRACE_ID.test(context.traceId) || !SPAN_ID.test(context.spanId)) return budget;
+  return { ...budget, traceparent: traceparent(context) };
 }
 
 /**

package/src/context.ts

@@ -1,6 +1,34 @@
 // Single responsibility: the ambient request context. Authz, tracing, locale, tz and the
 // service bag reach every layer through AsyncLocalStorage instead of being threaded as
 // parameters — otherwise every signature in the framework grows a `ctx` argument twice.
+//
+// THERE IS EXACTLY ONE ASSERTION IN THIS FILE AND IT IS IRREDUCIBLE (`As of 2026-08-24`). It is
+// the `as Ctx` in `createContext`, and it is the LAST one: the second — over `preview` — is gone,
+// because `CtxFacts` gives that value an honest type, and `@ultimat3/http`'s
+// `createRequestContext` now composes this function instead of building a second context beside
+// it, so that package has none at all.
+//
+// Why the last one cannot go. `Ctx extends CtxServices`, and `CtxServices` is the seam an app
+// augments (`declare module '@ultimat3/core'`) to declare `ctx.posts`. Those members are
+// therefore REQUIRED of any value typed `Ctx` — and this function cannot obtain them: they arrive
+// through `init.services`, a `ServiceBag` with a string index signature, and through
+// `installedServices()`, which returns the same. No function can return a value of a type whose
+// required members it has no way to hold, and no type operator can separate an augmented member
+// from a core one either — the index signature makes `keyof Ctx` `string`, so every `Omit` over it
+// removes everything.
+//
+// Four alternatives were built and measured before this line was kept. Making the augmented half
+// `Partial<CtxServices>` removes the assertion and turns `ctx.posts` into `PostRepo | undefined`
+// for every app — true, and a breaking change to the documented seam. Requiring `CtxInit.services`
+// to be a `CtxServices` moves the proof to the caller and breaks every internal `createContext()`
+// in an app's program, because an app typechecks the framework's sources through its project
+// references. A generic `createContext<S>` returns a context no framework caller can pass where a
+// `Ctx` is wanted. And an overload whose implementation signature returns the looser type compiles
+// only through TypeScript's documented bivariance hole — the same assertion, laundered.
+//
+// So it stays, bounded to that one expression, with `CtxFacts` beside it carrying everything this
+// package CAN prove. The structural repair is to `Ctx extends CtxServices` itself and it is a
+// major: this comment is the record of why it was not done quietly.
 
 import { type Actor, anonymousActor } from './actor';
 import { asyncContext } from './async-context';
@@ -37,7 +65,21 @@ export interface ServiceBag {
   readonly [service: string]: unknown;
 }
 
-export interface Ctx extends CtxServices {
+/**
+ * Every member the FRAMEWORK sets on a context — core's `Ctx` with the app's `CtxServices`
+ * augmentation removed. It exists because a framework function cannot type-check an object literal
+ * against a type carrying members only the app's boot knows about: `Ctx extends CtxServices`, an
+ * app augments `CtxServices` with `declare module`, and every service it declares then became a
+ * REQUIRED member of every context literal in the framework. `@ultimat3/http`'s
+ * `createRequestContext` stopped compiling inside `examples/dummy` for exactly that reason
+ * (`TS2739: missing posts, orgs`), while the framework's own gate — which augments nothing —
+ * stayed green.
+ *
+ * A service FACTORY is handed this and not a `Ctx`, which is also more honest than what it had:
+ * `installedServices` builds the bag, so a factory has never been able to read a sibling service,
+ * and the type now says so.
+ */
+export interface CtxFacts {
   readonly requestId: string;
   /** W3C trace id — the same value crosses HTTP -> job -> live query. */
   readonly traceId: string;
@@ -52,10 +94,27 @@ export interface Ctx extends CtxServices {
   now(): Date;
   readonly logger: Logger;
   readonly signal: AbortSignal;
+  /**
+   * Epoch milliseconds this request's budget runs out at, or `null` when nothing set one.
+   *
+   * The value BEHIND `signal`, published as a number because a signal can only say "already over"
+   * — and every outbound hop needs to say how much is LEFT. Without it a service called at t=29 of
+   * a 30s budget started a fresh 30s of its own: real work, holding a pool slot and a vendor
+   * connection, for half a minute after the caller's socket was answered `X_TIMEOUT`. `null` for a
+   * job, a task and a CLI command, none of which has a caller waiting on a socket.
+   */
+  readonly deadlineAt: number | null;
   /** Late-bound services, for anything not worth a type augmentation. */
   readonly services: ServiceBag;
 }
 
+/**
+ * The context as it EXISTS once a boot's services ride on it: the framework's half plus the app's
+ * augmentation. Structurally identical to what `Ctx` has always been — the split above changes
+ * nothing a reader sees, and everything a CONSTRUCTOR is asked to prove.
+ */
+export interface Ctx extends CtxFacts, CtxServices {}
+
 export interface CtxInit {
   readonly requestId?: string | undefined;
   readonly traceId?: string | undefined;
@@ -67,6 +126,8 @@ export interface CtxInit {
   readonly clock?: Clock | undefined;
   readonly logger?: Logger | undefined;
   readonly signal?: AbortSignal | undefined;
+  /** Epoch ms. `@ultimat3/http`'s `startDeadline` is the one production writer. */
+  readonly deadlineAt?: number | undefined;
   readonly services?: ServiceBag | undefined;
 }
 
@@ -112,6 +173,7 @@ export function createContext(init: CtxInit = {}): Ctx {
     now: () => clock.now(),
     logger: base.child({ requestId, traceId: trace }),
     signal: init.signal ?? neverAborted,
+    deadlineAt: init.deadlineAt ?? null,
   };
   // A registered service (`defineService`) closes over the ctx it is built for — actor, clock,
   // tz — so it has to run HERE, against this exact call's fields, rather than once at boot and
@@ -120,16 +182,17 @@ export function createContext(init: CtxInit = {}): Ctx {
   // what stops factories from depending on one another's instances. Explicit `init.services`
   // wins over an auto-installed one of the same name — a test's hand-built mock overrides the
   // real thing on purpose.
-  const preview = Object.freeze({ ...explicit, ...fields, services: explicit }) as Ctx;
+  const preview: CtxFacts = Object.freeze({ ...explicit, ...fields, services: explicit });
   const services: ServiceBag = Object.freeze({ ...installedServices(preview), ...explicit });
   const ctx = {
     // Services ride ON the context, not only under `ctx.services`: `CtxServices` exists to be
     // augmented, so `ctx.posts` has to BE the service. Spread first, so a service that collides
     // with a framework field (`actor`, `logger`) loses — it stays reachable as
     // `ctx.services.actor`, and the context's own meaning never depends on what an app named a
-    // service. The assertion is the one thing this package cannot prove: an augmentation
-    // declares which services exist, only the boot code knows whether it passed them, or
-    // registered a factory for them. So a service nothing installed reads as `undefined`
+    // service. The `as Ctx` below is the file's ONE assertion and the header says why it cannot
+    // be removed: an augmentation declares which services exist, only the boot code knows whether
+    // it passed them or registered a factory for them, and a `ServiceBag` cannot prove either.
+    // So a service nothing installed reads as `undefined`
     // through `ctx.posts` — this is a frozen plain object, and it stays one on purpose: a
     // get-trap proxy that threw on absent keys would also throw on `await ctx` (the runtime
     // probes `.then`), on `JSON.stringify`, and on every optional-property check.
@@ -191,6 +254,10 @@ export function withChildContext<T>(patch: CtxPatch, fn: () => T): T {
     role: patch.role ?? parent.role,
     clock: patch.clock ?? parent.clock,
     logger: patch.logger ?? parent.logger,
+    // One request, one budget: a child scope inherits the deadline for the same reason it
+    // inherits `requestId`. A patch may SHORTEN it (a step with its own budget); nothing here
+    // lengthens it, because the socket the parent is answering does not move.
+    deadlineAt: patch.deadlineAt ?? parent.deadlineAt ?? undefined,
     signal: patch.signal ?? parent.signal,
     services: { ...carried, ...(patch.services ?? {}) },
   });

package/src/index.ts

@@ -72,7 +72,7 @@ export type {
   ThemeMode,
 } from './config';
 export { defineConfig } from './config';
-export type { Ctx, CtxInit, CtxPatch, CtxServices, ServiceBag } from './context';
+export type { Ctx, CtxFacts, CtxInit, CtxPatch, CtxServices, ServiceBag } from './context';
 export {
   createContext,
   DEFAULT_LOCALE,
@@ -509,6 +509,11 @@ export {
   registerPrimitiveRegistrar,
   resetPrimitiveRegistrars,
 } from './registrar';
+export {
+  budgetHeaders,
+  REQUEST_TIMEOUT_HEADER,
+  remainingBudgetMs,
+} from './request-budget';
 export type { Err, Ok, Result } from './result';
 export { err, isErr, isOk, map, mapErr, ok, tryCatch, unwrap, unwrapOr } from './result';
 export type { RetryDecision, RetryDeps, RetryPolicy, RetryStopReason } from './retry';
@@ -530,3 +535,24 @@ export {
   VERSION_DEFINE,
   VERSION_MANIFEST,
 } from './version';
+// The webhook wire format, at the tier both halves can reach — `@ultimat3/jobs` signs a delivery
+// and `@ultimat3/http` verifies one, and neither may import the other. Same argument
+// `timing-safe-equal.ts` makes for itself, one line above.
+export type {
+  WebhookMacInput,
+  WebhookSignatureFields,
+  WebhookSigningInput,
+} from './webhook-signature';
+export {
+  isCanonicalWebhookField,
+  parseWebhookSignatureHeader,
+  WEBHOOK_FIELD_MAX,
+  WEBHOOK_ID_HEADER,
+  WEBHOOK_SIGNATURE_HEADER,
+  WEBHOOK_SIGNATURE_VERSION,
+  WEBHOOK_TOPIC_HEADER,
+  webhookHeaders,
+  webhookMac,
+  webhookSignature,
+  webhookSigningString,
+} from './webhook-signature';

package/src/registrar.ts

@@ -54,12 +54,20 @@ export interface PrimitiveFactory {
 export const PRIMITIVE_FACTORIES = Object.freeze<readonly PrimitiveFactory[]>(
   (
     [
+      // `mutator` and not `action`, even though `Mutator extends Action`: the scan seeds `Mutator`
+      // in its own roots and the fixpoint refuses to overwrite a name it already holds, so the
+      // more specific answer wins. A `kind: 'action'` here would be the one row the scan disagrees
+      // with, and it would disagree silently in the direction that loses information.
+      { factory: 'transition', pkg: '@ultimat3/action', kind: 'mutator' },
       { factory: 'agent', pkg: '@ultimat3/ai', kind: 'action' },
       { factory: 'agentJob', pkg: '@ultimat3/ai', kind: 'job' },
       { factory: 'hive', pkg: '@ultimat3/ai', kind: 'action' },
       { factory: 'llm', pkg: '@ultimat3/ai', kind: 'action' },
       { factory: 'backfill', pkg: '@ultimat3/jobs', kind: 'job' },
+      { factory: 'exportRows', pkg: '@ultimat3/jobs', kind: 'job' },
       { factory: 'purge', pkg: '@ultimat3/jobs', kind: 'job' },
+      { factory: 'webhook', pkg: '@ultimat3/jobs', kind: 'job' },
+      { factory: 'notifier', pkg: '@ultimat3/notify', kind: 'job' },
       { factory: 'scrape', pkg: '@ultimat3/scraping', kind: 'job' },
     ] satisfies readonly PrimitiveFactory[]
   ).map((entry) => Object.freeze(entry)),

package/src/request-budget.ts

@@ -0,0 +1,44 @@
+// How much of THIS request's budget is left, and the one header that carries it to the next hop.
+// The header name lives here rather than in `@ultimat3/http` because both ends need it and only
+// one of them is tier 2: the reader is http's `resolveTimeoutMs`, the writer is a typed client in
+// tier 0, and a second literal in the writer is a propagation that silently stops working the day
+// either string is edited.
+
+import type { Ctx } from './context';
+import { tryUseContext } from './context';
+
+/**
+ * A caller may SHORTEN the hop it is calling, never lengthen it — `@ultimat3/http`'s
+ * `resolveTimeoutMs` takes the minimum of its own configured budget and this. It had ONE reader
+ * and zero writers anywhere in the tree, so a 30s gateway budget that had already been spent to
+ * t=29 handed the next service a fresh 30s: work still running, still holding a pool slot and a
+ * vendor connection, 30 seconds after the caller's socket was answered `X_TIMEOUT`.
+ */
+export const REQUEST_TIMEOUT_HEADER = 'x-request-timeout-ms';
+
+/**
+ * Milliseconds left before this context's deadline, or `undefined` when there is no deadline or
+ * it has already passed.
+ *
+ * `undefined` for a spent budget rather than `0`, and that is not a nicety: the far side ignores
+ * anything under 1ms and falls back to its OWN configured budget, so a `0` on the wire reads as
+ * "the caller asked for nothing" — the exact failure this header exists to prevent, one hop later.
+ * Whether to make a call whose budget is gone is the caller's decision (`throwIfAborted`), not
+ * this function's.
+ */
+export const remainingBudgetMs = (ctx: Ctx): number | undefined => {
+  if (ctx.deadlineAt === null) return undefined;
+  const left = Math.floor(ctx.deadlineAt - ctx.now().getTime());
+  return left >= 1 ? left : undefined;
+};
+
+/**
+ * The budget header for the ambient request, or nothing. Rounded DOWN by `remainingBudgetMs`:
+ * a hop must never be told it has more time than the caller will wait.
+ */
+export const budgetHeaders = (): Record<string, string> => {
+  const ctx = tryUseContext();
+  if (ctx === undefined) return {};
+  const left = remainingBudgetMs(ctx);
+  return left === undefined ? {} : { [REQUEST_TIMEOUT_HEADER]: String(left) };
+};

package/src/service.ts

@@ -8,10 +8,15 @@
 // with `defineService` is what lets `createContext` do that automatically instead of every
 // caller wiring `services: { posts: postsService(ctx) }` by hand at every call site.
 
-import type { Ctx, ServiceBag } from './context';
+import type { CtxFacts, ServiceBag } from './context';
 import { UltimateError } from './errors';
 
-export type ServiceFactory<T = unknown> = (ctx: Ctx) => T;
+/**
+ * `CtxFacts` and not `Ctx`: this factory runs INSIDE `createContext`, against a preview that
+ * carries no other registered service — which the paragraph above has always said and the type
+ * now enforces. It is also what lets `createContext` build that preview without an assertion.
+ */
+export type ServiceFactory<T = unknown> = (ctx: CtxFacts) => T;
 
 const factories = new Map<string, ServiceFactory>();
 
@@ -48,7 +53,7 @@ export function isManagedService(name: string): boolean {
  * service yet — a factory reads the ambient actor/clock/tz, never a sibling service, so
  * factories cannot depend on one another's instances.
  */
-export function installedServices(ctx: Ctx): ServiceBag {
+export function installedServices(ctx: CtxFacts): ServiceBag {
   if (factories.size === 0) return {};
   const bag: Record<string, unknown> = {};
   for (const [name, factory] of factories) bag[name] = factory(ctx);

package/src/webhook-signature.ts

@@ -0,0 +1,149 @@
+// Single responsibility: the webhook wire format — the canonical string, the mac over it, the
+// three headers a delivery carries, and the parse of the one header a receiver reads back.
+//
+// It lives HERE for the reason `timing-safe-equal.ts` does, in that file's own words: two packages
+// need the identical guarantee and cannot share it any other way. `@ultimat3/jobs` (tier 3) signs
+// a delivery and its boundary forbids `@ultimat3/http`; `@ultimat3/http` (tier 2) verifies one and
+// may not reach tier 3. Neither is the other's dependency, so the one copy lives at the tier both
+// can reach. Before this module the spelling was stated twice and held together by a hex literal
+// asserted in two test files — which works and is not a single source of truth.
+//
+// FORMAT and never POLICY. What counts as fresh, how large a body may be, and which status a
+// refusal answers with are the receiver's questions and stay in `@ultimat3/http`.
+
+/** The format's version: the first field of the canonical string, and the signature's key. */
+export const WEBHOOK_SIGNATURE_VERSION = 'v1';
+
+export const WEBHOOK_ID_HEADER = 'x-ultimate-webhook-id';
+export const WEBHOOK_TOPIC_HEADER = 'x-ultimate-webhook-topic';
+export const WEBHOOK_SIGNATURE_HEADER = 'x-ultimate-webhook-signature';
+
+/** Bounds the canonical string, the header echo and any error text built from either. */
+export const WEBHOOK_FIELD_MAX = 200;
+
+/** Fields a spreadsheet-free reader still must not let move a separator. See below. */
+const SEPARATOR = 0x3a;
+const DELETE = 0x7f;
+
+/** `t=<digits>,v1=<hex>`, in either order, with nothing else accepted. */
+const SIGNATURE_FIELD = /^([a-z0-9]+)=([A-Za-z0-9_-]+)$/;
+/** Digits only and bounded — see `parseWebhookSignatureHeader`. */
+const TIMESTAMP = /^\d{1,15}$/;
+
+/**
+ * A field may not move the `:` separators. Without this rule an event id of `evt:01HZ` with topic
+ * `orders.paid` and an id of `evt` with topic `01HZ:orders.paid` build the SAME canonical string —
+ * one mac authenticating two differently-labelled deliveries, which is the sender's own signature
+ * under a label it never wrote. A control character is refused for a second reason: these fields
+ * are sent as HTTP header values, and a CR or LF in one is a header nobody wrote.
+ */
+export function isCanonicalWebhookField(value: string): boolean {
+  if (value.length === 0 || value.length > WEBHOOK_FIELD_MAX) return false;
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code === SEPARATOR || code < 0x20 || code === DELETE) return false;
+  }
+  return true;
+}
+
+export interface WebhookSigningInput {
+  /** The shared secret for this endpoint. Never logged, never rendered into an error. */
+  readonly secret: string;
+  /**
+   * When this REQUEST is signed — not when the event happened. A delivery retried three days later
+   * signs again at the moment it is sent, so a receiver's freshness window measures the request in
+   * front of it rather than the age of the fact behind it.
+   */
+  readonly timestampSeconds: number;
+  readonly eventId: string;
+  readonly topic: string;
+  /** The exact text the delivery sends. Serialised by the app, signed here byte for byte. */
+  readonly body: string;
+}
+
+/** The bytes the mac is taken over. One function, so the format has one spelling anywhere. */
+export function webhookSigningString(input: WebhookSigningInput): string {
+  return `${WEBHOOK_SIGNATURE_VERSION}:${input.timestampSeconds}:${input.eventId}:${input.topic}:${input.body}`;
+}
+
+export interface WebhookMacInput {
+  readonly secret: string;
+  /**
+   * The timestamp exactly as it is spelled on the wire. A STRING and not a number, because a mac
+   * is over bytes: re-rendering it would make `t=01700000000` and `t=1700000000` one signature
+   * over two different headers.
+   */
+  readonly timestampText: string;
+  readonly eventId: string;
+  readonly topic: string;
+  /**
+   * Text on the sending side, raw BYTES on the receiving one. Identical either way — an HMAC is
+   * over a byte stream and `update(string)` encodes UTF-8 — and the bytes form never round-trips a
+   * body that is not valid UTF-8 through a decoder before the mac is taken over it.
+   */
+  readonly body: string | Uint8Array;
+}
+
+/** The hex hmac-sha256 over the canonical string. The one place either side computes one. */
+export function webhookMac(input: WebhookMacInput): string {
+  const hasher = new Bun.CryptoHasher('sha256', input.secret);
+  hasher.update(
+    `${WEBHOOK_SIGNATURE_VERSION}:${input.timestampText}:${input.eventId}:${input.topic}:`,
+  );
+  hasher.update(input.body);
+  return hasher.digest('hex');
+}
+
+/**
+ * The `x-ultimate-webhook-signature` value: `t=<seconds>,v1=<hex hmac-sha256>`.
+ *
+ * The timestamp travels in the header AND inside the mac. Both are needed: the header is what the
+ * receiver measures its window against, and the copy under the mac is what stops that header being
+ * edited on a captured request.
+ */
+export function webhookSignature(input: WebhookSigningInput): string {
+  const timestampText = String(input.timestampSeconds);
+  const mac = webhookMac({ ...input, timestampText });
+  return `t=${timestampText},${WEBHOOK_SIGNATURE_VERSION}=${mac}`;
+}
+
+/** Every header a delivery carries beyond `content-type`. One composition over the two above. */
+export function webhookHeaders(input: WebhookSigningInput): Readonly<Record<string, string>> {
+  return {
+    [WEBHOOK_ID_HEADER]: input.eventId,
+    [WEBHOOK_TOPIC_HEADER]: input.topic,
+    [WEBHOOK_SIGNATURE_HEADER]: webhookSignature(input),
+  };
+}
+
+export interface WebhookSignatureFields {
+  /** As spelled on the wire — what `webhookMac` must be given. */
+  readonly timestampText: string;
+  readonly timestampSeconds: number;
+  readonly mac: string;
+}
+
+/**
+ * The header, or `undefined` for anything this format does not define. It parses and never judges:
+ * whether the timestamp is FRESH is the receiver's question and lives one tier up.
+ */
+export function parseWebhookSignatureHeader(
+  header: string | null,
+): WebhookSignatureFields | undefined {
+  if (header === null) return undefined;
+  let timestamp: string | undefined;
+  let mac: string | undefined;
+  for (const part of header.split(',')) {
+    const match = SIGNATURE_FIELD.exec(part.trim());
+    if (match === null) return undefined;
+    const [, key, value] = match;
+    if (key === 't') timestamp = value;
+    else if (key === WEBHOOK_SIGNATURE_VERSION) mac = value;
+  }
+  if (timestamp === undefined || mac === undefined) return undefined;
+  // Digits only, and bounded. Without it `Number('nope')` is `NaN`, `NaN > toleranceMs` is FALSE,
+  // and a receiver's freshness window silently accepts every delivery — the one guard here whose
+  // failure mode is "the check does not run" rather than "the check refuses".
+  if (!TIMESTAMP.test(timestamp)) return undefined;
+  return { timestampText: timestamp, timestampSeconds: Number(timestamp), mac };
+}