@lunora/cli 1.0.0-alpha.32 → 1.0.0-alpha.320

package/skills/lunora-deploy/SKILL.md

@@ -29,9 +29,16 @@ D1 database, R2 buckets, and secrets — so the work is mostly making
 
 `lunora deploy` runs a fixed pipeline:
 
-1. **Codegen** — regenerates `lunora/_generated/` and typechecks.
-2. **Validate `wrangler.jsonc`** — required `compatibility_date`, the
-   `nodejs_compat` flag, and the `SHARD` Durable Object binding.
+1. **Codegen** — regenerates `lunora/_generated/`. It does **not** run
+   `tsc`: nothing in the deploy pipeline type-checks, and wrangler/esbuild
+   strips types, so a project with a TS error deploys. Run `lunora verify`
+   (which does run `tsc --noEmit`) as the CI type gate before this.
+2. **Validate `wrangler.jsonc`** — a `compatibility_date` at or past the
+   minimum the runtime needs, the `SHARD` Durable Object binding and its
+   SQLite migration tag, and the shape of every declared binding. It does
+   **not** check `compatibility_flags`: `nodejs_compat` is what every
+   template ships and what dependencies reaching for `node:` builtins need,
+   but no Lunora package requires it, so nothing fails when it is missing.
 3. **Schema-drift gate** — blocks if the committed baseline
    (`lunora/.lunora-schema.json`) drifted with a breaking change and no
    accompanying migration. The baseline is re-blessed only after the deploy
@@ -40,9 +47,23 @@ D1 database, R2 buckets, and secrets — so the work is mostly making
    images).
 
 Useful flags: `--env <name>` (Cloudflare environment), `--migrate` (run pending
-data migrations against the live worker after deploy, with `--migrate-token` /
-`--migrate-url`), `--allow-schema-drift` (override the gate — use sparingly), and
-`--update-schema-baseline` (re-bless the baseline with the current shape).
+data migrations against the live worker after deploy), `--allow-schema-drift`
+(override the gate — use sparingly), and `--update-schema-baseline` (re-bless
+the baseline with the current shape).
+
+`--migrate` has three hard requirements, checked **before** `wrangler deploy`,
+so missing one aborts the whole deploy rather than skipping the migration:
+
+- `--migrate-yes` — confirms running production data migrations. Always
+  required; there is no environment variable for it.
+- `--migrate-url <https://…>` — the deploy target URL is only known after
+  wrangler runs, so it cannot be inferred. Omit it only when the checkout is
+  linked (`lunora link`) for this same `--env`.
+- an admin token — `--migrate-token` or `LUNORA_ADMIN_TOKEN`.
+
+```bash
+lunora deploy --migrate --migrate-yes --migrate-url https://app.example.com
+```
 
 ## Preflight: `lunora doctor`
 
@@ -119,10 +140,19 @@ before the first request hits production.
 - **Production:** `lunora deploy`. Separate D1 database / R2 buckets / secrets
   from dev. Never point a dev worker at prod resources.
 
-For `.global()` table DDL, generate and commit SQL migrations with `lunora
-migrate generate` before deploying; `@lunora/d1`'s runner applies them. For data
-backfills, deploy first, then `lunora deploy --migrate` (or `lunora migrate up
---prod`). See `lunora-migration-helper`.
+For `.global()` table DDL, `lunora migrate generate` emits a reviewable SQL
+file — but **no command applies it**, `lunora deploy` included. What actually
+provisions a global table is the runtime, from the schema rather than from the
+file: on first use it runs `CREATE TABLE IF NOT EXISTS` plus additive
+`ADD COLUMN`, so additive changes land whether or not the file exists.
+Anything the generator cannot express — a backfilling `UPDATE`, a rename
+written as add/copy/drop, an index the schema does not declare — must be
+applied by hand:
+`wrangler d1 execute <DB> --remote --file=lunora/migrations/<file>.sql`. The
+file is multi-statement, so it is not a `@lunora/d1` `Migration` either.
+For data backfills, deploy first, then `lunora deploy --migrate --migrate-yes
+--migrate-url <url>` (or `lunora migrate up --prod`). See
+`lunora-migration-helper`.
 
 ## Common Pitfalls
 
@@ -147,4 +177,5 @@ secret put` for every prod secret.
 - [ ] DO + container `class_name`s exported by the worker entry.
 - [ ] Production secrets set via `wrangler secret put`.
 - [ ] Schema changes migrated; the drift gate is green (no `--allow-schema-drift`).
-- [ ] `lunora deploy` succeeded; `--migrate` run if data backfills were pending.
+- [ ] `lunora deploy` succeeded; `--migrate --migrate-yes --migrate-url <url>` run
+      if data backfills were pending.

package/skills/lunora-functions/SKILL.md

@@ -70,15 +70,22 @@ Each function declares its inputs with `.input(...)` (a `v.*` map) and ends with
 terminal `.query` / `.mutation` / `.action` handler. Export them as named
 consts from `lunora/*.ts`; codegen surfaces them as `api.<file>.<name>`.
 
-| Kind       | Reads `ctx.db`                    | Writes `ctx.db` | Side effects / `fetch` | Reactive |
-| ---------- | --------------------------------- | --------------- | ---------------------- | -------- |
-| `query`    | yes                               | no              | no                     | yes      |
-| `mutation` | yes                               | yes             | no                     | —        |
-| `action`   | no (use `runQuery`/`runMutation`) | no              | yes                    | —        |
+| Kind       | Reads `ctx.db` | Writes `ctx.db`     | Side effects / `fetch` | Reactive |
+| ---------- | -------------- | ------------------- | ---------------------- | -------- |
+| `query`    | yes            | no                  | no                     | yes      |
+| `mutation` | yes            | yes, transactional  | no                     | —        |
+| `action`   | yes            | yes, autocommitting | yes                    | —        |
+
+The builders are **generated**, not imported from `@lunora/server`: codegen binds
+them to your schema, so `ctx.db`, `v.id("channels")`, and index names are all
+typed. `@lunora/server` exports the schema/HTTP/validator surface and
+`LunoraError`, never `query` / `mutation` / `action`.
 
 ```ts
-import type { Id } from "@lunora/server";
-import { action, LunoraError, mutation, query, v } from "@lunora/server";
+import { LunoraError } from "lunorash/server";
+
+import type { Id } from "#lunora/_generated/server.js";
+import { action, mutation, query, v } from "#lunora/_generated/server.js";
 
 // `api` / `internal` come from codegen:
 // import { api, internal } from "./_generated/api";
@@ -112,8 +119,12 @@ export const notifySlack = action.input({ messageId: v.id("messages") }).action(
 
 - **Pick the right kind.** Reactive read → `query`. Transactional write →
   `mutation`. External I/O (`fetch`, third-party SDKs, calling other functions)
-  → `action`. An action has no `ctx.db`; it reaches data via `ctx.runQuery` /
-  `ctx.runMutation`.
+  → `action`. An action has a `ctx.db`, but its own writes are not
+  transactional: each autocommits as it runs, so a later throw rolls nothing
+  back. Reach data through `ctx.runQuery` / `ctx.runMutation` — a mutation
+  called that way runs in the same all-or-nothing transaction a top-level one
+  gets, so put every write that has to land together in ONE mutation rather
+  than sequencing several from the action.
 - **`internal*` variants** (`internalQuery`, `internalMutation`,
   `internalAction`) are not exposed to clients — use them for server-only logic
   called from actions, crons, or other functions.
@@ -148,26 +159,118 @@ await ctx.db.delete(id);
 scans the whole table — `@lunora/advisor` flags it as `filter-without-index`.
 Declare the index and constrain with `.withIndex`.
 
+### Following foreign keys: `ctx.db.related`
+
+Every `v.id("table")` column is an edge in a graph your schema already declares.
+`ctx.db.related` walks it, so "this customer's tickets, and those tickets'
+messages" is one call instead of a hand-written chain of `withIndex` lookups.
+
+```ts
+const { continueCursor, isDone, nodes } = await ctx.db.related(
+    { table: "customers", id: customerId }, // or a row you already loaded
+    { depth: 2, direction: "in", edges: ["tickets.customerId", "messages.ticketId"], limit: 50 },
+);
+
+for (const node of nodes) {
+    node.table; // "messages"
+    node.document; // the row itself
+    node.depth; // 2
+    node.score; // 0.5 — 1 at depth 1, halving per hop
+    node.path; // ["tickets.customerId", "messages.ticketId"]
+    node.pathIds; // ids along the way, start included
+}
+```
+
+- **Edge names are `"<table>.<column>"`.** `edges` restricts the walk to the
+  named ones; a name the schema does not declare is **refused**, not ignored.
+- **`direction`** — `"out"` follows the ids this row holds, `"in"` the rows that
+  point at it, `"both"` (the default) does both.
+- **`depth`** defaults to `1`, max `4`. **`limit`** defaults to `50`, max `200`.
+  Both caps **refuse rather than clamp**, so do not probe for the ceiling.
+- **Only a column is an edge**: a bare `v.id(...)`, `v.optional(v.id(...))` or
+  `v.array(v.id(...))`. An id nested in a `v.object` / `v.union` / `v.record` is
+  not. An array FK is followed **outward only**.
+- **It is an ordinary read** — RLS, column masks, soft delete, `.global()`
+  routing and reactivity all apply, because every hop goes back through
+  `ctx.db`. Under a `.rls("required")` schema each hop gets exactly the verdict a
+  direct read of that table would, so declare a read policy for every table the
+  walk can reach — or narrow it with `edges`.
+- Index the foreign keys. Each inward hop is a `WHERE fk IN (…)` read, and
+  unindexed it scans — see the `lunora-performance-audit` skill for the cost
+  model and the traversal caps.
+
 ## Other `ctx` capabilities
 
-`ctx.auth` (the resolved session: `ctx.auth.userId`), `ctx.scheduler`
-(`runAfter` / `runAt` for deferred work), `ctx.storage` (R2), `ctx.vectors`
-(Vectorize), and — when their packages are wired — `ctx.ai` and `ctx.containers`.
+Always available:
+
+- `ctx.auth` — the resolved session (`ctx.auth.userId`).
+- `ctx.scheduler` — `runAfter` / `runAt` for deferred work.
+- `ctx.secrets` — Cloudflare Secrets Store.
+- `ctx.span` / `ctx.trace` — the current span and a scoped tracing helper for
+  wide events.
+
+Added by their package when wired. **A dependency in `package.json` is not
+enough** — codegen scans the `lunora/` source set and flips a capability on only
+when a file there imports the `@lunora/*` package or reads its `ctx.*` helper.
+So write the call first, then run `lunora codegen` to surface the typed context:
+
+| `ctx.*`                                                                                   | Package                       |
+| ----------------------------------------------------------------------------------------- | ----------------------------- |
+| `ctx.storage`                                                                             | `@lunora/storage` (R2)        |
+| `ctx.ai`                                                                                  | `@lunora/ai` (Workers AI)     |
+| `ctx.flags`                                                                               | `@lunora/flags` (OpenFeature) |
+| `ctx.queues.<name>`                                                                       | `@lunora/queue`               |
+| `ctx.workflows` / `ctx.runStep`                                                           | `@lunora/workflow`            |
+| `ctx.containers`                                                                          | `@lunora/container`           |
+| `ctx.browser` (action-only)                                                               | `@lunora/browser`             |
+| `ctx.sql` (action-only)                                                                   | `@lunora/hyperdrive`          |
+| `ctx.kv` / `ctx.images` / `ctx.analytics` / `ctx.pipelines` / `ctx.vectors` / `ctx.r2sql` | `@lunora/bindings` subpaths   |
+
+Two exceptions to the usage scan, and one extra requirement:
+
+- **`ctx.flags` gates on a declaration file**, not on usage — codegen wires it
+  only when `lunora/flags.ts` exists (`vis generate lunora-flags` creates it).
+  `ctx.notify` / `ctx.push` work the same way via `lunora/notify.ts`.
+- **`ctx.sql` also needs the real resource.** Codegen types the field, but the
+  connection needs a `HYPERDRIVE` binding (`wrangler hyperdrive create`) and an
+  explicit `createHyperdrive(ctx.env.HYPERDRIVE)` + driver adapter in the
+  action — see `lunora-setup-hyperdrive`. Bindings codegen can provision on its
+  own (e.g. `BROWSER` for `ctx.browser`) need no manual wrangler step.
+
+`ctx.browser` and `ctx.sql` are **action-only** by design. They are external,
+non-deterministic I/O: a query is re-run on every subscription re-evaluation, so
+a non-deterministic read makes reactivity wrong, and a mutation's writes are
+transactional — a rollback cannot un-send a network call.
 
 ## HTTP endpoints
 
 For webhooks or non-RPC HTTP, use `httpRouter` / `httpRoute` + `httpAction`:
 
+`httpRouter()` takes **no arguments** — it returns a [Hono](https://hono.dev)
+app you mount routes on, and you export the app. Passing it a routes object is a
+type error (`Expected 0 arguments`), and from untyped code the routes simply
+never mount.
+
 ```ts
+// lunora/http.ts
 import { httpAction, httpRouter } from "@lunora/server";
 
-export default httpRouter({
-    "/webhooks/stripe": httpAction(async (ctx, request) => {
+import { internal } from "./_generated/api";
+
+const app = httpRouter();
+
+app.post(
+    "/webhooks/stripe",
+    httpAction(async (ctx, request) => {
         const event = await request.json();
+
         await ctx.runMutation(internal.billing.record, { event });
+
         return new Response("ok");
     }),
-});
+);
+
+export default app;
 ```
 
 ## Checklist
@@ -179,4 +282,6 @@ export default httpRouter({
       `action` (side effects via `runQuery`/`runMutation`).
 - [ ] Server-only logic uses `internal*`; expected failures throw `LunoraError`.
 - [ ] `ctx.db` writes only inside mutations; ids typed with `Id<"table">`.
+- [ ] Any `ctx.db.related` walk is narrowed with `edges` / `direction`, and its
+      foreign keys are indexed.
 - [ ] Ran `lunora codegen`; typecheck is clean.

package/skills/lunora-migration-helper/SKILL.md

@@ -2,7 +2,8 @@
 name: lunora-migration-helper
 description: Plans Lunora schema and data migrations with widen-migrate-narrow. Use for
     breaking schema changes, backfills, table reshaping, online data migrations
-    (`defineMigration` + `lunora migrate up`), the `.global()` D1 SQL flow, and the
+    (`defineMigration` + `lunora migrate up`), the `.global()` D1 / Hyperdrive
+    structural flows, and the
     pre-deploy schema-drift gate.
 ---
 
@@ -15,7 +16,7 @@ Safely change a Lunora schema and migrate data when making breaking changes.
 - Adding required fields to existing tables.
 - Changing field types or structure.
 - Splitting/merging tables, renaming/removing fields.
-- Reshaping `.global()` (D1-backed) tables.
+- Reshaping `.global()` tables (D1- or Hyperdrive-backed).
 
 ## When Not to Use
 
@@ -23,21 +24,35 @@ Safely change a Lunora schema and migrate data when making breaking changes.
 - Adding **optional** fields that need no backfill.
 - Adding new tables or indexes with no correctness concern.
 
-## Two Storage Layers — Know Which You Are Migrating
+## Storage Layers — Know Which You Are Migrating
 
-Lunora tables live in one of two backends, and they migrate differently:
+Lunora tables live in one of three backends, and they migrate differently:
 
 - **ShardDO SQLite (default `root`, and `.shardBy(key)` tables).** State lives in
   the per-app / per-shard Durable Object. Data is reshaped with **online data
   migrations** — `defineMigration` declarations run by `lunora migrate up`,
   resumable per shard.
-- **`.global()` tables (D1).** Replicated to D1 for cross-region reads. Their
-  structural DDL gets versioned **SQL migrations** via `lunora migrate generate`,
-  applied by `@lunora/d1`'s runner at deploy time.
-
-A breaking change to a `.global()` table needs a generated SQL migration; a data
-backfill (either layer) is an online `defineMigration`. Both follow the same
-**widen → migrate → narrow** discipline.
+- **`.global()` on D1 (the default global backend).** Replicated to D1 for
+  cross-region reads. Structural DDL gets versioned **SQL migrations** via
+  `lunora migrate generate`, applied by `@lunora/d1`'s runner at deploy time.
+- **`.global({ backend: "hyperdrive" })` on Postgres/MySQL.** The same reactive
+  `.global()` contract served over Cloudflare Hyperdrive. Structural DDL works
+  differently here: tables **auto-provision on first use** — the runtime applies
+  the DDL through the dialect — so there is no `lunora migrate generate` step
+  and no versioned SQL file to commit. See `lunora-setup-hyperdrive-global`.
+
+So: a breaking structural change to a **D1-backed** `.global()` table needs a
+generated SQL migration; the Hyperdrive-backed equivalent provisions itself. A
+data backfill (any layer) is always an online `defineMigration`. All three
+follow the same **widen → migrate → narrow** discipline — check the table's
+backend before assuming which structural path applies.
+
+> **Moving an existing dataset between global backends.** To move a `.global()`
+> dataset from D1 onto Hyperdrive, use
+> `lunora migrate d1-to-hyperdrive --from-url <d1-worker> --to-url <hd-worker>`
+> (`--tables` scopes it; `--out` keeps the intermediate NDJSON dump). This is a
+> backend move, not a schema change — the widen → migrate → narrow discipline
+> below still governs any reshaping you do on either side of it.
 
 ## Key Principle: Widen, Migrate, Narrow
 
@@ -115,6 +130,40 @@ export default defineMigration({
 The transform must preserve row identity — the runner always keeps the original
 `_id` / `_creationTime`, so do not change them.
 
+### Reading another table
+
+The transform's second argument is a **shard-scoped reader** (`ctx.db` with
+`get` / `findFirst` / `findMany` / `count`), so the common backfill — read the
+parent, copy a field down onto its children — is expressible. It may be `async`.
+
+```ts
+up: async (doc, ctx) => {
+    const thread = await ctx.db.get(String(doc.threadId), "threads");
+
+    return thread ? { ...doc, userId: thread.userId } : undefined;
+},
+```
+
+It is a reader, not a writer: the runner accounts for exactly one rewrite per
+row read, and a transform writing directly would make that count describe
+something other than what happened. To touch a second table, run a second
+migration over that table.
+
+### A shard key cannot be backfilled by a migration
+
+If the field you are backfilling **is** the table's `.shardBy()` key, this is the
+wrong tool, and no amount of reader access fixes it:
+
+- a row whose shard key is unset does not belong to any shard, so a shard-scoped
+  query will never enumerate it; and
+- writing the key would have to **move the row to a different Durable Object**,
+  which a per-shard runner has no way to do.
+
+Re-keying is an export → transform → import (`lunora export`, rewrite the NDJSON,
+`lunora import` — ids are preserved, so foreign keys survive), not a migration.
+So the rule elsewhere in this skill that a data backfill is always an online
+`defineMigration` has this one exception.
+
 ### Run it
 
 ```bash
@@ -129,7 +178,10 @@ lunora migrate down backfill-display-name      # revert (if `down` defined)
 Useful flags: `--batch-size <n>`, `--steps <n>` (cap batches this run), and
 `--prod --url <worker> --yes` to target production (with `LUNORA_ADMIN_TOKEN`).
 
-## `.global()` (D1) Structural Migration Flow
+## `.global()` on D1 — Structural Migration Flow
+
+This flow is **D1-specific**. Hyperdrive-backed globals auto-provision their DDL
+at runtime and skip it entirely.
 
 ```bash
 # 1. Edit lunora/schema.ts (widen: add the optional new field to the .global() table).
@@ -146,8 +198,8 @@ lunora deploy
 ```
 
 `lunora migrate generate` only considers `.global()` tables (root/sharded tables
-are not D1-backed). Run it after each schema edit in the widen and narrow steps;
-backfill data with an online migration between them.
+live in ShardDO SQLite, not D1). Run it after each schema edit in the widen and
+narrow steps; backfill data with an online migration between them.
 
 ## The Schema-Drift Gate
 
@@ -176,9 +228,10 @@ add the migration — not to bypass it.
    transform before it touches real rows.
 5. **Deleting a field prematurely.** Deprecate with `v.optional` + a comment;
    delete only once nothing references it.
-6. **Migrating the wrong layer.** A `.global()` structural change needs `lunora
-migrate generate` (SQL); a data backfill needs a `defineMigration`. Check the
-   table's `.global()` / `.shardBy()` modifier first.
+6. **Migrating the wrong layer.** A D1-backed `.global()` structural change needs
+   `lunora migrate generate` (SQL); a Hyperdrive-backed one auto-provisions; a
+   data backfill needs a `defineMigration`. Check the table's `.global()` /
+   `.shardBy()` modifier — and, for `.global()`, its `backend` — first.
 
 ## Checklist
 
@@ -186,9 +239,9 @@ migrate generate` (SQL); a data backfill needs a `defineMigration`. Check the
 - [ ] Widened the schema to accept both shapes; `lunora codegen` clean.
 - [ ] Updated reads to handle both shapes; started writing the new shape.
 - [ ] Deployed the widened schema.
-- [ ] Authored a `defineMigration`; previewed with `lunora migrate up --dry-run`.
-- [ ] Ran `lunora migrate up`; `lunora migrate generate` + deploy for `.global()`
-      structural changes.
-- [ ] Verified completion with `lunora migrate status`.
+- [ ] Authored a `defineMigration`; previewed with `lunora migrate up <id> --dry-run`.
+- [ ] Ran `lunora migrate up <id>`; `lunora migrate generate` + deploy for
+      `.global()` structural changes.
+- [ ] Verified completion with `lunora migrate status <id>`.
 - [ ] Narrowed the schema (required / drop old field); removed both-shapes code.
 - [ ] Deployed the final schema; schema-drift gate passed.

package/skills/lunora-performance-audit/SKILL.md

@@ -2,8 +2,8 @@
 name: lunora-performance-audit
 description: Diagnoses and fixes Lunora performance problems — full-table scans, missing
     indexes, OCC write conflicts, oversized subscriptions, and sharding/`.global()`
-    scaling. Use when queries are slow, mutations conflict, or `@lunora/advisor`
-    flags a table.
+    scaling. Use when queries are slow, mutations conflict, `lunora insights`
+    reports a hot-spot, or `@lunora/advisor` flags a table.
 ---
 
 # Lunora Performance Audit
@@ -14,7 +14,7 @@ apply it across sibling functions consistently.
 ## When to Use
 
 - Queries feel slow or read far more rows than they return.
-- Mutations retry or conflict under load (OCC).
+- Mutations conflict (409 `CONFLICT`) under load (OCC).
 - Subscriptions fan out updates too broadly or re-run too often.
 - The Lunora Studio **Advisors** tab or `@lunora/advisor` flags a table.
 
@@ -34,12 +34,35 @@ apply it across sibling functions consistently.
 
 ## Signal Gathering
 
-Start with the static advisors — they need no traffic:
+### Runtime signal: `lunora insights`
+
+When the worker is running and has served traffic, start here — it reports the
+measured problem, not a suspected one:
+
+```bash
+lunora insights                      # against the local dev worker
+lunora insights --shard channel:demo # scope to one shard
+lunora insights --limit 25 --format json  # machine-readable, more rows
+lunora insights --prod --url https://app.example.com --token $LUNORA_ADMIN_TOKEN
+```
+
+It ranks per-function **write-conflict hot-spots** (OCC contention — the
+sharding signal), **error rates**, and **latency outliers**. A function at the
+top of the write-conflict list is the direct input to the OCC section below; a
+latency outlier usually resolves to the read-amplification section.
+
+The Studio **Issues** panel and `lunora logs` cover the error side in more
+detail once `insights` tells you where to look.
+
+### Static signal: the advisors
+
+These need no traffic, so they also work on a cold codebase:
 
 - **Lunora Studio → Advisors tab** surfaces `@lunora/advisor` findings live in
   dev.
-- `@lunora/advisor` runs static lints over `defineSchema` + discovered query
-  reads / insert writes. Relevant performance/schema rules:
+- `@lunora/advisor` runs ~90 static lints over `defineSchema` + discovered query
+  reads / insert writes (plus a few runtime lints). The performance/schema rules
+  most relevant here:
     - `filter-without-index` — a query filters a table with no covering index.
     - `unindexed-foreign-key` — a relation/FK column has no index.
     - `duplicate-index` / `empty-index` — wasted or malformed indexes.
@@ -73,11 +96,49 @@ const mine = await ctx.db
 Index columns are ordered: put equality columns first, then the range/sort
 column. Fix every sibling query on the table the same way.
 
+## Problem Class: Relation Traversal Cost
+
+**Symptom:** a query calling `ctx.db.related` is slow, or one page of it reads
+far more rows than it returns.
+
+A traversal is not one read. It is one batched `findMany` **per edge, per hop**,
+and the frontier grows multiplicatively — which is why every option is bounded,
+and why the bounds **refuse rather than clamp**:
+
+| Option        | Default | Cap      | What the cap is protecting                                                   |
+| ------------- | ------- | -------- | ---------------------------------------------------------------------------- |
+| `depth`       | `1`     | `4`      | Past 4 hops a real schema is bounded by request time, not by `limit`.        |
+| `limit`       | `50`    | `200`    | Nodes returned in one page.                                                  |
+| cursor offset | `0`     | `10 000` | The offset is re-walk work, not a skip: each hop reads `N + limit + 1` rows. |
+
+A caller asking for `depth: 9` gets a `BAD_REQUEST`, not a silent depth 4 — so a
+traversal that throws is a mis-sized request, not a bug to route around.
+
+**Fixes, in order of preference:**
+
+1. **Narrow with `edges`.** Name only the `"<table>.<column>"` edges the feature
+   needs. Following every declared foreign key is the usual reason a walk is
+   wide — one unrelated `v.id(...)` column can double the frontier per hop.
+2. **Narrow with `direction`.** `"in"` or `"out"` instead of the default
+   `"both"` halves the edges expanded at each hop.
+3. **Drop `depth` before raising `limit`.** Each hop multiplies; a page is
+   linear.
+4. **Index the foreign keys.** Every inward hop is a `WHERE fk IN (…)` read, so
+   an unindexed FK makes each hop a scan. `@lunora/advisor` flags it as
+   `unindexed-foreign-key`.
+5. **Stop deep-paging.** An offset past 10 000 is refused outright. That is the
+   signal the traversal is the wrong tool for the job — narrow the walk instead
+   of paging through it.
+
 ## Problem Class: Write Conflicts (OCC)
 
-**Symptom:** mutations on hot rows retry or fail under concurrency. ShardDO uses
-optimistic concurrency control — concurrent writes to the same DO that touch
-overlapping state conflict and retry.
+**Symptom:** mutations on hot rows fail under concurrency, or the function tops
+the write-conflict section of `lunora insights`. ShardDO uses optimistic
+concurrency control — concurrent writes to the same DO that touch overlapping
+state conflict. There is **no server-side retry loop**: the loser throws
+`ConflictError` (code `CONFLICT`, HTTP 409) and the caller decides, so a client
+that never handles it (`isConflictError` from `@lunora/client`) just surfaces
+409s to the user.
 
 **Fixes, in order of preference:**
 
@@ -115,6 +176,11 @@ cross-region reads (with read-your-writes via the Sessions API). Reserve it for
 read-mostly tables — `.global()` adds the D1 migration flow (see the
 `lunora-migration-helper` skill) and write-path cost.
 
+If the dataset outgrows D1, `.global({ backend: "hyperdrive" })` serves the same
+reactive `.global()` contract from Postgres/MySQL over Cloudflare Hyperdrive —
+see the `lunora-setup-hyperdrive-global` skill (and `lunora migrate
+d1-to-hyperdrive` to move an existing dataset).
+
 ### `.shardBy(key)` vs `.global()` — choose one per table
 
 - `.shardBy(key)`: partitions a table across Durable Objects by key — scales
@@ -135,8 +201,11 @@ read-mostly tables — `.global()` adds the D1 migration flow (see the
 ## Checklist
 
 - [ ] Scoped one concrete flow; traced every `ctx.db` read/write.
+- [ ] Ran `lunora insights` (if the worker has traffic) for the measured signal.
 - [ ] Checked the Studio Advisors tab / `@lunora/advisor` findings.
 - [ ] Read amplification: replaced `.filter()` with an indexed `.withIndex()`.
+- [ ] Relation traversals: narrowed with `edges` / `direction` before `depth`;
+      foreign keys indexed.
 - [ ] Write conflicts: narrowed writes and/or partitioned with `.shardBy(key)`.
 - [ ] Subscription cost: scoped query args so live queries depend on few rows.
 - [ ] Cross-region: applied `.global()` only to read-mostly tables.