@voltro/database 0.33.0 → 0.35.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { ConfigError } from 'effect';
+import { Context } from 'effect';
 import { Effect } from 'effect';
 import { Exit } from 'effect';
 import { Layer } from 'effect';
@@ -8,6 +9,7 @@ import { SqlClient } from '@effect/sql';
 import { SqlError } from '@effect/sql';
 import { Statement } from '@effect/sql';
 import { Stream } from 'effect';
+import { TransactionConnection } from '@effect/sql/SqlClient';
 import { VoidIfEmpty } from 'effect/Types';
 import { YieldableError } from 'effect/Cause';
 
@@ -182,6 +184,7 @@ export declare const attributionFields: (explicit?: WriteAttribution | undefined
     traceId?: string;
     subjectId?: string | null;
     procedure?: string;
+    via?: "agent";
 };
 
 /** The write's identity, as both sides can compute it. NOT the row image: the
@@ -316,6 +319,13 @@ export declare interface BranchExecutor {
     readonly createTable: (namespace: string, table: string) => Promise<void>;
     /** Copy one table's rows from the parent namespace into the branch (`INSERT … SELECT`). */
     readonly copyTable: (fromNamespace: string, toNamespace: string, table: string) => Promise<void>;
+    /** Replay one of the parent's foreign keys into the branch, re-pointed at the
+     *  branch's own copy of the target table. `LIKE … INCLUDING ALL` does not copy
+     *  foreign keys — see {@link BranchForeignKey} for why that is not optional. */
+    readonly addForeignKey: (namespace: string, fk: BranchForeignKey) => Promise<void>;
+    /** Restore an index's NAME, which the `LIKE` copy re-derived. Idempotent + a
+     *  no-op when the name already matches — see {@link BranchIndexName}. */
+    readonly restoreIndexName: (namespace: string, index: BranchIndexName) => Promise<void>;
     /** Drop the whole branch namespace (teardown). */
     readonly dropNamespace: (namespace: string) => Promise<void>;
     /** Create a Neon copy-on-write branch from `parentBranch`; RESOLVE to the new
@@ -325,6 +335,69 @@ export declare interface BranchExecutor {
     readonly neonBranchDelete: (branchId: string) => Promise<void>;
 }
 
+/**
+ * One foreign key to REPLAY into the branch namespace, re-pointed at the
+ * branch's own copy of the target table.
+ *
+ * This exists because of a silent fidelity hole in the namespace mechanism, and
+ * the hole is a property of Postgres rather than of our emission:
+ * `CREATE TABLE … (LIKE parent INCLUDING ALL)` copies columns, defaults, CHECK
+ * constraints, identity and indexes — and does NOT copy FOREIGN KEYS. There is
+ * no `INCLUDING` clause that does. So a namespace branch of a schema with
+ * referential integrity came up WITHOUT any of it: a PR preview bound to that
+ * branch accepts writes production rejects, and a migration rehearsed on it is
+ * rehearsing a different schema from the one it claims to.
+ *
+ * The caller supplies them (introspection already carries them per column, as
+ * `ColumnSnapshot.references`), because the branch primitive deliberately does
+ * no I/O of its own.
+ */
+export declare interface BranchForeignKey {
+    /** Table (in the branch) that carries the FK column. */
+    readonly table: string;
+    readonly column: string;
+    /** Referenced table — resolved to the BRANCH's copy, never the parent's. */
+    readonly targetTable: string;
+    readonly targetColumn: string;
+    readonly onDelete?: 'cascade' | 'restrict' | 'setNull' | 'noAction';
+    readonly onUpdate?: 'cascade' | 'restrict' | 'setNull' | 'noAction';
+}
+
+/**
+ * One index whose NAME must be restored on the branch.
+ *
+ * The second thing `LIKE … INCLUDING ALL` does not carry, found the same way as
+ * the foreign keys — by branching a real converged schema and watching the
+ * differ propose work. Postgres copies the index and **re-derives its name from
+ * the table and columns**; the source name survives only when it happened to
+ * equal that derivation. Measured on pg 17:
+ *
+ *     probeparent._voltro_api_keys     byApiKeyTenant
+ *     br_pr9_probe._voltro_api_keys    _voltro_api_keys_tenantId_idx
+ *     probeparent._voltro_idempotency  _voltro_idempotency_scope_key_uq
+ *     br_pr9_probe._voltro_idempotency _voltro_idempotency_scope_key_idx
+ *
+ * The planner compares indexes BY NAME, so every custom-named index on the
+ * parent reads as a different index on the branch: a rehearsal proposed
+ * `rename-index` plus a spurious `drop-unique-composite`/`add-unique-composite`
+ * pair for a schema that was already converged. Which is worse than noise — the
+ * rehearsal is supposed to be the thing that tells you what your migration does.
+ *
+ * PRIMARY KEYS are excluded: `<table>_pkey` is postgres's own derivation AND
+ * what four of the five introspectors fabricate, so the copy is already right.
+ * Expression indexes are excluded too — their key list carries no column to
+ * match on.
+ */
+export declare interface BranchIndexName {
+    readonly table: string;
+    /** Key columns IN INDEX ORDER — how the branch's copy is identified, since its
+     *  re-derived name is exactly what we do not know. */
+    readonly columns: ReadonlyArray<string>;
+    readonly unique: boolean;
+    /** The name the PARENT's index carries, and the one to restore. */
+    readonly name: string;
+}
+
 export declare interface BranchLimitDecision {
     /** Namespaces to tear down now (past TTL). */
     readonly evict: ReadonlyArray<string>;
@@ -375,6 +448,14 @@ export declare interface BranchPlanInput {
     readonly seed: BranchSeed;
     /** namespace only: the source schema to snapshot from (required for `'copy'`). */
     readonly parentNamespace?: string;
+    /** namespace only: the parent's foreign keys, replayed into the branch —
+     *  `LIKE … INCLUDING ALL` does not copy them. Ignored by `neon-cow`, whose
+     *  copy-on-write branch carries the parent's catalog verbatim. */
+    readonly foreignKeys?: ReadonlyArray<BranchForeignKey>;
+    /** namespace only: composite UNIQUE constraints whose NAME the `LIKE` copy
+     *  re-derived by the `LIKE` copy. Same reason as `foreignKeys` — a branch that
+     *  differs from the parent is not a copy of it. See {@link BranchIndexName}. */
+    readonly indexNames?: ReadonlyArray<BranchIndexName>;
     /** neon-cow only: the base Neon branch to copy-on-write from (default `'main'`). */
     readonly neonParentBranch?: string;
 }
@@ -393,6 +474,14 @@ export declare interface BranchProvisionRequest {
     readonly tableNames: ReadonlyArray<string>;
     /** namespace mechanism, `seed: 'copy'`: the source schema to snapshot from. */
     readonly parentNamespace?: string;
+    /** namespace mechanism: the parent's foreign keys, replayed into the branch
+     *  after the tables exist (and after the rows, for a `copy` seed). Omitting
+     *  them yields a branch with NO referential integrity — see
+     *  {@link BranchForeignKey}. */
+    readonly foreignKeys?: ReadonlyArray<BranchForeignKey>;
+    /** namespace mechanism: the parent's index names, restored on the branch after
+     *  the `LIKE` copy re-derived them — see {@link BranchIndexName}. */
+    readonly indexNames?: ReadonlyArray<BranchIndexName>;
     /** The owned-DB connection string (Neon detection drives the fast-path). */
     readonly dbUrl?: string;
     /** neon mechanism: the base branch to copy-on-write from (default `'main'`). */
@@ -431,7 +520,7 @@ export declare interface BranchSqlRunner {
 export declare type BranchState = 'requested' | 'provisioning' | 'ready' | 'destroying' | 'destroyed' | 'failed';
 
 export declare interface BranchStep {
-    readonly kind: 'create-namespace' | 'create-table' | 'copy-table' | 'seed' | 'drop-namespace' | 'neon-branch-create' | 'neon-branch-delete';
+    readonly kind: 'create-namespace' | 'create-table' | 'copy-table' | 'copy-foreign-key' | 'restore-index-name' | 'seed' | 'drop-namespace' | 'neon-branch-create' | 'neon-branch-delete';
     readonly detail: string;
     readonly table?: string;
 }
@@ -443,6 +532,37 @@ export declare class BranchTransitionInvalid extends Error {
     constructor(from: BranchState, event: BranchEvent);
 }
 
+/**
+ * Per-dialect ceilings, keyed by the same ids `DialectId` uses.
+ *
+ * Deliberately NOT a `Record<DialectId, …>` typed against the dialect union:
+ * `@voltro/database` owns both, so the union would compile-check the map — but
+ * the stores look their entry up by a string they hold anyway (mysql's store
+ * carries `variant: 'mysql' | 'mariadb'`), and an unknown key must degrade to
+ * "no chunking" rather than to `undefined.maxBindParameters` at runtime. The
+ * parity test asserts every shipped dialect has an entry, which is the check
+ * that actually matters.
+ */
+export declare const BULK_INSERT_LIMITS: Readonly<Record<string, BulkInsertLimits>>;
+
+/**
+ * What one `INSERT … VALUES` statement may carry on a dialect.
+ *
+ * Both bounds are real and independent; see the header for the mssql case where
+ * the row bound binds first.
+ */
+export declare interface BulkInsertLimits {
+    /** Bind parameters (`?` / `$n`) the engine accepts in ONE statement. */
+    readonly maxBindParameters: number;
+    /** Row constructors the engine accepts in one `VALUES` clause, when the
+     *  engine caps that separately. */
+    readonly maxRowsPerStatement?: number;
+}
+
+/** The ceilings for `dialectId`, or `undefined` when we do not know them —
+ *  which must read as "emit one statement, exactly as before". */
+export declare const bulkInsertLimitsFor: (dialectId: string) => BulkInsertLimits | undefined;
+
 /** Raw binary column — `BYTEA` (postgres) / `BLOB` (sqlite) / `LONGBLOB`
  *  (mysql/mariadb) / `VARBINARY(MAX)` (mssql). Values round-trip as
  *  `Uint8Array`. Use for storing bytes IN the database (e.g. the
@@ -500,6 +620,33 @@ export declare type ChangeEvent = {
     readonly op: 'insert' | 'update' | 'delete';
     readonly old: Row | null;
     readonly new: Row | null;
+    /**
+     * Set when the TRANSPORT could not carry this change's row images and they
+     * had to be RECONSTRUCTED. Absent on every ordinary event, which is the only
+     * case where `old`/`new` are the images as they were at commit.
+     *
+     * Postgres caps a `pg_notify` payload at 8000 bytes, and under
+     * `changeStrategy: 'cdc'` the NOTIFY trigger is the SOLE emitter — so a row
+     * that does not fit used to arrive with both images null and every tap
+     * (search index, analytics mirror, cdc-out, row history) dropped it as a
+     * non-event, permanently, with nothing logged. The CDC consumer re-reads the
+     * row by primary key before the event reaches anyone; this field says what
+     * that recovered:
+     *
+     *   - `'rehydrated'` — insert/update. `new` is the row RE-READ from the
+     *     database, so it is the row as it is NOW, not necessarily the image the
+     *     write that fired this event produced (a later write to the same row can
+     *     already have landed). `old` is null — postgres keeps no pre-image once
+     *     the transaction is gone.
+     *   - `'tombstone'` — delete. `old` carries the PRIMARY KEY AND NOTHING ELSE:
+     *     the row is gone, so the pre-image is unrecoverable and the key is the
+     *     whole truth. Enough to REMOVE the row downstream; not a snapshot of what
+     *     was deleted, and anything recording history must not treat it as one.
+     *   - `'unrecovered'` — both images are null. The change is known to have
+     *     happened and its content is not available (no key in the payload, the
+     *     re-read failed, or the row was already gone). Re-read or resync.
+     */
+    readonly oversized?: 'rehydrated' | 'tombstone' | 'unrecovered';
     /**
      * How the event reached this process. Absent/'inline' = emitted by this
      * process's own write path; 'injected' = delivered over a cross-instance
@@ -549,10 +696,16 @@ export declare type ChangeEvent = {
      * an absent `traceId`.
      */
     readonly procedure?: string;
+    /**
+     * The write was made BY AN AGENT acting as `subjectId`, not by that subject
+     * directly. Mirrors `WriteAttribution.via` — see it for why the identity is
+     * NOT changed instead. Absent = a direct call, which is a fact, not a gap.
+     */
+    readonly via?: 'agent';
 };
 
 /** Attribution and origin, identical on every constructor. */
-export declare type ChangeEventMeta = Pick<ChangeEvent, 'origin' | 'traceId' | 'subjectId' | 'procedure'>;
+export declare type ChangeEventMeta = Pick<ChangeEvent, 'origin' | 'traceId' | 'subjectId' | 'procedure' | 'via'>;
 
 /** A row was created. `old` is null, always. */
 export declare const changeInsert: (table: string, row: Row, meta?: ChangeEventMeta) => ChangeEvent;
@@ -589,6 +742,19 @@ 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;
 
+/**
+ * Split `rows` into groups that each fit in one statement on this dialect.
+ *
+ * Returns a single group whenever the whole array already fits — which is the
+ * overwhelmingly common case, and it must stay allocation-cheap and, more
+ * importantly, must keep emitting the SAME single statement it did before. A
+ * chunker that split a 3-row insert into 3 would be a correct implementation of
+ * the wrong thing.
+ *
+ * `undefined` limits (an unknown dialect) → one group, unchanged behaviour.
+ */
+export declare const chunkRowsForInsert: <T extends Record<string, unknown>>(rows: ReadonlyArray<T>, limits: BulkInsertLimits | undefined) => ReadonlyArray<ReadonlyArray<T>>;
+
 /**
  * Claim the attribution for an echo, or `undefined` if this write did not
  * originate here.
@@ -1468,6 +1634,18 @@ declare type ColumnOptionalForInsert<K extends PropertyKey, D> = K extends AutoF
  */
 export declare const columnSchema: <TsType, C extends ColumnType>(def: ColumnDefinition<TsType, C>) => Schema.Schema.Any;
 
+/**
+ * How many bind parameters one row costs.
+ *
+ * The MAX across rows, not the first row's count: `sql.insert` builds its
+ * column list from the union of the rows' keys and binds a value (a NULL where
+ * a row omits the column) in every position, so a set whose first row is narrow
+ * and whose tenth is wide costs the WIDE row's count for every row. Counting
+ * the first row would under-count exactly the shape most likely to be near the
+ * ceiling.
+ */
+export declare const columnsPerRow: (rows: ReadonlyArray<Record<string, unknown>>) => number;
+
 export declare type ColumnType = 'id' | 'text' | 'integer' | 'real' | 'decimal' | 'bigint' | 'boolean' | 'timestamp' | 'date' | 'json' | 'bytes' | 'reference' | 'vector' | 'enum' | 'array' | 'interval' | 'raw';
 
 /**
@@ -1564,6 +1742,75 @@ export declare interface ConnectionConfig {
      */
     readonly ssl?: boolean;
     readonly maxConnections?: number;
+    /**
+     * How long a caller waits for a free pooled connection before the acquire
+     * FAILS (ms). Default {@link DEFAULT_ACQUIRE_TIMEOUT_MS}; `0` restores the
+     * driver's own (unbounded) behaviour. Env `DB_ACQUIRE_TIMEOUT_MS`.
+     *
+     * This is the OTHER half of `statementTimeoutMs`. That one bounds a query the
+     * SERVER is running; nothing bounded a query the client had not sent yet — a
+     * request arriving when every pooled connection is busy did not fail, did not
+     * retry and logged nothing, it simply sat in the driver's queue. A bounded
+     * failure names the pool as the cause at the moment it IS the cause, instead
+     * of surfacing as an unexplained latency spike somewhere with no connection
+     * information in it.
+     *
+     * **What each dialect can actually enforce** — the drivers differ, and the
+     * difference is not papered over:
+     *   - **postgres** — exact. Maps to node-postgres' `connectionTimeoutMillis`,
+     *     which bounds BOTH establishing a new connection and waiting in the
+     *     pool's pending queue for a busy one (`pg-pool`'s `_pendingQueue`
+     *     timer). This is the full guarantee.
+     *   - **mysql/mariadb** — establishment only, and that is the whole of it.
+     *     mysql2's pool has NO time-based acquire bound at all
+     *     (`lib/base/pool.js` pushes the callback onto `_connectionQueue` with no
+     *     timer). The waiting half is UNBOUNDED by default and deliberately so —
+     *     see {@link ConnectionConfig.acquireQueueLimit} for the length bound
+     *     that exists, why it is opt-in, and what it costs.
+     *   - **mssql** — establishment only. Maps to `@effect/sql-mssql`'s
+     *     `connectTimeout` (tedious connect + the boot `SELECT 1` probe); its
+     *     pool is an Effect `Pool` whose `get` has no timeout knob.
+     *   - **sqlite** — ignored. One in-process connection, no pool to exhaust.
+     */
+    readonly acquireTimeoutMs?: number;
+    /**
+     * **mysql/mariadb only, OPT-IN, and a hazard** — how many callers may be
+     * QUEUED waiting for a free pooled connection before the next one fails
+     * immediately (mysql2's `queueLimit`). Unset by default (mysql2's own `0` =
+     * unbounded queue). Env `DB_ACQUIRE_QUEUE_LIMIT`.
+     *
+     * It looks like the mysql substitute for `acquireTimeoutMs`, which mysql2
+     * cannot express for the waiting phase. **It is not, and a default of 100
+     * shipped for exactly one change set before it wedged a process.** A LENGTH
+     * bound and a TIME bound are not interchangeable, and the difference is the
+     * reason this is opt-in:
+     *
+     * - A time bound self-throttles. The acquire fails only after the wait has
+     *   elapsed, so a caller that retries on failure retries no faster than the
+     *   timeout — a busy loop is impossible.
+     * - A length bound is free. Past the limit mysql2 rejects the acquire
+     *   **synchronously** (`lib/base/pool.js` — the queue-limit branch is the one
+     *   error return that does not go through `process.nextTick`), so a caller
+     *   that retries on failure retries at CPU speed, in the same tick, forever.
+     *   The event loop is never reached again: no timer fires, nothing drains the
+     *   queue that caused the rejection, and nothing is logged.
+     *
+     * That caller is not hypothetical and not ours to fix: `@effect/cluster`
+     * releases shards one statement per shard (300 by default) and wraps each in
+     * `Effect.eventually` — retry until success, no schedule, no delay, logged at
+     * debug. On a `shardLockDisableAdvisory` (Galera / PXC) runner those releases
+     * are pooled `DELETE FROM cluster_locks` statements, so every graceful
+     * shutdown queued ~290 acquires against a 10-connection pool, crossed the
+     * limit, and spun the process at 100% CPU with no output.
+     *
+     * So: set it only where you know nothing retries an acquire failure without a
+     * delay, and set it well above the fan-out of anything that might.
+     *
+     * Other dialects ignore it: postgres bounds the wait by TIME (which is
+     * strictly better — it does not care how many are ahead of you), and mssql's
+     * Effect `Pool` exposes neither.
+     */
+    readonly acquireQueueLimit?: number;
     /**
      * Per-statement timeout in ms — a runaway query (missing index, cartesian
      * join) is aborted instead of holding a pooled connection forever, which under
@@ -1602,6 +1849,22 @@ export declare interface ConnectionConfig {
     readonly schema?: string;
 }
 
+/**
+ * A stable, non-disclosing id for the database a connection points at.
+ *
+ * `undefined` when the inputs do not identify one — which a caller must treat as
+ * "cannot tell", never as "different".
+ */
+export declare const connectionIdentity: (input: ConnectionIdentityInput) => string | undefined;
+
+export declare interface ConnectionIdentityInput {
+    readonly dialect?: string | undefined;
+    readonly url?: string | undefined;
+    readonly host?: string | undefined;
+    readonly port?: number | undefined;
+    readonly database?: string | undefined;
+}
+
 /** Case-insensitive substring match on a text column. Non-indexable —
  *  always evaluated as an unindexed leaf (the matcher's pre-filter only
  *  recognizes eq/in/range). Lowers to `ILIKE '%…%'` on Postgres. */
@@ -2012,6 +2275,29 @@ export declare interface DbEnumHandle<Values extends ReadonlyArray<string>> {
     readonly column: () => ColumnBuilder<Values[number], 'enum'>;
 }
 
+export declare const dbMetricTagCacheSizeForTests: () => number;
+
+/**
+ * What kind of database work is being timed.
+ *
+ * A CLOSED union on purpose — it is a metric label, and a label whose value set
+ * is open is a cardinality incident waiting for the first caller who passes a
+ * table name. Adding a member here is a deliberate act with a matching entry in
+ * the docs' metrics table.
+ */
+export declare type DbOp = 'select' | 'insert' | 'update' | 'delete' | 'upsert' | 'raw' | 'transaction' | 'ddl';
+
+/** Current in-flight count for `dialect` — the gauge's value, for tests. */
+export declare const dbOperationsInFlight: (dialect: string) => number;
+
+/** One completed database operation. */
+export declare interface DbOpSample {
+    readonly dialect: DialectId | string;
+    readonly op: DbOp;
+    readonly durationMs: number;
+    readonly status: 'ok' | 'error';
+}
+
 /**
  * Fixed-point exact-decimal column — money, tax rates, anything where
  * floating-point rounding is unacceptable. Emits `NUMERIC(precision, scale)`
@@ -2089,6 +2375,34 @@ export declare const decryptFieldsOnRead: (rows: ReadonlyArray<Row>, table: Tabl
     }) => void;
 }) => ReadonlyArray<Row>;
 
+/**
+ * 10 s — the framework's default `ConnectionConfig.acquireTimeoutMs`.
+ *
+ * Long enough that a healthy pool under a burst never trips it (a connection is
+ * normally handed over in single-digit milliseconds) and short enough that "the
+ * pool is exhausted" reaches a log line while it is still the answer to a
+ * question somebody is asking. Every dialect that can bound an acquire reads
+ * THIS constant, so the number is one decision rather than four.
+ */
+export declare const DEFAULT_ACQUIRE_TIMEOUT_MS = 10000;
+
+/**
+ * How often a persistent fallback is allowed to say so.
+ *
+ * A once-per-table warning (the shape `makeOversizedReporter` uses) is right for
+ * a condition that either recovers or does not recur. This one is different: it
+ * is a PERMANENT per-query cliff, and after the single line scrolls out of the
+ * log there is nothing left to find. Re-warning on an interval keeps a
+ * still-degraded query present in a log an operator greps a week later, without
+ * turning a hot path into a log flood.
+ *
+ * Env: `VOLTRO_DB_EAGER_FALLBACK_WARN_INTERVAL_MS`. `0` warns once per
+ * (table, reason) and never again.
+ */
+export declare const DEFAULT_EAGER_FALLBACK_WARN_INTERVAL_MS = 300000;
+
+export declare const DEFAULT_SUBJECT_GRAPH_DEPTH = 4;
+
 export declare const defineMigration: (input: MigrationDefinitionInput) => MigrationDefinition;
 
 /**
@@ -2111,6 +2425,42 @@ export declare const defineSeed: (input: SeedDefinitionInput) => SeedDefinition;
 
 export declare const denseRank: (alias?: string) => WindowBuilder;
 
+/**
+ * Walk the schema outward from `subjectTable` and return every route to a table
+ * holding that subject's rows.
+ *
+ * Breadth-first with a visited set keyed on (table, foreignKey), so a cyclic
+ * schema terminates and a table reachable two ways contributes both routes ONCE
+ * each rather than looping. Two tables can legitimately be reached by different
+ * columns (`createdBy` and `updatedBy` both pointing at `actors`) and both are
+ * kept — dropping one would silently narrow an erasure.
+ */
+export declare const deriveSubjectGraph: (input: DeriveSubjectGraphInput) => SubjectGraph;
+
+export declare interface DeriveSubjectGraphInput {
+    /** The table whose primary key IS the subject id (`users`, `actors`, …). */
+    readonly subjectTable: string;
+    /** Every registered table. Defaults to the live table registry at call time —
+     *  a default rather than a fixed read, so a test can hand in a schema without
+     *  writing to a process-global other suites also use. */
+    readonly tables?: ReadonlyArray<TableLike>;
+    /** Every registered relation, as `allRegisteredRelations()` returns them.
+     *  Defaults to the live relations registry. */
+    readonly relations?: ReadonlyArray<{
+        readonly source: string;
+        readonly name: string;
+        readonly relation: Relation;
+    }>;
+    /**
+     * Hop ceiling. 4 is deep enough for `user → org-membership → project → task`
+     * and shallow enough that a densely-linked schema does not fan out into every
+     * table it has. Anything cut is REPORTED as `depth-truncated`.
+     */
+    readonly maxDepth?: number;
+    /** Tables never to walk INTO. */
+    readonly exclude?: ReadonlyArray<string>;
+}
+
 /**
  * Lower-cases + naively singularizes a table name into a typeid prefix.
  *
@@ -2167,6 +2517,57 @@ export declare interface DialectReplicationAdapter {
     compare(primaryPosition: string, replicaPosition: string): CaughtUpVerdict;
 }
 
+/**
+ * The parts of a transaction that are genuinely the DIALECT's. Anything not in
+ * here is owned by `runRetryingTransaction` / `runStoreTransaction` and must not
+ * be re-decided per store — see the header.
+ */
+export declare interface DialectTransactionSpec {
+    /** `<Store>.transactional` / `<Store>.runInNamespace` — prefixes the
+     *  missing-connection error so a failure names the entry point it came from. */
+    readonly label: string;
+    /**
+     * Which dialect this transaction belongs to — the `dialect` label on
+     * `voltro_db_queries_total{op="transaction"}` and its duration histogram.
+     *
+     * REQUIRED rather than derived from `span.attributes['db.system']`: that
+     * field carries OpenTelemetry's spelling (`postgresql`, not `postgres`) and
+     * mysql and mariadb share one value there, so a metric derived from it would
+     * silently merge two dialects. Required also means a new dialect store cannot
+     * be written without deciding what its transactions are called.
+     */
+    readonly dialect: DialectId;
+    /** The store's `sql.withTransaction` — issues BEGIN/COMMIT/ROLLBACK and
+     *  provides `TransactionConnection`. */
+    readonly withTransaction: <A>(effect: Effect.Effect<A, unknown, never>) => Effect.Effect<A, unknown, never>;
+    /** The store's managed runtime, ALWAYS as `runPromiseExit` — `runPromise` is
+     *  the bug this file exists to prevent, so the shared bracket never sees one. */
+    readonly runPromiseExit: <A>(effect: Effect.Effect<A, unknown, never>) => Promise<Exit.Exit<A, unknown>>;
+    /** Transient-contention predicate: pg `40001`/`40P01`, mysql deadlock/lock-wait,
+     *  sqlite `SQLITE_BUSY`, turso's MVCC write-write conflict, mssql `1205`. Drives
+     *  BOTH the retry schedule and the commit-defect promotion. */
+    readonly isRetryable: (e: unknown) => boolean;
+    /** OpenTelemetry span for the whole boundary (retries included). */
+    readonly span: {
+        readonly name: string;
+        readonly attributes: Readonly<Record<string, string>>;
+    };
+    /**
+     * Runs on the transaction's connection BEFORE the caller's work, once per
+     * attempt. Postgres' namespace binding (`SET LOCAL search_path TO "<ns>"`)
+     * is the only current use; it must be inside the transaction, on this
+     * connection, or a pooled handoff leaks the tenant's schema into the next
+     * request.
+     */
+    readonly prepare?: (conn: TransactionConnectionContext) => Effect.Effect<unknown, unknown, never>;
+    /**
+     * Wraps the finished program (retry + span already applied) immediately
+     * before it runs. Turso sets the fiber flag that upgrades `BEGIN` to
+     * `BEGIN CONCURRENT` here; every other dialect omits it.
+     */
+    readonly wrapProgram?: <A>(effect: Effect.Effect<A, unknown, never>) => Effect.Effect<A, unknown, never>;
+}
+
 /**
  * Drain accumulated WARN-level identifier messages. Called once by
  * `voltro dev` (and `voltro start`) after schema discovery so the boot
@@ -2216,6 +2617,26 @@ export declare class EagerCardinalityError extends Error {
     constructor(message: string);
 }
 
+export declare interface EagerFallbackEvent {
+    readonly dialect: DialectId | string;
+    readonly table: string;
+    readonly reason: EagerFallbackReason;
+    /** The error the JSON-agg statement threw. Absent for `not-compilable`. */
+    readonly error?: unknown;
+}
+
+/** Why an eager-load query is running on the walker instead of JSON-agg. */
+export declare type EagerFallbackReason = 
+/** `compileEagerJson` returned `null` — the shape is not compilable (an
+*  unregistered relation, an ambiguous inferred FK, or a namespaced read on a
+*  dialect whose JSON-agg compiler does not qualify identifiers). Steady
+*  state for a given query: it will never take the fast path. */
+'not-compilable'
+/** The compiled JSON-agg statement THREW and the walker re-ran the work. This
+*  is the one to alert on: the fast path exists, is being attempted, and is
+*  failing — so every such query pays BOTH paths. */
+| 'execute-failed';
+
 /**
  * Compiled JSON-aggregation plan: a `Statement.Statement` ready to
  * execute via `SqlClient.SqlClient`, plus a `decode()` that restores
@@ -2447,6 +2868,46 @@ export declare const expires: () => MixinDefinition<{
     readonly expiresAt: ColumnDefinition<Date | null, "timestamp", boolean>;
 }>;
 
+/**
+ * The ONE place `injectExternalChange`'s origin stamp is decided.
+ *
+ * Every store — memory + all four dialects — used to carry its own
+ * `{ ...event, origin: 'injected' }`, five hand copies of one subtle decision,
+ * which is precisely the shape this repo has twice watched drift (see the
+ * `settleTransactionExit` note in `voltro/CLAUDE.md`). Extracted so the rule has
+ * a single definition and `injectOriginParity.test.ts` can assert no store has
+ * grown a sixth.
+ *
+ * **The rule, and why it is `??` rather than an unconditional stamp.** The seam
+ * means "emit to local subscribers without persisting", and its overwhelming
+ * caller IS a transport (the postgres NOTIFY consumer, the mysql binlog reader,
+ * plugin-broadcast's bus) — so an event that states no origin is stamped
+ * `'injected'`. But one framework caller emits through this seam and is NOT a
+ * transport: `publishReactivity` wakes a reactivity CHANNEL, which has no row,
+ * no database and no peer behind it. That emission happened HERE, and calling it
+ * injected cost two things:
+ *
+ *   - a subscriber could not tell its OWN channel publish from a peer's, since
+ *     both arrived `'injected'`;
+ *   - plugin-broadcast's re-entrancy bracket suppresses re-publishes while it is
+ *     injecting, so a channel published synchronously from inside a change
+ *     listener never left the replica — silently.
+ *
+ * So a caller that KNOWS the emission is local says so, and that statement wins.
+ *
+ * `attribution` is merged UNDER the event on purpose: an event that already
+ * carries identity came from the originating replica and that identity wins over
+ * anything this replica has pending.
+ */
+export declare const externalChangeEvent: (event: ChangeEvent, attribution?: Partial<ChangeEventMeta>) => ChangeEvent;
+
+/** The subset of `@voltro/logger`'s logger this module needs. Structural so
+ *  this package keeps its browser-safe import surface. */
+export declare interface FallbackLogger {
+    readonly warn: (message: string, fields?: Record<string, unknown>) => void;
+    readonly debug: (message: string, fields?: Record<string, unknown>) => void;
+}
+
 /** The cipher the store middleware injects. Operates on opaque strings. */
 export declare interface FieldCipher {
     readonly encrypt: (plaintext: string) => string;
@@ -2543,6 +3004,26 @@ export declare interface FileMigrationContext {
     readonly appliedAt: string;
 }
 
+/**
+ * Fire the `onSchemaChange` seeds for the tables an apply just changed.
+ *
+ * Unlike tenant-create this does NOT propagate: a schema apply that succeeded
+ * must not be reported as failed because a data fixture threw. The runner logs
+ * + records the failure in `_voltro_seeds`.
+ */
+export declare const fireSchemaChangeSeeds: (event: SchemaChangeSeedEvent) => Promise<void>;
+
+/**
+ * Fire the `onTenantCreate` seeds for a freshly provisioned namespace.
+ *
+ * Awaited, and a rejection PROPAGATES to the provisioning caller on purpose:
+ * a tenant whose namespace exists but whose seed data does not is a broken
+ * tenant that reports success, which is the exact failure class this seam was
+ * built to remove. `provisionTenantNamespace` is idempotent, so the caller's
+ * retry is safe.
+ */
+export declare const fireTenantCreateSeeds: (event: TenantCreateSeedEvent) => Promise<void>;
+
 /** Flatten an intersection into a single object type for readable errors/hovers. */
 declare type Flatten<O> = {
     [K in keyof O]: O[K];
@@ -2565,6 +3046,10 @@ declare interface FormatIssueOptions {
     readonly indent?: string;
 }
 
+/** Human-readable rendering of a derived graph — what `voltro privacy scope`
+ *  prints, and what a DPO reads before signing off on a DSAR process. */
+export declare const formatSubjectGraph: (graph: SubjectGraph) => string;
+
 /**
  * Live tables the framework's own runtime creates under a name that does NOT
  * start with a reserved prefix, so the prefix rule below cannot recognise them.
@@ -3140,6 +3625,9 @@ export declare const lead: (column: string, offset?: number, alias?: string) =>
 
 export declare type LeafOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'notIn' | 'contains' | 'startsWith' | 'arrayContains' | 'arrayOverlaps' | 'arrayHas' | 'isNull' | 'isNotNull' | 'spatial';
 
+/** Every registration conflict since the last {@link clearRetentions}. */
+export declare const listRetentionConflicts: () => ReadonlyArray<RetentionConflict>;
+
 /** Every currently-registered retention spec. The boot sweep reads this each tick. */
 export declare const listRetentions: () => ReadonlyArray<RetentionSpec>;
 
@@ -3179,14 +3667,40 @@ export declare const lt: <RowOf = Record<string, unknown>, K extends keyof RowOf
 
 export declare const lte: <RowOf = Record<string, unknown>, K extends keyof RowOf & string = keyof RowOf & string>(column: K, value: RowOf[K]) => PredicateLeaf;
 
+/**
+ * Build the store-scoped fallback reporter: counts EVERY occurrence, logs a
+ * rate-limited line.
+ *
+ * Instance-scoped rather than a module global, for the reason
+ * `makeOversizedReporter` states: the rate limit must be the STORE's, so a
+ * second store in the same process (a read replica, a test harness) cannot
+ * silence the first one's first warning.
+ *
+ * The COUNTER is never rate-limited. That separation is the whole point of
+ * PERF-23 — the log line is for a human reading it at the moment it happens,
+ * and the counter is for the dashboard that has to show a cliff which started
+ * three weeks ago.
+ */
+export declare const makeEagerFallbackReporter: (log: FallbackLogger, options?: {
+    readonly warnIntervalMs?: number;
+    readonly now?: () => number;
+}) => ((event: EagerFallbackEvent) => void);
+
 /**
  * A concrete {@link BranchExecutor} for the NAMESPACE mechanism on Postgres — it
  * emits schema DDL + table-copy DML through an injected {@link BranchSqlRunner}.
  * `createTable` clones the parent table's STRUCTURE (`LIKE … INCLUDING ALL`);
- * `copyTable` snapshots its rows (`INSERT … SELECT`); teardown drops the schema.
+ * `copyTable` snapshots its rows (`INSERT … SELECT`); `addForeignKey` replays the
+ * referential integrity `LIKE` does not carry; teardown drops the schema.
  * The Neon ops throw — a copy-on-write branch needs a Neon connection (which
  * resolves to the `neon-cow` mechanism + its own executor).
  *
+ * POSTGRES ONLY, and the name is the whole warning: every statement here is
+ * postgres syntax (`CREATE SCHEMA`, `LIKE … INCLUDING ALL`, `"` quoting). MySQL /
+ * MariaDB spell the clone `CREATE TABLE x LIKE y` and quote with backticks;
+ * sqlite has no schema namespace to create. A caller on another dialect needs
+ * its own executor — the PLAN is dialect-agnostic, this executor is not.
+ *
  * Pure SQL emission: unit-tested with a recording runner (no live DB to BUILD or
  * TEST — only to RUN, like any SQL). The cloud wires `run` to its owned store.
  */
@@ -3482,6 +3996,15 @@ export declare const neq: <RowOf = Record<string, unknown>, K extends keyof RowO
  *  double-destroy or a provision-after-destroyed can't corrupt state). */
 export declare const nextBranchState: (current: BranchState, event: BranchEvent) => BranchState;
 
+/** The normalised `(host, port, database)` a connection points at, before
+ *  hashing. Exported for the tests — the digest is not readable, and a
+ *  normalisation bug in it would be invisible otherwise. */
+export declare const normaliseTarget: (input: ConnectionIdentityInput) => {
+    readonly host: string;
+    readonly port: number;
+    readonly database: string;
+} | undefined;
+
 /** Negate a sub-predicate: `not(eq('archived', true))` → `NOT (...)`.
  *  Wraps any subtree, including `and(...)`/`or(...)`. */
 export declare const not: (predicate: Predicate) => NotPredicate;
@@ -3506,6 +4029,16 @@ export declare interface NotPredicate {
  */
 export declare const numeric: (precision: number, scale?: number) => ColumnBuilder<string, "decimal">;
 
+/**
+ * Time `run`, count it, and hold the in-flight gauge for its duration.
+ *
+ * The `finally` is load-bearing in two directions: a throw must still be TIMED
+ * (a statement that fails after 30 seconds is the interesting one) and must
+ * still release the gauge, or a single failing query leaks a permanent +1 and
+ * the saturation signal drifts upward forever.
+ */
+export declare const observeDbOp: <T>(dialect: DialectId | string, op: DbOp, run: () => Promise<T>) => Promise<T>;
+
 /**
  * What a decrypt failure does. `'throw'` (default, and the ONLY safe production
  * behaviour) surfaces a typed `FieldDecryptionError`. `'null'` degrades the one
@@ -3650,10 +4183,18 @@ export declare const planBranch: (input: BranchPlanInput) => ReadonlyArray<Branc
 /**
  * The ordered steps to stand a branch up — what the cloud executor runs
  * (create-namespace + create-table via `provisionTenantNamespace`, copy-table
- * via cross-namespace `INSERT … SELECT`, seed via the boot seeds). Pure plan, so
+ * via cross-namespace `INSERT … SELECT`, copy-foreign-key via
+ * `ALTER TABLE … ADD CONSTRAINT`, seed via the boot seeds). Pure plan, so
  * it's unit-testable; the executor is the cloud side.
+ *
+ * The FK replay is sequenced AFTER the row copy on purpose: `INSERT … SELECT`
+ * per table has no topological order, so a child table copied before its parent
+ * would violate a constraint that is only correct once every table is populated.
+ * It is sequenced BEFORE the `fresh` seed for the mirror-image reason — seeds
+ * write through the app's own paths and should meet the same integrity rules
+ * production has.
  */
-export declare const planBranchProvision: (branchNamespace: string, tableNames: ReadonlyArray<string>, seed: BranchSeed, parentNamespace?: string) => ReadonlyArray<BranchStep>;
+export declare const planBranchProvision: (branchNamespace: string, tableNames: ReadonlyArray<string>, seed: BranchSeed, parentNamespace?: string, foreignKeys?: ReadonlyArray<BranchForeignKey>, indexNames?: ReadonlyArray<BranchIndexName>) => ReadonlyArray<BranchStep>;
 
 /** The teardown plan — drop the whole branch namespace (idempotent on the
  *  executor side). */
@@ -4583,11 +5124,22 @@ declare interface RawSqlFragment {
     readonly strings: ReadonlyArray<string>;
     readonly values: ReadonlyArray<unknown>;
     /**
-     * Tables this raw read depends on, for reactive invalidation. Raw
-     * reads are otherwise untracked — the query planner can't infer which
-     * tables an arbitrary SQL string touches. Declare them here (or via
-     * `store.raw(fragment, { dependsOn })`) to opt the read into the
-     * reactive layer's change-driven recomputation.
+     * Tables this raw read depends on, for reactive invalidation. Raw reads are
+     * otherwise untracked — the query planner cannot infer which tables an
+     * arbitrary SQL string touches. Declare them here (or via
+     * `store.raw(fragment, { dependsOn })`).
+     *
+     * WHAT IT DRIVES, stated narrowly because the previous wording promised more
+     * than any code delivered. For a live query whose handler returns a COMPUTED
+     * VALUE — the shape whose handler is genuinely re-run on a change — these
+     * tables JOIN the query's declared `source:`, so a write to one recomputes the
+     * subscription. That is the only shape where re-running can refresh a raw
+     * result. A handler that returns a query DESCRIPTOR re-runs the DESCRIPTOR on
+     * a change, not the handler, so declaring tables cannot refresh the raw read
+     * there; the runtime warns about that case at subscribe time instead.
+     *
+     * Best-effort in both directions: the tables are recorded as declared and
+     * never validated against the SQL.
      */
     readonly dependsOn?: ReadonlyArray<string>;
 }
@@ -4617,6 +5169,15 @@ export declare const readableByColumns: (table: TableLike) => ReadonlyArray<Read
  *  would truncate. */
 export declare const real: () => ColumnBuilder<number, "real", boolean>;
 
+/**
+ * Record one completed operation: the counter, the duration histogram, and — on
+ * a throw — the error counter.
+ *
+ * Prefer {@link observeDbOp}, which also moves the in-flight gauge and cannot
+ * forget the `error` arm on a throw.
+ */
+export declare const recordDbOp: (s: DbOpSample) => void;
+
 /** One write, as the store sees it at the moment it happens. */
 export declare interface RecordedWrite {
     readonly table: string;
@@ -4733,7 +5294,33 @@ export declare const registerPendingAttribution: (key: string, attribution: Writ
  */
 export declare const registerRelations: (spec: RelationsSpec) => void;
 
-/** Register (or replace) the retention bound for a table. Idempotent per table. */
+/**
+ * Register the retention bound for a table.
+ *
+ * ── Two registrations for one table used to be a silent last-write-wins ─────
+ *
+ * A consumer registered `_voltro_schedule_claims` at 1 hour from a startup, and
+ * one second later the framework registered its own default for the same table.
+ * Ours won, nothing said so, and their startup went on logging `bounded to 1h`
+ * at every boot while the table kept everything younger than the framework's
+ * TTL. They found it by counting rows, not by reading a log.
+ *
+ * `registry.set(table, spec)` is what did that, and the comment above it —
+ * "so a double-registration (e.g. plugin re-init) is idempotent" — describes a
+ * case that really exists (a plugin re-registering ITS OWN spec) and silently
+ * covered a different one.
+ *
+ * **Precedence now decides, and a real conflict is always reported.** An app's
+ * registration outranks a plugin's, which outranks a framework default; a tie
+ * keeps the later one, as before. `source` defaults to `'app'`, so an
+ * application does not have to know the field exists to win with it.
+ *
+ * The direction was not obvious and is worth stating: the loser here is chosen
+ * by WHO registered, not by which TTL is narrower. A narrower TTL deletes more,
+ * and picking "narrower wins" would let a framework default we tighten in some
+ * future release silently start deleting an app's data faster than the app
+ * asked for. Whoever owns the data decides; we are the fallback.
+ */
 export declare const registerRetention: (spec: RetentionSpec) => void;
 
 /**
@@ -4808,6 +5395,9 @@ export declare const requireTable: (tableName: string) => TableLike;
 
 export declare const requireTenants: () => (() => TableLike);
 
+/** Test seams for the cardinality guard — the caches are module-private otherwise. */
+export declare const resetDbMetricTagCacheForTests: () => void;
+
 /**
  * Re-read SNOWFLAKE_MACHINE_ID from the environment. Use in tests or
  * after a runtime reconfiguration. Production code should set the env
@@ -4874,6 +5464,13 @@ export declare const resolveActorSnapshot: (store: ActorLookupStore, subjectId:
  */
 export declare const resolveBranchMechanism: (opts: BranchMechanismOptions) => BranchMechanism;
 
+/** Resolve the re-warn interval. Env overrides the caller, like every other
+ *  tunable here; an unparseable or negative value falls through to the default
+ *  rather than being honoured. */
+export declare const resolveEagerFallbackWarnIntervalMs: (configured?: number | undefined, env?: {
+    readonly VOLTRO_DB_EAGER_FALLBACK_WARN_INTERVAL_MS?: string;
+}) => number;
+
 /**
  * Answer a transport echo with the attribution of the local write that produced
  * it, or with `undefined` when the write came from another replica.
@@ -4943,6 +5540,22 @@ export declare const resolveTenantHome: (tenantId: string | null | undefined, co
  */
 export declare const resolveTenantNamespace: (tenantId: string | null | undefined) => string;
 
+export declare interface RetentionConflict {
+    readonly table: string;
+    readonly kept: {
+        readonly source: RetentionSource;
+        readonly ttlMs: number;
+    };
+    readonly dropped: {
+        readonly source: RetentionSource;
+        readonly ttlMs: number;
+    };
+}
+
+/** Who registered a bound. Higher precedence first: an app's deliberate policy
+ *  outranks a plugin's, which outranks a framework default. */
+export declare type RetentionSource = 'app' | 'plugin' | 'framework';
+
 /** A registered bound on one append-only table. */
 export declare interface RetentionSpec {
     /** Physical table name, e.g. `_voltro_schedule_runs`. */
@@ -4961,6 +5574,16 @@ export declare interface RetentionSpec {
      * plain time-only purge.
      */
     readonly where?: Predicate;
+    /**
+     * Who registered this. Decides which registration wins when two arrive for
+     * one table — see {@link registerRetention}.
+     *
+     * DEFAULTS TO `'app'`, and that default is the feature: an application
+     * registering a bound has said something deliberate about ITS data, so it
+     * outranks a framework default without having to know this field exists. The
+     * framework and plugins pass their own value explicitly.
+     */
+    readonly source?: RetentionSource;
     /** Optional human label for logs (defaults to the table name). */
     readonly label?: string;
     /**
@@ -5048,6 +5671,57 @@ export declare interface RuleViolationDetail {
     readonly message?: string;
 }
 
+/**
+ * Run `body` inside one retrying transaction and settle its Exit.
+ *
+ * Owns, for every dialect:
+ *   1. the connection handshake — `withTransaction` + `TransactionConnection`,
+ *      with a loud failure rather than a silent non-transactional run when the
+ *      service is somehow absent;
+ *   2. **commit-defect promotion** — `@effect/sql` runs COMMIT as `Effect.orDie`,
+ *      so a serialization/deadlock error raised AT COMMIT arrives as a defect and
+ *      `Effect.retry` never sees it. A retryable defect is promoted back to a
+ *      typed failure so the schedule can replay it; anything else re-dies, so
+ *      genuine defects keep crash semantics;
+ *   3. the retry schedule — exponential backoff from 10ms, up to 3 retries,
+ *      gated on the dialect's `isRetryable`. Each attempt re-runs `body` from
+ *      scratch against a FRESH transaction;
+ *   4. the span, covering all attempts as one logical operation;
+ *   5. settling through `settleTransactionExit`, never `runPromise`.
+ *
+ * `body` receives the attempt number (1-based) so a caller can build per-attempt
+ * state that must not be shared across a retry.
+ */
+export declare const runRetryingTransaction: <A>(spec: DialectTransactionSpec & {
+    readonly body: (conn: TransactionConnectionContext, attempt: number) => Promise<A>;
+}) => Promise<A>;
+
+/**
+ * THE entry point every dialect store's `transactional()` — and postgres'
+ * `runInNamespace()` — routes through.
+ *
+ * On top of `runRetryingTransaction` it owns the two things that are about the
+ * CALLER rather than the engine:
+ *
+ *   - **write attribution.** Captured HERE, synchronously, before any await:
+ *     `transactional()` is entered from the request's async-local scope but the
+ *     callback runs from inside the Effect, where — measured against live
+ *     postgres — that scope is EMPTY. The captured value is handed to
+ *     `makeView` so every write the view makes carries the identity explicitly
+ *     (a pool handoff cannot strand it), and the scope is re-entered around
+ *     `work` for anything the view reaches that is not threaded. `undefined`
+ *     stays `undefined`: "no request behind this write" and "a request that knew
+ *     nothing" are different facts and must not blur.
+ *   - **event drain ordering.** A fresh view per attempt, and `commitEvents()`
+ *     only after the Exit settled successfully — so a retried attempt's buffered
+ *     events are dropped with its unreachable view and subscribers see exactly
+ *     the winning attempt, once.
+ */
+export declare const runStoreTransaction: <T, V extends DataStore & TransactionalViewHandle>(spec: DialectTransactionSpec & {
+    readonly work: (tx: DataStore) => Promise<T>;
+    readonly makeView: (conn: TransactionConnectionContext, attr: WriteAttribution | undefined) => V;
+}) => Promise<T>;
+
 /**
  * Run `fn` with `attribution` active for its whole (sync + awaited) execution.
  *
@@ -5065,6 +5739,16 @@ export declare const runWithWriteAttribution: <T>(attribution: WriteAttribution,
  */
 export declare const runWriteRecorders: (port: TxnRecorderPort, write: RecordedWrite) => Promise<void>;
 
+/**
+ * Are two connections pointed at the same database?
+ *
+ * Three answers, and the third is the load-bearing one: `'unknown'` means at
+ * least one side could not be identified, and the caller keeps whatever
+ * conservative behaviour it had. Collapsing that into `false` is how a guard
+ * stops guarding.
+ */
+export declare const sameDatabase: (a: string | undefined, b: string | undefined) => "same" | "different" | "unknown";
+
 /**
  * Lower a tenant id to the safe identifier fragment used inside a
  * namespace name. ONLY `[a-z0-9_]` survive; every other character —
@@ -5082,6 +5766,15 @@ export declare const runWriteRecorders: (port: TxnRecorderPort, write: RecordedW
  */
 export declare const sanitizeIdentifierFragment: (tenantId: string) => string;
 
+/** What a schema-change firing knows: which tables the apply actually touched.
+ *  A seed watches table NAMES (`watchedTables`), so this is the list the
+ *  runner intersects against — an empty list fires nothing. */
+export declare interface SchemaChangeSeedEvent {
+    readonly changedTables: ReadonlyArray<string>;
+}
+
+export declare type SchemaChangeSeedHook = (event: SchemaChangeSeedEvent) => Promise<void>;
+
 /**
  * The PUBLIC structural view of a built table — name, columns, and applied
  * indexes — with NONE of the fluent builder methods.
@@ -5129,6 +5822,7 @@ export declare interface SeedDefinition {
     readonly name: string;
     readonly lifecycle: SeedLifecycle;
     readonly cron?: string;
+    readonly timezone?: string;
     readonly watchedTables?: ReadonlyArray<string>;
     readonly fingerprint?: (ctx: {
         src: string;
@@ -5143,6 +5837,15 @@ export declare interface SeedDefinitionInput {
     readonly lifecycle: SeedLifecycle;
     /** Required for `lifecycle: 'cron'`. Standard cron expression or `@hourly`/`@daily` etc. */
     readonly cron?: string;
+    /**
+     * IANA timezone the `cron` expression is read in. Default `'UTC'`.
+     *
+     * Defaulted rather than required, unlike `defineSchedule`'s: a seed is
+     * reference data, so "02:00 in Europe/Berlin" is a much rarer requirement
+     * than it is for a business schedule — but server-local is never the answer,
+     * so the default is an explicit UTC rather than the container's clock.
+     */
+    readonly timezone?: string;
     /** Required for `lifecycle: 'onSchemaChange'`. Table names to watch. */
     readonly watchedTables?: ReadonlyArray<string>;
     /**
@@ -5268,6 +5971,12 @@ export declare const serverOnlyColumns: (table: TableLike) => ReadonlyArray<stri
  *  to the pure resolvers in tests instead. */
 export declare const setResidencyConfig: (config: ResidencyConfig) => ResidencyConfig;
 
+/** Install (or, with `null`, remove) the `onSchemaChange` runner. */
+export declare const setSchemaChangeSeedHook: (hook: SchemaChangeSeedHook | null) => void;
+
+/** Install (or, with `null`, remove) the `onTenantCreate` runner. */
+export declare const setTenantCreateSeedHook: (hook: TenantCreateSeedHook | null) => void;
+
 /**
  * Unwrap a transaction program's `Exit`: return the value, or throw the
  * ORIGINAL error rather than Effect's `FiberFailure` wrapper.
@@ -5490,6 +6199,51 @@ export declare interface StreamTableOptions {
     readonly retry?: Schedule.Schedule<unknown, TableStreamError>;
 }
 
+export declare interface SubjectGraph {
+    readonly subjectTable: string;
+    readonly paths: ReadonlyArray<SubjectPath>;
+    readonly limitations: ReadonlyArray<SubjectGraphLimitation>;
+}
+
+/** A known blind spot in a derived graph. Always reported. */
+export declare interface SubjectGraphLimitation {
+    readonly kind: 
+    /** BFS hit `maxDepth`; tables beyond `table` were not explored. */
+    'depth-truncated'
+    /** A table nothing links to the subject — invisible to this derivation. */
+    | 'unreachable'
+    /** Excluded by configuration. */
+    | 'excluded';
+    readonly table: string;
+    readonly detail: string;
+}
+
+/** One hop away from the previous table. */
+export declare interface SubjectHop {
+    /** The table this hop lands on. */
+    readonly table: string;
+    /** Column on `table` holding the PREVIOUS row's key. */
+    readonly foreignKey: string;
+    /** Column on the PREVIOUS table whose value `foreignKey` holds. Almost always
+     *  `id`; `sourceKey` on a relation can move it. */
+    readonly parentKey: string;
+}
+
+/**
+ * An ordered route from the subject table to a table holding their data.
+ * `hops` is empty for the subject table itself (the row keyed by the subject id).
+ */
+export declare interface SubjectPath {
+    /** Terminal table — where rows are read/erased. */
+    readonly table: string;
+    readonly hops: ReadonlyArray<SubjectHop>;
+    /** `hops.length`. 0 = the subject row itself, 1 = a direct child. */
+    readonly depth: number;
+    /** Which declaration produced it — a declared `relations()` block, an
+     *  inferred `reference()` column, or an app-supplied `subjectScopes` entry. */
+    readonly via: 'relation' | 'reference' | 'declared';
+}
+
 /**
  * `col IN (SELECT col FROM ...)` / `col NOT IN (SELECT ...)` — the
  * RHS is a sub-query descriptor. The sub-query MUST project a
@@ -6117,6 +6871,17 @@ export declare interface TableUnique {
  */
 export declare const teardownBranch: (branchId: string, mechanism: BranchMechanism, executor: BranchExecutor) => Promise<ReadonlyArray<BranchStep>>;
 
+/** What a tenant-create firing knows: which namespace was just provisioned. */
+export declare interface TenantCreateSeedEvent {
+    /** The namespace (postgres schema / mysql database / attached sqlite file)
+     *  that was just created. Seeds run scoped to THIS namespace, never the
+     *  shared one. */
+    readonly namespace: string;
+    readonly dialect: string;
+}
+
+export declare type TenantCreateSeedHook = (event: TenantCreateSeedEvent) => Promise<void>;
+
 /** A tenant's declared home — the region it's pinned to, optionally a named
  *  connection/secret key for that region's DB. */
 export declare interface TenantHome {
@@ -6212,6 +6977,22 @@ export declare const timestampMs: Schema.Schema<Date, number>;
  */
 export declare const timestampMsOrNull: Schema.Schema<Date | null, number | null>;
 
+/**
+ * A store's per-transaction `DataStore` view: buffers the ChangeEvents its
+ * writes produce and drains them to the parent emitter only once the
+ * transaction has actually committed.
+ */
+export declare interface TransactionalViewHandle {
+    commitEvents(): void;
+}
+
+/**
+ * The `[Connection, depth]` tuple `@effect/sql` provides inside
+ * `withTransaction`. Every statement that must run on the transaction's OWN
+ * connection (rather than a fresh one from the pool) is given this explicitly.
+ */
+export declare type TransactionConnectionContext = Context.Tag.Service<typeof TransactionConnection>;
+
 /** Append one row inside the caller's transaction. Insert-only by design. */
 export declare type TxnAppend = (table: string, row: Row) => Promise<void>;
 
@@ -6730,6 +7511,21 @@ export declare interface WriteAttribution {
     /** `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;
+    /**
+     * The write was made BY AN AGENT on the subject's behalf.
+     *
+     * `subjectId` stays the PERSON — an agent never escalates identity, which is
+     * the whole property `@voltro/ai`'s `agentActor` encodes. So without a second
+     * field, "Anna archived this invoice" and "an agent archived it while acting
+     * as Anna" are the same row, and the difference is the one a reviewer of an
+     * agent rollout actually asks about.
+     *
+     * Set by the transports that KNOW: the app-tool surface reached over MCP
+     * (`@voltro/cli`'s `agentToolSurface`) and any in-process `appTools` caller
+     * that opts in. Absent for an ordinary request — absent means "a human or a
+     * service called this directly", not "unknown".
+     */
+    readonly via?: 'agent';
 }
 
 export declare type WriteRecorder = (port: TxnRecorderPort, write: RecordedWrite) => Promise<void>;