@beignet/core 0.0.44 → 0.0.45

package/src/application/index.ts

@@ -301,21 +301,13 @@ function createUseCaseEventHelpers<Emits extends readonly DomainEventLike[]>(
     assertDeclared,
     async record(recorder, event, payload) {
       const declaredEvent = resolveDeclared(event) as typeof event;
-      const parsed = await parseEventPayload(
-        declaredEvent,
-        payload,
-        useCaseName,
-      );
-      await recorder.record(declaredEvent, parsed);
+      await parseEventPayload(declaredEvent, payload, useCaseName);
+      await recorder.record(declaredEvent, payload);
     },
     async publish(eventBus, event, payload) {
       const declaredEvent = resolveDeclared(event) as typeof event;
-      const parsed = await parseEventPayload(
-        declaredEvent,
-        payload,
-        useCaseName,
-      );
-      await eventBus.publish(declaredEvent, parsed);
+      await parseEventPayload(declaredEvent, payload, useCaseName);
+      await eventBus.publish(declaredEvent, payload);
     },
   };
 }
@@ -340,6 +332,8 @@ export const USE_CASE_TRUSTED_RUN: unique symbol = Symbol.for(
   "beignet.useCase.trustedRun",
 );
 
+const USE_CASE_OUTPUT_VALIDATED = Symbol.for("beignet.useCase.outputValidated");
+
 /**
  * Finalized use case definition.
  *
@@ -849,6 +843,10 @@ class UseCaseBuilder<
       value: (args: RunArgs) => execute(args, false),
       enumerable: false,
     });
+    Object.defineProperty(def, USE_CASE_OUTPUT_VALIDATED, {
+      value: validation.output,
+      enumerable: false,
+    });
 
     return def as unknown as InputSchema extends StandardSchemaV1
       ? OutputSchema extends StandardSchemaV1

package/src/client/client.ts

@@ -377,6 +377,16 @@ function formatQuotedList(values: string[]): string {
   return values.map((value) => `"${value}"`).join(", ");
 }
 
+class MalformedResponseJsonError extends Error {
+  readonly parseError: unknown;
+
+  constructor(parseError: unknown) {
+    super("Response body contains malformed JSON.");
+    this.name = "MalformedResponseJsonError";
+    this.parseError = parseError;
+  }
+}
+
 /**
  * Generate an idempotency key. Idempotency keys only need to be unique per
  * request, not cryptographically strong, so this degrades gracefully when
@@ -615,6 +625,9 @@ export class Endpoint<
       TContract,
       TProvidedHeaders
     >;
+    let phase: "client" | "network" | "contract" = "client";
+    let response: Response | undefined;
+    let responseStatus: number | undefined;
 
     try {
       if (args.body !== undefined && args.rawBody !== undefined) {
@@ -714,7 +727,10 @@ export class Endpoint<
         options.body = requestBody;
       }
 
-      const response = await fetchFn(url, options);
+      phase = "network";
+      response = await fetchFn(url, options);
+      phase = "contract";
+      responseStatus = response.status;
       const shouldValidateResponses = this.config.validateResponses !== false;
 
       // Handle non-2xx responses
@@ -723,12 +739,15 @@ export class Endpoint<
         try {
           errorBody = await parseResponseBody(response);
         } catch (parseErr) {
+          if (!(parseErr instanceof MalformedResponseJsonError)) {
+            throw parseErr;
+          }
           // JSON parse failed — still report the HTTP error
           throw this.createError({
             status: response.status,
             code: "INVALID_JSON",
             message: createInvalidJsonMessage("error", response.status),
-            cause: parseErr,
+            cause: parseErr.parseError,
             response,
             source: "contract",
           });
@@ -759,11 +778,14 @@ export class Endpoint<
       try {
         data = await parseResponseBody(response);
       } catch (parseErr) {
+        if (!(parseErr instanceof MalformedResponseJsonError)) {
+          throw parseErr;
+        }
         throw this.createError({
           status: response.status,
           code: "INVALID_JSON",
           message: createInvalidJsonMessage("success", response.status),
-          cause: parseErr,
+          cause: parseErr.parseError,
           response,
           source: "contract",
         });
@@ -839,11 +861,25 @@ export class Endpoint<
           response: error.response,
         };
       }
+      const source = phase;
       const error = this.createError({
-        code: "NETWORK_ERROR",
-        message: err instanceof Error ? err.message : "Network request failed",
+        code:
+          source === "network"
+            ? "NETWORK_ERROR"
+            : source === "contract"
+              ? "RESPONSE_PROCESSING_ERROR"
+              : "CLIENT_ERROR",
+        message:
+          err instanceof Error
+            ? err.message
+            : source === "network"
+              ? "Network request failed"
+              : source === "contract"
+                ? "Response processing failed"
+                : "Client request preparation failed",
         cause: err,
-        source: "network",
+        source,
+        ...(source === "contract" ? { status: responseStatus, response } : {}),
       }) as InferEndpointContractError<TContract>;
       return {
         ok: false,
@@ -1074,14 +1110,18 @@ async function parseResponseBody(response: Response): Promise<unknown> {
     return undefined;
   }
 
-  const text = await response.text().catch(() => "");
+  const text = await response.text();
   if (text === "") {
     return undefined;
   }
 
   const contentType = response.headers.get("content-type");
   if (contentType?.includes("application/json")) {
-    return JSON.parse(text);
+    try {
+      return JSON.parse(text);
+    } catch (error) {
+      throw new MalformedResponseJsonError(error);
+    }
   }
 
   return text;

package/src/events/index.ts

@@ -315,8 +315,8 @@ export async function publishEvent<E extends EventPayloadDef>(
   payload: InferEventPayload<E>,
   options?: EventPublishOptions,
 ): Promise<void> {
-  const parsed = await parseEventPayload(event, payload);
-  await eventBus.publish(event, parsed, options);
+  await parseEventPayload(event, payload);
+  await eventBus.publish(event, payload, options);
 }
 
 /**

package/src/idempotency/index.ts

@@ -228,11 +228,17 @@ export interface IdempotencyPort {
 
   /**
    * Mark a reserved key as complete and store the result that may be replayed.
+   *
+   * Implementations must reject when the fingerprint, reservation token, or
+   * in-progress state no longer matches the current reservation.
    */
   complete(input: IdempotencyCompleteInput): Promise<void>;
 
   /**
    * Release or mark a reserved key after the protected work fails.
+   *
+   * Implementations must reject when the fingerprint, reservation token, or
+   * in-progress state no longer matches the current reservation.
    */
   fail(input: IdempotencyFailInput): Promise<void>;
 }
@@ -405,6 +411,38 @@ export class IdempotencyFingerprintError extends Error {
   }
 }
 
+/**
+ * Error thrown when a completion or failure mutation no longer owns the
+ * matching in-progress reservation.
+ */
+export class IdempotencyMutationError extends Error {
+  /** Mutation that failed to match the current reservation. */
+  readonly action: "complete" | "fail";
+  /** Operation namespace supplied to the failed mutation. */
+  readonly namespace: string;
+  /** Client-provided idempotency key supplied to the failed mutation. */
+  readonly key: string;
+  /** Normalized logical scope key supplied to the failed mutation. */
+  readonly scopeKey: string;
+
+  constructor(args: {
+    action: "complete" | "fail";
+    namespace: string;
+    key: string;
+    scope?: IdempotencyScope;
+  }) {
+    const scopeKey = normalizeIdempotencyScope(args.scope);
+    super(
+      `Idempotency ${args.action} for key "${args.key}" in namespace "${args.namespace}" matched no in-progress reservation with this fingerprint and reservation token. The reservation may be missing, expired, already completed or released, or owned by a different execution.`,
+    );
+    this.name = "IdempotencyMutationError";
+    this.action = args.action;
+    this.namespace = args.namespace;
+    this.key = args.key;
+    this.scopeKey = scopeKey;
+  }
+}
+
 type CanonicalValue =
   | null
   | string
@@ -557,9 +595,8 @@ export function createMemoryIdempotencyStore(
   options: MemoryIdempotencyStoreOptions = {},
 ): MemoryIdempotencyStore {
   const storeNow = options.now ?? (() => new Date());
-  const createReservationToken =
-    options.createReservationToken ?? createRandomReservationToken;
   const records = new Map<string, MemoryRecord>();
+  const pendingReservations = new Map<string, Promise<void>>();
 
   return {
     get entries() {
@@ -573,45 +610,71 @@ export function createMemoryIdempotencyStore(
       assertTtl(input.ttlSec);
       assertTtl(input.reservationTtlSec);
 
-      const now = storeNow();
       const storageKey = createIdempotencyStorageKey(input);
-      const existing = records.get(storageKey);
-
-      if (existing && !isExpired(existing, now)) {
-        return reservationFromRecord(existing, input.fingerprint);
-      }
-
-      if (existing) {
-        records.delete(storageKey);
+      while (true) {
+        const now = storeNow();
+        const existing = records.get(storageKey);
+
+        if (existing && !isExpired(existing, now)) {
+          return reservationFromRecord(existing, input.fingerprint);
+        }
+
+        if (existing) {
+          records.delete(storageKey);
+        }
+
+        const pendingReservation = pendingReservations.get(storageKey);
+        if (pendingReservation) {
+          await pendingReservation;
+          continue;
+        }
+
+        let releasePendingReservation!: () => void;
+        pendingReservations.set(
+          storageKey,
+          new Promise<void>((resolve) => {
+            releasePendingReservation = resolve;
+          }),
+        );
+
+        try {
+          const reservationToken =
+            options.createReservationToken?.() ??
+            (await createRandomReservationToken());
+          const reservedAt = storeNow();
+          const record: MemoryRecord = {
+            namespace: input.namespace,
+            key: input.key,
+            scopeKey: normalizeIdempotencyScope(input.scope),
+            fingerprint: input.fingerprint,
+            reservationToken,
+            replayTtlSec: input.ttlSec,
+            status: "in-progress",
+            reservedAt,
+            expiresAt: resolveExpiresAt(
+              input.reservationTtlSec ??
+                DEFAULT_IDEMPOTENCY_RESERVATION_TTL_SEC,
+              reservedAt,
+            ),
+          };
+
+          records.set(storageKey, record);
+
+          return {
+            status: "reserved",
+            namespace: record.namespace,
+            key: record.key,
+            scopeKey: record.scopeKey,
+            fingerprint: record.fingerprint,
+            reservationToken: record.reservationToken,
+            reservedAt: record.reservedAt,
+            expiresAt: record.expiresAt,
+          };
+        } finally {
+          pendingReservations.delete(storageKey);
+          releasePendingReservation();
+        }
       }
-
-      const record: MemoryRecord = {
-        namespace: input.namespace,
-        key: input.key,
-        scopeKey: normalizeIdempotencyScope(input.scope),
-        fingerprint: input.fingerprint,
-        reservationToken: createReservationToken(),
-        replayTtlSec: input.ttlSec,
-        status: "in-progress",
-        reservedAt: now,
-        expiresAt: resolveExpiresAt(
-          input.reservationTtlSec ?? DEFAULT_IDEMPOTENCY_RESERVATION_TTL_SEC,
-          now,
-        ),
-      };
-
-      records.set(storageKey, record);
-
-      return {
-        status: "reserved",
-        namespace: record.namespace,
-        key: record.key,
-        scopeKey: record.scopeKey,
-        fingerprint: record.fingerprint,
-        reservationToken: record.reservationToken,
-        reservedAt: record.reservedAt,
-        expiresAt: record.expiresAt,
-      };
     },
 
     async complete(input) {
@@ -628,7 +691,12 @@ export function createMemoryIdempotencyStore(
         existing.reservationToken !== input.reservationToken ||
         existing.status !== "in-progress"
       ) {
-        return;
+        throw new IdempotencyMutationError({
+          action: "complete",
+          namespace: input.namespace,
+          key: input.key,
+          scope: input.scope,
+        });
       }
 
       existing.status = "completed";
@@ -654,7 +722,12 @@ export function createMemoryIdempotencyStore(
         existing.reservationToken !== input.reservationToken ||
         existing.status === "completed"
       ) {
-        return;
+        throw new IdempotencyMutationError({
+          action: "fail",
+          namespace: input.namespace,
+          key: input.key,
+          scope: input.scope,
+        });
       }
 
       records.delete(storageKey);
@@ -706,14 +779,22 @@ export async function runIdempotently<Result>(
       try {
         result = await options.run();
       } catch (error) {
-        await idempotency.fail({
-          namespace: operation.namespace,
-          key: operation.key,
-          scope: operation.scope,
-          fingerprint: operation.fingerprint,
-          reservationToken: reservation.reservationToken,
-          error,
-        });
+        try {
+          await idempotency.fail({
+            namespace: operation.namespace,
+            key: operation.key,
+            scope: operation.scope,
+            fingerprint: operation.fingerprint,
+            reservationToken: reservation.reservationToken,
+            error,
+          });
+        } catch (settlementError) {
+          throw new AggregateError(
+            [error, settlementError],
+            "Idempotent operation failed and releasing its reservation also failed.",
+            { cause: error },
+          );
+        }
         throw error;
       }
 
@@ -736,20 +817,30 @@ export async function runIdempotently<Result>(
   }
 }
 
-function createRandomReservationToken(): string {
-  if (typeof globalThis.crypto?.randomUUID === "function") {
-    return globalThis.crypto.randomUUID();
+async function createRandomReservationToken(): Promise<string> {
+  const crypto = globalThis.crypto;
+  if (typeof crypto?.randomUUID === "function") {
+    return crypto.randomUUID();
   }
-
-  const bytes = new Uint8Array(16);
-  globalThis.crypto?.getRandomValues?.(bytes);
-  if (bytes.some((value) => value !== 0)) {
+  if (typeof crypto?.getRandomValues === "function") {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
     return Array.from(bytes, (value) =>
       value.toString(16).padStart(2, "0"),
     ).join("");
   }
 
-  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+  try {
+    const nodeCrypto = await import("node:crypto");
+    if (typeof nodeCrypto.randomUUID === "function") {
+      return nodeCrypto.randomUUID();
+    }
+    return nodeCrypto.randomBytes(16).toString("hex");
+  } catch {
+    throw new Error(
+      "Idempotency reservations require Web Crypto or Node.js crypto.",
+    );
+  }
 }
 
 function normalizeOmitPath(

package/src/jobs/index.ts

@@ -1640,7 +1640,7 @@ export function createUniqueJobDispatcher(
         keyPrefix: options.keyPrefix,
       });
       if (!unique) {
-        await options.jobs.dispatch(job, parsed, dispatchOptions);
+        await options.jobs.dispatch(job, payload, dispatchOptions);
         return;
       }
 
@@ -1666,7 +1666,7 @@ export function createUniqueJobDispatcher(
       }
 
       try {
-        await options.jobs.dispatch(job, parsed, dispatchOptions);
+        await options.jobs.dispatch(job, payload, dispatchOptions);
       } catch (error) {
         try {
           await result.lease.release();

package/src/notifications/index.ts

@@ -1216,7 +1216,7 @@ export function createQueuedNotificationDispatcher<Name extends string, Ctx>(
           await options.jobs.dispatch(options.deliveryJob, {
             notificationName: notification.name,
             channel,
-            payload: parsed,
+            payload,
             options: queuedSendOptions(sendOptions),
           });
           result = {

package/src/outbox/index.ts

@@ -1269,14 +1269,14 @@ export async function enqueueEvent<E extends EventPayloadDef>(
   payload: InferEventPayload<E>,
   options: EnqueueTypedOutboxOptions = {},
 ): Promise<OutboxMessage> {
-  const parsed = await parseEventPayload(event, payload);
+  await parseEventPayload(event, payload);
   const trace =
     parseTraceCarrier(options.trace) ?? captureTraceCarrier(options.tracing);
   return outbox.enqueue({
     id: options.id,
     kind: "event",
     name: event.name,
-    payload: toOutboxJsonValue(parsed),
+    payload: toOutboxJsonValue(payload),
     trace,
     availableAt: options.availableAt,
     maxAttempts: options.maxAttempts,
@@ -1292,14 +1292,14 @@ export async function enqueueJob<J extends JobDef>(
   payload: InferJobPayload<J>,
   options: EnqueueTypedOutboxOptions = {},
 ): Promise<OutboxMessage> {
-  const parsed = await parseJobPayload(job, payload);
+  await parseJobPayload(job, payload);
   const trace =
     parseTraceCarrier(options.trace) ?? captureTraceCarrier(options.tracing);
   return outbox.enqueue({
     id: options.id,
     kind: "job",
     name: job.name,
-    payload: toOutboxJsonValue(parsed),
+    payload: toOutboxJsonValue(payload),
     trace,
     availableAt: options.availableAt,
     maxAttempts: options.maxAttempts ?? getJobRetryMaxAttempts(job.retry),
@@ -1422,10 +1422,10 @@ async function deliverOutboxMessage(
       );
     }
 
-    const payload = await parseEventPayload(event, message.payload);
+    await parseEventPayload(event, message.payload);
     await options.eventBus.publish(
       event,
-      payload,
+      message.payload as never,
       trace ? { trace } : undefined,
     );
     return;
@@ -1444,7 +1444,7 @@ async function deliverOutboxMessage(
     );
   }
 
-  const payload = await parseJobPayload(job, message.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
@@ -1457,7 +1457,7 @@ async function deliverOutboxMessage(
     }
   )[SINGLE_ATTEMPT_DISPATCH];
   if (singleAttempt) {
-    await singleAttempt(job, payload, {
+    await singleAttempt(job, message.payload as never, {
       attempt: message.attempts,
       maxAttempts: message.maxAttempts,
       trace,
@@ -1465,7 +1465,11 @@ async function deliverOutboxMessage(
     return;
   }
 
-  await options.jobs.dispatch(job, payload, trace ? { trace } : undefined);
+  await options.jobs.dispatch(
+    job,
+    message.payload as never,
+    trace ? { trace } : undefined,
+  );
 }
 
 /**

package/src/ports/unit-of-work.ts

@@ -245,8 +245,12 @@ export function createDomainEventRecorder(): BufferedDomainEventRecorder {
     async flush(eventBus) {
       while (records.length > 0) {
         const record = records[0];
-        const payload = await parseEventPayload(record.event, record.payload);
-        await eventBus.publish(record.event, payload, record.options);
+        await parseEventPayload(record.event, record.payload);
+        await eventBus.publish(
+          record.event,
+          record.payload as never,
+          record.options,
+        );
         records.shift();
       }
     },

package/src/server/hooks/idempotency.ts

@@ -2,6 +2,10 @@
  * Idempotency hooks for @beignet/core/server
  */
 
+import {
+  type ErrorReporterPort,
+  tryReportException,
+} from "../../error-reporting/index.js";
 import { AppError, httpErrors } from "../../errors/index.js";
 import {
   createIdempotencyFingerprint,
@@ -35,6 +39,10 @@ export type IdempotencyPorts = {
   idempotency: IdempotencyPort;
 };
 
+type OptionalErrorReporterPorts = IdempotencyPorts & {
+  errorReporter?: ErrorReporterPort;
+};
+
 /**
  * Minimal context shape required for actor- and tenant-scoped idempotency.
  */
@@ -252,6 +260,7 @@ export function createIdempotencyHooks<Ctx extends CtxWithIdempotency>(
     },
     [responseFinalizerHook]: async ({
       req,
+      ctx,
       response,
       error,
       native,
@@ -292,14 +301,41 @@ export function createIdempotencyHooks<Ctx extends CtxWithIdempotency>(
 
       // Framework-owned responses, errors, non-2xx responses, and native
       // `Response` results release the reservation. Streams are not replayable.
-      await port.fail({
-        namespace,
-        key,
-        scope,
-        fingerprint,
-        reservationToken,
-        error,
-      });
+      try {
+        await port.fail({
+          namespace,
+          key,
+          scope,
+          fingerprint,
+          reservationToken,
+          error,
+        });
+      } catch (settlementError) {
+        if (error === undefined) {
+          throw settlementError;
+        }
+
+        await tryReportException({
+          reporter: ctx
+            ? (ctx.ports as OptionalErrorReporterPorts).errorReporter
+            : undefined,
+          error: settlementError,
+          reportOptions: {
+            level: "error",
+            mechanism: "beignet.idempotency.settlement",
+            handled: true,
+            tags: {
+              "idempotency.namespace": namespace,
+            },
+            contexts: {
+              idempotency: {
+                namespace,
+                key,
+              },
+            },
+          },
+        });
+      }
       return undefined;
     },
   };