@beignet/core 0.0.37 → 0.0.39

package/src/locks/index.ts

@@ -64,6 +64,25 @@ export type LeaseRenewOptions = {
   ttlMs?: number;
 };
 
+/**
+ * State required to restore a lease handle in another runtime invocation.
+ */
+export type LeaseRestoreOptions = {
+  /**
+   * TTL to use when `renew()` is called without an explicit override.
+   */
+  ttlMs: number;
+  /**
+   * Persisted expiry when the caller has it. Omitted values stay unknown.
+   */
+  expiresAt?: Date;
+  /**
+   * Persisted fencing token when the caller has it. Omitted values stay
+   * unknown rather than being fabricated.
+   */
+  fencingToken?: string | number;
+};
+
 /**
  * Active lease handle returned by a lock provider.
  */
@@ -100,7 +119,11 @@ export type LocksPort = {
     options: LeaseAcquireOptions,
     fn: (ctx: { lease: LeaseHandle }) => MaybePromise<T>,
   ): Promise<T | undefined>;
-  restore(key: string, ownerToken: string): LeaseHandle;
+  restore(
+    key: string,
+    ownerToken: string,
+    options: LeaseRestoreOptions,
+  ): LeaseHandle;
   forceRelease(key: string): Promise<boolean>;
 };
 
@@ -220,20 +243,21 @@ export function createMemoryLocks(
         await result.lease.release();
       }
     },
-    restore(key, ownerToken) {
+    restore(key, ownerToken, restoreOptions) {
       if (!key) throw new LeaseOptionsError("Lease key is required.");
       if (!ownerToken) {
         throw new LeaseOptionsError("Lease owner token is required.");
       }
+      validateRestoreOptions(restoreOptions);
 
       return createMemoryLease(
         port,
         {
           key,
           ownerToken,
-          expiresAt: new Date(0),
-          ttlMs: 1,
-          fencingToken: 0,
+          ttlMs: restoreOptions.ttlMs,
+          expiresAt: restoreOptions.expiresAt,
+          fencingToken: restoreOptions.fencingToken,
         },
         now,
       );
@@ -306,32 +330,40 @@ export function withLease<T>(
 
 function createMemoryLease(
   port: MemoryLocksPort,
-  record: MemoryLeaseRecord,
+  record: {
+    key: string;
+    ownerToken: string;
+    ttlMs: number;
+    expiresAt?: Date;
+    fencingToken?: string | number;
+  },
   now: () => Date,
 ): LeaseHandle {
   const lease: LeaseHandle = {
     key: record.key,
     ownerToken: record.ownerToken,
-    expiresAt: record.expiresAt,
-    fencingToken: record.fencingToken,
+    ...(record.expiresAt ? { expiresAt: record.expiresAt } : {}),
+    ...(record.fencingToken !== undefined
+      ? { fencingToken: record.fencingToken }
+      : {}),
     async renew(options) {
       const active = port.leases.get(record.key);
-      if (
-        !active ||
-        active.ownerToken !== record.ownerToken ||
-        active.expiresAt.getTime() <= now().getTime()
-      ) {
+      if (!active || active.ownerToken !== record.ownerToken) {
+        return false;
+      }
+      if (active.expiresAt.getTime() <= now().getTime()) {
         port.leases.delete(record.key);
         return false;
       }
 
-      const ttlMs = options?.ttlMs ?? active.ttlMs;
+      const ttlMs = options?.ttlMs ?? record.ttlMs;
       if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
         throw new LeaseOptionsError("Lease ttlMs must be a positive number.");
       }
 
       active.ttlMs = ttlMs;
       active.expiresAt = new Date(now().getTime() + ttlMs);
+      record.ttlMs = ttlMs;
       lease.expiresAt = active.expiresAt;
       return true;
     },
@@ -352,6 +384,23 @@ function createMemoryLease(
   return lease;
 }
 
+function validateRestoreOptions(options: LeaseRestoreOptions): void {
+  if (!options || !Number.isFinite(options.ttlMs) || options.ttlMs <= 0) {
+    throw new LeaseOptionsError(
+      "Lease restore ttlMs must be a positive number.",
+    );
+  }
+  if (
+    options.expiresAt !== undefined &&
+    (!(options.expiresAt instanceof Date) ||
+      !Number.isFinite(options.expiresAt.getTime()))
+  ) {
+    throw new LeaseOptionsError(
+      "Lease restore expiresAt must be a valid Date.",
+    );
+  }
+}
+
 function instrumentLocks(
   locks: LocksPort,
   instrumentation: ReturnType<typeof createProviderInstrumentation>,
@@ -387,8 +436,8 @@ function instrumentLocks(
         await result.lease.release();
       }
     },
-    restore(key, ownerToken) {
-      return locks.restore(key, ownerToken);
+    restore(key, ownerToken, options) {
+      return locks.restore(key, ownerToken, options);
     },
     async forceRelease(key) {
       const released = await locks.forceRelease(key);

package/src/outbox/index.ts

@@ -7,6 +7,7 @@
 
 import {
   type EventPayloadDef,
+  type EventPublishOptions,
   type InferEventPayload,
   parseEventPayload,
 } from "../events/index.js";
@@ -21,15 +22,20 @@ import {
   shouldRetryJob,
 } from "../jobs/index.js";
 import type { JobDispatcherPort } from "../ports/events.js";
-import type {
-  BufferedDomainEventRecorder,
-  DomainEventRecorderPort,
-} from "../ports/unit-of-work.js";
+import type { DomainEventRecorderPort } from "../ports/unit-of-work.js";
 import {
   type BaseProviderInstrumentationEvent,
   createProviderInstrumentation,
   type ProviderInstrumentationTarget,
 } from "../providers/index.js";
+import {
+  captureTraceCarrier,
+  parseTraceCarrier,
+  resolveTracingPort,
+  runWithTracing,
+  type TraceCarrier,
+  type TracingPort,
+} from "../tracing/index.js";
 
 /**
  * Value or promise of that value.
@@ -113,6 +119,8 @@ export interface OutboxEnqueueInput {
    * JSON-serializable payload.
    */
   payload: OutboxJsonValue;
+  /** Versioned trace context captured when the message was recorded. */
+  trace?: TraceCarrier;
   /**
    * Earliest time the message may be claimed.
    */
@@ -143,6 +151,8 @@ export interface OutboxMessage {
    * JSON-serializable payload.
    */
   payload: OutboxJsonValue;
+  /** Versioned trace context captured when the message was recorded. */
+  trace?: TraceCarrier;
   /**
    * Current delivery status.
    */
@@ -490,6 +500,10 @@ export interface EnqueueTypedOutboxOptions {
    * Maximum delivery attempts before dead-lettering.
    */
   maxAttempts?: number;
+  /** Explicit trace context to persist with this message. */
+  trace?: TraceCarrier;
+  /** Tracing port used to capture the active context at enqueue time. */
+  tracing?: TracingPort;
 }
 
 /**
@@ -547,6 +561,7 @@ export interface DrainOutboxOptions {
     publish<E extends EventPayloadDef>(
       event: E,
       payload: InferEventPayload<E>,
+      options?: EventPublishOptions,
     ): MaybePromise<void>;
   };
   /**
@@ -592,6 +607,23 @@ export interface DrainOutboxOptions {
     error: unknown,
     message: ClaimedOutboxMessage,
   ) => MaybePromise<void>;
+  /**
+   * Observer called after a failed delivery is successfully moved to the dead
+   * letter state. Observer failures are ignored.
+   */
+  onDeadLetter?: (
+    error: unknown,
+    message: ClaimedOutboxMessage,
+  ) => MaybePromise<void>;
+  /**
+   * Observer called when a failed delivery cannot be settled as retryable or
+   * dead-lettered. Observer failures are ignored.
+   */
+  onSettlementError?: (
+    settlementError: unknown,
+    message: ClaimedOutboxMessage,
+    deliveryError: unknown,
+  ) => MaybePromise<void>;
 }
 
 /**
@@ -921,11 +953,13 @@ export function createOutboxMessage(
   }
 
   const now = options.now ?? new Date();
+  const trace = parseTraceCarrier(input.trace);
   return {
     id: options.id ?? input.id ?? options.createId?.() ?? createId(),
     kind: input.kind,
     name: input.name,
     payload: toOutboxJsonValue(input.payload),
+    ...(trace ? { trace } : {}),
     status: "pending",
     attempts: 0,
     maxAttempts: input.maxAttempts ?? DEFAULT_OUTBOX_MAX_ATTEMPTS,
@@ -1236,11 +1270,14 @@ export async function enqueueEvent<E extends EventPayloadDef>(
   options: EnqueueTypedOutboxOptions = {},
 ): Promise<OutboxMessage> {
   const parsed = await parseEventPayload(event, payload);
+  const trace =
+    parseTraceCarrier(options.trace) ?? captureTraceCarrier(options.tracing);
   return outbox.enqueue({
     id: options.id,
     kind: "event",
     name: event.name,
     payload: toOutboxJsonValue(parsed),
+    trace,
     availableAt: options.availableAt,
     maxAttempts: options.maxAttempts,
   });
@@ -1256,11 +1293,14 @@ export async function enqueueJob<J extends JobDef>(
   options: EnqueueTypedOutboxOptions = {},
 ): Promise<OutboxMessage> {
   const parsed = await parseJobPayload(job, payload);
+  const trace =
+    parseTraceCarrier(options.trace) ?? captureTraceCarrier(options.tracing);
   return outbox.enqueue({
     id: options.id,
     kind: "job",
     name: job.name,
     payload: toOutboxJsonValue(parsed),
+    trace,
     availableAt: options.availableAt,
     maxAttempts: options.maxAttempts ?? getJobRetryMaxAttempts(job.retry),
   });
@@ -1272,16 +1312,14 @@ export async function enqueueJob<J extends JobDef>(
 export function createOutboxEventRecorder(
   outbox: OutboxPort,
   options: EnqueueTypedOutboxOptions = {},
-): BufferedDomainEventRecorder {
+): DomainEventRecorderPort {
   return {
-    async record(event, payload) {
-      await enqueueEvent(outbox, event, payload, options);
-    },
-    entries() {
-      return [];
+    async record(event, payload, publishOptions) {
+      await enqueueEvent(outbox, event, payload, {
+        ...options,
+        trace: publishOptions?.trace ?? options.trace,
+      });
     },
-    clear() {},
-    async flush() {},
   };
 }
 
@@ -1293,8 +1331,11 @@ export function createOutboxJobDispatcher(
   options: EnqueueTypedOutboxOptions = {},
 ): JobDispatcherPort {
   return {
-    async dispatch(job, payload) {
-      await enqueueJob(outbox, job, payload, options);
+    async dispatch(job, payload, dispatchOptions) {
+      await enqueueJob(outbox, job, payload, {
+        ...options,
+        trace: dispatchOptions?.trace ?? options.trace,
+      });
     },
   };
 }
@@ -1365,6 +1406,7 @@ function outboxInstrumentationDetails(
 async function deliverOutboxMessage(
   options: DrainOutboxOptions,
   message: ClaimedOutboxMessage,
+  trace?: TraceCarrier,
 ): Promise<void> {
   if (message.kind === "event") {
     if (!options.eventBus) {
@@ -1381,7 +1423,11 @@ async function deliverOutboxMessage(
     }
 
     const payload = await parseEventPayload(event, message.payload);
-    await options.eventBus.publish(event, payload);
+    await options.eventBus.publish(
+      event,
+      payload,
+      trace ? { trace } : undefined,
+    );
     return;
   }
 
@@ -1414,11 +1460,12 @@ async function deliverOutboxMessage(
     await singleAttempt(job, payload, {
       attempt: message.attempts,
       maxAttempts: message.maxAttempts,
+      trace,
     });
     return;
   }
 
-  await options.jobs.dispatch(job, payload);
+  await options.jobs.dispatch(job, payload, trace ? { trace } : undefined);
 }
 
 /**
@@ -1448,6 +1495,7 @@ export async function drainOutbox(
       watcher: "jobs",
     },
   );
+  const tracing = resolveTracingPort(options.instrumentation);
 
   const now = options.now ?? new Date();
   const messages = await options.outbox.claimBatch({
@@ -1464,7 +1512,28 @@ export async function drainOutbox(
 
   for (const message of messages) {
     try {
-      await deliverOutboxMessage(options, message);
+      const parentTrace = parseTraceCarrier(message.trace);
+      const traceAttributes = {
+        "beignet.outbox.message_kind": message.kind,
+        "beignet.outbox.message_name": message.name,
+      } as const;
+      await runWithTracing(
+        tracing,
+        {
+          name: `beignet.outbox deliver ${message.name}`,
+          type: "outbox",
+          kind: "consumer",
+          parent: parentTrace,
+          attributes: traceAttributes,
+          metricAttributes: traceAttributes,
+        },
+        (span) =>
+          deliverOutboxMessage(
+            options,
+            message,
+            captureTraceCarrier(span?.context ?? parentTrace),
+          ),
+      );
       await options.outbox.markDelivered({
         id: message.id,
         claimToken: message.claimToken,
@@ -1492,18 +1561,41 @@ export async function drainOutbox(
       const retryDelayMs = deadLetter
         ? 0
         : resolveRetryDelayMs(options, message, error, now);
-      await options.outbox.markFailed({
-        id: message.id,
-        claimToken: message.claimToken,
-        error,
-        deadLetter,
-        now,
-        retryAt: deadLetter
-          ? undefined
-          : new Date(now.getTime() + retryDelayMs),
-      });
+      try {
+        await options.outbox.markFailed({
+          id: message.id,
+          claimToken: message.claimToken,
+          error,
+          deadLetter,
+          now,
+          retryAt: deadLetter
+            ? undefined
+            : new Date(now.getTime() + retryDelayMs),
+        });
+      } catch (settlementError) {
+        try {
+          await options.onSettlementError?.(settlementError, message, error);
+        } catch {
+          // Preserve the settlement failure when its observer also fails.
+        }
+        instrumentation.custom({
+          name: "outbox.settlement.failed",
+          label: "Outbox settlement failed",
+          summary: `Could not settle failed ${message.kind} "${message.name}"`,
+          details: outboxInstrumentationDetails(message, {
+            deliveryError: serializeOutboxError(error),
+            settlementError: serializeOutboxError(settlementError),
+          }),
+        });
+        continue;
+      }
 
       if (deadLetter) {
+        try {
+          await options.onDeadLetter?.(error, message);
+        } catch {
+          // Dead-letter observers must not change the settled message state.
+        }
         instrumentation.record({
           type: "outbox",
           ...options.instrumentationContext,

package/src/ports/events.ts

@@ -1,11 +1,13 @@
 import type {
   EventPayloadDef,
+  EventPublishOptions,
   InferEventPayload as InferContractEventPayload,
   StandardSchema,
 } from "../events/index.js";
 import type {
   JobDef as ContractJobDef,
   InferJobPayload as InferContractJobPayload,
+  JobDispatchOptions,
 } from "../jobs/index.js";
 
 /**
@@ -74,6 +76,7 @@ export interface EventBusPort {
   publish<E extends DomainEventDef>(
     event: E,
     payload: InferEventPayload<E>,
+    options?: EventPublishOptions,
   ): Promise<void> | void;
 
   /**
@@ -81,7 +84,10 @@ export interface EventBusPort {
    */
   subscribe<E extends DomainEventDef>(
     event: E,
-    handler: (payload: InferEventPayload<E>) => Promise<void> | void,
+    handler: (
+      payload: InferEventPayload<E>,
+      options?: EventPublishOptions,
+    ) => Promise<void> | void,
   ): () => void;
 }
 
@@ -96,5 +102,6 @@ export interface JobDispatcherPort {
   dispatch<J extends JobDef>(
     job: J,
     payload: InferJobPayload<J>,
+    options?: JobDispatchOptions,
   ): Promise<void> | void;
 }

package/src/ports/index.ts

@@ -75,7 +75,7 @@ export type DeferredPortsDefinition<
  * Define the set of ports (outbound dependencies) for your application.
  *
  * The identity form captures the exact shape of the provided `ports` object
- * so you can export `type AppPorts = typeof appPorts`.
+ * so you can export `type AppPorts = typeof initialPorts`.
  *
  * The curried form, `definePorts<AppPorts>()({ bound, deferred })`, declares
  * which port keys providers contribute at server startup. Deferred keys boot
@@ -86,14 +86,14 @@ export type DeferredPortsDefinition<
  * @example
  * ```ts
  * // Identity form: every port is bound directly.
- * const appPorts = definePorts({
+ * const initialPorts = definePorts({
  *   db: dbAdapter,
  *   mailer: mailerAdapter,
  * });
- * export type AppPorts = typeof appPorts;
+ * export type AppPorts = typeof initialPorts;
  *
  * // Deferred form: providers contribute the rest at startup.
- * export const appPorts = definePorts<AppPorts>()({
+ * export const initialPorts = definePorts<AppPorts>()({
  *   bound: { gate },
  *   deferred: ["db", "mailer", "storage"],
  * });

package/src/ports/unbound.ts

@@ -13,7 +13,7 @@ function unboundPortMessage(portName: string): string {
   return (
     `Port "${portName}" is not bound. "${portName}" is declared as deferred ` +
     "in definePorts(...). Register a provider that contributes it " +
-    "(server/providers.ts) or bind it in infra/app-ports.ts."
+    "(server/providers.ts) or bind it in infra/port-wiring.ts."
   );
 }
 

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

@@ -1,4 +1,7 @@
-import { parseEventPayload } from "../events/index.js";
+import {
+  type EventPublishOptions,
+  parseEventPayload,
+} from "../events/index.js";
 import type {
   DomainEventDef,
   EventBusPort,
@@ -71,6 +74,8 @@ export interface RecordedDomainEvent {
    * Unparsed payload recorded during the transaction.
    */
   payload: unknown;
+  /** Optional metadata propagated when the event is flushed. */
+  options?: EventPublishOptions;
 }
 
 /**
@@ -87,6 +92,7 @@ export interface DomainEventRecorderPort {
   record<E extends DomainEventDef>(
     event: E,
     payload: InferEventPayload<E>,
+    options?: EventPublishOptions,
   ): Promise<void> | void;
 }
 
@@ -167,11 +173,12 @@ export function createDomainEventRecorder(): BufferedDomainEventRecorder {
   const records: RecordedDomainEvent[] = [];
 
   return {
-    record(event, payload) {
+    record(event, payload, options) {
       records.push({
         event,
         eventName: event.name,
         payload,
+        ...(options ? { options } : {}),
       });
     },
 
@@ -187,7 +194,7 @@ export function createDomainEventRecorder(): BufferedDomainEventRecorder {
       while (records.length > 0) {
         const record = records[0];
         const payload = await parseEventPayload(record.event, record.payload);
-        await eventBus.publish(record.event, payload);
+        await eventBus.publish(record.event, payload, record.options);
         records.shift();
       }
     },

package/src/query-codec.ts

@@ -0,0 +1,130 @@
+const QUERY_VALUE_PREFIX = "~beignet-query:";
+
+type EncodedQueryValue =
+  | { type: "null" }
+  | { type: "string"; value: string }
+  | { type: "number"; value: number }
+  | { type: "boolean"; value: boolean }
+  | { type: "date"; value: string }
+  | { type: "array"; value: EncodedQueryValue[] }
+  | { type: "object"; value: Record<string, EncodedQueryValue> };
+
+function encodeStructuredValue(
+  value: unknown,
+  ancestors: Set<object>,
+): EncodedQueryValue {
+  if (value === null) return { type: "null" };
+  if (typeof value === "string") return { type: "string", value };
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return { type: "number", value };
+  }
+  if (typeof value === "boolean") return { type: "boolean", value };
+  if (value instanceof Date && Number.isFinite(value.getTime())) {
+    return { type: "date", value: value.toISOString() };
+  }
+  if (typeof value !== "object" || value === null) {
+    throw new TypeError("Query value is not serializable.");
+  }
+  if (ancestors.has(value)) {
+    throw new TypeError("Query value contains a circular reference.");
+  }
+
+  ancestors.add(value);
+  try {
+    if (Array.isArray(value)) {
+      return {
+        type: "array",
+        value: value.map((entry) => encodeStructuredValue(entry, ancestors)),
+      };
+    }
+
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new TypeError("Query value contains a non-plain object.");
+    }
+    return {
+      type: "object",
+      value: Object.fromEntries(
+        Object.entries(value)
+          .filter(([, entry]) => entry !== undefined)
+          .map(([key, entry]) => [
+            key,
+            encodeStructuredValue(entry, ancestors),
+          ]),
+      ),
+    };
+  } finally {
+    ancestors.delete(value);
+  }
+}
+
+function decodeStructuredValue(value: unknown): unknown {
+  if (typeof value !== "object" || value === null || !("type" in value)) {
+    throw new TypeError("Invalid encoded query value.");
+  }
+  const encoded = value as { type: unknown; value?: unknown };
+
+  switch (encoded.type) {
+    case "null":
+      return null;
+    case "string":
+      if (typeof encoded.value === "string") return encoded.value;
+      break;
+    case "number":
+      if (typeof encoded.value === "number" && Number.isFinite(encoded.value)) {
+        return encoded.value;
+      }
+      break;
+    case "boolean":
+      if (typeof encoded.value === "boolean") return encoded.value;
+      break;
+    case "date": {
+      if (typeof encoded.value !== "string") break;
+      const date = new Date(encoded.value);
+      if (Number.isFinite(date.getTime())) return date;
+      break;
+    }
+    case "array":
+      if (Array.isArray(encoded.value)) {
+        return encoded.value.map(decodeStructuredValue);
+      }
+      break;
+    case "object":
+      if (
+        typeof encoded.value === "object" &&
+        encoded.value !== null &&
+        !Array.isArray(encoded.value)
+      ) {
+        return Object.fromEntries(
+          Object.entries(encoded.value).map(([key, entry]) => [
+            key,
+            decodeStructuredValue(entry),
+          ]),
+        );
+      }
+      break;
+  }
+
+  throw new TypeError("Invalid encoded query value.");
+}
+
+export function encodeQueryValue(value: unknown): string {
+  if (typeof value === "string" && !value.startsWith(QUERY_VALUE_PREFIX)) {
+    return value;
+  }
+  return `${QUERY_VALUE_PREFIX}${JSON.stringify(
+    encodeStructuredValue(value, new Set()),
+  )}`;
+}
+
+export function decodeQueryValue(value: string): unknown {
+  if (!value.startsWith(QUERY_VALUE_PREFIX)) return value;
+
+  try {
+    return decodeStructuredValue(
+      JSON.parse(value.slice(QUERY_VALUE_PREFIX.length)) as unknown,
+    );
+  } catch {
+    return value;
+  }
+}