@beignet/core 0.0.32 → 0.0.34

package/README.md

@@ -58,7 +58,7 @@ name the framework area they depend on.
 | `@beignet/core/events` | Events and listeners |
 | `@beignet/core/flags` | Feature flag definitions, FlagsPort, memory/static adapters, and helpers |
 | `@beignet/core/idempotency` | Retry-safe command, webhook, and job primitives |
-| `@beignet/core/jobs` | Job definitions, retry policies, and inline job dispatch |
+| `@beignet/core/jobs` | Job definitions, retry policies, timeout guards, execution hooks, execution lease helpers, uniqueness guards, and inline job dispatch |
 | `@beignet/core/locks` | Lease-backed LocksPort, memory adapter, memory provider, and helpers |
 | `@beignet/core/mail` | Mail port, memory mailer, and memory mailer provider |
 | `@beignet/core/memo` | Request-scoped memoization for port lookups |
@@ -68,14 +68,14 @@ name the framework area they depend on.
 | `@beignet/core/payments` | Payments port, memory payments adapter, and memory payments provider |
 | `@beignet/core/pagination` | Offset/cursor page types, normalizers, and result helpers |
 | `@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/search` | Search index definitions, SearchPort, memory adapter, memory provider, and helpers |
 | `@beignet/core/schedules` | Schedule primitives |
-| `@beignet/core/server` | Framework-agnostic server runtime and hook helpers |
+| `@beignet/core/server` | Framework-agnostic server runtime, security headers, CSRF, and hook helpers |
 | `@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/tenancy` | Branded tenant scope helpers for repository boundaries |
+| `@beignet/core/testing` | Port and policy assertions, recording adapters, 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 (`createUploads<AppContext>()` app-bound builder), router, signer port, and test signer |
 | `@beignet/core/uploads/client` | Browser upload client for server and direct uploads |
@@ -98,10 +98,100 @@ Jobs, outbox delivery, and schedule runners use the same terms:
 - `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.
 
+Jobs may also declare dispatch-time uniqueness and execution leases:
+
+```typescript
+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,
+  });
+}
+```
+
+`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.
+
+`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.
+
+`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.
@@ -180,9 +270,12 @@ provider `name` that defaults to `"memory-mailer"`.
 `{ 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. Options accept the dispatcher's
-`onError` handler plus a provider `name` that defaults to
-`"inline-notifications"`.
+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"`.
 
 ```typescript
 // server/providers.ts
@@ -199,8 +292,56 @@ export const providers = [
 
 Replace `createMemoryMailerProvider(...)` with a real mail provider such as
 `@beignet/provider-mail-resend` for production delivery. Production apps can
-keep the inline notifications provider and run it from jobs or listeners, or
-replace it with an app-owned dispatcher when delivery needs custom semantics.
+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.
+
+```typescript
+// 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,
+  });
+```
+
+```typescript
+// 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,
+      }),
+    ],
+  });
+});
+```
+
+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
 
@@ -215,6 +356,8 @@ import {
   type EntitlementDecisionObserver,
   requireEntitlement,
 } from "@beignet/core/entitlements";
+import { createTenant } from "@beignet/core/ports";
+import { createTenantScope } from "@beignet/core/tenancy";
 
 function createBillingEntitlements(
   billing: BillingRepository,
@@ -222,7 +365,10 @@ function createBillingEntitlements(
 ) {
   return createEntitlements({
     async inspect(input) {
-      const account = await billing.findByTenantId(input.subject.id);
+      if (input.subject.type !== "tenant") return false;
+      const account = await billing.findByTenantScope(
+        createTenantScope(createTenant(input.subject.id)),
+      );
       return account?.status === "active";
     },
     onDecision: recordDecision,
@@ -353,6 +499,56 @@ 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`.
 
+## 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.
+
+```typescript
+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({ metadata, uploadId }) {
+    return `issues/${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.create({
+      id: files[0]!.uploadId,
+      key: files[0]!.key,
+    });
+  },
+});
+```
+
+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(...)`.
+
 ## Webhooks
 
 Use `@beignet/core/webhooks` for provider-neutral inbound webhook definitions,
@@ -378,6 +574,10 @@ export const issueWebhook = defineWebhook("issues.provider", {
     secret: process.env.PROVIDER_WEBHOOK_SECRET ?? "",
     signatureHeader: "x-provider-signature",
     signaturePrefix: "sha256=",
+    timestamp: {
+      header: "x-provider-timestamp",
+      toleranceSec: 300,
+    },
   }),
 });
 ```
@@ -399,6 +599,13 @@ direction. Attach provider verifiers at the route boundary through the
 (`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.
+
 ## Provider metadata
 
 Reusable provider packages should declare static metadata in `package.json`
@@ -418,7 +625,7 @@ without importing provider implementation code.
       "requiredTables": ["cache_entries"],
       "registration": {
         "required": true,
-        "tokens": ["cacheProvider", "createCacheProvider"]
+        "tokens": ["createCacheProvider"]
       },
       "watchers": ["cache"]
     }
@@ -578,6 +785,45 @@ 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.
 
+### 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:
+
+```ts
+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,
+  }),
+});
+```
+
+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
@@ -645,7 +891,7 @@ import { createTestContextFactory, createTestPorts } from "@beignet/core/testing
 import {
   createTestTenant,
   createTestUserActor,
-} from "@beignet/core/ports/testing";
+} from "@beignet/core/testing";
 
 const fixture = createTestPorts<AppContext["ports"]>({
   base: appPorts,
@@ -785,7 +1031,7 @@ 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 `bun test`.
+  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
@@ -807,18 +1053,47 @@ Both entrypoints require `context.service` in the blueprint, generate fresh
 `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:
+
+```ts
+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
+```
+
+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:
 
 ```ts
+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(
-  redisCacheProvider,
+  createRedisCacheProvider(),
   {
-    ports: { devtools },
     config: { URL: "redis://localhost:6379" },
   },
 );
@@ -899,7 +1174,7 @@ ORM table objects, or provider SDKs directly.
 
 ### Port testing helpers
 
-Use `@beignet/core/ports/testing` when tests need stable actor, tenant,
+Use `@beignet/core/testing` when tests need stable actor, tenant,
 authorization, or audit assertions:
 
 ```ts
@@ -909,7 +1184,7 @@ import {
   createTestActivityContext,
   createTestTenant,
   createTestUserActor,
-} from "@beignet/core/ports/testing";
+} from "@beignet/core/testing";
 
 const activity = createTestActivityContext({
   actor: createTestUserActor("user_1", { role: "admin" }),
@@ -963,7 +1238,7 @@ import {
   createRecordingEventBus,
   createRecordingJobDispatcher,
   createRecordingProviderInstrumentation,
-} from "@beignet/core/ports/testing";
+} from "@beignet/core/testing";
 import { drainOutbox } from "@beignet/core/outbox";
 import { createProviderInstrumentation } from "@beignet/core/providers";
 
@@ -1113,6 +1388,29 @@ 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. Use
+`resolveTrustedRequest(...)` when app code needs external request metadata
+behind a platform edge or reverse proxy that strips or normalizes forwarding
+headers before they reach application code:
+
+```ts
+import { resolveTrustedRequest } from "@beignet/core/server";
+
+const requestInfo = resolveTrustedRequest(req, {
+  clientIp: "x-forwarded-for-last",
+});
+
+requestInfo.origin; // "https://app.example.com"
+requestInfo.clientIp; // resolved only when clientIp is configured
+```
+
+The same `trustedProxy` policy is accepted by `createRateLimitHooks(...)` for
+IP-scoped keys and by `createCsrfHooks(...)` for comparing browser origins
+against the external host and protocol. Configure it only when every request
+passes through your trusted edge.
+
 ### Rate limiting
 
 Use `createRateLimitHooks(...)` from `@beignet/core/server` to enforce
@@ -1131,14 +1429,15 @@ const server = await createServer<AppContext, AppPorts>({
 - `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.
-- `ip` scopes require an explicit `ipSource`. 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(...)`.
-  Use `"x-forwarded-for-last"` only behind a trusted proxy that appends the
-  socket address, `"x-forwarded-for-first"` when a trusted edge normalizes
-  the header, or pass a function for platform headers such as
-  `cf-connecting-ip`.
+- `ip` scopes require an explicit `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
+  `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
+  `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
   shares one `ip:unknown` bucket.
@@ -1230,12 +1529,17 @@ 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) => {
@@ -1265,6 +1569,10 @@ await drainOutbox({
 The outbox is at-least-once delivery. Use idempotent listeners or jobs when a
 duplicate delivery would be harmful.
 
+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
@@ -1373,6 +1681,27 @@ const writerAuth = createAuthHooks<AppContext>()({
 });
 ```
 
+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:
+
+```ts
+import { createSecurityHeadersHooks } from "@beignet/core/server";
+
+const securityHeaders = createSecurityHeadersHooks({
+  contentSecurityPolicy: "default-src 'self'; frame-ancestors 'none'",
+  strictTransportSecurity: {
+    maxAgeSec: 31_536_000,
+    includeSubDomains: true,
+  },
+});
+```
+
+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:
 
@@ -1390,6 +1719,31 @@ const browserAppCors = createCorsHooks({
 apps do not accidentally reflect arbitrary request origins for cookies or
 authorization headers.
 
+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:
+
+```ts
+import { createCsrfHooks } from "@beignet/core/server";
+
+const csrf = createCsrfHooks({
+  allowMissingOrigin: false,
+  trustedProxy: {},
+  trustedOrigins: ["https://app.example.com"],
+  token: {
+    cookieName: "csrf",
+    headerName: "x-csrf-token",
+  },
+  skip: ({ contract }) => contract.name.startsWith("webhooks."),
+});
+```
+
+Pass `trustedProxy: {}` only when Beignet should compare `Origin` or `Referer`
+against the external `x-forwarded-host` and `x-forwarded-proto` values written
+by your trusted edge.
+
 ### HTTP adapter boundary
 
 `@beignet/core/server` is framework-neutral. It owns route matching, hooks,
@@ -1471,15 +1825,37 @@ Service contexts created with `server.createServiceContext(...)` receive fresh
 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.
+`TracingPort`, `TraceOperation`, `TraceSpan`, `createTraceContext`,
+`createChildTraceContext`, `parseTraceparent`, `createTraceparent`,
+`createTraceId`, `createSpanId`). 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.
+
+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`, 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.
+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`.
 
 `createInstrumentedAuditLog({ audit, instrumentation })` from
 `@beignet/core/ports` writes durable audit entries first and mirrors sanitized
@@ -1558,7 +1934,6 @@ 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.pathTemplate;      // "/api/todos/:id" (alias)
 getTodo.method;            // "GET"
 getTodo.metadata;          // { auth: "required", ... }
 ```