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

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

@@ -1,5 +1,4 @@
-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 { Vault, VaultMeta, IndexDef, Operator, LiveQuery, LiveAggregation, AggregateSpec, AggregateResult, RetrieveHit, Collection, Noydb, Query, JoinStrategy, ChangeEvent } from '@noy-db/hub/cargo';
 import { DecryptedRecord } from '@noy-db/hub/bundle';
 
 /**
@@ -174,7 +173,7 @@ interface FederationMeta {
  */
 interface VaultTemplate {
     readonly version: number;
-    readonly configure: (vault: Vault$1) => void;
+    readonly configure: (vault: Vault) => void;
 }
 /** One row in the StateManagement `vault-registry` collection. */
 interface VaultRegistryRow {
@@ -317,6 +316,13 @@ interface CrossVaultDerivationContext {
     /** The shard's schema/template version, from its registry row. */
     readonly schemaVersion: number;
 }
+/** Tuning for auto-push-on-write (#13). */
+interface InsightAutoPushConfig {
+    /** Reset-debounce window (ms): batch a multi-tick write burst into one re-derive. Omit = microtask coalescing. */
+    readonly debounceMs?: number;
+    /** Skip auto-pushing a shard whose registry `schemaVersion` is below this. */
+    readonly minVersion?: number;
+}
 /**
  * A push-model cross-vault derivation (#271, Insight Vault — Layer 4).
  *
@@ -344,8 +350,9 @@ interface CrossVaultDerivationSpec<R = Record<string, unknown>, S = Record<strin
      * `source` collection, recompute and push that shard's summary
      * automatically (coalesced per microtask). Default off — without this the
      * derivation is explicit-refresh-only (drive it with `refreshInsights()`).
+     * Pass an object to enable debounce / minVersion tuning (#13).
      */
-    readonly autoPush?: boolean;
+    readonly autoPush?: boolean | InsightAutoPushConfig;
 }
 /** The result of `refreshInsights()`. */
 interface RefreshInsightsResult {
@@ -673,7 +680,7 @@ declare class VaultGroup<T> {
      * (#271) and the shard's registry version is behind the template, its cutover
      * runs inline first — so a behind shard never surfaces a stale handle.
      */
-    openShard(partitionKey: string): Promise<Vault$1>;
+    openShard(partitionKey: string): Promise<Vault>;
     /** @internal — open + configure with no cutover-on-open hook (used by the migration path itself to avoid recursion). */
     private _openShardRaw;
     /**
@@ -688,13 +695,13 @@ declare class VaultGroup<T> {
      * the candidate backend's `capabilities.region` must match or this throws
      * `DataResidencyError` BEFORE provisioning (#271 data-residency guard).
      */
-    createShard(partitionKey: string, region?: string): Promise<Vault$1>;
+    createShard(partitionKey: string, region?: string): Promise<Vault>;
     /**
      * Drill down to a single shard's full Collection API. Throws if the shard is unknown.
      * Also throws ShardProvisioningError if the registry row exists but the vault has been deleted
      * (registry/store divergence).
      */
-    shard(partitionKey: string): Promise<Vault$1>;
+    shard(partitionKey: string): Promise<Vault>;
     /** 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/unreachable skips. */
@@ -847,10 +854,24 @@ declare class ShardedQuery<T, R = T> {
     toArray(options?: FanoutQueryOptions): Promise<FanoutResult<R>>;
     /** @internal — build the change-subscription + relevance binding for this query's group+collection. */
     liveBinding(): LiveBinding;
-    /** @internal — joined queries don't support reactive/aggregate surfaces in v1. */
-    private assertNoJoinLegs;
-    /** 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?: LiveQueryOptions): CrossVaultLiveQuery<R>;
+    /**
+     * @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(): FanoutRecordSource<R>;
     /** One-shot distributed aggregate — central reduce over all shard records. */
     aggregate<Spec extends AggregateSpec>(spec: Spec): CrossVaultAggregation<R, Spec>;
     /** Begin a grouped cross-shard aggregate. */
@@ -864,4 +885,4 @@ declare class ShardedGroupedQuery<T, R, F extends string> {
     aggregate<Spec extends AggregateSpec>(spec: Spec): CrossVaultGroupedAggregation<R, F, Spec>;
 }
 
-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 };
+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, type InsightAutoPushConfig as I, ShardedCollection as J, ShardedGroupedQuery as K, type LiveQueryOptions as L, type MergeCompartmentOptions as M, ShardedQuery as N, type ShardingConfig as O, type SurfaceStatus as P, type VaultRegistryRow as Q, type RefreshInsightsResult as R, StateManagementVault as S, mergeCompartment as T, mergeDecryptedRecords as U, VaultGroup as V, resolveFieldAuthority as W, resolveRecordByFieldAuthority as X, 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-BchRCDm5.d.ts → vault-group-D0EC-D5c.d.ts}

@@ -1,5 +1,4 @@
-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 { Vault, VaultMeta, IndexDef, Operator, LiveQuery, LiveAggregation, AggregateSpec, AggregateResult, RetrieveHit, Collection, Noydb, Query, JoinStrategy, ChangeEvent } from '@noy-db/hub/cargo';
 import { DecryptedRecord } from '@noy-db/hub/bundle';
 
 /**
@@ -174,7 +173,7 @@ interface FederationMeta {
  */
 interface VaultTemplate {
     readonly version: number;
-    readonly configure: (vault: Vault$1) => void;
+    readonly configure: (vault: Vault) => void;
 }
 /** One row in the StateManagement `vault-registry` collection. */
 interface VaultRegistryRow {
@@ -317,6 +316,13 @@ interface CrossVaultDerivationContext {
     /** The shard's schema/template version, from its registry row. */
     readonly schemaVersion: number;
 }
+/** Tuning for auto-push-on-write (#13). */
+interface InsightAutoPushConfig {
+    /** Reset-debounce window (ms): batch a multi-tick write burst into one re-derive. Omit = microtask coalescing. */
+    readonly debounceMs?: number;
+    /** Skip auto-pushing a shard whose registry `schemaVersion` is below this. */
+    readonly minVersion?: number;
+}
 /**
  * A push-model cross-vault derivation (#271, Insight Vault — Layer 4).
  *
@@ -344,8 +350,9 @@ interface CrossVaultDerivationSpec<R = Record<string, unknown>, S = Record<strin
      * `source` collection, recompute and push that shard's summary
      * automatically (coalesced per microtask). Default off — without this the
      * derivation is explicit-refresh-only (drive it with `refreshInsights()`).
+     * Pass an object to enable debounce / minVersion tuning (#13).
      */
-    readonly autoPush?: boolean;
+    readonly autoPush?: boolean | InsightAutoPushConfig;
 }
 /** The result of `refreshInsights()`. */
 interface RefreshInsightsResult {
@@ -673,7 +680,7 @@ declare class VaultGroup<T> {
      * (#271) and the shard's registry version is behind the template, its cutover
      * runs inline first — so a behind shard never surfaces a stale handle.
      */
-    openShard(partitionKey: string): Promise<Vault$1>;
+    openShard(partitionKey: string): Promise<Vault>;
     /** @internal — open + configure with no cutover-on-open hook (used by the migration path itself to avoid recursion). */
     private _openShardRaw;
     /**
@@ -688,13 +695,13 @@ declare class VaultGroup<T> {
      * the candidate backend's `capabilities.region` must match or this throws
      * `DataResidencyError` BEFORE provisioning (#271 data-residency guard).
      */
-    createShard(partitionKey: string, region?: string): Promise<Vault$1>;
+    createShard(partitionKey: string, region?: string): Promise<Vault>;
     /**
      * Drill down to a single shard's full Collection API. Throws if the shard is unknown.
      * Also throws ShardProvisioningError if the registry row exists but the vault has been deleted
      * (registry/store divergence).
      */
-    shard(partitionKey: string): Promise<Vault$1>;
+    shard(partitionKey: string): Promise<Vault>;
     /** 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/unreachable skips. */
@@ -847,10 +854,24 @@ declare class ShardedQuery<T, R = T> {
     toArray(options?: FanoutQueryOptions): Promise<FanoutResult<R>>;
     /** @internal — build the change-subscription + relevance binding for this query's group+collection. */
     liveBinding(): LiveBinding;
-    /** @internal — joined queries don't support reactive/aggregate surfaces in v1. */
-    private assertNoJoinLegs;
-    /** 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?: LiveQueryOptions): CrossVaultLiveQuery<R>;
+    /**
+     * @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(): FanoutRecordSource<R>;
     /** One-shot distributed aggregate — central reduce over all shard records. */
     aggregate<Spec extends AggregateSpec>(spec: Spec): CrossVaultAggregation<R, Spec>;
     /** Begin a grouped cross-shard aggregate. */
@@ -864,4 +885,4 @@ declare class ShardedGroupedQuery<T, R, F extends string> {
     aggregate<Spec extends AggregateSpec>(spec: Spec): CrossVaultGroupedAggregation<R, F, Spec>;
 }
 
-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 };
+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, type InsightAutoPushConfig as I, ShardedCollection as J, ShardedGroupedQuery as K, type LiveQueryOptions as L, type MergeCompartmentOptions as M, ShardedQuery as N, type ShardingConfig as O, type SurfaceStatus as P, type VaultRegistryRow as Q, type RefreshInsightsResult as R, StateManagementVault as S, mergeCompartment as T, mergeDecryptedRecords as U, VaultGroup as V, resolveFieldAuthority as W, resolveRecordByFieldAuthority as X, 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.32",
+  "version": "0.3.0-pre.1",
   "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>",
@@ -38,13 +38,13 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.0.0"
   },
   "peerDependencies": {
-    "@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"
+    "@noy-db/as-xlsx": "^0.3.0-pre.1",
+    "@noy-db/hub": "^0.3.0-pre.1",
+    "@noy-db/in-devtools": "^0.3.0-pre.1",
+    "@noy-db/to-meter": "^0.3.0-pre.1"
   },
   "peerDependenciesMeta": {
     "@noy-db/in-devtools": {
@@ -56,12 +56,12 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.18.0",
-    "@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",
+    "@noy-db/as-xlsx": "0.3.0-pre.1",
+    "@noy-db/as-zip": "0.3.0-pre.1",
+    "@noy-db/hub": "0.3.0-pre.1",
+    "@noy-db/in-devtools": "0.3.0-pre.1",
+    "@noy-db/to-memory": "0.3.0-pre.1",
+    "@noy-db/to-meter": "0.3.0-pre.1",
     "@types/node": "^22.0.0",
     "eslint": "^9.18.0",
     "tsup": "^8.4.0",
@@ -87,7 +87,8 @@
   "scripts": {
     "build": "tsup",
     "test": "vitest run",
-    "lint": "eslint src/",
-    "typecheck": "tsc --noEmit"
+    "lint": "eslint src/ && pnpm check:architecture",
+    "typecheck": "tsc --noEmit",
+    "check:architecture": "node scripts/check-architecture.mjs"
   }
 }