@voltro/cli 0.52.0 → 0.53.0

package/templates/agent-docs/data.md

@@ -1103,6 +1103,40 @@ target: {
 
 `path`, `by`, `match`, and `shapeItem` are browser-safe descriptor data (a dot-path string + pure functions) — the same discipline as `identify`/`shape`.
 
+## Declared relations — a junction saved in the same mutation
+
+A form with a multi-reference field (assigned stores, tags, members) writes a
+JUNCTION table beside the row. Declare that on the write target and the
+framework reconciles the links INSIDE the mutation's transaction — no
+hand-written junction code in the executor, and a failure rolls the whole
+write back:
+
+```ts
+export const employeesUpdate = defineMutation({
+  name: 'employees.update',
+  input: EmployeesUpdateInput,   // carries assignedStores: string[]
+  output: Employee,
+  target: {
+    table: 'employees',
+    op: 'update',
+    relations: { assignedStores: 'employee_assigned_stores' },
+  },
+})
+```
+
+After the executor succeeds, `input.assignedStores` is reconciled against the
+junction via the diff-based link writer (`store.relationLinks`): missing rows
+inserted, surplus rows deleted, unchanged rows untouched — so reactive
+subscriptions on the junction see one change per changed row. The anchor
+column is derived from the junction's `reference()` targets; a self-junction
+(both columns referencing one table) is refused by name, never guessed.
+
+The semantics worth knowing: an ABSENT input field leaves the links
+untouched — absent is not empty; an empty array is the explicit "clear them
+all". The row id comes from the executor's `output.id`, falling back to
+`input.id`. The link writes go through `ctx.store`, so undo capture and
+cross-table rules see them like any other write.
+
 ## Typed Errors
 
 ```ts
@@ -2026,8 +2060,14 @@ Queries/subscriptions are for live state. Streams are for one-shot element flows
 ## Reconnect
 
 A dropped WebSocket rebuilds the whole client stack — new socket, new RPC
-client, new subscription cache — and re-subscribes every active query, each of
-which answers with a fresh snapshot.
+client, new subscription cache — and re-subscribes every active query. Inside
+the resume window (`reactive.resume.windowMs`, default 60 s) the server replays
+**only the deltas the client missed** — the re-subscribe presents the last
+materialised revision and the stream continues on the same revision line, so a
+short offline gap costs a handful of patches instead of every row. Outside the
+window, for computed queries, for row-filtered apps, or whenever anything is in
+doubt, the query answers with a fresh snapshot — the delta-resume wire contract
+lives in [the wire protocol](/docs/data/wire-protocol#reconnect--delta-resume).
 
 **What is on screen while that happens is your last-known-good data, not a
 skeleton.** The replacement cache is seeded from the one it retires, so `data`
@@ -2054,6 +2094,15 @@ Three things are deliberately NOT carried across:
 - **Entries nothing re-subscribes to.** A screen that unmounted during the
   reconnect does not pin its rows; the seed evicts on the normal inactive TTL.
 
+### The local-first mirror partitions by subject — the carve-out
+
+An app using `@voltro/local-first`'s query mirror keeps rows on the DEVICE
+across reloads. The blank-on-auth rule extends there structurally: every
+mirrored key carries the subject AND tenant, so the next subject's binding
+simply never finds the predecessor's rows, and a logout or membership
+revocation calls `purge()` on the departing partition. Nothing about the
+in-memory blanking above changes.
+
 ### An auth change still blanks — on purpose
 
 When the rebuild happens because the connection's *subject* changed — a cookie
@@ -2158,32 +2207,40 @@ once. Order BETWEEN subscribers was never guaranteed.
 There is a number, it is not a constant, and which number you get depends on a
 property of your **queries** rather than of your scale. Re-derive it on your own
 hardware with `node packages/runtime/scripts/fanout-ceiling.mjs`; the figures
-below are the spread across three runs on a busy developer machine at 10 matched
-writes per second, against a budget of 100 ms of event-loop time per second (10%
-of one core).
+below are the spread across three runs on a busy developer machine (12-core,
+macOS) at 10 matched writes per second, against a budget of 100 ms of
+event-loop time per second (10% of one core).
 
 | Subscriber population | Marginal CPU per subscriber | Subscribers per node |
 | --- | --- | --- |
-| **Shared** — N clients on the SAME query (a leaderboard, a shared board) | 0.5–0.9 µs | ≈ 11 000–20 000 |
-| **Distinct** — N clients each on their OWN query (`where userId = me`) | 22–29 µs | ≈ 350–450 |
-
-Ranges rather than single numbers, deliberately: that is the spread three runs
-produced, and a ceiling quoted to three significant figures from one run is a
-number somebody will hold you to.
-
-The shared case is cheap because the memoisation above applies: one read, one
-diff, N emits. The distinct case gets no sharing at all — the read, the diff and
-the emit are all per subscriber — and a per-user dashboard is exactly that shape.
-**Plan against the distinct number**, and note that it scales inversely with your
-write rate: at 1 matched write per second it is ten times higher.
-
-Two things that are easy to assume and are not true:
-
-- **A more selective `where` buys no headroom.** Measured: 200 of 200
-  subscribers whose predicate matched *nothing* were still woken by one write on
-  their table. Every subscription is a dependent of its own table, so a change
-  wakes all of them and each re-queries. The ceiling counts subscribers **on the
-  table**, not subscribers whose predicate matches.
+| **Shared** — N clients on the SAME query (a leaderboard, a shared board), every write matches all of them | 0.37–0.41 µs | ≈ 25 000–27 000 |
+| **Distinct** — N clients each on their OWN query (`where userId = me`), a write matches ONE | flat — per-write cost does not grow with resident subscribers | not set by subscriber count |
+
+The shared case fans out by design — one read and one diff (the memoisation
+above), then N emits — and it is the shape that sets the ceiling. The distinct
+case changed shape entirely with **matcher authority**: a subscription whose
+query is a plain predicate read is woken by the predicate index alone, so a
+write to *somebody else's* row is a non-event, not a wake. Per write it costs a
+bucket lookup plus one delivery, regardless of how many thousands of distinct
+subscribers are resident. Measured: **0 of 200** subscribers whose predicate
+matched nothing were woken by a write on their table — **a selective `where`
+buys real headroom** now.
+
+What still wakes conservatively (any change on the table), and deliberately —
+this list is exhaustive:
+
+- queries with an **eager `.with()` spec**, a setOp (`union`/…) or a CTE — the
+  handler reads rows the root predicate does not describe;
+- **`dependsOn`** raw reads (the dispatcher can only re-run the descriptor,
+  never the handler);
+- **computed** queries and **`reactivityChannel`** queries (their own
+  recompute paths, unchanged);
+- **oversized change events** (`tombstone` / `unrecovered` — row images the
+  matcher cannot see wake the whole table for that one event; `rehydrated`
+  events are judged normally).
+
+One thing that is easy to assume and is not true:
+
 - **It is not 512.** That constant bounds `onChange` LISTENERS — one per declared
   subscription file, reaction or aggregate, bound once at boot. Every client
   subscription in a process shares the dispatcher's single listener, so ten
@@ -2195,6 +2252,17 @@ mysql/mariadb (binlog), so a second node needs no extra wiring — the cost bein
 budgeted here is the matcher and re-query CPU each node spends on ITS OWN
 clients.
 
+### Deltas are per-query — two queries can briefly diverge
+
+Every subscription has its own revision line and its own delivery moment. After
+one write that affects two queries you hold open, the deltas arrive as two
+independent pushes — usually microseconds apart, but there is no cross-query
+transaction on the wire, and a render between the two pushes can see query A
+after the write and query B before it. Within ONE query you never see a partial
+write (a delta is computed from a committed row set); across queries, design for
+eventual agreement rather than instantaneous consistency — derive values that
+must agree atomically inside one query instead of joining two on the client.
+
 ## Raw WebSocket gateways — `defineWebSocket`
 
 Everything above rides the framework's subscription protocol, and that stays the answer for app realtime — live queries, optimistic patches, reconnect. A **gateway** exists for the other case: a FOREIGN protocol that needs a socket the framework does not speak — a Yjs provider, a legacy device fleet, an MQTT-over-WS bridge. It mounts its own upgrade path beside the rpc socket, in a `*.ws.ts` file discovered on **both** boot paths:
@@ -4854,7 +4922,7 @@ A streaming query (what `useSubscription` opens) emits a sequence of **subscript
 { _tag: 'error', error: { _tag?: string, message: string, ...fields }, revision?: number }
 ```
 
-- **`revision`** — monotonically increasing; lets the client order events and detect gaps.
+- **`revision`** — monotonically increasing; lets the client order events. **Revisions may JUMP forward** — under socket backpressure the server coalesces updates a slow consumer hasn't read yet into one event whose patch is computed against the row set of the last event it actually handed over, so patch continuity holds across the jump. A jump is therefore normal, never a gap; only a *regressing* or repeating revision would be a protocol violation.
 - **`emittedAt`** — epoch milliseconds, present on `delta` only.
 - **`data`** (snapshot) — the full payload, typed by the query's `output` schema (a row, an array of rows, a computed value — whatever the handler returns).
 - **`patch`** (delta) — an id-keyed RFC-6902-style patch against the row set the client last held.
@@ -4873,6 +4941,70 @@ propagate to the shared connection and stall every *other* subscription on it
 client surfaces it as `useSubscription(...).error` for that one query key;
 siblings keep delivering their snapshots and deltas.
 
+### Slow consumers — coalescing and `SubscriptionOverrun`
+
+A consumer that stops reading (a backgrounded tab, a saturated link) does not
+grow the server without bound. While its socket is blocked, updates
+**coalesce**: the server keeps only the newest state per subscription and, when
+the socket accepts again, sends ONE event — a patch against the last state the
+consumer was actually handed (`revision` jumps accordingly, see above). Memory
+per blocked subscription is bounded by construction: one pending state,
+regardless of how far behind the consumer is.
+
+A consumer that stays more than `reactive.socket.maxBufferedBytes` (default
+1 MiB, env `VOLTRO_REACTIVE_MAX_BUFFERED_BYTES`) behind for
+`reactive.socket.overrunAfterMs` (default 10 s) is closed **loudly**: it
+receives an `error` event with `error._tag: 'SubscriptionOverrun'` (carrying
+`bufferedBytes` + `maxBufferedBytes`) and the stream ends — never a silent
+drop. The client re-subscribes and starts from a fresh snapshot.
+
+Oversized events are telemetry, not a cap: an event over
+`reactive.socket.oversizedEventBytes` (default 256 KiB) is delivered normally
+and counted (`voltro_subscription_oversized_total`) with a WARN naming the
+query — alongside `voltro_subscription_buffered_bytes`,
+`voltro_subscription_coalesced_total` and `voltro_subscription_overrun_total`
+in the Prometheus exporter and the inspect Metrics panel.
+
+### Reconnect — delta-resume
+
+A client that reconnects inside the **resume window** does not have to pay for
+a full snapshot: it sends the last `revision` it materialised in the per-call
+`voltro-resume-from` request header (the same header surface the idempotency
+key rides), and the server — which kept the subscription alive server-side for
+the window after the disconnect — **replays only the deltas that were missed**
+and re-attaches the stream on the SAME revision line.
+
+The signal is the first event's tag, not a schema field:
+
+- **first event `delta`** — the resume was honoured; apply the patch onto the
+  rows you already hold and continue.
+- **first event `snapshot`** — the resume was declined; reset to the snapshot.
+  This is the answer whenever anything is in doubt, because a wrong snapshot
+  costs bytes while a wrong replay would leak rows.
+
+`@voltro/client` does both automatically — the reconnect-seeded cache keeps its
+rows and revision, presents the header, and treats a snapshot-first stream as
+the reset it already knows how to do. Replayed deltas may **coalesce** exactly
+as slow-consumer updates do (revisions jump; patch continuity holds).
+
+A resume is declined — always with a fresh snapshot — when:
+
+- the window expired (`reactive.resume.windowMs`, default 60 s, env
+  `VOLTRO_REACTIVE_RESUME_WINDOW_MS`), or more deltas were missed than the ring
+  retains (`reactive.resume.maxDeltas`, default 256, env
+  `VOLTRO_REACTIVE_RESUME_MAX_DELTAS`);
+- the query's `guards:` were revoked while the client was away — the
+  per-delivery re-check keeps running on the detached subscription, and a
+  revocation drops the retained history outright;
+- the resuming caller is a different subject or tenant (a login, logout or
+  tenant switch between disconnect and resume) — the retained history is keyed
+  by subject AND tenant, so a changed identity simply never finds it;
+- the app registers a row filter (`setRowFilter`), or the query is a
+  **computed** query — both are excluded from resume by design: a row-filtered
+  subscription's visible row set exists only per delivery, and a computed query
+  re-runs a handler with no delta chain to replay. They reconnect with a fresh
+  snapshot, exactly as before.
+
 **Author a live-subscribed getter to return, not throw.** A subscription is a
 long-lived stream, so a getter that throws on every re-evaluation is a broken
 stream. For an expected-absent row, make the query `output: Schema.NullOr(...)`
@@ -5205,6 +5337,203 @@ try {
 
 
 
+---
+
+<!-- source: en/data/content-collections.md -->
+## Content collections
+
+_File-based, schema-typed markdown content — defineCollection over content/<name>/**/*.md, an isomorphic getCollection/getEntry, locale trees with fallback, headings for TOCs, data collections, references, and RSS feeds — without installing a markdown dependency._
+
+A content collection turns a folder of markdown files into typed, rendered
+content: you declare the frontmatter schema in code, and `getCollection()` /
+`getEntry()` hand you decoded data plus server-rendered HTML with
+syntax-highlighted code fences. The markdown engine lives in the framework —
+**do not install your own `marked` / `remark` / `shiki`**; a second pipeline
+drifts from the one your artifacts, feeds and templates already use.
+
+## A blog in 20 lines
+
+One collection file, one markdown file, one page:
+
+```ts
+// src/collections/posts.collection.ts
+import { Schema } from 'effect'
+import { defineCollection } from '@voltro/content'
+
+export const posts = defineCollection({
+  name: 'posts',
+  directory: 'content/posts',
+  schema: Schema.Struct({ title: Schema.String, date: Schema.String }),
+})
+export type Post = Schema.Schema.Type<typeof posts.schema>
+```
+
+```ts
+// src/pages/blog/[slug]/page.tsx
+import { getCollection, getEntry, type ContentEntry } from '@voltro/content'
+import { useLoaderData } from '@voltro/web'
+import { posts, type Post } from '../../../collections/posts.collection'
+
+export const renderMode = 'static' as const
+export const getStaticPaths = async () =>
+  (await getCollection(posts.name)).map((e) => ({ params: { slug: e.slug } }))
+export const loader = async ({ params }: { params: { slug: string } }) =>
+  await getEntry<Post>(posts.name, params.slug)
+
+export default function Post() {
+  const post = useLoaderData<ContentEntry<Post> | null>()
+  if (!post) return <main>Not found</main>
+  return <article dangerouslySetInnerHTML={{ __html: post.html ?? '' }} />
+}
+```
+
+Drop `content/posts/hello.md` with `title:` + `date:` frontmatter and the
+build pre-renders `/blog/hello` — highlighted code fences included.
+
+## How it stays out of your bundle
+
+The loader is **isomorphic**. At build/SSR time it reads the filesystem and
+renders markdown (shiki runs on the server only). The build also emits JSON
+artifacts under `dist/assets/content/<name>[.<locale>]/…` — an index (slugs +
+frontmatter, no bodies) and one file per entry (rendered HTML + headings). On
+an SPA navigation, the CLIENT branch of `getCollection`/`getEntry` fetches
+those artifacts. The result: no markdown engine, no highlighter, and no
+content bodies in your JavaScript bundle. `voltro dev` serves the same
+artifact shapes on demand and invalidates them when a `content/**` file
+changes.
+
+## Frontmatter is a schema, and violations fail the build
+
+The `schema` is an `effect/Schema` struct decoded per file. A missing or
+mistyped field is a **build error naming the file** — not a page that renders
+`undefined`. Numbers in frontmatter arrive as strings; use
+`Schema.Union(Schema.NumberFromString, Schema.Number)` for numeric fields.
+`getCollection<A>` returns entries whose `data` is the schema's inferred
+type — no casts.
+
+## Slugs come from the path
+
+`content/posts/hello.md` → `hello`; nested folders stay in the slug
+(`database/joins.md` → `database/joins`). Two files resolving to one slug
+(a rename that left both) is a build error.
+
+## Locale trees + fallback
+
+A collection with `i18n` treats the first path segment as the locale:
+
+```ts
+export const docs = defineCollection({
+  name: 'docs',
+  directory: 'content/docs',
+  schema: Schema.Struct({ title: Schema.String }),
+  i18n: { locales: ['en', 'de'], defaultLocale: 'en', missing: 'fallback' },
+})
+```
+
+`getCollection('docs', { locale: 'de' })` reads the `de/` tree. A slug missing
+in the requested locale is served from the default tree with
+`fallback: true` on the entry (render an "untranslated" banner off it) — or
+omitted entirely with `missing: 'missing'`. Incomplete translations are the
+normal case; decide the policy per collection instead of improvising per page.
+
+## Headings as data
+
+Every rendered entry carries `headings: [{ depth, slug, text }]` — the TOC
+input. The slugs are the SAME ids stamped on the rendered `<h2 id="…">`
+elements, so sidebar anchors never drift from the body. For a TOC without a
+render pass, `extractHeadings(markdown)` (from `@voltro/content/markdown`)
+computes the same data synchronously.
+
+## Data collections
+
+`kind: 'data'` reads `.json` files instead of markdown — the `authors.json`
+case. Each file decodes whole against the schema; there is no render path:
+
+```ts
+export const authors = defineCollection({
+  name: 'authors',
+  directory: 'content/authors',
+  kind: 'data',
+  schema: Schema.Struct({ name: Schema.String, url: Schema.String }),
+})
+```
+
+## References between collections
+
+`reference('<collection>')` declares a frontmatter field that names an entry
+of another collection by slug:
+
+```ts
+schema: Schema.Struct({
+  title: Schema.String,
+  author: reference('authors'),
+})
+```
+
+The build validates every reference — a dangling one (`author: nobody`) fails
+the build naming the collection, entry, field and target. Resolve it with
+`getEntry('authors', entry.data.author)`.
+
+## RSS feeds from a collection
+
+Declare feeds in `app.config.ts`; the build writes them next to
+`sitemap.xml`, and `voltro dev` serves the same XML live:
+
+```ts
+export default {
+  // …
+  seo: { siteUrl: 'https://example.com' },
+  feeds: [{
+    path: '/rss.xml',
+    collection: 'posts',
+    title: 'My blog',
+    item: (e) => e.data.draft === 'true' ? null : ({
+      title: e.data.title, link: `/blog/${e.slug}`, date: e.data.date,
+    }),
+  }],
+}
+```
+
+Returning `null` from `item` excludes an entry — that is the **draft filter**:
+keep a `draft: true` field in your schema and filter it in `item` and in your
+page loaders (the changelog template's `visibleReleases` helper is the worked
+example, including future-dated staging).
+
+## No MDX — islands carry the interactivity
+
+Collection bodies are **markdown, not MDX**: JSX, `import`s and
+`{expressions}` in a body are not executed. When a content page needs a live
+widget, the surrounding PAGE provides it via the islands mechanism — the
+content stays inert HTML and the widget hydrates alone:
+
+```tsx
+// src/pages/blog/[slug]/page.tsx
+export const interactive = 'islands' as const
+
+export default function Post() {
+  const post = useLoaderData<ContentEntry<Post>>()
+  return (
+    <main>
+      <ReadingProgress />  {/* an island() component — the ONLY hydrated JS */}
+      <article dangerouslySetInnerHTML={{ __html: post.html ?? '' }} />
+    </main>
+  )
+}
+```
+
+## Limits + neighbors
+
+- **Images referenced from markdown bodies** are copied as-is (no transform):
+  the [image pipeline](/docs/routing/assets) covers `?image` imports from
+  code. Put content images under `public/` and reference them absolutely.
+- **Files are DEVELOPER content** — versioned with the code, deployed by the
+  build. Editorial content with drafts, roles and a save/publish pipeline is
+  [`@voltro/cms`](/docs/data/cms). Astro's remote "Content Layer loaders"
+  map to `@voltro/cms` here: remote/editorial sources go through the CMS,
+  not through file collections.
+
+
+
 ---
 
 <!-- source: en/data/cms.md -->
@@ -5745,3 +6074,118 @@ app's public origin comes from `VOLTRO_PUBLIC_URL`.
   a secret, not a connection.
 - **`redirectTo` is a same-origin path only.** An absolute URL is rejected —
   otherwise every app declaring a connection would ship an open redirector.
+
+
+
+---
+
+<!-- source: en/data/grpc.md -->
+## gRPC surface
+
+_Serve opt-in procedures to generated gRPC clients — proto emitted from your effect/Schema with checked-in field-number stability, unary for mutations/actions, server-streaming for live queries, guards + interceptors + typed errors identical to the socket._
+
+The gRPC surface serves a NAMED list of your procedures to external gRPC
+clients — the polyglot-microservice door. The `.proto` is generated from the
+same `effect/Schema` your procedures already declare, so there is no second
+contract to maintain; the wire semantics are the framework's own: guards,
+plugin interceptors and typed errors behave **identically** to the rpc
+socket, because a gRPC call runs the *same bound runner* every other surface
+uses (the e2e proves interceptor order side by side).
+
+```ts
+// app.config.ts
+export default {
+  type: 'api' as const,
+  name: 'api',
+  grpc: {
+    port: 50051,
+    procedures: ['orders.get', 'orders.list', 'orders.create'],
+    // tls: { certPath, keyPath, caPath? } — plaintext without it (dev / mesh).
+  },
+}
+```
+
+NOTHING is exposed by default — every tag is named. Booting writes
+`.framework/grpc.proto` (hand it to any proto codegen) and mounts
+`grpc.health.v1` health checking plus server reflection (`grpcurl … list`
+works out of the box). The gRPC packages ship as script-free optional
+dependencies of `@voltro/cli`; a configured `grpc:` block with them missing
+refuses the boot by name.
+
+## Field numbers are managed — `grpc.manifest.json`
+
+Field numbers are the proto wire identity, so they may never depend on
+property order. They come from a checked-in manifest in your app root:
+
+- a **new** field gets the next never-used number — an **inserted** field
+  never renumbers its neighbours;
+- a **deleted** field's number becomes `reserved` (emitted into the proto,
+  so `protoc` refuses a colliding hand-edit too);
+- **reusing** a reserved number is a codegen error, never a warning — an old
+  client would silently read the wrong field.
+
+Commit the manifest with the schema change that moved it: the diff review IS
+the wire-contract review.
+
+## The mapping table
+
+| Schema | proto3 |
+|---|---|
+| `Schema.String` / `Number` / `Boolean` | `string` / `double` / `bool` |
+| integer schemas | `int64` |
+| `Schema.Array(T)` | `repeated T` |
+| nested `Schema.Struct` | nested message |
+| `Schema.Record({ key: String, value: T })` | `map<string, T>` |
+| `Schema.optional(T)` **and** `Schema.NullOr(T)` | `optional T` — absent and `null` are ONE wire state (proto3 presence) |
+| string-literal unions | `string` (validated server-side on decode) |
+| unions of shapes, tuples, recursion, free-form objects | a LOUD per-procedure codegen error naming the schema path |
+
+Requests are decoded against the descriptor's input schema before the
+executor runs — proto3 suppresses default values on the wire, and without
+that decode an empty string would arrive as an absent field and fail
+somewhere much later.
+
+## Status codes — complete against the wire error union
+
+| outcome | gRPC status | trailers |
+|---|---|---|
+| no credential on a guarded call | `UNAUTHENTICATED` | |
+| presented-and-rejected credential | `UNAUTHENTICATED` | |
+| authenticated, missing scope (`ScopeError`) | `PERMISSION_DENIED` | `voltro-error: scope` |
+| input fails the schema | `INVALID_ARGUMENT` | `voltro-error: input` |
+| `BusinessRuleViolation` | `FAILED_PRECONDITION` | `voltro-error: rule` |
+| `requiresApproval` pending — a FLOW OUTCOME, not a failure | `FAILED_PRECONDITION` | `voltro-pending: approval` + `voltro-approval-id` |
+| your declared typed error | `FAILED_PRECONDITION` | `voltro-error: <tag>` |
+| deadline exceeded | `DEADLINE_EXCEEDED` | |
+| anything else | `INTERNAL` | |
+
+**Deadlines interrupt the work.** A client deadline (`grpc-timeout`) aborts
+the executor's fiber through the request signal — the server stops doing the
+work, it does not merely suppress the response (the e2e pins this with a
+sleeping action whose post-sleep write never lands).
+
+## Streaming queries
+
+A `query` becomes a **server-streaming** rpc: each frame is the CURRENT full
+snapshot, re-pushed live when the query's `source:` changes — subscribe,
+mutate from anywhere, and the open stream receives the new frame with no
+re-request. The per-delivery guard re-check applies (a revoked scope ends
+the stream with the mapped status), and slow consumers are handled through
+grpc-js write backpressure — frames coalesce to the latest snapshot rather
+than buffering unboundedly.
+
+## Declared limits (v1)
+
+- **No client- or bidi-streaming**, and `*.stream.ts` procedures are NOT
+  exposable — the fourth kind is a one-shot element stream with its own
+  semantics; put it behind a query or keep it on the socket.
+- **No gRPC-Web** — a browser talks the framework's own subscription
+  protocol (that is the better browser transport in every dimension we care
+  about); gRPC is for backends.
+- **No Connect protocol** — connectrpc is NOT gRPC-Web; a connect consumer's
+  alternative today is the [REST/OpenAPI projection](/docs/data/rest-routes).
+- App realtime stays on the framework's subscription protocol, and gateways
+  exist for the other case: a FOREIGN protocol that needs a socket the
+  framework does not speak — the same boundary
+  [data/subscriptions](/docs/data/subscriptions) draws for raw WebSocket
+  gateways, one sentence, two doors.

package/templates/agent-docs/database/advancedqueries.md

@@ -379,7 +379,7 @@ Emits `CONSTRAINT <name> UNIQUE (col1, col2, ...)` inline in CREATE
 TABLE on every dialect. Standard SQL.
 
 This is what backs `ctx.store.upsert(..., { conflictColumns: ['a', 'b'] })`
-— see [Bulk operations](/docs/database/bulk-operations#upsert).
+— see [Bulk operations](/docs/database/bulk-operations#upsert-insert-or-update-on-conflict).
 
 ## GiST indexes (PostGIS spatial)
 
@@ -689,7 +689,7 @@ mssql, sqlite 3.8+).
   depend on?"
 
 When you don't have a recursive structure, plain
-[`withCte()`](/docs/database/query-builder#ctes) is enough.
+[`withCte()`](/docs/database/query-builder#ctes-common-table-expressions) is enough.
 
 ## Shape
 
@@ -820,7 +820,7 @@ eager-load with `.with({...})` to get the per-field pre-filter.
 
 ## See also
 
-- [Plain CTEs](/docs/database/query-builder#ctes) — `withCte()` for
+- [Plain CTEs](/docs/database/query-builder#ctes-common-table-expressions) — `withCte()` for
   non-recursive named sub-queries
 - [Self-joins](/docs/database/self-joins) — for single-level
   parent/child queries
@@ -830,7 +830,7 @@ eager-load with `.with({...})` to get the per-field pre-filter.
   `unionAll`, the mechanism a recursive CTE is built on
 - [Joins](/docs/database/joins) — relation-based traversal when the
   graph depth is fixed (e.g. parent + immediate children)
-- [Aggregations](/docs/database/query-builder#aggregations) —
+- [Aggregations](/docs/database/query-builder#aggregates) —
   COUNT/SUM/AVG over a recursive CTE's result set
 
 
@@ -940,7 +940,7 @@ keep the branches' result sets bounded.
   the column-level "in A but not in B" case
 - [Aggregations](/docs/database/aggregations) — `count()` etc. on
   a set-op result is a common pattern
-- [CTEs](/docs/database/query-builder#ctes) — name a complex set-op
+- [CTEs](/docs/database/query-builder#ctes-common-table-expressions) — name a complex set-op
   result so you can reference it in a larger query
 
 
@@ -1044,7 +1044,7 @@ Non-correlated only. The inner query can NOT reference outer-row
 columns like `WHERE inner.userId = users.id`. For correlated
 sub-queries (a common shape: "user who has at least one post created
 in the last hour") use a [Self-join](/docs/database/self-joins) or
-an [Eager-load](/docs/database/joins#eager-loading) — both can
+an [Eager-load](/docs/database/joins#eager-loading-via-with-spec) — both can
 express the same query without the correlation reference.
 
 ## Reactivity
@@ -1069,7 +1069,7 @@ every dialect we ship. No per-dialect dispatch.
   with `count()` etc. for "count of X where Y belongs to Z"
 - [Self-joins](/docs/database/self-joins) — when the relationship
   can be expressed as a join instead
-- [CTEs](/docs/database/query-builder#ctes) — for naming a
+- [CTEs](/docs/database/query-builder#ctes-common-table-expressions) — for naming a
   sub-query you reuse multiple times in the same outer query
 
 

package/templates/agent-docs/database/columntypes.md

@@ -350,7 +350,7 @@ on it explicitly via `.expressionIndex(name, [...], { ... })`.
 
 - [Columns](/docs/database/columns) — `.computed(row => ...)` and
   `.default(() => ...)` for the app-side variants
-- [Indexes](/docs/database/indexes#expression) — `.expressionIndex()`
+- [Indexes](/docs/database/indexes#expression-indexes) — `.expressionIndex()`
   for indexing a generated column
 - [Full-text search](/docs/database/full-text-search) — the FTS
   pattern uses STORED tsvector generated columns
@@ -989,7 +989,7 @@ behavioural gaps are too large to paper over.
 ## See also
 
 - [Columns](/docs/database/columns) — the regular schema-DSL types
-- [Expression indexes](/docs/database/indexes#expression) — the
+- [Expression indexes](/docs/database/indexes#expression-indexes) — the
   framework's index API (`kind: 'gist' | 'gin'` on postgres)
 - [PostGIS docs](https://postgis.net/docs/) — the official manual,
   authoritative for every spatial function the framework re-exports

package/templates/agent-docs/database/querying.md

@@ -309,7 +309,7 @@ The query builder has dedicated pages for the deeper topics:
 - **[Self-joins](/docs/database/self-joins)** — `.as(alias)` +
   `.innerJoin(table, alias, on)` + `.selectJoined({...})` for parent/
   child trees and CTE references.
-- **[CTEs](/docs/database/query-builder#ctes)** — `.withCte(name, sub)`
+- **[CTEs](/docs/database/query-builder#ctes-common-table-expressions)** — `.withCte(name, sub)`
   for named sub-queries reusable inside the outer SELECT.
 - **[Recursive CTEs](/docs/database/recursive-cte)** — `.recursiveCte`
   for tree walks (org hierarchy, comment threads, file folders).

package/templates/agent-docs/database/schema.md

@@ -445,7 +445,7 @@ framework runs on the post-commit change channel.
 **Reach for `reference()` first.** A real foreign key across a plugin boundary
 works and survives the plugin renaming its table, because `reference()` takes
 the table as a VALUE — see
-[plugins/overview](/docs/plugins/overview#pointing-your-table-at-a-plugins-row).
+[plugins/overview](/docs/plugins/overview).
 `pluginRef` is for the case where you have deliberately chosen NOT to have a
 key: it enforces nothing at the database level.