@opensaas/stack-core 0.37.0 → 0.39.0

package/dist/context/index.js

@@ -1,23 +1,15 @@
-import { checkAccess, mergeFilters, filterReadableFields, buildIncludeWithAccessControl, mergeIncludeWithAccessControl, stripVirtualFieldsFromInclude, foldDeclaredDependencies, } from '../access/index.js';
+import { checkAccess, mergeFilters, filterReadableFields, buildAccessScopedInclude, buildAccessScopedWhere, stripVirtualFieldsFromInclude, foldDeclaredDependencies, validateQueryKeys, validateQueryFieldReadAccess, } from '../access/index.js';
 import { ValidationError, DatabaseError } from '../hooks/index.js';
 import { getDbKey } from '../lib/case-utils.js';
-import { buildInclude, pickFields, isFragment } from '../query/index.js';
+import { buildInclude, pickFields, isFragment, buildFieldSelectionScope } from '../query/index.js';
 import { getRelationshipOptions } from '../query/relationship-options.js';
 import { runWritePipeline, createWriteStrategy, updateWriteStrategy, deleteWriteStrategy, } from './write-pipeline.js';
-/**
- * Tracks which (listName, operation) pairs have already warned about an ignored
- * `select` argument, so a misused read op warns once rather than on every call.
- */
+import { AfterTransactionError } from './transaction-boundary.js';
+import { TransactionRegistry } from '../access/transaction-registry.js';
 const selectWarnings = new Set();
 /**
- * Warn (once per list+operation) when a caller passes a `select` argument to a
- * read op that does not honour it.
- *
- * `context.db` reads never apply Prisma `select` semantics — narrowing is done
- * via `include` or a fragment `query`. The op still runs and returns the full,
- * access-filtered result, so this is a visible no-op rather than an error.
- *
- * Centralised here so every affected read op shares one implementation.
+ * Warn once per (list, operation) when a caller passes `select` to a read op
+ * that ignores it. See "Narrowing Reads" in packages/core/CLAUDE.md.
  */
 function warnIfSelectIgnored(args, listName, operation) {
     if (!args || args.select === undefined)
@@ -31,34 +23,23 @@ function warnIfSelectIgnored(args, listName, operation) {
         `Narrow a read with \`include\` or a fragment \`query\` instead. ` +
         `See https://stack.opensaas.au/docs/concepts/queries`);
 }
-/**
- * Check if a list is configured as a singleton
- */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
 function isSingletonList(listConfig) {
     return !!listConfig.isSingleton;
 }
 /**
  * Compute the set of single-field unique selectors a `findUnique` `where` may be
- * keyed by, derived from what the list config exposes at runtime.
- *
- * The set is:
- * - `id` — always a unique identifier on every list.
- * - Any field declared `isIndexed: 'unique'` in the config (e.g. `text({ isIndexed: 'unique' })`).
- * - For a `relationship` field declared `isIndexed: 'unique'`, the foreign-key
- *   column name (`<field>Id`) — that is the column Prisma marks `@unique`, so the
- *   unique `where` is keyed by `<field>Id`, not the relation field itself.
+ * keyed by, derived from what the list config exposes at runtime: `id`, plus any
+ * field declared `isIndexed: 'unique'` — for a `relationship` field, this is the
+ * foreign-key column name (`<field>Id`), since that's the column Prisma marks
+ * `@unique`, not the relation field itself.
  *
- * Chosen rule (documented intentionally): the config does NOT expose compound
- * (`@@unique`) keys at runtime — there is no list-level unique declaration in the
- * config API — so we cannot validate compound `<Model>_<a>_<b>` selectors. We
- * therefore enforce the tractable subset: `where` must contain EXACTLY ONE
- * recognised single-field unique key and NO other keys. This rejects non-unique
- * filters (the bug in #567) and rejects extra non-unique keys alongside a unique
- * one, while never falsely rejecting a valid single-field unique lookup. If a
- * project legitimately needs a compound-unique lookup, that path is not covered
- * here and would need explicit config support; the safe escape hatch for any
- * non-unique single-row lookup is `findFirst` (see #565).
+ * The config exposes no list-level compound (`@@unique`) declaration, so this
+ * cannot validate a compound `<Model>_<a>_<b>` selector — `where` must contain
+ * exactly one recognised single-field unique key and no others. This rejects
+ * non-unique filters (#567) without ever rejecting a valid single-field unique
+ * lookup; a compound-unique or otherwise non-unique lookup should use
+ * `findFirst` instead (see #565).
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
 function getUniqueWhereKeys(listConfig) {
@@ -95,10 +76,6 @@ function assertUniqueWhere(where, uniqueKeys, listName) {
         throw new ValidationError([message], {});
     }
 }
-/**
- * Check if auto-create is enabled for a singleton list
- * Defaults to true if not explicitly set to false
- */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
 function shouldAutoCreate(listConfig) {
     if (!listConfig.isSingleton)
@@ -107,47 +84,34 @@ function shouldAutoCreate(listConfig) {
         return true;
     return listConfig.isSingleton.autoCreate !== false;
 }
-/**
- * Extract default values from field configs
- * Used to auto-create singleton records with sensible defaults
- */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
 function getDefaultData(listConfig) {
     const data = {};
     for (const [fieldKey, fieldConfig] of Object.entries(listConfig.fields)) {
-        // Skip virtual fields - they're not stored in database
         if (fieldConfig.virtual)
             continue;
-        // Skip system fields (id, createdAt, updatedAt)
         if (fieldKey === 'id' || fieldKey === 'createdAt' || fieldKey === 'updatedAt')
             continue;
-        // Add default value if present
         if ('defaultValue' in fieldConfig && fieldConfig.defaultValue !== undefined) {
             data[fieldKey] = fieldConfig.defaultValue;
         }
     }
     return data;
 }
-/**
- * Parse Prisma error and convert to user-friendly DatabaseError
- */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
 function parsePrismaError(error, listConfig) {
-    // Check if it's a Prisma error
     if (error &&
         typeof error === 'object' &&
         'code' in error &&
         'meta' in error &&
         typeof error.code === 'string') {
         const prismaError = error;
-        // Handle unique constraint violation
+        // P2002 is Prisma's unique constraint violation code.
         if (prismaError.code === 'P2002') {
             const target = prismaError.meta?.target;
             const fieldErrors = {};
             if (target && Array.isArray(target)) {
-                // Get field names from the constraint target
                 for (const fieldName of target) {
-                    // Get the field config to get a better label
                     const fieldConfig = listConfig.fields[fieldName];
                     const label = fieldName.charAt(0).toUpperCase() + fieldName.slice(1);
                     if (fieldConfig) {
@@ -157,39 +121,54 @@ function parsePrismaError(error, listConfig) {
                         fieldErrors[fieldName] = `This value is already in use`;
                     }
                 }
-                // Create a user-friendly general message
                 const fieldLabels = target.map((f) => f.charAt(0).toUpperCase() + f.slice(1)).join(', ');
                 return new DatabaseError(`${fieldLabels} must be unique. The value you entered is already in use.`, fieldErrors, prismaError.code);
             }
             return new DatabaseError('A record with this value already exists', {}, prismaError.code);
         }
-        // Handle other Prisma errors - return generic message
         return new DatabaseError(prismaError.message || 'A database error occurred', {}, prismaError.code);
     }
-    // Not a Prisma error, return as-is if it's already an Error
     if (error instanceof Error) {
         return error;
     }
-    // Unknown error type
     return new Error('An unknown error occurred');
 }
 /**
- * Create an access-controlled context
- *
- * @param config - OpenSaas configuration
- * @param prisma - Your Prisma client instance (pass as generic for type safety)
- * @param session - Current session object (or null if not authenticated)
- * @param storage - Optional storage utilities (uploadFile, uploadImage, deleteFile, deleteImage)
+ * Drain a `context.transaction()` owner's deferral registry once its callback
+ * (and any real underlying transaction) has settled (ADR-0028). A transaction/
+ * callback error always wins — compensators still all run, but their errors
+ * are discarded in favor of re-surfacing the original, matching the Write
+ * Pipeline's `txError` precedence — otherwise any deferred `afterTransaction`
+ * errors reject with {@link AfterTransactionError} even though the callback
+ * succeeded and the transaction committed.
  */
+async function settleTransactionOwner(settled, registry) {
+    const errors = [];
+    let result;
+    try {
+        result = await settled;
+    }
+    catch (err) {
+        const outcome = { status: 'rolled-back', error: err };
+        await registry.drain(outcome, errors);
+        throw err;
+    }
+    await registry.drain({ status: 'committed' }, errors);
+    if (errors.length > 0) {
+        throw new AfterTransactionError(errors);
+    }
+    return result;
+}
 export function getContext(config, prisma, session, storage, _isSudo = false, 
 // Internal: when rebuilding the context against a transaction client, reuse the
 // already-initialised plugin services rather than re-running plugin runtimes.
-_sharedPlugins) {
-    // Initialize db object - will be populated with access-controlled operations
-    // Type is intentionally broad to allow dynamic model access
+_sharedPlugins, 
+// Internal (ADR-0028, #899): when rebuilding the context for a transaction
+// owner's callback body, carry the deferral registry so writes reached
+// through this context join it instead of firing afterTransaction eagerly.
+_transactionOwner) {
+    // Broad type to allow dynamic model access; populated by populateDbDelegate below.
     const db = {};
-    // Create context with db reference (will be populated below)
-    // Storage utilities can be provided via parameter or use default stubs
     const context = {
         session,
         prisma: prisma,
@@ -213,13 +192,11 @@ _sharedPlugins) {
         plugins: _sharedPlugins ?? {},
         _isSudo,
         _resolveOutputChain: [],
+        _transactionOwner,
     };
-    // Create access-controlled operations for each list, populating `db` in place.
     populateDbDelegate(db, config, prisma, context);
-    // Execute plugin runtime functions and populate context.plugins.
     // Skipped when reusing shared plugins (transaction rebind) so runtimes — and
     // any side effects they carry — run exactly once per top-level context.
-    // Use _plugins (sorted by dependencies) if available, otherwise fall back to plugins array
     if (!_sharedPlugins) {
         const pluginsToExecute = config._plugins || config.plugins || [];
         for (const plugin of pluginsToExecute) {
@@ -231,13 +208,12 @@ _sharedPlugins) {
                 }
                 catch (error) {
                     console.error(`Error executing runtime for plugin "${plugin.name}":`, error);
-                    // Continue with other plugins even if one fails
                 }
             }
         }
     }
-    // Generic server action handler with discriminated union for type safety
-    // Returns a result object instead of throwing to work properly in Next.js production
+    // Returns a result object instead of throwing — required for server actions
+    // to work in Next.js production builds.
     async function serverAction(props) {
         const dbKey = getDbKey(props.listKey);
         const listConfig = config.lists[props.listKey];
@@ -317,8 +293,7 @@ _sharedPlugins) {
                 return { bulkAction: false, error: 'Action failed' };
             }
         }
-        // Relationship-table row removal (ADR-0018, #739). Runs on the RELATED row
-        // through the secured context, so the related list's access + hooks apply.
+        // Runs on the RELATED row (ADR-0018 boundary — see ServerActionProps above).
         // Honours Silent failure: an access-denied operation returns `null`, which
         // becomes `{ removed: false }` with a generic reason — never leaking whether
         // the row was denied or absent.
@@ -359,14 +334,13 @@ _sharedPlugins) {
                 return { removed: false, error: dbError.message };
             }
         }
-        // Relationship-table pre-linked create (ADR-0018, #738). Creates a row on
-        // the RELATED list through the secured context, so the related list's create
-        // access + hooks (and field-level access) apply — never the parent's. The
-        // back-reference to the parent is set here from `field`/`parentId` (a to-one
-        // back-ref connects a single parent; a to-many back-ref, e.g. many-to-many,
-        // connects the parent by id), so the client can never re-target the link.
-        // Honours Silent failure: an access-denied create returns `null`, surfaced
-        // as `{ created: false }` with a generic reason (no denied-vs-absent leak).
+        // Runs on the RELATED list (ADR-0018 boundary — see ServerActionProps above).
+        // The back-reference to the parent is set here from `field`/`parentId` (a
+        // to-one back-ref connects a single parent; a to-many back-ref, e.g.
+        // many-to-many, connects the parent by id), so the client can never
+        // re-target the link. Honours Silent failure: an access-denied create
+        // returns `null`, surfaced as `{ created: false }` with a generic reason
+        // (no denied-vs-absent leak).
         if (props.action === 'createRelated') {
             try {
                 // Defensive guard (hardening; unreachable from the drawer, which always
@@ -423,11 +397,9 @@ _sharedPlugins) {
                 };
             }
         }
-        // Relationship-table inline cell edit (ADR-0018, #737). Updates ONE scalar
-        // field on the RELATED row through the secured context, so the related list's
-        // operation- and field-level update access plus its hooks/validation apply —
-        // never the parent's. Honours Silent failure: an access-denied update returns
-        // `null`, surfaced as `{ updated: false }` with a generic reason (no
+        // Updates ONE scalar field on the RELATED row (ADR-0018 boundary — see
+        // ServerActionProps above). Honours Silent failure: an access-denied update
+        // returns `null`, surfaced as `{ updated: false }` with a generic reason (no
         // denied-vs-absent leak); a validation/db error surfaces its message and
         // fieldErrors so the cell can revert with a reason and show an inline error.
         if (props.action === 'updateRelated') {
@@ -498,7 +470,6 @@ _sharedPlugins) {
             };
         }
         catch (error) {
-            // Handle ValidationError (has fieldErrors)
             if (error instanceof ValidationError) {
                 return {
                     success: false,
@@ -506,7 +477,6 @@ _sharedPlugins) {
                     fieldErrors: error.fieldErrors,
                 };
             }
-            // Handle DatabaseError (has fieldErrors)
             if (error instanceof DatabaseError) {
                 return {
                     success: false,
@@ -514,7 +484,6 @@ _sharedPlugins) {
                     fieldErrors: error.fieldErrors,
                 };
             }
-            // Parse and convert Prisma errors to user-friendly DatabaseError
             const dbError = parsePrismaError(error, listConfig);
             if (dbError instanceof DatabaseError) {
                 return {
@@ -523,34 +492,44 @@ _sharedPlugins) {
                     fieldErrors: dbError.fieldErrors,
                 };
             }
-            // Generic error fallback
             return {
                 success: false,
                 error: dbError.message,
             };
         }
     }
-    // Sudo function - creates a new context that bypasses access control
-    // but still executes all hooks and validation
+    // Bypasses access control; hooks and validation still run.
     function sudo() {
-        return getContext(config, prisma, session, context.storage, true);
+        return getContext(config, prisma, session, context.storage, true, undefined, 
+        // ADR-0028: a sudo write issued from inside an owned transaction (e.g.
+        // `tx.sudo().db.x.create()`) must still defer to that owner.
+        context._transactionOwner);
     }
-    // Interactive, hook-firing transaction (#614). Rebinds the access-controlled
-    // context to the transaction client so every `txContext.db.*` write runs its
-    // access checks + hooks but persists inside ONE transaction (atomic). The
-    // transaction `options` (e.g. `isolationLevel`) pass through to Prisma, and a
-    // serialization failure thrown inside the callback propagates to the caller
-    // for retry (it is never converted to a silent `null`).
+    // Interactive, hook-firing transaction (#614). See the `transaction` doc on
+    // `StackContext` above for the atomicity/isolation/retry contract.
+    //
+    // This call OWNS a deferral registry for its callback's writes (ADR-0028):
+    // it always observes when its own callback settles — resolve/reject — even
+    // when the underlying client cannot open a real interactive transaction, so
+    // every `txContext.db.*` write defers its transaction-boundary bracket here
+    // instead of firing eagerly, and this call flushes them with the real
+    // outcome once the callback (and any real transaction) has settled. A
+    // `transaction()` nested inside another joins the outer owner's queue
+    // rather than creating a second one.
     function transaction(fn, options) {
-        const client = prisma;
-        if (typeof client.$transaction !== 'function') {
-            // No interactive transaction available — either a plain client/mock or we
-            // are already inside a transaction (a Prisma tx client exposes no
-            // `$transaction`). Run directly: hook/access semantics are identical and
-            // atomicity is provided by any enclosing transaction.
+        if (context._transactionOwner) {
             return fn(returned);
         }
-        return client.$transaction((tx) => fn(getContext(config, tx, session, context.storage, _isSudo, context.plugins)), options);
+        const registry = new TransactionRegistry();
+        const client = prisma;
+        const settled = typeof client.$transaction !== 'function'
+            ? // No interactive transaction available (plain client/mock, or already
+                // inside one — see `TransactionCapable` above). Run directly: hook/
+                // access semantics are identical, atomicity comes from the enclosing
+                // transaction.
+                fn(getContext(config, prisma, session, context.storage, _isSudo, context.plugins, registry))
+            : client.$transaction((tx) => fn(getContext(config, tx, session, context.storage, _isSudo, context.plugins, registry)), options);
+        return settleTransactionOwner(settled, registry);
     }
     const returned = {
         db: db,
@@ -579,7 +558,6 @@ _sharedPlugins) {
 export function populateDbDelegate(target, config, prisma, context) {
     for (const [listName, listConfig] of Object.entries(config.lists)) {
         const dbKey = getDbKey(listName);
-        // Create base operations
         const createOp = createCreate(listName, listConfig, prisma, context, config);
         const findManyOp = createFindMany(listName, listConfig, prisma, context, config);
         const updateOp = createUpdate(listName, listConfig, prisma, context, config);
@@ -590,11 +568,10 @@ export function populateDbDelegate(target, config, prisma, context) {
             create: createOp,
             update: updateOp,
             delete: createDelete(listName, listConfig, prisma, context, config),
-            count: createCount(listName, listConfig, prisma, context),
+            count: createCount(listName, listConfig, prisma, context, config),
             createMany: createCreateMany(listName, listConfig, prisma, context, config, createOp),
             updateMany: createUpdateMany(listName, listConfig, prisma, context, config, findManyOp, updateOp),
         };
-        // Add get() method for singleton lists
         if (isSingletonList(listConfig)) {
             operations.get = createGet(listName, listConfig, prisma, context, config, createOp);
         }
@@ -619,51 +596,51 @@ export function buildDbDelegate(config, prisma, context) {
  *
  * A fragment's own `include` and a sudo caller's `include` are folded and
  * used as-is, matching their existing (unmerged) treatment. A non-sudo
- * caller include is folded and then merged through the same
- * access-scoping pipeline as before. A bare read stays on the exact
- * ADR-0024 path — `include: undefined`, no related `query` access
- * evaluated — unless folding actually added something, which only happens
- * when a field on this list declares `needs`.
+ * caller include is folded and then scoped by `buildAccessScopedInclude`
+ * (ADR-0026) — caller-directed, so a relation named nowhere in the folded
+ * tree never has its list's `query` access evaluated at all. A bare read
+ * stays on the exact ADR-0024 path — `include: undefined`, no related
+ * `query` access evaluated — unless folding actually added something, which
+ * only happens when a field on this list declares `needs`.
+ *
+ * Also returns the `FieldSelectionScope` a fragment's own field selection
+ * produces (ADR-0027), so the caller can pass it to `filterReadableFields`
+ * and make computation itself projection-aware, not only the fold above.
+ * `undefined` for every non-fragment path: a caller `include` (sudo or not)
+ * and a bare read both mean "compute every field," matching what they
+ * already fetch.
  */
 async function resolveReadInclude(callerInclude, fragmentFields, listName, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
 listConfig, context, config) {
     if (fragmentFields !== undefined) {
         const fragmentInclude = buildInclude(fragmentFields) ?? undefined;
-        return foldDeclaredDependencies(fragmentInclude, listConfig.fields, config);
+        const selection = buildFieldSelectionScope(fragmentFields);
+        const folded = foldDeclaredDependencies(fragmentInclude, listConfig.fields, config, listName, [listName], selection);
+        return { ...folded, selection };
     }
     if (context._isSudo) {
-        return foldDeclaredDependencies(callerInclude, listConfig.fields, config);
+        const folded = foldDeclaredDependencies(callerInclude, listConfig.fields, config, listName);
+        return { ...folded, selection: undefined };
     }
-    const folded = foldDeclaredDependencies(callerInclude, listConfig.fields, config);
+    const folded = foldDeclaredDependencies(callerInclude, listConfig.fields, config, listName);
     if (!folded.include) {
-        return folded;
+        return { ...folded, selection: undefined };
     }
-    const accessControlledInclude = await buildIncludeWithAccessControl(listConfig.fields, { session: context.session, context }, config, 0, 
-    // Seed the cycle guard with the root list so a relationship cycle back
-    // to it (self-referential or longer) stops re-descending.
-    [listName]);
-    const include = mergeIncludeWithAccessControl(folded.include, accessControlledInclude, listConfig.fields, config, listName);
-    return { include, declaredOnly: folded.declaredOnly };
+    const include = await buildAccessScopedInclude(folded.include, listConfig.fields, { session: context.session, context }, config, listName);
+    return { include, declaredOnly: folded.declaredOnly, selection: undefined };
 }
-/**
- * Create findUnique operation with access control
- */
 function createFindUnique(listName, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
 listConfig, prisma, context, config) {
     return async (args) => {
-        // `select` is a visible no-op: warn, then proceed with include/query narrowing.
         warnIfSelectIgnored(args, listName, 'findUnique');
-        // Enforce unique-`where` (Keystone `findOne` parity). This is a caller-shape
-        // check independent of access, so it runs first and THROWS on misuse — it is
-        // not an access denial and must not be masked as a silent `null`. The
-        // type-level constraint already lives on the generated delegate: the custom
-        // `<List>FindUniqueArgs` only Omits `select`/`include` from
-        // `Prisma.<List>FindUniqueArgs`, so its `where` stays Prisma's
-        // `<List>WhereUniqueInput` — this runtime guard backstops untyped callers.
+        // Runs first, before the access check below — a non-unique `where` is a
+        // caller-shape error (see `assertUniqueWhere`), not an access denial. The
+        // generated `<List>FindUniqueArgs` only Omits `select`/`include` from
+        // Prisma's own type, so `where` stays `<List>WhereUniqueInput` — this
+        // runtime guard backstops untyped callers.
         assertUniqueWhere(args.where, getUniqueWhereKeys(listConfig), listName);
-        // Check query access (skip if sudo mode)
         let where = args.where;
         if (!context._isSudo) {
             const queryAccess = listConfig.access?.operation?.query;
@@ -674,28 +651,27 @@ listConfig, prisma, context, config) {
             if (accessResult === false) {
                 return null;
             }
-            // Merge access filter with where clause
             const mergedWhere = mergeFilters(args.where, accessResult);
             if (mergedWhere === null) {
                 return null;
             }
             where = mergedWhere;
         }
-        // When a query fragment is provided, build the include from the fragment
-        // instead of the access-controlled include. Access control still runs via
-        // filterReadableFields; the fragment then narrows to only the requested fields.
+        // Access control still runs via filterReadableFields even though a
+        // fragment drives `include`; the fragment only narrows which fields come back.
         const fragment = isFragment(args.query) ? args.query : null;
         // Resolve `include`, folding any declared dependencies (`needs`,
         // ADR-0025) in alongside whatever the fragment/caller/sudo/bare path
         // already produces — see `resolveReadInclude`'s doc comment.
-        let { include, declaredOnly } = await resolveReadInclude(args.include, fragment ? fragment._fields : undefined, listName, listConfig, context, config);
+        let { include, declaredOnly, selection } = await resolveReadInclude(args.include, fragment ? fragment._fields : undefined, listName, listConfig, context, config);
         // Virtual fields have no database column. Whichever path produced
         // `include` (fragment, access-controlled merge, or sudo passthrough), a
         // virtual key must never reach Prisma — it would throw "Unknown field"
-        // (#628). The virtual value is still computed unconditionally below by
-        // `filterReadableFields`, independent of what was requested here.
+        // (#628). Below, `filterReadableFields` computes a virtual field's value
+        // exactly when `selection` says the read is going to return it (ADR-0027)
+        // — every one of them for a bare/`include`-based read (`selection` is
+        // `undefined`), only the ones a fragment named otherwise.
         include = stripVirtualFieldsFromInclude(include, listConfig.fields, config);
-        // Execute query with optimized includes
         // Access Prisma model dynamically - required because model names are generated at runtime
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const model = prisma[getDbKey(listName)];
@@ -706,33 +682,29 @@ listConfig, prisma, context, config) {
         if (!item) {
             return null;
         }
-        // Filter readable fields and apply resolveOutput hooks (including nested relationships)
         // Pass sudo flag through context to skip field-level access checks
         const filtered = await filterReadableFields(item, listConfig.fields, {
             session: context.session,
             context: { ...context, _isSudo: context._isSudo },
-        }, config, 0, listName, declaredOnly);
-        // When a fragment is provided, pick only the requested fields from the result
+        }, config, 0, listName, declaredOnly, selection);
         if (fragment) {
             return pickFields(filtered, fragment._fields);
         }
         return filtered;
     };
 }
-/**
- * Create findMany operation with access control
- */
 function createFindMany(listName, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
 listConfig, prisma, context, config) {
     return async (args) => {
-        // `select` is a visible no-op: warn, then proceed with include/query narrowing.
         warnIfSelectIgnored(args, listName, 'findMany');
-        // Check singleton constraint (throw error instead of silently returning empty)
+        // Singleton misuse throws rather than silently returning `[]` — unlike an
+        // access denial, this is a caller-shape error.
         if (isSingletonList(listConfig)) {
             throw new ValidationError([`Cannot use findMany: ${listName} is a singleton list. Use get() instead.`], {});
         }
-        // Check query access (skip if sudo mode)
+        // Check query access first (skip if sudo mode) — this MUST run before the
+        // #912/#915 where/orderBy validation below. See the comment there for why.
         let where = args?.where;
         if (!context._isSudo) {
             const queryAccess = listConfig.access?.operation?.query;
@@ -743,26 +715,61 @@ listConfig, prisma, context, config) {
             if (accessResult === false) {
                 return [];
             }
-            // Merge access filter with where clause
-            const mergedWhere = mergeFilters(args?.where, accessResult);
+            // #912 — reject a `where`/`orderBy` key the list config doesn't declare
+            // (e.g. a Prisma-generated back-relation), and #915 — reject one naming
+            // a field this session cannot READ (closing a probe via a `count()`
+            // that varies with the withheld value, or an `orderBy` that leaks
+            // relative ordering). Both run only now that the caller is known to
+            // have SOME access to the list (`accessResult !== false`): the thrown
+            // errors name the offending key, and running them before the access
+            // check above would let a caller with ZERO access to the list learn a
+            // field's name and read-gating status from the error message alone —
+            // turning the validation itself into the kind of oracle #915 closes.
+            // `sudo` bypasses this whole branch, matching the write path.
+            validateQueryKeys({
+                where: args?.where,
+                orderBy: args?.orderBy,
+                listConfig,
+                listName,
+                config,
+                isSudo: false,
+            });
+            await validateQueryFieldReadAccess({
+                where: args?.where,
+                orderBy: args?.orderBy,
+                listConfig,
+                listName,
+                session: context.session,
+                context,
+                isSudo: false,
+            });
+            // #916 — scope every relation filter nested in `where`
+            // (`some`/`every`/`none`/`is`/`isNot`) by the RELATED list's own `query`
+            // access, recursing through every hop of a chain — the `where`
+            // counterpart to how `include` is already scoped below via
+            // `buildAccessScopedInclude`. Runs after the checks above for the same
+            // ordering reason: only once the caller is known to have SOME access to
+            // THIS list.
+            const scopedWhere = args?.where
+                ? (await buildAccessScopedWhere(args.where, listConfig, listName, config, {
+                    session: context.session,
+                    context,
+                }))
+                : args?.where;
+            const mergedWhere = mergeFilters(scopedWhere, accessResult);
             if (mergedWhere === null) {
                 return [];
             }
             where = mergedWhere;
         }
-        // When a query fragment is provided, build include from fragment fields
         const fragment = isFragment(args?.query) ? args.query : null;
         // Resolve `include`, folding any declared dependencies (`needs`,
         // ADR-0025) in alongside whatever the fragment/caller/sudo/bare path
         // already produces — see `resolveReadInclude`'s doc comment.
-        let { include, declaredOnly } = await resolveReadInclude(args?.include, fragment ? fragment._fields : undefined, listName, listConfig, context, config);
-        // Virtual fields have no database column. Whichever path produced
-        // `include` (fragment, access-controlled merge, or sudo passthrough), a
-        // virtual key must never reach Prisma — it would throw "Unknown field"
-        // (#628). The virtual value is still computed unconditionally below by
-        // `filterReadableFields`, independent of what was requested here.
+        let { include, declaredOnly, selection } = await resolveReadInclude(args?.include, fragment ? fragment._fields : undefined, listName, listConfig, context, config);
+        // Strips virtual keys from `include` before the Prisma call — see the
+        // `createFindUnique` comment above for why (#628, ADR-0027).
         include = stripVirtualFieldsFromInclude(include, listConfig.fields, config);
-        // Execute query with optimized includes
         // Access Prisma model dynamically - required because model names are generated at runtime
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const model = prisma[getDbKey(listName)];
@@ -773,13 +780,11 @@ listConfig, prisma, context, config) {
             skip: args?.skip,
             include,
         });
-        // Filter readable fields for each item and apply resolveOutput hooks (including nested relationships)
         // Pass sudo flag through context to skip field-level access checks
         const filtered = await Promise.all(items.map((item) => filterReadableFields(item, listConfig.fields, {
             session: context.session,
             context: { ...context, _isSudo: context._isSudo },
-        }, config, 0, listName, declaredOnly)));
-        // When a fragment is provided, pick only the requested fields from each result
+        }, config, 0, listName, declaredOnly, selection)));
         if (fragment) {
             return filtered.map((item) => pickFields(item, fragment._fields));
         }
@@ -801,9 +806,6 @@ function createFindFirst(findManyOp) {
         return result[0] ?? null;
     };
 }
-/**
- * Create create operation with access control and hooks
- */
 function createCreate(listName, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
 listConfig, prisma, context, config) {
@@ -821,10 +823,8 @@ listConfig, prisma, context, config) {
         });
     };
 }
-/**
- * Create createMany operation with access control and hooks
- * Runs create in a loop to ensure all hooks and access control are executed for each item
- */
+// Runs create in a loop (not Prisma's native createMany) so every item still
+// gets its own hooks and access control.
 function createCreateMany(listName, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
 listConfig, prisma, context, config, 
@@ -839,9 +839,6 @@ createFn) {
         return results;
     };
 }
-/**
- * Create update operation with access control and hooks
- */
 function createUpdate(listName, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
 listConfig, prisma, context, config) {
@@ -859,10 +856,8 @@ listConfig, prisma, context, config) {
         });
     };
 }
-/**
- * Create updateMany operation with access control and hooks
- * Runs findMany to get records, then update in a loop to ensure all hooks and access control are executed
- */
+// Finds matching records, then updates each individually (not Prisma's native
+// updateMany) so every item still gets its own hooks and access control.
 function createUpdateMany(listName, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
 listConfig, prisma, context, config, 
@@ -871,9 +866,7 @@ findManyFn,
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 updateFn) {
     return async (args) => {
-        // First, find all matching records (respects access control)
         const items = await findManyFn({ where: args.where });
-        // Then update each one individually (runs hooks and access control for each)
         const results = [];
         for (const item of items) {
             const result = await updateFn({ where: { id: item.id }, data: args.data });
@@ -882,9 +875,6 @@ updateFn) {
         return results;
     };
 }
-/**
- * Create delete operation with access control and hooks
- */
 function createDelete(listName, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
 listConfig, prisma, context, config) {
@@ -902,14 +892,12 @@ listConfig, prisma, context, config) {
         });
     };
 }
-/**
- * Create count operation with access control
- */
 function createCount(listName, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
-listConfig, prisma, context) {
+listConfig, prisma, context, config) {
     return async (args) => {
-        // Check query access (skip if sudo mode)
+        // Check query access first (skip if sudo mode) — this MUST run before the
+        // #912/#915 where validation below. See the comment there for why.
         let where = args?.where;
         if (!context._isSudo) {
             const queryAccess = listConfig.access?.operation?.query;
@@ -920,14 +908,47 @@ listConfig, prisma, context) {
             if (accessResult === false) {
                 return 0;
             }
-            // Merge access filter with where clause
-            const mergedWhere = mergeFilters(args?.where, accessResult);
+            // #912 — reject a `where` key the list config doesn't declare (e.g. a
+            // Prisma-generated back-relation), and #915 — reject one naming a field
+            // this session cannot READ. `count` leaks the most cleanly of any read
+            // op — a bare count answers a predicate with no rows returned at all —
+            // so it gets the same reject, not a lesser one. Both run only now that
+            // the caller is known to have SOME access to the list (`accessResult
+            // !== false`) — see the identical comment in `createFindMany` for why
+            // that ordering matters: running them before the access check would
+            // let a fully-denied caller learn a field's name and read-gating
+            // status from the thrown error alone. `sudo` bypasses this whole
+            // branch, matching the write path.
+            validateQueryKeys({
+                where: args?.where,
+                listConfig,
+                listName,
+                config,
+                isSudo: false,
+            });
+            await validateQueryFieldReadAccess({
+                where: args?.where,
+                listConfig,
+                listName,
+                session: context.session,
+                context,
+                isSudo: false,
+            });
+            // #916 — scope every relation filter nested in `where` by the RELATED
+            // list's own `query` access. See the identical comment in
+            // `createFindMany` for why this runs here, in this order.
+            const scopedWhere = args?.where
+                ? (await buildAccessScopedWhere(args.where, listConfig, listName, config, {
+                    session: context.session,
+                    context,
+                }))
+                : args?.where;
+            const mergedWhere = mergeFilters(scopedWhere, accessResult);
             if (mergedWhere === null) {
                 return 0;
             }
             where = mergedWhere;
         }
-        // Execute count
         // Access Prisma model dynamically - required because model names are generated at runtime
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const model = prisma[getDbKey(listName)];
@@ -937,23 +958,16 @@ listConfig, prisma, context) {
         return count;
     };
 }
-/**
- * Create get operation for singleton lists
- * Returns the single record, or auto-creates it if enabled
- */
 function createGet(listName, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
 listConfig, prisma, context, config, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 createFn) {
     return async (args) => {
-        // `select` is a visible no-op: warn, then proceed with include/query narrowing.
         warnIfSelectIgnored(args, listName, 'get');
-        // First try to find the existing record
         // Access Prisma model dynamically - required because model names are generated at runtime
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const model = prisma[getDbKey(listName)];
-        // Check query access (skip if sudo mode)
         let where = {};
         if (!context._isSudo) {
             const queryAccess = listConfig.access?.operation?.query;
@@ -964,45 +978,39 @@ createFn) {
             if (accessResult === false) {
                 return null;
             }
-            // Merge access filter (for singleton, we don't have a specific where clause)
+            // A singleton has no per-record `where`, so the access filter (if any) is
+            // the whole `where`.
             if (accessResult && typeof accessResult === 'object') {
                 where = accessResult;
             }
         }
-        // When a query fragment is provided, build the include from the fragment
-        // instead of the access-controlled include. Access control still runs via
-        // filterReadableFields; the fragment then narrows to only the requested fields.
+        // Access control still runs via filterReadableFields even though a
+        // fragment drives `include`; the fragment only narrows which fields come back.
         const fragment = isFragment(args?.query) ? args.query : null;
         // Resolve `include`, folding any declared dependencies (`needs`,
         // ADR-0025) in alongside whatever the fragment/caller/sudo/bare path
         // already produces — see `resolveReadInclude`'s doc comment.
-        let { include, declaredOnly } = await resolveReadInclude(args?.include, fragment ? fragment._fields : undefined, listName, listConfig, context, config);
+        let { include, declaredOnly, selection } = await resolveReadInclude(args?.include, fragment ? fragment._fields : undefined, listName, listConfig, context, config);
         // Virtual fields have no database column and must never reach Prisma (#628).
         include = stripVirtualFieldsFromInclude(include, listConfig.fields, config);
-        // Try to find the record
         const item = await model.findFirst({
             where,
             include,
         });
-        // If record exists, return it
         if (item) {
-            // Filter readable fields and apply resolveOutput hooks
             const filtered = await filterReadableFields(item, listConfig.fields, {
                 session: context.session,
                 context: { ...context, _isSudo: context._isSudo },
-            }, config, 0, listName, declaredOnly);
-            // When a fragment is provided, pick only the requested fields from the result
+            }, config, 0, listName, declaredOnly, selection);
             if (fragment) {
                 return pickFields(filtered, fragment._fields);
             }
             return filtered;
         }
-        // If no record and auto-create is enabled, create it
         if (shouldAutoCreate(listConfig)) {
             const defaultData = getDefaultData(listConfig);
             return await createFn({ data: defaultData });
         }
-        // No record and auto-create is disabled
         return null;
     };
 }