@klum-db/lobby 0.2.0-pre.32 → 0.3.0-pre.1

package/dist/index.cjs

@@ -129,13 +129,13 @@ async function writeMultiVaultBundle(compartments, opts = {}) {
   const inner = [];
   const entries = [];
   for (const c of compartments) {
-    const innerBytes = await (0, import_bundle.writeNoydbBundle)(c.vault, c.bundleOptions ?? {});
-    const header = (0, import_bundle.readNoydbBundleHeader)(innerBytes);
+    const innerBytes = await (0, import_pod.writePod)(c.vault, c.bundleOptions ?? {});
+    const header = (0, import_pod.readPodHeader)(innerBytes);
     const entry = {
       handle: header.handle,
       exportedAt: c.exportedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
       innerBytes: innerBytes.length,
-      innerSha256: await (0, import_kernel.sha256Hex)(innerBytes)
+      innerSha256: await (0, import_cargo.sha256Hex)(innerBytes)
     };
     if (c.roleTag !== void 0) entry.roleTag = c.roleTag;
     if (c.disclose?.name !== void 0 && c.disclose.name !== false) {
@@ -158,7 +158,7 @@ async function writeMultiVaultBundle(compartments, opts = {}) {
   }
   const manifest = {
     multiFormatVersion: NOYDB_MULTI_BUNDLE_VERSION,
-    handle: opts.handle ?? (0, import_kernel.generateULID)(),
+    handle: opts.handle ?? (0, import_cargo.generateULID)(),
     compartments: entries
   };
   return encodeMultiBundle(manifest, inner);
@@ -166,12 +166,12 @@ async function writeMultiVaultBundle(compartments, opts = {}) {
 async function readNoydbBundleManifest(bytes) {
   if (hasMultiMagic(bytes)) return [...decodeMultiBundle(bytes).manifest.compartments];
   if ((0, import_hub.hasNoydbBundleMagic)(bytes)) {
-    const header = (0, import_bundle.readNoydbBundleHeader)(bytes);
+    const header = (0, import_pod.readPodHeader)(bytes);
     const env = (0, import_hub.readNoydbBundlePublicEnvelope)(bytes);
     const entry = {
       handle: header.handle,
       innerBytes: bytes.length,
-      innerSha256: await (0, import_kernel.sha256Hex)(bytes)
+      innerSha256: await (0, import_cargo.sha256Hex)(bytes)
     };
     if (env !== void 0) entry.publicEnvelope = env;
     return [entry];
@@ -183,7 +183,7 @@ function readMultiVaultBundleCompartment(bytes, selector) {
     throw new Error(`readMultiVaultBundleCompartment: numeric selector must be an integer, got ${selector}.`);
   }
   if ((0, import_hub.hasNoydbBundleMagic)(bytes) && !hasMultiMagic(bytes)) {
-    const header = (0, import_bundle.readNoydbBundleHeader)(bytes);
+    const header = (0, import_pod.readPodHeader)(bytes);
     if (selector === 0 || selector === header.handle) return bytes;
     throw new Error(`readMultiVaultBundleCompartment: single v1 bundle has only compartment "${header.handle}".`);
   }
@@ -192,12 +192,12 @@ function readMultiVaultBundleCompartment(bytes, selector) {
   if (idx < 0 || idx >= inner.length) throw new Error(`readMultiVaultBundleCompartment: no compartment ${typeof selector === "number" ? `at index ${selector}` : `"${selector}"`}.`);
   return inner[idx];
 }
-var import_kernel, import_bundle, import_hub, NOYDB_MULTI_BUNDLE_MAGIC, NOYDB_MULTI_BUNDLE_PREFIX_BYTES, NOYDB_MULTI_BUNDLE_VERSION;
+var import_cargo, import_pod, import_hub, NOYDB_MULTI_BUNDLE_MAGIC, NOYDB_MULTI_BUNDLE_PREFIX_BYTES, NOYDB_MULTI_BUNDLE_VERSION;
 var init_multi_bundle = __esm({
   "src/bundle/multi-bundle.ts"() {
     "use strict";
-    import_kernel = require("@noy-db/hub/kernel");
-    import_bundle = require("@noy-db/hub/bundle");
+    import_cargo = require("@noy-db/hub/cargo");
+    import_pod = require("@noy-db/hub/pod");
     import_hub = require("@noy-db/hub");
     init_uint32();
     NOYDB_MULTI_BUNDLE_MAGIC = new Uint8Array([78, 68, 66, 77]);
@@ -271,7 +271,7 @@ async function walkCrossVaultClosure(openVault, opts) {
     for (const vaultName of batch) {
       const seeds = perVaultSeeds.get(vaultName);
       const v = await openVault(vaultName);
-      const { closure } = await (0, import_bundle2.walkClosure)(v, {
+      const { closure } = await (0, import_bundle.walkClosure)(v, {
         seeds,
         ...opts.maxDepth !== void 0 ? { maxDepth: opts.maxDepth } : {}
       });
@@ -323,20 +323,20 @@ async function extractCrossVaultPartition(openVault, opts) {
   const sealIds = {};
   for (const [vaultName, seeds] of plan.perVaultSeeds) {
     const v = await openVault(vaultName);
-    const { bundleBytes, transferKey, sealId } = await (0, import_bundle2.extractPartition)(v, {
+    const { bundleBytes, transferKey, sealId } = await (0, import_bundle.extractPartition)(v, {
       seeds,
       ...opts.maxDepth !== void 0 ? { maxDepth: opts.maxDepth } : {},
       carrySchemas: opts.carrySchemas ?? true,
       carryLedger: opts.carryLedger ?? false,
       ...opts.compression !== void 0 ? { compression: opts.compression } : {}
     });
-    const header = (0, import_bundle2.readNoydbBundleHeader)(bundleBytes);
+    const header = (0, import_pod2.readPodHeader)(bundleBytes);
     const meta = opts.compartmentMeta?.[vaultName];
     const entry = {
       handle: header.handle,
       exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
       innerBytes: bundleBytes.length,
-      innerSha256: await (0, import_kernel2.sha256Hex)(bundleBytes)
+      innerSha256: await (0, import_cargo2.sha256Hex)(bundleBytes)
     };
     if (meta?.roleTag !== void 0) entry.roleTag = meta.roleTag;
     if (meta?.disclose?.name !== void 0 && meta.disclose.name !== false) {
@@ -355,7 +355,7 @@ async function extractCrossVaultPartition(openVault, opts) {
   }
   const manifest = {
     multiFormatVersion: NOYDB_MULTI_BUNDLE_VERSION,
-    handle: (0, import_kernel2.generateULID)(),
+    handle: (0, import_cargo2.generateULID)(),
     compartments
   };
   return { bundle: encodeMultiBundle(manifest, inner), transferKeys, sealIds };
@@ -365,7 +365,7 @@ async function describeCrossVaultExtraction(openVault, opts) {
   const compartments = [];
   for (const [vaultName, seeds] of plan.perVaultSeeds) {
     const v = await openVault(vaultName);
-    const preview = await (0, import_bundle2.describeExtraction)(v, {
+    const preview = await (0, import_bundle.describeExtraction)(v, {
       seeds,
       ...opts.maxDepth !== void 0 ? { maxDepth: opts.maxDepth } : {}
     });
@@ -373,12 +373,13 @@ async function describeCrossVaultExtraction(openVault, opts) {
   }
   return { compartments, dangling: plan.dangling };
 }
-var import_bundle2, import_kernel2, CrossVaultDanglingRefError;
+var import_bundle, import_pod2, import_cargo2, CrossVaultDanglingRefError;
 var init_extract_cross_vault = __esm({
   "src/interchange/extract-cross-vault.ts"() {
     "use strict";
-    import_bundle2 = require("@noy-db/hub/bundle");
-    import_kernel2 = require("@noy-db/hub/kernel");
+    import_bundle = require("@noy-db/hub/bundle");
+    import_pod2 = require("@noy-db/hub/pod");
+    import_cargo2 = require("@noy-db/hub/cargo");
     init_multi_bundle();
     CrossVaultDanglingRefError = class extends Error {
       constructor(dangling) {
@@ -464,7 +465,7 @@ async function mergeDecryptedRecords(receiver, decrypted, opts) {
     incomingSource.set(coll, srcMap);
     incomingSourceTs.set(coll, stsMap);
   }
-  const diff = await (0, import_hub2.diffVault)(receiver, candidate);
+  const diff = await (0, import_cargo3.diffVault)(receiver, candidate);
   const byCollection = {};
   const conflicts = [];
   const writes = [];
@@ -580,15 +581,15 @@ async function mergeDecryptedRecords(receiver, decrypted, opts) {
   };
 }
 async function mergeCompartment(receiver, compartmentBytes, opts) {
-  const incoming = await (0, import_bundle3.decryptExtractedPartition)(compartmentBytes, opts.transferKey);
+  const incoming = await (0, import_bundle2.decryptExtractedPartition)(compartmentBytes, opts.transferKey);
   return mergeDecryptedRecords(receiver, incoming, opts);
 }
-var import_hub2, import_bundle3, FieldLevelDeferredError;
+var import_cargo3, import_bundle2, FieldLevelDeferredError;
 var init_merge_compartment = __esm({
   "src/interchange/merge-compartment.ts"() {
     "use strict";
-    import_hub2 = require("@noy-db/hub");
-    import_bundle3 = require("@noy-db/hub/bundle");
+    import_cargo3 = require("@noy-db/hub/cargo");
+    import_bundle2 = require("@noy-db/hub/bundle");
     init_field_authority();
     FieldLevelDeferredError = class extends Error {
       constructor(collection) {
@@ -684,7 +685,7 @@ async function graduate(noydb, docked, opts) {
   await mergeDecryptedRecords(vault, staged, { strategy: "take-incoming", reason: "dock:graduate" });
   let deedSealed = false;
   if (opts.deed) {
-    await (0, import_hub3.createDeedOwner)(noydb._store, opts.vaultName, opts.deed.ownerId, opts.deed.sealingProvider);
+    await (0, import_cargo4.createDeedOwner)(noydb._store, opts.vaultName, opts.deed.ownerId, opts.deed.sealingProvider);
     deedSealed = true;
   }
   if (opts.stateVault) {
@@ -704,11 +705,11 @@ async function graduate(noydb, docked, opts) {
     event: { type: "unit-graduated", unitId: docked.unitId, vault: opts.vaultName }
   };
 }
-var import_hub3, UnitGraduationError, ISO_EPOCH;
+var import_cargo4, UnitGraduationError, ISO_EPOCH;
 var init_graduate = __esm({
   "src/dock/graduate.ts"() {
     "use strict";
-    import_hub3 = require("@noy-db/hub");
+    import_cargo4 = require("@noy-db/hub/cargo");
     init_merge_compartment();
     init_stage_records();
     UnitGraduationError = class extends Error {
@@ -738,7 +739,7 @@ __export(surface_exports, {
 async function proposeSurface(smv, def, proposedBy, now) {
   const row = {
     ...def,
-    id: def.id ?? (0, import_kernel3.generateULID)(),
+    id: def.id ?? (0, import_cargo5.generateULID)(),
     status: "proposed",
     proposedBy,
     createdAt: now
@@ -759,7 +760,7 @@ async function exportSurface(source, surface) {
     throw new SurfaceStateError(surface.id, surface.status, "agreed");
   }
   const seeds = Object.fromEntries(surface.collections.map((c) => [c, () => true]));
-  const { bundleBytes, transferKey } = await (0, import_bundle5.extractPartition)(source, {
+  const { bundleBytes, transferKey } = await (0, import_bundle4.extractPartition)(source, {
     seeds,
     maxDepth: 0,
     ...surface.fields ? { fieldProjection: surface.fields } : {},
@@ -797,12 +798,12 @@ async function markSynced(smv, id, now) {
     nextSyncDueAt: now + cadenceMs
   });
 }
-var import_kernel3, import_bundle5, SurfaceNotFoundError, SurfaceStateError, SurfaceCadenceScheduler;
+var import_cargo5, import_bundle4, SurfaceNotFoundError, SurfaceStateError, SurfaceCadenceScheduler;
 var init_surface = __esm({
   "src/interchange/surface.ts"() {
     "use strict";
-    import_kernel3 = require("@noy-db/hub/kernel");
-    import_bundle5 = require("@noy-db/hub/bundle");
+    import_cargo5 = require("@noy-db/hub/cargo");
+    import_bundle4 = require("@noy-db/hub/bundle");
     init_merge_compartment();
     SurfaceNotFoundError = class extends Error {
       name = "SurfaceNotFoundError";
@@ -907,38 +908,38 @@ function canonical(value) {
   return `{${keys.map((k) => `${JSON.stringify(k)}:${canonical(obj[k])}`).join(",")}}`;
 }
 async function fingerprintBlueprint(bp) {
-  return (0, import_kernel4.sha256Hex)(new TextEncoder().encode(canonical(bp)));
+  return (0, import_cargo6.sha256Hex)(new TextEncoder().encode(canonical(bp)));
 }
-var import_kernel4;
+var import_cargo6;
 var init_schema_manifest = __esm({
   "src/federation/schema-manifest.ts"() {
     "use strict";
-    import_kernel4 = require("@noy-db/hub/kernel");
+    import_cargo6 = require("@noy-db/hub/cargo");
   }
 });
 
 // src/federation/constants.ts
-var import_hub4;
+var import_cargo7;
 var init_constants = __esm({
   "src/federation/constants.ts"() {
     "use strict";
-    import_hub4 = require("@noy-db/hub");
+    import_cargo7 = require("@noy-db/hub/cargo");
   }
 });
 
 // src/federation/state-vault.ts
 var state_vault_exports = {};
 __export(state_vault_exports, {
-  STATE_VAULT_NAME: () => import_hub4.STATE_VAULT_NAME,
+  STATE_VAULT_NAME: () => import_cargo7.STATE_VAULT_NAME,
   StateManagementVault: () => StateManagementVault
 });
-var import_kernel5, REGISTRY, MANIFEST, EVENTS, MIGRATION_STATUS, SURFACES, StateManagementVault;
+var import_cargo8, REGISTRY, MANIFEST, EVENTS, MIGRATION_STATUS, SURFACES, StateManagementVault;
 var init_state_vault = __esm({
   "src/federation/state-vault.ts"() {
     "use strict";
     init_schema_manifest();
     init_constants();
-    import_kernel5 = require("@noy-db/hub/kernel");
+    import_cargo8 = require("@noy-db/hub/cargo");
     init_constants();
     REGISTRY = "vaultRegistry";
     MANIFEST = "schemaManifest";
@@ -968,7 +969,7 @@ var init_state_vault = __esm({
       #surfaces;
       /** Idempotently open the reserved state vault and bind the control-plane collections. */
       static async open(db) {
-        const vault = await db.openVault(import_hub4.STATE_VAULT_NAME);
+        const vault = await db.openVault(import_cargo7.STATE_VAULT_NAME);
         return new _StateManagementVault(
           vault.collection(REGISTRY),
           vault.collection(MANIFEST),
@@ -1028,7 +1029,7 @@ var init_state_vault = __esm({
        */
       async appendEvent(event) {
         const ts = event.ts ?? Date.now();
-        const id = (0, import_kernel5.generateULID)();
+        const id = (0, import_cargo8.generateULID)();
         await this.#events.put(id, { ...event, id, ts });
       }
       /**
@@ -1070,13 +1071,13 @@ var init_state_vault = __esm({
 
 // src/federation/classify-skip.ts
 function classifyShardSkip(err) {
-  return err instanceof import_kernel6.NoAccessError ? "no-grant" : "error";
+  return err instanceof import_cargo9.NoAccessError ? "no-grant" : "error";
 }
-var import_kernel6;
+var import_cargo9;
 var init_classify_skip = __esm({
   "src/federation/classify-skip.ts"() {
     "use strict";
-    import_kernel6 = require("@noy-db/hub/kernel");
+    import_cargo9 = require("@noy-db/hub/cargo");
   }
 });
 
@@ -1101,7 +1102,7 @@ async function applyBroadcastLegs(rows, legs) {
   for (const leg of legs) {
     const map = /* @__PURE__ */ new Map();
     for (const rec of await leg.from.list()) {
-      const k = coerceKey((0, import_kernel7.readPath)(rec, leg.on));
+      const k = coerceKey((0, import_cargo10.readPath)(rec, leg.on));
       if (k !== null && !map.has(k)) map.set(k, rec);
     }
     indexes.push({ leg, map });
@@ -1109,7 +1110,7 @@ async function applyBroadcastLegs(rows, legs) {
   return rows.map((row) => {
     const out = { ...row };
     for (const { leg, map } of indexes) {
-      const key = coerceKey((0, import_kernel7.readPath)(row, leg.field));
+      const key = coerceKey((0, import_cargo10.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>");
@@ -1119,11 +1120,11 @@ async function applyBroadcastLegs(rows, legs) {
     return out;
   });
 }
-var import_kernel7, warnedBroadcastKeys;
+var import_cargo10, warnedBroadcastKeys;
 var init_cross_shard_join = __esm({
   "src/federation/cross-shard-join.ts"() {
     "use strict";
-    import_kernel7 = require("@noy-db/hub/kernel");
+    import_cargo10 = require("@noy-db/hub/cargo");
     warnedBroadcastKeys = /* @__PURE__ */ new Set();
   }
 });
@@ -1223,28 +1224,33 @@ var init_insight_auto_push = __esm({
   "src/federation/insight-auto-push.ts"() {
     "use strict";
     InsightAutoPush = class {
-      constructor(recompute, isSource, onError = (err, pk) => console.warn(`[klum-db] insight auto-push failed for shard "${pk}":`, err)) {
+      constructor(recompute, isSource, onError = (err, pk) => console.warn(`[klum-db] insight auto-push failed for shard "${pk}":`, err), debounceMs) {
         this.recompute = recompute;
         this.isSource = isSource;
         this.onError = onError;
+        this.debounceMs = debounceMs;
       }
       recompute;
       isSource;
       onError;
-      /** Partition keys awaiting recompute. */
+      debounceMs;
       dirty = /* @__PURE__ */ new Set();
-      /** The in-flight flush, or null when idle. */
       pending = null;
+      timer = null;
+      resolvePending = null;
+      flushing = false;
       /** Called from a shard's onAfterWrite hook. Marks the shard dirty + schedules a flush. */
       noteWrite(partitionKey, collection) {
         if (!this.isSource(collection)) return;
         this.dirty.add(partitionKey);
-        this.schedule();
+        if (this.debounceMs !== void 0) this.scheduleDebounced();
+        else this.schedule();
       }
       /** Resolve once no flush is pending (drains rescheduled flushes too). */
       async whenSettled() {
         while (this.pending) await this.pending;
       }
+      // ── microtask path (unchanged default) ──
       schedule() {
         if (this.pending) return;
         this.pending = this.runFlush().finally(() => {
@@ -1252,6 +1258,29 @@ var init_insight_auto_push = __esm({
           if (this.dirty.size > 0) this.schedule();
         });
       }
+      // ── debounce path (#13) ──
+      scheduleDebounced() {
+        if (!this.pending) this.pending = new Promise((r) => {
+          this.resolvePending = r;
+        });
+        if (this.timer) clearTimeout(this.timer);
+        this.timer = setTimeout(() => {
+          this.timer = null;
+          if (this.flushing) return;
+          this.flushing = true;
+          void this.runFlush().finally(() => {
+            this.flushing = false;
+            if (this.dirty.size > 0) {
+              this.scheduleDebounced();
+            } else {
+              const resolve = this.resolvePending;
+              this.resolvePending = null;
+              this.pending = null;
+              resolve?.();
+            }
+          });
+        }, this.debounceMs);
+      }
       async runFlush() {
         await Promise.resolve();
         const pks = [...this.dirty];
@@ -1306,12 +1335,12 @@ var init_partial_reduce = __esm({
 });
 
 // src/federation/aggregate-across.ts
-var import_kernel8, import_kernel9, CrossVaultAggregation, CrossVaultGroupedAggregation;
+var import_cargo11, import_cargo12, CrossVaultAggregation, CrossVaultGroupedAggregation;
 var init_aggregate_across = __esm({
   "src/federation/aggregate-across.ts"() {
     "use strict";
-    import_kernel8 = require("@noy-db/hub/kernel");
-    import_kernel9 = require("@noy-db/hub/kernel");
+    import_cargo11 = require("@noy-db/hub/cargo");
+    import_cargo12 = require("@noy-db/hub/cargo");
     init_cross_vault_live();
     init_partial_reduce();
     CrossVaultAggregation = class {
@@ -1329,7 +1358,7 @@ var init_aggregate_across = __esm({
           return { result: finalizePartial(this.spec, mergePartials(this.spec, partials)), skippedVaults: skippedVaults2 };
         }
         const { records, skippedVaults } = await this.src.fanoutRecords(options);
-        return { result: (0, import_kernel8.reduceRecords)(records, this.spec), skippedVaults };
+        return { result: (0, import_cargo11.reduceRecords)(records, this.spec), skippedVaults };
       }
       live(options = {}) {
         if (!this.bind) throw new Error("CrossVaultAggregation: live() requires a LiveBinding \u2014 use ShardedQuery.aggregate()");
@@ -1340,7 +1369,7 @@ var init_aggregate_across = __esm({
           isRelevant: this.bind.isRelevant,
           compute: async () => {
             const { records, skippedVaults } = await src.fanoutRecords(options);
-            return { value: (0, import_kernel8.reduceRecords)(records, spec), skipped: skippedVaults };
+            return { value: (0, import_cargo11.reduceRecords)(records, spec), skipped: skippedVaults };
           },
           initialSnapshot: { value: void 0, skipped: [] },
           ...options.debounceMs !== void 0 ? { debounceMs: options.debounceMs } : {}
@@ -1375,7 +1404,7 @@ var init_aggregate_across = __esm({
       async run(options = {}) {
         const { records, skippedVaults } = await this.src.fanoutRecords(options);
         return {
-          results: (0, import_kernel9.groupAndReduce)(records, this.field, this.spec),
+          results: (0, import_cargo12.groupAndReduce)(records, this.field, this.spec),
           skippedVaults
         };
       }
@@ -1390,7 +1419,7 @@ var init_aggregate_across = __esm({
           compute: async () => {
             const { records, skippedVaults } = await src.fanoutRecords(options);
             return {
-              records: (0, import_kernel9.groupAndReduce)(records, field, spec),
+              records: (0, import_cargo12.groupAndReduce)(records, field, spec),
               skipped: skippedVaults
             };
           },
@@ -1463,7 +1492,7 @@ async function retrieveAcross(group, collectionName, query, opts = {}) {
     }
     return pv.hits.map((h) => ({ ...h, id: pv.vault + SEP + h.id }));
   });
-  const fused = (0, import_kernel10.fuseRetrieval)(lists, {
+  const fused = (0, import_cargo13.fuseRetrieval)(lists, {
     ...opts.limit !== void 0 ? { limit: opts.limit } : {},
     ...opts.rrfK !== void 0 ? { k: opts.rrfK } : {}
   });
@@ -1473,11 +1502,11 @@ async function retrieveAcross(group, collectionName, query, opts = {}) {
   });
   return { hits, skippedVaults };
 }
-var import_kernel10, SEP;
+var import_cargo13, SEP;
 var init_retrieve_across = __esm({
   "src/federation/retrieve-across.ts"() {
     "use strict";
-    import_kernel10 = require("@noy-db/hub/kernel");
+    import_cargo13 = require("@noy-db/hub/cargo");
     init_classify_skip();
     SEP = "\0";
   }
@@ -1491,30 +1520,34 @@ __export(vault_group_exports, {
   ShardedQuery: () => ShardedQuery,
   VaultGroup: () => VaultGroup
 });
+function autoPushConfig(spec) {
+  if (!spec.autoPush) return null;
+  return spec.autoPush === true ? {} : spec.autoPush;
+}
 function assertSafePartitionKey(partitionKey) {
   if (partitionKey.length === 0) {
-    throw new import_kernel11.ValidationError("partitionKey must be a non-empty string");
+    throw new import_cargo14.ValidationError("partitionKey must be a non-empty string");
   }
-  if (partitionKey === import_hub4.STATE_VAULT_NAME) {
-    throw new import_kernel11.ReservedVaultNameError(partitionKey);
+  if (partitionKey === import_cargo7.STATE_VAULT_NAME) {
+    throw new import_cargo14.ReservedVaultNameError(partitionKey);
   }
   if (!SAFE_PARTITION_KEY.test(partitionKey)) {
-    throw new import_kernel11.ValidationError(
+    throw new import_cargo14.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 import_kernel11.ValidationError(
+    throw new import_cargo14.ValidationError(
       `partitionKey "${partitionKey}" must not contain "--" \u2014 it is reserved as the shard vault-id separator and would risk shard-id collisions.`
     );
   }
 }
-var import_kernel11, SHARD_SEPARATOR, SAFE_PARTITION_KEY, VaultGroup, ShardedCollection, ShardedQuery, ShardedGroupedQuery;
+var import_cargo14, SHARD_SEPARATOR, SAFE_PARTITION_KEY, VaultGroup, ShardedCollection, ShardedQuery, ShardedGroupedQuery;
 var init_vault_group = __esm({
   "src/federation/vault-group.ts"() {
     "use strict";
     init_state_vault();
-    import_kernel11 = require("@noy-db/hub/kernel");
+    import_cargo14 = require("@noy-db/hub/cargo");
     init_constants();
     init_classify_skip();
     init_cross_shard_join();
@@ -1535,7 +1568,7 @@ var init_vault_group = __esm({
         this.cutoverOnOpen = cutoverOnOpen;
         this.meta = meta;
         if (name.includes(SHARD_SEPARATOR)) {
-          throw new import_kernel11.ValidationError(
+          throw new import_cargo14.ValidationError(
             `VaultGroup name "${name}" must not contain "--" (reserved shard vault-id separator).`
           );
         }
@@ -1640,11 +1673,11 @@ var init_vault_group = __esm({
         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 import_kernel11.ShardProvisioningError(vaultId, partitionKey);
+        if (row && !provisioned) throw new import_cargo14.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 import_kernel11.DataResidencyError(vaultId, region, backendRegion);
+          if (backendRegion !== region) throw new import_cargo14.DataResidencyError(vaultId, region, backendRegion);
         }
         const vault = await this.db.openVault(vaultId);
         this.template.configure(vault);
@@ -1678,9 +1711,9 @@ var init_vault_group = __esm({
       async shard(partitionKey) {
         const vaultId = this.shardVaultId(partitionKey);
         const row = await this.registry.get(this.registryId(partitionKey));
-        if (!row) throw new import_kernel11.UnknownShardError(partitionKey, this.name);
+        if (!row) throw new import_cargo14.UnknownShardError(partitionKey, this.name);
         const provisioned = await this.db._shardVaultProvisioned(vaultId);
-        if (!provisioned) throw new import_kernel11.ShardProvisioningError(vaultId, partitionKey);
+        if (!provisioned) throw new import_cargo14.ShardProvisioningError(vaultId, partitionKey);
         return this.openShard(partitionKey);
       }
       /** A sharded view over one logical collection across all shards. */
@@ -1712,7 +1745,7 @@ var init_vault_group = __esm({
         for (const p of probes) {
           if ("error" in p) skipped.push({ vaultId: p.row.vaultId, reason: "error", error: p.error });
           else if (p.provisioned) eligible.push(p.row);
-          else skipped.push({ vaultId: p.row.vaultId, reason: "error", error: new import_kernel11.ShardProvisioningError(p.row.vaultId, p.row.partitionKey) });
+          else skipped.push({ vaultId: p.row.vaultId, reason: "error", error: new import_cargo14.ShardProvisioningError(p.row.vaultId, p.row.partitionKey) });
         }
         return { eligible, skipped };
       }
@@ -1749,15 +1782,18 @@ var init_vault_group = __esm({
       withCrossVaultDerivation(spec) {
         const target = spec.target.vault;
         if (target === this.name || target.startsWith(`${this.name}${SHARD_SEPARATOR}`)) {
-          throw new import_kernel11.ValidationError(
+          throw new import_cargo14.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);
         if (spec.autoPush && !this.insightAutoPush) {
+          const cfg = autoPushConfig(spec);
           const controller = new InsightAutoPush(
             (pk) => this._recomputeShardInsights(pk),
-            (collection) => this.crossVaultDerivations.some((s) => s.autoPush && s.source === collection)
+            (collection) => this.crossVaultDerivations.some((s) => s.autoPush && s.source === collection),
+            void 0,
+            cfg?.debounceMs
           );
           this.insightAutoPush = controller;
           const prefix = `${this.name}${SHARD_SEPARATOR}`;
@@ -1838,6 +1874,8 @@ var init_vault_group = __esm({
         };
         for (const spec of this.crossVaultDerivations) {
           if (!spec.autoPush) continue;
+          const min = autoPushConfig(spec)?.minVersion;
+          if (min !== void 0 && row.schemaVersion < min) continue;
           const records = await shard.collection(spec.source).list();
           const summary = spec.derive(records, ctx);
           const insight = await this.db.openVault(spec.target.vault);
@@ -1870,7 +1908,7 @@ var init_vault_group = __esm({
       async cutoverShard(partitionKey) {
         const vaultId = this.shardVaultId(partitionKey);
         const row = await this.registry.get(this.registryId(partitionKey));
-        if (!row) throw new import_kernel11.UnknownShardError(partitionKey, this.name);
+        if (!row) throw new import_cargo14.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 };
@@ -1953,7 +1991,7 @@ var init_vault_group = __esm({
         let vault;
         if (!row) {
           if (this.group.sharding.autoCreate === false) {
-            throw new import_kernel11.UnknownShardError(key, this.group.name);
+            throw new import_cargo14.UnknownShardError(key, this.group.name);
           }
           vault = await this.group.createShard(key, this.group.sharding.regionOf?.(record));
         } else {
@@ -2036,7 +2074,7 @@ var init_vault_group = __esm({
           this.group.template.configure(probe);
           for (const leg of this.coPartitionedLegs) {
             if (!probe.resolveRef(this.collectionName, leg.field)) {
-              throw new import_kernel11.CrossShardJoinError(
+              throw new import_cargo14.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.`
               );
             }
@@ -2118,23 +2156,23 @@ var init_vault_group = __esm({
           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 import_kernel11.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. */
+      /**
+       * Returns a reactive cross-shard live query — a facade over CrossVaultLive.
+       *
+       * Joined queries (crossShardJoin / broadcastJoin) are supported (#14): the live
+       * value reflects the fully-joined rows. **v1 limitation:** recomputes only on
+       * writes to the primary (left) collection; writes to a co-partitioned right
+       * collection or a broadcast-dimension collection do NOT trigger a recompute —
+       * re-run the query to pick those up.
+       */
       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 };
+            const joined = await applyBroadcastLegs(records, this.broadcastLegs);
+            return { records: joined, skipped: skippedVaults };
           },
           initialSnapshot: { records: [], skipped: [] },
           ...options.debounceMs !== void 0 ? { debounceMs: options.debounceMs } : {}
@@ -2154,14 +2192,28 @@ var init_vault_group = __esm({
           stop: () => core.stop()
         };
       }
+      /**
+       * @internal — the FanoutRecordSource for aggregate surfaces. With no join legs,
+       * returns `this` (partial-reduce-eligible, #8). With join legs, returns a
+       * toArray-backed source (fully-joined rows) and NO fanoutReduce, forcing
+       * central-reduce over the joined rows (partial-reduce can't span the central
+       * broadcast join). Used by scalar `aggregate()` and `ShardedGroupedQuery`.
+       */
+      aggregateSource() {
+        if (!this.coPartitionedLegs.length && !this.broadcastLegs.length) return this;
+        return {
+          fanoutRecords: async (o) => {
+            const { results, skippedVaults } = await this.toArray(o);
+            return { records: results, skippedVaults };
+          }
+        };
+      }
       /** One-shot distributed aggregate — central reduce over all shard records. */
       aggregate(spec) {
-        this.assertNoJoinLegs("aggregate");
-        return new CrossVaultAggregation(this, spec, this.liveBinding());
+        return new CrossVaultAggregation(this.aggregateSource(), spec, this.liveBinding());
       }
       /** Begin a grouped cross-shard aggregate. */
       groupBy(field) {
-        this.assertNoJoinLegs("groupBy");
         return new ShardedGroupedQuery(this, field);
       }
     };
@@ -2174,7 +2226,7 @@ var init_vault_group = __esm({
       field;
       aggregate(spec) {
         return new CrossVaultGroupedAggregation(
-          { fanoutRecords: (o) => this.query.fanoutRecords(o) },
+          this.query.aggregateSource(),
           this.field,
           spec,
           this.query.liveBinding()
@@ -2187,10 +2239,10 @@ var init_vault_group = __esm({
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  CrossShardJoinError: () => import_kernel13.CrossShardJoinError,
+  CrossShardJoinError: () => import_cargo16.CrossShardJoinError,
   CrossVaultDanglingRefError: () => CrossVaultDanglingRefError,
-  CustodyApi: () => import_hub6.CustodyApi,
-  DataResidencyError: () => import_kernel13.DataResidencyError,
+  CustodyApi: () => import_cargo17.CustodyApi,
+  DataResidencyError: () => import_cargo16.DataResidencyError,
   DockedUnit: () => DockedUnit,
   FieldAuthorityPolicyMissingError: () => FieldAuthorityPolicyMissingError,
   FieldLevelDeferredError: () => FieldLevelDeferredError,
@@ -2201,17 +2253,17 @@ __export(index_exports, {
   NOYDB_MULTI_BUNDLE_MAGIC: () => NOYDB_MULTI_BUNDLE_MAGIC,
   NOYDB_MULTI_BUNDLE_PREFIX_BYTES: () => NOYDB_MULTI_BUNDLE_PREFIX_BYTES,
   NOYDB_MULTI_BUNDLE_VERSION: () => NOYDB_MULTI_BUNDLE_VERSION,
-  ReservedVaultNameError: () => import_kernel13.ReservedVaultNameError,
-  ShardProvisioningError: () => import_kernel13.ShardProvisioningError,
+  ReservedVaultNameError: () => import_cargo16.ReservedVaultNameError,
+  ShardProvisioningError: () => import_cargo16.ShardProvisioningError,
   SurfaceCadenceScheduler: () => SurfaceCadenceScheduler,
   SurfaceNotFoundError: () => SurfaceNotFoundError,
   SurfaceStateError: () => SurfaceStateError,
   UnitGraduationError: () => UnitGraduationError,
-  UnknownShardError: () => import_kernel13.UnknownShardError,
-  VaultTemplateNotFoundError: () => import_kernel13.VaultTemplateNotFoundError,
+  UnknownShardError: () => import_cargo16.UnknownShardError,
+  VaultTemplateNotFoundError: () => import_cargo16.VaultTemplateNotFoundError,
   agreeSurface: () => agreeSurface,
   applySurface: () => applySurface,
-  createDeedOwner: () => import_hub6.createDeedOwner,
+  createDeedOwner: () => import_cargo17.createDeedOwner,
   createLobby: () => createLobby,
   decodeMultiBundle: () => decodeMultiBundle,
   describeCrossVaultExtraction: () => describeCrossVaultExtraction,
@@ -2219,11 +2271,11 @@ __export(index_exports, {
   exportSurface: () => exportSurface,
   extractCrossVaultPartition: () => extractCrossVaultPartition,
   groupInspector: () => groupInspector,
-  isDeedVault: () => import_hub6.isDeedVault,
+  isDeedVault: () => import_cargo17.isDeedVault,
   isSurfaceDue: () => isSurfaceDue,
-  liberateVault: () => import_hub6.liberateVault,
+  liberateVault: () => import_cargo17.liberateVault,
   listDueSurfaces: () => listDueSurfaces,
-  loadDeedMarker: () => import_hub6.loadDeedMarker,
+  loadDeedMarker: () => import_cargo17.loadDeedMarker,
   markSynced: () => markSynced,
   mergeCompartment: () => mergeCompartment,
   mergeDecryptedRecords: () => mergeDecryptedRecords,
@@ -2238,8 +2290,7 @@ __export(index_exports, {
   writeMultiVaultBundle: () => writeMultiVaultBundle
 });
 module.exports = __toCommonJS(index_exports);
-var import_kernel12 = require("@noy-db/hub/kernel");
-var import_hub5 = require("@noy-db/hub");
+var import_cargo15 = require("@noy-db/hub/cargo");
 
 // src/dock/docked-unit.ts
 var DockedUnit = class {
@@ -2321,13 +2372,13 @@ async function meterGroup(group, opts = {}) {
 }
 
 // src/index.ts
-var import_kernel13 = require("@noy-db/hub/kernel");
+var import_cargo16 = require("@noy-db/hub/cargo");
 init_multi_bundle();
 init_extract_cross_vault();
 init_merge_compartment();
 
 // src/interchange/migrate-then-merge.ts
-var import_bundle4 = require("@noy-db/hub/bundle");
+var import_bundle3 = require("@noy-db/hub/bundle");
 init_merge_compartment();
 init_stage_records();
 init_stage_records();
@@ -2352,7 +2403,7 @@ async function migrateThenMerge(receiver, compartmentBytes, opts) {
     );
   }
   if (fromVersion > toVersion) throw new MinVersionError(fromVersion, toVersion);
-  const incoming = await (0, import_bundle4.decryptExtractedPartition)(compartmentBytes, opts.transferKey);
+  const incoming = await (0, import_bundle3.decryptExtractedPartition)(compartmentBytes, opts.transferKey);
   const transformsByCollection = {};
   const migrationByCollection = {};
   for (const [coll, recs] of Object.entries(incoming)) {
@@ -2375,7 +2426,7 @@ async function migrateThenMerge(receiver, compartmentBytes, opts) {
 
 // src/index.ts
 init_field_authority();
-var import_hub6 = require("@noy-db/hub");
+var import_cargo17 = require("@noy-db/hub/cargo");
 
 // src/dock/unit-driver.ts
 var InMemoryUnitDriver = class {
@@ -2409,10 +2460,10 @@ var Lobby = class {
   }
   async openVaultGroup(name, opts) {
     const db = this.noydb;
-    if (db.isClosed) throw new import_kernel12.ValidationError("Instance is closed");
-    if (name === import_hub5.STATE_VAULT_NAME) throw new import_kernel12.ReservedVaultNameError(name);
+    if (db.isClosed) throw new import_cargo15.ValidationError("Instance is closed");
+    if (name === import_cargo15.STATE_VAULT_NAME) throw new import_cargo15.ReservedVaultNameError(name);
     const template = this.vaultTemplates.get(opts.sharding.vaultTemplate);
-    if (!template) throw new import_kernel12.VaultTemplateNotFoundError(opts.sharding.vaultTemplate);
+    if (!template) throw new import_cargo15.VaultTemplateNotFoundError(opts.sharding.vaultTemplate);
     const { VaultGroup: VaultGroup2 } = await Promise.resolve().then(() => (init_vault_group(), vault_group_exports));
     const { StateManagementVault: StateManagementVault2 } = await Promise.resolve().then(() => (init_state_vault(), state_vault_exports));
     const stateVault = opts.registry ? void 0 : await StateManagementVault2.open(db);
@@ -2431,7 +2482,7 @@ var Lobby = class {
   }
   async openStateManagementVault() {
     const db = this.noydb;
-    if (db.isClosed) throw new import_kernel12.ValidationError("Instance is closed");
+    if (db.isClosed) throw new import_cargo15.ValidationError("Instance is closed");
     const { StateManagementVault: StateManagementVault2 } = await Promise.resolve().then(() => (init_state_vault(), state_vault_exports));
     return StateManagementVault2.open(db);
   }