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

package/dist/bindings/index.d.cts

@@ -1,9 +1,10 @@
-import { p as KoraEventEmitter } from '../events-BynBOsO3.cjs';
-import { S as ScopeMap } from '../build-scope-map-BIeawJzC.cjs';
+import { p as KoraEventEmitter } from '../events-3z0Tema3.cjs';
+import { S as ScopeMap } from '../build-scope-map-B8dpCt6P.cjs';
 
 /** Sync status shape consumed by framework binding hooks (matches {@link SyncStatusInfo} in `@korajs/sync`). */
 interface KoraBindingSyncStatus {
-    status: 'connected' | 'syncing' | 'synced' | 'offline' | 'error' | 'schema-mismatch' | 'clock-error';
+    status: 'connected' | 'reconnecting' | 'syncing' | 'synced' | 'offline' | 'error' | 'schema-mismatch' | 'clock-error';
+    reconnecting: boolean;
     pendingOperations: number;
     lastSyncedAt: number | null;
     lastSuccessfulPush: number | null;
@@ -72,6 +73,8 @@ interface AuthSyncBinding {
      * Separate from the user id (`sub`).
      */
     resolveNodeId?: () => Promise<string | undefined>;
+    /** Returns the authenticated user id used for local store namespacing. */
+    resolveUserId?: () => Promise<string | undefined>;
     /** Notifies when auth state changes so sync can refresh scope or reconnect. */
     subscribe?: (listener: () => void) => () => void;
 }

package/dist/bindings/index.d.ts

@@ -1,9 +1,10 @@
-import { p as KoraEventEmitter } from '../events-BynBOsO3.js';
-import { S as ScopeMap } from '../build-scope-map-DOf4JLTh.js';
+import { p as KoraEventEmitter } from '../events-3z0Tema3.js';
+import { S as ScopeMap } from '../build-scope-map-CDpIGOsf.js';
 
 /** Sync status shape consumed by framework binding hooks (matches {@link SyncStatusInfo} in `@korajs/sync`). */
 interface KoraBindingSyncStatus {
-    status: 'connected' | 'syncing' | 'synced' | 'offline' | 'error' | 'schema-mismatch' | 'clock-error';
+    status: 'connected' | 'reconnecting' | 'syncing' | 'synced' | 'offline' | 'error' | 'schema-mismatch' | 'clock-error';
+    reconnecting: boolean;
     pendingOperations: number;
     lastSyncedAt: number | null;
     lastSuccessfulPush: number | null;
@@ -72,6 +73,8 @@ interface AuthSyncBinding {
      * Separate from the user id (`sub`).
      */
     resolveNodeId?: () => Promise<string | undefined>;
+    /** Returns the authenticated user id used for local store namespacing. */
+    resolveUserId?: () => Promise<string | undefined>;
     /** Notifies when auth state changes so sync can refresh scope or reconnect. */
     subscribe?: (listener: () => void) => () => void;
 }

package/dist/{build-scope-map-BIeawJzC.d.cts → build-scope-map-B8dpCt6P.d.cts}

@@ -1,4 +1,4 @@
-import { S as SchemaDefinition } from './events-BynBOsO3.cjs';
+import { S as SchemaDefinition } from './events-3z0Tema3.cjs';
 
 /**
  * Per-collection scope map: `{ collectionName: { field: value, ... } }`

package/dist/{build-scope-map-DOf4JLTh.d.ts → build-scope-map-CDpIGOsf.d.ts}

@@ -1,4 +1,4 @@
-import { S as SchemaDefinition } from './events-BynBOsO3.js';
+import { S as SchemaDefinition } from './events-3z0Tema3.js';
 
 /**
  * Per-collection scope map: `{ collectionName: { field: value, ... } }`

package/dist/{events-BynBOsO3.d.cts → events-3z0Tema3.d.cts}

@@ -89,6 +89,56 @@ declare class ArrayFieldBuilder<ItemKind extends FieldKind = FieldKind, Req exte
     merge(strategy: FieldMergeStrategy): ArrayFieldBuilder<ItemKind, Req, Auto>;
     _build(): FieldDescriptor;
 }
+/**
+ * Field builder for structured object fields with a nested field schema.
+ *
+ * Each nested key merges by its own declared kind (scalars via LWW, nested
+ * arrays via add-wins, nested objects recursively), so two devices editing
+ * different keys of the same object offline both converge on reconnect instead
+ * of one clobbering the other.
+ */
+declare class ObjectFieldBuilder<Req extends boolean = true, Auto extends boolean = false> extends FieldBuilder<'object', Req, Auto> {
+    private readonly _fields;
+    constructor(fields: Record<string, FieldBuilder>, required?: Req, defaultValue?: unknown, auto?: Auto, mergeStrategy?: FieldMergeStrategy | null);
+    optional(): ObjectFieldBuilder<false, Auto>;
+    default(value: Record<string, unknown>): ObjectFieldBuilder<false, Auto>;
+    auto(): ObjectFieldBuilder<false, true>;
+    merge(strategy: FieldMergeStrategy): ObjectFieldBuilder<Req, Auto>;
+    _build(): FieldDescriptor;
+}
+/**
+ * Field builder for dynamic-key JSON values. Carries a compile-time shape `T`
+ * for inference while merging structurally as a convergent CRDT: a plain-object
+ * value recurses as a map, an array merges add-wins, any other value is a scalar
+ * leaf under last-write-wins.
+ */
+declare class JsonFieldBuilder<T = unknown, Req extends boolean = true, Auto extends boolean = false> extends FieldBuilder<'json', Req, Auto> {
+    optional(): JsonFieldBuilder<T, false, Auto>;
+    default(value: T): JsonFieldBuilder<T, false, Auto>;
+    auto(): JsonFieldBuilder<T, false, true>;
+    merge(strategy: FieldMergeStrategy): JsonFieldBuilder<T, Req, Auto>;
+    _build(): FieldDescriptor;
+}
+/**
+ * Field builder for secret fields (passwords, tokens, API keys).
+ *
+ * A secret field's value is never exposed in merge traces, DevTools, or logs
+ * (it is redacted at the point traces are built). Its at-rest protection is
+ * chosen with `.hashed()` (one-way, for passwords) or `.encrypted()` (reversible,
+ * for tokens); the default is `encrypted`.
+ */
+declare class SecretFieldBuilder<Req extends boolean = true, Auto extends boolean = false> extends FieldBuilder<'secret', Req, Auto> {
+    private readonly _secretMode;
+    constructor(secretMode?: SecretMode, required?: Req, defaultValue?: unknown, auto?: Auto, mergeStrategy?: FieldMergeStrategy | null);
+    /** Store this secret as a one-way salted hash (passwords: verify, never read back). */
+    hashed(): SecretFieldBuilder<Req, Auto>;
+    /** Store this secret as reversible ciphertext (tokens/keys: decrypt to use). */
+    encrypted(): SecretFieldBuilder<Req, Auto>;
+    optional(): SecretFieldBuilder<false, Auto>;
+    auto(): SecretFieldBuilder<false, true>;
+    merge(strategy: FieldMergeStrategy): SecretFieldBuilder<Req, Auto>;
+    _build(): FieldDescriptor;
+}
 /**
  * Type builder namespace. The developer's primary interface for defining field types.
  *
@@ -103,6 +153,8 @@ declare class ArrayFieldBuilder<ItemKind extends FieldKind = FieldKind, Req exte
  *   notes: t.richtext(),
  *   tags: t.array(t.string()).default([]),
  *   priority: t.enum(['low', 'medium', 'high']).default('medium'),
+ *   settings: t.object({ theme: t.string(), fontSize: t.number() }),
+ *   metadata: t.json<{ source: string }>(),
  *   createdAt: t.timestamp().auto(),
  * }
  * ```
@@ -115,6 +167,10 @@ declare const t: {
     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>;
+    object(fields: Record<string, FieldBuilder>): ObjectFieldBuilder<true, false>;
+    json<T = unknown>(): JsonFieldBuilder<T, true, false>;
+    blob(): FieldBuilder<"blob", true, false>;
+    secret(): SecretFieldBuilder<true, false>;
 };
 
 /**
@@ -390,7 +446,39 @@ interface OperationInput {
 /** 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';
+type FieldKind = 'string' | 'number' | 'boolean' | 'timestamp' | 'richtext' | 'enum' | 'array' | 'object' | 'json' | 'blob' | 'secret';
+/**
+ * How a `secret` field's value is protected at rest.
+ * - `hashed`: one-way (passwords). Stored as a salted hash; never read back.
+ * - `encrypted`: reversible (tokens, keys). Stored as ciphertext; decrypted to use.
+ */
+type SecretMode = 'hashed' | 'encrypted';
+/**
+ * A content-addressed reference to binary data stored out of band.
+ *
+ * A `blob` field never carries the bytes in the operation log; it carries this
+ * small reference. The bytes live in a content-addressed blob store, keyed by
+ * `hash`, so identical content is stored once and never re-synced to a peer that
+ * already has that hash.
+ */
+interface BlobRef {
+    /** Hex-encoded SHA-256 hash of the bytes. The content address. */
+    hash: string;
+    /** Size of the bytes in bytes. */
+    size: number;
+    /** Optional MIME type (for example "image/png"). */
+    mimeType?: string;
+    /** Optional original filename. */
+    filename?: string;
+    /**
+     * Hex-encoded SHA-256 hash of this blob's manifest — the small chunk index a
+     * peer fetches first to learn how to pull the bytes out of band. Present when
+     * the blob was stored for transfer; absent for a bare reference created without
+     * chunking. Because it is a content address like `hash`, the manifest is fetched
+     * and integrity-verified over the same channel as the chunks.
+     */
+    manifestHash?: string;
+}
 /**
  * Comprehensive sync diagnostics snapshot.
  * Provides connection, latency, throughput, queue, and error metrics
@@ -398,7 +486,7 @@ type FieldKind = 'string' | 'number' | 'boolean' | 'timestamp' | 'richtext' | 'e
  */
 interface SyncDiagnosticsSnapshot {
     /** Current developer-facing sync status */
-    status: 'connected' | 'syncing' | 'synced' | 'offline' | 'error' | 'schema-mismatch' | 'clock-error';
+    status: 'connected' | 'reconnecting' | 'syncing' | 'synced' | 'offline' | 'error' | 'schema-mismatch' | 'clock-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 */
@@ -490,6 +578,17 @@ interface FieldDescriptor {
     mergeStrategy: FieldMergeStrategy | null;
     /** State machine transition map for enum fields. Null if no transitions declared. */
     transitions: TransitionMap | null;
+    /**
+     * Nested field descriptors for `object` fields (each key merges by its own
+     * kind). Null for `json` fields (dynamic keys, resolved structurally) and for
+     * all non-structured kinds.
+     */
+    nestedFields?: Record<string, FieldDescriptor> | null;
+    /**
+     * At-rest protection mode for `secret` fields (`hashed` or `encrypted`).
+     * Null/absent for every other kind.
+     */
+    secretMode?: SecretMode | null;
 }
 /**
  * Defines a state machine on an enum field, constraining valid state transitions.
@@ -727,6 +826,33 @@ type KoraEvent = {
     code: string;
     message: string;
     retriable: boolean;
+} | {
+    /**
+     * The server rejected one of THIS client's outbound operations before it
+     * became authoritative. The op has been diverted out of the pending sync
+     * queue into the durable rejected store (kept, not retried); the app can
+     * surface the reason and decide whether to roll back the optimistic local
+     * write or let the user edit and resubmit.
+     */
+    type: 'sync:operation-rejected';
+    operationId: string;
+    collection: string;
+    recordId: string;
+    code: string;
+    message: string;
+    retriable: boolean;
+} | {
+    type: 'sync:delivery-gap';
+    expectedBase: number;
+    receivedBase: number;
+    currentWatermark: number;
+    messageId: string;
+    repeatCount: number;
+} | {
+    type: 'sync:delivery-stalled';
+    sessionId: string;
+    watermark: number;
+    repeatCount: number;
 } | {
     type: 'query:subscribed';
     queryId: string;
@@ -781,6 +907,46 @@ type KoraEvent = {
     type: 'store:quota-exceeded';
     dbName: string;
     message: string;
+} | {
+    /**
+     * OPFS persistence was unavailable, so the store fell back to a
+     * NON-PERSISTENT in-memory database. Anything written this session is lost
+     * on reload. This is emitted instead of failing silently so the condition
+     * is observable rather than a data-loss trap.
+     */
+    type: 'store:opfs-unavailable';
+    dbName: string;
+    /**
+     * Why OPFS could not be used. `lock-conflict` means another runtime on this
+     * origin already holds the OPFS pool for this database; `timeout` means the
+     * VFS install did not complete in time (common in headless CI); `unsupported`
+     * means the runtime has no usable OPFS.
+     */
+    reason: 'lock-conflict' | 'timeout' | 'unsupported';
+    message: string;
+} | {
+    /**
+     * A preferred storage backend could not provide durable storage, so Kora
+     * promoted the app to another durable backend before user code observed the
+     * store. This is informational: data still survives reloads.
+     */
+    type: 'store:storage-fallback';
+    dbName: string;
+    from: 'opfs' | 'sqlite-wasm';
+    to: 'indexeddb';
+    reason: 'lock-conflict' | 'timeout' | 'unsupported';
+    message: string;
+} | {
+    /**
+     * Another runtime on this origin was already using this database name, so
+     * this runtime attached to it as a follower and now SHARES that one
+     * database. That is intended for multiple tabs of the SAME app; it is a bug
+     * if these are logically separate apps, which should each use a distinct
+     * store name (`store: { name: '...' }`) to stay isolated.
+     */
+    type: 'store:db-name-collision';
+    dbName: string;
+    message: string;
 } | {
     type: 'replay:completed';
     targetOperationId: string;
@@ -805,4 +971,4 @@ interface KoraEventEmitter {
     emit<T extends KoraEventType>(event: KoraEventByType<T>): void;
 }
 
-export { type AtomicOpType as A, type SequenceConfig as B, type CustomResolver as C, type StateMachineDefinition as D, EnumFieldBuilder as E, FieldBuilder as F, type SyncDiagnosticsSnapshot as G, type HLCTimestamp as H, type SyncRuleDefinition as I, type TimeSource as J, type KoraEvent as K, migrate as L, type MigrationDefinition as M, t as N, type OperationType as O, type RandomSource as R, type SchemaDefinition as S, type TransitionMap as T, type VersionVector as V, type AtomicOp as a, type CollectionDefinition as b, type RelationDefinition as c, ArrayFieldBuilder as d, type FieldKind as e, type Operation as f, type MigrationStep as g, type StateMachineConstraint as h, type TransitionValidationResult as i, CONNECTION_QUALITIES as j, type ConnectionQuality as k, type Constraint as l, type FieldDescriptor as m, type FieldMergeStrategy as n, type KoraEventByType as o, type KoraEventEmitter as p, type KoraEventListener as q, type KoraEventType as r, MERGE_STRATEGIES as s, type MergeStrategy as t, type MergeTrace as u, MigrationBuilder as v, type OnDeleteAction as w, type OperationInput as x, type RelationType as y, RollbackBuilder as z };
+export { type AtomicOpType as A, type BlobRef as B, type CollectionDefinition as C, type SecretMode as D, EnumFieldBuilder as E, FieldBuilder as F, type SequenceConfig as G, type HLCTimestamp as H, type StateMachineDefinition as I, JsonFieldBuilder as J, type KoraEvent as K, type SyncDiagnosticsSnapshot as L, type MigrationDefinition as M, type SyncRuleDefinition as N, type OperationType as O, type TimeSource as P, migrate as Q, type RandomSource as R, type SchemaDefinition as S, type TransitionMap as T, t as U, type VersionVector as V, type AtomicOp as a, type CustomResolver as b, type RelationDefinition as c, ArrayFieldBuilder as d, type FieldKind as e, type Operation as f, type MigrationStep as g, type StateMachineConstraint as h, type TransitionValidationResult as i, CONNECTION_QUALITIES as j, type ConnectionQuality as k, type Constraint as l, type FieldDescriptor as m, type FieldMergeStrategy as n, type KoraEventByType as o, type KoraEventEmitter as p, type KoraEventListener as q, type KoraEventType as r, MERGE_STRATEGIES as s, type MergeStrategy as t, type MergeTrace as u, MigrationBuilder as v, type OnDeleteAction as w, type OperationInput as x, type RelationType as y, RollbackBuilder as z };

package/dist/{events-BynBOsO3.d.ts → events-3z0Tema3.d.ts}

@@ -89,6 +89,56 @@ declare class ArrayFieldBuilder<ItemKind extends FieldKind = FieldKind, Req exte
     merge(strategy: FieldMergeStrategy): ArrayFieldBuilder<ItemKind, Req, Auto>;
     _build(): FieldDescriptor;
 }
+/**
+ * Field builder for structured object fields with a nested field schema.
+ *
+ * Each nested key merges by its own declared kind (scalars via LWW, nested
+ * arrays via add-wins, nested objects recursively), so two devices editing
+ * different keys of the same object offline both converge on reconnect instead
+ * of one clobbering the other.
+ */
+declare class ObjectFieldBuilder<Req extends boolean = true, Auto extends boolean = false> extends FieldBuilder<'object', Req, Auto> {
+    private readonly _fields;
+    constructor(fields: Record<string, FieldBuilder>, required?: Req, defaultValue?: unknown, auto?: Auto, mergeStrategy?: FieldMergeStrategy | null);
+    optional(): ObjectFieldBuilder<false, Auto>;
+    default(value: Record<string, unknown>): ObjectFieldBuilder<false, Auto>;
+    auto(): ObjectFieldBuilder<false, true>;
+    merge(strategy: FieldMergeStrategy): ObjectFieldBuilder<Req, Auto>;
+    _build(): FieldDescriptor;
+}
+/**
+ * Field builder for dynamic-key JSON values. Carries a compile-time shape `T`
+ * for inference while merging structurally as a convergent CRDT: a plain-object
+ * value recurses as a map, an array merges add-wins, any other value is a scalar
+ * leaf under last-write-wins.
+ */
+declare class JsonFieldBuilder<T = unknown, Req extends boolean = true, Auto extends boolean = false> extends FieldBuilder<'json', Req, Auto> {
+    optional(): JsonFieldBuilder<T, false, Auto>;
+    default(value: T): JsonFieldBuilder<T, false, Auto>;
+    auto(): JsonFieldBuilder<T, false, true>;
+    merge(strategy: FieldMergeStrategy): JsonFieldBuilder<T, Req, Auto>;
+    _build(): FieldDescriptor;
+}
+/**
+ * Field builder for secret fields (passwords, tokens, API keys).
+ *
+ * A secret field's value is never exposed in merge traces, DevTools, or logs
+ * (it is redacted at the point traces are built). Its at-rest protection is
+ * chosen with `.hashed()` (one-way, for passwords) or `.encrypted()` (reversible,
+ * for tokens); the default is `encrypted`.
+ */
+declare class SecretFieldBuilder<Req extends boolean = true, Auto extends boolean = false> extends FieldBuilder<'secret', Req, Auto> {
+    private readonly _secretMode;
+    constructor(secretMode?: SecretMode, required?: Req, defaultValue?: unknown, auto?: Auto, mergeStrategy?: FieldMergeStrategy | null);
+    /** Store this secret as a one-way salted hash (passwords: verify, never read back). */
+    hashed(): SecretFieldBuilder<Req, Auto>;
+    /** Store this secret as reversible ciphertext (tokens/keys: decrypt to use). */
+    encrypted(): SecretFieldBuilder<Req, Auto>;
+    optional(): SecretFieldBuilder<false, Auto>;
+    auto(): SecretFieldBuilder<false, true>;
+    merge(strategy: FieldMergeStrategy): SecretFieldBuilder<Req, Auto>;
+    _build(): FieldDescriptor;
+}
 /**
  * Type builder namespace. The developer's primary interface for defining field types.
  *
@@ -103,6 +153,8 @@ declare class ArrayFieldBuilder<ItemKind extends FieldKind = FieldKind, Req exte
  *   notes: t.richtext(),
  *   tags: t.array(t.string()).default([]),
  *   priority: t.enum(['low', 'medium', 'high']).default('medium'),
+ *   settings: t.object({ theme: t.string(), fontSize: t.number() }),
+ *   metadata: t.json<{ source: string }>(),
  *   createdAt: t.timestamp().auto(),
  * }
  * ```
@@ -115,6 +167,10 @@ declare const t: {
     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>;
+    object(fields: Record<string, FieldBuilder>): ObjectFieldBuilder<true, false>;
+    json<T = unknown>(): JsonFieldBuilder<T, true, false>;
+    blob(): FieldBuilder<"blob", true, false>;
+    secret(): SecretFieldBuilder<true, false>;
 };
 
 /**
@@ -390,7 +446,39 @@ interface OperationInput {
 /** 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';
+type FieldKind = 'string' | 'number' | 'boolean' | 'timestamp' | 'richtext' | 'enum' | 'array' | 'object' | 'json' | 'blob' | 'secret';
+/**
+ * How a `secret` field's value is protected at rest.
+ * - `hashed`: one-way (passwords). Stored as a salted hash; never read back.
+ * - `encrypted`: reversible (tokens, keys). Stored as ciphertext; decrypted to use.
+ */
+type SecretMode = 'hashed' | 'encrypted';
+/**
+ * A content-addressed reference to binary data stored out of band.
+ *
+ * A `blob` field never carries the bytes in the operation log; it carries this
+ * small reference. The bytes live in a content-addressed blob store, keyed by
+ * `hash`, so identical content is stored once and never re-synced to a peer that
+ * already has that hash.
+ */
+interface BlobRef {
+    /** Hex-encoded SHA-256 hash of the bytes. The content address. */
+    hash: string;
+    /** Size of the bytes in bytes. */
+    size: number;
+    /** Optional MIME type (for example "image/png"). */
+    mimeType?: string;
+    /** Optional original filename. */
+    filename?: string;
+    /**
+     * Hex-encoded SHA-256 hash of this blob's manifest — the small chunk index a
+     * peer fetches first to learn how to pull the bytes out of band. Present when
+     * the blob was stored for transfer; absent for a bare reference created without
+     * chunking. Because it is a content address like `hash`, the manifest is fetched
+     * and integrity-verified over the same channel as the chunks.
+     */
+    manifestHash?: string;
+}
 /**
  * Comprehensive sync diagnostics snapshot.
  * Provides connection, latency, throughput, queue, and error metrics
@@ -398,7 +486,7 @@ type FieldKind = 'string' | 'number' | 'boolean' | 'timestamp' | 'richtext' | 'e
  */
 interface SyncDiagnosticsSnapshot {
     /** Current developer-facing sync status */
-    status: 'connected' | 'syncing' | 'synced' | 'offline' | 'error' | 'schema-mismatch' | 'clock-error';
+    status: 'connected' | 'reconnecting' | 'syncing' | 'synced' | 'offline' | 'error' | 'schema-mismatch' | 'clock-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 */
@@ -490,6 +578,17 @@ interface FieldDescriptor {
     mergeStrategy: FieldMergeStrategy | null;
     /** State machine transition map for enum fields. Null if no transitions declared. */
     transitions: TransitionMap | null;
+    /**
+     * Nested field descriptors for `object` fields (each key merges by its own
+     * kind). Null for `json` fields (dynamic keys, resolved structurally) and for
+     * all non-structured kinds.
+     */
+    nestedFields?: Record<string, FieldDescriptor> | null;
+    /**
+     * At-rest protection mode for `secret` fields (`hashed` or `encrypted`).
+     * Null/absent for every other kind.
+     */
+    secretMode?: SecretMode | null;
 }
 /**
  * Defines a state machine on an enum field, constraining valid state transitions.
@@ -727,6 +826,33 @@ type KoraEvent = {
     code: string;
     message: string;
     retriable: boolean;
+} | {
+    /**
+     * The server rejected one of THIS client's outbound operations before it
+     * became authoritative. The op has been diverted out of the pending sync
+     * queue into the durable rejected store (kept, not retried); the app can
+     * surface the reason and decide whether to roll back the optimistic local
+     * write or let the user edit and resubmit.
+     */
+    type: 'sync:operation-rejected';
+    operationId: string;
+    collection: string;
+    recordId: string;
+    code: string;
+    message: string;
+    retriable: boolean;
+} | {
+    type: 'sync:delivery-gap';
+    expectedBase: number;
+    receivedBase: number;
+    currentWatermark: number;
+    messageId: string;
+    repeatCount: number;
+} | {
+    type: 'sync:delivery-stalled';
+    sessionId: string;
+    watermark: number;
+    repeatCount: number;
 } | {
     type: 'query:subscribed';
     queryId: string;
@@ -781,6 +907,46 @@ type KoraEvent = {
     type: 'store:quota-exceeded';
     dbName: string;
     message: string;
+} | {
+    /**
+     * OPFS persistence was unavailable, so the store fell back to a
+     * NON-PERSISTENT in-memory database. Anything written this session is lost
+     * on reload. This is emitted instead of failing silently so the condition
+     * is observable rather than a data-loss trap.
+     */
+    type: 'store:opfs-unavailable';
+    dbName: string;
+    /**
+     * Why OPFS could not be used. `lock-conflict` means another runtime on this
+     * origin already holds the OPFS pool for this database; `timeout` means the
+     * VFS install did not complete in time (common in headless CI); `unsupported`
+     * means the runtime has no usable OPFS.
+     */
+    reason: 'lock-conflict' | 'timeout' | 'unsupported';
+    message: string;
+} | {
+    /**
+     * A preferred storage backend could not provide durable storage, so Kora
+     * promoted the app to another durable backend before user code observed the
+     * store. This is informational: data still survives reloads.
+     */
+    type: 'store:storage-fallback';
+    dbName: string;
+    from: 'opfs' | 'sqlite-wasm';
+    to: 'indexeddb';
+    reason: 'lock-conflict' | 'timeout' | 'unsupported';
+    message: string;
+} | {
+    /**
+     * Another runtime on this origin was already using this database name, so
+     * this runtime attached to it as a follower and now SHARES that one
+     * database. That is intended for multiple tabs of the SAME app; it is a bug
+     * if these are logically separate apps, which should each use a distinct
+     * store name (`store: { name: '...' }`) to stay isolated.
+     */
+    type: 'store:db-name-collision';
+    dbName: string;
+    message: string;
 } | {
     type: 'replay:completed';
     targetOperationId: string;
@@ -805,4 +971,4 @@ interface KoraEventEmitter {
     emit<T extends KoraEventType>(event: KoraEventByType<T>): void;
 }
 
-export { type AtomicOpType as A, type SequenceConfig as B, type CustomResolver as C, type StateMachineDefinition as D, EnumFieldBuilder as E, FieldBuilder as F, type SyncDiagnosticsSnapshot as G, type HLCTimestamp as H, type SyncRuleDefinition as I, type TimeSource as J, type KoraEvent as K, migrate as L, type MigrationDefinition as M, t as N, type OperationType as O, type RandomSource as R, type SchemaDefinition as S, type TransitionMap as T, type VersionVector as V, type AtomicOp as a, type CollectionDefinition as b, type RelationDefinition as c, ArrayFieldBuilder as d, type FieldKind as e, type Operation as f, type MigrationStep as g, type StateMachineConstraint as h, type TransitionValidationResult as i, CONNECTION_QUALITIES as j, type ConnectionQuality as k, type Constraint as l, type FieldDescriptor as m, type FieldMergeStrategy as n, type KoraEventByType as o, type KoraEventEmitter as p, type KoraEventListener as q, type KoraEventType as r, MERGE_STRATEGIES as s, type MergeStrategy as t, type MergeTrace as u, MigrationBuilder as v, type OnDeleteAction as w, type OperationInput as x, type RelationType as y, RollbackBuilder as z };
+export { type AtomicOpType as A, type BlobRef as B, type CollectionDefinition as C, type SecretMode as D, EnumFieldBuilder as E, FieldBuilder as F, type SequenceConfig as G, type HLCTimestamp as H, type StateMachineDefinition as I, JsonFieldBuilder as J, type KoraEvent as K, type SyncDiagnosticsSnapshot as L, type MigrationDefinition as M, type SyncRuleDefinition as N, type OperationType as O, type TimeSource as P, migrate as Q, type RandomSource as R, type SchemaDefinition as S, type TransitionMap as T, t as U, type VersionVector as V, type AtomicOp as a, type CustomResolver as b, type RelationDefinition as c, ArrayFieldBuilder as d, type FieldKind as e, type Operation as f, type MigrationStep as g, type StateMachineConstraint as h, type TransitionValidationResult as i, CONNECTION_QUALITIES as j, type ConnectionQuality as k, type Constraint as l, type FieldDescriptor as m, type FieldMergeStrategy as n, type KoraEventByType as o, type KoraEventEmitter as p, type KoraEventListener as q, type KoraEventType as r, MERGE_STRATEGIES as s, type MergeStrategy as t, type MergeTrace as u, MigrationBuilder as v, type OnDeleteAction as w, type OperationInput as x, type RelationType as y, RollbackBuilder as z };