@fabrika/db 0.8.2 → 0.9.0-cloudflare.2

package/types/src/errors.d.ts

@@ -0,0 +1,98 @@
+/**
+ * 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 sql_dialect: "ctx.sql runs only on Postgres; an application on SQLite (Cloudflare) reads and writes through ctx.db";
+    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;

package/types/src/file-columns.d.ts

@@ -0,0 +1,37 @@
+import { type Session } from './database';
+import type { Primitive } from './description';
+import type { TableModel } from './policy';
+/** Where a site's file references belong, and what claiming a pending one needs. */
+export interface FileBinding {
+    /** The work a reference of this site belongs to: one request, or one job attempt. */
+    readonly holder: object;
+    /** The id a pending file must carry to be claimed here: the request (or attempt) that staged it. */
+    readonly request: string;
+    /** How long a pending file may wait for its first reference. */
+    readonly graceMs: number;
+    /** Whether files of `kind` wait for a clean scan: a claimed one is `quarantined` until then. */
+    scans(kind: string): boolean;
+}
+/**
+ * Puts a file reference in each file column of `rows`, read with `action` in `session`: one statement loads every
+ * file's metadata. Without a binding (a store's own runner) the columns keep their ids.
+ */
+export declare function answerFiles<R>(model: TableModel, binding: FileBinding | undefined, session: Session, rows: R[], action: string): Promise<R[]>;
+/**
+ * A write's value for a file column: `null`, or the id of a file reference of the column's kind. A string id, a copied
+ * object or a reference of another kind is refused; whether the site holds it is checked where the write runs.
+ */
+export declare function fileValue(model: TableModel, column: string, value: unknown): string | null;
+/**
+ * The top-level scope a row of `model` lies in, from the values it is written with: `<dimension>:<value>`, or `null` for
+ * an application table, which sets no scope.
+ */
+export declare function rowScope(model: TableModel, values: ReadonlyMap<string, Primitive | null>): string | null | undefined;
+/** The top-level scope of the row whose key is `key`, read in `session`: what an update's file references are stamped with. */
+export declare function storedRowScope(model: TableModel, session: Session, key: string, keyValue: string): Promise<string | null>;
+/**
+ * The file references of a write, in `session` (its transaction), after its statement: each file is locked `for share`
+ * while its state is checked, a pending one this request staged within the grace is claimed, and the first reference
+ * from a dimensional table stamps its scope; a reference from another top-level scope is refused.
+ */
+export declare function referenceFiles(model: TableModel, binding: FileBinding | undefined, session: Session, values: ReadonlyMap<string, Primitive | null>, scope: () => Promise<string | null>): Promise<void>;

package/types/src/file-references.d.ts

@@ -0,0 +1,27 @@
+import type { StoredFileMeta, StoredFileStatus } from './stored-files';
+/** What a handler sees of a stored file: its metadata, never its object. */
+export interface FileReference {
+    readonly id: string;
+    readonly name: string | null;
+    readonly type: string;
+    readonly size: number;
+    readonly status: StoredFileStatus;
+}
+/** Whose a reference is, and what it lets that work do. */
+export interface FileHolding {
+    readonly id: string;
+    readonly kind: string;
+    /** The work that holds it: one request, or one job attempt. */
+    readonly holder: object;
+    /** Read under an action that reads the file (or received, or put): it may be written into a column, served and opened. */
+    readonly readable: boolean;
+}
+/**
+ * A reference to a file for `holder`; only `@fabrika/db` and the framework mint one. A `readable` one also lets its
+ * holder write the file into a column, serve it and open it, through any reference to the same file.
+ */
+export declare function fileReference(meta: StoredFileMeta, holder: object, readable: boolean): FileReference;
+/** What a reference holds, or `undefined` for any other value: a structural copy, a string id or a forged object. */
+export declare function fileHoldingOf(value: unknown): FileHolding | undefined;
+/** Whether `holder` received, put, or read under a read action the file `id`. */
+export declare function holdsFile(holder: object, id: string): boolean;

package/types/src/framework-tables.d.ts

@@ -0,0 +1,59 @@
+import { type Session } from './database';
+import type { DataLayerRuntime } from './store';
+/** One webhook binding: the scope value it reaches, the provider account it accepts, and its signing secret. */
+export interface WebhookBinding {
+    readonly id: string;
+    /** The webhook mount's name. */
+    readonly webhook: string;
+    readonly scope: {
+        readonly type: string;
+        readonly value: string;
+    };
+    /** The provider account: for GitHub, `installation:<id>` or `repository:<id>`, which a delivery must name. */
+    readonly account: string;
+    readonly secret: string;
+}
+export interface NewWebhookBinding extends WebhookBinding {
+    readonly createdBy: string;
+    readonly createdAt: number;
+}
+export interface WebhookTables {
+    /** Records a binding, in `using` when given: the transaction of the procedure that binds. */
+    createBinding(binding: NewWebhookBinding, using?: Session): Promise<void>;
+    /** The binding `id` of `webhook`, or `null`. */
+    binding(webhook: string, id: string): Promise<WebhookBinding | null>;
+    /**
+     * Replaces the secret of the binding when it belongs to `webhook` and `scope`, in `using` when given: a provider that
+     * issues its own signing secret shows it only after the binding's URL is registered. `false` when there was none.
+     */
+    replaceSecret(webhook: string, id: string, scope: {
+        readonly type: string;
+        readonly value: string;
+    }, secret: string, using?: Session): Promise<boolean>;
+    /** Removes the binding when it belongs to `webhook` and `scope`, in `using` when given; `false` when there was none. */
+    removeBinding(webhook: string, id: string, scope: {
+        readonly type: string;
+        readonly value: string;
+    }, using?: Session): Promise<boolean>;
+    /**
+     * Claims a delivery key for `leaseMs`: `null` when the binding completed it within the retention window, or another
+     * copy holds an unexpired claim. A claim whose lease expired is taken over. Keys of the binding older than
+     * `retainedSince` are dropped first, so the table stays bounded.
+     */
+    claimDelivery(bindingId: string, deliveryKey: string, now: number, leaseMs: number, retainedSince: number): Promise<DeliveryClaim | null>;
+    /**
+     * Completes a claimed delivery in `using`, the transaction its handler wrote in, so the work and the completion
+     * commit together; `false` when another copy took the claim over meanwhile, and that transaction must not commit.
+     * Without `using` (a handler with no transaction) it completes on its own.
+     */
+    completeDelivery(claim: DeliveryClaim, using?: Session): Promise<boolean>;
+    /** Gives a claim back after its handler failed, so the provider's redelivery runs it again at once. */
+    releaseDelivery(claim: DeliveryClaim): Promise<void>;
+}
+/** One copy's claim on a delivery: its lease end fences the completion against a copy that took the claim over. */
+export interface DeliveryClaim {
+    readonly bindingId: string;
+    readonly key: string;
+    readonly leaseUntil: number;
+}
+export declare function webhookTables(runtime: () => DataLayerRuntime): WebhookTables;

package/types/src/framework.d.ts

@@ -0,0 +1,37 @@
+import type { DataAccess } from './orm';
+import { type FrameworkTables, type Locator, type ProvisionalBinding } from './registry';
+import type { DataLayerRuntime } from './store';
+export type { Admissions } from './admissions';
+export type { LeaseFence } from './capability';
+export type { InvocationTransaction, Session } from './database';
+export { CAPABILITY_ERRORS, CapabilityError, type CapabilityErrorReason, LeaseLostError, QUERY_REFUSALS, type QueryRefusal, QueryRefusedError, } from './errors';
+export type { FileBinding } from './file-columns';
+export { type FileHolding, fileHoldingOf, type FileReference, fileReference, holdsFile } from './file-references';
+export type { DeliveryClaim, NewWebhookBinding, WebhookBinding, WebhookTables } from './framework-tables';
+export type { JobLeases, JobLeaseState, JobOutcome, OverdueClaim } from './job-leases';
+export type { DataAccess, DataHandles, DataSite } from './orm';
+export type { FrameworkTables, Locator, ProvisionalBinding } from './registry';
+export type { SqlMode, SqlSite, SqlTag, SqlValue } from './sql';
+export type { FileColumnRef, QuarantinedStoredFile, ServedFile, StagedFile, StoredFileMeta, StoredFiles, StoredFileStatus } from './stored-files';
+/** Whether `value` is an object `scoped(tables)` created, rather than a look-alike with the same fields. */
+export declare function isScopedDatabase(value: unknown): boolean;
+/**
+ * Connects the layer `scoped(tables)` created to `runtime`, once, and answers its locator, which nothing else can
+ * reach. Throws for any other value and for a layer that is already connected.
+ */
+export declare function bindScopedDatabase(value: unknown, runtime: DataLayerRuntime): Locator;
+/**
+ * Connects the layer like `bindScopedDatabase`, and answers with its locator the `release` that disconnects it again:
+ * a boot that fails releases the layer, so a later boot of the same application binds it. Throws as that does.
+ */
+export declare function bindScopedDatabaseProvisionally(value: unknown, runtime: DataLayerRuntime): ProvisionalBinding;
+/**
+ * The framework's own writes over the layer `scoped(tables)` created: the webhook tables, the job leases and the
+ * admission counters. Each operation needs the layer bound first. Throws for any other value.
+ */
+export declare function frameworkTablesOf(value: unknown): FrameworkTables;
+/**
+ * The mini-ORM of the layer `scoped(tables)` created: the invocation transactions and the `ctx.db` handles the
+ * framework builds per site. Each operation needs the layer bound first. Throws for any other value.
+ */
+export declare function dataAccessOf(value: unknown): DataAccess;

package/types/src/guard.d.ts

@@ -0,0 +1,23 @@
+import type { OperationNode } from 'kysely';
+export type RootKind = 'SelectQueryNode' | 'InsertQueryNode' | 'UpdateQueryNode' | 'DeleteQueryNode';
+export interface ForeignKeyPair {
+    readonly childColumn: string;
+    readonly parentColumn: string;
+}
+export interface GuardContext {
+    readonly root: RootKind;
+    readonly table: string;
+    /** The children a select may join, each with the composite foreign key its ON must equal. */
+    readonly joins: Readonly<Record<string, readonly ForeignKeyPair[]>>;
+    /** The scope predicate; it must be the WHERE itself or its top-level right conjunct. Absent for an insert only. */
+    readonly scope: OperationNode | undefined;
+    /**
+     * A select that locks its rows: `share` is the layer's check of a mutation's destination, `update` a mutation's
+     * `getForUpdate` of its own target, `claim` a queue claim's `for update skip locked`. No other lock is admitted.
+     */
+    readonly lock?: 'share' | 'update' | 'claim';
+    /** An insert that does nothing on a conflict of its listed columns: `on conflict (columns) do nothing`, and no other. */
+    readonly onConflict?: 'nothing';
+}
+/** Refuses any operation tree outside the allowlist. Runs on the final tree, immediately before it is compiled. */
+export declare function assertAllowedTree(root: OperationNode, context: GuardContext): void;

package/types/src/identifier.d.ts

@@ -0,0 +1,4 @@
+/** `^[a-z_][a-z0-9_]*$`, at most 63 characters (Postgres truncates longer names). */
+export declare function isPlainIdentifier(value: unknown): value is string;
+/** A plain identifier, or two joined by one dot (`note_comments.body`, the alias of a joined column). */
+export declare function isPlainAlias(value: unknown): value is string;

package/types/src/index.d.ts

@@ -0,0 +1,10 @@
+export type { AppCapability, AppGrant, CapabilityAuthority, CapabilityGrant, ContainerGrant, LeaseFence, Ref, RefGrant, RowGrant, RowRef, Within, WithinGrant, } from './capability';
+export { MAX_WITHIN_VALUES } from './capability';
+export { applicationSchema, Database, type DatabaseEngine, type Executor, type SqlDialect, type TransactionOptions, type TransactionRunner, } from './database';
+export type { AllowedOperator, ComparisonOperator, ConditionTuple, ListOperator, NoColumns, NullOperator, PatternOperator, Primitive, ScopedSelect, } from './description';
+export { CAPABILITY_ERRORS, CapabilityError, type CapabilityErrorReason, DatabaseError, LeaseLostError, PolicyError, QUERY_REFUSALS, type QueryRefusal, QueryRefusedError, } from './errors';
+export type { AnyDbIndex, ChildRows, ContainedRows, CountOptions, DataKind, DbIndex, IndexedTable, ListOptions, ListPage, NoUnscoped, OrderTerm, OwnerRow, ReadOnlyUnscoped, ReferenceRows, ReferenceTables, RowFor, Saved, ScopeTarget, TargetForm, TargetRow, Unavailable, UnownedTarget, UnscopedDeclaration, UnscopedInsert, UnscopedMode, UnscopedRows, UnscopedTables, VersionArguments, WithinRows, WithinTables, } from './orm-types';
+export { type ChildPolicy, type ChildScope, type ColumnList, defineTables, type DimensionPolicy, type DimensionScope, type InsertValues, isTables, readTables, type RecordActions, type ReferencePolicy, type ReferenceScope, type RowOf, type TableActions, type TableInsert, Tables, type TableUpdate, type UpdateValues, type VersionColumn, type VocabularyTables, } from './policy';
+export { type AggregateRow, type AggregateSpec, type ChildListScope, type DataLayer, type DataLayerRuntime, scoped, type ScopedDatabase, } from './store';
+export { type TablePolicies, tablePolicies } from './tables';
+export type { ColumnTypes, DefineVocabularyPolicies, NormalizedPolicies, TableVocabulary, TypedColumnList, VocabularyAction, VocabularyChildScope, VocabularyContainer, VocabularyContainerOf, VocabularyDimension, VocabularyDimensionScope, VocabularyPolicyMap, VocabularyTablePolicy, } from './vocabulary-tables';

package/types/src/job-leases.d.ts

@@ -0,0 +1,93 @@
+import type { LeaseFence } from './capability';
+import { type Session, type SqlDialect } from './database';
+import type { DataLayerRuntime } from './store';
+export type JobOutcome = 'succeeded' | 'failed';
+export interface JobLeaseState {
+    readonly generation: number;
+    /** The attempt holding the lease, or `null` when it is free. */
+    readonly holder: string | null;
+    readonly expiresAt: Date;
+    /** The holding attempt's deadline: no write of it commits after this. */
+    readonly attemptDeadline: Date;
+    /** When the job was first seen in this schema: the baseline of a job that never succeeded. */
+    readonly firstSeenAt: Date;
+    readonly lastStartedAt: Date | null;
+    readonly lastFinishedAt: Date | null;
+    readonly lastStatus: JobOutcome | null;
+    readonly lastSucceededAt: Date | null;
+    readonly lastDurationMs: number | null;
+    readonly lastMissedReportedAt: Date | null;
+}
+/** A job overdue by twice its period, claimed for one report. */
+export interface OverdueClaim {
+    readonly lastSucceededAt: Date | null;
+    readonly firstSeenAt: Date;
+}
+export interface JobLeases {
+    /** The database's clock. */
+    now(): Promise<Date>;
+    /** Records that the job exists (its first-seen time), once; later calls change nothing. */
+    register(job: string): Promise<void>;
+    /**
+     * Frees a lease whose holder never finished before it expired (the run crashed) and records the run as failed.
+     * `true` for the one caller that freed it.
+     */
+    reapCrashed(job: string): Promise<boolean>;
+    /**
+     * A free lease for `holder`, under a new generation, for `leaseMs`; its attempt may write for `attemptMs`. `null`
+     * while another run holds it.
+     */
+    acquire(job: string, holder: string, attemptMs: number, leaseMs: number): Promise<LeaseFence | null>;
+    /**
+     * `acquire` of a registered job that never waits for a lock: `null` at once while another run holds the lease or an
+     * attempt's transaction holds its row. A kick takes the lease only this way, on a connection requests share.
+     */
+    tryAcquire(job: string, holder: string, attemptMs: number, leaseMs: number): Promise<LeaseFence | null>;
+    /**
+     * Hands a live lease to the next attempt under a new generation, so no write of the previous attempt commits from
+     * now on. `null` when `fence` no longer holds it.
+     */
+    renew(fence: LeaseFence, holder: string, attemptMs: number, leaseMs: number): Promise<LeaseFence | null>;
+    /** Frees the lease and records the run's outcome and duration; `false` when `fence` no longer held it. */
+    finish(fence: LeaseFence, outcome: JobOutcome): Promise<boolean>;
+    /** Records that a kick arrived: the run that started before it runs the job once more. Never waits on the lease. */
+    markPending(job: string): Promise<void>;
+    /**
+     * Clears the flag `markPending` set; `true` for the one caller that cleared it. A run clears it when it starts (it
+     * covers every kick before it) and again after it succeeded, when `true` means one more run.
+     */
+    takePending(job: string): Promise<boolean>;
+    /**
+     * Claims one report of a job that has not succeeded within twice `periodMs`, at most once per period: only the
+     * caller that gets the claim reports.
+     */
+    claimOverdue(job: string, periodMs: number): Promise<OverdueClaim | null>;
+    /**
+     * Refuses every further write of the attempt `fence` names and cancels the statements it still has running; the
+     * runner calls it when the attempt ends.
+     */
+    cancelInFlight(fence: LeaseFence): Promise<void>;
+    state(job: string): Promise<JobLeaseState | null>;
+}
+/** One framework statement in each dialect's text; a session runs the text of its own. */
+export type DialectTexts = Readonly<Record<SqlDialect, string>>;
+/** SQLite's clock, as a stored timestamp: ISO text, so a comparison of two is a text comparison. */
+export declare const SQLITE_NOW = "strftime('%Y-%m-%dT%H:%M:%fZ', 'now')";
+/** SQLite's clock moved by `ms`, an SQL expression of milliseconds (negative is earlier). */
+export declare function sqliteNowPlus(ms: string): string;
+/** A stored SQLite timestamp (`SQLITE_NOW_FORMAT`) as a `Date`, or `null`; anything else is refused. */
+export declare function sqliteTimestamp(value: unknown, what: string): Date | null;
+/**
+ * The database's clock inside `session`'s transaction: a queue claim compares and moves `due` by it, so no process
+ * clock decides when a row is due.
+ */
+export declare function databaseNow(session: Session): Promise<Date>;
+/**
+ * Runs `work` in a mutation's transaction under `fence`. Before it: the attempt still holds its lease, the lease row
+ * stays locked `for share` until the commit (a takeover or a renewal waits), and every statement is bounded by the
+ * attempt's remaining time. After it, just before the commit: the attempt still holds the lease within its deadline.
+ * Otherwise the transaction rolls back with `LeaseLostError`; so does a statement the deadline or the runner cancelled.
+ * On SQLite only the two checks run: no other event reaches the Durable Object while the transaction is open.
+ */
+export declare function fencedTransaction<T>(session: Session, fence: LeaseFence, work: (transaction: Session) => Promise<T>): Promise<T>;
+export declare function jobLeases(runtime: () => DataLayerRuntime): JobLeases;

package/types/src/links.d.ts

@@ -0,0 +1,13 @@
+import type { OperationNode } from 'kysely';
+import type { RefGrant } from './capability';
+import type { Container } from './policy';
+export interface LinkValue {
+    readonly link: Container;
+    readonly value: string;
+}
+/**
+ * The column values a Ref addresses over `links`: the first link takes the Ref's id, every other link a value
+ * from its chain. A chain entry no link covers cannot be enforced, so it is refused rather than ignored.
+ */
+export declare function linkValues(table: string, links: readonly Container[], grant: RefGrant): readonly LinkValue[];
+export declare function linksPredicate(table: string, values: readonly LinkValue[]): OperationNode;

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

@@ -0,0 +1,4 @@
+import { type FrameworkMigration } from './migrations';
+/** The `strftime` format of a stored timestamp; `strftime(SQLITE_NOW_FORMAT, 'now')` is the database's clock. */
+export declare const SQLITE_NOW_FORMAT = "%Y-%m-%dT%H:%M:%fZ";
+export declare const SQLITE_FRAMEWORK_MIGRATIONS: readonly FrameworkMigration[];

package/types/src/migrations.d.ts

@@ -0,0 +1,25 @@
+/** Migration identity of the framework's tables in every application schema: bundle `fabrika`, same ledger. */
+export declare const FRAMEWORK_MIGRATION_BUNDLE = "fabrika";
+export declare const WEBHOOK_BINDINGS_TABLE = "fabrika_webhook_bindings";
+export declare const WEBHOOK_DELIVERIES_TABLE = "fabrika_webhook_deliveries";
+export declare const JOB_LEASES_TABLE = "fabrika_job_leases";
+export declare const JOB_KICKS_TABLE = "fabrika_job_kicks";
+export declare const FORM_ADMISSIONS_TABLE = "fabrika_form_admissions";
+export declare const FORM_CHALLENGES_TABLE = "fabrika_form_challenges";
+export declare const FORM_FILES_TABLE = "fabrika_form_files";
+export declare const FORM_BYTES_TABLE = "fabrika_form_bytes";
+export declare const FILES_TABLE = "fabrika_files";
+export declare const FILE_DELETIONS_TABLE = "fabrika_file_deletions";
+/** The function an application's last adoption migration calls with the name of a file collection it adopted. */
+export declare const FILES_RELEASE_FUNCTION = "fabrika_files_release";
+/**
+ * The function an adoption migration calls right before it reads a collection's table: it copies the rows an older
+ * instance wrote since 0008 ran, so each one it adopts has its `fabrika_files` row. Idempotent.
+ */
+export declare const FILES_COPY_FUNCTION = "fabrika_files_copy_legacy";
+export interface FrameworkMigration {
+    /** Ordered by name; an applied one is immutable, like an application's. */
+    readonly name: string;
+    readonly sql: string;
+}
+export declare const FRAMEWORK_MIGRATIONS: readonly FrameworkMigration[];

package/types/src/nodes.d.ts

@@ -0,0 +1,63 @@
+import { type DeleteQueryNode, type InsertQueryNode, type OperationNode, ReferenceNode, ReturningNode, type SelectQueryNode, type UpdateQueryNode, WhereNode } from 'kysely';
+import { type NameSet } from './builtins';
+import type { SqlDialect } from './database';
+import type { Condition, Primitive, SelectState } from './description';
+export declare function column(table: string, name: string): ReferenceNode;
+export declare function equals(table: string, name: string, value: Primitive): OperationNode;
+export declare function allOf(nodes: readonly OperationNode[]): OperationNode;
+/** One node, or the OR of several in a parenthesis: inside an AND, `a and b or c` would read as `(a and b) or c`. */
+export declare function anyOf(nodes: readonly OperationNode[]): OperationNode;
+export declare function inList(table: string, name: string, values: readonly string[]): OperationNode;
+/** The scope of a `Within` that is not limited to scope values. */
+export declare function everything(): OperationNode;
+/** LIKE treats `\` as its escape character by default, so the text matches literally. */
+export declare function containsPattern(text: string): string;
+/**
+ * The caller's conditions go inside an explicit parenthesis and the scope is the top-level right conjunct, so
+ * `x or true` cannot escape it. The guard checks this shape.
+ */
+export declare function scopedWhere(conditions: OperationNode | undefined, scope: OperationNode): WhereNode;
+/** `returning key as id[, version as version]`: a mutation's acknowledgement, never row data. */
+export declare function acknowledgement(table: string, key: string, version: string | undefined): ReturningNode;
+/** `after` is a keyset page's position, ANDed to the caller's conditions inside their parenthesis. */
+export declare function selectNode(state: SelectState, visible: readonly string[], scope: OperationNode, after?: OperationNode, days?: NameSet, dialect?: SqlDialect): SelectQueryNode;
+export interface AggregateColumns {
+    readonly groupBy: readonly string[];
+    readonly count: boolean;
+    readonly sum: readonly string[];
+    readonly min: readonly string[];
+    readonly max: readonly string[];
+}
+export declare function aggregateNode(table: string, columns: AggregateColumns, conditions: readonly Condition[], scope: OperationNode, days?: NameSet): SelectQueryNode;
+/** `conflict` names the columns of a unique index the insert does nothing on: `on conflict (<columns>) do nothing`. */
+export declare function insertNode(table: string, values: ReadonlyMap<string, Primitive | null>, answer: ReturningNode, conflict?: readonly string[]): InsertQueryNode;
+export declare function updateNode(table: string, values: ReadonlyMap<string, Primitive | null>, bump: string | undefined, where: WhereNode, answer: ReturningNode): UpdateQueryNode;
+export declare function deleteNode(table: string, where: WhereNode, key: string): DeleteQueryNode;
+/** `select key from table where (conditions) and scope limit 1`: does the scoped object exist? */
+export declare function existsNode(table: string, key: string, scope: OperationNode, conditions?: OperationNode): SelectQueryNode;
+/** `select key as id, version as version from table where (conditions) and scope limit 1`: an update that sets nothing. */
+export declare function acknowledgementNode(table: string, key: string, version: string | undefined, where: WhereNode): SelectQueryNode;
+/** `select columns from table where scope limit 1`: the containment columns of one object, for the framework's locator. */
+export declare function locateNode(table: string, columns: readonly string[], scope: OperationNode): SelectQueryNode;
+/**
+ * The same check, locked: `for share` keeps the row from moving until the transaction that checked it ends, `for
+ * update` also keeps every other writer and locker of it waiting.
+ */
+export declare function lockNode(table: string, key: string, scope: OperationNode, lock?: 'share' | 'update'): SelectQueryNode;
+/** The alias a keyset page's position column is selected under; a column name holds no dot, so none collides. */
+export declare function cursorAlias(index: number): string;
+/** `select …, cast(<column> as text) as "keyset.c<n>"`: each order column's exact value, which a Date would round. */
+export declare function withCursorColumns(node: SelectQueryNode, table: string, columns: readonly string[]): SelectQueryNode;
+/**
+ * A queue claim's lease: `select <columns> from table where (<conditions> and (<due> is not null and <due> <= $now and
+ * <attempts> < $max)) and scope order by <due>, <key> limit $n for update skip locked`. A row another claim holds is
+ * skipped, never waited for.
+ */
+export declare function claimNode(state: SelectState, columns: readonly string[], due: {
+    readonly due: string;
+    readonly attempts: string;
+    readonly now: Date;
+    readonly maxAttempts: number;
+}, scope: OperationNode, days: NameSet, dialect?: SqlDialect): SelectQueryNode;
+/** `select <columns> from table where scope for update`: a mutation's precondition read of its own target. */
+export declare function lockedSelectNode(table: string, columns: readonly string[], scope: OperationNode, days?: NameSet): SelectQueryNode;