@terreno/mcp 58.0.1 → 58.0.3

package/src/docs/versioned/next/implementationPlans/mcp-agent-debugger-gaps.md

@@ -0,0 +1,257 @@
+# Implementation Plan: MCP Agent Debugger Gaps (Network, Dispatch, Storage, Native Logs, Dev Commands)
+
+**Status:** Complete — Pick landed 2026-11-06  
+**Parent IP:** [mcp-boost-parity.md](mcp-boost-parity.md) (extends the local stdio companion; does not repeat hosted docs/codegen work)  
+**Roadmap:** Area=`mcp`, Target=`Next`, Impact=`Feature`  
+**Created:** 2026-11-05  
+
+## Goal
+
+Close the remaining agent-debugging gaps compared to integrated RN debuggers (for example
+Xerlock): **network traffic**, **structured Redux dispatch**, **local key-value storage
+read/write**, **native platform logs**, and **app-registered dev commands**. Agents already get
+merged console/backend logs, Mongo, SyncDB/RTK state, navigation, and web driving via
+`terreno-mcp-local`; this plan adds the missing observe/act surfaces without building a
+human debugger UI.
+
+## Non-Goals
+
+- On-device **SQLite** inspection outside SyncDB/TinyBase (partial overlap with
+  `get_syncdb_state`; raw `expo-sqlite` is out of scope).
+- **Push notification** simulation, **network throttle**, and **React component tree /
+  profiler** MCP tools (human DevTools + screenshots + `get_client_state` remain the path).
+- **Zustand** as a first-class framework integration (apps may expose Zustand via
+  `registerTerrenoDevCommand` only).
+- Taking **`metro-mcp`** as a dependency (implement on the existing CDP session in
+  `metroDevSession.ts`).
+- New **hosted** (`terreno-mcp`) tools — all work is **`terreno-mcp-local`** plus small
+  **`@terreno/syncdb`** / bootstrap dev hooks.
+
+## Decisions
+
+| # | Question | Decision |
+|---|----------|----------|
+| D1 | Separate `read_network` tool vs extend `read_logs`? | **Extend `read_logs`** with source `network` (chronological merge with other sources when omitted). |
+| D2 | Depend on `metro-mcp` vs in-house? | **In-house** on `mcp-server/src/local/metro/metroDevSession.ts` (same Hermes CDP connection as `app` / `evaluate`). |
+| D3 | Writable local storage in v1? | **Yes** — `write_local_storage` requires `TERRENO_MCP_EVAL=1`; reads are always allowed. |
+| D4 | Build order | **Network → dispatch + storage → native logs → dev commands → docs**. |
+| D5 | React tree snapshot | **Defer** — not in this plan. |
+
+## Architecture
+
+### Tool surface (after this plan)
+
+| Tool | Server | Purpose |
+|------|--------|---------|
+| `read_logs` | local | Existing sources `backend`, `browser`, `metro`, `app`; **add** `network`, `native`. |
+| `last_error` | local | Unchanged; may surface errors from new sources when level is `error`. |
+| `dispatch_client_action` | local | Dispatch a Redux action on `globalThis.__TERRENO_STORE__` via CDP (EVAL-gated). |
+| `read_local_storage` | local | Read AsyncStorage keys (and opt-in SecureStore key names) via dev global adapter. |
+| `write_local_storage` | local | Write one key (EVAL-gated); never writes SecureStore unless app registers an explicit allowlist entry. |
+| `list_dev_commands` | local | List `{name, description, inputSchema}` from `globalThis.__TERRENO_DEV_COMMANDS__`. |
+| `invoke_dev_command` | local | Run a registered handler by name (EVAL-gated). |
+
+Existing tools (`get_client_state`, `syncdb_*`, `evaluate`, `navigate`, `browser`, …) are
+unchanged.
+
+### CDP network capture (D1, D2)
+
+Extend `metroDevSession.ts`:
+
+1. After attaching to the debug target, enable CDP domains **`Runtime`** (existing) and
+   **`Network`**.
+2. Maintain a ring buffer (same cap as console, default 2000) of normalized entries:
+   - `timestamp`, `method`, `url`, `status`, `mimeType`, `durationMs` when available
+   - Request/response **header maps** with **`Authorization`**, **`Cookie`**, and
+     **`set-auth-token`** redacted
+   - Optional truncated **response body** (text only, max 4 KiB per entry; skip binary)
+3. `read_logs` with `sources: ["network"]` (or default merge) maps the ring into the same
+   JSON shape as other sources, with `source: "network"`.
+4. `connection` metadata reuses the existing CDP status block; document that enabling
+   Network shares the single Hermes debugger slot with DevTools contention rules already
+   documented for `app`.
+
+No separate MCP tool name.
+
+### Redux dispatch (D3, D4 phase 2)
+
+`dispatch_client_action`:
+
+```typescript
+// Input (strict JSON schema)
+{
+  type: string;           // required Redux action type
+  payload?: unknown;      // optional JSON-serializable payload
+}
+```
+
+Implementation:
+
+1. Refuse unless `TERRENO_MCP_EVAL=1` (same posture as `evaluate` / `navigate`).
+2. Prefer in-process read of `globalThis.__TERRENO_STORE__` when the MCP process shares the
+   app heap (tests); otherwise CDP `Runtime.evaluate` with a fixed snippet that calls
+   `globalThis.__TERRENO_STORE__?.dispatch({type, payload})` and returns `{ok, error?}`.
+3. Validate `type` is a non-empty string; reject non-JSON-serializable payloads before evaluate.
+4. Tool description tells agents to use `get_client_state` first, then dispatch, then
+   `read_logs` / `get_client_state` again.
+
+Requires `registerTerrenoDevStore(store)` in consumer apps (already in bootstrap /
+`create-terreno-app`).
+
+### Local storage (D3, D4 phase 2)
+
+Dev-only adapter on the app (new **`@terreno/syncdb`** export, wired in bootstrap template and
+`example-frontend`):
+
+```typescript
+registerTerrenoDevStorage({
+  asyncStorage: true,              // default: wire AsyncStorage getAllKeys/getItem/setItem
+  secureStoreKeyAllowlist?: string[]; // optional SecureStore keys readable/writable via MCP
+});
+```
+
+Sets `globalThis.__TERRENO_DEV_STORAGE__` with `{listKeys, get, set}` in `__DEV__` only.
+
+MCP tools:
+
+- **`read_local_storage`**: `{keys?: string[], prefix?: string}` — returns key/value pairs;
+  omit keys to return all keys from `listKeys()` (cap 200 keys, 8 KiB per value in output).
+- **`write_local_storage`**: `{key, value}` — EVAL-gated; rejects keys not allowed (SecureStore
+  keys not on allowlist).
+
+MMKV and custom stores: apps register via `registerTerrenoDevCommand` or extend the adapter in
+app code (document pattern; no MMKV in framework).
+
+### Native logs (D4 phase 3)
+
+Extend `read_logs` with source **`native`**:
+
+| Platform | Mechanism | When unavailable |
+|----------|-----------|------------------|
+| Android emulator/device | `adb logcat -d -t <N>` subprocess; optional `TERRENO_ADB_SERIAL` | Clear status: `adb` not on PATH or no device |
+| iOS Simulator | `xcrun simctl spawn booted log stream --style compact` with timeout/read cap | No booted sim or Xcode tools missing |
+
+Entries use `source: "native"`, plain-text `raw`, parsed `level` when log line matches common
+patterns. **Not** merged into `last_error` unless line matches error heuristics (document
+behavior). Opt-in env **`TERRENO_NATIVE_LOGS=0`** disables subprocess collection (default on).
+
+Web and Metro-only sessions: `native` source returns empty with status note.
+
+### Dev commands (D4 phase 4)
+
+App API ( **`@terreno/syncdb`** ):
+
+```typescript
+registerTerrenoDevCommand({
+  name: "seedTodos",
+  description: "Insert three fixture todos for the signed-in user",
+  inputSchema: { type: "object", properties: { count: { type: "number" } } },
+  handler: async ({count}) => ({created: count ?? 3}),
+});
+```
+
+Registry: `globalThis.__TERRENO_DEV_COMMANDS__` — map of name → `{description, inputSchema,
+handler}` (handlers run only inside the app via CDP evaluate, same as dispatch).
+
+MCP:
+
+- **`list_dev_commands`** — no args; JSON list of `{name, description, inputSchema}`.
+- **`invoke_dev_command`** — `{name, arguments?}`; EVAL-gated; returns JSON-serializable
+  result or structured error.
+
+Example: register one command in `example-frontend` that toggles a feature flag in AsyncStorage
+to prove the loop.
+
+## Notifications
+
+None.
+
+## UI
+
+No user-visible UI. Dev hooks are `__DEV__` only and no-op in production builds.
+
+## Phases
+
+| Phase | Scope | Depends on |
+|-------|-------|------------|
+| 1. Network via CDP | `metroDevSession` Network domain + `read_logs` `network` source | — |
+| 2. Dispatch + storage | `dispatch_client_action`, storage adapter, read/write tools, bootstrap + example | 1 (shares CDP) |
+| 3. Native logs | `read_logs` `native` source, adb/simctl collectors | — (parallel with 2 after 1) |
+| 4. Dev commands | Registry API, `list_dev_commands`, `invoke_dev_command`, example command | 2 (same evaluate path) |
+| 5. Documentation | Reference, how-to, explainer updates; real captured outputs | 1–4 |
+
+## Feature Flags & Migrations
+
+- No data migrations.
+- All new app hooks are stripped or no-op when `!__DEV__`.
+- `TERRENO_MCP_EVAL=1` remains opt-in; bootstrap must not enable it by default.
+- New env vars: `TERRENO_NATIVE_LOGS` (default on), `TERRENO_ADB_SERIAL` (optional).
+
+## Risks
+
+- **CDP load**: Enabling Network increases traffic on the single Hermes session; keep ring caps
+  and body truncation strict.
+- **Secret leakage**: Redact auth headers; never log request bodies that look like JWTs (regex
+  heuristic in normalizer).
+- **Storage writes**: Mis-invoked `write_local_storage` can corrupt auth tokens; tool description
+  and docs warn to prefer `syncdb_action` for synced data.
+- **Native log volume**: Cap lines per `read_logs` call; default `entries` applies per source.
+- **`invoke_dev_command`**: Arbitrary app code — same trust model as `evaluate`; dev-only registry.
+
+## Not Included / Future Work
+
+- SQLite file browser, notification dispatcher, network throttling, React tree/profiler MCP
+  tools, first-party MMKV adapter.
+
+## Files to Create / Modify
+
+| Area | Files |
+|------|--------|
+| CDP | `mcp-server/src/local/metro/metroDevSession.ts`, tests |
+| Logs | `mcp-server/src/local/tools/readLogs.ts`, tests |
+| Runtime tools | `mcp-server/src/local/tools/runtime.ts` or new `clientDispatch.ts`, `localStorage.ts`, `devCommands.ts` |
+| Registry | `syncdb/src/devMcpRegistry.ts` (or split files), `syncdb/src/index.ts`, tests |
+| Bootstrap | `mcp-server/src/docs/templates/bootstrap/frontend/**`, `create-terreno-app` store bootstrap |
+| Example | `example-frontend/app/_layout.tsx`, optional `devCommands.ts` |
+| Docs | `docs/reference/mcp-server.md`, `docs/how-to/debug-with-mcp.md`, `docs/explanation/ai-development-loop.md`, `docs/reference/environment-variables.md`, `mcp-server/README.md` |
+
+## Task List
+
+See [`docs/tasks/mcp-agent-debugger-gaps.md`](../tasks/mcp-agent-debugger-gaps.md).
+
+## E2E tests
+
+| ID | Spec or flow | Layer | Proves | Written in |
+| --- | --- | --- | --- | --- |
+| E1 | `mcp-server/src/local/localServer.e2e.test.ts` (extend) | process | `read_logs` returns at least one `network` entry after CDP mock emits `Network.responseReceived` | Task 1.3 |
+| E2 | `example-frontend/e2e/mcp-network-debug.spec.ts` | browser | A failing API call produces a 403/404 visible via agent workflow documented in how-to (page triggers fetch; test asserts backend log + optional network source when Metro attached in CI) | Task 5.2 |
+
+If CI cannot attach Metro CDP reliably, Task 5.2 records `None — Metro CDP not in CI` and E2
+becomes a manual evidence step in Task 5.1 only; unit/E1 coverage remains required.
+
+**Pick note (2026-11-06):** E2 browser spec not added — Metro CDP is not reliable in CI. E1
+(`localServer.e2e.test.ts`) plus unit tests satisfy automated proof.
+
+## Regression cases
+
+None — no hard-to-automate change
+
+## User guide
+
+None — operator/agent documentation only; no end-user workflow change
+
+## Acceptance Criteria
+
+- [x] `read_logs` documents and returns entries with `source: "network"` when the app performs
+  fetch/XHR over CDP, with auth headers redacted in captured output.
+- [x] `read_logs` documents and returns entries with `source: "native"` on Android (adb) and
+  iOS Simulator when tools are available, with clear status when not.
+- [x] `dispatch_client_action` dispatches a known action in `example-frontend` under
+  `TERRENO_MCP_EVAL=1` and `get_client_state` reflects the new state.
+- [x] `read_local_storage` / `write_local_storage` round-trip a key in `example-frontend` dev
+  build; write refused without `TERRENO_MCP_EVAL=1`.
+- [x] `list_dev_commands` / `invoke_dev_command` list and run the example-frontend registered
+  command with EVAL gate on invoke only.
+- [x] Reference and how-to pages list every new tool and source with real output captured in
+  Task 5.1.
+- [x] `bun run mcp:build`, affected package tests, and `bun run lint` pass.

package/src/docs/versioned/next/implementationPlans/syncdb-high-churn-fields.md

@@ -0,0 +1,266 @@
+# SyncDB: high-churn fields without a sequence claim per write
+
+**Status:** Draft  
+**Roadmap:** Area=`api`, Target=`Next`, Impact=`Feature`  
+**Branch:** syncdb-high-churn-fields  
+**Owner:** Josh Gachnang  
+**Created:** 2026-11-09  
+
+This is an options document. It describes the problem, compares five ways to handle it, and
+recommends an order. Nothing here is implemented yet; the Decisions table lists what needs an
+answer before a task list is written.
+
+## Goal
+
+A synced document can carry fields that change every few seconds (a gauge, a heartbeat, a
+progress counter) without each change costing three replicated writes and a round trip through
+the stream's counter document.
+
+## Problem
+
+Every write to a synced model outside a caller session does three things
+(`api/src/sync/syncSeqPlugin.ts`, `api/src/sync/models.ts`):
+
+1. `claimSyncSeqs`: a pipeline update on the stream's `synccounters` document that increments
+   `seq` and pushes a `pending` entry.
+2. The document write itself, stamped with `_syncSeq`.
+3. `confirmSyncSeqs`: a `$pull` of the `pending` entry.
+
+That is three oplog entries per write, two of them on one hot document per stream. The cost is
+the same whether the write changes a title a person typed or a memory reading that moved by a
+few kilobytes.
+
+### Measured in a consumer app (Shade, 2026-11-09)
+
+Shade projects each agent session's container memory (`memUsedBytes`, `memPercent`) into two
+synced collections every few seconds. Over a 20-hour oplog:
+
+| Namespace | Oplog entries | Size | Share |
+|---|---|---|---|
+| `synccounters` | 1,519,392 | 547 MB | 56% |
+| the two projection collections | 443,273 | 167 MB | 17% |
+| everything else | about 395,000 | about 270 MB | 27% |
+
+In one hour the sessions collection took 12,596 updates and its counter took 25,094. The
+replication oplog window fell from about 48 hours to 20 hours and tripped the oplog-window
+alert. Shade has since added a deadband in its own projection code, which is Option B below done
+by hand in one app.
+
+### What makes this hard
+
+- **Catch-up reads by sequence.** A snapshot pages `_syncSeq` in `(cursor, frontier]`
+  (`api/src/sync/routes.ts`). A write with no new sequence is invisible to a client that was
+  offline when it happened.
+- **Clients drop deltas that do not raise the sequence.** `applyDelta` ignores a delta whose
+  `seq` is not strictly higher than the stored entity's (`syncdb/src/sync/deltaApplier.ts`). An
+  unsequenced change cannot reuse the `sync:delta` event as it stands.
+- **The no-op check is all or nothing.** `pre("save")` already skips the claim when the only
+  modified path is `updated`. There is no way for a model to add its own fields to that set, and
+  the query-write path (`findOneAndUpdate`, `updateOne`) has no such check at all.
+
+## Non-Goals
+
+- Changing ordering or frontier guarantees for ordinary fields (C1 stays as it is).
+- Offline edits to high-churn fields. They are server-written values; client mutations on them
+  keep going through the normal sequenced path or are rejected.
+- Replacing the per-stream counter with another ordering source. See Option E, listed only for
+  completeness.
+
+## Options
+
+### Option A: volatile fields (unsequenced writes, live-only delivery, periodic sequencing)
+
+A model declares fields that change often:
+
+```ts
+sync: {
+  scope: {type: "broadcast"},
+  volatile: {fields: ["memUsedBytes", "memPercent"], sequenceEveryMs: 60_000},
+}
+```
+
+- A write whose meaningful modified paths are all volatile skips the claim and the confirm. The
+  document write still happens, so the value is durable and a snapshot of the document returns
+  the current value. Cost: one oplog entry instead of three.
+- The change-stream watcher sees the update with an unchanged `_syncSeq` and emits a new
+  `sync:volatile` event carrying `{collection, id, stream, seq, fields}`. The client merges the
+  fields into the entity it holds when `seq` matches the entity's sequence, and ignores the
+  event otherwise (a sequenced delta is on its way or already applied).
+- To bound staleness for clients that were offline, a volatile-only write is sequenced normally
+  when the document's last sequenced write is older than `sequenceEveryMs`. Catch-up then sees
+  a value at most that old. The plugin needs the time of the last sequenced write, either a new
+  `_syncSeqAt` stamp or an in-process map keyed by document id.
+- A write that touches any non-volatile field is sequenced as today and carries the volatile
+  fields with it.
+
+Cost and risk:
+
+- Protocol addition: a new socket event and a client handler. Older clients ignore the event and
+  see volatile fields refresh only on sequenced writes, which is a safe degradation.
+- The query-write path has to learn which fields an update touches (`$set`, `$unset`, `$inc`
+  keys) to decide whether it is volatile-only. Replacements are always sequenced.
+- The watcher has to distinguish "update with unchanged `_syncSeq`" from a sequenced delta.
+  `updateDescription.updatedFields` already says whether `_syncSeq` changed.
+- Permissions and masking apply to `sync:volatile` exactly as to deltas; the event must go
+  through the same per-socket serialization.
+
+Effect on the measured case: 3 entries per memory write down to 1, with no loss of live
+resolution. The two counter updates behind each projection write were about 320 MB of the
+980 MB measured, so roughly a third off Shade's total oplog volume.
+
+### Option B: declarative write coalescing (drop writes that do not matter yet)
+
+A model declares a tolerance and a minimum interval per field:
+
+```ts
+sync: {
+  scope: {type: "broadcast"},
+  coalesce: {
+    memPercent: {minDelta: 1, minIntervalMs: 15_000},
+    memUsedBytes: {follows: "memPercent"},
+  },
+}
+```
+
+- In `pre("save")` and the query-write hook, a write whose meaningful modified paths are all
+  coalesced fields, and where each change is inside its tolerance or its interval, is dropped
+  entirely: no claim, no document write, no oplog entry.
+- A change that exceeds the tolerance, or the first change after the interval, is written and
+  sequenced as today.
+
+Cost and risk:
+
+- No protocol change, no client change. Smallest diff of the five.
+- Lossy by design: clients see the value in steps. Fine for gauges, wrong for anything that must
+  be exact at rest. A trailing flush (write the last dropped value after the interval) fixes
+  "exact at rest" but needs an in-process timer, which does not survive a restart and misbehaves
+  with several API instances unless the timer is per instance and idempotent.
+- Dropping a `save()` silently is surprising. The hook must unmark the paths and leave the
+  in-memory document holding the stored value, or callers will read back a value that was never
+  written.
+- `minDelta` only means something for numbers. Other types get `minIntervalMs` only.
+
+Effect on the measured case: depends on the tolerance. A one-point deadband on `memPercent`
+removes nearly all of the writes for an idle session.
+
+### Option C: cheaper sequencing for every write (batched confirms)
+
+Keep the semantics and reduce the cost of the confirm. Today each confirm is its own `$pull`.
+Instead:
+
+- Hold confirmed seqs in a per-stream, in-process queue.
+- Fold the queue into the next claim on that stream: the claim's pipeline update already
+  rewrites `pending`, so it can filter out confirmed seqs in the same update.
+- Flush the queue with a standalone `$pull` after a short idle delay (for example 50 ms) so a
+  quiet stream's frontier still advances promptly.
+
+Cost and risk:
+
+- Under sustained writes this takes 3 entries per write to 2, and counter writes from 2 to 1.
+  A quiet stream gains nothing, since each write still gets its own flush.
+- The frontier lags by up to the flush delay. Deltas already carry `frontierSeq` and clients
+  clamp to it, so correctness holds, but cursor advancement and `hasMore` lag by the same
+  amount.
+- A crash loses queued confirms. Those entries age out through the existing 60-second lease,
+  so the frontier stalls for up to a minute after a crash under load. That is the same failure
+  mode as today's crash between claim and confirm, but it would now cover more seqs.
+- Helps every synced model with no configuration. Does nothing about the write to the document
+  itself, or about deltas fanned out to every subscriber.
+
+Effect on the measured case: up to half of the counter entries, so at most about a quarter
+off the total, with no app changes.
+
+### Option D: ephemeral channel (values that never touch MongoDB)
+
+Give apps a first-class way to publish values that are not part of the document at all:
+
+```ts
+syncApp.publishEphemeral({collection: "zergsessions", id, stream, fields: {memPercent: 41.2}});
+```
+
+- The server keeps the latest value per `(collection, id)` in memory and emits `sync:ephemeral`
+  to the stream's room. A client joining the room gets the current values in the join
+  acknowledgement.
+- The client keeps ephemeral fields in a separate in-memory layer that query hooks merge over
+  the stored entity. Nothing is written to the local store or to MongoDB.
+
+Cost and risk:
+
+- Zero oplog entries. The right model for presence, typing indicators, live gauges and progress.
+- Values are lost on server restart until the next publish, and are not available offline.
+- Several API instances need a shared fan-out (the Socket.IO adapter already in use, or Redis)
+  and a shared "latest value" store for joins, or a join can miss values published on another
+  instance.
+- Largest surface of the five: a server API, a socket event, a client layer, hook changes and
+  codegen typing for the ephemeral fields. Apps must move the fields out of their schema.
+
+Effect on the measured case: removes the projection writes and their counter updates, about
+half of Shade's oplog volume.
+
+### Option E: order by cluster time instead of a counter (not recommended)
+
+Stamp documents with the server's operation time (`$currentDate` with `$type: "timestamp"`) and
+use that as the cursor. No counter document, so one oplog entry per write for every model.
+
+Rejected for now: the stable-frontier problem that C1 solved comes back in a harder form
+(timestamps are assigned before commit, so a reader can see a later timestamp before an earlier
+one lands), stream-local ordering turns into global ordering, every stored client cursor needs a
+migration, and scope-move markers and tombstone compaction are both built on per-stream seqs.
+It is a rewrite of the protocol, listed so the comparison is complete.
+
+## Comparison
+
+| | Oplog entries per high-churn write | Live resolution | Offline catch-up | Protocol change | Client change | App change |
+|---|---|---|---|---|---|---|
+| Today | 3 | full | exact | | | |
+| A: volatile fields | 1 | full | stale by at most `sequenceEveryMs` | new event | new handler | config only |
+| B: coalescing | 0 for dropped writes, 3 for kept | stepped | exact for what was written | none | none | config only |
+| C: batched confirms | 2 under load | full | exact | none | none | none |
+| D: ephemeral channel | 0 | full | none | new event and join payload | new layer | move fields, new publish call |
+| E: cluster time | 1 | full | exact | rewrite | rewrite | none |
+
+## Recommendation
+
+1. **Ship B first.** It needs no protocol or client work, it is what the affected app has
+   already done by hand, and it fixes the alerting problem on its own. Start with
+   `minDelta` and `minIntervalMs`, without a trailing flush.
+2. **Then A**, for fields where stepping is not acceptable. It keeps full live resolution at a
+   third of the cost and degrades safely for older clients.
+3. **C is independent** and worth doing for every model, but it is an optimisation of the hot
+   path with a crash-recovery trade-off, so it should come with a load-harness comparison
+   (`api/src/sync/loadHarness.ts`) before it is approved.
+4. **D only if** presence-style features (typing, cursors, live progress) arrive on the roadmap.
+   It is the cleanest answer for values that should never be stored, and too much surface to
+   build for gauges alone.
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Which options go ahead, and in what order? | Open. Recommendation: B, then A; C separately after a load test; D deferred. |
+| B: does a dropped write need a trailing flush so the stored value is exact at rest? | Open. Recommendation: no in the first version. |
+| B: should a dropped `save()` be silent, or logged at debug level? | Open. Recommendation: debug log with model and paths. |
+| A: where does "last sequenced at" live, a `_syncSeqAt` field or process memory? | Open. Recommendation: `_syncSeqAt`, so it is correct across instances and restarts. |
+| A: default for `sequenceEveryMs` | Open. Recommendation: 60 seconds. |
+| A: may clients mutate volatile fields? | Open. Recommendation: reject in the mutation handler; they are server-written. |
+| C: flush delay, and is a longer post-crash frontier stall acceptable? | Open. Needs load-harness numbers. |
+
+## Phases
+
+Written once the decisions above are made. Each chosen option is its own phase with its own
+task list under `docs/tasks/`.
+
+## Files to Create / Modify
+
+For B and A, the likely touch points:
+
+- `api/src/sync/types.ts`: `SyncConfig.coalesce`, `SyncConfig.volatile`, the `sync:volatile`
+  payload type.
+- `api/src/sync/syncSeqPlugin.ts`: extend the no-op check in `pre("save")`; add the same check
+  to `preQueryWrite`.
+- `api/src/realtime/changeStreamWatcher.ts`: emit `sync:volatile` for updates that leave
+  `_syncSeq` unchanged on a model with volatile fields.
+- `api/src/sync/mutationHandler.ts`: reject client mutations on volatile fields.
+- `syncdb/src/sync/deltaApplier.ts` and `syncdb/src/client.ts`: apply `sync:volatile`.
+- `docs/explanation/local-first-data.md` and `docs/reference/syncdb.md`: document the options
+  and when to use each.

package/src/docs/versioned/next/reference/environment-variables.md

@@ -121,6 +121,8 @@ Hosting platforms scope variables per environment. Vercel has **Production**, **
 | `TERRENO_PROJECT_ROOT` | `terreno-mcp-local`, `terreno` CLI | ❌ | nearest Terreno project root | No | tooling |
 | `TERRENO_METRO_URL` | `terreno-mcp-local` | ❌ | frontend script port or `http://localhost:8082` | No | tooling |
 | `TERRENO_MCP_EVAL` | `terreno-mcp-local` | ❌ | disabled | No | tooling |
+| `TERRENO_NATIVE_LOGS` | `terreno-mcp-local` `read_logs` source `native` | ❌ | enabled (`0` disables) | No | tooling |
+| `TERRENO_ADB_SERIAL` | `terreno-mcp-local` native Android logs | ❌ | default `adb` device | No | tooling |
 | `TERRENO_WEB_URL` | `terreno` CLI | ❌ | `http://localhost:8082` | No | tooling |
 | `BUN_CHROME_PATH` | Bun WebView | ❌ | browser auto-discovery | No | tooling |
 | `TERRENO_OPENAPI` | `terreno` CLI | ❌ | — | No | tooling |

package/src/docs/versioned/next/reference/mcp-server.md

@@ -159,6 +159,18 @@ privately and are not returned. Start the local MCP with
 See [Debug a Terreno app with MCP](../how-to/debug-with-mcp.md) for examples and
 safety guidance.
 
+### Dev client hooks (`@terreno/syncdb`)
+
+| Tool | EVAL | Registration |
+| --- | --- | --- |
+| `read_logs` / `last_error` | no | sources include **network** and **native** |
+| `dispatch_client_action` | yes | `registerTerrenoDevClientDispatch` |
+| `read_local_storage` / `write_local_storage` | write | `registerTerrenoDevStorage` (reads redact auth-like keys) |
+| `list_dev_commands` / `invoke_dev_command` | invoke | `registerTerrenoDevCommand` |
+
+Network capture redacts `Authorization`, `Cookie`, `Set-Cookie`, and `Set-Auth-Token`.
+Failed requests include the URL from the matching `requestWillBeSent` `requestId`.
+
 ### terreno_search_docs
 
 BM25-style keyword search over markdown bundled with the MCP server: `docs/resources/*.md`, synced Diátaxis docs under `docs/versioned/`, and per-component excerpts derived from `ui-types-documentation.json`. **Prefer this tool before guessing** Terreno APIs (same posture as Laravel Boost `search-docs`).

package/src/docs/versioned/next/reference/test.md

@@ -361,7 +361,10 @@ exist or has no `smoke` script is an error.
 ## Coverage gates
 
 Package CI uses `scripts/check-coverage.ts` (`bun run test:coverage`, default 95%
-functions and lines) as the live gate. Bun 1.4.2+ may exit 1 on bunfig
+functions and lines) as the live gate. It runs the suite as concurrent
+`bun test --shard` processes and gates the merged LCOV; a sharded run below the
+threshold is confirmed with one unsplit pass
+([Test sharding](../explanation/test-sharding.md)). Bun 1.4.2+ may exit 1 on bunfig
 `coverageThreshold` before isolated LCOV merges; the script continues when tests
 reported `0 fail` and then enforces 95% on the merged report. The blocks
 coverage pass sets `--max-concurrency=1`, because Bun's default 20-way run