@voltro/cli 0.28.0 → 0.30.0

package/templates/apps/mobile-app/src/app/index.tsx

@@ -0,0 +1,62 @@
+// Home screen — the reactive end-to-end loop, on a phone.
+//
+// The SAME hooks as the web frontend: `useSubscription('app', 'notes.list')`
+// streams the server-side query; `useMutation('app', 'notes.create')` writes it.
+// When the mutation lands, the server pushes a delta and this list re-renders —
+// no refetch, no polling. (Requires the M0 client boot; see ../client.ts.)
+import { useState } from 'react'
+import { Link } from 'expo-router'
+import { FlatList, Pressable, Text, TextInput, View } from 'react-native'
+import { useMutation, useSubscription } from '@voltro/client'
+
+interface Note {
+  readonly id: string
+  readonly title: string
+}
+
+export default function Home() {
+  const notes = useSubscription<ReadonlyArray<Note>>('app', 'notes.list')
+  const createNote = useMutation<{ title: string }, Note>('app', 'notes.create')
+  const [title, setTitle] = useState('')
+
+  return (
+    <View style={{ flex: 1, padding: 16, gap: 12 }}>
+      <View style={{ flexDirection: 'row', gap: 8 }}>
+        <TextInput
+          value={title}
+          onChangeText={setTitle}
+          placeholder="New note…"
+          style={{ flex: 1, borderWidth: 1, borderColor: '#ccc', borderRadius: 8, padding: 10 }}
+        />
+        <Pressable
+          onPress={() => {
+            if (title.trim().length === 0) return
+            // Auto-optimistic: the list updates instantly, reconciles on ack.
+            createNote.mutate({ title: title.trim() })
+            setTitle('')
+          }}
+          style={{ backgroundColor: '#2563eb', borderRadius: 8, paddingHorizontal: 16, justifyContent: 'center' }}
+        >
+          <Text style={{ color: 'white', fontWeight: '600' }}>Add</Text>
+        </Pressable>
+      </View>
+
+      <FlatList
+        data={notes.data ?? []}
+        keyExtractor={(n) => n.id}
+        ListEmptyComponent={<Text style={{ color: '#666' }}>No notes yet — add one above.</Text>}
+        renderItem={({ item }) => (
+          <Link href={`/orders/${item.id}` as never} asChild>
+            <Pressable style={{ paddingVertical: 12, borderBottomWidth: 1, borderBottomColor: '#eee' }}>
+              <Text style={{ fontSize: 16 }}>{item.title}</Text>
+            </Pressable>
+          </Link>
+        )}
+      />
+
+      <Link href="/settings" style={{ color: '#2563eb', textAlign: 'center', paddingTop: 8 }}>
+        Settings & sync status
+      </Link>
+    </View>
+  )
+}

package/templates/apps/mobile-app/src/app/orders/[id].tsx

@@ -0,0 +1,19 @@
+// A param screen — the target of the `/orders/:id` deep link (see
+// ../../lib/deeplinks.ts). Tapping a note, a universal link, or a push whose
+// payload carried `data.deepLink: '/orders/<id>'` all land here through the one
+// typed link table.
+import { useLocalSearchParams } from 'expo-router'
+import { Text, View } from 'react-native'
+
+export default function OrderDetail() {
+  const { id } = useLocalSearchParams<{ id: string }>()
+  return (
+    <View style={{ flex: 1, padding: 16, gap: 8 }}>
+      <Text style={{ fontSize: 20, fontWeight: '700' }}>Order {id}</Text>
+      <Text style={{ color: '#666' }}>
+        Reached via the typed deep-link table. Fetch this order with
+        {' '}useSubscription('app', 'orders.get', {'{'} id {'}'}).
+      </Text>
+    </View>
+  )
+}

package/templates/apps/mobile-app/src/app/settings.tsx

@@ -0,0 +1,51 @@
+// Settings — sync status (first-class on mobile) + device registration for push.
+import { useState } from 'react'
+import { Pressable, Text, View } from 'react-native'
+import { useMobileConnectionStatus } from '@voltro/react-native'
+import { buildDeviceRegistration } from '../lib/notifications'
+
+export default function Settings() {
+  const { status, reportSuccess, reportFailure } = useMobileConnectionStatus()
+  const [registered, setRegistered] = useState<string | null>(null)
+
+  return (
+    <View style={{ flex: 1, padding: 16, gap: 16 }}>
+      <View>
+        <Text style={{ fontSize: 18, fontWeight: '700' }}>Sync</Text>
+        <Text style={{ color: '#666' }}>Connection: {status}</Text>
+        <View style={{ flexDirection: 'row', gap: 8, marginTop: 8 }}>
+          {/* In a real app these are driven by NetInfo + the client's transport
+              errors (see plans/open/mobile/03). Buttons here make the seam visible. */}
+          <Pressable onPress={reportSuccess} style={btn}>
+            <Text style={btnText}>Mark reachable</Text>
+          </Pressable>
+          <Pressable onPress={reportFailure} style={btn}>
+            <Text style={btnText}>Mark unreachable</Text>
+          </Pressable>
+        </View>
+      </View>
+
+      <View>
+        <Text style={{ fontSize: 18, fontWeight: '700' }}>Push</Text>
+        <Text style={{ color: '#666' }}>
+          {registered ? `Registered token ${registered.slice(0, 12)}…` : 'Not registered'}
+        </Text>
+        <Pressable
+          onPress={() => {
+            // In a real app the token comes from expo-notifications'
+            // getExpoPushTokenAsync(); the SENDER is server-side + creds-gated
+            // (see plans/open/mobile/02). This builds the _voltro_devices row.
+            const row = buildDeviceRegistration('ExponentPushToken[demo]', 'ios')
+            setRegistered(row.deviceToken)
+          }}
+          style={[btn, { marginTop: 8 }]}
+        >
+          <Text style={btnText}>Register this device</Text>
+        </Pressable>
+      </View>
+    </View>
+  )
+}
+
+const btn = { backgroundColor: '#2563eb', borderRadius: 8, paddingHorizontal: 14, paddingVertical: 10 } as const
+const btnText = { color: 'white', fontWeight: '600' } as const

package/templates/apps/mobile-app/src/client.ts

@@ -0,0 +1,74 @@
+// The Voltro client for React Native.
+//
+// The transport keystone now EXISTS: `@voltro/client`'s `buildApiRuntime` builds
+// the runtime + subscription cache + rpc client over a WebSocket, and it takes
+// the WebSocket constructor as an INJECTED dependency — so React Native passes
+// its own `globalThis.WebSocket` (which RN provides) and gets the SAME client
+// stack the web app uses, without pulling in `@voltro/web`. See
+// plans/open/mobile/00-overview.md (M0).
+//
+// ┌─ THE ONE REMAINING SEAM ─────────────────────────────────────────────────┐
+// │ `buildApiHandle` below is functional. What it still needs is the api's rpc │
+// │ GROUP + descriptor map — on web these come from codegen's generated entry. │
+// │ A `voltro codegen` mobile target that emits them for this app is the next  │
+// │ M-step (plans/open/mobile/01). Until it lands, `buildApiHandles()` returns │
+// │ an empty map (the screens show their loading state) rather than faking it. │
+// └──────────────────────────────────────────────────────────────────────────┘
+
+import { buildApiRuntime, type ApiHandle, type BuildApiRuntimeOptions } from '@voltro/client'
+import { offlineFirstDefaults } from '@voltro/react-native'
+
+/** The api's rpc group type — sourced from @voltro/client so the template needs
+ *  no direct @effect/rpc dependency. Codegen produces the concrete value. */
+type ApiRpcGroup = BuildApiRuntimeOptions['group']
+
+/** The api's base URL. On a simulator/device this must be your machine's LAN
+ *  address (not `localhost`), e.g. `http://192.168.1.20:4000`. */
+export const API_URL = process.env.EXPO_PUBLIC_API_URL ?? 'http://localhost:4000'
+
+/** The offline-first posture spread into the app's client config. */
+export const clientPosture = offlineFirstDefaults
+
+/** http(s)://host:port → ws(s)://host:port/ws (the api's WebSocket endpoint). */
+const toWsUrl = (httpUrl: string): string =>
+  `${httpUrl.replace(/^http/, 'ws').replace(/\/+$/, '')}/ws`
+
+/** React Native provides a global WebSocket; no tracking/reconnect wrapper here
+ *  yet (the RN reconnect supervisor is a later M-step — plans/open/mobile/03). */
+const rnWebSocket = (url: string, protocols?: string | ReadonlyArray<string>): globalThis.WebSocket =>
+  new globalThis.WebSocket(url, protocols as string | string[] | undefined)
+
+/**
+ * Build one api's {@link ApiHandle} for the RN client provider. Fully functional
+ * — hand it the codegen-produced `group` + `descriptors` for the api and it
+ * returns a live handle. `descriptors` is `ClientDescriptor`-shaped
+ * (see @voltro/client); pass the generated map.
+ */
+export const buildApiHandle = async (
+  name: string,
+  group: ApiRpcGroup,
+  descriptors: ApiHandle['descriptors'],
+): Promise<ApiHandle> => {
+  const wsUrl = toWsUrl(API_URL)
+  const built = await buildApiRuntime({ name, wsUrl, group, webSocketConstructor: rnWebSocket })
+  return {
+    runtime: built.runtime,
+    cache: built.cache,
+    client: built.client as ApiHandle['client'],
+    descriptors,
+    inspectBaseUrl: API_URL.replace(/\/+$/, ''),
+    errorBus: built.errorBus,
+  }
+}
+
+/**
+ * Build the `apis` map `FrameworkRuntimesProvider` needs. Returns an empty map
+ * until codegen emits this app's rpc group (the seam above) — then map each
+ * configured api through {@link buildApiHandle}.
+ */
+export const buildApiHandles = async (): Promise<ReadonlyMap<string, ApiHandle>> => {
+  // Once codegen targets mobile:
+  //   const { rpcGroup, descriptors } = await import('./rpcGroup.generated')
+  //   return new Map([['app', await buildApiHandle('app', rpcGroup, descriptors)]])
+  return new Map<string, ApiHandle>()
+}

package/templates/apps/mobile-app/src/lib/deeplinks.ts

@@ -0,0 +1,39 @@
+// The app's deep-link table + a pure resolver.
+//
+// A deep link maps an inbound URL — a universal link (`https://…/orders/42`), a
+// custom-scheme URL (`{{appName}}://orders/42`), or a push payload's
+// `data.deepLink` — to an in-app navigation. `defineDeepLink` + the pure matcher
+// come from `@voltro/react-native`; this module is browser/RN-safe (no Metro, no
+// screens), which is exactly why it is unit-testable without a simulator.
+//
+// Declaration order wins in `matchFirstDeepLink`, so list more-specific patterns
+// FIRST. The `navigate` callback is injected (the screen layer passes
+// expo-router's `router.push`), keeping this table pure + testable.
+import {
+  defineDeepLink,
+  matchFirstDeepLink,
+  type DeepLinkDescriptor,
+} from '@voltro/react-native'
+
+/** Build the app's deep links against a navigate function (expo-router's `push`). */
+export const makeDeepLinks = (
+  navigate: (href: string) => void,
+): ReadonlyArray<DeepLinkDescriptor> => [
+  defineDeepLink({ pattern: '/orders/:id', handler: ({ id }) => navigate(`/orders/${id}`) }),
+  defineDeepLink({ pattern: '/settings', handler: () => navigate('/settings') }),
+]
+
+/**
+ * Route an inbound URL through the link table. Returns `true` when a link
+ * matched (its handler ran → navigation happened), `false` when nothing did so
+ * the caller can fall back to a default route.
+ */
+export const handleDeepLink = (
+  links: ReadonlyArray<DeepLinkDescriptor>,
+  url: string,
+): boolean => {
+  const hit = matchFirstDeepLink(links, url)
+  if (hit === null) return false
+  hit.descriptor.handler(hit.params)
+  return true
+}

package/templates/apps/mobile-app/src/lib/notifications.ts

@@ -0,0 +1,31 @@
+// Push device registration — the CREDENTIAL-FREE half.
+//
+// After the OS issues a push token (via `expo-notifications`), the app upserts a
+// `_voltro_devices` row so the server can later fan a notification out to it. The
+// SENDER (APNs/FCM/Expo push) is server-side and creds-gated — see
+// plans/open/mobile/02-push-pipeline.md. This module only builds the row, purely,
+// so it is testable without a device.
+//
+// `userId` / `tenantId` are deliberately NOT set here: the server stamps them
+// from the authenticated request (never trusted from the client).
+import {
+  resolveDeviceRegistration,
+  type DeviceRegistration,
+  type DevicePlatform,
+  type DeviceRegistrationEnv,
+} from '@voltro/react-native'
+
+/**
+ * Build the registration row from an Expo push token + platform. Pure given an
+ * `env` (inject `now` / `locale` / `timezone` in tests); in a real runtime the
+ * locale/timezone defaults come from the device.
+ */
+export const buildDeviceRegistration = (
+  expoPushToken: string,
+  platform: DevicePlatform,
+  env?: DeviceRegistrationEnv,
+): DeviceRegistration =>
+  resolveDeviceRegistration(
+    { deviceToken: expoPushToken, platform, metadata: { via: 'expo' } },
+    env,
+  )

package/templates/apps/mobile-app/src/lib/sync.ts

@@ -0,0 +1,29 @@
+// Background-sync decision layer — pure, on top of `@voltro/react-native`.
+//
+// The framework owns the DECISION (should this trigger actually sync, given
+// what's in flight + when we last ran); the OS wiring (AppState / interval /
+// background-fetch) is the screen's. Keeping the decision here + pure means a
+// screen never re-implements the gate, and the gate is unit-testable.
+import {
+  backgroundSyncReducer,
+  initialBackgroundSyncState,
+  shouldSync,
+  type BackgroundSyncState,
+  type ShouldSyncOptions,
+} from '@voltro/react-native'
+
+/** Sync every 5 minutes while foregrounded (matches `offlineFirstDefaults`). */
+export const SYNC_OPTIONS: ShouldSyncOptions = { intervalMs: 5 * 60_000, enabled: true }
+
+/**
+ * Should a trigger (foreground return, interval tick, manual pull) actually kick
+ * a sync now? `force` bypasses the foreground + interval gates (a manual pull).
+ */
+export const planSync = (
+  state: BackgroundSyncState,
+  now: number,
+  force = false,
+): boolean => shouldSync(state, now, SYNC_OPTIONS, force)
+
+export { backgroundSyncReducer, initialBackgroundSyncState }
+export type { BackgroundSyncState }

package/templates/apps/mobile-app/src/persistence.ts

@@ -0,0 +1,38 @@
+// RN persistence — a key-value store with the security split M0 needs.
+//
+// The web client persists its cache/outbox via `window.localStorage`, which does
+// not exist in RN. This adapter provides the RN equivalent, with a deliberate
+// split (see plans/open/mobile/03-offline-first-and-sync.md):
+//   - SECRETS (session tokens) → `expo-secure-store` (Keychain / Keystore).
+//   - the query cache / outbox → `@react-native-async-storage/async-storage`.
+// Putting a session token in AsyncStorage is a security bug; secure-store is its
+// home.
+//
+// This is a generic async KV. M0 adapts it to whichever persistence CONTRACT it
+// wires (the client cache and/or `@voltro/local-first`'s `PersistenceAdapter`) —
+// it does not itself claim to satisfy a framework interface that would drift.
+import AsyncStorage from '@react-native-async-storage/async-storage'
+import * as SecureStore from 'expo-secure-store'
+
+/** Keys carrying secrets — routed to the Keychain/Keystore, never AsyncStorage. */
+const SECRET_PREFIX = 'secret:'
+
+const isSecret = (key: string): boolean => key.startsWith(SECRET_PREFIX)
+
+export const kv = {
+  get: async (key: string): Promise<string | null> =>
+    isSecret(key) ? SecureStore.getItemAsync(key) : AsyncStorage.getItem(key),
+
+  set: async (key: string, value: string): Promise<void> => {
+    if (isSecret(key)) await SecureStore.setItemAsync(key, value)
+    else await AsyncStorage.setItem(key, value)
+  },
+
+  remove: async (key: string): Promise<void> => {
+    if (isSecret(key)) await SecureStore.deleteItemAsync(key)
+    else await AsyncStorage.removeItem(key)
+  },
+}
+
+/** Prefix a key so it lands in secure storage. */
+export const secretKey = (name: string): string => `${SECRET_PREFIX}${name}`

package/templates/apps/mobile-app/template.json

@@ -0,0 +1,6 @@
+{
+  "id": "mobile-app",
+  "kind": "mobile",
+  "summary": "An Expo (React Native) app that is the THIRD consumer of your api — same typed hooks (useSubscription / useMutation), offline-first by default, typed deep links, and device registration for push. Expo owns Metro; `voltro dev` runs the sibling api. Scaffold both: `create-project --api=api-backend --mobile`.",
+  "tags": ["mobile", "react-native", "expo", "fullstack", "reactive", "offline-first", "deep-links", "push", "api-backend"]
+}

package/templates/apps/mobile-app/tests/deeplinks.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it, vi } from 'vitest'
+import { handleDeepLink, makeDeepLinks } from '../src/lib/deeplinks'
+
+describe('deep links', () => {
+  it('routes an order URL to the order screen with the captured id', () => {
+    const navigate = vi.fn()
+    const links = makeDeepLinks(navigate)
+    expect(handleDeepLink(links, '/orders/42')).toBe(true)
+    expect(navigate).toHaveBeenCalledWith('/orders/42')
+  })
+
+  it('matches a full custom-scheme URL (scheme + host stripped) and a universal link', () => {
+    const navigate = vi.fn()
+    const links = makeDeepLinks(navigate)
+    expect(handleDeepLink(links, '{{appName}}://orders/7?ref=push')).toBe(true)
+    expect(handleDeepLink(links, 'https://example.com/orders/7')).toBe(true)
+    expect(navigate).toHaveBeenNthCalledWith(1, '/orders/7')
+    expect(navigate).toHaveBeenNthCalledWith(2, '/orders/7')
+  })
+
+  it('routes the settings link', () => {
+    const navigate = vi.fn()
+    expect(handleDeepLink(makeDeepLinks(navigate), '/settings')).toBe(true)
+    expect(navigate).toHaveBeenCalledWith('/settings')
+  })
+
+  it('returns false and navigates nowhere for an unknown URL', () => {
+    const navigate = vi.fn()
+    expect(handleDeepLink(makeDeepLinks(navigate), '/nope/nowhere')).toBe(false)
+    expect(navigate).not.toHaveBeenCalled()
+  })
+})

package/templates/apps/mobile-app/tests/notifications.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest'
+import { buildDeviceRegistration } from '../src/lib/notifications'
+
+describe('device registration', () => {
+  it('builds a _voltro_devices row from an Expo push token (pure with injected env)', () => {
+    const row = buildDeviceRegistration('ExponentPushToken[abc]', 'ios', {
+      locale: 'de-DE',
+      timezone: 'Europe/Berlin',
+      now: () => 1_700_000_000_000,
+    })
+    expect(row).toMatchObject({
+      deviceToken: 'ExponentPushToken[abc]',
+      platform: 'ios',
+      locale: 'de-DE',
+      timezone: 'Europe/Berlin',
+      registeredAt: 1_700_000_000_000,
+      metadata: { via: 'expo' },
+    })
+  })
+
+  it('does NOT carry userId/tenantId — the server stamps those from the request', () => {
+    const row = buildDeviceRegistration('tok', 'android', { now: () => 0 })
+    expect(row).not.toHaveProperty('userId')
+    expect(row).not.toHaveProperty('tenantId')
+  })
+})

package/templates/apps/mobile-app/tests/sync.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest'
+import {
+  backgroundSyncReducer,
+  initialBackgroundSyncState,
+  planSync,
+} from '../src/lib/sync'
+
+describe('background-sync decision', () => {
+  it('syncs a fresh foregrounded state', () => {
+    expect(planSync(initialBackgroundSyncState, 1_000)).toBe(true)
+  })
+
+  it('does not sync again while a sync is already in flight', () => {
+    const syncing = backgroundSyncReducer(initialBackgroundSyncState, { type: 'syncStarted', at: 1_000 })
+    expect(planSync(syncing, 1_100)).toBe(false)
+  })
+
+  it('respects the interval gate after a recent attempt, but a forced pull bypasses it', () => {
+    let s = backgroundSyncReducer(initialBackgroundSyncState, { type: 'syncStarted', at: 1_000 })
+    s = backgroundSyncReducer(s, { type: 'syncSucceeded', at: 1_050 })
+    // 1 minute later — inside the 5-minute interval → no auto sync…
+    expect(planSync(s, 1_050 + 60_000)).toBe(false)
+    // …but a manual pull forces it.
+    expect(planSync(s, 1_050 + 60_000, true)).toBe(true)
+    // 5+ minutes later the interval gate opens.
+    expect(planSync(s, 1_050 + 6 * 60_000)).toBe(true)
+  })
+
+  it('does not auto-sync while backgrounded, but a forced sync still runs', () => {
+    const bg = backgroundSyncReducer(initialBackgroundSyncState, { type: 'background' })
+    expect(planSync(bg, 10_000)).toBe(false)
+    expect(planSync(bg, 10_000, true)).toBe(true)
+  })
+})

package/templates/apps/mobile-app/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "expo/tsconfig.base",
+  "compilerOptions": {
+    "strict": true,
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src", "app.config.ts", "tests", ".expo/types/**/*.ts", "expo-env.d.ts"]
+}

package/templates/apps/mobile-app/voltro.mobile.ts

@@ -0,0 +1,11 @@
+// The api(s) this mobile app consumes — mirrors a web app.config.ts's `apis:`
+// map. The NAME ('app') is the lookup key the hooks use:
+// `useSubscription('app', 'notes.list')`, `useMutation('app', 'notes.create')`.
+// The `package` resolves the sibling api in this project so codegen can pull its
+// typed rpc surface (end-to-end types on a phone). Scaffold the api with
+// `--api=api-backend`.
+export default {
+  apis: {
+    app: { package: '@{{projectName}}/api' },
+  },
+}

package/templates/baselines/compose/docker-compose.prod.yml

@@ -59,6 +59,21 @@ services:
       NODE_ENV: production
       DB_URL: postgres://{{projectNameSnake}}:${POSTGRES_PASSWORD:-change-me-in-prod}@postgres:5432/{{projectNameSnake}}
       VOLTRO_SESSION_SECRET: ${VOLTRO_SESSION_SECRET:?must be set for prod compose}
+      # Only needed once an app turns on a plugin that encrypts columns at rest
+      # (`governance` with `fieldEncryption`, or any `.encrypted()` column). It
+      # is commented out because a generated file cannot know which plugins you
+      # will enable — and left here, named, because the alternative is finding
+      # out at `onActivate` in a container:
+      #
+      #   governance: fieldEncryption is enabled but secret
+      #   "VOLTRO_FIELD_ENCRYPTION_KEY" did not resolve
+      #
+      # Mint it with `voltro secret generate field-encryption` — same shape as
+      # `openssl rand -hex 32`, but it is the documented path and it cannot
+      # produce the wrong length. LOSE THE KEY, LOSE THE DATA: there is no
+      # recovery for a column encrypted under a key you no longer have, so back
+      # it up wherever you keep the session secret.
+      # VOLTRO_FIELD_ENCRYPTION_KEY: ${VOLTRO_FIELD_ENCRYPTION_KEY:?must be set once fieldEncryption is on}
     ports:
       - "4000:4000"
     depends_on:

package/templates/baselines/compose-mariadb/docker-compose.prod.yml

@@ -83,6 +83,21 @@ services:
       S3_SECRET_ACCESS_KEY: ${S3_SECRET_ACCESS_KEY:-minioadmin}
       S3_FORCE_PATH_STYLE: "1"
       VOLTRO_SESSION_SECRET: ${VOLTRO_SESSION_SECRET:?must be set for prod compose}
+      # Only needed once an app turns on a plugin that encrypts columns at rest
+      # (`governance` with `fieldEncryption`, or any `.encrypted()` column). It
+      # is commented out because a generated file cannot know which plugins you
+      # will enable — and left here, named, because the alternative is finding
+      # out at `onActivate` in a container:
+      #
+      #   governance: fieldEncryption is enabled but secret
+      #   "VOLTRO_FIELD_ENCRYPTION_KEY" did not resolve
+      #
+      # Mint it with `voltro secret generate field-encryption` — same shape as
+      # `openssl rand -hex 32`, but it is the documented path and it cannot
+      # produce the wrong length. LOSE THE KEY, LOSE THE DATA: there is no
+      # recovery for a column encrypted under a key you no longer have, so back
+      # it up wherever you keep the session secret.
+      # VOLTRO_FIELD_ENCRYPTION_KEY: ${VOLTRO_FIELD_ENCRYPTION_KEY:?must be set once fieldEncryption is on}
     ports:
       - "4000:4000"
     depends_on:

package/templates/patches/@effect__cluster@0.60.0.patch

@@ -10,8 +10,8 @@ index 77ebad1d2e940b73a494bf9ab0ad7e008daddf82..5e268da7b7923f454b7293eff2ee7932
 +  const envelopeToRow = (envelope, message_id, deliver_at_in) => {
 +    // Cast deliver_at (millisecond epoch) to BigInt so mssql's tedious
 +    // driver binds it as BIGINT instead of inferring INT (which overflows
-+    // for any post-2001 timestamp). Other dialects accept bigint fine.
-+    const deliver_at = deliver_at_in == null ? null : BigInt(deliver_at_in);
++    // for any post-2001 timestamp). ONLY mssql — sqlite runs safeIntegers(true) and hangs on a bigint.
++    const deliver_at = deliver_at_in == null ? null : sql.onDialectOrElse({ mssql: () => BigInt(deliver_at_in), orElse: () => deliver_at_in });
      switch (envelope._tag) {
        case "Request":
          return {
@@ -96,8 +96,8 @@ index e41d91033992bb890bebb1a16a5ac9e6657a9c41..5ac3181298a020b4e748fc6433ec6f4a
 +  const envelopeToRow = (envelope, message_id, deliver_at_in) => {
 +    // Cast deliver_at (millisecond epoch) to BigInt so mssql's tedious
 +    // driver binds it as BIGINT instead of inferring INT (which overflows
-+    // for any post-2001 timestamp). Other dialects accept bigint fine.
-+    const deliver_at = deliver_at_in == null ? null : BigInt(deliver_at_in);
++    // for any post-2001 timestamp). ONLY mssql — sqlite runs safeIntegers(true) and hangs on a bigint.
++    const deliver_at = deliver_at_in == null ? null : sql.onDialectOrElse({ mssql: () => BigInt(deliver_at_in), orElse: () => deliver_at_in });
      switch (envelope._tag) {
        case "Request":
          return {
@@ -183,8 +183,8 @@ index 4326c3832b425548dac135493a4a6cbec0856f63..430474fe47549170592fa32d5b0dcac6
    ): MessageRow => {
 +    // Cast deliver_at (millisecond epoch) to BigInt so mssql's tedious
 +    // driver binds it as BIGINT instead of inferring INT (which overflows
-+    // for any post-2001 timestamp). Other dialects accept bigint fine.
-+    const deliver_at: bigint | null = deliver_at_in == null ? null : BigInt(deliver_at_in)
++    // for any post-2001 timestamp). ONLY mssql — sqlite runs safeIntegers(true) and hangs on a bigint.
++    const deliver_at: bigint | number | null = deliver_at_in == null ? null : sql.onDialectOrElse({ mssql: () => BigInt(deliver_at_in), orElse: () => deliver_at_in })
      switch (envelope._tag) {
        case "Request":
          return {

package/dist/apiBuild-DgBS9ayv.js

@@ -1,2 +0,0 @@
-import { c as e, l as t } from "./apiBuild-eUM32r1u.js";
-export { e as runApiBuild, t as runServeBundleBuild };

package/dist/dbCommand-DvguqlzF.js

@@ -1,2 +0,0 @@
-import { s as e } from "./dbCommand-CpYgmSw4.js";
-export { e as runDbCommand };

package/dist/fileConventions-3bffWssN.js

@@ -1,30 +0,0 @@
-//#region src/fileConventions.ts
-var e = /\.(query|mutation|action|stream)\.ts$/, t = /\.(query|mutation|action|stream)\.server\.ts$/, n = /\.event\.ts$/, r = /\.workflow\.tsx$/, i = /\.workflow\.server\.tsx$/, a = /\.workflow\.tsx?$/, o = /\.trigger\.tsx?$/, s = /\.cron\.tsx?$/, c = /\.webhook\.tsx?$/, l = /\.outbox\.tsx?$/, u = /\.subscribe\.tsx?$/, d = /\.reaction\.tsx?$/, f = /\.aggregate\.tsx?$/, p = /\.startup\.tsx?$/, m = /\.seed\.ts$/, h = /\.relations\.ts$/, g = /\.entity\.ts$|\.schema\.ts$|^schema\.ts$/, _ = (e) => a.test(e) && !r.test(e) && !i.test(e), v = /(?:^|\/)page\.tsx$/, y = /\.island\.tsx?$/, b = /\.component\.tsx$/, x = /\.component\.ui\.tsx$/, S = /\.hook\.tsx?$/, C = /\.internal\.tsx?$/, w = /\.types\.tsx?$/, T = /\.fixture\.tsx?$/, E = /\.tracking\.tsx?$/, D = /\.store\.tsx?$/, O = /\.client\.tsx?$/, k = /\.(test|spec)\.tsx?$/, A = [
-	e,
-	t,
-	a,
-	i,
-	o,
-	s,
-	c,
-	l,
-	u,
-	d,
-	f,
-	p,
-	m,
-	h,
-	g,
-	/\.route\.tsx?$/,
-	n,
-	D,
-	O,
-	/\.(agent|tool|email|connection|serverless|server|config|generated)\.tsx?$/
-], j = (e) => A.some((t) => t.test(e)), M = /* @__PURE__ */ new Set([
-	"layout.tsx",
-	"error.tsx",
-	"loading.tsx",
-	"not-found.tsx"
-]);
-//#endregion
-export { j as A, E as C, r as D, c as E, a as O, k as S, w as T, g as _, n as a, D as b, C as c, v as d, M as f, h as g, d as h, s as i, _ as j, i as k, y as l, t as m, b as n, T as o, e as p, x as r, S as s, f as t, l as u, m as v, o as w, u as x, p as y };

package/dist/frameworkTableAssembly-lrjZtk0G.js

@@ -1,2 +0,0 @@
-import { t as e } from "./frameworkTableAssembly-BwHU9Euq.js";
-export { e as assembleFrameworkTables };

package/dist/inspect-gt8bq-Tz.js

@@ -1,2 +0,0 @@
-import { r as e } from "./inspect-CUCCzw2I.js";
-export { e as buildCapabilityManifest };

package/dist/manifestBuild-ifczArzr.js

@@ -1,2 +0,0 @@
-import { t as e } from "./manifestBuild-BnzAxp2O.js";
-export { e as buildRpcEntry };