@korajs/server 1.0.0-beta.1 → 1.0.0-beta.4

package/dist/index.d.ts

@@ -1,10 +1,199 @@
-import { SchemaDefinition, KoraEventEmitter, Operation, BlobRef, VersionVector } from '@korajs/core';
+import { SchemaDefinition, Operation, BlobRef, KoraEventEmitter, VersionVector } from '@korajs/core';
 import * as _korajs_sync from '@korajs/sync';
-import { SyncStore, MessageSerializer, SyncMessage, AwarenessUpdateMessage, YjsDocUpdateMessage, BlobChunkRequestMessage, BlobChunkResponseMessage, 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.js';
 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;
+}
+/**
+ * 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>;
+    /**
+     * 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 +314,318 @@ 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 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 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;
+    constructor(config: KoraSyncServerConfig);
     /**
-     * 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.
+     * 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>;
     /**
-     * Query records from a materialized collection with filtering, ordering,
-     * and pagination. Requires schema to be set via setSchema().
+     * Handle an incoming client connection (attach mode).
+     * Creates a new ClientSession for the transport.
      *
-     * @param collection - The collection name to query
-     * @param options - Query options (where, orderBy, limit, offset)
-     * @returns Array of matching records
+     * @param transport - The server transport for the new connection
+     * @returns The session ID
      */
-    queryCollection(collection: string, options?: CollectionQueryOptions): Promise<MaterializedRecord[]>;
+    handleConnection(transport: ServerTransport): string;
     /**
-     * Find a single record by ID from a materialized collection.
-     * Requires schema to be set via setSchema().
+     * 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.
      *
-     * @param collection - The collection name
-     * @param id - The record ID
-     * @returns The record or null if not found (or deleted)
+     * 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
      */
-    findRecord(collection: string, id: string): Promise<MaterializedRecord | null>;
+    applyLocalOperation(op: Operation): Promise<ApplyServerOperationResult>;
     /**
-     * Count records in a materialized collection, optionally filtered.
-     * Requires schema to be set via setSchema().
+     * Collect every blob reference still reachable from live records on the server.
      *
-     * @param collection - The collection name
-     * @param where - Optional exact-match filters
-     * @returns Number of matching records
+     * 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;
+    };
+    /**
+     * 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).
+     */
+    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 {
+    /**
+     * Apply a mutation through the validated server pipeline and relay the
+     * resulting operation(s) to connected clients.
+     */
+    apply(mutation: RouteMutation, options?: RouteScopeOptions): Promise<RouteApplyResult>;
+    /**
+     * 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.
@@ -303,6 +705,31 @@ interface KoraSyncServerConfig {
      * `@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.
@@ -513,6 +940,14 @@ interface ClientSessionOptions {
     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.
@@ -553,6 +988,8 @@ declare class ClientSession {
     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.
@@ -596,210 +1033,15 @@ declare class ClientSession {
     private handleAwarenessUpdate;
     private handleYjsDocUpdate;
     private sendError;
-    private setSerializerWireFormat;
-    private handleTransportClose;
-}
-
-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?: {
-        code: string;
-        message: string;
-    };
-}
-
-/**
- * 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 blobChunkRelay;
-    private readonly persistBlobChunk;
-    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.
-     *
-     * @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>;
-    /**
-     * 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;
-}
-
-/**
- * Per-collection scope map from auth context.
- */
-type ScopeMap = Record<string, Record<string, unknown>>;
-
-/**
- * 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;
-};
-/**
- * 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 {
     /**
-     * Apply a mutation through the validated server pipeline and relay the
-     * resulting operation(s) to 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.
      */
-    apply(mutation: RouteMutation, options?: RouteScopeOptions): Promise<RouteApplyResult>;
-    /** 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>;
+    private sendOperationRejected;
+    private setSerializerWireFormat;
+    private handleTransportClose;
 }
 
 /**
@@ -875,6 +1117,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
@@ -1384,4 +1649,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 ProductionHttpRouteContext, type ProductionHttpRouteRequest, type ProductionHttpRouteResponse, type ProductionServer, type ProductionServerConfig, type RelayCallback, type RouteApplyResult, type RouteMutation, 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 };
+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 };