@noy-db/hub 0.10.0-pre.1 → 0.10.0-pre.2

package/dist/{chunk-HQFTE3DX.js → chunk-5BGHAVBN.js}

@@ -11,7 +11,7 @@ import {
   filterRecords,
   fnViewDecoder,
   orderKeyOf
-} from "./chunk-R4PDYYK5.js";
+} from "./chunk-C2NXAR3D.js";
 
 // src/kernel/query/internal/maintenance.ts
 var MaintenanceMethods = class {
@@ -97,4 +97,4 @@ var MaintenanceMethods = class {
 export {
   MaintenanceMethods
 };
-//# sourceMappingURL=chunk-HQFTE3DX.js.map
+//# sourceMappingURL=chunk-5BGHAVBN.js.map

package/dist/{chunk-QHG7GQKM.js → chunk-5JNEDW7I.js}

@@ -1,7 +1,7 @@
 import {
   envelopeBodyForHash,
   sha256Hex
-} from "./chunk-WRLWEYHY.js";
+} from "./chunk-EFINFZIF.js";
 
 // src/with-commit/history/ledger/entry.ts
 function canonicalJson(value) {
@@ -65,4 +65,4 @@ export {
   parseIndex,
   envelopePayloadHash
 };
-//# sourceMappingURL=chunk-QHG7GQKM.js.map
+//# sourceMappingURL=chunk-5JNEDW7I.js.map

package/dist/{chunk-NC6CF37L.js → chunk-5OWJSDTO.js}

@@ -3,15 +3,15 @@ import {
 } from "./chunk-XBKH4FOC.js";
 import {
   normalizeJoinOn
-} from "./chunk-ME6LY5UG.js";
+} from "./chunk-ET3U2C3A.js";
 import {
   sha256Hex
-} from "./chunk-WRLWEYHY.js";
+} from "./chunk-EFINFZIF.js";
 import {
   MaterializedViewConfigError,
   MaterializedViewSourceUnknownError,
   RefNotDeclaredError
-} from "./chunk-JGYCKX56.js";
+} from "./chunk-ISIXU45J.js";
 
 // src/with-formula/materialized-views/dependency-analyzer.ts
 function analyzeDependencies(query) {
@@ -574,4 +574,4 @@ export {
   ungatedMvContext,
   wrapDbWithPredicates
 };
-//# sourceMappingURL=chunk-NC6CF37L.js.map
+//# sourceMappingURL=chunk-5OWJSDTO.js.map

package/dist/{chunk-NC6CF37L.js.map → chunk-5OWJSDTO.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/with-formula/materialized-views/dependency-analyzer.ts","../src/with-formula/materialized-views/query-hash.ts","../src/with-formula/materialized-views/projection-legs.ts","../src/with-formula/materialized-views/registry.ts"],"sourcesContent":["import { describeGroupKey, type GroupKey } from '../../kernel/query/reduce/date-trunc.js'\nimport type { Query, QueryPlan } from '../../kernel/query/builder.js'\nimport type { JoinContext, JoinLeg } from '../../kernel/query/relate/join.js'\nimport type { MaterializedViewSpec } from './types.js'\nimport { normalizeJoinOn } from '../../kernel/query/relate/join-on.js'\n\n/**\n * Walks a `Query<T>` plan and returns the set of source collection\n * names that any source-write should trigger a refresh on.\n *\n * Handles:\n *   - root collection (the one the query was built from)\n *   - FK join targets (`.join(field, { as })`)\n *\n * Also handles:\n *   - cross-join targets (`.crossJoin(target, { as })`) — v3\n *\n * Deferred:\n *   - `.wherePredicate(name)` — v2 predicate primitive\n *   - Overlay-name expansion to {base, overlay}\n *\n * The set is materialized at MV registration time. The MV registry\n * uses it to (a) dispatch `onSourceWrite` only to MVs that actually\n * care, and (b) contribute edges to the shared cycle-detection graph.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function analyzeDependencies(query: Query<any>): Set<string> {\n  const deps = new Set<string>()\n  const plan = query._plan()\n  const ctx = query._joinContext()\n\n  // The root collection is always a dependency.\n  if (ctx?.leftCollection) {\n    deps.add(ctx.leftCollection)\n  }\n\n  // FK join targets contribute additional sources.\n  for (const leg of plan.joins) {\n    deps.add(leg.target)\n  }\n\n  // Cross-join targets are also dependency sources — writes to either side\n  // must trigger MV refresh. Symmetric with FK-join target handling above.\n  for (const clause of plan.clauses) {\n    if (clause.type === 'crossJoin') {\n      deps.add(clause.target)\n    }\n  }\n\n  // Sub-plans inside OR clauses can carry nested joins. Walk them.\n  // (Today only top-level `.join()` populates `plan.joins`, but the\n  // OR-group machinery permits sub-plans, so we recurse defensively.)\n  walkClausesForJoins(plan, deps, ctx)\n\n  return deps\n}\n\nfunction walkClausesForJoins(\n  plan: QueryPlan,\n  deps: Set<string>,\n  ctx: JoinContext | undefined,\n): void {\n  void ctx\n  // Today `plan.joins` carries all join legs at top level. Sub-plans\n  // inside OR groups don't currently support nested joins, so the loop\n  // below is a no-op safety net for future builder extensions.\n  for (const clause of plan.clauses) {\n    if (clause.type === 'group') {\n      // Group clauses don't (yet) carry their own joins; this is a\n      // forward-compat anchor for when OR-groups support nested\n      // sources.\n    }\n  }\n}\n\n/**\n * Convenience: produce a stable string summary of the query plan\n * suitable for `queryHash` derivation. Captures everything the\n * dependency analyzer reads + the where/orderBy/limit/offset\n * structure that affects materialized rows.\n *\n * `joinContext` is intentionally NOT included — the join-resolution\n * function references would defeat hash determinism. The set of join\n * TARGETS (collection names) IS included via the plan.joins legs.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function summarizeQueryPlan(query: Query<any>): string {\n  const plan = query._plan()\n  const ctx = query._joinContext()\n  return JSON.stringify({\n    root: ctx?.leftCollection ?? null,\n    clauses: plan.clauses.map(c => {\n      if (c.type === 'crossJoin') {\n        return {\n          type: 'crossJoin',\n          target: c.target,\n          as: c.as,\n          // Inline on: callback: use sentinel — drift detection disabled for this MV\n          onPredicateName: c.onPredicateName ?? (c.on ? '[inline]' : null),\n          maxRows: c.maxRows ?? null,\n          // `outer` changes the row set, so it is part of the plan's identity\n          // for drift detection, not decoration (#1130).\n          outer: c.outer ?? false,\n        }\n      }\n      return c\n    }),\n    orderBy: plan.orderBy,\n    limit: plan.limit ?? null,\n    offset: plan.offset,\n    joins: plan.joins.map(j => summarizeJoinLeg(j)),\n  })\n}\n\n/**\n * The per-leg half of {@link summarizeQueryPlan}, split out so the property\n * test in `__tests__/query-join-summary-hash.test.ts` can address it directly.\n *\n * ⭐ **THE RULE FOR GROWING THIS FUNCTION (#1389).** Every key here is inside\n * an already-stored `queryHash`. A key that is emitted unconditionally can\n * never be added, removed, or renamed without moving EVERY joined MV's hash\n * and silently recomputing every one of them. A key that is OMITTED AT ITS\n * DEFAULT can: `JSON.stringify` drops an `undefined` value, so a leg that does\n * not use the feature summarises byte-identically to its pre-change self and\n * only the MVs genuinely using the feature recompute — once, correctly.\n * So: **new keys are omitted at their default, always.** Pinned by the\n * byte-identity test in that file.\n *\n * ⛔ And the converse duty, which is what #1389 actually was: a `JoinLeg` field\n * that changes WHICH ROWS the leg produces and is NOT emitted here makes two\n * semantically different MVs share a hash, so drift detection goes blind and\n * nothing reports it. `direction`, `inner` and `isDictJoin` were all in that\n * state. The exclusion list below is deliberate and each entry states why;\n * the property test fails if a new `JoinLeg` key appears in neither.\n */\nfunction summarizeJoinLeg(j: JoinLeg): Record<string, unknown> {\n  return {\n    field: j.field,\n    as: j.as,\n    target: j.target,\n    mode: j.mode,\n    // #1339 — the declared `on` IS the join's identity: two `.joinOn()`\n    // plans differing only here select different rows, and without this key\n    // they would hash identically and neither MV would ever be seen as\n    // stale. `undefined` for every other leg, and `JSON.stringify` drops an\n    // undefined value, so a plan carrying no `joinOn` summarises\n    // byte-identically to its pre-#1339 self and no stored hash moves.\n    on: j.on,\n    // #1389 — `direction` (#1289) decides which SIDE is preserved: a right or\n    // full leg emits rows a left leg never produces. Omitted for a left leg,\n    // which is `undefined` on the leg itself, so a plain `.join()` plan is\n    // byte-identical to its pre-#1389 summary.\n    direction: j.direction,\n    // #1389 — `inner` (#1361) DROPS every unmatched left row. Only ever\n    // `true`; `undefined` on every other leg, so again nothing moves for a\n    // plan that does not use it.\n    inner: j.inner,\n    // #1389 — a dict join attaches `{ ...labels, key }` from the dictionary\n    // snapshot instead of a right-side record, and `target` names a\n    // dictionary rather than a collection. Two legs can otherwise agree on\n    // all four base keys (a dict leg's `target` IS its `field`, which a ref\n    // join to a like-named collection reproduces), so without this key they\n    // hash identically while materializing different rows. Only ever `true`.\n    isDictJoin: j.isDictJoin,\n    // ── EXCLUDED, deliberately (#1389). Read before adding one. ──────────\n    //\n    // `partitionScope` — NOT emitted, and this is the load-bearing one. It is\n    //   `'all'` on every leg ever built and the executor never reads it\n    //   (#1342), so it cannot change a row. It is also present unconditionally\n    //   rather than omitted-at-default, so starting to emit it would move\n    //   EVERY joined MV's hash at once for zero semantic gain. If a future\n    //   change ever makes it narrowable, emit it only when it is not `'all'`.\n    //\n    // `strategy` — NOT emitted: a manual planner override picks HOW the same\n    //   rows are produced (hash vs lookup), never which. Emitting it would\n    //   force a full recompute for a pure performance tweak.\n    //\n    // `maxRows` — NOT emitted: a per-side ceiling that throws\n    //   `JoinTooLargeError` when crossed. A query that succeeds returns the\n    //   same rows at any ceiling above its size, so it is not part of the\n    //   plan's row identity.\n  }\n}\n\n/**\n * Canonical string description of a UNION MV's plan, used as input to\n * `computeQueryHash`.\n *\n * Asymmetry note:\n *   - Arm collection names are NOT sorted. Declaration order is\n *     semantically meaningful for the dedup-only UNION path —\n *     `materializeUnionResult` iterates `spec.unionSources` in\n *     declaration order and keeps the first-seen row per composite key\n *     (tie-break precedence). If we sorted arms here, a consumer who\n *     reordered `unionSources` to change precedence would compute the\n *     same `queryHash`, refresh would be a no-op, and stale MV rows\n *     would persist. Hashing in declaration order makes any reorder\n *     trigger a refresh.\n *   - `groupBy` fields ARE sorted, by their canonical `describeGroupKey`\n *     description (which is the field name itself for a plain key). Multi-key\n *     groupBy buckets are commutative (`canonicalGroupKey` produces the same\n *     composite key regardless of field order in the input spec).\n *   - `aggregate` keys ARE sorted. Reducer-spec keys are independent\n *     of each other — order of declaration doesn't change output.\n *\n * Per-arm `map` functions are NOT fingerprinted; consumers must bump\n * the MV's `name` (or rely on application-level cache busting) when\n * `map` semantics change non-equivalently.\n */\nexport function summarizeUnionPlan<T extends Record<string, unknown>>(\n  spec: MaterializedViewSpec<T>,\n): string {\n  return `union(${summarizeUnionArms(spec)})${summarizeGroupingTail(spec)}`\n}\n\n/**\n * Canonical string description of a projection MV's plan (#810), used\n * as input to `computeQueryHash`.\n *\n * Leg descriptors ARE sorted (contrast with UNION arm order): every\n * leg attaches under a distinct `as` alias, forward legs are\n * one-to-one attachments and collect legs are independent\n * hash-grouped passes, so declaration order never changes the\n * materialized rows — a pure reorder must NOT force a refresh.\n * `from` (#1140) constrains the legal orderings (a leg must follow the\n * alias it attaches to) without making order meaningful: each descriptor\n * carries its own `@alias`, and aliases are unique, so the sorted set\n * still determines the leg graph exactly.\n *\n * The projection `map` is NOT fingerprinted (identical limitation as\n * the UNION arm `map`); consumers must bump the MV's `name` when\n * `map` semantics change non-equivalently.\n */\nexport function summarizeProjectionPlan<T extends Record<string, unknown>>(\n  spec: MaterializedViewSpec<T>,\n): string {\n  const projection = spec.projection!\n  const legs = projection.joins\n    .map(leg => {\n      // #1140 — `from` changes which rows a leg attaches to, so it is part of\n      // the plan's identity. Omitting it would let two structurally different\n      // projections share a queryHash and silently skip a refresh.\n      const at = leg.from !== undefined ? `@${leg.from}` : ''\n      return 'collect' in leg\n        ? `collect${at}:${leg.collect}.${leg.on}→${leg.as}`\n        : `field${at}:${leg.field}→${leg.as}`\n    })\n    .sort()\n  const body = JSON.stringify({ source: projection.source, legs })\n  return `projection(${body})${summarizeGroupingTail(spec)}`\n}\n\n/** Arm descriptors for `summarizeUnionPlan` — declaration order preserved (see its doc). */\nfunction summarizeUnionArms<T extends Record<string, unknown>>(\n  spec: MaterializedViewSpec<T>,\n): string {\n  return (spec.unionSources ?? [])\n    .map(s => {\n      // Fold each arm's join legs into the summary so adding or\n      // reordering joins (which changes the materialized rows) bumps\n      // queryHash. Leg order is declaration-significant (legs chain), so\n      // it is NOT sorted — same rationale as arm declaration order.\n      // #1411 — a declared leg folds its NORMALISED predicate in (the normal\n      // form is what makes two logically identical `on`s hash identically, and\n      // `normalizeJoinOn` throwing here is what makes a malformed leg fail at\n      // registration rather than at the first refresh).\n      const joins = s.join?.length\n        ? `[${s.join.map(j => 'on' in j\n            ? `${j.target}?${JSON.stringify(normalizeJoinOn(j.on, j.target))}${j.mode === 'inner' ? '!' : ''}→${j.as}`\n            : `${j.field}→${j.as}`).join(';')}]`\n        : ''\n      return `${s.collection}${joins}`\n    })\n    .join(',')\n}\n\n\n/**\n * #1411 — the window's contribution to `queryHash`.\n *\n * ⚠️ **`partitionBy` and `orderBy` are NOT sorted, unlike the groupBy and\n * aggregate keys beside them.** Group buckets are commutative, so sorting them\n * is what stops a re-ordered declaration from forcing a pointless refresh. A\n * window's keys are not: `orderBy: ['a','b']` walks a partition differently\n * from `['b','a']` and produces different running totals, and a partition list\n * feeds the same key-building order. Sorting them here would let a real\n * semantic change reuse a stored `queryHash`, refresh would be a no-op, and\n * the view would serve numbers computed under the old ordering.\n *\n * ⭐ **Returns the EMPTY STRING when no window is declared**, which is the same\n * omitted-at-default discipline `summarizeJoinLeg` states above and for the\n * same reason: every existing MV's stored `queryHash` must stay byte-identical\n * across this change, so only a view that actually declares a window\n * recomputes — once, correctly.\n *\n * `select` KEYS are sorted — they are independent output columns, same\n * rationale as the aggregate keys. The slot VALUES are functions and cannot be\n * hashed; renaming a column or adding one is what this can see, which is the\n * same limit `aggregate` has.\n */\nfunction summarizeWindow<T extends Record<string, unknown>>(\n  spec: MaterializedViewSpec<T>,\n): string {\n  if (!spec.window) return ''\n  const list = (v: unknown): string => {\n    if (v === undefined) return ''\n    const arr = Array.isArray(v) ? v : [v]\n    return arr\n      .map((k) =>\n        typeof k === 'object' && k !== null && 'field' in (k as Record<string, unknown>)\n          ? `${describeGroupKey((k as { field: GroupKey }).field)}:${String((k as { direction?: string }).direction ?? 'asc')}`\n          : describeGroupKey(k as GroupKey),\n      )\n      .join(',')\n  }\n  const selectKeys = Object.keys(spec.window.select).sort().join(',')\n  return `|window(partition(${list(spec.window.partitionBy)})order(${list(spec.window.orderBy)})select(${selectKeys}))`\n}\n\n/**\n * Shared `|groupBy(…)|aggregate(…)|money(…)` tail for the UNION and\n * projection summaries — both feed the same post-map grouping pipeline,\n * so the same spec fields fold into both hashes with the same rules.\n */\nfunction summarizeGroupingTail<T extends Record<string, unknown>>(\n  spec: MaterializedViewSpec<T>,\n): string {\n  // `describeGroupKey` is the identity of a group key: a plain field name maps\n  // to itself, and a `dateTrunc()` key (#1350) to a canonical string carrying\n  // every parameter that decides which bucket a row lands in. Changing a unit,\n  // a timezone or the week start therefore bumps the hash and forces a refresh.\n  const groupBy: string = Array.isArray(spec.groupBy)\n    ? spec.groupBy.map(describeGroupKey).sort().join(',')\n    : spec.groupBy === undefined\n      ? ''\n      : describeGroupKey(spec.groupBy as GroupKey)\n  const aggKeys = spec.aggregate ? Object.keys(spec.aggregate).sort().join(',') : ''\n  // `moneyFields` changes reducer semantics (float → exact BigInt), so\n  // declaring / removing / re-keying it must bump queryHash. Keys are\n  // sorted — they're independent of each other (one descriptor per\n  // output field), same rationale as aggregate keys.\n  const moneyKeys = spec.moneyFields ? Object.keys(spec.moneyFields).sort().join(',') : ''\n  return `|groupBy(${groupBy})|aggregate(${aggKeys})|money(${moneyKeys})${summarizeWindow(spec)}`\n}\n","/**\n * Deterministic hash of a materialized view strategy's \"shape\": MV\n * name + canonical query-plan summary + sorted dependency-set.\n *\n * Used to detect strategy drift: a row whose `_materializedFrom.queryHash`\n * doesn't match the current strategy is considered stale.\n *\n * Web Crypto SHA-256 — no extra deps. Mirrors the v1\n * `computeStrategyHash` pattern.\n */\nimport { sha256Hex } from '../../capsule/index.js'\n\nexport async function computeQueryHash(\n  mvName: string,\n  /**\n   * Source-collection set the query depends on. Sorted before\n   * canonicalization so set iteration order doesn't affect the hash.\n   */\n  dependencies: ReadonlySet<string>,\n  /**\n   * Stringified query-plan summary. The caller produces this from the\n   * `Query<T>` builder — concretely: a JSON serialization of clauses +\n   * orderBy + limit + offset + joins. Function bodies inside\n   * `wherePredicate` are NOT included here (those carry their own\n   * `predicateHash` to be folded in by a later sub-issue).\n   */\n  queryPlanSummary: string,\n): Promise<string> {\n  const canonical = JSON.stringify({\n    mvName,\n    dependencies: [...dependencies].sort(),\n    queryPlanSummary,\n  })\n  const bytes = new TextEncoder().encode(canonical)\n  return sha256Hex(bytes)\n}\n\n/**\n * Canonicalize a query plan for hashing. Walks the plan structure\n * with sorted keys so insertion order doesn't perturb the result.\n * Lives here rather than in `query/builder.ts` to keep that module\n * stable across MV-specific evolutions.\n *\n * @internal exported for testing\n */\nexport function canonicalizeQueryPlan(plan: unknown): string {\n  return JSON.stringify(plan, (_key, value) => {\n    if (value && typeof value === 'object' && !Array.isArray(value)) {\n      const sorted: Record<string, unknown> = {}\n      for (const k of Object.keys(value as Record<string, unknown>).sort()) {\n        sorted[k] = (value as Record<string, unknown>)[k]\n      }\n      return sorted\n    }\n    return value\n  })\n}\n","/**\n * Projection-leg topology (#810, extended by #1140).\n *\n * A projection MV's legs originally all attached to the PRIMARY row: a forward\n * leg named an FK field on `projection.source`, and a reverse `collect` leg's\n * `on` field had to `ref()` the source itself. Anything two FKs away was\n * therefore inexpressible — `bill → entity → client` has no leg shape, because\n * the bill has no `clientId` and `clients.entityId` refs `entities`, not\n * `bills`.\n *\n * `from` closes that: a leg may attach to a previously-declared ALIAS instead of\n * to the primary row. This module owns the two questions that follow from it —\n * *is this leg graph well-formed?* and *which collection does a leg's rows come\n * from?* — so neither the registry nor the executor has to re-derive them.\n *\n * **Why cycles are impossible by construction, and there is no depth cap.**\n * `from` may only name an alias declared EARLIER in `joins`. A leg can therefore\n * never reach forward, the graph is a forest rooted at the primary row, and its\n * depth is bounded by the number of legs. Validation refuses an unknown or\n * not-yet-declared alias, which is the same check.\n */\n\nimport { MaterializedViewConfigError } from '../../kernel/errors.js'\nimport type { ProjectionJoinLeg, ProjectionSpec } from './types.js'\n\n/** Reverse (one-to-many) leg — discriminated on `collect`, as the type is. */\nexport function isCollectLeg(\n  leg: ProjectionJoinLeg,\n): leg is Extract<ProjectionJoinLeg, { collect: string }> {\n  return 'collect' in leg\n}\n\n/**\n * Refuse a malformed leg graph where `withMaterializedView()` checks the rest of\n * the leg shape — at spec CONSTRUCTION, not at vault open and not at first\n * materialization. Alias wiring is pure configuration: it needs no refs, no\n * records and no store, so the earliest failure is the best one.\n * (Ref EXISTENCE still resolves at first materialization, unchanged — refs\n * cannot exist until after `openVault()` returns.)\n */\nexport function validateProjectionLegs<T extends Record<string, unknown>>(\n  mvName: string,\n  projection: ProjectionSpec<T>,\n): void {\n  // Non-empty and unique `as` are already refused by `withMaterializedView()`\n  // itself, earlier and with its own message — not re-checked here. This\n  // function owns the `from` wiring and nothing else.\n  const seen = new Map<string, ProjectionJoinLeg>()\n  for (const leg of projection.joins) {\n    if (leg.from !== undefined) {\n      const parent = seen.get(leg.from)\n      if (!parent) {\n        throw new MaterializedViewConfigError(\n          `\"${mvName}\": projection leg \"${leg.as}\" declares from: \"${leg.from}\", which is not an ` +\n            `alias declared EARLIER in \\`joins\\`. A leg may only attach to the primary row or to a ` +\n            `preceding leg — that ordering rule is what makes a cycle impossible. Known so far: ` +\n            `${[...seen.keys()].map(a => `\"${a}\"`).join(', ') || '(none)'}`,\n        )\n      }\n      if (isCollectLeg(parent)) {\n        throw new MaterializedViewConfigError(\n          `\"${mvName}\": projection leg \"${leg.as}\" declares from: \"${leg.from}\", but \"${leg.from}\" ` +\n            `is a collect leg and holds an ARRAY of rows, not one record. A leg can only hang off a ` +\n            `forward leg (record | null). Attach it to the primary row instead, or collect the ` +\n            `far side directly if its ref() reaches \"${projection.source}\".`,\n        )\n      }\n    }\n    seen.set(leg.as, leg)\n  }\n}\n\n/**\n * The collection a leg's rows come from — the primary source for a root leg, the\n * `from` leg's own target otherwise.\n *\n * Returns `null` when a forward `ref()` somewhere along the chain is not\n * declared yet, which at registration time is the normal case rather than an\n * error: refs are declared after `openVault()` returns, so the registry retries\n * this on every dispatch until it resolves (`_pendingForwardDeps`).\n *\n * `resolveRef` is passed in rather than imported so this module stays free of\n * vault wiring — the registry hands it the ref registry's `getOutbound`, the\n * executor hands it a join context lookup. Both answer the same question.\n */\nexport type RefLookup = (collection: string, field: string) => { target: string } | null\n\nexport function resolveLegOwner(\n  leg: ProjectionJoinLeg,\n  joins: ReadonlyArray<ProjectionJoinLeg>,\n  source: string,\n  resolveRef: RefLookup,\n): string | null {\n  if (leg.from === undefined) return source\n  const parent = joins.find(l => l.as === leg.from)\n  if (!parent) return null // refused by validateProjectionLegs; defensive here\n  if (isCollectLeg(parent)) return parent.collect // refused too, same reason\n  const parentOwner = resolveLegOwner(parent, joins, source, resolveRef)\n  if (parentOwner === null) return null\n  return resolveRef(parentOwner, parent.field)?.target ?? null\n}\n\n/**\n * The collection a FORWARD leg resolves INTO — i.e. its dependency. `null` while\n * any ref in the chain (including this leg's own) is still undeclared.\n */\nexport function resolveForwardLegTarget(\n  leg: Extract<ProjectionJoinLeg, { field: string }>,\n  joins: ReadonlyArray<ProjectionJoinLeg>,\n  source: string,\n  resolveRef: RefLookup,\n): string | null {\n  const owner = resolveLegOwner(leg, joins, source, resolveRef)\n  if (owner === null) return null\n  return resolveRef(owner, leg.field)?.target ?? null\n}\n","import { MaterializedViewSourceUnknownError, RefNotDeclaredError } from '../../kernel/errors.js'\nimport type { ViaGraph, FieldRef, EdgeKind, Grain } from '../../kernel/via/graph.js'\nimport type { Clause, FieldClause } from '../../kernel/query/predicate.js'\nimport type { DeclaredPredicate } from '../../kernel/query/builder.js'\nimport { analyzeDependencies, summarizeQueryPlan, summarizeUnionPlan, summarizeProjectionPlan } from './dependency-analyzer.js'\nimport { computeQueryHash } from './query-hash.js'\nimport { isCollectLeg, resolveForwardLegTarget } from './projection-legs.js'\nimport type { MaterializedViewSpec, MVQueryContext } from './types.js'\n\n/**\n * Whole-record artifact-grain field marker (#638 Task 2) — MUST match\n * `derivations/registry.ts`'s and `vault.ts`'s overlay-edge marker so\n * cross-registry edges (a derivation feeding an MV, or vice versa) resolve\n * to the SAME graph node. See that file's `WHOLE_RECORD` doc comment.\n */\nconst WHOLE_RECORD = '*'\n\n/**\n * One registered MV strategy alongside its derived metadata. Stored\n * type-erased on `TRow` so the registry can hold heterogeneous MVs.\n */\nexport interface RegisteredMV {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  readonly spec: MaterializedViewSpec<any>\n  /** Output collection name (`spec.output?.collection ?? spec.name`). */\n  readonly outputCollection: string\n  /** Set of source collections; populated at registration via the analyzer. */\n  readonly dependencies: ReadonlySet<string>\n  /** Canonical `queryHash` — `_materializedFrom.queryHash` for every emitted row. */\n  readonly queryHash: string\n  /**\n   * Top-level FieldClauses on the partition field, captured at\n   * registration time. Used by the cycle detector to resolve\n   * same-collection-as-source edges via the partition-discriminator\n   * check. Empty when `spec.output?.partition` is undefined.\n   */\n  readonly partitionClauses: readonly FieldClause[]\n  /**\n   * #638 Task 2 — `'record'` for a row-per-source-row Query<T> or\n   * `unionSources` MV, `'aggregate'` for a `.groupBy().aggregate()` MV\n   * (the shape that requires explicit `sources`, since the dependency\n   * analyzer can't walk an aggregate plan). Feeds `edges()`'s grain.\n   */\n  readonly grain: Grain\n}\n\n/**\n * Vault-internal registry of MV strategies. Owned by `Vault`; not\n * exported. Parallel to v1's `DerivationRegistry`; the two graphs share\n * a single cycle-detection pass at vault open (see `validate`).\n *\n * @internal\n */\nexport class MaterializedViewRegistry {\n  /** Keyed by `spec.name`. */\n  private readonly _byName = new Map<string, RegisteredMV>()\n  /** Keyed by dependency source-collection → MVs that depend on it. */\n  private readonly _bySource = new Map<string, RegisteredMV[]>()\n  /**\n   * Projection MVs (#810) whose forward-leg ref() targets could not be\n   * resolved at registration time. A forward leg names only the FK\n   * FIELD; its dependency is the field's ref() TARGET, declared on the\n   * source collection — but registration runs at vault open, BEFORE\n   * user code declares collections (and their refs). Constructing the\n   * source collection here to look them up would be worse: a later\n   * `vault.collection(source, { refs })` call only registers refs on a\n   * cache miss, so an early construction would silently drop them.\n   * Instead each entry carries a non-constructive ref-registry probe;\n   * `mvsForSource` retries on every dispatch until every forward\n   * target has resolved (see `_resolvePendingForwardDeps`).\n   */\n  private readonly _pendingForwardDeps: Array<{\n    reg: RegisteredMV\n    /** Forward-leg ALIASES still awaiting resolution (#1140 — a leg is identified\n     *  by its alias, not its field: with `from`, two legs may name the same FK\n     *  field on different collections). */\n    aliases: Set<string>\n    resolveTarget: (alias: string) => string | null\n  }> = []\n\n  /**\n   * Query-form strategies whose `query()` callback could not be planned at\n   * registration time because a `.join()` names a field whose `ref()` is not\n   * declared YET (#1139).\n   *\n   * Registration runs inside `openVault()`; a collection's refs can only be\n   * declared afterwards, so for a query-form MV that joins a declared FK there\n   * is NO call ordering the consumer can choose — the plan is simply built too\n   * early. Rather than failing the vault open, the strategy is parked here and\n   * replanned from {@link resolvePendingPlans}, which every write dispatch and\n   * `vault.refreshView()` call runs first. This is the query-form counterpart\n   * of `_pendingForwardDeps`, one level up: that defers a leg's TARGET, this\n   * defers the whole plan.\n   *\n   * Only `RefNotDeclaredError` parks a strategy. Every other planning failure\n   * still throws out of `openVault()` exactly as before, so a typo'd source or\n   * a malformed spec keeps its loud, early error.\n   *\n   * A parked strategy is invisible until it resolves: it contributes no\n   * `_bySource` entries and no cycle-detection edges (same caveat as a\n   * late-resolved forward target — `edges()` runs once at vault open). It also\n   * cannot be dispatched, which is why {@link hasPendingPlans} forces the\n   * conservative branch in `Collection._txAtomicSafe`: the atomic write path\n   * skips MV dispatch, and skipping it here would mean the write that was\n   * supposed to trigger the first replan is the one that gets missed.\n   */\n  private readonly _pendingPlans: Array<{\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    spec: MaterializedViewSpec<any>\n    db: MVQueryContext\n    options?: { knownCollections?: (name: string) => boolean }\n  }> = []\n\n  /**\n   * Register an MV. Invokes `spec.query()` once at registration time to\n   * read the plan + join context; the resulting `Query<T>` is discarded\n   * after dependency extraction. `vault.collection(...)` must therefore\n   * be functional by the time this runs — typically wired from\n   * `Vault._initMaterializedViews` after collection bootstrap.\n   *\n   * Throws `MaterializedViewSourceUnknownError` if the analyzer\n   * surfaces a dependency the vault doesn't know about (when a\n   * `knownCollections` checker is supplied).\n   */\n  async register(\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    spec: MaterializedViewSpec<any>,\n    db: MVQueryContext,\n    options?: { knownCollections?: (name: string) => boolean },\n  ): Promise<void> {\n    // Build a predicate-aware db wrapper. If `spec.predicates` is\n    // declared, the wrapper intercepts `.collection().query()` and\n    // attaches the predicates map to the resulting Query<T>. With no\n    // predicates declared, the wrapper is the original db unchanged.\n    const ungatedDb = ungatedMvContext(db) // #1414 — the engine keeps its pre-gate source; see ungatedMvContext\n    const dbForQuery = spec.predicates ? wrapDbWithPredicates(ungatedDb, spec.predicates) : ungatedDb\n\n    // Invoke the query callback once to inspect its plan / dependencies.\n    // For Query<T> shapes the analyzer extracts deps + plan summary\n    // automatically. Reduction / GroupedReduction shapes don't\n    // expose the underlying Query, so the spec must declare `sources`\n    // explicitly. `partitionClauses` are only populated for Query<T>\n    // since same-collection-partition is a non-aggregate concern.\n    // UNION-form strategies: dependencies and plan summary come\n    // straight off the strategy — no `query` callback to introspect.\n    // The dependency-analyzer + summarizer are bypassed entirely; the\n    // executor handles materialization via `materializeUnionResult`.\n    let dependencies: Set<string>\n    let queryPlanSummary: string\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    let qAny: any = null\n    let isQuery = false\n    // Projection-form (#810): forward legs whose ref() target wasn't\n    // resolvable at registration time — folded in lazily, see\n    // `_pendingForwardDeps`.\n    const pendingForwardFields: string[] = []\n    if (spec.unionSources) {\n      dependencies = new Set(spec.unionSources.map(s => s.collection))\n      // Per-arm joins resolve right-side collections that aren't among\n      // the arm `collection`s. The consumer lists those in `sources`;\n      // fold them into the dependency set so a write to a join-target\n      // collection triggers MV refresh (and contributes a cycle edge).\n      if (spec.sources) for (const s of spec.sources) dependencies.add(s)\n      // #1411 — a declared join names its target literally, so it needs no\n      // `sources` entry to be a dependency (a ref join's target is only known\n      // once the ref is declared, which is why THOSE must be listed).\n      for (const arm of spec.unionSources) for (const leg of arm.join ?? []) if ('on' in leg) dependencies.add(leg.target)\n      queryPlanSummary = summarizeUnionPlan(spec)\n    } else if (spec.projection) {\n      // Projection-form (#810): dependencies are all AUTO — the primary\n      // source, every collect leg's collection (both literal names), and\n      // every forward leg's ref() target. Forward targets usually can't\n      // resolve yet (refs are declared after vault open) — those go\n      // through the pending-resolution path below. Explicit `sources`\n      // remains additive, same as the other two forms.\n      const projection = spec.projection\n      dependencies = new Set([projection.source])\n      for (const leg of projection.joins) {\n        // A collect leg's dependency is its literal collection name, whatever it\n        // attaches to — which is why `from` needs no new dependency machinery on\n        // that side. A forward leg's dependency is a ref() target, still unknown.\n        if (isCollectLeg(leg)) dependencies.add(leg.collect)\n        else pendingForwardFields.push(leg.as)\n      }\n      if (spec.sources) for (const s of spec.sources) dependencies.add(s)\n      queryPlanSummary = summarizeProjectionPlan(spec)\n    } else {\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      let q: any\n      try {\n        q = spec.query!(dbForQuery)\n      } catch (e) {\n        // #1139 — a join on a ref that is not declared YET. Park and replan;\n        // see `_pendingPlans`. Anything else is a real registration failure.\n        if (!(e instanceof RefNotDeclaredError)) throw e\n        this._pendingPlans.push({ spec, db, ...(options !== undefined ? { options } : {}) })\n        return\n      }\n      qAny = q // already `any` — see the declaration above\n      isQuery = typeof qAny._plan === 'function'\n      if (isQuery) {\n        // `q` is the `Query` arm of the union here (runtime-confirmed via\n        // `qAny._plan` above); reuse the already-`any` `qAny` the block uses\n        // for `_plan()` rather than re-narrowing.\n        dependencies = analyzeDependencies(qAny)\n        queryPlanSummary = summarizeQueryPlan(qAny)\n        // Fold `.wherePredicate(name, ctx)` references into the plan\n        // summary so predicate function or ctx changes (signalled by\n        // bumping `hash` or supplying a different ctx) propagate into\n        // `queryHash` and force refresh on next visit.\n        const predicateRefs = extractPredicateRefs(qAny._plan())\n        if (predicateRefs.length > 0) {\n          queryPlanSummary = JSON.stringify({ plan: queryPlanSummary, predicates: predicateRefs })\n        }\n        // If `sources` is ALSO declared, take the union (consumer's\n        // explicit list extends the auto-analyzed set).\n        if (spec.sources) for (const s of spec.sources) dependencies.add(s)\n      } else {\n        // Aggregate shape: require explicit `sources`.\n        if (!spec.sources || spec.sources.length === 0) {\n          throw new Error(\n            `withMaterializedView \"${spec.name}\": query() returned an aggregate ` +\n              `(Reduction or GroupedReduction) but no \\`sources\\` field is declared. ` +\n              `The dependency analyzer cannot walk through groupBy().aggregate() ` +\n              `back to the source — declare sources: [...] explicitly.`,\n          )\n        }\n        dependencies = new Set(spec.sources)\n        // Aggregate plans don't carry a chainable query plan for summary\n        // purposes; the dep-set + spec.name serve as the queryHash inputs.\n        queryPlanSummary = JSON.stringify({ aggregate: true, sources: [...spec.sources].sort() })\n      }\n    }\n\n    // Sanity-check declared dependencies against the vault's known\n    // collections. Optional — when the checker isn't supplied (test\n    // wiring, in-process composition) the registration succeeds and\n    // any typo surfaces at first onSourceWrite as a no-op.\n    if (options?.knownCollections) {\n      for (const dep of dependencies) {\n        if (!options.knownCollections(dep)) {\n          throw new MaterializedViewSourceUnknownError(spec.name, dep)\n        }\n      }\n    }\n\n    const outputCollection = spec.output?.collection ?? spec.name\n    const queryHash = await computeQueryHash(spec.name, dependencies, queryPlanSummary)\n    // For same-collection-as-source MVs, capture the where-clauses on\n    // the partition field so cycle detection can prove disjointness.\n    // Only applicable to Query<T> shapes — aggregate MVs don't carry\n    // a chainable plan to inspect (and same-collection aggregation\n    // doesn't make sense for same-collection aggregation).\n    const partitionClauses: FieldClause[] = []\n    const partitionField = spec.output?.partition?.field\n    if (partitionField !== undefined && isQuery) {\n      const plan = qAny._plan()\n      for (const clause of plan.clauses) {\n        if (isFieldClauseOnField(clause, partitionField)) partitionClauses.push(clause)\n      }\n    }\n    // #638 Task 2 — 'aggregate' only for the explicit-sources aggregate shape\n    // (groupBy().aggregate() with no chainable plan); a row-per-source-row\n    // Query<T>, unionSources, or projection MV is 'record'.\n    const grain: Grain = spec.unionSources || spec.projection || isQuery ? 'record' : 'aggregate'\n    const reg: RegisteredMV = { spec, outputCollection, dependencies, queryHash, partitionClauses, grain }\n\n    this._byName.set(spec.name, reg)\n    for (const dep of dependencies) {\n      const arr = this._bySource.get(dep)\n      if (arr) arr.push(reg)\n      else this._bySource.set(dep, [reg])\n    }\n    if (pendingForwardFields.length > 0) {\n      // Non-constructive ref-registry probe: the Vault (the real\n      // MVQueryContext) carries its RefRegistry as a private field,\n      // reachable structurally at runtime. Test stubs without one simply\n      // never resolve — forward deps then come only from explicit `sources`.\n      const refRegistry = (db as unknown as {\n        refRegistry?: { getOutbound(collection: string): Record<string, { target: string }> }\n      }).refRegistry\n      const projectionSpec = spec.projection!\n      const resolveRef = (c: string, f: string): { target: string } | null =>\n        refRegistry?.getOutbound(c)[f] ?? null\n      this._pendingForwardDeps.push({\n        reg,\n        aliases: new Set(pendingForwardFields),\n        resolveTarget: (alias) => {\n          const leg = projectionSpec.joins.find(l => l.as === alias)\n          if (!leg || isCollectLeg(leg)) return null\n          // Walks the `from` chain — every hop needs its own ref declared, so a\n          // two-hop leg simply resolves one dispatch later than a one-hop one.\n          return resolveForwardLegTarget(leg, projectionSpec.joins, projectionSpec.source, resolveRef)\n        },\n      })\n      // Immediate attempt — covers refs already declared by the time\n      // this MV registers (re-registration flows, test wiring).\n      this._resolvePendingForwardDeps()\n    }\n  }\n\n  /**\n   * `true` while any query-form strategy is still unplanned (#1139). Read by\n   * `Collection._txAtomicSafe`, which must refuse the atomic write path while\n   * this holds — see the `_pendingPlans` doc comment for why.\n   */\n  hasPendingPlans(): boolean {\n    return this._pendingPlans.length > 0\n  }\n\n  /**\n   * Replan every parked query-form strategy (#1139). Called at the head of both\n   * write dispatchers and of `vault.refreshView()`, so a strategy resolves on the\n   * first write or refresh after its source collection's refs are declared —\n   * which is the earliest moment it could produce a correct plan, and strictly\n   * before the first moment it could have any output to produce.\n   *\n   * Each entry is handed straight back to {@link register}, so a strategy that\n   * is STILL unplannable simply re-parks itself and the next dispatch tries\n   * again. Idempotent and cheap: the array empties as strategies resolve, and\n   * both callers skip the await entirely once it is empty.\n   *\n   * A late-resolved strategy does NOT retro-feed `edges()` — the unified cycle\n   * pass runs once at vault open, before refs exist. Same caveat, and the same\n   * reason, as a late-resolved forward-leg target.\n   */\n  async resolvePendingPlans(): Promise<void> {\n    if (this._pendingPlans.length === 0) return\n    // Splice first: `register` re-parks anything still unplannable, and reading\n    // a live array it is concurrently pushing to would loop.\n    const parked = this._pendingPlans.splice(0)\n    for (const entry of parked) {\n      await this.register(entry.spec, entry.db, entry.options)\n    }\n  }\n\n  /** All MVs that depend on `source`, in registration order. */\n  mvsForSource(source: string): ReadonlyArray<RegisteredMV> {\n    if (this._pendingForwardDeps.length > 0) this._resolvePendingForwardDeps()\n    return this._bySource.get(source) ?? []\n  }\n\n  /**\n   * Retry ref() resolution for every pending projection forward leg\n   * (#810). A field resolves once its source collection's refs have\n   * been declared; the target then folds into the owning MV's\n   * dependency set and `_bySource`, so subsequent writes to it\n   * dispatch a refresh. Idempotent and cheap — the pending list\n   * empties as fields resolve, and `mvsForSource` skips the call\n   * entirely once it's empty.\n   *\n   * Late-resolved targets do NOT retro-feed `edges()` — the cycle\n   * pass runs once at vault open, before refs exist. A cycle routed\n   * exclusively through a forward leg is therefore not detected at\n   * open (collect + source edges, the literal names, are).\n   */\n  private _resolvePendingForwardDeps(): void {\n    for (let i = this._pendingForwardDeps.length - 1; i >= 0; i--) {\n      const entry = this._pendingForwardDeps[i]!\n      for (const alias of [...entry.aliases]) {\n        const target = entry.resolveTarget(alias)\n        if (target === null) continue\n        entry.aliases.delete(alias)\n        if (entry.reg.dependencies.has(target)) continue\n        // `dependencies` is declared ReadonlySet for consumers; the\n        // registry owns the underlying Set and is the one writer.\n        ;(entry.reg.dependencies as Set<string>).add(target)\n        const arr = this._bySource.get(target)\n        if (arr) arr.push(entry.reg)\n        else this._bySource.set(target, [entry.reg])\n      }\n      if (entry.aliases.size === 0) this._pendingForwardDeps.splice(i, 1)\n    }\n  }\n\n  /** Single MV by name, or `undefined`. */\n  byName(name: string): RegisteredMV | undefined {\n    return this._byName.get(name)\n  }\n\n  /** Iterate over every registered MV. */\n  all(): ReadonlyArray<RegisteredMV> {\n    return [...this._byName.values()]\n  }\n\n  /**\n   * Graph edges for #638 Task 2: one `'mv'` edge per registered MV — target\n   * = the output collection (a `WHOLE_RECORD` artifact node), sources =\n   * every dependency (also `WHOLE_RECORD` nodes). Same-collection edges\n   * (`dep === outputCollection`) are skipped IFF the MV declares an\n   * `output.partition` discriminator AND the query has a where-clause that\n   * provably excludes the partition value (`partitionDisjoint`) — the SAME\n   * condition the old local DFS used. Grain comes from the registration-time\n   * `RegisteredMV.grain`.\n   */\n  edges(): ReadonlyArray<{ readonly target: FieldRef; readonly sources: readonly FieldRef[]; readonly kind: EdgeKind; readonly grain: Grain }> {\n    const out: Array<{ target: FieldRef; sources: FieldRef[]; kind: EdgeKind; grain: Grain }> = []\n    for (const reg of this._byName.values()) {\n      const sources: FieldRef[] = []\n      for (const dep of reg.dependencies) {\n        if (dep === reg.outputCollection && partitionDisjoint(reg)) continue\n        sources.push({ collection: dep, field: WHOLE_RECORD })\n      }\n      if (sources.length === 0) continue\n      out.push({ target: { collection: reg.outputCollection, field: WHOLE_RECORD }, sources, kind: 'mv', grain: reg.grain })\n    }\n    return out\n  }\n\n  /**\n   * Cycle detection, delegated to `ViaGraph.assertAcyclic()` (#638 Task 2 —\n   * retires the local DFS). `graph` is the caller's shared per-vault graph,\n   * ALREADY carrying this registry's `edges()` AND `DerivationRegistry`'s\n   * (registered by the caller — see `Vault._initMaterializedViews`, which\n   * runs after `_initDerivations`, so a pure-derivation cycle already threw\n   * `DerivationCycleError` there; any cycle surfacing here necessarily\n   * touches an MV edge). Throws `MaterializedViewCycleError` — SAME class as\n   * before.\n   */\n  validate(graph: ViaGraph): void {\n    graph.assertAcyclic()\n  }\n}\n\n/**\n * Type guard: is the clause a top-level `FieldClause` on the given\n * field? Used by the partition-disjoint check.\n *\n * @internal\n */\nfunction isFieldClauseOnField(clause: Clause, field: string): clause is FieldClause {\n  return clause.type === 'field' && clause.field === field\n}\n\n/**\n * #1414 — wrap an `MVQueryContext` so its `.collection().query()` returns a\n * query with the cold-collection gate removed.\n *\n * The MV engine reads its sources synchronously: registration inspects the\n * plan the spec callback returns, and the executor's scan runs from inside a\n * write commit. Both predate #1414 and both have always read whatever the\n * in-memory cache held. Gating them would convert a pre-existing (and\n * separately tracked) staleness into a thrown error on a write path nobody\n * pointed at a query — so the engine keeps its old source and #1414's change\n * stays on the surface a consumer or a guard actually calls.\n *\n * @internal\n */\nexport function ungatedMvContext(db: MVQueryContext): MVQueryContext {\n  return {\n    // ⚠️ Every argument is forwarded. A spec's `db.collection(name, { tiers })`\n    // supplies the options at FIRST construction (first-construction wins), so\n    // a wrapper that drops the second argument silently un-declares them.\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    collection(name: string, ...rest: any[]): any {\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      const c = (db.collection as any)(name, ...rest) as Record<string | symbol, unknown>\n      return new Proxy(c, {\n        get(target, prop, receiver) {\n          if (prop === 'query') {\n            return (...args: unknown[]) => {\n              // eslint-disable-next-line @typescript-eslint/no-explicit-any\n              const q = (target.query as any)(...args)\n              // The legacy predicate overload returns `T[]`, not a Query.\n              return q && typeof q._ungated === 'function' ? q._ungated() : q\n            }\n          }\n          return Reflect.get(target, prop, receiver)\n        },\n      })\n    },\n  }\n}\n\n/**\n * Wrap an `MVQueryContext` so its `.collection().query()` returns a\n * Query<T> with the MV's declared predicates attached. Bare Queries\n * (outside of any MV) don't gain `.wherePredicate()` — only Queries\n * obtained through this wrapped db do.\n *\n * @internal\n */\nexport function wrapDbWithPredicates(\n  db: MVQueryContext,\n  predicates: NonNullable<MaterializedViewSpec<Record<string, unknown>>['predicates']>,\n): MVQueryContext {\n  // Build the predicate map once — the fn signature in the MV spec\n  // is row-typed but the QueryBuilder casts to unknown, so we widen\n  // here for the Map.\n  const map = new Map<string, DeclaredPredicate>()\n  for (const [name, decl] of Object.entries(predicates)) {\n    map.set(name, {\n      hash: decl.hash,\n      fn: decl.fn as (record: unknown, ctx?: unknown) => boolean,\n    })\n  }\n  return {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    collection<T extends Record<string, unknown>>(name: string): any {\n      const c = db.collection<T>(name)\n      // Return an object that delegates everything to `c` but\n      // overrides `.query()` to attach predicates via the new\n      // `Query._withPredicates()` accessor.\n      return new Proxy(c, {\n        get(target, prop, receiver) {\n          if (prop === 'query') {\n            return (...args: unknown[]) => {\n              // eslint-disable-next-line @typescript-eslint/no-explicit-any\n              const q = (target.query as any)(...args)\n              // For non-aggregate Query<T>, attach predicates. For\n              // legacy predicate-arg overload that returns T[] (sync\n              // filter), pass through unchanged.\n               \n              if (q && typeof q._withPredicates === 'function') {\n                return q._withPredicates(map)\n              }\n              return q\n            }\n          }\n          return Reflect.get(target, prop, receiver)\n        },\n      })\n    },\n  }\n}\n\n/**\n * Walk a QueryPlan's clauses and collect predicate-reference markers\n * for `queryHash` derivation. Returns a sorted array (deterministic\n * order) of `{ name, predicateHash, ctxHash }` tuples — these are the\n * hashable identity of each `.wherePredicate()` call site.\n *\n * @internal\n */\nfunction extractPredicateRefs(\n  plan: { clauses: readonly Clause[] },\n): Array<{ name: string; predicateHash: string; ctxHash: string }> {\n  const refs: Array<{ name: string; predicateHash: string; ctxHash: string }> = []\n  const walk = (clauses: readonly Clause[]): void => {\n    for (const c of clauses) {\n      if (c.type === 'wherePredicate') {\n        refs.push({ name: c.name, predicateHash: c.predicateHash, ctxHash: c.ctxHash })\n      } else if (c.type === 'group') {\n        walk(c.clauses)\n      }\n    }\n  }\n  walk(plan.clauses)\n  // Stable-sort by (name, predicateHash, ctxHash) — same predicate\n  // appearing twice with different ctx hashes both flow through.\n  refs.sort((a, b) => {\n    if (a.name !== b.name) return a.name < b.name ? -1 : 1\n    if (a.predicateHash !== b.predicateHash) return a.predicateHash < b.predicateHash ? -1 : 1\n    return a.ctxHash < b.ctxHash ? -1 : a.ctxHash > b.ctxHash ? 1 : 0\n  })\n  return refs\n}\n\n/**\n * Provability check for the same-collection partition-discriminator.\n * Returns `true` when\n * the captured partition clauses on the MV's query provably exclude\n * the partition's value — meaning the input filter and the output\n * partition are disjoint and the same-collection edge isn't really a\n * cycle.\n *\n * Supported provability shapes (narrow on purpose — DERIV-PP30-001\n * is the load-bearing case):\n *\n * - `.where(field, '==', X)` where X !== partition.value → disjoint\n * - `.where(field, '!=', partition.value)` → disjoint\n * - `.where(field, 'in', [...])` where partition.value NOT in list → disjoint\n *\n * Anything else (no clause on the partition field, an 'in' list that\n * contains partition.value, unsupported operators) → not disjoint,\n * the cycle detector surfaces `MaterializedViewCycleError`.\n *\n * @internal\n */\nfunction partitionDisjoint(reg: RegisteredMV): boolean {\n  const partition = reg.spec.output?.partition\n  if (partition === undefined) return false\n  const value = partition.value\n  // The OR-semantics of multiple where-clauses on the same field\n  // would muddy this check. v2 only treats AND-chained clauses;\n  // any clause that proves disjoint is sufficient.\n  for (const c of reg.partitionClauses) {\n    if (c.op === '==' && c.value !== value) return true\n    if (c.op === '!=' && c.value === value) return true\n    if (c.op === 'in' && Array.isArray(c.value)) {\n      const list = c.value as readonly unknown[]\n      if (!list.includes(value)) return true\n    }\n  }\n  return false\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/with-formula/materialized-views/dependency-analyzer.ts","../src/with-formula/materialized-views/query-hash.ts","../src/with-formula/materialized-views/projection-legs.ts","../src/with-formula/materialized-views/registry.ts"],"sourcesContent":["import { describeGroupKey, type GroupKey } from '../../kernel/query/reduce/date-trunc.js'\nimport type { Query, QueryPlan } from '../../kernel/query/builder.js'\nimport type { JoinContext, JoinLeg } from '../../kernel/query/relate/join.js'\nimport type { MaterializedViewSpec } from './types.js'\nimport { normalizeJoinOn } from '../../kernel/query/relate/join-on.js'\n\n/**\n * Walks a `Query<T>` plan and returns the set of source collection\n * names that any source-write should trigger a refresh on.\n *\n * Handles:\n *   - root collection (the one the query was built from)\n *   - FK join targets (`.join(field, { as })`)\n *\n * Also handles:\n *   - cross-join targets (`.crossJoin(target, { as })`) — v3\n *\n * Deferred:\n *   - `.wherePredicate(name)` — v2 predicate primitive\n *   - Overlay-name expansion to {base, overlay}\n *\n * The set is materialized at MV registration time. The MV registry\n * uses it to (a) dispatch `onSourceWrite` only to MVs that actually\n * care, and (b) contribute edges to the shared cycle-detection graph.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function analyzeDependencies(query: Query<any>): Set<string> {\n  const deps = new Set<string>()\n  const plan = query._plan()\n  const ctx = query._joinContext()\n\n  // The root collection is always a dependency.\n  if (ctx?.leftCollection) {\n    deps.add(ctx.leftCollection)\n  }\n\n  // FK join targets contribute additional sources.\n  for (const leg of plan.joins) {\n    deps.add(leg.target)\n  }\n\n  // Cross-join targets are also dependency sources — writes to either side\n  // must trigger MV refresh. Symmetric with FK-join target handling above.\n  for (const clause of plan.clauses) {\n    if (clause.type === 'crossJoin') {\n      deps.add(clause.target)\n    }\n  }\n\n  // Sub-plans inside OR clauses can carry nested joins. Walk them.\n  // (Today only top-level `.join()` populates `plan.joins`, but the\n  // OR-group machinery permits sub-plans, so we recurse defensively.)\n  walkClausesForJoins(plan, deps, ctx)\n\n  return deps\n}\n\nfunction walkClausesForJoins(\n  plan: QueryPlan,\n  deps: Set<string>,\n  ctx: JoinContext | undefined,\n): void {\n  void ctx\n  // Today `plan.joins` carries all join legs at top level. Sub-plans\n  // inside OR groups don't currently support nested joins, so the loop\n  // below is a no-op safety net for future builder extensions.\n  for (const clause of plan.clauses) {\n    if (clause.type === 'group') {\n      // Group clauses don't (yet) carry their own joins; this is a\n      // forward-compat anchor for when OR-groups support nested\n      // sources.\n    }\n  }\n}\n\n/**\n * Convenience: produce a stable string summary of the query plan\n * suitable for `queryHash` derivation. Captures everything the\n * dependency analyzer reads + the where/orderBy/limit/offset\n * structure that affects materialized rows.\n *\n * `joinContext` is intentionally NOT included — the join-resolution\n * function references would defeat hash determinism. The set of join\n * TARGETS (collection names) IS included via the plan.joins legs.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function summarizeQueryPlan(query: Query<any>): string {\n  const plan = query._plan()\n  const ctx = query._joinContext()\n  return JSON.stringify({\n    root: ctx?.leftCollection ?? null,\n    clauses: plan.clauses.map(c => {\n      if (c.type === 'crossJoin') {\n        return {\n          type: 'crossJoin',\n          target: c.target,\n          as: c.as,\n          // Inline on: callback: use sentinel — drift detection disabled for this MV\n          onPredicateName: c.onPredicateName ?? (c.on ? '[inline]' : null),\n          maxRows: c.maxRows ?? null,\n          // `outer` changes the row set, so it is part of the plan's identity\n          // for drift detection, not decoration (#1130).\n          outer: c.outer ?? false,\n        }\n      }\n      return c\n    }),\n    orderBy: plan.orderBy,\n    limit: plan.limit ?? null,\n    offset: plan.offset,\n    joins: plan.joins.map(j => summarizeJoinLeg(j)),\n  })\n}\n\n/**\n * The per-leg half of {@link summarizeQueryPlan}, split out so the property\n * test in `__tests__/query-join-summary-hash.test.ts` can address it directly.\n *\n * ⭐ **THE RULE FOR GROWING THIS FUNCTION (#1389).** Every key here is inside\n * an already-stored `queryHash`. A key that is emitted unconditionally can\n * never be added, removed, or renamed without moving EVERY joined MV's hash\n * and silently recomputing every one of them. A key that is OMITTED AT ITS\n * DEFAULT can: `JSON.stringify` drops an `undefined` value, so a leg that does\n * not use the feature summarises byte-identically to its pre-change self and\n * only the MVs genuinely using the feature recompute — once, correctly.\n * So: **new keys are omitted at their default, always.** Pinned by the\n * byte-identity test in that file.\n *\n * ⛔ And the converse duty, which is what #1389 actually was: a `JoinLeg` field\n * that changes WHICH ROWS the leg produces and is NOT emitted here makes two\n * semantically different MVs share a hash, so drift detection goes blind and\n * nothing reports it. `direction`, `inner` and `isDictJoin` were all in that\n * state. The exclusion list below is deliberate and each entry states why;\n * the property test fails if a new `JoinLeg` key appears in neither.\n */\nfunction summarizeJoinLeg(j: JoinLeg): Record<string, unknown> {\n  return {\n    field: j.field,\n    as: j.as,\n    target: j.target,\n    mode: j.mode,\n    // #1339 — the declared `on` IS the join's identity: two `.joinOn()`\n    // plans differing only here select different rows, and without this key\n    // they would hash identically and neither MV would ever be seen as\n    // stale. `undefined` for every other leg, and `JSON.stringify` drops an\n    // undefined value, so a plan carrying no `joinOn` summarises\n    // byte-identically to its pre-#1339 self and no stored hash moves.\n    on: j.on,\n    // #1389 — `direction` (#1289) decides which SIDE is preserved: a right or\n    // full leg emits rows a left leg never produces. Omitted for a left leg,\n    // which is `undefined` on the leg itself, so a plain `.join()` plan is\n    // byte-identical to its pre-#1389 summary.\n    direction: j.direction,\n    // #1389 — `inner` (#1361) DROPS every unmatched left row. Only ever\n    // `true`; `undefined` on every other leg, so again nothing moves for a\n    // plan that does not use it.\n    inner: j.inner,\n    // #1389 — a dict join attaches `{ ...labels, key }` from the dictionary\n    // snapshot instead of a right-side record, and `target` names a\n    // dictionary rather than a collection. Two legs can otherwise agree on\n    // all four base keys (a dict leg's `target` IS its `field`, which a ref\n    // join to a like-named collection reproduces), so without this key they\n    // hash identically while materializing different rows. Only ever `true`.\n    isDictJoin: j.isDictJoin,\n    // ── EXCLUDED, deliberately (#1389). Read before adding one. ──────────\n    //\n    // `partitionScope` — NOT emitted, and this is the load-bearing one. It is\n    //   `'all'` on every leg ever built and the executor never reads it\n    //   (#1342), so it cannot change a row. It is also present unconditionally\n    //   rather than omitted-at-default, so starting to emit it would move\n    //   EVERY joined MV's hash at once for zero semantic gain. If a future\n    //   change ever makes it narrowable, emit it only when it is not `'all'`.\n    //\n    // `strategy` — NOT emitted: a manual planner override picks HOW the same\n    //   rows are produced (hash vs lookup), never which. Emitting it would\n    //   force a full recompute for a pure performance tweak.\n    //\n    // `maxRows` — NOT emitted: a per-side ceiling that throws\n    //   `JoinTooLargeError` when crossed. A query that succeeds returns the\n    //   same rows at any ceiling above its size, so it is not part of the\n    //   plan's row identity.\n  }\n}\n\n/**\n * Canonical string description of a UNION MV's plan, used as input to\n * `computeQueryHash`.\n *\n * Asymmetry note:\n *   - Arm collection names are NOT sorted. Declaration order is\n *     semantically meaningful for the dedup-only UNION path —\n *     `materializeUnionResult` iterates `spec.unionSources` in\n *     declaration order and keeps the first-seen row per composite key\n *     (tie-break precedence). If we sorted arms here, a consumer who\n *     reordered `unionSources` to change precedence would compute the\n *     same `queryHash`, refresh would be a no-op, and stale MV rows\n *     would persist. Hashing in declaration order makes any reorder\n *     trigger a refresh.\n *   - `groupBy` fields ARE sorted, by their canonical `describeGroupKey`\n *     description (which is the field name itself for a plain key). Multi-key\n *     groupBy buckets are commutative (`canonicalGroupKey` produces the same\n *     composite key regardless of field order in the input spec).\n *   - `aggregate` keys ARE sorted. Reducer-spec keys are independent\n *     of each other — order of declaration doesn't change output.\n *\n * Per-arm `map` functions are NOT fingerprinted; consumers must bump\n * the MV's `name` (or rely on application-level cache busting) when\n * `map` semantics change non-equivalently.\n */\nexport function summarizeUnionPlan<T extends Record<string, unknown>>(\n  spec: MaterializedViewSpec<T>,\n): string {\n  return `union(${summarizeUnionArms(spec)})${summarizeGroupingTail(spec)}`\n}\n\n/**\n * Canonical string description of a projection MV's plan (#810), used\n * as input to `computeQueryHash`.\n *\n * Leg descriptors ARE sorted (contrast with UNION arm order): every\n * leg attaches under a distinct `as` alias, forward legs are\n * one-to-one attachments and collect legs are independent\n * hash-grouped passes, so declaration order never changes the\n * materialized rows — a pure reorder must NOT force a refresh.\n * `from` (#1140) constrains the legal orderings (a leg must follow the\n * alias it attaches to) without making order meaningful: each descriptor\n * carries its own `@alias`, and aliases are unique, so the sorted set\n * still determines the leg graph exactly.\n *\n * The projection `map` is NOT fingerprinted (identical limitation as\n * the UNION arm `map`); consumers must bump the MV's `name` when\n * `map` semantics change non-equivalently.\n */\nexport function summarizeProjectionPlan<T extends Record<string, unknown>>(\n  spec: MaterializedViewSpec<T>,\n): string {\n  const projection = spec.projection!\n  const legs = projection.joins\n    .map(leg => {\n      // #1140 — `from` changes which rows a leg attaches to, so it is part of\n      // the plan's identity. Omitting it would let two structurally different\n      // projections share a queryHash and silently skip a refresh.\n      const at = leg.from !== undefined ? `@${leg.from}` : ''\n      return 'collect' in leg\n        ? `collect${at}:${leg.collect}.${leg.on}→${leg.as}`\n        : `field${at}:${leg.field}→${leg.as}`\n    })\n    .sort()\n  const body = JSON.stringify({ source: projection.source, legs })\n  return `projection(${body})${summarizeGroupingTail(spec)}`\n}\n\n/** Arm descriptors for `summarizeUnionPlan` — declaration order preserved (see its doc). */\nfunction summarizeUnionArms<T extends Record<string, unknown>>(\n  spec: MaterializedViewSpec<T>,\n): string {\n  return (spec.unionSources ?? [])\n    .map(s => {\n      // Fold each arm's join legs into the summary so adding or\n      // reordering joins (which changes the materialized rows) bumps\n      // queryHash. Leg order is declaration-significant (legs chain), so\n      // it is NOT sorted — same rationale as arm declaration order.\n      // #1411 — a declared leg folds its NORMALISED predicate in (the normal\n      // form is what makes two logically identical `on`s hash identically, and\n      // `normalizeJoinOn` throwing here is what makes a malformed leg fail at\n      // registration rather than at the first refresh).\n      const joins = s.join?.length\n        ? `[${s.join.map(j => 'on' in j\n            ? `${j.target}?${JSON.stringify(normalizeJoinOn(j.on, j.target))}${j.mode === 'inner' ? '!' : ''}→${j.as}`\n            : `${j.field}→${j.as}`).join(';')}]`\n        : ''\n      return `${s.collection}${joins}`\n    })\n    .join(',')\n}\n\n\n/**\n * #1411 — the window's contribution to `queryHash`.\n *\n * ⚠️ **`partitionBy` and `orderBy` are NOT sorted, unlike the groupBy and\n * aggregate keys beside them.** Group buckets are commutative, so sorting them\n * is what stops a re-ordered declaration from forcing a pointless refresh. A\n * window's keys are not: `orderBy: ['a','b']` walks a partition differently\n * from `['b','a']` and produces different running totals, and a partition list\n * feeds the same key-building order. Sorting them here would let a real\n * semantic change reuse a stored `queryHash`, refresh would be a no-op, and\n * the view would serve numbers computed under the old ordering.\n *\n * ⭐ **Returns the EMPTY STRING when no window is declared**, which is the same\n * omitted-at-default discipline `summarizeJoinLeg` states above and for the\n * same reason: every existing MV's stored `queryHash` must stay byte-identical\n * across this change, so only a view that actually declares a window\n * recomputes — once, correctly.\n *\n * `select` KEYS are sorted — they are independent output columns, same\n * rationale as the aggregate keys. The slot VALUES are functions and cannot be\n * hashed; renaming a column or adding one is what this can see, which is the\n * same limit `aggregate` has.\n */\nfunction summarizeWindow<T extends Record<string, unknown>>(\n  spec: MaterializedViewSpec<T>,\n): string {\n  if (!spec.window) return ''\n  const list = (v: unknown): string => {\n    if (v === undefined) return ''\n    const arr = Array.isArray(v) ? v : [v]\n    return arr\n      .map((k) =>\n        typeof k === 'object' && k !== null && 'field' in (k as Record<string, unknown>)\n          ? `${describeGroupKey((k as { field: GroupKey }).field)}:${String((k as { direction?: string }).direction ?? 'asc')}`\n          : describeGroupKey(k as GroupKey),\n      )\n      .join(',')\n  }\n  const selectKeys = Object.keys(spec.window.select).sort().join(',')\n  return `|window(partition(${list(spec.window.partitionBy)})order(${list(spec.window.orderBy)})select(${selectKeys}))`\n}\n\n/**\n * Shared `|groupBy(…)|aggregate(…)|money(…)` tail for the UNION and\n * projection summaries — both feed the same post-map grouping pipeline,\n * so the same spec fields fold into both hashes with the same rules.\n */\nfunction summarizeGroupingTail<T extends Record<string, unknown>>(\n  spec: MaterializedViewSpec<T>,\n): string {\n  // `describeGroupKey` is the identity of a group key: a plain field name maps\n  // to itself, and a `dateTrunc()` key (#1350) to a canonical string carrying\n  // every parameter that decides which bucket a row lands in. Changing a unit,\n  // a timezone or the week start therefore bumps the hash and forces a refresh.\n  const groupBy: string = Array.isArray(spec.groupBy)\n    ? spec.groupBy.map(describeGroupKey).sort().join(',')\n    : spec.groupBy === undefined\n      ? ''\n      : describeGroupKey(spec.groupBy as GroupKey)\n  const aggKeys = spec.aggregate ? Object.keys(spec.aggregate).sort().join(',') : ''\n  // `moneyFields` changes reducer semantics (float → exact BigInt), so\n  // declaring / removing / re-keying it must bump queryHash. Keys are\n  // sorted — they're independent of each other (one descriptor per\n  // output field), same rationale as aggregate keys.\n  const moneyKeys = spec.moneyFields ? Object.keys(spec.moneyFields).sort().join(',') : ''\n  return `|groupBy(${groupBy})|aggregate(${aggKeys})|money(${moneyKeys})${summarizeWindow(spec)}`\n}\n","/**\n * Deterministic hash of a materialized view strategy's \"shape\": MV\n * name + canonical query-plan summary + sorted dependency-set.\n *\n * Used to detect strategy drift: a row whose `_materializedFrom.queryHash`\n * doesn't match the current strategy is considered stale.\n *\n * Web Crypto SHA-256 — no extra deps. Mirrors the v1\n * `computeStrategyHash` pattern.\n */\nimport { sha256Hex } from '../../capsule/index.js'\n\nexport async function computeQueryHash(\n  mvName: string,\n  /**\n   * Source-collection set the query depends on. Sorted before\n   * canonicalization so set iteration order doesn't affect the hash.\n   */\n  dependencies: ReadonlySet<string>,\n  /**\n   * Stringified query-plan summary. The caller produces this from the\n   * `Query<T>` builder — concretely: a JSON serialization of clauses +\n   * orderBy + limit + offset + joins. Function bodies inside\n   * `wherePredicate` are NOT included here (those carry their own\n   * `predicateHash` to be folded in by a later sub-issue).\n   */\n  queryPlanSummary: string,\n): Promise<string> {\n  const canonical = JSON.stringify({\n    mvName,\n    dependencies: [...dependencies].sort(),\n    queryPlanSummary,\n  })\n  const bytes = new TextEncoder().encode(canonical)\n  return sha256Hex(bytes)\n}\n\n/**\n * Canonicalize a query plan for hashing. Walks the plan structure\n * with sorted keys so insertion order doesn't perturb the result.\n * Lives here rather than in `query/builder.ts` to keep that module\n * stable across MV-specific evolutions.\n *\n * @internal exported for testing\n */\nexport function canonicalizeQueryPlan(plan: unknown): string {\n  return JSON.stringify(plan, (_key, value) => {\n    if (value && typeof value === 'object' && !Array.isArray(value)) {\n      const sorted: Record<string, unknown> = {}\n      for (const k of Object.keys(value as Record<string, unknown>).sort()) {\n        sorted[k] = (value as Record<string, unknown>)[k]\n      }\n      return sorted\n    }\n    return value\n  })\n}\n","/**\n * Projection-leg topology (#810, extended by #1140).\n *\n * A projection MV's legs originally all attached to the PRIMARY row: a forward\n * leg named an FK field on `projection.source`, and a reverse `collect` leg's\n * `on` field had to `ref()` the source itself. Anything two FKs away was\n * therefore inexpressible — `bill → entity → client` has no leg shape, because\n * the bill has no `clientId` and `clients.entityId` refs `entities`, not\n * `bills`.\n *\n * `from` closes that: a leg may attach to a previously-declared ALIAS instead of\n * to the primary row. This module owns the two questions that follow from it —\n * *is this leg graph well-formed?* and *which collection does a leg's rows come\n * from?* — so neither the registry nor the executor has to re-derive them.\n *\n * **Why cycles are impossible by construction, and there is no depth cap.**\n * `from` may only name an alias declared EARLIER in `joins`. A leg can therefore\n * never reach forward, the graph is a forest rooted at the primary row, and its\n * depth is bounded by the number of legs. Validation refuses an unknown or\n * not-yet-declared alias, which is the same check.\n */\n\nimport { MaterializedViewConfigError } from '../../kernel/errors.js'\nimport type { ProjectionJoinLeg, ProjectionSpec } from './types.js'\n\n/** Reverse (one-to-many) leg — discriminated on `collect`, as the type is. */\nexport function isCollectLeg(\n  leg: ProjectionJoinLeg,\n): leg is Extract<ProjectionJoinLeg, { collect: string }> {\n  return 'collect' in leg\n}\n\n/**\n * Refuse a malformed leg graph where `withMaterializedView()` checks the rest of\n * the leg shape — at spec CONSTRUCTION, not at vault open and not at first\n * materialization. Alias wiring is pure configuration: it needs no refs, no\n * records and no store, so the earliest failure is the best one.\n * (Ref EXISTENCE still resolves at first materialization, unchanged — refs\n * cannot exist until after `openVault()` returns.)\n */\nexport function validateProjectionLegs<T extends Record<string, unknown>>(\n  mvName: string,\n  projection: ProjectionSpec<T>,\n): void {\n  // Non-empty and unique `as` are already refused by `withMaterializedView()`\n  // itself, earlier and with its own message — not re-checked here. This\n  // function owns the `from` wiring and nothing else.\n  const seen = new Map<string, ProjectionJoinLeg>()\n  for (const leg of projection.joins) {\n    if (leg.from !== undefined) {\n      const parent = seen.get(leg.from)\n      if (!parent) {\n        throw new MaterializedViewConfigError(\n          `\"${mvName}\": projection leg \"${leg.as}\" declares from: \"${leg.from}\", which is not an ` +\n            `alias declared EARLIER in \\`joins\\`. A leg may only attach to the primary row or to a ` +\n            `preceding leg — that ordering rule is what makes a cycle impossible. Known so far: ` +\n            `${[...seen.keys()].map(a => `\"${a}\"`).join(', ') || '(none)'}`,\n        )\n      }\n      if (isCollectLeg(parent)) {\n        throw new MaterializedViewConfigError(\n          `\"${mvName}\": projection leg \"${leg.as}\" declares from: \"${leg.from}\", but \"${leg.from}\" ` +\n            `is a collect leg and holds an ARRAY of rows, not one record. A leg can only hang off a ` +\n            `forward leg (record | null). Attach it to the primary row instead, or collect the ` +\n            `far side directly if its ref() reaches \"${projection.source}\".`,\n        )\n      }\n    }\n    seen.set(leg.as, leg)\n  }\n}\n\n/**\n * The collection a leg's rows come from — the primary source for a root leg, the\n * `from` leg's own target otherwise.\n *\n * Returns `null` when a forward `ref()` somewhere along the chain is not\n * declared yet, which at registration time is the normal case rather than an\n * error: refs are declared after `openVault()` returns, so the registry retries\n * this on every dispatch until it resolves (`_pendingForwardDeps`).\n *\n * `resolveRef` is passed in rather than imported so this module stays free of\n * vault wiring — the registry hands it the ref registry's `getOutbound`, the\n * executor hands it a join context lookup. Both answer the same question.\n */\nexport type RefLookup = (collection: string, field: string) => { target: string } | null\n\nexport function resolveLegOwner(\n  leg: ProjectionJoinLeg,\n  joins: ReadonlyArray<ProjectionJoinLeg>,\n  source: string,\n  resolveRef: RefLookup,\n): string | null {\n  if (leg.from === undefined) return source\n  const parent = joins.find(l => l.as === leg.from)\n  if (!parent) return null // refused by validateProjectionLegs; defensive here\n  if (isCollectLeg(parent)) return parent.collect // refused too, same reason\n  const parentOwner = resolveLegOwner(parent, joins, source, resolveRef)\n  if (parentOwner === null) return null\n  return resolveRef(parentOwner, parent.field)?.target ?? null\n}\n\n/**\n * The collection a FORWARD leg resolves INTO — i.e. its dependency. `null` while\n * any ref in the chain (including this leg's own) is still undeclared.\n */\nexport function resolveForwardLegTarget(\n  leg: Extract<ProjectionJoinLeg, { field: string }>,\n  joins: ReadonlyArray<ProjectionJoinLeg>,\n  source: string,\n  resolveRef: RefLookup,\n): string | null {\n  const owner = resolveLegOwner(leg, joins, source, resolveRef)\n  if (owner === null) return null\n  return resolveRef(owner, leg.field)?.target ?? null\n}\n","import { MaterializedViewSourceUnknownError, RefNotDeclaredError } from '../../kernel/errors.js'\nimport type { ViaGraph, FieldRef, EdgeKind, Grain } from '../../kernel/via/graph.js'\nimport type { Clause, FieldClause } from '../../kernel/query/predicate.js'\nimport type { DeclaredPredicate } from '../../kernel/query/builder.js'\nimport { analyzeDependencies, summarizeQueryPlan, summarizeUnionPlan, summarizeProjectionPlan } from './dependency-analyzer.js'\nimport { computeQueryHash } from './query-hash.js'\nimport { isCollectLeg, resolveForwardLegTarget } from './projection-legs.js'\nimport type { MaterializedViewSpec, MVQueryContext } from './types.js'\n\n/**\n * Whole-record artifact-grain field marker (#638 Task 2) — MUST match\n * `derivations/registry.ts`'s and `vault.ts`'s overlay-edge marker so\n * cross-registry edges (a derivation feeding an MV, or vice versa) resolve\n * to the SAME graph node. See that file's `WHOLE_RECORD` doc comment.\n */\nconst WHOLE_RECORD = '*'\n\n/**\n * One registered MV strategy alongside its derived metadata. Stored\n * type-erased on `TRow` so the registry can hold heterogeneous MVs.\n */\nexport interface RegisteredMV {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  readonly spec: MaterializedViewSpec<any>\n  /** Output collection name (`spec.output?.collection ?? spec.name`). */\n  readonly outputCollection: string\n  /** Set of source collections; populated at registration via the analyzer. */\n  readonly dependencies: ReadonlySet<string>\n  /** Canonical `queryHash` — `_materializedFrom.queryHash` for every emitted row. */\n  readonly queryHash: string\n  /**\n   * Top-level FieldClauses on the partition field, captured at\n   * registration time. Used by the cycle detector to resolve\n   * same-collection-as-source edges via the partition-discriminator\n   * check. Empty when `spec.output?.partition` is undefined.\n   */\n  readonly partitionClauses: readonly FieldClause[]\n  /**\n   * #638 Task 2 — `'record'` for a row-per-source-row Query<T> or\n   * `unionSources` MV, `'aggregate'` for a `.groupBy().aggregate()` MV\n   * (the shape that requires explicit `sources`, since the dependency\n   * analyzer can't walk an aggregate plan). Feeds `edges()`'s grain.\n   */\n  readonly grain: Grain\n}\n\n/**\n * Vault-internal registry of MV strategies. Owned by `Vault`; not\n * exported. Parallel to v1's `DerivationRegistry`; the two graphs share\n * a single cycle-detection pass at vault open (see `validate`).\n *\n * @internal\n */\nexport class MaterializedViewRegistry {\n  /** Keyed by `spec.name`. */\n  private readonly _byName = new Map<string, RegisteredMV>()\n  /** Keyed by dependency source-collection → MVs that depend on it. */\n  private readonly _bySource = new Map<string, RegisteredMV[]>()\n  /**\n   * Projection MVs (#810) whose forward-leg ref() targets could not be\n   * resolved at registration time. A forward leg names only the FK\n   * FIELD; its dependency is the field's ref() TARGET, declared on the\n   * source collection — but registration runs at vault open, BEFORE\n   * user code declares collections (and their refs). Constructing the\n   * source collection here to look them up would be worse: a later\n   * `vault.collection(source, { refs })` call only registers refs on a\n   * cache miss, so an early construction would silently drop them.\n   * Instead each entry carries a non-constructive ref-registry probe;\n   * `mvsForSource` retries on every dispatch until every forward\n   * target has resolved (see `_resolvePendingForwardDeps`).\n   */\n  private readonly _pendingForwardDeps: Array<{\n    reg: RegisteredMV\n    /** Forward-leg ALIASES still awaiting resolution (#1140 — a leg is identified\n     *  by its alias, not its field: with `from`, two legs may name the same FK\n     *  field on different collections). */\n    aliases: Set<string>\n    resolveTarget: (alias: string) => string | null\n  }> = []\n\n  /**\n   * Query-form strategies whose `query()` callback could not be planned at\n   * registration time because a `.join()` names a field whose `ref()` is not\n   * declared YET (#1139).\n   *\n   * Registration runs inside `openVault()`; a collection's refs can only be\n   * declared afterwards, so for a query-form MV that joins a declared FK there\n   * is NO call ordering the consumer can choose — the plan is simply built too\n   * early. Rather than failing the vault open, the strategy is parked here and\n   * replanned from {@link resolvePendingPlans}, which every write dispatch and\n   * `vault.refreshView()` call runs first. This is the query-form counterpart\n   * of `_pendingForwardDeps`, one level up: that defers a leg's TARGET, this\n   * defers the whole plan.\n   *\n   * Only `RefNotDeclaredError` parks a strategy. Every other planning failure\n   * still throws out of `openVault()` exactly as before, so a typo'd source or\n   * a malformed spec keeps its loud, early error.\n   *\n   * A parked strategy is invisible until it resolves: it contributes no\n   * `_bySource` entries and no cycle-detection edges (same caveat as a\n   * late-resolved forward target — `edges()` runs once at vault open). It also\n   * cannot be dispatched, which is why {@link hasPendingPlans} forces the\n   * conservative branch in `Collection._txAtomicSafe`: the atomic write path\n   * skips MV dispatch, and skipping it here would mean the write that was\n   * supposed to trigger the first replan is the one that gets missed.\n   */\n  private readonly _pendingPlans: Array<{\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    spec: MaterializedViewSpec<any>\n    db: MVQueryContext\n    options?: { knownCollections?: (name: string) => boolean }\n  }> = []\n\n  /**\n   * Register an MV. Invokes `spec.query()` once at registration time to\n   * read the plan + join context; the resulting `Query<T>` is discarded\n   * after dependency extraction. `vault.collection(...)` must therefore\n   * be functional by the time this runs — typically wired from\n   * `Vault._initMaterializedViews` after collection bootstrap.\n   *\n   * Throws `MaterializedViewSourceUnknownError` if the analyzer\n   * surfaces a dependency the vault doesn't know about (when a\n   * `knownCollections` checker is supplied).\n   */\n  async register(\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    spec: MaterializedViewSpec<any>,\n    db: MVQueryContext,\n    options?: { knownCollections?: (name: string) => boolean },\n  ): Promise<void> {\n    // Build a predicate-aware db wrapper. If `spec.predicates` is\n    // declared, the wrapper intercepts `.collection().query()` and\n    // attaches the predicates map to the resulting Query<T>. With no\n    // predicates declared, the wrapper is the original db unchanged.\n    const ungatedDb = ungatedMvContext(db) // #1414 — the engine keeps its pre-gate source; see ungatedMvContext\n    const dbForQuery = spec.predicates ? wrapDbWithPredicates(ungatedDb, spec.predicates) : ungatedDb\n\n    // Invoke the query callback once to inspect its plan / dependencies.\n    // For Query<T> shapes the analyzer extracts deps + plan summary\n    // automatically. Reduction / GroupedReduction shapes don't\n    // expose the underlying Query, so the spec must declare `sources`\n    // explicitly. `partitionClauses` are only populated for Query<T>\n    // since same-collection-partition is a non-aggregate concern.\n    // UNION-form strategies: dependencies and plan summary come\n    // straight off the strategy — no `query` callback to introspect.\n    // The dependency-analyzer + summarizer are bypassed entirely; the\n    // executor handles materialization via `materializeUnionResult`.\n    let dependencies: Set<string>\n    let queryPlanSummary: string\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    let qAny: any = null\n    let isQuery = false\n    // Projection-form (#810): forward legs whose ref() target wasn't\n    // resolvable at registration time — folded in lazily, see\n    // `_pendingForwardDeps`.\n    const pendingForwardFields: string[] = []\n    if (spec.unionSources) {\n      dependencies = new Set(spec.unionSources.map(s => s.collection))\n      // Per-arm joins resolve right-side collections that aren't among\n      // the arm `collection`s. The consumer lists those in `sources`;\n      // fold them into the dependency set so a write to a join-target\n      // collection triggers MV refresh (and contributes a cycle edge).\n      if (spec.sources) for (const s of spec.sources) dependencies.add(s)\n      // #1411 — a declared join names its target literally, so it needs no\n      // `sources` entry to be a dependency (a ref join's target is only known\n      // once the ref is declared, which is why THOSE must be listed).\n      for (const arm of spec.unionSources) for (const leg of arm.join ?? []) if ('on' in leg) dependencies.add(leg.target)\n      queryPlanSummary = summarizeUnionPlan(spec)\n    } else if (spec.projection) {\n      // Projection-form (#810): dependencies are all AUTO — the primary\n      // source, every collect leg's collection (both literal names), and\n      // every forward leg's ref() target. Forward targets usually can't\n      // resolve yet (refs are declared after vault open) — those go\n      // through the pending-resolution path below. Explicit `sources`\n      // remains additive, same as the other two forms.\n      const projection = spec.projection\n      dependencies = new Set([projection.source])\n      for (const leg of projection.joins) {\n        // A collect leg's dependency is its literal collection name, whatever it\n        // attaches to — which is why `from` needs no new dependency machinery on\n        // that side. A forward leg's dependency is a ref() target, still unknown.\n        if (isCollectLeg(leg)) dependencies.add(leg.collect)\n        else pendingForwardFields.push(leg.as)\n      }\n      if (spec.sources) for (const s of spec.sources) dependencies.add(s)\n      queryPlanSummary = summarizeProjectionPlan(spec)\n    } else {\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      let q: any\n      try {\n        q = spec.query!(dbForQuery)\n      } catch (e) {\n        // #1139 — a join on a ref that is not declared YET. Park and replan;\n        // see `_pendingPlans`. Anything else is a real registration failure.\n        if (!(e instanceof RefNotDeclaredError)) throw e\n        this._pendingPlans.push({ spec, db, ...(options !== undefined ? { options } : {}) })\n        return\n      }\n      qAny = q // already `any` — see the declaration above\n      isQuery = typeof qAny._plan === 'function'\n      if (isQuery) {\n        // `q` is the `Query` arm of the union here (runtime-confirmed via\n        // `qAny._plan` above); reuse the already-`any` `qAny` the block uses\n        // for `_plan()` rather than re-narrowing.\n        dependencies = analyzeDependencies(qAny)\n        queryPlanSummary = summarizeQueryPlan(qAny)\n        // Fold `.wherePredicate(name, ctx)` references into the plan\n        // summary so predicate function or ctx changes (signalled by\n        // bumping `hash` or supplying a different ctx) propagate into\n        // `queryHash` and force refresh on next visit.\n        // ⚠️ \"force refresh on next visit\" was ASPIRATIONAL until family#204:\n        // nothing compared the stored hash. It is now compared once per cold\n        // session (stale.ts `markDriftedMVsStale`). ⛔ Still NOT covered:\n        // `rowKey`, which is not part of the hash at all — a changed row key\n        // is invisible to drift detection.\n        const predicateRefs = extractPredicateRefs(qAny._plan())\n        if (predicateRefs.length > 0) {\n          queryPlanSummary = JSON.stringify({ plan: queryPlanSummary, predicates: predicateRefs })\n        }\n        // If `sources` is ALSO declared, take the union (consumer's\n        // explicit list extends the auto-analyzed set).\n        if (spec.sources) for (const s of spec.sources) dependencies.add(s)\n      } else {\n        // Aggregate shape: require explicit `sources`.\n        if (!spec.sources || spec.sources.length === 0) {\n          throw new Error(\n            `withMaterializedView \"${spec.name}\": query() returned an aggregate ` +\n              `(Reduction or GroupedReduction) but no \\`sources\\` field is declared. ` +\n              `The dependency analyzer cannot walk through groupBy().aggregate() ` +\n              `back to the source — declare sources: [...] explicitly.`,\n          )\n        }\n        dependencies = new Set(spec.sources)\n        // Aggregate plans don't carry a chainable query plan for summary\n        // purposes; the dep-set + spec.name serve as the queryHash inputs.\n        queryPlanSummary = JSON.stringify({ aggregate: true, sources: [...spec.sources].sort() })\n      }\n    }\n\n    // Sanity-check declared dependencies against the vault's known\n    // collections. Optional — when the checker isn't supplied (test\n    // wiring, in-process composition) the registration succeeds and\n    // any typo surfaces at first onSourceWrite as a no-op.\n    if (options?.knownCollections) {\n      for (const dep of dependencies) {\n        if (!options.knownCollections(dep)) {\n          throw new MaterializedViewSourceUnknownError(spec.name, dep)\n        }\n      }\n    }\n\n    const outputCollection = spec.output?.collection ?? spec.name\n    const queryHash = await computeQueryHash(spec.name, dependencies, queryPlanSummary)\n    // For same-collection-as-source MVs, capture the where-clauses on\n    // the partition field so cycle detection can prove disjointness.\n    // Only applicable to Query<T> shapes — aggregate MVs don't carry\n    // a chainable plan to inspect (and same-collection aggregation\n    // doesn't make sense for same-collection aggregation).\n    const partitionClauses: FieldClause[] = []\n    const partitionField = spec.output?.partition?.field\n    if (partitionField !== undefined && isQuery) {\n      const plan = qAny._plan()\n      for (const clause of plan.clauses) {\n        if (isFieldClauseOnField(clause, partitionField)) partitionClauses.push(clause)\n      }\n    }\n    // #638 Task 2 — 'aggregate' only for the explicit-sources aggregate shape\n    // (groupBy().aggregate() with no chainable plan); a row-per-source-row\n    // Query<T>, unionSources, or projection MV is 'record'.\n    const grain: Grain = spec.unionSources || spec.projection || isQuery ? 'record' : 'aggregate'\n    const reg: RegisteredMV = { spec, outputCollection, dependencies, queryHash, partitionClauses, grain }\n\n    this._byName.set(spec.name, reg)\n    for (const dep of dependencies) {\n      const arr = this._bySource.get(dep)\n      if (arr) arr.push(reg)\n      else this._bySource.set(dep, [reg])\n    }\n    if (pendingForwardFields.length > 0) {\n      // Non-constructive ref-registry probe: the Vault (the real\n      // MVQueryContext) carries its RefRegistry as a private field,\n      // reachable structurally at runtime. Test stubs without one simply\n      // never resolve — forward deps then come only from explicit `sources`.\n      const refRegistry = (db as unknown as {\n        refRegistry?: { getOutbound(collection: string): Record<string, { target: string }> }\n      }).refRegistry\n      const projectionSpec = spec.projection!\n      const resolveRef = (c: string, f: string): { target: string } | null =>\n        refRegistry?.getOutbound(c)[f] ?? null\n      this._pendingForwardDeps.push({\n        reg,\n        aliases: new Set(pendingForwardFields),\n        resolveTarget: (alias) => {\n          const leg = projectionSpec.joins.find(l => l.as === alias)\n          if (!leg || isCollectLeg(leg)) return null\n          // Walks the `from` chain — every hop needs its own ref declared, so a\n          // two-hop leg simply resolves one dispatch later than a one-hop one.\n          return resolveForwardLegTarget(leg, projectionSpec.joins, projectionSpec.source, resolveRef)\n        },\n      })\n      // Immediate attempt — covers refs already declared by the time\n      // this MV registers (re-registration flows, test wiring).\n      this._resolvePendingForwardDeps()\n    }\n  }\n\n  /**\n   * `true` while any query-form strategy is still unplanned (#1139). Read by\n   * `Collection._txAtomicSafe`, which must refuse the atomic write path while\n   * this holds — see the `_pendingPlans` doc comment for why.\n   */\n  hasPendingPlans(): boolean {\n    return this._pendingPlans.length > 0\n  }\n\n  /**\n   * Replan every parked query-form strategy (#1139). Called at the head of both\n   * write dispatchers and of `vault.refreshView()`, so a strategy resolves on the\n   * first write or refresh after its source collection's refs are declared —\n   * which is the earliest moment it could produce a correct plan, and strictly\n   * before the first moment it could have any output to produce.\n   *\n   * Each entry is handed straight back to {@link register}, so a strategy that\n   * is STILL unplannable simply re-parks itself and the next dispatch tries\n   * again. Idempotent and cheap: the array empties as strategies resolve, and\n   * both callers skip the await entirely once it is empty.\n   *\n   * A late-resolved strategy does NOT retro-feed `edges()` — the unified cycle\n   * pass runs once at vault open, before refs exist. Same caveat, and the same\n   * reason, as a late-resolved forward-leg target.\n   */\n  async resolvePendingPlans(): Promise<void> {\n    if (this._pendingPlans.length === 0) return\n    // Splice first: `register` re-parks anything still unplannable, and reading\n    // a live array it is concurrently pushing to would loop.\n    const parked = this._pendingPlans.splice(0)\n    for (const entry of parked) {\n      await this.register(entry.spec, entry.db, entry.options)\n    }\n  }\n\n  /** All MVs that depend on `source`, in registration order. */\n  mvsForSource(source: string): ReadonlyArray<RegisteredMV> {\n    if (this._pendingForwardDeps.length > 0) this._resolvePendingForwardDeps()\n    return this._bySource.get(source) ?? []\n  }\n\n  /**\n   * Retry ref() resolution for every pending projection forward leg\n   * (#810). A field resolves once its source collection's refs have\n   * been declared; the target then folds into the owning MV's\n   * dependency set and `_bySource`, so subsequent writes to it\n   * dispatch a refresh. Idempotent and cheap — the pending list\n   * empties as fields resolve, and `mvsForSource` skips the call\n   * entirely once it's empty.\n   *\n   * Late-resolved targets do NOT retro-feed `edges()` — the cycle\n   * pass runs once at vault open, before refs exist. A cycle routed\n   * exclusively through a forward leg is therefore not detected at\n   * open (collect + source edges, the literal names, are).\n   */\n  private _resolvePendingForwardDeps(): void {\n    for (let i = this._pendingForwardDeps.length - 1; i >= 0; i--) {\n      const entry = this._pendingForwardDeps[i]!\n      for (const alias of [...entry.aliases]) {\n        const target = entry.resolveTarget(alias)\n        if (target === null) continue\n        entry.aliases.delete(alias)\n        if (entry.reg.dependencies.has(target)) continue\n        // `dependencies` is declared ReadonlySet for consumers; the\n        // registry owns the underlying Set and is the one writer.\n        ;(entry.reg.dependencies as Set<string>).add(target)\n        const arr = this._bySource.get(target)\n        if (arr) arr.push(entry.reg)\n        else this._bySource.set(target, [entry.reg])\n      }\n      if (entry.aliases.size === 0) this._pendingForwardDeps.splice(i, 1)\n    }\n  }\n\n  /** Single MV by name, or `undefined`. */\n  byName(name: string): RegisteredMV | undefined {\n    return this._byName.get(name)\n  }\n\n  /** Iterate over every registered MV. */\n  all(): ReadonlyArray<RegisteredMV> {\n    return [...this._byName.values()]\n  }\n\n  /**\n   * Graph edges for #638 Task 2: one `'mv'` edge per registered MV — target\n   * = the output collection (a `WHOLE_RECORD` artifact node), sources =\n   * every dependency (also `WHOLE_RECORD` nodes). Same-collection edges\n   * (`dep === outputCollection`) are skipped IFF the MV declares an\n   * `output.partition` discriminator AND the query has a where-clause that\n   * provably excludes the partition value (`partitionDisjoint`) — the SAME\n   * condition the old local DFS used. Grain comes from the registration-time\n   * `RegisteredMV.grain`.\n   */\n  edges(): ReadonlyArray<{ readonly target: FieldRef; readonly sources: readonly FieldRef[]; readonly kind: EdgeKind; readonly grain: Grain }> {\n    const out: Array<{ target: FieldRef; sources: FieldRef[]; kind: EdgeKind; grain: Grain }> = []\n    for (const reg of this._byName.values()) {\n      const sources: FieldRef[] = []\n      for (const dep of reg.dependencies) {\n        if (dep === reg.outputCollection && partitionDisjoint(reg)) continue\n        sources.push({ collection: dep, field: WHOLE_RECORD })\n      }\n      if (sources.length === 0) continue\n      out.push({ target: { collection: reg.outputCollection, field: WHOLE_RECORD }, sources, kind: 'mv', grain: reg.grain })\n    }\n    return out\n  }\n\n  /**\n   * Cycle detection, delegated to `ViaGraph.assertAcyclic()` (#638 Task 2 —\n   * retires the local DFS). `graph` is the caller's shared per-vault graph,\n   * ALREADY carrying this registry's `edges()` AND `DerivationRegistry`'s\n   * (registered by the caller — see `Vault._initMaterializedViews`, which\n   * runs after `_initDerivations`, so a pure-derivation cycle already threw\n   * `DerivationCycleError` there; any cycle surfacing here necessarily\n   * touches an MV edge). Throws `MaterializedViewCycleError` — SAME class as\n   * before.\n   */\n  validate(graph: ViaGraph): void {\n    graph.assertAcyclic()\n  }\n}\n\n/**\n * Type guard: is the clause a top-level `FieldClause` on the given\n * field? Used by the partition-disjoint check.\n *\n * @internal\n */\nfunction isFieldClauseOnField(clause: Clause, field: string): clause is FieldClause {\n  return clause.type === 'field' && clause.field === field\n}\n\n/**\n * #1414 — wrap an `MVQueryContext` so its `.collection().query()` returns a\n * query with the cold-collection gate removed.\n *\n * The MV engine reads its sources synchronously: registration inspects the\n * plan the spec callback returns, and the executor's scan runs from inside a\n * write commit. Both predate #1414 and both have always read whatever the\n * in-memory cache held. Gating them would convert a pre-existing (and\n * separately tracked) staleness into a thrown error on a write path nobody\n * pointed at a query — so the engine keeps its old source and #1414's change\n * stays on the surface a consumer or a guard actually calls.\n *\n * @internal\n */\nexport function ungatedMvContext(db: MVQueryContext): MVQueryContext {\n  return {\n    // ⚠️ Every argument is forwarded. A spec's `db.collection(name, { tiers })`\n    // supplies the options at FIRST construction (first-construction wins), so\n    // a wrapper that drops the second argument silently un-declares them.\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    collection(name: string, ...rest: any[]): any {\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      const c = (db.collection as any)(name, ...rest) as Record<string | symbol, unknown>\n      return new Proxy(c, {\n        get(target, prop, receiver) {\n          if (prop === 'query') {\n            return (...args: unknown[]) => {\n              // eslint-disable-next-line @typescript-eslint/no-explicit-any\n              const q = (target.query as any)(...args)\n              // The legacy predicate overload returns `T[]`, not a Query.\n              return q && typeof q._ungated === 'function' ? q._ungated() : q\n            }\n          }\n          return Reflect.get(target, prop, receiver)\n        },\n      })\n    },\n  }\n}\n\n/**\n * Wrap an `MVQueryContext` so its `.collection().query()` returns a\n * Query<T> with the MV's declared predicates attached. Bare Queries\n * (outside of any MV) don't gain `.wherePredicate()` — only Queries\n * obtained through this wrapped db do.\n *\n * @internal\n */\nexport function wrapDbWithPredicates(\n  db: MVQueryContext,\n  predicates: NonNullable<MaterializedViewSpec<Record<string, unknown>>['predicates']>,\n): MVQueryContext {\n  // Build the predicate map once — the fn signature in the MV spec\n  // is row-typed but the QueryBuilder casts to unknown, so we widen\n  // here for the Map.\n  const map = new Map<string, DeclaredPredicate>()\n  for (const [name, decl] of Object.entries(predicates)) {\n    map.set(name, {\n      hash: decl.hash,\n      fn: decl.fn as (record: unknown, ctx?: unknown) => boolean,\n    })\n  }\n  return {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    collection<T extends Record<string, unknown>>(name: string): any {\n      const c = db.collection<T>(name)\n      // Return an object that delegates everything to `c` but\n      // overrides `.query()` to attach predicates via the new\n      // `Query._withPredicates()` accessor.\n      return new Proxy(c, {\n        get(target, prop, receiver) {\n          if (prop === 'query') {\n            return (...args: unknown[]) => {\n              // eslint-disable-next-line @typescript-eslint/no-explicit-any\n              const q = (target.query as any)(...args)\n              // For non-aggregate Query<T>, attach predicates. For\n              // legacy predicate-arg overload that returns T[] (sync\n              // filter), pass through unchanged.\n               \n              if (q && typeof q._withPredicates === 'function') {\n                return q._withPredicates(map)\n              }\n              return q\n            }\n          }\n          return Reflect.get(target, prop, receiver)\n        },\n      })\n    },\n  }\n}\n\n/**\n * Walk a QueryPlan's clauses and collect predicate-reference markers\n * for `queryHash` derivation. Returns a sorted array (deterministic\n * order) of `{ name, predicateHash, ctxHash }` tuples — these are the\n * hashable identity of each `.wherePredicate()` call site.\n *\n * @internal\n */\nfunction extractPredicateRefs(\n  plan: { clauses: readonly Clause[] },\n): Array<{ name: string; predicateHash: string; ctxHash: string }> {\n  const refs: Array<{ name: string; predicateHash: string; ctxHash: string }> = []\n  const walk = (clauses: readonly Clause[]): void => {\n    for (const c of clauses) {\n      if (c.type === 'wherePredicate') {\n        refs.push({ name: c.name, predicateHash: c.predicateHash, ctxHash: c.ctxHash })\n      } else if (c.type === 'group') {\n        walk(c.clauses)\n      }\n    }\n  }\n  walk(plan.clauses)\n  // Stable-sort by (name, predicateHash, ctxHash) — same predicate\n  // appearing twice with different ctx hashes both flow through.\n  refs.sort((a, b) => {\n    if (a.name !== b.name) return a.name < b.name ? -1 : 1\n    if (a.predicateHash !== b.predicateHash) return a.predicateHash < b.predicateHash ? -1 : 1\n    return a.ctxHash < b.ctxHash ? -1 : a.ctxHash > b.ctxHash ? 1 : 0\n  })\n  return refs\n}\n\n/**\n * Provability check for the same-collection partition-discriminator.\n * Returns `true` when\n * the captured partition clauses on the MV's query provably exclude\n * the partition's value — meaning the input filter and the output\n * partition are disjoint and the same-collection edge isn't really a\n * cycle.\n *\n * Supported provability shapes (narrow on purpose — DERIV-PP30-001\n * is the load-bearing case):\n *\n * - `.where(field, '==', X)` where X !== partition.value → disjoint\n * - `.where(field, '!=', partition.value)` → disjoint\n * - `.where(field, 'in', [...])` where partition.value NOT in list → disjoint\n *\n * Anything else (no clause on the partition field, an 'in' list that\n * contains partition.value, unsupported operators) → not disjoint,\n * the cycle detector surfaces `MaterializedViewCycleError`.\n *\n * @internal\n */\nfunction partitionDisjoint(reg: RegisteredMV): boolean {\n  const partition = reg.spec.output?.partition\n  if (partition === undefined) return false\n  const value = partition.value\n  // The OR-semantics of multiple where-clauses on the same field\n  // would muddy this check. v2 only treats AND-chained clauses;\n  // any clause that proves disjoint is sufficient.\n  for (const c of reg.partitionClauses) {\n    if (c.op === '==' && c.value !== value) return true\n    if (c.op === '!=' && c.value === value) return true\n    if (c.op === 'in' && Array.isArray(c.value)) {\n      const list = c.value as readonly unknown[]\n      if (!list.includes(value)) return true\n    }\n  }\n  return false\n}\n"],"mappings":";;;;;;;;;;;;;;;;AA0BO,SAAS,oBAAoB,OAAgC;AAClE,QAAM,OAAO,oBAAI,IAAY;AAC7B,QAAM,OAAO,MAAM,MAAM;AACzB,QAAM,MAAM,MAAM,aAAa;AAG/B,MAAI,KAAK,gBAAgB;AACvB,SAAK,IAAI,IAAI,cAAc;AAAA,EAC7B;AAGA,aAAW,OAAO,KAAK,OAAO;AAC5B,SAAK,IAAI,IAAI,MAAM;AAAA,EACrB;AAIA,aAAW,UAAU,KAAK,SAAS;AACjC,QAAI,OAAO,SAAS,aAAa;AAC/B,WAAK,IAAI,OAAO,MAAM;AAAA,IACxB;AAAA,EACF;AAKA,sBAAoB,MAAM,MAAM,GAAG;AAEnC,SAAO;AACT;AAEA,SAAS,oBACP,MACA,MACA,KACM;AACN,OAAK;AAIL,aAAW,UAAU,KAAK,SAAS;AACjC,QAAI,OAAO,SAAS,SAAS;AAAA,IAI7B;AAAA,EACF;AACF;AAaO,SAAS,mBAAmB,OAA2B;AAC5D,QAAM,OAAO,MAAM,MAAM;AACzB,QAAM,MAAM,MAAM,aAAa;AAC/B,SAAO,KAAK,UAAU;AAAA,IACpB,MAAM,KAAK,kBAAkB;AAAA,IAC7B,SAAS,KAAK,QAAQ,IAAI,OAAK;AAC7B,UAAI,EAAE,SAAS,aAAa;AAC1B,eAAO;AAAA,UACL,MAAM;AAAA,UACN,QAAQ,EAAE;AAAA,UACV,IAAI,EAAE;AAAA;AAAA,UAEN,iBAAiB,EAAE,oBAAoB,EAAE,KAAK,aAAa;AAAA,UAC3D,SAAS,EAAE,WAAW;AAAA;AAAA;AAAA,UAGtB,OAAO,EAAE,SAAS;AAAA,QACpB;AAAA,MACF;AACA,aAAO;AAAA,IACT,CAAC;AAAA,IACD,SAAS,KAAK;AAAA,IACd,OAAO,KAAK,SAAS;AAAA,IACrB,QAAQ,KAAK;AAAA,IACb,OAAO,KAAK,MAAM,IAAI,OAAK,iBAAiB,CAAC,CAAC;AAAA,EAChD,CAAC;AACH;AAuBA,SAAS,iBAAiB,GAAqC;AAC7D,SAAO;AAAA,IACL,OAAO,EAAE;AAAA,IACT,IAAI,EAAE;AAAA,IACN,QAAQ,EAAE;AAAA,IACV,MAAM,EAAE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAOR,IAAI,EAAE;AAAA;AAAA;AAAA;AAAA;AAAA,IAKN,WAAW,EAAE;AAAA;AAAA;AAAA;AAAA,IAIb,OAAO,EAAE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAOT,YAAY,EAAE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAkBhB;AACF;AA2BO,SAAS,mBACd,MACQ;AACR,SAAO,SAAS,mBAAmB,IAAI,CAAC,IAAI,sBAAsB,IAAI,CAAC;AACzE;AAoBO,SAAS,wBACd,MACQ;AACR,QAAM,aAAa,KAAK;AACxB,QAAM,OAAO,WAAW,MACrB,IAAI,SAAO;AAIV,UAAM,KAAK,IAAI,SAAS,SAAY,IAAI,IAAI,IAAI,KAAK;AACrD,WAAO,aAAa,MAChB,UAAU,EAAE,IAAI,IAAI,OAAO,IAAI,IAAI,EAAE,SAAI,IAAI,EAAE,KAC/C,QAAQ,EAAE,IAAI,IAAI,KAAK,SAAI,IAAI,EAAE;AAAA,EACvC,CAAC,EACA,KAAK;AACR,QAAM,OAAO,KAAK,UAAU,EAAE,QAAQ,WAAW,QAAQ,KAAK,CAAC;AAC/D,SAAO,cAAc,IAAI,IAAI,sBAAsB,IAAI,CAAC;AAC1D;AAGA,SAAS,mBACP,MACQ;AACR,UAAQ,KAAK,gBAAgB,CAAC,GAC3B,IAAI,OAAK;AASR,UAAM,QAAQ,EAAE,MAAM,SAClB,IAAI,EAAE,KAAK,IAAI,OAAK,QAAQ,IACxB,GAAG,EAAE,MAAM,IAAI,KAAK,UAAU,gBAAgB,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,GAAG,EAAE,SAAS,UAAU,MAAM,EAAE,SAAI,EAAE,EAAE,KACtG,GAAG,EAAE,KAAK,SAAI,EAAE,EAAE,EAAE,EAAE,KAAK,GAAG,CAAC,MACnC;AACJ,WAAO,GAAG,EAAE,UAAU,GAAG,KAAK;AAAA,EAChC,CAAC,EACA,KAAK,GAAG;AACb;AA0BA,SAAS,gBACP,MACQ;AACR,MAAI,CAAC,KAAK,OAAQ,QAAO;AACzB,QAAM,OAAO,CAAC,MAAuB;AACnC,QAAI,MAAM,OAAW,QAAO;AAC5B,UAAM,MAAM,MAAM,QAAQ,CAAC,IAAI,IAAI,CAAC,CAAC;AACrC,WAAO,IACJ;AAAA,MAAI,CAAC,MACJ,OAAO,MAAM,YAAY,MAAM,QAAQ,WAAY,IAC/C,GAAG,iBAAkB,EAA0B,KAAK,CAAC,IAAI,OAAQ,EAA6B,aAAa,KAAK,CAAC,KACjH,iBAAiB,CAAa;AAAA,IACpC,EACC,KAAK,GAAG;AAAA,EACb;AACA,QAAM,aAAa,OAAO,KAAK,KAAK,OAAO,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG;AAClE,SAAO,qBAAqB,KAAK,KAAK,OAAO,WAAW,CAAC,UAAU,KAAK,KAAK,OAAO,OAAO,CAAC,WAAW,UAAU;AACnH;AAOA,SAAS,sBACP,MACQ;AAKR,QAAM,UAAkB,MAAM,QAAQ,KAAK,OAAO,IAC9C,KAAK,QAAQ,IAAI,gBAAgB,EAAE,KAAK,EAAE,KAAK,GAAG,IAClD,KAAK,YAAY,SACf,KACA,iBAAiB,KAAK,OAAmB;AAC/C,QAAM,UAAU,KAAK,YAAY,OAAO,KAAK,KAAK,SAAS,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI;AAKhF,QAAM,YAAY,KAAK,cAAc,OAAO,KAAK,KAAK,WAAW,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI;AACtF,SAAO,YAAY,OAAO,eAAe,OAAO,WAAW,SAAS,IAAI,gBAAgB,IAAI,CAAC;AAC/F;;;AC3UA,eAAsB,iBACpB,QAKA,cAQA,kBACiB;AACjB,QAAM,YAAY,KAAK,UAAU;AAAA,IAC/B;AAAA,IACA,cAAc,CAAC,GAAG,YAAY,EAAE,KAAK;AAAA,IACrC;AAAA,EACF,CAAC;AACD,QAAM,QAAQ,IAAI,YAAY,EAAE,OAAO,SAAS;AAChD,SAAO,UAAU,KAAK;AACxB;AAUO,SAAS,sBAAsB,MAAuB;AAC3D,SAAO,KAAK,UAAU,MAAM,CAAC,MAAM,UAAU;AAC3C,QAAI,SAAS,OAAO,UAAU,YAAY,CAAC,MAAM,QAAQ,KAAK,GAAG;AAC/D,YAAM,SAAkC,CAAC;AACzC,iBAAW,KAAK,OAAO,KAAK,KAAgC,EAAE,KAAK,GAAG;AACpE,eAAO,CAAC,IAAK,MAAkC,CAAC;AAAA,MAClD;AACA,aAAO;AAAA,IACT;AACA,WAAO;AAAA,EACT,CAAC;AACH;;;AC9BO,SAAS,aACd,KACwD;AACxD,SAAO,aAAa;AACtB;AAUO,SAAS,uBACd,QACA,YACM;AAIN,QAAM,OAAO,oBAAI,IAA+B;AAChD,aAAW,OAAO,WAAW,OAAO;AAClC,QAAI,IAAI,SAAS,QAAW;AAC1B,YAAM,SAAS,KAAK,IAAI,IAAI,IAAI;AAChC,UAAI,CAAC,QAAQ;AACX,cAAM,IAAI;AAAA,UACR,IAAI,MAAM,sBAAsB,IAAI,EAAE,qBAAqB,IAAI,IAAI,oMAG9D,CAAC,GAAG,KAAK,KAAK,CAAC,EAAE,IAAI,OAAK,IAAI,CAAC,GAAG,EAAE,KAAK,IAAI,KAAK,QAAQ;AAAA,QACjE;AAAA,MACF;AACA,UAAI,aAAa,MAAM,GAAG;AACxB,cAAM,IAAI;AAAA,UACR,IAAI,MAAM,sBAAsB,IAAI,EAAE,qBAAqB,IAAI,IAAI,WAAW,IAAI,IAAI,sNAGzC,WAAW,MAAM;AAAA,QAChE;AAAA,MACF;AAAA,IACF;AACA,SAAK,IAAI,IAAI,IAAI,GAAG;AAAA,EACtB;AACF;AAiBO,SAAS,gBACd,KACA,OACA,QACA,YACe;AACf,MAAI,IAAI,SAAS,OAAW,QAAO;AACnC,QAAM,SAAS,MAAM,KAAK,OAAK,EAAE,OAAO,IAAI,IAAI;AAChD,MAAI,CAAC,OAAQ,QAAO;AACpB,MAAI,aAAa,MAAM,EAAG,QAAO,OAAO;AACxC,QAAM,cAAc,gBAAgB,QAAQ,OAAO,QAAQ,UAAU;AACrE,MAAI,gBAAgB,KAAM,QAAO;AACjC,SAAO,WAAW,aAAa,OAAO,KAAK,GAAG,UAAU;AAC1D;AAMO,SAAS,wBACd,KACA,OACA,QACA,YACe;AACf,QAAM,QAAQ,gBAAgB,KAAK,OAAO,QAAQ,UAAU;AAC5D,MAAI,UAAU,KAAM,QAAO;AAC3B,SAAO,WAAW,OAAO,IAAI,KAAK,GAAG,UAAU;AACjD;;;ACpGA,IAAM,eAAe;AAsCd,IAAM,2BAAN,MAA+B;AAAA;AAAA,EAEnB,UAAU,oBAAI,IAA0B;AAAA;AAAA,EAExC,YAAY,oBAAI,IAA4B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAc5C,sBAOZ,CAAC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EA4BW,gBAKZ,CAAC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAaN,MAAM,SAEJ,MACA,IACA,SACe;AAKf,UAAM,YAAY,iBAAiB,EAAE;AACrC,UAAM,aAAa,KAAK,aAAa,qBAAqB,WAAW,KAAK,UAAU,IAAI;AAYxF,QAAI;AACJ,QAAI;AAEJ,QAAI,OAAY;AAChB,QAAI,UAAU;AAId,UAAM,uBAAiC,CAAC;AACxC,QAAI,KAAK,cAAc;AACrB,qBAAe,IAAI,IAAI,KAAK,aAAa,IAAI,OAAK,EAAE,UAAU,CAAC;AAK/D,UAAI,KAAK,QAAS,YAAW,KAAK,KAAK,QAAS,cAAa,IAAI,CAAC;AAIlE,iBAAW,OAAO,KAAK,aAAc,YAAW,OAAO,IAAI,QAAQ,CAAC,EAAG,KAAI,QAAQ,IAAK,cAAa,IAAI,IAAI,MAAM;AACnH,yBAAmB,mBAAmB,IAAI;AAAA,IAC5C,WAAW,KAAK,YAAY;AAO1B,YAAM,aAAa,KAAK;AACxB,qBAAe,oBAAI,IAAI,CAAC,WAAW,MAAM,CAAC;AAC1C,iBAAW,OAAO,WAAW,OAAO;AAIlC,YAAI,aAAa,GAAG,EAAG,cAAa,IAAI,IAAI,OAAO;AAAA,YAC9C,sBAAqB,KAAK,IAAI,EAAE;AAAA,MACvC;AACA,UAAI,KAAK,QAAS,YAAW,KAAK,KAAK,QAAS,cAAa,IAAI,CAAC;AAClE,yBAAmB,wBAAwB,IAAI;AAAA,IACjD,OAAO;AAEL,UAAI;AACJ,UAAI;AACF,YAAI,KAAK,MAAO,UAAU;AAAA,MAC5B,SAAS,GAAG;AAGV,YAAI,EAAE,aAAa,qBAAsB,OAAM;AAC/C,aAAK,cAAc,KAAK,EAAE,MAAM,IAAI,GAAI,YAAY,SAAY,EAAE,QAAQ,IAAI,CAAC,EAAG,CAAC;AACnF;AAAA,MACF;AACA,aAAO;AACP,gBAAU,OAAO,KAAK,UAAU;AAChC,UAAI,SAAS;AAIX,uBAAe,oBAAoB,IAAI;AACvC,2BAAmB,mBAAmB,IAAI;AAU1C,cAAM,gBAAgB,qBAAqB,KAAK,MAAM,CAAC;AACvD,YAAI,cAAc,SAAS,GAAG;AAC5B,6BAAmB,KAAK,UAAU,EAAE,MAAM,kBAAkB,YAAY,cAAc,CAAC;AAAA,QACzF;AAGA,YAAI,KAAK,QAAS,YAAW,KAAK,KAAK,QAAS,cAAa,IAAI,CAAC;AAAA,MACpE,OAAO;AAEL,YAAI,CAAC,KAAK,WAAW,KAAK,QAAQ,WAAW,GAAG;AAC9C,gBAAM,IAAI;AAAA,YACR,yBAAyB,KAAK,IAAI;AAAA,UAIpC;AAAA,QACF;AACA,uBAAe,IAAI,IAAI,KAAK,OAAO;AAGnC,2BAAmB,KAAK,UAAU,EAAE,WAAW,MAAM,SAAS,CAAC,GAAG,KAAK,OAAO,EAAE,KAAK,EAAE,CAAC;AAAA,MAC1F;AAAA,IACF;AAMA,QAAI,SAAS,kBAAkB;AAC7B,iBAAW,OAAO,cAAc;AAC9B,YAAI,CAAC,QAAQ,iBAAiB,GAAG,GAAG;AAClC,gBAAM,IAAI,mCAAmC,KAAK,MAAM,GAAG;AAAA,QAC7D;AAAA,MACF;AAAA,IACF;AAEA,UAAM,mBAAmB,KAAK,QAAQ,cAAc,KAAK;AACzD,UAAM,YAAY,MAAM,iBAAiB,KAAK,MAAM,cAAc,gBAAgB;AAMlF,UAAM,mBAAkC,CAAC;AACzC,UAAM,iBAAiB,KAAK,QAAQ,WAAW;AAC/C,QAAI,mBAAmB,UAAa,SAAS;AAC3C,YAAM,OAAO,KAAK,MAAM;AACxB,iBAAW,UAAU,KAAK,SAAS;AACjC,YAAI,qBAAqB,QAAQ,cAAc,EAAG,kBAAiB,KAAK,MAAM;AAAA,MAChF;AAAA,IACF;AAIA,UAAM,QAAe,KAAK,gBAAgB,KAAK,cAAc,UAAU,WAAW;AAClF,UAAM,MAAoB,EAAE,MAAM,kBAAkB,cAAc,WAAW,kBAAkB,MAAM;AAErG,SAAK,QAAQ,IAAI,KAAK,MAAM,GAAG;AAC/B,eAAW,OAAO,cAAc;AAC9B,YAAM,MAAM,KAAK,UAAU,IAAI,GAAG;AAClC,UAAI,IAAK,KAAI,KAAK,GAAG;AAAA,UAChB,MAAK,UAAU,IAAI,KAAK,CAAC,GAAG,CAAC;AAAA,IACpC;AACA,QAAI,qBAAqB,SAAS,GAAG;AAKnC,YAAM,cAAe,GAElB;AACH,YAAM,iBAAiB,KAAK;AAC5B,YAAM,aAAa,CAAC,GAAW,MAC7B,aAAa,YAAY,CAAC,EAAE,CAAC,KAAK;AACpC,WAAK,oBAAoB,KAAK;AAAA,QAC5B;AAAA,QACA,SAAS,IAAI,IAAI,oBAAoB;AAAA,QACrC,eAAe,CAAC,UAAU;AACxB,gBAAM,MAAM,eAAe,MAAM,KAAK,OAAK,EAAE,OAAO,KAAK;AACzD,cAAI,CAAC,OAAO,aAAa,GAAG,EAAG,QAAO;AAGtC,iBAAO,wBAAwB,KAAK,eAAe,OAAO,eAAe,QAAQ,UAAU;AAAA,QAC7F;AAAA,MACF,CAAC;AAGD,WAAK,2BAA2B;AAAA,IAClC;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,kBAA2B;AACzB,WAAO,KAAK,cAAc,SAAS;AAAA,EACrC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAkBA,MAAM,sBAAqC;AACzC,QAAI,KAAK,cAAc,WAAW,EAAG;AAGrC,UAAM,SAAS,KAAK,cAAc,OAAO,CAAC;AAC1C,eAAW,SAAS,QAAQ;AAC1B,YAAM,KAAK,SAAS,MAAM,MAAM,MAAM,IAAI,MAAM,OAAO;AAAA,IACzD;AAAA,EACF;AAAA;AAAA,EAGA,aAAa,QAA6C;AACxD,QAAI,KAAK,oBAAoB,SAAS,EAAG,MAAK,2BAA2B;AACzE,WAAO,KAAK,UAAU,IAAI,MAAM,KAAK,CAAC;AAAA,EACxC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAgBQ,6BAAmC;AACzC,aAAS,IAAI,KAAK,oBAAoB,SAAS,GAAG,KAAK,GAAG,KAAK;AAC7D,YAAM,QAAQ,KAAK,oBAAoB,CAAC;AACxC,iBAAW,SAAS,CAAC,GAAG,MAAM,OAAO,GAAG;AACtC,cAAM,SAAS,MAAM,cAAc,KAAK;AACxC,YAAI,WAAW,KAAM;AACrB,cAAM,QAAQ,OAAO,KAAK;AAC1B,YAAI,MAAM,IAAI,aAAa,IAAI,MAAM,EAAG;AAGvC,QAAC,MAAM,IAAI,aAA6B,IAAI,MAAM;AACnD,cAAM,MAAM,KAAK,UAAU,IAAI,MAAM;AACrC,YAAI,IAAK,KAAI,KAAK,MAAM,GAAG;AAAA,YACtB,MAAK,UAAU,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;AAAA,MAC7C;AACA,UAAI,MAAM,QAAQ,SAAS,EAAG,MAAK,oBAAoB,OAAO,GAAG,CAAC;AAAA,IACpE;AAAA,EACF;AAAA;AAAA,EAGA,OAAO,MAAwC;AAC7C,WAAO,KAAK,QAAQ,IAAI,IAAI;AAAA,EAC9B;AAAA;AAAA,EAGA,MAAmC;AACjC,WAAO,CAAC,GAAG,KAAK,QAAQ,OAAO,CAAC;AAAA,EAClC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYA,QAA6I;AAC3I,UAAM,MAAsF,CAAC;AAC7F,eAAW,OAAO,KAAK,QAAQ,OAAO,GAAG;AACvC,YAAM,UAAsB,CAAC;AAC7B,iBAAW,OAAO,IAAI,cAAc;AAClC,YAAI,QAAQ,IAAI,oBAAoB,kBAAkB,GAAG,EAAG;AAC5D,gBAAQ,KAAK,EAAE,YAAY,KAAK,OAAO,aAAa,CAAC;AAAA,MACvD;AACA,UAAI,QAAQ,WAAW,EAAG;AAC1B,UAAI,KAAK,EAAE,QAAQ,EAAE,YAAY,IAAI,kBAAkB,OAAO,aAAa,GAAG,SAAS,MAAM,MAAM,OAAO,IAAI,MAAM,CAAC;AAAA,IACvH;AACA,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYA,SAAS,OAAuB;AAC9B,UAAM,cAAc;AAAA,EACtB;AACF;AAQA,SAAS,qBAAqB,QAAgB,OAAsC;AAClF,SAAO,OAAO,SAAS,WAAW,OAAO,UAAU;AACrD;AAgBO,SAAS,iBAAiB,IAAoC;AACnE,SAAO;AAAA;AAAA;AAAA;AAAA;AAAA,IAKL,WAAW,SAAiB,MAAkB;AAE5C,YAAM,IAAK,GAAG,WAAmB,MAAM,GAAG,IAAI;AAC9C,aAAO,IAAI,MAAM,GAAG;AAAA,QAClB,IAAI,QAAQ,MAAM,UAAU;AAC1B,cAAI,SAAS,SAAS;AACpB,mBAAO,IAAI,SAAoB;AAE7B,oBAAM,IAAK,OAAO,MAAc,GAAG,IAAI;AAEvC,qBAAO,KAAK,OAAO,EAAE,aAAa,aAAa,EAAE,SAAS,IAAI;AAAA,YAChE;AAAA,UACF;AACA,iBAAO,QAAQ,IAAI,QAAQ,MAAM,QAAQ;AAAA,QAC3C;AAAA,MACF,CAAC;AAAA,IACH;AAAA,EACF;AACF;AAUO,SAAS,qBACd,IACA,YACgB;AAIhB,QAAM,MAAM,oBAAI,IAA+B;AAC/C,aAAW,CAAC,MAAM,IAAI,KAAK,OAAO,QAAQ,UAAU,GAAG;AACrD,QAAI,IAAI,MAAM;AAAA,MACZ,MAAM,KAAK;AAAA,MACX,IAAI,KAAK;AAAA,IACX,CAAC;AAAA,EACH;AACA,SAAO;AAAA;AAAA,IAEL,WAA8C,MAAmB;AAC/D,YAAM,IAAI,GAAG,WAAc,IAAI;AAI/B,aAAO,IAAI,MAAM,GAAG;AAAA,QAClB,IAAI,QAAQ,MAAM,UAAU;AAC1B,cAAI,SAAS,SAAS;AACpB,mBAAO,IAAI,SAAoB;AAE7B,oBAAM,IAAK,OAAO,MAAc,GAAG,IAAI;AAKvC,kBAAI,KAAK,OAAO,EAAE,oBAAoB,YAAY;AAChD,uBAAO,EAAE,gBAAgB,GAAG;AAAA,cAC9B;AACA,qBAAO;AAAA,YACT;AAAA,UACF;AACA,iBAAO,QAAQ,IAAI,QAAQ,MAAM,QAAQ;AAAA,QAC3C;AAAA,MACF,CAAC;AAAA,IACH;AAAA,EACF;AACF;AAUA,SAAS,qBACP,MACiE;AACjE,QAAM,OAAwE,CAAC;AAC/E,QAAM,OAAO,CAAC,YAAqC;AACjD,eAAW,KAAK,SAAS;AACvB,UAAI,EAAE,SAAS,kBAAkB;AAC/B,aAAK,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,EAAE,eAAe,SAAS,EAAE,QAAQ,CAAC;AAAA,MAChF,WAAW,EAAE,SAAS,SAAS;AAC7B,aAAK,EAAE,OAAO;AAAA,MAChB;AAAA,IACF;AAAA,EACF;AACA,OAAK,KAAK,OAAO;AAGjB,OAAK,KAAK,CAAC,GAAG,MAAM;AAClB,QAAI,EAAE,SAAS,EAAE,KAAM,QAAO,EAAE,OAAO,EAAE,OAAO,KAAK;AACrD,QAAI,EAAE,kBAAkB,EAAE,cAAe,QAAO,EAAE,gBAAgB,EAAE,gBAAgB,KAAK;AACzF,WAAO,EAAE,UAAU,EAAE,UAAU,KAAK,EAAE,UAAU,EAAE,UAAU,IAAI;AAAA,EAClE,CAAC;AACD,SAAO;AACT;AAuBA,SAAS,kBAAkB,KAA4B;AACrD,QAAM,YAAY,IAAI,KAAK,QAAQ;AACnC,MAAI,cAAc,OAAW,QAAO;AACpC,QAAM,QAAQ,UAAU;AAIxB,aAAW,KAAK,IAAI,kBAAkB;AACpC,QAAI,EAAE,OAAO,QAAQ,EAAE,UAAU,MAAO,QAAO;AAC/C,QAAI,EAAE,OAAO,QAAQ,EAAE,UAAU,MAAO,QAAO;AAC/C,QAAI,EAAE,OAAO,QAAQ,MAAM,QAAQ,EAAE,KAAK,GAAG;AAC3C,YAAM,OAAO,EAAE;AACf,UAAI,CAAC,KAAK,SAAS,KAAK,EAAG,QAAO;AAAA,IACpC;AAAA,EACF;AACA,SAAO;AACT;","names":[]}

package/dist/{chunk-YAYDDYRU.js → chunk-5Y4MO7UQ.js}

@@ -1,15 +1,15 @@
 import {
   MaintenanceMethods
-} from "./chunk-HQFTE3DX.js";
+} from "./chunk-5BGHAVBN.js";
 import {
   installMethods
 } from "./chunk-F6NCB7KT.js";
 import {
   Query
-} from "./chunk-R4PDYYK5.js";
+} from "./chunk-C2NXAR3D.js";
 import {
   gateTerminal
-} from "./chunk-TA5VTIC4.js";
+} from "./chunk-KA4AAUST.js";
 
 // src/kernel/query/live/live.ts
 function buildLiveQuery(recompute, upstreams, options) {
@@ -267,4 +267,4 @@ export {
   buildLiveQuery,
   installLive
 };
-//# sourceMappingURL=chunk-YAYDDYRU.js.map
+//# sourceMappingURL=chunk-5Y4MO7UQ.js.map

package/dist/{chunk-TLIFNRU5.js → chunk-63LZLRWG.js}

@@ -1,6 +1,6 @@
 import {
   buildRecordEnvelope
-} from "./chunk-WRLWEYHY.js";
+} from "./chunk-EFINFZIF.js";
 
 // src/with-shape/schema-update/fence.ts
 var FENCE_RECORD_ID = "schema-fence";
@@ -36,4 +36,4 @@ export {
   loadFence,
   saveFence
 };
-//# sourceMappingURL=chunk-TLIFNRU5.js.map
+//# sourceMappingURL=chunk-63LZLRWG.js.map

package/dist/{chunk-BUFFPAR2.js → chunk-74W56QPY.js}

@@ -1,16 +1,16 @@
 import {
   splitAroundJoins
-} from "./chunk-R4PDYYK5.js";
+} from "./chunk-C2NXAR3D.js";
 import {
   evaluateClause,
   hasFnClause,
   normalizeMatches,
   normalizeSubqueryOperand
-} from "./chunk-WQHEEYQA.js";
+} from "./chunk-NLDBQHDV.js";
 import {
   FieldNotQueryableError,
   QueryExtensionMissingError
-} from "./chunk-JGYCKX56.js";
+} from "./chunk-ISIXU45J.js";
 
 // src/kernel/query/scan-builder.ts
 var DEFAULT_SCAN_PAGE_SIZE = 100;
@@ -190,4 +190,4 @@ for (const [method, subpath] of SCAN_EXTENSION_METHODS) {
 export {
   ScanBuilder
 };
-//# sourceMappingURL=chunk-BUFFPAR2.js.map
+//# sourceMappingURL=chunk-74W56QPY.js.map

package/dist/{chunk-VPG2UJYR.js → chunk-7KNYLHVX.js}

@@ -3,14 +3,14 @@ import {
   buildRecordEnvelope,
   encrypt,
   openEnvelopeJson
-} from "./chunk-WRLWEYHY.js";
+} from "./chunk-EFINFZIF.js";
 import {
   SequenceContentionError,
   SequenceNotEnabledError,
   SequenceOfflineError,
   ValidationError,
   isConflictError
-} from "./chunk-JGYCKX56.js";
+} from "./chunk-ISIXU45J.js";
 
 // src/with-commit/sequence/active.ts
 function withSequence() {
@@ -197,4 +197,4 @@ export {
   resolveSequenceKey,
   SequenceStore
 };
-//# sourceMappingURL=chunk-VPG2UJYR.js.map
+//# sourceMappingURL=chunk-7KNYLHVX.js.map

package/dist/chunk-7KNYLHVX.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/with-commit/sequence/active.ts","../src/with-commit/sequence/strategy.ts","../src/with-commit/sequence/index.ts"],"sourcesContent":["/**\n * Enable the atomic-sequence capability.\n * Pass to `createNoydb({ sequenceStrategy: withSequence() })` to make\n * `vault.sequence('name').next()` / `.peek()` / `.seedTo()` live. The\n * {@link SequenceStore} CAS engine is statically imported here, so it is pulled\n * into the bundle only when `withSequence()` is referenced (the floor never\n * imports it).\n */\nimport type { SequenceStrategy } from './strategy.js'\nimport { SequenceStore } from './index.js'\n\nexport function withSequence(): SequenceStrategy {\n  return {\n    createStore(opts) {\n      return new SequenceStore(opts)\n    },\n  }\n}\n","/**\n * Sequence capability strategy — the single on-demand factory the vault routes\n * `vault.sequence()` through to build its atomic-CAS {@link SequenceStore}. The\n * active engine ({@link withSequence}) constructs the real store (kept out of\n * the floor bundle — the store class is reached only via the opt-in\n * `active.ts` chunk); {@link NO_SEQUENCE} throws. The vault always assembles the\n * per-call {@link SequenceStoreOptions} and delegates here, so an un-opted-in\n * caller hits `NO_SEQUENCE`'s throw at `vault.sequence()`.\n *\n * Note: `vault.sequence()` is synchronous, so the factory is a plain (sync)\n * constructor — the engine is tree-shaken by reachability (only `withSequence()`\n * pulls `active.ts`, which statically imports the store), not by a dynamic\n * import. Deferred-numbering series (`withDeferredNumbering`) are a distinct\n * capability and are NOT routed through this strategy.\n * @internal\n */\nimport type { SequenceStore, SequenceStoreOptions } from './index.js'\nimport { SequenceNotEnabledError } from '../../kernel/errors.js'\n\nexport interface SequenceStrategy {\n  createStore(opts: SequenceStoreOptions): SequenceStore\n}\n\n/**\n * No-op stub — the floor default. The capability factory throws\n * {@link SequenceNotEnabledError}; opt in with `sequenceStrategy: withSequence()`\n * in createNoydb. @internal\n */\nexport const NO_SEQUENCE: SequenceStrategy = {\n  createStore(): SequenceStore {\n    throw new SequenceNotEnabledError()\n  },\n}\n","/**\n * Atomic sequence primitive — online-coordinated gap-free numbering.\n *\n * `vault.sequence('invoice-2026').next()` returns 1, 2, 3, … with no\n * gaps and no duplicates, even under concurrent callers. Each named\n * sequence is an independent counter record at `_sequences/<name>`,\n * incremented with an optimistic compare-and-swap retry loop — the same\n * proven pattern as the ledger head (`history/ledger/store.ts`).\n *\n * **Explicitly online-only.** Gap-free numbering requires single-authority\n * serialization, which an offline / non-CAS store cannot provide. `next()`\n * throws {@link SequenceOfflineError} unless the backing store advertises\n * `capabilities.casAtomic`. This is a deliberate, honest wall — an offline\n * writer cannot safely allocate a global sequence number.\n *\n * Note on \"gap-free\": the *sequence* is gap-free (each `next()` yields a\n * unique, +1 value). If a caller discards a value without using it, that\n * is a gap in *usage*, not in the sequence — assign each `next()` result\n * to its record in the same operation.\n */\n\nimport { buildRecordAad, buildRecordEnvelope } from '../../capsule/index.js'\nimport type { NoydbStore, EncryptedEnvelope } from '../../kernel/types.js'\nimport { encrypt, openEnvelopeJson, type EnclaveKey } from '../../capsule/index.js'\nimport type { ConflictError} from '../../kernel/errors.js';\nimport { isConflictError, SequenceContentionError, SequenceOfflineError, ValidationError } from '../../kernel/errors.js'\n\n// Capability opt-in seam (S4): `vault.sequence()` builds its CAS store through\n// the sequenceStrategy, so it throws SequenceNotEnabledError unless opted in.\nexport { withSequence } from './active.js'\nexport { NO_SEQUENCE, type SequenceStrategy } from './strategy.js'\nexport { SequenceNotEnabledError } from '../../kernel/errors.js'\n\n/**\n * ⛔ **COUNTERS NEVER SYNC — A SEQUENCE IS UNIQUE PER DEVICE, NOT ACROSS A\n * FLEET (family#206).** `_sequences` is absent from `RESERVED_REPLICATION`\n * (`with-sync/reserved-mirror.ts:108`, whose replicated set is `_keyring`,\n * `_broker_member`, `_broker`, `_meta`, `_users`, `_delegations`,\n * `_rejections`), and `next()` CASes the counter record against the LOCAL\n * store. So two devices issuing from the same sequence name produce the SAME\n * numbers, and `next()`'s \"no duplicates under concurrency\" guarantee holds\n * within one device only.\n *\n * ⚠️ The CAS is doing real work and it is not the gap here — it serializes\n * concurrent writers against ONE store. What is missing is replication of the\n * counter itself, which is why the failure is invisible to any single-device\n * test and to every in-tree simulation that shares a store.\n *\n * ⛔ Do not use this for an invoice number that must be unique across devices\n * until family#206 lands — it is the first item of the next cycle.\n *\n * ⭐ Measured: with sync on both devices, A `next()` → 1, A pushes, B pulls the\n * whole vault, B `next()` → 1. Two records numbered 1 after a COMPLETE sync\n * cycle — the pull cannot help, because there is nothing replicating to pull.\n */\nexport const SEQUENCE_COLLECTION = '_sequences'\n// A sequence is a single hot CAS row — higher contention than a ledger\n// append. A larger budget + jittered backoff absorbs moderate concurrency;\n// a genuine burst beyond this surfaces SequenceContentionError so the\n// caller can retry / queue (the honest online-only contract).\nconst MAX_NEXT_ATTEMPTS = 16\n\ninterface SequenceState {\n  value: number\n}\n\n/** Options for `SequenceHandle.next`. Deferred-numbering series use `for`; the CAS counter ignores all of these. */\nexport interface NextOptions {\n  /** Deferred mode: the record id to number. Ignored by the CAS counter. */\n  readonly for?: string\n  /** Deferred mode: reject after this many ms if still unsealed (reserved; not yet enforced in this slice). */\n  readonly timeoutMs?: number\n}\n\n/**\n * Partitioning for a CAS sequence. A partitioned sequence is an\n * independent counter scoped to one tuple of values — e.g.\n * `sequence('invoice', { partition: [2026, 'EU'] })` numbers EU-2026 invoices\n * separately from `[2026, 'US']` and from the bare `invoice` series.\n *\n * Partition components are URI-encoded (so `/`, null bytes and other\n * separators in a value can never collide with the structural separators) and\n * `'/'`-joined, then appended to the series with a null-byte (`\\x00`)\n * separator. The null byte is illegal in a plain series name, which guarantees\n * a partitioned key is always disjoint from any unpartitioned series.\n */\nexport interface SequenceOptions {\n  /** Partition tuple. Each component is URI-encoded and `'/'`-joined. */\n  readonly partition?: readonly (string | number)[]\n  /**\n   * Render template for the serial string. When set, `vault.sequence`\n   * returns a {@link FormattedSequenceHandle} whose `next()` resolves to\n   * `{ serial, formatted }`. Tokens:\n   * - `{seq}` — the allocated integer\n   * - `{seq:0N}` — zero-padded to width N (e.g. `{seq:04}` → `0001`)\n   * - `{partition.i}` — the i-th `partition` component (original value)\n   *\n   * Any other token, or a `{partition.i}` index beyond the supplied\n   * `partition`, throws `ValidationError` at `vault.sequence()` construction.\n   * Per-partition reset is inherent: a new partition tuple starts at 1.\n   */\n  readonly format?: string\n}\n\n/**\n * A formatted sequence handle. Identical to {@link SequenceHandle}\n * except `next()` also returns the rendered `formatted` string. `peek()` /\n * `seedTo()` operate on the underlying integer counter, unchanged.\n */\nexport interface FormattedSequenceHandle {\n  /** Allocate the next value and return it with its rendered serial string. */\n  next(opts?: NextOptions): Promise<{ serial: number; formatted: string }>\n  /** Read the current integer value without allocating. Returns 0 if never used. */\n  peek(): Promise<number>\n  /** Set-if-greater on the underlying integer counter. See {@link SequenceHandle.seedTo}. */\n  seedTo(n: number): Promise<void>\n}\n\n// Matches a single `{...}` token with no nested braces.\nconst SEQ_FORMAT_TOKEN = /\\{([^{}]*)\\}/g\nconst SEQ_PAD_TOKEN = /^seq:0(\\d+)$/\nconst SEQ_PARTITION_TOKEN = /^partition\\.(\\d+)$/\n\n/**\n * Validate a sequence `format` against the supplied partition and return a\n * pure `(serial) => string` renderer. Eager validation: every token is\n * checked now, so a bad pattern throws `ValidationError` at construction —\n * never at `next()` time.\n */\nexport function compileSequenceFormat(\n  format: string,\n  series: string,\n  partition: readonly (string | number)[] | undefined,\n): (serial: number) => string {\n  const parts = partition ?? []\n  for (const m of format.matchAll(SEQ_FORMAT_TOKEN)) {\n    const token = m[1] ?? ''\n    if (token === 'seq') continue\n    if (SEQ_PAD_TOKEN.test(token)) continue\n    const partMatch = SEQ_PARTITION_TOKEN.exec(token)\n    if (partMatch) {\n      const idx = Number(partMatch[1])\n      if (idx >= parts.length) {\n        throw new ValidationError(\n          `sequence(\"${series}\"): format token \"{${token}}\" references partition index ${idx}, ` +\n            `but only ${parts.length} partition component(s) were supplied.`,\n        )\n      }\n      continue\n    }\n    throw new ValidationError(\n      `sequence(\"${series}\"): format contains unknown token \"{${token}}\". ` +\n        `Accepted tokens: {seq}, {seq:0N}, {partition.i}.`,\n    )\n  }\n  return (serial: number): string =>\n    format.replace(SEQ_FORMAT_TOKEN, (full, token: string) => {\n      if (token === 'seq') return String(serial)\n      const padMatch = SEQ_PAD_TOKEN.exec(token)\n      if (padMatch) return String(serial).padStart(Number(padMatch[1]), '0')\n      const partMatch = SEQ_PARTITION_TOKEN.exec(token)\n      if (partMatch) return String(parts[Number(partMatch[1])])\n      return full // unreachable — validated above\n    })\n}\n\n/**\n * Resolve the CAS storage key for a (series, partition) pair.\n *\n * With no partition the key is `series` verbatim. With a partition the key is\n * `${series}\\x00${parts}` where `parts` is each component passed through\n * `encodeURIComponent(String(part))` and `'/'`-joined. The null-byte separator\n * is illegal in a plain series name, so partitioned keys never collide with\n * unpartitioned ones; URI-encoding keeps any component containing `/` distinct\n * from a multi-component partition.\n *\n * @throws {ValidationError} if any partition component is empty after `String()`\n *   or is a non-finite number (`NaN`, `±Infinity`).\n */\nexport function resolveSequenceKey(series: string, opts?: SequenceOptions): string {\n  const partition = opts?.partition\n  if (!partition || partition.length === 0) return series\n  const parts = partition.map((p) => {\n    if (typeof p === 'number' && !Number.isFinite(p)) {\n      throw new ValidationError(`sequence partition component must be a finite number, got ${p}`)\n    }\n    const s = String(p)\n    if (s === '') {\n      throw new ValidationError('sequence partition component must not be empty')\n    }\n    return encodeURIComponent(s)\n  })\n  return `${series}\\x00${parts.join('/')}`\n}\n\nexport interface SequenceHandle {\n  /** Atomically allocate and return the next value (1, 2, 3, …). Deferred series resolve at the next pass. */\n  next(opts?: NextOptions): Promise<number>\n  /** Read the current value without allocating. Returns 0 if never used. */\n  peek(): Promise<number>\n  /**\n   * Set-if-greater: advance the counter to at least `n`. A no-op if the\n   * current value is already `>= n` (so it never rewinds), and `seedTo(0)` is\n   * a no-op. Idempotent and CAS-safe under concurrent `next()` / `seedTo()`.\n   *\n   * Use after a bundle / CSV import to fast-forward the counter past the\n   * highest imported serial, so subsequent `next()` calls cannot re-use a\n   * number that is already on a record.\n   *\n   * Online-only: throws {@link SequenceOfflineError} on a non-CAS store.\n   */\n  seedTo(n: number): Promise<void>\n}\n\nasync function sleepBackoff(attempt: number): Promise<void> {\n  // Exponential backoff with full jitter to break the thundering herd\n  // when many writers contend on the same counter row.\n  const ceil = Math.min(2 ** attempt, 32)\n  const ms = Math.floor(Math.random() * ceil)\n  await new Promise((r) => setTimeout(r, ms))\n}\n\n/** Per-call context the vault assembles to build a {@link SequenceStore}. */\nexport interface SequenceStoreOptions {\n  adapter: NoydbStore\n  vault: string\n  encrypted: boolean\n  getDEK: (collectionName: string) => Promise<EnclaveKey>\n  actor: string\n}\n\nexport class SequenceStore {\n  private readonly adapter: NoydbStore\n  private readonly vault: string\n  private readonly encrypted: boolean\n  private readonly getDEK: (collectionName: string) => Promise<EnclaveKey>\n  private readonly actor: string\n  /**\n   * Memoized DEK promise. The `_sequences` collection DEK is created on\n   * first access; without sharing one promise, a burst of concurrent\n   * `next()` calls would each trigger DEK creation and diverge (one\n   * writer's ciphertext unreadable by another). One shared promise → one\n   * DEK.\n   */\n  private dekPromise: Promise<EnclaveKey> | null = null\n\n  constructor(opts: SequenceStoreOptions) {\n    this.adapter = opts.adapter\n    this.vault = opts.vault\n    this.encrypted = opts.encrypted\n    this.getDEK = opts.getDEK\n    this.actor = opts.actor\n  }\n\n  /** A handle bound to one sequence name. */\n  handle(name: string): SequenceHandle {\n    return {\n      next: () => this.next(name),\n      peek: () => this.peek(name),\n      seedTo: (n) => this.seedTo(name, n),\n    }\n  }\n\n  private assertOnline(): void {\n    if (this.adapter.capabilities?.casAtomic !== true) {\n      throw new SequenceOfflineError()\n    }\n  }\n\n  private dek(): Promise<EnclaveKey> {\n    if (!this.dekPromise) this.dekPromise = this.getDEK(SEQUENCE_COLLECTION)\n    return this.dekPromise\n  }\n\n  private async read(name: string): Promise<{ env: EncryptedEnvelope | null; value: number }> {\n    const env = await this.adapter.get(this.vault, SEQUENCE_COLLECTION, name)\n    if (!env) return { env: null, value: 0 }\n    const json = this.encrypted ? await openEnvelopeJson({ collection: SEQUENCE_COLLECTION, id: name }, env, await this.dek()) : (env._data ?? '')\n    const state = JSON.parse(json) as SequenceState\n    return { env, value: state.value }\n  }\n\n  private async encryptState(name: string, state: SequenceState, version: number): Promise<EncryptedEnvelope> {\n    const json = JSON.stringify(state)\n    if (!this.encrypted) {\n      return buildRecordEnvelope({ collection: SEQUENCE_COLLECTION, id: name, version }, { iv: '', data: json})\n    }\n    const identity = { collection: SEQUENCE_COLLECTION, id: name, version }\n    const { iv, data } = await encrypt(json, await this.dek(), buildRecordAad(identity))\n    return buildRecordEnvelope(identity, { iv, data})\n  }\n\n  async peek(name: string): Promise<number> {\n    return (await this.read(name)).value\n  }\n\n  async next(name: string): Promise<number> {\n    this.assertOnline()\n    let lastConflict: ConflictError | undefined\n    for (let attempt = 0; attempt < MAX_NEXT_ATTEMPTS; attempt++) {\n      const { env, value } = await this.read(name)\n      const nextValue = value + 1\n      const expectedVersion = env?._v ?? 0 // 0 ≡ \"must not yet exist\" (create)\n      const envelope = await this.encryptState(name, { value: nextValue }, expectedVersion + 1)\n      try {\n        await this.adapter.put(this.vault, SEQUENCE_COLLECTION, name, envelope, expectedVersion)\n        return nextValue\n      } catch (err) {\n        if (isConflictError(err)) {\n          lastConflict = err\n          if (attempt < MAX_NEXT_ATTEMPTS - 1) await sleepBackoff(attempt)\n          continue\n        }\n        throw err\n      }\n    }\n    void lastConflict\n    throw new SequenceContentionError(name, MAX_NEXT_ATTEMPTS)\n  }\n\n  async seedTo(name: string, n: number): Promise<void> {\n    this.assertOnline()\n    if (n <= 0) return // set-if-greater: 0 (and any non-positive seed) is a no-op\n    let lastConflict: ConflictError | undefined\n    for (let attempt = 0; attempt < MAX_NEXT_ATTEMPTS; attempt++) {\n      const { env, value } = await this.read(name)\n      if (value >= n) return // already at or past the floor — no write, idempotent\n      const expectedVersion = env?._v ?? 0 // 0 ≡ \"must not yet exist\" (create)\n      const envelope = await this.encryptState(name, { value: n }, expectedVersion + 1)\n      try {\n        await this.adapter.put(this.vault, SEQUENCE_COLLECTION, name, envelope, expectedVersion)\n        return\n      } catch (err) {\n        if (isConflictError(err)) {\n          lastConflict = err\n          if (attempt < MAX_NEXT_ATTEMPTS - 1) await sleepBackoff(attempt)\n          continue\n        }\n        throw err\n      }\n    }\n    void lastConflict\n    throw new SequenceContentionError(name, MAX_NEXT_ATTEMPTS)\n  }\n}\n"],"mappings":"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","names":[]}