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

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

@@ -317,6 +317,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 +351,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 {
@@ -847,10 +855,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 +886,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-SfkQJ3CM.d.ts}

@@ -317,6 +317,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 +351,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 {
@@ -847,10 +855,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 +886,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.2.0-pre.33",
   "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>",