foldkit-remote 0.18.1 → 0.20.0

package/dist/{src-Cp71fJac.mjs → src-BDqn7Ocr.mjs}

@@ -1,14 +1,14 @@
 import { Context, Data, Deferred, Duration, Effect, Layer, Match, Option, Predicate, Record, Request, RequestResolver, Result, Schema, SchemaAST, SchemaGetter, Stream } from "effect";
 import { KeyValueStore } from "effect/persistence";
 import * as Domain from "foldkit-entity";
-import { Entity, Expr, Query, QueryEvaluateError, ReadFilter, SchemaShape, SelectionTypeId, Write, compareRows, dependenciesOf, evaluate } from "foldkit-entity";
+import { Entity, Expr, Operators, Query, QueryEvaluateError, ReadFilter, SchemaShape, SelectionTypeId, Write, compareRows, dependenciesOf, evaluate } from "foldkit-entity";
 import { mapMessage } from "foldkit/command";
 import { defineMessageUnion } from "foldkit/message";
 import * as Subscription from "foldkit/subscription";
 import { Metadata } from "foldkit-surface";
 import { Rpc, RpcGroup } from "effect/rpc";
 import { defineTaggedUnion } from "foldkit/schema";
-//#region src/requirement.ts
+// src/requirement.ts
 /**
 * What a Remote Projection needs from the server: entity slices and query
 * connections. They ride on `Projection.metadata` under Remote's own keys, so
@@ -110,8 +110,7 @@ const RemoteConnections = Metadata.key("remote.connection", {
 const requirementsOf = (projection) => RemoteRequirements.get(projection.metadata);
 /** The query connections a Projection carries. */
 const connectionsOf = (projection) => RemoteConnections.get(projection.metadata);
-//#endregion
-//#region src/data.ts
+// src/data.ts
 /**
 * Whether two values the server sent are the same data: equal primitives, or
 * arrays and plain objects whose entries are. Anything else is compared by
@@ -129,8 +128,7 @@ const isPlain = (value) => {
 	const prototype = Object.getPrototypeOf(value);
 	return prototype === Object.prototype || prototype === null;
 };
-//#endregion
-//#region src/relation.ts
+// src/relation.ts
 /**
 * Relation values on the wire and in the store: a ref key (`"Entity:id"`), a
 * nullable ref key, an array of ref keys, or a page of ref keys. The planner
@@ -218,8 +216,7 @@ const shapeOf = (ast, nullable) => {
 		}
 	}
 };
-//#endregion
-//#region src/store.ts
+// src/store.ts
 /**
 * The pure entity store: values, per-field presence, staleness, and tombstones.
 *
@@ -406,8 +403,7 @@ const missingFields = (store, key, fields, windows) => {
 		return requested !== void 0 && stored !== void 0 && stored !== "" && stored !== requested;
 	});
 };
-//#endregion
-//#region src/mutation.ts
+// src/mutation.ts
 /**
 * Mutation status and idempotent reconciliation.
 *
@@ -420,6 +416,7 @@ const emptyMutationState = {
 	applied: /* @__PURE__ */ new Set(),
 	failed: /* @__PURE__ */ new Set(),
 	errors: /* @__PURE__ */ new Map(),
+	operations: /* @__PURE__ */ new Map(),
 	sequence: 0
 };
 /**
@@ -442,17 +439,20 @@ const beginMutation = (state, requestId) => ({
 	pending: /* @__PURE__ */ new Set([...state.pending, requestId]),
 	sequence: state.sequence + 1
 });
-const failMutation = (state, requestId, error) => {
+const failMutation = (state, requestId, error, operation) => {
 	const pending = new Set(state.pending);
 	pending.delete(requestId);
 	const failed = remember(state.failed, requestId);
 	const errors = new Map([...state.errors, [requestId, error]]);
+	const operations = new Map([...state.operations, [requestId, operation]]);
 	for (const id of errors.keys()) if (!failed.has(id)) errors.delete(id);
+	for (const id of operations.keys()) if (!failed.has(id)) operations.delete(id);
 	return {
 		...state,
 		pending,
 		failed,
-		errors
+		errors,
+		operations
 	};
 };
 const mutationStatus = (state, requestId) => {
@@ -487,6 +487,23 @@ const reconcileMutation = (store, state, requestId, answer) => {
 	};
 };
 const conflict = Schema.TaggedStruct("Conflict", {});
+const unmet = Schema.TaggedStruct("Unmet", {});
+/**
+* The row the write would leave breaks one of its Entity's invariants: which
+* one, what to tell the author, and the fields to show it beside. None and
+* empty when the invariant reads a member hidden from whoever asked.
+*/
+const invalid = Schema.TaggedStruct("Invalid", {
+	rule: Schema.OptionFromNullOr(Schema.String),
+	message: Schema.String,
+	path: Schema.Array(Schema.String)
+});
+const conflictOrInvalid = Schema.Union([conflict, invalid]);
+const conflictUnmetOrInvalid = Schema.Union([
+	conflict,
+	unmet,
+	invalid
+]);
 const anyField = Schema.TaggedStruct("Field", {
 	key: Schema.String,
 	reason: Schema.Unknown
@@ -500,10 +517,24 @@ const Refusal = {
 	}),
 	/** The row moved on since the client read it; the author decides what wins. */
 	conflict,
+	/** The row does not hold what the write's `when` asks of it, where it would commit. */
+	unmet,
+	/** The row the write would leave breaks an invariant of its Entity. */
+	invalid,
 	/** Whether a refusal, of whatever mutation, is a `Refusal.field`. */
 	isField: Schema.is(anyField),
 	/** Whether a refusal, of whatever mutation, is `Refusal.conflict`. */
-	isConflict: Schema.is(conflict)
+	isConflict: Schema.is(conflict),
+	/** Whether a refusal, of whatever mutation, is `Refusal.unmet`. */
+	isUnmet: Schema.is(unmet),
+	/** Whether a refusal, of whatever mutation, is `Refusal.invalid`. */
+	isInvalid: Schema.is(invalid),
+	/**
+	* Whether a refusal is `Refusal.invalid` naming this invariant: the one
+	* `Entity.invariant` returned, or one `Entity.invariants` reads. An invariant
+	* over a member hidden from the asker names none, so it matches nothing.
+	*/
+	isInvalidBy: (refusal, invariant) => Schema.is(invalid)(refusal) && Option.contains(refusal.rule, invariant.id)
 };
 /** The codec itself, or a `Schema.Struct` over the fields. */
 const schemaOf = (shape) => Schema.isSchema(shape) ? shape : Schema.Struct(shape);
@@ -525,11 +556,18 @@ const patchOfWrite = (bound) => ({
 /**
 * What a declared write shows before the server answers: an update's or an
 * insert's row as a patch (an update's only for the keys named, when some
-* are). A delete shows nothing, since no operation removes a row from every
+* are), and an update's increments as amounts over the value the store holds. A delete shows nothing, since no operation removes a row from every
 * list it is in; its answer does.
 */
 const optimisticOfWrite = (write, input, keys) => Match.value(write).pipe(Match.tagsExhaustive({
-	Update: () => [patchOfWrite(Write.bind(write, input, keys))],
+	Update: () => {
+		const bound = Write.bind(write, input, keys);
+		const patch = patchOfWrite(bound);
+		return [Object.keys(bound.increments).length === 0 ? patch : {
+			...patch,
+			adds: bound.increments
+		}];
+	},
 	Insert: () => {
 		const patch = patchOfWrite(Write.bind(write, input));
 		return [{
@@ -553,13 +591,14 @@ const Mutation = {
 	* A mutation that is a declared `Write` (`update`, `insert` or `delete`): its
 	* input is the write's, and it answers nothing but the row it changed, as a
 	* patch, or its deletion. It may be refused as a conflict, for a write that
-	* `expect`s a revision the row has moved past.
+	* `expect`s a revision the row has moved past, for a write with a `when` as
+	* unmet, and as invalid when the row it would leave breaks an invariant.
 	*/
 	write: (name, write) => ({
 		name,
 		Input: write.input.schema,
 		Output: Schema.Struct({}),
-		Refusal: Refusal.conflict,
+		Refusal: Option.isSome(write.when) ? conflictUnmetOrInvalid : conflictOrInvalid,
 		write
 	}),
 	make: (name, config) => ({
@@ -569,8 +608,7 @@ const Mutation = {
 		Refusal: config.Refusal ?? Schema.Never
 	})
 };
-//#endregion
-//#region src/query.ts
+// src/query.ts
 /**
 * Queries and connections. A connection's identity is its descriptor plus the
 * canonical encoded filter/sort input — **never** the pagination window, so
@@ -712,8 +750,7 @@ const Query$1 = {
 		}
 	})
 };
-//#endregion
-//#region src/wire.ts
+// src/wire.ts
 /**
 * The Remote wire: Effect RPC semantics over `effect/rpc`. Remote owns
 * the message shapes; Effect owns the transport. `Make`ing reads batch, mutations
@@ -822,9 +859,21 @@ const ReadBatchResult = Schema.Struct({
 	entities: Schema.Array(NormalizedEntity),
 	settled: Schema.Array(SettledFields)
 });
+/**
+* One operation's identity across every client: minted where it is first sent
+* and sent again with each retry of it. Bounded, since a server keys a record
+* of the write by it.
+*/
+const OperationId = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(128), Schema.isPattern(/^[A-Za-z0-9:._-]+$/));
 const MutationRequest = Schema.Struct({
-	/** Stable across transport retries so a mutation is not applied twice. */
+	/**
+	* This client's id for the request, the same on each retry of it. It is
+	* unique within one client's Model only (a counter there), so it names a
+	* request to that client; `operation` names it to a server.
+	*/
 	requestId: Schema.String,
+	/** The operation's identity across clients: what a server keys a record of the write by. */
+	operation: Schema.optional(OperationId),
 	mutation: Schema.String,
 	input: Schema.Unknown,
 	/** For a mutation that is a `Write`: the input keys to write, when not all of them. */
@@ -972,8 +1021,7 @@ const QueryRpc = Rpc.make("FoldkitRemoteQuery", {
 	error: Schema.Union([RemoteQueryError, RemoteUnauthenticated])
 });
 const RemoteRpc = RpcGroup.make(Read, Mutate, QueryRpc, Live);
-//#endregion
-//#region src/coalesce.ts
+// src/coalesce.ts
 /**
 * Read coalescing: every requirement a client asks for goes through one
 * `RequestResolver`, so requirements issued together become one `ReadBatch`
@@ -1097,8 +1145,7 @@ const coalesceReads = (read, options = {}) => Effect.gen(function* () {
 		};
 	}));
 });
-//#endregion
-//#region src/client.ts
+// src/client.ts
 /**
 * The transport seam: the `RemoteClient` Effect service, the RPC client it is
 * built from, the wire-to-client reconstructions, and the mutation call.
@@ -1198,18 +1245,28 @@ const coalescedLayer = (layer, options = {}) => Layer.effect(RemoteClient, Effec
 	};
 })).pipe(Layer.provide(layer));
 /**
+* A new operation's identity: random, so unique across clients and reloads.
+* `randomUUID` exists only in a secure context, so a page served over plain
+* HTTP draws 128 random bits from `getRandomValues`, which exists in all.
+*/
+const mintOperation = () => typeof globalThis.crypto.randomUUID === "function" ? globalThis.crypto.randomUUID() : Array.from(globalThis.crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(16)), (byte) => byte.toString(16).padStart(2, "0")).join("");
+/**
 * `Remote.mutate` as a standalone effect, so `Remote.mutateInto` can reuse it
 * without the object literal referencing itself.
 */
-const mutateRemote = Effect.fn("Remote.mutate")(function* (mutation, input, requestId, keys) {
+const mutateRemote = Effect.fn("Remote.mutate")(function* (mutation, input, requestId, options = {}) {
+	const { keys } = options;
+	const operation = options.operation ?? (yield* Effect.sync(mintOperation));
 	yield* Effect.annotateCurrentSpan({
 		mutation: mutation.name,
-		requestId
+		requestId,
+		operation
 	});
 	const client = yield* RemoteClient;
 	const encoded = yield* Schema.encodeUnknownEffect(mutation.Input)(input).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(new RemoteMutationError({ message: error.message }))));
 	const result = yield* client.mutate({
 		requestId,
+		operation,
 		mutation: mutation.name,
 		input: encoded,
 		...keys === void 0 ? {} : { keys }
@@ -1221,8 +1278,7 @@ const mutateRemote = Effect.fn("Remote.mutate")(function* (mutation, input, requ
 		deleted: result.deleted ?? []
 	};
 });
-//#endregion
-//#region src/connection.ts
+// src/connection.ts
 /**
 * The pure connection model: an ordered normalized structure of edges with
 * explicit known boundaries. Pages, live events, and optimistic inserts are all
@@ -1385,8 +1441,7 @@ const hasNext = (connection) => {
 };
 /** A connection with more than one segment has an explicit unknown gap. */
 const isGapped = (connection) => connection.segments.length > 1;
-//#endregion
-//#region src/selection.ts
+// src/selection.ts
 /**
 * Selections: the fields a Surface picks of an entity (nested through
 * relations, paged through connections), the requirement graph they imply,
@@ -1568,8 +1623,7 @@ const assembleRelation = (store, value, relation) => {
 		refreshing
 	};
 };
-//#endregion
-//#region src/entity.ts
+// src/entity.ts
 /**
 * Entities: the descriptor an application declares, refs, ref pages, and
 * patches, with the codecs that carry refs on the wire.
@@ -1657,8 +1711,7 @@ const Entity$1 = {
 		values: patch
 	})
 };
-//#endregion
-//#region src/placement.ts
+// src/placement.ts
 /**
 * Where one row falls in a loaded list, by the list's own declared order:
 * the decidable half of placing a row instead of fetching the list again.
@@ -1675,16 +1728,14 @@ const Entity$1 = {
 */
 const RowPlace = Data.taggedEnum();
 /**
-* The values a row holds of the fields an order reads, or none when it lacks
-* one. An `id` no Selection stored is its key's, when the id is stored as
+* The values a row holds of the fields an order reads, a call's arguments
+* included, or none when it lacks one. An `id` no Selection stored is its key's, when the id is stored as
 * text as a key holds it, so the id tie-break every order ends on does not
 * make such a row unplaceable; a number id is never compared as text.
 */
 const keysOf = (store, key, id, idIsText, terms) => {
 	const values = Object.create(null);
-	for (const term of terms) {
-		if (term.expr._tag !== "Field") return Option.none();
-		const field = term.expr.key;
+	for (const { key: field } of dependenciesOf(...terms).fields) {
 		const stored = readField(store, key, field);
 		const value = field === "id" && Option.isNone(stored) && idIsText ? id : stored;
 		if (Option.isNone(value)) return Option.none();
@@ -1694,12 +1745,12 @@ const keysOf = (store, key, id, idIsText, terms) => {
 };
 /**
 * Where the row stored under `key` falls in `connection`, by `body`'s order
-* for `input` (encoded, as a connection's identity carries it). The row's own
-* edge, if the list holds it, is left out: placing a row that moved asks
-* where it goes now.
+* for `input` (encoded, as a connection's identity carries it), a call in it
+* run by `operators`. The row's own edge, if the list holds it, is left out:
+* placing a row that moved asks where it goes now.
 */
-const placeIn = (store, connection, body, input, key) => {
-	const placement = Query.placement(body, input);
+const placeIn = (store, connection, body, input, key, operators) => {
+	const placement = Query.placement(body, input, { operators });
 	if (placement._tag === "NotPlaceable") return RowPlace.Unknown({ reason: placement.reason });
 	const terms = Query.orderFor(body, input);
 	const prefix = `${body.entity.name}:`;
@@ -1711,7 +1762,10 @@ const placeIn = (store, connection, body, input, key) => {
 	/** Negative when the row sorts before the edge; none when the edge cannot be compared. */
 	const against = (edge) => Option.flatMap(keysOf(store, entityKey(edge.ref.entity, edge.ref.id), Option.some(edge.ref.id), idIsText, terms), (values) => {
 		try {
-			return Option.some(compareRows(terms, row.value, values, body.entity.name));
+			return Option.some(compareRows(terms, row.value, values, body.entity.name, {
+				input,
+				operators
+			}));
 		} catch {
 			return Option.none();
 		}
@@ -1767,8 +1821,7 @@ const withEdge = (connection, added, place) => ({
 		};
 	})
 });
-//#endregion
-//#region src/matching.ts
+// src/matching.ts
 /**
 * Running a query body against the rows the client already holds.
 *
@@ -1855,7 +1908,7 @@ const matchingEncoded = (store, descriptor, encoded, options = {}) => {
 		});
 	}
 	return {
-		matched: evaluate(body, encoded, rows).map((row) => row.__key),
+		matched: evaluate(body, encoded, rows, { operators: options.operators }).map((row) => row.__key),
 		skipped
 	};
 };
@@ -1868,7 +1921,7 @@ const matchingEncoded = (store, descriptor, encoded, options = {}) => {
 * asymmetry with `matching`, which takes a decoded input, is the shape of the
 * two real callers rather than an oversight.
 */
-const belongsEncoded = (store, descriptor, encoded, key) => {
+const belongsEncoded = (store, descriptor, encoded, key, operators) => {
 	const entry = store[key];
 	if (entry === void 0) return "unknown";
 	if (entry.tombstone) return "no";
@@ -1876,7 +1929,10 @@ const belongsEncoded = (store, descriptor, encoded, key) => {
 	if (body !== void 0 && decidableOn(body).some((field) => entry.stale.has(field))) return "unknown";
 	let judged;
 	try {
-		judged = matchingEncoded(store, descriptor, encoded, { among: [key] });
+		judged = matchingEncoded(store, descriptor, encoded, {
+			among: [key],
+			operators
+		});
 	} catch (error) {
 		if (error instanceof QueryEvaluateError) return "unknown";
 		throw error;
@@ -1885,8 +1941,7 @@ const belongsEncoded = (store, descriptor, encoded, key) => {
 	if (judged.skipped.includes(key)) return "unknown";
 	return "no";
 };
-//#endregion
-//#region src/impact.ts
+// src/impact.ts
 /**
 * What a write did to the lists the client holds: given one change and one
 * loaded connection, whether the connection is still right as it stands.
@@ -1949,7 +2004,7 @@ const sameOrder = (left, right) => left.segments.length === right.segments.lengt
 * What `change` does to `connection`, judged against `store`, the store after
 * the write.
 */
-const impactOn = (connection, store, change) => {
+const impactOn = (connection, store, change, operators) => {
 	const { descriptor } = connection;
 	const body = descriptor.body;
 	if ((body?.entity.name ?? descriptor.Result.entity) !== change.entity) return kept;
@@ -1975,7 +2030,7 @@ const impactOn = (connection, store, change) => {
 			const refilters = touches(roles.predicate);
 			const unloaded = hasPrevious(pages) || hasNext(pages) || isGapped(pages);
 			if (!(held && reorders) && !refilters && !(!held && (created || reorders && unloaded))) return kept;
-			const belongs = held && !refilters ? "yes" : belongsEncoded(store, descriptor, connection.encoded, key);
+			const belongs = held && !refilters ? "yes" : belongsEncoded(store, descriptor, connection.encoded, key, operators);
 			if (belongs === "unknown") return Impact.Invalidated({ reason: `${key} changed a field "${descriptor.name}" filters on, and the client cannot judge it` });
 			if (!held && belongs === "no") return kept;
 			if (held && belongs === "yes" && !reorders) return kept;
@@ -1990,7 +2045,7 @@ const impactOn = (connection, store, change) => {
 				}), place);
 				return sameOrder(pages, next) ? kept : Impact.Placed({ connection: next });
 			};
-			return RowPlace.$match(placeIn(store, pages, body, connection.encoded, key), {
+			return RowPlace.$match(placeIn(store, pages, body, connection.encoded, key, operators), {
 				Before: placedAt,
 				End: placedAt,
 				Outside: () => held ? Impact.Placed({ connection: withoutEdge(pages, key) }) : kept,
@@ -1999,8 +2054,7 @@ const impactOn = (connection, store, change) => {
 		}
 	});
 };
-//#endregion
-//#region src/inspect.ts
+// src/inspect.ts
 const inspectEntry = (key, entry) => ({
 	key,
 	present: [...entry.present],
@@ -2030,8 +2084,7 @@ const inspectEntity = (model, key) => {
 	const entry = model.entities[key];
 	return entry === void 0 ? void 0 : inspectEntry(key, entry);
 };
-//#endregion
-//#region src/optimistic.ts
+// src/optimistic.ts
 /**
 * Optimistic layers. Pending changes are held as ordered layers over a base
 * store and as overlays over a connection; the visible value is recomputed, never
@@ -2137,7 +2190,7 @@ const removeOverlay = (optimistic, id) => {
 * entity only a request holds (a temporary id) is not the server's to age, and
 * is dated `Infinity`, so freshness never plans or times it.
 */
-const visibleStore = (base, optimistic) => writeEntities(base, optimistic.layers.flatMap((layer) => layer.patches.map((patch) => {
+const visibleStore = (base, optimistic) => writeEntities(base, resolvedPatches(base, optimistic).map((patch) => {
 	const key = entityKey(patch.entity, patch.id);
 	const under = base[key];
 	return {
@@ -2145,7 +2198,34 @@ const visibleStore = (base, optimistic) => writeEntities(base, optimistic.layers
 		values: patch.values,
 		updatedAt: under === void 0 || under.tombstone ? Infinity : under.updatedAt
 	};
-})));
+}));
+/**
+* Every pending patch in order, each amount added to the value under it: the
+* store's, or an earlier layer's. A prediction, so only over a number the
+* client holds: a field it has not read, or holds as anything else, keeps
+* what it shows until the server answers with the sum.
+*/
+const resolvedPatches = (base, optimistic) => {
+	const shown = /* @__PURE__ */ new Map();
+	return optimistic.layers.flatMap((layer) => layer.patches.map(({ adds, ...patch }) => {
+		const key = entityKey(patch.entity, patch.id);
+		const earlier = shown.get(key) ?? {};
+		const values = { ...patch.values };
+		const under = base[key];
+		const valueUnder = (field) => Object.hasOwn(earlier, field) ? Option.some(earlier[field]) : Option.fromUndefinedOr(under?.values[field]);
+		for (const [field, amount] of Object.entries(adds ?? {})) Option.map(Option.filter(valueUnder(field), Predicate.isNumber), (current) => {
+			values[field] = current + amount;
+		});
+		shown.set(key, {
+			...earlier,
+			...values
+		});
+		return {
+			...patch,
+			values
+		};
+	}));
+};
 /**
 * A fresh page is newer than any settled overlay it covers: an edge the page
 * carries no longer needs an insert overlay, and a `remove` overlay hiding it
@@ -2219,8 +2299,7 @@ const visibleItems = (connection, connectionId, overlays, store) => {
 		...take("append")
 	];
 };
-//#endregion
-//#region src/live.ts
+// src/live.ts
 const emptyLiveState = {
 	cursor: 0,
 	boundary: {}
@@ -2340,8 +2419,7 @@ const applyConnectionEvent = (state, optimistic, event, policy = {}) => {
 const liveHasPrevious = (connection, state, connectionId) => hasPrevious(connection) || (state.boundary[connectionId]?.before ?? 0) > 0;
 /** `hasNext` accounting for edges recorded outside the loaded boundary. */
 const liveHasNext = (connection, state, connectionId) => hasNext(connection) || (state.boundary[connectionId]?.after ?? 0) > 0;
-//#endregion
-//#region src/plan.ts
+// src/plan.ts
 /**
 * The pure requirement planner.
 *
@@ -2434,8 +2512,7 @@ const plan = (store, requirements, options = {}) => {
 	const nested = followed.length === 0 ? [] : plan(store, followed, options);
 	return [...Requirement.merge([...planned, ...nested])].sort((a, b) => entityKey(a.entity, a.id) < entityKey(b.entity, b.id) ? -1 : 1);
 };
-//#endregion
-//#region src/retain.ts
+// src/retain.ts
 /**
 * The entity keys the roots reach: each root entity, the targets its retained
 * fields refer to, and recursively the targets a nested relation selects.
@@ -2507,8 +2584,7 @@ const keptOf = (record, keep) => {
 	const kept = entries.filter(([key]) => keep(key));
 	return kept.length === entries.length ? record : Object.fromEntries(kept);
 };
-//#endregion
-//#region src/persistence.ts
+// src/persistence.ts
 /**
 * Remote cache persistence: a snapshot of the entity store and nothing else.
 * Runtime state (connections' live cursors, optimistic layers, the mutation
@@ -2705,8 +2781,7 @@ const RemotePersistence = {
 		return restored;
 	})
 };
-//#endregion
-//#region src/remoteData.ts
+// src/remoteData.ts
 /** `RemoteData`: the state of a value the store may not hold yet. */
 /**
 * The server would not answer who is asking: their session ended or was
@@ -2862,8 +2937,7 @@ const RemoteData = {
 		}
 	}
 };
-//#endregion
-//#region src/model.ts
+// src/model.ts
 /**
 * The Remote submodel: the store, connections, mutations, live state, and
 * optimistic layers an application keeps in its Model, the Messages that
@@ -2991,7 +3065,8 @@ const remoteMessageCases = {
 	},
 	MutationFailed: {
 		requestId: Schema.String,
-		error: remoteErrorSchema
+		error: remoteErrorSchema,
+		operation: Schema.String
 	},
 	OverlayShown: {
 		id: Schema.String,
@@ -3432,7 +3507,7 @@ const reduceRemote = (model, message) => {
 		}
 		case "MutationFailed": return {
 			...model,
-			mutations: failMutation(model.mutations, message.requestId, message.error),
+			mutations: failMutation(model.mutations, message.requestId, message.error, message.operation),
 			optimistic: settleFailure(model.optimistic, message.requestId)
 		};
 		case "LiveReceived": {
@@ -3749,8 +3824,7 @@ const writeRead = (store, requests, result, now = 0) => {
 	}
 	return setUnavailable(writeEntities(answered, writes, now), result.settled.map((entry) => [entityKey(entry.entity, entry.id), entry.fields]), true);
 };
-//#endregion
-//#region src/policy.ts
+// src/policy.ts
 const RemotePolicy = {
 	/** Fetch only what the store lacks. */
 	cacheFirst: { _tag: "CacheFirst" },
@@ -3779,8 +3853,7 @@ const RemotePolicy = {
 	*/
 	refreshes: (policy) => policy._tag !== "CacheFirst"
 };
-//#endregion
-//#region src/resume.ts
+// src/resume.ts
 /**
 * What of Remote's state crosses from a server render to the browser.
 *
@@ -3994,8 +4067,7 @@ const resumePart = (domain, options = {}) => ({
 		onSuccess: (capture) => Result.succeed(domain.store.set(model, restoreRemote(domain.store.get(model), capture)))
 	})
 });
-//#endregion
-//#region src/json.ts
+// src/json.ts
 /**
 * Remote's three calls as JSON: one request, `{ operation, payload }`, and one
 * answer, `{ result }` or `{ error }`. `RemoteServer.answer` is the other end.
@@ -4100,8 +4172,7 @@ const http = (url, options = {}) => json(async (request) => {
 	if (body === notJson) throw new Error(status);
 	return body;
 });
-//#endregion
-//#region src/sse.ts
+// src/sse.ts
 /**
 * Remote live over fetch with SSE framing: the other end of
 * `foldkit-remote-server/fetch`'s live open. One `POST` carries the live
@@ -4221,8 +4292,7 @@ const httpWithLive = (url, options = {}) => ({
 	...http(url, options),
 	FoldkitRemoteLive: liveFetch(url, options)
 });
-//#endregion
-//#region src/index.ts
+// src/index.ts
 /**
 * `foldkit-remote` — normalized application-facing server state.
 *
@@ -4237,7 +4307,11 @@ const explainedDependencies = (dependencies) => ({
 		key
 	})),
 	inputs: dependencies.inputs,
-	operations: dependencies.operations
+	operations: dependencies.operations,
+	operators: dependencies.operators.map(({ id, version }) => ({
+		id,
+		version
+	}))
 });
 const descriptorOf = (entity) => Entity.is(entity) ? Entity$1.from(entity) : entity;
 const selectionOf = (selection) => SelectionTypeId in selection ? Selection.from(selection) : selection;
@@ -4264,11 +4338,11 @@ const readContract = (source, shape, window) => {
 * compared with neighbours that hold those fields. What the view reads, and so
 * decodes, stays its Selection.
 */
-const placeableReadContract = (contract, body) => {
+const placeableReadContract = (contract, body, operators) => {
 	if (body === void 0) return contract;
 	const { requirement, ref } = contract;
 	const encoded = Schema.encodeSync(ref.Input)(ref.input);
-	if (Query.placement(body, encoded)._tag !== "Placeable") return contract;
+	if (Query.placement(body, encoded, { operators })._tag !== "Placeable") return contract;
 	const missing = Query.dependencies(body).fields.filter((field) => !requirement.select.fields.includes(field.key));
 	if (missing.length === 0) return contract;
 	return {
@@ -5029,7 +5103,10 @@ const Remote = {
 	* in one step; the result carries the application-facing operations. The
 	* descriptor alone is `Remote.define`, the binding alone `Remote.at`.
 	*/
-	make: (config) => bindDomain(defineRemote(config), config.model, { verifyPlacement: config.verifyPlacement }),
+	make: (config) => bindDomain(defineRemote(config), config.model, {
+		verifyPlacement: config.verifyPlacement,
+		operators: config.operators
+	}),
 	/**
 	* Declares a Remote domain without binding it: its entities, queries, and
 	* mutations, plus the submodel. For a domain reused across applications or
@@ -5391,6 +5468,7 @@ const failedReadWords = (error) => {
 };
 /** The bound domain: the descriptor, the binding, and the operations over them. */
 const bindDomain = (definition, store, options = {}) => {
+	const operators = options.operators ?? Operators.kernel;
 	const bound = bindRemote(definition, store);
 	const readers = /* @__PURE__ */ new Map();
 	const keptConnections = /* @__PURE__ */ new Set();
@@ -5423,7 +5501,7 @@ const bindDomain = (definition, store, options = {}) => {
 		const declared = (descriptor?.Result)?.live;
 		if (descriptor?.body === void 0) return declared;
 		const encoded = JSON.parse(identity.slice(identity.indexOf("\0") + 1));
-		return belongsEncoded(storeOf(bound, model), descriptor, encoded, entityKey(event.edge.ref.entity, event.edge.ref.id)) === "no" ? {
+		return belongsEncoded(storeOf(bound, model), descriptor, encoded, entityKey(event.edge.ref.entity, event.edge.ref.id), operators) === "no" ? {
 			prepend: "ignore",
 			append: "ignore"
 		} : declared;
@@ -5472,7 +5550,7 @@ const bindDomain = (definition, store, options = {}) => {
 				...query.value,
 				connection: placed,
 				holds
-			}, store, change), {
+			}, store, change, operators), {
 				Kept: () => placed,
 				Placed: ({ connection }) => connection,
 				Invalidated: () => placed
@@ -5492,7 +5570,7 @@ const bindDomain = (definition, store, options = {}) => {
 			pages,
 			layers,
 			remote.entities
-		], `placed:${identity}`, () => placedHeld(identity, pages, changesOf({ entities: layers.flatMap((layer) => layer.patches) }, remote.entities), visibleStoreOf(remote.entities, remote.optimistic)));
+		], `placed:${identity}`, () => placedHeld(identity, pages, changesOf({ entities: resolvedPatches(remote.entities, remote.optimistic) }, remote.entities), visibleStoreOf(remote.entities, remote.optimistic)));
 	};
 	/**
 	* The edges a loaded list shows: its pages with pending edits placed, and
@@ -5535,7 +5613,7 @@ const bindDomain = (definition, store, options = {}) => {
 			for (const edge of inserted.values()) {
 				if (held.has(edge.key)) continue;
 				const key = entityKey(edge.ref.entity, edge.ref.id);
-				RowPlace.$match(placeIn(store, placed, body, query.value.encoded, key), {
+				RowPlace.$match(placeIn(store, placed, body, query.value.encoded, key, operators), {
 					Before: (place) => void (placed = withEdge(placed, edge, place)),
 					End: (place) => void (placed = withEdge(placed, edge, place)),
 					Outside: () => void outside.push(edge),
@@ -5624,7 +5702,7 @@ const bindDomain = (definition, store, options = {}) => {
 					connection: pages,
 					holds
 				};
-				const after = Impact.$match(impactOn(held, visible, change), {
+				const after = Impact.$match(impactOn(held, visible, change, operators), {
 					Kept: () => Option.some(pages),
 					Placed: ({ connection }) => Option.some(connection),
 					Invalidated: () => Option.none()
@@ -5806,7 +5884,7 @@ const bindDomain = (definition, store, options = {}) => {
 			const listed = query.Result.entity;
 			if (listed === void 0) throw new Error(`Remote: query "${query.name}" is not a connection over an entity, so it has no page to select`);
 			if (select.entity !== listed) throw new Error(`Remote: the selection is of "${select.entity}", but query "${query.name}" lists "${listed}"`);
-			const { ref, relation, requirement } = placeableReadContract(readContract(query.ref(input), select, window), query.body);
+			const { ref, relation, requirement } = placeableReadContract(readContract(query.ref(input), select, window), query.body, operators);
 			const relationKey = stableStringify(relation);
 			const sizeOf = (remote) => windowSize(remote, ref);
 			const shown = (remote, connection) => cutToWindow(shownEdges(remote, ref.identity, connection), ref.window, sizeOf(remote));
@@ -6021,7 +6099,10 @@ const bindDomain = (definition, store, options = {}) => {
 			const among = (connection === void 0 ? [] : shownEdges(remote, over.ref.identity, connection)).map((edge) => entityKey(edge.ref.entity, edge.ref.id));
 			let judged;
 			try {
-				judged = matching(visible, by, input, { among });
+				judged = matching(visible, by, input, {
+					among,
+					operators
+				});
 			} catch (error) {
 				if (error instanceof QueryEvaluateError) return {
 					items: [],
@@ -6071,6 +6152,7 @@ const bindDomain = (definition, store, options = {}) => {
 			const remote = store.get(model);
 			const requestId = options.requestId ?? `${bound.contract.name}-${remote.mutations.sequence + 1}`;
 			const tempId = `${requestId}.tmp`;
+			const known = Option.fromUndefinedOr(remote.mutations.operations.get(requestId));
 			const optimistic = typeof options.optimistic === "function" ? options.optimistic({
 				requestId,
 				tempId
@@ -6087,11 +6169,15 @@ const bindDomain = (definition, store, options = {}) => {
 				command: {
 					name: `Remote.mutate(${mutation.name})`,
 					args: { requestId },
-					effect: mutateRemote(mutation, input, requestId, options.keys).pipe(Effect.match({
+					effect: Effect.flatMap(Effect.sync(() => Option.getOrElse(known, mintOperation)), (operation) => mutateRemote(mutation, input, requestId, {
+						keys: options.keys,
+						operation
+					}).pipe(Effect.match({
 						onFailure: (error) => ({
 							_tag: "MutationFailed",
 							requestId,
-							error: remoteError(error)
+							error: remoteError(error),
+							operation
 						}),
 						onSuccess: (outcome) => ({
 							_tag: "MutationSucceeded",
@@ -6101,7 +6187,7 @@ const bindDomain = (definition, store, options = {}) => {
 							deleted: outcome.deleted,
 							now: (options.now ?? wallClock)()
 						})
-					}))
+					})))
 				}
 			};
 		},
@@ -6253,7 +6339,6 @@ const pickWindow = (window) => ({
 	...window.after === void 0 ? {} : { after: window.after },
 	...window.before === void 0 ? {} : { before: window.before }
 });
-//#endregion
-export { emptyOptimistic as $, refParts as $n, QueryResult as $t, writeRead as A, schemaOf as An, RemoteClient as At, plan as B, missingFields as Bn, Live as Bt, remoteMessageCases as C, beginMutation as Cn, hasPrevious as Ct, updateRemote as D, optimisticOfWrite as Dn, segment as Dt, retentionRootsSchema as E, mutationStatus as En, merge as Et, REMOTE_CACHE_VERSION as F, hasField as Fn, remoteError as Ft, emptyLiveState as G, tombstone as Gn, MAX_RELATION_DEPTH as Gt, applyConnectionEvent as H, remove as Hn, LiveEdge as Ht, RemotePersistence as I, isFieldStale as In, coalesceQueries as It, ConnectionChange as J, RELATION_ALIAS as Jn, MutationResult as Jt, liveHasNext as K, writeEntities as Kn, Mutate as Kt, gc as L, isFieldUnavailable as Ln, coalesceReads as Lt, RemoteData as M, emptyStore as Mn, connectionChangeOf as Mt, remoteDataSchema as N, entityKey as Nn, liveEventOf as Nt, windowGrowthKey as O, patchOfWrite as On, terminal as Ot, remoteErrorSchema as P, entry as Pn, mutateRemote as Pt, connectionIdentity as Q, isRefPage as Qn, QueryRequest as Qt, reachable as R, isTombstone as Rn, requirementKey as Rt, refreshedAt as S, Refusal as Sn, hasNext as St, remoteModelSchema as T, failMutation as Tn, items as Tt, applyEntityEvent as U, setStale as Un, LiveRequirement as Ut, windowKey as V, readField as Vn, LiveChange as Vt, classifyLive as W, setUnavailable as Wn, MAX_FIELDS_PER_REQUEST as Wt, addOverlay as X, RelationEntityAnnotation as Xn, PageSize as Xt, addLayer as Y, RelationAnnotation as Yn, NormalizedEntity as Yt, beginOptimistic as Z, aliasedField as Zn, QueryEdge as Zt, isRemoteMessage as _, WireBoundary as _n, relationOf as _t, RemoteJsonAnswer as a, ReadRequest as an, RemoteRequirements as ar, visibleItems as at, overlaysOf as b, stableStringify as bn, edge as bt, emptyRefresh as c, RemoteLiveError as cn, requirementsOf as cr, inspectRemote as ct, initialRemoteModel as d, RemoteQueryError as dn, RowPlace as dt, QueryRpc as en, refsIn as er, pruneOverlays as et, invalidateConnections as f, RemoteReadError as fn, placeIn as ft, isQueryLoading as g, WindowSchema as gn, pageSchema as gt, isLoadingThrough as h, SettledFields as hn, assemble as ht, liveFetch as i, ReadBatchResult as in, RemoteConnections as ir, settleSuccess as it, Denied as j, clearStale as jn, coalescedLayer as jt, withRefreshRequested as k, reconcileMutation as kn, unknown as kt, failureOf as l, RemoteMutationError as ln, belongsEncoded as lt, isLoading as m, RemoteUnauthenticated as mn, Selection as mt, RemoteUnsatisfied as n, Read as nn, relationShape as nr, removeOverlay as nt, RemoteJsonRequest as o, RelationRequest as on, Requirement as or, visibleStore as ot, isFieldFailed as p, RemoteRpc as pn, Entity$1 as pt, liveHasPrevious as q, writeEntity as qn, MutationRequest as qt, httpWithLive as r, ReadBatch as rn, targetsOf as rr, settleFailure as rt, RemotePolicy as s, RemoteForbidden as sn, connectionsOf as sr, inspectEntity as st, Remote as t, REMOTE_PROTOCOL_VERSION as tn, relationAlias as tr, removeLayer as tt, forgetRemote as u, RemoteProtocolError as un, matching as ut, noFailures as v, IDENTITY_SEPARATOR as vn, unavailableOf as vt, remoteMessageSchema as w, emptyMutationState as wn, isGapped as wt, refreshIsInFlight as x, Mutation as xn, emptyConnection as xt, onlyOverlaid as y, Query$1 as yn, cursor as yt, deadlineOf as z, markStale as zn, ConnectionChangeSchema as zt };
+export { emptyOptimistic as $, RelationEntityAnnotation as $n, PageSize as $t, writeRead as A, optimisticOfWrite as An, unknown as At, plan as B, isFieldUnavailable as Bn, requirementKey as Bt, remoteMessageCases as C, stableStringify as Cn, hasNext as Ct, updateRemote as D, emptyMutationState as Dn, merge as Dt, retentionRootsSchema as E, beginMutation as En, items as Et, REMOTE_CACHE_VERSION as F, emptyStore as Fn, mintOperation as Ft, emptyLiveState as G, remove as Gn, LiveRequirement as Gt, applyConnectionEvent as H, markStale as Hn, Live as Ht, RemotePersistence as I, entityKey as In, mutateRemote as It, ConnectionChange as J, tombstone as Jn, Mutate as Jt, liveHasNext as K, setStale as Kn, MAX_FIELDS_PER_REQUEST as Kt, gc as L, entry as Ln, remoteError as Lt, RemoteData as M, reconcileMutation as Mn, coalescedLayer as Mt, remoteDataSchema as N, schemaOf as Nn, connectionChangeOf as Nt, windowGrowthKey as O, failMutation as On, segment as Ot, remoteErrorSchema as P, clearStale as Pn, liveEventOf as Pt, connectionIdentity as Q, RelationAnnotation as Qn, OperationId as Qt, reachable as R, hasField as Rn, coalesceQueries as Rt, refreshedAt as S, Query$1 as Sn, emptyConnection as St, remoteModelSchema as T, Refusal as Tn, isGapped as Tt, applyEntityEvent as U, missingFields as Un, LiveChange as Ut, windowKey as V, isTombstone as Vn, ConnectionChangeSchema as Vt, classifyLive as W, readField as Wn, LiveEdge as Wt, addOverlay as X, writeEntity as Xn, MutationResult as Xt, addLayer as Y, writeEntities as Yn, MutationRequest as Yt, beginOptimistic as Z, RELATION_ALIAS as Zn, NormalizedEntity as Zt, isRemoteMessage as _, RemoteUnauthenticated as _n, pageSchema as _t, RemoteJsonAnswer as a, Read as an, relationShape as ar, settleSuccess as at, overlaysOf as b, WireBoundary as bn, cursor as bt, emptyRefresh as c, ReadRequest as cn, RemoteRequirements as cr, inspectEntity as ct, initialRemoteModel as d, RemoteLiveError as dn, requirementsOf as dr, matching as dt, QueryEdge as en, aliasedField as er, pruneOverlays as et, invalidateConnections as f, RemoteMutationError as fn, RowPlace as ft, isQueryLoading as g, RemoteRpc as gn, assemble as gt, isLoadingThrough as h, RemoteReadError as hn, Selection as ht, liveFetch as i, REMOTE_PROTOCOL_VERSION as in, relationAlias as ir, settleFailure as it, Denied as j, patchOfWrite as jn, RemoteClient as jt, withRefreshRequested as k, mutationStatus as kn, terminal as kt, failureOf as l, RelationRequest as ln, Requirement as lr, inspectRemote as lt, isLoading as m, RemoteQueryError as mn, Entity$1 as mt, RemoteUnsatisfied as n, QueryResult as nn, refParts as nr, removeOverlay as nt, RemoteJsonRequest as o, ReadBatch as on, targetsOf as or, visibleItems as ot, isFieldFailed as p, RemoteProtocolError as pn, placeIn as pt, liveHasPrevious as q, setUnavailable as qn, MAX_RELATION_DEPTH as qt, httpWithLive as r, QueryRpc as rn, refsIn as rr, resolvedPatches as rt, RemotePolicy as s, ReadBatchResult as sn, RemoteConnections as sr, visibleStore as st, Remote as t, QueryRequest as tn, isRefPage as tr, removeLayer as tt, forgetRemote as u, RemoteForbidden as un, connectionsOf as ur, belongsEncoded as ut, noFailures as v, SettledFields as vn, relationOf as vt, remoteMessageSchema as w, Mutation as wn, hasPrevious as wt, refreshIsInFlight as x, IDENTITY_SEPARATOR as xn, edge as xt, onlyOverlaid as y, WindowSchema as yn, unavailableOf as yt, deadlineOf as z, isFieldStale as zn, coalesceReads as zt };
 
-//# sourceMappingURL=src-Cp71fJac.mjs.map
+//# sourceMappingURL=src-BDqn7Ocr.mjs.map