@terreno/mcp 0.30.0 → 56.0.0-beta.0

package/src/docs/versioned/next/how-to/migrate-rtk-to-syncdb.md

@@ -0,0 +1,445 @@
+# How to Migrate from @terreno/rtk to @terreno/syncdb
+
+This guide is **AI-context-first**: it is written for an agent (or human) performing a screen-by-screen migration, not as a codemod. Work through one concern at a time — reads, then writes, then conflicts, then sync-status UX — and delete RTK-era code as you go.
+
+`@terreno/syncdb` supersedes `@terreno/rtk` for **data synchronization** (CRUD reads/writes, offline queue, realtime convergence). It does not replace the generated OpenAPI SDK, Better Auth Redux wiring, or feature-flag infrastructure.
+
+## 1. Before you start
+
+| Decision | Requirement | Why |
+|----------|-------------|-----|
+| **Better Auth first?** | Recommended before or in parallel with data migration | `betterAuthAdapter` is the shipped `AuthProvider`; socket sessions work cleanly with `RealtimeApp({betterAuth})`. Legacy JWT sockets still work during transition. |
+| **Backend version** | `@terreno/api` with `SyncApp`, `RealtimeApp`, `syncPlugin`, `isDeletedPlugin` | Without backend sync registration, the client has nothing to talk to. |
+| **MongoDB replica set** | Required for `RealtimeApp` change streams | Single-node replset is fine for dev. |
+| **Per-collection rollout** | One synced collection at a time | REST and sync share the same write path; migrate screen-by-screen. |
+| **Redux** | Keep Redux for auth, feature flags, app state; drop RTK Query for migrated collections | See §2. |
+
+**Auth can migrate before data (M3).** A typical two-step order:
+
+1. **Step A — Auth:** Move login/session to Better Auth (`generateBetterAuthSlice`, `betterAuthAdapter`, `syncDb.start()` on login). Screens can still read/write via RTK Query during this step.
+2. **Step B — Data:** For each collection, replace RTK Query hooks with syncdb hooks and delete the RTK path for that screen.
+
+The example app completed both steps; todos are syncdb-only while profile/admin still use generated RTK hooks.
+
+Reference: [`docs/reference/syncdb.md`](../reference/syncdb.md), and the package [`syncdb/README.md`](https://github.com/flourishhealth/terreno/blob/release-56.0.0/syncdb/README.md).
+
+## 2. Install and configure
+
+### Install packages
+
+```bash
+bun install @terreno/syncdb
+bunx expo install expo-sqlite   # native persistence — install in the app, rebuild native
+```
+
+### Create the sync client
+
+**After** (`example-frontend/store/syncdb.ts`):
+
+```typescript
+import {baseUrl} from "@terreno/rtk";
+import {betterAuthAdapter, createSyncDb} from "@terreno/syncdb";
+import {betterAuthClient} from "@/lib/betterAuth";
+
+const authProvider = betterAuthAdapter(betterAuthClient, {pollIntervalMs: 60_000});
+
+export const syncDb = createSyncDb({
+  authProvider,
+  baseUrl,
+  collections: ["todos"],
+  name: "terreno-example",
+  debug: __DEV__ ? {capacity: 1000} : false,
+});
+```
+
+### Start/stop on auth
+
+**After** (`example-frontend/app/_layout.tsx`):
+
+```typescript
+useEffect(() => {
+  if (!userId) {
+    return;
+  }
+  let stopped = false;
+  syncDb
+    .start()
+    .then(() => {
+      if (!stopped) {
+        setSyncDbReady(true);
+      }
+    })
+    .catch((error) => {
+      console.error("[syncdb] Failed to start client", error);
+    });
+  return () => {
+    stopped = true;
+    setSyncDbReady(false);
+    void syncDb.stop();
+  };
+}, [userId, syncDbStartAttempt]);
+```
+
+Gate writes with a ready flag (`useSyncDbReady`) so `mutate()` is not called before `start()` resolves a user.
+
+### Wrap screens with `SyncDbProvider`
+
+**After** (`example-frontend/app/(tabs)/index.tsx`):
+
+```tsx
+import {SyncDbProvider} from "@terreno/syncdb/react";
+import {syncDb} from "@/store/syncdb";
+
+const TodosScreen = () => (
+  <SyncDbProvider client={syncDb}>
+    <SyncTodosScreen />
+  </SyncDbProvider>
+);
+```
+
+The example also mounts `SyncDbProvider` at the root (`_layout.tsx`) for `SyncHealthToast`.
+
+### Redux store: keep vs remove
+
+| Keep on Redux | Remove for migrated collections |
+|---------------|--------------------------------|
+| `generateBetterAuthSlice` / session | `generateAuthSlice` (JWT) once Better Auth ships |
+| `terrenoApi` reducer for **non-synced** routes | `useGetTodosQuery` / todo mutations |
+| `createOfflineMiddleware` + offline slice | `realtimeList` / `realtimeDocument` for that collection |
+| Feature-flag / app-state slices | Per-screen `isLoading` spinners tied to RTK mutations |
+
+**Before** (`origin/master:example-frontend/store/index.ts`): `generateAuthSlice`, `createOfflineMiddleware`, offline payload sessionStorage.
+
+**After** (`example-frontend/store/index.ts`): `generateBetterAuthSlice`, `terrenoApi` only — no offline middleware.
+
+## 3. Reads
+
+There is no `isLoading` for reads after bootstrap — data is already in the local store.
+
+### List reads
+
+**Before** (`origin/master:example-frontend/app/(tabs)/index.tsx`):
+
+```typescript
+const {data: todosData, isLoading, refetch, isFetching} = useGetTodosQuery({}, {skip: !userId});
+const todos = todosData?.data ?? [];
+```
+
+**After** (`example-frontend/components/SyncTodosScreen.tsx`):
+
+```typescript
+import {useEntity, useEntityIds} from "@terreno/syncdb/react";
+
+const incompleteIds = useEntityIds<SyncTodo>("todos", {
+  filter: (t) => !t.completed,
+  sort: sortByCreatedDesc,
+});
+
+// Per row:
+const {data} = useEntity<SyncTodo>("todos", id);
+```
+
+For small lists, `useQuery` is fine:
+
+```typescript
+import {useQuery} from "@terreno/syncdb/react";
+const todos = useQuery<Todo>("todos", {filter: (t) => !t.completed});
+```
+
+`filter` / `sort` run in JS — there are no server query params. Tombstones are excluded unless `{includeDeleted: true}`.
+
+### Delete this RTK read code
+
+- `useGetTodosQuery` / `useGet*Query` for the migrated collection
+- `isLoading`, `isFetching`, `refetch`, `RefreshControl` wired to list fetch
+- `skip: !userId` guards on list queries (replace with `useSyncDbReady` on writes; reads are safe once bootstrapped)
+- `realtimeList("todos")` / `realtimeDocument("todos")` in `store/sdk.ts` for that collection
+
+## 4. Writes
+
+Writes are synchronous from the UI's perspective: local apply + outbox enqueue + background replay.
+
+### Create / update / delete
+
+**Before** (`origin/master:example-frontend/app/(tabs)/index.tsx`):
+
+```typescript
+const [createTodo, {isLoading: isCreating}] = usePostTodosMutation();
+const [updateTodo] = usePatchTodosByIdMutation();
+const [deleteTodo] = useDeleteTodosByIdMutation();
+
+await createTodo({title, completed: false}).unwrap();
+await updateTodo({id, completed: true}).unwrap();
+await deleteTodo(id).unwrap();
+```
+
+**After** (`example-frontend/components/SyncTodosScreen.tsx`):
+
+```typescript
+import {generateMutationId} from "@terreno/syncdb";
+import {useMutate} from "@terreno/syncdb/react";
+
+const {create, update, remove} = useMutate("todos");
+
+const id = generateMutationId();
+create({data: {_id: id, title, completed: false, created: DateTime.now().toISO()}});
+update({id, data: {completed: true}});
+remove({id});
+```
+
+Client-minted `_id` on creates lets the optimistic row render before the server acks.
+
+### Delete this RTK write code
+
+- `usePost*Mutation`, `usePatch*Mutation`, `useDelete*Mutation` for the migrated collection
+- `.unwrap()` / try-catch around mutation promises for happy-path UX
+- **`isLoading` / `isCreating` / `isUpdating` spinners on write buttons** — syncdb writes do not await the server
+- Manual optimistic cache updates (`updateQueryData`, `upsertQueryData`, temporary local rows in component state)
+- `refetch()` or tag invalidation after mutate (`invalidatesTags` for that collection)
+- `createOfflineMiddleware` endpoint list entries for that collection (`configureOfflineMutationEndpoints`)
+- `If-Unmodified-Since` / 409 handling in custom mutation code (conflicts move to `useConflicts()`)
+
+Server rejection surfaces later as outbox nacks — conflicts in `useConflicts()`, terminal failures in `getSyncStatus().failedCount`.
+
+## 5. Conflicts
+
+A **conflict** means the client's `baseVersion` (last seen `_syncSeq`) disagrees with the server. The server returns a `conflict` nack:
+
+- HTTP: `POST /sync/mutate` → **409** with `{nack: {code: "conflict", serverDoc, serverSeq, ...}}`
+- Socket: `sync:nack` with `code: "conflict"`
+
+The client records the conflict locally; the UI must let the user pick a side.
+
+### Strategies
+
+| Strategy | When to use |
+|----------|-------------|
+| `useServer` | Accept canonical server data (or tombstone if server deleted the doc) |
+| `keepMine` | Re-enqueue local changes with a fresh `baseVersion` |
+
+```typescript
+import {useConflicts} from "@terreno/syncdb/react";
+
+const {conflicts, resolve} = useConflicts();
+resolve({mutationId, strategy: "useServer"});
+resolve({mutationId, strategy: "keepMine"});
+```
+
+### Minimum UI
+
+The example app uses:
+
+- `SyncConflictsController` — single app-wide sheet state (`example-frontend/components/SyncConflictsController.tsx`)
+- `ConflictSheet` rendered from `SyncHealthToast` (`example-frontend/app/_layout.tsx`)
+- `SyncStatusBanner` conflict badge → `openConflicts("todos")` (`example-frontend/components/SyncTodosScreen.tsx`)
+
+Copy that pattern or build equivalent: show local vs server fields, two resolution actions, block further edits on conflicted entities until resolved.
+
+## 6. Sync status
+
+Replace **request-loading UX** with **sync-state UX**.
+
+| RTK era | Syncdb era |
+|---------|------------|
+| `isLoading` on queries | No list loading spinner (data is local) |
+| `useOfflineStatus` / `useServerStatus` | `useSyncStatus()` |
+| `OfflineBanner` on fetch failure | `SyncStatusBanner` + `SyncHealthToast` |
+| Pull-to-refresh `refetch()` | Optional `client.forceResync()` for support tooling |
+
+**After** (`example-frontend/components/SyncTodosScreen.tsx`):
+
+```typescript
+import {useSyncStatus} from "@terreno/syncdb/react";
+import {SyncStatusBanner} from "@terreno/ui";
+
+const syncStatus = useSyncStatus();
+
+<SyncStatusBanner
+  isOnline={syncStatus.isOnline}
+  queuedCount={syncStatus.queuedCount}
+  conflictCount={syncStatus.conflictCount}
+  failedCount={syncStatus.failedCount}
+  paused={syncStatus.paused}
+  draining={syncStatus.draining}
+  sentThisDrain={syncStatus.sentThisDrain}
+  totalThisDrain={syncStatus.totalThisDrain}
+  onOpenConflicts={openConflictSheet}
+  onAuthRequired={handleAuthRequired}
+/>
+```
+
+`SyncHealthToast` (`example-frontend/components/SyncHealthToast.tsx`) adds persistent toasts for per-collection conflicts/failures and an initial "Syncing…" toast with optional force reload.
+
+`paused: "auth"` means replay is halted until the same user re-authenticates — wire `onAuthRequired` to your login flow.
+
+## 7. Auth
+
+**Auth can ship before data migration.** Complete Better Auth + `betterAuthAdapter` first; keep RTK Query for reads/writes until each screen migrates.
+
+### Better Auth adapter
+
+**After** (`example-frontend/store/syncdb.ts`):
+
+```typescript
+import {betterAuthAdapter, createSyncDb} from "@terreno/syncdb";
+import {betterAuthClient} from "@/lib/betterAuth";
+
+const authProvider = betterAuthAdapter(syncAuthClient, {pollIntervalMs: 60_000});
+
+export const syncDb = createSyncDb({authProvider, baseUrl, collections: ["todos"], name: "terreno-example"});
+```
+
+`betterAuthAdapter` implements `AuthProvider`:
+
+- `getToken()` / `getUserId()` — read session per request (not cached)
+- `onAuthChange` — session atom subscription (example bridges `$store.atoms.session`)
+- `refresh()` — one silent refresh per auth-pause episode
+
+### Token storage
+
+Better Auth session tokens live in the Better Auth client (`@terreno/rtk` `createBetterAuthClient`):
+
+- **Native:** `expo-secure-store`
+- **Web:** `@react-native-async-storage/async-storage`
+
+Syncdb does not store tokens itself — it calls `authProvider` on every transport/HTTP request.
+
+### Socket auth and `sync:auth-expired`
+
+On connect, the socket transport sends the bearer token from `getToken()`. When the server's session re-validation sweep finds an expired/disabled session, it emits `sync:auth-expired` then disconnects (`api/src/realtime/sessionRevalidation.ts`). The client maps this to `paused: "auth"` — **no local wipe**, outbox preserved (INV-2).
+
+### Backend
+
+```typescript
+new RealtimeApp({betterAuth: {auth, userModel: User}})
+```
+
+Required for Better Auth socket sessions. Legacy JWT sockets continue to work without it.
+
+## 8. Codegen
+
+### Does `bun run sdk` still work?
+
+**Yes.** `example-frontend/package.json` still defines:
+
+```json
+"sdk": "bun scripts/generate-sdk.ts && bun biome check --write scripts/generate-sdk.ts"
+```
+
+It runs `@rtk-query/codegen-openapi` against `openapi-config.ts` and writes `store/openApiSdk.ts`.
+
+### What changes post-migration
+
+| Still generated | Stop using for migrated collections |
+|-----------------|-------------------------------------|
+| Auth routes, `GET /auth/me`, admin, AI explorer, version config, feature flags | `useGetTodosQuery`, `usePostTodosMutation`, etc. |
+| Custom REST / RPC endpoints | Todo `realtimeList` / `realtimeDocument` wiring in `store/sdk.ts` |
+
+Keep running `bun run sdk` after backend route changes — non-synced screens still import from `store/sdk.ts`.
+
+Workflow:
+
+```bash
+# Backend running on port 4000
+cd example-frontend && bun run sdk
+```
+
+## 9. Feature flags
+
+Post-migration, feature flags stay on `@terreno/rtk` + OpenFeature — **not** on syncdb.
+
+**After** (`example-frontend/app/_layout.tsx`):
+
+```typescript
+import {OpenFeatureProvider} from "@openfeature/react-sdk";
+import {useTerrenoFeatureFlags} from "@terreno/rtk";
+
+const OpenFeatureBridge = ({children, socket}) => {
+  const bridgeUserId = useSelector(selectBetterAuthUserId) ?? undefined;
+  useTerrenoFeatureFlags(terrenoApi, {skip: !bridgeUserId, socket, userId: bridgeUserId});
+  return <OpenFeatureProvider domain="feature-flags">{children}</OpenFeatureProvider>;
+};
+```
+
+See [`docs/reference/feature-flags.md`](../reference/feature-flags.md) and [`docs/how-to/add-feature-flags.md`](add-feature-flags.md).
+
+**Example app gap:** todos do **not** gate on a feature flag — `SyncTodosScreen` is syncdb-only. For a gradual rollout, add a boolean flag and render the RTK screen when off, syncdb screen when on (see §10). The reference migration intentionally skipped flag wiring to keep one data path for e2e tests.
+
+## 10. Rollback
+
+### Per-screen feature flag
+
+Ship both implementations behind a flag:
+
+- Flag **off** → legacy RTK Query screen
+- Flag **on** → syncdb screen
+
+Both bundles ship until you flip the default and delete the RTK path.
+
+The example app does **not** use this pattern for todos.
+
+### What local data survives
+
+| Event | Local IndexedDB / SQLite | Outbox |
+|-------|------------------------|--------|
+| Logout / 401 | **Kept** (INV-2) | **Kept** — same user can sign back in and replay |
+| Different-user login | **Wiped** | **Wiped** |
+| `signOut()` default | **Kept** | **Kept** |
+| `signOut()` with `wipeOnSignOut: true` | **Wiped** | **Wiped** |
+| Schema version mismatch | **Wiped** + re-bootstrap | Re-built |
+| Decrypt failure (web, default) | **Wiped** + re-bootstrap | Re-built |
+
+`wipeLocalData` clears store tables, persisted databases, and cached encryption keys (`syncdb/src/storage/wipe.ts`).
+
+Rolling back a **screen** to RTK does not automatically clear syncdb data — stale local todos may still exist until user switch or explicit wipe. Plan for that if you flip the flag off in production.
+
+## 11. Checklist
+
+Copy and track per collection:
+
+```
+[ ] 1. Backend: isDeletedPlugin + syncPlugin on schema
+[ ] 2. Backend: modelRouter sync scope configured
+[ ] 3. Backend: SyncApp + RealtimeApp registered; Mongo replica set running
+[ ] 4. Backend: ensureSyncIndexes succeeds at startup
+[ ] 5. Frontend: @terreno/syncdb installed; expo-sqlite in app (native)
+[ ] 6. Frontend: createSyncDb client + betterAuthAdapter
+[ ] 7. Frontend: syncDb.start()/stop() wired to auth in root layout
+[ ] 8. Frontend: SyncDbProvider wraps migrated screens
+[ ] 9. Reads: useGet*Query → useQuery / useEntityIds + useEntity
+[ ] 10. Writes: usePost/Patch/Delete*Mutation → useMutate().create/update/remove
+[ ] 11. Deleted RTK: mutation isLoading spinners, refetch-after-mutate, offline middleware entries, realtime cache patches
+[ ] 12. Conflicts: useConflicts + resolution UI (ConflictSheet or equivalent)
+[ ] 13. Sync status: useSyncStatus + SyncStatusBanner / health toasts (not query isLoading)
+[ ] 14. Auth: Better Auth session + onAuthRequired → re-login when paused
+[ ] 15. Codegen: bun run sdk still run for non-synced routes; remove todo hooks from screens
+[ ] 16. Feature flags: OpenFeature bridge still fed via useTerrenoFeatureFlags (if used)
+[ ] 17. Rollback plan: feature flag or accept stale local data on revert
+[ ] 18. Verify: CRUD, offline create/edit/delete, reconnect, conflict both strategies, user switch
+```
+
+## Backend prerequisites (detail)
+
+Before a collection can sync:
+
+- [ ] `isDeletedPlugin` on schema (soft delete required)
+- [ ] `syncPlugin` on schema (`_syncSeq` stamping)
+- [ ] `modelRouter("/path", Model, {sync: {scope: ...}})` three-argument form
+- [ ] Custom scopes include `snapshotFilter`
+- [ ] `new SyncApp({getUserScopes?})` for tenant/custom scopes
+- [ ] `new RealtimeApp({betterAuth?})` + MongoDB replica set
+- [ ] No `updateMany`, `deleteMany`, `deleteOne`, `findOneAndDelete`, or `bulkWrite` on synced models
+
+## What stays on @terreno/rtk
+
+- Generated OpenAPI SDK for non-synced routes
+- Better Auth Redux slice (`generateBetterAuthSlice`)
+- Feature flags (`useTerrenoFeatureFlags` / `useFeatureFlags`)
+- Socket connection for flags and legacy realtime (until removed)
+- `@terreno/rtk` is not being removed
+
+## Further reading
+
+- [`docs/reference/syncdb.md`](../reference/syncdb.md) — full API reference
+- [`syncdb/README.md`](https://github.com/flourishhealth/terreno/blob/release-56.0.0/syncdb/README.md) — architecture and protocol detail
+- [`docs/how-to/configure-better-auth.md`](configure-better-auth.md) — Better Auth setup

package/src/docs/versioned/next/implementationPlans/PLAN_INDEX.md

@@ -15,43 +15,10 @@ Umbrella plans that coordinate several IPs.
 | Plan | Status | Created | Tasks |
 |------|--------|---------|-------|
 | [Admin UI v2 — Django-parity admin](admin-ui-v2-django-parity.md) | Approved | 2026-06-15 | [tasks](../tasks/admin-ui-v2-django-parity.md) |
-| [RBAC Permissions](rbac-permissions.md) | Draft (API design) | 2026-07-08 | TBD |
-| [SyncDB Local-First Data Layer](syncdb-local-first.md) | In progress ([PR #869](https://github.com/flourishhealth/terreno/pull/869)) | 2026-07-13 | [tasks](../tasks/syncdb-local-first.md) |
-| [MCP Boost parity](mcp-boost-parity.md) | In progress ([PR #802](https://github.com/flourishhealth/terreno/pull/802)) | 2026-06-21 | TBD |
-
-## Open source launch IPs
-
-All part of the [launch program](oss-launch-program.md). The **RTK flag** column marks dependence on the `@terreno/rtk` → `@terreno/syncdb` migration in PR #869: `None` is safe to implement now, `Partial` has some blocked tasks, `Blocked` cannot start until #869 merges.
-
-### Wave 0 — unblocked
-
-| Plan | Status | RTK flag | Tasks |
-|------|--------|----------|-------|
-| [OSS governance baseline](oss-governance-baseline.md) | Draft | None | [tasks](../tasks/oss-governance-baseline.md) |
-| [Public roadmap on GitHub](public-roadmap-github.md) | Draft | None | [tasks](../tasks/public-roadmap-github.md) |
-| [Deploy to GCP (generalized)](deploy-to-gcp.md) | Draft | None | [tasks](../tasks/deploy-to-gcp.md) |
-| [Agentic SDLC plugin (`/terreno-*`)](agentic-sdlc-plugin.md) | Draft | Partial | [tasks](../tasks/agentic-sdlc-plugin.md) |
-
-### Wave 1 — gated on PR #869
-
-| Plan | Status | RTK flag | Tasks |
-|------|--------|----------|-------|
-| [RTK deprecation and syncdb migration docs](rtk-to-syncdb-migration-docs.md) | Draft | **Blocked** (gating IP) | [tasks](../tasks/rtk-to-syncdb-migration-docs.md) |
-| [Positioning — Django/Rails for TypeScript](positioning-django-rails-universal.md) | Draft | Partial | [tasks](../tasks/positioning-django-rails-universal.md) |
-| [Reference documentation coverage](docs-reference-coverage.md) | Draft | Blocked | [tasks](../tasks/docs-reference-coverage.md) |
-| [AI-first tutorials](docs-tutorials-ai-first.md) | Draft | Blocked | [tasks](../tasks/docs-tutorials-ai-first.md) |
-| [Deployment foundation](deployment-foundation.md) | Draft | Partial | [tasks](../tasks/deployment-foundation.md) |
-| [Deploy to Vercel](deploy-to-vercel.md) | Draft | Partial | [tasks](../tasks/deploy-to-vercel.md) |
-| [Upgrade guides and skill](upgrade-guides-and-skill.md) | Draft | Blocked | [tasks](../tasks/upgrade-guides-and-skill.md) |
-| [The AI development loop (Boost)](ai-dev-loop-boost.md) | Draft | Partial | [tasks](../tasks/ai-dev-loop-boost.md) |
-| [Dogfooding run and launch blog post](build-terreno-app-validation.md) | Draft | Blocked | [tasks](../tasks/build-terreno-app-validation.md) |
-| [Examples, demo, and test coverage](examples-demo-coverage.md) | Draft | Partial | [tasks](../tasks/examples-demo-coverage.md) |
-
-### Wave 2 — independent
-
-| Plan | Status | RTK flag | Tasks |
-|------|--------|----------|-------|
-| [Web SSR and admin SPA](web-ssr-and-admin-spa.md) | Draft | Partial | [tasks](../tasks/web-ssr-and-admin-spa.md) |
+| [@terreno/syncdb-codegen](syncdb-codegen.md) | Draft | 2026-07-08 | [tasks](../tasks/syncdb-codegen.md) |
+| [SyncDB local-first data layer (v2)](syncdb-local-first.md) | In progress — Phases 1–8 landed, Phase 9 follow-ups open | 2026-06-23 | [tasks](../tasks/syncdb-local-first.md) |
+| [SyncDB hardening (syncdb-2)](terreno-syncdb-2.md) | Implemented — Phases A–F landed; deviations carried into Phase 9 | 2026-07-11 | [tasks](../tasks/syncdb-local-first.md) (Phase 8/9) |
+| [SyncDB Phase C design](syncdb-phase-c-design.md) | Implemented — design authority for C1–C8 | 2026-07-11 | [tasks](../tasks/syncdb-local-first.md) (Phase 8) |
 
 ## Completed
 

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

@@ -1,13 +1,13 @@
 # Implementation Plan: RTK Deprecation and SyncDB Migration Docs
 
-**Status:** Draft — blocked on PR #869
+**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:** PR [#869](https://github.com/flourishhealth/terreno/pull/869) merging
-**RTK deprecation flag:** **Blocked** — this IP *is* the RTK deprecation. Nothing here can be written until #869 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
 
@@ -33,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** — agent-assisted via `upgrading-terreno` skill |
-| 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
 
@@ -57,6 +57,56 @@ 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 (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
 
 The migration guide is the highest-value artifact. It must be organized by *what the developer has to change*, not by package internals: