@mdbase-dev/connect 0.1.0-beta.84 → 0.1.0-beta.85

package/README.md

@@ -151,10 +151,19 @@ versioned capabilities in their manifest; they never maintain a parallel array
 of protocol operations. Use `getSnapshot()` and `subscribe()` directly or
 through your framework's external-store integration.
 
-The session distinguishes `authorization_required`, `checking_setup`,
+Before and during startup the session distinguishes `not_started`, `starting`,
+and `start_failed`; the last state carries the original typed problem and a
+later `start()` retries. `destroyed` is terminal. Once started, the session
+distinguishes `authorization_required`, `checking_setup`,
 `setup_review_required`, `ready`, `unavailable`, and `blocked`. Setup
-inspection is read-only. If an update is needed, render the supplied plan and
-apply the exact assessment the user reviewed:
+inspection is read-only.
+While startup owns a provisional connection, synchronous methods return the
+catalogued `session_starting` outcome and cannot mutate selection or grants.
+After `start_failed`, every lifecycle-dependent method returns the exact
+`snapshot.problem` object.
+
+If an update is needed, render the supplied plan and apply the exact assessment
+the user reviewed:
 
 ```ts
 const snapshot = session.getSnapshot();
@@ -178,11 +187,29 @@ changes to the session. The session auto-selects only when exactly one saved
 connection exists. Switching is state-driven and must not reload the page:
 
 ```ts
-session.select(collectionId, { history: "replace" });
-session.clearSelection();
-session.forget(collectionId);
+const selected = session.select(collectionId, { history: "replace" });
+const cleared = session.clearSelection();
+const forgotten = session.forget(collectionId);
 ```
 
+These synchronous methods return lifecycle-aware `ConnectOutcome` values.
+Explicit `forget()` and `forgetAll()` remove the saved grant, all pending
+mutation recovery records for that connection, and coordinate grant-key cleanup
+with other tabs and workers through Web Locks. Browsers without Web Locks retain
+retired and forgotten key material in the configured key store rather than risk
+deleting a key another context is using; applications that require physical key
+removal must clear that store only after closing all application contexts.
+Automatic authorization invalidation keeps pending recovery state so
+reauthorization can resume an outcome-unknown mutation safely.
+Async lifecycle-dependent methods wait for an in-progress `start()` within the
+same request budget and return typed lifecycle, timeout, or cancellation
+outcomes rather than throwing for session state.
+
+If a saved grant belongs to an earlier registered identity for the same
+application declaration, the snapshot is `authorization_required`. Connect
+does not discard or replay that grant's pending mutations and does not open an
+authorization flow automatically; call `authorize("selected")` explicitly.
+
 Selection validates the saved authorization before changing the URL. Explicit
 unavailable IDs remain authoritative so applications can offer exact
 reauthorization or another collection:

package/dist/advanced.d.ts

@@ -6,4 +6,4 @@ export { connectError, connectProblem, operationProblem } from "./errors.js";
 export { connectFailure, connectSuccess } from "./outcomes.js";
 export type { MdbaseApplicationVerificationStore, MdbaseApplicationSessionConnect } from "./application-session.js";
 export { MdbaseSession } from "./session.js";
-export type { MdbaseSessionConnect, MdbaseSessionOptions } from "./session.js";
+export type { MdbaseSessionConnect, MdbaseSessionOptions, MdbaseSessionSnapshot } from "./session.js";

package/dist/application-session.d.ts

@@ -1,8 +1,8 @@
-import { type ApplicationCapabilityId, type JsonObject, type MdbaseAppManifest } from "@mdbase-dev/connect-protocol";
+import { type ApplicationCapabilityId, type ConnectProblem, type JsonObject, type MdbaseAppManifest } from "@mdbase-dev/connect-protocol";
 import { type MdbaseEffectiveCapabilities } from "./capabilities.js";
 import type { MdbaseAuthorizationOutcome, MdbaseAuthorizeOptions, MdbaseConnection } from "./connection.js";
 import type { MdbaseConnectionInfo } from "./connection-types.js";
-import { type ConnectOutcome, type CollectionTypeProblemCode, type AuthorizationProblemCode, type RegistrationProblemCode, type SessionProblemCode } from "./outcomes.js";
+import { type ConnectOutcome, type CollectionTypeProblemCode, type RegistrationProblemCode, type SessionProblemCode } from "./outcomes.js";
 import type { MdbaseApplicationSelection, MdbaseSelectionHistory } from "./selection.js";
 import type { CollectionSetupAssessment, ConfigurationSetupAssessment, ConnectRequestOptions, TypePackAssessment } from "./operation-types.js";
 import { type ResolvedConnectTimeouts } from "./request-budget.js";
@@ -11,6 +11,7 @@ import { type MdbaseSessionConnect, type MdbaseUnavailableReason } from "./sessi
 export interface MdbaseApplicationSessionConnect<Frontmatter extends JsonObject = JsonObject> extends MdbaseSessionConnect<Frontmatter> {
     register(options?: ConnectRequestOptions): Promise<ConnectOutcome<Application, RegistrationProblemCode>>;
     manifest(options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseAppManifest, RegistrationProblemCode>>;
+    connectionApplicationId(collectionId: string): string | null;
 }
 export interface MdbaseApplicationSessionOptions {
     selection: MdbaseApplicationSelection;
@@ -59,7 +60,17 @@ interface ApplicationSessionContext {
     connections: MdbaseConnectionInfo[];
 }
 export type MdbaseApplicationSessionSnapshot = {
-    status: "opening";
+    status: "not_started";
+    connections: MdbaseConnectionInfo[];
+} | {
+    status: "starting";
+    connections: MdbaseConnectionInfo[];
+} | {
+    status: "start_failed";
+    problem: ConnectProblem<SessionProblemCode>;
+    connections: MdbaseConnectionInfo[];
+} | {
+    status: "destroyed";
     connections: MdbaseConnectionInfo[];
 } | {
     status: "unselected";
@@ -107,11 +118,16 @@ export declare class MdbaseApplicationSession<Frontmatter extends JsonObject = J
     private setupTypePackAdoptions;
     private verificationGeneration;
     private lifecycleGeneration;
+    private readonly operationControllers;
     private startOperation;
     constructor(connect: MdbaseApplicationSessionConnect<Frontmatter>, options: MdbaseApplicationSessionOptions, timeouts?: ResolvedConnectTimeouts);
     start(options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseApplicationSessionSnapshot, SessionProblemCode>>;
+    private waitForStart;
+    private abandonStart;
     private beginStart;
     private startWithinBudget;
+    private performStartWithinBudget;
+    private startFailure;
     destroy(): void;
     private cleanupBase;
     getSnapshot(): MdbaseApplicationSessionSnapshot;
@@ -119,27 +135,32 @@ export declare class MdbaseApplicationSession<Frontmatter extends JsonObject = J
     connection(): MdbaseConnection<Frontmatter> | null;
     select(collectionId: string, options?: {
         history?: MdbaseSelectionHistory;
-    }): ConnectOutcome<MdbaseConnection<Frontmatter>, "unknown_collection">;
+    }): ConnectOutcome<MdbaseConnection<Frontmatter>, SessionProblemCode>;
     clearSelection(options?: {
         history?: MdbaseSelectionHistory;
-    }): void;
-    forget(collectionId: string): void;
+    }): ConnectOutcome<void, SessionProblemCode>;
+    forget(collectionId: string): ConnectOutcome<void, SessionProblemCode>;
     authorize(target: "choose" | "selected" | {
         collectionId: string;
     }, options?: Omit<MdbaseAuthorizeOptions, "operations" | "returnTo" | "target">): Promise<ConnectOutcome<MdbaseAuthorizationOutcome<Frontmatter>, SessionProblemCode>>;
-    handleAuthorizationCallback(callbackUrl: string | URL, options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseConnection<Frontmatter>, AuthorizationProblemCode>>;
-    completeAuthorization(callbackUrl?: string | URL, options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseConnection<Frontmatter>, AuthorizationProblemCode>>;
+    handleAuthorizationCallback(callbackUrl: string | URL, options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseConnection<Frontmatter>, SessionProblemCode>>;
+    completeAuthorization(callbackUrl?: string | URL, options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseConnection<Frontmatter>, SessionProblemCode>>;
     ensureCapabilities(capabilities: ApplicationCapabilityId[], options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseAuthorizationOutcome<Frontmatter> | {
         kind: "unchanged";
         connection: MdbaseConnection<Frontmatter>;
     }, SessionProblemCode>>;
-    applyCollectionSetup(options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseApplicationSessionSnapshot, CollectionTypeProblemCode | "collection_not_ready">>;
+    applyCollectionSetup(options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseApplicationSessionSnapshot, CollectionTypeProblemCode | SessionProblemCode>>;
+    private applyCollectionSetupStarted;
     private refresh;
     private verifySetup;
     private collectionSetupInput;
     private context;
     private publish;
-    private requireBase;
+    private lifecycleBase;
+    private withLifecycleBase;
+    private beginLifecycleOperation;
+    private lifecycleCurrent;
+    private destroyedOutcome;
     private requireManifest;
     private requireApplication;
 }

package/dist/application-session.js

@@ -1,9 +1,9 @@
 import { capabilityOperations, operationsForApplicationCapabilities } from "@mdbase-dev/connect-protocol";
 /* The versioned protocol package is the sole capability-to-operation compiler. */
 import { effectiveCapabilities } from "./capabilities.js";
-import { connectProblem } from "./errors.js";
+import { MdbaseConnectError, connectProblem } from "./errors.js";
 import { connectFailure, connectSuccess } from "./outcomes.js";
-import { createRequestBudget, requestAbortReason, resolveConnectTimeouts, withRequestBudget } from "./request-budget.js";
+import { createRequestBudget, resolveConnectTimeouts, withRequestBudget } from "./request-budget.js";
 import { defaultCallbackUrl } from "./runtime-utils.js";
 import { MdbaseSession } from "./session.js";
 export class MdbaseMemoryVerificationStore {
@@ -29,7 +29,7 @@ export class MdbaseApplicationSession {
     timeouts;
     listeners = new Set();
     verificationStore;
-    snapshot = { status: "opening", connections: [] };
+    snapshot = { status: "not_started", connections: [] };
     manifest = null;
     application = null;
     base = null;
@@ -38,6 +38,7 @@ export class MdbaseApplicationSession {
     setupTypePackAdoptions = null;
     verificationGeneration = 0;
     lifecycleGeneration = 0;
+    operationControllers = new Set();
     startOperation = null;
     constructor(connect, options, timeouts = resolveConnectTimeouts()) {
         this.connect = connect;
@@ -46,22 +47,47 @@ export class MdbaseApplicationSession {
         this.verificationStore = options.verificationStore ?? defaultVerificationStore();
     }
     start(options) {
+        if (this.snapshot.status === "destroyed") {
+            return Promise.resolve(connectFailure(connectProblem("session_destroyed", "This application session has been destroyed.")));
+        }
         if (this.base && !this.startOperation)
             return Promise.resolve(connectSuccess(this.snapshot));
         const operation = this.startOperation ?? this.beginStart();
+        return this.waitForStart(operation, options, this.timeouts.watchStartMs);
+    }
+    async waitForStart(operation, options, timeoutMs) {
         operation.waiters += 1;
-        return withRequestBudget(options, this.timeouts.watchStartMs, () => operation.promise)
-            .finally(() => {
+        try {
+            return await withRequestBudget(options, timeoutMs, () => operation.promise);
+        }
+        catch (error) {
+            if (error instanceof MdbaseConnectError) {
+                return connectFailure(error.problem);
+            }
+            throw error;
+        }
+        finally {
             operation.waiters -= 1;
             if (operation.waiters === 0 && this.startOperation === operation) {
-                operation.controller.abort();
-                this.startOperation = null;
-                this.lifecycleGeneration += 1;
+                this.abandonStart(operation);
             }
-        });
+        }
+    }
+    abandonStart(operation) {
+        operation.controller.abort();
+        this.startOperation = null;
+        this.lifecycleGeneration += 1;
+        this.verificationGeneration += 1;
+        if (this.base)
+            this.cleanupBase(this.base);
+        this.application = null;
+        this.manifest = null;
+        this.setupAssessment = null;
+        this.setupTypePackAdoptions = null;
+        this.publish({ status: "not_started", connections: this.connect.connections() });
     }
     beginStart() {
-        this.snapshot = { status: "opening", connections: [] };
+        this.publish({ status: "starting", connections: this.connect.connections() });
         const controller = new AbortController();
         const generation = ++this.lifecycleGeneration;
         const operation = {
@@ -79,15 +105,36 @@ export class MdbaseApplicationSession {
         return operation;
     }
     async startWithinBudget(options, generation) {
+        try {
+            return await this.performStartWithinBudget(options, generation);
+        }
+        catch (error) {
+            if (error instanceof MdbaseConnectError) {
+                return this.startFailure(error.problem, generation);
+            }
+            if (generation === this.lifecycleGeneration) {
+                this.verificationGeneration += 1;
+                if (this.base)
+                    this.cleanupBase(this.base);
+                this.application = null;
+                this.manifest = null;
+                this.setupAssessment = null;
+                this.setupTypePackAdoptions = null;
+                this.publish({ status: "not_started", connections: this.connect.connections() });
+            }
+            throw error;
+        }
+    }
+    async performStartWithinBudget(options, generation) {
         const registration = await this.connect.register(options);
         if (!registration.ok)
-            return registration;
+            return this.startFailure(registration.problem, generation);
         const manifest = await this.connect.manifest(options);
         if (!manifest.ok)
-            return manifest;
+            return this.startFailure(manifest.problem, generation);
         const capabilities = manifest.value.requirements?.capabilities;
         if (!capabilities) {
-            return connectFailure(connectProblem("invalid_application_manifest", "Application sessions require a versioned semantic capability contract.", {
+            return this.startFailure(connectProblem("invalid_application_manifest", "Application sessions require a versioned semantic capability contract.", {
                 details: {
                     issues: [{
                             path: "/requirements/capabilities",
@@ -96,10 +143,10 @@ export class MdbaseApplicationSession {
                             params: {}
                         }]
                 }
-            }));
+            }), generation);
         }
         if (generation !== this.lifecycleGeneration || options.signal?.aborted) {
-            throw requestAbortReason(options.signal ?? new AbortController().signal);
+            return connectFailure(connectProblem("operation_cancelled", "Application session startup was cancelled.", { operationOutcome: "not_sent" }));
         }
         this.application = registration.value;
         this.manifest = manifest.value;
@@ -113,10 +160,11 @@ export class MdbaseApplicationSession {
             const started = await base.start(options);
             if (!started.ok) {
                 this.cleanupBase(base);
-                return started;
+                return this.startFailure(started.problem, generation);
             }
             if (generation !== this.lifecycleGeneration || options.signal?.aborted) {
-                throw requestAbortReason(options.signal ?? new AbortController().signal);
+                this.cleanupBase(base);
+                return connectFailure(connectProblem("operation_cancelled", "Application session startup was cancelled.", { operationOutcome: "not_sent" }));
             }
             this.stopBase = base.subscribe(() => {
                 if (this.base === base)
@@ -124,7 +172,8 @@ export class MdbaseApplicationSession {
             });
             await this.refresh(true, options);
             if (generation !== this.lifecycleGeneration || options.signal?.aborted) {
-                throw requestAbortReason(options.signal ?? new AbortController().signal);
+                this.cleanupBase(base);
+                return connectFailure(connectProblem("operation_cancelled", "Application session startup was cancelled.", { operationOutcome: "not_sent" }));
             }
             return connectSuccess(this.snapshot);
         }
@@ -133,18 +182,33 @@ export class MdbaseApplicationSession {
             throw error;
         }
     }
+    startFailure(problem, generation) {
+        if (generation === this.lifecycleGeneration) {
+            this.publish({
+                status: "start_failed",
+                problem,
+                connections: this.connect.connections()
+            });
+        }
+        return connectFailure(problem);
+    }
     destroy() {
+        if (this.snapshot.status === "destroyed")
+            return;
         this.lifecycleGeneration += 1;
         this.verificationGeneration += 1;
         this.startOperation?.controller.abort();
         this.startOperation = null;
+        for (const controller of this.operationControllers)
+            controller.abort();
+        this.operationControllers.clear();
         if (this.base)
             this.cleanupBase(this.base);
         this.application = null;
         this.manifest = null;
         this.setupAssessment = null;
         this.setupTypePackAdoptions = null;
-        this.snapshot = { status: "opening", connections: [] };
+        this.publish({ status: "destroyed", connections: [] });
         this.listeners.clear();
     }
     cleanupBase(base) {
@@ -167,47 +231,100 @@ export class MdbaseApplicationSession {
         return current?.status === "ready" ? current.connection : null;
     }
     select(collectionId, options = {}) {
-        return this.requireBase().select(collectionId, options);
+        const base = this.lifecycleBase();
+        return base.ok ? base.value.select(collectionId, options) : base;
     }
     clearSelection(options = {}) {
-        this.requireBase().clearSelection(options);
+        const base = this.lifecycleBase();
+        if (!base.ok)
+            return base;
+        base.value.clearSelection(options);
+        return connectSuccess(undefined);
     }
     forget(collectionId) {
-        this.requireBase().forget(collectionId);
+        const base = this.lifecycleBase();
+        if (!base.ok)
+            return base;
+        base.value.forget(collectionId);
+        return connectSuccess(undefined);
     }
     authorize(target, options = {}) {
-        return this.requireBase().authorize(target, options);
+        return this.withLifecycleBase(options, async (base, requestOptions, generation) => {
+            const outcome = await base.authorize(target, { ...options, ...requestOptions });
+            if (outcome.ok && outcome.value.kind === "connected" && this.lifecycleCurrent(generation)) {
+                await this.refresh(true, requestOptions);
+            }
+            return outcome;
+        });
     }
     handleAuthorizationCallback(callbackUrl, options) {
-        return this.requireBase().handleAuthorizationCallback(String(callbackUrl), options);
+        const exactUrl = String(callbackUrl);
+        const joinsStartupCallback = this.startOperation !== null
+            && this.options.selection.authorizationCallback() === exactUrl;
+        return this.withLifecycleBase(options, async (base, requestOptions, generation) => {
+            if (joinsStartupCallback) {
+                const current = base.getSnapshot();
+                if (current.status === "ready")
+                    return connectSuccess(current.connection);
+                return connectFailure(connectProblem("collection_not_ready", "Authorization did not produce a ready collection."));
+            }
+            const outcome = await base.handleAuthorizationCallback(exactUrl, requestOptions);
+            if (outcome.ok && this.lifecycleCurrent(generation))
+                await this.refresh(true, requestOptions);
+            return outcome;
+        });
     }
     completeAuthorization(callbackUrl, options) {
-        return this.requireBase().handleAuthorizationCallback(callbackUrl === undefined ? defaultCallbackUrl() : String(callbackUrl), options);
+        const exactUrl = callbackUrl === undefined ? defaultCallbackUrl() : String(callbackUrl);
+        const joinsStartupCallback = this.startOperation !== null
+            && this.options.selection.authorizationCallback() === exactUrl;
+        return this.withLifecycleBase(options, async (base, requestOptions, generation) => {
+            if (joinsStartupCallback) {
+                const current = base.getSnapshot();
+                if (current.status === "ready")
+                    return connectSuccess(current.connection);
+                return connectFailure(connectProblem("collection_not_ready", "Authorization did not produce a ready collection."));
+            }
+            const outcome = await base.handleAuthorizationCallback(exactUrl, requestOptions);
+            if (outcome.ok && this.lifecycleCurrent(generation))
+                await this.refresh(true, requestOptions);
+            return outcome;
+        });
     }
     ensureCapabilities(capabilities, options) {
-        const manifestRequirements = this.requireManifest().requirements?.capabilities;
-        const declared = new Set([
-            ...(manifestRequirements?.required ?? []),
-            ...(manifestRequirements?.optional ?? [])
-        ]);
-        if (capabilities.some((capability) => !declared.has(capability))) {
-            return Promise.resolve(connectFailure(connectProblem("invalid_application_manifest", "Applications may only request capabilities declared in their manifest.", {
-                details: {
-                    issues: [{
-                            path: "/requirements/capabilities",
-                            keyword: "undeclaredCapability",
-                            message: "must declare every capability requested by the application",
-                            params: {
-                                requested: capabilities,
-                                declared: [...declared]
-                            }
-                        }]
+        return this.withLifecycleBase(options, (base, requestOptions, generation) => {
+            const manifestRequirements = this.manifest.requirements?.capabilities;
+            const declared = new Set([
+                ...(manifestRequirements?.required ?? []),
+                ...(manifestRequirements?.optional ?? [])
+            ]);
+            if (capabilities.some((capability) => !declared.has(capability))) {
+                return Promise.resolve(connectFailure(connectProblem("invalid_application_manifest", "Applications may only request capabilities declared in their manifest.", {
+                    details: {
+                        issues: [{
+                                path: "/requirements/capabilities",
+                                keyword: "undeclaredCapability",
+                                message: "must declare every capability requested by the application",
+                                params: {
+                                    requested: capabilities,
+                                    declared: [...declared]
+                                }
+                            }]
+                    }
+                })));
+            }
+            return base.ensureOperations(operationsForIds(capabilities), requestOptions).then(async (outcome) => {
+                if (outcome.ok && outcome.value.kind === "connected" && this.lifecycleCurrent(generation)) {
+                    await this.refresh(true, requestOptions);
                 }
-            })));
-        }
-        return this.requireBase().ensureOperations(operationsForIds(capabilities), options);
+                return outcome;
+            });
+        });
+    }
+    applyCollectionSetup(options) {
+        return this.withLifecycleBase(options, (_base, requestOptions, generation) => this.applyCollectionSetupStarted(requestOptions, generation));
     }
-    async applyCollectionSetup(options) {
+    async applyCollectionSetupStarted(options, generation) {
         if (this.snapshot.status !== "setup_review_required" || !this.setupAssessment) {
             return connectFailure(connectProblem("collection_not_ready", "There is no reviewed collection setup to apply."));
         }
@@ -228,20 +345,25 @@ export class MdbaseApplicationSession {
                 .filter((pack) => pack.status === "downgrade")
                 .map((pack) => pack.desired.id)
         };
-        const budget = createRequestBudget(options, this.timeouts.requestMs);
-        const requestOptions = { signal: budget.signal, timeoutMs: null };
-        try {
-            const applied = await connection.applyCollectionSetup(input, requestOptions);
-            if (!applied.ok)
-                return applied;
-            this.setupAssessment = null;
-            this.setupTypePackAdoptions = null;
-            await this.verifySetup(this.context(connection), ++this.verificationGeneration, requestOptions);
-            return connectSuccess(this.snapshot);
+        const applied = await connection.applyCollectionSetup(input, options);
+        if (!this.lifecycleCurrent(generation)) {
+            if (!applied.ok && applied.problem.code === "operation_outcome_unknown") {
+                return connectFailure(applied.problem);
+            }
+            return connectFailure(connectProblem("session_destroyed", lifecycleProblemMessage("session_destroyed")));
         }
-        finally {
-            budget.dispose();
+        if (!applied.ok) {
+            if (applied.problem.code === "application_declaration_mismatch") {
+                this.setupAssessment = null;
+                this.setupTypePackAdoptions = null;
+                this.publish({ status: "authorization_required", ...this.context(connection) });
+            }
+            return applied;
         }
+        this.setupAssessment = null;
+        this.setupTypePackAdoptions = null;
+        await this.verifySetup(this.context(connection), ++this.verificationGeneration, options);
+        return connectSuccess(this.snapshot);
     }
     async refresh(awaitVerification = false, options) {
         if (!this.base || !this.manifest)
@@ -259,7 +381,13 @@ export class MdbaseApplicationSession {
             this.publish(current);
             return;
         }
+        if (current.status !== "ready")
+            return;
         const context = this.context(current.connection);
+        if (this.connect.connectionApplicationId(current.collectionId) !== this.application?.id) {
+            this.publish({ status: "authorization_required", ...context });
+            return;
+        }
         if (!context.capabilities.requiredAvailable
             || !accessRequirementSatisfied(this.manifest, context.info)) {
             this.publish({ status: "authorization_required", ...context });
@@ -294,7 +422,9 @@ export class MdbaseApplicationSession {
         if (generation !== this.verificationGeneration)
             return;
         if (!outcome.ok) {
-            this.publish({ status: "blocked", problem: outcome.problem, ...context });
+            this.publish(outcome.problem.code === "application_declaration_mismatch"
+                ? { status: "authorization_required", ...context }
+                : { status: "blocked", problem: outcome.problem, ...context });
             return;
         }
         if (!outcome.value.applicable) {
@@ -306,7 +436,9 @@ export class MdbaseApplicationSession {
                 if (generation !== this.verificationGeneration)
                     return;
                 if (!outcome.ok) {
-                    this.publish({ status: "blocked", problem: outcome.problem, ...context });
+                    this.publish(outcome.problem.code === "application_declaration_mismatch"
+                        ? { status: "authorization_required", ...context }
+                        : { status: "blocked", problem: outcome.problem, ...context });
                     return;
                 }
                 this.setupTypePackAdoptions = adoptions;
@@ -353,16 +485,91 @@ export class MdbaseApplicationSession {
         };
     }
     publish(snapshot) {
+        if (this.snapshot.status === "destroyed" && snapshot.status !== "destroyed")
+            return;
         if (JSON.stringify(this.snapshot) === JSON.stringify(snapshot))
             return;
         this.snapshot = snapshot;
         for (const listener of this.listeners)
             listener();
     }
-    requireBase() {
-        if (!this.base)
-            throw new Error("Start the application session before using it.");
-        return this.base;
+    lifecycleBase() {
+        const status = this.snapshot.status;
+        if (this.startOperation || status === "starting") {
+            return connectFailure(connectProblem("session_starting", "The application session is still starting."));
+        }
+        if (this.snapshot.status === "start_failed")
+            return connectFailure(this.snapshot.problem);
+        if (this.base)
+            return connectSuccess(this.base);
+        const code = status === "destroyed"
+            ? "session_destroyed"
+            : "session_not_started";
+        return connectFailure(connectProblem(code, lifecycleProblemMessage(code)));
+    }
+    async withLifecycleBase(options, operation) {
+        const lifecycle = this.beginLifecycleOperation(options);
+        const budget = createRequestBudget(lifecycle.options, this.timeouts.requestMs);
+        const requestOptions = { signal: budget.signal, timeoutMs: null };
+        try {
+            const starting = this.startOperation;
+            if (starting) {
+                const started = await this.waitForStart(starting, requestOptions, null);
+                if (!started.ok)
+                    return started;
+            }
+            if (!this.lifecycleCurrent(lifecycle.generation)) {
+                return connectFailure(connectProblem("session_destroyed", lifecycleProblemMessage("session_destroyed")));
+            }
+            const base = this.lifecycleBase();
+            if (!base.ok)
+                return base;
+            const outcome = await operation(base.value, requestOptions, lifecycle.generation);
+            if (!this.lifecycleCurrent(lifecycle.generation))
+                return this.destroyedOutcome(outcome);
+            return outcome;
+        }
+        catch (error) {
+            if (error instanceof MdbaseConnectError) {
+                if (!this.lifecycleCurrent(lifecycle.generation)) {
+                    if (error.problem.code === "operation_outcome_unknown") {
+                        return connectFailure(error.problem);
+                    }
+                    return connectFailure(connectProblem("session_destroyed", lifecycleProblemMessage("session_destroyed")));
+                }
+                return connectFailure(error.problem);
+            }
+            throw error;
+        }
+        finally {
+            budget.dispose();
+            lifecycle.dispose();
+        }
+    }
+    beginLifecycleOperation(options = {}) {
+        const controller = new AbortController();
+        const abort = () => controller.abort(options.signal?.reason);
+        if (options.signal?.aborted)
+            abort();
+        else
+            options.signal?.addEventListener("abort", abort, { once: true });
+        this.operationControllers.add(controller);
+        return {
+            generation: this.lifecycleGeneration,
+            options: { ...options, signal: controller.signal },
+            dispose: () => {
+                options.signal?.removeEventListener("abort", abort);
+                this.operationControllers.delete(controller);
+            }
+        };
+    }
+    lifecycleCurrent(generation) {
+        return this.snapshot.status !== "destroyed" && generation === this.lifecycleGeneration;
+    }
+    destroyedOutcome(outcome) {
+        if (!outcome.ok && outcome.problem.code === "operation_outcome_unknown")
+            return outcome;
+        return connectFailure(connectProblem("session_destroyed", lifecycleProblemMessage("session_destroyed")));
     }
     requireManifest() {
         if (!this.manifest)
@@ -461,6 +668,13 @@ function declarationIdFromFamilyIdentity(familyIdentity) {
     }
     return familyIdentity.slice(prefix.length);
 }
+function lifecycleProblemMessage(code) {
+    if (code === "session_destroyed")
+        return "This application session has been destroyed.";
+    if (code === "session_starting")
+        return "The application session is still starting.";
+    return "Start the application session before using it.";
+}
 function defaultVerificationStore() {
     if (typeof localStorage !== "undefined") {
         return {