@voltro/cli 0.30.1 → 0.31.0

package/templates/agent-docs/plugins/multitenancy.md

@@ -0,0 +1,99 @@
+# Multi-tenancy
+
+> The tenant() schema mixin (auto-scope reads + auto-fill writes), the assertOwnTenant write-guard, and the typed TenantMismatch error.
+
+
+
+---
+
+<!-- source: en/plugins/multitenancy.md -->
+## Multi-tenancy
+
+_The tenant() schema mixin (auto-scope reads + auto-fill writes), the assertOwnTenant write-guard, and the typed TenantMismatch error._
+
+`@voltro/plugin-multitenancy` is the first-party multi-tenancy primitive. It has two surfaces: a **schema mixin** (`tenant()`) and a **write-time guard** (`assertOwnTenant` + the typed `TenantMismatch` error).
+
+**Status:** ✓ shipped.
+
+## The `tenant()` mixin
+
+Add it to any table whose rows belong to a tenant. It contributes a `tenantId` reference (to the app's `tenants` table) and tells the runtime to auto-scope reads + auto-fill writes:
+
+```ts
+import { table, id, text } from '@voltro/database'
+import { tenant } from '@voltro/plugin-multitenancy'
+
+export const projects = table('projects', {
+  id:   id(),
+  name: text(),
+}).with(tenant())
+```
+
+`tenant()` transitively requires `audit()` — composing it pulls in the
+`createdAt` / `updatedAt` / `createdBy` / `updatedBy` columns too. The mixin
+is also available on the `./mixin` subpath (`@voltro/plugin-multitenancy/mixin`)
+for projects that don't want the full barrel.
+
+What the runtime does for a `tenant()`-marked table:
+
+- **Reads are auto-scoped.** The runtime AND-merges `eq('tenantId', subject.tenantId)` into every subscription predicate against the table — tenant A never sees tenant B's rows, and a write in tenant A never wakes a subscription in tenant B.
+- **Writes are auto-filled.** On insert, `tenantId` is stamped from `ctx.request.subject.tenantId` when the caller didn't pass it explicitly. The wrapper never overrides a value the caller did pass.
+
+## The write-guard — `assertOwnTenant`
+
+Read isolation is automatic. **Writes are not** — a mutation receives raw, user-supplied input including `tenantId`, so without an explicit check a client authenticated as tenant A could submit `tenantId: 'B'` and land the row in B's data. Guard every tenant-scoped mutation:
+
+```ts
+import { assertOwnTenant, TenantMismatch } from '@voltro/plugin-multitenancy'
+
+const execute = async (input: { tenantId: string }, ctx) => {
+  assertOwnTenant(input.tenantId, ctx.request.subject)
+  // safe to use input.tenantId for the write
+}
+```
+
+`assertOwnTenant(inputTenantId, subject)` throws `TenantMismatch` when `inputTenantId` doesn't equal the subject's `tenantId`. Anonymous subjects have no tenant scope at all, so the guard always throws for them — anonymous + tenant-scoped writes need an `apiKey` / `serviceAccount` subject instead.
+
+## The typed error — `TenantMismatch`
+
+`TenantMismatch` is a `Schema.TaggedError` carrying `inputTenantId` + `subjectTenantId` (empty string for anonymous subjects). Declare it on the mutation's `error:` schema so the rpc layer surfaces the rejection typed. **Import it from the browser-safe `@voltro/plugin-multitenancy/guard` subpath in the descriptor (`*.mutation.ts`)** — the package root also re-exports the schema mixin, which pulls `@voltro/database` into the client rpcGroup bundle (a browser-safety violation):
+
+```ts
+import { defineMutation } from '@voltro/protocol'
+import { TenantMismatch } from '@voltro/plugin-multitenancy/guard'
+import { Schema } from 'effect'
+
+export const createProject = defineMutation({
+  name:   'projects.create',
+  input:  Schema.Struct({ tenantId: Schema.String, name: Schema.String }),
+  output: Schema.Struct({ id: Schema.String }),
+  error:  TenantMismatch,
+  target: { table: 'projects', op: 'insert' },
+})
+```
+
+The client then pattern-matches on `error._tag === 'TenantMismatch'`.
+
+## Why it's a separate package
+
+Multi-tenancy is a product decision, not a transport-protocol primitive — keeping it out of `@voltro/protocol` lets apps that don't need tenancy skip the dependency entirely, while `@voltro/protocol` stays focused on the wire (`Subject`, `AuthMiddleware`).
+
+## Data residency — pin a tenant to a region
+
+For regulated / EU buyers ("EU data stays in the EU"), pin each tenant to a home **region** and route its request-scoped store there. This composes namespace isolation (a tenant's rows live in their own namespace) with region routing — declare the tenant→home mapping plus which regions *this* deployment serves:
+
+```ts
+import { setResidencyConfig } from '@voltro/database'
+
+setResidencyConfig({
+  homes: [
+    { tenantId: 'acme_eu',   region: 'eu-west-1' },
+    { tenantId: 'globex_us', region: 'us-east-1', connectionKey: 'us_primary' },
+  ],
+  servableRegions: ['eu-west-1'],   // this deployment serves only EU
+})
+```
+
+The serve pipeline binds the store per request via `bindResidentStore(subject, config, stores)`, where `stores` is the per-region `DataStore` handles this deployment holds. It returns `{ store, placement }` — `placement` being `{ region, namespace, connectionKey? }`, the tenant's rows in its home region.
+
+It **fails closed** at every fork — no mapped home (or an anonymous caller) throws `TenantResidencyUnresolved`; a tenant homed in a region this deployment doesn't serve throws `TenantRegionUnavailable` (the gateway routes that request to the home region's deployment instead). There is no default store: a US deployment can never return a store for an EU-homed tenant. Per-region infra (the actual stores + connection strings via the secrets backend) is yours to provision; v1 routes the primary store — cross-region analytics across tenants is a separate concern.

package/templates/agent-docs/plugins/notifications.md

@@ -0,0 +1,252 @@
+# Notifications
+
+> Unified notifications — one send API across email / Slack / SMS / push / in-app, with per-user channel preferences, an in-app inbox, and delivery records.
+
+
+
+---
+
+<!-- source: en/plugins/notifications.md -->
+## Notifications
+
+_Unified notifications — one send API across email / Slack / SMS / push / in-app, with per-user channel preferences, an in-app inbox, and delivery records._
+
+`@voltro/plugin-notifications` is the **one** messaging answer instead of twenty brand wrappers: a single `send` across channels, per-user preferences, and an in-app inbox with unread counts — not a per-vendor SDK in every handler.
+
+## Wiring
+
+```ts
+// app.config.ts
+import { notificationsPlugin, consoleChannel, webhookChannel, emailChannel } from '@voltro/plugin-notifications'
+
+export default {
+  type: 'api' as const,
+  name: 'api',
+  plugins: [
+    notificationsPlugin({
+      channels: [
+        consoleChannel(),                                   // dev: writes to stdout
+        emailChannel((m) => myMailer(m)),                   // bridge to @voltro/plugin-mail
+        webhookChannel({ url: process.env.SLACK_WEBHOOK! }),// slack/teams/discord incoming webhook
+      ],
+    }),
+  ],
+}
+```
+
+The built-in **in-app** channel persists to the notification store and is appended automatically; `consoleChannel()`, `webhookChannel({ url, id?, format?, headers? })`, `emailChannel(send)`, `smsChannel(send)`, `pushChannel({ tokensFor, transport })` (see [Push](#push-apns-fcm)), and `customChannel(id, deliver)` cover the rest. A channel is just `{ id, deliver: (msg) => Promise<void> }` — bring your own.
+
+`notificationsPlugin({ channels?, store?, digestWindowMs?, flushIntervalMs?, name? })` — the inbox, per-subject channel preferences, and delivery log **auto-persist to the framework DataStore by default**, durably, on every supported dialect. You only pass an explicit `store` for a **custom** backend (see [Store](#store)). `digestWindowMs` enables [digest/batching](#digest-batching); the scheduled flush (interval `flushIntervalMs`, default 30s) drains digest windows and quiet-hours deferrals.
+
+## Sending — `NotificationService`
+
+```ts
+import { NotificationService } from '@voltro/plugin-notifications'
+
+export default (input: { userId: string }, _ctx) => Effect.gen(function* () {
+  const notify = yield* NotificationService
+  yield* Effect.promise(() => notify.send({
+    to: input.userId,
+    category: 'order.shipped',
+    title: 'Your order shipped',
+    body: 'Track it in your account.',
+    // channels?: ['email', 'inApp'] — narrow this send to specific channels
+  }))
+  return { ok: true }
+})
+```
+
+`resolveChannels` picks the effective channel set: an explicit `channels:` on the send narrows to those (intersected with the configured channels); else every configured channel — then any channel the user has turned **off** for that category (a stored `ChannelPreference` with `enabled: false`) is dropped. A missing preference means on. Each delivery is recorded as a `DeliveryRecord` (channel, status, error?).
+
+## Push (APNs / FCM)
+
+`pushChannel` is a first-class mobile-push channel — the built-in alternative to hand-rolling `customChannel`:
+
+```ts
+import { pushChannel, PushTokenRejected } from '@voltro/plugin-notifications'
+
+pushChannel({
+  tokensFor: async (subjectId) => myDeviceTokens(subjectId), // your device-token table
+  transport: async (payload) => {
+    // payload: { token, title, body, badge?, data } — the APNs / FCM shape.
+    const res = await sendToApns(payload) // your provider + AUTH secret live HERE
+    if (res.status === 410) throw new PushTokenRejected({ token: payload.token, reason: 'Unregistered' })
+  },
+})
+```
+
+`deliver` formats one `PushPayload` per device token and sends each. A `PushTokenRejected` is captured into the fan-out (recorded `failed`, naming the rejected token — **never** the auth secret) so your app can prune the dead token. The push AUTH secret lives in your `transport` closure — it never enters the package and is never logged.
+
+## Digest / batching
+
+Set `digestWindowMs > 0` and multiple sends to the **same subject** within the window coalesce into **one** digest delivery, flushed on the window boundary:
+
+```ts
+notificationsPlugin({ digestWindowMs: 5 * 60_000 }) // 5-minute rollup
+```
+
+Three sends to `u1` inside the window produce ONE `digest`-category notification whose body lists all three and whose `data.items` carries them. A send that forces its own `channels:` bypasses the digest (explicit intent → deliver now). The scheduled flush (interval `flushIntervalMs`) delivers each window on its boundary.
+
+## Quiet hours (per-subject DND)
+
+Each subject can set a Do-Not-Disturb window; a send during the window is **held** and delivered after (default) or **dropped**:
+
+```ts
+import { NotificationService } from '@voltro/plugin-notifications'
+
+export default (_input, _ctx) => Effect.gen(function* () {
+  const notify = yield* NotificationService
+  // 22:00 → 08:00 in the subject's zone; minutes past local midnight.
+  yield* Effect.promise(() => notify.setQuietHours({
+    subjectId: 'u1', startMinute: 22 * 60, endMinute: 8 * 60, tz: 'Europe/Berlin', policy: 'hold',
+  }))
+  return { ok: true }
+})
+```
+
+Windows may wrap midnight. `policy: 'hold'` defers the send to the window close (delivered by the scheduled flush); `policy: 'drop'` discards it. Subjects self-manage from the browser with `useQuietHours()`.
+
+## Broadcast / topic fan-out
+
+`send` is single-recipient. To reach N subscribers of a topic in one call, subscribe subjects to a topic and `broadcast`:
+
+```ts
+import { NotificationService } from '@voltro/plugin-notifications'
+
+export default (_input, _ctx) => Effect.gen(function* () {
+  const notify = yield* NotificationService
+  yield* Effect.promise(() => notify.subscribe('release-notes', 'u1'))
+  const result = yield* Effect.promise(() => notify.broadcast('release-notes', {
+    category: 'news', title: 'v2 shipped', body: 'Read the changelog.',
+  }))
+  return { recipients: result.recipients } // one call → every subscriber
+})
+```
+
+Each fan-out send still honours that subject's preferences + quiet hours. Subjects self-subscribe from the browser with `useTopicSubscription()`.
+
+## Inbox + preferences (client)
+
+The plugin ships routes — `notifications.inbox`, `unreadCount`, `markRead`, `preferences`, `setPreference`, plus the self-service `subscribe` / `unsubscribe` (topics) and `setQuietHours` / `clearQuietHours` (DND) — and matching hooks:
+
+```tsx
+import {
+  useInbox, useUnreadCount, useMarkRead, useSetNotificationPreference,
+  useTopicSubscription, useQuietHours,
+} from '@voltro/plugin-notifications/web'
+
+const inbox = useInbox()              // InboxItem[]
+const unread = useUnreadCount()       // number — drives the badge
+const markRead = useMarkRead()
+const setPref = useSetNotificationPreference()
+const topics = useTopicSubscription() // { subscribe, unsubscribe }
+const quiet = useQuietHours()         // { set, clear }
+```
+
+> **The plugin OWNS the `notifications.*` route tags** (`notifications.inbox`, `notifications.unreadCount`, `notifications.markRead`, `notifications.preferences`, `notifications.setPreference`, `notifications.subscribe`, `notifications.unsubscribe`, `notifications.setQuietHours`, `notifications.clearQuietHours`). An app must NOT also author its own `notifications.*` procedures — boot **fails** with a tag-collision error. Use the plugin OR hand-roll your own, never both.
+
+## Inbox states — read is not archived
+
+`readAt` and `archivedAt` are two states, not one, and the distinction is the
+one users care about: archiving is what EMPTIES the inbox.
+
+```ts
+notifications.markRead      // one item read
+notifications.markUnread    // …and back again
+notifications.markAllRead   // → { count } — how many CHANGED, not how many exist
+notifications.archive       // out of the inbox
+notifications.unarchive     // back into it
+```
+
+Archiving does **not** mark an item read. An archived-but-unread item still
+counts toward `unreadCount`, so a UI can show what the user actually did rather
+than a state the framework inferred for them.
+
+All five are scoped to the calling subject: an inbox action never reaches
+another subject's row because an id happens to be guessable.
+
+
+## Store
+
+**Durable by default — no config.** The plugin contributes six tables via its `extendSchema` and migrates them automatically: `_voltro_notification_inbox`, `_voltro_notification_preferences`, `_voltro_notification_deliveries`, `_voltro_notification_topic_subscriptions` (broadcast fan-out set), `_voltro_notification_quiet_hours` (per-subject DND window), and `_voltro_notification_held` (the digest/quiet-hours held queue). Once the app's store exists, the plugin auto-binds a `dataStoreNotificationStore` over those tables (via the plugin `bindDataStore` hook) and declares the `store:write` permission for them — so the inbox, per-subject channel preferences, and delivery log all persist to the framework DataStore on every supported dialect.
+
+The append-only tables are bounded by the framework retention sweep: `_voltro_notification_deliveries` (time-TTL, 90d default), `_voltro_notification_inbox` (read-aware — unread items survive, 180d default), and `_voltro_notification_held` (safety-net on `flushAt`, 7d default; the scheduled flush normally drains a held row the moment it is due).
+
+The in-memory store is just the **dev/test fallback** before the DataStore is bound. You only pass an explicit `store` for a **custom** backend:
+
+```ts
+import { dataStoreNotificationStore, memoryNotificationStore } from '@voltro/plugin-notifications'
+
+// dataStoreNotificationStore(store) — the durable default the plugin auto-binds.
+// memoryNotificationStore()         — the in-process dev/test fallback.
+```
+
+The store is the swap point; the service + channels are storage-agnostic.
+
+## Dashboard panel
+
+Both dashboards ship a **Notifications** panel (api apps): the **delivery log** (channel → recipient, category, sent/failed status) with per-channel + sent/failed counts, plus a per-subject **inbox lookup**. Read-only. Backed by `/_voltro/inspect/plugins/notifications/{deliveries,inbox}` (permission `inspect:read`).
+
+## Whose inbox is it — `resolveSubjectId`
+
+```ts
+notificationsPlugin({
+  // Your addressing unit, not ours. An employee, a member, a contact —
+  // something that need not have an auth user. It almost always lives in a
+  // TABLE, so the resolver may be async.
+  resolveSubjectId: (ctx) => resolveCallerEmployeeId(ctx),
+})
+```
+
+By default an inbox belongs to `subject.id`. That is the framework's answer and
+it is not always yours: a shift change, an absence request or a task reminder is
+addressed to a PERSON, and your app may key that person by its own id.
+
+Return your own id here and the whole surface follows — `inbox`, `unreadCount`,
+`markRead`, `archive`, preferences, quiet hours.
+
+### Read this before you reach for it
+
+**The subject is whatever signs in. If your addressing unit is not that, you are
+addressing something nobody can read.**
+
+That sentence was written by the team that adopted this option and then reversed
+it, and it is the correction to an argument this page used to make. The earlier
+version justified `resolveSubjectId` with a measured number: rows belonging to
+people who had no auth user, which employee-keying would "reach" and `subject.id`
+would not. The number was correct and the conclusion was backwards. An inbox
+belongs to whoever can OPEN it, and only an account can open one. Keying by
+employee did not deliver those rows — it made them look addressed, and charged a
+translation on every read path and every push for the privilege.
+
+So the question to ask first is not "what is our addressing unit" but **"can the
+thing I am addressing sign in?"** If it cannot, this option gives you rows nobody
+will ever see. Translate at the SENDING seam instead — once, where the producer
+knows both ids — and leave the inbox keyed by the account.
+
+`resolveSubjectId` remains right for the case it was built for: an app whose
+sign-in identity genuinely IS its own id (a member, a contact, a tenant user)
+rather than the framework's `subject.id`. That is a different situation from
+having a second identity that some accounts happen to map to.
+
+**The resolver may be async, and usually has to be.** An app that has its own
+addressing unit keeps it in a table — an employee, a member and a contact are
+all rows. If the mapping were in the token, this seam would not be needed at
+all: `subject.id` would already be the right id. Return a `string`, a
+`Promise<string>`, or `undefined`/`Promise<undefined>`; a sync resolver still
+works unchanged.
+
+It is deliberately **not cached** for you. A per-connection cache is the obvious
+next step and it is yours to make: the first call would decide the answer for
+the life of the connection, so a member created a second after connect resolves
+to the fallback until reconnect. You know your invalidation; the framework does
+not. Memoise inside your resolver if that trade is right for your app.
+
+Absent keeps `subject.id`, so nothing changes for an app whose units line up.
+Returning `undefined` — or throwing, or a rejected promise, if your resolver
+reaches a database — falls back the same way rather than failing the read.
+
+
+## Permissions
+
+`store:write` (in-app inbox + delivery records) + `inspect:read` (dashboard panel).

package/templates/agent-docs/plugins/openapi.md

@@ -0,0 +1,94 @@
+# OpenAPI
+
+> Generate an OpenAPI 3.1 spec + Swagger-UI docs from your defineRestRoute descriptors and (opt-in) your rpc procedures. Your routes ARE the API docs — nothing hand-maintained.
+
+
+
+---
+
+<!-- source: en/plugins/openapi.md -->
+## OpenAPI
+
+_Generate an OpenAPI 3.1 spec + Swagger-UI docs from your defineRestRoute descriptors and (opt-in) your rpc procedures. Your routes ARE the API docs — nothing hand-maintained._
+
+`@voltro/plugin-openapi` turns your [`defineRestRoute`](/docs/data/rest-routes) descriptors — and, opt-in, your rpc procedures (queries / mutations / actions / streams) — into a live OpenAPI 3.1 document + a Swagger-UI page. The descriptors already carry method, path, input/output Schemas, `summary` and deprecation; the rpc procedures carry input/output/error Schemas. The plugin reads them, so there is **zero hand-written API documentation** to drift.
+
+## Wiring
+
+```ts
+// app.config.ts
+import { openapiPlugin } from '@voltro/plugin-openapi'
+import listCustomers from './routes/v1/customers.list.route'
+import createCharge from './routes/v1/charge.route'
+
+export default {
+  type: 'api' as const, name: 'api',
+  restRoutes: [listCustomers, createCharge],
+  plugins: [
+    openapiPlugin({
+      routes: [listCustomers, createCharge],          // the same descriptors
+      info: { title: 'Payments API', version: '1.0.0' },
+      // specPath: '/openapi.json',  docsPath: '/docs'  (defaults; docsPath:false disables the UI)
+      // token: process.env.OPENAPI_DOCS_TOKEN,  // opt-in Bearer gate (see Permissions)
+    }),
+  ],
+}
+```
+
+Mounts **`GET /openapi.json`** (the spec) and **`GET /docs`** (Swagger UI).
+
+## What it maps
+
+- Each route → an OpenAPI path + operation, keyed by method.
+- The input Schema's `query` fields → `parameters` (in: query); `params` → path params; `body` → a JSON `requestBody`.
+- The output Schema → the `200` JSON response.
+- `summary` / `description` → operation metadata; `deprecated` → `deprecated: true`; `example.request` / `example.response` → request-body / 200-response examples; `sunset` → the `x-sunset` extension.
+- The serve pipeline's real error statuses are documented per operation — `400` (input decode, when the route has an `input` schema), `401`/`403` (when it has `guards`), `410` (when `sunset` is set), `500` (always) — all referencing one shared `components.schemas.VoltroHttpError` envelope.
+- When any route declares `guards`, the document publishes `components.securitySchemes.bearerAuth` and guarded operations carry `security: [{ bearerAuth: [] }]`.
+
+Schemas are converted with effect's `JSONSchema.make`, so your `effect/Schema` definitions become JSON Schema verbatim. Pure: `generateOpenApiSpec(routes, info)` is exported + unit-tested if you want the spec without serving it.
+
+## rpc procedures in the spec
+
+Pass your rpc procedure descriptors via the `procedures` option and each query / mutation / action / stream is projected into the same spec. The framework's rpc surface is a **batched JSON-RPC protocol over one endpoint** (`POST /rpc`) — not a REST-per-resource API — so the projection is honest about that: every procedure becomes a `POST /rpc/<name>` operation whose body is the rpc **payload** (the `input` Schema), tagged `rpc` and flagged with an `x-voltro-rpc` extension. The operation description states the real transport; the path is a documentation projection, not a REST route you call directly.
+
+```ts
+import { openapiPlugin } from '@voltro/plugin-openapi'
+import listOrders from './orders.list.query'
+import createOrder from './orders.create.mutation'
+import charge from './billing.charge.action'
+import runAgent from './agent.run.stream'
+
+openapiPlugin({
+  routes: [listCustomers],                        // REST routes (optional)
+  procedures: [listOrders, createOrder, charge, runAgent],  // rpc procedures
+  info: { title: 'API', version: '1.0.0' },
+})
+```
+
+Per procedure kind:
+
+- **query** → `POST /rpc/<name>`; `input` → requestBody, `output` → the `200` response (documented as the *first snapshot*; the WebSocket rpc channel then pushes reactive updates).
+- **mutation** / **action** → `input` → requestBody, `output` → `200`.
+- **stream** → the `element` Schema is documented as a streaming response (`application/x-ndjson`, one element per line) — **not** faked as a single JSON value.
+- The procedure's **typed error channel** (its `Schema.TaggedError` union) becomes a `422` response referencing the error schema; a procedure with no declared error documents only `200` + `500`.
+
+Mixing rpc + REST in one spec is fine — the rpc operations are grouped under the `rpc` tag and flagged `x-voltro-rpc`, so a consumer can tell them apart from real REST routes. `procedures` is opt-in: omit it to keep the spec REST-only.
+
+## Access control
+
+Both routes publish your full API contract (every path, param, and schema), and both are **unauthenticated by default** — mount them only where that's intended. Two levers narrow the surface:
+
+- `docsPath: false` hides only the Swagger-UI viewer; the spec at `/openapi.json` stays served.
+- `token` (or the `OPENAPI_DOCS_TOKEN` env var) requires `Authorization: Bearer <token>` on **both** routes — a missing or mismatched header gets a `401`. The same shape as [`@voltro/plugin-prometheus`](/docs/plugins/prometheus)'s gate. Leave it unset behind a trusted network boundary; set it for a public-internet deployment.
+
+```ts
+openapiPlugin({
+  routes: [listCustomers, createCharge],
+  token: process.env.OPENAPI_DOCS_TOKEN,   // unset → both routes are public
+})
+```
+
+## Permissions
+
+The plugin declares no runtime permissions — it only mounts the two GET routes built from descriptors you already declared.

package/templates/agent-docs/plugins/postgis.md

@@ -0,0 +1,140 @@
+# PostGIS
+
+> Postgres-native geography / geometry columns, geometry constructors (point/line/polygon/multi/GeoJSON), spatial predicates (ST_DWithin, ST_Within, ST_Contains, ST_Intersects, ST_Buffer, bbox &&), ST_Distance projection + <-> KNN ordering, and GiST indexes via expressionIndex. Postgres-only by design.
+
+
+
+---
+
+<!-- source: en/plugins/postgis.md -->
+## PostGIS
+
+_Postgres-native geography / geometry columns, geometry constructors (point/line/polygon/multi/GeoJSON), spatial predicates (ST_DWithin, ST_Within, ST_Contains, ST_Intersects, ST_Buffer, bbox &&), ST_Distance projection + <-> KNN ordering, and GiST indexes via expressionIndex. Postgres-only by design._
+
+`@voltro/plugin-postgis` adds postgres-native spatial column types and operators to the schema DSL. PostGIS is a postgres extension with no portable cross-dialect equivalent, so the plugin is **postgres-only** — a `geography()`/`geometry()` column FAILS LOUD at schema emission (`voltro migrate` / auto-migrate throws a `postgres-only` error) on any other dialect, and a spatial predicate throws in the SQL compiler.
+
+**Status:** ✓ shipped.
+
+## Columns — `geography` / `geometry`
+
+```ts
+import { table, id, text } from '@voltro/database'
+import { geography } from '@voltro/plugin-postgis'
+
+export const venues = table('venues', {
+  id:       id(),
+  name:     text(),
+  // SRID 4326 = WGS-84 lat/lon. Most common for global apps.
+  location: geography('Point', 4326),
+})
+```
+
+- **`geography(kind, srid)`** — spheroid-aware coordinates; distance calculations honour the earth's curvature. Use for global apps with WGS-84 lat/lon (SRID 4326).
+- **`geometry(kind, srid)`** — planar (cartesian) coordinates; distance is straight-line in the SRID's reference frame. Use for local apps with projected coordinates (e.g. a UTM zone for one country).
+
+`kind` is `'Point' | 'LineString' | 'Polygon' | 'MultiPoint' | 'MultiLineString' | 'MultiPolygon' | 'GeometryCollection'`. On postgres the migrator emits the real `geography(Point,4326)` DDL plus a one-time `CREATE EXTENSION IF NOT EXISTS postgis`; on any other dialect schema emission throws.
+
+## Value constructors
+
+These build PostGIS WKT/EWKT (well-known text) values that the SQL compiler binds as literals; postgres' implicit text→geometry cast parses them at insert time. Coordinates are `[lon, lat]` (x before y) throughout.
+
+```ts
+import { point, lineString, polygon, multiPoint, multiLineString, multiPolygon, geoJson } from '@voltro/plugin-postgis'
+
+await ctx.store.insert('venues', {
+  name:     'HQ',
+  location: point(8.682, 50.110, 4326),   // (lon, lat, srid) — Frankfurt
+})
+
+// A path / route.
+const route = lineString([[8.68, 50.11], [8.69, 50.12], [8.70, 50.13]], 4326)
+
+// polygon(rings, srid) — each ring is an array of [lon, lat] tuples; the first
+// ring is the exterior, the rest are holes; each ring MUST be closed.
+const area = polygon([[[8.6, 50.1], [8.7, 50.1], [8.7, 50.2], [8.6, 50.1]]], 4326)
+
+// Multi-geometries.
+const cluster = multiPoint([[8.68, 50.11], [8.70, 50.13]], 4326)
+const lines   = multiLineString([[[8.68, 50.11], [8.69, 50.12]]], 4326)
+const zones   = multiPolygon([[[[8.6, 50.1], [8.7, 50.1], [8.7, 50.2], [8.6, 50.1]]]], 4326)
+
+// GeoJSON input — lowered to the same EWKT (SRID 4326 by the GeoJSON spec).
+const fromGeoJson = geoJson({ type: 'Point', coordinates: [8.682, 50.110] })
+```
+
+## Spatial predicates
+
+```ts
+import { queryFor } from '@voltro/database'
+import { ST_DWithin, ST_Within, ST_Contains, ST_Intersects, ST_Buffer, bboxOverlaps, point, polygon, envelope } from '@voltro/plugin-postgis'
+
+// Venues within 1km of a target point (meters; great-circle on geography).
+await ctx.store.query(
+  queryFor(venues)
+    .where(ST_DWithin('location', point(8.682, 50.110, 4326), 1000))
+    .descriptor,
+)
+
+const cityCenter = polygon([[[8.65, 50.10], [8.72, 50.10], [8.72, 50.13], [8.65, 50.13], [8.65, 50.10]]], 4326)
+
+// Points that lie INSIDE a polygon (the column is within the geom).
+queryFor(venues).where(ST_Within('location', cityCenter))
+
+// A region column that fully CONTAINS a point (column-first, always).
+queryFor(regions).where(ST_Contains('boundary', point(8.682, 50.110, 4326)))
+
+// Everything a 500 m buffer around a route touches.
+queryFor(venues).where(ST_Buffer('location', point(8.682, 50.110, 4326), 500))
+
+// Coarse, index-only bounding-box overlap — pair with an exact predicate or use alone.
+queryFor(venues).where(bboxOverlaps('location', envelope(8.6, 50.05, 8.75, 50.15, 4326)))
+```
+
+- **`ST_DWithin(column, geom, meters)`** — `column` is within `meters` of `geom` (metric distance; the column is cast to `geography`).
+- **`ST_Within(column, geom)`** — `column`'s geometry is fully inside `geom` (the converse of `ST_Contains`). The right shape for "rows inside this polygon".
+- **`ST_Contains(column, geom)`** — `column`'s geometry fully contains `geom`.
+- **`ST_Intersects(column, geom)`** — `column`'s geometry shares any point with `geom`.
+- **`ST_Buffer(column, geom, meters)`** — `column` intersects the `geom` grown by `meters` (a metric buffer via a geography round-trip). Shape-aware "within N metres of a line/polygon".
+- **`bboxOverlaps(column, geom)`** — the `&&` bounding-box overlap operator: cheap, GiST-index-only, approximate. Build the box with `envelope(minLon, minLat, maxLon, maxLat, srid)`.
+
+Spatial predicates are for one-shot `ctx.store.query` reads — they throw in the in-memory reactive matcher, so don't use them in subscriptions.
+
+## Distance projection + KNN ordering
+
+`withDistance(...)` and `nearestBy(...)` are `QueryTransform`s applied via the builder's `.use(...)` seam (same mechanism as `hybridSearch`), so they compose with `.where(...)`, `.limit(k)`, and the spatial predicates. Postgres-only — the compiler throws on other dialects.
+
+```ts
+import { queryFor } from '@voltro/database'
+import { withDistance, nearestBy, ST_DWithin, point } from '@voltro/plugin-postgis'
+
+// Distance-as-a-value: project ST_Distance in METRES onto each row.
+const withMeters = await ctx.store.query(
+  queryFor(venues)
+    .use(withDistance('location', point(8.682, 50.110), { as: 'meters' }))
+    .where(ST_DWithin('location', point(8.682, 50.110), 5000))
+    .descriptor,
+)
+// withMeters[i].meters === distance in metres
+
+// KNN: the k nearest venues via the indexed `<->` operator.
+const nearest5 = await ctx.store.query(
+  queryFor(venues)
+    .use(nearestBy('location', point(8.682, 50.110)))
+    .limit(5)
+    .descriptor,
+)
+```
+
+- **`withDistance(column, geom, { as?, useGeography? })`** — surfaces `ST_Distance(column, geom) AS "<alias>"` (default alias `distance`). Metric metres by default; pass `{ useGeography: false }` for planar SRID-unit distance.
+- **`nearestBy(column, geom, { direction? })`** — orders by `column <-> geom` (the KNN operator; leads any explicit `.orderBy(...)`). Pair with `.limit(k)` for `ORDER BY geom <-> point LIMIT k` — an indexed nearest-neighbour scan when a GiST index covers the column. `<->` is planar; add `withDistance` too if you need a metric distance value.
+
+## GiST index
+
+A regular B-tree index is useless for spatial queries — declare a GiST index, the PostGIS-recommended access method, via the framework's `.expressionIndex(...)` with `{ kind: 'gist' }`:
+
+```ts
+table('venues', { id: id(), location: geography('Point', 4326) })
+  .expressionIndex('venues_loc_gist', [{ expr: '"location"' }], { kind: 'gist' })
+```
+
+On postgres this emits `CREATE INDEX … USING GIST` natively. Other dialects warn and fall back to a B-tree (which won't accelerate spatial predicates) — another reason this plugin is postgres-first.