@beignet/core

Runtime: Beignet requires Node.js 22.12 or newer. Bun is optional.

Core framework primitives for Beignet

This package provides Beignet's framework primitives: contracts, server runtime, typed client, use cases, agent capabilities, ports, domain helpers, app errors, config, events, idempotency, locks, outbox, mail, notifications, payments, search, webhooks, feature flags, error reporting, schedules, uploads, entitlements, pagination helpers, testing helpers, and OpenAPI generation.

Installation

npm install @beignet/core

# Use with your preferred Standard Schema library
npm install zod
# or
npm install valibot
# or
npm install arktype
Copy

TypeScript requirements

This package requires TypeScript 5.0 or higher for proper type inference.

Agent skills

This package ships a TanStack Intent skill for coding agents: @beignet/core#app-architecture. Load it when adding or fixing Beignet schemas, contracts, use cases, app errors, ports, policies, app context, providers, domain events, workflow primitives, seeds, tests, or core subpath imports.

Subpaths

Install @beignet/core once, then import the framework area you need. The package intentionally has no root entrypoint; use explicit subpaths so imports name the framework area they depend on.

Use boundary markers as side-effect imports so local linting and formatting do not treat them as unused symbols:

import "@beignet/core/client-only";
import "@beignet/core/server-only";
Copy

Agent capabilities

Agent capabilities are validated application entrypoints for authenticated AI agent transports. Definitions remain transport-neutral and should delegate business behavior to the same use cases called by HTTP routes, jobs, and scripts.

import {
  createAgentCapabilities,
  createAgentCapabilityExecutor,
} from "@beignet/core/agent-capabilities";
import { z } from "zod";
import type { AppContext } from "@/app-context";
import { createIssueUseCase } from "@/features/issues/use-cases";

type AgentPrincipal = { agentId: string; userId: string };

const { defineAgentCapability, defineAgentCapabilityRegistry } =
  createAgentCapabilities<AppContext, AgentPrincipal>();

const createIssue = defineAgentCapability("issues.create", {
  description: "Create an issue in one workspace.",
  input: z.object({ workspaceId: z.string(), title: z.string().min(1) }),
  output: z.object({ id: z.string(), title: z.string() }),
  async handle({ ctx, input }) {
    const { workspaceId: _workspaceId, ...useCaseInput } = input;
    return createIssueUseCase.run({ ctx, input: useCaseInput });
  },
});

const registry = defineAgentCapabilityRegistry([createIssue]);

export const executor = createAgentCapabilityExecutor({
  registry,
  async createContext({ principal, input }) {
    const server = await import("@/server").then(({ getServer }) => getServer());
    const membership = await server.ports.members.findMembership({
      workspaceId: input.workspaceId,
      userId: principal.userId,
    });
    if (!membership) throw new Error("Not a workspace member");

    return server.createServiceContext({
      asUser: { id: principal.userId, role: membership.role },
      tenantId: input.workspaceId,
    });
  },
});
Copy

Input is validated before createContext(...) runs. Output is validated before it reaches the transport. Context construction remains app-owned: authenticate the transport first, re-read tenant membership from an authoritative port, and call server.createServiceContext(...) instead of assembling AppContext by hand. Use @beignet/agent-auth-better-auth to expose a registry through Better Auth Agent Auth.

Registry creation comes from the same app-bound factory as defineAgentCapability, so definitions with another context or principal type are rejected. Executor hooks observe the complete attempt and include a stage. Completion events contain the capability, context, principal, validated input, validated output, and duration. Failure events expose context and validated input only when execution reached those stages; raw malformed input and unvalidated output are not exposed. Dynamic transport adapters may provide authorize(...) to inspect the exact parsed input before context construction without causing a second validation pass. Pass an independent instrumentation target and tracing port to the executor when lookup, input-validation, and context failures must be visible before an app context exists. Without those options, successful context construction lets the executor derive observability ports from ctx.

Durable failure language

Jobs, outbox delivery, and schedule runners use the same terms:

• attempt is the one-based execution or delivery attempt currently being handled.
• attempts in a retry policy is the maximum total attempts, including the first try.
• backoff is the delay before the next retry.
• timeout is the maximum execution window for one handler attempt.
• hook is app-owned behavior that wraps one handler attempt.
• execution lease is a TTL-backed lock around one handler attempt for a logical job key.
• terminal failure means the work should not be retried automatically.
• dead letter is a durable terminal delivery state, currently owned by the outbox.

Error reporting follows the same terminal boundary. Retry attempts stay in logs and instrumentation; exhausted or non-retryable work becomes an incident. Runtime owners can use tryReportException(...) when reporting must never replace application behavior:

import { tryReportException } from "@beignet/core/error-reporting";

await tryReportException({
  reporter: ctx.ports.errorReporter,
  error,
  reportOptions: {
    mechanism: "app.import",
    tags: { "beignet.kind": "task" },
  },
});
Copy

Best-effort capture and its failure observer are each bounded to one second by default. Set timeoutMs to a different positive duration, or explicitly use false only for a reporter that is intentionally allowed to block the owning runtime boundary. Timeouts surface to onReporterError as ErrorReportingTimeoutError and otherwise resolve to undefined.

redactErrorReportOptions(...) applies Beignet's shared sensitive-key rules to structured user, tag, context, and extra metadata. It intentionally does not rewrite the original exception message or stack.

Jobs may also declare dispatch-time uniqueness and execution leases:

import {
  createJobExecutionLeaseHook,
  createInlineJobDispatcher,
  createJobs,
  createUniqueJobDispatcher,
  type JobDef,
  retry,
} from "@beignet/core/jobs";
import type { LocksPort } from "@beignet/core/locks";
import { z } from "zod";

type AppContext = {
  ports: {
    billing: {
      syncAccount(
        accountId: string,
        options?: { signal?: AbortSignal },
      ): Promise<void>;
    };
    locks: LocksPort;
  };
};

const { defineJob } = createJobs<AppContext>();

const syncAccountPayloadSchema = z.object({
  accountId: z.string().min(1),
});

const syncAccountExecutionLease = createJobExecutionLeaseHook<
  JobDef<"billing.sync-account", typeof syncAccountPayloadSchema, AppContext>,
  AppContext
>({
  locks: ({ ctx }) => ctx.ports.locks,
  key: ({ payload }) => payload.accountId,
  ttl: "5m",
});

export const SyncAccountJob = defineJob("billing.sync-account", {
  payload: syncAccountPayloadSchema,
  unique: ({ payload }) => ({
    key: payload.accountId,
    ttl: "10m",
  }),
  timeout: "30s",
  retry: retry.exponential({ attempts: 3 }),
  hooks: [syncAccountExecutionLease],
  async handle({ payload, ctx, signal }) {
    await ctx.ports.billing.syncAccount(payload.accountId, { signal });
  },
});

export function createJobsPort(ctx: AppContext) {
  return createUniqueJobDispatcher({
    jobs: createInlineJobDispatcher<AppContext>({ ctx }),
    locks: ctx.ports.locks,
  });
}
Copy

unique suppresses duplicate dispatches while the resolved lock key's TTL is active. It does not replace handler idempotency: providers may still execute a queued job more than once after a worker crash or retry. Dispatcher and transport boundaries validate the payload but preserve the original JSON-safe value for the next boundary. The runner parses immediately before handler execution, so transforming schemas produce the handler value exactly once.

timeout bounds each handler attempt. When the timeout expires, Beignet throws JobTimeoutError, aborts the handler's signal, and lets the job retry policy decide whether the timeout should retry. Cancellation is cooperative: a handler that ignores the signal can keep running while a retry-capable runner starts another attempt. Propagate the signal, keep the handler idempotent, and treat the timeout as terminal when overlapping attempts would be unsafe.

hooks wrap each handler attempt when the job runs through a Beignet dispatcher or worker helper. Runner-level hooks, such as createInlineJobDispatcher({ hooks }), wrap job-local hooks. Hook failures are classified by the same retry policy as handler failures. When a runner can report attempt metadata, hooks receive Beignet's one-based attempt and maxAttempts values. Direct job.handle(...) calls bypass hooks; use runJobHandler(...) or a dispatcher when a test needs hook behavior.

createJobExecutionLeaseHook(...) is the first built-in hook helper. It acquires a TTL-backed LocksPort lease for one handler attempt, then releases best effort in finally. It does not start renewal loops, so serverless entrypoints can use it with a shared locks provider; the TTL remains the safety boundary if the runtime terminates early. Unavailable leases skip by default, or can throw JobExecutionLeaseUnavailableError for retry classification.

Schedules do not own retry policies. They can carry provider attempt metadata through ScheduleRunContext.attempt, then dispatch jobs or outbox messages when the work needs Beignet-managed retry and dead-letter behavior.

Outbox drains emit first-class provider instrumentation for delivered, retried, and dead-lettered messages when you pass a devtools or instrumentation port to drainOutbox(...). Pass instrumentationContext when the worker has request or trace IDs that should connect the drain to devtools rows.

Best-effort work

BestEffortWorkPort lets application code request non-durable follow-up work without waiting for it in the originating operation:

import type { BestEffortWorkPort } from "@beignet/core/ports";

export type AppPorts = {
  bestEffortWork: BestEffortWorkPort;
};

ctx.ports.bestEffortWork.defer(() =>
  ctx.ports.workspaceBroadcast.publish(workspaceId, message),
);
Copy

Use it only when losing the callback does not change the operation's result, such as publishing a cache-invalidation hint after the authoritative write has committed. The adapter owns scheduler and callback error isolation. Use a job or transaction-scoped outbox when work must be retried or survive process termination.

Tests can use createRecordingBestEffortWork() directly or the default bestEffortWork returned by createTestPorts(...). Call fixture.flushBestEffortWork() to run the current queued batch deterministically; callbacks deferred by that batch remain pending until the next flush. A flush attempts the complete batch before rejecting with any callback failures.

Event subscriptions

Beignet event payloads are canonical JSON transport data. publishEvent(...), use-case event helpers, buffered recorder flushes, and outbox helpers parse the payload, convert the output to strict JSON, and validate the decoded JSON again. They throw EventTransportError before publication or durable recording when the output is not JSON-safe or changes under repeated validation. Use strings or numbers for timestamps rather than Date, and keep schema transforms idempotent. Keep validation deterministic and side-effect-free because Beignet can run it at producer and receiving boundaries. A transform such as z.string().trim() is valid because parsing its canonical output does not change it.

EventBusPort.subscribe(...) returns an EventSubscription with a ready promise and asynchronous, idempotent unsubscribe() method. Await ready before advertising that a process can receive events, and await unsubscribe() during shutdown. The memory adapter is ready immediately; transport adapters resolve readiness only after their initial subscription is active.

registerListeners(...) combines a listener registry into one subscription. It waits for every child subscription and applies one 10-second registration deadline by default. When setup fails or times out, Beignet starts every child cleanup within the remaining deadline. If cleanup does not settle in time, ready rejects with both the startup failure and a ListenerRegistrationCleanupTimeoutError instead of hanging startup. Set readyTimeoutMs when the process needs a different bounded startup policy. Normal teardown after successful readiness still awaits transport cleanup; apply a host-level shutdown deadline when required. Readiness is an initial lifecycle signal, not an ongoing health check or durability guarantee.

An app-owned EventBusPort adapter must call prepareEventPayloadForTransport(...) before publication. An in-process adapter delivers the returned payload and forwards the complete publishOptions object to subscribers. A serialized adapter encodes transportValue, sends documented metadata such as the trace carrier, and lets registerListeners(...) validate the decoded payload again at the receiving boundary.

Provider-contributed ports

Apps bind app-owned ports directly and defer the rest to providers with the curried definePorts<AppPorts>()({ bound, deferred }) form. Deferred keys boot as throwing placeholders, and createServer(...) fails startup with the unbound key list unless onUnboundPorts is set to "warn" or "ignore".

import { definePorts } from "@beignet/core/ports";
import type { AppPorts } from "@/ports";

export const initialPorts = definePorts<AppPorts>()({
  bound: { gate },
  deferred: ["db", "logger", "mailer", "storage"],
});
Copy

Use InferProviderPorts with an as const provider list to type the runtime ports without casts:

import type { InferProviderPorts } from "@beignet/core/providers";
import type { AppPorts } from "@/ports";
import type { providers } from "@/server/providers";

export type AppRuntimePorts = AppPorts & InferProviderPorts<typeof providers>;
Copy

Reusable provider packages should export a named ServiceProvider return type and use AnyProviderConfigSchema<Config> for its config generic. That keeps a private Zod or other Standard Schema implementation out of the package declaration while preserving the validated config output and exact contributed-port inference. App-local providers should keep their concrete schema inference because they do not have a package compatibility boundary.

App-local providers can declare required ports, app context, and service-context input through the curried createProvider() form. setup then receives typed ports and a createServiceContext factory that returns the app context:

import { createProvider } from "@beignet/core/providers";

export const appDatabaseProvider = createProvider<
  { db: DbPort<typeof schema>; devtools?: DevtoolsPort },
  AppContext,
  AppServiceContextInput
>()({
  name: "app-database",
  async setup({ ports, createServiceContext }) {
    const repositories = createRepositories(ports.db.drizzle);
    return { ports: repositories };
  },
});
Copy

Lifecycle hooks returned from setup should close over setup locals; a start(ctx) hook with an unannotated parameter keeps TypeScript from inferring the provided ports from the returned ports object.

Dev-default providers

Core ships provider factories for the mail and notifications ports so apps can defer those ports before choosing production infrastructure.

createMemoryMailerProvider(options?) contributes { mailer: MailerPort } backed by createMemoryMailer(...). Deliveries are captured in memory and recorded as mail.sent devtools events through the mail watcher when an instrumentation port is installed. Instrumentation records only the provider, recipient count, delivery ID, and duration; it does not record addresses, subjects, or message bodies. Options extend CreateMemoryMailerOptions (defaultFrom, now, id, onSend) plus a provider name that defaults to "memory-mailer".

The shared address formatter used by Beignet's Resend and SMTP providers rejects carriage returns and line feeds in email addresses and display names, and safely escapes quoted display names. This blocks address fields from injecting additional mail header lines; providers still own full email-syntax validation.

createInlineNotificationsProvider(options?) contributes { notifications: NotificationPort } backed by createInlineNotificationDispatcher(...). Channel handlers receive an app service context built lazily through the server context blueprint on each send, so registration order does not matter. One failed channel does not block the remaining channels. Inline sends return ordered sent, skipped, and failed results; queued dispatchers also return queued. Set failureMode: "throw" to reject after every channel has run. Options also accept an app-owned preferences evaluator, the dispatcher's onError result mapper, and a provider name that defaults to "inline-notifications".

// server/providers.ts
import { createMemoryMailerProvider } from "@beignet/core/mail";
import { createInlineNotificationsProvider } from "@beignet/core/notifications";

export const providers = [
  createMemoryMailerProvider({
    defaultFrom: "App <noreply@example.local>",
  }),
  createInlineNotificationsProvider(),
] as const;
Copy

Replace createMemoryMailerProvider(...) with a real mail provider such as @beignet/provider-mail-resend for production delivery. Production apps can keep the inline provider or define a central notification registry and a defineNotificationDeliveryJob(...). Install createQueuedNotificationsProvider(...) after the app's jobs provider to enqueue one independently retryable job per channel. Register the delivery job with every BullMQ/Inngest worker or outbox registry that can receive it.

// server/notifications.ts
import {
  defineNotificationDeliveryJob,
  defineNotificationRegistry,
} from "@beignet/core/notifications";
import type { AppContext } from "@/app-context";
import { WelcomeNotification } from "@/features/users/notifications";

export const notificationRegistry = defineNotificationRegistry<AppContext>([
  WelcomeNotification,
]);

export const DeliverNotificationJob =
  defineNotificationDeliveryJob<AppContext>({
    registry: notificationRegistry,
  });
Copy

// server/index.ts
import { createQueuedNotificationsProvider } from "@beignet/core/notifications";
import { createNextServer, createNextServerLoader } from "@beignet/next";

export const getServer = createNextServerLoader(async () => {
  const { providers } = await import("./providers");
  const { DeliverNotificationJob } = await import("./notifications");

  return createNextServer({
    // ...
    providers: [
      ...providers,
      createQueuedNotificationsProvider({
        deliveryJob: DeliverNotificationJob,
      }),
    ],
  });
});
Copy

The delivery job defaults to three attempts with exponential backoff. The queued dispatcher validates notification payloads before enqueueing and uses the app's existing jobs port, so the same setup works with direct job providers or createOutboxJobDispatcher(...).

Entitlements

Use @beignet/core/entitlements for product access decisions derived from app-owned billing or plan state. The resolver maps durable app state to allow/deny decisions; requireEntitlement(...) enforces the decision from a use case and throws a framework-owned 403 by default.

import {
  createEntitlements,
  type EntitlementDecisionObserver,
  requireEntitlement,
} from "@beignet/core/entitlements";
import { createTenant } from "@beignet/core/ports";
import { createTenantScope } from "@beignet/core/tenancy";

function createBillingEntitlements(
  billing: BillingRepository,
  recordDecision?: EntitlementDecisionObserver,
) {
  return createEntitlements({
    async inspect(input) {
      if (input.subject.type !== "tenant") return false;
      const account = await billing.findByTenantScope(
        createTenantScope(createTenant(input.subject.id)),
      );
      return account?.status === "active";
    },
    onDecision: recordDecision,
  });
}

await requireEntitlement(ctx, {
  entitlement: "todos.create",
  subject: { type: "tenant", id: tenantId },
});
Copy

onDecision is diagnostic only. Observer errors are ignored and cannot change the entitlement result.

Feature flags

Use @beignet/core/flags for typed feature flag definitions and provider-neutral evaluation. Flags always carry a default value, and provider failures return that default instead of throwing into product workflows.

import { defineFlag, defineFlags } from "@beignet/core/flags";

export const billingFlags = defineFlags({
  newCheckout: defineFlag.boolean("billing.new-checkout", {
    default: false,
  }),
});

const enabled = await ctx.ports.flags.evaluate(billingFlags.newCheckout, {
  context: {
    targetingKey: ctx.actor.id,
    tenant: ctx.tenant,
    requestId: ctx.requestId,
  },
});
Copy

Plain evaluation does not record exposure. Call recordExposure(...) explicitly when a user actually sees or can be affected by the flagged behavior. Use createMemoryFlags(...) or createStaticFlags(...) in tests, or install @beignet/provider-flags-openfeature for production providers. String and number flags widen to string and number by default; pass a generic when an app wants a closed variant union.

Error reporting

Use @beignet/core/error-reporting for provider-neutral exception and message capture. The port accepts severity, tags, user, contexts, extra metadata, and request/trace correlation IDs.

import { createMemoryErrorReporter } from "@beignet/core/error-reporting";
import { createErrorReportingHooks } from "@beignet/core/server";
import type { AppContext } from "@/app-context";

await ctx.ports.errorReporter.captureException(error, {
  level: "error",
  requestId: ctx.requestId,
  traceId: ctx.traceId,
  tags: { feature: "billing" },
});

const errorReporter = createMemoryErrorReporter();

export const hooks = [createErrorReportingHooks<AppContext>()];
Copy

Use createMemoryErrorReporter(...) in tests, createNoopErrorReporter() when an app needs a bound port without capture, and createErrorReportingHooks(...) in server/index.ts to capture unexpected HTTP failures without changing response mapping. Install @beignet/provider-error-reporting-sentry for production providers.

Locks and leases

Use @beignet/core/locks for provider-neutral lease-backed lock coordination. Locks prevent overlapping schedules, singleton jobs, cache stampedes, and short critical sections across multiple workers or servers.

import { createMemoryLocks } from "@beignet/core/locks";

await ctx.ports.locks.withLease(
  "schedule:daily-report",
  { ttlMs: 60_000, waitMs: 0 },
  async ({ lease }) => {
    await runDailyReport(ctx, { fencingToken: lease.fencingToken });
  },
);

const locks = createMemoryLocks();
Copy

To resume ownership in a later invocation, call locks.restore(key, ownerToken, { ttlMs, expiresAt?, fencingToken? }) with persisted state. The required ttlMs becomes the default for renew(); omitted expiry and fencing metadata stay unknown. Stale handles cannot delete or renew a newer owner's lease.

Use createMemoryLocks(...) in tests, createMemoryLocksProvider() for local provider wiring, or install @beignet/provider-locks-redis for production leases.

Search

Use @beignet/core/search for provider-neutral search index definitions, document indexing, and querying searchable read models.

import { defineSearchIndex } from "@beignet/core/search";

const issueSearchIndex = defineSearchIndex("issues", {
  searchableAttributes: ["key", "title", "description"],
  filterableAttributes: ["tenantId", "status"],
  sortableAttributes: ["createdAt"],
});

await ctx.ports.search.indexDocuments(issueSearchIndex, issueDocument);

const results = await ctx.ports.search.search(issueSearchIndex, {
  query: "billing",
  filters: { tenantId },
  sort: ["createdAt:desc"],
  limit: 20,
});
Copy

Use createMemorySearch(...) in tests, createMemorySearchProvider() for local provider wiring, or install @beignet/provider-search-meilisearch for production search. Search instrumentation records the index, result count, and query length. It does not record query text or document bodies. Provider adapters may require query fields to be declared in the index metadata. For Meilisearch, filters and facets must use filterableAttributes, and sort must use sortableAttributes.

Storage

Use StoragePort for provider-neutral object storage and createMemoryStorage() in tests. Storage keys are relative object paths with one shared contract across memory, local disk, S3, and Vercel Blob adapters.

Custom storage adapters can reuse the same validation, prefix, and public-URL behavior:

import {
  assertValidStorageKey,
  createStoragePublicUrl,
  normalizeStorageKeyPrefix,
  prefixStorageKey,
} from "@beignet/core/ports";

assertValidStorageKey("projects/report.json");

const keyPrefix = normalizeStorageKeyPrefix("/production/");
const providerKey = prefixStorageKey({
  keyPrefix,
  key: "projects/report.json",
});
const publicUrl = createStoragePublicUrl({
  publicBaseUrl: "https://assets.example.com",
  key: providerKey,
});
Copy

The shared assertion rejects empty keys, control characters, leading or trailing slashes, backslashes, empty segments, and . / .. segments. Provider adapters may add narrower restrictions for their own internal namespaces.

StoragePort.get(...) returns a one-shot StorageObjectBody. Consume one of its body methods, or call await object.cancel() when only inspecting metadata so providers can release unread streams, sockets, or file snapshots. Prefer stat(...) for metadata-only lookups.

Uploads

Use @beignet/core/uploads for typed file workflows above StoragePort. Upload definitions own metadata validation, authorization, storage keys, file constraints, direct-upload signing, and completion hooks.

import { createUploads } from "@beignet/core/uploads";
import { z } from "zod";

const { defineUpload } = createUploads<AppContext>();

export const issueAttachmentUpload = defineUpload("issues.attachment", {
  metadata: z.object({ issueKey: z.string() }),
  file: {
    contentTypes: ["application/pdf", "text/plain"],
    maxSizeBytes: 5 * 1024 * 1024,
    checksum: { algorithm: "sha256" },
  },
  authorize({ ctx }) {
    return ctx.actor.type === "user";
  },
  key({ ctx, metadata, uploadId }) {
    const actorId = ctx.actor.type === "user" ? ctx.actor.id : "anonymous";
    return `issues/${actorId}/${metadata.issueKey}/attachments/${uploadId}`;
  },
  async verifyFile({ ctx, file }) {
    const scan = await ctx.ports.fileScanner.scanObject(file.key);

    return scan.clean
      ? true
      : { valid: false, reason: "Upload did not pass scanning." };
  },
  async onComplete({ ctx, files }) {
    await ctx.ports.issueAttachments.upsertByUploadId({
      id: files[0]!.uploadId,
      key: files[0]!.key,
    });
  },
});
Copy

For supported media types, uploads verify the declared content type against the file signature before completion. Set contentTypeVerification: false only for workflows that intentionally accept mismatched supported file types. Direct uploads can require a SHA-256 checksum with checksum: { algorithm: "sha256" }; browser clients need a client-safe manifest so @beignet/core/uploads/client can compute the digest before prepare. Use verifyFile(...) for app-owned scanning, moderation, and quarantine decisions that run after the object exists in storage and before onComplete(...). Server uploads authorize each file before reading its bytes for signature or checksum verification. If key derivation, storage, or verification fails before onComplete(...) begins, the router deletes every object already stored by that request before returning the original error. Cleanup failures are instrumented as upload.server.cleanup.failed. Once app-owned completion begins, Beignet leaves the objects in place because the app may already have persisted durable references and therefore owns transaction or compensation. Direct-upload objects likewise remain app-owned because they existed before the completion request.

Direct-upload completion is stateless. Beignet does not retain issuance or single-use state between prepare and complete, so keys must include the relevant actor, tenant, or resource owner and onComplete(...) must be idempotent by upload ID or object key. Use an app-owned issuance table when a workflow requires single-use completion or revocation.

createUploadRouter(...) bounds JSON request bodies and server-handled multipart bodies. Multipart limits are enforced against both a declared Content-Length and the bytes actually read, so chunked requests cannot bypass limits.multipartMaxBytes before formData() parsing.

Upload route failures use Beignet's flat { code, message, details? } error body. The typed upload client maps that response to UploadClientError with the same code, status, and details.

Webhooks

Use @beignet/core/webhooks for provider-neutral inbound webhook definitions, raw-body verification, typed event payload catalogs, and test verifiers.

import {
  createHmacWebhookVerifier,
  defineWebhook,
} from "@beignet/core/webhooks";
import { z } from "zod";

export const issueWebhook = defineWebhook("issues.provider", {
  provider: "provider",
  events: {
    "issue.created": z.object({
      id: z.string(),
      type: z.literal("issue.created"),
      issueId: z.string(),
    }),
  },
  verifier: createHmacWebhookVerifier({
    secret: process.env.PROVIDER_WEBHOOK_SECRET ?? "",
    signatureHeader: "x-provider-signature",
    signaturePrefix: "sha256=",
    timestamp: {
      header: "x-provider-timestamp",
      toleranceSec: 300,
    },
  }),
});
Copy

Use createMemoryWebhookVerifier(...) in tests and createWebhookRoute(...) from @beignet/next to expose raw-body webhook routes in Next.js apps. Use a provider package such as @beignet/webhooks-github or @beignet/webhooks-stripe when a vendor has signature semantics beyond the generic HMAC verifier. For billing flows backed by ctx.ports.payments, use @beignet/core/payments with createPaymentWebhookRoute(...) from @beignet/next instead of a generic webhook catalog.

Feature webhook definitions stay provider-free: defineWebhook(...) catalogs are contract-reachable code, and contract-reachable code cannot import @beignet/provider-* packages — beignet lint enforces this dependency direction. Attach provider verifiers at the route boundary through the verify option of createWebhookRoute(...); the inline verifier: option on defineWebhook(...) is reserved for the core verifiers (createHmacWebhookVerifier(...), createMemoryWebhookVerifier(...)) and for tests.

Generic webhook catalogs reject verified event types that are not declared in events by default. Set allowUnknownEvents: true on createWebhookRoute(...) or verifyWebhook(...) only for broad provider endpoints that intentionally acknowledge valid events the app does not handle. When a generic HMAC provider signs a timestamp header or payload field, pass timestamp to reject replayed deliveries outside the configured tolerance. Header mode authenticates the exact <timestamp>.<rawBody> bytes; payload mode authenticates the raw body containing the timestamp.

Provider metadata

Reusable provider packages should declare static metadata in package.json under beignet.provider. That manifest metadata is package-owned and side-effect-free, so CLI diagnostics can inspect installed provider packages without importing provider implementation code.

{
  "beignet": {
    "provider": {
      "displayName": "Cache provider",
      "ports": ["cache"],
      "appPorts": [{ "name": "cache", "type": "CachePort" }],
      "env": ["CACHE_URL", "CACHE_REGION"],
      "requiredEnv": ["CACHE_URL"],
      "requiredTables": ["cache_entries"],
      "registration": {
        "required": true,
        "tokens": ["createCacheProvider"]
      },
      "watchers": ["cache"]
    }
  }
}
Copy

env lists all variables the provider may read. requiredEnv is the subset that beignet doctor --strict should require in app config. requiredTables lists database tables the provider always needs when it is installed and used; doctor checks app schema, migrations, and database setup files for those names. When a provider supports mutually exclusive credential paths, use requiredEnvAlternatives instead of requiredEnv. Each nested array is one complete configuration; doctor, provider audit, and preflight accept the provider when any one is complete:

{
  "env": ["API_TOKEN", "OIDC_CLIENT_ID", "OIDC_TOKEN"],
  "requiredEnvAlternatives": [
    ["API_TOKEN"],
    ["OIDC_CLIENT_ID", "OIDC_TOKEN"]
  ]
}
Copy

registration.required: true marks providers that apps must register in server/providers.ts; doctor reports a missing registration as a warning, which fails beignet doctor --strict. Optional-by-design providers such as @beignet/devtools can declare registration.severity: "hint" instead, so an installed-but-unregistered package is reported as an informational hint that never fails doctor, even in strict mode. Use parseProviderPackageMetadata(...) to validate manifest metadata before publishing a provider package.

The package manifest is the sole provider metadata source. Runtime provider objects define lifecycle behavior and a diagnostic name; they do not repeat package facts. App-local providers therefore need no metadata declaration unless they are published as a reusable package, in which case add the manifest to that package.

Tasks

Use @beignet/core/tasks for app-owned operational entrypoints such as backfills, maintenance work, and one-off repair scripts. Tasks are not HTTP routes and are not background jobs; they are explicit functions a CLI or worker can run with parsed input and an application context. Run them with runTask(...) or beignet task run, and collect them with defineTasks(...).

import { createTasks } from "@beignet/core/tasks";
import { z } from "zod";
import type { AppContext } from "@/app-context";

const { defineTask } = createTasks<AppContext>();

export const backfillSearchTask = defineTask("posts.backfill-search", {
  input: z.object({
    dryRun: z.boolean().default(true),
  }),
  async handle({ input, ctx }) {
    ctx.ports.logger.info("Backfill started", {
      dryRun: input.dryRun,
    });
  },
});
Copy

Feature-owned task files should usually call use cases, repositories, or ports rather than hiding business rules inside a script.

Key concepts

Contract

A contract is the single source of truth for an API endpoint. It describes:

• HTTP method and path (with path parameters)
• Path parameters, query parameters, request headers, and request body schemas
• Response schemas (per status code, including error responses)
• Metadata for auth, rate limiting, idempotency, etc.

Contract group

A contract group allows you to share configuration across related endpoints, such as a common namespace, route metadata, headers, and shared response schemas.

Usage

Defining contracts

import { z } from "zod";
import {
  defineContractGroup,
  defineQueryTransport,
  query,
} from "@beignet/core/contracts";

// Create a contract group for related endpoints
const todos = defineContractGroup()
  .namespace("todos")
  .prefix("/api/todos")
  .meta({ auth: "required" })
  .headers(z.object({
    authorization: z.string().startsWith("Bearer "),
  }));

// Define schemas
const TodoSchema = z.object({
  id: z.string(),
  title: z.string(),
  completed: z.boolean(),
});

const CreateTodoRequest = z.object({
  title: z.string().min(1),
  completed: z.boolean().optional(),
});

// Define contracts
export const getTodo = todos
  .get("/:id")
  .pathParams(z.object({ id: z.string() }))
  .responses({ 200: TodoSchema })
  .errors({
    TodoNotFound: {
      code: "TODO_NOT_FOUND",
      status: 404,
      message: "Todo not found",
      details: z.object({ id: z.string() }),
    },
  });

export const createTodo = todos
  .post("/")
  .body(CreateTodoRequest)
  .responses({ 201: TodoSchema });

export const listTodos = todos
  .get("/")
  .query(
    z.object({
      completed: z.boolean().optional(),
      limit: z.number().int().optional(),
    }),
    defineQueryTransport({
      completed: query.boolean(),
      limit: query.integer(),
    }),
  )
  .responses({ 200: z.array(TodoSchema) });
Copy

Clients and OpenAPI generation infer required path argument keys from literal path templates. Use .pathParams(...) when you want runtime validation, coercion, richer OpenAPI schemas, or parameter descriptions.

Query schemas define logical values and validation; query transports define URL encoding. The same explicit transport drives typed-client encoding, server decoding, and OpenAPI form or deepObject metadata. Use the scalar helpers query.string(), query.number(), query.integer(), query.boolean(), query.dateTime(), and query.date(). Arrays repeat one scalar field, and query.deepObject(...) supports one flat object. Empty collections are omitted unless the array or object transport opts into { empty: "preserve" }, a versioned Beignet extension for typed clients.

query.integer() accepts JavaScript safe integers and publishes that range in OpenAPI.

The client serializes schema input values and, when validateInput: true is enabled, validates them without using transformed output as the query wire value. The server decodes the transport once and then runs the Standard Schema, so handlers receive defaults and transformed schema outputs. Keep HTTP wire conversion in the transport rather than a schema transform.

createServer(...) enforces registration-time guarantees: each method + path may only be registered once, contract names must be unique across the route registry because typed clients, OpenAPI operations, and devtools key on them, and an introspectable .pathParams(...) object schema must declare exactly the :param keys from the path template. Mismatches fail server startup with the contract name and path. Opaque Standard Schemas skip that registration-time key comparison; OpenAPI falls back to required string parameters from the literal path template unless a custom schema introspector is supplied. At dispatch time, a request that matches a registered path with an unregistered method receives a framework-owned 405 METHOD_NOT_ALLOWED response with an Allow header listing the registered methods. GET routes also serve HEAD when no explicit HEAD route exists; explicit HEAD routes take precedence, and every HEAD response is bodyless.

Runtime integrity

Workflow artifacts are explicit too. Use createRuntimeIntegrity(...) when an app should fail startup if a listener, schedule, task, or outbox event/job is listed in the app manifest but missing from the runtime registries:

import {
  createRuntimeIntegrity,
  defineRuntimeManifest,
  defineRuntimeRegistries,
} from "@beignet/core/server";
import { postEvents } from "@/features/posts/domain/events";
import { postJobs } from "@/features/posts/jobs";
import { postListeners } from "@/features/posts/listeners";
import { listeners } from "@/server/listeners";
import { outboxRegistry } from "@/server/outbox";

export const runtimeIntegrity = createRuntimeIntegrity({
  manifest: defineRuntimeManifest({
    listeners: [...postListeners],
    outbox: {
      events: [...postEvents],
      jobs: [...postJobs],
    },
  }),
  registries: defineRuntimeRegistries({
    listeners,
    outbox: outboxRegistry,
  }),
});
Copy

Pass integrity: runtimeIntegrity to createServer(...) or createNextServer(...). The check is pure and serverless-safe: it compares imported definitions and registries in memory, without filesystem scanning, provider calls, database access, worker startup, or background loops. Use mode: "warn" to log findings without failing boot.

Contract path templates intentionally support concrete segments and single-segment params such as :id and [id]. Framework or platform catch-all route files can expose a central Beignet handler, but individual contracts should stay on explicit paths; catch-all contract patterns such as /files/[...path] are rejected.

For routes that cannot be contracts at all — third-party callback endpoints with externally defined request shapes, signature-verified webhooks, streaming endpoints that own body consumption — server.rawRoute({ name, method, path, metadata }).handle(fn) builds a handler that still runs the whole pipeline (hooks, context creation, instrumentation, framework error mapping) without contract parsing or validation. The request body stays unconsumed for the handler, metadata feeds metadata-driven hooks such as rate limiting exactly like contract metadata, and the route is not added to the registry — the adapter mounts the returned handler at the route's own path.

Server-sent events

createServerSentEventResponse(...) creates a portable Fetch Response for an SSE endpoint. Use it from a contract handler or raw route after application-owned authentication and authorization:

import { createServerSentEventResponse } from "@beignet/core/server";

return createServerSentEventResponse({
  signal: req.signal,
  maxLifetimeMs: 240_000,
  start({ send }) {
    send({ event: "reconcile", data: { workspaceId } });
    const subscription = ctx.ports.workspaceBroadcast.subscribe(
      workspaceId,
      (change) => {
        send({ event: "changed", data: change });
      },
    );
    return { close: () => subscription.unsubscribe() };
  },
  onError: (error) => ctx.ports.logger.error("SSE stream failed", { error }),
});
Copy

Event data is JSON-encoded. Optional event, id, and retry fields use standard SSE framing; retry sets the browser reconnection delay in milliseconds. comment(...) sends an explicit comment, and close() ends the response. send(...) and comment(...) return true when they enqueue a frame and false after closure, when framing or encoding fails, or when the unread byte limit would be exceeded. Event names and IDs must fit on one line, and IDs cannot contain null characters. A producer, framing, encoding, stream, or buffer-overflow failure reports through onError and closes the connection.

Heartbeat comments default to 25 seconds; heartbeatMs: false disables them. maxLifetimeMs is opt-in. Both options accept false or an integer from 1 through 2_147_483_647; retry accepts an integer from 0 through the same maximum. start(...) receives a stream-scoped signal that aborts whenever the response closes. Pass it to subscription APIs that perform asynchronous setup. start(...) may return a cleanup callback, a closeable subscription, a promise of either, or nothing. If it returns cleanup, request abort, response cancellation, explicit close, and maximum lifetime invoke that cleanup exactly once. onError also observes cleanup failures without creating an unhandled rejection. When stream closure aborts asynchronous setup, an expected AbortError rejection is treated as cancellation rather than a producer failure; other setup rejections still reach onError.

Unread encoded frames are bounded to 1_048_576 bytes by default. Set maxBufferedBytes to an integer from 1 through 2_147_483_647 when the endpoint has a verified frame-size requirement. If one frame or the accumulated unread queue would exceed the limit, the helper reports a RangeError and closes the connection; the limit remains active even when maxLifetimeMs is disabled. Response-body cancellation waits for cleanup that has already been registered, but it does not wait indefinitely for pending asynchronous setup. The stream signal lets setup stop cooperatively, and any cleanup returned after closure still runs exactly once.

The response always sets Content-Type: text/event-stream, Cache-Control: no-store, no-transform, and X-Accel-Buffering: no, removes Content-Length and hop-by-hop streaming headers, and preserves other custom headers supplied through headers. The helper does not own authorization, replay, durability, distributed connection limits, or client reconciliation. Keep authoritative state elsewhere and reconcile on initial connection and reconnect when messages are best-effort hints.

Use a contract handler when the stream belongs in the route registry and OpenAPI document. Use a raw route when the endpoint is transport-only and the app owns its request and response shape. Document a contract stream with a .responses({ 200: null }) success schema and an OpenAPI text/event-stream media override.

Use .headers(...) for request headers that are part of the endpoint contract. Declare header keys in lowercase; server and client runtime matching is case-insensitive.

Request bodies are supported for POST, PUT, and PATCH contracts only. JSON bodies require Content-Type: application/json; otherwise the runtime passes the body to validation as text. When a missing content type accompanies a valid JSON object or array that fails validation, the framework-owned error includes a targeted details.hint without changing the response code.

If you do not pass name, Beignet generates one from the HTTP method and full path:

defineContract({ method: "GET", path: "/users/:id" }).name;
// "getUsersById"

defineContract({ method: "POST", path: "/api/todos" }).name;
// "createTodos"
Copy

Auto-generated names ignore a leading /api segment, include path parameters as By..., and are used as defaults in places like React Query keys and OpenAPI operationIds. Pass name explicitly when you need a custom stable identifier.

Path prefixes

Use .prefix(...) on a contract group to compose shared URL path segments without repeating them on every route:

const api = defineContractGroup().prefix("/api/v1");

const todos = api
  .namespace("todos")
  .prefix("/todos");

export const listTodos = todos.get("/");
// GET /api/v1/todos

export const getTodo = todos.get("/:id");
// GET /api/v1/todos/:id
Copy

Prefixes compose immutably and normalize boundary slashes. namespace() controls resource identity for contract names, OpenAPI tags, and client cache grouping; prefix() only controls URL paths.

For public API versions, keep request and response shapes explicit with path prefixes. Header negotiation remains app-owned. Mark an old contract or whole version group with .deprecated(...) while it is still served:

const v1 = defineContractGroup()
  .namespace("legacyTodos")
  .prefix("/api/v1/todos")
  .deprecated({
    since: "2026-07-11T00:00:00Z",
    sunset: "2027-01-01T00:00:00Z",
    reason: "Use the current todos collection.",
    replacement: "/api/todos",
    documentation: "https://docs.example.com/migrations/todos-v1",
  });
Copy

The metadata sets OpenAPI deprecated: true, adds x-beignet-deprecation, and sends standard Deprecation, Sunset, and deprecation-documentation Link response headers. UTC ISO 8601 timestamps are validated when contracts are built or registered.

Test app fixtures

Use @beignet/core/testing to build app contexts and common memory ports without hand-rolling audit, event, job, mail, notification, outbox, storage, idempotency, logger, clock, and UOW setup in every test:

import { createUseCaseTester } from "@beignet/core/application";
import { createTestContextFactory, createTestPorts } from "@beignet/core/testing";
import {
  createTestTenant,
  createTestUserActor,
} from "@beignet/core/testing";

const fixture = createTestPorts<AppContext["ports"]>({
  base: initialPorts,
  overrides: {
    gate: initialPorts.gate,
    posts: { findById: async (id) => postRecord(id) },
  },
});
const createContext = createTestContextFactory<AppContext, AppContext["ports"]>({
  ports: fixture.ports,
  actor: createTestUserActor("user_test"),
  auth: { user: { id: "user_test" } },
  tenant: createTestTenant("tenant_example"),
});
const tester = createUseCaseTester<AppContext>(createContext);
Copy

The returned fixture exposes captured side effects such as events, dispatchedJobs, audit.entries, mailer.deliveries, notifications.deliveries, outbox.messages, and memory storage for assertions. Its default bestEffortWork port queues callbacks in pendingBestEffortWork; call flushBestEffortWork() to run the current batch.

overrides is typed as TestPortsOverrides<Ports>, which accepts typed partial ports without casts. The partial rule is one level deep: an object-valued port may supply only the members the test needs, and any missing member becomes a named throwing function (Test port "posts.update" was called but not provided.). Function-valued ports, class instances, and other exotic objects are supplied whole — nested config objects are not partial.

The default audit port is wrapped with createAmbientAuditLog(...), so entries recorded inside an active request context inherit actor, tenant, request ID, and trace ID exactly like production. fixture.audit still exposes the underlying memory port for entries assertions.

One-call test contexts

Use createTestContext(...) when a job, listener, schedule, notification, or task test needs a full app context instead of a repeated factory:

import { createTestContext } from "@beignet/core/testing";

const makeContext = createTestContext<AppContext>();

it("audits handled jobs", async () => {
  using fixture = makeContext({
    ports: { issues: { findById: async (id) => issueRecord(id) } },
  });

  await IndexIssueJob.handle({ job: IndexIssueJob, payload, ctx: fixture.ctx });

  expect(fixture.audit.entries).toMatchObject([
    { action: "jobs.issues.index", requestId: "test-request" },
  ]);
});
Copy

The fixture assembles ctx with actor (default createTestSystemActor("test-system")), tenant, request ID, trace ID, auth, ports, and a live bound ctx.gate. It also enters the ambient request context so ambient enrichment (such as the default audit port) behaves like the server; using (or an explicit dispose()) clears it:

let fixture: ReturnType<ReturnType<typeof createTestContext<AppContext>>>;

afterEach(() => {
  fixture.dispose();
});
Copy

Pass ambient: false to skip ambient entry. Reading an app port that is neither a kit default nor supplied throws a named error (App port "tweets" is not bound in this test context.), so partial port wiring fails on use instead of failing silently.

Transactional domain events

When a use case records domain events through a buffered recorder on the transaction ports, pass transaction.outbox: true to enqueue tx.events to ports.outbox after commit and clear them after rollback:

import { createDomainEventRecorder } from "@beignet/core/ports";

const fixture = createTestPorts<AppContext["ports"], AppTransactionPorts>({
  transaction: {
    ports: (ports) => ({ ...ports, events: createDomainEventRecorder() }),
    outbox: true,
  },
});
Copy

transaction.outbox requires transaction.ports to include an events recorder created by createDomainEventRecorder(); the kit throws a named error otherwise. createOutboxEventRecorder(...) writes immediately through a transaction-scoped outbox port and is intentionally not a buffered recorder.

Sharing the server context blueprint

Declare the context blueprint once with defineServerContext(...) from @beignet/core/server and keep it in a canonical server/context.ts file. The same value round-trips through createServer(...) adapters and createTestApp(...) from @beignet/web/testing with full inference:

// server/context.ts
import { defineServerContext } from "@beignet/core/server";

export const appContext = defineServerContext<AppContext, AppPorts>()({
  gate: (ports) => ports.gate,
  request: async ({ req, ports, requestId, trace }) => ({
    actor: await resolveActor(req),
    auth: null,
    requestId,
    ...trace,
    ports,
  }),
  service: ({ ports, requestId, trace }) => ({
    actor: createServiceActor("app-service"),
    auth: null,
    requestId,
    ...trace,
    ports,
  }),
});
Copy

// server/index.ts
const server = await createNextServer({ ports, routes, context: appContext });

// features/<feature>/tests/routes.test.ts
import { createTestApp } from "@beignet/web/testing";

const app = await createTestApp({ ports, routes, context: appContext });
Copy

The service factory powers two server entrypoints:

• server.createServiceContext(...) returns the built context and enters the ambient correlation frame for the rest of the caller's async execution. Use it from long-lived runtimes only: servers, workers, and test runners.
• server.runServiceContext(...) builds the same context and runs a callback inside a scoped ambient frame, returning the callback's result. Use it from plain scripts such as seeds and one-off maintenance work — the createServiceContext(...) entrypoint relies on AsyncLocalStorage.enterWith, and resuming that frame across top-level await crashes Bun 1.3.x in plain scripts.

// scripts/seed.ts (plain script, top-level await)
const server = await createServer({ ports, context: appContext });

await server.runServiceContext({ tenantId: "tenant_demo" }, async (ctx) => {
  await seedDemoData(ctx);
});
Copy

Both entrypoints require context.service in the blueprint, generate fresh requestId and trace values per call, and expose the service actor and tenant on the ambient request context so audit and instrumentation wrappers observe them at record time.

Tenant scopes

Use @beignet/core/tenancy when a repository method should be scoped to the current tenant without accepting arbitrary tenant IDs from callers:

import {
  requireTenantScope,
  tenantScopeId,
  type TenantScope,
} from "@beignet/core/tenancy";

export interface TodoRepository {
  create(input: CreateTodoInput, scope: TenantScope): Promise<Todo>;
}

const scope = requireTenantScope(ctx);
await ctx.ports.todos.create(input, scope);

const tenantId = tenantScopeId(scope); // adapter boundary
Copy

Apps still own tenant resolution and tenant data modeling. TenantScope only brands the already-resolved ctx.tenant value for app-facing repository boundaries. beignet doctor --strict checks generated tenant-scoped Drizzle repositories, explicit raw tenantId repository boundaries, and scoped tenantId/workspaceId predicates as a conservative drift detector.

Testing providers

Use installProviderForTest(...) to run provider setup against test ports without hand-rolling setup, port merge, and lifecycle plumbing:

import type { CachePort } from "@beignet/core/ports";
import { installProviderForTest } from "@beignet/core/testing";
import { createRedisCacheProvider } from "@beignet/provider-cache-redis";

const { ports, result, start, stop } = await installProviderForTest(
  createRedisCacheProvider(),
  {
    config: { URL: "redis://localhost:6379" },
  },
);

const cache = ports.cache as CachePort;
await cache.set("posts:list", "[]");

await stop();
Copy

ports contains the base ports merged with provider-contributed ports, and result exposes the raw setup result for lifecycle-hook assertions. config is passed to setup as-is, matching server startup where config is validated before setup runs. Pass createServiceContext when the provider builds service contexts from runtime entrypoints.

Test factories and seeds

Use the same subpath to keep feature tests and demo seed data port-based. Factories build app-owned records, and optional persist functions write through the context you pass in:

import {
  createDatabaseTestHarness,
  createFactory,
  defineSeed,
  resetFactories,
  runSeeds,
} from "@beignet/core/testing";

const postFactory = createFactory("post", {
  defaults: ({ sequence }) => ({
    title: `Post ${sequence}`,
    content: "Created in a test.",
  }),
  persist: (ctx: AppContext, post) => ctx.ports.posts.create(post),
});

const demoPostsSeed = defineSeed("demo-posts", {
  run: async (ctx: AppContext) => {
    await postFactory.createList(ctx, 3);
  },
});

export async function seedDemoPosts(ctx: AppContext) {
  await runSeeds({ ctx, seeds: [demoPostsSeed] });
}

export function resetPostFactories() {
  resetFactories(postFactory);
}
Copy

For repository and persistence tests, compose the app-owned database fixture with the same factories and seeds:

const databaseHarness = createDatabaseTestHarness({
  create: createTestDatabase,
  ctx: (database) => ({ ports: database.ports }),
  reset: (database) => database.reset(),
  close: (database) => database.close(),
  factories: [postFactory],
  seeds: [demoPostsSeed],
});

afterEach(async () => {
  await databaseHarness.cleanup();
});

const { ctx } = await databaseHarness.setup({ seed: true });
const post = await postFactory.create(ctx, { title: "Database conventions" });
Copy

Keep factories and seeds app-owned. They should not import database clients, ORM table objects, or provider SDKs directly.

Port testing helpers

Use @beignet/core/testing when tests need stable actor, tenant, authorization, or audit assertions:

import {
  assertAuditEntry,
  createPolicyTester,
  createTestActivityContext,
  createTestTenant,
  createTestUserActor,
} from "@beignet/core/testing";

const activity = createTestActivityContext({
  actor: createTestUserActor("user_1", { role: "admin" }),
  tenant: createTestTenant("tenant_1"),
});

const tester = createPolicyTester({ policies: [postPolicy] });
await tester.assertMatrix([
  {
    name: "admin can publish",
    ctx: activity,
    ability: "posts.publish",
    subject: post,
    expected: "allow",
  },
]);

const permissions = await tester.gate.canMany(activity, {
  publish: ["posts.publish", post],
});
expect(permissions.publish).toBe(true);

assertAuditEntry(audit.entries, {
  action: "posts.publish",
  actorId: "user_1",
  tenantId: "tenant_1",
  resourceType: "post",
  resourceId: post.id,
});
Copy

createTestImpersonatedUserActor(...) is available for tests where an admin or support actor is acting as another user and audit metadata should record the impersonator ID.

The same subpath includes assertion helpers for common provider-backed test adapters:

import {
  assertDispatchedJob,
  assertIdempotencyCompleted,
  assertMailDelivery,
  assertNotificationDelivery,
  assertOutboxDelivered,
  assertOutboxDrainResult,
  assertOutboxPending,
  assertProviderInstrumentationEvent,
  assertRecordedEvent,
  assertStorageObject,
  createRecordingEventBus,
  createRecordingJobDispatcher,
  createRecordingProviderInstrumentation,
} from "@beignet/core/testing";
import { drainOutbox } from "@beignet/core/outbox";
import { createProviderInstrumentation } from "@beignet/core/providers";

const { bus, events } = createRecordingEventBus();
const { jobs, dispatchedJobs } = createRecordingJobDispatcher();

await bus.publish(PostPublished, { postId: post.id });
await jobs.dispatch(LogPostPublishedJob, { postId: post.id });

assertRecordedEvent(events, {
  name: "posts.published",
  payload: { postId: post.id },
});

assertDispatchedJob(dispatchedJobs, {
  name: "posts.log-published",
  payload: { postId: post.id },
});

assertNotificationDelivery(notifications.deliveries, {
  notificationName: "posts.published",
  channels: ["email"],
});

assertMailDelivery(mailer.deliveries, {
  subject: "Post published",
});

await assertStorageObject(storage, {
  key: "posts/post_1/attachment.txt",
  text: "hello",
});

assertIdempotencyCompleted(fixture.idempotency, {
  namespace: "posts.create",
  key: "idem_1",
  result: { id: post.id },
});

assertOutboxPending(outbox, {
  kind: "event",
  name: "posts.published",
  payload: { postId: post.id },
});

const result = await drainOutbox({ outbox, registry, eventBus, jobs });

assertOutboxDrainResult(result, {
  claimed: 1,
  delivered: 1,
  settlementFailed: 0,
  leaseLost: 0,
});

assertOutboxDelivered(outbox.messages, {
  kind: "event",
  name: "posts.published",
});

const { instrumentation, events: providerEvents } =
  createRecordingProviderInstrumentation();
const providerInstrumentation = createProviderInstrumentation(instrumentation, {
  providerName: "redis",
  watcher: "providers",
});

providerInstrumentation.custom({
  name: "cache.get",
  details: { key: "posts:list", hit: true },
});

assertProviderInstrumentationEvent(providerEvents, {
  type: "custom",
  name: "cache.get",
  providerName: "redis",
  details: { hit: true },
});
Copy

createRecordingEventBus() applies the same canonical JSON and transport-stability checks as Beignet's runtime event buses before appending an event to its captured log. Await bus.publish(...) before reading that log.

createProviderInstrumentation(...) adds details.providerName to custom and typed provider events, so tests and devtools can group provider work consistently. Watcher checks, synchronous sink errors, and rejected asynchronous sink writes are isolated so observability cannot replace the provider operation's result or error.

Pagination

Use @beignet/core/pagination to keep list use cases and repository ports consistent without coupling them to an ORM:

import { normalizeOffsetPage } from "@beignet/core/pagination";

const page = normalizeOffsetPage(input, {
  defaultLimit: 20,
  maxLimit: 100,
});

return ctx.ports.posts.findMany({
  page,
  filters: { status: input.status },
  sort: { field: "createdAt", direction: "desc" },
});
Copy

Beignet's convention is items for list contents and page for pagination metadata. Keep filters and sort options app-owned plain objects.

Request-scoped memoization

Use createMemo(...) from @beignet/core/memo to run a lookup once per request no matter how many policies, use cases, and handlers ask for it. The server enters a memo scope around every HTTP request and every server.runServiceContext(...) execution; the scope's cache dies with it, so there is no TTL, no invalidation policy, and no cross-request staleness.

import { createMemo } from "@beignet/core/memo";

const repository = createDrizzleIssuesRepository(db);

export const issues = {
  ...repository,
  findById: createMemo(repository.findById, { name: "issues.findById" }),
  update: async (id: string, patch: IssuePatch) => {
    const updated = await repository.update(id, patch);
    // A write makes the memoized read stale within this same request.
    issues.findById.invalidate(id);
    return updated;
  },
};
Copy

• Wrap reads in infra, next to the adapter — use cases and policies never know caching exists. Memoize reads, not mutations, and pair mutations with invalidate(...) as above.
• Concurrent calls share one in-flight promise; rejected promises are evicted so the next call retries instead of memoizing the failure.
• Default cache keys use a structural, type-tagged encoding of the arguments ("1" and 1 never collide, object key order is irrelevant). Arguments that cannot be encoded deterministically throw a MemoKeyError naming the memo; pass key: (...args) => string for those.
• Outside a scope — plain scripts, createServiceContext(...) callers — memoized functions call straight through uncached. runMemoScope(fn) creates a scope explicitly in scripts and unit tests.
• With devtools installed, each call records a memo.hit or memo.miss event (with fill duration) under the request, so duplicate lookups are visible in the waterfall.

For caching that must survive across requests, use the explicit tier — ports.cache.remember with keys that change when the data changes — and see the request lifecycle docs for context latency budgets.

Trusted proxy request metadata

Beignet trusts no forwarding headers by default. Configure one server-level policy when the app always runs behind a platform edge or reverse proxy that strips or normalizes those headers:

const server = await createServer({
  ports,
  trustedProxy: {
    clientIp: "x-forwarded-for-last",
  },
  context: ({ ports, requestId, requestInfo, trace }) => ({
    ports,
    requestId,
    requestInfo,
    ...trace,
  }),
  hooks: [
    createCsrfHooks(),
    createRateLimitHooks(),
  ],
});
Copy

The request context factory and every server-hook phase receive the same requestInfo, including the external URL, origin, protocol, host, and optional client IP. Store it on AppContext when routes or Server Components need it. createRateLimitHooks(...) and createCsrfHooks(...) consume the server policy automatically. Their hook-local trustedProxy options remain available when one hook deliberately needs a different policy.

resolveTrustedRequest(...) remains available for standalone adapters. Do not copy clientIp into logs or audit metadata unless the application explicitly needs that personal data and applies its retention policy.

Rate limiting

Use createRateLimitHooks(...) from @beignet/core/server to enforce contract.metadata.rateLimit at the HTTP boundary:

import { createRateLimitHooks } from "@beignet/core/server";

const server = await createServer<AppContext, AppPorts>({
  ports: initialPorts,
  hooks: [createRateLimitHooks<AppContext>()],
  // ...
});
Copy

• global and ip scopes run in onRequest before parsing and context creation; user scope runs in beforeHandle after route hooks have resolved identity and ctx.actor exists.
• Default buckets use contract:<contract-name>:global, contract:<contract-name>:ip:<client-ip>, or contract:<contract-name>:user:<user-id>, so traffic to one contract does not consume another contract's limit. A user-scoped limit fails with AuthUnauthorizedError when route hooks do not resolve a user actor.
• ip scopes require an explicit server-level trustedProxy.clientIp, hook-local trustedProxy.clientIp, ipSource, or custom earlyKey. The hook's validate phase fails createServer(...) startup when a registered contract declares an ip-scoped rate limit without one, and enforcement throws the same configuration error for contracts added later through server.route(...). Prefer createServer({ trustedProxy: { clientIp: "x-forwarded-for-last" } }) behind a trusted proxy that appends the socket address, "x-forwarded-for-first" when a trusted edge normalizes the header, or createServer({ trustedProxy: { clientIp: "cf-connecting-ip" } }) for platform headers.
• Pass ipSource: "none" to explicitly opt out of client-IP resolution: Beignet then trusts no forwarding headers and all ip-scoped traffic for each contract shares that contract's contract:<contract-name>:ip:unknown bucket.
• Denials throw the framework 429 Too Many Requests catalog error with scope, retryAfterSeconds, and resetAt details, and the response carries a standard Retry-After header when the limiter reports a reset time. The bucket key is never included in the client-visible response.
• Each denial emits a rateLimit.denied instrumentation event carrying the key, scope, limit, and window when the app ports include an instrumentation or devtools sink, so operators keep bucket visibility.
• A custom key or earlyKey owns the complete bucket key and bypasses the default contract namespace. Include route identity when custom buckets should remain independent per contract.

Idempotency

Use createIdempotencyHooks(...) from @beignet/core/server to enforce contract.metadata.idempotency at the HTTP boundary, mirroring createRateLimitHooks(...):

import { createIdempotencyHooks } from "@beignet/core/server";

const server = await createServer<AppContext, AppPorts>({
  ports: initialPorts,
  hooks: [createIdempotencyHooks<AppContext>()],
  // ...
});
Copy

The hook reads the key from the metadata header (default idempotency-key), reserves it through ctx.ports.idempotency after request parsing and route hook identity resolution, stores final route-owned 2xx responses after the response-validation phase, replays completed matching responses with an idempotency-replayed: true header, and maps in-progress and conflicting keys to framework-owned 409 responses using the httpErrors.IdempotencyInProgress and httpErrors.IdempotencyConflict catalog entries.

Unfinished reservations expire after 300 seconds by default; override reservationTtlSec when the protected operation has a different upper bound. ttlSec controls the completed replay window. Omitted meta.scope binds the key to the actor, includes the current tenant when one is present, and fails closed when ctx.actor.id is missing. Use "global" explicitly only for a public operation whose callers should share one key namespace. Explicit actor- and tenant-scoped modes fail closed when their required identity is missing, and stored HTTP responses are validated against the current contract before replay. Disabling server response validation also disables response persistence for HTTP idempotency.

Typed clients read the same metadata: createClient(...) endpoints attach a generated UUID to the metadata header on every call (injected before request header validation, so header schemas pass), and the header becomes optional in call types. Pass idempotencyKey as a call option for retry-with-same-key flows; an explicit headers value always wins over generation. Each direct call(...) invocation otherwise receives a new key, so generate one outside an application retry loop and pass it to every attempt of the same logical command.

Use runIdempotently(...) from @beignet/core/idempotency when a non-HTTP command, webhook, or job may be retried and must not perform duplicate work:

import {
  createIdempotencyFingerprint,
  runIdempotently,
} from "@beignet/core/idempotency";

const result = await runIdempotently(ctx.ports.idempotency, {
  namespace: "todos.import",
  key: input.importId,
  scope: {
    tenantId: ctx.tenant?.id,
    actorId: ctx.actor?.id,
  },
  fingerprint: await createIdempotencyFingerprint(input, {
    omit: ["importId"],
  }),
  ttlSec: 60 * 60 * 24,
  run: () => ctx.ports.uow.transaction((tx) => tx.todos.importBatch(input)),
});
Copy

The memory store is useful for tests and local examples:

import { createMemoryIdempotencyStore } from "@beignet/core/idempotency";

const idempotency = createMemoryIdempotencyStore();
Copy

createIdempotencyFingerprint(...) sorts object keys and tags non-JSON values before hashing while retaining the stable representation of ordinary JSON payloads. BigInts and Dates therefore remain distinct from same-looking strings; invalid dates, non-finite numbers, circular values, and the reserved tag key fail instead of producing ambiguous fingerprints. Non-plain objects other than Date fail as unsupported; project them to plain command data before hashing.

Reservation tokens use Web Crypto randomUUID() or getRandomValues() when available and securely fall back to node:crypto on supported Node runtimes. The memory adapter accepts createReservationToken when a deterministic test needs to supply its own token factory, and fails clearly if neither secure runtime source is available.

Production apps should back IdempotencyPort with atomic SQL or Redis storage. The Drizzle/libSQL path can use createDrizzleSqliteIdempotencyPort(...) from @beignet/provider-db-drizzle/sqlite. For high-integrity workflows, prefer exposing a transaction-scoped tx.idempotency port from the app Unit of Work so reservation, business writes, audit records, domain-event records, and idempotency completion commit together.

runIdempotently(...) releases a reservation only when the protected work throws. If the work succeeds but complete(...) fails, the reservation stays in progress and the completion error is rethrown so an immediate retry cannot repeat the successful work. If both the protected work and reservation release fail, runIdempotently(...) throws an AggregateError whose cause is the original operation error and whose errors retain both failures. HTTP idempotency keeps the already-prepared application error response in this case and reports the settlement failure through ctx.ports.errorReporter when that optional port is available. Completion and failure carry the opaque token returned by reserve(...), so a stale executor cannot mutate a successor reservation after its own TTL expires. Implementations must reject complete(...) and fail(...) when that token, fingerprint, or reservation state no longer matches; silently dropping a stale mutation would let callers mistake a non-replayable result for a completed operation. The memory adapter throws IdempotencyMutationError; each Drizzle dialect exposes its corresponding Drizzle*IdempotencyMutationError.

Outbox

Use @beignet/core/outbox when events or jobs must be recorded in the same database transaction as the business write, then delivered later with retries:

import {
  createOutboxEventRecorder,
  defineOutboxRegistry,
  drainOutbox,
  type OutboxAdminPort,
} from "@beignet/core/outbox";
import {
  createDrizzleSqliteOutboxAdminPort,
  createDrizzleSqliteOutboxPort,
  createDrizzleSqliteUnitOfWork,
} from "@beignet/provider-db-drizzle/sqlite";

const outboxAdmin: OutboxAdminPort =
  createDrizzleSqliteOutboxAdminPort(db);

const uow = createDrizzleSqliteUnitOfWork({
  db,
  createTransactionPorts: (tx) => {
    const outbox = createDrizzleSqliteOutboxPort(tx);

    return {
      posts: createPostRepository(tx),
      events: createOutboxEventRecorder(outbox, {
        tracing: ports.tracing,
      }),
      outbox,
    };
  },
});

const registry = defineOutboxRegistry({
  events: [PostPublished],
  jobs: [SendPostPublishedEmailJob],
});

await drainOutbox({
  outbox: ctx.ports.outbox,
  registry,
  eventBus: ctx.ports.eventBus,
  jobs: ctx.ports.jobs,
  instrumentation: ctx.ports,
});
Copy

Registry entries describe what the drain may deliver; they do not install the delivery transports. A registry with events requires eventBus, and a registry with jobs requires jobs. drainOutbox(...) validates those capabilities before claiming a batch, so incomplete worker wiring fails without consuming delivery attempts.

The storage port uses token-guarded leases. claimBatch(...) returns both newly claimed messages and eligible rows it atomically dead-lettered because a previous crashed claim exhausted maxAttempts. renewClaim(...) extends only an active, unexpired claim. markDelivered(...) and markFailed(...) also reject expired or stale claim tokens.

drainOutbox(...) defaults to a batch size of 100, serial delivery, a 30-second lease, a 10-second serialized heartbeat, and a 5-minute maximum active duration per message. Set concurrency above one only for handlers that can run without ordering guarantees. Configure leaseMs, heartbeatMs, and maxActiveMs together when delivery latency requires different limits, and synchronize the clocks on every drain host because adapters compare the timestamps supplied by workers. Reaching maxActiveMs stops further renewals; the last confirmed lease can remain active until its own expiration.

The result reports abandonedDeadLettered, settlementFailed, and leaseLost in addition to the normal claim and delivery counters. A successful external delivery whose acknowledgement cannot be stored increments settlementFailed; Beignet does not call markFailed(...) after that success. Treat either uncertainty counter as an operational failure because the message may be delivered again after lease expiry. onLeaseError distinguishes recovered, degraded, and lost lease states; only lost increments leaseLost. One message can increment both uncertainty counters when its settlement reaches the lease deadline.

The outbox is at-least-once delivery. Use idempotent listeners or jobs when a duplicate delivery would be harmful. Drizzle-backed outbox tables persist the optional versioned trace carrier in trace_context_json; add that nullable column to existing tables before upgrading the adapter.

Beignet's use-case event helpers, publishEvent(...), and enqueueEvent(...) validate payloads and forward canonical Standard Schema output. They reject non-JSON outputs and transforms that change when canonical JSON is validated again, before publishing or writing an outbox row. In-process delivery preserves that validation state, while durable or distributed transports validate decoded JSON again. For an outbox, model timestamps as JSON strings or numbers rather than Date objects. Job transports continue to preserve the original JSON-safe payload until the worker's handler-facing parse.

An ordinary Unit of Work event flush has a different boundary: it runs after commit, and a publishing failure rejects even though the database writes are already durable. Do not treat that rejection as proof of rollback or blindly retry non-idempotent work; use the outbox when delivery must survive that window.

createObservedUnitOfWork(...) decorates any Unit of Work with an isolated observer that runs only after the wrapped transaction resolves. Use it to request best-effort follow-up scheduling without allowing observer failures to reject a committed operation:

import { createObservedUnitOfWork } from "@beignet/core/ports";

const observedUow = createObservedUnitOfWork({
  unitOfWork: uow,
  afterCommit: scheduleOutboxDrain,
  onObserverError: (error) => logger.error("Drain scheduling failed", { error }),
});
Copy

The observer itself is not durable. The outbox row remains the durable intent, and a recovery drain must handle missed scheduling callbacks.

When an inline dispatcher exposes Beignet's single-attempt delivery hook, an onError observer is still notified but cannot swallow the failure. The outbox retains retry and dead-letter ownership instead of marking the message delivered.

Use OutboxAdminPort only from operational contexts. It lets beignet outbox list, show, requeue, purge dead-lettered rows, and prune delivered rows without exposing those destructive operations to transaction-scoped use cases.

Schedules

Use @beignet/core/schedules to define typed schedules and run them inline from cron routes, workers, scripts, and tests. Pass a devtools-compatible sink as instrumentation and the inline runner records schedule devtools events (started, completed, failed) for each run:

import { createInlineScheduleRunner } from "@beignet/core/schedules";

const runner = createInlineScheduleRunner<AppContext>({
  ctx,
  instrumentation: ctx.ports,
  instrumentationContext: {
    requestId: ctx.requestId,
    traceId: ctx.traceId,
  },
});

await runner.run(SendDailyDigestSchedule, { source: "vercel-cron" });
Copy

instrumentationContext attaches request correlation fields to recorded events. The shared provider instrumentation helper applies watcher checks, redaction, and sink-failure isolation. Default redaction covers secret-shaped keys plus high-confidence credentials embedded in text, including error messages and stacks. Lifecycle hook failures still reach onHookError when provided. Handler failures reject runner.run(...) after onError runs so trigger hosts can retry.

Contract metadata and route hooks

Use metadata to describe cross-cutting concerns for OpenAPI, clients, docs, and app conventions:

const sendMessage = messages
  .post("/api/messages")
  .body(SendMessageRequest)
  .responses({ 201: SendMessageResponse })
  .meta({
    auth: "required",
    idempotency: {
      required: true,
      header: "idempotency-key",
      scope: "actor-tenant",
      ttlSec: 300,
    },
    rateLimit: {
      max: 60,
      windowSec: 60,
      scope: "user",
    },
  });
Copy

The built-in server hooks enforce rateLimit and idempotency metadata: install createRateLimitHooks(...) and createIdempotencyHooks(...) where the server is composed. Use route hooks for runtime enforcement of route-specific policy where the route is wired:

Bind route declarations to the app context once in lib/routes.ts with createRoutes<AppContext>(), then import the resulting builders in feature route files.

import { createAuthHooks } from "@beignet/core/server";
import { defineRouteGroup } from "@/lib/routes";
import type { AppContext } from "@/app-context";

const auth = createAuthHooks<AppContext>()({
  resolve: ({ ctx }) => {
    return ctx.auth ? { user: ctx.auth.user } : null;
  },
});

export const messageRoutes = defineRouteGroup({
  name: "messages",
  routes: [
    {
      contract: sendMessage,
      hooks: [auth.required()],
      useCase: sendMessageUseCase,
    },
  ],
});
Copy

Ordinary app routes bind { contract, useCase }. The response status is inferred when the contract declares exactly one 2xx response (otherwise status is required and typed to the declared keys). A sole path, query, or body schema passes through unchanged when no additional path, query, or object body values are present. Multiple sources merge via defaultBinderInput — query lowest, then body, then path. Headers are never merged, and a scalar or array body combined with another source needs an explicit input: (parts) => ... mapper. When the use case .input(...) schema is the contract's sole request schema by reference, the server skips the use case's input re-parse — one schema, one parse.

Use { contract, handle } as the escape hatch for response headers, streaming, and multi-status responses. defineRoute remains available for full handlers that read hook-added ctx fields.

Framework-neutral response header values may be strings or string arrays. Use an array for repeated fields such as Set-Cookie; Web-compatible adapters append every item separately, and hooks receive the same string-or-array header record:

return {
  status: 200,
  headers: {
    "set-cookie": [
      "session=abc; Path=/; HttpOnly; Secure; SameSite=Lax",
      "theme=dark; Path=/; Secure; SameSite=Lax",
    ],
  },
  body: { ok: true },
};
Copy

When credentials live in request headers, declare a headers schema on the auth hooks. The hook validates the raw lowercase request header record before resolve runs, so resolve receives typed header values; on required() routes a schema failure returns a framework-owned 401:

const writerAuth = createAuthHooks<AppContext>()({
  name: "writer",
  headers: writerHeadersSchema,
  resolve: ({ headers }) => ({
    actor: createUserActor(headers["x-user-id"]),
  }),
});
Copy

Use createSecurityHeadersHooks(...) for the default browser response-header baseline. The hook adds common headers such as X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy, Cross-Origin-Opener-Policy, and Cross-Origin-Resource-Policy; it does not guess your CSP or HSTS policy:

import { createSecurityHeadersHooks } from "@beignet/core/server";

const securityHeaders = createSecurityHeadersHooks({
  contentSecurityPolicy: "default-src 'self'; frame-ancestors 'none'",
  strictTransportSecurity: {
    maxAgeSec: 31_536_000,
    includeSubDomains: true,
  },
});
Copy

Existing response headers win, so routes that stream files, render HTML, or need a different CSP can set their own policy.

Use createCorsHooks(...) for app-wide CORS headers. Wildcard origins are accepted only for non-credentialed requests:

import { createCorsHooks } from "@beignet/core/server";

const publicCors = createCorsHooks({ origins: "*" });
const browserAppCors = createCorsHooks({
  origins: ["https://app.example.com"],
  credentials: true,
  exposedHeaders: ["x-request-id"],
});
Copy

createCorsHooks({ origins: "*", credentials: true }) throws during setup so apps do not accidentally reflect arbitrary request origins for cookies or authorization headers. The hook always exposes x-beignet-error-owner so the typed browser client can distinguish framework failures from route-owned errors; exposedHeaders adds app-owned response headers that browser code also needs to read.

The hook short-circuits only real browser preflights: OPTIONS requests that include both Origin and Access-Control-Request-Method. An explicit OPTIONS contract without those headers continues through normal route dispatch.

Use createCsrfHooks(...) when browser mutations depend on cookies. By default the hook protects unsafe methods by rejecting cross-origin Origin or Referer headers while still allowing requests that do not carry browser origin headers. Set allowMissingOrigin: false and enable token checks for stricter browser-only APIs:

import { createCsrfHooks } from "@beignet/core/server";

const csrf = createCsrfHooks({
  allowMissingOrigin: false,
  trustedOrigins: ["https://app.example.com"],
  token: {
    cookieName: "csrf",
    headerName: "x-csrf-token",
  },
  skip: ({ contract }) => contract.name.startsWith("webhooks."),
});
Copy

Set trustedProxy: {} on createServer(...) when Beignet should compare Origin or Referer against the external x-forwarded-host and x-forwarded-proto values written by your trusted edge. The CSRF hook uses that central policy unless its own trustedProxy option deliberately overrides it.

Typed client errors

@beignet/core/client classifies failures by where they occur. ContractError.source is "client" for local request preparation, "network" for a rejected fetch, "http" for a non-2xx response, and "contract" for malformed or contract-invalid responses. Unexpected failures use CLIENT_ERROR, NETWORK_ERROR, or RESPONSE_PROCESSING_ERROR respectively; expected input and response validation failures keep their more specific codes. Response-processing errors preserve the native Response and status, including when reading the response stream itself fails.

HTTP adapter boundary

@beignet/core/server is framework-neutral. It owns route matching, hooks, request validation, response validation, error mapping, and provider lifecycle. Adapters own the platform edge only:

• Convert the native request into HttpRequestLike, including its abort signal when the platform exposes one
• Call server.api(...) or a single route handler
• Convert HttpResponse back into the native response type

The public adapter contract is HttpAdapter<NativeRequest, NativeResponse>. Use it when building a runtime package beyond the first-party @beignet/web and @beignet/next adapters. Custom adapters must supply an absolute HTTP or HTTPS HttpRequestLike.url; invalid values are converted to a framework-owned 400 INVALID_REQUEST_URL response instead of escaping as a rejected handler promise.

Health and readiness

Use createHealthHandler(...) and runHealthChecks(...) from @beignet/core/server for app-owned liveness and readiness endpoints. Readiness checks should be cheap, bounded, and non-mutating:

import { createHealthHandler } from "@beignet/core/server";
import { getServer } from "@/server";

const server = await getServer();

const readiness = createHealthHandler(
  server.ports,
  {
    checks: {
      database: (ports) => ports.db.checkHealth(),
    },
    timeoutMs: 2000,
  },
  "production",
);
Copy

Provider checks such as ctx.ports.db.checkHealth() should be called from routes, workers, or deployment probes. Do not run migrations, drains, workers, or polling loops from health checks.

Request instrumentation and tracing

createServer(...) owns request instrumentation. For every request it resolves a request ID (from x-request-id, or generated) and a W3C trace context (from traceparent, or generated) before user hooks and context creation, passes them to context factories as requestId and trace, writes both response headers, and records request/error events into the provider instrumentation port resolved from final ports (ports.instrumentation, then ports.devtools). Without an installed sink, headers are still written and events are a no-op.

Recorded request events and afterSend hooks also carry a per-stage timing breakdown (stages): onRequestMs, parseMs, contextMs, beforeHandleMs, handlerMs, and sendMs. The devtools waterfall renders these as sub-bars under each request span, so slow context creation or a slow handler is visible per request instead of hiding inside one total duration.

import { appContext } from "@/server/context";

const server = await createServer({
  ports,
  providers,
  // Defaults shown. Pass false to disable headers and event recording.
  instrumentation: {
    requestIdHeader: "x-request-id",
    traceContextHeader: "traceparent",
    ignorePaths: ["/api/devtools"],
  },
  context: appContext,
});
Copy

Service contexts created with server.createServiceContext(...) receive fresh requestId and trace values per call. Context values win: when a factory sets its own requestId, headers and recorded events use it.

instrumentation: false keeps request and service correlation available to context factories and createAmbientAuditLog(...); it disables only response headers and instrumentation event recording. ignorePaths suppresses recorded events without removing ambient correlation from matching requests.

Trace primitives live in @beignet/core/tracing (TraceContext, TracingPort, TraceOperation, TraceSpan, createTraceContext, createChildTraceContext, parseTraceparent, createTraceparent, createTraceId, createSpanId, TraceCarrier, captureTraceCarrier, and parseTraceCarrier). The module is dependency-free so app context types can be imported from client bundles.

When final ports include ports.tracing, requests execute inside an active beignet.request <contract> span. Incoming traceparent and tracestate continue the trace; if the host already established an active span, Beignet's request span becomes its child. Use cases, listeners, job handlers, schedule handlers, and task handlers create nested active spans through the same port. Install @beignet/provider-tracing-opentelemetry to adapt this port to an app-owned OpenTelemetry SDK and emit baseline duration, error, and provider operation metrics.

The optional versioned TraceCarrier continues traces through outbox rows, event bus envelopes, and provider-backed job payloads. Event publish and job dispatch accept an optional third { trace } argument for transport layers; normal application calls remain two arguments. Unknown or malformed carriers are ignored so trace metadata cannot block message delivery.

Listener, job, schedule, and task runners accept both a lazy ctx factory and an explicit tracing port. Provider-backed runtimes should pass the installed port so Beignet starts the workflow span before resolving server.createServiceContext(...); the resulting context then inherits the real active span instead of treating local correlation IDs as a remote parent.

For custom TraceOperation values, attributes are span-only. Use metricAttributes only for bounded operation dimensions such as a contract, use-case, job, schedule, or task name. Never add request, actor, tenant, or payload values to metric attributes.

Use cases created with createUseCase(...) are instrumented by default. Each run resolves the instrumentation port from ctx.ports and records usecase lifecycle events plus correlated error events for failures. When a tracing port is installed, it also creates an active child span. Pass instrumentation: false to opt out of instrumentation events; tracing is controlled by whether the app installs ports.tracing.

App-owned onRun observers are best-effort. Synchronous throws and rejected observer promises are ignored so instrumentation cannot fail a use case or replace its original error.

createInstrumentedAuditLog({ audit, instrumentation }) from @beignet/core/ports writes durable audit entries first and mirrors sanitized audit activity into the resolved instrumentation sink.

createAmbientAuditLog(audit) from @beignet/core/server fills missing actor, tenant, requestId, and traceId fields from the ambient request context at record time. The server keeps that context current for requests (including identity elevated by route hooks) and for service contexts created with server.createServiceContext(...), so jobs, listeners, schedules, and tasks are covered. Because enrichment happens at record time, the wrapper also works for audit ports rebuilt per transaction inside a unit of work — wrap both the top-level port and the per-transaction rebuild:

import { createAmbientAuditLog } from "@beignet/core/server";

const audit = createAmbientAuditLog(
  createInstrumentedAuditLog({ audit: durableAudit, instrumentation: ports }),
);

await audit.record({
  action: "posts.publish",
  resource: { type: "post", id: post.id },
});
Copy

Entry-provided fields always win; on runtimes without AsyncLocalStorage the wrapper passes entries through unchanged, and entries without an actor normalize to an anonymous actor.

Route-owned response validation can be disabled with validateResponses: false on createServer(...), mirroring the client option of the same name. When enabled, Beignet sends the declared response schema's parsed output: object schemas can strip undeclared keys, transforms change the wire value, and catalog error-detail schemas apply the same semantics. The parsed body is also the value observed by response finalizers, afterSend hooks, and idempotency storage. Disabling validation sends route-owned handler bodies as-is without schema stripping or transforms.

Binder routes whose use case .output(...) schema is the declared success response schema by reference skip the redundant success-status parse only when use-case output validation is enabled. If the use case sets validate: { output: false }, route response validation still runs once. If profiling justifies disabling validation entirely, drive validateResponses from an environment flag so development and CI keep it on.

OpenAPI metadata

Add OpenAPI-specific metadata for documentation using the .openapi() method:

export const getTodo = todos
  .get("/api/todos/:id")
  .pathParams(z.object({ id: z.string() }))
  .responses({ 200: TodoSchema })
  .openapi({
    summary: "Get a todo by ID",
    description: "Retrieves a single todo item by its unique identifier",
    tags: ["todos"],
    deprecated: false,
    operationId: "getTodoById",
    externalDocs: {
      url: "https://docs.example.com/todos",
      description: "Todo documentation",
    },
    security: [{ bearerAuth: [] }],
  });
Copy

.openapi(...) and .meta({ openapi: ... }) share the same shallow merge semantics. OpenAPI fields from contract groups and earlier calls are preserved, while a later value replaces the same field. Structured fields such as responses are replaced as a whole rather than deep-merged. Prefer .openapi(...) for operation metadata; use .meta(...) when composing it with other metadata conventions.

Use requestBody, responses, and parameters overrides when an operation needs non-JSON media such as multipart uploads, binary downloads, event streams, or cookie parameters. contractsToOpenAPI(...) accepts schemaConverters for non-Zod Standard Schema libraries; custom converters run before Beignet's default Zod converter.

Descriptions attached before .optional() are preserved on generated query and header parameters, matching descriptions attached to the outer optional schema.

OpenAPI operationId defaults to the stable contract name. Explicit operation IDs are supported when an external SDK needs a different method name; server registration and OpenAPI generation reject duplicates. contractsToOpenAPI(...) also rejects duplicate method and normalized path combinations instead of replacing an earlier operation; :id and [id] both normalize to the OpenAPI path parameter {id}. Paths with the same hierarchy must also use consistent parameter names: /items/{id} and /items/{slug} cannot coexist in one OpenAPI document, even when they use different methods.

External TypeScript clients

Applications outside the contract-owning codebase can generate types from the served OpenAPI document and use them with an independent client:

bun add openapi-fetch
bun add --dev openapi-typescript typescript
bunx openapi-typescript https://api.example.com/api/openapi --output src/generated/api.ts
Copy

import createClient from "openapi-fetch";
import type { paths } from "./generated/api";

const api = createClient<paths>({
  baseUrl: "https://api.example.com",
});

const { data, error } = await api.GET("/api/todos/{id}", {
  params: { path: { id: "todo_123" } },
});
Copy

The generated client types cover paths, parameters, JSON bodies, responses, and declared catalog errors. Map OpenAPI string/binary schemas to Blob through the generator's Node API for typed uploads and downloads. See the OpenAPI guide for the complete generation, non-JSON media, authentication, and CI drift workflow.

Schema introspection

Contracts expose their schemas for runtime introspection:

getTodo.schema.pathParams;  // Path parameter schema
getTodo.schema.query;      // Query parameter schema
getTodo.schema.body;       // Request body schema
getTodo.schema.responses;  // Response schemas by status code
getTodo.path;              // "/api/todos/:id"
getTodo.method;            // "GET"
getTodo.metadata;          // { auth: "required", ... }
Copy