test(sql-orm-client): regression guards for namespaced capability

lookup; centralize the structural cast in a `withCapabilities` helper

Adds two tests that assert depth-1 includes against an emitted-shape
contract (capabilities under `targetFamily` and `target` namespaces)
fire exactly one SQL execution. Either fails fast if
`selectIncludeStrategy`'s namespace-aware lookup regresses.

Verified the unit-level guard fails when the strategy detection
reverts to top-level-only access.

Test ergonomics:

- Adds `withCapabilities(contract, capabilities)` to `helpers.ts`.
  The narrow `TestContract` type fixes capabilities to the exact
  shape from `contract.json` (e.g. the `postgres` namespace's specific
  readonly fields). Tests need to construct contracts with arbitrary
  capability shapes, which don't fit the narrow type. The helper
  centralizes the structural cast in one named, documented place.

- Removes per-test `as unknown as ReturnType<typeof getTestContract>`
  / `as unknown as TestContract` casts from `include-strategy.test.ts`
  (was 7) and `collection-dispatch.test.ts` (was 3) by routing through
  `withCapabilities`.

- The pre-existing `withSingleQueryCapabilities` and the new
  `withEmittedSqlCapabilities` helpers in `collection-dispatch.test.ts`
  delegate to `withCapabilities`.

Regression guards:

- `collection-dispatch.test.ts` — `withEmittedSqlCapabilities` produces
  `{ sql: { jsonAgg: true }, postgres: { jsonAgg: true, lateral: true } }`.
  Asserts on MockRuntime's `executions.length`.
- `integration/include.test.ts` — uses `getTestContract()` directly
  (whose capabilities are already in the emitted shape via the
  `postgres` namespace) against the dev Postgres. Asserts
  `runtime.executions.length === 1`.

All 481 sql-orm-client tests pass.

Author: Sævar Berg

packages/3-extensions/sql-orm-client/test/collection-dispatch.test.ts

@@ -6,24 +6,35 @@ import type { IncludeExpr } from '../src/types';
 import { emptyState } from '../src/types';
 import { createCollectionFor } from './collection-fixtures';
 import type { MockRuntime, TestContract } from './helpers';
-import { createMockRuntime, getTestContract } from './helpers';
+import { createMockRuntime, getTestContract, withCapabilities } from './helpers';
 
 function withSingleQueryCapabilities(contract: TestContract): TestContract {
-  return {
-    ...contract,
-    capabilities: {
-      ...contract.capabilities,
-      [contract.targetFamily]: {
-        ...(contract.capabilities[contract.targetFamily] ?? {}),
-        jsonAgg: true,
-      },
-      [contract.target]: {
-        ...(contract.capabilities[contract.target] ?? {}),
-        jsonAgg: true,
-        lateral: true,
-      },
+  return withCapabilities(contract, {
+    ...contract.capabilities,
+    [contract.targetFamily]: {
+      ...(contract.capabilities[contract.targetFamily] ?? {}),
+      jsonAgg: true,
+    },
+    [contract.target]: {
+      ...(contract.capabilities[contract.target] ?? {}),
+      jsonAgg: true,
+      lateral: true,
     },
-  } as unknown as TestContract;
+  });
+}
+
+/**
+ * Mirrors the shape produced by the contract emitter: capability flags
+ * nested under the family + target namespaces, with no top-level entries.
+ * Used to assert "single-query path is selected for an emitted-shape
+ * contract" — the regression scenario the principled namespaced lookup
+ * was introduced to handle.
+ */
+function withEmittedSqlCapabilities(contract: TestContract): TestContract {
+  return withCapabilities(contract, {
+    sql: { jsonAgg: true, returning: true },
+    postgres: { jsonAgg: true, lateral: true, returning: true },
+  });
 }
 
 function addConnection(
@@ -78,6 +89,36 @@ describe('collection-dispatch', () => {
     expect(rows).toEqual([{ id: 1, name: 'Alice', email: 'alice@example.com' }]);
   });
 
+  it('dispatchCollectionRows() depth-1 include with emitted-shape capabilities fires a single SQL execution (regression guard for namespaced capability lookup)', async () => {
+    // Guards against regressing the fix that taught `selectIncludeStrategy`
+    // to read capability flags from the contract's `targetFamily` and
+    // `target` namespaces. Prior to that fix, every emitted contract fell
+    // back to multi-query for nested includes — silently, because
+    // functional correctness was unaffected. This test fails fast if the
+    // regression returns: an emitted-shape contract should resolve a
+    // depth-1 include in one SQL execution, not two.
+    const contract = withEmittedSqlCapabilities(getTestContract());
+    const { collection, runtime } = createCollectionFor('User', contract);
+    const scoped = collection.select('name').include('posts');
+    runtime.setNextResults([
+      [{ id: 1, name: 'Alice', posts: '[{"id":10,"title":"Post A","user_id":1,"views":3}]' }],
+    ]);
+
+    const rows = await dispatchCollectionRows<Record<string, unknown>>({
+      contract,
+      runtime,
+      state: scoped.state,
+      tableName: scoped.tableName,
+      modelName: scoped.modelName,
+    }).toArray();
+
+    expect(rows).toEqual([
+      { name: 'Alice', posts: [{ id: 10, title: 'Post A', userId: 1, views: 3 }] },
+    ]);
+    // The point of the test: 1 execution, not N+1.
+    expect(runtime.executions).toHaveLength(1);
+  });
+
   it('dispatchCollectionRows() single-query path returns empty rows and releases scope', async () => {
     const contract = withSingleQueryCapabilities(getTestContract());
     const { collection, runtime } = createCollectionFor('User', contract);
@@ -205,7 +246,7 @@ describe('collection-dispatch', () => {
     // Force multi-query strategy by clearing capabilities. Otherwise
     // the base test contract's postgres.lateral / postgres.jsonAgg
     // would route to single-query lateral.
-    const contract = { ...getTestContract(), capabilities: {} } as unknown as TestContract;
+    const contract = withCapabilities(getTestContract(), {});
     const { collection, runtime } = createCollectionFor('User', contract);
     const scoped = collection.select('name').include('posts', (posts) => posts.select('title'));
 

packages/3-extensions/sql-orm-client/test/helpers.ts

@@ -24,6 +24,24 @@ export function getTestContract(): TestContract {
   return structuredClone(baseTestContract);
 }
 
+/**
+ * Override the capabilities of a {@link TestContract} for a test scenario.
+ *
+ * The narrow `TestContract` type fixes capabilities to the exact shape
+ * found in `fixtures/generated/contract.json` (e.g. the `postgres`
+ * namespace's specific readonly fields). Tests need to construct
+ * contracts with arbitrary capability shapes — empty, only-jsonAgg,
+ * cross-namespace, etc. — that don't fit that narrow type.
+ *
+ * This helper centralizes the structural cast so call sites stay clean.
+ */
+export function withCapabilities(
+  contract: TestContract,
+  capabilities: Record<string, Record<string, boolean>>,
+): TestContract {
+  return { ...contract, capabilities } as unknown as TestContract;
+}
+
 const testContext: ExecutionContext<TestContract> = createExecutionContext({
   contract: baseTestContract,
   stack: createSqlExecutionStack({

packages/3-extensions/sql-orm-client/test/include-strategy.test.ts

@@ -1,54 +1,42 @@
 import { describe, expect, it } from 'vitest';
 import { selectIncludeStrategy } from '../src/include-strategy';
-import { getTestContract } from './helpers';
+import { getTestContract, withCapabilities } from './helpers';
 
 // The default test contract has `target: 'postgres'`, `targetFamily: 'sql'`,
 // and capabilities populated under those two namespaces. The strategy
-// selector reads only those namespaces, so override `capabilities`
-// directly to drive each scenario.
+// selector reads only those namespaces, so each test uses
+// `withCapabilities(...)` to swap in the override the scenario needs.
 
 describe('selectIncludeStrategy', () => {
   it('returns multiQuery when include capabilities are absent', () => {
-    const contract = {
-      ...getTestContract(),
-      capabilities: {},
-    } as unknown as ReturnType<typeof getTestContract>;
+    const contract = withCapabilities(getTestContract(), {});
 
     expect(selectIncludeStrategy(contract)).toBe('multiQuery');
   });
 
   it('returns correlated when jsonAgg is enabled in the family namespace without lateral', () => {
-    const contract = {
-      ...getTestContract(),
-      capabilities: {
-        sql: { jsonAgg: true },
-      },
-    } as unknown as ReturnType<typeof getTestContract>;
+    const contract = withCapabilities(getTestContract(), {
+      sql: { jsonAgg: true },
+    });
 
     expect(selectIncludeStrategy(contract)).toBe('correlated');
   });
 
   it('returns lateral when both flags are enabled in the same namespace', () => {
-    const contract = {
-      ...getTestContract(),
-      capabilities: {
-        postgres: { jsonAgg: true, lateral: true },
-      },
-    } as unknown as ReturnType<typeof getTestContract>;
+    const contract = withCapabilities(getTestContract(), {
+      postgres: { jsonAgg: true, lateral: true },
+    });
 
     expect(selectIncludeStrategy(contract)).toBe('lateral');
   });
 
   it('returns lateral when flags are split across family and target namespaces', () => {
     // Real-world shape: SQL family declares `jsonAgg`; the postgres
     // target adds `lateral` on top.
-    const contract = {
-      ...getTestContract(),
-      capabilities: {
-        sql: { jsonAgg: true },
-        postgres: { lateral: true },
-      },
-    } as unknown as ReturnType<typeof getTestContract>;
+    const contract = withCapabilities(getTestContract(), {
+      sql: { jsonAgg: true },
+      postgres: { lateral: true },
+    });
 
     expect(selectIncludeStrategy(contract)).toBe('lateral');
   });
@@ -58,37 +46,30 @@ describe('selectIncludeStrategy', () => {
     // A `mongo: { lateral: true }` namespace must not enable lateral
     // on a postgres runtime — namespaces are scoped to the running
     // target/family.
-    const contract = {
-      ...getTestContract(),
-      capabilities: {
-        mongo: { jsonAgg: true, lateral: true },
-        nonsense: { lateral: true },
-      },
-    } as unknown as ReturnType<typeof getTestContract>;
+    const contract = withCapabilities(getTestContract(), {
+      mongo: { jsonAgg: true, lateral: true },
+      nonsense: { lateral: true },
+    });
 
     expect(selectIncludeStrategy(contract)).toBe('multiQuery');
   });
 
   it('treats non-boolean capability values as missing', () => {
     // The Contract type declares capability values as `boolean`. Anything
     // else (string, object, undefined) is treated as not present.
-    const contract = {
-      ...getTestContract(),
-      capabilities: {
-        sql: { jsonAgg: 'yes' as unknown as boolean, lateral: true },
-      },
-    } as unknown as ReturnType<typeof getTestContract>;
+    // The cast on `'yes'` is deliberate — we're feeding an invalid value
+    // through a valid-typed contract to exercise the runtime check.
+    const contract = withCapabilities(getTestContract(), {
+      sql: { jsonAgg: 'yes' as unknown as boolean, lateral: true },
+    });
 
     expect(selectIncludeStrategy(contract)).toBe('multiQuery');
   });
 
   it('treats explicit `false` as not enabled', () => {
-    const contract = {
-      ...getTestContract(),
-      capabilities: {
-        sql: { jsonAgg: true, lateral: false },
-      },
-    } as unknown as ReturnType<typeof getTestContract>;
+    const contract = withCapabilities(getTestContract(), {
+      sql: { jsonAgg: true, lateral: false },
+    });
 
     expect(selectIncludeStrategy(contract)).toBe('correlated');
   });

packages/3-extensions/sql-orm-client/test/integration/include.test.ts

@@ -67,6 +67,41 @@ type NumericPostField = import('../../src/types').NumericFieldNames<
 >;
 
 describe('integration/include', () => {
+  it(
+    'depth-1 include against an emitted contract fires a single SQL execution (regression guard for namespaced capability lookup)',
+    async () => {
+      // Guards against regressing the fix that taught `selectIncludeStrategy`
+      // to read capability flags from the contract's `targetFamily` and
+      // `target` namespaces. The default `getTestContract()` carries
+      // `postgres: { lateral: true, jsonAgg: true, ... }` — the emitter's
+      // actual output shape. Prior to the fix, this exact test would fire
+      // 2 SQL queries instead of 1, against a real driver.
+      await withCollectionRuntime(async (runtime) => {
+        const users = createUsersCollection(runtime);
+
+        await seedUsers(runtime, [{ id: 1, name: 'Alice', email: 'alice@example.com' }]);
+        await seedPosts(runtime, [{ id: 10, title: 'Post A', userId: 1, views: 100 }]);
+
+        runtime.resetExecutions();
+        const rows = await users.include('posts').all();
+
+        expect(rows).toEqual([
+          {
+            id: 1,
+            name: 'Alice',
+            email: 'alice@example.com',
+            invitedById: null,
+            address: null,
+            posts: [{ id: 10, title: 'Post A', userId: 1, views: 100, embedding: null }],
+          },
+        ]);
+        // The point of the test: 1 execution, not N+1.
+        expect(runtime.executions).toHaveLength(1);
+      });
+    },
+    timeouts.spinUpPpgDev,
+  );
+
   it(
     'include() stitches one-to-many and one-to-one relations from real rows',
     async () => {