@voltro/runtime 0.11.2 → 0.11.3

package/CHANGELOG.md

@@ -39,6 +39,61 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.11.3] — 2026-07-24
+
+### Added
+
+- **@voltro/runtime** — `crud.*` secure-default CRUD handler helpers + `redactColumns` (A1 core). Each returns an executor you export as a `*.query.server.ts` / `*.mutation.server.ts` default — the descriptor (schemas + `guards`) stays hand-written and browser-safe:
+
+  ```ts
+  // accounts.list.query.server.ts
+  import { crud } from '@voltro/runtime'
+  export default crud.list('accounts', { redact: ['apiSecret'] })
+  ```
+
+  They bake in the invariants a hand-rolled CRUD generator kept getting wrong (the leak class was in the HANDLERS, not the schemas):
+
+  - **Tenant scope** — `list` / `getById` read through `ctx.store`, which auto-scopes a `tenant()` table; they never `.unscoped()`, so a cross-tenant read is impossible. - **Redaction** — `redact` columns are stripped from every returned row (a credential / secret / salary a read must never ship), on reads AND on the row a `create` / `update` echoes. `redactColumns(rows, cols)` is exported standalone for a hand-written handler that isn't plain CRUD. - **`getById` returns `null`, never throws** — a reactive getter that throws stalls its shared-WS siblings (pairs with the per-subscription error isolation).
+
+  What they deliberately DON'T do is authorize: a guard runs before the executor, so gating stays on the DESCRIPTOR (`guards: [...]`) — an executor can't gate itself. Keep write descriptors guarded.
+
+  Scope note: this is the browser-safe, codegen-free core. Deriving the descriptor SCHEMAS from a table (to drop the hand-written `Schema.Struct`) is structurally a codegen concern — a table VALUE can't be imported into a browser-loaded descriptor (it drags the store into the bundle; `rowSchema` is server-only for exactly this reason) — so full schema-derivation + a `.crud()` boot audit for the scope/gating discipline are a separate, planned pass. See `plans/framework-a1-defineCrud.md`.
+- **@voltro/runtime** — `ctx.store.links(junctionTable, anchor)` — a diff-based writer for a many-to-many JUNCTION table (A2). It reconciles the links from one anchor row against a target-id list by writing only the DIFFERENCE:
+
+  ```ts
+  await ctx.store.links('post_tags', { postId: post.id }).set(tagIds) // add missing, remove surplus
+  await ctx.store.links('post_tags', { postId: post.id }).add([tagId]) // idempotent
+  await ctx.store.links('post_tags', { postId: post.id }).remove([tagId])
+  await ctx.store.links('post_tags', { postId: post.id }).list()      // current target ids
+  ```
+
+  Why it belongs in the framework rather than every app: a drop-all-then-reinsert `setLinks` loses data when two writers overlap and makes a reactive subscription on the junction churn every row (flicker) even when nothing changed. `links().set()` touches only the rows that actually differ — the added are inserted, the removed deleted, the unchanged left in place — so a reactive consumer sees a change only for what changed, and `set()` returns `{ added, removed }`. `add`/`remove` are likewise idempotent (they read first and act only on the genuine delta).
+
+  `anchor` names the source column and its id (`{ postId: 'p1' }`); the target column is the junction's OTHER `reference()` column, auto-detected. A junction with anything but exactly two reference columns is refused with a message naming what it found — use plain `insertMany`/`deleteMany` for a non-standard junction. The writes go through the normal stamped/tenant-scoped store path, so tenant and audit columns are filled as usual. Additive: a new `links` method on `FluentStore` + the `JunctionLinks` interface.
+- **@voltro/client, @voltro/web** — `useSubscription(..., { initialSnapshot })` — the last mile of "SSR-correct first paint, then live" (A5). Pass the value an SSR loader already fetched with `ctx.query` (read it in the component with `useLoaderData()`) and the subscription shows it at the first paint with `loading: false` — it IS real server data — then swaps to the live stream the instant its first snapshot arrives:
+
+  ```tsx
+  const seed = useLoaderData<Employee>()
+  const { data } = useSubscription('app', 'employees.me', {}, { initialSnapshot: seed })
+  ```
+
+  The SSR markup and the hydration render read the same loader value, so they match (no hydration flicker), and the app no longer hand-builds a seed store to bridge loader data into the first render. This is the difference from `fallback`, whose value never came from the server and so keeps `loading: true`; use exactly one of the two. Like `fallback`, `initialSnapshot` guarantees `data` is present, so the call gets the non-union result and needs no `loading` branch. Additive: a new `initialSnapshot` field on `SubscriptionOptions` + an overload; `@voltro/web` re-exports the client surface.
+- **@voltro/cli** — `apis.<name>.authHeaders` in a web `app.config.ts` — a declarative per-reconnect auth-header resolver, so an authenticated split-origin web app no longer hand-mounts `VoltroRuntimeProvider` just to inject a rotating-token thunk (A4). The framework owns the client mount, the reconnect re-resolve, and the SSR-null case (the resolver runs browser-only — it never fires on the server):
+
+  ```ts
+  // app.config.ts
+  apis: {
+    api: {
+      package: '@app/api',
+      authHeaders: async () => ({ authorization: `Bearer ${await getToken()}` }),
+    },
+  }
+  ```
+
+  Because it's a FUNCTION, the codegen imports it from `app.config.ts` into the client bundle rather than serializing it — so a config that declares `authHeaders` must stay browser-safe (no `node:*` / server-only value imports; a pure env schema is fine, and tree-shakes out). It supersedes a static `headers` on the same api. The provider already resolved a `ResolvableHeaders` thunk fresh per connection generation; this just lets you declare it in config instead of hand-writing a `mount()` call.
+
+---
+
 ## [0.11.2] — 2026-07-24
 
 ### Added

package/dist/index.d.ts

@@ -1519,6 +1519,48 @@ export declare const counter: (name: string, description?: string) => Metric.Met
  */
 export declare const countRunningWorkflows: (store: DataStore) => Promise<number>;
 
+/**
+ * Secure-default CRUD executor factories. Each takes the table NAME (not the
+ * table value — that would be a server import in a descriptor) and returns an
+ * `(input, ctx) => …` executor for a `*.server.ts` default export.
+ */
+export declare const crud: {
+    /** Tenant-scoped list of every row, redacted. */
+    list: (table: string, options?: CrudReadOptions) => (_input: unknown, ctx: AppContext) => Promise<ReadonlyArray<Row>>;
+    /** One row by id, or `null` when absent — never throws. Redacted. */
+    getById: (table: string, options?: CrudReadOptions) => (input: {
+        readonly id: string;
+    }, ctx: AppContext) => Promise<Row | null>;
+    /** Insert the input as a new row (id / tenant / audit auto-stamped). The echoed
+     *  row is redacted. Guard the DESCRIPTOR — this does not gate. */
+    create: (table: string, options?: CrudWriteOptions) => (input: Row, ctx: AppContext) => Promise<Row>;
+    /** Patch a row by id (`{ id, ...patch }`); returns the updated row or `null`.
+     *  Redacted. Guard the DESCRIPTOR. */
+    update: (table: string, options?: CrudWriteOptions) => (input: {
+        readonly id: string;
+    } & Record<string, unknown>, ctx: AppContext) => Promise<Row | null>;
+    /** Delete a row by id; returns `{ deleted }`. Guard the DESCRIPTOR. */
+    remove: (table: string) => (input: {
+        readonly id: string;
+    }, ctx: AppContext) => Promise<{
+        readonly deleted: boolean;
+    }>;
+};
+
+/** Options common to a generated READ. */
+export declare interface CrudReadOptions {
+    /** Columns stripped from every returned row — a secret/credential a generated
+     *  read must never ship (`bankIban`, `tokenHash`, `salary`). The wire schema on
+     *  the descriptor should omit them too, so they never reach the client at all;
+     *  this is the runtime half that guarantees it regardless. */
+    readonly redact?: ReadonlyArray<string>;
+}
+
+/** Options for a generated WRITE — `redact` applies to the row the write echoes. */
+export declare interface CrudWriteOptions {
+    readonly redact?: ReadonlyArray<string>;
+}
+
 /** Read the active context, if any. Tests use this to validate the
  *  propagation; production code uses it only inside this module. */
 export declare const currentRoutingContext: () => RoutingContext | undefined;
@@ -1974,6 +2016,16 @@ export declare interface FieldChange {
 export declare const fingerprintFor: (table: string, predicate: Predicate, indexHint?: string) => string;
 
 export declare interface FluentStore extends Omit<MutationStore, 'update' | 'delete' | 'query'> {
+    /**
+     * Diff-based many-to-many link writer for a junction table. `anchor` names the
+     * source column and its id (`{ postId: 'p1' }`); the target column is the
+     * junction's other reference column, auto-detected. Only the difference is
+     * written, so reactive consumers see one change per changed row, not a
+     * drop+reinsert of the whole set.
+     *
+     *     await ctx.store.links('post_tags', { postId: post.id }).set(tagIds)
+     */
+    links(junctionTable: string, anchor: Readonly<Record<string, string>>): JunctionLinks;
     /**
      * Execute a query descriptor and return the matching rows — TYPED.
      *
@@ -2454,6 +2506,34 @@ export declare type IvmState = ReadonlyMap<string, GroupState>;
 /** Project the public aggregate value from a group's accumulator. */
 export declare const ivmValue: (shape: AggregateShape, g: GroupState) => number | null;
 
+/**
+ * Diff-based writer for a many-to-many JUNCTION table (A2). Reconciles the set
+ * of links from ONE anchor row (`{ [sourceColumn]: id }`) against a target-id
+ * list by writing only the DIFFERENCE — the added rows are inserted, the removed
+ * rows are deleted, and rows already correct are left untouched. That is the
+ * whole point over a drop-all-then-reinsert `setLinks`: a reactive subscription
+ * on the junction sees a change event only for the rows that actually changed
+ * (no flicker, no lost data if two writers overlap), and an unchanged link never
+ * churns. The TARGET column is the junction's OTHER reference column (the one the
+ * anchor doesn't name); a junction with anything but exactly two reference
+ * columns is rejected with a message naming what it found.
+ */
+export declare interface JunctionLinks {
+    /** The current target ids linked to the anchor. */
+    list(): Promise<ReadonlyArray<string>>;
+    /** Reconcile the links to EXACTLY `targetIds` — insert the missing, delete the
+     *  surplus, leave the rest. Returns what changed. */
+    set(targetIds: ReadonlyArray<string>): Promise<{
+        readonly added: ReadonlyArray<string>;
+        readonly removed: ReadonlyArray<string>;
+    }>;
+    /** Link `targetIds` that aren't linked yet (idempotent — existing links are
+     *  not re-inserted, so they emit no event). Returns the ids actually added. */
+    add(targetIds: ReadonlyArray<string>): Promise<ReadonlyArray<string>>;
+    /** Unlink `targetIds` that are currently linked. Returns the ids actually removed. */
+    remove(targetIds: ReadonlyArray<string>): Promise<ReadonlyArray<string>>;
+}
+
 export declare interface KvFacade {
     readonly kv: AsyncKv;
     /** The resolved Effect-native `Kv` service instance. Its methods close over
@@ -3611,6 +3691,13 @@ export declare const recordTimelineEvent: (change: CdcChange & {
     readonly tenantId?: string | null;
 }) => void;
 
+/**
+ * Strip `redact` columns from a set of rows. Exposed on its own so a hand-written
+ * handler that isn't a plain CRUD read can still redact declaratively and be
+ * audited the same way. Pure — no store, no context.
+ */
+export declare const redactColumns: <R extends Row>(rows: ReadonlyArray<R>, redact: ReadonlyArray<string>) => ReadonlyArray<R>;
+
 /** Blank sensitive-looking columns. Returns a new object; null passes through. */
 export declare const redactRow: (row: Row_2 | null | undefined) => Row_2 | null;