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

package/dist/index.d.ts

@@ -1,7 +1,9 @@
-import { R as RandomSource, B as BlobRef, C as CollectionDefinition, A as AtomicOpType, a as AtomicOp, F as FieldBuilder, b as CustomResolver, M as MigrationDefinition, S as SchemaDefinition, c as RelationDefinition, O as OperationType, E as EnumFieldBuilder, J as JsonFieldBuilder, d as ArrayFieldBuilder, e as FieldKind, f as Operation, V as VersionVector, g as MigrationStep, h as StateMachineConstraint, T as TransitionMap, i as TransitionValidationResult } from './events-D7JCtQSD.js';
-export { j as CONNECTION_QUALITIES, k as ConnectionQuality, l as Constraint, m as FieldDescriptor, n as FieldMergeStrategy, H as HLCTimestamp, K as KoraEvent, o as KoraEventByType, p as KoraEventEmitter, q as KoraEventListener, r as KoraEventType, s as MERGE_STRATEGIES, t as MergeStrategy, u as MergeTrace, v as MigrationBuilder, w as OnDeleteAction, x as OperationInput, y as RelationType, z as RollbackBuilder, D as SecretMode, G as SequenceConfig, I as StateMachineDefinition, L as SyncDiagnosticsSnapshot, N as SyncRuleDefinition, P as TimeSource, Q as migrate, U as t } from './events-D7JCtQSD.js';
-export { H as HybridLogicalClock, M as MAX_LOGICAL, c as createOperation, i as isValidOperation, v as verifyOperationIntegrity } from './operation-BX4ok7U4.js';
-export { S as ScopeMap, b as buildScopeMap } from './build-scope-map-Cv5HfCQP.js';
+import { R as RandomSource, B as BlobRef, C as CollectionDefinition, O as OperationInput, A as AtomicOp, a as Operation, H as HLCTimestamp, S as SchemaDefinition, M as MergeTrace, F as FieldBuilder, b as CustomResolver, c as MigrationDefinition, d as FieldDescriptor, e as OperationType, V as VersionVector, f as MigrationStep, g as StateMachineConstraint, T as TransitionMap, h as TransitionValidationResult } from './events-BSU-0z5O.js';
+export { i as ArrayAtomicOpSentinel, j as ArrayFieldBuilder, k as AtomicOpSentinel, l as AtomicOpType, m as BackfillOptions, n as CONNECTION_QUALITIES, o as ConnectionQuality, p as Constraint, E as EncryptedEnvelopeField, q as EncryptedOperationEnvelope, r as EnumFieldBuilder, s as FieldInput, t as FieldKind, u as FieldKindToType, v as FieldMap, w as FieldMergeStrategy, x as FieldOutput, y as FieldTypeInfo, I as InferFieldInput, z as InferFieldType, D as InferInsert, G as InferInsertInput, J as InferRecord, K as InferRecordField, L as InferUpdate, N as InferUpdateField, P as InferUpdateInput, Q as JsonFieldBuilder, U as KoraEvent, W as KoraEventByType, X as KoraEventEmitter, Y as KoraEventListener, Z as KoraEventType, _ as MERGE_STRATEGIES, $ as MergeStrategy, a0 as MigrationBuilder, a1 as NumericAtomicOpSentinel, a2 as ObjectFieldBuilder, a3 as ObjectFieldValue, a4 as OnDeleteAction, a5 as RelationDefinition, a6 as RelationType, a7 as RichtextInput, a8 as RollbackBuilder, a9 as ScalarFieldBuilder, aa as ScalarFieldKind, ab as SecretFieldBuilder, ac as SecretMode, ad as SequenceConfig, ae as Simplify, af as StateMachineDefinition, ag as SyncDiagnosticsSnapshot, ah as SyncRuleDefinition, ai as TimeSource, aj as applyAtomicOp, ak as isAtomicOp, al as migrate, am as op, an as resolveAtomicOp, ao as t, ap as toAtomicOp } from './events-BSU-0z5O.js';
+import { F as FoldState, a as FoldOptions, b as FoldRecordResult, c as FoldFieldVersions, M as MergeOpResult, O as OperationTransform, d as FoldTrace } from './sql-gen-ByOZIQU-.js';
+export { C as CounterFieldState, e as CreateOperationOptions, D as DEFAULT_OPERATION_HASH_VERSION, E as ElementSetFieldState, f as ElementState, g as ExtremumFieldState, h as FOLD_STATE_VERSION, i as FieldLogEntry, j as FieldState, k as FoldFieldKind, l as FoldTraceMode, H as HashableOperation, m as HybridLogicalClock, K as KeyMapFieldState, n as KeyState, o as MAX_LOGICAL, p as OperationHashVersion, R as RegisterFieldState, q as ResolverFieldState, r as RichtextFieldState, s as RichtextSubsumes, t as RichtextUpdateMerger, S as Stamp, u as computeOperationId, v as createOperation, w as generateFullDDL, x as generateSQL, y as isValidOperation, z as verifyOperationId, A as verifyOperationIntegrity } from './sql-gen-ByOZIQU-.js';
+import { S as ScopeMap } from './build-scope-map-CIFa58oA.js';
+export { b as buildScopeMap } from './build-scope-map-CIFa58oA.js';
 
 /**
  * Base error class for all Kora errors.
@@ -28,6 +30,18 @@ declare class SchemaValidationError extends KoraError {
 declare class OperationError extends KoraError {
     constructor(message: string, context?: Record<string, unknown>);
 }
+/**
+ * Thrown by the local write path when an operation would exceed `maxOperationBytes`
+ * (RT-86): the server refuses such an operation, so the write is refused before it is
+ * accepted, with nothing written.
+ */
+declare class OperationTooLargeError extends KoraError {
+    readonly collection: string;
+    readonly recordId: string;
+    readonly bytes: number;
+    readonly maxBytes: number;
+    constructor(collection: string, recordId: string, bytes: number, maxBytes: number);
+}
 /**
  * Thrown when a merge conflict cannot be automatically resolved.
  */
@@ -325,131 +339,113 @@ declare function isApplyFailure(result: ApplyResult): boolean;
 declare function defaultApplyFailureReason(result: Exclude<ApplyResult, 'applied' | 'duplicate'>, overrides?: Partial<ApplyFailureReason>): ApplyFailureReason;
 
 /**
- * Atomic field operations for intent-preserving updates.
- *
- * Instead of read-modify-write patterns, developers express intent:
- * ```typescript
- * await app.stock.update(id, { quantity: op.increment(-5) })
- * ```
- *
- * The operation intent is preserved in the Operation for merge:
- * concurrent increments compose (sum of deltas) instead of LWW.
- */
-
-/**
- * Sentinel marker for detecting atomic op objects in update data.
- * Uses Symbol.for() so the sentinel survives module boundary crossings.
- */
-declare const KORA_ATOMIC_OP: unique symbol;
-/** String key used for the sentinel symbol — exported for internal use */
-declare const KORA_ATOMIC_OP_KEY: typeof KORA_ATOMIC_OP;
-/**
- * Sentinel object returned by op.* helpers.
- * Detected by Collection.update() and resolved to concrete values.
+ * Thrown when an operation (or a record value) holds a value that has no canonical
+ * JSON form: the op log and the wire are JSON, so such a value would be stored and
+ * synced as something other than what was written and hashed.
  */
-interface AtomicOpSentinel {
-    readonly [KORA_ATOMIC_OP_KEY]: true;
-    readonly type: AtomicOpType;
-    readonly value: unknown;
+declare class NonCanonicalValueError extends KoraError {
+    readonly path: string;
+    readonly receivedType: string;
+    constructor(message: string, path: string, receivedType: string);
 }
 /**
- * Type guard: checks whether a value is an atomic op sentinel.
- *
- * @param value - Any value to check
- * @returns true if the value is an AtomicOpSentinel
- */
-declare function isAtomicOp(value: unknown): value is AtomicOpSentinel;
-/**
- * Apply a plain atomic op (`{ type, value }`) to a current value, producing the
- * concrete result. This is the single source of truth for atomic-op semantics:
- * {@link resolveAtomicOp} (sentinel form, used on the write path) delegates here,
- * and the server's materialization replays stored atomic ops through it, so the
- * server's materialized view composes concurrent atomic writes identically to the
- * client. Folding this over a field's writes in HLC order yields, for a same-type
- * atomic chain, exactly the composed intent (sum of increments, max of maxes, ...).
- *
- * @param currentValue - The current value of the field
- * @param atomicOp - The atomic op to apply (type + operand)
- * @returns The resulting concrete value
- */
-declare function applyAtomicOp(currentValue: unknown, atomicOp: AtomicOp): unknown;
-/**
- * Resolve an atomic op sentinel against a current value to produce a concrete result.
- *
- * @param currentValue - The current value of the field in the database
- * @param sentinel - The atomic op sentinel from the developer's update call
- * @returns The resolved concrete value
- */
-declare function resolveAtomicOp(currentValue: unknown, sentinel: AtomicOpSentinel): unknown;
-/**
- * Atomic operation helpers. Use these in collection.update() calls
- * to express intent-preserving mutations.
- *
- * @example
- * ```typescript
- * import { op } from 'korajs'
- *
- * // Increment a counter (works correctly with concurrent updates)
- * await app.stock.update(id, { quantity: op.increment(-5) })
- *
- * // Keep the maximum value
- * await app.scores.update(id, { highScore: op.max(newScore) })
- *
- * // Append to an array
- * await app.todos.update(id, { tags: op.append('urgent') })
- * ```
- */
-declare const op: {
-    /**
-     * Increment a number field by the given amount.
-     * Concurrent increments compose: the sum of all deltas is applied to the base.
-     *
-     * @param n - The amount to increment (use negative values to decrement)
-     */
-    increment(n: number): AtomicOpSentinel;
-    /**
-     * Decrement a number field by the given amount.
-     * Syntactic sugar for `op.increment(-n)`.
-     *
-     * @param n - The amount to decrement
-     */
-    decrement(n: number): AtomicOpSentinel;
-    /**
-     * Set the field to the maximum of the current value and the given value.
-     * Concurrent max operations take the maximum of all values.
-     *
-     * @param n - The value to compare against the current value
-     */
-    max(n: number): AtomicOpSentinel;
-    /**
-     * Set the field to the minimum of the current value and the given value.
-     * Concurrent min operations take the minimum of all values.
-     *
-     * @param n - The value to compare against the current value
-     */
-    min(n: number): AtomicOpSentinel;
-    /**
-     * Append an item to an array field.
-     * Concurrent appends include all appended items.
-     *
-     * @param item - The item to append to the array
-     */
-    append(item: unknown): AtomicOpSentinel;
-    /**
-     * Remove an item from an array field (by value equality).
-     * Concurrent removes of the same item are idempotent.
-     *
-     * @param item - The item to remove from the array
-     */
-    remove(item: unknown): AtomicOpSentinel;
-};
+ * The one canonical form of an operation body (RT-72 family: RT-79, RT-80, RT-83).
+ *
+ * The op log, the wire (JSON and protobuf, whose data is JSON) and every store hold an
+ * operation as JSON. An operation's id is a hash of its body. So the body is put in its
+ * canonical form ONCE, when the operation is created (and when a legacy operation is
+ * ingested or rebuilt), and the canonical body is what is hashed, stored, sent and
+ * folded: the four can never disagree, by construction.
+ *
+ * | Value                                   | Canonical form                                  |
+ * |-----------------------------------------|-------------------------------------------------|
+ * | `undefined` member of an insert's data  | absent                                          |
+ * | `undefined` member of an update's data  | `null`: the field is CLEARED (beta.12 meaning)  |
+ * | `undefined` member of an update's `previousData` | `null` (the field held no value)       |
+ * | `undefined` member inside an object value | absent (as JSON drops it); a `t.json()` field refuses it at validation |
+ * | `undefined` array element               | `null` (as JSON writes it)                      |
+ * | `undefined` atomic op                   | absent                                          |
+ * | `-0`                                    | `0` (JSON writes `0`)                           |
+ * | valid `Date`                            | its ISO 8601 string (`toISOString()`), as JSON  |
+ * | `Uint8Array` / `ArrayBuffer`            | `{ $koraBytes: <base64> }` (the op-log binary form) |
+ * | plain object (`Object.prototype` or `null` prototype) | plain object, members canonical   |
+ * | array (dense)                           | array, elements canonical                       |
+ * | string, finite number, boolean, `null`  | itself                                          |
+ * | invalid `Date`, `NaN`, `±Infinity`, `BigInt`, function, symbol, `Map`, `Set`, `WeakMap`, `RegExp`, `Promise`, any other class instance, an object with a `toJSON` method, an own `__proto__` key, a circular reference | refused: {@link NonCanonicalValueError} naming the path and the fix |
+ *
+ * Canonicalization is idempotent: a canonical body is returned unchanged (same
+ * references where nothing changed).
+ *
+ * @param input - The operation body (as given to `createOperation`, or a stored operation)
+ * @returns The body with `data`, `previousData` and `atomicOps` canonical
+ * @throws {NonCanonicalValueError} For a value with no canonical form
+ */
+declare function canonicalizeOperationBody<T extends CanonicalizableBody>(input: T): T;
+/** The members of an operation body that {@link canonicalizeOperationBody} reads. */
+interface CanonicalizableBody {
+    type: OperationInput['type'];
+    collection: string;
+    recordId: string;
+    data: Record<string, unknown> | null;
+    previousData: Record<string, unknown> | null;
+    atomicOps?: Record<string, AtomicOp>;
+}
 /**
- * Extract the serializable AtomicOp from a sentinel (strips the Symbol marker).
- *
- * @param sentinel - The atomic op sentinel
- * @returns A plain object suitable for JSON serialization
- */
-declare function toAtomicOp(sentinel: AtomicOpSentinel): AtomicOp;
+ * The canonical form of one value inside an operation body or a record field (see
+ * {@link canonicalizeOperationBody} for the table). Exported so schema validation
+ * produces exactly the values an operation will carry.
+ *
+ * @param value - Any value
+ * @param path - Where the value is, for the error message (e.g. `notes.extra.when`)
+ * @returns The canonical value (the same reference when it already is)
+ * @throws {NonCanonicalValueError} For a value with no canonical form
+ */
+declare function canonicalValue(value: unknown, path: string): unknown;
+/**
+ * A legacy update in its canonical body when its id PROVES the beta.12 clear (RT-85):
+ * the id is the content hash of the body with every `previousData` key absent from
+ * `data` restored as `null` (version 1, or version 2 with a lost declaration), and not
+ * of the body as it is. Such an id can only come from a writer that hashed the clear,
+ * so the restored body is the one its author wrote and applied; a body a schema
+ * transform or anything else rewrote never proves it.
+ *
+ * Used where a legacy body enters a replica without a known provenance: a device's
+ * inbound delivery, and the one-time canonicalization of stored logs. The server's
+ * ingest of a protocol-1 upload applies the same rule (plus the unverifiable
+ * protocol-1 case, for the session's own node).
+ *
+ * @param op - Any operation
+ * @returns The canonical operation, or `op` itself when nothing is proven
+ */
+declare function canonicalizeProvenLegacyClear<T extends Operation>(op: T): Promise<T>;
+/**
+ * The canonical body of a legacy (version-1, beta.12) update (RT-71, RT-83): every
+ * `previousData` key absent from `data` is a clear, restored as `null`. beta.12 wrote
+ * `previousData[key]` for every key it validated, so such a key held `undefined` in
+ * `data`: beta.12 hashed it as `null`, applied it as a cleared field, and its JSON log
+ * and upload dropped it. `null` and `undefined` hash identically under version 1, so
+ * the id is unchanged.
+ *
+ * Applied ONCE, where a genuine beta.12 body is identified (RT-85), never at fold time:
+ * the server's ingest of a protocol-1 upload, a device's own beta.12 log at the
+ * upgrade, and any body whose id proves the clear
+ * ({@link canonicalizeProvenLegacyClear}). The result is stored, so the server, peers
+ * and the upgraded writer fold the same body. A no-op
+ * for anything else (a declared version 2, an envelope, an insert or delete, an update
+ * whose data covers its previousData). Idempotent.
+ *
+ * @param op - Any operation
+ * @returns The operation with the restored data, or `op` itself
+ */
+declare function canonicalizeLegacyOperation<T extends LegacyBody>(op: T): T;
+/** The members of an operation {@link canonicalizeLegacyOperation} reads. */
+interface LegacyBody {
+    type: Operation['type'];
+    data: Record<string, unknown> | null;
+    previousData: Record<string, unknown> | null;
+    hashVersion?: Operation['hashVersion'];
+    encrypted?: Operation['encrypted'];
+}
 
 /** One operation's contribution to a record's materialized state. */
 interface ReplayOperation {
@@ -462,7 +458,35 @@ interface ReplayOperation {
      * last-write-wins.
      */
     atomicOps?: Record<string, AtomicOp> | null;
+    /**
+     * For updates: the values the writer saw before its change. Array fields use it
+     * as the base of a three-way set merge (see {@link mergeArraySet}). Absent means
+     * array fields resolve by last-write-wins.
+     */
+    previousData?: Record<string, unknown> | null;
 }
+/**
+ * Three-way set merge for array fields, shared by the client merge engine
+ * (`addWinsSet`) and the record fold, so client and server agree.
+ *
+ *   result = (local ∩ remote) ∪ (local − base) ∪ (remote − base)
+ *
+ * A base element is kept only if BOTH sides kept it (a one-sided removal is never
+ * undone by the other side's unchanged copy); a non-base element is kept if EITHER
+ * side has it. Elements are compared by `JSON.stringify`.
+ *
+ * Order is role-independent: kept base elements first, in base order, then every
+ * other kept element sorted by its serialized form. Swapping `local` and `remote`
+ * yields the identical array.
+ *
+ * Interim (S1): W7 replaces this pairwise rule with a per-element LWW set.
+ *
+ * @param local - One side's array after its modifications
+ * @param remote - The other side's array after its modifications
+ * @param base - The common ancestor both sides edited from
+ * @returns The merged array
+ */
+declare function mergeArraySet(local: unknown[], remote: unknown[], base: unknown[]): unknown[];
 /**
  * Replay a list of operations (MUST be pre-sorted in HLC total order —
  * wallTime, then logical, then nodeId) to produce the current state of a single
@@ -476,6 +500,10 @@ interface ReplayOperation {
  * the current op always wins that last-write-wins comparison, so the result is
  * deterministic and identical on every replica that folds the same operation set.
  *
+ * Plain array writes that carry `previousData` are merged as a set against that
+ * base (see {@link mergeArraySet}) when a concurrent writer changed the field since
+ * the base, so the fold and the client merge agree on one-sided removals.
+ *
  * This is the single definition of atomic materialization shared by the client
  * (`@korajs/store` apply pipeline) and the server (`@korajs/server` materialization),
  * so both converge to the same value for any number of concurrent atomic writers.
@@ -484,6 +512,446 @@ interface ReplayOperation {
  * or never inserted.
  */
 declare function replayOperationsForRecord(ops: ReplayOperation[]): Record<string, unknown> | null;
+/** A {@link ReplayOperation} with the HLC timestamp it was written at. */
+interface VersionedReplayOperation {
+    type: string;
+    data: Record<string, unknown> | null;
+    timestamp: HLCTimestamp;
+}
+/** Per-field versions of a live record, as folded by {@link replayFieldVersionsForRecord}. */
+interface RecordFieldVersions {
+    /** Field name -> HLC of the write that produced the field's current value. */
+    fields: Record<string, HLCTimestamp>;
+    /** The record's first operation (its creation; the server's `_created_at`). */
+    created: HLCTimestamp;
+    /** The record's newest operation. */
+    latest: HLCTimestamp;
+}
+/**
+ * Fold the per-field versions of one record, mirroring {@link replayOperationsForRecord}
+ * exactly (RT-27): an insert resets the field set and stamps every field it carries,
+ * an update stamps the fields it writes (composed atomic and array writes included:
+ * the field's version is its last writer's), a delete hides the record until a later
+ * write revives it. Operations MUST be pre-sorted in HLC total order.
+ *
+ * @param ops - The record's operations in HLC order
+ * @returns The live record's field versions, or null when it is deleted or absent
+ */
+declare function replayFieldVersionsForRecord(ops: readonly VersionedReplayOperation[]): RecordFieldVersions | null;
+/**
+ * Expand operations for a record fold (RT-27). A scope-entry insert carrying
+ * per-field versions restates the record's CURRENT values, each produced at its own
+ * version; folding it as one insert at a single timestamp would misplace every field
+ * relative to the receiver's own writes. It is expanded into an insert at its
+ * `timestamp` (the record's creation) followed by one update per newer field version,
+ * so a fold in HLC order puts each field exactly where its writer did. Other
+ * operations pass through unchanged. The result is sorted in HLC total order (stable,
+ * so an expansion keeps insert-before-update on equal timestamps).
+ *
+ * @param ops - Operations of one record, in any order
+ * @returns The operations to fold, in HLC order
+ */
+declare function expandFieldVersionedOperations(ops: readonly Operation[]): Operation[];
+
+/** `FoldTrace.field` of a record-level (delete vs write) decision. */
+declare const FOLD_RECORD_TRACE_FIELD = "*";
+/**
+ * An empty fold state for one record: no operation merged yet.
+ *
+ * @param collection - The record's collection
+ * @param recordId - The record's id
+ */
+declare function createFoldState(collection: string, recordId: string): FoldState;
+/**
+ * Merge one operation into a record's fold state.
+ *
+ * The merge is a join on a per-field CRDT, so it is commutative, associative and
+ * idempotent: any replica that has merged the same set of operations, in any
+ * order, any number of times, holds an identical state. Cost is O(fields the
+ * operation touches) except for the out-of-order cases documented per kind (a late
+ * write into an atomic or resolver chain refolds that field's chain).
+ *
+ * Record-level semantics:
+ * - The record exists once an insert has been merged.
+ * - Delete vs write is last-write-wins on the record: the record is live iff its
+ *   newest insert/update is later (HLC, then op id) than its newest delete. A
+ *   delete keeps the field states; a later write revives the record with every
+ *   field's merged value (the same visible result as the pre-W7 replay for an
+ *   update after a delete).
+ * - An insert onto an existing row merges per field; it is not a reset.
+ *
+ * @param state - The record's current state (not mutated)
+ * @param op - The operation (must belong to the same collection and record)
+ * @param schema - The schema; resolvers and merge strategies come from it
+ * @param options - Exclusion, richtext merger (traces only), trace mode, schema
+ *   transforms (the operation is merged as `operationSchemaView` reads it for
+ *   `schema.version`)
+ * @returns The new state, the merge traces, and whether anything changed
+ */
+declare function mergeOp(state: FoldState, input: Operation, schema: SchemaDefinition, options?: FoldOptions): MergeOpResult;
+/**
+ * Fold a record's operations from scratch: the reference definition of the
+ * record's state. Equal to merging the operations one by one with
+ * {@link mergeOp} in any order.
+ *
+ * @param ops - The record's operations, in any order, duplicates allowed
+ * @param schema - The schema
+ * @param options - `exclude` leaves out ops the server terminally rejected; traces
+ *   default to `'none'` here (pass `traces` to get them)
+ * @returns The state (null if no op remains after exclusion) and the traces
+ */
+declare function foldRecord(ops: readonly Operation[], schema: SchemaDefinition, options?: FoldOptions): FoldRecordResult;
+/**
+ * The record's materialized field values (without `id`), or null when it does not
+ * exist (no insert merged) or is deleted. Keys are in sorted order.
+ *
+ * @param state - The record's fold state
+ * @param options - `richtext` is required when a richtext field has concurrent updates
+ */
+declare function materialize(state: FoldState, options?: Pick<FoldOptions, 'richtext'>): Record<string, unknown> | null;
+/** True when the record exists and its newest write is later than its newest delete. */
+declare function isFoldStateLive(state: FoldState): boolean;
+/**
+ * Join two replicas' states of the same record (state-based CRDT merge):
+ * `joinStates(foldRecord(A).state, foldRecord(B).state) = foldRecord(A ∪ B).state`.
+ * Commutative, associative and idempotent. Used to merge a restored backup or a
+ * peer's snapshot without replaying its operations.
+ *
+ * @param a - One state
+ * @param b - The other state (same collection and record)
+ * @param schema - The schema (resolver fields refold through their resolver)
+ */
+declare function joinStates(a: FoldState, b: FoldState, schema: SchemaDefinition): FoldState;
+/**
+ * Each field's newest affecting write as a serialized HLC (`HybridLogicalClock.
+ * serialize`), regardless of liveness: the `_field_versions` column of a stored row,
+ * without a deserialize/serialize round trip. Keys in sorted order.
+ */
+declare function getFoldFieldVersionStrings(state: FoldState): Record<string, string>;
+/**
+ * Per-field versions of a live record (the fold's `_field_versions`): each field's
+ * newest affecting write, plus the record's creation and newest operation. null
+ * when the record is not live.
+ */
+declare function getFoldFieldVersions(state: FoldState): FoldFieldVersions | null;
+
+/**
+ * Serialize a record's fold state for storage (the client `_fold_state` column,
+ * the server stores' fold-record rows, backups, compaction snapshots).
+ *
+ * The output is canonical JSON (sorted keys), so two replicas holding the same
+ * operations write byte-identical strings. Format, version 2 (version 1, Stage A,
+ * keyed array elements by value only and is refused: such a state is re-folded):
+ *
+ * ```
+ * {
+ *   "v": 2,                      // format version
+ *   "c": "todos", "r": "<id>",   // collection, record id
+ *   "cr": Stamp|null,            // oldest insert (creation)
+ *   "w":  Stamp|null,            // newest insert/update
+ *   "d":  Stamp|null,            // newest delete (tombstone register)
+ *   "u":  Stamp|null,            // newest operation of any type
+ *   "f": { "<field>": FieldState }
+ * }
+ * Stamp      = { "t": "<HLC serialized>", "o": "<op id>", "c"?: 1 }  // c: authority class
+ * FieldState =
+ *   { "k":"reg", "e":[{ "s":Stamp, "v":value, "a"?:AtomicOp }], "val":value }
+ *   { "k":"set", "ao":bool, "sh":{ "s":Stamp, "arr":bool, "v"?:value }|null, "clr":Stamp|null,
+ *     "el":{ "<canonical JSON>#<k>":{ "v":value, "n":k, "a":Stamp|null, "f":{ "s":Stamp, "i":n }|null, "r":Stamp|null } } }
+ *   { "k":"map", "sh":{ "s":Stamp, "obj":bool, "v"?:value }|null, "clr":Stamp|null,
+ *     "keys":{ "<key>":{ "s":Stamp, "del":bool, "v"?:value } } }
+ *   { "k":"ctr", "base":{ "s":Stamp, "v":value }|null, "d":[{ "s":Stamp, "n":number }], "val":value }
+ *   { "k":"max"|"min", "best":{ "s":Stamp, "v":number }|null, "reg":{ "s":Stamp, "v":value }|null }
+ *   { "k":"res", "e":[{ "s":Stamp, "v":value, "b"?:value, "z"?:1 }], "val":value, "err"?:string }
+ *   { "k":"rt", "reset":{ "s":Stamp, "v":value }|null, "u":{ "<base64 Yjs update>":Stamp } }
+ * ```
+ *
+ * Values are JSON-safe (binary as `{ "$koraBytes": base64 }`). The state is
+ * self-contained: kinds that need history embed exactly the history they need
+ * ('reg' keeps the atomic chain since the newest plain write, 'res' its whole
+ * write log, 'ctr' the deltas since its base), so a compactor may treat the state
+ * as the record's snapshot and drop operations it covers.
+ *
+ * @param state - The fold state
+ * @returns Canonical JSON
+ */
+declare function serializeFoldState(state: FoldState): string;
+/**
+ * Parse a stored fold state. Throws {@link FoldStateError} for an unknown format
+ * version or a malformed state; the caller then re-folds the record from its log.
+ *
+ * @param json - Output of {@link serializeFoldState}
+ */
+declare function deserializeFoldState(json: string): FoldState;
+
+/** A materialized row and its versions, the input of {@link createSnapshotState}. */
+interface FoldSnapshotInput {
+    collection: string;
+    recordId: string;
+    /** Field values of the row (record or op-data form; binary is normalized). */
+    values: Record<string, unknown>;
+    /** Per-field version: the HLC of the newest write of each field. */
+    fieldVersions: Record<string, HLCTimestamp>;
+    /** HLC of the row's creation. */
+    created: HLCTimestamp;
+    /** HLC of the newest operation the row reflects (its `_version`). */
+    latest: HLCTimestamp;
+    /** The row is a domain tombstone. */
+    deleted: boolean;
+}
+/** Options of {@link createSnapshotState}. */
+interface FoldSnapshotOptions {
+    /**
+     * A fold state this replica still holds for the record (its stored
+     * `_kora_fold_state`, or the base of a compacted record). Every field whose stored
+     * kind still matches the schema is taken from it as-is (exact: element, delta and
+     * update stamps included); only the other fields are rebuilt from the row.
+     */
+    seed?: FoldState | null;
+    /**
+     * Legacy authoritative node ids (`FoldOptions.authoritativeNodeIds`). A
+     * `merge('server-authoritative')` field whose version was written by an
+     * authoritative node (a `kora:server:` node or one of these) is stamped with
+     * authority class 1, so a client write it beat cannot overturn it when merged again.
+     */
+    authoritativeNodeIds?: ReadonlySet<string>;
+}
+/**
+ * Build a record's fold state from a materialized row: the base snapshot used when
+ * the operations that produced the row are no longer all in the log (a database
+ * compacted before W7, or a record that owns quarantined log rows).
+ *
+ * Exact where the replica still has the data: fields of `options.seed` (a stored
+ * fold state) whose kind is unchanged are used verbatim, and the record stamps come
+ * from it. Every other field is written at its own version with a sentinel
+ * operation id that sorts after any real id, so the snapshot dominates every
+ * operation it reflects: re-merging such an operation changes nothing (the record's
+ * remaining log is folded on top of it again on every re-fold), while a later
+ * operation merges on top as usual. Arrays and objects also clear elements / keys
+ * written before the snapshot (so an older add the row no longer shows is not
+ * resurrected), richtext hides older updates, counters drop older deltas and
+ * custom-resolver fields start a fresh log at the snapshot value. A
+ * `merge('server-authoritative')` field whose version is a server node's write
+ * keeps its authority class.
+ *
+ * Approximate for a row-only field (RT-68 residual): a concurrent write OLDER than
+ * the field's version that arrives later folds against the snapshot value, not
+ * against the original operations (a late counter delta or array add is dropped).
+ * It cannot be otherwise without the original operations: the row alone does not
+ * say whether an older write is already in its value. The store marks such records
+ * approximate, and the server's fold state replaces the snapshot when the record
+ * next enters the device's scope.
+ *
+ * @param input - The row's values and versions
+ * @param schema - The schema (selects each field's fold kind)
+ * @param options - Seed state and authoritative node ids
+ */
+declare function createSnapshotState(input: FoldSnapshotInput, schema: SchemaDefinition, options?: FoldSnapshotOptions): FoldState;
+/** Result of {@link adaptFoldState}. */
+interface AdaptedFoldState {
+    state: FoldState;
+    /** Fields rebuilt as snapshots (their stored kind no longer matched the schema). */
+    adapted: string[];
+}
+/**
+ * Make a stored fold state mergeable under the current schema after a change of a
+ * field's fold kind (RT-63): every field whose stored kind no longer matches the
+ * plan is replaced by a snapshot of its materialized value at its newest write (as
+ * {@link createSnapshotState} builds from a row), keeping its authority class.
+ * Fields whose kind is unchanged are kept exactly. Used for compacted base states,
+ * whose operations are no longer in the log to re-fold with the new plan.
+ *
+ * @param state - A stored fold state (base or record state)
+ * @param schema - The current schema
+ * @param options - `richtext` merger, to materialize a richtext field with several updates
+ */
+declare function adaptFoldState(state: FoldState, schema: SchemaDefinition, options?: Pick<FoldOptions, 'richtext'>): AdaptedFoldState;
+
+/**
+ * Fingerprint of how a schema folds records (W7): the fold-state format version
+ * plus every collection's {@link collectionFoldPlanFingerprint}. When it changes
+ * (a field becomes `merge('counter')`, an array becomes append-only, a resolver is
+ * added or edited), stored fold states may hold fields of another kind and must be
+ * re-folded. The same definition as the server stores' `fold_plan_fingerprint`.
+ *
+ * Schema transforms (RT-84) are part of the plan when any is registered: an operation
+ * of another schema version folds as its transformed view, so changing a transform or
+ * the target version re-folds. Without transforms the fingerprint is unchanged.
+ *
+ * @param schema - The schema
+ * @param transforms - The schema transforms the replica folds with
+ */
+declare function foldPlanFingerprint(schema: SchemaDefinition, transforms?: readonly OperationTransform[]): string;
+/**
+ * Per-collection fold plan fingerprints, to find which collections a schema change
+ * re-plans (only their records need re-folding).
+ *
+ * @param schema - The schema
+ * @param transforms - The schema transforms the replica folds with (see {@link foldPlanFingerprint})
+ * @returns Collection name -> fingerprint (format version included)
+ */
+declare function foldPlanFingerprints(schema: SchemaDefinition, transforms?: readonly OperationTransform[]): Record<string, string>;
+/**
+ * The fields of a stored fold state whose kind no longer matches the schema (empty
+ * when the state can be merged into as-is).
+ *
+ * @param state - A stored fold state
+ * @param schema - The current schema
+ */
+declare function mismatchedFoldFields(state: FoldState, schema: SchemaDefinition): string[];
+
+/**
+ * Node-id namespaces Kora reserves for itself.
+ *
+ * Every id starting with {@link RESERVED_NODE_ID_PREFIX} belongs to Kora: devices
+ * never author under one (a client refuses to adopt such an id, and the server
+ * refuses it at the handshake). Inside it, {@link SERVER_NODE_ID_PREFIX} names the
+ * server's own nodes (`kora:server:<stableId>`): their writes are authoritative for
+ * `merge('server-authoritative')` fields on every replica, whatever list of node
+ * ids a given handshake advertised. That keeps authority stable across server
+ * restarts and instances without any replica having to learn the ids first.
+ */
+declare const RESERVED_NODE_ID_PREFIX = "kora:";
+/** Prefix of every server-authored node id: `kora:server:<stableId>`. */
+declare const SERVER_NODE_ID_PREFIX = "kora:server:";
+/** True when `nodeId` is in Kora's reserved `kora:` namespace. */
+declare function isReservedNodeId(nodeId: string): boolean;
+/** True when `nodeId` names a server node (`kora:server:<stableId>`). */
+declare function isServerNodeId(nodeId: string): boolean;
+/**
+ * Whether a node's writes are authoritative for `merge('server-authoritative')`
+ * fields: a server node by prefix, or one of `explicit` (legacy, randomly generated
+ * server node ids a server keeps advertising in its handshake).
+ *
+ * @param nodeId - The writing node
+ * @param explicit - Additional authoritative node ids (`FoldOptions.authoritativeNodeIds`)
+ */
+declare function isAuthoritativeNodeId(nodeId: string, explicit?: ReadonlySet<string>): boolean;
+
+/**
+ * Turn a {@link FoldTrace} into the {@link MergeTrace} DevTools and `merge:*`
+ * events consume. `operationA` is the operation that last wrote the field before
+ * the merge; the fold state only keeps its id (`trace.priorOperationId`), so the
+ * caller looks it up in its operation log. When it is unavailable (compacted, or
+ * the field had no prior value) the incoming operation stands in for it, and
+ * `inputA` still carries the prior value.
+ *
+ * @param trace - A trace from `mergeOp`
+ * @param operationA - The operation that produced the field's prior value, if known
+ */
+declare function toMergeTrace(trace: FoldTrace, operationA?: Operation | null): MergeTrace;
+
+/**
+ * Lossless string encoding for SQL text columns (RT-65), shared by every store that
+ * binds JavaScript strings into a database: the server's Postgres and SQLite stores
+ * and the client's SQLite stores (better-sqlite3, SQLite WASM on OPFS, and the
+ * IndexedDB fallback, which runs SQLite WASM in memory).
+ *
+ * A JavaScript string is a sequence of UTF-16 code units. SQL text is UTF-8, which
+ * cannot hold two kinds of code unit sequence a JS string can:
+ *
+ * - A lone UTF-16 surrogate: better-sqlite3, SQLite WASM (TextEncoder) and the
+ *   Postgres driver all encode it as U+FFFD: silent corruption.
+ * - U+0000: Postgres TEXT refuses it; SQLite WASM reads a TEXT column up to the first
+ *   NUL.
+ *
+ * The codec maps those code units to an escape introduced by U+FFFF, a Unicode
+ * noncharacter (valid UTF-8, never assigned):
+ *
+ * | Input | Stored |
+ * |---|---|
+ * | U+0000 | U+FFFF `0` |
+ * | U+FFFF | U+FFFF `F` |
+ * | lone surrogate `\uXXXX` | U+FFFF `s` + 4 lowercase hex digits |
+ *
+ * Every other string is stored unchanged, so existing rows, equality filters and
+ * ordering are unaffected for ordinary text. The map is injective, and
+ * `decodeStoredText(encodeStoredText(s)) === s` for every JS string. Equality is
+ * preserved: `encode(a) === encode(b)` iff `a === b`, so an equality filter binds the
+ * encoded value.
+ *
+ * Ordering of escaped strings: range filters (`$gt`, `$lt`, ...) and `orderBy` compare
+ * the stored (encoded) form, in the database's collation (UTF-8 byte order on SQLite and
+ * on Postgres with `C.UTF-8`). A string containing U+0000, U+FFFF or a lone surrogate
+ * therefore sorts by its escape, U+FFFF, at the position of the first such code unit:
+ * after every other BMP character there, and before supplementary-plane characters.
+ * For example `"a\u0000"` sorts after `"ab"` (in JavaScript it sorts before), and a
+ * lone surrogate sorts after `"\uFFFE"`. Such strings are rare and equality is exact;
+ * do not rely on their relative order in range queries.
+ *
+ * Columns holding `JSON.stringify` output need no codec: well-formed `JSON.stringify`
+ * escapes U+0000 and lone surrogates as `\u` sequences.
+ */
+/** The escape introducer: U+FFFF, a noncharacter. */
+declare const STORED_TEXT_ESCAPE = "\uFFFF";
+/** True when `s` contains a code unit a SQL text column cannot hold as is. */
+declare function needsStoredTextEncoding(s: string): boolean;
+/**
+ * Encode a JS string for a SQL TEXT column (or a string inside a JSONB value).
+ *
+ * @param s - Any JavaScript string
+ * @returns `s` itself when it holds no NUL, U+FFFF or lone surrogate; otherwise the escaped form
+ */
+declare function encodeStoredText(s: string): string;
+/**
+ * Decode a string written by {@link encodeStoredText}.
+ *
+ * @param s - A stored string
+ * @returns The original JavaScript string. A U+FFFF not followed by a valid tag is kept as is.
+ */
+declare function decodeStoredText(s: string): string;
+/**
+ * Apply {@link encodeStoredText} to every string (and object key) inside a JSON value.
+ *
+ * @param value - A JSON-compatible value
+ */
+declare function encodeStoredJsonValue(value: unknown): unknown;
+/**
+ * Apply {@link decodeStoredText} to every string (and object key) inside a JSON value.
+ *
+ * @param value - A JSON-compatible value
+ */
+declare function decodeStoredJsonValue(value: unknown): unknown;
+
+/**
+ * Deterministic id for a side-effect operation (a referential cascade, a
+ * set-null, a constraint correction) generated while applying `parentOpId`.
+ *
+ * Every replica that applies the same parent operation and generates the same
+ * effect on the same record derives the same id, so the effect is stored once and
+ * deduplicates everywhere instead of multiplying (one copy per replica) and racing
+ * (W7 step 3). Cascades keep working offline: a client derives the same id the
+ * server will.
+ *
+ * Callers must also make the side-effect's CONTENT deterministic (timestamp and
+ * data derived from the parent), because dedup by id keeps whichever copy arrives
+ * first. Ids are SHA-256 over canonical JSON of
+ * `{ domain, parent, rule, target }`, hex encoded.
+ *
+ * @param parentOpId - Id of the operation whose application produced the effect
+ * @param ruleId - Stable id of the rule (for example `relation:<name>:cascade`)
+ * @param targetRecordId - Id of the record the effect writes
+ * @returns 64-char hex id
+ */
+declare function deriveSideEffectOpId(parentOpId: string, ruleId: string, targetRecordId: string): Promise<string>;
+
+/**
+ * A fold state cannot be used: unknown format version, malformed JSON, a state
+ * for a different record, or a field whose stored kind no longer matches the
+ * schema. The fix is always the same: re-fold the record from its operation log
+ * (`foldRecord`), which is the source of truth.
+ */
+declare class FoldStateError extends KoraError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * The fold was asked for something its configuration cannot provide, for example
+ * materializing a richtext field with several concurrent Yjs updates without a
+ * richtext merger.
+ */
+declare class FoldConfigurationError extends KoraError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
 
 /**
  * Canonical JSON-safe encoding of binary bytes stored inside `op.data` /
@@ -578,7 +1046,7 @@ interface StateMachineInput {
     onInvalidTransition: 'reject' | 'last-valid-state';
 }
 interface CollectionInput {
-    fields: Record<string, FieldBuilder<any, any, any>>;
+    fields: Record<string, FieldBuilder>;
     indexes?: string[];
     constraints?: ConstraintInput[];
     resolve?: Record<string, CustomResolver>;
@@ -636,23 +1104,6 @@ type TypedSchemaDefinition<T extends SchemaInput = SchemaInput> = SchemaDefiniti
 };
 declare function defineSchema<const T extends SchemaInput>(input: T): TypedSchemaDefinition<T>;
 
-/**
- * Generate CREATE TABLE and CREATE INDEX SQL for a single collection.
- *
- * @param collectionName - The collection name
- * @param collection - The collection definition
- * @param relations - Optional relations for FK references
- * @returns An array of SQL statements (CREATE TABLE + CREATE INDEX)
- */
-declare function generateSQL(collectionName: string, collection: CollectionDefinition, relations?: Record<string, RelationDefinition>): string[];
-/**
- * Generate the full DDL for all collections plus metadata tables.
- *
- * @param schema - The complete schema definition
- * @returns An array of all SQL statements needed to initialize the database
- */
-declare function generateFullDDL(schema: SchemaDefinition): string[];
-
 /**
  * Quote a SQL identifier (table or column name) for safe interpolation into
  * generated SQL.
@@ -697,76 +1148,105 @@ declare function quoteIdent(name: string): string;
  * @throws {SchemaValidationError} If validation fails
  */
 declare function validateRecord(collection: string, collectionDef: CollectionDefinition, data: Record<string, unknown>, operationType: OperationType): Record<string, unknown>;
+/**
+ * The domain check of one resolved field value (value-domain.ts), for values produced
+ * after validation: an atomic op's resolved result (`op.increment(0.5)` on a timestamp,
+ * an increment past the largest finite number).
+ *
+ * @param collection - The collection (for the message)
+ * @param fieldName - The field
+ * @param descriptor - The field's descriptor
+ * @param value - The resolved value
+ * @throws {SchemaValidationError} When the value is outside the field's domain
+ */
+declare function assertResolvedFieldValue(collection: string, fieldName: string, descriptor: FieldDescriptor, value: unknown): void;
 
 /**
- * Type-level inference utilities for Kora schemas.
+ * One value domain (RT-86, RT-87): every value the local API accepts must be storable and
+ * transmissible, unchanged, by every built-in store (client SQLite and IndexedDB; server
+ * memory, SQLite and Postgres) and every transport (JSON and protobuf). The domain is
+ * defined here once, enforced where values are written (`validateRecord`, after atomic
+ * ops resolve) and re-checked by the server on ingest (`operationValueViolation`), so a
+ * value outside it is refused with a clear error before anything stores it, never by a
+ * database half-way through a sync.
  *
- * These mapped types convert FieldBuilder type parameters into concrete
- * TypeScript types, enabling full autocomplete and type checking from
- * defineSchema() through createApp() to collection methods.
+ * | Field type     | Domain                                                    | Client SQLite / IndexedDB | Server SQLite | Server Postgres          | Wire (JSON / protobuf) |
+ * |----------------|-----------------------------------------------------------|---------------------------|---------------|--------------------------|------------------------|
+ * | `string`       | any string (U+0000 and lone surrogates included)          | TEXT / string             | TEXT          | TEXT, lossless text codec (RT-65) | JSON string (escaped) |
+ * | `enum`         | one of the declared values                                | TEXT / string             | TEXT          | TEXT                     | JSON string            |
+ * | `secret`       | string (stored hashed or encrypted)                       | TEXT                      | TEXT          | TEXT                     | JSON string            |
+ * | `number`       | finite double; `-0` is `0`                                | REAL / number             | REAL          | DOUBLE PRECISION         | JSON number            |
+ * | `boolean`      | `true` / `false`                                          | INTEGER 0/1 / boolean     | INTEGER       | INTEGER                  | JSON boolean           |
+ * | `timestamp`    | integer milliseconds in [-8.64e15, 8.64e15] (the `Date` range; a safe integer). Fractions are refused, not rounded | INTEGER / number | INTEGER | BIGINT | JSON number |
+ * | `array`        | dense array of the item kind's domain, nesting <= {@link MAX_VALUE_DEPTH} | TEXT (JSON) / array | TEXT (JSON) | JSONB (text codec) | JSON array |
+ * | `object`       | plain object; declared keys in their kind's domain        | TEXT (JSON) / object      | TEXT (JSON)   | JSONB                    | JSON object            |
+ * | `json`         | any JSON value: finite numbers, no `__proto__` key, nesting <= {@link MAX_VALUE_DEPTH}, not exactly `{ __kora_bytes__ }` (the wire's binary form) | TEXT (JSON) / value | TEXT (JSON) | JSONB | JSON |
+ * | `blob`         | a `BlobRef`                                               | TEXT (JSON)               | TEXT          | TEXT                     | JSON object            |
+ * | `richtext`     | Yjs update bytes (`Uint8Array` / `ArrayBuffer`) or a string | BLOB / bytes            | BLOB          | BYTEA                    | `{ $koraBytes }` / bytes |
+ * | any operation  | serialized size <= `maxOperationBytes` (default {@link DEFAULT_MAX_OPERATION_BYTES}) | | | | |
  *
- * Zero runtime cost — these are purely compile-time constructs.
+ * Every value additionally has a canonical JSON form (core canonical-body): no `NaN`,
+ * `±Infinity`, `BigInt`, `Map`, `Set`, class instances or cycles.
  */
-
+/** Smallest `t.timestamp()` value: the earliest instant a JavaScript `Date` can hold. */
+declare const TIMESTAMP_MIN_MS = -8640000000000000;
+/** Largest `t.timestamp()` value: the latest instant a JavaScript `Date` can hold. */
+declare const TIMESTAMP_MAX_MS = 8640000000000000;
 /**
- * Maps a FieldKind string literal to its corresponding TypeScript type.
- */
-interface FieldKindToType {
-    string: string;
-    number: number;
-    boolean: boolean;
-    timestamp: number;
-    richtext: string;
-    enum: string;
-    array: unknown[];
-    object: Record<string, unknown>;
-    json: unknown;
-    blob: BlobRef;
-    secret: string;
-}
+ * Deepest nesting of arrays and objects inside one field value. Postgres parses JSONB
+ * recursively with a stack limit, and every replica folds values recursively; 64 levels
+ * is far beyond any real document.
+ */
+declare const MAX_VALUE_DEPTH = 64;
+/** Default largest serialized operation, shared by the local write path and the server. */
+declare const DEFAULT_MAX_OPERATION_BYTES: number;
 /**
- * Infers the TypeScript type for a single field descriptor or builder.
- * Supports both FieldBuilder (class instances) and FieldDescriptor (compiled objects).
- */
-type InferFieldType<F> = F extends EnumFieldBuilder<infer V, any, any> ? V[number] : F extends JsonFieldBuilder<infer T, any, any> ? T : F extends ArrayFieldBuilder<infer K, any, any> ? FieldKindToType[K][] : F extends FieldBuilder<infer K, any, any> ? K extends keyof FieldKindToType ? FieldKindToType[K] : unknown : F extends {
-    kind: 'enum';
-    enumValues: infer V;
-} ? V extends readonly (infer S)[] ? S : string : F extends {
-    kind: 'array';
-    itemKind: infer K extends FieldKind;
-} ? FieldKindToType[K][] : F extends {
-    kind: infer K extends FieldKind;
-} ? FieldKindToType[K] : unknown;
-/**
- * Infers the full record type returned from queries.
- * Includes `id`, `createdAt`, `updatedAt` metadata fields.
- * Optional/defaulted fields include `| null` in their type.
- */
-type InferRecord<Fields extends Record<string, FieldBuilder<any, any, any>>> = {
-    readonly id: string;
-    readonly createdAt: number;
-    readonly updatedAt: number;
-} & {
-    readonly [K in keyof Fields]: Fields[K] extends FieldBuilder<any, true, any> ? InferFieldType<Fields[K]> : InferFieldType<Fields[K]> | null;
-};
+ * Why `value` is not a valid `t.timestamp()` value, or null when it is.
+ *
+ * @param value - The value
+ */
+declare function timestampDomainViolation(value: unknown): string | null;
 /**
- * Infers the insert input type using inline key remapping.
- * - Required non-auto fields are required keys
- * - Optional/defaulted non-auto fields are optional keys
- * - Auto fields are excluded entirely
+ * The path of the first container nested deeper than `maxDepth`, or null.
+ *
+ * @param value - Any value
+ * @param maxDepth - The deepest allowed nesting of arrays and objects
  */
-type InferInsertInput<Fields extends Record<string, FieldBuilder<any, any, any>>> = {
-    [K in keyof Fields as Fields[K] extends FieldBuilder<any, any, true> ? never : Fields[K] extends FieldBuilder<any, true, false> ? K : never]: InferFieldType<Fields[K]>;
-} & {
-    [K in keyof Fields as Fields[K] extends FieldBuilder<any, any, true> ? never : Fields[K] extends FieldBuilder<any, true, false> ? never : K]?: InferFieldType<Fields[K]>;
-};
+declare function valueDepthViolation(value: unknown, maxDepth?: number): string | null;
 /**
- * Infers the update input type using inline key remapping.
- * All non-auto fields are optional (partial update semantics).
+ * The path of the first own `__proto__` key in a value, or null. JSON can carry such a
+ * key, but most JavaScript code (including object spreads into a fresh `{}` with
+ * assignment) turns it into a prototype and loses it, so it is refused everywhere.
+ *
+ * @param value - Any value
  */
-type InferUpdateInput<Fields extends Record<string, FieldBuilder<any, any, any>>> = {
-    [K in keyof Fields as Fields[K] extends FieldBuilder<any, any, true> ? never : K]?: InferFieldType<Fields[K]>;
-};
+declare function protoKeyViolation(value: unknown): string | null;
+/**
+ * Why a field value, as an OPERATION carries it (op-data form: richtext as
+ * `{ $koraBytes }` or a string, secrets in their at-rest string form), is outside the
+ * field's domain, or null when it is inside. The server checks every uploaded and
+ * route-written operation's data with it, so every server store and every peer holds
+ * the same values (RT-86, RT-87). `null` is always accepted (a cleared field).
+ *
+ * @param descriptor - The field's descriptor in the schema that reads the operation
+ * @param value - The value from `data`
+ */
+declare function operationValueViolation(descriptor: FieldDescriptor, value: unknown): string | null;
+/**
+ * Why a json or object field value is reserved by the wire, or null: an object whose
+ * only member is `__kora_bytes__`.
+ *
+ * @param value - A field value
+ */
+declare function reservedWireShapeViolation(value: unknown): string | null;
+/**
+ * Serialized size of an operation in bytes (UTF-8 of its JSON), the measure the server
+ * enforces `maxOperationBytes` with and the local write path checks before a write is
+ * accepted (RT-86).
+ *
+ * @param op - The operation
+ */
+declare function measureOperationBytes(op: Operation): number;
 
 /**
  * Create an empty version vector.
@@ -837,6 +1317,45 @@ declare function isCollectionSyncScoped(schema: SchemaDefinition, collectionName
  */
 declare function collectSchemaScopeValueKeys(schema: SchemaDefinition): string[];
 
+/**
+ * Reserved key in a server scope grant that carries VERIFIED claim values
+ * (for example `{ userId: <jwt sub>, orgId: <from your user store> }`).
+ *
+ * An auth provider usually cannot know the sync schema, so instead of listing
+ * every collection it returns `{ $claims: { userId } }` and the sync server binds
+ * each schema-scoped collection from those values when the session starts. A
+ * collection whose scope bindings cannot all be resolved from the claims is
+ * denied (fail closed), never widened to "everything".
+ *
+ * Collection names must start with a letter, so `$claims` can never collide with
+ * a real collection. Any consumer that does not expand it sees a key that matches
+ * no collection, which is also fail-closed.
+ */
+declare const SCOPE_CLAIMS_KEY: "$claims";
+/**
+ * Build a server scope grant from verified claim values, optionally combined
+ * with explicit per-collection grants. Explicit entries win over claim-derived
+ * bindings for the same collection.
+ *
+ * @param claims - Verified scope values, keyed by the scope binding names your
+ *   schema uses (`scope: ['userId']` binds the `userId` value)
+ * @param explicit - Optional explicit per-collection predicates
+ * @returns A scope grant suitable for `AuthContext.scopes`
+ *
+ * @example
+ * ```typescript
+ * return { userId: payload.sub, scopes: claimScopes({ userId: payload.sub, orgId }) }
+ * ```
+ */
+declare function claimScopes(claims: Record<string, unknown>, explicit?: ScopeMap): ScopeMap;
+/**
+ * Read the verified claim values carried by a scope grant, if any.
+ *
+ * @param grant - A scope grant (possibly containing {@link SCOPE_CLAIMS_KEY})
+ * @returns The claim values, or null when the grant has none
+ */
+declare function getScopeClaims(grant: ScopeMap | undefined): Record<string, unknown> | null;
+
 /**
  * Collect every unique scope field name declared across all collections.
  *
@@ -882,28 +1401,99 @@ declare function formatSequenceValue(template: string, counter: number, nodeId:
  */
 declare function defaultSequenceFormat(name: string): string;
 
-/**
- * Transforms operations created under an older schema version so they are valid
- * after a schema upgrade. Used during sync when client and server schema versions differ
- * but remain within the server's supported range.
- */
-interface OperationTransform {
-    /** Schema version the operation was authored against */
-    readonly fromVersion: number;
-    /** Target schema version after transformation */
-    readonly toVersion: number;
-    /**
-     * Transform a single operation. Return `null` to drop operations that cannot be migrated.
-     */
-    transform(operation: Operation): Operation | null;
-}
-
 /**
  * Apply registered transforms until the operation matches `targetSchemaVersion`.
  * Returns null when a transform drops the operation or no path exists.
  */
 declare function applyOperationTransforms(operation: Operation, targetSchemaVersion: number, transforms: readonly OperationTransform[]): Operation | null;
 
+/**
+ * Thrown when a schema transform breaks its contract: it changed an operation's
+ * identity (id, node, type, collection, record or timestamp), or produced a body with
+ * no canonical JSON form.
+ */
+declare class OperationTransformError extends KoraError {
+    constructor(message: string, context: Record<string, unknown>);
+}
+/**
+ * The operation as a schema reads it: its schema view (transforms at fold time).
+ *
+ * Operations are immutable and content-addressed, so a schema transform never rewrites
+ * a stored operation. Every replica (server stores and devices alike) stores and sends
+ * the operation exactly as its author wrote it, and applies the transform chain only
+ * when it judges or folds the operation, through this one function:
+ * - the server authorizes and validates the view, and its stores fold the view;
+ * - a device folds the view; an operation with no view (no transform path, e.g. one
+ *   authored under a NEWER schema than the device's) is kept aside and replayed after
+ *   the device upgrades.
+ *
+ * Contract, enforced here:
+ * - transforms are PURE and DETERMINISTIC: the same operation and transforms give the
+ *   same view on every replica, at every time (no clock, randomness or I/O). Every
+ *   replica must register the same transforms for the schema versions its log holds;
+ *   the fold plan fingerprint includes them, so changing a transform re-folds;
+ * - a transform rewrites `data`, `previousData`, `atomicOps` and `schemaVersion` only. A
+ *   view whose id, node, type, collection, record or timestamp differs is refused
+ *   ({@link OperationTransformError});
+ * - the view's body is canonical (core canonical-body), like any written body.
+ *
+ * Returned unchanged: an operation already at `targetSchemaVersion`, any operation
+ * when no transform is registered (it folds as written), and an encryption envelope the
+ * caller cannot read (`encrypted` set: the server folds its cleartext header as is;
+ * devices transform after decryption).
+ *
+ * @param op - The operation as stored
+ * @param targetSchemaVersion - The schema version of the replica judging or folding it
+ * @param transforms - The registered transforms
+ * @returns The view, or null when a transform drops the operation or no path exists
+ * @throws {OperationTransformError} When a transform breaks the contract above
+ */
+declare function operationSchemaView(op: Operation, targetSchemaVersion: number, transforms: readonly OperationTransform[] | undefined): Operation | null;
+/**
+ * Fingerprint of a transform chain for a target schema version: '' when no transform
+ * is registered (operations fold as written, whatever the target), otherwise the
+ * target version and each transform's versions and source text. Part of the fold plan
+ * fingerprint, so a replica re-folds when its views change.
+ *
+ * @param targetSchemaVersion - The replica's schema version
+ * @param transforms - The registered transforms
+ */
+declare function operationTransformsFingerprint(targetSchemaVersion: number, transforms: readonly OperationTransform[] | undefined): string;
+/**
+ * Thrown when stored operations have a schema version the registered transforms cannot
+ * read (RT-103): starting would fold those operations as absent and silently erase them
+ * from every record they belong to.
+ */
+declare class OperationTransformCoverageError extends KoraError {
+    readonly versions: readonly number[];
+    readonly targetSchemaVersion: number;
+    constructor(message: string, versions: readonly number[], targetSchemaVersion: number, context?: Record<string, unknown>);
+}
+/**
+ * The stored schema versions the transforms have no path from (RT-103). Mirrors the
+ * path {@link operationSchemaView} follows (`fromVersion` to `toVersion`, at most 32
+ * steps). An empty transform list reads everything (operations fold as written).
+ *
+ * @param storedVersions - Distinct schema versions of the stored operations
+ * @param targetSchemaVersion - The replica's schema version
+ * @param transforms - The registered transforms
+ * @returns Each version with no path and the version whose transform is missing, ascending
+ */
+declare function missingTransformPaths(storedVersions: Iterable<number>, targetSchemaVersion: number, transforms: readonly OperationTransform[] | undefined): Array<{
+    version: number;
+    missingFrom: number;
+}>;
+/**
+ * Refuse to start a replica whose transforms cannot read operations it stores (RT-103).
+ *
+ * @param storedVersions - Distinct schema versions of the stored operations
+ * @param targetSchemaVersion - The replica's schema version
+ * @param transforms - The registered transforms
+ * @param replica - Names the replica in the message ("server store", "local database")
+ * @throws {OperationTransformCoverageError} When a stored version has no path
+ */
+declare function assertOperationTransformCoverage(storedVersions: Iterable<number>, targetSchemaVersion: number, transforms: readonly OperationTransform[] | undefined, replica: string): void;
+
 /**
  * Convert migration steps to SQL statements.
  *
@@ -933,7 +1523,7 @@ declare function migrationStepsToSQL(steps: readonly MigrationStep[]): string[];
  *   .addIndex('todos', 'priority')
  *
  * const rollbackSQL = rollbackStepsToSQL(migration)
- * // ['DROP INDEX IF EXISTS idx_todos_priority',
+ * // ['DROP INDEX IF EXISTS "idx_5_todos_priority"',
  * //  'ALTER TABLE "todos" DROP COLUMN "priority"']
  * ```
  */
@@ -1125,4 +1715,4 @@ interface ProtoOutput {
  */
 declare function generateProtoDefinitions(schema: SchemaDefinition): ProtoOutput;
 
-export { APPLY_FAILURE_CODES, APPLY_RESULTS, AppNotReadyError, type ApplyFailureReason, type ApplyResult, ArrayFieldBuilder, AtomicOp, type AtomicOpSentinel, AtomicOpType, BlobRef, type BlobRefMetadata, CausalTracker, ClockDriftError, CollectionDefinition, type CollectionInput, type ConstraintInput, CustomResolver, EnumFieldBuilder, FieldBuilder, FieldKind, type FieldKindToType, type InferFieldType, type InferInsertInput, type InferRecord, type InferUpdateInput, InvalidTimestampError, KORA_ERROR_FIX_SUGGESTIONS, type KoraBytesValue, KoraError, MergeConflictError, MigrationDefinition, MigrationRollbackError, MigrationStep, MissingSecretKeyError, Operation, OperationError, type OperationLog, type OperationTransform, OperationType, type ProtoOutput, RandomSource, RelationDefinition, type RelationInput, RemoteClockDriftError, type ReplayOperation, type ReversibleMigration, SchemaDefinition, type SchemaInput, SchemaValidationError, type SecretKeyProvider, StateMachineConstraint, type StateMachineInput, StorageError, SyncError, TransitionMap, TransitionValidationResult, type TypedSchemaDefinition, VersionVector, advanceVector, applyAtomicOp, applyOperationTransforms, base64ToBytes, buildStateMachineConstraints, bytesToBase64, canAutoRollback, collectSchemaScopeFields, collectSchemaScopeValueKeys, computeDelta, createBlobRef, createReversibleMigration, createVersionVector, decodeBytesFromOpData, decryptSecret, defaultApplyFailureReason, defaultSequenceFormat, defineSchema, deserializeVector, dominates, encodeBytesForOpData, encryptSecret, extractScopeValuesFromClaims, extractTimestamp, formatSequenceValue, generateFullDDL, generateProtoDefinitions, generateRollbackSteps, generateSQL, generateUUIDv7, getCollectionScopeBindings, getKoraErrorFix, getTransitionMap, hasSchemaSyncRules, hashBlob, hashSecret, isApplyFailure, isAtomicOp, isBlobRef, isCollectionSyncScoped, isKoraBytesValue, isLegacyNumericByteObject, isValidUUIDv7, mergeVectors, migrationStepsToSQL, op, quoteIdent, replayOperationsForRecord, resolveAtomicOp, revealSecret, rollbackStepsToSQL, serializeVector, toAtomicOp, transformSecretFieldsForWrite, validateRecord, validateTransition, vectorsEqual, verifySecret, verifySecretValue };
+export { APPLY_FAILURE_CODES, APPLY_RESULTS, type AdaptedFoldState, AppNotReadyError, type ApplyFailureReason, type ApplyResult, AtomicOp, BlobRef, type BlobRefMetadata, type CanonicalizableBody, CausalTracker, ClockDriftError, CollectionDefinition, type CollectionInput, type ConstraintInput, CustomResolver, DEFAULT_MAX_OPERATION_BYTES, FOLD_RECORD_TRACE_FIELD, FieldBuilder, FieldDescriptor, FoldConfigurationError, FoldFieldVersions, FoldOptions, FoldRecordResult, type FoldSnapshotInput, type FoldSnapshotOptions, FoldState, FoldStateError, FoldTrace, HLCTimestamp, InvalidTimestampError, KORA_ERROR_FIX_SUGGESTIONS, type KoraBytesValue, KoraError, type LegacyBody, MAX_VALUE_DEPTH, MergeConflictError, MergeOpResult, MergeTrace, MigrationDefinition, MigrationRollbackError, MigrationStep, MissingSecretKeyError, NonCanonicalValueError, Operation, OperationError, OperationInput, type OperationLog, OperationTooLargeError, OperationTransform, OperationTransformCoverageError, OperationTransformError, OperationType, type ProtoOutput, RESERVED_NODE_ID_PREFIX, RandomSource, type RecordFieldVersions, type RelationInput, RemoteClockDriftError, type ReplayOperation, type ReversibleMigration, SCOPE_CLAIMS_KEY, SERVER_NODE_ID_PREFIX, STORED_TEXT_ESCAPE, SchemaDefinition, type SchemaInput, SchemaValidationError, ScopeMap, type SecretKeyProvider, StateMachineConstraint, type StateMachineInput, StorageError, SyncError, TIMESTAMP_MAX_MS, TIMESTAMP_MIN_MS, TransitionMap, TransitionValidationResult, type TypedSchemaDefinition, VersionVector, type VersionedReplayOperation, adaptFoldState, advanceVector, applyOperationTransforms, assertOperationTransformCoverage, assertResolvedFieldValue, base64ToBytes, buildStateMachineConstraints, bytesToBase64, canAutoRollback, canonicalValue, canonicalizeLegacyOperation, canonicalizeOperationBody, canonicalizeProvenLegacyClear, claimScopes, collectSchemaScopeFields, collectSchemaScopeValueKeys, computeDelta, createBlobRef, createFoldState, createReversibleMigration, createSnapshotState, createVersionVector, decodeBytesFromOpData, decodeStoredJsonValue, decodeStoredText, decryptSecret, defaultApplyFailureReason, defaultSequenceFormat, defineSchema, deriveSideEffectOpId, deserializeFoldState, deserializeVector, dominates, encodeBytesForOpData, encodeStoredJsonValue, encodeStoredText, encryptSecret, expandFieldVersionedOperations, extractScopeValuesFromClaims, extractTimestamp, foldPlanFingerprint, foldPlanFingerprints, foldRecord, formatSequenceValue, generateProtoDefinitions, generateRollbackSteps, generateUUIDv7, getCollectionScopeBindings, getFoldFieldVersionStrings, getFoldFieldVersions, getKoraErrorFix, getScopeClaims, getTransitionMap, hasSchemaSyncRules, hashBlob, hashSecret, isApplyFailure, isAuthoritativeNodeId, isBlobRef, isCollectionSyncScoped, isFoldStateLive, isKoraBytesValue, isLegacyNumericByteObject, isReservedNodeId, isServerNodeId, isValidUUIDv7, joinStates, materialize, measureOperationBytes, mergeArraySet, mergeOp, mergeVectors, migrationStepsToSQL, mismatchedFoldFields, missingTransformPaths, needsStoredTextEncoding, operationSchemaView, operationTransformsFingerprint, operationValueViolation, protoKeyViolation, quoteIdent, replayFieldVersionsForRecord, replayOperationsForRecord, reservedWireShapeViolation, revealSecret, rollbackStepsToSQL, serializeFoldState, serializeVector, timestampDomainViolation, toMergeTrace, transformSecretFieldsForWrite, validateRecord, validateTransition, valueDepthViolation, vectorsEqual, verifySecret, verifySecretValue };