ultimabase 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# ultimabase
+
+## 0.1.1
+
+### Patch Changes
+
+- The published starter starts: `ultimabase dev` runs `dist/serve.js`, and `@ultimabase/realtime`, which `@ultimabase/graphql` and `@ultimabase/rest` import, is a required peer the starter lists.
+
+## 0.1.0
+
+### Minor Changes
+
+- 0e885c4: The first release: the kernel, its adapters, transports and plugins, the testing helpers and the starter.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# ultimabase
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The UltimaBase kernel: models, queries, access rules, hooks, functions and transactions, the plugin contract, and the in-memory database. Everything else is a plugin.
+
+Documentation: [Introduction](https://ultimabase.dev/docs).

package/dist/access.d.ts

@@ -0,0 +1,62 @@
+import { PublicError } from './errors.ts';
+import type { Filter } from './adapter.ts';
+import type { Logger } from './app-options.ts';
+import { Relations } from './relations.ts';
+import type { Caller } from './rules.ts';
+import type { ModelInfo } from './schema.ts';
+import type { Models, Verb } from './query-where.ts';
+type Operation = 'read' | 'create' | 'update' | 'delete';
+type Values = {
+    readonly [field: string]: unknown;
+};
+/**
+ * Each field with a read rule: `private` when only Master reads it, which a
+ * transport leaves out, `rule` when it may be hidden (D-44, D-107).
+ */
+export declare function readRules(model: ModelInfo): {
+    readonly [field: string]: 'private' | 'rule';
+};
+/** The record a rule sees: each stored `one` key as `{ id }` or `null` (D-77). */
+export declare function recordOf(model: ModelInfo, row: Values): Values;
+/** A refusal, logged with the caller's id before it is thrown (D-88). */
+export declare function refused(details: {
+    readonly [key: string]: string;
+}, message: string, caller: Caller, logger: Logger): PublicError;
+/** A write's stored `record`, its `value`, and the relation it comes from. */
+export type Write = {
+    readonly record?: Values;
+    readonly data?: unknown;
+    readonly via?: string;
+};
+/** The access rules of one query, for a caller other than Master. */
+export declare class Access {
+    private readonly filters;
+    readonly models: Models;
+    readonly caller: Caller;
+    private readonly logger;
+    /** The query's relation filters (D-151). */
+    readonly relations: Relations;
+    constructor(models: Models, caller: Caller, logger: Logger);
+    /** The model's read filter (D-10); `undefined` when every row passes. */
+    readable(name: string): Filter | undefined;
+    private filterOf;
+    /** Whether a field read rule may hide the field, from the whole row (D-44). */
+    ruled(model: ModelInfo, field: string): boolean;
+    /** Refuses a filter or a sort on a field with a read rule (D-44, D-86). */
+    check(model: ModelInfo, field: string, path: string, verb: Verb): void;
+    /** The fields of a row its field read rules hide (D-44). */
+    hidden(model: ModelInfo, row: Values, fields: Iterable<string>): ReadonlySet<string>;
+    /**
+     * Fails with `ACCESS_DENIED` unless the model's rule, then each written
+     * field's rule, allows the write (D-10, D-44, D-67).
+     */
+    allow(model: ModelInfo, operation: Exclude<Operation, 'read'>, write: Write): void;
+}
+/** The query's access rules; `undefined` for Master, which skips them. */
+export declare function accessFor(models: Models, caller: Caller, logger: Logger): Access | undefined;
+/** `filter` and the model's read filter, both. */
+export declare function and(filter: Filter, readable: Filter | undefined): Filter;
+export declare function and(filter: Filter | undefined, readable: Filter): Filter;
+export declare function and(filter: Filter | undefined, readable: Filter | undefined): Filter | undefined;
+export {};
+//# sourceMappingURL=access.d.ts.map

package/dist/access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access.d.ts","sourceRoot":"","sources":["../src/access.ts"],"names":[],"mappings":"AAGA,OAAO,EAAgB,WAAW,EAAE,MAAM,aAAa,CAAA;AACvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,SAAS,EAAW,MAAM,gBAAgB,CAAA;AACnD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAExC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAC5C,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAIpD,KAAK,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAA;AACxD,KAAK,MAAM,GAAG;IAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAA;AAsCnD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG;IAC5C,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAAA;CAC5C,CAuBA;AAED,kFAAkF;AAClF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAc9D;AAqDD,yEAAyE;AACzE,wBAAgB,OAAO,CACtB,OAAO,EAAE;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,EAC3C,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACZ,WAAW,CAIb;AAaD,8EAA8E;AAC9E,MAAM,MAAM,KAAK,GAAG;IACnB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AAED,qEAAqE;AACrE,qBAAa,MAAM;IAClB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwC;IAChE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAE7B,YAAY,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAKzD;IAED,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAKzC;IAED,OAAO,CAAC,QAAQ;IAyBhB,+EAA+E;IAC/E,KAAK,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAE9C;IAED,2EAA2E;IAC3E,KAAK,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,CAMrE;IAED,4DAA4D;IAC5D,MAAM,CACL,KAAK,EAAE,SAAS,EAChB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,GACtB,WAAW,CAAC,MAAM,CAAC,CAWrB;IAED;;;OAGG;IACH,KAAK,CACJ,KAAK,EAAE,SAAS,EAChB,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,EACrC,KAAK,EAAE,KAAK,GACV,IAAI,CAgCN;CACD;AAED,0EAA0E;AAC1E,wBAAgB,SAAS,CACxB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACZ,MAAM,GAAG,SAAS,CAEpB;AAED,kDAAkD;AAClD,wBAAgB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAAA;AACzE,wBAAgB,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;AACzE,wBAAgB,GAAG,CAClB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC1B,MAAM,GAAG,SAAS,CAAA"}

package/dist/access.js

@@ -0,0 +1,258 @@
+// Access rules at run time (D-10, D-44, D-86): each model's read filter, the
+// fields a caller may not filter on or see, and the rules a write runs.
+// Master skips them all (D-48): its queries get no `Access`.
+import { InvalidQuery, PublicError } from './errors.js';
+import { Relations, trusted } from './relations.js';
+import { allow, filterOf, isMaster, isReadFilter, readFilter } from './rules.js';
+import { entries, isObject, modelOf, normalizeWhere } from './query-where.js';
+import { madeId } from './uuid.js';
+/** The `access` a `.with` received, on a model or a field. */
+function accessOf(rules) {
+    return rules !== undefined && isObject(rules) ? rules['access'] : undefined;
+}
+/** The rule of `operation`: a function covers all, `write` the writes. */
+function ruleOf(access, operation) {
+    if (!isObject(access))
+        return access;
+    const rule = access[operation];
+    return rule === undefined && operation !== 'read' ? access['write'] : rule;
+}
+function fieldRule(model, field, operation) {
+    return ruleOf(accessOf(model.definition.fields.get(field)?.rules), operation);
+}
+function run(rule, facts) {
+    if (typeof rule !== 'function') {
+        throw new TypeError('An access rule is a function.');
+    }
+    const result = Reflect.apply(rule, undefined, [facts]);
+    return result;
+}
+function decide(rule, facts) {
+    const result = run(rule, facts);
+    if (typeof result !== 'boolean') {
+        throw new TypeError('A write rule or a field rule returns a boolean.');
+    }
+    return result;
+}
+/**
+ * Each field with a read rule: `private` when only Master reads it, which a
+ * transport leaves out, `rule` when it may be hidden (D-44, D-107).
+ */
+export function readRules(model) {
+    const rules = {};
+    for (const field of model.fields.keys()) {
+        const rule = fieldRule(model, field, 'read');
+        if (rule !== undefined) {
+            rules[field] = rule === allow.private ? 'private' : 'rule';
+        }
+    }
+    // A virtual is hidden by its own rule and by its needs' (D-151).
+    for (const { name, needs } of model.virtuals.values()) {
+        const own = fieldRule(model, name, 'read');
+        const found = [
+            ...needs.map((need) => rules[need]),
+            own === undefined
+                ? undefined
+                : own === allow.private
+                    ? 'private'
+                    : 'rule',
+        ];
+        if (found.includes('private'))
+            rules[name] = 'private';
+        else if (found.includes('rule'))
+            rules[name] = 'rule';
+    }
+    return rules;
+}
+/** The record a rule sees: each stored `one` key as `{ id }` or `null` (D-77). */
+export function recordOf(model, row) {
+    const record = {
+        id: row['id'],
+        createdAt: row['createdAt'],
+        updatedAt: row['updatedAt'],
+    };
+    for (const field of model.fields.values()) {
+        const value = row[field.name];
+        if (field.kind === 'scalar')
+            record[field.name] = value ?? null;
+        else if (field.kind === 'one' && field.stored) {
+            record[field.name] = isObject(value) ? { id: value['id'] } : null;
+        }
+    }
+    return record;
+}
+function ids(value, key) {
+    const list = isObject(value) ? value[key] : undefined;
+    return Array.isArray(list)
+        ? list.map((item) => ({ id: isObject(item) ? item['id'] : null }))
+        : [];
+}
+/** The value a field rule sees (D-44, D-86): a relation's ids, not its data. */
+function fieldValue(model, name, given) {
+    const kind = model.fields.get(name)?.kind;
+    const create = isObject(given) ? given['create'] : undefined;
+    if (kind === 'many') {
+        return {
+            connect: ids(given, 'connect'),
+            disconnect: ids(given, 'disconnect'),
+            delete: ids(given, 'delete'),
+            // The rows it creates, by the ids the kernel gives them (D-128).
+            create: Array.isArray(create)
+                ? create.filter(isObject).map((item) => ({ id: madeId(item) }))
+                : [],
+        };
+    }
+    if (kind !== 'one')
+        return given;
+    if (isObject(create))
+        return { id: madeId(create) };
+    const connect = isObject(given) ? given['connect'] : undefined;
+    return isObject(connect) ? { id: connect['id'] } : null;
+}
+/**
+ * Whether a relation value only updates linked rows: it changes no link, so
+ * the field rule does not judge it (D-138).
+ */
+function updatesOnly(model, name, given) {
+    const kind = model.fields.get(name)?.kind;
+    if (!isObject(given) || given['update'] === undefined)
+        return false;
+    if (kind === 'one')
+        return true;
+    if (kind !== 'many')
+        return false;
+    const links = ['connect', 'disconnect', 'create', 'delete'];
+    return links.every((key) => ids(given, key).length === 0);
+}
+const closed = { OR: [] };
+/** A refusal, logged with the caller's id before it is thrown (D-88). */
+export function refused(details, message, caller, logger) {
+    const callerId = caller.kind === 'user' ? caller.user.id : null;
+    logger.warn({ ...details, callerId }, message);
+    return new PublicError('ACCESS_DENIED', message, { details });
+}
+function denied(refusal, caller, logger) {
+    const { model, operation, field, via } = refusal;
+    const details = {
+        model,
+        operation,
+        ...(field === undefined ? {} : { field }),
+        ...(via === undefined ? {} : { via }),
+    };
+    return refused(details, `${model} ${operation} refused.`, caller, logger);
+}
+/** The access rules of one query, for a caller other than Master. */
+export class Access {
+    filters = new Map();
+    models;
+    caller;
+    logger;
+    /** The query's relation filters (D-151). */
+    relations;
+    constructor(models, caller, logger) {
+        this.models = models;
+        this.caller = caller;
+        this.logger = logger;
+        this.relations = new Relations(models, caller);
+    }
+    /** The model's read filter (D-10); `undefined` when every row passes. */
+    readable(name) {
+        if (this.filters.has(name))
+            return this.filters.get(name);
+        const filter = this.filterOf(modelOf(this.models, name));
+        this.filters.set(name, filter);
+        return filter;
+    }
+    filterOf(model) {
+        const rule = ruleOf(accessOf(model.definition.rules), 'read');
+        // Closed by default (D-04).
+        if (rule === undefined)
+            return closed;
+        const result = run(rule, {
+            caller: this.caller,
+            operation: 'read',
+            where: readFilter,
+        });
+        if (result === true)
+            return undefined;
+        if (result === false)
+            return closed;
+        if (!isReadFilter(result)) {
+            throw new TypeError('A read rule returns a boolean or a read filter.');
+        }
+        // The rule's own filter is trusted: no guard, no other rule (D-86).
+        const path = `${model.name}.access.read`;
+        return normalizeWhere(this.models, model, filterOf(result), path, trusted(this.relations));
+    }
+    /** Whether a field read rule may hide the field, from the whole row (D-44). */
+    ruled(model, field) {
+        return fieldRule(model, field, 'read') !== undefined;
+    }
+    /** Refuses a filter or a sort on a field with a read rule (D-44, D-86). */
+    check(model, field, path, verb) {
+        if (fieldRule(model, field, 'read') === undefined)
+            return;
+        throw new InvalidQuery(path, `${path}: ${model.name}.${field} has a read rule; only Master ${verb} on it.`);
+    }
+    /** The fields of a row its field read rules hide (D-44). */
+    hidden(model, row, fields) {
+        const hidden = new Set();
+        let record;
+        for (const field of fields) {
+            const rule = fieldRule(model, field, 'read');
+            if (rule === undefined)
+                continue;
+            record ??= recordOf(model, row);
+            const facts = { caller: this.caller, operation: 'read', record };
+            if (!decide(rule, facts))
+                hidden.add(field);
+        }
+        return hidden;
+    }
+    /**
+     * Fails with `ACCESS_DENIED` unless the model's rule, then each written
+     * field's rule, allows the write (D-10, D-44, D-67).
+     */
+    allow(model, operation, write) {
+        const value = write.data === undefined
+            ? undefined
+            : Object.fromEntries(entries(write.data, 'data'));
+        const facts = {
+            caller: this.caller,
+            operation,
+            ...(write.record === undefined
+                ? {}
+                : { record: recordOf(model, write.record) }),
+            ...(value === undefined ? {} : { value }),
+        };
+        const refusal = {
+            model: model.name,
+            operation,
+            ...(write.via === undefined ? {} : { via: write.via }),
+        };
+        const rule = ruleOf(accessOf(model.definition.rules), operation);
+        if (rule === undefined || !decide(rule, facts))
+            throw denied(refusal, this.caller, this.logger);
+        for (const [field, given] of Object.entries(value ?? {})) {
+            const check = fieldRule(model, field, operation);
+            if (check === undefined || updatesOnly(model, field, given))
+                continue;
+            const allowed = decide(check, {
+                ...facts,
+                value: fieldValue(model, field, given),
+            });
+            if (!allowed) {
+                throw denied({ ...refusal, field }, this.caller, this.logger);
+            }
+        }
+    }
+}
+/** The query's access rules; `undefined` for Master, which skips them. */
+export function accessFor(models, caller, logger) {
+    return isMaster(caller) ? undefined : new Access(models, caller, logger);
+}
+export function and(filter, readable) {
+    if (readable === undefined)
+        return filter;
+    return filter === undefined ? readable : { AND: [readable, filter] };
+}

package/dist/adapter-errors.d.ts

@@ -0,0 +1,43 @@
+/** A unique index refused a write; the kernel reports `UNIQUE_VIOLATION`. */
+export declare class UniqueViolation extends Error {
+    readonly model: string;
+    readonly fields: readonly string[];
+    constructor(model: string, fields: readonly string[]);
+}
+/**
+ * A foreign key refused a write that raced another (D-99): `model.field`
+ * links a `target` deleted meanwhile, or, `restricted`, the write deleted a
+ * `target` that `model.field` still links.
+ */
+export declare class RelationViolation extends Error {
+    readonly model: string;
+    readonly field: string;
+    readonly target: string;
+    readonly restricted: boolean;
+    constructor(model: string, field: string, target: string, restricted: boolean);
+}
+/**
+ * A computed number fell outside its field's range, or was not finite on a
+ * float: nothing was written (D-132).
+ */
+export declare class OutOfRange extends Error {
+    readonly model: string;
+    readonly field: string;
+    constructor(model: string, field: string);
+}
+/** A check of a write found another count: nothing was written (D-99). */
+export declare class CheckFailed extends Error {
+    readonly index: number;
+    constructor(index: number);
+}
+/** The database refused a sync's statement or a deploy's file (D-105). */
+export declare class MigrationFailed extends Error {
+    /** The statement's SQL, or the file's name. */
+    readonly at: string;
+    /** What the database said. */
+    readonly reason: string;
+    /** Whether it waited past its limit for a table another session held. */
+    readonly locked: boolean;
+    constructor(at: string, reason: string, locked?: boolean);
+}
+//# sourceMappingURL=adapter-errors.d.ts.map

package/dist/adapter-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-errors.d.ts","sourceRoot":"","sources":["../src/adapter-errors.ts"],"names":[],"mappings":"AAEA,6EAA6E;AAC7E,qBAAa,eAAgB,SAAQ,KAAK;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;IAElC,YAAY,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,EAKnD;CACD;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAE5B,YACC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,OAAO,EAYnB;CACD;AAED;;;GAGG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IAEtB,YAAY,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAKvC;CACD;AAED,0EAA0E;AAC1E,qBAAa,WAAY,SAAQ,KAAK;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IAEtB,YAAY,KAAK,EAAE,MAAM,EAIxB;CACD;AAED,0EAA0E;AAC1E,qBAAa,eAAgB,SAAQ,KAAK;IACzC,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,8BAA8B;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IAExB,YAAY,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,UAAQ,EAMrD;CACD"}

package/dist/adapter-errors.js

@@ -0,0 +1,72 @@
+// The errors an adapter throws, which the kernel reports to the client (D-73).
+/** A unique index refused a write; the kernel reports `UNIQUE_VIOLATION`. */
+export class UniqueViolation extends Error {
+    model;
+    fields;
+    constructor(model, fields) {
+        super(`Unique constraint failed on ${model} (${fields.join(', ')}).`);
+        this.name = 'UniqueViolation';
+        this.model = model;
+        this.fields = fields;
+    }
+}
+/**
+ * A foreign key refused a write that raced another (D-99): `model.field`
+ * links a `target` deleted meanwhile, or, `restricted`, the write deleted a
+ * `target` that `model.field` still links.
+ */
+export class RelationViolation extends Error {
+    model;
+    field;
+    target;
+    restricted;
+    constructor(model, field, target, restricted) {
+        super(restricted
+            ? `${model}.${field} still links a deleted ${target}.`
+            : `${model}.${field} links a missing ${target}.`);
+        this.name = 'RelationViolation';
+        this.model = model;
+        this.field = field;
+        this.target = target;
+        this.restricted = restricted;
+    }
+}
+/**
+ * A computed number fell outside its field's range, or was not finite on a
+ * float: nothing was written (D-132).
+ */
+export class OutOfRange extends Error {
+    model;
+    field;
+    constructor(model, field) {
+        super(`The result for ${model}.${field} is out of range.`);
+        this.name = 'OutOfRange';
+        this.model = model;
+        this.field = field;
+    }
+}
+/** A check of a write found another count: nothing was written (D-99). */
+export class CheckFailed extends Error {
+    index;
+    constructor(index) {
+        super(`Check ${String(index)} of the write failed.`);
+        this.name = 'CheckFailed';
+        this.index = index;
+    }
+}
+/** The database refused a sync's statement or a deploy's file (D-105). */
+export class MigrationFailed extends Error {
+    /** The statement's SQL, or the file's name. */
+    at;
+    /** What the database said. */
+    reason;
+    /** Whether it waited past its limit for a table another session held. */
+    locked;
+    constructor(at, reason, locked = false) {
+        super(`The database refused ${at}: ${reason}`);
+        this.name = 'MigrationFailed';
+        this.at = at;
+        this.reason = reason;
+        this.locked = locked;
+    }
+}

package/dist/adapter-json.d.ts

@@ -0,0 +1,20 @@
+/** The operators a `Condition` on a json value adds. */
+export type JsonCondition = {
+    /**
+     * A json value's operators test the value at this path into it (D-149):
+     * a key, or an array's index as PostgreSQL's `#>` reads it. A path the
+     * value lacks is unknown, as `null` is. `equals` and `not` then take a
+     * JSON value, `null` a JSON `null`; `lt` to `gte` a number or a string,
+     * matching a value of that JSON type; the `string` operators a string
+     * value, `mode` applying to them; the `array` ones an array.
+     */
+    readonly path?: readonly string[];
+    readonly stringContains?: string;
+    readonly stringStartsWith?: string;
+    readonly stringEndsWith?: string;
+    /** Each element is held, as PostgreSQL's `@>` holds it (D-149). */
+    readonly arrayContains?: readonly unknown[];
+    readonly arrayStartsWith?: unknown;
+    readonly arrayEndsWith?: unknown;
+};
+//# sourceMappingURL=adapter-json.d.ts.map

package/dist/adapter-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-json.d.ts","sourceRoot":"","sources":["../src/adapter-json.ts"],"names":[],"mappings":"AAEA,wDAAwD;AACxD,MAAM,MAAM,aAAa,GAAG;IAC3B;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;IAClC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC,mEAAmE;IACnE,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,OAAO,EAAE,CAAA;IAC3C,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAA;IAClC,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAA;CAChC,CAAA"}

package/dist/adapter-json.js

@@ -0,0 +1,2 @@
+// A json value's path condition in the adapter contract (D-73, D-149).
+export {};

package/dist/adapter-migrations.d.ts

@@ -0,0 +1,90 @@
+import type { Schema } from './adapter.ts';
+/** One statement of a plan, as it runs and as a migration file shows it. */
+export type Statement = {
+    readonly sql: string;
+    /** The model it changes, and how, for the log: `Locker`, `added owner`. */
+    readonly model: string;
+    readonly does: string;
+    /** What it deletes, when it loses data: `removing "Locker.label" deletes data`. */
+    readonly loses?: string;
+    /**
+     * When the database refuses it, for a change rows can break:
+     * `limiting "Locker.kind" to wood, glass fails when a row holds another value`.
+     */
+    readonly tries?: string;
+    /**
+     * A removal that may be a rename: the field or model that may be the same
+     * (`Locker.title`), the name it keeps its data under with `dbName`
+     * (`label`), and the SQL that renames instead.
+     */
+    readonly rename?: {
+        readonly to: string;
+        readonly dbName: string;
+        readonly sql: string;
+    };
+};
+/** A migration file: its file name, its SQL and its SHA-256. */
+export type Migration = {
+    readonly name: string;
+    readonly sql: string;
+    readonly checksum: string;
+    /** The models' hash its header names, which a production start reads. */
+    readonly schema?: string;
+    /** False when its second line is `-- ultimabase no transaction`. */
+    readonly transaction: boolean;
+};
+/** The snapshot a database's tables match, and who wrote it (D-105). */
+export type Stored = {
+    /** None when a deploy stopped before it stored one. */
+    readonly snapshot: unknown;
+    readonly by: 'sync' | 'deploy';
+    /** In name order. */
+    readonly applied: readonly {
+        readonly name: string;
+        readonly checksum: string;
+        readonly schema?: string;
+    }[];
+};
+/**
+ * Development sync's statements, or the migration files to deploy, each in
+ * its transaction; then `to` is stored.
+ */
+export type Run = {
+    readonly kind: 'sync';
+    /** The snapshot the statements start from, checked under the lock. */
+    readonly from: unknown;
+    readonly statements: readonly Statement[];
+    readonly to: unknown;
+} | {
+    readonly kind: 'deploy';
+    readonly files: readonly Migration[];
+    readonly to: unknown;
+};
+/**
+ * How a database follows the models (D-105). A snapshot is JSON in the
+ * adapter's own format, which it validates when it reads one back.
+ */
+export interface Migrations {
+    /** What this database makes of the models. */
+    snapshot(schema: Schema): unknown;
+    /**
+     * The statements from a snapshot, or an empty database, to the models'
+     * snapshot; a required field added takes its `default` in the rows.
+     */
+    plan(from: unknown, schema: Schema): readonly Statement[];
+    /** The database's snapshot, if it has one; the adapter is started. */
+    stored(): Promise<Stored | undefined>;
+    /**
+     * Applies `run` under a lock that one database holds at a time; a
+     * statement or file the database refuses throws `MigrationFailed`.
+     */
+    apply(run: Run): Promise<void>;
+    /**
+     * Drops every table, for `ultimabase reset`; returns the models' tables.
+     * A table another session holds throws a locked `MigrationFailed`.
+     */
+    reset(): Promise<readonly string[]>;
+    /** The database's host when it is not on this machine: `reset` then needs `--force`. */
+    readonly remote?: string;
+}
+//# sourceMappingURL=adapter-migrations.d.ts.map

package/dist/adapter-migrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-migrations.d.ts","sourceRoot":"","sources":["../src/adapter-migrations.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAE1C,4EAA4E;AAC5E,MAAM,MAAM,SAAS,GAAG;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,mFAAmF;IACnF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE;QACjB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;QACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;QACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;KACpB,CAAA;CACD,CAAA;AAED,gEAAgE;AAChE,MAAM,MAAM,SAAS,GAAG;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,yEAAyE;IACzE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,oEAAoE;IACpE,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;CAC7B,CAAA;AAED,wEAAwE;AACxE,MAAM,MAAM,MAAM,GAAG;IACpB,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,QAAQ,CAAA;IAC9B,qBAAqB;IACrB,QAAQ,CAAC,OAAO,EAAE,SAAS;QAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;QACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;QACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KACxB,EAAE,CAAA;CACH,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,GAAG,GACZ;IACA,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,CAAA;IACzC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAA;CACnB,GACD;IACA,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAA;IACpC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAA;CACnB,CAAA;AAEJ;;;GAGG;AACH,MAAM,WAAW,UAAU;IAC1B,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAA;IACjC;;;OAGG;IACH,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,SAAS,EAAE,CAAA;IACzD,sEAAsE;IACtE,MAAM,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;IACrC;;;OAGG;IACH,KAAK,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC9B;;;OAGG;IACH,KAAK,IAAI,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAA;IACnC,wFAAwF;IACxF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACxB"}

package/dist/adapter-migrations.js

@@ -0,0 +1 @@
+export {};