@voltro/database 0.11.3 → 0.12.0

package/dist/index.d.ts

@@ -492,6 +492,16 @@ export declare const clearRetentions: () => void;
 /** Wipe — used by tests + the dev-loop hot-reload. */
 export declare const clearTableRegistry: () => void;
 
+/**
+ * The value to bind for `column`, given what the table declares it as.
+ * Returns `value` unchanged whenever nothing unambiguous applies — including
+ * for an unknown column, which the column AUDIT reports rather than this.
+ */
+export declare const coercePredicateValue: (columnType: ColumnType | undefined, value: unknown) => unknown;
+
+/** Same, for the array-valued operators (`inSet` / `notInSet`). */
+export declare const coercePredicateValues: (columnType: ColumnType | undefined, values: ReadonlyArray<unknown>) => ReadonlyArray<unknown>;
+
 /**
  * Walk a predicate tree + yield every sub-query descriptor. The
  * store calls this before evaluating to know which sub-queries to
@@ -545,6 +555,19 @@ export declare class ColumnBuilder<TsType, Type extends ColumnType, HasDefault e
      * ciphertext on disk) — encrypt only what you read back whole.
      */
     encrypted(): this;
+    /**
+     * Mark this column SERVER-INTERNAL: server code reads it, but it must never be
+     * serialized to a client. The EXPOSURE axis, distinct from `.encrypted()`
+     * (storage-at-rest) — a `keyHash` an auth middleware verifies is `serverOnly`,
+     * a private note the owner may read is `encrypted` but not.
+     *
+     *     keyHash: text().serverOnly(),
+     *
+     * A column is exposed to both server and client by default; this opts it OUT of
+     * the client. The `crud.*` read helpers strip it from every returned row, and
+     * the boot audit fails a wire-reachable query that declares it in its output.
+     */
+    serverOnly(): this;
     /**
      * Classify this column as SENSITIVE — it holds personal / sensitive data of
      * `class` (`'email'`, `'fullName'`, `'phone'`, `'address'`, `'secret'`, …).
@@ -973,6 +996,19 @@ export declare interface ColumnDefinition<TsType, Type extends ColumnType = Colu
      * no cipher is registered.
      */
     readonly encrypted?: boolean;
+    /**
+     * Wire-exposure flag, set by `.serverOnly()`. When `true` the column is
+     * SERVER-INTERNAL: server code reads it normally (an auth middleware verifying
+     * a `keyHash`, say), but it must NEVER be serialized to a client. This is the
+     * EXPOSURE axis, orthogonal to `.encrypted()` (which is storage-at-rest): a
+     * column can be either, both, or neither — a hash you never ship is serverOnly
+     * but not encrypted; a private note the owner may read is encrypted but not
+     * serverOnly. The default is exposed to BOTH server and client; `.serverOnly()`
+     * opts a column OUT of the client. The table-aware read paths (`crud.*`) strip
+     * it automatically, and the boot audit flags a wire-reachable query whose
+     * `source` table carries a serverOnly column that its output declares.
+     */
+    readonly serverOnly?: boolean;
     /**
      * Data-sensitivity classification, set by `.sensitive(class)`. Declares that
      * this column holds personal / sensitive data of a given CLASS (`'email'`,
@@ -1200,7 +1236,19 @@ export declare const compileEagerJson: (descriptor: QueryDescriptor, sql: SqlCon
  * WHERE clause. Identifiers are quoted via `sql(col)`; values flow through
  * `sql\`${v}\`` as parameters — no string concatenation, no injection.
  */
-export declare const compilePredicate: (predicate: Predicate, sql: SqlConstructor, namespace?: QueryNamespace) => Statement.Fragment;
+export declare const compilePredicate: (predicate: Predicate, sql: SqlConstructor, namespace?: QueryNamespace, 
+/**
+ * The table this predicate filters, when the caller knows it. Supplied so a
+ * leaf's VALUE can be coerced to the column's shape — `eq('capturedAt',
+ * epochMs)` against a `timestamp()` column otherwise compiles to
+ * `WHERE capturedAt = 1767916800000` and matches nothing, silently. The write
+ * path has always encoded; this closes the asymmetry.
+ *
+ * Optional because `compilePredicate` is also called for JOIN conditions and
+ * by callers that hold only the AST. Absent → no coercion, i.e. exactly the
+ * previous behaviour.
+ */
+table?: string) => Statement.Fragment;
 
 /**
  * Rebind a captured {@link RawSqlFragment} onto a live `sql`
@@ -4443,6 +4491,14 @@ export declare type SensitivityClass = 'email' | 'fullName' | 'firstName' | 'las
  */
 export declare const serializeArraysForWrite: (row: Row, table: TableLike | undefined, dialect: DialectId) => Row;
 
+/**
+ * The names of a table's SERVER-ONLY columns (`.serverOnly()`) — columns that
+ * must never be serialized to a client. The table-aware read paths (`crud.*`)
+ * strip these from every returned row, and the boot audit checks a wire query's
+ * output against them. Pure — no store, no context.
+ */
+export declare const serverOnlyColumns: (table: TableLike) => ReadonlyArray<string>;
+
 /** Register the process-wide residency config (boot). Pass a config explicitly
  *  to the pure resolvers in tests instead. */
 export declare const setResidencyConfig: (config: ResidencyConfig) => ResidencyConfig;
@@ -4514,6 +4570,8 @@ export declare interface SpatialSpec {
     readonly bufferMeters?: number;
 }
 
+export { SqlClient }
+
 export declare type SqlConstructor = Statement.Constructor;
 
 /**