@thomasfosterau/legation-jsonapi 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,4304 @@
+import { t as __exportAll } from "./rolldown-runtime-D8jQpDG7.js";
+import { ApiError as ApiError$1, Atomic, Document, Filter, Handlers, MEDIA_TYPE, Middleware, Query, Relationship, Resource } from "@thomasfosterau/effect-jsonapi";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as Arr from "effect/Array";
+import * as Context from "effect/Context";
+import * as P from "effect/Predicate";
+import * as R from "effect/Record";
+import * as Result from "effect/Result";
+import * as HttpClient from "effect/http/HttpClient";
+import * as HttpClientRequest from "effect/http/HttpClientRequest";
+import * as Option from "effect/Option";
+import * as SchemaIssue from "effect/SchemaIssue";
+import * as Str from "effect/String";
+import { Authorization, AuthorizationError, Backend, BackendError, ClientStore, Collection, CrudMutation, Edge, FilterPolicy, MutationRejected, Mutator, Node, Predicate, Query as Query$1, QueryError, Transport } from "@thomasfosterau/legation";
+import * as Iterable from "effect/Iterable";
+import * as HttpApi from "effect/http-api/HttpApi";
+import * as Ref from "effect/Ref";
+import * as Semaphore from "effect/Semaphore";
+import { ClientEngine, Hash, RejectionMemory, Related, Subset, SyncRoom, SyncServer, UnknownMutator } from "@thomasfosterau/legation/internal";
+import * as Duration from "effect/Duration";
+import * as Match from "effect/Match";
+import { flow } from "effect/Function";
+import * as HashSet from "effect/HashSet";
+import * as HashMap from "effect/HashMap";
+import * as Stream from "effect/Stream";
+import * as HttpServerResponse from "effect/http/HttpServerResponse";
+import * as Layer from "effect/Layer";
+import { KeyValueStore } from "effect/persistence";
+// src/errors.ts
+/**
+* Synchronizer Errors
+*
+* Tagged error types for the JSON:API adapter. All errors extend
+* `Schema.TaggedError`, so they are yieldable inside `Effect.gen`, usable with
+* `Effect.fail`, and handled with `Effect.catchTag` / `Effect.catchTags`.
+* Because `Schema.TaggedError` extends `Error`, the `message` field is also
+* available as `.message` on instances.
+*/
+/**
+* Base error for synchronizer operations.
+*/
+var SyncError = class extends Schema.TaggedError()("SyncError", {
+	message: Schema.String,
+	cause: Schema.optional(Schema.Defect())
+}) {};
+/**
+* Network-related error (connection failure, timeout, etc.).
+*/
+var NetworkError = class extends Schema.TaggedError()("NetworkError", {
+	message: Schema.String,
+	cause: Schema.optional(Schema.Defect())
+}) {};
+/**
+* Parsing error for JSON:API documents.
+*/
+var ParseError = class extends Schema.TaggedError()("ParseError", {
+	message: Schema.String,
+	cause: Schema.optional(Schema.Defect())
+}) {};
+/**
+* API error carrying the JSON:API error objects returned by the server.
+*/
+var ApiError = class extends Schema.TaggedError()("ApiError", {
+	message: Schema.String,
+	errors: Schema.Array(Document.ErrorObject)
+}) {};
+/**
+* Conflict error raised when local and remote resource versions mismatch.
+*/
+var ConflictError = class extends Schema.TaggedError()("ConflictError", {
+	message: Schema.String,
+	localVersion: Schema.optional(Schema.String),
+	remoteVersion: Schema.optional(Schema.String)
+}) {};
+// src/schema.ts
+/**
+* JSON:API Schemas
+*
+* Generic codecs for the JSON:API v1.1 document types this loader decodes from
+* arbitrary upstream servers, plus a `decodeDocument` helper that validates
+* untrusted input (e.g. a parsed HTTP response body) into a `JsonApiDocument`.
+*
+* The spec primitives — link objects, the `jsonapi` member, error objects, and
+* free-form `meta` — are adopted from `@thomasfosterau/effect-jsonapi`'s
+* `Document` module (the canonical, spec-compliant definitions) rather than
+* hand-rolled here. What stays local are the *generic, untyped* composites
+* (`ResourceObject`, `Relationship`, `JsonApiDocument`): the library models
+* documents per known `Resource` definition, but a collection loader reads
+* resources whose `type` and attribute shapes it does not know ahead of time,
+* so it needs a resource-agnostic document schema layered over those
+* primitives.
+*
+* JSON:API is an *open* format: documents and most member objects may carry
+* implementation-specific members beyond those the spec names. Effect v4
+* `Schema.Struct` already drops excess properties during decoding rather than
+* rejecting them, so these schemas validate the *shape* of the members we care
+* about while tolerating extra members. Free-form members (`meta`,
+* `attributes`) are modelled as `Document.AnyMeta`
+* (`Schema.Record(Schema.String, Schema.Unknown)`).
+*
+* Schema failures are mapped to the package's `ParseError`, with the
+* underlying `Schema` issue attached as `cause`.
+*/
+var schema_exports = /* @__PURE__ */ __exportAll({
+	JsonApiDocument: () => JsonApiDocument,
+	JsonApiError: () => JsonApiError,
+	LinkObject: () => LinkObject,
+	Links: () => Links,
+	Relationship: () => Relationship$1,
+	ResourceIdentifier: () => ResourceIdentifier,
+	ResourceObject: () => ResourceObject,
+	decodeDocument: () => decodeDocument
+});
+/** Free-form `meta` / `attributes` object: arbitrary JSON values by key. */
+const MetaSchema = Document.AnyMeta;
+/**
+* Schema for a JSON:API link object (`{ href, ... }`), adopted from the
+* library's spec-compliant definition.
+*/
+const LinkObject = Document.LinkObject;
+/**
+* Schema for a single link value: either a URL string or a link object.
+*/
+const LinkValue = Document.Link;
+/**
+* Schema for a JSON:API `links` object. The spec allows arbitrary link names,
+* so this is a record of link values; `self` / `related` are simply well-known
+* keys within it.
+*/
+const Links = Schema.Record(Schema.String, LinkValue);
+/**
+* Schema for a JSON:API resource identifier (`{ type, id, meta? }`).
+*/
+const ResourceIdentifier = Schema.Struct({
+	type: Schema.String,
+	id: Schema.String,
+	meta: Schema.optional(MetaSchema)
+});
+/**
+* Schema for a JSON:API relationship (`{ data?, links?, meta? }`). The
+* `data` member may be a single identifier, an array of identifiers, or
+* `null`.
+*/
+const Relationship$1 = Schema.Struct({
+	data: Schema.optional(Schema.NullOr(Schema.Union([ResourceIdentifier, Schema.Array(ResourceIdentifier)]))),
+	links: Schema.optional(Links),
+	meta: Schema.optional(MetaSchema)
+});
+/**
+* Schema for a JSON:API resource object (a resource identifier plus
+* optional `attributes`, `relationships`, and `links`).
+*/
+const ResourceObject = Schema.Struct({
+	type: Schema.String,
+	id: Schema.String,
+	meta: Schema.optional(MetaSchema),
+	attributes: Schema.optional(MetaSchema),
+	relationships: Schema.optional(Schema.Record(Schema.String, Relationship$1)),
+	links: Schema.optional(Links)
+});
+/**
+* Schema for a JSON:API error object, adopted from the library's
+* spec-compliant definition.
+*/
+const JsonApiError = Document.ErrorObject;
+/**
+* Schema for a top-level JSON:API document.
+*
+* The `data` member may be a single resource, a collection of resources, a
+* resource identifier (or collection thereof), or `null`. The other
+* top-level members (`errors`, `meta`, `included`, `links`, `jsonapi`) are
+* all optional. The `jsonapi` member reuses the library's `JsonApiObject`.
+*/
+const JsonApiDocument = Schema.Struct({
+	data: Schema.optional(Schema.NullOr(Schema.Union([
+		ResourceObject,
+		Schema.Array(ResourceObject),
+		ResourceIdentifier,
+		Schema.Array(ResourceIdentifier)
+	]))),
+	errors: Schema.optional(Schema.Array(JsonApiError)),
+	meta: Schema.optional(MetaSchema),
+	included: Schema.optional(Schema.Array(ResourceObject)),
+	links: Schema.optional(Links),
+	jsonapi: Schema.optional(Document.JsonApiObject)
+});
+const decodeJsonApiDocument = Schema.decodeUnknownEffect(JsonApiDocument);
+/**
+* Decode an unknown value (e.g. a parsed HTTP response body) into a
+* `JsonApiDocument`. Schema failures become `ParseError`, with the schema
+* issue attached as `cause`.
+*/
+const decodeDocument = (input) => decodeJsonApiDocument(input).pipe(Effect.mapError((cause) => new ParseError({
+	message: "Invalid JSON:API document",
+	cause
+})));
+// src/JsonApiQuery.ts
+/**
+* JsonApiQuery
+*
+* The bridge between the filter grammar's URL form and the engine's plan
+* (ADR-0028 §5, issue #161) — a façade-boundary projection for one job
+* (ADR-0029 §6: a URL must mean the same thing answered from the replica as
+* answered by the network), not a general translation between two dialects
+* of one language. effect-jsonapi owns the grammar — its AST (`Filter.Ast`),
+* the `filter[...]` ⇄ AST codec (`Query.Filter`), the whole query codec
+* (`Query.schema`) and the canonical query string (`Query.canonical`); this
+* module owns the three translations legation needs on top of them:
+*
+* - **Filter AST ⇄ `Predicate`** ({@link fromFilterAst}, {@link toFilterAst}):
+*   both directions are partial, and neither is the other's inverse.
+*   {@link fromFilterAst} rejects a literal that is not a wire scalar
+*   (`string | number | boolean`) or a `Date` (encoded to its instant text —
+*   see below) with a typed `QueryError`, since a grammar AST is typed by
+*   the attribute's **decoded** schema and that type is open-ended (issue
+*   #218's design note). {@link toFilterAst} returns `None` for `Exists`
+*   (server-only, no URL form), an empty `In` / `NotIn` list, and a `null`
+*   literal (the grammar's lists are non-empty and `NULL` is never a
+*   literal — `isnull` names it); those callers fail closed.
+*   {@link foldConstants} removes the two definite cases before encoding:
+*   an empty `In` is false and an empty `NotIn` is true under ADR-0028's
+*   per-operator table, so they fold away exactly. Both functions carry a
+*   **field-namespace precondition**: a field name is copied verbatim
+*   between the two ASTs, which is correct only because every caller in
+*   this module pre-synthesises a resource whose field names are already
+*   the engine's ({@link resourcesOf} — a to-one edge is named by its FK key
+*   field, never the relationship name). Neither function checks that a
+*   field it is given actually names something on the other side; a caller
+*   bridging an AST built over a resource with its own naming must
+*   translate field names first. A `Date` literal's conversion to
+*   `value.toISOString()` is an **encode, not a copy**: ADR-0028 rule (e)
+*   fixes instant comparison to that exact text, so an instant literal that
+*   arrives any other way (a differently-formatted string, say) will not
+*   compare correctly downstream — this is the one step in either direction
+*   that changes a value's representation rather than re-tagging it, which
+*   is also why {@link toFilterAst} is a separate partial function rather
+*   than {@link fromFilterAst}'s inverse: the type erasure `Date → string`
+*   cannot be undone from the `Predicate` side alone.
+* - **URL → `Query.Read`** ({@link parseRead}, {@link parseParams}): a
+*   request URL is decoded with effect-jsonapi's `Query.schema` for the
+*   collection's node — `include`, `fields`, `sort`, `page` and `filter` —
+*   and mapped onto the declarative read: `filter` → `where`, `sort` →
+*   `order`, `page[limit]` / `page[after]` → `first` / `after`, `include`
+*   → the edge selects. `fields[]` is a serialisation-time projection
+*   (ADR-0029 §5) and is carried beside the read, never into the plan.
+*   Every rejection is a `QueryError` naming the parameter, so a façade or
+*   a derived REST handler answers 400 with `source.parameter` set.
+* - **`Query.Read` → canonical string** ({@link canonical}): the read is
+*   compiled with `Query.plan` and its plan is encoded through the
+*   canonical encoder, so two reads with one plan have one string —
+*   subscription identity for `Client.subscribe(url)` (ADR-0029 §2).
+*   {@link urlReads} packages the parse and the canonical string as the
+*   `Client.UrlReads` seam a Client or an engine host is built with (#159).
+*
+* The query codec is derived from the **node graph**, not from an
+* effect-jsonapi resource: {@link resourcesOf} synthesises one resource per
+* node whose filterable attributes carry the node's filterable set (the
+* operators and literal kinds of ADR-0028 rule d, #154) and whose
+* relationships are the node's edges. A filter names the row field the
+* engine evaluates — a `one`-edge is filtered by its key field
+* (`filter[categoryId]=c-audio`, as in ADR-0029's worked examples), not by
+* the edge name. Include paths are single level (decision D1 of ADR-0028):
+* a read includes a node's own edges only, so `include=variants.product` is
+* rejected as a parse failure.
+*
+* The **exact encoder** ({@link defaultEncoder}) is what `JsonApiBackend`
+* pushes to the server: the whole predicate as the grammar's canonical
+* `filter[...]` record (operators, `or`, `not`, `isnull` and `nin`
+* included — nothing is dropped any more), plus `sort`. Order, cursor and
+* limit stay local: `Subset.apply` still finalises the window, which is now
+* redundancy over an exact filter rather than correction of a superset
+* (ADR-0028 §6). A predicate that can never match (an empty allow-set)
+* encodes to `None` and the backend skips the request.
+*/
+var JsonApiQuery_exports = /* @__PURE__ */ __exportAll({
+	PageWindow: () => PageWindow,
+	buildQueryString: () => buildQueryString,
+	canonical: () => canonical,
+	defaultEncoder: () => defaultEncoder,
+	flatFilter: () => flatFilter,
+	foldConstants: () => foldConstants,
+	fromFilterAst: () => fromFilterAst,
+	invalidParameter: () => invalidParameter,
+	parseParams: () => parseParams,
+	parseRead: () => parseRead,
+	querySchema: () => querySchema,
+	resourcesOf: () => resourcesOf,
+	singleRowParams: () => singleRowParams,
+	singleRowSchema: () => singleRowSchema,
+	toFilterAst: () => toFilterAst,
+	toRequestOptions: () => toRequestOptions,
+	urlReads: () => urlReads
+});
+/**
+* A grammar literal as a `Predicate` literal: scalars as they are, a `Date`
+* as its instant text (the load-bearing encode of ADR-0028 rule e), or a
+* typed `QueryError` for anything else — a grammar AST is typed by the
+* attribute's decoded schema (issue #218's design note), which is
+* open-ended, so this is the one place that type meets `Predicate.Literal`'s
+* closed wire-scalar union and can fail.
+*/
+const literalOf = (field, value) => {
+	switch (typeof value) {
+		case "string":
+		case "number":
+		case "boolean": return Result.succeed(value);
+		default: return value instanceof Date ? Result.succeed(value.toISOString()) : Result.fail(new QueryError({
+			message: `Filter literal ${JSON.stringify(value)} for field "${field}" is not a scalar`,
+			parameter: `filter[${field}]`
+		}));
+	}
+};
+/**
+* The engine form of a filter AST, or a typed `QueryError` naming the field
+* whose literal {@link literalOf} rejects: `Compare` / `In` / `NotIn` /
+* `IsNull` map node for node, `And` / `Or` / `Not` recurse, and the empty
+* conjunction (the grammar's "true") is `Predicate.always`. The map is
+* structural — a singleton group, which the grammar's normal form keeps
+* after deduplicating `Or(x, x)`, stays a singleton group rather than
+* collapsing through `Predicate.or` — so {@link canonical} is idempotent.
+* Literals are the codec's decoded scalars; a `Date` (a `DateFromString`
+* attribute) becomes its ISO-8601 UTC text (see the module doc's encode
+* note). Field names are copied verbatim — the module doc's
+* field-namespace precondition.
+*
+* This module's own callers ({@link readOf}, {@link filterOf}) never see
+* this fail: their ASTs are decoded through {@link resourcesOf}'s synthetic
+* resource, whose filterable attributes admit only wire scalars, or are
+* built by {@link toFilterAst} from a `Predicate.Literal`, which is one
+* already. The typed failure exists for this function's public contract —
+* any caller bridging an AST built over a resource with a richer decoded
+* attribute type (a `Date`-valued one aside, which is handled) — not for
+* either call site here.
+*/
+const fromFilterAst = (ast) => {
+	switch (ast._tag) {
+		case "Compare": return Result.map(literalOf(ast.field, ast.value), (value) => Predicate.compare(ast.op, ast.field, value));
+		case "In": return Result.map(Result.all(ast.values.map((value) => literalOf(ast.field, value))), (values) => Predicate.isIn(ast.field, values));
+		case "NotIn": return Result.map(Result.all(ast.values.map((value) => literalOf(ast.field, value))), (values) => Predicate.notIn(ast.field, values));
+		case "IsNull": return Result.succeed(ast.negated ? Predicate.isNotNull(ast.field) : Predicate.isNull(ast.field));
+		case "And": return Arr.isReadonlyArrayEmpty(ast.members) ? Result.succeed(Predicate.always) : Result.map(Result.all(ast.members.map(fromFilterAst)), (predicates) => ({
+			_tag: "And",
+			predicates
+		}));
+		case "Or": return Result.map(Result.all(ast.members.map(fromFilterAst)), (predicates) => ({
+			_tag: "Or",
+			predicates
+		}));
+		case "Not": return Result.map(fromFilterAst(ast.member), Predicate.not);
+	}
+};
+/** A non-empty list of non-null literals, or `None` (the grammar has neither an empty list nor a `NULL` literal). */
+const literalList = (values) => {
+	const [head, ...tail] = values;
+	return head === void 0 || head === null || tail.includes(null) ? Option.none() : Option.some([head, ...tail]);
+};
+/**
+* The grammar form of a predicate, or `None` where it has no URL form:
+* `Exists` (server-only, ADR-0028 §5), an empty `In` / `NotIn` list, or a
+* `null` literal (the deprecated wire form of `isnull`; it evaluates to
+* unknown and cannot be folded). `True` is the empty conjunction.
+* `fromFilterAst ∘ toFilterAst` is the identity on every constructor-built
+* predicate it accepts.
+*/
+const toFilterAst = (predicate) => {
+	switch (predicate._tag) {
+		case "True": return Option.some(Filter.and());
+		case "Compare": return predicate.value === null ? Option.none() : Option.some({
+			_tag: "Compare",
+			op: predicate.op,
+			field: predicate.field,
+			value: predicate.value
+		});
+		case "In": return Option.map(literalList(predicate.values), (values) => Filter.isIn(predicate.field, values));
+		case "NotIn": return Option.map(literalList(predicate.values), (values) => Filter.notIn(predicate.field, values));
+		case "IsNull": return Option.some(Filter.isNull(predicate.field, predicate.negated === true));
+		case "And": return Option.map(Option.all(predicate.predicates.map(toFilterAst)), (members) => Filter.and(...members));
+		case "Or": return Option.map(Option.all(predicate.predicates.map(toFilterAst)), (members) => Filter.or(...members));
+		case "Not": return Option.map(toFilterAst(predicate.predicate), Filter.not);
+		case "Exists":
+		case "InSet": return Option.none();
+	}
+};
+/** The definite-false predicate: the empty disjunction (`Some(false)` for every row). */
+const FALSE = {
+	_tag: "Or",
+	predicates: []
+};
+const isTrue = (predicate) => predicate._tag === "True";
+const isFalse = (predicate) => predicate._tag === "Or" && Arr.isReadonlyArrayEmpty(predicate.predicates);
+/** Kleene `And` over folded members: any false is false; true members vanish. */
+const foldAnd = (members) => {
+	const folded = members.map(foldConstants);
+	if (folded.some(isFalse)) return FALSE;
+	const kept = folded.filter((member) => !isTrue(member));
+	return Arr.isReadonlyArrayEmpty(kept) ? Predicate.always : Predicate.and(...kept);
+};
+/** Kleene `Or` over folded members: any true is true; false members vanish. */
+const foldOr = (members) => {
+	const folded = members.map(foldConstants);
+	if (folded.some(isTrue)) return Predicate.always;
+	const kept = folded.filter((member) => !isFalse(member));
+	return Arr.isReadonlyArrayEmpty(kept) ? FALSE : Predicate.or(...kept);
+};
+const foldNot = (inner) => {
+	const folded = foldConstants(inner);
+	return isTrue(folded) ? FALSE : isFalse(folded) ? Predicate.always : Predicate.not(folded);
+};
+/**
+* Fold the definite constants out of a predicate, exactly under ADR-0028's
+* three-valued semantics: an empty `In` is false and an empty `NotIn` is
+* true for every row (the compilers render them `1 = 0` / `1 = 1`), a
+* false conjunct or a true disjunct decides its connective, and true
+* conjuncts / false disjuncts vanish. Unknown is never folded — a `null`
+* literal stays where it is. The result is `Predicate.always`, the empty
+* `Or` (false), or a predicate free of empty lists.
+*/
+const foldConstants = (predicate) => {
+	switch (predicate._tag) {
+		case "In": return Arr.isReadonlyArrayEmpty(predicate.values) ? FALSE : predicate;
+		case "NotIn": return Arr.isReadonlyArrayEmpty(predicate.values) ? Predicate.always : predicate;
+		case "And": return foldAnd(predicate.predicates);
+		case "Or": return foldOr(predicate.predicates);
+		case "Not": return foldNot(predicate.predicate);
+		default: return predicate;
+	}
+};
+/** A check that a decoded literal is a value of the kind (`FilterPolicy.matchesKind`). */
+const kindCheck = (kind) => Schema.makeFilter((value) => FilterPolicy.matchesKind(kind, value), {
+	identifier: `LiteralKind.${kind}`,
+	title: kind,
+	description: `a literal of kind "${kind}"`
+});
+/**
+* The attribute schema a filter literal of the kind decodes through: the
+* wire string is parsed as the scalar the schema's encoded form names, then
+* checked against the kind (int4 range, the fixed instant format).
+*/
+const literalSchema = (kind) => {
+	switch (kind) {
+		case "text": return Schema.String;
+		case "instant": return Schema.String.pipe(Schema.check(kindCheck("instant")));
+		case "integer": return Schema.Number.pipe(Schema.check(kindCheck("integer")));
+		case "double": return Schema.Number;
+		case "boolean": return Schema.Boolean;
+	}
+};
+/**
+* The synthetic resource's attributes: every filterable field (`id` and the
+* `one`-edge keys included) with its kind's schema and its operators
+* declared through `Filter.able`; every other attribute as `Unknown`, so
+* `fields[type]` still names it but no filter reaches it.
+*/
+const attributesOf$2 = (node) => {
+	const filterable = R.map(node.filterable, (declared) => literalSchema(declared.kind).pipe(Filter.able(declared.operators)));
+	return {
+		...filterable,
+		...R.map(R.filter(node.attributes, (_, field) => !R.has(filterable, field)), () => Schema.Unknown)
+	};
+};
+/**
+* The synthetic resource's relationships: the node's edges, targets
+* resolved lazily through the graph. A paginated edge is a `many`
+* relationship here: effect-jsonapi keeps `Relationship.paginated` out of
+* `include` paths, whereas a read includes a paginated edge like any other
+* (its per-parent window is the plan's, not the URL's — {@link canonical}
+* refuses `include: { first }`).
+*/
+/**
+* The resource of node `type`. {@link resourcesOf} builds one per node and
+* every edge targets a node, so a miss is a defect, never a request error.
+*/
+const resourceIn = (resources, type) => {
+	const resource = resources.get(type);
+	if (resource === void 0) throw new QueryError({ message: `No resource for node "${type}"` });
+	return resource;
+};
+const relationshipsOf = (node, resources) => {
+	return R.map(node.edges, (edge) => {
+		const target = () => resourceIn(resources, edge.target);
+		return edge.kind === "one" ? Relationship.one(target) : Relationship.many(target);
+	});
+};
+const resourceGraphs = /* @__PURE__ */ new WeakMap();
+/**
+* The node graph as effect-jsonapi resource definitions, one per node —
+* the declaration the URL codecs are derived from. Attributes are typed by
+* the node's filterable set (kind and operators), relationships are its
+* edges; nothing else about the resource is faithful (a document is never
+* serialised through it). Memoised per registry.
+*/
+const resourcesOf = (nodes) => {
+	const cached = resourceGraphs.get(nodes);
+	if (cached !== void 0) return cached;
+	const resources = /* @__PURE__ */ new Map();
+	nodes.nodes.forEach((node) => resources.set(node.type, Resource.make(node.type, {
+		attributes: attributesOf$2(node),
+		relationships: relationshipsOf(node, resources)
+	})));
+	resourceGraphs.set(nodes, resources);
+	return resources;
+};
+/**
+* The root window's page parameters: `page[limit]` is the read's `first`
+* (a positive integer), `page[after]` its `after` cursor (a row id,
+* opaque on the wire), `page[offset]` its `offset` (a non-negative
+* integer, #209 — every audited app's pagination idiom). `page[offset]`
+* and `page[after]` are different pagination idioms; {@link parseParams}
+* rejects a request naming both, and {@link decodedOf} emits `limit` then
+* whichever of `after` / `offset` the read carries — the order the
+* canonical string keeps.
+*/
+const PageWindow = {
+	limit: Schema.optionalKey(Schema.FiniteFromString.pipe(Schema.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(1)))),
+	after: Schema.optionalKey(Schema.String),
+	offset: Schema.optionalKey(Schema.FiniteFromString.pipe(Schema.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0))))
+};
+/** A value derived per node, memoised per registry then per node type. */
+const memoised = (store, nodes, node, build) => {
+	let byType = store.get(nodes);
+	if (byType === void 0) {
+		byType = /* @__PURE__ */ new Map();
+		store.set(nodes, byType);
+	}
+	const cached = byType.get(node.type);
+	if (cached !== void 0) return cached;
+	const value = build();
+	byType.set(node.type, value);
+	return value;
+};
+/** The `include` option of a node's query codecs: single-level paths only (ADR-0028 D1); no edges, no `include` at all. */
+const includeOption = (node) => !R.isEmptyReadonlyRecord(node.edges) ? { depth: 1 } : false;
+const queryCodecs = /* @__PURE__ */ new WeakMap();
+/** Build (or fetch) the query codec of one node: `Query.schema` over its synthetic resource. */
+const codecOf = (nodes, node) => memoised(queryCodecs, nodes, node, () => {
+	const resource = resourceIn(resourcesOf(nodes), node.type);
+	const schema = Query.schema(resource, {
+		include: includeOption(node),
+		fields: true,
+		sort: node.sortable,
+		page: PageWindow,
+		filter: true
+	});
+	return {
+		schema,
+		canonical: Query.canonical(schema)
+	};
+});
+/** The node a collection names, or a `QueryError` thrown — a definition-time defect. */
+const nodeOrThrow = (nodes, collection) => {
+	const node = nodes.nodes.get(collection);
+	if (node === void 0) throw new QueryError({
+		message: `Unknown collection: ${collection}`,
+		query: collection
+	});
+	return node;
+};
+/**
+* The query codec of a collection's `list` endpoint — `include`, `fields[…]`,
+* `sort`, `page[…]` and `filter[…]` exactly as the node graph declares them:
+* the codec {@link parseParams} decodes with, so an effect-jsonapi endpoint
+* served by a derived handler (`RestHandlers.list`) declares the grammar the
+* handler parses when it is passed as `Endpoint.list(R, { query })`.
+* effect-jsonapi's own `filter: true` derives a grammar from the *resource*
+* instead, and the two spell a to-one relationship's filter differently: the
+* resource grammar names the relationship (`filter[category]=c-audio`), the
+* node graph — and every URL the engine emits ({@link canonical}) — names the
+* key field (`filter[categoryId]=c-audio`, as ADR-0029's URLs do). One codec
+* on both sides keeps the endpoint's contract and the handler's parse the
+* same language. Every edge is includable under it, so a resource served
+* with it declares its collection-valued edges `Relationship.many`, never
+* `paginated` (whose `include=` only the resource grammar refuses). Throws a
+* `QueryError` for an unknown collection — a definition-time defect.
+*/
+const querySchema = (nodes, collection) => codecOf(nodes, nodeOrThrow(nodes, collection)).schema;
+const singleRowCodecs = /* @__PURE__ */ new WeakMap();
+/**
+* The query codec of a collection's `get` endpoint — `include` and
+* `fields[…]` exactly as the node graph declares them, the two parameters a
+* single-resource request takes ({@link singleRowParams}) — for
+* `Endpoint.get(R, { query })`, the counterpart of {@link querySchema}: the
+* endpoint's contract and the derived handler's parse are one grammar on
+* the single-row route too. Throws a `QueryError` for an unknown collection.
+*/
+const singleRowSchema = (nodes, collection) => {
+	const node = nodeOrThrow(nodes, collection);
+	return memoised(singleRowCodecs, nodes, node, () => Query.schema(resourceIn(resourcesOf(nodes), node.type), {
+		include: includeOption(node),
+		fields: true
+	}));
+};
+/** The flat query record: `URLSearchParams` with repeated keys as arrays (as `UrlParams.toRecord` does). */
+const recordOf$1 = (params) => {
+	if (!(params instanceof URLSearchParams)) return { ...params };
+	const record = {};
+	params.forEach((value, key) => {
+		const existing = record[key];
+		record[key] = existing === void 0 ? value : P.isString(existing) ? [existing, value] : [...existing, value];
+	});
+	return record;
+};
+/**
+* The rejection of one query parameter, in the shape every check here
+* raises (`parameter` names the offending key, so a caller answers 400 with
+* `source.parameter`). Exported for a caller that checks a parsed URL
+* against a declaration of its own — the replica-side writer against the
+* resource it is bound to — and must reject the way the codec does.
+*/
+const invalidParameter = (collection, parameter, detail) => new QueryError({
+	message: `Invalid query for "${collection}" (${parameter}): ${detail}`,
+	query: collection,
+	parameter
+});
+const invalid$1 = invalidParameter;
+const nodeOf$1 = (nodes, collection) => {
+	const node = nodes.nodes.get(collection);
+	return node === void 0 ? Effect.fail(new QueryError({
+		message: `Unknown collection: ${collection}`,
+		query: collection
+	})) : Effect.succeed(node);
+};
+/** The `include` tokens of the wire value: the comma form, the repeated key, or both. */
+const includeTokens = (value) => value === void 0 ? [] : (P.isString(value) ? [value] : value).flatMap((item) => item.split(","));
+/**
+* Check `include` before decoding: every path is one of the node's own
+* edges. A nested path is rejected by decision D1; an undeclared edge is
+* rejected so the caller can rule on it (a façade falls through, ADR-0029
+* §1). The codec would reject both too; the check gives the reason.
+*/
+const checkInclude = (node, value) => failFirst(includeTokens(value), (token) => token.includes(".") ? Option.some(invalid$1(node.type, "include", `nested include path "${token}" is not supported; a read includes a node's own edges only (ADR-0028 D1)`)) : node.edges[token] === void 0 ? Option.some(invalid$1(node.type, "include", `"${token}" is not an edge of "${node.type}" (edges: ${Object.keys(node.edges).join(", ")})`)) : Option.none());
+/** Fail with the first item's error, in order; succeed when no item has one. */
+const failFirst = (items, errorOf) => Option.match(Arr.findFirst(items, errorOf), {
+	onNone: () => Effect.void,
+	onSome: Effect.fail
+});
+const keyOf = (segment) => P.isObjectOrArray(segment) ? segment.key : segment;
+/** The types a read on the node can carry: its own and its edge targets'. */
+const carriedTypes$1 = (node) => /* @__PURE__ */ new Set([node.type, ...Object.values(node.edges).map((edge) => edge.target)]);
+/**
+* The rejection of a `fields[type]` projection the read cannot carry, or
+* `undefined` when it can. The codec silently drops such a type; a
+* projection nobody can apply is a client mistake worth a 400, and the same
+* rule keeps {@link canonical} and {@link parseParams} in agreement.
+*/
+const projectionError = (node, type) => {
+	const types = carriedTypes$1(node);
+	return types.has(type) ? void 0 : invalid$1(node.type, `fields[${type}]`, `"${type}" is not a type this read can carry (types: ${[...types].join(", ")})`);
+};
+/** Check every `fields[…]` key before decoding (see {@link projectionError}). */
+const checkFields = (node, record) => failFirst(Object.keys(record), (key) => {
+	const match = /^fields\[(.*)\]$/.exec(key);
+	return Option.fromUndefinedOr(match === null ? void 0 : projectionError(node, match[1] ?? ""));
+});
+/**
+* `page[offset]` and `page[after]` are different pagination idioms — one
+* request names one (#209). The schema alone cannot reject the
+* combination (each key decodes fine on its own), so this runs before
+* decoding, the way {@link checkInclude} rejects a nested path.
+*/
+const checkPage = (node, record) => record["page[after]"] !== void 0 && record["page[offset]"] !== void 0 ? Effect.fail(invalid$1(node.type, "page[offset]", `"page[offset]" and "page[after]" are different pagination idioms; a request names one`)) : Effect.void;
+/** The query-string parameter an issue path names: the flat key itself, or `family[member]` for the nested families. */
+const parameterOf = (path) => {
+	const [head, second] = (path ?? []).map(keyOf);
+	if (!P.isString(head)) return void 0;
+	return (head === "fields" || head === "page") && P.isString(second) ? `${head}[${second}]` : head;
+};
+/** A codec rejection as a `QueryError` naming the parameter (the issue's path is the flat key). */
+const decodeError = (collection) => (error) => {
+	const issue = SchemaIssue.makeFormatterStandardSchemaV1()(error.issue).issues[0];
+	const parameter = parameterOf(issue?.path);
+	return new QueryError({
+		message: `Invalid query for "${collection}"${parameter === void 0 ? "" : ` (${parameter})`}: ${issue?.message ?? error.message}`,
+		query: collection,
+		parameter,
+		cause: error
+	});
+};
+/** Sort terms as `order` tokens (`name`, `-createdAt`). */
+const orderOf = (sort) => sort.map((term) => term.direction === "desc" ? `-${term.field}` : term.field);
+/**
+* The declarative read a decoded query describes, or the typed `QueryError`
+* {@link fromFilterAst} fails with for `decoded.filter` — unreachable in
+* practice (the module doc's note on this call site), carried as a `Result`
+* rather than thrown so {@link parseParams}'s `Effect.Effect<_, QueryError>`
+* contract holds even if that precondition is ever violated.
+*/
+const readOf = (collection, decoded) => {
+	const whereResult = decoded.filter === void 0 ? Result.succeed(void 0) : fromFilterAst(decoded.filter);
+	return Result.map(whereResult, (where) => ({
+		collection,
+		...where === void 0 ? {} : { where },
+		...decoded.include === void 0 || Arr.isReadonlyArrayEmpty(decoded.include) ? {} : { include: Object.fromEntries(decoded.include.map((edge) => [edge, true])) },
+		...decoded.sort === void 0 || Arr.isReadonlyArrayEmpty(decoded.sort) ? {} : { order: orderOf(decoded.sort) },
+		...decoded.page?.limit === void 0 ? {} : { first: decoded.page.limit },
+		...decoded.page?.after === void 0 ? {} : { after: decoded.page.after },
+		...decoded.page?.offset === void 0 ? {} : { offset: decoded.page.offset }
+	}));
+};
+/**
+* Parse a collection's query parameters into a read. `include`, `fields`,
+* `sort`, `page` and `filter` are decoded with the node-derived query codec
+* (unknown filter fields, undeclared operators, literals of the wrong kind,
+* unsortable fields, unknown sparse fields and nested include paths all
+* fail with a `QueryError` naming the parameter) and mapped onto the read;
+* `fields[]` rides beside it as the projection.
+*/
+const parseParams = (nodes, collection, params) => Effect.gen(function* () {
+	const node = yield* nodeOf$1(nodes, collection);
+	const record = recordOf$1(params);
+	yield* checkInclude(node, record["include"]);
+	yield* checkFields(node, record);
+	yield* checkPage(node, record);
+	const decoded = yield* Schema.decodeUnknownEffect(codecOf(nodes, node).schema)(record).pipe(Effect.mapError(decodeError(collection)));
+	return {
+		read: yield* Effect.fromResult(readOf(collection, decoded)),
+		...decoded.fields === void 0 ? {} : { fields: decoded.fields }
+	};
+});
+/** A path segment percent-decoded, or a `QueryError` naming `id` when it is malformed. */
+const decodeId = (collection, segment) => Effect.try({
+	try: () => decodeURIComponent(segment),
+	catch: () => invalid$1(collection, "id", `path segment "${segment}" is not percent-encoded`)
+});
+/**
+* The resource a request path addresses: `…/{type}/{id}` (one row) when the
+* segment before the last names a node, else `…/{type}` (a listing) when
+* the last does. A node named earlier on the path — the spec's related
+* resource (`/products/p-1/variants`) and relationship (`…/relationships/…`)
+* URLs — is not a read this parser serves (read the related collection
+* with its key filter instead), so it is rejected rather than misread as a
+* whole-collection listing.
+*/
+const locate = (nodes, url) => {
+	const segments = url.pathname.split("/").filter((segment) => Str.isNonEmpty(segment));
+	const last = segments.at(-1);
+	const previous = segments.at(-2);
+	if (previous !== void 0 && last !== void 0 && nodes.nodes.has(previous)) return Effect.map(decodeId(previous, last), (id) => ({
+		collection: previous,
+		id
+	}));
+	const message = segments.slice(0, -2).some((segment) => nodes.nodes.has(segment)) ? `Nested resource path "${url.pathname}" is not a read; filter the related collection by its key instead` : last !== void 0 && nodes.nodes.has(last) ? void 0 : `No collection on path "${url.pathname}"`;
+	return message === void 0 && last !== void 0 ? Effect.succeed({ collection: last }) : Effect.fail(new QueryError({
+		message: message ?? `No collection on path "${url.pathname}"`,
+		query: url.pathname
+	}));
+};
+/**
+* The query of a single-row read — `filter[id]=…`, first 1 (ADR-0029 §3) —
+* from a `/{type}/{id}` request's own query, which takes `include` and
+* `fields[…]` only. Shared by {@link parseRead} and the derived `get`
+* handler, which has the id from the route instead of the path.
+*/
+const singleRowParams = (collection, id, params) => {
+	const extra = Arr.findFirst(params.keys(), (key) => key !== "include" && !key.startsWith("fields["));
+	if (Option.isSome(extra)) return Effect.fail(invalid$1(collection, extra.value, `a single-resource request takes "include" and "fields[…]" only`));
+	const widened = new URLSearchParams(params);
+	widened.set("filter[id]", flatFilter(Filter.eq("id", id))["filter[id]"] ?? "");
+	widened.set("page[limit]", "1");
+	return Effect.succeed(widened);
+};
+/**
+* Parse a request URL into a read. The collection is the path's last
+* segment that names a node (`/api/products?…`, any prefix), or the
+* segment before a row id (`/api/products/p-1?…`, which reads as
+* `filter[id]=p-1` with `first` 1). The query is then {@link parseParams}.
+*/
+const parseRead = (nodes, url) => Effect.gen(function* () {
+	const parsed = P.isString(url) ? new URL(url, "http://localhost") : url;
+	const located = yield* locate(nodes, parsed);
+	const params = located.id === void 0 ? parsed.searchParams : yield* singleRowParams(located.collection, located.id, parsed.searchParams);
+	const result = yield* parseParams(nodes, located.collection, params);
+	return located.id === void 0 ? result : {
+		...result,
+		id: located.id
+	};
+});
+const noUrlForm = (collection, detail) => new QueryError({
+	message: `Read on "${collection}" has no URL form: ${detail}`,
+	query: collection
+});
+/** The plan's edge selects as include paths, in code-point order (the include set is unordered). */
+const includeOf = (collection, edges) => edges.map((edge) => {
+	if (edge.first !== void 0) throw noUrlForm(collection, `the per-edge window on "${edge.edge}" (include: { first }) has no query parameter`);
+	return edge.edge;
+}).toSorted((a, b) => Predicate.compareText(a, b));
+const astOf = (collection, predicate) => Option.getOrThrowWith(toFilterAst(predicate), () => noUrlForm(collection, `"${predicate._tag}" carries an Exists node or a null literal`));
+/** Passes {@link filterOf} allows the normal form to settle in; two suffice in practice. */
+const NORMAL_FORM_PASSES = 8;
+/**
+* The plan's root predicate as a filter AST in normal form; `undefined` for
+* the whole collection. Two normalisations meet here: {@link foldConstants}
+* on the engine side (constants, singleton groups) and `Filter.normalise`
+* on the grammar side (member order, deduplication, literal-list order).
+* Each can hand the other new work — deduplicating `Or(x, x)` leaves a
+* singleton group the fold then collapses — so the result is their
+* fixpoint, which makes {@link canonical} idempotent: parsing a canonical
+* string and canonicalising again gives the same string.
+*/
+const filterOf = (collection, declaration, where) => {
+	const settle = (predicate, pass) => {
+		if (pass >= NORMAL_FORM_PASSES) return Option.some(astOf(collection, predicate));
+		if (isTrue(predicate)) return Option.none();
+		const ast = Filter.normalise(astOf(collection, predicate), declaration);
+		const back = fromFilterAst(ast);
+		if (Result.isFailure(back)) throw back.failure;
+		const next = foldConstants(back.success);
+		if (JSON.stringify(next) === JSON.stringify(predicate)) return Option.some(ast);
+		return settle(next, pass + 1);
+	};
+	return Option.getOrUndefined(settle(foldConstants(where), 0));
+};
+/**
+* The decoded query a compiled read denotes. The page comes from the
+* **read**, not the compiled window: an offset read's `root.limit`
+* absorbs `offset` (`Query.plan`'s `rootLimit`, #209), so reconstructing
+* `page[limit]`/`page[after]` from `root` would leak the inflated fetch
+* size into the URL instead of the request the caller actually made.
+*/
+const decodedOf = (compiled, declaration, fields, read) => {
+	const { root } = compiled;
+	const include = includeOf(root.collection, compiled.edges);
+	const filter = filterOf(root.collection, declaration, root.where);
+	const page = read.offset === void 0 ? {
+		...root.limit === void 0 ? {} : { limit: root.limit },
+		...root.cursor === void 0 ? {} : { after: root.cursor }
+	} : {
+		...read.first === void 0 ? {} : { limit: read.first },
+		offset: read.offset
+	};
+	return {
+		...Arr.isReadonlyArrayEmpty(include) ? {} : { include },
+		...fields === void 0 ? {} : { fields: projectionOf(fields) },
+		...filter === void 0 ? {} : { filter },
+		...Arr.isReadonlyArrayEmpty(root.orderBy) ? {} : { sort: root.orderBy },
+		...R.isEmptyReadonlyRecord(page) ? {} : { page }
+	};
+};
+/** A projection with each type's field list in code-point order (a set). */
+const projectionOf = (fields) => Object.fromEntries(Object.entries(fields).map(([type, names]) => [type, names.toSorted(Predicate.compareText)]));
+/**
+* The canonical URL of a read — `/{collection}?{query}` (no API prefix;
+* `parseRead` accepts it back) — through effect-jsonapi's canonical encoder
+* over the compiled plan: one string per plan, whatever spelling the read
+* used (`where` as a map or a predicate, conjuncts in any order, `True`
+* conjuncts). It is the subscription identity of ADR-0029 §2. Throws a
+* `QueryError` for a read the plan or the grammar refuses: an unknown
+* collection or edge, a field outside the filterable set, an `Exists`, a
+* `null` literal, or a per-edge window. A `fields[]` projection rides
+* along when given.
+*/
+const canonical = (nodes, read, fields) => {
+	const compiled = Query$1.plan(nodes, read);
+	const node = nodes.nodes.get(read.collection);
+	if (node === void 0) throw new QueryError({
+		message: `Unknown collection: ${read.collection}`,
+		query: read.collection
+	});
+	Object.keys(fields ?? {}).forEach((type) => {
+		const error = projectionError(node, type);
+		if (error !== void 0) throw error;
+	});
+	const encoded = Result.try({
+		try: () => {
+			const declaration = Resource.filterable(resourceIn(resourcesOf(nodes), node.type));
+			return codecOf(nodes, node).canonical(decodedOf(compiled, declaration, fields, read));
+		},
+		catch: (error) => error instanceof QueryError ? error : new QueryError({
+			message: `Read on "${read.collection}" has no URL form: ${error instanceof Error ? error.message : String(error)}`,
+			query: read.collection,
+			cause: error
+		})
+	});
+	if (Result.isFailure(encoded)) throw encoded.failure;
+	const query = encoded.success;
+	return query === "" ? `/${read.collection}` : `/${read.collection}?${query}`;
+};
+/** {@link canonical} as an effect: the `QueryError` it throws becomes a typed failure. */
+const tryCanonical = (nodes, read) => Effect.suspend(() => {
+	const result = Result.try(() => canonical(nodes, read));
+	if (Result.isSuccess(result)) return Effect.succeed(result.success);
+	return result.failure instanceof QueryError ? Effect.fail(result.failure) : Effect.die(result.failure);
+});
+/**
+* The `Client.UrlReads` seam over this bridge (#159, ADR-0029 §2): pass as
+* `urls` to `Client.make` / `Client.connect` / `Client.fromView` so
+* `client.subscribe(url)` parses through {@link parseRead} and keys the pin
+* by {@link canonical}, and to an engine host (`ServiceWorkerHost.run`) so
+* a page with no Client can register by URL. The `fields[]` projection a
+* URL carries is dropped: it never changes what a subscription syncs
+* (ADR-0029 §5), so two URLs differing only in `fields[]` are one
+* subscription.
+*/
+const urlReads = (nodes) => ({
+	parse: (url) => Effect.map(parseRead(nodes, url), (parsed) => parsed.read),
+	canonical: (read) => tryCanonical(nodes, read)
+});
+/** The attribute schema of a field whose literals have the JS type. */
+const scalarSchema = (type) => type === "string" ? Schema.String : type === "number" ? Schema.Number : Schema.Boolean;
+/** Collect the literal JS types each field of a tree is compared with (mutates `types`). */
+const collectLiteralTypes = (ast, types) => {
+	const add = (field, value) => {
+		const set = types.get(field) ?? /* @__PURE__ */ new Set();
+		set.add(typeof value);
+		types.set(field, set);
+	};
+	switch (ast._tag) {
+		case "Compare": return add(ast.field, ast.value);
+		case "In":
+		case "NotIn": return ast.values.forEach((value) => add(ast.field, value));
+		case "IsNull":
+			types.get(ast.field) ?? types.set(ast.field, /* @__PURE__ */ new Set());
+			return;
+		case "And":
+		case "Or": return ast.members.forEach((member) => collectLiteralTypes(member, types));
+		case "Not": return collectLiteralTypes(ast.member, types);
+	}
+};
+/** The one JS type each field of a tree is compared with (`string` for a field only null-tested). */
+const literalTypesOf = (ast) => {
+	const types = /* @__PURE__ */ new Map();
+	collectLiteralTypes(ast, types);
+	const resolved = /* @__PURE__ */ new Map();
+	types.forEach((kinds, field) => {
+		const [kind, ...rest] = kinds;
+		if (Arr.isReadonlyArrayNonEmpty(rest)) throw new QueryError({
+			message: `Field "${field}" is compared with literals of several types (${[...kinds].join(", ")}); ADR-0028 rule (d) admits one`,
+			parameter: `filter[${field}]`
+		});
+		resolved.set(field, kind ?? "string");
+	});
+	return resolved;
+};
+const flatFilterCodecs = /* @__PURE__ */ new Map();
+/**
+* The codec for encoding a tree without a node graph: each field it names
+* admits every operator, typed by the JS type of its literals. The wire
+* form of a scalar does not depend on its declared kind, so this encodes
+* exactly what the typed codec would. Memoised by the field → type
+* signature, since a backend encodes the same shapes on every pull.
+*/
+const flatFilterCodecOf = (ast) => {
+	const types = literalTypesOf(ast);
+	const signature = [...types].map(([field, type]) => `${field}:${type}`).toSorted(Predicate.compareText).join("\n");
+	const cached = flatFilterCodecs.get(signature);
+	if (cached !== void 0) return cached;
+	const attributes = R.fromIterableWith(types, ([field, type]) => [field, scalarSchema(type).pipe(Filter.able())]);
+	const codec = Query.Filter(Resource.make("query", { attributes }));
+	flatFilterCodecs.set(signature, codec);
+	return codec;
+};
+/**
+* The canonical flat `filter[...]` record of a filter AST — the grammar's
+* own encoder (`Query.Filter`), so the shorthand, the group form, escaping
+* and member order are effect-jsonapi's byte for byte.
+*/
+const flatFilter = (ast) => Schema.encodeSync(flatFilterCodecOf(ast))(ast);
+/**
+* Serialize sort terms into the JSON:API `sort` value (`-field,field`) through
+* the library's `Query.Sort` codec, so the wire encoding matches the spec's
+* descending-prefix convention by construction.
+*
+* Since effect-jsonapi 0.15 the codec's encoded side is `Repeatable`
+* (`string | ReadonlyArray<string>`) because it also decodes the repeated-key
+* spelling; its encoder emits the comma form, and an array is joined into
+* that same form rather than trusted to never appear.
+*/
+const encodeSort = (terms) => {
+	const encoded = Schema.encodeSync(Query.Sort(terms.map((term) => term.field)))(terms.map((term) => ({
+		field: term.field,
+		direction: term.direction
+	})));
+	return P.isString(encoded) ? encoded : encoded.join(",");
+};
+/**
+* Build the JSON:API query string (with its leading `?`, or `` when empty)
+* for `include` / `fields` / `filter` / `sort` / `page`, in the canonical
+* family order and percent-encoding (`Query.serialise`). `filter` is a
+* filter AST, encoded exactly through {@link flatFilter}.
+*/
+const buildQueryString = (options) => {
+	if (options === void 0) return "";
+	const pairs = [];
+	if (options.include && Arr.isReadonlyArrayNonEmpty(options.include)) pairs.push(["include", options.include.join(",")]);
+	pairs.push(...Object.entries(options.fields ?? {}).map(([type, names]) => [`fields[${type}]`, names.join(",")]));
+	if (options.filter !== void 0) pairs.push(...Object.entries(flatFilter(options.filter)));
+	if (options.sort && Arr.isReadonlyArrayNonEmpty(options.sort)) pairs.push(["sort", encodeSort(options.sort)]);
+	pairs.push(...Object.entries(options.page ?? {}).flatMap(([key, value]) => value === void 0 ? [] : [[`page[${key}]`, String(value)]]));
+	const query = Query.serialise(pairs);
+	return query === "" ? "" : `?${query}`;
+};
+/**
+* The request options a subset encodes to, or `None` when its predicate
+* folds to false. The filter is the whole predicate, constants folded;
+* `orderBy` becomes `sort`. Limit and cursor are not pushed: the window is
+* applied locally over the exact filter. Throws a `QueryError` for a
+* predicate with no URL form (`Exists`, a `null` literal).
+*/
+const toRequestOptions = (subset) => {
+	const where = foldConstants(subset.where);
+	if (isFalse(where)) return Option.none();
+	const filter = isTrue(where) ? void 0 : Option.getOrThrowWith(toFilterAst(where), () => noUrlForm(subset.collection, "the predicate carries an Exists node or a null literal"));
+	const sort = subset.orderBy.map((term) => ({
+		field: term.field,
+		direction: term.direction
+	}));
+	return Option.some({
+		...filter === void 0 ? {} : { filter },
+		...Arr.isReadonlyArrayEmpty(sort) ? {} : { sort }
+	});
+};
+/** The shipped encoder: exact under ADR-0028 (see the module doc). */
+const defaultEncoder = { encode: (subset) => Effect.try({
+	try: () => Option.map(toRequestOptions(subset), buildQueryString),
+	catch: (error) => error instanceof QueryError ? error : new QueryError({
+		message: `Subset on "${subset.collection}" could not be encoded: ${error instanceof Error ? error.message : String(error)}`,
+		query: subset.collection,
+		cause: error
+	})
+}) };
+// src/CollectionLoader.ts
+/**
+* CollectionLoader
+*
+* The JSON:API package's place in the v2 model (ADR-0008): a *collection
+* loader*. A JSON:API `type` is a collection, each resource's `id` is a row
+* id, and a resource maps to a row value (attributes + resolved
+* relationship references). Loaders read documents into collection rows;
+* they do not own a sync model of their own.
+*
+* This is a read-side adapter. Writes in the v2 engine are named mutators
+* (ADR-0008), not ad-hoc REST calls, so the former conflict-strategy
+* push/pull helpers are gone. To sync a JSON:API upstream, back a `Backend`
+* (or a read-only collection) with `load`/`loadOne` and emit row versions
+* from the upstream's own change token (ETag, `meta.version`, …).
+*/
+var CollectionLoader_exports = /* @__PURE__ */ __exportAll({
+	JsonApiSource: () => JsonApiSource,
+	buildQueryString: () => buildQueryString,
+	documentToRows: () => documentToRows,
+	load: () => load,
+	loadOne: () => loadOne,
+	parseResponse: () => parseResponse,
+	resourceToRow: () => resourceToRow
+});
+const identifier = (ref) => ({
+	type: ref.type,
+	id: ref.id
+});
+/**
+* `Array.isArray` types its guard as `any[]`, so it does not narrow the
+* `ReadonlyArray` members the schema-derived document types use. This guard
+* narrows them correctly.
+*/
+const isReadonlyArray = (value) => Array.isArray(value);
+/** Map a resource (or bare identifier) to a collection row. */
+const resourceToRow = (resource) => {
+	const full = resource;
+	const relationships = R.filterMap(full.relationships ?? {}, ({ data }) => data === void 0 ? Result.failVoid : Result.succeed(data === null ? null : isReadonlyArray(data) ? data.map(identifier) : identifier(data)));
+	return {
+		collection: resource.type,
+		id: resource.id,
+		value: {
+			type: resource.type,
+			id: resource.id,
+			attributes: full.attributes ?? {},
+			relationships
+		}
+	};
+};
+const dataResources = (data) => data === void 0 || data === null ? [] : isReadonlyArray(data) ? data : [data];
+/** Map a whole document to its primary rows and its `included` rows. */
+const documentToRows = (document) => ({
+	rows: dataResources(document.data).map(resourceToRow),
+	included: (document.included ?? []).map(resourceToRow)
+});
+/** The {@link JsonApiSource} service loaders read from. */
+const JsonApiSource = Context.Service("@thomasfosterau/legation-jsonapi/JsonApiSource");
+const jsonApiHeaders$1 = {
+	"Content-Type": "application/vnd.api+json",
+	Accept: "application/vnd.api+json"
+};
+/** Validate a JSON:API response into a document (non-2xx / `errors` → ApiError). */
+const parseResponse = (response) => Effect.gen(function* () {
+	if (response.status < 200 || response.status >= 300) {
+		const body = yield* response.json.pipe(Effect.orElseSucceed(() => void 0));
+		const candidate = P.isObjectOrArray(body) ? body.errors : void 0;
+		const errors = Array.isArray(candidate) ? candidate : [];
+		return yield* new ApiError({
+			message: `HTTP ${response.status}`,
+			errors
+		});
+	}
+	const json = yield* response.json.pipe(Effect.mapError((cause) => new ParseError({
+		message: "Failed to parse JSON body",
+		cause
+	})));
+	const document = yield* decodeDocument(json);
+	if (document.errors && Arr.isReadonlyArrayNonEmpty(document.errors)) return yield* new ApiError({
+		message: "Document carried errors",
+		errors: document.errors
+	});
+	return document;
+});
+const get = (url) => HttpClientRequest.get(url).pipe(HttpClientRequest.setHeaders(jsonApiHeaders$1));
+/** Load a collection (`GET /{type}`) into rows. */
+const load = (type, options) => Effect.gen(function* () {
+	const source = yield* JsonApiSource;
+	const client = yield* HttpClient.HttpClient;
+	const url = `${source.baseUrl}/${type}${buildQueryString(options)}`;
+	const response = yield* Effect.scoped(client.execute(get(url)));
+	return documentToRows(yield* parseResponse(response));
+});
+/** Load a single resource (`GET /{type}/{id}`); `undefined` if absent. */
+const loadOne = (type, id, options) => Effect.gen(function* () {
+	const source = yield* JsonApiSource;
+	const client = yield* HttpClient.HttpClient;
+	const url = `${source.baseUrl}/${type}/${id}${buildQueryString(options)}`;
+	const response = yield* Effect.scoped(client.execute(get(url)));
+	return documentToRows(yield* parseResponse(response)).rows[0];
+});
+// src/Convention.ts
+/**
+* Convention
+*
+* Convention-first discovery of a JSON:API resource surface from an app's
+* Effect `HttpApi` (the happy path: "bring a JSON:API api, get sync"). We
+* reflect the api's endpoints and classify each one by HTTP method + path
+* into a JSON:API role, so no per-endpoint annotation is required:
+*
+* | method  | path shape      | role     |
+* | ------- | --------------- | -------- |
+* | GET     | `/{type}`       | list     |
+* | GET     | `/{type}/:id`   | getOne   |
+* | POST    | `/{type}`       | create   |
+* | PATCH   | `/{type}/:id`   | update   |
+* | PUT     | `/{type}/:id`   | update   |
+* | DELETE  | `/{type}/:id`   | delete   |
+*
+* The resource `type` (the collection name) is the last static path segment
+* (the segment before a trailing `:id` param, or the final segment). Any
+* prefix (`/api`, version segments) is ignored. Endpoints that don't fit the
+* table — nested routes, RPCs, custom actions — are simply not part of the
+* derived CRUD surface; the app can still call them directly.
+*
+* One endpoint is recognised structurally rather than by path: an atomic
+* operations endpoint (the JSON:API Atomic Operations extension, e.g.
+* effect-jsonapi's `Endpoint.operations`, conventionally `POST /operations`)
+* is any endpoint whose request payload is an `atomic:operations` document.
+* By path shape alone it would read as `create` on a phantom `operations`
+* resource, so `reflectResources` skips it and `reflectAtomic` reports it
+* instead — the backend then pushes a whole batch as one request.
+*/
+var Convention_exports = /* @__PURE__ */ __exportAll({
+	classify: () => classify,
+	isAtomicEndpoint: () => isAtomicEndpoint,
+	isParam: () => isParam,
+	reflectAtomic: () => reflectAtomic,
+	reflectResources: () => reflectResources,
+	segmentsOf: () => segmentsOf
+});
+/** A route template's segments, empty ones dropped (`/todos/:id` is `["todos", ":id"]`). */
+const segmentsOf = (path) => path.split("/").filter((segment) => Str.isNonEmpty(segment));
+/** Whether a template segment is a path parameter (`:id`). */
+const isParam = (segment) => segment.startsWith(":");
+/** Map an HTTP method + whether the route has a trailing id to a CRUD role. */
+const roleOf = (method, hasId) => {
+	switch (method.toUpperCase()) {
+		case "GET": return hasId ? "getOne" : "list";
+		case "POST": return hasId ? void 0 : "create";
+		case "PATCH":
+		case "PUT": return hasId ? "update" : void 0;
+		case "DELETE": return hasId ? "delete" : void 0;
+		default: return;
+	}
+};
+/**
+* Classify a (method, path) into a resource type + role, or `undefined` if
+* it isn't a conventional JSON:API CRUD route — `/{type}` or `/{type}/:id`,
+* where the type is a static segment and the only param is a trailing id
+* (nested routes like `/todos/:id/comments` are not CRUD on a single type).
+*/
+const classify = (method, path) => {
+	const segments = segmentsOf(path);
+	const last = segments.at(-1);
+	if (last === void 0) return void 0;
+	const hasId = isParam(last);
+	const type = hasId ? segments[segments.length - 2] : last;
+	if (type === void 0 || isParam(type)) return void 0;
+	const params = segments.filter(isParam);
+	if (params.length > 1 || params.length === 1 && !hasId) return void 0;
+	const operation = roleOf(method, hasId);
+	return operation === void 0 ? void 0 : {
+		type,
+		operation
+	};
+};
+/** The top-level member that makes a request an atomic operations document. */
+const ATOMIC_OPERATIONS_MEMBER = "atomic:operations";
+/** Depth bound for walking a payload schema's unions and suspensions. */
+const MEMBER_WALK_DEPTH = 8;
+/**
+* Whether a schema is (or, through unions and suspensions, may be) an object
+* with a top-level `atomic:operations` member.
+*/
+const hasAtomicMember = (ast, depth = 0) => {
+	if (depth > MEMBER_WALK_DEPTH) return false;
+	switch (ast._tag) {
+		case "Objects": return ast.propertySignatures.some((property) => property.name === ATOMIC_OPERATIONS_MEMBER);
+		case "Union": return ast.types.some((member) => hasAtomicMember(member, depth + 1));
+		case "Suspend": return hasAtomicMember(ast.thunk(), depth + 1);
+		default: return false;
+	}
+};
+/**
+* Whether an endpoint takes an `atomic:operations` request document: some
+* payload schema (any content type) is an object with a top-level
+* `atomic:operations` member, possibly one arm of a union. This is what
+* makes an endpoint the atomic operations endpoint — not its path, which is
+* configurable.
+*/
+const isAtomicEndpoint = (endpoint) => Iterable.some(endpoint.payload.values(), ({ schemas }) => Iterable.some(schemas, (schema) => hasAtomicMember(schema.ast)));
+const refOf$1 = (group, endpoint) => ({
+	groupId: group.identifier,
+	name: endpoint.identifier,
+	method: endpoint.method,
+	path: endpoint.path
+});
+/**
+* Reflect an `HttpApi` into its JSON:API resource surface. The first endpoint
+* matching each (type, role) wins; later duplicates are ignored. An atomic
+* operations endpoint is never a resource (see `reflectAtomic`).
+*/
+const reflectResources = (api) => {
+	const resources = /* @__PURE__ */ new Map();
+	HttpApi.reflect(api, {
+		onGroup: () => {},
+		onEndpoint: ({ group, endpoint }) => {
+			if (isAtomicEndpoint(endpoint)) return;
+			const role = classify(endpoint.method, endpoint.path);
+			if (role === void 0) return;
+			const existing = resources.get(role.type) ?? { type: role.type };
+			if (existing[role.operation] !== void 0) return;
+			existing[role.operation] = refOf$1(group, endpoint);
+			resources.set(role.type, existing);
+		}
+	});
+	return resources;
+};
+/**
+* Reflect an `HttpApi`'s atomic operations endpoint, if it declares one: the
+* first endpoint whose request payload is an `atomic:operations` document.
+* `JsonApiSync` uses it to push a batch as one all-or-nothing request.
+*/
+const reflectAtomic = (api) => {
+	let atomic;
+	HttpApi.reflect(api, {
+		onGroup: () => {},
+		onEndpoint: ({ group, endpoint }) => {
+			if (atomic === void 0 && isAtomicEndpoint(endpoint)) atomic = refOf$1(group, endpoint);
+		}
+	});
+	return atomic;
+};
+// src/Derive.ts
+/**
+* Derive
+*
+* Turn a discovered JSON:API resource surface (Convention.ts) into the
+* engine's shared model: one `Collection` per resource type, and the three
+* CRUD mutators (create / update / delete) per type that has the matching
+* endpoint. Only the *client* (optimistic) handlers live here — they write
+* the overlay; the authoritative side is JsonApiBackend.ts, which replays
+* the same intents as HTTP calls.
+*
+* Rows are stored as the loader's `ResourceValue` (type, id, attributes,
+* relationship linkage), so the derived collections line up exactly with
+* what `CollectionLoader.documentToRows` produces on the read path.
+*/
+var Derive_exports = /* @__PURE__ */ __exportAll({
+	CreateArgs: () => CreateArgs,
+	DeleteArgs: () => DeleteArgs,
+	RowSchema: () => RowSchema,
+	UpdateArgs: () => UpdateArgs,
+	collectionFor: () => collectionFor,
+	derive: () => derive,
+	mutatorName: () => mutatorName,
+	toRow: () => toRow
+});
+/** Flatten a loaded resource into an engine row (attributes at top level). */
+const toRow = (value) => ({
+	...value.attributes,
+	id: value.id,
+	relationships: value.relationships
+});
+/** Permissive codec for a row (the engine never decodes rows through it). */
+const RowSchema = Schema.Record(Schema.String, Schema.Unknown);
+/** The collection for a resource type: rows keyed by resource id. */
+const collectionFor = (type) => Collection.make({
+	name: type,
+	schema: RowSchema,
+	id: (value) => value.id
+});
+/** The mutator name for a (type, operation): `"{type}/{operation}"`. */
+const mutatorName = (type, operation) => `${type}/${operation}`;
+/** Create: the full resource to insert (client supplies the id). */
+const CreateArgs = Schema.Struct({
+	type: Schema.String,
+	id: Schema.String,
+	attributes: Schema.Record(Schema.String, Schema.Unknown),
+	relationships: Schema.optional(Schema.Record(Schema.String, Schema.Unknown))
+});
+/** Update: a partial attribute patch, merged over the current row. */
+const UpdateArgs = Schema.Struct({
+	type: Schema.String,
+	id: Schema.String,
+	attributes: Schema.Record(Schema.String, Schema.Unknown)
+});
+/** Delete: address one row. */
+const DeleteArgs = Schema.Struct({
+	type: Schema.String,
+	id: Schema.String
+});
+/**
+* Derive collections, CRUD mutators, and operation metadata from a resource
+* map. A mutator is only derived when the resource exposes the corresponding
+* write endpoint (no create endpoint ⇒ no `create` mutator).
+*/
+const derive = (resources) => {
+	const collections = [];
+	const entries = [];
+	const operations = /* @__PURE__ */ new Map();
+	const add = (type, operation, args, local) => {
+		const name = mutatorName(type, operation);
+		entries.push({
+			mutator: Mutator.make(name, args),
+			local
+		});
+		operations.set(name, {
+			operation,
+			type
+		});
+	};
+	resources.forEach((resource) => {
+		const type = resource.type;
+		collections.push(collectionFor(type));
+		if (resource.create !== void 0) add(type, "create", CreateArgs, (args, writer) => writer.put(type, args.id, toRow({
+			type,
+			id: args.id,
+			attributes: args.attributes,
+			relationships: args.relationships ?? {}
+		})));
+		if (resource.update !== void 0) add(type, "update", UpdateArgs, (args, writer) => Effect.gen(function* () {
+			const current = yield* writer.get(type, args.id);
+			yield* writer.put(type, args.id, {
+				...current ?? {
+					id: args.id,
+					relationships: {}
+				},
+				...args.attributes,
+				id: args.id
+			});
+		}));
+		if (resource.delete !== void 0) add(type, "delete", DeleteArgs, (args, writer) => writer.del(type, args.id));
+	});
+	return {
+		collections,
+		registry: Mutator.registry(entries),
+		operations
+	};
+};
+// src/DocumentWriter.ts
+/**
+* DocumentWriter
+*
+* Rows to a JSON:API compound document — the **one serialiser** ADR-0029 §6
+* binds both the derived REST handlers ({@link RestHandlers}, #163) and the
+* replica-side writer behind the service-worker façade
+* ({@link ReplicaDocuments}, #164) to: "same URL, same result". The
+* document is a pure function of the node graph, the read, the resolved
+* rows and the `fields[]` projection — no HTTP, no backend, no clock — so
+* the two sides agree byte for byte on document content whichever source
+* produced the rows.
+*
+* The mapping, node for node (CONTEXT.md: a `type` is a collection, a
+* resource `id` is a row id, a resource is a row value):
+*
+* - **Attributes** are the node's declared attributes, in declaration order,
+*   read off the row value. A `one`-edge's key field (`categoryId`) is not
+*   an attribute: it is linkage.
+* - **Relationships** come from two places. A `one` edge's linkage is its
+*   key on the row (`{ data: { type, id } }`, or `data: null` when the key
+*   is null). A collection-valued edge's linkage is the edge rows the read
+*   resolved onto the row (`related[edge]`): present when the read path
+*   fetched them, absent otherwise — a relationship never claims an empty
+*   list it did not see. A paginated edge always carries the spec's `links`
+*   (`self` / `related`, effect-jsonapi's model of an unbounded
+*   relationship) and, when the read resolved its rows (`include=reviews`
+*   includes a paginated edge like any other; only a per-edge window has no
+*   URL form), their linkage beside the links.
+* - **`included`** holds the rows of every edge the read `include`s, in
+*   code-point order of edge name then root-row order, deduplicated by
+*   `(type, id)` with full linkage checked (`Handlers.buildIncluded`: an
+*   included row no resource identifier in the document references is
+*   thrown at, never emitted). An included resource carries its own
+*   `one`-edge linkage and paginated links, and the collection-valued
+*   linkage the caller resolved for it ({@link Input.linkage} — the third
+*   batch, keyed by the included rows); an edge with no resolved rows is
+*   omitted. The member itself is present exactly when the read has an
+*   `include`, as an empty array when nothing resolved (JSON:API 1.1
+*   §Fetching Includes: a response to a request carrying `include` is a
+*   compound document).
+* - **`fields[type]`** is applied last, to attributes only, on primary and
+*   included resources alike (ADR-0029 §5: a serialisation-time projection
+*   over full rows). Linkage is never projected away.
+* - **`links.self`** is the read's canonical string (`JsonApiQuery.canonical`)
+*   — one string per plan, whatever the request's spelling — and a
+*   collection whose window is full (`first` rows came back) carries
+*   `links.next`: the same canonical query with `page[after]` at the last
+*   row's id, the cursor `Subset.apply` continues from. A short page has no
+*   `next`. An optional `prefix` (the api's mount path) is prepended to
+*   every link; ADR-0029 §6 lets the host differ, nothing else.
+*
+* Only **node rows** are written (a row value carrying the node's attributes
+* and its `one`-edge key fields, as `Node.row` decodes and `Query.run`
+* resolves). The `JsonApiRow` shape of `Derive.ts` (linkage under
+* `relationships`, no node graph) is not a second strategy here: its
+* collections declare no graph to plan against, so nothing can write them
+* until a bridge (`NodeBridge` over the app's resources) gives them one —
+* the seam is {@link relationshipOf}, the one place a row's linkage is read.
+*/
+var DocumentWriter_exports = /* @__PURE__ */ __exportAll({
+	collection: () => collection,
+	data: () => data,
+	idOf: () => idOf$1,
+	relatedValuesOf: () => relatedValuesOf
+});
+/** A row value as a record (a node row always is one). */
+const recordOf = (value) => P.isObjectOrArray(value) ? value : {};
+/** The row id a row value carries (node rows carry `id` in the value). */
+const idOf$1 = (value) => String(recordOf(value)["id"]);
+/** A resolved edge's value as its rows: a list as it is, a single row alone, `null` / `undefined` as none. */
+const relatedValuesOf = (value) => Array.isArray(value) ? value : value === null || value === void 0 ? [] : [value];
+const envOf = (input) => ({
+	nodes: input.nodes,
+	linkage: input.linkage,
+	prefix: input.prefix ?? ""
+});
+/** The node's declared attributes off the row value, in declaration order; absent ones are left out. */
+const attributesOf$1 = (node, value) => {
+	return R.filterMap(node.attributes, (_, field) => {
+		const attribute = value[field];
+		return attribute === void 0 ? Result.failVoid : Result.succeed(attribute);
+	});
+};
+/** The resolved rows of one collection-valued edge of a row: `related` first, then the caller's linkage. */
+const edgeRowsOf = (env, node, row, name) => {
+	const related = row.related?.[name];
+	return Array.isArray(related) ? related : env.linkage?.get(node.type)?.get(row.id)?.[name];
+};
+/**
+* The relationship object of one edge, or `undefined` when nothing is known
+* about it. This is where a row's linkage is read: a `one` edge's key off
+* its `via` field, a collection-valued edge's identifiers off its resolved
+* rows.
+*/
+const relationshipOf = (env, node, row, name) => {
+	const edge = node.edges[name];
+	if (edge === void 0) return void 0;
+	if (edge.kind === "one") {
+		const key = recordOf(row.value)[edge.via];
+		return { data: key === void 0 || key === null ? null : {
+			type: edge.target,
+			id: String(key)
+		} };
+	}
+	const rows = edgeRowsOf(env, node, row, name);
+	const data = rows === void 0 ? void 0 : { data: rows.map((value) => ({
+		type: edge.target,
+		id: idOf$1(value)
+	})) };
+	if (edge.kind === "many") return data;
+	return {
+		links: {
+			self: `${env.prefix}${Handlers.relationshipLink(node.type, row.id, name)}`,
+			related: `${env.prefix}${Handlers.relatedLink(node.type, row.id, name)}`
+		},
+		...data
+	};
+};
+/** The resource object of one row of a node. */
+const resourceOf = (env, node, row) => {
+	const relationships = R.filterMap(node.edges, (_, name) => {
+		const relationship = relationshipOf(env, node, row, name);
+		return relationship === void 0 ? Result.failVoid : Result.succeed(relationship);
+	});
+	return {
+		type: node.type,
+		id: row.id,
+		attributes: attributesOf$1(node, recordOf(row.value)),
+		...R.isEmptyReadonlyRecord(relationships) ? {} : { relationships }
+	};
+};
+/** The edge rows of one included edge across the root rows, as resources of the target node. */
+const includedOf = (env, node, rows, name) => {
+	const edge = node.edges[name];
+	const target = edge === void 0 ? void 0 : env.nodes.nodes.get(edge.target);
+	if (target === void 0) return [];
+	return rows.flatMap((row) => relatedValuesOf(row.related[name]).map((related) => resourceOf(env, target, {
+		id: idOf$1(related),
+		value: related
+	})));
+};
+/** The resource's attributes narrowed to its type's `fields[]` entry, when one is given. */
+const project = (resource, fields) => {
+	const names = fields?.[resource.type];
+	if (names === void 0) return resource;
+	const attributes = R.filter(resource.attributes, (_, field) => names.includes(field));
+	return {
+		...resource,
+		attributes
+	};
+};
+/** The node a read addresses; a read on an unknown collection is a definition defect. */
+const nodeOf = (nodes, read) => {
+	const node = nodes.nodes.get(read.collection);
+	if (node === void 0) throw new Error(`DocumentWriter: unknown collection "${read.collection}"`);
+	return node;
+};
+/**
+* The primary resources and the compound `included`, both projected.
+* `included` is `undefined` for a read with no `include`, so the member is
+* omitted; a read with one gets the array even when it is empty, because a
+* response to a request carrying `include` is a compound document (JSON:API
+* 1.1 §Fetching Includes).
+*/
+const assemble = (input, node) => {
+	const env = envOf(input);
+	const data = input.rows.map((row) => project(resourceOf(env, node, row), input.fields));
+	const include = input.read.include;
+	return {
+		data,
+		included: include === void 0 ? void 0 : Object.keys(include).toSorted(Predicate.compareText).flatMap((name) => includedOf(env, node, input.rows, name)).map((resource) => project(resource, input.fields))
+	};
+};
+/** `links.self`: the read's canonical string behind the prefix. */
+const selfLink = (input) => `${input.prefix ?? ""}${canonical(input.nodes, input.read, input.fields)}`;
+/**
+* The read's resolved rows sliced to the page it actually asked for
+* (#209). An offset read's root window was compiled with
+* `limit = offset + first` (`Query.plan`'s `rootLimit`) so a covering
+* subscription could be judged by the ordinary limit-prefix rule and the
+* window fetched in one shot; `input.rows` therefore holds up to
+* `offset + first` rows in window order, and this is where they are
+* sliced back down to the `first` rows starting at `offset` — the one
+* place both the derived REST handler and the replica-side writer apply
+* the slice, since both call this module. A cursor-paginated read has no
+* `offset`, so its rows are its page already.
+*/
+const pageOf = (input) => {
+	const { offset, first } = input.read;
+	if (offset === void 0) return input.rows;
+	return input.rows.slice(offset, first === void 0 ? void 0 : offset + first);
+};
+/**
+* `links.next` for a full page: an offset read continues at `offset +
+* first` in the same idiom it was asked in; a cursor read continues after
+* the page's last row (`page[after]`), the cursor `Subset.apply` resumes
+* from. A short page — fewer rows than `first`, or no window at all — has
+* no next; switching a cursor request to `page[after]`-of-offset (or vice
+* versa) is never done — pagination links stay in the idiom the request
+* used (#209).
+*/
+const nextLink = (input, page) => {
+	const { first, offset } = input.read;
+	if (first === void 0 || page.length < first) return void 0;
+	const link = (read) => `${input.prefix ?? ""}${canonical(input.nodes, read, input.fields)}`;
+	if (offset !== void 0) return link({
+		...input.read,
+		offset: offset + first
+	});
+	const last = page.at(-1);
+	return last === void 0 ? void 0 : link({
+		...input.read,
+		after: last.id
+	});
+};
+/**
+* `links.prev` for an offset page past the first: the same query at
+* `max(0, offset - first)`. Cursor pagination has no `prev` — a forward
+* cursor names no way back, and ADR-0029's model is unbounded-forward only
+* (#209 adds `prev` for the offset idiom alone).
+*/
+const prevLink = (input) => {
+	const { first, offset } = input.read;
+	if (offset === void 0 || offset <= 0 || first === void 0) return void 0;
+	const read = {
+		...input.read,
+		offset: Math.max(0, offset - first)
+	};
+	return `${input.prefix ?? ""}${canonical(input.nodes, read, input.fields)}`;
+};
+/**
+* The collection document of a read: every row of its page as primary
+* data, the included edges compounded, `links.self` canonical and
+* `links.next` (and, for an offset read past the first page, `links.prev`)
+* when the page is full. Throws for a read the canonical encoder refuses
+* (a per-edge window, an `Exists`) — such a read has no URL, so it is
+* never one a URL produced.
+*/
+const collection = (input) => {
+	const page = pageOf(input);
+	const { data, included } = assemble({
+		...input,
+		rows: page
+	}, nodeOf(input.nodes, input.read));
+	const next = nextLink(input, page);
+	const prev = prevLink(input);
+	return Handlers.collection(data, {
+		...included === void 0 ? {} : { included },
+		links: {
+			self: selfLink(input),
+			...next === void 0 ? {} : { next },
+			...prev === void 0 ? {} : { prev }
+		}
+	});
+};
+/**
+* The single-resource document of a read: the first row as primary data
+* (`null` when the read matched nothing — the caller decides the 404), the
+* included edges compounded, `links.self` canonical.
+*/
+const data = (input) => {
+	const first = input.rows[0];
+	const { data: primary, included } = assemble({
+		...input,
+		rows: first === void 0 ? [] : [first]
+	}, nodeOf(input.nodes, input.read));
+	return Handlers.data(primary[0] ?? null, {
+		...included === void 0 ? {} : { included },
+		links: { self: selfLink(input) }
+	});
+};
+// src/Ledger.ts
+/**
+* Ledger
+*
+* The ledger a `JsonApiBackend` keeps for each client group (#468): the highest
+* acknowledged mutation id per client (`lastMutationIds`) and the permanent
+* rejections it still remembers, each with its reason (#366, #365). A
+* `LedgerStore` is where that state is read from and written to. The default,
+* {@link memory}, keeps nothing, so the backend's own in-memory copy is the
+* ledger and a restart forgets it. {@link keyValue} stores each group's ledger
+* in an Effect `KeyValueStore`, which survives a restart when that store does.
+*/
+var Ledger_exports = /* @__PURE__ */ __exportAll({
+	emptyGroup: () => emptyGroup,
+	keyValue: () => keyValue,
+	memory: () => memory
+});
+/** An empty group ledger: nothing acknowledged, nothing remembered. */
+const emptyGroup = {
+	lastMutationIds: {},
+	rejections: []
+};
+/**
+* The in-memory ledger store: it persists nothing, so the backend keeps each
+* group's ledger in its own memory for the life of the instance. A restart of
+* the backend forgets every acknowledged id and remembered rejection.
+*/
+const memory = {
+	read: () => Effect.succeed(emptyGroup),
+	write: () => Effect.void
+};
+const Rejection = Schema.Struct({
+	clientId: Schema.String,
+	mutationId: Schema.Number,
+	reason: Schema.String
+});
+const GroupLedger = Schema.Struct({
+	lastMutationIds: Schema.Record(Schema.String, Schema.Number),
+	rejections: Schema.Array(Rejection)
+});
+const decodeGroup = Schema.decodeUnknownEffect(GroupLedger);
+/**
+* A ledger store over an Effect `KeyValueStore`: each client group's ledger is
+* one JSON value under `${prefix}${clientGroupId}`. Use a durable key/value
+* store (a file system, SQL or browser storage layer) for it to survive a
+* restart. A stored value that does not decode is a `BackendError`, not an
+* empty ledger, so a corrupt store is never mistaken for a fresh one.
+*/
+const keyValue = (store, options = {}) => {
+	const keyOf = (clientGroupId) => `${options.prefix ?? "legation-jsonapi:ledger:"}${clientGroupId}`;
+	return {
+		read: (clientGroupId) => store.get(keyOf(clientGroupId)).pipe(Effect.mapError((cause) => new BackendError({
+			message: "Ledger read failed",
+			cause
+		})), Effect.flatMap((raw) => raw === void 0 ? Effect.succeed(emptyGroup) : Effect.try({
+			try: () => JSON.parse(raw),
+			catch: (cause) => new BackendError({
+				message: "Ledger is not JSON",
+				cause
+			})
+		}).pipe(Effect.flatMap((value) => decodeGroup(value).pipe(Effect.mapError((cause) => new BackendError({
+			message: "Ledger does not decode",
+			cause
+		}))))))),
+		write: (clientGroupId, ledger) => store.set(keyOf(clientGroupId), JSON.stringify(ledger)).pipe(Effect.mapError((cause) => new BackendError({
+			message: "Ledger write failed",
+			cause
+		})))
+	};
+};
+// src/JsonApiBackend.ts
+/**
+* JsonApiBackend
+*
+* An implementation of the core `Backend` contract (ADR-0009) backed by a
+* JSON:API HTTP surface instead of app-owned storage. This is what lets the
+* library "figure out the sync story" from a plain REST API: the sync server
+* (in-process for the client-direct happy path) drives this backend's three
+* operations, and the existing engine supplies journal, overlay, rebase, and
+* CVR diffing on top.
+*
+* Mapping:
+* - `evaluate` lists the collection (`GET /{type}`), pushing the whole
+*   predicate to the server as the filter grammar's canonical `filter[...]`
+*   form via the `QueryEncoder` (exact under ADR-0028; a predicate that can
+*   never match skips the request) and applying predicate, order and limit
+*   locally with `Subset.apply` — the window is local, and re-running the
+*   filter is redundancy over an exact server answer, not correction.
+*   With `includes`, it adds `?include=...` and harvests the compound document's
+*   related rows, serving auto-subscribed `id IN (...)` subsets from that cache.
+* - `getRows` serves row values from the cache `evaluate` populates and this
+*   backend's own writes keep current (the sync server always evaluates before
+*   fetching put rows in the same pull), falling back to `GET /{type}/{id}`.
+*   The cache reflects this instance's own writes only, so a deployment runs
+*   one JsonApiBackend per server and writes the server only through it
+*   (#447): another writer's changes go unseen, and `getRows` can serve a
+*   superseded row.
+* - `applyMutations` replays the batch as HTTP writes. Each mutation is one
+*   JSON:API write (`Write`: a create, update or delete of one resource —
+*   derived CRUD mutators map directly, and `writes` expresses custom
+*   mutators). With `atomic` configured the whole batch goes as one
+*   `atomic:operations` request (`create` → `add`, `update` → `update`,
+*   `delete` → `remove`, sent with the extension's media type); otherwise
+*   each write is its own `POST`/`PATCH`/`DELETE`.
+*
+* **Versioning.** A plain REST API exposes no row-version token, so versions
+* are a content hash of the resource value: the hash changes iff the row
+* changed, which is exactly what CVR diffing needs.
+*
+* **Change hints.** A push's hints carry each touched row's pre-push value as
+* `oldValues`, as MemoryBackend's do, so topic-derived fan-out (ADR-0023) pokes
+* the windows a row moved away from. A REST API keeps no change token, and
+* nothing here says whether a cached row is still current (a write made
+* elsewhere goes unseen, #447; this backend's own writes do keep its cache
+* current, #395), so the old value is always read: each update or delete does one
+* `GET /{type}/{id}` before its write, once per row per push. A row the push
+* creates was absent before the push, so it is not read (`enterBatchCreate`),
+* unless the server refuses the create and a later write of the row needs its
+* value (`readRefusedCreates`, #402). Every failed read fails the push with
+* BackendError, a 4xx and a 404 included, and so does a 2xx with no resource, so
+* an update or delete is either sent with its old value or not sent. On the
+* atomic path nothing has been written by then, so the retry reads again. On the
+* per-resource path the writes before the failed read have already applied and
+* been acknowledged, so the retry does not resend them
+* and their hints are lost: the at-least-once delivery described below, as for
+* any transient write failure there. A read the server refuses (a 4xx) stalls
+* that client's queue until the refusal is resolved. A resource that receives
+* updates or deletes needs a `getOne` route: without one each of its updates
+* and deletes fails its push, before anything is written. The new value of a
+* create or update is the server's returned document when it sends one, else
+* the row read before the push merged with the write (so a partial PATCH hints
+* the full row), else the written value.
+*
+* **Delivery semantics.** Without a cooperating server there is no
+* server-side mutation-id ledger, so this backend keeps one per client group:
+* the highest acknowledged id per client, and the rejections it remembers.
+* The ledger lives in this instance's memory by default (`Ledger.memory`), so
+* a restart of the backend forgets it: a resent mutation that was already
+* applied looks new, guarded only by the server's own idempotency, if any, and
+* a replayed copy or a pull can no longer report an earlier rejection. A
+* deployment that restarts its backend passes a durable `Ledger.LedgerStore`
+* (`ledger`, e.g. `Ledger.keyValue` over an Effect `KeyValueStore`) to keep
+* both across restarts (#468). Each ledger change is written after the server
+* has applied its writes and before the ids are acknowledged, in the order the
+* push already uses. If that ledger write fails after the server write
+* succeeded, the push fails with a `BackendError`. Mutations acknowledged earlier
+* in the same push keep their acknowledgement; the failed one and the rest of the
+* push are not acknowledged, so the client's resend re-applies them. On the atomic
+* path a rejection recorded before the failing write stays remembered, and the
+* resend records it again. That is the same window as a crash between the two
+* writes, and with or without a store the server's own idempotency is what guards
+* it.
+*
+* Over an atomic operations endpoint (`atomic` set) a push is all-or-nothing
+* per batch: one request, and the ledger advances only once the server has
+* applied every operation in it. A transient failure — transport, 5xx, or a
+* 4xx naming no operation — leaves the server holding nothing and the ledger
+* unmoved, so the client's retry resends the same batch. A 4xx error document
+* whose `source.pointer` names an operation (`Atomic.operationPointer(i)`) is
+* a permanent rejection of that mutation (ADR-0008's poison-mutation
+* semantics): it is recorded as rejected and the batch is resent without it,
+* until the remainder applies or nothing is left; every mutation in the batch
+* is then acknowledged in order (one round trip per rejection, bounded by the
+* batch size). `lid` is supported by the wire format but unused: derived
+* creates carry the client-generated `id`, and no mutator yet needs a
+* server-assigned one.
+*
+* The ledger also remembers the rejections it has made (#366), so a
+* replayed copy of a rejected mutation lists it in `rejected` with the same reason,
+* as MemoryBackend does. A push forgets the rejections below its lowest id per
+* client. The memory is bounded per client: a client that never pushes again keeps
+* its last push's rejections. It assumes one journal per `clientId`, which backend
+* contiguity already requires.
+*
+* Over per-resource endpoints (no `atomic`) delivery is *at-least-once*:
+* make writes idempotent (client-generated ids on create; PATCH/DELETE are
+* naturally idempotent) and retries are safe.
+*/
+var JsonApiBackend_exports = /* @__PURE__ */ __exportAll({
+	make: () => make$2,
+	versionOf: () => versionOf
+});
+const jsonApiHeaders = {
+	"Content-Type": "application/vnd.api+json",
+	Accept: "application/vnd.api+json"
+};
+/** The extension media type an atomic operations request carries both ways. */
+const atomicHeaders = {
+	"Content-Type": Atomic.MEDIA_TYPE,
+	Accept: Atomic.MEDIA_TYPE
+};
+const trimSlashes = (s) => s.replace(/\/+$/, "");
+/** Resolve a route template against the base url, substituting the id param. */
+const urlFor = (baseUrl, path, id) => trimSlashes(baseUrl) + path.replace(/:[^/]+/g, () => encodeURIComponent(id ?? ""));
+/** A content-hash row version: a plain REST API exposes no version token. */
+const versionOf = Hash.contentHash;
+const backendError = (message) => (cause) => new BackendError({
+	message,
+	cause
+});
+/** The refusal for a mutation past its client's next expected id (Backend.ts guarantee 1). */
+const mutationGap = (clientId, expected, got) => new BackendError({ message: `Mutation-id gap for client "${clientId}": expected ${expected}, got ${got}` });
+/** Append `?`/`&`-joined params to an existing query string. */
+const appendQuery = (query, extra) => extra === "" ? query : query === "" ? `?${extra}` : `${query}&${extra}`;
+/**
+* The set of ids a subset pins via an `id IN (...)` / `id = ...` filter, or
+* `undefined` if it isn't id-pinned. Used to recognize auto-subscribed
+* relationship subsets that the include fast-path can serve from cache.
+*/
+const pinnedIds = (predicate) => {
+	switch (predicate._tag) {
+		case "In": return predicate.field === "id" ? new Set(predicate.values.map((value) => String(value))) : void 0;
+		case "Compare": return predicate.op === "eq" && predicate.field === "id" ? /* @__PURE__ */ new Set([String(predicate.value)]) : void 0;
+		case "And": return Option.getOrUndefined(Arr.findFirst(predicate.predicates, (inner) => Option.fromUndefinedOr(pinnedIds(inner))));
+		default: return;
+	}
+};
+/**
+* Fold one applied write's effect into a push's PUT values (mutates `puts`). A
+* put records the row's value. A delete drops an earlier write's value for the
+* row, so a later delete in the same push leaves the hint naming it as a
+* delete (#369).
+*/
+const recordEffect = (puts, collection, id, effect) => {
+	if (effect._tag === "delete") puts.get(collection)?.delete(id);
+	else puts.set(collection, (puts.get(collection) ?? /* @__PURE__ */ new Map()).set(id, effect.value));
+};
+/** Record a touched id under its collection (mutates `touched`). */
+const recordTouched = (touched, collection, id) => {
+	touched.set(collection, (touched.get(collection) ?? /* @__PURE__ */ new Set()).add(id));
+};
+/** The row entry for (collection, id), if this push has entered the row. */
+const entryOf = (acc, collection, id) => acc.rows.get(collection)?.get(id);
+/** Enter a row under (collection, id) (mutates `acc`). */
+const setEntry = (acc, collection, id, entry) => {
+	acc.rows.set(collection, (acc.rows.get(collection) ?? /* @__PURE__ */ new Map()).set(id, entry));
+};
+/**
+* The pre-push values this push read, as the hints' `olds`: the same snapshot
+* MemoryBackend takes before it applies a batch.
+*/
+const oldsOf = (acc) => {
+	const olds = /* @__PURE__ */ new Map();
+	acc.rows.forEach((entries, collection) => entries.forEach((entry, id) => {
+		if (Option.isSome(entry.before)) olds.set(collection, (olds.get(collection) ?? /* @__PURE__ */ new Map()).set(id, entry.before.value));
+	}));
+	return olds;
+};
+/**
+* Fold one applied write into the push: the row's value after it, and the
+* write's effect on the hint. A row the push has not entered was absent before
+* the push wrote it (a create), so it starts with no value.
+*/
+const recordApplied = (acc, write, document) => {
+	const entry = entryOf(acc, write.type, write.id) ?? {
+		before: Option.none(),
+		current: Option.none()
+	};
+	setEntry(acc, write.type, write.id, entry);
+	entry.current = write.operation === "delete" ? Option.none() : Option.some(rowAfter(write, entry.current, document));
+	recordTouched(acc.touched, write.type, write.id);
+	recordEffect(acc.puts, write.type, write.id, Option.isSome(entry.current) ? {
+		_tag: "put",
+		value: entry.current.value
+	} : { _tag: "delete" });
+};
+/** Build a JSON:API write body (`{ data: { type, id, attributes, ... } }`). */
+const writeBody = (type, id, attributes, relationships) => ({ data: {
+	type,
+	id,
+	attributes,
+	...relationships !== void 0 ? { relationships } : {}
+} });
+/** A write's relationships in the row's linkage shape, as `toRow` gives a server document. */
+const linkageOf$1 = (write) => resourceToRow({
+	type: write.type,
+	id: write.id,
+	relationships: write.relationships ?? {}
+}).value.relationships;
+/**
+* The value a create/update writes, as the hint carries it — the same shape
+* `toRow` gives a resource the server returned, so a hint looks alike
+* whichever path produced it and whatever the server answered.
+*/
+const writtenValue = (write) => ({
+	...write.attributes,
+	id: write.id,
+	relationships: linkageOf$1(write)
+});
+/** The row after a partial update: the row read before the push, with the write laid over it. */
+const mergeWrite = (read, write) => ({
+	...read,
+	...write.attributes,
+	id: write.id,
+	relationships: {
+		...read.relationships,
+		...linkageOf$1(write)
+	}
+});
+/**
+* The value a create or update leaves its row with: the server's document when
+* it returned one; otherwise the row's value so far merged with the write; or
+* the written value alone when the push does not know the row.
+*/
+const rowAfter = (write, current, document) => document ?? (Option.isSome(current) ? mergeWrite(current.value, write) : writtenValue(write));
+/** Express a derived CRUD mutator's decoded args as one JSON:API write. */
+const writeOf$1 = (operation, args) => {
+	switch (operation.operation) {
+		case "create": {
+			const a = args;
+			return Effect.succeed({
+				operation: "create",
+				type: operation.type,
+				id: a.id,
+				attributes: a.attributes,
+				...a.relationships !== void 0 ? { relationships: a.relationships } : {}
+			});
+		}
+		case "update": {
+			const a = args;
+			return Effect.succeed({
+				operation: "update",
+				type: operation.type,
+				id: a.id,
+				attributes: a.attributes
+			});
+		}
+		case "delete": {
+			const a = args;
+			return Effect.succeed({
+				operation: "delete",
+				type: operation.type,
+				id: a.id
+			});
+		}
+		default: return Effect.fail(new BackendError({ message: `Operation "${operation.operation}" is not a write` }));
+	}
+};
+/** One write as an atomic operation object (`add` / `update` / `remove`). */
+const operationOf = (write) => {
+	switch (write.operation) {
+		case "create": return {
+			op: "add",
+			data: {
+				type: write.type,
+				id: write.id,
+				attributes: write.attributes ?? {},
+				...write.relationships !== void 0 ? { relationships: write.relationships } : {}
+			}
+		};
+		case "update": return {
+			op: "update",
+			data: {
+				type: write.type,
+				id: write.id,
+				attributes: write.attributes ?? {},
+				...write.relationships !== void 0 ? { relationships: write.relationships } : {}
+			}
+		};
+		case "delete": return {
+			op: "remove",
+			ref: {
+				type: write.type,
+				id: write.id
+			}
+		};
+	}
+};
+/**
+* The index of the operation an error's `source.pointer` names — the
+* operation itself (`Atomic.operationPointer(i)`) or a member below it — or
+* `undefined` when the pointer names none of the `count` operations sent.
+*/
+const operationIndex = (pointer, count) => {
+	const match = /^\/atomic:operations\/(\d+)(?:\/|$)/.exec(pointer);
+	if (match === null) return void 0;
+	const index = Number(match[1]);
+	return index < count && Atomic.operationPointer(index) === `/atomic:operations/${index}` ? index : void 0;
+};
+/** The per-operation rejections an error document carries, by operation index. */
+const rejectionsOf = (body, count, fallbackReason) => {
+	const errors = P.isObjectOrArray(body) && Array.isArray(body.errors) ? body.errors : [];
+	const byIndex = /* @__PURE__ */ new Map();
+	errors.forEach((error) => {
+		const pointer = error?.source?.pointer;
+		if (!P.isString(pointer)) return;
+		const index = operationIndex(pointer, count);
+		if (index === void 0 || byIndex.has(index)) return;
+		byIndex.set(index, error.detail ?? error.title ?? fallbackReason);
+	});
+	return [...byIndex].map(([index, reason]) => ({
+		index,
+		reason
+	}));
+};
+/** The row an `atomic:results` entry carries, if it returned a resource. */
+const resultRow = (result) => {
+	const data = P.isObjectOrArray(result) ? result.data : void 0;
+	const resource = Schema.decodeUnknownOption(ResourceObject)(data);
+	return Option.isSome(resource) ? toRow(resourceToRow(resource.value).value) : void 0;
+};
+/**
+* Enter a row an atomic batch creates, before the batch's one request. The row
+* was absent before the push, so it needs no read: a later update or delete of
+* it in the same batch must not GET it, since that 404 would fail the push. An
+* entry already present (an earlier delete in the batch read the row) is kept.
+* A create the server refuses is the one case where the row may exist; the
+* resend reads it then (`readRefusedCreates`).
+*/
+const enterBatchCreate = (acc, write) => {
+	if (entryOf(acc, write.type, write.id) === void 0) setEntry(acc, write.type, write.id, {
+		before: Option.none(),
+		current: Option.none()
+	});
+};
+/** A stored group ledger, as the backend holds it. */
+const groupOf = (ledger) => {
+	const rejections = /* @__PURE__ */ new Map();
+	ledger.rejections.forEach((entry) => {
+		const ids = rejections.get(entry.clientId) ?? /* @__PURE__ */ new Map();
+		ids.set(entry.mutationId, entry.reason);
+		rejections.set(entry.clientId, ids);
+	});
+	return {
+		acknowledged: new Map(Object.entries(ledger.lastMutationIds)),
+		rejections
+	};
+};
+/** A group as the store holds it. */
+const ledgerOf = (group) => ({
+	lastMutationIds: Object.fromEntries(group.acknowledged),
+	rejections: [...group.rejections].flatMap(([clientId, ids]) => [...ids].map(([mutationId, reason]) => ({
+		clientId,
+		mutationId,
+		reason
+	})))
+});
+/** Build the JsonApiBackend from its config; requires an `HttpClient`. */
+const make$2 = (config) => Effect.gen(function* () {
+	const client = yield* HttpClient.HttpClient;
+	const encoder = config.query ?? defaultEncoder;
+	const includes = config.includes ?? {};
+	const cache = yield* Ref.make(/* @__PURE__ */ new Map());
+	const includedIds = yield* Ref.make(/* @__PURE__ */ new Map());
+	const groups = yield* Ref.make(/* @__PURE__ */ new Map());
+	const ledgerStore = config.ledger ?? memory;
+	const ledgerLock = yield* Semaphore.make(1);
+	const getJson = (url) => Effect.scoped(client.execute(HttpClientRequest.get(url).pipe(HttpClientRequest.setHeaders(jsonApiHeaders))));
+	const transientStatuses = /* @__PURE__ */ new Set([408, 429]);
+	const isPermanentStatus = (status) => status >= 400 && status < 500 && !transientStatuses.has(status);
+	/** Send one write; the resource document it answers with, if it answers with one. */
+	const sendWrite = (request) => Effect.scoped(client.execute(request)).pipe(Effect.mapError(backendError("JSON:API write failed")), Effect.flatMap((response) => {
+		if (response.status >= 200 && response.status < 300) return response.json.pipe(Effect.orElseSucceed(() => void 0), Effect.map(resultRow));
+		const message = `JSON:API write returned HTTP ${response.status}`;
+		return isPermanentStatus(response.status) ? Effect.fail(new MutationRejected({ reason: message })) : Effect.fail(new BackendError({ message }));
+	}));
+	/**
+	* The `getOne` route an update or delete reads its row through. A resource
+	* with no such route cannot be written by update or delete, so the write
+	* fails with BackendError before anything is sent.
+	*/
+	const getOneFor = (type) => {
+		const getOne = config.resources.get(type)?.getOne;
+		return getOne === void 0 ? Effect.fail(new BackendError({ message: `"${type}" has no getOne route, so its updates and deletes cannot read the row before writing it` })) : Effect.succeed(getOne);
+	};
+	/**
+	* Read a row before the push writes it: the value the server holds now. Every
+	* failed read fails the push with BackendError, a 404 and any other 4xx
+	* included, and so does a 2xx whose document carries no resource: an update
+	* or delete that went out without its old value would hint no `oldValues`, so
+	* it is not sent instead. On the atomic path every read precedes the one
+	* request, so nothing is written on a read the push cannot complete. On the
+	* per-resource path the writes before the failed read have already applied,
+	* and their hints are lost (see the module header's delivery note).
+	*
+	* The cache is never consulted here: it has no freshness signal for a write
+	* made elsewhere (a version token would be needed), and this backend's own
+	* writes keep it current for `getRows` only (#395). So each push reads the row.
+	*/
+	const readBefore = (type, id) => Effect.gen(function* () {
+		const getOne = yield* getOneFor(type);
+		const response = yield* getJson(urlFor(config.baseUrl, getOne.path, id)).pipe(Effect.mapError(backendError(`Failed to read ${type}/${id} before writing it`)));
+		if (response.status < 200 || response.status >= 300) return yield* new BackendError({ message: `JSON:API read of ${type}/${id} returned HTTP ${response.status}` });
+		const document = yield* parseResponse(response).pipe(Effect.mapError(backendError(`Invalid JSON:API resource ${type}/${id}`)));
+		const resource = documentToRows(document).rows[0]?.value;
+		if (resource === void 0) return yield* new BackendError({ message: `JSON:API read of ${type}/${id} returned no resource` });
+		return toRow(resource);
+	});
+	/**
+	* Enter a row the write touches. An update or delete reads the row on the
+	* push's first write to it, so the pre-push value is kept for the hint (the
+	* read is `readBefore`, where a cache hit would replace it, #395). A row
+	* already entered is not read again. A create reads nothing and enters no
+	* row: its row is entered when the create applies, or up front for the
+	* atomic path's batch (`enterBatchCreate`).
+	*/
+	const enterRow = (acc, write) => {
+		if (write.operation === "create" || entryOf(acc, write.type, write.id) !== void 0) return Effect.void;
+		return readBefore(write.type, write.id).pipe(Effect.map((before) => setEntry(acc, write.type, write.id, {
+			before: Option.some(before),
+			current: Option.some(before)
+		})));
+	};
+	/**
+	* Refuse a write that cannot be read before it is sent: an update or delete
+	* of a resource with no `getOne` route. Checked for a whole push before its
+	* first write, so a push that cannot be read sends nothing on either path.
+	*/
+	const checkReadable = (write) => write.operation === "create" ? Effect.void : getOneFor(write.type).pipe(Effect.asVoid);
+	/** Enter one write of an atomic batch before its request: a create as absent, others by reading the row. */
+	const enterBatchWrite = (acc, write) => write.operation === "create" ? Effect.sync(() => enterBatchCreate(acc, write)) : enterRow(acc, write);
+	/**
+	* Read the rows the batch's refused creates would have made absent (#402).
+	* The batch entered each row a create touches as absent, which is right only
+	* while the create applies. The server refused these creates, so the row may
+	* exist: when a later update or delete of it is still to be sent, read it
+	* now, before the resend, so that write carries its pre-push value. Each row
+	* is read at most once, and a row no remaining update or delete touches is
+	* not read, so a create that applies never makes a read that can fail the push.
+	*/
+	const readRefusedCreates = (acc, refused, remaining) => Effect.forEach(refused.filter((entry) => entry.write.operation === "create"), (create) => {
+		const { type, id } = create.write;
+		const laterWrite = remaining.some((entry) => entry.index > create.index && entry.write.operation !== "create" && entry.write.type === type && entry.write.id === id);
+		const entry = entryOf(acc, type, id);
+		if (!laterWrite || entry !== void 0 && Option.isSome(entry.before)) return Effect.void;
+		return readBefore(type, id).pipe(Effect.map((row) => setEntry(acc, type, id, {
+			before: Option.some(row),
+			current: Option.some(row)
+		})));
+	}, { discard: true });
+	const cacheRows = (collection, rows) => Ref.update(cache, (current) => {
+		const next = new Map(current);
+		const map = new Map(next.get(collection) ?? []);
+		rows.forEach((value) => map.set(value.id, value));
+		next.set(collection, map);
+		return next;
+	});
+	/**
+	* Bring the cache into line with a write the server has applied (#395): the
+	* row's value after the push's writes so far, or no row once a delete has
+	* applied, so `getRows` never serves a value the push has superseded.
+	*/
+	const cacheApplied = (acc, write) => {
+		const current = entryOf(acc, write.type, write.id)?.current ?? Option.none();
+		return Ref.update(cache, (rows) => {
+			const next = new Map(rows);
+			const map = new Map(next.get(write.type) ?? []);
+			if (Option.isSome(current)) map.set(write.id, current.value);
+			else map.delete(write.id);
+			next.set(write.type, map);
+			return next;
+		});
+	};
+	/** Harvest a compound document's `included` rows; record their ids complete. */
+	const harvestIncluded = (included) => Effect.gen(function* () {
+		const byCollection = Arr.groupBy(included, (row) => row.$collection);
+		yield* Effect.forEach(R.toEntries(byCollection), ([collection, rows]) => cacheRows(collection, rows).pipe(Effect.andThen(Ref.update(includedIds, (current) => {
+			const next = new Map(current);
+			const ids = new Set(next.get(collection) ?? []);
+			rows.forEach((row) => ids.add(row.id));
+			next.set(collection, ids);
+			return next;
+		}))), {
+			concurrency: 1,
+			discard: true
+		});
+	});
+	const entriesFrom = (values, subset) => Subset.apply(values.map((value) => ({
+		id: value.id,
+		value
+	})), subset).map((row) => ({
+		id: row.id,
+		version: versionOf(row.value)
+	}));
+	const evaluate = (_context, subset) => Effect.gen(function* () {
+		const list = config.resources.get(subset.collection)?.list;
+		if (list === void 0) return [];
+		if (Predicate.hasExists(subset.where)) return yield* new BackendError({ message: `JSON:API backend does not support Exists predicates on "${subset.collection}"` });
+		const ids = pinnedIds(subset.where);
+		if (ids !== void 0) {
+			const complete = (yield* Ref.get(includedIds)).get(subset.collection);
+			if (complete !== void 0 && [...ids].every((id) => complete.has(id))) {
+				const cached = (yield* Ref.get(cache)).get(subset.collection);
+				if (cached !== void 0 && [...ids].every((id) => cached.has(id))) return entriesFrom([...cached.values()], subset);
+			}
+		}
+		const encoded = yield* encoder.encode(subset).pipe(Effect.mapError(backendError(`Subset on "${subset.collection}" has no URL form`)));
+		if (Option.isNone(encoded)) return [];
+		const includeParam = (includes[subset.collection] ?? []).join(",");
+		const query = appendQuery(encoded.value, includeParam === "" ? "" : `include=${encodeURIComponent(includeParam)}`);
+		const url = urlFor(config.baseUrl, list.path) + query;
+		const response = yield* getJson(url).pipe(Effect.mapError(backendError(`Failed to list "${subset.collection}"`)));
+		const document = yield* parseResponse(response).pipe(Effect.mapError(backendError(`Invalid JSON:API listing "${subset.collection}"`)));
+		const loaded = documentToRows(document);
+		const values = loaded.rows.map((row) => toRow(row.value));
+		yield* cacheRows(subset.collection, values);
+		yield* harvestIncluded(loaded.included.map((row) => ({
+			...toRow(row.value),
+			$collection: row.collection
+		})));
+		return entriesFrom(values, subset);
+	});
+	const getRows = (_context, collection, ids) => Effect.gen(function* () {
+		const cached = (yield* Ref.get(cache)).get(collection);
+		const getOne = config.resources.get(collection)?.getOne;
+		return (yield* Effect.forEach(ids, (id) => Effect.gen(function* () {
+			const hit = cached?.get(id);
+			if (hit !== void 0) return [{
+				id,
+				version: versionOf(hit),
+				value: hit
+			}];
+			if (getOne === void 0) return [];
+			const response = yield* getJson(urlFor(config.baseUrl, getOne.path, id)).pipe(Effect.mapError(backendError(`Failed to fetch ${collection}/${id}`)));
+			if (response.status === 404) return [];
+			const document = yield* parseResponse(response).pipe(Effect.mapError(backendError(`Invalid JSON:API resource ${collection}/${id}`)));
+			const resource = documentToRows(document).rows[0]?.value;
+			if (resource === void 0) return [];
+			const value = toRow(resource);
+			return [{
+				id,
+				version: versionOf(value),
+				value
+			}];
+		}), { concurrency: 1 })).flat();
+	});
+	/** Decode a pushed mutation's args and express it as one JSON:API write. */
+	const writeFor = (mutation) => Effect.gen(function* () {
+		const definition = config.mutators.get(mutation.mutator);
+		const custom = config.writes?.get(mutation.mutator);
+		const operation = config.operations.get(mutation.mutator);
+		if (definition === void 0 || custom === void 0 && operation === void 0) return yield* UnknownMutator.make(mutation.mutator);
+		const args = yield* Schema.decodeUnknownEffect(definition.args)(mutation.args).pipe(Effect.mapError(backendError(`Invalid args for mutator "${mutation.mutator}"`)));
+		if (custom !== void 0) return yield* Effect.try({
+			try: () => custom(args),
+			catch: backendError(`Invalid args for mutator "${mutation.mutator}"`)
+		});
+		if (operation === void 0) return yield* UnknownMutator.make(mutation.mutator);
+		return yield* writeOf$1(operation, args);
+	});
+	const applyOne = (write) => Effect.gen(function* () {
+		const resource = config.resources.get(write.type);
+		switch (write.operation) {
+			case "create": {
+				const ref = resource?.create;
+				if (ref === void 0) return yield* new BackendError({ message: `No create endpoint for "${write.type}"` });
+				return yield* sendWrite(HttpClientRequest.post(urlFor(config.baseUrl, ref.path)).pipe(HttpClientRequest.setHeaders(jsonApiHeaders), HttpClientRequest.bodyJsonUnsafe(writeBody(write.type, write.id, write.attributes ?? {}, write.relationships))));
+			}
+			case "update": {
+				const ref = resource?.update;
+				if (ref === void 0) return yield* new BackendError({ message: `No update endpoint for "${write.type}"` });
+				return yield* sendWrite(HttpClientRequest.patch(urlFor(config.baseUrl, ref.path, write.id)).pipe(HttpClientRequest.setHeaders(jsonApiHeaders), HttpClientRequest.bodyJsonUnsafe(writeBody(write.type, write.id, write.attributes ?? {}, write.relationships))));
+			}
+			case "delete": {
+				const ref = resource?.delete;
+				if (ref === void 0) return yield* new BackendError({ message: `No delete endpoint for "${write.type}"` });
+				yield* sendWrite(HttpClientRequest.make("DELETE")(urlFor(config.baseUrl, ref.path, write.id)).pipe(HttpClientRequest.setHeaders(jsonApiHeaders)));
+				return;
+			}
+		}
+	});
+	/** The group's ledger, filled from the store on first use. Callers hold `ledgerLock`. */
+	const fillGroup = (clientGroupId) => Effect.gen(function* () {
+		const cached = (yield* Ref.get(groups)).get(clientGroupId);
+		if (cached !== void 0) return cached;
+		const group = groupOf(yield* ledgerStore.read(clientGroupId));
+		yield* Ref.update(groups, (current) => new Map(current).set(clientGroupId, group));
+		return group;
+	});
+	/** A client group's ledger, read under `ledgerLock` so a first read cannot race an update. */
+	const readGroup = (clientGroupId) => Semaphore.withPermit(ledgerLock, fillGroup(clientGroupId));
+	/**
+	* Change a client group's ledger. `change` returns the group it becomes, or
+	* the group it was when nothing changes, and then nothing is written. The
+	* store is written before the new group is kept, so a failed write leaves the
+	* store and this instance agreeing on the old group.
+	*/
+	const updateGroup = (clientGroupId, change) => Semaphore.withPermit(ledgerLock, Effect.gen(function* () {
+		const current = yield* fillGroup(clientGroupId);
+		const next = change(current);
+		if (next === current) return;
+		yield* ledgerStore.write(clientGroupId, ledgerOf(next));
+		yield* Ref.update(groups, (all) => new Map(all).set(clientGroupId, next));
+	}));
+	/** Acknowledge mutations in the ledger, in the order given, in one update. */
+	const bumpLedger = (context, mutations) => Arr.isReadonlyArrayEmpty(mutations) ? Effect.void : updateGroup(context.clientGroupId, (group) => {
+		const acknowledged = new Map(group.acknowledged);
+		mutations.forEach((mutation) => acknowledged.set(mutation.clientId, mutation.mutationId));
+		return {
+			...group,
+			acknowledged
+		};
+	});
+	/** Remember permanent rejections, so a replayed copy of them reports the same outcome (#366). */
+	const rememberRejections = (context, rejected) => Arr.isReadonlyArrayEmpty(rejected) ? Effect.void : updateGroup(context.clientGroupId, (group) => {
+		const rejections = new Map(group.rejections);
+		rejected.forEach((entry) => {
+			const ids = new Map(rejections.get(entry.clientId) ?? []);
+			ids.set(entry.mutationId, entry.reason);
+			rejections.set(entry.clientId, ids);
+		});
+		return {
+			...group,
+			rejections
+		};
+	});
+	/**
+	* Forget the rejections this push's floors have moved past (#355), so the
+	* memory is bounded per client, as MemoryBackend's is.
+	*/
+	const forgetRejections = (context, mutations) => updateGroup(context.clientGroupId, (group) => {
+		const rejections = RejectionMemory.forgetBelow(group.rejections, RejectionMemory.floorsOf(mutations));
+		return rejections === group.rejections ? group : {
+			...group,
+			rejections
+		};
+	});
+	/**
+	* The rejections a push's replayed copies were committed with (an id the ledger
+	* already covers, with a remembered rejection). They are reported again (#366).
+	*/
+	const replayedRejections = (context, mutations) => Effect.gen(function* () {
+		const group = yield* readGroup(context.clientGroupId);
+		return mutations.flatMap((mutation) => {
+			if (mutation.mutationId > (group.acknowledged.get(mutation.clientId) ?? 0)) return [];
+			const reason = group.rejections.get(mutation.clientId)?.get(mutation.mutationId);
+			return reason === void 0 ? [] : [{
+				clientId: mutation.clientId,
+				mutationId: mutation.mutationId,
+				reason
+			}];
+		});
+	});
+	const lastMutationIdsOf = (context) => readGroup(context.clientGroupId).pipe(Effect.map((group) => Object.fromEntries(group.acknowledged)));
+	/** The group's remembered rejections, each with its reason (#365). A pull reports those its watermark covers. */
+	const rememberedRejections = (context) => readGroup(context.clientGroupId).pipe(Effect.map((group) => [...group.rejections].flatMap(([clientId, ids]) => [...ids].map(([mutationId, reason]) => ({
+		clientId,
+		mutationId,
+		reason
+	})))));
+	/**
+	* The mutations a push still has to send, in order, each with its write. A
+	* mutation at or below its client's acknowledged id was already applied, so it
+	* is skipped (idempotent, acknowledged). With `strict`, a mutation past the next
+	* expected id is a gap the push cannot apply, so the push is refused.
+	*/
+	const unacknowledged = (context, mutations, strict) => Effect.gen(function* () {
+		const group = yield* readGroup(context.clientGroupId);
+		const expected = new Map(group.acknowledged);
+		const batch = [];
+		yield* Effect.forEach(mutations, (mutation) => {
+			const last = expected.get(mutation.clientId) ?? 0;
+			if (mutation.mutationId <= last) return Effect.void;
+			if (strict && mutation.mutationId > last + 1) return Effect.fail(mutationGap(mutation.clientId, last + 1, mutation.mutationId));
+			expected.set(mutation.clientId, mutation.mutationId);
+			return Effect.map(writeFor(mutation), (write) => {
+				batch.push({
+					mutation,
+					write
+				});
+			});
+		}, {
+			concurrency: 1,
+			discard: true
+		});
+		return batch;
+	});
+	/**
+	* The mutations a per-resource push still has to send, in order. A mutation
+	* at or below its client's acknowledged id was already applied, so it is
+	* skipped (idempotent, acknowledged). A mutation past the next expected id is a
+	* gap, refused with a `BackendError` before any write of the push is sent, as
+	* the atomic path refuses it (`unacknowledged`, strict). Unlike
+	* `unacknowledged`, nothing is decoded here: the send loop decodes each write
+	* in turn, so an undecodable mutation still fails at its own place in the push.
+	*/
+	const pendingEach = (context, mutations) => Effect.gen(function* () {
+		const expected = new Map((yield* readGroup(context.clientGroupId)).acknowledged);
+		const pending = [];
+		yield* Effect.forEach(mutations, (mutation) => {
+			const last = expected.get(mutation.clientId) ?? 0;
+			if (mutation.mutationId <= last) return Effect.void;
+			if (mutation.mutationId > last + 1) return Effect.fail(mutationGap(mutation.clientId, last + 1, mutation.mutationId));
+			expected.set(mutation.clientId, mutation.mutationId);
+			pending.push(mutation);
+			return Effect.void;
+		}, {
+			concurrency: 1,
+			discard: true
+		});
+		return pending;
+	});
+	/**
+	* Replay each write as its own request (at-least-once, in order). Before the
+	* first request, each pending mutation that decodes is checked for a `getOne`
+	* route, so a write that cannot be read sends nothing. A mutation whose args
+	* do not decode is not checked: the loop fails the push at it, after the
+	* writes before it, as it always has.
+	*/
+	const applyEach = (context, mutations) => Effect.gen(function* () {
+		const acc = {
+			touched: /* @__PURE__ */ new Map(),
+			puts: /* @__PURE__ */ new Map(),
+			rejected: [],
+			rows: /* @__PURE__ */ new Map()
+		};
+		const replays = yield* replayedRejections(context, mutations);
+		const pending = yield* pendingEach(context, mutations);
+		const decoded = yield* Effect.forEach(pending, (mutation) => Effect.gen(function* () {
+			const write = yield* writeFor(mutation).pipe(Effect.option);
+			if (Option.isSome(write)) yield* checkReadable(write.value);
+			return {
+				mutation,
+				write
+			};
+		}));
+		yield* Effect.forEach(decoded, ({ mutation, write: decodedWrite }) => Effect.gen(function* () {
+			const write = Option.isSome(decodedWrite) ? decodedWrite.value : yield* writeFor(mutation);
+			yield* enterRow(acc, write);
+			const outcome = yield* applyOne(write).pipe(Effect.map((document) => ({
+				_tag: "applied",
+				document
+			})), Effect.catchTag("MutationRejected", (error) => Effect.succeed({
+				_tag: "rejected",
+				reason: error.reason
+			})));
+			if (outcome._tag === "applied") {
+				recordApplied(acc, write, outcome.document);
+				yield* cacheApplied(acc, write);
+			} else {
+				const rejection = {
+					clientId: mutation.clientId,
+					mutationId: mutation.mutationId,
+					reason: outcome.reason
+				};
+				acc.rejected.push(rejection);
+				yield* rememberRejections(context, [rejection]);
+			}
+			yield* bumpLedger(context, [mutation]);
+		}), {
+			concurrency: 1,
+			discard: true
+		});
+		const rejected = [...replays, ...acc.rejected];
+		return {
+			lastMutationIds: yield* lastMutationIdsOf(context),
+			hints: Backend.buildChangeHints(acc.touched, acc.puts, oldsOf(acc)),
+			...Arr.isReadonlyArrayNonEmpty(rejected) ? { rejected } : {}
+		};
+	});
+	/** Send one `atomic:operations` request and classify the server's answer. */
+	const sendAtomic = (path, operations) => Effect.gen(function* () {
+		const response = yield* Effect.scoped(client.execute(HttpClientRequest.post(urlFor(config.baseUrl, path)).pipe(HttpClientRequest.bodyText(JSON.stringify({ "atomic:operations": operations }), Atomic.MEDIA_TYPE), HttpClientRequest.setHeaders(atomicHeaders)))).pipe(Effect.mapError(backendError("JSON:API atomic:operations request failed")));
+		const status = response.status;
+		const message = `JSON:API atomic:operations returned HTTP ${status}`;
+		const body = yield* response.json.pipe(Effect.orElseSucceed(() => void 0));
+		if (status >= 200 && status < 300) {
+			const results = P.isObjectOrArray(body) ? body["atomic:results"] : void 0;
+			return {
+				_tag: "applied",
+				results: Array.isArray(results) ? results : []
+			};
+		}
+		if (isPermanentStatus(status)) {
+			const rejections = rejectionsOf(body, operations.length, message);
+			if (Arr.isReadonlyArrayNonEmpty(rejections)) return {
+				_tag: "rejected",
+				rejections
+			};
+		}
+		return yield* new BackendError({ message });
+	});
+	/**
+	* Push the batch as one `atomic:operations` request. Nothing is
+	* acknowledged until the server has applied the whole (remaining) batch;
+	* permanently rejected operations are dropped and the rest resent.
+	*/
+	const applyAtomic = (context, mutations, atomic) => Effect.gen(function* () {
+		const replays = yield* replayedRejections(context, mutations);
+		const batch = yield* unacknowledged(context, mutations, true);
+		const acc = {
+			touched: /* @__PURE__ */ new Map(),
+			puts: /* @__PURE__ */ new Map(),
+			rejected: [],
+			rows: /* @__PURE__ */ new Map()
+		};
+		yield* Effect.forEach(batch, ({ write }) => enterBatchWrite(acc, write), {
+			concurrency: 1,
+			discard: true
+		});
+		const rejectedAt = /* @__PURE__ */ new Map();
+		const round = (pending) => Effect.gen(function* () {
+			if (Arr.isReadonlyArrayEmpty(pending)) return {
+				pending,
+				results: []
+			};
+			const outcome = yield* sendAtomic(atomic.path, pending.map((entry) => operationOf(entry.write)));
+			if (outcome._tag === "applied") return {
+				pending,
+				results: outcome.results
+			};
+			const refused = outcome.rejections.flatMap(({ index }) => {
+				const entry = pending[index];
+				return entry === void 0 ? [] : [entry];
+			});
+			outcome.rejections.forEach(({ index, reason }) => {
+				const entry = pending[index];
+				if (entry !== void 0) rejectedAt.set(entry.index, reason);
+			});
+			const next = pending.filter((entry) => !rejectedAt.has(entry.index));
+			yield* readRefusedCreates(acc, refused, next);
+			return yield* round(next);
+		});
+		const { pending, results } = yield* round(batch.map((entry, index) => ({
+			...entry,
+			index
+		})));
+		yield* Effect.forEach(pending, ({ write }, position) => {
+			recordApplied(acc, write, resultRow(results[position]));
+			return cacheApplied(acc, write);
+		}, {
+			concurrency: 1,
+			discard: true
+		});
+		const rejected = [...rejectedAt].toSorted(([a], [b]) => a - b).flatMap(([index, reason]) => {
+			const entry = batch[index];
+			return entry === void 0 ? [] : [{
+				clientId: entry.mutation.clientId,
+				mutationId: entry.mutation.mutationId,
+				reason
+			}];
+		});
+		yield* rememberRejections(context, rejected);
+		yield* bumpLedger(context, batch.map(({ mutation }) => mutation));
+		const reported = [...replays, ...rejected];
+		return {
+			lastMutationIds: yield* lastMutationIdsOf(context),
+			hints: Backend.buildChangeHints(acc.touched, acc.puts, oldsOf(acc)),
+			...Arr.isReadonlyArrayNonEmpty(reported) ? { rejected: reported } : {}
+		};
+	});
+	const applyMutations = (context, mutations) => Effect.gen(function* () {
+		yield* forgetRejections(context, mutations);
+		return config.atomic === void 0 ? yield* applyEach(context, mutations) : yield* applyAtomic(context, mutations, config.atomic);
+	});
+	return Backend.Backend.of({
+		applyMutations,
+		lastMutationIds: lastMutationIdsOf,
+		rejections: rememberedRejections,
+		evaluate,
+		getRows
+	});
+});
+// src/FacadeWrites.ts
+/**
+* FacadeWrites
+*
+* The pieces of a façade write (ADR-0030) that do not depend on the fetch
+* handler: reading the `Prefer` header (RFC 7240), decoding a write's body
+* **structurally** into a `JsonApiBackend.Write`, and the default **intent
+* mapping** from a `Write` to the graph-derived CRUD mutation the engine
+* journals (`CrudMutation`, graph row form). `JsonApiFacade` composes them.
+*
+* Structural means exactly ADR-0030 §5's list: `data` is an object whose
+* `type` is the route's, whose `id` (when present) is the path's for a
+* `PATCH`, whose `attributes` / `relationships` are objects when present, and
+* whose relationships are `one` edges of the node with `{ type, id }` or
+* `null` linkage. Attribute values are never checked: the server rules on
+* them, and a value it refuses surfaces as a permanent rejection.
+*/
+var FacadeWrites_exports = /* @__PURE__ */ __exportAll({
+	InvalidWriteArgs: () => InvalidWriteArgs,
+	decodeWrite: () => decodeWrite,
+	graphIntentOf: () => graphIntentOf,
+	preferencesOf: () => preferencesOf,
+	writesOf: () => writesOf
+});
+/** Read the `Prefer` headers of a request (several headers and comma-separated lists alike). */
+const preferencesOf = (headers) => {
+	const pairs = Arr.map((headers.get("prefer") ?? "").split(","), (part) => {
+		const [token = ""] = part.split(";");
+		const [rawName = "", ...rest] = token.split("=");
+		const value = rest.join("=").trim().replace(/^"(.*)"$/, "$1").toLowerCase();
+		return [rawName.trim().toLowerCase(), value];
+	});
+	const has = (name, value) => Arr.some(pairs, ([n, v]) => n === name && (value === void 0 || v === value));
+	const wait = Arr.findLast(pairs, ([n, v]) => n === "wait" && /^\d+$/.test(v));
+	const preferences = {
+		respondAsync: has("respond-async"),
+		strict: has("handling", "strict")
+	};
+	return Option.match(wait, {
+		onNone: () => preferences,
+		onSome: ([, v]) => ({
+			...preferences,
+			wait: Number(v)
+		})
+	});
+};
+const refuse = (refusal) => Effect.fail(refusal);
+const invalid = (detail, pointer) => refuse({
+	status: 400,
+	code: "invalid_document",
+	title: "Invalid document",
+	detail,
+	pointer
+});
+const isRecord = (value) => P.isObject(value) && !Array.isArray(value);
+const decodeJson = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Unknown));
+/** The linkage of one relationship: a related id, `null`, or a refusal. */
+const linkageOf = (name, member, node) => {
+	const pointer = `/data/relationships/${name}`;
+	const edge = node.edges[name];
+	if (edge === void 0 || edge.kind !== "one") return refuse({
+		status: 422,
+		code: "unsupported_relationship",
+		title: "Unsupported relationship",
+		detail: edge === void 0 ? `"${name}" is not a relationship of ${node.type}` : `"${name}" is a to-many relationship; its linkage lives on the related resources, not on ${node.type}`,
+		pointer
+	});
+	if (!isRecord(member) || !("data" in member)) return invalid(`relationship "${name}" must be an object with a "data" member`, pointer);
+	const data = member["data"];
+	if (data === null) return Effect.succeed(null);
+	if (!isRecord(data) || !P.isString(data["id"]) || data["type"] !== edge.target) return invalid(`relationship "${name}" must link one "${edge.target}" by type and id, or be null`, `${pointer}/data`);
+	return Effect.succeed(data["id"]);
+};
+/** The body's `data` member as an object, or the refusal for a body that has none. */
+const dataOf = (body) => Effect.gen(function* () {
+	const text = yield* body.pipe(Effect.catch(() => invalid("the request body could not be read", "")));
+	const document = yield* decodeJson(text).pipe(Effect.catch(() => invalid("the request body is not JSON", "")));
+	if (!isRecord(document) || !("data" in document)) return yield* invalid("a write document needs a \"data\" member", "");
+	const data = document["data"];
+	return isRecord(data) ? data : yield* invalid("\"data\" must be a resource object", "/data");
+});
+const clientIdRequired = {
+	status: 503,
+	code: "client_id_required",
+	title: "Client id required",
+	detail: "A create the façade journals offline needs a client-generated id in data.id.",
+	pointer: "/data/id"
+};
+/** The resource id a create or an update addresses, checked against the route's type and path. */
+const idOf = (target, data) => {
+	if (data["type"] !== target.type) return refuse({
+		status: 409,
+		code: "type_mismatch",
+		title: "Type mismatch",
+		detail: `this endpoint writes "${target.type}" resources`,
+		pointer: "/data/type"
+	});
+	const id = data["id"];
+	if (id !== void 0 && !P.isString(id)) return invalid("\"data.id\" must be a string", "/data/id");
+	if (target.operation === "create") return id === void 0 || id === "" ? refuse(clientIdRequired) : Effect.succeed(id);
+	if (id === void 0) return invalid("an update's data needs the id the path names", "/data/id");
+	return id === target.id ? Effect.succeed(id) : refuse({
+		status: 409,
+		code: "id_mismatch",
+		title: "Id mismatch",
+		detail: `"data.id" must be the id the path names ("${target.id}")`,
+		pointer: "/data/id"
+	});
+};
+/** An optional object member of `data` (`attributes`, `relationships`): `{}` when absent. */
+const memberOf = (data, name) => {
+	const member = data[name] ?? {};
+	return isRecord(member) ? Effect.succeed(member) : invalid(`"data.${name}" must be an object`, `/data/${name}`);
+};
+/**
+* Decode a write's body structurally into a `Write` whose `relationships`
+* are flattened into `one`-edge ids by relationship name (`null` clears).
+* A `DELETE` reads no body. Fails with the {@link Refusal} the offline façade
+* answers with; a create without a client id is refused only once the rest
+* of its body has passed.
+*/
+const decodeWrite = (node, target, body) => {
+	if (target.operation === "delete") return Effect.succeed({
+		operation: "delete",
+		type: target.type,
+		id: target.id
+	});
+	return Effect.gen(function* () {
+		const data = yield* dataOf(body);
+		const checked = yield* Effect.result(idOf(target, data));
+		if (Result.isFailure(checked) && checked.failure.code !== "client_id_required") return yield* refuse(checked.failure);
+		const attributes = yield* memberOf(data, "attributes");
+		const relationships = yield* memberOf(data, "relationships");
+		const linkage = yield* Effect.forEach(R.toEntries(relationships), ([name, member]) => Effect.map(linkageOf(name, member, node), (related) => [name, related]), { concurrency: 1 });
+		return {
+			operation: target.operation,
+			type: target.type,
+			id: yield* Result.match(checked, {
+				onFailure: refuse,
+				onSuccess: Effect.succeed
+			}),
+			attributes,
+			relationships: R.fromEntries(linkage)
+		};
+	});
+};
+/**
+* The default intent mapping: the graph-derived CRUD mutations
+* (`CrudMutation`), args in the graph row form — the attributes plus, per
+* `one` edge the payload links, its `via` key.
+*/
+const graphIntentOf = (nodes) => (write) => {
+	const node = nodes.nodes.get(write.type);
+	if (node === void 0) return void 0;
+	const mutator = CrudMutation.name(write.type, write.operation);
+	if (write.operation === "delete") return {
+		mutator,
+		args: {
+			type: write.type,
+			id: write.id
+		}
+	};
+	const linked = Arr.map(R.toEntries(write.relationships ?? {}), ([name, related]) => {
+		const edge = node.edges[name];
+		return edge?.kind === "one" ? Option.some([edge.via, related]) : Option.none();
+	});
+	const vias = Option.all(linked);
+	if (Option.isNone(vias)) return void 0;
+	const attributes = {
+		...write.attributes,
+		...R.fromEntries(vias.value)
+	};
+	return {
+		mutator,
+		args: {
+			type: write.type,
+			id: write.id,
+			attributes
+		}
+	};
+};
+const decodeWriteArgs = Schema.decodeUnknownSync(CrudMutation.WriteArgs);
+const decodeDeleteArgs = Schema.decodeUnknownSync(CrudMutation.DeleteArgs);
+/**
+* One graph-row write as a `JsonApiBackend` write: each `one` edge's `via` key
+* moves out of the attributes into `relationships[edge].data` (`null` linkage
+* when the key is `null`). A key the args do not carry leaves the relationship
+* out, as a payload that did not link it.
+*/
+const writeOf = (node, operation, args) => {
+	const oneEdges = R.toEntries(node.edges).flatMap(([name, edge]) => edge.kind === "one" ? [[name, edge]] : []);
+	const vias = HashSet.fromIterable(oneEdges.map(([, edge]) => edge.via));
+	const relationships = R.fromEntries(oneEdges.flatMap(([name, edge]) => Object.hasOwn(args.attributes, edge.via) ? [[name, { data: P.isString(args.attributes[edge.via]) ? {
+		type: edge.target,
+		id: args.attributes[edge.via]
+	} : null }]] : []));
+	return {
+		operation,
+		type: node.type,
+		id: args.id,
+		attributes: R.filter(args.attributes, (_, field) => !HashSet.has(vias, field)),
+		relationships
+	};
+};
+/**
+* Refuse args whose `type` is not the mutation's own (#529): a `notes/create`
+* naming `secrets` would otherwise write a type the mutation's name, which the
+* server authorised, never covered. `JsonApiBackend` reports the refusal as
+* invalid args, as it does args that do not decode.
+*/
+const sameType = (type, mutator) => (args) => {
+	if (args.type !== type) throw new InvalidWriteArgs({ message: `"${mutator}" writes "${type}", but its args name "${args.type}"` });
+	return args;
+};
+/** Graph-derived CRUD args that do not fit the mutation they were journaled under. */
+var InvalidWriteArgs = class extends Schema.TaggedError()("InvalidWriteArgs", { message: Schema.String }) {};
+/**
+* The inverse of {@link graphIntentOf} (ADR-0030 §5): for every graph-derived
+* CRUD mutation (`CrudMutation`, filtered by `options.writes` as the registry
+* is), how its args replay as one JSON:API write. Pass it as a
+* `JsonApiBackend`'s `writes`, so a node-graph app's journaled `{type}/create`,
+* `{type}/update` and `{type}/delete` reach the server as `POST`, `PATCH` and
+* `DELETE` (or atomic operations), with each `one` edge's `via` key rebuilt as
+* the relationship's linkage. The write's `type` is always the mutation's own:
+* args naming another type are refused ({@link InvalidWriteArgs}).
+*/
+const writesOf = (nodes, options) => new Map(CrudMutation.entries(nodes, options).flatMap((entry) => {
+	const node = nodes.nodes.get(entry.type);
+	if (node === void 0) return [];
+	const name = entry.mutator.name;
+	const operation = entry.operation;
+	return [[name, operation === "delete" ? flow(decodeDeleteArgs, sameType(entry.type, name), (args) => ({
+		operation,
+		type: entry.type,
+		id: args.id
+	})) : flow(decodeWriteArgs, sameType(entry.type, name), (args) => writeOf(node, operation, args))]];
+}));
+// src/MutationStatus.ts
+var MutationStatus_exports = /* @__PURE__ */ __exportAll({
+	current: () => current,
+	defaultMaxWait: () => defaultMaxWait,
+	document: () => document,
+	parseId: () => parseId,
+	resourceType: () => resourceType,
+	segment: () => segment,
+	settled: () => settled,
+	unknownDocument: () => unknownDocument
+});
+/** The JSON:API type of a status resource; `_legation` and this type are never an app's. */
+const resourceType = "legation-mutations";
+/** The path segments of the status route after the api prefix: `/_legation/mutations/{id}`. */
+const segment = "_legation";
+/** The default cap on `Prefer: wait`: a `respondWith` promise must not outlive the worker's patience. */
+const defaultMaxWait = "30 seconds";
+/**
+* The link to the resource a graph-derived CRUD mutation (`{type}/create|update|delete`,
+* args `{ type, id, … }`) addresses: `{prefix}/{type}/{id}`. `undefined` for any other mutation.
+*/
+const resourceLink = (nodes, prefix, state) => {
+	const parts = state.mutator.split("/");
+	const [type = "", operation = ""] = parts;
+	if (parts.length !== 2 || !nodes.nodes.has(type)) return void 0;
+	if (operation !== "create" && operation !== "update" && operation !== "delete") return void 0;
+	const args = state.args;
+	if (!P.isObject(args) || !("id" in args) || !P.isString(args.id)) return void 0;
+	return `${prefix}/${type}/${encodeURIComponent(args.id)}`;
+};
+/** The status document of a tracked mutation; `prefix` is where the api is mounted, as links see it. */
+const document = (nodes, prefix, state) => {
+	const self = `${prefix}/${segment}/mutations/${state.mutationId}`;
+	const resource = resourceLink(nodes, prefix, state);
+	const base = {
+		phase: state.phase,
+		mutator: state.mutator,
+		journaledAt: state.journaledAt
+	};
+	const settledAt = state.settledAt;
+	const timed = settledAt === void 0 ? base : {
+		...base,
+		settledAt
+	};
+	const reason = state.phase === "rejected" ? state.reason : void 0;
+	return { data: {
+		type: resourceType,
+		id: String(state.mutationId),
+		attributes: reason === void 0 ? timed : {
+			...timed,
+			reason
+		},
+		links: resource === void 0 ? { self } : {
+			self,
+			resource
+		}
+	} };
+};
+/** The `404 unknown_mutation` error document. */
+const unknownDocument = (id) => ({ errors: [{
+	status: "404",
+	code: "unknown_mutation",
+	title: "Unknown mutation",
+	detail: `No mutation ${id} is tracked here. It was never journaled by this worker, or it settled and was evicted beyond the retention window, or it settled before this worker started; the three cannot be told apart.`
+}] });
+/** A mutation id as the route carries it: a positive integer, or none. */
+const parseId = (raw) => /^[1-9]\d*$/.test(raw) ? Option.some(Number(raw)) : Option.none();
+/** One mutation's state now, from the engine's map stream (it emits the current map first). */
+const current = (states, mutationId) => Stream.runHead(states).pipe(Effect.map(Option.flatMap((map) => HashMap.get(map, mutationId))));
+/**
+* The mutation's state once it leaves `pending` (or is no longer tracked),
+* or as it is when `wait` elapses first.
+*/
+const settled = (states, mutationId, wait) => states.pipe(Stream.map((map) => HashMap.get(map, mutationId)), Stream.filter((state) => Option.isNone(state) || state.value.phase !== "pending"), Stream.runHead, Effect.map(Option.flatten), Effect.timeoutOption(wait), Effect.flatMap(Option.match({
+	onNone: () => current(states, mutationId),
+	onSome: Effect.succeed
+})));
+// src/Linkage.ts
+/**
+* Linkage
+*
+* What a document's relationships are resolved from beside the URL's
+* includes — shared by the derived REST handlers ({@link RestHandlers}) and
+* the replica-side writer ({@link ReplicaDocuments}), so both sides resolve
+* the same edges for the same declarations and the one serialiser
+* ({@link DocumentWriter}) writes the same bytes (ADR-0029 §6).
+*
+* **Linkage follows the resource's declaration.** effect-jsonapi's resource
+* schemas require every declared relationship on every resource object, so
+* a read resolves, beside its includes, the rows of every `Relationship.many`
+* the resource declares — on the primary resource, and on each included
+* resource's own declaration — and writes them as linkage, not `included`.
+* A `one` relationship's linkage is the edge's key field and costs nothing.
+* The primary resource's `many` relationships ride in the read's second
+* phase (they are selected beside its includes, {@link withLinkage}); the
+* included resources' ride in one more batch keyed by the included rows
+* ({@link resolve}). Nothing the resource does not declare is resolved, so a
+* collection the URL never named is never touched — neither for its cost
+* nor for its policy verdict. A paginated node edge is served under either
+* declaration: as `Relationship.many` it carries the spec's `links` and its
+* rows' linkage (the edge's declared order) and can be `include`d; as
+* `Relationship.paginated` it carries `links` only.
+*
+* A declaration the node graph cannot serve (a relationship that is no
+* edge, or of the other kind, or targeting another type) is a
+* definition-time defect ({@link planOf} throws).
+*
+* The rows come from a {@link Fetch}: the server's authorized batch
+* evaluation on the REST side (`SyncServer.readSubsets`), the replica's
+* local view on the worker side. One plan, one join, whichever source
+* answers (ADR-0025).
+*
+* Package-internal: the two callers import it directly; nothing outside
+* `@thomasfosterau/legation-jsonapi` derives linkage.
+*/
+const declared = (resource, name) => `Linkage: relationship "${name}" of resource "${resource.type}"`;
+const descriptorsOf$1 = (resource) => Object.entries(resource.relationships);
+/** One declared relationship checked against the node's edge of that name: same name, same arity, same target. */
+const checkDeclaration = (resource, node, name, descriptor) => {
+	const edge = node.edges[name];
+	if (edge === void 0) throw new Error(`${declared(resource, name)} is not an edge of the "${node.type}" node`);
+	if ((descriptor.kind === "many" || descriptor.kind === "paginated") === (edge.kind === "one")) throw new Error(`${declared(resource, name)} is "${descriptor.kind}" but the node edge is "${edge.kind}"`);
+	if (descriptor.ref().type !== edge.target) throw new Error(`${declared(resource, name)} targets "${descriptor.ref().type}" but the node edge targets "${edge.target}"`);
+};
+/**
+* The resource's relationships as node edges, each checked against the
+* node's edge of that name. Returns the `Relationship.many` names — the
+* edges resolved for linkage.
+*/
+const manyEdgesOf = (resource, node) => {
+	const descriptors = descriptorsOf$1(resource);
+	descriptors.forEach(([name, descriptor]) => checkDeclaration(resource, node, name, descriptor));
+	return descriptors.flatMap(([name, descriptor]) => descriptor.kind === "many" ? [name] : []);
+};
+/** The linkage plan of a resource over its node (a definition-time check of the whole declaration). */
+const planOf = (nodes, resource, node) => {
+	return {
+		root: manyEdgesOf(resource, node),
+		included: new Map(descriptorsOf$1(resource).flatMap(([name, descriptor]) => {
+			if (descriptor.kind === "paginated") return [];
+			const target = descriptor.ref();
+			const targetNode = nodes.nodes.get(target.type);
+			return targetNode === void 0 ? [] : [[name, manyEdgesOf(target, targetNode)]];
+		}))
+	};
+};
+/** The read to run: the URL's read with the root linkage edges selected beside its includes. */
+const withLinkage = (plan, read) => {
+	const include = {
+		...R.fromIterableWith(plan.root, (name) => [name, true]),
+		...read.include
+	};
+	return R.isEmptyReadonlyRecord(include) ? read : {
+		...read,
+		include
+	};
+};
+/**
+* The collections the declared linkage is resolved from beyond the read's
+* own includes: the targets of the root's declared `many` edges the read
+* does not include, and of every declared `many` edge of each included
+* type. A replica that holds each of these whole answers the linkage
+* exactly as the server does — the coverage requirement
+* `ReplicaDocuments.toCover` states.
+*/
+const collectionsOf = (nodes, node, plan, read) => {
+	const included = read.include ?? {};
+	const roots = plan.root.flatMap((name) => {
+		const edge = node.edges[name];
+		return included[name] === void 0 && edge !== void 0 ? [edge.target] : [];
+	});
+	const nested = Object.keys(included).flatMap((name) => includedTargets(nodes, node, plan, name));
+	return [.../* @__PURE__ */ new Set([...roots, ...nested])];
+};
+/** The targets of the declared `many` edges of included edge `name`'s type. */
+const includedTargets = (nodes, node, plan, name) => {
+	const via = node.edges[name];
+	const target = via === void 0 ? void 0 : nodes.nodes.get(via.target);
+	if (target === void 0) return [];
+	return (plan.included.get(name) ?? []).flatMap((edge) => {
+		const next = target.edges[edge];
+		return next === void 0 ? [] : [next.target];
+	});
+};
+/** The ids of the rows one included edge resolved across the root rows. */
+const includedIds = (rows, name) => {
+	return new Set(rows.flatMap((row) => relatedValuesOf(row.related[name]).map(idOf$1)));
+};
+/** Add an included type's `many` edge to the batch for a set of parents, merging into the entry the batch already has. */
+const addLinkageQuery = (nodes, queries, type, edge, parents) => {
+	const key = `${type}\0${edge}`;
+	const existing = queries.get(key);
+	if (existing !== void 0) {
+		parents.forEach((id) => existing.parents.add(id));
+		return;
+	}
+	const relationship = Collection.relationshipsOf(nodes.collections, type).get(edge);
+	if (relationship === void 0) return;
+	queries.set(key, {
+		type,
+		edge,
+		collection: relationship.collection,
+		field: relationship.foreignField,
+		order: relationship.order ?? [],
+		parents: new Set(parents)
+	});
+};
+/** The included-linkage batch a read needs: one subset per (included type, `many` edge), parents merged. */
+const linkageQueries = (nodes, plan, node, read, rows) => {
+	const queries = /* @__PURE__ */ new Map();
+	Object.keys(read.include ?? {}).forEach((name) => {
+		const edges = plan.included.get(name) ?? [];
+		const parents = includedIds(rows, name);
+		if (Arr.isReadonlyArrayEmpty(edges) || parents.size === 0) return;
+		const type = node.edges[name]?.target;
+		if (type === void 0) return;
+		edges.forEach((edge) => addLinkageQuery(nodes, queries, type, edge, parents));
+	});
+	return [...queries.values()];
+};
+/** The fetched rows of the batch, assigned to their parents: every parent gets every edge, empty or not. */
+const assignLinkage = (queries, fetched) => {
+	const linkage = /* @__PURE__ */ new Map();
+	const bucket = (type, parent, edge) => {
+		const byId = linkage.get(type) ?? /* @__PURE__ */ new Map();
+		linkage.set(type, byId);
+		const edges = byId.get(parent) ?? {};
+		byId.set(parent, edges);
+		return edges[edge] ??= [];
+	};
+	queries.forEach((query) => {
+		query.parents.forEach((parent) => bucket(query.type, parent, query.edge));
+		fetched.forEach((row) => {
+			if (row.collection !== query.collection) return;
+			const parent = String(row.value[query.field]);
+			if (query.parents.has(parent)) bucket(query.type, parent, query.edge).push(row.value);
+		});
+	});
+	return linkage;
+};
+/**
+* Run a read over a row source with the linkage its resource declares:
+* the read's two phases (`Query.runVia`, the root linkage edges selected
+* beside the includes), then the included resources' `many` edges in one
+* more batch, keyed by the included rows. The rows and the linkage are
+* exactly what {@link DocumentWriter} takes.
+*/
+const resolve$1 = (fetchRows, nodes, node, plan, read) => Effect.gen(function* () {
+	const rows = yield* Query$1.runVia(fetchRows, nodes, withLinkage(plan, read));
+	const queries = linkageQueries(nodes, plan, node, read, rows);
+	const fetched = Arr.isReadonlyArrayEmpty(queries) ? [] : yield* fetchRows(queries.map((query) => Subset.make({
+		collection: query.collection,
+		where: Predicate.isIn(query.field, [...query.parents]),
+		orderBy: query.order
+	})));
+	return {
+		rows,
+		linkage: assignLinkage(queries, fetched)
+	};
+});
+// src/ReplicaDocuments.ts
+/**
+* ReplicaDocuments
+*
+* JSON:API documents written from the **replica** (issue #164): the
+* worker-side caller of {@link DocumentWriter}, the counterpart of the
+* derived REST handlers ({@link RestHandlers}) that write the same
+* documents from the backend. Given the node graph and a local view, a URL
+* (or a parsed read with its `fields[]` projection) runs as a read over the
+* rows the replica holds — `Query.runVia` over the view, the two-phase
+* include of ADR-0025 with the plan's edge windows applied — and its rows
+* are serialised by the one serialiser, so the same URL yields the same
+* document content on either side (ADR-0029 §6). The document sees the
+* optimistic overlay exactly as `Client.query` does (ADR-0029 §4); it
+* depends on nothing but `effect` and the two legation packages, so it runs
+* where the engine runs — a service worker included.
+*
+* **How the replica learns which relationships to emit.** The REST tier
+* derives its linkage from the endpoint's effect-jsonapi resource: every
+* `Relationship.many` the resource declares is resolved beside the URL's
+* includes and written as linkage ({@link Linkage}). The replica takes the
+* same input — a resource declaration per type ({@link Options.resources})
+* — and derives its plan through the same function, so for the same
+* declarations both sides resolve the same edges and write the same bytes
+* by construction; the façade (#166) is built from the app's `HttpApi` and
+* has these declarations at hand. An app that has only the node graph
+* passes nothing and gets `JsonApiQuery.resourcesOf(nodes)`: the synthetic
+* resources whose relationships are the node's edges — every collection
+* edge (paginated ones as `many`) resolved for linkage — which a REST
+* handler built over the same synthetic resources reproduces. A resource
+* the node graph cannot serve is a definition-time defect here as there.
+*
+* **One grammar on both sides.** A URL is parsed with the node-derived
+* codec (`JsonApiQuery.parseRead`), so parity holds when the endpoint is
+* declared with the same codec — `JsonApiQuery.querySchema(nodes,
+* collection)`, or declarations equivalent to it: a filter names the edge's
+* key field (`filter[categoryId]`), `sort` admits the node's sortable set
+* and `id`, and collection edges are `many` (a `paginated` declaration
+* refuses `include=` the node grammar accepts). Where the bound resource
+* declares less than the node — an edge it leaves out, a type it never
+* reaches — the endpoint cannot emit what the URL asks for, so the replica
+* refuses it the same way the codec would: an `include` edge or a
+* `fields[type]` type the resource does not declare is a `QueryError`
+* naming the parameter, raised before the read runs.
+*
+* **What the replica must hold.** The writer resolves everything from the
+* local view and cannot tell a missing row from an absent one, so a
+* document is faithful only when the replica holds every row the read and
+* its linkage need. That is the caller's coverage check (ADR-0029 §3,
+* `Client.coverageOf`): {@link ReplicaDocuments.toCover} names the reads a
+* request needs covered — the URL's read as stated, plus one
+* whole-collection read per collection the declared linkage resolves from
+* beyond the read's includes (the root's declared `many` edges the URL did
+* not include, and every declared `many` edge of each included type). A
+* replica holding each of those whole (under the same auth filter the
+* server applies) answers the linkage exactly as the server does. The
+* requirement is sound and conservative: a pin that holds an edge window
+* without the whole collection is not credited, and a read that is
+* uncovered goes to the network unchanged (ADR-0029 §4). The façade serves
+* a URL only when every read `toCover` lists is covered; this module never
+* decides that itself.
+*
+* A URL is network input, so nothing about it is a defect: a collection no
+* bound resource declares fails every entry point with a `QueryError`, and
+* the façade routes the request to the network.
+*/
+var ReplicaDocuments_exports = /* @__PURE__ */ __exportAll({
+	fetchOf: () => fetchOf,
+	make: () => make$1
+});
+/**
+* The local view as a row source: each subset evaluated over the replica
+* (confirmed rows with the optimistic overlay), rows tagged with their
+* collection, batches concatenated in subset order — the shape
+* `SyncServer.readSubsets` gives the REST tier. The subsets of a batch are
+* independent, so they run concurrently. A store failure is a defect, as
+* `Query.run` treats it.
+*/
+const fetchOf = (view) => (subsets) => Effect.forEach(subsets, (subset) => view.query(subset).pipe(Effect.orDie, Effect.map((rows) => rows.map((row) => ({
+	collection: subset.collection,
+	id: row.id,
+	value: row.value
+})))), { concurrency: "unbounded" }).pipe(Effect.map((batches) => batches.flat()));
+/** Every resource bound to its node (a definition-time check of each declaration). */
+const bindAll = (nodes, resources) => {
+	const bindings = /* @__PURE__ */ new Map();
+	resources.forEach((resource) => {
+		const node = nodes.nodes.get(resource.type);
+		if (node === void 0) throw new Error(`ReplicaDocuments: no node "${resource.type}" in the graph for the resource`);
+		bindings.set(resource.type, {
+			node,
+			resource,
+			plan: planOf(nodes, resource, node)
+		});
+	});
+	return bindings;
+};
+const descriptorsOf = (resource) => resource.relationships;
+/** The types a resource's document can carry: its own and its relationships' targets. */
+const carriedTypes = (resource) => [resource.type, ...Object.values(descriptorsOf(resource)).map((descriptor) => descriptor.ref().type)];
+/**
+* The rejection of what the bound resource does not declare, in the codec's
+* shape: an `include` edge that is no relationship of the resource, or a
+* `fields[type]` type its document cannot carry. Checked before the read
+* runs, so a refused request costs no query.
+*/
+const undeclared = (binding, parsed) => {
+	const { resource } = binding;
+	const relationships = descriptorsOf(resource);
+	const name = Object.keys(parsed.read.include ?? {}).find((included) => relationships[included] === void 0);
+	if (name !== void 0) return invalidParameter(resource.type, "include", `"${name}" is not a relationship the "${resource.type}" resource declares (relationships: ${Object.keys(relationships).join(", ")})`);
+	const types = carriedTypes(resource);
+	const type = Object.keys(parsed.fields ?? {}).find((projected) => !types.includes(projected));
+	if (type !== void 0) return invalidParameter(resource.type, `fields[${type}]`, `"${type}" is not a type the "${resource.type}" resource can carry (types: ${types.join(", ")})`);
+};
+/** Bind the replica-side writer to a graph and its declarations (a definition-time check of every declaration). */
+const make$1 = (options) => {
+	const { nodes, prefix } = options;
+	const bindings = bindAll(nodes, options.resources ?? resourcesOf(nodes));
+	/** The binding of a read's collection; a type nothing declares is the URL's failure, not a defect. */
+	const bound = (read) => {
+		const binding = bindings.get(read.collection);
+		return binding === void 0 ? Effect.fail(new QueryError({
+			message: `No resource declares "${read.collection}"; the replica cannot serve it`,
+			query: read.collection
+		})) : Effect.succeed(binding);
+	};
+	/** The binding of a parsed read, with what the resource does not declare refused. */
+	const checked = (parsed) => Effect.flatMap(bound(parsed.read), (binding) => {
+		const error = undeclared(binding, parsed);
+		return error === void 0 ? Effect.succeed(binding) : Effect.fail(error);
+	});
+	/** The writer's input for a parsed read's rows off the view. */
+	const input = (view, parsed) => Effect.flatMap(checked(parsed), ({ node, plan }) => resolve$1(fetchOf(view), nodes, node, plan, parsed.read).pipe(Effect.map((resolved) => ({
+		nodes,
+		read: parsed.read,
+		rows: resolved.rows,
+		linkage: resolved.linkage,
+		...parsed.fields === void 0 ? {} : { fields: parsed.fields },
+		...prefix === void 0 ? {} : { prefix }
+	}))));
+	const collection$1 = (view, parsed) => Effect.map(input(view, parsed), collection);
+	const data$1 = (view, parsed) => Effect.map(input(view, parsed), data);
+	const fromUrl = (view, url) => parseRead(nodes, url).pipe(Effect.flatMap((parsed) => parsed.id === void 0 ? collection$1(view, parsed) : data$1(view, parsed)));
+	const toCover = (read) => Effect.map(bound(read), ({ node, plan }) => [read, ...collectionsOf(nodes, node, plan, read).map((name) => ({ collection: name }))]);
+	return {
+		collection: collection$1,
+		data: data$1,
+		fromUrl,
+		toCover
+	};
+};
+// src/RestHandlers.ts
+/**
+* RestHandlers
+*
+* Derived JSON:API `list` / `get` handlers over the sync engine's read path
+* (issue #163). A JSON:API `GET` is ADR-0025's `read` operation with a
+* document body: the URL is parsed into a `Query.Read` by the one grammar
+* (`JsonApiQuery.parseParams`), the request's identity becomes a
+* `SyncContext`, the read runs through `Query.plan` → the filterable check
+* and the deny-by-default auth filters (`Authorization.authorize`) →
+* `Backend.evaluate` + `getRows` with ADR-0025's two-phase include
+* resolution (`Query.runVia` over `SyncServer.readSubsets` — the very
+* function the protocol's `handleRead` runs), and the rows are serialised
+* by {@link DocumentWriter}. Two carriers, one evaluator, one auth path:
+* what the sync tier syncs for a window is what the REST tier answers for
+* the same URL, so a façade serving that URL from the replica (ADR-0029 §6)
+* can match it.
+*
+* Scoping is the auth policy's, never the handler's: a request without
+* identity to a private collection sees the policy's empty allow-set —
+* an empty collection for `list`, a 404 for `get` — exactly as the sync
+* tier's `isIn(field, [])` behaves. No `WHERE userId` lives here.
+*
+* Sorting and paging are `Subset.apply`'s (ADR-0026 / ADR-0028): code-point
+* text order, NULLs last, the id tie-break, `page[after]` as the cursor —
+* the REST tier inherits them by construction.
+*
+* **Linkage follows the resource's declaration** ({@link Linkage}, shared
+* with the replica-side writer): beside the URL's includes, the rows of
+* every `Relationship.many` the endpoint's resource declares are resolved —
+* on the primary resource, and on each included resource's own declaration
+* — and written as linkage, not `included`; nothing the resource does not
+* declare is touched. A paginated node edge under `Relationship.paginated`
+* carries `links` only, and the endpoint's own codec refuses `include=`
+* for it. A declaration the node graph cannot serve is a definition-time
+* defect, thrown when the handler is built.
+*
+* **Outcomes the derivation owns.** A URL the grammar rejects is answered
+* with the codec's 400 error document, `source.parameter` naming the
+* offending key, before any backend call; a collection the policy denies
+* (no auth filter declared) is a 403, and within a batch every subset is
+* authorized before any is evaluated. Both are written as JSON:API error
+* responses by the handler — effect-jsonapi's `ApiError` classes carry no
+* `source` member, and every endpoint already declares the 400. A `get`
+* that matches no row fails with the error the caller declares on the
+* endpoint (`notFound`), so the api's own 404 class is what the client
+* decodes. A backend failure is a defect (500), as the hand-written
+* handlers' `orDie` made it.
+*
+* Derivation is opt-in per endpoint: `handlers.handle("list", rest.list(Product))`
+* beside hand-written handlers on the same api.
+*/
+var RestHandlers_exports = /* @__PURE__ */ __exportAll({
+	make: () => make,
+	queryErrorDocument: () => queryErrorDocument
+});
+/**
+* The 400 error document of a URL the grammar rejects: the codec's own
+* document (`Middleware.schemaErrorDocument`, one error object per issue,
+* each with `source.parameter`) when the rejection came from decoding; the
+* same shape around the `QueryError`'s message and `parameter` when it came
+* from the graph checks that run before decoding (an undeclared include, a
+* `fields[]` type the read cannot carry). The façade answers a parse failure
+* with this document too (ADR-0029 §1).
+*/
+const queryErrorDocument = (error) => {
+	if (Schema.isSchemaError(error.cause)) return Middleware.schemaErrorDocument("Query", error.cause);
+	return { errors: [{
+		status: String(ApiError$1.BadRequest.status),
+		code: ApiError$1.BadRequest.code,
+		...ApiError$1.BadRequest.title === void 0 ? {} : { title: ApiError$1.BadRequest.title },
+		detail: error.message,
+		...error.parameter === void 0 ? {} : { source: { parameter: error.parameter } }
+	}] };
+};
+/** The 403 error document of a collection the policy denies. */
+const forbiddenDocument = (error) => ({ errors: [{
+	status: String(ApiError$1.Forbidden.status),
+	code: ApiError$1.Forbidden.code,
+	...ApiError$1.Forbidden.title === void 0 ? {} : { title: ApiError$1.Forbidden.title },
+	detail: error.message
+}] });
+/** An error document as a JSON:API response. */
+const errorResponse = (status, document) => HttpServerResponse.jsonUnsafe(document, {
+	status,
+	contentType: MEDIA_TYPE
+});
+/** `HttpServerRequest.url` is path + query; any origin makes it parseable. */
+const searchParamsOf = (request) => new URL(request.url, "http://localhost").searchParams;
+/** An outcome the derivation owns, as a response; a backend failure is a defect. */
+const respondToFailures = (effect) => Effect.catch(effect, (error) => {
+	if (error instanceof QueryError) return Effect.succeed(errorResponse(ApiError$1.BadRequest.status, queryErrorDocument(error)));
+	if (error instanceof AuthorizationError) return Effect.succeed(errorResponse(ApiError$1.Forbidden.status, forbiddenDocument(error)));
+	if (error instanceof BackendError) return Effect.die(error);
+	return Effect.fail(error);
+});
+/**
+* Bind the derived handlers to a graph and a read path. The node of a
+* resource is looked up by its `type` when the handler is built and the
+* resource's relationships are checked against the node's edges then, so a
+* declaration the graph cannot serve is a definition-time defect, never a
+* 500.
+*/
+const make = (options) => {
+	const { nodes, backend, policy, middleware, prefix } = options;
+	const deps = {
+		backend,
+		authPolicy: policy,
+		...middleware && { middleware }
+	};
+	const nodeOf = (resource) => {
+		const node = nodes.nodes.get(resource.type);
+		if (node === void 0) throw new Error(`RestHandlers: no node "${resource.type}" in the graph for the resource`);
+		return node;
+	};
+	const run = (context, node, plan, read) => resolve$1((subsets) => SyncServer.readSubsets(deps, context, {
+		clientGroupId: context.clientGroupId,
+		subsets
+	}), nodes, node, plan, read);
+	/** The writer's input for a read's rows (the projection and prefix only when given). */
+	const input = (read, resolved, fields) => ({
+		nodes,
+		read,
+		rows: resolved.rows,
+		linkage: resolved.linkage,
+		...fields === void 0 ? {} : { fields },
+		...prefix === void 0 ? {} : { prefix }
+	});
+	const list = (resource) => {
+		const node = nodeOf(resource);
+		const plan = planOf(nodes, resource, node);
+		return ({ request }) => respondToFailures(Effect.gen(function* () {
+			const context = yield* options.context(request);
+			const { read, fields } = yield* parseParams(nodes, node.type, searchParamsOf(request));
+			const resolved = yield* run(context, node, plan, read);
+			return collection(input(read, resolved, fields));
+		}));
+	};
+	const get = (resource, { notFound }) => {
+		const node = nodeOf(resource);
+		const plan = planOf(nodes, resource, node);
+		return ({ params, request }) => respondToFailures(Effect.gen(function* () {
+			const context = yield* options.context(request);
+			const single = yield* singleRowParams(node.type, params.id, searchParamsOf(request));
+			const { read, fields } = yield* parseParams(nodes, node.type, single);
+			const resolved = yield* run(context, node, plan, read);
+			if (Arr.isReadonlyArrayEmpty(resolved.rows)) return yield* Effect.fail(notFound());
+			return data(input(read, resolved, fields));
+		}));
+	};
+	return {
+		list,
+		get
+	};
+};
+// src/JsonApiFacade.ts
+/**
+* JsonApiFacade
+*
+* The façade of ADR-0029 (issue #166): a fetch handler that answers a
+* JSON:API `GET` from the replica when an explicit subscription covers it,
+* and stays out of the way otherwise. A service worker composes it into its
+* `fetch` listener **first**, before the HTTP cache and the network, so a
+* cached copy never becomes a second source of truth for a locally
+* answerable document (ADR-0029 §1).
+*
+* The handler is built from the app's `HttpApi` and the replica it reads:
+*
+* 1. **Route reflection.** `Convention.reflectResources(api)` gives the
+*    `list` and `getOne` routes per type; those whose type is a node of the
+*    graph are kept, so a route the replica cannot read (a server-only
+*    resource) is never the façade's. A request is its business iff its
+*    method is `GET`, its `Accept` names `application/vnd.api+json`, and its
+*    path — under {@link Options.baseUrl} — matches one of those route
+*    templates segment for segment. Anything else yields `undefined` and
+*    the caller composes what comes next.
+* 2. **Parse.** The URL becomes a `Query.Read` through the one grammar
+*    (`JsonApiQuery.parseRead`). A URL the grammar rejects is answered with
+*    the codec's 400 error document (`RestHandlers.queryErrorDocument`),
+*    whether or not the request is covered, because the server rejects it
+*    identically — except an `include` the graph does not declare, which
+*    goes to the network where the server rules on it (ADR-0029 §1), and a
+*    path the graph cannot place, likewise.
+* 3. **Coverage.** Every read `ReplicaDocuments.toCover` names for the
+*    request — the read itself and the whole collections its declared
+*    linkage resolves from — is checked with {@link Options.coverageOf}, the
+*    ledger's verdict (`Client.coverageOf`, or `Coverage.coverageOf` over
+*    the registrations an `EngineHost` holds on mirrors' behalf). One
+*    uncovered read sends the request to the network unchanged.
+* 4. **Answer.** A covered read runs over the view — confirmed rows with the
+*    optimistic overlay, exactly what `Client.query` sees for a covered read
+*    — and is serialised by the one writer, so the document's content is
+*    byte-equal to the derived REST handler's for the same declarations
+*    (ADR-0029 §6). The response is `200` `application/vnd.api+json` with
+*    `Cache-Control: no-store` (the replica is the cache) and
+*    `x-legation-served-at: <cookie>`, the replica's CVR cookie at the time
+*    of the answer, so devtools and tests can
+*    tell a local answer from a network one.
+* 5. **Offline.** An uncovered request while the network is unreachable —
+*    `navigator.onLine === false` here, or a forwarded fetch that rejected
+*    at the transport in the caller ({@link FetchHandler.offline}) — is
+*    answered with the 503 `offline` error document, the one error the
+*    façade synthesises that the server never would (ADR-0029 §4). A status
+*    code from the server is never offline, and a covered request is never
+*    affected by connectivity.
+*
+* **The parity assumption.** Answering a parse failure locally, and a
+* covered request at all, presumes the server rules on the same URL the
+* same way: its read endpoints are declared with the graph's own codec
+* (`JsonApiQuery.querySchema` for a `list`, `singleRowSchema` for a `get`)
+* and served by the derived handlers (`RestHandlers`), as the commerce
+* example does. A hand-written server with another grammar — a filter key
+* the node does not declare, a `sort` the codec refuses, a different `page`
+* vocabulary — must not compose the façade: its 400s and its documents
+* would diverge from the server's.
+*
+* 6. **Writes** (ADR-0030, with {@link Options.mutate} set). A `POST` /
+*    `PATCH` / `DELETE` on a reflected write route of a type the graph
+*    declares (and {@link Options.writes} allows) is forwarded unchanged
+*    while online and unasked; offline, after a forward that rejected at the
+*    transport, or on `Prefer: respond-async`, it is decoded structurally
+*    (`FacadeWrites`), mapped to a mutation by the intent mapping (default:
+*    the graph-derived CRUD mutations, `CrudMutation`), journaled, and
+*    answered with a `202 Accepted` **write receipt**: the resource as
+*    journaled, read back through the one writer, `meta.legation.status:
+*    "pending"` and a `Location` naming the mutation status URL. Never `201`,
+*    `200` or `204`: those are the server's words for "applied". A write it
+*    cannot journal is forwarded online; offline it gets ADR-0030 §3's error
+*    documents: `400 invalid_document`, `409 type_mismatch` / `id_mismatch`
+*    or `422 unsupported_relationship` for a malformed body, and the `503`
+*    `offline` document otherwise, with `client_id_required` appended for a
+*    create without an id and `not_journalable` for a mutation the engine
+*    refuses. Attribute values are never the façade's to refuse.
+*
+* 7. **The mutation status URL** (ADR-0030 §2, with
+*    {@link Options.mutationStates} set): `GET {prefix}/_legation/mutations/{id}`
+*    beside every reflected prefix is answered from the engine's
+*    mutation-state map and never forwarded (`MutationStatus`): `200` with
+*    the mutation's phase, `404 unknown_mutation` for an id the map does not
+*    hold, `Prefer: wait=N` holding a pending answer up to
+*    {@link Options.maxWait}.
+*
+* What it never does: register a subscription because a request arrived,
+* journal a write online unless asked, or rewrite a request it forwards. A single-resource
+* request whose row the covered replica does not hold is forwarded too: the
+* 404 is the endpoint's own error class, which only the server can write.
+*
+* It lives in `@thomasfosterau/legation-jsonapi` rather than `@thomasfosterau/legation-browser` by
+* ADR-0006's rule: its dependencies are this package's (the codec, the
+* writer, route reflection) plus the standard `Request` / `Response`
+* globals, and the one browser-only reading — `navigator.onLine` — is an
+* option with a guarded default. `@thomasfosterau/legation-browser` therefore stays free of
+* effect-jsonapi; its `ServiceWorkerHost.start` hands a worker what this
+* handler needs from the host.
+*/
+var JsonApiFacade_exports = /* @__PURE__ */ __exportAll({
+	fetchHandler: () => fetchHandler,
+	offlineDocument: () => offlineDocument,
+	offlineResponse: () => offlineResponse,
+	servedAtHeader: () => servedAtHeader
+});
+/** The header a locally served response carries: the replica's CVR cookie at the time of the answer. */
+const servedAtHeader = "x-legation-served-at";
+/** The 503 error document of an uncovered request while offline (ADR-0029 §4). */
+const offlineDocument = { errors: [{
+	status: "503",
+	code: "offline",
+	title: "Service unavailable",
+	detail: "The request is not covered by a local subscription and the network is unreachable."
+}] };
+/** Every response the façade synthesises: JSON:API, never cached, marked as served locally. */
+const respondWith = (status, body, cookie, headers = {}) => new Response(JSON.stringify(body), {
+	status,
+	headers: {
+		...headers,
+		"content-type": MEDIA_TYPE,
+		"cache-control": "no-store",
+		[servedAtHeader]: cookie ?? ""
+	}
+});
+/** One error object of a façade-synthesised write error, `source.pointer` when it names one. */
+const errorObject = (refusal) => {
+	const error = {
+		status: String(refusal.status),
+		code: refusal.code,
+		title: refusal.title,
+		detail: refusal.detail
+	};
+	return refusal.pointer === void 0 ? error : {
+		...error,
+		source: { pointer: refusal.pointer }
+	};
+};
+/** The 503 `offline` document with a second error object saying why the write was not journaled. */
+const offlineWith = (reason) => ({ errors: [...offlineDocument.errors, errorObject(reason)] });
+/**
+* The offline answer to a write it could not journal (ADR-0030 §3): a
+* structural refusal is its own `400` / `409` / `422` document — the statuses
+* JSON:API prescribes for the same faults, so no divergence from the server —
+* except a create without a client id, which is the `503` `offline` document
+* with `client_id_required` appended; an engine refusal is `503` `offline`
+* with `not_journalable`; anything else the plain `503` `offline`.
+*/
+const unjournaledDocument = (failure) => Match.valueTags(failure, {
+	Refused: ({ refusal }) => refusal.status === 503 ? [503, offlineWith(refusal)] : [refusal.status, { errors: [errorObject(refusal)] }],
+	NotJournalable: ({ detail }) => [503, offlineWith({
+		status: 503,
+		code: "not_journalable",
+		title: "Not journalable",
+		detail
+	})],
+	Unmapped: () => [503, offlineDocument]
+});
+/** The 503 response of an uncovered request while offline, marked with the cookie when known. */
+const offlineResponse = (cookie) => respondWith(503, offlineDocument, cookie);
+const routeOf = (type, template, single) => {
+	const segments = segmentsOf(template);
+	const prefix = segments.slice(0, segments.length - (single ? 2 : 1));
+	return {
+		type,
+		segments,
+		prefix: Arr.isReadonlyArrayEmpty(prefix) ? "" : `/${prefix.join("/")}`
+	};
+};
+/** The read routes of the api whose type the graph declares: a `list` and a `getOne` per such resource. */
+const routesOf = (api, nodes) => {
+	return [...reflectResources(api).values()].flatMap((resource) => {
+		if (!nodes.nodes.has(resource.type)) return [];
+		const list = resource.list === void 0 ? [] : [routeOf(resource.type, resource.list.path, false)];
+		const one = resource.getOne === void 0 ? [] : [routeOf(resource.type, resource.getOne.path, true)];
+		return list.concat(one);
+	});
+};
+const writeMethods = {
+	create: "POST",
+	update: "PATCH",
+	delete: "DELETE"
+};
+/** The write routes of the api whose type the graph declares and `writes` allows. */
+const writeRoutesOf = (api, nodes, writes) => Arr.flatMap([...reflectResources(api).values()], (resource) => {
+	const node = nodes.nodes.get(resource.type);
+	if (node === void 0) return [];
+	return Arr.filterMap([
+		"create",
+		"update",
+		"delete"
+	], (operation) => {
+		const endpoint = resource[operation];
+		const method = writeMethods[operation];
+		const allowed = writes === void 0 || (writes[resource.type] ?? []).includes(operation);
+		return endpoint === void 0 || endpoint.method.toUpperCase() !== method || !allowed ? Result.failVoid : Result.succeed({
+			...routeOf(resource.type, endpoint.path, operation !== "create"),
+			operation,
+			node,
+			method
+		});
+	});
+});
+const matchesTemplate = (route, segments) => route.segments.length === segments.length && route.segments.every((template, index) => isParam(template) ? true : template === segments[index]);
+const baseOf = (baseUrl) => {
+	if (baseUrl === "" || baseUrl.startsWith("/")) return { path: baseUrl.replace(/\/+$/, "") };
+	const url = new URL(baseUrl);
+	return {
+		origin: url.origin,
+		path: url.pathname.replace(/\/+$/, "")
+	};
+};
+/**
+* The request path relative to the base, or `undefined` when it lies
+* elsewhere. A trailing slash is left to the server: the route templates
+* carry none, and whether `/products/` is `/products` is its ruling.
+*/
+const pathUnder = (base, url) => {
+	if (base.origin !== void 0 && url.origin !== base.origin) return void 0;
+	if (!url.pathname.startsWith(base.path) || url.pathname.endsWith("/")) return void 0;
+	const rest = url.pathname.slice(base.path.length);
+	return rest.startsWith("/") ? rest : void 0;
+};
+/** Whether an `Accept` header names the JSON:API media type (parameters aside). */
+const acceptsJsonApi = (header) => header !== null && header.split(",").some((part) => (part.trim().split(";")[0] ?? "").trim().toLowerCase() === MEDIA_TYPE);
+/**
+* Whether a `Content-Type` is the JSON:API media type without the atomic
+* extension: an `ext` parameter naming atomic marks the operations endpoint,
+* never a façade write (ADR-0030 §5).
+*/
+const sendsJsonApi = (header) => {
+	if (header === null) return false;
+	const [type = "", ...parameters] = header.split(";");
+	if (type.trim().toLowerCase() !== MEDIA_TYPE) return false;
+	return !parameters.some((parameter) => {
+		const [name = "", value = ""] = parameter.split("=");
+		return name.trim().toLowerCase() === "ext" && value.toLowerCase().includes("atomic");
+	});
+};
+const navigatorOnline = () => {
+	return globalThis.navigator?.onLine !== false;
+};
+const forward = { _tag: "Forward" };
+const respond = (response) => ({
+	_tag: "Respond",
+	response
+});
+/**
+* A grammar rejection as the server would rule on it. An `include` the
+* graph does not declare is the server's call (ADR-0029 §1), and so is a
+* path the graph cannot place (no parameter, no decoding issue: the URL
+* names something the graph does not); anything else is the codec's 400,
+* which the server returns identically.
+*/
+const queryFailure = (error, cookie) => error.parameter === "include" || error.parameter === void 0 && !Schema.isSchemaError(error.cause) ? forward : respond(respondWith(400, queryErrorDocument(error), cookie));
+/**
+* Build the façade over an api and a replica. Route reflection and the
+* writer's declaration checks run here, so a declaration the graph cannot
+* serve is a definition-time defect, never a response.
+*/
+const fetchHandler = (options) => {
+	const { nodes, view, coverageOf } = options;
+	const routes = routesOf(options.api, nodes);
+	const mutate = options.mutate;
+	const writeRoutes = mutate === void 0 ? [] : writeRoutesOf(options.api, nodes, options.writes);
+	const intentOf = options.intentOf ?? graphIntentOf(nodes);
+	const base = baseOf(options.baseUrl ?? "");
+	const online = options.online ?? navigatorOnline;
+	/** The cookie at the time of an answer; read only when a response is synthesised. */
+	const cookie = options.cookie === void 0 ? Effect.succeed(void 0) : Effect.catch(options.cookie, () => Effect.succeed(void 0));
+	const writers = /* @__PURE__ */ new Map();
+	/** The writer for a link prefix: one per prefix, built when a route first needs it. */
+	const writerFor = (prefix) => {
+		const existing = writers.get(prefix);
+		if (existing !== void 0) return existing;
+		const made = make$1({
+			nodes,
+			prefix,
+			...options.resources === void 0 ? {} : { resources: options.resources }
+		});
+		writers.set(prefix, made);
+		return made;
+	};
+	routes.forEach((route) => {
+		writerFor(options.prefix ?? route.prefix);
+	});
+	const candidateOf = (request) => {
+		if (request.method !== "GET" || !acceptsJsonApi(request.headers.get("accept"))) return;
+		const url = new URL(request.url);
+		const path = pathUnder(base, url);
+		if (path === void 0) return void 0;
+		const segments = segmentsOf(path);
+		const route = routes.find((candidate) => matchesTemplate(candidate, segments));
+		return route === void 0 ? void 0 : {
+			route,
+			url
+		};
+	};
+	/** Rules 1 to 4 for every read the request needs, judged over the request's root rows: covered by the ledger, or not the façade's to answer. */
+	const covered = (reads, snapshot) => Effect.forEach(reads, (read) => coverageOf(read, { snapshot })).pipe(Effect.map((verdicts) => verdicts.every((verdict) => verdict._tag === "Covered")));
+	/** The replica with the request's root window answered from `rows`: the rows coverage judged, not a second read. */
+	const pinned = (base, root, rows) => ({
+		query: (subset) => Subset.hash(subset) === Subset.hash(root) ? Effect.succeed(rows) : base.query(subset),
+		observe: base.observe
+	});
+	/** A rejection as an outcome, with the cookie read for the response it may carry. */
+	const rejected = (error) => Effect.flatMap(cookie, (served) => Effect.fail(queryFailure(error, served)));
+	const answer = ({ route, url }) => Effect.gen(function* () {
+		const docs = writers.get(options.prefix ?? route.prefix);
+		if (docs === void 0) return yield* Effect.fail(forward);
+		const parsed = yield* parseRead(nodes, url).pipe(Effect.catch(rejected));
+		const needed = yield* docs.toCover(parsed.read).pipe(Effect.mapError(() => forward));
+		const root = yield* Query$1.tryPlan(nodes, parsed.read).pipe(Effect.mapError(() => forward));
+		const rows = yield* view.query(root.root).pipe(Effect.orElseSucceed(() => void 0));
+		if (rows === void 0 || !(yield* covered(needed, {
+			subset: root.root,
+			rows
+		}))) {
+			if (online()) return yield* Effect.fail(forward);
+			return yield* Effect.flatMap(cookie, (served) => Effect.fail(respond(offlineResponse(served))));
+		}
+		const replica = pinned(view, root.root, rows);
+		const document = yield* (parsed.id === void 0 ? docs.collection(replica, parsed) : docs.data(replica, parsed)).pipe(Effect.catch(rejected));
+		if (parsed.id !== void 0 && document.data === null) return yield* Effect.fail(forward);
+		return respondWith(200, document, yield* cookie);
+	});
+	const readHandle = (request) => {
+		const candidate = candidateOf(request);
+		if (candidate === void 0) return Effect.succeed(void 0);
+		return answer(candidate).pipe(Effect.catchTags({
+			Forward: () => Effect.succeed(void 0),
+			Respond: (outcome) => Effect.succeed(outcome.response)
+		}));
+	};
+	const writeCandidateOf = (request) => {
+		const method = request.method.toUpperCase();
+		if (!acceptsJsonApi(request.headers.get("accept"))) return void 0;
+		if (method !== "DELETE" && !sendsJsonApi(request.headers.get("content-type"))) return;
+		const path = pathUnder(base, new URL(request.url));
+		if (path === void 0) return void 0;
+		const segments = segmentsOf(path);
+		const route = writeRoutes.find((candidate) => candidate.method === method && matchesTemplate(candidate, segments));
+		if (route === void 0) return void 0;
+		return {
+			route,
+			target: route.operation === "create" ? {
+				operation: "create",
+				type: route.type
+			} : {
+				operation: route.operation,
+				type: route.type,
+				id: decodeURIComponent(segments.at(-1) ?? "")
+			}
+		};
+	};
+	/** The mutation status URL of a journaled mutation: beside the api it belongs to (ADR-0030 §2). */
+	const statusUrl = (route, mutationId) => `${base.origin ?? ""}${base.path}${route.prefix}/_legation/mutations/${mutationId}`;
+	/**
+	* The receipt's `data`: the resource read back through the one writer
+	* after journaling (ADR-0030 §1), or — when the replica does not hold the
+	* row (a patch of a row it never pulled) — the request's own members.
+	*/
+	const receiptData = ({ route }, write) => {
+		const prefix = options.prefix ?? route.prefix;
+		const docs = writerFor(prefix);
+		const sent = {
+			type: write.type,
+			id: write.id,
+			attributes: write.attributes ?? {}
+		};
+		return docs.fromUrl(view, `${prefix}/${write.type}/${encodeURIComponent(write.id)}`).pipe(Effect.map((document) => "data" in document && document.data !== null && !Array.isArray(document.data) ? document.data : sent), Effect.orElseSucceed(() => sent));
+	};
+	/**
+	* Journal a write and answer its `202` receipt, or fail with `undefined`
+	* when it cannot be journaled (the caller forwards it online, or answers
+	* offline). The body is read from a clone.
+	*/
+	const journal = (request, candidate, preferences) => Effect.gen(function* () {
+		const body = Effect.tryPromise(() => request.clone().text());
+		const write = yield* decodeWrite(candidate.route.node, candidate.target, body).pipe(Effect.mapError((refusal) => ({
+			_tag: "Refused",
+			refusal
+		})));
+		const intent = intentOf(write);
+		if (intent === void 0 || mutate === void 0) return yield* Effect.fail({ _tag: "Unmapped" });
+		const handle = yield* mutate(intent.mutator, intent.args).pipe(Effect.mapError((error) => P.isTagged(error, "MutatorError") ? {
+			_tag: "NotJournalable",
+			detail: error.message
+		} : { _tag: "Unmapped" }));
+		const location = statusUrl(candidate.route, handle.mutationId);
+		const meta = { legation: {
+			status: "pending",
+			mutationId: handle.mutationId,
+			mutation: location
+		} };
+		const document = write.operation === "delete" ? { meta } : {
+			data: yield* receiptData(candidate, write),
+			meta
+		};
+		const headers = preferences.respondAsync ? {
+			location,
+			"preference-applied": "respond-async"
+		} : { location };
+		return respondWith(202, document, yield* cookie, headers);
+	});
+	const offlineNow = Effect.map(cookie, offlineResponse);
+	/** The offline answer to a write it could not journal: ADR-0030 §3's error documents. */
+	const unjournaled = (failure) => Effect.map(cookie, (served) => {
+		const [status, document] = unjournaledDocument(failure);
+		return respondWith(status, document, served);
+	});
+	/** ADR-0030 §3's decision table for a write candidate, offline meaning `navigator.onLine` false. */
+	const writeHandle = (request, candidate) => {
+		const preferences = preferencesOf(request.headers);
+		const reachable = online();
+		if (preferences.strict) return reachable ? Effect.succeed(void 0) : offlineNow;
+		if (reachable && !preferences.respondAsync) return Effect.succeed(void 0);
+		return journal(request, candidate, preferences).pipe(Effect.catch((failure) => reachable ? Effect.succeed(void 0) : unjournaled(failure)));
+	};
+	const mutationStates = options.mutationStates;
+	const maxWait = Duration.fromInputUnsafe(options.maxWait ?? "30 seconds");
+	/** Every prefix the api's reflected routes sit under: the status route sits beside each. */
+	const prefixes = Arr.dedupe(Arr.map([...routes, ...writeRoutes], (route) => route.prefix));
+	/** A status request: the route prefix it names and the id segment, or `undefined`. */
+	const statusCandidateOf = (request) => {
+		if (mutationStates === void 0 || request.method !== "GET") return void 0;
+		if (!acceptsJsonApi(request.headers.get("accept"))) return void 0;
+		const path = pathUnder(base, new URL(request.url));
+		if (path === void 0) return void 0;
+		const segments = segmentsOf(path);
+		const [id = "", mutations = "", legation = ""] = segments.toReversed();
+		if (legation !== "_legation" || mutations !== "mutations") return void 0;
+		const prefix = segments.slice(0, -3);
+		const joined = Arr.isReadonlyArrayEmpty(prefix) ? "" : `/${prefix.join("/")}`;
+		return prefixes.includes(joined) ? {
+			prefix: joined,
+			id: decodeURIComponent(id)
+		} : void 0;
+	};
+	const statusHandle = (request, states, candidate) => Effect.gen(function* () {
+		const links = `${base.origin ?? ""}${base.path}${candidate.prefix}`;
+		const mutationId = parseId(candidate.id);
+		if (Option.isNone(mutationId)) return respondWith(404, unknownDocument(candidate.id), yield* cookie);
+		const now = yield* current(states, mutationId.value);
+		const asked = preferencesOf(request.headers).wait;
+		const wait = asked === void 0 || Option.isNone(now) || now.value.phase !== "pending" ? void 0 : Duration.min(Duration.seconds(asked), maxWait);
+		const state = wait === void 0 ? now : yield* settled(states, mutationId.value, wait);
+		const served = yield* cookie;
+		if (Option.isNone(state)) return respondWith(404, unknownDocument(candidate.id), served);
+		const document$1 = document(nodes, links, state.value);
+		return wait === void 0 ? respondWith(200, document$1, served) : respondWith(200, document$1, served, { "preference-applied": `wait=${Math.floor(Duration.toSeconds(wait))}` });
+	});
+	const handle = (request) => {
+		const status = statusCandidateOf(request);
+		if (status !== void 0 && mutationStates !== void 0) return statusHandle(request, mutationStates, status);
+		const write = writeCandidateOf(request);
+		return write === void 0 ? readHandle(request) : writeHandle(request, write);
+	};
+	const offline = (request) => {
+		const write = writeCandidateOf(request);
+		if (write === void 0) return offlineNow;
+		const preferences = preferencesOf(request.headers);
+		if (preferences.strict) return offlineNow;
+		return journal(request, write, preferences).pipe(Effect.catch(unjournaled));
+	};
+	const forwarded = (request, response) => options.pull !== void 0 && response.status >= 200 && response.status < 300 && writeCandidateOf(request) !== void 0 ? Effect.ignore(options.pull) : Effect.void;
+	return {
+		matches: (request) => candidateOf(request) !== void 0 || writeCandidateOf(request) !== void 0 || statusCandidateOf(request) !== void 0,
+		handle,
+		offline,
+		forwarded
+	};
+};
+// src/JsonApiSync.ts
+/**
+* JsonApiSync
+*
+* The happy path: hand it an app's JSON:API `HttpApi` and get a fully wired,
+* offline-capable sync engine. It reflects the api into resources
+* (Convention.ts), derives collections + CRUD mutators (Derive.ts), and
+* composes the JsonApiBackend with an in-process sync room and the client
+* engine — so the app's existing REST API gains optimistic writes, a durable
+* journal, rebase, and live queries with no extra server to deploy
+* (client-direct deployment; "realtime" is periodic pull).
+*
+* The same JsonApiBackend satisfies the BYO `Backend` contract, so a later
+* server-side deployment for CVR fan-out reuses it unchanged.
+*
+* When the api advertises the JSON:API Atomic Operations extension (an
+* endpoint taking an `atomic:operations` document), pushes go to it as one
+* all-or-nothing request per batch; otherwise each mutation is replayed as
+* its own request (`JsonApiSyncOptions.atomic`).
+*/
+var JsonApiSync_exports = /* @__PURE__ */ __exportAll({
+	inspect: () => inspect,
+	layer: () => layer,
+	start: () => start
+});
+/**
+* Reflect + derive an api's resources, collections, mutators, operations —
+* and its atomic operations endpoint, when it declares one.
+*/
+const inspect = (api) => {
+	const resources = reflectResources(api);
+	const atomic = reflectAtomic(api);
+	return {
+		resources,
+		...atomic !== void 0 ? { atomic } : {},
+		...derive(resources)
+	};
+};
+/** Every resource collection is readable; the REST API enforces real auth. */
+const authPolicy = (resources) => Authorization.policy(Object.fromEntries([...resources.keys()].map((type) => [type, Authorization.allowAll])));
+/**
+* The full client-direct stack as a layer: provide an `HttpClient`, get a
+* ready `ClientEngine`. CVR store and invalidation bus are in-process; the
+* client store defaults to in-memory, or to the durable store over
+* `keyValueStore` (pass it for offline persistence and a durable ledger across
+* reloads, or pass `store` and `ledger` for another durable store).
+*/
+const layer = (api, options) => {
+	const { resources, registry, operations, atomic } = inspect(api);
+	const atomicPath = options.atomic === false ? void 0 : options.atomic?.path ?? atomic?.path;
+	const ledger = options.ledger ?? (options.keyValueStore !== void 0 ? keyValue(options.keyValueStore) : void 0);
+	const clientStore = options.store ?? (options.keyValueStore !== void 0 ? ClientStore.layerKeyValue().pipe(Layer.provide(Layer.succeed(KeyValueStore.KeyValueStore)(options.keyValueStore))) : ClientStore.layerMemory);
+	const backendLayer = Layer.effect(Backend.Backend)(make$2({
+		baseUrl: options.baseUrl,
+		resources,
+		mutators: registry.mutators,
+		operations,
+		...atomicPath !== void 0 ? { atomic: { path: atomicPath } } : {},
+		...options.queryEncoder !== void 0 ? { query: options.queryEncoder } : {},
+		...options.includes !== void 0 ? { includes: options.includes } : {},
+		...ledger !== void 0 ? { ledger } : {}
+	}));
+	const authLayer = Layer.succeed(Authorization.AuthPolicy)(authPolicy(resources));
+	const serverLayer = SyncRoom.layer.pipe(Layer.provide(backendLayer), Layer.provide(authLayer));
+	const transportLayer = Transport.layerInMemory(options.clientGroupId).pipe(Layer.provide(serverLayer));
+	const pullInterval = options.pullInterval === null ? void 0 : options.pullInterval ?? Duration.seconds(5);
+	const syncLoop = {
+		...pullInterval !== void 0 ? { pullInterval } : {},
+		...options.pushDebounce !== void 0 ? { pushDebounce: options.pushDebounce } : {}
+	};
+	return ClientEngine.layer({
+		clientId: options.clientId,
+		clientGroupId: options.clientGroupId,
+		mutators: registry,
+		syncLoop
+	}).pipe(Layer.provide(transportLayer), Layer.provide(clientStore));
+};
+/**
+* Start syncing: run the engine's sync loop. Interval pull, push-on-mutate,
+* pull-on-poke and push+pull-on-reconnect are all scheduled by the core loop
+* (configure the interval/debounce on `layer`'s options). Requires a `Scope` —
+* fork it into the app's runtime and the fibers live until the scope closes.
+*/
+const start = Effect.gen(function* () {
+	yield* (yield* ClientEngine.ClientEngine).runSync.pipe(Effect.orDie);
+});
+// src/NodeBridge.ts
+/**
+* NodeBridge
+*
+* The first-class integration ADR-0022 promised: a JSON:API resource
+* definition (`Resource.make` from `@thomasfosterau/effect-jsonapi`) **is**
+* a node definition — same type name, same attributes, and relationships
+* that map one-for-one onto edges. This module derives {@link Node} graphs
+* from resource definitions so an app declares its resources once and gets
+* the sync engine's replica, queries, joins, and fan-out topics from the
+* same source of truth as its HTTP API.
+*
+* The mapping:
+*
+* - `Relationship.one` / `Relationship.optional` → `Edge.one`, stored in
+*   the foreign-key field `` `${name}Id` `` (override per relationship with
+*   `via`). JSON:API keeps relationship linkage out of `attributes`, so the
+*   engine-side row gains the key field the edge declares.
+* - `Relationship.many` / `Relationship.paginated` → `Edge.many` /
+*   `Edge.paginated`. The **inverse** — the one-edge on the target holding
+*   the key — is discovered when it is unambiguous, and named explicitly
+*   when it is not: on the resource, with the `@legation/inverses`
+*   annotation ({@link syncAnnotations}), or in the `inverses` option.
+* - `paginated` edges need an `order` (cursor pagination requires a stable
+*   order, and it is part of the edge's identity — ADR-0022). It is read off
+*   the relationship's own declaration, `Relationship.paginated(ref, { order })`
+*   (#220), or given in the `order` option.
+*
+* **Sync metadata on the resource (#220).** What only the sync engine needs —
+* an inverse name, the literal kind of a field no schema can tell (an
+* `instant` stored as text) — is declared on the resource as
+* `@legation/`-namespaced annotations: `Resource.make(…, { annotations:
+* syncAnnotations({ inverses, kinds }) })`, or `Resource.annotate`, which
+* `Resource.extend` keeps. The {@link FromResourceOptions} remain, as
+* explicit overrides: an option entry wins over the resource's annotation or
+* declaration for the same relationship or field. A to-one relationship's
+* key field is still `` `${name}Id` `` or the `via` option until
+* effect-jsonapi's storage-key slot (effect-jsonapi#509) reaches this
+* package.
+*
+* **Acyclic resource graphs.** The library's resource types expand eagerly,
+* so mutually-referencing definitions (`Product ⇄ Review`) cannot be
+* authored; the idiomatic JSON:API graph points parent → child and the
+* child carries its foreign key as a plain attribute (`productId`). The
+* `edges` option closes that gap: it promotes such an attribute to a
+* declared one-edge on the bridged node, and {@link registry} discovers
+* collection-valued inverses across **bridged** one-edges — declared and
+* relationship-derived alike — so the acyclic graph bridges without ever
+* naming an inverse by hand.
+*
+* **The filterable set** (ADR-0028 rule d, #154) is read off the resource's
+* own declaration (effect-jsonapi, since 0.13: `Filter.able` / `Sort.able` piped
+* onto an attribute schema, `Resource.attribute(schema, { filter, sort })`,
+* `Relationship.one(ref, { filter })`) through `Resource.filterable` /
+* `Resource.sortable`. An attribute keeps its name and derives its literal
+* kind from its schema exactly as `Node.make` does; a to-one relationship's
+* declaration lands on the edge's **key field** (`author` → `authorId`,
+* kind `text`), which is the field the engine filters by. The
+* `filterable` / `sortable` options remain as overrides: an option entry
+* replaces the resource's declaration for that field (the way to give an
+* `instant` its kind, which no schema can tell), and adds fields the
+* resource does not declare.
+*
+* All mismatches are definition-time defects (a thrown
+* {@link ResourceBridgeError}), never runtime failures: a resource graph
+* either bridges completely or not at all.
+*
+* **Identity** is always `id` here: a JSON:API resource is identified by the
+* spec's `id` member, so a bridged node declares no identity attribute of its
+* own (`Node.make`'s `id` option, #144). The JSON:API surface — `/{type}/{id}`
+* widening to `filter[id]`, linkage and `included` reading `id` off a row
+* value — assumes that, so a hand-built node naming a natural key is not yet
+* servable through these handlers.
+*/
+var NodeBridge_exports = /* @__PURE__ */ __exportAll({
+	InversesAnnotation: () => InversesAnnotation,
+	KindsAnnotation: () => KindsAnnotation,
+	ResourceBridgeError: () => ResourceBridgeError,
+	fromResource: () => fromResource,
+	registry: () => registry,
+	syncAnnotations: () => syncAnnotations
+});
+/** A definition-time mismatch between a resource graph and the node model. */
+var ResourceBridgeError = class extends Schema.TaggedError()("ResourceBridgeError", {
+	resource: Schema.String,
+	relationship: Schema.String,
+	message: Schema.String
+}) {};
+/** The annotation key naming the inverse edge of collection relationships, by relationship name. */
+const InversesAnnotation = "@legation/inverses";
+/** The annotation key naming the literal kind of filterable fields, by row field. */
+const KindsAnnotation = "@legation/kinds";
+/**
+* The resource annotations that declare `sync`, to pass as (or merge into)
+* `Resource.make`'s `annotations` or `Resource.annotate`'s.
+*/
+const syncAnnotations = (sync) => {
+	let record = {};
+	if (sync.inverses !== void 0) record = {
+		...record,
+		[InversesAnnotation]: sync.inverses
+	};
+	if (sync.kinds !== void 0) record = {
+		...record,
+		[KindsAnnotation]: sync.kinds
+	};
+	return record;
+};
+const Inverses = Schema.Record(Schema.String, Schema.String);
+const Kinds = Schema.Record(Schema.String, Schema.Literals([
+	"text",
+	"integer",
+	"double",
+	"boolean",
+	"instant"
+]));
+/**
+* Read one of the bridge's annotations off a resource: absent reads as empty,
+* and a value of the wrong shape is a definition-time defect.
+*/
+const annotationOf = (resource, key, schema) => Option.map(Option.fromUndefinedOr(Resource.annotations(resource)[key]), (value) => Option.getOrElse(Schema.decodeUnknownOption(schema)(value), () => fail(resource.type, key, `the "${key}" annotation does not have the shape the bridge reads`)));
+const fail = (resource, relationship, message) => {
+	throw new ResourceBridgeError({
+		resource,
+		relationship,
+		message
+	});
+};
+/**
+* The one-edges a resource bridges to: its `one`/`optional` relationships
+* plus the option-declared extras. This is the map inverse discovery
+* scans, so declared and relationship-derived edges resolve identically.
+*/
+const oneEdgesOf = (resource, options) => {
+	const related = R.filterMap(resource.relationships, (descriptor, name) => descriptor.kind === "one" || descriptor.kind === "optional" ? Result.succeed(Edge.one(descriptor.ref().type, { via: options.via?.[name] ?? `${name}Id` })) : Result.failVoid);
+	const declared = R.map(options.edges ?? {}, (edge) => Edge.one(edge.target, { via: edge.via }));
+	return {
+		...related,
+		...declared
+	};
+};
+/**
+* Discover the inverse of a collection-valued relationship: the unique
+* one-edge on the (bridged) target that points back at `source`.
+*/
+const discoverInverse = (source, name, target, targetOneEdges) => {
+	const candidates = Object.entries(targetOneEdges).filter(([, edge]) => edge.target === source);
+	const only = candidates[0];
+	if (candidates.length === 1 && only !== void 0) return only[0];
+	return fail(source, name, Arr.isReadonlyArrayEmpty(candidates) ? `no inverse found: "${target}" bridges no one-edge back to "${source}" — declare one (a relationship, or options.edges over its key attribute), or name it in options.inverses` : `ambiguous inverse: "${target}" bridges ${candidates.length} one-edges back to "${source}" (${candidates.map(([candidate]) => `"${candidate}"`).join(", ")}) — name the right one in options.inverses`);
+};
+/**
+* A paginated relationship's own canonical order (effect-jsonapi's
+* `Relationship.paginated(ref, { order })`), as the engine spells an order:
+* field names, `-` prefixed for descending.
+*/
+const declaredOrder = (descriptor) => descriptor.kind === "paginated" ? Option.map(Option.fromUndefinedOr(descriptor.order), (order) => order.map((term) => term.direction === "desc" ? `-${term.field}` : term.field)) : Option.none();
+/**
+* Bridge one collection-valued relationship to its edge: the inverse is
+* named in the options or discovered on the target; a paginated one also
+* needs its declared order.
+*/
+const collectionEdge = (resource, name, descriptor, options, oneEdgesOfTarget) => {
+	const target = descriptor.ref();
+	const inverse = options.inverses?.[name] ?? Option.getOrUndefined(Option.flatMapNullishOr(annotationOf(resource, "@legation/inverses", Inverses), (inverses) => inverses[name])) ?? discoverInverse(resource.type, name, target.type, oneEdgesOfTarget(target));
+	if (descriptor.kind === "many") return Edge.many(target.type, { inverse });
+	const order = options.order?.[name] ?? Option.getOrUndefined(declaredOrder(descriptor));
+	if (order === void 0) return fail(resource.type, name, `a paginated relationship needs an edge order (cursor pagination requires a stable order) — declare it on the relationship, Relationship.paginated(ref, { order }), or in options.order`);
+	return Edge.paginated(target.type, {
+		inverse,
+		order
+	});
+};
+/** The resource's edges: its one-edges plus every collection-valued relationship's. */
+const edgesOf = (resource, options, oneEdgesOfTarget) => {
+	const collections = R.filterMap(resource.relationships, (descriptor, name) => descriptor.kind === "many" || descriptor.kind === "paginated" ? Result.succeed(collectionEdge(resource, name, descriptor, options, oneEdgesOfTarget)) : Result.failVoid);
+	return {
+		...oneEdgesOf(resource, options),
+		...collections
+	};
+};
+/**
+* The resource's attributes minus every one-edge's key field: a one-edge's
+* key replaces any attribute of the same name (the promoted-attribute
+* case); the edge's branded id carries the field.
+*/
+const attributesOf = (resource, edges) => {
+	const keys = new Set(Object.values(edges).flatMap((edge) => edge.kind === "one" ? [edge.via] : []));
+	return R.filter(resource.fields.attributes.fields, (_, field) => !keys.has(field));
+};
+/**
+* The filterable set the resource declares, keyed by **row field**: an
+* attribute under its own name, with the kind left to `Node.make` to derive
+* from its schema; a to-one relationship under its edge's key field, kind
+* `text` (an id). A key field declared twice — the relationship and the
+* attribute it is stored in both filterable — is a definition-time defect:
+* neither declaration may silently win.
+*/
+const declaredFilterable = (resource, edges) => {
+	const declared = {};
+	const attributes = resource.fields.attributes.fields;
+	Object.entries(Resource.filterable(resource)).forEach(([key, entry]) => {
+		const edge = edges[key];
+		const viaRelationship = attributes[key] === void 0 && edge?.kind === "one";
+		const field = viaRelationship ? edge.via : key;
+		if (declared[field] !== void 0) fail(resource.type, key, `key field "${field}" is declared filterable twice (by relationship "${key}" and by the attribute it is stored in) — declare it once`);
+		declared[field] = viaRelationship ? {
+			operators: entry.operators,
+			kind: "text"
+		} : entry.operators;
+	});
+	return declared;
+};
+/**
+* The declared filterable set with the resource's `@legation/kinds`
+* annotation applied: each named field keeps its operators and takes the
+* annotated kind. Naming a field the resource does not declare filterable is a
+* definition-time defect.
+*/
+const withKinds = (resource, declared) => R.reduce(Option.getOrElse(annotationOf(resource, KindsAnnotation, Kinds), () => ({})), declared, (current, kind, field) => {
+	const entry = current[field];
+	if (entry === void 0) return fail(resource.type, KindsAnnotation, `"${field}" has a kind in "${KindsAnnotation}" but is not declared filterable on the resource`);
+	const operators = "operators" in entry ? entry.operators : entry;
+	return {
+		...current,
+		[field]: {
+			operators,
+			kind
+		}
+	};
+});
+/**
+* The per-node options: hint keys from the bridge options; the filterable
+* set and sortable fields from the resource's declaration, each option
+* entry replacing the resource's for its field.
+*/
+const nodeOptionsOf = (resource, edges, options) => ({
+	...options.hintKeys === void 0 ? {} : { hintKeys: options.hintKeys },
+	filterable: {
+		...withKinds(resource, declaredFilterable(resource, edges)),
+		...options.filterable
+	},
+	sortable: [...Resource.sortable(resource), ...options.sortable ?? []]
+});
+/** Bridge one resource, resolving inverses through `oneEdgesOfTarget`. */
+const bridge = (resource, options, oneEdgesOfTarget) => {
+	const edges = edgesOf(resource, options, oneEdgesOfTarget);
+	return Node.make(resource.type, {
+		attributes: attributesOf(resource, edges),
+		edges,
+		...nodeOptionsOf(resource, edges, options)
+	});
+};
+/**
+* Derive a {@link Node} definition from a single JSON:API resource
+* definition. Inverse discovery here sees only the target resource's own
+* relationships — bridge a whole graph with {@link registry} to discover
+* across option-declared edges too.
+*/
+const fromResource = (resource, options = {}) => bridge(resource, options, (target) => oneEdgesOf(target, {}));
+/**
+* Bridge a whole resource graph and close it as a validated
+* {@link Node.NodeRegistry} — nodes plus the derived engine
+* `CollectionRegistry`, ready for `Client.make` / `Server.make`.
+* Options are keyed by resource type.
+*/
+const registry = (resources, options = {}) => Node.registry(resources.map((resource) => bridge(resource, options[resource.type] ?? {}, (target) => oneEdgesOf(target, options[target.type] ?? {}))));
+// src/Relationships.ts
+var Relationships_exports = /* @__PURE__ */ __exportAll({
+	hydrate: () => hydrate,
+	observe: () => observe,
+	query: () => query,
+	related: () => related,
+	resolve: () => resolve
+});
+const refOf = (value, name) => value.relationships?.[name] ?? null;
+const isLink = (value) => P.isObjectOrArray(value) && "type" in value && "id" in value;
+/** The `{ type, id }` links a row's named relationship points at. */
+const linksOf = (value, name) => {
+	const ref = refOf(value, name);
+	if (ref === null || ref === void 0) return [];
+	return (Array.isArray(ref) ? ref : [ref]).filter(isLink);
+};
+/** Resolve one relationship of a row against a lookup (linkage → value[s]). */
+const resolve = (lookup, value, name) => {
+	const ref = refOf(value, name);
+	if (ref === null || ref === void 0) return ref;
+	if (Array.isArray(ref)) return ref.flatMap((link) => {
+		const row = lookup(link.type, link.id);
+		return row === void 0 ? [] : [row];
+	});
+	return isLink(ref) ? lookup(ref.type, ref.id) : void 0;
+};
+/** Resolve several named relationships of a row. */
+const hydrate = (lookup, value, names) => {
+	return R.fromIterableWith(names, (name) => [name, resolve(lookup, value, name)]);
+};
+/**
+* The linkage strategy: `targets` pins each referenced collection by `id` and
+* the linked ids; `resolveRow` reads the referenced rows out of the index by id
+* and hydrates via {@link hydrate}, so resolution is byte-for-byte the previous
+* behaviour.
+*/
+const linkageStrategy = (names) => ({
+	targets: (baseRows) => {
+		const map = /* @__PURE__ */ new Map();
+		baseRows.flatMap((row) => names.flatMap((name) => linksOf(row.value, name))).forEach((link) => {
+			const entry = map.get(link.type) ?? {
+				field: "id",
+				ids: /* @__PURE__ */ new Set()
+			};
+			entry.ids.add(link.id);
+			map.set(link.type, entry);
+		});
+		return map;
+	},
+	resolveRow: (index, baseRow) => {
+		const lookup = (collection, id) => index.get(collection)?.get(id)?.[0]?.value;
+		return hydrate(lookup, baseRow.value, names);
+	}
+});
+/**
+* Resolve a subset's rows together with their named relationships, reading the
+* referenced collections from the engine's local view. Delegates to
+* {@link Related.queryWith} with the linkage strategy.
+*/
+const query = (engine, subset, names) => Related.queryWith(engine, linkageStrategy(names), subset);
+/**
+* Live version of {@link query} as an incrementally-maintained join. Delegates
+* to {@link Related.observeWith}: a write to a referenced row re-hydrates the
+* join without re-querying the base; a base change that shifts referenced
+* collections re-establishes the observers.
+*/
+const observe = (engine, subset, names) => Related.observeWith(engine, linkageStrategy(names), subset);
+/**
+* Auto-subscribing relational read: subscribes the base subset and the narrowed
+* `id IN (...)` subsets of each referenced collection, tracks the live linkage,
+* and tears the subscriptions down when the scope closes. Delegates to
+* {@link Related.relatedWith}. Pair with the backend's `includes` config to
+* deliver the related rows in the parent's response (no extra round trip).
+*/
+const related = (engine, subset, names) => Related.relatedWith(engine, linkageStrategy(names), subset);
+export { ApiError, CollectionLoader_exports as CollectionLoader, ConflictError, Convention_exports as Convention, Derive_exports as Derive, DocumentWriter_exports as DocumentWriter, FacadeWrites_exports as FacadeWrites, JsonApiBackend_exports as JsonApiBackend, JsonApiFacade_exports as JsonApiFacade, JsonApiQuery_exports as JsonApiQuery, schema_exports as JsonApiSchema, JsonApiSync_exports as JsonApiSync, Ledger_exports as Ledger, MutationStatus_exports as MutationStatus, NetworkError, NodeBridge_exports as NodeBridge, ParseError, Relationships_exports as Relationships, ReplicaDocuments_exports as ReplicaDocuments, RestHandlers_exports as RestHandlers, SyncError };
+
+//# sourceMappingURL=index.js.map