@beignet/core 0.0.37 → 0.0.38

package/src/error-reporting/index.ts

@@ -4,6 +4,18 @@
  * Provider-neutral error reporting primitives for Beignet applications.
  */
 
+import { type RedactionOptions, redactValue } from "../ports/redaction.js";
+import {
+  DEFAULT_ERROR_REPORTING_TIMEOUT_MS,
+  errorReportingObserverTimeout,
+  runErrorReportingOperation,
+} from "./internal.js";
+
+export {
+  DEFAULT_ERROR_REPORTING_TIMEOUT_MS,
+  ErrorReportingTimeoutError,
+} from "./internal.js";
+
 type MaybePromise<T> = T | Promise<T>;
 
 /**
@@ -67,6 +79,33 @@ export type ErrorReportOptions = {
   traceparent?: string;
 };
 
+/**
+ * Arguments accepted by `tryReportException(...)`.
+ */
+export interface TryReportExceptionOptions {
+  /** Reporter that owns the capture. Omit it to make reporting a no-op. */
+  reporter?: ErrorReporterPort | ErrorReporterResolver;
+  /** Original application or infrastructure error. */
+  error: unknown;
+  /** Structured metadata attached to the report. */
+  reportOptions?: ErrorReportOptions;
+  /**
+   * Maximum time allowed for capture and, separately, the failure observer.
+   * Set to `false` only when the reporting implementation is intentionally
+   * unbounded.
+   *
+   * @default 1000
+   */
+  timeoutMs?: number | false;
+  /**
+   * Observer for reporter failures. Observer failures are also isolated.
+   */
+  onReporterError?: (args: {
+    error: unknown;
+    reportingError: unknown;
+  }) => MaybePromise<void>;
+}
+
 /**
  * Result returned by a reporting provider after capture.
  */
@@ -102,6 +141,11 @@ export type ErrorReporterPort = {
   flush(options?: ErrorReporterFlushOptions): Promise<boolean>;
 };
 
+/** Lazy reporter resolver evaluated inside the best-effort capture deadline. */
+export type ErrorReporterResolver = () => MaybePromise<
+  ErrorReporterPort | undefined
+>;
+
 /**
  * Captured exception stored by `createMemoryErrorReporter(...)`.
  */
@@ -252,6 +296,73 @@ export function reportMessage(
   return reporter.captureMessage(message, options);
 }
 
+/**
+ * Best-effort exception capture for runtime boundaries.
+ *
+ * Missing reporters, reporter failures, and reporter-failure observer errors
+ * resolve to `undefined` so diagnostics cannot replace application behavior.
+ */
+export async function tryReportException(
+  options: TryReportExceptionOptions,
+): Promise<ErrorReportResult | undefined> {
+  const reporterSource = options.reporter;
+  if (!reporterSource) return undefined;
+
+  const timeoutMs = options.timeoutMs ?? DEFAULT_ERROR_REPORTING_TIMEOUT_MS;
+
+  try {
+    return await runErrorReportingOperation(async () => {
+      const reporter =
+        typeof reporterSource === "function"
+          ? await reporterSource()
+          : reporterSource;
+      if (!reporter) return undefined;
+      return reporter.captureException(options.error, options.reportOptions);
+    }, timeoutMs);
+  } catch (reportingError) {
+    try {
+      if (options.onReporterError) {
+        await runErrorReportingOperation(
+          () =>
+            options.onReporterError?.({
+              error: options.error,
+              reportingError,
+            }),
+          errorReportingObserverTimeout(timeoutMs),
+        );
+      }
+    } catch {
+      // Reporter failure observers must not replace application behavior.
+    }
+    return undefined;
+  }
+}
+
+/**
+ * Redact structured error-report metadata with Beignet's shared sensitive-key
+ * rules. The original exception is intentionally not part of this operation.
+ */
+export function redactErrorReportOptions(
+  options: ErrorReportOptions,
+  redactionOptions: RedactionOptions = {},
+): ErrorReportOptions {
+  return {
+    ...options,
+    user: options.user
+      ? redactValue(options.user, redactionOptions)
+      : options.user,
+    tags: options.tags
+      ? redactValue(options.tags, redactionOptions)
+      : options.tags,
+    contexts: options.contexts
+      ? redactValue(options.contexts, redactionOptions)
+      : options.contexts,
+    extra: options.extra
+      ? redactValue(options.extra, redactionOptions)
+      : options.extra,
+  };
+}
+
 function withAmbientState(
   port: MemoryErrorReporterPort,
   options: ErrorReportOptions | undefined,

package/src/error-reporting/internal.ts

@@ -0,0 +1,47 @@
+type MaybePromise<T> = T | Promise<T>;
+
+export const DEFAULT_ERROR_REPORTING_TIMEOUT_MS = 1000;
+
+export class ErrorReportingTimeoutError extends Error {
+  readonly code = "ERROR_REPORTING_TIMEOUT" as const;
+  readonly timeoutMs: number;
+
+  constructor(timeoutMs: number) {
+    super(`Error reporting timed out after ${timeoutMs}ms.`);
+    this.name = "ErrorReportingTimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+export function errorReportingObserverTimeout(
+  timeoutMs: number | false,
+): number | false {
+  return timeoutMs === false || (Number.isFinite(timeoutMs) && timeoutMs > 0)
+    ? timeoutMs
+    : DEFAULT_ERROR_REPORTING_TIMEOUT_MS;
+}
+
+export async function runErrorReportingOperation<T>(
+  operation: () => MaybePromise<T>,
+  timeoutMs: number | false = DEFAULT_ERROR_REPORTING_TIMEOUT_MS,
+): Promise<T> {
+  if (timeoutMs === false) return operation();
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new TypeError("Error reporting timeoutMs must be a positive number.");
+  }
+
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      Promise.resolve().then(operation),
+      new Promise<never>((_, reject) => {
+        timeout = setTimeout(
+          () => reject(new ErrorReportingTimeoutError(timeoutMs)),
+          timeoutMs,
+        );
+      }),
+    ]);
+  } finally {
+    if (timeout !== undefined) clearTimeout(timeout);
+  }
+}

package/src/events/index.ts

@@ -1,6 +1,10 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 import { runWithResolvedTracingContext } from "../tracing/execution.js";
-import type { TracingPort } from "../tracing/index.js";
+import {
+  parseTraceCarrier,
+  type TraceCarrier,
+  type TracingPort,
+} from "../tracing/index.js";
 
 /**
  * Any Standard Schema compatible validator.
@@ -58,6 +62,12 @@ export interface EventDef<
 export type InferEventPayload<E extends EventPayloadDef> =
   E["payload"] extends StandardSchemaV1<unknown, infer Output> ? Output : never;
 
+/** Metadata propagated with an event delivery. */
+export interface EventPublishOptions {
+  /** Versioned trace context captured by the event producer. */
+  trace?: TraceCarrier;
+}
+
 /**
  * Options for `defineEvent(...)`.
  */
@@ -140,13 +150,17 @@ export interface EventBusLike {
   publish<E extends EventPayloadDef>(
     event: E,
     payload: InferEventPayload<E>,
+    options?: EventPublishOptions,
   ): MaybePromise<void>;
   /**
    * Subscribe to an event and return an unsubscribe function.
    */
   subscribe<E extends EventPayloadDef>(
     event: E,
-    handler: (payload: InferEventPayload<E>) => MaybePromise<void>,
+    handler: (
+      payload: InferEventPayload<E>,
+      options?: EventPublishOptions,
+    ) => MaybePromise<void>,
   ): () => void;
 }
 
@@ -299,9 +313,10 @@ export async function publishEvent<E extends EventPayloadDef>(
   eventBus: EventBusLike,
   event: E,
   payload: InferEventPayload<E>,
+  options?: EventPublishOptions,
 ): Promise<void> {
   const parsed = await parseEventPayload(event, payload);
-  await eventBus.publish(event, parsed);
+  await eventBus.publish(event, parsed, options);
 }
 
 /**
@@ -316,7 +331,7 @@ export function registerListeners<Ctx>(
   options: RegisterListenersOptions<Ctx> = {},
 ): () => void {
   const unsubscribes = listeners.map((listener) =>
-    eventBus.subscribe(listener.event, async (rawPayload) => {
+    eventBus.subscribe(listener.event, async (rawPayload, publishOptions) => {
       try {
         const payload = await parseEventPayload(listener.event, rawPayload);
         const traceAttributes = {
@@ -330,6 +345,7 @@ export function registerListeners<Ctx>(
             name: `beignet.listener ${listener.name}`,
             type: "listener",
             kind: "consumer",
+            parent: parseTraceCarrier(publishOptions?.trace),
             attributes: traceAttributes,
             metricAttributes: traceAttributes,
           },

package/src/idempotency/index.ts

@@ -36,6 +36,9 @@ export type IdempotencyScopeMode =
   | "tenant"
   | "actor-tenant";
 
+/** Default lifetime for unfinished idempotency reservations. */
+export const DEFAULT_IDEMPOTENCY_RESERVATION_TTL_SEC = 300;
+
 /**
  * Contract metadata for idempotency-aware routes.
  *
@@ -65,9 +68,16 @@ export interface IdempotencyMeta {
   scope?: IdempotencyScopeMode;
 
   /**
-   * Time-to-live for reserved and completed keys.
+   * Time-to-live for completed replay results.
    */
   ttlSec?: number;
+
+  /**
+   * Time-to-live for unfinished reservations.
+   *
+   * @default 300
+   */
+  reservationTtlSec?: number;
 }
 
 /**
@@ -91,9 +101,15 @@ export interface IdempotencyReserveInput {
    */
   fingerprint: string;
   /**
-   * Optional key time-to-live in seconds.
+   * Optional time-to-live for the completed replay result.
    */
   ttlSec?: number;
+  /**
+   * Time-to-live for unfinished work before a successor may reserve the key.
+   *
+   * @default 300
+   */
+  reservationTtlSec?: number;
 }
 
 /**
@@ -106,6 +122,7 @@ export type IdempotencyReservation =
       key: string;
       scopeKey: string;
       fingerprint: string;
+      reservationToken: string;
       reservedAt: Date;
       expiresAt: Date | null;
     }
@@ -161,6 +178,8 @@ export interface IdempotencyCompleteInput {
    * Fingerprint that must match the reserved operation.
    */
   fingerprint: string;
+  /** Opaque identity returned by the matching reserved result. */
+  reservationToken: string;
   /**
    * Result to replay for future matching requests.
    */
@@ -187,6 +206,8 @@ export interface IdempotencyFailInput {
    * Fingerprint that must match the reserved operation.
    */
   fingerprint: string;
+  /** Opaque identity returned by the matching reserved result. */
+  reservationToken: string;
   /**
    * Error that caused the protected operation to fail.
    */
@@ -281,6 +302,8 @@ export interface MemoryIdempotencyEntry {
    * Fingerprint of the logical command payload.
    */
   fingerprint: string;
+  /** Opaque identity of the current in-progress reservation. */
+  reservationToken: string;
   /**
    * Memory store status.
    */
@@ -388,7 +411,9 @@ type CanonicalValue =
   | readonly CanonicalValue[]
   | { readonly [key: string]: CanonicalValue };
 
-type MemoryRecord = MemoryIdempotencyEntry;
+type MemoryRecord = MemoryIdempotencyEntry & {
+  replayTtlSec?: number;
+};
 
 function assertNonEmptyString(name: string, value: string): void {
   if (typeof value !== "string" || value.trim().length === 0) {
@@ -516,6 +541,8 @@ export interface MemoryIdempotencyStoreOptions {
    * system clock.
    */
   now?: () => Date;
+  /** Token factory used for deterministic tests. */
+  createReservationToken?: () => string;
 }
 
 /**
@@ -528,6 +555,8 @@ export function createMemoryIdempotencyStore(
   options: MemoryIdempotencyStoreOptions = {},
 ): MemoryIdempotencyStore {
   const storeNow = options.now ?? (() => new Date());
+  const createReservationToken =
+    options.createReservationToken ?? createRandomReservationToken;
   const records = new Map<string, MemoryRecord>();
 
   return {
@@ -540,6 +569,7 @@ export function createMemoryIdempotencyStore(
       assertNonEmptyString("key", input.key);
       assertNonEmptyString("fingerprint", input.fingerprint);
       assertTtl(input.ttlSec);
+      assertTtl(input.reservationTtlSec);
 
       const now = storeNow();
       const storageKey = createIdempotencyStorageKey(input);
@@ -558,9 +588,14 @@ export function createMemoryIdempotencyStore(
         key: input.key,
         scopeKey: normalizeIdempotencyScope(input.scope),
         fingerprint: input.fingerprint,
+        reservationToken: createReservationToken(),
+        replayTtlSec: input.ttlSec,
         status: "in-progress",
         reservedAt: now,
-        expiresAt: resolveExpiresAt(input.ttlSec, now),
+        expiresAt: resolveExpiresAt(
+          input.reservationTtlSec ?? DEFAULT_IDEMPOTENCY_RESERVATION_TTL_SEC,
+          now,
+        ),
       };
 
       records.set(storageKey, record);
@@ -571,6 +606,7 @@ export function createMemoryIdempotencyStore(
         key: record.key,
         scopeKey: record.scopeKey,
         fingerprint: record.fingerprint,
+        reservationToken: record.reservationToken,
         reservedAt: record.reservedAt,
         expiresAt: record.expiresAt,
       };
@@ -583,11 +619,23 @@ export function createMemoryIdempotencyStore(
 
       const storageKey = createIdempotencyStorageKey(input);
       const existing = records.get(storageKey);
-      if (!existing || existing.fingerprint !== input.fingerprint) return;
+      assertNonEmptyString("reservationToken", input.reservationToken);
+      if (
+        !existing ||
+        existing.fingerprint !== input.fingerprint ||
+        existing.reservationToken !== input.reservationToken ||
+        existing.status !== "in-progress"
+      ) {
+        return;
+      }
 
       existing.status = "completed";
       existing.result = input.result;
       existing.completedAt = storeNow();
+      existing.expiresAt = resolveExpiresAt(
+        existing.replayTtlSec,
+        existing.completedAt,
+      );
     },
 
     async fail(input) {
@@ -597,8 +645,15 @@ export function createMemoryIdempotencyStore(
 
       const storageKey = createIdempotencyStorageKey(input);
       const existing = records.get(storageKey);
-      if (!existing || existing.fingerprint !== input.fingerprint) return;
-      if (existing.status === "completed") return;
+      assertNonEmptyString("reservationToken", input.reservationToken);
+      if (
+        !existing ||
+        existing.fingerprint !== input.fingerprint ||
+        existing.reservationToken !== input.reservationToken ||
+        existing.status === "completed"
+      ) {
+        return;
+      }
 
       records.delete(storageKey);
     },
@@ -627,6 +682,7 @@ export async function runIdempotently<Result>(
     scope: options.scope,
     fingerprint: options.fingerprint,
     ttlSec: options.ttlSec,
+    reservationTtlSec: options.reservationTtlSec,
   };
   const reservation = await idempotency.reserve(operation);
 
@@ -653,6 +709,7 @@ export async function runIdempotently<Result>(
           key: operation.key,
           scope: operation.scope,
           fingerprint: operation.fingerprint,
+          reservationToken: reservation.reservationToken,
           error,
         });
         throw error;
@@ -663,6 +720,7 @@ export async function runIdempotently<Result>(
         key: operation.key,
         scope: operation.scope,
         fingerprint: operation.fingerprint,
+        reservationToken: reservation.reservationToken,
         result,
       });
       return result;
@@ -676,6 +734,22 @@ export async function runIdempotently<Result>(
   }
 }
 
+function createRandomReservationToken(): string {
+  if (typeof globalThis.crypto?.randomUUID === "function") {
+    return globalThis.crypto.randomUUID();
+  }
+
+  const bytes = new Uint8Array(16);
+  globalThis.crypto?.getRandomValues?.(bytes);
+  if (bytes.some((value) => value !== 0)) {
+    return Array.from(bytes, (value) =>
+      value.toString(16).padStart(2, "0"),
+    ).join("");
+  }
+
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+
 function normalizeOmitPath(
   path: string | readonly string[],
 ): readonly string[] {

package/src/jobs/index.ts

@@ -1,7 +1,11 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 import type { LeaseHandle, LeaseMetadata, LocksPort } from "../locks/index.js";
 import { runWithResolvedTracingContext } from "../tracing/execution.js";
-import type { TracingPort } from "../tracing/index.js";
+import {
+  parseTraceCarrier,
+  type TraceCarrier,
+  type TracingPort,
+} from "../tracing/index.js";
 
 /**
  * Any Standard Schema compatible validator.
@@ -582,6 +586,73 @@ export interface InlineJobDispatcherOptions<Ctx> {
   hooks?: readonly JobHook<JobDef<string, StandardSchema, Ctx>, Ctx>[];
 }
 
+/** Metadata propagated when a job is dispatched. */
+export interface JobDispatchOptions {
+  /** Versioned trace context captured by the job producer. */
+  trace?: TraceCarrier;
+}
+
+const JOB_TRANSPORT_ENVELOPE_TYPE = "beignet.job";
+const JOB_TRANSPORT_ENVELOPE_VERSION = 1;
+
+/** Parsed payload and propagation metadata from a job transport envelope. */
+export interface ParsedJobTransportEnvelope {
+  payload: unknown;
+  trace?: TraceCarrier;
+}
+
+/**
+ * Wrap a job payload with transport metadata when a trace is present.
+ * Payloads without metadata retain their legacy wire shape.
+ */
+export function createJobTransportEnvelope(
+  payload: unknown,
+  options?: JobDispatchOptions,
+): unknown {
+  const trace = parseTraceCarrier(options?.trace);
+  if (!trace) return payload;
+
+  return {
+    __beignet: {
+      type: JOB_TRANSPORT_ENVELOPE_TYPE,
+      version: JOB_TRANSPORT_ENVELOPE_VERSION,
+      trace,
+    },
+    payload,
+  };
+}
+
+/**
+ * Decode a Beignet job transport envelope while accepting legacy raw payloads.
+ * Unknown or malformed trace metadata is ignored without dropping the payload.
+ */
+export function parseJobTransportEnvelope(
+  value: unknown,
+): ParsedJobTransportEnvelope {
+  if (typeof value !== "object" || value === null || !("payload" in value)) {
+    return { payload: value };
+  }
+
+  const metadata = "__beignet" in value ? value.__beignet : undefined;
+  if (
+    typeof metadata !== "object" ||
+    metadata === null ||
+    !("type" in metadata) ||
+    metadata.type !== JOB_TRANSPORT_ENVELOPE_TYPE ||
+    !("version" in metadata) ||
+    metadata.version !== JOB_TRANSPORT_ENVELOPE_VERSION
+  ) {
+    return { payload: value };
+  }
+
+  const trace =
+    "trace" in metadata ? parseTraceCarrier(metadata.trace) : undefined;
+  return {
+    payload: value.payload,
+    ...(trace ? { trace } : {}),
+  };
+}
+
 /**
  * Well-known symbol under which the inline dispatcher exposes a
  * single-attempt dispatch. Delivery systems that own execution retries
@@ -597,7 +668,7 @@ export const SINGLE_ATTEMPT_DISPATCH: unique symbol = Symbol.for(
  * Metadata passed to a single-attempt dispatch when another delivery layer
  * owns retry scheduling.
  */
-export interface SingleAttemptJobDispatchOptions {
+export interface SingleAttemptJobDispatchOptions extends JobDispatchOptions {
   /**
    * One-based delivery attempt.
    */
@@ -625,6 +696,7 @@ export interface JobDispatcher {
   dispatch<J extends JobDef>(
     job: J,
     payload: InferJobPayload<J>,
+    options?: JobDispatchOptions,
   ): MaybePromise<void>;
 }
 
@@ -693,6 +765,7 @@ export interface InlineJobDispatcher<Ctx = unknown> {
   dispatch<J extends JobDef<string, StandardSchema, Ctx>>(
     job: J,
     payload: InferJobPayload<J>,
+    options?: JobDispatchOptions,
   ): Promise<void>;
 }
 
@@ -1275,6 +1348,8 @@ export interface RunJobHandlerOptions<
   ctx: Ctx | (() => MaybePromise<Ctx>);
   /** Runtime tracing port used before a lazy context factory runs. */
   tracing?: TracingPort;
+  /** Trace context captured by the dispatching process. */
+  trace?: TraceCarrier;
   /**
    * Runner-level hooks. These wrap job-local hooks.
    */
@@ -1327,6 +1402,7 @@ export async function runJobHandler<
       name: `beignet.job ${args.job.name}`,
       type: "job",
       kind: "consumer",
+      parent: parseTraceCarrier(args.trace),
       attributes: traceAttributes,
       metricAttributes: traceAttributes,
     },
@@ -1485,6 +1561,7 @@ export function createInlineJobDispatcher<Ctx>(
           payload: parsed,
           ctx,
           hooks: options.hooks,
+          trace: dispatchOptions.trace,
           attempt: dispatchOptions.attempt ?? attempt,
           maxAttempts: dispatchOptions.maxAttempts ?? maxAttempts,
         });
@@ -1515,8 +1592,9 @@ export function createInlineJobDispatcher<Ctx>(
     async dispatch<J extends JobDef<string, StandardSchema, Ctx>>(
       job: J,
       payload: InferJobPayload<J>,
+      dispatchOptions?: JobDispatchOptions,
     ) {
-      await run(job, payload, options.retry !== false);
+      await run(job, payload, options.retry !== false, dispatchOptions);
     },
   };
 
@@ -1550,9 +1628,10 @@ export function createUniqueJobDispatcher(
     async dispatch<J extends JobDef>(
       job: J,
       payload: InferJobPayload<J>,
+      dispatchOptions?: JobDispatchOptions,
     ): Promise<void> {
       if (!job.unique) {
-        await options.jobs.dispatch(job, payload);
+        await options.jobs.dispatch(job, payload, dispatchOptions);
         return;
       }
 
@@ -1561,7 +1640,7 @@ export function createUniqueJobDispatcher(
         keyPrefix: options.keyPrefix,
       });
       if (!unique) {
-        await options.jobs.dispatch(job, parsed);
+        await options.jobs.dispatch(job, parsed, dispatchOptions);
         return;
       }
 
@@ -1587,7 +1666,7 @@ export function createUniqueJobDispatcher(
       }
 
       try {
-        await options.jobs.dispatch(job, parsed);
+        await options.jobs.dispatch(job, parsed, dispatchOptions);
       } catch (error) {
         try {
           await result.lease.release();