@terreno/mcp 57.0.0 → 57.2.0

package/src/docs/versioned/next/implementationPlans/pluggable-database-sqlite.md

@@ -0,0 +1,247 @@
+# Pluggable database layer and SQLite adapter
+
+**Status:** Approved — decisions 2026-08-20
+**Branch:** `cursor/sqlite-pluggable-db-ip-4d52`
+**Owner:** —
+**Created:** 2026-08-20
+**Research:** [pluggable-database-sqlite-research.md](pluggable-database-sqlite-research.md)
+**Roadmap issue:** *(pending `roadmap-item` handoff)*
+
+## Goal
+
+Make the persistence layer of `@terreno/api` pluggable: extract a `DatabaseAdapter` seam under `modelRouter`, make the current Mongoose/MongoDB handler the default adapter behind it (zero behavior change), and ship a SQLite adapter (`@terreno/db-sqlite`) that supports the full CRUD + permissions + population + OpenAPI + admin surface for apps that do not need Mongo-only capabilities.
+
+Existing codebases keep authoring models exactly as today — `new mongoose.Schema({...})` with the standard plugins — on both databases.
+
+## Non-Goals
+
+- Realtime change-stream events, the syncdb server protocol, feature-flag watchers, or Atlas `$search` on SQLite (Mongo-only in v1, gated by capability flags).
+- The legacy passport-local-mongoose JWT auth path on SQLite (Better Auth is the auth provider on SQLite).
+- A Postgres adapter (the seam must not preclude one, but none ships here).
+- Data migration tooling between Mongo and SQLite.
+- Certifying `admin-backend`, `comms`, `ai`, or `feature-flags` on SQLite (they are schema-driven and expected to mostly work; certification is follow-up work).
+- A new schema DSL. Mongoose remains the schema authoring format and source of truth for OpenAPI/admin metadata.
+
+## Decisions
+
+| # | Question | Decision |
+|---|----------|----------|
+| D1 | Schema authoring | **Option A** — Mongoose schemas stay the authoring format; adapters interpret the compiled model (`schema.paths`). Mongoose remains a dependency on SQLite as schema DSL + document layer. |
+| D2 | SQLite storage model | **Option A2** — relational column mapping. Schema paths become real columns; arrays/subdocuments/Mixed/Map fall back to JSON columns. |
+| D3 | v1 capability line | CRUD, permissions, population, OpenAPI, validation, and admin metadata work on SQLite. Change streams, syncdb server, feature-flag watch, and Atlas search stay Mongo-only behind adapter capability flags. |
+| D4 | Auth on SQLite | Better Auth, via its built-in SQLite support (Kysely adapter accepts `bun:sqlite` / `better-sqlite3` / `node:sqlite` handles). Legacy passport path requires the Mongo adapter. |
+| D5 | Query language | The existing Mongo-filter subset that modelRouter emits is the adapter contract; the SQLite adapter compiles it to SQL. |
+| D6 | Package scope v1 | `@terreno/api` + `@terreno/db-sqlite` + `example-backend` (SQLite mode) + `@terreno/test` harness support. |
+| D7 | Driver | `bun:sqlite` is the default; the adapter takes an injected driver handle so `better-sqlite3` / `node:sqlite` / `libsql` work too. |
+| D8 | Packaging | New workspace package `@terreno/db-sqlite` (mirrors the comms adapter-package pattern). The interface + Mongoose adapter live in `@terreno/api`. |
+| D9 | Population | First-class requirement. `populatePaths` (single refs, arrays of refs, field selection) must behave identically on both adapters, including populated create/update/read responses and soft-delete filtering of referenced docs. |
+
+## Architecture
+
+### The adapter seam
+
+New module `api/src/db/adapter.ts` defining the contract; everything in `api.ts`, `sync/executors.ts`, `docLoader.ts`, and the permissions doc-loading path is refactored to call it instead of Mongoose model APIs directly.
+
+```typescript
+export interface DatabaseAdapter {
+  readonly capabilities: AdapterCapabilities;
+  collection<T>(model: ModelLike<T>): AdapterCollection<T>;
+  // Schema lifecycle: no-op on Mongo; DDL sync on SQLite.
+  ensureSchema(models: ModelLike<unknown>[]): Promise<void>;
+  // Auth integration: what Better Auth's `database` option receives.
+  getBetterAuthDatabase(): unknown;
+}
+
+export interface AdapterCapabilities {
+  changeStreams: boolean;   // realtime + syncdb server + feature-flag watch
+  transactions: boolean;    // sync seq claiming sessions
+  textSearch: boolean;      // Atlas $search / $autocomplete
+}
+
+export interface AdapterCollection<T> {
+  create(data: Partial<T>): Promise<HydratedDoc<T>>;
+  findById(id: string, options?: {populate?: PopulatePath[]}): Promise<HydratedDoc<T> | null>;
+  list(options: {
+    query: MongoFilter;      // the validated modelRouter filter subset
+    sort?: string | Record<string, SortDirection>;
+    skip?: number;
+    limit?: number;
+    populate?: PopulatePath[];
+  }): Promise<HydratedDoc<T>[]>;
+  count(query: MongoFilter): Promise<number>;
+  save(doc: HydratedDoc<T>): Promise<HydratedDoc<T>>;      // runs validation, plugin semantics, version check
+  delete(doc: HydratedDoc<T>, options: {soft: boolean}): Promise<void>;
+  populate(docs: HydratedDoc<T>[], paths: PopulatePath[]): Promise<void>;
+}
+```
+
+Adapter selection happens at app construction; the default preserves today's behavior with no consumer changes:
+
+```typescript
+// Mongo (default — implicit when `database` is omitted)
+new TerrenoApp({userModel: User});
+
+// SQLite
+import {sqliteAdapter} from "@terreno/db-sqlite";
+new TerrenoApp({userModel: User, database: sqliteAdapter({filename: "app.db"})});
+```
+
+### MongooseAdapter (in `@terreno/api`)
+
+Thin delegation to the exact calls the framework makes today (`find/findById/create/doc.save()/deleteOne/countDocuments/.populate()`), including the native `model.collection.findOne` soft-delete probe in `docLoader.ts`. Capabilities: all `true`. `getBetterAuthDatabase()` returns the `mongodbAdapter` client as `betterAuthSetup.ts` builds it today. All existing api tests must pass unchanged against this adapter — the Phase 1 gate.
+
+### SqliteAdapter (`@terreno/db-sqlite`)
+
+**Documents.** Rows are hydrated into real Mongoose documents with `model.hydrate(row)` — no Mongo connection required — so virtuals, methods, `toJSON({virtuals: true})`, and consumer typing all work unchanged. Writes go through `adapter.save()`, which runs `doc.validate()`, applies the framework plugin semantics natively, and persists changed paths.
+
+**Plugin semantics (behavior spec, implemented natively).**
+
+| Plugin behavior | SQLite implementation |
+|---|---|
+| `createdUpdatedPlugin` | Set `created` on insert, `updated` on every save |
+| `isDeletedPlugin` | `deleted` column; every read appends `AND deleted IS NOT 1`; `docLoader` probe reads without the filter |
+| Optimistic concurrency / `__v` | `UPDATE ... WHERE _id = ? AND __v = ?`; zero rows → the same conflict error path as Mongoose `VersionError` |
+| `findExactlyOne` / `findOneOrNone` / `upsertPlugin` statics | Work as-is — they run through `model.find`, which the framework only calls via the adapter surface |
+| Consumer `schema.pre/post("save")` document middleware | Invoked through Mongoose's hook registry around persist (best-effort; verified by conformance tests; documented limitation if a hook depends on Mongo-only internals) |
+| Consumer custom **query** middleware | Not translated to SQL beyond the built-in soft-delete/archive filters — documented limitation |
+
+**Schema → DDL mapping (D2, A2).**
+
+| Mongoose path | SQLite column |
+|---|---|
+| `_id` | `TEXT PRIMARY KEY` — default `new mongoose.Types.ObjectId().toHexString()` (matches the synced-model String-`_id` precedent) |
+| String | `TEXT` |
+| Number | `NUMERIC` |
+| Boolean | `INTEGER` (0/1) |
+| Date | `TEXT` — ISO 8601 UTC (lexicographic order = chronological; Luxon-friendly) |
+| ObjectId / ref | `TEXT` (no `FOREIGN KEY` constraint — matches Mongo's non-enforcing refs) |
+| enum | `TEXT` + `CHECK (col IN (...))` |
+| Array / subdocument / Mixed / Map | `TEXT` JSON (`CHECK (json_valid(col))`) |
+| `DateOnly` custom type | `TEXT` (`YYYY-MM-DD`) |
+| `__v` | `INTEGER NOT NULL DEFAULT 0` |
+| `required: true` | `NOT NULL` |
+| `default` | Applied in the JS layer (supports function defaults), not DDL |
+| `index` / `unique` / `sparse` | `CREATE [UNIQUE] INDEX`; sparse → partial index `WHERE col IS NOT NULL` |
+
+**DDL sync.** `ensureSchema(models)` runs at startup: creates missing tables/columns/indexes when `autoMigrate: "additive"` (default in dev); destructive changes (type change, drop, constraint change) are never auto-applied — the adapter throws a clear `APIError`-style startup error and writes the proposed SQL to a migration file for manual review. Connection defaults: WAL mode, `busy_timeout`, `foreign_keys=OFF`.
+
+**Query translation.** The adapter compiles exactly the filter surface modelRouter emits: top-level equality on `queryFields`, `$in/$nin/$ne/$exists/$gt/$gte/$lt/$lte`, `$and`/`$or`, and the `_gte`/`_lte` date-range expansion. Column-backed paths compile to plain SQL predicates; nested/JSON paths use `json_extract`; membership in array columns uses `EXISTS (SELECT 1 FROM json_each(col) ...)`. Any operator outside the contract → 400 `APIError` (same as an invalid query today). Sort/skip/limit/count map directly. `realtime/queryMatcher.ts` documents the operator semantics and seeds the conformance fixtures.
+
+### Population (D9)
+
+Population is a first-class, conformance-tested part of the adapter contract — not an afterthought:
+
+- **Contract:** `populate(docs, paths)` with `PopulatePath = {path, fields?}`, plus a `populate` option on `findById`/`list`. The executors' post-create/post-update re-read with population goes through the same path, so populated response shapes are identical across adapters.
+- **Ref discovery:** from `schema.path(key).options.ref` and array-element refs — the same metadata `getOpenApiSpecForModel` reads, so the populated schemas in `/openapi.json` stay correct on SQLite with no OpenAPI changes.
+- **SQLite strategy:** batched two-phase loads, mirroring Mongoose's own populate. Per path: collect distinct FK values across the page, run one `SELECT _id, <fields> FROM <ref_table> WHERE _id IN (...)`, attach results (single ref → object, array of refs → array). No N+1, no JOIN row-explosion, and `fields` projection happens in SQL.
+- **Soft-delete parity:** when the referenced model has `isDeletedPlugin`, the batched lookup appends the soft-delete filter — a soft-deleted target populates to `null`/absent exactly as it does through Mongoose query middleware today.
+- **Missing refs:** dangling FK values populate to `null` (Mongoose parity).
+- **v1 scope:** single-level populate with field selection — the full surface `populatePaths` supports today. Nested (multi-hop) populate is future work on both adapters.
+- **Conformance suite:** single ref, array of refs, field selection, dangling ref, soft-deleted target, populate-on-create/update responses — run against both adapters.
+
+### Capability gating (D3)
+
+`TerrenoApp` checks `adapter.capabilities` at registration time:
+
+- Realtime/change-stream registration, syncdb route registration, and feature-flag watchers require `changeStreams: true`; on SQLite they fail fast at startup with an actionable error naming the capability (not a runtime surprise).
+- Atlas `$search`/`$autocomplete` stubs require `textSearch: true`.
+- Sync seq sessions require `transactions: true`.
+
+### Auth (D4)
+
+`betterAuthSetup.ts` stops reaching for the global `mongoose.connection` and instead calls `adapter.getBetterAuthDatabase()`. The Mongo adapter returns the `mongodbAdapter` client (today's behavior); the SQLite adapter returns its driver handle, which Better Auth's built-in Kysely adapter accepts directly for `bun:sqlite`, `better-sqlite3`, and `node:sqlite`. Better Auth schema tables are created via its migration tooling, invoked from `ensureSchema`. `setupAuth`/passport (`auth.ts`) is gated to the Mongo adapter with a clear startup error otherwise.
+
+## Models
+
+No new Mongoose models. `@terreno/db-sqlite` maintains one internal metadata table (`_terreno_schema`) recording the applied DDL per model for additive-migration diffing.
+
+## APIs
+
+No route surface changes. `modelRouter` options, generated endpoints, pagination envelope (`{data, limit, more, page, total}`), array-field endpoints, permissions, `queryFilter`, and OpenAPI output are identical on both adapters. New public API:
+
+- `TerrenoAppOptions.database?: DatabaseAdapter` (default: Mongoose adapter).
+- `@terreno/db-sqlite` exports `sqliteAdapter(options: {filename: string; driver?: SqliteDriverHandle; autoMigrate?: "additive" | "off"})`.
+- `@terreno/api` exports the `DatabaseAdapter` / `AdapterCollection` / `AdapterCapabilities` types and `mongooseAdapter()`.
+
+## Notifications
+
+None.
+
+## UI
+
+None (backend-only).
+
+## Phases
+
+### Phase 1 — Adapter seam + Mongoose adapter (no behavior change)
+
+Define the adapter interfaces; implement `MongooseAdapter`; refactor `api.ts`, `sync/executors.ts`, `docLoader.ts`, and permissions doc loading to consume the adapter; wire `TerrenoAppOptions.database`; add capability checks to realtime/sync/feature-flag/search registration (all pass on Mongo). Gate: entire existing api test suite green with zero test edits.
+
+### Phase 2 — `@terreno/db-sqlite` core
+
+Package scaffold; DDL mapping + `ensureSchema` additive migration; CRUD; query translation; sort/pagination/count; plugin semantics (timestamps, soft delete, `__v` conflict); **population** (batched loads, soft-delete parity, field selection); enum checks and indexes; driver injection with `bun:sqlite` default. Adapter conformance suite in `@terreno/api` run against both adapters.
+
+### Phase 3 — Auth + capability hardening
+
+`getBetterAuthDatabase()` seam; Better Auth on SQLite end-to-end (signup/login/session → `req.user`); passport path gated to Mongo; startup errors for missing capabilities; `@terreno/test` gains `TERRENO_TEST_DB=sqlite` (temp-file DB per suite, no mongod download).
+
+### Phase 4 — Example, docs, and integration
+
+`example-backend` `DB_ADAPTER=sqlite` mode (skips change-stream features via capability flags); verify `/openapi.json` and admin `/admin/config` output parity; docs (how-to: run Terreno on SQLite; explanation: adapter capabilities; update positioning doc's "MongoDB-only" claims); MCP `terreno_generate_model`/bootstrap templates mention adapter choice; changelog + upgrade note (none required for existing apps).
+
+## Feature Flags & Migrations
+
+- No feature flag: adapter choice is an explicit constructor option; omitting it preserves today's behavior exactly.
+- No data migrations for existing apps.
+- SQLite DDL migrations: additive-auto by default in dev; destructive changes always manual (generated SQL file + startup error). Documented in the how-to.
+
+## Activity Log & User Updates
+
+n/a.
+
+## Not Included / Future Work
+
+- Postgres adapter (the seam is designed dialect-neutral; JSON handling and DDL mapping are the SQLite-specific parts).
+- Realtime/outbox-based change feed for SQLite (would unblock syncdb + feature-flag watch off-Mongo).
+- Nested (multi-hop) populate on both adapters.
+- Certifying `admin-backend`, `comms`, `ai`, `feature-flags` on SQLite.
+- Mongo↔SQLite data migration tooling.
+- passport-local credential store on SQLite.
+
+## Files to Create / Modify
+
+**Create**
+
+- `api/src/db/adapter.ts` — interfaces + capability types
+- `api/src/db/mongooseAdapter.ts` — default adapter
+- `api/src/db/conformance/` — shared adapter conformance suite (CRUD, query, populate, plugins)
+- `db-sqlite/` — new workspace package: `src/sqliteAdapter.ts`, `src/ddl.ts`, `src/queryCompiler.ts`, `src/populate.ts`, `src/drivers.ts`, tests
+- `docs/how-to/run-on-sqlite.md`, `docs/explanation/database-adapters.md`
+
+**Modify**
+
+- `api/src/api.ts`, `api/src/sync/executors.ts`, `api/src/docLoader.ts`, `api/src/permissions.ts` — consume adapter
+- `api/src/terrenoApp.ts` — `database` option, capability gating
+- `api/src/betterAuthSetup.ts` — `getBetterAuthDatabase()` seam
+- `api/src/auth.ts` — Mongo-gate the passport path
+- `api/src/index.ts` — export adapter types + `mongooseAdapter`
+- `test/src/` — `TERRENO_TEST_DB=sqlite` harness mode
+- `example-backend/src/server.ts` + `utils/database.ts` — `DB_ADAPTER=sqlite` mode
+- `mcp-server/src/tools.ts` / bootstrap templates — adapter-aware scaffolds
+- Root `package.json` catalog + workspaces, CI workflows for the new package
+
+## Task List
+
+[docs/tasks/pluggable-database-sqlite.md](../tasks/pluggable-database-sqlite.md)
+
+## Acceptance Criteria
+
+- [ ] Existing api test suite passes unchanged with the Mongoose adapter as default (Phase 1 gate).
+- [ ] A modelRouter app (models, permissions, queryFilter, pagination, sorting, array endpoints) runs on SQLite with byte-identical response envelopes.
+- [ ] `populatePaths` behaves identically on both adapters: single ref, array of refs, field selection, dangling ref → `null`, soft-deleted ref filtered, populated create/update responses — verified by the conformance suite.
+- [ ] `/openapi.json` for the same models is identical on Mongo and SQLite.
+- [ ] Better Auth signup/login/session works on SQLite; passport path fails fast with a clear error.
+- [ ] Realtime, syncdb, and feature-flag registration on SQLite fail fast at startup with capability-named errors.
+- [ ] `ensureSchema` creates tables/columns/indexes additively; destructive changes error with generated SQL.
+- [ ] `example-backend` boots and serves CRUD in `DB_ADAPTER=sqlite` mode with no mongod running.
+- [ ] `bun run lint`, `bun run compile`, and api + db-sqlite tests green in CI.

package/src/docs/versioned/next/implementationPlans/positioning-django-rails-universal.md

@@ -78,7 +78,7 @@ The Django/Rails claim invites the obvious question. `docs/explanation/positioni
 | Models + ORM | Mongoose schemas + `@terreno/api` plugins | Document store, not relational; no migrations framework |
 | `ModelViewSet` / scaffolds | `modelRouter` | REST only; no GraphQL |
 | Django admin | `@terreno/admin-backend` + `admin-frontend` / `admin-spa` | Younger; see the admin parity IP for the gap list |
-| Auth + permissions | Better Auth + `Permissions` | RBAC is in progress (`rbac-permissions.md`) |
+| Auth + permissions | Better Auth + `Permissions` / RBAC | RBAC shipped (`rbac-permissions.md`, Complete) |
 | Templates / views | `@terreno/ui` components, one codebase for iOS/Android/web | SSR is not shipped yet — see [`web-ssr-and-admin-spa`](web-ssr-and-admin-spa.md) |
 | `manage.py` / generators | MCP server tools (the *tool* layer) + the `/terreno-*` SDLC pipeline (the *process* layer) | Agent-driven rather than CLI-driven. Django gives you `manage.py startapp`; Terreno gives you a reviewed path from a request to a mergeable PR |
 | Celery / ActiveJob | Not shipped | On the roadmap |

package/src/docs/versioned/next/implementationPlans/public-roadmap-github.md

@@ -147,7 +147,7 @@ None beyond GitHub's own subscriptions. Announcements category posts should be t
 ## Phases
 
 1. **Discussions** — enable, create categories, seed each with a pinned intro post, add the RFC template.
-2. **Project board** — create the Project, fields, and views; backfill items from `PLAN_INDEX.md` and the IPs in this program.
+2. **Project board** — create the Project, fields, and views; backfill items from the IPs in this program.
 3. **Labels and triage** — create the label set, delete unused defaults, add `triage.yml`.
 4. **Roadmap generation** — `ROADMAP.md` + `roadmap-generate.yml`, link from README and docs site.
 5. **Linear bridge** — configure the integration, document the process in `CONTRIBUTING.md`, and record the rules in a maintainer doc.
@@ -195,7 +195,7 @@ See [`docs/tasks/public-roadmap-github.md`](../tasks/public-roadmap-github.md).
 
 - [ ] All seven Discussion categories exist with the specified formats and a pinned intro post each.
 - [ ] The **Terreno Roadmap** Project exists with the six fields and four views described above.
-- [ ] Every IP in `docs/implementationPlans/PLAN_INDEX.md` marked Approved or later has a tracking issue on the board with its `IP` field set to the IP slug.
+- [ ] Every IP whose `**Status:**` header is Approved or later has a tracking issue on the board with its `IP` field set to the IP slug.
 - [ ] The label set matches the taxonomy table; no unused GitHub default labels remain.
 - [ ] `bun run scripts/generate-roadmap.ts` produces `ROADMAP.md` grouped by `Target` then `Area`, and `roadmap-generate.yml` commits it only when changed.
 - [ ] Opening a new issue applies `status:needs-triage` and the correct `area:*` label automatically.

package/src/docs/versioned/next/implementationPlans/rbac-permissions.md

@@ -1,9 +1,36 @@
 # RBAC Permissions for Terreno — API Design
 
-**Status:** Draft — API design for discussion (full IP to follow)
+**Status:** Complete — phases 1–6 shipped in PR #932 (2026-08-22)
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1089
 **Target package:** `@terreno/api` (new `src/rbac/` module), with surfaces in `admin-backend`, `admin-frontend`, `admin-spa`, `rtk`, and the modelRouter MCP work
 **Depends on:** `better-auth/plugins/access` (already a dependency via the Better Auth provider)
 
+## Shipped (PR #932)
+
+Phases 1–6 in section 8 are implemented. `RoleManager` emits `RbacAudit` (including
+`permissionDelta`) on create/update/remove/assign/unassign; denied escalation attempts are
+written with `denied: true`. `rbacRouter` is a thin HTTP adapter and does not write a second
+audit row. Apps can attach `createAccess({auditSink})` (one sink or an array) to fan the same
+record into a consuming-app audit log. `persistAudit: false` skips the built-in collection
+and requires at least one sink. Seed upsert lives in `upsertSeededRole`; `RbacRole.seedDefaults({statements,
+extraRoles})` is the single seed entry. `previewRoleChange.affectedUserCount` is the number of
+users currently holding that role.
+
+### Compatibility: no default-connection models
+
+Importing `@terreno/api` does **not** register `RbacRole` or `RbacAudit` on
+`mongoose.connection`. Apps must:
+
+1. Call `createAccess({connection, ...})` (registers both models on that connection), or
+2. Call `createRbacRoleModel(connection)` / `createRbacAuditModel(connection)` in scripts/tests.
+
+The previous `RbacRoleModel` / `RbacAuditModel` value singletons are removed. The TypeScript
+type `RbacRoleModel` remains exported. Migrate `import {RbacRoleModel} from "@terreno/api"` to
+`createRbacRoleModel(connection)`.
+
+Left out of this close: Redis/pubsub cross-instance cache invalidation beyond in-process
+`invalidateCache`.
+
 ---
 
 ## 1. Summary
@@ -408,7 +435,11 @@ export interface RoleManager {
 
   // Diff previews for the admin UI (see 4.11)
   previewRoleChange(args: {roleName: string; permissions: PermissionSet}): Promise<RoleDiff>;
-  previewAssignment(args: {userId: string; roleNames: string[]}): Promise<UserPermissionDiff>;
+  previewAssignment(args: {
+    actor: User;
+    userId: string;
+    roleNames: string[];
+  }): Promise<UserPermissionDiff>;
 }
 
 export interface RoleDiff {
@@ -429,12 +460,18 @@ Guardrails baked into `RoleManager` (borrowed from Better Auth's dynamic access
 - **No escalation**: an actor can only grant (or edit a role to include, or assign) permissions
   the actor **themselves currently holds**. Holding `rbac:manageRoles` lets an actor *manage*
   roles but never lets them hand out actions they lack — a role editor cannot bootstrap
-  privileges they do not have. The **only** exception is `superadmin`, which (via its `"*"`
+  privileges they do not have. Role **update** checks `actorPermissions ⊇ (existing ∪ incoming)`
+  so emptying a role still requires holding its current grants. Role **remove** checks
+  `actorPermissions ⊇ existing`. The **only** exception is `superadmin`, which (via its `"*"`
   expansion) holds every permission and so can grant anything; this is a property of *what
   superadmin holds*, not a special "manageRoles can escalate" rule. Concretely: the check is
   `actorPermissions ⊇ permissionsBeingGranted`, evaluated against the actor's effective set.
 - **Vocabulary validation**: every `resource:action` in `permissions` must exist in
   `access.statements` — writes with unknown pairs are 400s.
+- **Preview assignment** takes the same `actor` as assign: it requires `rbac:assignRoles`,
+  the target-user privilege-subset check, and `assertNoEscalation` for every previewed role.
+  The before/after diff uses uncached permission resolution on both sides so a warm cache
+  cannot invent gained/lost grants, and the preview cannot write live permission caches.
 - **Managing roles requires** `rbac:manageRoles`; assigning requires `rbac:assignRoles`. These
   gate *access* to the operation and are additive to (not a substitute for) the no-escalation
   subset check above.
@@ -872,11 +909,11 @@ behavior is per-source `staleOnFailure` (default `"deny"`):
 
 | Policy | Behavior |
 |---|---|
-| `"deny"` (default) | Omit this source's grants for the request. Local `user.roles` and other sources still apply. Revoked upstream access cannot linger because a dependency is down. |
+| `"deny"` (default) | Omit this source's additive grants (`roles`, `permissions`) for the request. Local `user.roles` and other sources still apply. If a prior fetch cached a `deny` set, keep applying that last-known deny so IdP/ABAC restrictions do not lift while the source is down. Revoked upstream *elevations* cannot linger because a dependency is down. |
 | `"use-stale-bounded"` | Reuse the last successful grants only if younger than `staleMaxAgeMs` (hard cap). Suitable for read-only hints, not elevation. |
 | `"use-stale"` | Reuse last successful grants until TTL expiry. **Not permitted** for sources that can grant roles/permissions beyond what local roles already provide — elevation paths must fail closed. |
 
-`PermissionSource.deny` already fails closed; grant caching matches that posture for elevation.
+`PermissionSource.deny` fails closed on refresh failure by keeping the last cached deny set (additive grants from that source are still omitted). Grant caching matches that posture for elevation.
 Logged at `warn` with source name and policy applied.
 
 ### 4.11 Admin UI (first-class)
@@ -890,7 +927,8 @@ New screens in `admin-frontend` / `admin-spa`, driven entirely by the 4.9 endpoi
   212 users."
 - **User role assignment** (embedded in the admin user detail): multi-select of roles with
   exclusion conflicts surfaced inline; confirmation modal shows `UserPermissionDiff` (total
-  permissions gained/lost after union with their remaining roles).
+  permissions gained/lost after union with their remaining roles). The preview endpoint
+  requires an actor with `rbac:assignRoles` and rejects roles the actor cannot grant.
 - **Effective permissions inspector**: per user, each permission annotated with its source
   ("via PatientGuide", "via healthie").
 
@@ -968,15 +1006,14 @@ fall out of the admin UI with zero code — the exact win the RBAC move is for.
 6. **Deny semantics**: **Only `PermissionSource.deny`** — roles do not carry negative
    permissions (union semantics stay simple; matches Better Auth).
 
-## 8. Phasing sketch (full task breakdown in the IP)
+## 8. Phasing sketch — shipped
 
-1. **Core**: statements/merge, `createAccess`, resolve+cache, `RbacRole` model + seeds,
+1. **Core** — shipped: statements/merge, `createAccess`, resolve+cache, `RbacRole` model + seeds,
    `rbacUserPlugin`, `IsPermitted`, `requireAccess` middleware. Tests.
-2. **modelRouter**: `access` option, scope-aware permission middleware, filter merging,
+2. **modelRouter** — shipped: `access` option, scope-aware permission middleware, filter merging,
    field-mask response handling, actions support.
-3. **HTTP surface**: `rbacRouter`, previews, `/auth/me` extension, backfill script.
-4. **Admin**: roles screens, diffs, user assignment, `admin:access` migration.
-5. **Realtime + MCP**: swap internals to `access.can()`/`fieldMask()`.
-6. **Sources + client**: `PermissionSource`, rtk selectors, Better Auth bridge, docs +
-   example-backend/-frontend demonstration (example app gets a `manager` role and a scoped
-   todo example).
+3. **HTTP surface** — shipped: `rbacRouter`, previews, `/auth/me` extension, backfill script.
+4. **Admin** — shipped: roles screens, diffs, user assignment, `admin:access` migration.
+5. **Realtime + MCP** — shipped: internals use `access.can()`/`fieldMask()`.
+6. **Sources + client** — shipped: `PermissionSource`, rtk selectors, Better Auth bridge,
+   example-backend/-frontend `manager` role and scoped todo example.

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

@@ -1,6 +1,7 @@
 # Implementation Plan: RTK Deprecation and SyncDB Migration Docs
 
-**Status:** In progress — syncdb available on `release-56.0.0`; reference + migration guide drafted
+**Status:** Complete — syncdb reference, migration guide, agent surfaces, and deprecation signalling shipped on `master`
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1007
 **Priority:** Critical (gates most of Wave 1)
 **Effort:** Big batch
 **Owner:** unassigned
@@ -206,14 +207,14 @@ See [`docs/tasks/rtk-to-syncdb-migration-docs.md`](../tasks/rtk-to-syncdb-migrat
 
 ## Acceptance Criteria
 
-- [ ] A verified inventory of `@terreno/syncdb`'s public exports exists and every documented API appears in the merged package's `src/index.ts`.
-- [ ] `docs/reference/syncdb.md` documents every exported hook, client method, and config option, with a runnable example for each.
-- [ ] `docs/how-to/migrate-rtk-to-syncdb.md` covers all eleven steps, and every before/after pair compiles against the merged code.
-- [ ] Following the guide, a fresh clone of `example-frontend` can be moved from the RTK path to the syncdb path with no undocumented steps.
-- [ ] `docs/reference/rtk.md` no longer exists at its old path; the Legacy page states the support window; a Docusaurus redirect resolves the old URL.
-- [ ] `docs/explanation/authentication.md` presents Better Auth first and JWT as legacy.
-- [ ] No agent-facing surface (`AGENTS.md`, `CLAUDE*.md`, `.rulesync/rules/`, MCP resources, bootstrap templates) instructs an agent to write RTK Query code for a new app.
-- [ ] `terreno_bootstrap_app` output uses syncdb, and a bootstrapped app runs.
-- [ ] `terreno_get_upgrade_guide` returns the syncdb upgrade note for the release range that includes #869.
-- [ ] `CHANGELOG.md` has a `Deprecated` entry naming `@terreno/rtk`, the support window, and the migration guide link.
-- [ ] `bun run lint`, `bun run compile`, `bun run rules:check`, and `bun run website:build` all pass.
+- [x] A verified inventory of `@terreno/syncdb`'s public exports exists and every documented API appears in the merged package's `src/index.ts`.
+- [x] `docs/reference/syncdb.md` documents every exported hook, client method, and config option, with a runnable example for each.
+- [x] `docs/how-to/migrate-rtk-to-syncdb.md` covers all eleven steps, and every before/after pair compiles against the merged code.
+- [x] Following the guide, a fresh clone of `example-frontend` can be moved from the RTK path to the syncdb path with no undocumented steps.
+- [x] `docs/reference/rtk.md` no longer exists at its old path; the Legacy page states the support window; a Docusaurus redirect resolves the old URL.
+- [x] `docs/explanation/authentication.md` presents Better Auth first and JWT as legacy.
+- [x] No agent-facing surface (`AGENTS.md`, `CLAUDE*.md`, `.rulesync/rules/`, MCP resources, bootstrap templates) instructs an agent to write RTK Query code for a new app.
+- [x] `terreno_bootstrap_app` output uses syncdb, and a bootstrapped app runs.
+- [x] `terreno_get_upgrade_guide` returns the syncdb upgrade note for the release range that includes #869.
+- [x] `CHANGELOG.md` has a `Deprecated` entry naming `@terreno/rtk`, the support window, and the migration guide link.
+- [x] `bun run lint`, `bun run compile`, `bun run rules:check`, and `bun run website:build` all pass.

package/src/docs/versioned/next/implementationPlans/syncdb-codegen-research.md

@@ -0,0 +1,137 @@
+# Research: @terreno/syncdb-codegen
+
+**Date:** 2026-08-20  
+**Scope:** Validate the draft IP (`docs/implementationPlans/syncdb-codegen.md`) against the current `master` codebase and parent syncdb work.  
+**Status:** Complete — clarification pass answered 2026-08-20. IP **Approved**.
+
+## Clarification outcomes (2026-08-20)
+
+| # | Topic | Choice |
+|---|-------|--------|
+| 1 | Collection discovery | A — `x-terreno-sync` + `--collections` fallback |
+| 2 | Per-mutation retries | A — `maxAttempts` plumbing |
+| 3 | Type emission | A — hand-rolled emitter |
+| 4 | Hook factory | A — `createCollectionHooks` in `@terreno/syncdb/react` |
+| 5 | Hook naming | **C — friendly names** (`useTodos`, `useTodo`, `useCreateTodo`, …) |
+| 6 | Mutation return | A — `[trigger]` one-tuple |
+| 7 | example-frontend scope | A — todos only |
+| 8 | Delivery | **B — single PR** |
+| 9 | npm publish | **Include `@terreno/syncdb-codegen` in `publish-on-tag.yml`** |
+
+## Open questions (blocking — see blend Step 3)
+
+Resolved — see table above.
+
+## Problem summary
+
+`@terreno/syncdb` is implemented (Phases 1–8 of `syncdb-local-first.md` landed). Consumers still hand-write collection strings, entity interfaces, and hook wiring — see `example-frontend/components/SyncTodosScreen.tsx`. RTK consumers get typed hooks from `bun run sdk` → `openApiSdk.ts`. The gap is a **codegen CLI** that reads the same OpenAPI spec and emits typed syncdb hooks (friendly names per approved IP).
+
+## What was investigated
+
+| Area | Locations | Finding |
+|------|-----------|---------|
+| React hooks | `syncdb/src/react/hooks.ts`, `index.ts` | `useQuery`, `useEntity`, `useMutate` exist; no per-operation hooks, no `createCollectionHooks` |
+| Mutate / outbox | `syncdb/src/client.ts`, `mutations/outbox.ts`, `storage/schema.ts` | `MutateArgs` has no `maxAttempts`; outbox rows have `errorNackCount` only; replay uses global `MAX_ERROR_NACK_ATTEMPTS = 5` |
+| OpenAPI list | `api/src/openApi.ts` `listOpenApiMiddleware` | No vendor extensions; no `operationId`; tags = model collection name |
+| Sync registry | `api/src/sync/registry.ts`, `api/src/api.ts` | In-memory only; `collectionTag = routePath.replace(/^\//, "")`; not reflected in OpenAPI |
+| Example backend | `example-backend/src/api/todos.ts`, `projects.ts` | `sync: {scope: {type: "owner"}}` on todos; tenant scope on projects |
+| RTK hook names | `example-frontend/store/openApiSdk.ts` | `useGetTodosQuery`, `useGetTodosByIdQuery`, `usePostTodosMutation`, `usePatchTodosByIdMutation`, `useDeleteTodosByIdMutation` |
+| Codegen package | `syncdb-codegen/` | **Does not exist** — tasks/IP only |
+| Parent IP | `docs/implementationPlans/syncdb-local-first.md` | Shaped; codegen listed as Phase 6 / future work |
+| Roadmap | `.github/roadmap-fields.yml` present | Roadmap-enabled repo; no GitHub issue found for syncdb-codegen |
+
+## Current consumer pattern (manual)
+
+```typescript
+// example-frontend/components/SyncTodosScreen.tsx
+interface SyncTodo { _id: string; title?: string; completed?: boolean; created?: string; }
+const todos = useQuery<SyncTodo>("todos", {sort: sortByCreatedDesc});
+const {update, remove} = useMutate("todos");
+```
+
+`example-frontend/store/syncdb.ts` maintains `SYNC_COLLECTIONS` by hand — can drift from backend `sync` registration.
+
+## Candidate options (not chosen here — see blocking questions)
+
+### How codegen discovers synced collections
+
+| Option | Pros | Cons |
+|--------|------|------|
+| **A. `x-terreno-sync` on list OpenAPI ops** | Single input (same as RTK); spec is versioned with backend; ~10-line api change | Must thread `routePath` into `listOpenApiMiddleware` (not available today) |
+| **B. `--collections` CLI flag only** | No api change | Drifts from backend; duplicates config |
+| **C. `GET /sync/config` manifest** | Runtime truth | Extra endpoint; second source of truth vs OpenAPI |
+
+Draft IP recommends **A + B fallback**.
+
+### Per-mutation retry budget (`retries` / `maxAttempts`)
+
+| Option | Pros | Cons |
+|--------|------|------|
+| **A. Plumb `maxAttempts` through mutate → outbox → replay** | Config is honest; matches RTK `maxRetries: 0` intent | Touches syncdb storage + replay coordinator |
+| **B. Codegen emits `retries` but engine ignores** | Smaller diff | Lying generated config |
+
+Draft IP recommends **A**.
+
+### Type emission from OpenAPI schemas
+
+| Option | Pros | Cons |
+|--------|------|------|
+| **A. Hand-rolled emitter for mongoose-to-swagger dialect** | Zero runtime deps; small compiled binary | Must grow if spec dialect widens |
+| **B. `openapi-typescript` or oazapfts** | Battle-tested | Heavier dep; may emit more than needed |
+
+Draft IP recommends **A** (~150 lines + snapshot tests).
+
+### Hook factory location
+
+| Option | Pros | Cons |
+|--------|------|------|
+| **A. `createCollectionHooks` in `@terreno/syncdb/react`** | Versioned with hooks; custom hooks use same factory | Expands syncdb public API |
+| **B. Inline factory in every generated file** | No syncdb API change | Duplicated generated code |
+| **C. Runtime export from `@terreno/syncdb-codegen`** | — | Codegen becomes app dependency (rejected) |
+
+Draft IP recommends **A**.
+
+### Hook naming and RTK collision
+
+| Option | Pros | Cons |
+|--------|------|------|
+| **A. Grouped `useTodosMutate()`** | No name collision with RTK | Different call sites; harder migration |
+| **B. RTK-exact per-op names (`useGetTodosQuery`, …)** | Import-path migration | Intentional name collision — must not barrel-export both SDKs |
+| **C. Friendly names (`useCreateTodo`)** | Readable | Diverges from RTK; migration friction |
+
+Draft IP recommends **B**.
+
+### Mutation hook return shape
+
+| Option | Pros | Cons |
+|--------|------|------|
+| **A. `[trigger]` one-tuple** | RTK destructuring compiles; syncdb writes are sync | `.unwrap()` / `isLoading` must be deleted at migration |
+| **B. Full RTK async tuple** | Drop-in compat | Fakes async state syncdb does not have |
+
+Draft IP recommends **A**.
+
+## Technical notes for implementation
+
+1. **`listOpenApiMiddleware` needs `routePath`**: Today signature is `(model, options)` only. `collection` for `x-terreno-sync` must match `sync/registry.ts` `collectionTag` (path without leading `/`). Pass path from `_buildModelRouter` or read from options if added there.
+
+2. **`scope` in extension**: Emit scope **type** string (`owner` | `tenant` | `broadcast` | `custom`). Function resolvers → `"custom"`.
+
+3. **Name derivation**: Match `@rtk-query/codegen-openapi` — pascal-case from HTTP method + path segments (verified against `openApiSdk.ts` for `/todos`).
+
+4. **example-backend has two synced models** (todos owner, projects tenant). Draft IP example-frontend integration only wires todos — confirm whether projects should appear in generated SDK for the example app.
+
+5. **No data migration** for optional `_outbox.maxAttempts` cell — missing cell keeps engine default (5).
+
+6. **Roadmap handoff**: When IP status → Approved, run `roadmap-item` to create/update tracking issue (no existing issue found).
+
+## Open questions (blocking — see blend Step 3)
+
+Transferred to the clarification pass in the blend thread; do not treat draft IP decisions as approved until answered.
+
+## References
+
+- `docs/implementationPlans/syncdb-codegen.md` (draft IP)
+- `docs/tasks/syncdb-codegen.md` (task breakdown)
+- `docs/implementationPlans/syncdb-local-first.md` (parent — Phase 6 codegen)
+- `docs/how-to/migrate-rtk-to-syncdb.md` (migration guide — codegen section TBD)
+- `.rulesync/skills/generate-sdk/SKILL.md` (RTK codegen parallel)