@klum-db/lobby 0.2.0-pre.30 → 0.2.0-pre.32

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

@@ -1,4 +1,4 @@
-import { Vault as Vault$1, IndexDef, Operator, LiveQuery, LiveAggregation, AggregateSpec, AggregateResult, Collection, Noydb, Query, JoinStrategy, ChangeEvent } from '@noy-db/hub/kernel';
+import { Vault as Vault$1, VaultMeta, IndexDef, Operator, LiveQuery, LiveAggregation, AggregateSpec, AggregateResult, RetrieveHit, Collection, Noydb, Query, JoinStrategy, ChangeEvent } from '@noy-db/hub/kernel';
 import { Vault } from '@noy-db/hub';
 import { DecryptedRecord } from '@noy-db/hub/bundle';
 
@@ -154,6 +154,17 @@ declare function mergeCompartment(receiver: Vault, compartmentBytes: Uint8Array,
  * docs/superpowers/specs/2026-06-07-mvf-vaultgroup-routing-mvp-design.md.
  */
 
+/** A federation group's own descriptive metadata (reuses the noy-db VaultMeta shape). */
+type GroupMeta = VaultMeta;
+/** Federation-level metadata: the group's own meta + each member vault's vaultMeta. */
+interface FederationMeta {
+    readonly meta: GroupMeta | undefined;
+    readonly vaults: ReadonlyArray<{
+        readonly vaultId: string;
+        readonly partitionKey: string;
+        readonly meta: VaultMeta | undefined;
+    }>;
+}
 /**
  * A schema blueprint for a class of shard vaults. `configure` is
  * re-applied to every shard handle so all shards are configured
@@ -210,6 +221,8 @@ interface VaultGroupOptions<T> {
      * Zero cost for shards never opened. Default `false` (use `rolloutSchema`).
      */
     readonly cutoverOnOpen?: boolean;
+    /** Descriptive group-level metadata (label/description/icon) for UIs. Descriptive-only. */
+    readonly meta?: GroupMeta;
 }
 /** Result of `VaultGroup.rolloutSchema` (#271 active batch runner). */
 interface SchemaRolloutResult {
@@ -241,6 +254,32 @@ interface FanoutResult<R> {
     readonly results: R[];
     readonly skippedVaults: SkippedVault[];
 }
+/** Options for cross-vault federated retrieval (#26). Extends the fan-out base. */
+interface FederatedRetrieveOptions extends FanoutQueryOptions {
+    readonly mode?: 'lexical' | 'semantic' | 'hybrid';
+    readonly limit?: number;
+    readonly minScore?: number;
+    readonly fields?: readonly string[];
+    readonly match?: 'any' | 'all';
+    readonly prefix?: boolean;
+    readonly snippetWindow?: number;
+    readonly includeRecord?: boolean;
+    /** Payload filter applied per-vault (retrieve ∩ where), rebuilt into each shard's `within`. */
+    readonly where?: ReadonlyArray<readonly [field: string, op: Operator, value: unknown]>;
+    /** RRF constant; default 60. */
+    readonly rrfK?: number;
+    /** Re-throw a per-shard retrieve() failure instead of skipping it. */
+    readonly failFast?: boolean;
+}
+/** A fused hit carrying the originating shard (provenance). */
+interface FederatedRetrieveHit<R> extends RetrieveHit<R> {
+    readonly vault: string;
+}
+/** Result of `ShardedCollection.retrieve()`. */
+interface FederatedRetrieveResult<R> {
+    readonly hits: FederatedRetrieveHit<R>[];
+    readonly skippedVaults: SkippedVault[];
+}
 /** A single captured where-clause, replayed inside each shard. */
 interface WhereClause {
     readonly field: string;
@@ -511,12 +550,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 +580,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;
@@ -569,13 +629,15 @@ declare class VaultGroup<T> {
     /** @internal */ readonly sharding: ShardingConfig<T>;
     /** @internal */ readonly template: VaultTemplate;
     /** @internal — lazy cutover-on-open (#271). */ readonly cutoverOnOpen: boolean;
+    /** @internal — group-level descriptive metadata (#27). */ readonly meta?: GroupMeta | undefined;
     constructor(
     /** @internal */ db: Noydb, 
     /** @internal */ name: string, 
     /** @internal */ registry: Collection<VaultRegistryRow>, 
     /** @internal */ sharding: ShardingConfig<T>, 
     /** @internal */ template: VaultTemplate, 
-    /** @internal — lazy cutover-on-open (#271). */ cutoverOnOpen?: boolean);
+    /** @internal — lazy cutover-on-open (#271). */ cutoverOnOpen?: boolean, 
+    /** @internal — group-level descriptive metadata (#27). */ meta?: GroupMeta | undefined);
     /** @internal — set when the group is managed (no explicit registry). */
     private stateVault;
     /** @internal */
@@ -598,6 +660,14 @@ declare class VaultGroup<T> {
      * `liveBinding().isRelevant` already applies to the reactive path.
      */
     allRows(): Promise<VaultRegistryRow[]>;
+    /**
+     * Federation-level descriptive metadata (#27): this group's `meta` plus each
+     * member vault's `vaultMeta` (read via `getMeta()`). Best-effort per shard — a
+     * shard that fails to open yields `meta: undefined` for that entry, never
+     * throwing. Member meta is transient per-open (noy-db sets it at `openVault`,
+     * does not persist it); this surfaces whatever each vault was opened with.
+     */
+    federationMeta(): Promise<FederationMeta>;
     /**
      * Open an existing shard and apply the template. When `cutoverOnOpen` is set
      * (#271) and the shard's registry version is behind the template, its cutover
@@ -627,9 +697,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 +743,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;
     /**
@@ -721,6 +806,15 @@ declare class ShardedCollection<T, R = T> {
     put(id: string, record: T): Promise<void>;
     /** Begin a cross-shard fan-out query. */
     query(): ShardedQuery<T, R>;
+    /**
+     * Cross-vault federated retrieval (#26): scatter-gather across all eligible
+     * shards — each shard runs its own trusted-tier `retrieve()`, then results are
+     * RRF-fused by rank only (no cross-vault statistics cross the DEK boundary).
+     * Every hit carries its originating `vault`. An unreachable, schema-drifted, or
+     * un-indexed shard is skipped (`skippedVaults`); pass `failFast` to re-throw
+     * the first per-shard error instead.
+     */
+    retrieve(query: string, opts?: FederatedRetrieveOptions): Promise<FederatedRetrieveResult<R>>;
 }
 declare class ShardedQuery<T, R = T> {
     private readonly group;
@@ -739,6 +833,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. */
@@ -760,4 +864,4 @@ declare class ShardedGroupedQuery<T, R, F extends string> {
     aggregate<Spec extends AggregateSpec>(spec: Spec): CrossVaultGroupedAggregation<R, F, Spec>;
 }
 
-export { ShardedGroupedQuery as A, ShardedQuery as B, type CapturedBlueprint as C, type DecryptedMergeOptions as D, type ShardingConfig as E, type FanoutQueryOptions as F, type GroupedRow as G, type SurfaceStatus as H, type VaultRegistryRow as I, mergeCompartment as J, mergeDecryptedRecords as K, type LiveQueryOptions as L, type MergeCompartmentOptions as M, resolveFieldAuthority as N, resolveRecordByFieldAuthority as O, type RefreshInsightsResult as R, StateManagementVault as S, VaultGroup as V, type VaultTemplate as a, type SkippedVault as b, type MergeReport as c, type SurfaceDirection as d, type SurfaceConflictPolicy as e, type SurfaceRow as f, type VaultGroupOptions as g, CrossVaultAggregation as h, type CrossVaultDerivationContext as i, type CrossVaultDerivationSpec as j, CrossVaultGroupedAggregation as k, type CrossVaultLiveAggregation as l, type CrossVaultLiveQuery as m, type DeploymentEvent as n, type FanoutResult as o, type FieldAuthorityInputs as p, type FieldAuthorityPolicy as q, FieldAuthorityPolicyMissingError as r, type FieldAuthorityRule as s, FieldLevelDeferredError as t, type MergeConflict as u, type MergeStrategy as v, type MigrationStatusRow as w, type SchemaManifestRow as x, type SchemaRolloutResult as y, ShardedCollection as z };
+export { type MergeStrategy as A, type MigrationStatusRow as B, type CapturedBlueprint as C, type DecryptedMergeOptions as D, type SchemaManifestRow as E, type FanoutQueryOptions as F, type GroupedRow as G, type SchemaRolloutResult as H, ShardedCollection as I, ShardedGroupedQuery as J, ShardedQuery as K, type LiveQueryOptions as L, type MergeCompartmentOptions as M, type ShardingConfig as N, type SurfaceStatus as O, type VaultRegistryRow as P, mergeCompartment as Q, type RefreshInsightsResult as R, StateManagementVault as S, mergeDecryptedRecords as T, resolveFieldAuthority as U, VaultGroup as V, resolveRecordByFieldAuthority as W, type VaultTemplate as a, type SkippedVault as b, type MergeReport as c, type SurfaceDirection as d, type SurfaceConflictPolicy as e, type SurfaceRow as f, type VaultGroupOptions as g, CrossVaultAggregation as h, type CrossVaultDerivationContext as i, type CrossVaultDerivationSpec as j, CrossVaultGroupedAggregation as k, type CrossVaultLiveAggregation as l, type CrossVaultLiveQuery as m, type DeploymentEvent as n, type FanoutResult as o, type FederatedRetrieveHit as p, type FederatedRetrieveOptions as q, type FederatedRetrieveResult as r, type FederationMeta as s, type FieldAuthorityInputs as t, type FieldAuthorityPolicy as u, FieldAuthorityPolicyMissingError as v, type FieldAuthorityRule as w, FieldLevelDeferredError as x, type GroupMeta as y, type MergeConflict as z };

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

@@ -1,4 +1,4 @@
-import { Vault as Vault$1, IndexDef, Operator, LiveQuery, LiveAggregation, AggregateSpec, AggregateResult, Collection, Noydb, Query, JoinStrategy, ChangeEvent } from '@noy-db/hub/kernel';
+import { Vault as Vault$1, VaultMeta, IndexDef, Operator, LiveQuery, LiveAggregation, AggregateSpec, AggregateResult, RetrieveHit, Collection, Noydb, Query, JoinStrategy, ChangeEvent } from '@noy-db/hub/kernel';
 import { Vault } from '@noy-db/hub';
 import { DecryptedRecord } from '@noy-db/hub/bundle';
 
@@ -154,6 +154,17 @@ declare function mergeCompartment(receiver: Vault, compartmentBytes: Uint8Array,
  * docs/superpowers/specs/2026-06-07-mvf-vaultgroup-routing-mvp-design.md.
  */
 
+/** A federation group's own descriptive metadata (reuses the noy-db VaultMeta shape). */
+type GroupMeta = VaultMeta;
+/** Federation-level metadata: the group's own meta + each member vault's vaultMeta. */
+interface FederationMeta {
+    readonly meta: GroupMeta | undefined;
+    readonly vaults: ReadonlyArray<{
+        readonly vaultId: string;
+        readonly partitionKey: string;
+        readonly meta: VaultMeta | undefined;
+    }>;
+}
 /**
  * A schema blueprint for a class of shard vaults. `configure` is
  * re-applied to every shard handle so all shards are configured
@@ -210,6 +221,8 @@ interface VaultGroupOptions<T> {
      * Zero cost for shards never opened. Default `false` (use `rolloutSchema`).
      */
     readonly cutoverOnOpen?: boolean;
+    /** Descriptive group-level metadata (label/description/icon) for UIs. Descriptive-only. */
+    readonly meta?: GroupMeta;
 }
 /** Result of `VaultGroup.rolloutSchema` (#271 active batch runner). */
 interface SchemaRolloutResult {
@@ -241,6 +254,32 @@ interface FanoutResult<R> {
     readonly results: R[];
     readonly skippedVaults: SkippedVault[];
 }
+/** Options for cross-vault federated retrieval (#26). Extends the fan-out base. */
+interface FederatedRetrieveOptions extends FanoutQueryOptions {
+    readonly mode?: 'lexical' | 'semantic' | 'hybrid';
+    readonly limit?: number;
+    readonly minScore?: number;
+    readonly fields?: readonly string[];
+    readonly match?: 'any' | 'all';
+    readonly prefix?: boolean;
+    readonly snippetWindow?: number;
+    readonly includeRecord?: boolean;
+    /** Payload filter applied per-vault (retrieve ∩ where), rebuilt into each shard's `within`. */
+    readonly where?: ReadonlyArray<readonly [field: string, op: Operator, value: unknown]>;
+    /** RRF constant; default 60. */
+    readonly rrfK?: number;
+    /** Re-throw a per-shard retrieve() failure instead of skipping it. */
+    readonly failFast?: boolean;
+}
+/** A fused hit carrying the originating shard (provenance). */
+interface FederatedRetrieveHit<R> extends RetrieveHit<R> {
+    readonly vault: string;
+}
+/** Result of `ShardedCollection.retrieve()`. */
+interface FederatedRetrieveResult<R> {
+    readonly hits: FederatedRetrieveHit<R>[];
+    readonly skippedVaults: SkippedVault[];
+}
 /** A single captured where-clause, replayed inside each shard. */
 interface WhereClause {
     readonly field: string;
@@ -511,12 +550,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 +580,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;
@@ -569,13 +629,15 @@ declare class VaultGroup<T> {
     /** @internal */ readonly sharding: ShardingConfig<T>;
     /** @internal */ readonly template: VaultTemplate;
     /** @internal — lazy cutover-on-open (#271). */ readonly cutoverOnOpen: boolean;
+    /** @internal — group-level descriptive metadata (#27). */ readonly meta?: GroupMeta | undefined;
     constructor(
     /** @internal */ db: Noydb, 
     /** @internal */ name: string, 
     /** @internal */ registry: Collection<VaultRegistryRow>, 
     /** @internal */ sharding: ShardingConfig<T>, 
     /** @internal */ template: VaultTemplate, 
-    /** @internal — lazy cutover-on-open (#271). */ cutoverOnOpen?: boolean);
+    /** @internal — lazy cutover-on-open (#271). */ cutoverOnOpen?: boolean, 
+    /** @internal — group-level descriptive metadata (#27). */ meta?: GroupMeta | undefined);
     /** @internal — set when the group is managed (no explicit registry). */
     private stateVault;
     /** @internal */
@@ -598,6 +660,14 @@ declare class VaultGroup<T> {
      * `liveBinding().isRelevant` already applies to the reactive path.
      */
     allRows(): Promise<VaultRegistryRow[]>;
+    /**
+     * Federation-level descriptive metadata (#27): this group's `meta` plus each
+     * member vault's `vaultMeta` (read via `getMeta()`). Best-effort per shard — a
+     * shard that fails to open yields `meta: undefined` for that entry, never
+     * throwing. Member meta is transient per-open (noy-db sets it at `openVault`,
+     * does not persist it); this surfaces whatever each vault was opened with.
+     */
+    federationMeta(): Promise<FederationMeta>;
     /**
      * Open an existing shard and apply the template. When `cutoverOnOpen` is set
      * (#271) and the shard's registry version is behind the template, its cutover
@@ -627,9 +697,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 +743,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;
     /**
@@ -721,6 +806,15 @@ declare class ShardedCollection<T, R = T> {
     put(id: string, record: T): Promise<void>;
     /** Begin a cross-shard fan-out query. */
     query(): ShardedQuery<T, R>;
+    /**
+     * Cross-vault federated retrieval (#26): scatter-gather across all eligible
+     * shards — each shard runs its own trusted-tier `retrieve()`, then results are
+     * RRF-fused by rank only (no cross-vault statistics cross the DEK boundary).
+     * Every hit carries its originating `vault`. An unreachable, schema-drifted, or
+     * un-indexed shard is skipped (`skippedVaults`); pass `failFast` to re-throw
+     * the first per-shard error instead.
+     */
+    retrieve(query: string, opts?: FederatedRetrieveOptions): Promise<FederatedRetrieveResult<R>>;
 }
 declare class ShardedQuery<T, R = T> {
     private readonly group;
@@ -739,6 +833,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. */
@@ -760,4 +864,4 @@ declare class ShardedGroupedQuery<T, R, F extends string> {
     aggregate<Spec extends AggregateSpec>(spec: Spec): CrossVaultGroupedAggregation<R, F, Spec>;
 }
 
-export { ShardedGroupedQuery as A, ShardedQuery as B, type CapturedBlueprint as C, type DecryptedMergeOptions as D, type ShardingConfig as E, type FanoutQueryOptions as F, type GroupedRow as G, type SurfaceStatus as H, type VaultRegistryRow as I, mergeCompartment as J, mergeDecryptedRecords as K, type LiveQueryOptions as L, type MergeCompartmentOptions as M, resolveFieldAuthority as N, resolveRecordByFieldAuthority as O, type RefreshInsightsResult as R, StateManagementVault as S, VaultGroup as V, type VaultTemplate as a, type SkippedVault as b, type MergeReport as c, type SurfaceDirection as d, type SurfaceConflictPolicy as e, type SurfaceRow as f, type VaultGroupOptions as g, CrossVaultAggregation as h, type CrossVaultDerivationContext as i, type CrossVaultDerivationSpec as j, CrossVaultGroupedAggregation as k, type CrossVaultLiveAggregation as l, type CrossVaultLiveQuery as m, type DeploymentEvent as n, type FanoutResult as o, type FieldAuthorityInputs as p, type FieldAuthorityPolicy as q, FieldAuthorityPolicyMissingError as r, type FieldAuthorityRule as s, FieldLevelDeferredError as t, type MergeConflict as u, type MergeStrategy as v, type MigrationStatusRow as w, type SchemaManifestRow as x, type SchemaRolloutResult as y, ShardedCollection as z };
+export { type MergeStrategy as A, type MigrationStatusRow as B, type CapturedBlueprint as C, type DecryptedMergeOptions as D, type SchemaManifestRow as E, type FanoutQueryOptions as F, type GroupedRow as G, type SchemaRolloutResult as H, ShardedCollection as I, ShardedGroupedQuery as J, ShardedQuery as K, type LiveQueryOptions as L, type MergeCompartmentOptions as M, type ShardingConfig as N, type SurfaceStatus as O, type VaultRegistryRow as P, mergeCompartment as Q, type RefreshInsightsResult as R, StateManagementVault as S, mergeDecryptedRecords as T, resolveFieldAuthority as U, VaultGroup as V, resolveRecordByFieldAuthority as W, type VaultTemplate as a, type SkippedVault as b, type MergeReport as c, type SurfaceDirection as d, type SurfaceConflictPolicy as e, type SurfaceRow as f, type VaultGroupOptions as g, CrossVaultAggregation as h, type CrossVaultDerivationContext as i, type CrossVaultDerivationSpec as j, CrossVaultGroupedAggregation as k, type CrossVaultLiveAggregation as l, type CrossVaultLiveQuery as m, type DeploymentEvent as n, type FanoutResult as o, type FederatedRetrieveHit as p, type FederatedRetrieveOptions as q, type FederatedRetrieveResult as r, type FederationMeta as s, type FieldAuthorityInputs as t, type FieldAuthorityPolicy as u, FieldAuthorityPolicyMissingError as v, type FieldAuthorityRule as w, FieldLevelDeferredError as x, type GroupMeta as y, type MergeConflict as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klum-db/lobby",
-  "version": "0.2.0-pre.30",
+  "version": "0.2.0-pre.32",
   "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>",
@@ -41,10 +41,10 @@
     "node": ">=18.0.0"
   },
   "peerDependencies": {
-    "@noy-db/as-xlsx": "^0.2.0-pre.26",
-    "@noy-db/hub": "^0.2.0-pre.26",
-    "@noy-db/in-devtools": "^0.2.0-pre.26",
-    "@noy-db/to-meter": "^0.2.0-pre.26"
+    "@noy-db/as-xlsx": "^0.2.0-pre.29",
+    "@noy-db/hub": "^0.2.0-pre.29",
+    "@noy-db/in-devtools": "^0.2.0-pre.29",
+    "@noy-db/to-meter": "^0.2.0-pre.29"
   },
   "peerDependenciesMeta": {
     "@noy-db/in-devtools": {
@@ -56,12 +56,12 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.18.0",
-    "@noy-db/as-xlsx": "0.2.0-pre.26",
-    "@noy-db/as-zip": "0.2.0-pre.26",
-    "@noy-db/hub": "0.2.0-pre.26",
-    "@noy-db/in-devtools": "0.2.0-pre.26",
-    "@noy-db/to-memory": "0.2.0-pre.26",
-    "@noy-db/to-meter": "0.2.0-pre.26",
+    "@noy-db/as-xlsx": "0.2.0-pre.30",
+    "@noy-db/as-zip": "0.2.0-pre.30",
+    "@noy-db/hub": "0.2.0-pre.30",
+    "@noy-db/in-devtools": "0.2.0-pre.30",
+    "@noy-db/to-memory": "0.2.0-pre.30",
+    "@noy-db/to-meter": "0.2.0-pre.30",
     "@types/node": "^22.0.0",
     "eslint": "^9.18.0",
     "tsup": "^8.4.0",