@jarenjs/linq 0.73.0 → 0.75.0

package/ARCHITECTURE.md

@@ -202,16 +202,14 @@ residual runs locally, and `explain()` reports the split.
   (`JL0005`) rather than silently materialised — except two providers
   sharing a `scope` (one store's entity sets), whose roots are two
   bindings of one multi-entity input.
-- **Federation is a door, not a default.** `federate({ sources,
-  maxRows, maxBytes })` (`src/federate.js`, QUERY-PEN §12.1) hands back
-  one provider source per name, sharing one scope, so the ordinary join
-  is admitted and the federation executes it: each side's own packed
-  document at its own source, the smaller side into a bounded hash
-  table, the other probed against it, and the caller's document decided
-  in the engine over the two reduced sets. It spells no join semantics
-  of its own — the reduction bounds the FETCH, and a value it cannot
-  key is kept rather than guessed at — and a budget is a refusal
-  (`JL2008`), never a spill.
+- **Federation is explicit.** `federate()` (QUERY-PEN §12.1) accepts a
+  connected equality graph across named providers. Source-local work runs at
+  its provider; estimates choose a connected fetch order, hash sets reduce
+  candidates, and the engine retains the original tuple semantics. Packed
+  joins run inside out under the same cumulative row/byte admission credits.
+  Per-side budgets also cap intermediates; buffered production and final
+  results have the explicit limits documented in §12.1. Aliases receive
+  independent input members, and array framing preserves array-valued rows.
 - **The engine result shape leaks nowhere.** Every surface — sync,
   async, provider — reproduces `undefined | item | items` exactly,
   which is why the window-wrapper trick exists at all.

package/README.md

@@ -730,3 +730,10 @@ Every subpath a consumer can import, derived from the manifest by
 | `@jarenjs/linq/messages` | JavaScript | declared |
 | `@jarenjs/linq/ai` | JavaScript | declared |
 <!--/fact-->
+
+Explicit cross-provider joins use `federate({ sources, maxRows, maxBytes,
+maxTotalRows, maxTotalBytes })`. Connected joins across three or more sources,
+including successive fluent `.join()` calls, preserve the engine's result
+order while sharing cumulative admission credits. See
+[QUERY-PEN §12.1](docs/QUERY-PEN.md#121-the-federation-boundary-federate) for
+planning, buffering limits and cleanup guarantees.

package/docs/DB-CLIENT.md

@@ -826,10 +826,10 @@ never builds one; the migration between two of them is
 
 ## 7. Cost
 
-`@jarenjs/linq/db` builds to **<!--fact:bundle.db-->627,769<!--/fact--> bytes** as a minified,
+`@jarenjs/linq/db` builds to **<!--fact:bundle.db-->633,786<!--/fact--> bytes** as a minified,
 tree-shaken ESM bundle — the figure `scripts/check-tree-shaking.js`
 measures and `npm run test:tree-shaking` reports, published rounded
-(<!--fact:bundle.db.kb-->628<!--/fact--> kB) beside the other nine subpath prices in
+(<!--fact:bundle.db.kb-->634<!--/fact--> kB) beside the other nine subpath prices in
 [docs/CONSUMING.md](../../../docs/CONSUMING.md).
 
 It is by far the largest of the ten, and the reason is §1.1's edge rather

package/docs/LINQ-FORMAT.md

@@ -37,7 +37,7 @@ is the index of those guides, and it is how a reader reaches any of them.
 | Document | Lines | What it writes, and when to open it |
 |---|---:|---|
 | [LINQ-FORMAT.md](LINQ-FORMAT.md) | 948 | this file, the binder and the family's **normative reference**: what a pen is, the rules all of them keep, the shared `JL01xx` table, and the cross-pen views derived from the guides it indexes. **Read it when** you want a rule that is true of every pen, an index of the documents, or one place to look up a method without knowing which pen owns it |
-| [QUERY-PEN.md](QUERY-PEN.md) | 1,725 | the chain, `.` — query documents (`jaren-query`) and the provider seam. **Read it when** you are querying data, or implementing a provider that answers a query document |
+| [QUERY-PEN.md](QUERY-PEN.md) | 1,735 | the chain, `.` — query documents (`jaren-query`) and the provider seam. **Read it when** you are querying data, or implementing a provider that answers a query document |
 | [SCHEMA-PEN.md](SCHEMA-PEN.md) | 1,205 | `./schema` — JSON Schema 2020-12: the structural keywords, the constraints and the annotations, each with a method of its own, plus `$query`, `$defs`/`$ref` recursion and the normalizer's per-field predicates. **Read it when** you are describing the shape of data — for validation, for a form, or as the base of an entity |
 | [MODEL-PEN.md](MODEL-PEN.md) | 1,092 | `./model` — the `x-entity` vocabulary on JSON Schema, and the `$model` 0.1 document `openStore` accepts unchanged. **Read it when** you are declaring a store's entities, their keys and their relations |
 | [JSLT-PEN.md](JSLT-PEN.md) | 955 | `./jslt` — `$jslt` 0.1 stylesheets: the envelope and its rules, whose bodies are captured over the matched value. **Read it when** you are transforming one document into another |
@@ -205,7 +205,7 @@ and the bundle is the byte count the tree-shaking probe builds.
 | Document | Subpath | Lines | Mapping rows | Worked examples | Refusals | Bundle |
 |---|---|---:|---:|---:|---:|---:|
 | [LINQ-FORMAT.md](LINQ-FORMAT.md) | — | 948 | — | — | — | — |
-| [QUERY-PEN.md](QUERY-PEN.md) | `.` | 1,725 | 34 | 8 | 15 | 174,131 B |
+| [QUERY-PEN.md](QUERY-PEN.md) | `.` | 1,735 | 34 | 8 | 15 | 174,241 B |
 | [SCHEMA-PEN.md](SCHEMA-PEN.md) | `./schema` | 1,205 | 82 | 10 | 4 | 36,717 B |
 | [MODEL-PEN.md](MODEL-PEN.md) | `./model` | 1,092 | 28 | 6 | 3 | 45,143 B |
 | [JSLT-PEN.md](JSLT-PEN.md) | `./jslt` | 955 | 17 | 8 | 3 | 19,856 B |
@@ -215,12 +215,12 @@ and the bundle is the byte count the tree-shaking probe builds.
 | [APP-PEN.md](APP-PEN.md) | `./app` | 1,143 | 22 | 7 | 3 | 51,006 B |
 | [FORMS-PEN.md](FORMS-PEN.md) | `./forms` | 940 | 18 | 6 | 3 | 40,873 B |
 | [AI-PEN.md](AI-PEN.md) | `./ai` | 98 | 12 | 1 | 3 | 16,904 B |
-| [MESSAGES-PEN.md](MESSAGES-PEN.md) | `./messages` | 105 | 9 | 2 | 1 | 18,337 B |
+| [MESSAGES-PEN.md](MESSAGES-PEN.md) | `./messages` | 105 | 9 | 2 | 1 | 18,363 B |
 | [JTLT-PEN.md](JTLT-PEN.md) | `./jtlt` | 83 | 13 | 1 | 2 | 16,725 B |
 | [PROJECT-PEN.md](PROJECT-PEN.md) | `./project` | 75 | 9 | 1 | 1 | 15,132 B |
 | [CHARTS-PEN.md](CHARTS-PEN.md) | `./charts` | 94 | 21 | 1 | 1 | 17,014 B |
-| [DB-CLIENT.md](DB-CLIENT.md) | `./db` | 893 | 41 | 4 | 2 | 627,769 B |
-| **16 documents** | | **12,391** | **371** | **73** | | |
+| [DB-CLIENT.md](DB-CLIENT.md) | `./db` | 893 | 41 | 4 | 2 | 633,786 B |
+| **16 documents** | | **12,401** | **371** | **73** | | |
 <!--/fact-->
 
 A pen whose mapping rows are far below its worked examples is a pen
@@ -262,7 +262,7 @@ it and each document publishes it. The rounded column is what
 <!--fact:pens.cost-->
 | Subpath | Document | Bundle | Rounded |
 |---|---|---:|---:|
-| `@jarenjs/linq` | [QUERY-PEN.md](QUERY-PEN.md) | 174,131 B | 174 kB |
+| `@jarenjs/linq` | [QUERY-PEN.md](QUERY-PEN.md) | 174,241 B | 174 kB |
 | `@jarenjs/linq/schema` | [SCHEMA-PEN.md](SCHEMA-PEN.md) | 36,717 B | 37 kB |
 | `@jarenjs/linq/model` | [MODEL-PEN.md](MODEL-PEN.md) | 45,143 B | 45 kB |
 | `@jarenjs/linq/jslt` | [JSLT-PEN.md](JSLT-PEN.md) | 19,856 B | 20 kB |
@@ -272,11 +272,11 @@ it and each document publishes it. The rounded column is what
 | `@jarenjs/linq/app` | [APP-PEN.md](APP-PEN.md) | 51,006 B | 51 kB |
 | `@jarenjs/linq/forms` | [FORMS-PEN.md](FORMS-PEN.md) | 40,873 B | 41 kB |
 | `@jarenjs/linq/ai` | [AI-PEN.md](AI-PEN.md) | 16,904 B | 17 kB |
-| `@jarenjs/linq/messages` | [MESSAGES-PEN.md](MESSAGES-PEN.md) | 18,337 B | 18 kB |
+| `@jarenjs/linq/messages` | [MESSAGES-PEN.md](MESSAGES-PEN.md) | 18,363 B | 18 kB |
 | `@jarenjs/linq/jtlt` | [JTLT-PEN.md](JTLT-PEN.md) | 16,725 B | 17 kB |
 | `@jarenjs/linq/project` | [PROJECT-PEN.md](PROJECT-PEN.md) | 15,132 B | 15 kB |
 | `@jarenjs/linq/charts` | [CHARTS-PEN.md](CHARTS-PEN.md) | 17,014 B | 17 kB |
-| `@jarenjs/linq/db` | [DB-CLIENT.md](DB-CLIENT.md) | 627,769 B | 628 kB |
+| `@jarenjs/linq/db` | [DB-CLIENT.md](DB-CLIENT.md) | 633,786 B | 634 kB |
 <!--/fact-->
 
 Read these as prices, not as scores. `./db` is the largest by an order of

package/docs/MESSAGES-PEN.md

@@ -100,6 +100,6 @@ gate compares generated files and all locale parameter sets with their sources.
 
 ## 7. Cost
 
-The isolated messages pen costs **<!--fact:bundle.messages-->18,337<!--/fact--> bytes**.
+The isolated messages pen costs **<!--fact:bundle.messages-->18,363<!--/fact--> bytes**.
 It carries the shared template compiler and generated vocabulary, with no locale,
 validator, forms or contract engine and no query chain.

package/docs/QUERY-PEN.md

@@ -472,8 +472,9 @@ time:
   emits `{ "$for": { "it": "$.Post[*]", "it2": "$.User[*]" }, "$where":
   { "$eq": ["$it.authorId", "$it2.id"] }, "$return": "$it" }` — the shape
   the store's translator answers in ONE statement when the result is a
-  bare binding (MODEL-FORMAT §10.2), and the declared residual over both
-  fetched roots when it is a projection (§10.6). `concat` stays
+  bare binding or a projection tree of member paths and constants
+  (MODEL-FORMAT §10.2). An opaque projection remains a declared residual
+  over the fetched roots (§10.6). `concat` stays
   same-source even within a scope: one input per document. A scope MAY
   carry `relations` — the relation tables of every root of the scope,
   keyed by root name (a store's does) — which is where a chained hop
@@ -732,46 +733,55 @@ const rows = await fromAsync(fed.source('orders'))
 spaces or other characters), and all of a federation's sources share one scope — which
 is exactly what admits the join. The federation is what executes it:
 
-1. each side's own document — the filters and the projection the chain
-   already packed per side — runs against ITS source, over that
-   source's own root;
-2. the smaller side (by declared `estimatedRows`, else the first named)
-   is streamed into a hash table keyed by the join key, counting rows
-   and serialized bytes against the budget as it fills;
-3. the other side is streamed and PROBED: a row whose key no build row
-   carries cannot pair, so it is dropped before it costs anything;
-4. the caller's own document runs in the engine over the two reduced
-   sets — the **resident join**, which is what decides.
-
-Step 4 is the contract. This boundary spells no join semantics of its
-own: the engine's `$eq` decides which rows pair, its ordering orders
-them, its projection shapes them. The hash table bounds the FETCH and
-nothing else, so a reduction that cannot key a value (a compound join
-key) keeps the row rather than guessing at it.
-
-`fed.source(name).explain(document)` answers the plan without running
-any of it: the `strategy`, the `budget`, the `build` and `probe` sides
-with their estimates, their own documents and whether each streams, and
-the `resident` document the engine answers.
-
-**A budget is a refusal, not a spill.** A side that reaches `maxRows` or
-`maxBytes` stops at the row that WOULD have broken it and raises
-`JL2008`; every cursor the call opened is closed exactly once, whether
-it answered, refused, failed or was aborted. A `signal` on the call is
-read at the ROW boundary — where a cursor can be let go without
-abandoning a pull the source is still inside — and a declared
-`estimatedRows` decides only which side BUILDS, never how much is held:
-a source that under-reports is refused by the budget all the same. A source offering a
-cursor (§12) is pulled row by row, so the bound is enforced before the
-memory is spent; one offering only `execute` answers whole, and
-`explain()` says `buffered` rather than pretending otherwise.
-
-Refused, by name: more than two sides in one federated document, a
-binding over a root the federation does not carry, and a join with no
-equality between one member of each side — without one the fetch is the
-cross product of two sources, which is what the budget exists to
-refuse. Non-goals: no spill, no distributed transaction, no
-cross-source write.
+1. Each side's own filters and projection run at its source. Cursor sources
+   receive that document directly; buffered sources receive an array wrapper
+   so array-valued projected rows retain their item boundaries.
+2. Mandatory equality predicates form a connected binding graph. The smallest
+   declared `estimatedRows` starts the fetch. Each subsequent side is the
+   smallest estimated side connected to an already fetched side. Missing or
+   equal estimates preserve binding declaration order. Equality inside an OR
+   does not establish an edge; disconnected bindings refuse `JL0005` before
+   any source opens.
+3. Each next side is reduced against the retained keys of its already fetched
+   neighbours. Singular member/index paths are supported, including quoted
+   names and negative array indexes. Compound key values are conservatively
+   retained for the engine to compare.
+4. The original query engine decides the result over those sets, in the
+   original binding order. Fetch order never changes tuple or result order.
+   Packed joins emitted by successive `.join()` calls execute inside out;
+   their projected results become bounded intermediate sides. Aliases of one
+   source retain independent fetched sets.
+
+`explain(document)` reports `strategy`, per-side `budget`, `combinedBudget`,
+`order` (the ordered side descriptions), and `resident.document`. Each side
+names its source, estimate, join key, child document and `row`/`buffered`
+streaming mode. Nested sides additionally expose `children`. `build` and
+`probe` remain the first two sides for compatibility.
+
+**Budgets are admission credits.** `maxRows` and `maxBytes` apply separately
+at each source or intermediate. `maxTotalRows` and `maxTotalBytes` cover all
+retained source and intermediate admissions in the entire call, and default
+to twice their corresponding per-side budget. All four are positive safe
+integers. Credits are cumulative: freeing an intermediate's inputs does not
+refund them. This conservative rule makes a nested plan's total explicit.
+
+A cursor refuses with `JL2008` before retaining the row that would exceed a
+credit. Buffered sources are checked after they produce their array. Nested
+resident phrases additionally cap `sequenceItems` and `resultItems` at
+`maxRows` (or a stricter caller limit); exceeding those intermediate limits
+raises `JL2008`. Intermediate bytes are checked after projection. These are
+bounds on admitted data and intermediate item counts, **not** a promise to
+bound a buffered provider's heap, the size of one constructed value, or the
+final resident result. A caller can also supply query-engine limits for that
+final result. Estimates affect planning only, never admission.
+
+Every opened cursor closes exactly once on success, budget refusal, child
+failure or cancellation. `signal` is checked at row boundaries and passed to
+providers. Cleanup failures preserve a primary execution failure and never
+strand another opened cursor.
+
+There is no spill, distributed transaction or cross-source write. A merge
+strategy remains unavailable because providers declare no ordering guarantee.
 
 ## 13. Worked examples
 
@@ -1195,7 +1205,7 @@ proves that too, so the exclusion cannot hide a chain refusal).
 | `JL2004` | a provider's `execute()` answered a promise on the synchronous surface |
 | `JL2005` | a push queue was fed after `end()` |
 | `JL2006` | a provider answered an element terminal with something other than one array |
-| `JL2008` | a federated fetch reached one side's row or byte budget (§12.1) |
+| `JL2008` | a federated fetch or intermediate reached a per-side or combined row/byte budget (§12.1) |
 
 `JL2007` is the client door's, not the chain's: `createDbLedger`'s stale
 settlement ([DB-CLIENT.md §2.6](DB-CLIENT.md#26-the-ledger)); it is
@@ -1672,7 +1682,7 @@ are shorter:
 ## 17. Cost
 
 A consumer importing `from` from `@jarenjs/linq` and calling one
-terminal bundles **<!--fact:bundle.chain-->174,131<!--/fact--> bytes** (esbuild, ESM, minified, tree-shaken,
+terminal bundles **<!--fact:bundle.chain-->174,241<!--/fact--> bytes** (esbuild, ESM, minified, tree-shaken,
 `platform: 'neutral'`). The figure is measured by
 `scripts/check-tree-shaking.js`'s chain probe and compared with this
 section on every `npm run test:tree-shaking`: it is derived, never typed,
@@ -1706,7 +1716,7 @@ making:
 `docs/CONSUMING.md` states the rounded price of all ten subpaths in one
 table, each figure held equal to the same measurements. Two of its rows
 are the ones to read together: the chain at <!--fact:bundle.chain.kb-->174<!--/fact--> kB and
-`./db` at <!--fact:bundle.db.kb-->628<!--/fact--> kB.
+`./db` at <!--fact:bundle.db.kb-->634<!--/fact--> kB.
 The client costs what the store costs, by construction, and the chain
 costs what running a query costs.
 
@@ -1715,7 +1725,7 @@ the reason is worth knowing: a bundler counts a shared module once, and
 the chain and every pen share the expression capture (`expression.js`)
 and the coded errors under it (`errors.js`, and `@jarenjs/core`'s error
 and object helpers). A consumer importing the chain AND the schema pen
-bundles **<!--fact:bundle.chain.withSchemaPen-->198,801<!--/fact--> bytes** — **<!--fact:bundle.chain.shared-->12,047<!--/fact--> bytes** less than the sum of the
+bundles **<!--fact:bundle.chain.withSchemaPen-->198,911<!--/fact--> bytes** — **<!--fact:bundle.chain.shared-->12,047<!--/fact--> bytes** less than the sum of the
 figure above and [SCHEMA-PEN.md](SCHEMA-PEN.md#7-cost) §7's, which is
 what those shared modules weigh. The probe measures that pair too, so
 the saving is derived like everything else here. What the chain does NOT

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/linq",
   "private": false,
-  "version": "0.73.0",
+  "version": "0.75.0",
   "type": "module",
   "main": "./src/index.js",
   "types": "./types/index.d.ts",
@@ -104,13 +104,13 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.73.0",
-    "@jarenjs/json": "^0.73.0"
+    "@jarenjs/core": "^0.75.0",
+    "@jarenjs/json": "^0.75.0"
   },
   "peerDependencies": {
-    "@jarenjs/db": "^0.73.0",
-    "@jarenjs/formats": "^0.73.0",
-    "@jarenjs/validate": "^0.73.0"
+    "@jarenjs/db": "^0.75.0",
+    "@jarenjs/formats": "^0.75.0",
+    "@jarenjs/validate": "^0.75.0"
   },
   "peerDependenciesMeta": {
     "@jarenjs/db": {

package/src/federate.js

@@ -1,51 +1,26 @@
 //@ts-check
 /**
- * @file The federation boundary (QUERY-PEN.md §13): an EXPLICIT opt-in
- * to reading two different provider sources under one query document.
+ * @file Explicit bounded federation (QUERY-PEN §12.1). Source-local
+ * documents execute at their providers; a connected mandatory equality
+ * graph chooses the fetch order by declared estimates, with binding order
+ * breaking ties. Hash membership only removes impossible candidates: the
+ * query engine decides the resident result and its original tuple order.
  *
- * The rule everywhere else in this package is that a query document
- * reads ONE input, and a join whose sides come from two unrelated
- * sources is `JL0005` at build time. That refusal is not a limitation
- * to route around — it is what keeps a chain honest about where the
- * work happens. A cross-source join cannot be pushed anywhere: someone
- * has to hold rows in memory, and a surface that did it implicitly
- * would turn a one-line chain into an unbounded fetch of two
- * databases.
+ * Packed joins emitted by successive LINQ joins execute inside out. Every
+ * source and intermediate has a per-side budget, and one shared admission
+ * counter covers the entire call. Intermediate phrase materialization is
+ * capped through the query engine's own limits. Buffered providers and
+ * intermediate byte sizes can only be checked after they produce an array;
+ * cursor providers admit each retained row before holding it.
  *
- * So it is spelled out instead. `federate()` takes the sources by
- * name, takes the budgets that make the fetch finite, and hands back
- * one provider-compatible source per name, all sharing one scope — so
- * the join the chain already knows how to build is admitted, and the
- * federation is what executes it:
- *
- *   1. each binding's own document — the filters and the projection the
- *      chain already packed per side — runs against ITS source;
- *   2. the smaller side (declared estimate, else the first named) is
- *      streamed into a hash table keyed by the join key, counting rows
- *      and serialized bytes against the budget as it fills;
- *   3. the other side is streamed and PROBED: a row whose key no build
- *      row carries cannot join, so it is dropped before it costs
- *      anything;
- *   4. the caller's own document runs in the engine over the two
- *      reduced sets — the resident join, which is what decides.
- *
- * Step 4 is why this file spells no join semantics of its own. The
- * engine's `$eq` decides which rows pair, its ordering orders them and
- * its projection shapes them; the hash table exists to bound the FETCH,
- * never to answer the query. A reduction that dropped a row the engine
- * would have joined would be a wrong answer, so the probe keeps
- * anything it cannot key (a compound key value) rather than guessing.
- *
- * Non-goals, named rather than discovered: no spill (a budget is a
- * refusal, not a disk), no distributed transaction, no cross-source
- * write, and no non-equality join — without an equality key the fetch
- * is the cross product, which is exactly what the budget exists to
- * refuse.
+ * No spill, distributed transaction, cross-source writes, or disconnected
+ * cartesian products. Ordinary unrelated-source join() still refuses JL0005.
  */
 
 import { LinqBuildError, LinqRuntimeError } from './errors.js';
 import { compileDocument, isProviderSource, providerRoot } from './provider.js';
 import { memberSegment } from './expression.js';
+import { parseJSONPath } from '@jarenjs/json/path';
 
 /** The strategies this boundary knows. One, for now, and it says so. */
 const STRATEGIES = new Set(['hash']);
@@ -57,7 +32,7 @@ const STRATEGIES = new Set(['hash']);
  * @returns {number}
  */
 function budgetOf(value, what) {
-  if (!Number.isInteger(value) || value < 1) {
+  if (!Number.isSafeInteger(value) || value < 1) {
     throw new LinqBuildError('JL0005',
       `federate() needs a positive integer ${what} — a federated fetch holds rows in memory, `
       + 'and a bound is what makes that finite');
@@ -69,15 +44,22 @@ function budgetOf(value, what) {
  * The one member path a `'$it.a.b'` operand names, or `null` for
  * anything else (an operator call, a literal, the binding itself).
  * @param {any} node
- * @returns {{ binding: string, path: string[] } | null}
+ * @returns {{ binding: string, path: (string | number)[] } | null}
  */
 function memberPathOf(node) {
   if (typeof node !== 'string' || !node.startsWith('$')) return null;
-  const parts = node.slice(1).split('.');
-  if (parts.length < 2) return null;
-  const [binding, ...path] = parts;
-  if (binding === '' || path.some((name) => name === '')) return null;
-  return { binding, path };
+  const match = /^\$([^.[\]]+)([.[])/.exec(node);
+  if (match === null) return null;
+  try {
+    const { segments } = parseJSONPath(`$${node.slice(match[1].length + 1)}`);
+    if (!segments.every((segment) => !segment.descendant && segment.selectors.length === 1
+      && ['name', 'index'].includes(segment.selectors[0].kind))) return null;
+    return { binding: match[1], path: segments.map((segment) => {
+      const selector = segment.selectors[0];
+      return selector.kind === 'name' ? selector.name : selector.index;
+    }) };
+  }
+  catch { return null; }
 }
 
 /** Read one member path out of a row; `undefined` where it is absent. */
@@ -85,7 +67,14 @@ function valueAt(row, path) {
   let value = row;
   for (const name of path) {
     if (value === null || typeof value !== 'object') return undefined;
-    value = value[name];
+    if (typeof name === 'number') {
+      if (!Array.isArray(value)) return undefined;
+      value = value[name < 0 ? value.length + name : name];
+    }
+    else {
+      if (Array.isArray(value) || !Object.hasOwn(value, name)) return undefined;
+      value = value[name];
+    }
   }
   return value;
 }
@@ -169,7 +158,7 @@ function locateFlwor(document) {
  * @param {Map<string, any>} members - federated name → member record
  * @returns {any}
  */
-function planFederation(document, members) {
+function planFederation(document, members, nested = false) {
   const located = locateFlwor(document);
   const query = located === null ? document : located.flwor;
   const bindings = query?.$for;
@@ -178,10 +167,8 @@ function planFederation(document, members) {
       'a federated document ranges over its sources with $for — this one has no bindings');
   }
   const names = Object.keys(bindings);
-  if (names.length !== 2) {
-    throw new LinqBuildError('JL0005',
-      `a federated fetch joins exactly two sources, not ${names.length} — `
-      + 'federate one pair at a time, or load the third side yourself');
+  if (names.length < (nested ? 1 : 2)) {
+    throw new LinqBuildError('JL0005', 'a federated fetch needs at least two source bindings');
   }
 
   /** @type {any[]} */
@@ -191,15 +178,20 @@ function planFederation(document, members) {
     // the two spellings the chain builds: a bare root, or the side's
     // own packed document (its `$where`, its `$orderby`, its `$return`)
     const packed = Array.isArray(value) && value.length === 1 ? value[0] : null;
-    // a packed side ranges over ONE root: a side that is itself a join
-    // is a federation of a federation, which this boundary does not
-    // plan and will not guess at
+    // A source-local phrase has one bare root; a packed join is planned
+    // recursively and becomes a bounded intermediate side.
     const inner = packed === null ? [] : Object.keys(packed.$for ?? {});
     const root = packed === null ? value
       : (inner.length === 1 ? packed.$for[inner[0]] : null);
     if (typeof root !== 'string') {
-      throw new LinqBuildError('JL0005',
-        `the binding '${binding}' does not range over a federated source`);
+      if (packed === null || inner.length === 0) {
+        throw new LinqBuildError('JL0005',
+          `the binding '${binding}' does not range over a federated source`);
+      }
+      const child = planFederation(packed, members, true);
+      sides.push({ binding, nested: child, packed, root: null,
+        member: { name: binding, estimatedRows: undefined } });
+      continue;
     }
     const member = members.get(root);
     if (member === undefined) {
@@ -210,52 +202,57 @@ function planFederation(document, members) {
     sides.push({ binding, member, packed, root });
   }
 
-  const key = joinKey(query.$where, sides);
-  // the estimate decides which side fills the table: a hash join holds
-  // the BUILD side whole, so the smaller declared side is the one to
-  // hold. Undeclared estimates keep the caller's own order, which is
-  // stable and says so in `explain()`
-  const [first, second] = sides;
-  const build = (second.member.estimatedRows ?? Infinity)
-    < (first.member.estimatedRows ?? Infinity) ? second : first;
-  const probe = build === first ? second : first;
-  return {
-    strategy: 'hash',
-    build: { ...build, key: key[build.binding] },
-    probe: { ...probe, key: key[probe.binding] },
-    // the resident document is the caller's own with each side reduced
-    // to its root: the packed work has already run at the source, and
-    // whatever the terminal wrapped around the query is put back
-    resident: located.rewrap({ ...query,
-      $for: Object.fromEntries(sides.map((side) => [side.binding, side.root])) }),
-  };
-}
-
-/**
- * The equality key that links the two sides, or the refusal.
- * @param {any} where
- * @param {any[]} sides
- * @returns {Record<string, string[]>}
- */
-function joinKey(where, sides) {
-  const conjuncts = where === undefined || where === null ? []
-    : (Array.isArray(where?.$and) ? where.$and : [where]);
-  const [a, b] = sides;
-  for (const conjunct of conjuncts) {
-    const operands = conjunct?.$eq;
-    if (!Array.isArray(operands) || operands.length !== 2) continue;
+  // A mandatory equality graph supplies the fetch order. OR branches
+  // never prove an edge. Estimates choose among connected candidates;
+  // equal or absent estimates retain binding declaration order.
+  const edges = [];
+  const visit = (where) => {
+    if (Array.isArray(where?.$and)) { where.$and.forEach(visit); return; }
+    const operands = where?.$eq;
+    if (!Array.isArray(operands) || operands.length !== 2) return;
     const left = memberPathOf(operands[0]);
     const right = memberPathOf(operands[1]);
-    if (left === null || right === null) continue;
-    if (left.binding === a.binding && right.binding === b.binding)
-      return { [a.binding]: left.path, [b.binding]: right.path };
-    if (left.binding === b.binding && right.binding === a.binding)
-      return { [b.binding]: left.path, [a.binding]: right.path };
+    if (left && right && left.binding !== right.binding
+      && names.includes(left.binding) && names.includes(right.binding)) edges.push({ left, right });
+  };
+  visit(query.$where);
+  const remaining = [...sides];
+  const order = [];
+  const selected = new Set();
+  while (remaining.length > 0) {
+    const candidates = remaining.filter((side) => selected.size === 0 || edges.some(({ left, right }) =>
+      (left.binding === side.binding && selected.has(right.binding))
+      || (right.binding === side.binding && selected.has(left.binding))));
+    if (candidates.length === 0) throw new LinqBuildError('JL0005',
+      'a federated join needs an equality between one member of each side in a connected binding graph');
+    candidates.sort((a, b) => (a.member.estimatedRows ?? Infinity) - (b.member.estimatedRows ?? Infinity));
+    const side = candidates[0];
+    side.links = edges.flatMap(({ left, right }) => {
+      const [own, other] = left.binding === side.binding ? [left, right] : [right, left];
+      return own.binding === side.binding && selected.has(other.binding)
+        ? [{ key: own.path, binding: other.binding, otherKey: other.path }] : [];
+    });
+    const edge = edges.find(({ left, right }) => left.binding === side.binding || right.binding === side.binding);
+    side.key = edge === undefined ? [] : (edge.left.binding === side.binding ? edge.left.path : edge.right.path);
+    order.push(side); selected.add(side.binding); remaining.splice(remaining.indexOf(side), 1);
+  }
+  // Bindings may independently project or alias the same source. Give
+  // those sets separate input members so one cannot overwrite another.
+  const used = new Set(sides.filter((side) => side.root !== null).map((side) => side.member.name));
+  const roots = new Set();
+  for (const side of sides) {
+    side.inputName = side.member.name;
+    if (side.root === null || roots.has(side.root)) {
+      let name = `_federated${sides.indexOf(side)}`;
+      while (used.has(name)) name += '_';
+      used.add(name); side.inputName = name; side.root = `$${memberSegment(name)}[*]`;
+    }
+    roots.add(side.root);
   }
-  throw new LinqBuildError('JL0005',
-    'a federated join needs an equality between one member of each side — without one the '
-    + 'fetch is the cross product of two sources, which is what the budget exists to refuse '
-    + '(a non-equality condition still applies, but it cannot bound the fetch)');
+  return { strategy: 'hash', sides: order, build: order[0], probe: order[1],
+    resident: located.rewrap({ ...query,
+      $for: Object.fromEntries(sides.map((side) => [side.binding,
+        side.packed === null ? side.root : [side.root]])) }) };
 }
 
 /**
@@ -274,7 +271,7 @@ function joinKey(where, sides) {
  * @param {any[]} open - cursors to close, in order
  * @returns {Promise<{ rows: any[], read: number, bytes: number, streamed: boolean }>}
  */
-async function fetchSide(member, document, options, budget, keep, open) {
+async function fetchSide(member, document, options, budget, keep, open, combined) {
   const kept = [];
   let read = 0;
   let bytes = 0;
@@ -292,6 +289,11 @@ async function fetchSide(member, document, options, budget, keep, open) {
         `the federated fetch of '${member.name}' reached its ${budget.maxBytes}-byte budget `
         + `at row ${kept.length + 1} — narrow the sides, or raise maxBytes`);
     }
+    if (combined.rows + 1 > combined.maxRows || combined.bytes + size > combined.maxBytes) {
+      throw new LinqRuntimeError('JL2008',
+        'the federated fetch reached its combined row or byte budget — narrow the sides, or raise maxTotalRows/maxTotalBytes');
+    }
+    combined.rows++; combined.bytes += size;
     bytes += size;
     kept.push(row);
   };
@@ -321,19 +323,18 @@ async function fetchSide(member, document, options, budget, keep, open) {
     return { rows: kept, read, bytes, streamed: true };
   }
   stopIfAborted();
-  const answer = await member.provider.execute(document, options);
-  for (const row of itemsOf(answer)) admit(row);
+  // Frame the sequence as one array so an array-valued row is still
+  // one row. Cursor sources already supply that item boundary.
+  const answer = await member.provider.execute([document], options);
+  if (!Array.isArray(answer)) throw new LinqRuntimeError('JL2008',
+    `the federated source '${member.name}' did not answer the requested array frame`);
+  for (const row of answer) { stopIfAborted(); admit(row); }
   return { rows: kept, read, bytes, streamed: false };
 }
 
-/** The engine's answer shape as a row list: none, one, or many. */
-function itemsOf(answer) {
-  if (answer === undefined) return [];
-  return Array.isArray(answer) ? answer : [answer];
-}
-
 /** One side's document, with the federated root rewritten to the source's own. */
 function childDocument(side) {
+  if (side.nested) return side.packed;
   const own = providerRoot(side.member.provider);
   if (side.packed === null) return { $for: { it: own }, $return: '$it' };
   const binding = Object.keys(side.packed.$for)[0];
@@ -344,7 +345,7 @@ function childDocument(side) {
  * An explicit federation boundary over two or more provider sources.
  *
  * @param {{ sources: Record<string, any>, maxRows: number, maxBytes: number,
- *   strategy?: string }} spec
+ *   maxTotalRows?: number, maxTotalBytes?: number, strategy?: string }} spec
  * @returns {{ source: (name: string) => any, names: readonly string[] }}
  * @example
  * const fed = federate({
@@ -378,6 +379,11 @@ export function federate(spec) {
     maxBytes: budgetOf(spec.maxBytes, 'maxBytes'),
   };
 
+  const totals = {
+    maxRows: budgetOf(spec.maxTotalRows ?? budget.maxRows * 2, 'maxTotalRows'),
+    maxBytes: budgetOf(spec.maxTotalBytes ?? budget.maxBytes * 2, 'maxTotalBytes'),
+  };
+
   /** The scope every member shares: what admits the join, and nothing else. */
   const scope = Object.freeze({ federation: true });
   /** @type {Map<string, any>} federated root → member */
@@ -415,34 +421,43 @@ export function federate(spec) {
     const plan = planFederation(document, members);
     /** @type {any[]} */
     const open = [];
-    try {
-      const buildDoc = childDocument(plan.build);
-      const built = await fetchSide(plan.build.member, buildDoc, options, budget,
-        () => true, open);
-      // the table is the REDUCTION, never the answer: it says which
-      // keys can pair, and the engine decides which rows do
-      const keys = new Set();
-      let unkeyed = false;
-      for (const row of built.rows) {
-        const key = hashKey(valueAt(row, plan.build.key));
-        if (key === null) unkeyed = true;
-        else keys.add(key);
+    const combined = { ...totals, rows: 0, bytes: 0 };
+    const run = async (current, intermediate = false) => {
+      const fetched = new Map();
+      for (const side of current.sides) {
+        const tables = side.links.map((link) => {
+          const keys = new Set();
+          let unkeyed = false;
+          for (const row of fetched.get(link.binding)) {
+            const key = hashKey(valueAt(row, link.otherKey));
+            if (key === null) unkeyed = true; else keys.add(key);
+          }
+          return { ...link, keys, unkeyed };
+        });
+        const keep = (row) => tables.every((table) => {
+          const key = hashKey(valueAt(row, table.key));
+          return table.unkeyed || key === null || table.keys.has(key);
+        });
+        const member = side.nested ? { ...side.member,
+          provider: { execute: () => run(side.nested, true) } } : side.member;
+        const found = await fetchSide(member, childDocument(side), options, budget, keep, open, combined);
+        fetched.set(side.binding, found.rows);
       }
-      const probeDoc = childDocument(plan.probe);
-      const probed = await fetchSide(plan.probe.member, probeDoc, options, budget,
-        (row) => {
-          if (unkeyed) return true;
-          const key = hashKey(valueAt(row, plan.probe.key));
-          return key === null || keys.has(key);
-        }, open);
-
-      const input = {
-        [plan.build.member.name]: built.rows,
-        [plan.probe.member.name]: probed.rows,
-      };
-      const compiled = compileDocument(plan.resident,
-        { ...options, externals: options?.externalNames ?? [] });
-      const answer = compiled(input, options?.externals ?? {});
+      const input = Object.fromEntries(current.sides.map((side) => [side.inputName, fetched.get(side.binding)]));
+      const limits = intermediate ? { ...options?.limits,
+        sequenceItems: Math.min(options?.limits?.sequenceItems ?? Infinity, budget.maxRows),
+        resultItems: Math.min(options?.limits?.resultItems ?? Infinity, budget.maxRows) } : options?.limits;
+      const compiled = compileDocument(intermediate ? [current.resident] : current.resident,
+        { ...options, limits, externals: options?.externalNames ?? [] });
+      try { return compiled(input, options?.externals ?? {}); }
+      catch (error) {
+        if (intermediate && error.code === 'JQ2009' && /sequenceItems|resultItems/.test(error.message)) throw new LinqRuntimeError('JL2008',
+          'a federated intermediate join reached its row budget');
+        throw error;
+      }
+    };
+    try {
+      const answer = await run(plan);
       // the fetch answered, so a cursor that will not close IS this
       // call's failure rather than something to swallow
       await closeAll(open);
@@ -484,13 +499,16 @@ export function federate(spec) {
       source: side.member.name,
       root: side.root,
       estimatedRows: side.member.estimatedRows ?? null,
-      key: `$${side.binding}.${side.key.join('.')}`,
+      key: `$${side.binding}${side.key.map((part) => typeof part === 'number' ? `[${part}]` : memberSegment(part)).join('')}`,
       document: childDocument(side),
-      streaming: typeof side.member.provider.cursor === 'function' ? 'row' : 'buffered',
+      streaming: typeof side.member.provider?.cursor === 'function' ? 'row' : 'buffered',
+      ...(side.nested ? { children: side.nested.sides.map(describe) } : {}),
     });
     return {
       strategy: plan.strategy,
       budget: { ...budget },
+      combinedBudget: { maxTotalRows: totals.maxRows, maxTotalBytes: totals.maxBytes },
+      order: plan.sides.map(describe),
       build: describe(plan.build),
       probe: describe(plan.probe),
       // the join itself is the engine's, over what the two fetches

package/src/messages/vocabulary.js

@@ -135,7 +135,8 @@ export const CATALOGS = deepFreeze({
     ],
     "x-form/assert": [],
     "form/addItem": [],
-    "form/removeItem": []
+    "form/removeItem": [],
+    "form/jsonPlaceholder": []
   },
   "contract": {
     "contract/not-found": [],

package/types/index.d.ts

@@ -795,15 +795,18 @@ export interface FederatedSide {
   readonly document: unknown;
   /** Whether this side is pulled row by row, or answered whole. */
   readonly streaming: 'row' | 'buffered';
+  readonly children?: readonly FederatedSide[];
 }
 
 /** What a federated document will do, without doing any of it (§12.1). */
 export interface FederationPlan {
   readonly strategy: 'hash';
   readonly budget: { readonly maxRows: number; readonly maxBytes: number };
+  readonly combinedBudget: { readonly maxTotalRows: number; readonly maxTotalBytes: number };
+  readonly order: readonly FederatedSide[];
   readonly build: FederatedSide;
   readonly probe: FederatedSide;
-  /** The join itself is the engine's, over the two reduced sides. */
+  /** The engine evaluates the original binding order over the reduced sets. */
   readonly resident: { readonly document: unknown };
 }
 
@@ -822,13 +825,18 @@ export interface FederatedSource<T = unknown> extends AsyncProvider<T> {
  * out of that, by naming the sources and the bounds together: each
  * side's own filters and projection run at its source, the smaller side
  * fills a bounded hash table, the other is probed against it, and the
- * caller's own document decides over the two reduced sets. A side that
+ * caller's own document decides over the reduced sets. Connected N-way
+ * graphs and nested fluent joins share cumulative admission credits. A side that
  * reaches `maxRows` or `maxBytes` raises `JL2008` at the row that would
  * have broken the bound. */
 export function federate(spec: {
   sources: Record<string, AsyncProvider | { provider: AsyncProvider; estimatedRows?: number }>;
   maxRows: number;
   maxBytes: number;
+  /** Shared admission credits across source reads and intermediate sets; defaults to 2 * maxRows. */
+  maxTotalRows?: number;
+  /** Defaults to 2 * maxBytes. Buffered providers/intermediates are checked after production. */
+  maxTotalBytes?: number;
   strategy?: 'hash';
 }): {
   source<T = unknown>(name: string): FederatedSource<T>;

package/types/message-vocabulary.d.ts

@@ -1,7 +1,7 @@
 // Derived from the English catalogs by scripts/generate-message-pen.js.
 export interface CatalogIds {
   validate: "type" | "required" | "minimum" | "maximum" | "exclusiveMinimum" | "exclusiveMaximum" | "multipleOf" | "minLength" | "maxLength" | "pattern" | "additionalProperties" | "minProperties" | "maxProperties" | "minItems" | "maxItems" | "uniqueItems" | "contains" | "items" | "allOf" | "anyOf" | "oneOf" | "not" | "format" | "if" | "then" | "else" | "false schema" | "$query" | "JQ2001" | "JQ2003";
-  forms: "form/required" | "form/type" | "form/const" | "form/enum" | "form/minLength" | "form/maxLength" | "form/pattern" | "form/format" | "form/minimum" | "form/maximum" | "form/exclusiveMinimum" | "form/exclusiveMaximum" | "form/multipleOf" | "form/minItems" | "form/maxItems" | "form/uniqueItems" | "form/minProperties" | "form/maxProperties" | "x-form/assert" | "form/addItem" | "form/removeItem";
+  forms: "form/required" | "form/type" | "form/const" | "form/enum" | "form/minLength" | "form/maxLength" | "form/pattern" | "form/format" | "form/minimum" | "form/maximum" | "form/exclusiveMinimum" | "form/exclusiveMaximum" | "form/multipleOf" | "form/minItems" | "form/maxItems" | "form/uniqueItems" | "form/minProperties" | "form/maxProperties" | "x-form/assert" | "form/addItem" | "form/removeItem" | "form/jsonPlaceholder";
   contract: "contract/not-found" | "contract/method-not-allowed" | "contract/body-too-large" | "contract/unsupported-media" | "contract/malformed-json" | "contract/invalid-input" | "contract/idempotency-key-required" | "contract/handler-failed" | "contract/idempotency-conflict" | "contract/invalid-output" | "contract/malformed-path" | "contract/malformed-query" | "contract/not-implemented" | "contract/precondition-failed" | "contract/invalid-header" | "contract/handler-error" | "contract/client-invalid-input" | "contract/network" | "contract/cancelled" | "contract/invalid-response" | "contract/key-storage-failed" | "contract/undeclared-response" | "contract/not-a-contract" | "contract/incompatible" | "contract/host-failed" | "contract/local-handler-failed" | "contract/unknown-operation" | "contract/port-timeout" | "contract/malformed-frame" | "contract/channel-closed" | "contract/not-a-stream" | "contract/invalid-snapshot" | "contract/seq-regression" | "contract/stream-error" | "contract/heartbeat-missed" | "contract/slow-consumer" | "contract/reconnect-exhausted";
 }
 export interface MessageParameters {
@@ -56,6 +56,7 @@ export interface MessageParameters {
   "x-form/assert": never;
   "form/addItem": never;
   "form/removeItem": never;
+  "form/jsonPlaceholder": never;
   "contract/not-found": never;
   "contract/method-not-allowed": "allow";
   "contract/body-too-large": "limit" | "op";