@korajs/core 1.0.0-beta.12 → 1.0.0-beta.14

package/dist/internal.d.cts

@@ -1,23 +1,6 @@
-import { x as OperationInput, p as KoraEventEmitter, r as KoraEventType, q as KoraEventListener, o as KoraEventByType, f as Operation } from './events-D7JCtQSD.cjs';
-export { a as validateOperationParams } from './operation-BXvJ6RiA.cjs';
-
-/**
- * Compute the content-addressed ID for an operation using SHA-256.
- * The same operation content always produces the same hash, ensuring deduplication.
- *
- * @param input - The operation input (without id/timestamp, which are assigned separately)
- * @param timestamp - The HLC timestamp serialized as a string
- * @returns A hex-encoded SHA-256 hash
- */
-declare function computeOperationId(input: OperationInput, timestamp: string): Promise<string>;
-/**
- * Deterministic JSON serialization with sorted keys.
- * Ensures identical objects always produce identical strings regardless of property insertion order.
- *
- * @param obj - The value to serialize
- * @returns A deterministic JSON string
- */
-declare function canonicalize(obj: unknown): string;
+import { S as Stamp, k as FoldFieldKind } from './sql-gen-BOeuiyqu.cjs';
+export { B as SCHEMA_CEILING_DIRECTIVE, G as canonicalize, I as collectionIndexName, u as computeOperationId, J as enumCheckConstraint, L as legacyCollectionIndexName, N as sqlDefaultLiteral, P as sqlStringLiteral, Q as validateOperationParams } from './sql-gen-BOeuiyqu.cjs';
+import { X as KoraEventEmitter, Z as KoraEventType, Y as KoraEventListener, W as KoraEventByType, a as Operation, H as HLCTimestamp, b as CustomResolver, C as CollectionDefinition } from './events-Da29Dt_3.cjs';
 
 /**
  * Concrete implementation of KoraEventEmitter.
@@ -56,4 +39,251 @@ declare class SimpleEventEmitter implements KoraEventEmitter {
  */
 declare function topologicalSort(operations: Operation[]): Operation[];
 
-export { SimpleEventEmitter, canonicalize, computeOperationId, topologicalSort };
+/**
+ * Value-domain rules live in validation only (RT-101).
+ *
+ * Kora's generated DDL used to restate two schema rules as storage constraints: an enum
+ * field's `CHECK (col IN (...))` and a required field's `NOT NULL`. The value domain
+ * already enforces both at write time on every replica, and storage constraints cannot
+ * evolve with the schema (SQLite cannot alter a column constraint): an enum value added
+ * by a schema upgrade was valid everywhere but refused by every existing table. The DDL
+ * no longer emits them, and existing tables are relaxed once, by these helpers.
+ *
+ * Kora's own bookkeeping columns (`id` and every `_`-prefixed column) keep their
+ * constraints: they are written by Kora only and never evolve with the app schema.
+ */
+/** A row of `PRAGMA table_info(<table>)`. */
+interface SqliteColumnInfo {
+    cid: number;
+    name: string;
+    type: string;
+    notnull: number;
+    dflt_value: string | null;
+    pk: number;
+}
+/** A row of `PRAGMA foreign_key_list(<table>)`. */
+interface SqliteForeignKeyInfo {
+    id: number;
+    seq: number;
+    table: string;
+    from: string;
+    to: string | null;
+    on_update: string;
+    on_delete: string;
+    match?: string;
+}
+/** What a SQLite table looks like, read from its catalog. */
+interface SqliteTableCatalog {
+    /** Table name */
+    table: string;
+    /** The table's `CREATE TABLE` statement (`sqlite_master.sql`) */
+    sql: string;
+    columns: readonly SqliteColumnInfo[];
+    foreignKeys: readonly SqliteForeignKeyInfo[];
+    /** Column lists of the table's `UNIQUE` constraints (`index_list` origin `u`) */
+    uniqueConstraints: readonly (readonly string[])[];
+    /** `CREATE INDEX` / `CREATE TRIGGER` statements on the table (`sqlite_master.sql`) */
+    dependents: readonly string[];
+}
+/** Columns Kora writes itself; their constraints are kept. */
+declare function isKoraInternalColumn(name: string): boolean;
+/** One `CHECK` constraint of a SQLite `CREATE TABLE` statement. */
+interface SqliteCheckConstraint {
+    /** The constraint name (`CONSTRAINT <name> CHECK ...`), unquoted, or null */
+    name: string | null;
+    /** The checked expression, verbatim (the text between the parentheses) */
+    expression: string;
+    /** The column whose definition carries the check (a column constraint), or null */
+    column: string | null;
+}
+/**
+ * Every `CHECK` constraint of a SQLite `CREATE TABLE` statement, column and table
+ * constraints alike, with the expression verbatim (RT-111). The catalog pragmas do not
+ * report checks, so a table rebuild must carry them over from the statement itself.
+ *
+ * @param createTableSql - The table's `CREATE TABLE` statement (`sqlite_master.sql`)
+ * @returns The checks in statement order
+ */
+declare function parseSqliteCheckConstraints(createTableSql: string): SqliteCheckConstraint[];
+/**
+ * Whether a check is one of Kora's own value-domain checks (beta.12 and earlier DDL):
+ * an enum check (see {@link parseEnumCheckDefinition}) on one column that is not Kora's
+ * own and, when `enumColumns` is given, is an enum field of the schema. A check of any
+ * other shape, or on another column, was added by hand and is kept (RT-111).
+ *
+ * @param check - A check of the table
+ * @param enumColumns - The table's enum fields (undefined: any enum-shaped check counts)
+ */
+declare function isKoraSqliteEnumCheck(check: SqliteCheckConstraint, enumColumns?: readonly string[]): boolean;
+/**
+ * Whether a table still carries a value-domain constraint of Kora's: an enum `CHECK` on
+ * an enum field (see {@link isKoraSqliteEnumCheck}), or `NOT NULL` on a column that is not
+ * Kora's own. Checks added by hand never make a table need relaxation.
+ *
+ * @param catalog - The table as read from SQLite's catalog
+ * @param enumColumns - The table's enum fields (undefined: any enum-shaped check counts)
+ */
+declare function sqliteTableNeedsRelaxation(catalog: SqliteTableCatalog, enumColumns?: readonly string[]): boolean;
+/**
+ * Whether a check names any of `columns` (its own column, or an identifier in its
+ * expression). A rebuild that drops a column cannot keep a check that reads it.
+ *
+ * @param check - A check of the table
+ * @param columns - Column names
+ */
+declare function sqliteCheckReferencesColumn(check: SqliteCheckConstraint, columns: ReadonlySet<string>): boolean;
+/**
+ * The table constraint that re-creates a kept check in a rebuilt table: a column check
+ * becomes a table check (SQLite evaluates both the same way, per row).
+ *
+ * @param check - The check to keep
+ */
+declare function sqliteCheckConstraintDefinition(check: SqliteCheckConstraint): string;
+/**
+ * Statements that rebuild a SQLite table without value-domain constraints (SQLite's
+ * documented "make other kinds of table schema changes" procedure), keeping every row,
+ * column (types and defaults), primary key, foreign key, `UNIQUE` constraint, index and
+ * trigger, and every `CHECK` that is not one of Kora's enum checks (RT-111). Run them in
+ * ONE transaction, with foreign key enforcement off when the database enforces foreign
+ * keys (the drop of a referenced table would otherwise fail or fire its actions). Returns
+ * an empty list when the table needs nothing, so running it again is a no-op
+ * (idempotent); a rebuild interrupted mid-way rolls back with its transaction and runs
+ * again at the next open (resumable).
+ *
+ * @param catalog - The table as read from SQLite's catalog
+ * @param enumColumns - The table's enum fields, which decide which enum-shaped checks are
+ *   Kora's (undefined: any enum-shaped check on a non-internal column)
+ * @returns The rebuild statements, or `[]`
+ */
+declare function sqliteConstraintRelaxationStatements(catalog: SqliteTableCatalog, enumColumns?: readonly string[]): string[];
+/** A `CHECK` that restricts one column to a list of string literals (an enum check). */
+interface EnumCheckShape {
+    /** The column, unquoted */
+    column: string;
+    /** The allowed values, unquoted */
+    values: string[];
+    /** The check also allows NULL (`... OR col IS NULL`) */
+    allowsNull: boolean;
+}
+/**
+ * Parse a `CHECK` constraint definition as an enum check, structurally: one column
+ * compared to string literals, in any form Postgres normalizes `col IN (...)` to
+ * (`col = ANY (ARRAY[...])`, the single-value `col = 'x'`, casts such as
+ * `(col)::text = ANY ((ARRAY['x'::character varying])::text[])`), a disjunction of
+ * equalities (`col = 'a' OR col = 'b'`), the SQLite source form `col IN ('a', 'b')`, an
+ * optional `OR col IS NULL`, and a trailing `NOT VALID`. Anything else (another operator,
+ * a function call, two columns, `AND`, `NOT`) is not an enum check and returns null.
+ *
+ * @param definition - The constraint definition (`pg_get_constraintdef`, or SQLite DDL)
+ * @returns The column and values, or null when the check has another shape
+ */
+declare function parseEnumCheckDefinition(definition: string): EnumCheckShape | null;
+/**
+ * Whether a Postgres `CHECK` constraint definition (`pg_get_constraintdef`) has the shape
+ * of a Kora enum check (see {@link parseEnumCheckDefinition}). Other checks (added by hand)
+ * are left alone.
+ *
+ * @param definition - The constraint definition text
+ */
+declare function isPostgresEnumCheckDefinition(definition: string): boolean;
+/** Runs a read-only SQL statement and returns its rows (an adapter's or a transaction's query). */
+type SqliteQueryFn = (sql: string) => Promise<Array<Record<string, unknown>>>;
+/**
+ * Read a SQLite table's catalog through `query`, or null when the table does not exist.
+ *
+ * @param query - Runs a SELECT/PRAGMA and returns rows
+ * @param table - The table name
+ */
+declare function readSqliteTableCatalog(query: SqliteQueryFn, table: string): Promise<SqliteTableCatalog | null>;
+/**
+ * Every statement that relaxes the given SQLite tables (one rebuild per table that still
+ * carries a value-domain constraint; tables that do not exist or need nothing are
+ * skipped). Run them in one transaction; see {@link sqliteConstraintRelaxationStatements}.
+ *
+ * @param query - Runs a SELECT/PRAGMA and returns rows (inside the caller's transaction)
+ * @param tables - The collection tables to check
+ * @param enumColumnsByTable - Each table's enum fields (only enum checks on them are
+ *   Kora's, RT-111); a table missing here treats any enum-shaped check as Kora's
+ * @returns The statements, or `[]` when every table is already relaxed (idempotent)
+ */
+declare function planSqliteConstraintRelaxation(query: SqliteQueryFn, tables: readonly string[], enumColumnsByTable?: Readonly<Record<string, readonly string[]>>): Promise<string[]>;
+/**
+ * The `ALTER TABLE` statements that relax Postgres collection tables: drop every Kora enum
+ * `CHECK` (one column compared to a literal list, see {@link isPostgresEnumCheckDefinition})
+ * and every `NOT NULL` on a schema field. Kora's own columns, multi-column checks and
+ * checks of any other shape (added by hand) are kept. Reads the catalog of the current
+ * schema through `query`, so run it and the statements in one transaction.
+ *
+ * A check is matched structurally against the schema (RT-108): it is parsed as an enum
+ * check ({@link parseEnumCheckDefinition}, every form Postgres normalizes `IN (...)` to,
+ * including the single-value `col = 'x'`) and dropped when its one column is an enum field
+ * of the table (`enumFieldsByTable`; without it, any schema field), or when it restricts
+ * any other non-internal column to two or more literals (the multi-value shape every
+ * beta.12 enum check had).
+ *
+ * @param query - Runs a SELECT and returns rows
+ * @param fieldsByTable - Collection table name to its schema field names
+ * @param enumFieldsByTable - Collection table name to its enum field names (before and
+ *   after the change); when a table is missing, every schema field counts as one
+ * @returns The statements, or `[]` when nothing is left to relax (idempotent)
+ */
+declare function planPostgresConstraintRelaxation(query: SqliteQueryFn, fieldsByTable: Readonly<Record<string, readonly string[]>>, enumFieldsByTable?: Readonly<Record<string, readonly string[]>>): Promise<string[]>;
+
+/**
+ * Total order on stamps: authority class (only `merge('server-authoritative')`
+ * fields carry one), then serialized HLC (which sorts exactly like
+ * `HybridLogicalClock.compare`), then operation id.
+ *
+ * @returns Negative if a < b, positive if a > b, 0 if equal
+ */
+declare function compareStamps(a: Stamp, b: Stamp): number;
+/**
+ * Build a stamp from an HLC timestamp and an operation id. Throws
+ * `InvalidTimestampError` for a timestamp that cannot be serialized (for example
+ * a null wallTime left by a beta.12 backup restore): such an op must be repaired
+ * by the log-integrity scan (W8) before it is folded, never folded with a guess.
+ */
+declare function stampOf(timestamp: HLCTimestamp, opId: string): Stamp;
+
+/** How the fold merges one field, derived from the schema. */
+interface FieldPlan {
+    kind: FoldFieldKind;
+    /** For 'set': removals are ignored (`merge('append-only')`). */
+    appendOnly: boolean;
+    /** For 'res': the custom resolver. */
+    resolver?: CustomResolver;
+    /** Name of the strategy for traces. */
+    strategy: string;
+    /** Tier for traces: 3 for custom resolvers, 1 otherwise. */
+    tier: 1 | 3;
+    /** Secret field: values are redacted from traces. */
+    secret: boolean;
+    /** `merge('server-authoritative')`: writes of authoritative nodes win (class 1 stamps). */
+    authoritative?: boolean;
+}
+/**
+ * Decide how a field is folded. Precedence matches the pairwise engine it
+ * replaces: a custom resolver (tier 3), then a schema-declared merge strategy,
+ * then the field kind's default.
+ *
+ * | Schema | Fold kind |
+ * |---|---|
+ * | `resolve: { field }` | 'res' (resolver over the write log) |
+ * | `merge('counter')` | 'ctr' (base + deltas) |
+ * | `merge('max')` / `merge('min')` | 'max' / 'min' |
+ * | array, `merge('append-only')` | 'set' with removals ignored |
+ * | array (default or `merge('union')`) | 'set' (LWW element set) |
+ * | object / json | 'map' (per-top-level-key LWW) |
+ * | richtext | 'rt' (Yjs updates + string reset register) |
+ * | `merge('server-authoritative')` | 'reg' with authority-classed stamps |
+ * | everything else, `merge('lww')` | 'reg' |
+ *
+ * A field that is not in the schema (an older schema version's field, or an
+ * unknown collection) folds as a last-write-wins register.
+ *
+ * @param collection - The collection definition, if the schema has it
+ * @param field - The field name
+ */
+declare function planField(collection: CollectionDefinition | undefined, field: string): FieldPlan;
+
+export { type EnumCheckShape, type FieldPlan, SimpleEventEmitter, type SqliteCheckConstraint, type SqliteColumnInfo, type SqliteForeignKeyInfo, type SqliteQueryFn, type SqliteTableCatalog, compareStamps, isKoraInternalColumn, isKoraSqliteEnumCheck, isPostgresEnumCheckDefinition, parseEnumCheckDefinition, parseSqliteCheckConstraints, planField, planPostgresConstraintRelaxation, planSqliteConstraintRelaxation, readSqliteTableCatalog, sqliteCheckConstraintDefinition, sqliteCheckReferencesColumn, sqliteConstraintRelaxationStatements, sqliteTableNeedsRelaxation, stampOf, topologicalSort };

package/dist/internal.d.ts

@@ -1,23 +1,6 @@
-import { x as OperationInput, p as KoraEventEmitter, r as KoraEventType, q as KoraEventListener, o as KoraEventByType, f as Operation } from './events-D7JCtQSD.js';
-export { a as validateOperationParams } from './operation-BX4ok7U4.js';
-
-/**
- * Compute the content-addressed ID for an operation using SHA-256.
- * The same operation content always produces the same hash, ensuring deduplication.
- *
- * @param input - The operation input (without id/timestamp, which are assigned separately)
- * @param timestamp - The HLC timestamp serialized as a string
- * @returns A hex-encoded SHA-256 hash
- */
-declare function computeOperationId(input: OperationInput, timestamp: string): Promise<string>;
-/**
- * Deterministic JSON serialization with sorted keys.
- * Ensures identical objects always produce identical strings regardless of property insertion order.
- *
- * @param obj - The value to serialize
- * @returns A deterministic JSON string
- */
-declare function canonicalize(obj: unknown): string;
+import { S as Stamp, k as FoldFieldKind } from './sql-gen-CXTA6w-w.js';
+export { B as SCHEMA_CEILING_DIRECTIVE, G as canonicalize, I as collectionIndexName, u as computeOperationId, J as enumCheckConstraint, L as legacyCollectionIndexName, N as sqlDefaultLiteral, P as sqlStringLiteral, Q as validateOperationParams } from './sql-gen-CXTA6w-w.js';
+import { X as KoraEventEmitter, Z as KoraEventType, Y as KoraEventListener, W as KoraEventByType, a as Operation, H as HLCTimestamp, b as CustomResolver, C as CollectionDefinition } from './events-Da29Dt_3.js';
 
 /**
  * Concrete implementation of KoraEventEmitter.
@@ -56,4 +39,251 @@ declare class SimpleEventEmitter implements KoraEventEmitter {
  */
 declare function topologicalSort(operations: Operation[]): Operation[];
 
-export { SimpleEventEmitter, canonicalize, computeOperationId, topologicalSort };
+/**
+ * Value-domain rules live in validation only (RT-101).
+ *
+ * Kora's generated DDL used to restate two schema rules as storage constraints: an enum
+ * field's `CHECK (col IN (...))` and a required field's `NOT NULL`. The value domain
+ * already enforces both at write time on every replica, and storage constraints cannot
+ * evolve with the schema (SQLite cannot alter a column constraint): an enum value added
+ * by a schema upgrade was valid everywhere but refused by every existing table. The DDL
+ * no longer emits them, and existing tables are relaxed once, by these helpers.
+ *
+ * Kora's own bookkeeping columns (`id` and every `_`-prefixed column) keep their
+ * constraints: they are written by Kora only and never evolve with the app schema.
+ */
+/** A row of `PRAGMA table_info(<table>)`. */
+interface SqliteColumnInfo {
+    cid: number;
+    name: string;
+    type: string;
+    notnull: number;
+    dflt_value: string | null;
+    pk: number;
+}
+/** A row of `PRAGMA foreign_key_list(<table>)`. */
+interface SqliteForeignKeyInfo {
+    id: number;
+    seq: number;
+    table: string;
+    from: string;
+    to: string | null;
+    on_update: string;
+    on_delete: string;
+    match?: string;
+}
+/** What a SQLite table looks like, read from its catalog. */
+interface SqliteTableCatalog {
+    /** Table name */
+    table: string;
+    /** The table's `CREATE TABLE` statement (`sqlite_master.sql`) */
+    sql: string;
+    columns: readonly SqliteColumnInfo[];
+    foreignKeys: readonly SqliteForeignKeyInfo[];
+    /** Column lists of the table's `UNIQUE` constraints (`index_list` origin `u`) */
+    uniqueConstraints: readonly (readonly string[])[];
+    /** `CREATE INDEX` / `CREATE TRIGGER` statements on the table (`sqlite_master.sql`) */
+    dependents: readonly string[];
+}
+/** Columns Kora writes itself; their constraints are kept. */
+declare function isKoraInternalColumn(name: string): boolean;
+/** One `CHECK` constraint of a SQLite `CREATE TABLE` statement. */
+interface SqliteCheckConstraint {
+    /** The constraint name (`CONSTRAINT <name> CHECK ...`), unquoted, or null */
+    name: string | null;
+    /** The checked expression, verbatim (the text between the parentheses) */
+    expression: string;
+    /** The column whose definition carries the check (a column constraint), or null */
+    column: string | null;
+}
+/**
+ * Every `CHECK` constraint of a SQLite `CREATE TABLE` statement, column and table
+ * constraints alike, with the expression verbatim (RT-111). The catalog pragmas do not
+ * report checks, so a table rebuild must carry them over from the statement itself.
+ *
+ * @param createTableSql - The table's `CREATE TABLE` statement (`sqlite_master.sql`)
+ * @returns The checks in statement order
+ */
+declare function parseSqliteCheckConstraints(createTableSql: string): SqliteCheckConstraint[];
+/**
+ * Whether a check is one of Kora's own value-domain checks (beta.12 and earlier DDL):
+ * an enum check (see {@link parseEnumCheckDefinition}) on one column that is not Kora's
+ * own and, when `enumColumns` is given, is an enum field of the schema. A check of any
+ * other shape, or on another column, was added by hand and is kept (RT-111).
+ *
+ * @param check - A check of the table
+ * @param enumColumns - The table's enum fields (undefined: any enum-shaped check counts)
+ */
+declare function isKoraSqliteEnumCheck(check: SqliteCheckConstraint, enumColumns?: readonly string[]): boolean;
+/**
+ * Whether a table still carries a value-domain constraint of Kora's: an enum `CHECK` on
+ * an enum field (see {@link isKoraSqliteEnumCheck}), or `NOT NULL` on a column that is not
+ * Kora's own. Checks added by hand never make a table need relaxation.
+ *
+ * @param catalog - The table as read from SQLite's catalog
+ * @param enumColumns - The table's enum fields (undefined: any enum-shaped check counts)
+ */
+declare function sqliteTableNeedsRelaxation(catalog: SqliteTableCatalog, enumColumns?: readonly string[]): boolean;
+/**
+ * Whether a check names any of `columns` (its own column, or an identifier in its
+ * expression). A rebuild that drops a column cannot keep a check that reads it.
+ *
+ * @param check - A check of the table
+ * @param columns - Column names
+ */
+declare function sqliteCheckReferencesColumn(check: SqliteCheckConstraint, columns: ReadonlySet<string>): boolean;
+/**
+ * The table constraint that re-creates a kept check in a rebuilt table: a column check
+ * becomes a table check (SQLite evaluates both the same way, per row).
+ *
+ * @param check - The check to keep
+ */
+declare function sqliteCheckConstraintDefinition(check: SqliteCheckConstraint): string;
+/**
+ * Statements that rebuild a SQLite table without value-domain constraints (SQLite's
+ * documented "make other kinds of table schema changes" procedure), keeping every row,
+ * column (types and defaults), primary key, foreign key, `UNIQUE` constraint, index and
+ * trigger, and every `CHECK` that is not one of Kora's enum checks (RT-111). Run them in
+ * ONE transaction, with foreign key enforcement off when the database enforces foreign
+ * keys (the drop of a referenced table would otherwise fail or fire its actions). Returns
+ * an empty list when the table needs nothing, so running it again is a no-op
+ * (idempotent); a rebuild interrupted mid-way rolls back with its transaction and runs
+ * again at the next open (resumable).
+ *
+ * @param catalog - The table as read from SQLite's catalog
+ * @param enumColumns - The table's enum fields, which decide which enum-shaped checks are
+ *   Kora's (undefined: any enum-shaped check on a non-internal column)
+ * @returns The rebuild statements, or `[]`
+ */
+declare function sqliteConstraintRelaxationStatements(catalog: SqliteTableCatalog, enumColumns?: readonly string[]): string[];
+/** A `CHECK` that restricts one column to a list of string literals (an enum check). */
+interface EnumCheckShape {
+    /** The column, unquoted */
+    column: string;
+    /** The allowed values, unquoted */
+    values: string[];
+    /** The check also allows NULL (`... OR col IS NULL`) */
+    allowsNull: boolean;
+}
+/**
+ * Parse a `CHECK` constraint definition as an enum check, structurally: one column
+ * compared to string literals, in any form Postgres normalizes `col IN (...)` to
+ * (`col = ANY (ARRAY[...])`, the single-value `col = 'x'`, casts such as
+ * `(col)::text = ANY ((ARRAY['x'::character varying])::text[])`), a disjunction of
+ * equalities (`col = 'a' OR col = 'b'`), the SQLite source form `col IN ('a', 'b')`, an
+ * optional `OR col IS NULL`, and a trailing `NOT VALID`. Anything else (another operator,
+ * a function call, two columns, `AND`, `NOT`) is not an enum check and returns null.
+ *
+ * @param definition - The constraint definition (`pg_get_constraintdef`, or SQLite DDL)
+ * @returns The column and values, or null when the check has another shape
+ */
+declare function parseEnumCheckDefinition(definition: string): EnumCheckShape | null;
+/**
+ * Whether a Postgres `CHECK` constraint definition (`pg_get_constraintdef`) has the shape
+ * of a Kora enum check (see {@link parseEnumCheckDefinition}). Other checks (added by hand)
+ * are left alone.
+ *
+ * @param definition - The constraint definition text
+ */
+declare function isPostgresEnumCheckDefinition(definition: string): boolean;
+/** Runs a read-only SQL statement and returns its rows (an adapter's or a transaction's query). */
+type SqliteQueryFn = (sql: string) => Promise<Array<Record<string, unknown>>>;
+/**
+ * Read a SQLite table's catalog through `query`, or null when the table does not exist.
+ *
+ * @param query - Runs a SELECT/PRAGMA and returns rows
+ * @param table - The table name
+ */
+declare function readSqliteTableCatalog(query: SqliteQueryFn, table: string): Promise<SqliteTableCatalog | null>;
+/**
+ * Every statement that relaxes the given SQLite tables (one rebuild per table that still
+ * carries a value-domain constraint; tables that do not exist or need nothing are
+ * skipped). Run them in one transaction; see {@link sqliteConstraintRelaxationStatements}.
+ *
+ * @param query - Runs a SELECT/PRAGMA and returns rows (inside the caller's transaction)
+ * @param tables - The collection tables to check
+ * @param enumColumnsByTable - Each table's enum fields (only enum checks on them are
+ *   Kora's, RT-111); a table missing here treats any enum-shaped check as Kora's
+ * @returns The statements, or `[]` when every table is already relaxed (idempotent)
+ */
+declare function planSqliteConstraintRelaxation(query: SqliteQueryFn, tables: readonly string[], enumColumnsByTable?: Readonly<Record<string, readonly string[]>>): Promise<string[]>;
+/**
+ * The `ALTER TABLE` statements that relax Postgres collection tables: drop every Kora enum
+ * `CHECK` (one column compared to a literal list, see {@link isPostgresEnumCheckDefinition})
+ * and every `NOT NULL` on a schema field. Kora's own columns, multi-column checks and
+ * checks of any other shape (added by hand) are kept. Reads the catalog of the current
+ * schema through `query`, so run it and the statements in one transaction.
+ *
+ * A check is matched structurally against the schema (RT-108): it is parsed as an enum
+ * check ({@link parseEnumCheckDefinition}, every form Postgres normalizes `IN (...)` to,
+ * including the single-value `col = 'x'`) and dropped when its one column is an enum field
+ * of the table (`enumFieldsByTable`; without it, any schema field), or when it restricts
+ * any other non-internal column to two or more literals (the multi-value shape every
+ * beta.12 enum check had).
+ *
+ * @param query - Runs a SELECT and returns rows
+ * @param fieldsByTable - Collection table name to its schema field names
+ * @param enumFieldsByTable - Collection table name to its enum field names (before and
+ *   after the change); when a table is missing, every schema field counts as one
+ * @returns The statements, or `[]` when nothing is left to relax (idempotent)
+ */
+declare function planPostgresConstraintRelaxation(query: SqliteQueryFn, fieldsByTable: Readonly<Record<string, readonly string[]>>, enumFieldsByTable?: Readonly<Record<string, readonly string[]>>): Promise<string[]>;
+
+/**
+ * Total order on stamps: authority class (only `merge('server-authoritative')`
+ * fields carry one), then serialized HLC (which sorts exactly like
+ * `HybridLogicalClock.compare`), then operation id.
+ *
+ * @returns Negative if a < b, positive if a > b, 0 if equal
+ */
+declare function compareStamps(a: Stamp, b: Stamp): number;
+/**
+ * Build a stamp from an HLC timestamp and an operation id. Throws
+ * `InvalidTimestampError` for a timestamp that cannot be serialized (for example
+ * a null wallTime left by a beta.12 backup restore): such an op must be repaired
+ * by the log-integrity scan (W8) before it is folded, never folded with a guess.
+ */
+declare function stampOf(timestamp: HLCTimestamp, opId: string): Stamp;
+
+/** How the fold merges one field, derived from the schema. */
+interface FieldPlan {
+    kind: FoldFieldKind;
+    /** For 'set': removals are ignored (`merge('append-only')`). */
+    appendOnly: boolean;
+    /** For 'res': the custom resolver. */
+    resolver?: CustomResolver;
+    /** Name of the strategy for traces. */
+    strategy: string;
+    /** Tier for traces: 3 for custom resolvers, 1 otherwise. */
+    tier: 1 | 3;
+    /** Secret field: values are redacted from traces. */
+    secret: boolean;
+    /** `merge('server-authoritative')`: writes of authoritative nodes win (class 1 stamps). */
+    authoritative?: boolean;
+}
+/**
+ * Decide how a field is folded. Precedence matches the pairwise engine it
+ * replaces: a custom resolver (tier 3), then a schema-declared merge strategy,
+ * then the field kind's default.
+ *
+ * | Schema | Fold kind |
+ * |---|---|
+ * | `resolve: { field }` | 'res' (resolver over the write log) |
+ * | `merge('counter')` | 'ctr' (base + deltas) |
+ * | `merge('max')` / `merge('min')` | 'max' / 'min' |
+ * | array, `merge('append-only')` | 'set' with removals ignored |
+ * | array (default or `merge('union')`) | 'set' (LWW element set) |
+ * | object / json | 'map' (per-top-level-key LWW) |
+ * | richtext | 'rt' (Yjs updates + string reset register) |
+ * | `merge('server-authoritative')` | 'reg' with authority-classed stamps |
+ * | everything else, `merge('lww')` | 'reg' |
+ *
+ * A field that is not in the schema (an older schema version's field, or an
+ * unknown collection) folds as a last-write-wins register.
+ *
+ * @param collection - The collection definition, if the schema has it
+ * @param field - The field name
+ */
+declare function planField(collection: CollectionDefinition | undefined, field: string): FieldPlan;
+
+export { type EnumCheckShape, type FieldPlan, SimpleEventEmitter, type SqliteCheckConstraint, type SqliteColumnInfo, type SqliteForeignKeyInfo, type SqliteQueryFn, type SqliteTableCatalog, compareStamps, isKoraInternalColumn, isKoraSqliteEnumCheck, isPostgresEnumCheckDefinition, parseEnumCheckDefinition, parseSqliteCheckConstraints, planField, planPostgresConstraintRelaxation, planSqliteConstraintRelaxation, readSqliteTableCatalog, sqliteCheckConstraintDefinition, sqliteCheckReferencesColumn, sqliteConstraintRelaxationStatements, sqliteTableNeedsRelaxation, stampOf, topologicalSort };