@voltro/runtime 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -39,6 +39,42 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.3.0] — 2026-07-18
+
+### ⚠ BREAKING
+
+- **@voltro/cli** — `voltro build` precompiles the whole serve path (framework + effect + `@voltro` inlined, app modules as lazy chunks) into a single **serve bundle**, and `voltro serve` boots from it in-process — cutting `serve: ready` from ~1000 ms to ~180 ms (5–6×; the win is larger on a cold scale-to-zero container). The app's declared SQL driver is inlined (only the native leaf like `pg` stays external, resolved at runtime so it survives the deploy relocation). **Production now serves ONLY from the bundle and NEVER transpiles on demand:** the bundle build externalises unresolvable optional peers (e.g. `@react-email/render` behind `@voltro/plugin-mail`) so it always builds; a bundle-build failure is **fatal** (`voltro build` exits non-zero); and an unbuilt production `voltro serve` fails loud instead of falling back to tsx. The build toolchain (`tsx`, `esbuild`, `vite`, `@vitejs/plugin-react`, `@tailwindcss/vite` + their native tree: rolldown/lightningcss/postcss/jiti) moves to **`optionalDependencies`** of `@voltro/cli`, so `pnpm --prod --no-optional deploy` yields a serve image with none of it — a prod API image's `node_modules` drops ~305 MB → ~131 MB, structurally, with no fragile prune list. `voltro dev` and a non-production local `voltro serve` are unchanged (still tsx). **Migration:** in production (`NODE_ENV=production`) run `voltro build` before `voltro serve`. The generated Dockerfiles already do; a custom Dockerfile / start script adds a `voltro build .` step before `voltro serve .` (`voltro update` prints this — see the 0.3.0 codemod note).
+
+### Added
+
+- **@voltro/protocol, @voltro/runtime, @voltro/plugin-rbac** — Declarative authorization `guards:` on `defineMutation` / `defineQuery` / `defineAction`. The framework enforces the declared scope(s) in the dispatch spine BEFORE the executor (for a mutation, before the transaction opens), fails with a typed `ScopeError`, and auto-merges `ScopeError` into the wire error union so the client decodes the denial typed. Guards are browser-safe DATA (scope strings + a pure `resource: (input) => id` extractor). Checks run against the caller's EFFECTIVE scope set — raw subject scopes ∪ `@voltro/plugin-rbac` role-derived scopes — via a new canonical effective-scope seam in `@voltro/protocol` (`effectiveScopes` / `setEffectiveScopes` / `checkGuards`), which rbac now publishes to (so a role-granted scope satisfies a `guards:` entry and the in-handler `permission()` identically). Adds `ctx.access` (`has` / `hasAny` / `require` / `scopes`) — the cast-free typed authorization slice on every handler context. Enforcement is single-sourced in the shared serve pipeline, so `voltro dev` and `voltro serve` can't drift.
+- **@voltro/protocol, @voltro/client** — Nested / path-targeted auto-optimistic. A mutation `target` can now patch a nested array INSIDE a query's value — a JSON array column (`snapshot.projects`) or a computed/shaped result — at item granularity, via `path` (dot-path to the array), `by` (item key, default `id`), and `match` (a pure predicate that scopes the patch to the entries whose current value satisfies it, preventing a patch bleeding across sibling subscriptions that share a source table). Previously auto-optimistic only patched the flat top-level row array keyed by `id`; nested values needed a hand-written `.withOptimistic` reducer. `path`/`by`/`match` are browser-safe descriptor data (a dot-path string + pure predicate), same discipline as `identify`/`shape`. A path insert is applied even on a computed entry (it targets a known document, not a blind top-level add).
+- **@voltro/runtime** — `ctx.store.applyDefined(input, keys)` (and a standalone `applyDefined` export from `@voltro/runtime`) — builds a partial-update patch keeping only the listed keys whose value the caller actually provided (`!== undefined`; a defined falsy value like `0`/`''`/`false` is kept). Collapses the per-field `if (input.x !== undefined) patch.x = input.x` idiom every partial-update mutation hand-writes.
+- **@voltro/database** — `.uniqueActive([cols], opts?)` on the table builder — a portable partial-UNIQUE constraint that holds only among the rows matching a predicate (default `"deletedAt" IS NULL`, pairing with `.softDelete()`). Emits `CREATE UNIQUE INDEX … WHERE` on postgres / sqlite / mssql, so a soft-deleted row leaves the active set and a NEW row with the same key inserts cleanly — no hand-written `generatedAs("CASE WHEN …")` column and no resurrection footgun. On mysql / mariadb (no partial-index support) it FAILS LOUDLY at migrate time rather than silently emitting a full unique index that would forbid re-creating a soft-deleted key — the generated-STORED-column lowering for those dialects is a follow-up. Kept out of the declarative index snapshot (the incremental planner is predicate-blind and would misclassify a unique+partial index as a full constraint), so the fresh-schema DDL path is its sole emitter and there is no re-diff churn. Live-verified against postgres.
+- **@voltro/cli** — `voltro update` upgrades an app to the latest framework: it bumps every `@voltro/*` dependency, installs with the detected package manager, and runs the codemods shipped with the target version. Codemods are authored with `defineCodemod` + an import-scoped ts-morph helper toolkit (`renameImport`, `renameModuleSpecifier`, `renameJsxProp`, `renameObjectKey`, `add`/`removeImport`, structural `changeCallArgs`/`wrapCall`, `annotate`) and run against the app source; a `manual` kind surfaces written steps for changes that can't be automated. Breaking public-API changes now ship a codemod (or an explicit `codemod: none`), enforced by the changelog gate. Framework-owned `_voltro_*` table changes continue to ride the declarative differ on `voltro db apply` / `voltro dev` boot — `update` does not touch the database.
+
+### Fixed
+
+- **@voltro/database** — The core-table registry (`registerCoreTables` / `requireActors` / `requireTenants`) now stores its state on a process-global `Symbol.for` singleton, the same mechanism the main table registry already uses — instead of module-local `let` bindings. Module-local state splits when the `@voltro/database` module is duplicated in a process (e.g. resolved through both the `.` and `./sql` entry points, or a bundled framework copy alongside an externally-resolved one): one instance's `registerCoreTables` becomes invisible to the instance that reads it, surfacing as a spurious `core 'actors' table not registered` at store construction. Pinning it to `globalThis` makes every copy share one store, matching the table registry's already-global behaviour.
+
+---
+
+## [0.2.2] — 2026-07-17
+
+### Added
+
+- **@voltro/cli** — `voltro build` now precompiles the whole serve path (framework + effect + `@voltro` inlined, app modules as lazy chunks) into a single **serve bundle** (`.framework/dist-api/serveBundle/serveEntry.js`), and `voltro serve` boots from it in-process — no child `node --import tsx`, no CLI command graph, no per-module resolution of the ~2700-module framework graph. This cuts `serve: ready` from ~1000 ms to ~180 ms (~5–6×) on both driverless (memory) and driver-backed (postgres) apps; the win is larger on a cold scale-to-zero container where module resolution dominates. The app's declared SQL driver is inlined into the bundle so it shares the framework's single effect instance (only the native leaf like `pg` stays external, resolved at runtime so it survives the deploy relocation). Fully fallback-safe: a missing, stale, or corrupt bundle degrades to the standard tsx serve path, so it can never stop `voltro serve` from booting. Nothing to configure — building an API app produces the bundle and serving prefers it automatically.
+
+### Fixed
+
+- **@voltro/database** — The core-table registry (`registerCoreTables` / `requireActors` / `requireTenants`) now stores its state on a process-global `Symbol.for` singleton, the same mechanism the main table registry already uses — instead of module-local `let` bindings. Module-local state splits when the `@voltro/database` module is duplicated in a process (e.g. resolved through both the `.` and `./sql` entry points, or a bundled framework copy alongside an externally-resolved one): one instance's `registerCoreTables` becomes invisible to the instance that reads it, surfacing as a spurious `core 'actors' table not registered` at store construction. Pinning it to `globalThis` makes every copy share one store, matching the table registry's already-global behaviour.
+
+### Internal (no consumer-facing effect)
+
+- **@voltro/cli** — `appModuleLoader` now accepts lazy `() => import()` loaders alongside eager module namespaces (the eager path — today's `apiEntry.js` bundle — is unchanged). Groundwork for the serve bundle: app modules registered as lazy loaders evaluate on first `importAppModule` (during `runServe`, after `registerCoreTables`) rather than eagerly at bundle-import time. No consumer-facing effect on its own.
+
+---
+
 ## [0.2.1] — 2026-07-17
 
 ### Fixed

package/dist/index.d.ts

@@ -12,6 +12,7 @@ import { DialectReplicationAdapter } from '@voltro/database';
 import { Duration } from 'effect';
 import { Effect } from 'effect';
 import { FieldCipher } from '@voltro/database';
+import { GuardCheckSpec } from '@voltro/protocol';
 import * as http from 'node:http';
 import { HttpClient } from '@effect/platform';
 import { HttpRequestInterceptor } from '@voltro/protocol';
@@ -45,6 +46,7 @@ import { RpcGroup } from '@effect/rpc';
 import { RpcInterceptor } from '@voltro/protocol';
 import { Sampler } from '@opentelemetry/sdk-trace-base';
 import { Schema } from 'effect';
+import { ScopeError } from '@voltro/protocol';
 import { SpanProcessor } from '@opentelemetry/sdk-trace-base';
 import { spawn } from 'node:child_process';
 import { SqlClient } from '@effect/sql';
@@ -687,9 +689,34 @@ export declare interface ApiKeyStore {
     readonly patch: (id: string, fields: Partial<ApiKeyRow>) => Promise<void>;
 }
 
+/**
+ * Typed authorization slice on `ctx.access` — the ergonomic, cast-free face of
+ * the caller's EFFECTIVE scope set (raw subject scopes ∪ rbac role-derived
+ * scopes). Replaces the `ctx as unknown as GuardCtx` shape apps hand-rolled to
+ * reach the subject's permissions: a handler reads `ctx.access.has('x')` /
+ * `yield* ctx.access.require('x')` directly, and it stays in lockstep with the
+ * declarative `guards:` the framework enforces (same effective-scope seam).
+ */
+export declare interface AppAccess {
+    /** True if the caller holds `scope` (or the `admin:full` bypass). */
+    readonly has: (scope: string) => boolean;
+    /** True if the caller holds AT LEAST ONE of `scopes`. */
+    readonly hasAny: (scopes: ReadonlyArray<string>) => boolean;
+    /** Effect guard — fails with a typed `ScopeError` when the caller lacks
+     *  `scope`. `yield* ctx.access.require('notes:write')` at the top of a
+     *  handler mirrors a descriptor `guards:` entry for in-body branching. */
+    readonly require: (scope: string) => Effect.Effect<void, ScopeError>;
+    /** The caller's effective scope set (live — reflects rbac resolution). */
+    readonly scopes: ReadonlyArray<string>;
+}
+
 export declare interface AppContext {
     readonly store: FluentStore;
     readonly request: RuntimeContext;
+    /** Typed authorization slice — the caller's effective scopes. Use
+     *  `ctx.access.has(scope)` / `yield* ctx.access.require(scope)` instead of
+     *  reaching into `ctx.request.subject.scopes`. Always present. */
+    readonly access: AppAccess;
     /** Cache — always present (memory backend by default). Use
      *  `ctx.cache.wrap(key, { ttlMs, tags }, () => expensive())` to cache
      *  derived work; tagged entries auto-invalidate when a mutation writes a
@@ -716,6 +743,15 @@ export declare interface AppContext {
     readonly events?: EventsAppContext;
 }
 
+/**
+ * Pure helper backing `ctx.store.applyDefined`. Picks the listed keys from
+ * `input` whose value is not `undefined`, so a PATCH sets exactly the fields
+ * the caller sent — no accidental overwrite of an omitted field with
+ * `undefined`, no hand-written per-field guards. Exported standalone for use
+ * outside a handler (tests, seeds).
+ */
+export declare const applyDefined: <I extends Record<string, unknown>>(input: I, keys: ReadonlyArray<keyof I & string>) => Partial<I>;
+
 /**
  * Apply ONE CDC delta to the materialized state, returning the new state and any
  * groups that need a rescan (min/max whose extreme was deleted). insert/sum/avg/
@@ -1522,6 +1558,17 @@ export declare interface FluentStore extends Omit<MutationStore, 'update' | 'del
     delete(table: string): DeleteBuilder;
     /** Keyed delete by primary key. */
     delete(table: string, primaryKey: string): Promise<boolean>;
+    /**
+     * Build an update patch from `input`, keeping ONLY the listed `keys` whose
+     * value the caller actually PROVIDED (`!== undefined`). Collapses the
+     * per-field `if (input.x !== undefined) patch.x = input.x` idiom every
+     * partial-update mutation hand-writes:
+     *
+     * ```ts
+     * await ctx.store.update('notes', input.id, ctx.store.applyDefined(input, ['title', 'body', 'dueAt']))
+     * ```
+     */
+    applyDefined<I extends Record<string, unknown>>(input: I, keys: ReadonlyArray<keyof I & string>): Partial<I>;
 }
 
 export declare interface FluentStoreBackend {
@@ -2022,6 +2069,12 @@ export declare const makeApiKeyService: (store: ApiKeyStore, opts?: {
     prefix?: string;
 }) => ApiKeyServiceShape;
 
+/** Build the `ctx.access` slice for a subject. Reads the effective-scope seam
+ *  LIVE (via getters/closures) so a scope rbac resolves after context
+ *  construction is still reflected. Used by the shared AppContext builder AND
+ *  the test-context factory so `ctx.access` can't drift between them. */
+export declare const makeAppAccess: (subject: Subject) => AppAccess;
+
 /** Build the `ctx.kv` facade. `KV_BACKEND` picks the backend; unknown values
  *  fall back to `database`. */
 export declare const makeAsyncKv: ({ store, env }: KvFacadeOptions) => Promise<KvFacade>;
@@ -2285,6 +2338,7 @@ export declare interface MutationLike {
     readonly descriptor: {
         readonly name: string;
         readonly source?: string | ReadonlyArray<string> | undefined;
+        readonly guards?: ReadonlyArray<GuardCheckSpec> | undefined;
     };
     executor(input: unknown, ctx: unknown): unknown;
 }