@korajs/core 1.0.0-beta.1 → 1.0.0-beta.10

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { R as RandomSource, B as BlobRef, C as CollectionDefinition, A as AtomicOpType, a as AtomicOp, F as FieldBuilder, b as CustomResolver, M as MigrationDefinition, S as SchemaDefinition, c as RelationDefinition, O as OperationType, E as EnumFieldBuilder, J as JsonFieldBuilder, d as ArrayFieldBuilder, e as FieldKind, f as Operation, V as VersionVector, g as MigrationStep, h as StateMachineConstraint, T as TransitionMap, i as TransitionValidationResult } from './events-CqDkr1LN.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, D as SecretMode, G as SequenceConfig, I as StateMachineDefinition, L as SyncDiagnosticsSnapshot, N as SyncRuleDefinition, P as TimeSource, Q as migrate, U as t } from './events-CqDkr1LN.cjs';
-export { H as HybridLogicalClock, M as MAX_LOGICAL, c as createOperation, i as isValidOperation, v as verifyOperationIntegrity } from './operation-CFoY-ZmB.cjs';
-export { S as ScopeMap, b as buildScopeMap } from './build-scope-map-DtTr9C7A.cjs';
+import { R as RandomSource, B as BlobRef, C as CollectionDefinition, A as AtomicOpType, a as AtomicOp, F as FieldBuilder, b as CustomResolver, M as MigrationDefinition, S as SchemaDefinition, c as RelationDefinition, O as OperationType, E as EnumFieldBuilder, J as JsonFieldBuilder, d as ArrayFieldBuilder, e as FieldKind, f as Operation, V as VersionVector, g as MigrationStep, h as StateMachineConstraint, T as TransitionMap, i as TransitionValidationResult } from './events-3z0Tema3.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, D as SecretMode, G as SequenceConfig, I as StateMachineDefinition, L as SyncDiagnosticsSnapshot, N as SyncRuleDefinition, P as TimeSource, Q as migrate, U as t } from './events-3z0Tema3.cjs';
+export { H as HybridLogicalClock, M as MAX_LOGICAL, c as createOperation, i as isValidOperation, v as verifyOperationIntegrity } from './operation-BvBgl-4c.cjs';
+export { S as ScopeMap, b as buildScopeMap } from './build-scope-map-B8dpCt6P.cjs';
 
 /**
  * Base error class for all Kora errors.
@@ -359,6 +359,20 @@ interface AtomicOpSentinel {
  * @returns true if the value is an AtomicOpSentinel
  */
 declare function isAtomicOp(value: unknown): value is AtomicOpSentinel;
+/**
+ * Apply a plain atomic op (`{ type, value }`) to a current value, producing the
+ * concrete result. This is the single source of truth for atomic-op semantics:
+ * {@link resolveAtomicOp} (sentinel form, used on the write path) delegates here,
+ * and the server's materialization replays stored atomic ops through it, so the
+ * server's materialized view composes concurrent atomic writes identically to the
+ * client. Folding this over a field's writes in HLC order yields, for a same-type
+ * atomic chain, exactly the composed intent (sum of increments, max of maxes, ...).
+ *
+ * @param currentValue - The current value of the field
+ * @param atomicOp - The atomic op to apply (type + operand)
+ * @returns The resulting concrete value
+ */
+declare function applyAtomicOp(currentValue: unknown, atomicOp: AtomicOp): unknown;
 /**
  * Resolve an atomic op sentinel against a current value to produce a concrete result.
  *
@@ -437,6 +451,40 @@ declare const op: {
  */
 declare function toAtomicOp(sentinel: AtomicOpSentinel): AtomicOp;
 
+/** One operation's contribution to a record's materialized state. */
+interface ReplayOperation {
+    type: string;
+    data: Record<string, unknown> | null;
+    /**
+     * Atomic-op intents carried by this operation, per field. When present, a field
+     * is composed (rather than overwritten) if the previous writer on that field was
+     * an atomic op of the same type. Absent means every field resolves by
+     * last-write-wins.
+     */
+    atomicOps?: Record<string, AtomicOp> | null;
+}
+/**
+ * Replay a list of operations (MUST be pre-sorted in HLC total order —
+ * wallTime, then logical, then nodeId) to produce the current state of a single
+ * record, composing atomic-op intents.
+ *
+ * Per field, an atomic op composes onto the running value only when the field's
+ * previous writer was an atomic op of the SAME type (a same-type atomic chain:
+ * concurrent increments sum, maxes take the max, appends accumulate); any other
+ * write, including the first atomic write after a plain set, resolves by
+ * last-write-wins on the resolved value. Because operations are folded in HLC order,
+ * the current op always wins that last-write-wins comparison, so the result is
+ * deterministic and identical on every replica that folds the same operation set.
+ *
+ * This is the single definition of atomic materialization shared by the client
+ * (`@korajs/store` apply pipeline) and the server (`@korajs/server` materialization),
+ * so both converge to the same value for any number of concurrent atomic writers.
+ *
+ * Returns the record field data (without `id`) or null if the record was deleted
+ * or never inserted.
+ */
+declare function replayOperationsForRecord(ops: ReplayOperation[]): Record<string, unknown> | null;
+
 /**
  * Canonical JSON-safe encoding of binary bytes stored inside `op.data` /
  * `op.previousData` (currently richtext field values). A raw Uint8Array
@@ -605,6 +653,38 @@ declare function generateSQL(collectionName: string, collection: CollectionDefin
  */
 declare function generateFullDDL(schema: SchemaDefinition): string[];
 
+/**
+ * Quote a SQL identifier (table or column name) for safe interpolation into
+ * generated SQL.
+ *
+ * Uses standard double-quote quoting, which both SQLite and PostgreSQL honor,
+ * and doubles any embedded double-quote per the SQL standard. Quoting is what
+ * lets a valid JavaScript identifier — camelCase (`formResponses`), PascalCase
+ * (`UserProfiles`), or a word that happens to be a SQL keyword (`order`,
+ * `select`) — round-trip through generated DDL and queries without ever
+ * producing invalid or ambiguous SQL.
+ *
+ * Schema validation (see `validateCollectionName` / `validateFieldName`)
+ * already restricts identifiers to `[A-Za-z][A-Za-z0-9_]*`, so the escape here
+ * never actually fires in practice; it is defense in depth so this helper is
+ * correct for any input rather than only for pre-validated names.
+ *
+ * Consistency is the contract: every path that emits an identifier for a
+ * user-defined collection or field MUST go through this helper, because a
+ * quoted `CREATE TABLE "order"` paired with an unquoted `SELECT ... FROM order`
+ * would reintroduce the exact keyword-collision bug this guards against.
+ *
+ * @param name - The raw identifier (collection name, field/column name).
+ * @returns The identifier wrapped in double quotes, ready to splice into SQL.
+ *
+ * @example
+ * ```typescript
+ * quoteIdent('formResponses') // => '"formResponses"'
+ * quoteIdent('order')         // => '"order"'
+ * ```
+ */
+declare function quoteIdent(name: string): string;
+
 /**
  * Validates a record's data against a collection's field definitions.
  * Applies defaults, rejects auto fields, and type-checks each value.
@@ -854,7 +934,7 @@ declare function migrationStepsToSQL(steps: readonly MigrationStep[]): string[];
  *
  * const rollbackSQL = rollbackStepsToSQL(migration)
  * // ['DROP INDEX IF EXISTS idx_todos_priority',
- * //  'ALTER TABLE todos DROP COLUMN priority']
+ * //  'ALTER TABLE "todos" DROP COLUMN "priority"']
  * ```
  */
 declare function rollbackStepsToSQL(migration: MigrationDefinition): string[];
@@ -1045,4 +1125,4 @@ interface ProtoOutput {
  */
 declare function generateProtoDefinitions(schema: SchemaDefinition): ProtoOutput;
 
-export { APPLY_FAILURE_CODES, APPLY_RESULTS, AppNotReadyError, type ApplyFailureReason, type ApplyResult, ArrayFieldBuilder, AtomicOp, type AtomicOpSentinel, AtomicOpType, BlobRef, type BlobRefMetadata, CausalTracker, ClockDriftError, CollectionDefinition, type CollectionInput, type ConstraintInput, CustomResolver, EnumFieldBuilder, FieldBuilder, FieldKind, type FieldKindToType, type InferFieldType, type InferInsertInput, type InferRecord, type InferUpdateInput, InvalidTimestampError, KORA_ERROR_FIX_SUGGESTIONS, type KoraBytesValue, KoraError, MergeConflictError, MigrationDefinition, MigrationRollbackError, MigrationStep, MissingSecretKeyError, Operation, OperationError, type OperationLog, type OperationTransform, OperationType, type ProtoOutput, RandomSource, RelationDefinition, type RelationInput, RemoteClockDriftError, type ReversibleMigration, SchemaDefinition, type SchemaInput, SchemaValidationError, type SecretKeyProvider, StateMachineConstraint, type StateMachineInput, StorageError, SyncError, TransitionMap, TransitionValidationResult, type TypedSchemaDefinition, VersionVector, advanceVector, applyOperationTransforms, base64ToBytes, buildStateMachineConstraints, bytesToBase64, canAutoRollback, collectSchemaScopeFields, collectSchemaScopeValueKeys, computeDelta, createBlobRef, createReversibleMigration, createVersionVector, decodeBytesFromOpData, decryptSecret, defaultApplyFailureReason, defaultSequenceFormat, defineSchema, deserializeVector, dominates, encodeBytesForOpData, encryptSecret, extractScopeValuesFromClaims, extractTimestamp, formatSequenceValue, generateFullDDL, generateProtoDefinitions, generateRollbackSteps, generateSQL, generateUUIDv7, getCollectionScopeBindings, getKoraErrorFix, getTransitionMap, hasSchemaSyncRules, hashBlob, hashSecret, isApplyFailure, isAtomicOp, isBlobRef, isCollectionSyncScoped, isKoraBytesValue, isLegacyNumericByteObject, isValidUUIDv7, mergeVectors, migrationStepsToSQL, op, resolveAtomicOp, revealSecret, rollbackStepsToSQL, serializeVector, toAtomicOp, transformSecretFieldsForWrite, validateRecord, validateTransition, vectorsEqual, verifySecret, verifySecretValue };
+export { APPLY_FAILURE_CODES, APPLY_RESULTS, AppNotReadyError, type ApplyFailureReason, type ApplyResult, ArrayFieldBuilder, AtomicOp, type AtomicOpSentinel, AtomicOpType, BlobRef, type BlobRefMetadata, CausalTracker, ClockDriftError, CollectionDefinition, type CollectionInput, type ConstraintInput, CustomResolver, EnumFieldBuilder, FieldBuilder, FieldKind, type FieldKindToType, type InferFieldType, type InferInsertInput, type InferRecord, type InferUpdateInput, InvalidTimestampError, KORA_ERROR_FIX_SUGGESTIONS, type KoraBytesValue, KoraError, MergeConflictError, MigrationDefinition, MigrationRollbackError, MigrationStep, MissingSecretKeyError, Operation, OperationError, type OperationLog, type OperationTransform, OperationType, type ProtoOutput, RandomSource, RelationDefinition, type RelationInput, RemoteClockDriftError, type ReplayOperation, type ReversibleMigration, SchemaDefinition, type SchemaInput, SchemaValidationError, type SecretKeyProvider, StateMachineConstraint, type StateMachineInput, StorageError, SyncError, TransitionMap, TransitionValidationResult, type TypedSchemaDefinition, VersionVector, advanceVector, applyAtomicOp, applyOperationTransforms, base64ToBytes, buildStateMachineConstraints, bytesToBase64, canAutoRollback, collectSchemaScopeFields, collectSchemaScopeValueKeys, computeDelta, createBlobRef, createReversibleMigration, createVersionVector, decodeBytesFromOpData, decryptSecret, defaultApplyFailureReason, defaultSequenceFormat, defineSchema, deserializeVector, dominates, encodeBytesForOpData, encryptSecret, extractScopeValuesFromClaims, extractTimestamp, formatSequenceValue, generateFullDDL, generateProtoDefinitions, generateRollbackSteps, generateSQL, generateUUIDv7, getCollectionScopeBindings, getKoraErrorFix, getTransitionMap, hasSchemaSyncRules, hashBlob, hashSecret, isApplyFailure, isAtomicOp, isBlobRef, isCollectionSyncScoped, isKoraBytesValue, isLegacyNumericByteObject, isValidUUIDv7, mergeVectors, migrationStepsToSQL, op, quoteIdent, replayOperationsForRecord, resolveAtomicOp, revealSecret, rollbackStepsToSQL, serializeVector, toAtomicOp, transformSecretFieldsForWrite, validateRecord, validateTransition, vectorsEqual, verifySecret, verifySecretValue };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { R as RandomSource, B as BlobRef, C as CollectionDefinition, A as AtomicOpType, a as AtomicOp, F as FieldBuilder, b as CustomResolver, M as MigrationDefinition, S as SchemaDefinition, c as RelationDefinition, O as OperationType, E as EnumFieldBuilder, J as JsonFieldBuilder, d as ArrayFieldBuilder, e as FieldKind, f as Operation, V as VersionVector, g as MigrationStep, h as StateMachineConstraint, T as TransitionMap, i as TransitionValidationResult } from './events-CqDkr1LN.js';
-export { j as CONNECTION_QUALITIES, k as ConnectionQuality, l as Constraint, m as FieldDescriptor, n as FieldMergeStrategy, H as HLCTimestamp, K as KoraEvent, o as KoraEventByType, p as KoraEventEmitter, q as KoraEventListener, r as KoraEventType, s as MERGE_STRATEGIES, t as MergeStrategy, u as MergeTrace, v as MigrationBuilder, w as OnDeleteAction, x as OperationInput, y as RelationType, z as RollbackBuilder, D as SecretMode, G as SequenceConfig, I as StateMachineDefinition, L as SyncDiagnosticsSnapshot, N as SyncRuleDefinition, P as TimeSource, Q as migrate, U as t } from './events-CqDkr1LN.js';
-export { H as HybridLogicalClock, M as MAX_LOGICAL, c as createOperation, i as isValidOperation, v as verifyOperationIntegrity } from './operation-BJtu18Fi.js';
-export { S as ScopeMap, b as buildScopeMap } from './build-scope-map-DvOHbYjn.js';
+import { R as RandomSource, B as BlobRef, C as CollectionDefinition, A as AtomicOpType, a as AtomicOp, F as FieldBuilder, b as CustomResolver, M as MigrationDefinition, S as SchemaDefinition, c as RelationDefinition, O as OperationType, E as EnumFieldBuilder, J as JsonFieldBuilder, d as ArrayFieldBuilder, e as FieldKind, f as Operation, V as VersionVector, g as MigrationStep, h as StateMachineConstraint, T as TransitionMap, i as TransitionValidationResult } from './events-3z0Tema3.js';
+export { j as CONNECTION_QUALITIES, k as ConnectionQuality, l as Constraint, m as FieldDescriptor, n as FieldMergeStrategy, H as HLCTimestamp, K as KoraEvent, o as KoraEventByType, p as KoraEventEmitter, q as KoraEventListener, r as KoraEventType, s as MERGE_STRATEGIES, t as MergeStrategy, u as MergeTrace, v as MigrationBuilder, w as OnDeleteAction, x as OperationInput, y as RelationType, z as RollbackBuilder, D as SecretMode, G as SequenceConfig, I as StateMachineDefinition, L as SyncDiagnosticsSnapshot, N as SyncRuleDefinition, P as TimeSource, Q as migrate, U as t } from './events-3z0Tema3.js';
+export { H as HybridLogicalClock, M as MAX_LOGICAL, c as createOperation, i as isValidOperation, v as verifyOperationIntegrity } from './operation-ClhEbhoV.js';
+export { S as ScopeMap, b as buildScopeMap } from './build-scope-map-CDpIGOsf.js';
 
 /**
  * Base error class for all Kora errors.
@@ -359,6 +359,20 @@ interface AtomicOpSentinel {
  * @returns true if the value is an AtomicOpSentinel
  */
 declare function isAtomicOp(value: unknown): value is AtomicOpSentinel;
+/**
+ * Apply a plain atomic op (`{ type, value }`) to a current value, producing the
+ * concrete result. This is the single source of truth for atomic-op semantics:
+ * {@link resolveAtomicOp} (sentinel form, used on the write path) delegates here,
+ * and the server's materialization replays stored atomic ops through it, so the
+ * server's materialized view composes concurrent atomic writes identically to the
+ * client. Folding this over a field's writes in HLC order yields, for a same-type
+ * atomic chain, exactly the composed intent (sum of increments, max of maxes, ...).
+ *
+ * @param currentValue - The current value of the field
+ * @param atomicOp - The atomic op to apply (type + operand)
+ * @returns The resulting concrete value
+ */
+declare function applyAtomicOp(currentValue: unknown, atomicOp: AtomicOp): unknown;
 /**
  * Resolve an atomic op sentinel against a current value to produce a concrete result.
  *
@@ -437,6 +451,40 @@ declare const op: {
  */
 declare function toAtomicOp(sentinel: AtomicOpSentinel): AtomicOp;
 
+/** One operation's contribution to a record's materialized state. */
+interface ReplayOperation {
+    type: string;
+    data: Record<string, unknown> | null;
+    /**
+     * Atomic-op intents carried by this operation, per field. When present, a field
+     * is composed (rather than overwritten) if the previous writer on that field was
+     * an atomic op of the same type. Absent means every field resolves by
+     * last-write-wins.
+     */
+    atomicOps?: Record<string, AtomicOp> | null;
+}
+/**
+ * Replay a list of operations (MUST be pre-sorted in HLC total order —
+ * wallTime, then logical, then nodeId) to produce the current state of a single
+ * record, composing atomic-op intents.
+ *
+ * Per field, an atomic op composes onto the running value only when the field's
+ * previous writer was an atomic op of the SAME type (a same-type atomic chain:
+ * concurrent increments sum, maxes take the max, appends accumulate); any other
+ * write, including the first atomic write after a plain set, resolves by
+ * last-write-wins on the resolved value. Because operations are folded in HLC order,
+ * the current op always wins that last-write-wins comparison, so the result is
+ * deterministic and identical on every replica that folds the same operation set.
+ *
+ * This is the single definition of atomic materialization shared by the client
+ * (`@korajs/store` apply pipeline) and the server (`@korajs/server` materialization),
+ * so both converge to the same value for any number of concurrent atomic writers.
+ *
+ * Returns the record field data (without `id`) or null if the record was deleted
+ * or never inserted.
+ */
+declare function replayOperationsForRecord(ops: ReplayOperation[]): Record<string, unknown> | null;
+
 /**
  * Canonical JSON-safe encoding of binary bytes stored inside `op.data` /
  * `op.previousData` (currently richtext field values). A raw Uint8Array
@@ -605,6 +653,38 @@ declare function generateSQL(collectionName: string, collection: CollectionDefin
  */
 declare function generateFullDDL(schema: SchemaDefinition): string[];
 
+/**
+ * Quote a SQL identifier (table or column name) for safe interpolation into
+ * generated SQL.
+ *
+ * Uses standard double-quote quoting, which both SQLite and PostgreSQL honor,
+ * and doubles any embedded double-quote per the SQL standard. Quoting is what
+ * lets a valid JavaScript identifier — camelCase (`formResponses`), PascalCase
+ * (`UserProfiles`), or a word that happens to be a SQL keyword (`order`,
+ * `select`) — round-trip through generated DDL and queries without ever
+ * producing invalid or ambiguous SQL.
+ *
+ * Schema validation (see `validateCollectionName` / `validateFieldName`)
+ * already restricts identifiers to `[A-Za-z][A-Za-z0-9_]*`, so the escape here
+ * never actually fires in practice; it is defense in depth so this helper is
+ * correct for any input rather than only for pre-validated names.
+ *
+ * Consistency is the contract: every path that emits an identifier for a
+ * user-defined collection or field MUST go through this helper, because a
+ * quoted `CREATE TABLE "order"` paired with an unquoted `SELECT ... FROM order`
+ * would reintroduce the exact keyword-collision bug this guards against.
+ *
+ * @param name - The raw identifier (collection name, field/column name).
+ * @returns The identifier wrapped in double quotes, ready to splice into SQL.
+ *
+ * @example
+ * ```typescript
+ * quoteIdent('formResponses') // => '"formResponses"'
+ * quoteIdent('order')         // => '"order"'
+ * ```
+ */
+declare function quoteIdent(name: string): string;
+
 /**
  * Validates a record's data against a collection's field definitions.
  * Applies defaults, rejects auto fields, and type-checks each value.
@@ -854,7 +934,7 @@ declare function migrationStepsToSQL(steps: readonly MigrationStep[]): string[];
  *
  * const rollbackSQL = rollbackStepsToSQL(migration)
  * // ['DROP INDEX IF EXISTS idx_todos_priority',
- * //  'ALTER TABLE todos DROP COLUMN priority']
+ * //  'ALTER TABLE "todos" DROP COLUMN "priority"']
  * ```
  */
 declare function rollbackStepsToSQL(migration: MigrationDefinition): string[];
@@ -1045,4 +1125,4 @@ interface ProtoOutput {
  */
 declare function generateProtoDefinitions(schema: SchemaDefinition): ProtoOutput;
 
-export { APPLY_FAILURE_CODES, APPLY_RESULTS, AppNotReadyError, type ApplyFailureReason, type ApplyResult, ArrayFieldBuilder, AtomicOp, type AtomicOpSentinel, AtomicOpType, BlobRef, type BlobRefMetadata, CausalTracker, ClockDriftError, CollectionDefinition, type CollectionInput, type ConstraintInput, CustomResolver, EnumFieldBuilder, FieldBuilder, FieldKind, type FieldKindToType, type InferFieldType, type InferInsertInput, type InferRecord, type InferUpdateInput, InvalidTimestampError, KORA_ERROR_FIX_SUGGESTIONS, type KoraBytesValue, KoraError, MergeConflictError, MigrationDefinition, MigrationRollbackError, MigrationStep, MissingSecretKeyError, Operation, OperationError, type OperationLog, type OperationTransform, OperationType, type ProtoOutput, RandomSource, RelationDefinition, type RelationInput, RemoteClockDriftError, type ReversibleMigration, SchemaDefinition, type SchemaInput, SchemaValidationError, type SecretKeyProvider, StateMachineConstraint, type StateMachineInput, StorageError, SyncError, TransitionMap, TransitionValidationResult, type TypedSchemaDefinition, VersionVector, advanceVector, applyOperationTransforms, base64ToBytes, buildStateMachineConstraints, bytesToBase64, canAutoRollback, collectSchemaScopeFields, collectSchemaScopeValueKeys, computeDelta, createBlobRef, createReversibleMigration, createVersionVector, decodeBytesFromOpData, decryptSecret, defaultApplyFailureReason, defaultSequenceFormat, defineSchema, deserializeVector, dominates, encodeBytesForOpData, encryptSecret, extractScopeValuesFromClaims, extractTimestamp, formatSequenceValue, generateFullDDL, generateProtoDefinitions, generateRollbackSteps, generateSQL, generateUUIDv7, getCollectionScopeBindings, getKoraErrorFix, getTransitionMap, hasSchemaSyncRules, hashBlob, hashSecret, isApplyFailure, isAtomicOp, isBlobRef, isCollectionSyncScoped, isKoraBytesValue, isLegacyNumericByteObject, isValidUUIDv7, mergeVectors, migrationStepsToSQL, op, resolveAtomicOp, revealSecret, rollbackStepsToSQL, serializeVector, toAtomicOp, transformSecretFieldsForWrite, validateRecord, validateTransition, vectorsEqual, verifySecret, verifySecretValue };
+export { APPLY_FAILURE_CODES, APPLY_RESULTS, AppNotReadyError, type ApplyFailureReason, type ApplyResult, ArrayFieldBuilder, AtomicOp, type AtomicOpSentinel, AtomicOpType, BlobRef, type BlobRefMetadata, CausalTracker, ClockDriftError, CollectionDefinition, type CollectionInput, type ConstraintInput, CustomResolver, EnumFieldBuilder, FieldBuilder, FieldKind, type FieldKindToType, type InferFieldType, type InferInsertInput, type InferRecord, type InferUpdateInput, InvalidTimestampError, KORA_ERROR_FIX_SUGGESTIONS, type KoraBytesValue, KoraError, MergeConflictError, MigrationDefinition, MigrationRollbackError, MigrationStep, MissingSecretKeyError, Operation, OperationError, type OperationLog, type OperationTransform, OperationType, type ProtoOutput, RandomSource, RelationDefinition, type RelationInput, RemoteClockDriftError, type ReplayOperation, type ReversibleMigration, SchemaDefinition, type SchemaInput, SchemaValidationError, type SecretKeyProvider, StateMachineConstraint, type StateMachineInput, StorageError, SyncError, TransitionMap, TransitionValidationResult, type TypedSchemaDefinition, VersionVector, advanceVector, applyAtomicOp, applyOperationTransforms, base64ToBytes, buildStateMachineConstraints, bytesToBase64, canAutoRollback, collectSchemaScopeFields, collectSchemaScopeValueKeys, computeDelta, createBlobRef, createReversibleMigration, createVersionVector, decodeBytesFromOpData, decryptSecret, defaultApplyFailureReason, defaultSequenceFormat, defineSchema, deserializeVector, dominates, encodeBytesForOpData, encryptSecret, extractScopeValuesFromClaims, extractTimestamp, formatSequenceValue, generateFullDDL, generateProtoDefinitions, generateRollbackSteps, generateSQL, generateUUIDv7, getCollectionScopeBindings, getKoraErrorFix, getTransitionMap, hasSchemaSyncRules, hashBlob, hashSecret, isApplyFailure, isAtomicOp, isBlobRef, isCollectionSyncScoped, isKoraBytesValue, isLegacyNumericByteObject, isValidUUIDv7, mergeVectors, migrationStepsToSQL, op, quoteIdent, replayOperationsForRecord, resolveAtomicOp, revealSecret, rollbackStepsToSQL, serializeVector, toAtomicOp, transformSecretFieldsForWrite, validateRecord, validateTransition, vectorsEqual, verifySecret, verifySecretValue };

package/dist/index.js

@@ -365,32 +365,36 @@ var KORA_ATOMIC_OP = /* @__PURE__ */ Symbol.for("kora.atomic_op");
 function isAtomicOp(value) {
   return typeof value === "object" && value !== null && KORA_ATOMIC_OP in value && value[KORA_ATOMIC_OP] === true;
 }
-function resolveAtomicOp(currentValue, sentinel) {
-  switch (sentinel.type) {
+function applyAtomicOp(currentValue, atomicOp) {
+  switch (atomicOp.type) {
     case "increment": {
       const current = typeof currentValue === "number" ? currentValue : 0;
-      const operand = sentinel.value;
+      const operand = atomicOp.value;
       return current + operand;
     }
     case "max": {
       const current = typeof currentValue === "number" ? currentValue : Number.NEGATIVE_INFINITY;
-      return Math.max(current, sentinel.value);
+      return Math.max(current, atomicOp.value);
     }
     case "min": {
       const current = typeof currentValue === "number" ? currentValue : Number.POSITIVE_INFINITY;
-      return Math.min(current, sentinel.value);
+      return Math.min(current, atomicOp.value);
     }
     case "append": {
       const current = Array.isArray(currentValue) ? [...currentValue] : [];
-      current.push(sentinel.value);
+      current.push(atomicOp.value);
       return current;
     }
     case "remove": {
       if (!Array.isArray(currentValue)) return [];
-      return currentValue.filter((item) => item !== sentinel.value);
+      const target = JSON.stringify(atomicOp.value);
+      return currentValue.filter((item) => JSON.stringify(item) !== target);
     }
   }
 }
+function resolveAtomicOp(currentValue, sentinel) {
+  return applyAtomicOp(currentValue, { type: sentinel.type, value: sentinel.value });
+}
 function createSentinel(type, value) {
   return Object.freeze({
     [KORA_ATOMIC_OP]: true,
@@ -458,6 +462,46 @@ function toAtomicOp(sentinel) {
   return { type: sentinel.type, value: sentinel.value };
 }
 
+// src/operations/replay-record.ts
+function replayOperationsForRecord(ops) {
+  let record = null;
+  let deleted = false;
+  const lastWriterKind = {};
+  for (const op2 of ops) {
+    switch (op2.type) {
+      case "insert":
+        if (op2.data) {
+          record = { ...op2.data };
+          deleted = false;
+          for (const field of Object.keys(op2.data)) {
+            lastWriterKind[field] = "lww";
+          }
+        }
+        break;
+      case "update":
+        if (op2.data) {
+          const next = { ...record ?? {} };
+          for (const [field, value] of Object.entries(op2.data)) {
+            const atomicOp = op2.atomicOps?.[field];
+            if (atomicOp && lastWriterKind[field] === `atomic:${atomicOp.type}`) {
+              next[field] = applyAtomicOp(next[field], atomicOp);
+            } else {
+              next[field] = value;
+            }
+            lastWriterKind[field] = atomicOp ? `atomic:${atomicOp.type}` : "lww";
+          }
+          record = next;
+          deleted = false;
+        }
+        break;
+      case "delete":
+        deleted = true;
+        break;
+    }
+  }
+  return deleted ? null : record;
+}
+
 // src/operations/op-data-binary.ts
 function isKoraBytesValue(value) {
   if (typeof value !== "object" || value === null) {
@@ -708,7 +752,7 @@ function validateStateMachineDefinition(collectionName, sm, fields) {
 }
 
 // src/schema/define.ts
-var COLLECTION_NAME_RE = /^[a-z][a-z0-9_]*$/;
+var COLLECTION_NAME_RE = /^[A-Za-z][A-Za-z0-9_]*$/;
 var FIELD_NAME_RE = /^[a-z][a-zA-Z0-9_]*$/;
 var RESERVED_FIELDS = /* @__PURE__ */ new Set(["id", "_created_at", "_updated_at", "_version", "_deleted"]);
 function defineSchema(input) {
@@ -773,7 +817,7 @@ function validateVersion(version) {
 function validateCollectionName(name) {
   if (!COLLECTION_NAME_RE.test(name)) {
     throw new SchemaValidationError(
-      `Collection name "${name}" is invalid. Must be lowercase, start with a letter, and contain only letters, numbers, and underscores.`,
+      `Collection name "${name}" is invalid. Must start with a letter and contain only letters, numbers, and underscores.`,
       { collection: name }
     );
   }
@@ -965,6 +1009,11 @@ function validateRelation(name, relation, collections) {
   }
 }
 
+// src/schema/quote-ident.ts
+function quoteIdent(name) {
+  return `"${name.replace(/"/g, '""')}"`;
+}
+
 // src/schema/sql-gen.ts
 function generateSQL(collectionName, collection, relations) {
   const statements = [];
@@ -976,7 +1025,7 @@ function generateSQL(collectionName, collection, relations) {
     if (relations) {
       for (const rel of Object.values(relations)) {
         if (rel.from === collectionName && rel.field === fieldName) {
-          colDef += ` REFERENCES ${rel.to}(id)`;
+          colDef += ` REFERENCES ${quoteIdent(rel.to)}(id)`;
           fkFields.push(fieldName);
           break;
         }
@@ -989,36 +1038,40 @@ function generateSQL(collectionName, collection, relations) {
   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} (
+  statements.push(
+    `CREATE TABLE IF NOT EXISTS ${quoteIdent(collectionName)} (
   ${columns.join(",\n  ")}
-)`);
+)`
+  );
   for (const [fieldName, descriptor] of Object.entries(collection.fields)) {
     const colDef = columnDefinition(fieldName, descriptor);
-    statements.push(`--kora:safe-alter
-ALTER TABLE ${collectionName} ADD COLUMN ${colDef}`);
+    statements.push(
+      `--kora:safe-alter
+ALTER TABLE ${quoteIdent(collectionName)} ADD COLUMN ${colDef}`
+    );
   }
   statements.push(
     `--kora:safe-alter
-ALTER TABLE ${collectionName} ADD COLUMN _version TEXT NOT NULL DEFAULT ''`
+ALTER TABLE ${quoteIdent(collectionName)} ADD COLUMN _version TEXT NOT NULL DEFAULT ''`
   );
   statements.push(
     `--kora:safe-alter
-ALTER TABLE ${collectionName} ADD COLUMN _field_versions TEXT NOT NULL DEFAULT '{}'`
+ALTER TABLE ${quoteIdent(collectionName)} ADD COLUMN _field_versions TEXT NOT NULL DEFAULT '{}'`
   );
   for (const indexField of collection.indexes) {
     statements.push(
-      `CREATE INDEX IF NOT EXISTS idx_${collectionName}_${indexField} ON ${collectionName} (${indexField})`
+      `CREATE INDEX IF NOT EXISTS idx_${collectionName}_${indexField} ON ${quoteIdent(collectionName)} (${quoteIdent(indexField)})`
     );
   }
   for (const fkField of fkFields) {
     if (!indexedFields.has(fkField)) {
       statements.push(
-        `CREATE INDEX IF NOT EXISTS idx_${collectionName}_${fkField} ON ${collectionName} (${fkField})`
+        `CREATE INDEX IF NOT EXISTS idx_${collectionName}_${fkField} ON ${quoteIdent(collectionName)} (${quoteIdent(fkField)})`
       );
     }
   }
   statements.push(
-    `CREATE TABLE IF NOT EXISTS _kora_ops_${collectionName} (
+    `CREATE TABLE IF NOT EXISTS ${quoteIdent(`_kora_ops_${collectionName}`)} (
   id TEXT PRIMARY KEY NOT NULL,
   node_id TEXT NOT NULL,
   type TEXT NOT NULL,
@@ -1032,7 +1085,7 @@ ALTER TABLE ${collectionName} ADD COLUMN _field_versions TEXT NOT NULL DEFAULT '
 )`
   );
   statements.push(
-    `CREATE INDEX IF NOT EXISTS idx_kora_ops_${collectionName}_record_id ON _kora_ops_${collectionName} (record_id)`
+    `CREATE INDEX IF NOT EXISTS idx_kora_ops_${collectionName}_record_id ON ${quoteIdent(`_kora_ops_${collectionName}`)} (record_id)`
   );
   return statements;
 }
@@ -1050,6 +1103,9 @@ function generateFullDDL(schema) {
   statements.push(
     "CREATE TABLE IF NOT EXISTS _kora_sync_queue (\n  id TEXT PRIMARY KEY NOT NULL,\n  payload TEXT NOT NULL\n)"
   );
+  statements.push(
+    "CREATE TABLE IF NOT EXISTS _kora_sync_rejected (\n  operation_id TEXT PRIMARY KEY NOT NULL,\n  collection TEXT NOT NULL,\n  record_id TEXT NOT NULL,\n  code TEXT NOT NULL,\n  message TEXT NOT NULL,\n  retriable INTEGER NOT NULL,\n  rejected_at INTEGER NOT NULL\n)"
+  );
   statements.push(
     "CREATE TABLE IF NOT EXISTS _kora_audit_traces (\n  id TEXT PRIMARY KEY NOT NULL,\n  recorded_at INTEGER NOT NULL,\n  event_type TEXT NOT NULL,\n  collection TEXT NOT NULL,\n  record_id TEXT NOT NULL,\n  field TEXT NOT NULL,\n  strategy TEXT NOT NULL,\n  tier INTEGER NOT NULL,\n  constraint_name TEXT,\n  trace_json TEXT NOT NULL\n)"
   );
@@ -1066,7 +1122,7 @@ function generateFullDDL(schema) {
 }
 function columnDefinition(fieldName, descriptor) {
   const sqlType = mapFieldType(descriptor);
-  const parts = [fieldName, sqlType];
+  const parts = [quoteIdent(fieldName), sqlType];
   if (descriptor.required && descriptor.defaultValue === void 0 && !descriptor.auto) {
     parts.push("NOT NULL");
   }
@@ -1075,7 +1131,7 @@ function columnDefinition(fieldName, descriptor) {
   }
   if (descriptor.kind === "enum" && descriptor.enumValues) {
     const values = descriptor.enumValues.map((v) => `'${v}'`).join(", ");
-    parts.push(`CHECK (${fieldName} IN (${values}))`);
+    parts.push(`CHECK (${quoteIdent(fieldName)} IN (${values}))`);
   }
   return parts.join(" ");
 }
@@ -1717,10 +1773,17 @@ function validateFieldValue(collection, fieldName, descriptor, value) {
       break;
     }
     case "json": {
-      if (!isJsonSerializable(value)) {
+      const nonJson = findNonJsonSerializable(value, fieldName);
+      if (nonJson) {
         throw new SchemaValidationError(
-          `Field "${fieldName}" in collection "${collection}" must be JSON-serializable, got ${describeType(value)}`,
-          { collection, field: fieldName, expectedType: "json", receivedType: describeType(value) }
+          `Field "${fieldName}" in collection "${collection}" must be JSON-serializable; found ${nonJson.receivedType} at "${nonJson.path}"`,
+          {
+            collection,
+            field: fieldName,
+            expectedType: "json",
+            receivedType: nonJson.receivedType,
+            path: nonJson.path
+          }
         );
       }
       break;
@@ -1757,21 +1820,41 @@ function isPlainObject(value) {
   const proto = Object.getPrototypeOf(value);
   return proto === null || proto === Object.prototype;
 }
-function isJsonSerializable(value) {
+function findNonJsonSerializable(value, path, seen = /* @__PURE__ */ new WeakSet()) {
   if (value === null) {
-    return true;
+    return null;
   }
   const type = typeof value;
   if (type === "string" || type === "number" || type === "boolean") {
-    return Number.isFinite(value) || type !== "number";
+    if (type === "number" && !Number.isFinite(value)) {
+      return { path, receivedType: describeType(value) };
+    }
+    return null;
+  }
+  if (type === "undefined" || type === "function" || type === "symbol" || type === "bigint") {
+    return { path, receivedType: describeType(value) };
   }
   if (Array.isArray(value)) {
-    return value.every(isJsonSerializable);
+    for (let index = 0; index < value.length; index++) {
+      const invalid = findNonJsonSerializable(value[index], `${path}[${index}]`, seen);
+      if (invalid) return invalid;
+    }
+    return null;
   }
   if (type === "object") {
-    return Object.values(value).every(isJsonSerializable);
+    const objectValue = value;
+    if (seen.has(objectValue)) {
+      return { path, receivedType: "circular object" };
+    }
+    seen.add(objectValue);
+    for (const [key, nestedValue] of Object.entries(objectValue)) {
+      const invalid = findNonJsonSerializable(nestedValue, `${path}.${key}`, seen);
+      if (invalid) return invalid;
+    }
+    seen.delete(objectValue);
+    return null;
   }
-  return false;
+  return { path, receivedType: describeType(value) };
 }
 function describeType(value) {
   if (value === null) {
@@ -2212,14 +2295,18 @@ function migrationStepsToSQL(steps) {
         statements.push(addFieldSQL(step.collection, step.field, step.descriptor));
         break;
       case "removeField":
-        statements.push(`ALTER TABLE ${step.collection} DROP COLUMN ${step.field}`);
+        statements.push(
+          `ALTER TABLE ${quoteIdent(step.collection)} DROP COLUMN ${quoteIdent(step.field)}`
+        );
         break;
       case "renameField":
-        statements.push(`ALTER TABLE ${step.collection} RENAME COLUMN ${step.from} TO ${step.to}`);
+        statements.push(
+          `ALTER TABLE ${quoteIdent(step.collection)} RENAME COLUMN ${quoteIdent(step.from)} TO ${quoteIdent(step.to)}`
+        );
         break;
       case "addIndex":
         statements.push(
-          `CREATE INDEX IF NOT EXISTS idx_${step.collection}_${step.field} ON ${step.collection} (${step.field})`
+          `CREATE INDEX IF NOT EXISTS idx_${step.collection}_${step.field} ON ${quoteIdent(step.collection)} (${quoteIdent(step.field)})`
         );
         break;
       case "removeIndex":
@@ -2237,13 +2324,13 @@ function rollbackStepsToSQL(migration) {
 }
 function addFieldSQL(collection, field, descriptor) {
   const sqlType = mapFieldType2(descriptor);
-  const parts = [`ALTER TABLE ${collection} ADD COLUMN ${field}`, sqlType];
+  const parts = [`ALTER TABLE ${quoteIdent(collection)} ADD COLUMN ${quoteIdent(field)}`, sqlType];
   if (descriptor.defaultValue !== void 0) {
     parts.push(`DEFAULT ${sqlDefault2(descriptor.defaultValue)}`);
   }
   if (descriptor.kind === "enum" && descriptor.enumValues) {
     const values = descriptor.enumValues.map((v) => `'${v}'`).join(", ");
-    parts.push(`CHECK (${field} IN (${values}))`);
+    parts.push(`CHECK (${quoteIdent(field)} IN (${values}))`);
   }
   return parts.join(" ");
 }
@@ -2545,6 +2632,7 @@ export {
   StorageError,
   SyncError,
   advanceVector,
+  applyAtomicOp,
   applyOperationTransforms,
   base64ToBytes,
   buildScopeMap,
@@ -2593,6 +2681,8 @@ export {
   migrate,
   migrationStepsToSQL,
   op,
+  quoteIdent,
+  replayOperationsForRecord,
   resolveAtomicOp,
   revealSecret,
   rollbackStepsToSQL,