@terreno/mcp 0.31.0 → 56.0.0-beta.2

package/src/docs/versioned/next/implementationPlans/rtk-to-syncdb-migration-docs.md

@@ -1,14 +1,13 @@
 # Implementation Plan: RTK Deprecation and SyncDB Migration Docs
 
-**Status:** Draft — blocked; the syncdb source does not exist yet
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1007
+**Status:** In progress — syncdb available on `release-56.0.0`; reference + migration guide drafted
 **Priority:** Critical (gates most of Wave 1)
 **Effort:** Big batch
 **Owner:** unassigned
 **Created:** 2026-07-27
 **Program:** [OSS launch](oss-launch-program.md)
-**Depends on:** a merged `@terreno/syncdb` package. PR [#869](https://github.com/flourishhealth/terreno/pull/869) was the delivery vehicle but is **closed, not merged** (checked 2026-08-09); no `syncdb/` package exists on `master`. This IP stays blocked until a syncdb PR lands and `git log --oneline master | rg -i syncdb` shows the merged package.
-**RTK deprecation flag:** **Blocked** — this IP *is* the RTK deprecation. Nothing here can be written until syncdb lands, because the public surface of `@terreno/syncdb` is not final until then.
+**Depends on:** a merged `@terreno/syncdb` package. It was **not** delivered by PR #869 (closed); it lives on the **`release-56.0.0`** launch branch (`syncdb/`), so this IP is authored on and targets `release-56.0.0`, not `master`.
+**RTK deprecation flag:** **Unblocked on `release-56.0.0`** — this IP *is* the RTK deprecation. The `@terreno/syncdb` public surface is now final on `release-56.0.0` (`syncdb/src/index.ts`, `syncdb/src/react/index.ts`, `syncdb/src/testing/index.ts`); docs are written against that source.
 
 ## Goal
 
@@ -34,8 +33,8 @@ Scope is documentation, deprecation signalling, and migration tooling — not sy
 | M3 | Auth vs data migration | **C** — Better Auth first, then syncdb |
 | M4 | `docs/reference/rtk.md` (→ P7 **A**) | **Remove from the public reference index** — no legacy reference page. Existing RTK consumers use **`docs/how-to/migrate-rtk-to-syncdb.md`** only; do not maintain a parallel RTK reference path in launch docs |
 | M5 | SDK codegen command | **A** — `bun run sdk` keeps working |
-| M6 | Codemod | **B (reaffirmed 2026-08-09)** — no migration script or codemod. The migration is agent-assisted: ship the *context* an AI coding agent needs to perform the migration in a specific app (the syncdb reference, verified before/after pairs, and the `upgrading-terreno` skill), not a mechanical transform. See "Migration strategy" below |
-| M7 | Local-first default | **A** if #869 ships local-first only (verify against merged code) |
+| M6 | Codemod | **B (reaffirmed 2026-08-09)** — no migration script/codemod. Ship the *context* an AI agent needs (the syncdb reference, verified before/after pairs, and the `upgrading-terreno` skill), not a mechanical transform. See "Migration strategy" below |
+| M7 | Local-first default | **A — confirmed local-first only.** `@terreno/syncdb` has no server-first mode and no opt-in flag: the local store is the UI source of truth (`syncdb/src/index.ts:4-7`, `syncdb/README.md:3`) and `SyncDbConfig` (`syncdb/src/client.ts`) exposes no server-first option |
 
 ## Architecture
 
@@ -58,49 +57,55 @@ Every document below currently describes an RTK-shaped world and must be reconci
 | `README.md` architecture diagram | `@terreno/rtk` box | `@terreno/syncdb` box |
 | `mcp-server` resources + bootstrap templates | RTK store wiring | syncdb client wiring |
 
+### Surface map reconciliation (Task 1.2, checked against `release-56.0.0`)
+
+The pre-merge surface map above was a hypothesis. Reconciled against the merged
+`syncdb/` on `release-56.0.0`:
+
+- **Three entry points, not one:** `@terreno/syncdb` (client, protocol/status/conflict
+  types, `betterAuthAdapter`, key providers/codecs, persister factories, transports,
+  `wipeLocalData`, `generateMutationId`, `listConflicts`, `OUTBOX_TABLE`),
+  `@terreno/syncdb/react` (`SyncDbProvider`, `useSyncDbClient`, `useEntity`, `useQuery`,
+  `useEntityIds`, `useMutate`, `useSyncStatus`, `useConflicts`, `useSyncDebugLog`), and
+  `@terreno/syncdb/testing` (`createFakeTransport`).
+- **Backend surface #869's hypothesis under-specified:** `SyncApp` (`GET /sync/snapshot`,
+  `POST /sync/mutate`, `POST /sync/mutate/batch`, `GET /sync/key`, `POST /sync/entities`),
+  `RealtimeApp` (Socket.io `sync:subscribe`/`sync:mutate`/`sync:delta`/`sync:ack`/`sync:nack`/
+  `sync:mutateBatch`), the required `syncPlugin` + `isDeletedPlugin`, the `sync` modelRouter
+  config (owner/tenant/broadcast/custom scoping + `getUserScopes`/`snapshotFilter`), and
+  `ensureSyncIndexes()` plus the `SyncCounter`/`SyncMutation`/`SyncScopeMove`/`SyncKey`
+  bookkeeping models. All are documented in `docs/reference/syncdb.md`.
+- **Encryption at rest (web) is a real public surface:** AES-GCM codec, `createServerKeyProvider`
+  (default) / `createLocalKeyProvider`, `onDecryptFailure`. Documented.
+- **M5 confirmed:** `bun run sdk` still generates `store/openApiSdk.ts` for non-synced routes
+  (auth, profile, admin, AI, feature flags); synced collections use syncdb hooks instead.
+- **M7 confirmed:** local-first only (see the blocking-questions table).
+
 ### Migration strategy: AI-context-first (not codemods)
 
-The migration is delivered as **context for an AI coding agent to perform the
-migration in a specific app**, not as a script that mechanically transforms code.
-A one-size codemod is the wrong tool here: the RTK → syncdb move is not a
-find-and-replace. Writes change semantics (local-first, optimistic code gets
-*deleted*), conflicts and sync status are net-new concepts with app-specific UI,
-and auth migrates on its own schedule. Those are judgment calls an agent makes
-per screen with the right context — not transforms a codemod can apply blindly.
-
-Concretely, this IP ships three context artifacts and no migration script:
-
-1. **The syncdb reference** (`docs/reference/syncdb.md`) — the ground-truth API
-   surface the agent maps RTK calls onto.
-2. **The migration guide** (`docs/how-to/migrate-rtk-to-syncdb.md`) — organized by
-   *what the developer changes*, with **verified before/after pairs** taken from
-   the real `example-frontend` migration. These pairs are the highest-value
-   context: an agent generalizes from a correct concrete example far better than
-   from prose rules.
-3. **The `upgrading-terreno` skill** (owned by
-   [`upgrade-guides-and-skill`](upgrade-guides-and-skill.md)) — the procedure that
-   points an agent at the reference and guide, tells it to migrate one screen at
-   a time behind `USE_SYNCDB`, verify, and repeat. The skill encodes *how to
-   drive the migration*; it does not encode the edits themselves.
-
-Design rules that follow from this strategy:
-
-- **Every code sample must be real and compile against the merged syncdb** — an
-  agent will copy them, so an invented sample produces broken migrations at scale.
-- **Name what to delete, not just what to add.** The parts consumers get wrong
-  are the RTK patterns that become dead code (manual optimistic updates, write
-  spinners, refetch-after-mutate); the guide must call these out explicitly so an
-  agent removes them.
-- **Prefer decision tables and per-step checklists** (agent-followable) over long
-  narrative. The copy-pasteable checklist in step 11 doubles as an agent to-do
-  list.
-- **Keep the rollout unit small** — per screen via `USE_SYNCDB` — so an agent can
-  migrate, verify, and stop at any point.
-
-If a mechanical helper turns out to be genuinely safe for a narrow sub-step (for
-example a pure import rename during the support window), it may be added later as
-an *optional* convenience, but it is never the primary path and never a
-precondition for migrating.
+The migration is delivered as **context for an AI coding agent (and humans) to perform
+the migration in a specific app**, not as a script that mechanically transforms code.
+The RTK → syncdb move is not find-and-replace: writes change semantics (local-first;
+optimistic code gets *deleted*), conflicts and sync status are net-new concepts with
+app-specific UI, and auth migrates on its own schedule. Those are per-screen judgment
+calls, not blind transforms.
+
+This IP therefore ships three context artifacts and no migration script:
+
+1. **The syncdb reference** (`docs/reference/syncdb.md`) — the ground-truth API the agent
+   maps RTK calls onto.
+2. **The migration guide** (`docs/how-to/migrate-rtk-to-syncdb.md`) — organized by *what the
+   developer changes*, with **verified before/after pairs** from the real `example-frontend`
+   migration (RTK todos on `master` → `SyncTodosScreen` on `release-56.0.0`). An agent
+   generalizes far better from a correct concrete example than from prose.
+3. **The `upgrading-terreno` skill** (owned by [`upgrade-guides-and-skill`](upgrade-guides-and-skill.md))
+   — drives an agent to migrate one screen at a time behind a flag, verify, and repeat.
+
+Design rules that follow: every code sample is real and compiles against the merged
+syncdb; the guide names what to **delete** (manual optimistic updates, write spinners,
+refetch-after-mutate), not just what to add; prefer decision tables and per-step
+checklists over narrative; keep the rollout unit small (per screen). A mechanical helper
+may be added later for a narrow safe sub-step, but it is never the primary path.
 
 ### The migration guide's shape
 

package/src/docs/versioned/next/implementationPlans/syncdb-api-inventory.md

@@ -0,0 +1,303 @@
+# @terreno/syncdb API inventory (temporary)
+
+Working document for the RTK → syncdb migration. Lists every public export from the three package entry points, with source locations verified against `syncdb/src/`.
+
+## M5 — Does `bun run sdk` still work?
+
+**Yes.** The example app still generates RTK Query hooks from the backend OpenAPI spec:
+
+- `example-frontend/package.json:73` — `"sdk": "bun scripts/generate-sdk.ts && bun biome check --write scripts/generate-sdk.ts"`
+- `example-frontend/scripts/generate-sdk.ts:22` — runs `@rtk-query/codegen-openapi` against `openapi-config.ts`
+- `example-frontend/openapi-config.ts:11` — output is `./store/openApiSdk.ts`
+
+**What it generates now (post-migration):** typed RTK Query hooks for **non-synced** routes — Better Auth, `GET /auth/me`, admin, AI explorer, version config, feature-flag configuration, and any custom REST endpoints. Synced collections (e.g. todos) are **not** read or written through generated hooks; they use `@terreno/syncdb` hooks instead. `example-frontend/store/sdk.ts` still wraps `openApiSdk.ts` with tag enhancements and realtime wiring for endpoints that remain on RTK (todos realtime config is legacy/unused by the syncdb screen).
+
+## M7 — Local-first only vs opt-in?
+
+**Local-first only — there is no server-first mode and no opt-in flag.**
+
+The on-device TinyBase store is always the UI source of truth; reads come from local state, writes apply optimistically, and the server reconciles asynchronously.
+
+- `syncdb/src/index.ts:4-7` — package doc: "reads come from the local store, writes apply optimistically… the server is asynchronous reconciliation"
+- `syncdb/README.md:3-4` — "TinyBase MergeableStore … is the UI's source of truth"
+- `syncdb/src/client.ts:60-151` (`SyncDbConfig`) — no `mode`, `serverFirst`, or similar option
+
+---
+
+## `@terreno/syncdb` (`syncdb/src/index.ts`)
+
+### Client factory and constants
+
+| Symbol | Kind | Description | Source |
+|--------|------|-------------|--------|
+| `createSyncDb` | `function (config: SyncDbConfig): SyncDb` | Assemble the local-first client | `client.ts:281` |
+| `DEFAULT_RECONCILE_INTERVAL_MS` | `const` (5 min) | Default periodic reconcile interval | `client.ts:38` |
+| `DEFAULT_SEQ_JUMP_RECONCILE_MIN_INTERVAL_MS` | `const` (30s) | Seq-jump reconcile rate limit | `client.ts:41` |
+| `DEFAULT_TOMBSTONE_RETENTION_MS` | `const` (90 days) | Client tombstone compaction window | `client.ts:44` |
+| `DEFAULT_START_AUTH_RETRY_ATTEMPTS` | `const` (3) | `start()` auth-resolution retries | `client.ts:55` |
+| `DEFAULT_START_AUTH_RETRY_DELAY_MS` | `const` (250) | Delay between `start()` auth retries | `client.ts:56` |
+
+### `SyncDbConfig` fields
+
+| Field | Type | Default | Description | Source |
+|-------|------|---------|-------------|--------|
+| `name` | `string` | — (required) | Persisted database name | `client.ts:62` |
+| `collections` | `string[]` | — (required) | Collections to sync | `client.ts:64` |
+| `authProvider` | `AuthProvider` | — (required) | Token/user/auth-change surface | `client.ts:65` |
+| `baseUrl` | `string?` | — | Server origin; required unless `transport` + `httpChannel` injected | `client.ts:67` |
+| `transport` | `SyncTransport?` | socket transport from `baseUrl` | Transport override (tests) | `client.ts:69` |
+| `httpChannel` | `HttpChannel?` | from `baseUrl` | HTTP channel override | `client.ts:71` |
+| `persisterFactory` | `PersisterFactory?` | platform default | Persister override | `client.ts:73` |
+| `keyProvider` | `KeyProvider?` | server-derived via `/sync/key` | Web encryption key provider | `client.ts:75` |
+| `idbGetImpl` | test hook | — | IndexedDB read override (tests) | `client.ts:82` |
+| `idbSetImpl` | test hook | — | IndexedDB write override (tests) | `client.ts:83` |
+| `reconcileIntervalMs` | `number?` | `DEFAULT_RECONCILE_INTERVAL_MS` (5 min); `0` disables | Periodic reconcile timer | `client.ts:85` |
+| `seqJumpReconcileMinIntervalMs` | `number?` | `DEFAULT_SEQ_JUMP_RECONCILE_MIN_INTERVAL_MS` | Per-stream seq-jump rate limit | `client.ts:87` |
+| `now` | `() => number?` | `Date.now` | Injectable clock | `client.ts:89` |
+| `random` | `() => number?` | `Math.random` | Injectable RNG for backoff jitter | `client.ts:91` |
+| `debug` | `boolean \| SyncDebugLogOptions?` | `false` (off) | In-memory debug event log | `client.ts:98` |
+| `onAuthRequired` | `() => void?` | — | Fires once per auth-pause episode | `client.ts:104` |
+| `wipeOnSignOut` | `boolean?` | `false` | `signOut()` also wipes local data | `client.ts:111` |
+| `batchSize` | `number?` | `50` (server caps at 100) | Max mutations per batched drain | `client.ts:113` |
+| `haltQueueOnConflict` | `boolean?` | `false` | Conflict halts entire drain vs per-entity | `client.ts:119` |
+| `onDecryptFailure` | `() => void?` | wipe + re-bootstrap (with `console.warn`) | Override decrypt-failure recovery | `client.ts:129` |
+| `tombstoneRetentionMs` | `number?` | `DEFAULT_TOMBSTONE_RETENTION_MS`; `0` disables | Client tombstone compaction after reconcile | `client.ts:138` |
+| `startAuthRetryAttempts` | `number?` | `DEFAULT_START_AUTH_RETRY_ATTEMPTS`; `1` disables | `start()` user-id resolution attempts | `client.ts:148` |
+| `startAuthRetryDelayMs` | `number?` | `DEFAULT_START_AUTH_RETRY_DELAY_MS` | Delay between those attempts | `client.ts:150` |
+
+### `SyncDb` methods and properties
+
+| Member | Signature / type | Description | Source |
+|--------|------------------|-------------|--------|
+| `store` | `readonly SyncStore` | Local-first entity store | `client.ts:193` |
+| `outbox` | `readonly Outbox` | Durable mutation outbox | `client.ts:195` |
+| `debug` | `readonly SyncDebugLog \| undefined` | Debug log when `debug` enabled | `client.ts:270` |
+| `start` | `() => Promise<void>` | Resolve user, persist, connect, bootstrap | `client.ts:202` |
+| `stop` | `() => Promise<void>` | Disconnect, stop persistence, clear timers | `client.ts:204` |
+| `goOffline` | `() => void` | Simulated outage (local writes continue) | `client.ts:212` |
+| `goOnline` | `() => Promise<void>` | End simulated outage | `client.ts:218` |
+| `mutate` | `(args: MutateArgs) => {mutationId, id}` | Optimistic write + enqueue + replay | `client.ts:224` |
+| `reconcile` | `() => Promise<void>` | HTTP snapshot catch-up all streams | `client.ts:226` |
+| `forceResync` | `() => Promise<ForceResyncResult>` | Purge streams and re-bootstrap from 0 | `client.ts:233` |
+| `replayOutbox` | `() => Promise<void>` | Drain queued mutations now | `client.ts:235` |
+| `resolveConflict` | `({mutationId, strategy}) => void` | Apply `useServer` or `keepMine` | `client.ts:237` |
+| `retryFailed` | `({entityId}) => void` | Re-enable blocked entity queue | `client.ts:244` |
+| `signOut` | `() => Promise<void>` | Explicit teardown; optional wipe | `client.ts:254` |
+| `getSyncStatus` | `() => SyncStatus` | Aggregate sync state snapshot | `client.ts:256` |
+| `onStatusChange` | `(callback) => () => void` | Subscribe to connectivity/syncing changes | `client.ts:264` |
+
+### Supporting client types
+
+| Symbol | Kind | Source |
+|--------|------|--------|
+| `MutateArgs` | `interface` `{collection, operation, id?, data?}` | `client.ts:182` |
+| `ForceResyncSkipReason` | `type` union | `client.ts:162` |
+| `ForceResyncResult` | `interface` | `client.ts:170` |
+
+### Protocol, status, and conflict types (`types.ts`)
+
+| Symbol | Kind | Source |
+|--------|------|--------|
+| `SyncMutationOperation` | `type` `"create" \| "update" \| "delete"` | `types.ts:9` |
+| `SyncDelta` | `interface` | `types.ts:12` |
+| `SyncMutateRequest` | `interface` | `types.ts:35` |
+| `SyncAck` | `interface` | `types.ts:49` |
+| `SyncNackCode` | `type` | `types.ts:63` |
+| `SyncNack` | `interface` | `types.ts:66` |
+| `SyncMutateBatchRequest` | `interface` | `types.ts:94` |
+| `SyncMutateBatchResult` | `type` | `types.ts:107` |
+| `SyncMutateBatchResponse` | `interface` | `types.ts:116` |
+| `SyncSnapshotEntity` | `interface` | `types.ts:121` |
+| `SyncEntitiesResponse` | `interface` | `types.ts:129` |
+| `SyncSnapshotResponse` | `interface` | `types.ts:134` |
+| `SyncStreamInfo` | `interface` | `types.ts:156` |
+| `OutboxStatus` | `type` | `types.ts:164` |
+| `OutboxMutation` | `interface` | `types.ts:167` |
+| `SyncConflict` | `interface` | `types.ts:186` |
+| `ConflictResolutionStrategy` | `type` `"useServer" \| "keepMine"` | `types.ts:206` |
+| `SyncCollectionStatus` | `interface` | `types.ts:213` |
+| `SyncStatus` | `interface` | `types.ts:220` |
+| `AuthProvider` | `interface` | `types.ts:269` |
+
+### Store / outbox / wipe
+
+| Symbol | Kind | Source |
+|--------|------|--------|
+| `listConflicts` | `function` | `mutations/conflicts.ts:71` |
+| `generateMutationId` | `function` | `mutations/outbox.ts` (re-export `index.ts:75`) |
+| `Outbox` | `type` | `mutations/outbox.ts` |
+| `SyncStore` | `type` | `storage/store.ts` |
+| `OUTBOX_TABLE` | `const` | `storage/types.ts` |
+| `SyncEntity` | `type` | `storage/types.ts` |
+| `wipeLocalData` | `async function` | `storage/wipe.ts:19` |
+
+### Auth adapter
+
+| Symbol | Kind | Source |
+|--------|------|--------|
+| `betterAuthAdapter` | `function` | `auth/betterAuthAdapter.ts:39` |
+| `DEFAULT_AUTH_POLL_INTERVAL_MS` | `const` (5000) | `auth/betterAuthAdapter.ts:5` |
+| `BetterAuthAdapterOptions` | `interface` | `auth/betterAuthAdapter.ts:7` |
+| `BetterAuthClientLike` | `type` | `auth/types.ts` |
+| `BetterAuthGetSessionResult` | `type` | `auth/types.ts` |
+| `BetterAuthSessionAtomLike` | `type` | `auth/types.ts` |
+| `BetterAuthSessionDataLike` | `type` | `auth/types.ts` |
+| `BetterAuthSessionLike` | `type` | `auth/types.ts` |
+| `BetterAuthUserLike` | `type` | `auth/types.ts` |
+
+### Encryption and key providers
+
+| Symbol | Kind | Source |
+|--------|------|--------|
+| `AES_GCM_ENVELOPE_VERSION` | `const` | `crypto/aesGcmCodec.ts` |
+| `createAesGcmCodec` | `function` | `crypto/aesGcmCodec.ts` |
+| `PayloadIntegrityError` | `class` | `crypto/aesGcmCodec.ts` |
+| `UnknownEnvelopeVersionError` | `class` | `crypto/aesGcmCodec.ts` |
+| `identityCodec` | `const` | `crypto/identityCodec.ts` |
+| `createKeyProviderCodec` | `function` | `crypto/keyProviders.ts` |
+| `createLocalKeyProvider` | `function` | `crypto/keyProviders.ts` |
+| `createServerKeyProvider` | `function` | `crypto/keyProviders.ts` |
+| `DEFAULT_KEY_CACHE_DB_NAME` | `const` | `crypto/keyProviders.ts` |
+| `KeyProvider` | `interface` | `crypto/types.ts` |
+| `PayloadCodec` | `interface` | `crypto/types.ts` |
+
+### Persisters
+
+| Symbol | Kind | Source |
+|--------|------|--------|
+| `createDefaultPersisterFactory` | `function` | `persisters/defaultPersisterFactory.ts` |
+| `createEncryptedIndexedDbPersister` | `function` | `persisters/encryptedIndexedDbPersister.ts` |
+| `clearMemoryPersisterData` | `function` | `persisters/memoryPersister.ts` |
+| `createMemoryPersister` | `function` | `persisters/memoryPersister.ts` |
+| `memoryPersisterFactory` | `function` | `persisters/memoryPersister.ts` |
+| `DefaultPersisterFactoryConfig` | `type` | `persisters/types.ts` |
+| `PersisterFactory` | `type` | `persisters/types.ts` |
+
+### Transports and HTTP channel
+
+| Symbol | Kind | Source |
+|--------|------|--------|
+| `AuthRequiredError` | `class` | `sync/httpChannel.ts` |
+| `createHttpChannel` | `function` | `sync/httpChannel.ts` |
+| `FetchLike` | `type` | `sync/httpChannel.ts` |
+| `FetchSnapshotPageArgs` | `type` | `sync/httpChannel.ts` |
+| `HttpChannel` | `interface` | `sync/httpChannel.ts` |
+| `HttpChannelConfig` | `interface` | `sync/httpChannel.ts` |
+| `createSocketTransport` | `function` | `sync/socketTransport.ts` |
+| `SocketTransportConfig` | `interface` | `sync/socketTransport.ts` |
+| `DEFAULT_BATCH_SIZE` | `const` | `sync/transport.ts` |
+| `DEFAULT_MUTATION_TIMEOUT_MS` | `const` | `sync/transport.ts` |
+| `SendMutationBatchResult` | `type` | `sync/transport.ts` |
+| `SendMutationResult` | `type` | `sync/transport.ts` |
+| `SyncTransport` | `interface` | `sync/transport.ts` |
+| `TransportStatus` | `interface` | `sync/transport.ts` |
+
+### Debug log types
+
+| Symbol | Kind | Source |
+|--------|------|--------|
+| `SyncDebugDirection` | `type` | `debug/debugLog.ts:43` |
+| `SyncDebugEvent` | `interface` | `debug/debugLog.ts:46` |
+| `SyncDebugEventType` | `type` | `debug/debugLog.ts:27` |
+| `SyncDebugLog` | `interface` | `debug/debugLog.ts` |
+| `SyncDebugLogOptions` | `interface` | `debug/debugLog.ts` |
+| `SyncDebugRecordInput` | `interface` | `debug/debugLog.ts` |
+| `SyncDebugSnapshot` | `interface` | `debug/debugLog.ts` |
+| `SyncDebugStats` | `interface` | `debug/debugLog.ts` |
+
+**Not exported (internal):** `resolveConflict` (mutation writer), `writeConflict`, cursor mutators, IndexedDB helpers, debug broadcast bridge — use `client.resolveConflict` / `useConflicts().resolve` instead.
+
+---
+
+## `@terreno/syncdb/react` (`syncdb/src/react/index.ts` → hooks + provider)
+
+| Symbol | Kind | Description | Source |
+|--------|------|-------------|--------|
+| `SyncDbProvider` | `React.FC<SyncDbProviderProps>` | Provides client to descendants | `provider.tsx:13` |
+| `SyncDbProviderProps` | `interface` `{client, children}` | Provider props | `provider.tsx:7` |
+| `useSyncDbClient` | `() => SyncDb` | Access client from context | `provider.tsx:18` |
+| `useEntity` | `<T>(collection, id) => UseEntityResult<T>` | Subscribe to one entity | `hooks.ts:117` |
+| `UseEntityResult` | `interface` `{data, deleted, seq, isPending}` | `useEntity` return shape | `hooks.ts:105` |
+| `useQuery` | `<T>(collection, options?) => T[]` | Subscribe to collection (decoded data) | `hooks.ts:170` |
+| `UseQueryOptions` | `interface` `{filter?, sort?, includeDeleted?}` | Query options | `hooks.ts:149` |
+| `useEntityIds` | `<T>(collection, options?) => string[]` | Stable id list for virtualization | `hooks.ts:221` |
+| `useMutate` | `(collection) => UseMutateResult` | `{create, update, remove}` | `hooks.ts:266` |
+| `UseMutateResult` | `interface` | Mutation helpers | `hooks.ts:253` |
+| `useSyncStatus` | `() => SyncStatus` | Reactive aggregate status | `hooks.ts:296` |
+| `useConflicts` | `() => UseConflictsResult` | `{conflicts, resolve}` | `hooks.ts:328` |
+| `UseConflictsResult` | `interface` | Conflict hook return | `hooks.ts:320` |
+| `useSyncDebugLog` | `() => UseSyncDebugLogResult` | Debug log subscription | `hooks.ts:379` |
+| `UseSyncDebugLogResult` | `interface` `{enabled, events, stats, log, clear}` | Debug hook return | `hooks.ts:355` |
+
+---
+
+## `@terreno/syncdb/testing` (`syncdb/src/testing/index.ts`)
+
+| Symbol | Kind | Description | Source |
+|--------|------|-------------|--------|
+| `createFakeTransport` | `() => FakeTransport` | In-memory transport double | `testing/fakeTransport.ts:74` |
+| `FakeTransport` | `interface` extends `SyncTransport` | Test controls + recording | `testing/fakeTransport.ts:32` |
+| `FakeMutationResponder` | `type` | Single-mutation responder | `testing/fakeTransport.ts:22` |
+| `FakeBatchResponder` | `type` | Batch responder | `testing/fakeTransport.ts:27` |
+
+---
+
+## Reference migration (`example-frontend`)
+
+Before paths are from `origin/master`; after paths are on the current branch.
+
+### (a) Store setup
+
+| | Path | What changed |
+|---|------|--------------|
+| **Before** | `example-frontend/store/index.ts` (master) | `generateAuthSlice(terrenoApi)`, `createOfflineMiddleware`, Redux persist, RTK Query reducer |
+| **After** | `example-frontend/store/index.ts` | `generateBetterAuthSlice`, RTK only for non-synced API + app state |
+| **After** | `example-frontend/store/syncdb.ts` | `createSyncDb({authProvider: betterAuthAdapter(...), collections: ["todos"], ...})` |
+
+### (b) Provider wiring
+
+| | Path | What changed |
+|---|------|--------------|
+| **Before** | `example-frontend/app/_layout.tsx` (master) | Redux `Provider` only; todos screen uses RTK hooks directly |
+| **After** | `example-frontend/app/(tabs)/index.tsx` | `SyncDbProvider client={syncDb}` wraps `SyncTodosScreen` |
+| **After** | `example-frontend/app/_layout.tsx` | `syncDb.start()` / `stop()` on login; `SyncDbProvider` + `SyncHealthToast` at root when `userId` set |
+
+### (c) Reads
+
+| | Path | What changed |
+|---|------|--------------|
+| **Before** | `example-frontend/app/(tabs)/index.tsx` (master) | `useGetTodosQuery({}, {skip: !userId})`, `isLoading`, `refetch` |
+| **After** | `example-frontend/components/SyncTodosScreen.tsx` | `useEntityIds<SyncTodo>("todos", {filter, sort})` + per-row `useEntity("todos", id)` |
+
+### (d) Writes
+
+| | Path | What changed |
+|---|------|--------------|
+| **Before** | `example-frontend/app/(tabs)/index.tsx` (master) | `usePostTodosMutation`, `usePatchTodosByIdMutation`, `useDeleteTodosByIdMutation`, `.unwrap()`, per-item `isUpdating` spinners |
+| **After** | `example-frontend/components/SyncTodosScreen.tsx` | `useMutate("todos")` → `create({data})`, `update({id, data})`, `remove({id})`; gated on `useSyncDbReady()` |
+
+### (e) Conflict UI
+
+| | Path | What changed |
+|---|------|--------------|
+| **Before** | master todos screen | `useServerStatus` undismissed conflicts (RTK offline slice) |
+| **After** | `example-frontend/components/SyncConflictsController.tsx` | App-wide conflict sheet controller |
+| **After** | `example-frontend/app/_layout.tsx` | `ConflictSheet` via `SyncHealthToast` `renderConflictsModal` |
+| **After** | `example-frontend/components/SyncTodosScreen.tsx` | `SyncStatusBanner` `onOpenConflicts` → `openConflicts("todos")` |
+
+### (f) Sync-status UI
+
+| | Path | What changed |
+|---|------|--------------|
+| **Before** | master todos screen | `useServerStatus`, `OfflineBanner`, request `isLoading` / `isFetching` / `RefreshControl` |
+| **After** | `example-frontend/components/SyncTodosScreen.tsx` | `useSyncStatus()` + `SyncStatusBanner` |
+| **After** | `example-frontend/components/SyncHealthToast.tsx` | Persistent toasts for conflicts, failures, backlog |
+| **After** | `example-frontend/components/syncHealthSignals.ts` | Toast signal computation |
+
+### Not covered by the reference migration
+
+- **Auth migration details** — Better Auth session atom bridge in `store/syncdb.ts`; login still uses `@terreno/rtk` Better Auth slice (documented in migration guide §7).
+- **Feature flags** — OpenFeature bridge in `_layout.tsx` (`OpenFeatureBridge` + `useTerrenoFeatureFlags`); no per-screen flag gating todos (syncdb-only).
+- **Other screens** — Profile, admin, AI explorer, consent flow still use generated RTK hooks (`store/sdk.ts`).
+- **SDK realtime config for todos** — `TODO_REALTIME_ENDPOINTS` in `sdk.ts` remains but is unused by `SyncTodosScreen`.
+- **Debug tooling** — `example-frontend/app/syncdb-debug.tsx` (`useSyncDebugLog`).