@routier/core 0.2.1 → 0.4.0

package/dist/plugins/translators/TupleTranslator.d.ts

@@ -0,0 +1,45 @@
+import { DataTranslator } from "./DataTranslator";
+import { QueryOption } from "../query/types";
+/**
+ * The memory half's pass over JOIN TUPLES.
+ *
+ * `JsonTranslator` cannot do this job, and the reason is one line of it: `map` and `group` walk
+ * `option.value.fields` and deserialize each field through its `PropertyInfo`. A tuple has no
+ * schema and no fields — `getFields` over `([p, m]) => ({ ... })` extracts nothing meaningful —
+ * so that loop would either no-op or write properties onto a two-element array.
+ *
+ * Everything a join query is allowed to do after the join is expressible as a plain closure
+ * over the tuple, and that is all this does. The lambdas the caller wrote (`([p, m]) => ...`)
+ * are applied as-is, which is also why the result is identical whichever backend produced the
+ * pairs.
+ *
+ * Both halves are already in entity shape when the tuples arrive here (the wire contract), so
+ * there is nothing left to deserialize — the reason the missing field loop costs nothing.
+ *
+ * The absent operations are absent by design, not by omission: `sum`/`min`/`max`/`distinct` and
+ * `group` are not declared on the tuple queryable's type, so reaching them means something
+ * built an option this API cannot express, and a throw naming it is the honest answer.
+ */
+export declare class TupleTranslator<TRoot extends {}, TShape> extends DataTranslator<TRoot, TShape> {
+    filter<TResult>(data: unknown, option: QueryOption<TShape, "filter">): TResult;
+    map<TResult>(data: unknown, option: QueryOption<TShape, "map">): TResult;
+    sort<TResult>(data: unknown, option: QueryOption<TShape, "sort">): TResult;
+    skip<TResult>(data: unknown, option: QueryOption<TShape, "skip">): TResult;
+    take<TResult>(data: unknown, option: QueryOption<TShape, "take">): TResult;
+    count<TResult extends number>(data: unknown, _: QueryOption<TShape, "count">): TResult;
+    /**
+     * Already joined by the time anything reaches here.
+     *
+     * The pairs were produced either by the plugin (its translator's `join`) or by the datastore
+     * before this pass ran, so the option is a record of what happened rather than work to do.
+     */
+    join(data: unknown, _: QueryOption<TShape, "join">): TShape;
+    group<TResult>(_: unknown, __: QueryOption<TShape, "group">): TResult;
+    sum<TResult extends number>(_: unknown, __: QueryOption<TShape, "sum">): TResult;
+    min<TResult extends string | number | Date>(_: unknown, __: QueryOption<TShape, "min">): TResult;
+    max<TResult extends string | number | Date>(_: unknown, __: QueryOption<TShape, "max">): TResult;
+    distinct<TResult>(_: unknown, __: QueryOption<TShape, "distinct">): TResult;
+    nearest(_: unknown, __: QueryOption<TShape, "nearest">): TShape;
+    private notSupported;
+    private notAnArray;
+}

package/dist/plugins/translators/index.d.ts

@@ -1,6 +1,7 @@
 export * from './DataTranslator';
 export * from './JsonTranslator';
 export * from './SqlTranslator';
+export * from './TupleTranslator';
 export * from './types';
 export * from './TranslatedArrayValue';
 export * from './TranslatedGroupValue';

package/dist/plugins/types.d.ts

@@ -1,4 +1,5 @@
 import { PluginEventCallbackPartialResult, PluginEventCallbackResult } from "../results";
+import { ExecutedQuery } from "./query/explain";
 import { QueryOptionsCollection } from "./query/QueryOptionsCollection";
 import { CompiledSchema, InferType } from '../schema';
 import { BulkPersistChanges, BulkPersistResult, SchemaCollection } from "../collections";
@@ -7,6 +8,28 @@ import { ITranslatedValue } from "./translators";
  * Interface for a database plugin, which provides query, destroy, and bulk operations.
  */
 export interface IDbPlugin {
+    /**
+     * Uniquely identifies the database this plugin talks to, INCLUDING host or path where a
+     * bare name would collide — `orders.db` in two directories is two databases, and `mydb`
+     * on two hosts is two databases. Two instances over the same database must return the
+     * same string, in this process and in any other; two over different databases must not.
+     *
+     * Used to scope schema subscription channels, so instances of one database (another tab,
+     * a worker) see each other's change notifications and unrelated databases holding the
+     * same schema do not.
+     *
+     * Required rather than optional on purpose. An absent value used to fall back to scoping
+     * by schema alone, which shares one channel across every database holding that schema —
+     * the exact cross-talk this prevents, arrived at by omission. Requiring it also makes a
+     * wrapper that forgets to forward it a compile error rather than a silent regression.
+     *
+     * Derive it, never generate it: a random value is unique per PROCESS, not per database,
+     * so another tab would never match one and cross-context notifications would stop.
+     *
+     * Must not contain credentials — it becomes part of a channel key, so build it from
+     * host/port/database rather than returning a connection string.
+     */
+    readonly databaseName: string;
     /**
      * Executes a query operation on the database.
      * @param event The query event containing schema, parent, and query operation.
@@ -28,7 +51,48 @@ export interface IDbPlugin {
 /**
  * Event for a query operation, including schema, parent, and the query operation.
  */
-export type DbPluginQueryEvent<TRoot extends {}, TShape> = DbPluginOperationEvent<IQuery<TRoot, TShape>>;
+export type DbPluginQueryEvent<TRoot extends {}, TShape> = DbPluginOperationEvent<IQuery<TRoot, TShape>> & {
+    /**
+     * Whether the caller asked for an explanation. Required, never optional: a query is
+     * either explained or it is not, and "unset" is not a third state.
+     *
+     * A plugin is free to ignore it. One that reports unconditionally is correct; one that
+     * checks the flag to skip building report strings is also correct. What a plugin must
+     * NOT do is treat `true` as an instruction it has to obey — a plugin that cannot report
+     * simply doesn't, and the datastore marks the step as not reported.
+     */
+    explain: boolean;
+    /**
+     * Where a plugin reports what it executed. Pushing to it is how a plugin supports
+     * `.explain()` — a plugin that never pushes still answers queries, and its explanations
+     * mark the database step as not reported (`executedQueriesUnsupported`) instead of
+     * showing statements.
+     *
+     * The datastore decides whether anyone sees it: with `explain` on it reads the array and
+     * an empty one means "not supported"; with `explain` off it takes no action either way.
+     *
+     * An array the DATASTORE creates and the plugin pushes into, rather than a value the plugin
+     * returns. The result envelope is rebuilt in at least six places between a plugin and the
+     * caller — the memory half re-translates, joins build fresh tuple values, the cache
+     * reconstructs from stored entries — so anything carried on it is discarded before arrival.
+     * The event is not rebuilt, and an array survives the shallow spread in `ConcurrencyDbPlugin`
+     * because both sides then hold the same array. Assigning a new one would not.
+     *
+     * Push once per query actually executed, in execution order, so a join reports both reads.
+     * `text` is whatever the backend runs — SQL for a SQL engine, a description of the access
+     * path for a store that has no statement. A plugin that answered without touching its
+     * backend pushes a description of that instead — `CacheDbPlugin` pushes "cache hit" —
+     * because pushing nothing reads as "this plugin does not report".
+     *
+     * Push AFTER the query runs, not before. `RetryDbPlugin` re-invokes with the same event, so
+     * a plugin that pushes first reports an entry per failed attempt.
+     *
+     * The array accumulates for as long as the event lives. That is why `.explain()` is not
+     * offered on a subscribed queryable: `subscribeQuery` builds its event once and re-issues it
+     * on every change notification, which would grow this without bound.
+     */
+    executedQueries: ExecutedQuery[];
+};
 /**
  * Event for bulk operations, including schema, parent, and the entity changes.
  */
@@ -71,12 +135,69 @@ export type ReplicationPluginOptions = {
      */
     read?: IDbPlugin;
 };
+/**
+ * A value inside a delta. Arrays and Dates are values, not sub-structures to descend into.
+ *
+ * Descending into them would be both wrong and useless: an element-wise array delta cannot
+ * express "the last element was removed", and a partial Date is meaningless.
+ */
+type DeltaValue<V> = V extends readonly unknown[] ? V : V extends Date ? V : V extends object ? DeltaProperties<V> : V;
+type DeltaProperties<T> = {
+    [K in keyof T]?: DeltaValue<T[K]>;
+};
+/**
+ * What changed about an entity, expressed as a **partial entity**.
+ *
+ * A change two levels deep appears where it actually lives —
+ * `{ nested: { inner: { value } } }` — not as a flattened key.
+ *
+ * This deliberately carries no storage vocabulary. It used to be typed
+ * `{ [key: string]: string | number | Date }`, which was wrong twice over: it excluded
+ * booleans, nulls, arrays and objects that the schema happily allows, and its flat
+ * scalar shape was really a SQL `SET column = ?` list — one storage family's concern
+ * leaking into the contract every plugin sees.
+ *
+ * Translating this into storage terms belongs to the plugin. A document store can merge it
+ * as-is; a SQL plugin decides which columns it touches and how a nested value is encoded
+ * (see `toColumnAssignments` in `@routier/sql-plugin-core`, which stores nested objects and
+ * arrays as JSON). Core does not need to know, and must not.
+ */
+export type EntityDelta<T extends {}> = DeltaProperties<InferType<T>>;
 export type EntityUpdateInfo<T extends {}> = {
     entity: InferType<T>;
     changeType: EntityChangeType;
-    delta: {
-        [key: string]: string | number | Date;
+    delta: EntityDelta<T>;
+    /**
+     * Present when the schema declares a `.concurrency()` token: the update must be
+     * applied ONLY IF the stored row's `column` still equals `expected` (the value the
+     * writer read). The entity/delta already carry the bumped value to store on success.
+     * A plugin that finds a mismatch must fail the whole save with an
+     * OptimisticConcurrencyError naming the conflicted rows — never apply partially.
+     */
+    concurrency?: {
+        column: string;
+        expected: number;
     };
+    /**
+     * The values these properties held BEFORE this update — keyed like `delta`, which holds
+     * the values they hold after.
+     *
+     * DATASTORE-INTERNAL. The datastore strips it before the plugin is called
+     * (`DataStore.onSavePreparedChanges`), so no plugin ever receives it and nothing goes over
+     * a wire. It exists for save-pipeline participants that must undo work keyed by an old
+     * value — a search index has to delete the rows for terms that just left a field, and
+     * `delta` only says what the field says now.
+     *
+     * Always populated for an update. It is part of what an update IS, not something a
+     * declaration switches on — a consumer can rely on it without knowing what else the store
+     * declared, and there is one code path to reason about rather than two.
+     *
+     * Which properties appear depends on what the change-tracking mode can know. Proxy and
+     * immutable name exactly the properties that changed. Diff detects change by comparing a
+     * content hash, so it cannot say WHICH property moved and reports every root property —
+     * the same "assume everything" convention its empty `delta` already uses.
+     */
+    previous?: EntityDelta<T>;
 };
 export type TaggedEntity<T> = {
     entity: T;
@@ -96,3 +217,4 @@ export type IQuery<TRoot extends {}, TShape> = {
     get changeTracking(): boolean;
 };
 export type EntityChangeType = "propertiesChanged" | "markedDirty" | "notModified";
+export {};

package/dist/plugins/wire/handler.d.ts

@@ -0,0 +1,122 @@
+import { ReadonlySchemaCollection } from "../../collections/ReadonlySchemaCollection";
+import { Filter, ParamsFilter } from "../../expressions";
+import { CompiledSchema } from "../../schema";
+import { IDbPlugin } from "../types";
+import { ScopeProvider } from "./query";
+import { SerializedRequest, SerializedResponse } from "./types";
+/**
+ * The receiving half: takes a serialized request, executes it, returns a serialized response.
+ *
+ * Deliberately not a server. It is one async function from JSON to JSON, with no notion of HTTP, so
+ * the same handler sits behind Express, a Cloudflare Worker, a Lambda, a WebSocket message, or a
+ * worker `postMessage`. Transport is the caller's business; this is the part that would otherwise be
+ * rewritten per framework.
+ *
+ * ```ts
+ * const handle = createRequestHandler({ plugin, schemas });
+ *
+ * app.post("/routier", async (req, res) => res.json(await handle(req.body)));
+ * ```
+ *
+ * ## Security is YOURS, and this gives you the two places to put it
+ *
+ * There is no built-in notion of a user, a tenant, a role or a token, and there should not be: this
+ * library cannot know what your identities are or what they may see. What it can do is make sure
+ * there is nowhere for a decision to be forgotten. Two hooks, and both receive a `context` you built
+ * from the request:
+ *
+ *  - **`authorize`** — may this caller do this at all? Called once per request, before anything is
+ *    deserialized or executed, with the action and every collection the request touches.
+ *  - **`scope`** — which ROWS may this caller see? A filter the receiver ANDs into every read of a
+ *    collection, and checks every written row against.
+ *
+ * With neither supplied, the endpoint answers anything for anyone. That is the correct default for a
+ * function with no idea who is calling it — and the moment you name a context type, passing one
+ * becomes required, so a policy cannot be half-wired.
+ *
+ * ```ts
+ * const handle = createRequestHandler<{ tenantId: string }>({
+ *     plugin,
+ *     schemas,
+ *     authorize: ({ action, context }) => context.tenantId != null || "not signed in",
+ *     scope: ({ context }) => ({ filter: ([row, p]) => row.tenantId === p.tenantId, params: context }),
+ * });
+ *
+ * app.post("/routier", async (req, res) => {
+ *     const context = { tenantId: req.user?.tenantId };   // from the REQUEST, never from the body
+ *     res.json(await handle(req.body, context));
+ * });
+ * ```
+ *
+ * ## Errors are values
+ *
+ * A failure comes back as `{ ok: false, error }` rather than as a rejected promise, so a transport
+ * cannot accidentally turn a query error into a 500 with no body. The caller decides the status.
+ */
+/** What a hook is told about the request it is judging. */
+export type RequestInfo<TContext> = {
+    action: "query" | "persist" | "destroy";
+    /** Every collection this request touches, including the inner side of any join. */
+    collectionNames: string[];
+    /** Whatever the transport built from the request — a user, a tenant, a token. Never the body. */
+    context: TContext;
+    /** The raw request, for a policy that needs to look closer. Treat it as caller-controlled input. */
+    request: SerializedRequest;
+};
+/**
+ * May this request proceed?
+ *
+ * `true` to allow. `false` or a string to refuse — a string becomes the error message, which is the
+ * cheapest way to say WHY without inventing an error type. Throwing also refuses.
+ *
+ * Called once, before deserialization, so a refused request never reaches a schema or a plugin.
+ */
+export type AuthorizeHook<TContext> = (info: RequestInfo<TContext>) => boolean | string | Promise<boolean | string>;
+/** What a scope hook is asked. One collection at a time, since each may be scoped differently. */
+export type ScopeInfo<TContext> = {
+    collectionName: string;
+    schema: CompiledSchema<any>;
+    context: TContext;
+    action: "query" | "persist";
+};
+/**
+ * The rows of one collection this caller may touch, as a filter.
+ *
+ * Written exactly like a collection's own `.scope()` — a filter, optionally with params — so the same
+ * expression is pushed into the database on reads and checked against each row on writes. Return
+ * `null` for a collection this caller may see in full.
+ *
+ * ```ts
+ * scope: ({ collectionName, context }) =>
+ *     collectionName === "orders"
+ *         ? { filter: ([row, p]) => row.tenantId === p.tenantId, params: { tenantId: context.tenantId } }
+ *         : null
+ * ```
+ */
+export type ScopeHook<TContext> = (info: ScopeInfo<TContext>) => {
+    filter: Filter<any> | ParamsFilter<any, any>;
+    params?: {};
+} | null;
+export type RequestHandlerOptions<TContext> = {
+    /** The plugin that actually holds the data. Anything implementing `IDbPlugin`. */
+    plugin: IDbPlugin;
+    /** Every collection this endpoint will answer for. A name absent from here is refused. */
+    schemas: ReadonlySchemaCollection;
+    /** May this caller do this? See `AuthorizeHook`. Absent means yes, to everyone. */
+    authorize?: AuthorizeHook<TContext>;
+    /** Which rows may this caller touch? See `ScopeHook`. Absent means all of them. */
+    scope?: ScopeHook<TContext>;
+    /**
+     * Whether a `destroy` request may drop the database. **Defaults to false.**
+     *
+     * `HttpTransportDbPlugin` never sends one, but an endpoint answers whatever arrives — and a
+     * hand-written `{"kind":"destroy"}` would otherwise wipe the store for anyone who could reach
+     * the route. Destroying a database is not something a remote caller should be able to ask for by
+     * default, so it is opt-in and still passes through `authorize`.
+     */
+    allowDestroy?: boolean;
+};
+export type RequestHandler<TContext> = (request: SerializedRequest, context: TContext) => Promise<SerializedResponse>;
+export declare const createRequestHandler: <TContext = void>(options: RequestHandlerOptions<TContext>) => RequestHandler<TContext>;
+/** Re-exported so a caller can type its own scope provider without reaching for the query module. */
+export type { ScopeProvider };

package/dist/plugins/wire/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types';
+export * from './query';
+export * from './persist';
+export * from './handler';

package/dist/plugins/wire/persist.d.ts

@@ -0,0 +1,43 @@
+import { BulkPersistChanges, BulkPersistResult } from "../../collections";
+import { CompiledSchema } from "../../schema";
+import { ReadonlySchemaCollection } from "../../collections/ReadonlySchemaCollection";
+import { SchemaResolver } from "./query";
+import { SerializedPersistRequest, SerializedResponse } from "./types";
+/**
+ * Saves, in the form that survives a wire.
+ *
+ * Simpler than a query, because a change set holds no functions: adds, updates and removes are
+ * entities, and an entity reaching a plugin has already been through `preprocess` — so it is in
+ * STORAGE shape, where a Date is already an ISO string and a nested object is already whatever the
+ * schema said to store. It is JSON by the time it gets here.
+ *
+ * Two things are deliberately left behind:
+ *
+ * - **Tags.** `SchemaPersistChanges.tags` is caller-side metadata for correlating a save with its
+ *   echo locally. The receiver has no use for it and no business seeing it.
+ * - **Schema ids.** Collections are NAMED. An id is a hash of the schema's own shape, so it would
+ *   couple both sides to identical schema definitions; a name lets the receiver resolve its own.
+ */
+export declare const serializeBulkPersist: (changes: BulkPersistChanges, schemas: ReadonlySchemaCollection) => SerializedPersistRequest;
+/**
+ * Rebuilds a change set from its wire form, keyed by the RECEIVER's schema ids.
+ *
+ * @throws when a named collection is not one this store declares. A save aimed at data this side
+ * does not have must not be silently dropped — the caller would be told it succeeded.
+ */
+export declare const deserializeBulkPersist: (request: SerializedPersistRequest, resolveSchema: SchemaResolver) => {
+    changes: BulkPersistChanges;
+    schemas: CompiledSchema<any>[];
+};
+/**
+ * Serializes the ECHO of a save — the part the change tracker cannot do without.
+ *
+ * A save's result is not a receipt. It carries the rows as the database wrote them, including any
+ * identity the database assigned, and the change tracker matches each one back to the addition that
+ * produced it. Returning a count instead would leave every inserted entity without its key.
+ */
+export declare const serializePersistResult: (result: BulkPersistResult, schemas: ReadonlySchemaCollection) => SerializedResponse;
+/** Rebuilds a save's echo against the SENDER's schema ids, which is what its change tracker holds. */
+export declare const deserializePersistResult: (response: Extract<SerializedResponse, {
+    kind: "persist";
+}>, resolveSchema: SchemaResolver) => BulkPersistResult;

package/dist/plugins/wire/query.d.ts

@@ -0,0 +1,49 @@
+import { Expression } from "../../expressions";
+import { CompiledSchema } from "../../schema";
+import { QueryOptionsCollection } from "../query/QueryOptionsCollection";
+import { SerializedQueryOption } from "./types";
+/**
+ * Splits options into the PREFIX that can be sent and the remainder that cannot.
+ *
+ * A prefix, not a filtered subset, and that is the whole correctness argument. Options are ordered,
+ * and most are not idempotent: sending `count` while keeping `map` local would count unmapped rows,
+ * and applying `take` on both sides would window twice. So the split stops at the first option that
+ * cannot travel, and everything from there on runs where the closures are.
+ *
+ * It is the same shape as the database/memory split this composes with — one more cut of the same
+ * ordered list, for one more reason.
+ */
+export declare const splitSendableOptions: <T>(options: QueryOptionsCollection<T>) => {
+    sendable: QueryOptionsCollection<T>;
+    local: QueryOptionsCollection<T>;
+};
+export declare const serializeQueryOptions: <T>(options: QueryOptionsCollection<T>) => SerializedQueryOption[];
+/** How the receiver finds a collection it was sent the NAME of. */
+export type SchemaResolver = (collectionName: string) => CompiledSchema<any> | null;
+/**
+ * A filter the RECEIVER adds to every read of a collection, whatever the sender asked for.
+ *
+ * Returns `null` for a collection with nothing to add. See `createRequestHandler` for the policy
+ * side; this is only how it reaches the options.
+ */
+export type ScopeProvider = (schema: CompiledSchema<any>) => Expression | null;
+/**
+ * Rebuilds query options from their wire form, against the receiver's own schemas.
+ *
+ * The closures that were dropped are reconstructed here rather than sent:
+ *
+ * - a **sort selector** from its property, which is all `JsonTranslator.sort` reads;
+ * - a **filter predicate** from its expression tree, via `toStrictPredicate` — which THROWS rather
+ *   than keeping a row it cannot judge, because on a receiver a filter that quietly stops filtering
+ *   returns rows the requester excluded.
+ *
+ * @throws when a named property or collection is not declared by the receiver's schemas. A payload
+ * describing data this side does not have is a disagreement, and it has to be loud.
+ */
+export declare const deserializeQueryOptions: (serialized: SerializedQueryOption[], schema: CompiledSchema<any>, resolveSchema: SchemaResolver, 
+/**
+ * A receiver-side filter per collection, applied to this collection AND to every collection a
+ * join reaches. Prepended, so it is ANDed with whatever the sender sent and there is no order of
+ * options that removes it.
+ */
+scopeFor?: ScopeProvider) => QueryOptionsCollection<any>;

package/dist/plugins/wire/types.d.ts

@@ -0,0 +1,139 @@
+import { SerializedExpression } from "../../expressions";
+import { JoinKind } from "../query/join";
+import { ExecutedQuery } from "../query/explain";
+import { QueryOrdering } from "../query/types";
+/**
+ * The wire format for a whole Routier operation.
+ *
+ * This is what makes a plugin that owns no database possible: the query itself travels, and a
+ * receiver executes it against whatever plugin IT has. Nothing here is HTTP-specific — it is plain
+ * JSON, so the same payload works over fetch, a WebSocket, a worker `postMessage`, or a queue.
+ *
+ * ## Two rules shape every type below
+ *
+ * 1. **No functions cross.** A query option carries live closures — a sort selector, a filter
+ *    predicate, a map projection — and none of them survive `JSON.stringify`. Where a closure can
+ *    be REBUILT from data it is dropped and reconstructed on arrival (a sort selector from its
+ *    property, a filter predicate from its expression tree). Where it cannot, the option does not
+ *    travel at all and the sender runs it locally; see `map` and `group`.
+ * 2. **The receiver's schema is the authority.** Collections are named, never described. A payload
+ *    says "teams", and the receiver resolves its own compiled schema for that name. Sending a
+ *    schema would let the sender decide what its properties are, which is backwards for anything
+ *    crossing a trust boundary — and it is the same reason `expressionFromJson` takes the schema
+ *    rather than reading an id out of the payload.
+ */
+/** A query option, in the form that survives a wire. */
+export type SerializedQueryOption = {
+    name: "skip";
+    value: number;
+} | {
+    name: "take";
+    value: number;
+}
+/** The selector is dropped and rebuilt from the property on arrival. */
+ | {
+    name: "sort";
+    value: {
+        propertyName: string;
+        direction: QueryOrdering;
+    };
+}
+/**
+ * The expression only — no closure and no params bag.
+ *
+ * A filter reaching a query option is already BOUND: `ParamReferenceExpression` never escapes
+ * the parser, so every param value is already a literal in the tree. The receiver rebuilds a
+ * runnable predicate from the tree with `toStrictPredicate`.
+ */
+ | {
+    name: "filter";
+    value: {
+        expression: SerializedExpression;
+    };
+} | {
+    name: "nearest";
+    value: {
+        propertyName: string;
+        vector: number[];
+        count: number;
+    };
+} | {
+    name: "join";
+    value: {
+        kind: JoinKind;
+        /** Named, not described — the receiver resolves its own schema for it. */
+        innerCollectionName: string;
+        outerKeyPath: string;
+        innerKeyPath: string;
+        innerOptions: SerializedQueryOption[];
+        semiJoinKeyThreshold: number;
+    };
+} | {
+    name: "count" | "min" | "max" | "sum" | "distinct";
+    value: true;
+};
+export type SerializedQueryRequest = {
+    kind: "query";
+    collectionName: string;
+    options: SerializedQueryOption[];
+    /**
+     * Whether the caller wants the response to say what the server ran. Required — a query is
+     * either explained or it is not. A server whose plugin does not report answers `true` the
+     * same as `false`, and the caller's explanation marks the remote step as not reported.
+     */
+    explain: boolean;
+};
+/** One entity update, as `EntityUpdateInfo` minus nothing — every field of it is already JSON. */
+export type SerializedUpdate = {
+    entity: unknown;
+    changeType: "propertiesChanged" | "markedDirty" | "notModified";
+    delta: unknown;
+    concurrency?: {
+        column: string;
+        expected: number;
+    };
+};
+export type SerializedSchemaChanges = {
+    collectionName: string;
+    adds: unknown[];
+    updates: SerializedUpdate[];
+    removes: unknown[];
+};
+export type SerializedPersistRequest = {
+    kind: "persist";
+    changes: SerializedSchemaChanges[];
+};
+export type SerializedDestroyRequest = {
+    kind: "destroy";
+};
+export type SerializedRequest = SerializedQueryRequest | SerializedPersistRequest | SerializedDestroyRequest;
+/** What a receiver sends back. Errors are a value, not a transport status. */
+export type SerializedResponse = 
+/**
+ * `executedQueries` carries what the SERVER's plugin ran, so `.explain()` on a client sees
+ * through the wire rather than reporting a blank. Optional on the response, unlike on a
+ * local event: a plugin that does not report has nothing to send, and the client's
+ * explanation then marks the remote step as not reported. There is no flag on either end —
+ * the wire forwards whatever the plugin pushed, or nothing.
+ */
+{
+    ok: true;
+    kind: "query";
+    value: unknown;
+    executedQueries?: ExecutedQuery[];
+} | {
+    ok: true;
+    kind: "persist";
+    changes: Array<{
+        collectionName: string;
+        adds: unknown[];
+        updates: unknown[];
+        removes: unknown[];
+    }>;
+} | {
+    ok: true;
+    kind: "destroy";
+} | {
+    ok: false;
+    error: string;
+};