@voltro/cli 0.27.0 → 0.28.0

package/dist/serveEntry.js

@@ -1,5 +1,5 @@
 import { Z as e } from "./inspectMetrics-BU90mvJN.js";
-import { c as t } from "./seedRunner-D6eu-u5U.js";
+import { c as t } from "./seedRunner-Bqxgp7HZ.js";
 import { r as n } from "./appModuleLoader-C9r9mxZt.js";
-import { t as r } from "./serveCommand-DfkisVWP.js";
+import { t as r } from "./serveCommand-ZTn-dPFa.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.27.0",
+  "version": "0.28.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -62,22 +62,22 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.27.0",
-    "@voltro/cache": "0.27.0",
-    "@voltro/data-transfer": "0.27.0",
-    "@voltro/database": "0.27.0",
-    "@voltro/env": "0.27.0",
-    "@voltro/kv": "0.27.0",
-    "@voltro/logger": "0.27.0",
-    "@voltro/plugin-auth": "0.27.0",
-    "@voltro/plugin-broadcast": "0.27.0",
-    "@voltro/plugin-mail": "0.27.0",
-    "@voltro/plugin-storage": "0.27.0",
-    "@voltro/plugin-webhooks": "0.27.0",
-    "@voltro/protocol": "0.27.0",
-    "@voltro/runtime": "0.27.0",
-    "@voltro/serverless": "0.27.0",
-    "@voltro/workflow": "0.27.0",
+    "@voltro/ai": "0.28.0",
+    "@voltro/cache": "0.28.0",
+    "@voltro/data-transfer": "0.28.0",
+    "@voltro/database": "0.28.0",
+    "@voltro/env": "0.28.0",
+    "@voltro/kv": "0.28.0",
+    "@voltro/logger": "0.28.0",
+    "@voltro/plugin-auth": "0.28.0",
+    "@voltro/plugin-broadcast": "0.28.0",
+    "@voltro/plugin-mail": "0.28.0",
+    "@voltro/plugin-storage": "0.28.0",
+    "@voltro/plugin-webhooks": "0.28.0",
+    "@voltro/protocol": "0.28.0",
+    "@voltro/runtime": "0.28.0",
+    "@voltro/serverless": "0.28.0",
+    "@voltro/workflow": "0.28.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/AGENTS.md

@@ -602,7 +602,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.26.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.27.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | AI | `node_modules/@voltro/cli/templates/agent-docs/ai.md` | How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework. |
 | Authentication | `node_modules/@voltro/cli/templates/agent-docs/authentication.md` | How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol. |
 | Caching | `node_modules/@voltro/cli/templates/agent-docs/caching.md` | Voltro's caching layer (@voltro/cache) — an always-on memory default, swappable Redis-compatible backends, a low-level wrap primitive, and automatic query-result invalidation. |

package/templates/agent-docs/_index.md

@@ -9,7 +9,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.26.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.27.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | AI | `node_modules/@voltro/cli/templates/agent-docs/ai.md` | How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework. |
 | Authentication | `node_modules/@voltro/cli/templates/agent-docs/authentication.md` | How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol. |
 | Caching | `node_modules/@voltro/cli/templates/agent-docs/caching.md` | Voltro's caching layer (@voltro/cache) — an always-on memory default, swappable Redis-compatible backends, a low-level wrap primitive, and automatic query-result invalidation. |

package/templates/agent-docs/deployment.md

@@ -1150,6 +1150,59 @@ KV_BACKEND=redis
 
 Schedules and aggregates auto-coordinate via an advisory lock on SQL stores — no extra config to keep them from double-firing across replicas.
 
+### The prerequisites you learn at the SECOND pod
+
+Every item below is invisible on one replica and breaks on two. They are
+collected here because an operator reported each of them separately, each found
+the same way: the first pod proved the configuration worked.
+
+**The connection pool multiplies, the database limit does not.**
+
+```sh
+DB_MAX_CONNECTIONS=10       # per replica — the fleet opens up to this × replicaCount
+```
+
+The framework opens ONE pool per process. At 4 replicas a pool of 10 is 40
+connections against a database that still allows whatever it allowed before you
+scaled. An operator's second pod died on `Connection timed out` for exactly
+this. `voltro serve` now prints the number and the arithmetic at boot:
+
+```
+db pool: max=10 per replica (DB_MAX_CONNECTIONS) × 4 replicas = up to 40 connections.
+```
+
+Set `REPLICA_COUNT` from your deployment (Helm: `{{ .Values.replicaCount }}`) and
+the line does the multiplication for you; without it the line still names the
+formula. `voltro dev` deliberately does not print it — one process, no replicas.
+
+**`POD_IP` is each replica's identity, not only a workflow setting.**
+
+```yaml
+env:
+  - name: POD_IP
+    valueFrom:
+      fieldRef:
+        fieldPath: status.podIP
+```
+
+Without it every replica registers under the same host, so they are one runner
+as far as the cluster is concerned. The boot warning for it fires only on SQL
+cluster storage, so a deployment that has not adopted durable workflows yet gets
+no signal at all — inject it as a matter of course.
+
+**Derive the broadcast namespace from something that cannot be forgotten.**
+
+```yaml
+- name: VOLTRO_BROADCAST_NAMESPACE
+  value: {{ .Release.Namespace }}
+```
+
+Staging and production of the same app share a name, code and fingerprint, so
+the auto-derived namespace does NOT separate them — only this variable does. An
+operator's own guidance, and better than ours was: a value taken from the
+release namespace cannot be left out of one environment's config file, because
+there is no file to forget.
+
 ### Workflow failover across replicas
 
 On a **SQL store** (postgres / mysql / mariadb / mssql), durable workflows survive a replica crash: completed `step({...})` activities are checkpointed in the cluster journal, so when a replica dies mid-run, a **surviving replica takes over the run and continues it from the last completed step** — it replays the completed steps rather than re-running them. (On sqlite the engine is single-process — durable within one replica, no cross-replica failover.) Two requirements:
@@ -1181,6 +1234,9 @@ Lower the lease for **faster failover**, at the cost of **false-positive reclaim
 - [ ] `VOLTRO_LOG_FORMAT=json`; `sentryPlugin()` + `SENTRY_DSN` for errors
 - [ ] `terminationGracePeriodSeconds` generous for graceful drain; `VOLTRO_SHUTDOWN_GRACE_MS` set just under it (minus the preStop sleep)
 - [ ] `CACHE_BACKEND` / `KV_BACKEND` + a cross-replica change bus when running >1 replica
+- [ ] `DB_MAX_CONNECTIONS` set so `pool × replicaCount` fits your database's limit — read the `db pool:` boot line before raising `replicaCount`
+- [ ] `POD_IP` injected via the downward API on EVERY multi-replica deployment, not only for durable workflows
+- [ ] `VOLTRO_BROADCAST_NAMESPACE` derived from the release namespace — staging and production do not separate themselves
 - [ ] For durable workflows on >1 replica: SQL store + `POD_IP` injected; tune `VOLTRO_WORKFLOW_FAILOVER_LEASE` if a 35s takeover is too slow; step side effects idempotent
 
 

package/templates/agent-docs/testing.md

@@ -372,6 +372,48 @@ What it fills and what it leaves alone:
 
 There is no flag to turn the validation off — a test store that accepts rows production rejects is a fake testing itself. `fixtureRow` is a runtime filler for the loose `store.insert(name, row)` path. For **compile-time** payload typing (a missing required column caught as a type error at the call), use [`insertRow` / `upsertRow`](/docs/data/mutations) from `@voltro/database`, which check against `InferInsertRow<T>`.
 
+## Subscribers — `makeSubscribeContext` + the change constructors
+
+A `*.subscribe.ts` handler does not receive an `AppContext`. It receives a
+change EVENT and a `SubscribeContext`, and both have constructors:
+
+```ts
+import { changeInsert, changeUpdate, changeDelete, changeSoftDelete, makeSubscribeContext, makeTestContext } from '@voltro/testing'
+import subscriber from '../src/attendance.subscribe'
+
+const app = makeTestContext({ store: { attendance: [{ id: 'a1', employeeId: 'e1' }] } })
+const ctx = makeSubscribeContext({ id: 'attendance', store: app.store })
+
+await subscriber.handler(changeUpdate('attendance', { id: 'a1', state: 'in' }, { id: 'a1', state: 'out' }), ctx)
+```
+
+**Build the event with a constructor, not with an object literal.** The
+constructors put the semantics in the name, which is the half a literal cannot
+give you:
+
+| | `op` | `old` | `new` |
+| --- | --- | --- | --- |
+| `changeInsert(t, row)` | `insert` | `null` | the row |
+| `changeUpdate(t, before, after)` | `update` | before | after |
+| `changeDelete(t, row)` | `delete` | the row | `null` |
+| `changeSoftDelete(t, row)` | **`update`** | `deletedAt: null` | `deletedAt` set |
+
+`changeSoftDelete` is the reason this exists. There is no `op: 'softDelete'` and
+there never will be — a soft delete is an ordinary update that sets `deletedAt`
+— so a test author who does not know that writes a delete, and the test passes
+against a stream the framework never emits. We shipped exactly that defect: a
+feature that keys off soft deletes was inert in production while its own tests
+were green, because they asserted against an event shape that does not exist.
+
+`ctx.store` has **no default and throws when touched**. Pass
+`makeTestContext().store` so the subscriber and the code under test share one; a
+silent empty store would let a subscriber reading the wrong table pass its test,
+which is the same silent-nothing the constructors exist to remove.
+
+`ctx.publish` is absent unless you pass one, mirroring the real context — where
+it is optional precisely so that reaching for it in an app that declares no
+event is a type error.
+
 ## Subject + tenant re-scoping
 
 `withSubject` and `withTenant` re-scope to a different principal for one block, sharing the **same** underlying data — so cross-subject reads exercise real tenant scoping, not a closure stub. This is how you prove isolation: write as one tenant, then assert another tenant can't see the row.