@beignet/core 0.0.50 → 0.0.51

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

@@ -953,6 +953,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 +2434,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

@@ -2,6 +2,10 @@ import {
   type EventPublishOptions,
   parseEventPayload,
 } from "../events/index.js";
+import {
+  isEventPayloadParsed,
+  markEventPayloadParsed,
+} from "../events/payload-state.js";
 import type {
   DomainEventDef,
   EventBusPort,
@@ -83,17 +87,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 parsed 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 +124,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 +132,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, validating entries recorded
+   * directly without the use-case event helper.
    */
   flush(eventBus: EventBusPort): Promise<void>;
 }
@@ -223,19 +229,25 @@ export function createObservedUnitOfWork<TxPorts>(
  */
 export function createDomainEventRecorder(): BufferedDomainEventRecorder {
   const records: RecordedDomainEvent[] = [];
+  const parsedRecords = new WeakSet<RecordedDomainEvent>();
 
   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(options)) parsedRecords.add(record);
+      records.push(record);
     },
 
     entries() {
-      return records;
+      return records.map((record) => ({
+        ...record,
+        ...(record.options ? { options: { ...record.options } } : {}),
+      }));
     },
 
     clear() {
@@ -245,11 +257,13 @@ export function createDomainEventRecorder(): BufferedDomainEventRecorder {
     async flush(eventBus) {
       while (records.length > 0) {
         const record = records[0];
-        await parseEventPayload(record.event, record.payload);
+        const payload = parsedRecords.has(record)
+          ? record.payload
+          : await parseEventPayload(record.event, record.payload);
         await eventBus.publish(
           record.event,
-          record.payload as never,
-          record.options,
+          payload as never,
+          markEventPayloadParsed(record.options),
         );
         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,

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

@@ -669,24 +669,6 @@ export async function createServer<
     registryNeedsSort = true;
   };
 
-  const createBuilder = <C extends HttpContractConfig>(
-    contract: C,
-    shouldRegister: boolean,
-  ): RouteBuilder<Ctx, C> => ({
-    handle: (fn) => {
-      const wrapped = buildHandler(
-        options,
-        finalPorts,
-        contextRuntime,
-        contract,
-        fn,
-        hooks,
-      );
-      if (shouldRegister) registerRoute(contract, fn);
-      return wrapped;
-    },
-  });
-
   if (options.routes) {
     try {
       for (const route of options.routes) {
@@ -917,7 +899,58 @@ export async function createServer<
     api,
     route: (contractLike) => {
       const contract = resolveContract(contractLike);
-      return createBuilder(contract, true);
+      return {
+        handle: (fn) => {
+          const wrapped = buildHandler(
+            options,
+            finalPorts,
+            contextRuntime,
+            contract,
+            fn,
+            hooks,
+          );
+          registerRoute(contract, fn);
+          const compiled = compilePath(contract.path);
+
+          return async (req: HttpRequestLike) => {
+            const method = req.method.toUpperCase();
+            let url: URL;
+            try {
+              url = parseHttpRequestUrl(req.url);
+            } catch (error) {
+              return await executeFallback(
+                {
+                  contract: fallbackContract("invalidRequestUrl", method, "/"),
+                  handler: async () => {
+                    throw error;
+                  },
+                },
+                req,
+                {},
+              );
+            }
+
+            const requestMethod = method;
+            const contractMethod = contract.method.toUpperCase();
+            const methodMatches =
+              requestMethod === contractMethod ||
+              (requestMethod === "HEAD" && contractMethod === "GET");
+            if (!methodMatches || !compiled.pattern.test(url.pathname)) {
+              const pathname = url.pathname || "/";
+              return await executeFallback(
+                {
+                  contract: fallbackContract("notFound", method, pathname),
+                  handler: notFoundHandler,
+                },
+                req,
+                {},
+              );
+            }
+
+            return await wrapped(req);
+          };
+        },
+      };
     },
     rawRoute: (init) => ({
       handle: (fn) => {

package/src/testing/index.ts

@@ -15,7 +15,7 @@ import {
 } from "../notifications/index.js";
 import {
   createMemoryOutbox,
-  enqueueEvent,
+  createOutboxEventRecorder,
   type MemoryOutboxPort,
 } from "../outbox/index.js";
 import {
@@ -489,10 +489,17 @@ export function createTestPorts<
               outbox: MemoryOutboxPort;
             }
           ).outbox;
-          for (const entry of events.entries()) {
-            await enqueueEvent(outbox, entry.event, entry.payload);
-          }
-          events.clear();
+          const outboxRecorder = createOutboxEventRecorder(outbox);
+          await events.flush({
+            publish(event, payload, options) {
+              return outboxRecorder.record(event, payload, options);
+            },
+            subscribe() {
+              throw new Error(
+                "The test outbox event publisher does not support subscriptions.",
+              );
+            },
+          });
         }
         await transactionOptions?.afterCommit?.(tx);
       },
@@ -619,18 +626,19 @@ function completeTestPortOverrides<Ports extends AnyPorts>(
 
 function resolveBufferedTransactionEvents(
   tx: unknown,
-): Pick<BufferedDomainEventRecorder, "entries" | "clear"> {
+): Pick<BufferedDomainEventRecorder, "entries" | "clear" | "flush"> {
   const events =
     tx && typeof tx === "object"
       ? (tx as { events?: unknown }).events
       : undefined;
   const recorder = events as
-    | Partial<Pick<BufferedDomainEventRecorder, "entries" | "clear">>
+    | Partial<Pick<BufferedDomainEventRecorder, "entries" | "clear" | "flush">>
     | undefined;
   if (
     !recorder ||
     typeof recorder.entries !== "function" ||
-    typeof recorder.clear !== "function"
+    typeof recorder.clear !== "function" ||
+    typeof recorder.flush !== "function"
   ) {
     throw new Error(
       "createTestPorts transaction.outbox requires tx.events to be a buffered domain event recorder. " +
@@ -638,7 +646,10 @@ function resolveBufferedTransactionEvents(
     );
   }
 
-  return recorder as Pick<BufferedDomainEventRecorder, "entries" | "clear">;
+  return recorder as Pick<
+    BufferedDomainEventRecorder,
+    "entries" | "clear" | "flush"
+  >;
 }
 
 /**