@beignet/core 0.0.51 → 0.0.52

package/src/openapi/index.ts

@@ -436,20 +436,58 @@ export function contractsToOpenAPI(
     ],
   };
   const operationIds = new Map<string, string>();
+  const operations = new Map<
+    string,
+    { readonly contractName: string; readonly route: string }
+  >();
+  const pathShapes = new Map<
+    string,
+    {
+      readonly contractName: string;
+      readonly pathKey: string;
+      readonly route: string;
+    }
+  >();
 
   for (const contract of contracts) {
     const config = resolveContract(contract);
     assertValidContractLifecycle(config);
+    const pathTemplate = parsePathTemplate(config.path);
+    const pathKey = pathTemplate.openApiPath;
+    const route = `${config.method.toUpperCase()} ${config.path}`;
+    const operationRoute = `${config.method.toUpperCase()} ${pathKey}`;
+    const conflictingOperation = operations.get(operationRoute);
+    if (conflictingOperation) {
+      throw new Error(
+        `Duplicate OpenAPI operation: ${operationRoute} is produced by both contract "${conflictingOperation.contractName}" (${conflictingOperation.route}) and contract "${config.name}" (${route}). Each method + normalized path combination must be unique within an OpenAPI document.`,
+      );
+    }
+    const conflictingPathShape = pathShapes.get(pathTemplate.shapeKey);
+    if (conflictingPathShape && conflictingPathShape.pathKey !== pathKey) {
+      throw new Error(
+        `Ambiguous OpenAPI path: ${pathKey} from contract "${config.name}" (${route}) conflicts with ${conflictingPathShape.pathKey} from contract "${conflictingPathShape.contractName}" (${conflictingPathShape.route}). Templated paths with the same hierarchy must use the same parameter names within an OpenAPI document.`,
+      );
+    }
     const operationId = getContractOperationId(config);
-    const route = `${config.method} ${config.path}`;
     const conflictingRoute = operationIds.get(operationId);
     if (conflictingRoute) {
       throw new Error(
         `Duplicate OpenAPI operationId: "${operationId}" is used by both ${conflictingRoute} and ${route}. Operation IDs must be unique within an OpenAPI document.`,
       );
     }
+    operations.set(operationRoute, {
+      contractName: config.name,
+      route,
+    });
+    if (!conflictingPathShape) {
+      pathShapes.set(pathTemplate.shapeKey, {
+        contractName: config.name,
+        pathKey,
+        route,
+      });
+    }
     operationIds.set(operationId, route);
-    addContractToPaths(config, paths, state);
+    addContractToPaths(config, pathKey, paths, state);
   }
 
   const openapi: OpenAPIObject = {
@@ -481,10 +519,10 @@ export function contractsToOpenAPI(
  */
 function addContractToPaths(
   contract: AnyContract,
+  pathKey: string,
   paths: PathsObject,
   state: GeneratorState,
 ): void {
-  const pathKey = parsePathTemplate(contract.path).openApiPath;
   if (!paths[pathKey]) {
     paths[pathKey] = {};
   }

package/src/outbox/index.ts

@@ -8,13 +8,10 @@
 import {
   type EventPayloadDef,
   type EventPublishOptions,
+  type EventTransportValue,
   type InferEventPayload,
-  parseEventPayload,
+  prepareEventPayloadForTransport,
 } from "../events/index.js";
-import {
-  isEventPayloadParsed,
-  markEventPayloadParsed,
-} from "../events/payload-state.js";
 import {
   getJobRetryDelayMs,
   getJobRetryMaxAttempts,
@@ -1508,14 +1505,19 @@ export async function enqueueEvent<E extends EventPayloadDef>(
   payload: InferEventPayload<E>,
   options: EnqueueTypedOutboxOptions = {},
 ): Promise<OutboxMessage> {
-  const parsed = await parseEventPayload(event, payload);
-  return await enqueueParsedEvent(outbox, event, parsed, options);
+  const prepared = await prepareEventPayloadForTransport(event, payload);
+  return await enqueueTransportEvent(
+    outbox,
+    event,
+    prepared.transportValue,
+    options,
+  );
 }
 
-async function enqueueParsedEvent<E extends EventPayloadDef>(
+async function enqueueTransportEvent<E extends EventPayloadDef>(
   outbox: OutboxPort,
   event: E,
-  payload: InferEventPayload<E>,
+  payload: EventTransportValue,
   options: EnqueueTypedOutboxOptions,
 ): Promise<OutboxMessage> {
   const trace =
@@ -1524,7 +1526,7 @@ async function enqueueParsedEvent<E extends EventPayloadDef>(
     id: options.id,
     kind: "event",
     name: event.name,
-    payload: toOutboxJsonValue(payload),
+    payload,
     trace,
     availableAt: options.availableAt,
     maxAttempts: options.maxAttempts,
@@ -1563,12 +1565,14 @@ export function createOutboxEventRecorder(
 ): DomainEventRecorderPort {
   return {
     async record(event, payload, publishOptions) {
-      const parsed = isEventPayloadParsed(publishOptions)
-        ? payload
-        : await parseEventPayload(event, payload);
-      await enqueueParsedEvent(outbox, event, parsed, {
+      const prepared = await prepareEventPayloadForTransport(
+        event,
+        payload,
+        publishOptions,
+      );
+      await enqueueTransportEvent(outbox, event, prepared.transportValue, {
         ...options,
-        trace: publishOptions?.trace ?? options.trace,
+        trace: prepared.publishOptions.trace ?? options.trace,
       });
     },
   };
@@ -1673,11 +1677,15 @@ async function deliverOutboxMessage(
       );
     }
 
-    const payload = await parseEventPayload(event, message.payload);
+    const prepared = await prepareEventPayloadForTransport(
+      event,
+      message.payload,
+      trace ? { trace } : undefined,
+    );
     await options.eventBus.publish(
       event,
-      payload,
-      markEventPayloadParsed(trace ? { trace } : undefined),
+      prepared.payload,
+      prepared.publishOptions,
     );
     return;
   }

package/src/ports/events.ts

@@ -53,7 +53,10 @@ export type InferJobPayload<J extends JobDef> = InferContractJobPayload<J>;
  * An EventBus port for publishing and subscribing to domain events.
  *
  * This interface defines a framework-agnostic contract for event-driven
- * communication within your application.
+ * communication within your application. Implementations must prepare
+ * producer payloads with `prepareEventPayloadForTransport(...)` from
+ * `@beignet/core/events` so direct publication and provider swaps preserve the
+ * same canonical JSON semantics.
  *
  * @example
  * ```ts

package/src/ports/storage.ts

@@ -82,6 +82,13 @@ export interface StorageObjectBody extends StorageObject {
    * buffering them.
    */
   readonly bodyUsed: boolean;
+  /**
+   * Discard an unread body and release any resources held by its provider.
+   *
+   * Calling this after consumption has started is a no-op. Callers that only
+   * inspect object metadata should cancel the body in a `finally` block.
+   */
+  cancel(reason?: unknown): Promise<void>;
   /**
    * Consume the object as a readable byte stream.
    */
@@ -376,6 +383,9 @@ function createObjectBody(entry: MemoryStorageEntry): StorageObjectBody {
     get bodyUsed() {
       return bodyUsed;
     },
+    async cancel() {
+      if (!bodyUsed) bodyUsed = true;
+    },
     stream() {
       return bytesToStream(consumeBytes());
     },

package/src/ports/testing.ts

@@ -1,3 +1,4 @@
+import { prepareEventPayloadForTransport } from "../events/index.js";
 import type {
   MemoryIdempotencyEntry,
   MemoryIdempotencyStore,
@@ -81,8 +82,9 @@ export interface RecordedEventExpectation {
 /**
  * Create a recording event bus for testing.
  *
- * This bus records all published events for later assertion,
- * but does not support subscription (throws if called).
+ * This bus validates canonical transport output and records published events
+ * asynchronously for later assertion. Await `publish(...)` before reading the
+ * captured log. Subscription is not supported and throws when called.
  *
  * @example
  * ```ts
@@ -104,8 +106,13 @@ export function createRecordingEventBus(): {
   const events: RecordedEvent[] = [];
 
   const bus: EventBusPort = {
-    publish(event, payload) {
-      events.push({ name: event.name, payload });
+    async publish(event, payload, options) {
+      const prepared = await prepareEventPayloadForTransport(
+        event,
+        payload,
+        options,
+      );
+      events.push({ name: event.name, payload: prepared.payload });
     },
     subscribe() {
       throw new Error("Not implemented for recording bus");

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

@@ -1,11 +1,8 @@
 import {
   type EventPublishOptions,
-  parseEventPayload,
+  prepareEventPayloadForTransport,
 } from "../events/index.js";
-import {
-  isEventPayloadParsed,
-  markEventPayloadParsed,
-} from "../events/payload-state.js";
+import { isEventPayloadParsed } from "../events/payload-state.js";
 import type {
   DomainEventDef,
   EventBusPort,
@@ -93,8 +90,8 @@ export interface RecordedDomainEvent {
    */
   readonly eventName: string;
   /**
-   * Recorded payload. Use-case helpers store parsed schema output; direct
-   * recorder calls are validated when the buffer is flushed.
+   * Recorded payload. Use-case helpers store canonical transport-stable schema
+   * output; direct recorder calls are validated when the buffer is flushed.
    */
   readonly payload: unknown;
   /** Optional metadata propagated when the event is flushed. */
@@ -132,8 +129,8 @@ export interface BufferedDomainEventRecorder extends DomainEventRecorderPort {
    */
   clear(): void;
   /**
-   * Publish recorded events in FIFO order, validating entries recorded
-   * directly without the use-case event helper.
+   * Publish recorded events in FIFO order, proving transport stability for
+   * entries recorded directly without the use-case event helper.
    */
   flush(eventBus: EventBusPort): Promise<void>;
 }
@@ -229,7 +226,10 @@ export function createObservedUnitOfWork<TxPorts>(
  */
 export function createDomainEventRecorder(): BufferedDomainEventRecorder {
   const records: RecordedDomainEvent[] = [];
-  const parsedRecords = new WeakSet<RecordedDomainEvent>();
+  const validationOptions = new WeakMap<
+    RecordedDomainEvent,
+    EventPublishOptions
+  >();
 
   return {
     record(event, payload, options) {
@@ -239,7 +239,9 @@ export function createDomainEventRecorder(): BufferedDomainEventRecorder {
         payload,
         ...(options?.trace ? { options: { trace: options.trace } } : {}),
       };
-      if (isEventPayloadParsed(options)) parsedRecords.add(record);
+      if (isEventPayloadParsed(event, payload, options) && options) {
+        validationOptions.set(record, { ...options });
+      }
       records.push(record);
     },
 
@@ -257,13 +259,15 @@ export function createDomainEventRecorder(): BufferedDomainEventRecorder {
     async flush(eventBus) {
       while (records.length > 0) {
         const record = records[0];
-        const payload = parsedRecords.has(record)
-          ? record.payload
-          : await parseEventPayload(record.event, record.payload);
+        const prepared = await prepareEventPayloadForTransport(
+          record.event,
+          record.payload,
+          validationOptions.get(record) ?? record.options,
+        );
         await eventBus.publish(
           record.event,
-          payload as never,
-          markEventPayloadParsed(record.options),
+          prepared.payload as never,
+          prepared.publishOptions,
         );
         records.shift();
       }

package/src/search/index.ts

@@ -435,10 +435,10 @@ function instrumentSearch(
       instrumentation.custom({
         name: "search.query",
         label: "Search query",
-        summary: `${index.name}: ${result.query}`,
+        summary: `${index.name}: ${result.hits.length} hits`,
         details: {
           index: index.name,
-          query: result.query,
+          queryLength: result.query.length,
           hits: result.hits.length,
           total: result.page.total,
           durationMs: Date.now() - startedAt,

package/src/server/instrumentation.ts

@@ -61,8 +61,8 @@ export interface ServerInstrumentationOptions<Ctx = unknown> {
   traceContextHeader?: string | false;
 
   /**
-   * Request path prefixes that should not enter ambient correlation or record
-   * events. Response headers are still written.
+   * Request path prefixes that should not record instrumentation events.
+   * Ambient correlation still runs, and enabled response headers are written.
    *
    * Defaults to the devtools dashboard prefix so its polling traffic does not
    * fill the event timeline.
@@ -125,10 +125,10 @@ export interface ServerInstrumentationRuntime<Ctx> {
    */
   createServiceCorrelation(): RequestCorrelation;
   /**
-   * Pipeline hook installed before user hooks, when instrumentation is
-   * enabled.
+   * Pipeline hook installed before user hooks. It always owns ambient
+   * correlation; response headers and event recording remain configurable.
    */
-  hook?: ServerHook<Ctx, AnyPorts>;
+  hook: ServerHook<Ctx, AnyPorts>;
 }
 
 type TraceContextFields = {
@@ -350,7 +350,6 @@ export function createServerInstrumentation<Ctx>(
     req: HttpRequestLike;
     ctx?: unknown;
   }) => {
-    if (isIgnoredPath(getPathname(args.req), ignorePaths)) return;
     const trace = resolveTraceContext(args);
     enterActiveRequestContext({
       requestId: resolveRequestId(args),
@@ -377,7 +376,10 @@ export function createServerInstrumentation<Ctx>(
       return undefined;
     },
     beforeSend: ({ req, ctx, response }) => {
-      if (requestIdHeader === false && traceContextHeader === false) {
+      if (
+        !enabled ||
+        (requestIdHeader === false && traceContextHeader === false)
+      ) {
         return undefined;
       }
 
@@ -502,6 +504,6 @@ export function createServerInstrumentation<Ctx>(
       requestId: createRequestId(),
       trace: tracing?.current() ?? createTraceContext(),
     }),
-    hook: enabled ? hook : undefined,
+    hook,
   };
 }

package/src/server/response-finalization.ts

@@ -312,18 +312,18 @@ function getDeclaredCatalogErrorsForStatus(
   );
 }
 
-async function validateCatalogErrorResponse<C extends HttpContractConfig>(
+async function parseCatalogErrorResponse<C extends HttpContractConfig>(
   contract: C,
   res: HttpResponseLike,
-): Promise<void> {
+): Promise<HttpResponseLike> {
   const body = res.body;
-  if (res.status < 400 || !isErrorResponseBody(body)) return;
+  if (res.status < 400 || !isErrorResponseBody(body)) return res;
 
   const declaredErrors = getDeclaredCatalogErrorsForStatus(
     contract,
     res.status,
   );
-  if (declaredErrors.length === 0) return;
+  if (declaredErrors.length === 0) return res;
 
   const matchingError = declaredErrors.find(
     (error) => error.code === body.code,
@@ -346,7 +346,18 @@ async function validateCatalogErrorResponse<C extends HttpContractConfig>(
 
   if (matchingError.details && body.details !== undefined) {
     try {
-      await parseStandardSchema(matchingError.details, body.details);
+      const parsedDetails = await parseStandardSchema(
+        matchingError.details,
+        body.details,
+      );
+      const { details: _details, ...bodyWithoutDetails } = body;
+      return {
+        ...res,
+        body:
+          parsedDetails === undefined
+            ? bodyWithoutDetails
+            : { ...bodyWithoutDetails, details: parsedDetails },
+      };
     } catch (error) {
       if (error instanceof SchemaValidationError) {
         throw new ResponseContractViolationError({
@@ -360,18 +371,20 @@ async function validateCatalogErrorResponse<C extends HttpContractConfig>(
       throw error;
     }
   }
+
+  return res;
 }
 
-async function validateResponseAgainstContract<C extends HttpContractConfig>(
+async function parseResponseAgainstContract<C extends HttpContractConfig>(
   contract: C,
   res: HttpResponseLike,
   responseValidationExemptStatus?: number,
-): Promise<void> {
+): Promise<HttpResponseLike> {
   const statusKey = String(res.status);
   const hasDeclaredStatus = Object.hasOwn(contract.responses, statusKey);
 
   if (!hasDeclaredStatus) {
-    if (Object.keys(contract.responses).length === 0) return;
+    if (Object.keys(contract.responses).length === 0) return res;
 
     throw new ResponseContractViolationError({
       code: "UNDECLARED_RESPONSE_STATUS",
@@ -400,19 +413,22 @@ async function validateResponseAgainstContract<C extends HttpContractConfig>(
         }),
       });
     }
-    return;
+    return res;
   }
 
-  if (!responseSchema) return;
+  if (!responseSchema) return res;
 
   // Binder routes whose use case output schema is the same object as the
   // declared success response schema skip the redundant success-status parse.
   // Error statuses and undeclared statuses are validated unchanged.
-  if (res.status === responseValidationExemptStatus) return;
+  if (res.status === responseValidationExemptStatus) return res;
 
   try {
-    await parseStandardSchema(responseSchema, res.body);
-    await validateCatalogErrorResponse(contract, res);
+    const parsed = {
+      ...res,
+      body: await parseStandardSchema(responseSchema, res.body),
+    };
+    return await parseCatalogErrorResponse(contract, parsed);
   } catch (error) {
     if (error instanceof SchemaValidationError) {
       throw new ResponseContractViolationError({
@@ -463,7 +479,7 @@ export async function finalizeResponse<C extends HttpContractConfig>(
   const normalized = normalizeResponse(res);
   validateHttpResponseSemantics(contract, normalized);
   if (options.validateContract ?? true) {
-    await validateResponseAgainstContract(
+    return parseResponseAgainstContract(
       contract,
       normalized,
       responseValidationExemptStatus,
@@ -490,6 +506,8 @@ export function defaultErrorResponse(
   ctx?: unknown,
 ): HttpResponseLike {
   const requestId = getRequestIdFromContext(ctx);
+  const exposeErrorDetails =
+    process.env.NODE_ENV === "development" || process.env.NODE_ENV === "test";
   return {
     status: 500,
     body: createErrorResponseBody({
@@ -497,7 +515,7 @@ export function defaultErrorResponse(
       message: "Internal server error",
       requestId,
       details:
-        process.env.NODE_ENV !== "production" && err instanceof Error
+        exposeErrorDetails && err instanceof Error
           ? {
               error: {
                 message: err.message,

package/src/server/server.ts

@@ -204,15 +204,18 @@ export type CreateServerOptions<
    * `ports.devtools`) when one is installed.
    *
    * Pass `false` to disable headers and event recording. Context factories
-   * still receive `requestId` and `trace` arguments.
+   * still receive `requestId` and `trace` arguments, and request-scoped
+   * correlation remains available to ambient audit wrappers.
    */
   instrumentation?: ServerInstrumentationOptions<Ctx> | false;
   /**
-   * Whether route-owned responses are validated against the contract's
-   * declared statuses and response schemas before they are sent.
+   * Whether route-owned responses are parsed against the contract's declared
+   * statuses and response schemas before they are sent. The parsed schema
+   * output becomes the response body.
    *
-   * Disable this to trade response guarantees for throughput, mirroring the
-   * client-side `validateResponses` option.
+   * Disable this to send route-owned handler bodies as-is without validation,
+   * unknown-key stripping, or transforms, mirroring the client-side
+   * `validateResponses` option.
    *
    * @default true
    */
@@ -407,9 +410,7 @@ export async function createServer<
     options.instrumentation,
   );
   const hooks = [
-    ...(instrumentation.hook
-      ? [instrumentation.hook as ServerHook<Ctx, FinalPorts>]
-      : []),
+    instrumentation.hook as ServerHook<Ctx, FinalPorts>,
     ...((options.hooks ?? []) as ServerHook<Ctx, FinalPorts>[]),
   ];
   const contracts = options.routes ? contractsFromRoutes(options.routes) : [];

package/src/uploads/index.ts

@@ -968,29 +968,47 @@ export function createUploadRouter<Ctx>(
             },
           });
         }
-        const object = needsUploadBodyVerification(upload, file)
+        const verifyBody = needsUploadBodyVerification(upload, file);
+        const objectBody = verifyBody
           ? await options.storage.get(file.key)
+          : null;
+        const object = verifyBody
+          ? objectBody
           : await options.storage.stat(file.key);
         if (!object) {
           throw new UploadObjectNotFoundError({
             message: `Uploaded object "${file.key}" was not found.`,
           });
         }
-        assertStoredObject(upload, file, object);
-        const verified = await verifyStoredUploadFile(upload, file, object);
-        const completedObject = storageObjectMetadata(object);
-        const completedFile = {
-          ...file,
-          ...(verified.checksum ? { checksum: verified.checksum } : {}),
-          object: completedObject,
-        };
-        await assertVerifiedFile(upload, {
-          ctx,
-          metadata,
-          file: completedFile,
-          storage: options.storage,
-        });
-        files.push(completedFile);
+        let operationFailed = false;
+        try {
+          assertStoredObject(upload, file, object);
+          const verified = await verifyStoredUploadFile(upload, file, object);
+          const completedObject = storageObjectMetadata(object);
+          const completedFile = {
+            ...file,
+            ...(verified.checksum ? { checksum: verified.checksum } : {}),
+            object: completedObject,
+          };
+          await assertVerifiedFile(upload, {
+            ctx,
+            metadata,
+            file: completedFile,
+            storage: options.storage,
+          });
+          files.push(completedFile);
+        } catch (error) {
+          operationFailed = true;
+          throw error;
+        } finally {
+          if (objectBody && !objectBody.bodyUsed) {
+            if (operationFailed) {
+              await objectBody.cancel().catch(() => undefined);
+            } else {
+              await objectBody.cancel();
+            }
+          }
+        }
       }
 
       const result = await upload.onComplete?.({ ctx, metadata, files });