@noy-db/hub 0.2.0-pre.16 → 0.2.0-pre.18

package/dist/{vault-group-DX2HFQMX.js → vault-group-DPZVFRI5.js}

@@ -1,13 +1,18 @@
+import {
+  StateManagementVault
+} from "./chunk-ZJ67TB4S.js";
 import {
   STATE_VAULT_NAME
 } from "./chunk-ZC7J6ZYV.js";
 import {
   groupAndReduce,
   reduceRecords
-} from "./chunk-L2BNJ6HM.js";
+} from "./chunk-32XVU2LT.js";
 import {
   readPath
-} from "./chunk-CJORTUJ2.js";
+} from "./chunk-RZWQNMMP.js";
+import "./chunk-FZU343FL.js";
+import "./chunk-QJKZ5WUP.js";
 import {
   CrossShardJoinError,
   NoAccessError,
@@ -15,7 +20,7 @@ import {
   ShardProvisioningError,
   UnknownShardError,
   ValidationError
-} from "./chunk-535SSHBS.js";
+} from "./chunk-HMFC6M2G.js";
 
 // src/federation/classify-skip.ts
 function classifyShardSkip(err) {
@@ -265,12 +270,13 @@ function assertSafePartitionKey(partitionKey) {
   }
 }
 var VaultGroup = class {
-  constructor(db, name, registry, sharding, template) {
+  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).`
@@ -282,6 +288,7 @@ var VaultGroup = class {
   registry;
   sharding;
   template;
+  migrateOnOpen;
   /** @internal — set when the group is managed (no explicit registry). */
   stateVault;
   /** @internal */
@@ -315,8 +322,22 @@ var VaultGroup = class {
     const rows = this.registry.query().toArray();
     return rows.filter((r) => r.group === this.name);
   }
-  /** Open an existing shard and apply the template. */
+  /**
+   * 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;
@@ -394,6 +415,161 @@ var VaultGroup = class {
     });
     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.
+   */
+  withCrossVaultDerivation(spec) {
+    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) {
@@ -604,4 +780,4 @@ export {
   ShardedQuery,
   VaultGroup
 };
-//# sourceMappingURL=vault-group-DX2HFQMX.js.map
+//# sourceMappingURL=vault-group-DPZVFRI5.js.map

package/dist/vault-group-DPZVFRI5.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/federation/classify-skip.ts","../src/federation/cross-shard-join.ts","../src/federation/cross-vault-live.ts","../src/federation/aggregate-across.ts","../src/federation/vault-group.ts"],"sourcesContent":["import { NoAccessError } from '../errors.js'\nimport type { SkippedVault } from './types.js'\n\n/**\n * Classify a per-shard fan-out failure. `NoAccessError` (no keyring envelope for\n * the calling identity) is the unambiguous not-granted signal → `'no-grant'`\n * (expected under scoped access, not a fault). Everything else → `'error'` —\n * `InvalidKeyError`/`DecryptionError`/`KeyringCorruptError` can mean \"wrong KEK\n * OR whole-file corruption\" per loadKeyring, so they must not hide as no-grant.\n */\nexport function classifyShardSkip(err: Error): Exclude<SkippedVault['reason'], 'schema-drift'> {\n  return err instanceof NoAccessError ? 'no-grant' : 'error'\n}\n","/**\n * @category capability\n * crossShardJoin — co-partitioned + broadcast dimension join for\n * ShardedQuery. Spec:\n * docs/superpowers/specs/2026-06-09-cross-shard-join-design.md.\n *\n * This module owns the BROADCAST half (central, post-merge map-attach)\n * and the leg type definitions. The CO-PARTITIONED half is threaded\n * into the existing intra-vault `.join()` from vault-group.ts — see\n * ShardedQuery.fanoutRecords. join.ts is deliberately untouched.\n */\nimport { readPath } from '../query/predicate.js'\nimport type { JoinStrategy } from '../query/join.js'\n\n/** Public options for `ShardedQuery.crossShardJoin`. */\nexport interface CrossShardJoinOptions {\n  /** Alias key under which the joined same-shard record attaches. */\n  readonly as: string\n  /** Per-shard row ceiling override (default DEFAULT_JOIN_MAX_ROWS). */\n  readonly maxRows?: number\n  /** Planner strategy override, passed through to intra-vault `.join()`. */\n  readonly strategy?: JoinStrategy\n}\n\n/**\n * Minimal structural shape of a broadcast dimension source. A\n * `Collection` satisfies this natively: `list()` hydrates and returns\n * the decoded records. Kept as a one-method interface so plain test\n * sources are trivial to construct.\n */\nexport interface BroadcastSource {\n  list(): Promise<readonly unknown[]>\n}\n\n/** Public options for `ShardedQuery.broadcastJoin`. */\nexport interface BroadcastJoinOptions {\n  /** Alias key under which the dimension record attaches. */\n  readonly as: string\n  /** The shared dimension collection (an opened handle in another vault). */\n  readonly from: BroadcastSource\n  /** Right-side key to match `field` against. Default 'id'. */\n  readonly on?: string\n  /** Miss behavior. 'warn' (default) attaches null + one-shot warning; 'cascade' is silent. */\n  readonly mode?: 'warn' | 'cascade'\n}\n\n/** Internal co-partitioned leg carried on ShardedQuery. */\nexport interface CoPartitionedLeg {\n  readonly field: string\n  readonly as: string\n  readonly maxRows: number | undefined\n  readonly strategy: JoinStrategy | undefined\n}\n\n/** Internal broadcast leg carried on ShardedQuery. */\nexport interface BroadcastLeg {\n  readonly field: string\n  readonly as: string\n  readonly from: BroadcastSource\n  readonly on: string\n  readonly mode: 'warn' | 'cascade'\n}\n\n/**\n * Coerce an unknown key value into a lookup string. Mirrors join.ts's\n * private `coerceRefKey` (string → string; number/bigint → String;\n * else null) — re-implemented locally to keep join.ts literally\n * untouched.\n */\nfunction coerceKey(value: unknown): string | null {\n  if (value === null || value === undefined) return null\n  if (typeof value === 'string') return value\n  if (typeof value === 'number' || typeof value === 'bigint') return String(value)\n  return null\n}\n\n/** One-shot warn dedup for broadcast misses, keyed by `field→as`. */\nconst warnedBroadcastKeys = new Set<string>()\nfunction warnOnceBroadcastMiss(field: string, as: string, key: string): void {\n  const dedup = `${field}→${as}:${key}`\n  if (warnedBroadcastKeys.has(dedup)) return\n  warnedBroadcastKeys.add(dedup)\n  console.warn(\n    `[noy-db] broadcastJoin: no \"${as}\" dimension row for ${field}=\"${key}\". ` +\n      `Attaching null. Use mode: 'cascade' to silence.`,\n  )\n}\n\n/** Test-only reset for the broadcast warn dedup set. */\nexport function resetBroadcastWarnings(): void {\n  warnedBroadcastKeys.clear()\n}\n\n/**\n * Apply every broadcast leg to a merged row set, centrally. Each leg's\n * source is snapshotted ONCE, indexed by its `on` key, then every row\n * gets `{ [as]: match ?? null }`. Returns fresh top-level objects.\n */\nexport async function applyBroadcastLegs(\n  rows: readonly unknown[],\n  legs: readonly BroadcastLeg[],\n): Promise<unknown[]> {\n  if (legs.length === 0) return [...rows]\n\n  // Build one index per leg (list() once per source).\n  const indexes: { leg: BroadcastLeg; map: Map<string, unknown> }[] = []\n  for (const leg of legs) {\n    const map = new Map<string, unknown>()\n    for (const rec of await leg.from.list()) {\n      const k = coerceKey(readPath(rec, leg.on))\n      if (k !== null && !map.has(k)) map.set(k, rec)\n    }\n    indexes.push({ leg, map })\n  }\n\n  return rows.map((row) => {\n    const out = { ...(row as Record<string, unknown>) }\n    for (const { leg, map } of indexes) {\n      const key = coerceKey(readPath(row, leg.field))\n      const match = key === null ? null : map.get(key) ?? null\n      if (match === null && leg.mode === 'warn') {\n        warnOnceBroadcastMiss(leg.field, leg.as, key ?? '<null>')\n      }\n      out[leg.as] = match\n    }\n    return out\n  })\n}\n","/**\n * @category capability\n * Reactive core for cross-vault live queries/aggregations. Generic over a\n * snapshot S. Single-flight + microtask-coalesced recompute on relevant\n * change. Mirrors the LiveQuery/LiveAggregation contracts via facades.\n * Spec: docs/superpowers/specs/2026-06-07-cross-vault-live-and-aggregate-design.md.\n */\nimport type { ChangeEvent } from '../types.js'\n\nexport interface CrossVaultLiveOptions<S> {\n  readonly subscribeToChanges: (handler: (e: ChangeEvent) => void) => () => void\n  readonly isRelevant: (e: ChangeEvent) => boolean\n  readonly compute: () => Promise<S>\n  readonly initialSnapshot: S\n  readonly debounceMs?: number\n}\n\nexport class CrossVaultLive<S> {\n  snapshot: S\n  error: Error | null = null\n  readonly ready: Promise<void>\n\n  private readonly subs = new Set<() => void>()\n  private readonly unsubChange: () => void\n  private readonly opts: CrossVaultLiveOptions<S>\n  private stopped = false\n  private computing = false\n  private dirty = false\n  private scheduled = false\n  private timer: ReturnType<typeof setTimeout> | null = null\n  private resolveReady!: () => void\n  private settledOnce = false\n\n  constructor(opts: CrossVaultLiveOptions<S>) {\n    this.opts = opts\n    this.snapshot = opts.initialSnapshot\n    this.ready = new Promise<void>((res) => { this.resolveReady = res })\n    this.unsubChange = opts.subscribeToChanges((e) => {\n      if (this.stopped || !opts.isRelevant(e)) return\n      this.schedule()\n    })\n    this.schedule() // initial compute\n  }\n\n  subscribe(cb: () => void): () => void {\n    if (this.stopped) return () => {}\n    this.subs.add(cb)\n    return () => this.subs.delete(cb)\n  }\n\n  stop(): void {\n    if (this.stopped) return\n    this.stopped = true\n    this.unsubChange()\n    if (this.timer !== null) clearTimeout(this.timer)\n    this.subs.clear()\n    if (!this.settledOnce) this.resolveReady() // never leave ready dangling\n  }\n\n  private schedule(): void {\n    if (this.stopped) return\n    if (this.computing) { this.dirty = true; return }\n    if (this.scheduled) return\n    this.scheduled = true\n    const run = () => { this.scheduled = false; void this.runCompute() }\n    const ms = this.opts.debounceMs ?? 0\n    if (ms > 0) this.timer = setTimeout(run, ms)\n    // queueMicrotask is non-cancellable; the `if (this.stopped) return` guard at the top of runCompute makes a post-stop fire a no-op.\n    else queueMicrotask(run)\n  }\n\n  private async runCompute(): Promise<void> {\n    if (this.stopped) return\n    this.computing = true\n    this.dirty = false\n    try {\n      const next = await this.opts.compute()\n      if (this.stopped) return\n      this.snapshot = next\n      this.error = null\n    } catch (err) {\n      if (this.stopped) return\n      this.error = err instanceof Error ? err : new Error(String(err))\n    } finally {\n      this.computing = false\n      if (!this.stopped) {\n        if (!this.settledOnce) { this.settledOnce = true; this.resolveReady() }\n        for (const cb of this.subs) cb()\n        if (this.dirty) this.schedule()\n      }\n    }\n  }\n}\n","/**\n * @category capability\n * One-shot distributed aggregate wrappers for cross-vault fan-out.\n * Central-reduce: all shard records are concatenated and reduced in one pass\n * so avg/mean values are computed over the full union, not as avg-of-avgs.\n * Spec: docs/superpowers/specs/2026-06-07-cross-vault-live-and-aggregate-design.md.\n */\nimport { reduceRecords } from '../aggregate/aggregation.js'\nimport { groupAndReduce } from '../aggregate/groupby.js'\nimport type { AggregateResult, AggregateSpec } from '../aggregate/aggregation.js'\nimport type {\n  FanoutQueryOptions,\n  SkippedVault,\n  GroupedRow,\n  LiveQueryOptions,\n  CrossVaultLiveAggregation,\n  CrossVaultLiveQuery,\n} from './types.js'\nimport { CrossVaultLive } from './cross-vault-live.js'\nimport type { ChangeEvent } from '../types.js'\n\n/** A source that can fan out records across shards. Satisfied by ShardedQuery. */\nexport interface FanoutRecordSource<R> {\n  fanoutRecords(options: FanoutQueryOptions): Promise<{ records: R[]; skippedVaults: SkippedVault[] }>\n}\n\n/** Live-binding hooks (change subscription + relevance) threaded from ShardedQuery. */\nexport interface LiveBinding {\n  subscribeToChanges: (handler: (e: ChangeEvent) => void) => () => void\n  isRelevant: (e: ChangeEvent) => boolean\n}\n\n/**\n * One-shot cross-vault aggregate. Concatenates all shard records and runs a\n * single central reduce, ensuring correct avg/mean values.\n */\nexport class CrossVaultAggregation<R, Spec extends AggregateSpec> {\n  constructor(\n    private readonly src: FanoutRecordSource<R>,\n    private readonly spec: Spec,\n    private readonly bind?: LiveBinding,\n  ) {}\n\n  async run(options: FanoutQueryOptions = {}): Promise<{\n    result: AggregateResult<Spec>\n    skippedVaults: SkippedVault[]\n  }> {\n    const { records, skippedVaults } = await this.src.fanoutRecords(options)\n    return { result: reduceRecords(records, this.spec), skippedVaults }\n  }\n\n  live(options: LiveQueryOptions = {}): CrossVaultLiveAggregation<AggregateResult<Spec>> {\n    if (!this.bind) throw new Error('CrossVaultAggregation: live() requires a LiveBinding — use ShardedQuery.aggregate()')\n    const spec = this.spec\n    const src = this.src\n    const core = new CrossVaultLive<{ value: AggregateResult<Spec> | undefined; skipped: SkippedVault[] }>({\n      subscribeToChanges: this.bind.subscribeToChanges,\n      isRelevant: this.bind.isRelevant,\n      compute: async () => {\n        const { records, skippedVaults } = await src.fanoutRecords(options)\n        return { value: reduceRecords(records, spec), skipped: skippedVaults }\n      },\n      initialSnapshot: { value: undefined, skipped: [] },\n      ...(options.debounceMs !== undefined ? { debounceMs: options.debounceMs } : {}),\n    })\n    return {\n      get value() { return core.snapshot.value },\n      get skippedVaults() { return core.snapshot.skipped as readonly SkippedVault[] },\n      get error() { return core.error },\n      ready: core.ready,\n      subscribe: (cb) => core.subscribe(cb),\n      stop: () => core.stop(),\n    }\n  }\n}\n\n/**\n * One-shot cross-vault grouped aggregate. Concatenates all shard records and\n * runs a single central group-and-reduce, emitting one row per bucket.\n */\nexport class CrossVaultGroupedAggregation<R, F extends string, Spec extends AggregateSpec> {\n  constructor(\n    private readonly src: FanoutRecordSource<R>,\n    private readonly field: F,\n    private readonly spec: Spec,\n    private readonly bind?: LiveBinding,\n  ) {}\n\n  async run(options: FanoutQueryOptions = {}): Promise<{\n    results: GroupedRow<F, Spec>[]\n    skippedVaults: SkippedVault[]\n  }> {\n    const { records, skippedVaults } = await this.src.fanoutRecords(options)\n    return {\n      results: groupAndReduce<GroupedRow<F, Spec>>(records, this.field, this.spec),\n      skippedVaults,\n    }\n  }\n\n  live(options: LiveQueryOptions = {}): CrossVaultLiveQuery<GroupedRow<F, Spec>> {\n    if (!this.bind) throw new Error('CrossVaultGroupedAggregation: live() requires a LiveBinding — use ShardedQuery.groupBy().aggregate()')\n    const field = this.field\n    const spec = this.spec\n    const src = this.src\n    const core = new CrossVaultLive<{ records: GroupedRow<F, Spec>[]; skipped: SkippedVault[] }>({\n      subscribeToChanges: this.bind.subscribeToChanges,\n      isRelevant: this.bind.isRelevant,\n      compute: async () => {\n        const { records, skippedVaults } = await src.fanoutRecords(options)\n        return {\n          records: groupAndReduce<GroupedRow<F, Spec>>(records, field, spec),\n          skipped: skippedVaults,\n        }\n      },\n      initialSnapshot: { records: [], skipped: [] },\n      ...(options.debounceMs !== undefined ? { debounceMs: options.debounceMs } : {}),\n    })\n    return {\n      get value() { return core.snapshot.records as readonly GroupedRow<F, Spec>[] },\n      get skippedVaults() { return core.snapshot.skipped as readonly SkippedVault[] },\n      get error() { return core.error },\n      ready: core.ready,\n      subscribe: (cb) => core.subscribe(cb),\n      stop: () => core.stop(),\n    }\n  }\n}\n","/**\n * @category capability\n * Multi-vault partition federation — VaultGroup transparent shard\n * routing. Spec:\n * docs/superpowers/specs/2026-06-07-mvf-vaultgroup-routing-mvp-design.md.\n */\nimport type { Noydb } from '../noydb.js'\nimport type { Vault } from '../vault.js'\nimport type { Collection } from '../collection.js'\nimport { StateManagementVault } from './state-vault.js'\nimport { CrossShardJoinError, ReservedVaultNameError, ShardProvisioningError, UnknownShardError, ValidationError } from '../errors.js'\nimport { STATE_VAULT_NAME } from './constants.js'\nimport { classifyShardSkip } from './classify-skip.js'\nimport { applyBroadcastLegs } from './cross-shard-join.js'\nimport type { CoPartitionedLeg, BroadcastLeg, CrossShardJoinOptions, BroadcastJoinOptions } from './cross-shard-join.js'\nimport { CrossVaultLive } from './cross-vault-live.js'\nimport { CrossVaultAggregation, CrossVaultGroupedAggregation } from './aggregate-across.js'\nimport type { FanoutRecordSource, LiveBinding } from './aggregate-across.js'\nimport type { AggregateSpec } from '../aggregate/aggregation.js'\nimport type {\n  ShardingConfig,\n  VaultRegistryRow,\n  VaultTemplate,\n  FanoutQueryOptions,\n  FanoutResult,\n  SkippedVault,\n  WhereClause,\n  LiveQueryOptions,\n  CrossVaultLiveQuery,\n  CrossVaultDerivationSpec,\n  CrossVaultDerivationContext,\n  RefreshInsightsResult,\n  MigrationStatusRow,\n  FleetMigrationResult,\n} from './types.js'\n\n/** Reserved separator between group name and partition key in a shard vault id. */\nconst SHARD_SEPARATOR = '--'\n/** Store-safe partition-key charset (single hyphens OK; '--' is the reserved separator). */\nconst SAFE_PARTITION_KEY = /^[A-Za-z0-9._-]+$/\n\nfunction assertSafePartitionKey(partitionKey: string): void {\n  if (partitionKey.length === 0) {\n    throw new ValidationError('partitionKey must be a non-empty string')\n  }\n  if (partitionKey === STATE_VAULT_NAME) {\n    throw new ReservedVaultNameError(partitionKey)\n  }\n  if (!SAFE_PARTITION_KEY.test(partitionKey)) {\n    throw new ValidationError(\n      `partitionKey \"${partitionKey}\" contains characters outside [A-Za-z0-9._-]. ` +\n        `Map your records to a store-safe key in sharding.keyOf.`,\n    )\n  }\n  if (partitionKey.includes(SHARD_SEPARATOR)) {\n    throw new ValidationError(\n      `partitionKey \"${partitionKey}\" must not contain \"--\" — it is reserved as the ` +\n        `shard vault-id separator and would risk shard-id collisions.`,\n    )\n  }\n}\n\nexport class VaultGroup<T> {\n  constructor(\n    /** @internal */ readonly db: Noydb,\n    /** @internal */ readonly name: string,\n    /** @internal */ readonly registry: Collection<VaultRegistryRow>,\n    /** @internal */ readonly sharding: ShardingConfig<T>,\n    /** @internal */ readonly template: VaultTemplate,\n    /** @internal — lazy migrate-on-open (#271). */ readonly migrateOnOpen: boolean = false,\n  ) {\n    if (name.includes(SHARD_SEPARATOR)) {\n      throw new ValidationError(\n        `VaultGroup name \"${name}\" must not contain \"--\" (reserved shard vault-id separator).`,\n      )\n    }\n  }\n\n  /** @internal — set when the group is managed (no explicit registry). */\n  private stateVault: StateManagementVault | undefined\n\n  /** @internal */\n  _attachStateVault(sv: StateManagementVault): void {\n    this.stateVault = sv\n  }\n\n  /** Deterministic vault name for a partition key, namespaced by the group. */\n  shardVaultId(partitionKey: string): string {\n    assertSafePartitionKey(partitionKey)\n    return `${this.name}${SHARD_SEPARATOR}${partitionKey}`\n  }\n\n  /**\n   * @internal — group-qualified registry record key (avoids cross-group key\n   * collisions). Identical to the shard vault id by design — the registry row\n   * for a shard is keyed by that shard's vault id — so it delegates to\n   * `shardVaultId`, reusing its partition-key validation.\n   */\n  registryId(partitionKey: string): string {\n    return this.shardVaultId(partitionKey)\n  }\n\n  /**\n   * Registry rows for THIS group (hydrates the registry collection first).\n   * The registry may be shared across groups (the auto-wired StateManagement\n   * vault holds one `vaultRegistry` for the whole instance), so rows are\n   * filtered by `group` — without this, a group's fan-out reads would leak\n   * across into other groups' shards. Mirrors the `${group}--` scoping that\n   * `liveBinding().isRelevant` already applies to the reactive path.\n   */\n  async allRows(): Promise<VaultRegistryRow[]> {\n    await this.registry.list()\n    const rows = this.registry.query().toArray() // toArray() is synchronous\n    return rows.filter((r) => r.group === this.name)\n  }\n\n  /**\n   * Open an existing shard and apply the template. When `migrateOnOpen` is set\n   * (#271) and the shard's registry version is behind the template, its cutover\n   * runs inline first — so a behind shard never surfaces a stale handle.\n   */\n  async openShard(partitionKey: string): Promise<Vault> {\n    if (this.migrateOnOpen) {\n      const row = await this.registry.get(this.registryId(partitionKey))\n      if (row && row.schemaVersion < this.template.version) {\n        await this.migrateShard(partitionKey)\n      }\n    }\n    return this._openShardRaw(partitionKey)\n  }\n\n  /** @internal — open + configure with no migrate-on-open hook (used by the migration path itself to avoid recursion). */\n  private async _openShardRaw(partitionKey: string): Promise<Vault> {\n    const vault = await this.db.openVault(this.shardVaultId(partitionKey), { create: false })\n    this.template.configure(vault)\n    return vault\n  }\n\n  /**\n   * Idempotently provision a shard for `partitionKey`. Returns the\n   * configured vault handle.\n   *\n   * - row + vault present → no-op, return handle\n   * - row present, vault gone → ShardProvisioningError\n   * - row absent (vault present or not) → open-or-create, configure, write row\n   */\n  async createShard(partitionKey: string): Promise<Vault> {\n    const vaultId = this.shardVaultId(partitionKey)\n    const row = await this.registry.get(this.registryId(partitionKey))\n    const provisioned = await this.db._shardVaultProvisioned(vaultId)\n\n    if (row && !provisioned) throw new ShardProvisioningError(vaultId, partitionKey)\n    if (row && provisioned) return this.openShard(partitionKey)\n\n    // Row absent → create (or reconcile a provisioned-but-unregistered vault).\n    const vault = await this.db.openVault(vaultId)\n    this.template.configure(vault)\n    await this.registry.put(this.registryId(partitionKey), {\n      vaultId,\n      partitionKey,\n      templateName: this.sharding.vaultTemplate,\n      schemaVersion: this.template.version,\n      createdAt: Date.now(),\n      group: this.name,\n    })\n    if (this.stateVault) {\n      try {\n        await this.stateVault.appendEvent({\n          type: 'shard-created',\n          group: this.name,\n          vaultId,\n          templateName: this.sharding.vaultTemplate,\n          version: this.template.version,\n        })\n      } catch {\n        /* best-effort: event logging never fails the shard write */\n      }\n    }\n    return vault\n  }\n\n  /**\n   * Drill down to a single shard's full Collection API. Throws if the shard is unknown.\n   * Also throws ShardProvisioningError if the registry row exists but the vault has been deleted\n   * (registry/store divergence).\n   */\n  async shard(partitionKey: string): Promise<Vault> {\n    const vaultId = this.shardVaultId(partitionKey)\n    const row = await this.registry.get(this.registryId(partitionKey))\n    if (!row) throw new UnknownShardError(partitionKey, this.name)\n    const provisioned = await this.db._shardVaultProvisioned(vaultId)\n    if (!provisioned) throw new ShardProvisioningError(vaultId, partitionKey)\n    return this.openShard(partitionKey)\n  }\n\n  /** A sharded view over one logical collection across all shards. */\n  collection<R = T>(collectionName: string): ShardedCollection<T, R> {\n    return new ShardedCollection<T, R>(this, collectionName)\n  }\n\n  /** @internal — eligible (openable-candidate) rows + drift/divergence skips. */\n  async resolveEligible(options: { minVersion?: number } = {}): Promise<{\n    eligible: VaultRegistryRow[]\n    skipped: SkippedVault[]\n  }> {\n    const rows = await this.allRows()\n    const skipped: SkippedVault[] = []\n    const versionOk: VaultRegistryRow[] = []\n    for (const row of rows) {\n      if (options.minVersion !== undefined && row.schemaVersion < options.minVersion) {\n        skipped.push({ vaultId: row.vaultId, reason: 'schema-drift' })\n      } else versionOk.push(row)\n    }\n    const provisioned = await Promise.all(versionOk.map((r) => this.db._shardVaultProvisioned(r.vaultId)))\n    const eligible: VaultRegistryRow[] = []\n    versionOk.forEach((row, i) => {\n      if (provisioned[i]) eligible.push(row)\n      else skipped.push({ vaultId: row.vaultId, reason: 'error', error: new ShardProvisioningError(row.vaultId, row.partitionKey) })\n    })\n    return { eligible, skipped }\n  }\n\n  /** @internal — registered push-model cross-vault derivations (#271 Insight Vault). */\n  private readonly crossVaultDerivations: CrossVaultDerivationSpec[] = []\n\n  /**\n   * Register a push-model cross-vault derivation — the Insight Vault pattern\n   * (#271, Layer 4). Drive it with {@link refreshInsights}.\n   *\n   * For each shard, `derive(records, ctx)` runs on that shard's `source`\n   * records and its return value is written into the analytics\n   * (`target.vault` / `target.collection`) vault, keyed by partition key —\n   * one summary row per shard. The derivation runs in-process under THIS\n   * group's `Noydb` (which already holds both the shard and Insight Vault\n   * keyrings); the shard's decrypted records are reduced to a summary that is\n   * re-encrypted under the Insight Vault's own DEK, so no shard ciphertext\n   * crosses a DEK boundary.\n   *\n   * **Zero-knowledge note:** the Insight Vault backend sees aggregated\n   * structure (totals, counts, timestamps) drawn from many shards — a weaker\n   * ZK profile than the per-shard vaults. Opt-in; keep summaries to aggregate\n   * scalars (no embeddings / no raw records).\n   *\n   * v1 is explicit-refresh (no write-path push); call `refreshInsights()`\n   * after a batch of writes, or on a schedule.\n   */\n  withCrossVaultDerivation<R = Record<string, unknown>, S = Record<string, unknown>>(\n    spec: CrossVaultDerivationSpec<R, S>,\n  ): void {\n    this.crossVaultDerivations.push(spec as unknown as CrossVaultDerivationSpec)\n  }\n\n  /**\n   * Run every registered {@link withCrossVaultDerivation}: read each eligible\n   * shard's source records, derive a per-shard summary, and write it into the\n   * Insight Vault keyed by partition key. Shards behind `minVersion`,\n   * unprovisioned, or whose read errors are reported in `skippedVaults` and\n   * are not written (a stale summary is never left behind for a failed shard).\n   */\n  async refreshInsights(options: { minVersion?: number; concurrency?: number } = {}): Promise<RefreshInsightsResult> {\n    if (this.crossVaultDerivations.length === 0) return { written: 0, skippedVaults: [] }\n    const { eligible, skipped } = await this.resolveEligible(\n      options.minVersion !== undefined ? { minVersion: options.minVersion } : {},\n    )\n    let written = 0\n    for (const spec of this.crossVaultDerivations) {\n      const results = await this.db.queryAcross<Record<string, unknown>[]>(\n        eligible.map((r) => r.vaultId),\n        async (vault) => {\n          this.template.configure(vault)\n          return vault.collection<Record<string, unknown>>(spec.source).list()\n        },\n        { create: false, ...(options.concurrency !== undefined ? { concurrency: options.concurrency } : {}) },\n      )\n      const insight = await this.db.openVault(spec.target.vault)\n      const out = insight.collection<Record<string, unknown>>(spec.target.collection)\n      for (let i = 0; i < eligible.length; i++) {\n        const row = eligible[i]!\n        const res = results[i]\n        if (!res || res.result === undefined) {\n          skipped.push({ vaultId: row.vaultId, reason: 'error', ...(res?.error ? { error: res.error } : {}) })\n          continue\n        }\n        const ctx: CrossVaultDerivationContext = {\n          vaultId: row.vaultId,\n          partitionKey: row.partitionKey,\n          schemaVersion: row.schemaVersion,\n        }\n        const summary = spec.derive(res.result, ctx)\n        await out.put(row.partitionKey, summary)\n        written++\n      }\n    }\n    return { written, skippedVaults: skipped }\n  }\n\n  /** @internal — the control-plane vault for migration status; lazily opened. */\n  private async ensureStateVault(): Promise<StateManagementVault> {\n    if (!this.stateVault) this.stateVault = await StateManagementVault.open(this.db)\n    return this.stateVault\n  }\n\n  /**\n   * Migrate ONE shard to the template's current version (#271 fleet runner,\n   * per-shard step). Opens the shard (applying the template, which arms the\n   * M12 cutover), drains schema-write detection, runs `vault.runSchemaCutover()`\n   * (the per-vault drain-barrier-transform protocol), then advances the\n   * registry row's `schemaVersion` and records `migration-status`. A shard\n   * already at the template version is a no-op (`status: 'done'`, migrated 0).\n   * Never throws on a cutover failure — it records `status: 'failed'` and\n   * returns the row, so a fleet run continues past a bad shard.\n   */\n  async migrateShard(partitionKey: string): Promise<MigrationStatusRow> {\n    const vaultId = this.shardVaultId(partitionKey)\n    const row = await this.registry.get(this.registryId(partitionKey))\n    if (!row) throw new UnknownShardError(partitionKey, this.name)\n    const target = this.template.version\n    const sv = await this.ensureStateVault()\n    const base = { vaultId, group: this.name, currentVersion: row.schemaVersion, targetVersion: target }\n\n    if (row.schemaVersion >= target) {\n      const done: MigrationStatusRow = { ...base, status: 'done', migrated: 0, finishedAt: Date.now() }\n      await sv.upsertMigrationStatus(done)\n      return done\n    }\n\n    await sv.upsertMigrationStatus({ ...base, status: 'running', startedAt: Date.now() })\n    try { await sv.appendEvent({ type: 'migration-started', group: this.name, vaultId, version: target }) } catch { /* best-effort */ }\n\n    try {\n      const vault = await this._openShardRaw(partitionKey)\n      await vault._drainPendingSchemaWrites()\n      const { migrated } = await vault.runSchemaCutover()\n      // Advance the authoritative registry version (no built-in update path).\n      await this.registry.put(this.registryId(partitionKey), { ...row, schemaVersion: target })\n      const done: MigrationStatusRow = { ...base, currentVersion: target, status: 'done', migrated, finishedAt: Date.now() }\n      await sv.upsertMigrationStatus(done)\n      try { await sv.appendEvent({ type: 'migration-completed', group: this.name, vaultId, version: target }) } catch { /* best-effort */ }\n      return done\n    } catch (err) {\n      const error = err instanceof Error ? err.message : String(err)\n      const failed: MigrationStatusRow = { ...base, status: 'failed', error, finishedAt: Date.now() }\n      await sv.upsertMigrationStatus(failed)\n      try { await sv.appendEvent({ type: 'migration-failed', group: this.name, vaultId, version: target, detail: error }) } catch { /* best-effort */ }\n      return failed\n    }\n  }\n\n  /**\n   * Active batch runner (#271): migrate every shard behind the template version\n   * to it, in controlled batches. **Resumable + crash-safe** — shards already at\n   * the target are skipped (the registry version is the source of truth), so a\n   * re-run after a crash only picks up the unfinished + previously-failed shards.\n   *\n   * - `cohort` — restrict to these partition keys (the staged / canary rollout:\n   *   migrate a small cohort, verify the Insight Vault, then run the rest).\n   * - `batchSize` — max shards migrated concurrently per batch (back-pressure).\n   *   Default 4. Batches run sequentially; shards within a batch run in parallel.\n   */\n  async migrateFleet(options: { cohort?: readonly string[]; batchSize?: number } = {}): Promise<FleetMigrationResult> {\n    const target = this.template.version\n    const rows = await this.allRows()\n    const cohort = options.cohort\n    const todo = rows.filter(\n      (r) => r.schemaVersion < target && (cohort === undefined || cohort.includes(r.partitionKey)),\n    )\n    const batchSize = Math.max(1, options.batchSize ?? 4)\n    const migrated: string[] = []\n    const failed: { vaultId: string; error: string }[] = []\n    for (let i = 0; i < todo.length; i += batchSize) {\n      const batch = todo.slice(i, i + batchSize)\n      const settled = await Promise.all(batch.map((r) => this.migrateShard(r.partitionKey)))\n      for (const res of settled) {\n        if (res.status === 'done') migrated.push(res.vaultId)\n        else failed.push({ vaultId: res.vaultId, error: res.error ?? 'unknown' })\n      }\n    }\n    return { target, migrated, failed }\n  }\n}\n\nexport class ShardedCollection<T, R = T> {\n  constructor(\n    private readonly group: VaultGroup<T>,\n    private readonly collectionName: string,\n  ) {}\n\n  /** Route a write to the shard owning `keyOf(record)`. */\n  async put(id: string, record: T): Promise<void> {\n    const key = this.group.sharding.keyOf(record)\n    const row = await this.group.registry.get(this.group.registryId(key))\n    let vault: Vault\n    if (!row) {\n      if (this.group.sharding.autoCreate === false) {\n        throw new UnknownShardError(key, this.group.name)\n      }\n      vault = await this.group.createShard(key)\n    } else {\n      vault = await this.group.openShard(key)\n    }\n    await vault.collection<T>(this.collectionName).put(id, record)\n  }\n\n  /** Begin a cross-shard fan-out query. */\n  query(): ShardedQuery<T, R> {\n    return new ShardedQuery<T, R>(this.group, this.collectionName, [])\n  }\n}\n\nexport class ShardedQuery<T, R = T> {\n  constructor(\n    private readonly group: VaultGroup<T>,\n    private readonly collectionName: string,\n    private readonly clauses: readonly WhereClause[],\n    private readonly coPartitionedLegs: readonly CoPartitionedLeg[] = [],\n    private readonly broadcastLegs: readonly BroadcastLeg[] = [],\n  ) {}\n\n  where(field: string, op: WhereClause['op'], value: unknown): ShardedQuery<T, R> {\n    return new ShardedQuery<T, R>(\n      this.group,\n      this.collectionName,\n      [...this.clauses, { field, op, value }],\n      this.coPartitionedLegs,\n      this.broadcastLegs,\n    )\n  }\n\n  /** Co-partitioned join: each shard joins its own same-vault right collection (resolved via ref()), then union. */\n  crossShardJoin(field: string, opts: CrossShardJoinOptions): ShardedQuery<T, R> {\n    const leg: CoPartitionedLeg = { field, as: opts.as, maxRows: opts.maxRows, strategy: opts.strategy }\n    return new ShardedQuery<T, R>(\n      this.group,\n      this.collectionName,\n      this.clauses,\n      [...this.coPartitionedLegs, leg],\n      this.broadcastLegs,\n    )\n  }\n\n  /** Broadcast dimension join: enrich every merged row from a single shared collection. */\n  broadcastJoin(field: string, opts: BroadcastJoinOptions): ShardedQuery<T, R> {\n    const leg: BroadcastLeg = {\n      field,\n      as: opts.as,\n      from: opts.from,\n      on: opts.on ?? 'id',\n      mode: opts.mode ?? 'warn',\n    }\n    return new ShardedQuery<T, R>(\n      this.group,\n      this.collectionName,\n      this.clauses,\n      this.coPartitionedLegs,\n      [...this.broadcastLegs, leg],\n    )\n  }\n\n  /** @internal — fan out the where-filtered records across eligible shards. */\n  async fanoutRecords(options: FanoutQueryOptions = {}): Promise<{ records: R[]; skippedVaults: SkippedVault[] }> {\n    const { eligible, skipped } = await this.group.resolveEligible(options)\n    // Deterministic pre-check: an undeclared co-partitioned join ref fails\n    // identically on every shard, so surface it as ONE CrossShardJoinError\n    // rather than N identical skips. Probe the first eligible shard.\n    const probeRow = eligible[0]\n    if (this.coPartitionedLegs.length > 0 && probeRow) {\n      const probe = await this.group.openShard(probeRow.partitionKey)\n      this.group.template.configure(probe)\n      for (const leg of this.coPartitionedLegs) {\n        if (!probe.resolveRef(this.collectionName, leg.field)) {\n          throw new CrossShardJoinError(\n            `crossShardJoin(\"${leg.field}\"): no ref() declared for \"${leg.field}\" on ` +\n              `collection \"${this.collectionName}\" in template \"${this.group.sharding.vaultTemplate}\". ` +\n              `Add refs: { ${leg.field}: ref('<target>') } to the template's collection options.`,\n          )\n        }\n      }\n    }\n    const across = await this.group.db.queryAcross<R[]>(\n      eligible.map((r) => r.vaultId),\n      async (vault) => {\n        this.group.template.configure(vault)\n        const coll = vault.collection<R>(this.collectionName)\n        await coll.list() // hydrate the in-memory cache before the sync query\n        // Hydrate each co-partitioned join target — resolveSource reads the\n        // in-memory cache, so an unopened right collection would join to an\n        // empty snapshot (every row → null).\n        for (const leg of this.coPartitionedLegs) {\n          const desc = vault.resolveRef(this.collectionName, leg.field)\n          if (desc) await vault.collection(desc.target).list()\n        }\n        let q = coll.query()\n        for (const c of this.clauses) q = q.where(c.field, c.op, c.value)\n        for (const leg of this.coPartitionedLegs) {\n          q = q.join(leg.field, {\n            as: leg.as,\n            ...(leg.maxRows !== undefined ? { maxRows: leg.maxRows } : {}),\n            ...(leg.strategy ? { strategy: leg.strategy } : {}),\n          })\n        }\n        return q.toArray()\n      },\n      { concurrency: options.concurrency ?? 1, create: false },\n    )\n    const results: R[] = []\n    for (const r of across) {\n      if (r.error) skipped.push({ vaultId: r.vault, reason: classifyShardSkip(r.error), error: r.error })\n      else for (const item of r.result) results.push(item)\n    }\n    return { records: results, skippedVaults: skipped }\n  }\n\n  /** Fan out across eligible shards, merge, then apply any broadcast dimension legs. */\n  async toArray(options: FanoutQueryOptions = {}): Promise<FanoutResult<R>> {\n    const { records, skippedVaults } = await this.fanoutRecords(options)\n    const results = (await applyBroadcastLegs(records, this.broadcastLegs)) as R[]\n    return { results, skippedVaults }\n  }\n\n  /** @internal — build the change-subscription + relevance binding for this query's group+collection. */\n  liveBinding(): LiveBinding {\n    const group = this.group\n    const collectionName = this.collectionName\n    return {\n      subscribeToChanges: (h) => { group.db.on('change', h); return () => group.db.off('change', h) },\n      isRelevant: (e) => e.collection === collectionName && e.vault.startsWith(`${group.name}--`),\n    }\n  }\n\n  /** @internal — joined queries don't support reactive/aggregate surfaces in v1. */\n  private assertNoJoinLegs(surface: string): void {\n    if (this.coPartitionedLegs.length || this.broadcastLegs.length) {\n      throw new CrossShardJoinError(\n        `${surface}() is not supported on a ShardedQuery with crossShardJoin/broadcastJoin ` +\n          `legs in v1. Use toArray() for joined cross-shard queries.`,\n      )\n    }\n  }\n\n  /** Returns a reactive cross-shard live query — a facade over CrossVaultLive. */\n  live(options: LiveQueryOptions = {}): CrossVaultLiveQuery<R> {\n    this.assertNoJoinLegs('live')\n    const bind = this.liveBinding()\n    const core = new CrossVaultLive<{ records: R[]; skipped: SkippedVault[] }>({\n      ...bind,\n      compute: async () => {\n        const { records, skippedVaults } = await this.fanoutRecords(options)\n        return { records, skipped: skippedVaults }\n      },\n      initialSnapshot: { records: [], skipped: [] },\n      ...(options.debounceMs !== undefined ? { debounceMs: options.debounceMs } : {}),\n    })\n    return {\n      get value() { return core.snapshot.records as readonly R[] },\n      get skippedVaults() { return core.snapshot.skipped as readonly SkippedVault[] },\n      get error() { return core.error },\n      ready: core.ready,\n      subscribe: (cb) => core.subscribe(cb),\n      stop: () => core.stop(),\n    }\n  }\n\n  /** One-shot distributed aggregate — central reduce over all shard records. */\n  aggregate<Spec extends AggregateSpec>(spec: Spec): CrossVaultAggregation<R, Spec> {\n    this.assertNoJoinLegs('aggregate')\n    return new CrossVaultAggregation<R, Spec>(this, spec, this.liveBinding())\n  }\n\n  /** Begin a grouped cross-shard aggregate. */\n  groupBy<F extends string>(field: F): ShardedGroupedQuery<T, R, F> {\n    this.assertNoJoinLegs('groupBy')\n    return new ShardedGroupedQuery<T, R, F>(this, field)\n  }\n}\n\n/** Grouped cross-shard query — intermediate after `.groupBy(field)`, terminates with `.aggregate(spec)`. */\nexport class ShardedGroupedQuery<T, R, F extends string> {\n  constructor(\n    private readonly query: ShardedQuery<T, R>,\n    private readonly field: F,\n  ) {}\n\n  aggregate<Spec extends AggregateSpec>(spec: Spec): CrossVaultGroupedAggregation<R, F, Spec> {\n    return new CrossVaultGroupedAggregation<R, F, Spec>(\n      { fanoutRecords: (o) => this.query.fanoutRecords(o) } satisfies FanoutRecordSource<R>,\n      this.field,\n      spec,\n      this.query.liveBinding(),\n    )\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/{with-materialized-view--4PsvMDu.d.cts → with-materialized-view-BdH_A_r6.d.cts}

@@ -1,4 +1,4 @@
-import { aP as MaterializedViewStrategy, aQ as MaterializedViewStrategyHandle } from './types-Bze6vkwm.cjs';
+import { aS as MaterializedViewStrategy, aT as MaterializedViewStrategyHandle } from './types-BpLPqyaO.cjs';
 
 /**
  * Register a materialized view: a declared query whose result is

package/dist/{with-materialized-view-QT1Tp7NO.d.ts → with-materialized-view-CzAgp_HJ.d.ts}

@@ -1,4 +1,4 @@
-import { aP as MaterializedViewStrategy, aQ as MaterializedViewStrategyHandle } from './types-DrmBTscX.js';
+import { aS as MaterializedViewStrategy, aT as MaterializedViewStrategyHandle } from './types-Diqc2caK.js';
 
 /**
  * Register a materialized view: a declared query whose result is

package/dist/{with-overlayed-view-BEXfpzSb.d.ts → with-overlayed-view-BJbqQnsR.d.ts}

@@ -1,4 +1,4 @@
-import { aR as OverlayedViewStrategy, aW as OverlayedViewStrategyHandle } from './types-DrmBTscX.js';
+import { aU as OverlayedViewStrategy, aZ as OverlayedViewStrategyHandle } from './types-Diqc2caK.js';
 
 /**
  * Register a read-shadow overlay: bind an MV-owned base collection to

package/dist/{with-overlayed-view-DlH5qmeB.d.cts → with-overlayed-view-C40rDPlu.d.cts}

@@ -1,4 +1,4 @@
-import { aR as OverlayedViewStrategy, aW as OverlayedViewStrategyHandle } from './types-Bze6vkwm.cjs';
+import { aU as OverlayedViewStrategy, aZ as OverlayedViewStrategyHandle } from './types-BpLPqyaO.cjs';
 
 /**
  * Register a read-shadow overlay: bind an MV-owned base collection to

package/dist/with-rollup-Bopu5UDZ.d.cts

@@ -0,0 +1,47 @@
+import { aK as DerivationStrategy, aO as DerivationStrategyHandle } from './types-BpLPqyaO.cjs';
+
+/**
+ * Register a deterministic derivation: one source collection → one or
+ * more typed outputs, computed by the user's `derive` function on
+ * plaintext after DEK unwrap. Outputs are encrypted with the same DEK
+ * as the source and written via the standard `Collection.put` path.
+ *
+ * See docs/superpowers/specs/2026-05-01-dim14-derivation-v1-design.md.
+ */
+declare function withDerivation<TSource extends Record<string, unknown>, TOutputs extends Record<string, Record<string, unknown>>>(spec: DerivationStrategy<TSource, TOutputs>): DerivationStrategyHandle;
+
+/**
+ * `withRollup` — aggregate many child records onto a single field of their
+ * parent (#376 slice 2). The reverse of a join: instead of reading children
+ * on demand, the parent carries a maintained summary.
+ *
+ * ```ts
+ * withRollup<Sale, Buyer>({
+ *   from: 'sales',          // child collection (the trigger)
+ *   key: 'buyerId',         // FK on the child → parent id
+ *   into: 'buyers',         // parent collection
+ *   field: 'revenueByYear', // field on the parent to maintain
+ *   compute: (sales) => groupSumByYear(sales, 'total'),
+ * })
+ * ```
+ *
+ * On every write OR delete of a `from` record, the parent at id `child[key]`
+ * is recomputed: `compute(allChildren where child[key] === parentId)` is
+ * patched onto `parent[field]`. A parent write also recomputes its own
+ * aggregate (so a parent created after its children still fills in). Only the
+ * `field` is touched — the rest of the parent record is never clobbered — and
+ * a value-equality guard suppresses no-op writes. The aggregate is gap-free
+ * with respect to child inserts, updates, and deletes.
+ *
+ * Desugars to a `withDerivation` strategy carrying a `rollup` marker; dispatch
+ * handles it without invoking the executor. Eager-only in this slice.
+ */
+declare function withRollup<TChild extends Record<string, unknown> = Record<string, unknown>, TParent extends Record<string, unknown> = Record<string, unknown>>(config: {
+    from: string;
+    key: keyof TChild & string;
+    into: string;
+    field: keyof TParent & string;
+    compute: (children: TChild[]) => unknown;
+}): DerivationStrategyHandle;
+
+export { withRollup as a, withDerivation as w };

package/dist/with-rollup-DrlGkxiE.d.ts

@@ -0,0 +1,47 @@
+import { aK as DerivationStrategy, aO as DerivationStrategyHandle } from './types-Diqc2caK.js';
+
+/**
+ * Register a deterministic derivation: one source collection → one or
+ * more typed outputs, computed by the user's `derive` function on
+ * plaintext after DEK unwrap. Outputs are encrypted with the same DEK
+ * as the source and written via the standard `Collection.put` path.
+ *
+ * See docs/superpowers/specs/2026-05-01-dim14-derivation-v1-design.md.
+ */
+declare function withDerivation<TSource extends Record<string, unknown>, TOutputs extends Record<string, Record<string, unknown>>>(spec: DerivationStrategy<TSource, TOutputs>): DerivationStrategyHandle;
+
+/**
+ * `withRollup` — aggregate many child records onto a single field of their
+ * parent (#376 slice 2). The reverse of a join: instead of reading children
+ * on demand, the parent carries a maintained summary.
+ *
+ * ```ts
+ * withRollup<Sale, Buyer>({
+ *   from: 'sales',          // child collection (the trigger)
+ *   key: 'buyerId',         // FK on the child → parent id
+ *   into: 'buyers',         // parent collection
+ *   field: 'revenueByYear', // field on the parent to maintain
+ *   compute: (sales) => groupSumByYear(sales, 'total'),
+ * })
+ * ```
+ *
+ * On every write OR delete of a `from` record, the parent at id `child[key]`
+ * is recomputed: `compute(allChildren where child[key] === parentId)` is
+ * patched onto `parent[field]`. A parent write also recomputes its own
+ * aggregate (so a parent created after its children still fills in). Only the
+ * `field` is touched — the rest of the parent record is never clobbered — and
+ * a value-equality guard suppresses no-op writes. The aggregate is gap-free
+ * with respect to child inserts, updates, and deletes.
+ *
+ * Desugars to a `withDerivation` strategy carrying a `rollup` marker; dispatch
+ * handles it without invoking the executor. Eager-only in this slice.
+ */
+declare function withRollup<TChild extends Record<string, unknown> = Record<string, unknown>, TParent extends Record<string, unknown> = Record<string, unknown>>(config: {
+    from: string;
+    key: keyof TChild & string;
+    into: string;
+    field: keyof TParent & string;
+    compute: (children: TChild[]) => unknown;
+}): DerivationStrategyHandle;
+
+export { withRollup as a, withDerivation as w };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noy-db/hub",
-  "version": "0.2.0-pre.16",
+  "version": "0.2.0-pre.18",
   "description": "Zero-knowledge, offline-first, encrypted document store — core library with AES-256-GCM, PBKDF2, multi-user keyring, and sync engine",
   "license": "MIT",
   "author": "vLannaAi <vicio@lanna.ai>",
@@ -76,6 +76,26 @@
         "default": "./dist/history/index.cjs"
       }
     },
+    "./forget": {
+      "import": {
+        "types": "./dist/forget/index.d.ts",
+        "default": "./dist/forget/index.js"
+      },
+      "require": {
+        "types": "./dist/forget/index.d.cts",
+        "default": "./dist/forget/index.cjs"
+      }
+    },
+    "./sealed-record": {
+      "import": {
+        "types": "./dist/sealed-record/index.d.ts",
+        "default": "./dist/sealed-record/index.js"
+      },
+      "require": {
+        "types": "./dist/sealed-record/index.d.cts",
+        "default": "./dist/sealed-record/index.cjs"
+      }
+    },
     "./query": {
       "import": {
         "types": "./dist/query/index.d.ts",
@@ -269,14 +289,14 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@noy-db/attestation": "0.2.0-pre.16"
+    "@noy-db/attestation": "0.2.0-pre.18"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "esbuild": "^0.25.0",
     "zod": "^3.23.0",
     "zod-to-json-schema": "^3.25.2",
-    "@noy-db/on-shamir": "0.2.0-pre.16"
+    "@noy-db/on-shamir": "0.2.0-pre.18"
   },
   "peerDependencies": {
     "zod-to-json-schema": "^3.25.0"

package/dist/chunk-42FEUPZQ.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/guards/with-guard.ts","../src/guards/immutable-guard.ts"],"sourcesContent":["import { ValidationError } from '../errors.js'\nimport type { GuardStrategy, GuardStrategyHandle } from './types.js'\n\n/**\n * Register a guard for a collection. Guards run on every `put()` /\n * `delete()` for the named collection (after permissions, before\n * encryption) and may:\n *\n *   - `check` — block writes by throwing (typically `RecordLockedError`)\n *   - `frozenFields` — freeze specific fields once a condition is true\n *   - `amendment` — declare an authorized-override path with invariant\n *\n * Pass the returned handle to `createNoydb({ strategies: [...] })`.\n *\n * @see docs/superpowers/specs/2026-05-18-guards-design.md\n */\nexport function withGuard<T extends Record<string, unknown>>(\n  strategy: GuardStrategy<T>,\n): GuardStrategyHandle<T> {\n  if (!strategy.collection || strategy.collection.length === 0) {\n    throw new ValidationError('withGuard: collection name is required')\n  }\n  return {\n    __noydb_strategy: 'guard',\n    spec: strategy,\n  }\n}\n","/**\n * `immutableGuard` — declarative WORM / append-only sugar over the guard\n * subsystem.\n *\n * Issued fiscal documents (invoices, DDTs) must be immutable after issue.\n * That is expressible today with a hand-rolled `withGuard` (block on\n * `check`/`onDelete`, allow an admin `amendment`), but the boilerplate is\n * repetitive and easy to get subtly wrong. `immutableGuard` generates\n * exactly that guard from a declarative config, reusing the guard\n * machinery wholesale — `check`/`onDelete` rejection, the ledgered\n * `amendment` override, and composition with `periods`/`history`.\n *\n * ```ts\n * createNoydb({ guardStrategies: [\n *   immutableGuard({\n *     collection: 'invoices',\n *     after: (r) => r.status === 'issued',   // immutable once issued\n *   }),\n * ] })\n * ```\n *\n * A record is mutable until `after(record)` holds; from then on, updates\n * and deletes throw `RecordLockedError` unless performed inside an\n * `amendment` transaction by an authorized role (the override is\n * ledgered by the guard amendment mechanism). `appendOnly: true` is\n * shorthand for `after: () => true` — immutable from creation.\n */\n\nimport { withGuard } from './with-guard.js'\nimport type { GuardStrategy, GuardStrategyHandle, GuardContext, GuardChange } from './types.js'\nimport { RecordLockedError, ValidationError } from '../errors.js'\n\nexport interface ImmutableGuardConfig<T extends Record<string, unknown>> {\n  /** The collection to make WORM. */\n  collection: string\n  /**\n   * A record becomes immutable once this predicate holds. Evaluated on\n   * the *existing* (already-persisted) record, so the write that first\n   * makes it true is still allowed; subsequent writes are blocked.\n   * Mutually exclusive with `appendOnly`.\n   */\n  after?: (record: T) => boolean\n  /** Shorthand for `after: () => true` — immutable from creation. */\n  appendOnly?: boolean\n  /** Roles permitted to override via an amendment transaction. Default `['admin', 'owner']`. */\n  amendmentRoles?: ReadonlyArray<'admin' | 'owner'>\n  /**\n   * Optional set-level invariant run over the amendment change-set after\n   * the writes execute. Signature matches `GuardStrategy.amendment.invariant`\n   * exactly: it receives every {before, after} pair touching this\n   * collection in the amendment plus the guard context; throwing reverts\n   * the whole amendment and surfaces as `InvariantError`.\n   *\n   * Use this to keep a constraint inviolable EVEN under amendment — e.g.\n   * forbid deleting an issued document by re-throwing on any\n   * `before !== null && after === null` change, or assert a cross-record\n   * sum is preserved. When omitted the amendment is unconditionally\n   * allowed (the amendment itself is the sanctioned, ledgered override) —\n   * this is the backward-compatible default.\n   */\n  amendmentInvariant?: (\n    changes: ReadonlyArray<GuardChange<T>>,\n    ctx: GuardContext<T>,\n  ) => Promise<void> | void\n}\n\nfunction recordId(record: Record<string, unknown> | null): string {\n  const id = record?.id\n  return typeof id === 'string' ? id : ''\n}\n\n/**\n * Build an immutability guard. Pass the returned handle to\n * `createNoydb({ guardStrategies: [...] })`.\n */\nexport function immutableGuard<T extends Record<string, unknown>>(\n  config: ImmutableGuardConfig<T>,\n): GuardStrategyHandle<T> {\n  const { collection, after, appendOnly, amendmentRoles, amendmentInvariant } = config\n  if (appendOnly && after !== undefined) {\n    throw new ValidationError('immutableGuard: `after` and `appendOnly` are mutually exclusive')\n  }\n  if (!appendOnly && after === undefined) {\n    throw new ValidationError('immutableGuard: provide `after` or `appendOnly: true`')\n  }\n\n  const isImmutable: (record: T) => boolean = appendOnly ? () => true : after!\n  const reason = appendOnly ? 'append-only collection' : 'record is immutable after issue'\n\n  const spec: GuardStrategy<T> = {\n    collection,\n    // Block updates to an already-immutable record. Inserts (existing\n    // null) and the transition write that first makes the record\n    // immutable are allowed — `after` reads the prior state.\n    check: (incoming: T, ctx: GuardContext<T>) => {\n      if (ctx.existing !== null && isImmutable(ctx.existing)) {\n        throw new RecordLockedError(collection, recordId(incoming as Record<string, unknown>), reason)\n      }\n    },\n    // Block deletes of an immutable record.\n    onDelete: (existing: T) => {\n      if (isImmutable(existing)) {\n        throw new RecordLockedError(collection, recordId(existing as Record<string, unknown>), reason)\n      }\n    },\n    // The authorized override: inside an amendment transaction the\n    // check/onDelete are skipped and the change is ledgered. By default\n    // there is no extra invariant — the amendment itself is the\n    // sanctioned exception. Callers may supply `amendmentInvariant` to\n    // keep a constraint inviolable even under amendment (e.g. forbid\n    // deletes, or preserve a cross-record sum); a throw reverts the\n    // amendment and surfaces as `InvariantError`.\n    amendment: {\n      roles: amendmentRoles ?? ['admin', 'owner'],\n      invariant: amendmentInvariant ?? (() => {\n        /* allow — the amendment is the override, and is ledgered */\n      }),\n    },\n  }\n\n  return withGuard<T>(spec)\n}\n"],"mappings":";;;;;;AAgBO,SAAS,UACd,UACwB;AACxB,MAAI,CAAC,SAAS,cAAc,SAAS,WAAW,WAAW,GAAG;AAC5D,UAAM,IAAI,gBAAgB,wCAAwC;AAAA,EACpE;AACA,SAAO;AAAA,IACL,kBAAkB;AAAA,IAClB,MAAM;AAAA,EACR;AACF;;;ACwCA,SAAS,SAAS,QAAgD;AAChE,QAAM,KAAK,QAAQ;AACnB,SAAO,OAAO,OAAO,WAAW,KAAK;AACvC;AAMO,SAAS,eACd,QACwB;AACxB,QAAM,EAAE,YAAY,OAAO,YAAY,gBAAgB,mBAAmB,IAAI;AAC9E,MAAI,cAAc,UAAU,QAAW;AACrC,UAAM,IAAI,gBAAgB,iEAAiE;AAAA,EAC7F;AACA,MAAI,CAAC,cAAc,UAAU,QAAW;AACtC,UAAM,IAAI,gBAAgB,uDAAuD;AAAA,EACnF;AAEA,QAAM,cAAsC,aAAa,MAAM,OAAO;AACtE,QAAM,SAAS,aAAa,2BAA2B;AAEvD,QAAM,OAAyB;AAAA,IAC7B;AAAA;AAAA;AAAA;AAAA,IAIA,OAAO,CAAC,UAAa,QAAyB;AAC5C,UAAI,IAAI,aAAa,QAAQ,YAAY,IAAI,QAAQ,GAAG;AACtD,cAAM,IAAI,kBAAkB,YAAY,SAAS,QAAmC,GAAG,MAAM;AAAA,MAC/F;AAAA,IACF;AAAA;AAAA,IAEA,UAAU,CAAC,aAAgB;AACzB,UAAI,YAAY,QAAQ,GAAG;AACzB,cAAM,IAAI,kBAAkB,YAAY,SAAS,QAAmC,GAAG,MAAM;AAAA,MAC/F;AAAA,IACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAQA,WAAW;AAAA,MACT,OAAO,kBAAkB,CAAC,SAAS,OAAO;AAAA,MAC1C,WAAW,uBAAuB,MAAM;AAAA,MAExC;AAAA,IACF;AAAA,EACF;AAEA,SAAO,UAAa,IAAI;AAC1B;","names":[]}