@cosmicdrift/kumiko-framework 0.328.0 → 0.329.0

package/dist/pipeline/append-event-core.js

@@ -0,0 +1,84 @@
+import { requestContext } from "../api/request-context.js";
+import { SYSTEM_EVENT_PREFIX } from "../crypto/system-event-pii.js";
+import { qnScope, toKebab } from "../engine/qualified-name.js";
+import { InternalError, validationErrorFromZod } from "../errors/index.js";
+import { isStreamArchived } from "../event-store/archive.js";
+import { ArchivedStreamError } from "../event-store/errors.js";
+import { append, getStreamVersion } from "../event-store/event-store.js";
+import { runProjectionsForEvent } from "./projections-runner.js";
+export async function appendDomainEventCore(deps, args) {
+    const isSystemEvent = args.type.startsWith(SYSTEM_EVENT_PREFIX);
+    const eventDef = deps.registry.getEvent(args.type);
+    if (!eventDef && !isSystemEvent) {
+        throw new InternalError({
+            message: `${deps.callSiteLabel}("${args.type}") — event not registered. Call r.defineEvent(shortName, schema) in a feature; appendEvent expects the qualified name returned by defineEvent (e.g. "<feature>:event:<short>").`,
+        });
+    }
+    // Cross-feature ownership: features don't get to emit each other's events.
+    // Silent cross-feature writes would make event-store semantics fragile —
+    // a rename or schema-evolution in feature A could break an unrelated
+    // handler in feature B. The contract is: if you want feature A's state to
+    // react to feature B, wire an r.multiStreamProjection in A against B's
+    // events and let A emit its OWN follow-up on A's stream.
+    //
+    // Feature names are registered case-preserving (pubsubOrders) but qualified
+    // into kebab-case for the event/handler names (pubsub-orders:event:…) — so
+    // we compare the kebab form on both sides.
+    if (deps.callerFeature && !isSystemEvent) {
+        const owner = qnScope(args.type);
+        const callerKebab = toKebab(deps.callerFeature);
+        if (owner && owner !== callerKebab) {
+            throw new InternalError({
+                message: `${deps.callSiteLabel}("${args.type}") — event belongs to feature "${owner}" but the caller runs in feature "${callerKebab}". Events are owned by the feature that defines them. Either move r.defineEvent into "${callerKebab}", or react via r.multiStreamProjection and emit a follow-up event you own.`,
+            });
+        }
+    }
+    // System events skip schema validation — payload shape is owned by the
+    // framework step that emits + the bundled MSP that consumes.
+    let validatedPayload;
+    if (eventDef) {
+        const parsed = eventDef.schema.safeParse(args.payload ?? {});
+        if (!parsed.success)
+            throw validationErrorFromZod(parsed.error);
+        validatedPayload = parsed.data;
+    }
+    else {
+        validatedPayload = (args.payload ?? {});
+    }
+    // Archive guard: block writes on archived streams. Without this an append
+    // would produce an "invisible" row that loadAggregate filters out by default
+    // — silent data loss from the caller's POV.
+    if (await isStreamArchived(deps.db, deps.tenantId, args.aggregateId)) {
+        throw new ArchivedStreamError(deps.tenantId, args.aggregateId);
+    }
+    // Stream-version authoritative. See Block 0 / getStreamVersion doc for
+    // why row.version isn't sufficient once ctx.appendEvent enters the picture.
+    const expectedVersion = await getStreamVersion(deps.db, args.aggregateId, deps.tenantId);
+    const reqCtx = requestContext.get();
+    // metadata.requestId is a plain trace marker — no uniqueness constraint,
+    // every event of the request carries it. HTTP-level idempotency runs in
+    // pipeline/idempotency.ts (Redis-backed cached-response replay) BEFORE
+    // the command executes, so retries never reach this code path twice for
+    // the same request.
+    const stored = await append(deps.db, {
+        aggregateId: args.aggregateId,
+        aggregateType: args.aggregateType,
+        tenantId: deps.tenantId,
+        expectedVersion,
+        type: args.type,
+        eventVersion: eventDef?.version ?? 1,
+        payload: validatedPayload,
+        metadata: {
+            userId: deps.userId,
+            ...(reqCtx?.requestId ? { requestId: reqCtx.requestId } : {}),
+            ...(reqCtx?.correlationId ? { correlationId: reqCtx.correlationId } : {}),
+            ...(reqCtx?.causationId ? { causationId: reqCtx.causationId } : {}),
+            ...(args.headers ? { headers: args.headers } : {}),
+        },
+    });
+    // Inline projections fire in the same tx — a throw rolls everything back
+    // together. Same semantics regardless of which call-site triggered the
+    // append (write-handler ctx.appendEvent vs. MSP-apply ctx.appendEvent).
+    await runProjectionsForEvent(stored, deps.registry, deps.db);
+    return stored;
+}

package/dist/pipeline/auth-claims-resolver.d.ts

@@ -0,0 +1,9 @@
+import type { AuthClaimsContext, AuthClaimsHookDef, SessionUser } from "../engine/types/index.js";
+import type { Logger } from "../logging/types.js";
+export type ResolveAuthClaimsArgs = {
+    readonly user: SessionUser;
+    readonly hooks: readonly AuthClaimsHookDef[];
+    readonly contextFactory: (user: SessionUser) => AuthClaimsContext;
+    readonly log?: Logger;
+};
+export declare function resolveAuthClaims(args: ResolveAuthClaimsArgs): Promise<Record<string, unknown>>;

package/dist/pipeline/auth-claims-resolver.js

@@ -0,0 +1,76 @@
+// Run every registered r.authClaims() hook in parallel and merge the results
+// into a single claim record.
+//
+// Key policy:
+// - Auto-prefix: each key a hook returns is stored as `"<featureName>:<key>"`.
+//   Cross-feature collisions are impossible by construction.
+// - Same-feature duplicate key (two hooks in one feature both return the same
+//   inner key, or one hook returns the same key twice): last-wins. Matches
+//   the `{ ...payload.claims }` spread the JWT layer already does.
+// - Reserved separator: we skip any key returned by a hook that itself
+//   contains `":"` and log a warning. The separator is the framework's —
+//   claim-returning code must own the *inner* name, not the prefix.
+//
+// Error policy: best-effort. If a hook throws, the error is logged and that
+// feature's claims just don't end up in the record. Login still succeeds.
+// Rationale: claims are convenience identity-facts, not access-gates.
+// Security decisions must go through `roles` + field-access rules, both of
+// which are unaffected by a missing claim.
+export async function resolveAuthClaims(args) {
+    if (args.hooks.length === 0)
+        return {};
+    const ctx = args.contextFactory(args.user);
+    const results = await Promise.allSettled(args.hooks.map((h) => runSingleHook(h, args.user, ctx, args.log)));
+    const merged = {};
+    for (let i = 0; i < results.length; i++) {
+        const hook = args.hooks[i];
+        if (!hook)
+            continue;
+        const result = results[i];
+        if (!result)
+            continue;
+        if (result.status === "rejected") {
+            // Already logged in runSingleHook's catch — Promise.allSettled just
+            // surfaces it here so the rest of the merge keeps going.
+            continue;
+        }
+        const claims = result.value;
+        for (const [innerKey, value] of Object.entries(claims)) {
+            if (innerKey.includes(":")) {
+                args.log?.warn("r.authClaims return key contains reserved separator ':' — dropping", {
+                    featureName: hook.featureName,
+                    rejectedKey: innerKey,
+                });
+                continue;
+            }
+            // Typo / rename drift check: when the feature declared its claim
+            // vocabulary via r.claimKey(), any hook return-key outside that
+            // vocabulary is almost certainly a mistake (forgot to declare,
+            // renamed one side but not the other). We still merge it — best-
+            // effort matches the error policy — but log a warning so it surfaces.
+            //
+            // `declaredKeys` is undefined when the feature never called
+            // r.claimKey(), keeping legacy hooks silent (opt-in to the check).
+            if (hook.declaredKeys && !hook.declaredKeys.has(innerKey)) {
+                args.log?.warn("r.authClaims returned an inner-key that was not declared via r.claimKey()", { featureName: hook.featureName, undeclaredKey: innerKey });
+            }
+            const prefixed = `${hook.featureName}:${innerKey}`;
+            merged[prefixed] = value;
+        }
+    }
+    return merged;
+}
+// Isolate the try/catch so the calling Promise.allSettled only sees success
+// values — keeps the merge loop straightforward.
+async function runSingleHook(hook, user, ctx, log) {
+    try {
+        return await hook.fn(user, ctx);
+    }
+    catch (err) {
+        log?.warn("r.authClaims hook threw — dropping this feature's claims for this login", {
+            featureName: hook.featureName,
+            err: err instanceof Error ? err.message : String(err),
+        });
+        throw err;
+    }
+}

package/dist/pipeline/cascade-handler.d.ts

@@ -0,0 +1,6 @@
+import type { TableColumns } from "../db/dialect.js";
+import type { PreDeleteHookFn, Registry } from "../engine/types/index.js";
+import type { SystemHookDef } from "./lifecycle-pipeline.js";
+type TableMap = ReadonlyMap<string, TableColumns<any>>;
+export declare function createCascadeDeleteHook(registry: Registry, tables: TableMap): SystemHookDef<PreDeleteHookFn>;
+export {};

package/dist/pipeline/cascade-handler.js

@@ -0,0 +1,85 @@
+import { deleteMany, fetchOne, updateMany } from "../db/query.js";
+import { OnDeleteStrategies, SystemHookNames, SystemHookPriorities } from "../engine/constants.js";
+import { ConflictError, FrameworkReasons } from "../errors/index.js";
+export function createCascadeDeleteHook(registry, tables) {
+    return {
+        name: SystemHookNames.cascadeDelete,
+        priority: SystemHookPriorities.cascadeDelete,
+        fn: async (payload, ctx) => {
+            const entityName = payload.entityName;
+            const db = ctx.systemDb
+                ? ctx.systemDb.acknowledgeCrossTenant(`cascade delete for r.systemScope() write handler (${entityName ?? "unknown"})`)
+                : ctx.db;
+            if (!entityName || !db) {
+                ctx.log?.debug(`cascadeDelete: skipping — ${!entityName ? "no entityName" : "no db"} on payload ${payload.id}`);
+                return;
+            }
+            // Cascade applies to outgoing hasMany / manyToMany relations only —
+            // the parent side of the link is where `onDelete` lives (see
+            // relations.ts). Incoming belongsTo edges are covered because their
+            // counterpart hasMany declares the strategy.
+            const outgoing = registry.getRelations(entityName);
+            // Outgoing: e.g. department.users (hasMany target: user) — users have FK to department
+            for (const [, relation] of Object.entries(outgoing)) {
+                // Only hasMany / manyToMany carry cascade semantics. belongsTo points
+                // at a parent; the parent's onDelete decides what happens to this node.
+                if (relation.type !== "hasMany" && relation.type !== "manyToMany")
+                    continue;
+                const strategy = relation.onDelete ?? OnDeleteStrategies.nothing;
+                if (strategy === OnDeleteStrategies.nothing)
+                    continue;
+                if (relation.type === "hasMany" && relation.foreignKey) {
+                    const targetTable = tables.get(relation.target);
+                    if (!targetTable)
+                        continue;
+                    if (strategy === OnDeleteStrategies.restrict) {
+                        const row = await fetchOne(db, targetTable, { [relation.foreignKey]: payload.id });
+                        if (row) {
+                            throw new ConflictError({
+                                message: `${relation.target} has records referencing ${entityName}#${payload.id}`,
+                                i18nKey: "errors.deleteRestricted",
+                                details: {
+                                    reason: FrameworkReasons.deleteRestricted,
+                                    blockingEntity: relation.target,
+                                    entity: entityName,
+                                    entityId: payload.id,
+                                },
+                            });
+                        }
+                    }
+                    if (strategy === OnDeleteStrategies.cascade) {
+                        await deleteMany(db, targetTable, { [relation.foreignKey]: payload.id });
+                    }
+                    if (strategy === OnDeleteStrategies.setNull) {
+                        await updateMany(db, targetTable, { [relation.foreignKey]: null }, { [relation.foreignKey]: payload.id });
+                    }
+                }
+                if (relation.type === "manyToMany" && relation.through) {
+                    const throughTable = tables.get(relation.through.table);
+                    if (!throughTable)
+                        continue;
+                    // sourceKey points at the owner side (the entity being deleted).
+                    const sourceKey = relation.through.sourceKey;
+                    if (strategy === OnDeleteStrategies.restrict) {
+                        const row = await fetchOne(db, throughTable, { [sourceKey]: payload.id });
+                        if (row) {
+                            throw new ConflictError({
+                                message: `${relation.through.table} has records referencing ${entityName}#${payload.id}`,
+                                i18nKey: "errors.deleteRestricted",
+                                details: {
+                                    reason: FrameworkReasons.deleteRestricted,
+                                    blockingEntity: relation.through.table,
+                                    entity: entityName,
+                                    entityId: payload.id,
+                                },
+                            });
+                        }
+                    }
+                    if (strategy === OnDeleteStrategies.cascade) {
+                        await deleteMany(db, throughTable, { [sourceKey]: payload.id });
+                    }
+                }
+            }
+        },
+    };
+}

package/dist/pipeline/dispatch-batch.d.ts

@@ -0,0 +1,5 @@
+import type { WriteOrigin } from "@cosmicdrift/kumiko-types/event-store-types";
+import type { SessionUser, WriteResult } from "../engine/types/index.js";
+import type { BatchCommand, BatchResult, DispatchContext } from "./dispatch-shared.js";
+export declare function runBatch(ctx: DispatchContext, commands: readonly BatchCommand[], user: SessionUser, requestId?: string, inheritedOrigin?: WriteOrigin): Promise<BatchResult>;
+export declare function unwrapSingle(batchResult: BatchResult): WriteResult;

package/dist/pipeline/dispatch-batch.js

@@ -0,0 +1,217 @@
+import { requestContext, runWithWriteOrigin } from "../api/request-context.js";
+import { transaction } from "../db/query.js";
+import { InternalError, toWriteErrorInfo, writeFailure } from "../errors/index.js";
+import { createFallbackLogger } from "../logging/utils.js";
+import { parseJsonSafe } from "../utils/safe-json.js";
+import { resolveDbSource } from "./dispatch-shared.js";
+import { executeNestedWrite } from "./dispatch-write.js";
+import { BatchRollback, isLifecycleResult, wrapToKumiko, } from "./dispatcher-utils.js";
+import { effectiveWriteOrigin, isPersonalDataGated, rootWriteOrigin } from "./write-origin.js";
+// afterCommit hooks fire in flushAfterCommit, outside the command's scope.
+function rewrapHooksWithOrigin(afterCommitHooks, fromIndex, origin) {
+    for (let i = fromIndex; i < afterCommitHooks.length; i++) {
+        const original = afterCommitHooks[i];
+        if (!original)
+            continue;
+        afterCommitHooks[i] = () => runWithWriteOrigin(origin, original);
+    }
+}
+// Core batch logic extracted so write() and command() can reuse it
+// (a single write = batch of one, running in its own transaction).
+export async function runBatch(ctx, commands, user, requestId, inheritedOrigin) {
+    const current = requestContext.get();
+    if (!current?.signal) {
+        return runBatchBody(ctx, commands, user, requestId, inheritedOrigin);
+    }
+    // Strip the signal: a disconnect would roll back the tx, idempotency would
+    // cache a 500 for the uncommitted write and afterCommit effects would be lost.
+    const { signal: _signal, ...withoutSignal } = current;
+    return requestContext.run(withoutSignal, () => runBatchBody(ctx, commands, user, requestId, inheritedOrigin));
+}
+async function runBatchBody(ctx, commands, user, requestId, inheritedOrigin) {
+    const { idempotency, lifecycle, appContext: context } = ctx;
+    if (commands.length === 0) {
+        return { isSuccess: true, results: [] };
+    }
+    // Idempotency: if the same requestId has already been processed, return the
+    // cached result without re-executing. The cache holds the full BatchResult.
+    // idempotencyToken is only set when we actually acquired the lock — the
+    // corrupted-cache fallthrough below leaves it unset, so finalize() skips
+    // store() rather than writing over an entry it never owned.
+    let idempotencyToken;
+    if (requestId && idempotency) {
+        const checked = await idempotency.check(user.tenantId, user.id, requestId);
+        if (checked.status === "cached") {
+            const parsed = parseJsonSafe(checked.result, null);
+            if (parsed)
+                return parsed;
+            // corrupted cache entry — treat as miss, let the request re-run
+        }
+        else {
+            idempotencyToken = checked.token;
+        }
+    }
+    // Cache the result under requestId so retries get the same answer. Only a
+    // provably rolled-back 5xx releases the lock instead (releaseOrFinalize).
+    const finalize = async (result) => {
+        if (requestId && idempotency && idempotencyToken) {
+            await idempotency.store(user.tenantId, user.id, requestId, idempotencyToken, result);
+        }
+        return result;
+    };
+    // Never for the no-tx fallback: without a rollback, a re-run would repeat
+    // the side effects of the commands that already ran.
+    const releaseOrFinalize = async (result, isRetryableRollback) => {
+        if (isRetryableRollback && requestId && idempotency && idempotencyToken) {
+            await idempotency.release(user.tenantId, user.id, requestId, idempotencyToken);
+            return result;
+        }
+        return finalize(result);
+    };
+    const afterCommitHooks = [];
+    const results = [];
+    // Flush afterCommit hooks in parallel. Errors are logged, not rethrown:
+    // the writes are already committed, we can't undo them.
+    //
+    // Parallelisation is safe because afterCommit hooks are deferred side-
+    // effects (e.g. feature-level postSave hooks in afterCommit phase)
+    // that don't depend on each other — the in-transaction work already ran
+    // sequentially inside the lifecycle pipeline where ordering matters. If a
+    // future hook ever needs ordering, it should do its sequencing internally
+    // (one hook pushing multiple sub-calls) rather than relying on the
+    // flush-loop order.
+    const flushAfterCommit = async () => {
+        const logError = createFallbackLogger("dispatcher", context.log);
+        const outcomes = await Promise.allSettled(afterCommitHooks.map((hook) => hook()));
+        for (const outcome of outcomes) {
+            if (outcome.status === "rejected") {
+                const detail = outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason);
+                logError.error("afterCommit hook failed", { error: detail });
+            }
+        }
+    };
+    const origins = [];
+    // Fires the batch-level system hooks with every successful save/delete
+    // context from this run. Called after flushAfterCommit so per-save hooks
+    // have all completed first; errors are isolated inside lifecycleHooks.
+    const flushBatchHooksInner = async () => {
+        try {
+            const saves = [];
+            const deletes = [];
+            for (const r of results) {
+                if (!r.isSuccess)
+                    continue;
+                if (!isLifecycleResult(r.data))
+                    continue;
+                if (r.data.kind === "save")
+                    saves.push(r.data);
+                else if (r.data.kind === "delete")
+                    deletes.push(r.data);
+            }
+            if (saves.length > 0 && lifecycle)
+                await lifecycle.runPostSaveBatch(saves, context);
+            if (deletes.length > 0 && lifecycle)
+                await lifecycle.runPostDeleteBatch(deletes, context);
+        }
+        catch (e) {
+            // Batch hooks must never fail the batch — the commit already happened.
+            // Pass the raw error so the logger preserves stack + cause chain;
+            // collapsing to .message hides exactly what ops needs to debug.
+            const logError = createFallbackLogger("dispatcher", context.log);
+            logError.error("batch hook flush failed", { error: e });
+        }
+    };
+    // Batch hooks see every command's saves, so they run under the strictest origin.
+    const flushBatchHooks = async () => {
+        const strictest = origins.find(isPersonalDataGated) ?? origins[0];
+        // skip: no command ran, so batch hooks have no saves or deletes to see
+        if (!strictest)
+            return;
+        await runWithWriteOrigin(strictest, flushBatchHooksInner);
+    };
+    // batch() opens its own outer transaction — needs the top-level
+    // connection's `.begin()` (TransactionSql exposes only `.savepoint()`).
+    const db = resolveDbSource(ctx, undefined);
+    if (!db) {
+        // Without a DB connection there is no transaction to open. Fall back to
+        // sequential execution — useful for unit tests that don't touch the DB.
+        // Each command runs independently; a failure stops the batch.
+        for (let i = 0; i < commands.length; i++) {
+            const cmd = commands[i];
+            if (!cmd)
+                continue;
+            const origin = effectiveWriteOrigin(rootWriteOrigin(ctx.registry, cmd.type, user), inheritedOrigin);
+            origins.push(origin);
+            const hookStart = afterCommitHooks.length;
+            const res = await runWithWriteOrigin(origin, () => executeNestedWrite(ctx, cmd.type, cmd.payload, user, origin, undefined, afterCommitHooks));
+            rewrapHooksWithOrigin(afterCommitHooks, hookStart, origin);
+            results.push(res);
+            if (!res.isSuccess) {
+                // No tx means no rollback — but we still drop afterCommit hooks,
+                // matching the semantic "failure = side-effects don't fire".
+                return finalize({ isSuccess: false, error: res.error, failedIndex: i, results });
+            }
+        }
+        await flushAfterCommit();
+        await flushBatchHooks();
+        return finalize({ isSuccess: true, results });
+    }
+    let transactionCallbackCompleted = false;
+    try {
+        await transaction(db, async (tx) => {
+            for (let i = 0; i < commands.length; i++) {
+                const cmd = commands[i];
+                if (!cmd)
+                    continue;
+                const origin = effectiveWriteOrigin(rootWriteOrigin(ctx.registry, cmd.type, user), inheritedOrigin);
+                origins.push(origin);
+                const hookStart = afterCommitHooks.length;
+                const res = await runWithWriteOrigin(origin, () => executeNestedWrite(ctx, cmd.type, cmd.payload, user, origin, tx, afterCommitHooks));
+                rewrapHooksWithOrigin(afterCommitHooks, hookStart, origin);
+                results.push(res);
+                if (!res.isSuccess) {
+                    throw new BatchRollback(i, res.error);
+                }
+            }
+            transactionCallbackCompleted = true;
+        });
+    }
+    catch (e) {
+        if (e instanceof BatchRollback) {
+            // Thrown inside the callback, so the tx rolled back. A 4xx is
+            // deterministic and stays cached; a 5xx may be transient.
+            return releaseOrFinalize({
+                isSuccess: false,
+                error: e.failureError,
+                failedIndex: e.failedIndex,
+                results,
+            }, e.failureError.httpStatus >= 500);
+        }
+        // A completed callback means the throw came from COMMIT (outcome unknown),
+        // so cache it; otherwise COMMIT was never sent and releasing is safe.
+        const error = toWriteErrorInfo(wrapToKumiko(e));
+        return releaseOrFinalize({
+            isSuccess: false,
+            error,
+            failedIndex: results.length,
+            results,
+        }, !transactionCallbackCompleted && error.httpStatus >= 500);
+    }
+    // Commit succeeded — fire deferred side-effects.
+    await flushAfterCommit();
+    await flushBatchHooks();
+    return finalize({ isSuccess: true, results });
+}
+// Unwrap a BatchResult into a single WriteResult for write()/command().
+// Picks the first result on success (the only one for a single write), the
+// failing one on failure. Falls back to a synthetic error if the batch
+// didn't produce any results (unexpected).
+export function unwrapSingle(batchResult) {
+    if (batchResult.isSuccess) {
+        return (batchResult.results[0] ?? writeFailure(new InternalError({ message: "empty_batch_result" })));
+    }
+    return (batchResult.results[batchResult.failedIndex] ?? {
+        isSuccess: false,
+        error: batchResult.error,
+    });
+}

package/dist/pipeline/dispatch-query.d.ts

@@ -0,0 +1,4 @@
+import type { DbTx } from "../db/connection.js";
+import type { SessionUser } from "../engine/types/index.js";
+import type { DispatchContext, WriteOrigin } from "./dispatch-shared.js";
+export declare function executeQuery(ctx: DispatchContext, type: string, payload: unknown, user: SessionUser, origin: WriteOrigin, tx?: DbTx): Promise<unknown>;

package/dist/pipeline/dispatch-query.js

@@ -0,0 +1,141 @@
+import { hasAccess } from "../engine/access.js";
+import { filterReadFields } from "../engine/field-access.js";
+import { AccessDeniedError, NotFoundError, validationErrorFromZod } from "../errors/index.js";
+import { assertNoSecretLeak } from "../secrets/index.js";
+import { buildHandlerContext, enforceRateLimit, ensureFeatureEnabled, runHandlerInstrumented, } from "./dispatch-shared.js";
+import { runInMemberReadOnlyTransaction } from "./member-read-only-transaction.js";
+// Standalone query execution — used by the public dispatcher.query() and
+// by ctx.query/ctx.queryAs inside handlers. Runs the handler, applies
+// field-level read filters for the given user, logs the event.
+export async function executeQuery(ctx, type, payload, user, origin, tx) {
+    return runHandlerInstrumented(ctx, type, "query", user, () => executeQueryInner(ctx, type, payload, user, origin, tx));
+}
+async function executeQueryInner(ctx, type, payload, user, origin, tx) {
+    const { registry } = ctx;
+    const handler = registry.getQueryHandler(type);
+    if (!handler)
+        throw new NotFoundError("handler", type);
+    // Feature-toggle gate runs BEFORE rate-limit on purpose: calls to a
+    // disabled feature must not consume the rate-limit quota — the call
+    // never happened from the feature's perspective. Order is: lookup →
+    // feature-gate → rate-limit → access → validation → handler.
+    await ensureFeatureEnabled(ctx, type, user.tenantId);
+    // Rate-limit gate runs BEFORE access-check on purpose: anonymous /
+    // unauthorized callers must hit the cap too (otherwise the limit
+    // would be a free probe-detector for valid credentials). The
+    // resolver throws RateLimitError which the dispatcher's outer
+    // wrapper turns into a 429 response. Apps that don't use L3 pay zero
+    // cost for non-systemScope handlers with no rateLimit declared;
+    // systemScope handlers pay one isHandlerSystemScoped lookup to check
+    // whether the default per-tenant limit applies.
+    await enforceRateLimit(ctx, handler.rateLimit, type, user, registry.isHandlerSystemScoped(type));
+    // Default-deny: missing access rule is treated as "no one has access".
+    // The registry boot-validator refuses to register handlers without one,
+    // so in normal boots this branch shouldn't fire — the guard is belt-and-
+    // suspenders in case a handler sneaks through (e.g. runtime injection).
+    if (!hasAccess(user, handler.access)) {
+        throw new AccessDeniedError({
+            message: `access denied for ${type}`,
+            details: { handler: type },
+        });
+    }
+    const parsed = handler.schema.safeParse(payload);
+    if (!parsed.success) {
+        throw validationErrorFromZod(parsed.error);
+    }
+    // Trash opt-in rides the validated query payload: only the entity-list
+    // schema (and custom query schemas that opt in) carries `includeDeleted`,
+    // so other handlers never see the flag. Visibility filters still apply
+    // downstream (see HandlerContext.includeDeleted) — safe from raw input.
+    const includeDeleted = typeof parsed.data === "object" &&
+        parsed.data !== null &&
+        parsed.data["includeDeleted"] === true; // @cast-boundary validated-payload
+    // A resolved member (ctx.queryAsMember) runs in a Postgres READ ONLY transaction, not just the ctx surface below.
+    return user.origin === "member-resolution"
+        ? runInMemberReadOnlyTransaction(ctx, tx, (readOnlyTx) => runQueryHandler(ctx, type, handler, parsed.data, includeDeleted, user, origin, readOnlyTx))
+        : runQueryHandler(ctx, type, handler, parsed.data, includeDeleted, user, origin, tx);
+}
+async function runQueryHandler(ctx, type, handler, payload, includeDeleted, user, origin, tx) {
+    const { registry } = ctx;
+    const handlerContext = await buildHandlerContext(ctx, type, user, origin, tx, undefined, includeDeleted);
+    let result = await handler.handler({ type, payload, user }, handlerContext);
+    // postQuery-Hooks: fire BEFORE field-access-filter so hooks see raw data
+    // and can merge custom-fields/computed-counts/tags/etc. Each hook is
+    // responsible for its own field-access on values it adds (the filter
+    // below only knows the entity's stammfields).
+    //
+    // Two firing-pfade kombiniert in dieser Reihenfolge:
+    //   1. Handler-keyed hooks via r.hook("postQuery", "ns:query:list", fn)
+    //      — feuern nur für genau diesen handler
+    //   2. Entity-keyed hooks via r.entityHook("postQuery", "property", fn)
+    //      — feuern für ALLE query-handlers des entity
+    const entityName = registry.getHandlerEntity(type);
+    // Handler-keyed postQuery hooks fire for any query (incl. entity-less
+    // standalone queries like "ns:dashboard"). Entity-keyed hooks only apply
+    // when the handler maps to an entity — so this block must NOT be gated on
+    // entityName, or hooks on standalone queries register silently and never fire.
+    const handlerHooks = registry.getPostQueryHooks(type);
+    const entityHooks = entityName ? registry.getEntityPostQueryHooks(entityName) : [];
+    const postQueryHooks = [...handlerHooks, ...entityHooks];
+    if (postQueryHooks.length > 0 && result && typeof result === "object") {
+        if (Array.isArray(result)) {
+            let rows = result; // @cast-boundary engine-payload
+            for (const hook of postQueryHooks) {
+                const out = await hook({ entityName, rows }, handlerContext);
+                rows = [...out.rows];
+            }
+            result = rows;
+        }
+        else if (Array.isArray(result.rows)) {
+            // @cast-boundary engine-payload
+            const r = result;
+            let rows = r.rows;
+            for (const hook of postQueryHooks) {
+                const out = await hook({ entityName, rows }, handlerContext);
+                rows = [...out.rows];
+            }
+            result = { ...r, rows };
+        }
+        else {
+            let rows = [result]; // @cast-boundary engine-payload
+            for (const hook of postQueryHooks) {
+                const out = await hook({ entityName, rows }, handlerContext);
+                rows = [...out.rows];
+            }
+            // A single-object result carries exactly one row through the hook
+            // pipeline. Returning 0 rows (effect lost) or ≥2 rows (extras
+            // dropped) cannot be represented in the single-object response —
+            // surface it instead of silently falling back / truncating.
+            if (rows.length !== 1) {
+                throw new Error(`postQuery hook on single-object result for "${type}" must return exactly one row, got ${rows.length}`);
+            }
+            result = rows[0];
+        }
+    }
+    // Field-level read filter — only applies to entity-bound results.
+    const entity = entityName ? registry.getEntity(entityName) : undefined;
+    if (entity && result && typeof result === "object") {
+        if (Array.isArray(result)) {
+            result = result.map((row) => filterReadFields(entity, row, user));
+        }
+        else {
+            const resultAsDbRow = result; // @cast-boundary engine-payload
+            if (Array.isArray(resultAsDbRow.rows)) {
+                // generic handler-result shape narrow
+                const r = result; // @cast-boundary engine-payload
+                result = {
+                    ...r,
+                    rows: r.rows.map((row) => filterReadFields(entity, row, user)),
+                };
+            }
+            else {
+                result = filterReadFields(entity, result, user); // @cast-boundary engine-payload
+            }
+        }
+    }
+    // Response-guard: fail the request if a handler accidentally included
+    // a Secret<> branded value in its return. Must run AFTER field-access
+    // filtering so a legitimately stripped secret doesn't false-positive.
+    assertNoSecretLeak(result);
+    return result;
+}