@voltro/cli 0.28.0 → 0.30.0

package/templates/agent-docs/database/misc.md

@@ -296,6 +296,63 @@ who may receive the plaintext — a private note you decrypt *for its owner* is
 valid case, so treating "encrypted" as "never to a client" would be wrong. State
 the exposure policy explicitly.
 
+## `.readableBy(...scopes)` — visible only to scoped subjects
+
+The **graded middle of the same wire-exposure axis** as `.serverOnly()` — not a
+fourth axis. A plain column is visible to everyone who can read the row;
+`.serverOnly()` hides it from every client; `.readableBy(...)` sits between them —
+the column reaches a subject only if it holds the scope:
+
+```ts
+import { id, integer, text, table } from '@voltro/database'
+
+export const invoices = table('invoices', {
+  id:          id(),
+  number:      text(),                                        // visible to everyone
+  amountCents: integer().readableBy('billing:read'),          // only billing-scoped subjects
+  taxNote:     text().readableBy('billing:read', 'admin:pii'), // ANY of the two scopes
+})
+```
+
+**What it does:** a column marked `.readableBy(...scopes)` is stripped from the
+wire OUTPUT for any subject holding NONE of the listed scopes, and present for
+one holding **at least one** of them. Like `.serverOnly()` it changes nothing at
+rest and nothing in the DDL — it is a wire concern only, so a server-internal
+read (`ctx.store.query`) still sees the value; the strip applies only on the way
+out to a client.
+
+**Scope semantics:**
+
+- **≥ 1 scope, OR-matched.** A subject sees the column iff it holds at least one
+  of the listed scopes — `.readableBy('a', 'b')` means "a OR b", not both.
+- **Effective scopes.** The check is the framework's `hasEffectiveScope` — the
+  subject's RAW scopes **∪** its rbac role-derived scopes — so a role that grants
+  `billing:read` unlocks the column even when the scope is not listed directly on
+  the subject.
+- **`admin:full` bypasses it.** A subject holding `admin:full` sees every
+  `.readableBy(...)` column, exactly as it satisfies every guard.
+- **At least one scope is required.** `.readableBy()` with no scope would mean
+  "readable by nobody" — that is `.serverOnly()` — so both the empty call and a
+  blank scope string are rejected at declaration.
+
+**`.serverOnly()` wins when both are present.** `.serverOnly()` is the all-hidden
+end of the axis, so a column carrying both is hidden from EVERYONE — `admin:full`
+included. `.readableBy()` only ever *narrows* an otherwise-visible column; it can
+never re-expose a `.serverOnly()` one:
+
+```ts
+amountCents: integer().readableBy('billing:read'),          // scoped subjects see it; admin:full does too
+secretKey:   text().serverOnly().readableBy('billing:read'), // serverOnly wins → hidden from EVERYONE
+```
+
+Enforcement shares the SAME chokepoint as `.serverOnly()` — the Dispatcher's read
+boundary — but resolves **per subject**: it applies to a query's initial snapshot
+AND every reactive subscription delta, and to the one-shot
+[`publicApi`](/docs/data/rest-routes) REST GET, in both boot paths (`voltro dev`,
+`voltro serve`). A table that declares no `.readableBy(...)` column pays nothing —
+the strip collapses to the subject-independent `.serverOnly()` set and the
+dispatcher's read/diff memo is still shared across all subscribers of a change.
+
 ## Worked example
 
 ```ts

package/templates/agent-docs/database/schema.md

@@ -280,7 +280,9 @@ Two layers enforce row invariants, and they're complementary:
 
 - **`table().validate(Schema)` (below)** — app-level `effect/Schema` validation, run before the INSERT/UPDATE. Use it for the rich stuff a portable `CHECK` can't express: regex / email / structured strings, length ranges, numeric bounds, cross-field rules with custom typed errors. It's the single validation surface — don't reach for a pile of `.min()` / `.max()` / `.pattern()` column modifiers (there aren't any, by design).
 
-Rule of thumb: **`.check()` when the DATABASE must guarantee it; `validate(Schema)` for everything else.** There is no `.comment()` / `.index()` column modifier — indexes are table-level.
+- **`table().rule(name, predicate)` (cross-table)** — neither of the above can read ANOTHER table. A [business rule](/docs/data/mutations#cross-table-business-rules-rule) is a predicate the runtime evaluates inside the mutation transaction, so it can compare the written row against rows in other tables (an invoice total vs. its line items) and rolls the mutation back with a typed `BusinessRuleViolation` on failure.
+
+Rule of thumb: **`.check()` when the DATABASE must guarantee a single-row constraint; `table().rule()` for a cross-table invariant; `validate(Schema)` for everything else.** There is no `.comment()` / `.index()` column modifier — indexes are table-level.
 
 ## Default with callback
 

package/templates/agent-docs/internationalization.md

@@ -45,13 +45,17 @@ The framework's generated `.framework/app.tsx` wraps the Router in `<I18nProvide
 
 Server-side, the active locale is determined by, in priority order:
 
-1. **`voltro:lang` cookie** — the user's explicit choice (written by `@voltro/ui-shadcn`'s ProfileMenu).
+1. **`voltro:locale` cookie** — the user's explicit choice (written by `@voltro/ui-shadcn`'s ProfileMenu).
 2. **`Accept-Language` header** — the browser/OS preference, q-weighted and sorted per RFC 4647.
 3. **`defaultLocale`** — last-resort fallback.
 
 The resolved locale is **guaranteed** to be one of the codes in `locales`. Any unsupported value (a cookie pointing at a code you no longer ship, a browser asking for `xx-YY`) falls through to the next signal. RFC 4647 lookup strips subtags one segment at a time — `de-CH-1996` → `de-CH` → `de` — so a `de` catalog serves a `de-CH` browser.
 
-The client side mirrors #1 (cookie) and #3 (default) for hydration safety. `Accept-Language` is **server-only** because `navigator.languages` can diverge from what the server saw, which would cause a hydration mismatch.
+The client **adopts what the server resolved**, reading it from the `<html lang>` attribute the server render sets, then falling back to the cookie and the default. `Accept-Language` is never read in the browser: `navigator.languages` can diverge from what the server saw.
+
+> Earlier versions said the client "mirrors cookie and default for hydration safety". That was the opposite of what happened. Dropping the `Accept-Language` signal is not the same as agreeing with the server about it — on a first visit, with no cookie yet, the server negotiated `Accept-Language` while the client fell through to `defaultLocale`. An English browser on a German-default app therefore hydrated `de` over an `en` tree and React discarded the entire server render, which is exactly what SSR was enabled to avoid. It stopped as soon as anything wrote the cookie, so one language switch made it un-reproducible for that developer.
+
+`<html lang>` carries the same resolved locale — the value the `<I18nProvider>` renders with, on the same request. That matters on its own: it is what a screen reader pronounces in, what Chrome offers to translate *from*, and what hyphenation uses.
 
 See [Catalogs](/docs/i18n/catalogs) for the type-safe catalog convention and the component hooks, [Plurals & formatting](/docs/i18n/formatting) for CLDR plural selection and the `Intl`-backed date / number / relative-time hooks, and [URL strategies](/docs/i18n/url-strategies) for cookie-only vs URL-prefix routing.
 
@@ -236,7 +240,7 @@ export const getCatalog = (locale?: string) => pickCatalog({ en, de }, locale, '
 ```
 
 ```tsx
-// any page — meta gets the active locale (from the URL prefix, or the voltro:lang cookie)
+// any page — meta gets the active locale (from the URL prefix, or the voltro:locale cookie)
 import { getCatalog } from '../locales'
 
 export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
@@ -326,14 +330,14 @@ The wrap deliberately doesn't re-export everything, to keep the framework's bles
 <!-- source: en/i18n/url-strategies.md -->
 ## URL strategies
 
-_Cookie-only vs URL-prefix routing (Strategy A / B), the URL-prefix integration sketch, resolveLocale on the /server subpath, the voltro:lang / voltro:theme cookie convention._
+_Cookie-only vs URL-prefix routing (Strategy A / B), the URL-prefix integration sketch, resolveLocale on the /server subpath, the voltro:locale / voltro:theme cookie convention._
 
 There are two ways an i18n app can encode the active locale. Pick **one**, based on what the app's URLs are *for*.
 
 ## Strategy A — cookie-only (default for product apps)
 
 - All locales are served from the **same** URL (`/dashboard`, `/settings`).
-- The `voltro:lang` cookie + `Accept-Language` determine which catalog renders.
+- The `voltro:locale` cookie + `Accept-Language` determine which catalog renders.
 - The ProfileMenu's language switch — or the standalone `<LocaleSwitcher>` from `@voltro/ui-shadcn` — writes the cookie and reloads.
 - Use when URLs are **functional** (`/dashboard/projects/42/deployments`) and don't need to encode the language. This is most apps.
 
@@ -507,15 +511,16 @@ The `/server` subpath is convention. Both that path and the main entry are pure
 
 ## Cookie convention
 
-The framework reads + writes **`voltro:lang`** for the active language choice (lowercase IETF tag: `en`, `de`, `fr-CA`). `@voltro/ui-shadcn`'s ProfileMenu and the framework's auto-wired resolver agree on this name — **don't pick a different one in app code.**
+The framework reads + writes **`voltro:locale`** for the active language choice (lowercase IETF tag: `en`, `de`, `fr-CA`). `@voltro/ui-shadcn`'s ProfileMenu and the framework's auto-wired resolver agree on this name — **don't pick a different one in app code.**
 
-For theme the parallel cookie is **`voltro:theme`** (values `'system' | 'light' | 'dark'`). Both are managed by the kit's ProfileMenu out of the box; the helpers live in `@voltro/ui-shadcn` (`THEME_COOKIE`, `LANG_COOKIE`, `getCookie`, `setCookie`, `deleteCookie`, `parsePreferenceCookies`, `applyTheme`).
+For theme the parallel cookie is **`voltro:theme`** (values `'system' | 'light' | 'dark'`). Both are managed by the kit's ProfileMenu out of the box; the helpers live in `@voltro/ui-shadcn` (`THEME_COOKIE`, `LOCALE_COOKIE`, `getCookie`, `setCookie`, `deleteCookie`, `parsePreferenceCookies`, `applyTheme`).
 
 ## Anti-patterns
 
 - **Don't mix strategies within one app.** Pick cookie-only *or* URL-prefix per app; mixing them produces ambiguous canonical URLs and broken language switching.
 - **Don't read `Accept-Language` on the client.** It's server-only — `navigator.languages` can diverge from what the server saw and cause a hydration mismatch.
-- **Don't invent your own cookie name.** The kit and the resolver only agree on `voltro:lang` / `voltro:theme`.
+- **Don't invent your own cookie name.** The kit and the resolver only agree on `voltro:locale` / `voltro:theme`.
+- **Don't hardcode the name either — import the constant.** `LOCALE_COOKIE` / `THEME_COOKIE` from `@voltro/ui-shadcn`. A cookie name the framework READS and your app WRITES is a public API, and it is the only kind where both sides can disagree with nothing failing: the resolver finds nothing, falls back to `Accept-Language`, and a user's language choice quietly stops working — but only for the users whose browser language differs from their choice, which is the least likely case anyone tests. With the constant, a rename in the framework is a compile error in your app. `voltro doctor` flags a written literal for exactly this reason.
 
 
 
@@ -697,3 +702,159 @@ For dates, numbers and relative time the hooks are the blessed path; reach for `
 - **Don't pin a global `timeZone` / locale for the whole app.** The formatters resolve the active locale from the provider; a pin makes every viewer read the app in one user's settings.
 - **Don't pass a locale-formatted string to a machine consumer.** Formatted output is presentation — send ISO strings and raw numbers to APIs, `dateTime` attributes and sort keys.
 - **Don't format inside a `.map()` by constructing `Intl` objects yourself.** The hooks memoize per locale; a fresh `new Intl.NumberFormat(...)` per row is the slow path.
+
+
+
+---
+
+<!-- source: en/i18n/datetime.md -->
+## Dates & timezones
+
+_"@voltro/datetime — UTC-instant storage, timezone-aware arithmetic/formatting on TC39 Temporal, and the request-scoped timezone-context seam."_
+
+`@voltro/datetime` is the framework's opinion on time: **store UTC instants,
+render in the viewer's timezone, never do zone math by hand.** It is built on the
+[TC39 Temporal](https://tc39.es/proposal-temporal/docs/) standard (via a
+polyfill, so the API is identical on the server and in the browser) and ships
+pure, browser-safe helpers plus a request-scoped timezone seam.
+
+The `.` entry is browser-safe — no `effect`, no `node:*` — so a route or
+component can import it directly. The Effect seam lives in a separate subpath,
+`@voltro/datetime/context`, so the pure surface carries no `effect` dependency.
+
+> **Phase 1.** This is the storage + timezone + formatting layer. Schema-DSL
+> temporal column types, `interval()`, and `rrule()` are later phases; use
+> `timestamp()` columns and these helpers today.
+
+## The storage contract: a `Date` is a UTC instant
+
+`timestamp()` stores `TIMESTAMPTZ`, and the driver hands your app code a plain JS
+`Date`. A `Date` is a bare epoch-millisecond count with no zone of its own, so
+the ONLY correct reading of it is "the UTC instant it points at". These helpers
+make that reading explicit and lossless in both directions:
+
+```ts
+import { toInstant, toUTCString, isValidTimeZone } from '@voltro/datetime'
+
+// A `Date` from a query IS a UTC instant — read it as one, losslessly.
+const when = toInstant(row.createdAt)   // Temporal.Instant
+toUTCString(row.createdAt)              // "2026-08-06T12:00:00Z" — the wire/storage form
+
+isValidTimeZone('Europe/Berlin')        // true
+isValidTimeZone('Mars/Phobos')          // false
+```
+
+`toInstant` accepts a `Temporal.Instant`, a JS `Date`, or an ISO-8601 string —
+but a string MUST carry an explicit offset or `Z`. A naive `2026-01-01T12:00`
+denotes no instant and throws, by design: the whole point is that there is no
+silent zone-guessing. Bridge back with `toDate(instant)` for storage or interop.
+
+## Timezone resolution — the framework convention
+
+Which zone should a given request render in? Resolve it in priority order, each
+candidate validated as an IANA name, falling back to `UTC`:
+
+```ts
+import { resolveTimezone } from '@voltro/datetime'
+
+const tz = resolveTimezone({
+  userTimeZone:    user.timezone,        // 1. the viewing user's profile
+  tenantTimeZone:  tenant.timezone,      // 2. the tenant / org default
+  browserTimeZone: 'Europe/Berlin',      // 3. the browser-reported zone
+})                                        // → a validated IANA name, else 'UTC'
+```
+
+This mirrors `@voltro/i18n`'s `resolveLocale` in spirit — pure, framework-agnostic,
+no Effect or RPC — so it runs in any request pipeline. An invalid or absent
+candidate falls through to the next signal; the result is GUARANTEED valid.
+
+### Carrying it through a request — the context seam
+
+The resolved zone travels through a request via an Effect context tag in
+`@voltro/datetime/context`, so any route, mutation, workflow, or agent can read it:
+
+```ts
+import { currentTimezone, withTimezone } from '@voltro/datetime/context'
+import { Effect } from 'effect'
+
+const program = Effect.gen(function* () {
+  const tz = yield* currentTimezone   // the request's zone, or 'UTC' when none set
+  return tz
+})
+
+// Provide an explicit zone for a sub-computation:
+program.pipe(withTimezone('Europe/Berlin'))
+```
+
+`currentTimezone` never fails — an absent context is the documented `UTC`
+default, so call sites don't handle a missing-service error. The runtime provides
+the tag per request (via `resolvedTimezoneLayer`); the web layer's `useTimezone()`
+hook is a thin projection over it.
+
+## Arithmetic — the DST split is in the names
+
+Every operation that is ambiguous without a zone REQUIRES an IANA `timeZone`
+argument. There is no implicit "system zone", so a call site cannot silently do
+the wrong thing on a differently-configured box. The DST distinction is
+deliberate and encoded in the method names:
+
+```ts
+import { addDays, addHours, startOfDay, endOfDay } from '@voltro/datetime'
+
+// WALL-CLOCK: same local time, one calendar day later in Berlin.
+// Across a DST boundary the elapsed real time is 23h or 25h. Needs a zone.
+addDays(when, 1, 'Europe/Berlin')
+
+// EXACT elapsed time: 24 × 3600 seconds, DST-oblivious. No zone.
+addHours(when, 24)
+
+// Zone-relative day boundaries.
+startOfDay(when, 'Europe/Berlin')
+endOfDay(when, 'Europe/Berlin')
+```
+
+`addDays` / `addMonths` are wall-clock ("same local time, N days on"); `addHours`
+is exact elapsed time. Comparisons that measure absolute instants (`isAfter`,
+`isBefore`) take no zone; `isSameDay` does, because "same day" is a wall-clock
+question. For a calendar date with no time and no zone — a birthday, a holiday, a
+due date — use `plainDate(year, month, day)` / `parseDate('2026-08-06')`.
+
+## Formatting — locale- and timezone-aware
+
+Formatting is where the viewer's timezone and locale are APPLIED. Both are
+explicit arguments — this layer carries no ambient locale (the web layer resolves
+`useLocale()` and passes it in):
+
+```ts
+import { formatDate, formatDateTime, formatRelativeTime } from '@voltro/datetime'
+
+formatDate(row.createdAt, 'Europe/Berlin', { locale: 'de' })        // "6. Aug. 2026"
+formatDateTime(row.createdAt, 'America/New_York', { locale: 'en' })
+formatRelativeTime(row.createdAt, { locale: 'en' })                 // "3 hours ago"
+```
+
+`FormatOptions` is `{ locale? }` plus any `Intl.DateTimeFormatOptions` override,
+so `formatDate(when, tz, { locale, dateStyle: 'full' })` works. `formatRelativeTime`
+picks the largest unit that fits the signed distance from `now` (default: the
+current instant) and is zone-independent — it measures elapsed real time, not
+wall-clock days.
+
+> These helpers are the STORAGE/TIMEZONE layer. `@voltro/i18n`'s
+> [`useFormatDate` / `useRelativeTime`](/docs/i18n/formatting) hooks are the
+> React binding that read the active locale from the provider; reach for those in
+> components, and for `@voltro/datetime` in server code, loaders, and tests.
+
+## Temporal directly
+
+The exact standard `Temporal` types are re-exported, so you can drop to the full
+API when a helper doesn't cover your case:
+
+```ts
+import { Temporal } from '@voltro/datetime'
+
+const noon = Temporal.PlainTime.from('12:00')
+```
+
+Import `Temporal` from `@voltro/datetime`, never from the polyfill directly — that
+keeps the eventual switch to the native global (once it is universal in browsers)
+a one-line change for the whole codebase.