@krizaka/outbox 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,310 @@
+import {
+  OUTBOX_BOUNDS,
+  OUTBOX_DEFAULTS,
+  backoffSeconds,
+  checkMessage,
+  checkSettings
+} from "./chunk-AD76AB44.js";
+import {
+  FAIL_STATE,
+  OUTBOX_CODE,
+  OutboxError
+} from "./chunk-7WIJNAGK.js";
+
+// src/consumer.ts
+import { ident } from "@krizaka/db";
+async function consumeOnce(tx, consumer, messageId, now, effect, schema = "outbox") {
+  const rows = await tx(`INSERT INTO ${ident(schema)}.processed (consumer, message_id, processed_at) VALUES ($1, $2, $3) ON CONFLICT DO NOTHING RETURNING 1`, [consumer, messageId, now]);
+  if (rows.length === 0) return "duplicate";
+  await effect();
+  return "applied";
+}
+
+// src/memory.ts
+import { addSeconds, isAfter, isBefore } from "@krizaka/time";
+function memoryOutboxStore() {
+  const rows = /* @__PURE__ */ new Map();
+  const open = (r) => r.deliveredAt === null && r.deadAt === null;
+  const leaseValid = (r, now) => r.leasedUntil !== null && isAfter(r.leasedUntil, now);
+  return {
+    async append(m) {
+      if (rows.has(m.id)) return false;
+      rows.set(m.id, { id: m.id, topic: m.topic, type: m.type, payload: structuredClone(m.payload), createdAt: m.createdAt, availableAt: m.availableAt, attempts: 0, leasedUntil: null, leaseOwner: null, deliveredAt: null, deadAt: null, lastError: null });
+      return true;
+    },
+    async claim({ topic, owner, limit, leaseSeconds, maxAttempts, now }) {
+      for (const r of rows.values()) {
+        if (open(r) && r.attempts >= maxAttempts && r.leasedUntil !== null && !leaseValid(r, now)) {
+          r.deadAt = now;
+          r.leasedUntil = null;
+          r.leaseOwner = null;
+          r.lastError ??= "the last attempt's lease expired with no answer";
+        }
+      }
+      const due = [...rows.values()].filter((r) => open(r) && r.attempts < maxAttempts && !isAfter(r.availableAt, now) && !leaseValid(r, now) && (topic === void 0 || r.topic === topic)).sort((a, b) => a.availableAt.valueOf() - b.availableAt.valueOf() || a.createdAt.valueOf() - b.createdAt.valueOf()).slice(0, limit);
+      return due.map((r) => {
+        r.attempts += 1;
+        r.leasedUntil = addSeconds(now, leaseSeconds);
+        r.leaseOwner = owner;
+        return { id: r.id, topic: r.topic, type: r.type, payload: structuredClone(r.payload), occurredAt: r.createdAt, attempts: r.attempts };
+      });
+    },
+    async complete(id, owner, now) {
+      const r = rows.get(id);
+      if (!r || !open(r) || r.leaseOwner !== owner) return false;
+      r.deliveredAt = now;
+      r.leasedUntil = null;
+      r.leaseOwner = null;
+      return true;
+    },
+    async fail(id, owner, error, { now, maxAttempts, backoffSeconds: base, backoffMaxSeconds }) {
+      const r = rows.get(id);
+      if (!r || !open(r) || r.leaseOwner !== owner) return { state: FAIL_STATE.lost };
+      r.lastError = error;
+      r.leasedUntil = null;
+      r.leaseOwner = null;
+      if (r.attempts >= maxAttempts) {
+        r.deadAt = now;
+        return { state: FAIL_STATE.dead };
+      }
+      r.availableAt = addSeconds(now, backoffSeconds(r.attempts, { backoffSeconds: base, backoffMaxSeconds }));
+      return { state: FAIL_STATE.retry, availableAt: r.availableAt };
+    },
+    async retryDead(id, now) {
+      const r = rows.get(id);
+      if (!r || r.deadAt === null) return false;
+      r.deadAt = null;
+      r.attempts = 0;
+      r.availableAt = now;
+      return true;
+    },
+    async purgeBefore(before) {
+      let removed = 0;
+      for (const [id, r] of rows) {
+        const finished = r.deliveredAt ?? r.deadAt;
+        if (finished !== null && isBefore(finished, before)) {
+          rows.delete(id);
+          removed += 1;
+        }
+      }
+      return removed;
+    },
+    async stats(now) {
+      const all = [...rows.values()];
+      return {
+        pending: all.filter((r) => open(r) && !leaseValid(r, now)).length,
+        leased: all.filter((r) => open(r) && leaseValid(r, now)).length,
+        delivered: all.filter((r) => r.deliveredAt !== null).length,
+        dead: all.filter((r) => r.deadAt !== null).length
+      };
+    },
+    rows: () => [...rows.values()]
+  };
+}
+
+// src/outbox.ts
+import { randomUUID } from "crypto";
+import { ident as ident3 } from "@krizaka/db";
+import { subHours } from "@krizaka/time";
+
+// src/persistence.ts
+import { ident as ident2 } from "@krizaka/db";
+import { addSeconds as addSeconds2 } from "@krizaka/time";
+function dbOutboxStore(query, schema = "outbox") {
+  const message = `${ident2(schema)}.message`;
+  return {
+    async append(m) {
+      const rows = await query(
+        `INSERT INTO ${message} (id, topic, event_type, payload, created_at, available_at) VALUES ($1, $2, $3, $4::jsonb, $5, $6) ON CONFLICT (id) DO NOTHING RETURNING 1`,
+        [m.id, m.topic, m.type, JSON.stringify(m.payload), m.createdAt, m.availableAt]
+      );
+      return rows.length > 0;
+    },
+    async claim({ topic, owner, limit, leaseSeconds, maxAttempts, now }) {
+      await query(
+        `UPDATE ${message} SET dead_at = $1, leased_until = NULL, lease_owner = NULL, last_error = COALESCE(last_error, 'the last attempt''s lease expired with no answer')
+          WHERE delivered_at IS NULL AND dead_at IS NULL AND attempts >= $2 AND leased_until IS NOT NULL AND leased_until <= $1`,
+        [now, maxAttempts]
+      );
+      const rows = await query(
+        `UPDATE ${message} AS m SET leased_until = $1, lease_owner = $2, attempts = m.attempts + 1
+          WHERE m.id IN (
+            SELECT id FROM ${message}
+             WHERE delivered_at IS NULL AND dead_at IS NULL AND available_at <= $3 AND attempts < $4
+               AND (leased_until IS NULL OR leased_until <= $3) AND ($5::text IS NULL OR topic = $5)
+             ORDER BY available_at, created_at LIMIT $6
+               FOR UPDATE SKIP LOCKED)
+        RETURNING m.id, m.topic, m.event_type, m.payload, m.created_at, m.attempts`,
+        [addSeconds2(now, leaseSeconds), owner, now, maxAttempts, topic ?? null, limit]
+      );
+      return rows.map((r) => ({ id: r.id, topic: r.topic, type: r.event_type, payload: r.payload, occurredAt: new Date(r.created_at), attempts: Number(r.attempts) })).sort((a, b) => a.occurredAt.valueOf() - b.occurredAt.valueOf());
+    },
+    async complete(id, owner, now) {
+      const rows = await query(
+        `UPDATE ${message} SET delivered_at = $3, leased_until = NULL, lease_owner = NULL
+          WHERE id = $1 AND lease_owner = $2 AND delivered_at IS NULL AND dead_at IS NULL RETURNING 1`,
+        [id, owner, now]
+      );
+      return rows.length > 0;
+    },
+    async fail(id, owner, error, { now, maxAttempts, backoffSeconds: backoffSeconds2, backoffMaxSeconds }) {
+      const [row] = await query(
+        `UPDATE ${message} SET last_error = $3::text, leased_until = NULL, lease_owner = NULL,
+                dead_at      = CASE WHEN attempts >= $5 THEN $4::timestamptz ELSE NULL END,
+                available_at = CASE WHEN attempts >= $5 THEN available_at
+                                    ELSE $4::timestamptz + make_interval(secs => LEAST($7::double precision, $6::double precision * power(2, attempts - 1))) END
+          WHERE id = $1 AND lease_owner = $2 AND delivered_at IS NULL AND dead_at IS NULL
+        RETURNING attempts, dead_at, available_at`,
+        [id, owner, error, now, maxAttempts, backoffSeconds2, backoffMaxSeconds]
+      );
+      if (!row) return { state: FAIL_STATE.lost };
+      return row.dead_at ? { state: FAIL_STATE.dead } : { state: FAIL_STATE.retry, availableAt: new Date(row.available_at) };
+    },
+    async retryDead(id, now) {
+      const rows = await query(`UPDATE ${message} SET dead_at = NULL, attempts = 0, available_at = $2 WHERE id = $1 AND dead_at IS NOT NULL RETURNING 1`, [id, now]);
+      return rows.length > 0;
+    },
+    async purgeBefore(before) {
+      const rows = await query(`DELETE FROM ${message} WHERE COALESCE(delivered_at, dead_at) < $1 RETURNING 1`, [before]);
+      return rows.length;
+    },
+    async stats(now) {
+      const [row] = await query(
+        `SELECT count(*) FILTER (WHERE delivered_at IS NULL AND dead_at IS NULL AND (leased_until IS NULL OR leased_until <= $1))::int AS pending,
+                count(*) FILTER (WHERE delivered_at IS NULL AND dead_at IS NULL AND leased_until > $1)::int AS leased,
+                count(*) FILTER (WHERE delivered_at IS NOT NULL)::int AS delivered,
+                count(*) FILTER (WHERE dead_at IS NOT NULL)::int AS dead
+           FROM ${message}`,
+        [now]
+      );
+      return { pending: row?.pending ?? 0, leased: row?.leased ?? 0, delivered: row?.delivered ?? 0, dead: row?.dead ?? 0 };
+    }
+  };
+}
+
+// src/outbox.ts
+var MAX_ERROR = 1e3;
+var describe = (error) => (error instanceof Error ? `${error.name}: ${error.message}` : String(error)).slice(0, MAX_ERROR);
+function createOutbox(deps) {
+  const schema = ident3(deps.schema ?? "outbox");
+  const storeFor = deps.storeFor ?? ((query) => dbOutboxStore(query, schema));
+  const settings = async () => checkSettings(typeof deps.settings === "function" ? await deps.settings() : deps.settings);
+  return {
+    async append(tx, message) {
+      checkMessage(message);
+      const now = deps.clock.now();
+      const id = message.id ?? randomUUID();
+      const appended = await storeFor(tx).append({ id, topic: message.topic, type: message.type, payload: message.payload, createdAt: now, availableAt: message.availableAt ?? now });
+      return { id, appended };
+    },
+    async claim(query, options) {
+      const s = await settings();
+      return storeFor(query).claim({ ...options, limit: options.limit ?? s.batchSize, leaseSeconds: options.leaseSeconds ?? s.leaseSeconds, maxAttempts: s.maxAttempts, now: deps.clock.now() });
+    },
+    complete: (query, id, owner) => storeFor(query).complete(id, owner, deps.clock.now()),
+    async fail(query, id, owner, error) {
+      const s = await settings();
+      return storeFor(query).fail(id, owner, describe(error), { now: deps.clock.now(), maxAttempts: s.maxAttempts, backoffSeconds: s.backoffSeconds, backoffMaxSeconds: s.backoffMaxSeconds });
+    },
+    retryDead: (query, id) => storeFor(query).retryDead(id, deps.clock.now()),
+    async purge(query) {
+      const s = await settings();
+      return storeFor(query).purgeBefore(subHours(deps.clock.now(), s.retentionDays * 24));
+    },
+    stats: (query) => storeFor(query).stats(deps.clock.now())
+  };
+}
+
+// src/schema.ts
+import { defineModule } from "@krizaka/db";
+var outboxSchema = defineModule({
+  module: "outbox",
+  migrations: [
+    {
+      version: 1,
+      name: "messages and processed",
+      sql: (c) => `
+CREATE TABLE ${c.schema}.message (
+  id           uuid PRIMARY KEY,
+  topic        text NOT NULL CHECK (topic ~ '^[a-z][a-z0-9_.:-]{0,59}$'),
+  event_type   text NOT NULL CHECK (event_type ~ '^[a-z][a-z0-9_.-]{0,99}$'),
+  payload      jsonb NOT NULL,
+  created_at   timestamptz NOT NULL,
+  available_at timestamptz NOT NULL,
+  attempts     integer NOT NULL DEFAULT 0 CHECK (attempts >= 0),
+  leased_until timestamptz,
+  lease_owner  text,
+  delivered_at timestamptz,
+  dead_at      timestamptz,
+  last_error   text,
+  CHECK (delivered_at IS NULL OR dead_at IS NULL)
+);
+CREATE INDEX message_due ON ${c.schema}.message (topic, available_at) WHERE delivered_at IS NULL AND dead_at IS NULL;
+CREATE INDEX message_finished ON ${c.schema}.message (COALESCE(delivered_at, dead_at)) WHERE delivered_at IS NOT NULL OR dead_at IS NOT NULL;
+CREATE TABLE ${c.schema}.processed (
+  consumer     text NOT NULL CHECK (char_length(consumer) BETWEEN 1 AND 100),
+  message_id   uuid NOT NULL,
+  processed_at timestamptz NOT NULL,
+  PRIMARY KEY (consumer, message_id)
+);`
+    }
+  ]
+});
+
+// src/worker.ts
+async function drainOnce(options) {
+  const { outbox, query, owner, deliver, topic } = options;
+  const summary = { claimed: 0, delivered: 0, retried: 0, dead: 0, lost: 0 };
+  const batch = await outbox.claim(query, { owner, ...topic === void 0 ? {} : { topic } });
+  summary.claimed = batch.length;
+  for (const message of batch) {
+    let failure = null;
+    try {
+      await deliver(message);
+    } catch (error) {
+      failure = { error };
+    }
+    if (failure === null) {
+      if (await outbox.complete(query, message.id, owner)) summary.delivered += 1;
+      else summary.lost += 1;
+      continue;
+    }
+    const outcome = await outbox.fail(query, message.id, owner, failure.error);
+    if (outcome.state === FAIL_STATE.retry) summary.retried += 1;
+    else if (outcome.state === FAIL_STATE.dead) summary.dead += 1;
+    else summary.lost += 1;
+  }
+  return summary;
+}
+var IDLE_SECONDS = 5;
+async function runWorker(options) {
+  const idle = options.idleSeconds ?? IDLE_SECONDS;
+  while (!options.signal?.aborted) {
+    let waited;
+    try {
+      waited = (await drainOnce(options)).claimed === 0;
+    } catch (error) {
+      options.onError?.(error);
+      waited = true;
+    }
+    if (waited && !options.signal?.aborted) await options.sleep(idle);
+  }
+}
+export {
+  FAIL_STATE,
+  OUTBOX_BOUNDS,
+  OUTBOX_CODE,
+  OUTBOX_DEFAULTS,
+  OutboxError,
+  backoffSeconds,
+  checkMessage,
+  checkSettings,
+  consumeOnce,
+  createOutbox,
+  dbOutboxStore,
+  drainOnce,
+  memoryOutboxStore,
+  outboxSchema,
+  runWorker
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/consumer.ts","../src/memory.ts","../src/outbox.ts","../src/persistence.ts","../src/schema.ts","../src/worker.ts"],"sourcesContent":["import { ident, type Query } from \"@krizaka/db\";\n\n/**\n * The idempotent consumer: the outbox delivers AT LEAST ONCE, so a consumer that has an effect in the database applies it once per\n * message id. Run it inside the transaction of the effect: the marker and the effect commit together, so a crash between them\n * leaves neither and the redelivery applies both; a redelivery after the commit finds the marker and does nothing.\n *\n * ```ts\n * await db.transaction(async (tx) => {\n *   const result = await consumeOnce(tx, \"credits\", message.id, clock.now(), () => credits.grant(tx, …));\n * });\n * ```\n * @param tx the transaction the effect writes through\n * @param consumer who applies it (`credits`, `mail`): a message may be consumed once by each consumer\n * @param messageId the outbox message's id\n * @param effect what to do the first time; its failure rolls the marker back with the transaction\n * @param schema the Postgres schema of the module, default `outbox`\n * @returns `applied` the first time, `duplicate` after\n */\nexport async function consumeOnce(tx: Query, consumer: string, messageId: string, now: Date, effect: () => Promise<void>, schema = \"outbox\"): Promise<\"applied\" | \"duplicate\"> {\n  const rows = await tx(`INSERT INTO ${ident(schema)}.processed (consumer, message_id, processed_at) VALUES ($1, $2, $3) ON CONFLICT DO NOTHING RETURNING 1`, [consumer, messageId, now]);\n  if (rows.length === 0) return \"duplicate\";\n  await effect();\n  return \"applied\";\n}\n","import { addSeconds, isAfter, isBefore } from \"@krizaka/time\";\n\nimport { FAIL_STATE, type FailOutcome, type OutboxMessage, type OutboxStats, type OutboxStore } from \"./port\";\nimport { backoffSeconds } from \"./rules\";\n\ninterface Row {\n  id: string;\n  topic: string;\n  type: string;\n  payload: unknown;\n  createdAt: Date;\n  availableAt: Date;\n  attempts: number;\n  leasedUntil: Date | null;\n  leaseOwner: string | null;\n  deliveredAt: Date | null;\n  deadAt: Date | null;\n  lastError: string | null;\n}\n\n/** An in-memory outbox store, for unit tests and demos (the same behaviour as the database's: the contract kit runs on both). */\nexport function memoryOutboxStore(): OutboxStore & { rows(): readonly Readonly<Row>[] } {\n  const rows = new Map<string, Row>();\n  const open = (r: Row) => r.deliveredAt === null && r.deadAt === null;\n  const leaseValid = (r: Row, now: Date) => r.leasedUntil !== null && isAfter(r.leasedUntil, now);\n  return {\n    async append(m) {\n      if (rows.has(m.id)) return false;\n      rows.set(m.id, { id: m.id, topic: m.topic, type: m.type, payload: structuredClone(m.payload), createdAt: m.createdAt, availableAt: m.availableAt, attempts: 0, leasedUntil: null, leaseOwner: null, deliveredAt: null, deadAt: null, lastError: null });\n      return true;\n    },\n    async claim({ topic, owner, limit, leaseSeconds, maxAttempts, now }) {\n      for (const r of rows.values()) {\n        if (open(r) && r.attempts >= maxAttempts && r.leasedUntil !== null && !leaseValid(r, now)) {\n          r.deadAt = now;\n          r.leasedUntil = null;\n          r.leaseOwner = null;\n          r.lastError ??= \"the last attempt's lease expired with no answer\";\n        }\n      }\n      const due = [...rows.values()]\n        .filter((r) => open(r) && r.attempts < maxAttempts && !isAfter(r.availableAt, now) && !leaseValid(r, now) && (topic === undefined || r.topic === topic))\n        .sort((a, b) => a.availableAt.valueOf() - b.availableAt.valueOf() || a.createdAt.valueOf() - b.createdAt.valueOf())\n        .slice(0, limit);\n      return due.map((r): OutboxMessage => {\n        r.attempts += 1;\n        r.leasedUntil = addSeconds(now, leaseSeconds);\n        r.leaseOwner = owner;\n        return { id: r.id, topic: r.topic, type: r.type, payload: structuredClone(r.payload), occurredAt: r.createdAt, attempts: r.attempts };\n      });\n    },\n    async complete(id, owner, now) {\n      const r = rows.get(id);\n      if (!r || !open(r) || r.leaseOwner !== owner) return false;\n      r.deliveredAt = now;\n      r.leasedUntil = null;\n      r.leaseOwner = null;\n      return true;\n    },\n    async fail(id, owner, error, { now, maxAttempts, backoffSeconds: base, backoffMaxSeconds }): Promise<FailOutcome> {\n      const r = rows.get(id);\n      if (!r || !open(r) || r.leaseOwner !== owner) return { state: FAIL_STATE.lost };\n      r.lastError = error;\n      r.leasedUntil = null;\n      r.leaseOwner = null;\n      if (r.attempts >= maxAttempts) {\n        r.deadAt = now;\n        return { state: FAIL_STATE.dead };\n      }\n      r.availableAt = addSeconds(now, backoffSeconds(r.attempts, { backoffSeconds: base, backoffMaxSeconds }));\n      return { state: FAIL_STATE.retry, availableAt: r.availableAt };\n    },\n    async retryDead(id, now) {\n      const r = rows.get(id);\n      if (!r || r.deadAt === null) return false;\n      r.deadAt = null;\n      r.attempts = 0;\n      r.availableAt = now;\n      return true;\n    },\n    async purgeBefore(before) {\n      let removed = 0;\n      for (const [id, r] of rows) {\n        const finished = r.deliveredAt ?? r.deadAt;\n        if (finished !== null && isBefore(finished, before)) {\n          rows.delete(id);\n          removed += 1;\n        }\n      }\n      return removed;\n    },\n    async stats(now): Promise<OutboxStats> {\n      const all = [...rows.values()];\n      return {\n        pending: all.filter((r) => open(r) && !leaseValid(r, now)).length,\n        leased: all.filter((r) => open(r) && leaseValid(r, now)).length,\n        delivered: all.filter((r) => r.deliveredAt !== null).length,\n        dead: all.filter((r) => r.deadAt !== null).length,\n      };\n    },\n    rows: () => [...rows.values()],\n  };\n}\n","import { randomUUID } from \"node:crypto\";\n\nimport { ident } from \"@krizaka/db\";\nimport { subHours } from \"@krizaka/time\";\n\nimport { dbOutboxStore } from \"./persistence\";\nimport { type ClaimOptions, type Clock, type FailOutcome, type NewMessage, type OutboxMessage, type OutboxSettings, type OutboxStats, type OutboxStore, type Query } from \"./port\";\nimport { checkMessage, checkSettings } from \"./rules\";\n\nexport interface OutboxDeps {\n  clock: Clock;\n  /** The settings, read at each call so the admin's change applies at once: an object, or a function over the settings service. */\n  settings: OutboxSettings | (() => OutboxSettings | Promise<OutboxSettings>);\n  /** The store over a query (a pool or a transaction). Default: the PostgreSQL store on schema `outbox`. */\n  storeFor?: (query: Query) => OutboxStore;\n  /** The Postgres schema, when the product renamed the module's (used by the default store). */\n  schema?: string;\n}\n\n/** The outbox as a product uses it. Every function takes the `Query` it works through: pass `tx` to join a unit of work. */\nexport interface Outbox {\n  /** Appends a message INSIDE the caller's transaction: it commits or rolls back with it. Answers its id, and `false` when that id was already appended. */\n  append(tx: Query, message: NewMessage): Promise<{ id: string; appended: boolean }>;\n  /** Leases a batch of due messages to `owner`. Exclusive while each lease is valid. */\n  claim(query: Query, options: ClaimOptions & { limit?: number; leaseSeconds?: number }): Promise<OutboxMessage[]>;\n  /** The delivery succeeded. `false` when the lease was lost to another worker. */\n  complete(query: Query, id: string, owner: string): Promise<boolean>;\n  /** The delivery failed: back off (doubling, capped), or dead after `maxAttempts`. */\n  fail(query: Query, id: string, owner: string, error: unknown): Promise<FailOutcome>;\n  /** A dead message gets another life, due now. */\n  retryDead(query: Query, id: string): Promise<boolean>;\n  /** Removes delivered and dead messages older than the retention. Returns how many. */\n  purge(query: Query): Promise<number>;\n  stats(query: Query): Promise<OutboxStats>;\n}\n\nconst MAX_ERROR = 1000;\nconst describe = (error: unknown) => (error instanceof Error ? `${error.name}: ${error.message}` : String(error)).slice(0, MAX_ERROR);\n\n/**\n * The outbox of a product.\n * @param deps the clock, the settings, and optionally the store and schema\n * @returns the outbox's functions\n */\nexport function createOutbox(deps: OutboxDeps): Outbox {\n  const schema = ident(deps.schema ?? \"outbox\");\n  const storeFor = deps.storeFor ?? ((query: Query) => dbOutboxStore(query, schema));\n  const settings = async () => checkSettings(typeof deps.settings === \"function\" ? await deps.settings() : deps.settings);\n  return {\n    async append(tx, message) {\n      checkMessage(message);\n      const now = deps.clock.now();\n      const id = message.id ?? randomUUID();\n      const appended = await storeFor(tx).append({ id, topic: message.topic, type: message.type, payload: message.payload, createdAt: now, availableAt: message.availableAt ?? now });\n      return { id, appended };\n    },\n    async claim(query, options) {\n      const s = await settings();\n      return storeFor(query).claim({ ...options, limit: options.limit ?? s.batchSize, leaseSeconds: options.leaseSeconds ?? s.leaseSeconds, maxAttempts: s.maxAttempts, now: deps.clock.now() });\n    },\n    complete: (query, id, owner) => storeFor(query).complete(id, owner, deps.clock.now()),\n    async fail(query, id, owner, error) {\n      const s = await settings();\n      return storeFor(query).fail(id, owner, describe(error), { now: deps.clock.now(), maxAttempts: s.maxAttempts, backoffSeconds: s.backoffSeconds, backoffMaxSeconds: s.backoffMaxSeconds });\n    },\n    retryDead: (query, id) => storeFor(query).retryDead(id, deps.clock.now()),\n    async purge(query) {\n      const s = await settings();\n      return storeFor(query).purgeBefore(subHours(deps.clock.now(), s.retentionDays * 24));\n    },\n    stats: (query) => storeFor(query).stats(deps.clock.now()),\n  };\n}\n","import { ident, type Query } from \"@krizaka/db\";\nimport { addSeconds } from \"@krizaka/time\";\n\nimport { FAIL_STATE, type FailOutcome, type OutboxMessage, type OutboxStats, type OutboxStore } from \"./port\";\n\ninterface Claimed {\n  id: string;\n  topic: string;\n  event_type: string;\n  payload: unknown;\n  created_at: Date | string;\n  attempts: number;\n}\n\n/**\n * The PostgreSQL store of the outbox, in `outbox.message` (see `outboxSchema`), over the `Query` it is given: the caller's\n * transaction for `append` (so the message commits or rolls back with the work), a pool for the worker's calls.\n *\n * `claim` is `UPDATE … WHERE id IN (SELECT … FOR UPDATE SKIP LOCKED)`: two workers never lease the same message while a lease is\n * valid. `complete` and `fail` only act for the lease's owner, so a worker that lost its lease cannot overwrite the new holder's outcome.\n * Times come from the caller (the injected clock), never from the database's `now()`.\n * @param schema the Postgres schema of the module, default `outbox`\n */\nexport function dbOutboxStore(query: Query, schema = \"outbox\"): OutboxStore {\n  const message = `${ident(schema)}.message`;\n  return {\n    async append(m) {\n      const rows = await query(\n        `INSERT INTO ${message} (id, topic, event_type, payload, created_at, available_at) VALUES ($1, $2, $3, $4::jsonb, $5, $6) ON CONFLICT (id) DO NOTHING RETURNING 1`,\n        [m.id, m.topic, m.type, JSON.stringify(m.payload), m.createdAt, m.availableAt],\n      );\n      return rows.length > 0;\n    },\n    async claim({ topic, owner, limit, leaseSeconds, maxAttempts, now }) {\n      // a message whose last allowed attempt's lease expired with no answer is dead, not delivered a ninth time\n      await query(\n        `UPDATE ${message} SET dead_at = $1, leased_until = NULL, lease_owner = NULL, last_error = COALESCE(last_error, 'the last attempt''s lease expired with no answer')\n          WHERE delivered_at IS NULL AND dead_at IS NULL AND attempts >= $2 AND leased_until IS NOT NULL AND leased_until <= $1`,\n        [now, maxAttempts],\n      );\n      const rows = await query<Claimed>(\n        `UPDATE ${message} AS m SET leased_until = $1, lease_owner = $2, attempts = m.attempts + 1\n          WHERE m.id IN (\n            SELECT id FROM ${message}\n             WHERE delivered_at IS NULL AND dead_at IS NULL AND available_at <= $3 AND attempts < $4\n               AND (leased_until IS NULL OR leased_until <= $3) AND ($5::text IS NULL OR topic = $5)\n             ORDER BY available_at, created_at LIMIT $6\n               FOR UPDATE SKIP LOCKED)\n        RETURNING m.id, m.topic, m.event_type, m.payload, m.created_at, m.attempts`,\n        [addSeconds(now, leaseSeconds), owner, now, maxAttempts, topic ?? null, limit],\n      );\n      return rows\n        .map((r): OutboxMessage => ({ id: r.id, topic: r.topic, type: r.event_type, payload: r.payload, occurredAt: new Date(r.created_at), attempts: Number(r.attempts) }))\n        .sort((a, b) => a.occurredAt.valueOf() - b.occurredAt.valueOf());\n    },\n    async complete(id, owner, now) {\n      const rows = await query(\n        `UPDATE ${message} SET delivered_at = $3, leased_until = NULL, lease_owner = NULL\n          WHERE id = $1 AND lease_owner = $2 AND delivered_at IS NULL AND dead_at IS NULL RETURNING 1`,\n        [id, owner, now],\n      );\n      return rows.length > 0;\n    },\n    async fail(id, owner, error, { now, maxAttempts, backoffSeconds, backoffMaxSeconds }): Promise<FailOutcome> {\n      const [row] = await query<{ attempts: number; dead_at: Date | null; available_at: Date | string }>(\n        `UPDATE ${message} SET last_error = $3::text, leased_until = NULL, lease_owner = NULL,\n                dead_at      = CASE WHEN attempts >= $5 THEN $4::timestamptz ELSE NULL END,\n                available_at = CASE WHEN attempts >= $5 THEN available_at\n                                    ELSE $4::timestamptz + make_interval(secs => LEAST($7::double precision, $6::double precision * power(2, attempts - 1))) END\n          WHERE id = $1 AND lease_owner = $2 AND delivered_at IS NULL AND dead_at IS NULL\n        RETURNING attempts, dead_at, available_at`,\n        [id, owner, error, now, maxAttempts, backoffSeconds, backoffMaxSeconds],\n      );\n      if (!row) return { state: FAIL_STATE.lost };\n      return row.dead_at ? { state: FAIL_STATE.dead } : { state: FAIL_STATE.retry, availableAt: new Date(row.available_at) };\n    },\n    async retryDead(id, now) {\n      const rows = await query(`UPDATE ${message} SET dead_at = NULL, attempts = 0, available_at = $2 WHERE id = $1 AND dead_at IS NOT NULL RETURNING 1`, [id, now]);\n      return rows.length > 0;\n    },\n    async purgeBefore(before) {\n      const rows = await query(`DELETE FROM ${message} WHERE COALESCE(delivered_at, dead_at) < $1 RETURNING 1`, [before]);\n      return rows.length;\n    },\n    async stats(now): Promise<OutboxStats> {\n      const [row] = await query<{ pending: number; leased: number; delivered: number; dead: number }>(\n        `SELECT count(*) FILTER (WHERE delivered_at IS NULL AND dead_at IS NULL AND (leased_until IS NULL OR leased_until <= $1))::int AS pending,\n                count(*) FILTER (WHERE delivered_at IS NULL AND dead_at IS NULL AND leased_until > $1)::int AS leased,\n                count(*) FILTER (WHERE delivered_at IS NOT NULL)::int AS delivered,\n                count(*) FILTER (WHERE dead_at IS NOT NULL)::int AS dead\n           FROM ${message}`,\n        [now],\n      );\n      return { pending: row?.pending ?? 0, leased: row?.leased ?? 0, delivered: row?.delivered ?? 0, dead: row?.dead ?? 0 };\n    },\n  };\n}\n","import { defineModule } from \"@krizaka/db\";\n\n/**\n * The tables of « outbox », in their own Postgres schema (ADR-001 §3). `message` is the outbox itself, the columns of the Java kit's\n * envelope (id, type, occurredAt = created_at, payload) and the state of its delivery; `processed` is the idempotent consumers'\n * record of the message ids they already applied. They reference no product table. Version 1 is frozen once released: a change is version 2.\n */\nexport const outboxSchema = defineModule({\n  module: \"outbox\",\n  migrations: [\n    {\n      version: 1,\n      name: \"messages and processed\",\n      sql: (c) => `\nCREATE TABLE ${c.schema}.message (\n  id           uuid PRIMARY KEY,\n  topic        text NOT NULL CHECK (topic ~ '^[a-z][a-z0-9_.:-]{0,59}$'),\n  event_type   text NOT NULL CHECK (event_type ~ '^[a-z][a-z0-9_.-]{0,99}$'),\n  payload      jsonb NOT NULL,\n  created_at   timestamptz NOT NULL,\n  available_at timestamptz NOT NULL,\n  attempts     integer NOT NULL DEFAULT 0 CHECK (attempts >= 0),\n  leased_until timestamptz,\n  lease_owner  text,\n  delivered_at timestamptz,\n  dead_at      timestamptz,\n  last_error   text,\n  CHECK (delivered_at IS NULL OR dead_at IS NULL)\n);\nCREATE INDEX message_due ON ${c.schema}.message (topic, available_at) WHERE delivered_at IS NULL AND dead_at IS NULL;\nCREATE INDEX message_finished ON ${c.schema}.message (COALESCE(delivered_at, dead_at)) WHERE delivered_at IS NOT NULL OR dead_at IS NOT NULL;\nCREATE TABLE ${c.schema}.processed (\n  consumer     text NOT NULL CHECK (char_length(consumer) BETWEEN 1 AND 100),\n  message_id   uuid NOT NULL,\n  processed_at timestamptz NOT NULL,\n  PRIMARY KEY (consumer, message_id)\n);`,\n    },\n  ],\n});\n","import type { Outbox } from \"./outbox\";\nimport { FAIL_STATE, type OutboxMessage, type Query } from \"./port\";\n\nexport interface DrainSummary {\n  claimed: number;\n  delivered: number;\n  retried: number;\n  dead: number;\n  /** Deliveries whose outcome could not be recorded because the lease had been lost to another worker. */\n  lost: number;\n}\n\nexport interface DrainOptions {\n  outbox: Outbox;\n  /** A pool-level query: each call is its own statement, never one long transaction, so a lease is all that holds a message. */\n  query: Query;\n  /** Who this worker is (a hostname and a process id): only the holder of a lease can complete or fail its message. */\n  owner: string;\n  /** Delivers one message: resolve on success, throw on failure. It must be idempotent on `message.id` (at-least-once). */\n  deliver: (message: OutboxMessage) => Promise<void>;\n  /** Only this topic; default every topic. */\n  topic?: string;\n}\n\n/**\n * One round: leases a batch, delivers each message in order, records each outcome. Safe to run from several instances at once.\n * A delivery that throws is retried later (or is dead after `maxAttempts`); the round goes on with the next message.\n * @returns what happened\n */\nexport async function drainOnce(options: DrainOptions): Promise<DrainSummary> {\n  const { outbox, query, owner, deliver, topic } = options;\n  const summary: DrainSummary = { claimed: 0, delivered: 0, retried: 0, dead: 0, lost: 0 };\n  const batch = await outbox.claim(query, { owner, ...(topic === undefined ? {} : { topic }) });\n  summary.claimed = batch.length;\n  for (const message of batch) {\n    let failure: { error: unknown } | null = null;\n    try {\n      await deliver(message);\n    } catch (error) {\n      failure = { error };\n    }\n    if (failure === null) {\n      if (await outbox.complete(query, message.id, owner)) summary.delivered += 1;\n      else summary.lost += 1;\n      continue;\n    }\n    const outcome = await outbox.fail(query, message.id, owner, failure.error);\n    if (outcome.state === FAIL_STATE.retry) summary.retried += 1;\n    else if (outcome.state === FAIL_STATE.dead) summary.dead += 1;\n    else summary.lost += 1;\n  }\n  return summary;\n}\n\nexport interface WorkerOptions extends DrainOptions {\n  /** Waits this many seconds (a timer: the package has none of its own). */\n  sleep: (seconds: number) => Promise<void>;\n  /** The worker stops when this signal is aborted (checked between rounds). */\n  signal?: AbortSignal;\n  /** Seconds to wait when a round found nothing. Default 5. */\n  idleSeconds?: number;\n  /** Told of a round that threw (the store was unreachable): the loop waits and goes on. */\n  onError?: (error: unknown) => void;\n}\n\n// @fixed: how long an idle worker waits before it looks again, a technical polling interval\nconst IDLE_SECONDS = 5;\n\n/**\n * The loop a product starts (Next.js `instrumentation.ts`, a worker process): drain, and sleep when there was nothing. It has no\n * timer of its own — the product passes `sleep` — and it ends when the signal is aborted.\n */\nexport async function runWorker(options: WorkerOptions): Promise<void> {\n  const idle = options.idleSeconds ?? IDLE_SECONDS;\n  while (!options.signal?.aborted) {\n    let waited: boolean;\n    try {\n      waited = (await drainOnce(options)).claimed === 0;\n    } catch (error) {\n      options.onError?.(error);\n      waited = true;\n    }\n    if (waited && !options.signal?.aborted) await options.sleep(idle);\n  }\n}\n"],"mappings":"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","names":["ident","ident","addSeconds","ident","addSeconds","backoffSeconds","ident"]}

package/dist/port-CXch5iMa.d.ts

@@ -0,0 +1,124 @@
+/**
+ * The ports of « outbox »: a message written in the caller's transaction and delivered after the commit, AT LEAST ONCE. Generic:
+ * no broker, no product import, no database client (a `Query` comes in), no wall clock (a `Clock` comes in).
+ *
+ * THE GUARANTEE. A claim is exclusive while its lease is valid. A worker that delivers and then crashes before `complete` lets the
+ * lease expire, and the message is delivered AGAIN. So every consumer must be idempotent on the message id (see `consumeOnce`).
+ * The outbox never promises « exactly once ».
+ */
+
+/** What a product appends. */
+interface NewMessage {
+    /** Where it goes: a worker claims one topic (`mail`, `recommender`, `webhooks`). Lower-case letters, digits, `_ . : -`. */
+    topic: string;
+    /** What happened, as a routing key (`evt.credit.granted.v1`): the Java kit's form. Lower-case letters, digits, `_ . -`. */
+    type: string;
+    /** The event's data: JSON. Never a secret, and as little personal data as the consumer needs. */
+    payload: unknown;
+    /** A stable id (a UUID) when the same fact can be appended twice: the second append is a no-op. Default: a fresh UUID. */
+    id?: string;
+    /** Not before this instant (a scheduled delivery). Default: now. */
+    availableAt?: Date;
+}
+/** The envelope a worker receives: the Java kit's `id`, `type`, `occurredAt`, `payload`, and where it is in its attempts. */
+interface OutboxMessage {
+    id: string;
+    topic: string;
+    type: string;
+    payload: unknown;
+    occurredAt: Date;
+    /** How many deliveries have been started for it, this one included. */
+    attempts: number;
+}
+/** The knobs of the outbox, read from the admin's settings (`@krizaka/outbox/settings`). */
+interface OutboxSettings {
+    /** Messages a worker claims at once. */
+    batchSize: number;
+    /** Seconds a claim holds a message before another worker may take it. Longer than the slowest delivery. */
+    leaseSeconds: number;
+    /** Deliveries started before a message is dead. */
+    maxAttempts: number;
+    /** Seconds before the second attempt; it doubles with each attempt. */
+    backoffSeconds: number;
+    /** The most seconds a retry waits. */
+    backoffMaxSeconds: number;
+    /** Days a delivered or dead message is kept before `purge`. */
+    retentionDays: number;
+}
+/** What `claim` takes. */
+interface ClaimOptions {
+    /** Only this topic; default every topic. */
+    topic?: string;
+    /** Who claims: a worker's id, so that only the holder of a lease can complete or fail the message. */
+    owner: string;
+}
+/** What became of a failed delivery. */
+declare const FAIL_STATE: {
+    readonly retry: "retry";
+    readonly dead: "dead";
+    readonly lost: "lost";
+};
+/** The result of `fail`: the message will be retried, is dead, or was not this worker's any more. */
+type FailOutcome = {
+    state: typeof FAIL_STATE.retry;
+    availableAt: Date;
+} | {
+    state: typeof FAIL_STATE.dead;
+} | {
+    state: typeof FAIL_STATE.lost;
+};
+interface OutboxStats {
+    /** Waiting for a worker (including retries). */
+    pending: number;
+    /** Held by a worker right now. */
+    leased: number;
+    delivered: number;
+    dead: number;
+}
+/** Where the messages live. Every adapter runs `outboxStoreContract` (`@krizaka/outbox/testkit`). Times come from the caller. */
+interface OutboxStore {
+    /** Writes the message. A second append of the same id writes nothing and answers `false`. */
+    append(message: {
+        id: string;
+        topic: string;
+        type: string;
+        payload: unknown;
+        createdAt: Date;
+        availableAt: Date;
+    }): Promise<boolean>;
+    /** First marks dead the messages whose last attempt's lease expired with no answer, then leases up to `limit` due messages. */
+    claim(options: ClaimOptions & {
+        limit: number;
+        leaseSeconds: number;
+        maxAttempts: number;
+        now: Date;
+    }): Promise<OutboxMessage[]>;
+    /** Marks it delivered, when `owner` still holds it. `false` when the lease was lost: the other worker delivers. */
+    complete(id: string, owner: string, now: Date): Promise<boolean>;
+    /** Records the failure: back off, or dead after `maxAttempts`. */
+    fail(id: string, owner: string, error: string, options: {
+        now: Date;
+        maxAttempts: number;
+        backoffSeconds: number;
+        backoffMaxSeconds: number;
+    }): Promise<FailOutcome>;
+    /** Gives a dead message another life: no attempts, due now. `false` when it is not dead. */
+    retryDead(id: string, now: Date): Promise<boolean>;
+    /** Removes the delivered and dead messages older than `before`. Returns how many. */
+    purgeBefore(before: Date): Promise<number>;
+    stats(now: Date): Promise<OutboxStats>;
+}
+declare const OUTBOX_CODE: {
+    readonly badTopic: "OUTBOX_BAD_TOPIC";
+    readonly badType: "OUTBOX_BAD_TYPE";
+    readonly badId: "OUTBOX_BAD_ID";
+    readonly badPayload: "OUTBOX_BAD_PAYLOAD";
+    readonly badSettings: "OUTBOX_BAD_SETTINGS";
+};
+type OutboxCode = (typeof OUTBOX_CODE)[keyof typeof OUTBOX_CODE];
+declare class OutboxError extends Error {
+    readonly code: OutboxCode;
+    constructor(code: OutboxCode, message: string);
+}
+
+export { type ClaimOptions as C, type FailOutcome as F, type NewMessage as N, type OutboxStore as O, type OutboxMessage as a, type OutboxStats as b, type OutboxSettings as c, FAIL_STATE as d, OUTBOX_CODE as e, type OutboxCode as f, OutboxError as g };

package/dist/settings.d.ts

@@ -0,0 +1,22 @@
+import * as _krizaka_settings from '@krizaka/settings';
+import { c as OutboxSettings } from './port-CXch5iMa.js';
+
+/**
+ * The settings of « outbox », a fragment the product adds to its registry (`@krizaka/outbox/settings`): the admin tunes the worker
+ * without a redeploy. Global scope only.
+ */
+declare const outboxSettings: {
+    readonly "outbox.batchSize": _krizaka_settings.Def<number>;
+    readonly "outbox.leaseSeconds": _krizaka_settings.Def<number>;
+    readonly "outbox.maxAttempts": _krizaka_settings.Def<number>;
+    readonly "outbox.backoffSeconds": _krizaka_settings.Def<number>;
+    readonly "outbox.backoffMaxSeconds": _krizaka_settings.Def<number>;
+    readonly "outbox.retentionDays": _krizaka_settings.Def<number>;
+};
+/**
+ * The outbox's settings as `createOutbox` takes them, from the product's accessor (`(key) => service.get(key, ctx)`).
+ * A key the accessor does not know falls back to the default.
+ */
+declare function readOutboxSettings(read: (key: keyof typeof outboxSettings) => number | undefined | Promise<number | undefined>): Promise<OutboxSettings>;
+
+export { outboxSettings, readOutboxSettings };

package/dist/settings.js

@@ -0,0 +1,33 @@
+import {
+  OUTBOX_BOUNDS,
+  OUTBOX_DEFAULTS
+} from "./chunk-AD76AB44.js";
+import "./chunk-7WIJNAGK.js";
+
+// src/settings.ts
+import { integer } from "@krizaka/settings";
+var def = (key, unit) => integer("outbox", OUTBOX_DEFAULTS[key], { min: OUTBOX_BOUNDS[key][0], max: OUTBOX_BOUNDS[key][1], unit });
+var outboxSettings = {
+  "outbox.batchSize": def("batchSize", "messages"),
+  "outbox.leaseSeconds": def("leaseSeconds", "seconds"),
+  "outbox.maxAttempts": def("maxAttempts", "attempts"),
+  "outbox.backoffSeconds": def("backoffSeconds", "seconds"),
+  "outbox.backoffMaxSeconds": def("backoffMaxSeconds", "seconds"),
+  "outbox.retentionDays": def("retentionDays", "days")
+};
+async function readOutboxSettings(read) {
+  const value = async (key) => await read(`outbox.${key}`) ?? OUTBOX_DEFAULTS[key];
+  return {
+    batchSize: await value("batchSize"),
+    leaseSeconds: await value("leaseSeconds"),
+    maxAttempts: await value("maxAttempts"),
+    backoffSeconds: await value("backoffSeconds"),
+    backoffMaxSeconds: await value("backoffMaxSeconds"),
+    retentionDays: await value("retentionDays")
+  };
+}
+export {
+  outboxSettings,
+  readOutboxSettings
+};
+//# sourceMappingURL=settings.js.map

package/dist/settings.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/settings.ts"],"sourcesContent":["import { integer, type Registry } from \"@krizaka/settings\";\n\nimport type { OutboxSettings } from \"./port\";\nimport { OUTBOX_BOUNDS, OUTBOX_DEFAULTS } from \"./rules\";\n\nconst def = <K extends keyof OutboxSettings>(key: K, unit: string) => integer(\"outbox\", OUTBOX_DEFAULTS[key], { min: OUTBOX_BOUNDS[key][0], max: OUTBOX_BOUNDS[key][1], unit });\n\n/**\n * The settings of « outbox », a fragment the product adds to its registry (`@krizaka/outbox/settings`): the admin tunes the worker\n * without a redeploy. Global scope only.\n */\nexport const outboxSettings = {\n  \"outbox.batchSize\": def(\"batchSize\", \"messages\"),\n  \"outbox.leaseSeconds\": def(\"leaseSeconds\", \"seconds\"),\n  \"outbox.maxAttempts\": def(\"maxAttempts\", \"attempts\"),\n  \"outbox.backoffSeconds\": def(\"backoffSeconds\", \"seconds\"),\n  \"outbox.backoffMaxSeconds\": def(\"backoffMaxSeconds\", \"seconds\"),\n  \"outbox.retentionDays\": def(\"retentionDays\", \"days\"),\n} as const satisfies Registry;\n\n/**\n * The outbox's settings as `createOutbox` takes them, from the product's accessor (`(key) => service.get(key, ctx)`).\n * A key the accessor does not know falls back to the default.\n */\nexport async function readOutboxSettings(read: (key: keyof typeof outboxSettings) => number | undefined | Promise<number | undefined>): Promise<OutboxSettings> {\n  const value = async (key: keyof OutboxSettings) => (await read(`outbox.${key}`)) ?? OUTBOX_DEFAULTS[key];\n  return {\n    batchSize: await value(\"batchSize\"),\n    leaseSeconds: await value(\"leaseSeconds\"),\n    maxAttempts: await value(\"maxAttempts\"),\n    backoffSeconds: await value(\"backoffSeconds\"),\n    backoffMaxSeconds: await value(\"backoffMaxSeconds\"),\n    retentionDays: await value(\"retentionDays\"),\n  };\n}\n"],"mappings":";;;;;;;AAAA,SAAS,eAA8B;AAKvC,IAAM,MAAM,CAAiC,KAAQ,SAAiB,QAAQ,UAAU,gBAAgB,GAAG,GAAG,EAAE,KAAK,cAAc,GAAG,EAAE,CAAC,GAAG,KAAK,cAAc,GAAG,EAAE,CAAC,GAAG,KAAK,CAAC;AAMvK,IAAM,iBAAiB;AAAA,EAC5B,oBAAoB,IAAI,aAAa,UAAU;AAAA,EAC/C,uBAAuB,IAAI,gBAAgB,SAAS;AAAA,EACpD,sBAAsB,IAAI,eAAe,UAAU;AAAA,EACnD,yBAAyB,IAAI,kBAAkB,SAAS;AAAA,EACxD,4BAA4B,IAAI,qBAAqB,SAAS;AAAA,EAC9D,wBAAwB,IAAI,iBAAiB,MAAM;AACrD;AAMA,eAAsB,mBAAmB,MAAuH;AAC9J,QAAM,QAAQ,OAAO,QAA+B,MAAM,KAAK,UAAU,GAAG,EAAE,KAAM,gBAAgB,GAAG;AACvG,SAAO;AAAA,IACL,WAAW,MAAM,MAAM,WAAW;AAAA,IAClC,cAAc,MAAM,MAAM,cAAc;AAAA,IACxC,aAAa,MAAM,MAAM,aAAa;AAAA,IACtC,gBAAgB,MAAM,MAAM,gBAAgB;AAAA,IAC5C,mBAAmB,MAAM,MAAM,mBAAmB;AAAA,IAClD,eAAe,MAAM,MAAM,eAAe;AAAA,EAC5C;AACF;","names":[]}

package/dist/testkit.d.ts

@@ -0,0 +1,6 @@
+import { O as OutboxStore } from './port-CXch5iMa.js';
+
+/** What every `OutboxStore` adapter must do: the same behaviour behind the same port. `make` gives an empty store. */
+declare function outboxStoreContract(name: string, make: () => OutboxStore | Promise<OutboxStore>): void;
+
+export { outboxStoreContract };