@modelprofile.com/authswitch 6.5.0 → 7.0.0

package/ts/classes.authoritydatabase.ts

@@ -1,28 +1,81 @@
 import * as plugins from './plugins.js';
 import {
-  AuthSwitchAuthorityAccountModel, AuthSwitchAuthorityBindingModel, AuthSwitchAuthorityCodexHomeModel, AuthSwitchAuthorityEnrollmentModel,
+  AuthSwitchAuthorityAccountModel, AuthSwitchAuthorityBindingModel, AuthSwitchAuthorityClaudeHandoffModel,
+  AuthSwitchAuthorityClaudeHomeModel, AuthSwitchAuthorityCodexHomeModel, AuthSwitchAuthorityEnrollmentModel,
   AuthSwitchAuthorityEventModel, AuthSwitchAuthorityGrantModel, AuthSwitchAuthorityHandoffModel,
-  AuthSwitchAuthorityMetaModel, AuthSwitchAuthorityMigrationLedgerModel, assertStoredAuthorityAccount,
-  assertStoredAuthorityBinding, assertStoredAuthorityEnrollment, assertStoredAuthorityGrant,
-  assertStoredAuthorityHandoff, assertStoredAuthorityMigrationLedger,
-  type IStoredAuthorityAccount, type IStoredAuthorityBinding, type IStoredAuthorityCodexHome, type IStoredAuthorityEnrollment,
+  AuthSwitchAuthorityMetaModel, AuthSwitchAuthorityMigrationLedgerModel, AuthSwitchAuthorityOperationModel,
+  AuthSwitchAuthorityUsageModel, authorityUsageId, assertStoredAuthorityAccount,
+  assertStoredAuthorityBinding, assertStoredAuthorityClaudeHandoff, assertStoredAuthorityClaudeHome,
+  assertStoredAuthorityEnrollment, assertStoredAuthorityGrant,
+  assertStoredAuthorityHandoff, assertStoredAuthorityMigrationLedger, assertStoredAuthorityOperation,
+  assertStoredAuthorityUsage,
+  type IStoredAuthorityAccount, type IStoredAuthorityBinding, type IStoredAuthorityClaudeHandoff,
+  type IStoredAuthorityClaudeHome, type IStoredAuthorityCodexHome, type IStoredAuthorityEnrollment,
   type IStoredAuthorityEvent, type IStoredAuthorityGrant, type IStoredAuthorityHandoff,
-  type IStoredAuthorityMeta, type IStoredAuthorityMigrationLedger,
+  type IStoredAuthorityDeviceOperation, type IStoredAuthorityMeta, type IStoredAuthorityMigrationLedger,
+  type IStoredAuthorityOperation, type IStoredAuthorityPreuseOperation, type IStoredAuthorityUsage,
 } from './classes.authoritymodels.js';
+import type { IAuthSwitchStoredUsage, IAuthSwitchUsageContext } from './classes.authorityusage.js';
+import { authorityModel, authorityModelRegistry, authorityStoredRecords,
+  assertAuthorityStoredRecord, type IAuthorityStoredRecord } from './classes.authorityregistry.js';
+import type { IAuthorityBackupSnapshotAttempt, IAuthorityBackupSourceCapsule } from './classes.authoritybackup.js';
+import { runAuthorityMigrations } from './ts_migration/index.js';
 
 export interface IAuthSwitchAuthorityDatabaseOptions {
   dataDirectory: string;
   socketPath: string;
 }
 
+export interface IAuthoritySnapshotCaptureOptions {
+  /** Recreate capsules on every transaction retry from a source already held under qualified exclusion. */
+  sourceFactory: () => AsyncIterable<IAuthorityBackupSourceCapsule>;
+  signal?: AbortSignal;
+  pageSize?: number;
+}
+
 type TEventKind = IStoredAuthorityEvent['kind'];
 type TSession = plugins.smartdata.SmartdataSession;
+type TStoredAuthorityDeviceOperationAdmission = Omit<IStoredAuthorityDeviceOperation, 'expectedGrantGeneration'>;
+type TClaudeHandoffDraft = {
+  home: IStoredAuthorityClaudeHome;
+  handoff: IStoredAuthorityClaudeHandoff;
+  outgoing: IStoredAuthorityGrant;
+  incoming: IStoredAuthorityGrant;
+};
+
+const usageContext = (meta: IStoredAuthorityMeta, account: IStoredAuthorityAccount,
+  grant: IStoredAuthorityGrant): IAuthSwitchUsageContext => ({
+  epoch: meta.epoch, accountId: account.id, loginId: grant.id, subjectId: account.subject,
+  workspaceId: account.workspaceId, providerId: account.providerId,
+  purpose: grant.purpose, owner: grant.owner, grantState: grant.state,
+  removed: account.removed, authorizationGeneration: grant.authorizationGeneration,
+  grantGeneration: grant.grantGeneration, nativeSource: null,
+});
+const sameUsageContext = (left: IAuthSwitchUsageContext, right: IAuthSwitchUsageContext): boolean =>
+  left.epoch === right.epoch && left.accountId === right.accountId && left.loginId === right.loginId
+  && left.subjectId === right.subjectId && left.workspaceId === right.workspaceId
+  && left.providerId === right.providerId
+  && left.purpose === right.purpose && left.owner === right.owner && left.grantState === right.grantState
+  && left.removed === right.removed && left.authorizationGeneration === right.authorizationGeneration
+  && left.grantGeneration === right.grantGeneration;
+const sameUsageSource = (left: IAuthSwitchUsageContext, right: IAuthSwitchUsageContext): boolean =>
+  sameUsageContext(left, right) && (left.nativeSource === null ? right.nativeSource === null
+    : right.nativeSource !== null && left.nativeSource.homeId === right.nativeSource.homeId
+      && left.nativeSource.credentialDigest === right.nativeSource.credentialDigest
+      && left.nativeSource.configDigest === right.nativeSource.configDigest
+      && left.nativeSource.accessTokenDigest === right.nativeSource.accessTokenDigest);
+const storedOperation = (stored: Parameters<typeof AuthSwitchAuthorityOperationModel.exact.toPersisted>[0]): IStoredAuthorityOperation => {
+  const operation = AuthSwitchAuthorityOperationModel.exact.toPersisted(stored);
+  assertStoredAuthorityOperation(operation);
+  return operation;
+};
 
 /** Separate account, grant, binding and journal records; the only global record is a revision counter. */
 export class AuthSwitchAuthorityDatabase {
   private engine?: plugins.smartdb.LocalSmartDb;
   private database?: plugins.smartdata.SmartdataDb;
   private started = false;
+  private mode: 'normal' | 'closed_restore' | null = null;
 
   constructor(private readonly options: IAuthSwitchAuthorityDatabaseOptions) {}
 
@@ -35,8 +88,10 @@ export class AuthSwitchAuthorityDatabase {
     await plugins.fs.promises.chmod(pathArg, 0o700);
   }
 
-  public async start(): Promise<void> {
+  public async start(options: { mode?: 'normal' | 'closed_restore' } = {}): Promise<void> {
     if (this.started || this.engine || this.database) throw new Error('Authswitch database is already starting or started.');
+    const mode = options.mode ?? 'normal';
+    if (mode !== 'normal' && mode !== 'closed_restore') throw new Error('Invalid authority database start mode.');
     await this.privateDirectory(this.options.dataDirectory);
     await this.privateDirectory(plugins.path.dirname(this.options.socketPath));
     const engine = new plugins.smartdb.LocalSmartDb({ folderPath: this.options.dataDirectory, socketPath: this.options.socketPath });
@@ -45,26 +100,41 @@ export class AuthSwitchAuthorityDatabase {
       const connection = await engine.start();
       const database = new plugins.smartdata.SmartdataDb({ mongoDbUrl: connection.connectionUri, mongoDbName: 'authswitch' });
       this.database = database;
-      for (const model of [AuthSwitchAuthorityMetaModel, AuthSwitchAuthorityAccountModel,
-        AuthSwitchAuthorityGrantModel, AuthSwitchAuthorityBindingModel, AuthSwitchAuthorityCodexHomeModel, AuthSwitchAuthorityEnrollmentModel,
-        AuthSwitchAuthorityHandoffModel, AuthSwitchAuthorityMigrationLedgerModel, AuthSwitchAuthorityEventModel]) {
-        plugins.smartdata.setDefaultManagerForDoc({ db: database }, model);
-      }
       await database.init();
-      await Promise.all([AuthSwitchAuthorityMetaModel.init(), AuthSwitchAuthorityAccountModel.init(),
-        AuthSwitchAuthorityGrantModel.init(), AuthSwitchAuthorityBindingModel.init(), AuthSwitchAuthorityCodexHomeModel.init(),
-        AuthSwitchAuthorityEnrollmentModel.init(), AuthSwitchAuthorityHandoffModel.init(),
-        AuthSwitchAuthorityMigrationLedgerModel.init(), AuthSwitchAuthorityEventModel.init()]);
-      await Promise.all([AuthSwitchAuthorityMetaModel.exact.prepare(), AuthSwitchAuthorityAccountModel.exact.prepare(),
-        AuthSwitchAuthorityGrantModel.exact.prepare(), AuthSwitchAuthorityBindingModel.exact.prepare(), AuthSwitchAuthorityCodexHomeModel.exact.prepare(),
-        AuthSwitchAuthorityEnrollmentModel.exact.prepare(), AuthSwitchAuthorityHandoffModel.exact.prepare(),
-        AuthSwitchAuthorityMigrationLedgerModel.exact.prepare(), AuthSwitchAuthorityEventModel.exact.prepare()]);
-      const initial: IStoredAuthorityMeta = {
-        id: 'authswitch-authority', epoch: plugins.crypto.randomUUID(), revision: 0,
-        updateId: plugins.crypto.randomUUID(),
-      };
-      const result = await AuthSwitchAuthorityMetaModel.exact.insert(initial);
-      if (result.status === 'conflict' && result.document.id !== initial.id) throw new Error('Authswitch authority could not initialize.');
+      // The LocalSmartDb root lease excludes another engine during this catalog admission.
+      const inventory = await database.inspectNamespace({ maxCollections: 1024,
+        documentCountUpTo: 0, timeoutMs: 30_000 });
+      const names = new Set(authorityModelRegistry.map(entry => entry.name));
+      for (const collection of inventory.collections) {
+        if (collection.namespaceType !== 'collection' || !names.has(collection.collectionName)) {
+          throw new Error('Authswitch authority database contains an unknown collection or namespace.');
+        }
+      }
+      const fresh = inventory.collections.length === 0;
+      if (mode === 'closed_restore' && !fresh) {
+        throw new Error('Closed authority restore requires an empty database.');
+      }
+      if (mode === 'normal' && !fresh) {
+        if (!inventory.collections.some(item => item.collectionName === 'authswitch_authority_meta')) {
+          throw new Error('Existing authswitch authority database has no metadata collection.');
+        }
+        await runAuthorityMigrations(database);
+      }
+      await Promise.all(authorityModelRegistry.map(entry => entry.initialize(database)));
+      await Promise.all(authorityModelRegistry.map(entry => entry.prepare()));
+      if (mode === 'normal') {
+        if (fresh) {
+          const initial: IStoredAuthorityMeta = {
+            id: 'authswitch-authority', schemaVersion: 2, admission: 'open',
+            epoch: plugins.crypto.randomUUID(), revision: 0, updateId: plugins.crypto.randomUUID(),
+          };
+          const result = await AuthSwitchAuthorityMetaModel.exact.insert(initial);
+          if (result.status !== 'inserted') throw new Error('Authswitch authority could not initialize.');
+        } else if (!await AuthSwitchAuthorityMetaModel.exact.findStoredOne({ id: 'authswitch-authority' })) {
+          throw new Error('Existing authswitch authority metadata is missing.');
+        }
+      }
+      this.mode = mode;
       this.started = true;
     } catch (error) {
       try { await this.stop(); } catch { /* Preserve the original startup error. */ }
@@ -86,6 +156,70 @@ export class AuthSwitchAuthorityDatabase {
     } finally { await session.close(); }
   }
 
+  /** One repeatable SmartData transaction per capture attempt; portable staging happens inside visit. */
+  public async captureBackupSnapshot(options: IAuthoritySnapshotCaptureOptions,
+    visit: (attempt: IAuthorityBackupSnapshotAttempt) => Promise<void>): Promise<void> {
+    if (typeof options.sourceFactory !== 'function' || typeof visit !== 'function') {
+      throw new Error('Authority backup capture requires an exact source and visitor.');
+    }
+    await this.transaction(async session => {
+      options.signal?.throwIfAborted();
+      const stored = await AuthSwitchAuthorityMetaModel.exact.findStoredOne({ id: 'authswitch-authority' },
+        { session, signal: options.signal });
+      if (!stored) throw new Error('Authority backup metadata is absent.');
+      const meta = AuthSwitchAuthorityMetaModel.exact.toPersisted(stored);
+      if (meta.admission !== 'open') throw new Error('Closed restored authority cannot publish a backup.');
+      let recordsComplete = false;
+      let sourcesComplete = false;
+      const records = async function* (): AsyncGenerator<IAuthorityStoredRecord> {
+        yield* authorityStoredRecords({ session, signal: options.signal, pageSize: options.pageSize });
+        recordsComplete = true;
+      };
+      const sources = async function* (): AsyncGenerator<IAuthorityBackupSourceCapsule> {
+        for await (const source of options.sourceFactory()) {
+          options.signal?.throwIfAborted();
+          yield source;
+        }
+        sourcesComplete = true;
+      };
+      await visit({ epoch: meta.epoch, revision: meta.revision, records: records(), sources: sources() });
+      if (!recordsComplete || !sourcesComplete) {
+        throw new Error('Authority backup visitor did not consume the complete pinned inventory.');
+      }
+      return true;
+    });
+  }
+
+  /** Reopened closed restore readback uses the same exhaustive registry and stable keyset order. */
+  public readStoredRecords(options: { signal?: AbortSignal; pageSize?: number } = {}): AsyncIterable<IAuthorityStoredRecord> {
+    this.db();
+    return authorityStoredRecords(options);
+  }
+
+  public async restoreClosedMeta(meta: IStoredAuthorityMeta): Promise<void> {
+    if (this.mode !== 'closed_restore') throw new Error('Authority database is not a closed restore target.');
+    const record: IAuthorityStoredRecord = { model: 'authswitch_authority_meta', id: meta.id, value: meta };
+    assertAuthorityStoredRecord(record);
+    if (meta.admission !== 'closed_restored') throw new Error('Restored authority metadata must remain closed.');
+    await authorityModel(record.model).insert(record);
+  }
+
+  public async insertClosedRestoredRecord(record: IAuthorityStoredRecord): Promise<void> {
+    if (this.mode !== 'closed_restore' || record.model === 'authswitch_authority_meta') {
+      throw new Error('Authority database is not admitting this restored record.');
+    }
+    if ((await this.readMeta()).admission !== 'closed_restored') {
+      throw new Error('Closed restore metadata must be installed before records.');
+    }
+    assertAuthorityStoredRecord(record);
+    await authorityModel(record.model).insert(record);
+  }
+
+  public async assertOpenAdmission(): Promise<void> {
+    const meta = await this.readMeta();
+    if (meta.admission !== 'open') throw new Error('Restored authority admission is closed pending ownership reconciliation.');
+  }
+
   public async readMeta(): Promise<IStoredAuthorityMeta> {
     this.db();
     const stored = await AuthSwitchAuthorityMetaModel.exact.findStoredOne({ id: 'authswitch-authority' });
@@ -111,28 +245,40 @@ export class AuthSwitchAuthorityDatabase {
     return stored ? AuthSwitchAuthorityCodexHomeModel.exact.toPersisted(stored) : null;
   }
 
+  /** Durable home claims must be inspected even when the daemon has lost its process map. */
+  public async codexHomesForAccount(accountId: string, after: string | null): Promise<IStoredAuthorityCodexHome[]> {
+    this.db();
+    if (!/^[a-f0-9]{64}$/.test(accountId) || (after !== null && !/^[a-f0-9]{64}$/.test(after))) {
+      throw new Error('Invalid managed Codex home selector.');
+    }
+    const stored = await AuthSwitchAuthorityCodexHomeModel.exact.findStored({
+      filter: after ? { accountId, id: { $gt: after } } : { accountId }, sort: { id: 1 }, limit: 128,
+    });
+    return stored.map(item => AuthSwitchAuthorityCodexHomeModel.exact.toPersisted(item));
+  }
+
   /** Home path identity is hashed by the caller; no vendor files or raw paths enter SmartData. */
-  public async reserveCodexHome(accountId: string, scopeId: string, homeId: string,
+  public async reserveCodexHome(accountId: string, grantId: string, scopeId: string, homeId: string,
     updateId: string): Promise<{ newlyRegistered: boolean }> {
     try {
       return await this.transaction(async session => {
         const accountStored = await AuthSwitchAuthorityAccountModel.exact.findStoredOne({ id: accountId }, { session });
         const account = accountStored ? AuthSwitchAuthorityAccountModel.exact.toPersisted(accountStored) : null;
-        const grantStored = account?.primaryGrantId
-          ? await AuthSwitchAuthorityGrantModel.exact.findStoredOne({ id: account.primaryGrantId }, { session }) : null;
+        const grantStored = await AuthSwitchAuthorityGrantModel.exact.findStoredOne({ id: grantId }, { session });
         const grant = grantStored ? AuthSwitchAuthorityGrantModel.exact.toPersisted(grantStored) : null;
         if (!account || account.removed || account.providerId !== 'openai' || grant?.owner !== 'daemon'
-          || grant.purpose !== 'openai_managed' || grant.accountId !== accountId || grant.state === 'removed') {
+          || grant.purpose !== 'openai_managed' || grant.accountId !== accountId
+          || grant.id !== account.primaryGrantId || grant.state === 'removed') {
           throw new Error('Managed Codex requires a daemon-owned OpenAI account.');
         }
         const used = await AuthSwitchAuthorityCodexHomeModel.exact.findStoredOne({ id: homeId }, { session });
         if (used) {
-          if (used.accountId !== accountId || used.scopeId !== scopeId) {
+          if (used.accountId !== accountId || used.grantId !== grantId || used.scopeId !== scopeId) {
             throw new Error('Managed Codex home already belongs to another account or scope.');
           }
           return { newlyRegistered: false };
         }
-        const record: IStoredAuthorityCodexHome = { id: homeId, accountId, scopeId, activeRun: null,
+        const record: IStoredAuthorityCodexHome = { id: homeId, accountId, grantId, scopeId, activeRun: null,
           createdAt: new Date().toISOString(), updateId };
         const inserted = await AuthSwitchAuthorityCodexHomeModel.exact.insert(record, { session });
         if (inserted.status !== 'inserted') throw new Error('Managed Codex home changed during admission.');
@@ -142,7 +288,7 @@ export class AuthSwitchAuthorityDatabase {
       if (error instanceof plugins.smartdata.SmartdataExactPersistenceError
         && (error.code === 'ambiguous_write' || error.code === 'unique_conflict')) {
         const assigned = await AuthSwitchAuthorityCodexHomeModel.exact.findStoredOne({ id: homeId });
-        if (assigned?.accountId === accountId && assigned.scopeId === scopeId
+        if (assigned?.accountId === accountId && assigned.grantId === grantId && assigned.scopeId === scopeId
           && assigned.updateId === updateId) return { newlyRegistered: true };
         throw new Error('Managed Codex home registration changed concurrently; refresh before retrying.');
       }
@@ -188,10 +334,10 @@ export class AuthSwitchAuthorityDatabase {
       const accountStored = binding
         ? await AuthSwitchAuthorityAccountModel.exact.findStoredOne({ id: binding.accountId }, { session }) : null;
       const account = accountStored ? AuthSwitchAuthorityAccountModel.exact.toPersisted(accountStored) : null;
-      const grantStored = binding && account?.primaryGrantId === binding.grantId
+      const grantStored = binding && account && !account.removed
         ? await AuthSwitchAuthorityGrantModel.exact.findStoredOne({ id: binding.grantId }, { session }) : null;
       const grant = grantStored ? AuthSwitchAuthorityGrantModel.exact.toPersisted(grantStored) : null;
-      return { binding, account, grant };
+      return { binding, account, grant: grant?.accountId === account?.id ? grant : null };
     });
   }
 
@@ -219,6 +365,296 @@ export class AuthSwitchAuthorityDatabase {
     return stored ? AuthSwitchAuthorityMigrationLedgerModel.exact.toPersisted(stored) : null;
   }
 
+  public async readOperation(id: string): Promise<IStoredAuthorityOperation | null> {
+    this.db();
+    const stored = await AuthSwitchAuthorityOperationModel.exact.findStoredOne({ id });
+    return stored ? storedOperation(stored) : null;
+  }
+
+  public async operationsPage(after: string | null, limit = 128): Promise<{ operations: IStoredAuthorityDeviceOperation[]; nextCursor: string | null }> {
+    this.db();
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 256) throw new Error('Invalid operation page size.');
+    const stored = await AuthSwitchAuthorityOperationModel.exact.findStored({
+      filter: after
+        ? { kind: { $in: ['add_openai', 'reauth_openai'] }, id: { $gt: after } }
+        : { kind: { $in: ['add_openai', 'reauth_openai'] } },
+      sort: { id: 1 }, limit: limit + 1,
+    });
+    const operations = stored.slice(0, limit).map(storedOperation)
+      .filter((item): item is IStoredAuthorityDeviceOperation => item.kind !== 'preuse_openai');
+    return { operations, nextCursor: stored.length > limit ? operations.at(-1)!.id : null };
+  }
+
+  public async operationsByState(state: IStoredAuthorityDeviceOperation['state'], after: string | null,
+    limit = 128): Promise<IStoredAuthorityDeviceOperation[]> {
+    this.db();
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 256) throw new Error('Invalid operation page size.');
+    const stored = await AuthSwitchAuthorityOperationModel.exact.findStored({
+      filter: after ? { state, id: { $gt: after } } : { state }, sort: { id: 1 }, limit,
+    });
+    return stored.map(storedOperation)
+      .filter((item): item is IStoredAuthorityDeviceOperation => item.kind !== 'preuse_openai');
+  }
+
+  public async preuseOperationsByState(state: IStoredAuthorityPreuseOperation['state'], after: string | null,
+    limit = 128): Promise<IStoredAuthorityPreuseOperation[]> {
+    this.db();
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 256) throw new Error('Invalid operation page size.');
+    const stored = await AuthSwitchAuthorityOperationModel.exact.findStored({
+      filter: after ? { kind: 'preuse_openai', state, id: { $gt: after } } : { kind: 'preuse_openai', state },
+      sort: { id: 1 }, limit,
+    });
+    return stored.map(storedOperation)
+      .filter((item): item is IStoredAuthorityPreuseOperation => item.kind === 'preuse_openai');
+  }
+
+  /** Insert-or-read admission for one exact device-login intent. Existing receipts are never replayed. */
+  public async createOperation(intent: TStoredAuthorityDeviceOperationAdmission): Promise<{
+    operation: IStoredAuthorityDeviceOperation; created: boolean;
+  }> {
+    this.db();
+    assertStoredAuthorityOperation({ ...intent,
+      expectedGrantGeneration: intent.kind === 'reauth_openai' ? 1 : null });
+    const sameRequest = (current: IStoredAuthorityOperation): current is IStoredAuthorityDeviceOperation =>
+      current.kind !== 'preuse_openai' && current.kind === intent.kind
+      && current.accountId === intent.accountId && current.grantId === intent.grantId
+      && current.purpose === intent.purpose;
+    try {
+      return await this.transaction(async session => {
+        const existingStored = await AuthSwitchAuthorityOperationModel.exact.findStoredOne(
+          { id: intent.id }, { session });
+        if (existingStored) {
+          const existing = storedOperation(existingStored);
+          if (!sameRequest(existing)) throw new Error('Account operation ID belongs to a different request.');
+          return { operation: existing, created: false };
+        }
+        const metaStored = await AuthSwitchAuthorityMetaModel.exact.findStoredOne(
+          { id: 'authswitch-authority' }, { session });
+        if (!metaStored || AuthSwitchAuthorityMetaModel.exact.toPersisted(metaStored).admission !== 'open') {
+          throw new Error('Authswitch authority admission is closed.');
+        }
+        let expectedGrantGeneration: number | null = null;
+        if (intent.kind === 'reauth_openai') {
+          const accountStored = await AuthSwitchAuthorityAccountModel.exact.findStoredOne(
+            { id: intent.accountId! }, { session });
+          const grantStored = await AuthSwitchAuthorityGrantModel.exact.findStoredOne(
+            { id: intent.grantId! }, { session });
+          const account = accountStored ? AuthSwitchAuthorityAccountModel.exact.toPersisted(accountStored) : null;
+          const grant = grantStored ? AuthSwitchAuthorityGrantModel.exact.toPersisted(grantStored) : null;
+          if (!account || account.removed || account.providerId !== 'openai'
+            || account.primaryGrantId !== intent.grantId || !grant || grant.accountId !== intent.accountId
+            || grant.providerId !== 'openai' || grant.purpose !== 'openai_managed'
+            || grant.owner !== 'daemon' || ['removed', 'exchange_may_have_been_sent'].includes(grant.state)) {
+            throw new Error('Selected OpenAI login is unavailable for reauthentication.');
+          }
+          expectedGrantGeneration = grant.grantGeneration;
+        }
+        const operation: IStoredAuthorityDeviceOperation = { ...intent, expectedGrantGeneration };
+        assertStoredAuthorityOperation(operation);
+        const result = await AuthSwitchAuthorityOperationModel.exact.insert(operation, { session });
+        if (result.status !== 'inserted') throw new Error('Account operation ID already exists.');
+        return { operation, created: true };
+      });
+    } catch (error) {
+      if (!(error instanceof plugins.smartdata.SmartdataExactPersistenceError) || error.code !== 'ambiguous_write') throw error;
+      const stored = await this.readOperation(intent.id);
+      if (stored && sameRequest(stored)) {
+        return { operation: stored, created: stored.updateId === intent.updateId };
+      }
+      throw new Error('Account operation creation outcome is unknown; no provider login was started.');
+    }
+  }
+
+  /** Revalidate the durable owner and exact reauthentication generation after mutable runtime preparation. */
+  public async confirmOperationMayStart(operationId: string): Promise<IStoredAuthorityDeviceOperation> {
+    return this.transaction(async session => {
+      const metaStored = await AuthSwitchAuthorityMetaModel.exact.findStoredOne(
+        { id: 'authswitch-authority' }, { session });
+      const operationStored = await AuthSwitchAuthorityOperationModel.exact.findStoredOne(
+        { id: operationId }, { session });
+      if (!metaStored || AuthSwitchAuthorityMetaModel.exact.toPersisted(metaStored).admission !== 'open') {
+        throw new Error('Authswitch authority admission is closed.');
+      }
+      if (!operationStored) throw new Error('Account operation was not found.');
+      const operation = storedOperation(operationStored);
+      if (operation.kind === 'preuse_openai' || operation.state !== 'starting') {
+        throw new Error('Account operation is no longer starting.');
+      }
+      if (operation.kind === 'reauth_openai') {
+        const accountStored = await AuthSwitchAuthorityAccountModel.exact.findStoredOne(
+          { id: operation.accountId! }, { session });
+        const grantStored = await AuthSwitchAuthorityGrantModel.exact.findStoredOne(
+          { id: operation.grantId! }, { session });
+        const account = accountStored ? AuthSwitchAuthorityAccountModel.exact.toPersisted(accountStored) : null;
+        const grant = grantStored ? AuthSwitchAuthorityGrantModel.exact.toPersisted(grantStored) : null;
+        if (!account || account.removed || account.providerId !== 'openai'
+          || account.primaryGrantId !== operation.grantId || !grant || grant.accountId !== operation.accountId
+          || grant.providerId !== 'openai' || grant.purpose !== 'openai_managed'
+          || grant.owner !== 'daemon' || ['removed', 'exchange_may_have_been_sent'].includes(grant.state)
+          || grant.grantGeneration !== operation.expectedGrantGeneration) {
+          throw new Error('Selected OpenAI login changed before reauthentication could start.');
+        }
+      }
+      return operation;
+    });
+  }
+
+  public async changeOperation(updateId: string, operationId: string,
+    change: (operation: IStoredAuthorityDeviceOperation) => IStoredAuthorityDeviceOperation): Promise<IStoredAuthorityDeviceOperation> {
+    this.db();
+    try {
+      const stored = await AuthSwitchAuthorityOperationModel.exact.findStoredOne({ id: operationId });
+      if (!stored) throw new Error('Account operation was not found.');
+      const current = storedOperation(stored);
+      if (current.kind === 'preuse_openai') throw new Error('Account operation is not a device login.');
+      const draft = change(structuredClone(current));
+      const allowed: Record<IStoredAuthorityDeviceOperation['state'], IStoredAuthorityDeviceOperation['state'][]> = {
+        starting: ['pending', 'failed', 'cancelled', 'interrupted'],
+        pending: ['committing', 'failed', 'cancelled', 'interrupted'],
+        committing: ['complete', 'outcome_unknown'],
+        complete: [], failed: [], cancelled: [], interrupted: [], outcome_unknown: [],
+      };
+      if (draft.id !== current.id || draft.kind !== current.kind || draft.purpose !== current.purpose
+        || draft.accountId !== current.accountId || draft.grantId !== current.grantId
+        || draft.expectedGrantGeneration !== current.expectedGrantGeneration
+        || draft.createdAt !== current.createdAt || draft.updateId !== updateId
+        || draft.revision !== current.revision + 1 || !allowed[current.state].includes(draft.state)) {
+        throw new Error('Account operation transition is invalid.');
+      }
+      assertStoredAuthorityOperation(draft);
+      const result = await AuthSwitchAuthorityOperationModel.exact.transition({
+        current: stored, change: model => Object.assign(model, draft),
+      });
+      if (result.status !== 'transitioned') throw new Error('Account operation changed concurrently.');
+      return draft;
+    } catch (error) {
+      if (!(error instanceof plugins.smartdata.SmartdataExactPersistenceError) || error.code !== 'ambiguous_write') throw error;
+      const stored = await this.readOperation(operationId);
+      if (stored?.kind !== 'preuse_openai' && stored?.updateId === updateId) return stored;
+      throw new Error('Account operation transition outcome is unknown.');
+    }
+  }
+
+  /** Insert-or-read idempotency for one exact preuse request. Existing records are never resumed here. */
+  public async createPreuseOperation(operation: IStoredAuthorityPreuseOperation): Promise<{
+    operation: IStoredAuthorityPreuseOperation; created: boolean;
+  }> {
+    this.db();
+    assertStoredAuthorityOperation(operation);
+    const sameRequest = (current: IStoredAuthorityOperation): current is IStoredAuthorityPreuseOperation =>
+      current.kind === 'preuse_openai' && current.accountId === operation.accountId
+      && current.grantId === operation.grantId && current.purpose === operation.purpose
+      && current.requestHash === operation.requestHash && current.requestedModel === operation.requestedModel;
+    try {
+      return await this.transaction(async session => {
+        const existingStored = await AuthSwitchAuthorityOperationModel.exact.findStoredOne({ id: operation.id }, { session });
+        if (existingStored) {
+          const existing = storedOperation(existingStored);
+          if (!sameRequest(existing)) throw new Error('Preuse operation ID belongs to a different request.');
+          return { operation: existing, created: false };
+        }
+        const accountStored = await AuthSwitchAuthorityAccountModel.exact.findStoredOne({ id: operation.accountId }, { session });
+        const grantStored = await AuthSwitchAuthorityGrantModel.exact.findStoredOne({ id: operation.grantId }, { session });
+        const account = accountStored ? AuthSwitchAuthorityAccountModel.exact.toPersisted(accountStored) : null;
+        const grant = grantStored ? AuthSwitchAuthorityGrantModel.exact.toPersisted(grantStored) : null;
+        if (!account || account.removed || account.providerId !== 'openai' || account.primaryGrantId !== operation.grantId
+          || !grant || grant.accountId !== operation.accountId || grant.providerId !== 'openai'
+          || grant.purpose !== 'openai_managed' || grant.owner !== 'daemon'
+          || !['ready', 'retry_wait'].includes(grant.state)
+          || grant.authorizationGeneration !== operation.authorizationGeneration) {
+          throw new Error('Selected OpenAI login is unavailable for preuse.');
+        }
+        const inserted = await AuthSwitchAuthorityOperationModel.exact.insert(operation, { session });
+        if (inserted.status !== 'inserted') throw new Error('Preuse operation ID already exists.');
+        return { operation, created: true };
+      });
+    } catch (error) {
+      if (!(error instanceof plugins.smartdata.SmartdataExactPersistenceError) || error.code !== 'ambiguous_write') throw error;
+      const stored = await this.readOperation(operation.id);
+      if (stored && sameRequest(stored) && stored.updateId === operation.updateId) {
+        return { operation: stored, created: true };
+      }
+      throw new Error('Preuse operation creation outcome is unknown; no provider request was started.');
+    }
+  }
+
+  /** The committed marker precedes the only quota-consuming provider call. */
+  public async markPreuseRequestMayHaveStarted(operationId: string, updateId: string, model: string,
+    grantGeneration: number, now: string): Promise<IStoredAuthorityPreuseOperation> {
+    try {
+      return await this.transaction(async session => {
+        const operationStored = await AuthSwitchAuthorityOperationModel.exact.findStoredOne({ id: operationId }, { session });
+        if (!operationStored) throw new Error('Preuse operation was not found.');
+        const current = storedOperation(operationStored);
+        if (current.kind !== 'preuse_openai' || current.state !== 'preparing') {
+          throw new Error('Preuse operation is no longer preparing.');
+        }
+        const accountStored = await AuthSwitchAuthorityAccountModel.exact.findStoredOne({ id: current.accountId }, { session });
+        const grantStored = await AuthSwitchAuthorityGrantModel.exact.findStoredOne({ id: current.grantId }, { session });
+        const account = accountStored ? AuthSwitchAuthorityAccountModel.exact.toPersisted(accountStored) : null;
+        const grant = grantStored ? AuthSwitchAuthorityGrantModel.exact.toPersisted(grantStored) : null;
+        if (!account || account.removed || account.providerId !== 'openai' || account.primaryGrantId !== current.grantId
+          || !grant || grant.accountId !== current.accountId || grant.providerId !== 'openai'
+          || grant.purpose !== current.purpose || grant.owner !== 'daemon'
+          || !['ready', 'retry_wait'].includes(grant.state)
+          || grant.authorizationGeneration !== current.authorizationGeneration
+          || grant.grantGeneration !== grantGeneration) {
+          throw new Error('Preuse login changed before its request marker was committed.');
+        }
+        const draft: IStoredAuthorityPreuseOperation = { ...current, model, grantGeneration,
+          state: 'request_may_have_started', updatedAt: now, revision: current.revision + 1, updateId };
+        assertStoredAuthorityOperation(draft);
+        const transitioned = await AuthSwitchAuthorityOperationModel.exact.transition({
+          current: operationStored, change: stored => Object.assign(stored, draft),
+        }, { session });
+        if (transitioned.status !== 'transitioned') throw new Error('Preuse operation changed concurrently.');
+        return draft;
+      });
+    } catch (error) {
+      if (!(error instanceof plugins.smartdata.SmartdataExactPersistenceError) || error.code !== 'ambiguous_write') throw error;
+      const stored = await this.readOperation(operationId);
+      if (stored?.kind === 'preuse_openai' && stored.updateId === updateId
+        && stored.state === 'request_may_have_started') return stored;
+      throw new Error('Preuse request-marker outcome is unknown; no provider request was started.');
+    }
+  }
+
+  public async changePreuseOperation(updateId: string, operationId: string,
+    change: (operation: IStoredAuthorityPreuseOperation) => IStoredAuthorityPreuseOperation): Promise<IStoredAuthorityPreuseOperation> {
+    this.db();
+    try {
+      const stored = await AuthSwitchAuthorityOperationModel.exact.findStoredOne({ id: operationId });
+      if (!stored) throw new Error('Preuse operation was not found.');
+      const current = storedOperation(stored);
+      if (current.kind !== 'preuse_openai') throw new Error('Operation is not a preuse request.');
+      const draft = change(structuredClone(current));
+      const allowed: Record<IStoredAuthorityPreuseOperation['state'], IStoredAuthorityPreuseOperation['state'][]> = {
+        preparing: ['request_may_have_started', 'not_sent'],
+        request_may_have_started: ['complete', 'outcome_unknown'],
+        complete: [], not_sent: [], outcome_unknown: [],
+      };
+      if (draft.id !== current.id || draft.kind !== current.kind || draft.purpose !== current.purpose
+        || draft.accountId !== current.accountId || draft.grantId !== current.grantId
+        || draft.requestHash !== current.requestHash || draft.requestedModel !== current.requestedModel
+        || draft.authorizationGeneration !== current.authorizationGeneration
+        || draft.createdAt !== current.createdAt || draft.updateId !== updateId
+        || draft.revision !== current.revision + 1 || !allowed[current.state].includes(draft.state)) {
+        throw new Error('Preuse operation transition is invalid.');
+      }
+      assertStoredAuthorityOperation(draft);
+      const result = await AuthSwitchAuthorityOperationModel.exact.transition({
+        current: stored, change: model => Object.assign(model, draft),
+      });
+      if (result.status !== 'transitioned') throw new Error('Preuse operation changed concurrently.');
+      return draft;
+    } catch (error) {
+      if (!(error instanceof plugins.smartdata.SmartdataExactPersistenceError) || error.code !== 'ambiguous_write') throw error;
+      const stored = await this.readOperation(operationId);
+      if (stored?.kind === 'preuse_openai' && stored.updateId === updateId) return stored;
+      throw new Error('Preuse operation transition outcome is unknown.');
+    }
+  }
+
   public async migrationLedgerByStatus(status: IStoredAuthorityMigrationLedger['status'],
     after: string | null, limit = 128): Promise<IStoredAuthorityMigrationLedger[]> {
     this.db();
@@ -241,10 +677,153 @@ export class AuthSwitchAuthorityDatabase {
     });
   }
 
-  public async page(accountAfter: string | null, bindingAfter: string | null, limit: number): Promise<{
-    meta: IStoredAuthorityMeta; accounts: Array<{ account: IStoredAuthorityAccount; grant: IStoredAuthorityGrant | null }>;
+  public async readAccountAndGrant(accountId: string, grantId: string): Promise<{
+    account: IStoredAuthorityAccount | null; grant: IStoredAuthorityGrant | null;
+  }> {
+    return this.transaction(async session => {
+      const accountStored = await AuthSwitchAuthorityAccountModel.exact.findStoredOne({ id: accountId }, { session });
+      const grantStored = await AuthSwitchAuthorityGrantModel.exact.findStoredOne({ id: grantId }, { session });
+      const account = accountStored ? AuthSwitchAuthorityAccountModel.exact.toPersisted(accountStored) : null;
+      const grant = grantStored ? AuthSwitchAuthorityGrantModel.exact.toPersisted(grantStored) : null;
+      return { account, grant: grant?.accountId === accountId ? grant : null };
+    });
+  }
+
+  /** Epoch, account and exact login are read from one authority snapshot. */
+  public async readUsageContext(accountId: string, loginId: string): Promise<IAuthSwitchUsageContext | null> {
+    return (await this.readUsageAccessView(accountId, loginId))?.context ?? null;
+  }
+
+  /** Backend-only view used to validate a usage token before and after unsealing. */
+  public async readUsageAccessView(accountId: string, loginId: string): Promise<{
+    context: IAuthSwitchUsageContext; account: IStoredAuthorityAccount; grant: IStoredAuthorityGrant;
+  } | null> {
+    if (!/^[a-f0-9]{64}$/.test(accountId) || !/^[a-f0-9]{64}$/.test(loginId)) {
+      throw new Error('Invalid authority usage identity.');
+    }
+    return this.transaction(async session => {
+      const meta = await AuthSwitchAuthorityMetaModel.exact.findStoredOne({ id: 'authswitch-authority' }, { session });
+      const account = await AuthSwitchAuthorityAccountModel.exact.findStoredOne({ id: accountId }, { session });
+      const grant = await AuthSwitchAuthorityGrantModel.exact.findStoredOne({ id: loginId }, { session });
+      if (!meta || !account || !grant || grant.accountId !== accountId) return null;
+      const accountRecord = AuthSwitchAuthorityAccountModel.exact.toPersisted(account);
+      const grantRecord = AuthSwitchAuthorityGrantModel.exact.toPersisted(grant);
+      return { context: usageContext(AuthSwitchAuthorityMetaModel.exact.toPersisted(meta), accountRecord, grantRecord),
+        account: accountRecord, grant: grantRecord };
+    });
+  }
+
+  /** Coherent native source ownership, including the home handoff fence. */
+  public async readClaudeNativeUsageView(homeId: string, accountId: string, loginId: string): Promise<{
+    context: IAuthSwitchUsageContext; account: IStoredAuthorityAccount; grant: IStoredAuthorityGrant;
+    home: IStoredAuthorityClaudeHome;
+  } | null> {
+    if (![homeId, accountId, loginId].every(id => /^[a-f0-9]{64}$/.test(id))) {
+      throw new Error('Invalid Claude native usage selector.');
+    }
+    return this.transaction(async session => {
+      const metaStored = await AuthSwitchAuthorityMetaModel.exact.findStoredOne({ id: 'authswitch-authority' }, { session });
+      const accountStored = await AuthSwitchAuthorityAccountModel.exact.findStoredOne({ id: accountId }, { session });
+      const grantStored = await AuthSwitchAuthorityGrantModel.exact.findStoredOne({ id: loginId }, { session });
+      const homeStored = await AuthSwitchAuthorityClaudeHomeModel.exact.findStoredOne({ id: homeId }, { session });
+      if (!metaStored || !accountStored || !grantStored || !homeStored
+        || grantStored.accountId !== accountId || accountStored.removed
+        || accountStored.providerId !== 'anthropic' || grantStored.providerId !== 'anthropic'
+        || grantStored.purpose !== 'claude_host_native' || grantStored.owner !== 'claude_native'
+        || grantStored.state !== 'native' || homeStored.status !== 'ready'
+        || homeStored.pendingOperationId !== null || homeStored.activeAccountId !== accountId
+        || homeStored.activeGrantId !== loginId) return null;
+      const account = AuthSwitchAuthorityAccountModel.exact.toPersisted(accountStored);
+      const grant = AuthSwitchAuthorityGrantModel.exact.toPersisted(grantStored);
+      return { context: usageContext(AuthSwitchAuthorityMetaModel.exact.toPersisted(metaStored), account, grant),
+        account, grant, home: AuthSwitchAuthorityClaudeHomeModel.exact.toPersisted(homeStored) };
+    });
+  }
+
+  public async readUsage(accountId: string, loginId: string): Promise<IAuthSwitchStoredUsage | null> {
+    this.db();
+    if (!/^[a-f0-9]{64}$/.test(accountId) || !/^[a-f0-9]{64}$/.test(loginId)) {
+      throw new Error('Invalid authority usage identity.');
+    }
+    const stored = await AuthSwitchAuthorityUsageModel.exact.findStoredOne({ id: authorityUsageId(accountId, loginId) });
+    if (!stored) return null;
+    const { id: _id, accountId: _accountId, loginId: _loginId, ...record } =
+      AuthSwitchAuthorityUsageModel.exact.toPersisted(stored);
+    return record;
+  }
+
+  /** Publish one credential-free usage result only if its authority and predecessor still match. */
+  public async publishUsageIfCurrent(context: IAuthSwitchUsageContext,
+    previousUpdateId: string | null, next: IAuthSwitchStoredUsage): Promise<boolean> {
+    const id = authorityUsageId(context.accountId, context.loginId);
+    const draft: IStoredAuthorityUsage = { id, accountId: context.accountId,
+      loginId: context.loginId, ...next };
+    assertStoredAuthorityUsage(draft);
+    if (!sameUsageSource(context, next.context)
+      || (previousUpdateId !== null && !/^[a-f0-9-]{36}$/.test(previousUpdateId))) {
+      throw new Error('Authority usage publication has an invalid context or predecessor.');
+    }
+    try {
+      return await this.transaction(async session => {
+        const metaStored = await AuthSwitchAuthorityMetaModel.exact.findStoredOne({ id: 'authswitch-authority' }, { session });
+        const accountStored = await AuthSwitchAuthorityAccountModel.exact.findStoredOne({ id: context.accountId }, { session });
+        const grantStored = await AuthSwitchAuthorityGrantModel.exact.findStoredOne({ id: context.loginId }, { session });
+        if (!metaStored || !accountStored || !grantStored || grantStored.accountId !== context.accountId) return false;
+        const actual = usageContext(AuthSwitchAuthorityMetaModel.exact.toPersisted(metaStored),
+          AuthSwitchAuthorityAccountModel.exact.toPersisted(accountStored),
+          AuthSwitchAuthorityGrantModel.exact.toPersisted(grantStored));
+        if (!sameUsageContext(context, actual) || actual.removed) return false;
+        if (actual.providerId === 'openai') {
+          if (actual.owner !== 'daemon' || actual.purpose !== 'openai_managed'
+            || context.nativeSource !== null || !['ready', 'retry_wait'].includes(actual.grantState)) return false;
+        } else if (actual.providerId === 'anthropic' && actual.purpose === 'claude_host_native') {
+          if (actual.owner === 'daemon') {
+            if (context.nativeSource !== null || !['ready', 'retry_wait'].includes(actual.grantState)) return false;
+          } else if (actual.owner === 'claude_native' && actual.grantState === 'native'
+            && context.nativeSource !== null) {
+            const homeStored = await AuthSwitchAuthorityClaudeHomeModel.exact.findStoredOne({
+              id: context.nativeSource.homeId }, { session });
+            if (!homeStored || homeStored.status !== 'ready' || homeStored.pendingOperationId !== null
+              || homeStored.activeAccountId !== context.accountId
+              || homeStored.activeGrantId !== context.loginId) return false;
+          } else return false;
+        } else return false;
+        const current = await AuthSwitchAuthorityUsageModel.exact.findStoredOne({ id }, { session });
+        if (current) {
+          const prior = AuthSwitchAuthorityUsageModel.exact.toPersisted(current);
+          if (sameUsageSource(prior.context, context)
+            ? prior.updateId !== previousUpdateId : previousUpdateId !== null) return false;
+          const changed = await AuthSwitchAuthorityUsageModel.exact.transition({ current,
+            change: model => Object.assign(model, draft) }, { session });
+          if (changed.status !== 'transitioned') return false;
+        } else {
+          if (previousUpdateId !== null) return false;
+          const inserted = await AuthSwitchAuthorityUsageModel.exact.insert(draft, { session });
+          if (inserted.status !== 'inserted') return false;
+        }
+        await this.appendEvent(session, AuthSwitchAuthorityMetaModel.exact.toPersisted(metaStored),
+          next.updateId, 'account', context.accountId);
+        return true;
+      });
+    } catch (error) {
+      if (!(error instanceof plugins.smartdata.SmartdataExactPersistenceError)) throw error;
+      if (error.code === 'unique_conflict') return false;
+      if (error.code !== 'ambiguous_write') throw error;
+      const [stored, event] = await Promise.all([
+        AuthSwitchAuthorityUsageModel.exact.findStoredOne({ id }),
+        AuthSwitchAuthorityEventModel.exact.findStoredOne({ id: next.updateId }),
+      ]);
+      if (stored?.updateId === next.updateId && event?.epoch === context.epoch
+        && event.kind === 'account' && event.accountId === context.accountId
+        && sameUsageSource(stored.context, context)) return true;
+      throw new Error('Authority usage publication outcome is unknown; the provider query must not be replayed.');
+    }
+  }
+
+  public async page(accountAfter: string | null, grantAfter: string | null, bindingAfter: string | null, limit: number): Promise<{
+    meta: IStoredAuthorityMeta; accounts: IStoredAuthorityAccount[]; grants: IStoredAuthorityGrant[];
     bindings: IStoredAuthorityBinding[];
-    nextAccountCursor: string | null; nextBindingCursor: string | null;
+    nextAccountCursor: string | null; nextGrantCursor: string | null; nextBindingCursor: string | null;
   }> {
     if (!Number.isSafeInteger(limit) || limit < 1 || limit > 256) throw new Error('Invalid authority page size.');
     return this.transaction(async session => {
@@ -254,28 +833,128 @@ export class AuthSwitchAuthorityDatabase {
         filter: accountAfter ? { id: { $gt: accountAfter } } : {},
         sort: { id: 1 }, limit: limit + 1, session,
       });
+      const grants = await AuthSwitchAuthorityGrantModel.exact.findStored({
+        filter: grantAfter ? { id: { $gt: grantAfter } } : {},
+        sort: { id: 1 }, limit: limit + 1, session,
+      });
       const bindings = await AuthSwitchAuthorityBindingModel.exact.findStored({
         filter: bindingAfter ? { id: { $gt: bindingAfter } } : {},
         sort: { id: 1 }, limit: limit + 1, session,
       });
       const accountPage = accounts.slice(0, limit).map(item => AuthSwitchAuthorityAccountModel.exact.toPersisted(item));
+      const grantPage = grants.slice(0, limit).map(item => AuthSwitchAuthorityGrantModel.exact.toPersisted(item));
       const bindingPage = bindings.slice(0, limit).map(item => AuthSwitchAuthorityBindingModel.exact.toPersisted(item));
-      const withGrants: Array<{ account: IStoredAuthorityAccount; grant: IStoredAuthorityGrant | null }> = [];
-      for (const account of accountPage) {
-        const stored = account.primaryGrantId
-          ? await AuthSwitchAuthorityGrantModel.exact.findStoredOne({ id: account.primaryGrantId }, { session }) : null;
-        if (account.primaryGrantId && !stored) throw new Error('Authority account primary grant is missing.');
-        withGrants.push({ account, grant: stored ? AuthSwitchAuthorityGrantModel.exact.toPersisted(stored) : null });
-      }
       return {
         meta: AuthSwitchAuthorityMetaModel.exact.toPersisted(meta),
-        accounts: withGrants, bindings: bindingPage,
+        accounts: accountPage, grants: grantPage, bindings: bindingPage,
         nextAccountCursor: accounts.length > limit ? accountPage.at(-1)!.id : null,
+        nextGrantCursor: grants.length > limit ? grantPage.at(-1)!.id : null,
         nextBindingCursor: bindings.length > limit ? bindingPage.at(-1)!.id : null,
       };
     });
   }
 
+  /**
+   * One bounded, repeatable-read diagnostic page. Its metadata revision is authority state,
+   * not a complete change clock for every native-home record.
+   */
+  public async doctorPage(cursors: {
+    accountAfter: string | null;
+    loginAfter: string | null;
+    codexHomeAfter: string | null;
+    claudeHomeAfter: string | null;
+    claudeHandoffAfter: string | null;
+    nativeHandoffAfter: string | null;
+    migrationAfter: string | null;
+  }, limit: number): Promise<{
+    observedAt: string;
+    meta: IStoredAuthorityMeta;
+    accounts: IStoredAuthorityAccount[];
+    logins: IStoredAuthorityGrant[];
+    codexHomes: IStoredAuthorityCodexHome[];
+    claudeHomes: IStoredAuthorityClaudeHome[];
+    claudeHandoffs: IStoredAuthorityClaudeHandoff[];
+    nativeHandoffs: IStoredAuthorityHandoff[];
+    migrations: IStoredAuthorityMigrationLedger[];
+    nextAccountCursor: string | null;
+    nextLoginCursor: string | null;
+    nextCodexHomeCursor: string | null;
+    nextClaudeHomeCursor: string | null;
+    nextClaudeHandoffCursor: string | null;
+    nextNativeHandoffCursor: string | null;
+    nextMigrationCursor: string | null;
+  }> {
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 128) {
+      throw new Error('Invalid authority doctor page size.');
+    }
+    const hashCursor = (value: string | null): boolean => value === null || /^[a-f0-9]{64}$/.test(value);
+    if (![cursors.accountAfter, cursors.loginAfter, cursors.codexHomeAfter, cursors.claudeHomeAfter,
+      cursors.nativeHandoffAfter, cursors.migrationAfter].every(hashCursor)
+      || (cursors.claudeHandoffAfter !== null && !/^[a-f0-9-]{36}$/.test(cursors.claudeHandoffAfter))) {
+      throw new Error('Invalid authority doctor cursor.');
+    }
+    return this.transaction(async session => {
+      const meta = await AuthSwitchAuthorityMetaModel.exact.findStoredOne({ id: 'authswitch-authority' }, { session });
+      if (!meta) throw new Error('Authswitch authority metadata is missing.');
+      const accounts = await AuthSwitchAuthorityAccountModel.exact.findStored({
+        filter: cursors.accountAfter ? { id: { $gt: cursors.accountAfter } } : {},
+        sort: { id: 1 }, limit: limit + 1, session,
+      });
+      const logins = await AuthSwitchAuthorityGrantModel.exact.findStored({
+        filter: cursors.loginAfter ? { id: { $gt: cursors.loginAfter } } : {},
+        sort: { id: 1 }, limit: limit + 1, session,
+      });
+      const codexHomes = await AuthSwitchAuthorityCodexHomeModel.exact.findStored({
+        filter: cursors.codexHomeAfter ? { id: { $gt: cursors.codexHomeAfter } } : {},
+        sort: { id: 1 }, limit: limit + 1, session,
+      });
+      const claudeHomes = await AuthSwitchAuthorityClaudeHomeModel.exact.findStored({
+        filter: cursors.claudeHomeAfter ? { id: { $gt: cursors.claudeHomeAfter } } : {},
+        sort: { id: 1 }, limit: limit + 1, session,
+      });
+      const claudeHandoffs = await AuthSwitchAuthorityClaudeHandoffModel.exact.findStored({
+        filter: cursors.claudeHandoffAfter ? { id: { $gt: cursors.claudeHandoffAfter } } : {},
+        sort: { id: 1 }, limit: limit + 1, session,
+      });
+      const nativeHandoffs = await AuthSwitchAuthorityHandoffModel.exact.findStored({
+        filter: cursors.nativeHandoffAfter ? { id: { $gt: cursors.nativeHandoffAfter } } : {},
+        sort: { id: 1 }, limit: limit + 1, session,
+      });
+      const migrations = await AuthSwitchAuthorityMigrationLedgerModel.exact.findStored({
+        filter: cursors.migrationAfter ? { id: { $gt: cursors.migrationAfter } } : {},
+        sort: { id: 1 }, limit: limit + 1, session,
+      });
+      const accountPage = accounts.slice(0, limit).map(item => AuthSwitchAuthorityAccountModel.exact.toPersisted(item));
+      const loginPage = logins.slice(0, limit).map(item => AuthSwitchAuthorityGrantModel.exact.toPersisted(item));
+      const codexHomePage = codexHomes.slice(0, limit).map(item => AuthSwitchAuthorityCodexHomeModel.exact.toPersisted(item));
+      const claudeHomePage = claudeHomes.slice(0, limit).map(item => AuthSwitchAuthorityClaudeHomeModel.exact.toPersisted(item));
+      const claudeHandoffPage = claudeHandoffs.slice(0, limit)
+        .map(item => AuthSwitchAuthorityClaudeHandoffModel.exact.toPersisted(item));
+      const nativeHandoffPage = nativeHandoffs.slice(0, limit)
+        .map(item => AuthSwitchAuthorityHandoffModel.exact.toPersisted(item));
+      const migrationPage = migrations.slice(0, limit)
+        .map(item => AuthSwitchAuthorityMigrationLedgerModel.exact.toPersisted(item));
+      return {
+        observedAt: new Date().toISOString(),
+        meta: AuthSwitchAuthorityMetaModel.exact.toPersisted(meta),
+        accounts: accountPage,
+        logins: loginPage,
+        codexHomes: codexHomePage,
+        claudeHomes: claudeHomePage,
+        claudeHandoffs: claudeHandoffPage,
+        nativeHandoffs: nativeHandoffPage,
+        migrations: migrationPage,
+        nextAccountCursor: accounts.length > limit ? accountPage.at(-1)!.id : null,
+        nextLoginCursor: logins.length > limit ? loginPage.at(-1)!.id : null,
+        nextCodexHomeCursor: codexHomes.length > limit ? codexHomePage.at(-1)!.id : null,
+        nextClaudeHomeCursor: claudeHomes.length > limit ? claudeHomePage.at(-1)!.id : null,
+        nextClaudeHandoffCursor: claudeHandoffs.length > limit ? claudeHandoffPage.at(-1)!.id : null,
+        nextNativeHandoffCursor: nativeHandoffs.length > limit ? nativeHandoffPage.at(-1)!.id : null,
+        nextMigrationCursor: migrations.length > limit ? migrationPage.at(-1)!.id : null,
+      };
+    });
+  }
+
   public async grantsByState(state: IStoredAuthorityGrant['state'], after: string | null, limit = 128): Promise<IStoredAuthorityGrant[]> {
     this.db();
     if (!Number.isSafeInteger(limit) || limit < 1 || limit > 256) throw new Error('Invalid authority scan size.');
@@ -338,18 +1017,27 @@ export class AuthSwitchAuthorityDatabase {
   }
 
   private async persistGrant(session: TSession, current: Awaited<ReturnType<typeof AuthSwitchAuthorityGrantModel.exact.findStoredOne>>,
-    draft: IStoredAuthorityGrant): Promise<void> {
+    draft: IStoredAuthorityGrant, allowClaudeHandoff = false): Promise<void> {
     assertStoredAuthorityGrant(draft);
     if (current) {
       const prior = AuthSwitchAuthorityGrantModel.exact.toPersisted(current);
       if (draft.id !== prior.id || draft.accountId !== prior.accountId
         || draft.providerId !== prior.providerId || draft.purpose !== prior.purpose
         || draft.audience !== prior.audience) throw new Error('Grant identity cannot change.');
+      if (!allowClaudeHandoff && draft.purpose === 'claude_host_native'
+        && (['handoff_pending', 'handoff_quarantined'].includes(draft.state)
+          || ['handoff_pending', 'handoff_quarantined'].includes(prior.state)
+          || draft.owner !== prior.owner)) {
+        throw new Error('Claude native ownership requires the two-grant handoff transaction.');
+      }
       const result = await AuthSwitchAuthorityGrantModel.exact.transition({
         current, change: model => Object.assign(model, draft),
       }, { session });
       if (result.status !== 'transitioned') throw new Error('Grant changed concurrently.');
     } else {
+      if (!allowClaudeHandoff && ['handoff_pending', 'handoff_quarantined'].includes(draft.state)) {
+        throw new Error('Claude handoff cannot begin with an unassigned grant.');
+      }
       const result = await AuthSwitchAuthorityGrantModel.exact.insert(draft, { session });
       if (result.status !== 'inserted') throw new Error('Grant was added concurrently.');
     }
@@ -398,6 +1086,75 @@ export class AuthSwitchAuthorityDatabase {
     }
   }
 
+  /** Device-login result, account and grant are one commit; a lost RPC response remains discoverable by operation ID. */
+  public async commitLoginOperation(updateId: string, operationId: string, accountId: string, grantId: string,
+    change: (account: IStoredAuthorityAccount | null, grant: IStoredAuthorityGrant | null) => {
+      account: IStoredAuthorityAccount; grant: IStoredAuthorityGrant;
+    }): Promise<{ account: IStoredAuthorityAccount; grant: IStoredAuthorityGrant; operation: IStoredAuthorityDeviceOperation }> {
+    try {
+      return await this.transaction(async session => {
+        const metaStored = await AuthSwitchAuthorityMetaModel.exact.findStoredOne({ id: 'authswitch-authority' }, { session });
+        const operationStored = await AuthSwitchAuthorityOperationModel.exact.findStoredOne({ id: operationId }, { session });
+        if (!metaStored || !operationStored) throw new Error('Device operation is unavailable.');
+        const operation = storedOperation(operationStored);
+        if (operation.kind === 'preuse_openai' || operation.state !== 'committing' || operation.commitId !== updateId
+          || (operation.kind === 'reauth_openai' && (operation.accountId !== accountId || operation.grantId !== grantId))) {
+          throw new Error('Device operation is not admitted for this login.');
+        }
+        const accountStored = await AuthSwitchAuthorityAccountModel.exact.findStoredOne({ id: accountId }, { session });
+        const grantStored = await AuthSwitchAuthorityGrantModel.exact.findStoredOne({ id: grantId }, { session });
+        const oldGrant = grantStored ? AuthSwitchAuthorityGrantModel.exact.toPersisted(grantStored) : null;
+        if (operation.kind === 'reauth_openai' && oldGrant?.grantGeneration !== operation.expectedGrantGeneration) {
+          throw new Error('Login changed while device reauthentication was pending.');
+        }
+        const draft = change(
+          accountStored ? structuredClone(AuthSwitchAuthorityAccountModel.exact.toPersisted(accountStored)) : null,
+          oldGrant ? structuredClone(oldGrant) : null);
+        if (draft.account.id !== accountId || draft.grant.id !== grantId || draft.grant.accountId !== accountId
+          || draft.account.primaryGrantId !== grantId || draft.account.providerId !== draft.grant.providerId
+          || draft.account.updateId !== updateId || draft.grant.updateId !== updateId) {
+          throw new Error('Device login account/grant change has an invalid identity.');
+        }
+        if (accountStored && accountStored.primaryGrantId !== grantId) {
+          throw new Error('Primary grant identity cannot be replaced.');
+        }
+        if (grantStored && ['legacy_native', 'claude_native'].includes(grantStored.owner)
+          && draft.grant.owner === 'daemon') {
+          throw new Error('Native ownership requires a verified handoff.');
+        }
+        const completed: IStoredAuthorityDeviceOperation = {
+          ...operation, state: 'complete', prompt: null,
+          result: { accountId, grantId, accountRevision: draft.account.revision,
+            grantGeneration: draft.grant.grantGeneration },
+          error: null, updatedAt: draft.account.statusObservedAt, finishedAt: draft.account.statusObservedAt,
+          revision: operation.revision + 1, updateId,
+        };
+        assertStoredAuthorityOperation(completed);
+        await this.persistAccount(session, accountStored, draft.account);
+        await this.persistGrant(session, grantStored, draft.grant);
+        const transitioned = await AuthSwitchAuthorityOperationModel.exact.transition({
+          current: operationStored, change: model => Object.assign(model, completed),
+        }, { session });
+        if (transitioned.status !== 'transitioned') throw new Error('Device operation changed concurrently.');
+        await this.appendEvent(session, AuthSwitchAuthorityMetaModel.exact.toPersisted(metaStored),
+          updateId, 'account', accountId);
+        return { ...draft, operation: completed };
+      });
+    } catch (error) {
+      if (!(error instanceof plugins.smartdata.SmartdataExactPersistenceError) || error.code !== 'ambiguous_write') throw error;
+      const [event, operation, pair] = await Promise.all([
+        AuthSwitchAuthorityEventModel.exact.findStoredOne({ id: updateId }),
+        this.readOperation(operationId), this.readAccountAndPrimaryGrant(accountId),
+      ]);
+      if (event && operation?.kind !== 'preuse_openai' && operation?.state === 'complete' && operation.updateId === updateId
+        && pair.account?.updateId === updateId && pair.grant?.updateId === updateId
+        && operation.result?.accountId === accountId && operation.result.grantId === grantId) {
+        return { account: pair.account, grant: pair.grant, operation };
+      }
+      throw new Error('Device login commit outcome is unknown; inspect the durable operation before retrying.');
+    }
+  }
+
   /** Grant transition and public account revision share a transaction and one event. */
   public async changeGrant(updateId: string, grantId: string,
     change: (grant: IStoredAuthorityGrant, account: IStoredAuthorityAccount) => IStoredAuthorityGrant): Promise<{
@@ -416,6 +1173,11 @@ export class AuthSwitchAuthorityDatabase {
         if (draft.id !== grantId || draft.accountId !== account.id || draft.updateId !== updateId) {
           throw new Error('Grant change has an invalid identity.');
         }
+        if (grant.purpose === 'claude_host_native' && draft.state === 'exchange_may_have_been_sent'
+          && grant.state !== 'exchange_may_have_been_sent'
+          && !(await this.hasVerifiedClaudeGrantReceipt(account.id, grant.id, session))) {
+          throw new Error('Claude refresh requires a verified import and backup receipt.');
+        }
         const accountDraft: IStoredAuthorityAccount = { ...account, revision: account.revision + 1,
           statusObservedAt: draft.statusObservedAt, updateId };
         await this.persistGrant(session, grantStored, draft);
@@ -504,6 +1266,9 @@ export class AuthSwitchAuthorityDatabase {
           if (grant.state === 'exchange_may_have_been_sent') {
             throw new Error('Wait for the account refresh to finish before removing it.');
           }
+          if (['handoff_pending', 'handoff_quarantined'].includes(grant.state)) {
+            throw new Error('Resolve the Claude native handoff before removing this account.');
+          }
         });
         await scan(async (grant, stored) => {
           if (grant.state === 'removed') return;
@@ -584,7 +1349,7 @@ export class AuthSwitchAuthorityDatabase {
     }
   }
 
-  public async changeBinding(updateId: string, bindingId: string, accountId: string,
+  public async changeBinding(updateId: string, bindingId: string, accountId: string, grantId: string,
     change: (draft: IStoredAuthorityBinding | null, account: IStoredAuthorityAccount,
       grant: IStoredAuthorityGrant | null) => IStoredAuthorityBinding): Promise<{
       meta: IStoredAuthorityMeta; binding: IStoredAuthorityBinding;
@@ -595,13 +1360,14 @@ export class AuthSwitchAuthorityDatabase {
         const accountStored = await AuthSwitchAuthorityAccountModel.exact.findStoredOne({ id: accountId }, { session });
         if (!metaStored || !accountStored) throw new Error('Account is not available for this runtime.');
         const account = AuthSwitchAuthorityAccountModel.exact.toPersisted(accountStored);
-        const grantStored = account.primaryGrantId
-          ? await AuthSwitchAuthorityGrantModel.exact.findStoredOne({ id: account.primaryGrantId }, { session }) : null;
+        const grantStored = await AuthSwitchAuthorityGrantModel.exact.findStoredOne({ id: grantId }, { session });
         const grant = grantStored ? AuthSwitchAuthorityGrantModel.exact.toPersisted(grantStored) : null;
         const current = await AuthSwitchAuthorityBindingModel.exact.findStoredOne({ id: bindingId }, { session });
         const draft = change(current ? structuredClone(AuthSwitchAuthorityBindingModel.exact.toPersisted(current)) : null, account, grant);
         if (draft.id !== bindingId || draft.accountId !== accountId || draft.updateId !== updateId) throw new Error('Binding change has an invalid identity.');
-        if (draft.grantId !== grant?.id) throw new Error('Binding grant does not belong to the account.');
+        if (draft.grantId !== grantId || grant?.accountId !== accountId) {
+          throw new Error('Binding login does not belong to the account.');
+        }
         if (current && (draft.runtime !== current.runtime || draft.scopeId !== current.scopeId)) {
           throw new Error('Runtime binding identity cannot change.');
         }
@@ -628,14 +1394,15 @@ export class AuthSwitchAuthorityDatabase {
     }
   }
 
-  /** Closing an owned runtime revokes only its exact capability/incarnation. */
-  public async revokeBinding(updateId: string, bindingId: string, capabilityHash: string): Promise<boolean> {
+  private async revokeBindingExact(updateId: string, bindingId: string, capabilityHash: string,
+    externalOnly: boolean): Promise<boolean> {
     try {
       return await this.transaction(async session => {
         const metaStored = await AuthSwitchAuthorityMetaModel.exact.findStoredOne({ id: 'authswitch-authority' }, { session });
         if (!metaStored) throw new Error('Authswitch authority metadata is missing.');
         const current = await AuthSwitchAuthorityBindingModel.exact.findStoredOne({ id: bindingId }, { session });
-        if (!current || current.capabilityHash !== capabilityHash) return false;
+        if (!current || current.capabilityHash !== capabilityHash
+          || (externalOnly && !['flex', 'opencode'].includes(current.runtime))) return false;
         const result = await AuthSwitchAuthorityBindingModel.exact.delete({ current }, { session });
         if (result.status !== 'deleted') throw new Error('Runtime binding changed during revocation.');
         await this.appendEvent(session, AuthSwitchAuthorityMetaModel.exact.toPersisted(metaStored),
@@ -645,11 +1412,24 @@ export class AuthSwitchAuthorityDatabase {
     } catch (error) {
       if (!(error instanceof plugins.smartdata.SmartdataExactPersistenceError) || error.code !== 'ambiguous_write') throw error;
       const event = await AuthSwitchAuthorityEventModel.exact.findStoredOne({ id: updateId });
-      if (event && !(await this.readBinding(bindingId))) return true;
+      const binding = await this.readBinding(bindingId);
+      // Every bind mints a fresh random capability. An event plus absence or a different
+      // capability therefore proves that this exact deletion committed before any successor.
+      if (event && (!binding || binding.capabilityHash !== capabilityHash)) return true;
       throw new Error('Authswitch binding revocation outcome is unknown.');
     }
   }
 
+  /** Closing an authority-owned runtime revokes its exact capability after owned cleanup. */
+  public revokeBinding(updateId: string, bindingId: string, capabilityHash: string): Promise<boolean> {
+    return this.revokeBindingExact(updateId, bindingId, capabilityHash, false);
+  }
+
+  /** External callers can release only Flex/OpenCode bindings; managed Codex cleanup stays daemon-owned. */
+  public releaseExternalBinding(updateId: string, bindingId: string, capabilityHash: string): Promise<boolean> {
+    return this.revokeBindingExact(updateId, bindingId, capabilityHash, true);
+  }
+
   /** Enrollment metadata is sealed by the caller and cannot become detached from an account. */
   public async changeEnrollment(updateId: string, enrollmentId: string, accountId: string,
     change: (current: IStoredAuthorityEnrollment | null) => IStoredAuthorityEnrollment): Promise<IStoredAuthorityEnrollment> {
@@ -769,6 +1549,317 @@ export class AuthSwitchAuthorityDatabase {
     }
   }
 
+  public async readClaudeHome(homeId: string): Promise<IStoredAuthorityClaudeHome | null> {
+    this.db();
+    if (!/^[a-f0-9]{64}$/.test(homeId)) throw new Error('Invalid Claude home selector.');
+    const stored = await AuthSwitchAuthorityClaudeHomeModel.exact.findStoredOne({ id: homeId });
+    return stored ? AuthSwitchAuthorityClaudeHomeModel.exact.toPersisted(stored) : null;
+  }
+
+  public async readClaudeHandoff(operationId: string): Promise<IStoredAuthorityClaudeHandoff | null> {
+    this.db();
+    if (!/^[a-f0-9-]{36}$/.test(operationId)) throw new Error('Invalid Claude handoff selector.');
+    const stored = await AuthSwitchAuthorityClaudeHandoffModel.exact.findStoredOne({ id: operationId });
+    return stored ? AuthSwitchAuthorityClaudeHandoffModel.exact.toPersisted(stored) : null;
+  }
+
+  /** A backed-up backend import receipt, not an account snapshot, authorizes an inactive Claude grant. */
+  public async hasVerifiedClaudeGrantReceipt(accountId: string, grantId: string,
+    session?: TSession): Promise<boolean> {
+    this.db();
+    if (!/^[a-f0-9]{64}$/.test(accountId) || !/^[a-f0-9]{64}$/.test(grantId)) {
+      throw new Error('Invalid Claude grant receipt selector.');
+    }
+    for (const status of ['verified', 'complete'] as const) {
+      const stored = await AuthSwitchAuthorityMigrationLedgerModel.exact.findStored({
+        filter: { grantId, status }, sort: { id: 1 }, limit: 128, session,
+      });
+      if (stored.some(item => item.accountId === accountId
+        && item.backupDigest !== null
+        && ['authswitch_stash', 'authswitch_backup', 'claude_native'].includes(item.sourceKind))) return true;
+      if (stored.length === 128) throw new Error('Claude grant has too many migration receipts to verify.');
+    }
+    return false;
+  }
+
+  public async claudeHandoffsByPhase(phase: IStoredAuthorityClaudeHandoff['phase'],
+    after: string | null): Promise<IStoredAuthorityClaudeHandoff[]> {
+    this.db();
+    if (!['reserved', 'prepared', 'quarantined'].includes(phase)
+      || (after !== null && !/^[a-f0-9-]{36}$/.test(after))) throw new Error('Invalid Claude handoff scan.');
+    const stored = await AuthSwitchAuthorityClaudeHandoffModel.exact.findStored({
+      filter: after === null ? { phase } : { phase, id: { $gt: after } },
+      sort: { id: 1 }, limit: 128,
+    });
+    return stored.map(item => AuthSwitchAuthorityClaudeHandoffModel.exact.toPersisted(item));
+  }
+
+  public async claudeHandoffsPage(after: string | null, limit = 128): Promise<{
+    handoffs: IStoredAuthorityClaudeHandoff[]; nextCursor: string | null;
+  }> {
+    this.db();
+    if ((after !== null && !/^[a-f0-9-]{36}$/.test(after))
+      || !Number.isSafeInteger(limit) || limit < 1 || limit > 256) throw new Error('Invalid Claude handoff page.');
+    const stored = await AuthSwitchAuthorityClaudeHandoffModel.exact.findStored({
+      filter: after === null ? {} : { id: { $gt: after } }, sort: { id: 1 }, limit: limit + 1,
+    });
+    const handoffs = stored.slice(0, limit).map(item => AuthSwitchAuthorityClaudeHandoffModel.exact.toPersisted(item));
+    return { handoffs, nextCursor: stored.length > limit ? handoffs.at(-1)!.id : null };
+  }
+
+  /** Only a verified backend import receipt may adopt a native home. No startup autodiscovery exists. */
+  public async registerClaudeHomeFromReceipt(input: { homeId: string; accountId: string; grantId: string;
+    receiptId: string; sourceDigest: string; accountUuid: string; organizationUuid: string;
+    updateId: string; now: string }): Promise<IStoredAuthorityClaudeHome> {
+    const { homeId, accountId, grantId, receiptId, sourceDigest, updateId } = input;
+    for (const value of [homeId, accountId, grantId, receiptId, sourceDigest]) {
+      if (!/^[a-f0-9]{64}$/.test(value)) throw new Error('Invalid verified Claude home identity.');
+    }
+    if (!/^[a-f0-9-]{36}$/.test(updateId)) throw new Error('Invalid Claude home update identity.');
+    try {
+      return await this.transaction(async session => {
+        const receiptStored = await AuthSwitchAuthorityMigrationLedgerModel.exact.findStoredOne({ id: receiptId }, { session });
+        const accountStored = await AuthSwitchAuthorityAccountModel.exact.findStoredOne({ id: accountId }, { session });
+        const grantStored = await AuthSwitchAuthorityGrantModel.exact.findStoredOne({ id: grantId }, { session });
+        const current = await AuthSwitchAuthorityClaudeHomeModel.exact.findStoredOne({ id: homeId }, { session });
+        if (!receiptStored || !['verified', 'complete'].includes(receiptStored.status)
+          || receiptStored.backupDigest === null
+          || receiptStored.sourceKind !== 'claude_native' || receiptStored.sourcePathHash !== homeId
+          || receiptStored.sourceDigest !== sourceDigest || receiptStored.accountId !== accountId
+          || receiptStored.grantId !== grantId || !accountStored || accountStored.removed
+          || accountStored.providerId !== 'anthropic' || accountStored.subject !== input.accountUuid
+          || accountStored.workspaceId !== input.organizationUuid || !grantStored
+          || grantStored.accountId !== accountId || grantStored.purpose !== 'claude_host_native'
+          || grantStored.owner !== 'claude_native' || grantStored.state !== 'native'
+          || grantStored.ciphertext !== null) {
+          throw new Error('Verified Claude native source mapping is unavailable.');
+        }
+        if (current) {
+          if (current.activeAccountId !== accountId || current.activeGrantId !== grantId) {
+            throw new Error('Claude native home belongs to another grant.');
+          }
+          return AuthSwitchAuthorityClaudeHomeModel.exact.toPersisted(current);
+        }
+        const home: IStoredAuthorityClaudeHome = { id: homeId, activeAccountId: accountId,
+          activeGrantId: grantId, pendingOperationId: null, status: 'ready', revision: 1,
+          createdAt: input.now, updateId };
+        assertStoredAuthorityClaudeHome(home);
+        const inserted = await AuthSwitchAuthorityClaudeHomeModel.exact.insert(home, { session });
+        if (inserted.status !== 'inserted') throw new Error('Claude native home changed concurrently.');
+        return home;
+      });
+    } catch (error) {
+      if (!(error instanceof plugins.smartdata.SmartdataExactPersistenceError)
+        || !['ambiguous_write', 'unique_conflict'].includes(error.code)) throw error;
+      const home = await this.readClaudeHome(homeId);
+      if (home?.updateId === updateId && home.activeAccountId === accountId && home.activeGrantId === grantId) return home;
+      throw new Error('Claude native home registration outcome is unknown.');
+    }
+  }
+
+  public async readClaudeHandoffContext(operationId: string): Promise<{
+    handoff: IStoredAuthorityClaudeHandoff; home: IStoredAuthorityClaudeHome;
+    outgoing: IStoredAuthorityGrant; incoming: IStoredAuthorityGrant;
+    outgoingAccount: IStoredAuthorityAccount; incomingAccount: IStoredAuthorityAccount;
+  } | null> {
+    if (!/^[a-f0-9-]{36}$/.test(operationId)) throw new Error('Invalid Claude handoff selector.');
+    return this.transaction(async session => {
+      const stored = await AuthSwitchAuthorityClaudeHandoffModel.exact.findStoredOne({ id: operationId }, { session });
+      if (!stored) return null;
+      const handoff = AuthSwitchAuthorityClaudeHandoffModel.exact.toPersisted(stored);
+      const homeStored = await AuthSwitchAuthorityClaudeHomeModel.exact.findStoredOne({ id: handoff.homeId }, { session });
+      const outgoingStored = await AuthSwitchAuthorityGrantModel.exact.findStoredOne({ id: handoff.outgoingGrantId }, { session });
+      const incomingStored = await AuthSwitchAuthorityGrantModel.exact.findStoredOne({ id: handoff.incomingGrantId }, { session });
+      const outgoingAccountStored = await AuthSwitchAuthorityAccountModel.exact.findStoredOne({ id: handoff.outgoingAccountId }, { session });
+      const incomingAccountStored = await AuthSwitchAuthorityAccountModel.exact.findStoredOne({ id: handoff.incomingAccountId }, { session });
+      if (!homeStored || !outgoingStored || !incomingStored || !outgoingAccountStored || !incomingAccountStored) {
+        throw new Error('Claude handoff references a missing authority record.');
+      }
+      return { handoff,
+        home: AuthSwitchAuthorityClaudeHomeModel.exact.toPersisted(homeStored),
+        outgoing: AuthSwitchAuthorityGrantModel.exact.toPersisted(outgoingStored),
+        incoming: AuthSwitchAuthorityGrantModel.exact.toPersisted(incomingStored),
+        outgoingAccount: AuthSwitchAuthorityAccountModel.exact.toPersisted(outgoingAccountStored),
+        incomingAccount: AuthSwitchAuthorityAccountModel.exact.toPersisted(incomingAccountStored) };
+    });
+  }
+
+  /** One phase advances both grants, home, journal and both account events atomically. */
+  public async changeClaudeHandoff(input: { operationId: string; homeId: string; incomingGrantId: string;
+    updateId: string; eventIds: readonly [string, string];
+    change: (current: {
+      home: IStoredAuthorityClaudeHome; handoff: IStoredAuthorityClaudeHandoff | null;
+      outgoing: IStoredAuthorityGrant; incoming: IStoredAuthorityGrant;
+      outgoingAccount: IStoredAuthorityAccount; incomingAccount: IStoredAuthorityAccount;
+    }) => TClaudeHandoffDraft }): Promise<TClaudeHandoffDraft> {
+    const { operationId, homeId, incomingGrantId, updateId, eventIds } = input;
+    if (!/^[a-f0-9-]{36}$/.test(operationId) || !/^[a-f0-9]{64}$/.test(homeId)
+      || !/^[a-f0-9]{64}$/.test(incomingGrantId)
+      || ![updateId, ...eventIds].every(value => /^[a-f0-9-]{36}$/.test(value))
+      || new Set([updateId, ...eventIds]).size !== 3) throw new Error('Invalid Claude handoff identity.');
+    let expectedPhase: IStoredAuthorityClaudeHandoff['phase'] | null = null;
+    try {
+      return await this.transaction(async session => {
+        const metaStored = await AuthSwitchAuthorityMetaModel.exact.findStoredOne({ id: 'authswitch-authority' }, { session });
+        const homeStored = await AuthSwitchAuthorityClaudeHomeModel.exact.findStoredOne({ id: homeId }, { session });
+        const handoffStored = await AuthSwitchAuthorityClaudeHandoffModel.exact.findStoredOne({ id: operationId }, { session });
+        if (!metaStored || !homeStored) throw new Error('Verified Claude home is unavailable.');
+        const home = AuthSwitchAuthorityClaudeHomeModel.exact.toPersisted(homeStored);
+        const handoff = handoffStored ? AuthSwitchAuthorityClaudeHandoffModel.exact.toPersisted(handoffStored) : null;
+        if (home.status !== 'ready' || (handoff === null ? home.pendingOperationId !== null
+          : home.pendingOperationId !== operationId || handoff.homeId !== homeId
+            || handoff.incomingGrantId !== incomingGrantId)) {
+          throw new Error('Claude home has another pending or quarantined operation.');
+        }
+        const outgoingId = handoff?.outgoingGrantId ?? home.activeGrantId;
+        if (outgoingId === incomingGrantId) throw new Error('Claude home already owns the selected grant.');
+        const outgoingStored = await AuthSwitchAuthorityGrantModel.exact.findStoredOne({ id: outgoingId }, { session });
+        const incomingStored = await AuthSwitchAuthorityGrantModel.exact.findStoredOne({ id: incomingGrantId }, { session });
+        if (!outgoingStored || !incomingStored) throw new Error('Claude handoff grant is unavailable.');
+        const outgoing = AuthSwitchAuthorityGrantModel.exact.toPersisted(outgoingStored);
+        const incoming = AuthSwitchAuthorityGrantModel.exact.toPersisted(incomingStored);
+        const incomingHome = await AuthSwitchAuthorityClaudeHomeModel.exact.findStoredOne({
+          activeGrantId: incomingGrantId,
+        }, { session });
+        if (incomingHome && incomingHome.id !== homeId) {
+          throw new Error('Claude grant is already active in another native home.');
+        }
+        const outgoingAccountStored = await AuthSwitchAuthorityAccountModel.exact.findStoredOne({ id: outgoing.accountId }, { session });
+        const incomingAccountStored = await AuthSwitchAuthorityAccountModel.exact.findStoredOne({ id: incoming.accountId }, { session });
+        if (!outgoingAccountStored || !incomingAccountStored || outgoingAccountStored.removed || incomingAccountStored.removed
+          || outgoing.accountId === incoming.accountId || outgoing.providerId !== 'anthropic'
+          || incoming.providerId !== 'anthropic' || outgoing.purpose !== 'claude_host_native'
+          || incoming.purpose !== 'claude_host_native' || home.activeGrantId !== outgoing.id
+          || home.activeAccountId !== outgoing.accountId) throw new Error('Claude handoff account identity is invalid.');
+        const outgoingAccount = AuthSwitchAuthorityAccountModel.exact.toPersisted(outgoingAccountStored);
+        const incomingAccount = AuthSwitchAuthorityAccountModel.exact.toPersisted(incomingAccountStored);
+        const draft = input.change({ home: structuredClone(home), handoff: handoff ? structuredClone(handoff) : null,
+          outgoing: structuredClone(outgoing), incoming: structuredClone(incoming),
+          outgoingAccount: structuredClone(outgoingAccount), incomingAccount: structuredClone(incomingAccount) });
+        expectedPhase = draft.handoff.phase;
+        assertStoredAuthorityClaudeHome(draft.home);
+        assertStoredAuthorityClaudeHandoff(draft.handoff);
+        if (draft.home.id !== homeId || draft.home.createdAt !== home.createdAt
+          || draft.home.revision !== home.revision + 1 || draft.home.updateId !== updateId
+          || draft.handoff.id !== operationId || draft.handoff.homeId !== homeId
+          || draft.handoff.outgoingAccountId !== outgoing.accountId || draft.handoff.outgoingGrantId !== outgoing.id
+          || draft.handoff.incomingAccountId !== incoming.accountId || draft.handoff.incomingGrantId !== incoming.id
+          || draft.handoff.sourceIdentity.accountUuid !== outgoingAccount.subject
+          || draft.handoff.sourceIdentity.organizationUuid !== outgoingAccount.workspaceId
+          || draft.handoff.targetIdentity.accountUuid !== incomingAccount.subject
+          || draft.handoff.targetIdentity.organizationUuid !== incomingAccount.workspaceId
+          || draft.handoff.revision !== (handoff?.revision ?? 0) + 1 || draft.handoff.updateId !== updateId
+          || draft.outgoing.id !== outgoing.id || draft.incoming.id !== incoming.id
+          || draft.outgoing.accountId !== outgoing.accountId || draft.incoming.accountId !== incoming.accountId
+          || draft.outgoing.updateId !== updateId || draft.incoming.updateId !== updateId
+          || draft.outgoing.revision !== outgoing.revision + 1 || draft.incoming.revision !== incoming.revision + 1) {
+          throw new Error('Claude handoff changed an immutable identity or revision.');
+        }
+        if (handoff && (draft.handoff.startedAt !== handoff.startedAt
+          || JSON.stringify(draft.handoff.sourceIdentity) !== JSON.stringify(handoff.sourceIdentity)
+          || JSON.stringify(draft.handoff.targetIdentity) !== JSON.stringify(handoff.targetIdentity)
+          || (handoff.phase !== 'reserved' && (JSON.stringify(draft.handoff.before) !== JSON.stringify(handoff.before)
+            || JSON.stringify(draft.handoff.after) !== JSON.stringify(handoff.after)
+            || draft.handoff.sourceAccessDigest !== handoff.sourceAccessDigest
+            || draft.handoff.targetAccessDigest !== handoff.targetAccessDigest)))) {
+          throw new Error('Claude handoff proof or identity changed.');
+        }
+        if (!handoff) {
+          let verifiedIncoming = false;
+          for (const status of ['verified', 'complete'] as const) {
+            const receipts = await AuthSwitchAuthorityMigrationLedgerModel.exact.findStored({
+              filter: { grantId: incoming.id, status }, sort: { id: 1 }, limit: 128, session,
+            });
+            if (receipts.length === 128) throw new Error('Claude grant receipt set is unbounded.');
+            verifiedIncoming ||= receipts.some(item => item.accountId === incoming.accountId
+              && item.backupDigest !== null
+              && ['authswitch_stash', 'authswitch_backup', 'claude_native'].includes(item.sourceKind));
+          }
+          if (draft.handoff.phase !== 'reserved' || home.pendingOperationId !== null
+            || !verifiedIncoming
+            || outgoing.state !== 'native' || outgoing.owner !== 'claude_native' || outgoing.ciphertext !== null
+            || incoming.state !== 'ready' || incoming.owner !== 'daemon' || incoming.ciphertext === null
+            || draft.home.activeGrantId !== outgoing.id || draft.home.pendingOperationId !== operationId
+            || draft.home.status !== 'ready' || draft.outgoing.state !== 'native'
+            || draft.outgoing.owner !== 'claude_native' || draft.outgoing.ciphertext !== null
+            || draft.incoming.state !== 'handoff_pending' || draft.incoming.owner !== 'daemon'
+            || draft.incoming.ciphertext !== incoming.ciphertext) throw new Error('Claude handoff reservation is invalid.');
+        } else if (handoff.phase === 'reserved' && draft.handoff.phase === 'prepared') {
+          if (outgoing.state !== 'native' || incoming.state !== 'handoff_pending'
+            || draft.outgoing.state !== 'handoff_pending' || draft.outgoing.owner !== 'claude_native'
+            || draft.outgoing.ciphertext !== null || draft.incoming.state !== 'handoff_pending'
+            || draft.incoming.owner !== 'daemon' || draft.incoming.ciphertext !== incoming.ciphertext
+            || draft.home.activeGrantId !== outgoing.id || draft.home.pendingOperationId !== operationId
+            || draft.home.status !== 'ready') throw new Error('Claude handoff preparation is invalid.');
+        } else if (handoff.phase === 'prepared' && draft.handoff.phase === 'committed') {
+          if (outgoing.state !== 'handoff_pending' || incoming.state !== 'handoff_pending'
+            || draft.outgoing.state !== 'ready' || draft.outgoing.owner !== 'daemon'
+            || draft.outgoing.ciphertext !== handoff.sealedOutgoing
+            || draft.incoming.state !== 'native' || draft.incoming.owner !== 'claude_native'
+            || draft.incoming.ciphertext !== null || draft.home.activeAccountId !== incoming.accountId
+            || draft.home.activeGrantId !== incoming.id || draft.home.pendingOperationId !== null
+            || draft.home.status !== 'ready' || draft.handoff.sealedOutgoing !== null) {
+            throw new Error('Claude handoff completion is invalid.');
+          }
+        } else if (['reserved', 'prepared'].includes(handoff.phase)
+          && draft.handoff.phase === 'aborted') {
+          if (incoming.state !== 'handoff_pending' || draft.incoming.state !== 'ready'
+            || draft.incoming.owner !== 'daemon' || draft.incoming.ciphertext !== incoming.ciphertext
+            || draft.outgoing.state !== 'native' || draft.outgoing.owner !== 'claude_native'
+            || draft.outgoing.ciphertext !== null || draft.home.activeGrantId !== outgoing.id
+            || draft.home.pendingOperationId !== null || draft.home.status !== 'ready'
+            || draft.handoff.sealedOutgoing !== null) throw new Error('Claude handoff abort is invalid.');
+        } else if (['reserved', 'prepared'].includes(handoff.phase)
+          && draft.handoff.phase === 'quarantined') {
+          if (draft.outgoing.state !== 'handoff_quarantined' || draft.outgoing.owner !== 'claude_native'
+            || draft.incoming.state !== 'handoff_quarantined' || draft.incoming.owner !== 'daemon'
+            || draft.home.activeGrantId !== outgoing.id || draft.home.pendingOperationId !== operationId
+            || draft.home.status !== 'quarantined' || draft.handoff.problem === 'none') {
+            throw new Error('Claude handoff quarantine is invalid.');
+          }
+        } else throw new Error('Claude handoff phase transition is invalid.');
+        await this.persistGrant(session, outgoingStored, draft.outgoing, true);
+        await this.persistGrant(session, incomingStored, draft.incoming, true);
+        const homeResult = await AuthSwitchAuthorityClaudeHomeModel.exact.transition({ current: homeStored,
+          change: model => Object.assign(model, draft.home) }, { session });
+        if (homeResult.status !== 'transitioned') throw new Error('Claude home changed concurrently.');
+        if (handoffStored) {
+          const result = await AuthSwitchAuthorityClaudeHandoffModel.exact.transition({ current: handoffStored,
+            change: model => Object.assign(model, draft.handoff) }, { session });
+          if (result.status !== 'transitioned') throw new Error('Claude handoff changed concurrently.');
+        } else {
+          const result = await AuthSwitchAuthorityClaudeHandoffModel.exact.insert(draft.handoff, { session });
+          if (result.status !== 'inserted') throw new Error('Claude handoff operation already exists.');
+        }
+        const outgoingAccountDraft = { ...outgoingAccount, revision: outgoingAccount.revision + 1,
+          statusObservedAt: draft.handoff.updatedAt, updateId };
+        const incomingAccountDraft = { ...incomingAccount, revision: incomingAccount.revision + 1,
+          statusObservedAt: draft.handoff.updatedAt, updateId };
+        await this.persistAccount(session, outgoingAccountStored, outgoingAccountDraft);
+        await this.persistAccount(session, incomingAccountStored, incomingAccountDraft);
+        const first = await this.appendEvent(session, AuthSwitchAuthorityMetaModel.exact.toPersisted(metaStored),
+          eventIds[0], 'account', outgoing.accountId);
+        await this.appendEvent(session, first, eventIds[1], 'account', incoming.accountId);
+        return draft;
+      });
+    } catch (error) {
+      if (!(error instanceof plugins.smartdata.SmartdataExactPersistenceError) || error.code !== 'ambiguous_write') throw error;
+      const context = await this.readClaudeHandoffContext(operationId);
+      const first = await AuthSwitchAuthorityEventModel.exact.findStoredOne({ id: eventIds[0] });
+      const second = await AuthSwitchAuthorityEventModel.exact.findStoredOne({ id: eventIds[1] });
+      if (context && context.handoff.phase === expectedPhase
+        && [context.handoff, context.home, context.outgoing, context.incoming,
+          context.outgoingAccount, context.incomingAccount].every(item => item.updateId === updateId)
+        && first?.accountId === context.outgoing.accountId
+        && second?.accountId === context.incoming.accountId && first.epoch === second.epoch
+        && second.revision === first.revision + 1) {
+        return { handoff: context.handoff, home: context.home,
+          outgoing: context.outgoing, incoming: context.incoming };
+      }
+      throw new Error('Claude handoff database outcome is unknown; native ownership remains blocked.');
+    }
+  }
+
   /** Ledger transitions never silently replace an active credential or waive backup proof. */
   public async changeMigrationLedger(updateId: string, ledgerId: string,
     change: (current: IStoredAuthorityMigrationLedger | null) => IStoredAuthorityMigrationLedger): Promise<IStoredAuthorityMigrationLedger> {
@@ -806,6 +1897,7 @@ export class AuthSwitchAuthorityDatabase {
 
   public async stop(): Promise<void> {
     this.started = false;
+    this.mode = null;
     const database = this.database;
     const engine = this.engine;
     this.database = undefined;