@korajs/core 0.3.2 → 0.5.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { R as RandomSource, F as FieldKind, a as FieldDescriptor, C as CustomResolver, S as SchemaDefinition, b as CollectionDefinition, c as RelationDefinition, O as OperationType, d as Operation, V as VersionVector } from './events-7Fhdjxd2.js';
-export { e as CONNECTION_QUALITIES, f as ConnectionQuality, g as Constraint, H as HLCTimestamp, h as HybridLogicalClock, K as KoraEvent, i as KoraEventByType, j as KoraEventEmitter, k as KoraEventListener, l as KoraEventType, M as MERGE_STRATEGIES, m as MergeStrategy, n as MergeTrace, o as OnDeleteAction, p as OperationInput, q as RelationType, T as TimeSource, r as createOperation, s as isValidOperation, v as verifyOperationIntegrity } from './events-7Fhdjxd2.js';
+import { R as RandomSource, A as AtomicOpType, a as AtomicOp, F as FieldBuilder, C as CustomResolver, M as MigrationDefinition, S as SchemaDefinition, b as CollectionDefinition, c as RelationDefinition, O as OperationType, E as EnumFieldBuilder, 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-BeIEDJBW.js';
+export { j as CONNECTION_QUALITIES, k as ConnectionQuality, l as Constraint, m as FieldDescriptor, n as FieldMergeStrategy, H as HLCTimestamp, o as HybridLogicalClock, K as KoraEvent, p as KoraEventByType, q as KoraEventEmitter, r as KoraEventListener, s as KoraEventType, t as MERGE_STRATEGIES, u as MergeStrategy, v as MergeTrace, w as MigrationBuilder, x as OnDeleteAction, y as OperationInput, z as RelationType, B as RollbackBuilder, D as SequenceConfig, G as StateMachineDefinition, I as SyncDiagnosticsSnapshot, J as SyncRuleDefinition, L as TimeSource, N as createOperation, P as isValidOperation, Q as migrate, U as t, W as verifyOperationIntegrity } from './events-BeIEDJBW.js';
 
 /**
  * Base error class for all Kora errors.
@@ -9,6 +9,10 @@ declare class KoraError extends Error {
     readonly code: string;
     readonly context?: Record<string, unknown> | undefined;
     constructor(message: string, code: string, context?: Record<string, unknown> | undefined);
+    /**
+     * Actionable hint for resolving this error (from registry or error context).
+     */
+    get fix(): string | undefined;
 }
 /**
  * Thrown when schema validation fails during defineSchema() or at app initialization.
@@ -65,6 +69,41 @@ declare class ClockDriftError extends KoraError {
     constructor(currentHlcTime: number, physicalTime: number);
 }
 
+/**
+ * Human-readable remediation hints keyed by {@link KoraError} `code`.
+ */
+declare const KORA_ERROR_FIX_SUGGESTIONS: Record<string, string>;
+/**
+ * Returns a suggested fix for a Kora error code, if one is known.
+ */
+declare function getKoraErrorFix(code: string): string | undefined;
+
+/**
+ * Tracks the latest operation per collection and within an open transaction
+ * to populate {@link Operation.causalDeps} for local mutations.
+ */
+declare class CausalTracker {
+    private readonly lastOpIdByCollection;
+    private lastTransactionOpId;
+    /**
+     * Start a new transaction boundary. Clears in-transaction op ids.
+     */
+    beginTransaction(): void;
+    /**
+     * Clear the transaction boundary without recording ops (after rollback).
+     */
+    clearTransaction(): void;
+    /**
+     * Compute causal dependencies for the next operation in a collection.
+     * Uses direct parents only: collection head and the previous op in the open transaction.
+     */
+    nextCausalDeps(collection: string, inTransaction: boolean): string[];
+    /**
+     * Record an operation after it has been created and assigned an id.
+     */
+    afterOperation(collection: string, operationId: string, inTransaction: boolean): void;
+}
+
 /**
  * Generates a UUID v7 per RFC 9562.
  * UUID v7 encodes a Unix timestamp in milliseconds in the most significant 48 bits,
@@ -98,88 +137,149 @@ declare function extractTimestamp(uuid: string): number;
 declare function isValidUUIDv7(uuid: string): boolean;
 
 /**
- * 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)
+ * Outcome of applying a single operation to materialized storage (local or remote).
+ */
+declare const APPLY_RESULTS: readonly ["applied", "duplicate", "skipped", "rejected", "deferred"];
+type ApplyResult = (typeof APPLY_RESULTS)[number];
+/**
+ * Structured failure metadata when apply returns `skipped`, `rejected`, or `deferred`.
+ */
+interface ApplyFailureReason {
+    code: string;
+    message: string;
+    retriable: boolean;
+}
+/** Well-known apply failure codes for DevTools and `sync:apply-failed` events. */
+declare const APPLY_FAILURE_CODES: {
+    readonly APPLY_FAILED: "APPLY_FAILED";
+    readonly APPLY_SKIPPED: "APPLY_SKIPPED";
+    readonly APPLY_REJECTED: "APPLY_REJECTED";
+    readonly APPLY_DEFERRED: "APPLY_DEFERRED";
+    readonly CLOCK_DRIFT: "CLOCK_DRIFT";
+    readonly REFERENTIAL_INTEGRITY: "REFERENTIAL_INTEGRITY";
+    readonly SCHEMA_MISMATCH: "SCHEMA_MISMATCH";
+};
+/**
+ * Returns true when the apply outcome should surface as a failure to the developer.
+ */
+declare function isApplyFailure(result: ApplyResult): boolean;
+/**
+ * Default failure metadata when the store does not attach a specific reason.
+ */
+declare function defaultApplyFailureReason(result: Exclude<ApplyResult, 'applied' | 'duplicate'>, overrides?: Partial<ApplyFailureReason>): ApplyFailureReason;
+
+/**
+ * Atomic field operations for intent-preserving updates.
  *
- * @example
+ * Instead of read-modify-write patterns, developers express intent:
  * ```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
+ * 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.
  */
-declare class FieldBuilder<Kind extends FieldKind = FieldKind, Req extends boolean = true, Auto extends boolean = false> {
-    protected readonly _kind: Kind;
-    protected readonly _required: boolean;
-    protected readonly _defaultValue: unknown;
-    protected readonly _auto: boolean;
-    constructor(kind: Kind, required?: Req, defaultValue?: unknown, auto?: Auto);
-    /** Mark this field as optional (not required on insert) */
-    optional(): FieldBuilder<Kind, false, Auto>;
-    /** Set a default value for this field. Implicitly makes the field optional. */
-    default(value: unknown): FieldBuilder<Kind, false, Auto>;
-    /** Mark this field as auto-populated (e.g., createdAt timestamps). Developers cannot set auto fields. */
-    auto(): FieldBuilder<Kind, false, true>;
-    /** @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.
+ * Sentinel marker for detecting atomic op objects in update data.
+ * Uses Symbol.for() so the sentinel survives module boundary crossings.
  */
-declare class EnumFieldBuilder<Values extends readonly string[] = readonly string[], Req extends boolean = true, Auto extends boolean = false> extends FieldBuilder<'enum', Req, Auto> {
-    private readonly _enumValues;
-    constructor(values: Values, required?: Req, defaultValue?: unknown, auto?: Auto);
-    optional(): EnumFieldBuilder<Values, false, Auto>;
-    default(value: Values[number]): EnumFieldBuilder<Values, false, Auto>;
-    auto(): EnumFieldBuilder<Values, false, true>;
-    _build(): FieldDescriptor;
-}
+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;
 /**
- * Field builder for array fields with a typed item kind.
- * Preserves the item kind type parameter for inference.
+ * Sentinel object returned by op.* helpers.
+ * Detected by Collection.update() and resolved to concrete values.
  */
-declare class ArrayFieldBuilder<ItemKind extends FieldKind = FieldKind, Req extends boolean = true, Auto extends boolean = false> extends FieldBuilder<'array', Req, Auto> {
-    private readonly _itemKind;
-    constructor(itemBuilder: FieldBuilder<ItemKind>, required?: Req, defaultValue?: unknown, auto?: Auto);
-    optional(): ArrayFieldBuilder<ItemKind, false, Auto>;
-    default(value: unknown[]): ArrayFieldBuilder<ItemKind, false, Auto>;
-    auto(): ArrayFieldBuilder<ItemKind, false, true>;
-    _build(): FieldDescriptor;
+interface AtomicOpSentinel {
+    readonly [KORA_ATOMIC_OP_KEY]: true;
+    readonly type: AtomicOpType;
+    readonly value: unknown;
 }
 /**
- * Type builder namespace. The developer's primary interface for defining field types.
+ * 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;
+/**
+ * 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 { 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'),
- *   createdAt: t.timestamp().auto(),
- * }
+ * 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 t: {
-    string(): FieldBuilder<"string", true, false>;
-    number(): FieldBuilder<"number", true, false>;
-    boolean(): FieldBuilder<"boolean", true, false>;
-    timestamp(): FieldBuilder<"timestamp", true, false>;
-    richtext(): FieldBuilder<"richtext", true, false>;
-    enum<const V extends readonly string[]>(values: V): EnumFieldBuilder<V, true, false>;
-    array<K extends FieldKind>(itemBuilder: FieldBuilder<K>): ArrayFieldBuilder<K, true, false>;
+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;
 };
+/**
+ * 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;
 
 /**
  * Input shape for defineSchema() — what the developer writes.
@@ -188,12 +288,49 @@ interface SchemaInput {
     version: number;
     collections: Record<string, CollectionInput>;
     relations?: Record<string, RelationInput>;
+    /** Schema migrations keyed by target version number. */
+    migrations?: Record<number, MigrationDefinition>;
+    /**
+     * Declarative partial-sync rules.
+     *
+     * @example
+     * ```typescript
+     * sync: {
+     *   todos: { where: { userId: true, orgId: true } },
+     *   projects: { where: { orgId: true } },
+     * }
+     * ```
+     */
+    sync?: Record<string, SyncRuleInput>;
+}
+/**
+ * Developer input for a collection sync rule.
+ */
+interface SyncRuleInput {
+    /**
+     * Field filters bound to scope values.
+     * Use `true` to bind a field to a scope value with the same name.
+     * Use a string to bind to a different scope value key.
+     */
+    where: Record<string, boolean | string>;
+}
+interface StateMachineInput {
+    /** 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';
 }
 interface CollectionInput {
     fields: Record<string, FieldBuilder<any, any, any>>;
     indexes?: string[];
     constraints?: ConstraintInput[];
     resolve?: Record<string, CustomResolver>;
+    /** Scope fields for sync filtering. Only records matching the client's scope values are synced. */
+    scope?: string[];
+    /** State machine definition constraining transitions on an enum field */
+    stateMachine?: StateMachineInput;
 }
 interface ConstraintInput {
     type: 'unique' | 'capacity' | 'referential';
@@ -292,15 +429,23 @@ interface FieldKindToType {
     number: number;
     boolean: boolean;
     timestamp: number;
-    richtext: Uint8Array;
+    richtext: string;
     enum: string;
     array: unknown[];
 }
 /**
- * Infers the TypeScript type for a single FieldBuilder.
- * Handles base fields, enums (with literal union), and arrays (with typed items).
+ * 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, infer _Req, infer _Auto> ? V[number] : F extends ArrayFieldBuilder<infer K, infer _Req, infer _Auto> ? FieldKindToType[K][] : F extends FieldBuilder<infer K, infer _Req, infer _Auto> ? FieldKindToType[K] : unknown;
+type InferFieldType<F> = F extends EnumFieldBuilder<infer V, any, any> ? V[number] : 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.
@@ -314,40 +459,22 @@ type InferRecord<Fields extends Record<string, FieldBuilder<any, any, any>>> = {
     readonly [K in keyof Fields]: Fields[K] extends FieldBuilder<any, true, any> ? InferFieldType<Fields[K]> : InferFieldType<Fields[K]> | null;
 };
 /**
- * Helper: extract keys where the field is required and not auto.
- */
-type RequiredInsertKeys<Fields extends Record<string, FieldBuilder<any, any, any>>> = {
-    [K in keyof Fields]: Fields[K] extends FieldBuilder<any, any, true> ? never : Fields[K] extends FieldBuilder<any, true, false> ? K : never;
-}[keyof Fields];
-/**
- * Helper: extract keys where the field is optional (not required) and not auto.
- */
-type OptionalInsertKeys<Fields extends Record<string, FieldBuilder<any, any, any>>> = {
-    [K in keyof Fields]: Fields[K] extends FieldBuilder<any, any, true> ? never : Fields[K] extends FieldBuilder<any, true, false> ? never : K;
-}[keyof Fields];
-/**
- * Infers the insert input type.
+ * 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
  */
 type InferInsertInput<Fields extends Record<string, FieldBuilder<any, any, any>>> = {
-    [K in RequiredInsertKeys<Fields> & string]: InferFieldType<Fields[K]>;
+    [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 OptionalInsertKeys<Fields> & string]?: 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]>;
 };
 /**
- * Helper: extract keys where the field is not auto.
- */
-type NonAutoKeys<Fields extends Record<string, FieldBuilder<any, any, any>>> = {
-    [K in keyof Fields]: Fields[K] extends FieldBuilder<any, any, true> ? never : K;
-}[keyof Fields];
-/**
- * Infers the update input type.
+ * Infers the update input type using inline key remapping.
  * All non-auto fields are optional (partial update semantics).
  */
 type InferUpdateInput<Fields extends Record<string, FieldBuilder<any, any, any>>> = {
-    [K in NonAutoKeys<Fields> & string]?: InferFieldType<Fields[K]>;
+    [K in keyof Fields as Fields[K] extends FieldBuilder<any, any, true> ? never : K]?: InferFieldType<Fields[K]>;
 };
 
 /**
@@ -375,9 +502,10 @@ declare function dominates(a: VersionVector, b: VersionVector): boolean;
 declare function vectorsEqual(a: VersionVector, b: VersionVector): boolean;
 /**
  * Operation log interface for computing deltas.
+ * getRange may be async (for DB-backed implementations) or sync (for in-memory).
  */
 interface OperationLog {
-    getRange(nodeId: string, fromSeq: number, toSeq: number): Operation[];
+    getRange(nodeId: string, fromSeq: number, toSeq: number): Operation[] | Promise<Operation[]>;
 }
 /**
  * Compute the operations that `local` has but `remote` does not.
@@ -388,7 +516,7 @@ interface OperationLog {
  * @param operationLog - The operation log to fetch operations from
  * @returns Operations sorted in causal order
  */
-declare function computeDelta(localVector: VersionVector, remoteVector: VersionVector, operationLog: OperationLog): Operation[];
+declare function computeDelta(localVector: VersionVector, remoteVector: VersionVector, operationLog: OperationLog): Promise<Operation[]>;
 /**
  * Serialize a version vector to a JSON-compatible string.
  */
@@ -398,4 +526,342 @@ declare function serializeVector(vector: VersionVector): string;
  */
 declare function deserializeVector(s: string): VersionVector;
 
-export { ArrayFieldBuilder, ClockDriftError, CollectionDefinition, type CollectionInput, type ConstraintInput, CustomResolver, EnumFieldBuilder, FieldBuilder, FieldDescriptor, FieldKind, type FieldKindToType, type InferFieldType, type InferInsertInput, type InferRecord, type InferUpdateInput, KoraError, MergeConflictError, Operation, OperationError, type OperationLog, OperationType, RandomSource, RelationDefinition, type RelationInput, SchemaDefinition, type SchemaInput, SchemaValidationError, StorageError, SyncError, type TypedSchemaDefinition, VersionVector, advanceVector, computeDelta, createVersionVector, defineSchema, deserializeVector, dominates, extractTimestamp, generateFullDDL, generateSQL, generateUUIDv7, isValidUUIDv7, mergeVectors, serializeVector, t, validateRecord, vectorsEqual };
+/**
+ * Returns true when the schema declares partial sync rules at the root level.
+ */
+declare function hasSchemaSyncRules(schema: SchemaDefinition): boolean;
+/**
+ * Resolve field → scope-value-key bindings for a collection.
+ *
+ * Sync rules take precedence over legacy `collection.scope` arrays.
+ * Returns `null` when the collection has no sync filtering configured.
+ */
+declare function getCollectionScopeBindings(schema: SchemaDefinition, collectionName: string): Record<string, string> | null;
+/**
+ * Returns whether a collection participates in sync filtering for this schema.
+ */
+declare function isCollectionSyncScoped(schema: SchemaDefinition, collectionName: string): boolean;
+/**
+ * Collect unique scope value keys referenced by sync rules and legacy scope fields.
+ */
+declare function collectSchemaScopeValueKeys(schema: SchemaDefinition): string[];
+
+/**
+ * Per-collection scope map: `{ collectionName: { field: value, ... } }`
+ *
+ * Used to filter which operations a client should receive during sync.
+ */
+type ScopeMap = Record<string, Record<string, unknown>>;
+/**
+ * Build a per-collection scope map from the schema's scope declarations
+ * and the client's flat scope values.
+ *
+ * Supports both legacy `collection.scope` arrays and declarative `schema.sync`
+ * rules (`sync: { todos: { where: { userId: true } } }`).
+ *
+ * When `schema.sync` is present, only collections with sync rules or legacy
+ * scope fields are included in the result. Other collections are omitted so
+ * sync engines treat them as out of scope (partial sync).
+ *
+ * @param schema - The schema definition with scope declarations
+ * @param scopeValues - Flat key-value scope values from the client
+ * @returns A per-collection scope map
+ *
+ * @example
+ * ```typescript
+ * // Schema declares: sales.scope = ['orgId', 'storeId']
+ * // Client provides: { orgId: 'org-123', storeId: 'store-456' }
+ * // Result: { sales: { orgId: 'org-123', storeId: 'store-456' }, products: {} }
+ * ```
+ */
+declare function buildScopeMap(schema: SchemaDefinition, scopeValues: Record<string, unknown>): ScopeMap;
+
+/**
+ * Collect every unique scope field name declared across all collections.
+ *
+ * @deprecated Use {@link collectSchemaScopeValueKeys} instead.
+ */
+declare function collectSchemaScopeFields(schema: SchemaDefinition): string[];
+/**
+ * Extract flat scope values from JWT (or auth) claims using schema scope field names.
+ *
+ * Resolution order for each scope field:
+ * 1. Top-level claim with the same name
+ * 2. Nested `claims.scope[field]` object
+ * 3. `userId` falls back to the standard JWT `sub` claim
+ *
+ * @param schema - Schema with per-collection scope declarations
+ * @param claims - Decoded JWT claims (unverified; client-side scope hints only)
+ * @returns Flat key-value map suitable for {@link buildScopeMap}
+ */
+declare function extractScopeValuesFromClaims(schema: SchemaDefinition, claims: Record<string, unknown>): Record<string, unknown>;
+
+/**
+ * Offline-safe sequence formatting.
+ *
+ * Format tokens:
+ * - `{date}` → YYYYMMDD (current date)
+ * - `{node4}` → first 4 characters of nodeId
+ * - `{node8}` → first 8 characters of nodeId
+ * - `{seq}` → zero-padded counter (default 4 digits)
+ * - `{seq:N}` → zero-padded counter with N digits
+ *
+ * @example
+ * ```typescript
+ * formatSequenceValue('INV-{date}-{node4}-{seq}', 42, 'a1b2c3d4e5f6')
+ * // → "INV-20260508-a1b2-0042"
+ *
+ * formatSequenceValue('ORDER-{seq:6}', 7, 'node-id')
+ * // → "ORDER-000007"
+ * ```
+ */
+declare function formatSequenceValue(template: string, counter: number, nodeId: string, now?: Date): string;
+/**
+ * Default format when none is provided: `{name}-{seq:4}`.
+ */
+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;
+
+/**
+ * Convert migration steps to SQL statements.
+ *
+ * Structural steps (addField, removeField, renameField, addIndex, removeIndex)
+ * produce SQL. Backfill steps are skipped (handled at the application layer
+ * by reading rows and applying the transform function).
+ *
+ * @param steps - The migration steps from a MigrationBuilder
+ * @returns Array of SQL statements for structural changes
+ */
+declare function migrationStepsToSQL(steps: readonly MigrationStep[]): string[];
+/**
+ * Generate SQL statements to roll back a migration.
+ *
+ * Uses the migration's explicit rollback steps if available,
+ * otherwise auto-generates inverse steps from the forward steps.
+ *
+ * Backfill steps in the rollback are skipped (handled at the application layer).
+ *
+ * @param migration - The migration definition to generate rollback SQL for
+ * @returns Array of SQL statements that undo the migration's structural changes
+ *
+ * @example
+ * ```typescript
+ * const migration = migrate()
+ *   .addField('todos', 'priority', t.enum(['low', 'medium', 'high']).default('medium'))
+ *   .addIndex('todos', 'priority')
+ *
+ * const rollbackSQL = rollbackStepsToSQL(migration)
+ * // ['DROP INDEX IF EXISTS idx_todos_priority',
+ * //  'ALTER TABLE todos DROP COLUMN priority']
+ * ```
+ */
+declare function rollbackStepsToSQL(migration: MigrationDefinition): string[];
+
+/**
+ * A migration that includes both forward (up) and backward (down) steps.
+ * Rollback steps are applied in reverse order of the forward steps.
+ */
+interface ReversibleMigration {
+    readonly up: readonly MigrationStep[];
+    readonly down: readonly MigrationStep[];
+    readonly fromVersion: number;
+    readonly toVersion: number;
+}
+/**
+ * Error thrown when a migration step cannot be automatically rolled back
+ * and no explicit down step has been provided.
+ */
+declare class MigrationRollbackError extends KoraError {
+    constructor(step: MigrationStep);
+}
+/**
+ * Determines whether a migration step can be automatically rolled back
+ * without explicit developer-provided down steps.
+ *
+ * Auto-rollback is possible when the inverse operation is deterministic:
+ * - addField -> removeField (drop the added column)
+ * - addIndex -> removeIndex (drop the added index)
+ * - removeIndex -> addIndex (re-create the index)
+ * - renameField -> renameField (swap from/to names)
+ *
+ * Steps that CANNOT auto-rollback:
+ * - removeField: the field descriptor is lost (need it to re-create the column)
+ * - backfill: data transforms are not reversible
+ *
+ * @param step - The forward migration step to check
+ * @returns true if the step can be auto-rolled back
+ */
+declare function canAutoRollback(step: MigrationStep): boolean;
+/**
+ * Generates rollback steps for a list of forward migration steps.
+ * Steps are reversed in order (last forward step becomes first rollback step).
+ *
+ * For steps that cannot be auto-rolled back, throws a MigrationRollbackError.
+ * Use canAutoRollback() to check before calling, or provide explicit down steps
+ * via the MigrationBuilder .down() API.
+ *
+ * @param forwardSteps - The forward migration steps to generate rollbacks for
+ * @returns Array of rollback steps in reverse execution order
+ * @throws MigrationRollbackError if any step cannot be auto-rolled back
+ */
+declare function generateRollbackSteps(forwardSteps: readonly MigrationStep[]): MigrationStep[];
+/**
+ * Create a ReversibleMigration from forward steps, explicit down steps, and version info.
+ *
+ * If explicit down steps are provided, they are used as-is.
+ * If no explicit down steps are provided, auto-generation is attempted.
+ *
+ * @param upSteps - The forward migration steps
+ * @param downSteps - Optional explicit rollback steps (overrides auto-generation)
+ * @param fromVersion - The schema version before the migration
+ * @param toVersion - The schema version after the migration
+ * @returns A complete ReversibleMigration
+ * @throws MigrationRollbackError if auto-generation fails and no explicit down steps provided
+ */
+declare function createReversibleMigration(upSteps: readonly MigrationStep[], downSteps: readonly MigrationStep[] | null, fromVersion: number, toVersion: number): ReversibleMigration;
+
+/**
+ * Validates whether a transition from one state to another is allowed
+ * by the given state machine constraint.
+ *
+ * @param constraint - The state machine constraint defining allowed transitions
+ * @param fromValue - The current state value (before the transition)
+ * @param toValue - The target state value (after the transition)
+ * @returns A TransitionValidationResult describing whether the transition is valid
+ *
+ * @example
+ * ```typescript
+ * const constraint: StateMachineConstraint = {
+ *   field: 'status',
+ *   collection: 'orders',
+ *   transitions: {
+ *     draft: ['submitted', 'cancelled'],
+ *     submitted: ['approved'],
+ *     approved: [],
+ *   },
+ * }
+ *
+ * const result = validateTransition(constraint, 'draft', 'submitted')
+ * // { valid: true, from: 'draft', to: 'submitted', field: 'status',
+ * //   collection: 'orders', allowedTargets: ['submitted', 'cancelled'] }
+ * ```
+ */
+declare function validateTransition(constraint: StateMachineConstraint, fromValue: unknown, toValue: unknown): TransitionValidationResult;
+/**
+ * Extracts all state machine constraints from a schema definition.
+ * Scans every collection for enum fields that have transition rules declared
+ * via the `.transitions()` builder method.
+ *
+ * @param schema - The schema definition to extract constraints from
+ * @returns An array of StateMachineConstraint objects, one per enum field with transitions
+ *
+ * @example
+ * ```typescript
+ * const schema = defineSchema({
+ *   version: 1,
+ *   collections: {
+ *     orders: {
+ *       fields: {
+ *         status: t.enum(['draft', 'submitted']).transitions({
+ *           draft: ['submitted'],
+ *           submitted: [],
+ *         }),
+ *       },
+ *     },
+ *   },
+ * })
+ *
+ * const constraints = buildStateMachineConstraints(schema)
+ * // [{ field: 'status', collection: 'orders', transitions: { draft: ['submitted'], submitted: [] } }]
+ * ```
+ */
+declare function buildStateMachineConstraints(schema: SchemaDefinition): StateMachineConstraint[];
+/**
+ * Finds the state machine constraint for a specific field in a specific collection,
+ * if one exists.
+ *
+ * @param schema - The schema definition to search
+ * @param collection - The collection name
+ * @param field - The field name
+ * @returns The TransitionMap if the field has transitions declared, or null otherwise
+ */
+declare function getTransitionMap(schema: SchemaDefinition, collection: string, field: string): TransitionMap | null;
+
+/**
+ * Output of the proto definition generator.
+ * Contains the .proto file text, a type mapping, and a JSON descriptor
+ * compatible with protobufjs's `Root.fromJSON()`.
+ */
+interface ProtoOutput {
+    /** The generated .proto file content as a string */
+    proto: string;
+    /** TypeScript type map: field name -> protobuf type */
+    typeMap: Map<string, string>;
+    /** JSON descriptor for dynamic protobufjs usage (no .proto file needed) */
+    jsonDescriptor: Record<string, unknown>;
+}
+/**
+ * Generates Protocol Buffer definitions from a Kora schema.
+ *
+ * Produces three outputs:
+ * 1. A `.proto` file string conforming to proto3 syntax
+ * 2. A type map linking Kora field paths to protobuf types
+ * 3. A JSON descriptor for runtime protobufjs usage via `Root.fromJSON()`
+ *
+ * The generated definitions include:
+ * - Per-collection record messages with proper type mappings
+ * - Nested enum types for enum fields
+ * - `KoraOperation` wrapper for the sync wire format
+ * - `OperationBatch` for batched sync transfers
+ * - `HandshakeMessage` / `HandshakeResponse` for sync session initiation
+ * - `Acknowledgment` for delivery confirmation
+ *
+ * @param schema - A validated SchemaDefinition from defineSchema()
+ * @returns ProtoOutput with proto text, type map, and JSON descriptor
+ *
+ * @example
+ * ```typescript
+ * import { defineSchema, t, generateProtoDefinitions } from '@korajs/core'
+ *
+ * const schema = defineSchema({
+ *   version: 1,
+ *   collections: {
+ *     todos: {
+ *       fields: {
+ *         title: t.string(),
+ *         completed: t.boolean().default(false),
+ *       }
+ *     }
+ *   }
+ * })
+ *
+ * const { proto, typeMap, jsonDescriptor } = generateProtoDefinitions(schema)
+ * // proto is a valid .proto file string
+ * // typeMap maps "todos.title" -> "string", "todos.completed" -> "bool"
+ * // jsonDescriptor can be loaded with protobuf.Root.fromJSON()
+ * ```
+ */
+declare function generateProtoDefinitions(schema: SchemaDefinition): ProtoOutput;
+
+export { APPLY_FAILURE_CODES, APPLY_RESULTS, type ApplyFailureReason, type ApplyResult, ArrayFieldBuilder, AtomicOp, type AtomicOpSentinel, AtomicOpType, CausalTracker, ClockDriftError, CollectionDefinition, type CollectionInput, type ConstraintInput, CustomResolver, EnumFieldBuilder, FieldBuilder, FieldKind, type FieldKindToType, type InferFieldType, type InferInsertInput, type InferRecord, type InferUpdateInput, KORA_ERROR_FIX_SUGGESTIONS, KoraError, MergeConflictError, MigrationDefinition, MigrationRollbackError, MigrationStep, Operation, OperationError, type OperationLog, type OperationTransform, OperationType, type ProtoOutput, RandomSource, RelationDefinition, type RelationInput, type ReversibleMigration, SchemaDefinition, type SchemaInput, SchemaValidationError, type ScopeMap, StateMachineConstraint, type StateMachineInput, StorageError, SyncError, TransitionMap, TransitionValidationResult, type TypedSchemaDefinition, VersionVector, advanceVector, applyOperationTransforms, buildScopeMap, buildStateMachineConstraints, canAutoRollback, collectSchemaScopeFields, collectSchemaScopeValueKeys, computeDelta, createReversibleMigration, createVersionVector, defaultApplyFailureReason, defaultSequenceFormat, defineSchema, deserializeVector, dominates, extractScopeValuesFromClaims, extractTimestamp, formatSequenceValue, generateFullDDL, generateProtoDefinitions, generateRollbackSteps, generateSQL, generateUUIDv7, getCollectionScopeBindings, getKoraErrorFix, getTransitionMap, hasSchemaSyncRules, isApplyFailure, isAtomicOp, isCollectionSyncScoped, isValidUUIDv7, mergeVectors, migrationStepsToSQL, op, resolveAtomicOp, rollbackStepsToSQL, serializeVector, toAtomicOp, validateRecord, validateTransition, vectorsEqual };