@fabrika/db 0.9.0-dev.1 → 0.9.0-dev.2

package/types/src/orm.d.ts

@@ -0,0 +1,77 @@
+import type { InvocationTransaction, Session } from './database';
+import { type FileBinding } from './file-columns';
+import type { DataKind, TargetForm, UnscopedMode } from './orm-types';
+import { type TableModels } from './policy';
+import { type SqlSite, type SqlTag } from './sql';
+import { type DataLayerRuntime, type TableContext } from './store';
+/** A list page holds this many rows unless the caller asks for fewer, and never more than `MAX_LIST_LIMIT`. */
+export declare const DEFAULT_LIST_LIMIT = 50;
+export declare const MAX_LIST_LIMIT = 500;
+/** What every handle of one site, in one invocation, is made for. */
+export interface DataSite {
+    /** A query reads; a mutation also writes and locks; a job reads, and writes only in its fenced transaction. */
+    readonly kind: DataKind;
+    /** The tables the site declares `unscoped`, each in its mode. */
+    readonly unscoped: Readonly<Record<string, UnscopedMode>>;
+    /** Who an unscoped insert is stamped with (`createdBy`): no capability carries a principal for it. */
+    readonly principal: string;
+    /** A job's schedule period, in ms: a queue claim's first backoff, doubled at each later claim of the row. */
+    readonly tickMs?: number;
+    /**
+     * A public procedure, which anyone calls: its `ctx.db.app` inserts and reads nothing back, reads only under a table's
+     * read action, and reaches application tables only. It updates or removes only a versioned row whose id a verified
+     * signed token of its request carries (`carried`); it never locks or claims a row.
+     */
+    readonly public?: true;
+    /**
+     * Where the site's file references belong: each file column it reads answers one, and a file column it writes takes
+     * only one it holds. Absent where the framework serves no file; the columns then read as ids and refuse every write.
+     */
+    readonly files?: FileBinding;
+    /** The texts the verified signed tokens of a public procedure's request carry: the row ids it may update or remove. */
+    readonly carried?: ReadonlySet<string>;
+    /** Throws unless the work running now is the invocation these handles were made for. */
+    check(): void;
+    /** The session every statement of the site runs in. */
+    session(): Promise<Session>;
+}
+/** The handles of one site; the framework composes `ctx.db` from them by the site's access form. */
+export interface DataHandles {
+    /** `ctx.db.target` (or `ctx.db.created`, or a job's `ctx.db.on`/`.in`): a `Ref`'s row and subtree. */
+    target(capability: unknown, form: TargetForm): object;
+    /** `ctx.db.within` (or a job's `ctx.db.over`): every table listed in a `Within`'s dimension. */
+    within(capability: unknown): object;
+    /**
+     * `ctx.db.app`. Of an `app` endpoint: each application table, and each dimension and child table, read-only, by the
+     * capability's action held application-wide. Of an `on`, `in` or `over` endpoint (a `Ref` or a `Within`): each
+     * application table, read-only, every row, where the capability's action is its read action.
+     */
+    app(capability: unknown): object;
+    /** `ctx.db.reference`. */
+    readonly reference: object;
+    /** `ctx.db.unscoped`, or `undefined` for a site that declares none. */
+    readonly unscoped: object | undefined;
+}
+/** The data side of one bound layer, which only the framework reaches (`@fabrika/db/framework`). */
+export interface DataAccess {
+    /** One invocation's transaction over the bound connection; a query's is `READ ONLY`. */
+    invocation(readOnly: boolean): InvocationTransaction;
+    /** A statement-at-a-time session: what a job's reads outside its transaction run in. */
+    direct(): Session;
+    /** One transaction, fenced by the lease of the job attempt running now: a job's `ctx.transaction`. */
+    transaction<T>(work: (session: Session) => Promise<T>): Promise<T>;
+    /** The handles of one site. Throws for a declaration this layer cannot honour. */
+    handles(site: DataSite): DataHandles;
+    /** `ctx.sql` of a site that declares it, running in the site's session on the application's schema. */
+    sql(site: SqlSite): SqlTag;
+}
+/** What `scoped` hands this module: the layer's tables and the way to its runtime. */
+export interface DataLayerParts {
+    readonly models: TableModels;
+    contextOf(table: string): TableContext;
+    runtime(): DataLayerRuntime;
+    newSession(runtime: DataLayerRuntime): Session;
+    newInvocation(runtime: DataLayerRuntime, readOnly: boolean): InvocationTransaction;
+    fenced<T>(runtime: DataLayerRuntime, work: (session: Session) => Promise<T>): Promise<T>;
+}
+export declare function dataAccess(parts: DataLayerParts): DataAccess;

package/types/src/policy.d.ts

@@ -0,0 +1,350 @@
+import type { Insertable, Selectable, SelectType, Updateable } from 'kysely';
+import { type NameSet } from './builtins';
+import type { Unavailable } from './orm-types';
+export type { RowOf } from './orm-types';
+import type { ColumnTypes, DefineVocabularyPolicies, TableVocabulary } from './vocabulary-tables';
+export interface DimensionScope<Col extends string> {
+    readonly dimension: string;
+    readonly key: Col;
+    readonly in?: {
+        readonly dimension: string;
+        readonly column: Col;
+    };
+}
+export interface ChildScope<Table extends string, Col extends string> {
+    readonly child: Table;
+    readonly key: Col;
+    readonly column: Col;
+    readonly inherit: readonly Col[];
+}
+export interface ReferenceScope {
+    readonly reference: string;
+}
+/** Rows of the whole application, in no dimension; the value says why. `key` defaults to `id`. */
+export interface ApplicationScope<Col extends string> {
+    readonly app: string;
+    readonly key?: Col;
+}
+/** One action, or a list of them: a table that staff and a public procedure both read names both actions. */
+export type TableAction<A extends string> = A | readonly A[];
+export interface TableActions<A extends string> {
+    readonly read: TableAction<A>;
+    readonly insert?: TableAction<A>;
+    readonly update?: TableAction<A>;
+    readonly delete?: TableAction<A>;
+}
+/**
+ * A queue table's columns (ADR-0060's drain): `due` is when a row is next claimed, `null` once it is done; `attempts`
+ * counts its claims, and a row with `maxAttempts` (default 10) of them is no longer claimed.
+ */
+export interface QueuePolicy<Col extends string> {
+    readonly attempts: Col;
+    readonly due: Col;
+    readonly maxAttempts?: number;
+}
+/**
+ * A dimension or child table's actions: also those besides `read` with which an `app` endpoint lists every row,
+ * read-only (`appRead`), and those with which it only counts and aggregates every row (`appCount`).
+ */
+export interface RecordActions<A extends string> extends TableActions<A> {
+    readonly appRead?: readonly A[];
+    readonly appCount?: readonly A[];
+}
+interface WritablePolicy<Col extends string, A extends string, V extends Col, Acts = TableActions<A>> {
+    readonly actions: Acts;
+    readonly insert?: readonly Col[];
+    readonly update?: readonly Col[];
+    /** An INTEGER (int4) column: Postgres returns a BIGINT as a string, so it cannot be compared as a number. */
+    readonly version?: V;
+    readonly createdBy?: Col;
+    readonly columns?: ColumnPolicies<Col, A>;
+    /** A queue table: its rows are claimed (`claim`) and finished through `row.ref`; it needs `version` and an update action. */
+    readonly queue?: QueuePolicy<Col>;
+    /**
+     * The file columns, each with the file kind it holds: a `uuid` foreign key to `fabrika_files`, written only with a
+     * file reference. The table's actions are the file's authority.
+     */
+    readonly files?: FilePolicies<Col>;
+}
+/** A table's file columns: column → the name of a file kind of the contract (`c.files`). */
+export type FilePolicies<Col extends string> = {
+    readonly [C in Col]?: string;
+};
+/**
+ * A column's own actions. `read`: only a capability of exactly that action reads, filters or sorts by the column;
+ * without one it falls back to the table's read action. `write`: only a capability of that action updates the column,
+ * and the table's update action does not, so the column is not in `update`.
+ */
+export type ColumnPolicies<Col extends string, A extends string> = {
+    readonly [C in Col]?: ColumnPolicy<A>;
+};
+/** A column's own read action, its own write action, or both. */
+export interface ColumnPolicy<A extends string> {
+    readonly read?: A;
+    readonly write?: A;
+}
+/** A table no handler writes (a reference table) declares column read actions only. */
+export type ColumnReadPolicies<Col extends string, A extends string> = {
+    readonly [C in Col]?: {
+        readonly read: A;
+    };
+};
+export interface DimensionPolicy<Col extends string, A extends string, V extends Col = Col> extends WritablePolicy<Col, A, V, RecordActions<A>> {
+    readonly scope: DimensionScope<Col>;
+}
+export interface ChildPolicy<Table extends string, Col extends string, A extends string, V extends Col = Col> extends WritablePolicy<Col, A, V, RecordActions<A>> {
+    readonly scope: ChildScope<Table, Col>;
+}
+/** An application table: written like a dimension table, by an `app` endpoint whose action is the operation's. */
+export interface ApplicationPolicy<Col extends string, A extends string, V extends Col = Col> extends WritablePolicy<Col, A, V> {
+    readonly scope: ApplicationScope<Col>;
+}
+interface ReadOnlyPolicy<Col extends string, A extends string> {
+    readonly insert?: never;
+    readonly update?: never;
+    readonly version?: never;
+    readonly createdBy?: never;
+    readonly queue?: never;
+    readonly files?: never;
+    readonly columns?: ColumnReadPolicies<Col, A>;
+}
+export interface ReferencePolicy<Col extends string, A extends string> extends ReadOnlyPolicy<Col, A> {
+    readonly scope: ReferenceScope;
+    readonly actions: {
+        readonly read: TableAction<A>;
+    };
+}
+/** The columns a version can live in: those whose generated select type is `number`, an INTEGER (int4). */
+export type VersionColumn<Row> = {
+    [K in keyof Row & string]: SelectType<Row[K]> extends number ? K : never;
+}[keyof Row & string];
+/** A foreign key within the schema, as codegen reads it: `columns[i]` references column `references[i]` of `table`. */
+export interface ForeignKey<Col extends string = string, Table extends string = string> {
+    readonly columns: readonly Col[];
+    readonly table: Table;
+    readonly references: readonly string[];
+}
+/** One table of the generated column list: its column names, and its foreign keys to tables of the schema. */
+export interface TableColumns<Col extends string = string, Table extends string = string> {
+    readonly columns: readonly Col[];
+    readonly foreignKeys: readonly ForeignKey<Col, Table>[];
+    /** The columns of Postgres type `date`, which a read answers as `YYYY-MM-DD` text; absent when there are none. */
+    readonly dates?: readonly Col[];
+    /** The `timestamp` and `timestamptz` columns, which a write takes as a `Date` or strict ISO 8601 text; absent when none. */
+    readonly timestamps?: readonly Col[];
+}
+/** The columns and foreign keys of every table, generated next to the schema types. */
+export type ColumnList<DB> = {
+    readonly [T in keyof DB & string]: TableColumns<keyof DB[T] & string, keyof DB & string>;
+};
+export interface Container {
+    readonly dimension: string;
+    readonly column: string;
+}
+export type ScopeModel = {
+    readonly mode: 'dimension';
+    readonly dimension: string;
+    readonly key: string;
+    readonly container: Container | undefined;
+} | {
+    readonly mode: 'child';
+    readonly parent: string;
+    readonly key: string;
+    readonly column: string;
+    readonly inherit: readonly string[];
+} | {
+    readonly mode: 'reference';
+    readonly reason: string;
+} | {
+    readonly mode: 'app';
+    readonly reason: string;
+    readonly key: string;
+};
+/** Each operation's actions: any one of them allows it. `read` names at least one; an empty list allows no operation. */
+export interface ActionModel {
+    readonly read: readonly string[];
+    readonly insert: readonly string[];
+    readonly update: readonly string[];
+    readonly delete: readonly string[];
+    /** A dimension or child table's actions besides `read` with which an `app` endpoint reads every row, read-only. */
+    readonly appRead: readonly string[];
+    /** A dimension or child table's actions with which an `app` endpoint counts and aggregates every row, and reads none. */
+    readonly appCount: readonly string[];
+}
+export interface QueueModel {
+    readonly attempts: string;
+    readonly due: string;
+    readonly maxAttempts: number;
+}
+/** How many claims a queue row takes before it is no longer claimed, unless its policy states `maxAttempts`. */
+export declare const DEFAULT_MAX_ATTEMPTS = 10;
+/** One table's policy, checked against its column list. */
+export interface TableModel {
+    readonly name: string;
+    readonly scope: ScopeModel;
+    readonly actions: ActionModel;
+    /** Every column the table has. */
+    readonly columns: NameSet;
+    /** The columns every read action of the table reads, in column-list order. */
+    readonly visible: readonly string[];
+    readonly insert: NameSet;
+    readonly update: NameSet;
+    readonly version: string | undefined;
+    readonly createdBy: string | undefined;
+    readonly queue: QueueModel | undefined;
+    /** The file columns, each with its file kind: a reference to `fabrika_files`, written only with a file reference. */
+    readonly files: Readonly<Record<string, string>>;
+    /** The columns that declare their own read action, as declared (also those equal to the table's). */
+    readonly columnReads: Readonly<Record<string, string>>;
+    /** The columns that declare their own write action: only a capability of it updates them. */
+    readonly columnWrites: Readonly<Record<string, string>>;
+    /** The columns of Postgres type `date`, read as `YYYY-MM-DD` text. */
+    readonly dates: NameSet;
+    /** The `timestamp` and `timestamptz` columns: a write's text must be strict ISO 8601 with an offset. */
+    readonly timestamps: NameSet;
+    /** The table's foreign keys, from the column list; a containment column must be one to its container's key. */
+    readonly foreignKeys: readonly ForeignKey[];
+    /**
+     * The containment links this table carries a column for, nearest first: a dimension table's container and
+     * the container's own chain; a child's parent and the parent's chain. Every predicate of a Ref covers all.
+     */
+    readonly chain: readonly Container[];
+}
+/** Every table's model by name; read it through `modelOf`, never by a plain property access. */
+export type TableModels = Readonly<Record<string, TableModel>>;
+/** The validated policies of every table; carries the schema and the literal policy types to the store. */
+export declare class Tables<DB, P> {
+    #private;
+    constructor(models: TableModels);
+}
+export declare function tableModels<DB, P>(tables: Tables<DB, P>): TableModels;
+/** Whether `value` is what `defineTables` returned, rather than another form of the same policies. */
+export declare function isTables<DB, P, Other extends object>(value: Tables<DB, P> | Other): value is Tables<DB, P>;
+export declare function modelOf(models: TableModels, table: string): TableModel | undefined;
+/**
+ * Declares the access policy of every table, under the application's vocabulary:
+ * `defineTables(vocabulary, columns)({ notes: { scope: …, actions: … }, … })`. `columns` is the generated column list,
+ * which carries the schema's row types; a list without them makes the policies uncallable. The action and dimension
+ * names are the vocabulary's, and each table's containment comes from it: a key defaults to `id`, a container column
+ * to `<container>_id`, a child's column to `<parent dimension>_id`, and its inherited chain is its parent's.
+ */
+export declare function defineTables<const V extends TableVocabulary, C extends object>(vocabulary: V, columns: C): VocabularyTables<V, C>;
+/** `defineTables(vocabulary, columns)` answers the policies' builder, or names the fix for an untyped column list. */
+export type VocabularyTables<V, C> = [ColumnTypes<C>] extends [never] ? Unavailable<'the column list carries no row types: import columns from the generated src/db/schema.generated.ts (fabrika db codegen)'> : DefineVocabularyPolicies<ColumnTypes<C>, V>;
+/**
+ * The same policies read from values nobody type-checked: `src/db/tables.ts` and its vocabulary as the static reader
+ * has them from a commit. Every shape `defineTables` refuses at runtime is refused here, through the same parse.
+ */
+export declare function readTables(columns: unknown, policies: unknown, vocabulary: unknown): Tables<unknown, unknown>;
+/**
+ * The columns a capability of `action` updates in `model`: the update list for the table's update action, the
+ * columns that declare it as their own write action for any other; none for an action that writes nothing here.
+ */
+export declare function updatableBy(model: TableModel, action: string): NameSet;
+/** Whether the table names `action`: one of its table actions, or a column's own write action. */
+export declare function namesAction(model: TableModel, action: string): boolean;
+/**
+ * The columns a capability of `action` reads: every one that declares no read action of its own, or exactly this
+ * one. A capability reads its own row, so a write `Ref` sees the columns of its action and none of another's.
+ */
+export declare function visibleFor(model: TableModel, action: string): readonly string[];
+/** Every action that updates a column of `model`: its update action and each column's own write action. */
+export declare function updateActions(model: TableModel): readonly string[];
+/** Whether `names` holds `name`: an operation's actions, the one way a policy check reads a list. */
+export declare function includes(names: readonly string[], name: unknown): boolean;
+type PolicyOf<P, T> = T extends keyof P ? P[T] : never;
+type ScopeOf<P, T> = PolicyOf<P, T> extends {
+    readonly scope: infer S;
+} ? S : never;
+export type Operation = 'read' | 'insert' | 'update' | 'delete';
+/** The action, or the union of the actions, of operation `Op` on table `T`; `never` when the policy names none. */
+export type ActionOf<P, T, Op extends Operation> = PolicyOf<P, T> extends {
+    readonly actions: infer Acts;
+} ? Acts extends {
+    readonly [K in Op]: infer A;
+} ? A extends string ? A : A extends readonly (infer L extends string)[] ? L : never : never : never;
+export type DimensionOf<P, T> = ScopeOf<P, T> extends {
+    readonly dimension: infer D extends string;
+} ? D : never;
+export type ContainerOf<P, T> = ScopeOf<P, T> extends {
+    readonly in: {
+        readonly dimension: infer D extends string;
+    };
+} ? D : never;
+/** The dimension that lists and inserts of T are scoped by: its container, or for a top-level table its own. */
+export type ListDimensionOf<P, T> = [ContainerOf<P, T>] extends [never] ? DimensionOf<P, T> : ContainerOf<P, T>;
+export type ParentOf<P, T> = ScopeOf<P, T> extends {
+    readonly child: infer C extends string;
+} ? C : never;
+export type DimensionTableName<P> = {
+    [K in keyof P]: P[K] extends {
+        readonly scope: {
+            readonly dimension: string;
+        };
+    } ? K : never;
+}[keyof P] & string;
+export type ChildTableName<P> = {
+    [K in keyof P]: P[K] extends {
+        readonly scope: {
+            readonly child: string;
+        };
+    } ? K : never;
+}[keyof P] & string;
+export type ApplicationTableName<P> = {
+    [K in keyof P]: P[K] extends {
+        readonly scope: {
+            readonly app: string;
+        };
+    } ? K : never;
+}[keyof P] & string;
+type ListedColumns<P, T, Field extends 'insert' | 'update'> = PolicyOf<P, T> extends {
+    readonly [K in Field]: readonly (infer C extends string)[];
+} ? C : never;
+type Flat<T> = {
+    [K in keyof T]: T[K];
+};
+type ColumnPoliciesOf<P, T> = PolicyOf<P, T> extends {
+    readonly columns: infer C;
+} ? C : never;
+type TableReadAction<P, T> = PolicyOf<P, T> extends {
+    readonly scope: {
+        readonly read: infer A;
+    };
+} ? A : ActionOf<P, T, 'read'>;
+/** Columns whose own read action is not the table's: no read by the table's read action returns them. */
+type RestrictedColumns<P, T> = [ColumnPoliciesOf<P, T>] extends [never] ? never : {
+    [K in keyof ColumnPoliciesOf<P, T>]: ColumnPoliciesOf<P, T>[K] extends {
+        readonly read: infer R;
+    } ? ([TableReadAction<P, T>] extends [R] ? never : K) : never;
+}[keyof ColumnPoliciesOf<P, T>];
+/** A row of table `T` as a store reads it, by the table's read action. */
+export type PolicyRow<DB, P, T> = T extends keyof DB ? Flat<Omit<Selectable<DB[T]>, RestrictedColumns<P, T>>> : never;
+export type InsertValues<DB, P, T> = T extends keyof DB ? Flat<Pick<Insertable<DB[T]>, ListedColumns<P, T, 'insert'> & keyof Insertable<DB[T]>>> : never;
+export type UpdateValues<DB, P, T> = T extends keyof DB ? Flat<Pick<Updateable<DB[T]>, ListedColumns<P, T, 'update'> & keyof Updateable<DB[T]>>> : never;
+/** The values a store inserts into table `T` of a `defineTables` result: `TableInsert<typeof tables, 'deals'>`. */
+export type TableInsert<Tb, T> = Tb extends Tables<infer DB, infer P> ? InsertValues<DB, P, T> : never;
+/** The values a store updates in table `T` of a `defineTables` result: `TableUpdate<typeof tables, 'deals'>`. */
+export type TableUpdate<Tb, T> = Tb extends Tables<infer DB, infer P> ? UpdateValues<DB, P, T> : never;
+/** What a mutation answers: the key, and the new version of a versioned table. It returns no row data. */
+export type Acknowledgement<P, T> = PolicyOf<P, T> extends {
+    readonly version: string;
+} ? {
+    readonly id: string;
+    readonly version: number;
+} : {
+    readonly id: string;
+};
+/** A move also answers the object's new containment chain, by dimension. */
+export type MoveAcknowledgement<P, T> = Acknowledgement<P, T> & {
+    readonly chain: Readonly<Record<string, string>>;
+};
+/** A table with a version column takes `{ expectVersion }` on update; one without takes nothing. */
+export type VersionArguments<P, T> = PolicyOf<P, T> extends {
+    readonly version: string;
+} ? [options: {
+    readonly expectVersion: number;
+}] : [];
+/** Children of T that a select of T can join: their read action is T's read action. */
+export type JoinableChildren<DB, P, T> = {
+    [K in ChildTableName<P> as ParentOf<P, K> extends T ? (ActionOf<P, K, 'read'> extends ActionOf<P, T, 'read'> ? K : never) : never]: PolicyRow<DB, P, K>;
+};

package/types/src/production.d.ts

@@ -0,0 +1,5 @@
+/** Marks this process as one that serves an application; called by the generated entrypoint only. */
+export declare function markProductionProcess(): void;
+export declare function isProductionProcess(): boolean;
+/** Throws when this process serves an application: `what` is a test helper, which production never runs. */
+export declare function refuseInProduction(what: string): void;

package/types/src/registry.d.ts

@@ -0,0 +1,35 @@
+import type { Admissions } from './admissions';
+import type { Session } from './database';
+import type { WebhookTables } from './framework-tables';
+import type { JobLeases } from './job-leases';
+import type { DataAccess } from './orm';
+import type { DataLayerRuntime, TableContext, TableProbe } from './store';
+import type { StoredFiles } from './stored-files';
+/**
+ * Answers what the framework's access check reads from the database: an object's containers, by dimension. `using` is
+ * the session to read in (a job's transaction, which sees the object it just wrote); a statement of its own otherwise.
+ */
+export type Locator = (dimension: string, id: string, using?: Session) => Promise<ReadonlyMap<string, string> | null>;
+/** What the framework writes itself: its own `fabrika_*` tables. Usable once bound. */
+export interface FrameworkTables {
+    readonly webhooks: WebhookTables;
+    readonly jobs: JobLeases;
+    /** A procedure's admission buckets, the challenge tokens it accepted and its byte budget. */
+    readonly admissions: Admissions;
+    /** Every stored file (`fabrika_files`): staged before its object, claimed at its first reference, swept unreferenced. */
+    readonly files: StoredFiles;
+}
+export interface FrameworkSide {
+    /** Connects the layer once and answers its locator; a second call throws. */
+    bind(runtime: DataLayerRuntime): Locator;
+    readonly framework: FrameworkTables;
+    /** The untyped handle over one table that `@fabrika/db/testing` hands the isolation tests. */
+    probe(table: string): TableProbe;
+    /** One table's context, for the framework's own store builders (`defineStore`, `@fabrika/db/testing`). */
+    tableContext(table: string, mode: 'dimension' | 'child'): TableContext;
+    /** The mini-ORM: invocation transactions and the handles of `ctx.db`; usable once bound. */
+    readonly data: DataAccess;
+}
+export declare function register(database: object, side: FrameworkSide): void;
+/** The framework side of an object `scoped` created; undefined for anything else, a structural copy included. */
+export declare function frameworkSideOf(value: unknown): FrameworkSide | undefined;

package/types/src/sql.d.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod/v4';
+import { type Session } from './database';
+/** What a site declares: `'read'` runs queries only, `'write'` also `INSERT`, `UPDATE` and `DELETE`. */
+export type SqlMode = 'read' | 'write';
+/** A value an interpolation binds: a scalar, a `Date` (bound as ISO text), or a list of strings or numbers (an array). */
+export type SqlValue = string | number | boolean | bigint | Date | null | readonly (string | number)[];
+/** One test of a capability's scope on a table: the column holds the value, or one of the list. */
+export interface ScopeTest {
+    readonly column: string;
+    readonly value: string | readonly string[];
+}
+/** A capability's predicate on one table: every row (`'all'`), or an OR of AND groups; no group matches nothing. */
+export type ScopeTerms = 'all' | readonly (readonly ScopeTest[])[];
+/** What a fragment's table is to its statement: read, or the target of its UPDATE or DELETE. */
+export type ScopeUse = 'read' | 'update' | 'delete';
+/**
+ * The scope of `capability` on `table` for `use`, as the data layer predicates its handles; throws when it does not
+ * reach it for that use. `assigned` is the columns an UPDATE's SET names (none when the SET cannot be read with
+ * certainty), and `undefined` before a statement is known.
+ */
+export type ScopeOf = (capability: unknown, table: string, use: ScopeUse, assigned?: readonly string[]) => ScopeTerms;
+/** The operation a write statement performs on one of its targets. */
+export type WriteOperation = 'insert' | 'update' | 'delete';
+/** Throws for a table no statement may write with `operation`: a reference table. */
+export type WriteTarget = (table: string, operation: WriteOperation) => void;
+/**
+ * `ctx.sql.scope(capability, table, alias?)`: the capability's whole predicate on one table, as SQL with bound values.
+ * A fragment is a frozen object with no prototype; what it holds lives in this module's registry, read through
+ * methods captured at load, so no object an application builds or changes is ever taken for one.
+ */
+export interface SqlScope {
+    readonly kind: 'sql-scope';
+}
+/** `ctx.sql(Row)`: the tag for rows of `Row`, and `scope` for the capability's predicate inside its text. */
+export interface SqlTag {
+    <S extends z.core.$ZodType>(row: S): (text: TemplateStringsArray, ...values: readonly (SqlValue | SqlScope)[]) => Promise<z.output<S>[]>;
+    scope(capability: unknown, table: string, alias?: string): SqlScope;
+}
+/** The site a tag is made for: its mode, its binding to the invocation, and the session its statements run in. */
+export interface SqlSite {
+    readonly mode: SqlMode;
+    /** Throws unless the work running now is the invocation the tag was made for. */
+    check(): void;
+    session(): Promise<Session>;
+    /** Fails the site's transaction (the invocation's, or a job's fenced one), so it commits nothing. */
+    fail(): void;
+}
+/**
+ * The SQL `parts` make, with `$1…$n` for the values, or a `QueryRefusedError` that names what is refused: more than
+ * one statement, any statement but a query (and `INSERT`/`UPDATE`/`DELETE` for `'write'`), a nested statement of
+ * another kind, a qualified name outside `schema`, a `fabrika_*` or `pg_*` name, a function call outside the reviewed
+ * built-ins, and a value placed where it would not be bound.
+ */
+export declare function classifySql(parts: readonly string[], mode: SqlMode, schema: string): string;
+/**
+ * `ctx.sql` of one site. Every call first checks that the work running now is the site's invocation, then classifies
+ * the text, then binds the values; only then does it reach the session, so a refused statement sends nothing.
+ */
+export declare function sqlTag(site: SqlSite, schema: string | undefined, termsOf: ScopeOf, writeTarget: WriteTarget): SqlTag;