@noy-db/hub 0.2.0-pre.21 → 0.2.0-pre.24

package/dist/vault-group-BB246VIM.js

@@ -1,804 +0,0 @@
-import {
-  StateManagementVault
-} from "./chunk-JTI57WRT.js";
-import {
-  STATE_VAULT_NAME
-} from "./chunk-ZC7J6ZYV.js";
-import {
-  groupAndReduce,
-  reduceRecords
-} from "./chunk-JYNH4FIM.js";
-import {
-  readPath
-} from "./chunk-U2XSUCDF.js";
-import "./chunk-TNH5SLCD.js";
-import "./chunk-FZU343FL.js";
-import "./chunk-37VGJM3T.js";
-import {
-  CrossShardJoinError,
-  DataResidencyError,
-  NoAccessError,
-  ReservedVaultNameError,
-  ShardProvisioningError,
-  UnknownShardError,
-  ValidationError
-} from "./chunk-OTWT6BAJ.js";
-
-// src/federation/classify-skip.ts
-function classifyShardSkip(err) {
-  return err instanceof NoAccessError ? "no-grant" : "error";
-}
-
-// src/federation/cross-shard-join.ts
-function coerceKey(value) {
-  if (value === null || value === void 0) return null;
-  if (typeof value === "string") return value;
-  if (typeof value === "number" || typeof value === "bigint") return String(value);
-  return null;
-}
-var warnedBroadcastKeys = /* @__PURE__ */ new Set();
-function warnOnceBroadcastMiss(field, as, key) {
-  const dedup = `${field}\u2192${as}:${key}`;
-  if (warnedBroadcastKeys.has(dedup)) return;
-  warnedBroadcastKeys.add(dedup);
-  console.warn(
-    `[noy-db] broadcastJoin: no "${as}" dimension row for ${field}="${key}". Attaching null. Use mode: 'cascade' to silence.`
-  );
-}
-async function applyBroadcastLegs(rows, legs) {
-  if (legs.length === 0) return [...rows];
-  const indexes = [];
-  for (const leg of legs) {
-    const map = /* @__PURE__ */ new Map();
-    for (const rec of await leg.from.list()) {
-      const k = coerceKey(readPath(rec, leg.on));
-      if (k !== null && !map.has(k)) map.set(k, rec);
-    }
-    indexes.push({ leg, map });
-  }
-  return rows.map((row) => {
-    const out = { ...row };
-    for (const { leg, map } of indexes) {
-      const key = coerceKey(readPath(row, leg.field));
-      const match = key === null ? null : map.get(key) ?? null;
-      if (match === null && leg.mode === "warn") {
-        warnOnceBroadcastMiss(leg.field, leg.as, key ?? "<null>");
-      }
-      out[leg.as] = match;
-    }
-    return out;
-  });
-}
-
-// src/federation/cross-vault-live.ts
-var CrossVaultLive = class {
-  snapshot;
-  error = null;
-  ready;
-  subs = /* @__PURE__ */ new Set();
-  unsubChange;
-  opts;
-  stopped = false;
-  computing = false;
-  dirty = false;
-  scheduled = false;
-  timer = null;
-  resolveReady;
-  settledOnce = false;
-  constructor(opts) {
-    this.opts = opts;
-    this.snapshot = opts.initialSnapshot;
-    this.ready = new Promise((res) => {
-      this.resolveReady = res;
-    });
-    this.unsubChange = opts.subscribeToChanges((e) => {
-      if (this.stopped || !opts.isRelevant(e)) return;
-      this.schedule();
-    });
-    this.schedule();
-  }
-  subscribe(cb) {
-    if (this.stopped) return () => {
-    };
-    this.subs.add(cb);
-    return () => this.subs.delete(cb);
-  }
-  stop() {
-    if (this.stopped) return;
-    this.stopped = true;
-    this.unsubChange();
-    if (this.timer !== null) clearTimeout(this.timer);
-    this.subs.clear();
-    if (!this.settledOnce) this.resolveReady();
-  }
-  schedule() {
-    if (this.stopped) return;
-    if (this.computing) {
-      this.dirty = true;
-      return;
-    }
-    if (this.scheduled) return;
-    this.scheduled = true;
-    const run = () => {
-      this.scheduled = false;
-      void this.runCompute();
-    };
-    const ms = this.opts.debounceMs ?? 0;
-    if (ms > 0) this.timer = setTimeout(run, ms);
-    else queueMicrotask(run);
-  }
-  async runCompute() {
-    if (this.stopped) return;
-    this.computing = true;
-    this.dirty = false;
-    try {
-      const next = await this.opts.compute();
-      if (this.stopped) return;
-      this.snapshot = next;
-      this.error = null;
-    } catch (err) {
-      if (this.stopped) return;
-      this.error = err instanceof Error ? err : new Error(String(err));
-    } finally {
-      this.computing = false;
-      if (!this.stopped) {
-        if (!this.settledOnce) {
-          this.settledOnce = true;
-          this.resolveReady();
-        }
-        for (const cb of this.subs) cb();
-        if (this.dirty) this.schedule();
-      }
-    }
-  }
-};
-
-// src/federation/aggregate-across.ts
-var CrossVaultAggregation = class {
-  constructor(src, spec, bind) {
-    this.src = src;
-    this.spec = spec;
-    this.bind = bind;
-  }
-  src;
-  spec;
-  bind;
-  async run(options = {}) {
-    const { records, skippedVaults } = await this.src.fanoutRecords(options);
-    return { result: reduceRecords(records, this.spec), skippedVaults };
-  }
-  live(options = {}) {
-    if (!this.bind) throw new Error("CrossVaultAggregation: live() requires a LiveBinding \u2014 use ShardedQuery.aggregate()");
-    const spec = this.spec;
-    const src = this.src;
-    const core = new CrossVaultLive({
-      subscribeToChanges: this.bind.subscribeToChanges,
-      isRelevant: this.bind.isRelevant,
-      compute: async () => {
-        const { records, skippedVaults } = await src.fanoutRecords(options);
-        return { value: reduceRecords(records, spec), skipped: skippedVaults };
-      },
-      initialSnapshot: { value: void 0, skipped: [] },
-      ...options.debounceMs !== void 0 ? { debounceMs: options.debounceMs } : {}
-    });
-    return {
-      get value() {
-        return core.snapshot.value;
-      },
-      get skippedVaults() {
-        return core.snapshot.skipped;
-      },
-      get error() {
-        return core.error;
-      },
-      ready: core.ready,
-      subscribe: (cb) => core.subscribe(cb),
-      stop: () => core.stop()
-    };
-  }
-};
-var CrossVaultGroupedAggregation = class {
-  constructor(src, field, spec, bind) {
-    this.src = src;
-    this.field = field;
-    this.spec = spec;
-    this.bind = bind;
-  }
-  src;
-  field;
-  spec;
-  bind;
-  async run(options = {}) {
-    const { records, skippedVaults } = await this.src.fanoutRecords(options);
-    return {
-      results: groupAndReduce(records, this.field, this.spec),
-      skippedVaults
-    };
-  }
-  live(options = {}) {
-    if (!this.bind) throw new Error("CrossVaultGroupedAggregation: live() requires a LiveBinding \u2014 use ShardedQuery.groupBy().aggregate()");
-    const field = this.field;
-    const spec = this.spec;
-    const src = this.src;
-    const core = new CrossVaultLive({
-      subscribeToChanges: this.bind.subscribeToChanges,
-      isRelevant: this.bind.isRelevant,
-      compute: async () => {
-        const { records, skippedVaults } = await src.fanoutRecords(options);
-        return {
-          records: groupAndReduce(records, field, spec),
-          skipped: skippedVaults
-        };
-      },
-      initialSnapshot: { records: [], skipped: [] },
-      ...options.debounceMs !== void 0 ? { debounceMs: options.debounceMs } : {}
-    });
-    return {
-      get value() {
-        return core.snapshot.records;
-      },
-      get skippedVaults() {
-        return core.snapshot.skipped;
-      },
-      get error() {
-        return core.error;
-      },
-      ready: core.ready,
-      subscribe: (cb) => core.subscribe(cb),
-      stop: () => core.stop()
-    };
-  }
-};
-
-// src/federation/vault-group.ts
-var SHARD_SEPARATOR = "--";
-var SAFE_PARTITION_KEY = /^[A-Za-z0-9._-]+$/;
-function assertSafePartitionKey(partitionKey) {
-  if (partitionKey.length === 0) {
-    throw new ValidationError("partitionKey must be a non-empty string");
-  }
-  if (partitionKey === STATE_VAULT_NAME) {
-    throw new ReservedVaultNameError(partitionKey);
-  }
-  if (!SAFE_PARTITION_KEY.test(partitionKey)) {
-    throw new ValidationError(
-      `partitionKey "${partitionKey}" contains characters outside [A-Za-z0-9._-]. Map your records to a store-safe key in sharding.keyOf.`
-    );
-  }
-  if (partitionKey.includes(SHARD_SEPARATOR)) {
-    throw new ValidationError(
-      `partitionKey "${partitionKey}" must not contain "--" \u2014 it is reserved as the shard vault-id separator and would risk shard-id collisions.`
-    );
-  }
-}
-var VaultGroup = class {
-  constructor(db, name, registry, sharding, template, migrateOnOpen = false) {
-    this.db = db;
-    this.name = name;
-    this.registry = registry;
-    this.sharding = sharding;
-    this.template = template;
-    this.migrateOnOpen = migrateOnOpen;
-    if (name.includes(SHARD_SEPARATOR)) {
-      throw new ValidationError(
-        `VaultGroup name "${name}" must not contain "--" (reserved shard vault-id separator).`
-      );
-    }
-  }
-  db;
-  name;
-  registry;
-  sharding;
-  template;
-  migrateOnOpen;
-  /** @internal — set when the group is managed (no explicit registry). */
-  stateVault;
-  /** @internal */
-  _attachStateVault(sv) {
-    this.stateVault = sv;
-  }
-  /** Deterministic vault name for a partition key, namespaced by the group. */
-  shardVaultId(partitionKey) {
-    assertSafePartitionKey(partitionKey);
-    return `${this.name}${SHARD_SEPARATOR}${partitionKey}`;
-  }
-  /**
-   * @internal — group-qualified registry record key (avoids cross-group key
-   * collisions). Identical to the shard vault id by design — the registry row
-   * for a shard is keyed by that shard's vault id — so it delegates to
-   * `shardVaultId`, reusing its partition-key validation.
-   */
-  registryId(partitionKey) {
-    return this.shardVaultId(partitionKey);
-  }
-  /**
-   * Registry rows for THIS group (hydrates the registry collection first).
-   * The registry may be shared across groups (the auto-wired StateManagement
-   * vault holds one `vaultRegistry` for the whole instance), so rows are
-   * filtered by `group` — without this, a group's fan-out reads would leak
-   * across into other groups' shards. Mirrors the `${group}--` scoping that
-   * `liveBinding().isRelevant` already applies to the reactive path.
-   */
-  async allRows() {
-    await this.registry.list();
-    const rows = this.registry.query().toArray();
-    return rows.filter((r) => r.group === this.name);
-  }
-  /**
-   * Open an existing shard and apply the template. When `migrateOnOpen` is set
-   * (#271) and the shard's registry version is behind the template, its cutover
-   * runs inline first — so a behind shard never surfaces a stale handle.
-   */
-  async openShard(partitionKey) {
-    if (this.migrateOnOpen) {
-      const row = await this.registry.get(this.registryId(partitionKey));
-      if (row && row.schemaVersion < this.template.version) {
-        await this.migrateShard(partitionKey);
-      }
-    }
-    return this._openShardRaw(partitionKey);
-  }
-  /** @internal — open + configure with no migrate-on-open hook (used by the migration path itself to avoid recursion). */
-  async _openShardRaw(partitionKey) {
-    const vault = await this.db.openVault(this.shardVaultId(partitionKey), { create: false });
-    this.template.configure(vault);
-    return vault;
-  }
-  /**
-   * Idempotently provision a shard for `partitionKey`. Returns the
-   * configured vault handle.
-   *
-   * - row + vault present → no-op, return handle
-   * - row present, vault gone → ShardProvisioningError
-   * - row absent (vault present or not) → open-or-create, configure, write row
-   *
-   * When `region` is given (the routing `put` passes `sharding.regionOf(record)`),
-   * the candidate backend's `capabilities.region` must match or this throws
-   * `DataResidencyError` BEFORE provisioning (#271 data-residency guard).
-   */
-  async createShard(partitionKey, region) {
-    const vaultId = this.shardVaultId(partitionKey);
-    const row = await this.registry.get(this.registryId(partitionKey));
-    const provisioned = await this.db._shardVaultProvisioned(vaultId);
-    if (row && !provisioned) throw new ShardProvisioningError(vaultId, partitionKey);
-    if (row && provisioned) return this.openShard(partitionKey);
-    if (region !== void 0) {
-      const backendRegion = this.db._resolveBackend(vaultId).capabilities?.region;
-      if (backendRegion !== region) throw new DataResidencyError(vaultId, region, backendRegion);
-    }
-    const vault = await this.db.openVault(vaultId);
-    this.template.configure(vault);
-    await this.registry.put(this.registryId(partitionKey), {
-      vaultId,
-      partitionKey,
-      templateName: this.sharding.vaultTemplate,
-      schemaVersion: this.template.version,
-      createdAt: Date.now(),
-      group: this.name
-    });
-    if (this.stateVault) {
-      try {
-        await this.stateVault.appendEvent({
-          type: "shard-created",
-          group: this.name,
-          vaultId,
-          templateName: this.sharding.vaultTemplate,
-          version: this.template.version
-        });
-      } catch {
-      }
-    }
-    return vault;
-  }
-  /**
-   * Drill down to a single shard's full Collection API. Throws if the shard is unknown.
-   * Also throws ShardProvisioningError if the registry row exists but the vault has been deleted
-   * (registry/store divergence).
-   */
-  async shard(partitionKey) {
-    const vaultId = this.shardVaultId(partitionKey);
-    const row = await this.registry.get(this.registryId(partitionKey));
-    if (!row) throw new UnknownShardError(partitionKey, this.name);
-    const provisioned = await this.db._shardVaultProvisioned(vaultId);
-    if (!provisioned) throw new ShardProvisioningError(vaultId, partitionKey);
-    return this.openShard(partitionKey);
-  }
-  /** A sharded view over one logical collection across all shards. */
-  collection(collectionName) {
-    return new ShardedCollection(this, collectionName);
-  }
-  /** @internal — eligible (openable-candidate) rows + drift/divergence skips. */
-  async resolveEligible(options = {}) {
-    const rows = await this.allRows();
-    const skipped = [];
-    const versionOk = [];
-    for (const row of rows) {
-      if (options.minVersion !== void 0 && row.schemaVersion < options.minVersion) {
-        skipped.push({ vaultId: row.vaultId, reason: "schema-drift" });
-      } else versionOk.push(row);
-    }
-    const provisioned = await Promise.all(versionOk.map((r) => this.db._shardVaultProvisioned(r.vaultId)));
-    const eligible = [];
-    versionOk.forEach((row, i) => {
-      if (provisioned[i]) eligible.push(row);
-      else skipped.push({ vaultId: row.vaultId, reason: "error", error: new ShardProvisioningError(row.vaultId, row.partitionKey) });
-    });
-    return { eligible, skipped };
-  }
-  /** @internal — registered push-model cross-vault derivations (#271 Insight Vault). */
-  crossVaultDerivations = [];
-  /**
-   * Register a push-model cross-vault derivation — the Insight Vault pattern
-   * (#271, Layer 4). Drive it with {@link refreshInsights}.
-   *
-   * For each shard, `derive(records, ctx)` runs on that shard's `source`
-   * records and its return value is written into the analytics
-   * (`target.vault` / `target.collection`) vault, keyed by partition key —
-   * one summary row per shard. The derivation runs in-process under THIS
-   * group's `Noydb` (which already holds both the shard and Insight Vault
-   * keyrings); the shard's decrypted records are reduced to a summary that is
-   * re-encrypted under the Insight Vault's own DEK, so no shard ciphertext
-   * crosses a DEK boundary.
-   *
-   * **Zero-knowledge note:** the Insight Vault backend sees aggregated
-   * structure (totals, counts, timestamps) drawn from many shards — a weaker
-   * ZK profile than the per-shard vaults. Opt-in; keep summaries to aggregate
-   * scalars (no embeddings / no raw records).
-   *
-   * v1 is explicit-refresh (no write-path push); call `refreshInsights()`
-   * after a batch of writes, or on a schedule.
-   *
-   * The `target.vault` must NOT be the group itself or one of its shards —
-   * a summary writing back into client-shard data would breach the Insight
-   * Vault's separate-DEK-boundary contract. Such a target throws a
-   * `ValidationError` at registration (#271 Insight-write isolation).
-   */
-  withCrossVaultDerivation(spec) {
-    const target = spec.target.vault;
-    if (target === this.name || target.startsWith(`${this.name}${SHARD_SEPARATOR}`)) {
-      throw new ValidationError(
-        `withCrossVaultDerivation: target.vault "${target}" is the "${this.name}" group itself or one of its shards \u2014 an Insight summary must target a SEPARATE analytics vault, never write back into client-shard data (it would breach the per-shard DEK boundary). Use a distinct vault name.`
-      );
-    }
-    this.crossVaultDerivations.push(spec);
-  }
-  /**
-   * Run every registered {@link withCrossVaultDerivation}: read each eligible
-   * shard's source records, derive a per-shard summary, and write it into the
-   * Insight Vault keyed by partition key. Shards behind `minVersion`,
-   * unprovisioned, or whose read errors are reported in `skippedVaults` and
-   * are not written (a stale summary is never left behind for a failed shard).
-   */
-  async refreshInsights(options = {}) {
-    if (this.crossVaultDerivations.length === 0) return { written: 0, skippedVaults: [] };
-    const { eligible, skipped } = await this.resolveEligible(
-      options.minVersion !== void 0 ? { minVersion: options.minVersion } : {}
-    );
-    let written = 0;
-    for (const spec of this.crossVaultDerivations) {
-      const results = await this.db.queryAcross(
-        eligible.map((r) => r.vaultId),
-        async (vault) => {
-          this.template.configure(vault);
-          return vault.collection(spec.source).list();
-        },
-        { create: false, ...options.concurrency !== void 0 ? { concurrency: options.concurrency } : {} }
-      );
-      const insight = await this.db.openVault(spec.target.vault);
-      const out = insight.collection(spec.target.collection);
-      for (let i = 0; i < eligible.length; i++) {
-        const row = eligible[i];
-        const res = results[i];
-        if (!res || res.result === void 0) {
-          skipped.push({ vaultId: row.vaultId, reason: "error", ...res?.error ? { error: res.error } : {} });
-          continue;
-        }
-        const ctx = {
-          vaultId: row.vaultId,
-          partitionKey: row.partitionKey,
-          schemaVersion: row.schemaVersion
-        };
-        const summary = spec.derive(res.result, ctx);
-        await out.put(row.partitionKey, summary);
-        written++;
-      }
-    }
-    return { written, skippedVaults: skipped };
-  }
-  /** @internal — the control-plane vault for migration status; lazily opened. */
-  async ensureStateVault() {
-    if (!this.stateVault) this.stateVault = await StateManagementVault.open(this.db);
-    return this.stateVault;
-  }
-  /**
-   * Migrate ONE shard to the template's current version (#271 fleet runner,
-   * per-shard step). Opens the shard (applying the template, which arms the
-   * M12 cutover), drains schema-write detection, runs `vault.runSchemaCutover()`
-   * (the per-vault drain-barrier-transform protocol), then advances the
-   * registry row's `schemaVersion` and records `migration-status`. A shard
-   * already at the template version is a no-op (`status: 'done'`, migrated 0).
-   * Never throws on a cutover failure — it records `status: 'failed'` and
-   * returns the row, so a fleet run continues past a bad shard.
-   */
-  async migrateShard(partitionKey) {
-    const vaultId = this.shardVaultId(partitionKey);
-    const row = await this.registry.get(this.registryId(partitionKey));
-    if (!row) throw new UnknownShardError(partitionKey, this.name);
-    const target = this.template.version;
-    const sv = await this.ensureStateVault();
-    const base = { vaultId, group: this.name, currentVersion: row.schemaVersion, targetVersion: target };
-    if (row.schemaVersion >= target) {
-      const done = { ...base, status: "done", migrated: 0, finishedAt: Date.now() };
-      await sv.upsertMigrationStatus(done);
-      return done;
-    }
-    await sv.upsertMigrationStatus({ ...base, status: "running", startedAt: Date.now() });
-    try {
-      await sv.appendEvent({ type: "migration-started", group: this.name, vaultId, version: target });
-    } catch {
-    }
-    try {
-      const vault = await this._openShardRaw(partitionKey);
-      await vault._drainPendingSchemaWrites();
-      const { migrated } = await vault.runSchemaCutover();
-      await this.registry.put(this.registryId(partitionKey), { ...row, schemaVersion: target });
-      const done = { ...base, currentVersion: target, status: "done", migrated, finishedAt: Date.now() };
-      await sv.upsertMigrationStatus(done);
-      try {
-        await sv.appendEvent({ type: "migration-completed", group: this.name, vaultId, version: target });
-      } catch {
-      }
-      return done;
-    } catch (err) {
-      const error = err instanceof Error ? err.message : String(err);
-      const failed = { ...base, status: "failed", error, finishedAt: Date.now() };
-      await sv.upsertMigrationStatus(failed);
-      try {
-        await sv.appendEvent({ type: "migration-failed", group: this.name, vaultId, version: target, detail: error });
-      } catch {
-      }
-      return failed;
-    }
-  }
-  /**
-   * Active batch runner (#271): migrate every shard behind the template version
-   * to it, in controlled batches. **Resumable + crash-safe** — shards already at
-   * the target are skipped (the registry version is the source of truth), so a
-   * re-run after a crash only picks up the unfinished + previously-failed shards.
-   *
-   * - `cohort` — restrict to these partition keys (the staged / canary rollout:
-   *   migrate a small cohort, verify the Insight Vault, then run the rest).
-   * - `batchSize` — max shards migrated concurrently per batch (back-pressure).
-   *   Default 4. Batches run sequentially; shards within a batch run in parallel.
-   */
-  async migrateFleet(options = {}) {
-    const target = this.template.version;
-    const rows = await this.allRows();
-    const cohort = options.cohort;
-    const todo = rows.filter(
-      (r) => r.schemaVersion < target && (cohort === void 0 || cohort.includes(r.partitionKey))
-    );
-    const batchSize = Math.max(1, options.batchSize ?? 4);
-    const migrated = [];
-    const failed = [];
-    for (let i = 0; i < todo.length; i += batchSize) {
-      const batch = todo.slice(i, i + batchSize);
-      const settled = await Promise.all(batch.map((r) => this.migrateShard(r.partitionKey)));
-      for (const res of settled) {
-        if (res.status === "done") migrated.push(res.vaultId);
-        else failed.push({ vaultId: res.vaultId, error: res.error ?? "unknown" });
-      }
-    }
-    return { target, migrated, failed };
-  }
-};
-var ShardedCollection = class {
-  constructor(group, collectionName) {
-    this.group = group;
-    this.collectionName = collectionName;
-  }
-  group;
-  collectionName;
-  /** Route a write to the shard owning `keyOf(record)`. */
-  async put(id, record) {
-    const key = this.group.sharding.keyOf(record);
-    const row = await this.group.registry.get(this.group.registryId(key));
-    let vault;
-    if (!row) {
-      if (this.group.sharding.autoCreate === false) {
-        throw new UnknownShardError(key, this.group.name);
-      }
-      vault = await this.group.createShard(key, this.group.sharding.regionOf?.(record));
-    } else {
-      vault = await this.group.openShard(key);
-    }
-    await vault.collection(this.collectionName).put(id, record);
-  }
-  /** Begin a cross-shard fan-out query. */
-  query() {
-    return new ShardedQuery(this.group, this.collectionName, []);
-  }
-};
-var ShardedQuery = class _ShardedQuery {
-  constructor(group, collectionName, clauses, coPartitionedLegs = [], broadcastLegs = []) {
-    this.group = group;
-    this.collectionName = collectionName;
-    this.clauses = clauses;
-    this.coPartitionedLegs = coPartitionedLegs;
-    this.broadcastLegs = broadcastLegs;
-  }
-  group;
-  collectionName;
-  clauses;
-  coPartitionedLegs;
-  broadcastLegs;
-  where(field, op, value) {
-    return new _ShardedQuery(
-      this.group,
-      this.collectionName,
-      [...this.clauses, { field, op, value }],
-      this.coPartitionedLegs,
-      this.broadcastLegs
-    );
-  }
-  /** Co-partitioned join: each shard joins its own same-vault right collection (resolved via ref()), then union. */
-  crossShardJoin(field, opts) {
-    const leg = { field, as: opts.as, maxRows: opts.maxRows, strategy: opts.strategy };
-    return new _ShardedQuery(
-      this.group,
-      this.collectionName,
-      this.clauses,
-      [...this.coPartitionedLegs, leg],
-      this.broadcastLegs
-    );
-  }
-  /** Broadcast dimension join: enrich every merged row from a single shared collection. */
-  broadcastJoin(field, opts) {
-    const leg = {
-      field,
-      as: opts.as,
-      from: opts.from,
-      on: opts.on ?? "id",
-      mode: opts.mode ?? "warn"
-    };
-    return new _ShardedQuery(
-      this.group,
-      this.collectionName,
-      this.clauses,
-      this.coPartitionedLegs,
-      [...this.broadcastLegs, leg]
-    );
-  }
-  /** @internal — fan out the where-filtered records across eligible shards. */
-  async fanoutRecords(options = {}) {
-    const { eligible, skipped } = await this.group.resolveEligible(options);
-    const probeRow = eligible[0];
-    if (this.coPartitionedLegs.length > 0 && probeRow) {
-      const probe = await this.group.openShard(probeRow.partitionKey);
-      this.group.template.configure(probe);
-      for (const leg of this.coPartitionedLegs) {
-        if (!probe.resolveRef(this.collectionName, leg.field)) {
-          throw new CrossShardJoinError(
-            `crossShardJoin("${leg.field}"): no ref() declared for "${leg.field}" on collection "${this.collectionName}" in template "${this.group.sharding.vaultTemplate}". Add refs: { ${leg.field}: ref('<target>') } to the template's collection options.`
-          );
-        }
-      }
-    }
-    const across = await this.group.db.queryAcross(
-      eligible.map((r) => r.vaultId),
-      async (vault) => {
-        this.group.template.configure(vault);
-        const coll = vault.collection(this.collectionName);
-        await coll.list();
-        for (const leg of this.coPartitionedLegs) {
-          const desc = vault.resolveRef(this.collectionName, leg.field);
-          if (desc) await vault.collection(desc.target).list();
-        }
-        let q = coll.query();
-        for (const c of this.clauses) q = q.where(c.field, c.op, c.value);
-        for (const leg of this.coPartitionedLegs) {
-          q = q.join(leg.field, {
-            as: leg.as,
-            ...leg.maxRows !== void 0 ? { maxRows: leg.maxRows } : {},
-            ...leg.strategy ? { strategy: leg.strategy } : {}
-          });
-        }
-        return q.toArray();
-      },
-      { concurrency: options.concurrency ?? 1, create: false }
-    );
-    const results = [];
-    for (const r of across) {
-      if (r.error) skipped.push({ vaultId: r.vault, reason: classifyShardSkip(r.error), error: r.error });
-      else for (const item of r.result) results.push(item);
-    }
-    return { records: results, skippedVaults: skipped };
-  }
-  /** Fan out across eligible shards, merge, then apply any broadcast dimension legs. */
-  async toArray(options = {}) {
-    const { records, skippedVaults } = await this.fanoutRecords(options);
-    const results = await applyBroadcastLegs(records, this.broadcastLegs);
-    return { results, skippedVaults };
-  }
-  /** @internal — build the change-subscription + relevance binding for this query's group+collection. */
-  liveBinding() {
-    const group = this.group;
-    const collectionName = this.collectionName;
-    return {
-      subscribeToChanges: (h) => {
-        group.db.on("change", h);
-        return () => group.db.off("change", h);
-      },
-      isRelevant: (e) => e.collection === collectionName && e.vault.startsWith(`${group.name}--`)
-    };
-  }
-  /** @internal — joined queries don't support reactive/aggregate surfaces in v1. */
-  assertNoJoinLegs(surface) {
-    if (this.coPartitionedLegs.length || this.broadcastLegs.length) {
-      throw new CrossShardJoinError(
-        `${surface}() is not supported on a ShardedQuery with crossShardJoin/broadcastJoin legs in v1. Use toArray() for joined cross-shard queries.`
-      );
-    }
-  }
-  /** Returns a reactive cross-shard live query — a facade over CrossVaultLive. */
-  live(options = {}) {
-    this.assertNoJoinLegs("live");
-    const bind = this.liveBinding();
-    const core = new CrossVaultLive({
-      ...bind,
-      compute: async () => {
-        const { records, skippedVaults } = await this.fanoutRecords(options);
-        return { records, skipped: skippedVaults };
-      },
-      initialSnapshot: { records: [], skipped: [] },
-      ...options.debounceMs !== void 0 ? { debounceMs: options.debounceMs } : {}
-    });
-    return {
-      get value() {
-        return core.snapshot.records;
-      },
-      get skippedVaults() {
-        return core.snapshot.skipped;
-      },
-      get error() {
-        return core.error;
-      },
-      ready: core.ready,
-      subscribe: (cb) => core.subscribe(cb),
-      stop: () => core.stop()
-    };
-  }
-  /** One-shot distributed aggregate — central reduce over all shard records. */
-  aggregate(spec) {
-    this.assertNoJoinLegs("aggregate");
-    return new CrossVaultAggregation(this, spec, this.liveBinding());
-  }
-  /** Begin a grouped cross-shard aggregate. */
-  groupBy(field) {
-    this.assertNoJoinLegs("groupBy");
-    return new ShardedGroupedQuery(this, field);
-  }
-};
-var ShardedGroupedQuery = class {
-  constructor(query, field) {
-    this.query = query;
-    this.field = field;
-  }
-  query;
-  field;
-  aggregate(spec) {
-    return new CrossVaultGroupedAggregation(
-      { fanoutRecords: (o) => this.query.fanoutRecords(o) },
-      this.field,
-      spec,
-      this.query.liveBinding()
-    );
-  }
-};
-export {
-  ShardedCollection,
-  ShardedGroupedQuery,
-  ShardedQuery,
-  VaultGroup
-};
-//# sourceMappingURL=vault-group-BB246VIM.js.map