@peanut-admin/admin 0.1.0-alpha.11

package/admin-core/src/governance/audit.ts

@@ -0,0 +1,56 @@
+import type { GovernanceAudience } from './types'
+
+export type GovernanceAuditOutcome = 'success' | 'denied' | 'error'
+
+export interface GovernanceAuditFilter {
+  eventType?: string
+  action?: string
+  outcome?: GovernanceAuditOutcome
+  requestId?: string
+  targetType?: string
+  targetId?: string
+}
+
+export interface GovernanceAuditDetailInput {
+  id: string
+  audience: GovernanceAudience
+  eventType: string
+  action: string
+  outcome: GovernanceAuditOutcome
+  requestId: string
+  occurredAt: string
+  metadata: Readonly<Record<string, unknown>>
+}
+
+const safeFilter = (value: string): boolean => value !== ''
+  && value.length <= 160
+  && !/[\u0000-\u001f\u007f]/.test(value)
+
+export const normalizeAuditFilter = (input: GovernanceAuditFilter): GovernanceAuditFilter => {
+  for (const value of [input.eventType, input.action, input.requestId, input.targetType, input.targetId]) {
+    if (value !== undefined && !safeFilter(value)) throw new Error('AUDIT_FILTER_INVALID')
+  }
+  if ((input.targetType === undefined) !== (input.targetId === undefined)) {
+    throw new Error('AUDIT_TARGET_FILTER_INCOMPLETE')
+  }
+  return { ...input }
+}
+
+export const projectAuditDetail = (
+  input: GovernanceAuditDetailInput,
+  metadataAllowlist: readonly string[],
+) => {
+  const metadata: Record<string, boolean | number | string | null> = {}
+  if (metadataAllowlist.some(key => (
+    !/^[a-z][a-z0-9_]{0,63}$/.test(key)
+    || /token|secret|cookie|password|sql|target_set/i.test(key)
+  ))) throw new Error('AUDIT_METADATA_ALLOWLIST_INVALID')
+  const allowed = new Set(metadataAllowlist)
+  for (const key of [...allowed].sort()) {
+    const value = input.metadata[key]
+    if (value === null || ['boolean', 'number', 'string'].includes(typeof value)) {
+      metadata[key] = value as boolean | number | string | null
+    }
+  }
+  return { ...input, metadata }
+}

package/admin-core/src/governance/catalog.ts

@@ -0,0 +1,86 @@
+import type {
+  GovernanceAudience,
+  GovernanceCatalog,
+  GovernanceCatalogInput,
+  GovernancePermissionDefinition,
+} from './types'
+
+const permissionPattern = /^[a-z][a-z0-9]*(?:[.-][a-z][a-z0-9-]*)+$/
+const modulePattern = /^[a-z][a-z0-9]*(?:[.-][a-z][a-z0-9-]*)*$/
+
+const fail = (code: string): never => { throw new Error(code) }
+
+const canonicalRoutePath = (audience: GovernanceAudience, path: string): string => {
+  if (audience !== 'tenant' && audience !== 'platform') fail('GOVERNANCE_ROUTE_INVALID')
+  const prefix = audience === 'tenant' ? '/app' : '/platform'
+  if (path === ''
+    || !path.startsWith('/')
+    || path.endsWith('/')
+    || path.includes('//')
+    || /[\\%?#\u0000-\u0020\u007f]/.test(path)
+    || path.split('/').some(segment => segment === '.' || segment === '..')
+    || (path !== prefix && !path.startsWith(`${prefix}/`))) fail('GOVERNANCE_ROUTE_INVALID')
+  return path
+}
+
+export const createGovernanceCatalog = (input: GovernanceCatalogInput): GovernanceCatalog => {
+  const permissions = new Map<string, GovernancePermissionDefinition>()
+  for (const permission of input.permissions) {
+    if (!['tenant', 'platform'].includes(permission.audience)
+      || !permissionPattern.test(permission.key)
+      || !modulePattern.test(permission.moduleKey)
+      || (permission.audience === 'platform') !== permission.key.startsWith('platform.')
+      || permissions.has(permission.key)) fail('GOVERNANCE_PERMISSION_INVALID')
+    permissions.set(permission.key, { ...permission })
+  }
+
+  const routes = new Map<string, GovernanceCatalogInput['routes'][number]>()
+  const paths = new Set<string>()
+  for (const route of input.routes) {
+    const path = canonicalRoutePath(route.audience, route.path)
+    if (route.name === ''
+      || route.componentKey === ''
+      || route.permissionKeys.length === 0
+      || route.clientKeys.length === 0
+      || new Set(route.permissionKeys).size !== route.permissionKeys.length
+      || new Set(route.clientKeys).size !== route.clientKeys.length
+      || routes.has(route.name)
+      || paths.has(path)) fail('GOVERNANCE_ROUTE_INVALID')
+    const expectedModule = route.moduleKey ?? (route.audience === 'platform' ? 'platform' : 'core')
+    for (const permissionKey of route.permissionKeys) {
+      const permission = permissions.get(permissionKey) ?? fail('GOVERNANCE_PERMISSION_UNDECLARED')
+      if (permission.audience !== route.audience) fail('GOVERNANCE_PERMISSION_AUDIENCE_MISMATCH')
+      if (!permission.active) fail('GOVERNANCE_PERMISSION_INACTIVE')
+      if (permission.moduleKey !== expectedModule) fail('GOVERNANCE_PERMISSION_MODULE_MISMATCH')
+    }
+    routes.set(route.name, {
+      ...route,
+      path,
+      permissionKeys: [...route.permissionKeys],
+      clientKeys: [...route.clientKeys],
+    })
+    paths.add(path)
+  }
+
+  const icons = new Map<string, GovernanceCatalogInput['icons'][string]>()
+  for (const [key, icon] of Object.entries(input.icons)) {
+    if (!/^[A-Z][A-Za-z0-9]{0,63}$/.test(key)
+      || icon.label.trim() === ''
+      || icon.glyph.trim() === ''
+      || icons.has(key)) fail('GOVERNANCE_ICON_INVALID')
+    icons.set(key, { ...icon })
+  }
+
+  return { permissions, routes, icons }
+}
+
+export const requireGovernancePermission = (
+  catalog: GovernanceCatalog,
+  key: string,
+  audience: GovernanceAudience,
+): GovernancePermissionDefinition => {
+  const permission = catalog.permissions.get(key) ?? fail('GOVERNANCE_PERMISSION_UNDECLARED')
+  if (permission.audience !== audience) fail('GOVERNANCE_PERMISSION_AUDIENCE_MISMATCH')
+  if (!permission.active) fail('GOVERNANCE_PERMISSION_INACTIVE')
+  return permission
+}

package/admin-core/src/governance/index.ts

@@ -0,0 +1,26 @@
+export { createGovernanceCatalog, requireGovernancePermission } from './catalog'
+export { normalizeAuditFilter, projectAuditDetail } from './audit'
+export { explainMenuVisibility } from './menu'
+export { createDataPolicyDraft, createRolePermissionDraft, requireRevision } from './roles'
+export type {
+  GovernanceAuditDetailInput,
+  GovernanceAuditFilter,
+  GovernanceAuditOutcome,
+} from './audit'
+export type {
+  CreateDataPolicyDraftInput,
+  DataPolicyDraftInput,
+  RolePermissionDraftInput,
+  UpdateDataPolicyDraftInput,
+} from './roles'
+export type {
+  GovernanceAudience,
+  GovernanceCatalog,
+  GovernanceCatalogInput,
+  GovernanceIconDefinition,
+  GovernanceMenuExplanation,
+  GovernanceMenuInput,
+  GovernancePermissionDefinition,
+  GovernanceRouteDefinition,
+  GovernanceVisibilityContext,
+} from './types'

package/admin-core/src/governance/menu.ts

@@ -0,0 +1,63 @@
+import { requireGovernancePermission } from './catalog'
+import type {
+  GovernanceCatalog,
+  GovernanceMenuExplanation,
+  GovernanceMenuInput,
+  GovernanceVisibilityContext,
+} from './types'
+
+const fail = (code: string): never => { throw new Error(code) }
+
+const sameStrings = (left: readonly string[], right: readonly string[]): boolean => (
+  [...new Set(left)].sort().join('\u0000') === [...new Set(right)].sort().join('\u0000')
+  && new Set(left).size === left.length
+  && new Set(right).size === right.length
+)
+
+export const explainMenuVisibility = (
+  menu: GovernanceMenuInput,
+  context: GovernanceVisibilityContext,
+  catalog: GovernanceCatalog,
+): GovernanceMenuExplanation => {
+  const route = menu.routeName === null ? null : catalog.routes.get(menu.routeName)
+  if (menu.type === 'page' && route === undefined) fail('GOVERNANCE_ROUTE_UNDECLARED')
+  if (route !== null && route !== undefined) {
+    if (menu.audience !== context.audience || route.audience !== menu.audience) fail('GOVERNANCE_ROUTE_AUDIENCE_MISMATCH')
+    const expectedModule = menu.audience === 'platform' && menu.moduleKey === 'core' ? 'platform' : menu.moduleKey
+    const routeModule = route.moduleKey ?? (route.audience === 'platform' ? 'platform' : 'core')
+    if (routeModule !== expectedModule) fail('GOVERNANCE_ROUTE_MODULE_MISMATCH')
+    if (route.path !== menu.routePath
+      || route.componentKey !== menu.componentKey
+      || !sameStrings(route.clientKeys, menu.clientKeys)) fail('GOVERNANCE_ROUTE_CONTRACT_MISMATCH')
+  }
+
+  const permission = menu.requiredPermission === null
+    ? null
+    : requireGovernancePermission(catalog, menu.requiredPermission, context.audience)
+  const expectedPermissionModule = menu.audience === 'platform' && menu.moduleKey === 'core' ? 'platform' : menu.moduleKey
+  if (permission !== null && permission.moduleKey !== expectedPermissionModule) fail('GOVERNANCE_PERMISSION_MODULE_MISMATCH')
+  if (route !== null && route !== undefined && permission !== null
+    && !route.permissionKeys.includes(permission.key)) fail('GOVERNANCE_ROUTE_PERMISSION_MISMATCH')
+
+  const icon = menu.icon === null ? null : catalog.icons.get(menu.icon)
+  if (menu.icon !== null && icon === undefined) fail('GOVERNANCE_ICON_UNDECLARED')
+
+  let reason = 'visible'
+  if (!menu.clientKeys.includes(context.clientKey)) {
+    reason = 'client_unavailable'
+  } else if (menu.moduleKey !== 'core' && !context.deploymentModules.has(menu.moduleKey)) {
+    reason = 'deployment_module_unavailable'
+  } else if (menu.moduleKey !== 'core' && context.audience === 'tenant' && !context.tenantModules.has(menu.moduleKey)) {
+    reason = 'tenant_module_disabled'
+  } else if (permission !== null && !context.permissions.has(permission.key)) {
+    reason = 'permission_not_granted'
+  }
+
+  return {
+    key: menu.key,
+    visible: reason === 'visible',
+    reason,
+    trustedPath: route?.path ?? null,
+    icon: icon ?? null,
+  }
+}

package/admin-core/src/governance/roles.ts

@@ -0,0 +1,144 @@
+import type { components } from '../generated/api'
+import { requireGovernancePermission } from './catalog'
+import type { GovernanceAudience, GovernanceCatalog } from './types'
+
+const fail = (code: string): never => { throw new Error(code) }
+
+const canonicalId = (value: string): string => {
+  if (!/^[1-9][0-9]*$/.test(value)) fail('GOVERNANCE_ROLE_INVALID')
+  return value
+}
+
+export const requireRevision = (ifMatch: string, currentRevision: number): number => {
+  if (ifMatch === '') fail('PRECONDITION_REQUIRED')
+  const match = /^"rev-([1-9][0-9]*)"$/.exec(ifMatch) ?? fail('PRECONDITION_INVALID')
+  const revision = Number(match[1])
+  if (!Number.isSafeInteger(revision) || revision !== currentRevision) fail('REVISION_MISMATCH')
+  return revision
+}
+
+export interface RolePermissionDraftInput {
+  audience: GovernanceAudience
+  roleId: string
+  currentRevision: number
+  ifMatch: string
+  permissionKeys: readonly string[]
+  availableModules: ReadonlySet<string>
+  catalog: GovernanceCatalog
+}
+
+export const createRolePermissionDraft = (input: RolePermissionDraftInput) => {
+  const keys = [...new Set(input.permissionKeys)].sort()
+  for (const key of keys) {
+    const permission = requireGovernancePermission(input.catalog, key, input.audience)
+    if (!['core', 'platform'].includes(permission.moduleKey)
+      && !input.availableModules.has(permission.moduleKey)) fail('GOVERNANCE_PERMISSION_MODULE_UNAVAILABLE')
+  }
+  return {
+    kind: 'validated-draft' as const,
+    audience: input.audience,
+    roleId: canonicalId(input.roleId),
+    expectedRevision: requireRevision(input.ifMatch, input.currentRevision),
+    payload: { permission_keys: keys } satisfies components['schemas']['ReplaceRolePermissionsRequest'],
+  }
+}
+
+type ReplaceDataPolicyRequest = components['schemas']['ReplaceDataPolicyRequest']
+type DataPolicyGroupWrite = components['schemas']['DataPolicyGroupWrite']
+type DataPolicyConditionWrite = components['schemas']['DataPolicyConditionWrite']
+type DataPolicyTargetSetWrite = components['schemas']['DataPolicyTargetSetWrite']
+
+interface DataPolicyDraftBase {
+  audience: GovernanceAudience
+  roleId: string
+  resourceKey: string
+  operation: string
+  payload: ReplaceDataPolicyRequest
+}
+
+export interface CreateDataPolicyDraftInput extends DataPolicyDraftBase {
+  mode: 'create'
+}
+
+export interface UpdateDataPolicyDraftInput extends DataPolicyDraftBase {
+  mode: 'update'
+  currentRevision: number
+  ifMatch: string
+}
+
+export type DataPolicyDraftInput = CreateDataPolicyDraftInput | UpdateDataPolicyDraftInput
+
+const text = (value: string, limit: number, code: string): string => {
+  const canonical = value.trim()
+  if (canonical === '' || canonical.length > limit || /[\u0000-\u001f\u007f]/.test(canonical)) fail(code)
+  return canonical
+}
+
+const targetSetDraft = (input: DataPolicyTargetSetWrite): DataPolicyTargetSetWrite => {
+  const targets = input.targets.map(target => ({ target_id: text(target.target_id, 128, 'DATA_POLICY_TARGETS_INVALID') }))
+  if (targets.length === 0 || targets.length > 500
+    || new Set(targets.map(target => target.target_id)).size !== targets.length) fail('DATA_POLICY_TARGETS_INVALID')
+  return {
+    name: text(input.name, 120, 'DATA_POLICY_TARGET_SET_INVALID'),
+    target_resource_key: text(input.target_resource_key, 160, 'DATA_POLICY_TARGET_SET_INVALID'),
+    targets,
+  }
+}
+
+const conditionDraft = (input: DataPolicyConditionWrite): DataPolicyConditionWrite => ({
+  condition_key: text(input.condition_key, 160, 'DATA_POLICY_CONDITION_INVALID'),
+  ...(input.target_set === undefined
+    ? {}
+    : { target_set: input.target_set === null ? null : targetSetDraft(input.target_set) }),
+})
+
+const groupDraft = (input: DataPolicyGroupWrite): DataPolicyGroupWrite => {
+  if (input.conditions.length === 0 || input.conditions.length > 20) fail('DATA_POLICY_CONDITIONS_INVALID')
+  return {
+    name: text(input.name, 120, 'DATA_POLICY_GROUP_INVALID'),
+    conditions: input.conditions.map(conditionDraft),
+  }
+}
+
+const optionalDate = (value: string | null | undefined): string | null => {
+  if (value === undefined || value === null) return null
+  if (!Number.isFinite(Date.parse(value))) fail('DATA_POLICY_PERIOD_INVALID')
+  return value
+}
+
+export const createDataPolicyDraft = (input: DataPolicyDraftInput) => {
+  if (input.audience !== 'tenant') fail('GOVERNANCE_DATA_POLICY_AUDIENCE_MISMATCH')
+  const resourceKey = text(input.resourceKey, 160, 'GOVERNANCE_OPERATION_INVALID')
+  const operation = text(input.operation, 160, 'GOVERNANCE_OPERATION_INVALID')
+  const reason = input.payload.reason === undefined || input.payload.reason === null
+    ? null
+    : text(input.payload.reason, 300, 'DATA_POLICY_REASON_INVALID')
+  const validFrom = optionalDate(input.payload.valid_from)
+  const validUntil = optionalDate(input.payload.valid_until)
+  if (validFrom !== null && validUntil !== null && Date.parse(validUntil) <= Date.parse(validFrom)) {
+    fail('DATA_POLICY_PERIOD_INVALID')
+  }
+  if (input.payload.groups.length > 50
+    || (input.payload.status === 'active' && input.payload.groups.length === 0)) fail('DATA_POLICY_GROUPS_INVALID')
+  const groups = input.payload.groups.map(groupDraft)
+  if (new Set(groups.map(group => group.name)).size !== groups.length) fail('DATA_POLICY_GROUP_INVALID')
+
+  return {
+    kind: 'validated-draft' as const,
+    mode: input.mode,
+    audience: 'tenant' as const,
+    roleId: canonicalId(input.roleId),
+    expectedRevision: input.mode === 'create'
+      ? null
+      : requireRevision(input.ifMatch, input.currentRevision),
+    resourceKey,
+    operation,
+    payload: {
+      status: input.payload.status,
+      reason,
+      valid_from: validFrom,
+      valid_until: validUntil,
+      groups,
+    } satisfies ReplaceDataPolicyRequest,
+  }
+}

package/admin-core/src/governance/types.ts

@@ -0,0 +1,64 @@
+import type { AdminNavigationRoute } from '../runtime/navigation'
+
+export type GovernanceAudience = 'tenant' | 'platform'
+
+export interface GovernancePermissionDefinition {
+  key: string
+  moduleKey: string
+  audience: GovernanceAudience
+  active: boolean
+}
+
+export interface GovernanceRouteDefinition extends AdminNavigationRoute {
+  audience: GovernanceAudience
+  moduleKey?: string
+  permissionKeys: readonly string[]
+  componentKey: string
+  clientKeys: readonly string[]
+}
+
+export interface GovernanceIconDefinition {
+  label: string
+  glyph: string
+}
+
+export interface GovernanceCatalog {
+  permissions: ReadonlyMap<string, GovernancePermissionDefinition>
+  routes: ReadonlyMap<string, GovernanceRouteDefinition>
+  icons: ReadonlyMap<string, GovernanceIconDefinition>
+}
+
+export interface GovernanceCatalogInput {
+  permissions: readonly GovernancePermissionDefinition[]
+  routes: readonly GovernanceRouteDefinition[]
+  icons: Readonly<Record<string, GovernanceIconDefinition>>
+}
+
+export interface GovernanceMenuInput {
+  key: string
+  type: 'group' | 'page' | 'link'
+  audience: GovernanceAudience
+  routeName: string | null
+  routePath: string | null
+  componentKey: string | null
+  requiredPermission: string | null
+  moduleKey: string
+  clientKeys: readonly string[]
+  icon: string | null
+}
+
+export interface GovernanceVisibilityContext {
+  audience: GovernanceAudience
+  clientKey: string
+  deploymentModules: ReadonlySet<string>
+  tenantModules: ReadonlySet<string>
+  permissions: ReadonlySet<string>
+}
+
+export interface GovernanceMenuExplanation {
+  key: string
+  visible: boolean
+  reason: string
+  trustedPath: string | null
+  icon: GovernanceIconDefinition | null
+}

package/admin-core/src/index.ts

@@ -0,0 +1,122 @@
+export const ADMIN_CORE_PACKAGE = '@peanut-admin/admin/core' as const
+export const ADMIN_CORE_VERSION = '0.1.0' as const
+
+export { createPlatformApiClient, createProtectedFetch, createTenantApiClient } from './api/client'
+export type {
+  ApiAudience,
+  AudienceApiClient,
+  AudienceApiClientOptions,
+  ProtectedFetchOptions,
+} from './api/client'
+export { createBrowserRefreshCoordinator, createMemoryRefreshCoordinator } from './api/refresh'
+export type { RefreshAttempt, RefreshCoordinator } from './api/refresh'
+export { isProblemCode, parseProblemDetails } from './api/problem'
+export type { ProblemDetails, ProblemFieldError } from './api/problem'
+export { hasAllPermissions, hasPermission, useAccess } from './access/access'
+export type { AccessHints } from './access/access'
+export {
+  evaluateRequiredPermissions,
+  permissionEvaluatorSlot,
+  PERMISSION_EVALUATOR_OVERRIDE_KEY,
+} from './access/permission-policy'
+export type { PermissionEvaluator } from './access/permission-policy'
+export {
+  usePlatformAuth,
+  usePlatformContext,
+  useTenantAuth,
+  useTenantContext,
+} from './auth/stores'
+export type { PlatformContextData, TenantContextData } from './auth/stores'
+export { isMultiTenantDeployment, isTenantAccessToken } from './auth/tenant-session'
+export type {
+  TenantAuthentication,
+  TenantChoice,
+  TenantSelection,
+  TenantSessionOutcome,
+} from './auth/tenant-session'
+export { disposeTenantState, registerTenantDisposer } from './lifecycle/tenant'
+export { createTenantLifecycle } from './lifecycle/tenant'
+export type { TenantDisposer, TenantLifecycle, TenantLifecycleTicket } from './lifecycle/tenant'
+export { createMenuRouteRegistry, defineAdminModule } from './module/contribution'
+export { collectPluginContributions, routesForTenantModules } from './module/plugin-contribution-policy'
+export { enabledTenantModulesFromRoutes } from './module/tenant-modules'
+export type {
+  AdminModuleContribution,
+  AdminModuleLocaleContribution,
+  AdminModuleRoute,
+  AdminModuleShellSlotContribution,
+  AdminModuleShellSlotName,
+  AdminModuleStoreContribution,
+  AdminRouteAccess,
+  MenuRouteRegistry,
+} from './module/contribution'
+export type { PluginFrontendContribution, PluginFrontendRoute } from './module/plugin-contribution-policy'
+export type { TenantModuleRoute } from './module/tenant-modules'
+export { defineAdminHostConfig } from './runtime/config'
+export type { AdminAudienceHostConfig, AdminHostConfig } from './runtime/config'
+export { mapAdminRuntimeError } from './runtime/errors'
+export type { AdminRuntimeErrorKind, AdminRuntimeErrorState } from './runtime/errors'
+export { runAdminRouteGuard } from './runtime/guard'
+export type {
+  AdminRouteGuardDependencies,
+  AdminRouteGuardInput,
+  AdminRouteGuardResult,
+} from './runtime/guard'
+export { createAdminNavigationRegistry } from './runtime/navigation'
+export type {
+  AdminNavigationMenuInput,
+  AdminNavigationRegistry,
+  AdminNavigationRegistryInput,
+  AdminNavigationRoute,
+} from './runtime/navigation'
+export {
+  createAdminOverrideRegistry,
+  defineAdminOverrideSlot,
+} from './runtime/overrides'
+export type {
+  AdminOverride,
+  AdminOverrideKind,
+  AdminOverrideRegistry,
+  AdminOverrideRegistryInput,
+  AdminOverrideResolution,
+  AdminOverrideResolutionMetadata,
+  AdminOverrideSlot,
+  AdminOverrideSource,
+} from './runtime/overrides'
+export { useOperationTargets } from './targets/store'
+export type {
+  OperationTargetScope,
+  TargetCardinality,
+  TargetCandidate,
+  TypedTarget,
+  TypedTargetSet,
+} from './targets/store'
+export type { components, operations, paths } from './generated/api'
+export {
+  createDataPolicyDraft,
+  createGovernanceCatalog,
+  createRolePermissionDraft,
+  explainMenuVisibility,
+  normalizeAuditFilter,
+  projectAuditDetail,
+  requireGovernancePermission,
+  requireRevision,
+} from './governance/index'
+export type {
+  GovernanceAuditDetailInput,
+  GovernanceAuditFilter,
+  GovernanceAuditOutcome,
+  GovernanceAudience,
+  GovernanceCatalog,
+  GovernanceCatalogInput,
+  GovernanceIconDefinition,
+  GovernanceMenuExplanation,
+  GovernanceMenuInput,
+  GovernancePermissionDefinition,
+  GovernanceRouteDefinition,
+  GovernanceVisibilityContext,
+  CreateDataPolicyDraftInput,
+  DataPolicyDraftInput,
+  RolePermissionDraftInput,
+  UpdateDataPolicyDraftInput,
+} from './governance/index'

package/admin-core/src/lifecycle/tenant.ts

@@ -0,0 +1,59 @@
+export type TenantDisposer = () => void | Promise<void>
+
+export interface TenantLifecycleTicket {
+  generation: number
+  signal: AbortSignal
+  isCurrent: () => boolean
+}
+
+export interface TenantLifecycle {
+  current: () => number
+  capture: () => TenantLifecycleTicket
+  invalidate: () => number
+}
+
+const tenantDisposers = new Map<string, TenantDisposer>()
+
+export const registerTenantDisposer = (key: string, disposer: TenantDisposer): (() => void) => {
+  if (key === '' || tenantDisposers.has(key)) {
+    throw new Error(`TENANT_DISPOSER_DUPLICATE: ${key}`)
+  }
+  tenantDisposers.set(key, disposer)
+
+  return () => {
+    if (tenantDisposers.get(key) === disposer) {
+      tenantDisposers.delete(key)
+    }
+  }
+}
+
+export const disposeTenantState = async (): Promise<void> => {
+  const disposers = [...tenantDisposers.values()]
+  const results = await Promise.allSettled(disposers.map(async disposer => disposer()))
+  const failure = results.find((result): result is PromiseRejectedResult => result.status === 'rejected')
+  if (failure !== undefined) throw failure.reason
+}
+
+export const createTenantLifecycle = (): TenantLifecycle => {
+  let generation = 0
+  let controller = new AbortController()
+
+  return {
+    current: () => generation,
+    capture: () => {
+      const capturedGeneration = generation
+      const signal = controller.signal
+      return {
+        generation: capturedGeneration,
+        signal,
+        isCurrent: () => capturedGeneration === generation && !signal.aborted,
+      }
+    },
+    invalidate: () => {
+      controller.abort()
+      controller = new AbortController()
+      generation += 1
+      return generation
+    },
+  }
+}