docs(drivers): measure the ContainsAny phantom-leg sweep across eight door pins (#17967)

Fixes #17879

Clause-②: no

A **measurement** card, not a defect sweep. Every reading below was
taken on disk against
`origin/main@bdb247d`, control first, with each leg's direction
predicted before it was run.

## Headline

**No detector was swapped, anywhere — and that is the measured result,
not a gap.**

The phantom half is real on all eight doors. The `ContainsAny` template
landed by #17876 closes
**none** of them: seven are defeated by one mechanism, and the eighth is
already masked today.

## The mechanism, measured

`ContainsAny` distributes over a union, because `T` is naked in its
array/record arms. So a
door that is a union answers `boolean`, and **both** of the family's
assertion forms accept
`boolean`:

```text
const leg: boolean = false        compiles   -> the `= false` half stays GREEN
boolean extends true ? never : X  picks X    -> the conditional half stays GREEN
```

Calibration, measured twice in independent runs (a line that errors =
that leg reddens):

```text
shape                                    IsAny leg   ContainsAny leg
any                       (bare)         RED         RED     <- control fires
any[]                                    green       RED     <- template works
Record[string, any]                      green       RED     <- template works
Record[string, any] | null               green       GREEN   <- template INERT
Record[string, any] | undefined          green       GREEN   <- template INERT
any[] | undefined                        green       GREEN   <- template INERT
```

Seven of my eight doors are unions — either a not-found arm (`| null`)
or an optional
parameter (`| undefined`). That is why the swap buys nothing on them.

## Per-file measurement

`resolves to` is read off the door itself; `CONTROL` puts that door back
to a **bare** `any`;
`NESTED` puts it back to a nested one. Counts are errors **in that
file**.

| # | file | door resolves to | CONTROL (bare any) | NESTED | swap? |
|---|---|---|---|---|---|
| 1 | `sql-driver-distinct-filter-narrowing` | `FilterCondition \|
undefined` | **3 errors** — fires | **0** | no — union **and** saturated
|
| 2 | `sql-driver-update-declared-null` | `Record[string, unknown] \|
null` | **2 errors** — fires | **1** (`Equals` only) | no — union |
| 3 | `sqlite-wasm-16711-inherited-object-def-keys` | nested `any`
**today** (see below) | **7 errors** — fires | n/a | no — RED on `main`
|
| 4 | `sqlite-wasm-distinct-filter-narrowing` | `FilterCondition \|
undefined` | **2 errors** — fires | **0** | no — union **and** saturated
|
| 5 | `sqlite-wasm-update-declared-null` | `Record[string, unknown] \|
null` | **2 errors** — fires | **1** (`Equals` only) | no — union |
| 6 | `turso-driver-options-door` (17 doors) | `DriverOptions \|
undefined` | row reds (TS1360) — fires | **0** | no — union |
| 7 | `turso-driver-update-declared-null` | `Record[string, unknown] \|
null` | **2 errors** — fires | **1** (`Equals` only) | no — union |
| 8 | `turso-update-missing-id` | `Record[string, unknown] \| null` |
**2 errors** — fires | **1** (`Equals` only) | no — union |

**The control fired on all eight**, so no reading here is void. In every
NESTED run a shadow
`ContainsAny` leg was compiled alongside the real one: it stayed green
in all seven applicable
cases, which is the direct measurement that the swap would have bought
nothing.

Files 1 and 4 carry a second, independent reason:
`ContainsAny[FilterCondition]` is already
`true`, because `FilterCondition` is an open map with `any` values by
contract. The detector is
**saturated** on the correct door and cannot separate it from a
regression at all.

## File 3 — the strongest reading in the sweep

`SqliteWasmDriver.initObjects`'s parameter does not merely *regress* to
a nested `any`. It
**is** one, on `main`, today:

```text
objects: Array[{ name: string; fields?: Record[string, any]; tenancy?: any;
                 indexes?: any[]; lifecycle?: any }]
```

Four sub-doors are masked (`fields`, `tenancy`, `indexes`, `lifecycle`),
and the file's two
`IsAny` legs are green about all four. `ContainsAny` there is **RED at
baseline** — it would go
red on `main`, not on a regression — so the swap is not available.
Un-masking the door is a
change to `SqlDriver.initObjects` in `@objectstack/driver-sql`, a
**non-test file**, which is
outside this card (stop condition: *the fix would require touching a
non-test file*).

Worth recording: the existing pair already covers the `objects: any[]`
shape — the **element**
leg catches it, since the element of `any[]` is `any`.

## The two excluded files — read-only, nothing touched

`driver-memory` is under the #5499 investment freeze, so this is a
source read plus the
calibration table above — no probe, no run, no file touched in that
package. It is a
**derived** reading, flagged as such:

| door | resolves to | would the template work? |
|---|---|---|
| `InMemoryDriver.update` | `Record[string, unknown] \| null` | no —
union |
| `InMemoryDriver.upsert` | `Record[string, unknown]` | **yes** |
| `InMemoryDriver.find` | `Record[string, unknown][]` | **yes** |
| `InMemoryDriver.findOne` | `Record[string, unknown] \| null` | no —
union |
| `InMemoryDriver.create` | `Record[string, unknown]` | **yes** |

So the frozen pair holds **the only three doors in the whole population
where #17876's template
is effective exactly as written**. That is a question for triage, not
for this PR.

## What this PR changes

Eight comment blocks, one per file, recording that file's measured
reading where the next
author will look. **No detector, no assertion and no type was changed**
— so this diff cannot
move any verdict, and it does not preempt the repair decision.

## Verification

```text
pnpm --filter @objectstack/driver-sql typecheck            exit 0   (tsc --noEmit)
pnpm --filter @objectstack/driver-sqlite-wasm typecheck    exit 0   (tsc --noEmit)
pnpm --filter @objectstack/driver-turso typecheck          exit 0   (tsc --noEmit)
driver-sql test          176 files / 2602 passed, 11 + 164 skipped
driver-sqlite-wasm test   29 files /  518 passed
driver-turso test         52 files / 1248 passed
                          VERDICT command-exit 0 (shared verify lock)
pnpm lint (repo-wide, `eslint . --no-inline-config`)       exit 0   in 2m0s
dispatch-gates derived families                            49 of 52 PASS
```

The three not in that 49 exited **3 = PREREQUISITE NOT MET**, which is
neither a pass nor a
failure: `check:dual-build-cjs-loads`, `check:lean-entry-closure` and
`check:type-check-debt`
each need a full-monorepo `pnpm build` this worktree never did. **NOT
MEASURED**, declared to
CI, which builds fresh. None can be reached by a comment-only diff.

Ablation hygiene: every mutation leg proved its edit on disk before the
run and proved the
artifact carried it (`scripts/ablation-dist-preflight.mjs`, driver-sql
rebuilt per wasm leg);
every restore leg was proved by blob hash against `HEAD` and a
whole-tree `git status`.

## Changeset — measured, not assumed

`skip-changeset`. `npm pack --dry-run --json` in all three packages: the
intersection of
(changed paths) and (shipped paths) is **empty**, with a positive
control present in every
listing. `files[]` is `["dist","README.md","CHANGELOG.md"]` in all three
— `src/**` never
ships, and no `.test.` file appears in any tarball. Zero published bytes
move.

## Acceptance notes

- **Not filed, recommended for the seat:** `SqlDriver.initObjects`'s
parameter masks four
sub-doors (`fields`, `tenancy`, `indexes`, `lifecycle`). Measured, live
on `main`, with a
pin that is green about it. The fix is a non-test narrowing in
`@objectstack/driver-sql`.
- **Not filed, observation:** #17876's own `findOne` leg
(`ContainsAny[SqlFindOne] = false`, door `Record[string, unknown] |
null`) has the same
union blind spot measured here. Its array and bare-record legs are
unaffected and sound.
- The repair itself is **not** proposed here: both candidates were
measured, and either also
changes the two files #17876 already landed, which is outside this
card's eight.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01RuoNSXUbBoWHkNS4AknTrM

---
_Generated by [Claude
Code](https://claude.ai/code/session_01RuoNSXUbBoWHkNS4AknTrM)_

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-musk

packages/drivers/driver-sql/src/sql-driver-distinct-filter-narrowing.test.ts

@@ -51,6 +51,25 @@ import { SqlDriver } from './index.js';
 /** `true` for `any` and for nothing else — `0 extends 1 & T` holds only there. */
 type IsAny<T> = 0 extends 1 & T ? true : false;
 
+/**
+ * [#17879] MEASURED — this door's `IsAny` half is a PHANTOM half, and the
+ * `ContainsAny` detector (#17876) does NOT close it here. On disk, against
+ * this file's own driver, with both directions predicted before running:
+ *
+ *   door resolves to      `FilterCondition | undefined`
+ *   CONTROL  `filters?: any`                 3 errors here (the `narrowed`
+ *                                             leg + both TS2578) => it fires
+ *   NESTED   `filters?: Record<string, any>`  0 errors here => no half at all
+ *   the same run with `ContainsAny` swapped in: still 0 => it buys nothing
+ *
+ * TWO reasons, both measured: `ContainsAny` distributes over a union, so an
+ * optional parameter (`X | undefined`) answers `boolean`, which passes both
+ * assertion forms; and `ContainsAny<FilterCondition>` is already `true` —
+ * the contract type is an open map (`[key: string]: any`), so the detector is
+ * SATURATED on the correct door and cannot separate it from a regression.
+ * No swap was made. The two measured repairs are in the #17879 report.
+ */
+
 describe('SqlDriver.distinct takes a bare FilterCondition (#6320)', () => {
   let driver: SqlDriver;
   let knexInstance: Knex;

packages/drivers/driver-sql/src/sql-driver-update-declared-null.test.ts

@@ -49,6 +49,25 @@ import { SqlDriver } from './index.js';
 
 /** `any` defeats ordinary assignability checks; this is the standard detector. */
 type IsAny<T> = 0 extends 1 & T ? true : false;
+
+/**
+ * [#17879] MEASURED — `sqlUpdateIsAny` below is a PHANTOM half against a
+ * NESTED regression, and `ContainsAny` (#17876) does NOT close it. On disk,
+ * reverting only this door in `sql-driver.ts`:
+ *
+ *   door resolves to  `Record<string, unknown> | null`
+ *   CONTROL  `Promise<any>`                       2 errors (both legs)
+ *                                                  => the instrument fires
+ *   NESTED   `Promise<Record<string, any> | null>` 1 error (`Equals` only)
+ *                                                  => half the protection
+ *   the same NESTED run with a `ContainsAny` leg alongside: still GREEN
+ *
+ * WHY it does not close: `ContainsAny` distributes over the union, so
+ * `Record<string, any> | null` answers `boolean` (`true` for the record arm,
+ * `false` for `null`) — and `const leg: boolean = false` compiles. Every
+ * door carrying the not-found arm has this shape. No swap was made; the two
+ * measured repairs are in the #17879 report.
+ */
 /** Exact (mutual, non-`any`) type equality. */
 type Equals<A, B> = (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? true : false;
 

packages/drivers/driver-sqlite-wasm/src/sqlite-wasm-16711-inherited-object-def-keys.test.ts

@@ -36,6 +36,25 @@ import { SqliteWasmDriver } from './index.js';
 /** `any` defeats ordinary assignability checks; this is the standard detector. */
 type IsAny<T> = 0 extends 1 & T ? true : false;
 
+/**
+ * [#17879] MEASURED — the strongest reading in the sweep: this door does not
+ * merely regress to a nested `any`, it ALREADY IS one, today, and the two
+ * `IsAny` legs below are green about it.
+ *
+ *   door resolves to  `{ name: string; fields?: Record<string, any>;
+ *                        tenancy?: any; indexes?: any[]; lifecycle?: any }[]`
+ *   `IsAny` on the array and on the element   both `false` => both legs green
+ *   `ContainsAny` on either                   `true`      => RED AT BASELINE
+ *   CONTROL  `objects: any`                   7 errors here => it fires
+ *
+ * So the #17876 swap cannot be made here: it does not go red on a REGRESSION,
+ * it goes red on `main`. Four sub-doors (`fields`, `tenancy`, `indexes`,
+ * `lifecycle`) are masked in `SqlDriver.initObjects`'s own parameter literal,
+ * and un-masking them is a NON-TEST change in `@objectstack/driver-sql` —
+ * outside #17879's scope, reported instead. Note the pair below already
+ * covers the `objects: any[]` shape: the ELEMENT leg catches it.
+ */
+
 type InitObjectsArg = Parameters<SqliteWasmDriver['initObjects']>[0];
 type InitObjectsElement = InitObjectsArg extends Array<infer E> ? E : never;
 

packages/drivers/driver-sqlite-wasm/src/sqlite-wasm-distinct-filter-narrowing.test.ts

@@ -34,6 +34,23 @@ import { SqliteWasmDriver } from './index.js';
 /** `true` for `any` and for nothing else. */
 type IsAny<T> = 0 extends 1 & T ? true : false;
 
+/**
+ * [#17879] MEASURED — the phantom half, and why `ContainsAny` (#17876) is
+ * inert here. Measured across the `.d.ts` boundary this file exists to pin,
+ * with `@objectstack/driver-sql` rebuilt for each leg:
+ *
+ *   door resolves to      `FilterCondition | undefined`
+ *   CONTROL  `filters?: any`                 2 errors here (the `narrowed`
+ *                                             leg + TS2578) => it fires
+ *   NESTED   `filters?: Record<string, any>`  0 errors here, with or without
+ *                                             `ContainsAny` swapped in
+ *
+ * `ContainsAny` distributes over the `| undefined` an optional parameter
+ * carries, answering `boolean`; and it is saturated on the correct door
+ * anyway, since `FilterCondition` is an open map. No swap was made — see the
+ * #17879 report for the two measured repairs.
+ */
+
 describe("SqliteWasmDriver inherits distinct's bare-FilterCondition parameter (#6320)", () => {
   let driver: SqliteWasmDriver;
   let knexInstance: Knex;

packages/drivers/driver-sqlite-wasm/src/sqlite-wasm-update-declared-null.test.ts

@@ -37,6 +37,22 @@ import { SqliteWasmDriver } from './index.js';
 
 /** `any` defeats ordinary assignability checks; this is the standard detector. */
 type IsAny<T> = 0 extends 1 & T ? true : false;
+
+/**
+ * [#17879] MEASURED — `wasmUpdateIsAny` below is a PHANTOM half against a
+ * NESTED regression, and `ContainsAny` (#17876) does NOT close it. Measured
+ * through the inherited `.d.ts`, rebuilding `@objectstack/driver-sql` per leg:
+ *
+ *   door resolves to  `Record<string, unknown> | null`
+ *   CONTROL  `Promise<any>`                       2 errors (both legs)
+ *                                                  => the instrument fires
+ *   NESTED   `Promise<Record<string, any> | null>` 1 error (`Equals` only)
+ *   the same NESTED run with a `ContainsAny` leg alongside: still GREEN
+ *
+ * `ContainsAny` distributes over the not-found arm, so the regressed door
+ * answers `boolean` and `const leg: boolean = false` compiles. No swap was
+ * made; the two measured repairs are in the #17879 report.
+ */
 /** Exact (mutual, non-`any`) type equality. */
 type Equals<A, B> = (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? true : false;
 

packages/drivers/driver-turso/src/turso-driver-options-door.test.ts

@@ -62,6 +62,23 @@ import type { DriverOptions } from '@objectstack/spec/data';
 /** `any` defeats ordinary assignability checks; this is the standard detector. */
 type IsAny<T> = 0 extends 1 & T ? true : false;
 
+/**
+ * [#17879] MEASURED — `Door<T>` below asks `IsAny`, which is a PHANTOM half
+ * against a NESTED regression, and swapping in `ContainsAny` (#17876) does
+ * NOT close it. Measured on the `find` row, on disk:
+ *
+ *   every one of the 17 doors resolves to `DriverOptions | undefined`
+ *   CONTROL  `options?: any`                 that row reds (TS1360) => fires
+ *   NESTED   `options?: Record<string, any>`  0 errors here — the row still
+ *                                             answers `'DriverOptions'`
+ *   the same NESTED run with `ContainsAny` inside `Door<T>`: still `'DriverOptions'`
+ *
+ * `ContainsAny` distributes over the `| undefined` every optional parameter
+ * carries, so the regressed door answers `boolean`, and `boolean extends true`
+ * is `false` — the detector reads it as "no `any` here". No swap was made;
+ * the two measured repairs are in the #17879 report.
+ */
+
 /**
  * Reports what a given `options` door actually is. `'any'` for a widened door,
  * `'DriverOptions'` for one that matches the base contract exactly.

packages/drivers/driver-turso/src/turso-driver-update-declared-null.test.ts

@@ -42,6 +42,22 @@ import { TursoDriver } from './turso-driver.js';
 
 /** `any` defeats ordinary assignability checks; this is the standard detector. */
 type IsAny<T> = 0 extends 1 & T ? true : false;
+
+/**
+ * [#17879] MEASURED — `tursoUpdateIsAny` below is a PHANTOM half against a
+ * NESTED regression, and `ContainsAny` (#17876) does NOT close it. On disk,
+ * reverting only this override:
+ *
+ *   door resolves to  `Record<string, unknown> | null`
+ *   CONTROL  `Promise<any>`                       2 errors (both legs)
+ *                                                  => the instrument fires
+ *   NESTED   `Promise<Record<string, any> | null>` 1 error (`Equals` only)
+ *   the same NESTED run with a `ContainsAny` leg alongside: still GREEN
+ *
+ * `ContainsAny` distributes over the not-found arm, so the regressed door
+ * answers `boolean`, which `= false` accepts. No swap was made; the two
+ * measured repairs are in the #17879 report.
+ */
 /** Exact (mutual, non-`any`) type equality. */
 type Equals<A, B> = (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? true : false;
 

packages/drivers/driver-turso/src/turso-update-missing-id.test.ts

@@ -104,6 +104,22 @@ import { asLibsqlClient, makeLibsqlSqliteStub, type LibsqlSqliteStub } from './l
 
 /** `any` defeats ordinary assignability checks; this is the standard detector. */
 type IsAny<T> = 0 extends 1 & T ? true : false;
+
+/**
+ * [#17879] MEASURED — `transportUpdateIsAny` below is a PHANTOM half against
+ * a NESTED regression, and `ContainsAny` (#17876) does NOT close it. On disk,
+ * reverting only `RemoteTransport.update`:
+ *
+ *   door resolves to  `Record<string, unknown> | null`
+ *   CONTROL  `Promise<any>`                       2 errors (both legs)
+ *                                                  => the instrument fires
+ *   NESTED   `Promise<Record<string, any> | null>` 1 error (`Equals` only)
+ *   the same NESTED run with a `ContainsAny` leg alongside: still GREEN
+ *
+ * `ContainsAny` distributes over the not-found arm, so the regressed door
+ * answers `boolean`, which `= false` accepts. No swap was made; the two
+ * measured repairs are in the #17879 report.
+ */
 /** Exact (mutual, non-`any`) type equality. */
 type Equals<A, B> = (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? true : false;