@beignet/core 0.0.31 → 0.0.32

package/src/domain/entity.ts

@@ -66,9 +66,47 @@ function validateSchemaSync<T>(
 // biome-ignore lint/suspicious/noExplicitAny: Base methods type for flexibility
 type AnyMethods = Record<string, any>;
 
+/**
+ * Base entity instance passed to the `.methods(...)` builder: validated props
+ * plus the `with` and `toJSON` helpers, before domain methods attach.
+ *
+ * `with(...)` is typed as returning the base instance here because the final
+ * methods object is still being defined while the builder runs. At runtime
+ * the returned instance carries the entity's methods, and `EntityInstance`
+ * maps base-instance returns back to the full instance type so consumers keep
+ * typed method chaining.
+ */
+export type EntityBaseInstance<Schema extends StandardSchema> =
+  InferOutput<Schema> & {
+    /**
+     * Create a new validated entity instance with patched properties.
+     */
+    with(
+      patch: Partial<InferOutput<Schema>>,
+    ): EntityBaseInstance<Schema> | Promise<EntityBaseInstance<Schema>>;
+    /**
+     * Convert the entity to a plain JSON object for persistence.
+     */
+    toJSON(): InferOutput<Schema>;
+  };
+
+/**
+ * Replace base-instance returns with the full entity instance type, unwrapping
+ * promises, so methods that return `self` or `self.with(...)` chain with the
+ * entity's methods attached.
+ */
+type WithEntityInstance<R, Instance, Schema extends StandardSchema> =
+  R extends Promise<infer P>
+    ? Promise<WithEntityInstance<P, Instance, Schema>>
+    : R extends EntityBaseInstance<Schema>
+      ? Instance
+      : R;
+
 /**
  * Entity instance with validated props, attached methods, and immutable update
- * helpers.
+ * helpers. Method returns that are typed as the base instance (`self` or
+ * `self.with(...)`) are mapped to the full instance type so chaining keeps
+ * the entity's methods.
  */
 export type EntityInstance<
   Name extends string,
@@ -87,7 +125,13 @@ export type EntityInstance<
    * Convert the entity to a plain JSON object for persistence.
    */
   toJSON(): InferOutput<Schema>;
-} & Methods;
+} & {
+  [K in keyof Methods]: Methods[K] extends (...args: infer A) => infer R
+    ? (
+        ...args: A
+      ) => WithEntityInstance<R, EntityInstance<Name, Schema, Methods>, Schema>
+    : Methods[K];
+};
 
 /**
  * Entity definition returned by `defineEntity(...).build()`.
@@ -135,8 +179,7 @@ class EntityBuilder<
     private readonly cfg: {
       name: Name;
       schema?: Schema;
-      // biome-ignore lint/suspicious/noExplicitAny: Methods builder receives base instance
-      methods?: (self: any) => Methods;
+      methods?: (self: EntityBaseInstance<Schema>) => Methods;
     },
   ) {}
 
@@ -147,17 +190,22 @@ class EntityBuilder<
     return new EntityBuilder<Name, S, Methods>({
       name: this.cfg.name,
       schema,
-      methods: this.cfg.methods,
+      // Methods declared before props were typed against the previous schema;
+      // canonical builder order is props-then-methods, so this widening only
+      // affects the discouraged reverse order.
+      methods: this.cfg.methods as unknown as
+        | ((self: EntityBaseInstance<S>) => Methods)
+        | undefined,
     });
   }
 
   /**
    * Define methods to attach to entity instances.
-   * The method builder receives the base instance (with props, with, and toJSON).
+   * The method builder receives the typed base instance: validated props plus
+   * `with` and `toJSON`.
    */
   methods<M extends AnyMethods>(
-    // biome-ignore lint/suspicious/noExplicitAny: Methods builder receives base instance with props
-    build: (self: any) => M,
+    build: (self: EntityBaseInstance<Schema>) => M,
   ): EntityBuilder<Name, Schema, M> {
     return new EntityBuilder<Name, Schema, M>({
       name: this.cfg.name,
@@ -190,8 +238,7 @@ class EntityBuilder<
         // Cast parsed to a plain object for spreading
         const parsedObj = parsed as Record<string, unknown>;
 
-        // biome-ignore lint/suspicious/noExplicitAny: Dynamic object construction
-        const base: any = {
+        const base = {
           ...parsedObj,
           // Immutable update - creates a new validated instance
           // Note: Re-validates the merged props for data integrity
@@ -205,7 +252,7 @@ class EntityBuilder<
           toJSON() {
             return parsed;
           },
-        };
+        } as EntityBaseInstance<Schema>;
 
         const methods = methodsBuilder?.(base) ?? {};
         const instance = Object.freeze({
@@ -262,6 +309,7 @@ class EntityBuilder<
  * ```
  */
 export function defineEntity<Name extends string>(name: Name) {
-  // biome-ignore lint/suspicious/noExplicitAny: Initial schema type will be set via .props()
-  return new EntityBuilder<Name, any, Record<string, never>>({ name } as any);
+  return new EntityBuilder<Name, StandardSchema, Record<string, never>>({
+    name,
+  });
 }

package/src/domain/index.ts

@@ -1,18 +1,19 @@
 /**
  * @beignet/core/domain
  *
- * Domain modeling helpers for Beignet - value objects, entities, and domain events.
+ * Domain modeling helpers for Beignet - value objects and entities.
  *
  * This package provides small, framework-agnostic helpers for domain modeling:
  * - A Value Object builder (defineValueObject)
  * - An Entity/Aggregate builder (defineEntity)
- * - A Domain Event helper (defineDomainEvent)
+ *
+ * Domain events are declared with `defineEvent` from `@beignet/core/events`.
  */
 
-export { defineEntity, type EntityDef, type EntityInstance } from "./entity.js";
 export {
-  type DomainEventDef,
-  defineDomainEvent,
-  type InferEventPayload,
-} from "./events.js";
+  defineEntity,
+  type EntityBaseInstance,
+  type EntityDef,
+  type EntityInstance,
+} from "./entity.js";
 export { defineValueObject, type ValueObjectDef } from "./value-object.js";

package/src/flags/index.ts

@@ -38,7 +38,7 @@ export type FlagKey = string;
 /**
  * Feature flag value kind.
  */
-export type FlagKind = "boolean" | "string" | "number" | "object";
+export type FlagValueKind = "boolean" | "string" | "number" | "object";
 
 /**
  * Subject used for provider-neutral flag targeting.
@@ -104,8 +104,9 @@ export type FlagEvaluationContext = {
  * Flag definition registered through `defineFlags(...)`.
  */
 export type FlagDef<TValue extends FlagValue = FlagValue> = {
+  kind: "flag";
   key: FlagKey;
-  kind: FlagKindForValue<TValue>;
+  valueKind: FlagValueKindForValue<TValue>;
   defaultValue: TValue;
   description?: string;
   metadata?: Record<string, unknown>;
@@ -120,13 +121,14 @@ export type InferFlagValue<TFlag> =
 /**
  * Map a value type to its runtime flag kind.
  */
-export type FlagKindForValue<TValue extends FlagValue> = TValue extends boolean
-  ? "boolean"
-  : TValue extends string
-    ? "string"
-    : TValue extends number
-      ? "number"
-      : "object";
+export type FlagValueKindForValue<TValue extends FlagValue> =
+  TValue extends boolean
+    ? "boolean"
+    : TValue extends string
+      ? "string"
+      : TValue extends number
+        ? "number"
+        : "object";
 
 /**
  * Options accepted when declaring a flag.
@@ -184,7 +186,7 @@ export type FlagEvaluationDetails<TValue extends FlagValue = FlagValue> = {
   key: string;
   value: TValue;
   defaultValue: TValue;
-  kind: FlagKindForValue<TValue>;
+  valueKind: FlagValueKindForValue<TValue>;
   reason: FlagEvaluationReason;
   defaulted: boolean;
   variant?: string;
@@ -320,20 +322,21 @@ export type MemoryFlagsPort = FlagsPort & {
 };
 
 function createFlag<TValue extends FlagValue>(
-  kind: FlagKind,
+  valueKind: FlagValueKind,
   key: string,
   options: DefineFlagOptions<TValue>,
 ): FlagDef<TValue> {
   const defaultValue = options.default;
-  if (!matchesKind(defaultValue, kind)) {
+  if (!matchesValueKind(defaultValue, valueKind)) {
     throw new Error(
-      `Flag "${key}" default value does not match "${kind}" flag kind.`,
+      `Flag "${key}" default value does not match "${valueKind}" flag value kind.`,
     );
   }
 
   return {
+    kind: "flag",
     key,
-    kind: kind as FlagKindForValue<TValue>,
+    valueKind: valueKind as FlagValueKindForValue<TValue>,
     defaultValue,
     description: options.description,
     metadata: options.metadata,
@@ -454,9 +457,9 @@ export function createMemoryFlags(
     ...port,
     values,
     set(flag, value) {
-      if (!matchesKind(value, flag.kind)) {
+      if (!matchesValueKind(value, flag.valueKind)) {
         throw new Error(
-          `Flag "${flag.key}" value does not match "${flag.kind}" flag kind.`,
+          `Flag "${flag.key}" value does not match "${flag.valueKind}" flag value kind.`,
         );
       }
       values.set(flag.key, value);
@@ -485,13 +488,14 @@ function createFlagsFromStore(
     const values = readValues();
     const stored = values[flag.key];
     const hasStored = Object.hasOwn(values, flag.key);
-    const usedStoredValue = hasStored && matchesKind(stored, flag.kind);
+    const usedStoredValue =
+      hasStored && matchesValueKind(stored, flag.valueKind);
     const value = usedStoredValue
       ? (stored as typeof defaultValue)
       : defaultValue;
     const details: FlagEvaluationDetails<typeof defaultValue> = {
       key: flag.key,
-      kind: flag.kind as FlagKindForValue<typeof defaultValue>,
+      valueKind: flag.valueKind as FlagValueKindForValue<typeof defaultValue>,
       value,
       defaultValue,
       reason: usedStoredValue ? "static" : "default",
@@ -551,7 +555,7 @@ function createFlagsFromStore(
   return flags;
 }
 
-function matchesKind(value: unknown, kind: FlagKind): boolean {
+function matchesValueKind(value: unknown, kind: FlagValueKind): boolean {
   switch (kind) {
     case "boolean":
       return typeof value === "boolean";

package/src/idempotency/index.ts

@@ -507,13 +507,27 @@ function reservationFromRecord(
   };
 }
 
+/**
+ * Options for `createMemoryIdempotencyStore(...)`.
+ */
+export interface MemoryIdempotencyStoreOptions {
+  /**
+   * Clock used for reservation and completion timestamps. Defaults to the
+   * system clock.
+   */
+  now?: () => Date;
+}
+
 /**
  * Create an in-memory idempotency store for tests and local examples.
  *
  * The memory store is process-local and not suitable for multi-process
  * production deployments.
  */
-export function createMemoryIdempotencyStore(): MemoryIdempotencyStore {
+export function createMemoryIdempotencyStore(
+  options: MemoryIdempotencyStoreOptions = {},
+): MemoryIdempotencyStore {
+  const storeNow = options.now ?? (() => new Date());
   const records = new Map<string, MemoryRecord>();
 
   return {
@@ -527,7 +541,7 @@ export function createMemoryIdempotencyStore(): MemoryIdempotencyStore {
       assertNonEmptyString("fingerprint", input.fingerprint);
       assertTtl(input.ttlSec);
 
-      const now = new Date();
+      const now = storeNow();
       const storageKey = createIdempotencyStorageKey(input);
       const existing = records.get(storageKey);
 
@@ -573,7 +587,7 @@ export function createMemoryIdempotencyStore(): MemoryIdempotencyStore {
 
       existing.status = "completed";
       existing.result = input.result;
-      existing.completedAt = new Date();
+      existing.completedAt = storeNow();
     },
 
     async fail(input) {

package/src/jobs/index.ts

@@ -284,18 +284,50 @@ export interface InlineJobDispatcherOptions<Ctx> {
    */
   ctx?: Ctx | (() => MaybePromise<Ctx>);
   /**
-   * Called when a dispatched inline job fails. When omitted, errors are
-   * rethrown to the caller.
+   * Called when a dispatched inline job fails all attempts allowed by its
+   * retry policy. When omitted, the final error is rethrown to the caller.
    */
   onError?: (error: unknown, job: JobDef<string, StandardSchema, Ctx>) => void;
+  /**
+   * Sleep implementation used between retry attempts. Defaults to a real
+   * `setTimeout` delay; inject a fake in tests to keep retries instant.
+   */
+  sleep?: (ms: number) => Promise<void>;
+  /**
+   * Honor the job's declared retry policy inline. Defaults to `true`. Set
+   * `false` when another layer owns execution retries for every dispatch
+   * through this dispatcher.
+   */
+  retry?: boolean;
 }
 
+/**
+ * Well-known symbol under which the inline dispatcher exposes a
+ * single-attempt dispatch. Delivery systems that own execution retries
+ * themselves — the outbox drain — call it instead of `dispatch(...)` so a
+ * job's retry policy runs in exactly one layer. Registered with `Symbol.for`
+ * so multiple core copies in one process agree on the key.
+ */
+export const SINGLE_ATTEMPT_DISPATCH: unique symbol = Symbol.for(
+  "beignet.jobs.singleAttemptDispatch",
+);
+
+/**
+ * Shape of the single-attempt dispatch exposed under
+ * `SINGLE_ATTEMPT_DISPATCH`.
+ */
+export type SingleAttemptJobDispatch = <J extends JobDef>(
+  job: J,
+  payload: InferJobPayload<J>,
+) => Promise<void>;
+
 /**
  * Local/test job dispatcher that executes job handlers inline.
  */
 export interface InlineJobDispatcher<Ctx = unknown> {
   /**
-   * Validate a payload and run the job handler immediately.
+   * Validate a payload and run the job handler inline, honoring the job's
+   * declared retry policy before failing.
    */
   dispatch<J extends JobDef<string, StandardSchema, Ctx>>(
     job: J,
@@ -400,7 +432,20 @@ function durationToMs(name: string, value: JobRetryDuration): number {
   }
 }
 
+const VALIDATED_RETRY_OPTIONS = Symbol("beignet.jobs.validatedRetryOptions");
+
 function validateJobRetryOptions(options: JobRetryOptions): JobRetryOptions {
+  // Options returned by this function are branded so repeated validation —
+  // per attempt in the retry helpers — short-circuits instead of re-parsing
+  // duration strings and reallocating.
+  if (
+    (options as { [VALIDATED_RETRY_OPTIONS]?: boolean })[
+      VALIDATED_RETRY_OPTIONS
+    ]
+  ) {
+    return options;
+  }
+
   const strategy = options.strategy ?? "exponential";
 
   if (!["none", "fixed", "exponential"].includes(strategy)) {
@@ -436,11 +481,16 @@ function validateJobRetryOptions(options: JobRetryOptions): JobRetryOptions {
     }
   }
 
-  return {
+  const validated = {
     ...options,
     strategy,
     attempts,
   };
+  Object.defineProperty(validated, VALIDATED_RETRY_OPTIONS, {
+    value: true,
+    enumerable: false,
+  });
+  return validated;
 }
 
 /**
@@ -584,28 +634,93 @@ export async function parseJobPayload<J extends JobDef>(
 
 /**
  * Create a local/test dispatcher that runs job handlers inline.
+ *
+ * Dispatch honors the job's declared retry policy: failed attempts retry with
+ * the policy's delays until the policy is exhausted. Payload validation
+ * failures never retry. Jobs without a retry policy run exactly once.
  */
 export function createInlineJobDispatcher<Ctx>(
   options: InlineJobDispatcherOptions<Ctx> = {},
 ): InlineJobDispatcher<Ctx> {
-  return {
-    async dispatch<J extends JobDef<string, StandardSchema, Ctx>>(
-      job: J,
-      payload: InferJobPayload<J>,
-    ) {
+  const sleep =
+    options.sleep ??
+    ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+
+  async function run<J extends JobDef<string, StandardSchema, Ctx>>(
+    job: J,
+    payload: InferJobPayload<J>,
+    retryEnabled: boolean,
+  ): Promise<void> {
+    const fail = (error: unknown): void => {
+      options.onError?.(error, job);
+      if (!options.onError) throw error;
+    };
+
+    let parsed: InferJobPayload<J>;
+    let ctx: Ctx;
+    try {
+      parsed = await parseJobPayload(job, payload);
+      // Resolve once per dispatch so a ctx factory does not run (and cannot
+      // produce different contexts) across retry attempts.
+      ctx = await resolveCtx(options.ctx);
+    } catch (error) {
+      fail(error);
+      return;
+    }
+
+    const policy = retryEnabled ? job.retry : undefined;
+    const maxAttempts = policy ? (getJobRetryMaxAttempts(policy) ?? 1) : 1;
+
+    for (let attempt = 1; ; attempt += 1) {
       try {
-        const parsed = await parseJobPayload(job, payload);
         await job.handle({
           job,
           payload: parsed,
-          ctx: await resolveCtx(options.ctx),
+          ctx,
         });
+        return;
       } catch (error) {
-        options.onError?.(error, job);
-        if (!options.onError) throw error;
+        const willRetry = shouldRetryJob(policy, {
+          error,
+          attempt,
+          maxAttempts,
+          jobName: job.name,
+        });
+        if (!willRetry) {
+          fail(error);
+          return;
+        }
+
+        const delayMs = getJobRetryDelayMs(policy, {
+          error,
+          attempt,
+          jobName: job.name,
+        });
+        if (delayMs > 0) await sleep(delayMs);
       }
+    }
+  }
+
+  const dispatcher: InlineJobDispatcher<Ctx> = {
+    async dispatch<J extends JobDef<string, StandardSchema, Ctx>>(
+      job: J,
+      payload: InferJobPayload<J>,
+    ) {
+      await run(job, payload, options.retry !== false);
     },
   };
+
+  // Non-enumerable so spreads and serialization keep treating the dispatcher
+  // as a plain port; the outbox drain discovers it by symbol.
+  Object.defineProperty(dispatcher, SINGLE_ATTEMPT_DISPATCH, {
+    value: <J extends JobDef<string, StandardSchema, Ctx>>(
+      job: J,
+      payload: InferJobPayload<J>,
+    ) => run(job, payload, false),
+    enumerable: false,
+  });
+
+  return dispatcher;
 }
 
 /**
@@ -617,9 +732,9 @@ export function createInlineJobDispatcher<Ctx>(
  * export const { defineJob } = createJobs<AppContext>();
  * ```
  *
- * Retry options are provider hints. Inline dispatchers validate payloads and
- * call `handle(...)` immediately; durable providers may enqueue or schedule the
- * job according to their own runtime.
+ * Retry options describe the job's retry policy. Inline dispatchers run the
+ * policy in-process with real delays; durable providers map the policy onto
+ * their own runtime and reject options they cannot honor.
  */
 export function createJobs<Ctx>(): Jobs<Ctx> {
   return {

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";
@@ -311,9 +313,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.
    */
@@ -677,7 +683,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 +715,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 {
@@ -740,7 +765,10 @@ export function createMemoryOutbox(): MemoryOutboxPort {
     },
 
     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 +778,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 +796,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 +810,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 +824,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 +1046,22 @@ 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);
+    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,