# Content temporarily unavailable
# PR #2043 retained observer snapshot oracle review

Reviewed source head: the commit that adds this record on
`perf-lazy-observer-snapshot`. The production change is unchanged from
`069633263`. This record adds the fixed-seed campaign and this audit.

## Contract and evidence

`LiveQueryObserver.getSnapshot()` returns one object for each revision. A
consumer can keep that object and read `data` or `state` for the first time
after the Collection changes and after the observer builds newer snapshots.
The first read, in either order, must show the rows that were visible when the
observer built the snapshot. `data` must list the rows of `state.values()` in
the same order. A single-result query keeps only the first such row.

The authority is the snapshot contract in
`packages/db/src/live-query-observer.ts`: "Each snapshot owns a captured view
of `state`/`data`, so reading an older snapshot cannot expose rows from a later
revision." #1542 broke this law with a getter that read the live Collection on
first access. The external review of #1542 reproduced that failure.

The oracle is
`packages/db/tests/live-query-observer-snapshot-oracle.property.test.ts`. Its
model is a sorted map from key to version. The model records its rows at each
`capture` step, next to the unread production snapshot. At the end, the driver
reads each retained snapshot in a generated order and compares both properties
with the recorded rows.

## Mutant results

All mutant runs used the reviewed test file. The production source was
restored after each run.

| Mutant | Outcome |
| --- | --- |
| The `state` getter reads `collection.entries()` on first access (the #1542 design) | Assertion failure in all four generated cases at fixed seed 2043, path `0:2:1:1:1`, and in the pinned history. The calibration test passed. |
| The `state` and `data` getters read the observer's latest entries | Assertion failure in 5 of 6 tests (recorded by the implementation run before this record). |

Direct replay of the first mutant with `TANSTACK_DB_ORACLE_SEED=2043`,
`TANSTACK_DB_ORACLE_PATH=0:2:1:1:1` and
`TANSTACK_DB_ORACLE_PROPERTY=live-query-observer.retained-snapshot` reproduced
the same counterexample: snapshot 0 captured no rows, but its `state` showed
row `a`.

## ORC-012 requirement audit

| Requirement | Outcome |
| --- | --- |
| ORC-001 | Applicable. The law and its authority are above. The claim is limited to the shared observer over a local-only Collection behind an ordered live query. Hydration seeds, persisted status and framework wiring have other owners, which the oracle prose names. |
| ORC-002 | Applicable. The expected rows come from the model's sorted map. The model does not import the observer, its entry collection or its ordering. |
| ORC-003 | Applicable. The opening prose states the law, the model, the history grammar, the production path, the checkpoint and the limits. The ownership table maps each contract row to its observation. |
| ORC-004 | Applicable. The grammar has upsert, delete and capture over keys `a`..`d` and versions `0`..`9`, with a generated read order and a generated choice of `data` or `state` first. The pinned history reconstructs the case of a snapshot read after several newer snapshots. No ablation check is executable. An ablation of the read-order axis would remove the `state`-first case, which the live-read mutant needs. That gap is accepted for this bounded grammar. |
| ORC-005 | Applicable. The driver calls the production `getSnapshot()` with and without a subscriber. It reads the public `data` and `state` properties at the end of the history. |
| ORC-006 | Applicable. The calibration test gives the checker a snapshot whose properties read the live Collection, and the checker rejects it. The two production mutants above fail at the intended checkpoint. Each outcome is an assertion failure. |
| ORC-007 | Applicable. Each generated case runs the same property and budget twice: once with fixed seed 2043 and once with an unseeded or replay seed through `oraclePropertyOptions`. The replay interface accepts the seed, the path and the property name. The direct replay above reproduced the reported failure. The property does not use `fc.commands`. |
| ORC-008 | Applicable. The model keeps only the visible key-to-version map. The order of keys is derived from the map, so the model keeps no separate order state. |
| ORC-009 | Applicable. "Capture" is a model-only step. It means one call to `getSnapshot()` whose result is kept unread. "Recorded rows" are the model rows at that step. |
| ORC-010 | Applicable, with a gap. The harness cleans up the observer, the query and the source in a `finally` block after the comparison. If cleanup throws after an assertion failure, the cleanup error replaces the assertion error. The cleanup calls are local-only Collection cleanups, and no run showed a cleanup failure. Shrinking reduced the mutant counterexample to one upsert and one capture, and the replay reproduced it. |
| ORC-011 | Inapplicable. No reviewer named a fault that the model and production could share. |
| ORC-013 | Inapplicable. The oracle protects no threshold or range law. |
| ORC-014 | Inapplicable. No controlled provider supplies a premise. |

## Unresolved

- No per-adapter test proves that an adapter never reads `state` for a
  `data`-only consumer. The allocation counts in the PR were taken with scratch
  tests. A permanent check needs a test seam in production, which this PR does
  not add.