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

package/types/src/store.d.ts

@@ -0,0 +1,334 @@
+import { type OperationNode, type ReturningNode } from 'kysely';
+import { type NameSet } from './builtins';
+import { type AppGrant, type CapabilityAuthority, type Ref, type RefGrant, type Within, type WithinGrant } from './capability';
+import { type Database, type Session } from './database';
+import { type NoColumns, type Primitive, type ScopedSelect, type TableShape } from './description';
+import { type FileBinding } from './file-columns';
+import type { ForeignKeyPair, GuardContext, RootKind } from './guard';
+import { type Acknowledgement, type ActionOf, type ChildTableName, type Container, type ContainerOf, type DimensionOf, type DimensionTableName, type InsertValues, type JoinableChildren, type ListDimensionOf, type MoveAcknowledgement, type Operation, type ParentOf, type PolicyRow, type TableModel, type TableModels, type Tables, type UpdateValues, type VersionArguments } from './policy';
+import type { ScopeTerms, ScopeUse } from './sql';
+import { type TablePolicies } from './tables';
+export interface DataLayerRuntime {
+    readonly database: Database;
+    readonly capabilities: CapabilityAuthority;
+    /** Whether the request running now may only read (an export's); its every statement then runs `READ ONLY`. */
+    readonly readOnly?: () => boolean;
+}
+/** Empty until the framework connects the layer at boot; every table handle of one `scoped` call shares it. */
+export interface Connection {
+    runtime: DataLayerRuntime | undefined;
+}
+export interface TableContext {
+    readonly model: TableModel;
+    readonly parent: TableModel | undefined;
+    /** The table that owns the dimension an insert or a move targets: the container's table, or a child's parent. */
+    readonly destination: TableModel | undefined;
+    readonly shape: TableShape;
+    readonly joins: Readonly<Record<string, readonly ForeignKeyPair[]>>;
+    readonly connection: Connection;
+}
+export declare function runtimeOf(connection: Connection): DataLayerRuntime;
+export interface DimensionScopeModel {
+    readonly dimension: string;
+    readonly key: string;
+    readonly container: Container | undefined;
+}
+export declare function dimensionScope(model: TableModel): DimensionScopeModel;
+export declare function childScope(context: TableContext): {
+    readonly key: string;
+    readonly column: string;
+    readonly parent: DimensionScopeModel;
+};
+/** The dimension that lists and inserts are scoped by: the container, or for a top-level table its own. */
+export declare function listDimension(scope: DimensionScopeModel): string;
+/** The actions that allow `operation` on the table, any one of them; throws when its policy declares none. */
+export declare function requiredActions(context: TableContext, operation: Operation): readonly string[];
+/** Refuses a capability whose action is not one of `operation`'s actions on the table. */
+export declare function checkAction(context: TableContext, operation: Operation, action: string): void;
+/** The object a Ref of the model's own dimension names, with every link of its chain. */
+export declare function selfLinks(model: TableModel): readonly Container[];
+/** This object, over the whole chain the Ref carries. */
+export declare function objectPredicate(context: TableContext, capability: unknown, operation: Operation): OperationNode;
+/** Rows of a dimension table within the scope values of its list dimension. */
+export declare function dimensionListPredicate(context: TableContext, capability: unknown, operation: Operation): OperationNode | undefined;
+/** Rows of a child table that belong to the parent object the Ref names, over the whole chain. */
+export declare function parentPredicate(context: TableContext, grant: RefGrant): OperationNode;
+export declare function childListPredicate(context: TableContext, capability: unknown, operation: Operation): OperationNode | undefined;
+/**
+ * The column that places a row of `model` in `dimension`: the column of that link of its containment chain, or a
+ * top-level table's own key; `undefined` when no `Within` of the dimension reaches the table.
+ */
+export declare function reachColumn(model: TableModel, dimension: string): string | undefined;
+/**
+ * Rows of a table a `Within` of any dimension of its chain lists, by the table's read action: tasks under a `Within` of
+ * `org` through their stamped `org_id`, as under one of `project` through `project_id`.
+ */
+export declare function reachPredicate(context: TableContext, capability: unknown): OperationNode | undefined;
+/**
+ * `ctx.sql.scope`'s predicate: what the handles of `capability` match in the table for `use`, as column tests. A
+ * fragment that reads (`'read'`) needs an action the handles read the table with: any action it names for a `Ref`,
+ * its read action for a `Within`, an action `ctx.db.app` lists it for with an `app` capability, and its read action
+ * for a scoped site's read of an application table. A fragment on the statement's UPDATE or DELETE target needs that
+ * operation's own action, and an `app` capability writes application tables only. A `Ref` matches its object's column
+ * and every link of the chain it carries; a `Within` matches like `ctx.db.within` (its values, each container grant on
+ * its own column, or every row for `all`); an `app` capability, and a scoped read of an application table, every row.
+ */
+export declare function scopeTerms(context: TableContext, capability: unknown, use: ScopeUse, assigned?: readonly string[]): ScopeTerms;
+/**
+ * A `Ref` of `dimension` whose action updates columns of the table: its update action, or a column's own write action.
+ * Which columns it updates follows from the action (`updatableBy`).
+ */
+export declare function updatingRef(context: TableContext, capability: unknown, dimension: string): RefGrant;
+/**
+ * What an `app` capability reaches of a dimension or child table: its rows (`list`, a scope fragment) with the read
+ * action or an action of `appRead`; its counts (`count`, `aggregate`) with those or an action of `appCount`.
+ */
+export type AppReach = 'rows' | 'counts';
+/**
+ * Every row of a dimension or child table an `app` capability reads through `ctx.db.app`: `true`, for an action that
+ * reaches `reach` (`checkRecordReach`).
+ */
+export declare function appRecordPredicate(context: TableContext, capability: unknown, reach: AppReach): OperationNode;
+/** Every row a capability of an `app` endpoint reads in `table`, by the table's read action: `true`. */
+export declare function appListPredicate(context: TableContext, capability: unknown): OperationNode;
+/**
+ * Every row of an application table, for a `Ref` or a `Within` of its read action: what `ctx.db.app` of an `on`, `in`
+ * or `over` endpoint reads, read-only, as a reference table is read. The table's read action decides who reads it.
+ */
+export declare function scopedApplicationRead(context: TableContext, capability: unknown): OperationNode;
+/** One row of an application table by its key, for an `app` capability of `operation`'s action. */
+export declare function appRowPredicate(context: TableContext, capability: unknown, key: unknown, operation: Operation): OperationNode;
+/**
+ * What a claim of a queue table leases through `capability`: an application table's every row for an `app` capability,
+ * a dimension or child table's rows a `Within` lists. Either way its action is one of the table's update actions.
+ */
+export declare function claimScope(context: TableContext, capability: unknown): {
+    readonly grant: AppGrant | WithinGrant;
+    readonly scope: OperationNode | undefined;
+};
+/**
+ * The one row a claim's `row.ref` names, for an action of `operation`: its key and every containment column it had when
+ * it was claimed, so a row moved since is not reached.
+ */
+export declare function claimedRowPredicate(context: TableContext, capability: unknown, operation: 'update' | 'delete'): OperationNode;
+/** The row of an application table `key` names. */
+export declare function appKeyPredicate(model: TableModel, key: unknown): OperationNode;
+/**
+ * The capability of an `app` endpoint whose action updates columns of an application table: its update action, or a
+ * column's own write action. Which columns it updates follows from the action (`updatableBy`).
+ */
+export declare function updatingApp(context: TableContext, capability: unknown): AppGrant;
+export declare function childObjectPredicate(context: TableContext, parent: unknown, key: unknown, operation: Operation): OperationNode;
+export declare function guard(context: TableContext, root: RootKind, scope: OperationNode | undefined): GuardContext;
+/**
+ * Where a table operation's statements run: a store's own sessions, one transaction per mutation, or the mini-ORM's
+ * invocation transaction (`orm.ts`), where every statement of a handler runs in one.
+ */
+export interface Runner {
+    /** The session a read runs in. */
+    read(): Promise<Session>;
+    /** Runs `work` in one transaction. */
+    write<T>(work: (transaction: Session) => Promise<T>): Promise<T>;
+    /** Where file references are made and checked; a store's own runner has none, and its file columns read as ids. */
+    readonly files?: FileBinding;
+}
+/**
+ * Every mutation of a store runs in its own transaction. In a job attempt that transaction is fenced by the attempt's
+ * lease (`fencedTransaction`): an attempt that lost it, or ran out of time, writes nothing.
+ */
+export declare function fencedWork<T>(runtime: DataLayerRuntime, work: (transaction: Session) => Promise<T>): Promise<T>;
+/** The action a capability holds, which its operation's checks already admitted. */
+export declare function heldAction(context: TableContext, capability: unknown): string;
+/**
+ * Reads insert or update data through its own property descriptors, so no getter runs and no inherited or
+ * non-enumerable key slips past. Every key is checked before any value is read; unknown keys are refused, not
+ * dropped, so an agent learns about them.
+ */
+export declare function readValues(values: unknown, allowed: NameSet, what: 'insert' | 'update', model: TableModel): Map<string, Primitive | null>;
+export declare function versionArgument(context: TableContext, options: readonly unknown[]): OperationNode | undefined;
+/**
+ * One row by its scope predicate, with `visible` columns (the table's read action's, unless a capability reads its own).
+ * `action` is what read it: each file column then answers a reference that reads the file only under a read action.
+ */
+export declare function selectOne<O>(context: TableContext, run: Runner, scope: OperationNode, visible?: readonly string[], action?: string): Promise<O>;
+export declare function answer(context: TableContext): ReturningNode;
+export declare function keyOf(model: TableModel): string;
+export declare function insertRow<O>(context: TableContext, run: Runner, values: ReadonlyMap<string, Primitive | null>, destination: RefGrant | undefined): Promise<O>;
+/**
+ * `insert(values, { onConflict: { columns, do } })`: on a conflict of `columns` (a unique index of the table), `nothing`
+ * writes nothing and `update` sets the columns the table's update action writes, from `updates`.
+ */
+export interface OnConflict {
+    readonly columns: readonly string[];
+    readonly mode: 'nothing' | 'update';
+    /** The values given for the table's update columns: what `update` sets on the conflicting row. */
+    readonly updates: ReadonlyMap<string, Primitive | null>;
+}
+/**
+ * The `onConflict` of an insert's options, read through own data properties; `undefined` without options. `'update'`
+ * also needs the capability's action to be one of the table's update actions.
+ */
+export declare function onConflictOf(context: TableContext, options: unknown, action: string, given: ReadonlyMap<string, Primitive | null>): OnConflict | undefined;
+/**
+ * The rows a write addresses: the scope predicate, and the caller's conditions beside it (an unscoped row's key, whose
+ * scope predicate is `true`).
+ */
+export interface Addressed {
+    readonly scope: OperationNode;
+    readonly conditions?: OperationNode;
+}
+/**
+ * Zero changed rows → one follow-up read in the same transaction → 404 when the object is gone, else 409. An update
+ * that sets no column writes nothing, not even the version: it reads the acknowledgement under the same conditions.
+ */
+export declare function updateRow<O>(context: TableContext, run: Runner, target: Addressed, changes: ReadonlyMap<string, Primitive | null>, expectedVersion: OperationNode | undefined, destination?: RefGrant): Promise<O>;
+/** Like `updateRow`: under `expectVersion`, a row that changed is 409 and a missing one 404. */
+export declare function removeRow(context: TableContext, run: Runner, target: Addressed, expectedVersion?: OperationNode): Promise<void>;
+type Columns<Row> = keyof Row & string;
+type NumericColumn<Row> = {
+    [K in Columns<Row>]: Exclude<Row[K], null> extends number | bigint | string ? K : never;
+}[Columns<Row>];
+export interface AggregateSpec<Row> {
+    readonly groupBy?: readonly Columns<Row>[];
+    readonly count?: boolean;
+    readonly sum?: readonly NumericColumn<Row>[];
+    readonly min?: readonly Columns<Row>[];
+    readonly max?: readonly Columns<Row>[];
+    readonly where?: (q: ScopedSelect<Row, Row, NoColumns>) => ScopedSelect<Row, unknown, NoColumns>;
+}
+type Listed<S, K extends 'groupBy' | 'sum' | 'min' | 'max'> = S extends {
+    readonly [P in K]: readonly (infer C extends string)[];
+} ? C : never;
+type Flat<T> = {
+    [K in keyof T]: T[K];
+};
+/**
+ * `count` is a string because Postgres returns a bigint. A sum is a string for integer and numeric columns and a
+ * number for floating-point ones; the column type alone cannot tell them apart.
+ */
+export type AggregateRow<Row, S> = Flat<Pick<Row, Listed<S, 'groupBy'> & keyof Row> & (S extends {
+    readonly count: true;
+} ? {
+    readonly count: string;
+} : NoColumns) & {
+    readonly [K in Listed<S, 'sum'> as `sum_${K}`]: string | number | null;
+} & {
+    readonly [K in Listed<S, 'min'> & keyof Row as `min_${K}`]: Row[K] | null;
+} & {
+    readonly [K in Listed<S, 'max'> & keyof Row as `max_${K}`]: Row[K] | null;
+}>;
+export declare function aggregateRows<Row, O>(context: TableContext, run: Runner, scope: OperationNode | undefined, shape: TableShape, spec: AggregateSpec<Row>): Promise<O[]>;
+/** An insert's row, stamped from its capability, the destination it locks, and what it does on a conflict. */
+export interface PreparedInsert {
+    readonly row: Map<string, Primitive | null>;
+    readonly destination: RefGrant | undefined;
+    readonly conflict: OnConflict | undefined;
+}
+/**
+ * A dimension table's insert over a capability nobody type-checked: into a container (a new UUIDv7 key, the chain from
+ * the container's `Ref`), or for a top-level table the object the `Ref` names.
+ */
+export declare function prepareDimensionInsert(context: TableContext, target: unknown, values: unknown, options?: unknown): PreparedInsert;
+/** An application table's insert, for an `app` capability of its insert action: a new key, no containment. */
+export declare function prepareApplicationInsert(context: TableContext, capability: unknown, values: unknown, options?: unknown): PreparedInsert;
+/** A child table's insert under the parent its `Ref` names, whose chain is checked against the database. */
+export declare function prepareChildInsert(context: TableContext, parent: unknown, values: unknown, options?: unknown): PreparedInsert;
+/** A prepared insert, with its conflict handling when the caller named one. */
+export declare function insertPrepared(context: TableContext, run: Runner, prepared: PreparedInsert): Promise<Readonly<Record<string, unknown>>>;
+/** `DimensionTable.insert` over a capability nobody type-checked; the table probe of `@fabrika/db/testing` calls it too. */
+export declare function insertIntoDimension<O>(context: TableContext, run: Runner, target: unknown, values: unknown): Promise<O>;
+/** An application table's insert, for an `app` capability of its insert action. */
+export declare function insertIntoApplication<O>(context: TableContext, run: Runner, capability: unknown, values: unknown): Promise<O>;
+/** `ChildTable.insert` over a capability nobody type-checked. */
+export declare function insertIntoChild<O>(context: TableContext, run: Runner, parent: unknown, values: unknown): Promise<O>;
+type ReadAction<P, T> = ActionOf<P, T, 'read'>;
+type Row<DB, P, T> = PolicyRow<DB, P, T>;
+type Joinable<DB, P, T> = JoinableChildren<DB, P, T>;
+type ParentDimension<P, T> = DimensionOf<P, ParentOf<P, T>>;
+/** The table handle of a dimension table: every entry point takes a `Ref` or a `Within`. */
+export declare class DimensionTable<DB, P, T extends string> {
+    #private;
+    constructor(context: TableContext);
+    select<S>(within: Within<ListDimensionOf<P, T>, ReadAction<P, T>>, build: (q: ScopedSelect<Row<DB, P, T>, Row<DB, P, T>, Joinable<DB, P, T>>) => ScopedSelect<Row<DB, P, T>, S, Joinable<DB, P, T>>): Promise<S[]>;
+    get(ref: Ref<DimensionOf<P, T>, ReadAction<P, T>>): Promise<Row<DB, P, T>>;
+    /**
+     * Into a container (the key is a new UUIDv7, the chain comes from the container's Ref and is checked against
+     * the database), or for a top-level table the object the `Ref` names. Answers an acknowledgement, not the row.
+     */
+    insert(target: Ref<ListDimensionOf<P, T>, ActionOf<P, T, 'insert'>>, values: InsertValues<DB, P, T>): Promise<Acknowledgement<P, T>>;
+    update(ref: Ref<DimensionOf<P, T>, ActionOf<P, T, 'update'>>, values: UpdateValues<DB, P, T>, ...options: VersionArguments<P, T>): Promise<Acknowledgement<P, T>>;
+    remove(ref: Ref<DimensionOf<P, T>, ActionOf<P, T, 'delete'>>): Promise<void>;
+    /**
+     * Moves the object to another container: the delete action at the source, the insert action at the target,
+     * whose chain is checked against the database. Every chain column changes; children that copy them follow
+     * through `ON UPDATE CASCADE` on their composite foreign key. Answers the acknowledgement and the new chain.
+     */
+    move(ref: Ref<DimensionOf<P, T>, ActionOf<P, T, 'delete'>>, to: Ref<ContainerOf<P, T>, ActionOf<P, T, 'insert'>>): Promise<MoveAcknowledgement<P, T>>;
+    aggregate<const S extends AggregateSpec<Row<DB, P, T>>>(within: Within<ListDimensionOf<P, T>, ReadAction<P, T>>, spec: S): Promise<AggregateRow<Row<DB, P, T>, S>[]>;
+}
+/** The scope a child list is reached through: one parent object, or the parent's list dimension. */
+export type ChildListScope<P, T> = Ref<ParentDimension<P, T>, ReadAction<P, T>> | Within<ListDimensionOf<P, ParentOf<P, T>>, ReadAction<P, T>>;
+/** The table handle of a child table: one row is addressed by its parent's `Ref` and its own key. */
+export declare class ChildTable<DB, P, T extends string> {
+    #private;
+    constructor(context: TableContext);
+    select<S>(scope: ChildListScope<P, T>, build: (q: ScopedSelect<Row<DB, P, T>, Row<DB, P, T>, NoColumns>) => ScopedSelect<Row<DB, P, T>, S, NoColumns>): Promise<S[]>;
+    get(parent: Ref<ParentDimension<P, T>, ReadAction<P, T>>, key: string): Promise<Row<DB, P, T>>;
+    /** Under the parent the Ref names, whose chain is checked against the database. Answers an acknowledgement. */
+    insert(parent: Ref<ParentDimension<P, T>, ActionOf<P, T, 'insert'>>, values: InsertValues<DB, P, T>): Promise<Acknowledgement<P, T>>;
+    update(parent: Ref<ParentDimension<P, T>, ActionOf<P, T, 'update'>>, key: string, values: UpdateValues<DB, P, T>, ...options: VersionArguments<P, T>): Promise<Acknowledgement<P, T>>;
+    remove(parent: Ref<ParentDimension<P, T>, ActionOf<P, T, 'delete'>>, key: string): Promise<void>;
+    aggregate<const S extends AggregateSpec<Row<DB, P, T>>>(scope: ChildListScope<P, T>, spec: S): Promise<AggregateRow<Row<DB, P, T>, S>[]>;
+}
+/**
+ * One table's operations without the store types, for `@fabrika/db/testing` only: the generated isolation tests address
+ * a table by name. Every runtime check of a store applies; a child row is addressed by its parent's capability and
+ * `key`, a dimension row by its capability alone.
+ */
+export interface TableProbe {
+    readonly mode: 'dimension' | 'child' | 'app';
+    get(capability: unknown, key?: string): Promise<Readonly<Record<string, unknown>>>;
+    select(capability: unknown): Promise<readonly Readonly<Record<string, unknown>>[]>;
+    /** `aggregate(capability, { count: true })`; zero rows when the capability reaches none. */
+    count(capability: unknown): Promise<string>;
+    /** `aggregate(capability, { groupBy: columns, count: true })`: the values of `columns` in each group, and its count. */
+    group(capability: unknown, columns: readonly string[]): Promise<readonly Readonly<Record<string, unknown>>[]>;
+    insert(capability: unknown, values: unknown): Promise<unknown>;
+    update(capability: unknown, key: string | undefined, values: unknown, expectVersion?: number): Promise<unknown>;
+    remove(capability: unknown, key?: string): Promise<void>;
+}
+/** What a select or an aggregate of a capability that reads `visible` may name: those columns, and no join. */
+export declare function actionShape(model: TableModel, visible: readonly string[]): TableShape;
+/** What `serve(contract, { database })` takes: the policies as data. `boot` binds only an object `scoped` created. */
+export interface DataLayer {
+    /** Every table's policy as data, for the contract compiler. */
+    readonly tables: TablePolicies;
+}
+declare const layerTypes: unique symbol;
+/**
+ * What `scoped` returns: the policies, typed by the tables they came from. It has no connection, no locator and no
+ * handle of its own; `boot` binds it through `@fabrika/db/framework`, which only `@fabrika/app` imports, and a
+ * handler reaches data through `ctx.db`. The brand is type-only: no value has the property.
+ */
+export interface ScopedDatabase<DB, P> extends DataLayer {
+    readonly [layerTypes]?: {
+        readonly db: DB;
+        readonly policies: P;
+    };
+}
+/**
+ * Binds the table policies to the data layer. An application calls it once, in `src/app.ts`, and passes the result to
+ * `serve(contract, { database })`. Nothing reaches the database until `boot` binds that one object; another `scoped`
+ * result never gets a connection.
+ */
+export declare function scoped<DB, P>(tables: Tables<DB, P>): ScopedDatabase<DB, P>;
+/**
+ * A store over one dimension table of the layer: the framework's own tests and kits build them, never an application,
+ * whose handlers reach data through `ctx.db`. Exported from `@fabrika/db/testing` only.
+ */
+export declare function defineStore<DB, P, const T extends DimensionTableName<P>, S>(database: ScopedDatabase<DB, P>, table: T, build: (t: DimensionTable<DB, P, T>) => S): S;
+/** A store over one child table of the layer, as `defineStore`; exported from `@fabrika/db/testing` only. */
+export declare function defineChildStore<DB, P, const T extends ChildTableName<P>, S>(database: ScopedDatabase<DB, P>, table: T, build: (t: ChildTable<DB, P, T>) => S): S;
+/** The table that owns `dimension`: the one dimension table scoped by it (`defineTables` refuses a second). */
+export declare function ownerOf(models: TableModels, dimension: string): TableModel | undefined;
+export {};

package/types/src/stored-files.d.ts

@@ -0,0 +1,98 @@
+import { type Session } from './database';
+import type { DataLayerRuntime } from './store';
+/** A stored file's states: written, waiting for its first reference, for its scan, served, or refused by the scan. */
+export declare const STORED_FILE_STATUSES: readonly ["pending", "quarantined", "live", "rejected"];
+export type StoredFileStatus = (typeof STORED_FILE_STATUSES)[number];
+/** What a file reference carries: the file's metadata, never its bytes or its object. */
+export interface StoredFileMeta {
+    readonly id: string;
+    readonly kind: string;
+    readonly name: string | null;
+    readonly type: string;
+    readonly size: number;
+    readonly status: StoredFileStatus;
+}
+/** A file about to be written: its row comes first, then the object under `objectKey`. */
+export interface StagedFile {
+    readonly id: string;
+    readonly kind: string;
+    readonly objectKey: string;
+    readonly contentType: string;
+    readonly name: string | null;
+    /** The request (or job attempt) that writes it: only it may claim the file while it is pending. */
+    readonly request: string;
+}
+/** A stored file as a byte consumer reads it: only a live one is served, by its scanned version when its kind scans. */
+export interface ServedFile extends StoredFileMeta {
+    readonly objectKey: string;
+    readonly objectVersion: string | null;
+}
+/** What the scan pass needs of a quarantined file. */
+export interface QuarantinedStoredFile {
+    readonly id: string;
+    readonly objectKey: string;
+    readonly size: number;
+    readonly sha256: string;
+    readonly contentType: string;
+    readonly scanAttempts: number;
+    readonly dueSince: Date;
+}
+/** A file column the sweep looks a file up in: an application table's column, both validated identifiers. */
+export interface FileColumnRef {
+    readonly table: string;
+    readonly column: string;
+}
+/** What a reference write learns of a file it locked. */
+export interface LockedFile {
+    readonly kind: string;
+    readonly status: StoredFileStatus;
+    readonly request: string | null;
+    readonly scope: string | null;
+    /** Whether it is still within the pending grace, counted from its creation. */
+    readonly fresh: boolean;
+}
+export interface StoredFiles {
+    /** Commits the `pending` row of a file whose object is written next, on a connection of its own: the cleanup intent. */
+    stage(file: StagedFile): Promise<void>;
+    /** Records the written object's size and digest on its pending row, on a connection of its own. */
+    written(id: string, written: {
+        readonly size: number;
+        readonly sha256: string;
+    }): Promise<void>;
+    /**
+     * Deletes a pending row this request wrote and nobody claimed, and records its object for deletion, in one
+     * statement: the object key, or `null` when the file was claimed (or is gone).
+     */
+    abandon(id: string, request: string): Promise<string | null>;
+    /** A file as a byte consumer reads it, in `using` or on its own; `null` when the sweep deleted it. */
+    find(id: string, using?: Session): Promise<ServedFile | null>;
+    /** Quarantines a live file of a scanning kind again when it has no scanned version, so the scan decides once more. */
+    requarantine(id: string, version: string | null): Promise<void>;
+    /** Each file's metadata, by id, in `using`: what the data layer answers in a file column. */
+    metadata(using: Session, ids: readonly string[]): Promise<ReadonlyMap<string, StoredFileMeta>>;
+    quarantined(kinds: readonly string[], limit: number, now: Date): Promise<readonly QuarantinedStoredFile[]>;
+    promote(id: string, sha256: string, version: string): Promise<boolean>;
+    deferScan(id: string, attempts: number, after: Date): Promise<boolean>;
+    reject(id: string): Promise<boolean>;
+    /** Objects whose rows a sweep deleted and whose own deletion it did not finish. */
+    unfinishedDeletions(limit: number): Promise<readonly string[]>;
+    forgetDeletion(objectKey: string): Promise<void>;
+    /** Clears the legacy marker of every migrated file that one of `columns` references: it is an ordinary file now. */
+    adoptReferenced(columns: readonly FileColumnRef[]): Promise<number>;
+    /** At most `limit` files past the grace that no column of `columns` references (pending ones included), oldest first. */
+    unreferenced(columns: readonly FileColumnRef[], limit: number, graceMs: number): Promise<readonly string[]>;
+    /**
+     * Deletes the row of an unreferenced file and records its object for deletion, in one transaction; `null` when it
+     * survived: a reference exists (the foreign key refuses the delete), or it is legacy or within the grace.
+     */
+    remove(id: string, graceMs: number): Promise<string | null>;
+}
+/** Locks file `id` `for share` in `session`, the transaction that writes a reference to it; `null` when it is gone. */
+export declare function lockStoredFile(session: Session, id: string, graceMs: number): Promise<LockedFile | null>;
+/** Ends the pending state of a file the reference write locked: `quarantined` for a scanning kind, else `live`. */
+export declare function claimStoredFile(session: Session, id: string, ended: 'quarantined' | 'live'): Promise<void>;
+/** Sets the scope of a file's first dimensional reference; `false` when it already holds another. */
+export declare function stampStoredFile(session: Session, id: string, scope: string): Promise<boolean>;
+/** Each file's metadata, by id, in `using`: one statement for every file column of a read. */
+export declare function storedFilesMetadata(using: Session, ids: readonly string[]): Promise<ReadonlyMap<string, StoredFileMeta>>;
+export declare function storedFiles(runtime: () => DataLayerRuntime): StoredFiles;

package/types/src/tables.d.ts

@@ -0,0 +1,11 @@
+import type { TablePolicyArtifact } from '@fabrika/auth-core';
+import { type Tables } from './policy';
+export { PolicyError } from './errors';
+export type { FileReference } from './file-references';
+export type { AnyDbIndex, ApplicationRows, ApplicationTables, AppRecordRows, ChildRows, ClaimedRow, ClaimedRowHandle, ClaimOptions, ContainedRows, CountOptions, DataKind, DbIndex, FragmentTable, IndexedTable, InsertConflict, InsertMethod, ListOptions, ListPage, NoUnscoped, OrderTerm, OwnerRow, PublicApplicationRows, PublicApplicationTables, PublicInsertMethod, ReadOnlyUnscoped, ReferenceRows, ReferenceTables, RowFor, RowOf, Saved, ScopedApplicationRows, ScopedApplicationTables, ScopeTarget, TableNameOf, TargetForm, TargetRow, Unavailable, UnownedTarget, UnscopedDeclaration, UnscopedInsert, UnscopedMode, UnscopedRows, UnscopedTables, VersionArguments, WithinRows, WithinTables, } from './orm-types';
+export { type ApplicationPolicy, type ApplicationScope, type ChildPolicy, type ChildScope, type ColumnList, defineTables, type DimensionPolicy, type DimensionScope, type FilePolicies, isTables, type QueuePolicy, readTables, type RecordActions, type ReferencePolicy, type ReferenceScope, type TableAction, type TableActions, type TableInsert, Tables, type TableUpdate, type VersionColumn, type VocabularyTables, } from './policy';
+export type { ColumnTypes, DefineVocabularyPolicies, NormalizedPolicies, TableVocabulary, TypedColumnList, VocabularyAction, VocabularyChildScope, VocabularyContainer, VocabularyContainerOf, VocabularyDimension, VocabularyDimensionScope, VocabularyPolicyMap, VocabularyTablePolicy, } from './vocabulary-tables';
+/** Every table's policy in the form the contract artifact carries, by table name. */
+export type TablePolicies = Readonly<Record<string, TablePolicyArtifact>>;
+/** The artifact form of every policy `defineTables` (or `readTables`) checked. */
+export declare function tablePolicies<DB, P>(tables: Tables<DB, P>): TablePolicies;

package/types/src/temporal.d.ts

@@ -0,0 +1,12 @@
+import { type NameSet } from './builtins';
+/**
+ * A day as the layer answers it: the database's `YYYY-MM-DD` text, or a decoded `Date` that is exactly a UTC midnight
+ * in 0001–9999 — the only `Date` `Bun.SQL` decodes correctly from a `date`, whatever the process's time zone.
+ */
+export declare function dayText(value: string | Date, where: string): string;
+/** Replaces each value under a key of `days` in every row with its `YYYY-MM-DD` text, in place. */
+export declare function answerDays<R>(table: string, days: NameSet, rows: R[]): R[];
+/** A day a write binds: `YYYY-MM-DD` text of a real day, as the layer answers one. */
+export declare function dayInput(value: string, where: string): string;
+/** A timestamp a write binds as text: strict ISO 8601 with `Z` or an offset, every field in range. */
+export declare function timestampInput(value: string, where: string): string;

package/types/src/testing.d.ts

@@ -0,0 +1,126 @@
+import { Database } from './database';
+import type { Primitive } from './description';
+import { type Tables } from './policy';
+import type { TableProbe } from './store';
+export { ChildTable, defineChildStore, defineStore, DimensionTable, type TableProbe } from './store';
+export declare const TEST_POSTGRES_URL = "FABRIKA_TEST_POSTGRES_URL";
+/** Set to `1` by the platform build: a missing test database is then a failure, not a skip. */
+export declare const TEST_POSTGRES_REQUIRED = "FABRIKA_TEST_POSTGRES_REQUIRED";
+export interface TestDatabaseOptions {
+    /** The application's `db/migrations/` directory. */
+    readonly migrations: string | URL;
+    /** The test file, for the skip message. */
+    readonly label: string;
+    /**
+     * How long to wait for free connection slots, in ms, before the file fails saying so; `DEFAULT_CONNECTION_WAIT_MS` by
+     * default. Once one file of a process gave up, every later one fails at once.
+     */
+    readonly connectionWaitMs?: number;
+}
+/** A value a test row holds in a column; `null` for a nullable column the fixture left empty. */
+export type SampleValue = Primitive | null;
+/** One seeded row and where it lies. */
+export interface WorldRow {
+    /** The row's key: the dimension value of a dimension table's row, a child's own key. */
+    readonly key: string;
+    /** A child row's parent key; `null` for a dimension table. */
+    readonly parent: string | null;
+    /** The value of the grant dimension the row lies in (`IsolationWorlds.dimension`). */
+    readonly scope: string;
+    /**
+     * Every dimension value the row lies in: a dimension table's own first, then each container, innermost first. A
+     * share link's chain is this list.
+     */
+    readonly chain: readonly {
+        readonly type: string;
+        readonly value: string;
+    }[];
+    /** The row's values of the policy's update columns, as seeded. */
+    readonly updates: Readonly<Record<string, SampleValue>>;
+    /**
+     * The distinct value written into every text column the fixture filled itself, in this row and in its containers.
+     * Each occurs in no other fixture, so one found in an answer to another scope is a leaked row.
+     */
+    readonly markers: readonly string[];
+}
+/** One seeded row of an application table, which lies in no dimension. */
+export interface ApplicationRow {
+    readonly key: string;
+    /** The row's values of the policy's update columns, as seeded. */
+    readonly updates: Readonly<Record<string, SampleValue>>;
+    /** The distinct value written into every text column the fixture filled itself. */
+    readonly markers: readonly string[];
+}
+/** A row seeded under another: its key, and the distinct value written into every text column the fixture filled. */
+export interface SeededRow {
+    readonly key: string;
+    readonly markers: readonly string[];
+}
+/**
+ * What the isolation fixture cannot seed for a schema: a CHECK its values fail, a required foreign key to a scoped table
+ * outside the containment chain. It is a limit of the generator, named with the constraint or the column, never a
+ * failure of the handler or the policy a case is about.
+ */
+export declare class SeedLimitError extends Error {
+    readonly name = "SeedLimitError";
+}
+/** One row of a table in each of two containment chains that share no value. */
+export interface IsolationWorlds {
+    /**
+     * The dimension a caller's grants are scoped by: a dimension table's container, or its own dimension when it has
+     * none; a child table's parent's.
+     */
+    readonly dimension: string;
+    readonly own: WorldRow;
+    readonly other: WorldRow;
+}
+export interface TestDatabase {
+    /** The connection `boot` binds the data layer to: the runtime role, on the migrated schema. */
+    readonly database: Database;
+    readonly schema: string;
+    /**
+     * Seeds one row of `table` in each of two fresh chains, with every container row a table owns. `values` (column →
+     * value) are written into both rows of `table`: the state an endpoint's precondition needs. A text column keeps its
+     * marker, so a seed of one, or of a column that places the row, throws.
+     */
+    seedWorlds<DB, P>(tables: Tables<DB, P>, table: string, values?: Readonly<Record<string, SampleValue>>): Promise<IsolationWorlds>;
+    /** Seeds one row of the application table `table`: its key, version and creator stamped, every other column sampled. */
+    seedRow<DB, P>(tables: Tables<DB, P>, table: string): Promise<ApplicationRow>;
+    /**
+     * Seeds one row of `table`, a child or dimension table that lies in the object of `under` (a row `seedWorlds`
+     * seeded), placed in that row's chain: the row a fixture names by id, such as a note's comment. Answers its key and
+     * the markers it holds.
+     */
+    seedUnder<DB, P>(tables: Tables<DB, P>, table: string, under: WorldRow): Promise<SeededRow>;
+    /** Values for the policy's insert columns of `table` that its schema accepts: every required one, sampled; a file column a seeded file. */
+    sampleInsert<DB, P>(tables: Tables<DB, P>, table: string): Promise<Readonly<Record<string, SampleValue>>>;
+    /**
+     * The object key of every file the fixture seeded into a file column, oldest first. Each stands for an empty object,
+     * which a test's object store holds when a handler serves or opens the file.
+     */
+    seededObjects(): readonly string[];
+    /** Closes the connections and drops the schema and its roles. */
+    close(): Promise<void>;
+}
+/**
+ * The object version a seeded file was scanned at: whoever stocks its empty object (`seededObjects`) stores it under
+ * this version, so a file of a scanning kind is served as a live one is, by its scanned version.
+ */
+export declare const SEEDED_OBJECT_VERSION = "\"seeded\"";
+/**
+ * A fresh schema with the framework's and the application's migrations applied by the real runner (`@fabrika/platform-node`) as its
+ * migration role, connected and seeded as its runtime role, or `null` after the standard skip message when
+ * `FABRIKA_TEST_POSTGRES_URL` is unset. That URL is the provisioning credential, which must be able to create roles.
+ * With `FABRIKA_TEST_POSTGRES_REQUIRED=1` a missing URL throws instead. The URL is a credential: no message names it.
+ */
+export declare function testDatabase(options: TestDatabaseOptions): Promise<TestDatabase | null>;
+/**
+ * The connections a test database holds once open: the provisioning connection, the seeder and the runtime role's.
+ * Migrating and reading the catalog each borrow one more for a moment, and so does the drop once the others ended.
+ */
+export declare const TEST_DATABASE_CONNECTIONS: number;
+/**
+ * The untyped handle over one table of the data layer `scoped(tables)` created; it reaches the database once `boot`
+ * has bound that layer. Every runtime check of a store applies: kind, dimension, action and the request's authority.
+ */
+export declare function tableProbe(layer: unknown, table: string): TableProbe;