@klum-db/lobby 0.2.0-pre.27 → 0.2.0-pre.28

package/dist/vault-group-DeBoCFT9.d.cts

@@ -0,0 +1,763 @@
+import { Vault as Vault$1, IndexDef, Operator, LiveQuery, LiveAggregation, AggregateSpec, AggregateResult, Collection, Noydb, Query, JoinStrategy, ChangeEvent } from '@noy-db/hub/kernel';
+import { Vault } from '@noy-db/hub';
+import { DecryptedRecord } from '@noy-db/hub/bundle';
+
+/**
+ * @klum-db/lobby interchange — field-authority conflict resolution (FR-4).
+ *
+ * Pure functions: given an app-supplied per-field policy and both sides'
+ * RECORD-level provenance (FR-5 `_source`/`_sourceTs`), decide field-by-field
+ * whether the incoming value wins. No vault I/O — unit-testable in isolation.
+ * @module
+ */
+/** How a single field's authority is decided on merge. */
+type FieldAuthorityRule = {
+    readonly authority: 'source-newest';
+} | {
+    readonly authority: 'owner';
+    readonly ownerSource: string;
+} | {
+    readonly authority: 'fixed-source';
+    readonly source: string;
+};
+/** Per-collection field → rule map. Fields not listed default to keep-local. */
+type FieldAuthorityPolicy = Record<string, FieldAuthorityRule>;
+/** Record-level provenance for both sides (shared across all fields — Q3 defer). */
+interface FieldAuthorityInputs {
+    readonly incomingSource?: string;
+    readonly incomingSourceTs?: string;
+    readonly localSource?: string;
+    readonly localSourceTs?: string;
+}
+/** Thrown when a collection resolves to `field-authority` but no policy is supplied for it. */
+declare class FieldAuthorityPolicyMissingError extends Error {
+    constructor(collection: string);
+}
+/** Decide whether the INCOMING value of one field wins. Pure. Defaults never clobber on ambiguity. */
+declare function resolveFieldAuthority(rule: FieldAuthorityRule, io: FieldAuthorityInputs): 'incoming' | 'local';
+/**
+ * Build the merged record per policy, starting from the local (`before`) copy
+ * and overlaying only the changed fields whose rule resolves to `incoming`.
+ * Returns the merged record plus a per-field decision map (for the audit report).
+ * Pure — no I/O.
+ */
+declare function resolveRecordByFieldAuthority(policy: FieldAuthorityPolicy, before: Record<string, unknown>, incoming: Record<string, unknown>, changedFields: readonly string[], io: FieldAuthorityInputs): {
+    merged: Record<string, unknown>;
+    decisions: Record<string, 'incoming' | 'local'>;
+};
+
+/**
+ * @klum-db/lobby interchange — reconcile an incoming extracted-partition
+ * compartment into an existing receiver vault (FR-3).
+ *
+ * `mergeCompartment(receiver, compartmentBytes, opts)` → `MergeReport`:
+ *   1. Decrypt the incoming bytes via hub's `decryptExtractedPartition`.
+ *   2. `diffVault(receiver, incoming)` classifies records as added / modified
+ *      / deleted (deleted = receiver-only slice, ignored per FR-3 semantics).
+ *   3. Resolve each `modified` entry per the per-collection strategy.
+ *   4. Apply writes via `collection.put(id, rec, { reason })` (unless dryRun).
+ *
+ * @module
+ */
+
+/** Per-collection conflict strategy. `field-level` is a deprecated alias for `field-authority`. */
+type MergeStrategy = 'take-incoming' | 'keep-local' | 'lww-by-ts' | 'manual-queue' | 'field-authority'
+/** @deprecated Use `field-authority` instead. */
+ | 'field-level';
+/** Options for the decrypted-records merge path (no bundle, no transfer key). */
+interface DecryptedMergeOptions {
+    readonly strategy: MergeStrategy | (Record<string, MergeStrategy> & {
+        default?: MergeStrategy;
+    });
+    readonly dryRun?: boolean;
+    /** Audit reason stamped on every write. Defaults to `'merge:compartment'`. */
+    readonly reason?: string;
+    /** Per-collection field→authority policy. Required for any collection using `field-authority`. */
+    readonly fieldAuthority?: Record<string, FieldAuthorityPolicy>;
+}
+/** Options for the bundle merge path — adds the transfer key for decryption. */
+interface MergeCompartmentOptions extends DecryptedMergeOptions {
+    readonly transferKey: Uint8Array;
+}
+interface MergeConflict {
+    readonly collection: string;
+    readonly id: string;
+    readonly strategy: MergeStrategy;
+    readonly resolution: 'incoming' | 'local' | 'queued' | 'field-merged';
+}
+interface MergeReport {
+    readonly vault: string;
+    readonly dryRun: boolean;
+    readonly summary: {
+        readonly inserted: number;
+        readonly updated: number;
+        readonly skipped: number;
+        readonly queued: number;
+        readonly total: number;
+    };
+    readonly byCollection: Record<string, {
+        readonly inserted: number;
+        readonly updated: number;
+        readonly skipped: number;
+        readonly queued: number;
+    }>;
+    /**
+     * One entry per `modified` (id-collision) record, regardless of outcome —
+     * including `take-incoming` overwrites (`resolution: 'incoming'`). This is a
+     * full audit trail of every conflict the merge encountered and how it was
+     * resolved, not just the ones that were skipped or queued.
+     */
+    readonly conflicts: readonly MergeConflict[];
+}
+/**
+ * @deprecated No longer thrown — `field-level` is now a deprecated alias for
+ * `field-authority` and resolves via the field-authority resolver (FR-4).
+ * Kept for backwards compatibility of existing imports.
+ */
+declare class FieldLevelDeferredError extends Error {
+    constructor(collection: string);
+}
+/**
+ * Merge an already-decrypted record set into the receiver. The shared core of
+ * `mergeCompartment` (decrypt → this) and `migrateThenMerge` (decrypt → migrate → this).
+ * `decrypted` is keyed by collection; each record carries id/record/ts/source/sourceTs.
+ *
+ * Semantics:
+ * - **added**: in incoming, not in receiver → always insert (every strategy).
+ * - **modified**: in both, body differs → resolve per collection strategy.
+ * - **deleted**: in receiver, not in incoming → IGNORE (incoming is a slice;
+ *   never delete receiver rows).
+ * - **unchanged**: no-op.
+ *
+ * Returns a {@link MergeReport} describing what was (or would be) written.
+ * When `dryRun: true` the report is fully computed but no `put()` is called.
+ *
+ * Writes are applied sequentially and **non-transactionally**: a `put()`
+ * failure mid-loop (e.g. schema mismatch or a storage error) rejects the
+ * returned promise but leaves the receiver partially merged. Use `dryRun`
+ * first to validate the plan when partial application is unacceptable.
+ */
+declare function mergeDecryptedRecords(receiver: Vault, decrypted: Record<string, readonly DecryptedRecord[]>, opts: DecryptedMergeOptions): Promise<MergeReport>;
+/**
+ * Reconcile an incoming extracted-partition compartment into a receiver vault.
+ * Decrypts the compartment bytes then delegates to {@link mergeDecryptedRecords}.
+ *
+ * See {@link mergeDecryptedRecords} for full semantics, dryRun behaviour, and
+ * the non-transactional write caveat.
+ */
+declare function mergeCompartment(receiver: Vault, compartmentBytes: Uint8Array, opts: MergeCompartmentOptions): Promise<MergeReport>;
+
+/**
+ * @category capability
+ * Multi-vault partition federation (MVF) — public types for VaultGroup
+ * transparent shard routing. See
+ * docs/superpowers/specs/2026-06-07-mvf-vaultgroup-routing-mvp-design.md.
+ */
+
+/**
+ * A schema blueprint for a class of shard vaults. `configure` is
+ * re-applied to every shard handle so all shards are configured
+ * identically (collections, indexes, schemas). `version` is recorded
+ * into each shard's registry row and drives the fan-out
+ * `minVersion` guard.
+ */
+interface VaultTemplate {
+    readonly version: number;
+    readonly configure: (vault: Vault$1) => void;
+}
+/** One row in the StateManagement `vault-registry` collection. */
+interface VaultRegistryRow {
+    readonly vaultId: string;
+    readonly partitionKey: string;
+    readonly templateName: string;
+    readonly schemaVersion: number;
+    readonly createdAt: number;
+    /** Which VaultGroup this shard belongs to (registry is shared across groups). */
+    readonly group: string;
+}
+/** How a VaultGroup maps records to shards. */
+interface ShardingConfig<T> {
+    /** Extract the partition key from a record. */
+    readonly keyOf: (record: T) => string;
+    /** Name of the template (registered via `withVaultTemplate`) shards are stamped from. */
+    readonly vaultTemplate: string;
+    /** When a write targets an unknown partition key, stamp a shard inline. Default `true`. */
+    readonly autoCreate?: boolean;
+    /**
+     * Data-residency guard (#271): the geographic region a record's shard must
+     * live in (e.g. `'eu'`). When set, `createShard` resolves the candidate
+     * backend (via `routeStore`'s vault-prefix routing) and throws
+     * `DataResidencyError` if its `capabilities.region` doesn't match — so a
+     * shard never lands on a non-compliant backend. Advisory until a region is
+     * declared on the backing store; pair with `routeStore({ vaultRoutes })`
+     * and a region-encoded partition key (e.g. `eu-acme` → `firm--eu-`).
+     */
+    readonly regionOf?: (record: T) => string;
+}
+/** Options for `Noydb.openVaultGroup`. */
+interface VaultGroupOptions<T> {
+    /**
+     * The `vault-registry` collection (source of truth for shard discovery).
+     * Optional: when omitted, the reserved StateManagement vault's registry
+     * is auto-opened and used.
+     */
+    readonly registry?: Collection<VaultRegistryRow>;
+    readonly sharding: ShardingConfig<T>;
+    /**
+     * Lazy migrate-on-open (#271 fleet migration). When `true`, opening a shard
+     * whose registry `schemaVersion` is behind the template's version runs that
+     * shard's cutover inline (via `migrateShard`) before surfacing the handle.
+     * Zero cost for shards never opened. Default `false` (use `migrateFleet`).
+     */
+    readonly migrateOnOpen?: boolean;
+}
+/** Result of `VaultGroup.migrateFleet` (#271 active batch runner). */
+interface FleetMigrationResult {
+    /** The version migrated toward (the template's current version). */
+    readonly target: number;
+    /** vaultIds successfully migrated (or already current). */
+    readonly migrated: string[];
+    /** vaultIds whose cutover failed, with the error message. */
+    readonly failed: {
+        readonly vaultId: string;
+        readonly error: string;
+    }[];
+}
+/** Options for a cross-shard fan-out read. */
+interface FanoutQueryOptions {
+    /** Skip shards whose registry `schemaVersion` is below this. */
+    readonly minVersion?: number;
+    /** Max shards queried in parallel (passed to queryAcross). Default 1. */
+    readonly concurrency?: number;
+}
+/** A shard excluded from a fan-out result, with the reason. */
+interface SkippedVault {
+    readonly vaultId: string;
+    readonly reason: 'schema-drift' | 'error' | 'no-grant';
+    readonly error?: Error;
+}
+/** The result of a cross-shard fan-out read. */
+interface FanoutResult<R> {
+    readonly results: R[];
+    readonly skippedVaults: SkippedVault[];
+}
+/** A single captured where-clause, replayed inside each shard. */
+interface WhereClause {
+    readonly field: string;
+    readonly op: Operator;
+    readonly value: unknown;
+}
+/** Options for the live/aggregate fan-out (extends the one-shot opts). */
+interface LiveQueryOptions extends FanoutQueryOptions {
+    /** Coalesce window before recompute. Default 0 (microtask). */
+    readonly debounceMs?: number;
+}
+/** A grouped aggregate output row: the grouped field + the reduced spec result. */
+type GroupedRow<F extends string, Spec extends AggregateSpec> = {
+    readonly [K in F]: unknown;
+} & AggregateResult<Spec>;
+/** Reactive cross-shard record (or grouped-row) query — array-shaped, mirrors LiveQuery<T>. */
+interface CrossVaultLiveQuery<T> extends LiveQuery<T> {
+    readonly skippedVaults: readonly SkippedVault[];
+    readonly ready: Promise<void>;
+}
+/** Reactive cross-shard scalar aggregate — mirrors LiveAggregation<R>. */
+interface CrossVaultLiveAggregation<R> extends LiveAggregation<R> {
+    readonly skippedVaults: readonly SkippedVault[];
+    readonly ready: Promise<void>;
+}
+/**
+ * Context passed to a cross-vault `derive` callback (#271 Insight Vault).
+ * One call per shard; identifies which shard the records came from.
+ */
+interface CrossVaultDerivationContext {
+    /** The shard's vault id (e.g. `firm-clients--acme`). */
+    readonly vaultId: string;
+    /** The shard's partition key (e.g. `acme`). */
+    readonly partitionKey: string;
+    /** The shard's schema/template version, from its registry row. */
+    readonly schemaVersion: number;
+}
+/**
+ * A push-model cross-vault derivation (#271, Insight Vault — Layer 4).
+ *
+ * For each eligible shard, `refreshInsights()` reads the shard's `source`
+ * collection, runs `derive` on that shard's records, and writes the returned
+ * summary row into a separate analytics ("Insight") vault — keyed by partition
+ * key, one row per shard. The summary is re-encrypted under the Insight Vault's
+ * own DEK; the shard's ciphertext never leaves its DEK boundary (the push model
+ * that resolves the cross-vault DEK conflict). See the ZK note in the spec —
+ * the Insight Vault backend sees aggregated structure across shards, a weaker
+ * profile than per-shard vaults; opt-in.
+ */
+interface CrossVaultDerivationSpec<R = Record<string, unknown>, S = Record<string, unknown>> {
+    /** Collection read from each shard. */
+    readonly source: string;
+    /** Destination Insight Vault + collection for the per-shard summary rows. */
+    readonly target: {
+        readonly vault: string;
+        readonly collection: string;
+    };
+    /** Per-shard reducer: that shard's source records + context → one summary row. */
+    readonly derive: (records: R[], ctx: CrossVaultDerivationContext) => S;
+    /**
+     * Opt in to auto-push-on-write (#12): when a write lands on a shard's
+     * `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()`).
+     */
+    readonly autoPush?: boolean;
+}
+/** The result of `refreshInsights()`. */
+interface RefreshInsightsResult {
+    /** Number of summary rows written (one per eligible shard × registered derivation). */
+    readonly written: number;
+    /** Shards excluded (schema-drift, unprovisioned, or read error). */
+    readonly skippedVaults: SkippedVault[];
+}
+/** A serializable blueprint captured from a VaultTemplate.configure run. */
+interface CapturedBlueprint {
+    /** Sorted collection names declared by the template. */
+    readonly collections: string[];
+    /** Per-collection index defs (key order canonicalized). */
+    readonly indexes: Record<string, IndexDef[]>;
+    /** Collections that declared `persistJsonSchema: true`. */
+    readonly persistJsonSchema: string[];
+}
+/** One row in the StateManagement `schema-manifest` collection, keyed by `${templateName}:${version}`. */
+interface SchemaManifestRow {
+    readonly templateName: string;
+    readonly version: number;
+    readonly collections: string[];
+    readonly indexes: Record<string, IndexDef[]>;
+    readonly persistJsonSchema: string[];
+    /** sha256 over the canonicalized serializable blueprint. */
+    readonly fingerprint: string;
+    readonly recordedAt: number;
+}
+/** One row in the append-only StateManagement `deployment-events` collection. */
+interface DeploymentEvent {
+    readonly id: string;
+    readonly ts: number;
+    readonly type: 'shard-created' | 'manifest-recorded' | 'group-opened' | 'migration-started' | 'migration-completed' | 'migration-failed' | 'unit-graduated';
+    readonly group: string;
+    readonly vaultId?: string;
+    readonly templateName?: string;
+    readonly version?: number;
+    readonly actor?: string;
+    /** Free-form detail (e.g. migration error message). */
+    readonly detail?: string;
+}
+/**
+ * One row in the StateManagement `migration-status` collection (#271 fleet
+ * schema-migration runner), keyed by `vaultId`. Tracks each shard's progress
+ * toward the template's current version so the active batch runner is
+ * resumable and the staged rollout can verify a cohort before proceeding.
+ */
+interface MigrationStatusRow {
+    readonly vaultId: string;
+    readonly group: string;
+    /** The shard's registry schemaVersion at the time of this status. */
+    readonly currentVersion: number;
+    /** The version the runner is moving this shard to (the template's version). */
+    readonly targetVersion: number;
+    readonly status: 'pending' | 'running' | 'done' | 'failed';
+    readonly startedAt?: number;
+    readonly finishedAt?: number;
+    /** Records migrated by the per-shard cutover (when status `done`). */
+    readonly migrated?: number;
+    readonly error?: string;
+}
+/** Which direction the sync flows across the surface boundary. */
+type SurfaceDirection = 'push' | 'pull' | 'bidi';
+/** Lifecycle state of a bilateral surface agreement. */
+type SurfaceStatus = 'proposed' | 'agreed' | 'suspended';
+/**
+ * Conflict resolution policy for a Surface.
+ * `strategy` may be a single MergeStrategy applied to all collections, or a
+ * per-collection map (with an optional `default` fallback).
+ */
+interface SurfaceConflictPolicy {
+    readonly strategy: MergeStrategy | (Record<string, MergeStrategy> & {
+        default?: MergeStrategy;
+    });
+    readonly fieldAuthority?: Record<string, FieldAuthorityPolicy>;
+}
+/**
+ * Persisted row in the StateManagementVault `surfaces` collection (FR-7).
+ * Describes a bilaterally-agreed subset of collections/fields that two parties
+ * sync in a given direction with a given conflict policy.
+ */
+interface SurfaceRow {
+    readonly id: string;
+    /** Collection names included in this surface. */
+    readonly collections: readonly string[];
+    /** Per-collection field allow-lists (omit = all fields). */
+    readonly fields?: Record<string, readonly string[]>;
+    readonly direction: SurfaceDirection;
+    readonly conflictPolicy: SurfaceConflictPolicy;
+    /** Sync cadence in milliseconds (undefined = manual only). */
+    readonly cadenceMs?: number;
+    readonly status: SurfaceStatus;
+    readonly proposedBy: string;
+    readonly agreedBy?: string;
+    readonly createdAt: number;
+    readonly lastSyncAt?: number;
+    readonly nextSyncDueAt?: number;
+}
+
+/**
+ * @category capability
+ * StateManagement Vault — federation control plane (registry +
+ * schema-manifest + append-only deployment-events). See
+ * docs/superpowers/specs/2026-06-08-statemanagement-vault-design.md.
+ */
+
+declare class StateManagementVault {
+    #private;
+    readonly registry: Collection<VaultRegistryRow>;
+    readonly schemaManifest: Collection<SchemaManifestRow>;
+    private constructor();
+    /** Idempotently open the reserved state vault and bind the control-plane collections. */
+    static open(db: Noydb): Promise<StateManagementVault>;
+    /** Read one shard's migration status (or null). */
+    getMigrationStatus(vaultId: string): Promise<MigrationStatusRow | null>;
+    /** All migration-status rows (hydrates first). */
+    listMigrationStatus(): Promise<MigrationStatusRow[]>;
+    /** Upsert one shard's migration status (keyed by vaultId). */
+    upsertMigrationStatus(row: MigrationStatusRow): Promise<void>;
+    /** Persist a new Surface row (keyed by `row.id`). */
+    createSurface(row: SurfaceRow): Promise<void>;
+    /** Read one Surface row by id, or null if absent. */
+    getSurface(id: string): Promise<SurfaceRow | null>;
+    /** All persisted Surface rows (hydrates first). */
+    listSurfaces(): Promise<SurfaceRow[]>;
+    /**
+     * Merge `patch` into the existing Surface row keyed by `id`, persist the
+     * result, and return it. Mirrors the migrationStatus upsert pattern but
+     * returns the merged row for convenience.
+     */
+    updateSurface(id: string, patch: Partial<SurfaceRow>): Promise<SurfaceRow>;
+    /** Read-only query over the append-only deployment-events log. */
+    queryEvents(): Query<DeploymentEvent>;
+    /**
+     * Append a deployment event with a fresh unique (ULID) id. This is the
+     * only write path to the events log; no update/delete is exposed.
+     * Callers should treat failures as non-fatal — this method does not
+     * swallow errors, so wrap the call site in try/catch where appropriate.
+     */
+    appendEvent(event: Omit<DeploymentEvent, 'id' | 'ts'> & {
+        ts?: number;
+    }): Promise<void>;
+    /**
+     * Ensure a manifest row exists for `(templateName, template.version)`.
+     * Safe to call repeatedly: the `fingerprint` is a deterministic hash of
+     * the template's declared shape (stable across calls), though each call
+     * refreshes `recordedAt`.
+     */
+    recordManifest(templateName: string, template: VaultTemplate): Promise<string>;
+    /**
+     * True when `template`'s current declared shape does not match the recorded
+     * manifest for `(templateName, template.version)`. Because shards carry no
+     * schema state independent of their template, this catches "a template's
+     * shape changed without bumping `version`" — not independent per-shard drift.
+     * A missing manifest is treated as drift (nothing to verify against).
+     */
+    detectDrift(templateName: string, template: VaultTemplate): Promise<boolean>;
+}
+
+/** Public options for `ShardedQuery.crossShardJoin`. */
+interface CrossShardJoinOptions {
+    /** Alias key under which the joined same-shard record attaches. */
+    readonly as: string;
+    /** Per-shard row ceiling override (default DEFAULT_JOIN_MAX_ROWS). */
+    readonly maxRows?: number;
+    /** Planner strategy override, passed through to intra-vault `.join()`. */
+    readonly strategy?: JoinStrategy;
+}
+/**
+ * Minimal structural shape of a broadcast dimension source. A
+ * `Collection` satisfies this natively: `list()` hydrates and returns
+ * the decoded records. Kept as a one-method interface so plain test
+ * sources are trivial to construct.
+ */
+interface BroadcastSource {
+    list(): Promise<readonly unknown[]>;
+}
+/** Public options for `ShardedQuery.broadcastJoin`. */
+interface BroadcastJoinOptions {
+    /** Alias key under which the dimension record attaches. */
+    readonly as: string;
+    /** The shared dimension collection (an opened handle in another vault). */
+    readonly from: BroadcastSource;
+    /** Right-side key to match `field` against. Default 'id'. */
+    readonly on?: string;
+    /** Miss behavior. 'warn' (default) attaches null + one-shot warning; 'cascade' is silent. */
+    readonly mode?: 'warn' | 'cascade';
+}
+/** Internal co-partitioned leg carried on ShardedQuery. */
+interface CoPartitionedLeg {
+    readonly field: string;
+    readonly as: string;
+    readonly maxRows: number | undefined;
+    readonly strategy: JoinStrategy | undefined;
+}
+/** Internal broadcast leg carried on ShardedQuery. */
+interface BroadcastLeg {
+    readonly field: string;
+    readonly as: string;
+    readonly from: BroadcastSource;
+    readonly on: string;
+    readonly mode: 'warn' | 'cascade';
+}
+
+/** A source that can fan out records across shards. Satisfied by ShardedQuery. */
+interface FanoutRecordSource<R> {
+    fanoutRecords(options: FanoutQueryOptions): Promise<{
+        records: R[];
+        skippedVaults: SkippedVault[];
+    }>;
+}
+/** Live-binding hooks (change subscription + relevance) threaded from ShardedQuery. */
+interface LiveBinding {
+    subscribeToChanges: (handler: (e: ChangeEvent) => void) => () => void;
+    isRelevant: (e: ChangeEvent) => boolean;
+}
+/**
+ * One-shot cross-vault aggregate. Concatenates all shard records and runs a
+ * single central reduce, ensuring correct avg/mean values.
+ */
+declare class CrossVaultAggregation<R, Spec extends AggregateSpec> {
+    private readonly src;
+    private readonly spec;
+    private readonly bind?;
+    constructor(src: FanoutRecordSource<R>, spec: Spec, bind?: LiveBinding | undefined);
+    run(options?: FanoutQueryOptions): Promise<{
+        result: AggregateResult<Spec>;
+        skippedVaults: SkippedVault[];
+    }>;
+    live(options?: LiveQueryOptions): CrossVaultLiveAggregation<AggregateResult<Spec>>;
+}
+/**
+ * One-shot cross-vault grouped aggregate. Concatenates all shard records and
+ * runs a single central group-and-reduce, emitting one row per bucket.
+ */
+declare class CrossVaultGroupedAggregation<R, F extends string, Spec extends AggregateSpec> {
+    private readonly src;
+    private readonly field;
+    private readonly spec;
+    private readonly bind?;
+    constructor(src: FanoutRecordSource<R>, field: F, spec: Spec, bind?: LiveBinding | undefined);
+    run(options?: FanoutQueryOptions): Promise<{
+        results: GroupedRow<F, Spec>[];
+        skippedVaults: SkippedVault[];
+    }>;
+    live(options?: LiveQueryOptions): CrossVaultLiveQuery<GroupedRow<F, Spec>>;
+}
+
+/**
+ * @category capability
+ * Multi-vault partition federation — VaultGroup transparent shard
+ * routing. Spec:
+ * docs/superpowers/specs/2026-06-07-mvf-vaultgroup-routing-mvp-design.md.
+ */
+
+declare class VaultGroup<T> {
+    /** @internal */ readonly db: Noydb;
+    /** @internal */ readonly name: string;
+    /** @internal */ readonly registry: Collection<VaultRegistryRow>;
+    /** @internal */ readonly sharding: ShardingConfig<T>;
+    /** @internal */ readonly template: VaultTemplate;
+    /** @internal — lazy migrate-on-open (#271). */ readonly migrateOnOpen: boolean;
+    constructor(
+    /** @internal */ db: Noydb, 
+    /** @internal */ name: string, 
+    /** @internal */ registry: Collection<VaultRegistryRow>, 
+    /** @internal */ sharding: ShardingConfig<T>, 
+    /** @internal */ template: VaultTemplate, 
+    /** @internal — lazy migrate-on-open (#271). */ migrateOnOpen?: boolean);
+    /** @internal — set when the group is managed (no explicit registry). */
+    private stateVault;
+    /** @internal */
+    _attachStateVault(sv: StateManagementVault): void;
+    /** Deterministic vault name for a partition key, namespaced by the group. */
+    shardVaultId(partitionKey: string): string;
+    /**
+     * @internal — group-qualified registry record key (avoids cross-group key
+     * collisions). Identical to the shard vault id by design — the registry row
+     * for a shard is keyed by that shard's vault id — so it delegates to
+     * `shardVaultId`, reusing its partition-key validation.
+     */
+    registryId(partitionKey: string): string;
+    /**
+     * Registry rows for THIS group (hydrates the registry collection first).
+     * The registry may be shared across groups (the auto-wired StateManagement
+     * vault holds one `vaultRegistry` for the whole instance), so rows are
+     * filtered by `group` — without this, a group's fan-out reads would leak
+     * across into other groups' shards. Mirrors the `${group}--` scoping that
+     * `liveBinding().isRelevant` already applies to the reactive path.
+     */
+    allRows(): Promise<VaultRegistryRow[]>;
+    /**
+     * Open an existing shard and apply the template. When `migrateOnOpen` is set
+     * (#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>;
+    /** @internal — open + configure with no migrate-on-open hook (used by the migration path itself to avoid recursion). */
+    private _openShardRaw;
+    /**
+     * Idempotently provision a shard for `partitionKey`. Returns the
+     * configured vault handle.
+     *
+     * - row + vault present → no-op, return handle
+     * - row present, vault gone → ShardProvisioningError
+     * - row absent (vault present or not) → open-or-create, configure, write row
+     *
+     * When `region` is given (the routing `put` passes `sharding.regionOf(record)`),
+     * 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>;
+    /**
+     * 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>;
+    /** 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. */
+    resolveEligible(options?: {
+        minVersion?: number;
+    }): Promise<{
+        eligible: VaultRegistryRow[];
+        skipped: SkippedVault[];
+    }>;
+    /** @internal — registered push-model cross-vault derivations (#271 Insight Vault). */
+    private readonly crossVaultDerivations;
+    /** @internal — auto-push controller; created (and the change-subscription armed) when the first autoPush derivation registers. */
+    private insightAutoPush?;
+    /**
+     * Register a push-model cross-vault derivation — the Insight Vault pattern
+     * (#271, Layer 4). Drive it with {@link refreshInsights}.
+     *
+     * For each shard, `derive(records, ctx)` runs on that shard's `source`
+     * records and its return value is written into the analytics
+     * (`target.vault` / `target.collection`) vault, keyed by partition key —
+     * one summary row per shard. The derivation runs in-process under THIS
+     * group's `Noydb` (which already holds both the shard and Insight Vault
+     * keyrings); the shard's decrypted records are reduced to a summary that is
+     * re-encrypted under the Insight Vault's own DEK, so no shard ciphertext
+     * crosses a DEK boundary.
+     *
+     * **Zero-knowledge note:** the Insight Vault backend sees aggregated
+     * structure (totals, counts, timestamps) drawn from many shards — a weaker
+     * ZK profile than the per-shard vaults. Opt-in; keep summaries to aggregate
+     * scalars (no embeddings / no raw records).
+     *
+     * v1 is explicit-refresh (no write-path push); call `refreshInsights()`
+     * after a batch of writes, or on a schedule.
+     *
+     * The `target.vault` must NOT be the group itself or one of its shards —
+     * a summary writing back into client-shard data would breach the Insight
+     * Vault's separate-DEK-boundary contract. Such a target throws a
+     * `ValidationError` at registration (#271 Insight-write isolation).
+     */
+    withCrossVaultDerivation<R = Record<string, unknown>, S = Record<string, unknown>>(spec: CrossVaultDerivationSpec<R, S>): void;
+    /**
+     * Run every registered {@link withCrossVaultDerivation}: read each eligible
+     * shard's source records, derive a per-shard summary, and write it into the
+     * 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).
+     */
+    refreshInsights(options?: {
+        minVersion?: number;
+        concurrency?: number;
+    }): Promise<RefreshInsightsResult>;
+    /** @internal — re-derive + push every autoPush derivation's summary for one shard. */
+    private _recomputeShardInsights;
+    /**
+     * Await any pending Insight auto-push flush (#12). Resolves immediately when
+     * no autoPush derivation is registered or nothing is pending. Use after a
+     * batch of writes to observe the Insight Vault, or in tests.
+     */
+    whenInsightsSettled(): Promise<void>;
+    /** @internal — the control-plane vault for migration status; lazily opened. */
+    private ensureStateVault;
+    /**
+     * Migrate ONE shard to the template's current version (#271 fleet runner,
+     * per-shard step). Opens the shard (applying the template, which arms the
+     * M12 cutover), drains schema-write detection, runs `vault.runSchemaCutover()`
+     * (the per-vault drain-barrier-transform protocol), then advances the
+     * registry row's `schemaVersion` and records `migration-status`. A shard
+     * already at the template version is a no-op (`status: 'done'`, migrated 0).
+     * Never throws on a cutover failure — it records `status: 'failed'` and
+     * returns the row, so a fleet run continues past a bad shard.
+     */
+    migrateShard(partitionKey: string): Promise<MigrationStatusRow>;
+    /**
+     * Active batch runner (#271): migrate every shard behind the template version
+     * to it, in controlled batches. **Resumable + crash-safe** — shards already at
+     * the target are skipped (the registry version is the source of truth), so a
+     * re-run after a crash only picks up the unfinished + previously-failed shards.
+     *
+     * - `cohort` — restrict to these partition keys (the staged / canary rollout:
+     *   migrate a small cohort, verify the Insight Vault, then run the rest).
+     * - `batchSize` — max shards migrated concurrently per batch (back-pressure).
+     *   Default 4. Batches run sequentially; shards within a batch run in parallel.
+     */
+    migrateFleet(options?: {
+        cohort?: readonly string[];
+        batchSize?: number;
+    }): Promise<FleetMigrationResult>;
+}
+declare class ShardedCollection<T, R = T> {
+    private readonly group;
+    private readonly collectionName;
+    constructor(group: VaultGroup<T>, collectionName: string);
+    /** Route a write to the shard owning `keyOf(record)`. */
+    put(id: string, record: T): Promise<void>;
+    /** Begin a cross-shard fan-out query. */
+    query(): ShardedQuery<T, R>;
+}
+declare class ShardedQuery<T, R = T> {
+    private readonly group;
+    private readonly collectionName;
+    private readonly clauses;
+    private readonly coPartitionedLegs;
+    private readonly broadcastLegs;
+    constructor(group: VaultGroup<T>, collectionName: string, clauses: readonly WhereClause[], coPartitionedLegs?: readonly CoPartitionedLeg[], broadcastLegs?: readonly BroadcastLeg[]);
+    where(field: string, op: WhereClause['op'], value: unknown): ShardedQuery<T, R>;
+    /** Co-partitioned join: each shard joins its own same-vault right collection (resolved via ref()), then union. */
+    crossShardJoin(field: string, opts: CrossShardJoinOptions): ShardedQuery<T, R>;
+    /** Broadcast dimension join: enrich every merged row from a single shared collection. */
+    broadcastJoin(field: string, opts: BroadcastJoinOptions): ShardedQuery<T, R>;
+    /** @internal — fan out the where-filtered records across eligible shards. */
+    fanoutRecords(options?: FanoutQueryOptions): Promise<{
+        records: R[];
+        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. */
+    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. */
+    live(options?: LiveQueryOptions): CrossVaultLiveQuery<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. */
+    groupBy<F extends string>(field: F): ShardedGroupedQuery<T, R, F>;
+}
+/** Grouped cross-shard query — intermediate after `.groupBy(field)`, terminates with `.aggregate(spec)`. */
+declare class ShardedGroupedQuery<T, R, F extends string> {
+    private readonly query;
+    private readonly field;
+    constructor(query: ShardedQuery<T, R>, field: F);
+    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 FleetMigrationResult as u, type MergeConflict as v, type MergeStrategy as w, type MigrationStatusRow as x, type SchemaManifestRow as y, ShardedCollection as z };