@fabrika/db 0.8.2 → 0.9.0-cloudflare.2

package/types/src/admissions.d.ts

@@ -0,0 +1,21 @@
+import type { DataLayerRuntime } from './store';
+export interface Admissions {
+    /**
+     * Takes one from `bucket` of `endpoint` in the database's current minute; `false` when `limit` were already taken
+     * there. The counter and the check are one statement.
+     */
+    take(endpoint: string, bucket: string, limit: number): Promise<boolean>;
+    /**
+     * Records the digest of a challenge token `endpoint` accepted, kept for `retainMs`; `false` when it was already
+     * recorded and has not expired, which makes the token's second use a replay.
+     */
+    recordChallenge(endpoint: string, tokenDigest: string, retainMs: number): Promise<boolean>;
+    /**
+     * Reserves `bytes` of `endpoint`'s hourly byte budget `limit`, in the database's current hour; `false`, with nothing
+     * taken, when they no longer fit. The check and the counter are one statement.
+     */
+    reserveBytes(endpoint: string, bytes: number, limit: number): Promise<boolean>;
+    /** Gives back `bytes` of a reservation of the current hour that the request did not need. */
+    releaseBytes(endpoint: string, bytes: number): Promise<void>;
+}
+export declare function admissions(runtime: () => DataLayerRuntime): Admissions;

package/types/src/application-rows.d.ts

@@ -0,0 +1,58 @@
+import { type ForeignKey, type TableModels } from './policy';
+/** Why the values of a set of application rows cannot be seeded as given. */
+export type ApplicationRowRefusal = 
+/** `table` is no application table: `mode` is its scope mode, or `null` when no policy names it. */
+{
+    readonly kind: 'table';
+    readonly table: string;
+    readonly mode: string | null;
+}
+/** `column` is no column of `table`'s column list. */
+ | {
+    readonly kind: 'column';
+    readonly table: string;
+    readonly column: string;
+}
+/** `column` is the row's key, version or creator, which the seeding stamps. */
+ | {
+    readonly kind: 'stamped';
+    readonly table: string;
+    readonly column: string;
+}
+/** `column` is a file column, which the seeding fills with a live, scanned file. */
+ | {
+    readonly kind: 'file';
+    readonly table: string;
+    readonly column: string;
+}
+/** `column` is given an array or an object, where a column takes one value. */
+ | {
+    readonly kind: 'value';
+    readonly table: string;
+    readonly column: string;
+    readonly given: 'array' | 'object';
+}
+/** The values give `columns`, some but not all columns of the foreign key `key`. */
+ | {
+    readonly kind: 'partial-key';
+    readonly table: string;
+    readonly columns: readonly string[];
+    readonly key: ForeignKey;
+}
+/** The foreign keys that link `tables` form a cycle, so no order seeds each after the rows it links to. */
+ | {
+    readonly kind: 'cycle';
+    readonly tables: readonly string[];
+};
+export interface ApplicationRowsPlan {
+    /** The application tables, each after every given table it links to. */
+    readonly order: readonly string[];
+    /** Each application table's foreign keys to another given table that the values leave to the link. */
+    readonly links: Readonly<Record<string, readonly ForeignKey[]>>;
+    /** Every refusal, by table then column; a cycle last. Empty when the rows can be seeded. */
+    readonly refusals: readonly ApplicationRowRefusal[];
+}
+/** The plan of seeding one row of each table `rows` names (table → column → value). */
+export declare function planApplicationRows(models: TableModels, rows: Readonly<Record<string, Readonly<Record<string, unknown>>>>): ApplicationRowsPlan;
+/** A refusal in the words both the checker and the test kit use, so the two never describe one rule differently. */
+export declare function applicationRowRefusalText(refusal: ApplicationRowRefusal): string;

package/types/src/builtins.d.ts

@@ -0,0 +1,42 @@
+export declare const ownKeys: {
+    (o: object): string[];
+    (o: {}): string[];
+};
+export declare const ownDescriptor: (o: any, p: PropertyKey) => PropertyDescriptor | undefined;
+export declare const hasOwn: (o: object, v: PropertyKey) => boolean;
+export declare const isArray: (arg: any) => arg is any[];
+export declare const freeze: {
+    <T extends Function>(f: T): T;
+    <T extends {
+        [idx: string]: U | null | undefined | object;
+    }, U extends string | bigint | number | boolean | symbol>(o: T): Readonly<T>;
+    <T>(o: T): Readonly<T>;
+};
+export declare const prototypeOf: (o: any) => any;
+export declare const isSafeInteger: (number: unknown) => boolean;
+export declare const OBJECT_PROTOTYPE: unknown;
+export declare const ownNames: (o: any) => string[];
+export declare const ownSymbols: (o: any) => symbol[];
+/**
+ * A frozen set of names, read through the captured `Object.hasOwn` only. Entries are defined, not assigned, so
+ * `__proto__` or an inherited setter cannot drop one.
+ */
+export type NameSet = Readonly<Record<string, true>>;
+export declare function nameSet(names: readonly string[]): NameSet;
+export declare function inSet(set: NameSet, name: unknown): name is string;
+/** The names in the order they were added. */
+export declare function namesOf(set: NameSet): readonly string[];
+/**
+ * The elements of a plain array, each passed through `parse` before it is copied; undefined for anything else: a
+ * subclass, an array with an own property besides its indexes and `length` (an own `map` or `Symbol.iterator`),
+ * a hole, or an accessor element. The input's own methods never run.
+ */
+export declare function parseList<T>(value: unknown, parse: (item: unknown) => T): T[] | undefined;
+/** A frozen copy of a string map, read through the captured `Map.prototype.forEach`. */
+export declare function recordOf(map: ReadonlyMap<string, string>): Readonly<Record<string, string>>;
+/** Defines an own property: unlike an assignment, it cannot hit `__proto__` or an inherited setter. */
+export declare function setOwn<V>(record: Record<string, V>, key: string, value: V): void;
+/** Redefines an own data property of any object, as `setOwn` does for a record. */
+export declare function defineValue(target: object, key: string, value: unknown): void;
+/** An own property of a record, or undefined: an inherited one is never read. */
+export declare function ownEntry<V>(record: Readonly<Record<string, V>>, key: string): V | undefined;

package/types/src/capability.d.ts

@@ -0,0 +1,119 @@
+/**
+ * One authorized object, for one action. The framework mints the class that implements it; this package never
+ * constructs one. The `~capability` member is type-only: the implementing class declares it so that
+ * `Ref<'note', 'notes.read'>` and `Ref<'note', 'notes.delete'>` stay distinct types, and nothing reads it at runtime.
+ */
+export interface Ref<Dim extends string, Action extends string> {
+    readonly '~capability': {
+        readonly kind: 'ref';
+        readonly dimension: Dim;
+        readonly action: Action;
+    };
+}
+/** The scope values of one dimension in which the caller holds one action. */
+export interface Within<Dim extends string, Action extends string> {
+    readonly '~capability': {
+        readonly kind: 'within';
+        readonly dimension: Dim;
+        readonly action: Action;
+    };
+}
+/**
+ * One action held as a global grant: the capability of an `app` endpoint, for data of the whole application. Like a
+ * `Ref`, the member is type-only.
+ */
+export interface AppCapability<Action extends string> {
+    readonly '~capability': {
+        readonly kind: 'app';
+        readonly action: Action;
+    };
+}
+/**
+ * One claimed row of one queue table, for one action: what a claim answers as `row.ref`, and what `tx.db.on(row.ref)`
+ * finishes the row through. Like a `Ref`, the member is type-only.
+ */
+export interface RowRef<Table extends string, Action extends string> {
+    readonly '~capability': {
+        readonly kind: 'row';
+        readonly table: Table;
+        readonly action: Action;
+    };
+}
+export interface RefGrant {
+    readonly kind: 'ref';
+    readonly dimension: string;
+    readonly action: string;
+    readonly principal: string;
+    readonly id: string;
+    /** The values of the containers this object lies in, by dimension (`workspace → w1` for a note). */
+    readonly chain: ReadonlyMap<string, string>;
+}
+/** The values of one container dimension in which the caller holds the action: `organization → [o1]`. */
+export interface ContainerGrant {
+    readonly dimension: string;
+    readonly values: readonly string[];
+}
+/**
+ * The most scope values one `Within` carries, its own and its containers' together. Each becomes one bound
+ * parameter of every statement the `Within` scopes; Postgres binds at most 65535.
+ */
+export declare const MAX_WITHIN_VALUES = 1000;
+export interface WithinGrant {
+    readonly kind: 'within';
+    readonly dimension: string;
+    readonly action: string;
+    readonly principal: string;
+    /** The values of `dimension` itself; `all` comes from a grant that is not limited to scope values. */
+    readonly values: readonly string[] | 'all';
+    /**
+     * The containers of `dimension` whose grants also authorise this `Within`. They stay separate from `values`, so
+     * every statement judges a row by the chain columns it carries now: a scope moved out of a container is out.
+     */
+    readonly containers: readonly ContainerGrant[];
+    /**
+     * The dimensions inside `dimension` (the listed object's own and the containers between) in which the caller holds
+     * the action: a row that lies in one of their values is listed, as a single-object read of it is allowed.
+     */
+    readonly contained: readonly ContainerGrant[];
+}
+/** An `app` endpoint's grant: the action everywhere in the application, which the proxy checked was held globally. */
+export interface AppGrant {
+    readonly kind: 'app';
+    readonly action: string;
+    readonly principal: string;
+}
+/** A row a claim leased: the table, its key, and the containment it had then, column by column. */
+export interface RowGrant {
+    readonly kind: 'row';
+    readonly table: string;
+    readonly action: string;
+    readonly principal: string;
+    readonly id: string;
+    /** The row's containment columns and their values when it was claimed: a row moved since is out of reach. */
+    readonly chain: ReadonlyMap<string, string>;
+}
+export type CapabilityGrant = RefGrant | WithinGrant | AppGrant | RowGrant;
+/** How a refusal names a capability: `a Ref of note`, `a Within of workspace`, `an app capability`, `a row of outbox`. */
+export declare function describeGrant(grant: CapabilityGrant): string;
+/** One generation of a job's lease, held by one attempt. A write of the attempt commits only while it still holds it. */
+export interface LeaseFence {
+    readonly job: string;
+    /** The attempt holding the lease. */
+    readonly holder: string;
+    readonly generation: number;
+}
+/**
+ * The framework side of a capability. `resolve` returns what an authentic capability of the current request grants,
+ * or throws when the value is not one, is forged, or belongs to a request that has ended or is not the current one.
+ * The data layer checks the kind, the dimension and the action itself, on every operation.
+ */
+export interface CapabilityAuthority {
+    resolve(capability: unknown): CapabilityGrant;
+    /** Mints the capability of one claimed row, bound to the work running now as every capability is. */
+    row(grant: Omit<RowGrant, 'kind'>): unknown;
+    /**
+     * The lease the work running now must still hold for a write to commit: the job attempt's, or `null` in a
+     * request. Every mutation checks it inside its own transaction.
+     */
+    fence(): LeaseFence | null;
+}

package/types/src/codegen-sqlite.d.ts

@@ -0,0 +1,6 @@
+import { type SqliteMigrationBundle } from './sqlite-migrate';
+/**
+ * Applies `bundles` (the framework's `fabrika`, then the application's `app`) to a fresh in-memory database and renders
+ * the module for `SCHEMA_FILE` from its application tables. Deterministic for given migrations.
+ */
+export declare function generateSqliteSchema(bundles: readonly SqliteMigrationBundle[]): Promise<string>;

package/types/src/codegen.d.ts

@@ -0,0 +1,82 @@
+import { type DatabaseObject } from '@fabrika/platform-node';
+import { z } from 'zod/v4';
+/** Where an application keeps the generated types and column list; committed, never hand-edited. */
+export declare const SCHEMA_FILE = "src/db/schema.generated.ts";
+/** A column's TypeScript types: what a read returns, and what an insert or update may bind when that differs. */
+export interface ScalarType {
+    readonly select: string;
+    readonly write?: string;
+}
+export declare class CodegenError extends Error {
+    name: string;
+}
+declare const catalogColumnSchema: z.ZodObject<{
+    table_name: z.ZodString;
+    column_name: z.ZodString;
+    type_name: z.ZodString;
+    type_type: z.ZodString;
+    type_category: z.ZodString;
+    nullable: z.ZodBoolean;
+    generated: z.ZodEnum<{
+        default: "default";
+        no: "no";
+        always: "always";
+    }>;
+    enum_labels: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type CatalogColumn = z.infer<typeof catalogColumnSchema>;
+declare const catalogForeignKeySchema: z.ZodObject<{
+    table_name: z.ZodString;
+    constraint_name: z.ZodString;
+    columns: z.ZodArray<z.ZodString>;
+    referenced_table: z.ZodString;
+    referenced_columns: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type CatalogForeignKey = z.infer<typeof catalogForeignKeySchema>;
+/** What codegen reads of the schema: every column, and every foreign key between its tables. */
+export interface Catalog {
+    readonly columns: readonly CatalogColumn[];
+    readonly foreignKeys: readonly CatalogForeignKey[];
+}
+/**
+ * Reads the columns of the application's schema, refusing one that escapes it or holds a database object that
+ * `objects`, the migrations' manifest (`PostgresApplicationMigrations.objects`), does not name. The URL is a
+ * credential: no message here contains it.
+ */
+export declare function introspectSchema(url: string, schema: string, objects: readonly DatabaseObject[]): Promise<readonly CatalogColumn[]>;
+/** `introspectSchema`, with the foreign keys between the schema's tables. */
+export declare function introspectCatalog(url: string, schema: string, objects: readonly DatabaseObject[]): Promise<Catalog>;
+/** What the renderer needs of a column beyond its name, whichever database it was read from. */
+export interface DescribedColumn {
+    readonly scalar: ScalarType;
+    readonly nullable: boolean;
+    readonly generated: 'no' | 'default' | 'always';
+    /** The column list field that names the column: a day, a timestamp, or (on SQLite) a boolean. */
+    readonly list: 'dates' | 'timestamps' | 'booleans' | undefined;
+}
+/** A foreign key as the renderer reads it: the columns of `table_name` that reference `referenced_table`. */
+export interface ForeignKeyColumns {
+    readonly table_name: string;
+    readonly columns: readonly string[];
+    readonly referenced_table: string;
+    readonly referenced_columns: readonly string[];
+}
+/** A column as the renderer groups it, before its type is described. */
+export interface NamedColumn {
+    readonly table_name: string;
+    readonly column_name: string;
+}
+/**
+ * The generated module: one interface per application table, the `DB` map Kysely and `defineTables` take, and the
+ * runtime column list with each table's foreign keys to application tables. Deterministic for a given catalog, so
+ * `fabrika db codegen --verify` can compare text.
+ */
+export declare function renderSchema(catalog: readonly CatalogColumn[], foreignKeys?: readonly CatalogForeignKey[]): string;
+/**
+ * `renderSchema` over columns of any database: `describe` gives each column's types and list field, and refuses a
+ * type the data layer does not read. A foreign key's `constraint_name` is not rendered; keys keep the given order.
+ */
+export declare function renderTables<C extends NamedColumn>(catalog: readonly C[], foreignKeys: readonly ForeignKeyColumns[], describe: (column: C) => DescribedColumn): string;
+/** Introspects the migrated schema, checked against the migrations' manifest, and renders the module for `SCHEMA_FILE`. */
+export declare function generateSchema(url: string, schema: string, objects: readonly DatabaseObject[]): Promise<string>;
+export {};

package/types/src/database.d.ts

@@ -0,0 +1,179 @@
+import { type Dialect, Kysely, type QueryCompiler, type RootOperationNode } from 'kysely';
+import { type GuardContext } from './guard';
+export type LooseDB = Record<string, Record<string, unknown>>;
+/** What a statement runs on: the database's own executor, or the one of the transaction it runs in. */
+export type Executor = Pick<Kysely<LooseDB>, 'executeQuery'>;
+/** The SQL a database speaks: Postgres on Bun, SQLite in a Cloudflare Durable Object (ADR-0065). */
+export type SqlDialect = 'postgres' | 'sqlite';
+export interface TransactionOptions {
+    /**
+     * A `READ ONLY` transaction on Postgres. SQLite opens none: each statement runs in a transaction of its own, which
+     * rolls back a statement that wrote. A read-only session refuses writes either way.
+     */
+    readonly readOnly: boolean;
+    /** How long the transaction may sit idle before the database ends it; a database without the setting ignores it. */
+    readonly idleTimeoutMs?: number;
+}
+/**
+ * Runs `body` in one transaction, on the executor it hands it: commits when `body` resolves, rolls back when it
+ * rejects, and rejects with `body`'s error. Its BEGIN, COMMIT and ROLLBACK failures reject with the driver's error.
+ */
+export type TransactionRunner = <T>(options: TransactionOptions, body: (executor: Executor) => Promise<T>) => Promise<T>;
+/** What a `Database` runs on: the driver, the compiler of its dialect, and how it opens a transaction. */
+export interface DatabaseEngine {
+    readonly dialect: SqlDialect;
+    readonly kysely: Kysely<LooseDB>;
+    /** Compiles every guarded tree; frozen, since a patch to it after the guard ran would bypass the guard. */
+    readonly compiler: QueryCompiler;
+    readonly transaction: TransactionRunner;
+    /** The application's schema, the connection's `search_path`; `undefined` where the database has none. */
+    readonly schema?: string;
+}
+/**
+ * The compiler turns the guarded tree into SQL, so a patch to it after the guard ran would bypass the guard.
+ * Freezing it when this module loads, before application modules, makes such a patch throw instead.
+ */
+export declare function freezePrototypeChain(object: object): void;
+/**
+ * `app_<id>`, the schema an application's migrations create (ADR-0017). `@fabrika/platform-node`'s
+ * `applicationDatabaseSchema` derives the same name for the migration runner; the two must agree.
+ */
+export declare function applicationSchema(appId: string): string;
+/** The connection the data layer runs on. It has no public query method: everything goes through a store. */
+export declare class Database {
+    #private;
+    private constructor();
+    /**
+     * Any Kysely Postgres dialect: `@fabrika/db/postgres` opens Bun.SQL through it, tests use one that records statements
+     * instead of sending them.
+     */
+    static fromDialect(dialect: Dialect, options?: {
+        readonly schema?: string;
+    }): Database;
+    /** A database of another dialect (`@fabrika/db/sqlite`), with its own frozen compiler and transaction runner. */
+    static fromEngine(engine: DatabaseEngine): Database;
+    get dialect(): SqlDialect;
+    /** The application's schema, the connection's `search_path`; `undefined` over a bare dialect and on SQLite. */
+    get schema(): string | undefined;
+    close(): Promise<void>;
+}
+/**
+ * Opens the pool's first connection, which stays open. A pool with one open connection makes a statement wait for it
+ * when the database refuses another (Bun 1.3.14), so only a pool with none fails on a database at its limit: the test
+ * kit opens it before a file's first case, where a refusal is waited out instead of failing a case.
+ */
+export declare function openFirstConnection(database: Database): Promise<void>;
+/** The connection a session runs on, and whether the request running now may only read. */
+export interface SessionSource {
+    readonly database: Database;
+    readonly readOnly?: () => boolean;
+}
+/**
+ * The one way to a session: every statement of a request — a store's, a locator's, a framework table's — asks the
+ * runtime whether the request is read-only. A read-only session refuses every write and lock before it reaches the
+ * database, and reads in `READ ONLY` transactions.
+ */
+export declare function sessionOf(source: SessionSource): Session;
+/** What a session reports to, and asks, the transaction it runs in. */
+interface SessionHooks {
+    /** Hears of every statement the database refused: in a transaction, Postgres aborts the rest of it. */
+    readonly failed?: () => void;
+    /** Whether the transaction is still the work's: a session kept past it runs nothing on a connection given back. */
+    readonly open?: () => boolean;
+}
+/**
+ * Runs guarded operation trees; the only path from the layer to the connection. A driver failure leaves it as a
+ * `DatabaseError`, which carries the SQLSTATE and nothing the driver said about the row.
+ */
+export declare class Session {
+    #private;
+    constructor(executor: Executor, engine: DatabaseEngine, inTransaction: boolean, readOnly: boolean, hooks?: SessionHooks);
+    get readOnly(): boolean;
+    /** The dialect of the database this session runs on: a framework statement picks its text by it. */
+    get dialect(): SqlDialect;
+    /** Fails the transaction this session runs in, so it commits nothing: a statement refused before it was sent. */
+    fail(): void;
+    run<O>(node: RootOperationNode, context: GuardContext): Promise<O[]>;
+    /**
+     * Runs `work` in one transaction (`READ ONLY` in a read-only session); inside one, it runs in the transaction already
+     * open. When `signal` aborts, the transaction rolls back and its connection goes back to the pool at once, whether
+     * `work` returned or not; its session then runs nothing more.
+     */
+    transaction<T>(work: (session: Session) => Promise<T>, signal?: AbortSignal): Promise<T>;
+}
+/** How long an invocation's transaction may sit idle before Postgres ends it, and its connection with it. */
+export declare const INVOCATION_IDLE_TIMEOUT_MS = 30000;
+/** A writing invocation that holds its object's storage transaction longer than this logs one line. */
+export declare const TRANSACTION_HELD_LOG_MS = 1000;
+/** A writing invocation that holds its object's storage transaction longer than this is also reported. */
+export declare const TRANSACTION_HELD_REPORT_MS = 5000;
+/** Where an enclosure tells how long it held its object: every other event of the object waited that long. */
+export interface HoldWatch {
+    /** The site the invocation serves, which the log line names. */
+    readonly site: string;
+    /** Hears a hold longer than `TRANSACTION_HELD_REPORT_MS`, in whole ms. */
+    readonly held: (heldMs: number) => void;
+}
+/**
+ * The one transaction of an invocation (a request, a webhook delivery): opened by its first statement, then ended
+ * once by the framework — committed after the handler returned and its output passed validation, rolled back
+ * otherwise. Every handle of the invocation runs in `session()`. Ending it and giving its connection back are two
+ * states: once ended no statement runs in it, and the connection is back in the pool whether the COMMIT succeeded,
+ * failed, or the connection died.
+ */
+export declare class InvocationTransaction {
+    #private;
+    /** `now` is the clock an enclosure's hold is measured by. */
+    constructor(database: Database, readOnly: boolean, now?: () => number);
+    /** A `READ ONLY` transaction: a query's or an export's. */
+    get readOnly(): boolean;
+    /** Whether the transaction was opened: an invocation that reached no data commits nothing. */
+    get opened(): boolean;
+    /** Marks it failed, so it commits nothing: a statement refused before it was sent, even when the handler caught it. */
+    fail(): void;
+    /** No statement runs in it any more. */
+    get ended(): boolean;
+    /** Its connection is back in the pool (or it never took one). */
+    get released(): boolean;
+    /**
+     * Runs `work`: the invocation from its handler to its `commit()`. On SQLite a writing invocation's transaction
+     * encloses `work`, opened before it: a Durable Object's transaction holds back every other event, the answers to the
+     * object's own I/O included, until its callback ends, so the handler runs inside it. There `commit()` and `rollback()`
+     * decide, the COMMIT runs once `work` returned, and a failed COMMIT rejects with a `DatabaseError`. A read-only
+     * invocation, and every invocation elsewhere, runs `work` as is: a read-only one on SQLite holds no storage
+     * transaction, so the object serves other events while it awaits.
+     *
+     * Only the SQLite enclosure is measured for `watch`, from entering the transaction until it settled: it holds the
+     * whole object, where a Postgres transaction holds one pooled connection and other requests go on.
+     */
+    enclose<T>(work: () => Promise<T>, watch: HoldWatch): Promise<T>;
+    /** The session the invocation's statements run in; the first call opens the transaction. */
+    session(): Promise<Session>;
+    /**
+     * Commits what the invocation wrote. A statement the database refused aborted the transaction, so it rolls back
+     * and throws instead: Postgres would answer the COMMIT with a silent ROLLBACK. A failed COMMIT throws a
+     * `DatabaseError`, after the connection is back in the pool.
+     */
+    commit(): Promise<void>;
+    /** Discards what the invocation wrote; idempotent, never throws, and returns once the connection is back (inside `enclose`, it only decides). */
+    rollback(): Promise<void>;
+}
+/**
+ * A scalar parameter of a framework statement; Bun.SQL mis-binds arrays and JSON strings. No Date: these texts skip
+ * the compiler that binds one, and a lease time is the database's clock, never the process's.
+ */
+export type FixedParameter = string | number | null;
+/**
+ * One of the framework's own fixed statements (`job-leases.ts`): a constant text with scalar parameters. They need
+ * what the guard refuses on purpose (`now()`, `set_config`, `pg_backend_pid()`, `on conflict`), so they bypass it;
+ * no subpath exports this, and no text is ever built from a caller's value.
+ */
+export declare function runFixedStatement(session: Session, text: string, parameters: readonly FixedParameter[]): Promise<readonly unknown[]>;
+/** A bound parameter of an application's own statement (`sql.ts`), after its value was encoded for the driver. */
+export type SqlParameter = string | number | boolean | bigint | null;
+/**
+ * One `ctx.sql` statement, whose text `sql.ts` classified and whose values are bound parameters only. It runs through the
+ * session's one path to the connection, so a statement the database refuses fails the invocation it runs in.
+ */
+export declare function runApplicationStatement(session: Session, text: string, parameters: readonly SqlParameter[]): Promise<readonly unknown[]>;
+export {};

package/types/src/description.d.ts

@@ -0,0 +1,109 @@
+import { type NameSet } from './builtins';
+export type Primitive = string | number | bigint | boolean | Date;
+export type ComparisonOperator = '=' | '<>' | '<' | '<=' | '>' | '>=';
+export type PatternOperator = 'like' | 'ilike' | 'not like' | 'not ilike';
+export type ListOperator = 'in' | 'not in';
+export type NullOperator = 'is' | 'is not';
+export type AllowedOperator = ComparisonOperator | PatternOperator | ListOperator | NullOperator;
+export interface Compare {
+    readonly kind: 'compare';
+    readonly column: string;
+    readonly operator: AllowedOperator;
+    readonly value: Primitive | readonly Primitive[] | null;
+}
+/** A case-insensitive substring match; the text's `%`, `_` and `\` match literally. */
+export interface Contains {
+    readonly kind: 'contains';
+    readonly column: string;
+    readonly text: string;
+}
+export interface AnyOf {
+    readonly kind: 'any';
+    readonly conditions: readonly (Compare | Contains)[];
+}
+export type Condition = Compare | Contains | AnyOf;
+/** What a select may name: the visible columns of its table and of the children it may join. */
+export interface TableShape {
+    readonly table: string;
+    readonly visible: NameSet;
+    readonly joinable: Readonly<Record<string, JoinShape>>;
+    /** The `date` columns, which a read answers as `YYYY-MM-DD` text. */
+    readonly dates: NameSet;
+}
+export interface JoinShape {
+    readonly shape: TableShape;
+    /** The child's read actions: a select of the parent joins it only with one of them. */
+    readonly readActions: readonly string[];
+    /** The composite foreign key: child column = parent column, for each pair. */
+    readonly on: readonly {
+        readonly childColumn: string;
+        readonly parentColumn: string;
+    }[];
+}
+export interface JoinState {
+    readonly join: JoinShape;
+    readonly select: SelectState;
+}
+export interface SelectState {
+    /** Identifies the description a callback received, so it cannot return one from elsewhere. */
+    readonly origin: object;
+    readonly table: string;
+    readonly columns: readonly string[] | undefined;
+    readonly conditions: readonly Condition[];
+    readonly orderBy: readonly {
+        readonly column: string;
+        readonly direction: 'asc' | 'desc';
+    }[];
+    readonly limit: number | undefined;
+    readonly offset: number | undefined;
+    readonly joins: readonly JoinState[];
+}
+type Comparable<V> = Exclude<V, null | undefined>;
+type Columns<Row> = keyof Row & string;
+type StringColumn<Row> = {
+    [K in Columns<Row>]: Comparable<Row[K]> extends string ? K : never;
+}[Columns<Row>];
+type NullableColumn<Row> = {
+    [K in Columns<Row>]: null extends Row[K] ? K : never;
+}[Columns<Row>];
+export type ConditionTuple<Row> = {
+    [K in Columns<Row>]: readonly [K, ComparisonOperator, Comparable<Row[K]>] | readonly [K, ListOperator, readonly Comparable<Row[K]>[]];
+}[Columns<Row>] | {
+    [K in StringColumn<Row>]: readonly [K, PatternOperator | 'contains', string];
+}[StringColumn<Row>];
+type Prefixed<C extends string, J> = {
+    [K in keyof J & string as `${C}.${K}`]: J[K];
+};
+export type NoColumns = Record<never, never>;
+/**
+ * The only query surface a store callback sees: a frozen description, not a Kysely builder. There is nothing to
+ * execute, no raw SQL entry point, and no way to name a table other than this one and its declared children.
+ */
+export declare class ScopedSelect<Row, Selected, Children> {
+    #private;
+    constructor(token: symbol, state: SelectState, shape: TableShape);
+    /** The columns to return; without it, every visible column. */
+    columns<const C extends Columns<Row>>(columns: readonly C[]): ScopedSelect<Row, Pick<Row, C>, Children>;
+    where<C extends Columns<Row>>(column: C, operator: ComparisonOperator, value: Comparable<Row[C]>): ScopedSelect<Row, Selected, Children>;
+    where<C extends Columns<Row>>(column: C, operator: ListOperator, values: readonly Comparable<Row[C]>[]): ScopedSelect<Row, Selected, Children>;
+    where<C extends StringColumn<Row>>(column: C, operator: PatternOperator, pattern: string): ScopedSelect<Row, Selected, Children>;
+    where<C extends NullableColumn<Row>>(column: C, operator: NullOperator, value: null): ScopedSelect<Row, Selected, Children>;
+    /** One OR group of conditions on this table's columns. */
+    whereAny(conditions: readonly ConditionTuple<Row>[]): ScopedSelect<Row, Selected, Children>;
+    /** A case-insensitive substring match in which `%` and `_` in the text match themselves. */
+    contains(column: StringColumn<Row>, text: string): ScopedSelect<Row, Selected, Children>;
+    orderBy(column: Columns<Row>, direction?: 'asc' | 'desc'): ScopedSelect<Row, Selected, Children>;
+    limit(limit: number): ScopedSelect<Row, Selected, Children>;
+    offset(offset: number): ScopedSelect<Row, Selected, Children>;
+    /** An inner join to a declared child; its columns come back prefixed (`note_comments.body`). */
+    join<C extends keyof Children & string, J>(child: C, build: (q: ScopedSelect<Children[C], Children[C], NoColumns>) => ScopedSelect<Children[C], J, NoColumns>): ScopedSelect<Row, Selected & Prefixed<C, J>, Children>;
+}
+/** A column the shape lets a query name; a hidden one is refused like a missing one. */
+export declare function columnOf(shape: TableShape, name: unknown): string;
+/** One `[column, operator, value]` condition over a caller's values, checked before anything reads it further. */
+export declare function parseCondition(shape: TableShape, column: unknown, operator: unknown, value: unknown): Compare | Contains;
+export declare function startSelect<Row, Children>(shape: TableShape): ScopedSelect<Row, Row, Children>;
+/** The description a callback returned; it must derive from the one it received. */
+export declare function finishSelect<Row, Children>(built: unknown, start: ScopedSelect<Row, Row, Children>): SelectState;
+export declare function isPrimitive(value: unknown): value is Primitive;
+export {};