@beignet/core 0.0.2 → 0.0.4

package/README.md

@@ -2,9 +2,13 @@
 
 > Core framework primitives for Beignet
 
+> [!CAUTION]
+> Beignet is experimental alpha software. The `0.0.x` package line is for early
+> evaluation, and APIs may change between releases while the framework settles.
+
 This package provides Beignet's framework primitives: contracts, server runtime,
 typed client, use cases, ports, domain helpers, app errors, config, events,
-idempotency, outbox, mail, notifications, schedules, pagination helpers,
+idempotency, outbox, mail, notifications, schedules, uploads, pagination helpers,
 testing helpers, and OpenAPI generation.
 
 ## Installation
@@ -35,13 +39,14 @@ name the framework area they depend on.
 | --- | --- |
 | `@beignet/core/application` | Use case builder and test helpers |
 | `@beignet/core/client` | Typed HTTP client |
+| `@beignet/core/client-only` | Static lint marker for modules intended for client-side imports |
 | `@beignet/core/config` | Environment config validation |
 | `@beignet/core/contracts` | HTTP contract builders, types, path helpers, and contract metadata |
 | `@beignet/core/domain` | Entities, value objects, and domain events |
 | `@beignet/core/errors` | Error catalogs and response helpers |
 | `@beignet/core/events` | Events and listeners |
 | `@beignet/core/idempotency` | Retry-safe command, webhook, and job primitives |
-| `@beignet/core/jobs` | Job definitions and inline job dispatch |
+| `@beignet/core/jobs` | Job definitions, retry policies, and inline job dispatch |
 | `@beignet/core/mail` | Mail port and memory mailer |
 | `@beignet/core/notifications` | Notification definitions, dispatchers, mail channels, and test adapters |
 | `@beignet/core/openapi` | OpenAPI generation |
@@ -50,9 +55,179 @@ name the framework area they depend on.
 | `@beignet/core/ports` | App-facing ports, auth, audit, policies, cache, storage, logging, and redaction |
 | `@beignet/core/ports/testing` | Port and policy test helpers |
 | `@beignet/core/providers` | Provider lifecycle and instrumentation primitives |
-| `@beignet/core/schedules` | Scheduled task primitives |
+| `@beignet/core/schedules` | Schedule primitives |
 | `@beignet/core/server` | Framework-agnostic server runtime and hook helpers |
-| `@beignet/core/testing` | Test factories, seed definitions, and seed runners |
+| `@beignet/core/server-only` | Static lint marker for modules that must stay out of client bundles |
+| `@beignet/core/tasks` | Operational task definitions and inline task execution |
+| `@beignet/core/testing` | Test context factories, memory port fixtures, provider install helper, factories, seeds, and database harnesses |
+| `@beignet/core/tracing` | Dependency-free W3C trace context primitives |
+| `@beignet/core/uploads` | Upload definitions, router, signer port, and test signer |
+| `@beignet/core/uploads/client` | Browser upload client for server and direct uploads |
+
+## 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.
+- `terminal failure` means the work should not be retried automatically.
+- `dead letter` is a durable terminal delivery state, currently owned by the
+  outbox.
+
+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.
+
+## 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"`.
+
+```typescript
+import { definePorts } from "@beignet/core/ports";
+import type { AppPorts } from "@/ports";
+
+export const appPorts = definePorts<AppPorts>()({
+  bound: { gate },
+  deferred: ["db", "logger", "mailer", "storage"],
+});
+```
+
+Use `InferProviderPorts` with an `as const` provider list to type the runtime
+ports without casts:
+
+```typescript
+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>;
+```
+
+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:
+
+```typescript
+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.db);
+    return { ports: repositories };
+  },
+});
+```
+
+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.
+
+## 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.
+
+```json
+{
+  "beignet": {
+    "provider": {
+      "displayName": "Cache provider",
+      "ports": ["cache"],
+      "appPorts": [{ "name": "cache", "type": "CachePort" }],
+      "env": ["CACHE_URL", "CACHE_REGION"],
+      "requiredEnv": ["CACHE_URL"],
+      "registration": {
+        "required": true,
+        "tokens": ["cacheProvider", "createCacheProvider"]
+      },
+      "watchers": ["cache"]
+    }
+  }
+}
+```
+
+`env` lists all variables the provider may read. `requiredEnv` is the subset
+that `beignet doctor --strict` should require in app config.
+
+`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.
+
+Provider objects can also declare optional runtime-inert metadata for app-local
+tooling and documentation. It does not change runtime setup; it describes the
+package, contributed ports, required prior ports, env vars, and devtools
+watchers owned by the provider.
+
+```typescript
+import { createProvider } from "@beignet/core/providers";
+
+export const cacheProvider = createProvider({
+  name: "cache",
+  metadata: {
+    packageName: "@acme/beignet-provider-cache",
+    ports: ["cache"],
+    env: ["CACHE_URL"],
+    watchers: ["cache"],
+  },
+  setup() {
+    return { ports: { cache: createCachePort() } };
+  },
+});
+```
+
+## 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(...)`.
+
+```typescript
+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,
+    });
+  },
+});
+```
+
+Feature-owned task files should usually call use cases, repositories, or
+ports rather than hiding business rules inside a script.
 
 ## Key concepts
 
@@ -67,7 +242,7 @@ A **contract** is the single source of truth for an API endpoint. It describes:
 
 ### Contract group
 
-A **contract group** allows you to share configuration across related endpoints, such as a common namespace, authentication requirements, and shared response schemas.
+A **contract group** allows you to share configuration across related endpoints, such as a common namespace, route metadata, headers, and shared response schemas.
 
 ## Usage
 
@@ -75,10 +250,10 @@ A **contract group** allows you to share configuration across related endpoints,
 
 ```ts
 import { z } from "zod";
-import { createContractGroup } from "@beignet/core/contracts";
+import { defineContractGroup } from "@beignet/core/contracts";
 
 // Create a contract group for related endpoints
-const todos = createContractGroup()
+const todos = defineContractGroup()
   .namespace("todos")
   .prefix("/api/todos")
   .meta({ auth: "required" })
@@ -130,6 +305,22 @@ 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.
 
+`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. 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; `HEAD` is intentionally not served by `GET` handlers.
+
+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.
+
 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.
@@ -137,10 +328,10 @@ Request bodies are supported for `POST`, `PUT`, and `PATCH` contracts only.
 If you do not pass `name`, Beignet generates one from the HTTP method and full path:
 
 ```ts
-createContract({ method: "GET", path: "/users/:id" }).name;
+defineContract({ method: "GET", path: "/users/:id" }).name;
 // "getUsersById"
 
-createContract({ method: "POST", path: "/api/todos" }).name;
+defineContract({ method: "POST", path: "/api/todos" }).name;
 // "createTodos"
 ```
 
@@ -151,7 +342,7 @@ Auto-generated names ignore a leading `/api` segment, include path parameters as
 Use `.prefix(...)` on a contract group to compose shared URL path segments without repeating them on every route:
 
 ```ts
-const api = createContractGroup().prefix("/api/v1");
+const api = defineContractGroup().prefix("/api/v1");
 
 const todos = api
   .namespace("todos")
@@ -168,16 +359,198 @@ Prefixes compose immutably and normalize boundary slashes. `namespace()` control
 resource identity for contract names, OpenAPI tags, and client cache grouping;
 `prefix()` only controls URL paths.
 
-### Test factories and seeds
+### 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:
+
+```ts
+import { createUseCaseTester } from "@beignet/core/application";
+import { createTestContextFactory, createTestPorts } from "@beignet/core/testing";
+import {
+  createTestTenant,
+  createTestUserActor,
+} from "@beignet/core/ports/testing";
+
+const fixture = createTestPorts<AppContext["ports"]>({
+  base: appPorts,
+  overrides: {
+    gate: appPorts.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);
+```
+
+The returned fixture exposes captured side effects such as `events`,
+`dispatchedJobs`, `audit.entries`, `mailer.deliveries`,
+`notifications.deliveries`, `outbox.messages`, and memory storage for
+assertions.
+
+`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:
+
+```ts
+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" },
+  ]);
+});
+```
+
+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:
+
+```ts
+let fixture: ReturnType<ReturnType<typeof createTestContext<AppContext>>>;
+
+afterEach(() => {
+  fixture.dispose();
+});
+```
 
-Use `@beignet/core/testing` 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:
+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 flush `tx.events` to
+`ports.eventBus` after commit and clear it after rollback:
 
 ```ts
-import { defineFactory, defineSeed, runSeeds } from "@beignet/core/testing";
+import { createDomainEventRecorder } from "@beignet/core/ports";
+
+const fixture = createTestPorts<AppContext["ports"], AppTransactionPorts>({
+  transaction: {
+    ports: (ports) => ({ ...ports, events: createDomainEventRecorder() }),
+    outbox: true,
+  },
+});
+```
+
+`transaction.outbox` requires `transaction.ports` to include an `events`
+recorder such as `createDomainEventRecorder()` or
+`createOutboxEventRecorder(...)`; the kit throws a named error otherwise.
+
+#### 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(...)` with full inference:
+
+```ts
+// 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,
+  }),
+});
+```
+
+```ts
+// server/index.ts
+const server = await createNextServer({ ports, routes, context: appContext });
+
+// features/<feature>/tests/routes.test.ts
+const app = await createTestApp({ ports, routes, context: appContext });
+```
+
+### Testing providers
 
-const postFactory = defineFactory("post", {
+Use `installProviderForTest(...)` to run provider setup against test ports
+without hand-rolling setup, port merge, and lifecycle plumbing:
+
+```ts
+import { installProviderForTest } from "@beignet/core/testing";
+
+const { ports, result, start, stop } = await installProviderForTest(
+  redisProvider,
+  {
+    ports: { devtools },
+    config: { URL: "redis://localhost:6379" },
+  },
+);
+
+const cache = ports.cache as CachePort;
+await cache.set("posts:list", "[]");
+
+await stop();
+```
+
+`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:
+
+```ts
+import {
+  createDatabaseTestHarness,
+  createFactory,
+  defineSeed,
+  resetFactories,
+  runSeeds,
+} from "@beignet/core/testing";
+
+const postFactory = createFactory("post", {
   defaults: ({ sequence }) => ({
     title: `Post ${sequence}`,
     content: "Created in a test.",
@@ -194,11 +567,179 @@ const demoPostsSeed = defineSeed("demo-posts", {
 export async function seedDemoPosts(ctx: AppContext) {
   await runSeeds({ ctx, seeds: [demoPostsSeed] });
 }
+
+export function resetPostFactories() {
+  resetFactories(postFactory);
+}
+```
+
+For repository and persistence tests, compose the app-owned database fixture
+with the same factories and seeds:
+
+```ts
+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" });
 ```
 
 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/ports/testing` when tests need stable actor, tenant,
+authorization, or audit assertions:
+
+```ts
+import {
+  assertAuditEntry,
+  createPolicyTester,
+  createTestActivityContext,
+  createTestTenant,
+  createTestUserActor,
+} from "@beignet/core/ports/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",
+  },
+]);
+
+assertAuditEntry(audit.entries, {
+  action: "posts.publish",
+  actorId: "user_1",
+  tenantId: "tenant_1",
+  resourceType: "post",
+  resourceId: post.id,
+});
+```
+
+`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:
+
+```ts
+import {
+  assertDispatchedJob,
+  assertIdempotencyCompleted,
+  assertMailDelivery,
+  assertNotificationDelivery,
+  assertOutboxDelivered,
+  assertOutboxDrainResult,
+  assertOutboxPending,
+  assertProviderInstrumentationEvent,
+  assertRecordedEvent,
+  assertStorageObject,
+  createRecordingEventBus,
+  createRecordingJobDispatcher,
+  createRecordingProviderInstrumentation,
+} from "@beignet/core/ports/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,
+});
+
+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 },
+});
+```
+
+`createProviderInstrumentation(...)` adds `details.providerName` to custom and
+typed provider events, so tests and devtools can group provider work
+consistently.
+
 ### Pagination
 
 Use `@beignet/core/pagination` to keep list use cases and repository ports
@@ -222,10 +763,65 @@ return ctx.ports.posts.findMany({
 Beignet's convention is `items` for list contents and `page` for pagination
 metadata. Keep filters and sort options app-owned plain objects.
 
+### Rate limiting
+
+Use `createRateLimitHooks(...)` from `@beignet/core/server` to enforce
+`contract.metadata.rateLimit` at the HTTP boundary:
+
+```ts
+import { createRateLimitHooks } from "@beignet/core/server";
+
+const server = await createServer<AppContext, AppPorts>({
+  ports: appPorts,
+  hooks: [createRateLimitHooks<AppContext>()],
+  // ...
+});
+```
+
+- `global` and `ip` scopes run in `onRequest` before parsing and context
+  creation; `user` scope runs in `beforeHandle` once `ctx.actor` exists.
+- `ip` buckets default to the last `x-forwarded-for` entry, the address
+  appended by the platform's trusted proxy. Use the `ipSource` option to
+  switch to `"x-forwarded-for-first"` behind a header-normalizing edge, or
+  pass a function for platform headers such as `cf-connecting-ip`.
+- Denials throw the framework `429 Too Many Requests` catalog error with
+  `scope`, `retryAfterSeconds`, and `resetAt` details. 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.
+
 ### Idempotency
 
-Use `@beignet/core/idempotency` when a command, webhook, or job may be retried
-and must not perform duplicate work:
+Use `createIdempotencyHooks(...)` from `@beignet/core/server` to enforce
+`contract.metadata.idempotency` at the HTTP boundary, mirroring
+`createRateLimitHooks(...)`:
+
+```ts
+import { createIdempotencyHooks } from "@beignet/core/server";
+
+const server = await createServer<AppContext, AppPorts>({
+  ports: appPorts,
+  hooks: [createIdempotencyHooks<AppContext>()],
+  // ...
+});
+```
+
+The hook reads the key from the metadata header (default `idempotency-key`),
+reserves it through `ctx.ports.idempotency` after request parsing, 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.
+
+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.
+
+Use `runIdempotently(...)` from `@beignet/core/idempotency` when a non-HTTP
+command, webhook, or job may be retried and must not perform duplicate work:
 
 ```ts
 import {
@@ -234,17 +830,17 @@ import {
 } from "@beignet/core/idempotency";
 
 const result = await runIdempotently(ctx.ports.idempotency, {
-  namespace: "todos.create",
-  key: input.idempotencyKey,
+  namespace: "todos.import",
+  key: input.importId,
   scope: {
     tenantId: ctx.tenant?.id,
     actorId: ctx.actor?.id,
   },
   fingerprint: await createIdempotencyFingerprint(input, {
-    omit: ["idempotencyKey"],
+    omit: ["importId"],
   }),
   ttlSec: 60 * 60 * 24,
-  run: () => ctx.ports.uow.transaction((tx) => tx.todos.create(input)),
+  run: () => ctx.ports.uow.transaction((tx) => tx.todos.importBatch(input)),
 });
 ```
 
@@ -257,9 +853,11 @@ const idempotency = createMemoryIdempotencyStore();
 ```
 
 Production apps should back `IdempotencyPort` with atomic SQL or Redis storage.
-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.
+The Drizzle/libSQL path can use `createDrizzleTursoIdempotencyPort(...)` from
+`@beignet/provider-drizzle-turso`. 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.
 
 ### Outbox
 
@@ -306,9 +904,37 @@ await drainOutbox({
 The outbox is at-least-once delivery. Use idempotent listeners or jobs when a
 duplicate delivery would be harmful.
 
-### Contract metadata
+### Schedules
 
-Use metadata to drive cross-cutting concerns like authentication, rate limiting, and idempotency:
+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:
+
+```ts
+import { createInlineScheduleRunner } from "@beignet/core/schedules";
+
+const runner = createInlineScheduleRunner<AppContext>({
+  ctx,
+  instrumentation: ctx.ports.devtools,
+  instrumentationContext: {
+    requestId: ctx.requestId,
+    traceId: ctx.traceId,
+  },
+});
+
+await runner.run(SendDailyDigestSchedule, { source: "vercel-cron" });
+```
+
+`instrumentationContext` attaches request correlation fields to recorded
+events. Recording failures are isolated from schedule execution and reported
+to `onHookError` when provided. Handler failures still 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:
 
 ```ts
 const sendMessage = messages
@@ -331,6 +957,159 @@ const sendMessage = messages
   });
 ```
 
+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:
+
+```ts
+import { createAuthHooks, defineRouteGroup } from "@beignet/core/server";
+import type { AppContext } from "@/app-context";
+
+const auth = createAuthHooks<AppContext>()({
+  resolve: ({ ctx }) => {
+    return ctx.auth ? { user: ctx.auth.user } : null;
+  },
+});
+
+export const messageRoutes = defineRouteGroup<AppContext>()({
+  name: "messages",
+  routes: [
+    {
+      contract: sendMessage,
+      hooks: [auth.required()],
+      useCase: sendMessageUseCase,
+    },
+  ],
+});
+```
+
+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), and the use case input
+defaults to the merged request parts via `defaultBinderInput` — query lowest,
+then body, then path; headers are never merged and need 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<AppContext>()` remains
+available for full handlers that read hook-added `ctx` fields.
+
+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`:
+
+```ts
+const writerAuth = createAuthHooks<AppContext>()({
+  name: "writer",
+  headers: writerHeadersSchema,
+  resolve: ({ headers }) => ({
+    actor: createUserActor(headers["x-user-id"]),
+  }),
+});
+```
+
+### 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`
+- 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.
+
+### 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.
+
+```ts
+const server = await createServer({
+  ports,
+  providers,
+  // Defaults shown. Pass `instrumentation: false` to disable entirely.
+  instrumentation: {
+    requestIdHeader: "x-request-id",
+    traceContextHeader: "traceparent",
+    ignorePaths: ["/api/devtools"],
+  },
+  context: {
+    request: ({ ports, requestId, trace }) => ({
+      requestId,
+      ...trace,
+      ports,
+    }),
+  },
+});
+```
+
+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.
+
+Trace primitives live in `@beignet/core/tracing` (`TraceContext`,
+`createTraceContext`, `createChildTraceContext`, `parseTraceparent`,
+`createTraceparent`, `createTraceId`, `createSpanId`). The module is
+dependency-free so app context types can be imported from client bundles.
+
+Use cases created with `createUseCase(...)` are instrumented by default. Each
+run resolves the instrumentation port from `ctx.ports`, creates a child span
+from the context's trace fields, and records `usecase` lifecycle events plus
+correlated `error` events for failures. Pass `instrumentation: false` to opt
+out.
+
+`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:
+
+```ts
+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 },
+});
+```
+
+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. Binder routes whose use case `.output(...)` schema is the
+declared success response schema by reference already skip the redundant
+success-status parse; 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:
@@ -354,6 +1133,12 @@ export const getTodo = todos
   });
 ```
 
+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.
+
 ### Schema introspection
 
 Contracts expose their schemas for runtime introspection:
@@ -371,12 +1156,12 @@ getTodo.metadata;          // { auth: "required", ... }
 
 ## API reference
 
-### `createContractGroup()`
+### `defineContractGroup()`
 
 Creates a new contract group for defining related endpoints.
 
 ```ts
-const group = createContractGroup()
+const group = defineContractGroup()
   .namespace("myNamespace")    // Optional resource namespace
   .prefix("/api/v1")           // Optional URL path prefix
   .meta({ auth: "required" })  // Shared metadata
@@ -386,6 +1171,10 @@ const group = createContractGroup()
   });
 ```
 
+Shared catalog errors merge with route-level `.errors(...)` declarations, so
+each contract carries the union of group and route errors. Later declarations
+win when the same catalog key is declared twice.
+
 Any non-empty response map is treated as a response contract. Include
 successful statuses such as `200` or `201` alongside custom error statuses; use
 `responses: {}` only when you want to skip response validation. Prefer
@@ -406,7 +1195,7 @@ standard error envelope.
 | `.headers(schema)` | Define request header schema |
 | `.body(schema)` | Define request body schema |
 | `.responses({ ... })` | Define or merge response schemas by status code |
-| `.errors({ ... })` | Declare route-owned catalog errors using Beignet's standard error envelope |
+| `.errors({ ... })` | Declare route-owned catalog errors using Beignet's standard error envelope; merges with group and earlier declarations |
 | `.meta(metadata)` | Add custom metadata |
 | `.openapi(options)` | Add OpenAPI metadata (summary, tags, etc.) |
 
@@ -422,9 +1211,11 @@ OpenAPI generation currently requires Zod schemas, even though core contracts ca
 
 ## Related packages
 
+- [`@beignet/web`](https://beignet.dev/server) - Web Fetch server adapter
 - [`@beignet/next`](https://beignet.dev/server) - Next.js server adapter
 - [`@beignet/react-query`](https://beignet.dev/react-query) - TanStack Query integration
 - [`@beignet/react-hook-form`](https://beignet.dev/react-hook-form) - React Hook Form integration
+- [`@beignet/react-uploads`](https://beignet.dev/react-uploads) - React upload state and progress hooks
 - [`@beignet/nuqs`](https://beignet.dev/nuqs) - URL query state integration with nuqs
 - [`@beignet/devtools`](https://beignet.dev/devtools) - Local request, provider, and audit timeline