@cosmicdrift/kumiko-framework 0.327.0 → 0.328.1

package/src/pipeline/auth-claims-resolver.ts

@@ -1,103 +0,0 @@
-import type { AuthClaimsContext, AuthClaimsHookDef, SessionUser } from "../engine/types";
-import type { Logger } from "../logging/types";
-
-// Shape the dispatcher (or a test harness) has to hand in: a way to build the
-// per-hook context and the list of registered hooks. Staying off the
-// Dispatcher/Registry types here keeps this utility trivially unit-testable —
-// a fake `hooks` array + a stub `contextFactory` and you can assert the merge
-// policy without spinning up Drizzle, Redis, or anything else.
-export type ResolveAuthClaimsArgs = {
-  readonly user: SessionUser;
-  readonly hooks: readonly AuthClaimsHookDef[];
-  readonly contextFactory: (user: SessionUser) => AuthClaimsContext;
-  readonly log?: Logger;
-};
-
-// 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: ResolveAuthClaimsArgs,
-): Promise<Record<string, unknown>> {
-  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: Record<string, unknown> = {};
-  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: AuthClaimsHookDef,
-  user: SessionUser,
-  ctx: AuthClaimsContext,
-  log: Logger | undefined,
-): Promise<Record<string, unknown>> {
-  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/src/pipeline/cascade-handler.ts

@@ -1,109 +0,0 @@
-import type { TableColumns } from "../db/dialect";
-import { deleteMany, fetchOne, updateMany } from "../db/query";
-import { OnDeleteStrategies, SystemHookNames, SystemHookPriorities } from "../engine/constants";
-import type { PreDeleteHookFn, Registry } from "../engine/types";
-import { ConflictError, FrameworkReasons } from "../errors";
-import type { SystemHookDef } from "./lifecycle-pipeline";
-
-// biome-ignore lint/suspicious/noExplicitAny: Drizzle dynamic tables
-type TableMap = ReadonlyMap<string, TableColumns<any>>;
-
-export function createCascadeDeleteHook(
-  registry: Registry,
-  tables: TableMap,
-): SystemHookDef<PreDeleteHookFn> {
-  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/src/pipeline/dispatch-batch.ts

@@ -1,269 +0,0 @@
-import type { WriteOrigin } from "@cosmicdrift/kumiko-types/event-store-types";
-import { requestContext, runWithWriteOrigin } from "../api/request-context";
-import type { DbConnection } from "../db/connection";
-import { transaction } from "../db/query";
-import type { DeleteContext, SaveContext, SessionUser, WriteResult } from "../engine/types";
-import { InternalError, toWriteErrorInfo, writeFailure } from "../errors";
-import { createFallbackLogger } from "../logging/utils";
-import { parseJsonSafe } from "../utils/safe-json";
-import type { BatchCommand, BatchResult, DispatchContext } from "./dispatch-shared";
-import { resolveDbSource } from "./dispatch-shared";
-import { executeNestedWrite } from "./dispatch-write";
-import {
-  type AfterCommitHook,
-  BatchRollback,
-  isLifecycleResult,
-  wrapToKumiko,
-} from "./dispatcher-utils";
-import { effectiveWriteOrigin, isPersonalDataGated, rootWriteOrigin } from "./write-origin";
-
-// afterCommit hooks fire in flushAfterCommit, outside the command's scope.
-function rewrapHooksWithOrigin(
-  afterCommitHooks: AfterCommitHook[],
-  fromIndex: number,
-  origin: WriteOrigin,
-): void {
-  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: DispatchContext,
-  commands: readonly BatchCommand[],
-  user: SessionUser,
-  requestId?: string,
-  inheritedOrigin?: WriteOrigin,
-): Promise<BatchResult> {
-  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: DispatchContext,
-  commands: readonly BatchCommand[],
-  user: SessionUser,
-  requestId?: string,
-  inheritedOrigin?: WriteOrigin,
-): Promise<BatchResult> {
-  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: string | undefined;
-  if (requestId && idempotency) {
-    const checked = await idempotency.check(user.tenantId, user.id, requestId);
-    if (checked.status === "cached") {
-      const parsed = parseJsonSafe<BatchResult | null>(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: BatchResult): Promise<BatchResult> => {
-    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: BatchResult,
-    isRetryableRollback: boolean,
-  ): Promise<BatchResult> => {
-    if (isRetryableRollback && requestId && idempotency && idempotencyToken) {
-      await idempotency.release(user.tenantId, user.id, requestId, idempotencyToken);
-      return result;
-    }
-    return finalize(result);
-  };
-
-  const afterCommitHooks: AfterCommitHook[] = [];
-  const results: WriteResult[] = [];
-
-  // 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: WriteOrigin[] = [];
-
-  // 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: SaveContext[] = [];
-      const deletes: DeleteContext[] = [];
-      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) as DbConnection | 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: BatchResult): WriteResult {
-  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/src/pipeline/dispatch-query.ts

@@ -1,195 +0,0 @@
-import type { DbRow, DbTx } from "../db/connection";
-import { hasAccess } from "../engine/access";
-import { filterReadFields } from "../engine/field-access";
-import type { QueryHandlerDef, SessionUser } from "../engine/types";
-import { AccessDeniedError, NotFoundError, validationErrorFromZod } from "../errors";
-import { assertNoSecretLeak } from "../secrets";
-import type { DispatchContext, WriteOrigin } from "./dispatch-shared";
-import {
-  buildHandlerContext,
-  enforceRateLimit,
-  ensureFeatureEnabled,
-  runHandlerInstrumented,
-} from "./dispatch-shared";
-import { runInMemberReadOnlyTransaction } from "./member-read-only-transaction";
-
-// 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: DispatchContext,
-  type: string,
-  payload: unknown,
-  user: SessionUser,
-  origin: WriteOrigin,
-  tx?: DbTx,
-): Promise<unknown> {
-  return runHandlerInstrumented(ctx, type, "query", user, () =>
-    executeQueryInner(ctx, type, payload, user, origin, tx),
-  );
-}
-
-async function executeQueryInner(
-  ctx: DispatchContext,
-  type: string,
-  payload: unknown,
-  user: SessionUser,
-  origin: WriteOrigin,
-  tx?: DbTx,
-): Promise<unknown> {
-  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 as Record<string, unknown>)["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: DispatchContext,
-  type: string,
-  handler: QueryHandlerDef,
-  payload: unknown,
-  includeDeleted: boolean,
-  user: SessionUser,
-  origin: WriteOrigin,
-  tx: DbTx | undefined,
-): Promise<unknown> {
-  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 as Record<string, unknown>[]; // @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 as { rows?: unknown }).rows)) {
-      // @cast-boundary engine-payload
-      const r = result as { rows: Record<string, unknown>[]; nextCursor: string | null };
-      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: Record<string, unknown>[] = [result as Record<string, unknown>]; // @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: Record<string, unknown>) => filterReadFields(entity, row, user));
-    } else {
-      const resultAsDbRow = result as DbRow; // @cast-boundary engine-payload
-      if (Array.isArray((resultAsDbRow as { rows?: unknown }).rows)) {
-        // generic handler-result shape narrow
-        const r = result as { rows: Record<string, unknown>[]; nextCursor: string | null }; // @cast-boundary engine-payload
-        result = {
-          ...r,
-          rows: r.rows.map((row) => filterReadFields(entity, row, user)),
-        };
-      } else {
-        result = filterReadFields(entity, result as DbRow, 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;
-}