foldkit-remote 0.20.0 → 0.22.0

package/dist/connection.js

@@ -0,0 +1,170 @@
+import { entityKey } from "./store.js";
+// 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
+* evidence about one connection; `merge` is the single deterministic reducer and
+* performs no I/O.
+*
+* Optimistic overlays and live state arrive in later phases.
+*/
+const edge = (ref, key = entityKey(ref.entity, ref.id)) => ({
+	key,
+	ref
+});
+const terminal = { _tag: "Terminal" };
+const unknown = { _tag: "Unknown" };
+const cursor = (value) => ({
+	_tag: "Cursor",
+	cursor: value
+});
+const emptyConnection = {
+	segments: [],
+	stale: false
+};
+const segment = (edges, start, end) => ({
+	edges,
+	start,
+	end
+});
+const dedupeEdges = (edges) => {
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const value of edges) {
+		if (seen.has(value.key)) continue;
+		seen.add(value.key);
+		out.push(value);
+	}
+	return out;
+};
+const normalize = (segment) => ({
+	...segment,
+	edges: dedupeEdges(segment.edges)
+});
+/** Longest suffix of `a` that is a prefix of `b`, matched by edge identity. */
+const overlapLength = (a, b) => {
+	const most = Math.min(a.length, b.length);
+	for (let length = most; length > 0; length--) {
+		let matches = true;
+		for (let i = 0; i < length; i++) if (a[a.length - length + i].key !== b[i].key) {
+			matches = false;
+			break;
+		}
+		if (matches) return length;
+	}
+	return 0;
+};
+const cursorJoinable = (a, b) => a._tag === "Cursor" && b._tag === "Cursor" && a.cursor === b.cursor;
+/** Joins `a` immediately before `b`, or returns `undefined` when they are not contiguous. */
+const join = (a, b) => {
+	if (cursorJoinable(a.end, b.start)) return {
+		edges: dedupeEdges([...a.edges, ...b.edges]),
+		start: a.start,
+		end: b.end
+	};
+	if (overlapLength(a.edges, b.edges) > 0) return {
+		edges: dedupeEdges([...a.edges, ...b.edges]),
+		start: a.start,
+		end: b.end
+	};
+};
+/**
+* Global by edge identity: an edge appears once per connection. Dropping a
+* shared edge from the middle of a segment would otherwise imply that its
+* surviving neighbours are adjacent, so a segment with holes is split at each
+* hole and the new inner boundaries are `Unknown`.
+*/
+const dedupeConnection = (segments) => {
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const segmentValue of segments) {
+		const runs = [];
+		let run = [];
+		for (const edgeValue of segmentValue.edges) {
+			if (seen.has(edgeValue.key)) {
+				if (run.length > 0) {
+					runs.push(run);
+					run = [];
+				}
+				continue;
+			}
+			seen.add(edgeValue.key);
+			run.push(edgeValue);
+		}
+		if (run.length > 0) runs.push(run);
+		if (runs.length === 0) continue;
+		if (runs.length === 1) {
+			out.push({
+				...segmentValue,
+				edges: runs[0]
+			});
+			continue;
+		}
+		runs.forEach((edges, index) => {
+			out.push({
+				edges,
+				start: index === 0 ? segmentValue.start : unknown,
+				end: index === runs.length - 1 ? segmentValue.end : unknown
+			});
+		});
+	}
+	return out;
+};
+/** Adds a page to the connection, joining contiguous or overlapping segments. */
+const merge = (current, page) => {
+	const incoming = normalize(page);
+	if (incoming.edges.length === 0) return incoming.start._tag === "Terminal" && incoming.end._tag === "Terminal" && current.segments.length === 0 ? {
+		...current,
+		segments: [incoming]
+	} : current;
+	const segments = [...current.segments.map(normalize), incoming];
+	let joined = true;
+	while (joined) {
+		joined = false;
+		outer: for (let i = 0; i < segments.length; i++) for (let j = 0; j < segments.length; j++) {
+			if (i === j) continue;
+			const result = join(segments[i], segments[j]);
+			if (result === void 0) continue;
+			segments[i] = result;
+			segments.splice(j, 1);
+			joined = true;
+			break outer;
+		}
+	}
+	return {
+		...current,
+		segments: orderSegments(dedupeConnection(segments))
+	};
+};
+/**
+* Disjoint segments have no cursor linking them, so their relative order is
+* whatever it was; the two exceptions are known: a segment starting at the
+* terminal boundary is first, one ending at it is last.
+*/
+const orderSegments = (segments) => {
+	const first = segments.filter((value) => value.start._tag === "Terminal");
+	const last = segments.filter((value) => value.end._tag === "Terminal" && !first.includes(value));
+	const middle = segments.filter((value) => !first.includes(value) && !last.includes(value));
+	return [
+		...first,
+		...middle,
+		...last
+	];
+};
+/** Visible edges, segment by segment. */
+const items = (connection) => connection.segments.flatMap((value) => value.edges);
+/** There is more before the known region. Derived from boundaries, never row count. */
+const hasPrevious = (connection) => {
+	const first = connection.segments[0];
+	return first !== void 0 && first.start._tag !== "Terminal";
+};
+/** There is more after the known region. Derived from boundaries, never row count. */
+const hasNext = (connection) => {
+	const last = connection.segments[connection.segments.length - 1];
+	return last !== void 0 && last.end._tag !== "Terminal";
+};
+/** A connection with more than one segment has an explicit unknown gap. */
+const isGapped = (connection) => connection.segments.length > 1;
+export { cursor, edge, emptyConnection, hasNext, hasPrevious, isGapped, items, merge, segment, terminal, unknown };
+
+//# sourceMappingURL=connection.js.map

package/dist/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","names":[],"sources":["../src/connection.ts"],"sourcesContent":["/**\n * The pure connection model: an ordered normalized structure of edges with\n * explicit known boundaries. Pages, live events, and optimistic inserts are all\n * evidence about one connection; `merge` is the single deterministic reducer and\n * performs no I/O.\n *\n * Optimistic overlays and live state arrive in later phases.\n */\nimport { entityKey } from './store.js'\n\nexport interface EdgeRef {\n  readonly entity: string\n  readonly id: string\n}\n\n/** `key` is the edge identity used for de-duplication. */\nexport interface Edge {\n  readonly key: string\n  readonly ref: EdgeRef\n}\n\nexport const edge = (ref: EdgeRef, key: string = entityKey(ref.entity, ref.id)): Edge => ({\n  key,\n  ref,\n})\n\nexport type Cursor = string\n\nexport type Boundary =\n  | { readonly _tag: 'Terminal' }\n  | { readonly _tag: 'Cursor'; readonly cursor: Cursor }\n  | { readonly _tag: 'Unknown' }\n\nexport const terminal: Boundary = { _tag: 'Terminal' }\nexport const unknown: Boundary = { _tag: 'Unknown' }\nexport const cursor = (value: Cursor): Boundary => ({ _tag: 'Cursor', cursor: value })\n\nexport interface Segment {\n  readonly edges: readonly Edge[]\n  readonly start: Boundary\n  readonly end: Boundary\n}\n\nexport interface Connection {\n  readonly segments: readonly Segment[]\n  readonly stale: boolean\n}\n\nexport const emptyConnection: Connection = { segments: [], stale: false }\n\nexport const segment = (edges: readonly Edge[], start: Boundary, end: Boundary): Segment => ({\n  edges,\n  start,\n  end,\n})\n\nconst dedupeEdges = (edges: readonly Edge[]): Edge[] => {\n  const seen = new Set<string>()\n  const out: Edge[] = []\n  for (const value of edges) {\n    if (seen.has(value.key)) continue\n    seen.add(value.key)\n    out.push(value)\n  }\n  return out\n}\n\nconst normalize = (segment: Segment): Segment => ({ ...segment, edges: dedupeEdges(segment.edges) })\n\n/** Longest suffix of `a` that is a prefix of `b`, matched by edge identity. */\nconst overlapLength = (a: readonly Edge[], b: readonly Edge[]): number => {\n  const most = Math.min(a.length, b.length)\n  for (let length = most; length > 0; length--) {\n    let matches = true\n    for (let i = 0; i < length; i++) {\n      if (a[a.length - length + i]!.key !== b[i]!.key) {\n        matches = false\n        break\n      }\n    }\n    if (matches) return length\n  }\n  return 0\n}\n\nconst cursorJoinable = (a: Boundary, b: Boundary): boolean =>\n  a._tag === 'Cursor' && b._tag === 'Cursor' && a.cursor === b.cursor\n\n/** Joins `a` immediately before `b`, or returns `undefined` when they are not contiguous. */\nconst join = (a: Segment, b: Segment): Segment | undefined => {\n  if (cursorJoinable(a.end, b.start)) {\n    return { edges: dedupeEdges([...a.edges, ...b.edges]), start: a.start, end: b.end }\n  }\n  const overlap = overlapLength(a.edges, b.edges)\n  if (overlap > 0) {\n    return {\n      edges: dedupeEdges([...a.edges, ...b.edges]),\n      start: a.start,\n      end: b.end,\n    }\n  }\n  return undefined\n}\n\n/**\n * Global by edge identity: an edge appears once per connection. Dropping a\n * shared edge from the middle of a segment would otherwise imply that its\n * surviving neighbours are adjacent, so a segment with holes is split at each\n * hole and the new inner boundaries are `Unknown`.\n */\nconst dedupeConnection = (segments: readonly Segment[]): Segment[] => {\n  const seen = new Set<string>()\n  const out: Segment[] = []\n  for (const segmentValue of segments) {\n    const runs: Edge[][] = []\n    let run: Edge[] = []\n    for (const edgeValue of segmentValue.edges) {\n      if (seen.has(edgeValue.key)) {\n        if (run.length > 0) {\n          runs.push(run)\n          run = []\n        }\n        continue\n      }\n      seen.add(edgeValue.key)\n      run.push(edgeValue)\n    }\n    if (run.length > 0) runs.push(run)\n    if (runs.length === 0) continue\n    if (runs.length === 1) {\n      out.push({ ...segmentValue, edges: runs[0]! })\n      continue\n    }\n    runs.forEach((edges, index) => {\n      out.push({\n        edges,\n        start: index === 0 ? segmentValue.start : unknown,\n        end: index === runs.length - 1 ? segmentValue.end : unknown,\n      })\n    })\n  }\n  return out\n}\n\n/** Adds a page to the connection, joining contiguous or overlapping segments. */\nexport const merge = (current: Connection, page: Segment): Connection => {\n  // A zero-edge page carries no ordering evidence; joining it would let its\n  // boundary overwrite a real segment's end. Ignore it, unless it is the whole\n  // list and nothing is held: then it is the evidence that the list is empty,\n  // which placing a created row by the list's order needs. A later page drops\n  // it, as `dedupeConnection` keeps no segment without edges.\n  const incoming = normalize(page)\n  if (incoming.edges.length === 0) {\n    const whole = incoming.start._tag === 'Terminal' && incoming.end._tag === 'Terminal'\n    return whole && current.segments.length === 0 ? { ...current, segments: [incoming] } : current\n  }\n\n  const segments = [...current.segments.map(normalize), incoming]\n  let joined = true\n  while (joined) {\n    joined = false\n    outer: for (let i = 0; i < segments.length; i++) {\n      for (let j = 0; j < segments.length; j++) {\n        if (i === j) continue\n        const result = join(segments[i]!, segments[j]!)\n        if (result === undefined) continue\n        segments[i] = result\n        segments.splice(j, 1)\n        joined = true\n        break outer\n      }\n    }\n  }\n  return { ...current, segments: orderSegments(dedupeConnection(segments)) }\n}\n\n/**\n * Disjoint segments have no cursor linking them, so their relative order is\n * whatever it was; the two exceptions are known: a segment starting at the\n * terminal boundary is first, one ending at it is last.\n */\nconst orderSegments = (segments: readonly Segment[]): Segment[] => {\n  const first = segments.filter(value => value.start._tag === 'Terminal')\n  const last = segments.filter(value => value.end._tag === 'Terminal' && !first.includes(value))\n  const middle = segments.filter(value => !first.includes(value) && !last.includes(value))\n  return [...first, ...middle, ...last]\n}\n\n/** Visible edges, segment by segment. */\nexport const items = (connection: Connection): ReadonlyArray<Edge> =>\n  connection.segments.flatMap(value => value.edges)\n\n/** There is more before the known region. Derived from boundaries, never row count. */\nexport const hasPrevious = (connection: Connection): boolean => {\n  const first = connection.segments[0]\n  return first !== undefined && first.start._tag !== 'Terminal'\n}\n\n/** There is more after the known region. Derived from boundaries, never row count. */\nexport const hasNext = (connection: Connection): boolean => {\n  const last = connection.segments[connection.segments.length - 1]\n  return last !== undefined && last.end._tag !== 'Terminal'\n}\n\n/** A connection with more than one segment has an explicit unknown gap. */\nexport const isGapped = (connection: Connection): boolean => connection.segments.length > 1\n"],"mappings":"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"}

package/dist/data.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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
+ * identity.
+ */
+export declare const sameData: (left: unknown, right: unknown) => boolean;
+//# sourceMappingURL=data.d.ts.map

package/dist/data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data.d.ts","names":[],"sources":["../src/data.ts"],"mappings":";;;;;qBAKa,WAAQ,eAAiB"}

package/dist/data.js

@@ -0,0 +1,21 @@
+// 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
+* identity.
+*/
+const sameData = (left, right) => {
+	if (Object.is(left, right)) return true;
+	if (typeof left !== "object" || typeof right !== "object" || left === null || right === null) return false;
+	if (Array.isArray(left)) return Array.isArray(right) && left.length === right.length && left.every((item, index) => sameData(item, right[index]));
+	if (!isPlain(left) || !isPlain(right)) return false;
+	const keys = Object.keys(left);
+	return keys.length === Object.keys(right).length && keys.every((key) => Object.hasOwn(right, key) && sameData(left[key], right[key]));
+};
+const isPlain = (value) => {
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+};
+export { sameData };
+
+//# sourceMappingURL=data.js.map

package/dist/data.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data.js","names":[],"sources":["../src/data.ts"],"sourcesContent":["/**\n * Whether two values the server sent are the same data: equal primitives, or\n * arrays and plain objects whose entries are. Anything else is compared by\n * identity.\n */\nexport const sameData = (left: unknown, right: unknown): boolean => {\n  if (Object.is(left, right)) return true\n  if (typeof left !== 'object' || typeof right !== 'object' || left === null || right === null) {\n    return false\n  }\n  if (Array.isArray(left)) {\n    return (\n      Array.isArray(right) &&\n      left.length === right.length &&\n      left.every((item, index) => sameData(item, right[index]))\n    )\n  }\n  if (!isPlain(left) || !isPlain(right)) return false\n  const keys = Object.keys(left)\n  return (\n    keys.length === Object.keys(right).length &&\n    keys.every(\n      key =>\n        Object.hasOwn(right, key) &&\n        sameData((left as Record<string, unknown>)[key], (right as Record<string, unknown>)[key]),\n    )\n  )\n}\n\nconst isPlain = (value: object): boolean => {\n  const prototype = Object.getPrototypeOf(value)\n  return prototype === Object.prototype || prototype === null\n}\n"],"mappings":";;;;;;AAKA,MAAa,YAAY,MAAe,UAA4B;CAClE,IAAI,OAAO,GAAG,MAAM,KAAK,GAAG,OAAO;CACnC,IAAI,OAAO,SAAS,YAAY,OAAO,UAAU,YAAY,SAAS,QAAQ,UAAU,MACtF,OAAO;CAET,IAAI,MAAM,QAAQ,IAAI,GACpB,OACE,MAAM,QAAQ,KAAK,KACnB,KAAK,WAAW,MAAM,UACtB,KAAK,OAAO,MAAM,UAAU,SAAS,MAAM,MAAM,MAAM,CAAC;CAG5D,IAAI,CAAC,QAAQ,IAAI,KAAK,CAAC,QAAQ,KAAK,GAAG,OAAO;CAC9C,MAAM,OAAO,OAAO,KAAK,IAAI;CAC7B,OACE,KAAK,WAAW,OAAO,KAAK,KAAK,CAAC,CAAC,UACnC,KAAK,OACH,QACE,OAAO,OAAO,OAAO,GAAG,KACxB,SAAU,KAAiC,MAAO,MAAkC,IAAI,CAC5F;AAEJ;AAEA,MAAM,WAAW,UAA2B;CAC1C,MAAM,YAAY,OAAO,eAAe,KAAK;CAC7C,OAAO,cAAc,OAAO,aAAa,cAAc;AACzD"}

package/dist/diagnostics-DHhVYflV.d.ts

@@ -0,0 +1,125 @@
+import { i as RemoteError } from "./remoteData-mK1suYi1.js";
+import { Data, Option } from "effect";
+import { Diagnostic } from "foldkit-surface";
+/**
+ * Which part of a prediction the server's answer disagreed with. `Value`: a
+ * field a pending write showed, answered with another value. `Placement`: a
+ * list the client placed rows in, which the server's first page lists
+ * otherwise. `Gap`: a row whose answer left out fields the client showed,
+ * so they are read again and the row reads `Loading` meanwhile.
+ */
+type PredictionPart = Data.TaggedEnum<{
+  Value: {
+    /** The request the answer settled, as `Data.mutate` returned it. */
+    readonly requestId: string;
+    /** The mutation's name, when the request was started with one (`Data.mutate` always is). */
+    readonly mutation: Option.Option<string>;
+    readonly entity: string;
+    readonly id: string;
+    readonly field: string;
+    /** What the client showed while the write was pending, encoded. */
+    readonly shown: unknown;
+    /** What the answer holds, encoded. */
+    readonly answered: unknown;
+  };
+  Placement: {
+    readonly connection: string;
+    /** The keys as placed, as far as the server's page reached. */
+    readonly placed: ReadonlyArray<string>;
+    /** The keys of the server's first page. */
+    readonly served: ReadonlyArray<string>;
+  };
+  Gap: {
+    readonly requestId: string;
+    readonly mutation: Option.Option<string>;
+    readonly entity: string;
+    readonly id: string;
+    /** The fields shown and not answered, which the store does not otherwise hold. */
+    readonly fields: ReadonlyArray<string>;
+  };
+}>;
+declare const PredictionPart: Data.TaggedEnum.Constructor<{
+  readonly _tag: "Gap";
+  readonly requestId: string;
+  readonly mutation: Option.Option<string>;
+  readonly entity: string;
+  readonly id: string;
+  readonly fields: ReadonlyArray<string>;
+} | {
+  readonly _tag: "Placement";
+  readonly connection: string;
+  readonly placed: ReadonlyArray<string>;
+  readonly served: ReadonlyArray<string>;
+} | {
+  readonly _tag: "Value";
+  readonly requestId: string;
+  readonly mutation: Option.Option<string>;
+  readonly entity: string;
+  readonly id: string;
+  readonly field: string;
+  readonly shown: unknown;
+  readonly answered: unknown;
+}>;
+/**
+ * Under `verifyPredictions`, a part the client predicted that the server's
+ * answer disagreed with: where the client's evaluation is not unknown, it
+ * should equal the server's (operations-phase6-DESIGN §2).
+ */
+interface PredictionMismatch extends Diagnostic {
+  readonly _tag: 'PredictionMismatch';
+  readonly part: PredictionPart;
+}
+/**
+ * A write that failed while the application's own `update` does not receive
+ * `MutationFailed`: its optimistic change went, and nothing answered it.
+ */
+interface WriteUnheard extends Diagnostic {
+  readonly _tag: 'WriteUnheard';
+  readonly requestId: string;
+  readonly mutation: Option.Option<string>;
+  readonly error: RemoteError;
+}
+/**
+ * A live stream the server refused for what it asks (`RemoteLiveRefused`):
+ * more rows of one Entity than its `maxIdsPerEntity`. It is not reopened
+ * until what it asks changes, so those rows are not live meanwhile.
+ */
+interface LiveRefused extends Diagnostic {
+  readonly _tag: 'LiveRefused';
+  /** The stream's key, as `Data.liveStatus` and the Model's `streams` name it. */
+  readonly stream: string;
+  readonly error: RemoteError;
+}
+/**
+ * A durable write the outbox read back and cannot send: stored by a version
+ * of the application that registered a Mutation this one lacks, or whose
+ * input this one's `Input` no longer decodes. It is kept, shown no layer and
+ * never sent, and the writes after it are sent.
+ */
+interface OutboxUnreadable extends Diagnostic {
+  readonly _tag: 'OutboxUnreadable';
+  /** Its operation id, which `Data.dismiss` takes. */
+  readonly requestId: string;
+  readonly reason: string;
+}
+/**
+ * The outbox could not write its store (it is full, or the browser refuses
+ * storage): its writes are still sent, but a reload before they are answered
+ * loses them.
+ */
+interface OutboxUnsaved extends Diagnostic {
+  readonly _tag: 'OutboxUnsaved';
+  readonly key: string;
+  readonly reason: string;
+}
+/** Every diagnostic Remote's client records. */
+type RemoteDiagnostic = LiveRefused | OutboxUnreadable | OutboxUnsaved | PredictionMismatch | WriteUnheard;
+declare const predictionMismatch: (part: PredictionPart) => PredictionMismatch;
+declare const writeUnheard: (facts: Pick<WriteUnheard, 'requestId' | 'mutation' | 'error'>) => WriteUnheard;
+declare const liveRefused: (facts: Pick<LiveRefused, 'stream' | 'error'>) => LiveRefused;
+declare const outboxUnreadable: (facts: Pick<OutboxUnreadable, 'requestId' | 'reason'>) => OutboxUnreadable;
+declare const outboxUnsaved: (facts: Pick<OutboxUnsaved, 'key' | 'reason'>) => OutboxUnsaved;
+/** `kept` with `recorded` after it, within the window; `kept` itself when nothing was recorded. */
+declare const withDiagnostics: (kept: ReadonlyArray<RemoteDiagnostic>, recorded: ReadonlyArray<RemoteDiagnostic>) => ReadonlyArray<RemoteDiagnostic>;
+export { PredictionPart as a, liveRefused as c, predictionMismatch as d, withDiagnostics as f, PredictionMismatch as i, outboxUnreadable as l, OutboxUnreadable as n, RemoteDiagnostic as o, writeUnheard as p, OutboxUnsaved as r, WriteUnheard as s, LiveRefused as t, outboxUnsaved as u };
+//# sourceMappingURL=diagnostics-DHhVYflV.d.ts.map

package/dist/diagnostics-DHhVYflV.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics-DHhVYflV.d.ts","names":[],"sources":["../src/diagnostics.ts"],"mappings":";;;;;;;;;;KAoBY,iBAAiB,KAAK;EAChC;;aAEW;;aAEA,UAAU,OAAO;aACjB;aACA;aACA;;aAEA;;aAEA;;EAEX;aACW;;aAEA,QAAQ;;aAER,QAAQ;;EAEnB;aACW;aACA,UAAU,OAAO;aACjB;aACA;;aAEA,QAAQ;;;cAGR,gBAAc,KAAA,WAAA;;WARH;WACD,UAAA,OAAO;WACT;WACJ;WAEI,QAAA;;;WAZI;WAEJ,QAAA;WAEA,QAAA;;;WAhBG;WAED,UAAA,OAAO;WACT;WACJ;WACG;WAEA;WAEG;;;;;;;UAyBN,2BAA2B;WACjC;WACA,MAAM;;;;;;UAOA,qBAAqB;WAC3B;WACA;WACA,UAAU,OAAO;WACjB,OAAO;;;;;;;UAQD,oBAAoB;WAC1B;;WAEA;WACA,OAAO;;;;;;;;UASD,yBAAyB;WAC/B;;WAEA;WACA;;;;;;;UAQM,sBAAsB;WAC5B;WACA;WACA;;;KAIC,mBACR,cACA,mBACA,gBACA,qBACA;cAUS,qBAAkB,MAAU,mBAAiB;cAe7C,eAAY,OAChB,KAAK,sDACX;cAQU,cAAW,OAAW,KAAK,qCAAmC;cAQ9D,mBAAgB,OACpB,KAAK,8CACX;cAQU,gBAAa,OAAW,KAAK,qCAAmC;;cAehE,kBAAe,MACpB,cAAc,mBAAiB,UAC3B,cAAc,sBACvB,cAAc"}

package/dist/diagnostics.d.ts

@@ -0,0 +1,2 @@
+import { a as PredictionPart, c as liveRefused, d as predictionMismatch, f as withDiagnostics, i as PredictionMismatch, l as outboxUnreadable, n as OutboxUnreadable, o as RemoteDiagnostic, p as writeUnheard, r as OutboxUnsaved, s as WriteUnheard, t as LiveRefused, u as outboxUnsaved } from "./diagnostics-DHhVYflV.js";
+export { LiveRefused, OutboxUnreadable, OutboxUnsaved, PredictionMismatch, PredictionPart, RemoteDiagnostic, WriteUnheard, liveRefused, outboxUnreadable, outboxUnsaved, predictionMismatch, withDiagnostics, writeUnheard };

package/dist/diagnostics.js

@@ -0,0 +1,60 @@
+import { Data, Option } from "effect";
+// src/diagnostics.ts
+/**
+* What Remote's client meets and keeps going past, as diagnostics: a
+* prediction the server's answer disagreed with (`verifyPredictions`), a
+* failed write the application does not hear, and a live stream refused. The
+* reducer records each in the Model's `diagnostics`; the wiring and
+* `Remote.fold` report what an update recorded.
+*/
+const source = "foldkit-remote";
+const PredictionPart = Data.taggedEnum();
+const named = (mutation, requestId) => Option.match(mutation, {
+	onNone: () => `Request ${requestId}`,
+	onSome: (name) => `${name} (request ${requestId})`
+});
+const shownAs = (value) => JSON.stringify(value) ?? String(value);
+const predictionMismatch = (part) => ({
+	_tag: "PredictionMismatch",
+	source,
+	level: "warning",
+	message: PredictionPart.$match(part, {
+		Value: (facts) => `${named(facts.mutation, facts.requestId)} showed ${facts.entity}:${facts.id}.${facts.field} as ${shownAs(facts.shown)} while it was pending, and the server answered ${shownAs(facts.answered)}: the client's prediction and the server's write disagree.`,
+		Placement: (facts) => `The client placed rows in ${facts.connection} as [${facts.placed.join(", ")}], and the server's first page lists [${facts.served.join(", ")}]: the client's order and the server's disagree.`,
+		Gap: (facts) => `${named(facts.mutation, facts.requestId)} answered ${facts.entity}:${facts.id} without ${facts.fields.join(", ")}, which the client showed while it was pending. They are read again, so the row reads Loading meanwhile: answer with them, or select fewer.`
+	}),
+	part
+});
+const writeUnheard = (facts) => ({
+	_tag: "WriteUnheard",
+	source,
+	level: "warning",
+	message: `${named(facts.mutation, facts.requestId)} failed (${facts.error._tag}: ${facts.error.message}) and the application's update does not hear it, so its change went with no word. Share MutationFailed (Data.wiring(actives, { shared: ['MutationFailed'] })) and show Data.failedWrites.`,
+	...facts
+});
+const liveRefused = (facts) => ({
+	_tag: "LiveRefused",
+	source,
+	level: "warning",
+	message: `The server refused a live stream (${facts.error.message}), so what it asks is not live and is not asked again until it changes. Watch fewer rows at once, or raise the server's maxIdsPerEntity.`,
+	...facts
+});
+const outboxUnreadable = (facts) => ({
+	_tag: "OutboxUnreadable",
+	source,
+	level: "warning",
+	message: `A stored write (${facts.requestId}) cannot be sent: ${facts.reason}. It was made by an earlier version of the application; it is kept until Data.dismiss, and the writes after it are sent.`,
+	...facts
+});
+const outboxUnsaved = (facts) => ({
+	_tag: "OutboxUnsaved",
+	source,
+	level: "warning",
+	message: `The outbox could not write ${facts.key} (${facts.reason}). Its writes are sent, but a reload before they are answered loses them.`,
+	...facts
+});
+/** `kept` with `recorded` after it, within the window; `kept` itself when nothing was recorded. */
+const withDiagnostics = (kept, recorded) => recorded.length === 0 ? kept : [...kept, ...recorded].slice(-256);
+export { PredictionPart, liveRefused, outboxUnreadable, outboxUnsaved, predictionMismatch, withDiagnostics, writeUnheard };
+
+//# sourceMappingURL=diagnostics.js.map

package/dist/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","names":[],"sources":["../src/diagnostics.ts"],"sourcesContent":["/**\n * What Remote's client meets and keeps going past, as diagnostics: a\n * prediction the server's answer disagreed with (`verifyPredictions`), a\n * failed write the application does not hear, and a live stream refused. The\n * reducer records each in the Model's `diagnostics`; the wiring and\n * `Remote.fold` report what an update recorded.\n */\nimport { Data, Option } from 'effect'\nimport type { Diagnostic } from 'foldkit-surface'\nimport type { RemoteError } from './remoteData.js'\n\nconst source = 'foldkit-remote'\n\n/**\n * Which part of a prediction the server's answer disagreed with. `Value`: a\n * field a pending write showed, answered with another value. `Placement`: a\n * list the client placed rows in, which the server's first page lists\n * otherwise. `Gap`: a row whose answer left out fields the client showed,\n * so they are read again and the row reads `Loading` meanwhile.\n */\nexport type PredictionPart = Data.TaggedEnum<{\n  Value: {\n    /** The request the answer settled, as `Data.mutate` returned it. */\n    readonly requestId: string\n    /** The mutation's name, when the request was started with one (`Data.mutate` always is). */\n    readonly mutation: Option.Option<string>\n    readonly entity: string\n    readonly id: string\n    readonly field: string\n    /** What the client showed while the write was pending, encoded. */\n    readonly shown: unknown\n    /** What the answer holds, encoded. */\n    readonly answered: unknown\n  }\n  Placement: {\n    readonly connection: string\n    /** The keys as placed, as far as the server's page reached. */\n    readonly placed: ReadonlyArray<string>\n    /** The keys of the server's first page. */\n    readonly served: ReadonlyArray<string>\n  }\n  Gap: {\n    readonly requestId: string\n    readonly mutation: Option.Option<string>\n    readonly entity: string\n    readonly id: string\n    /** The fields shown and not answered, which the store does not otherwise hold. */\n    readonly fields: ReadonlyArray<string>\n  }\n}>\nexport const PredictionPart = Data.taggedEnum<PredictionPart>()\n\n/**\n * Under `verifyPredictions`, a part the client predicted that the server's\n * answer disagreed with: where the client's evaluation is not unknown, it\n * should equal the server's (operations-phase6-DESIGN §2).\n */\nexport interface PredictionMismatch extends Diagnostic {\n  readonly _tag: 'PredictionMismatch'\n  readonly part: PredictionPart\n}\n\n/**\n * A write that failed while the application's own `update` does not receive\n * `MutationFailed`: its optimistic change went, and nothing answered it.\n */\nexport interface WriteUnheard extends Diagnostic {\n  readonly _tag: 'WriteUnheard'\n  readonly requestId: string\n  readonly mutation: Option.Option<string>\n  readonly error: RemoteError\n}\n\n/**\n * A live stream the server refused for what it asks (`RemoteLiveRefused`):\n * more rows of one Entity than its `maxIdsPerEntity`. It is not reopened\n * until what it asks changes, so those rows are not live meanwhile.\n */\nexport interface LiveRefused extends Diagnostic {\n  readonly _tag: 'LiveRefused'\n  /** The stream's key, as `Data.liveStatus` and the Model's `streams` name it. */\n  readonly stream: string\n  readonly error: RemoteError\n}\n\n/**\n * A durable write the outbox read back and cannot send: stored by a version\n * of the application that registered a Mutation this one lacks, or whose\n * input this one's `Input` no longer decodes. It is kept, shown no layer and\n * never sent, and the writes after it are sent.\n */\nexport interface OutboxUnreadable extends Diagnostic {\n  readonly _tag: 'OutboxUnreadable'\n  /** Its operation id, which `Data.dismiss` takes. */\n  readonly requestId: string\n  readonly reason: string\n}\n\n/**\n * The outbox could not write its store (it is full, or the browser refuses\n * storage): its writes are still sent, but a reload before they are answered\n * loses them.\n */\nexport interface OutboxUnsaved extends Diagnostic {\n  readonly _tag: 'OutboxUnsaved'\n  readonly key: string\n  readonly reason: string\n}\n\n/** Every diagnostic Remote's client records. */\nexport type RemoteDiagnostic =\n  | LiveRefused\n  | OutboxUnreadable\n  | OutboxUnsaved\n  | PredictionMismatch\n  | WriteUnheard\n\nconst named = (mutation: Option.Option<string>, requestId: string): string =>\n  Option.match(mutation, {\n    onNone: () => `Request ${requestId}`,\n    onSome: name => `${name} (request ${requestId})`,\n  })\n\nconst shownAs = (value: unknown): string => JSON.stringify(value) ?? String(value)\n\nexport const predictionMismatch = (part: PredictionPart): PredictionMismatch => ({\n  _tag: 'PredictionMismatch',\n  source,\n  level: 'warning',\n  message: PredictionPart.$match(part, {\n    Value: facts =>\n      `${named(facts.mutation, facts.requestId)} showed ${facts.entity}:${facts.id}.${facts.field} as ${shownAs(facts.shown)} while it was pending, and the server answered ${shownAs(facts.answered)}: the client's prediction and the server's write disagree.`,\n    Placement: facts =>\n      `The client placed rows in ${facts.connection} as [${facts.placed.join(', ')}], and the server's first page lists [${facts.served.join(', ')}]: the client's order and the server's disagree.`,\n    Gap: facts =>\n      `${named(facts.mutation, facts.requestId)} answered ${facts.entity}:${facts.id} without ${facts.fields.join(', ')}, which the client showed while it was pending. They are read again, so the row reads Loading meanwhile: answer with them, or select fewer.`,\n  }),\n  part,\n})\n\nexport const writeUnheard = (\n  facts: Pick<WriteUnheard, 'requestId' | 'mutation' | 'error'>,\n): WriteUnheard => ({\n  _tag: 'WriteUnheard',\n  source,\n  level: 'warning',\n  message: `${named(facts.mutation, facts.requestId)} failed (${facts.error._tag}: ${facts.error.message}) and the application's update does not hear it, so its change went with no word. Share MutationFailed (Data.wiring(actives, { shared: ['MutationFailed'] })) and show Data.failedWrites.`,\n  ...facts,\n})\n\nexport const liveRefused = (facts: Pick<LiveRefused, 'stream' | 'error'>): LiveRefused => ({\n  _tag: 'LiveRefused',\n  source,\n  level: 'warning',\n  message: `The server refused a live stream (${facts.error.message}), so what it asks is not live and is not asked again until it changes. Watch fewer rows at once, or raise the server's maxIdsPerEntity.`,\n  ...facts,\n})\n\nexport const outboxUnreadable = (\n  facts: Pick<OutboxUnreadable, 'requestId' | 'reason'>,\n): OutboxUnreadable => ({\n  _tag: 'OutboxUnreadable',\n  source,\n  level: 'warning',\n  message: `A stored write (${facts.requestId}) cannot be sent: ${facts.reason}. It was made by an earlier version of the application; it is kept until Data.dismiss, and the writes after it are sent.`,\n  ...facts,\n})\n\nexport const outboxUnsaved = (facts: Pick<OutboxUnsaved, 'key' | 'reason'>): OutboxUnsaved => ({\n  _tag: 'OutboxUnsaved',\n  source,\n  level: 'warning',\n  message: `The outbox could not write ${facts.key} (${facts.reason}). Its writes are sent, but a reload before they are answered loses them.`,\n  ...facts,\n})\n\n/**\n * How many diagnostics the Model keeps, the newest. Each was reported as it\n * was recorded; the bound keeps a long session's failed writes from growing it.\n */\nconst DIAGNOSTIC_WINDOW = 256\n\n/** `kept` with `recorded` after it, within the window; `kept` itself when nothing was recorded. */\nexport const withDiagnostics = (\n  kept: ReadonlyArray<RemoteDiagnostic>,\n  recorded: ReadonlyArray<RemoteDiagnostic>,\n): ReadonlyArray<RemoteDiagnostic> =>\n  recorded.length === 0 ? kept : [...kept, ...recorded].slice(-DIAGNOSTIC_WINDOW)\n"],"mappings":";;;;;;;;;AAWA,MAAM,SAAS;AAuCf,MAAa,iBAAiB,KAAK,WAA2B;AAmE9D,MAAM,SAAS,UAAiC,cAC9C,OAAO,MAAM,UAAU;CACrB,cAAc,WAAW;CACzB,SAAQ,SAAQ,GAAG,KAAK,YAAY,UAAU;AAChD,CAAC;AAEH,MAAM,WAAW,UAA2B,KAAK,UAAU,KAAK,KAAK,OAAO,KAAK;AAEjF,MAAa,sBAAsB,UAA8C;CAC/E,MAAM;CACN;CACA,OAAO;CACP,SAAS,eAAe,OAAO,MAAM;EACnC,QAAO,UACL,GAAG,MAAM,MAAM,UAAU,MAAM,SAAS,EAAE,UAAU,MAAM,OAAO,GAAG,MAAM,GAAG,GAAG,MAAM,MAAM,MAAM,QAAQ,MAAM,KAAK,EAAE,iDAAiD,QAAQ,MAAM,QAAQ,EAAE;EAClM,YAAW,UACT,6BAA6B,MAAM,WAAW,OAAO,MAAM,OAAO,KAAK,IAAI,EAAE,wCAAwC,MAAM,OAAO,KAAK,IAAI,EAAE;EAC/I,MAAK,UACH,GAAG,MAAM,MAAM,UAAU,MAAM,SAAS,EAAE,YAAY,MAAM,OAAO,GAAG,MAAM,GAAG,WAAW,MAAM,OAAO,KAAK,IAAI,EAAE;CACtH,CAAC;CACD;AACF;AAEA,MAAa,gBACX,WACkB;CAClB,MAAM;CACN;CACA,OAAO;CACP,SAAS,GAAG,MAAM,MAAM,UAAU,MAAM,SAAS,EAAE,WAAW,MAAM,MAAM,KAAK,IAAI,MAAM,MAAM,QAAQ;CACvG,GAAG;AACL;AAEA,MAAa,eAAe,WAA+D;CACzF,MAAM;CACN;CACA,OAAO;CACP,SAAS,qCAAqC,MAAM,MAAM,QAAQ;CAClE,GAAG;AACL;AAEA,MAAa,oBACX,WACsB;CACtB,MAAM;CACN;CACA,OAAO;CACP,SAAS,mBAAmB,MAAM,UAAU,oBAAoB,MAAM,OAAO;CAC7E,GAAG;AACL;AAEA,MAAa,iBAAiB,WAAiE;CAC7F,MAAM;CACN;CACA,OAAO;CACP,SAAS,8BAA8B,MAAM,IAAI,IAAI,MAAM,OAAO;CAClE,GAAG;AACL;;AASA,MAAa,mBACX,MACA,aAEA,SAAS,WAAW,IAAI,OAAO,CAAC,GAAG,MAAM,GAAG,QAAQ,CAAC,CAAC,MAAM,IAAkB"}

package/dist/entity-CgsG5Uel.d.ts

@@ -0,0 +1,196 @@
+import { r as EntityStore } from "./store-ah2qjcJW.js";
+import { l as QueryWindow } from "./query-BuIU93xA.js";
+import { n as RelationRequirement } from "./requirement-D57S2LpH.js";
+import { u as refParts } from "./relation-BLBGOZom.js";
+import { Schema } from "effect";
+import * as Domain from "foldkit-entity";
+/** One page of a paginated relation with each target assembled through a nested selection. */
+interface Page<Item> {
+  readonly items: ReadonlyArray<Item>;
+  readonly hasNext: boolean;
+  readonly hasPrevious: boolean;
+}
+/**
+ * The fields a projection reads of one entity, plus the slice it reads of each
+ * relation's target. `Shape` tells a parent selection whether this one is a
+ * paginated relation (`connection`) or a plain entity slice (`entity`).
+ */
+interface Selection<Value, Name extends string = string, Shape extends 'entity' | 'connection' = 'entity' | 'connection'> {
+  readonly entity: Name;
+  readonly fields: readonly string[];
+  /** A pure codec: entity fields carry no decoding or encoding services. */
+  readonly schema: Schema.Codec<Value, unknown, never, never>;
+  /** Pagination windows for nested relation fields, keyed by field name. */
+  readonly connections?: Readonly<Record<string, QueryWindow>> | undefined;
+  /** The slice required of each nested relation's target, keyed by field name. */
+  readonly relations?: Readonly<Record<string, RelationRequirement>> | undefined;
+  /** Present when this selection is itself a paginated relation. */
+  readonly window?: QueryWindow | undefined;
+  /** Phantom: see `Shape`. */
+  readonly shape?: Shape | undefined;
+}
+/** Flattens a mapped type so hovers show the picked fields, not the machinery. */
+type Simplify<T> = T extends (infer O) ? { readonly [K in keyof O]: O[K]; } : never;
+/** The value a Selection reads: `Selection.Value<typeof ProjectCard>`. */
+type SelectionValueOf<S> = S extends Selection<infer V, any, any> ? V : never;
+/** The nested selections a relation field admits: of its target entity, in the shapes its value takes. */
+type NestedFor<Field> = Exclude<Field, null | undefined> extends ReadonlyArray<EntityRef$1<infer Name, any>> ? Selection<unknown, Name, 'entity' | 'connection'> : Exclude<Field, null | undefined> extends RefPage<infer Name, any> ? Selection<unknown, Name, 'entity' | 'connection'> : Exclude<Field, null | undefined> extends EntityRef$1<infer Name, any> ? Selection<unknown, Name, 'entity'> : never;
+/** What a selection of an entity with fields `F` may pick: `true` per scalar, a nested selection per relation. */
+type SelectionOf<F extends Schema.Struct.Fields> = { readonly [K in keyof F]?: true | NestedFor<Schema.Schema.Type<F[K]>>; };
+/** `T | null` when the field admits `null` or `undefined` (both assemble to `null`). */
+type Nullable<Field, T> = [Extract<Field, null | undefined>] extends [never] ? T : T | null;
+/** A nested selection's value takes the shape of the field it selects through. */
+type NestedValue<Field, Sel> = Sel extends Selection<infer V, string, 'connection'> ? Nullable<Field, V> : Sel extends Selection<infer V, string, 'entity'> ? Nullable<Field, Exclude<Field, null | undefined> extends ReadonlyArray<EntityRef$1<any, any>> ? ReadonlyArray<V> : Exclude<Field, null | undefined> extends RefPage<any, any> ? Page<V> : V> : never;
+/** The value a selection `Sel` of fields `F` reads. */
+type SelectionValue<F extends Schema.Struct.Fields, Sel> = Simplify<{ readonly [K in keyof Sel & keyof F]: Sel[K] extends true ? Schema.Schema.Type<F[K]> : NestedValue<Schema.Schema.Type<F[K]>, Sel[K]>; }>;
+declare const pageSchema: (item: AnySchema) => AnySchema;
+/** The requirement a nested selection contributes for its relation's target. */
+declare const relationOf: (selection: Selection<unknown>) => RelationRequirement;
+declare const Selection: {
+  /**
+   * The Remote Selection of a `foldkit-entity` Selection: the same members, read
+   * from Remote's store. `true` on a relation reads its refs, as it does here.
+   */
+  from: <Name extends string, S extends Schema.Constraint>(selection: Domain.Selection<Name, unknown, S>) => Selection<S['Type'], Name, 'entity'>;
+  /**
+   * The fields to read of `entity`. A nested `Selection` on a relation field
+   * reads through the ref (or refs, or page of refs) the field holds into the
+   * target's fields; a scalar field cannot take one.
+   */
+  make: <Name extends string, F extends Schema.Struct.Fields, const Sel extends SelectionOf<F>>(entity: EntityDescriptor<Name, F>, selection: Sel) => Selection<SelectionValue<F, Sel>, Name, 'entity'>;
+  /**
+   * A paginated relation: one page of refs to `entity` with a window, or, with
+   * a nested selection, one page of targets assembled through it.
+   */
+  connection: {
+    <Name extends string, F extends Schema.Struct.Fields>(entity: EntityDescriptor<Name, F>, window: QueryWindow): Selection<RefPage<Name, F>, Name, 'connection'>;
+    <Name extends string, F extends Schema.Struct.Fields, Item>(entity: EntityDescriptor<Name, F>, window: QueryWindow, selection: Selection<Item, NoInfer<Name>, 'entity'>): Selection<Page<Item>, Name, 'connection'>;
+  };
+};
+interface Assembled {
+  readonly values: unknown;
+  readonly refreshing: boolean;
+}
+/**
+ * Reads an entity's selected fields out of the store, following each nested
+ * relation into its targets. `undefined` means some field, at any depth, is
+ * not present yet. A tombstoned target reads as `null` (or is dropped from a
+ * list), so the Selection's codec decides whether that is a failure.
+ */
+declare const assemble: (store: EntityStore, key: string, requirement: RelationRequirement) => Assembled | undefined;
+/**
+ * The first field `requirement` reads, at any depth, that the server settled
+ * without a value, as `Entity:id.field`. A read that consults it says why it
+ * cannot assemble rather than waiting on a field nothing will fetch.
+ */
+declare const unavailableOf: (store: EntityStore, key: string, requirement: RelationRequirement) => string | undefined;
+type AnySchema = Schema.Schema<unknown>;
+declare const entityRefFields: unique symbol;
+/**
+ * A normalized reference to an entity. `F` is a phantom carrying the entity's
+ * fields so `Entity.patch` can type its patch; it is absent at runtime.
+ */
+interface EntityRef$1<Name extends string, F extends Schema.Struct.Fields = Schema.Struct.Fields> {
+  readonly entity: Name;
+  readonly id: string;
+  readonly [entityRefFields]?: F;
+}
+interface EntityDescriptor<Name extends string, F extends Schema.Struct.Fields> {
+  readonly name: Name;
+  readonly schema: Schema.Struct<F>;
+  readonly fields: F;
+  ref(id: Schema.Schema.Type<F['id']>): EntityRef$1<Name, F>;
+  /** The fields a Surface reads of this entity; `Selection.make(entity, …)` with the entity as receiver. */
+  select<const Sel extends SelectionOf<F>>(selection: Sel): Selection<SelectionValue<F, Sel>, Name, 'entity'>;
+  /** A patch of this entity's wire-shaped values; `Entity.patch(entity.ref(id), values)`. */
+  patch(id: Schema.Schema.Type<F['id']>, values: Partial<Schema.Struct.Encoded<F>>): EntityPatch<Name, F>;
+}
+/**
+ * Relations are **references**, never inline target schemas: a ref cannot
+ * reconstruct a full entity, and dereferencing is a store concern. Because the
+ * target schema is not inlined, recursive relations cannot arise through the
+ * schema graph.
+ */
+/**
+ * A ref as the wire carries it: the target's name, a colon, and its id. Typed
+ * with the name, so a relation to `User` takes `'User:u1'` and not a ref to
+ * some other entity, which would read as a row that does not exist.
+ */
+type RefKey<Name extends string> = `${Name}:${string}`;
+/**
+ * A patch in wire shape: the values the store holds, so a relation is its ref
+ * key (`Entity.refKey`), not an `EntityRef`.
+ */
+interface EntityPatch<Name extends string, F extends Schema.Struct.Fields> {
+  readonly entity: Name;
+  readonly id: string;
+  readonly values: Partial<Schema.Struct.Encoded<F>>;
+}
+/** What a relation field decodes to: a ref, refs, or a page of refs, perhaps null. */
+type IsRelation<T> = [NonNullable<T>] extends [never] ? false : [NonNullable<T>] extends [EntityRef$1<string, any> | ReadonlyArray<EntityRef$1<string, any>> | RefPage<string, any>] ? true : false;
+/**
+ * `Remote.patch`'s values: each field's wire shape, except a relation, which
+ * takes what it decodes to (`Remote.ref(User, id)`, an array of refs, a page
+ * of refs, or `null` where it is optional), never a ref key typed by hand.
+ */
+type PatchValues<F extends Schema.Struct.Fields> = { readonly [K in keyof Schema.Struct.Encoded<F>]?: K extends keyof Schema.Struct.Type<F> ? IsRelation<Schema.Struct.Type<F>[K]> extends true ? Schema.Struct.Type<F>[K] : Schema.Struct.Encoded<F>[K] : Schema.Struct.Encoded<F>[K]; };
+/**
+ * One authoritative page of a paginated relation: refs (never inline entities)
+ * plus whether more exist. The adapter does not hold segmentation state; the
+ * client merges pages.
+ */
+interface RefPage<Name extends string, F extends Schema.Struct.Fields = Schema.Struct.Fields> {
+  readonly refs: ReadonlyArray<EntityRef$1<Name, F>>;
+  readonly hasNext: boolean;
+  readonly hasPrevious: boolean;
+}
+/** The ref codec a `foldkit-entity` relation becomes: one ref, a nullable ref, or an array of refs. */
+type RelationField<Spec> = Spec extends Domain.RelationSpec<infer Target, infer Cardinality, infer Optional> ? Cardinality extends 'many' ? Schema.$Array<Schema.Codec<EntityRef$1<Target['name']>, RefKey<Target['name']>>> : Optional extends true ? Schema.NullOr<Schema.Codec<EntityRef$1<Target['name']>, RefKey<Target['name']>>> : Schema.Codec<EntityRef$1<Target['name']>, RefKey<Target['name']>> : never;
+/**
+ * The fields Remote stores for a `foldkit-entity` Entity: its own fields, its
+ * derived members (the server supplies them like any field), and each relation
+ * as refs.
+ */
+type FieldsFrom<E> = E extends Domain.Entity<any, infer Fields, infer Relations, infer Derived> ? Fields & { readonly [K in keyof Derived]: Derived[K]['schema']; } & { readonly [K in keyof Relations]: RelationField<Relations[K]>; } : never;
+declare const Entity$1: {
+  /**
+   * The Remote descriptor of a `foldkit-entity` Entity. Relations declared with
+   * `Entity.relate` become ref fields, so the store, the planner, and the server
+   * treat it as they treat an `Entity.make` descriptor.
+   */
+  from: <E extends Domain.AnyEntity>(entity: E & {
+    readonly fields: {
+      readonly id: unknown;
+    };
+  }) => EntityDescriptor<E['name'], FieldsFrom<E>>;
+  make: <const Name extends string, const F extends Schema.Struct.Fields & {
+    readonly id: Schema.Schema<unknown>;
+  }>(name: Name, schema: Schema.Struct<F>) => EntityDescriptor<Name, F>;
+  /** A relation to a known entity, decoded as a reference. */
+  ref: <Name extends string, F extends Schema.Struct.Fields>(entity: EntityDescriptor<Name, F>) => Schema.Codec<EntityRef$1<Name, F>, RefKey<Name>>;
+  /** A relation by name, for recursive or forward references. */
+  refTo: <Name extends string>(name: Name) => Schema.Codec<EntityRef$1<Name>, RefKey<Name>>;
+  /**
+   * The wire key a relation field carries (`"Entity:id"`). Adapters that read a
+   * foreign key emit this so the ref codec can decode it on the client.
+   */
+  refKey: (ref: {
+    readonly entity: string;
+    readonly id: string;
+  }) => string;
+  /** Splits a ref key back into its entity and id. */
+  refParts: typeof refParts;
+  /** A relation value of one authoritative page of refs. */
+  refPage: <Name extends string, F extends Schema.Struct.Fields>(entity: EntityDescriptor<Name, F>) => Schema.Codec<RefPage<Name, F>, {
+    readonly refs: ReadonlyArray<string>;
+    readonly hasNext: boolean;
+    readonly hasPrevious: boolean;
+  }>;
+  /**
+   * A normalized patch for an entity, typed against its fields' wire shape:
+   * write a relation as its ref key (`Entity.refKey`), as the server does.
+   */
+  patch: <Name extends string, F extends Schema.Struct.Fields>(ref: EntityRef$1<Name, F>, patch: Partial<Schema.Struct.Encoded<F>>) => EntityPatch<Name, F>;
+};
+export { relationOf as _, EntityRef$1 as a, RefKey as c, Selection as d, SelectionOf as f, pageSchema as g, assemble as h, EntityPatch as i, RefPage as l, SelectionValueOf as m, Entity$1 as n, FieldsFrom as o, SelectionValue as p, EntityDescriptor as r, PatchValues as s, AnySchema as t, Page as u, unavailableOf as v };
+//# sourceMappingURL=entity-CgsG5Uel.d.ts.map