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

package/dist/sql-builder-D5UMzHEo.d.ts

@@ -0,0 +1,615 @@
+import { SchemaDefinition, OperationTransform, FoldOptions, Operation, MergeTrace, FoldState, CausalTracker, HybridLogicalClock, SecretKeyProvider, OnDeleteAction, RelationDefinition, CollectionDefinition, FieldDescriptor } from '@korajs/core';
+import { T as Transaction, S as StorageAdapter, L as LocalMutationHandler, C as CollectionRecord, Q as QueryDescriptor } from './types-Dh-xyUjP.js';
+
+/**
+ * Merges richtext Yjs updates for the fold (core has no Yjs dependency): applies
+ * every update to one fresh document and encodes its state. The encoding depends
+ * only on the document's content, not on how it was split into updates, so every
+ * replica materializes byte-identical richtext.
+ */
+declare function mergeYjsUpdates(updates: Uint8Array[]): Uint8Array;
+/** Which fields of a row to (re)write from the fold state. */
+type MaterializeFields = 'all' | ReadonlySet<string>;
+/** Result of merging one operation into its record. */
+interface FoldApplyOutcome {
+    /** The merge changed the record's state. */
+    changed: boolean;
+    /** Merge traces (MergeTrace form), for `merge:*` events. */
+    traces: MergeTrace[];
+}
+/**
+ * The client side of the W7 fold: every write to a materialized row — local
+ * writes, remote operations, scope entries, rejection re-merges, re-materialization
+ * — goes through this class, inside the write transaction that appends the
+ * operation ("append, then merge"). A row is always the materialization of its
+ * record's fold state.
+ */
+declare class RecordFolder {
+    private readonly schema;
+    private readonly transforms;
+    private authoritative;
+    constructor(schema: SchemaDefinition, transforms?: readonly OperationTransform[]);
+    /** The schema transforms every merge applies (transforms at fold time, RT-84). */
+    getOperationTransforms(): readonly OperationTransform[];
+    /**
+     * The fields an operation's merge can change: its own data's keys, or every field
+     * when the fold reads it through a schema transform (whose view may name others).
+     */
+    private touchedFields;
+    /** Node ids whose writes win `merge('server-authoritative')` fields. */
+    getAuthoritativeNodeIds(): ReadonlySet<string>;
+    /** @internal Set by the store from persisted meta / the sync handshake. */
+    setAuthoritativeNodeIds(ids: Iterable<string>): void;
+    /** Fold options every merge of this database uses. */
+    options(traces?: FoldOptions['traces']): FoldOptions;
+    /** Whether the schema has a `merge('server-authoritative')` field in `collection`. */
+    hasAuthoritativeFields(collection: string): boolean;
+    /**
+     * Merge one operation (already appended to the log) into its record and
+     * re-materialize the row.
+     *
+     * @param tx - The write transaction that appended the operation
+     * @param op - The operation
+     * @param mode - 'remote' emits merge traces; 'local' does not (a local write is
+     *   computed from the row it updates, so it is never concurrent with it)
+     */
+    applyInTx(tx: Transaction, op: Operation, mode: 'local' | 'remote'): Promise<FoldApplyOutcome>;
+    /**
+     * Fold a record from its base state and its log, leaving out operations the
+     * server terminally rejected, and re-materialize its row (all fields).
+     *
+     * @returns The new state (null when nothing of the record remains)
+     */
+    refoldInTx(tx: Transaction, collection: string, recordId: string, options?: {
+        clearRetraction?: boolean;
+    }): Promise<FoldState | null>;
+    /**
+     * `join(base, snapshot, fold(log - terminally rejected, provisional effects))`, or
+     * null when none exists. Base and snapshot are adapted to the current fold plan
+     * (RT-63): a field whose kind changed is rebuilt from its materialized value.
+     */
+    foldFromLog(tx: Transaction, collection: string, recordId: string): Promise<FoldState | null>;
+    /** The record's operations (log + retained sequence-conflict rows). */
+    loadRecordOperations(tx: Transaction, collection: string, recordId: string): Promise<Operation[]>;
+    /**
+     * Which of `ids` the fold leaves out: operations with a terminal-rejection marker
+     * from the server (or quarantined by a scope retraction, which the server never
+     * receives). Writes the user chose to discard from a held node are NOT left out:
+     * discarding stops the upload, it is not a rollback.
+     */
+    loadTerminalRejections(tx: Transaction, ids: readonly string[]): Promise<Set<string>>;
+    /**
+     * The record's stored state, or null (none, another format version, or a field
+     * whose fold kind the schema has changed since: the caller re-folds, RT-63).
+     */
+    loadState(tx: Transaction, collection: string, recordId: string): Promise<FoldState | null>;
+    /** The stored state as it is, even when the plan changed (a snapshot seed). */
+    loadStoredState(tx: Transaction, collection: string, recordId: string): Promise<FoldState | null>;
+    /** The record's compacted base, adapted to the current fold plan (RT-63). */
+    loadBase(tx: Transaction, collection: string, recordId: string): Promise<FoldState | null>;
+    /** The record's row snapshot (RT-68), adapted to the current fold plan. */
+    loadSnapshot(tx: Transaction, collection: string, recordId: string): Promise<FoldState | null>;
+    /** Store `snapshot` as the record's row snapshot (joined with an existing one). */
+    saveSnapshot(tx: Transaction, snapshot: FoldState): Promise<void>;
+    /**
+     * A scope entry carrying the server's fold state (RT-29) replaces the record's row
+     * snapshot (RT-68): the server's state is built from every operation of the record
+     * the device was missing, so with the device's own log it is the exact state.
+     * Only a carried state this schema can read and join counts (otherwise the entry
+     * merges by its data and the snapshot stays).
+     *
+     * @returns Whether a snapshot was dropped
+     */
+    private dropSnapshotForCarriedState;
+    /** Records that still fold against a row snapshot (approximate, RT-68). */
+    listSnapshotRecords(tx: Transaction): Promise<Array<{
+        collection: string;
+        recordId: string;
+    }>>;
+    /**
+     * After a full resync, a record whose log holds its insert again no longer needs
+     * its row snapshot: drop it and re-fold the record from base and log (RT-68).
+     *
+     * @returns Whether the snapshot was dropped
+     */
+    settleSnapshotInTx(tx: Transaction, collection: string, recordId: string): Promise<boolean>;
+    /**
+     * Fold a local-only provisional side effect (RT-69) into its record: stored apart
+     * from the log (never sequenced, never uploaded) and kept until the real copy of
+     * the effect arrives or the delivery stream catches up.
+     *
+     * @param parentId - The remote operation that caused it (the parent delete)
+     */
+    applyProvisionalInTx(tx: Transaction, op: Operation, parentId: string): Promise<void>;
+    /**
+     * Remove provisional effects of a record (those caused by one of `parentIds`, or
+     * all of them when null). The caller re-folds the record.
+     *
+     * @returns How many were removed
+     */
+    deleteProvisional(tx: Transaction, collection: string, recordId: string, parentIds: readonly string[] | null): Promise<number>;
+    /** Records with provisional effects. */
+    listProvisionalRecords(tx: Transaction): Promise<Array<{
+        collection: string;
+        recordId: string;
+    }>>;
+    private loadProvisional;
+    saveState(tx: Transaction, state: FoldState): Promise<void>;
+    saveBase(tx: Transaction, state: FoldState): Promise<void>;
+    /** Join `addition` into the record's base state. */
+    joinIntoBase(tx: Transaction, addition: FoldState): Promise<void>;
+    /**
+     * Write the row of a record from its fold state.
+     *
+     * - No insert merged: no row (an existing one is hidden).
+     * - Otherwise the row holds the fold's values (also while deleted: a tombstone
+     *   keeps its last values), `_deleted` from the record's liveness, and versions
+     *   from the state: `_version` / `_updated_at` = newest operation, `_created_at` =
+     *   creation, `_field_versions` = each field's newest write.
+     * - Only `fields` are written to an existing row; columns the fold never wrote
+     *   (a column a schema migration added with a default, a local-only backfill)
+     *   keep their stored value.
+     * - A row hidden by a scope retraction stays hidden unless `clearRetraction`
+     *   (a scope-entry insert) is set.
+     */
+    materializeRow(tx: Transaction, state: FoldState, fields: MaterializeFields, options: {
+        clearRetraction: boolean;
+        absent?: boolean;
+    }): Promise<void>;
+    /**
+     * Load the record's state; rebuild it from base + log when it is missing or in
+     * another format version. `rebuilt` tells the caller to rewrite the whole row.
+     */
+    private loadOrRebuild;
+    private hasStateRow;
+    private readStateRow;
+    private toMergeTraces;
+}
+
+/**
+ * How a local node's {@link LocalNodeRecord.principal} was learned (RT-50):
+ *
+ * - `fresh`: the node had no writes when it was bound to the signed-in user, so every
+ *   write under it was made by that user.
+ * - `server`: a sync handshake as the node was accepted for that user (the server's node
+ *   claims are authoritative).
+ * - `app`: the app assigned a held node to the signed-in user
+ *   (`app.sync.assignHeld`). A guess: cleared if the server refuses the node for them.
+ */
+type LocalNodeBinding = 'fresh' | 'server' | 'app';
+/** A terminal rejection to record (RT-36). */
+interface TerminalRejection {
+    operationId: string;
+    /** Authoring node and sequence, when known (null for rows seeded from the old list). */
+    nodeId: string | null;
+    sequenceNumber: number | null;
+    code: string;
+    rejectedAt: number;
+}
+/** A node id this database authored operations under (RT-38, RT-40). */
+interface LocalNodeRecord {
+    nodeId: string;
+    /** Wall-clock time (ms) the node was registered. Display only. */
+    createdAt: number;
+    /** A sync handshake as this node was accepted at least once. */
+    accepted: boolean;
+    /**
+     * The server refused this node (`NODE_ID_CLAIMED`) after it had been accepted: it
+     * belongs to a principal that is not signed in. Its unsynced operations are held for
+     * that principal, never uploaded under another one.
+     */
+    held: boolean;
+    /** {@link ACCEPTED_CYCLE_META_KEY} value when the server last refused it, or null. */
+    refusedCycle: number | null;
+    /**
+     * The signed-in user the node's writes belong to (RT-42), or null when the app never
+     * told the store who was signed in while it was in use. A node bound to one user is
+     * never used for, uploaded under, or adopted by another user's session.
+     */
+    principal: string | null;
+    /**
+     * How {@link principal} was learned (RT-50), or null when unbound, or bound by a release
+     * that did not record it (treated as a guess).
+     */
+    binding: LocalNodeBinding | null;
+    /**
+     * Users the server refused this UNBOUND node for (`NODE_ID_CLAIMED`, RT-50): it is
+     * not theirs, so it is never tried again on their sessions. An unbound node that was
+     * accepted before belongs to whichever user the server accepts it for.
+     */
+    refusedPrincipals: string[];
+}
+/** A parked adoption (RT-46): the node made no upload progress in its last session. */
+interface ParkedAdoption {
+    /** {@link AdoptionSchedule.progress} when it was parked: retried once it moves. */
+    progressMark: number;
+    /** Wall-clock time (ms) after which it is retried anyway. Scheduling only. */
+    untilMs: number;
+    /** Consecutive parks (backoff exponent). */
+    count: number;
+    /** Wall-clock time (ms) it was parked. Scheduling only. */
+    parkedAtMs: number;
+}
+/**
+ * Which local nodes' adoptions are parked (RT-46), and a counter of upload progress on
+ * this database: a parked node is retried once anything else uploaded (its deferral may
+ * have depended on it) or after its backoff.
+ */
+interface AdoptionSchedule {
+    progress: number;
+    parked: Record<string, ParkedAdoption>;
+}
+/** Read access to a database (an open adapter, or a reader handed to a delete check). */
+interface DatabaseQuery {
+    query<T>(sql: string, params?: unknown[]): Promise<T[]>;
+}
+/**
+ * Whether any local node has operations above its contiguous acknowledged prefix that
+ * the server did not refuse for good (RT-41): the authoritative "unsynced" (W3), which
+ * the outbound queue only approximates. A local node is one in the registry, the
+ * database's node id, or the node of the legacy prefix key; a node with no recorded
+ * prefix counts from 0. Works on a database no store has opened in this release.
+ */
+declare function hasUnsyncedOwnOperations(db: DatabaseQuery): Promise<boolean>;
+
+/**
+ * Called inside the write transaction for every local delete, after the delete
+ * operation is built and before referential side effects run. Lets the unified
+ * apply pipeline run its referential checks (and emit their traces) against the
+ * rows the transaction sees. Throwing aborts the whole write.
+ */
+type LocalDeleteHook = (operation: Operation, tx: Transaction) => Promise<void>;
+/**
+ * Everything the single local write path needs to build and persist an
+ * operation inside a storage transaction. One environment serves single-record
+ * writes, `app.transaction` commits and referential cascades, so every local
+ * operation is built the same way (W6).
+ */
+interface WriteEnv {
+    readonly schema: SchemaDefinition;
+    readonly clock: HybridLogicalClock;
+    readonly nodeId: string;
+    readonly relationEnforcer: RelationEnforcer | null;
+    readonly secretKeyProvider?: SecretKeyProvider;
+    /** Shared by every operation of an `app.transaction` / `app.mutation` commit. */
+    readonly transactionId?: string;
+    /** Human-readable mutation name propagated to every operation (DevTools). */
+    readonly mutationName?: string;
+    /** See {@link LocalDeleteHook}. */
+    readonly beforeLocalDelete?: LocalDeleteHook;
+    /**
+     * The W7 record fold. When set, a local write appends its operation and then
+     * merges it into the record's fold state, which re-materializes the row (the
+     * same path remote operations take). Absent only under
+     * `experimental.legacyMerge` (and while a pre-W7 database is migrated, before its
+     * re-materialization): the row is then written directly, as in beta.12.
+     */
+    readonly fold?: RecordFolder;
+    /**
+     * Largest operation a local write may produce (RT-86), the server's
+     * `maxOperationBytes`. Default `DEFAULT_MAX_OPERATION_BYTES` (256 KiB).
+     */
+    readonly maxOperationBytes?: number;
+    /**
+     * Throws when local writes are not allowed right now: the store's pinned node
+     * belongs to another user than the one signed in (F9). Called before every local
+     * operation is built.
+     */
+    readonly assertLocalWriteAllowed?: () => void;
+}
+/**
+ * Causal bookkeeping for the operations built inside ONE storage transaction.
+ *
+ * Dependencies are computed from the committed causal heads (the shared
+ * {@link CausalTracker}) overlaid with the operations already built in this
+ * transaction. Heads are published to the shared tracker only after the
+ * transaction commits, so a rolled-back write never leaves a dependency on an
+ * operation that does not exist.
+ */
+declare class CausalScope {
+    private readonly tracker;
+    /** When true, every operation also depends on the previous one in this scope. */
+    private readonly chainOperations;
+    private readonly lastByCollection;
+    private lastInScope;
+    private readonly recorded;
+    constructor(tracker: CausalTracker | null, 
+    /** When true, every operation also depends on the previous one in this scope. */
+    chainOperations: boolean);
+    /**
+     * Direct causal parents for the next operation in `collection`.
+     *
+     * @param collection - Collection of the operation being built
+     * @param extra - Explicit parents (e.g. the delete that caused a cascade)
+     */
+    depsFor(collection: string, extra?: readonly string[]): string[];
+    /** Record an operation built in this scope. */
+    record(collection: string, operationId: string): void;
+    /** Publish this scope's heads to the shared tracker. Call only after commit. */
+    publish(): void;
+}
+/**
+ * The sequence-number block of ONE write transaction.
+ *
+ * The first number is reserved with one `UPSERT ... RETURNING` on
+ * `_kora_version_vector`, inside the transaction; later numbers continue the block
+ * in memory, and {@link SequenceBlock.close} persists the block's end with one
+ * write before the transaction commits. Write transactions are serialized and no
+ * code path allocates numbers outside one, so the block is contiguous and never
+ * shared; the UNIQUE `(node_id, sequence_number)` index on every op table is the
+ * backstop. A rollback discards the reservation with everything else.
+ */
+declare class SequenceBlock {
+    private readonly tx;
+    private readonly nodeId;
+    private last;
+    private persisted;
+    constructor(tx: Transaction, nodeId: string);
+    /** The next number of the block. */
+    take(): Promise<number>;
+    /** Persist the end of the block. Must run inside the transaction, before commit. */
+    close(): Promise<void>;
+}
+/**
+ * The per-transaction state of a local write: the transaction handle, its
+ * sequence block and its causal scope. Every operation built in one transaction
+ * takes the next number of the same contiguous block.
+ */
+interface WriteScope {
+    readonly tx: Transaction;
+    readonly sequence: SequenceBlock;
+    readonly causal: CausalScope;
+}
+
+/**
+ * A resolved relation reference: describes a relation that points TO a given collection.
+ * When a record in `targetCollection` is deleted, we must handle records in
+ * `sourceCollection` that reference it via `foreignKeyField`.
+ */
+interface IncomingRelation {
+    /** Name of the relation in the schema */
+    relationName: string;
+    /** Collection that holds the foreign key (the "from" side) */
+    sourceCollection: string;
+    /** Field in the source collection that references the target */
+    foreignKeyField: string;
+    /** What to do when the referenced record is deleted */
+    onDelete: OnDeleteAction;
+    /** The full relation definition */
+    relation: RelationDefinition;
+}
+
+/**
+ * Configuration for the RelationEnforcer.
+ */
+interface RelationEnforcerConfig {
+    schema: SchemaDefinition;
+}
+/**
+ * Result of enforcing referential integrity on a delete operation.
+ * Contains all additional operations that were created as side effects
+ * (cascaded deletes and set-null updates).
+ */
+interface EnforcementResult {
+    /** Additional operations created by cascading deletes and set-null updates */
+    operations: Operation[];
+}
+/**
+ * Enforces referential integrity constraints during local delete operations.
+ *
+ * When a record is deleted, this enforcer checks all relations that reference
+ * the deleted record's collection and applies the appropriate onDelete policy:
+ *
+ * - **cascade**: Recursively deletes all referencing records
+ * - **set-null**: Sets the foreign key to null on all referencing records
+ * - **restrict**: Throws a ReferentialIntegrityError if any references exist
+ * - **no-action**: Does nothing (the foreign key is left dangling)
+ *
+ * The enforcer runs inside the delete's write transaction and writes every side
+ * effect through the single local write path (`writeDeleteInTx` /
+ * `writeUpdateInTx`), so cascaded operations reserve their sequence numbers in
+ * the same contiguous block as the parent and carry per-field version stamps
+ * (STORE-2, STORE-3). Every generated operation depends causally on the delete
+ * that caused it.
+ *
+ * @example
+ * ```typescript
+ * const enforcer = new RelationEnforcer({ schema })
+ * // inside a write transaction, after building the parent delete operation:
+ * const result = await enforcer.enforceDelete('projects', 'proj-1', scope, env, deleteOp.id)
+ * // result.operations contains any cascaded delete/update ops
+ * ```
+ */
+declare class RelationEnforcer {
+    private readonly lookup;
+    constructor(config: RelationEnforcerConfig);
+    /**
+     * Enforce referential integrity for a record being deleted.
+     *
+     * @param collection - The collection the deleted record belongs to
+     * @param recordId - The ID of the deleted record
+     * @param scope - The active write scope (transaction + causal scope)
+     * @param env - The write environment of the delete
+     * @param parentOpId - Id of the delete operation; every side effect depends on it
+     * @returns All additional operations created as side effects
+     * @throws {ReferentialIntegrityError} If a 'restrict' policy is violated
+     */
+    enforceDelete(collection: string, recordId: string, scope: WriteScope, env: WriteEnv, parentOpId: string): Promise<EnforcementResult>;
+    /**
+     * Enforce a single relation's onDelete policy.
+     */
+    private enforceRelation;
+    /**
+     * Cascade: delete every live record that references the deleted record. Each
+     * cascaded delete runs the full delete path, so it recurses into its own
+     * referencing records.
+     */
+    private enforceCascade;
+    /**
+     * Set-null: set the foreign key to null on every live referencing record.
+     */
+    private enforceSetNull;
+    /**
+     * Restrict: refuse the delete if any referencing records exist.
+     */
+    private enforceRestrict;
+    /** Ids of live records referencing `deletedRecordId`, in id order (deterministic). */
+    private findReferencing;
+    /**
+     * Get the relation lookup map for external use (e.g., by the merge engine).
+     */
+    getRelationLookup(): Map<string, IncomingRelation[]>;
+}
+
+/**
+ * Callback invoked after a mutation so the Store can notify subscriptions.
+ */
+type MutationCallback = (collection: string, operation: Operation) => void;
+/**
+ * Collection provides CRUD operations on a single schema collection.
+ * Delegates to {@link LocalMutationHandler} when configured (unified apply pipeline),
+ * otherwise uses shared mutation executors directly.
+ */
+declare class Collection {
+    private readonly name;
+    private readonly definition;
+    private readonly schema;
+    private readonly adapter;
+    private clock;
+    private nodeId;
+    private readonly onMutation;
+    private relationEnforcer;
+    private mutationHandler;
+    private causalTracker;
+    private readonly secretKeyProvider?;
+    private readonly onStorageError?;
+    private readonly fold?;
+    private readonly maxOperationBytes?;
+    private readonly assertLocalWriteAllowed?;
+    constructor(name: string, definition: CollectionDefinition, schema: SchemaDefinition, adapter: StorageAdapter, clock: HybridLogicalClock, nodeId: string, onMutation: MutationCallback, relationEnforcer: RelationEnforcer | null, mutationHandler: LocalMutationHandler | null, causalTracker: CausalTracker | null, secretKeyProvider?: SecretKeyProvider | undefined, onStorageError?: ((error: unknown) => void) | undefined, fold?: (() => RecordFolder | undefined) | undefined, maxOperationBytes?: number | undefined, assertLocalWriteAllowed?: (() => void) | undefined);
+    /**
+     * Point this collection at the store's new device identity after a node-id
+     * rotation (RT-21). Internal: called by the owning Store only.
+     *
+     * @internal
+     */
+    rebindNode(clock: HybridLogicalClock, nodeId: string, relationEnforcer: RelationEnforcer | null, causalTracker: CausalTracker | null): void;
+    private mutationContext;
+    insert(data: Record<string, unknown>): Promise<CollectionRecord>;
+    findById(id: string): Promise<CollectionRecord | null>;
+    update(id: string, data: Record<string, unknown>): Promise<CollectionRecord>;
+    delete(id: string): Promise<void>;
+    getName(): string;
+    getDefinition(): CollectionDefinition;
+    /** Replace the mutation handler (e.g. after ApplyPipeline is wired in createApp). */
+    setMutationHandler(handler: LocalMutationHandler | null): void;
+}
+
+/**
+ * Shared context for executing local collection mutations.
+ *
+ * Extends the {@link WriteEnv} of the single local write path with the target
+ * collection and the post-commit plumbing. There is deliberately no way to
+ * allocate a sequence number outside a write transaction: every local operation
+ * reserves its number inside the transaction that persists it (W6).
+ */
+interface LocalMutationContext extends WriteEnv {
+    readonly collection: string;
+    readonly definition: CollectionDefinition;
+    readonly adapter: StorageAdapter;
+    /** Called once per committed operation, after the storage transaction commits. */
+    readonly onMutation: MutationCallback;
+    readonly causalTracker: CausalTracker | null;
+    /** Additional parent op ids (e.g. referential cascade from a delete). */
+    readonly extraCausalDeps?: string[];
+    /**
+     * Called when a write transaction fails, before the error propagates (the
+     * store maps out-of-space errors to `store:quota-exceeded`).
+     */
+    readonly onStorageError?: (error: unknown) => void;
+}
+
+/**
+ * Result of building a SQL query: the parameterized SQL string and its bound values.
+ */
+interface SqlQuery {
+    sql: string;
+    params: unknown[];
+}
+/**
+ * Build a SELECT query from a QueryDescriptor.
+ * Automatically adds `WHERE _deleted = 0` to exclude soft-deleted records.
+ *
+ * @param descriptor - The query descriptor
+ * @param fields - The field descriptors from the collection schema
+ * @returns A parameterized SQL query
+ */
+declare function buildSelectQuery(descriptor: QueryDescriptor, fields: Record<string, FieldDescriptor>): SqlQuery;
+/**
+ * Build a COUNT query from a QueryDescriptor.
+ * Automatically adds `WHERE _deleted = 0`.
+ *
+ * @param descriptor - The query descriptor
+ * @param fields - The field descriptors from the collection schema
+ * @returns A parameterized SQL query that returns { count: number }
+ */
+declare function buildCountQuery(descriptor: QueryDescriptor, fields: Record<string, FieldDescriptor>): SqlQuery;
+/**
+ * Build an INSERT query for a collection record.
+ *
+ * @param collection - The collection name
+ * @param record - The record data (already serialized with id, _created_at, _updated_at)
+ * @returns A parameterized SQL query
+ */
+declare function buildInsertQuery(collection: string, record: Record<string, unknown>): SqlQuery;
+/**
+ * Build an UPDATE query for a collection record.
+ *
+ * @param collection - The collection name
+ * @param id - The record ID
+ * @param changes - The fields to update (already serialized)
+ * @returns A parameterized SQL query
+ */
+declare function buildUpdateQuery(collection: string, id: string, changes: Record<string, unknown>): SqlQuery;
+/**
+ * Build a soft-delete query (SET _deleted = 1).
+ *
+ * @param collection - The collection name
+ * @param id - The record ID
+ * @param updatedAt - The timestamp to set on _updated_at
+ * @returns A parameterized SQL query
+ */
+declare function buildSoftDeleteQuery(collection: string, id: string, updatedAt: number, version?: string): SqlQuery;
+/**
+ * Build an UPDATE that applies only when the row is missing or older than `remoteVersion`
+ * (serialized HLC). Prevents stale remote sync from overwriting newer local materialized state.
+ */
+declare function buildLwwUpdateQuery(collection: string, id: string, changes: Record<string, unknown>, remoteVersion: string): SqlQuery;
+/**
+ * Build a soft-delete that applies only when the row is older than `remoteVersion`.
+ */
+declare function buildLwwSoftDeleteQuery(collection: string, id: string, updatedAt: number, version: string): SqlQuery;
+/**
+ * Build a WHERE clause from conditions, validating field names against the schema.
+ *
+ * @param where - The where conditions
+ * @param fields - The field descriptors from the collection schema
+ * @returns The SQL WHERE clause string and params, or null if no conditions
+ */
+declare function buildWhereClause(where: Record<string, unknown>, fields: Record<string, FieldDescriptor>): SqlQuery | null;
+/**
+ * Record metadata exposed on every record under a camelCase name and backed by a
+ * system column (STORE-11): `where({ updatedAt: { $gt: t } })` and
+ * `orderBy('createdAt', 'desc')` filter and sort on these columns. A schema field
+ * declared with the same name wins and its own column is used instead.
+ */
+declare const VIRTUAL_TIMESTAMP_FIELDS: Readonly<{
+    readonly createdAt: "_created_at";
+    readonly updatedAt: "_updated_at";
+}>;
+/** Name of a virtual record-metadata field usable in `where` and `orderBy`. */
+type VirtualTimestampField = keyof typeof VIRTUAL_TIMESTAMP_FIELDS;
+/** Every virtual record-metadata field name, for typing `where` / `orderBy` keys. */
+declare const VIRTUAL_TIMESTAMP_FIELD_NAMES: readonly VirtualTimestampField[];
+
+export { type AdoptionSchedule as A, Collection as C, type DatabaseQuery as D, type LocalMutationContext as L, type ParkedAdoption as P, RelationEnforcer as R, type SqlQuery as S, type TerminalRejection as T, VIRTUAL_TIMESTAMP_FIELDS as V, buildInsertQuery as a, buildCountQuery as b, buildLwwSoftDeleteQuery as c, buildLwwUpdateQuery as d, buildSelectQuery as e, buildSoftDeleteQuery as f, buildUpdateQuery as g, buildWhereClause as h, hasUnsyncedOwnOperations as i, type LocalDeleteHook as j, RecordFolder as k, type LocalNodeRecord as l, VIRTUAL_TIMESTAMP_FIELD_NAMES as m, type VirtualTimestampField as n, mergeYjsUpdates as o };