@korajs/core 0.3.1 → 0.4.0

package/dist/events-BMulupSB.d.ts

@@ -0,0 +1,844 @@
+/**
+ * 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)
+ *
+ * @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 = true, Auto extends boolean = false> {
+    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?: Req, defaultValue?: unknown, auto?: Auto, mergeStrategy?: FieldMergeStrategy | null);
+    /** 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>;
+    /**
+     * 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>;
+    /** @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 = true, Auto extends boolean = false> extends FieldBuilder<'enum', Req, Auto> {
+    private readonly _enumValues;
+    private readonly _transitions;
+    constructor(values: Values, required?: Req, defaultValue?: unknown, auto?: Auto, 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: Record<Values[number], Values[number][]>): EnumFieldBuilder<Values, Req, Auto>;
+    _build(): FieldDescriptor;
+}
+/**
+ * Field builder for array fields with a typed item kind.
+ * Preserves the item kind type parameter for inference.
+ */
+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, mergeStrategy?: FieldMergeStrategy | null);
+    optional(): ArrayFieldBuilder<ItemKind, false, Auto>;
+    default(value: unknown[]): ArrayFieldBuilder<ItemKind, false, Auto>;
+    auto(): ArrayFieldBuilder<ItemKind, false, true>;
+    merge(strategy: FieldMergeStrategy): ArrayFieldBuilder<ItemKind, Req, Auto>;
+    _build(): FieldDescriptor;
+}
+/**
+ * Type builder namespace. The developer's primary interface for defining field types.
+ *
+ * @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(),
+ * }
+ * ```
+ */
+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>;
+};
+
+/**
+ * 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>;
+};
+/**
+ * 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 record and returns the fields to update.
+     * Runs after structural changes (addField, renameField, etc.).
+     *
+     * @param collection - The collection name
+     * @param transform - Forward transform function
+     * @param reverseTransform - Optional reverse transform for rollback support
+     */
+    backfill(collection: string, transform: (record: Record<string, unknown>) => Record<string, unknown>, reverseTransform?: (record: Record<string, unknown>) => Record<string, unknown>): 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 {
+    /** SHA-256 hash of (type + collection + recordId + data + timestamp + nodeId). Content-addressed. */
+    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;
+}
+/**
+ * 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';
+/**
+ * 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' | 'syncing' | 'synced' | 'offline' | 'error';
+    /** 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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>;
+}
+/**
+ * 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;
+}
+
+/**
+ * Hybrid Logical Clock implementation based on Kulkarni et al.
+ *
+ * Provides a total order that respects causality without requiring synchronized clocks.
+ * Each call to now() returns a timestamp strictly greater than the previous one.
+ *
+ * @example
+ * ```typescript
+ * const clock = new HybridLogicalClock('node-1')
+ * const ts1 = clock.now()
+ * const ts2 = clock.now()
+ * // HybridLogicalClock.compare(ts1, ts2) < 0 (ts1 is earlier)
+ * ```
+ */
+declare class HybridLogicalClock {
+    private readonly nodeId;
+    private readonly timeSource;
+    private readonly onDriftWarning?;
+    private wallTime;
+    private logical;
+    constructor(nodeId: string, timeSource?: TimeSource, onDriftWarning?: ((driftMs: number) => void) | undefined);
+    /**
+     * Generate a new timestamp for a local event.
+     * Guarantees monotonicity: each call returns a timestamp strictly greater than the previous.
+     *
+     * @throws {ClockDriftError} If physical time is more than 5 minutes behind the HLC wallTime
+     */
+    now(): HLCTimestamp;
+    /**
+     * Update clock on receiving a remote timestamp.
+     * Merges the remote clock state with the local state to maintain causal ordering.
+     *
+     * @throws {ClockDriftError} If physical time is more than 5 minutes behind the resulting wallTime
+     */
+    receive(remote: HLCTimestamp): HLCTimestamp;
+    /**
+     * Compare two timestamps. Returns negative if a < b, positive if a > b, zero if equal.
+     * Total order: wallTime first, then logical, then nodeId (lexicographic).
+     */
+    static compare(a: HLCTimestamp, b: HLCTimestamp): number;
+    /**
+     * Serialize an HLC timestamp to a string that sorts lexicographically.
+     * Format: zero-padded wallTime:logical:nodeId
+     */
+    static serialize(ts: HLCTimestamp): string;
+    /**
+     * Deserialize an HLC timestamp from its serialized string form.
+     */
+    static deserialize(s: string): HLCTimestamp;
+    private checkDrift;
+}
+
+/**
+ * Creates an immutable, content-addressed Operation from the given parameters.
+ * The operation is deep-frozen after creation — it cannot be modified.
+ *
+ * @param input - The operation parameters (without id, which is computed)
+ * @param clock - The HLC clock to generate the timestamp
+ * @returns A frozen Operation with a content-addressed id
+ *
+ * @example
+ * ```typescript
+ * const op = await createOperation({
+ *   nodeId: 'device-1',
+ *   type: 'insert',
+ *   collection: 'todos',
+ *   recordId: 'rec-1',
+ *   data: { title: 'Ship it' },
+ *   previousData: null,
+ *   sequenceNumber: 1,
+ *   causalDeps: [],
+ *   schemaVersion: 1,
+ * }, clock)
+ * ```
+ */
+declare function createOperation(input: OperationInput, clock: HybridLogicalClock): Promise<Operation>;
+/**
+ * Validates operation input parameters. Throws OperationError with
+ * contextual information on validation failure.
+ */
+declare function validateOperationParams(input: OperationInput): void;
+/**
+ * Verify the integrity of an operation by recomputing its content hash.
+ * Returns true if the id matches the recomputed hash.
+ */
+declare function verifyOperationIntegrity(op: Operation): Promise<boolean>;
+/**
+ * Type guard for Operation interface.
+ */
+declare function isValidOperation(value: unknown): value is Operation;
+
+/**
+ * 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:auth-failed';
+    reason: string;
+} | {
+    type: 'sync:sent';
+    operations: Operation[];
+    batchSize: number;
+} | {
+    type: 'sync:received';
+    operations: Operation[];
+    batchSize: number;
+} | {
+    type: 'sync:acknowledged';
+    sequenceNumber: number;
+} | {
+    type: 'query:subscribed';
+    queryId: string;
+    collection: string;
+} | {
+    type: 'query:invalidated';
+    queryId: string;
+    trigger: Operation;
+} | {
+    type: 'query:executed';
+    queryId: string;
+    duration: number;
+    resultCount: number;
+} | {
+    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[];
+};
+/** 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 AtomicOpType as A, RollbackBuilder as B, type CustomResolver as C, type SequenceConfig as D, EnumFieldBuilder as E, FieldBuilder as F, type StateMachineDefinition as G, type HLCTimestamp as H, type SyncDiagnosticsSnapshot as I, type TimeSource as J, type KoraEvent as K, createOperation as L, type MigrationDefinition as M, isValidOperation as N, type OperationType as O, migrate as P, t as Q, type RandomSource as R, type SchemaDefinition as S, type TransitionMap as T, verifyOperationIntegrity as U, type VersionVector as V, validateOperationParams as W, type AtomicOp as a, type CollectionDefinition as b, type RelationDefinition as c, ArrayFieldBuilder as d, type Operation as e, type MigrationStep as f, type StateMachineConstraint as g, type TransitionValidationResult as h, CONNECTION_QUALITIES as i, type ConnectionQuality as j, type Constraint as k, type FieldDescriptor as l, type FieldKind as m, type FieldMergeStrategy as n, HybridLogicalClock as o, type KoraEventByType as p, type KoraEventEmitter as q, type KoraEventListener as r, type KoraEventType as s, MERGE_STRATEGIES as t, type MergeStrategy as u, type MergeTrace as v, MigrationBuilder as w, type OnDeleteAction as x, type OperationInput as y, type RelationType as z };