@opensaas/stack-core 0.39.2 → 0.41.0

package/.turbo/turbo-build.log

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

package/CHANGELOG.md

@@ -1,5 +1,194 @@
 # @opensaas/stack-core
 
+## 0.41.0
+
+### Minor Changes
+
+- [#1179](https://github.com/OpenSaasAU/stack/pull/1179) [`67dce2e`](https://github.com/OpenSaasAU/stack/commit/67dce2e9d96afdc5c69f0a2f1c8b395346d4e942) Thanks [@borisno2](https://github.com/borisno2)! - A list/field `resolveInput` / `validate` / `beforeOperation` / `afterOperation` hook's `context` is now a full secured context — `sudo()`, `withSession()`, `transaction()` and `serverAction` — bound to the write's OWN transaction client, exactly like the `txContext` a `context.transaction()` callback receives.
+
+  ```typescript
+  Order: list({
+    hooks: {
+      beforeOperation: async ({ context }) => {
+        // Elevated AND atomic with this write — rolls back together if it throws.
+        await context.sudo().db.auditLog.create({ data: { action: 'order-write' } })
+      },
+    },
+  })
+  ```
+
+  Previously this `context` had no `sudo()`/`withSession()`/`transaction()` at all, forcing a workaround (`getContext(session).sudo()`) that opened a SEPARATE connection from the write's transaction — its writes could survive a rollback, and it could deadlock on a single-connection adapter. `context.transaction()` called from inside one of these hooks now joins the write's transaction rather than opening a nested one. `beforeTransaction`/`afterTransaction` are unaffected — they keep the plain access-checked context bound to the base client, always. A field's `resolveOutput` keeps the same context type as before; which client it's bound to already depended on how the read arose (a plain read: the base client; a create/update's own Field Visibility pass: that write's transaction client), unchanged by this release.
+
+### Patch Changes
+
+- [#1108](https://github.com/OpenSaasAU/stack/pull/1108) [`2260539`](https://github.com/OpenSaasAU/stack/commit/2260539c5488dae0ee6e7f86ccd913e5c898ccdb) Thanks [@borisno2](https://github.com/borisno2)! - Fix: a relation quantifier (`some`/`every`/`none`/`is`/`isNot`) nested inside an `include` entry's own `where` is now scoped by the deeper related list's `query` access and field-read access too, reusing `buildAccessScopedWhere` ([#916](https://github.com/OpenSaasAU/stack/issues/916)) — closing a residual probing-oracle gap in [#1092](https://github.com/OpenSaasAU/stack/issues/1092)'s fix.
+
+- [#1102](https://github.com/OpenSaasAU/stack/pull/1102) [`aa34cca`](https://github.com/OpenSaasAU/stack/commit/aa34cca65877759b9625da1538c65c53ed54385a) Thanks [@borisno2](https://github.com/borisno2)! - Fix: a `where`/`orderBy` nested inside a caller's `include` entry now validates against the related list's config, closing a probing oracle over undeclared or read-denied fields one hop into a relation ([#1092](https://github.com/OpenSaasAU/stack/issues/1092)).
+
+- [#1041](https://github.com/OpenSaasAU/stack/pull/1041) [`182153c`](https://github.com/OpenSaasAU/stack/commit/182153cb976b14ef67673d0eeef7925d950bfa10) Thanks [@borisno2](https://github.com/borisno2)! - Upgrade Prisma packages to `^7.9.1`, keeping the CLI, client, and driver adapters on the same release. Scaffolded PostgreSQL projects now pin `@prisma/adapter-pg` to `^7.9.1`.
+
+- [#1101](https://github.com/OpenSaasAU/stack/pull/1101) [`682795f`](https://github.com/OpenSaasAU/stack/commit/682795f7c7f0d0194ffd08e993d452c368bcd847) Thanks [@borisno2](https://github.com/borisno2)! - Fix a query fragment read (`{ query: fragment }`) skipping the Access Filter's scoping walk, so a related list's `query` access, row filters, and the read-include depth cap were never enforced. Fragment reads may now return fewer related rows — those rows were never authorised.
+
+- [#1110](https://github.com/OpenSaasAU/stack/pull/1110) [`73d1b6a`](https://github.com/OpenSaasAU/stack/commit/73d1b6aba9a9b789a8111105d56257a1de66a883) Thanks [@borisno2](https://github.com/borisno2)! - A caller-supplied `_count` in `include` is now scoped by each named relation's own `query` access (a row filter is folded into the count, a fully denied relation counts `0`), closing a cardinality leak where counts previously reached the caller unscoped.
+
+- [#1091](https://github.com/OpenSaasAU/stack/pull/1091) [`f1e8792`](https://github.com/OpenSaasAU/stack/commit/f1e8792ce580d92a5874599dfb8a8ccde4d6c8b3) Thanks [@borisno2](https://github.com/borisno2)! - Fix a read naming a list-only ref's synthetic back-relation (`from_<List>_<field>`) in `include`: it now resolves to the declared relationship it stands for and is scoped by that list's `query` access, its field-level `read` gates, and its virtual fields — instead of being returned unscoped. An `include` key that resolves to neither a declared relationship, a synthetic back-relation, nor `_count` is now rejected rather than silently passed through. Responses will shrink for callers relying on either gap — the extra rows and fields they received were never authorised.
+
+- [#1120](https://github.com/OpenSaasAU/stack/pull/1120) [`9eb7c77`](https://github.com/OpenSaasAU/stack/commit/9eb7c7766d212e92b02d53a1ba3aaead4faf1496) Thanks [@borisno2](https://github.com/borisno2)! - Fix `_count` ignoring a relationship's field-level `read` access, letting the true count of a hidden relationship leak through both the admin list view and a caller-supplied `_count`.
+
+- [#1090](https://github.com/OpenSaasAU/stack/pull/1090) [`5b478de`](https://github.com/OpenSaasAU/stack/commit/5b478de64f3564d837d2f9f912972e49008be884) Thanks [@borisno2](https://github.com/borisno2)! - Fix nested update/delete (e.g. `post.update({ data: { author: { update: {...} } } })`) silently treating a Prisma filter returned by the target list's `update`/`delete` access as an unconditional allow. It is now re-checked against the target row in the database, matching top-level write behavior.
+
+- [#1115](https://github.com/OpenSaasAU/stack/pull/1115) [`d335122`](https://github.com/OpenSaasAU/stack/commit/d335122323b3402c0838aa50873fab0c085fbb01) Thanks [@borisno2](https://github.com/borisno2)! - Fix a denied to-many relation coming back `undefined` instead of `[]` on both the caller-`include:` and fragment `query` read paths.
+
+## 0.40.0
+
+### Minor Changes
+
+- [#1020](https://github.com/OpenSaasAU/stack/pull/1020) [`8e6707a`](https://github.com/OpenSaasAU/stack/commit/8e6707adcca9d7e062bc1747ec79a29082c09ef9) Thanks [@borisno2](https://github.com/borisno2)! - Add `ui.listView.defaultColumn` to field config — a declared, presentation-only flag (default `true`) controlling whether a field belongs in a list/related-list table's default column set. Naming a field explicitly in `ui.listView.initialColumns` or a relationship's `ui.itemView.columns` always shows it regardless of this flag.
+
+  ```typescript
+  fields: {
+    internalScore: integer({ ui: { listView: { defaultColumn: false } } }),
+  }
+  ```
+
+  `password()` now sets this flag to `false` by default instead of the admin UI matching on field type — a password field can opt back into default columns with `ui: { listView: { defaultColumn: true } } }`.
+
+- [#1011](https://github.com/OpenSaasAU/stack/pull/1011) [`afd1a60`](https://github.com/OpenSaasAU/stack/commit/afd1a60a6ddaa558bf14887e45fa1c007e6669b0) Thanks [@borisno2](https://github.com/borisno2)! - `OperationAccess.create` now throws `InvalidCreateAccessResultError` when the rule returns anything other than `true`/`false` — most notably a Prisma filter, which previously fell through the `create` access check unrecognised and was silently treated as a full allow (both the top-level write pipeline and nested-create paths were affected).
+
+  Create has no existing row to scope a filter against, so a filter can no longer be honoured here:
+
+  ```typescript
+  // Before: type-checked, read as row-scoped, actually allowed everyone
+  create: ({ session }) => ({ ownerId: { equals: session.userId } })
+
+  // Now throws InvalidCreateAccessResultError. Scope ownership in a hook instead:
+  hooks: {
+    resolveInput: async ({ resolvedData, context, operation }) => {
+      if (operation === 'create') {
+        return { ...resolvedData, ownerId: context.session?.userId }
+      }
+      return resolvedData
+    },
+  },
+  access: {
+    operation: {
+      create: ({ session }) => !!session, // boolean only
+    },
+  },
+  ```
+
+  `create: () => false` still denies via Silent failure as before; only a non-boolean result now throws.
+
+- [#984](https://github.com/OpenSaasAU/stack/pull/984) [`51ae299`](https://github.com/OpenSaasAU/stack/commit/51ae299b7624f97e890f85b3075c62d8e114cec2) Thanks [@borisno2](https://github.com/borisno2)! - Extend `isIndexed` to `integer`, `timestamp`, and `select`, matching `text`, `decimal`, `bigInt`, `calendarDay`, and `relationship`.
+
+  ```typescript
+  fields: {
+    rank: integer({ isIndexed: true }),
+    publishedAt: timestamp({ isIndexed: true }),
+    status: select({
+      options: [{ label: 'Draft', value: 'draft' }],
+      isIndexed: 'unique',
+    }),
+  }
+  ```
+
+  `isIndexed: true` generates a block-level `@@index([field])`; `isIndexed: 'unique'` generates an inline `@unique`. `select` supports both under the default string column and a native-enum column (`db: { type: 'enum' }`). No field type's default indexing behavior changes — an existing config generates the same schema as before.
+
+- [#1007](https://github.com/OpenSaasAU/stack/pull/1007) [`4ce64b4`](https://github.com/OpenSaasAU/stack/commit/4ce64b4f9868eca0f34cc0676e46440b3d8f16ce) Thanks [@borisno2](https://github.com/borisno2)! - The derived MCP `query` tool now accepts an optional `fields` projection — the wire form of the runtime's existing fragment field selection — so an assistant can select scalars and nested relation fields (with `where`/`orderBy`/`take`/`skip`, and a to-many's row count) in a single call instead of following a foreign key with a second one. Omitting `fields` is unchanged, a bare read exactly as before.
+
+  ```json
+  {
+    "name": "list_post_query",
+    "arguments": {
+      "fields": {
+        "title": true,
+        "author": { "fields": { "name": true } },
+        "comments": {
+          "fields": { "text": true },
+          "where": { "approved": { "equals": true } },
+          "take": 5,
+          "count": true
+        }
+      }
+    }
+  }
+  ```
+
+  The generated tool schema enumerates two levels of each list's own fields and relations, per session, and refuses (as an `isError` tool result, never a protocol error) anything it doesn't advertise — an unknown field, or a relation named a third level deep. See the ADR (`docs/adr/0033-mcp-tools-advertise-a-bounded-projection.md`) for the full design.
+
+  **Behaviour change:** `tools/list` is now evaluated per session. A list whose operation-level `query` access denies the session outright no longer appears in the tool listing at all — none of its four CRUD tools, and no relation entry elsewhere pointing at it. Previously every list's tools were listed regardless of session.
+
+- [#1002](https://github.com/OpenSaasAU/stack/pull/1002) [`48d2762`](https://github.com/OpenSaasAU/stack/commit/48d27626dfb636c481301116e46c826ef3156124) Thanks [@borisno2](https://github.com/borisno2)! - Fix admin UI URL round-trip for a list keyed with anything other than strict PascalCase (issue [#991](https://github.com/OpenSaasAU/stack/issues/991)). `getListKeyFromUrl` reconstructs a list key by string transformation, which is lossy for a non-PascalCase key — a real example is a better-auth plugin's derived list (e.g. `oauthApplication`, from the `mcp` plugin's OAuth tables). Such a list appeared in navigation but its own link resolved to a key that did not exist in `config.lists`, rendering "List not found".
+
+  `@opensaas/stack-core` adds `resolveListKeyFromUrl(urlSegment, listKeys)` alongside the existing `getListKeyFromUrl`, which is unchanged and still exported. The new resolver matches a URL segment against the config's actual list keys via `getUrlKey` — the same helper that builds the URL — instead of reconstructing one, so route lookup and URL generation cannot drift apart. It returns `undefined` for a segment matching no list (so callers keep rendering their existing "not found" state), and throws if two distinct list keys would produce the same URL segment.
+
+  ```typescript
+  import { resolveListKeyFromUrl } from '@opensaas/stack-core'
+
+  resolveListKeyFromUrl('oauth-application', Object.keys(config.lists)) // 'oauthApplication'
+  resolveListKeyFromUrl('does-not-exist', Object.keys(config.lists)) // undefined
+  ```
+
+  `@opensaas/stack-ui`'s `AdminUI` now uses `resolveListKeyFromUrl` for its route resolution, fixing the broken link for any such list.
+
+  `@opensaas/stack-auth`'s `convertBetterAuthSchema` now PascalCases a better-auth plugin's camelCase `modelName` when deriving a list key (`oauthApplication` → `OauthApplication`, `rateLimit` → `RateLimit`), matching the repo's PascalCase list-key convention and fixing the same round-trip bug at the source for these lists.
+
+  **Schema-affecting for `@opensaas/stack-auth` users with a better-auth plugin that declares extra tables** (e.g. `mcp`'s OAuth tables, or `rateLimit.storage: 'database'` with no `modelName` remap configured): the generated Prisma **model name** changes to match the new PascalCase list key. The physical **table name** does not change — the previous camelCase name is preserved via `db.map` (`@@map`) — so `prisma db push` / `prisma migrate dev` sees a model rename, not a table rename, and `context.db.oauthApplication` (the camelCase db accessor) keeps working unchanged. Regenerate (`pnpm generate`) and re-run your migration/push step after upgrading.
+
+- [#1003](https://github.com/OpenSaasAU/stack/pull/1003) [`9de43c8`](https://github.com/OpenSaasAU/stack/commit/9de43c80c8ef996dc6f08f68f7c1d8451aa0f10e) Thanks [@borisno2](https://github.com/borisno2)! - Add `context.withSession(session)` — a sibling to `sudo()` for the other axis. It derives a `StackContext` that reuses the receiver's already-resolved config, client (including a transaction client — a call inside `context.transaction()` stays in that transaction), and storage, but carries a substituted session, so access control and hooks run against the new session as normal.
+
+  This closes a gap for callers that are legitimately authorised but arrive without the session a list `validate` hook expects — an unattended dispatcher, a service principal, or a job runner:
+
+  ```typescript
+  // Runs with the job owner's session so hooks see the right identity, while
+  // still going through the normal access control checks for that session.
+  const asOwner = context.withSession(job.ownerSession)
+  await asOwner.db.task.update({ where: { id: job.taskId }, data: { status: 'done' } })
+
+  // Drop to anonymous
+  const anonymous = context.withSession(null)
+  ```
+
+  `withSession` grants no authority of its own — the derived context can do exactly what any context built with that session directly could do. It's orthogonal to `sudo()`: `context.withSession(s).sudo()` and `context.sudo().withSession(s)` are equivalent, since `withSession` preserves the receiver's sudo state instead of resetting it.
+
+  The generated `Context<TSession>` type (`.opensaas/types.ts`) now includes `withSession: (session: TSession | null) => Context<TSession>` alongside `sudo`, so the method is typed in application code — run `opensaas generate` (or `pnpm generate`) to pick it up.
+
+### Patch Changes
+
+- [#1017](https://github.com/OpenSaasAU/stack/pull/1017) [`b30fa61`](https://github.com/OpenSaasAU/stack/commit/b30fa6135a6acca8c9be99fbdf5ffa7faab1959f) Thanks [@{](https://github.com/{)! - Let an application declare model-level indexes (`db.indexes`) on the derived auth lists (`User`/`Session`/`Account`/`Verification`/`RateLimit`).
+
+  Each per-model block in `authPlugin()` now accepts `indexes`, in the same shape as a list's own `db.indexes`:
+
+  ```typescript
+  authPlugin({
+    // Adopt a live constraint's real name instead of Prisma's derived one.
+   indexes: [{ fields: ['email'], unique: true, name: 'user_email_key' }] },
+    session: { indexes: [{ fields: ['token'], unique: true, name: 'session_token_key' }] },
+    // Extend a derived column into a composite index.
+    verification: {
+      indexes: [{ fields: ['identifier', { field: 'createdAt', sort: 'desc' }] }],
+    },
+  })
+  ```
+
+  An entry covering a column the stack already derives an index for (e.g. `User.email`) suppresses that derived index for that column and emits only the app's entry, rather than erroring — the application's declaration wins (ADR-0035). Suppression is per-column: every other derived index on the model is unaffected.
+
+  This also fixes a related generator gap: a list's `db.indexes` can now reference `createdAt`/`updatedAt` even when the list has no explicit field for them and relies on `db.timestamps` for the auto-injected columns (previously only a list with an explicitly declared `createdAt`/`updatedAt` field could be indexed on it).
+
+- [#983](https://github.com/OpenSaasAU/stack/pull/983) [`16da817`](https://github.com/OpenSaasAU/stack/commit/16da8176114826d18d6747d27abedf75de6c3262) Thanks [@borisno2](https://github.com/borisno2)! - Fix `HashedPassword.toJSON()` returning the raw bcrypt hash, so `JSON.stringify` of a row (e.g. a server→client prop, `Response.json()`, an MCP tool response) no longer leaks the stored hash for a `password()` field.
+
+  `toJSON()` now returns `{ isSet: boolean }`, matching the redaction the admin UI already applies via `valueForClientSerialization`. `toString()`, `valueOf()`, `[Symbol.toPrimitive]`, and `==` comparison against the hash are unchanged. If you parse `JSON.stringify`'d rows and read the password field as a string, update that code to read `.isSet` instead — this is a visible output/type change on `HashedPassword.toJSON()`, though the field's read access remains the application's to configure (unchanged).
+
+- [#999](https://github.com/OpenSaasAU/stack/pull/999) [`f85c7d1`](https://github.com/OpenSaasAU/stack/commit/f85c7d1b92e76d5e8ae090f93c0ff94e0d6c36c1) Thanks [@borisno2](https://github.com/borisno2)! - MCP derived CRUD tool and custom tool failures (access denial, thrown engine/database errors, input schema validation) now return a successful JSON-RPC response with `result.isError: true` instead of a JSON-RPC `error` object, so the calling model can see and recover from them. Genuine protocol failures (unknown method, malformed request, unknown tool name) are unchanged. Note: the wire shape of tool failures changes — a consumer asserting on the old `error` shape will need to update.
+
+- [#1006](https://github.com/OpenSaasAU/stack/pull/1006) [`0f2e12a`](https://github.com/OpenSaasAU/stack/commit/0f2e12a69710e759d8749b8536fd5b31836226e9) Thanks [@borisno2](https://github.com/borisno2)! - `relationship({ ref: 'ListName' })` list-only refs now accept `db.foreignKey: { map: '...' }` to rename the foreign key column. The boolean form (`true`/`false`) is still rejected there since ownership is implicit on a list-only ref.
+
+- [#1004](https://github.com/OpenSaasAU/stack/pull/1004) [`05c747a`](https://github.com/OpenSaasAU/stack/commit/05c747a18284ac769860f751a660b72591570571) Thanks [@borisno2](https://github.com/borisno2)! - Fix a nested create/update/delete through a list-only ref's synthetic reverse relation (`from_<List>_<field>`) silently bypassing the target list's hooks and validation. It now runs the same pipeline a declared relationship field's nested write gets. Under `sudo()`, an undeclared key that isn't a synthetic reverse relation is now refused rather than passed through unchecked.
+
+- [#1000](https://github.com/OpenSaasAU/stack/pull/1000) [`0b5b51e`](https://github.com/OpenSaasAU/stack/commit/0b5b51e52787ea9e945206a109a7a56dc38e78e5) Thanks [@borisno2](https://github.com/borisno2)! - Fix `P2002` unique-constraint errors losing per-field detail under Prisma 7 driver adapters (`@prisma/adapter-pg`, PGlite), where `meta.target` is left empty. The error handler now recovers the violated columns and constraint name from the adapter's error shape, and a new `uniqueConstraintOf(error)` helper exposes this to callers of `context.db.*` directly. Unique-violation messages under driver adapters change from the generic fallback back to field-specific text.
+
+- [#1001](https://github.com/OpenSaasAU/stack/pull/1001) [`52dfdd2`](https://github.com/OpenSaasAU/stack/commit/52dfdd2c051aa2f4b4cbd96a459213c34c3bf85c) Thanks [@borisno2](https://github.com/borisno2)! - Fix `include` on a to-one relationship throwing `PrismaClientValidationError` when the related list's `query` access resolves to a filter (Prisma only accepts a nested `where` on a to-many include). The relation is now fetched and access-scoped via a batched existence check instead, returning `null` for an excluded related row rather than throwing — a caller relying on the previous exception, or whose types assumed a non-null relation, should re-check nullability.
+
 ## 0.39.2
 
 ### Patch Changes

package/CLAUDE.md

@@ -192,6 +192,97 @@ Key points:
   optimistically at write time, unchanged. See ADR-0028 and the hooks concept
   doc.
 
+#### Hook context is the same secured context as a transaction's (#1176)
+
+A list/field `resolveInput` / `validate` / `beforeOperation` / `afterOperation`
+hook's `context` argument is a full `StackContext` — `sudo()`, `withSession()`,
+`transaction()` and `serverAction` are all present, exactly like the `txContext`
+a `context.transaction()` callback receives — bound to the WRITE'S OWN
+transaction client, not the base one. This amends ADR-0012: the Write
+Pipeline's transaction rebind (`bindContextToTransaction`) goes through the
+same `getContext` factory `context.transaction()` already rebuilds through,
+instead of hand-assembling a bare `AccessContext` object literal.
+
+```typescript
+Order: list({
+  hooks: {
+    beforeOperation: async ({ context }) => {
+      // Elevated AND atomic with this write: rolls back together if the
+      // write (or a later hook in it) throws — unlike `getContext(session)
+      // .sudo()`, which would bind to a SEPARATE connection.
+      await context.sudo().db.auditLog.create({ data: { action: 'order-write' } })
+    },
+  },
+})
+```
+
+- `context.sudo()` / `context.withSession(s)` from one of these hooks stays
+  bound to the SAME transaction client the hook itself was given — carrying
+  the write's transaction owner (ADR-0028, so a write through them defers its
+  `afterTransaction` to that owner) and the hook's own resolve chain
+  (ADR-0023, so a write issued from inside a `resolveOutput` hook keeps that
+  hook's cycle-guard chain into its own Field Visibility pass).
+- `context.transaction(fn)` called from inside one of these hooks **joins**
+  the write's transaction (the existing "no interactive client → run
+  directly" fallback) — it never opens a nested one.
+- Plugin runtimes are **not** re-executed on this rebind (same rule as the
+  nested-write rebind ADR-0010 already established).
+- **Unaffected:** `beforeTransaction` / `afterTransaction` (list and field) keep
+  the plain `AccessContext`, bound to the BASE client, always — see ADR-0028
+  for why boundary hooks must not run through a client that may already be
+  closed by flush time.
+- **A field's `resolveOutput` keeps the plain `AccessContext` type**, but which
+  client it's bound to already depended — before this record and after it
+  alike — on how the read that triggered it arose: a plain top-level read
+  resolves against the base client; a `resolveOutput` that runs as part of a
+  create/update's OWN result (the write's Field Visibility pass, Phase 11)
+  resolves against THAT write's transaction client (ADR-0010) — so a
+  `context.db` read/write from inside such a hook is already atomic with the
+  write, same as `beforeOperation`/`afterOperation`. Not a consequence of this
+  record; stated here only so it isn't mistaken for one.
+
+See ADR-0066 and the hooks concept doc's "In-transaction vs
+transaction-boundary hooks" section.
+
+#### Substituting a session (`context.withSession`, #980)
+
+`context.withSession(session)` sits beside `sudo()` on the other axis:
+`sudo()` keeps the session and drops access control; `withSession()` keeps
+access control (and hooks) and swaps the session. It reuses the receiver's
+already-resolved config, client (including a transaction client — a call
+inside `context.transaction()` stays in that transaction), and storage.
+
+Like `sudo()` (and unlike `transaction()`), plugin runtime services are
+**rebuilt, not reused** — `plugin.runtime(context, sudo)` factories are
+re-run so any plugin service that closes over the session (e.g. an auth
+plugin's "who is this session" lookup) binds to the _new_ one rather than
+staying stale. A hot loop calling `withSession()` per iteration re-runs
+every plugin's `runtime()` each time; batch via a shared derived context
+where the loop body doesn't need a different session per iteration.
+
+```typescript
+// An unattended dispatcher running a committed intent, or any job runner
+// that is legitimately authorised but arrives without the session a list's
+// validate hook wants to see in `args.context.session`.
+async function dispatchJob(context: StackContext, job: { ownerSession: Session }) {
+  const asOwner = context.withSession(job.ownerSession)
+  await asOwner.db.task.update({ where: { id: job.taskId }, data: { status: 'done' } })
+}
+```
+
+**`withSession` grants no authority of its own.** It is not an
+authorisation — the derived context can do exactly what any context built
+with that session directly could do; access rules still evaluate against
+the new session. The application decides who may call it.
+
+**Orthogonal to `sudo()`.** `context.withSession(s).sudo()` and
+`context.sudo().withSession(s)` are equivalent — both elevated and both
+carrying `s`. `withSession` preserves the receiver's sudo state rather than
+resetting it: called on an already-sudo context it stays sudo, called on a
+plain context it does not grant sudo.
+
+`withSession(null)` is a legitimate way to drop to an anonymous context.
+
 ### Generators (`src/generator/`)
 
 - `prisma.ts` - Generates `prisma/schema.prisma` from config
@@ -320,6 +411,18 @@ const context = createContext<typeof prisma>(config, prisma, session)
 - Uses context for all operations (access control enforced); writes are validated by the normal `context.db` pipeline (field Zod schemas, hooks, access control)
 - Custom tools may declare a Zod `inputSchema` — validated on `tools/call`, converted to JSON Schema for `tools/list` — or a plain JSON Schema object
 - Auth adapters (like `@opensaas/stack-auth/mcp`) provide session integration; custom session fields pass through to access control
+- The derived `query` tool accepts an optional `fields` projection (`packages/core/src/mcp/projection.ts`) — the wire form of a fragment field selection, translated into a `context.db` `include` so the ordinary read pipeline (access scoping, `needs` folding, the depth cap) applies with no parallel read path. The generated schema enumerates two fixed levels of each list's vocabulary, per session; `tools/list` itself is per-session as a result (ADR-0033)
+
+### The MCP `query` Tool's `fields` Projection (ADR-0033)
+
+An optional `fields` argument on the derived `query` tool narrows (or widens, up to two levels) what a read returns, in the wire form of a fragment field selection: `{ scalarField: true, relation: { fields: {...} } }`. A to-many relation additionally accepts `where`/`orderBy`/`take`/`skip` and a `count`. Omitting `fields` is unchanged — a bare read, per ADR-0024.
+
+`projection.ts` does the work in two passes, both walking the same per-session vocabulary (`relatedListIfVisible`):
+
+- `generateFieldsProjectionSchema` builds the JSON Schema advertised on `tools/list` — a relation whose target list denies this session's operation-level `query` access, or has `mcp.enabled: false`, is omitted from the vocabulary entirely, not merely left unusable.
+- `resolveFieldsProjection` validates a caller's `fields` against that same vocabulary and translates it into a plain `context.db` `include` (deliberately NOT the fragment `query:` argument — going through the ordinary caller-`include` path is what gets `buildAccessScopedInclude`'s nested-`where` AND-fold, the to-one existence check, and the depth cap for free; the trade-off is that every computed field at a traversed level still computes server-side, same as any other `include`-based read, even one the projection didn't select — only the wire response is narrowed). Throws `McpProjectionRefusedError` (caught in the handler and turned into an `isError` tool result, never a JSON-RPC error) naming what was asked for and what's available on any mismatch.
+
+A to-many's `count` is resolved separately via Prisma's `_count.select`, access-scoped by ANDing the related list's `query` access with any caller `where` on that same relation (mirroring, but not reusing, `relationship-count.ts`'s `_count` scoping — that module's own helper isn't exported and was built for a different feature, issue #732's admin list view).
 
 ### With Third-Party Field Packages
 

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

@@ -1,24 +1,103 @@
-import type { Session, AccessContext } from './types.js';
+import type { Session, AccessContext, PrismaFilter } from './types.js';
 import type { OpenSaasConfig, FieldConfig, ListConfig } from '../config/types.js';
+import { type ResolveSyntheticRelation } from './query-validation.js';
+/**
+ * One relation's recorded access filter, or an outright denial — see the
+ * module doc's "To-one relations" section. `kind: 'scoped'` is to-one only
+ * (a to-many filter is attached as Prisma `where` instead, never recorded
+ * here); `kind: 'denied'` is recorded for BOTH arities (issue #1103) — a
+ * to-many relation has no `where`-based way to record "zero rows, and the
+ * key itself absent" either, so it shares the same post-query mechanism a
+ * denied to-one already used.
+ */
+export type ToOneAccessFilterEntry = {
+    kind: 'scoped';
+    relatedListName: string;
+    accessWhere: PrismaFilter;
+} | {
+    kind: 'denied';
+};
+/**
+ * Which relations, at which nesting level of an `include`, need a post-query
+ * fixup rather than a Prisma-side `where` — a to-one relation whose related
+ * list's `query` access resolved to a filter (`kind: 'scoped'`) or a denial
+ * (`kind: 'denied'`), Prisma cannot express either as a nested `where` on a
+ * to-one include; a to-many relation whose related list denies `query`
+ * access outright (`kind: 'denied'` only — a to-many filter is attached as
+ * `where` and never reaches this tree) is dropped from `include` entirely,
+ * so nothing marks its key present in the raw row either (issue #1103).
+ * `resolveToOneAccessVisibility` consumes this tree; `filterReadableFields`
+ * (`field-visibility.ts`) applies its result — forcing a denied key to `null`
+ * for a to-one relation, `[]` for a to-many one.
+ */
+export type ToOneAccessFilterTree = {
+    /** Relation keys at THIS level needing a post-query fixup. */
+    filters: Record<string, ToOneAccessFilterEntry>;
+    /** Per-key trees for relations present in the include for other reasons, whose own nested include may contain further filters. */
+    nested: Record<string, ToOneAccessFilterTree>;
+};
+export declare function emptyToOneAccessFilterTree(): ToOneAccessFilterTree;
+/**
+ * Whether a relationship field is to-one (at most one related row) rather
+ * than to-many. Exported so `field-visibility.ts` can pick the same `null`
+ * (to-one) vs `[]` (to-many) shape for a denied relation's forced value
+ * (issue #1103) that this module used to decide whether to record the
+ * denial in the first place — one source of truth for arity, not two.
+ */
+export declare function isToOneRelationship(fieldConfig: FieldConfig): boolean;
+/**
+ * Which `_count.select` keys, at which nesting level of an `include`, were
+ * denied outright by their related list's `query` access — omitted from the
+ * `_count.select` sent to Prisma (issue #1087), so the row Prisma returns
+ * either lacks the key entirely or lacks a `_count` object at all. Consumed
+ * post-query by `filterReadableFields` (`field-visibility.ts`), which injects
+ * `0` for each — a count is a session-relative value, and `0` is what "no
+ * visible rows" means for it, never an absent key (mirroring the to-one
+ * `null` injection this module already does for issue #974, though a denied
+ * count needs no existence check: `0` requires no query at all).
+ */
+export type CountAccessDenialTree = {
+    /** `_count.select` keys denied at THIS level. */
+    keys: Set<string>;
+    /** Per-relation trees for relations present in the include for other reasons, whose own nested include may contain a further `_count`. */
+    nested: Record<string, CountAccessDenialTree>;
+};
+export declare function emptyCountAccessDenialTree(): CountAccessDenialTree;
 /**
  * Build the access-scoped `include` for exactly the relations a read
  * requested, recursing only into branches `requestedInclude` itself names.
  *
  * 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 field that isn't a relationship (scalar, virtual, …) → access
+ *   control does not govern it; passed through unchanged (a virtual key is
+ *   stripped later by `stripVirtualFieldsFromInclude`, #628).
+ * - Not declared at all → resolved via `resolveSyntheticReverseRelation`
+ *   (the synthetic-back-relation case above); `_count` is scoped by
+ *   `buildAccessScopedCountSelect` (issue #1087 — each named relation's own
+ *   `query` access, exactly like any other relation this walk scopes; a
+ *   denied one is recorded for `filterReadableFields` to inject `0` for,
+ *   post-query, since Prisma cannot be asked for a guaranteed `0`); anything
+ *   else throws `UndeclaredIncludeKeyError` rather than reaching the
+ *   database unscoped.
  * - 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.
+ *   control chooses *whether* and *with what filter*. This denial is also
+ *   recorded in `toOneAccessFilters` (`kind: 'denied'`), for either arity, so
+ *   `filterReadableFields` can still surface an explicit `null` (to-one,
+ *   issue #974) or `[]` (to-many, issue #1103) for it rather than an absent
+ *   key.
+ * - Otherwise, for a to-**many** relation → the access `where` is
+ *   AND-combined with any caller-supplied nested `where` (never replaced —
+ *   the other half of #566), and a caller-supplied `take` rides through
+ *   unchanged (#752). For a to-**one** relation → the access filter (if any)
+ *   is recorded in `toOneAccessFilters` instead of attached as `where`,
+ *   because Prisma only accepts a nested `where` on a to-many include
+ *   (issue #974) — the entry itself never carries a `where` for a to-one key.
+ * - Either way — 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.
  *
  * **Depth is a cost limit, not a cycle guard (ADR-0026).** A `requestedInclude`
  * is always a finite literal — the caller's own object, or
@@ -32,7 +111,57 @@ import type { OpenSaasConfig, FieldConfig, ListConfig } from '../config/types.js
 export declare function buildAccessScopedInclude(requestedInclude: Record<string, unknown>, fieldConfigs: Record<string, FieldConfig>, args: {
     session: Session | null;
     context: AccessContext;
-}, config: OpenSaasConfig, listKey: string, depth?: number): Promise<Record<string, unknown>>;
+}, config: OpenSaasConfig, listKey: string, depth?: number): Promise<{
+    include: Record<string, unknown>;
+    toOneAccessFilters: ToOneAccessFilterTree;
+    countDenials: CountAccessDenialTree;
+}>;
+/**
+ * One relation's resolved post-query visibility — see
+ * `resolveToOneAccessVisibility`. `kind: 'visible'` (an existence check
+ * against a set of ids) only ever arises for a to-one relation, since only a
+ * to-one `kind: 'scoped'` filter entry produces one; `kind: 'denied'` passes
+ * straight through unresolved for either arity.
+ */
+export type ToOneVisibility = {
+    kind: 'denied';
+} | {
+    kind: 'visible';
+    ids: ReadonlySet<string>;
+};
+/** The resolved counterpart to {@link ToOneAccessFilterTree}, produced by `resolveToOneAccessVisibility`. */
+export type ToOneAccessVisibilityTree = {
+    filters: Record<string, ToOneVisibility>;
+    nested: Record<string, ToOneAccessVisibilityTree>;
+};
+export declare function emptyToOneAccessVisibilityTree(): ToOneAccessVisibilityTree;
+/**
+ * Resolve a `ToOneAccessFilterTree` against the RAW rows Prisma already
+ * fetched (unscoped for the flagged to-one relations — see
+ * `buildAccessScopedInclude`) into the set of related ids the session may
+ * actually see, one batched `id IN (...)` existence check per (relation,
+ * nesting level) across every row in `items` — never once per row.
+ *
+ * For each `filters` entry at a level:
+ * - `kind: 'denied'` → carried straight through; no query, nothing to check.
+ * - `kind: 'scoped'` → every id present at this key across ALL of `items` is
+ *   collected first (an empty set skips the query entirely — nothing to
+ *   check), then ONE `findMany` through the RAW `prisma` client (not
+ *   `context.db`, which would re-evaluate the same access-control function a
+ *   second time) asks which of those ids also satisfy `accessWhere` — the
+ *   exact `PrismaFilter` `checkAccess` already produced, handed to Prisma
+ *   unmodified rather than interpreted by hand.
+ *
+ * Recurses into `nested` by flattening the related items reached through
+ * each key across every row in `items` (a to-many hop contributes every one
+ * of its rows; a to-one hop contributes its single row, if any) into the
+ * next level's own `items` array, so a to-one relation nested arbitrarily
+ * deep is still resolved with one batched query per node, not per parent row.
+ */
+export declare function resolveToOneAccessVisibility(items: readonly unknown[], tree: ToOneAccessFilterTree, args: {
+    session: Session | null;
+    context: AccessContext;
+}): Promise<ToOneAccessVisibilityTree>;
 /**
  * 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`
@@ -73,11 +202,25 @@ export declare function buildAccessScopedInclude(requestedInclude: Record<string
  * 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.
+ *
+ * A quantifier's value of literal `null` (`is: null`/`isNot: null`, a to-one
+ * relation's existence check) is passed through untouched rather than folded:
+ * it names no fields to read-check or scope, and AND-folding an access filter
+ * into it would silently invert the caller's own predicate (see the inline
+ * comment at that branch).
+ *
+ * `resolveSyntheticRelation` (#1092/#1108) extends this to a key that
+ * resolves to a synthetic back-relation (#1082) rather than a declared
+ * field, recursing against its SOURCE list. Only `buildAccessScopedInclude`
+ * passes it, for the include-nested `where` position; the top-level `where`
+ * this function was originally built for (`context/index.ts`) omits it, so
+ * a synthetic key there is unaffected — matching #1092's own scope, which
+ * deliberately left the top-level checks unchanged.
  */
 export declare function buildAccessScopedWhere(where: unknown, listConfig: ListConfig<any>, listName: string, config: OpenSaasConfig, args: {
     session: Session | null;
     context: AccessContext;
-}): Promise<unknown>;
+}, resolveSyntheticRelation?: ResolveSyntheticRelation): Promise<unknown>;
 /**
  * Remove keys that correspond to `virtual` fields from a Prisma `include`
  * object, recursing into nested relationship includes using the related

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