@voltro/cli 0.4.0 → 0.6.0

package/dist/serveEntry.js

@@ -1,4 +1,4 @@
-import { jt as e, rt as t } from "./dev-CQxbrpDz.js";
+import { Lt as e, lt as t } from "./dev-Bjq-nIvH.js";
 import { a as n } from "./startupRunner-DhlX9nqd.js";
-import { t as r } from "./serveCommand-BZzUJIyo.js";
+import { t as r } from "./serveCommand-C-XQ89NJ.js";
 export { e as loadDotEnv, n as registerAppModules, t as registerDriver, r as runServe };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -31,6 +31,11 @@
       "import": "./dist/inspectState.js",
       "default": "./dist/inspectState.js"
     },
+    "./devActivity": {
+      "types": "./dist/devActivity.d.ts",
+      "import": "./dist/devActivity.js",
+      "default": "./dist/devActivity.js"
+    },
     "./startup": {
       "types": "./dist/startup.d.ts",
       "import": "./dist/startup.js",
@@ -52,22 +57,22 @@
     "@effect/platform-node": "^0.107.0",
     "@effect/sql": "^0.51.1",
     "@effect/workflow": "^0.18.2",
-    "@voltro/ai": "0.4.0",
-    "@voltro/cache": "0.4.0",
-    "@voltro/data-transfer": "0.4.0",
-    "@voltro/database": "0.4.0",
-    "@voltro/env": "0.4.0",
-    "@voltro/kv": "0.4.0",
-    "@voltro/logger": "0.4.0",
-    "@voltro/plugin-auth": "0.4.0",
-    "@voltro/plugin-broadcast": "0.4.0",
-    "@voltro/plugin-mail": "0.4.0",
-    "@voltro/plugin-storage": "0.4.0",
-    "@voltro/plugin-webhooks": "0.4.0",
-    "@voltro/protocol": "0.4.0",
-    "@voltro/runtime": "0.4.0",
-    "@voltro/serverless": "0.4.0",
-    "@voltro/workflow": "0.4.0",
+    "@voltro/ai": "0.6.0",
+    "@voltro/cache": "0.6.0",
+    "@voltro/data-transfer": "0.6.0",
+    "@voltro/database": "0.6.0",
+    "@voltro/env": "0.6.0",
+    "@voltro/kv": "0.6.0",
+    "@voltro/logger": "0.6.0",
+    "@voltro/plugin-auth": "0.6.0",
+    "@voltro/plugin-broadcast": "0.6.0",
+    "@voltro/plugin-mail": "0.6.0",
+    "@voltro/plugin-storage": "0.6.0",
+    "@voltro/plugin-webhooks": "0.6.0",
+    "@voltro/protocol": "0.6.0",
+    "@voltro/runtime": "0.6.0",
+    "@voltro/serverless": "0.6.0",
+    "@voltro/workflow": "0.6.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "ts-morph": "^28.0.0"

package/templates/AGENTS.core.md

@@ -61,6 +61,100 @@ Ask in order; stop at the first "yes":
 Deep dive: **`data.md`** (queries/mutations/actions/streams/errors),
 **`workflows.md`**, **`scheduling.md`**.
 
+### Pick the SERVER primitive (inside a handler)
+
+The four above answer "which FILE do I write". This answers "what do I write
+INSIDE it" — the part where hand-rolled boilerplate actually accumulates. Every
+line below replaces something real apps write by hand hundreds of times.
+
+1. **Loading one row you expect to exist?** → **`.one()`**
+   (`ctx.store.select('t').where('id', x).one()`). It fails with the typed
+   `NoRowFound` when there is no row — AND when there is more than one, so a
+   filter that stops being unique fails loudly instead of returning an
+   arbitrary row. `NoRowFound` is declarable in the descriptor's `error:` union.
+   Nullable variant: **`.first()`** / **`.maybeOne()`**.
+   Never `const rows = await …; if (!rows[0]) throw new NotFound()`.
+2. **Need related data — 2+ reads to assemble one result?** → declare
+   **`relations()`** (`*.relations.ts`) and eager-load with **`.with({ posts: true })`**.
+   That compiles to ONE JSON-aggregate query on every SQL dialect. Sequential
+   `store.query` calls per parent row are an N+1 you are writing on purpose.
+3. **Something must happen AFTER a mutation commits** (notify, webhook, sync)?
+   → **`defineSubscriber`** (`*.subscribe.ts`, runs any handler on a table
+   change) or **`defineReaction`** (`*.reaction.tsx`, fires a named agent or
+   workflow; requires a `dedupeKey`, supports `rateLimit` / `costBudgetUsd`).
+   Both are post-commit and receive the `old`/`new` diff. Calling a
+   notify-helper at the tail of the mutation body instead makes the reactivity
+   invisible — you can only find it by reading every executor. Both are
+   best-effort, so genuinely critical delivery still belongs in a workflow.
+4. **A roll-up / counter recomputed on every read?** → **`defineAggregate`**
+   (`*.aggregate.ts`). Add `incremental:` for `count|sum|avg|min|max` group-bys
+   and it is MAINTAINED on write rather than recomputed. `read({ where })`
+   parameterises it, so one aggregate serves per-team / per-period slices.
+5. **A permission check?** → declare **`guards:`** on the descriptor — it is
+   enforced before the executor (and before a mutation's transaction opens) and
+   fails with a typed `ScopeError`. Two kinds, same array, all must pass:
+   - `{ scope: 'notes:write' }` — may the caller do this AT ALL.
+   - `{ action, resourceType, resource: (input) => input.id }` — may they do it
+     to THIS ROW (relationship/ReBAC, against a `defineResourcePolicy`). Needs a
+     registered `setTupleSource`; **everything unanswerable DENIES** (no source,
+     no policy, no id, source throws).
+   Guards are re-checked on every subscription delivery, so a revoked grant ends
+   the stream instead of continuing to push rows. Only use `ctx.access`
+   in-handler for checks that need LOADED data. A hand-written `requireScope(...)`
+   at the top of every executor — or a hand-kept map from rpc tag to policy rule,
+   which is fail-open by omission — is what `guards:` exists to delete.
+6. **Storing a token, secret, or credential in a column?** → **`.encrypted()`**
+   on the column. Boot fails loudly if no cipher is configured, so an
+   `.encrypted()` column can never silently persist plaintext.
+7. **Writing an Effect-form handler?** → `const store = yield* EffectStore` —
+   its failures land on the typed error channel. `Effect.promise(() =>
+   ctx.store.query(…))` throws that channel away and turns a store failure into
+   a defect.
+8. **Cursor pagination?** → **`paginateBy(descriptor, column, cursor, limit,
+   direction?)`** (or **`paginateById`**, its `id`-column shorthand). Not a
+   hand-rolled limit+1 / slice / `hasMore` triple. `direction` flips the
+   COMPARISON as well as the sort — a `desc` feed pages with `<`.
+9. **Assembling data whose SHAPE depends on the data** (a tree walk where each
+   level's ids come from the level above)? → **`ctx.load` / `ctx.loadMany`** —
+   same-tick reads of one table coalesce into one `WHERE id IN (...)`, so the
+   walk costs one query per LEVEL. Use `relations()` + `.with()` whenever the
+   shape IS static; this is the fallback, not the default.
+10. **A mutation must cause an EXTERNAL side effect** (webhook, Jira sync,
+   payment)? → **`ctx.outbox.enqueue(effect, payload)`** + a
+   **`defineOutboxHandler`** in a `*.outbox.ts`. The enqueue writes through the
+   mutation's TRANSACTION, so the intent commits with the write or not at all;
+   delivery happens after commit, with backoff and a dead-letter. Do NOT call
+   the remote from the mutation (not transactional), and do not hand-build a
+   deliveries table + drain cron — that IS this primitive.
+11. **Calling a third party ON BEHALF OF A USER** (their Jira token, their Slack
+   grant)? → **`defineConnection({ id, kind: 'oauth2' | 'pat' })`** in a
+   `*.connection.ts`, then **`ctx.connections.get(id)`**. One declaration yields
+   the encrypted per-user token store, the OAuth authorize/callback pair,
+   refresh-before-use, and the `useConnection` + `<ConnectAccount>` connect UI.
+   The credential is bound to the REQUEST's subject — there is no parameter for
+   another subject. Do NOT hand-build a per-user token table, an OAuth action
+   pair, or a "credentials resolver" over your own schema.
+
+| You're about to write | Reach for instead |
+|---|---|
+| `const rows = …; if (!rows[0]) throw new NotFound()` | `.one()` |
+| 3+ sequential `store.query` to assemble related data | `relations()` + `.with()` |
+| a notify/webhook helper called at the end of a mutation | `defineSubscriber` / `defineReaction` |
+| a counter recomputed by scanning rows on every read | `defineAggregate` (+ `incremental:`) |
+| `requireScope(...)` as the first line of every executor | `guards:` on the descriptor |
+| a token/secret column written as plain text | `.encrypted()` |
+| `Effect.promise(() => ctx.store.query(...))` in an Effect handler | `yield* EffectStore` |
+| hand-rolled limit+1 / `hasMore` cursor paging | `paginateBy` / `paginateById` |
+| a loop issuing one `store.query` per node of a walk | `ctx.load` / `ctx.loadMany` |
+| a deliveries table + drain cron + retry worker | `ctx.outbox.enqueue` + `defineOutboxHandler` |
+| a per-user `integrationTokens` table + OAuth actions + a refresh check | `defineConnection` + `ctx.connections.get(id)` |
+| `row['name'] as string` on every field you read | nothing — `ctx.store.query(database.t….descriptor)` already returns the table's row type. A cast here means the descriptor was hand-built, or you are casting out of habit |
+
+Deep dive: **`data.md`** (`.one()`, subscribers, reactions, aggregates),
+**`database/querying.md`** (relations + `.with`), **`authentication.md`**
+(`guards:`, resource policies), **`plugins/governance.md`** (`.encrypted()`),
+**`data.md`** (`defineConnection`, the credentials vault).
+
 ### Pick the CLIENT primitive (decision rubric)
 
 `useSubscription` / `useMutation` / `useAction` are the transport — they are NOT
@@ -180,6 +274,31 @@ export default { type: 'web' as const, name: 'myWeb',
 Env, secrets, auth strategies, layers, plugins config → **`configuration.md`**.
 `store: 'memory'` loses data on restart — default to `postgres` for real work.
 
+**NEVER hardcode a secret, not even as a fallback.** Not
+`process.env.X ?? 'dev-only-change-me'`, not a value committed to `.env`. A
+hardcoded fallback means every environment that forgot to configure the
+variable shares one key that is readable by anyone with the repo — and it looks
+completely healthy until someone forges a session. Declare it instead:
+
+```ts
+env: defineEnv({
+  VOLTRO_SESSION_SECRET: envVar.secret({ generate: 'base64url' }),  // ours → minted
+  STRIPE_SECRET_KEY:     envVar.secret({ minLength: 20 }),          // theirs → must be set
+})
+```
+
+`generate` makes `voltro dev` mint a unique per-project value into a gitignored
+`.env.local` on first boot, so local development needs no placeholder at all.
+Omit it for third-party credentials — an invented API key authenticates nobody,
+and failing the boot gate is the useful outcome. Deployment values come from
+`voltro secret generate <purpose>`; `voltro serve` refuses to start without them.
+
+Also: don't read `process.env` for a secret at config time to pass it to a
+plugin. `app.config.ts` is evaluated BEFORE the env gate and before minting, so
+that read is what pushes you into writing a fallback. `authRoutesPlugin` and
+`voltroPasswordStrategy` resolve `VOLTRO_SESSION_SECRET` themselves — omit
+`secret:` entirely.
+
 ## The browser/server boundary (load-bearing — verify when you touch it)
 
 Codegen pulls every **descriptor** (`*.query.ts` / `*.mutation.ts` /

package/templates/AGENTS.md

@@ -61,6 +61,100 @@ Ask in order; stop at the first "yes":
 Deep dive: **`data.md`** (queries/mutations/actions/streams/errors),
 **`workflows.md`**, **`scheduling.md`**.
 
+### Pick the SERVER primitive (inside a handler)
+
+The four above answer "which FILE do I write". This answers "what do I write
+INSIDE it" — the part where hand-rolled boilerplate actually accumulates. Every
+line below replaces something real apps write by hand hundreds of times.
+
+1. **Loading one row you expect to exist?** → **`.one()`**
+   (`ctx.store.select('t').where('id', x).one()`). It fails with the typed
+   `NoRowFound` when there is no row — AND when there is more than one, so a
+   filter that stops being unique fails loudly instead of returning an
+   arbitrary row. `NoRowFound` is declarable in the descriptor's `error:` union.
+   Nullable variant: **`.first()`** / **`.maybeOne()`**.
+   Never `const rows = await …; if (!rows[0]) throw new NotFound()`.
+2. **Need related data — 2+ reads to assemble one result?** → declare
+   **`relations()`** (`*.relations.ts`) and eager-load with **`.with({ posts: true })`**.
+   That compiles to ONE JSON-aggregate query on every SQL dialect. Sequential
+   `store.query` calls per parent row are an N+1 you are writing on purpose.
+3. **Something must happen AFTER a mutation commits** (notify, webhook, sync)?
+   → **`defineSubscriber`** (`*.subscribe.ts`, runs any handler on a table
+   change) or **`defineReaction`** (`*.reaction.tsx`, fires a named agent or
+   workflow; requires a `dedupeKey`, supports `rateLimit` / `costBudgetUsd`).
+   Both are post-commit and receive the `old`/`new` diff. Calling a
+   notify-helper at the tail of the mutation body instead makes the reactivity
+   invisible — you can only find it by reading every executor. Both are
+   best-effort, so genuinely critical delivery still belongs in a workflow.
+4. **A roll-up / counter recomputed on every read?** → **`defineAggregate`**
+   (`*.aggregate.ts`). Add `incremental:` for `count|sum|avg|min|max` group-bys
+   and it is MAINTAINED on write rather than recomputed. `read({ where })`
+   parameterises it, so one aggregate serves per-team / per-period slices.
+5. **A permission check?** → declare **`guards:`** on the descriptor — it is
+   enforced before the executor (and before a mutation's transaction opens) and
+   fails with a typed `ScopeError`. Two kinds, same array, all must pass:
+   - `{ scope: 'notes:write' }` — may the caller do this AT ALL.
+   - `{ action, resourceType, resource: (input) => input.id }` — may they do it
+     to THIS ROW (relationship/ReBAC, against a `defineResourcePolicy`). Needs a
+     registered `setTupleSource`; **everything unanswerable DENIES** (no source,
+     no policy, no id, source throws).
+   Guards are re-checked on every subscription delivery, so a revoked grant ends
+   the stream instead of continuing to push rows. Only use `ctx.access`
+   in-handler for checks that need LOADED data. A hand-written `requireScope(...)`
+   at the top of every executor — or a hand-kept map from rpc tag to policy rule,
+   which is fail-open by omission — is what `guards:` exists to delete.
+6. **Storing a token, secret, or credential in a column?** → **`.encrypted()`**
+   on the column. Boot fails loudly if no cipher is configured, so an
+   `.encrypted()` column can never silently persist plaintext.
+7. **Writing an Effect-form handler?** → `const store = yield* EffectStore` —
+   its failures land on the typed error channel. `Effect.promise(() =>
+   ctx.store.query(…))` throws that channel away and turns a store failure into
+   a defect.
+8. **Cursor pagination?** → **`paginateBy(descriptor, column, cursor, limit,
+   direction?)`** (or **`paginateById`**, its `id`-column shorthand). Not a
+   hand-rolled limit+1 / slice / `hasMore` triple. `direction` flips the
+   COMPARISON as well as the sort — a `desc` feed pages with `<`.
+9. **Assembling data whose SHAPE depends on the data** (a tree walk where each
+   level's ids come from the level above)? → **`ctx.load` / `ctx.loadMany`** —
+   same-tick reads of one table coalesce into one `WHERE id IN (...)`, so the
+   walk costs one query per LEVEL. Use `relations()` + `.with()` whenever the
+   shape IS static; this is the fallback, not the default.
+10. **A mutation must cause an EXTERNAL side effect** (webhook, Jira sync,
+   payment)? → **`ctx.outbox.enqueue(effect, payload)`** + a
+   **`defineOutboxHandler`** in a `*.outbox.ts`. The enqueue writes through the
+   mutation's TRANSACTION, so the intent commits with the write or not at all;
+   delivery happens after commit, with backoff and a dead-letter. Do NOT call
+   the remote from the mutation (not transactional), and do not hand-build a
+   deliveries table + drain cron — that IS this primitive.
+11. **Calling a third party ON BEHALF OF A USER** (their Jira token, their Slack
+   grant)? → **`defineConnection({ id, kind: 'oauth2' | 'pat' })`** in a
+   `*.connection.ts`, then **`ctx.connections.get(id)`**. One declaration yields
+   the encrypted per-user token store, the OAuth authorize/callback pair,
+   refresh-before-use, and the `useConnection` + `<ConnectAccount>` connect UI.
+   The credential is bound to the REQUEST's subject — there is no parameter for
+   another subject. Do NOT hand-build a per-user token table, an OAuth action
+   pair, or a "credentials resolver" over your own schema.
+
+| You're about to write | Reach for instead |
+|---|---|
+| `const rows = …; if (!rows[0]) throw new NotFound()` | `.one()` |
+| 3+ sequential `store.query` to assemble related data | `relations()` + `.with()` |
+| a notify/webhook helper called at the end of a mutation | `defineSubscriber` / `defineReaction` |
+| a counter recomputed by scanning rows on every read | `defineAggregate` (+ `incremental:`) |
+| `requireScope(...)` as the first line of every executor | `guards:` on the descriptor |
+| a token/secret column written as plain text | `.encrypted()` |
+| `Effect.promise(() => ctx.store.query(...))` in an Effect handler | `yield* EffectStore` |
+| hand-rolled limit+1 / `hasMore` cursor paging | `paginateBy` / `paginateById` |
+| a loop issuing one `store.query` per node of a walk | `ctx.load` / `ctx.loadMany` |
+| a deliveries table + drain cron + retry worker | `ctx.outbox.enqueue` + `defineOutboxHandler` |
+| a per-user `integrationTokens` table + OAuth actions + a refresh check | `defineConnection` + `ctx.connections.get(id)` |
+| `row['name'] as string` on every field you read | nothing — `ctx.store.query(database.t….descriptor)` already returns the table's row type. A cast here means the descriptor was hand-built, or you are casting out of habit |
+
+Deep dive: **`data.md`** (`.one()`, subscribers, reactions, aggregates),
+**`database/querying.md`** (relations + `.with`), **`authentication.md`**
+(`guards:`, resource policies), **`plugins/governance.md`** (`.encrypted()`),
+**`data.md`** (`defineConnection`, the credentials vault).
+
 ### Pick the CLIENT primitive (decision rubric)
 
 `useSubscription` / `useMutation` / `useAction` are the transport — they are NOT
@@ -180,6 +274,31 @@ export default { type: 'web' as const, name: 'myWeb',
 Env, secrets, auth strategies, layers, plugins config → **`configuration.md`**.
 `store: 'memory'` loses data on restart — default to `postgres` for real work.
 
+**NEVER hardcode a secret, not even as a fallback.** Not
+`process.env.X ?? 'dev-only-change-me'`, not a value committed to `.env`. A
+hardcoded fallback means every environment that forgot to configure the
+variable shares one key that is readable by anyone with the repo — and it looks
+completely healthy until someone forges a session. Declare it instead:
+
+```ts
+env: defineEnv({
+  VOLTRO_SESSION_SECRET: envVar.secret({ generate: 'base64url' }),  // ours → minted
+  STRIPE_SECRET_KEY:     envVar.secret({ minLength: 20 }),          // theirs → must be set
+})
+```
+
+`generate` makes `voltro dev` mint a unique per-project value into a gitignored
+`.env.local` on first boot, so local development needs no placeholder at all.
+Omit it for third-party credentials — an invented API key authenticates nobody,
+and failing the boot gate is the useful outcome. Deployment values come from
+`voltro secret generate <purpose>`; `voltro serve` refuses to start without them.
+
+Also: don't read `process.env` for a secret at config time to pass it to a
+plugin. `app.config.ts` is evaluated BEFORE the env gate and before minting, so
+that read is what pushes you into writing a fallback. `authRoutesPlugin` and
+`voltroPasswordStrategy` resolve `VOLTRO_SESSION_SECRET` themselves — omit
+`secret:` entirely.
+
 ## The browser/server boundary (load-bearing — verify when you touch it)
 
 Codegen pulls every **descriptor** (`*.query.ts` / `*.mutation.ts` /

package/templates/agent-docs/_manifest.json

@@ -17,7 +17,7 @@
       "group": null,
       "description": "How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol.",
       "path": "agent-docs/authentication.md",
-      "files": 11
+      "files": 12
     },
     {
       "id": "caching",
@@ -53,7 +53,7 @@
       "group": null,
       "description": "How Voltro's reactive data layer works — queries, mutations, actions, streams, all over one WebSocket with typed errors and tracked dependencies.",
       "path": "agent-docs/data.md",
-      "files": 13
+      "files": 15
     },
     {
       "id": "database/advancedqueries",
@@ -161,7 +161,7 @@
       "group": null,
       "description": "Voltro Cloud (coming soon) — the managed runtime for your Voltro project. Today the Free control plane registers + observes your self-hosted apps.",
       "path": "agent-docs/deployment.md",
-      "files": 6
+      "files": 7
     },
     {
       "id": "internationalization",

package/templates/agent-docs/ai.md

@@ -438,7 +438,18 @@ So one agent can run GPT-5.5 on a dedicated key while another inherits the env d
 **Model picker / routing** — the input selects among server-owned configs (UI picker, cost/size routing, plan tiers):
 
 ```tsx
-// descriptor: input: Schema.Struct({ prompt: Schema.String, tier: Schema.Literal('fast', 'smart') })
+// support.agent.tsx — DESCRIPTOR: the picker is constrained to server-known tiers
+import { defineAgent } from '@voltro/ai/agent'
+import { Schema } from 'effect'
+
+export const support = defineAgent({
+  name:  'support',
+  input: Schema.Struct({ prompt: Schema.String, tier: Schema.Literal('fast', 'smart') }),
+})
+
+// support.agent.server.tsx — EXECUTOR: map the tier onto server-owned configs
+import { defineAgentExecutor } from '@voltro/ai'
+
 export default defineAgentExecutor(support, {
   model: (input) => input.tier === 'smart'
     ? { name: 'openai', model: 'gpt-5.5' }
@@ -449,7 +460,18 @@ export default defineAgentExecutor(support, {
 **BYOK (bring your own key)** — the caller supplies their OWN key; you fold it into the returned config:
 
 ```tsx
-// descriptor: input: Schema.Struct({ prompt: Schema.String, apiKey: Schema.String })
+// support.agent.tsx — DESCRIPTOR: the caller's own key is part of the input
+import { defineAgent } from '@voltro/ai/agent'
+import { Schema } from 'effect'
+
+export const support = defineAgent({
+  name:  'support',
+  input: Schema.Struct({ prompt: Schema.String, apiKey: Schema.String }),
+})
+
+// support.agent.server.tsx — EXECUTOR: fold the caller's key into the config
+import { defineAgentExecutor } from '@voltro/ai'
+
 export default defineAgentExecutor(support, {
   model: (input) => ({ name: 'openai', model: 'gpt-5.5', apiKey: input.apiKey }),
 })
@@ -505,10 +527,20 @@ System prompts go in the agent definition's `system` field, NOT in the messages
 The `system` field lives on the **executor**. Template it with per-call values (locale, persona, plan-specific instructions) — the function receives the input typed from the descriptor's schema:
 
 ```tsx
+// support.agent.tsx — DESCRIPTOR: every field `system` reads must be declared here
+import { defineAgent } from '@voltro/ai/agent'
+import { Schema } from 'effect'
+
+export const support = defineAgent({
+  name:  'support',
+  input: Schema.Struct({ prompt: Schema.String, plan: Schema.optional(Schema.String) }),
+})
+
 // support.agent.server.tsx — `plan` comes from the descriptor's input schema
+import { defineAgentExecutor } from '@voltro/ai'
+
 export default defineAgentExecutor(support, {
   system: (input) => `You are speaking with a user on the ${input.plan ?? 'free'} plan.`,
-  // …
 })
 ```
 
@@ -1717,6 +1749,7 @@ export const ask = defineAction({
 ```ts
 // copilot.ask.action.server.ts — the server executor (imports @voltro/ai)
 import { Effect } from 'effect'
+import { EffectStore } from '@voltro/runtime'
 import { runDataCopilot, generateObject, CopilotProposalSchema, type CopilotSchema } from '@voltro/ai'
 
 // The manifest the model is constrained to — only these tables/columns exist.
@@ -1729,6 +1762,7 @@ const schema: CopilotSchema = {
 
 const execute = (input: { question: string }, ctx: AppContext) =>
   Effect.gen(function* () {
+    const store = yield* EffectStore
     const v = yield* Effect.promise(() =>
       runDataCopilot(input.question, schema, {
         propose: ({ system, prompt }) =>
@@ -1739,13 +1773,15 @@ const execute = (input: { question: string }, ctx: AppContext) =>
     )
     if (!v.ok) return { ok: false as const, reason: v.rejection.reason }
     // The validated SELECT runs AS the subject → tenant + row scope apply.
-    const rows = yield* Effect.promise(() => ctx.store.query(v.descriptor as never))
-    return { ok: true as const, rows: rows as ReadonlyArray<Record<string, unknown>> }
+    const rows = yield* store.query(v.descriptor)
+    return { ok: true as const, rows }
   })
 
 export default execute
 ```
 
+`v.descriptor` is already a `QueryDescriptor`, so nothing needs casting. In an Effect-form executor read through `EffectStore` (`yield* EffectStore`) rather than lifting `ctx.store.query` with `Effect.promise` — the lift discards the typed `StoreError` channel that `store.query` gives you.
+
 ## Client: `useDataCopilot` + `<DataCopilot>`
 
 The hook is a thin binding over `useAction` — it imports **nothing** from