@voltro/database 0.27.0 → 0.29.0

package/dist/index.d.ts

@@ -488,6 +488,9 @@ export declare interface CdcConfig {
  *  warns. See this file's header for why it is 512 and why it is not `0`. */
 export declare const CHANGE_LISTENER_CEILING = 512;
 
+/** A row was removed from the table. `new` is null, always. */
+export declare const changeDelete: (table: string, row: Row, meta?: ChangeEventMeta) => ChangeEvent;
+
 /**
  * A row-change event emitted by the data store (in-memory) or the CDC
  * consumer (Postgres logical replication). Drives the reactive engine.
@@ -548,6 +551,29 @@ export declare type ChangeEvent = {
     readonly procedure?: string;
 };
 
+/** Attribution and origin, identical on every constructor. */
+export declare type ChangeEventMeta = Pick<ChangeEvent, 'origin' | 'traceId' | 'subjectId' | 'procedure'>;
+
+/** A row was created. `old` is null, always. */
+export declare const changeInsert: (table: string, row: Row, meta?: ChangeEventMeta) => ChangeEvent;
+
+/**
+ * A row was SOFT-deleted — an `update` that sets `deletedAt`.
+ *
+ * Not a `delete`, and that is the point. A test reaching for `changeDelete`
+ * here is describing a hard delete, which is a different event with different
+ * consequences: a soft delete is reversible, so anything cascading off it
+ * destroys rows a restore cannot bring back.
+ *
+ * `at` defaults to a fixed instant rather than `new Date()`: the value is never
+ * what a soft-delete rule reads — the null → non-null TRANSITION is — and a
+ * moving default makes a test that snapshots the event flake for no reason.
+ */
+export declare const changeSoftDelete: (table: string, row: Row, opts?: {
+    readonly at?: string | Date;
+    readonly column?: string;
+} & ChangeEventMeta) => ChangeEvent;
+
 /**
  * Whether the DataStore emits ChangeEvents inline from each write
  * (`inline`) or via the dialect's CDC consumer (`cdc`).
@@ -560,6 +586,9 @@ export declare type ChangeEvent = {
  */
 export declare type ChangeStrategy = 'inline' | 'cdc';
 
+/** A row changed. Both sides are present, because an update has both. */
+export declare const changeUpdate: (table: string, before: Row, after: Row, meta?: ChangeEventMeta) => ChangeEvent;
+
 /**
  * Claim the attribution for an echo, or `undefined` if this write did not
  * originate here.
@@ -683,6 +712,33 @@ export declare class ColumnBuilder<TsType, Type extends ColumnType, HasDefault e
      * neither.)
      */
     serverOnly(): this;
+    /**
+     * Restrict this column's WIRE visibility to subjects holding one of `scopes`.
+     * The graded middle of the exposure axis: a plain column is visible to every
+     * client, `.serverOnly()` hides it from every client, and
+     * `.readableBy('billing:read')` strips it from wire OUTPUT for any subject that
+     * holds NONE of the listed scopes while leaving it for one that holds ANY.
+     *
+     *     amountCents: integer().readableBy('billing:read'),
+     *     ssn:         text().readableBy('hr:read', 'admin:pii'),
+     *
+     * The scope strings are the SAME vocabulary as `guards:` / `ctx.access`, and
+     * are matched against the subject's EFFECTIVE scopes (raw subject scopes ∪ any
+     * rbac role-derived scopes). `admin:full` sees every `.readableBy()` column,
+     * exactly as it satisfies every guard. The strip runs at the runtime wire
+     * boundary (the Dispatcher's read chokepoint, shared with `.serverOnly()`), so
+     * server-internal `ctx.query` reads still see the value — this is an exposure
+     * concern, not an at-rest one.
+     *
+     * Declaration rules, both rejected at the schema file:
+     *   - at least ONE scope is required — `.readableBy()` with none would mean
+     *     "readable by nobody", which is `.serverOnly()`; the empty call is
+     *     almost always that mistake, so it throws rather than silently behaving
+     *     like `.serverOnly()`;
+     *   - each scope must be a non-blank string (a typo'd `''` never unlocks
+     *     anything, so it is refused up front).
+     */
+    readableBy(...scopes: ReadonlyArray<string>): this;
     /**
      * Mark this column as the row's OPTIMISTIC-CONCURRENCY version.
      *
@@ -733,6 +789,13 @@ export declare class ColumnBuilder<TsType, Type extends ColumnType, HasDefault e
      *
      * Pairs with {@link safe}: under a masking profile, every column in an
      * exported table must be one or the other, or the export refuses (fail-closed).
+     *
+     * NOT a wire-exposure or authorization control. This is the EXPORT-masking axis
+     * only; it never strips the column from a client response and never gates a
+     * read. To keep a column off the wire, use {@link serverOnly} (hidden from every
+     * client) or {@link readableBy} (hidden unless the subject holds a scope) — those
+     * are enforced at the runtime wire boundary. Marking a PII column `.sensitive()`
+     * does NOT stop it reaching an anonymous caller; that is a job for `.readableBy()`.
      */
     sensitive(cls: SensitivityClass): this;
     /**
@@ -1153,6 +1216,45 @@ export declare interface ColumnDefinition<TsType, Type extends ColumnType = Colu
      * COSTS is per command — see `serverOnly()` below for the matrix.
      */
     readonly serverOnly?: boolean;
+    /**
+     * Field-level read scopes, set by `.readableBy(...scopes)`. A NON-EMPTY list
+     * of scope strings; the column is stripped from wire OUTPUT for any subject
+     * that holds NONE of them, and present for a subject holding at least ONE.
+     * This is the graded middle of the exposure axis: `.serverOnly()` hides a
+     * column from EVERYONE on the wire, a plain column is visible to everyone,
+     * and `.readableBy('billing:read')` is visible only to callers scoped for it.
+     *
+     * The scope strings are the SAME vocabulary as `guards:` / `ctx.access` — they
+     * are checked against the subject's EFFECTIVE scope set (raw subject scopes ∪
+     * any rbac role-derived scopes), and the `admin:full` bypass sees every
+     * `.readableBy()` column, exactly as it satisfies every guard. Empty here is a
+     * declaration error (`.readableBy()` with no scope would mean "nobody" — use
+     * `.serverOnly()` for that), so the field is never present as `[]`.
+     *
+     * Orthogonal to `.encrypted()` (storage-at-rest) and to `.sensitive()` /
+     * `.safe()` (export-time masking): this is purely the WIRE-exposure axis.
+     */
+    readonly readableBy?: ReadonlyArray<string>;
+    /**
+     * CRDT-managed marker, set by the `crdtText()` column constructor. When `true`
+     * the column holds an ENCODED CRDT state (opaque bytes — a Yjs update blob
+     * behind `@voltro/local-first`'s swappable backend) rather than a plain value.
+     *
+     * It changes NOTHING about the column's DDL or how the declarative differ
+     * treats it: the storage type is `bytes` (BYTEA / BLOB / LONGBLOB /
+     * VARBINARY), a normal storable type, and the planner compares it structurally
+     * like any other `bytes` column — introspection never reports this flag, and
+     * `sameColumnShape` never reads it, so a `crdtText()` column round-trips
+     * through a plan with zero churn (no phantom re-plan).
+     *
+     * What it DOES drive lives above the DDL, in the runtime write path: the
+     * MutationStore reads it (via the SchemaRegistry) to run the AUTHORITATIVE
+     * server-side merge on write — an incoming encoded update is folded into the
+     * stored state with `mergeCrdtStates` before the row is written, so two
+     * concurrent clients converge. Orthogonal to every other flag here; a CRDT
+     * column is just `bytes` with server-merge semantics.
+     */
+    readonly crdtManaged?: boolean;
     /**
      * Optimistic-concurrency marker, set by `.version()`.
      *
@@ -1514,6 +1616,49 @@ export declare const count: (alias?: string) => AggregateColumn;
 
 export declare const countDistinct: (column: string, alias?: string) => AggregateColumn;
 
+/**
+ * The names of a table's CRDT-managed columns (`crdtText()`). These store an
+ * encoded CRDT state as `bytes` and get an authoritative SERVER-SIDE merge on
+ * every write (the runtime folds the incoming update into the stored state
+ * before writing). Pure — no store, no context; the runtime's SchemaRegistry
+ * uses the same signal to gate `mergeCrdtStates` on the write path.
+ */
+export declare const crdtManagedColumns: (table: TableLike) => ReadonlyArray<string>;
+
+/**
+ * CRDT-managed text column — a field whose value is a CONFLICT-FREE replicated
+ * text document rather than a plain string. Two clients editing it at the same
+ * time converge without a last-write-wins loser.
+ *
+ * ```ts
+ * export const documents = table('documents', {
+ *   id:    id(),
+ *   title: text(),
+ *   body:  crdtText(),          // CRDT-managed field
+ * })
+ * ```
+ *
+ * STORAGE. The column stores the ENCODED CRDT state as `bytes` (BYTEA / BLOB /
+ * LONGBLOB / VARBINARY) — an opaque Yjs update blob produced by
+ * `@voltro/local-first`. There is no special DDL: to the declarative differ it
+ * is an ordinary nullable `bytes` column, so it plans and round-trips like any
+ * other (no phantom re-plan). The row type is `Uint8Array | null`; decode it to
+ * a string with `@voltro/local-first`'s `decodeCrdtText(state)`, and produce
+ * writes with a `crdtText()` handle's `.encode()`.
+ *
+ * NULLABLE by design: an insert may omit the column (no document yet), and the
+ * first write establishes the state. A stored `null` is treated as the empty
+ * document by the server merge.
+ *
+ * SERVER MERGE. The authoritative merge runs in the runtime on write: the
+ * MutationStore folds an incoming encoded update into the stored state with
+ * `mergeCrdtStates` before writing, and the reactive engine broadcasts the
+ * merged result. That is what makes the column converge; the browser-safe merge
+ * primitives it uses live in `@voltro/local-first` and never import the
+ * `database` handle.
+ */
+export declare const crdtText: () => ColumnBuilder<Uint8Array | null, "bytes">;
+
 /** The attribution on the current async stack, or `undefined` outside a request. */
 export declare const currentWriteAttribution: () => WriteAttribution | undefined;
 
@@ -2823,6 +2968,13 @@ export declare const isFileMigration: (value: unknown) => value is FileMigration
  *  but no user schema declares — never plan a drop for it. */
 export declare const isFrameworkOwnedLiveTable: (name: string) => boolean;
 
+/**
+ * Whether a table carries `localFirst()`. Pure reflection over its applied
+ * mixins — the same signal the runtime registry uses, exposed for tooling and
+ * for a client that builds its sync set from the schema.
+ */
+export declare const isLocalFirst: (table: LocalFirstMarked) => boolean;
+
 export declare const isMigrationDefinition: (value: unknown) => value is MigrationDefinition;
 
 /**
@@ -2991,6 +3143,38 @@ export declare type LeafOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' |
 /** Every currently-registered retention spec. The boot sweep reads this each tick. */
 export declare const listRetentions: () => ReadonlyArray<RetentionSpec>;
 
+/**
+ * Opt a table into local-first behaviour.
+ *
+ * ```ts
+ * export const documents = table('documents', {
+ *   id:    id(),
+ *   title: text(),
+ *   body:  crdtText(),                 // CRDT-managed field
+ * }).with(timestamps, tenant, localFirst())
+ * ```
+ *
+ * Adds no column — it is a marker the framework reflects on to sync + persist
+ * the table client-side. Compose it with `crdtText()` columns for converging
+ * rich fields; plain columns on a local-first table sync last-write-wins.
+ */
+export declare const localFirst: () => MixinDefinition<{}>;
+
+/** The minimum shape {@link isLocalFirst} reflects on — a table's applied
+ *  mixins. Compatible with `Table` from `@voltro/database`. */
+export declare interface LocalFirstMarked {
+    readonly appliedMixins: ReadonlyArray<AnyMixin>;
+}
+
+/**
+ * The names of the local-first tables in a schema (a record of `table()`s).
+ * The discovery surface a boot step / client-sync-set builder consumes to learn
+ * which tables get a local mirror + sync loop.
+ */
+export declare const localFirstTables: (schema: Readonly<Record<string, LocalFirstMarked & {
+    readonly tableName: string;
+}>>) => ReadonlyArray<string>;
+
 export declare const lt: <RowOf = Record<string, unknown>, K extends keyof RowOf & string = keyof RowOf & string>(column: K, value: RowOf[K]) => PredicateLeaf;
 
 export declare const lte: <RowOf = Record<string, unknown>, K extends keyof RowOf & string = keyof RowOf & string>(column: K, value: RowOf[K]) => PredicateLeaf;
@@ -4385,6 +4569,25 @@ declare interface RawSqlFragment {
     readonly dependsOn?: ReadonlyArray<string>;
 }
 
+/** One `.readableBy(...scopes)` column: the field NAME plus the scope set that
+ *  makes it visible. */
+export declare interface ReadableByColumn {
+    readonly column: string;
+    /** Non-empty — a subject holding ANY of these sees the column. */
+    readonly scopes: ReadonlyArray<string>;
+}
+
+/**
+ * The `.readableBy(...scopes)` columns of a table — the field-level read-scope
+ * layer of the wire-exposure axis. Each entry names a column and the scope set
+ * that unlocks it (a subject holding ANY of the scopes sees it; one holding
+ * NONE has it stripped from wire output). Empty when the table declares none —
+ * which lets the runtime strip stay subject-INDEPENDENT (and its read/diff memo
+ * shared) for the common table that has no per-field permissions. Pure — no
+ * store, no context.
+ */
+export declare const readableByColumns: (table: TableLike) => ReadonlyArray<ReadableByColumn>;
+
 /** Floating-point number. Postgres `DOUBLE PRECISION`, mysql/mariadb `DOUBLE`,
  *  mssql `FLOAT`, sqlite `REAL`. Drivers return JS numbers — no codec. Use for
  *  fractional values (ratings, percentages, measurements) where `integer()`
@@ -4768,6 +4971,50 @@ export declare const rowSchema: <T extends TableLike>(table: T, options?: {
     readonly omit?: ReadonlyArray<string>;
 }) => Schema.Schema.Any;
 
+/** The context a rule predicate is evaluated with. */
+export declare interface RuleContext {
+    /** Transactional store — read other tables in the mutation's snapshot. */
+    readonly store: RuleReadStore;
+    /** The calling subject (tenant / user), for tenant-aware rules. */
+    readonly subject: unknown;
+}
+
+/**
+ * What a rule predicate may return. `true` / `void` / `undefined` = the rule
+ * HOLDS. `false` = violated with the rule's default detail. A
+ * `RuleViolationDetail` object = violated, carrying per-row i18n params / a
+ * field pointer for THIS specific row.
+ */
+export declare type RuleOutcome = boolean | void | RuleViolationDetail;
+
+/**
+ * A rule predicate over the POST-WRITE row. Runs inside the mutation
+ * transaction. Return `true`/nothing when the invariant holds; return `false`
+ * or a `RuleViolationDetail` to signal a violation. May be async (cross-table
+ * reads).
+ */
+export declare type RulePredicate = (row: Record<string, unknown>, context: RuleContext) => RuleOutcome | Promise<RuleOutcome>;
+
+/** Minimal READ surface (a subset of `DataStore`) handed to a rule predicate —
+ *  the SAME transactional store the mutation writes through, so cross-table
+ *  reads share its MVCC snapshot and cannot race the write the rule guards. */
+export declare interface RuleReadStore {
+    query(descriptor: QueryDescriptor): Promise<ReadonlyArray<Record<string, unknown>>>;
+}
+
+/** Severity of a business rule. `error` rolls the mutation back; `warning`
+ *  logs + audits but lets the write commit (useful during data migrations). */
+export declare type RuleSeverity = 'error' | 'warning';
+
+export declare interface RuleViolationDetail {
+    /** i18n params for the violation message (per this row). */
+    readonly params?: Record<string, unknown>;
+    /** Field path the violation pinpoints, if any. */
+    readonly field?: string;
+    /** Human-readable message (fallback / dev aid). */
+    readonly message?: string;
+}
+
 /**
  * Run `fn` with `attribution` active for its whole (sync + awaited) execution.
  *
@@ -5278,6 +5525,12 @@ export declare interface Table<Name extends string, Fields extends Record<string
     readonly appliedUniques: ReadonlyArray<TableUnique>;
     readonly appliedFullText: ReadonlyArray<TableFullTextIndex>;
     readonly appliedChecks: ReadonlyArray<TableCheck>;
+    /**
+     * The cross-table business rules DECLARED on this table, set by
+     * `.rule(name, predicate)`. Evaluated by the runtime inside the mutation
+     * transaction (see `TableRule`); they emit no DDL.
+     */
+    readonly appliedRules: ReadonlyArray<TableRule>;
     /**
      * The name this table used to have, set by `.renamedFrom('old_name')`.
      * Named apart from the METHOD that sets it — one interface cannot carry both.
@@ -5539,6 +5792,38 @@ export declare interface Table<Name extends string, Fields extends Record<string
      * For a single-column check, `column.check(expr)` is the terser form.
      */
     check: <const CkName extends string>(name: CkName, expr: string) => Table<Name, Fields, Reactive, IxNames>;
+    /**
+     * Declare a CROSS-TABLE business rule (S3). Unlike `.check(name, expr)` — a
+     * single-row SQL `CHECK` the database enforces — a rule is a PREDICATE the
+     * runtime evaluates INSIDE the mutation's transaction, after the write and
+     * before commit. It can read OTHER tables in the same snapshot and rolls the
+     * mutation back with a typed `BusinessRuleViolation` on failure.
+     *
+     * The predicate receives the POST-WRITE row and a `context` whose `store` is
+     * the SAME transactional store the mutation wrote through. Return `true`
+     * (or nothing) when the invariant holds; return `false` or a
+     * `RuleViolationDetail` (i18n `params` / a `field` pointer) to signal a
+     * violation.
+     *
+     * ```ts
+     * table('invoices', { id: id(), total: integer() }).rule(
+     *   'totalMatchesLineItems',
+     *   async (row, { store }) => {
+     *     const items = await store.query(
+     *       lineItems.where(eq('invoiceId', row.id)).descriptor,
+     *     )
+     *     const sum = items.reduce((a, l) => a + (l.amount as number), 0)
+     *     return sum === row.total || { params: { computed: sum, declared: row.total } }
+     *   },
+     * )
+     * ```
+     *
+     * `severity: 'warning'` logs + audits the violation but lets the write
+     * commit (useful during data migration); the default `'error'` rolls back.
+     */
+    rule: <const RuleName extends string>(name: RuleName, predicate: RulePredicate, options?: {
+        readonly severity?: RuleSeverity;
+    }) => Table<Name, Fields, Reactive, IxNames>;
     /**
      * Declare a full-text-search index (S7). One method, three back-
      * ends:
@@ -5757,6 +6042,21 @@ export declare interface TableLike {
  *  Internally we always store the thunk form. */
 declare type TableRef = TableLike | (() => TableLike);
 
+/**
+ * A named cross-table business rule, attached by `.rule(name, predicate)`.
+ *
+ * UNLIKE `.check(name, expr)` — a single-row SQL `CHECK` emitted as DDL and
+ * enforced by the database — a rule is a PREDICATE the runtime evaluates INSIDE
+ * the mutation's transaction, AFTER the write and BEFORE commit. It can read
+ * OTHER tables in the same MVCC snapshot and rolls the whole mutation back
+ * (typed `BusinessRuleViolation`) on violation. It emits no DDL.
+ */
+export declare interface TableRule {
+    readonly name: string;
+    readonly predicate: RulePredicate;
+    readonly severity: RuleSeverity;
+}
+
 /** A page read failed while streaming a table. Carries the underlying store
  *  error as `cause` so callers can inspect the transient-ness for retry. */
 export declare class TableStreamError extends TableStreamError_base<{
@@ -6223,6 +6523,11 @@ export declare const viewSql: (v: View<string, Record<string, ColumnDefinition<u
 /** Stable mixin id — the runtime keys read-filtering off it. */
 export declare const VOLTRO_EXPIRES_MIXIN_ID = "voltro/expires";
 
+/** Stable mixin id — the runtime keys local-first discovery off it. Re-declared
+ *  (without importing this mixin) in the runtime's SchemaRegistry; kept in step
+ *  by `localFirstMixinId.test.ts`. */
+export declare const VOLTRO_LOCAL_FIRST_MIXIN_ID: "voltro/localFirst";
+
 /**
  * `_voltro_api_keys` — first-class API key management. Only the SHA-256 HASH
  * of a key is stored (`hashedKey`, unique); the raw token is shown once at