@beignet/core 0.0.50 → 0.0.52

package/src/payments/index.ts

@@ -624,10 +624,6 @@ export function createMemoryPaymentsProvider(
 
   return createProvider({
     name,
-    metadata: {
-      ports: ["payments"],
-      watchers: ["payments"],
-    },
     setup({ ports }) {
       const instrumentation = createProviderInstrumentation(ports, {
         providerName: name,

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/index.ts

@@ -283,6 +283,7 @@ export type {
   ClaimedOutboxMessage,
   OutboxAdminPort,
   OutboxClaimBatchOptions,
+  OutboxClaimBatchResult,
   OutboxCountMessagesOptions,
   OutboxDeleteResult,
   OutboxEnqueueInput,
@@ -296,6 +297,8 @@ export type {
   OutboxPort,
   OutboxPruneDeliveredInput,
   OutboxPurgeDeadLetteredInput,
+  OutboxRenewClaimInput,
+  OutboxRenewClaimResult,
   OutboxRequeueMessageInput,
 } from "../outbox/index.js";
 /**

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");
@@ -953,6 +960,19 @@ export interface OutboxDrainResultExpectation {
    * Expected dead-lettered count.
    */
   deadLettered?: number;
+  /**
+   * Expected count of eligible messages dead-lettered after exhausting their
+   * claim attempt budget.
+   */
+  abandonedDeadLettered?: number;
+  /**
+   * Expected count of messages whose durable settlement remained unknown.
+   */
+  settlementFailed?: number;
+  /**
+   * Expected count of messages whose active claim could not be confirmed.
+   */
+  leaseLost?: number;
 }
 
 /**
@@ -2421,6 +2441,24 @@ function outboxDrainResultMatches(
   ) {
     return false;
   }
+  if (
+    expectation.abandonedDeadLettered !== undefined &&
+    result.abandonedDeadLettered !== expectation.abandonedDeadLettered
+  ) {
+    return false;
+  }
+  if (
+    expectation.settlementFailed !== undefined &&
+    result.settlementFailed !== expectation.settlementFailed
+  ) {
+    return false;
+  }
+  if (
+    expectation.leaseLost !== undefined &&
+    result.leaseLost !== expectation.leaseLost
+  ) {
+    return false;
+  }
 
   return true;
 }

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

@@ -1,7 +1,8 @@
 import {
   type EventPublishOptions,
-  parseEventPayload,
+  prepareEventPayloadForTransport,
 } from "../events/index.js";
+import { isEventPayloadParsed } from "../events/payload-state.js";
 import type {
   DomainEventDef,
   EventBusPort,
@@ -83,17 +84,18 @@ export interface RecordedDomainEvent {
   /**
    * Event definition used to validate the payload before publishing.
    */
-  event: DomainEventDef;
+  readonly event: DomainEventDef;
   /**
    * Stable event name.
    */
-  eventName: string;
+  readonly eventName: string;
   /**
-   * Unparsed payload recorded during the transaction.
+   * Recorded payload. Use-case helpers store canonical transport-stable schema
+   * output; direct recorder calls are validated when the buffer is flushed.
    */
-  payload: unknown;
+  readonly payload: unknown;
   /** Optional metadata propagated when the event is flushed. */
-  options?: EventPublishOptions;
+  readonly options?: EventPublishOptions;
 }
 
 /**
@@ -119,7 +121,7 @@ export interface DomainEventRecorderPort {
  */
 export interface BufferedDomainEventRecorder extends DomainEventRecorderPort {
   /**
-   * Return recorded events without clearing them.
+   * Return a snapshot of recorded events without clearing them.
    */
   entries(): readonly RecordedDomainEvent[];
   /**
@@ -127,7 +129,8 @@ export interface BufferedDomainEventRecorder extends DomainEventRecorderPort {
    */
   clear(): void;
   /**
-   * Validate and publish all recorded events to an event bus in FIFO order.
+   * Publish recorded events in FIFO order, proving transport stability for
+   * entries recorded directly without the use-case event helper.
    */
   flush(eventBus: EventBusPort): Promise<void>;
 }
@@ -223,19 +226,30 @@ export function createObservedUnitOfWork<TxPorts>(
  */
 export function createDomainEventRecorder(): BufferedDomainEventRecorder {
   const records: RecordedDomainEvent[] = [];
+  const validationOptions = new WeakMap<
+    RecordedDomainEvent,
+    EventPublishOptions
+  >();
 
   return {
     record(event, payload, options) {
-      records.push({
+      const record: RecordedDomainEvent = {
         event,
         eventName: event.name,
         payload,
-        ...(options ? { options } : {}),
-      });
+        ...(options?.trace ? { options: { trace: options.trace } } : {}),
+      };
+      if (isEventPayloadParsed(event, payload, options) && options) {
+        validationOptions.set(record, { ...options });
+      }
+      records.push(record);
     },
 
     entries() {
-      return records;
+      return records.map((record) => ({
+        ...record,
+        ...(record.options ? { options: { ...record.options } } : {}),
+      }));
     },
 
     clear() {
@@ -245,11 +259,15 @@ export function createDomainEventRecorder(): BufferedDomainEventRecorder {
     async flush(eventBus) {
       while (records.length > 0) {
         const record = records[0];
-        await parseEventPayload(record.event, record.payload);
+        const prepared = await prepareEventPayloadForTransport(
+          record.event,
+          record.payload,
+          validationOptions.get(record) ?? record.options,
+        );
         await eventBus.publish(
           record.event,
-          record.payload as never,
-          record.options,
+          prepared.payload as never,
+          prepared.publishOptions,
         );
         records.shift();
       }

package/src/providers/index.ts

@@ -51,5 +51,4 @@ export {
   type ProviderServiceContextFactory,
   type ProviderSetupResult,
   type ServiceProvider,
-  type ServiceProviderMetadata,
 } from "./provider.js";

package/src/providers/provider.ts

@@ -126,41 +126,6 @@ export type ProviderSetupResult<
   ): MaybePromise<void>;
 };
 
-/**
- * Static provider metadata used by docs and app-local tooling.
- *
- * Metadata is descriptive. It does not change provider setup, ordering, or
- * runtime port merging behavior.
- *
- * Reusable provider packages should also declare package-owned
- * `beignet.provider` metadata in package.json so external tooling can inspect
- * provider facts without importing runtime code.
- */
-export interface ServiceProviderMetadata {
-  /**
-   * Package that exports this provider, when it comes from a reusable package.
-   */
-  packageName?: string;
-  /**
-   * App port keys this provider contributes or replaces.
-   */
-  ports?: readonly string[];
-  /**
-   * App port keys this provider expects previous providers or base app ports to
-   * have installed before setup runs.
-   */
-  requires?: readonly string[];
-  /**
-   * Environment variables this provider reads directly or via config loading.
-   */
-  env?: readonly string[];
-  /**
-   * Devtools watcher names this provider can emit through provider
-   * instrumentation.
-   */
-  watchers?: readonly string[];
-}
-
 /**
  * A service provider that can extend or replace ports during app initialization.
  *
@@ -205,11 +170,6 @@ export interface ServiceProvider<
    */
   name: string;
 
-  /**
-   * Optional static metadata for docs and diagnostics.
-   */
-  metadata?: ServiceProviderMetadata;
-
   /**
    * Optional configuration definition.
    * If provided, the config will be loaded and validated before calling setup.

package/src/search/index.ts

@@ -351,10 +351,6 @@ export function createMemorySearchProvider(
 
   return createProvider({
     name,
-    metadata: {
-      ports: ["search"],
-      watchers: ["search"],
-    },
     setup({ ports }) {
       const instrumentation = createProviderInstrumentation(ports, {
         providerName: name,
@@ -439,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/hooks/cors.ts

@@ -2,6 +2,7 @@
  * CORS hook utilities for @beignet/core/server
  */
 
+import { BEIGNET_ERROR_OWNER_HEADER } from "../../contracts/types.js";
 import type {
   HttpRequestLike,
   HttpResponseHeaders,
@@ -25,6 +26,11 @@ export interface CorsConfig {
    * Allowed request headers.
    */
   headers?: string[];
+  /**
+   * Additional response headers browser JavaScript may read. Beignet always
+   * exposes its framework error-ownership header.
+   */
+  exposedHeaders?: string[];
   /**
    * Whether credentialed requests are allowed.
    */
@@ -35,6 +41,7 @@ const DEFAULT_CORS: Required<CorsConfig> = {
   origins: "*",
   methods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
   headers: ["Content-Type", "Authorization"],
+  exposedHeaders: [],
   credentials: false,
 };
 
@@ -43,6 +50,7 @@ function resolveCorsConfig(config: CorsConfig): Required<CorsConfig> {
     origins: config.origins ?? DEFAULT_CORS.origins,
     methods: config.methods ?? DEFAULT_CORS.methods,
     headers: config.headers ?? DEFAULT_CORS.headers,
+    exposedHeaders: config.exposedHeaders ?? DEFAULT_CORS.exposedHeaders,
     credentials: config.credentials ?? DEFAULT_CORS.credentials,
   };
 
@@ -71,6 +79,35 @@ function appendVaryOrigin(headers: HttpResponseHeaders): void {
   headers[varyKey] = current ? `${current}, Origin` : "Origin";
 }
 
+function appendCommaSeparatedHeader(
+  headers: HttpResponseHeaders,
+  name: string,
+  appended: readonly string[],
+): void {
+  const key =
+    Object.keys(headers).find(
+      (candidate) => candidate.toLowerCase() === name.toLowerCase(),
+    ) ?? name;
+  const existing = headers[key];
+  const values = [
+    ...(typeof existing === "string"
+      ? existing.split(",")
+      : (existing ?? []).flatMap((value) => value.split(","))),
+    ...appended,
+  ]
+    .map((value) => value.trim())
+    .filter(Boolean);
+  const seen = new Set<string>();
+  const unique = values.filter((value) => {
+    const normalized = value.toLowerCase();
+    if (seen.has(normalized)) return false;
+    seen.add(normalized);
+    return true;
+  });
+
+  headers[key] = unique.join(", ");
+}
+
 /**
  * Apply CORS response headers to a mutable header record.
  *
@@ -86,6 +123,7 @@ export function applyCorsHeaders(
     origins,
     methods,
     headers: allowedHeaders,
+    exposedHeaders,
     credentials,
   } = resolveCorsConfig(corsConfig);
 
@@ -101,6 +139,10 @@ export function applyCorsHeaders(
 
   headers["Access-Control-Allow-Methods"] = methods.join(", ");
   headers["Access-Control-Allow-Headers"] = allowedHeaders.join(", ");
+  appendCommaSeparatedHeader(headers, "Access-Control-Expose-Headers", [
+    BEIGNET_ERROR_OWNER_HEADER,
+    ...exposedHeaders,
+  ]);
 
   if (credentials) {
     headers["Access-Control-Allow-Credentials"] = "true";

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,