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

package/dist/{vault-group-DqEyXbN1.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;
@@ -590,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 */
@@ -619,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
@@ -757,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;
@@ -806,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-DqEyXbN1.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;
@@ -590,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 */
@@ -619,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
@@ -757,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;
@@ -806,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.31",
+  "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",