@korajs/core 0.5.0 → 1.0.0-beta.0

package/dist/index.d.cts

@@ -1,5 +1,7 @@
-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.cjs';
-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.cjs';
+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-BynBOsO3.cjs';
+export { j as CONNECTION_QUALITIES, k as ConnectionQuality, l as Constraint, m as FieldDescriptor, n as FieldMergeStrategy, H as HLCTimestamp, K as KoraEvent, o as KoraEventByType, p as KoraEventEmitter, q as KoraEventListener, r as KoraEventType, s as MERGE_STRATEGIES, t as MergeStrategy, u as MergeTrace, v as MigrationBuilder, w as OnDeleteAction, x as OperationInput, y as RelationType, z as RollbackBuilder, B as SequenceConfig, D as StateMachineDefinition, G as SyncDiagnosticsSnapshot, I as SyncRuleDefinition, J as TimeSource, L as migrate, N as t } from './events-BynBOsO3.cjs';
+export { H as HybridLogicalClock, M as MAX_LOGICAL, c as createOperation, i as isValidOperation, v as verifyOperationIntegrity } from './operation-BpZlYSpe.cjs';
+export { S as ScopeMap, b as buildScopeMap } from './build-scope-map-BIeawJzC.cjs';
 
 /**
  * Base error class for all Kora errors.
@@ -59,10 +61,33 @@ declare class SyncError extends KoraError {
 declare class StorageError extends KoraError {
     constructor(message: string, context?: Record<string, unknown>);
 }
+/**
+ * Thrown when collection/query APIs are used before {@link KoraApp.ready} resolves.
+ */
+declare class AppNotReadyError extends KoraError {
+    constructor(detail: string);
+}
 /**
  * Thrown when the HLC detects excessive clock drift.
  * Drift > 60s: warning. Drift > 5min: this error is thrown, refusing to generate timestamps.
  */
+declare class RemoteClockDriftError extends KoraError {
+    readonly remoteWallTime: number;
+    readonly localReferenceTime: number;
+    constructor(remoteWallTime: number, localReferenceTime: number);
+}
+/**
+ * Thrown when an HLC timestamp has structurally invalid fields: non-integer or
+ * negative wallTime/logical, or a logical counter beyond the serializable cap.
+ * Rejected BEFORE any clock state changes, so a malformed remote timestamp can
+ * never corrupt a replica's clock or break the lexicographic ordering of the
+ * serialized form.
+ */
+declare class InvalidTimestampError extends KoraError {
+    readonly wallTime: number;
+    readonly logical: number;
+    constructor(message: string, wallTime: number, logical: number);
+}
 declare class ClockDriftError extends KoraError {
     readonly currentHlcTime: number;
     readonly physicalTime: number;
@@ -281,6 +306,57 @@ declare const op: {
  */
 declare function toAtomicOp(sentinel: AtomicOpSentinel): AtomicOp;
 
+/**
+ * Canonical JSON-safe encoding of binary bytes stored inside `op.data` /
+ * `op.previousData` (currently richtext field values). A raw Uint8Array
+ * JSON-serializes to a numeric-key object and an ArrayBuffer to `{}` (silent
+ * data loss), which breaks content-hash stability, persistence round-trips,
+ * remote application, and merge. Tagging the bytes as base64 at
+ * operation-creation time makes the hashed value, the persisted JSON, the wire
+ * payload, and the value the merge engine sees the identical canonical value.
+ *
+ * This convention lives in `@korajs/core` because `op.data` is a core concept:
+ * both `@korajs/store` (persistence, creation) and `@korajs/merge` (CRDT merge)
+ * must agree on it, and neither may depend on the other.
+ */
+interface KoraBytesValue {
+    $koraBytes: string;
+}
+/**
+ * Type guard for the tagged binary form. Requires exactly the single
+ * `$koraBytes` key so arbitrary user objects that happen to contain the key
+ * are never silently reinterpreted as bytes.
+ */
+declare function isKoraBytesValue(value: unknown): value is KoraBytesValue;
+/**
+ * Detects the numeric-key object shape a raw Uint8Array produced when
+ * JSON-serialized before the tagged encoding existed ({"0":1,"1":2,...}).
+ */
+declare function isLegacyNumericByteObject(value: unknown): value is Record<string, number>;
+/**
+ * Dependency-free base64 encoder. btoa is unavailable for bytes in Node and
+ * Buffer is unavailable in browsers, so a manual implementation is the only
+ * deterministic option that works in every runtime Kora targets.
+ */
+declare function bytesToBase64(bytes: Uint8Array): string;
+/**
+ * Inverse of {@link bytesToBase64}.
+ */
+declare function base64ToBytes(base64: string): Uint8Array;
+/**
+ * Normalize a validated binary-or-string value into the canonical form stored
+ * in `op.data`: strings pass through unchanged (backward compatible with every
+ * existing operation), binary values become the tagged base64 form.
+ */
+declare function encodeBytesForOpData(value: string | Uint8Array | ArrayBuffer): string | KoraBytesValue;
+/**
+ * Reverse of {@link encodeBytesForOpData}, tolerant of every shape a binary
+ * op-data value has ever taken: canonical strings and tagged bytes, in-memory
+ * Uint8Array/ArrayBuffer (ops that never round-tripped through JSON), and
+ * pre-fix numeric-key objects.
+ */
+declare function decodeBytesFromOpData(value: unknown): string | Uint8Array;
+
 /**
  * Input shape for defineSchema() — what the developer writes.
  */
@@ -546,36 +622,6 @@ declare function isCollectionSyncScoped(schema: SchemaDefinition, collectionName
  */
 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.
  *
@@ -864,4 +910,4 @@ interface ProtoOutput {
  */
 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 };
+export { APPLY_FAILURE_CODES, APPLY_RESULTS, AppNotReadyError, 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, InvalidTimestampError, KORA_ERROR_FIX_SUGGESTIONS, type KoraBytesValue, KoraError, MergeConflictError, MigrationDefinition, MigrationRollbackError, MigrationStep, Operation, OperationError, type OperationLog, type OperationTransform, OperationType, type ProtoOutput, RandomSource, RelationDefinition, type RelationInput, RemoteClockDriftError, type ReversibleMigration, SchemaDefinition, type SchemaInput, SchemaValidationError, StateMachineConstraint, type StateMachineInput, StorageError, SyncError, TransitionMap, TransitionValidationResult, type TypedSchemaDefinition, VersionVector, advanceVector, applyOperationTransforms, base64ToBytes, buildStateMachineConstraints, bytesToBase64, canAutoRollback, collectSchemaScopeFields, collectSchemaScopeValueKeys, computeDelta, createReversibleMigration, createVersionVector, decodeBytesFromOpData, defaultApplyFailureReason, defaultSequenceFormat, defineSchema, deserializeVector, dominates, encodeBytesForOpData, extractScopeValuesFromClaims, extractTimestamp, formatSequenceValue, generateFullDDL, generateProtoDefinitions, generateRollbackSteps, generateSQL, generateUUIDv7, getCollectionScopeBindings, getKoraErrorFix, getTransitionMap, hasSchemaSyncRules, isApplyFailure, isAtomicOp, isCollectionSyncScoped, isKoraBytesValue, isLegacyNumericByteObject, isValidUUIDv7, mergeVectors, migrationStepsToSQL, op, resolveAtomicOp, rollbackStepsToSQL, serializeVector, toAtomicOp, validateRecord, validateTransition, vectorsEqual };

package/dist/index.d.ts

@@ -1,5 +1,7 @@
-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';
+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-BynBOsO3.js';
+export { j as CONNECTION_QUALITIES, k as ConnectionQuality, l as Constraint, m as FieldDescriptor, n as FieldMergeStrategy, H as HLCTimestamp, K as KoraEvent, o as KoraEventByType, p as KoraEventEmitter, q as KoraEventListener, r as KoraEventType, s as MERGE_STRATEGIES, t as MergeStrategy, u as MergeTrace, v as MigrationBuilder, w as OnDeleteAction, x as OperationInput, y as RelationType, z as RollbackBuilder, B as SequenceConfig, D as StateMachineDefinition, G as SyncDiagnosticsSnapshot, I as SyncRuleDefinition, J as TimeSource, L as migrate, N as t } from './events-BynBOsO3.js';
+export { H as HybridLogicalClock, M as MAX_LOGICAL, c as createOperation, i as isValidOperation, v as verifyOperationIntegrity } from './operation-D5WOZYvy.js';
+export { S as ScopeMap, b as buildScopeMap } from './build-scope-map-DOf4JLTh.js';
 
 /**
  * Base error class for all Kora errors.
@@ -59,10 +61,33 @@ declare class SyncError extends KoraError {
 declare class StorageError extends KoraError {
     constructor(message: string, context?: Record<string, unknown>);
 }
+/**
+ * Thrown when collection/query APIs are used before {@link KoraApp.ready} resolves.
+ */
+declare class AppNotReadyError extends KoraError {
+    constructor(detail: string);
+}
 /**
  * Thrown when the HLC detects excessive clock drift.
  * Drift > 60s: warning. Drift > 5min: this error is thrown, refusing to generate timestamps.
  */
+declare class RemoteClockDriftError extends KoraError {
+    readonly remoteWallTime: number;
+    readonly localReferenceTime: number;
+    constructor(remoteWallTime: number, localReferenceTime: number);
+}
+/**
+ * Thrown when an HLC timestamp has structurally invalid fields: non-integer or
+ * negative wallTime/logical, or a logical counter beyond the serializable cap.
+ * Rejected BEFORE any clock state changes, so a malformed remote timestamp can
+ * never corrupt a replica's clock or break the lexicographic ordering of the
+ * serialized form.
+ */
+declare class InvalidTimestampError extends KoraError {
+    readonly wallTime: number;
+    readonly logical: number;
+    constructor(message: string, wallTime: number, logical: number);
+}
 declare class ClockDriftError extends KoraError {
     readonly currentHlcTime: number;
     readonly physicalTime: number;
@@ -281,6 +306,57 @@ declare const op: {
  */
 declare function toAtomicOp(sentinel: AtomicOpSentinel): AtomicOp;
 
+/**
+ * Canonical JSON-safe encoding of binary bytes stored inside `op.data` /
+ * `op.previousData` (currently richtext field values). A raw Uint8Array
+ * JSON-serializes to a numeric-key object and an ArrayBuffer to `{}` (silent
+ * data loss), which breaks content-hash stability, persistence round-trips,
+ * remote application, and merge. Tagging the bytes as base64 at
+ * operation-creation time makes the hashed value, the persisted JSON, the wire
+ * payload, and the value the merge engine sees the identical canonical value.
+ *
+ * This convention lives in `@korajs/core` because `op.data` is a core concept:
+ * both `@korajs/store` (persistence, creation) and `@korajs/merge` (CRDT merge)
+ * must agree on it, and neither may depend on the other.
+ */
+interface KoraBytesValue {
+    $koraBytes: string;
+}
+/**
+ * Type guard for the tagged binary form. Requires exactly the single
+ * `$koraBytes` key so arbitrary user objects that happen to contain the key
+ * are never silently reinterpreted as bytes.
+ */
+declare function isKoraBytesValue(value: unknown): value is KoraBytesValue;
+/**
+ * Detects the numeric-key object shape a raw Uint8Array produced when
+ * JSON-serialized before the tagged encoding existed ({"0":1,"1":2,...}).
+ */
+declare function isLegacyNumericByteObject(value: unknown): value is Record<string, number>;
+/**
+ * Dependency-free base64 encoder. btoa is unavailable for bytes in Node and
+ * Buffer is unavailable in browsers, so a manual implementation is the only
+ * deterministic option that works in every runtime Kora targets.
+ */
+declare function bytesToBase64(bytes: Uint8Array): string;
+/**
+ * Inverse of {@link bytesToBase64}.
+ */
+declare function base64ToBytes(base64: string): Uint8Array;
+/**
+ * Normalize a validated binary-or-string value into the canonical form stored
+ * in `op.data`: strings pass through unchanged (backward compatible with every
+ * existing operation), binary values become the tagged base64 form.
+ */
+declare function encodeBytesForOpData(value: string | Uint8Array | ArrayBuffer): string | KoraBytesValue;
+/**
+ * Reverse of {@link encodeBytesForOpData}, tolerant of every shape a binary
+ * op-data value has ever taken: canonical strings and tagged bytes, in-memory
+ * Uint8Array/ArrayBuffer (ops that never round-tripped through JSON), and
+ * pre-fix numeric-key objects.
+ */
+declare function decodeBytesFromOpData(value: unknown): string | Uint8Array;
+
 /**
  * Input shape for defineSchema() — what the developer writes.
  */
@@ -546,36 +622,6 @@ declare function isCollectionSyncScoped(schema: SchemaDefinition, collectionName
  */
 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.
  *
@@ -864,4 +910,4 @@ interface ProtoOutput {
  */
 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 };
+export { APPLY_FAILURE_CODES, APPLY_RESULTS, AppNotReadyError, 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, InvalidTimestampError, KORA_ERROR_FIX_SUGGESTIONS, type KoraBytesValue, KoraError, MergeConflictError, MigrationDefinition, MigrationRollbackError, MigrationStep, Operation, OperationError, type OperationLog, type OperationTransform, OperationType, type ProtoOutput, RandomSource, RelationDefinition, type RelationInput, RemoteClockDriftError, type ReversibleMigration, SchemaDefinition, type SchemaInput, SchemaValidationError, StateMachineConstraint, type StateMachineInput, StorageError, SyncError, TransitionMap, TransitionValidationResult, type TypedSchemaDefinition, VersionVector, advanceVector, applyOperationTransforms, base64ToBytes, buildStateMachineConstraints, bytesToBase64, canAutoRollback, collectSchemaScopeFields, collectSchemaScopeValueKeys, computeDelta, createReversibleMigration, createVersionVector, decodeBytesFromOpData, defaultApplyFailureReason, defaultSequenceFormat, defineSchema, deserializeVector, dominates, encodeBytesForOpData, extractScopeValuesFromClaims, extractTimestamp, formatSequenceValue, generateFullDDL, generateProtoDefinitions, generateRollbackSteps, generateSQL, generateUUIDv7, getCollectionScopeBindings, getKoraErrorFix, getTransitionMap, hasSchemaSyncRules, isApplyFailure, isAtomicOp, isCollectionSyncScoped, isKoraBytesValue, isLegacyNumericByteObject, isValidUUIDv7, mergeVectors, migrationStepsToSQL, op, resolveAtomicOp, rollbackStepsToSQL, serializeVector, toAtomicOp, validateRecord, validateTransition, vectorsEqual };

package/dist/index.js

@@ -1,10 +1,14 @@
 import {
+  AppNotReadyError,
   ClockDriftError,
   HybridLogicalClock,
+  InvalidTimestampError,
   KORA_ERROR_FIX_SUGGESTIONS,
   KoraError,
+  MAX_LOGICAL,
   MergeConflictError,
   OperationError,
+  RemoteClockDriftError,
   SchemaValidationError,
   StorageError,
   SyncError,
@@ -13,7 +17,7 @@ import {
   isValidOperation,
   topologicalSort,
   verifyOperationIntegrity
-} from "./chunk-H4FXU5OP.js";
+} from "./chunk-5IICSH6H.js";
 
 // src/types.ts
 var MERGE_STRATEGIES = [
@@ -234,6 +238,106 @@ function toAtomicOp(sentinel) {
   return { type: sentinel.type, value: sentinel.value };
 }
 
+// src/operations/op-data-binary.ts
+function isKoraBytesValue(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const record = value;
+  return Object.keys(record).length === 1 && typeof record.$koraBytes === "string";
+}
+function isLegacyNumericByteObject(value) {
+  if (typeof value !== "object" || value === null || ArrayBuffer.isView(value)) {
+    return false;
+  }
+  const record = value;
+  const keys = Object.keys(record);
+  if (keys.length === 0) {
+    return false;
+  }
+  for (let i = 0; i < keys.length; i++) {
+    const byte = record[String(i)];
+    if (typeof byte !== "number" || !Number.isInteger(byte) || byte < 0 || byte > 255) {
+      return false;
+    }
+  }
+  return true;
+}
+var BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+var BASE64_REVERSE = new Map(
+  Array.from(BASE64_ALPHABET, (char, index) => [char, index])
+);
+function bytesToBase64(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const b0 = bytes[i] ?? 0;
+    const b1 = bytes[i + 1] ?? 0;
+    const b2 = bytes[i + 2] ?? 0;
+    const triple = b0 << 16 | b1 << 8 | b2;
+    out += BASE64_ALPHABET[triple >> 18 & 63] ?? "";
+    out += BASE64_ALPHABET[triple >> 12 & 63] ?? "";
+    out += i + 1 < bytes.length ? BASE64_ALPHABET[triple >> 6 & 63] ?? "" : "=";
+    out += i + 2 < bytes.length ? BASE64_ALPHABET[triple & 63] ?? "" : "=";
+  }
+  return out;
+}
+function base64ToBytes(base64) {
+  const cleaned = base64.replace(/=+$/, "");
+  const out = new Uint8Array(Math.floor(cleaned.length * 6 / 8));
+  let buffer = 0;
+  let bits = 0;
+  let index = 0;
+  for (const char of cleaned) {
+    const value = BASE64_REVERSE.get(char);
+    if (value === void 0) {
+      throw new OperationError(`Invalid base64 character "${char}" in tagged binary value.`, {
+        char
+      });
+    }
+    buffer = buffer << 6 | value;
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      out[index] = buffer >> bits & 255;
+      index += 1;
+    }
+  }
+  return out;
+}
+function encodeBytesForOpData(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  const bytes = value instanceof Uint8Array ? value : new Uint8Array(value);
+  return { $koraBytes: bytesToBase64(bytes) };
+}
+function decodeBytesFromOpData(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (value instanceof Uint8Array) {
+    return value;
+  }
+  if (value instanceof ArrayBuffer) {
+    return new Uint8Array(value);
+  }
+  if (isKoraBytesValue(value)) {
+    return base64ToBytes(value.$koraBytes);
+  }
+  if (isLegacyNumericByteObject(value)) {
+    const keys = Object.keys(value);
+    const bytes = new Uint8Array(keys.length);
+    for (let i = 0; i < keys.length; i++) {
+      bytes[i] = value[String(i)] ?? 0;
+    }
+    return bytes;
+  }
+  throw new OperationError(
+    "Binary op-data value must be a string, Uint8Array, ArrayBuffer, tagged { $koraBytes } object, or legacy numeric-key byte object.",
+    { receivedType: typeof value }
+  );
+}
+
 // src/scopes/sync-scope-bindings.ts
 function hasSchemaSyncRules(schema) {
   return schema.sync !== void 0 && Object.keys(schema.sync).length > 0;
@@ -663,6 +767,7 @@ function generateSQL(collectionName, collection, relations) {
   columns.push("_created_at INTEGER NOT NULL");
   columns.push("_updated_at INTEGER NOT NULL");
   columns.push("_version TEXT NOT NULL DEFAULT ''");
+  columns.push("_field_versions TEXT NOT NULL DEFAULT '{}'");
   columns.push("_deleted INTEGER NOT NULL DEFAULT 0");
   statements.push(`CREATE TABLE IF NOT EXISTS ${collectionName} (
   ${columns.join(",\n  ")}
@@ -675,6 +780,10 @@ ALTER TABLE ${collectionName} ADD COLUMN ${colDef}`);
   statements.push(
     `--kora:safe-alter
 ALTER TABLE ${collectionName} ADD COLUMN _version TEXT NOT NULL DEFAULT ''`
+  );
+  statements.push(
+    `--kora:safe-alter
+ALTER TABLE ${collectionName} ADD COLUMN _field_versions TEXT NOT NULL DEFAULT '{}'`
   );
   for (const indexField of collection.indexes) {
     statements.push(
@@ -702,6 +811,9 @@ ALTER TABLE ${collectionName} ADD COLUMN _version TEXT NOT NULL DEFAULT ''`
   schema_version INTEGER NOT NULL
 )`
   );
+  statements.push(
+    `CREATE INDEX IF NOT EXISTS idx_kora_ops_${collectionName}_record_id ON _kora_ops_${collectionName} (record_id)`
+  );
   return statements;
 }
 function generateFullDDL(schema) {
@@ -1167,9 +1279,9 @@ function validateFieldValue(collection, fieldName, descriptor, value) {
       break;
     }
     case "richtext": {
-      if (!(value instanceof Uint8Array) && typeof value !== "string") {
+      if (!(value instanceof Uint8Array) && !(value instanceof ArrayBuffer) && typeof value !== "string") {
         throw new SchemaValidationError(
-          `Field "${fieldName}" in collection "${collection}" must be a Uint8Array or string for richtext, got ${typeof value}`,
+          `Field "${fieldName}" in collection "${collection}" must be a Uint8Array, ArrayBuffer, or string for richtext, got ${typeof value}`,
           {
             collection,
             field: fieldName,
@@ -1906,6 +2018,7 @@ function generateProtoDefinitions(schema) {
 export {
   APPLY_FAILURE_CODES,
   APPLY_RESULTS,
+  AppNotReadyError,
   ArrayFieldBuilder,
   CONNECTION_QUALITIES,
   CausalTracker,
@@ -1913,21 +2026,26 @@ export {
   EnumFieldBuilder,
   FieldBuilder,
   HybridLogicalClock,
+  InvalidTimestampError,
   KORA_ERROR_FIX_SUGGESTIONS,
   KoraError,
+  MAX_LOGICAL,
   MERGE_STRATEGIES,
   MergeConflictError,
   MigrationBuilder,
   MigrationRollbackError,
   OperationError,
+  RemoteClockDriftError,
   RollbackBuilder,
   SchemaValidationError,
   StorageError,
   SyncError,
   advanceVector,
   applyOperationTransforms,
+  base64ToBytes,
   buildScopeMap,
   buildStateMachineConstraints,
+  bytesToBase64,
   canAutoRollback,
   collectSchemaScopeFields,
   collectSchemaScopeValueKeys,
@@ -1935,11 +2053,13 @@ export {
   createOperation,
   createReversibleMigration,
   createVersionVector,
+  decodeBytesFromOpData,
   defaultApplyFailureReason,
   defaultSequenceFormat,
   defineSchema,
   deserializeVector,
   dominates,
+  encodeBytesForOpData,
   extractScopeValuesFromClaims,
   extractTimestamp,
   formatSequenceValue,
@@ -1955,6 +2075,8 @@ export {
   isApplyFailure,
   isAtomicOp,
   isCollectionSyncScoped,
+  isKoraBytesValue,
+  isLegacyNumericByteObject,
   isValidOperation,
   isValidUUIDv7,
   mergeVectors,