@opensaas/stack-core 0.39.1 → 0.40.0

package/.turbo/turbo-build.log

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

package/CHANGELOG.md

@@ -1,5 +1,161 @@
 # @opensaas/stack-core
 
+## 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
+
+- [#960](https://github.com/OpenSaasAU/stack/pull/960) [`77ca919`](https://github.com/OpenSaasAU/stack/commit/77ca91931bc3de4051c1a40cc00b77158b8192e6) Thanks [@borisno2](https://github.com/borisno2)! - Fix `OutputConfig.opensaasDir`'s doc comment, which still listed the now-removed generated `prisma-extensions.ts` module among the bundle files.
+
 ## 0.39.1
 
 ## 0.39.0

package/CLAUDE.md

@@ -192,6 +192,45 @@ Key points:
   optimistically at write time, unchanged. See ADR-0028 and the hooks concept
   doc.
 
+#### 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 +359,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,5 +1,28 @@
-import type { Session, AccessContext } from './types.js';
+import type { Session, AccessContext, PrismaFilter } from './types.js';
 import type { OpenSaasConfig, FieldConfig, ListConfig } from '../config/types.js';
+/** One to-one relation's recorded access filter, or an outright denial — see the module doc's "To-one relations" section. */
+export type ToOneAccessFilterEntry = {
+    kind: 'scoped';
+    relatedListName: string;
+    accessWhere: PrismaFilter;
+} | {
+    kind: 'denied';
+};
+/**
+ * Which to-one relations, at which nesting level of an `include`, need a
+ * post-query existence check rather than a Prisma-side `where` — because
+ * their related list's `query` access resolved to a filter (`kind: 'scoped'`)
+ * or a denial (`kind: 'denied'`) and Prisma cannot express either as a nested
+ * `where` on a to-one include. `resolveToOneAccessVisibility` consumes this
+ * tree; `filterReadableFields` (`field-visibility.ts`) applies its result.
+ */
+export type ToOneAccessFilterTree = {
+    /** To-one relation keys at THIS level needing a post-query check. */
+    filters: Record<string, ToOneAccessFilterEntry>;
+    /** Per-key trees for relations present in the include for other reasons, whose own nested include may contain further to-one filters. */
+    nested: Record<string, ToOneAccessFilterTree>;
+};
+export declare function emptyToOneAccessFilterTree(): ToOneAccessFilterTree;
 /**
  * Build the access-scoped `include` for exactly the relations a read
  * requested, recursing only into branches `requestedInclude` itself names.
@@ -11,14 +34,21 @@ import type { OpenSaasConfig, FieldConfig, ListConfig } from '../config/types.js
  * - 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*. For a to-one relation
+ *   this denial is also recorded in `toOneAccessFilters` (`kind: 'denied'`),
+ *   so `filterReadableFields` can still surface an explicit `null` for it
+ *   (issue #974) 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 +62,50 @@ 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;
+}>;
+/** One to-one relation's resolved post-query visibility — see `resolveToOneAccessVisibility`. */
+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`

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":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAmHjF,6HAA6H;AAC7H,MAAM,MAAM,sBAAsB,GAChC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,eAAe,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,YAAY,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAA;AAE7F;;;;;;;GAOG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAA;IAC/C,yIAAyI;IACzI,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAA;CAC9C,CAAA;AAED,wBAAgB,0BAA0B,IAAI,qBAAqB,CAElE;AAWD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;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;IAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,kBAAkB,EAAE,qBAAqB,CAAA;CAAE,CAAC,CAgF1F;AAED,iGAAiG;AACjG,MAAM,MAAM,eAAe,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;CAAE,CAAA;AAEhG,6GAA6G;AAC7G,MAAM,MAAM,yBAAyB,GAAG;IACtC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;IACxC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAA;CAClD,CAAA;AAED,wBAAgB,8BAA8B,IAAI,yBAAyB,CAE1E;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,4BAA4B,CAChD,KAAK,EAAE,SAAS,OAAO,EAAE,EACzB,IAAI,EAAE,qBAAqB,EAC3B,IAAI,EAAE;IACJ,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;IACvB,OAAO,EAAE,aAAa,CAAA;CACvB,GACA,OAAO,CAAC,yBAAyB,CAAC,CA+CpC;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"}

package/dist/access/access-filter.js

@@ -2,6 +2,7 @@ import { checkAccess, getRelatedListConfig } from './engine.js';
 import { READ_INCLUDE_MAX_DEPTH } from './depth-limits.js';
 import { AccessScopeDepthExceededError, RelationFilterAccessDeniedError } from './errors.js';
 import { LOGICAL_OPERATORS, RELATION_QUANTIFIERS, resolveQueryField, walkWhereReadAccess, } from './query-validation.js';
+import { getDbKey } from '../lib/case-utils.js';
 /** A plain object — excludes `null` and arrays, which `typeof x === 'object'` alone would admit. */
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -13,13 +14,15 @@ function isPlainObject(value) {
  * own type before trusting it, rather than casting the whole value wholesale.
  *
  * A numeric `take` on a to-many relation include (a caller-supplied row bound,
- * issue #752) is carried through: it only ever NARROWS the fetched rows and can
- * never widen past the access `where`, so preserving it is access-neutral.
+ * issue #752), and a caller-supplied `orderBy`/`skip` (#851), are carried
+ * through the same way: none of the three can ever widen the result past the
+ * access `where` — they only narrow or reorder rows the access filter already
+ * admits — so preserving them is access-neutral.
  */
 function asEntryObject(value) {
     if (!isPlainObject(value))
         return null;
-    const { where, include, take } = value;
+    const { where, include, take, orderBy, skip } = value;
     const entry = {};
     if (isPlainObject(where))
         entry.where = where;
@@ -27,6 +30,11 @@ function asEntryObject(value) {
         entry.include = include;
     if (typeof take === 'number')
         entry.take = take;
+    if (isPlainObject(orderBy) || Array.isArray(orderBy)) {
+        entry.orderBy = orderBy;
+    }
+    if (typeof skip === 'number')
+        entry.skip = skip;
     return entry;
 }
 /**
@@ -42,6 +50,16 @@ function andWhere(accessWhere, callerWhere) {
     }
     return accessWhere ?? callerWhere;
 }
+export function emptyToOneAccessFilterTree() {
+    return { filters: {}, nested: {} };
+}
+function isToOneAccessFilterTreeEmpty(tree) {
+    return Object.keys(tree.filters).length === 0 && Object.keys(tree.nested).length === 0;
+}
+/** Whether a relationship field is to-one (at most one related row) rather than to-many. */
+function isToOneRelationship(fieldConfig) {
+    return !('many' in fieldConfig && fieldConfig.many === true);
+}
 /**
  * Build the access-scoped `include` for exactly the relations a read
  * requested, recursing only into branches `requestedInclude` itself names.
@@ -53,14 +71,21 @@ function andWhere(accessWhere, callerWhere) {
  * - 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*. For a to-one relation
+ *   this denial is also recorded in `toOneAccessFilters` (`kind: 'denied'`),
+ *   so `filterReadableFields` can still surface an explicit `null` for it
+ *   (issue #974) 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
@@ -77,6 +102,7 @@ export async function buildAccessScopedInclude(requestedInclude, fieldConfigs, a
         throw new AccessScopeDepthExceededError(listKey, requestedKeys[0], depth);
     }
     const result = {};
+    const toOneAccessFilters = emptyToOneAccessFilterTree();
     for (const [relationName, requestedValue] of Object.entries(requestedInclude)) {
         const fieldConfig = fieldConfigs[relationName];
         const isDeclaredRelationship = fieldConfig?.type === 'relationship' && 'ref' in fieldConfig && !!fieldConfig.ref;
@@ -87,31 +113,126 @@ export async function buildAccessScopedInclude(requestedInclude, fieldConfigs, a
         const relatedConfig = getRelatedListConfig(fieldConfig.ref, config);
         if (!relatedConfig)
             continue;
+        const isToOne = isToOneRelationship(fieldConfig);
         const queryAccess = relatedConfig.listConfig.access?.operation?.query;
         const accessResult = await checkAccess(queryAccess, {
             session: args.session,
             context: args.context,
         });
         if (accessResult === false) {
+            if (isToOne) {
+                toOneAccessFilters.filters[relationName] = { kind: 'denied' };
+            }
             continue;
         }
         const accessWhere = typeof accessResult === 'object' ? accessResult : undefined;
         const requestedEntry = asEntryObject(requestedValue);
-        const mergedWhere = andWhere(accessWhere, requestedEntry?.where);
         let nestedInclude;
+        let nestedToOneFilters;
         if (requestedEntry?.include) {
-            nestedInclude = await buildAccessScopedInclude(requestedEntry.include, relatedConfig.listConfig.fields, args, config, relatedConfig.listName, depth + 1);
+            const nested = await buildAccessScopedInclude(requestedEntry.include, relatedConfig.listConfig.fields, args, config, relatedConfig.listName, depth + 1);
+            nestedInclude = nested.include;
+            nestedToOneFilters = nested.toOneAccessFilters;
         }
         const entry = {};
-        if (mergedWhere)
-            entry.where = mergedWhere;
+        if (isToOne) {
+            if (accessWhere) {
+                toOneAccessFilters.filters[relationName] = {
+                    kind: 'scoped',
+                    relatedListName: relatedConfig.listName,
+                    accessWhere,
+                };
+            }
+        }
+        else {
+            const mergedWhere = andWhere(accessWhere, requestedEntry?.where);
+            if (mergedWhere)
+                entry.where = mergedWhere;
+            if (requestedEntry?.take !== undefined)
+                entry.take = requestedEntry.take;
+            if (requestedEntry?.orderBy !== undefined)
+                entry.orderBy = requestedEntry.orderBy;
+            if (requestedEntry?.skip !== undefined)
+                entry.skip = requestedEntry.skip;
+        }
         if (nestedInclude && Object.keys(nestedInclude).length > 0)
             entry.include = nestedInclude;
-        if (requestedEntry?.take !== undefined)
-            entry.take = requestedEntry.take;
+        if (nestedToOneFilters && !isToOneAccessFilterTreeEmpty(nestedToOneFilters)) {
+            toOneAccessFilters.nested[relationName] = nestedToOneFilters;
+        }
         result[relationName] = Object.keys(entry).length > 0 ? entry : true;
     }
-    return result;
+    return { include: result, toOneAccessFilters };
+}
+export function emptyToOneAccessVisibilityTree() {
+    return { filters: {}, nested: {} };
+}
+/**
+ * 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 async function resolveToOneAccessVisibility(items, tree, args) {
+    const resolved = emptyToOneAccessVisibilityTree();
+    for (const [key, entry] of Object.entries(tree.filters)) {
+        if (entry.kind === 'denied') {
+            resolved.filters[key] = { kind: 'denied' };
+            continue;
+        }
+        const ids = new Set();
+        for (const item of items) {
+            if (!item || typeof item !== 'object')
+                continue;
+            const value = item[key];
+            if (value && typeof value === 'object' && 'id' in value) {
+                ids.add(String(value.id));
+            }
+        }
+        if (ids.size === 0) {
+            resolved.filters[key] = { kind: 'visible', ids: new Set() };
+            continue;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- dynamic model access by list name, mirroring the rest of the read pipeline
+        const model = args.context.prisma[getDbKey(entry.relatedListName)];
+        const visibleRows = await model.findMany({
+            where: { AND: [entry.accessWhere, { id: { in: [...ids] } }] },
+            select: { id: true },
+        });
+        const visibleIds = new Set(Array.isArray(visibleRows) ? visibleRows.map((row) => String(row.id)) : []);
+        resolved.filters[key] = { kind: 'visible', ids: visibleIds };
+    }
+    for (const [key, nestedTree] of Object.entries(tree.nested)) {
+        const nestedItems = [];
+        for (const item of items) {
+            if (!item || typeof item !== 'object')
+                continue;
+            const value = item[key];
+            if (Array.isArray(value))
+                nestedItems.push(...value);
+            else if (value && typeof value === 'object')
+                nestedItems.push(value);
+        }
+        resolved.nested[key] = await resolveToOneAccessVisibility(nestedItems, nestedTree, args);
+    }
+    return resolved;
 }
 /**
  * Scope every relation filter (`some`/`every`/`none`/`is`/`isNot`) nested in a