gemi 0.59.0 → 0.60.0

package/skills/gemi-react-best-practices/rules/orm-include-not-n-plus-one.md

@@ -0,0 +1,56 @@
+---
+title: One include Tree Beats a Loop of Queries
+impact: HIGH
+impactDescription: N+1 round trips to 1
+tags: orm, n-plus-one, include, relations
+---
+
+## One include Tree Beats a Loop of Queries
+
+On Postgres, gemi's default **lateral** strategy folds an entire `include` /
+nested-`select` tree into the root statement using `LATERAL` joins and `json_agg` —
+one round trip for the whole tree. A loop that queries per row gets none of that.
+
+**Incorrect (1 + N round trips):**
+
+```ts
+const products = await Product.findMany({ where: { organizationId } });
+const withMedia = await Promise.all(
+  products.map(async (product) => ({
+    ...product,
+    media: await Media.findMany({ where: { productId: product.id } }),
+  })),
+);
+```
+
+**Correct (one statement):**
+
+```ts
+const products = await Product.findMany({
+  where: { organizationId },
+  include: { media: true },
+});
+```
+
+**Know when the lateral strategy declines**, because those nodes fall back to
+batched (one query per include node) and a deep tree can quietly become several
+round trips. It declines for: implicit many-to-many relations, self-relations, nodes
+with `_count`, nodes ordered by a relation, and **any descendant of a declined
+node**. If a read is hot and its tree contains one of these, consider restructuring
+the tree rather than accepting the fallback.
+
+**`take` inside a to-many is per-parent, not total** — `take: 10` on an included
+relation means ten per parent. That requires the lateral strategy; batched mode
+refuses it.
+
+**Index the foreign keys.** Relation filters, counts and orderings compile to
+correlated subqueries that run once per parent row; without an index on the child's
+FK each run scans the table.
+
+Override per call when you need the other strategy:
+
+```ts
+await User.findMany({ include: { accounts: true } }, { strategy: "batched" });
+```
+
+Reference: <https://nstfkc.github.io/gemi/orm.md>

package/skills/gemi-react-best-practices/rules/orm-paginate-helper.md

@@ -0,0 +1,69 @@
+---
+title: Use paginate() From gemi/orm, and Know Its Ceiling
+impact: MEDIUM
+impactDescription: bounded reads, no unbounded scans
+tags: orm, pagination, validation
+---
+
+## Use paginate() From gemi/orm, and Know Its Ceiling
+
+An unbounded list read is a slow query waiting for the row count to grow. `paginate`
+validates and clamps request input in one place rather than each controller
+hand-rolling `parseInt` and a guard.
+
+```ts
+import { paginate } from "gemi/orm";
+
+const { take, skip } = paginate({
+  page: req.search.get("page"),
+  perPage: req.search.get("perPage"),
+});
+```
+
+Its behaviour, which you must design around:
+
+- Absent, blank or non-finite values are treated as absent.
+- `perPage` **defaults to 25 and is capped at 100**.
+- `page` clamps to a minimum of 1.
+
+**The 100-row cap is the trap.** A caller that asks for `limit=200` silently gets
+100 — half its data, no error. If a surface genuinely needs more, it must paginate
+rather than raise the number.
+
+**Incorrect (unbounded, and it will not stay fast):**
+
+```ts
+const products = await Product.findMany({ where: { organizationId } });
+```
+
+**Incorrect (hand-rolled, and unvalidated `take` is refused rather than coerced):**
+
+```ts
+const take = Number(req.search.get("limit"));
+const products = await Product.findMany({ where, take });
+```
+
+**Correct:**
+
+```ts
+const { take, skip } = paginate({
+  page: req.search.get("page"),
+  perPage: req.search.get("perPage"),
+});
+const products = await Product.findMany({
+  where: { organizationId },
+  take,
+  skip,
+  orderBy: { createdAt: "desc" },
+});
+```
+
+Two related ORM behaviours: `take` and `skip` must be integers and are **refused,
+not coerced** — a negative `take` means "the last N rows". And an `update` with
+`data: {}` reads rather than writes, returning the row unchanged.
+
+A deliberately unpaginated read is a decision worth a comment saying why (see
+`CustomerProductsV2Controller`).
+
+Reference: <https://nstfkc.github.io/gemi/orm.md>
+`app/http/controllers/AdminMediaController.ts`

package/skills/gemi-react-best-practices/rules/orm-plain-rows-by-default.md

@@ -0,0 +1,55 @@
+---
+title: Plain Rows Are the Default — Opt Into Tracking Deliberately
+impact: MEDIUM
+impactDescription: ~100% read overhead when tracking is on
+tags: orm, rows, tracking, performance
+---
+
+## Plain Rows Are the Default — Opt Into Tracking Deliberately
+
+Queries return plain objects. No proxying, no hydration, no identity map — so a row
+can be spread, serialized, or handed to a view freely, and `select` narrows the
+**type** as well as the columns. This costs nothing, which is why it is the default.
+
+Two opt-ins exist above it, and both have a price:
+
+- **`{ track: true }`** enables `Model.save(row)` differential updates — only changed
+  columns are written, and an unchanged row produces no SQL at all. It costs roughly
+  **100% overhead on a 1,000-row read** (WeakMap insertion plus snapshot cloning), so
+  it does not belong on a list read.
+- **`Model.wrap(row)`** adds model methods and getters. It **requires a complete
+  row** — a partial `select` is a compile error — and tracks automatically.
+
+**Incorrect (tracking a list read that is only being serialized):**
+
+```ts
+const products = await Product.findMany(
+  { where: { organizationId } },
+  { track: true },        // pure overhead; nothing here is saved
+);
+return { products };
+```
+
+**Correct (plain for reads; track the single row you intend to mutate):**
+
+```ts
+const products = await Product.findMany({
+  where: { organizationId },
+  select: { publicId: true, name: true },
+});
+
+const product = await Product.findUnique({ where: { id } }, { track: true });
+product.name = nextName;
+await Product.save(product);   // writes only `name`
+```
+
+**Provenance is keyed on object identity via a WeakMap**, so spreading, cloning or
+serializing loses it — `Model.save({ ...product })` throws. It also cannot assign to
+a column the query did not fetch, and a tracked row remembers which connection
+produced it, so `save()` returns to the right pool.
+
+**There is no identity map and no lazy loading.** Two reads of the same row return
+two distinct objects that do not synchronize. Coordinate saves inside a
+`Model.transaction`, sequentially (`orm-transaction-sequential`).
+
+Reference: <https://nstfkc.github.io/gemi/orm-rows-and-entities.md>

package/skills/gemi-react-best-practices/rules/orm-select-narrow.md

@@ -0,0 +1,58 @@
+---
+title: Select the Columns the Response Actually Serializes
+impact: MEDIUM
+impactDescription: less data over two wires
+tags: orm, select, payload, serialization
+---
+
+## Select the Columns the Response Actually Serializes
+
+Every unselected column crosses two wires: database → server, then server → browser
+in the SSR payload or the API response. Narrowing at the query removes both, and
+prevents internal columns from leaking into a payload anyone can read.
+
+This is the query-side half of `payload-minimal-view-props`.
+
+**Incorrect (loads every column of every row, then renders three fields):**
+
+```ts
+const products = await Product.findMany({
+  where: { organizationId },
+  include: { media: true },
+});
+return products.map((p) => ({ id: p.publicId, name: p.name, cover: p.media[0] }));
+```
+
+**Correct (narrow the tree at the query, including inside the relation):**
+
+```ts
+const products = await Product.findMany({
+  where: { organizationId },
+  select: {
+    publicId: true,
+    name: true,
+    media: { select: { url: true }, take: 1 },
+  },
+});
+```
+
+Note `take: 1` inside the relation is **per parent** (`orm-include-not-n-plus-one`),
+which is what you want for a cover image.
+
+**Prefer `count` / `aggregate` over loading rows to count them:**
+
+```ts
+// Incorrect
+const orders = await Order.findMany({ where: { status: "pending" } });
+const pending = orders.length;
+
+// Correct
+const pending = await Order.count({ where: { status: "pending" } });
+```
+
+But note the counterpart from the ORM docs: a `_count` node makes the lateral
+strategy decline for that node and its descendants, and an unindexed `_count`
+compiles to a correlated subquery per parent row. A separate `count` query is often
+the cheaper shape for a hot read.
+
+Reference: <https://nstfkc.github.io/gemi/orm.md>

package/skills/gemi-react-best-practices/rules/orm-transaction-no-io.md

@@ -0,0 +1,54 @@
+---
+title: Keep Network I/O Out of a Transaction Callback
+impact: HIGH
+impactDescription: frees a pooled connection held for a network round-trip
+tags: orm, transactions, pooling, io
+---
+
+## Keep Network I/O Out of a Transaction Callback
+
+The reserved connection is held for the **entire** duration of the callback. An HTTP
+call, an upload, a queue push or an LLM request inside a transaction holds a pooled
+connection for as long as that request takes — and under load, unrelated queries
+elsewhere in the app queue behind it. The pools here are small and budgeted
+(your database config's pool sizes are asserted against a per-instance
+budget at boot), so one slow callback is felt app-wide.
+
+Do the I/O first, or after. Keep the transaction to the writes that must be atomic.
+
+**Incorrect (a connection held across a third-party API call):**
+
+```ts
+await Order.transaction(async () => {
+  const order = await Order.create({ data });
+  const charge = await stripe.charges.create({ amount });   // network
+  await Storage.put(`receipts/${order.publicId}.pdf`, pdf); // network
+  await Order.update({ where: { id: order.id }, data: { chargeId: charge.id } });
+});
+```
+
+**Correct (I/O outside; the transaction is the atomic write only):**
+
+```ts
+const charge = await stripe.charges.create({ amount });
+
+const order = await Order.transaction(async () => {
+  const created = await Order.create({ data });
+  await Order.update({
+    where: { id: created.id },
+    data: { chargeId: charge.id },
+  });
+  return created;
+});
+
+await Storage.put(`receipts/${order.publicId}.pdf`, pdf);
+```
+
+**Deferred work belongs in a Job**, not in the callback. `Job.dispatch(...)` from
+`app/jobs` enqueues and returns `void`, so the request path never waits on it.
+
+One caveat from `CLAUDE.md`: the queue runs in-process, and the cron
+scheduler does not start under `gemi run`. A **command** that dispatches a Job may
+exit before it runs — do that work inline instead.
+
+Reference: <https://nstfkc.github.io/gemi/orm.md>

package/skills/gemi-react-best-practices/rules/orm-transaction-sequential.md

@@ -0,0 +1,64 @@
+---
+title: Never Promise.all ORM Calls Inside a Transaction
+impact: HIGH
+impactDescription: prevents deadlock and lost writes
+tags: orm, transactions, concurrency, correctness
+---
+
+## Never Promise.all ORM Calls Inside a Transaction
+
+`Model.transaction(fn)` is **ambient** — it uses `AsyncLocalStorage`, so nothing
+takes a `tx` parameter and every ORM query in the async subtree joins the
+transaction automatically. That convenience has a hard constraint: the transaction
+holds **one reserved connection**, so concurrent queries inside the callback are not
+safe. Await them in sequence.
+
+This is the one place that overrides `payload-parallel-controller-work`: everywhere
+else independent awaits belong in a `Promise.all`, but inside a transaction callback
+sequential is correct.
+
+**Incorrect (concurrent queries on one reserved connection):**
+
+```ts
+await Order.transaction(async () => {
+  await Promise.all([
+    Order.update({ where: { id }, data: { status } }),
+    OrderItem.createMany({ data: items }),
+    AuditLog.create({ data: entry }),
+  ]);
+});
+```
+
+**Correct (sequential):**
+
+```ts
+await Order.transaction(async () => {
+  await Order.update({ where: { id }, data: { status } });
+  await OrderItem.createMany({ data: items });
+  await AuditLog.create({ data: entry });
+});
+```
+
+**A failed statement aborts the whole Postgres transaction block.** Catching an
+error and continuing loses everything after it. Wrap a fallible step in a nested
+transaction — nesting creates a savepoint, so an inner failure rolls back to the
+savepoint and leaves the outer transaction usable:
+
+```ts
+await Model.transaction(async () => {
+  try {
+    await Model.transaction(() => User.create({ data: { email } }));
+  } catch {
+    // recovery
+  }
+  await Audit.create({ data: entry }); // still safe
+});
+```
+
+**A transaction cannot span connections.** Crossing pools inside one raises
+`CrossConnectionTransactionError`, and it cannot span the ORM and Prisma clients
+either — they are separate pools. That is why the credit-settlement cluster stays
+entirely on Prisma; see `CLAUDE.md` → "The Prisma boundary is
+transactional, not directory-shaped."
+
+Reference: <https://nstfkc.github.io/gemi/orm.md>

package/skills/gemi-react-best-practices/rules/payload-dont-overprefetch.md

@@ -0,0 +1,54 @@
+---
+title: Do Not Prefetch What the Page May Never Read
+impact: HIGH
+impactDescription: keeps navigation payloads small
+tags: payload, prefetch, bandwidth, tradeoffs
+---
+
+## Do Not Prefetch What the Page May Never Read
+
+`Query.prefetch` is not free. Primed data is added to the payload of **every**
+navigation to that route — including navigations where the client already has the
+value cached. Priming a heavy collection to save one round-trip can cost more bytes
+than it saves, on every visit.
+
+Prefetch a read when the surface reads it **on mount, always**. Do not prefetch:
+
+- **Reads behind a closed popover, dialog, or tab.** Nobody has opened it. Gate them
+  by mounting (`bundle-mount-gate-heavy-panels`) or with `{ lazy: true }` +
+  `trigger()`.
+- **Heavy collections that revalidate well.** A large list benefits more from
+  cache-then-revalidate than from eager priming.
+- **Anything behind a feature flag or role gate** most visitors fail.
+
+**Incorrect (priming a catalogue for a picker most sessions never open):**
+
+```ts
+async view(req: HttpRequest) {
+  Query.prefetch("/app/:orgId/products/search", {
+    params: { orgId },
+    search: { q: null, limit: 25 },
+  });
+  return {};
+}
+```
+
+**Correct (the read lives inside the popover content, which Radix unmounts while closed):**
+
+```tsx
+function CatalogSearchPanel({ orgId }: { orgId: string }) {
+  const { data: products = [], loading } = useQuery(
+    "/app/:orgId/products/search",
+    { params: { orgId }, search: { q: debouncedQuery || null, limit } },
+    { suspense: false },
+  );
+  // …
+}
+
+<PopoverContent>
+  <CatalogSearchPanel orgId={orgId} />
+</PopoverContent>
+```
+
+For a route where the un-prefetched reads are deliberate, `Query.noPrefetch()`
+silences gemi's dev hint so the hints that remain stay meaningful.

package/skills/gemi-react-best-practices/rules/payload-instant-vs-prefetch.md

@@ -0,0 +1,58 @@
+---
+title: Query.instant Blocks, Query.prefetch Does Not
+impact: CRITICAL
+impactDescription: avoids blocking TTFB on a slow read
+tags: payload, prefetch, instant, ttfb
+---
+
+## Query.instant Blocks, Query.prefetch Does Not
+
+Both reuse an API handler server-side and prime the client cache. They differ in
+what they do to the response:
+
+- **`Query.instant(path, opts)`** — awaits the handler and blocks the response until
+  it resolves. The data ships in the initial payload. Use it when the view cannot
+  render anything meaningful without the data, or when the handler's return value is
+  needed to build the view's props.
+- **`Query.prefetch(path, opts)`** — starts the handler immediately and in parallel,
+  without blocking. Use it for everything else: the shell ships now, the data lands
+  behind it.
+
+The default choice is `prefetch`. Reach for `instant` only when you actually need
+the value on the server.
+
+**Incorrect (a slow, non-essential read holds up the whole document):**
+
+```ts
+async view(req: HttpRequest) {
+  const orgId = req.params.orgId;
+  // The credits widget lives in a corner of the nav. Blocking TTFB on it
+  // delays the entire page for every visitor.
+  const credits = await Query.instant("/app/:orgId/ai-credits", {
+    params: { orgId },
+  });
+  return { credits };
+}
+```
+
+**Correct (shell first, widget data behind it):**
+
+```ts
+view(req: HttpRequest) {
+  const orgId = req.params.orgId;
+  Query.prefetch("/app/:orgId/ai-credits", { params: { orgId } });
+  return {};
+}
+```
+
+**Also correct — `instant` when the server needs the value:**
+
+```ts
+async view(req: HttpRequest) {
+  const store = await Query.instant("/app/:orgId/store", { params });
+  Meta.title(`${store.name} — Acme`);
+  return { storeName: store.name };
+}
+```
+
+Reference: <https://nstfkc.github.io/gemi/data-fetching.md>

package/skills/gemi-react-best-practices/rules/payload-minimal-view-props.md

@@ -0,0 +1,51 @@
+---
+title: Return the Shape the View Renders, Not the Row You Loaded
+impact: HIGH
+impactDescription: smaller payload, no leaked columns
+tags: payload, serialization, ssr, security
+---
+
+## Return the Shape the View Renders, Not the Row You Loaded
+
+A controller's return value is serialized into the HTML payload and shipped to every
+visitor. Returning a whole model row inflates the document and can leak columns the
+UI never shows — internal ids, timestamps, provider tokens, soft-delete flags.
+
+It applies to `this.view(...)` handler returns and to API controller responses
+alike.
+
+**Incorrect (ships every column, including ones the UI never renders):**
+
+```ts
+async view(req: HttpRequest) {
+  const store = await Store.findUniqueOrThrow({
+    where: { publicId: req.params.storeId },
+  });
+  return { store };
+}
+```
+
+**Correct (select what the view renders):**
+
+```ts
+async view(req: HttpRequest) {
+  const store = await Store.findUniqueOrThrow({
+    where: { publicId: req.params.storeId },
+    select: { publicId: true, name: true, slug: true, logoUrl: true },
+  });
+  return { store };
+}
+```
+
+Two related habits:
+
+- **Do not ship the same data twice.** If a `Query.prefetch` already primes a read,
+  the view handler need not also return that data as props — pick one.
+- **Narrow at the query, not after it.** `select` in the ORM call keeps the columns
+  off the wire from the database too (`orm-select-narrow`), rather than loading them
+  and dropping them in JavaScript.
+
+Type safety follows the narrowing for free: `ViewProps<"/path">` infers the exact
+shape the handler returned.
+
+Reference: <https://nstfkc.github.io/gemi/views-and-layouts.md>

package/skills/gemi-react-best-practices/rules/payload-parallel-controller-work.md

@@ -0,0 +1,56 @@
+---
+title: Parallelize Independent Work in a Controller
+impact: CRITICAL
+impactDescription: 2-5x on multi-read endpoints
+tags: payload, async, promises, controllers, waterfalls
+---
+
+## Parallelize Independent Work in a Controller
+
+Server-side fetching lives in the controller method, not in the component tree, so
+there is nothing to restructure in the view — the parallelism is expressed where the
+awaits are. Independent awaits belong in a `Promise.all`.
+
+Each sequential `await` on an independent read adds a full database round-trip to
+the response.
+
+**Incorrect (three serial round-trips):**
+
+```ts
+export class OrganizationController extends Controller {
+  async show(req: HttpRequest) {
+    const org = await Organization.findUniqueOrThrow({ where: { publicId } });
+    const members = await Account.findMany({ where: { organizationId: org.id } });
+    const stores = await Store.findMany({ where: { organizationId: org.id } });
+    return { org, members, stores };
+  }
+}
+```
+
+**Correct (the dependent read first, then the two independent ones together):**
+
+```ts
+export class OrganizationController extends Controller {
+  async show(req: HttpRequest) {
+    const org = await Organization.findUniqueOrThrow({ where: { publicId } });
+    const [members, stores] = await Promise.all([
+      Account.findMany({ where: { organizationId: org.id } }),
+      Store.findMany({ where: { organizationId: org.id } }),
+    ]);
+    return { org, members, stores };
+  }
+}
+```
+
+**Two hard exceptions:**
+
+1. **Never `Promise.all` ORM calls inside `Model.transaction`** — see
+   `orm-transaction-sequential`. One reserved connection makes it unsafe.
+2. **A batch over the analytics pool is bounded**, not unbounded — the admin
+   aggregations cap their in-flight count at the pool size so a batch
+   cannot queue more work than the pool can serve.
+
+Two habits that compound with this: move an `await` into the branch that actually
+uses it, and check cheap synchronous conditions (a param, a flag already in memory)
+*before* awaiting anything — an early return costs nothing once the round-trip has
+already started.

package/skills/gemi-react-best-practices/rules/payload-prefetch-late-queries.md

@@ -0,0 +1,58 @@
+---
+title: Prefetch Reads That Render Discovers Late
+impact: CRITICAL
+impactDescription: removes a full serial round-trip
+tags: payload, prefetch, waterfall, suspense
+---
+
+## Prefetch Reads That Render Discovers Late
+
+gemi starts every query it can *reach* on the initial render, in parallel — so the
+page costs the slowest query, not their sum. The exception is a query render cannot
+reach yet. Two shapes cause it:
+
+1. **Nested under a suspending query.** A layout or parent that suspends blocks its
+   children from mounting, so their queries are not discovered until the parent
+   resolves — a textbook waterfall.
+2. **Conditionally rendered.** `{data.hasReports && <Reports />}` cannot start
+   `Reports`' query until `data` arrives.
+
+`Query.prefetch` in the controller starts these at request time instead of at
+discovery time, collapsing the waterfall.
+
+**Incorrect (the inner read cannot start until the outer one resolves):**
+
+```tsx
+function Dashboard() {
+  const { data: summary } = useQuery("/app/:orgId/summary", { params });
+  // Discovered only after `summary` resolves — two serial round-trips.
+  return summary.hasOrders ? <PendingOrders /> : null;
+}
+
+function PendingOrders() {
+  const { data } = useQuery("/app/:orgId/orders/pending-count", { params });
+  return <Badge>{data.count}</Badge>;
+}
+```
+
+**Correct (both start at request time, in parallel):**
+
+```ts
+export class DashboardController extends Controller {
+  view(req: HttpRequest) {
+    const orgId = req.params.orgId;
+    Query.prefetch("/app/:orgId/summary", { params: { orgId } });
+    Query.prefetch("/app/:orgId/orders/pending-count", { params: { orgId } });
+    return {};
+  }
+}
+```
+
+Matching prefetched data wakes a suspended query immediately, and an in-flight
+result is not overwritten by a later prefetch — so priming is safe to add.
+
+Weigh it against `payload-dont-overprefetch` first: priming costs bandwidth on
+every navigation. For a route where you deliberately want no priming,
+`Query.noPrefetch()` silences the dev hint.
+
+Reference: <https://nstfkc.github.io/gemi/data-fetching.md>