@opensaas/stack-core 0.37.0 → 0.39.0

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @opensaas/stack-core@0.37.0 build /home/runner/work/stack/stack/packages/core
+> @opensaas/stack-core@0.39.0 build /home/runner/work/stack/stack/packages/core
 > tsc
 

package/CHANGELOG.md

@@ -1,5 +1,196 @@
 # @opensaas/stack-core
 
+## 0.39.0
+
+### Minor Changes
+
+- [#926](https://github.com/OpenSaasAU/stack/pull/926) [`5e546b0`](https://github.com/OpenSaasAU/stack/commit/5e546b0fe3542ba41fc77e0a4628acc96eec13ea) Thanks [@borisno2](https://github.com/borisno2)! - Add a first-class `bigInt()` field type for 64-bit integers (e.g. a millisecond epoch) that overflow `integer()`'s 32-bit `Int` — Prisma `BigInt`, TypeScript `bigint`, with an admin UI component, filtering, and MCP support.
+
+  ```typescript
+  import { bigInt } from '@opensaas/stack-core/fields'
+
+  fields: {
+    occurredAtMs: bigInt({ validation: { isRequired: true } }),
+  }
+
+  await context.db.event.create({
+    data: { occurredAtMs: 9007199254740993n }, // bigint, number, or numeric string
+  })
+  ```
+
+  Create/update accept `bigint`, an integer `number`, or a numeric `string`, and always coerce to `bigint`. A `number` above `Number.MAX_SAFE_INTEGER` is rejected rather than silently losing precision. `bigint` isn't JSON-serialisable, so an MCP CRUD tool renders the value as a decimal string instead of throwing, and the admin UI's server→client boundary (list table, item form, relationship table) now round-trips a `bigint` value correctly rather than throwing during render. The migration introspector maps Prisma `BigInt` columns to `bigInt()` instead of the previous lossy `text()` fallback.
+
+- [#919](https://github.com/OpenSaasAU/stack/pull/919) [`cbb03fc`](https://github.com/OpenSaasAU/stack/commit/cbb03fc26047869d23513fbb156c6194d9be389b) Thanks [@borisno2](https://github.com/borisno2)! - Fix a fail-open bug where a field-level access rule returning a Prisma filter (instead of a boolean) silently granted the field full access. `checkFieldAccess` now throws `InvalidFieldAccessResultError` for any non-boolean result instead of defaulting to allow.
+
+  This narrows `FieldAccessControl`'s return type from `boolean | PrismaFilter | Promise<...>` to `boolean | Promise<boolean>` — field-level access was already documented (ADR-0001) to be boolean-only; the type had drifted from that. If a field rule returned a filter, it will now fail to compile (or throw at runtime for untyped/JS configs) instead of silently granting access. Evaluate the condition yourself and return a boolean instead, e.g.:
+
+  ```ts
+  // Before (silently granted full access on read/write)
+  someField: text({
+    access: {
+      update: ({ session }) => ({ ownerId: { equals: session?.userId } }),
+    },
+  })
+
+  // After
+  someField: text({
+    access: {
+      update: ({ session, item }) => !!session && session.userId === item?.ownerId,
+    },
+  })
+  ```
+
+  See `docs/adr/0030-field-level-access-fails-closed-on-a-non-boolean-result.md` for the full reasoning.
+
+- [#925](https://github.com/OpenSaasAU/stack/pull/925) [`6f9a64d`](https://github.com/OpenSaasAU/stack/commit/6f9a64d2f25212e91181adc2b67add326a540f6a) Thanks [@borisno2](https://github.com/borisno2)! - Fix a field-level `read` gate withholding a field's VALUE but leaving its PREDICATE unconstrained: a read-denied field could still be named in a `where`/`orderBy`, letting its value (or relative order) be recovered by probing — `count()` is the cleanest instrument, since it answers a predicate while returning no rows at all. `findMany`/`count` now reject a `where`/`orderBy` key naming a field the session cannot read (including nested inside `AND`/`OR`/`NOT`), throwing instead of returning a silently narrowed or empty result. A `read` rule that depends on the fetched row (`item`) cannot be evaluated before the query runs and now resolves to a denial rather than being skipped — see `docs/adr/0031-a-predicate-cannot-name-a-field-the-session-cannot-read.md`. `sudo` is unaffected.
+
+  This was independently reachable through the admin UI's own list view: `collectFilterSpecs`, `buildListFilterWhere`, and `collectFilterSuggestions` (`@opensaas/stack-core`) now take a required `{ session, context }` argument and return a `Promise`, excluding a read-denied field from the collected Filter specs so the UI never suggests, autocompletes, or submits a filter the engine is going to reject — a `field:value` token for such a field now degrades to free text instead. The list view's sort validation (`@opensaas/stack-ui`) excludes the same fields from what a `?sort=` URL param may activate.
+
+  ```ts
+  // Before
+  const specs = collectFilterSpecs(listConfig, listKey, config)
+  const where = buildListFilterWhere(query, listConfig, listKey, config)
+  const suggestions = collectFilterSuggestions(listConfig, listKey, config)
+
+  // After — pass the session/context the field's `read` access is checked against
+  const specs = await collectFilterSpecs(listConfig, listKey, config, { session, context })
+  const where = await buildListFilterWhere(query, listConfig, listKey, config, { session, context })
+  const suggestions = await collectFilterSuggestions(listConfig, listKey, config, {
+    session,
+    context,
+  })
+  ```
+
+- [#934](https://github.com/OpenSaasAU/stack/pull/934) [`9a399d6`](https://github.com/OpenSaasAU/stack/commit/9a399d68e4d3f384d4cef5ccd5fc8ec6802a40a5) Thanks [@list({](https://github.com/list({)! - `afterTransaction` now fires when the OUTERMOST transaction a write participates in settles, and can report `status: 'rolled-back'` where it always reported `'committed'` before (ADR-0028, fixes [#899](https://github.com/OpenSaasAU/stack/issues/899)).
+
+  A write that joins a transaction it did not open — inside `context.transaction()`, or a hook's own `context.db` write — used to fire its `afterTransaction` bracket optimistically as soon as its own write returned, even though the enclosing transaction was still open and could still roll back. It now defers that bracket until the transaction owner (`context.transaction()`, or the Write Pipeline when it opened the transaction) observes the real commit/rollback, then reports the outcome as a conjunction: `committed` if and only if the write itself succeeded **and** the enclosing transaction committed (the write's own error always wins over the transaction's outcome). `beforeTransaction` is unaffected — it still runs eagerly, before its write.
+
+  ```typescript
+
+    hooks: {
+      afterTransaction: async ({ status, item, error }) => {
+        if (status === 'rolled-back') {
+          // Now correctly fires even when this write itself succeeded but the
+          // OUTER context.transaction() callback later threw.
+          await billing.releaseSeat(error)
+        } else {
+          await billing.confirmSeat(item.seatId)
+        }
+      },
+    },
+  })
+  ```
+
+  Three behavior changes to be aware of when upgrading:
+
+  - A `context.transaction()` call can now **reject** with `AfterTransactionError` even after its underlying transaction already committed, if a deferred `afterTransaction` hook throws. A transaction/serialization error (e.g. `P2034`) still takes precedence and propagates unwrapped, so an existing `P2034` retry loop is unaffected.
+  - The deferred `item` a joined write's `afterTransaction` receives on commit is the row **as that write persisted it**, captured at write time — not re-read at flush — so it can be stale if a later write in the same transaction touches the same record.
+  - Transaction-boundary hooks (`beforeTransaction`/`afterTransaction`) on a joined write now always receive a context bound to the base client, never the transaction client — matching what top-level writes already did.
+
+  A write with no transaction owner at all (an app-managed `prisma.$transaction`, or a client that cannot open one, e.g. a bare test mock) is unaffected and still fires `afterTransaction` optimistically at write time.
+
+  See `docs/adr/0028-a-transaction-boundary-hook-reports-the-outermost-transaction.md` and the "In-transaction vs transaction-boundary hooks" section of the hooks concept doc.
+
+- [#924](https://github.com/OpenSaasAU/stack/pull/924) [`05c9ad4`](https://github.com/OpenSaasAU/stack/commit/05c9ad40f8c4e76718d870e0c1c02511a3475943) Thanks [@borisno2](https://github.com/borisno2)! - Fix `FieldAccess['read']` typing `item` as absent when Field Visibility always passes the fetched row. A field `read` rule that reads a property off `item` now compiles without a cast, `any`, or non-null assertion:
+
+  ```ts
+  // Before (required a cast/assertion — `item` was typed `undefined`)
+  internalNotes: text({
+    access: {
+      read: ({ item, session }) => item!.ownerId === session?.userId,
+    } as FieldAccessControl,
+  })
+
+  // After (compiles as written — `item` is typed as the row)
+  internalNotes: text({
+    access: { read: ({ item, session }) => item.ownerId === session?.userId },
+  })
+  ```
+
+  `FieldAccess['read']` now accepts only the single `operation: 'read'` call shape (rather than the full `read | create | update` union `FieldAccess['create']`/`FieldAccess['update']` still accept), so a rule written for the `read` slot never needs to narrow on `operation` to use `item`. The `create` branch — where there genuinely is no row yet — is unchanged.
+
+### Patch Changes
+
+- [#947](https://github.com/OpenSaasAU/stack/pull/947) [`5f00c3a`](https://github.com/OpenSaasAU/stack/commit/5f00c3a456295a1125281a4227309a8f8c6d853d) Thanks [@borisno2](https://github.com/borisno2)! - Clean up comments across `access/`, `config/`, `fields/`, `filter/`, `hooks/`, `lib/`, `mcp/`, `query/`, `utils/` and `validation/` per the CLAUDE.md Comments rule. No behavior changes.
+
+- [#946](https://github.com/OpenSaasAU/stack/pull/946) [`4d8b654`](https://github.com/OpenSaasAU/stack/commit/4d8b654d099ce13d00893ebc4ce904fa69f2c47a) Thanks [@borisno2](https://github.com/borisno2)! - Restore two comments in `src/context/` that were trimmed too far in a prior comment cleanup ([#945](https://github.com/OpenSaasAU/stack/issues/945)). No behavior changes.
+
+- [#920](https://github.com/OpenSaasAU/stack/pull/920) [`e0baadd`](https://github.com/OpenSaasAU/stack/commit/e0baaddade059cfea639d232f6953fc8c339f6f4) Thanks [@borisno2](https://github.com/borisno2)! - `findMany`/`count` now reject an undeclared `where`/`orderBy` key (including nested inside `AND`/`OR`/`NOT` or a relation filter), closing the same back-relation surface [#564](https://github.com/OpenSaasAU/stack/issues/564) closed on writes. `sudo` still bypasses.
+
+- [#945](https://github.com/OpenSaasAU/stack/pull/945) [`ab4a5dd`](https://github.com/OpenSaasAU/stack/commit/ab4a5ddd83eebcf85d4a98f210cd378b974725f5) Thanks [@borisno2](https://github.com/borisno2)! - Clean up comments in `src/context/` per the CLAUDE.md Comments rule. No behavior changes.
+
+- [#929](https://github.com/OpenSaasAU/stack/pull/929) [`94802ee`](https://github.com/OpenSaasAU/stack/commit/94802eee3b2fdc64fab4b576945820a6df9311c5) Thanks [@borisno2](https://github.com/borisno2)! - Fix: a relation filter in `where` (`some`/`every`/`none`/`is`/`isNot`) no longer bypasses the related list's `query` access — it is now scoped exactly like `include` already is, recursing through every hop of a chain, on both `findMany` and `count`. A filter through a related list that denies query access now throws `RelationFilterAccessDeniedError` instead of silently running unscoped; field-level `read` access on the related list also now applies to keys named inside the filter. `@opensaas/stack-ui`'s admin list view no longer needs its own relationship label-filter access fold, since the engine now covers it.
+
+- [#931](https://github.com/OpenSaasAU/stack/pull/931) [`114302b`](https://github.com/OpenSaasAU/stack/commit/114302b95129484fadb6a1a640435ab1a5d2d102) Thanks [@borisno2](https://github.com/borisno2)! - Correct `ListIndex`/`db.indexes` doc comments, which wrongly claimed an entry must span two or more fields — a single-field entry is fully supported and now documented as such.
+
+## 0.38.0
+
+### Minor Changes
+
+- [#873](https://github.com/OpenSaasAU/stack/pull/873) [`b21d8b2`](https://github.com/OpenSaasAU/stack/commit/b21d8b2af43f7a2a7ea10a89cfb39140a856bd68) Thanks [@borisno2](https://github.com/borisno2)! - Naming a relation in an `include` now fetches only that relation's own columns and stops, at every level — not just the root. This completes ADR-0024 (a bare read fetches scalars, never relations): reaching a relation's own relations means naming them too, e.g. `include: { author: { include: { organization: true } } }` rather than relying on `include: { author: true }` to pull `organization` in automatically. A relation nobody named (caller `include`, fragment `query`, or a field's `needs`) never has its list's operation-level `query` access evaluated at all.
+
+  **This is a silent break — detect it before you upgrade.** An `include` that named a relation bare and read past it (`item.<named>[0].<unnamed>`) now gets `undefined` for the unnamed part, with no error. Grep your codebase for `include: {` calls whose consumers read a second hop off a bare-named relation, and add the deeper relation explicitly:
+
+  ```typescript
+  // Before: relied on `author` auto-expanding its own `organization` relation
+  const post = await context.db.post.findUnique({
+    where: { id },
+    include: { author: true },
+  })
+  post.author.organization // silently undefined now
+
+  // After: name the relation you actually need
+  const post = await context.db.post.findUnique({
+    where: { id },
+    include: { author: { include: { organization: true } } },
+  })
+  post.author.organization // present
+  ```
+
+  `AccessScopeDepthExceededError` (thrown when an `include` names a relation past `READ_INCLUDE_MAX_DEPTH`) keeps its type, fields, and throw sites — only its message wording changed, from describing an inability to scope to describing a cost refusal, since the depth cap is now a cost limit rather than a security boundary (nothing walks the relationship graph unprompted anymore).
+
+- [#890](https://github.com/OpenSaasAU/stack/pull/890) [`17eb72f`](https://github.com/OpenSaasAU/stack/commit/17eb72f0a9a4b7508e3f318da66bb8d4c6cbd705) Thanks [@list({](https://github.com/list({)! - A computed field — any field carrying a `resolveOutput` hook, virtual or not — is now computed if and only if a read is actually going to return it. A fragment `query` that selects three fields no longer runs every `resolveOutput` on the list and discards the rest: an unselected field's field-level read access is never evaluated and its hook never runs. Its declared relations (`needs`, ADR-0025) are fetched under exactly the same condition, folded recursively at every nesting level — a nested fragment selecting a subset computes only that subset, while a nested `include` still computes every computed field at that level, matching bare and `include`-based reads, which are unaffected: they still compute every computed field on the list, exactly as before. See ADR-0027.
+
+  **This is a silent break — detect it before you upgrade, the same way ADR-0024's and ADR-0026's were.** Two independent behaviors changed with no thrown error:
+
+  1. **A hook's `item` never carries another computed field's resolved output, on any read path.** Previously a virtual field received the already-assembled, already-resolved object, so a virtual field could read an _earlier-declared_ virtual (or any field carrying its own `resolveOutput`, e.g. a `password()`'s wrapper or a formatted display field) and see its resolved value — working only by declaration order, with reordering two fields silently changing the result. Now every computed field's hook sees only the row's stored columns and its own declared dependencies; reaching for a sibling that is itself computed finds nothing there (or its raw stored form, never the wrapped/resolved value), the same as reaching for a field that was never declared. **Grep your config for a `resolveOutput` whose `item` reads a field that is itself computed** — virtual fields reading other virtual fields, or a hook reading a stored field that carries its own `resolveOutput` (a password wrapper, a formatted date) — and recompute from the shared stored columns instead of relying on another field's hook having already run.
+  2. **A field's hook no longer runs just because it's on the list — only because a read selects it.** If you relied on a `resolveOutput` hook running for a side effect (logging, cache warming) on every read regardless of a fragment's own field selection, that side effect now only fires when the fragment actually names the field. **Grep for a fragment `query` that intentionally omits a field whose hook you were relying on for a side effect**, and select that field explicitly (or move the side effect to a hook that isn't projection-gated, e.g. `afterOperation`).
+
+  A hookless virtual field (one with `access.read` but no `resolveOutput`) no longer has its read access evaluated at all on any read — such a field can never produce output, so under this rule it does no work at all.
+
+  ```typescript
+  // Before: `displayName` (declared after `fullNameCached`) could read the
+  // latter's resolved value purely because of declaration order.
+
+    fields: {
+      firstName: text(),
+      lastName: text(),
+      fullNameCached: virtual({
+        type: 'string',
+        hooks: { resolveOutput: ({ item }) => `${item.firstName} ${item.lastName}` },
+      }),
+      displayName: virtual({
+        type: 'string',
+        // item.fullNameCached is now always undefined here — recompute from
+        // the shared stored columns instead.
+        hooks: { resolveOutput: ({ item }) => `${item.fullNameCached} (${item.firstName[0]}.)` },
+      }),
+    },
+  })
+
+  // After: compute from the stored columns both fields actually share.
+  displayName: virtual({
+    type: 'string',
+    hooks: {
+      resolveOutput: ({ item }) => `${item.firstName} ${item.lastName} (${item.firstName[0]}.)`,
+    },
+  }),
+  ```
+
+### Patch Changes
+
+- [#873](https://github.com/OpenSaasAU/stack/pull/873) [`b21d8b2`](https://github.com/OpenSaasAU/stack/commit/b21d8b2af43f7a2a7ea10a89cfb39140a856bd68) Thanks [@borisno2](https://github.com/borisno2)! - Fix `needs` declarations being dropped beneath a caller-named relation that revisits a list (e.g. `include: { author: { include: { posts: true } } }`, or a self-referential `parent`), which left the revisited list's computed fields resolving over `undefined`.
+
 ## 0.37.0
 
 ### Minor Changes

package/CLAUDE.md

@@ -170,6 +170,27 @@ Key points:
 - If the client cannot open an interactive transaction (e.g. a test mock, or you
   are already inside one), `fn` runs directly with identical hook/access
   semantics. See ADR-0012.
+- **A transaction-boundary `afterTransaction` reports the OUTERMOST transaction,
+  not its own write's return (ADR-0028).** A write nested in `context.transaction()`
+  (or a hook's own `context.db` write) cannot itself observe when the enclosing
+  transaction settles, so its `afterTransaction` is deferred until the owner —
+  `context.transaction()`, or the Write Pipeline when it opened the transaction —
+  observes the real commit/rollback. `beforeTransaction` stays eager in every
+  case, so under `context.transaction()` it runs with that transaction already
+  open (keep it fast; a `context.db` write from it can block on rows the
+  transaction itself is writing). Status is a conjunction — `committed` iff the
+  write itself succeeded AND the enclosing transaction committed, the write's
+  own error always winning otherwise — and the deferred `item` is the row as
+  that write persisted it, not re-read at flush (so a later same-record write in
+  the same transaction leaves it stale). Because of this, a **rejected
+  `context.transaction()` no longer implies rollback**: a deferred hook that
+  throws after a successful commit rejects the call with `AfterTransactionError`
+  over already-final data, though a transaction/serialization error (e.g.
+  `P2034`) still takes precedence and propagates unwrapped. A write with no
+  transaction owner at all (an app-managed `prisma.$transaction`, or a client —
+  e.g. a bare test mock — that cannot open one) still fires `afterTransaction`
+  optimistically at write time, unchanged. See ADR-0028 and the hooks concept
+  doc.
 
 ### Generators (`src/generator/`)
 
@@ -249,7 +270,25 @@ Reads run no `afterOperation` (list or field):
 
 ### A Bare Read Fetches Scalars, Not Relations (ADR-0024)
 
-A read with no `include` and no fragment `query` returns the row's own columns plus its virtual fields — **never relations** — matching Prisma's own default. `findUnique`, `findMany`, and a singleton's `get()` all follow this rule uniformly, under sudo and under a session alike. Relations are fetched only when a caller names them via `include` or a fragment `query`, at which point the existing merge-with-access-control path (`mergeIncludeWithAccessControl`) applies exactly as before (#566/#830 unaffected). Foreign-key columns (e.g. `authorId`) are unaffected and always returned, so a relation stays reachable by id without an `include`. A `resolveOutput` hook that issues its own bare `context.db` read is subject to the same rule — reading `item.<relation>` inside such a hook silently returns `undefined` unless the hook's own read names that relation. See `docs/adr/0024-a-read-with-no-include-fetches-scalars-not-relations.md`.
+A read with no `include` and no fragment `query` returns the row's own columns plus its virtual fields — **never relations** — matching Prisma's own default. `findUnique`, `findMany`, and a singleton's `get()` all follow this rule uniformly, under sudo and under a session alike. Relations are fetched only when a caller names them via `include` or a fragment `query`, at which point the caller-directed access-scoping walk (`buildAccessScopedInclude`, ADR-0026) applies (#566/#830 unaffected). Foreign-key columns (e.g. `authorId`) are unaffected and always returned, so a relation stays reachable by id without an `include`. A `resolveOutput` hook that issues its own bare `context.db` read is subject to the same rule — reading `item.<relation>` inside such a hook silently returns `undefined` unless the hook's own read names that relation. See `docs/adr/0024-a-read-with-no-include-fetches-scalars-not-relations.md`.
+
+### Naming a Relation Fetches Its Columns, Not Its Subtree (ADR-0026)
+
+The bare-read rule above applies at **every level**, not only the root: naming a relation in an `include` fetches that relation's own columns and stops — its own further relations are returned only if the request nests an `include` for them too. `include: { author: true }` returns `author`'s scalar columns; reaching `author.organization` means writing `include: { author: { include: { organization: true } } }`. This is the "One hop" rule (see the glossary entry in `CONTEXT.md`).
+
+The read pipeline is **caller-directed**: `buildAccessScopedInclude` walks only the branches a request (a caller `include`, a fragment `query`'s projection, or a field's folded `needs`) itself names, and never evaluates a related list's operation-level `query` access for a relation nobody asked for. There is no separate "build the full access-scoped tree for the whole list, then reconcile against what was requested" pass — the old `buildIncludeWithAccessControl` + `mergeIncludeWithAccessControl` two-step this replaced. `READ_INCLUDE_MAX_DEPTH` is a cost limit on how deep a request may reach, not a security boundary: nothing walks the relationship graph unprompted anymore, so there is no unscoped subtree left to fail open on past the cap — a request naming a relation at or beyond the cap still throws `AccessScopeDepthExceededError` (ADR-0022), now worded as a cost refusal rather than a scoping failure.
+
+**Migration note (silent break):** an `include` that named a relation bare and read past it one hop (`item.<named>[0].<unnamed>`) now gets `undefined` for the unnamed part — no error. Grep for caller includes whose consumers read past the relation actually named, and add the deeper relation explicitly to the `include`.
+
+A computed field's declared dependency (`needs`, ADR-0025, below) folds in at **every** relation it's reached through, including one added purely to satisfy another field's own `needs` — the fold recurses through `foldDeclaredDependencies` rather than riding a caller-named relation's auto-expanded subtree, since nothing auto-expands anymore. See `docs/adr/0026-naming-a-relation-fetches-its-columns-not-its-subtree.md`.
+
+### A Computed Field Runs Only When It Is Going To Be Returned (ADR-0027)
+
+A computed field — any field carrying a `resolveOutput` hook, virtual or not — is computed **if and only if the read is actually going to return it**, and its declared relations (`needs`) are fetched under exactly the same condition. A fragment `query` selecting three fields runs only those three fields' hooks (and folds only their `needs`); a field it doesn't select does no work at all — neither its field-level `read` access nor its hook runs. This is **projection-aware, never access-aware**: a fragment's own field selection is the only thing that restricts a level this way. A bare read or an `include`-based read is unaffected — every computed field on the list still computes, exactly as before, since neither ever had a narrower field selection to restrict by. The rule applies at every nesting level: a nested fragment selecting a subset computes only that subset there; a nested `include` still computes every computed field at that level.
+
+**A computed field's hook never sees another computed field's resolved output**, on any read path — only the row's stored columns and its own declared dependencies. A sibling field that was skipped (unselected by a fragment) or denied by field-level access is absent from what the hook sees, never present holding its raw pre-hook value — reaching for it finds nothing there, the same as reaching for a relation never declared via `needs`. Before this, a virtual field received the already-assembled, already-resolved object, so a virtual field could accidentally read an earlier-declared virtual's resolved value purely by declaration order; reordering two such fields silently changed the result. That accidental coupling is gone: recompute from the stored columns both fields share instead.
+
+A hookless virtual field (one with `access.read` but no `resolveOutput`) has its read access evaluated on no read at all — such a field can never produce output, so there's nothing to preserve access side effects for. See `docs/adr/0027-a-computed-field-runs-only-when-it-is-going-to-be-returned.md` and the "Computed field" glossary entry in `CONTEXT.md`.
 
 ### Context Type Safety
 
@@ -402,13 +441,13 @@ User: list({
 
 // Usage
 const user = await context.db.user.findUnique({ where: { id } })
-console.log(user.fullName) // "John Doe" — computed via resolveOutput on every read
+console.log(user.fullName) // "John Doe" — computed via resolveOutput whenever the read returns it
 ```
 
 **Key characteristics:**
 
 - Not stored in database (no Prisma column created)
-- Computed via `resolveOutput` on every read (`select` is not honoured — narrow with `include`/fragment `query`)
+- Computed via `resolveOutput` on every bare/`include`-based read; on a fragment `query` read, only when the fragment selects it (ADR-0027) — `select` is still not honoured, narrow with `include`/fragment `query`
 - Must provide `type` (TypeScript type string) and `resolveOutput` hook
 - Can optionally provide `resolveInput` for write side effects
 - Useful for derived values, computed properties, and external API sync

package/dist/access/access-filter.d.ts

@@ -1,125 +1,83 @@
-import type { Session, AccessContext, PrismaFilter } from './types.js';
-import type { OpenSaasConfig, FieldConfig } from '../config/types.js';
+import type { Session, AccessContext } from './types.js';
+import type { OpenSaasConfig, FieldConfig, ListConfig } from '../config/types.js';
 /**
- * Access Filter — phase 1 of the two-phase read (pre-query).
+ * Build the access-scoped `include` for exactly the relations a read
+ * requested, recursing only into branches `requestedInclude` itself names.
  *
- * This module scopes which rows and relationships the database is allowed to
- * return, before the query runs. It evaluates *operation-level* `query` access
- * on related lists and turns the results into a Prisma `include`/`where` clause,
- * so denied rows and relations never leave the database.
+ * For each key in `requestedInclude`:
+ * - Not a config-declared relationship → access control does not govern it;
+ *   passed through unchanged (e.g. a fragment/caller key that isn't a
+ *   relationship at all).
+ * - A declared relationship whose related list's `query` access denies it
+ *   (`=== false`) → dropped entirely, no matter what the request asked for
+ *   nested beneath it (#566): the caller chooses *which* relations, access
+ *   control chooses *whether* and *with what filter*.
+ * - Otherwise → the access `where` is AND-combined with any caller-supplied
+ *   nested `where` (never replaced — the other half of #566), a
+ *   caller-supplied `take` rides through unchanged (#752), and — the "One
+ *   hop" rule (ADR-0026) — nested relations are scoped ONLY if
+ *   `requestedInclude` itself named a nested `include` here. A bare relation
+ *   (or one with no nested `include`) fetches its own columns and stops: no
+ *   recursive call, no access evaluation on anything beneath it.
  *
- * Phase 2 (post-query field stripping + `resolveOutput` + virtual computation)
- * lives in `field-visibility.ts`. The two phases cannot be merged: virtual
- * fields are computed in JavaScript and post-query field access can depend on
- * the fetched row, neither of which is expressible in SQL. See
- * `docs/adr/0001-access-control-is-a-two-phase-read.md` and the access-control
- * glossary in `CONTEXT.md`.
+ * **Depth is a cost limit, not a cycle guard (ADR-0026).** A `requestedInclude`
+ * is always a finite literal — the caller's own object, or
+ * `foldDeclaredDependencies`'s already-cycle-guarded fold — so this recursion
+ * cannot loop unboundedly on its own; nothing here walks the relationship
+ * graph unprompted. `READ_INCLUDE_MAX_DEPTH` still bounds how deep a request
+ * may reach, fail-closed per ADR-0022: a request naming anything at or past
+ * the cap throws `AccessScopeDepthExceededError` rather than silently
+ * returning less than what was asked for.
  */
-/** A single relation entry in a Prisma `include` object (see below). */
-type IncludeEntry = boolean | {
-    where?: PrismaFilter;
-    include?: IncludeObject;
-    take?: number;
-};
-type IncludeObject = Record<string, IncludeEntry>;
-/**
- * The result of trying to compute an access-controlled include for a list's
- * fields. `buildIncludeWithAccessControl` used to collapse three unrelated
- * outcomes into a single overloaded `undefined`: "inside a resolveOutput
- * context", "hit the depth cap", and "no relationships to scope" all looked
- * identical to callers, which is what let a depth-capped relation pass
- * through unscoped (issue #830). This discriminated result keeps them
- * distinguishable all the way to `mergeIncludeWithAccessControl`, which is the
- * only place that knows whether a caller actually asked for the part that
- * couldn't be scoped.
- *
- * - `scoped`: relationships were found and (to the extent depth allows)
- *   access-controlled; `include` is the resulting tree.
- * - `nothing-to-scope`: the list genuinely has no relationships to scope, OR
- *   we are inside a resolveOutput/virtual-field context and deliberately did
- *   not descend into a relation's own nested relations. Passing the caller's
- *   include through unchanged here is correct, not a leak.
- * - `depth-exceeded`: we could not evaluate this level at all because it sits
- *   at or past `READ_INCLUDE_MAX_DEPTH`. This is a denial: a caller `include`
- *   that reaches here must be rejected, not passed through.
- */
-export type AccessIncludeResult = {
-    kind: 'scoped';
-    include: RichIncludeObject;
-} | {
-    kind: 'nothing-to-scope';
-} | {
-    kind: 'depth-exceeded';
-};
-/** A relation entry in the rich, provenance-carrying tree `buildIncludeWithAccessControl` builds internally. */
-type RichIncludeEntry = {
-    where?: PrismaFilter;
-    nested: AccessIncludeResult;
-};
-type RichIncludeObject = Record<string, RichIncludeEntry>;
-/**
- * Collapse an `AccessIncludeResult` to the plain Prisma `include` shape used
- * when there is no caller-supplied include to merge against (the direct
- * auto-include path). `nothing-to-scope` and `depth-exceeded` both become
- * `undefined` here — at this call site nothing was explicitly requested past
- * either boundary, so there is nothing to deny.
- */
-export declare function toPrismaInclude(result: AccessIncludeResult): IncludeObject | undefined;
-/**
- * Build the access-controlled include for a list's fields.
- *
- * This allows us to filter relationships at the database level instead of in
- * memory. Returns an {@link AccessIncludeResult} rather than a plain include
- * object so that `mergeIncludeWithAccessControl` can tell a genuine "nothing
- * to scope" apart from "the engine hit its depth cap" (see that type's doc
- * comment and ADR-0022).
- */
-export declare function buildIncludeWithAccessControl(fieldConfigs: Record<string, FieldConfig>, args: {
+export declare function buildAccessScopedInclude(requestedInclude: Record<string, unknown>, fieldConfigs: Record<string, FieldConfig>, args: {
     session: Session | null;
     context: AccessContext;
-}, config: OpenSaasConfig, depth?: number, visitedLists?: readonly string[]): Promise<AccessIncludeResult>;
+}, config: OpenSaasConfig, listKey: string, depth?: number): Promise<Record<string, unknown>>;
 /**
- * Merge a caller-supplied `include` with the access-controlled include — phase-1
- * row/relation scoping for explicit caller selections.
- *
- * The caller's `include` decides WHICH relations to fetch; access control decides
- * WHETHER each relation may be fetched and WITH WHAT filter. Replacing the
- * access-controlled include with the caller's wholesale (the bug in #566) drops
- * every per-relation access `where` and denied-relation exclusion, silently
- * bypassing row-level access on any non-sudo read that passes `include`.
+ * Scope every relation filter (`some`/`every`/`none`/`is`/`isNot`) nested in a
+ * caller's `where` by the related list's own `query` access — the `where`
+ * counterpart to `buildAccessScopedInclude` above, closing #916 (the
+ * "unclosed half of ADR-0022"). `include` and `where` are fundamentally
+ * different requests (which relations come back, vs. which parent rows
+ * match), so this is a distinct function, but it shares every primitive that
+ * matters: `checkAccess`/`getRelatedListConfig` (the same access-evaluation
+ * calls `buildAccessScopedInclude` makes), `andWhere` (the same AND-fold), and
+ * `resolveQueryField`/`LOGICAL_OPERATORS`/`RELATION_QUANTIFIERS`/
+ * `walkWhereReadAccess` (the same shape-recognition and field-read check
+ * `query-validation.ts` already uses for #912/#915) — there is no second,
+ * parallel implementation of any of those decisions.
  *
- * For each relation the caller asks to include:
- * - If the relation is a config-declared relationship but is ABSENT from the
- *   access-controlled include, its `query` access returned `false` → it is DROPPED
- *   (not fetched).
- * - If it is present (allowed, possibly with a filter), the access entry is used
- *   as the base: the access `where` is AND-combined with any caller-supplied
- *   nested `where`, and nested includes are recursively merged using the related
- *   list's field configs (so deeply-nested selections are filtered at every
- *   level). A bare caller `true` becomes the access-controlled shape (filter +
- *   nested filtered include), never bare `true`.
- * - If the caller names a key that is NOT a config-declared relationship, it is
- *   passed through unchanged (access control does not govern it).
+ * For each relationship key found (at any depth — the walk recurses through
+ * `AND`/`OR`/`NOT` and through every hop of a chain):
+ * - Not a declared relationship, or the key #912 already rejected (this walk
+ *   runs strictly after that check) → passed through unchanged.
+ * - The related list's `query` access denies it (`=== false`) → THROWS
+ *   `RelationFilterAccessDeniedError`. Unlike `buildAccessScopedInclude`'s
+ *   silent drop, this is a loud failure: a `where` predicate has no neutral
+ *   "not requested" outcome the way a missing `include` key does, so a
+ *   silently-empty match would itself be a distinguishable signal (ADR-0022).
+ * - Otherwise → the access filter (if any) is AND-combined into the relation
+ *   quantifier's nested clause (never replacing the caller's own condition,
+ *   mirroring `andWhere`'s include-side contract), keys inside that nested
+ *   clause are checked against the RELATED list's field-level `read` access
+ *   (`walkWhereReadAccess`, closing #915's stated gap for this path), and the
+ *   walk recurses into the related list's own fields for a further hop.
  *
- * `accessControlledInclude` is the {@link AccessIncludeResult} for THIS level:
- * - `nothing-to-scope` → nothing to merge against (the list has no
- *   relationships, or we're inside a resolveOutput context where the caller
- *   include is irrelevant to begin with). Pass the caller's include through
- *   unchanged — this is a non-denial outcome, not "every relation denied".
- * - `depth-exceeded` → the engine could not compute a scope for THIS level at
- *   all because it sits at or past `READ_INCLUDE_MAX_DEPTH`. If the caller
- *   named anything here, that is exactly the case that used to pass through
- *   unscoped (issue #830): throw `AccessScopeDepthExceededError` instead. An
- *   empty caller include at this level (nothing further requested) is not an
- *   error — there's simply nothing to do.
- * - `scoped` → the normal per-relation merge below: a declared relationship
- *   ABSENT from the access include was denied (drop it); one PRESENT is used
- *   as the base, AND-combining `where`s and recursing into nested includes.
- *
- * `listKey` and `depth` are carried only to build a useful
- * `AccessScopeDepthExceededError` message; they do not affect merge behaviour.
+ * One quantifier is deliberately conservative rather than exactly precise:
+ * folding the access filter into `every`'s nested clause with a plain AND
+ * makes `every` require every related row to be BOTH access-visible AND
+ * matching, not "every access-visible row matches" (the latter needs a
+ * `NOT`/`OR` transform this does not attempt). The conservative version can
+ * only reject a query that the precise version would allow — it never
+ * widens what a caller can learn — so it is the safe direction to ship; a
+ * caller can observe that an inaccessible related row exists (an `every`
+ * that "should" pass instead fails), but never that row's field values,
+ * which is the property this ticket exists to close.
  */
-export declare function mergeIncludeWithAccessControl(callerInclude: Record<string, unknown>, accessControlledInclude: AccessIncludeResult, fieldConfigs: Record<string, FieldConfig>, config: OpenSaasConfig, listKey: string, depth?: number): Record<string, unknown>;
+export declare function buildAccessScopedWhere(where: unknown, listConfig: ListConfig<any>, listName: string, config: OpenSaasConfig, args: {
+    session: Session | null;
+    context: AccessContext;
+}): Promise<unknown>;
 /**
  * Remove keys that correspond to `virtual` fields from a Prisma `include`
  * object, recursing into nested relationship includes using the related
@@ -137,5 +95,4 @@ export declare function mergeIncludeWithAccessControl(callerInclude: Record<stri
  * no effect on whether the value appears in the result (#628).
  */
 export declare function stripVirtualFieldsFromInclude(include: Record<string, unknown> | undefined, fieldConfigs: Record<string, FieldConfig>, config: OpenSaasConfig): Record<string, unknown> | undefined;
-export {};
 //# sourceMappingURL=access-filter.d.ts.map

package/dist/access/access-filter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"access-filter.d.ts","sourceRoot":"","sources":["../../src/access/access-filter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAKrE;;;;;;;;;;;;;;GAcG;AAEH,wEAAwE;AACxE,KAAK,YAAY,GAAG,OAAO,GAAG;IAAE,KAAK,CAAC,EAAE,YAAY,CAAC;IAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAC9F,KAAK,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;AAEjD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,mBAAmB,GAC3B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,iBAAiB,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,kBAAkB,CAAA;CAAE,GAC5B;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,CAAA;AAE9B,gHAAgH;AAChH,KAAK,gBAAgB,GAAG;IAAE,KAAK,CAAC,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAA;CAAE,CAAA;AAC7E,KAAK,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;AAqBzD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,mBAAmB,GAAG,aAAa,GAAG,SAAS,CAOtF;AAED;;;;;;;;GAQG;AACH,wBAAsB,6BAA6B,CACjD,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACzC,IAAI,EAAE;IACJ,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;IACvB,OAAO,EAAE,aAAa,CAAA;CACvB,EACD,MAAM,EAAE,cAAc,EACtB,KAAK,GAAE,MAAU,EAIjB,YAAY,GAAE,SAAS,MAAM,EAAO,GACnC,OAAO,CAAC,mBAAmB,CAAC,CAwE9B;AAiDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,6BAA6B,CAC3C,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACtC,uBAAuB,EAAE,mBAAmB,EAC5C,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACzC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,MAAM,EACf,KAAK,GAAE,MAAU,GAChB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA2EzB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC5C,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACzC,MAAM,EAAE,cAAc,GACrB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAgCrC"}
+{"version":3,"file":"access-filter.d.ts","sourceRoot":"","sources":["../../src/access/access-filter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAgB,MAAM,YAAY,CAAA;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAkFjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,wBAAwB,CAC5C,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACzC,IAAI,EAAE;IACJ,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;IACvB,OAAO,EAAE,aAAa,CAAA;CACvB,EACD,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,MAAM,EACf,KAAK,GAAE,MAAU,GAChB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAwDlC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,OAAO,EAEd,UAAU,EAAE,UAAU,CAAC,GAAG,CAAC,EAC3B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE;IACJ,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;IACvB,OAAO,EAAE,aAAa,CAAA;CACvB,GACA,OAAO,CAAC,OAAO,CAAC,CA0FlB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC5C,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACzC,MAAM,EAAE,cAAc,GACrB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CA+BrC"}