@beignet/core 0.0.36 → 0.0.38

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();

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

@@ -6,6 +6,7 @@
 
 import {
   type AnyContract,
+  type ContractDeprecationMeta,
   type ContractLike,
   getContractHeaderSchemas,
   methodSupportsRequestBody,
@@ -13,6 +14,10 @@ import {
   resolveContract,
   STANDARD_ERROR_RESPONSE_SCHEMA,
 } from "../contracts/index.js";
+import {
+  assertValidContractLifecycle,
+  getContractOperationId,
+} from "../contracts/lifecycle.js";
 import {
   comparePathParamsToTemplate,
   formatPathParamsMismatch,
@@ -235,6 +240,8 @@ export interface OperationObject {
    * Whether the operation is deprecated.
    */
   deprecated?: boolean;
+  /** Beignet lifecycle details for a deprecated operation. */
+  "x-beignet-deprecation"?: ContractDeprecationMeta;
   /**
    * External documentation.
    */
@@ -409,9 +416,20 @@ export function contractsToOpenAPI(
       createZodSchemaConverter(),
     ],
   };
+  const operationIds = new Map<string, string>();
 
   for (const contract of contracts) {
     const config = resolveContract(contract);
+    assertValidContractLifecycle(config);
+    const operationId = getContractOperationId(config);
+    const route = `${config.method} ${config.path}`;
+    const conflictingRoute = operationIds.get(operationId);
+    if (conflictingRoute) {
+      throw new Error(
+        `Duplicate OpenAPI operationId: "${operationId}" is used by both ${conflictingRoute} and ${route}. Operation IDs must be unique within an OpenAPI document.`,
+      );
+    }
+    operationIds.set(operationId, route);
     addContractToPaths(config, paths, state);
   }
 
@@ -454,13 +472,15 @@ function addContractToPaths(
   const pathItem = paths[pathKey];
 
   const meta = contract.metadata?.openapi;
+  const deprecation = contract.metadata?.deprecation;
 
   const operation: OperationObject = {
-    operationId: meta?.operationId ?? contract.name,
+    operationId: getContractOperationId(contract),
     summary: meta?.summary,
     description: meta?.description,
     tags: meta?.tags,
-    deprecated: meta?.deprecated,
+    deprecated: deprecation ? true : meta?.deprecated,
+    "x-beignet-deprecation": deprecation,
     externalDocs: meta?.externalDocs,
     security: meta?.security,
     parameters: [],