@modelprofile.com/authswitch 6.4.0 → 7.0.0

package/ts/classes.authoritymodels.ts

@@ -1,7 +1,11 @@
 import * as plugins from './plugins.js';
+import type { TAuthSwitchLoginPrompt } from './authority-contract.js';
+import type { IAuthSwitchStoredUsage } from './classes.authorityusage.js';
 
 export interface IStoredAuthorityMeta {
   id: 'authswitch-authority';
+  schemaVersion: 2;
+  admission: 'open' | 'closed_restored';
   epoch: string;
   revision: number;
   updateId: string;
@@ -34,7 +38,7 @@ export interface IStoredAuthorityGrant {
   providerId: string;
   purpose: TStoredGrantPurpose;
   audience: string;
-  state: 'ready' | 'exchange_may_have_been_sent' | 'retry_wait' | 'needs_reauth' | 'native' | 'legacy_native_pending' | 'removed';
+  state: 'ready' | 'exchange_may_have_been_sent' | 'retry_wait' | 'needs_reauth' | 'native' | 'legacy_native_pending' | 'handoff_pending' | 'handoff_quarantined' | 'removed';
   owner: 'daemon' | 'claude_native' | 'legacy_native' | 'none';
   grantGeneration: number;
   authorizationGeneration: number;
@@ -49,6 +53,16 @@ export interface IStoredAuthorityGrant {
   updateId: string;
 }
 
+/** Credential-free provider usage cached for one exact account/login pair. */
+export interface IStoredAuthorityUsage extends IAuthSwitchStoredUsage {
+  id: string;
+  accountId: string;
+  loginId: string;
+}
+
+export const authorityUsageId = (accountId: string, loginId: string): string =>
+  plugins.crypto.createHash('sha256').update(JSON.stringify(['authswitch-usage-v1', accountId, loginId])).digest('hex');
+
 export interface IStoredAuthorityBinding {
   id: string;
   accountId: string;
@@ -71,6 +85,63 @@ export interface IStoredAuthorityEnrollment {
   updateId: string;
 }
 
+/** An immutable assignment of one private native Codex state home to one account and runtime scope. */
+export interface IStoredAuthorityCodexHome {
+  id: string;
+  accountId: string;
+  grantId: string;
+  scopeId: string;
+  activeRun: { id: string; socketPath: string; pid: number | null; startedAt: string | null } | null;
+  createdAt: string;
+  updateId: string;
+}
+
+/** One vendor home owns at most one active Claude grant; activeGrantId has a unique index. */
+export interface IStoredAuthorityClaudeHome {
+  id: string;
+  activeAccountId: string;
+  activeGrantId: string;
+  pendingOperationId: string | null;
+  status: 'ready' | 'quarantined';
+  revision: number;
+  createdAt: string;
+  updateId: string;
+}
+
+export interface IStoredAuthorityNativePair {
+  credentialDigest: string | null;
+  configDigest: string | null;
+}
+
+export interface IStoredAuthorityNativeIdentity {
+  accountUuid: string;
+  organizationUuid: string;
+}
+
+/** Backend-only proof for one exact two-grant native transfer. */
+export interface IStoredAuthorityClaudeHandoff {
+  id: string;
+  homeId: string;
+  outgoingAccountId: string;
+  outgoingGrantId: string;
+  incomingAccountId: string;
+  incomingGrantId: string;
+  phase: 'reserved' | 'prepared' | 'committed' | 'aborted' | 'quarantined';
+  before: IStoredAuthorityNativePair | null;
+  after: IStoredAuthorityNativePair | null;
+  sourceIdentity: IStoredAuthorityNativeIdentity;
+  targetIdentity: IStoredAuthorityNativeIdentity;
+  sourceAccessDigest: string | null;
+  targetAccessDigest: string | null;
+  sealedOutgoing: string | null;
+  runningEffectiveAuth: 'no_scoped_sessions' | 'unsupported_effective_auth' | null;
+  problem: 'none' | 'native_uncertain' | 'foreign_or_torn' | 'unsupported_effective_auth' | 'database_uncertain';
+  startedAt: string;
+  updatedAt: string;
+  revision: number;
+  updateId: string;
+}
+
 /** Journal for a native-home handoff. A prepared grant is never usable. */
 export interface IStoredAuthorityHandoff {
   id: string;
@@ -112,6 +183,82 @@ export interface IStoredAuthorityEvent {
   accountId: string;
 }
 
+/** A device flow and its immutable result receipt. Provider work is never resumed from this record. */
+export interface IStoredAuthorityDeviceOperation {
+  id: string;
+  kind: 'add_openai' | 'reauth_openai';
+  purpose: 'openai_managed';
+  accountId: string | null;
+  grantId: string | null;
+  expectedGrantGeneration: number | null;
+  state: 'starting' | 'pending' | 'committing' | 'complete' | 'failed' | 'cancelled' | 'interrupted' | 'outcome_unknown';
+  prompt: TAuthSwitchLoginPrompt | null;
+  result: { accountId: string; grantId: string; accountRevision: number; grantGeneration: number } | null;
+  error: string | null;
+  commitId: string | null;
+  createdAt: string;
+  updatedAt: string;
+  finishedAt: string | null;
+  revision: number;
+  updateId: string;
+}
+
+export type TStoredAuthorityPreuseProblem =
+  | 'none' | 'target_unavailable' | 'access_unavailable' | 'catalog_unavailable'
+  | 'account_busy' | 'cancelled' | 'authority_closing' | 'interrupted'
+  | 'request_uncertain' | 'restored_history_uncertain';
+
+/** One quota-consuming request. The prompt and generated prose never enter persistence. */
+export interface IStoredAuthorityPreuseOperation {
+  id: string;
+  kind: 'preuse_openai';
+  purpose: 'openai_managed';
+  accountId: string;
+  grantId: string;
+  /** Hash of the exact target, prompt and requested model; used only for idempotent admission. */
+  requestHash: string;
+  requestedModel: string | null;
+  model: string | null;
+  authorizationGeneration: number;
+  grantGeneration: number | null;
+  state: 'preparing' | 'request_may_have_started' | 'complete' | 'not_sent' | 'outcome_unknown';
+  result: { inputTokens: number | null; outputTokens: number | null; totalTokens: number | null } | null;
+  problem: TStoredAuthorityPreuseProblem;
+  createdAt: string;
+  updatedAt: string;
+  finishedAt: string | null;
+  revision: number;
+  updateId: string;
+}
+
+export type IStoredAuthorityOperation = IStoredAuthorityDeviceOperation | IStoredAuthorityPreuseOperation;
+
+/** Decorated storage fields shared by the two exact discriminated operation variants. */
+export interface IStoredAuthorityOperationDocument {
+  id: string;
+  kind: IStoredAuthorityOperation['kind'];
+  purpose: 'openai_managed';
+  accountId: string | null;
+  grantId: string | null;
+  expectedGrantGeneration?: number | null;
+  state: IStoredAuthorityOperation['state'];
+  prompt?: TAuthSwitchLoginPrompt | null;
+  result: IStoredAuthorityOperation['result'];
+  error?: string | null;
+  commitId?: string | null;
+  requestHash?: string;
+  requestedModel?: string | null;
+  model?: string | null;
+  authorizationGeneration?: number;
+  grantGeneration?: number | null;
+  problem?: TStoredAuthorityPreuseProblem;
+  createdAt: string;
+  updatedAt: string;
+  finishedAt: string | null;
+  revision: number;
+  updateId: string;
+}
+
 const object = (value: unknown): value is Record<string, unknown> =>
   value !== null && typeof value === 'object' && !Array.isArray(value)
   && [Object.prototype, null].includes(Object.getPrototypeOf(value));
@@ -127,9 +274,110 @@ const revision = (value: unknown): value is number => Number.isSafeInteger(value
 const ciphertext = (value: unknown): boolean => value === null
   || (typeof value === 'string' && value.length > 0 && value.length <= 131072 && /^[A-Za-z0-9_-]+$/.test(value));
 
+const usageWindow = (value: unknown): boolean => object(value)
+  && exactKeys(value, ['usedPercent', 'limitWindowSeconds', 'resetAfterSeconds', 'resetsAt'])
+  && ['usedPercent', 'limitWindowSeconds', 'resetAfterSeconds', 'resetsAt']
+    .every(key => typeof value[key] === 'number' && Number.isFinite(value[key]));
+const usageDetails = (value: unknown): boolean => object(value)
+  && Object.keys(value).every(key => ['allowed', 'limitReached', 'primaryWindow', 'secondaryWindow'].includes(key))
+  && typeof value.allowed === 'boolean' && typeof value.limitReached === 'boolean'
+  && (value.primaryWindow === undefined || usageWindow(value.primaryWindow))
+  && (value.secondaryWindow === undefined || usageWindow(value.secondaryWindow));
+const usageRateLimits = (value: unknown): boolean => object(value)
+  && Object.keys(value).every(key => ['providerId', 'plan', 'observedAt', 'rateLimit',
+    'additionalRateLimits', 'rateLimitReachedType', 'rateLimitResetCreditsAvailableCount'].includes(key))
+  && value.providerId === 'openai' && bounded(value.plan, 256) && iso(value.observedAt)
+  && (value.rateLimit === undefined || usageDetails(value.rateLimit))
+  && Array.isArray(value.additionalRateLimits) && value.additionalRateLimits.length <= 128
+  && value.additionalRateLimits.every((item: unknown) => object(item)
+    && Object.keys(item).every(key => ['limitName', 'meteredFeature', 'rateLimit'].includes(key))
+    && bounded(item.limitName, 256) && bounded(item.meteredFeature, 256)
+    && (item.rateLimit === undefined || usageDetails(item.rateLimit)))
+  && (value.rateLimitReachedType === undefined || bounded(value.rateLimitReachedType, 256))
+  && (value.rateLimitResetCreditsAvailableCount === undefined
+    || (typeof value.rateLimitResetCreditsAvailableCount === 'number'
+      && Number.isFinite(value.rateLimitResetCreditsAvailableCount)));
+
+const usageStatusText = (value: unknown): boolean => typeof value === 'string' && value.length <= 500
+  && !/[\u0000-\u001f\u007f-\u009f]/.test(value);
+const usageClaudeStatus = (value: unknown): boolean => object(value)
+  && exactKeys(value, ['plan', 'windows', 'facts', 'problems', 'rateLimit'])
+  && (value.plan === null || (object(value.plan) && exactKeys(value.plan, ['name', 'source'])
+    && usageStatusText(value.plan.name) && ['live', 'stored'].includes(String(value.plan.source))))
+  && (value.windows === null || (Array.isArray(value.windows) && value.windows.length <= 128
+    && value.windows.every((window: unknown) => object(window)
+      && Object.keys(window).every(key => ['label', 'scope', 'durationSeconds', 'usedPercent',
+        'resetAt', 'severity', 'headline'].includes(key))
+      && ['label', 'scope', 'durationSeconds', 'usedPercent', 'resetAt'].every(key => Object.hasOwn(window, key))
+      && usageStatusText(window.label) && ['account', 'feature'].includes(String(window.scope))
+      && Number.isSafeInteger(window.durationSeconds) && Number(window.durationSeconds) > 0
+      && typeof window.usedPercent === 'number' && Number.isFinite(window.usedPercent)
+      && window.usedPercent >= 0 && (window.resetAt === null || iso(window.resetAt))
+      && (window.severity === undefined || ['normal', 'warning', 'critical'].includes(String(window.severity)))
+      && (window.headline === undefined || window.headline === true))))
+  && Array.isArray(value.facts) && value.facts.length <= 128
+  && value.facts.every((fact: unknown) => object(fact)
+    && Object.keys(fact).every(key => ['section', 'label', 'value', 'summaryKey'].includes(key))
+    && ['section', 'label', 'value'].every(key => Object.hasOwn(fact, key))
+    && (fact.section === null || usageStatusText(fact.section))
+    && usageStatusText(fact.label) && usageStatusText(fact.value)
+    && (fact.summaryKey === undefined || ['subscription', 'billing', 'usageWindows', 'resets',
+      'resetDetails'].includes(String(fact.summaryKey))))
+  && Array.isArray(value.problems) && value.problems.length <= 32
+  && value.problems.every(usageStatusText)
+  && (value.rateLimit === null || (object(value.rateLimit)
+    && exactKeys(value.rateLimit, ['retryAt'])
+    && (value.rateLimit.retryAt === null || iso(value.rateLimit.retryAt))));
+const usageReading = (value: unknown): boolean => object(value)
+  && (value.kind === 'openai' ? exactKeys(value, ['kind', 'rateLimits']) && usageRateLimits(value.rateLimits)
+    : value.kind === 'anthropic' && exactKeys(value, ['kind', 'status'])
+      && usageClaudeStatus(value.status));
+
+export const assertStoredAuthorityUsage: (value: unknown) => asserts value is IStoredAuthorityUsage = value => {
+  if (!object(value) || !exactKeys(value, ['id', 'accountId', 'loginId', 'context', 'updateId',
+    'reading', 'observedAt', 'currentUntil', 'staleUntil', 'lastAttemptAt', 'nextAttemptAt',
+    'failures', 'problem']) || !hash(value.accountId) || !hash(value.loginId)
+    || value.id !== authorityUsageId(value.accountId, value.loginId)
+    || !object(value.context) || !exactKeys(value.context, ['epoch', 'accountId', 'loginId',
+      'subjectId', 'workspaceId', 'providerId', 'purpose', 'owner', 'grantState', 'removed',
+      'authorizationGeneration', 'grantGeneration', 'nativeSource'])
+    || !uuid(value.context.epoch) || value.context.accountId !== value.accountId
+    || value.context.loginId !== value.loginId || !bounded(value.context.subjectId)
+    || !bounded(value.context.workspaceId)
+    || !((value.context.providerId === 'openai' && value.context.purpose === 'openai_managed'
+      && value.context.owner === 'daemon' && value.context.nativeSource === null
+      && ['ready', 'retry_wait'].includes(String(value.context.grantState)))
+      || (value.context.providerId === 'anthropic' && value.context.purpose === 'claude_host_native'
+        && ((value.context.owner === 'daemon' && value.context.nativeSource === null
+          && ['ready', 'retry_wait'].includes(String(value.context.grantState)))
+          || (value.context.owner === 'claude_native' && value.context.grantState === 'native'
+            && object(value.context.nativeSource)
+            && exactKeys(value.context.nativeSource, ['homeId', 'credentialDigest',
+              'configDigest', 'accessTokenDigest'])
+            && hash(value.context.nativeSource.homeId)
+            && hash(value.context.nativeSource.credentialDigest)
+            && hash(value.context.nativeSource.configDigest)
+            && hash(value.context.nativeSource.accessTokenDigest)))))
+    || value.context.removed !== false || !revision(value.context.authorizationGeneration)
+    || !revision(value.context.grantGeneration) || !uuid(value.updateId)
+    || (value.reading !== null && (!object(value.reading) || !usageReading(value.reading)
+      || (value.context.providerId === 'openai' ? value.reading.kind !== 'openai'
+        : value.reading.kind !== 'anthropic')))
+    || (value.observedAt !== null && !iso(value.observedAt))
+    || (value.currentUntil !== null && !iso(value.currentUntil))
+    || (value.staleUntil !== null && !iso(value.staleUntil))
+    || !iso(value.lastAttemptAt) || !iso(value.nextAttemptAt)
+    || !revision(value.failures) || value.failures > 16
+    || !['none', 'unsupported', 'access_unavailable', 'provider_unavailable', 'provider_rejected',
+      'profile_unavailable', 'usage_unavailable'].includes(String(value.problem))) {
+    throw new Error('Invalid credential-free authority usage record.');
+  }
+};
+
 export const assertStoredAuthorityMeta: (value: unknown) => asserts value is IStoredAuthorityMeta = value => {
-  if (!object(value) || !exactKeys(value, ['id', 'epoch', 'revision', 'updateId'])
-    || value.id !== 'authswitch-authority' || !uuid(value.epoch)
+  if (!object(value) || !exactKeys(value, ['id', 'schemaVersion', 'admission', 'epoch', 'revision', 'updateId'])
+    || value.id !== 'authswitch-authority' || value.schemaVersion !== 2
+    || !['open', 'closed_restored'].includes(value.admission as string) || !uuid(value.epoch)
     || !revision(value.revision) || !uuid(value.updateId)) throw new Error('Invalid authswitch authority metadata.');
 };
 
@@ -154,7 +402,7 @@ export const assertStoredAuthorityGrant: (value: unknown) => asserts value is IS
     || typeof value.providerId !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(value.providerId)
     || !['openai_managed', 'claude_host_native', 'claude_container_setup', 'opencode_native'].includes(String(value.purpose))
     || !bounded(value.audience)
-    || !['ready', 'exchange_may_have_been_sent', 'retry_wait', 'needs_reauth', 'native', 'legacy_native_pending', 'removed'].includes(String(value.state))
+    || !['ready', 'exchange_may_have_been_sent', 'retry_wait', 'needs_reauth', 'native', 'legacy_native_pending', 'handoff_pending', 'handoff_quarantined', 'removed'].includes(String(value.state))
     || !['daemon', 'claude_native', 'legacy_native', 'none'].includes(String(value.owner))
     || !revision(value.grantGeneration) || !revision(value.authorizationGeneration)
     || !revision(value.revision) || !ciphertext(value.ciphertext)
@@ -170,6 +418,13 @@ export const assertStoredAuthorityGrant: (value: unknown) => asserts value is IS
   if ((value.state === 'retry_wait') !== (value.retryAt !== null)) throw new Error('Invalid refresh retry marker.');
   if (value.state === 'removed' && (value.ciphertext !== null || value.owner !== 'none')) throw new Error('A removed grant was retained.');
   if (value.state === 'legacy_native_pending' && value.owner !== 'legacy_native') throw new Error('A legacy native grant cannot be daemon-owned.');
+  if (['handoff_pending', 'handoff_quarantined'].includes(String(value.state))
+    && value.purpose !== 'claude_host_native') throw new Error('Only a Claude host grant may enter native handoff.');
+  if (['handoff_pending', 'handoff_quarantined'].includes(String(value.state))
+    && (value.owner === 'daemon' ? value.ciphertext === null
+      : value.owner !== 'claude_native' || value.ciphertext !== null)) {
+    throw new Error('Claude handoff grant has incompatible custody.');
+  }
   if (value.purpose === 'openai_managed' && value.providerId !== 'openai') throw new Error('OpenAI grant provider mismatch.');
   if (value.purpose === 'claude_container_setup' && value.owner === 'claude_native') throw new Error('Container setup grant has a native host owner.');
 };
@@ -191,6 +446,75 @@ export const assertStoredAuthorityEnrollment: (value: unknown) => asserts value
     || !revision(value.revision) || !uuid(value.updateId)) throw new Error('Invalid authswitch enrollment record.');
 };
 
+export const assertStoredAuthorityCodexHome: (value: unknown) => asserts value is IStoredAuthorityCodexHome = value => {
+  if (!object(value) || !exactKeys(value, ['id', 'accountId', 'grantId', 'scopeId', 'activeRun', 'createdAt', 'updateId'])
+    || !hash(value.id) || !hash(value.accountId) || !hash(value.grantId) || !bounded(value.scopeId)
+    || !iso(value.createdAt) || !uuid(value.updateId)) {
+    throw new Error('Invalid managed Codex home assignment.');
+  }
+  if (value.activeRun !== null && (!object(value.activeRun)
+    || !exactKeys(value.activeRun, ['id', 'socketPath', 'pid', 'startedAt'])
+    || !uuid(value.activeRun.id) || !bounded(value.activeRun.socketPath, 1024)
+    || (value.activeRun.pid !== null && (typeof value.activeRun.pid !== 'number'
+      || !Number.isSafeInteger(value.activeRun.pid) || value.activeRun.pid <= 0))
+    || (value.activeRun.startedAt !== null && !iso(value.activeRun.startedAt))
+    || (value.activeRun.pid === null) !== (value.activeRun.startedAt === null))) {
+    throw new Error('Invalid managed Codex run assignment.');
+  }
+};
+
+export const assertStoredAuthorityClaudeHome: (value: unknown) => asserts value is IStoredAuthorityClaudeHome = value => {
+  if (!object(value) || !exactKeys(value, ['id', 'activeAccountId', 'activeGrantId', 'pendingOperationId',
+    'status', 'revision', 'createdAt', 'updateId']) || !hash(value.id) || !hash(value.activeAccountId)
+    || !hash(value.activeGrantId) || (value.pendingOperationId !== null && !uuid(value.pendingOperationId))
+    || !['ready', 'quarantined'].includes(String(value.status)) || !revision(value.revision)
+    || value.revision === 0 || !iso(value.createdAt) || !uuid(value.updateId)
+    || (value.status === 'quarantined' && value.pendingOperationId === null)) {
+    throw new Error('Invalid Claude native home assignment.');
+  }
+};
+
+const nativePair = (value: unknown): value is IStoredAuthorityNativePair => object(value)
+  && exactKeys(value, ['credentialDigest', 'configDigest'])
+  && (value.credentialDigest === null || hash(value.credentialDigest))
+  && (value.configDigest === null || hash(value.configDigest));
+const nativeIdentity = (value: unknown): value is IStoredAuthorityNativeIdentity => object(value)
+  && exactKeys(value, ['accountUuid', 'organizationUuid'])
+  && bounded(value.accountUuid) && bounded(value.organizationUuid);
+
+export const assertStoredAuthorityClaudeHandoff: (value: unknown) => asserts value is IStoredAuthorityClaudeHandoff = value => {
+  if (!object(value) || !exactKeys(value, ['id', 'homeId', 'outgoingAccountId', 'outgoingGrantId',
+    'incomingAccountId', 'incomingGrantId', 'phase', 'before', 'after', 'sourceIdentity',
+    'targetIdentity', 'sourceAccessDigest', 'targetAccessDigest', 'sealedOutgoing',
+    'runningEffectiveAuth', 'problem', 'startedAt', 'updatedAt', 'revision', 'updateId'])
+    || !uuid(value.id) || !hash(value.homeId) || !hash(value.outgoingAccountId)
+    || !hash(value.outgoingGrantId) || !hash(value.incomingAccountId) || !hash(value.incomingGrantId)
+    || value.outgoingAccountId === value.incomingAccountId || value.outgoingGrantId === value.incomingGrantId
+    || !['reserved', 'prepared', 'committed', 'aborted', 'quarantined'].includes(String(value.phase))
+    || (value.before !== null && !nativePair(value.before)) || (value.after !== null && !nativePair(value.after))
+    || !nativeIdentity(value.sourceIdentity) || !nativeIdentity(value.targetIdentity)
+    || (value.sourceAccessDigest !== null && !hash(value.sourceAccessDigest))
+    || (value.targetAccessDigest !== null && !hash(value.targetAccessDigest))
+    || !ciphertext(value.sealedOutgoing)
+    || ![null, 'no_scoped_sessions', 'unsupported_effective_auth'].includes(value.runningEffectiveAuth as null)
+    || !['none', 'native_uncertain', 'foreign_or_torn', 'unsupported_effective_auth', 'database_uncertain'].includes(String(value.problem))
+    || !iso(value.startedAt) || !iso(value.updatedAt) || !revision(value.revision)
+    || value.revision === 0 || !uuid(value.updateId)) throw new Error('Invalid Claude native handoff.');
+  const hasProof = value.before !== null && value.after !== null
+    && value.sourceAccessDigest !== null && value.targetAccessDigest !== null;
+  const hasNoProof = value.before === null && value.after === null
+    && value.sourceAccessDigest === null && value.targetAccessDigest === null;
+  if ((value.phase === 'reserved' && (!hasNoProof || value.sealedOutgoing !== null))
+    || (['prepared', 'committed'].includes(String(value.phase)) && !hasProof)
+    || (['aborted', 'quarantined'].includes(String(value.phase)) && !hasProof && !hasNoProof)) {
+    throw new Error('Claude handoff phase lacks exact native proof.');
+  }
+  if (value.phase === 'prepared' && value.sealedOutgoing === null) throw new Error('Prepared Claude handoff lacks sealed outgoing grant.');
+  if (['committed', 'aborted'].includes(String(value.phase)) && value.sealedOutgoing !== null) {
+    throw new Error('Terminal Claude handoff retained a grant copy.');
+  }
+};
+
 export const assertStoredAuthorityHandoff: (value: unknown) => asserts value is IStoredAuthorityHandoff = value => {
   if (!object(value) || !exactKeys(value, ['id', 'accountId', 'grantId', 'nativeHomeId', 'direction', 'phase',
     'operationId', 'sourceDigest', 'verifiedSourceDigest', 'backupDigest', 'revision', 'statusObservedAt', 'updateId'])
@@ -230,11 +554,154 @@ export const assertStoredAuthorityEvent: (value: unknown) => asserts value is IS
     || !['account', 'binding'].includes(String(value.kind)) || !hash(value.accountId)) throw new Error('Invalid authswitch event record.');
 };
 
+const assertStoredAuthorityDeviceOperation: (value: unknown) => asserts value is IStoredAuthorityDeviceOperation = value => {
+  if (!object(value) || !exactKeys(value, ['id', 'kind', 'purpose', 'accountId', 'grantId',
+    'expectedGrantGeneration', 'state', 'prompt', 'result', 'error', 'commitId', 'createdAt',
+    'updatedAt', 'finishedAt', 'revision', 'updateId'])
+    || !uuid(value.id) || !['add_openai', 'reauth_openai'].includes(String(value.kind))
+    || value.purpose !== 'openai_managed'
+    || (value.accountId !== null && !hash(value.accountId))
+    || (value.grantId !== null && !hash(value.grantId))
+    || (value.expectedGrantGeneration !== null && !revision(value.expectedGrantGeneration))
+    || !['starting', 'pending', 'committing', 'complete', 'failed', 'cancelled', 'interrupted', 'outcome_unknown'].includes(String(value.state))
+    || (value.commitId !== null && !uuid(value.commitId))
+    || !iso(value.createdAt) || !iso(value.updatedAt)
+    || (value.finishedAt !== null && !iso(value.finishedAt))
+    || !revision(value.revision) || value.revision === 0 || !uuid(value.updateId)) {
+    throw new Error('Invalid authswitch operation record.');
+  }
+  if (value.kind === 'add_openai'
+    ? value.accountId !== null || value.grantId !== null || value.expectedGrantGeneration !== null
+    : value.accountId === null || value.grantId === null || value.expectedGrantGeneration === null) {
+    throw new Error('Invalid authswitch operation target.');
+  }
+  if (value.prompt !== null && (!object(value.prompt)
+    || (value.prompt.flow === 'device'
+      ? !exactKeys(value.prompt, ['flow', 'verificationUrl', 'userCode'])
+        || !bounded(value.prompt.verificationUrl, 2048) || !bounded(value.prompt.userCode, 128)
+      : value.prompt.flow === 'browser'
+        ? !exactKeys(value.prompt, ['flow', 'authUrl']) || !bounded(value.prompt.authUrl, 2048)
+        : true))) throw new Error('Invalid authswitch operation prompt.');
+  if (value.result !== null && (!object(value.result)
+    || !exactKeys(value.result, ['accountId', 'grantId', 'accountRevision', 'grantGeneration'])
+    || !hash(value.result.accountId) || !hash(value.result.grantId)
+    || !revision(value.result.accountRevision) || !revision(value.result.grantGeneration))) {
+    throw new Error('Invalid authswitch operation result.');
+  }
+  if (value.error !== null && !bounded(value.error, 512)) throw new Error('Invalid authswitch operation error.');
+  if (['starting', 'pending', 'committing'].includes(String(value.state))) {
+    if (value.finishedAt !== null || value.result !== null || value.error !== null
+      || (value.state === 'pending') !== (value.prompt !== null)
+      || (value.state === 'committing') !== (value.commitId !== null)) {
+      throw new Error('Invalid pending authswitch operation.');
+    }
+  } else if (value.finishedAt === null || value.prompt !== null
+    || (value.state === 'complete' ? value.result === null || value.error !== null || value.commitId === null
+      : value.result !== null || value.error === null)) {
+    throw new Error('Invalid terminal authswitch operation.');
+  }
+};
+
+const modelId = (value: unknown): value is string => typeof value === 'string'
+  && /^[a-zA-Z0-9][a-zA-Z0-9._:/-]{0,127}$/.test(value);
+const tokenCount = (value: unknown): value is number | null => value === null
+  || (Number.isSafeInteger(value) && Number(value) >= 0);
+
+const assertStoredAuthorityPreuseOperation: (value: unknown) => asserts value is IStoredAuthorityPreuseOperation = value => {
+  if (!object(value) || !exactKeys(value, ['id', 'kind', 'purpose', 'accountId', 'grantId', 'requestHash',
+    'requestedModel', 'model', 'authorizationGeneration', 'grantGeneration', 'state', 'result', 'problem',
+    'createdAt', 'updatedAt', 'finishedAt', 'revision', 'updateId'])
+    || !uuid(value.id) || value.kind !== 'preuse_openai' || value.purpose !== 'openai_managed'
+    || !hash(value.accountId) || !hash(value.grantId) || !hash(value.requestHash)
+    || (value.requestedModel !== null && !modelId(value.requestedModel))
+    || (value.model !== null && !modelId(value.model))
+    || !revision(value.authorizationGeneration) || value.authorizationGeneration === 0
+    || (value.grantGeneration !== null && (!revision(value.grantGeneration) || value.grantGeneration === 0))
+    || !['preparing', 'request_may_have_started', 'complete', 'not_sent', 'outcome_unknown'].includes(String(value.state))
+    || !['none', 'target_unavailable', 'access_unavailable', 'catalog_unavailable', 'account_busy', 'cancelled',
+      'authority_closing', 'interrupted', 'request_uncertain', 'restored_history_uncertain'].includes(String(value.problem))
+    || !iso(value.createdAt) || !iso(value.updatedAt)
+    || (value.finishedAt !== null && !iso(value.finishedAt))
+    || !revision(value.revision) || value.revision === 0 || !uuid(value.updateId)) {
+    throw new Error('Invalid authswitch preuse operation record.');
+  }
+  if (value.result !== null && (!object(value.result)
+    || !exactKeys(value.result, ['inputTokens', 'outputTokens', 'totalTokens'])
+    || !tokenCount(value.result.inputTokens) || !tokenCount(value.result.outputTokens)
+    || !tokenCount(value.result.totalTokens))) {
+    throw new Error('Invalid authswitch preuse operation result.');
+  }
+  if (value.state === 'preparing') {
+    if (value.model !== null || value.grantGeneration !== null || value.result !== null
+      || value.problem !== 'none' || value.finishedAt !== null) {
+      throw new Error('Invalid preparing authswitch preuse operation.');
+    }
+  } else if (value.state === 'request_may_have_started') {
+    if (value.model === null || value.grantGeneration === null || value.result !== null
+      || value.problem !== 'none' || value.finishedAt !== null) {
+      throw new Error('Invalid active authswitch preuse operation.');
+    }
+  } else if (value.state === 'complete') {
+    if (value.model === null || value.grantGeneration === null || value.result === null
+      || value.problem !== 'none' || value.finishedAt === null) {
+      throw new Error('Invalid completed authswitch preuse operation.');
+    }
+  } else if (value.state === 'not_sent') {
+    if (value.model !== null || value.grantGeneration !== null || value.result !== null
+      || value.problem === 'none' || value.problem === 'request_uncertain' || value.finishedAt === null) {
+      throw new Error('Invalid unsent authswitch preuse operation.');
+    }
+  } else {
+    const restoredHistory = value.problem === 'restored_history_uncertain';
+    const coherentMarker = (value.model === null) === (value.grantGeneration === null);
+    if (value.result !== null || value.finishedAt === null
+      || (restoredHistory ? !coherentMarker : value.model === null || value.grantGeneration === null
+        || !['cancelled', 'authority_closing', 'request_uncertain'].includes(String(value.problem)))) {
+      throw new Error('Invalid uncertain authswitch preuse operation.');
+    }
+  }
+};
+
+export const assertStoredAuthorityOperation: (value: unknown) => asserts value is IStoredAuthorityOperation = value => {
+  if (object(value) && value.kind === 'preuse_openai') assertStoredAuthorityPreuseOperation(value);
+  else assertStoredAuthorityDeviceOperation(value);
+};
+export const assertStoredAuthorityOperationDocument: (value: unknown) => asserts value is IStoredAuthorityOperationDocument = value => {
+  assertStoredAuthorityOperation(value);
+};
+
+/**
+ * Converts unresolved snapshot history into an immutable restored receipt. A live restart has stronger
+ * evidence and is handled separately: a snapshot captured in `preparing` may have sent after capture.
+ */
+export const restoreStoredAuthorityOperation = (operation: IStoredAuthorityOperation, options: {
+  restoredAt: string;
+  updateId: string;
+}): IStoredAuthorityOperation => {
+  assertStoredAuthorityOperation(operation);
+  const unresolvedDevice = operation.kind !== 'preuse_openai'
+    && ['starting', 'pending', 'committing'].includes(operation.state);
+  const unresolvedPreuse = operation.kind === 'preuse_openai'
+    && ['preparing', 'request_may_have_started'].includes(operation.state);
+  if (!unresolvedDevice && !unresolvedPreuse) return operation;
+  const restored: IStoredAuthorityOperation = operation.kind === 'preuse_openai'
+    ? { ...operation, state: 'outcome_unknown', result: null, problem: 'restored_history_uncertain',
+      updatedAt: options.restoredAt, finishedAt: options.restoredAt,
+      revision: operation.revision + 1, updateId: options.updateId }
+    : { ...operation, state: 'interrupted', prompt: null, result: null, commitId: null,
+      error: 'Interrupted by authority restore.', updatedAt: options.restoredAt, finishedAt: options.restoredAt,
+      revision: operation.revision + 1, updateId: options.updateId };
+  assertStoredAuthorityOperation(restored);
+  return restored;
+};
+
 @plugins.smartdata.managed({ collectionName: 'authswitch_authority_meta' })
 @plugins.smartdata.exactPersistence({ assertDocument: assertStoredAuthorityMeta })
 export class AuthSwitchAuthorityMetaModel extends plugins.smartdata.SmartDataDbDoc<AuthSwitchAuthorityMetaModel, IStoredAuthorityMeta> {
   declare static exact: plugins.smartdata.TExact<AuthSwitchAuthorityMetaModel>;
   @plugins.smartdata.unI() public id!: 'authswitch-authority';
+  @plugins.smartdata.svDb() public schemaVersion!: 2;
+  @plugins.smartdata.svDb() public admission!: IStoredAuthorityMeta['admission'];
   @plugins.smartdata.svDb() public epoch!: string;
   @plugins.smartdata.svDb() public revision!: number;
   @plugins.smartdata.svDb() public updateId!: string;
@@ -286,6 +753,26 @@ export class AuthSwitchAuthorityGrantModel extends plugins.smartdata.SmartDataDb
   @plugins.smartdata.svDb() public updateId!: string;
 }
 
+@plugins.smartdata.compoundIndex({ name: 'authority_usage_account_login', key: { accountId: 1, loginId: 1 }, options: { unique: true } })
+@plugins.smartdata.managed({ collectionName: 'authswitch_authority_usage' })
+@plugins.smartdata.exactPersistence({ assertDocument: assertStoredAuthorityUsage })
+export class AuthSwitchAuthorityUsageModel extends plugins.smartdata.SmartDataDbDoc<AuthSwitchAuthorityUsageModel, IStoredAuthorityUsage> {
+  declare static exact: plugins.smartdata.TExact<AuthSwitchAuthorityUsageModel>;
+  @plugins.smartdata.unI() public id!: string;
+  @plugins.smartdata.svDb() public accountId!: string;
+  @plugins.smartdata.svDb() public loginId!: string;
+  @plugins.smartdata.svDb() public context!: IAuthSwitchStoredUsage['context'];
+  @plugins.smartdata.svDb() public updateId!: string;
+  @plugins.smartdata.svDb() public reading!: IAuthSwitchStoredUsage['reading'];
+  @plugins.smartdata.svDb() public observedAt!: string | null;
+  @plugins.smartdata.svDb() public currentUntil!: string | null;
+  @plugins.smartdata.svDb() public staleUntil!: string | null;
+  @plugins.smartdata.svDb() public lastAttemptAt!: string;
+  @plugins.smartdata.svDb() public nextAttemptAt!: string;
+  @plugins.smartdata.svDb() public failures!: number;
+  @plugins.smartdata.svDb() public problem!: IAuthSwitchStoredUsage['problem'];
+}
+
 @plugins.smartdata.compoundIndex({ name: 'authority_binding_account_id', key: { accountId: 1, id: 1 } })
 @plugins.smartdata.managed({ collectionName: 'authswitch_authority_bindings' })
 @plugins.smartdata.exactPersistence({ assertDocument: assertStoredAuthorityBinding })
@@ -315,6 +802,62 @@ export class AuthSwitchAuthorityEnrollmentModel extends plugins.smartdata.SmartD
   @plugins.smartdata.svDb() public updateId!: string;
 }
 
+@plugins.smartdata.compoundIndex({ name: 'authority_codex_home_account_id', key: { accountId: 1, id: 1 } })
+@plugins.smartdata.managed({ collectionName: 'authswitch_authority_codex_homes' })
+@plugins.smartdata.exactPersistence({ assertDocument: assertStoredAuthorityCodexHome })
+export class AuthSwitchAuthorityCodexHomeModel extends plugins.smartdata.SmartDataDbDoc<AuthSwitchAuthorityCodexHomeModel, IStoredAuthorityCodexHome> {
+  declare static exact: plugins.smartdata.TExact<AuthSwitchAuthorityCodexHomeModel>;
+  @plugins.smartdata.unI() public id!: string;
+  @plugins.smartdata.svDb() public accountId!: string;
+  @plugins.smartdata.svDb() public grantId!: string;
+  @plugins.smartdata.svDb() public scopeId!: string;
+  @plugins.smartdata.svDb() public activeRun!: IStoredAuthorityCodexHome['activeRun'];
+  @plugins.smartdata.svDb() public createdAt!: string;
+  @plugins.smartdata.svDb() public updateId!: string;
+}
+
+@plugins.smartdata.managed({ collectionName: 'authswitch_authority_claude_homes' })
+@plugins.smartdata.exactPersistence({ assertDocument: assertStoredAuthorityClaudeHome })
+export class AuthSwitchAuthorityClaudeHomeModel extends plugins.smartdata.SmartDataDbDoc<AuthSwitchAuthorityClaudeHomeModel, IStoredAuthorityClaudeHome> {
+  declare static exact: plugins.smartdata.TExact<AuthSwitchAuthorityClaudeHomeModel>;
+  @plugins.smartdata.unI() public id!: string;
+  @plugins.smartdata.svDb() public activeAccountId!: string;
+  @plugins.smartdata.index({ unique: true }) public activeGrantId!: string;
+  @plugins.smartdata.svDb() public pendingOperationId!: string | null;
+  @plugins.smartdata.svDb() public status!: IStoredAuthorityClaudeHome['status'];
+  @plugins.smartdata.svDb() public revision!: number;
+  @plugins.smartdata.svDb() public createdAt!: string;
+  @plugins.smartdata.svDb() public updateId!: string;
+}
+
+@plugins.smartdata.compoundIndex({ name: 'authority_claude_handoff_home_phase', key: { homeId: 1, phase: 1, id: 1 } })
+@plugins.smartdata.compoundIndex({ name: 'authority_claude_handoff_phase_id', key: { phase: 1, id: 1 } })
+@plugins.smartdata.managed({ collectionName: 'authswitch_authority_claude_handoffs' })
+@plugins.smartdata.exactPersistence({ assertDocument: assertStoredAuthorityClaudeHandoff })
+export class AuthSwitchAuthorityClaudeHandoffModel extends plugins.smartdata.SmartDataDbDoc<AuthSwitchAuthorityClaudeHandoffModel, IStoredAuthorityClaudeHandoff> {
+  declare static exact: plugins.smartdata.TExact<AuthSwitchAuthorityClaudeHandoffModel>;
+  @plugins.smartdata.unI() public id!: string;
+  @plugins.smartdata.svDb() public homeId!: string;
+  @plugins.smartdata.svDb() public outgoingAccountId!: string;
+  @plugins.smartdata.svDb() public outgoingGrantId!: string;
+  @plugins.smartdata.svDb() public incomingAccountId!: string;
+  @plugins.smartdata.svDb() public incomingGrantId!: string;
+  @plugins.smartdata.svDb() public phase!: IStoredAuthorityClaudeHandoff['phase'];
+  @plugins.smartdata.svDb() public before!: IStoredAuthorityNativePair | null;
+  @plugins.smartdata.svDb() public after!: IStoredAuthorityNativePair | null;
+  @plugins.smartdata.svDb() public sourceIdentity!: IStoredAuthorityNativeIdentity;
+  @plugins.smartdata.svDb() public targetIdentity!: IStoredAuthorityNativeIdentity;
+  @plugins.smartdata.svDb() public sourceAccessDigest!: string | null;
+  @plugins.smartdata.svDb() public targetAccessDigest!: string | null;
+  @plugins.smartdata.svDb() public sealedOutgoing!: string | null;
+  @plugins.smartdata.svDb() public runningEffectiveAuth!: IStoredAuthorityClaudeHandoff['runningEffectiveAuth'];
+  @plugins.smartdata.svDb() public problem!: IStoredAuthorityClaudeHandoff['problem'];
+  @plugins.smartdata.svDb() public startedAt!: string;
+  @plugins.smartdata.svDb() public updatedAt!: string;
+  @plugins.smartdata.svDb() public revision!: number;
+  @plugins.smartdata.svDb() public updateId!: string;
+}
+
 @plugins.smartdata.compoundIndex({ name: 'authority_handoff_grant_id', key: { grantId: 1, id: 1 } })
 @plugins.smartdata.managed({ collectionName: 'authswitch_authority_handoffs' })
 @plugins.smartdata.exactPersistence({ assertDocument: assertStoredAuthorityHandoff })
@@ -336,6 +879,7 @@ export class AuthSwitchAuthorityHandoffModel extends plugins.smartdata.SmartData
 }
 
 @plugins.smartdata.compoundIndex({ name: 'authority_migration_status_id', key: { status: 1, id: 1 } })
+@plugins.smartdata.compoundIndex({ name: 'authority_migration_grant_status_id', key: { grantId: 1, status: 1, id: 1 } })
 @plugins.smartdata.managed({ collectionName: 'authswitch_authority_migration_ledger' })
 @plugins.smartdata.exactPersistence({ assertDocument: assertStoredAuthorityMigrationLedger })
 export class AuthSwitchAuthorityMigrationLedgerModel extends plugins.smartdata.SmartDataDbDoc<AuthSwitchAuthorityMigrationLedgerModel, IStoredAuthorityMigrationLedger> {
@@ -365,3 +909,34 @@ export class AuthSwitchAuthorityEventModel extends plugins.smartdata.SmartDataDb
   @plugins.smartdata.svDb() public kind!: IStoredAuthorityEvent['kind'];
   @plugins.smartdata.svDb() public accountId!: string;
 }
+
+@plugins.smartdata.compoundIndex({ name: 'authority_operation_state_id', key: { state: 1, id: 1 } })
+@plugins.smartdata.compoundIndex({ name: 'authority_operation_account_id', key: { accountId: 1, id: 1 } })
+@plugins.smartdata.compoundIndex({ name: 'authority_operation_kind_id', key: { kind: 1, id: 1 } })
+@plugins.smartdata.managed({ collectionName: 'authswitch_authority_operations' })
+@plugins.smartdata.exactPersistence({ assertDocument: assertStoredAuthorityOperationDocument })
+export class AuthSwitchAuthorityOperationModel extends plugins.smartdata.SmartDataDbDoc<AuthSwitchAuthorityOperationModel, IStoredAuthorityOperationDocument> {
+  declare static exact: plugins.smartdata.TExact<AuthSwitchAuthorityOperationModel>;
+  @plugins.smartdata.unI() public id!: string;
+  @plugins.smartdata.svDb() public kind!: IStoredAuthorityOperationDocument['kind'];
+  @plugins.smartdata.svDb() public purpose!: IStoredAuthorityOperation['purpose'];
+  @plugins.smartdata.svDb() public accountId!: string | null;
+  @plugins.smartdata.svDb() public grantId!: string | null;
+  @plugins.smartdata.svDb() public expectedGrantGeneration?: number | null;
+  @plugins.smartdata.svDb() public state!: IStoredAuthorityOperationDocument['state'];
+  @plugins.smartdata.svDb() public prompt?: TAuthSwitchLoginPrompt | null;
+  @plugins.smartdata.svDb() public result!: IStoredAuthorityOperationDocument['result'];
+  @plugins.smartdata.svDb() public error?: string | null;
+  @plugins.smartdata.svDb() public commitId?: string | null;
+  @plugins.smartdata.svDb() public requestHash?: string;
+  @plugins.smartdata.svDb() public requestedModel?: string | null;
+  @plugins.smartdata.svDb() public model?: string | null;
+  @plugins.smartdata.svDb() public authorizationGeneration?: number;
+  @plugins.smartdata.svDb() public grantGeneration?: number | null;
+  @plugins.smartdata.svDb() public problem?: TStoredAuthorityPreuseProblem;
+  @plugins.smartdata.svDb() public createdAt!: string;
+  @plugins.smartdata.svDb() public updatedAt!: string;
+  @plugins.smartdata.svDb() public finishedAt!: string | null;
+  @plugins.smartdata.svDb() public revision!: number;
+  @plugins.smartdata.svDb() public updateId!: string;
+}