@beignet/core 0.0.51 → 0.0.53

package/src/events/transport.ts

@@ -0,0 +1,242 @@
+/** Canonical JSON value that can cross an event transport boundary. */
+export type EventTransportValue =
+  | null
+  | string
+  | number
+  | boolean
+  | readonly EventTransportValue[]
+  | { readonly [key: string]: EventTransportValue };
+
+/** Why an event payload cannot safely cross a serialized transport. */
+export type EventTransportErrorReason = "not-json-safe" | "not-stable";
+
+/** Error thrown when an event payload cannot survive canonical JSON transport. */
+export class EventTransportError extends Error {
+  /** Stable event name. */
+  readonly eventName: string;
+  /** Whether the value is not JSON-safe or changes under repeated parsing. */
+  readonly reason: EventTransportErrorReason;
+  /** Payload path associated with a JSON-safety failure. */
+  readonly path?: string;
+
+  constructor(args: {
+    eventName: string;
+    reason: EventTransportErrorReason;
+    message: string;
+    path?: string;
+    cause?: unknown;
+  }) {
+    super(`Event "${args.eventName}" payload ${args.message}`, {
+      cause: args.cause,
+    });
+    this.name = "EventTransportError";
+    this.eventName = args.eventName;
+    this.reason = args.reason;
+    this.path = args.path;
+  }
+}
+
+function childTransportPath(path: string, key: string): string {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key)
+    ? `${path}.${key}`
+    : `${path}[${JSON.stringify(key)}]`;
+}
+
+function throwJsonSafetyError(args: {
+  eventName: string;
+  path: string;
+  message: string;
+}): never {
+  throw new EventTransportError({
+    eventName: args.eventName,
+    reason: "not-json-safe",
+    path: args.path,
+    message: `is not transport-safe at ${args.path}: ${args.message}`,
+  });
+}
+
+export function toEventTransportValue(
+  eventName: string,
+  value: unknown,
+  path = "payload",
+  seen: WeakSet<object> = new WeakSet(),
+): EventTransportValue {
+  if (value === null) return null;
+
+  if (typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      return throwJsonSafetyError({
+        eventName,
+        path,
+        message: "numbers must be finite.",
+      });
+    }
+    return Object.is(value, -0) ? 0 : value;
+  }
+
+  if (typeof value !== "object") {
+    return throwJsonSafetyError({
+      eventName,
+      path,
+      message: `received ${typeof value}; use null, strings, finite numbers, booleans, arrays, or plain objects.`,
+    });
+  }
+
+  try {
+    if (value instanceof Date) {
+      return throwJsonSafetyError({
+        eventName,
+        path,
+        message: "Date values are not supported; use an ISO string or number.",
+      });
+    }
+
+    if (seen.has(value)) {
+      return throwJsonSafetyError({
+        eventName,
+        path,
+        message: "circular references are not supported.",
+      });
+    }
+
+    seen.add(value);
+    if (Array.isArray(value)) {
+      const output: EventTransportValue[] = [];
+      const ownKeys = Reflect.ownKeys(value);
+      const hasUnsupportedKey = ownKeys.some((key) => {
+        if (key === "length") return false;
+        if (typeof key !== "string") return true;
+        const index = Number(key);
+        return (
+          !Number.isInteger(index) ||
+          index < 0 ||
+          index >= value.length ||
+          String(index) !== key
+        );
+      });
+      if (hasUnsupportedKey) {
+        return throwJsonSafetyError({
+          eventName,
+          path,
+          message: "arrays cannot contain symbol or custom properties.",
+        });
+      }
+      if (ownKeys.length !== value.length + 1) {
+        return throwJsonSafetyError({
+          eventName,
+          path,
+          message: "sparse arrays are not supported.",
+        });
+      }
+      for (let index = 0; index < value.length; index += 1) {
+        const key = String(index);
+        const itemPath = `${path}[${index}]`;
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor) {
+          return throwJsonSafetyError({
+            eventName,
+            path: itemPath,
+            message: "sparse arrays are not supported.",
+          });
+        }
+        if (!("value" in descriptor) || !descriptor.enumerable) {
+          return throwJsonSafetyError({
+            eventName,
+            path: itemPath,
+            message: "array items must be enumerable data properties.",
+          });
+        }
+        output.push(
+          toEventTransportValue(eventName, descriptor.value, itemPath, seen),
+        );
+      }
+      return output;
+    }
+
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      return throwJsonSafetyError({
+        eventName,
+        path,
+        message: "objects must be plain objects.",
+      });
+    }
+
+    const output = {} as Record<string, EventTransportValue>;
+    for (const key of Reflect.ownKeys(value)) {
+      if (typeof key !== "string") {
+        return throwJsonSafetyError({
+          eventName,
+          path,
+          message: "symbol properties are not supported.",
+        });
+      }
+      const propertyPath = childTransportPath(path, key);
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) {
+        return throwJsonSafetyError({
+          eventName,
+          path: propertyPath,
+          message: "properties must be enumerable data properties.",
+        });
+      }
+      Object.defineProperty(output, key, {
+        configurable: true,
+        enumerable: true,
+        writable: true,
+        value: toEventTransportValue(
+          eventName,
+          descriptor.value,
+          propertyPath,
+          seen,
+        ),
+      });
+    }
+    return output;
+  } catch (error) {
+    if (error instanceof EventTransportError) throw error;
+    throw new EventTransportError({
+      eventName,
+      reason: "not-json-safe",
+      path,
+      message: `could not be inspected as transport data at ${path}.`,
+      cause: error,
+    });
+  } finally {
+    seen.delete(value);
+  }
+}
+
+export function eventTransportValuesEqual(
+  left: EventTransportValue,
+  right: EventTransportValue,
+): boolean {
+  if (left === right) return true;
+  if (left === null || right === null || typeof left !== typeof right) {
+    return false;
+  }
+  if (Array.isArray(left) || Array.isArray(right)) {
+    if (!Array.isArray(left) || !Array.isArray(right)) return false;
+    return (
+      left.length === right.length &&
+      left.every((value, index) =>
+        eventTransportValuesEqual(value, right[index]),
+      )
+    );
+  }
+  if (typeof left !== "object" || typeof right !== "object") return false;
+
+  const leftRecord = left as Readonly<Record<string, EventTransportValue>>;
+  const rightRecord = right as Readonly<Record<string, EventTransportValue>>;
+  const leftKeys = Object.keys(leftRecord).sort();
+  const rightKeys = Object.keys(rightRecord).sort();
+  return (
+    leftKeys.length === rightKeys.length &&
+    leftKeys.every(
+      (key, index) =>
+        key === rightKeys[index] &&
+        eventTransportValuesEqual(leftRecord[key], rightRecord[key]),
+    )
+  );
+}

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/request-executor.ts

@@ -83,6 +83,7 @@ import {
 } from "./route-matching.js";
 import type { TrustedRequestInfo } from "./trusted-proxy.js";
 import { InvalidRequestUrlError } from "./trusted-proxy-internal.js";
+import { UseCaseRouteInputValidationError } from "./use-case-route.js";
 
 function withoutHeadResponseBody(
   response: HttpResponse,
@@ -282,6 +283,24 @@ export function createRequestExecutor<
         };
       }
 
+      if (currentError instanceof UseCaseRouteInputValidationError) {
+        return {
+          ctx,
+          response: errorResponse(
+            500,
+            currentError.code,
+            currentError.message,
+            {
+              contractName: currentError.contractName,
+              useCaseName: currentError.useCaseName,
+              location: "useCaseInput",
+            },
+          ),
+          error: currentError,
+          owner: "framework",
+        };
+      }
+
       if (currentError instanceof InvalidRequestUrlError) {
         return {
           ctx,