@fabrika/db 0.8.1 → 0.9.0-dev.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/db",
-	"version": "0.8.1",
+	"version": "0.9.0-dev.2",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -12,47 +12,48 @@
 	},
 	"files": [
 		"src",
-		"!src/**/__tests__/**"
+		"!src/**/__tests__/**",
+		"types"
 	],
 	"exports": {
 		".": {
 			"bun": "./src/index.ts",
-			"types": "./src/index.ts",
+			"types": "./types/src/index.d.ts",
 			"default": "./src/index.ts"
 		},
 		"./capability": {
 			"bun": "./src/capability.ts",
-			"types": "./src/capability.ts",
+			"types": "./types/src/capability.d.ts",
 			"default": "./src/capability.ts"
 		},
 		"./tables": {
 			"bun": "./src/tables.ts",
-			"types": "./src/tables.ts",
+			"types": "./types/src/tables.d.ts",
 			"default": "./src/tables.ts"
 		},
 		"./framework": {
 			"bun": "./src/framework.ts",
-			"types": "./src/framework.ts",
+			"types": "./types/src/framework.d.ts",
 			"default": "./src/framework.ts"
 		},
 		"./migrations": {
 			"bun": "./src/migrations.ts",
-			"types": "./src/migrations.ts",
+			"types": "./types/src/migrations.d.ts",
 			"default": "./src/migrations.ts"
 		},
 		"./production": {
 			"bun": "./src/production.ts",
-			"types": "./src/production.ts",
+			"types": "./types/src/production.d.ts",
 			"default": "./src/production.ts"
 		},
 		"./codegen": {
 			"bun": "./src/codegen.ts",
-			"types": "./src/codegen.ts",
+			"types": "./types/src/codegen.d.ts",
 			"default": "./src/codegen.ts"
 		},
 		"./testing": {
 			"bun": "./src/testing.ts",
-			"types": "./src/testing.ts",
+			"types": "./types/src/testing.d.ts",
 			"default": "./src/testing.ts"
 		}
 	},
@@ -61,8 +62,8 @@
 		"test": "bun test"
 	},
 	"dependencies": {
-		"@fabrika/auth-core": "0.8.1",
-		"@fabrika/platform-node": "0.8.1",
+		"@fabrika/auth-core": "0.9.0-dev.2",
+		"@fabrika/platform-node": "0.9.0-dev.2",
 		"kysely": "0.29.6",
 		"kysely-postgres-js": "5.0.1",
 		"zod": "^3.25.76"

package/src/testing.ts

@@ -371,6 +371,7 @@ export async function testDatabase(options: TestDatabaseOptions): Promise<TestDa
 		if (process.env[TEST_POSTGRES_REQUIRED] === '1') {
 			throw new Error(`${options.label}: ${TEST_POSTGRES_REQUIRED}=1, but ${TEST_POSTGRES_URL} is unset`)
 		}
+		// The Zerops build counts this line's text in every framework release's output: never reword it.
 		console.warn(`${options.label} skipped: set ${TEST_POSTGRES_URL} to run the Postgres-backed tests`)
 		return null
 	}

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/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,114 @@
+/**
+ * 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[];
+}
+/** 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.d.ts

@@ -0,0 +1,52 @@
+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";
+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>;
+/**
+ * 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;
+/** 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,124 @@
+import { type Dialect, Kysely, type RootOperationNode } from 'kysely';
+import { type GuardContext } from './guard';
+type LooseDB = Record<string, Record<string, unknown>>;
+type Executor = Pick<Kysely<LooseDB>, 'executeQuery'>;
+/**
+ * `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;
+export interface PostgresOptions {
+    readonly url: string;
+    /** The application's schema (`app_<id>`), set as the connection's `search_path`. */
+    readonly schema: string;
+    readonly max?: number;
+}
+/** 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();
+    /**
+     * Over `Bun.SQL` with `prepare: false`: Bun otherwise keeps one prepared statement per distinct SQL text per
+     * connection, and `in` lists of different lengths make that grow without bound.
+     */
+    static postgres(options: PostgresOptions): Database;
+    /** Any Kysely Postgres dialect; tests use one that records statements instead of sending them. */
+    static fromDialect(dialect: Dialect): Database;
+    /** The application's schema, the connection's `search_path`; `undefined` over a bare dialect. */
+    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, kysely: Kysely<LooseDB> | undefined, readOnly: boolean, hooks?: SessionHooks);
+    get readOnly(): boolean;
+    /** 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;
+/**
+ * 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;
+    constructor(database: Database, readOnly: boolean);
+    /** 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;
+    /** 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. */
+    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 {};

package/types/src/errors.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Why the layer refused a capability, as a closed catalog: a server log names the reason and its fixed text, never the
+ * message, which can name a table, a dimension or a value.
+ */
+export declare const CAPABILITY_ERRORS: Readonly<{
+    wrong_capability: "the operation takes another capability than it was given: another kind (a Ref, a Within or an app capability) or dimension";
+    wrong_action: "the capability holds another action than the table names for the operation";
+    out_of_reach: "the table does not lie in the capability's dimension, or the capability does not reach it";
+    unenforceable: "the table carries no column for a dimension of the capability's chain, so the layer cannot enforce it";
+    undeclared_operation: "the table's policy declares no action for the operation, or handlers do not write the table";
+    table_kind: "the operation needs another kind of table (a dimension, a child or an application table)";
+    within_size: "a Within carries more scope values than one statement binds";
+    layer_unbound: "the data layer was used before the framework connected it at boot, or connected a second time";
+}>;
+export type CapabilityErrorReason = keyof typeof CAPABILITY_ERRORS;
+/** A capability of the wrong kind, dimension or action for the operation, or the layer used outside its binding. */
+export declare class CapabilityError extends Error {
+    name: string;
+    /** What a log may say; the message is for the author's own run. */
+    readonly reason: CapabilityErrorReason;
+    constructor(reason: CapabilityErrorReason, message: string);
+}
+/**
+ * Why the layer refused, as a closed catalog: a server log names the reason and its fixed text, never the message,
+ * which can quote a value the request sent.
+ */
+export declare const QUERY_REFUSALS: {
+    readonly invalid_argument: "a data-layer call took an argument of another shape than its type declares";
+    readonly invalid_value: "a value cannot be bound: an invalid or out-of-range date, or a non-finite number";
+    readonly invalid_name: "a configured name (application, schema, table or file column) breaks its naming rule";
+    readonly unknown_column: "a column the table does not declare, or one this operation may not set";
+    readonly unknown_table: "a table src/db/tables.ts does not declare, or one no store, join or locator reaches";
+    readonly framework_table: "a framework table or a catalog name: application data reaches only the application's own tables";
+    readonly row_address: "a row is addressed otherwise than its table declares (its Ref, its parent Ref and key, or its key)";
+    readonly version_required: "the table has a version column, so update and remove take expectVersion";
+    readonly read_only: "a read-only request, query or table was asked to write or lock a row";
+    readonly ended: "the transaction, invocation or handle has ended or belongs to other work";
+    readonly statement_failed: "a statement of this transaction failed, so nothing it wrote commits";
+    readonly unexpected_row: "the database answered a row in another shape than its migration declares";
+    readonly statement_shape: "the compiled statement has a form the guard does not admit";
+    readonly scope_predicate: "the scope predicate is missing or is not a top-level conjunct";
+    readonly list_page: "a list limit, cursor or order outside what a page admits";
+    readonly undeclared_reach: "the site reaches data it did not declare (sql or unscoped, or their mode)";
+    readonly sql_template: "ctx.sql was not called as one tagged template whose values are interpolated whole";
+    readonly sql_statement: "ctx.sql runs one statement of an admitted kind, and none inside another";
+    readonly sql_read_only: "sql: 'read' runs queries only; declare sql: 'write' on a mutation, a job or a webhook";
+    readonly sql_name: "ctx.sql names a framework, catalog or foreign-schema object, or writes a name in U& form";
+    readonly sql_function: "ctx.sql calls a function that is not a reviewed built-in";
+    readonly sql_outside_transaction: "a job runs ctx.sql only inside ctx.transaction((tx) => …), as tx.sql";
+    readonly sql_scope: "ctx.sql.scope(…) stands alone, joined by AND, in a WHERE or JOIN … ON clause of its own invocation";
+    readonly file_scan: "a scan verdict outside the scan job's lease";
+    readonly claim_site: "claim leases rows in a transaction of its own: a job calls it on ctx.db, never inside ctx.transaction or a request";
+    readonly on_conflict: "an insert's onConflict names no column of the table, a column the insert leaves empty, or another action";
+    readonly public_reach: "a public procedure updates, removes, locks or claims no row, and an insert's conflict writes nothing";
+    readonly file_value: "a file column takes a file reference this request holds and may read (an incoming file, a put, or a read under the table's read action) of the column's kind, or null";
+    readonly file_scope: "a file is referenced from another top-level scope than the one its first reference set";
+};
+export type QueryRefusal = keyof typeof QUERY_REFUSALS;
+/** A query description or an operation tree outside what the layer allows. */
+export declare class QueryRefusedError extends Error {
+    name: string;
+    /** What a log may say; the message is for the author's own run and may quote a value. */
+    readonly reason: QueryRefusal;
+    constructor(reason: QueryRefusal, message: string);
+}
+/** A `ctx.sql` row its row schema refuses: the handler's bug. The message names the column, never its value. */
+export declare class SqlRowError extends Error {
+    name: string;
+}
+/** A table policy that cannot be enforced as written. */
+export declare class PolicyError extends Error {
+    name: string;
+}
+/** The addressed object does not exist in the capability's scope (HTTP 404). */
+export declare class NotFoundError extends Error {
+    name: string;
+}
+/** The object exists, but its version is not the one the caller expected (HTTP 409). */
+export declare class ConflictError extends Error {
+    name: string;
+}
+/** A job attempt wrote after it lost its lease (timed out, taken over or expired); nothing was written. */
+export declare class LeaseLostError extends Error {
+    name: string;
+}
+/**
+ * A statement the database refused or could not run, as the layer reports it: its SQLSTATE only. The driver's message,
+ * detail and hint can quote the whole failing row, columns the capability may not read included, so none is kept.
+ */
+export declare class DatabaseError extends Error {
+    name: string;
+    /** The five-character SQLSTATE, or `null` when the statement never reached the database (a lost connection). */
+    readonly sqlState: string | null;
+    constructor(sqlState: string | null);
+}
+/** The driver's failure as a `DatabaseError`; the driver's error object goes no further. */
+export declare function databaseError(error: unknown): DatabaseError;