fix(core): a bare read fetches scalars, not relations (#848) by borisno2 · Pull Request #853 · OpenSaasAU/stack

borisno2 · 2026-07-31T23:30:14Z

Summary

A context.db read with no include (and no fragment query) used to auto-include every readable relationship of the list, recursing up to READ_INCLUDE_MAX_DEPTH (5) and evaluating every related list's operation-level query access along the way — Prisma's own semantics for the same call are "scalars only." This is identified as the shared root cause behind Explicit include bypasses relation-level access filtering on reads — caller include REPLACES the access-controlled include #566, Access control fails OPEN past include depth 5: caller includes pass through unscoped and nested rows skip field-read filtering #830, and 0.33.0: reads inside resolveOutput recurse without bound — server OOMs on any access-scoped read #844.
A bare read now returns the row's own columns plus its virtual fields only, matching Prisma, for findUnique, findMany, and a singleton's .get() alike — under sudo and under a session, uniformly. .get() also gains caller-include support it never had.
Relations are still fetched, and access-scoped exactly as before, whenever a caller names them via include or a fragment query — the mergeIncludeWithAccessControl / buildIncludeWithAccessControl machinery (and the Explicit include bypasses relation-level access filtering on reads — caller include REPLACES the access-controlled include #566/Access control fails OPEN past include depth 5: caller includes pass through unscoped and nested rows skip field-read filtering #830 fixes it carries) is untouched; it's simply no longer invoked unprompted.
Follows the decision recorded in ADR-0024 (docs/adr/0024-a-read-with-no-include-fetches-scalars-not-relations.md, docs: record that a bare read fetches scalars, not relations (#848) #849, already merged).

Implementation

packages/core/src/context/index.ts: createFindUnique, createFindMany, and createGet (singleton) only call buildIncludeWithAccessControl when the caller supplied an include; a bare read sends include: undefined straight through. createGet gains the same fragment/include/sudo handling the other two reads already had.
packages/cli/src/generator/types.ts: generates a <List>GetArgs type for singleton lists and types get() to accept it (include/query/select), mirroring FindUniqueArgs.
Docs (docs/content/concepts/{queries,access-control}.md, docs/content/reference/context-api.md, packages/core/CLAUDE.md) updated to describe the new default; one example (examples/blog/test-context-nested-virtual.ts) fixed to pass an explicit include instead of relying on the old auto-include.
Existing regression coverage for Explicit include bypasses relation-level access filtering on reads — caller include REPLACES the access-controlled include #566 and Access control fails OPEN past include depth 5: caller includes pass through unscoped and nested rows skip field-read filtering #830 (caller-supplied-include behavior) is unmodified — only bare-read call sites in tests were updated. The #844 cycle-guard reproduction now demonstrates the cycle no longer occurs on the reporter's bare hook-issued read (with the mock's return value made to actually respect the include argument, so it faithfully models Prisma); the genuine two-list cycle regression is untouched and still throws.
New test coverage: packages/core/tests/bare-read-scalars.test.ts (bare vs. explicit-include behavior, including "no related query access is evaluated on a bare read") and a new describe block in packages/core/tests/singleton.test.ts for .get()'s new include support.

Test plan

pnpm test in packages/core — 923/923 passing
pnpm test in packages/cli — 323/323 passing
pnpm build for @opensaas/stack-core and @opensaas/stack-cli — clean
pnpm lint — clean (pre-existing unrelated warnings only)
pnpm manypkg fix — no changes
pnpm format — clean
Generated examples/blog types and typechecked the fixed example script against them
Changeset added (.changeset/silent-relations-detour.md, minor) leading with the silent nature of the break, both detection strategies, and the migration

Closes #848

🤖 Generated with Claude Code

https://claude.ai/code/session_01PifFTifspW7ud4ptUGK4Mx

Generated by Claude Code

A context.db read with no `include` (and no fragment `query`) used to auto-include every readable relationship, recursing 5 levels deep and evaluating every related list's query access along the way — the root cause behind #566, #830, and #844. It now returns the row's own columns plus its virtual fields only, matching Prisma's own semantics, for findUnique, findMany, and a singleton's get() alike (get() also gains caller-include support). Relations are fetched only when a caller names them, at which point the existing #566/#830 merge-with-access-control path is unchanged. See docs/adr/0024-a-read-with-no-include-fetches-scalars-not-relations.md. Closes #848 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PifFTifspW7ud4ptUGK4Mx

vercel · 2026-07-31T23:30:18Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
stack-docs	Ready	Preview	Jul 31, 2026 11:30pm

changeset-bot · 2026-07-31T23:30:19Z

🦋 Changeset detected

Latest commit: ab288f3

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 9 packages

Name	Type
@opensaas/stack-core	Minor
@opensaas/stack-cli	Minor
@opensaas/stack-auth	Minor
@opensaas/stack-rag	Minor
@opensaas/stack-storage	Minor
@opensaas/stack-tiptap	Minor
@opensaas/stack-ui	Minor
@opensaas/stack-storage-s3	Minor
@opensaas/stack-storage-vercel	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

borisno2 · 2026-07-31T23:31:27Z

Self-review

Overview

Implements #848 / ADR-0024: a context.db read with no include (and no fragment query) now returns the row's own scalar columns plus its virtual fields only — it no longer auto-includes every readable relationship recursively. Applies uniformly to findUnique, findMany, and a singleton's .get() (which also gains caller-include support it never had), under sudo and under a session alike.

Correctness

The caller-include merge path (buildIncludeWithAccessControl + mergeIncludeWithAccessControl, carrying the Explicit include bypasses relation-level access filtering on reads — caller include REPLACES the access-controlled include #566/Access control fails OPEN past include depth 5: caller includes pass through unscoped and nested rows skip field-read filtering #830 fixes) is untouched — it is simply gated behind args.include being truthy instead of running unconditionally. findFirst is sugar over findMany and inherits the new behavior automatically; no separate change was needed there.
Verified the two hot spots called out in the issue: (1) related-list query access is no longer evaluated on a bare read — covered by a spy assertion in bare-read-scalars.test.ts; (2) the reporter's User → Account → Student cycle no longer reproduces on the hook's bare context.db.account.findMany(...) call — the test's mock was changed to condition its return value on the actual include argument (mirroring real Prisma) rather than always returning the full relation tree, since the old mock would have masked the fix.
stripVirtualFieldsFromInclude(undefined, ...) and mergeIncludeWithAccessControl with an empty caller include: {} were checked against existing behavior — both are unchanged from before this PR (an empty object was already truthy pre-PR, so include: {} already took the merge branch; that's pre-existing, not a regression here).

Test coverage

New: packages/core/tests/bare-read-scalars.test.ts (bare vs. explicit include, FK columns + virtuals still returned, related query access not evaluated, sudo parity).
New: singleton .get() include-support tests in singleton.test.ts.
Updated in place (not touched further than necessary): 3 bare-read assertions in nested-access-and-hooks.test.ts now pass an explicit include to keep testing what they were designed to test; the #844 cycle reproduction and the concurrent-isolation test in resolve-chain.test.ts were adapted to the new default (see above).
Left deliberately unmodified per the issue's acceptance criteria: the Explicit include bypasses relation-level access filtering on reads — caller include REPLACES the access-controlled include #566/Access control fails OPEN past include depth 5: caller includes pass through unscoped and nested rows skip field-read filtering #830 regression suites in context.test.ts and access-relationships.test.ts, and the genuine two-list cycle regression in resolve-chain.test.ts (still throws ResolveOutputCycleError, proving the cycle guard isn't weakened).

Risks / things I considered and ruled out

Silent behavior change: this is the core, accepted risk of the change (a read that returned post.author now returns no author key, no error) — called out explicitly as the lead of the changeset per ADR-0024, with both detection strategies and a migration example.
Generator surface: packages/cli's new <List>GetArgs type is only generated for isSingleton lists, and get()'s new args parameter is optional, so existing generated call sites (get() with no args) keep compiling and behaving the same.
MCP: the query CRUD tool already issues a bare findMany with no include — it inherits the new default with no code change, matching the issue's explicit instruction not to add an include there.

Verification run

packages/core: 923/923 tests passing
packages/cli: 323/323 tests passing
tsc clean for both packages
pnpm lint clean (pre-existing unrelated warnings only), pnpm manypkg fix no-op, pnpm format clean
Regenerated examples/blog and typechecked the fixed example script against the real generated types

No further changes identified as needed.

Generated by Claude Code

github-actions · 2026-07-31T23:37:06Z