@mdbase-dev/sdk 0.0.0-stage → 0.1.0-beta.153

package/dist/application/declaration.d.ts

@@ -0,0 +1,51 @@
+export type ApplicationJson = null | boolean | number | string | readonly ApplicationJson[] | {
+    readonly [key: string]: ApplicationJson;
+};
+export interface ApplicationStorageDeclaration {
+    readonly joinDatabaseName?: string;
+    readonly setupDatabaseName?: string;
+    /** Use a stable opaque ID (e.g. a vault ID, not a path or name). Comparison
+     * is exact: case, whitespace and Unicode form are significant. A value equal
+     * to the application id uses the default storage path. Changing it requires
+     * fresh pairing and grants. */
+    readonly applicationNamespace?: string;
+}
+/** App data only: never trust roots, runtime loader, Worker/SQL callbacks, keys,
+ * bearer, or authority ports. Existing registered application ID stays exact;
+ * logical declaration identity is not an inferred CP registration receipt. */
+export interface MdbaseApplicationDeclaration {
+    readonly id: string;
+    readonly name: string;
+    readonly origin: string;
+    readonly environment: "lab" | "staging" | "production" | "local";
+    /** Installation kind sent at pairing; the origin must be declared under the
+     * manifest's `installation_origins.<environment>.<kind>`. Default: "mobile"
+     * for `capacitor://` origins, else "app-runtime". Android Capacitor apps
+     * served from https set "mobile" explicitly. */
+    readonly installationKind?: "app-runtime" | "mobile";
+    /** Complete canonical manifest data; runtime validation uses the public
+     * Connect parser. Accepts canonical typed builders without index-signature casts. */
+    readonly manifest: unknown;
+    readonly storage?: ApplicationStorageDeclaration;
+}
+export interface ApplicationDeclarationSnapshot extends Omit<MdbaseApplicationDeclaration, "storage" | "manifest" | "installationKind"> {
+    readonly installationKind: "app-runtime" | "mobile";
+    readonly manifest: Readonly<Record<string, ApplicationJson>>;
+    readonly storage: Readonly<Required<ApplicationStorageDeclaration>>;
+}
+/** SDK-only registration rebinding. Fresh defaults derive from registered ID;
+ * supplied compatibility DATA stays exact, including supplied default-like values.
+ * When the CP superseded a declared application UUID (changed manifest), every
+ * storage name stays as resolved for the DECLARED id, so local data never moves. */
+export declare function rebindApplicationDeclaration(original: Readonly<ApplicationDeclarationSnapshot>, registered: {
+    readonly id: string;
+    readonly name: string;
+    readonly supersededDeclaredId?: string;
+}): Readonly<ApplicationDeclarationSnapshot>;
+/** Bounds/immutable JSON custody only. Manifest schema, permission/version intent
+ * and registration remain the ONE canonical shared compiler/CP implementation. */
+/** Validator input for the frozen snapshot manifest. The snapshot keeps its
+ * null-prototype JSON objects; schema validators (AJV deep equality for
+ * uniqueItems/const) need ordinary objects, so they get a plain JSON copy. */
+export declare function plainApplicationManifest(declaration: Readonly<ApplicationDeclarationSnapshot>): unknown;
+export declare function applicationDeclaration(input: MdbaseApplicationDeclaration): Readonly<ApplicationDeclarationSnapshot>;

package/dist/application/declaration.js

@@ -0,0 +1,100 @@
+import { storageNamespaceDigest } from "./storage-scope.js";
+import { appOriginPlatform } from "../app-host/app-origin.js";
+import { mdbaseError } from "../errors.js";
+import { applicationEnvironmentAllowed, applicationLoopbackAllowed, localApplicationEnvironment, localApplicationOrigin } from "./local-build.js";
+const storageOverrides = new WeakMap();
+/** SDK-only registration rebinding. Fresh defaults derive from registered ID;
+ * supplied compatibility DATA stays exact, including supplied default-like values.
+ * When the CP superseded a declared application UUID (changed manifest), every
+ * storage name stays as resolved for the DECLARED id, so local data never moves. */
+export function rebindApplicationDeclaration(original, registered) {
+    const overrides = storageOverrides.get(original);
+    if (!overrides || !/^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/.test(registered.id) || registered.id === "00000000-0000-0000-0000-000000000000")
+        fail();
+    if (registered.supersededDeclaredId !== undefined && registered.supersededDeclaredId !== original.id)
+        fail();
+    return applicationDeclaration({ ...original, id: registered.id, name: registered.name, storage: registered.supersededDeclaredId === undefined ? overrides : { ...original.storage } });
+}
+function fail() { throw mdbaseError("invalid_request", "invalid application declaration", "application_declaration"); }
+function json(value, seen = new Set(), depth = 0, budget = { nodes: 0, chars: 0 }) {
+    if (++budget.nodes > 524288 || depth > 64)
+        fail();
+    if (typeof value === "string") {
+        budget.chars += value.length;
+        if (budget.chars > 524288)
+            fail();
+        return value;
+    }
+    if (value === null || typeof value === "boolean")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            fail();
+        return value;
+    }
+    if (typeof value !== "object" || seen.has(value) || Object.getOwnPropertySymbols(value).length)
+        fail();
+    seen.add(value);
+    try {
+        if (Array.isArray(value)) {
+            if (value.length > 524288 || Object.keys(value).length !== value.length)
+                fail();
+            return Object.freeze(Array.from({ length: value.length }, (_, i) => { const d = Object.getOwnPropertyDescriptor(value, String(i)); if (!d || !("value" in d))
+                fail(); return json(d.value, seen, depth + 1, budget); }));
+        }
+        if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)
+            fail();
+        const copy = Object.create(null);
+        for (const key of Object.keys(value)) {
+            budget.chars += key.length;
+            const d = Object.getOwnPropertyDescriptor(value, key);
+            if (budget.chars > 524288 || !d || !("value" in d))
+                fail();
+            copy[key] = json(d.value, seen, depth + 1, budget);
+        }
+        return Object.freeze(copy);
+    }
+    finally {
+        seen.delete(value);
+    }
+}
+/** Bounds/immutable JSON custody only. Manifest schema, permission/version intent
+ * and registration remain the ONE canonical shared compiler/CP implementation. */
+/** Validator input for the frozen snapshot manifest. The snapshot keeps its
+ * null-prototype JSON objects; schema validators (AJV deep equality for
+ * uniqueItems/const) need ordinary objects, so they get a plain JSON copy. */
+export function plainApplicationManifest(declaration) {
+    return JSON.parse(JSON.stringify(declaration.manifest));
+}
+export function applicationDeclaration(input) {
+    const data = json(input);
+    if (!data || Array.isArray(data) || Object.keys(data).some(key => !["id", "name", "origin", "environment", "manifest", "storage", "installationKind"].includes(key)))
+        fail();
+    const { id, name, origin, environment, manifest } = data;
+    if (typeof id !== "string" || !id || id.length > 256 || !/^[a-z0-9][a-z0-9._-]*$/.test(id) || id === "00000000-0000-0000-0000-000000000000"
+        || typeof name !== "string" || !name.trim() || new TextEncoder().encode(name).length > 100 || /[\u0000-\u001f\u007f]/.test(name)
+        || typeof origin !== "string" || typeof environment !== "string" || !applicationEnvironmentAllowed(environment) || !manifest || Array.isArray(manifest) || typeof manifest !== "object")
+        fail();
+    if (localApplicationEnvironment(environment) && !localApplicationOrigin(origin))
+        fail();
+    const platform = appOriginPlatform(origin, applicationLoopbackAllowed(environment), manifest.platform === "native" ? "native" : undefined);
+    const kind = data.installationKind ?? (platform === "mobile" ? "mobile" : "app-runtime");
+    if (platform === null || (kind !== "app-runtime" && kind !== "mobile") || (platform === "mobile" && kind !== "mobile") || ((platform === "extension" || platform === "native") && kind !== "app-runtime"))
+        fail();
+    const override = data.storage;
+    if (override !== undefined && (!override || Array.isArray(override) || typeof override !== "object" || Object.keys(override).some(key => !["joinDatabaseName", "setupDatabaseName", "applicationNamespace"].includes(key))))
+        fail();
+    const fields = override;
+    const namespace = fields?.applicationNamespace ?? id;
+    const databaseOwner = typeof namespace === "string" && namespace !== id ? `namespace.${storageNamespaceDigest(JSON.stringify([id, namespace]))}` : id;
+    const storage = { joinDatabaseName: fields?.joinDatabaseName ?? `mdbase.${databaseOwner}.native-collection-join.v1`, setupDatabaseName: fields?.setupDatabaseName ?? `mdbase.${databaseOwner}.native-model-setup.v1`, applicationNamespace: namespace };
+    for (const value of Object.values(storage))
+        if (typeof value !== "string" || !value || value.length > 256 || /[\u0000-\u001f\u007f]/.test(value))
+            fail();
+    if (storage.joinDatabaseName === storage.setupDatabaseName)
+        fail();
+    const resolved = Object.freeze({ id, name, origin, environment: environment, installationKind: kind, manifest: manifest, storage: Object.freeze(storage) });
+    storageOverrides.set(resolved, Object.freeze({ ...fields }));
+    return resolved;
+}
+//# sourceMappingURL=declaration.js.map

package/dist/application/declaration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"declaration.js","sourceRoot":"","sources":["../../src/application/declaration.ts"],"names":[],"mappings":"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"}

package/dist/application/entry.d.ts

@@ -0,0 +1,343 @@
+import { type MdbaseApplicationDeclaration } from "./declaration.js";
+import { type ApplicationCollectionSelectionSnapshot } from "./collection-selection.js";
+import { type MdbaseAccessRequest, type MdbaseAccessRequestOptions, type MdbaseAccessResult } from "./file-access.js";
+import type { MdbaseClient } from "../client.js";
+import type { FilesApi } from "../files.js";
+import type { MdbasePeopleClient } from "../people.js";
+import type { TimersApi } from "../timers.js";
+import type { AppWebSignInSnapshot } from "../app-host/web-sign-in-session.js";
+import { type AppReplicaScope } from "../app-host/owner.js";
+import { type AppStoragePolicy } from "../app-host/status.js";
+import { type MdbaseApplicationSetup } from "./setup.js";
+import { type MdbasePhase } from "./phase.js";
+import { type StatusSummary } from "../status.js";
+import type { WriteLedgerSnapshot } from "../write-ledger.js";
+import type { AppCollectionReadinessFenceDetail } from "../app-host/collection-readiness.js";
+export type MdbaseApplicationFacet = "capabilities" | "contracts" | "configuration" | "files" | "people" | "notifications";
+export interface MdbaseApplicationProblem {
+    readonly code: string;
+    readonly detail?: AppCollectionReadinessFenceDetail | "scope_aborted" | "scope_closed" | "observer_not_current" | "connection_not_current" | "collection_mismatch" | "currentness_check_failed" | "native_witness_collection_mismatch" | "native_witness_generation_mismatch" | "caller_aborted" | `${MdbaseApplicationFacet}_facet`;
+}
+/** A declared type the app cannot use: its definition has an error-level issue.
+ * Listed only with `readiness: {typeIssues: "degrade"}`. Pass an entry to
+ * `describeError` for the copy; show the rest of the collection as usual. */
+export interface MdbaseUnavailableType {
+    readonly name: string;
+    readonly path: string;
+    readonly contract: {
+        readonly id: string;
+        readonly version: string;
+    };
+    readonly problem: MdbaseApplicationProblem;
+}
+export interface MdbaseApplicationAssessment {
+    readonly status: "ready" | "setup_required" | "incompatible";
+    readonly problem: MdbaseApplicationProblem | null;
+    /** Present only when types degrade and at least one declared type is unusable. */
+    readonly unavailableTypes?: readonly MdbaseUnavailableType[];
+}
+export interface MdbaseApplicationFacetSnapshot {
+    readonly checking: boolean;
+    /** Null while checking/unsupported/read-failed; never invented READY. */
+    readonly assessment: MdbaseApplicationAssessment | null;
+    readonly problem: MdbaseApplicationProblem | null;
+}
+export interface MdbaseApplicationReadinessSnapshot extends MdbaseApplicationFacetSnapshot {
+    readonly facets: Readonly<Record<MdbaseApplicationFacet, MdbaseApplicationFacetSnapshot>>;
+}
+export interface MdbaseApplicationSnapshot extends AppWebSignInSnapshot {
+    readonly readiness: MdbaseApplicationReadinessSnapshot;
+    /** Requested (URL/user/memory) versus usable (actually open) collection. */
+    readonly selection: ApplicationCollectionSelectionSnapshot;
+    /** R1: the one derived state for UI. Switch on `phase.kind`; never hand-roll
+     * a ready check from `status`/`readiness`. Always set by the SDK entry. */
+    readonly phase?: MdbasePhase;
+    /** Sync of the open collection (null until it is ready). */
+    readonly sync?: StatusSummary | null;
+    /** R2: unconfirmed and refused writes of the open collection, and the save
+     * state to show (null until it is ready). Survives a reload. */
+    readonly writes?: WriteLedgerSnapshot | null;
+    /** On-device storage policy for this origin, read by the SDK (null where the
+     * SDK cannot tell). `persistent` is the browser's answer, never a durability
+     * claim: only a log-confirmed receipt counts as saved. */
+    readonly storage?: AppStoragePolicy | null;
+    /** Pending replica edits on nonpersistent storage: set after 30 seconds
+     * continuously pending, or immediately while disconnected. Normal online
+     * edits do not flash a warning. Null at zero pending or with persistence. */
+    readonly saveWarning?: "storage_may_be_evicted" | null;
+    /** Connect pages for this account (SDK-4). Null where the SDK cannot run. */
+    readonly links?: MdbaseLinks | null;
+}
+/** SDK-4: Connect pages an app links to rather than building its own. */
+export interface MdbaseLinks {
+    /** The account page: profile, collections, sign-in. */
+    readonly account: string;
+    /** Apps with access to the account's collections; revoke access there. */
+    readonly manageAccess: string;
+}
+export interface MdbaseApplicationRequestOptions {
+    readonly signal?: AbortSignal;
+}
+export interface MdbaseCollectionDeleteOptions extends MdbaseApplicationRequestOptions {
+    readonly confirmName: string;
+}
+export interface MdbaseSignOutOptions extends MdbaseApplicationRequestOptions {
+    /** Sign out even though changes on this device have not reached mdbase yet;
+     * they are lost. Without it, signOut rejects with `sign_out_pending_writes`. */
+    readonly discard?: boolean;
+}
+/** Sign-in outside a popup: native shells (Capacitor `Browser.open`) and
+ * browser extensions (`chrome.tabs.create`). The SDK still binds the URL to the
+ * environment's Connect origin; `open` only displays it. */
+export interface MdbaseSignInOpener {
+    open(url: string): void | Promise<void>;
+    /** Optional dismissal after sign-in finishes or is cancelled. */
+    close?(): void | Promise<void>;
+    /** Appended as `return_url`. Must exactly equal one of the manifest's
+     * `redirect_uris`: an https URL on the homepage origin, or a native app's
+     * private-use scheme derived from the manifest ID (RFC 8252), e.g.
+     * `dev.example.app://auth/mdbase/callback` for ID `dev.example.app`. */
+    readonly returnUrl?: string;
+}
+export interface MdbaseConnectOptions {
+    readonly signIn?: MdbaseSignInOpener;
+    /** Drive `setForeground` from `document.visibilityState`, and sync at once
+     * when the page regains focus or the network comes back. A hidden page only
+     * finishes sending pending writes (for at most two minutes). Default true;
+     * false leaves `setForeground` to the app. */
+    readonly followVisibility?: boolean;
+    /** Readiness policy. `typeIssues: "degrade"` keeps the collection ready when
+     * one of the app's own types has an error-level definition issue, and lists
+     * it in `readiness.assessment.unavailableTypes`; the app must then treat
+     * that type as unavailable. Default "block". Issues on definitions the app
+     * does not declare never affect readiness. */
+    readonly readiness?: {
+        readonly typeIssues?: "block" | "degrade";
+    };
+    /** SDK-10: list this browser's Private collections (kept on the person's
+     * computers) in `collections` and open them by the same selection. Default
+     * true; false for an app that lists them itself through the app-grant entry. */
+    readonly privateCollections?: boolean;
+}
+export interface MdbaseApplicationConnection {
+    readonly id: string;
+    readonly displayName: string;
+    readonly scope: Readonly<AppReplicaScope>;
+    readonly generation: string;
+    /** Actual public borrowed UI client, not a legacy facade or second engine. */
+    readonly records: MdbaseClient;
+    /** SAME records.files. Available accessors do not widen original authority. */
+    readonly files: FilesApi;
+    readonly people: MdbasePeopleClient;
+    readonly timers?: TimersApi;
+    isCurrent(): boolean;
+}
+export interface MdbaseApplication {
+    getSnapshot(): MdbaseApplicationSnapshot;
+    subscribe(listener: () => void): () => void;
+    start(options?: MdbaseApplicationRequestOptions): Promise<MdbaseApplicationSnapshot>;
+    /** Call from the user gesture (reserves the Connect popup synchronously):
+     * sign in, or approve the requested collection. Same as approve(). */
+    authorize(options?: MdbaseApplicationRequestOptions): Promise<MdbaseApplicationSnapshot>;
+    select(collectionId: string, options?: MdbaseApplicationRequestOptions): Promise<MdbaseApplicationSnapshot>;
+    /** Call from the user gesture: approve one named collection (default: the requested one; none: choose in Connect). */
+    approve(collectionId?: string | null, options?: MdbaseApplicationRequestOptions): Promise<MdbaseApplicationSnapshot>;
+    /** Call from the user gesture the first time the app needs an optional file
+     * action (for example adding an image). Resolves `granted` at once when it
+     * is already allowed; otherwise opens Connect for the open collection with
+     * your one-line reason. No reload: the connection and app state stay. An
+     * action the manifest does not declare rejects with `access_undeclared`.
+     * File writes the person has not allowed reject with `access_required`. */
+    requestAccess(request: MdbaseAccessRequest, options: MdbaseAccessRequestOptions): Promise<MdbaseAccessResult>;
+    /** Call from the user gesture: re-approve the open/requested collection. */
+    reauthorize(options?: MdbaseApplicationRequestOptions): Promise<MdbaseApplicationSnapshot>;
+    /** Re-read the approved collection list now (for example when a switcher
+     * opens). Focus and visibility already refresh it. */
+    refreshCollectionList?(options?: MdbaseApplicationRequestOptions): Promise<MdbaseApplicationSnapshot>;
+    /** Close the current collection and return to the chooser; Back restores it. */
+    chooseAnother(options?: MdbaseApplicationRequestOptions): Promise<MdbaseApplicationSnapshot>;
+    /** Refresh current aggregate evidence; checking/read errors never become READY. */
+    assess(options?: MdbaseApplicationRequestOptions): Promise<MdbaseApplicationReadinessSnapshot>;
+    /** Explicitly configure the current scope from its canonical declaration.
+     * No caller operations/plan/SQL; original recovery and consent stay SDK-owned. */
+    configure(options?: MdbaseApplicationRequestOptions): Promise<MdbaseApplicationSnapshot>;
+    /** Reviewable setup of the open collection: `plan` for one review screen,
+     * then `apply` that plan. `configure` is plan+apply with nothing to review. */
+    readonly setup: MdbaseApplicationSetup;
+    clearSelection(options?: MdbaseApplicationRequestOptions): Promise<MdbaseApplicationSnapshot>;
+    /** Local presentation/selection only; never revoke consent or delete records. */
+    forget(collectionId: string, options?: MdbaseApplicationRequestOptions): Promise<MdbaseApplicationSnapshot>;
+    /** Owner only, from an explicit confirmation: delete a collection for
+     * everyone, on every device and app. `confirmName` is the name the person
+     * typed; it must equal the collection's current name. A refusal rejects
+     * with a `collection_delete_*` code for `describeError` and changes nothing
+     * locally. On success the collection leaves `collections`. */
+    deleteCollection(collectionId: string, options: MdbaseCollectionDeleteOptions): Promise<MdbaseApplicationSnapshot>;
+    setForeground(active: boolean): void;
+    close(): Promise<void>;
+    /** Sign out of mdbase on this device: ends the server session and removes
+     * this browser's sign-in data, keys and cached collections for the account.
+     * Rejects with `sign_out_pending_writes` (a `conflict`) while changes have not
+     * reached mdbase, unless `{discard: true}`. Resolves signed out; Sign in works
+     * again without a reload, and a reload stays signed out. A server sign-out
+     * that could not complete (offline) still signs this device out; it shows
+     * in `signOutResult`. Optional for other implementations of this interface. */
+    signOut?(options?: MdbaseSignOutOptions): Promise<MdbaseApplicationSnapshot>;
+    /** @deprecated Use `createMdbase(...).addCollection(options)` or
+     * `approve(null, options)`: the same unified chooser, without a current hint.
+     * Optional for other implementations of this interface. */
+    addPrivateCollection?(options?: MdbaseApplicationRequestOptions): Promise<MdbaseApplicationSnapshot>;
+}
+/** Structural public consumer port; production uses MdbaseConnect. Explicit
+ * SDK testing fixtures may implement this without private fields or casts. */
+export interface MdbaseApplicationEntry {
+    application(): MdbaseApplication;
+    connection(collectionId: string): MdbaseApplicationConnection | null;
+}
+export declare class MdbaseApplicationUnavailableError extends Error {
+    readonly code = "application_not_yet_available";
+    constructor();
+}
+/** The application entry. New code: `createMdbase(declaration)`, the same
+ * entry with a strict snapshot; `MdbaseConnect` keeps its name for one cut.
+ * Declaration-only public entry. Construction is IO-free; SDK registration,
+ * same-artifact Worker and original profile/SQL start lazily on the first
+ * action. The URL names the requested collection; sign-in approval decides what
+ * opens. No app factories, private authority hooks, replacement actors or
+ * transport-only READY. */
+export declare class MdbaseConnect implements MdbaseApplicationEntry {
+    private readonly app;
+    private readonly declaration;
+    private readonly compiled;
+    private readonly lifetime;
+    private readonly listeners;
+    private readonly nativeListeners;
+    private readonly selection;
+    private readonly memory;
+    private runtime;
+    private initialization;
+    private closing;
+    private closed;
+    private foreground;
+    /** Page lifecycle: bumped on every pagehide; set while the page is hidden. */
+    private incarnation;
+    private hidden;
+    /** This page's tab group (leader or follower), and the current election. */
+    private tabs;
+    private election;
+    private signingOut;
+    private snapshot;
+    private composed;
+    private readonly hint;
+    private readonly forgotten;
+    private handledApproval;
+    private refreshing;
+    private refreshedAt;
+    /** Non-owning UI handle: the original Worker request still owns its lifetime. */
+    private approvalPortal;
+    /** Bumped by state outside base/selection: the slow-opening timer and sync. */
+    private revision;
+    private readonly links;
+    private readonly cpOrigin;
+    private opening;
+    private syncing;
+    /** On-device storage policy for this origin; null where it cannot be read. */
+    private storagePolicy;
+    private pendingSave;
+    private readonly signIn;
+    private readonly typeIssues;
+    /** SDK-10: this tab's Private collections (page-side thin clients, never the Worker). */
+    private readonly privates;
+    private readonly overlaid;
+    constructor(declaration: MdbaseApplicationDeclaration, options?: MdbaseConnectOptions);
+    /** SDK-10: the session's snapshot with this tab's Private collections listed
+     * and, while one is open, as the selected collection. Stable per change. */
+    private withPrivate;
+    private getSnapshot;
+    /** One grace window per continuously pending replica, not per edit or request. */
+    private trackSaveWarning;
+    private clearPendingSave;
+    /** SDK-9: one timer per opening collection; `slow` after SLOW_OPENING_MS. */
+    private trackOpening;
+    /** Follow the open collection's sync status while it is ready. */
+    private trackSync;
+    private nativeAuthorization;
+    private account;
+    /** SDK-3: approving a forgotten collection again shows it again. */
+    private unforgetApproved;
+    /** SDK-2: re-read the approved list when the app is shown or focused again
+     * (an approval in Connect, another app or another device). No polling. */
+    private followFocus;
+    private refreshCollections;
+    /** Request persistence once at app start, then re-read the policy when the
+     * page is shown again. A denial never blocks startup. Where the browser cannot
+     * say — no `navigator.storage`, no document — the policy stays null and the
+     * save warning assumes the conservative non-persistent state. */
+    private followStoragePolicy;
+    private notify;
+    /** Selection starts with the first action: it reads the URL request and
+     * follows Back/forward. Explicit actions still call the session themselves. */
+    private choose;
+    private track;
+    /** SDK-private port over the ONE runtime. Retire-before-switch and the
+     * same-scope fast path live in runtime.select; the popup is reserved here
+     * synchronously, before lazy registration/Worker startup awaits. */
+    private selectionSession;
+    private check;
+    private environment;
+    private initialize;
+    private call;
+    /** Sign-in start is idempotent in the native session; every lifecycle action
+     * that needs the protected request runs it first. */
+    private started;
+    /** Reserve the SDK popup synchronously in the user gesture, before any await. */
+    private reservePortal;
+    private requestAccess;
+    /** Repeating the SAME approval is a window gesture, not another Worker
+     * request (which would close the original portal before reporting busy). */
+    private approve;
+    private authorize;
+    /** UX-011. The Worker session signs out and erases; then this entry drops
+     * that runtime the way the back/forward-cache path does (incarnation, no
+     * initialization), so the next action starts a fresh Worker and a fresh
+     * pairing, and clears its own page storage (session hint, last collection,
+     * forgotten collections). */
+    private signOut;
+    /** Drop the signed-out runtime the way the back/forward-cache path does
+     * (incarnation, no initialization), so the next action starts afresh, and
+     * clear this page's storage (session hint, last and forgotten collections). */
+    private signedOut;
+    /** Another tab signed out of the one shared session: this tab is signed out too. */
+    private observeSignOut;
+    private tabsFor;
+    /** The leader tab went away: start again, as the new leader or a follower of it.
+     * If it went because the session signed out, this tab is signed out too: it
+     * neither leads nor starts a new session (its snapshot may not have arrived). */
+    private readonly leaderLost;
+    /** Every tab signed out, then another tab signed in again: follow that
+     * session as this tab would on load (no second sign-in or approval). */
+    private readonly signedInElsewhere;
+    private setForeground;
+    private followVisibility;
+    /** Back/forward cache: a page parked there is frozen with its Worker, which
+     * would keep holding the collection lease and block the next document of
+     * this app ("busy"). On pagehide, stop the Worker synchronously (a frozen
+     * page cannot finish an async stop); on a persisted pageshow, start a fresh
+     * one so the restored page works again. A non-persisted pagehide (unload)
+     * stops it the same way: the page is going anyway, and the lease is free at
+     * once for the document that replaces it. Browser Window contexts only. */
+    private followPageLifecycle;
+    private readonly pageHidden;
+    private readonly pageShown;
+    /** Fallback when tabs cannot share one Worker: another tab of this app on a
+     * different build (or one still letting go during a leader handover) holds the
+     * sign-in slot. Wait for it to be released (that tab closes, reloads or is
+     * parked in the back/forward cache), then start again by the bfcache-restore
+     * path. A hidden tab waits until it is shown, so it never takes over from a
+     * tab the user is reloading. Only Web Lock waits: no timers, no network. */
+    private awaitingOtherTab;
+    private awaitOtherTab;
+    private close;
+    application(): MdbaseApplication;
+    connection(collectionId: string): MdbaseApplicationConnection | null;
+}