@aui.io/apollo 0.1.80 → 0.1.82

package/node_modules/@aui.io/apollo-core/dist/src/services/mockdb.d.ts

@@ -1,4 +1,4 @@
-import { MockDbClient, type MockDbCloneResponse, type MockDbIdentitiesResponse, type MockDbIdentitiesUpsertResponse, type MockDbProvisionResponse, type MockDbSampleData, type MockDbStatusResponse, type MockDbTokenAuth } from "../api/mock-db.js";
+import { MockDbClient, type MockDbCloneResponse, type MockDbIdentitiesResponse, type MockDbIdentitiesUpsertResponse, type MockDbProvisionResponse, type MockDbResetResponse, type MockDbResetScope, type MockDbRowsPage, type MockDbSampleData, type MockDbSeedMode, type MockDbSeedResponse, type MockDbStatusResponse, type MockDbTokenAuth, type MockDbTruncateResponse } from "../api/mock-db.js";
 import type { Context } from "../config/index.js";
 import { keyPrefixes } from "../config/mockdb-keys.js";
 /** Env var the wired `connections.yaml` reads the runtime key from by default. */
@@ -48,7 +48,88 @@ export declare function statusMockDb(context: Context, options?: MockDbServiceOp
 export declare function createCollection(context: Context, name: string, schema: unknown, options?: MockDbServiceOptions): Promise<unknown>;
 export declare function listCollections(context: Context, options?: MockDbServiceOptions): Promise<unknown>;
 export declare function updateCollection(context: Context, name: string, addColumns: unknown[], options?: MockDbServiceOptions): Promise<unknown>;
-export declare function seedRows(context: Context, collection: string, rows: unknown[], options?: MockDbServiceOptions): Promise<unknown>;
+export interface SeedRowsOptions extends MockDbServiceOptions {
+    /** append (default) / upsert / replace — see `MockDbSeedOptions`. */
+    mode?: MockDbSeedMode;
+    /** false → counts only in the reply (the CLI's choice for a file import). */
+    echo?: boolean;
+    /** replace only: also empty collections that reference this one. */
+    cascade?: boolean;
+}
+/** One request. Rows of any count ride it (the service batches its INSERTs); a file import batches on top (`seedRowsFromFile`). */
+export declare function seedRows(context: Context, collection: string, rows: unknown[], options?: SeedRowsOptions): Promise<MockDbSeedResponse>;
+/** Rows per request when a file is imported; well under any body-size limit for ordinary rows. */
+export declare const DEFAULT_SEED_BATCH_SIZE = 500;
+export interface SeedFileOptions extends SeedRowsOptions {
+    /** Rows per request (default `DEFAULT_SEED_BATCH_SIZE`). */
+    batchSize?: number;
+    /** Called after every batch lands. */
+    onProgress?: (progress: {
+        batch: number;
+        batches: number;
+        sent: number;
+        total: number;
+    }) => void;
+}
+export interface SeedFileResult {
+    file: string;
+    collection: string;
+    mode: MockDbSeedMode;
+    rowsRead: number;
+    batchSize: number;
+    batches: number;
+    inserted: number;
+    updated: number;
+    deleted: number;
+    /** replace: the collections the first batch emptied, child-first. */
+    replaced: string[];
+}
+/**
+ * Parse a seed file: a JSON array, the `{ "rows": [...] }` wrapper the service
+ * body uses, or NDJSON / JSON Lines (one object per line, blank lines ignored).
+ * The shape is detected from the content, not the extension, so `.json`,
+ * `.ndjson` and `.jsonl` all work.
+ */
+export declare function parseRowsFile(text: string, where: string): unknown[];
+/** Read + parse a seed file from disk. */
+export declare function readRowsFile(file: string): Promise<{
+    path: string;
+    rows: unknown[];
+}>;
+/**
+ * Seed a whole file in batches, sequentially, stopping at the first failure.
+ *
+ * `replace` is honoured by the FIRST batch only — it truncates and inserts in
+ * one service transaction — and the rest append, so the collection ends up
+ * holding exactly the file. `upsert` rides every batch (and is safe to
+ * re-run); `append` rides every batch. Nothing is auto-retried: a failed batch
+ * is reported with exactly which rows landed, so the caller re-sends only
+ * what is missing (or re-runs the whole file with `upsert`).
+ */
+export declare function seedRowsFromFile(context: Context, collection: string, file: string, options?: SeedFileOptions): Promise<SeedFileResult>;
+export declare function listRows(context: Context, collection: string, page?: {
+    limit?: number;
+    offset?: number;
+    resolve?: boolean;
+}, options?: MockDbServiceOptions): Promise<MockDbRowsPage>;
+export declare function patchRow(context: Context, collection: string, id: string, patch: Record<string, unknown>, options?: MockDbServiceOptions): Promise<unknown>;
+export declare function deleteRow(context: Context, collection: string, id: string, options?: MockDbServiceOptions): Promise<unknown>;
+export declare function truncateCollection(context: Context, name: string, options?: MockDbServiceOptions & {
+    cascade?: boolean;
+}): Promise<MockDbTruncateResponse>;
+export declare function deleteCollection(context: Context, name: string, options?: MockDbServiceOptions): Promise<unknown>;
+/**
+ * The key-stable reset. The local key cache is deliberately NOT cleared —
+ * the service never touched the agent record, so the stored keys are still
+ * the live ones; `delete` is the command that forgets them.
+ */
+export declare function resetMockDb(context: Context, options?: MockDbServiceOptions & {
+    scope?: MockDbResetScope;
+}): Promise<MockDbResetResponse>;
+/** Parse `--mode`; undefined means append. */
+export declare function parseSeedMode(raw: string | undefined): MockDbSeedMode | undefined;
+/** Parse `--scope`; undefined means data. */
+export declare function parseResetScope(raw: string | undefined): MockDbResetScope | undefined;
 export declare function createEndpoint(context: Context, body: Record<string, unknown>, options?: MockDbServiceOptions): Promise<unknown>;
 export declare function listEndpoints(context: Context, options?: MockDbServiceOptions): Promise<unknown>;
 export declare function getEndpoint(context: Context, slug: string, options?: MockDbServiceOptions): Promise<unknown>;
@@ -153,7 +234,7 @@ export declare function normalizeSchema(raw: unknown): {
  */
 export declare function normalizeAddColumns(raw: unknown): unknown[];
 /** The text emitted by `apollo mockdb guide` — the how-to for driving the mock DB. */
-export declare const MOCKDB_GUIDE = "# Mock DB \u2014 Apollo CLI Guide\n\nA per-agent **mock database** for building and testing agents that have no\nreal backend (or no test environment) yet. You define collections (tables),\nseed realistic data, and declare named read/write endpoints; the agent's\nprogram sources then call those endpoints at runtime through a\n`connections.yaml` connection. It supports relative date/time fields\n(`now-30d`) that stay fresh, and per-conversation copy-on-write keyed by the\nsession id, so test runs are isolated and resettable.\n\nAll `apollo mockdb` commands are **non-interactive**. Pass the global\n`--json` for the machine envelope (`{ \"success\": true, \"data\": ... }`).\n\n## How auth works (and why it's safe)\n\n- The agent comes from the checkout you are standing in (`.apollorc`) or\n  `--agent <id>`; the account from the active project (`--account <id>` or\n  `APOLLO_ACCOUNT_ID` to override).\n- Your Apollo token is sent **first-party from the CLI** only where the\n  service demands it: `provision`, `status`, `delete`, and minting a\n  management key. The service verifies it against Apollo (you must be a\n  member of the agent's account).\n- Provision returns two per-agent keys, stored under `~/.apollo/mockdb/`:\n  - **managementKey** \u2014 used for ALL other management calls (`X-Mgmt-Key`;\n    no Apollo token transmitted). Minted on demand if missing/rejected.\n  - **runtimeKey** \u2014 what the agent's connection uses at runtime; also what\n    `apollo mockdb execute` uses to test endpoints.\n\n## Typical workflow\n\n```bash\n# 1. Provision (stores the keys) and wire bundle/src/connections.yaml\napollo mockdb provision --wire\n\n# 2. Create collections (parents before children \u2014 FKs need the parent first)\napollo mockdb collections create --name users \\\n  --schema '{\"columns\":[{\"name\":\"id\",\"type\":\"text\",\"primaryKey\":true},{\"name\":\"name\",\"type\":\"text\"}]}'\napollo mockdb collections create --name accounts \\\n  --schema '{\"columns\":[{\"name\":\"id\",\"type\":\"text\",\"primaryKey\":true},{\"name\":\"user_id\",\"type\":\"text\",\"references\":\"users.id\"},{\"name\":\"balance\",\"type\":\"number\"},{\"name\":\"opened_at\",\"type\":\"reldate\"}]}'\n\n# 3. Seed data (relative date tokens allowed)\napollo mockdb seed --collection users --rows '[{\"id\":\"U1\",\"name\":\"Ada Lovelace\"}]'\napollo mockdb seed --collection accounts --rows '[{\"id\":\"A1\",\"user_id\":\"U1\",\"balance\":4200.5,\"opened_at\":\"now-400d\"}]'\n\n# 4. Declare the endpoints the agent will call\napollo mockdb endpoint create --slug get-accounts \\\n  --param-schema '{\"user_id\":{\"type\":\"string\",\"required\":true}}' \\\n  --spec '{\"kind\":\"read\",\"collection\":\"accounts\",\"where\":[{\"column\":\"user_id\",\"op\":\"eq\",\"param\":\"user_id\"}]}'\n\n# 4b. A read keyed by a SET of ids: op \"in\" + a param declared { \"type\": \"array\" }\napollo mockdb endpoint create --slug accounts-by-ids \\\n  --param-schema '{\"ids\":{\"type\":\"array\",\"required\":true}}' \\\n  --spec '{\"kind\":\"read\",\"collection\":\"accounts\",\"where\":[{\"column\":\"id\",\"op\":\"in\",\"param\":\"ids\"}]}'\n\n# 5. Test an endpoint under a session (runtime key + session = a conversation)\napollo mockdb execute --slug get-accounts --session test-1 --body '{\"user_id\":\"U1\"}'\napollo mockdb execute --slug accounts-by-ids --body '{\"ids\":[\"A1\",\"A3\"]}'\n\n# 6. Inspect / reset that session's overlay\napollo mockdb session get --key test-1\napollo mockdb session reset --key test-1\n```\n\nThen map each program source that names `connection: mock-db` to an endpoint\nunder `operations` in `bundle/src/connections.yaml` (`method: POST`,\n`path: /<slug>/execute`, `rows: $.data.rows` -- the stub `wire` writes carries\nthe template), export the runtime key as `MOCKDB_TOKEN` (or the connection's\n`token_env`), and `apollo validate && apollo push`.\n\n## Endpoint params \u2014 `--param-schema` types\n\nEvery param a spec references (`where` clauses, insert/update values) must be\ndeclared: `{ \"<name>\": { \"type\": <type>, \"required\"?: bool } }`. An unknown type\nis a 400 at `endpoint create` / `update`.\n\n| type | accepts |\n|---|---|\n| `string` | any value, stringified |\n| `integer` / `number` | a number (numeric strings accepted) |\n| `boolean` | `true` / `false` (the strings too) |\n| `json` | any JSON value, passed through untouched |\n| `array` | a JSON array -- **what `op: \"in\"` needs**. On a GET query string, `?ids=A1,A2` or `?ids=[\"A1\",\"A2\"]` |\n\nDo not declare a set as `string`: the array is stringified to `\"A1,A2\"` and the\n`in` clause rejects it (`where id op \"in\" needs an array value (param \"ids\"\nresolved to string -- declare it as { \"type\": \"array\" } in paramSchema)`).\n\nOn the runtime side nothing is typed: a list-valued key bound on the source rides a\nPOST body as a JSON array as-is (no `type:` on the connection variable -- the\nloader refuses one), and a query-string variable renders it comma-joined\n(`style: csv`, the default) or repeated (`style: repeat`); mock-db's `array`\nparam accepts either.\n\n## Personas for the playground simulator (`identities`)\n\nOnce the mock DB has data, the playground can offer a **persona picker** before\nthe first message so a tester speaks as a real seeded user. The payload is\nauthored here \u2014 the schema and seed values are already in hand:\n\n```bash\n# Read what's stored (no personas \u21D2 { \"personas\": [] } \u2014 the picker is off).\napollo mockdb identities get\n\n# Upsert the payload (large payloads are easier from a file).\napollo mockdb identities set --file personas.json\napollo mockdb identities set --sample-data '{\n  \"instructions\": \"Pick a persona to simulate as.\",\n  \"personas\": [\n    {\n      \"label\": \"Jane Doe (verified)\",\n      \"state\": \"verified\",\n      \"default\": true,\n      \"fields\": [\n        { \"key\": \"user_id\", \"label\": \"User ID\", \"value\": \"U1001\", \"group\": \"who_you_are\" },\n        { \"key\": \"pin\", \"label\": \"PIN\", \"value\": \"4321\", \"group\": \"verify\", \"role\": \"secret\" }\n      ]\n    }\n  ]\n}'\n```\n\nRules the service enforces (a 400 names the exact `personas[i].fields[j]`):\n\n- Each persona needs a non-empty `label` and `state`; each field needs\n  `key`, `label`, `value`, and a `group` of `who_you_are` | `verify` |\n  `good_to_know` | `records`.\n- Exactly **one** persona carries `default: true` (when there is at least one).\n- Optional per-field extras: `role` (`key` | `secret`), `audience`\n  (`user` | `simulator` | `both`), `required_to_start`, `match`, `maps_to`.\n- Optional per-persona `intents` (`{ title, message }`) seed suggested openers.\n\n`set` is a full **REPLACE**, not a merge \u2014 `{\"personas\":[]}` turns the picker\noff. Seed the values first: every persona value must exist in the mock DB.\nPersonas travel with the DB \u2014 `clone` and `export` carry them.\n\n## Cloning another agent's mock DB\n\n```bash\n# Copy a template agent's collections + rows + endpoints + personas into THIS\n# agent (the target must be empty; your account must own both agents):\napollo mockdb clone --from <templateAgentId>\n```\n\n## Commands\n\n| Command | What it does |\n|---|---|\n| `mockdb provision [--wire]` | Create the agent's mock DB; store runtime + management keys |\n| `mockdb status` | Ownership + local key prefixes + verdict (ok / empty / new / unknown) |\n| `mockdb describe` | Schema, relationships, relative-field flags, endpoints, row counts |\n| `mockdb collections create --name <n> --schema <json>` | Create a collection (table) |\n| `mockdb collections update --name <n> --add-columns <json>` | Add nullable columns (no rename/type-change/drop) |\n| `mockdb collections list` | List collections |\n| `mockdb seed --collection <n> --rows <json-array>` | Seed base rows |\n| `mockdb endpoint create --slug <s> --spec <json> [--param-schema <json>] [--description <t>]` | Declare a read/insert/update/delete endpoint |\n| `mockdb endpoint list` / `get <slug>` | List / inspect endpoints |\n| `mockdb endpoint update <slug> [--spec] [--param-schema] [--description]` | PATCH-merge an endpoint |\n| `mockdb endpoint delete <slug>` | Delete an endpoint (re-map operations + push after) |\n| `mockdb execute --slug <s> [--session <key>] [--body <json>]` | Run an endpoint with the runtime key |\n| `mockdb identities get` / `set --sample-data <json> | --file <path>` | Read / replace the persona payload |\n| `mockdb session get --key <key>` / `reset --key <key>` | Inspect / reset a session overlay |\n| `mockdb rotate mgmt` / `rotate runtime` | Mint fresh keys (re-wire after a runtime rotation) |\n| `mockdb clone --from <id>` | Clone another agent's mock DB into this one (target must be empty) |\n| `mockdb export` | Export schema + base data + endpoints + personas |\n| `mockdb keys` | Show locally stored key prefixes (no secrets) |\n| `mockdb wire [--connection-id] [--token-env]` | Write bundle/src/connections.yaml for the runtime key |\n| `mockdb delete --force` | Permanently delete the mock DB (Apollo token only) |\n| `mockdb guide [--output <file>]` | Write this guide to a file (default GUIDE.md) |\n\nCommon flags: `--agent <id>`, `--account <id>`, and the global `--json`.\n\n## Notes\n\n- Create collections **parent-first** (a `references` FK needs the parent).\n- **Writes need `--session`**; reads may omit it to peek at pristine base.\n- Endpoint `where`/value params must be declared in `--param-schema`, with a\n  type the service knows (`string|integer|number|boolean|json|array`); a set fed to\n  `op: \"in\"` is `array`.\n- `execute` resolves the runtime key from `$MOCKDB_TOKEN` \u2192 the local cache \u2192\n  a fresh mint (then reports `runtimeKeyResync` so you re-wire).\n- A blank 2xx from the service is a transient transport blip: reads retry it,\n  writes stop and tell you to verify before retrying (never duplicate rows).\n- Override the service URL with `APOLLO_MOCKDB_URL`.\n";
+export declare const MOCKDB_GUIDE = "# Mock DB \u2014 Apollo CLI Guide\n\nA per-agent **mock database** for building and testing agents that have no\nreal backend (or no test environment) yet. You define collections (tables),\nseed realistic data, and declare named read/write endpoints; the agent's\nprogram sources then call those endpoints at runtime through a\n`connections.yaml` connection. It supports relative date/time fields\n(`now-30d`) that stay fresh, and per-conversation copy-on-write keyed by the\nsession id, so test runs are isolated and resettable.\n\nAll `apollo mockdb` commands are **non-interactive**. Pass the global\n`--json` for the machine envelope (`{ \"success\": true, \"data\": ... }`).\n\n## How auth works (and why it's safe)\n\n- The agent comes from the checkout you are standing in (`.apollorc`) or\n  `--agent <id>`; the account from the active project (`--account <id>` or\n  `APOLLO_ACCOUNT_ID` to override).\n- Your Apollo token is sent **first-party from the CLI** only where the\n  service demands it: `provision`, `status`, `delete`, and minting a\n  management key. The service verifies it against Apollo (you must be a\n  member of the agent's account).\n- Provision returns two per-agent keys, stored under `~/.apollo/mockdb/`:\n  - **managementKey** \u2014 used for ALL other management calls (`X-Mgmt-Key`;\n    no Apollo token transmitted). Minted on demand if missing/rejected.\n  - **runtimeKey** \u2014 what the agent's connection uses at runtime; also what\n    `apollo mockdb execute` uses to test endpoints.\n\n## Typical workflow\n\n```bash\n# 1. Provision (stores the keys) and wire bundle/src/connections.yaml\napollo mockdb provision --wire\n\n# 2. Create collections (parents before children \u2014 FKs need the parent first)\napollo mockdb collections create --name users \\\n  --schema '{\"columns\":[{\"name\":\"id\",\"type\":\"text\",\"primaryKey\":true},{\"name\":\"name\",\"type\":\"text\"}]}'\napollo mockdb collections create --name accounts \\\n  --schema '{\"columns\":[{\"name\":\"id\",\"type\":\"text\",\"primaryKey\":true},{\"name\":\"user_id\",\"type\":\"text\",\"references\":\"users.id\"},{\"name\":\"balance\",\"type\":\"number\"},{\"name\":\"opened_at\",\"type\":\"reldate\"}]}'\n\n# 3. Seed data (relative date tokens allowed). Inline for a handful of rows,\n#    --file (a JSON array or NDJSON) for a real dataset -- any size, batched.\napollo mockdb seed --collection users --rows '[{\"id\":\"U1\",\"name\":\"Ada Lovelace\"}]'\napollo mockdb seed --collection accounts --file accounts.json\n\n# 4. Declare the endpoints the agent will call\napollo mockdb endpoint create --slug get-accounts \\\n  --param-schema '{\"user_id\":{\"type\":\"string\",\"required\":true}}' \\\n  --spec '{\"kind\":\"read\",\"collection\":\"accounts\",\"where\":[{\"column\":\"user_id\",\"op\":\"eq\",\"param\":\"user_id\"}]}'\n\n# 4b. A read keyed by a SET of ids: op \"in\" + a param declared { \"type\": \"array\" }\napollo mockdb endpoint create --slug accounts-by-ids \\\n  --param-schema '{\"ids\":{\"type\":\"array\",\"required\":true}}' \\\n  --spec '{\"kind\":\"read\",\"collection\":\"accounts\",\"where\":[{\"column\":\"id\",\"op\":\"in\",\"param\":\"ids\"}]}'\n\n# 5. Test an endpoint under a session (runtime key + session = a conversation)\napollo mockdb execute --slug get-accounts --session test-1 --body '{\"user_id\":\"U1\"}'\napollo mockdb execute --slug accounts-by-ids --body '{\"ids\":[\"A1\",\"A3\"]}'\n\n# 6. Inspect / reset that session's overlay\napollo mockdb session get --key test-1\napollo mockdb session reset --key test-1\n```\n\nThen map each program source that names `connection: mock-db` to an endpoint\nunder `operations` in `bundle/src/connections.yaml` (`method: POST`,\n`path: /<slug>/execute`, `rows: $.data.rows` -- the stub `wire` writes carries\nthe template), export the runtime key as `MOCKDB_TOKEN` (or the connection's\n`token_env`), and `apollo validate && apollo push`.\n\n## Endpoint params \u2014 `--param-schema` types\n\nEvery param a spec references (`where` clauses, insert/update values) must be\ndeclared: `{ \"<name>\": { \"type\": <type>, \"required\"?: bool } }`. An unknown type\nis a 400 at `endpoint create` / `update`.\n\n| type | accepts |\n|---|---|\n| `string` | any value, stringified |\n| `integer` / `number` | a number (numeric strings accepted) |\n| `boolean` | `true` / `false` (the strings too) |\n| `json` | any JSON value, passed through untouched |\n| `array` | a JSON array -- **what `op: \"in\"` needs**. On a GET query string, `?ids=A1,A2` or `?ids=[\"A1\",\"A2\"]` |\n\nDo not declare a set as `string`: the array is stringified to `\"A1,A2\"` and the\n`in` clause rejects it (`where id op \"in\" needs an array value (param \"ids\"\nresolved to string -- declare it as { \"type\": \"array\" } in paramSchema)`).\n\nOn the runtime side nothing is typed: a list-valued key bound on the source rides a\nPOST body as a JSON array as-is (no `type:` on the connection variable -- the\nloader refuses one), and a query-string variable renders it comma-joined\n(`style: csv`, the default) or repeated (`style: repeat`); mock-db's `array`\nparam accepts either.\n\n## Changing data without a drop (keys stay valid)\n\n`mockdb delete --force` forgets the agent, so the next `provision` mints NEW\nkeys and everything wired to the old runtime key -- the vault's `MOCKDB_TOKEN`,\na deployed connection -- breaks until re-wired. None of these touch the keys:\n\n```bash\n# Re-seed everything: empty every collection + session overlay, keep schema,\n# endpoints, personas and keys. Then seed again.\napollo mockdb reset --force\n# Start over from an empty DB with the SAME keys (drops collections + endpoints + personas).\napollo mockdb reset --scope all --force\n\n# One collection: empty it (a parent with populated FK children is refused\n# unless --cascade, which empties the children too), drop it, or edit one row.\napollo mockdb collections truncate --name orders\napollo mockdb collections truncate --name users --cascade\napollo mockdb collections delete --name scratch --force\napollo mockdb rows list --collection users --limit 20\napollo mockdb rows patch --collection users --id U1 --set '{\"tier\":\"gold\"}'\napollo mockdb rows delete --collection users --id U9\n\n# Seed modes: upsert patches rows whose key exists (safe to re-run a file);\n# replace empties the collection first, in one transaction.\napollo mockdb seed --collection users --file users.json --mode upsert\napollo mockdb seed --collection orders --file orders.ndjson --mode replace\n```\n\nA read is never silently capped: `execute` replies `data.total` (the full\nmatch) and `data.hasMore` beside `rows`/`count`. Anything that sums or\ncounts rows must page (`offset` += `count`) until `hasMore` is false -- the\n`pagination:` stanza `wire` writes makes the engine do that on its own.\n\n## Personas for the playground simulator (`identities`)\n\nOnce the mock DB has data, the playground can offer a **persona picker** before\nthe first message so a tester speaks as a real seeded user. The payload is\nauthored here \u2014 the schema and seed values are already in hand:\n\n```bash\n# Read what's stored (no personas \u21D2 { \"personas\": [] } \u2014 the picker is off).\napollo mockdb identities get\n\n# Upsert the payload (large payloads are easier from a file).\napollo mockdb identities set --file personas.json\napollo mockdb identities set --sample-data '{\n  \"instructions\": \"Pick a persona to simulate as.\",\n  \"personas\": [\n    {\n      \"label\": \"Jane Doe (verified)\",\n      \"state\": \"verified\",\n      \"default\": true,\n      \"fields\": [\n        { \"key\": \"user_id\", \"label\": \"User ID\", \"value\": \"U1001\", \"group\": \"who_you_are\" },\n        { \"key\": \"pin\", \"label\": \"PIN\", \"value\": \"4321\", \"group\": \"verify\", \"role\": \"secret\" }\n      ]\n    }\n  ]\n}'\n```\n\nRules the service enforces (a 400 names the exact `personas[i].fields[j]`):\n\n- Each persona needs a non-empty `label` and `state`; each field needs\n  `key`, `label`, `value`, and a `group` of `who_you_are` | `verify` |\n  `good_to_know` | `records`.\n- Exactly **one** persona carries `default: true` (when there is at least one).\n- Optional per-field extras: `role` (`key` | `secret`), `audience`\n  (`user` | `simulator` | `both`), `required_to_start`, `match`, `maps_to`.\n- Optional per-persona `intents` (`{ title, message }`) seed suggested openers.\n\n`set` is a full **REPLACE**, not a merge \u2014 `{\"personas\":[]}` turns the picker\noff. Seed the values first: every persona value must exist in the mock DB.\nPersonas travel with the DB \u2014 `clone` and `export` carry them.\n\n## Cloning another agent's mock DB\n\n```bash\n# Copy a template agent's collections + rows + endpoints + personas into THIS\n# agent (the target must be empty; your account must own both agents):\napollo mockdb clone --from <templateAgentId>\n```\n\n## Commands\n\n| Command | What it does |\n|---|---|\n| `mockdb provision [--wire]` | Create the agent's mock DB; store runtime + management keys |\n| `mockdb status` | Ownership + local key prefixes + verdict (ok / empty / new / unknown) |\n| `mockdb describe` | Schema, relationships, relative-field flags, endpoints, row counts |\n| `mockdb collections create --name <n> --schema <json>` | Create a collection (table) |\n| `mockdb collections update --name <n> --add-columns <json>` | Add nullable columns (no rename/type-change/drop) |\n| `mockdb collections list` | List collections |\n| `mockdb collections truncate --name <n> [--cascade]` | Empty a collection (base rows + its session overlay records); keys stay |\n| `mockdb collections delete --name <n> --force` | Drop a collection and its table |\n| `mockdb seed --collection <n> (--rows <json-array> \\| --file <path>) [--mode append\\|upsert\\|replace] [--batch <n>] [--cascade]` | Seed base rows; a file (JSON array or NDJSON) is sent in batches |\n| `mockdb rows list --collection <n> [--limit] [--offset] [--resolve]` | Page through base rows (with the total) |\n| `mockdb rows patch --collection <n> --id <id> --set <json>` | Edit one base row by primary key |\n| `mockdb rows delete --collection <n> --id <id>` | Remove one base row by primary key |\n| `mockdb reset [--scope data\\|all] --force` | Key-stable reset: `data` empties every collection + sessions; `all` also drops collections, endpoints, personas |\n| `mockdb endpoint create --slug <s> --spec <json> [--param-schema <json>] [--description <t>]` | Declare a read/insert/update/delete endpoint |\n| `mockdb endpoint list` / `get <slug>` | List / inspect endpoints |\n| `mockdb endpoint update <slug> [--spec] [--param-schema] [--description]` | PATCH-merge an endpoint |\n| `mockdb endpoint delete <slug>` | Delete an endpoint (re-map operations + push after) |\n| `mockdb execute --slug <s> [--session <key>] [--body <json>]` | Run an endpoint with the runtime key |\n| `mockdb identities get` / `set --sample-data <json> | --file <path>` | Read / replace the persona payload |\n| `mockdb session get --key <key>` / `reset --key <key>` | Inspect / reset a session overlay |\n| `mockdb rotate mgmt` / `rotate runtime` | Mint fresh keys (re-wire after a runtime rotation) |\n| `mockdb clone --from <id>` | Clone another agent's mock DB into this one (target must be empty) |\n| `mockdb export` | Export schema + base data + endpoints + personas |\n| `mockdb keys` | Show locally stored key prefixes (no secrets) |\n| `mockdb wire [--connection-id] [--token-env]` | Write bundle/src/connections.yaml for the runtime key |\n| `mockdb delete --force` | Permanently delete the mock DB (Apollo token only) -- the next provision mints NEW keys; prefer `reset` |\n| `mockdb guide [--output <file>]` | Write this guide to a file (default GUIDE.md) |\n\nCommon flags: `--agent <id>`, `--account <id>`, and the global `--json`.\n\n## Notes\n\n- Create collections **parent-first** (a `references` FK needs the parent).\n- **Writes need `--session`**; reads may omit it to peek at pristine base.\n- Endpoint `where`/value params must be declared in `--param-schema`, with a\n  type the service knows (`string|integer|number|boolean|json|array`); a set fed to\n  `op: \"in\"` is `array`.\n- `execute` resolves the runtime key from `$MOCKDB_TOKEN` \u2192 the local cache \u2192\n  a fresh mint (then reports `runtimeKeyResync` so you re-wire).\n- A read replies at most `limit` rows (default 100, cap 1000) and says so:\n  `data.total` / `data.hasMore`. Page with `offset` until `hasMore` is false.\n- A blank 2xx from the service is a transient transport blip: reads retry it,\n  writes stop and tell you to verify before retrying (never duplicate rows).\n- Override the service URL with `APOLLO_MOCKDB_URL`.\n";
 /** Write the guide to `outputPath` (default `GUIDE.md` in the cwd). */
 export declare function writeMockDbGuide(outputPath?: string): Promise<{
     written: true;

package/node_modules/@aui.io/apollo-core/dist/src/services/mockdb.js

@@ -28,7 +28,7 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
-import { isMockDbTransportError, MockDbClient, mockDbErrorCode, } from "../api/mock-db.js";
+import { isMockDbTransportError, MOCKDB_RESET_SCOPES, MOCKDB_SEED_MODES, MockDbClient, mockDbErrorCode, } from "../api/mock-db.js";
 import { clearMockDbKeys, keyPrefixes, loadMockDbKeys, saveMockDbKeys, } from "../config/mockdb-keys.js";
 import { ApiError, AuthError, CliError, ConfigError, ValidationError, } from "../errors/index.js";
 /** Env var the wired `connections.yaml` reads the runtime key from by default. */
@@ -158,6 +158,10 @@ function blankBodyError(resolved, op, kind) {
         tail =
             "No key was stored, so nothing changed and it is safe to re-run. If it persists, the backend key-mint path is failing — check `apollo mockdb status` and report it.";
     }
+    else if (kind === "idempotent") {
+        tail =
+            "The operation may or may not have applied, and re-running it is SAFE (it is idempotent) — check with `apollo mockdb describe`, then re-run.";
+    }
     else {
         tail =
             "The write MAY have already landed server-side, so do NOT blindly retry (re-running an insert/seed can DUPLICATE rows). Verify first — `apollo mockdb describe` / `collections list` for base writes, `apollo mockdb session get --key <session>` for runtime writes — then retry only what's actually missing.";
@@ -171,6 +175,17 @@ async function readWithRetry(resolved, op, fn) {
         blankBodyError(resolved, op, "read");
     return result;
 }
+/**
+ * Run an IDEMPOTENT change (a reset, a truncate, a row patch/delete): a blank
+ * body is retried like a read — repeating it cannot duplicate anything — and
+ * a persistent blank fails with the honest word for it.
+ */
+async function idempotentWithRetry(resolved, op, fn) {
+    const result = await retryWhile(isEmptyReadObject, fn);
+    if (isEmptyReadObject(result))
+        blankBodyError(resolved, op, "idempotent");
+    return result;
+}
 function isAuthRejection(error) {
     return error instanceof ApiError && (error.status === 401 || error.status === 403);
 }
@@ -361,14 +376,210 @@ export async function updateCollection(context, name, addColumns, options = {})
         blankBodyError(resolved, "collections update", "write");
     return resp;
 }
+/** One request. Rows of any count ride it (the service batches its INSERTs); a file import batches on top (`seedRowsFromFile`). */
 export async function seedRows(context, collection, rows, options = {}) {
     const resolved = resolveMockDb(context, options);
-    // Seeding APPENDS rows — never auto-retry a blank (a repeat could duplicate).
-    const resp = await withManage(resolved, (auth) => resolved.client.seedRows(resolved.agentId, auth, collection, rows));
+    const seedOptions = {
+        ...(options.mode === undefined ? {} : { mode: options.mode }),
+        ...(options.echo === undefined ? {} : { echo: options.echo }),
+        ...(options.cascade === undefined ? {} : { cascade: options.cascade }),
+    };
+    // A seed WRITES rows — never auto-retry a blank (an append repeat could duplicate).
+    const resp = await withManage(resolved, (auth) => resolved.client.seedRows(resolved.agentId, auth, collection, rows, seedOptions));
     if (isEmptyReadObject(resp))
         blankBodyError(resolved, "seed", "write");
     return resp;
 }
+/** Rows per request when a file is imported; well under any body-size limit for ordinary rows. */
+export const DEFAULT_SEED_BATCH_SIZE = 500;
+/**
+ * Parse a seed file: a JSON array, the `{ "rows": [...] }` wrapper the service
+ * body uses, or NDJSON / JSON Lines (one object per line, blank lines ignored).
+ * The shape is detected from the content, not the extension, so `.json`,
+ * `.ndjson` and `.jsonl` all work.
+ */
+export function parseRowsFile(text, where) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        throw new ValidationError(`${where} is empty.`, "Give it a JSON array of rows, or one JSON object per line.");
+    if (trimmed.startsWith("[")) {
+        const parsed = parseJsonFlag(where, trimmed);
+        if (!Array.isArray(parsed))
+            throw new ValidationError(`${where} must be a JSON array of rows.`);
+        return parsed;
+    }
+    if (trimmed.startsWith("{")) {
+        // One whole-file object carrying `rows` is the wrapper, not a one-row NDJSON file.
+        let whole;
+        try {
+            whole = JSON.parse(trimmed);
+        }
+        catch {
+            whole = undefined; // more than one line, or not JSON at all: NDJSON below decides
+        }
+        const wrapped = whole?.rows;
+        if (Array.isArray(wrapped))
+            return wrapped;
+    }
+    const rows = [];
+    const lines = trimmed.split(/\r?\n/);
+    lines.forEach((line, i) => {
+        if (!line.trim())
+            return;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch (error) {
+            throw new ValidationError(`${where} line ${i + 1} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`, "A seed file is either one JSON array, or one JSON object per line (NDJSON).");
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new ValidationError(`${where} line ${i + 1} must be a JSON object (a row).`);
+        }
+        rows.push(parsed);
+    });
+    return rows;
+}
+/** Read + parse a seed file from disk. */
+export async function readRowsFile(file) {
+    const resolvedPath = path.resolve(file);
+    let raw;
+    try {
+        raw = await readFile(resolvedPath, "utf8");
+    }
+    catch (error) {
+        throw new ValidationError(`--file could not be read: ${error instanceof Error ? error.message : String(error)}`, `Check that ${resolvedPath} exists and is readable.`);
+    }
+    return { path: resolvedPath, rows: parseRowsFile(raw, `--file (${resolvedPath})`) };
+}
+/**
+ * Seed a whole file in batches, sequentially, stopping at the first failure.
+ *
+ * `replace` is honoured by the FIRST batch only — it truncates and inserts in
+ * one service transaction — and the rest append, so the collection ends up
+ * holding exactly the file. `upsert` rides every batch (and is safe to
+ * re-run); `append` rides every batch. Nothing is auto-retried: a failed batch
+ * is reported with exactly which rows landed, so the caller re-sends only
+ * what is missing (or re-runs the whole file with `upsert`).
+ */
+export async function seedRowsFromFile(context, collection, file, options = {}) {
+    const mode = options.mode ?? "append";
+    const batchSize = options.batchSize ?? DEFAULT_SEED_BATCH_SIZE;
+    if (!Number.isInteger(batchSize) || batchSize < 1) {
+        throw new ValidationError("--batch must be a positive integer.", `The default is ${String(DEFAULT_SEED_BATCH_SIZE)} rows per request.`);
+    }
+    const { path: resolvedPath, rows } = await readRowsFile(file);
+    if (rows.length === 0)
+        throw new ValidationError(`${resolvedPath} holds no rows.`);
+    const batches = Math.ceil(rows.length / batchSize);
+    const result = {
+        file: resolvedPath,
+        collection,
+        mode,
+        rowsRead: rows.length,
+        batchSize,
+        batches,
+        inserted: 0,
+        updated: 0,
+        deleted: 0,
+        replaced: [],
+    };
+    let sent = 0;
+    for (let batch = 0; batch < batches; batch++) {
+        const slice = rows.slice(batch * batchSize, (batch + 1) * batchSize);
+        // Only the first batch may truncate; the ones after it must land beside it.
+        const batchMode = mode === "replace" && batch > 0 ? "append" : mode;
+        let resp;
+        try {
+            resp = await seedRows(context, collection, slice, {
+                ...(options.agentId === undefined ? {} : { agentId: options.agentId }),
+                ...(options.accountId === undefined ? {} : { accountId: options.accountId }),
+                ...(options.tokenEnv === undefined ? {} : { tokenEnv: options.tokenEnv }),
+                ...(options.homeDir === undefined ? {} : { homeDir: options.homeDir }),
+                ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
+                mode: batchMode,
+                echo: false,
+                // cascade belongs to the truncating batch only.
+                ...(batchMode === "replace" ? { cascade: options.cascade === true } : {}),
+            });
+        }
+        catch (error) {
+            const first = batch * batchSize;
+            const last = first + slice.length - 1;
+            let landed;
+            if (batch === 0) {
+                landed =
+                    mode === "replace"
+                        ? "Nothing changed: a replace is one transaction, so the collection still holds its previous rows."
+                        : "Nothing from the file is in the collection.";
+            }
+            else {
+                landed = `Rows 0-${String(first - 1)} of the file (${String(sent)} rows, ${String(batch)} batch${batch === 1 ? "" : "es"}) are in the collection${mode === "replace" ? " (the first batch replaced the old rows)" : ""}; nothing from this batch or after it is.`;
+            }
+            throw new CliError(`mockdb seed --file: batch ${String(batch + 1)}/${String(batches)} (rows ${String(first)}-${String(last)} of ${resolvedPath}) failed: ${error instanceof Error ? error.message : String(error)}`, {
+                code: error instanceof CliError ? error.code : "API_SERVER_ERROR",
+                suggestion: `${landed} NOT auto-retried. Fix the rows and re-send from row ${String(first)} ` +
+                    `(or re-run the whole file with --mode upsert, which is safe to repeat).`,
+                cause: error,
+            });
+        }
+        sent += slice.length;
+        result.inserted += resp.inserted ?? 0;
+        result.updated += resp.updated ?? 0;
+        result.deleted += resp.deleted ?? 0;
+        if (batch === 0 && Array.isArray(resp.replaced))
+            result.replaced = resp.replaced.map(String);
+        options.onProgress?.({ batch: batch + 1, batches, sent, total: rows.length });
+    }
+    return result;
+}
+export async function listRows(context, collection, page = {}, options = {}) {
+    const resolved = resolveMockDb(context, options);
+    return readWithRetry(resolved, "rows list", () => withManage(resolved, (auth) => resolved.client.listRows(resolved.agentId, auth, collection, page)));
+}
+export async function patchRow(context, collection, id, patch, options = {}) {
+    const resolved = resolveMockDb(context, options);
+    return idempotentWithRetry(resolved, "rows patch", () => withManage(resolved, (auth) => resolved.client.patchRow(resolved.agentId, auth, collection, id, patch)));
+}
+export async function deleteRow(context, collection, id, options = {}) {
+    const resolved = resolveMockDb(context, options);
+    return idempotentWithRetry(resolved, "rows delete", () => withManage(resolved, (auth) => resolved.client.deleteRow(resolved.agentId, auth, collection, id)));
+}
+export async function truncateCollection(context, name, options = {}) {
+    const resolved = resolveMockDb(context, options);
+    return idempotentWithRetry(resolved, "collections truncate", () => withManage(resolved, (auth) => resolved.client.truncateCollection(resolved.agentId, auth, name, { cascade: options.cascade === true })));
+}
+export async function deleteCollection(context, name, options = {}) {
+    const resolved = resolveMockDb(context, options);
+    return idempotentWithRetry(resolved, "collections delete", () => withManage(resolved, (auth) => resolved.client.deleteCollection(resolved.agentId, auth, name)));
+}
+/**
+ * The key-stable reset. The local key cache is deliberately NOT cleared —
+ * the service never touched the agent record, so the stored keys are still
+ * the live ones; `delete` is the command that forgets them.
+ */
+export async function resetMockDb(context, options = {}) {
+    const resolved = resolveMockDb(context, options);
+    return idempotentWithRetry(resolved, "reset", () => withManage(resolved, (auth) => resolved.client.resetAgent(resolved.agentId, auth, options.scope === undefined ? {} : { scope: options.scope })));
+}
+/** Parse `--mode`; undefined means append. */
+export function parseSeedMode(raw) {
+    if (raw === undefined)
+        return undefined;
+    const value = raw.trim();
+    if (MOCKDB_SEED_MODES.includes(value))
+        return value;
+    throw new ValidationError(`--mode must be one of ${MOCKDB_SEED_MODES.join(", ")} (got ${JSON.stringify(raw)}).`, "append inserts (duplicate key → 409); upsert patches rows whose key exists; replace empties the collection first.");
+}
+/** Parse `--scope`; undefined means data. */
+export function parseResetScope(raw) {
+    if (raw === undefined)
+        return undefined;
+    const value = raw.trim();
+    if (MOCKDB_RESET_SCOPES.includes(value))
+        return value;
+    throw new ValidationError(`--scope must be one of ${MOCKDB_RESET_SCOPES.join(", ")} (got ${JSON.stringify(raw)}).`, "data empties every collection and clears sessions (schema + endpoints + personas stay); all also drops collections, endpoints and personas. Keys survive both.");
+}
 export async function createEndpoint(context, body, options = {}) {
     const resolved = resolveMockDb(context, options);
     const resp = await withManage(resolved, (auth) => resolved.client.createEndpoint(resolved.agentId, auth, body));
@@ -776,6 +987,18 @@ export async function wireMockDbConnection(context, options = {}) {
         `    #     method: POST`,
         `    #     path: /<endpoint-slug>/execute`,
         `    #     rows: $.data.rows`,
+        `    #     # A read replies 100 rows per page (data.total / data.hasMore say`,
+        `    #     # when it was capped). Keep pagination on every read a program may`,
+        `    #     # sum or count: the engine then walks the pages by offset instead`,
+        `    #     # of totalling the first hundred, and \`more:\` lets it stop on the`,
+        `    #     # server's own "no more" (needs a runtime that carries \`more:\` --`,
+        `    #     # every release up to 0.10.25 refuses the key: drop that one line`,
+        `    #     # there, never the pagination).`,
+        `    #     pagination:`,
+        `    #       style: offset`,
+        `    #       request: offset`,
+        `    #       max_pages: 10`,
+        `    #     more: $.data.hasMore`,
         ``,
     ].join("\n");
     let existing = "";
@@ -894,9 +1117,10 @@ apollo mockdb collections create --name users \\
 apollo mockdb collections create --name accounts \\
   --schema '{"columns":[{"name":"id","type":"text","primaryKey":true},{"name":"user_id","type":"text","references":"users.id"},{"name":"balance","type":"number"},{"name":"opened_at","type":"reldate"}]}'
 
-# 3. Seed data (relative date tokens allowed)
+# 3. Seed data (relative date tokens allowed). Inline for a handful of rows,
+#    --file (a JSON array or NDJSON) for a real dataset -- any size, batched.
 apollo mockdb seed --collection users --rows '[{"id":"U1","name":"Ada Lovelace"}]'
-apollo mockdb seed --collection accounts --rows '[{"id":"A1","user_id":"U1","balance":4200.5,"opened_at":"now-400d"}]'
+apollo mockdb seed --collection accounts --file accounts.json
 
 # 4. Declare the endpoints the agent will call
 apollo mockdb endpoint create --slug get-accounts \\
@@ -947,6 +1171,39 @@ loader refuses one), and a query-string variable renders it comma-joined
 (\`style: csv\`, the default) or repeated (\`style: repeat\`); mock-db's \`array\`
 param accepts either.
 
+## Changing data without a drop (keys stay valid)
+
+\`mockdb delete --force\` forgets the agent, so the next \`provision\` mints NEW
+keys and everything wired to the old runtime key -- the vault's \`MOCKDB_TOKEN\`,
+a deployed connection -- breaks until re-wired. None of these touch the keys:
+
+\`\`\`bash
+# Re-seed everything: empty every collection + session overlay, keep schema,
+# endpoints, personas and keys. Then seed again.
+apollo mockdb reset --force
+# Start over from an empty DB with the SAME keys (drops collections + endpoints + personas).
+apollo mockdb reset --scope all --force
+
+# One collection: empty it (a parent with populated FK children is refused
+# unless --cascade, which empties the children too), drop it, or edit one row.
+apollo mockdb collections truncate --name orders
+apollo mockdb collections truncate --name users --cascade
+apollo mockdb collections delete --name scratch --force
+apollo mockdb rows list --collection users --limit 20
+apollo mockdb rows patch --collection users --id U1 --set '{"tier":"gold"}'
+apollo mockdb rows delete --collection users --id U9
+
+# Seed modes: upsert patches rows whose key exists (safe to re-run a file);
+# replace empties the collection first, in one transaction.
+apollo mockdb seed --collection users --file users.json --mode upsert
+apollo mockdb seed --collection orders --file orders.ndjson --mode replace
+\`\`\`
+
+A read is never silently capped: \`execute\` replies \`data.total\` (the full
+match) and \`data.hasMore\` beside \`rows\`/\`count\`. Anything that sums or
+counts rows must page (\`offset\` += \`count\`) until \`hasMore\` is false -- the
+\`pagination:\` stanza \`wire\` writes makes the engine do that on its own.
+
 ## Personas for the playground simulator (\`identities\`)
 
 Once the mock DB has data, the playground can offer a **persona picker** before
@@ -1007,7 +1264,13 @@ apollo mockdb clone --from <templateAgentId>
 | \`mockdb collections create --name <n> --schema <json>\` | Create a collection (table) |
 | \`mockdb collections update --name <n> --add-columns <json>\` | Add nullable columns (no rename/type-change/drop) |
 | \`mockdb collections list\` | List collections |
-| \`mockdb seed --collection <n> --rows <json-array>\` | Seed base rows |
+| \`mockdb collections truncate --name <n> [--cascade]\` | Empty a collection (base rows + its session overlay records); keys stay |
+| \`mockdb collections delete --name <n> --force\` | Drop a collection and its table |
+| \`mockdb seed --collection <n> (--rows <json-array> \\| --file <path>) [--mode append\\|upsert\\|replace] [--batch <n>] [--cascade]\` | Seed base rows; a file (JSON array or NDJSON) is sent in batches |
+| \`mockdb rows list --collection <n> [--limit] [--offset] [--resolve]\` | Page through base rows (with the total) |
+| \`mockdb rows patch --collection <n> --id <id> --set <json>\` | Edit one base row by primary key |
+| \`mockdb rows delete --collection <n> --id <id>\` | Remove one base row by primary key |
+| \`mockdb reset [--scope data\\|all] --force\` | Key-stable reset: \`data\` empties every collection + sessions; \`all\` also drops collections, endpoints, personas |
 | \`mockdb endpoint create --slug <s> --spec <json> [--param-schema <json>] [--description <t>]\` | Declare a read/insert/update/delete endpoint |
 | \`mockdb endpoint list\` / \`get <slug>\` | List / inspect endpoints |
 | \`mockdb endpoint update <slug> [--spec] [--param-schema] [--description]\` | PATCH-merge an endpoint |
@@ -1020,7 +1283,7 @@ apollo mockdb clone --from <templateAgentId>
 | \`mockdb export\` | Export schema + base data + endpoints + personas |
 | \`mockdb keys\` | Show locally stored key prefixes (no secrets) |
 | \`mockdb wire [--connection-id] [--token-env]\` | Write bundle/src/connections.yaml for the runtime key |
-| \`mockdb delete --force\` | Permanently delete the mock DB (Apollo token only) |
+| \`mockdb delete --force\` | Permanently delete the mock DB (Apollo token only) -- the next provision mints NEW keys; prefer \`reset\` |
 | \`mockdb guide [--output <file>]\` | Write this guide to a file (default GUIDE.md) |
 
 Common flags: \`--agent <id>\`, \`--account <id>\`, and the global \`--json\`.
@@ -1034,6 +1297,8 @@ Common flags: \`--agent <id>\`, \`--account <id>\`, and the global \`--json\`.
   \`op: "in"\` is \`array\`.
 - \`execute\` resolves the runtime key from \`$MOCKDB_TOKEN\` → the local cache →
   a fresh mint (then reports \`runtimeKeyResync\` so you re-wire).
+- A read replies at most \`limit\` rows (default 100, cap 1000) and says so:
+  \`data.total\` / \`data.hasMore\`. Page with \`offset\` until \`hasMore\` is false.
 - A blank 2xx from the service is a transient transport blip: reads retry it,
   writes stop and tell you to verify before retrying (never duplicate rows).
 - Override the service URL with \`APOLLO_MOCKDB_URL\`.