@beignet/core 0.0.31 → 0.0.33

package/src/outbox/index.ts

@@ -16,6 +16,8 @@ import {
   type InferJobPayload,
   type JobDef,
   parseJobPayload,
+  SINGLE_ATTEMPT_DISPATCH,
+  type SingleAttemptJobDispatch,
   shouldRetryJob,
 } from "../jobs/index.js";
 import type { JobDispatcherPort } from "../ports/events.js";
@@ -267,6 +269,116 @@ export interface OutboxMarkFailedInput {
   now?: Date;
 }
 
+/**
+ * Default maximum messages returned from outbox admin list calls.
+ */
+export const DEFAULT_OUTBOX_ADMIN_LIST_LIMIT = 50;
+
+/**
+ * Shared filters for outbox admin read operations.
+ */
+export interface OutboxMessageQuery {
+  /**
+   * Status or statuses to include.
+   */
+  status?: OutboxMessageStatus | readonly OutboxMessageStatus[];
+  /**
+   * Message kind to include.
+   */
+  kind?: OutboxMessageKind;
+  /**
+   * Event or job name to include.
+   */
+  name?: string;
+  /**
+   * Include messages last updated before this timestamp.
+   */
+  updatedBefore?: Date;
+  /**
+   * Include delivered messages delivered before this timestamp.
+   */
+  deliveredBefore?: Date;
+}
+
+/**
+ * Options for listing outbox messages through the admin port.
+ */
+export interface OutboxListMessagesOptions extends OutboxMessageQuery {
+  /**
+   * Maximum messages to return. Defaults to
+   * `DEFAULT_OUTBOX_ADMIN_LIST_LIMIT`.
+   */
+  limit?: number;
+}
+
+/**
+ * Options for counting outbox messages through the admin port.
+ */
+export interface OutboxCountMessagesOptions extends OutboxMessageQuery {}
+
+/**
+ * Input for returning a dead-lettered message to the pending queue.
+ */
+export interface OutboxRequeueMessageInput {
+  /**
+   * Dead-lettered message ID.
+   */
+  id: string;
+  /**
+   * Earliest time the message may be claimed again. Defaults to `now`.
+   */
+  availableAt?: Date;
+  /**
+   * Reset attempts to zero before requeueing. Defaults to preserving the
+   * attempt count so operators can decide whether to grant a fresh retry
+   * budget.
+   */
+  resetAttempts?: boolean;
+  /**
+   * Requeue timestamp.
+   */
+  now?: Date;
+}
+
+/**
+ * Input for purging dead-lettered messages.
+ */
+export interface OutboxPurgeDeadLetteredInput {
+  /**
+   * Only purge messages last updated before this timestamp. Omit only when the
+   * caller intentionally wants to purge all dead-lettered messages.
+   */
+  before?: Date;
+  /**
+   * Maximum messages to purge.
+   */
+  limit?: number;
+}
+
+/**
+ * Input for pruning delivered messages.
+ */
+export interface OutboxPruneDeliveredInput {
+  /**
+   * Prune delivered messages delivered before this timestamp.
+   */
+  before: Date;
+  /**
+   * Maximum messages to prune.
+   */
+  limit?: number;
+}
+
+/**
+ * Result for outbox admin delete operations.
+ */
+export interface OutboxDeleteResult {
+  /**
+   * Number of rows deleted.
+   */
+  deleted: number;
+}
+
 /**
  * App-facing outbox storage port.
  *
@@ -292,10 +404,48 @@ export interface OutboxPort {
   markFailed(input: OutboxMarkFailedInput): Promise<void>;
 }
 
+/**
+ * Operational outbox admin port.
+ *
+ * Keep this separate from `OutboxPort` so request and drain contexts can expose
+ * only the hot-path delivery operations. Wire this port into maintenance
+ * contexts for CLI commands, runbooks, and devtools.
+ */
+export interface OutboxAdminPort {
+  /**
+   * List messages ordered by newest update first.
+   */
+  listMessages(
+    options?: OutboxListMessagesOptions,
+  ): Promise<readonly OutboxMessage[]>;
+  /**
+   * Count messages matching admin filters.
+   */
+  countMessages(options?: OutboxCountMessagesOptions): Promise<number>;
+  /**
+   * Fetch one message by ID.
+   */
+  getMessage(id: string): Promise<OutboxMessage | null>;
+  /**
+   * Return a dead-lettered message to pending state.
+   */
+  requeueMessage(input: OutboxRequeueMessageInput): Promise<OutboxMessage>;
+  /**
+   * Delete dead-lettered messages.
+   */
+  purgeDeadLettered(
+    input?: OutboxPurgeDeadLetteredInput,
+  ): Promise<OutboxDeleteResult>;
+  /**
+   * Delete delivered messages older than a retention cutoff.
+   */
+  pruneDelivered(input: OutboxPruneDeliveredInput): Promise<OutboxDeleteResult>;
+}
+
 /**
  * In-memory outbox for tests and local examples.
  */
-export interface MemoryOutboxPort extends OutboxPort {
+export interface MemoryOutboxPort extends OutboxPort, OutboxAdminPort {
   /**
    * Current message snapshots.
    */
@@ -311,9 +461,13 @@ export interface MemoryOutboxPort extends OutboxPort {
  */
 export interface CreateOutboxMessageOptions {
   /**
-   * Generated message ID override.
+   * Generated message ID override. Wins over `input.id`.
    */
   id?: string;
+  /**
+   * Fallback ID factory used when neither `id` nor `input.id` is provided.
+   */
+  createId?: () => string;
   /**
    * Timestamp used for created/updated/available dates.
    */
@@ -498,6 +652,22 @@ export class OutboxClaimError extends Error {
   }
 }
 
+/**
+ * Error thrown when an outbox admin operation cannot be completed safely.
+ */
+export class OutboxAdminError extends Error {
+  /**
+   * Message ID involved in the admin error, when applicable.
+   */
+  readonly id?: string;
+
+  constructor(args: { message: string; id?: string }) {
+    super(args.message);
+    this.name = "OutboxAdminError";
+    this.id = args.id;
+  }
+}
+
 function assertNonEmptyString(name: string, value: string): void {
   if (typeof value !== "string" || value.trim().length === 0) {
     throw new Error(`${name} must be a non-empty string`);
@@ -510,6 +680,12 @@ function assertPositiveInteger(name: string, value: number): void {
   }
 }
 
+function assertValidDate(name: string, value: Date): void {
+  if (!(value instanceof Date) || Number.isNaN(value.getTime())) {
+    throw new Error(`${name} must be a valid Date`);
+  }
+}
+
 function cloneDate(value: Date): Date {
   return new Date(value.getTime());
 }
@@ -639,6 +815,75 @@ function copyMessage(message: OutboxMessage): OutboxMessage {
   };
 }
 
+function normalizeStatusFilter(
+  status: OutboxMessageQuery["status"],
+): ReadonlySet<OutboxMessageStatus> | undefined {
+  if (status === undefined) return undefined;
+  return new Set(Array.isArray(status) ? status : [status]);
+}
+
+function messageMatchesQuery(
+  message: OutboxMessage,
+  query: OutboxMessageQuery = {},
+): boolean {
+  const statuses = normalizeStatusFilter(query.status);
+  if (statuses && !statuses.has(message.status)) return false;
+  if (query.kind !== undefined && message.kind !== query.kind) return false;
+  if (query.name !== undefined && message.name !== query.name) return false;
+  if (
+    query.updatedBefore !== undefined &&
+    message.updatedAt.getTime() >= query.updatedBefore.getTime()
+  ) {
+    return false;
+  }
+  if (
+    query.deliveredBefore !== undefined &&
+    (message.deliveredAt === null ||
+      message.deliveredAt.getTime() >= query.deliveredBefore.getTime())
+  ) {
+    return false;
+  }
+  return true;
+}
+
+function compareMessagesForAdminList(
+  left: OutboxMessage,
+  right: OutboxMessage,
+): number {
+  const updated = right.updatedAt.getTime() - left.updatedAt.getTime();
+  if (updated !== 0) return updated;
+  const created = right.createdAt.getTime() - left.createdAt.getTime();
+  if (created !== 0) return created;
+  return right.id.localeCompare(left.id);
+}
+
+function compareMessagesForAdminCleanup(
+  left: OutboxMessage,
+  right: OutboxMessage,
+): number {
+  const updated = left.updatedAt.getTime() - right.updatedAt.getTime();
+  if (updated !== 0) return updated;
+  const created = left.createdAt.getTime() - right.createdAt.getTime();
+  if (created !== 0) return created;
+  return left.id.localeCompare(right.id);
+}
+
+function compareDeliveredMessagesForPrune(
+  left: OutboxMessage,
+  right: OutboxMessage,
+): number {
+  const delivered =
+    (left.deliveredAt?.getTime() ?? 0) - (right.deliveredAt?.getTime() ?? 0);
+  if (delivered !== 0) return delivered;
+  return compareMessagesForAdminCleanup(left, right);
+}
+
+function resolveAdminListLimit(limit: number | undefined): number {
+  const resolved = limit ?? DEFAULT_OUTBOX_ADMIN_LIST_LIMIT;
+  assertPositiveInteger("limit", resolved);
+  return resolved;
+}
+
 function toClaimedMessage(message: OutboxMessage): ClaimedOutboxMessage {
   if (
     message.status !== "claimed" ||
@@ -677,7 +922,7 @@ export function createOutboxMessage(
 
   const now = options.now ?? new Date();
   return {
-    id: options.id ?? input.id ?? createId(),
+    id: options.id ?? input.id ?? options.createId?.() ?? createId(),
     kind: input.kind,
     name: input.name,
     payload: toOutboxJsonValue(input.payload),
@@ -709,12 +954,31 @@ function isEligible(message: OutboxMessage, now: Date): boolean {
   );
 }
 
+/**
+ * Options for `createMemoryOutbox(...)`.
+ */
+export interface MemoryOutboxOptions {
+  /**
+   * Message and claim-token ID factory. Defaults to `crypto.randomUUID()`.
+   */
+  id?: () => string;
+  /**
+   * Clock used for enqueue, claim, and completion timestamps when a call does
+   * not supply its own `now`. Defaults to the system clock.
+   */
+  now?: () => Date;
+}
+
 /**
  * Create an in-memory outbox for tests and local examples.
  *
  * The memory outbox is process-local and not durable.
  */
-export function createMemoryOutbox(): MemoryOutboxPort {
+export function createMemoryOutbox(
+  storeOptions: MemoryOutboxOptions = {},
+): MemoryOutboxPort {
+  const createStoreId = storeOptions.id ?? createId;
+  const storeNow = storeOptions.now ?? (() => new Date());
   const messages = new Map<string, OutboxMessage>();
 
   function getClaimedOrThrow(id: string, claimToken: string): OutboxMessage {
@@ -739,8 +1003,125 @@ export function createMemoryOutbox(): MemoryOutboxPort {
       return [...messages.values()].map(copyMessage);
     },
 
+    async listMessages(options = {}) {
+      const limit = resolveAdminListLimit(options.limit);
+      if (options.updatedBefore) {
+        assertValidDate("updatedBefore", options.updatedBefore);
+      }
+      if (options.deliveredBefore) {
+        assertValidDate("deliveredBefore", options.deliveredBefore);
+      }
+
+      return [...messages.values()]
+        .filter((message) => messageMatchesQuery(message, options))
+        .sort(compareMessagesForAdminList)
+        .slice(0, limit)
+        .map(copyMessage);
+    },
+
+    async countMessages(options = {}) {
+      if (options.updatedBefore) {
+        assertValidDate("updatedBefore", options.updatedBefore);
+      }
+      if (options.deliveredBefore) {
+        assertValidDate("deliveredBefore", options.deliveredBefore);
+      }
+
+      return [...messages.values()].filter((message) =>
+        messageMatchesQuery(message, options),
+      ).length;
+    },
+
+    async getMessage(id) {
+      assertNonEmptyString("id", id);
+      const message = messages.get(id);
+      return message ? copyMessage(message) : null;
+    },
+
+    async requeueMessage(input) {
+      assertNonEmptyString("id", input.id);
+      const message = messages.get(input.id);
+      if (!message) {
+        throw new OutboxAdminError({
+          id: input.id,
+          message: `Outbox message "${input.id}" does not exist.`,
+        });
+      }
+      if (message.status !== "deadLettered") {
+        throw new OutboxAdminError({
+          id: input.id,
+          message: `Outbox message "${input.id}" is not dead-lettered.`,
+        });
+      }
+
+      const now = input.now ?? storeNow();
+      const availableAt = input.availableAt ?? now;
+      assertValidDate("now", now);
+      assertValidDate("availableAt", availableAt);
+
+      message.status = "pending";
+      message.availableAt = cloneDate(availableAt);
+      message.claimToken = null;
+      message.claimedAt = null;
+      message.lockedUntil = null;
+      if (input.resetAttempts) message.attempts = 0;
+      message.updatedAt = cloneDate(now);
+
+      return copyMessage(message);
+    },
+
+    async purgeDeadLettered(input = {}) {
+      const limit =
+        input.limit === undefined
+          ? undefined
+          : resolveAdminListLimit(input.limit);
+      if (input.before) assertValidDate("before", input.before);
+
+      const candidates = [...messages.values()]
+        .filter(
+          (message) =>
+            message.status === "deadLettered" &&
+            (input.before === undefined ||
+              message.updatedAt.getTime() < input.before.getTime()),
+        )
+        .sort(compareMessagesForAdminCleanup)
+        .slice(0, limit);
+
+      for (const message of candidates) {
+        messages.delete(message.id);
+      }
+
+      return { deleted: candidates.length };
+    },
+
+    async pruneDelivered(input) {
+      assertValidDate("before", input.before);
+      const limit =
+        input.limit === undefined
+          ? undefined
+          : resolveAdminListLimit(input.limit);
+      const candidates = [...messages.values()]
+        .filter(
+          (message) =>
+            message.status === "delivered" &&
+            message.deliveredAt !== null &&
+            message.deliveredAt.getTime() < input.before.getTime(),
+        )
+        .sort(compareDeliveredMessagesForPrune)
+        .slice(0, limit);
+
+      for (const message of candidates) {
+        messages.delete(message.id);
+      }
+
+      return { deleted: candidates.length };
+    },
+
     async enqueue(input) {
-      const message = createOutboxMessage(input);
+      const message = createOutboxMessage(input, {
+        createId: createStoreId,
+        now: storeNow(),
+      });
       if (messages.has(message.id)) {
         throw new Error(`Outbox message "${message.id}" already exists.`);
       }
@@ -750,7 +1131,7 @@ export function createMemoryOutbox(): MemoryOutboxPort {
 
     async claimBatch(options) {
       assertPositiveInteger("limit", options.limit);
-      const now = options.now ?? new Date();
+      const now = options.now ?? storeNow();
       const leaseMs = options.leaseMs ?? DEFAULT_OUTBOX_LEASE_MS;
       assertPositiveInteger("leaseMs", leaseMs);
       const lockedUntil = new Date(now.getTime() + leaseMs);
@@ -768,7 +1149,7 @@ export function createMemoryOutbox(): MemoryOutboxPort {
       for (const message of eligible) {
         message.status = "claimed";
         message.attempts += 1;
-        message.claimToken = createId();
+        message.claimToken = createStoreId();
         message.claimedAt = cloneDate(now);
         message.lockedUntil = cloneDate(lockedUntil);
         message.updatedAt = cloneDate(now);
@@ -782,7 +1163,7 @@ export function createMemoryOutbox(): MemoryOutboxPort {
       assertNonEmptyString("id", input.id);
       assertNonEmptyString("claimToken", input.claimToken);
       const message = getClaimedOrThrow(input.id, input.claimToken);
-      const now = input.now ?? new Date();
+      const now = input.now ?? storeNow();
 
       message.status = "delivered";
       message.deliveredAt = cloneDate(now);
@@ -796,7 +1177,7 @@ export function createMemoryOutbox(): MemoryOutboxPort {
       assertNonEmptyString("id", input.id);
       assertNonEmptyString("claimToken", input.claimToken);
       const message = getClaimedOrThrow(input.id, input.claimToken);
-      const now = input.now ?? new Date();
+      const now = input.now ?? storeNow();
 
       message.status = input.deadLetter ? "deadLettered" : "pending";
       message.lastError = serializeOutboxError(input.error);
@@ -1018,6 +1399,25 @@ async function deliverOutboxMessage(
   }
 
   const payload = await parseJobPayload(job, message.payload);
+
+  // The drain owns execution retries: failed deliveries are rescheduled with
+  // the job's own policy via markFailed/retryAt. When the dispatcher exposes
+  // a single-attempt dispatch (the inline dispatcher does), use it so the
+  // retry policy runs in exactly one layer. Durable providers do not expose
+  // it — for them dispatch is an enqueue and the queue owns execution.
+  const singleAttempt = (
+    options.jobs as {
+      [SINGLE_ATTEMPT_DISPATCH]?: SingleAttemptJobDispatch;
+    }
+  )[SINGLE_ATTEMPT_DISPATCH];
+  if (singleAttempt) {
+    await singleAttempt(job, payload, {
+      attempt: message.attempts,
+      maxAttempts: message.maxAttempts,
+    });
+    return;
+  }
+
   await options.jobs.dispatch(job, payload);
 }
 

package/src/ports/events.ts

@@ -10,8 +10,8 @@ import type {
 
 /**
  * Represents a defined Domain Event with name and payload schema.
- * This is a minimal interface that ports need - implementations can use
- * the full DomainEventDef from @beignet/core/domain if desired.
+ * This is a minimal structural interface that ports need - event
+ * declarations from `defineEvent` in @beignet/core/events satisfy it.
  */
 export interface DomainEventDef<
   Name extends string = string,

package/src/ports/index.ts

@@ -281,14 +281,22 @@ export type {
  */
 export type {
   ClaimedOutboxMessage,
+  OutboxAdminPort,
   OutboxClaimBatchOptions,
+  OutboxCountMessagesOptions,
+  OutboxDeleteResult,
   OutboxEnqueueInput,
+  OutboxListMessagesOptions,
   OutboxMarkDeliveredInput,
   OutboxMarkFailedInput,
   OutboxMessage,
   OutboxMessageKind,
+  OutboxMessageQuery,
   OutboxMessageStatus,
   OutboxPort,
+  OutboxPruneDeliveredInput,
+  OutboxPurgeDeadLetteredInput,
+  OutboxRequeueMessageInput,
 } from "../outbox/index.js";
 /**
  * Payments port exports.
@@ -359,6 +367,15 @@ export {
   SearchOptionsError,
   searchDocuments,
 } from "../search/index.js";
+/**
+ * Tenant scope exports.
+ */
+export type { TenantScope } from "../tenancy/index.js";
+export {
+  createTenantScope,
+  requireTenantScope,
+  tenantScopeId,
+} from "../tenancy/index.js";
 /**
  * Webhook exports.
  *

package/src/providers/instrumentation.ts

@@ -39,6 +39,10 @@ export interface BaseProviderInstrumentationEvent {
    * W3C traceparent header value, when available.
    */
   traceparent?: string;
+  /**
+   * W3C tracestate value associated with the current operation.
+   */
+  tracestate?: string;
   /**
    * Watcher category used by devtools and instrumentation sinks.
    */

package/src/providers/provider.ts

@@ -36,6 +36,15 @@ export interface ProviderConfigDef<CfgSchema extends StandardSchemaV1> {
    * and pass them to the schema for validation.
    */
   envPrefix?: string;
+
+  /**
+   * Field-level config overrides, keyed by schema field name. Defined values
+   * are merged over the env-derived (or server-supplied) input before
+   * validation, so factory options win over environment variables and still
+   * satisfy required fields when the env var is absent. `undefined` values
+   * are ignored.
+   */
+  overrides?: Record<string, unknown>;
 }
 
 /**
@@ -161,8 +170,8 @@ export interface ServiceProviderMetadata {
  *
  * @example
  * ```ts
- * const redisProvider = createProvider({
- *   name: "redis",
+ * const redisCacheProvider = createProvider({
+ *   name: "cache-redis",
  *   config: {
  *     schema: z.object({ URL: z.string().url() }),
  *     envPrefix: "REDIS_",