@ultimat3/core 12.0.0 → 14.0.0

package/CLAUDE.md

@@ -450,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": "12.0.0",
+  "version": "14.0.0",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
   "license": "MIT",
   "type": "module",

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;
@@ -66,6 +108,13 @@ export interface Ctx extends CtxServices {
   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;
@@ -133,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.

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,
@@ -535,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/schema-error-codes.ts

@@ -8,6 +8,7 @@
 // one place and not the other fails the build instead of quietly disagreeing at runtime.
 
 import { registerErrorCodes } from './error-codes';
+import { registerErrorRetry } from './error-retry';
 
 /** Mirrors `SCHEMA_ERROR_CODES` in `packages/schema/src/errors.ts`. Keep the titles identical. */
 export const SCHEMA_ERROR_CODE_TITLES: Readonly<Record<string, string>> = Object.freeze({
@@ -26,3 +27,23 @@ registerErrorCodes(
     Object.entries(SCHEMA_ERROR_CODE_TITLES).map(([code, title]) => [code, { title }]),
   ),
 );
+
+// And how each is RETRIED, here for the same tier reason the titles are here.
+//
+// Every one is LISTED rather than left to the default, which is the lesson `packages/jobs/src/
+// errors.ts` writes up for its own six terminal webhook codes: `classifyThrown` reads an
+// unregistered code as UNCLASSIFIED, so the attempt count governs and a schema refusal raised
+// inside a job body burns the whole retry policy re-proving an answer no attempt can change.
+//
+// Measured cost before this: `@ultimat3/scraping` spent FIVE browser launches on a page carrying
+// a `<div constructor="...">` — five navigations, five arrivals at a login — and dead-lettered
+// reporting that the browser went away, about a browser that answered perfectly.
+// `packages/scraping/src/cdp-target.ts` names the gap and says it cannot be closed from there.
+//
+// A value that does not match its schema does not match it on attempt five either.
+registerErrorRetry({
+  X_VALIDATION_FAILED: 'terminal',
+  X_SCHEMA_UNSUPPORTED: 'terminal',
+  X_SCHEMA_DISCRIMINANT_INVALID: 'terminal',
+  X_SCHEMA_DEFAULT_UNSHAREABLE: 'terminal',
+});

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 };
+}