@geonosis/db 0.3.0 → 0.5.1

package/dist/index.d.cts

@@ -54,25 +54,118 @@ type Connection = Executor & {
     transaction: <Result>(run: (tx: Executor) => Promise<Result>) => Promise<Result>;
 };
 
+/**
+ * The two session settings a tenant wall is built on, spelled once at the composition root.
+ *
+ * Neither has a default. A default here would be one repo's name — `app.org_id` at the repo this
+ * came from — compiled into every other repo's policies, and the seam and the policies must agree
+ * on it exactly or the wall is open while every test still passes.
+ */
+type SessionSettings = {
+    /** What maintenance sets to see every tenant, through a lever no request path can reach. */
+    opsSetting: string;
+    /** What the ops setting holds while the lever is pulled. */
+    opsValue?: string;
+    /** What a transaction sets to name the tenant it is open for, and what the policies read. */
+    tenantSetting: string;
+};
+declare const DEFAULT_OPS_VALUE = "on";
+
+/** A query that takes its session as an argument: what the seam wraps and what a provider writes. */
+type Query<Params, Result, Handle = Executor> = (handle: Handle, params: Params) => Promise<Result>;
+/**
+ * A statement as its parts: the SQL between the values, and the values themselves.
+ *
+ * The shape of a template literal — one more chunk than there are values — because that is what
+ * every library that places values already speaks. A driver renders it to numbered placeholders; an
+ * ORM hands it to its own tag. Nothing writes text for something else to read back out.
+ */
+type SqlFragment = {
+    chunks: readonly string[];
+    values: readonly unknown[];
+};
+/** A fragment from the SQL around one value, or from SQL alone. */
+declare const fragment: (chunks: readonly string[], values?: readonly unknown[]) => SqlFragment;
+/** A fragment as the executor port's statement: the values numbered where they stood. */
+declare const asStatement: (piece: SqlFragment) => Statement;
+/**
+ * How a session is opened and named on ONE kind of handle.
+ *
+ * The seam's own vocabulary is scopes and settings, never SQL text: a repo whose queries are an
+ * ORM's builders hands in the builders' way of saying `set_config`, and nothing in the middle
+ * writes a statement for something else to parse back.
+ */
+type SessionHandles<Handle> = {
+    /**
+     * Hold a handle to the lifetime of the invocation that opened it. `stillOpen` throws when that
+     * invocation has ended; a handle keeper calls this, and a seam never does.
+     */
+    guard?: (handle: Handle, stillOpen: () => void) => Handle;
+    /** Whether this handle can open a transaction, or is one already. */
+    opens: (handle: Handle) => boolean;
+    /** Send a statement to this handle, values and all, the way this kind of handle takes one. */
+    send: (handle: Handle, statement: SqlFragment) => Promise<QueryAnswer>;
+    transaction: <Result>(handle: Handle, run: (tx: Handle) => Promise<Result>) => Promise<Result>;
+};
+declare const DEFAULT_TENANT_KEY = "tenantId";
+type SessionSeam<Key extends string = typeof DEFAULT_TENANT_KEY, Handle = Executor> = {
+    inOps: <Result>(handle: Handle, run: (tx: Handle) => Promise<Result>) => Promise<Result>;
+    inTenant: <Result>(handle: Handle, tenantId: string, run: (tx: Handle) => Promise<Result>) => Promise<Result>;
+    scoped: <Params extends Readonly<Record<Key, string>>, Result>(query: Query<Params, Result, Handle>) => Query<Params, Result, Handle>;
+    scopedAsOps: <Params, Result>(query: Query<Params, Result, Handle>) => Query<Params, Result, Handle>;
+    /** Send a statement to a handle of this seam's kind — what a generated query is written over. */
+    send: (handle: Handle, statement: SqlFragment) => Promise<QueryAnswer>;
+    /** The key `scoped` reads a query's tenant out of, for whatever is generated over this seam. */
+    tenantKey: Key;
+};
+type SessionSeamConfig<Key extends string = typeof DEFAULT_TENANT_KEY, Handle = Executor> = {
+    /**
+     * How long a statement may run under the ops lever, as Postgres reads it. No default: a sweep's
+     * budget is a fact about one deployment's data, and the value that fits belongs to whoever runs
+     * it. Absent, the connection's own timeout stands.
+     */
+    opsStatementTimeout?: string;
+    /** The kind of handle this seam opens sessions on. The executor port when nothing is named. */
+    over?: SessionHandles<Handle>;
+    settings: SessionSettings;
+    /**
+     * The key a query's own parameters carry its tenant under (#245). A repo whose queries say
+     * `{ orgId }` names it here instead of wrapping every call site in `inTenant` by hand.
+     *
+     * A key name rather than a selector, measured: under `tenantOf: (params) => string` nothing ties
+     * the selector's shape to the query's, and a query whose parameters carry no tenant at all
+     * compiles clean — which is the one thing `scoped` is here to make impossible.
+     */
+    tenantKey?: Key;
+};
+/**
+ * The seam every query crosses: one transaction, the scope named as its first statement.
+ *
+ * `set_config(..., true)` is local to the transaction, which is what makes this safe on a pool —
+ * the name is gone when the transaction ends, and a connection handed to the next request carries
+ * nothing. Naming it second would leave the statements before it running under no tenant at all.
+ */
+declare const createSessionSeam: <Key extends string = typeof DEFAULT_TENANT_KEY, Handle = Executor>(config: SessionSeamConfig<Key, Handle>) => SessionSeam<Key, Handle>;
+
 type ConformanceCase = {
     name: string;
     run: () => Promise<void>;
 };
 /** A handle that reports every statement it sends, including the ones a transaction is made of. */
-type RecordingConnection = {
+type RecordingConnection<Handle = Executor> = {
     close: () => Promise<void>;
-    connection: Connection;
+    connection: Handle;
     statements: string[];
 };
 /** As much of a session seam as the exam asks about. */
-type SeamUnderTest = {
-    inOps: <Result>(executor: Executor, run: (tx: Executor) => Promise<Result>) => Promise<Result>;
-    inTenant: <Result>(executor: Executor, tenantId: string, run: (tx: Executor) => Promise<Result>) => Promise<Result>;
+type SeamUnderTest<Handle = Executor> = {
+    inOps: <Result>(handle: Handle, run: (tx: Handle) => Promise<Result>) => Promise<Result>;
+    inTenant: <Result>(handle: Handle, tenantId: string, run: (tx: Handle) => Promise<Result>) => Promise<Result>;
     /**
      * The wrapper that reads the tenant out of a query's own parameters. Spelled here rather than
      * imported: what the exam asks about is the behaviour, and a consumer's seam is their own type.
      */
-    scoped?: <Params extends Readonly<Record<string, string>>, Result>(query: (executor: Executor, params: Params) => Promise<Result>) => (executor: Executor, params: Params) => Promise<Result>;
+    scoped?: <Params extends Readonly<Record<string, string>>, Result>(query: (handle: Handle, params: Params) => Promise<Result>) => (handle: Handle, params: Params) => Promise<Result>;
     /** The key those parameters carry the tenant under. `tenantId` when the seam names none. */
     tenantKey?: string;
 };
@@ -88,16 +181,23 @@ type ProbeTable = {
     schema?: string;
     tenantColumn: string;
 };
-type SessionSubject = {
+type SessionSubject<Handle = Executor> = {
     /** A handle OUTSIDE every session: what the policies alone let through. */
-    connection: Connection;
+    connection: Handle;
     /** The tables whose FORCE is checked. The probe table alone, when nothing else is named. */
     guardedTables?: readonly string[];
     probe: ProbeTable;
-    recording: () => Promise<RecordingConnection>;
+    recording: () => Promise<RecordingConnection<Handle>>;
     /** Empty the probe table. Whatever role can do that — the exam's own rows are its business. */
     reset: () => Promise<void>;
-    seam: SeamUnderTest;
+    /**
+     * How the exam's own SQL reaches this handle: a `SessionHandles.send`, which every subject
+     * already has. The executor port's own when nothing is said. It takes the statement as its PARTS
+     * so a subject binds the exam's values the way its own library binds one — a subject that had to
+     * render them into text would be writing the concatenation this port's shape exists to prevent.
+     */
+    run?: (handle: Handle, statement: SqlFragment) => Promise<QueryAnswer>;
+    seam: SeamUnderTest<Handle>;
 };
 /**
  * The tenant wall, as the source proof took it: what a query with NO predicate can still see.
@@ -105,7 +205,7 @@ type SessionSubject = {
  * Every read here is unqualified on purpose. A test that filters by tenant proves its own WHERE
  * clause works; only an unfiltered one asks what the policy lets through.
  */
-declare const tenantIsolationConformance: (subject: SessionSubject) => ConformanceCase[];
+declare const tenantIsolationConformance: <Handle>(subject: SessionSubject<Handle>) => ConformanceCase[];
 /**
  * The census: a read costs what it says.
  *
@@ -114,12 +214,12 @@ declare const tenantIsolationConformance: (subject: SessionSubject) => Conforman
  * a second transaction nested inside the first. Twenty scoped reads against a pool of five is how
  * the source repo found this one.
  */
-declare const statementCensusConformance: (subject: SessionSubject) => ConformanceCase[];
+declare const statementCensusConformance: <Handle>(subject: SessionSubject<Handle>) => ConformanceCase[];
 /**
  * Two tenants at once on one pool — the case a suite that runs one tenant at a time never reaches,
  * and the one a pooled connection carrying a stale setting would fail.
  */
-declare const concurrentTenantsConformance: (subject: SessionSubject) => ConformanceCase[];
+declare const concurrentTenantsConformance: <Handle>(subject: SessionSubject<Handle>) => ConformanceCase[];
 /**
  * A query that names its own tenant, under the key the CONSUMER's queries carry it in (#245).
  *
@@ -128,26 +228,32 @@ declare const concurrentTenantsConformance: (subject: SessionSubject) => Conform
  * remove — and a wrapper that reads a key nobody carries names `undefined`, which is not a tenant
  * and, before this, was not a refusal either.
  */
-declare const scopedQueryConformance: (subject: SessionSubject) => ConformanceCase[];
+declare const scopedQueryConformance: <Handle>(subject: SessionSubject<Handle>) => ConformanceCase[];
 /**
  * ENABLE alone exempts the table's OWNER, and the owner is the role that migrates and the role an
  * ops sweep connects as. A wall only the application is behind is a wall with a door in it.
  */
-declare const forcedRowLevelSecurityConformance: (subject: SessionSubject) => ConformanceCase[];
+declare const forcedRowLevelSecurityConformance: <Handle>(subject: SessionSubject<Handle>) => ConformanceCase[];
 /** As much of a handle keeper as the exam asks about. */
-type ConnectionsUnderTest = {
-    sessionDb: () => Connection;
+type ConnectionsUnderTest<Handle = Connection> = {
+    open?: () => {
+        close: () => Promise<void>;
+        connection: Handle;
+    };
+    sessionDb: () => Handle;
     withConnection: <Result>(run: () => Promise<Result>, release?: (closing: Promise<void>) => void) => Promise<Result>;
 };
-type ConnectionsSubject = {
-    connections: ConnectionsUnderTest;
+type ConnectionsSubject<Handle = Connection> = {
+    connections: ConnectionsUnderTest<Handle>;
     /**
      * A unit of work, by name. A durable step's handle is the one that outlives its step, and a
      * refusal that cannot say WHICH step leaked sends a reader through every step in the workflow.
      */
     perStep?: (named: string) => <Output>(body: () => Promise<Output>) => Promise<Output>;
     /** Something any role may run. The exam asks a handle a question rather than assuming a table. */
-    probe?: Statement;
+    probe?: SqlFragment;
+    /** How the exam's own SQL reaches this handle. The executor port's own when nothing is said. */
+    run?: (handle: Handle, statement: SqlFragment) => Promise<QueryAnswer>;
 };
 /**
  * The handle discipline: a connection belongs to the invocation that opened it and to no other.
@@ -157,9 +263,9 @@ type ConnectionsSubject = {
  * some later line — "Cannot use a pool after calling end on the pool" — which reads as a bug in the
  * query rather than as a handle used out of its lifetime.
  */
-declare const connectionsConformance: (subject: ConnectionsSubject) => ConformanceCase[];
+declare const connectionsConformance: <Handle>(subject: ConnectionsSubject<Handle>) => ConformanceCase[];
 /** The whole exam: what a consumer runs against their own session before depending on it. */
-declare const sessionConformance: (subject: SessionSubject) => ConformanceCase[];
+declare const sessionConformance: <Handle>(subject: SessionSubject<Handle>) => ConformanceCase[];
 
 /** What one invocation may be told about itself, for the refusal a handle that outlives it raises. */
 type InvocationOptions = {
@@ -191,29 +297,40 @@ type OpenOptions = {
      */
     poolSize?: number;
 };
-/** A handle, and the way to give its connections back. */
-type OpenConnection = {
+/**
+ * A handle, and the way to give its connections back.
+ *
+ * The handle is a type parameter because a driver hands back what its consumer's queries are
+ * written against — the executor port, or the database an ORM opened — and a keeper that narrowed
+ * it would take that away again at the first `sessionDb()` (#266).
+ */
+type OpenConnection<Handle = Connection> = {
     close: () => Promise<void>;
-    connection: Connection;
+    connection: Handle;
 };
 /** The one thing in a deployment that knows which package speaks the wire protocol. */
-type Driver = {
+type Driver<Handle = Connection> = {
     migrate: (connectionString: string, migrationsFolder: string) => Promise<void>;
-    open: (connectionString: string, options?: OpenOptions) => OpenConnection;
+    open: (connectionString: string, options?: OpenOptions) => OpenConnection<Handle>;
 };
-type Connections = {
+type Connections<Handle = Connection> = {
     /** Whether this call is running inside an invocation frame. */
     inInvocation: () => boolean;
     /** A handle outside every frame, for a caller who will close it themselves. */
-    open: () => OpenConnection;
+    open: () => OpenConnection<Handle>;
     /** The handle this invocation is using, opened on first ask. */
-    sessionDb: () => Connection;
+    sessionDb: () => Handle;
     withConnection: <Result>(run: () => Promise<Result>, release?: (closing: Promise<void>) => void, invocation?: InvocationOptions) => Promise<Result>;
 };
-type ConnectionsConfig = {
+type ConnectionsConfig<Handle = Connection> = {
     connectionString: string;
-    driver: Driver;
+    driver: Driver<Handle>;
     open?: OpenOptions;
+    /**
+     * The kind of handle this driver returns — the same `over` the seam was built with. Only its
+     * `guard` is read here; the executor port's own when nothing is named.
+     */
+    over?: Pick<SessionHandles<Handle>, 'guard'>;
 };
 /**
  * The handles of one database, and the discipline that closes them.
@@ -223,7 +340,7 @@ type ConnectionsConfig = {
  * lifetime that matches, and the frame is what makes "this invocation" a thing the code can ask
  * about rather than a thing the caller has to thread through.
  */
-declare const createConnections: (config: ConnectionsConfig) => Connections;
+declare const createConnections: <Handle = Connection>(config: ConnectionsConfig<Handle>) => Connections<Handle>;
 /**
  * The `scope.perStep` hook a workflow engine asks for, answered with a connection per unit of work.
  *
@@ -242,6 +359,233 @@ declare const perStepConnection: (connections: Pick<Connections, "withConnection
     perStep: (named?: string) => <Output>(body: () => Promise<Output>) => Promise<Output>;
 };
 
+/**
+ * As much of a drizzle-orm Postgres database as this package uses, declared here rather than
+ * imported.
+ *
+ * drizzle-orm is an OPTIONAL peer, and a type imported from it would put it in this package's
+ * published `.d.ts` — a consumer who wanted the executor port and nothing else would then need it
+ * installed to typecheck. `tx: unknown` is what the real signature is assignable to: a transaction
+ * handle's type is the driver's own class, and a parameter narrower than `unknown` refuses it
+ * (measured against drizzle-orm 0.45.2).
+ */
+type DrizzleDatabase = {
+    execute: (query: never) => Promise<unknown>;
+    transaction: <Result>(run: (tx: unknown) => Promise<Result>) => Promise<Result>;
+};
+/**
+ * As much of drizzle-orm's `sql` as sending a statement takes.
+ *
+ * Not the TAG: the tag SPREADS an array value into a tuple — `any(($1, $2))` for one array, which
+ * is not the query anybody wrote — while `param` places whatever it is given as one parameter
+ * (measured against drizzle-orm 0.45.2). Method syntax because `join` types its chunks as drizzle's
+ * own mutable array of its own class, which no wider parameter is assignable to under strict
+ * variance.
+ */
+type DrizzleSql = {
+    join(chunks: unknown[], separator?: unknown): unknown;
+    param(value: unknown): unknown;
+    raw(text: string): unknown;
+};
+type DrizzleModuleLike = {
+    sql: DrizzleSql;
+};
+type DrizzleSessionOptions = {
+    /** drizzle-orm itself, for a runtime whose copy is patched. Loaded on demand when absent. */
+    drizzleOrm?: DrizzleModuleLike;
+};
+/**
+ * A session seam's handle port, over a drizzle database.
+ *
+ * `set_config` is built with drizzle's own `sql`, so the values are placed by the library that will
+ * send them and no statement is written for something else to parse back; and the transaction the
+ * database opens is handed to the query as it is, which is the whole point — a repo on drizzle
+ * writes its queries in builders, and a seam that hands back anything else is an adapter that repo
+ * has to write.
+ */
+declare const drizzleSession: <Db extends DrizzleDatabase>(options?: DrizzleSessionOptions) => Promise<SessionHandles<Db>>;
+
+/**
+ * The columns every entity table has besides its own. Named because a repo's are named, defaulted
+ * because the DDL this package renders spells them this way.
+ */
+type EntityColumns = {
+    /** The body: one column, the whole of what the entity is. */
+    body?: string;
+    /** Epoch milliseconds of the row's first write (D-050). */
+    createdAt?: string;
+    /** Epoch milliseconds of its retirement, null while it is alive. */
+    retiredAt?: string;
+    tenant?: string;
+    updatedAt?: string;
+};
+/** A row as a read hands it back: the key it is addressed by, its body, and its clocks. */
+type EntityRow<Body> = {
+    body: Body;
+    createdAt: number;
+    key: string;
+    updatedAt: number;
+};
+/** The listing index, in its own order. The last column is unique within one tenant. */
+type EntityOrdering = readonly {
+    column: string;
+    direction?: 'asc' | 'desc';
+}[];
+/** A page, and where the next one starts. `nextCursor` is absent on the last page, never empty. */
+type EntityPage<Item> = {
+    items: Item[];
+    nextCursor?: string;
+};
+declare const DEFAULT_ENTITY_PAGE = 50;
+declare const MAX_ENTITY_PAGE = 100;
+type EntityDefinition<Body, Item, Key extends string, Param extends string, Handle = Executor> = {
+    columns?: EntityColumns;
+    /**
+     * The columns kept beside the body, read OFF the body on every write. The body is the only
+     * source: a column a caller could set separately is a second answer to what the entity says.
+     */
+    indexed?: (body: Body) => Readonly<Record<string, unknown>>;
+    item: (row: EntityRow<Body>) => Item;
+    /** The column a row is addressed by, and the parameter that names it. */
+    key: {
+        column: string;
+        param: Param;
+    };
+    order: EntityOrdering;
+    schema?: string;
+    /** The session every one of the generated verbs runs inside (D-014). */
+    seam: SessionSeam<Key, Handle>;
+    table: string;
+};
+type Tenanted<Key extends string> = Readonly<Record<Key, string>>;
+type Addressed<Key extends string, Param extends string> = Tenanted<Key> & Readonly<Record<Param, string>>;
+type Keyed<Param extends string> = Readonly<Record<Param, string>>;
+type UpsertOutput<Body, Param extends string> = Keyed<Param> & {
+    previous: Body | null;
+};
+type RetireOutput<Body, Param extends string> = Keyed<Param> & {
+    retired: Body | null;
+};
+/**
+ * A compensating query, as the data an engine reads: what the forward step answered, and the tenant
+ * it ran for. The engine holds the connection and knows neither this entity's key nor its seam's.
+ */
+type EntityUndo<Output, Handle = Executor> = Query<{
+    output: Output;
+    tenantId: string;
+}, void, Handle>;
+type Entity<Body, Item, Key extends string, Param extends string, Handle = Executor> = {
+    get: Query<Addressed<Key, Param>, Item | null, Handle>;
+    list: Query<Tenanted<Key> & {
+        cursor?: string;
+        limit?: number;
+    }, EntityPage<Item>, Handle>;
+    listAll: Query<Tenanted<Key>, Item[], Handle>;
+    retire: Query<Addressed<Key, Param>, RetireOutput<Body, Param>, Handle>;
+    undos: {
+        retire: EntityUndo<RetireOutput<Body, Param>, Handle>;
+        upsert: EntityUndo<UpsertOutput<Body, Param>, Handle>;
+    };
+    upsert: Query<Addressed<Key, Param> & {
+        body: Body;
+    }, UpsertOutput<Body, Param>, Handle>;
+};
+/**
+ * One declaration per entity: one payload table, one business key, and every read, every write and
+ * both undos written once (#251).
+ *
+ * Every verb goes through the seam's `scoped`, so a tenant is named before any of them runs and
+ * there is no door here that skips one (D-014).
+ */
+declare const defineEntity: <Body, Item, Key extends string, Param extends string, Handle = Executor>(definition: EntityDefinition<Body, Item, Key, Param, Handle>) => Entity<Body, Item, Key, Param, Handle>;
+/**
+ * The compensations of an entity, by name — the registry a workflow engine reads as plain data.
+ *
+ * A door rather than a property so the engine has one thing to import and this package has one
+ * thing to keep: `@geonosis/db` and an engine are sibling foundations, and what crosses between
+ * them is the shape.
+ */
+declare const undosOf: <Body, Item, Key extends string, Param extends string, Handle>(entity: Entity<Body, Item, Key, Param, Handle>) => Entity<Body, Item, Key, Param, Handle>["undos"];
+
+/** As much of a generated entity as the exam asks about; a consumer's own is their own type. */
+type EntityUnderTest<Body, Item, Handle> = Entity<Body, Item, string, string, Handle>;
+type EntitySubject<Body, Item, Handle = Executor> = {
+    /** Two bodies for the same row: what is written first, and what replaces it. */
+    bodies: readonly [Body, Body];
+    /** The body an item carries, for an exam that cannot know what a definition maps to. */
+    bodyOf: (item: Item) => Body;
+    connection: Handle;
+    entity: EntityUnderTest<Body, Item, Handle>;
+    /** Three keys, in the order this entity's listing index puts them. */
+    keys: readonly [string, string, string];
+    /** The parameter the entity addresses a row by. */
+    keyParam: string;
+    /** Empty the table. Whatever role can do that — the exam's own rows are its business. */
+    reset: () => Promise<void>;
+    /**
+     * A handle that reports every statement it sends, the transaction's own begin and commit
+     * included. Without it the write census is untested rather than passing.
+     */
+    recording?: () => Promise<RecordingConnection<Handle>>;
+    /** The key the entity's queries carry their tenant under. */
+    tenantKey: string;
+    /**
+     * The wall this entity's table was rendered with, and the lever that reaches past it. Supplied,
+     * the exam checks that the DDL, the policies and the session all name the SAME two settings —
+     * which no default-named table can show, because every one of the three would be wrong together.
+     */
+    wall?: {
+        /** Every row of the table, no predicate and no tenant: what the policy alone lets through. */
+        countAll: (handle: Handle) => Promise<number>;
+        inOps: <Result>(run: (tx: Handle) => Promise<Result>) => Promise<Result>;
+        settings: {
+            opsSetting: string;
+            tenantSetting: string;
+        };
+    };
+};
+/**
+ * The generated verbs, the keyset walk, both undos and the wall between two tenants (#251).
+ *
+ * A page is asked for one row at a time on purpose: a walk that fits in one page proves nothing
+ * about the cursor, and a listing whose keyset predicate is wrong shows up as a row visited twice
+ * or not at all rather than as an error.
+ */
+declare const entityConformance: <Body, Item, Handle>(subject: EntitySubject<Body, Item, Handle>) => ConformanceCase[];
+
+/** The tokens the DDL carries where a consumer's own name belongs, for a migrator that templates. */
+declare const ENTITY_PLACEHOLDERS: {
+    opsSetting: string;
+    tenantSetting: string;
+};
+type EntityMigration = {
+    name: string;
+    statements: string[];
+};
+type EntityDdlOptions = {
+    columns?: EntityColumns;
+    /** The columns kept beside the body, read off it on every write. Text unless named otherwise. */
+    indexed?: readonly (string | {
+        column: string;
+        type: string;
+    })[];
+    /** The business key column a row is addressed by. */
+    key: string;
+    order: EntityOrdering;
+    schema?: string;
+    settings: SessionSettings;
+    table: string;
+};
+/**
+ * An entity's table and its wall, as the two files a consumer applies.
+ *
+ * The tenant column DEFAULTS to the session setting, so a write that names no tenant still lands
+ * under the one its transaction is open for — the column and the policy then say the same thing,
+ * and neither depends on a caller remembering. Rendered with `ENTITY_PLACEHOLDERS` it is the same
+ * DDL with the tokens in it, for a migrator that templates.
+ */
+declare const entityMigrations: (options: EntityDdlOptions) => EntityMigration[];
+
 /**
  * What this seam throws when it refuses, so a caller can catch it by class (#211).
  *
@@ -283,7 +627,19 @@ type PgClientLike = {
     }>;
     release: () => void;
 };
-type NodePostgresOptions = {
+/** What one `open` reports its statements to, handed to the drizzle factory to wire a logger. */
+type StatementReporting = {
+    onStatement?: (statement: string) => void;
+};
+/**
+ * The database this driver's handles speak through, built over the pool it opened.
+ *
+ * A factory rather than a flag: a repo's database carries its own schema and options, and a flag
+ * could only ever hand back one with neither. `pool` is declared `never` so the factory's own
+ * parameter type — whatever the `pg` copy it imports says a pool is — satisfies it without a cast.
+ */
+type DrizzleFactory<Db extends DrizzleDatabase> = (pool: never, reporting: StatementReporting) => Db;
+type NodePostgresOptions<Db extends DrizzleDatabase = DrizzleDatabase> = {
     /**
      * The table recording which migration files have been applied. Named after this package so it
      * cannot collide with a consumer's own; a consumer whose migrator already keeps one names theirs.
@@ -291,6 +647,19 @@ type NodePostgresOptions = {
     migrationsTable?: string;
     /** The `pg` module itself, for a runtime whose copy is patched. Loaded on demand when absent. */
     pg?: PgModuleLike;
+    drizzle?: DrizzleFactory<Db>;
+};
+/**
+ * Two answers, one call: a driver whose handles are the executor port, or — given a factory — one
+ * whose handles are the DATABASE it built, so a repo on drizzle keeps its builders through the
+ * session this package opens. The drizzle signature is first because an options object without
+ * that key cannot match it.
+ */
+type NodePostgresDriverFactory = {
+    <Db extends DrizzleDatabase>(options: NodePostgresOptions<Db> & {
+        drizzle: DrizzleFactory<Db>;
+    }): Promise<Driver<Db>>;
+    (options?: NodePostgresOptions): Promise<Driver>;
 };
 /**
  * The one file in this package that names `pg`.
@@ -298,24 +667,7 @@ type NodePostgresOptions = {
  * It is a factory rather than a constant because the module is loaded on demand: a consumer using
  * the executor port with their own database library never resolves `pg` at all.
  */
-declare const nodePostgresDriver: (options?: NodePostgresOptions) => Promise<Driver>;
-
-/**
- * The two session settings a tenant wall is built on, spelled once at the composition root.
- *
- * Neither has a default. A default here would be one repo's name — `app.org_id` at the repo this
- * came from — compiled into every other repo's policies, and the seam and the policies must agree
- * on it exactly or the wall is open while every test still passes.
- */
-type SessionSettings = {
-    /** What maintenance sets to see every tenant, through a lever no request path can reach. */
-    opsSetting: string;
-    /** What the ops setting holds while the lever is pulled. */
-    opsValue?: string;
-    /** What a transaction sets to name the tenant it is open for, and what the policies read. */
-    tenantSetting: string;
-};
-declare const DEFAULT_OPS_VALUE = "on";
+declare const nodePostgresDriver: NodePostgresDriverFactory;
 
 type FreezeRegister = {
     /** The column of that register holding the tenant a row names. */
@@ -345,6 +697,39 @@ type TenantPolicyOptions = {
     /** The column holding the tenant a row belongs to. */
     tenantColumn: string;
 };
+/** One policy of the tenant wall, before either door renders it. */
+type TenantPolicy = {
+    as: 'permissive' | 'restrictive';
+    name: string;
+    /** The predicate, in both `using` and `with check`: read one way and write the same way. */
+    predicate: string;
+};
+declare const tenantPolicySet: (options: TenantPolicyOptions) => TenantPolicy[];
+/** As much of drizzle's policy vocabulary as this door uses; the consumer hands in their own. */
+type DrizzlePolicyTools = {
+    /**
+     * `never`, measured: drizzle-orm 0.45.2 types the config as its own class with its own `SQL`
+     * inside, and a structural stand-in for it here would be this package naming a type from a
+     * library it does not depend on. What the config must actually hold is held by the reach test,
+     * which runs the real generator over a real schema.
+     */
+    pgPolicy: (name: string, config: never) => unknown;
+    sql: {
+        raw: (text: string) => unknown;
+    };
+};
+/**
+ * The same wall as drizzle declarations, for a table's own definition.
+ *
+ * The tools are handed in rather than imported: a schema file already imports them, and this way
+ * the door costs nothing to a consumer who has never installed drizzle. FORCE is not among them —
+ * drizzle-orm 0.45.2 and drizzle-kit 0.31.10 contain the string `FORCE ROW LEVEL SECURITY` nowhere
+ * (measured 2026-09-02) — so `forceRowLevelSecurity` stays the statement to apply beside the
+ * generated migration, and ENABLE alone exempts the table's owner.
+ */
+declare const drizzleTenantPolicies: (tools: DrizzlePolicyTools, options: TenantPolicyOptions) => unknown[];
+/** The one statement a drizzle declaration cannot say, for the table its policies were declared on. */
+declare const forceRowLevelSecurity: (table: string, schema?: string) => string;
 /**
  * The row-level-security DDL for one tenant table, as statements to apply after the migrator ran.
  *
@@ -360,40 +745,4 @@ type TenantPolicyOptions = {
  */
 declare const tenantPolicies: (table: string, options: TenantPolicyOptions) => string[];
 
-/** A query that takes its session as an argument: what the seam wraps and what a provider writes. */
-type Query<Params, Result> = (executor: Executor, params: Params) => Promise<Result>;
-declare const DEFAULT_TENANT_KEY = "tenantId";
-type SessionSeam<Key extends string = typeof DEFAULT_TENANT_KEY> = {
-    inOps: <Result>(executor: Executor, run: (tx: Executor) => Promise<Result>) => Promise<Result>;
-    inTenant: <Result>(executor: Executor, tenantId: string, run: (tx: Executor) => Promise<Result>) => Promise<Result>;
-    scoped: <Params extends Readonly<Record<Key, string>>, Result>(query: Query<Params, Result>) => Query<Params, Result>;
-    scopedAsOps: <Params, Result>(query: Query<Params, Result>) => Query<Params, Result>;
-};
-type SessionSeamConfig<Key extends string = typeof DEFAULT_TENANT_KEY> = {
-    /**
-     * How long a statement may run under the ops lever, as Postgres reads it. No default: a sweep's
-     * budget is a fact about one deployment's data, and the value that fits belongs to whoever runs
-     * it. Absent, the connection's own timeout stands.
-     */
-    opsStatementTimeout?: string;
-    settings: SessionSettings;
-    /**
-     * The key a query's own parameters carry its tenant under (#245). A repo whose queries say
-     * `{ orgId }` names it here instead of wrapping every call site in `inTenant` by hand.
-     *
-     * A key name rather than a selector, measured: under `tenantOf: (params) => string` nothing ties
-     * the selector's shape to the query's, and a query whose parameters carry no tenant at all
-     * compiles clean — which is the one thing `scoped` is here to make impossible.
-     */
-    tenantKey?: Key;
-};
-/**
- * The seam every query crosses: one transaction, the scope named as its first statement.
- *
- * `set_config(..., true)` is local to the transaction, which is what makes this safe on a pool —
- * the name is gone when the transaction ends, and a connection handed to the next request carries
- * nothing. Naming it second would leave the statements before it running under no tenant at all.
- */
-declare const createSessionSeam: <Key extends string = typeof DEFAULT_TENANT_KEY>(config: SessionSeamConfig<Key>) => SessionSeam<Key>;
-
-export { type AppRoleOptions, type ConformanceCase, type Connection, type Connections, type ConnectionsConfig, type ConnectionsSubject, type ConnectionsUnderTest, DEFAULT_OPS_VALUE, DEFAULT_TENANT_KEY, DbRefusal, type Driver, type Executor, type FreezeRegister, type InvocationOptions, type NodePostgresOptions, type OpenConnection, type OpenOptions, type PgClientLike, type PgModuleLike, type PgPoolLike, type ProbeTable, type Query, type RecordingConnection, type SeamUnderTest, type SessionSeam, type SessionSeamConfig, type SessionSettings, type SessionSubject, type Statement, type TenantPolicyNames, type TenantPolicyOptions, appConnectionString, appRoleStatements, concurrentTenantsConformance, connectionsConformance, createConnections, createSessionSeam, forcedRowLevelSecurityConformance, nodePostgresDriver, perStepConnection, scopedQueryConformance, sessionConformance, statementCensusConformance, tenantIsolationConformance, tenantPolicies };
+export { type AppRoleOptions, type ConformanceCase, type Connection, type Connections, type ConnectionsConfig, type ConnectionsSubject, type ConnectionsUnderTest, DEFAULT_ENTITY_PAGE, DEFAULT_OPS_VALUE, DEFAULT_TENANT_KEY, DbRefusal, type Driver, type DrizzleDatabase, type DrizzleFactory, type DrizzleModuleLike, type DrizzlePolicyTools, type DrizzleSessionOptions, type DrizzleSql, ENTITY_PLACEHOLDERS, type Entity, type EntityColumns, type EntityDdlOptions, type EntityDefinition, type EntityMigration, type EntityOrdering, type EntityPage, type EntityRow, type EntitySubject, type EntityUnderTest, type EntityUndo, type Executor, type FreezeRegister, type InvocationOptions, MAX_ENTITY_PAGE, type NodePostgresOptions, type OpenConnection, type OpenOptions, type PgClientLike, type PgModuleLike, type PgPoolLike, type ProbeTable, type Query, type RecordingConnection, type RetireOutput, type SeamUnderTest, type SessionHandles, type SessionSeam, type SessionSeamConfig, type SessionSettings, type SessionSubject, type SqlFragment, type Statement, type StatementReporting, type TenantPolicy, type TenantPolicyNames, type TenantPolicyOptions, type UpsertOutput, appConnectionString, appRoleStatements, asStatement, concurrentTenantsConformance, connectionsConformance, createConnections, createSessionSeam, defineEntity, drizzleSession, drizzleTenantPolicies, entityConformance, entityMigrations, forceRowLevelSecurity, forcedRowLevelSecurityConformance, fragment, nodePostgresDriver, perStepConnection, scopedQueryConformance, sessionConformance, statementCensusConformance, tenantIsolationConformance, tenantPolicies, tenantPolicySet, undosOf };