@cosmicdrift/kumiko-framework 0.146.1 → 0.146.3

package/src/engine/codemod/pipeline-codemod.ts

@@ -370,7 +370,7 @@ export function generatePerformBlock(
   const pipelineType = schemaType ? `<${schemaType}, unknown>` : "";
 
   return [
-    `perform: pipeline${pipelineType}(({ event, r }) => [`,
+    `perform: stepsPipeline${pipelineType}(({ event, r }) => [`,
     stepsStr,
     `  ${stepIndent}]),`,
   ].join("\n");
@@ -513,7 +513,7 @@ function contentHasPipelineImport(content: string): boolean {
   const importLine = content
     .split("\n")
     .find((l) => l.includes("import") && l.includes("@cosmicdrift/kumiko-framework/engine"));
-  return !!importLine && importLine.includes("pipeline");
+  return !!importLine && importLine.includes("stepsPipeline");
 }
 
 function ensurePipelineImport(content: string): string | null {
@@ -525,7 +525,7 @@ function ensurePipelineImport(content: string): string | null {
   const match = content.match(importRegex);
   if (match) {
     const existingImports = (match[1] as string).trim();
-    const newImports = existingImports ? `${existingImports}, pipeline` : "pipeline";
+    const newImports = existingImports ? `${existingImports}, stepsPipeline` : "stepsPipeline";
     return content.replace(
       importRegex,
       `import { ${newImports} } from "@cosmicdrift/kumiko-framework/engine"`,
@@ -611,7 +611,7 @@ export async function convertFile(
       if (importResult) {
         content = importResult;
       } else if (options.verbose) {
-        console.log(`  ~ ${filePath}: pipeline import not needed or already present`);
+        console.log(`  ~ ${filePath}: stepsPipeline import not needed or already present`);
       }
     }
 
@@ -621,7 +621,7 @@ export async function convertFile(
 
     const status = hadChanges ? "converted" : "skipped";
     const reason = hadChanges
-      ? "handler replaced with perform: pipeline(...)"
+      ? "handler replaced with perform: stepsPipeline(...)"
       : "no convertible handler";
     return { filePath, status, reason };
   } catch (err) {

package/src/engine/define-handler.ts

@@ -23,7 +23,7 @@ import type { PipelineDef } from "./types/step";
 // visible) and collapse `keyof TMap` to `never`. See the spike-findings
 // memory for the empirical proof.
 //
-// Two authoring forms — `handler` (free-form) or `perform: pipeline(...)`
+// Two authoring forms — `handler` (free-form) or `perform: stepsPipeline(...)`
 // (step-pipeline). A `perform` is compiled to a handler-function at
 // definition time; the dispatcher only ever sees `handler`.
 
@@ -126,7 +126,7 @@ export function defineWriteHandler<
     throw new Error(
       `defineWriteHandler("${def.name}"): both \`handler\` and \`perform\` are set. ` +
         `Pick one — \`handler\` for the free-form async function, ` +
-        `\`perform: pipeline(...)\` for the step-pipeline form. ` +
+        `\`perform: stepsPipeline(...)\` for the step-pipeline form. ` +
         `(See step-vocabulary.md for which form fits.)`,
     );
   }

package/src/engine/define-workflow.ts

@@ -57,7 +57,7 @@ export type WorkflowInput<TPayload = unknown, TData = unknown> = {
  * defineWorkflow({
  *   name: "user-onboarding",
  *   trigger: { kind: "event", eventType: "user.signed-up" },
- *   steps: pipeline(({ event, r }) => [
+ *   steps: stepsPipeline(({ event, r }) => [
  *     r.step.mail.send({ to: () => event.payload.email, subject: "Welcome!", body: "..." }),
  *     r.step.wait({ for: "P1D" }),
  *     r.step.read.findOne("user", { table: userTable, where: ... }),

package/src/engine/index.ts

@@ -179,18 +179,20 @@ export {
   filterReadFields,
 } from "./field-access";
 // findForbiddenMembershipRole/isForbiddenMembershipRole/
-// stripForbiddenMembershipRoles are Public API for host apps that build
-// their own membership handlers. FORBIDDEN_MEMBERSHIP_ROLES itself stays
-// internal (637/3) — exporting the raw Set would make its representation a
-// semver promise; the predicate functions are the intended surface.
+// stripForbiddenMembershipRoles/buildSessionRoles are Public API for host
+// apps that build their own membership handlers. FORBIDDEN_MEMBERSHIP_ROLES
+// itself stays internal (637/3) — exporting the raw Set would make its
+// representation a semver promise; the predicate functions are the intended
+// surface.
 export {
+  buildSessionRoles,
   findForbiddenMembershipRole,
   isForbiddenMembershipRole,
   stripForbiddenMembershipRoles,
 } from "./membership-roles";
 export type { OwnershipClause, OwnershipMap, OwnershipRef, OwnershipRule } from "./ownership";
 export { from } from "./ownership";
-export { buildPipelineSteps, pipeline } from "./pipeline";
+export { buildPipelineSteps, stepsPipeline } from "./pipeline";
 export { defineApply, defineMspApply, setFields } from "./projection-helpers";
 export type { BuiltinQnType, ParsedQn, QnType } from "./qualified-name";
 export { isValidQn, parseQn, QnTypes, qn, toKebab } from "./qualified-name";

package/src/engine/membership-roles.ts

@@ -30,3 +30,16 @@ export function findForbiddenMembershipRole(roles: readonly string[]): string |
 export function stripForbiddenMembershipRoles(roles: readonly string[]): readonly string[] {
   return roles.filter((role) => !isForbiddenMembershipRole(role));
 }
+
+// Single mint path for session roles: merges globalRoles with the stripped
+// membership portion and dedupes. Every place that builds a session's roles
+// from a membership should go through this instead of repeating
+// `new Set([...globalRoles, ...stripForbiddenMembershipRoles(x)])` — a new
+// mint site that forgets the strip is exactly the bug class this guards
+// against.
+export function buildSessionRoles(
+  globalRoles: readonly string[],
+  membershipRoles: readonly string[],
+): readonly string[] {
+  return Array.from(new Set([...globalRoles, ...stripForbiddenMembershipRoles(membershipRoles)]));
+}

package/src/engine/pipeline.ts

@@ -1,4 +1,4 @@
-// pipeline() — public factory used in defineWriteHandler({ perform: pipeline(...) }).
+// stepsPipeline() — public factory used in defineWriteHandler({ perform: stepsPipeline(...) }).
 //
 // The closure receives { event, r } and returns the immutable list of
 // step instances. `r` is the StepBuilder singleton; new tier-1 steps
@@ -8,15 +8,10 @@
 // the resolver-side PipelineCtx (run-pipeline.ts). Resolvers that need
 // prior step results destructure them from the resolver's ctx.
 //
-// Naming note (Followup #1): the public `pipeline()` helper shares its
-// name with the internal `packages/framework/src/pipeline/` directory
-// (dispatcher, lifecycle, outbox-poller). No user-visible collision —
-// the internal directory isn't an export — but maintainer repo-wide
-// grep for `pipeline` returns mixed results. If a rename ever lands,
-// candidates are `r.steps([...])` for the public API or
-// `engine-pipeline/` / `runtime/` for the internal directory.
-// Decision-cost grows with each new caller; the rename window narrows
-// after the first external consumer.
+// Renamed from `pipeline()` (Followup #1) — it shared its name with the
+// internal `packages/framework/src/pipeline/` directory (dispatcher,
+// lifecycle, outbox-poller), which made repo-wide grep for `pipeline`
+// return mixed results.
 
 import { buildAggregateAppendEventStep } from "./steps/aggregate-append-event";
 import { buildAggregateCreateStep } from "./steps/aggregate-create";
@@ -69,7 +64,7 @@ const stepBuilder: StepBuilder = {
   },
 };
 
-export function pipeline<TPayload = unknown, TData = unknown>(
+export function stepsPipeline<TPayload = unknown, TData = unknown>(
   closure: (ctx: PipelineBuildCtx<TPayload>) => readonly StepInstance[],
 ): PipelineDef<TPayload, TData> {
   return {

package/src/engine/run-pipeline.ts

@@ -64,7 +64,7 @@ export async function runPipeline<TPayload, TData, TMap extends object = KumikoE
   if (outcome.kind === "return") {
     // RETURN_RESULT_KEY is only produced by r.step.return, whose run()
     // returns WriteResult<unknown>. The pipeline's generic TData is
-    // bound at build time (defineWriteHandler ↔ pipeline<P, D>(...));
+    // bound at build time (defineWriteHandler ↔ stepsPipeline<P, D>(...));
     // matching the runtime value to that compile-time type is the
     // contract user-side. Cast crosses that boundary.
     return outcome.result as WriteResult<TData>;

package/src/engine/types/handlers.ts

@@ -796,7 +796,7 @@ export type WriteHandlerDef = {
   readonly access?: AccessRule;
   readonly unsafeSkipTransitionGuard?: boolean;
   readonly rateLimit?: RateLimitOption;
-  // Set when the author wrote a `perform: pipeline(...)` block. Boot-
+  // Set when the author wrote a `perform: stepsPipeline(...)` block. Boot-
   // validators (projection-allowlist) and Designer/AI tooling read this
   // to inspect the step list. Absent on free-form handlers.
   // Inline-import is intentional: step.ts imports HandlerContext from

package/src/engine/types/step.ts

@@ -126,7 +126,7 @@ export type StepInstance = {
 };
 
 /**
- * What `pipeline(closure)` returns. Carries the closure (instead of an
+ * What `stepsPipeline(closure)` returns. Carries the closure (instead of an
  * eagerly-built array) so each handler-call sees a fresh event ref and
  * the `r` step-builder is resolved at runtime, not at module-load time.
  *
@@ -140,7 +140,7 @@ export type StepInstance = {
  * `noUnusedVariables` marker, not user-facing). _TData is NOT inferred
  * from the closure body (r.step.return has its own per-call TData), so
  * callers must spell it explicitly:
- *   `pipeline<{ greeting: string }, { echoed: string }>(...)`
+ *   `stepsPipeline<{ greeting: string }, { echoed: string }>(...)`
  * Better DX is a known follow-up — see step-vocabulary.md M.1-Followups.
  */
 export type PipelineDef<TPayload = unknown, _TData = unknown> = {
@@ -149,7 +149,7 @@ export type PipelineDef<TPayload = unknown, _TData = unknown> = {
 };
 
 /**
- * Argument bundle passed to the closure inside `pipeline(closure)`.
+ * Argument bundle passed to the closure inside `stepsPipeline(closure)`.
  * Build-time only — no `steps`, no `scope`, no `db`: at build time no
  * step has run yet.
  *
@@ -314,7 +314,7 @@ export type StepNamespace = {
     },
   ) => StepInstance;
   // --- Tier-3 / Workflow-only steps ---
-  // Only available inside defineWorkflow ({ steps: pipeline(...) }).
+  // Only available inside defineWorkflow ({ steps: stepsPipeline(...) }).
   // Runtime guard: throws when used inside sync defineWriteHandler.
   readonly wait: (args: { readonly for: StepResolver<string> }) => StepInstance;
   readonly waitForEvent: (args: {

package/src/engine/validate-projection-allowlist.ts

@@ -13,7 +13,7 @@
 // don't run at build time, so dummy event-payloads are fine.
 //
 // CLOSURE-BODY CONTRACT: the pipeline-closure body (the function passed
-// to `pipeline(...)`) must produce its step-list deterministically based
+// to `stepsPipeline(...)`) must produce its step-list deterministically based
 // on the step-builder `r` alone. Reading `event.payload` outside of
 // resolvers (i.e. at the top of the closure, not inside a step's `row:`
 // or `data:` callback) is forbidden — at boot the dummy payload is `{}`

package/src/pipeline/dispatch-batch.ts

@@ -0,0 +1,187 @@
+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";
+
+// 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,
+): 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.
+  if (requestId && idempotency) {
+    const cached = await idempotency.check(requestId);
+    if (cached) {
+      const parsed = parseJsonSafe<BatchResult | null>(cached, null);
+      if (parsed) return parsed;
+      // corrupted cache entry — treat as miss, let the request re-run
+    }
+  }
+
+  // Wrap return paths: cache the final result under requestId so retries get
+  // the same answer (both success and failure results are cached).
+  const finalize = async (result: BatchResult): Promise<BatchResult> => {
+    if (requestId && idempotency) {
+      await idempotency.store(requestId, result);
+    }
+    return 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 });
+      }
+    }
+  };
+
+  // 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 flushBatchHooks = 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() 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 res = await executeNestedWrite(
+        ctx,
+        cmd.type,
+        cmd.payload,
+        user,
+        undefined,
+        afterCommitHooks,
+      );
+      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 });
+  }
+
+  try {
+    await transaction(db, async (tx) => {
+      for (let i = 0; i < commands.length; i++) {
+        const cmd = commands[i];
+        if (!cmd) continue;
+        const res = await executeNestedWrite(
+          ctx,
+          cmd.type,
+          cmd.payload,
+          user,
+          tx,
+          afterCommitHooks,
+        );
+        results.push(res);
+        if (!res.isSuccess) {
+          throw new BatchRollback(i, res.error);
+        }
+      }
+    });
+  } catch (e) {
+    if (e instanceof BatchRollback) {
+      return finalize({
+        isSuccess: false,
+        error: e.failureError,
+        failedIndex: e.failedIndex,
+        results,
+      });
+    }
+    return finalize({
+      isSuccess: false,
+      error: toWriteErrorInfo(wrapToKumiko(e)),
+      failedIndex: results.length,
+      results,
+    });
+  }
+
+  // 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 last result if present (the failing one for failures, the only
+// one for successful single writes). 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

@@ -0,0 +1,165 @@
+import type { DbRow, DbTx } from "../db/connection";
+import { hasAccess } from "../engine/access";
+import { filterReadFields } from "../engine/field-access";
+import type { SessionUser } from "../engine/types";
+import { AccessDeniedError, NotFoundError, validationErrorFromZod } from "../errors";
+import { assertNoSecretLeak } from "../secrets";
+import type { DispatchContext } from "./dispatch-shared";
+import {
+  buildHandlerContext,
+  enforceRateLimit,
+  ensureFeatureEnabled,
+  runHandlerInstrumented,
+} from "./dispatch-shared";
+
+// 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,
+  tx?: DbTx,
+): Promise<unknown> {
+  return runHandlerInstrumented(ctx, type, "query", user, () =>
+    executeQueryInner(ctx, type, payload, user, tx),
+  );
+}
+
+async function executeQueryInner(
+  ctx: DispatchContext,
+  type: string,
+  payload: unknown,
+  user: SessionUser,
+  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. Inline-skip when the handler
+  // didn't opt in — keeps the hot path zero-cost (no await on a
+  // no-op promise).
+  if (handler.rateLimit !== undefined) {
+    await enforceRateLimit(ctx, handler.rateLimit, type, user);
+  }
+
+  // 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
+  const handlerContext = buildHandlerContext(ctx, type, user, tx, undefined, includeDeleted);
+  let result = await handler.handler({ type, payload: parsed.data, 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;
+}