@voltro/database 0.20.2 → 0.22.0

package/dist/index.d.ts

@@ -173,9 +173,10 @@ export declare const attachEagerLoads: (rows: ReadonlyArray<Row_2>, spec: WithSp
  * time the async-local scope is gone. Stamping at creation is what makes the
  * transactional path carry identity at all.
  */
-export declare const attributionFields: () => {
+export declare const attributionFields: (explicit?: WriteAttribution | undefined) => {
     traceId?: string;
     subjectId?: string | null;
+    procedure?: string;
 };
 
 /** The write's identity, as both sides can compute it. NOT the row image: the
@@ -245,6 +246,12 @@ export declare interface BackfillSpec<TsType = unknown> {
     readonly sleepMs?: number;
 }
 
+/** Mark a non-transactional write to `table` as started. Pairs with
+ *  `endLocalWrite` in a `finally` — an unpaired begin holds that table's echoes
+ *  until `DEFER_BOUND_MS`, which is why the pairing is the store's job and not
+ *  the caller's. */
+export declare const beginLocalWrite: (table: string) => void;
+
 /**
  * 64-bit integer column — `BIGINT` on postgres / mysql / mariadb / mssql,
  * `INTEGER` (which is 64-bit) on sqlite / turso. Use for values that can
@@ -515,6 +522,17 @@ export declare type ChangeEvent = {
      * `undefined` = no request context at all. The two are different facts.
      */
     readonly subjectId?: string | null;
+    /**
+     * The rpc tag of the call that caused this write (`teams.removeSubTeamMember`).
+     *
+     * `traceId` says WHICH call; this says WHAT CALL IT WAS. The difference
+     * matters to anything rendering history for a human: a row diff carries no
+     * intent, and the same delete on a join table is a member removal, a cascade,
+     * or an expiry depending only on who asked. Absent for a write with no
+     * procedure behind it (seed, startup, migration, schedule) — same meaning as
+     * an absent `traceId`.
+     */
+    readonly procedure?: string;
 };
 
 /**
@@ -2111,6 +2129,11 @@ export declare const encryptedColumnsOf: (table: TableLike) => ReadonlyArray<str
  */
 export declare const encryptFieldsForWrite: (row: Row, table: TableLike | undefined, cipher: FieldCipher | undefined) => Row;
 
+/** Mark it finished — AFTER its `routeEvent` has registered, not after the
+ *  statement. That is the whole point: the window being closed is exactly the
+ *  gap between the committing statement and the registration. */
+export declare const endLocalWrite: (table: string) => void;
+
 /**
  * Enforce the storage-cost caps: evict live branches past their TTL, and report
  * whether a new branch would exceed `maxBranches` (counting only what survives
@@ -4169,6 +4192,10 @@ export declare interface RecordedWrite {
     /** Request identity, when the write had a request behind it. */
     readonly traceId?: string | undefined;
     readonly subjectId?: string | null | undefined;
+    /** The rpc tag of the call doing the writing. Same meaning and same absence
+     *  rules as `traceId`; carried so a transactional write records WHICH CALL
+     *  changed a row, not only which trace. */
+    readonly procedure?: string | undefined;
 }
 
 /**
@@ -4401,6 +4428,18 @@ declare type Resolve<T> = {
  */
 export declare const resolveBranchMechanism: (opts: BranchMechanismOptions) => BranchMechanism;
 
+/**
+ * Answer a transport echo with the attribution of the local write that produced
+ * it, or with `undefined` when the write came from another replica.
+ *
+ * `deliver` is called EXACTLY once — synchronously in the common case, and on a
+ * later turn only when a local write to the same table is mid-registration.
+ * Stores must emit through this rather than calling `claimPendingAttribution`
+ * themselves: the claim is the easy half, and the two dialect stores had a
+ * hand-written copy of it each, which is how a decision drifts.
+ */
+export declare const resolveEchoAttribution: (table: string, op: string, primaryKey: unknown, deliver: (attribution: WriteAttribution | undefined) => void) => void;
+
 /**
  * Resolve a `.fullTextIndex(name, ...)` declaration off the source
  * table so `.matching()` can stamp the covered columns + config onto
@@ -4977,6 +5016,23 @@ export declare interface Table<Name extends string, Fields extends Record<string
     readonly appliedUniques: ReadonlyArray<TableUnique>;
     readonly appliedFullText: ReadonlyArray<TableFullTextIndex>;
     readonly appliedChecks: ReadonlyArray<TableCheck>;
+    /**
+     * 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.
+     *
+     * The table-level twin of a column's `.renamedFrom()`, and it exists for the
+     * same reason: a rename and a drop+create are structurally identical to a
+     * differ (old table gone, new table present) and mean completely different
+     * things. Without the marker the planner has to assume drop + create, which
+     * for a TABLE is data loss, so it refuses — and the rename can only be done
+     * by hand.
+     *
+     * A chained method, matching a column's `.renamedFrom()` — the two mean the
+     * same thing one level apart, so they read the same. It survives every
+     * subsequent `.index(...)` / `.with(...)` because each rebuild spreads its
+     * options through.
+     */
+    readonly previousTableName?: string;
     /**
      * Composite PRIMARY KEY column set, declared via `.primaryKey(['a','b'])`.
      * When set it REPLACES the single-column `id()` PK assumption: no column
@@ -5313,6 +5369,23 @@ export declare interface Table<Name extends string, Fields extends Record<string
      * says so at boot.
      */
     nonReactive: () => Table<Name, Fields, false, IxNames>;
+    /**
+     * Declare the name this table used to have, so the planner folds what would
+     * otherwise be DROP + CREATE — the loss of every row — into an in-place
+     * `rename-table`.
+     *
+     * Deliberately the SAME SHAPE as a column's `.renamedFrom()`, because the two
+     * mean the same thing one level apart, and a reader who learned one will reach
+     * for the other. It first shipped as a third argument to `table()`; that made
+     * the one API in this family that had to be looked up.
+     *
+     *     export const notes = table('archive_notes', { … }).renamedFrom('notes')
+     *
+     * Drop the marker once the rename has been applied in every environment. A
+     * marker whose old table is absent is a silent no-op, so it can sit in source
+     * across a staged rollout.
+     */
+    renamedFrom: (oldName: string) => Table<Name, Fields, Reactive, IxNames>;
 }
 
 export declare const table: <const Name extends string, const Input extends FieldsInput>(name: Name, fields: Input) => Table<Name, FieldDefinitions<Input>, true, never>;
@@ -5962,6 +6035,34 @@ export declare interface WindowSpec {
     }>;
 }
 
+/**
+ * Capture the attribution ONCE, at a point that is synchronously inside the
+ * request, and hand it to `fn` — while ALSO re-entering the async-local scope for
+ * everything `fn` reaches that has not been threaded.
+ *
+ * WHY BOTH. Re-entering the scope alone is not enough, and that is measured
+ * rather than assumed. `AsyncLocalStorage` propagates through continuations the
+ * current context CREATES; a continuation scheduled by ANOTHER context — which is
+ * exactly what a connection-pool handoff does when an acquisition queues — resumes
+ * with whatever store that other context had. So a `routeEvent` running after
+ * `await runPromise(...)` can read an EMPTY scope under contention, and the write
+ * lands with `traceId`/`subjectId` NULL. NULL is a legal value there meaning "no
+ * request behind this write", so the result does not look like a defect; it looks
+ * like a schedule. In a compliance trail that asymmetry is the whole problem.
+ *
+ * A consumer could not reproduce it across 2700 writes at 96-way concurrency with
+ * every core saturated — which is good evidence the window is narrow at their load
+ * and no evidence at all that it is closed. Their own framing is why this is being
+ * closed structurally rather than left: *"impossible beats unlikely when the
+ * failure is invisible."*
+ *
+ * The captured value is passed EXPLICITLY down the write path; the re-entered
+ * scope is the fallback for any path not yet threaded. That ordering is deliberate
+ * — a site that has not been threaded behaves exactly as it does today rather than
+ * worse, so the threading can be verified site by site instead of all at once.
+ */
+export declare const withCapturedAttribution: <T>(fn: (attribution: WriteAttribution | undefined) => T) => T;
+
 /** Tree of relations to eager-load. */
 export declare type WithSpec = Readonly<Record<string, true | EagerLoadSpec>>;
 
@@ -5976,6 +6077,25 @@ export declare type WithSpec = Readonly<Record<string, true | EagerLoadSpec>>;
  */
 export declare interface WriteAttribution {
     readonly traceId?: string;
+    /**
+     * The rpc tag of the call doing the writing (`teams.removeSubTeamMember`).
+     *
+     * WHY IT IS HERE AND NOT DERIVED. A row change carries no intent. The same
+     * DELETE on `userTeams` is a member being removed, a team being deleted, a
+     * user being deleted, or a membership expiring — and the before/after diff
+     * cannot tell those apart, because the difference is not in the data. A
+     * consumer building an audit UI hit exactly this: `_voltro_row_history` could
+     * say "row X of userTeams changed" and show the JSON, and could not say "Anna
+     * removed Bernd from the Frontend sub-team".
+     *
+     * The tag is the missing anchor, and it is already known at the boundary that
+     * establishes this attribution, so it costs one field rather than an app-side
+     * hook that would have to reconstruct intent from shape.
+     *
+     * Absent for a write with no procedure behind it — a seed, a `*.startup.tsx`,
+     * a migration. Same meaning as an absent `traceId`.
+     */
+    readonly procedure?: 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;