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

package/dist/events-Da29Dt_3.d.cts

@@ -0,0 +1,1737 @@
+/**
+ * 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.
+ *
+ * The type parameters carry the helper's operation and operand type (RT-113), so an
+ * update input accepts numeric helpers only on number and timestamp fields and array
+ * helpers, with the element type, only on array fields. The bare `AtomicOpSentinel` is
+ * any sentinel.
+ */
+interface AtomicOpSentinel<Type extends AtomicOpType = AtomicOpType, Value = unknown> {
+    readonly [KORA_ATOMIC_OP_KEY]: true;
+    readonly type: Type;
+    readonly value: Value;
+}
+/** The numeric helpers (`op.increment`, `op.decrement`, `op.max`, `op.min`). */
+type NumericAtomicOpSentinel = AtomicOpSentinel<'increment' | 'max' | 'min', number>;
+/** The array helpers (`op.append`, `op.remove`) for an array of `Item`. */
+type ArrayAtomicOpSentinel<Item> = AtomicOpSentinel<'append' | 'remove', Item>;
+/**
+ * Constraint of an array helper's item: listing the primitive types keeps a literal
+ * argument's literal type (`op.append('high')` is `'high'`, assignable to an enum array),
+ * while objects are inferred as written (not readonly).
+ */
+type AtomicItem = string | number | boolean | bigint | symbol | object | null | undefined;
+/**
+ * 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<"increment", number>;
+    /**
+     * Decrement a number field by the given amount.
+     * Syntactic sugar for `op.increment(-n)`.
+     *
+     * @param n - The amount to decrement
+     */
+    decrement(n: number): AtomicOpSentinel<"increment", number>;
+    /**
+     * 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<"max", number>;
+    /**
+     * 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<"min", number>;
+    /**
+     * Append an item to an array field.
+     * Concurrent appends include all appended items.
+     *
+     * @param item - The item to append to the array
+     */
+    append<Item extends AtomicItem>(item: Item): AtomicOpSentinel<"append", Item>;
+    /**
+     * 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 extends AtomicItem>(item: Item): AtomicOpSentinel<"remove", Item>;
+};
+/**
+ * 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;
+
+/**
+ * Type-level inference utilities for Kora schemas.
+ *
+ * These mapped types read the structural `'~field'` brand every FieldBuilder carries
+ * (kind, requiredness, auto flag, read and write value types) and turn a collection's
+ * builders into record, insert and update types, enabling autocomplete and type checking
+ * from defineSchema() through createApp() to collection methods.
+ *
+ * Nullability rules (they mirror the runtime):
+ * - Record (read): a required field is `T`; an auto `timestamp` is `number` (the framework
+ *   always fills it); every other field is `T | null` (optional and defaulted fields can be
+ *   cleared with `update(id, { field: null })`, and rows written before a field existed
+ *   hold null).
+ * - Insert: a required field must be provided; optional and defaulted fields may be
+ *   omitted (not `null`: insert refuses null); auto fields cannot be provided at all.
+ * - Update: every non-auto field is optional; optional and defaulted fields accept `null`
+ *   to clear them; number and timestamp fields also accept the numeric `op.*` helpers, and
+ *   array fields `op.append` / `op.remove` with an item of the element type.
+ *
+ * Zero runtime cost — these are purely compile-time constructs.
+ */
+
+/**
+ * Maps a FieldKind string literal to the TypeScript type a read returns for it, when
+ * nothing more specific is known (a compiled {@link FieldDescriptor} rather than a
+ * builder). Builders carry exact types: enum literal unions, array item types, object
+ * shapes and json `T`.
+ */
+interface FieldKindToType {
+    string: string;
+    number: number;
+    boolean: boolean;
+    timestamp: number;
+    richtext: Uint8Array;
+    enum: string;
+    array: unknown[];
+    object: Record<string, unknown>;
+    json: unknown;
+    blob: BlobRef;
+    secret: string;
+}
+/** Any field builder. */
+type AnyField = FieldBuilder;
+/** The field map of one collection, as written in `defineSchema({ collections: { x: { fields } } })`. */
+type FieldMap = Record<string, AnyField>;
+/**
+ * Infers the TypeScript type a read returns for a single field builder or compiled
+ * field descriptor (before nullability). For a builder this is exact: enum literal
+ * unions, typed array items, object shapes and json `T` are preserved.
+ */
+type InferFieldType<F> = F extends {
+    readonly '~field': unknown;
+} ? FieldOutput<F> : 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 TypeScript type a write accepts for a single field builder (before
+ * optionality). Equal to {@link InferFieldType} except for richtext, which accepts a
+ * string or Yjs bytes.
+ */
+type InferFieldInput<F> = F extends {
+    readonly '~field': unknown;
+} ? FieldInput<F> : F extends {
+    kind: 'richtext';
+} ? RichtextInput : InferFieldType<F>;
+type IsRequired<F> = F extends {
+    readonly '~field': {
+        readonly required: true;
+    };
+} ? true : false;
+type IsAuto<F> = F extends {
+    readonly '~field': {
+        readonly auto: true;
+    };
+} ? true : false;
+type KindOf<F> = F extends {
+    readonly '~field': {
+        readonly kind: infer K;
+    };
+} ? K : FieldKind;
+type RequiredInsertKeys<F extends FieldMap> = {
+    [K in keyof F]: IsAuto<F[K]> extends true ? never : IsRequired<F[K]> extends true ? K : never;
+}[keyof F];
+type OptionalInsertKeys<F extends FieldMap> = {
+    [K in keyof F]: IsAuto<F[K]> extends true ? never : IsRequired<F[K]> extends true ? never : K;
+}[keyof F];
+type WritableKeys<F extends FieldMap> = {
+    [K in keyof F]: IsAuto<F[K]> extends true ? never : K;
+}[keyof F];
+/** The read type of one field in a record, nullability applied. */
+type InferRecordField<F> = IsRequired<F> extends true ? InferFieldType<F> : IsAuto<F> extends true ? KindOf<F> extends 'timestamp' ? InferFieldType<F> : InferFieldType<F> | null : InferFieldType<F> | null;
+/**
+ * Infers the full record type returned from queries.
+ * Includes `id`, `createdAt`, `updatedAt` metadata fields.
+ * Optional and defaulted fields include `| null` in their type.
+ */
+type InferRecord<Fields extends FieldMap> = Simplify<{
+    readonly id: string;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+} & {
+    readonly [K in keyof Fields]: InferRecordField<Fields[K]>;
+}>;
+/**
+ * Infers the insert input type.
+ * - Required non-auto fields are required keys
+ * - Optional/defaulted non-auto fields are optional keys (omit them; `null` is refused)
+ * - Auto fields are excluded entirely
+ */
+type InferInsertInput<Fields extends FieldMap> = Simplify<{
+    [K in RequiredInsertKeys<Fields>]: InferFieldInput<Fields[K]>;
+} & {
+    [K in OptionalInsertKeys<Fields>]?: InferFieldInput<Fields[K]>;
+}>;
+/** Alias of {@link InferInsertInput}. */
+type InferInsert<Fields extends FieldMap> = InferInsertInput<Fields>;
+/** The element type of an array field's value. */
+type ArrayItemOf<T> = T extends readonly (infer Item)[] ? Item : never;
+/**
+ * The `op.*` helpers one field accepts (RT-113): the numeric helpers (`increment`,
+ * `decrement`, `max`, `min`) on number and timestamp fields, the array helpers (`append`,
+ * `remove`) with the field's element type on array fields, none elsewhere. The runtime
+ * refuses every other combination, since the resolved value leaves the field's domain.
+ */
+type InferAtomicOp<F> = KindOf<F> extends 'number' | 'timestamp' ? NumericAtomicOpSentinel : KindOf<F> extends 'array' ? ArrayAtomicOpSentinel<ArrayItemOf<InferFieldType<F>>> : never;
+/** The values an update accepts for one field. */
+type InferUpdateField<F> = InferFieldInput<F> | (IsRequired<F> extends true ? never : null) | InferAtomicOp<F>;
+/**
+ * Infers the update input type.
+ * All non-auto fields are optional (partial update semantics). Optional and defaulted
+ * fields accept `null`; number and timestamp fields accept the numeric `op.*` helpers and
+ * array fields the array helpers with their element type ({@link InferAtomicOp}).
+ */
+type InferUpdateInput<Fields extends FieldMap> = Simplify<{
+    [K in WritableKeys<Fields>]?: InferUpdateField<Fields[K]>;
+}>;
+/** Alias of {@link InferUpdateInput}. */
+type InferUpdate<Fields extends FieldMap> = InferUpdateInput<Fields>;
+
+/**
+ * A value a `t.richtext()` field accepts on write: a plain string (stored as a fresh
+ * Yjs document holding that text) or Yjs update bytes. Reads always return the Yjs
+ * update bytes (`Uint8Array`).
+ */
+type RichtextInput = string | Uint8Array | ArrayBuffer;
+/**
+ * Compile-time description of a field, carried by every {@link FieldBuilder} under the
+ * `'~field'` key. It exists only in the type system (the property is `declare`d, so it is
+ * never present at runtime) and is what makes builders structurally distinct:
+ * `t.string()` and `t.string().optional()` are different types, so inference can tell a
+ * required field from an optional one.
+ */
+interface FieldTypeInfo<Kind extends FieldKind, Req extends boolean, Auto extends boolean, Output, Input> {
+    /** The field kind. */
+    readonly kind: Kind;
+    /** Whether the developer must provide the field on insert. */
+    readonly required: Req;
+    /** Whether the framework fills the field (it cannot be written). */
+    readonly auto: Auto;
+    /** The type a read returns for the field (before nullability). */
+    readonly output: Output;
+    /** The type a write accepts for the field (before optionality). */
+    readonly input: Input;
+}
+/**
+ * The value types of each scalar field kind: what a read returns. `timestamp` is integer
+ * milliseconds since the epoch (a `Date` is not accepted; use `date.getTime()`).
+ */
+interface ScalarKindToType {
+    string: string;
+    number: number;
+    boolean: boolean;
+    timestamp: number;
+    richtext: Uint8Array;
+    blob: BlobRef;
+    secret: string;
+}
+/** The type a scalar field kind accepts on write. */
+interface ScalarKindToInput {
+    string: string;
+    number: number;
+    boolean: boolean;
+    timestamp: number;
+    richtext: RichtextInput;
+    blob: BlobRef;
+    secret: string;
+}
+/** A scalar field kind: one whose builder is a plain {@link FieldBuilder}. */
+type ScalarFieldKind = keyof ScalarKindToType;
+/** The read type a field kind has when its builder declares nothing more specific. */
+type DefaultFieldOutput<Kind extends FieldKind> = FieldKindToType[Kind];
+/** The write type a field kind has when its builder declares nothing more specific. */
+type DefaultFieldInput<Kind extends FieldKind> = Kind extends 'richtext' ? RichtextInput : FieldKindToType[Kind];
+/**
+ * Base field builder implementing the builder pattern for schema field definitions.
+ * Each builder is immutable — modifier methods return new builder instances.
+ *
+ * Type parameters track field metadata at the type level for inference:
+ * - Kind: the field kind ('string', 'number', etc.)
+ * - Req: whether the field is required (true = required on insert)
+ * - Auto: whether the field is auto-populated (true = excluded from insert input)
+ * - Output: the type a read returns
+ * - Input: the type a write accepts (differs from Output only for richtext)
+ *
+ * A bare `FieldBuilder` (no type arguments) means "any field builder".
+ *
+ * @example
+ * ```typescript
+ * t.string()                    // required string field
+ * t.string().optional()         // optional string field
+ * t.string().default('hello')   // string with default value
+ * t.timestamp().auto()          // auto-populated timestamp
+ * ```
+ */
+declare class FieldBuilder<Kind extends FieldKind = FieldKind, Req extends boolean = boolean, Auto extends boolean = boolean, Output = DefaultFieldOutput<Kind>, Input = Kind extends 'richtext' ? DefaultFieldInput<Kind> : Output> {
+    /**
+     * Type-only brand (never present at runtime). It makes the builder's kind,
+     * requiredness, auto flag and value types part of its structure, which is what
+     * schema inference reads.
+     */
+    readonly '~field': FieldTypeInfo<Kind, Req, Auto, Output, Input>;
+    protected readonly _kind: Kind;
+    protected readonly _required: boolean;
+    protected readonly _defaultValue: unknown;
+    protected readonly _auto: boolean;
+    protected readonly _mergeStrategy: FieldMergeStrategy | null;
+    constructor(kind: Kind, required?: boolean, defaultValue?: unknown, auto?: boolean, mergeStrategy?: FieldMergeStrategy | null);
+    /** Mark this field as optional (not required on insert; reads may return `null`). */
+    optional(): FieldBuilder<Kind, false, Auto, Output, Input>;
+    /**
+     * Set a default value for this field. Implicitly makes the field optional on insert.
+     * The value must be of the field's type (`t.number().default('x')` is a type error).
+     */
+    default(value: Input): FieldBuilder<Kind, false, Auto, Output, Input>;
+    /**
+     * Mark this field as auto-populated (e.g., createdAt timestamps). Developers cannot
+     * set auto fields; the framework fills `t.timestamp().auto()` with the insert time.
+     */
+    auto(): FieldBuilder<Kind, false, true, Output, Input>;
+    /**
+     * Declare a merge strategy for this field.
+     * Controls how concurrent modifications are resolved during sync.
+     *
+     * @param strategy - The merge strategy to use:
+     *   - `'lww'`: Last-write-wins (default for scalar fields)
+     *   - `'counter'`: Sum of deltas from base (for numbers)
+     *   - `'max'`: Keep the maximum value (for numbers/timestamps)
+     *   - `'min'`: Keep the minimum value (for numbers/timestamps)
+     *   - `'union'`: Set-union merge (default for arrays)
+     *   - `'append-only'`: Concatenate additions (for arrays)
+     *   - `'server-authoritative'`: Always prefer the remote/server value
+     */
+    merge(strategy: FieldMergeStrategy): FieldBuilder<Kind, Req, Auto, Output, Input>;
+    /** @internal Build the final FieldDescriptor. Used by defineSchema(). */
+    _build(): FieldDescriptor;
+}
+/**
+ * Field builder for enum fields with constrained string values.
+ * Preserves the literal enum tuple type for inference.
+ */
+declare class EnumFieldBuilder<Values extends readonly string[] = readonly string[], Req extends boolean = boolean, Auto extends boolean = boolean> extends FieldBuilder<'enum', Req, Auto, Values[number]> {
+    private readonly _enumValues;
+    private readonly _transitions;
+    constructor(values: Values, required?: boolean, defaultValue?: unknown, auto?: boolean, mergeStrategy?: FieldMergeStrategy | null, transitions?: TransitionMap | null);
+    optional(): EnumFieldBuilder<Values, false, Auto>;
+    default(value: Values[number]): EnumFieldBuilder<Values, false, Auto>;
+    auto(): EnumFieldBuilder<Values, false, true>;
+    merge(strategy: FieldMergeStrategy): EnumFieldBuilder<Values, Req, Auto>;
+    /**
+     * Declare allowed state transitions for this enum field.
+     * Enables state machine validation during mutations and merges.
+     *
+     * @param map - Map of state to allowed next states
+     *
+     * @example
+     * ```typescript
+     * t.enum(['draft', 'pending', 'confirmed', 'cancelled']).transitions({
+     *   draft: ['pending', 'cancelled'],
+     *   pending: ['confirmed', 'cancelled'],
+     *   confirmed: [],
+     *   cancelled: [],
+     * })
+     * ```
+     */
+    transitions(map: Partial<Record<Values[number], Values[number][]>>): EnumFieldBuilder<Values, Req, Auto>;
+    _build(): FieldDescriptor;
+}
+/** The read type of the values a field builder holds (before nullability). */
+type FieldOutput<F> = F extends {
+    readonly '~field': {
+        readonly output: infer O;
+    };
+} ? O : unknown;
+/** The write type a field builder accepts (before optionality). */
+type FieldInput<F> = F extends {
+    readonly '~field': {
+        readonly input: infer I;
+    };
+} ? I : unknown;
+/**
+ * Field builder for array fields. Carries the item builder's type, so
+ * `t.array(t.enum(['a', 'b']))` infers `('a' | 'b')[]`.
+ */
+declare class ArrayFieldBuilder<Item extends FieldBuilder = FieldBuilder, Req extends boolean = boolean, Auto extends boolean = boolean> extends FieldBuilder<'array', Req, Auto, FieldOutput<Item>[], FieldInput<Item>[]> {
+    private readonly _item;
+    constructor(itemBuilder: Item, required?: boolean, defaultValue?: unknown, auto?: boolean, mergeStrategy?: FieldMergeStrategy | null);
+    optional(): ArrayFieldBuilder<Item, false, Auto>;
+    default(value: FieldInput<Item>[]): ArrayFieldBuilder<Item, false, Auto>;
+    auto(): ArrayFieldBuilder<Item, false, true>;
+    merge(strategy: FieldMergeStrategy): ArrayFieldBuilder<Item, Req, Auto>;
+    _build(): FieldDescriptor;
+}
+/** Flattens an intersection of object types into one object type (for readable hovers). */
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type RequiredNestedKeys<F> = {
+    [K in keyof F]: F[K] extends {
+        readonly '~field': {
+            readonly required: true;
+        };
+    } ? K : never;
+}[keyof F];
+/**
+ * The value type of a `t.object({...})` field built from its nested builders. A required
+ * nested key is required; an optional or defaulted nested key may be absent or `null`.
+ */
+type ObjectFieldValue<F extends Record<string, FieldBuilder>, Mode extends 'output' | 'input'> = Simplify<{
+    [K in RequiredNestedKeys<F>]: Mode extends 'output' ? FieldOutput<F[K]> : FieldInput<F[K]>;
+} & {
+    [K in Exclude<keyof F, RequiredNestedKeys<F>>]?: (Mode extends 'output' ? FieldOutput<F[K]> : FieldInput<F[K]>) | null;
+}>;
+/**
+ * Field builder for structured object fields with a nested field schema. Carries the
+ * nested builders' types, so `t.object({ theme: t.string() })` infers `{ theme: string }`.
+ *
+ * Each nested key merges by its own declared kind (scalars via LWW, nested
+ * arrays via add-wins, nested objects recursively), so two devices editing
+ * different keys of the same object offline both converge on reconnect instead
+ * of one clobbering the other.
+ */
+declare class ObjectFieldBuilder<Fields extends Record<string, FieldBuilder> = Record<string, FieldBuilder>, Req extends boolean = boolean, Auto extends boolean = boolean> extends FieldBuilder<'object', Req, Auto, ObjectFieldValue<Fields, 'output'>, ObjectFieldValue<Fields, 'input'>> {
+    private readonly _fields;
+    constructor(fields: Fields, required?: boolean, defaultValue?: unknown, auto?: boolean, mergeStrategy?: FieldMergeStrategy | null);
+    optional(): ObjectFieldBuilder<Fields, false, Auto>;
+    default(value: ObjectFieldValue<Fields, 'input'>): ObjectFieldBuilder<Fields, false, Auto>;
+    auto(): ObjectFieldBuilder<Fields, false, true>;
+    merge(strategy: FieldMergeStrategy): ObjectFieldBuilder<Fields, Req, Auto>;
+    _build(): FieldDescriptor;
+}
+/**
+ * Field builder for dynamic-key JSON values. Carries a compile-time shape `T`
+ * for inference while merging structurally as a convergent CRDT: a plain-object
+ * value recurses as a map, an array merges add-wins, any other value is a scalar
+ * leaf under last-write-wins.
+ *
+ * A `Date` nested inside a json value is stored as its ISO string (the canonical
+ * operation form), so declare such members as `string` in `T`.
+ */
+declare class JsonFieldBuilder<T = unknown, Req extends boolean = boolean, Auto extends boolean = boolean> extends FieldBuilder<'json', Req, Auto, T> {
+    optional(): JsonFieldBuilder<T, false, Auto>;
+    default(value: T): JsonFieldBuilder<T, false, Auto>;
+    auto(): JsonFieldBuilder<T, false, true>;
+    merge(strategy: FieldMergeStrategy): JsonFieldBuilder<T, Req, Auto>;
+    _build(): FieldDescriptor;
+}
+/**
+ * Field builder for secret fields (passwords, tokens, API keys).
+ *
+ * A secret field's value is never exposed in merge traces, DevTools, or logs
+ * (it is redacted at the point traces are built). Its at-rest protection is
+ * chosen with `.hashed()` (one-way, for passwords) or `.encrypted()` (reversible,
+ * for tokens); the default is `encrypted`.
+ */
+declare class SecretFieldBuilder<Req extends boolean = boolean, Auto extends boolean = boolean> extends FieldBuilder<'secret', Req, Auto, string> {
+    private readonly _secretMode;
+    constructor(secretMode?: SecretMode, required?: boolean, defaultValue?: unknown, auto?: boolean, mergeStrategy?: FieldMergeStrategy | null);
+    /** Store this secret as a one-way salted hash (passwords: verify, never read back). */
+    hashed(): SecretFieldBuilder<Req, Auto>;
+    /** Store this secret as reversible ciphertext (tokens/keys: decrypt to use). */
+    encrypted(): SecretFieldBuilder<Req, Auto>;
+    optional(): SecretFieldBuilder<false, Auto>;
+    default(value: string): SecretFieldBuilder<false, Auto>;
+    auto(): SecretFieldBuilder<false, true>;
+    merge(strategy: FieldMergeStrategy): SecretFieldBuilder<Req, Auto>;
+    _build(): FieldDescriptor;
+}
+/** The builder `t.<kind>()` returns for a scalar kind: required, not auto. */
+type ScalarFieldBuilder<K extends ScalarFieldKind> = FieldBuilder<K, true, false, ScalarKindToType[K], ScalarKindToInput[K]>;
+/**
+ * Type builder namespace. The developer's primary interface for defining field types.
+ *
+ * Value types: `string` and `secret` are strings, `number` is a finite number,
+ * `timestamp` is integer milliseconds since the epoch (`Date` is not accepted; pass
+ * `date.getTime()`), `richtext` reads as Yjs update bytes and accepts a string or bytes,
+ * `blob` is a `BlobRef`.
+ *
+ * @example
+ * ```typescript
+ * import { t } from '@korajs/core'
+ *
+ * const fields = {
+ *   title: t.string(),
+ *   count: t.number(),
+ *   active: t.boolean().default(true),
+ *   notes: t.richtext(),
+ *   tags: t.array(t.string()).default([]),
+ *   priority: t.enum(['low', 'medium', 'high']).default('medium'),
+ *   settings: t.object({ theme: t.string(), fontSize: t.number() }),
+ *   metadata: t.json<{ source: string }>(),
+ *   createdAt: t.timestamp().auto(),
+ * }
+ * ```
+ */
+declare const t: {
+    /** A string field. */
+    string(): ScalarFieldBuilder<"string">;
+    /** A finite-number field. */
+    number(): ScalarFieldBuilder<"number">;
+    /** A boolean field. */
+    boolean(): ScalarFieldBuilder<"boolean">;
+    /** A timestamp field: integer milliseconds since the epoch (not a `Date`). */
+    timestamp(): ScalarFieldBuilder<"timestamp">;
+    /** A collaborative rich-text field (Yjs). Reads return the Yjs update bytes. */
+    richtext(): ScalarFieldBuilder<"richtext">;
+    /** An enum field whose value is one of `values`. */
+    enum<const V extends readonly string[]>(values: V): EnumFieldBuilder<V, true, false>;
+    /** An array field whose items have the type of `itemBuilder`. */
+    array<Item extends FieldBuilder>(itemBuilder: Item): ArrayFieldBuilder<Item, true, false>;
+    /** A structured object field whose keys are declared by nested builders. */
+    object<const F extends Record<string, FieldBuilder>>(fields: F): ObjectFieldBuilder<F, true, false>;
+    /** A dynamic JSON field typed as `T` (compile-time only; not validated against `T`). */
+    json<T = unknown>(): JsonFieldBuilder<T, true, false>;
+    /** A blob reference field (`BlobRef`); the bytes live in the blob store. */
+    blob(): ScalarFieldBuilder<"blob">;
+    /** A secret field (password, token): redacted from traces, hashed or encrypted at rest. */
+    secret(): SecretFieldBuilder<true, false>;
+};
+
+/**
+ * A single migration step describing a schema change.
+ */
+type MigrationStep = {
+    type: 'addField';
+    collection: string;
+    field: string;
+    descriptor: FieldDescriptor;
+} | {
+    type: 'removeField';
+    collection: string;
+    field: string;
+    descriptor?: FieldDescriptor;
+} | {
+    type: 'renameField';
+    collection: string;
+    from: string;
+    to: string;
+} | {
+    type: 'addIndex';
+    collection: string;
+    field: string;
+} | {
+    type: 'removeIndex';
+    collection: string;
+    field: string;
+} | {
+    type: 'backfill';
+    collection: string;
+    transform: (record: Record<string, unknown>) => Record<string, unknown>;
+    /** Reverse transform for rollback. If not provided, backfill is not safely reversible. */
+    reverseTransform?: (record: Record<string, unknown>) => Record<string, unknown>;
+    /**
+     * Rewrite rows on this device only, without writing operations (so nothing
+     * syncs). Default false: every changed record is written through the normal
+     * local write path as an update operation (mutation name `migration:v<N>`).
+     */
+    localOnly?: boolean;
+};
+/** Options for {@link MigrationBuilder.backfill}. */
+interface BackfillOptions {
+    /** Reverse transform for rollback support. */
+    reverseTransform?: (record: Record<string, unknown>) => Record<string, unknown>;
+    /**
+     * Rewrite rows on this device only, without operations, so the change never syncs.
+     * Use it for device-local derived data. Default false: backfilled values are written
+     * as update operations and sync like any other write.
+     */
+    localOnly?: boolean;
+}
+/**
+ * A completed migration definition containing ordered steps and optional rollback steps.
+ */
+interface MigrationDefinition {
+    readonly steps: readonly MigrationStep[];
+    /** Explicitly defined rollback steps. If undefined, inverse steps are auto-generated. */
+    readonly rollbackSteps: readonly MigrationStep[] | undefined;
+    /** Whether this migration can be safely rolled back. */
+    readonly safelyReversible: boolean;
+}
+/**
+ * Builder for defining rollback steps explicitly.
+ * Used with the `.down()` method on MigrationBuilder.
+ *
+ * @example
+ * ```typescript
+ * migrate()
+ *   .addField('todos', 'priority', t.enum(['low', 'medium', 'high']).default('medium'))
+ *   .addIndex('todos', 'priority')
+ *   .down((rollback) => {
+ *     rollback
+ *       .removeIndex('todos', 'priority')
+ *       .removeField('todos', 'priority')
+ *   })
+ * ```
+ */
+declare class RollbackBuilder {
+    private _steps;
+    /**
+     * Add a field during rollback (to reverse a removeField).
+     */
+    addField(collection: string, field: string, builder: FieldBuilder): RollbackBuilder;
+    /**
+     * Remove a field during rollback (to reverse an addField).
+     */
+    removeField(collection: string, field: string): RollbackBuilder;
+    /**
+     * Rename a field during rollback (to reverse a renameField).
+     */
+    renameField(collection: string, from: string, to: string): RollbackBuilder;
+    /**
+     * Add an index during rollback (to reverse a removeIndex).
+     */
+    addIndex(collection: string, field: string): RollbackBuilder;
+    /**
+     * Remove an index during rollback (to reverse an addIndex).
+     */
+    removeIndex(collection: string, field: string): RollbackBuilder;
+    /**
+     * Run a backfill during rollback (to reverse a previous backfill).
+     */
+    backfill(collection: string, transform: (record: Record<string, unknown>) => Record<string, unknown>): RollbackBuilder;
+    /**
+     * Get the accumulated rollback steps.
+     */
+    _getSteps(): readonly MigrationStep[];
+}
+/**
+ * Fluent builder for defining schema migrations.
+ *
+ * Each method returns a new builder instance (immutable).
+ *
+ * @example
+ * ```typescript
+ * migrate()
+ *   .addField('products', 'taxInclusive', t.boolean().default(false))
+ *   .renameField('products', 'cost', 'costPrice')
+ *   .backfill('products', (record) => ({
+ *     taxInclusive: record.taxRate > 0,
+ *   }))
+ * ```
+ */
+declare class MigrationBuilder implements MigrationDefinition {
+    readonly steps: readonly MigrationStep[];
+    readonly rollbackSteps: readonly MigrationStep[] | undefined;
+    readonly safelyReversible: boolean;
+    constructor(steps?: readonly MigrationStep[], rollbackSteps?: readonly MigrationStep[], safelyReversible?: boolean);
+    /**
+     * Add a new field to a collection.
+     * The field builder provides the type and default value.
+     */
+    addField(collection: string, field: string, builder: FieldBuilder): MigrationBuilder;
+    /**
+     * Remove a field from a collection.
+     * Optionally accepts a field builder to preserve the descriptor for rollback.
+     * Without the descriptor, rollback of this step requires a custom `.down()`.
+     *
+     * @param collection - The collection name
+     * @param field - The field name to remove
+     * @param builder - Optional field builder preserving the type info for rollback
+     */
+    removeField(collection: string, field: string, builder?: FieldBuilder): MigrationBuilder;
+    /**
+     * Rename a field in a collection.
+     * Implemented as ALTER TABLE RENAME COLUMN (SQLite 3.25+).
+     */
+    renameField(collection: string, from: string, to: string): MigrationBuilder;
+    /**
+     * Add an index on a field.
+     */
+    addIndex(collection: string, field: string): MigrationBuilder;
+    /**
+     * Remove an index on a field.
+     */
+    removeIndex(collection: string, field: string): MigrationBuilder;
+    /**
+     * Backfill records in a collection using a transform function.
+     * The transform receives each live record (typed values, as the app reads them) and
+     * returns the fields to change. Runs after structural changes (addField, renameField,
+     * etc.), in the same transaction as them and the schema version write.
+     *
+     * Changed records are written as update operations (mutation name `migration:v<N>`)
+     * through the normal local write path, so backfilled values sync. Pass
+     * `{ localOnly: true }` for device-local data that must not sync.
+     *
+     * @param collection - The collection name
+     * @param transform - Forward transform function
+     * @param reverseOrOptions - Reverse transform for rollback support, or options
+     */
+    backfill(collection: string, transform: (record: Record<string, unknown>) => Record<string, unknown>, reverseOrOptions?: ((record: Record<string, unknown>) => Record<string, unknown>) | BackfillOptions): MigrationBuilder;
+    /**
+     * Define explicit rollback steps for this migration.
+     * If not called, inverse steps are auto-generated from forward steps.
+     *
+     * @param fn - Function that receives a RollbackBuilder to define rollback steps
+     * @returns A new MigrationBuilder with the rollback steps attached
+     *
+     * @example
+     * ```typescript
+     * migrate()
+     *   .addField('todos', 'priority', t.enum(['low', 'medium', 'high']).default('medium'))
+     *   .addIndex('todos', 'priority')
+     *   .down((rollback) => {
+     *     rollback
+     *       .removeIndex('todos', 'priority')
+     *       .removeField('todos', 'priority')
+     *   })
+     * ```
+     */
+    down(fn: (rollback: RollbackBuilder) => void): MigrationBuilder;
+    /**
+     * Determine if a migration is safely reversible based on its steps.
+     * A migration is not safely reversible if:
+     * - It has a backfill step without a reverseTransform and no explicit rollback
+     * - It has a removeField without a stored descriptor and no explicit rollback
+     */
+    private _computeSafelyReversible;
+}
+/**
+ * Start building a migration.
+ *
+ * @returns A new MigrationBuilder
+ *
+ * @example
+ * ```typescript
+ * import { migrate, t } from '@korajs/core'
+ *
+ * const migration = migrate()
+ *   .addField('products', 'taxInclusive', t.boolean().default(false))
+ *   .renameField('products', 'cost', 'costPrice')
+ * ```
+ */
+declare function migrate(): MigrationBuilder;
+
+/**
+ * Hybrid Logical Clock timestamp.
+ * Provides a total order that respects causality without requiring synchronized clocks.
+ */
+interface HLCTimestamp {
+    /** Physical wall-clock time in milliseconds */
+    wallTime: number;
+    /** Logical counter. Increments when wallTime hasn't changed since last event. */
+    logical: number;
+    /** Node ID for tie-breaking. Ensures total order even with identical wall+logical. */
+    nodeId: string;
+}
+/** The three mutation types an operation can represent */
+type OperationType = 'insert' | 'update' | 'delete';
+/** Supported atomic operation types for intent-preserving field updates */
+type AtomicOpType = 'increment' | 'max' | 'min' | 'append' | 'remove';
+/**
+ * Atomic operation stored in an Operation's atomicOps field.
+ * This is the serializable form that persists in the operation log.
+ */
+interface AtomicOp {
+    readonly type: AtomicOpType;
+    readonly value: unknown;
+}
+/**
+ * The atomic unit of the entire system. Every mutation produces an Operation.
+ * Operations are IMMUTABLE and CONTENT-ADDRESSED.
+ */
+interface Operation {
+    /**
+     * Content-addressed SHA-256 hash of the operation's canonical body. Which fields it
+     * covers depends on `hashVersion` (version 2, the default for new operations, adds
+     * previousData, sequenceNumber, causalDeps and schemaVersion to version 1's fields).
+     * Verify with `verifyOperationId`.
+     */
+    id: string;
+    /** UUID v7 of the originating device. Time-sortable. */
+    nodeId: string;
+    /** What happened */
+    type: OperationType;
+    /** Which collection (from schema) */
+    collection: string;
+    /** ID of the affected record. UUID v7 for inserts, existing ID for update/delete. */
+    recordId: string;
+    /** Field values. null for delete. For updates, contains ONLY changed fields. */
+    data: Record<string, unknown> | null;
+    /** For updates: previous values of changed fields (enables 3-way merge). null for insert/delete. */
+    previousData: Record<string, unknown> | null;
+    /** Hybrid Logical Clock timestamp. Used for causal ordering. */
+    timestamp: HLCTimestamp;
+    /** Monotonically increasing per node. Used in version vectors. */
+    sequenceNumber: number;
+    /** Operation IDs this operation causally depends on (direct parents in the DAG). */
+    causalDeps: string[];
+    /** Schema version at time of creation. Used for migration transforms. */
+    schemaVersion: number;
+    /** Atomic operation intents for fields in data (e.g., increment, max). Present only when atomic ops were used. */
+    atomicOps?: Record<string, AtomicOp>;
+    /** Groups this operation with others in an atomic transaction. Not part of the content hash. */
+    transactionId?: string;
+    /** Human-readable name for the mutation group (e.g., 'complete-sale'). For DevTools display. */
+    mutationName?: string;
+    /**
+     * Per-field HLC versions, present only on server-synthesized scope-entry inserts
+     * (RT-27). The entry restates a record's current values; each field carries the
+     * version of the write that produced it, so a receiver resolves every field by
+     * last-write-wins against its own field version instead of one whole-row stamp.
+     * `timestamp` is then the record's creation time. Not part of the content hash.
+     */
+    fieldVersions?: Record<string, HLCTimestamp>;
+    /**
+     * Content-hash version of `id` (CORE-1). Absent means 1: the id covers type,
+     * collection, recordId, data, timestamp, nodeId and atomicOps. 2: it also
+     * covers previousData, sequenceNumber, causalDeps and schemaVersion. Verify
+     * with `verifyOperationId`. New operations are version 2 (protocol v2); the
+     * field is carried on the wire (protobuf operation field 14) and persisted.
+     */
+    hashVersion?: 1 | 2;
+    /**
+     * Server-authored serialized fold state (`serializeFoldState`) of the record (W7),
+     * carried on scope-entry inserts instead of `fieldVersions`, and present only on
+     * operations from a node the handshake named authoritative
+     * (`HandshakeResponseMessage.authoritativeNodeIds`). A receiver joins it into its own
+     * state (`joinStates`), so every field kind (richtext, counters, resolvers, element
+     * sets) enters with its full merge state. Opaque to the protocol layer. NOT part of
+     * the content hash; the server strips it from every device upload. Protobuf
+     * operation field 15.
+     */
+    foldState?: string;
+    /**
+     * End-to-end encryption envelope (protocol v2, W9). When present the operation's
+     * `data`, `previousData` and `atomicOps` travel only inside this envelope as
+     * ciphertext; `data` is null (or holds only the documented cleartext scope fields)
+     * and `previousData`/`atomicOps` are absent. The id is the version-2 hash of the
+     * PLAINTEXT operation and is verified after decryption. Not part of the content hash.
+     * Protobuf operation field 16 (JSON).
+     */
+    encrypted?: EncryptedOperationEnvelope;
+}
+/**
+ * One AES-GCM ciphertext inside an {@link EncryptedOperationEnvelope}.
+ */
+interface EncryptedEnvelopeField {
+    /** Base64 12-byte IV, unique per field encryption. */
+    iv: string;
+    /** Base64 AES-GCM ciphertext including the 16-byte tag. */
+    ct: string;
+}
+/**
+ * Versioned end-to-end encryption envelope of an operation (protocol v2, ENC-3,
+ * NEW-ENC-1). Each encrypted member is bound by AES-GCM additional authenticated data
+ * to canonical(nodeId, collection, recordId, type, timestamp, sequenceNumber, field,
+ * keyVersion), so a ciphertext cannot be moved to another operation, record or field.
+ */
+interface EncryptedOperationEnvelope {
+    /** Envelope format version. 2 is the only defined value. */
+    v: 2;
+    /** Cipher. Only AES-256-GCM is defined. */
+    alg: 'aes-256-gcm';
+    /**
+     * Identifier of the key material (key-derivation salt fingerprint), so a device
+     * holding different key material reports a diagnosable mismatch instead of a bare
+     * authentication failure (ENC-1 key distribution is still to come).
+     */
+    keyId: string;
+    /** Key version used (rotation). */
+    keyVersion: number;
+    /** Ciphertext of `data`, or null when the plaintext `data` is null. */
+    data: EncryptedEnvelopeField | null;
+    /** Ciphertext of `previousData`, or null when it is null. */
+    previousData: EncryptedEnvelopeField | null;
+    /** Ciphertext of `atomicOps`, present only when the plaintext operation had them. */
+    atomicOps?: EncryptedEnvelopeField;
+}
+/**
+ * Input for creating an operation (before id and timestamp are assigned).
+ */
+interface OperationInput {
+    nodeId: string;
+    type: OperationType;
+    collection: string;
+    recordId: string;
+    data: Record<string, unknown> | null;
+    previousData: Record<string, unknown> | null;
+    sequenceNumber: number;
+    causalDeps: string[];
+    schemaVersion: number;
+    /** Atomic operation intents for fields in data (e.g., increment, max). */
+    atomicOps?: Record<string, AtomicOp>;
+    /** Groups this operation with others in an atomic transaction. Not part of the content hash. */
+    transactionId?: string;
+    /** Human-readable name for the mutation group (e.g., 'complete-sale'). For DevTools display. */
+    mutationName?: string;
+}
+/** Version vector: maps nodeId to the max sequence number seen from that node */
+type VersionVector = Map<string, number>;
+/** Field kinds supported by the schema system */
+type FieldKind = 'string' | 'number' | 'boolean' | 'timestamp' | 'richtext' | 'enum' | 'array' | 'object' | 'json' | 'blob' | 'secret';
+/**
+ * How a `secret` field's value is protected at rest.
+ * - `hashed`: one-way (passwords). Stored as a salted hash; never read back.
+ * - `encrypted`: reversible (tokens, keys). Stored as ciphertext; decrypted to use.
+ */
+type SecretMode = 'hashed' | 'encrypted';
+/**
+ * A content-addressed reference to binary data stored out of band.
+ *
+ * A `blob` field never carries the bytes in the operation log; it carries this
+ * small reference. The bytes live in a content-addressed blob store, keyed by
+ * `hash`, so identical content is stored once and never re-synced to a peer that
+ * already has that hash.
+ */
+interface BlobRef {
+    /** Hex-encoded SHA-256 hash of the bytes. The content address. */
+    hash: string;
+    /** Size of the bytes in bytes. */
+    size: number;
+    /** Optional MIME type (for example "image/png"). */
+    mimeType?: string;
+    /** Optional original filename. */
+    filename?: string;
+    /**
+     * Hex-encoded SHA-256 hash of this blob's manifest — the small chunk index a
+     * peer fetches first to learn how to pull the bytes out of band. Present when
+     * the blob was stored for transfer; absent for a bare reference created without
+     * chunking. Because it is a content address like `hash`, the manifest is fetched
+     * and integrity-verified over the same channel as the chunks.
+     */
+    manifestHash?: string;
+}
+/**
+ * Comprehensive sync diagnostics snapshot.
+ * Provides connection, latency, throughput, queue, and error metrics
+ * for monitoring and DevTools integration.
+ */
+interface SyncDiagnosticsSnapshot {
+    /** Current developer-facing sync status */
+    status: 'connected' | 'reconnecting' | 'syncing' | 'synced' | 'offline' | 'error' | 'schema-mismatch' | 'clock-error' | 'auth-required' | 'encryption-locked';
+    /** Timestamp when the current connection was established, or null if disconnected */
+    connectedAt: number | null;
+    /** Timestamp when the last disconnection occurred, or null if never disconnected */
+    disconnectedAt: number | null;
+    /** Number of reconnection attempts since last successful connection */
+    reconnectAttempts: number;
+    /** Current round-trip time in milliseconds */
+    rttMs: number;
+    /** Median (50th percentile) RTT over the sliding window */
+    rttP50Ms: number;
+    /** 95th percentile RTT over the sliding window */
+    rttP95Ms: number;
+    /** 99th percentile RTT over the sliding window */
+    rttP99Ms: number;
+    /** Total operations sent during this session */
+    operationsSent: number;
+    /** Total operations received during this session */
+    operationsReceived: number;
+    /** Total bytes sent during this session */
+    bytesSent: number;
+    /** Total bytes received during this session */
+    bytesReceived: number;
+    /** Number of operations waiting to be sent */
+    pendingOperations: number;
+    /** Estimated bytes in the outbound queue */
+    outboundQueueSize: number;
+    /** Timestamp of the last successful sync, or null if never synced */
+    lastSyncedAt: number | null;
+    /** Duration of the last complete sync cycle in ms, or null if no cycle completed */
+    syncDuration: number | null;
+    /** Whether the initial sync (full delta exchange) has completed */
+    initialSyncComplete: boolean;
+    /** Progress of the initial sync as a 0-1 ratio */
+    initialSyncProgress: number;
+    /** Description of the last error, or null if no error occurred */
+    lastError: string | null;
+    /** Total number of errors during this session */
+    errorCount: number;
+    /** Assessed connection quality level */
+    quality: 'excellent' | 'good' | 'fair' | 'poor' | 'offline';
+    /** Estimated effective bandwidth in bytes per second, or null if not yet measured */
+    effectiveBandwidth: number | null;
+}
+/** Built-in field merge strategies that can be declared in the schema. */
+type FieldMergeStrategy = 'lww' | 'counter' | 'max' | 'min' | 'union' | 'append-only' | 'server-authoritative';
+/** Map of state to allowed next states for state machine constraints */
+type TransitionMap = Record<string, string[]>;
+/**
+ * A state machine constraint extracted from the schema.
+ * Used by merge and validation to enforce valid state transitions.
+ */
+interface StateMachineConstraint {
+    /** The enum field this constraint controls */
+    field: string;
+    /** The collection this constraint applies to */
+    collection: string;
+    /** Map of state to allowed next states */
+    transitions: TransitionMap;
+}
+/**
+ * Result of validating a state transition.
+ */
+interface TransitionValidationResult {
+    /** Whether the transition is allowed */
+    valid: boolean;
+    /** The source state */
+    from: string;
+    /** The target state */
+    to: string;
+    /** The field being transitioned */
+    field: string;
+    /** The collection containing the field */
+    collection: string;
+    /** All allowed target states from the source state */
+    allowedTargets: string[];
+}
+/**
+ * Descriptor produced by the type builder (t.string(), t.number(), etc.).
+ * Represents a fully configured field definition.
+ */
+interface FieldDescriptor {
+    kind: FieldKind;
+    required: boolean;
+    defaultValue: unknown;
+    auto: boolean;
+    enumValues: readonly string[] | null;
+    itemKind: FieldKind | null;
+    /** Declared merge strategy. Defaults to kind-appropriate strategy when undefined. */
+    mergeStrategy: FieldMergeStrategy | null;
+    /** State machine transition map for enum fields. Null if no transitions declared. */
+    transitions: TransitionMap | null;
+    /**
+     * Nested field descriptors for `object` fields (each key merges by its own
+     * kind). Null for `json` fields (dynamic keys, resolved structurally) and for
+     * all non-structured kinds.
+     */
+    nestedFields?: Record<string, FieldDescriptor> | null;
+    /**
+     * At-rest protection mode for `secret` fields (`hashed` or `encrypted`).
+     * Null/absent for every other kind.
+     */
+    secretMode?: SecretMode | null;
+}
+/**
+ * Defines a state machine on an enum field, constraining valid state transitions.
+ *
+ * When a state machine is defined on a collection, mutations and merges
+ * enforce that the controlled field only moves along declared transitions.
+ *
+ * @example
+ * ```typescript
+ * stateMachine: {
+ *   field: 'status',
+ *   transitions: {
+ *     draft: ['pending', 'cancelled'],
+ *     pending: ['confirmed', 'cancelled'],
+ *     confirmed: ['shipped'],
+ *     shipped: ['delivered'],
+ *     delivered: [],
+ *     cancelled: [],
+ *   },
+ *   onInvalidTransition: 'reject',
+ * }
+ * ```
+ */
+interface StateMachineDefinition {
+    /** The enum field this state machine controls */
+    field: string;
+    /** Map of state to allowed next states */
+    transitions: Record<string, string[]>;
+    /** What to do when an invalid transition is attempted */
+    onInvalidTransition: 'reject' | 'last-valid-state';
+}
+/**
+ * Definition of a collection within the schema.
+ */
+interface CollectionDefinition {
+    fields: Record<string, FieldDescriptor>;
+    indexes: string[];
+    constraints: Constraint[];
+    resolvers: Record<string, CustomResolver>;
+    /** Scope fields for sync filtering. Only records matching the client's scope values are synced. */
+    scope: string[];
+    /** Optional state machine constraining transitions on an enum field */
+    stateMachine?: StateMachineDefinition;
+}
+/** Custom resolver function for tier 3 merge resolution */
+type CustomResolver = (local: unknown, remote: unknown, base: unknown) => unknown;
+/**
+ * Constraint for tier 2 conflict resolution.
+ */
+interface Constraint {
+    type: 'unique' | 'capacity' | 'referential';
+    fields: string[];
+    where?: Record<string, unknown>;
+    onConflict: 'first-write-wins' | 'last-write-wins' | 'priority-field' | 'server-decides' | 'custom';
+    priorityField?: string;
+    resolve?: (local: unknown, remote: unknown, base: unknown) => unknown;
+}
+/** Relation type between collections */
+type RelationType = 'one-to-one' | 'one-to-many' | 'many-to-one' | 'many-to-many';
+/** On-delete behavior for relations */
+type OnDeleteAction = 'cascade' | 'set-null' | 'restrict' | 'no-action';
+/**
+ * Definition of a relation between two collections.
+ */
+interface RelationDefinition {
+    from: string;
+    to: string;
+    type: RelationType;
+    field: string;
+    onDelete: OnDeleteAction;
+}
+/**
+ * Declarative sync filter for a collection.
+ *
+ * `where` maps record field names to scope value keys. Use `true` to bind a field
+ * to a scope value with the same name (e.g. `{ userId: true }`).
+ */
+interface SyncRuleDefinition {
+    where: Record<string, string>;
+}
+/**
+ * The complete schema definition produced by defineSchema().
+ */
+interface SchemaDefinition {
+    version: number;
+    collections: Record<string, CollectionDefinition>;
+    relations: Record<string, RelationDefinition>;
+    /** Schema migrations keyed by target version. */
+    migrations: Record<number, MigrationDefinition>;
+    /**
+     * Declarative partial-sync rules per collection.
+     * When present, only listed collections (plus legacy `scope` collections) sync.
+     */
+    sync?: Record<string, SyncRuleDefinition>;
+}
+/**
+ * Merge strategies available for auto-merge and constraints.
+ */
+declare const MERGE_STRATEGIES: readonly ["auto-merge", "lww", "first-write-wins", "server-decides", "custom"];
+type MergeStrategy = (typeof MERGE_STRATEGIES)[number];
+/**
+ * Connection quality levels for adaptive sync.
+ */
+declare const CONNECTION_QUALITIES: readonly ["excellent", "good", "fair", "poor", "offline"];
+type ConnectionQuality = (typeof CONNECTION_QUALITIES)[number];
+/**
+ * Injectable time source for deterministic testing of clocks.
+ */
+interface TimeSource {
+    now(): number;
+}
+/**
+ * Injectable random source for deterministic testing of UUID generation.
+ */
+interface RandomSource {
+    getRandomValues<T extends ArrayBufferView>(array: T): T;
+}
+/**
+ * Configuration for an offline-safe sequence.
+ *
+ * Sequences produce monotonically increasing, collision-free identifiers
+ * that work across offline devices. Each device maintains its own counter
+ * scoped by (name, scope, nodeId).
+ *
+ * Format tokens available:
+ * - `{date}` → YYYYMMDD
+ * - `{node4}` → first 4 chars of nodeId
+ * - `{node8}` → first 8 chars of nodeId
+ * - `{seq}` → zero-padded counter (4 digits)
+ * - `{seq:N}` → zero-padded counter with N digits
+ *
+ * @example
+ * ```typescript
+ * await app.sequences.next('receipt', {
+ *   scope: storeId,
+ *   format: 'S-{date}-{node4}-{seq}',
+ * })
+ * // → "S-20260508-a1b2-0042"
+ * ```
+ */
+interface SequenceConfig {
+    /** Namespace within the sequence (e.g., a storeId or orgId). Defaults to ''. */
+    scope?: string;
+    /** Format template. Defaults to `{name}-{seq:4}`. */
+    format?: string;
+    /** Starting counter value. Defaults to 1. */
+    startAt?: number;
+}
+
+interface SyncApplyFailureEvent {
+    operationId: string;
+    collection: string;
+    recordId: string;
+    code: string;
+    message: string;
+    retriable: boolean;
+    firstSeenAt: number;
+    retryCount: number;
+}
+/**
+ * Trace of a merge decision. Records all inputs and outputs for debugging and DevTools.
+ */
+interface MergeTrace {
+    operationA: Operation;
+    operationB: Operation;
+    field: string;
+    strategy: string;
+    inputA: unknown;
+    inputB: unknown;
+    base: unknown | null;
+    output: unknown;
+    tier: 1 | 2 | 3;
+    constraintViolated: string | null;
+    duration: number;
+}
+/**
+ * All events emitted by the Kora framework.
+ * These are consumed by DevTools and can be observed by the developer.
+ */
+type KoraEvent = {
+    type: 'operation:created';
+    operation: Operation;
+} | {
+    type: 'operation:applied';
+    operation: Operation;
+    duration: number;
+} | {
+    type: 'merge:started';
+    operationA: Operation;
+    operationB: Operation;
+} | {
+    type: 'merge:completed';
+    trace: MergeTrace;
+} | {
+    type: 'merge:conflict';
+    trace: MergeTrace;
+} | {
+    type: 'constraint:violated';
+    constraint: string;
+    trace: MergeTrace;
+} | {
+    type: 'sync:connected';
+    nodeId: string;
+} | {
+    type: 'sync:disconnected';
+    reason: string;
+} | {
+    type: 'sync:schema-mismatch';
+    clientSchemaVersion: number;
+    serverSchemaVersion: number;
+    supportedMin: number;
+    supportedMax: number;
+    reason: string;
+} | {
+    /**
+     * A sync peer speaks an older, deprecated protocol version (protocol v2): a
+     * server emits it for a protocol-1 client (Kora <= beta.12), accepted with this
+     * deprecation in beta.13 and beta.14. `message` says what to upgrade.
+     */
+    type: 'sync:protocol-deprecated';
+    nodeId: string;
+    clientProtocolVersion: number;
+    serverProtocolVersion: number;
+    message: string;
+} | {
+    /**
+     * A server stored a protocol-1 (Kora <= beta.12) client's operation whose
+     * version-1 id it could not verify (RT-71: beta.12 hashed `undefined` members
+     * as `null`, which the JSON upload no longer holds). Counted in metrics.
+     */
+    type: 'sync:unverified-legacy-operation';
+    nodeId: string;
+    operationId: string;
+    collection: string;
+    message: string;
+} | {
+    /**
+     * A server refused an upload that reused a stored operation's id with different
+     * content (RT-77). Operation ids are content hashes, so this is tampering; the
+     * upload had no effect. Counted in metrics.
+     */
+    type: 'sync:forged-duplicate';
+    nodeId: string;
+    operationId: string;
+    collection: string;
+    message: string;
+} | {
+    type: 'sync:auth-failed';
+    reason: string;
+} | {
+    type: 'sync:suspended';
+    reason: 'auth-loading' | 'auth-required' | 'auth-rejected' | 'device-revoked' | string;
+} | {
+    type: 'sync:apply-blocked';
+    failure: SyncApplyFailureEvent;
+} | {
+    type: 'sync:apply-retrying';
+    failure: SyncApplyFailureEvent;
+} | {
+    type: 'sync:apply-recovered';
+    failure: SyncApplyFailureEvent;
+} | {
+    type: 'sync:apply-abandoned';
+    failure: SyncApplyFailureEvent;
+} | {
+    /**
+     * End-to-end encryption keyring status changed (ENC-1): locked (no passphrase,
+     * a wrong one, or a key record that must not be used), unlocking, unlocked.
+     * While not unlocked, sync is paused; local reads and writes continue.
+     */
+    type: 'encryption:status';
+    status: {
+        state: 'locked' | 'unlocking' | 'unlocked' | 'error';
+        keyring: string;
+        keyVersion: number | null;
+        code?: string;
+        message?: string;
+    };
+} | {
+    type: 'sync:clock-skew';
+    /** serverTime - localTime in ms. Negative = this device's clock is fast. */
+    skewMs: number;
+    severity: 'info' | 'slow-warning' | 'fast-blocked';
+    source: 'handshake' | 'server-reject';
+} | {
+    /**
+     * The server refused this device's node id (`NODE_ID_CLAIMED`, RT-21), so the
+     * device moved to a fresh node id and re-queued its unsynced writes under it.
+     */
+    type: 'sync:node-id-rotated';
+    previousNodeId: string;
+    nodeId: string;
+    /** Unsynced operations re-authored under the new node id. */
+    reenqueuedCount: number;
+    /**
+     * Unsynced operations left under the previous node id, held for the principal
+     * that owns it (RT-38): they upload when that user signs in again on this device.
+     */
+    heldCount?: number;
+} | {
+    /**
+     * Sync bookkeeping of one of this database's own node ids (Phase 2):
+     * - `history-behind`: the server holds more of this node's operations than the
+     *   device (its log lost a tail, RT-35); the counter was raised past them and a
+     *   full resync fetches them back.
+     * - `adoption-started` / `adoption-completed` / `adoption-refused`: the engine
+     *   uploads the unsynced writes of a node no live tab uses (RT-40).
+     * - `held`: the server refused this node for the signed-in principal; its unsynced
+     *   writes wait for the principal that owns it (RT-38).
+     * - `server-behind`: the server holds fewer of this node's operations than the
+     *   device had acknowledged (a server restored from a backup, RT-45); the device
+     *   re-uploads them from the server's position.
+     * - `adoption-parked`: an adopted node made no upload progress for a whole session
+     *   (for example a write the server keeps deferring); the next session tries the
+     *   other nodes first (RT-46).
+     * - `clone-detected`: another live copy of this database uses the same node id
+     *   (copied app data, a restored image); this copy moved to a fresh node id (RT-44).
+     * - `principal-switched`: the signed-in user changed; local writes from now on are
+     *   authored under that user's own node (RT-42).
+     * - `held-assigned` / `held-discarded`: the app assigned a held node's writes to
+     *   the signed-in user, or discarded them from sync (RT-50).
+     */
+    type: 'sync:local-node';
+    nodeId: string;
+    action: 'history-behind' | 'server-behind' | 'adoption-started' | 'adoption-completed' | 'adoption-refused' | 'adoption-parked' | 'held' | 'clone-detected' | 'principal-switched' | 'held-assigned' | 'held-discarded';
+    /** For `history-behind` / `server-behind`: the device's sequence and the server's. */
+    localSequence?: number;
+    serverSequence?: number;
+    /** Unsynced operations concerned, when known. */
+    operationCount?: number;
+} | {
+    type: 'sync:clock-rebase';
+    /** Number of unsynced operations that were re-stamped. */
+    rebasedCount: number;
+    /** How far ahead of server time the most future queued operation was, in ms. */
+    maxSkewMs: number;
+} | {
+    type: 'sync:sent';
+    operations: Operation[];
+    batchSize: number;
+} | {
+    type: 'sync:received';
+    operations: Operation[];
+    batchSize: number;
+    /** Server-ingest outcomes. Omitted for ordinary client-side receive events. */
+    uniqueOperations?: number;
+    duplicateOperations?: number;
+    rejectedOperations?: number;
+} | {
+    type: 'sync:acknowledged';
+    sequenceNumber: number;
+} | {
+    type: 'sync:scope-retracted';
+    collection: string;
+    recordId: string;
+    quarantinedOperationIds: string[];
+} | {
+    type: 'sync:apply-failed';
+    operationId: string;
+    collection: string;
+    recordId: string;
+    code: string;
+    message: string;
+    retriable: boolean;
+} | {
+    /**
+     * The server rejected one of THIS client's outbound operations before it
+     * became authoritative. The op has been diverted out of the pending sync
+     * queue into the durable rejected store (kept, not retried); the app can
+     * surface the reason and decide whether to roll back the optimistic local
+     * write or let the user edit and resubmit.
+     */
+    type: 'sync:operation-rejected';
+    operationId: string;
+    collection: string;
+    recordId: string;
+    code: string;
+    message: string;
+    retriable: boolean;
+} | {
+    type: 'sync:delivery-gap';
+    expectedBase: number;
+    receivedBase: number;
+    currentWatermark: number;
+    messageId: string;
+    repeatCount: number;
+} | {
+    type: 'sync:delivery-stalled';
+    sessionId: string;
+    watermark: number;
+    outstandingMaxDeliverySequence: number;
+    repeatCount: number;
+    reason: 'unacknowledged-delivery';
+} | {
+    type: 'query:subscribed';
+    queryId: string;
+    collection: string;
+} | {
+    type: 'query:invalidated';
+    queryId: string;
+    trigger: Operation;
+} | {
+    type: 'query:executed';
+    queryId: string;
+    duration: number;
+    resultCount: number;
+} | {
+    /**
+     * A reactive query subscription failed (STORE-12). `phase` is `initial` (the
+     * first run), `refresh` (a re-run after a write) or `callback` (the
+     * subscriber's callback threw). The subscription stays registered and keeps
+     * its last results; the subscriber's `onError` receives the same failure.
+     */
+    type: 'query:error';
+    queryId: string;
+    collection: string;
+    phase: 'initial' | 'refresh' | 'callback';
+    code: string;
+    message: string;
+} | {
+    /**
+     * Durable-storage (`navigator.storage.persist`) state (NEW-STORE-4).
+     * `checked`: the boot-time `persisted()` read, which never prompts.
+     * `requested`: the outcome of an explicit `app.storage.persistence.request()`.
+     * `unsupported`: the runtime has no StorageManager persistence API.
+     * `error`: the check or request threw (`message` says why).
+     */
+    type: 'storage:persistence';
+    state: 'checked' | 'requested' | 'unsupported' | 'error';
+    persisted: boolean;
+    message?: string;
+} | {
+    type: 'connection:quality';
+    quality: ConnectionQuality;
+} | {
+    type: 'sync:diagnostics';
+    diagnostics: SyncDiagnosticsSnapshot;
+} | {
+    type: 'sync:bandwidth';
+    bytesPerSecond: number;
+    direction: 'in' | 'out';
+} | {
+    type: 'sync:initial-sync-progress';
+    progress: number;
+    totalBatches: number;
+    receivedBatches: number;
+} | {
+    type: 'awareness:updated';
+    states: Map<number, unknown>;
+} | {
+    type: 'state-machine:transition';
+    collection: string;
+    recordId: string;
+    from: string;
+    to: string;
+    valid: boolean;
+} | {
+    type: 'state-machine:rejected';
+    collection: string;
+    recordId: string;
+    from: string;
+    to: string;
+    allowed: string[];
+} | {
+    type: 'store:persistence-error';
+    dbName: string;
+    message: string;
+    code: string;
+} | {
+    /**
+     * The local database could not be made durable before an upload several times in
+     * a row (storage quota exceeded, IndexedDB broken; RT-49). Uploads no longer wait
+     * for it, so the server holds the only durable copy of new writes (a reload
+     * recovers them from it) until `sync:durability-restored`. Writes are still
+     * accepted; warn the user (free up storage, stay online).
+     */
+    type: 'sync:durability-degraded';
+    message: string;
+    failedAttempts: number;
+} | {
+    type: 'sync:durability-restored';
+} | {
+    type: 'store:quota-exceeded';
+    dbName: string;
+    message: string;
+} | {
+    /**
+     * The log-integrity scan (W8 step 0) changed the operation log: it repaired rows
+     * written by an earlier release (a JSON-encoded timestamp from a beta.12 backup
+     * restore) and/or moved rows it could not repair to the quarantine table, where
+     * no fold reads them. `clean` is false while anything is quarantined or this
+     * database's own nodes have sequence gaps. See `store.verifyLogIntegrity()`.
+     */
+    type: 'store:log-integrity';
+    dbName: string;
+    repaired: number;
+    quarantined: number;
+    gaps: number;
+    clean: boolean;
+    message: string;
+} | {
+    /**
+     * The database was re-materialized with the W7 per-field fold (once, on the
+     * first open with fold-state version N, or after a replace-mode restore).
+     * `mode`: `'log'` rebuilt every record from its clean log (repairing
+     * pre-W7 divergence); `'snapshot+log'` used each row as a base snapshot
+     * because the log was compacted or has gaps; `'kept'` left every row as it
+     * was because the log has quarantined rows (never rebuilt from).
+     */
+    type: 'store:rematerialized';
+    dbName: string;
+    mode: 'log' | 'snapshot+log' | 'kept';
+    records: number;
+    changedRows: number;
+    message: string;
+} | {
+    /**
+     * OPFS persistence was unavailable, so the store fell back to a
+     * NON-PERSISTENT in-memory database. Anything written this session is lost
+     * on reload. This is emitted instead of failing silently so the condition
+     * is observable rather than a data-loss trap.
+     */
+    type: 'store:opfs-unavailable';
+    dbName: string;
+    /**
+     * Why OPFS could not be used. `lock-conflict` means another runtime on this
+     * origin already holds the OPFS pool for this database; `timeout` means the
+     * VFS install did not complete in time (common in headless CI); `unsupported`
+     * means the runtime has no usable OPFS.
+     */
+    reason: 'lock-conflict' | 'timeout' | 'unsupported';
+    message: string;
+} | {
+    /**
+     * BLOCKING. The local database was already migrated by a NEWER build of the app
+     * (its stored schema version is above this code's `schema.version`), for example
+     * an old build served offline after an update ran (RT-109). The store refuses to
+     * open it (`SchemaVersionAheadError`, `app.ready` rejects) and changes nothing in
+     * it. Apps should ask the user to reload online so the newer build runs.
+     */
+    type: 'store:schema-ahead';
+    dbName: string;
+    /** The schema version stored in the database */
+    storedVersion: number;
+    /** This code's `schema.version` */
+    codeVersion: number;
+    message: string;
+} | {
+    /**
+     * A preferred storage backend could not provide durable storage, so Kora
+     * promoted the app to another durable backend before user code observed the
+     * store. This is informational: data still survives reloads.
+     */
+    type: 'store:storage-fallback';
+    dbName: string;
+    from: 'opfs' | 'sqlite-wasm';
+    to: 'indexeddb';
+    reason: 'lock-conflict' | 'timeout' | 'unsupported';
+    message: string;
+} | {
+    /**
+     * BLOCKING. The store could not obtain durable storage when it opened or when
+     * this tab was promoted to storage leader, so it is running on a
+     * non-persistent in-memory database. Writes are refused with
+     * `StorageDurabilityError` (unless the app opted into non-durable storage)
+     * instead of being accepted and lost on reload. Apps should show a blocking
+     * state, for example asking the user to close other tabs and reload.
+     */
+    type: 'store:durability-lost';
+    dbName: string;
+    phase: 'open' | 'promotion';
+    reason: 'lock-conflict' | 'timeout' | 'unsupported' | 'open-failed';
+    message: string;
+} | {
+    /**
+     * BLOCKING while `state` is `waiting`. Another holder (a previous storage
+     * owner still shutting down, or a tab running an older Kora that does not
+     * take part in the ownership protocol) has the database's OPFS storage, so
+     * the open waits instead of falling back to non-durable storage. Apps
+     * should show a "close other tabs of this app" state; `resolved` follows
+     * when the wait ends.
+     */
+    type: 'store:storage-blocked';
+    dbName: string;
+    /** `pool`: the database's own pool; `legacy-pool`: the pre-W8a shared pool. */
+    resource: 'pool' | 'legacy-pool';
+    state: 'waiting' | 'resolved';
+    waitedMs?: number;
+    message: string;
+} | {
+    /**
+     * Informational. The database's data was moved between storage locations
+     * explicitly (the pre-W8a shared OPFS pool to the database's own pool, or
+     * between OPFS and IndexedDB), so there is still exactly one copy.
+     */
+    type: 'store:storage-migrated';
+    dbName: string;
+    from: 'legacy-opfs-pool' | 'opfs' | 'indexeddb';
+    to: 'opfs' | 'indexeddb';
+    message: string;
+} | {
+    /**
+     * Another runtime on this origin was already using this database name, so
+     * this runtime attached to it as a follower and now SHARES that one
+     * database. That is intended for multiple tabs of the SAME app; it is a bug
+     * if these are logically separate apps, which should each use a distinct
+     * store name (`store: { name: '...' }`) to stay isolated.
+     */
+    type: 'store:db-name-collision';
+    dbName: string;
+    message: string;
+} | {
+    type: 'replay:completed';
+    targetOperationId: string;
+    operationsApplied: number;
+    duration: number;
+};
+/** Extract the event type string union from KoraEvent */
+type KoraEventType = KoraEvent['type'];
+/** Extract a specific event by its type */
+type KoraEventByType<T extends KoraEventType> = Extract<KoraEvent, {
+    type: T;
+}>;
+/** Listener function for a specific event type */
+type KoraEventListener<T extends KoraEventType> = (event: KoraEventByType<T>) => void;
+/**
+ * Event emitter interface for the Kora framework.
+ * All packages that emit events must implement this interface.
+ */
+interface KoraEventEmitter {
+    on<T extends KoraEventType>(type: T, listener: KoraEventListener<T>): () => void;
+    off<T extends KoraEventType>(type: T, listener: KoraEventListener<T>): void;
+    emit<T extends KoraEventType>(event: KoraEventByType<T>): void;
+}
+
+export { type MergeStrategy as $, type AtomicOp as A, type BlobRef as B, type CollectionDefinition as C, type InferInsert as D, type EncryptedEnvelopeField as E, FieldBuilder as F, type InferInsertInput as G, type HLCTimestamp as H, type InferFieldInput as I, type InferRecord as J, type InferRecordField as K, type InferUpdate as L, type MergeTrace as M, type InferUpdateField as N, type OperationInput as O, type InferUpdateInput as P, JsonFieldBuilder as Q, type RandomSource as R, type SchemaDefinition as S, type TransitionMap as T, type KoraEvent as U, type VersionVector as V, type KoraEventByType as W, type KoraEventEmitter as X, type KoraEventListener as Y, type KoraEventType as Z, MERGE_STRATEGIES as _, type Operation as a, MigrationBuilder as a0, type NumericAtomicOpSentinel as a1, ObjectFieldBuilder as a2, type ObjectFieldValue as a3, type OnDeleteAction as a4, type RelationDefinition as a5, type RelationType as a6, type RichtextInput as a7, RollbackBuilder as a8, type ScalarFieldBuilder as a9, type ScalarFieldKind as aa, SecretFieldBuilder as ab, type SecretMode as ac, type SequenceConfig as ad, type Simplify as ae, type StateMachineDefinition as af, type SyncDiagnosticsSnapshot as ag, type SyncRuleDefinition as ah, type TimeSource as ai, applyAtomicOp as aj, isAtomicOp as ak, migrate as al, op as am, resolveAtomicOp as an, t as ao, toAtomicOp as ap, type CustomResolver as b, type MigrationDefinition as c, type FieldDescriptor as d, type OperationType as e, type MigrationStep as f, type StateMachineConstraint as g, type TransitionValidationResult as h, type ArrayAtomicOpSentinel as i, ArrayFieldBuilder as j, type AtomicOpSentinel as k, type AtomicOpType as l, type BackfillOptions as m, CONNECTION_QUALITIES as n, type ConnectionQuality as o, type Constraint as p, type EncryptedOperationEnvelope as q, EnumFieldBuilder as r, type FieldInput as s, type FieldKind as t, type FieldKindToType as u, type FieldMap as v, type FieldMergeStrategy as w, type FieldOutput as x, type FieldTypeInfo as y, type InferFieldType as z };