@beignet/core 0.0.49 → 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/best-effort-work.ts

@@ -0,0 +1,21 @@
+/**
+ * Non-durable work scheduled outside the originating application operation.
+ */
+export type BestEffortWork = () => Promise<void> | void;
+
+/**
+ * Non-durable, best-effort follow-up work.
+ *
+ * Use this for follow-up work that may be lost without changing the outcome
+ * of the originating operation. Required or retryable work belongs in a job
+ * or durable outbox instead.
+ */
+export interface BestEffortWorkPort {
+  /**
+   * Schedule work without waiting for it in the originating operation.
+   *
+   * Adapters should isolate scheduling and callback failures from the caller
+   * and report them through their configured error observer.
+   */
+  defer(work: BestEffortWork): void;
+}

package/src/ports/events.ts

@@ -1,9 +1,13 @@
 import type {
   EventPayloadDef,
   EventPublishOptions,
+  EventSubscription,
   InferEventPayload as InferContractEventPayload,
   StandardSchema,
 } from "../events/index.js";
+
+export type { EventSubscription } from "../events/index.js";
+
 import type {
   JobDef as ContractJobDef,
   InferJobPayload as InferContractJobPayload,
@@ -58,15 +62,16 @@ export type InferJobPayload<J extends JobDef> = InferContractJobPayload<J>;
  * const eventBus = createMemoryEventBus();
  *
  * // Subscribe to an event
- * const unsubscribe = eventBus.subscribe(UserRegistered, (payload) => {
+ * const subscription = eventBus.subscribe(UserRegistered, (payload) => {
  *   console.log(`User registered: ${payload.email}`);
  * });
+ * await subscription.ready;
  *
  * // Publish an event
  * await eventBus.publish(UserRegistered, { userId: "123", email: "test@example.com" });
  *
  * // Unsubscribe when done
- * unsubscribe();
+ * await subscription.unsubscribe();
  * ```
  */
 export interface EventBusPort {
@@ -80,7 +85,7 @@ export interface EventBusPort {
   ): Promise<void> | void;
 
   /**
-   * Subscribe to a domain event. Returns an unsubscribe function.
+   * Subscribe to a domain event. Returns initial readiness and cleanup.
    */
   subscribe<E extends DomainEventDef>(
     event: E,
@@ -88,7 +93,7 @@ export interface EventBusPort {
       payload: InferEventPayload<E>,
       options?: EventPublishOptions,
     ) => Promise<void> | void,
-  ): () => void;
+  ): EventSubscription;
 }
 
 /**

package/src/ports/index.ts

@@ -8,6 +8,7 @@
  * - `definePorts` – helper to define a typed ports object
  * - `PortsContext` – a generic type that describes ctx objects that carry ports
  * - `EventBusPort` – interface for event bus implementations
+ * - `BestEffortWorkPort` – interface for non-durable follow-up work
  * - `JobDispatcherPort` – interface for job dispatch implementations
  * - `UnitOfWorkPort` – interface for app-owned transaction boundaries
  * - `OutboxPort` – interface for durable event/job delivery storage
@@ -282,6 +283,7 @@ export type {
   ClaimedOutboxMessage,
   OutboxAdminPort,
   OutboxClaimBatchOptions,
+  OutboxClaimBatchResult,
   OutboxCountMessagesOptions,
   OutboxDeleteResult,
   OutboxEnqueueInput,
@@ -295,6 +297,8 @@ export type {
   OutboxPort,
   OutboxPruneDeliveredInput,
   OutboxPurgeDeadLetteredInput,
+  OutboxRenewClaimInput,
+  OutboxRenewClaimResult,
   OutboxRequeueMessageInput,
 } from "../outbox/index.js";
 /**
@@ -468,6 +472,13 @@ export {
   requireUserId,
   TenantRequiredError,
 } from "./auth.js";
+/**
+ * Best-effort work port exports.
+ */
+export type {
+  BestEffortWork,
+  BestEffortWorkPort,
+} from "./best-effort-work.js";
 /**
  * Ports builder exports.
  */
@@ -498,6 +509,7 @@ export { createFrozenClock, createSystemClock } from "./clock.js";
 export type {
   DomainEventDef,
   EventBusPort,
+  EventSubscription,
   InferEventPayload,
   InferJobPayload,
   JobDef,

package/src/ports/testing.ts

@@ -38,6 +38,7 @@ import {
   createTenant,
   createUserActor,
 } from "./audit.js";
+import type { BestEffortWork, BestEffortWorkPort } from "./best-effort-work.js";
 import type { EventBusPort, JobDef, JobDispatcherPort } from "./events.js";
 import {
   type CreateGateOptions,
@@ -114,6 +115,50 @@ export function createRecordingEventBus(): {
   return { bus, events };
 }
 
+/**
+ * Recording best-effort-work adapter for deterministic tests.
+ *
+ * Calls to `defer(...)` append work without running it. `flush()` runs the
+ * currently pending batch in FIFO order, then rejects with the callback error
+ * or an `AggregateError` after every callback in that batch has been attempted.
+ * Work deferred by a running callback remains pending for the next flush so
+ * one flush stays bounded.
+ */
+export function createRecordingBestEffortWork(): {
+  bestEffortWork: BestEffortWorkPort;
+  pending: BestEffortWork[];
+  flush(): Promise<void>;
+} {
+  const pending: BestEffortWork[] = [];
+
+  return {
+    bestEffortWork: {
+      defer(work) {
+        pending.push(work);
+      },
+    },
+    pending,
+    async flush() {
+      const batch = pending.splice(0);
+      const errors: unknown[] = [];
+      for (const work of batch) {
+        try {
+          await work();
+        } catch (error) {
+          errors.push(error);
+        }
+      }
+
+      if (errors.length === 1) {
+        throw errors[0];
+      }
+      if (errors.length > 1) {
+        throw new AggregateError(errors, "Best-effort work batch failed.");
+      }
+    },
+  };
+}
+
 /**
  * A job dispatch captured by `createRecordingJobDispatcher(...)`.
  */
@@ -908,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;
 }
 
 /**
@@ -2376,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

@@ -55,9 +55,11 @@ export type MaybePromise<T> = T | Promise<T>;
 /**
  * Late-bound service context factory exposed to providers.
  *
- * Calling it before all providers have started throws, so providers should
- * only invoke it from runtime entrypoints such as job dispatch, listeners, or
- * scheduled work.
+ * Calling it during provider setup or after provider shutdown throws. Start
+ * and stop hooks may invoke it after every provider has contributed ports and
+ * the server has verified that no deferred port remains unbound. Runtime
+ * entrypoints such as job dispatch, listeners, or scheduled work can close
+ * over it for later use.
  *
  * App-local providers can type the factory by declaring `Context` and
  * `ServiceInput` through the curried `createProvider<Requires, Context,
@@ -124,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.
  *
@@ -203,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.
@@ -222,8 +184,9 @@ export interface ServiceProvider<
    * @param ctx.ports - Ports contributed by previous providers
    * @param ctx.config - Validated config (if config was defined), or undefined
    * @param ctx.createServiceContext - Late-bound service context factory.
-   * Throws until all providers have started, so call it lazily from runtime
-   * entrypoints such as job dispatchers and event listeners.
+   * Throws during setup. Start and stop hooks may invoke it after all provider
+   * ports have been contributed and validated; runtime entrypoints such as job
+   * dispatchers and event listeners may call it lazily afterward.
    */
   setup(ctx: {
     ports: Readonly<Ports>;

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,7 +2,12 @@
  * CORS hook utilities for @beignet/core/server
  */
 
-import type { HttpRequestLike, ServerHook } from "../types.js";
+import { BEIGNET_ERROR_OWNER_HEADER } from "../../contracts/types.js";
+import type {
+  HttpRequestLike,
+  HttpResponseHeaders,
+  ServerHook,
+} from "../types.js";
 
 /**
  * CORS configuration for `createCorsHooks(...)`.
@@ -21,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.
    */
@@ -31,6 +41,7 @@ const DEFAULT_CORS: Required<CorsConfig> = {
   origins: "*",
   methods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
   headers: ["Content-Type", "Authorization"],
+  exposedHeaders: [],
   credentials: false,
 };
 
@@ -39,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,
   };
 
@@ -55,16 +67,47 @@ function resolveCorsConfig(config: CorsConfig): Required<CorsConfig> {
   return resolved;
 }
 
-function appendVaryOrigin(headers: Record<string, string>): void {
+function appendVaryOrigin(headers: HttpResponseHeaders): void {
   const varyKey =
     Object.keys(headers).find((key) => key.toLowerCase() === "vary") ?? "Vary";
-  const current = headers[varyKey];
+  const currentValue = headers[varyKey];
+  const current =
+    typeof currentValue === "string" ? currentValue : currentValue?.join(", ");
   const values = current?.split(",").map((value) => value.trim().toLowerCase());
   if (values?.includes("origin")) return;
 
   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.
  *
@@ -72,7 +115,7 @@ function appendVaryOrigin(headers: Record<string, string>): void {
  * when cookies or authorization headers are allowed cross-origin.
  */
 export function applyCorsHeaders(
-  headers: Record<string, string>,
+  headers: HttpResponseHeaders,
   req: HttpRequestLike,
   corsConfig: CorsConfig,
 ): void {
@@ -80,6 +123,7 @@ export function applyCorsHeaders(
     origins,
     methods,
     headers: allowedHeaders,
+    exposedHeaders,
     credentials,
   } = resolveCorsConfig(corsConfig);
 
@@ -95,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";
@@ -121,7 +169,7 @@ export function createCorsHooks<Ctx>(config: CorsConfig): ServerHook<Ctx> {
       ) {
         return undefined;
       }
-      const headers: Record<string, string> = {};
+      const headers: HttpResponseHeaders = {};
       applyCorsHeaders(headers, req, corsConfig);
       return {
         status: 204,

package/src/server/hooks/logging.ts

@@ -7,7 +7,11 @@ import {
   resolveTrustedRequest,
   type TrustedRequestInfo,
 } from "../trusted-proxy.js";
-import type { HttpRequestLike, ServerHook } from "../types.js";
+import type {
+  HttpRequestLike,
+  HttpResponseHeaders,
+  ServerHook,
+} from "../types.js";
 import { getRequestIdFromContext } from "./utils.js";
 
 /**
@@ -60,7 +64,7 @@ export interface LoggingConfig<Ctx> {
     ctx?: Ctx;
     req: HttpRequestLike;
     requestInfo: TrustedRequestInfo;
-    res: { status: number; headers: Record<string, string> };
+    res: { status: number; headers: HttpResponseHeaders };
     durationMs: number;
     contract?: HttpContractConfig;
     error?: unknown;

package/src/server/hooks/security.ts

@@ -9,7 +9,11 @@ import {
   type TrustedProxyConfig,
   type TrustedProxyOptions,
 } from "../trusted-proxy.js";
-import type { HttpRequestLike, ServerHook } from "../types.js";
+import type {
+  HttpRequestLike,
+  HttpResponseHeaders,
+  ServerHook,
+} from "../types.js";
 
 /**
  * Strict-Transport-Security configuration.
@@ -180,7 +184,7 @@ const DEFAULT_CSRF_HEADER = "x-csrf-token";
 const DEFAULT_CSRF_COOKIE = "beignet.csrf";
 
 function headerKey(
-  headers: Record<string, string>,
+  headers: HttpResponseHeaders,
   name: string,
 ): string | undefined {
   const lowerName = name.toLowerCase();
@@ -188,7 +192,7 @@ function headerKey(
 }
 
 function setHeaderIfMissing(
-  headers: Record<string, string>,
+  headers: HttpResponseHeaders,
   name: string,
   value: string | false | undefined,
 ): void {
@@ -217,7 +221,7 @@ function formatStrictTransportSecurity(
  * provide more specific policies.
  */
 export function applySecurityHeaders(
-  headers: Record<string, string>,
+  headers: HttpResponseHeaders,
   options: SecurityHeadersOptions = {},
 ): void {
   setHeaderIfMissing(

package/src/server/http.ts

@@ -29,6 +29,14 @@ export interface HttpRequestLike {
    * Request headers.
    */
   headers: Headers;
+  /**
+   * Abort signal for the request lifecycle when the platform exposes one.
+   *
+   * Streaming handlers should pass this to resources that must close when
+   * the client disconnects. Adapters without cancellation support may omit
+   * it.
+   */
+  signal?: AbortSignal;
   /**
    * The platform request when an adapter has one available.
    *
@@ -62,6 +70,19 @@ export interface HttpRequestLike {
   clone?(): HttpRequestLike;
 }
 
+/**
+ * Header values accepted by a framework-neutral Beignet response.
+ *
+ * Use an array when the field must be emitted more than once, such as
+ * `Set-Cookie`. Adapters append every array item as a separate field value.
+ */
+export type HttpResponseHeaderValue = string | readonly string[];
+
+/**
+ * Framework-neutral response headers.
+ */
+export type HttpResponseHeaders = Record<string, HttpResponseHeaderValue>;
+
 /**
  * Framework-neutral response object returned by route handlers and hooks.
  */
@@ -71,9 +92,9 @@ export interface HttpResponseLike {
    */
   status: number;
   /**
-   * Response headers.
+   * Response headers. Array values are emitted as repeated header fields.
    */
-  headers?: Record<string, string>;
+  headers?: HttpResponseHeaders;
   /**
    * JSON-serializable body or an adapter-specific body value.
    */

package/src/server/index.ts

@@ -95,6 +95,10 @@ export {
  * Server context blueprint declaration helper.
  */
 export { defineServerContext } from "./server-context.js";
+/**
+ * Portable Server-Sent Events response helper.
+ */
+export * from "./server-sent-events.js";
 /**
  * Trusted proxy request metadata helpers.
  */