@plumbus/core 0.7.0 → 0.8.0-beta.0

package/dist/api/idempotency.js

@@ -0,0 +1,176 @@
+/** Thrown when an in-flight idempotency claim is aborted (e.g. the first request failed). */
+export class IdempotencyAbortedError extends Error {
+    constructor() {
+        super('Idempotency claim aborted');
+        this.name = 'IdempotencyAbortedError';
+    }
+}
+const TTL_MULTIPLIERS = {
+    s: 1_000,
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+};
+/** Parse manifest idempotency TTL strings such as `24h` or `30m` into milliseconds. */
+export function parseIdempotencyTtl(ttl) {
+    const match = /^(\d+)([smhd])$/.exec(ttl.trim());
+    if (match === null) {
+        return undefined;
+    }
+    const value = Number(match[1]);
+    const unit = match[2];
+    if (unit === undefined) {
+        return undefined;
+    }
+    const multiplier = TTL_MULTIPLIERS[unit];
+    if (multiplier === undefined) {
+        return undefined;
+    }
+    return value * multiplier;
+}
+export function buildIdempotencyStoreKey(operationId, principal, idempotencyKey) {
+    const tenantPart = principal.tenantId ?? '';
+    const userPart = principal.userId ?? '';
+    return `${operationId}:${tenantPart}:${userPart}:${idempotencyKey}`;
+}
+export function principalsMatch(a, b) {
+    return a.userId === b.userId && a.tenantId === b.tenantId;
+}
+/** True when neither userId nor tenantId is set (anonymous `::` principal). */
+export function isAnonymousIdempotencyPrincipal(principal) {
+    return principal.userId === undefined && principal.tenantId === undefined;
+}
+/**
+ * How deep a payload may nest before fingerprinting refuses it.
+ *
+ * `canonicalize` recurses once per level, and a body that nests tens of thousands of levels
+ * (JSON.parse accepts it) took the whole request handler down with a `RangeError` — an
+ * unhandled 500 from a tiny payload. No real input comes close to this depth; a payload past
+ * it is refused as malformed rather than hashed.
+ */
+export const MAX_PAYLOAD_DEPTH = 64;
+/** Thrown by {@link hashPayload} when a payload nests deeper than {@link MAX_PAYLOAD_DEPTH}. */
+export class PayloadTooDeepError extends Error {
+    constructor() {
+        super(`Payload nests deeper than ${MAX_PAYLOAD_DEPTH} levels`);
+        this.name = 'PayloadTooDeepError';
+    }
+}
+function canonicalize(value, depth) {
+    if (value === null || typeof value !== 'object') {
+        return value;
+    }
+    if (depth >= MAX_PAYLOAD_DEPTH) {
+        throw new PayloadTooDeepError();
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => canonicalize(item, depth + 1));
+    }
+    const obj = value;
+    const sorted = Object.keys(obj).sort();
+    const result = {};
+    for (const key of sorted) {
+        result[key] = canonicalize(obj[key], depth + 1);
+    }
+    return result;
+}
+/**
+ * Stable JSON serialization for idempotency payload hashing (sorted object keys).
+ *
+ * Throws {@link PayloadTooDeepError} for a payload nested past {@link MAX_PAYLOAD_DEPTH}; a
+ * route answers that as a `validation` refusal, never as an unhandled error.
+ */
+export function hashPayload(payload) {
+    return JSON.stringify(canonicalize(payload, 0));
+}
+function isExpired(record) {
+    return record.expiresAt !== undefined && Date.now() > record.expiresAt;
+}
+function replayOrConflict(record, payloadHash, principal) {
+    if (!principalsMatch(record.principal, principal)) {
+        return { status: 'conflict', reason: 'principal' };
+    }
+    if (record.payloadHash !== payloadHash) {
+        return { status: 'conflict', reason: 'payload' };
+    }
+    return { status: 'replay', record };
+}
+function createInFlightEntry(payloadHash, principal) {
+    let resolve = () => { };
+    let reject = () => { };
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    void promise.catch(() => {
+        /* absorb early abort before a route handler attaches its own catch */
+    });
+    return { payloadHash, principal, promise, resolve, reject };
+}
+function pruneExpiredEntries(store) {
+    const now = Date.now();
+    for (const [key, entry] of store) {
+        if ('result' in entry && entry.expiresAt !== undefined && now > entry.expiresAt) {
+            store.delete(key);
+        }
+    }
+}
+/**
+ * Dev-oriented in-memory idempotency store. Entries without TTL are never evicted;
+ * when `ttlMs` is supplied on complete, expired records are ignored on subsequent claims.
+ */
+export function createInMemoryIdempotencyStore() {
+    const store = new Map();
+    return {
+        async claim(key, payloadHash, principal, options) {
+            if (options?.ttlMs !== undefined) {
+                pruneExpiredEntries(store);
+            }
+            const existing = store.get(key);
+            if (existing === undefined) {
+                store.set(key, createInFlightEntry(payloadHash, principal));
+                return { status: 'new' };
+            }
+            if ('result' in existing) {
+                if (isExpired(existing)) {
+                    store.delete(key);
+                    store.set(key, createInFlightEntry(payloadHash, principal));
+                    return { status: 'new' };
+                }
+                return replayOrConflict(existing, payloadHash, principal);
+            }
+            if (!principalsMatch(existing.principal, principal)) {
+                return { status: 'conflict', reason: 'principal' };
+            }
+            if (existing.payloadHash !== payloadHash) {
+                return { status: 'conflict', reason: 'payload' };
+            }
+            return { status: 'in-flight', wait: existing.promise };
+        },
+        async complete(key, result, options) {
+            const existing = store.get(key);
+            if (existing === undefined || 'result' in existing) {
+                return;
+            }
+            const record = {
+                payloadHash: existing.payloadHash,
+                result,
+                principal: existing.principal,
+                expiresAt: options?.ttlMs !== undefined ? Date.now() + options.ttlMs : undefined,
+            };
+            store.set(key, record);
+            existing.resolve(record);
+            if (options?.ttlMs !== undefined) {
+                pruneExpiredEntries(store);
+            }
+        },
+        async abort(key) {
+            const existing = store.get(key);
+            if (existing !== undefined && !('result' in existing)) {
+                existing.reject(new IdempotencyAbortedError());
+                store.delete(key);
+            }
+        },
+    };
+}
+//# sourceMappingURL=idempotency.js.map

package/dist/api/idempotency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.js","sourceRoot":"","sources":["../../src/api/idempotency.ts"],"names":[],"mappings":"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"}

package/dist/api/index.d.ts

@@ -1,6 +1,8 @@
-export { isApiExposed } from './exposure.js';
+export { capabilityHttpMethod, isApiExposed } from './exposure.js';
 export { authenticationFailureToHttp, buildAuthenticationRequest, } from './authentication-http.js';
 export { parseCookieHeader } from './cookies.js';
 export { LOCALE_COOKIE_NAME, registerAllRoutes, registerCapabilityRoute, registerStreamingRoute, resolveRequestLocale, } from './route-generator.js';
 export type { DependencyOptions, ResolveRequestLocaleOptions, RouteGeneratorConfig, } from './route-generator.js';
+export { buildIdempotencyStoreKey, createInMemoryIdempotencyStore, hashPayload, IdempotencyAbortedError, isAnonymousIdempotencyPrincipal, MAX_PAYLOAD_DEPTH, parseIdempotencyTtl, PayloadTooDeepError, principalsMatch, } from './idempotency.js';
+export type { IdempotencyClaimResult, IdempotencyPrincipal, IdempotencyRecord, IdempotencyStore, IdempotencyStoreOptions, } from './idempotency.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/api/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EACL,2BAA2B,EAC3B,0BAA0B,GAC3B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,uBAAuB,EACvB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,iBAAiB,EACjB,2BAA2B,EAC3B,oBAAoB,GACrB,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,EACL,2BAA2B,EAC3B,0BAA0B,GAC3B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,uBAAuB,EACvB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,iBAAiB,EACjB,2BAA2B,EAC3B,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,wBAAwB,EACxB,8BAA8B,EAC9B,WAAW,EACX,uBAAuB,EACvB,+BAA+B,EAC/B,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,kBAAkB,CAAC"}

package/dist/api/index.js

@@ -1,10 +1,12 @@
 // ── API Module ──
 // HTTP route generation: registers Fastify routes for capabilities.
-// Maps capability kind to HTTP method (query→GET, action/job→POST).
+// Maps a capability to its HTTP method: the declared `api.method` where there is one,
+// otherwise the kind's default (query→GET, action/job→POST).
 //
 // Key exports: registerAllRoutes, registerCapabilityRoute, isApiExposed
-export { isApiExposed } from './exposure.js';
+export { capabilityHttpMethod, isApiExposed } from './exposure.js';
 export { authenticationFailureToHttp, buildAuthenticationRequest, } from './authentication-http.js';
 export { parseCookieHeader } from './cookies.js';
 export { LOCALE_COOKIE_NAME, registerAllRoutes, registerCapabilityRoute, registerStreamingRoute, resolveRequestLocale, } from './route-generator.js';
+export { buildIdempotencyStoreKey, createInMemoryIdempotencyStore, hashPayload, IdempotencyAbortedError, isAnonymousIdempotencyPrincipal, MAX_PAYLOAD_DEPTH, parseIdempotencyTtl, PayloadTooDeepError, principalsMatch, } from './idempotency.js';
 //# sourceMappingURL=index.js.map

package/dist/api/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA,mBAAmB;AACnB,oEAAoE;AACpE,oEAAoE;AACpE,EAAE;AACF,wEAAwE;AAExE,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EACL,2BAA2B,EAC3B,0BAA0B,GAC3B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,uBAAuB,EACvB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA,mBAAmB;AACnB,oEAAoE;AACpE,sFAAsF;AACtF,6DAA6D;AAC7D,EAAE;AACF,wEAAwE;AAExE,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,EACL,2BAA2B,EAC3B,0BAA0B,GAC3B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,uBAAuB,EACvB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAM9B,OAAO,EACL,wBAAwB,EACxB,8BAA8B,EAC9B,WAAW,EACX,uBAAuB,EACvB,+BAA+B,EAC/B,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,GAChB,MAAM,kBAAkB,CAAC"}

package/dist/api/route-generator.d.ts

@@ -3,6 +3,7 @@ import type { FastifyInstance } from 'fastify';
 import type { AuthAdapter } from '../auth/adapter.js';
 import type { RequestAuthenticator } from '../auth/http-authentication.js';
 import type { EventQueue } from '../events/queue.js';
+import { type IdempotencyStore } from './idempotency.js';
 import type { ContextDependencies } from '../execution/context-factory.js';
 import type { CapabilityContract } from '../types/capability.js';
 import type { ExecutionContext } from '../types/context.js';
@@ -12,8 +13,29 @@ export interface DependencyOptions {
     /** Resolved locale for this request (from cookie / Accept-Language) */
     locale?: string;
 }
+/**
+ * A request's dependencies together with the database they were wired against.
+ *
+ * The generator needs the database as well as the dependencies because two
+ * things happen outside the execution context — queue dispatch for `kind: 'job'`
+ * capabilities and the `onCapabilityError` hook — and both must address the same
+ * database the capability itself read and wrote. Returning them together makes
+ * that impossible to get wrong.
+ */
+export interface ResolvedRequestDependencies {
+    /** Dependencies for this request. */
+    dependencies: ContextDependencies;
+    /** The database `dependencies` were wired against. */
+    db: PostgresJsDatabase;
+}
 export interface RouteGeneratorConfig {
-    /** Live Drizzle database connection used by the server. */
+    /**
+     * Live Drizzle database connection used by the server.
+     *
+     * This is the database every request uses unless `resolveDependencies` is
+     * supplied, in which case it is only the fallback for requests that never
+     * reach dependency resolution.
+     */
     db: PostgresJsDatabase;
     /** Auth adapter for extracting identity from requests */
     authAdapter: AuthAdapter;
@@ -21,8 +43,35 @@ export interface RouteGeneratorConfig {
     requestAuthenticator?: RequestAuthenticator;
     /** Factory to build base context dependencies for each request */
     createDependencies: (auth: NonNullable<Awaited<ReturnType<AuthAdapter['authenticate']>>>, options?: DependencyOptions) => ContextDependencies;
+    /**
+     * Optional async alternative to `createDependencies`, used for every request
+     * when present and ignored when absent.
+     *
+     * It exists for deployments that choose the request's database per request
+     * rather than per boot — a tenant's data plane resolved from its auth context.
+     * Leaving it unset keeps the synchronous `createDependencies` path exactly as
+     * it was, with no additional `await` between authentication and execution.
+     *
+     * Throwing rejects the request: the thrown value is mapped through the normal
+     * error-to-HTTP rules (a `PlumbusError` keeps its code and status, anything
+     * else becomes a generic 500), so a resolver that refuses an unknown or absent
+     * tenant fails closed instead of falling through to another tenant's data.
+     */
+    resolveDependencies?: (auth: NonNullable<Awaited<ReturnType<AuthAdapter['authenticate']>>>, options?: DependencyOptions) => Promise<ResolvedRequestDependencies>;
     /** Optional queue for dispatching async job capabilities */
     jobQueue?: EventQueue;
+    /**
+     * Where `api.idempotency` claims are kept for the routes this config registers.
+     *
+     * A capability that declares `api: { idempotency: { required: true, header } }` is served
+     * only with that header present; the same key with the same payload replays the stored
+     * answer, the same key with a different payload or principal is refused with a conflict,
+     * and a failed execution releases the key so the caller may retry. Left unset, every route
+     * registered with this config shares one in-memory store — correct within a process and
+     * lost on restart; a deployment that needs replay protection across instances supplies a
+     * shared store here.
+     */
+    idempotencyStore?: IdempotencyStore;
     /** Default locale when request headers do not resolve one */
     defaultLocale?: string;
     /** Locales supported by registered translation definitions */
@@ -41,11 +90,6 @@ export interface RouteGeneratorConfig {
         db?: PostgresJsDatabase;
     }) => void | Promise<void>;
 }
-/**
- * Register Fastify routes for a single capability.
- * HTTP method is derived from capability kind:
- *   query → GET, action → POST, job → POST (async), eventHandler → skipped
- */
 export declare function registerCapabilityRoute(app: FastifyInstance, capability: CapabilityContract, config: RouteGeneratorConfig): void;
 /**
  * Register routes for multiple capabilities at once.

package/dist/api/route-generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route-generator.d.ts","sourceRoot":"","sources":["../../src/api/route-generator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"route-generator.d.ts","sourceRoot":"","sources":["../../src/api/route-generator.ts"],"names":[],"mappings":"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"}

package/dist/api/route-generator.js

@@ -1,22 +1,37 @@
 import { authenticationFailureToHttp, buildAuthenticationRequest } from './authentication-http.js';
-import { errorToHttpResponse, errorToSsePayload, unknownErrorToSsePayload, } from '../errors/http.js';
+import { errorToHttpResponse, errorToSsePayload, GENERIC_INTERNAL_MESSAGE, unknownErrorToSsePayload, } from '../errors/http.js';
+import { capabilityHttpMethod } from './exposure.js';
+import { isPlumbusError } from '../errors/index.js';
 import { logHookError } from '../errors/hook-log.js';
 import { JobExecutionSource } from '../jobs/schema.js';
 import { dispatchQueuedJob } from '../jobs/dispatch.js';
 import { evaluateAccess } from '../execution/authorization.js';
 import { getCanonicalCapabilityName } from '../execution/canonical-name.js';
-import { executeCapability } from '../execution/capability-executor.js';
+import { authorizeCapability, executeCapability } from '../execution/capability-executor.js';
+import { buildIdempotencyStoreKey, createInMemoryIdempotencyStore, hashPayload, PayloadTooDeepError, IdempotencyAbortedError, isAnonymousIdempotencyPrincipal, parseIdempotencyTtl, } from './idempotency.js';
 import { createExecutionContext } from '../execution/context-factory.js';
 /**
  * Register Fastify routes for a single capability.
  * HTTP method is derived from capability kind:
  *   query → GET, action → POST, job → POST (async), eventHandler → skipped
  */
+/** One in-memory store per route configuration, for deployments that supplied none. */
+const defaultIdempotencyStores = new WeakMap();
+function idempotencyStoreOf(config) {
+    if (config.idempotencyStore)
+        return config.idempotencyStore;
+    let store = defaultIdempotencyStores.get(config);
+    if (!store) {
+        store = createInMemoryIdempotencyStore();
+        defaultIdempotencyStores.set(config, store);
+    }
+    return store;
+}
 export function registerCapabilityRoute(app, capability, config) {
     // Event handlers are internal-only, no HTTP route
     if (capability.kind === 'eventHandler')
         return;
-    const method = capability.kind === 'query' ? 'GET' : 'POST';
+    const method = capabilityHttpMethod(capability);
     const path = `/api/${capability.domain}/${toKebabCase(capability.name)}`;
     const handler = async (request, reply) => {
         const requestId = resolveRequestCorrelationId(request.headers);
@@ -78,7 +93,28 @@ export function registerCapabilityRoute(app, capability, config) {
             defaultLocale: config.defaultLocale ?? 'en',
             supportedLocales: config.supportedLocales ?? [config.defaultLocale ?? 'en'],
         });
-        const deps = config.createDependencies(authContext, { bypassTenantScope, locale });
+        // The synchronous factory stays the only path when no resolver is supplied:
+        // nothing extra is awaited between authentication and execution.
+        let deps;
+        let requestDb = config.db;
+        if (config.resolveDependencies) {
+            try {
+                const resolved = await config.resolveDependencies(authContext, {
+                    bypassTenantScope,
+                    locale,
+                });
+                deps = resolved.dependencies;
+                requestDb = resolved.db;
+            }
+            catch (err) {
+                const failure = dependencyResolutionToHttp(err, requestId);
+                reply.status(failure.statusCode).send(failure.body);
+                return;
+            }
+        }
+        else {
+            deps = config.createDependencies(authContext, { bypassTenantScope, locale });
+        }
         deps.correlationId = resolveRequestCorrelationId(request.headers);
         deps.request = {
             sourceIp: request.ip,
@@ -105,7 +141,7 @@ export function registerCapabilityRoute(app, capability, config) {
                 return reply.status(statusCode).send(body);
             }
             const jobId = await dispatchQueuedJob({
-                db: config.db,
+                db: requestDb,
                 jobQueue: config.jobQueue,
                 capability,
                 input: parsed.data,
@@ -115,6 +151,158 @@ export function registerCapabilityRoute(app, capability, config) {
             reply.status(202).send({ data: { jobId, status: 'accepted' } });
             return;
         }
+        // 4b. Declared idempotency (`api.idempotency.required`): the key is demanded, and the
+        // outcome of one execution is what every later request with that key receives.
+        const idempotency = capability.api?.idempotency;
+        // A caller the capability refuses is answered by the executor as always (403, audited)
+        // before any header is looked at, so authorization never leaks behind a validation answer.
+        const idempotencyApplies = idempotency?.required === true &&
+            method !== 'GET' &&
+            evaluateAccess(capability.access, ctx.auth).allowed;
+        if (idempotencyApplies && idempotency) {
+            const headerName = (idempotency.header ?? 'Idempotency-Key').toLowerCase();
+            const rawKey = request.headers[headerName];
+            const idempotencyKey = Array.isArray(rawKey) ? rawKey[0] : rawKey;
+            if (typeof idempotencyKey !== 'string' || idempotencyKey.length === 0) {
+                const err = ctx.errors.validation(`Missing required header: ${idempotency.header ?? 'Idempotency-Key'}`, { capability: canonicalName, reason: 'idempotency-key-required' });
+                const { statusCode, body } = errorToHttpResponse(err);
+                reply.status(statusCode).send(body);
+                return;
+            }
+            // Only a request that would execute claims a key: invalid input is answered by the
+            // executor as always, and leaves nothing behind for a retry to hit.
+            const parsed = capability.input.safeParse(input);
+            const principal = {
+                userId: ctx.auth.userId,
+                tenantId: ctx.auth.tenantId,
+            };
+            if (parsed.success && !isAnonymousIdempotencyPrincipal(principal)) {
+                const store = idempotencyStoreOf(config);
+                const operationId = capability.api?.operationId ?? canonicalName;
+                const storeKey = buildIdempotencyStoreKey(operationId, principal, idempotencyKey);
+                const authorityOf = (auth) => ({
+                    roles: [...auth.roles].sort(),
+                    scopes: [...auth.scopes].sort(),
+                });
+                // A role change can change the shape of a permitted result (e.g. staff vs student).
+                // Never reuse that result across different authority, even for the same person/input.
+                const authority = hashPayload(authorityOf(ctx.auth));
+                let payloadHash;
+                try {
+                    payloadHash = hashPayload({ input: parsed.data, authority });
+                }
+                catch (hashErr) {
+                    if (!(hashErr instanceof PayloadTooDeepError))
+                        throw hashErr;
+                    // A body nested past the fingerprint's depth cap is malformed input, answered like
+                    // any other validation failure — not an unhandled RangeError from the hasher.
+                    const err = ctx.errors.validation('Request body nests too deeply', {
+                        capability: canonicalName,
+                        reason: 'payload-too-deep',
+                    });
+                    const { statusCode, body } = errorToHttpResponse(err);
+                    reply.status(statusCode).send(body);
+                    return;
+                }
+                const ttlMs = idempotency.ttl !== undefined ? parseIdempotencyTtl(idempotency.ttl) : undefined;
+                const storeOptions = ttlMs !== undefined ? { ttlMs } : undefined;
+                // A cached result is still a disclosure. Refresh session/dependency authority, then
+                // run the capability's current resource checks without executing its handler again.
+                // In particular, the same check runs after an in-flight wait, not only before it.
+                const replay = async (result) => {
+                    try {
+                        const fresh = config.resolveDependencies
+                            ? (await config.resolveDependencies(authContext, { bypassTenantScope, locale }))
+                                .dependencies
+                            : config.createDependencies(authContext, { bypassTenantScope, locale });
+                        fresh.correlationId = deps.correlationId;
+                        fresh.request = deps.request;
+                        const current = createExecutionContext(fresh);
+                        if (current.auth.userId !== principal.userId ||
+                            current.auth.tenantId !== principal.tenantId) {
+                            throw current.errors.forbidden('Idempotency replay principal changed');
+                        }
+                        if (hashPayload(authorityOf(current.auth)) !== authority) {
+                            throw current.errors.forbidden('Idempotency replay authority changed');
+                        }
+                        const authorized = await authorizeCapability(capability, current, parsed.data);
+                        if (!authorized.success) {
+                            const failure = errorToHttpResponse(authorized.error);
+                            reply.status(failure.statusCode).send(failure.body);
+                            return;
+                        }
+                        reply.status(200).send({ data: result });
+                    }
+                    catch (error) {
+                        const failure = dependencyResolutionToHttp(error, requestId);
+                        reply.status(failure.statusCode).send(failure.body);
+                    }
+                };
+                let claim = await store.claim(storeKey, payloadHash, principal, storeOptions);
+                for (;;) {
+                    if (claim.status === 'replay') {
+                        await replay(claim.record.result);
+                        return;
+                    }
+                    if (claim.status === 'conflict') {
+                        const err = ctx.errors.conflict(claim.reason === 'principal'
+                            ? 'Idempotency key belongs to a different principal'
+                            : 'Idempotency key reused with different input', { capability: canonicalName, reason: 'idempotency-conflict', conflict: claim.reason });
+                        const { statusCode, body } = errorToHttpResponse(err);
+                        reply.status(statusCode).send(body);
+                        return;
+                    }
+                    if (claim.status === 'in-flight') {
+                        try {
+                            const record = await claim.wait;
+                            await replay(record.result);
+                            return;
+                        }
+                        catch (waitErr) {
+                            if (!(waitErr instanceof IdempotencyAbortedError))
+                                throw waitErr;
+                            claim = await store.claim(storeKey, payloadHash, principal, storeOptions);
+                            continue;
+                        }
+                    }
+                    break;
+                }
+                let claimed;
+                try {
+                    claimed = await executeCapability(capability, ctx, input);
+                }
+                catch (execErr) {
+                    await store.abort(storeKey);
+                    throw execErr;
+                }
+                if (claimed.success) {
+                    await store.complete(storeKey, claimed.data, storeOptions);
+                    reply.status(200).send({ data: claimed.data });
+                    return;
+                }
+                await store.abort(storeKey);
+                const httpError = errorToHttpResponse(claimed.error);
+                reply.status(httpError.statusCode).send(httpError.body);
+                if (config.onCapabilityError) {
+                    const failed = claimed.error;
+                    void (async () => config.onCapabilityError?.({
+                        capabilityName: capability.name,
+                        domain: capability.domain,
+                        errorCode: failed.code,
+                        errorMessage: failed.message,
+                        metadata: failed.metadata,
+                        userId: ctx.auth.userId,
+                        tenantId: ctx.auth.tenantId,
+                        sourceIp: request.ip,
+                        userAgent: request.headers['user-agent'],
+                        db: requestDb,
+                    }))().catch((hookErr) => {
+                        logHookError('onCapabilityError', hookErr);
+                    });
+                }
+                return;
+            }
+        }
         const result = await executeCapability(capability, ctx, input);
         if (result.success) {
             reply.status(200).send({ data: result.data });
@@ -135,18 +323,33 @@ export function registerCapabilityRoute(app, capability, config) {
                     tenantId: ctx.auth.tenantId,
                     sourceIp: request.ip,
                     userAgent: request.headers['user-agent'],
-                    db: config.db,
+                    db: requestDb,
                 }))().catch((hookErr) => {
                     logHookError('onCapabilityError', hookErr);
                 });
             }
         }
     };
-    if (method === 'GET') {
-        app.get(path, handler);
-    }
-    else {
-        app.post(path, handler);
+    /*
+     * Every method a capability may declare, not just the two the `kind` fallback produces. A
+     * declared `PATCH` that silently registered as `POST` is the same defect as a declared `POST`
+     * served as `GET`: the contract says one thing and the wire does another.
+     */
+    switch (method) {
+        case 'GET':
+            app.get(path, handler);
+            break;
+        case 'PATCH':
+            app.patch(path, handler);
+            break;
+        case 'PUT':
+            app.put(path, handler);
+            break;
+        case 'DELETE':
+            app.delete(path, handler);
+            break;
+        default:
+            app.post(path, handler);
     }
 }
 /**
@@ -226,7 +429,24 @@ export function registerStreamingRoute(app, capability, config, streamHandler) {
             defaultLocale: config.defaultLocale ?? 'en',
             supportedLocales: config.supportedLocales ?? [config.defaultLocale ?? 'en'],
         });
-        const deps = config.createDependencies(authContext, { bypassTenantScope, locale });
+        let deps;
+        if (config.resolveDependencies) {
+            try {
+                const resolved = await config.resolveDependencies(authContext, {
+                    bypassTenantScope,
+                    locale,
+                });
+                deps = resolved.dependencies;
+            }
+            catch (err) {
+                const failure = dependencyResolutionToHttp(err, requestId);
+                reply.status(failure.statusCode).send(failure.body);
+                return;
+            }
+        }
+        else {
+            deps = config.createDependencies(authContext, { bypassTenantScope, locale });
+        }
         deps.correlationId = resolveRequestCorrelationId(request.headers);
         deps.request = {
             sourceIp: request.ip,
@@ -280,6 +500,28 @@ export function registerStreamingRoute(app, capability, config, streamHandler) {
         reply.raw.end();
     });
 }
+/**
+ * Shape a failure from `resolveDependencies` into an HTTP response.
+ *
+ * A `PlumbusError` keeps its own code and status — a resolver that refuses an
+ * unknown tenant with `notFound`, or an untenanted request with `forbidden`,
+ * reaches the client as that. Anything else becomes a generic 500 so an
+ * infrastructure failure (a connection string, a routing table) is never echoed
+ * back to the caller. Streaming routes call this before any SSE header is
+ * written, so the refusal is a plain HTTP status there too.
+ */
+function dependencyResolutionToHttp(err, requestId) {
+    const mapped = isPlumbusError(err)
+        ? errorToHttpResponse(err)
+        : {
+            statusCode: 500,
+            body: { error: { code: 'internal', message: GENERIC_INTERNAL_MESSAGE } },
+        };
+    return {
+        statusCode: mapped.statusCode,
+        body: { error: { ...mapped.body.error, ...(requestId ? { requestId } : {}) } },
+    };
+}
 function resolveRequestCorrelationId(headers) {
     for (const key of ['x-correlation-id', 'x-request-id']) {
         const value = headers[key];