@orkestrel/database 0.0.1 → 0.0.2

package/dist/src/core/Table.d.ts

@@ -1,69 +0,0 @@
-import type { ContractInterface, FieldPath } from '@orkestrel/contract';
-import type { EmitterErrorHandler, EmitterHooks, EmitterInterface } from '@orkestrel/emitter';
-import type { AggregateFunction, Criteria, CursorInterface, DriverInterface, Key, KeyFunction, QueryInterface, ReadOptions, Row, TableEventMap, TableInterface } from './types.js';
-/**
- * A table — typed keyed CRUD plus fluent query and cursor access over a driver.
- *
- * @remarks
- * The table's contract is the load-bearing piece: writes go through `parse`
- * (coercing inputs and rejecting rows that don't fit with a `VALIDATION` throw),
- * reads come back through the contract guard (narrowing a stored {@link Row} to
- * the table's type — no assertion, AGENTS §1), and `contract` is exposed for
- * introspection and seeding. The driver only stores and scans; all querying is
- * the shared core engine in `helpers.ts`.
- *
- * @remarks
- * - **Observable (§13).** The owned {@link emitter} ({@link TableEventMap}) carries the
- *   per-row mutation moments — `write` (set / add / update), `remove`, `clear` — for
- *   fire-and-forget observers (cache invalidation, sync, an audit log), ALONGSIDE the
- *   database-level lifecycle. Events carry the affected KEY only (no value payload, to
- *   keep fan-out lean); reads / queries / counts are not emitted. Every event is emitted
- *   directly, strictly AFTER the driver write / delete / clear completes; the emitter
- *   isolates a listener throw and routes it to its `error` handler (the `error` option),
- *   so a buggy observer can never corrupt a write or perturb a transaction.
- */
-export declare class Table<T = Row> implements TableInterface<T> {
-    #private;
-    constructor(ready: () => Promise<void>, driver: DriverInterface, name: string, key: string, contract: ContractInterface<T>, generate?: KeyFunction, on?: EmitterHooks<TableEventMap>, error?: EmitterErrorHandler);
-    get emitter(): EmitterInterface<TableEventMap>;
-    get name(): string;
-    get primary(): string;
-    get contract(): ContractInterface<T>;
-    get(key: Key): Promise<T | undefined>;
-    get(keys: readonly Key[]): Promise<readonly (T | undefined)[]>;
-    resolve(key: Key): Promise<T>;
-    resolve(keys: readonly Key[]): Promise<readonly T[]>;
-    has(key: Key): Promise<boolean>;
-    has(keys: readonly Key[]): Promise<readonly boolean[]>;
-    keys(): Promise<readonly Key[]>;
-    records(criteria?: Criteria, options?: ReadOptions): Promise<readonly T[]>;
-    count(criteria?: Criteria, options?: ReadOptions): Promise<number>;
-    aggregate(operation: AggregateFunction, column: FieldPath, criteria?: Criteria, options?: ReadOptions): Promise<number | undefined>;
-    /**
-     * Stream the table's rows matching `criteria`, applying offset/limit paging.
-     *
-     * @remarks
-     * `criteria.limit` counts rows that pass BOTH the criteria conditions AND the
-     * table's contract guard (a stored row that fails the guard is skipped and
-     * does not count toward `limit`) — this can differ from {@link records}'s
-     * `limit`, which a driver's optional native `records` hook applies BEFORE
-     * the contract guard runs, when storage holds rows that no longer conform
-     * to the table's contract.
-     *
-     * @param criteria - Optional conditions plus offset/limit paging
-     * @param options - `{ signal }` to abort mid-stream
-     * @returns An async generator of matching, guard-conforming rows
-     */
-    scan(criteria?: Criteria, options?: ReadOptions): AsyncGenerator<T>;
-    set(row: T, options?: ReadOptions): Promise<Key>;
-    set(rows: readonly T[], options?: ReadOptions): Promise<readonly Key[]>;
-    add(row: T, options?: ReadOptions): Promise<Key>;
-    add(rows: readonly T[], options?: ReadOptions): Promise<readonly Key[]>;
-    update(key: Key, changes: Partial<T>, options?: ReadOptions): Promise<boolean>;
-    update(keys: readonly Key[], changes: Partial<T>, options?: ReadOptions): Promise<readonly boolean[]>;
-    remove(key: Key, options?: ReadOptions): Promise<boolean>;
-    remove(keys: readonly Key[], options?: ReadOptions): Promise<readonly boolean[]>;
-    clear(): Promise<void>;
-    query(): QueryInterface<T>;
-    cursor(): Promise<CursorInterface<T>>;
-}

package/dist/src/core/constants.d.ts

@@ -1,22 +0,0 @@
-/**
- * The primary-key column assumed when {@link TableKeys} does not name one.
- *
- * @remarks
- * `id` is the convention IndexedDB (`keyPath: 'id'`) and SQL (`id` / rowid) both
- * lean on, so a table that omits `key` keys its rows by `id`.
- */
-export declare const DEFAULT_PRIMARY = "id";
-/**
- * The longest `LIKE` / `GLOB` pattern the wildcard matcher accepts before rejecting it.
- *
- * @remarks
- * A ReDoS bound (AGENTS §6.5): the SA1–SA4 migration lets a model supply `list`
- * criteria over the wire, so `likeMatch` / `globMatch` run attacker-controlled
- * patterns. The matcher is the LINEAR greedy two-pointer wildcard match — never a
- * backtracking regex (`.*`-segments-separated-by-literals against a long input is the
- * catastrophic shape JS cannot bound without atomic groups), so it is O(value ×
- * pattern). Capping the pattern length bounds that pattern factor, leaving a match
- * linear in the value length whatever the pattern. A longer pattern throws a
- * `VALIDATION` {@link DatabaseError}; the cap is generous for any legitimate search.
- */
-export declare const MAX_PATTERN_LENGTH = 1024;

package/dist/src/core/drivers/MemoryDriver.d.ts

@@ -1,94 +0,0 @@
-import type { Criteria, DriverInterface, DriverMeta, Key, Migration, Row, TableSchema } from '../types.js';
-/**
- * The reference {@link DriverInterface} — nested maps, no I/O.
- *
- * @remarks
- * The in-between made concrete: it runs identically in a browser or on a server,
- * so it is the storage behind tests, ephemeral caches, and any code that wants
- * the database API without a persistent backend. Rows are copied in and out so a
- * caller can never mutate stored state by reference (AGENTS §11), and `snapshot`
- * clones every table to give transactions an exact rollback point. `scan` and
- * `keys` yield in key order — sorted by the core {@link compareValues} total
- * order, the same contract the SQLite (`ORDER BY`) and IndexedDB (key-ordered
- * reads) backends honor, so an unordered read agrees across every backend rather
- * than leaking Map insertion order. A persistent backend (IndexedDB, SQLite)
- * implements the same nine methods over real storage.
- */
-export declare class MemoryDriver implements DriverInterface {
-    #private;
-    open(schema: readonly TableSchema[]): Promise<void>;
-    close(): Promise<void>;
-    read(table: string, key: Key): Promise<Row | undefined>;
-    write(table: string, key: Key, row: Row): Promise<void>;
-    delete(table: string, key: Key): Promise<boolean>;
-    keys(table: string): Promise<readonly Key[]>;
-    scan(table: string): AsyncIterable<Row>;
-    /**
-     * Natively filtered lazy iteration — the {@link DriverInterface.stream} hook.
-     *
-     * @remarks
-     * Iterates the table's keys in the same key order `scan` and `keys` yield
-     * (sorted by {@link compareValues}), testing each row against
-     * `criteria.conditions` (via {@link matchesCriteria}) before counting it
-     * toward `offset` / `limit`. Both are applied lazily as matches are found —
-     * `offset` matches are skipped without being yielded, and iteration stops the
-     * instant `limit` yields have been produced, so a large table is never fully
-     * walked for a small page. `criteria.order` is IGNORED (the same contract as
-     * `TableInterface.scan` and `QueryInterface.stream`): streaming yields key
-     * order, sorted output is `records()`'s job. Rows yield copy-out (AGENTS
-     * §11), and an unknown table mirrors `scan`'s empty-yield behavior.
-     *
-     * @param table - The table to stream
-     * @param criteria - The filter / offset / limit to apply lazily
-     *
-     * @example
-     * ```ts
-     * for await (const row of driver.stream('users', { conditions, limit: 10 })) {
-     *   // one matched row at a time, in key order
-     * }
-     * ```
-     */
-    stream(table: string, criteria: Criteria): AsyncIterable<Row>;
-    clear(table: string): Promise<void>;
-    /**
-     * Capture the current state and return a thunk that rolls back to it.
-     *
-     * @remarks
-     * `tables` omitted clones and restores the WHOLE store, byte-identical to the
-     * prior whole-store behavior. `tables` provided clones ONLY the named tables,
-     * and the returned thunk restores ONLY those — every other table keeps
-     * whatever it was mutated to after the snapshot was taken.
-     *
-     * @param tables - The table names to scope the snapshot to; omitted captures every table
-     * @returns A thunk that restores the captured tables
-     */
-    snapshot(tables?: readonly string[]): Promise<() => Promise<void>>;
-    /**
-     * Return the persisted {@link DriverMeta}, or `undefined` when the store has
-     * never been stamped.
-     *
-     * @remarks
-     * In-process only — the metadata lives in this instance's memory, exactly
-     * like the rest of this driver's storage. A driver-conformance-valid
-     * implementation of the optional `meta` / `stamp` pair.
-     *
-     * @returns The last-stamped {@link DriverMeta}, or `undefined`
-     */
-    meta(): Promise<DriverMeta | undefined>;
-    /**
-     * Persist `meta` verbatim for a later `meta()` to return.
-     *
-     * @param meta - The {@link DriverMeta} to persist
-     */
-    stamp(meta: DriverMeta): Promise<void>;
-    /**
-     * Apply a {@link Migration} plan's steps against the in-memory store.
-     *
-     * @remarks
-     * A multi-step plan applies its steps sequentially and is NOT atomic — a
-     * failure partway through a plan leaves the earlier steps already applied.
-     *
-     * @param plan - The migration plan to apply
-     */
-    migrate(plan: Migration): Promise<void>;
-}

package/dist/src/core/errors.d.ts

@@ -1,38 +0,0 @@
-import type { DatabaseErrorCode } from './types.js';
-/**
- * An error thrown by the database layer.
- *
- * @remarks
- * Carries a {@link DatabaseErrorCode} and an optional `context` bag naming the
- * offending table / key. Thrown for: operating on a closed database (`CLOSED`), a
- * `resolve` miss (`NOT_FOUND`), an `add` onto an existing key (`CONFLICT`), a
- * row that fails its table's contract (`VALIDATION`), a cancelled operation whose
- * {@link ReadOptions.signal} aborted (`ABORTED`, carrying `signal.reason` in
- * `context`), an inapplicable {@link Migration} plan (`MIGRATION`), a
- * driver that violates a {@link DriverInterface} invariant, thrown by the
- * `conformDriver` helper (`CONFORMANCE`), and an unexpected infrastructure
- * fault surfaced by a driver seam — e.g. a filesystem failure while
- * persisting (`DRIVER`) — as opposed to expected domain conditions, which
- * keep their specific codes.
- */
-export declare class DatabaseError extends Error {
-    readonly code: DatabaseErrorCode;
-    readonly context?: Readonly<Record<string, unknown>>;
-    constructor(code: DatabaseErrorCode, message: string, context?: Readonly<Record<string, unknown>>);
-}
-/**
- * Narrow an unknown caught value to a {@link DatabaseError}.
- *
- * @param value - The value to test (typically a `catch` binding)
- * @returns `true` when `value` is a {@link DatabaseError}
- *
- * @example
- * ```ts
- * try {
- * 	await users.add(row)
- * } catch (error) {
- * 	if (isDatabaseError(error) && error.code === 'CONFLICT') await users.set(row)
- * }
- * ```
- */
-export declare function isDatabaseError(value: unknown): value is DatabaseError;

package/dist/src/core/factories.d.ts

@@ -1,43 +0,0 @@
-import type { DatabaseInterface, DatabaseOptions, DriverInterface, TablesShape } from './types.js';
-/**
- * Create a database over a driver and a declared `tables` schema.
- *
- * @remarks
- * `tables` maps each name to its columns (a `column → shape` map); the database
- * wraps each in an `objectShape`, so you never write `objectShape` at the table
- * level. The `const` type parameter captures the literal names and columns, so
- * `db.table('users')` is checked against the schema and typed by `Infer` of its
- * columns — no annotations. Name a non-`id` primary-key column per table via the
- * optional `keys` map.
- *
- * @param options - The driver, the `tables` column map, optional `keys`, and an
- *                   optional `name`
- * @returns A typed {@link DatabaseInterface}
- *
- * @example
- * ```ts
- * import { createDatabase, createMemoryDriver } from '@orkestrel/database'
- * import { integerShape, stringShape } from '@orkestrel/contract'
- *
- * const db = createDatabase({
- * 	driver: createMemoryDriver(),
- * 	tables: {
- * 		users: { id: stringShape(), age: integerShape() },
- * 		posts: { slug: stringShape(), title: stringShape() },
- * 	},
- * 	keys: { posts: 'slug' },
- * })
- * await db.table('users').set({ id: 'u1', age: 36 }) // typed; coerced + validated
- * ```
- */
-export declare function createDatabase<const T extends TablesShape>(options: DatabaseOptions<T>): DatabaseInterface<T>;
-/**
- * Create the in-memory reference {@link DriverInterface}.
- *
- * @remarks
- * Backed by nested maps with no I/O — the same driver runs in a browser or on a
- * server, making it the natural choice for tests and ephemeral storage.
- *
- * @returns A fresh in-memory driver
- */
-export declare function createMemoryDriver(): DriverInterface;

package/dist/src/core/helpers.d.ts

@@ -1,383 +0,0 @@
-import type { ContractShape, FieldPath } from '@orkestrel/contract';
-import type { AggregateFunction, ColumnType, ConformanceFinding, Condition, Criteria, DriverInterface, Key, Migration, MigrationStep, Order, Row, TableSchema } from './types.js';
-/**
- * A total ordering over arbitrary values — the comparator behind sorting and the
- * range operators.
- *
- * @remarks
- * Values of different types order by a fixed type rank (`undefined` < `null` <
- * boolean < number < string < other); same-typed values compare naturally.
- * `NaN` sorts after every other number and equal to itself, so the comparator
- * is total and never returns `NaN`.
- *
- * @param left - The left value
- * @param right - The right value
- * @returns `-1`, `0`, or `1`
- */
-export declare function compareValues(left: unknown, right: unknown): number;
-/**
- * Structural equality by SameValueZero leaves — the comparator behind conformance
- * checks and any test/fixture that needs "same data", not "same reference".
- *
- * @remarks
- * Primitives compare by SameValueZero (`NaN` equals itself; `+0` equals `-0`).
- * Arrays compare by index (same length, every element `deepEqual`). Plain
- * records (via `isRecord`) compare by their OWN enumerable keys: same key
- * COUNT and, for every key in `left`, `right` has that key (`Object.hasOwn`)
- * with a `deepEqual` value — so a key present with value `undefined` is NOT
- * equal to that key being absent (both differ in `Object.keys` membership).
- * Anything else (functions, class instances, mismatched shapes) falls through
- * to `false`. There is no cycle detection — a cyclic input recurses forever;
- * callers pass acyclic data (rows, plans, config).
- *
- * @param left - The left value
- * @param right - The right value
- * @returns Whether `left` and `right` are structurally equal
- *
- * @example
- * ```ts
- * deepEqual(Number.NaN, Number.NaN) // true
- * deepEqual({ a: [1, { b: 2 }] }, { a: [1, { b: 2 }] }) // true
- * deepEqual({ a: undefined }, {}) // false — present-undefined ≠ absent
- * ```
- */
-export declare function deepEqual(left: unknown, right: unknown): boolean;
-/**
- * Match a value against a wildcard pattern in LINEAR time — the shared, ReDoS-SAFE
- * engine behind {@link likeMatch} and {@link globMatch}.
- *
- * @remarks
- * A backtracking RegExp (`a%b%c` → `^a.*b.*c$`) is CATASTROPHIC on a hostile pattern:
- * `.*` segments separated by literals, matched against a long non-matching input, blow
- * up super-linearly — and JS has no atomic groups / possessive quantifiers to bound it
- * (AGENTS §6.5, now that the authed server runs model-supplied `list` criteria over the
- * wire). So this builds NO regex. It runs the classic GREEDY TWO-POINTER wildcard match:
- * the `any` wildcard records its position and, on a later mismatch, backtracks ONLY to
- * that last `any` (letting it absorb one more char) — so the work is O(value × pattern),
- * never the exponential / polynomial backtracking a regex would do. The pattern length
- * is capped at {@link MAX_PATTERN_LENGTH} (a `VALIDATION` {@link DatabaseError} over it),
- * bounding the pattern factor so a match stays linear in the value length whatever the
- * pattern.
- *
- * The `any` wildcard matches any run (including empty); `single` matches exactly one
- * char; every other pattern char matches itself LITERALLY (a pattern `.` / `(` / `\` is
- * a literal — the regex-metacharacter hazard is gone with the regex). `any` is tested
- * BEFORE a literal match, so a value that literally contains the wildcard char never
- * shadows the wildcard. Case folding is applied to BOTH sides when `fold` is set.
- *
- * @param value - The value to test
- * @param pattern - The wildcard pattern
- * @param any - The any-run wildcard char (`%` for `LIKE`, `*` for `GLOB`)
- * @param single - The single-char wildcard char (`_` for `LIKE`, `?` for `GLOB`)
- * @param fold - Whether to match case-INSENSITIVELY (`LIKE` folds; `GLOB` does not)
- * @returns Whether `value` matches `pattern`
- * @throws A `VALIDATION` {@link DatabaseError} when `pattern` exceeds {@link MAX_PATTERN_LENGTH}
- */
-export declare function wildcardMatch(value: string, pattern: string, any: string, single: string, fold: boolean): boolean;
-export declare function likeMatch(value: string, pattern: string): boolean;
-export declare function globMatch(value: string, pattern: string): boolean;
-/**
- * Evaluate one {@link Condition} against a row — the per-operator predicate.
- *
- * @remarks
- * Reads the condition's column — a `FieldPath`, resolved with `resolveField` (a
- * string is one column; an array descends a nested value) — and applies the
- * operator. Range operators use {@link compareValues}; `like` / `glob` / `starts`
- * / `ends` match only strings; `any` / `none` test membership by value equality.
- * Total — a type mismatch is simply a non-match.
- *
- * @param row - The row to test
- * @param condition - The condition to apply
- * @returns Whether the row satisfies the condition
- */
-export declare function matchesCondition(row: Row, condition: Condition): boolean;
-/**
- * Fold a row through a list of conditions, joining each by its connector.
- *
- * @remarks
- * Evaluated left-to-right: the first condition seeds the result, and each later
- * condition combines with `&&` (`and`) or `||` (`or`). An empty list matches
- * every row. There is no operator precedence — conditions combine in the order
- * the query builder recorded them.
- *
- * @param row - The row to test
- * @param conditions - The conditions to fold
- * @returns Whether the row satisfies the combined conditions
- */
-export declare function matchesCriteria(row: Row, conditions: readonly Condition[]): boolean;
-/**
- * Filter rows by a list of conditions — the shared basis for a table's count
- * and aggregate paths (no sort/page, unlike {@link applyCriteria}).
- *
- * @remarks
- * An empty condition list matches every row (returned as-is, no copy). Folds
- * each row through {@link matchesCriteria}.
- *
- * @param rows - The rows to filter
- * @param conditions - The conditions to apply (empty matches everything)
- * @returns The matching rows
- *
- * @example
- * ```ts
- * filterRows(
- * 	[{ age: 30 }, { age: 12 }],
- * 	[{ column: 'age', operator: 'above', values: [18], connector: 'and' }],
- * ) // => [{ age: 30 }]
- * ```
- */
-export declare function filterRows(rows: readonly Row[], conditions: readonly Condition[]): readonly Row[];
-/**
- * Sort rows by an ordering specification, leaving the input untouched.
- *
- * @remarks
- * Applies the terms in priority order — the first term that distinguishes two
- * rows decides — using {@link compareValues}, reversing for `descending`.
- *
- * @param rows - The rows to sort
- * @param order - The ordering terms in priority order
- * @returns A new, sorted array
- */
-export declare function sortRows(rows: readonly Row[], order: readonly Order[]): readonly Row[];
-/**
- * Apply a {@link Criteria} to rows — filter, then sort, then page.
- *
- * @remarks
- * The whole portable read pipeline in one place: conditions filter, `order`
- * sorts, and `offset` / `limit` window the result. Each step is skipped when its
- * part of the criteria is absent. The reference {@link DriverInterface} backends
- * lean on this rather than each re-deriving it.
- *
- * @param rows - The rows to process (typically a table's full `scan`)
- * @param criteria - The read specification, or `undefined` for all rows as-is
- * @returns The filtered, sorted, paged rows
- */
-export declare function applyCriteria(rows: readonly Row[], criteria?: Criteria): readonly Row[];
-/**
- * Compute an aggregate over a column across rows.
- *
- * @remarks
- * `count` returns the row count. The numeric aggregates coerce each cell with
- * the contracts `parseNumber` (so `'42'` counts) and ignore non-numeric cells;
- * over zero numeric values they return `undefined` — the SQL `NULL` of an empty
- * aggregate.
- *
- * @param rows - The rows to aggregate (non-record entries are ignored)
- * @param operation - The aggregate to compute
- * @param column - The column to aggregate
- * @returns The aggregate value, or `undefined` when undefined for the inputs
- */
-export declare function computeAggregate(rows: readonly unknown[], operation: AggregateFunction, column: FieldPath): number | undefined;
-/**
- * Read a row's primary key from a column, when it is a usable {@link Key}.
- *
- * @param row - The row to read
- * @param column - The primary-key column name
- * @returns The key (a string or finite number), or `undefined`
- */
-export declare function extractKey(row: Row, column: string): Key | undefined;
-/**
- * Map a column's {@link ContractShape} to its portable {@link ColumnType} — the
- * value a `TableSchema` carries so a native backend can declare a real column.
- *
- * @remarks
- * `string` → `text`; `number` → `integer` when the shape is integer-only, else
- * `real`; `boolean` → `boolean`. A `literal` takes the type of its values
- * (all-boolean → `boolean`, all-integer → `integer`, mixed/fractional numbers →
- * `real`, anything else → `text`). `optional` / `nullable` unwrap to their inner
- * type (nullability is tracked separately). `null` / `object` / `array` / `union` /
- * `json` / `raw` → `json`: a backend stores them as JSON text and can `json_extract`
- * for nested `FieldPath` queries. A scan-only backend ignores the result.
- *
- * @param shape - The column's contract shape
- * @returns The portable column type
- *
- * @example
- * ```ts
- * shapeToColumnType(stringShape()) // 'text'
- * shapeToColumnType(integerShape()) // 'integer'
- * shapeToColumnType(optionalShape(integerShape())) // 'integer'
- * shapeToColumnType(objectShape({ a: stringShape() })) // 'json'
- * ```
- */
-export declare function shapeToColumnType(shape: ContractShape): ColumnType;
-/**
- * Throw when an {@link ReadOptions.signal | AbortSignal} has fired — the shared
- * cancellation gate checked at operation boundaries and between streamed rows.
- *
- * @remarks
- * A no-op for `undefined` or a live signal, so callers thread `options?.signal`
- * straight through. When the signal has aborted, throws an `ABORTED`
- * {@link DatabaseError} carrying the signal's `reason` in its context — callers
- * mint signals with whatever tool they like (`AbortSignal.timeout(ms)`,
- * `new AbortController()`, `@orkestrel/abort`).
- *
- * @param signal - The signal to check, if any
- * @returns Nothing — returns normally while the signal is live
- * @throws An `ABORTED` {@link DatabaseError} when the signal has aborted
- *
- * @example
- * ```ts
- * import { checkAbort } from '@orkestrel/database'
- *
- * const controller = new AbortController()
- * checkAbort(controller.signal) // returns
- * controller.abort('too slow')
- * checkAbort(controller.signal) // throws DatabaseError('ABORTED', …)
- * ```
- */
-export declare function checkAbort(signal: AbortSignal | undefined): void;
-/**
- * Structurally diff a deployed and a declared table set into a {@link Migration}
- * plan.
- *
- * @remarks
- * Tables present in `declared` but not `deployed` become `table.add` steps
- * (carrying the full declared {@link TableSchema}); tables present in
- * `deployed` but not `declared` become `table.remove` steps. Tables present in
- * both are diffed column-by-column (by name) and index-group-by-index-group
- * (by deep equality of the column-name array), each producing `column.add` /
- * `column.remove` / `index.add` / `index.remove` steps. Step order is
- * deterministic: every `table.remove`, then every `table.add`, then each
- * shared table's column/index changes in `declared` order. `from` / `to` are
- * plan labels only — version tracking itself is deferred to persistent
- * backends.
- *
- * @param deployed - The table schemas currently applied
- * @param declared - The table schemas the caller wants applied
- * @param from - The plan's source version label (defaults to `0`)
- * @param to - The plan's target version label (defaults to `1`)
- * @returns The migration plan moving `deployed` toward `declared`
- *
- * @example
- * ```ts
- * const plan = planMigration(
- * 	[{ name: 'users', primary: 'id', columns: [], indexes: [] }],
- * 	[{ name: 'users', primary: 'id', columns: [{ name: 'age', type: 'integer', nullable: false }], indexes: [] }],
- * )
- * // plan.steps === [{ operation: 'column.add', table: 'users', column: { name: 'age', ... } }]
- * ```
- */
-export declare function planMigration(deployed: readonly TableSchema[], declared: readonly TableSchema[], from?: number, to?: number): Migration;
-/**
- * Apply one table's {@link MigrationStep}s to its rows — a pure row transform.
- *
- * @remarks
- * `column.remove` drops that field from every row (a fresh copy — inputs are
- * never mutated, AGENTS §11); `column.add` leaves rows as-is (an absent field
- * reads as `undefined`, backfill is application policy). `table.add` /
- * `table.remove` / `index.add` / `index.remove` are no-ops here (they operate
- * on storage shape, not row shape). Steps for tables other than the one
- * `rows` belongs to are ignored — pass only the steps relevant to this table.
- *
- * @param rows - The table's current rows
- * @param steps - The migration steps to apply (typically one table's slice of a {@link Migration})
- * @returns A new array of transformed rows; `rows` is never mutated
- *
- * @example
- * ```ts
- * const rows = [{ id: 'a', name: 'Ada', legacy: true }]
- * migrateRows(rows, [{ operation: 'column.remove', table: 'users', column: 'legacy' }])
- * // => [{ id: 'a', name: 'Ada' }]
- * ```
- */
-export declare function migrateRows(rows: readonly Row[], steps: readonly MigrationStep[]): readonly Row[];
-/**
- * Run the driver-conformance battery against a fresh {@link DriverInterface}
- * per phase, yielding one {@link ConformanceFinding} per violated invariant —
- * the shared invariant suite every backend (in-memory, SQLite, IndexedDB)
- * must uphold to be a drop-in {@link DriverInterface}.
- *
- * @remarks
- * Framework-agnostic: no test-runner or Node imports, only sibling core
- * modules — so it runs equally from a unit test, a smoke script, or a new
- * driver's own README. Opens a fixed two-table schema (`users` keyed by the
- * default `id`, `posts` keyed by a non-id `slug`) and, calling `factory()`
- * fresh for each phase so failures stay isolated, verifies: `open`/`close`;
- * `read` of a missing key returns `undefined`; `write`/`read` round-trip with
- * copy-in/copy-out isolation (mutating the caller's row after `write`, or the
- * row `read` returns, never perturbs stored state) and upsert-overwrite;
- * `delete` returns `true` then `false`; `keys`/`scan` yield in ascending key
- * order; `clear` empties only its target table; `snapshot`'s rollback thunk
- * restores pre-snapshot state; a scoped `snapshot(['users'])` rolls back only
- * the named table, leaving a concurrent mutation to another table intact; a
- * non-`id` primary key (`posts.slug`) round-trips; a nested-object row
- * round-trips structurally (via {@link deepEqual}). The optional surface is
- * presence-gated: when `migrate` exists, a `column.remove` plan strips the
- * column from stored rows and a plan referencing an unknown table throws
- * `DatabaseError` `MIGRATION`; when `stream` exists, it yields only
- * condition-matching rows and honors `offset`/`limit`; when `transaction`
- * exists, `commit` persists and `rollback` restores; when both `meta` and
- * `stamp` exist, a fresh store's `meta()` is `undefined`, and after
- * `stamp({ version, schema })`, `meta()` returns the exact stamped value.
- *
- * Each phase runs within a `try`/`catch`: an EXPECTED mismatch yields a
- * finding built from the assertion, while an UNEXPECTED throw (a driver
- * crash mid-phase) is caught and yielded as a finding too, naming the phase
- * as `check` and carrying the caught error in `context.error` — a broken
- * driver can never escape the battery as an unhandled rejection. Within a
- * phase, the FIRST violated assertion yields and the phase stops (matching
- * the historical fail-fast shape at phase granularity); the generator then
- * moves on to the next phase regardless. Because this is a **generator**,
- * consuming only the first yielded value reproduces true fail-fast (later
- * phases never run) — that is exactly what {@link conformDriver} does.
- *
- * @param factory - Mints a fresh, unopened driver instance (called once per phase)
- * @yields One {@link ConformanceFinding} per violated invariant, in phase order
- *
- * @example
- * ```ts
- * import { createMemoryDriver, driverFindings } from '@orkestrel/database'
- *
- * for await (const finding of driverFindings(() => createMemoryDriver())) {
- * 	console.log(finding.check, finding.message)
- * }
- * ```
- */
-export declare function driverFindings(factory: () => DriverInterface): AsyncGenerator<ConformanceFinding>;
-/**
- * Run the driver-conformance battery, throwing on the first violated
- * invariant — the fail-fast entry point most callers (test setup, CI smoke
- * checks) want.
- *
- * @remarks
- * A thin driver over {@link driverFindings}: because that generator is
- * lazy, consuming only its first yielded value means every LATER phase
- * never runs — true fail-fast, not merely "report only the first". The
- * thrown error is byte-compatible with the historical shape: a
- * `CONFORMANCE` {@link DatabaseError} whose `message` is the finding's
- * `message` and whose `context` is `{ check, ...finding.context }`.
- *
- * @param factory - Mints a fresh, unopened driver instance (called once per phase)
- * @returns Nothing — resolves once every phase has passed
- * @throws A `CONFORMANCE` {@link DatabaseError} on the first violated invariant
- *
- * @example
- * ```ts
- * import { conformDriver, createMemoryDriver } from '@orkestrel/database'
- *
- * await conformDriver(() => createMemoryDriver()) // resolves when every invariant holds
- * ```
- */
-export declare function conformDriver(factory: () => DriverInterface): Promise<void>;
-/**
- * Run the FULL driver-conformance battery and collect every violation — the
- * audit entry point for a driver author who wants a complete report rather
- * than a single fail-fast throw.
- *
- * @remarks
- * Drains {@link driverFindings} to completion: every phase runs regardless
- * of earlier violations, so a driver breaking two independent invariants
- * reports both. An empty array means the driver is fully conformant.
- *
- * @param factory - Mints a fresh, unopened driver instance (called once per phase)
- * @returns Every violated invariant found, in phase order (empty when fully conformant)
- *
- * @example
- * ```ts
- * import { auditDriver, createMemoryDriver } from '@orkestrel/database'
- *
- * const findings = await auditDriver(() => createMemoryDriver())
- * for (const finding of findings) console.log(`${finding.check}: ${finding.message}`)
- * ```
- */
-export declare function auditDriver(factory: () => DriverInterface): Promise<readonly ConformanceFinding[]>;