TML-2683: add sql-orm-client whole-shape-assertions rule + index + golden-rule pointer

Author: tensordreams

.agents/rules/README.md

@@ -57,6 +57,7 @@ Rules below are listed by bare filename; the canonical file is `.agents/rules/<n
 - `vitest-expect-typeof.mdc` — Type test patterns
 - `test-mocking-patterns.mdc` — Test-only assertions and mocking patterns
 - `prefer-object-matcher.mdc` — Prefer object matchers over multiple individual expect().toBe() calls
+- `sql-orm-client-whole-shape-assertions.mdc` — In sql-orm-client tests, assert the whole result shape (`toEqual`/snapshot) with explicit `select`
 - `prefer-to-throw.mdc` — Use `expect().toThrow()` instead of manual try/catch blocks
 - `no-tautological-tests.mdc` — Avoid tests that only restate fixture input structure
 - `use-ast-factories.mdc` — Use factory functions for creating AST nodes instead of manual object creation

.agents/rules/sql-orm-client-whole-shape-assertions.mdc

@@ -0,0 +1,77 @@
+---
+description: Prefer whole-result-shape assertions with explicit select projections in sql-orm-client tests
+globs: ["packages/3-extensions/sql-orm-client/**/*.test.ts", "test/integration/test/sql-orm-client/**/*.test.ts"]
+alwaysApply: false
+---
+
+# Assert the whole result shape, with explicit projections
+
+In `sql-orm-client` tests (unit and integration), assert the **entire** result with `toEqual`
+(or an inline/file snapshot), and pin the projected columns with explicit `.select(...)` (varargs:
+`.select('id', 'name')`) on the root collection **and** on every included relation. Order
+deterministically with
+`.orderBy((c) => c.<baseColumn>.asc())` so `toEqual` on arrays is reliable.
+
+Avoid partial matchers (`toMatchObject`, `toHaveProperty` / `not.toHaveProperty`, lone
+single-field `toBe`/`toEqual`) as the primary assertion for a query result, and avoid `toEqual`
+on a full model row with no `select`.
+
+## Why
+
+Two failure modes this prevents:
+
+1. **Partial matchers pass silently on wrong shapes.** `toMatchObject({ id: 1, role: 'admin' })`
+   succeeds even if the row carries an extra field it shouldn't, a sibling-variant field that
+   should have been dropped, or a misspelled key elsewhere. The result's *shape* is the contract;
+   assert all of it.
+2. **`toEqual` without `select` couples every test to the full model field set.** Adding one field
+   to a model then breaks every test that asserted a full row of it — tests far from the change.
+   An explicit `.select(...)` makes the asserted columns intentional, so unrelated field
+   additions don't ripple into unrelated tests, while `toEqual` still catches any wrong/missing
+   value *within* the selected shape.
+
+Together: `select` + `toEqual` is both **complete** (catches extra/missing/wrong fields in the
+projected shape) and **stable** (immune to unrelated model growth).
+
+## Good
+
+```ts
+const rows = await db.orm.Account
+  .select('id', 'name')
+  .orderBy((a) => a.id.asc())
+  .include('members', (m) => m.select('id', 'kind', 'role', 'plan').orderBy((u) => u.id.asc()))
+  .all();
+
+expect(rows).toEqual([
+  { id: 1, name: 'Acme', members: [
+    { id: 1, kind: 'admin', role: 'superadmin' }, // variant fields surface per the row's variant;
+    { id: 2, kind: 'regular', plan: 'free' },      // pinning them locks the variant shape
+  ] },
+  { id: 2, name: 'Empty', members: [] },
+]);
+```
+
+## Avoid
+
+```ts
+const member = members.find((m) => m.id === 1)!;
+expect(member).toMatchObject({ id: 1, role: 'admin' }); // passes even if `member` has stray fields
+expect(member).not.toHaveProperty('plan');               // enumerating absences ≠ asserting the shape
+```
+
+## Notes
+
+- **Polymorphic includes:** variant-specific fields surface according to each row's variant. Pin
+  them with `select` + `toEqual` so the per-variant shape (e.g. admin rows carry `role`, regular
+  rows carry `plan`) is asserted, not assumed.
+- **Determinism:** order by a **base-table** column (typically `id`). Don't order by a variant
+  table's column on a variant-narrowed collection unless that path is the thing under test.
+- **Snapshots** (`toMatchInlineSnapshot`) are an acceptable alternative to a hand-written `toEqual`
+  for large shapes, but still pair them with explicit `select` so the snapshot is stable.
+- This is about *result-shape* assertions. Asserting a single scalar (a count, a thrown error
+  code, a boolean) with `toBe`/`expect().rejects` is fine and expected.
+- **Relationship to `prefer-object-matcher.mdc`:** that rule consolidates scattered
+  `expect().toBe()` calls into one matcher repo-wide. This rule is the stricter, sql-orm-client
+  specialization for *query results*: the result row is the contract, so assert it **completely**
+  with `toEqual` + `select` rather than partially with `toMatchObject`. `toMatchObject` is still
+  fine for the non-result, constructed-object cases `prefer-object-matcher` targets.

AGENTS.md

@@ -53,6 +53,7 @@ The repo keeps a single canonical home for each kind of agent surface, with pres
 - Don't reexport from one file in another, except in `exports/` folders.
 - Don't branch on target; use adapters: `.agents/rules/no-target-branches.mdc`.
 - Keep tests concise; omit "should": `.agents/rules/omit-should-in-tests.mdc`.
+- In sql-orm-client tests, assert the whole result shape (`toEqual`/snapshot) with explicit `select`: `.agents/rules/sql-orm-client-whole-shape-assertions.mdc`.
 - Keep docs current (READMEs, rules, links): `.agents/rules/doc-maintenance.mdc`.
 - Prefer links to canonical docs over long comments.