TanStack

Content temporarily unavailable

Explicit SQLite storage targets: oracle review

Reviewed code commit: 6b0192c19924e231049364cd5ef1fde7094245e0 Scope: PR #2069 follow-up for the exported SQLite persistence adapter and its Browser and Electron receiving paths.

The approved law is that an adapter data operation states whether it addresses an eager Collection or a claimed persisted cache generation. A managed target must carry its physical storage ID and claim ID on every read and write. Once that claim is collected, the operation rejects before it can recreate rows, metadata, or catalog state. An explicitly eager Collection may use the same ID bytes; no prefix is reserved. This is a new lower-level API contract, not proof that all third-party adapters honor claims.

The contract-by-history-by-path-by-observation claim is bounded as follows: after a real SQLite claim, write, rotation, and collection, each of eleven core adapter data methods rejects the retired managed target, including through a reopened adapter. At each rejection checkpoint, the old row and tombstone tables and eight per-ID catalogs remain absent. The same test accepts explicit eager reuse of that ID while the managed target still rejects. A Browser coordinator history checks both leader and follower local mutations retain the claim through transaction construction; a real SQLite Browser receiver accepts a claimed mutation and rejects a late one without recreating old storage. An in-process Electron IPC receiver checks target forwarding under protocol v6. The native OPFS tests receive claim and hydration histories but do not enumerate all adapter operations.

RequirementOutcome for this change
ORC-001 authority and limitsThe design decision above is documented in the core README and the SQLite coverage-map owner. The oracle prose names eager reuse, managed rejection, and the native-host limits.
ORC-002 independent judgmentThe expected outcome comes from the caller's declared target and claim lifecycle. The real-SQLite oracle compares physical tables and catalog rows; it does not call the production target resolver to derive expectations. Existing fixtures decode target IDs for older, unrelated row laws.
ORC-003 literate responsibilitiesThe SQLite resume-snapshot oracle explains the law, fixed history, real adapter path, physical observations, and settled checkpoints beside its test. The Browser coordinator oracle explains why local transaction construction must preserve the claim; the composed Browser receiver checks durable rows.
ORC-004 generated grammarNot triggered by the new fixed target histories. Existing generated-history dimensions and models were migrated to the new adapter signature without changing their claims.
ORC-005 production path and observationReal node:sqlite exercises all eleven core methods after collection and reopened reads and writes. Browser tests exercise local leader, follower RPC, and a real wa-sqlite durability path. Electron tests exercise the in-process main/renderer bridge.
ORC-006 calibrationA temporary bare-ID fallback mutant failed at the first post-collection read. A temporary eager reset-target mutant failed at the managed-reset target comparison. The follower claim-loss mutant failed at the follower success checkpoint; the original request returned success. These were assertion failures, not timeouts or setup failures; each mutant was restored.
ORC-007 campaigns and replayNot triggered by the new fixed histories. The affected existing generated properties remained in their configured suites; no seed, path, or run budget changed here.
ORC-008 stateful-model minimalityNot triggered: this change adds a discriminated production API target but no reference-model state or transition.
ORC-009 vocabularyThe tests and documentation use Collection, persisted cache generation, persisted cache claim, physical storage ID, and rotation in the glossary's senses. The target kind is caller intent, not a new lifecycle state.
ORC-010 failure and cleanupThe SQLite history closes its database while preserving the primary failure. The real Browser receiving history uses failure-preserving cleanup for claims, coordinator, database, and temporary directory.
ORC-011 second formulationA recording adapter alone could accept the wrong eager target. The real-SQLite Browser receiver independently checks durable row and catalog effects; Electron IPC is a separate transport cut. These do not prove arbitrary custom adapters.
ORC-012 review evidenceThis record is tied to the exact code commit above; the later documentation commit does not change that reviewed code.
ORC-013 boundary distinctionBare ordinary and cache-shaped IDs reject; explicit eager reuse of a collected physical ID succeeds; the old managed target still rejects. This distinguishes claim authority from a reserved-name rule.
ORC-014 controlled-premise handoffThe Browser recording witness reaches both routes, and its claim-preservation premise is received by real wa-sqlite for a leader mutation. Follower RPC over real OPFS and actual Electron process execution remain outside this cut.

Local verification on the reviewed code: SQLite core 963 passed and one todo; Browser 261 passed; Electron 105 passed; Browser persisted conformance 113 passed; Electric 680, Query 627, Node 178, React Native 200, Expo 62, Capacitor 92, and Tauri 64 passed. Native Chromium OPFS claim/hydration 27, Electric 16, and leader-close 6 passed. Six affected package typechecks, changed-file lint without errors, formatting, and diff checks passed. The Electron binary was unavailable for its real-process E2E suite. The documentation link checker reported 13 existing links outside its /docs boundary and no new link failure. A workspace package-manager attempt received a private-registry 403, so tests used installed binaries; the documented local checks are actual executions.

Open boundaries: the API still permits a caller to choose an explicit eager target using a retired physical ID. That is the approved escape hatch for arbitrary eager Collection IDs, not an accidental managed fallback. A custom adapter can ignore the target contract, and a direct coordinator caller without a registered managed claim can request eager semantics. Native cross-tab scheduling and real Electron process behavior remain separate receiving cuts in the coverage map. This evidence closes the accidental bare-ID-to-eager adapter fallback for the exercised paths; it does not claim universal cache-generation lifecycle closure.