@openlup/outbox 0.0.0 → 0.13.1

package/package.json

@@ -1,9 +1,62 @@
 {
   "name": "@openlup/outbox",
-  "version": "0.0.0",
-  "description": "Inert package-name registration placeholder; no outbox implementation.",
+  "version": "0.13.1",
+  "private": false,
+  "description": "Transactional PostgreSQL outbox rail; development preview.",
   "license": "Apache-2.0",
   "type": "module",
-  "files": ["README.md"],
-  "publishConfig": {"access": "public", "tag": "preview"}
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openlup/openlup.git",
+    "directory": "packages/outbox"
+  },
+  "engines": {
+    "node": "24.x"
+  },
+  "packageManager": "npm@11.19.0",
+  "sideEffects": false,
+  "files": [
+    "dist/**",
+    "src/**",
+    "sql/**",
+    "AGENTS.md",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "release-gates.json"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "test": "vitest run test",
+    "prepublishOnly": "node -e \"throw new Error('OUTBOX_DIRECTORY_PUBLISH_REFUSED')\"",
+    "api:check": "node --experimental-strip-types ./scripts/api-contract.ts",
+    "api:update": "npm run build && node --experimental-strip-types ./scripts/api-contract.ts --update",
+    "ci": "npm run build && npm run test && npm run api:check"
+  },
+  "peerDependencies": {
+    "@openlup/core": "0.13.1"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./postgres": {
+      "types": "./dist/postgres.d.ts",
+      "import": "./dist/postgres.js",
+      "default": "./dist/postgres.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js",
+      "default": "./dist/testing.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "tag": "preview"
+  }
 }

package/release-gates.json

@@ -0,0 +1,53 @@
+{
+  "schemaVersion": 5,
+  "kind": "rail",
+  "compatibilityPolicies": {
+    "internal-candidate": "Development-preview API; no stable compatibility claim.",
+    "testing-internal": "Synthetic protocol test support."
+  },
+  "packageSurface": {
+    ".": {
+      "role": "rail",
+      "maturity": "experimental",
+      "compatibilityPolicy": "internal-candidate",
+      "packageSmokeEvidence": [
+        "test/packageContract.test.ts"
+      ],
+      "entrypoint": "dist/index.d.ts",
+      "snapshot": "api/index.api.md"
+    },
+    "./postgres": {
+      "role": "rail",
+      "maturity": "experimental",
+      "compatibilityPolicy": "internal-candidate",
+      "packageSmokeEvidence": [
+        "test/packageContract.test.ts"
+      ],
+      "entrypoint": "dist/postgres.d.ts",
+      "snapshot": "api/postgres.api.md"
+    },
+    "./testing": {
+      "role": "testing",
+      "maturity": "testing",
+      "compatibilityPolicy": "testing-internal",
+      "packageSmokeEvidence": [
+        "test/packageContract.test.ts"
+      ],
+      "entrypoint": "dist/testing.d.ts",
+      "snapshot": "api/testing.api.md"
+    }
+  },
+  "pack": {
+    "code": {
+      "maxPackedBytes": 32768,
+      "maxFiles": 48
+    },
+    "docs": {
+      "maxPackedBytes": 16384,
+      "maxFiles": 12
+    },
+    "maxPackedBytes": 65536,
+    "maxUnpackedBytes": 262144,
+    "maxFiles": 64
+  }
+}

package/sql/0001_outbox.sql

@@ -0,0 +1,329 @@
+-- Public platform communications outbox rail: the queue table, the dormant-event-type
+-- allowlist, and the claim/ack protocol that drains them.
+--
+-- WHAT THIS FORWARD SHIPS, AND WHY IT IS THE FIRST ONE CARRYING FUNCTIONS.
+-- The baseline and the read-parity forward both hold `grep -c 'CREATE FUNCTION'` = 0 on
+-- purpose. This migration breaks that property deliberately, because the dispatch rail
+-- has no non-RPC surface: claim is an atomic `UPDATE ... FOR UPDATE SKIP LOCKED` that
+-- hands back a claim token and evaluates a per-aggregate ordering barrier inside the same
+-- statement. Expressing it through the gateway's query builder would mean reimplementing
+-- pessimistic locking in the application, i.e. a second and divergent rail. Four functions
+-- is the whole crossing: no privilege model, no `private` schema, no queue statistics, no
+-- pruning, no preview-matrix claim scope, and above all no enqueue -- rows are written by
+-- capabilities that own their own business logic, and none of them is authored here.
+--
+-- AUTHORED, NOT COPIED. The protocol below was written for this migration against the
+-- observable contract the platform outbox store port issues (five named RPC arguments sets,
+-- a boolean/text/integer/SETOF return shape). It is not a cut of any historical migration:
+-- the provider-specific idempotency window and the hardcoded product event-type vocabulary
+-- that the managed implementation calls into are absent, the preview-matrix claim scope is
+-- absent, row-level security and role grants are absent because this kernel creates no
+-- roles to grant to, `SECURITY DEFINER` is absent for the same reason, every constraint is
+-- named rather than left to a generated identifier, and `CREATE` is unconditional because a
+-- manifest-ordered forward runs exactly once against a known prefix -- `IF NOT EXISTS` there
+-- would hide the drift the migration ledger exists to catch. `SET search_path` is kept: it
+-- is a real injection-hardening property that does not depend on a role model.
+
+CREATE TABLE public.outbox_events (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  available_at timestamptz NOT NULL DEFAULT now(),
+  processed_at timestamptz,
+  aggregate_type text NOT NULL,
+  aggregate_id uuid NOT NULL,
+  event_type text NOT NULL,
+  idempotency_key text NOT NULL,
+  status text NOT NULL DEFAULT 'pending',
+  attempts integer NOT NULL DEFAULT 0,
+  payload jsonb NOT NULL,
+  error text,
+  metadata jsonb NOT NULL DEFAULT '{}'::jsonb,
+  CONSTRAINT outbox_events_aggregate_type_nonempty_check CHECK (btrim(aggregate_type) <> ''),
+  CONSTRAINT outbox_events_event_type_nonempty_check CHECK (btrim(event_type) <> ''),
+  CONSTRAINT outbox_events_idempotency_key_nonempty_check CHECK (btrim(idempotency_key) <> ''),
+  CONSTRAINT outbox_events_attempts_check CHECK (attempts >= 0),
+  CONSTRAINT outbox_events_status_check
+    CHECK (status IN ('pending', 'processing', 'processed', 'failed', 'discarded')),
+  CONSTRAINT outbox_events_event_type_idempotency_key_key UNIQUE (event_type, idempotency_key)
+);
+
+CREATE INDEX idx_outbox_events_status_available
+  ON public.outbox_events (status, available_at);
+
+CREATE INDEX idx_outbox_events_aggregate
+  ON public.outbox_events (aggregate_type, aggregate_id);
+
+-- The claim barrier below refuses to skip an older unprocessed row for the same aggregate,
+-- INCLUDING one whose event type the caller does not know about. Without a way to declare a
+-- type intentionally unconsumed, a single retired producer would stall its aggregate
+-- forever. This table is that declaration, and it ships empty: which types are dormant is
+-- operator data, not platform content.
+CREATE TABLE public.outbox_dormant_event_types (
+  event_type text PRIMARY KEY,
+  owner text NOT NULL,
+  reason text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT outbox_dormant_event_types_event_type_nonempty_check CHECK (btrim(event_type) <> ''),
+  CONSTRAINT outbox_dormant_event_types_owner_nonempty_check CHECK (btrim(owner) <> ''),
+  CONSTRAINT outbox_dormant_event_types_reason_nonempty_check CHECK (btrim(reason) <> '')
+);
+
+-- Claim a batch for one allowlist of event types.
+--
+-- Three properties make this more than a SELECT, and each is load-bearing:
+--   1. an empty allowlist is refused, never widened -- a caller that forgot its filter must
+--      not drain every event type on the instance;
+--   2. rows whose attempts already reached the ceiling are discarded before the scan, so an
+--      exhausted row cannot be re-selected on every tick;
+--   3. per aggregate, an older unprocessed row blocks the newer one. A prior of an event
+--      type the caller neither claims nor knows also blocks, unless it has been declared
+--      dormant -- ordering within an aggregate is the guarantee producers rely on.
+-- The claim token written into metadata is the authorization for every later acknowledgement:
+-- knowing the row id is not enough, which is what makes a stale ack detectable rather than
+-- destructive.
+CREATE FUNCTION public.outbox_claim_batch(
+  p_event_types text[],
+  p_known_event_types text[] DEFAULT ARRAY[]::text[],
+  p_batch_size integer DEFAULT 25,
+  p_visibility_seconds integer DEFAULT 300,
+  p_max_attempts integer DEFAULT 8
+)
+RETURNS SETOF public.outbox_events
+LANGUAGE plpgsql
+SET search_path = public, pg_catalog
+AS $$
+DECLARE
+  v_batch integer := LEAST(GREATEST(COALESCE(p_batch_size, 25), 1), 100);
+  v_visibility integer := LEAST(GREATEST(COALESCE(p_visibility_seconds, 300), 300), 3600);
+  v_max integer := LEAST(GREATEST(COALESCE(p_max_attempts, 8), 1), 20);
+  v_known text[];
+BEGIN
+  IF p_event_types IS NULL OR cardinality(p_event_types) = 0 THEN
+    RAISE EXCEPTION 'outbox_claim_allowlist_required' USING ERRCODE = '22023';
+  END IF;
+
+  -- Everything the caller can recognise: what it claims now, plus what it declares it knows
+  -- about. A prior outside this set is treated as foreign, and only the dormant table can
+  -- release it.
+  SELECT array_agg(DISTINCT event_type)
+    INTO v_known
+    FROM unnest(COALESCE(p_known_event_types, ARRAY[]::text[]) || p_event_types) AS known(event_type)
+   WHERE event_type IS NOT NULL AND btrim(event_type) <> '';
+
+  WITH exhausted AS (
+    SELECT event.id
+      FROM public.outbox_events event
+     WHERE event.event_type = ANY (p_event_types)
+       AND event.status IN ('pending', 'failed', 'processing')
+       AND event.available_at <= now()
+       AND event.attempts >= v_max
+     ORDER BY event.created_at, event.id
+     LIMIT 100
+     FOR UPDATE SKIP LOCKED
+  )
+  UPDATE public.outbox_events event
+     SET status = 'discarded',
+         error = left(COALESCE(event.error, '') || ' | max_attempts_exhausted_at_claim', 2000),
+         metadata = event.metadata || jsonb_build_object(
+           'discardReason', 'max_attempts',
+           'discardedAt', now(),
+           'finalAttempts', event.attempts)
+    FROM exhausted
+   WHERE event.id = exhausted.id;
+
+  RETURN QUERY
+  WITH candidates AS (
+    SELECT event.id
+      FROM public.outbox_events event
+     WHERE event.event_type = ANY (p_event_types)
+       AND event.available_at <= now()
+       AND event.status IN ('pending', 'failed', 'processing')
+       AND event.attempts < v_max
+       AND NOT EXISTS (
+             SELECT 1
+               FROM public.outbox_events prior
+              WHERE prior.aggregate_type = event.aggregate_type
+                AND prior.aggregate_id = event.aggregate_id
+                AND prior.status IN ('pending', 'failed', 'processing')
+                AND (prior.created_at, prior.id) < (event.created_at, event.id)
+                AND (
+                  prior.event_type = ANY (p_event_types)
+                  OR (
+                    prior.event_type <> ALL (COALESCE(v_known, ARRAY[]::text[]))
+                    AND NOT EXISTS (
+                          SELECT 1
+                            FROM public.outbox_dormant_event_types dormant
+                           WHERE dormant.event_type = prior.event_type
+                        )
+                  )
+                ))
+     ORDER BY event.created_at, event.id
+     LIMIT v_batch
+     FOR UPDATE SKIP LOCKED
+  )
+  UPDATE public.outbox_events event
+     SET status = 'processing',
+         attempts = event.attempts + 1,
+         available_at = now() + make_interval(secs => v_visibility),
+         metadata = event.metadata || jsonb_build_object(
+           'lastClaimedAt', now(),
+           'claimToken', gen_random_uuid()::text)
+    FROM candidates
+   WHERE event.id = candidates.id
+  RETURNING event.*;
+END;
+$$;
+
+-- Acknowledge success. Returns false rather than raising when the row is no longer the
+-- caller's: a lease that expired and was re-claimed elsewhere is an ordinary race, and the
+-- caller logs it instead of aborting a batch.
+CREATE FUNCTION public.outbox_mark_processed(
+  p_event_id uuid,
+  p_claim_token text,
+  p_metadata jsonb DEFAULT '{}'::jsonb
+)
+RETURNS boolean
+LANGUAGE sql
+SET search_path = public, pg_catalog
+AS $$
+  WITH updated AS (
+    UPDATE public.outbox_events
+       SET status = 'processed',
+           processed_at = now(),
+           error = NULL,
+           metadata = metadata || COALESCE(p_metadata, '{}'::jsonb)
+     WHERE id = p_event_id
+       AND status = 'processing'
+       AND metadata->>'claimToken' = p_claim_token
+     RETURNING id
+  )
+  SELECT EXISTS (SELECT 1 FROM updated);
+$$;
+
+-- Acknowledge failure. The outcome the handler asks for is a request, not a verdict: a
+-- 'retry' on a row that has already spent its attempts becomes a discard, so the ceiling is
+-- enforced in one place instead of in every caller.
+--
+-- 'snooze' means the downstream is unavailable rather than the row being bad, so the attempt
+-- taken at claim is refunded -- an outage must not consume the DLQ budget of the events it
+-- happened to touch. Retry delay is exponential with equal jitter in [d/2, d]: without the
+-- jitter every row that failed in the same tick returns in the same later tick, and the
+-- convoy reforms on each retry instead of dispersing.
+CREATE FUNCTION public.outbox_mark_failed(
+  p_event_id uuid,
+  p_claim_token text,
+  p_error text,
+  p_outcome text DEFAULT 'retry',
+  p_base_delay_seconds integer DEFAULT 60,
+  p_max_delay_seconds integer DEFAULT 3600,
+  p_max_attempts integer DEFAULT 8,
+  p_snooze_seconds integer DEFAULT 300
+)
+RETURNS text
+LANGUAGE plpgsql
+SET search_path = public, pg_catalog
+AS $$
+DECLARE
+  v_row public.outbox_events%ROWTYPE;
+  v_base integer := LEAST(GREATEST(COALESCE(p_base_delay_seconds, 60), 5), 3600);
+  v_cap integer;
+  v_max integer := LEAST(GREATEST(COALESCE(p_max_attempts, 8), 1), 20);
+  v_snooze integer := LEAST(GREATEST(COALESCE(p_snooze_seconds, 300), 60), 3600);
+  v_delay double precision;
+BEGIN
+  IF p_outcome IS NULL OR p_outcome NOT IN ('retry', 'discard', 'snooze') THEN
+    RAISE EXCEPTION 'outbox_mark_failed_invalid_outcome' USING ERRCODE = '22023';
+  END IF;
+
+  v_cap := LEAST(GREATEST(v_base, COALESCE(p_max_delay_seconds, 3600)), 86400);
+
+  SELECT *
+    INTO v_row
+    FROM public.outbox_events
+   WHERE id = p_event_id
+     AND status = 'processing'
+     AND metadata->>'claimToken' = p_claim_token
+   FOR UPDATE;
+
+  IF NOT FOUND THEN
+    RETURN 'missed';
+  END IF;
+
+  IF p_outcome = 'discard' OR (p_outcome = 'retry' AND v_row.attempts >= v_max) THEN
+    UPDATE public.outbox_events
+       SET status = 'discarded',
+           error = left(p_error, 2000),
+           metadata = metadata || jsonb_build_object(
+             'discardReason',
+             CASE WHEN p_outcome = 'discard' THEN 'permanent_error' ELSE 'max_attempts' END,
+             'discardedAt', now(),
+             'finalAttempts', v_row.attempts)
+     WHERE id = v_row.id;
+    RETURN 'discarded';
+  END IF;
+
+  IF p_outcome = 'snooze' THEN
+    UPDATE public.outbox_events
+       SET status = 'failed',
+           attempts = GREATEST(v_row.attempts - 1, 0),
+           available_at = now() + make_interval(secs => v_snooze),
+           error = left(p_error, 2000),
+           metadata = metadata || jsonb_build_object(
+             'snoozeCount', COALESCE((metadata->>'snoozeCount')::integer, 0) + 1,
+             'lastSnoozedAt', now())
+     WHERE id = v_row.id;
+    RETURN 'snoozed';
+  END IF;
+
+  v_delay := LEAST(
+               v_cap::double precision,
+               v_base::double precision * power(2, LEAST(GREATEST(v_row.attempts - 1, 0), 16))
+             ) * (0.5 + random() * 0.5);
+
+  UPDATE public.outbox_events
+     SET status = 'failed',
+         available_at = now() + make_interval(secs => v_delay),
+         error = left(p_error, 2000)
+   WHERE id = v_row.id;
+  RETURN 'failed';
+END;
+$$;
+
+-- Hand back rows the caller claimed but never ran -- a drain loop that aborts mid-batch, or
+-- one handler reporting the downstream is out. The attempt taken at claim is refunded for
+-- exactly the same reason as in 'snooze': nothing was tried, so nothing was spent. Ids and
+-- tokens are supplied as parallel arrays and must agree in length, because a mismatch means
+-- the caller lost track of which token belongs to which row and releasing the wrong pairing
+-- would silently release nothing.
+CREATE FUNCTION public.outbox_release_unprocessed(
+  p_event_ids uuid[],
+  p_claim_tokens text[],
+  p_delay_seconds integer DEFAULT 0
+)
+RETURNS integer
+LANGUAGE plpgsql
+SET search_path = public, pg_catalog
+AS $$
+DECLARE
+  v_delay integer := LEAST(GREATEST(COALESCE(p_delay_seconds, 0), 0), 3600);
+  v_count integer;
+BEGIN
+  IF p_event_ids IS NULL OR p_claim_tokens IS NULL
+     OR cardinality(p_event_ids) <> cardinality(p_claim_tokens) THEN
+    RAISE EXCEPTION 'outbox_release_invalid_input' USING ERRCODE = '22023';
+  END IF;
+
+  UPDATE public.outbox_events event
+     SET status = 'pending',
+         available_at = now() + make_interval(secs => v_delay),
+         attempts = GREATEST(event.attempts - 1, 0)
+    FROM unnest(p_event_ids, p_claim_tokens) AS released(id, token)
+   WHERE event.id = released.id
+     AND event.status = 'processing'
+     AND event.metadata->>'claimToken' = released.token;
+
+  GET DIAGNOSTICS v_count = ROW_COUNT;
+  RETURN v_count;
+END;
+$$;

package/sql/manifest.json

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": 1,
+  "version": "outbox-1",
+  "migrations": [
+    {
+      "file": "0001_outbox.sql",
+      "source": "db/platform/migrations/20260807190000_comms_outbox_rail.sql",
+      "sha256": "dfb3e9808714846738222bb74a1bfdb38ceafdde2ca8a0c71ab835739fb333bd"
+    }
+  ]
+}

package/src/config.ts

@@ -0,0 +1,79 @@
+import type { OutboxDispatchConfig } from "./contracts.js";
+const CONFIG_BOUNDS = {
+  batchSize: { env: "COMMERCE_OUTBOX_DISPATCH_BATCH_SIZE", def: 25, min: 1, max: 100 },
+  maxAttempts: { env: "COMMERCE_OUTBOX_DISPATCH_MAX_ATTEMPTS", def: 8, min: 1, max: 20 },
+  visibilitySeconds: {
+    env: "COMMERCE_OUTBOX_DISPATCH_VISIBILITY_SECONDS",
+    def: 300,
+    min: 300,
+    max: 3600,
+  },
+  backoffBaseSeconds: { env: "COMMERCE_OUTBOX_DISPATCH_BACKOFF_BASE_SECONDS", def: 60, min: 5, max: 3600 },
+  backoffCapSeconds: { env: "COMMERCE_OUTBOX_DISPATCH_BACKOFF_CAP_SECONDS", def: 3600, min: 5, max: 86_400 },
+  snoozeSeconds: { env: "COMMERCE_OUTBOX_DISPATCH_SNOOZE_SECONDS", def: 300, min: 60, max: 3600 },
+  maxSnoozes: { env: "COMMERCE_OUTBOX_DISPATCH_MAX_SNOOZES", def: 48, min: 1, max: 1000 },
+  // Max keeps a >= 15s tail under the cron's hard kill: drain stop + in-flight
+  // handler + marks + queue stats + finishJobRun must all fit after the budget.
+  softBudgetMs: {
+    env: "COMMERCE_OUTBOX_DISPATCH_SOFT_BUDGET_MS",
+    def: 40_000,
+    min: 5000,
+    max: 60 * 1000 - 15_000,
+  },
+} as const;
+
+function readBoundedInt(
+  env: Record<string, string | undefined>,
+  bound: { env: string; def: number; min: number; max: number },
+): number {
+  const raw = env[bound.env];
+  if (raw === undefined || raw.trim() === "") return bound.def;
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed)) {
+    console.warn(`[outbox-dispatch] invalid ${bound.env}=${raw}; using default ${bound.def}`);
+    return bound.def;
+  }
+  const clamped = Math.min(Math.max(parsed, bound.min), bound.max);
+  if (clamped !== parsed) {
+    console.warn(`[outbox-dispatch] ${bound.env}=${parsed} clamped to ${clamped}`);
+  }
+  return clamped;
+}
+
+export function readOutboxDispatchConfig(
+  env: Record<string, string | undefined>,
+  prefix = "COMMERCE_OUTBOX_DISPATCH_",
+): OutboxDispatchConfig {
+  const bounds = Object.fromEntries(Object.entries(CONFIG_BOUNDS).map(([key, bound]) => [key, { ...bound, env: prefix + bound.env.slice("COMMERCE_OUTBOX_DISPATCH_".length) }])) as typeof CONFIG_BOUNDS;
+  const config: OutboxDispatchConfig = {
+    batchSize: readBoundedInt(env, bounds.batchSize),
+    maxAttempts: readBoundedInt(env, bounds.maxAttempts),
+    visibilitySeconds: readBoundedInt(env, bounds.visibilitySeconds),
+    backoffBaseSeconds: readBoundedInt(env, bounds.backoffBaseSeconds),
+    backoffCapSeconds: readBoundedInt(env, bounds.backoffCapSeconds),
+    snoozeSeconds: readBoundedInt(env, bounds.snoozeSeconds),
+    maxSnoozes: readBoundedInt(env, bounds.maxSnoozes),
+    softBudgetMs: readBoundedInt(env, bounds.softBudgetMs),
+  };
+  if (config.backoffCapSeconds < config.backoffBaseSeconds) {
+    console.warn(
+      `[outbox-dispatch] backoff cap ${config.backoffCapSeconds}s below base ${config.backoffBaseSeconds}s; raising cap to base`,
+    );
+    config.backoffCapSeconds = config.backoffBaseSeconds;
+  }
+  return config;
+}
+
+/** @beta Scheduled configuration is stricter than the bare immediate worker. */
+export function validateScheduledConfig(config: OutboxDispatchConfig, hostLimitSeconds: number, timeouts: readonly number[]): void {
+  const fail = (key: string, fix: string): never => { throw new Error(`@openlup/outbox: ${key}: ${fix}`); };
+  if (!Number.isFinite(hostLimitSeconds) || hostLimitSeconds < 20 || hostLimitSeconds > 720) fail("hostLimitSeconds", "use 20–720 seconds");
+  for (const [key, bound] of Object.entries(CONFIG_BOUNDS)) {
+    const value = config[key as keyof OutboxDispatchConfig];
+    const min = key === "visibilitySeconds" ? Math.min(5 * hostLimitSeconds, 3600) : bound.min;
+    const max = key === "softBudgetMs" ? hostLimitSeconds * 1000 - 15000 : bound.max;
+    if (!Number.isInteger(value) || value < min || value > max) fail(key, `use an integer in ${min}–${max}`);
+  }
+  if (config.backoffCapSeconds < config.backoffBaseSeconds) fail("backoffCapSeconds", "keep cap at least the base delay");
+  for (const timeout of timeouts) if (!Number.isFinite(timeout) || timeout <= 0 || timeout + 2000 > config.softBudgetMs) fail("handler.timeoutMs", "fit the effective timeout plus 2000 ms mark margin in the budget");
+}

package/src/contracts.ts

@@ -0,0 +1,86 @@
+import type { OutboxHandler as KernelHandler, OutboxEventRow } from "@openlup/core/outbox";
+export type { OutboxEventRow, OutboxHandlerOutcome, OutboxHandlerExecutionContext, OutboxHandlerDescriptor } from "@openlup/core/outbox";
+/** @beta The worker creates the host's standard AbortController. */
+export type OutboxHandler = KernelHandler<AbortSignal>;
+export type OutboxHandlerRegistry = ReadonlyMap<string, OutboxHandler>;
+
+export type OutboxMarkFailedStatus = "failed" | "discarded" | "snoozed" | "missed";
+
+export interface OutboxStore {
+  /** Read-only preflight used to admit a terminal handler when active providers are unavailable. */
+  hasPendingEventType?(eventType: string): Promise<boolean>;
+  claimBatch(input: {
+    eventTypes: readonly string[];
+    knownEventTypes?: readonly string[];
+    batchSize: number;
+    visibilitySeconds: number;
+    maxAttempts: number;
+  }): Promise<OutboxEventRow[]>;
+  markProcessed(input: {
+    eventId: string;
+    claimToken: string;
+    metadata?: Record<string, unknown>;
+  }): Promise<{ applied: boolean }>;
+  markFailed(input: {
+    eventId: string;
+    claimToken: string;
+    error: string;
+    outcome: "retry" | "discard" | "snooze";
+    baseDelaySeconds: number;
+    maxDelaySeconds: number;
+    maxAttempts: number;
+    snoozeSeconds: number;
+  }): Promise<{ status: OutboxMarkFailedStatus }>;
+  releaseUnprocessed(
+    items: ReadonlyArray<{ eventId: string; claimToken: string }>,
+    delaySeconds: number,
+  ): Promise<number>;
+}
+
+/** Managed-only best-effort queue observation, separate from core claim/ack policy. */
+export interface OutboxQueueDiagnostics {
+  queueStats(): Promise<Record<string, unknown>>;
+}
+
+export interface Clock {
+  now(): number;
+}
+
+export interface OutboxDispatchRunResult {
+  ok: boolean;
+  checked: number;
+  updated: number;
+  failures: number;
+  skipped: boolean;
+  reason?: string;
+  claimed: number;
+  processed: number;
+  retried: number;
+  snoozed: number;
+  discarded: number;
+  released: number;
+  duplicateInRun: number;
+  leaseLost: number;
+  batches: number;
+  runMs: number;
+  byEventType: Record<string, Record<string, number>>;
+  discardedEventIds: string[];
+  queue?: Record<string, unknown>;
+}
+
+export interface OutboxDispatchConfig {
+  batchSize: number;
+  maxAttempts: number;
+  visibilitySeconds: number;
+  backoffBaseSeconds: number;
+  backoffCapSeconds: number;
+  snoozeSeconds: number;
+  maxSnoozes: number;
+  softBudgetMs: number;
+}
+
+
+/** @beta Logging defaults retain the dispatch console transcript. */
+export interface OutboxLogger { warn(...args: unknown[]): void; error(...args: unknown[]): void }
+/** @beta Synchronous bounded observations; no payloads or credentials. */
+export interface OutboxObservation { event: "claimed" | "finished"; count: number }

package/src/enqueue.ts

@@ -0,0 +1,15 @@
+/** @beta Caller executes this inside the same transaction as its domain write. */
+export interface EnqueueEvent {
+  aggregateType: string; aggregateId: string; eventType: string; idempotencyKey: string;
+  payload: Record<string, unknown>; metadata?: Record<string, unknown>;
+  availableAt?: string;
+}
+/** @beta Duplicate enqueue keeps the durable event identity; no independent commit. */
+export function buildOutboxEnqueue(event: EnqueueEvent): { text: string; values: readonly unknown[] } {
+  return {
+    text: `insert into public.outbox_events (aggregate_type, aggregate_id, event_type, idempotency_key, payload, metadata, available_at)
+values ($1, $2::uuid, $3, $4, $5::jsonb, $6::jsonb, coalesce($7::timestamptz, now()))
+on conflict (event_type, idempotency_key) do nothing returning id::text`,
+    values: [event.aggregateType, event.aggregateId, event.eventType, event.idempotencyKey, JSON.stringify(event.payload), JSON.stringify(event.metadata ?? {}), event.availableAt ?? null],
+  };
+}