@beignet/core 0.0.3 → 0.0.4

package/src/providers/provider.ts

@@ -43,20 +43,50 @@ export interface ProviderConfigDef<CfgSchema extends StandardSchemaV1> {
  */
 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.
+ *
+ * App-local providers can type the factory by declaring `Context` and
+ * `ServiceInput` through the curried `createProvider<Requires, Context,
+ * ServiceInput>()` form. Untyped providers see `(input: void) =>
+ * Promise<unknown>`.
+ */
+export type ProviderServiceContextFactory<
+  Context = unknown,
+  ServiceInput = void,
+> = (input: ServiceInput) => Promise<Context>;
+
 /**
  * Context passed to provider lifecycle hooks.
  */
-export type ProviderLifecycleContext = {
+export type ProviderLifecycleContext<
+  Ports = ProviderPorts,
+  Context = unknown,
+  ServiceInput = void,
+> = {
   /**
    * Final app ports after provider setup.
    */
-  ports: Readonly<ProviderPorts>;
+  ports: Readonly<Ports>;
+  /**
+   * Build an app service context through the server context blueprint.
+   */
+  createServiceContext: ProviderServiceContextFactory<Context, ServiceInput>;
 };
 
 /**
  * Result returned from provider setup.
  */
-export type ProviderSetupResult<ProvidedPorts extends ProviderPorts> = {
+export type ProviderSetupResult<
+  ProvidedPorts extends ProviderPorts,
+  Ports = ProviderPorts,
+  Context = unknown,
+  ServiceInput = void,
+> = {
   /**
    * Ports contributed by this provider.
    * Keys overwrite earlier ports with the same name at runtime. Prefer unique
@@ -66,15 +96,60 @@ export type ProviderSetupResult<ProvidedPorts extends ProviderPorts> = {
 
   /**
    * Optional hook called after all providers have contributed their ports.
+   *
+   * Declared as a method so typed providers stay assignable to loosely typed
+   * provider lists. Hooks that take `ctx` with an unannotated parameter keep
+   * TypeScript from inferring `ProvidedPorts` from the returned `ports`.
+   * Prefer closing over setup locals, or annotate `ctx` with
+   * `ProviderLifecycleContext<...>`.
    */
-  start?: (ctx: ProviderLifecycleContext) => MaybePromise<void>;
+  start?(
+    ctx: ProviderLifecycleContext<Ports & ProvidedPorts, Context, ServiceInput>,
+  ): MaybePromise<void>;
 
   /**
    * Optional hook called when the server is stopped.
    */
-  stop?: (ctx: ProviderLifecycleContext) => MaybePromise<void>;
+  stop?(
+    ctx: ProviderLifecycleContext<Ports & ProvidedPorts, Context, ServiceInput>,
+  ): 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.
  *
@@ -111,12 +186,19 @@ export interface ServiceProvider<
   Ports,
   CfgSchema extends StandardSchemaV1 = StandardSchemaV1<void, void>,
   ProvidedPorts extends ProviderPorts = NoProvidedPorts,
+  Context = unknown,
+  ServiceInput = void,
 > {
   /**
    * Unique name for this provider (used for logging/debugging)
    */
   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.
@@ -130,11 +212,17 @@ 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.
    */
   setup(ctx: {
     ports: Readonly<Ports>;
     config: InferOutput<CfgSchema> | undefined;
-  }): MaybePromise<ProviderSetupResult<ProvidedPorts>>;
+    createServiceContext: ProviderServiceContextFactory<Context, ServiceInput>;
+  }): MaybePromise<
+    ProviderSetupResult<ProvidedPorts, Ports, Context, ServiceInput>
+  >;
 
   /**
    * Type-only marker for ports this provider contributes.
@@ -143,6 +231,25 @@ export interface ServiceProvider<
   readonly __providedPorts?: ProvidedPorts;
 }
 
+/**
+ * Loosely typed service provider.
+ *
+ * Required-port, config, app-context, and service-input generics are erased
+ * here so any provider created with `createProvider(...)` — including the
+ * typed curried form — stays assignable. Use this for code that works across
+ * arbitrary providers, such as provider lists and test helpers.
+ */
+export type AnyServiceProvider = ServiceProvider<
+  unknown,
+  // biome-ignore lint/suspicious/noExplicitAny: provider config types are erased at this level
+  StandardSchemaV1<any, any>,
+  ProviderPorts,
+  // biome-ignore lint/suspicious/noExplicitAny: provider context types are erased at this level
+  any,
+  // biome-ignore lint/suspicious/noExplicitAny: provider service-input types are erased at this level
+  any
+>;
+
 /**
  * Extract the ports a provider contributes.
  */
@@ -150,7 +257,9 @@ export type ProvidedPortsOf<TProvider> =
   TProvider extends ServiceProvider<
     infer _Ports,
     infer _CfgSchema,
-    infer ProvidedPorts
+    infer ProvidedPorts,
+    infer _Context,
+    infer _ServiceInput
   >
     ? ProvidedPorts
     : NoProvidedPorts;
@@ -165,8 +274,20 @@ type UnionToIntersection<T> = (
 
 /**
  * Extract and merge the ports contributed by a provider list.
+ *
+ * Use this with `typeof providers` to type provider-contributed ports in app
+ * code without hand-written casts:
+ *
+ * @example
+ * ```ts
+ * import type { InferProviderPorts } from "@beignet/core/providers";
+ * import type { providers } from "@/server/providers";
+ * import type { AppPorts } from "@/ports";
+ *
+ * export type AppRuntimePorts = AppPorts & InferProviderPorts<typeof providers>;
+ * ```
  */
-export type ProvidedPortsOfList<TProviders> =
+export type InferProviderPorts<TProviders> =
   TProviders extends readonly unknown[]
     ? [TProviders[number]] extends [never]
       ? NoProvidedPorts
@@ -179,6 +300,11 @@ export type ProvidedPortsOfList<TProviders> =
  * This is a simple identity function that helps TypeScript infer the correct types
  * for the provider definition.
  *
+ * App-local providers can use the curried zero-argument form to declare the
+ * ports they require from earlier providers plus their app context and
+ * service-context input. The required ports, `ctx.ports`, and
+ * `ctx.createServiceContext` are then fully typed with no casts.
+ *
  * @example
  * ```ts
  * export const myProvider = createProvider({
@@ -191,14 +317,47 @@ export type ProvidedPortsOfList<TProviders> =
  *     return { ports: { myService: createMyService(config) } };
  *   },
  * });
+ *
+ * // Typed app-local provider:
+ * export const appDatabaseProvider = createProvider<
+ *   { db: DbPort<typeof schema>; devtools?: DevtoolsPort },
+ *   AppContext,
+ *   AppServiceContextInput
+ * >()({
+ *   name: "app-database",
+ *   async setup({ ports, createServiceContext }) {
+ *     const repositories = createRepositories(ports.db.db);
+ *     return { ports: repositories };
+ *   },
+ * });
  * ```
  */
+export function createProvider<
+  Requires = unknown,
+  Context = unknown,
+  ServiceInput = void,
+>(): <
+  CfgSchema extends StandardSchemaV1 = StandardSchemaV1<void, void>,
+  Provided extends ProviderPorts = NoProvidedPorts,
+>(
+  def: ServiceProvider<Requires, CfgSchema, Provided, Context, ServiceInput>,
+) => ServiceProvider<Requires, CfgSchema, Provided, Context, ServiceInput>;
 export function createProvider<
   Ports = unknown,
   CfgSchema extends StandardSchemaV1 = StandardSchemaV1<void, void>,
   ProvidedPorts extends ProviderPorts = NoProvidedPorts,
 >(
   def: ServiceProvider<Ports, CfgSchema, ProvidedPorts>,
-): ServiceProvider<Ports, CfgSchema, ProvidedPorts> {
+): ServiceProvider<Ports, CfgSchema, ProvidedPorts>;
+export function createProvider(
+  def?: ServiceProvider<unknown, StandardSchemaV1, ProviderPorts>,
+):
+  | ServiceProvider<unknown, StandardSchemaV1, ProviderPorts>
+  | ((
+      definition: ServiceProvider<unknown, StandardSchemaV1, ProviderPorts>,
+    ) => ServiceProvider<unknown, StandardSchemaV1, ProviderPorts>) {
+  if (def === undefined) {
+    return (definition) => definition;
+  }
   return def;
 }

package/src/schedules/index.ts

@@ -29,6 +29,10 @@ export interface ScheduleRunContext {
    * Optional provider run ID.
    */
   readonly id?: string;
+  /**
+   * One-based provider attempt number for this run, when available.
+   */
+  readonly attempt?: number;
   /**
    * Time the provider planned the run.
    */
@@ -190,6 +194,10 @@ export interface ScheduleRunOptions<Payload = unknown> {
    * Optional provider run ID.
    */
   id?: string;
+  /**
+   * One-based provider attempt number for this run, when available.
+   */
+  attempt?: number;
   /**
    * Time the provider planned the run.
    */
@@ -262,6 +270,72 @@ export interface ScheduleErrorArgs<S extends ScheduleDef = ScheduleDef> {
  */
 export type ScheduleHookName = "start" | "success" | "error";
 
+/**
+ * Devtools event recorded by the inline schedule runner for each run.
+ */
+export interface ScheduleDevtoolsEvent {
+  /**
+   * Devtools event type.
+   */
+  type: "schedule";
+  /**
+   * Watcher category used by devtools.
+   */
+  watcher: "schedules";
+  /**
+   * Stable schedule name.
+   */
+  scheduleName: string;
+  /**
+   * Schedule run lifecycle status.
+   */
+  status: "started" | "completed" | "failed";
+  /**
+   * Cron expression for the schedule.
+   */
+  cron: string;
+  /**
+   * IANA timezone for the schedule, when declared.
+   */
+  timezone?: string;
+  /**
+   * Request correlation ID, when the trigger ran inside a request.
+   */
+  requestId?: string;
+  /**
+   * Trace identifier for distributed tracing integrations.
+   */
+  traceId?: string;
+  /**
+   * Structured run details such as `source`, `scheduledAt`, and `error`.
+   */
+  details?: Record<string, unknown>;
+}
+
+/**
+ * Sink for schedule devtools events, usually `ctx.ports.devtools`.
+ */
+export interface ScheduleInstrumentation {
+  /**
+   * Record one schedule devtools event.
+   */
+  record(event: ScheduleDevtoolsEvent): unknown;
+}
+
+/**
+ * Correlation fields attached to schedule instrumentation events.
+ */
+export interface ScheduleInstrumentationContext {
+  /**
+   * Request correlation ID for the triggering invocation.
+   */
+  requestId?: string;
+  /**
+   * Trace identifier for the triggering invocation.
+   */
+  traceId?: string;
+}
+
 /**
  * Arguments passed when a schedule lifecycle hook itself fails.
  */
@@ -304,6 +378,18 @@ export interface InlineScheduleRunnerOptions<Ctx> {
    * Clock used when run timestamps are not provided.
    */
   now?: () => Date;
+  /**
+   * Devtools-compatible sink that receives `schedule` events for each run.
+   *
+   * The runner records `started`, `completed`, and `failed` events. Recording
+   * failures are isolated from schedule execution and reported to
+   * `onHookError` when provided.
+   */
+  instrumentation?: ScheduleInstrumentation;
+  /**
+   * Correlation fields attached to recorded schedule events.
+   */
+  instrumentationContext?: ScheduleInstrumentationContext;
   /**
    * Called after payload validation and before the schedule handler.
    */
@@ -352,7 +438,7 @@ export interface InlineScheduleRunner<Ctx = unknown>
 /**
  * Context-bound schedule helper factory.
  */
-export interface ScheduleHandlers<Ctx> {
+export interface Schedules<Ctx> {
   /**
    * Define a schedule with the bound context type.
    */
@@ -360,13 +446,6 @@ export interface ScheduleHandlers<Ctx> {
     name: Name,
     options: DefineScheduleOptions<Name, Payload, Ctx>,
   ): ScheduleDef<Name, Payload, Ctx>;
-
-  /**
-   * Create an inline schedule runner with the bound context type.
-   */
-  createInlineScheduleRunner(
-    options?: InlineScheduleRunnerOptions<Ctx>,
-  ): InlineScheduleRunner<Ctx>;
 }
 
 /**
@@ -469,12 +548,27 @@ function normalizeOptionalDate(
   return normalizeDate(value, field, () => new Date());
 }
 
+function normalizeOptionalAttempt(
+  value: number | undefined,
+): number | undefined {
+  if (value === undefined) return undefined;
+
+  if (!Number.isInteger(value) || value < 1) {
+    throw new ScheduleRunContextError(
+      "Schedule run attempt must be a positive integer.",
+    );
+  }
+
+  return value;
+}
+
 function createRunContext(
   options: ScheduleRunOptions<unknown>,
   now: () => Date,
 ): ScheduleRunContext {
   return {
     id: options.id,
+    attempt: normalizeOptionalAttempt(options.attempt),
     scheduledAt: normalizeOptionalDate(options.scheduledAt, "scheduledAt"),
     triggeredAt: normalizeDate(options.triggeredAt, "triggeredAt", now),
     source: options.source,
@@ -556,13 +650,52 @@ async function runErrorHook<
   }
 }
 
-/**
- * Define a typed schedule.
- *
- * Cron and timezone are metadata for schedule providers. The inline runner only
- * runs schedules when its `run(...)` method is called.
- */
-export function defineSchedule<
+async function recordScheduleEvent<
+  Ctx,
+  S extends ScheduleDef<string, StandardSchema, Ctx>,
+>(
+  options: InlineScheduleRunnerOptions<Ctx>,
+  schedule: S,
+  status: ScheduleDevtoolsEvent["status"],
+  run: ScheduleRunContext,
+  args: {
+    payload?: InferSchedulePayload<S>;
+    hook: ScheduleHookName;
+    scheduleError?: unknown;
+    details?: Record<string, unknown>;
+  },
+): Promise<void> {
+  if (!options.instrumentation) return;
+
+  try {
+    options.instrumentation.record({
+      type: "schedule",
+      watcher: "schedules",
+      requestId: options.instrumentationContext?.requestId,
+      traceId: options.instrumentationContext?.traceId,
+      scheduleName: schedule.name,
+      status,
+      cron: schedule.cron,
+      timezone: schedule.timezone,
+      details: {
+        source: run.source,
+        scheduledAt: run.scheduledAt?.toISOString(),
+        ...args.details,
+      },
+    });
+  } catch (error) {
+    await reportHookError(options.onHookError, {
+      schedule,
+      payload: args.payload,
+      run,
+      hook: args.hook,
+      error,
+      scheduleError: args.scheduleError,
+    });
+  }
+}
+
+function defineScheduleImpl<
   Name extends string,
   Payload extends StandardSchema,
   Ctx = unknown,
@@ -637,6 +770,10 @@ export function createInlineScheduleRunner<Ctx>(
         payload = await resolveSchedulePayload(schedule, runOptions, run);
 
         const lifecycleArgs = { schedule, payload, run };
+        await recordScheduleEvent(options, schedule, "started", run, {
+          payload,
+          hook: "start",
+        });
         await runLifecycleHook(
           "start",
           options.onStart,
@@ -649,6 +786,10 @@ export function createInlineScheduleRunner<Ctx>(
           ctx: await resolveCtx(options.ctx),
           run,
         });
+        await recordScheduleEvent(options, schedule, "completed", run, {
+          payload,
+          hook: "success",
+        });
         await runLifecycleHook(
           "success",
           options.onSuccess,
@@ -656,6 +797,12 @@ export function createInlineScheduleRunner<Ctx>(
           lifecycleArgs,
         );
       } catch (error) {
+        await recordScheduleEvent(options, schedule, "failed", run, {
+          payload,
+          hook: "error",
+          scheduleError: error,
+          details: { error },
+        });
         await runErrorHook(options.onError, options.onHookError, {
           error,
           schedule,
@@ -670,20 +817,23 @@ export function createInlineScheduleRunner<Ctx>(
 
 /**
  * Create schedule helper methods bound to an application context type.
+ *
+ * Call it once in `lib/schedules.ts`:
+ *
+ * ```ts
+ * export const { defineSchedule } = createSchedules<AppContext>();
+ * ```
+ *
+ * Cron and timezone are metadata for schedule providers. The inline runner only
+ * runs schedules when its `run(...)` method is called.
  */
-export function createScheduleHandlers<Ctx>(): ScheduleHandlers<Ctx> {
+export function createSchedules<Ctx>(): Schedules<Ctx> {
   return {
     defineSchedule<Name extends string, Payload extends StandardSchema>(
       name: Name,
       options: DefineScheduleOptions<Name, Payload, Ctx>,
     ): ScheduleDef<Name, Payload, Ctx> {
-      return defineSchedule(name, options);
-    },
-
-    createInlineScheduleRunner(
-      options: InlineScheduleRunnerOptions<Ctx> = {},
-    ): InlineScheduleRunner<Ctx> {
-      return createInlineScheduleRunner(options);
+      return defineScheduleImpl(name, options);
     },
   };
 }

package/src/server/audit-context.ts

@@ -0,0 +1,45 @@
+import type { AuditLogPort } from "../ports/index.js";
+import { getActiveRequestContext } from "./request-context.js";
+
+/**
+ * Wrap an audit log port so missing `actor`, `tenant`, `requestId`, and
+ * `traceId` fields are filled from the ambient request context at record time.
+ *
+ * The server keeps the ambient context current for requests (including
+ * identity elevated by hooks) and for service contexts created for jobs,
+ * listeners, schedules, and tasks. Because enrichment happens when
+ * `record(...)` runs, the wrapper also works for ports rebuilt per
+ * transaction inside a unit of work — wrap both the top-level audit port and
+ * the per-transaction rebuild.
+ *
+ * Fields provided on the entry always win; only missing fields are filled.
+ * When no ambient context is active (for example on runtimes without
+ * `AsyncLocalStorage` propagation), entries pass through unchanged.
+ *
+ * @example
+ * ```ts
+ * const audit = createAmbientAuditLog(
+ *   createInstrumentedAuditLog({ audit: createDrizzleAuditLog(db), instrumentation: ports }),
+ * );
+ * await audit.record({ action: "posts.publish", resource: { type: "post", id } });
+ * ```
+ *
+ * @param audit - Underlying audit log port to write enriched entries to.
+ * @returns An audit log port that fills missing context fields before writing.
+ */
+export function createAmbientAuditLog(audit: AuditLogPort): AuditLogPort {
+  return {
+    record(entry) {
+      const context = getActiveRequestContext();
+      if (!context) return audit.record(entry);
+
+      return audit.record({
+        ...entry,
+        actor: entry.actor ?? context.actor,
+        tenant: entry.tenant ?? context.tenant,
+        requestId: entry.requestId ?? context.requestId,
+        traceId: entry.traceId ?? context.traceId,
+      });
+    },
+  };
+}