@voltro/database 0.18.0 → 0.20.0

package/dist/index.d.ts

@@ -159,6 +159,30 @@ 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;
+};
+
+/** The write's identity, as both sides can compute it. NOT the row image: the
+ *  transport re-encodes values (dates as strings, numbers as strings on some
+ *  drivers), so an image hash would disagree across the two sides and silently
+ *  never match. `(table, op, pk)` is stable through any re-encoding. */
+export declare const attributionKey: (table: string, op: string, primaryKey: unknown) => string;
+
 /**
  * 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 +488,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;
 };
 
 /**
@@ -478,9 +528,22 @@ export declare type ChangeEvent = {
  */
 export declare type ChangeStrategy = 'inline' | 'cdc';
 
+/**
+ * Claim the attribution for an echo, or `undefined` if this write did not
+ * originate here.
+ *
+ * Claiming REMOVES it: one registration answers exactly one echo, so a second
+ * echo of a different write to the same row cannot inherit the first's
+ * identity.
+ */
+export declare const claimPendingAttribution: (key: string) => WriteAttribution | undefined;
+
 /** Wipe — used by tests + the dev-loop hot-reload. */
 export declare const clearEnumRenames: () => void;
 
+/** Test seam. */
+export declare const clearPendingAttribution: () => void;
+
 /** Wipe the registry. Used by tests + the dev-loop hot-reload. */
 export declare const clearRelationsRegistry: () => void;
 
@@ -492,6 +555,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 +630,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 +1088,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 +1412,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
@@ -2799,6 +2886,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
@@ -3154,6 +3259,9 @@ export declare const paginateBy: (descriptor: QueryDescriptor, column: string, c
  */
 export declare const paginateById: (descriptor: QueryDescriptor, cursor: string | undefined, limit: number) => QueryDescriptor;
 
+/** Test seam — how many registrations are outstanding. */
+export declare const pendingAttributionCount: () => number;
+
 /**
  * Dispatch the provision plan by mechanism — the instant Neon CoW branch-create,
  * or the portable namespace snapshot fan-out. One call site for the cloud
@@ -4039,6 +4147,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.
  *
@@ -4093,6 +4224,15 @@ export declare const registerCoreTables: (options: CoreTableRegistration) => voi
  */
 export declare const registerDiscoveredRelations: (moduleExports: Record<string, unknown>) => number;
 
+/**
+ * Remember this write's attribution so its transport echo can be re-attributed.
+ *
+ * No-op when there is nothing to remember — a write with no request behind it
+ * must stay unattributed, and registering an empty entry would make the queue
+ * lie about which echo belongs to which write.
+ */
+export declare const registerPendingAttribution: (key: string, attribution: WriteAttribution) => void;
+
 /**
  * Register a single `relations()` spec. Multiple specs on the same
  * source MERGE — a second spec adds to the first one. A name
@@ -4113,6 +4253,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;
 
 /**
@@ -4332,6 +4480,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: (port: TxnRecorderPort, 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 —
@@ -5334,6 +5499,26 @@ 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>;
+
+/**
+ * `MAX(column)` over the rows matching an equality filter, on the caller's
+ * transaction connection. `null` when nothing matches.
+ *
+ * Equality-only and single-aggregate on purpose — see the header. It exists so
+ * an append-only trail can number its own entries; it is not a query facility,
+ * and widening it into one would give back exactly the read-modify-write reach
+ * this seam was shaped to withhold.
+ */
+export declare type TxnMaxOf = (table: string, column: string, where: Readonly<Record<string, string>>) => Promise<number | null>;
+
+/** Everything a recorder may do inside the caller's transaction. */
+export declare interface TxnRecorderPort {
+    readonly append: TxnAppend;
+    readonly maxOf: TxnMaxOf;
+}
+
 /** The minimal store surface `insertRow` needs — satisfied by `ctx.store`. */
 export declare interface TypedInsertStore {
     readonly insert: (table: string, row: Row) => Promise<Row>;
@@ -5387,6 +5572,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
@@ -5733,4 +5920,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 = (port: TxnRecorderPort, write: RecordedWrite) => Promise<void>;
+
 export { }