@noy-db/hub 0.7.0 → 0.8.0-pre.0

package/dist/{chunk-VTFVLCUH.js → chunk-3JWHAR6E.js}

@@ -1,6 +1,6 @@
 import {
   QuiesceTimeoutError
-} from "./chunk-7O3Y4PPD.js";
+} from "./chunk-244VXYPG.js";
 
 // src/port/by/types.ts
 function isQuorum(writers, generation, excludeWriterId) {
@@ -51,4 +51,4 @@ export {
   isQuorum,
   runDrainBarrier
 };
-//# sourceMappingURL=chunk-VTFVLCUH.js.map
+//# sourceMappingURL=chunk-3JWHAR6E.js.map

package/dist/{chunk-YMUFFJCO.js → chunk-3TDUWVWB.js}

@@ -1,6 +1,6 @@
 // src/with-lookup/reduce/strategy.ts
 var NOT_ENABLED = new Error(
-  'Aggregate / groupBy is not enabled on this Noydb instance. Import `{ withReduce }` from "@noy-db/hub/reduce" and pass it to `createNoydb({ reduceStrategy: withReduce() })`.'
+  'Aggregate / groupBy / window is not enabled on this Noydb instance. Import `{ withReduce }` from "@noy-db/hub/reduce" and pass it to `createNoydb({ reduceStrategy: withReduce() })`.'
 );
 var NO_REDUCE = {
   aggregate() {
@@ -12,6 +12,9 @@ var NO_REDUCE = {
   groupByN() {
     throw NOT_ENABLED;
   },
+  window() {
+    throw NOT_ENABLED;
+  },
   scanAggregate() {
     throw NOT_ENABLED;
   }
@@ -20,4 +23,4 @@ var NO_REDUCE = {
 export {
   NO_REDUCE
 };
-//# sourceMappingURL=chunk-YMUFFJCO.js.map
+//# sourceMappingURL=chunk-3TDUWVWB.js.map

package/dist/chunk-3TDUWVWB.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/with-lookup/reduce/strategy.ts"],"sourcesContent":["/**\n * Strategy seam between the core Query / ScanBuilder chain and the\n * optional aggregate / groupBy service. Core imports\n * `ReduceStrategy` as a TYPE-ONLY symbol and `NO_REDUCE` as a\n * tiny runtime stub.\n *\n * The heavy machinery — `Reduction`, `GroupedQuery`, the\n * reducer-step logic — is only reachable from `withReduce()` in\n * `./active.ts`, which is only exported through the\n * `@noy-db/hub/reduce` subpath. Consumers that don't import the\n * subpath ship none of the ~886 LOC.\n *\n * @internal\n */\n\nimport type {\n  Reduction,\n  ReduceSpec,\n  ReduceResult,\n  ReductionUpstream,\n} from './reduction.js'\nimport type { GroupedQuery, GroupedQueryN } from './groupby.js'\nimport type { GroupMaintenanceSource } from '../../kernel/query/live/incremental.js'\nimport type { WindowFactory, WindowSpec, WindowedQuery } from './window.js'\n/**\n * Re-exported so `kernel/query/builder.ts` can name `.window()`'s spec and\n * return type WITHOUT a second spine→service import specifier: this strategy\n * module is the seam the kernel is allowed to reach (`check-architecture.mjs`\n * → PRE_EXISTING_SPINE_SERVICE_IMPORTS), and adding a new grandfathered path\n * there for a type-only import would loosen the ratchet for no gain.\n */\nexport type { WindowSpec, WindowedQuery } from './window.js'\n\n/**\n * Options for {@link withReduce}. `window` is the {@link WindowFactory}\n * returned by `withWindow()` — omitted, `.window()` throws and the window\n * engine stays out of the bundle entirely (see `window.ts` § \"Opting in\").\n */\nexport interface ReduceOptions {\n  readonly window?: WindowFactory\n}\nimport type { ViaPipeline } from '../../kernel/via/pipeline.js'\nimport type { HydrationGate } from '../../kernel/query/hydration.js'\n\n/**\n * Seam interface. `@internal` — will promote to public only when the\n * aggregate service is extracted into its own package.\n *\n * @internal\n */\nexport interface ReduceStrategy {\n  /**\n   * Build an `Reduction<R>` for `Query.aggregate(spec)`. `executeRecords`\n   * is a closure that produces the matching record set when the\n   * reduction runs. NO_REDUCE throws; the active strategy\n   * constructs a real `Reduction`.\n   */\n  aggregate<Spec extends ReduceSpec>(\n    executeRecords: () => readonly unknown[],\n    spec: Spec,\n    upstreams: readonly ReductionUpstream[],\n    /** #1414 — the source collection's cold gate, when there is one. */\n    gate?: HydrationGate,\n  ): Reduction<ReduceResult<Spec>>\n\n  /**\n   * Build a `GroupedQuery<T, F, S>` for `Query.groupBy(field)`. Same\n   * closure / upstream inputs as `aggregate` plus the group key field.\n   */\n  groupBy<T, F extends string, S extends keyof T = never, M extends keyof T & string = never>(\n    executeRecords: () => readonly unknown[],\n    field: F,\n    upstreams: readonly ReductionUpstream[],\n    dictLabelResolver?: (\n      key: string,\n      locale: string,\n      fallback?: string | readonly string[],\n    ) => Promise<string | undefined>,\n    via?: ViaPipeline,\n    /**\n     * #1341 (grouped half) — the delta-maintenance seam. Supplied by\n     * `Query.groupBy()` only for a plan `canMaintainIncrementally()` admits;\n     * omitted, `.groupBy().aggregate().live()` re-runs in full as before.\n     */\n    maintenance?: GroupMaintenanceSource,\n  ): GroupedQuery<T, F, S, M>\n\n  /**\n   * Variadic-keyed sibling — builds a `GroupedQueryN<T, F, S>` for\n   * `Query.groupBy(...fields)`. No dictLabelResolver — `<field>Label`\n   * projection only applies to single-field groupings, which dispatch\n   * through `groupBy` above.\n   */\n  groupByN<T, F extends readonly string[], S extends keyof T = never, M extends keyof T & string = never>(\n    executeRecords: () => readonly unknown[],\n    fields: F,\n    upstreams: readonly ReductionUpstream[],\n    via?: ViaPipeline,\n    /** #1341 (grouped half) — see `groupBy` above. */\n    maintenance?: GroupMaintenanceSource,\n  ): GroupedQueryN<T, F, S, M>\n\n  /**\n   * Build a `WindowedQuery<T>` for `Query.window(spec)` (#1349). Same closure\n   * / upstream inputs as `groupBy`, plus the window definition. The Via\n   * pipeline is threaded so `.select()` gets the same money/distinct reducer\n   * rewriting `.aggregate()` gets.\n   *\n   * Throws unless the strategy was built as `withReduce({ window: withWindow() })`\n   * — the second opt-in exists so the window engine is not charged to a\n   * consumer who only aggregates. See `window.ts` § \"Opting in\".\n   */\n  window<T>(\n    executeRecords: () => readonly unknown[],\n    spec: WindowSpec,\n    upstreams: readonly ReductionUpstream[],\n    via?: ViaPipeline,\n  ): WindowedQuery<T>\n\n  /**\n   * Terminal streaming aggregator for `ScanBuilder.aggregate(spec)`.\n   * Takes an async iterable of decrypted records + the spec and\n   * returns the reduced result.\n   */\n  scanAggregate<Spec extends ReduceSpec>(\n    iter: AsyncIterable<unknown>,\n    spec: Spec,\n  ): Promise<ReduceResult<Spec>>\n}\n\nconst NOT_ENABLED = new Error(\n  'Aggregate / groupBy / window is not enabled on this Noydb instance. ' +\n  'Import `{ withReduce }` from \"@noy-db/hub/reduce\" and pass it to ' +\n  '`createNoydb({ reduceStrategy: withReduce() })`.',\n)\n\n/**\n * No-aggregate stub. Every `.aggregate()` / `.groupBy()` / streaming\n * `scan().aggregate()` call throws with a pointer at the subpath. The\n * real `Reduction` / `GroupedQuery` classes are never referenced at\n * runtime, so the bundler drops the ~886 LOC.\n *\n * @internal\n */\nexport const NO_REDUCE: ReduceStrategy = {\n  aggregate() { throw NOT_ENABLED },\n  groupBy() { throw NOT_ENABLED },\n  groupByN() { throw NOT_ENABLED },\n  window() { throw NOT_ENABLED },\n  scanAggregate() { throw NOT_ENABLED },\n}\n"],"mappings":";AAkIA,IAAM,cAAc,IAAI;AAAA,EACtB;AAGF;AAUO,IAAM,YAA4B;AAAA,EACvC,YAAY;AAAE,UAAM;AAAA,EAAY;AAAA,EAChC,UAAU;AAAE,UAAM;AAAA,EAAY;AAAA,EAC9B,WAAW;AAAE,UAAM;AAAA,EAAY;AAAA,EAC/B,SAAS;AAAE,UAAM;AAAA,EAAY;AAAA,EAC7B,gBAAgB;AAAE,UAAM;AAAA,EAAY;AACtC;","names":[]}

package/dist/{chunk-JBDFMYKQ.js → chunk-4AF3TUMP.js}

@@ -1,6 +1,6 @@
 import {
   BrokerNotEnabledError
-} from "./chunk-7O3Y4PPD.js";
+} from "./chunk-244VXYPG.js";
 
 // src/port/with/broker-strategy.ts
 var NO_BROKER = {
@@ -27,4 +27,4 @@ export {
   NO_BROKER,
   buildCredentialBrokerHandle
 };
-//# sourceMappingURL=chunk-JBDFMYKQ.js.map
+//# sourceMappingURL=chunk-4AF3TUMP.js.map

package/dist/{chunk-ZORTV6NH.js → chunk-4I522ERM.js}

@@ -1,13 +1,17 @@
+import {
+  matchDeclaredJoin
+} from "./chunk-MKXXMNJH.js";
 import {
   readPath
-} from "./chunk-NSITFOCJ.js";
+} from "./chunk-HLEK5VAN.js";
 import {
   DanglingReferenceError,
   JoinTooLargeError
-} from "./chunk-7O3Y4PPD.js";
+} from "./chunk-244VXYPG.js";
 
-// src/kernel/query/join.ts
+// src/kernel/query/relate/join.ts
 var DEFAULT_JOIN_MAX_ROWS = 5e4;
+var DEFAULT_CROSS_JOIN_MAX_ROWS = 5e4;
 var JOIN_WARN_FRACTION = 0.8;
 function referencesJoinAlias(clause, aliases) {
   if (clause.type !== "field") return false;
@@ -24,6 +28,14 @@ function splitAroundJoins(clauses, joins) {
   }
   return { preJoin, postJoin };
 }
+function orderReferencesJoinAlias(orderBy, joins) {
+  if (joins.length === 0 || orderBy.length === 0) return false;
+  const aliases = new Set(joins.map((leg) => leg.as));
+  return orderBy.some((entry) => aliases.has(entry.field.split(".")[0]));
+}
+function joinsDropLeftRows(joins) {
+  return joins.some((leg) => leg.inner === true);
+}
 function coerceRefKey(value) {
   if (value === null || value === void 0) return null;
   if (typeof value === "string") return value;
@@ -58,6 +70,11 @@ function applyJoins(rows, joins, context, locale) {
   return result;
 }
 function applyOneJoin(leftRows, leg, context, locale) {
+  const rows = applyOneJoinRaw(leftRows, leg, context, locale);
+  if (leg.inner !== true) return rows;
+  return rows.filter((row) => row !== null && typeof row === "object" && row[leg.as] != null);
+}
+function applyOneJoinRaw(leftRows, leg, context, locale) {
   if (leg.isDictJoin) {
     const dictSource = context.resolveDictSource?.(leg.field);
     if (!dictSource) {
@@ -114,13 +131,37 @@ function applyOneJoin(leftRows, leg, context, locale) {
   }
   const effLocale = locale ?? context.defaultLocale;
   const presentResolve = effLocale !== void 0 && source.presentForJoin !== void 0 ? (right) => right !== null && typeof right === "object" ? source.presentForJoin(right, effLocale) : right : void 0;
+  if (leg.on !== void 0) {
+    return declaredJoin(leftRows, leg, leg.on, rightSnapshot, maxRows, presentResolve);
+  }
   const strategy = leg.strategy ?? (source.lookupById ? "nested" : "hash");
+  const direction = leg.direction ?? "left";
+  if (direction !== "left") {
+    return outerJoinFromRight(leftRows, leg, source, direction, presentResolve);
+  }
   if (strategy === "nested" && source.lookupById) {
     const lookup = (id) => source.lookupById?.(id);
     return nestedLoopJoin(leftRows, leg, lookup, presentResolve);
   }
   return hashJoin(leftRows, leg, rightSnapshot, presentResolve);
 }
+function declaredJoin(leftRows, leg, on, rightSnapshot, maxRows, presentResolve) {
+  const matches = matchDeclaredJoin(leftRows, on, rightSnapshot, maxRows, (produced) => {
+    throw new JoinTooLargeError({
+      leftRows: leftRows.length,
+      rightRows: rightSnapshot.length,
+      maxRows,
+      side: "output",
+      message: `.joinOn("${leg.target}") produced more than ${maxRows} rows (${produced} and counting) from ${leftRows.length} left x ${rightSnapshot.length} right. A declared \`on\` is many-to-many, so the per-side ceilings do not bound the result. Narrow the predicate, filter the left side with where()/limit() before joining, or raise the ceiling via { maxRows }.`
+    });
+  });
+  const out = [];
+  for (const { left, right } of matches) {
+    const dressed = presentResolve && right !== void 0 ? presentResolve(right) : right;
+    out.push(attachJoin(left, leg, dressed, void 0));
+  }
+  return out;
+}
 function nestedLoopJoin(leftRows, leg, lookupById, presentResolve) {
   const out = [];
   for (const left of leftRows) {
@@ -151,6 +192,44 @@ function hashJoin(leftRows, leg, rightSnapshot, presentResolve) {
   }
   return out;
 }
+function reverseIndex(leftRows, field) {
+  return bucketByRefKey(leftRows, (left) => readPath(left, field));
+}
+function bucketByRefKey(items, readKey) {
+  const buckets = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const key = coerceRefKey(readKey(item));
+    if (key === null) continue;
+    const bucket = buckets.get(key);
+    if (bucket) bucket.push(item);
+    else buckets.set(key, [item]);
+  }
+  return buckets;
+}
+function outerJoinFromRight(leftRows, leg, source, direction, presentResolve) {
+  const byRight = reverseIndex(leftRows, leg.field);
+  const matchedLeft = /* @__PURE__ */ new Set();
+  const out = [];
+  const entries = source.snapshotEntries?.() ?? source.snapshot().map((record) => ({ id: coerceRefKey(readPath(record, "id")), record }));
+  for (const { id: rid, record: right } of entries) {
+    const dressed = presentResolve ? presentResolve(right) : right;
+    const bucket = rid === null ? void 0 : byRight.get(rid);
+    if (bucket === void 0 || bucket.length === 0) {
+      out.push({ [leg.as]: dressed });
+      continue;
+    }
+    for (const left of bucket) {
+      matchedLeft.add(left);
+      out.push(attachJoin(left, leg, dressed, readPath(left, leg.field)));
+    }
+  }
+  for (const left of leftRows) {
+    if (matchedLeft.has(left)) continue;
+    const row = attachJoin(left, leg, void 0, readPath(left, leg.field));
+    if (direction === "full") out.push(row);
+  }
+  return out;
+}
 function attachJoin(left, leg, right, rawId) {
   if (left === null || typeof left !== "object") {
     return left;
@@ -182,8 +261,13 @@ function resetJoinWarnings() {
 
 export {
   DEFAULT_JOIN_MAX_ROWS,
+  DEFAULT_CROSS_JOIN_MAX_ROWS,
   splitAroundJoins,
+  orderReferencesJoinAlias,
+  joinsDropLeftRows,
+  coerceRefKey,
   applyJoins,
+  bucketByRefKey,
   resetJoinWarnings
 };
-//# sourceMappingURL=chunk-ZORTV6NH.js.map
+//# sourceMappingURL=chunk-4I522ERM.js.map

package/dist/chunk-4I522ERM.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/kernel/query/relate/join.ts"],"sourcesContent":["/**\n * Query DSL `.join()` — eager, single-FK, intra-vault joins.\n *\n * resolves a ref()-declared foreign key into an attached\n * right-side record under an alias, using one of two planner paths\n * selected automatically:\n *\n *   - **nested-loop** — right-side source exposes `lookupById`, so\n *     each left row costs O(1). This is the common path for joins\n *     against a Collection, which backs `lookupById` with a Map\n *     lookup.\n *   - **hash** — right-side has only `snapshot()`. Build a\n *     `Map<id, record>` once, probe per left row. Same asymptotic\n *     cost for our collections, but the path exists as a fallback\n *     for custom QuerySource implementations and as an explicit\n *     test-only override via `{ strategy: 'hash' }`.\n *\n * Scope:\n *\n *   - Equi-joins on declared `ref()` fields only. Joins on\n *     undeclared fields throw at plan time with an actionable error\n *     naming the field and collection.\n *   - Same-vault only. Cross-vault correlation goes\n *     through `queryAcross`; this is an architectural\n *     invariant, not a limitation we plan to lift.\n *   - Hard row ceiling via `JoinTooLargeError` — default 50k per\n *     side, override via `{ maxRows }`. Warns at 80% of the ceiling\n *     on the existing warn channel.\n *   - Three ref-mode behaviors on dangling refs:\n *     strict → `DanglingReferenceError`,\n *     warn → attach `null` with a one-shot warning,\n *     cascade → attach `null` silently (cascade is a delete-time\n *     mode; any dangling refs still present at read time are\n *     mid-flight cascades or orphans from earlier, not a DSL error).\n *\n * Partition-awareness seam:\n *\n * Every `JoinLeg` carries a `partitionScope` field that is always `'all'`.\n * The executor never reads it. See {@link JoinLeg.partitionScope} for the\n * two constraints (#1342) that decide how it may ever be populated — one of\n * them silently invalidates stored materialized views.\n *\n * Joins stay OUT of the ledger: reads don't touch `_ledger/`,\n * including joined reads.\n */\n\nimport type { RefDescriptor, RefMode } from '../../refs.js'\nimport type { Clause } from '../predicate.js'\nimport type { ViaPipeline } from '../../via/pipeline.js'\nimport { readPath } from '../predicate.js'\nimport { matchDeclaredJoin, type JoinOnPlan } from './join-on.js'\nimport { JoinTooLargeError, DanglingReferenceError } from '../../errors.js'\n\n/** Planner strategy for a single join leg. Auto-selected unless overridden. */\nexport type JoinStrategy = 'hash' | 'nested'\n\n/**\n * Which side of a join leg is preserved (#1289).\n *\n *   - `'left'`  — every left row survives, `null` under the alias when the\n *     FK resolves to nothing. This is what `.join()` has always done, and it\n *     is the default for a leg that names no direction.\n *   - `'right'` — every RIGHT record survives, including one nothing points\n *     at; a left row whose FK matches nothing is dropped.\n *   - `'full'`  — the union of the two.\n *\n * `'right'` and `'full'` are the only two that need the reverse index — see\n * {@link outerJoinFromRight}. A forward leg is driven by the left row's FK\n * and never has to ask \"did anything point at this\".\n */\nexport type JoinDirection = 'left' | 'right' | 'full'\n\n/** Default per-side row ceiling before `.join()` throws `JoinTooLargeError`. */\nexport const DEFAULT_JOIN_MAX_ROWS = 50_000\n\n/**\n * Default row ceiling for cross-join expansion. Matches JoinTooLargeError's ceiling.\n *\n * ⭐ #1458 — moved here from `kernel/query/builder.ts`. Find carries no\n * cross-join concept, and a constant is the cheapest thing to leave behind by\n * accident: it would have kept `builder.ts` as the const's home while every\n * reader of it lived in `relate/`.\n */\nexport const DEFAULT_CROSS_JOIN_MAX_ROWS = 50_000\n\n/**\n * Fraction of the row ceiling at which a one-shot warning is emitted.\n * At 80% we warn; at 100% we throw. The warn gives consumers a\n * heads-up before the hard error so they can raise the ceiling or\n * filter further without first hitting a broken query.\n */\nconst JOIN_WARN_FRACTION = 0.8\n\n/**\n * Internal representation of a single join leg in the query plan.\n *\n * This is the primary place the partition seam is honored: every leg carries\n * a `partitionScope` field that is always `'all'` and is never read by the\n * executor. See {@link JoinLeg.partitionScope}.\n */\nexport interface JoinLeg {\n  /** Field on the left-side record holding the foreign key value. */\n  readonly field: string\n  /** Alias key under which the joined right-side record attaches. */\n  readonly as: string\n  /** Target collection name, resolved from the `ref()` declaration. */\n  readonly target: string\n  /** Ref mode controlling behavior on dangling refs at read time. */\n  readonly mode: RefMode\n  /** Manual planner strategy override. `undefined` → auto-select. */\n  readonly strategy: JoinStrategy | undefined\n  /** Per-side row ceiling override. `undefined` → DEFAULT_JOIN_MAX_ROWS. */\n  readonly maxRows: number | undefined\n  /**\n   * Partition scope for future partition-aware joins. Always `'all'` today —\n   * the executor never reads this field. Do not remove even though it looks\n   * unused: it is a plan-shape seam.\n   *\n   * ⛔ TWO CONSTRAINTS BEFORE POPULATING THIS (#1342):\n   *\n   * 1. **It is a `queryHash` input on a HAND-COMPOSED path only — NOT for a\n   *    registered materialized view.** ⚠️ This paragraph asserted the\n   *    opposite until 2026-09-04; the correction is the measurement.\n   *    `MaterializedViewRegistry` feeds `computeQueryHash` from\n   *    `summarizeQueryPlan()` (`materialized-views/registry.ts:201,243`),\n   *    and that summary has never emitted `partitionScope`. `serializePlan()`\n   *    *does* emit `plan.joins` verbatim, and `canonicalizeQueryPlan` is\n   *    exported, so a consumer composing\n   *    `computeQueryHash(name, deps, canonicalizeQueryPlan(serializePlan(q)))`\n   *    by hand does carry the field in their hash. **That composition, and\n   *    only that one, is what this constraint binds** — it is also the\n   *    composition `__tests__/query-partition-scope.test.ts` builds, which is\n   *    why the file read as evidence for the stronger claim.\n   *    ⭐ So populating this field does NOT invalidate registered MVs. The\n   *    reason to leave it alone is smaller and still sufficient: it is a\n   *    DERIVED value — storing it buys nothing, and it is the one leg key\n   *    emitted UNCONDITIONALLY rather than omitted-at-default, so any later\n   *    move to summarise it (see #1389's rule) would shift every joined MV's\n   *    hash at once, for zero gain. Derive the scope in the EXECUTOR from\n   *    clauses the plan already carries. Pinned by\n   *    `__tests__/query-partition-scope.test.ts`, which now pins BOTH paths.\n   *\n   * 2. **The seam-change route was RULED OUT, and the pruning shipped\n   *    anyway** — ADR 0007, \"partitioning is collection-shaped\". Pruning only\n   *    pays on the `scan()` path (`query()` runs over an in-memory,\n   *    already-decrypted cache where `candidateRecords()`'s hash / sorted /\n   *    compound dispatch (#1344, #1345) narrows better than a partition ever\n   *    could). Buying it by teaching `NoydbStore.listPage` a filter would\n   *    have meant lifting the partition key out of the ciphertext into a\n   *    storage key or cleartext metadata — a permanent per-record\n   *    classification handed to the backend, and a change to the published\n   *    `@noy-db/hub/to` contract across every `to-*` adapter. **Ruled no.**\n   *    ⭐ The pruning was bought instead with information the store already\n   *    has: `listPage(vault, **collection**, …)` names the collection in\n   *    cleartext, so a partition modelled as its own collection is never\n   *    fetched because it is never asked for.\n   *\n   * ⭐ **THE SCOPE IS NOW DERIVED, IN THE EXECUTOR, AND THIS FIELD IS STILL\n   * DORMANT.** `kernel/query/relate/partition.ts`'s `resolvePartitionScope()` is the\n   * one decision function — `with-store/partitioned/` and `explain()` both\n   * call it — and it takes the plan's top-level clause list, never a stored\n   * leg. It is sound in one direction only: narrow ONLY on a whitelist of\n   * provable shapes (`==` / `in` on the declared key at the top level of the\n   * AND-ed clause list), and fall back to `'all'` for everything else —\n   * `or` groups, negations, callback clauses, and any Via-covered clause\n   * (its operand is in STORED form, not partition-key space, which is why\n   * `candidateRecords` refuses the index for it too). A partition wrongly\n   * excluded is silently missing data.\n   */\n  readonly partitionScope: 'all' | readonly string[]\n  /**\n   * Which side is preserved (#1289). `undefined` reads as `'left'` — the\n   * pre-#1289 behaviour — so every plan built before this field existed, and\n   * every serialized plan that omits it, keeps its meaning exactly.\n   */\n  readonly direction?: JoinDirection\n  /**\n   * INNER join (#1361) — drop every left row whose alias resolves to nothing,\n   * instead of attaching `null` under it.\n   *\n   * Only `.join()` sets it (a right/full leg already drops on its own side),\n   * and only when the caller passes `{ mode: 'inner' }`. Omitted rather than\n   * written as `false` for the same reason `direction` is: a plan built\n   * without it must serialize byte-identically to a pre-#1361 one, or every\n   * stored `queryHash` moves.\n   */\n  readonly inner?: true\n  /**\n   * A DECLARED, deterministic join predicate (#1339) — composite equality or\n   * a range — instead of the `ref()`-declared FK the rest of this file\n   * resolves. Set only by `.joinOn()`, always through\n   * {@link normalizeJoinOn}, and OMITTED on every other leg: a plan built by\n   * `.join()` must serialize byte-identically to a pre-#1339 one, or every\n   * stored `queryHash` moves (the same discipline `direction` and `inner`\n   * follow above).\n   *\n   * ⭐ This is the field that separates `.joinOn()` from `.crossJoin({ on })`.\n   * It is plain JSON, so it survives `serializePlan()` and\n   * `summarizeQueryPlan()` and a materialized view can therefore DEPEND on\n   * it. A closure cannot. See `join-on.ts`.\n   */\n  readonly on?: JoinOnPlan\n  /**\n   * When `true`, this is a dictionary join. The executor\n   * resolves the left-field value against the dict snapshot and\n   * attaches `{ ...labels, key }` rather than a right-side record.\n   * `target` holds the dictionary name (not a collection name).\n   */\n  readonly isDictJoin?: true\n}\n\n/**\n * Minimal shape of a joinable right-side record source.\n *\n * Collections implement this structurally via their `QuerySource`;\n * sources without `lookupById` force the hash-join fallback. Kept as\n * a thin interface so tests can wire up plain-object sources without\n * pulling in the full Collection class.\n *\n * The optional `subscribe` is used by `Query.live()` to merge\n * right-side change streams into the live re-run trigger. Sources\n * that omit `subscribe` still work for live joins — they just\n * don't drive re-fires when their right side mutates. Collection\n * implements `subscribe` by hooking into the existing per-\n * vault event emitter.\n */\nexport interface JoinableSource {\n  snapshot(): readonly unknown[]\n  lookupById?(id: string): unknown\n  /**\n   * Default locale a label-resolving query falls back to when the query\n   * itself is locale-less. Set by a `staticDict()`-backed source from its\n   * `displayLocale` so `{ by: 'label' }` resolves under a locale-less read.\n   * Plain `_dict_*`-backed sources omit it.\n   */\n  readonly displayLocale?: string\n  /**\n   * Sync present-for-join dressing (#626 retirement, #650 Task 6) — when\n   * present and the query carries a locale, each joined right-side record\n   * is passed through this hook (built by the right-side `Collection` from\n   * its own i18n-text + lookup-label bindings) BEFORE it is attached under\n   * the leg's alias — so a joined `i18nText` field resolves to a string\n   * (not a raw `{ locale }` map) and a joined lookup field gains its\n   * `<field>Label`. Locale-less queries leave joined fields raw\n   * (consistent with a locale-less read). Replaces the old `i18nFields`\n   * data field — the join executor no longer resolves i18n locale itself,\n   * it just calls this hook.\n   */\n  readonly presentForJoin?: (record: unknown, locale: string) => unknown\n  /**\n   * The id-paired view of {@link snapshot} (#1289).\n   *\n   * ⚠️ A `Collection` snapshot record does NOT carry its own id — the id is\n   * the cache key, not a field. The forward join never noticed, because it\n   * reads the id off the LEFT row's FK and calls `lookupById`. A right/full\n   * outer join has to ask each RIGHT record \"what is your id, and did\n   * anything point at you\", and there is no field to read it from.\n   *\n   * Optional so a plain-object test source stays valid; `outerJoinFromRight`\n   * falls back to an `id` FIELD on the record, which is what such sources\n   * carry. A real Collection supplies this and the fallback never runs.\n   */\n  snapshotEntries?(): readonly { readonly id: string; readonly record: unknown }[]\n  /**\n   * Via RESULT decode for this source's own records (#1289) — the same\n   * `via.decodeResults` a top-level `toArray()` applies (money's stored\n   * scaled-int → canonical decimal, etc.).\n   *\n   * It exists because Via dressing keys by BARE FIELD NAME: the moment a\n   * record moves under an alias (`{ client: { amount } }`, or both sides of\n   * `crossJoinWith`) the top-level decode cannot see it, and the row silently\n   * serves raw money. Distinct from `presentForJoin`, which is the LOCALE\n   * half (i18n text + lookup labels) and only runs for a locale-carrying\n   * query — this half is locale-free and always applies.\n   */\n  readonly decodeResults?: (record: unknown) => unknown\n  /**\n   * This source's own compiled Via pipeline (#1337 / #1338).\n   *\n   * The two halves above (`presentForJoin`, `decodeResults`) dress a record\n   * that is ON ITS WAY OUT. Ordering, grouping and reduction happen while it\n   * is still under an alias mid-plan, and they need the pipeline itself:\n   * `compareForOrder` to sort an aliased money field by MAGNITUDE rather than\n   * lexically over its stored scaled integer, and `wrapReducers` to rewrite\n   * `sum('client.credit')` into the exact-BigInt money reducer (which also\n   * applies the RIGHT collection's `queryable: 'none'` posture gate — the\n   * gate whose silent absence is why joined aggregation was refused).\n   *\n   * A THUNK, not a property: `_applyMoneyFields` can rebuild a collection's\n   * pipeline after this source object has been handed out, and a copied\n   * reference would go quietly stale — the same discipline `decodeResults`\n   * above already follows.\n   *\n   * Optional: a plain-object test source declares none, and every consumer\n   * treats absence as \"no binding covers anything here\".\n   */\n  readonly via?: () => ViaPipeline | undefined\n  /**\n   * Subscribe to mutations on this source. The callback fires\n   * AFTER the underlying record set has been updated. Returns an\n   * unsubscribe function. Optional — sources without this method\n   * cannot trigger live-join re-fires from their side.\n   */\n  subscribe?(cb: () => void): () => void\n}\n\n/**\n * Join resolution context attached to a `Query` when it's constructed\n * from a `Collection`. Holds everything the `.join()` method needs to\n * translate a field name into a target collection + ref mode, and\n * everything the executor needs to read the right side.\n *\n * Kept as a structural interface so `Vault` can implement it\n * without `Query` needing to import `Vault` (circular-import\n * avoid). The Collection wires this up in its `query()` method using\n * the `joinResolver` back-reference the Vault passes in.\n */\nexport interface JoinContext {\n  /** Name of the left-side (owning) collection. */\n  readonly leftCollection: string\n  /**\n   * The owning collection's default locale. Used to resolve joined\n   * i18n fields at the `join` layer when a terminal call doesn't pass an\n   * explicit locale — so `openVault({ locale })` flows to joins like it does\n   * to `get`/`list`. A per-call `toArray({ locale })` overrides it.\n   */\n  readonly defaultLocale?: string\n  /** Look up a `RefDescriptor` by field name on the left collection. */\n  resolveRef(field: string): RefDescriptor | null\n  /** Resolve a right-side source by target collection name. */\n  resolveSource(collectionName: string): JoinableSource | null\n  /**\n   * Resolve a dictKey join source. Returns a `JoinableSource`\n   * whose snapshot exposes `{ key, ...labels }` records, keyed by the\n   * stable dictionary key. `null` when the field is not a dictKey.\n   *\n   * The source is built from the compartment's in-memory dictionary\n   * snapshot — same data as `DictionaryHandle.list()`, O(1) per lookup.\n   */\n  resolveDictSource?(field: string): JoinableSource | null\n}\n\n/**\n * Does this clause address a field that only exists once join legs are\n * attached — i.e. is its path rooted at a join alias?\n *\n * Only `FieldClause` is inspectable. A `FilterClause` carries an opaque\n * function and a `WherePredicateClause` a named one, so neither can be\n * classified; both stay on the pre-join side, which is where they have\n * always run. See `splitAroundJoins`.\n */\nfunction referencesJoinAlias(clause: Clause, aliases: ReadonlySet<string>): boolean {\n  if (clause.type !== 'field') return false\n  // `where('client.name', …)` addresses the alias; so does the anti-join\n  // form `where('client', '==', null)`, where the path IS the alias.\n  return aliases.has(clause.field.split('.')[0]!)\n}\n\n/**\n * Split a plan's clauses into those evaluable before the join legs run and\n * those that need the joined shape (#1030).\n *\n * Join legs attach after `where` so the left set can be narrowed (and\n * index-driven) first. That is the right default, but it silently broke any\n * predicate addressing a joined alias: the field did not exist yet, so\n * `readPath` returned `undefined`, nothing matched, and the query returned an\n * empty result with no error.\n *\n * The split is deliberately narrow. When no clause addresses an alias — every\n * query written against the previous behaviour — `postJoin` is empty and the\n * caller takes its original path unchanged. The reordered pipeline therefore\n * only ever runs for queries that match nothing today.\n *\n * KNOWN RESIDUAL: `.filter(r => r.client?.name === 'Ann')` cannot be\n * classified (the predicate is a closure), so it still runs pre-join and still\n * sees no alias. Prefer `.where()` for anything addressing a joined field.\n *\n * Shared by the eager `Query` and the streaming `ScanBuilder` so the two\n * cannot drift on which side a clause belongs to.\n */\nexport function splitAroundJoins(\n  clauses: readonly Clause[],\n  joins: readonly JoinLeg[],\n): { readonly preJoin: readonly Clause[]; readonly postJoin: readonly Clause[] } {\n  if (joins.length === 0 || clauses.length === 0) return { preJoin: clauses, postJoin: [] }\n  const aliases = new Set(joins.map(leg => leg.as))\n  const preJoin: Clause[] = []\n  const postJoin: Clause[] = []\n  for (const clause of clauses) {\n    ;(referencesJoinAlias(clause, aliases) ? postJoin : preJoin).push(clause)\n  }\n  return { preJoin, postJoin }\n}\n\n/**\n * Does any `orderBy` entry address a field that only exists once the legs are\n * attached (#1337)?\n *\n * The ordering half of {@link splitAroundJoins}, kept beside it because the\n * two answer the same question about different parts of the plan, and because\n * `Query.toArray()` and `Query.explain()` must not drift on the answer — one\n * decides when the sort runs, the other reports it.\n *\n * ⚠️ Only `plan.joins` legs count. A `crossJoin` alias lives in the CLAUSE\n * list and its expansion already runs before ordering, so an ordering over\n * one has never needed moving.\n */\nexport function orderReferencesJoinAlias(\n  orderBy: readonly { readonly field: string }[],\n  joins: readonly JoinLeg[],\n): boolean {\n  if (joins.length === 0 || orderBy.length === 0) return false\n  const aliases = new Set(joins.map(leg => leg.as))\n  return orderBy.some(entry => aliases.has(entry.field.split('.')[0]!))\n}\n\n/**\n * Does any leg drop left rows (#1361)?\n *\n * The entry condition for every terminal that must run the legs even though\n * nothing addresses an alias: an inner leg is no longer projection-only, so\n * `count()`, `exists()` and the ordering placement in `toArray()` all have to\n * ask. Kept beside {@link splitAroundJoins} and {@link orderReferencesJoinAlias}\n * because the three answer the same family of question, and because\n * `Query.toArray()` and `Query.explain()` must not drift on the answer.\n */\nexport function joinsDropLeftRows(joins: readonly JoinLeg[]): boolean {\n  return joins.some(leg => leg.inner === true)\n}\n\n/**\n * Coerce an unknown FK value into a lookup key string.\n *\n * Legitimate ref values are strings or numbers — the same narrowing\n * the write-time `enforceRefsOnPut` path applies. Anything else\n * (objects, arrays, booleans, null, undefined) is treated as \"no\n * ref\" and returns `null`, so the join attaches `null` instead of\n * running `String({})` and producing `'[object Object]'` as a\n * bucket key. This matches the lint rule guidance and keeps\n * bizarre FK values from producing silently-wrong lookups.\n */\nexport function coerceRefKey(value: unknown): string | null {\n  if (value === null || value === undefined) return null\n  if (typeof value === 'string') return value\n  if (typeof value === 'number' || typeof value === 'bigint') return String(value)\n  return null\n}\n\n/**\n * Warn-channel deduplication for dangling-ref `'warn'` mode. Keyed\n * by `field → target:refId` so the same dangling ref only produces\n * one warning even across many rows or repeated queries.\n */\nconst warnedDanglingKeys = new Set<string>()\nfunction warnOnceDangling(field: string, target: string, refId: string): void {\n  const key = `${field}→${target}:${refId}`\n  if (warnedDanglingKeys.has(key)) return\n  warnedDanglingKeys.add(key)\n  console.warn(\n    `[noy-db] .join() encountered dangling ref in 'warn' mode: ` +\n      `field \"${field}\" → \"${target}:${refId}\" not found. Attaching null.`,\n  )\n}\n\n/**\n * Track row-ceiling warnings to fire only once per (target, side).\n * Prevents per-query spam when a consumer is running the same query\n * repeatedly (e.g. in a reactive loop).\n */\nconst warnedCeilingKeys = new Set<string>()\nfunction warnCeilingApproaching(\n  target: string,\n  side: 'left' | 'right',\n  rows: number,\n  maxRows: number,\n): void {\n  const key = `${target}:${side}`\n  if (warnedCeilingKeys.has(key)) return\n  warnedCeilingKeys.add(key)\n  const pct = Math.round((rows / maxRows) * 100)\n  console.warn(\n    `[noy-db] .join() ${side} side is at ${pct}% of the ${maxRows}-row ` +\n      `ceiling for target \"${target}\" (${rows} rows). Streaming joins over ` +\n      `scan() are not yet supported for collections that need to exceed this.`,\n  )\n}\n\n/**\n * Apply every join leg in the plan against a base set of left-side\n * rows. Called by the query executor after `where` / `orderBy` /\n * `offset` / `limit` have narrowed the left set.\n *\n * Each leg attaches a `leg.as` field to every row. Returns a new\n * array of plain objects — the original left rows are not mutated\n * (structural sharing is fine for the inner fields, but the\n * top-level object is a fresh clone so consumers can further mutate\n * safely).\n *\n * **Ordering:** joins run AFTER orderBy / limit / offset by DEFAULT, so\n * \"top 10 invoices with client\" sorts and paginates the left side first\n * (index-driven) and joins only the page. Two things flip that, and both\n * are decided by the plan, never by a flag: a `where` addressing an alias\n * (#1030, {@link splitAroundJoins}) and an `orderBy` addressing one (#1337,\n * {@link orderReferencesJoinAlias}). Either one moves the sort and the page\n * to AFTER the legs, because neither can be evaluated against a row where\n * the alias does not exist yet. ⚠️ That query necessarily loses the\n * index-driven ordering fast path — the cost of sorting on a field the\n * index does not hold. `Query.explain()` names which placement a plan gets.\n *\n * An INNER leg (#1361) moves only the PAGE, not the sort: the drop removes\n * rows, so `limit` must observe it, but the ordering is on a left-side field\n * that the drop cannot reorder. `toArray()` therefore sorts pre-join, joins,\n * and slices after — and `explain()` reports `pre-join` on the sort and\n * `post-join` on the page rather than one word for both.\n *\n * **Multi-FK chaining:** each leg's `maxRows` is enforced\n * against the current left-row count independently. Because\n * joins are equi-joins on the target's primary key (one-to-one or\n * one-to-null), the left row count is constant across legs — no\n * cartesian blowup. The per-leg left-side check is still necessary\n * so that a later leg with a tighter ceiling correctly fires on a\n * query like `.join('a', { maxRows: 100_000 }).join('b', { maxRows: 50 })`,\n * which should throw on the second leg if the left set exceeds 50.\n */\nexport function applyJoins(\n  rows: readonly unknown[],\n  joins: readonly JoinLeg[],\n  context: JoinContext,\n  locale?: string,\n): unknown[] {\n  if (joins.length === 0) return [...rows]\n\n  let result: unknown[] = [...rows]\n  for (const leg of joins) {\n    result = applyOneJoin(result, leg, context, locale)\n  }\n  return result\n}\n\n/**\n * One leg, plus the #1361 inner-join drop.\n *\n * The drop is applied to the leg's OUTPUT rather than threaded through the\n * three producers (nested-loop, hash, dict) — an unmatched row is `null` under\n * the alias in all three by construction, and `attachJoin` has already run, so\n * a strict-mode `DanglingReferenceError` still fires for a dangling ref that\n * `inner` would otherwise hide.\n */\nfunction applyOneJoin(\n  leftRows: readonly unknown[],\n  leg: JoinLeg,\n  context: JoinContext,\n  locale?: string,\n): unknown[] {\n  const rows = applyOneJoinRaw(leftRows, leg, context, locale)\n  if (leg.inner !== true) return rows\n  return rows.filter(row => row !== null && typeof row === 'object' && (row as Record<string, unknown>)[leg.as] != null)\n}\n\nfunction applyOneJoinRaw(\n  leftRows: readonly unknown[],\n  leg: JoinLeg,\n  context: JoinContext,\n  locale?: string,\n): unknown[] {\n  // Dict join path — resolve left-field value against the\n  // dictionary snapshot and attach { key, ...labels } under leg.as.\n  if (leg.isDictJoin) {\n    const dictSource = context.resolveDictSource?.(leg.field)\n    if (!dictSource) {\n      throw new Error(\n        `.join() field \"${leg.field}\" on \"${context.leftCollection}\" is declared as a ` +\n          `dictKey join but the dict source could not be resolved. ` +\n          `Ensure the dictionary has at least one entry.`,\n      )\n    }\n    const out: unknown[] = []\n    const snapshot = dictSource.snapshot()\n    const dictMap = new Map<string, unknown>()\n    for (const entry of snapshot) {\n      const k = readPath(entry, 'key')\n      if (typeof k === 'string') dictMap.set(k, entry)\n    }\n    for (const left of leftRows) {\n      const rawId = readPath(left, leg.field)\n      const key = coerceRefKey(rawId)\n      const dictEntry = key === null ? undefined : dictMap.get(key)\n      out.push({ ...(left as Record<string, unknown>), [leg.as]: dictEntry ?? null })\n    }\n    return out\n  }\n\n  const source = context.resolveSource(leg.target)\n  if (!source) {\n    throw new Error(\n      `.join() cannot resolve target collection \"${leg.target}\" ` +\n        `(referenced from field \"${leg.field}\" on \"${context.leftCollection}\"). ` +\n        `Make sure the target collection has been opened via vault.collection() ` +\n        `at least once before running the query.`,\n    )\n  }\n\n  const maxRows = leg.maxRows ?? DEFAULT_JOIN_MAX_ROWS\n\n  // Per-leg left-side ceiling check. In a\n  // multi-FK chain, each leg's `maxRows` is enforced independently\n  // against the current left-row count, so\n  // `.join('a', { maxRows: 100_000 }).join('b', { maxRows: 50 })`\n  // correctly throws on the second leg if the left set exceeds 50.\n  if (leftRows.length > maxRows) {\n    throw new JoinTooLargeError({\n      leftRows: leftRows.length,\n      rightRows: -1,\n      maxRows,\n      side: 'left',\n      message:\n        `.join() left side has ${leftRows.length} rows, exceeding the ${maxRows}-row ` +\n        `ceiling for target \"${leg.target}\". Filter the left side further with ` +\n        `where()/limit() before joining, or raise the ceiling via { maxRows }. ` +\n        `Streaming joins over scan() are not yet supported.`,\n    })\n  }\n  if (leftRows.length > maxRows * JOIN_WARN_FRACTION) {\n    warnCeilingApproaching(leg.target, 'left', leftRows.length, maxRows)\n  }\n\n  const rightSnapshot = source.snapshot()\n  if (rightSnapshot.length > maxRows) {\n    throw new JoinTooLargeError({\n      leftRows: leftRows.length,\n      rightRows: rightSnapshot.length,\n      maxRows,\n      side: 'right',\n      message:\n        `.join() right side \"${leg.target}\" has ${rightSnapshot.length} rows, ` +\n        `exceeding the ${maxRows}-row ceiling. Raise the ceiling via { maxRows } ` +\n        `if the data genuinely fits in memory, or track  for streaming joins.`,\n    })\n  }\n  if (rightSnapshot.length > maxRows * JOIN_WARN_FRACTION) {\n    warnCeilingApproaching(leg.target, 'right', rightSnapshot.length, maxRows)\n  }\n\n  // `join`-layer dressing (#650 Task 6, #626 retirement). When the query\n  // carries a locale (per-call or the owning collection's default) and the\n  // right side declares a `presentForJoin` hook, resolve each matched right\n  // record through it before it's attached. Locale-less → leave raw.\n  const effLocale = locale ?? context.defaultLocale\n  const presentResolve: ((right: unknown) => unknown) | undefined =\n    effLocale !== undefined && source.presentForJoin !== undefined\n      ? (right) =>\n          right !== null && typeof right === 'object'\n            ? source.presentForJoin!(right, effLocale)\n            : right\n      : undefined\n\n  // #1339 — a declared `on` replaces the FK lookup entirely: there is no\n  // ref, so neither `lookupById` nor the id-keyed hash means anything. It\n  // runs BEFORE the strategy/direction selection below because it answers\n  // both questions itself (see `join-on.ts` for which strategy serves which\n  // shape, and at what cost).\n  if (leg.on !== undefined) {\n    return declaredJoin(leftRows, leg, leg.on, rightSnapshot, maxRows, presentResolve)\n  }\n\n  // Strategy selection: explicit override wins; otherwise prefer\n  // nested-loop when the source exposes lookupById (O(1) per row),\n  // falling back to hash join when it doesn't.\n  const strategy: JoinStrategy =\n    leg.strategy ?? (source.lookupById ? 'nested' : 'hash')\n\n  // #1289 — a right/full outer join cannot be driven by the left row's FK,\n  // because the rows it must produce are exactly the ones no FK names. It\n  // reverses the index instead: bucket the LEFT rows by their FK value, then\n  // walk the right snapshot asking each record \"did anything point at me\".\n  const direction = leg.direction ?? 'left'\n  if (direction !== 'left') {\n    return outerJoinFromRight(leftRows, leg, source, direction, presentResolve)\n  }\n\n  if (strategy === 'nested' && source.lookupById) {\n    // Bind through an arrow so the `this` context of lookupById\n    // doesn't drift — same pattern as the existing candidateRecords\n    // helper in builder.ts.\n    const lookup = (id: string): unknown => source.lookupById?.(id)\n    return nestedLoopJoin(leftRows, leg, lookup, presentResolve)\n  }\n  return hashJoin(leftRows, leg, rightSnapshot, presentResolve)\n}\n\n/**\n * Execute a declared-`on` leg (#1339).\n *\n * The match set comes from `join-on.ts`; this function is only the part that\n * has to agree with the rest of `.join()` — the alias attachment, the\n * present/decode dressing, and the OUTPUT ceiling.\n *\n * ⚠️ The output ceiling is not redundant with the two side ceilings above. A\n * ref join is one-to-one, so `output === leftRows`; a declared join is\n * many-to-many, so 1,000 × 1,000 rows both comfortably under a 50,000-row\n * side ceiling can produce a million rows. Checking as rows are produced is\n * what makes an unbounded theta join an error rather than a hang.\n */\nfunction declaredJoin(\n  leftRows: readonly unknown[],\n  leg: JoinLeg,\n  on: JoinOnPlan,\n  rightSnapshot: readonly unknown[],\n  maxRows: number,\n  presentResolve?: (right: unknown) => unknown,\n): unknown[] {\n  const matches = matchDeclaredJoin(leftRows, on, rightSnapshot, maxRows, produced => {\n    throw new JoinTooLargeError({\n      leftRows: leftRows.length,\n      rightRows: rightSnapshot.length,\n      maxRows,\n      side: 'output',\n      message:\n        `.joinOn(\"${leg.target}\") produced more than ${maxRows} rows (${produced} and counting) from ` +\n        `${leftRows.length} left x ${rightSnapshot.length} right. A declared \\`on\\` is many-to-many, so ` +\n        `the per-side ceilings do not bound the result. Narrow the predicate, filter the left side ` +\n        `with where()/limit() before joining, or raise the ceiling via { maxRows }.`,\n    })\n  })\n  const out: unknown[] = []\n  for (const { left, right } of matches) {\n    const dressed = presentResolve && right !== undefined ? presentResolve(right) : right\n    // `rawId` is `undefined` on purpose: a declared join has no ref, so\n    // \"matched nothing\" is never a DANGLING ref — `attachJoin` reads a null\n    // key as \"no reference at all\" and attaches null without consulting the\n    // ref mode. An unmatched row is data, not corruption.\n    out.push(attachJoin(left, leg, dressed, undefined))\n  }\n  return out\n}\n\nfunction nestedLoopJoin(\n  leftRows: readonly unknown[],\n  leg: JoinLeg,\n  lookupById: (id: string) => unknown,\n  presentResolve?: (right: unknown) => unknown,\n): unknown[] {\n  const out: unknown[] = []\n  for (const left of leftRows) {\n    const rawId = readPath(left, leg.field)\n    const key = coerceRefKey(rawId)\n    let right = key === null ? undefined : lookupById(key)\n    if (presentResolve && right !== undefined) right = presentResolve(right)\n    out.push(attachJoin(left, leg, right, rawId))\n  }\n  return out\n}\n\nfunction hashJoin(\n  leftRows: readonly unknown[],\n  leg: JoinLeg,\n  rightSnapshot: readonly unknown[],\n  presentResolve?: (right: unknown) => unknown,\n): unknown[] {\n  // Build the right-side hash once per query execution. We key on\n  // the `id` field because ref() always points to a target's primary\n  // key — non-equi and non-id joins are out of scope for.\n  const rightMap = new Map<string, unknown>()\n  for (const record of rightSnapshot) {\n    const rawId = readPath(record, 'id')\n    const key = coerceRefKey(rawId)\n    if (key !== null) {\n      rightMap.set(key, record)\n    }\n  }\n  const out: unknown[] = []\n  for (const left of leftRows) {\n    const rawId = readPath(left, leg.field)\n    const key = coerceRefKey(rawId)\n    let right = key === null ? undefined : rightMap.get(key)\n    if (presentResolve && right !== undefined) right = presentResolve(right)\n    out.push(attachJoin(left, leg, right, rawId))\n  }\n  return out\n}\n\n/**\n * Bucket the left rows by the FK value they carry, so the right side can be\n * asked \"did anything point at this record\" in O(1).\n *\n * This IS the reverse index #1289 names. It is built per execution and lives\n * only for the length of the join: nothing is persisted, no store is touched,\n * and it costs one pass over the left set that the forward path does not pay.\n * Left rows with a null/uncoercible FK are absent from every bucket — they are\n * \"no reference at all\", never a match.\n */\nfunction reverseIndex(leftRows: readonly unknown[], field: string): Map<string, unknown[]> {\n  return bucketByRefKey(leftRows, left => readPath(left, field))\n}\n\n/**\n * The reverse-FK index, generalised over what sits in the bucket (#1352).\n *\n * `outerJoinFromRight` buckets bare left ROWS by their FK; `traverse()`\n * buckets id-paired ENTRIES, because a child row alone cannot say what its\n * own id is (a Collection snapshot record carries no `id` field — the id is\n * the cache key). Same question — \"who points at this?\" — same coercion\n * rules, so it is deliberately one implementation rather than two that can\n * drift on what counts as a usable FK value.\n *\n * `readKey` extracts the raw FK from an item; `coerceRefKey` then decides\n * whether it is a key at all. An item whose FK is nullish, or is neither a\n * string nor a number, is dropped — \"no reference\", not \"a reference to\n * `[object Object]`\".\n */\nexport function bucketByRefKey<V>(\n  items: readonly V[],\n  readKey: (item: V) => unknown,\n): Map<string, V[]> {\n  const buckets = new Map<string, V[]>()\n  for (const item of items) {\n    const key = coerceRefKey(readKey(item))\n    if (key === null) continue\n    const bucket = buckets.get(key)\n    if (bucket) bucket.push(item)\n    else buckets.set(key, [item])\n  }\n  return buckets\n}\n\n/**\n * Right / full outer join (#1289).\n *\n * Walks the RIGHT snapshot as the driving relation. A right record with a\n * non-empty bucket emits one row per left row in it (identical in shape to\n * what the forward path would have produced); a right record nothing points\n * at emits a LEFT-LESS row — `{ [leg.as]: right }` and nothing else, which is\n * SQL's \"the left columns are NULL\" rendered in an object language.\n *\n * `'full'` then appends the left rows the right side never claimed, in their\n * original order, with `null` under the alias — i.e. exactly the rows the\n * forward left-outer path would emit for them, ref-mode behaviour included.\n * `'right'` drops those rows, but still runs the ref-mode check on them: a\n * strict dangling ref is a data-integrity finding, and hiding it behind a\n * change of join direction would make corruption depend on which method the\n * caller happened to type.\n */\nfunction outerJoinFromRight(\n  leftRows: readonly unknown[],\n  leg: JoinLeg,\n  source: JoinableSource,\n  direction: JoinDirection,\n  presentResolve?: (right: unknown) => unknown,\n): unknown[] {\n  const byRight = reverseIndex(leftRows, leg.field)\n  const matchedLeft = new Set<unknown>()\n  const out: unknown[] = []\n\n  // Prefer the id-paired view: a Collection record has no `id` field, so\n  // reading one off the record would leave every bucket unmatched and turn a\n  // right join into \"every right record is an orphan\" — wrong, and quietly so\n  // in `cascade`/`warn` mode. The field fallback serves plain-object sources.\n  const entries: readonly { id: string | null; record: unknown }[] =\n    source.snapshotEntries?.() ??\n    source.snapshot().map(record => ({ id: coerceRefKey(readPath(record, 'id')), record }))\n\n  for (const { id: rid, record: right } of entries) {\n    const dressed = presentResolve ? presentResolve(right) : right\n    const bucket = rid === null ? undefined : byRight.get(rid)\n    if (bucket === undefined || bucket.length === 0) {\n      // Nothing points at this record — the row that only a right/full outer\n      // join can produce.\n      out.push({ [leg.as]: dressed })\n      continue\n    }\n    for (const left of bucket) {\n      matchedLeft.add(left)\n      out.push(attachJoin(left, leg, dressed, readPath(left, leg.field)))\n    }\n  }\n\n  for (const left of leftRows) {\n    if (matchedLeft.has(left)) continue\n    // Unmatched left row: `attachJoin` with an undefined right applies the\n    // ref mode (strict throws, warn warns once) and attaches null.\n    const row = attachJoin(left, leg, undefined, readPath(left, leg.field))\n    if (direction === 'full') out.push(row)\n  }\n\n  return out\n}\n\n/**\n * Attach the resolved right-side record (or null) to the left row\n * under the alias, applying ref-mode semantics for the dangling\n * case.\n *\n * A left-side record whose FK field is null/undefined is NOT a\n * dangling ref — it's \"no reference at all\", which is always\n * allowed regardless of mode. This matches the write-time\n * `enforceRefsOnPut` behavior: \"Nullish ref values are allowed —\n * treat them as 'no reference'.\"\n *\n * Only non-null FKs pointing at non-existent targets trigger the\n * mode behavior.\n */\nfunction attachJoin(\n  left: unknown,\n  leg: JoinLeg,\n  right: unknown,\n  rawId: unknown,\n): unknown {\n  if (left === null || typeof left !== 'object') {\n    // Pathological input — return as-is. Shouldn't happen in\n    // practice because QuerySource yields objects, but defensive\n    // because plan execution is untyped at this layer.\n    return left\n  }\n  const merged: Record<string, unknown> = { ...(left as Record<string, unknown>) }\n\n  // \"No ref at all\" — null/undefined FK value, or a non-string/non-\n  // number FK that coerceRefKey treated as no-ref. Never throws\n  // regardless of mode; matches the write-time policy that nullish\n  // refs are allowed.\n  const refKey = coerceRefKey(rawId)\n  if (right === undefined) {\n    if (refKey !== null && leg.mode === 'strict') {\n      throw new DanglingReferenceError({\n        field: leg.field,\n        target: leg.target,\n        refId: refKey,\n        message:\n          `.join() strict dangling: record references \"${leg.target}:${refKey}\" ` +\n          `via field \"${leg.field}\", but no such record exists. Use ref() mode 'warn' ` +\n          `or 'cascade' if dangling refs are acceptable, or run ` +\n          `vault.checkIntegrity() to find and fix the orphans.`,\n      })\n    }\n    if (refKey !== null && leg.mode === 'warn') {\n      warnOnceDangling(leg.field, leg.target, refKey)\n    }\n    // For 'cascade' and null refs we attach null silently. Cascade\n    // is a delete-time mode; any dangling refs visible at read time\n    // are either mid-flight or pre-existing orphans, not a DSL error.\n    merged[leg.as] = null\n  } else {\n    merged[leg.as] = right\n  }\n  return merged\n}\n\n/**\n * Test-only: reset the join warning deduplication state between\n * tests. Production code never calls this — the dedup state is\n * intentionally process-scoped so a noisy query doesn't spam the\n * console once per component render.\n */\nexport function resetJoinWarnings(): void {\n  warnedDanglingKeys.clear()\n  warnedCeilingKeys.clear()\n}\n"],"mappings":";;;;;;;;;;;;AAyEO,IAAM,wBAAwB;AAU9B,IAAM,8BAA8B;AAQ3C,IAAM,qBAAqB;AAoQ3B,SAAS,oBAAoB,QAAgB,SAAuC;AAClF,MAAI,OAAO,SAAS,QAAS,QAAO;AAGpC,SAAO,QAAQ,IAAI,OAAO,MAAM,MAAM,GAAG,EAAE,CAAC,CAAE;AAChD;AAwBO,SAAS,iBACd,SACA,OAC+E;AAC/E,MAAI,MAAM,WAAW,KAAK,QAAQ,WAAW,EAAG,QAAO,EAAE,SAAS,SAAS,UAAU,CAAC,EAAE;AACxF,QAAM,UAAU,IAAI,IAAI,MAAM,IAAI,SAAO,IAAI,EAAE,CAAC;AAChD,QAAM,UAAoB,CAAC;AAC3B,QAAM,WAAqB,CAAC;AAC5B,aAAW,UAAU,SAAS;AAC5B;AAAC,KAAC,oBAAoB,QAAQ,OAAO,IAAI,WAAW,SAAS,KAAK,MAAM;AAAA,EAC1E;AACA,SAAO,EAAE,SAAS,SAAS;AAC7B;AAeO,SAAS,yBACd,SACA,OACS;AACT,MAAI,MAAM,WAAW,KAAK,QAAQ,WAAW,EAAG,QAAO;AACvD,QAAM,UAAU,IAAI,IAAI,MAAM,IAAI,SAAO,IAAI,EAAE,CAAC;AAChD,SAAO,QAAQ,KAAK,WAAS,QAAQ,IAAI,MAAM,MAAM,MAAM,GAAG,EAAE,CAAC,CAAE,CAAC;AACtE;AAYO,SAAS,kBAAkB,OAAoC;AACpE,SAAO,MAAM,KAAK,SAAO,IAAI,UAAU,IAAI;AAC7C;AAaO,SAAS,aAAa,OAA+B;AAC1D,MAAI,UAAU,QAAQ,UAAU,OAAW,QAAO;AAClD,MAAI,OAAO,UAAU,SAAU,QAAO;AACtC,MAAI,OAAO,UAAU,YAAY,OAAO,UAAU,SAAU,QAAO,OAAO,KAAK;AAC/E,SAAO;AACT;AAOA,IAAM,qBAAqB,oBAAI,IAAY;AAC3C,SAAS,iBAAiB,OAAe,QAAgB,OAAqB;AAC5E,QAAM,MAAM,GAAG,KAAK,SAAI,MAAM,IAAI,KAAK;AACvC,MAAI,mBAAmB,IAAI,GAAG,EAAG;AACjC,qBAAmB,IAAI,GAAG;AAC1B,UAAQ;AAAA,IACN,oEACY,KAAK,aAAQ,MAAM,IAAI,KAAK;AAAA,EAC1C;AACF;AAOA,IAAM,oBAAoB,oBAAI,IAAY;AAC1C,SAAS,uBACP,QACA,MACA,MACA,SACM;AACN,QAAM,MAAM,GAAG,MAAM,IAAI,IAAI;AAC7B,MAAI,kBAAkB,IAAI,GAAG,EAAG;AAChC,oBAAkB,IAAI,GAAG;AACzB,QAAM,MAAM,KAAK,MAAO,OAAO,UAAW,GAAG;AAC7C,UAAQ;AAAA,IACN,oBAAoB,IAAI,eAAe,GAAG,YAAY,OAAO,4BACpC,MAAM,MAAM,IAAI;AAAA,EAE3C;AACF;AAuCO,SAAS,WACd,MACA,OACA,SACA,QACW;AACX,MAAI,MAAM,WAAW,EAAG,QAAO,CAAC,GAAG,IAAI;AAEvC,MAAI,SAAoB,CAAC,GAAG,IAAI;AAChC,aAAW,OAAO,OAAO;AACvB,aAAS,aAAa,QAAQ,KAAK,SAAS,MAAM;AAAA,EACpD;AACA,SAAO;AACT;AAWA,SAAS,aACP,UACA,KACA,SACA,QACW;AACX,QAAM,OAAO,gBAAgB,UAAU,KAAK,SAAS,MAAM;AAC3D,MAAI,IAAI,UAAU,KAAM,QAAO;AAC/B,SAAO,KAAK,OAAO,SAAO,QAAQ,QAAQ,OAAO,QAAQ,YAAa,IAAgC,IAAI,EAAE,KAAK,IAAI;AACvH;AAEA,SAAS,gBACP,UACA,KACA,SACA,QACW;AAGX,MAAI,IAAI,YAAY;AAClB,UAAM,aAAa,QAAQ,oBAAoB,IAAI,KAAK;AACxD,QAAI,CAAC,YAAY;AACf,YAAM,IAAI;AAAA,QACR,kBAAkB,IAAI,KAAK,SAAS,QAAQ,cAAc;AAAA,MAG5D;AAAA,IACF;AACA,UAAM,MAAiB,CAAC;AACxB,UAAM,WAAW,WAAW,SAAS;AACrC,UAAM,UAAU,oBAAI,IAAqB;AACzC,eAAW,SAAS,UAAU;AAC5B,YAAM,IAAI,SAAS,OAAO,KAAK;AAC/B,UAAI,OAAO,MAAM,SAAU,SAAQ,IAAI,GAAG,KAAK;AAAA,IACjD;AACA,eAAW,QAAQ,UAAU;AAC3B,YAAM,QAAQ,SAAS,MAAM,IAAI,KAAK;AACtC,YAAM,MAAM,aAAa,KAAK;AAC9B,YAAM,YAAY,QAAQ,OAAO,SAAY,QAAQ,IAAI,GAAG;AAC5D,UAAI,KAAK,EAAE,GAAI,MAAkC,CAAC,IAAI,EAAE,GAAG,aAAa,KAAK,CAAC;AAAA,IAChF;AACA,WAAO;AAAA,EACT;AAEA,QAAM,SAAS,QAAQ,cAAc,IAAI,MAAM;AAC/C,MAAI,CAAC,QAAQ;AACX,UAAM,IAAI;AAAA,MACR,6CAA6C,IAAI,MAAM,6BAC1B,IAAI,KAAK,SAAS,QAAQ,cAAc;AAAA,IAGvE;AAAA,EACF;AAEA,QAAM,UAAU,IAAI,WAAW;AAO/B,MAAI,SAAS,SAAS,SAAS;AAC7B,UAAM,IAAI,kBAAkB;AAAA,MAC1B,UAAU,SAAS;AAAA,MACnB,WAAW;AAAA,MACX;AAAA,MACA,MAAM;AAAA,MACN,SACE,yBAAyB,SAAS,MAAM,wBAAwB,OAAO,4BAChD,IAAI,MAAM;AAAA,IAGrC,CAAC;AAAA,EACH;AACA,MAAI,SAAS,SAAS,UAAU,oBAAoB;AAClD,2BAAuB,IAAI,QAAQ,QAAQ,SAAS,QAAQ,OAAO;AAAA,EACrE;AAEA,QAAM,gBAAgB,OAAO,SAAS;AACtC,MAAI,cAAc,SAAS,SAAS;AAClC,UAAM,IAAI,kBAAkB;AAAA,MAC1B,UAAU,SAAS;AAAA,MACnB,WAAW,cAAc;AAAA,MACzB;AAAA,MACA,MAAM;AAAA,MACN,SACE,uBAAuB,IAAI,MAAM,SAAS,cAAc,MAAM,wBAC7C,OAAO;AAAA,IAE5B,CAAC;AAAA,EACH;AACA,MAAI,cAAc,SAAS,UAAU,oBAAoB;AACvD,2BAAuB,IAAI,QAAQ,SAAS,cAAc,QAAQ,OAAO;AAAA,EAC3E;AAMA,QAAM,YAAY,UAAU,QAAQ;AACpC,QAAM,iBACJ,cAAc,UAAa,OAAO,mBAAmB,SACjD,CAAC,UACC,UAAU,QAAQ,OAAO,UAAU,WAC/B,OAAO,eAAgB,OAAO,SAAS,IACvC,QACN;AAON,MAAI,IAAI,OAAO,QAAW;AACxB,WAAO,aAAa,UAAU,KAAK,IAAI,IAAI,eAAe,SAAS,cAAc;AAAA,EACnF;AAKA,QAAM,WACJ,IAAI,aAAa,OAAO,aAAa,WAAW;AAMlD,QAAM,YAAY,IAAI,aAAa;AACnC,MAAI,cAAc,QAAQ;AACxB,WAAO,mBAAmB,UAAU,KAAK,QAAQ,WAAW,cAAc;AAAA,EAC5E;AAEA,MAAI,aAAa,YAAY,OAAO,YAAY;AAI9C,UAAM,SAAS,CAAC,OAAwB,OAAO,aAAa,EAAE;AAC9D,WAAO,eAAe,UAAU,KAAK,QAAQ,cAAc;AAAA,EAC7D;AACA,SAAO,SAAS,UAAU,KAAK,eAAe,cAAc;AAC9D;AAeA,SAAS,aACP,UACA,KACA,IACA,eACA,SACA,gBACW;AACX,QAAM,UAAU,kBAAkB,UAAU,IAAI,eAAe,SAAS,cAAY;AAClF,UAAM,IAAI,kBAAkB;AAAA,MAC1B,UAAU,SAAS;AAAA,MACnB,WAAW,cAAc;AAAA,MACzB;AAAA,MACA,MAAM;AAAA,MACN,SACE,YAAY,IAAI,MAAM,yBAAyB,OAAO,UAAU,QAAQ,uBACrE,SAAS,MAAM,WAAW,cAAc,MAAM;AAAA,IAGrD,CAAC;AAAA,EACH,CAAC;AACD,QAAM,MAAiB,CAAC;AACxB,aAAW,EAAE,MAAM,MAAM,KAAK,SAAS;AACrC,UAAM,UAAU,kBAAkB,UAAU,SAAY,eAAe,KAAK,IAAI;AAKhF,QAAI,KAAK,WAAW,MAAM,KAAK,SAAS,MAAS,CAAC;AAAA,EACpD;AACA,SAAO;AACT;AAEA,SAAS,eACP,UACA,KACA,YACA,gBACW;AACX,QAAM,MAAiB,CAAC;AACxB,aAAW,QAAQ,UAAU;AAC3B,UAAM,QAAQ,SAAS,MAAM,IAAI,KAAK;AACtC,UAAM,MAAM,aAAa,KAAK;AAC9B,QAAI,QAAQ,QAAQ,OAAO,SAAY,WAAW,GAAG;AACrD,QAAI,kBAAkB,UAAU,OAAW,SAAQ,eAAe,KAAK;AACvE,QAAI,KAAK,WAAW,MAAM,KAAK,OAAO,KAAK,CAAC;AAAA,EAC9C;AACA,SAAO;AACT;AAEA,SAAS,SACP,UACA,KACA,eACA,gBACW;AAIX,QAAM,WAAW,oBAAI,IAAqB;AAC1C,aAAW,UAAU,eAAe;AAClC,UAAM,QAAQ,SAAS,QAAQ,IAAI;AACnC,UAAM,MAAM,aAAa,KAAK;AAC9B,QAAI,QAAQ,MAAM;AAChB,eAAS,IAAI,KAAK,MAAM;AAAA,IAC1B;AAAA,EACF;AACA,QAAM,MAAiB,CAAC;AACxB,aAAW,QAAQ,UAAU;AAC3B,UAAM,QAAQ,SAAS,MAAM,IAAI,KAAK;AACtC,UAAM,MAAM,aAAa,KAAK;AAC9B,QAAI,QAAQ,QAAQ,OAAO,SAAY,SAAS,IAAI,GAAG;AACvD,QAAI,kBAAkB,UAAU,OAAW,SAAQ,eAAe,KAAK;AACvE,QAAI,KAAK,WAAW,MAAM,KAAK,OAAO,KAAK,CAAC;AAAA,EAC9C;AACA,SAAO;AACT;AAYA,SAAS,aAAa,UAA8B,OAAuC;AACzF,SAAO,eAAe,UAAU,UAAQ,SAAS,MAAM,KAAK,CAAC;AAC/D;AAiBO,SAAS,eACd,OACA,SACkB;AAClB,QAAM,UAAU,oBAAI,IAAiB;AACrC,aAAW,QAAQ,OAAO;AACxB,UAAM,MAAM,aAAa,QAAQ,IAAI,CAAC;AACtC,QAAI,QAAQ,KAAM;AAClB,UAAM,SAAS,QAAQ,IAAI,GAAG;AAC9B,QAAI,OAAQ,QAAO,KAAK,IAAI;AAAA,QACvB,SAAQ,IAAI,KAAK,CAAC,IAAI,CAAC;AAAA,EAC9B;AACA,SAAO;AACT;AAmBA,SAAS,mBACP,UACA,KACA,QACA,WACA,gBACW;AACX,QAAM,UAAU,aAAa,UAAU,IAAI,KAAK;AAChD,QAAM,cAAc,oBAAI,IAAa;AACrC,QAAM,MAAiB,CAAC;AAMxB,QAAM,UACJ,OAAO,kBAAkB,KACzB,OAAO,SAAS,EAAE,IAAI,aAAW,EAAE,IAAI,aAAa,SAAS,QAAQ,IAAI,CAAC,GAAG,OAAO,EAAE;AAExF,aAAW,EAAE,IAAI,KAAK,QAAQ,MAAM,KAAK,SAAS;AAChD,UAAM,UAAU,iBAAiB,eAAe,KAAK,IAAI;AACzD,UAAM,SAAS,QAAQ,OAAO,SAAY,QAAQ,IAAI,GAAG;AACzD,QAAI,WAAW,UAAa,OAAO,WAAW,GAAG;AAG/C,UAAI,KAAK,EAAE,CAAC,IAAI,EAAE,GAAG,QAAQ,CAAC;AAC9B;AAAA,IACF;AACA,eAAW,QAAQ,QAAQ;AACzB,kBAAY,IAAI,IAAI;AACpB,UAAI,KAAK,WAAW,MAAM,KAAK,SAAS,SAAS,MAAM,IAAI,KAAK,CAAC,CAAC;AAAA,IACpE;AAAA,EACF;AAEA,aAAW,QAAQ,UAAU;AAC3B,QAAI,YAAY,IAAI,IAAI,EAAG;AAG3B,UAAM,MAAM,WAAW,MAAM,KAAK,QAAW,SAAS,MAAM,IAAI,KAAK,CAAC;AACtE,QAAI,cAAc,OAAQ,KAAI,KAAK,GAAG;AAAA,EACxC;AAEA,SAAO;AACT;AAgBA,SAAS,WACP,MACA,KACA,OACA,OACS;AACT,MAAI,SAAS,QAAQ,OAAO,SAAS,UAAU;AAI7C,WAAO;AAAA,EACT;AACA,QAAM,SAAkC,EAAE,GAAI,KAAiC;AAM/E,QAAM,SAAS,aAAa,KAAK;AACjC,MAAI,UAAU,QAAW;AACvB,QAAI,WAAW,QAAQ,IAAI,SAAS,UAAU;AAC5C,YAAM,IAAI,uBAAuB;AAAA,QAC/B,OAAO,IAAI;AAAA,QACX,QAAQ,IAAI;AAAA,QACZ,OAAO;AAAA,QACP,SACE,+CAA+C,IAAI,MAAM,IAAI,MAAM,gBACrD,IAAI,KAAK;AAAA,MAG3B,CAAC;AAAA,IACH;AACA,QAAI,WAAW,QAAQ,IAAI,SAAS,QAAQ;AAC1C,uBAAiB,IAAI,OAAO,IAAI,QAAQ,MAAM;AAAA,IAChD;AAIA,WAAO,IAAI,EAAE,IAAI;AAAA,EACnB,OAAO;AACL,WAAO,IAAI,EAAE,IAAI;AAAA,EACnB;AACA,SAAO;AACT;AAQO,SAAS,oBAA0B;AACxC,qBAAmB,MAAM;AACzB,oBAAkB,MAAM;AAC1B;","names":[]}

package/dist/{chunk-MUM7IANK.js → chunk-4MXI3ODD.js}

@@ -4,10 +4,10 @@ import {
   persistUserVisibility,
   readUserVisibility,
   saveUserEnvelope
-} from "./chunk-KG7TZKZG.js";
+} from "./chunk-7VCXZDA4.js";
 import {
   PolicyDeniedError
-} from "./chunk-7O3Y4PPD.js";
+} from "./chunk-244VXYPG.js";
 
 // src/with-party/directory/user-envelope/api.ts
 var UserApi = class {
@@ -213,7 +213,7 @@ var UserApi = class {
    * Honest caveat: this is a UX flag, not a privacy guarantee. The
    * envelope ciphertext at `_users/<keyringId>` and the keyring file at
    * `_keyring/<userId>` are both still observable to anyone with direct
-   * store read access. See `https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/user-envelope.md` →
+   * store read access. See `https://github.com/noy-db/docs/blob/main/content/docs/services/user-envelope.md` →
    * "Directory visibility".
    */
   async setMyVisibility(visibility) {
@@ -379,4 +379,4 @@ export {
   UserApi,
   createUserApi
 };
-//# sourceMappingURL=chunk-MUM7IANK.js.map
+//# sourceMappingURL=chunk-4MXI3ODD.js.map

package/dist/chunk-4MXI3ODD.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/with-party/directory/user-envelope/api.ts"],"sourcesContent":["/**\n * Public `vault.user.*` API surface.\n *\n * Three families:\n *  - Write-self: `me` / `updateMe` / `setMe` — always target the writer's\n *    own keyringId. **Own-only write rule** is structural — no method\n *    exists to write someone else's envelope.\n *  - Read-anyone: `get` / `list` — read other principals' envelopes\n *    (subject to `view-team-profiles` policy gate).\n *  - Reactive: `subscribe` / `live` — in-process event emission on local\n *    writes. Cross-instance updates land via the team/sync engine and\n *    surface to subscribers when the sync diff replays through this API.\n *\n * @see design-history/2026-05-05-user-envelope-design.md\n *\n * @module\n */\nimport { PolicyDeniedError } from '../../../kernel/errors.js'\nimport {\n  loadUserEnvelope,\n  saveUserEnvelope,\n  listUserEnvelopeIds,\n} from './storage.js'\nimport type {\n  UserEnvelope,\n  DeepPartialOrNull,\n  Unsubscribe,\n  UserEnvelopePresented,\n  LiveUserEnvelope,\n  VaultUserApi,\n  UserApiDeps,\n  UserApiFactory,\n} from '../../../kernel/types.js'\nimport {\n  persistUserVisibility,\n  readUserVisibility,\n} from '../visibility.js'\nimport type { UserVisibility } from '../types.js'\nimport type { ExportAccessibleOptions } from '../../../with-audit/portability/export-accessible.js'\nimport type { WithdrawAccessibleOptions, WithdrawResult } from '../../../with-audit/portability/withdraw-accessible.js'\nimport type {\n  RequestWithdrawalOptions,\n  RequestWithdrawalResult,\n  WithdrawalRequest,\n  WithdrawalRequestStatus,\n  ApproveWithdrawalOptions,\n  RejectWithdrawalOptions,\n} from '../../../with-audit/portability/request-withdrawal.js'\n\ninterface ChangeListener<T = unknown> {\n  (env: UserEnvelope<T> | null): void\n}\n\n/**\n * Implementation behind `vault.user`. Constructed once per Vault via\n * {@link createUserApi}, holds the writer's keyringId in closure so\n * `updateMe`/`setMe` cannot target any other principal — the own-only\n * rule is enforced at the type level (no `set(otherKeyringId, …)`\n * method) AND at runtime (the keyringId argument simply doesn't exist\n * on the write path).\n */\nexport class UserApi implements VaultUserApi {\n  /** keyringId → set of listeners. Wildcard '*' fires on every change. */\n  private readonly listeners = new Map<string, Set<ChangeListener>>()\n\n  private readonly adapter: UserApiDeps['adapter']\n  private readonly vaultName: UserApiDeps['vaultName']\n  /** The writer's own keyringId. Frozen at construction time. */\n  private readonly writerKeyringId: UserApiDeps['writerKeyringId']\n  private readonly getDek: UserApiDeps['getDek']\n  /**\n   * Policy-gate validator. When omitted, gates are skipped — useful\n   * for low-level tests that exercise the storage layer directly.\n   * Production paths always wire the Noydb-backed implementation.\n   */\n  private readonly checkGate?: UserApiDeps['checkGate']\n  /**\n   * Noydb-backed `exportMyAccessibleData`, injected by the Vault\n   * (which holds the keyring + bundle machinery). Omitted in low-level tests.\n   */\n  private readonly exportAccessible?: UserApiDeps['exportAccessible']\n  /**\n   * Noydb-backed `unilateralWithdrawal`, injected by the Vault.\n   * Destructive — extract + dispose (delete | freeze). Omitted in low-level tests.\n   */\n  private readonly unilateralWithdraw?: UserApiDeps['unilateralWithdraw']\n  /**\n   * Noydb-backed two-party withdrawal ceremony, injected by the\n   * Vault. requestWithdraw = requester side; the rest = owner side.\n   */\n  private readonly requestWithdraw?: UserApiDeps['requestWithdraw']\n  private readonly listWithdrawals?: UserApiDeps['listWithdrawals']\n  private readonly approveWithdraw?: UserApiDeps['approveWithdraw']\n  private readonly rejectWithdraw?: UserApiDeps['rejectWithdraw']\n\n  constructor(deps: UserApiDeps) {\n    this.adapter = deps.adapter\n    this.vaultName = deps.vaultName\n    this.writerKeyringId = deps.writerKeyringId\n    this.getDek = deps.getDek\n    this.checkGate = deps.checkGate\n    this.exportAccessible = deps.exportAccessible\n    this.unilateralWithdraw = deps.unilateralWithdraw\n    this.requestWithdraw = deps.requestWithdraw\n    this.listWithdrawals = deps.listWithdrawals\n    this.approveWithdraw = deps.approveWithdraw\n    this.rejectWithdraw = deps.rejectWithdraw\n  }\n\n  /**\n   * File a two-party withdrawal request for the caller's accessible\n   * scope. Non-destructive (writes a pending request); an owner later approves\n   * or rejects. This is the path for read-only roles (`client`/`viewer`) that\n   * cannot self-serve a destructive `unilateralWithdrawal`. Gated by\n   * `user-request-withdrawal` (enabled by default).\n   */\n  async requestWithdrawal(opts: RequestWithdrawalOptions = {}): Promise<RequestWithdrawalResult> {\n    if (this.checkGate) await this.checkGate('user-request-withdrawal')\n    if (!this.requestWithdraw) {\n      throw new Error('requestWithdrawal requires a Noydb-backed vault (not a bare UserApi)')\n    }\n    return this.requestWithdraw(opts)\n  }\n\n  /** Owner side: list filed withdrawal requests (optionally by status). */\n  async listWithdrawalRequests(opts: { status?: WithdrawalRequestStatus } = {}): Promise<WithdrawalRequest[]> {\n    if (!this.listWithdrawals) {\n      throw new Error('listWithdrawalRequests requires a Noydb-backed vault (not a bare UserApi)')\n    }\n    return this.listWithdrawals(opts)\n  }\n\n  /**\n   * Owner side: approve a pending request. Extracts the requester's\n   * recorded scope under firm authority, disposes of the source per the\n   * request's disposition, and returns the re-keyed bundle to hand back. Gated\n   * by `approve-user-withdrawal` (tier-2 default) + owner/admin role.\n   */\n  async approveWithdrawal(requestId: string, opts: ApproveWithdrawalOptions = {}): Promise<WithdrawResult> {\n    if (this.checkGate) await this.checkGate('approve-user-withdrawal')\n    if (!this.approveWithdraw) {\n      throw new Error('approveWithdrawal requires a Noydb-backed vault (not a bare UserApi)')\n    }\n    return this.approveWithdraw(requestId, opts)\n  }\n\n  /** Owner side: reject a pending request (no data is touched). */\n  async rejectWithdrawal(requestId: string, opts: RejectWithdrawalOptions = {}): Promise<WithdrawalRequest> {\n    if (this.checkGate) await this.checkGate('approve-user-withdrawal')\n    if (!this.rejectWithdraw) {\n      throw new Error('rejectWithdrawal requires a Noydb-backed vault (not a bare UserApi)')\n    }\n    return this.rejectWithdraw(requestId, opts)\n  }\n\n  /**\n   * Single-party withdrawal: export the caller's accessible scope\n   * (re-keyed) and dispose of the source (`delete` or `freeze`). Gated by the\n   * fail-closed built-in `client-unilateral-withdraw` policy — undefined or\n   * disabled → throws (use `requestWithdrawal`). The firm enables it at vault\n   * creation.\n   */\n  async unilateralWithdrawal(opts: WithdrawAccessibleOptions): Promise<WithdrawResult> {\n    if (this.checkGate) await this.checkGate('client-unilateral-withdraw')\n    if (!this.unilateralWithdraw) {\n      throw new Error('unilateralWithdrawal requires a Noydb-backed vault (not a bare UserApi)')\n    }\n    return this.unilateralWithdraw(opts)\n  }\n\n  /**\n   * Export the calling user's accessible scope as a portable, re-keyed\n   * `.noydb` bundle. Non-destructive and **always allowed** (data sovereignty\n   * by construction) but audited. Scope = the caller's DEK access set.\n   */\n  async exportMyAccessibleData(opts: ExportAccessibleOptions = {}): Promise<Uint8Array> {\n    if (!this.exportAccessible) {\n      throw new Error('exportMyAccessibleData requires a Noydb-backed vault (not a bare UserApi)')\n    }\n    return this.exportAccessible(opts)\n  }\n\n  // ─── Write-self ──────────────────────────────────────────────────────\n\n  /** Read the writer's own envelope. Returns null if never written. */\n  async me<T = unknown>(): Promise<UserEnvelope<T> | null> {\n    const dek = await this.getDek()\n    return loadUserEnvelope<T>(this.adapter, this.vaultName, this.writerKeyringId, dek)\n  }\n\n  /**\n   * Deep-merge a partial patch into the writer's own envelope. Creates\n   * the envelope on first call. Optimistic-concurrency safe — a stale\n   * `_v` (parallel writer on another device) throws `ConflictError`.\n   *\n   * Patch semantics:\n   *   - `undefined` (or omitted key) — skip; existing value preserved\n   *   - `null` — delete the field from the merged result\n   *   - any other value — overwrite (deep-merge for plain objects,\n   *     replace for primitives / arrays)\n   *\n   * To clear a field, pass `null` rather than `undefined`. Callers\n   * with shape `T = string | null` where `null` is a meaningful value\n   * should use `setMe` for that specific field instead — `null` here\n   * always means delete.\n   *\n   * Gated by the `edit-own-profile` policy gate (default `minTier: 3`).\n   * Pass `presented` to satisfy tightened policies that require a\n   * factor proof (e.g. STRICT_POLICY's TOTP requirement).\n   */\n  async updateMe<T extends object = Record<string, unknown>>(\n    patch: DeepPartialOrNull<T>,\n    presented?: UserEnvelopePresented,\n  ): Promise<UserEnvelope<T>> {\n    if (this.checkGate) await this.checkGate('edit-own-profile', presented)\n    const dek = await this.getDek()\n    const current = await loadUserEnvelope<T>(\n      this.adapter,\n      this.vaultName,\n      this.writerKeyringId,\n      dek,\n    )\n    const merged: T = current ? deepMerge(current.data, patch) : (patch as unknown as T)\n    const written = await saveUserEnvelope<T>(\n      this.adapter,\n      this.vaultName,\n      this.writerKeyringId,\n      merged,\n      dek,\n      current?._v ?? 0,\n    )\n    this.fireChange(this.writerKeyringId, written)\n    return written\n  }\n\n  /**\n   * Replace the writer's own envelope with `payload`. Use sparingly —\n   * `updateMe` is the canonical mutation. No `expectedVersion` check;\n   * callers explicitly take last-write-wins semantics.\n   *\n   * Gated by `edit-own-profile`. See `updateMe` for `presented` usage.\n   */\n  async setMe<T = unknown>(\n    payload: T,\n    presented?: UserEnvelopePresented,\n  ): Promise<UserEnvelope<T>> {\n    if (this.checkGate) await this.checkGate('edit-own-profile', presented)\n    const dek = await this.getDek()\n    const written = await saveUserEnvelope<T>(\n      this.adapter,\n      this.vaultName,\n      this.writerKeyringId,\n      payload,\n      dek,\n    )\n    this.fireChange(this.writerKeyringId, written)\n    return written\n  }\n\n  // ─── Visibility ──────────────────────────────────────────────────────\n\n  /**\n   * Read the current user's visibility flag from\n   * `_meta/visibility/<keyringId>`. Returns `{ hidden: false }` when no\n   * document has been persisted (the default-visible case).\n   */\n  async getMyVisibility(): Promise<UserVisibility> {\n    const persisted = await readUserVisibility(this.adapter, this.vaultName, this.writerKeyringId)\n    return persisted ?? { hidden: false }\n  }\n\n  /**\n   * Update the current user's visibility in the team directory.\n   *\n   * - `hidden: true` — opt out of the default `listUsersWithEnvelopes`\n   *   listing. `owner`/`admin` callers can still see the user by passing\n   *   `{ includeHidden: true }`.\n   * - `hidden: false` — opt back in.\n   *\n   * Own-only by construction: the keyringId argument doesn't exist on\n   * this method, so no caller can hide or unhide another principal.\n   *\n   * Honest caveat: this is a UX flag, not a privacy guarantee. The\n   * envelope ciphertext at `_users/<keyringId>` and the keyring file at\n   * `_keyring/<userId>` are both still observable to anyone with direct\n   * store read access. See `https://github.com/noy-db/docs/blob/main/content/docs/services/user-envelope.md` →\n   * \"Directory visibility\".\n   */\n  async setMyVisibility(visibility: UserVisibility): Promise<void> {\n    await persistUserVisibility(\n      this.adapter,\n      this.vaultName,\n      this.writerKeyringId,\n      { hidden: visibility.hidden },\n    )\n  }\n\n  // ─── Read-anyone ─────────────────────────────────────────────────────\n\n  /**\n   * Read another principal's envelope by their keyringId. Returns null\n   * if the principal exists but has no envelope yet, or if the\n   * keyringId does not exist at all.\n   *\n   * Gated by `view-team-profiles` (default `minTier: 2`) — but ONLY for\n   * cross-principal reads. Reading your own envelope (`keyringId ===\n   * self`) is never gated; that's just `me()` written long-form.\n   */\n  async get<T = unknown>(\n    keyringId: string,\n    presented?: UserEnvelopePresented,\n  ): Promise<UserEnvelope<T> | null> {\n    if (this.checkGate && keyringId !== this.writerKeyringId) {\n      await this.checkGate('view-team-profiles', presented)\n    }\n    const dek = await this.getDek()\n    return loadUserEnvelope<T>(this.adapter, this.vaultName, keyringId, dek)\n  }\n\n  /**\n   * Read every persisted envelope in the vault. Order is store-defined.\n   *\n   * Gated by `view-team-profiles`. Default policy (`minTier: 2`) lets\n   * any authenticated session read all envelopes. Two privacy-strict\n   * opt-outs:\n   *\n   *  - `view-team-profiles.enabled: false` → list() returns only the\n   *    caller's own envelope (silent self-fallback, no thrown error).\n   *  - `view-team-profiles.minTier: 1` + insufficient tier → throws\n   *    `PolicyDeniedError` with `reason: 'insufficient-tier'`. The\n   *    caller is expected to elevate, not silently degrade.\n   *\n   * The asymmetry is deliberate: `enabled: false` is a deliberate\n   * design choice (\"nobody sees teammate profiles in this app\");\n   * `insufficient-tier` is \"you need to authenticate further\". Different\n   * UX prompts for different intents.\n   */\n  async list<T = unknown>(presented?: UserEnvelopePresented): Promise<UserEnvelope<T>[]> {\n    if (this.checkGate) {\n      try {\n        await this.checkGate('view-team-profiles', presented)\n      } catch (err) {\n        if (err instanceof PolicyDeniedError && err.reason === 'disabled') {\n          // Privacy-strict opt-out: quietly return only self.\n          const me = await this.me<T>()\n          return me ? [me] : []\n        }\n        throw err\n      }\n    }\n    const dek = await this.getDek()\n    const ids = await listUserEnvelopeIds(this.adapter, this.vaultName)\n    const envelopes = await Promise.all(\n      ids.map((id) => loadUserEnvelope<T>(this.adapter, this.vaultName, id, dek)),\n    )\n    return envelopes.filter((e): e is UserEnvelope<T> => e !== null)\n  }\n\n  // ─── Reactive ────────────────────────────────────────────────────────\n\n  /**\n   * Listen for changes to a specific keyringId's envelope. The callback\n   * fires synchronously after every successful local `updateMe` /\n   * `setMe` for that principal.\n   *\n   * Cross-instance changes (a teammate edits their profile on their\n   * device, the sync engine pulls the diff onto this device) will fire\n   * subscribers when the sync layer replays the write through this API.\n   * In v1, subscribers do NOT fire on raw store changes — wire your sync\n   * layer to call back through `vault.user.setMe` / `updateMe` if you\n   * need that.\n   *\n   * Pass keyringId `'*'` to fire on every change in the vault.\n   */\n  subscribe<T = unknown>(\n    keyringId: string,\n    cb: (env: UserEnvelope<T> | null) => void,\n  ): Unsubscribe {\n    let listeners = this.listeners.get(keyringId)\n    if (!listeners) {\n      listeners = new Set()\n      this.listeners.set(keyringId, listeners)\n    }\n    const wrapped: ChangeListener = cb as ChangeListener\n    listeners.add(wrapped)\n    return () => {\n      listeners?.delete(wrapped)\n      if (listeners && listeners.size === 0) {\n        this.listeners.delete(keyringId)\n      }\n    }\n  }\n\n  /**\n   * Reactive handle that caches the current value and re-reads on every\n   * change for the given keyringId. Convenient for framework bindings:\n   *\n   *   const live = vault.user.live<UserShape>(vault.userId)\n   *   live.subscribe(env => render(env?.data))\n   *\n   * Initial value is `null` until the first `current()` call materializes\n   * it via `vault.user.get()`. Call `stop()` when done to release the\n   * subscription.\n   */\n  live<T = unknown>(keyringId: string): LiveUserEnvelope<T> {\n    let value: UserEnvelope<T> | null = null\n    let primed = false\n    const unsubscribe = this.subscribe<T>(keyringId, (env) => {\n      value = env\n    })\n\n    return {\n      current(): UserEnvelope<T> | null {\n        if (!primed) {\n          primed = true\n          // First call: kick off a read but return synchronously. The\n          // subscriber will be re-fired by the next write or the caller\n          // can await `vault.user.get()` directly for an immediate read.\n        }\n        return value\n      },\n      subscribe: (cb) => this.subscribe<T>(keyringId, cb),\n      stop: unsubscribe,\n    }\n  }\n\n  // ─── Internal: change emission ───────────────────────────────────────\n\n  private fireChange<T>(keyringId: string, env: UserEnvelope<T> | null): void {\n    const targeted = this.listeners.get(keyringId)\n    if (targeted) for (const l of targeted) l(env)\n    const wildcard = this.listeners.get('*')\n    if (wildcard) for (const l of wildcard) l(env)\n  }\n}\n\n/**\n * Build the `vault.user` API implementation from its dependencies. This is\n * the real {@link UserApiFactory} — `createNoydb()` dynamically imports it\n * and stashes it on the `Noydb` instance so `Vault`'s constructor can call\n * it synchronously.\n */\nexport const createUserApi: UserApiFactory = (deps: UserApiDeps): VaultUserApi => new UserApi(deps)\n\n/**\n * Recursive plain-object deep merge with delete intent.\n *\n * Patch semantics:\n *   - `undefined` — skip the key; source value preserved\n *   - `null` — delete the key from output (lodash `_.merge` /\n *     Firestore `FieldValue.delete()` semantics)\n *   - plain object — recurse (deep merge)\n *   - any other value — replace (arrays are replaced, not concatenated)\n *\n * Safe against the JS quirk where an own property explicitly set to\n * `undefined` is iterated by `Object.entries`. We dispatch on the value\n * BEFORE writing, so `{ k: undefined }` triggers the skip branch rather\n * than overwriting `out[k]` with undefined.\n */\nfunction deepMerge<T>(source: T, patch: DeepPartialOrNull<T>): T {\n  if (!isPlainObject(source) || !isPlainObject(patch)) {\n    // Top-level non-object replace. `null` patch at the leaf level\n    // would have been caught by the parent recursion's branch table;\n    // at the top level it means \"set the whole envelope to null,\"\n    // which the type system already prevents (T extends object).\n    return patch as unknown as T\n  }\n  const out: Record<string, unknown> = { ...(source as Record<string, unknown>) }\n  for (const [key, patchVal] of Object.entries(patch as Record<string, unknown>)) {\n    if (patchVal === undefined) {\n      // Skip — preserve the source value at this key. Matches the\n      // pre-existing behavior so callers who never used `null` see no diff.\n      continue\n    }\n    if (patchVal === null) {\n      // Delete intent. `delete` rather than `out[key] = undefined`\n      // because JSON.stringify drops undefined fields silently and\n      // we want the deletion to be visible to consumers iterating\n      // the merged object (e.g. `Object.keys(merged.profile)`).\n      delete out[key]\n      continue\n    }\n    const sourceVal = (source as Record<string, unknown>)[key]\n    if (isPlainObject(patchVal)) {\n      // Recurse for any plain-object patch — including the \"source is\n      // missing this key\" case. Without recursing through a synthetic\n      // empty source, nested `null` deletions in the patch would land\n      // as literal `null` values instead of triggering the delete\n      // branch (e.g. `{ app: { signature: null } }` against a missing\n      // `app` would emit `{ app: { signature: null } }` instead of\n      // `{ app: {} }`).\n      const recurseSource = isPlainObject(sourceVal) ? sourceVal : {}\n      out[key] = deepMerge(recurseSource, patchVal as DeepPartialOrNull<typeof recurseSource>)\n    } else {\n      out[key] = patchVal\n    }\n  }\n  return out as T\n}\n\nfunction isPlainObject(x: unknown): x is Record<string, unknown> {\n  if (x === null || typeof x !== 'object') return false\n  if (Array.isArray(x)) return false\n  const proto = Object.getPrototypeOf(x) as object | null\n  return proto === Object.prototype || proto === null\n}\n"],"mappings":";;;;;;;;;;;;AA6DO,IAAM,UAAN,MAAsC;AAAA;AAAA,EAE1B,YAAY,oBAAI,IAAiC;AAAA,EAEjD;AAAA,EACA;AAAA;AAAA,EAEA;AAAA,EACA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA;AAAA;AAAA;AAAA;AAAA;AAAA,EAKA;AAAA;AAAA;AAAA;AAAA;AAAA,EAKA;AAAA;AAAA;AAAA;AAAA;AAAA,EAKA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAEjB,YAAY,MAAmB;AAC7B,SAAK,UAAU,KAAK;AACpB,SAAK,YAAY,KAAK;AACtB,SAAK,kBAAkB,KAAK;AAC5B,SAAK,SAAS,KAAK;AACnB,SAAK,YAAY,KAAK;AACtB,SAAK,mBAAmB,KAAK;AAC7B,SAAK,qBAAqB,KAAK;AAC/B,SAAK,kBAAkB,KAAK;AAC5B,SAAK,kBAAkB,KAAK;AAC5B,SAAK,kBAAkB,KAAK;AAC5B,SAAK,iBAAiB,KAAK;AAAA,EAC7B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,MAAM,kBAAkB,OAAiC,CAAC,GAAqC;AAC7F,QAAI,KAAK,UAAW,OAAM,KAAK,UAAU,yBAAyB;AAClE,QAAI,CAAC,KAAK,iBAAiB;AACzB,YAAM,IAAI,MAAM,sEAAsE;AAAA,IACxF;AACA,WAAO,KAAK,gBAAgB,IAAI;AAAA,EAClC;AAAA;AAAA,EAGA,MAAM,uBAAuB,OAA6C,CAAC,GAAiC;AAC1G,QAAI,CAAC,KAAK,iBAAiB;AACzB,YAAM,IAAI,MAAM,2EAA2E;AAAA,IAC7F;AACA,WAAO,KAAK,gBAAgB,IAAI;AAAA,EAClC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAM,kBAAkB,WAAmB,OAAiC,CAAC,GAA4B;AACvG,QAAI,KAAK,UAAW,OAAM,KAAK,UAAU,yBAAyB;AAClE,QAAI,CAAC,KAAK,iBAAiB;AACzB,YAAM,IAAI,MAAM,sEAAsE;AAAA,IACxF;AACA,WAAO,KAAK,gBAAgB,WAAW,IAAI;AAAA,EAC7C;AAAA;AAAA,EAGA,MAAM,iBAAiB,WAAmB,OAAgC,CAAC,GAA+B;AACxG,QAAI,KAAK,UAAW,OAAM,KAAK,UAAU,yBAAyB;AAClE,QAAI,CAAC,KAAK,gBAAgB;AACxB,YAAM,IAAI,MAAM,qEAAqE;AAAA,IACvF;AACA,WAAO,KAAK,eAAe,WAAW,IAAI;AAAA,EAC5C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,MAAM,qBAAqB,MAA0D;AACnF,QAAI,KAAK,UAAW,OAAM,KAAK,UAAU,4BAA4B;AACrE,QAAI,CAAC,KAAK,oBAAoB;AAC5B,YAAM,IAAI,MAAM,yEAAyE;AAAA,IAC3F;AACA,WAAO,KAAK,mBAAmB,IAAI;AAAA,EACrC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,uBAAuB,OAAgC,CAAC,GAAwB;AACpF,QAAI,CAAC,KAAK,kBAAkB;AAC1B,YAAM,IAAI,MAAM,2EAA2E;AAAA,IAC7F;AACA,WAAO,KAAK,iBAAiB,IAAI;AAAA,EACnC;AAAA;AAAA;AAAA,EAKA,MAAM,KAAmD;AACvD,UAAM,MAAM,MAAM,KAAK,OAAO;AAC9B,WAAO,iBAAoB,KAAK,SAAS,KAAK,WAAW,KAAK,iBAAiB,GAAG;AAAA,EACpF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAsBA,MAAM,SACJ,OACA,WAC0B;AAC1B,QAAI,KAAK,UAAW,OAAM,KAAK,UAAU,oBAAoB,SAAS;AACtE,UAAM,MAAM,MAAM,KAAK,OAAO;AAC9B,UAAM,UAAU,MAAM;AAAA,MACpB,KAAK;AAAA,MACL,KAAK;AAAA,MACL,KAAK;AAAA,MACL;AAAA,IACF;AACA,UAAM,SAAY,UAAU,UAAU,QAAQ,MAAM,KAAK,IAAK;AAC9D,UAAM,UAAU,MAAM;AAAA,MACpB,KAAK;AAAA,MACL,KAAK;AAAA,MACL,KAAK;AAAA,MACL;AAAA,MACA;AAAA,MACA,SAAS,MAAM;AAAA,IACjB;AACA,SAAK,WAAW,KAAK,iBAAiB,OAAO;AAC7C,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,MAAM,MACJ,SACA,WAC0B;AAC1B,QAAI,KAAK,UAAW,OAAM,KAAK,UAAU,oBAAoB,SAAS;AACtE,UAAM,MAAM,MAAM,KAAK,OAAO;AAC9B,UAAM,UAAU,MAAM;AAAA,MACpB,KAAK;AAAA,MACL,KAAK;AAAA,MACL,KAAK;AAAA,MACL;AAAA,MACA;AAAA,IACF;AACA,SAAK,WAAW,KAAK,iBAAiB,OAAO;AAC7C,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,MAAM,kBAA2C;AAC/C,UAAM,YAAY,MAAM,mBAAmB,KAAK,SAAS,KAAK,WAAW,KAAK,eAAe;AAC7F,WAAO,aAAa,EAAE,QAAQ,MAAM;AAAA,EACtC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAmBA,MAAM,gBAAgB,YAA2C;AAC/D,UAAM;AAAA,MACJ,KAAK;AAAA,MACL,KAAK;AAAA,MACL,KAAK;AAAA,MACL,EAAE,QAAQ,WAAW,OAAO;AAAA,IAC9B;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAaA,MAAM,IACJ,WACA,WACiC;AACjC,QAAI,KAAK,aAAa,cAAc,KAAK,iBAAiB;AACxD,YAAM,KAAK,UAAU,sBAAsB,SAAS;AAAA,IACtD;AACA,UAAM,MAAM,MAAM,KAAK,OAAO;AAC9B,WAAO,iBAAoB,KAAK,SAAS,KAAK,WAAW,WAAW,GAAG;AAAA,EACzE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAoBA,MAAM,KAAkB,WAA+D;AACrF,QAAI,KAAK,WAAW;AAClB,UAAI;AACF,cAAM,KAAK,UAAU,sBAAsB,SAAS;AAAA,MACtD,SAAS,KAAK;AACZ,YAAI,eAAe,qBAAqB,IAAI,WAAW,YAAY;AAEjE,gBAAM,KAAK,MAAM,KAAK,GAAM;AAC5B,iBAAO,KAAK,CAAC,EAAE,IAAI,CAAC;AAAA,QACtB;AACA,cAAM;AAAA,MACR;AAAA,IACF;AACA,UAAM,MAAM,MAAM,KAAK,OAAO;AAC9B,UAAM,MAAM,MAAM,oBAAoB,KAAK,SAAS,KAAK,SAAS;AAClE,UAAM,YAAY,MAAM,QAAQ;AAAA,MAC9B,IAAI,IAAI,CAAC,OAAO,iBAAoB,KAAK,SAAS,KAAK,WAAW,IAAI,GAAG,CAAC;AAAA,IAC5E;AACA,WAAO,UAAU,OAAO,CAAC,MAA4B,MAAM,IAAI;AAAA,EACjE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAkBA,UACE,WACA,IACa;AACb,QAAI,YAAY,KAAK,UAAU,IAAI,SAAS;AAC5C,QAAI,CAAC,WAAW;AACd,kBAAY,oBAAI,IAAI;AACpB,WAAK,UAAU,IAAI,WAAW,SAAS;AAAA,IACzC;AACA,UAAM,UAA0B;AAChC,cAAU,IAAI,OAAO;AACrB,WAAO,MAAM;AACX,iBAAW,OAAO,OAAO;AACzB,UAAI,aAAa,UAAU,SAAS,GAAG;AACrC,aAAK,UAAU,OAAO,SAAS;AAAA,MACjC;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAaA,KAAkB,WAAwC;AACxD,QAAI,QAAgC;AACpC,QAAI,SAAS;AACb,UAAM,cAAc,KAAK,UAAa,WAAW,CAAC,QAAQ;AACxD,cAAQ;AAAA,IACV,CAAC;AAED,WAAO;AAAA,MACL,UAAkC;AAChC,YAAI,CAAC,QAAQ;AACX,mBAAS;AAAA,QAIX;AACA,eAAO;AAAA,MACT;AAAA,MACA,WAAW,CAAC,OAAO,KAAK,UAAa,WAAW,EAAE;AAAA,MAClD,MAAM;AAAA,IACR;AAAA,EACF;AAAA;AAAA,EAIQ,WAAc,WAAmB,KAAmC;AAC1E,UAAM,WAAW,KAAK,UAAU,IAAI,SAAS;AAC7C,QAAI,SAAU,YAAW,KAAK,SAAU,GAAE,GAAG;AAC7C,UAAM,WAAW,KAAK,UAAU,IAAI,GAAG;AACvC,QAAI,SAAU,YAAW,KAAK,SAAU,GAAE,GAAG;AAAA,EAC/C;AACF;AAQO,IAAM,gBAAgC,CAAC,SAAoC,IAAI,QAAQ,IAAI;AAiBlG,SAAS,UAAa,QAAW,OAAgC;AAC/D,MAAI,CAAC,cAAc,MAAM,KAAK,CAAC,cAAc,KAAK,GAAG;AAKnD,WAAO;AAAA,EACT;AACA,QAAM,MAA+B,EAAE,GAAI,OAAmC;AAC9E,aAAW,CAAC,KAAK,QAAQ,KAAK,OAAO,QAAQ,KAAgC,GAAG;AAC9E,QAAI,aAAa,QAAW;AAG1B;AAAA,IACF;AACA,QAAI,aAAa,MAAM;AAKrB,aAAO,IAAI,GAAG;AACd;AAAA,IACF;AACA,UAAM,YAAa,OAAmC,GAAG;AACzD,QAAI,cAAc,QAAQ,GAAG;AAQ3B,YAAM,gBAAgB,cAAc,SAAS,IAAI,YAAY,CAAC;AAC9D,UAAI,GAAG,IAAI,UAAU,eAAe,QAAmD;AAAA,IACzF,OAAO;AACL,UAAI,GAAG,IAAI;AAAA,IACb;AAAA,EACF;AACA,SAAO;AACT;AAEA,SAAS,cAAc,GAA0C;AAC/D,MAAI,MAAM,QAAQ,OAAO,MAAM,SAAU,QAAO;AAChD,MAAI,MAAM,QAAQ,CAAC,EAAG,QAAO;AAC7B,QAAM,QAAQ,OAAO,eAAe,CAAC;AACrC,SAAO,UAAU,OAAO,aAAa,UAAU;AACjD;","names":[]}

package/dist/{chunk-BLN54W3L.js → chunk-5FDLC6G7.js}

@@ -6,7 +6,7 @@ import {
   ConflictError,
   InvariantError,
   ValidationError
-} from "./chunk-7O3Y4PPD.js";
+} from "./chunk-244VXYPG.js";
 
 // src/with-commit/tx/atomic-eligibility.ts
 function canCommitAtomically(db, ctx) {
@@ -58,6 +58,45 @@ async function bestEffortRevert(executed, adapter, compensate) {
   }
 }
 
+// src/kernel/tx-write-gate.ts
+var inFlight = /* @__PURE__ */ new WeakMap();
+function writeGateKey(vault, collection, id) {
+  return `${vault}\0${collection}\0${id}`;
+}
+async function trackKeyedWrite(store, vault, collection, id, fn) {
+  let byKey = inFlight.get(store);
+  if (byKey === void 0) {
+    byKey = /* @__PURE__ */ new Map();
+    inFlight.set(store, byKey);
+  }
+  const key = writeGateKey(vault, collection, id);
+  let waiters = byKey.get(key);
+  if (waiters === void 0) {
+    waiters = /* @__PURE__ */ new Set();
+    byKey.set(key, waiters);
+  }
+  const running = fn();
+  const settled = running.then(() => void 0, () => void 0);
+  waiters.add(settled);
+  try {
+    return await running;
+  } finally {
+    waiters.delete(settled);
+    if (waiters.size === 0) byKey.delete(key);
+  }
+}
+async function drainKeyedWrites(store, keys) {
+  const byKey = inFlight.get(store);
+  if (byKey === void 0 || byKey.size === 0) return;
+  let waits;
+  for (const key of keys) {
+    const waiters = byKey.get(key);
+    if (waiters === void 0) continue;
+    for (const w of waiters) (waits ??= []).push(w);
+  }
+  if (waits !== void 0) await Promise.all(waits);
+}
+
 // src/with-commit/tx/transaction.ts
 var TxContext = class {
   /** Stable id for this transaction; shared by all writes it performs. */
@@ -211,6 +250,7 @@ async function runTransaction(db, fn, options, txInvariants) {
   }
   const priorEnvelopes = /* @__PURE__ */ new Map();
   const store = db._store;
+  await drainKeyedWrites(store, ctx._ops.map(keyOf));
   const invariants = txInvariants ?? [];
   const watchedScopes = new Set(invariants.map((i) => i.scope));
   const plainBefore = /* @__PURE__ */ new Map();
@@ -240,17 +280,29 @@ async function runTransaction(db, fn, options, txInvariants) {
     if (canCommitAtomically(db, ctx)) {
       await db._writeQueueTracker.track(() => commitAtomicBatch(db, ctx, priorEnvelopes));
     } else {
+      const writtenKeys = /* @__PURE__ */ new Set();
       try {
         for (const op of ctx._ops) {
           const coll = db.vault(op.vaultName).collection(op.collectionName);
           const key = keyOf(op);
           const prior = priorEnvelopes.get(key) ?? null;
+          if (op.expectedVersion !== void 0 && !writtenKeys.has(key)) {
+            const current = await store.get(op.vaultName, op.collectionName, op.id);
+            const actual = current?._v ?? 0;
+            if (actual !== op.expectedVersion) {
+              throw new ConflictError(
+                actual,
+                `Transaction execute: ${op.vaultName}/${op.collectionName}/${op.id} expected v${op.expectedVersion}, found v${actual}`
+              );
+            }
+          }
           ctx._executed.push({ op, priorEnvelope: prior });
           if (op.type === "put") {
             await coll.put(op.id, op.record, op.reason !== void 0 ? { reason: op.reason } : void 0);
           } else {
             await coll.delete(op.id);
           }
+          writtenKeys.add(key);
         }
       } catch (err) {
         await revertExecuted(ctx._executed, store, db);
@@ -270,7 +322,7 @@ async function runTransaction(db, fn, options, txInvariants) {
     db._clearActiveTxContext(ctx);
   }
   if (ctx._amendment) {
-    const { GuardExecutor } = await import("./executor-AQVXV5GZ.js");
+    const { GuardExecutor } = await import("./executor-BI5CHWRY.js");
     try {
       for (const [vaultName, v] of ctx._amendmentVaults) {
         const registry = v._getGuardRegistry();
@@ -441,10 +493,11 @@ function keyOf(op) {
 }
 
 export {
+  trackKeyedWrite,
   bestEffortRevert,
   TxContext,
   TxVault,
   TxCollection,
   runTransaction
 };
-//# sourceMappingURL=chunk-BLN54W3L.js.map
+//# sourceMappingURL=chunk-5FDLC6G7.js.map