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

package/dist/index.d.cts

@@ -1,10 +1,298 @@
-import { SchemaDefinition, KoraEventEmitter, Operation, VersionVector } from '@korajs/core';
+import { Operation, HybridLogicalClock, SchemaDefinition, BlobRef, KoraEventEmitter, OperationTransform, VersionVector, TimeSource } from '@korajs/core';
 import * as _korajs_sync from '@korajs/sync';
-import { SyncStore, MessageSerializer, SyncMessage, AwarenessUpdateMessage, YjsDocUpdateMessage, ApplyResult } from '@korajs/sync';
+import { SyncStore, ApplyResult, MessageSerializer, SyncMessage, AwarenessUpdateMessage, YjsDocUpdateMessage, BlobChunkRequestMessage, BlobChunkResponseMessage } from '@korajs/sync';
 import { S as ServerTransport, a as ServerMessageHandler, b as ServerCloseHandler, c as ServerErrorHandler } from './server-transport-CU1BLWgr.cjs';
 import { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
 import { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3';
 
+/**
+ * Predicate evaluation for conditional route mutations.
+ *
+ * A predicate is a small, total comparison language evaluated against the current
+ * materialized state of a single record at admission time. It is deliberately not
+ * a general query language: it exists so a server route can express an atomic
+ * admission guard (for example "accept this response only while the form is still
+ * below its cap") without pulling a query DSL into the write path.
+ */
+/**
+ * Comparison operators applied to one field. All operators present on a field
+ * must hold for the field to match. Numeric operators (`$lt`, `$lte`, `$gt`,
+ * `$gte`) require the record value to be a number; a non-numeric value fails.
+ */
+interface RoutePredicateOperators {
+    $eq?: unknown;
+    $ne?: unknown;
+    $lt?: number;
+    $lte?: number;
+    $gt?: number;
+    $gte?: number;
+    $in?: readonly unknown[];
+}
+/** A predicate: every listed field must satisfy all of its operators. */
+type RoutePredicate = Record<string, RoutePredicateOperators>;
+
+/**
+ * Per-collection scope map from auth context.
+ */
+type ScopeMap = Record<string, Record<string, unknown>>;
+
+/**
+ * A materialized record reconstructed from the operation log
+ * or read from a materialized collection table.
+ */
+interface MaterializedRecord {
+    id: string;
+    [key: string]: unknown;
+}
+/**
+ * A conditional, atomic multi-operation apply. The store reads the target under a
+ * cross-instance lock, lets the caller decide admission and build the operations
+ * against that locked state, and applies them in one transaction, or applies
+ * nothing. `admit` and `buildOperations` run inside the locked transaction so the
+ * predicate check and any atomic-op resolution see the authoritative current value
+ * even when multiple server instances race on the same target.
+ */
+interface ConditionalApplyInput {
+    /** Record the admission lock and predicate are keyed on. */
+    target: {
+        collection: string;
+        id: string;
+    };
+    /** Decides admission against the target's locked current state. */
+    admit: (current: MaterializedRecord | null) => boolean;
+    /**
+     * Builds the operations to apply, given the locked current state and a clock the
+     * store has already advanced past the target record's latest committed operation.
+     * Stamping the built operations with this clock guarantees they sort strictly
+     * after every prior write to the target, so last-write-wins materialization
+     * reflects the serialized commit order even when two instances commit in the same
+     * millisecond. Without it, a same-millisecond tie could let materialization pick
+     * an earlier resolved value and undercount an atomic counter, admitting past a cap.
+     */
+    buildOperations: (current: MaterializedRecord | null, context: ConditionalApplyContext) => Promise<Operation[]>;
+    /**
+     * When set, a record whose prior existence proves this set already committed.
+     * Checked under the same lock as admission, so a retry is idempotent even across
+     * instances: it returns `idempotent: true` without re-running the operations.
+     */
+    idempotencyKey?: {
+        collection: string;
+        id: string;
+    };
+}
+/** Context passed to {@link ConditionalApplyInput.buildOperations}. */
+interface ConditionalApplyContext {
+    /**
+     * A clock the store has advanced past the target record's latest committed
+     * operation. Operations built here must be stamped with it (route context threads
+     * it into operation creation) so they sort strictly after every prior write.
+     */
+    clock: HybridLogicalClock;
+}
+/** Result of {@link ServerStore.applyConditional}. */
+interface ConditionalApplyResult {
+    /** True when the predicate held (or the set was already committed). */
+    admitted: boolean;
+    /** True when the idempotency key already existed and nothing was re-applied. */
+    idempotent: boolean;
+    /** The operations that were applied (empty when not admitted or idempotent). */
+    applied: Operation[];
+}
+/**
+ * A stored operation paired with its server-assigned delivery sequence. The
+ * delivery sequence is monotonic in commit order, so a batch of these can be
+ * chained (each batch's base links to the previous batch's max) to give the
+ * client a gap-free, scope-agnostic recovery stream.
+ */
+interface DeliveredOperation {
+    operation: Operation;
+    deliverySequence: number;
+}
+/**
+ * Options for querying a materialized collection table.
+ */
+interface CollectionQueryOptions {
+    /** Exact-match filters on field values */
+    where?: Record<string, unknown>;
+    /** Field name to order results by */
+    orderBy?: string;
+    /** Sort direction (default: 'asc') */
+    orderDirection?: 'asc' | 'desc';
+    /** Maximum number of records to return */
+    limit?: number;
+    /** Number of records to skip (for pagination) */
+    offset?: number;
+    /** Include soft-deleted records (default: false) */
+    includeDeleted?: boolean;
+}
+/**
+ * Server-side store interface. Extends SyncStore with lifecycle,
+ * introspection, and materialization methods needed by the sync server.
+ */
+interface ServerStore extends SyncStore {
+    /** Close the store and release resources */
+    close(): Promise<void>;
+    /** Get the total number of stored operations */
+    getOperationCount(): Promise<number>;
+    /**
+     * The highest delivery sequence currently visible in the store (0 when empty).
+     * Used to initialize a fresh client's watermark baseline and for diagnostics.
+     */
+    getMaxDeliverySequence(): Promise<number>;
+    /**
+     * Operations with `deliverySequence > afterDeliverySequence`, ordered ascending
+     * by delivery sequence, at most `limit` of them. This is the substrate for the
+     * gap-free server->client stream: the caller (a client session) applies its own
+     * scope filter and chains the results into batches, advancing the client's
+     * durable watermark as batches are acknowledged. Because delivery sequence is
+     * assigned in commit order, a lower sequence is always visible before any higher
+     * one, so this scan can never skip an operation that later appears below the
+     * cursor.
+     */
+    getOperationsAfterDelivery(afterDeliverySequence: number, limit: number): Promise<DeliveredOperation[]>;
+    /**
+     * Conditionally apply a set of operations atomically, serialized across server
+     * instances on the target record. Optional: stores that can only run in a single
+     * process (or do not back a shared database) may omit it, and callers fall back
+     * to per-instance serialization. The Postgres store implements it with a
+     * transaction-scoped advisory lock so concurrent admissions cannot both pass a
+     * cap check (`applyConditional` returns `admitted: false` for the loser).
+     */
+    applyConditional?(input: ConditionalApplyInput): Promise<ConditionalApplyResult>;
+    /**
+     * Atomically reserve the next sequence number for a server-originated operation
+     * on this store's own node. Stores that serve conditional applies concurrently
+     * (the Postgres store, which does not serialize behind a single mutation tail)
+     * must implement this so two in-flight server operations cannot be handed the
+     * same sequence number, which would let one shadow the other during version-vector
+     * delta sync. Stores whose server writes are fully serialized may omit it, and
+     * callers fall back to reading the version vector.
+     */
+    reserveSequenceNumber?(): number;
+    /**
+     * Set the schema for materialized collection tables.
+     * Creates collection tables and indexes based on the schema definition.
+     * If operations already exist in the store, backfills the materialized
+     * tables from the operation log.
+     *
+     * @param schema - The schema definition describing all collections
+     */
+    setSchema(schema: SchemaDefinition): Promise<void>;
+    /** Schema used for materialized tables and server-side validation, if set. */
+    getSchema(): SchemaDefinition | null;
+    /**
+     * Get all records from a materialized collection.
+     * When schema is set, reads directly from the collection table (O(1) indexed).
+     * When schema is not set, falls back to replaying the operation log.
+     * Deleted records are excluded.
+     *
+     * @param collection - The collection name to query
+     * @returns Array of records with their current state
+     */
+    materializeCollection(collection: string): Promise<MaterializedRecord[]>;
+    /**
+     * Query records from a materialized collection with filtering, ordering,
+     * and pagination. Requires schema to be set via setSchema().
+     *
+     * @param collection - The collection name to query
+     * @param options - Query options (where, orderBy, limit, offset)
+     * @returns Array of matching records
+     */
+    queryCollection(collection: string, options?: CollectionQueryOptions): Promise<MaterializedRecord[]>;
+    /**
+     * Find a single record by ID from a materialized collection.
+     * Requires schema to be set via setSchema().
+     *
+     * @param collection - The collection name
+     * @param id - The record ID
+     * @returns The record or null if not found (or deleted)
+     */
+    findRecord(collection: string, id: string): Promise<MaterializedRecord | null>;
+    /**
+     * Count records in a materialized collection, optionally filtered.
+     * Requires schema to be set via setSchema().
+     *
+     * @param collection - The collection name
+     * @param where - Optional exact-match filters
+     * @returns Number of matching records
+     */
+    countCollection(collection: string, where?: Record<string, unknown>): Promise<number>;
+    /**
+     * Export all data as a portable backup binary.
+     * Ships operations, version vector, and metadata in a self-describing format
+     * with SHA-256 checksum.
+     */
+    exportBackup(): Promise<Uint8Array>;
+    /**
+     * Restore data from a portable backup binary.
+     * Operations are applied through applyRemoteOperation for safe merge.
+     *
+     * @param data - Backup binary
+     * @param merge - If true, merge with existing operations; if false, replace all
+     */
+    importBackup(data: Uint8Array, merge?: boolean): Promise<{
+        operationsRestored: number;
+        success: boolean;
+    }>;
+}
+
+/**
+ * Shared vocabulary for why the server refused an operation.
+ *
+ * The `retriable` flag answers one question for the caller: is it worth
+ * submitting this SAME operation again later?
+ *
+ *  - `true`  — the rejection is transient (for example a rate limit). The
+ *              identical operation may succeed once the condition clears, so a
+ *              client is right to back off and retry the same bytes.
+ *  - `false` — the rejection is permanent for the operation as written (a
+ *              constraint violation, a referential conflict, a malformed
+ *              mutation, a scope violation). Resubmitting the same bytes will
+ *              always fail; the caller must change the operation or give up.
+ *
+ * This is deliberately defined once, in one place, so the trusted server
+ * data-plane (route context / `server.kora`) and the untrusted client-ingestion
+ * path speak the same language. `retriable` (this spelling) matches the wire
+ * `ErrorMessage.retriable` field the sync protocol already ships, so a single
+ * flag flows from the pipeline out to connected clients unchanged.
+ */
+interface OperationRejection {
+    /** Stable, machine-readable reason code (for example `CONSTRAINT_VIOLATION`). */
+    code: string;
+    /** Human-readable explanation with enough context to debug without reproduction. */
+    message: string;
+    /** Whether resubmitting the identical operation may later succeed. */
+    retriable: boolean;
+}
+/**
+ * Reason codes whose underlying condition is transient, so the identical
+ * operation may succeed on a later attempt.
+ *
+ * Everything NOT listed here is treated as permanent. Permanent is the safe
+ * default: a client should never be told to keep hammering a genuinely invalid
+ * operation, so a new code is non-retriable until it is deliberately added here.
+ *
+ * `RATE_LIMIT` is the code the session emits when a client exceeds its
+ * per-minute operation budget (see `client-session.ts`).
+ */
+declare const RETRIABLE_REJECTION_CODES: ReadonlySet<string>;
+/**
+ * Classify a reason code as retriable (transient) or not (permanent).
+ *
+ * @param code - A rejection reason code.
+ * @returns `true` when resubmitting the identical operation may later succeed.
+ */
+declare function isRetriableRejection(code: string): boolean;
+
+interface ApplyServerOperationResult {
+    /** Result of applying the primary operation */
+    result: ApplyResult;
+    /** Primary op when applied, plus any server-generated side-effect operations */
+    appliedOperations: Operation[];
+    /** Rejection reason when the operation was not applied */
+    rejection?: OperationRejection;
+}
+
 /**
  * Snapshot of server-side sync metrics at a point in time.
  */
@@ -125,105 +413,370 @@ declare function createSilentLogger(): Logger;
 declare function createDefaultLogger(): Logger;
 
 /**
- * A materialized record reconstructed from the operation log
- * or read from a materialized collection table.
+ * Minimal interface for a ws.WebSocketServer instance.
+ * Allows dependency injection for testing without importing ws directly.
  */
-interface MaterializedRecord {
-    id: string;
-    [key: string]: unknown;
+interface WsServerLike {
+    on(event: string, listener: (...args: unknown[]) => void): void;
+    close(callback?: (err?: Error) => void): void;
+    address(): {
+        port: number;
+    } | string | null;
 }
 /**
- * Options for querying a materialized collection table.
+ * Constructor type for creating a WebSocket server.
  */
-interface CollectionQueryOptions {
-    /** Exact-match filters on field values */
-    where?: Record<string, unknown>;
-    /** Field name to order results by */
-    orderBy?: string;
-    /** Sort direction (default: 'asc') */
-    orderDirection?: 'asc' | 'desc';
-    /** Maximum number of records to return */
-    limit?: number;
-    /** Number of records to skip (for pagination) */
-    offset?: number;
-    /** Include soft-deleted records (default: false) */
-    includeDeleted?: boolean;
-}
+type WsServerConstructor = new (options: {
+    port?: number;
+    host?: string;
+    path?: string;
+}) => WsServerLike;
 /**
- * Server-side store interface. Extends SyncStore with lifecycle,
- * introspection, and materialization methods needed by the sync server.
+ * Self-hosted sync server. Accepts WebSocket connections from clients,
+ * handles the sync protocol, stores operations, and relays changes
+ * between connected clients.
+ *
+ * Two modes of operation:
+ * 1. **Standalone**: Call `start()` with a port — creates its own WebSocket server.
+ * 2. **Attach**: Call `handleConnection(transport)` — attach to an existing HTTP server.
  */
-interface ServerStore extends SyncStore {
-    /** Close the store and release resources */
-    close(): Promise<void>;
-    /** Get the total number of stored operations */
-    getOperationCount(): Promise<number>;
+declare class KoraSyncServer {
+    private readonly store;
+    private readonly auth;
+    private readonly serializer;
+    private readonly emitter;
+    private readonly maxConnections;
+    private readonly batchSize;
+    private readonly relayRetransmitIntervalMs;
+    private readonly deliveryPollIntervalMs;
+    private readonly schemaVersion;
+    private readonly supportedSchemaVersions;
+    private readonly operationTransforms;
+    private readonly port;
+    private readonly host;
+    private readonly path;
+    private readonly logger;
+    private readonly metrics;
+    private readonly awarenessRelay;
+    private readonly yjsDocRelay;
+    private readonly blobChunkRelay;
+    private readonly persistBlobChunk;
+    private readonly maxOperationBytes;
+    private readonly maxOpsPerMinute;
+    private readonly validateOperation;
+    private readonly koraContext;
+    private readonly sessions;
+    private readonly httpClients;
+    private readonly httpSessionToClient;
+    private readonly serverVersion;
+    private wsServer;
+    private running;
     /**
-     * Set the schema for materialized collection tables.
-     * Creates collection tables and indexes based on the schema definition.
-     * If operations already exist in the store, backfills the materialized
-     * tables from the operation log.
+     * Periodic tick that retransmits relay batches connected clients have not
+     * acknowledged, so a relay dropped by a lossy transport is redelivered instead of
+     * leaving that client with a permanent version-vector gap (a lost operation).
+     */
+    private relayRetransmitTimer;
+    private deliveryPollTimer;
+    private lastObservedDeliverySequence;
+    private deliveryPollInFlight;
+    /**
+     * Relay operations a client never acknowledged before it disconnected, buffered by
+     * client node id so they can be redelivered on its next connection. Bounded per
+     * node and expired by age so a client that never returns cannot grow this forever.
+     */
+    private readonly orphanedRelaysByNode;
+    private static readonly MAX_ORPHANED_RELAY_OPS_PER_NODE;
+    private static readonly ORPHANED_RELAY_TTL_MS;
+    constructor(config: KoraSyncServerConfig);
+    private ensureBackgroundTimersStarted;
+    /**
+     * Retransmit relay batches that connected clients have not acknowledged within
+     * `staleMs`. Called on a periodic tick and directly by tests. Redelivering an
+     * already-applied operation is harmless (clients dedup by content-addressed id).
+     */
+    retransmitPendingRelays(staleMs?: number): void;
+    /**
+     * Check whether the authoritative delivery log advanced without passing through
+     * this server instance, then wake delivery-watermark sessions to scan from their
+     * own acknowledged cursors. Session-level filtering remains the only fan-out path.
+     */
+    pollDeliveryLog(): Promise<void>;
+    /**
+     * Buffer relay operations a disconnected client never acknowledged, keyed by its
+     * node id, deduped by operation id and bounded by count. Redelivered when the
+     * client reconnects (see {@link takeOrphanedRelays}).
+     */
+    private bufferOrphanedRelays;
+    /** Remove and return a node's buffered orphaned relay operations, if any. */
+    private takeOrphanedRelays;
+    /** Drop buffered orphaned relays older than the TTL (client never returned). */
+    private expireOrphanedRelays;
+    /**
+     * The trusted, scoped data-plane context (`apply` / `query` / `findById`).
+     * Shared with the production server so HTTP routes, the operation validator,
+     * and `server.kora` are all the same object over the same pipeline.
+     */
+    getKoraContext(): ProductionHttpRouteContext;
+    /**
+     * Subscribe to session-level events for metrics collection and logging.
+     * Called when a new session is created.
+     */
+    private attachSessionEvents;
+    /**
+     * Get the metrics collector for external access (e.g., HTTP endpoints).
+     */
+    getMetricsCollector(): ServerMetricsCollector;
+    /**
+     * Get the logger for external access (e.g., event streaming).
+     */
+    getLogger(): Logger;
+    /**
+     * Start the WebSocket server in standalone mode.
      *
-     * @param schema - The schema definition describing all collections
+     * @param wsServerImpl - Optional WebSocket server constructor for testing
      */
-    setSchema(schema: SchemaDefinition): Promise<void>;
-    /** Schema used for materialized tables and server-side validation, if set. */
-    getSchema(): SchemaDefinition | null;
+    start(wsServerImpl?: WsServerConstructor): Promise<void>;
     /**
-     * Get all records from a materialized collection.
-     * When schema is set, reads directly from the collection table (O(1) indexed).
-     * When schema is not set, falls back to replaying the operation log.
-     * Deleted records are excluded.
+     * Stop the server. Closes all sessions and the WebSocket server.
+     */
+    stop(): Promise<void>;
+    /**
+     * Handle one HTTP sync request for a long-polling client.
      *
-     * @param collection - The collection name to query
-     * @returns Array of records with their current state
+     * A stable `clientId` identifies the logical connection across requests.
      */
-    materializeCollection(collection: string): Promise<MaterializedRecord[]>;
+    handleHttpRequest(request: HttpSyncRequest): Promise<HttpSyncResponse>;
+    /**
+     * Handle an incoming client connection (attach mode).
+     * Creates a new ClientSession for the transport.
+     *
+     * @param transport - The server transport for the new connection
+     * @returns The session ID
+     */
+    handleConnection(transport: ServerTransport): string;
+    /**
+     * Get the current server status.
+     */
+    getStatus(): Promise<ServerStatus>;
+    /**
+     * Apply a server-originated operation (for example one created by a custom
+     * HTTP route) through the same validated pipeline that incoming client
+     * operations use — Tier 2 constraints, referential integrity, and cascade
+     * side effects — then relay every applied operation to connected clients.
+     *
+     * Because the operation did not come from a client session, it is relayed to
+     * ALL sessions (there is no source session to exclude). Each session still
+     * applies its own per-scope visibility filter in `relayOperations`, so a
+     * client only receives the operation if it falls within that client's scope.
+     *
+     * @param op - A fully-formed, server-originated operation to apply
+     * @returns The apply result, including any server-generated side-effect ops
+     */
+    applyLocalOperation(op: Operation): Promise<ApplyServerOperationResult>;
+    /**
+     * Relay already-applied, server-originated operations to every connected client.
+     * Used by the conditional route apply, which commits its operations atomically
+     * through the store (bypassing {@link applyLocalOperation}) and then fans them
+     * out. Each session still enforces its own per-scope visibility filter.
+     *
+     * @param operations - Operations that have already been committed to the store
+     */
+    relayServerOperations(operations: Operation[]): void;
+    /**
+     * Collect every blob reference still reachable from live records on the server.
+     *
+     * This is the live set for garbage-collecting the server's central blob store:
+     * pass the result to `collectBlobGarbage(blobStore, liveRefs)` from
+     * `@korajs/store` to reclaim bytes no record references any more. Only
+     * collections that declare a `blob` field are scanned.
+     *
+     * @returns Every live blob reference across all collections
+     */
+    getLiveBlobRefs(): Promise<BlobRef[]>;
+    /**
+     * Get the number of currently connected clients.
+     */
+    getConnectionCount(): number;
+    private handleRelay;
+    private handleSessionClose;
+    private handleAwarenessRelay;
+    private handleYjsDocRelay;
+    private getOrCreateHttpClient;
+}
+
+/**
+ * A mutation a custom HTTP route asks the server to apply on the data plane.
+ *
+ * `recordId` is optional for inserts (a UUID v7 is generated when omitted) and
+ * required for updates and deletes. For updates, `data` holds only the changed
+ * fields; the server reads the current record to capture the previous values so
+ * the change three-way merges correctly with concurrent client edits.
+ */
+interface RouteMutation {
+    collection: string;
+    type: 'insert' | 'update' | 'delete';
+    recordId?: string;
+    data?: Record<string, unknown> | null;
+}
+/**
+ * Scope the route derived from the request's authenticated actor. When present,
+ * it is enforced exactly like a sync session's scope: `apply()` rejects a
+ * mutation whose resulting record falls outside the scope, and `query()` /
+ * `findById()` only return records inside it. Omit it for genuinely public
+ * routes (for example a signup endpoint) where no per-actor isolation applies.
+ */
+interface RouteScopeOptions {
+    scope?: ScopeMap;
+}
+/** Result of {@link ProductionHttpRouteContext.apply}. */
+type RouteApplyResult = {
+    ok: true;
+    operation: Operation;
+    record: MaterializedRecord | null;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+    retriable: boolean;
+};
+/**
+ * A conditional, multi-collection admission gate applied atomically per instance.
+ *
+ * The gate reads the current state of the target record (`collection` + `id`),
+ * checks the `if` predicate against it, and only then applies the `update` to the
+ * target plus every mutation in `also` as one set. If the predicate fails it
+ * applies nothing and returns the structured `reject`. `idempotencyKey` names a
+ * record whose prior existence proves the set already committed, so a retry
+ * returns the earlier outcome instead of applying the set (and its non-idempotent
+ * counter increments) again.
+ *
+ * Atomicity note: within one server instance the check and the writes do not
+ * interleave with other route mutations. Cross-instance, race-free admission and
+ * all-or-nothing across a mid-set crash require the store-level conditional
+ * transaction (a Postgres `WHERE ... < cap` commit), which is the next increment.
+ */
+interface RouteConditionalApply {
+    /** Collection of the record the predicate reads and the `update` targets. */
+    collection: string;
+    /** Id of the target record. */
+    id: string;
+    /** Admission predicate evaluated against the target's current state. */
+    if?: RoutePredicate;
+    /** Partial update applied to the target record when the predicate holds. */
+    update?: Record<string, unknown> | null;
+    /** Additional mutations committed atomically with the target update. */
+    also?: RouteMutation[];
+    /** Structured rejection returned when the predicate does not hold. */
+    reject?: {
+        code: string;
+        message: string;
+    };
     /**
-     * Query records from a materialized collection with filtering, ordering,
-     * and pagination. Requires schema to be set via setSchema().
-     *
-     * @param collection - The collection name to query
-     * @param options - Query options (where, orderBy, limit, offset)
-     * @returns Array of matching records
+     * Names a record whose existence means this set already committed. When it is
+     * present the set is skipped and the prior outcome returned. Use a stable,
+     * client-generated id (for example the accepted record's own id).
      */
-    queryCollection(collection: string, options?: CollectionQueryOptions): Promise<MaterializedRecord[]>;
+    idempotencyKey?: {
+        collection: string;
+        id: string;
+    };
+}
+/** Result of {@link ProductionHttpRouteContext.applyConditional}. */
+type RouteConditionalResult = {
+    ok: true;
+    /** True when the set was already committed and this call was a no-op. */
+    idempotent: boolean;
+    operations: Operation[];
+    records: (MaterializedRecord | null)[];
+} | {
+    ok: false;
+    code: string;
+    message: string;
+    retriable: boolean;
+};
+/**
+ * Scoped, validated data-plane access handed to custom HTTP route handlers.
+ *
+ * Every mutation goes through the same pipeline as sync (Tier 2 constraints,
+ * referential integrity, materialization, and fan-out to connected clients), so
+ * REST endpoints cannot accidentally bypass validation, constraints, or tenant
+ * isolation the way hand-rolled store writes can.
+ */
+interface ProductionHttpRouteContext {
     /**
-     * Find a single record by ID from a materialized collection.
-     * Requires schema to be set via setSchema().
-     *
-     * @param collection - The collection name
-     * @param id - The record ID
-     * @returns The record or null if not found (or deleted)
+     * Apply a mutation through the validated server pipeline and relay the
+     * resulting operation(s) to connected clients.
      */
-    findRecord(collection: string, id: string): Promise<MaterializedRecord | null>;
+    apply(mutation: RouteMutation, options?: RouteScopeOptions): Promise<RouteApplyResult>;
     /**
-     * Count records in a materialized collection, optionally filtered.
-     * Requires schema to be set via setSchema().
-     *
-     * @param collection - The collection name
-     * @param where - Optional exact-match filters
-     * @returns Number of matching records
+     * Conditionally apply a multi-collection mutation set as one admission gate:
+     * read the target, check the predicate, and commit the update plus every `also`
+     * mutation only if it holds, with at-most-once semantics via `idempotencyKey`.
      */
-    countCollection(collection: string, where?: Record<string, unknown>): Promise<number>;
+    applyConditional(spec: RouteConditionalApply, options?: RouteScopeOptions): Promise<RouteConditionalResult>;
+    /** Read materialized records from a collection, optionally scoped. */
+    query(collection: string, options?: CollectionQueryOptions & RouteScopeOptions): Promise<MaterializedRecord[]>;
+    /** Read a single materialized record by id, optionally scoped. */
+    findById(collection: string, id: string, options?: RouteScopeOptions): Promise<MaterializedRecord | null>;
+}
+
+/**
+ * What the server hands an operation validator so it can adjudicate an untrusted
+ * client operation before that operation becomes authoritative.
+ *
+ * The validator is POLICY (yours); the framework owns the MECHANISM around it —
+ * running it at ingestion, and routing its decision deterministically.
+ */
+interface OperationValidationContext {
     /**
-     * Export all data as a portable backup binary.
-     * Ships operations, version vector, and metadata in a self-describing format
-     * with SHA-256 checksum.
+     * The authenticated actor for the submitting session, or `null` for an
+     * anonymous / unauthenticated connection. This is how a public submission
+     * endpoint tells "signed-in owner" from "anonymous respondent" apart.
      */
-    exportBackup(): Promise<Uint8Array>;
+    auth: AuthContext | null;
     /**
-     * Restore data from a portable backup binary.
-     * Operations are applied through applyRemoteOperation for safe merge.
-     *
-     * @param data - Backup binary
-     * @param merge - If true, merge with existing operations; if false, replace all
+     * Trusted, scoped data-plane access — the same context available as
+     * `server.kora` / `request.kora`. Use `kora.query` / `kora.findById` to read
+     * current authoritative state while deciding, and `kora.apply` to AUTHOR a
+     * derived server operation (for example promoting a validated anonymous
+     * submission into an owner-visible collection). Authoring a new operation is
+     * always preferred over mutating the incoming one, which must stay immutable
+     * so content-addressing and convergence hold.
      */
-    importBackup(data: Uint8Array, merge?: boolean): Promise<{
-        operationsRestored: number;
-        success: boolean;
-    }>;
+    kora: ProductionHttpRouteContext;
 }
+/**
+ * The verdict a validator returns for one incoming operation.
+ *
+ * - `accept` — let the operation materialize on the server as-is and relay to
+ *   connected clients, exactly as an untrusted op would flow without a validator.
+ * - `reject` — refuse it. The operation never enters the authoritative log, so no
+ *   other replica ever sees it; a structured rejection travels back to the
+ *   submitter tied to the operation id, and the submitter keeps the op in a
+ *   durable rejected store (recoverable and explainable) rather than losing it or
+ *   retrying forever. `retriable` defaults from the shared taxonomy for the code.
+ * - `ignore` — the server takes responsibility for the operation out of band (for
+ *   example the validator already authored a derived op via `context.kora`) and
+ *   does not want the raw incoming op materialized. No rejection is sent, so the
+ *   submitter treats it as handled and drops it from its pending queue.
+ */
+type OperationDecision = {
+    action: 'accept';
+} | {
+    action: 'reject';
+    code: string;
+    message: string;
+    retriable?: boolean;
+} | {
+    action: 'ignore';
+};
+/**
+ * An app-provided function that adjudicates an untrusted client operation at sync
+ * ingestion, after HLC ordering and the built-in guards (timestamp, rate, size),
+ * and before the operation is materialized into authoritative state.
+ */
+type OperationValidator = (operation: Operation, context: OperationValidationContext) => Promise<OperationDecision> | OperationDecision;
 
 /**
  * Authenticated client context. Returned by an AuthProvider after validation.
@@ -268,7 +821,21 @@ interface KoraSyncServerConfig {
     maxConnections?: number;
     /** Maximum operations per sync batch. Defaults to 100. */
     batchSize?: number;
-    /** Schema version the server expects. Defaults to 1. */
+    /**
+     * How often to retransmit unacknowledged non-watermark relay batches, in
+     * milliseconds. Defaults to 2000. Set to 0 to disable periodic retransmit.
+     */
+    relayRetransmitIntervalMs?: number;
+    /**
+     * How often the server checks the authoritative delivery log for writes that did
+     * not pass through this KoraSyncServer instance, in milliseconds. Defaults to
+     * 2000. Set to 0 to disable polling.
+     */
+    deliveryPollIntervalMs?: number;
+    /**
+     * Schema version the server expects. Defaults to `store.getSchema()?.version`
+     * when the store has been configured with a schema, otherwise `1`.
+     */
     schemaVersion?: number;
     /**
      * Inclusive range of client schema versions accepted at handshake.
@@ -278,6 +845,13 @@ interface KoraSyncServerConfig {
         min: number;
         max: number;
     };
+    /**
+     * Transform accepted legacy client operations into the server schema version
+     * before validation and materialization. Required when
+     * `supportedSchemaVersions.min` is lower than `schemaVersion` and operation
+     * shapes changed across versions.
+     */
+    operationTransforms?: OperationTransform[];
     /** WebSocket path (standalone mode). Defaults to '/'. */
     path?: string;
     /** Structured logger. Defaults to pretty-print in dev, JSON lines in production. */
@@ -286,6 +860,48 @@ interface KoraSyncServerConfig {
     metricsCollector?: ServerMetricsCollector;
     /** Enable built-in dashboard and metrics endpoints. Defaults to true. */
     enableDashboard?: boolean;
+    /**
+     * Resolve a blob chunk by content hash from server-side storage. Optional.
+     * When provided, the server answers blob chunk requests directly from its own
+     * store; when absent, the server relays chunk requests among connected peers
+     * without storing any blob bytes itself.
+     */
+    resolveBlobChunk?: (hash: string) => Promise<Uint8Array | null>;
+    /**
+     * Persist a client-uploaded blob chunk (or manifest) centrally, keyed by its
+     * content hash. Optional. When provided, the server advertises central blob
+     * storage at handshake, clients upload the bytes behind their `blob` fields,
+     * and those bytes remain available to other devices after the authoring device
+     * goes offline. Pair with `resolveBlobChunk` (both backed by the same store)
+     * so uploaded blobs can then be served. `toServerBlobCallbacks` in
+     * `@korajs/store` derives both from a `ContentAddressedBlobStore`.
+     */
+    persistBlobChunk?: (hash: string, bytes: Uint8Array) => Promise<void> | void;
+    /**
+     * Maximum serialized byte size of a single client operation accepted at sync
+     * ingest. Operations larger than this are rejected before materialization.
+     * Defaults to 256 KiB. Set once here to enforce one payload cap across every
+     * connected client instead of configuring each session.
+     */
+    maxOperationBytes?: number;
+    /**
+     * Maximum operations accepted per connected client per minute (sliding window).
+     * Operations beyond the limit are rejected until the window resets. Defaults to
+     * 600. Set once here to enforce one rate cap across every connected client.
+     */
+    maxOpsPerMinute?: number;
+    /**
+     * Adjudicate untrusted client operations before they become authoritative.
+     *
+     * Runs at sync ingestion for every incoming client operation, after HLC
+     * ordering and the built-in guards, and before materialization. Return
+     * `accept` to let it through, `reject` to refuse it (a structured rejection
+     * travels back to the submitter and the op never enters the authoritative
+     * log), or `ignore` when the server has handled it out of band. This is what
+     * lets Kora serve public / multi-tenant apps where the client is not trusted.
+     * Omit it and every operation is accepted, as before.
+     */
+    validateOperation?: OperationValidator;
 }
 /**
  * Request envelope for the server-side HTTP sync endpoint.
@@ -439,6 +1055,20 @@ type AwarenessRelayCallback = (sourceSessionId: string, message: AwarenessUpdate
  * Callback invoked when a session receives a Yjs doc channel update to relay.
  */
 type YjsDocRelayCallback = (sourceSessionId: string, message: YjsDocUpdateMessage) => void;
+/**
+ * Callback invoked when a session receives a blob chunk request to route.
+ */
+type BlobChunkRequestCallback = (sourceSessionId: string, message: BlobChunkRequestMessage) => void;
+/**
+ * Callback invoked when a session receives a blob chunk response to route back.
+ */
+type BlobChunkResponseCallback = (sourceSessionId: string, message: BlobChunkResponseMessage) => void;
+/**
+ * Persist a blob chunk (or manifest) uploaded by a client, keyed by its content
+ * hash. Provided by the server operator; enables central blob storage so bytes
+ * survive the authoring device going offline.
+ */
+type PersistBlobChunk = (hash: string, bytes: Uint8Array) => Promise<void> | void;
 /**
  * Options for creating a ClientSession.
  */
@@ -455,6 +1085,8 @@ interface ClientSessionOptions {
     serializer?: MessageSerializer;
     /** Event emitter for DevTools integration */
     emitter?: KoraEventEmitter;
+    /** Structured logger used for protocol and persistence failures */
+    logger?: Logger;
     /** Max operations per sync batch */
     batchSize?: number;
     /** Schema version the server expects */
@@ -464,18 +1096,47 @@ interface ClientSessionOptions {
         min: number;
         max: number;
     };
+    /** Transform accepted legacy operations into the server schema before validation. */
+    operationTransforms?: OperationTransform[];
     /** Called when this session has operations to relay to other sessions */
     onRelay?: RelayCallback;
     /** Called when this session receives an awareness update to broadcast */
     onAwarenessUpdate?: AwarenessRelayCallback;
     /** Called when this session receives a Yjs doc channel update to broadcast */
     onYjsDocUpdate?: YjsDocRelayCallback;
+    /** Called when this session receives a blob chunk request to route */
+    onBlobChunkRequest?: BlobChunkRequestCallback;
+    /** Called when this session receives a blob chunk response to route back */
+    onBlobChunkResponse?: BlobChunkResponseCallback;
+    /** Persist a client-uploaded blob chunk centrally (keyed by content hash) */
+    persistBlobChunk?: PersistBlobChunk;
     /** Called when this session closes */
     onClose?: (sessionId: string) => void;
+    /**
+     * Called on close with relay operations this client never acknowledged, so the
+     * server can buffer them per node id and redeliver on the client's next
+     * connection. Closes the window where a relay dropped just before a reconnect
+     * would otherwise be lost (the per-session retransmit tick never fires in time).
+     */
+    onOrphanedRelays?: (nodeId: string, ops: Operation[]) => void;
+    /**
+     * Called once this session reaches streaming to pull any relay operations buffered
+     * for its node id while it was disconnected. They are re-sent through the normal
+     * relay path (re-filtered by this session's current scope).
+     */
+    takeOrphanedRelays?: (nodeId: string) => Operation[];
     /** Maximum serialized operation size in bytes. Defaults to 256 KiB. */
     maxOperationBytes?: number;
     /** Maximum operations accepted per minute for this session. Defaults to 600. */
     maxOpsPerMinute?: number;
+    /**
+     * Adjudicate untrusted client operations before materialization. When present,
+     * each incoming operation is passed to this validator; a `reject` decision
+     * sends an operation-rejected message and skips materialization.
+     */
+    validateOperation?: OperationValidator;
+    /** Trusted data-plane context handed to the validator (read state, author derived ops). */
+    koraContext?: ProductionHttpRouteContext;
 }
 /**
  * Handles the sync protocol for a single connected client.
@@ -497,22 +1158,67 @@ declare class ClientSession {
     private authContext;
     private syncQuerySubsets;
     private resumeDeltaCursor;
+    /**
+     * The delivery watermark the client reported at handshake, or null when the client
+     * does not use the delivery watermark (old client, or no watermark yet). When set,
+     * the server drives the gap-free server->client stream from delivery sequences
+     * instead of the version-vector delta.
+     */
+    private clientDeliveryWatermark;
+    /**
+     * The highest delivery sequence this client has ACKNOWLEDGED (its confirmed
+     * watermark, as reported in acks). Incremental streaming pushes resume from here, not
+     * from the highest sequence sent, so a dropped or unapplied batch is always
+     * re-included by the next push (which re-scans from the acknowledged position). This
+     * is what makes streaming recovery independent of any bounded retransmit buffer: there
+     * is no sent-but-unacked window that a buffer eviction could strand. Seeded from the
+     * client's reported watermark at handshake.
+     */
+    private lastAckedDeliverySeq;
+    /**
+     * Timestamp of the last delivery-stream send attempt. Periodic retransmission uses
+     * this as its stale window so a slow client does not receive duplicate full-stream
+     * batches every server tick while the first batch is still being applied.
+     */
+    private lastDeliveryPushAttemptAtMs;
+    private deliveryStallRepeatCount;
+    /** Serializes incremental delivery pushes so their batches never interleave. */
+    private deliveryPushChain;
+    /**
+     * Relay batches sent to this client but not yet acknowledged, keyed by messageId.
+     * The client acks every operation-batch it applies; on ack the entry is cleared.
+     * {@link retransmitPendingRelays} re-sends anything still unacked, so a relay
+     * dropped by a lossy transport is redelivered instead of leaving the client with a
+     * permanent version-vector gap (a lost operation) that delta sync cannot recover.
+     * Bounded so a silent client cannot grow it without limit.
+     */
+    private readonly pendingRelays;
+    private static readonly MAX_PENDING_RELAYS;
     private readonly sessionId;
     private readonly transport;
     private readonly store;
     private readonly auth;
     private readonly serializer;
     private readonly emitter;
+    private readonly logger;
     private readonly batchSize;
     private readonly schemaVersion;
     private readonly supportedSchemaVersions;
+    private readonly operationTransforms;
     private readonly onRelay;
     private readonly onAwarenessUpdate;
     private readonly onYjsDocUpdate;
+    private readonly onBlobChunkRequest;
+    private readonly onBlobChunkResponse;
+    private readonly persistBlobChunk;
     private readonly onClose;
+    private readonly onOrphanedRelays;
+    private readonly takeOrphanedRelays;
     private readonly maxOperationBytes;
     private readonly maxOpsPerMinute;
     private readonly rateLimiter;
+    private readonly validateOperation;
+    private readonly koraContext;
     constructor(options: ClientSessionOptions);
     /**
      * Start handling messages from the client transport.
@@ -523,9 +1229,39 @@ declare class ClientSession {
      * Only relays if the session is in streaming state and transport is connected.
      */
     relayOperations(operations: Operation[]): void;
+    /**
+     * Push newly-available in-scope operations to a delivery-watermark client, resuming
+     * from the highest delivery sequence already sent. Pushes are serialized so their
+     * batches never interleave (which would break the base/max chain).
+     */
+    private pushDeliveryStream;
+    private relayVisibleOperations;
+    /** Record a relay batch as awaiting acknowledgment, evicting the oldest if full. */
+    private trackPendingRelay;
+    /**
+     * Retransmit relay batches this client has not acknowledged within `staleMs`.
+     * Called on a periodic tick by the server (and directly by tests). Redelivering an
+     * already-applied op is harmless: the client dedups by content-addressed id.
+     */
+    retransmitPendingRelays(staleMs?: number): void;
+    /**
+     * Wake the durable delivery stream for clients that negotiated delivery
+     * watermarks. This is used both for dropped watermark batches and for operations
+     * appended by another server/store instance: the session always scans from its
+     * own acknowledged cursor and applies its visibility filter before sending.
+     */
+    pushDeliveryStreamIfSupported(staleMs?: number, options?: {
+        trackStall?: boolean;
+    }): void;
     /**
      * Close this session.
      */
+    /**
+     * Hand any unacknowledged relays to the server so they survive this session and are
+     * redelivered when this client reconnects (per-node buffer), then clear them. Called
+     * from every session-teardown path (explicit close and transport close).
+     */
+    private flushOrphanedRelays;
     close(reason?: string): void;
     getState(): SessionState;
     getSessionId(): string;
@@ -542,119 +1278,57 @@ declare class ClientSession {
     private sendToClient;
     private enqueueMessage;
     private handleMessageAsync;
+    /**
+     * Persist a client-uploaded blob chunk (or manifest) centrally. The bytes are
+     * verified to hash to the declared hash before storing, so a corrupt or
+     * mislabeled upload is rejected rather than served later as trusted content.
+     */
+    private handleBlobChunkPush;
     private handleMessageFailure;
     private handleHandshake;
     private handleOperationBatch;
+    private transformForServerSchema;
     private sendDelta;
-    private operationVisibleToClient;
-    private handleAwarenessUpdate;
-    private handleYjsDocUpdate;
-    private sendError;
-    private setSerializerWireFormat;
-    private handleTransportClose;
-}
-
-/**
- * Minimal interface for a ws.WebSocketServer instance.
- * Allows dependency injection for testing without importing ws directly.
- */
-interface WsServerLike {
-    on(event: string, listener: (...args: unknown[]) => void): void;
-    close(callback?: (err?: Error) => void): void;
-    address(): {
-        port: number;
-    } | string | null;
-}
-/**
- * Constructor type for creating a WebSocket server.
- */
-type WsServerConstructor = new (options: {
-    port?: number;
-    host?: string;
-    path?: string;
-}) => WsServerLike;
-/**
- * Self-hosted sync server. Accepts WebSocket connections from clients,
- * handles the sync protocol, stores operations, and relays changes
- * between connected clients.
- *
- * Two modes of operation:
- * 1. **Standalone**: Call `start()` with a port — creates its own WebSocket server.
- * 2. **Attach**: Call `handleConnection(transport)` — attach to an existing HTTP server.
- */
-declare class KoraSyncServer {
-    private readonly store;
-    private readonly auth;
-    private readonly serializer;
-    private readonly emitter;
-    private readonly maxConnections;
-    private readonly batchSize;
-    private readonly schemaVersion;
-    private readonly supportedSchemaVersions;
-    private readonly port;
-    private readonly host;
-    private readonly path;
-    private readonly logger;
-    private readonly metrics;
-    private readonly awarenessRelay;
-    private readonly yjsDocRelay;
-    private readonly sessions;
-    private readonly httpClients;
-    private readonly httpSessionToClient;
-    private readonly serverVersion;
-    private wsServer;
-    private running;
-    constructor(config: KoraSyncServerConfig);
-    /**
-     * Subscribe to session-level events for metrics collection and logging.
-     * Called when a new session is created.
-     */
-    private attachSessionEvents;
-    /**
-     * Get the metrics collector for external access (e.g., HTTP endpoints).
-     */
-    getMetricsCollector(): ServerMetricsCollector;
-    /**
-     * Get the logger for external access (e.g., event streaming).
-     */
-    getLogger(): Logger;
     /**
-     * Start the WebSocket server in standalone mode.
-     *
-     * @param wsServerImpl - Optional WebSocket server constructor for testing
-     */
-    start(wsServerImpl?: WsServerConstructor): Promise<void>;
-    /**
-     * Stop the server. Closes all sessions and the WebSocket server.
-     */
-    stop(): Promise<void>;
-    /**
-     * Handle one HTTP sync request for a long-polling client.
-     *
-     * A stable `clientId` identifies the logical connection across requests.
-     */
-    handleHttpRequest(request: HttpSyncRequest): Promise<HttpSyncResponse>;
-    /**
-     * Handle an incoming client connection (attach mode).
-     * Creates a new ClientSession for the transport.
+     * Send the gap-free server->client delivery stream, resuming just after
+     * `fromDeliverySeq`. Operations are scanned in server delivery-sequence order
+     * (commit order), scope-filtered for this session, and sent in batches that chain:
+     * each batch's `baseDeliverySequence` equals the previous batch's
+     * `maxDeliverySequence` (the first batch bases on `fromDeliverySeq`). The client
+     * applies a batch only when its watermark equals the base and advances the
+     * watermark to the max, so a dropped batch stalls the watermark and is recovered by
+     * the next handshake resend. Because delivery-sequence order respects causal order
+     * (a dependency is always committed, and thus sequenced, before its dependent), no
+     * topological sort is needed and the client never defers on a missing dependency
+     * that is itself in this stream.
      *
-     * @param transport - The server transport for the new connection
-     * @returns The session ID
+     * The final batch advances the watermark to the highest delivery sequence scanned,
+     * not merely the last in-scope one, so an out-of-scope tail is not re-scanned on the
+     * next reconnect. Returns the number of operations actually sent.
      */
-    handleConnection(transport: ServerTransport): string;
+    private sendDeliveryStream;
+    /** Build, track, and send one chained delivery-stream batch. */
+    private sendDeliveryBatch;
+    private operationVisibleToClient;
     /**
-     * Get the current server status.
+     * Read a record's current field values from the materialized store for scope /
+     * query-subset backfill. Includes soft-deleted rows so a relayed delete (whose op
+     * carries no fields) is still judged against the record's actual scope. Returns
+     * undefined when the record cannot be read (never materialized, or no schema).
      */
-    getStatus(): Promise<ServerStatus>;
+    private lookupRecordFields;
+    private handleAwarenessUpdate;
+    private handleYjsDocUpdate;
+    private sendError;
     /**
-     * Get the number of currently connected clients.
+     * Reject one specific client operation, tied to its id, so the submitter can
+     * divert it out of its pending queue into a durable rejected store rather than
+     * losing it or retrying forever. The op is NOT materialized, so no other
+     * replica ever sees it.
      */
-    getConnectionCount(): number;
-    private handleRelay;
-    private handleSessionClose;
-    private handleAwarenessRelay;
-    private handleYjsDocRelay;
-    private getOrCreateHttpClient;
+    private sendOperationRejected;
+    private setSerializerWireFormat;
+    private handleTransportClose;
 }
 
 /**
@@ -672,6 +1346,13 @@ interface ProductionServerConfig {
     syncPath?: string;
     /** Additional KoraSyncServer options */
     syncOptions?: Omit<KoraSyncServerConfig, 'store' | 'port' | 'host' | 'path'>;
+    /**
+     * Cross-Origin-Embedder-Policy for static and route responses. Defaults to
+     * `credentialless`, which keeps third-party embeds usable while allowing
+     * capable browsers to enable cross-origin isolation. Use `require-corp` only
+     * when every embedded resource explicitly opts in with CORP/CORS headers.
+     */
+    crossOriginEmbedderPolicy?: 'credentialless' | 'require-corp' | 'unsafe-none';
     /**
      * Optional HTTP route handlers mounted before static file serving.
      *
@@ -704,6 +1385,13 @@ interface ProductionHttpRouteRequest {
     headers?: Record<string, string | string[] | undefined>;
     query?: Record<string, string | string[] | undefined>;
     ip?: string;
+    /**
+     * Scoped, validated data-plane access. Use `kora.apply()` to mutate through
+     * the same pipeline as sync (constraints, referential integrity, fan-out) and
+     * `kora.query()` / `kora.findById()` to read materialized state, instead of
+     * writing to the store directly and bypassing those guarantees.
+     */
+    kora: ProductionHttpRouteContext;
 }
 interface ProductionHttpRouteResponse {
     status: number;
@@ -723,6 +1411,29 @@ interface ProductionServer {
     start(): Promise<string>;
     /** Stop the server gracefully. */
     stop(): Promise<void>;
+    /**
+     * Trusted, scoped data-plane access for server-side callers that have no HTTP
+     * request — background jobs, scheduled tasks, seeding scripts.
+     *
+     * `kora.apply()` runs the mutation through the exact same validated pipeline as
+     * sync (Tier 2 constraints, referential integrity, materialization, and fan-out
+     * to connected clients), and `kora.query()` / `kora.findById()` read
+     * materialized state. This is the same context handed to custom HTTP routes as
+     * `request.kora`, so a job and a request share one code path and one set of
+     * guarantees instead of the job writing to the store directly and silently
+     * bypassing validation.
+     */
+    kora: ProductionHttpRouteContext;
+    /**
+     * Every blob reference still reachable from a live record across all
+     * collections that declare a `blob` field. This is the live set for
+     * garbage-collecting the server's central blob store: pass it to
+     * `collectBlobGarbage(blobStore, refs)` from `@korajs/store` on a schedule to
+     * reclaim bytes no record points at any more.
+     *
+     * @returns Every live blob reference the server can currently see.
+     */
+    getLiveBlobRefs(): Promise<BlobRef[]>;
 }
 /**
  * Creates a production server that serves both static files and WebSocket sync
@@ -965,6 +1676,14 @@ declare class MemoryServerStore implements ServerStore {
     private readonly operations;
     private readonly operationIndex;
     private readonly versionVector;
+    /**
+     * Server-assigned delivery sequence per operation id. Single-process, so a plain
+     * counter incremented at insert time gives commit-order delivery sequence with no
+     * gaps. `operations` is kept in insertion (== delivery) order, so a delivery scan
+     * is a forward walk.
+     */
+    private readonly deliverySeqByOpId;
+    private deliverySeqCounter;
     private schema;
     /** Materialized records: collection -> recordId -> record data */
     private readonly materializedRecords;
@@ -977,6 +1696,8 @@ declare class MemoryServerStore implements ServerStore {
     applyRemoteOperation(op: Operation): Promise<ApplyResult>;
     getOperationRange(nodeId: string, fromSeq: number, toSeq: number): Promise<Operation[]>;
     getOperationCount(): Promise<number>;
+    getMaxDeliverySequence(): Promise<number>;
+    getOperationsAfterDelivery(afterDeliverySequence: number, limit: number): Promise<DeliveredOperation[]>;
     materializeCollection(collection: string): Promise<MaterializedRecord[]>;
     queryCollection(collection: string, options?: CollectionQueryOptions): Promise<MaterializedRecord[]>;
     findRecord(collection: string, id: string): Promise<MaterializedRecord | null>;
@@ -1017,14 +1738,44 @@ declare class PostgresServerStore implements ServerStore {
     private readonly ready;
     private schema;
     private closed;
-    constructor(db: PostgresJsDatabase, nodeId?: string);
+    /**
+     * Monotonic counter for this node's server-originated sequence numbers. Lazily
+     * seeded from the persisted version vector on first use, then advanced in memory
+     * (a synchronous `++`, atomic on the single JS thread) so concurrent conditional
+     * applies never receive the same number. Null means "not yet seeded"; reset to
+     * null after a backup import so it re-seeds from the restored version vector.
+     */
+    private sequenceCounter;
+    /**
+     * Time source for HLC timestamps on server-originated operations. Injectable so a
+     * test can freeze wall-clock time and prove the conditional-apply ordering holds
+     * under same-millisecond commits (the case the advisory lock and clock advance
+     * exist to make correct). Defaults to the system clock in production.
+     */
+    private readonly timeSource;
+    constructor(db: PostgresJsDatabase, nodeId?: string, timeSource?: TimeSource);
     getVersionVector(): VersionVector;
+    /**
+     * Atomically reserve this node's next server-operation sequence number. The
+     * synchronous increment cannot interleave on the single JS thread, so two
+     * concurrent conditional applies are always handed distinct numbers.
+     */
+    reserveSequenceNumber(): number;
     getNodeId(): string;
     getSchema(): SchemaDefinition | null;
     setSchema(schema: SchemaDefinition): Promise<void>;
     applyRemoteOperation(op: Operation): Promise<ApplyResult>;
+    /**
+     * Conditionally apply operations atomically, serialized across server instances
+     * on the target record via a transaction-scoped advisory lock. The lock makes
+     * the read-decide-write cycle atomic against concurrent instances, so a cap
+     * check like `responseCount < max` cannot be passed by two admissions at once.
+     */
+    applyConditional(input: ConditionalApplyInput): Promise<ConditionalApplyResult>;
     getOperationRange(nodeId: string, fromSeq: number, toSeq: number): Promise<Operation[]>;
     getOperationCount(): Promise<number>;
+    getMaxDeliverySequence(): Promise<number>;
+    getOperationsAfterDelivery(afterDeliverySequence: number, limit: number): Promise<DeliveredOperation[]>;
     materializeCollection(collection: string): Promise<MaterializedRecord[]>;
     queryCollection(collection: string, options?: CollectionQueryOptions): Promise<MaterializedRecord[]>;
     findRecord(collection: string, id: string): Promise<MaterializedRecord | null>;
@@ -1035,6 +1786,13 @@ declare class PostgresServerStore implements ServerStore {
         operationsRestored: number;
         success: boolean;
     }>;
+    /**
+     * The HLC timestamp of the most recent operation on a record, by total order
+     * (wallTime, logical, nodeId), or null when the record has no operations. Used
+     * by {@link applyConditional} to advance its clock past the record's latest
+     * write so newly built operations sort strictly after it.
+     */
+    private latestOperationTimestamp;
     /**
      * Rebuild a single record in the materialized collection table by replaying
      * all operations for that record.
@@ -1058,6 +1816,12 @@ declare class PostgresServerStore implements ServerStore {
     private materializeFromOpsLog;
     private initialize;
     private ensureTables;
+    /**
+     * Reserve the next delivery sequence inside an open append transaction. The
+     * `UPDATE ... RETURNING` locks the counter row until this transaction commits,
+     * serializing assignment into commit order (see the counter table comment).
+     */
+    private nextDeliverySeq;
     private serializeOperation;
     private deserializeOperation;
     private assertOpen;
@@ -1093,6 +1857,8 @@ declare class SqliteServerStore implements ServerStore {
     applyRemoteOperation(op: Operation): Promise<ApplyResult>;
     getOperationRange(nodeId: string, fromSeq: number, toSeq: number): Promise<Operation[]>;
     getOperationCount(): Promise<number>;
+    getMaxDeliverySequence(): Promise<number>;
+    getOperationsAfterDelivery(afterDeliverySequence: number, limit: number): Promise<DeliveredOperation[]>;
     materializeCollection(collection: string): Promise<MaterializedRecord[]>;
     queryCollection(collection: string, options?: CollectionQueryOptions): Promise<MaterializedRecord[]>;
     findRecord(collection: string, id: string): Promise<MaterializedRecord | null>;
@@ -1131,6 +1897,19 @@ declare class SqliteServerStore implements ServerStore {
      * Create the operations and sync_state tables if they don't exist.
      */
     private ensureTables;
+    /**
+     * Assign delivery sequences to any operations written before the column existed,
+     * then seed the durable counter from the current max. Ordered by
+     * (received_at, sequence_number, id) so the backfill is deterministic and stable
+     * across restarts. A one-time migration: after it runs, all rows have a value.
+     */
+    private backfillDeliverySequence;
+    /**
+     * Reserve the next delivery sequence inside the append transaction. SQLite locks
+     * the database for the write transaction, and this counter row keeps sequence
+     * allocation shared by every SqliteServerStore instance using the same file.
+     */
+    private nextDeliverySeq;
     private serializeOperation;
     private deserializeOperation;
     private assertOpen;
@@ -1232,4 +2011,4 @@ declare class AwarenessRelay {
  */
 declare function createKoraServer(config: KoraSyncServerConfig): KoraSyncServer;
 
-export { type AuthContext, type AuthProvider, AwarenessRelay, type AwarenessRelayCallback, type ClientMetrics, ClientSession, type ClientSessionOptions, type CollectionQueryOptions, type HttpPollResponse, HttpServerTransport, type HttpSyncRequest, type HttpSyncResponse, KoraAuthProvider, type KoraAuthProviderOptions, KoraSyncServer, type KoraSyncServerConfig, type LogEntry, type LogLevel, type Logger, type MaterializedRecord, MemoryServerStore, MixedAuthProvider, type MixedAuthProviderOptions, NoAuthProvider, PostgresServerStore, type ProductionHttpRoute, type ProductionHttpRouteRequest, type ProductionHttpRouteResponse, type ProductionServer, type ProductionServerConfig, type RelayCallback, ServerCloseHandler, ServerErrorHandler, ServerMessageHandler, ServerMetricsCollector, type ServerMetricsSnapshot, type ServerStatus, type ServerStore, ServerTransport, type SessionState, SqliteServerStore, TokenAuthProvider, type TokenAuthProviderOptions, type WsServerConstructor, type WsServerLike, WsServerTransport, type WsServerTransportOptions, type WsWebSocket, createDefaultLogger, createJsonLogger, createKoraServer, createPostgresServerStore, createPrettyLogger, createProductionServer, createSilentLogger, createSqliteServerStore };
+export { type AuthContext, type AuthProvider, AwarenessRelay, type AwarenessRelayCallback, type ClientMetrics, ClientSession, type ClientSessionOptions, type CollectionQueryOptions, type HttpPollResponse, HttpServerTransport, type HttpSyncRequest, type HttpSyncResponse, KoraAuthProvider, type KoraAuthProviderOptions, KoraSyncServer, type KoraSyncServerConfig, type LogEntry, type LogLevel, type Logger, type MaterializedRecord, MemoryServerStore, MixedAuthProvider, type MixedAuthProviderOptions, NoAuthProvider, type OperationDecision, type OperationRejection, type OperationValidationContext, type OperationValidator, PostgresServerStore, type ProductionHttpRoute, type ProductionHttpRouteContext, type ProductionHttpRouteRequest, type ProductionHttpRouteResponse, type ProductionServer, type ProductionServerConfig, RETRIABLE_REJECTION_CODES, type RelayCallback, type RouteApplyResult, type RouteConditionalApply, type RouteConditionalResult, type RouteMutation, type RoutePredicate, type RoutePredicateOperators, type RouteScopeOptions, ServerCloseHandler, ServerErrorHandler, ServerMessageHandler, ServerMetricsCollector, type ServerMetricsSnapshot, type ServerStatus, type ServerStore, ServerTransport, type SessionState, SqliteServerStore, TokenAuthProvider, type TokenAuthProviderOptions, type WsServerConstructor, type WsServerLike, WsServerTransport, type WsServerTransportOptions, type WsWebSocket, createDefaultLogger, createJsonLogger, createKoraServer, createPostgresServerStore, createPrettyLogger, createProductionServer, createSilentLogger, createSqliteServerStore, isRetriableRejection };