@geonosis/db 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,336 @@
+import { QueryAnswer } from '@geonosis/conformance';
+export { QueryAnswer } from '@geonosis/conformance';
+
+type AppRoleOptions = {
+    /**
+     * How long a session may sit inside an open transaction. No default: the number that fits is a
+     * fact about one deployment's traffic, and a wrong one closes a working connection mid-request.
+     */
+    idleInTransactionTimeout?: string;
+    password: string;
+    /** The name the application logs in as. A parameter, because a default here names one repo. */
+    role: string;
+    schema?: string;
+    /** How long one of that role's statements may run. No default, for the same reason. */
+    statementTimeout?: string;
+};
+/**
+ * The role an application connects as, as statements to run after every migration.
+ *
+ * NOSUPERUSER and NOBYPASSRLS are the point: the policies are the wall, and a superuser or a role
+ * with BYPASSRLS walks around it without a single query changing. The migrator stays the owner.
+ */
+declare const appRoleStatements: (options: AppRoleOptions) => string[];
+/** The same database, entered as the application role rather than as its owner. */
+declare const appConnectionString: (ownerConnectionString: string, credentials: {
+    password: string;
+    role: string;
+}) => string;
+
+/**
+ * A parameterised statement: the text a driver sends, and the values that fill its placeholders.
+ *
+ * Apart, never interpolated. A provider writes SQL for a database whose connection belongs to
+ * somebody else, and numbered placeholders are the only spelling that survives a value it did not
+ * choose.
+ */
+type Statement = {
+    params?: readonly unknown[];
+    text: string;
+};
+
+/**
+ * Query in a session — the whole port a domain provider needs from a database.
+ *
+ * It says nothing about connections, pools, transactions or tenancy on purpose: the consumer owns
+ * those, and a provider that could reach them would be deciding how somebody else's application
+ * talks to their database. What arrives here is already inside whatever session the caller opened.
+ */
+type Executor = {
+    execute: (statement: Statement) => Promise<QueryAnswer>;
+};
+/** An executor that can also open a transaction: a handle, rather than a session inside one. */
+type Connection = Executor & {
+    transaction: <Result>(run: (tx: Executor) => Promise<Result>) => Promise<Result>;
+};
+
+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 = {
+    close: () => Promise<void>;
+    connection: Connection;
+    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>;
+};
+/**
+ * A table under the policies under test, whose only required columns are these two.
+ *
+ * The exam writes to it, so it cannot be one of the consumer's own tables with its own NOT NULLs;
+ * and it has to be a real table under the real policies, or the exam is grading a fixture.
+ */
+type ProbeTable = {
+    idColumn: string;
+    name: string;
+    schema?: string;
+    tenantColumn: string;
+};
+type SessionSubject = {
+    /** A handle OUTSIDE every session: what the policies alone let through. */
+    connection: Connection;
+    /** The tables whose FORCE is checked. The probe table alone, when nothing else is named. */
+    guardedTables?: readonly string[];
+    probe: ProbeTable;
+    recording: () => Promise<RecordingConnection>;
+    /** Empty the probe table. Whatever role can do that — the exam's own rows are its business. */
+    reset: () => Promise<void>;
+    seam: SeamUnderTest;
+};
+/**
+ * The tenant wall, as the source proof took it: what a query with NO predicate can still see.
+ *
+ * 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[];
+/**
+ * The census: a read costs what it says.
+ *
+ * Four statements — the transaction, the tenant, the read, the commit. It is a literal number
+ * because the failures it catches are structural: a savepoint per query, a set_config per query, or
+ * 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[];
+/**
+ * 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[];
+/**
+ * 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[];
+/** The whole exam: what a consumer runs against their own session before depending on it. */
+declare const sessionConformance: (subject: SessionSubject) => ConformanceCase[];
+
+type OpenOptions = {
+    /**
+     * Every statement this handle sends, as it is sent — the transaction's own begin and commit
+     * included, because a count of round trips that leaves those out is not a count of round trips.
+     */
+    onStatement?: (statement: string) => void;
+    /**
+     * A pooled connection that died while nobody was using it. Nothing is waiting on it and the pool
+     * replaces it by itself, so this is how such a death is seen at all rather than something to act
+     * on.
+     */
+    onIdleError?: (error: unknown) => void;
+    /**
+     * How many connections one handle may hold. No default: the number that fits is the fan-out of
+     * one invocation against the concurrency the database was sized for, and a driver already has
+     * an opinion when nobody states one.
+     */
+    poolSize?: number;
+};
+/** A handle, and the way to give its connections back. */
+type OpenConnection = {
+    close: () => Promise<void>;
+    connection: Connection;
+};
+/** The one thing in a deployment that knows which package speaks the wire protocol. */
+type Driver = {
+    migrate: (connectionString: string, migrationsFolder: string) => Promise<void>;
+    open: (connectionString: string, options?: OpenOptions) => OpenConnection;
+};
+type Connections = {
+    /** 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;
+    /** The handle this invocation is using, opened on first ask. */
+    sessionDb: () => Connection;
+    withConnection: <Result>(run: () => Promise<Result>, release?: (closing: Promise<void>) => void) => Promise<Result>;
+};
+type ConnectionsConfig = {
+    connectionString: string;
+    driver: Driver;
+    open?: OpenOptions;
+};
+/**
+ * The handles of one database, and the discipline that closes them.
+ *
+ * A serverless invocation hibernates and dies; a handle opened once per process is dead by the
+ * second request, and a handle opened per query is a pool per query. One per invocation is the
+ * 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;
+/**
+ * The `scope.perStep` hook a workflow engine asks for, answered with a connection per unit of work.
+ *
+ * A durable run hibernates between steps, so the handle its first step opened is dead by the fifth:
+ * each step body and each undo opens its own. The engine's own writes — the trail, the closing
+ * batch — are not units of work and stay outside, on whatever connection the runner holds.
+ *
+ * The type is not imported. `@geonosis/workflows` is a sibling foundation and the floors forbid an
+ * edge between two of them in either direction; what crosses is the shape.
+ */
+declare const perStepConnection: (connections: Pick<Connections, "withConnection">) => {
+    perStep: () => <Output>(body: () => Promise<Output>) => Promise<Output>;
+};
+
+/**
+ * What this seam throws when it refuses, so a caller can catch it by class (#211).
+ *
+ * Every sibling has one — `WorkflowsError`, `ConformanceFailure`, `LearningError` — and this
+ * package threw a bare `Error`, which left a caller matching prose and a conformance case unable to
+ * tell a refusal from a driver that simply crashed (#213: a `TypeError` reads exactly like "the
+ * seam said no"). The name is on the instance so a log line says which package refused.
+ */
+declare class DbRefusal extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+
+/**
+ * As much of `pg` as this driver uses, declared here rather than imported.
+ *
+ * `pg` 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 `@types/pg` to
+ * typecheck. Structural is also what lets a Workers deployment hand in its own patched copy.
+ */
+type PgModuleLike = {
+    Pool: new (config: {
+        connectionString: string;
+        max?: number;
+    }) => PgPoolLike;
+};
+type PgPoolLike = {
+    connect: () => Promise<PgClientLike>;
+    end: () => Promise<void>;
+    on: (event: 'error', listener: (error: unknown) => void) => void;
+    query: (text: string, values?: unknown[]) => Promise<{
+        rows: unknown[];
+    }>;
+};
+type PgClientLike = {
+    query: (text: string, values?: unknown[]) => Promise<{
+        rows: unknown[];
+    }>;
+    release: () => void;
+};
+type NodePostgresOptions = {
+    /**
+     * 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.
+     */
+    migrationsTable?: string;
+    /** The `pg` module itself, for a runtime whose copy is patched. Loaded on demand when absent. */
+    pg?: PgModuleLike;
+};
+/**
+ * The one file in this package that names `pg`.
+ *
+ * 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";
+
+type FreezeRegister = {
+    /** The column of that register holding the tenant a row names. */
+    tenantColumn: string;
+    /** The table listing the tenants whose rows are read-only. */
+    table: string;
+};
+type TenantPolicyNames = {
+    freeze?: string;
+    isolation?: string;
+    opsMaintenance?: string;
+};
+type TenantPolicyOptions = {
+    /**
+     * A register of frozen tenants, and the restrictive policy that consults it. Off unless named:
+     * a restrictive policy is a second predicate every statement on the table pays for, and freezing
+     * a tenant's rows is a product feature rather than a property of tenancy.
+     */
+    freeze?: FreezeRegister;
+    /**
+     * What these policies are called. A consumer whose tables already carry a policy of the same name
+     * would otherwise have it dropped by the line above the one that creates ours.
+     */
+    names?: TenantPolicyNames;
+    schema?: string;
+    settings: SessionSettings;
+    /** The column holding the tenant a row belongs to. */
+    tenantColumn: string;
+};
+/**
+ * The row-level-security DDL for one tenant table, as statements to apply after the migrator ran.
+ *
+ * It is DDL rather than schema-builder calls because FORCE is not sayable in one: drizzle-orm
+ * 0.45.2 offers `enableRLS()` and drizzle-kit 0.31.10 emits `ENABLE ROW LEVEL SECURITY`, and
+ * neither package contains the string `FORCE ROW LEVEL SECURITY` anywhere (measured 2026-09-02).
+ * ENABLE alone exempts the table's OWNER — which is the role a migration and an ops sweep connect
+ * as — so a wall that is only enabled is a wall with a door in it for the busiest user.
+ *
+ * Every statement is re-runnable, because it runs again after the next migration: a policy is
+ * dropped if present before it is created. Apply the list in ONE transaction, or a failure halfway
+ * leaves a table whose policy was dropped and not remade.
+ */
+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>;
+type SessionSeam = {
+    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 {
+        tenantId: string;
+    }, Result>(query: Query<Params, Result>) => Query<Params, Result>;
+    scopedAsOps: <Params, Result>(query: Query<Params, Result>) => Query<Params, Result>;
+};
+type SessionSeamConfig = {
+    /**
+     * 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 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: (config: SessionSeamConfig) => SessionSeam;
+
+export { type AppRoleOptions, type ConformanceCase, type Connection, type Connections, type ConnectionsConfig, DEFAULT_OPS_VALUE, DbRefusal, type Driver, type Executor, type FreezeRegister, 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, createConnections, createSessionSeam, forcedRowLevelSecurityConformance, nodePostgresDriver, perStepConnection, sessionConformance, statementCensusConformance, tenantIsolationConformance, tenantPolicies };

package/dist/index.d.ts

@@ -0,0 +1,336 @@
+import { QueryAnswer } from '@geonosis/conformance';
+export { QueryAnswer } from '@geonosis/conformance';
+
+type AppRoleOptions = {
+    /**
+     * How long a session may sit inside an open transaction. No default: the number that fits is a
+     * fact about one deployment's traffic, and a wrong one closes a working connection mid-request.
+     */
+    idleInTransactionTimeout?: string;
+    password: string;
+    /** The name the application logs in as. A parameter, because a default here names one repo. */
+    role: string;
+    schema?: string;
+    /** How long one of that role's statements may run. No default, for the same reason. */
+    statementTimeout?: string;
+};
+/**
+ * The role an application connects as, as statements to run after every migration.
+ *
+ * NOSUPERUSER and NOBYPASSRLS are the point: the policies are the wall, and a superuser or a role
+ * with BYPASSRLS walks around it without a single query changing. The migrator stays the owner.
+ */
+declare const appRoleStatements: (options: AppRoleOptions) => string[];
+/** The same database, entered as the application role rather than as its owner. */
+declare const appConnectionString: (ownerConnectionString: string, credentials: {
+    password: string;
+    role: string;
+}) => string;
+
+/**
+ * A parameterised statement: the text a driver sends, and the values that fill its placeholders.
+ *
+ * Apart, never interpolated. A provider writes SQL for a database whose connection belongs to
+ * somebody else, and numbered placeholders are the only spelling that survives a value it did not
+ * choose.
+ */
+type Statement = {
+    params?: readonly unknown[];
+    text: string;
+};
+
+/**
+ * Query in a session — the whole port a domain provider needs from a database.
+ *
+ * It says nothing about connections, pools, transactions or tenancy on purpose: the consumer owns
+ * those, and a provider that could reach them would be deciding how somebody else's application
+ * talks to their database. What arrives here is already inside whatever session the caller opened.
+ */
+type Executor = {
+    execute: (statement: Statement) => Promise<QueryAnswer>;
+};
+/** An executor that can also open a transaction: a handle, rather than a session inside one. */
+type Connection = Executor & {
+    transaction: <Result>(run: (tx: Executor) => Promise<Result>) => Promise<Result>;
+};
+
+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 = {
+    close: () => Promise<void>;
+    connection: Connection;
+    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>;
+};
+/**
+ * A table under the policies under test, whose only required columns are these two.
+ *
+ * The exam writes to it, so it cannot be one of the consumer's own tables with its own NOT NULLs;
+ * and it has to be a real table under the real policies, or the exam is grading a fixture.
+ */
+type ProbeTable = {
+    idColumn: string;
+    name: string;
+    schema?: string;
+    tenantColumn: string;
+};
+type SessionSubject = {
+    /** A handle OUTSIDE every session: what the policies alone let through. */
+    connection: Connection;
+    /** The tables whose FORCE is checked. The probe table alone, when nothing else is named. */
+    guardedTables?: readonly string[];
+    probe: ProbeTable;
+    recording: () => Promise<RecordingConnection>;
+    /** Empty the probe table. Whatever role can do that — the exam's own rows are its business. */
+    reset: () => Promise<void>;
+    seam: SeamUnderTest;
+};
+/**
+ * The tenant wall, as the source proof took it: what a query with NO predicate can still see.
+ *
+ * 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[];
+/**
+ * The census: a read costs what it says.
+ *
+ * Four statements — the transaction, the tenant, the read, the commit. It is a literal number
+ * because the failures it catches are structural: a savepoint per query, a set_config per query, or
+ * 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[];
+/**
+ * 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[];
+/**
+ * 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[];
+/** The whole exam: what a consumer runs against their own session before depending on it. */
+declare const sessionConformance: (subject: SessionSubject) => ConformanceCase[];
+
+type OpenOptions = {
+    /**
+     * Every statement this handle sends, as it is sent — the transaction's own begin and commit
+     * included, because a count of round trips that leaves those out is not a count of round trips.
+     */
+    onStatement?: (statement: string) => void;
+    /**
+     * A pooled connection that died while nobody was using it. Nothing is waiting on it and the pool
+     * replaces it by itself, so this is how such a death is seen at all rather than something to act
+     * on.
+     */
+    onIdleError?: (error: unknown) => void;
+    /**
+     * How many connections one handle may hold. No default: the number that fits is the fan-out of
+     * one invocation against the concurrency the database was sized for, and a driver already has
+     * an opinion when nobody states one.
+     */
+    poolSize?: number;
+};
+/** A handle, and the way to give its connections back. */
+type OpenConnection = {
+    close: () => Promise<void>;
+    connection: Connection;
+};
+/** The one thing in a deployment that knows which package speaks the wire protocol. */
+type Driver = {
+    migrate: (connectionString: string, migrationsFolder: string) => Promise<void>;
+    open: (connectionString: string, options?: OpenOptions) => OpenConnection;
+};
+type Connections = {
+    /** 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;
+    /** The handle this invocation is using, opened on first ask. */
+    sessionDb: () => Connection;
+    withConnection: <Result>(run: () => Promise<Result>, release?: (closing: Promise<void>) => void) => Promise<Result>;
+};
+type ConnectionsConfig = {
+    connectionString: string;
+    driver: Driver;
+    open?: OpenOptions;
+};
+/**
+ * The handles of one database, and the discipline that closes them.
+ *
+ * A serverless invocation hibernates and dies; a handle opened once per process is dead by the
+ * second request, and a handle opened per query is a pool per query. One per invocation is the
+ * 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;
+/**
+ * The `scope.perStep` hook a workflow engine asks for, answered with a connection per unit of work.
+ *
+ * A durable run hibernates between steps, so the handle its first step opened is dead by the fifth:
+ * each step body and each undo opens its own. The engine's own writes — the trail, the closing
+ * batch — are not units of work and stay outside, on whatever connection the runner holds.
+ *
+ * The type is not imported. `@geonosis/workflows` is a sibling foundation and the floors forbid an
+ * edge between two of them in either direction; what crosses is the shape.
+ */
+declare const perStepConnection: (connections: Pick<Connections, "withConnection">) => {
+    perStep: () => <Output>(body: () => Promise<Output>) => Promise<Output>;
+};
+
+/**
+ * What this seam throws when it refuses, so a caller can catch it by class (#211).
+ *
+ * Every sibling has one — `WorkflowsError`, `ConformanceFailure`, `LearningError` — and this
+ * package threw a bare `Error`, which left a caller matching prose and a conformance case unable to
+ * tell a refusal from a driver that simply crashed (#213: a `TypeError` reads exactly like "the
+ * seam said no"). The name is on the instance so a log line says which package refused.
+ */
+declare class DbRefusal extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+
+/**
+ * As much of `pg` as this driver uses, declared here rather than imported.
+ *
+ * `pg` 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 `@types/pg` to
+ * typecheck. Structural is also what lets a Workers deployment hand in its own patched copy.
+ */
+type PgModuleLike = {
+    Pool: new (config: {
+        connectionString: string;
+        max?: number;
+    }) => PgPoolLike;
+};
+type PgPoolLike = {
+    connect: () => Promise<PgClientLike>;
+    end: () => Promise<void>;
+    on: (event: 'error', listener: (error: unknown) => void) => void;
+    query: (text: string, values?: unknown[]) => Promise<{
+        rows: unknown[];
+    }>;
+};
+type PgClientLike = {
+    query: (text: string, values?: unknown[]) => Promise<{
+        rows: unknown[];
+    }>;
+    release: () => void;
+};
+type NodePostgresOptions = {
+    /**
+     * 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.
+     */
+    migrationsTable?: string;
+    /** The `pg` module itself, for a runtime whose copy is patched. Loaded on demand when absent. */
+    pg?: PgModuleLike;
+};
+/**
+ * The one file in this package that names `pg`.
+ *
+ * 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";
+
+type FreezeRegister = {
+    /** The column of that register holding the tenant a row names. */
+    tenantColumn: string;
+    /** The table listing the tenants whose rows are read-only. */
+    table: string;
+};
+type TenantPolicyNames = {
+    freeze?: string;
+    isolation?: string;
+    opsMaintenance?: string;
+};
+type TenantPolicyOptions = {
+    /**
+     * A register of frozen tenants, and the restrictive policy that consults it. Off unless named:
+     * a restrictive policy is a second predicate every statement on the table pays for, and freezing
+     * a tenant's rows is a product feature rather than a property of tenancy.
+     */
+    freeze?: FreezeRegister;
+    /**
+     * What these policies are called. A consumer whose tables already carry a policy of the same name
+     * would otherwise have it dropped by the line above the one that creates ours.
+     */
+    names?: TenantPolicyNames;
+    schema?: string;
+    settings: SessionSettings;
+    /** The column holding the tenant a row belongs to. */
+    tenantColumn: string;
+};
+/**
+ * The row-level-security DDL for one tenant table, as statements to apply after the migrator ran.
+ *
+ * It is DDL rather than schema-builder calls because FORCE is not sayable in one: drizzle-orm
+ * 0.45.2 offers `enableRLS()` and drizzle-kit 0.31.10 emits `ENABLE ROW LEVEL SECURITY`, and
+ * neither package contains the string `FORCE ROW LEVEL SECURITY` anywhere (measured 2026-09-02).
+ * ENABLE alone exempts the table's OWNER — which is the role a migration and an ops sweep connect
+ * as — so a wall that is only enabled is a wall with a door in it for the busiest user.
+ *
+ * Every statement is re-runnable, because it runs again after the next migration: a policy is
+ * dropped if present before it is created. Apply the list in ONE transaction, or a failure halfway
+ * leaves a table whose policy was dropped and not remade.
+ */
+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>;
+type SessionSeam = {
+    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 {
+        tenantId: string;
+    }, Result>(query: Query<Params, Result>) => Query<Params, Result>;
+    scopedAsOps: <Params, Result>(query: Query<Params, Result>) => Query<Params, Result>;
+};
+type SessionSeamConfig = {
+    /**
+     * 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 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: (config: SessionSeamConfig) => SessionSeam;
+
+export { type AppRoleOptions, type ConformanceCase, type Connection, type Connections, type ConnectionsConfig, DEFAULT_OPS_VALUE, DbRefusal, type Driver, type Executor, type FreezeRegister, 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, createConnections, createSessionSeam, forcedRowLevelSecurityConformance, nodePostgresDriver, perStepConnection, sessionConformance, statementCensusConformance, tenantIsolationConformance, tenantPolicies };