@klum-db/lobby 0.4.0-pre.0 → 0.4.0-pre.1

package/dist/index.d.ts

@@ -1,10 +1,11 @@
-import { Vault, SealingKeyProvider, Noydb } from '@noy-db/hub/cargo';
+import { ExtractionPreview, Vault, SealingKeyProvider, Noydb } from '@noy-db/hub/cargo';
 export { CrossShardJoinError, CustodyApi, DataResidencyError, DeedMarker, GrantCustodianOptions, LiberateOptions, LiberateResult, ReservedVaultNameError, ShardProvisioningError, UnknownShardError, VaultTemplateNotFoundError, createDeedOwner, isDeedVault, liberateVault, loadDeedMarker } from '@noy-db/hub/cargo';
-import { a as VaultTemplate, S as StateManagementVault, V as VaultGroup, b as SkippedVault, M as MergeCompartmentOptions, c as MergeReport, d as SurfaceDirection, e as SurfaceConflictPolicy, f as SurfaceRow, g as VaultGroupOptions } from './vault-group-D0EC-D5c.js';
-export { C as CapturedBlueprint, h as CrossVaultAggregation, i as CrossVaultDerivationContext, j as CrossVaultDerivationSpec, k as CrossVaultGroupedAggregation, G as CrossVaultGroupedRow, l as CrossVaultLiveAggregation, m as CrossVaultLiveQuery, D as DecryptedMergeOptions, n as DeploymentEvent, F as FanoutQueryOptions, o as FanoutResult, p as FederatedRetrieveHit, q as FederatedRetrieveOptions, r as FederatedRetrieveResult, s as FederationMeta, t as FieldAuthorityInputs, u as FieldAuthorityPolicy, v as FieldAuthorityPolicyMissingError, w as FieldAuthorityRule, x as FieldLevelDeferredError, y as GroupMeta, I as InsightAutoPushConfig, L as LiveQueryOptions, z as MergeConflict, A as MergeStrategy, B as MigrationStatusRow, R as RefreshInsightsResult, E as SchemaManifestRow, H as SchemaRolloutResult, J as ShardedCollection, K as ShardedGroupedQuery, N as ShardedQuery, O as ShardingConfig, P as SurfaceStatus, Q as VaultRegistryRow, T as mergeCompartment, U as mergeDecryptedRecords, W as resolveFieldAuthority, X as resolveRecordByFieldAuthority } from './vault-group-D0EC-D5c.js';
+import { a as VaultRegistryRow, C as CrossVaultDerivationContext, I as InsightAutoPushConfig, V as VaultGroup, S as SkippedVault, b as VaultTemplate, c as StateManagementVault, M as MergeCompartmentOptions, d as MergeReport, e as SurfaceDirection, f as SurfaceConflictPolicy, g as SurfaceRow, h as VaultGroupOptions } from './vault-group-DJtzjwZK.js';
+export { i as CapturedBlueprint, j as CrossVaultAggregation, k as CrossVaultDerivationSpec, l as CrossVaultGroupedAggregation, G as CrossVaultGroupedRow, m as CrossVaultLiveAggregation, n as CrossVaultLiveQuery, D as DecryptedMergeOptions, o as DeploymentEvent, F as FanoutQueryOptions, p as FanoutResult, q as FederatedRetrieveHit, r as FederatedRetrieveOptions, s as FederatedRetrieveResult, t as FederationMeta, u as FieldAuthorityInputs, v as FieldAuthorityPolicy, w as FieldAuthorityPolicyMissingError, x as FieldAuthorityRule, y as FieldLevelDeferredError, z as GroupMeta, L as LiveQueryOptions, A as MergeConflict, B as MergeStrategy, E as MigrationStatusRow, P as PortalInviteAuditRef, H as PortalState, R as RefreshInsightsResult, J as SchemaManifestRow, K as SchemaRolloutResult, N as ShardedCollection, O as ShardedGroupedQuery, Q as ShardedQuery, T as ShardingConfig, U as SurfaceStatus, W as mergeCompartment, X as mergeDecryptedRecords, Y as resolveFieldAuthority, Z as resolveRecordByFieldAuthority } from './vault-group-DJtzjwZK.js';
 import { AsXlsxSheetOptions } from '@noy-db/as-xlsx';
 export { MultiVaultDenormColumn, MultiVaultXlsxEntry, MultiVaultXlsxOptions } from '@noy-db/as-xlsx';
-import { ExtractionPreview } from '@noy-db/hub/bundle';
+import { Role, Vault as Vault$1, Collection } from '@noy-db/hub';
+import { ShareLink } from '@noy-db/hub/share-link';
 import { InspectableContainer } from '@noy-db/in-devtools';
 import { Cover, WritePodOptions } from '@noy-db/hub/pod';
 
@@ -126,6 +127,278 @@ declare function describeCrossVaultExtraction(openVault: (name: string) => Promi
     maxDepth?: number;
 }): Promise<CrossVaultPreview>;
 
+/**
+ * Vendor-side deep-link addressing (#43). The share-link GRAMMAR is the
+ * hub's (`@noy-db/hub/share-link`, #806) — one canonical link shape for
+ * the LIFF permalink, the installed PWA, and the vendor console. The
+ * Lobby contributes the FLEET half: mapping the link's vault handle to
+ * the firm's registry row (resolve), and a client's registry row to its
+ * portal handle (build).
+ *
+ * Fail closed: unknown/foreign handles or clients throw a typed
+ * {@link ShareLinkResolutionError} whose message never enumerates the
+ * fleet (no vault ids, no partition keys beyond the caller's own input).
+ */
+
+/** Machine-readable {@link ShareLinkResolutionError} discriminant. */
+type ShareLinkResolutionErrorCode = 'UNKNOWN_VAULT_HANDLE' | 'UNKNOWN_CLIENT' | 'NO_PORTAL_HANDLE';
+/**
+ * Typed failure for fleet-side share-link resolution. Standalone
+ * (`extends Error`) mirroring the hub's `ShareLinkParseError` style.
+ * Fail closed: map to an app-level 404; never fall back to a default
+ * vault, and never leak fleet contents through the message.
+ */
+declare class ShareLinkResolutionError extends Error {
+    readonly code: ShareLinkResolutionErrorCode;
+    readonly name = "ShareLinkResolutionError";
+    constructor(code: ShareLinkResolutionErrorCode, message: string);
+}
+/** What {@link resolveShareLinkAgainstRegistry} returns. */
+interface ResolvedShareLink {
+    /** The parsed link (hub grammar), as-received or parsed from the raw string. */
+    readonly link: ShareLink;
+    /** The fleet registry row the link's vault handle resolved to. */
+    readonly row: VaultRegistryRow;
+    /**
+     * Console-route descriptor: everything the firm app needs to mint its
+     * OWN console URL for the addressed record. Descriptor, not redirect —
+     * the Lobby returns data, the app owns its routes.
+     */
+    readonly consoleRoute: {
+        readonly vaultId: string;
+        readonly collection: string;
+        readonly recordId: string;
+        readonly period?: string;
+        readonly version?: number;
+    };
+}
+/** Input to {@link buildShareLinkForClient}: fleet coordinates + link context. */
+interface BuildShareLinkForClientOptions {
+    /** The client's partition key in the fleet registry. */
+    readonly client: string;
+    /** Which VaultGroup the client belongs to (registry is shared across groups). */
+    readonly group: string;
+    readonly collection: string;
+    readonly record: string;
+    readonly period?: string;
+    readonly version?: number;
+    /** Single-use grant token — emitted only as the `#g=` fragment (hub rule). */
+    readonly grantToken?: string;
+    /** Origin prefix prepended verbatim by the hub builder (e.g. a LIFF permalink base). */
+    readonly base?: string;
+}
+
+/**
+ * Fleet-level portal provisioning (#42). One audited lobby operation
+ * that prepares a per-client portal vault: ensure the client shard
+ * exists in the fleet, assign the portal vault handle (the ULID that
+ * `share-link` links address, #43), apply firm custodian/admin grants,
+ * and issue the client's single-use, expiring magic-link invite — the
+ * seed for LINE-federated enrollment.
+ *
+ * Composes published primitives only: this repo's VaultGroup shard
+ * machinery, `@noy-db/hub` team grants (the session needs
+ * `teamStrategy: withTeam()`), and `@noy-db/on-magic-link`
+ * `issueInvite` / `issuePeerRecovery` / `revokeInvite`.
+ *
+ * Rebind (second-device enrollment, milestone security decision: new
+ * devices ONLY via firm re-invite) is `mode: 'rebind'` — a
+ * peer-recovery of the EXISTING principal, same keyring identity, no
+ * new principal by construction.
+ *
+ * The registry audit trail stores only safe fields (tokenId, userId,
+ * kind, timestamps) — NEVER the encoded invite, which carries the
+ * single-use temp passphrase.
+ *
+ * OIDC device-entry revocation (`revokeOidcDevice`) is deliberately
+ * NOT wrapped here: it requires the OIDC provider config and a live
+ * id-token — an auth context only the firm app holds.
+ */
+
+/** A firm-side slot to ensure on the client vault (custodian/admin). */
+interface PortalFirmGrant {
+    readonly userId: string;
+    readonly displayName: string;
+    readonly role: Role;
+    readonly passphrase: string;
+}
+/** Options for {@link provisionPortal}. */
+interface ProvisionPortalOptions {
+    /** The client's partition key in the fleet. */
+    readonly client: string;
+    /**
+     * `'invite'` (default) mints a NEW principal's enrollment invite;
+     * `'rebind'` re-invites the EXISTING principal (second device / lost
+     * access) — same keyring identity, no new principal.
+     */
+    readonly mode?: 'invite' | 'rebind';
+    /** The client principal the invite enrolls (or re-enrolls). */
+    readonly invite: {
+        readonly userId: string;
+        readonly displayName: string;
+        /** Defaults to `'client'`. */
+        readonly role?: Role;
+        readonly ttlMs?: number;
+        /** Override the generated temp phrase (deterministic tests only). */
+        readonly tempPhrase?: string;
+    };
+    /** Firm custodian/admin slots to ensure on the client vault. */
+    readonly firmGrants?: readonly PortalFirmGrant[];
+}
+/** What {@link provisionPortal} returns. */
+interface ProvisionPortalResult {
+    readonly vaultId: string;
+    /** The portal vault handle — the ULID share links address (#43). */
+    readonly handle: string;
+    /** The minted invite. `encoded` embeds after `#` in the app's invite URL. */
+    readonly invite: {
+        readonly encoded: string;
+        readonly tokenId: string;
+        readonly userId: string;
+        readonly expiresAt: string;
+    };
+    /** The updated fleet registry row (handle + portal audit trail). */
+    readonly row: VaultRegistryRow;
+}
+/** Options for {@link revokePortalInvite}. */
+interface RevokePortalInviteOptions {
+    readonly client: string;
+    readonly tokenId: string;
+}
+
+/** Explicit ZK surface: the only fields a model may emit. */
+interface ReadModelPosture {
+    readonly surface: readonly string[];
+}
+/** Rollup model: per-shard reduce → one summary row per shard. */
+interface RollupModelSpec<R = Record<string, unknown>, S extends Record<string, unknown> = Record<string, unknown>> {
+    /** Output collection name in the read-model vault. */
+    readonly name: string;
+    readonly kind: 'rollup';
+    /** Collection read from each shard (plain or MV-output — the engine is agnostic). */
+    readonly source: string;
+    /** Per-shard reducer. Must be pure — no clock, no randomness. */
+    readonly derive: (records: R[], ctx: CrossVaultDerivationContext) => S;
+    readonly posture: ReadModelPosture;
+}
+/**
+ * Mirror model (S2, #56): per-record replication of each shard's
+ * `source` collection (plain or #810-MV-output — the engine is
+ * agnostic) into one group-wide collection. Row id =
+ * `${shard}:${idOf(row)}` — identity is in-band, the same idiom as
+ * `sharding.keyOf`.
+ */
+interface MirrorModelSpec<R = Record<string, unknown>> {
+    /** Output collection name in the read-model vault. */
+    readonly name: string;
+    readonly kind: 'mirror';
+    /** Collection read from each shard (plain or MV-output — the engine is agnostic). */
+    readonly source: string;
+    /** Extract the source record's id (must be pure; parallel to `sharding.keyOf`). */
+    readonly idOf: (row: R) => string;
+    readonly posture: ReadModelPosture;
+}
+/** `never` makes caller-typed `derive`/`idOf` params assignable (contravariance). */
+type ReadModelSpec = RollupModelSpec<never> | MirrorModelSpec<never>;
+/** Options for `Lobby.openReadModel`. */
+interface OpenReadModelOptions {
+    /** The read-model vault. Must not be the group or one of its shards. */
+    readonly vault: string;
+    readonly models: readonly ReadModelSpec[];
+    /**
+     * Freshness (spec § 3). `autoPush` wires the #13 controller: a write
+     * on any model's `source` re-derives THAT shard's contribution only
+     * (never a full fan-out), coalesced per microtask — or on a
+     * reset-debounce timer via `{ debounceMs }`; `{ minVersion }` gates
+     * behind-version shards. Default off: explicit `refresh()` only.
+     */
+    readonly freshness?: {
+        readonly autoPush?: boolean | InsightAutoPushConfig;
+    };
+    /**
+     * Audience subset (spec § 5): only registry rows passing this
+     * predicate feed the read-model (e.g. an advisor's clients). Rows of
+     * a shard that falls OUT of scope retract on the next refresh — a
+     * narrowed audience never keeps out-of-scope data. Must be pure.
+     * Absent = the whole group.
+     */
+    readonly shards?: (row: VaultRegistryRow) => boolean;
+}
+/** The result of {@link ReadModel.refresh}. */
+interface ReadModelRefreshResult {
+    readonly written: number;
+    /** Rows removed by reconciliation: deleted sources + departed shards. */
+    readonly retracted: number;
+    readonly skippedVaults: SkippedVault[];
+}
+/** Fail-closed posture breach: a model emitted a field outside its declared surface. */
+declare class PostureViolationError extends Error {
+    readonly model: string;
+    readonly fields: readonly string[];
+    readonly shard: string;
+    readonly name = "PostureViolationError";
+    constructor(model: string, fields: readonly string[], shard: string);
+}
+/**
+ * A maintained federated read-model. Read side is deliberately boring:
+ * {@link collection} returns ordinary collections in the read-model
+ * vault — one query, never N shard opens.
+ */
+declare class ReadModel<T> {
+    private readonly group;
+    private readonly vaultName;
+    private readonly vault;
+    private readonly models;
+    private readonly shards?;
+    /** @internal — auto-push controller; armed by {@link _armAutoPush}. */
+    private autoPush;
+    /** @internal */
+    constructor(group: VaultGroup<T>, vaultName: string, vault: Vault$1, models: readonly ReadModelSpec[], shards?: ((row: VaultRegistryRow) => boolean) | undefined);
+    /**
+     * @internal — wire the #13 controller (spec § 3). Trigger is the
+     * Noydb-level change stream filtered to this group's shard vaults
+     * (`<group>--<pk>`); the read-model vault can never match that prefix
+     * (guarded at open), so its own writes can't loop back. Recompute is
+     * a per-shard `refresh({ only })` — rollup re-reduces and mirror
+     * reconciles just that shard; other shards' rows are untouched
+     * (registered shards are preserved by the reconcile asymmetry).
+     */
+    _armAutoPush(cfg: InsightAutoPushConfig): void;
+    /**
+     * Await any pending auto-push flush. Resolves immediately when
+     * `freshness.autoPush` is off or nothing is pending.
+     */
+    whenSettled(): Promise<void>;
+    /** An output collection of the read-model vault (keyed by model `name`). */
+    collection<S extends Record<string, unknown> = Record<string, unknown>>(model: string): Collection<S>;
+    /**
+     * Explicit refresh: for each model, read every eligible shard's
+     * `source`, posture-check, and write — rollup: one summary row per
+     * shard (id = partitionKey); mirror: one row per source record
+     * (id = `${shard}:${idOf(row)}`). Every row is stamped with `_shard`
+     * + `_sourceVersion` (mirror rows additionally `_sourceId`).
+     *
+     * Reconciliation (spec § 4): rows whose source record is gone, and
+     * all rows of a shard that LEFT the group, are deleted (`retracted`).
+     * Rows of a merely-unreachable shard are PRESERVED — offline is not
+     * departure; those shards land in `skippedVaults` instead.
+     */
+    refresh(options?: {
+        minVersion?: number;
+        concurrency?: number;
+        only?: readonly string[];
+        failFast?: boolean;
+    }): Promise<ReadModelRefreshResult>;
+    /**
+     * Delete stale rows: id not in `expected` AND the row's shard is
+     * healthy this refresh (source record deleted), no longer in the
+     * group registry (shard departed), or outside the audience predicate
+     * (scope narrowed — out-of-scope data never lingers, spec § 5).
+     * Unreachable-but-registered in-scope shards are preserved.
+     */
+    private reconcile;
+}
+
 /**
  * @klum-db/lobby dock — the foreign-format contract (unit-driver family).
  *
@@ -669,6 +942,50 @@ declare class Lobby {
      * the full tier (keyring, CEK, provenance, custody).
      */
     graduate(docked: DockedUnit, opts: GraduateOptions): Promise<GraduationReport>;
+    /**
+     * Resolve a portal share link (raw URL/path or a parsed `ShareLink`)
+     * against the fleet registry: `vaultHandle → registry row` plus a
+     * console-route descriptor the firm app turns into its own URL.
+     * Unknown/foreign handles fail closed with `ShareLinkResolutionError`.
+     * Delegates to `resolveShareLinkAgainstRegistry` in `portal/share-link.ts`.
+     */
+    resolveShareLink(link: string | URL | ShareLink, opts: {
+        readonly registry: Collection<VaultRegistryRow>;
+    }): Promise<ResolvedShareLink>;
+    /**
+     * Mint a portal share link for a fleet client (`client` partition key +
+     * `group`), delegating the link grammar to `@noy-db/hub/share-link`.
+     * Fails closed when the client is unknown or has no portal handle.
+     * Delegates to `buildShareLinkForClient` in `portal/share-link.ts`.
+     */
+    buildShareLink(parts: BuildShareLinkForClientOptions, opts: {
+        readonly registry: Collection<VaultRegistryRow>;
+    }): Promise<string>;
+    /**
+     * Provision (or re-invite, `mode: 'rebind'`) a client portal vault in
+     * one audited operation: ensure the shard, assign the portal handle
+     * (#43's link target), apply firm grants, issue the magic-link invite,
+     * stamp the audit trail on the fleet registry row.
+     * Needs `@noy-db/on-magic-link` (optional peer) and a session created
+     * with `teamStrategy: withTeam()`.
+     * Delegates to `provisionPortal` in `portal/provision.ts`.
+     */
+    provisionPortal<T>(group: VaultGroup<T>, opts: ProvisionPortalOptions): Promise<ProvisionPortalResult>;
+    /**
+     * Revoke an outstanding portal invite and stamp `revokedAt` on the
+     * fleet audit trail. Idempotent; fails closed on an unknown tokenId.
+     * Delegates to `revokePortalInvite` in `portal/provision.ts`.
+     */
+    revokePortalInvite<T>(group: VaultGroup<T>, opts: RevokePortalInviteOptions): Promise<VaultRegistryRow>;
+    /**
+     * Open a maintained federated read-model over `group` (#44 S1): rollup
+     * models reduce each shard's `source` into one summary row per shard in
+     * the read-model vault — deterministic ids, `_shard`/`_sourceVersion`
+     * provenance, fail-closed `posture.surface` allowlist, explicit
+     * `refresh()`. Spec: docs/federated-read-model.md.
+     * Delegates to `openReadModel` in `federation/read-model.ts`.
+     */
+    openReadModel<T>(group: VaultGroup<T>, opts: OpenReadModelOptions): Promise<ReadModel<T>>;
     /**
      * Export a scoped partition from `vaultName` bounded to the given surface.
      * Delegates to `exportSurface` in `interchange/surface.ts`.
@@ -704,4 +1021,4 @@ declare class Lobby {
 }
 declare function createLobby(noydb: Noydb): Lobby;
 
-export { type CompartmentManifest, type CompartmentMeta, type CrossVaultClosurePlan, CrossVaultDanglingRefError, type CrossVaultPreview, type CrossVaultRef, type CrossVaultSeed, DockedUnit, type ExportMultiVaultXlsxOptions, type ExtractCrossVaultOptions, type ExtractCrossVaultResult, type GraduateOptions, type GraduationReport, type GroupMeterReport, type GroupShardMetrics, InMemoryUnitDriver, Lobby, MergeCompartmentOptions, MergeReport, type MigrateThenMergeOptions, type MigrateThenMergeReport, type MigrationStep, MigrationTransformRequiredError, MinVersionError, type MultiBundleManifest, type MultiVaultCompartmentInput, NOYDB_MULTI_BUNDLE_MAGIC, NOYDB_MULTI_BUNDLE_PREFIX_BYTES, NOYDB_MULTI_BUNDLE_VERSION, SkippedVault, StateManagementVault, SurfaceCadenceScheduler, SurfaceConflictPolicy, type SurfaceDefinition, SurfaceDirection, SurfaceNotFoundError, SurfaceRow, SurfaceStateError, type UnitDriver, UnitGraduationError, VaultGroup, VaultGroupOptions, VaultTemplate, agreeSurface, applySurface, createLobby, decodeMultiBundle, describeCrossVaultExtraction, encodeMultiBundle, exportSurface, extractCrossVaultPartition, groupInspector, isSurfaceDue, listDueSurfaces, markSynced, meterGroup, migrateThenMerge, proposeSurface, readMultiVaultBundleCompartment, readNoydbBundleManifest, walkCrossVaultClosure, writeMultiVaultBundle };
+export { type BuildShareLinkForClientOptions, type CompartmentManifest, type CompartmentMeta, type CrossVaultClosurePlan, CrossVaultDanglingRefError, CrossVaultDerivationContext, type CrossVaultPreview, type CrossVaultRef, type CrossVaultSeed, DockedUnit, type ExportMultiVaultXlsxOptions, type ExtractCrossVaultOptions, type ExtractCrossVaultResult, type GraduateOptions, type GraduationReport, type GroupMeterReport, type GroupShardMetrics, InMemoryUnitDriver, InsightAutoPushConfig, Lobby, MergeCompartmentOptions, MergeReport, type MigrateThenMergeOptions, type MigrateThenMergeReport, type MigrationStep, MigrationTransformRequiredError, MinVersionError, type MirrorModelSpec, type MultiBundleManifest, type MultiVaultCompartmentInput, NOYDB_MULTI_BUNDLE_MAGIC, NOYDB_MULTI_BUNDLE_PREFIX_BYTES, NOYDB_MULTI_BUNDLE_VERSION, type OpenReadModelOptions, type PortalFirmGrant, PostureViolationError, type ProvisionPortalOptions, type ProvisionPortalResult, ReadModel, type ReadModelPosture, type ReadModelRefreshResult, type ReadModelSpec, type ResolvedShareLink, type RevokePortalInviteOptions, type RollupModelSpec, ShareLinkResolutionError, type ShareLinkResolutionErrorCode, SkippedVault, StateManagementVault, SurfaceCadenceScheduler, SurfaceConflictPolicy, type SurfaceDefinition, SurfaceDirection, SurfaceNotFoundError, SurfaceRow, SurfaceStateError, type UnitDriver, UnitGraduationError, VaultGroup, VaultGroupOptions, VaultRegistryRow, VaultTemplate, agreeSurface, applySurface, createLobby, decodeMultiBundle, describeCrossVaultExtraction, encodeMultiBundle, exportSurface, extractCrossVaultPartition, groupInspector, isSurfaceDue, listDueSurfaces, markSynced, meterGroup, migrateThenMerge, proposeSurface, readMultiVaultBundleCompartment, readNoydbBundleManifest, walkCrossVaultClosure, writeMultiVaultBundle };