@daloyjs/core 1.2.0 → 1.3.0

package/README.md

@@ -664,13 +664,14 @@ The framework refuses to start (or to construct) when configuration is unsafe:
 - `idempotency()` with `Idempotency-Key` fingerprinting + byte-for-byte response replay, in-flight `409`, `422` on key reuse with a different payload, and a pluggable `IdempotencyStore` (in-memory default) at `@daloyjs/core/idempotency`.
 - `responseCache()` server-side body cache (cache-key + TTL with `s-maxage`/`max-age` orchestration, request `no-store`/`no-cache` directives, recursion-safe stale-while-revalidate, proactive `varyHeaders` keying, `X-Cache` HIT/MISS/STALE marker, pluggable `ResponseCacheStore` whose in-memory default is bounded on both entry count and retained bytes) at `@daloyjs/core/response-cache`. Never caches `Set-Cookie`, `private`/`no-store`/`no-cache`, or `Vary: *` responses, and strips `Age`/hop-by-hop/`X-Request-Id` from stored entries so a hit never replays another request's correlation id. **Fail-closed on every principal dimension (CWE-524):** the key is the full _effective request URI_ including the authority (RFC 9111 §4), so hostnames never share entries; requests carrying `Authorization` **or** `Cookie` bypass the shared cache unless a `principal` names the caller (then each gets its own entry) or the header is explicitly declared shareable; a tenant resolved by `tenancy()` is folded into the key automatically — with a boot guard that refuses to start if the cache is mounted ahead of `tenancy()`; and the response's **own `Vary` header** is honoured as a secondary key (RFC 9111 §4.1), so the `Vary: Origin` written by `cors()` and the `Vary: Accept-Encoding` written by `compression()` keep one caller's allowed origin — or their gzipped bytes — from being served to the next, with each variant stored separately so they all stay warm. Complements `etag()`/`compression()`, which do not cache bodies.
 - `paginationQuery()` / `encodeCursor()` / `decodeCursor()` / `buildPageLinks()` / `buildLinkHeader()` cursor-pagination helpers at `@daloyjs/core/pagination`: opaque base64url cursors (length-capped, prototype-pollution-safe decode → `400` on tamper), RFC 8288 `Link` header emission with CRLF / header-injection guards, and a Standard Schema that validates `cursor`/`limit` and auto-wires both into the OpenAPI spec + typed client via `toJSONSchema()`.
-- `app.metrics()` + `MetricsRegistry` / `httpMetrics()` Prometheus / OpenMetrics exposition at `@daloyjs/core/metrics`: dependency-free counters / gauges / histograms, RED instrumentation (`http_requests_total`, `http_request_duration_seconds`, `http_requests_in_flight`) plus process gauges, exposition-injection-safe name/label validation, a per-metric cardinality cap, and an opt-in `/metrics` route with the same hardened posture as `app.healthcheck()` (bearer token + `timingSafeEqual`, per-IP rate limit, refuse-to-boot unauthenticated in production). The repo ships an `examples/observability/` Docker Compose stack that starts a pre-configured Prometheus + Grafana pair (with an auto-provisioned RED + heatmap dashboard) against any local app via `docker compose -f examples/observability/docker-compose.yml up`.
+- `app.metrics()` + `MetricsRegistry` / `httpMetrics()` Prometheus / OpenMetrics exposition at `@daloyjs/core/metrics`: dependency-free counters / gauges / histograms, RED instrumentation (`http_requests_total`, `http_request_duration_seconds`, `http_requests_in_flight`, `route` from the matched template) plus unprefixed process gauges (`process_resident_memory_bytes`), exposition-injection-safe name/label validation, a per-metric cardinality cap (`daloy_metrics_series_dropped_total`), and an opt-in `/metrics` route with the same hardened posture as `app.healthcheck()` (bearer token + portable `timingSafeEqual`, per-IP rate limit, refuse-to-boot unauthenticated in production). Pull scrape is for long-lived processes; on Workers / Lambda / Vercel use `telemetry: true` (OTLP push). The repo ships an `examples/observability/` Docker Compose stack that starts a pre-configured Prometheus + Grafana pair (with an auto-provisioned RED + heatmap dashboard) against any local app via `docker compose -f examples/observability/docker-compose.yml up`.
 - `otelTracing()` OpenTelemetry-compatible distributed tracing at `@daloyjs/core/tracing`: a dependency-free `Hooks` bundle that opens one `SERVER` span per request, attaches HTTP semantic-convention attributes (`http.request.method`, `url.path`, `server.address` / `server.port`, `http.response.status_code`, …), records exceptions + escalates `5xx` to `ERROR`, guarantees a single `span.end()`, and exposes the live span on `ctx.state.otelSpan`. Bring any tracer matching the small `TracingTracer` interface (the real `@opentelemetry/api` SDK on Node, or a custom exporter on Workers/Deno) plus your own propagator via `contextFromRequest` for `traceparent` continuation — no OTel SDK is forced into your install. The `examples/observability/` stack also runs **Jaeger**, and `examples/otel-tracing-demo.ts` ships a ~120-line dependency-free OTLP/HTTP exporter that streams spans straight to it.
-- `new App({ telemetry: true })` native OpenTelemetry OTLP push export at `@daloyjs/core/otlp`: one flag tees the app logger to the collector as OTLP logs and records `http.server.request.duration` per the OTel HTTP semantic conventions (spec attributes incl. `http.route` from the matched route template via the new `ctx.routePath`, spec bucket boundaries), pushed as dependency-free OTLP/HTTP JSON to the endpoint in the standard `OTEL_EXPORTER_OTLP_*` env vars — zero config on collector-based platforms that inject them, silent no-op without them. Standalone `createOtlpLogExporter()` / `createOtlpMetricsExporter()` (cumulative temporality — totals survive failed pushes) / `semconvHttpMetrics()` exports; fail-safe by contract (bounded queues, series-cardinality cap, a dead collector never affects serving, tenant-routing header values never logged).
+- `new App({ telemetry: true })` native OpenTelemetry OTLP push export at `@daloyjs/core/otlp`: one flag tees the app logger to the collector as OTLP logs and records `http.server.request.duration` per the OTel HTTP semantic conventions (spec attributes incl. `http.route` from the matched route template via the new `ctx.routePath`, spec bucket boundaries), pushed as dependency-free OTLP/HTTP JSON to the endpoint in the standard `OTEL_EXPORTER_OTLP_*` env vars — zero config on collector-based platforms that inject them, silent no-op without them. Standalone `createOtlpLogExporter()` / `createOtlpMetricsExporter()` (cumulative temporality — totals survive failed pushes) / `semconvHttpMetrics()` exports; fail-safe by contract (bounded queues, series-cardinality cap, a 5s export timeout, a dead collector never affects serving, tenant-routing header values never logged). Isolate runtimes flush per request through `toFetchHandler` (Cloudflare `waitUntil`, Vercel) and `toLambdaHandler` (awaited); Node/Bun/Deno flush on an interval plus shutdown.
 - `tenancy()` secure-by-default multitenancy at `@daloyjs/core/tenancy`: a dependency-free `Hooks` bundle that resolves the calling tenant once per request and exposes it on `ctx.state.tenant`. Pluggable resolution (`tenantFromSubdomain` PSL-aware, `tenantFromHeader`, `tenantFromPathPrefix`, `tenantFromClaim`, or a custom `(ctx) => string`, tried in array order). **Refuse-unresolved by default** (no ambient "default" tenant leak), **format-validated ids** (rejects key/log-injection + cache-poisoning payloads before they reach a key), **no-enumeration `404`** for unknown tenants, and **host-spoof-safe** subdomain resolution. A `tenantScope()` key helper drops straight into `rateLimit` `keyGenerator` and `concurrencyLimit` / `idempotency` `scope` to partition each per tenant (CWE-524 cross-tenant cache defense); `responseCache()` needs no wiring at all — it reads the resolved tenant itself and refuses to boot if mounted ahead of `tenancy()`. Runnable `examples/multitenancy-demo.ts`.
 - `resilientFetch()` + `CircuitBreaker` outbound resilience at `@daloyjs/core/fetch-resilience`: a dependency-free circuit breaker (`closed → open → half-open`), retry-with-backoff (exponential + full jitter, idempotent-method/transient-status scoped, honours `Retry-After`), and a per-call timeout (`AbortController` → `FetchTimeoutError`) designed to layer **on top of** `fetchGuard()` — an `SsrfBlockedError` is a terminal refusal that is never retried and never trips the breaker, so SSRF protection stays intact under the resilience layer.
 - `createWebhookSender()` + `MemoryWebhookDeadLetterSink` outbound webhook delivery at `@daloyjs/core/webhook-delivery`: the outbound counterpart to `verifyWebhookSignature()` — timestamped HMAC-signed `POST`s (`webhook-id` / `webhook-timestamp` / `webhook-signature`, computed over `"<timestamp>.<body>"` and reused across retries for safe deduping), bounded retry-with-backoff (transient-status + network scoped, honours `Retry-After`), per-attempt timeout, and dead-letter semantics. Transport defaults to `fetchGuard()`, so a subscriber URL pointing at cloud metadata or a private range is refused with a terminal `SsrfBlockedError` (never retried, dead-lettered once). Zero runtime dependencies.
 - `app.cron()` + standalone `Scheduler` in-process scheduled tasks at `@daloyjs/core/scheduler`: a queue-agnostic schedule primitive for periodic housekeeping (cache sweeps, token refresh, reconciliation). Fixed intervals or 5-field cron expressions (lists / ranges / steps / named months & days / `@hourly`–`@yearly` aliases / optional IANA `timeZone`), arithmetic cron parsing (no backtracking regex), fixed-rate **single-flight** (overlapping ticks are skipped, never run concurrently), per-run `timeoutMs` with `AbortSignal`, and graceful-shutdown integration (stop arming → await in-flight → abort after grace). Timers are `unref`'d. `parseCron()` / `nextCronRun()` exported standalone. Zero runtime dependencies.
+- Background jobs (queue-agnostic) at `@daloyjs/core/jobs`: durable `{ name, payload }` units that outlive the HTTP request and the process — `JobStore` SPI (all durability lives behind it; Redis/Postgres/SQS are user adapters, never core deps), `MemoryJobStore` for tests and single-process apps, `createJobQueue()` (name/queue charset allowlists, plain-JSON payloads capped at 64 KiB with prototype-pollution rejection, idempotency-key dedupe with conflict-on-reuse, delayed `runAt`, integer `priority`), and `createJobWorker()` (atomic claims with leases + fencing, auto-heartbeat plus `ctx.heartbeat()`, bounded concurrency, per-attempt `timeoutMs` via `AbortSignal`, retries with exponential backoff + full jitter, dead letters, graceful `stop()` drain, `runOnce()` for tests). Delivery is **at-least-once** — handlers must be idempotent (pass a key through to downstream APIs like Stripe's `Idempotency-Key`); `EnqueueOptions.idempotencyKey` collapses duplicate producers the way `idempotency()` collapses duplicate POSTs. `app.useJobs({ store, handlers, startWorker })` drains the worker on graceful shutdown and warns on a Memory store under production config; `app.cronEnqueue()` turns a cron tick into an idempotent enqueue so multi-replica crons do not double-fire. This is not a workflow/replay engine — no durable functions, no worlds, no `await sleep("7 days")`. Zero runtime dependencies.
 - `clientCertAuth()` mTLS / client-certificate auth at `@daloyjs/core/mtls`: authenticate zero-trust / service-to-service callers by their TLS client certificate from two sources — **native TLS** (the Node adapter lazily reads the peer cert off the socket; plain requests pay nothing) or a **TLS-terminating proxy** (Envoy `X-Forwarded-Client-Cert` and nginx/HAProxy-style structured headers). `requireVerified` by default, exact `allowSubjectCNs` / `allowIssuerCNs`, **constant-time** `allowFingerprints`, `allowSANs` (SPIFFE/DNS/URI/IP, `TYPE:value` or bare), validity-window enforcement, and a custom async `verify()` hook. Missing cert → `401` problem+json with `Cache-Control: no-store`; any failed check → `403` (never echoes cert details). The accepted `ClientCertificate` is stamped on `ctx.state`. `parseForwardedClientCert()` / `normalizePeerCertificate()` exported standalone. Zero runtime dependencies.
 - `autoBan()` adaptive auto-ban (fail2ban-style) at `@daloyjs/core/auto-ban`: temporarily ban abusive clients after repeated suspicious responses (default `401` / `403` / `429`, configurable `watchStatuses`) within a rolling `windowMs`. Bans **escalate** exponentially for repeat offenders (`banMs` → `2×` → `4×`, capped at `maxBanMs`) and **decay** once the client goes quiet. Observes the outgoing status via `onSend` (counts failures from any downstream middleware/handler), enforces in `beforeHandle`. Secure-by-default identity attribution — refuses to construct without `keyGenerator`, `trustedHops`, or `trustProxyHeaders` so one offender can never ban everyone; unattributable requests are skipped. Proxy-header identity is **spoof-resistant**: the client IP is read from the rightmost `X-Forwarded-For` entry (the one your proxy appended) via `resolveForwardedClientIp()`, so rotating spoofed left entries can neither evade strike accumulation nor frame a victim IP for banning; multi-hop chains declare their hop count with `trustedHops` (shared by `rateLimit()`, `loginThrottle()`, `concurrencyLimit()`, `geoBlock()`, `ipRestriction()`, `ipReputation()`, and `botGuard()`). For deployments where the origin itself is reachable, `trustedProxies` (a CIDR allowlist of your proxy peer addresses, accepted by every guard in that list) goes further: the immediate TCP peer is verified against the allowlist before any forwarded header is believed, so a direct-to-origin caller's spoofed `X-Forwarded-For` is ignored entirely — closing victim-IP framing and ban/limit evasion at the framework layer, and failing closed on peer-less edge platforms. Pluggable `AutoBanStore` (mirrors the `rateLimit()` store; in-memory default, Redis-able for multi-instance), `groupId` sharing across route groups, `429`/`403` ban response with `Retry-After`, and `onBan` / `onStrike` hooks. Zero runtime dependencies.
 - `botGuard()` bot / User-Agent management at `@daloyjs/core/bot-guard`: the in-app equivalent of Nginx/WAF bot rules. Blocks empty/missing `User-Agent` (default on) and known-abusive `User-Agent` strings / `RegExp`s, and **verifies declared crawlers** — a request claiming to be Googlebot/Bingbot is confirmed via reverse-DNS + forward-confirm (the method Google and Bing document), so a spoofed `User-Agent` can't impersonate a trusted crawler. Ships `GOOGLEBOT` / `BINGBOT` / `WELL_KNOWN_BOTS` presets and accepts custom `VerifiedBotRule`s. Allowlist-first (`allowUserAgents` bypasses every rule), secure-by-default (`verifiedBots` refuses to construct without an IP source; unverifiable crawlers blocked unless `blockUnverifiableBots: false`), subdomain-boundary-safe domain matching, per-IP verification cache to keep DNS off the hot path, `mode: "log"` monitor mode, `onBlock` callback, and a pluggable `BotResolver` (default lazy `node:dns/promises`). Zero runtime dependencies.

package/dist/adapters/cloudflare.d.ts

@@ -18,7 +18,11 @@
 import type { App } from "../app.js";
 /** Module shape expected by the Cloudflare Workers runtime as `export default`. */
 export interface ExportedFetchHandler<Env = unknown> {
-    /** Worker entry point: forwards the request to {@link App.fetch}. `env`/`ctx` are accepted but unused by the adapter. */
+    /**
+     * Worker entry point: forwards the request to {@link App.fetch}. After the
+     * response is produced, `ctx.waitUntil` is used to flush OTLP telemetry so
+     * the isolate stays alive long enough for the export POST to finish.
+     */
     fetch: (request: Request, env?: Env, ctx?: ExecutionContextLike) => Promise<Response>;
 }
 interface ExecutionContextLike {
@@ -28,6 +32,9 @@ interface ExecutionContextLike {
 /**
  * Wrap an {@link App} in the `{ fetch }` object expected by Cloudflare Workers and other web-standard hosts.
  *
+ * After each request, OTLP telemetry is flushed via `ctx.waitUntil` so the
+ * isolate stays alive long enough for the export POST to finish.
+ *
  * @param app - The DaloyJS {@link App} that serves each incoming request.
  * @returns An {@link ExportedFetchHandler} suitable as the module's `export default`.
  */

package/dist/adapters/cloudflare.js

@@ -1,11 +1,25 @@
 /**
  * Wrap an {@link App} in the `{ fetch }` object expected by Cloudflare Workers and other web-standard hosts.
  *
+ * After each request, OTLP telemetry is flushed via `ctx.waitUntil` so the
+ * isolate stays alive long enough for the export POST to finish.
+ *
  * @param app - The DaloyJS {@link App} that serves each incoming request.
  * @returns An {@link ExportedFetchHandler} suitable as the module's `export default`.
  */
 export function toFetchHandler(app) {
     return {
-        fetch: (req) => app.fetch(req),
+        async fetch(req, _env, ctx) {
+            const res = await app.fetch(req);
+            const telemetry = app.telemetry;
+            if (telemetry !== undefined) {
+                const pending = telemetry.flush();
+                if (ctx?.waitUntil !== undefined)
+                    ctx.waitUntil(pending);
+                else
+                    void pending;
+            }
+            return res;
+        },
     };
 }

package/dist/adapters/lambda.js

@@ -20,6 +20,9 @@ export function toLambdaHandler(app) {
             return responseToLambda(badRequestResponse(), isV2Event(event));
         }
         const response = await app.fetch(request);
+        // Lambda freezes when the handler resolves; await the export so OTLP
+        // actually leaves the isolate. `flush()` never rejects.
+        await app.telemetry?.flush();
         return responseToLambda(response, isV2Event(event));
     };
 }
@@ -49,6 +52,7 @@ export function toLambdaStreamHandler(app) {
             return;
         }
         await streamLambdaResponse(await app.fetch(request), rawStream, runtime);
+        await app.telemetry?.flush();
     });
 }
 function eventToRequest(event) {
@@ -75,13 +79,17 @@ function eventToRequest(event) {
         : (event.path ?? event.requestContext?.path ?? "/");
     const host = headers.get("host") ?? event.requestContext?.domainName ?? "localhost";
     const proto = headers.get("x-forwarded-proto") ?? "https";
-    const rawQueryString = isV2Event(event) ? (event.rawQueryString ?? "") : queryStringForV1(event);
+    const rawQueryString = isV2Event(event)
+        ? (event.rawQueryString ?? "")
+        : queryStringForV1(event);
     const qs = rawQueryString ? `?${rawQueryString}` : "";
     const path = rawPath.startsWith("/") ? rawPath : `/${rawPath}`;
     const url = `${proto}://${host}${path}${qs}`;
     const init = { method, headers };
     if (method !== "GET" && method !== "HEAD" && event.body != null) {
-        init.body = event.isBase64Encoded ? base64ToBytes(event.body) : event.body;
+        init.body = event.isBase64Encoded
+            ? base64ToBytes(event.body)
+            : event.body;
     }
     const request = new Request(url, init);
     // Fulfil the conn-info contract with the caller address API Gateway saw
@@ -171,8 +179,7 @@ function badRequestResponse() {
     }, { status: 400, headers: { "content-type": "application/problem+json" } });
 }
 function lambdaStreamingRuntime() {
-    const runtime = globalThis
-        .awslambda;
+    const runtime = globalThis.awslambda;
     if (!runtime ||
         typeof runtime.streamifyResponse !== "function" ||
         typeof runtime.HttpResponseStream?.from !== "function") {
@@ -182,7 +189,10 @@ function lambdaStreamingRuntime() {
 }
 async function streamLambdaResponse(response, rawStream, runtime) {
     const { headers, cookies } = responseHeaders(response);
-    const metadata = { statusCode: response.status, headers };
+    const metadata = {
+        statusCode: response.status,
+        headers,
+    };
     if (cookies.length)
         metadata.multiValueHeaders = { "set-cookie": cookies };
     const responseStream = runtime.HttpResponseStream.from(rawStream, metadata);

package/dist/adapters/vercel.d.ts

@@ -32,6 +32,11 @@ export type RouteHandlers = Record<(typeof NEXT_METHODS)[number], WebHandler>;
 /**
  * Wrap an {@link App} as a single web-standard fetch handler.
  *
+ * After the response is produced, any OTLP telemetry is flushed. When the
+ * runtime exposes `globalThis.waitUntil` (Vercel Fluid / Edge), that is used
+ * so the export can finish after the response is sent; otherwise the flush
+ * is started fire-and-forget.
+ *
  * @param app - The DaloyJS {@link App} that serves each incoming request.
  * @returns A {@link WebHandler} delegating to {@link App.fetch}.
  */

package/dist/adapters/vercel.js

@@ -1,12 +1,37 @@
-const NEXT_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"];
+const NEXT_METHODS = [
+    "GET",
+    "POST",
+    "PUT",
+    "PATCH",
+    "DELETE",
+    "OPTIONS",
+    "HEAD",
+];
 /**
  * Wrap an {@link App} as a single web-standard fetch handler.
  *
+ * After the response is produced, any OTLP telemetry is flushed. When the
+ * runtime exposes `globalThis.waitUntil` (Vercel Fluid / Edge), that is used
+ * so the export can finish after the response is sent; otherwise the flush
+ * is started fire-and-forget.
+ *
  * @param app - The DaloyJS {@link App} that serves each incoming request.
  * @returns A {@link WebHandler} delegating to {@link App.fetch}.
  */
 export function toWebHandler(app) {
-    return (req) => app.fetch(req);
+    return async (req) => {
+        const res = await app.fetch(req);
+        const telemetry = app.telemetry;
+        if (telemetry !== undefined) {
+            const pending = telemetry.flush();
+            const waitUntil = globalThis.waitUntil;
+            if (typeof waitUntil === "function")
+                waitUntil(pending);
+            else
+                void pending;
+        }
+        return res;
+    };
 }
 /**
  * Build the default `{ fetch }` export expected by Vercel Node.js Functions

package/dist/app.d.ts

@@ -9,6 +9,7 @@ import { type SecureHeadersOptions } from "./middleware.js";
 import { type LoadSheddingOptions } from "./load-shedding.js";
 import { MetricsRegistry, type HttpMetricsOptions } from "./metrics.js";
 import { Scheduler, type TaskDefinition, type TaskHandler } from "./scheduler.js";
+import { type JobHandler, type JobQueue, type JobQueueOptions, type JobStore, type JobWorker, type JobWorkerOptions } from "./jobs.js";
 import { type BehindProxyConfig } from "./conn-info.js";
 /** @internal Test-only helper to reset the latch between tests. */
 export declare function _resetCrashHandlersForTests(): void;
@@ -81,8 +82,9 @@ export interface AppOptions {
      * per the OTel HTTP semantic conventions, pushed to the collector named by
      * the standard `OTEL_EXPORTER_OTLP_*` environment variables. A silent no-op
      * when no endpoint is configured, so it is safe to keep enabled in
-     * development. Export failures never affect request serving. See
-     * {@link TelemetryOptions}.
+     * development. Export failures never affect request serving. Isolate
+     * runtimes must go through `toFetchHandler` / `toLambdaHandler` so a
+     * per-request flush actually runs. See {@link TelemetryOptions}.
      *
      * @since 1.2.0
      */
@@ -656,15 +658,15 @@ export interface MetricsRouteOptions {
      */
     registry?: MetricsRegistry;
     /**
-     * Resolve the low-cardinality `route` label. Strongly recommended: return
-     * the route template (e.g. `/books/:id`) instead of the raw path.
-     * Forwarded to {@link httpMetrics}.
+     * Resolve the low-cardinality `route` label. When omitted, the matched
+     * route template (`ctx.routePath`, e.g. `/books/:id`) is used. Forwarded
+     * to {@link httpMetrics}.
      */
     route?: HttpMetricsOptions["route"];
     /**
-     * Maximum distinct values for the default pathname-derived `route` label
-     * before further values collapse to `"<other>"`. Forwarded to
-     * {@link httpMetrics}. Default `100`.
+     * Maximum distinct values for the pathname fallback `route` label (no
+     * template on the context). Forwarded to {@link httpMetrics}. Default
+     * `100`.
      */
     maxRouteCardinality?: number;
     /** Latency histogram buckets, in seconds. Forwarded to {@link httpMetrics}. */
@@ -1000,6 +1002,13 @@ export declare class App<Routes extends readonly RouteDefinition<any, any, any,
      * is tied to graceful shutdown.
      */
     private scheduler?;
+    /**
+     * Job queue / worker attached by {@link App.useJobs}. Both stay `undefined`
+     * unless the app opts in — serverless isolates must never start a poll
+     * loop implicitly.
+     */
+    private jobQueue?;
+    private jobWorkerRef?;
     /** Idle-connection close hooks (adapter-registered, sync). */
     private idleConnectionCloseHooks;
     private pluginInstalledListeners;
@@ -1443,8 +1452,13 @@ export declare class App<Routes extends readonly RouteDefinition<any, any, any,
      *
      * Call this **before** registering the routes you want measured — like any
      * `app.use(...)` middleware, the instrumentation only wraps routes added
-     * afterwards. Pass `opts.registry` to register custom application metrics
-     * that are rendered alongside the built-in HTTP series.
+     * afterwards. Calling it after routes already exist logs a
+     * `metrics.late_install` warning listing the uninstrumented paths.
+     * Pass `opts.registry` to register custom application metrics that are
+     * rendered alongside the built-in HTTP series. Default series names are
+     * unprefixed (`http_requests_total`, `process_resident_memory_bytes`);
+     * construct the registry with `prefix: "daloy_"` if you want the old
+     * names.
      *
      * @param opts - Path, auth, rate-limit, registry, and label configuration.
      * @returns `this` for chaining.
@@ -1486,6 +1500,118 @@ export declare class App<Routes extends readonly RouteDefinition<any, any, any,
      * is owned by the app.
      */
     get scheduledTasks(): Scheduler | undefined;
+    /**
+     * Attach a queue-agnostic background-job queue (and optionally a worker)
+     * to this app. Opt-in by design: nothing in `new App()` starts a poll
+     * loop, so serverless isolates that only ever *enqueue* never pay for (or
+     * accidentally run) a worker.
+     *
+     * The queue answers *&ldquo;run this work somewhere, eventually&rdquo;* —
+     * durable, retried, at-least-once units of `{ name, payload }` that
+     * outlive the HTTP request and, with a durable {@link JobStore} adapter,
+     * the process itself. This is not a workflow engine: there is no replay,
+     * no durable function, no `await sleep("7 days")`.
+     *
+     * - `startWorker: true` creates a {@link JobWorker} over the same store,
+     *   starts it, and registers an `onClose` hook so in-flight jobs are
+     *   drained (then aborted past the grace period) on graceful shutdown.
+     *   Use it on long-lived Node/Bun/Deno processes only — never on Lambda /
+     *   Cloudflare Workers isolates.
+     * - {@link MemoryJobStore} under production config logs a high-severity
+     *   warning (it is process-local and loses every job on restart); pass
+     *   `strictProduction: true` to refuse to boot instead.
+     *
+     * @example
+     * ```ts
+     * app.useJobs({
+     *   store: new MemoryJobStore(), // production: your Redis/Postgres JobStore
+     *   handlers: {
+     *     "email.welcome": async ({ job, signal }) => {
+     *       await sendEmail(job.payload, { signal });
+     *     },
+     *   },
+     *   startWorker: true,
+     * });
+     *
+     * app.post("/users", contract, async (ctx) => {
+     *   const user = await db.insertUser(ctx.body);
+     *   await app.jobs!.enqueue({
+     *     name: "email.welcome",
+     *     payload: { userId: user.id },
+     *     idempotencyKey: jobIdempotencyKey({ tenant: ctx.state.tenant, name: "email.welcome", key: user.id }),
+     *   });
+     *   return { status: 201 as const, body: user };
+     * });
+     * ```
+     *
+     * @param opts - Store, optional handlers, worker and queue tuning.
+     * @returns This `App` instance for chaining.
+     * @throws {@link JobConfigError} when jobs are already configured, when
+     *   `startWorker` lacks handlers, or when `strictProduction` rejects a
+     *   {@link MemoryJobStore} under production config.
+     * @since 1.3.0
+     */
+    useJobs(opts: {
+        store: JobStore;
+        handlers?: Record<string, JobHandler<any>>;
+        startWorker?: boolean;
+        worker?: Omit<JobWorkerOptions, "queue" | "handlers">;
+        queue?: Omit<JobQueueOptions, "store">;
+        strictProduction?: boolean;
+    }): this;
+    /**
+     * The {@link JobQueue} attached by {@link App.useJobs}, or `undefined`
+     * when jobs are not configured. Route handlers enqueue through this;
+     * delivery is at-least-once, so handlers must be idempotent.
+     *
+     * @since 1.3.0
+     */
+    get jobs(): JobQueue | undefined;
+    /**
+     * The {@link JobWorker} created by {@link App.useJobs} with
+     * `startWorker: true`, or `undefined`. Exposed for inspection
+     * (`getState()`) and tests (`runOnce()`); the lifecycle is owned by the app.
+     *
+     * @since 1.3.0
+     */
+    get jobWorker(): JobWorker | undefined;
+    /**
+     * Register a cron task whose tick enqueues a job instead of running the
+     * side effect in-process. This is the production posture for scheduled
+     * work with global side effects (nightly reconciliation, invoice runs):
+     * every replica may tick, but the deterministic idempotency key
+     * `cron:{taskName}:{floor(scheduledFor / tickGranularity)}` collapses the
+     * duplicate enqueues into one job, and exactly one worker claims it.
+     *
+     * `tickGranularity` is the task's `intervalMs` for interval schedules and
+     * one minute for cron expressions (the finest cadence a cron expression
+     * can fire), so two replicas ticking the same slot always derive the same
+     * key. Use plain {@link App.cron} for process-local maintenance (cache
+     * sweeps that must happen in *this* process); use `cronEnqueue` for work
+     * that must happen once, cluster-wide, and survive a restart.
+     *
+     * @example
+     * ```ts
+     * app.cronEnqueue(
+     *   { name: "nightly-reconcile", cron: "0 2 * * *" },
+     *   { name: "ops.reconcile", payload: {} },
+     * );
+     * ```
+     *
+     * @param def - The task definition (schedule), same shape as {@link App.cron}.
+     * @param job - The job to enqueue on each tick. `payload` defaults to
+     *   `{ scheduledFor: <ISO time of the tick> }`.
+     * @returns This `App` instance for chaining.
+     * @throws {@link JobConfigError} (`store_required`) when called before
+     *   {@link App.useJobs} — fail fast at registration, not at the first tick.
+     * @since 1.3.0
+     */
+    cronEnqueue(def: TaskDefinition, job: {
+        name: string;
+        payload?: unknown;
+        queue?: string;
+        priority?: number;
+    }): this;
     private registerHealthRoute;
     /**
      * Register a built-in receiver for CSP / Reporting API