@voltro/database 0.17.0 → 0.19.0

package/dist/index.d.ts

@@ -159,6 +159,24 @@ export declare const arrayOverlaps: <RowOf = Record<string, unknown>, K extends
  */
 export declare const attachEagerLoads: (rows: ReadonlyArray<Row_2>, spec: WithSpec, sourceTable: TableLike, lookup: EagerLookup) => Promise<ReadonlyArray<Row_2>>;
 
+/**
+ * The attribution fields to spread onto a `ChangeEvent` at creation.
+ *
+ * Returns an object with the keys OMITTED rather than set to `undefined`, so an
+ * unattributed event is byte-identical to one from before this existed — no
+ * `traceId: undefined` appearing in a snapshot, a broadcast payload, or a
+ * consumer's `Object.keys`.
+ *
+ * **Call it where the event is CREATED, not where it is delivered.** A
+ * transactional write queues its events and flushes them after commit, by which
+ * time the async-local scope is gone. Stamping at creation is what makes the
+ * transactional path carry identity at all.
+ */
+export declare const attributionFields: () => {
+    traceId?: string;
+    subjectId?: string | null;
+};
+
 /**
  * Audit a list of tables in one call. Convenience for the CLI's boot
  * path; same shape as calling `auditTableIndexes` per table and
@@ -464,6 +482,32 @@ export declare type ChangeEvent = {
      * so the consumer must elect a single worker instead.
      */
     readonly origin?: 'inline' | 'injected';
+    /**
+     * The trace this write happened under — the SAME id `auditPlugin` records as
+     * `AuditEvent.traceId` and `voltro logs --trace` resolves.
+     *
+     * This is the correlation bridge. Without it `plugin-versioning` knows WHAT
+     * changed and the audit sink knows WHO called and whether it was refused, and
+     * nothing joins the two. With it, "what did this call touch" is one query.
+     *
+     * Absent means the write had no request behind it: a seed, a `*.startup.tsx`,
+     * a schedule, a workflow step — or an event injected from another replica.
+     * For `origin: 'injected'` the honest answer is the ORIGINATING replica's
+     * trace or nothing at all; stamping the receiving replica's ambient trace
+     * would attribute a remote write to a local request, which is worse than
+     * silence.
+     */
+    readonly traceId?: string;
+    /**
+     * The acting identity behind the write — the same one `audit()` stamps into
+     * `createdBy`/`updatedBy`, so a row's stamp and its change event never
+     * disagree. For an API-key subject that is the person, not the credential;
+     * which key was used is recoverable from the audit row sharing `traceId`.
+     *
+     * `null` = a resolved subject with no acting user (anonymous / system).
+     * `undefined` = no request context at all. The two are different facts.
+     */
+    readonly subjectId?: string | null;
 };
 
 /**
@@ -492,6 +536,9 @@ export declare const clearRetentions: () => void;
 /** Wipe — used by tests + the dev-loop hot-reload. */
 export declare const clearTableRegistry: () => void;
 
+/** Test seam / dev-restart seam. */
+export declare const clearWriteRecorders: () => void;
+
 /**
  * The value to bind for `column`, given what the table declares it as.
  * Returns `value` unchanged whenever nothing unambiguous applies — including
@@ -564,8 +611,25 @@ export declare class ColumnBuilder<TsType, Type extends ColumnType, HasDefault e
      *     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.
+     * the client. The `crud.*` read helpers strip it from every returned row.
+     *
+     * A HAND-WRITTEN query output is the case `crud.*` cannot cover, so an audit
+     * checks it: a wire-reachable query whose `source` table carries a serverOnly
+     * column that its output DECLARES. What that costs depends on the command,
+     * and the difference is deliberate — a refused boot mid-edit is worse than
+     * the bug; in production it is not:
+     *
+     * | command                        | on a leak                          |
+     * |--------------------------------|------------------------------------|
+     * | `voltro serve`                 | **boot fails**                     |
+     * | `voltro doctor`                | **exits non-zero**                 |
+     * | `voltro dev`                   | warns                              |
+     *
+     * `VOLTRO_SERVER_ONLY=strict` makes `voltro dev` fail too; `=warn` downgrades
+     * serve; `=off` silences it. (`voltro check` does NOT run this — it has a
+     * live-api mode with no access to your table definitions, and a rule that
+     * fires in one of its two modes would be worse than one that fires in
+     * neither.)
      */
     serverOnly(): this;
     /**
@@ -1005,8 +1069,9 @@ export declare interface ColumnDefinition<TsType, Type extends ColumnType = Colu
      * 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.
+     * it automatically, and an audit flags a wire-reachable query whose `source`
+     * table carries a serverOnly column that its output declares. What that audit
+     * COSTS is per command — see `serverOnly()` below for the matrix.
      */
     readonly serverOnly?: boolean;
     /**
@@ -1328,6 +1393,9 @@ export declare const count: (alias?: string) => AggregateColumn;
 
 export declare const countDistinct: (column: string, alias?: string) => AggregateColumn;
 
+/** The attribution on the current async stack, or `undefined` outside a request. */
+export declare const currentWriteAttribution: () => WriteAttribution | undefined;
+
 /**
  * The application's `database` handle. Indexed by table name; each entry is
  * a `Query` over the table's row type AND a `using()` constraint over the
@@ -2651,6 +2719,7 @@ export declare interface JsonFieldFilter {
     readonly inSet: (values: ReadonlyArray<unknown>) => PredicateLeaf;
     readonly notInSet: (values: ReadonlyArray<unknown>) => PredicateLeaf;
     readonly contains: (substring: string) => PredicateLeaf;
+    readonly startsWith: (prefix: string) => PredicateLeaf;
     readonly isNull: () => PredicateLeaf;
     readonly isNotNull: () => PredicateLeaf;
 }
@@ -2727,7 +2796,7 @@ export declare const lag: (column: string, offset?: number, alias?: string) => W
 
 export declare const lead: (column: string, offset?: number, alias?: string) => WindowBuilder;
 
-export declare type LeafOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'notIn' | 'contains' | 'arrayContains' | 'arrayOverlaps' | 'arrayHas' | 'isNull' | 'isNotNull' | 'spatial';
+export declare type LeafOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'notIn' | 'contains' | 'startsWith' | 'arrayContains' | 'arrayOverlaps' | 'arrayHas' | 'isNull' | 'isNotNull' | 'spatial';
 
 /** Every currently-registered retention spec. The boot sweep reads this each tick. */
 export declare const listRetentions: () => ReadonlyArray<RetentionSpec>;
@@ -2798,6 +2867,24 @@ export declare interface ManyToManyRelation {
     readonly targetKey: string;
 }
 
+/**
+ * A predicate that matches NO row — the "this caller may see nothing" case a
+ * row filter needs and the one it is most expensive to get wrong.
+ *
+ * The natural spelling is `inSet(col, [])`, and in many query builders that is
+ * the dangerous one: an empty `IN ()` gets dropped, and a DROPPED predicate does
+ * not narrow — it WIDENS, to the whole tenant. Here it is safe (the SQL
+ * compiler emits `FALSE`, the in-memory evaluator returns false, and both are
+ * pinned by tests) but an adopting team wrote `eq('id', '')` instead, because
+ * they could not tell from the outside and would not bet a visibility rule on
+ * it. They were right not to.
+ *
+ * So this exists to say the thing rather than encode it: a reviewer reading
+ * `MATCHES_NO_ROWS` sees the intent, where `eq('id', '')` looks like a bug and
+ * `inSet(col, [])` looks like an oversight.
+ */
+export declare const MATCHES_NO_ROWS: PredicateLeaf;
+
 /**
  * A mixin's materialised, SERIALIZABLE field shape: `FieldDefinitions<Input>`
  * run through `Resolve` so it's emitted as the concrete
@@ -4038,6 +4125,29 @@ declare interface RawSqlFragment {
  *  would truncate. */
 export declare const real: () => ColumnBuilder<number, "real", boolean>;
 
+/** One write, as the store sees it at the moment it happens. */
+export declare interface RecordedWrite {
+    readonly table: string;
+    readonly op: 'insert' | 'update' | 'delete';
+    /** Row AFTER the write — present on insert/update, null on delete. */
+    readonly next: Row | null;
+    /** Row BEFORE the write, where the store had it. */
+    readonly prev: Row | null;
+    /** Request identity, when the write had a request behind it. */
+    readonly traceId?: string | undefined;
+    readonly subjectId?: string | null | undefined;
+}
+
+/**
+ * Is ANY recorder interested in `table`?
+ *
+ * The stores call this on every write, so it is the hot path: a store with no
+ * recorders registered pays one `Map.size` check and nothing else, and never
+ * awaits. Keeping `routeEvent`'s cost at zero for the default configuration is
+ * what makes shipping this as an opt-in honest.
+ */
+export declare const recordsTable: (table: string) => boolean;
+
 /**
  * Foreign-key reference to another table's id column.
  *
@@ -4112,6 +4222,14 @@ export declare const registerRetention: (spec: RetentionSpec) => void;
  */
 export declare const registerTable: (table: TableLike) => void;
 
+/** Register (or replace) a recorder. Replacing is what a plugin re-activating
+ *  on a dev restart needs. */
+export declare const registerWriteRecorder: (id: string, registration: {
+    readonly recorder: WriteRecorder;
+    readonly tables: Iterable<string>;
+    readonly ownTables: Iterable<string>;
+}) => void;
+
 export declare type Relation = OneRelation | ManyRelation | ManyToManyRelation;
 
 /**
@@ -4331,6 +4449,23 @@ export declare const rowSchema: <T extends TableLike>(table: T, options?: {
     readonly omit?: ReadonlyArray<string>;
 }) => Schema.Schema.Any;
 
+/**
+ * Run `fn` with `attribution` active for its whole (sync + awaited) execution.
+ *
+ * Nesting is last-wins by design: a plugin that re-enters the store inside a
+ * handler is still acting under that request.
+ */
+export declare const runWithWriteAttribution: <T>(attribution: WriteAttribution, fn: () => T) => T;
+
+/**
+ * Run every recorder that claims `write.table`.
+ *
+ * Deliberately NOT error-swallowing — see the header. Swallowing here would
+ * reproduce the post-commit hole while looking like it had closed it, which is
+ * the worse of the two by a distance.
+ */
+export declare const runWriteRecorders: (append: TxnAppend, write: RecordedWrite) => Promise<void>;
+
 /**
  * Lower a tenant id to the safe identifier fragment used inside a
  * namespace name. ONLY `[a-z0-9_]` survive; every other character —
@@ -4643,6 +4778,26 @@ export declare const stampGeneratedId: <T extends Record<string, unknown>>(table
 /** `stampGeneratedId` over a batch. */
 export declare const stampGeneratedIds: <T extends Record<string, unknown>>(table: string, rows: ReadonlyArray<T>) => ReadonlyArray<T>;
 
+/**
+ * Prefix match on a text column — `startsWith('key', 'awb_')`.
+ *
+ * **Case-SENSITIVE**, unlike {@link contains}, and the asymmetry is deliberate
+ * rather than an oversight. `contains` is a search primitive (a human typing
+ * into a box), so folding case is what they mean. A prefix is a NAMESPACE — a
+ * key prefix, a path segment, a tenant-scoped id — where `awb_` and `AWB_` are
+ * two different namespaces and quietly merging them is a bug. It also matches
+ * the semantics of the JS method it is named after.
+ *
+ * It is the one string predicate a database can answer from an index: it lowers
+ * to `LIKE 'literal%'`, which a btree on the column can range-scan. `contains`
+ * (`%…%`) and a suffix match cannot, which is why there is no `endsWith` —
+ * `contains` already covers the un-indexable case and a second un-indexable
+ * operator would only look cheaper than it is.
+ *
+ * `%` and `_` in the argument are escaped, so the value is matched literally.
+ */
+export declare const startsWith: <RowOf = Record<string, unknown>, K extends keyof RowOf & string = keyof RowOf & string>(column: K, prefix: string) => PredicateLeaf;
+
 /**
  * Stream every row of a table as a lazy `Stream<Row>`, keyset-paginated so
  * memory stays flat regardless of table size. Backpressure is inherent: a
@@ -5313,6 +5468,9 @@ export declare const timestampMs: Schema.Schema<Date, number>;
  */
 export declare const timestampMsOrNull: Schema.Schema<Date | null, number | null>;
 
+/** Append one row inside the caller's transaction. Insert-only by design. */
+export declare type TxnAppend = (table: string, row: Row) => Promise<void>;
+
 /** The minimal store surface `insertRow` needs — satisfied by `ctx.store`. */
 export declare interface TypedInsertStore {
     readonly insert: (table: string, row: Row) => Promise<Row>;
@@ -5366,6 +5524,8 @@ export declare interface UniqueSpec {
     readonly dedup?: 'fail' | 'suffix-counter' | Statement.Fragment;
 }
 
+export declare const unregisterWriteRecorder: (id: string) => void;
+
 /**
  * Bulk-update rows matching `where`, typed against the table: the patch is a
  * `Partial<InferRow<T>>`, so a misspelled column or a value of the wrong type
@@ -5712,4 +5872,22 @@ export declare interface WindowSpec {
 /** Tree of relations to eager-load. */
 export declare type WithSpec = Readonly<Record<string, true | EagerLoadSpec>>;
 
+/**
+ * Who is writing, and under which call.
+ *
+ * `subjectId` is the ACTING identity — the same one the `audit()` mixin stamps
+ * into `createdBy`/`updatedBy`. For an API key that is the person behind the
+ * credential, not the credential: two answers to "who wrote this row" on one
+ * write would be worse than one. Which KEY was used is recoverable from the
+ * audit sink row sharing this `traceId` — that is what the bridge is for.
+ */
+export declare interface WriteAttribution {
+    readonly traceId?: string;
+    /** `null` is meaningful: a resolved subject with no acting user (an
+     *  anonymous or system call), as distinct from `undefined` = no request. */
+    readonly subjectId?: string | null;
+}
+
+export declare type WriteRecorder = (append: TxnAppend, write: RecordedWrite) => Promise<void>;
+
 export { }