@klum-db/lobby 0.2.0-pre.29 → 0.2.0-pre.31

package/dist/{vault-group-BXjO5kHB.d.cts → vault-group-DqEyXbN1.d.cts}

@@ -511,12 +511,29 @@ interface BroadcastLeg {
     readonly mode: 'warn' | 'cascade';
 }
 
+/**
+ * @category capability
+ * Distributed partial-reduce over the kernel Reducer protocol (#8). Each shard
+ * folds its own records to a partial STATE; states are merged centrally and
+ * finalized once — identical to central `reduceRecords` over the union, but
+ * without materializing the union. Used by the scalar `.aggregate().run()` path
+ * when every reducer exposes `merge` (else the caller falls back to central).
+ */
+
+/** One opaque reducer state per spec key. */
+type PartialState = Record<string, unknown>;
+
 /** A source that can fan out records across shards. Satisfied by ShardedQuery. */
 interface FanoutRecordSource<R> {
     fanoutRecords(options: FanoutQueryOptions): Promise<{
         records: R[];
         skippedVaults: SkippedVault[];
     }>;
+    /** Optional distributed partial-reduce (#8): fold each shard to a state in-callback. */
+    fanoutReduce?(spec: AggregateSpec, options: FanoutQueryOptions): Promise<{
+        partials: PartialState[];
+        skippedVaults: SkippedVault[];
+    }>;
 }
 /** Live-binding hooks (change subscription + relevance) threaded from ShardedQuery. */
 interface LiveBinding {
@@ -524,8 +541,12 @@ interface LiveBinding {
     isRelevant: (e: ChangeEvent) => boolean;
 }
 /**
- * One-shot cross-vault aggregate. Concatenates all shard records and runs a
- * single central reduce, ensuring correct avg/mean values.
+ * One-shot cross-vault aggregate. When every reducer in the spec exposes the
+ * `merge` seam, `run()` uses **distributed partial-reduce** — each shard folds
+ * its own records to a partial state, merged centrally and finalized once (no
+ * union materialized). A spec with any merge-less reducer falls back to
+ * central-reduce. The result is identical either way. `.live()` and grouped
+ * aggregates remain central-reduce.
  */
 declare class CrossVaultAggregation<R, Spec extends AggregateSpec> {
     private readonly src;
@@ -627,9 +648,11 @@ declare class VaultGroup<T> {
     shard(partitionKey: string): Promise<Vault$1>;
     /** A sharded view over one logical collection across all shards. */
     collection<R = T>(collectionName: string): ShardedCollection<T, R>;
-    /** @internal — eligible (openable-candidate) rows + drift/divergence skips. */
+    /** @internal — eligible (openable-candidate) rows + drift/divergence/unreachable skips. */
     resolveEligible(options?: {
         minVersion?: number;
+        only?: readonly string[];
+        failFast?: boolean;
     }): Promise<{
         eligible: VaultRegistryRow[];
         skipped: SkippedVault[];
@@ -671,11 +694,24 @@ declare class VaultGroup<T> {
      * 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).
+     * A shard whose backend is unreachable (provisioning probe or read throws) is
+     * **skipped** (`reason: 'error'`) and the pass continues for the others — its
+     * prior summary is left intact. Pass `failFast: true` for the legacy
+     * all-or-nothing throw. Reconcile a lagging shard later with
+     * `refreshInsights({ only: [pk] })` or `refreshDerivation(pk)`.
      */
     refreshInsights(options?: {
         minVersion?: number;
         concurrency?: number;
+        only?: readonly string[];
+        failFast?: boolean;
     }): Promise<RefreshInsightsResult>;
+    /**
+     * Reconcile one shard's Insight summaries after its backend was unreachable.
+     * Equivalent to `refreshInsights({ only: [partitionKey] })` — runs every
+     * registered derivation (autoPush or not) for just this shard.
+     */
+    refreshDerivation(partitionKey: string): Promise<RefreshInsightsResult>;
     /** @internal — re-derive + push every autoPush derivation's summary for one shard. */
     private _recomputeShardInsights;
     /**
@@ -739,6 +775,16 @@ declare class ShardedQuery<T, R = T> {
         records: R[];
         skippedVaults: SkippedVault[];
     }>;
+    /**
+     * @internal — distributed partial-reduce (#8). Fan out across eligible shards,
+     * but fold each shard's where-filtered records to a partial reducer STATE
+     * inside the per-shard callback (never returning the rows). Only the scalar
+     * `.aggregate()` path calls this, and that path rejects join legs upstream.
+     */
+    fanoutReduce(spec: AggregateSpec, options?: FanoutQueryOptions): Promise<{
+        partials: PartialState[];
+        skippedVaults: SkippedVault[];
+    }>;
     /** Fan out across eligible shards, merge, then apply any broadcast dimension legs. */
     toArray(options?: FanoutQueryOptions): Promise<FanoutResult<R>>;
     /** @internal — build the change-subscription + relevance binding for this query's group+collection. */

package/dist/{vault-group-BXjO5kHB.d.ts → vault-group-DqEyXbN1.d.ts}

@@ -511,12 +511,29 @@ interface BroadcastLeg {
     readonly mode: 'warn' | 'cascade';
 }
 
+/**
+ * @category capability
+ * Distributed partial-reduce over the kernel Reducer protocol (#8). Each shard
+ * folds its own records to a partial STATE; states are merged centrally and
+ * finalized once — identical to central `reduceRecords` over the union, but
+ * without materializing the union. Used by the scalar `.aggregate().run()` path
+ * when every reducer exposes `merge` (else the caller falls back to central).
+ */
+
+/** One opaque reducer state per spec key. */
+type PartialState = Record<string, unknown>;
+
 /** A source that can fan out records across shards. Satisfied by ShardedQuery. */
 interface FanoutRecordSource<R> {
     fanoutRecords(options: FanoutQueryOptions): Promise<{
         records: R[];
         skippedVaults: SkippedVault[];
     }>;
+    /** Optional distributed partial-reduce (#8): fold each shard to a state in-callback. */
+    fanoutReduce?(spec: AggregateSpec, options: FanoutQueryOptions): Promise<{
+        partials: PartialState[];
+        skippedVaults: SkippedVault[];
+    }>;
 }
 /** Live-binding hooks (change subscription + relevance) threaded from ShardedQuery. */
 interface LiveBinding {
@@ -524,8 +541,12 @@ interface LiveBinding {
     isRelevant: (e: ChangeEvent) => boolean;
 }
 /**
- * One-shot cross-vault aggregate. Concatenates all shard records and runs a
- * single central reduce, ensuring correct avg/mean values.
+ * One-shot cross-vault aggregate. When every reducer in the spec exposes the
+ * `merge` seam, `run()` uses **distributed partial-reduce** — each shard folds
+ * its own records to a partial state, merged centrally and finalized once (no
+ * union materialized). A spec with any merge-less reducer falls back to
+ * central-reduce. The result is identical either way. `.live()` and grouped
+ * aggregates remain central-reduce.
  */
 declare class CrossVaultAggregation<R, Spec extends AggregateSpec> {
     private readonly src;
@@ -627,9 +648,11 @@ declare class VaultGroup<T> {
     shard(partitionKey: string): Promise<Vault$1>;
     /** A sharded view over one logical collection across all shards. */
     collection<R = T>(collectionName: string): ShardedCollection<T, R>;
-    /** @internal — eligible (openable-candidate) rows + drift/divergence skips. */
+    /** @internal — eligible (openable-candidate) rows + drift/divergence/unreachable skips. */
     resolveEligible(options?: {
         minVersion?: number;
+        only?: readonly string[];
+        failFast?: boolean;
     }): Promise<{
         eligible: VaultRegistryRow[];
         skipped: SkippedVault[];
@@ -671,11 +694,24 @@ declare class VaultGroup<T> {
      * 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).
+     * A shard whose backend is unreachable (provisioning probe or read throws) is
+     * **skipped** (`reason: 'error'`) and the pass continues for the others — its
+     * prior summary is left intact. Pass `failFast: true` for the legacy
+     * all-or-nothing throw. Reconcile a lagging shard later with
+     * `refreshInsights({ only: [pk] })` or `refreshDerivation(pk)`.
      */
     refreshInsights(options?: {
         minVersion?: number;
         concurrency?: number;
+        only?: readonly string[];
+        failFast?: boolean;
     }): Promise<RefreshInsightsResult>;
+    /**
+     * Reconcile one shard's Insight summaries after its backend was unreachable.
+     * Equivalent to `refreshInsights({ only: [partitionKey] })` — runs every
+     * registered derivation (autoPush or not) for just this shard.
+     */
+    refreshDerivation(partitionKey: string): Promise<RefreshInsightsResult>;
     /** @internal — re-derive + push every autoPush derivation's summary for one shard. */
     private _recomputeShardInsights;
     /**
@@ -739,6 +775,16 @@ declare class ShardedQuery<T, R = T> {
         records: R[];
         skippedVaults: SkippedVault[];
     }>;
+    /**
+     * @internal — distributed partial-reduce (#8). Fan out across eligible shards,
+     * but fold each shard's where-filtered records to a partial reducer STATE
+     * inside the per-shard callback (never returning the rows). Only the scalar
+     * `.aggregate()` path calls this, and that path rejects join legs upstream.
+     */
+    fanoutReduce(spec: AggregateSpec, options?: FanoutQueryOptions): Promise<{
+        partials: PartialState[];
+        skippedVaults: SkippedVault[];
+    }>;
     /** Fan out across eligible shards, merge, then apply any broadcast dimension legs. */
     toArray(options?: FanoutQueryOptions): Promise<FanoutResult<R>>;
     /** @internal — build the change-subscription + relevance binding for this query's group+collection. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klum-db/lobby",
-  "version": "0.2.0-pre.29",
+  "version": "0.2.0-pre.31",
   "description": "klum-db Lobby — orchestrates a group of sovereign noy-db vaults (federation, interchange, custody). The outward framework to noy-db's inward vault.",
   "license": "MIT",
   "author": "vLannaAi <vicio@lanna.ai>",
@@ -46,6 +46,14 @@
     "@noy-db/in-devtools": "^0.2.0-pre.26",
     "@noy-db/to-meter": "^0.2.0-pre.26"
   },
+  "peerDependenciesMeta": {
+    "@noy-db/in-devtools": {
+      "optional": true
+    },
+    "@noy-db/to-meter": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@eslint/js": "^9.18.0",
     "@noy-db/as-xlsx": "0.2.0-pre.26",