@beignet/core 0.0.43 → 0.0.45

package/skills/app-architecture/SKILL.md

@@ -84,7 +84,7 @@ import { z } from "zod";
 import { errors } from "@/features/shared/errors";
 
 export const projectSchema = z.object({
-  id: z.string().uuid(),
+  id: z.uuid(),
   name: z.string().min(1),
 });
 
@@ -94,7 +94,7 @@ const projects = defineContractGroup()
 
 export const getProject = projects
   .get("/:id")
-  .pathParams(z.object({ id: z.string().uuid() }))
+  .pathParams(z.object({ id: z.uuid() }))
   .errors({ ProjectNotFound: errors.ProjectNotFound })
   .responses({ 200: projectSchema });
 ```
@@ -154,6 +154,12 @@ or outbox records must commit together.
 Do not import provider packages from contracts, use cases, routes, UI, or
 feature client modules.
 
+Prefer typed options objects for provider factories. Explicit first-party
+options override matching environment values. Treat injected SDK or database
+clients as caller-owned unless an option such as `closeOnStop: true` delegates
+shutdown to one provider instance, and preserve provider instrumentation when
+using a lower-level direct adapter.
+
 Tenant-owned repository methods should accept `TenantScope` instead of raw
 tenant IDs. Use cases derive it with `requireTenantScope(ctx)` or
 `createTenantScope(...)`; adapters unwrap it with `tenantScopeId(scope)` and
@@ -161,6 +167,11 @@ include that storage ID in read, write, update, and delete predicates.
 Provider-correlation lookups such as webhook customer IDs are not tenant
 authorization by themselves.
 
+Resolve request tenants only from membership-backed app state or provider
+claims that the app explicitly treats as authoritative and current. Keep that
+decision behind an app-owned resolver. Never turn caller-supplied tenant IDs or
+unverified session fields directly into `TenantContext`.
+
 ## Workflows
 
 Feature-owned workflow definitions belong under the feature:
@@ -262,6 +273,37 @@ messages or make `AppError.details` safe to export.
 Best-effort capture is bounded to one second by default. Tune `timeoutMs` when
 needed; use `false` only when reporting may intentionally block the boundary.
 
+## Runtime Safety
+
+- HTTP idempotency defaults to the current actor and includes the current
+  tenant when one exists. The default actor scope fails closed when the
+  required identity is missing. Use
+  `meta.scope: "global"` only for deliberately public operations whose callers
+  should share one key namespace.
+- Idempotency ports must reject `complete(...)` and `fail(...)` when the
+  fingerprint, reservation token, or in-progress state no longer matches.
+  Never silently drop a stale mutation: callers would mistake an unstored
+  result for a replayable one. The memory adapter throws
+  `IdempotencyMutationError`; Drizzle dialects expose corresponding
+  `Drizzle*IdempotencyMutationError` classes.
+- `formatMailAddress(...)` rejects carriage returns and line feeds before a
+  provider builds headers; providers still own complete email-syntax
+  validation. Mail providers make one vendor call, so put retryable delivery
+  behind jobs or the outbox.
+- Keep storage keys relative and reuse `assertValidStorageKey(...)`,
+  `normalizeStorageKeyPrefix(...)`, `prefixStorageKey(...)`, and
+  `createStoragePublicUrl(...)` from `@beignet/core/ports` in custom adapters.
+  Add provider-specific restrictions only after the shared validation.
+- Uploads are protected by default. Declare `authorize(...)` or deliberately
+  opt into `access: "public"`; server uploads authorize each file before
+  reading bytes for validation. Include actor, tenant, or resource ownership
+  in object keys.
+- Direct-upload completion is stateless, so make `onComplete(...)` idempotent
+  by upload ID or object key and use app-owned issuance state for single-use or
+  revocable grants. Before app-owned completion starts, a failed server batch
+  removes objects already written. After `onComplete(...)` starts, durable
+  references may exist and transaction or compensation belongs to the app.
+
 ## Validation
 
 After core app-architecture changes, run from the app root:

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();
       }
     },