@sixb/core 0.1.11 → 0.1.13

package/src/storage/ai-cost/analytics.ts

@@ -1,9 +1,4 @@
-import {
-  type AiModelCallUsage,
-  type AiModelCallUsageRecord,
-  aggregateAiModelCallUsage,
-  normalizeAiModelCallUsage,
-} from "../ai-usage"
+import { type AiModelCallUsageRecord, normalizeAiModelCallUsage } from "../ai-usage"
 import type {
   AiAccountingAgentBreakdown,
   AiAccountingAggregate,
@@ -65,6 +60,7 @@ export interface AiAccountingAggregateFragment {
   readonly modelCallCount: string
   readonly usage: {
     readonly reportedCallCount: string
+    readonly completeCallCount: string
     readonly inputTokens: AiAccountingUsageMeterFragment
     readonly outputTokens: AiAccountingUsageMeterFragment
     readonly uncachedInputTokens: AiAccountingUsageMeterFragment
@@ -358,9 +354,21 @@ export function aiAccountingBucketStart(at: Date, bucket: AiAccountingBucket): D
 function aggregateAccountingItems(
   items: readonly AiAccountingRecordSetItem[]
 ): AiAccountingAggregate {
+  const value = aggregateFragmentAccumulator()
+  value.modelCallCount = BigInt(items.length)
+  for (const item of items) {
+    const usage = normalizeAiModelCallUsage(item.usage.usage)
+    if (usage.reportingStatus !== "unavailable") value.reportedUsageCallCount += 1n
+    if (usage.reportingStatus === "complete") value.completeUsageCallCount += 1n
+    for (const field of AGGREGATE_USAGE_FIELDS) {
+      if (usage[field] === undefined) continue
+      value.usage[field].presentCallCount += 1n
+      value.usage[field].total += BigInt(usage[field])
+    }
+  }
   return {
     modelCallCount: items.length,
-    usage: aggregateAiModelCallUsage(items.map((item) => item.usage.usage)),
+    ...finishAggregateUsage(value),
     costs: aggregateCosts(items),
   }
 }
@@ -405,6 +413,7 @@ type AggregateUsageField = (typeof AGGREGATE_USAGE_FIELDS)[number]
 interface AggregateFragmentAccumulator {
   modelCallCount: bigint
   reportedUsageCallCount: bigint
+  completeUsageCallCount: bigint
   usage: Record<AggregateUsageField, { presentCallCount: bigint; total: bigint }>
   amounts: Map<string, bigint>
   ratedCallCount: bigint
@@ -416,6 +425,7 @@ function aggregateFragmentAccumulator(): AggregateFragmentAccumulator {
   return {
     modelCallCount: 0n,
     reportedUsageCallCount: 0n,
+    completeUsageCallCount: 0n,
     usage: Object.fromEntries(
       AGGREGATE_USAGE_FIELDS.map((field) => [field, { presentCallCount: 0n, total: 0n }])
     ) as AggregateFragmentAccumulator["usage"],
@@ -446,6 +456,10 @@ function appendAggregateFragment(
     fragment.usage.reportedCallCount,
     "reported usage call count"
   )
+  target.completeUsageCallCount += naturalBigInt(
+    fragment.usage.completeCallCount,
+    "complete usage call count"
+  )
   for (const field of AGGREGATE_USAGE_FIELDS) {
     const source = fragment.usage[field]
     const presentCallCount = naturalBigInt(source.presentCallCount, `${field} call count`)
@@ -473,6 +487,7 @@ function finishAggregateFragment(value: AggregateFragmentAccumulator): AiAccount
   if (
     classifiedCallCount !== value.modelCallCount ||
     value.reportedUsageCallCount > value.modelCallCount ||
+    value.completeUsageCallCount > value.reportedUsageCallCount ||
     AGGREGATE_USAGE_FIELDS.some(
       (field) => value.usage[field].presentCallCount > value.modelCallCount
     )
@@ -480,22 +495,9 @@ function finishAggregateFragment(value: AggregateFragmentAccumulator): AiAccount
     throw new TypeError("[Sixb] AI accounting SQL aggregate counts are inconsistent.")
   }
   const modelCallCount = safeAggregateNumber(value.modelCallCount, "model-call count")
-  const usageInput: Partial<Record<AggregateUsageField, number>> = {}
-  if (value.modelCallCount > 0n) {
-    for (const field of AGGREGATE_USAGE_FIELDS) {
-      const aggregate = value.usage[field]
-      if (aggregate.presentCallCount === value.modelCallCount) {
-        usageInput[field] = safeAggregateNumber(aggregate.total, field)
-      }
-    }
-  }
-  let usage: AiModelCallUsage = normalizeAiModelCallUsage(usageInput)
-  if (usage.reportingStatus === "unavailable" && value.reportedUsageCallCount > 0n) {
-    usage = { ...usage, reportingStatus: "partial" }
-  }
   return {
     modelCallCount,
-    usage,
+    ...finishAggregateUsage(value),
     costs: {
       amounts: [...value.amounts]
         .sort(([left], [right]) => left.localeCompare(right))
@@ -510,6 +512,42 @@ function finishAggregateFragment(value: AggregateFragmentAccumulator): AiAccount
   }
 }
 
+function finishAggregateUsage(
+  value: AggregateFragmentAccumulator
+): Pick<AiAccountingAggregate, "usage" | "usageCoverage"> {
+  const counts: Partial<Record<AggregateUsageField | "totalTokens", number>> = {}
+  const fieldCallCounts = {} as Record<AggregateUsageField, number>
+  for (const field of AGGREGATE_USAGE_FIELDS) {
+    const aggregate = value.usage[field]
+    fieldCallCounts[field] = safeAggregateNumber(aggregate.presentCallCount, `${field} call count`)
+    if (aggregate.presentCallCount > 0n) {
+      counts[field] = safeAggregateNumber(aggregate.total, field)
+    }
+  }
+  // Only the top-level meters contribute: cache/reasoning partitions overlap them.
+  if (counts.inputTokens !== undefined || counts.outputTokens !== undefined) {
+    counts.totalTokens = safeAggregateNumber(
+      value.usage.inputTokens.total + value.usage.outputTokens.total,
+      "totalTokens"
+    )
+  }
+  return {
+    usage: {
+      ...counts,
+      reportingStatus:
+        value.reportedUsageCallCount === 0n
+          ? "unavailable"
+          : value.completeUsageCallCount === value.modelCallCount
+            ? "complete"
+            : "partial",
+    },
+    usageCoverage: {
+      completeCallCount: safeAggregateNumber(value.completeUsageCallCount, "complete call count"),
+      fieldCallCounts,
+    },
+  }
+}
+
 function naturalBigInt(value: string, field: string): bigint {
   if (!/^(0|[1-9]\d*)$/.test(value)) {
     throw new TypeError(`[Sixb] AI accounting SQL ${field} must be a natural integer.`)

package/src/storage/ai-cost/index.ts

@@ -14,6 +14,7 @@ export type {
   AiAccountingOverview,
   AiAccountingRange,
   AiAccountingTimeBucket,
+  AiAccountingUsage,
   AiAccountingWorkflowBreakdown,
   AiBillableMeter,
   AiBillingIdentity,

package/src/storage/ai-cost/types.ts

@@ -1,4 +1,8 @@
-import type { AiModelCallUsageRecord } from "../ai-usage"
+import type {
+  AiModelCallUsageInput,
+  AiModelCallUsageRecord,
+  AiUsageReportingStatus,
+} from "../ai-usage"
 
 /** Token meters supported by deterministic local rate cards. */
 export type AiBillableMeter =
@@ -141,9 +145,22 @@ export interface ListAiModelCallAccountingInput extends AiAccountingRange {
   readonly offset?: number
 }
 
+/** Observed meter sums. Unreported meters are absent; incomplete sums are lower bounds. */
+export interface AiAccountingUsage extends AiModelCallUsageInput {
+  /** Sum of available input and output counts, including one-sided reports. */
+  readonly totalTokens?: number
+  /** Complete only when every call reports both input and output; details have separate coverage. */
+  readonly reportingStatus: AiUsageReportingStatus
+}
+
 export interface AiAccountingAggregate {
   readonly modelCallCount: number
-  readonly usage: AiModelCallUsageRecord["usage"]
+  readonly usage: AiAccountingUsage
+  readonly usageCoverage: {
+    /** Calls reporting both inputTokens and outputTokens. */
+    readonly completeCallCount: number
+    readonly fieldCallCounts: Readonly<Record<keyof AiModelCallUsageInput, number>>
+  }
   readonly costs: AiCostSummary
 }
 

package/src/storage/auth/in-memory/access-tokens.ts

@@ -38,8 +38,11 @@ export class InMemoryAuthAccessTokenStore implements AuthAccessTokenStore {
     const rows = [...this.state.accessTokens.values()]
       .filter((token) => token.projectId === input.projectId)
       .filter((token) => input.kind === undefined || token.kind === input.kind)
-      .filter((token) => input.subjectType === undefined || token.subjectType === input.subjectType)
-      .filter((token) => input.subjectId === undefined || token.subjectId === input.subjectId)
+      .filter(
+        (token) =>
+          input.subject === undefined ||
+          (token.subject.type === input.subject.type && token.subject.id === input.subject.id)
+      )
       .filter((token) => input.includeRevoked || !token.revokedAt)
       .sort((a, b) => compareByCreatedAt(a, b, order))
     const page = rows.slice(offset, input.limit === undefined ? undefined : offset + input.limit)

package/src/storage/auth/in-memory/auth-storage.ts

@@ -30,7 +30,6 @@ import {
   cloneRecord,
   consumeMagicLinkRecord,
   consumeOidcAttemptRecord,
-  createAccessTokenRecord,
   createAuthStorageState,
   createSessionRecord,
   deviceAuthorizationKey,
@@ -138,24 +137,22 @@ export class InMemoryAuthStorage implements AuthStorage {
       )
     }
     if (
-      input.accessToken.projectId !== input.projectId ||
-      input.accessToken.subjectType !== "user" ||
-      input.accessToken.subjectId !== authorization.approvedUserId ||
-      input.accessToken.createdBySessionId !== authorization.approvedSessionId
+      input.session.projectId !== input.projectId ||
+      input.session.userId !== authorization.approvedUserId
     ) {
       throw new AuthStorageError(
         "invalid_device_authorization",
-        "[Sixb] Device access token is invalid."
+        "[Sixb] Device session is invalid."
       )
     }
-    const accessToken = createAccessTokenRecord(this.state, input.accessToken)
+    const session = createSessionRecord(this.state, input.session)
     const consumed = {
       ...authorization,
       status: "consumed" as const,
       consumedAt: new Date(input.completedAt),
     }
     this.state.deviceAuthorizations.set(key, cloneRecord(consumed))
-    return { authorization: cloneRecord(consumed), accessToken: cloneRecord(accessToken) }
+    return { authorization: cloneRecord(consumed), session: cloneRecord(session) }
   }
 
   async completeMagicLinkSignIn(

package/src/storage/auth/in-memory/device-authorizations.ts

@@ -45,8 +45,6 @@ export class InMemoryAuthDeviceAuthorizationStore implements AuthDeviceAuthoriza
       deviceCodeHash: assertNonEmpty(input.deviceCodeHash, "Device code hash"),
       userCode: assertNonEmpty(input.userCode, "User code"),
       clientName: assertNonEmpty(input.clientName, "Client name"),
-      tokenName: assertNonEmpty(input.tokenName, "Token name"),
-      tokenExpiresAt: new Date(input.tokenExpiresAt),
       status: "pending",
       createdAt: new Date(input.createdAt),
       expiresAt: new Date(input.expiresAt),

package/src/storage/auth/in-memory/sessions.ts

@@ -1,6 +1,11 @@
 import type { AuthSessionAudience } from "../../../auth/audience"
 import { AuthStorageError } from "../errors"
-import type { AuthSessionStore, CreateAuthSessionInput, SessionRecord } from "../types"
+import type {
+  AuthSessionStore,
+  CreateAuthSessionInput,
+  RotateSessionRefreshTokenResult,
+  SessionRecord,
+} from "../types"
 import type { AuthStorageState } from "./shared"
 import {
   cloneDate,
@@ -73,6 +78,7 @@ export class InMemoryAuthSessionStore implements AuthSessionStore {
     const session = this.state.sessions.get(sessionKey(params.projectId, params.id))
     if (
       !session ||
+      session.bearer ||
       session.audience !== params.audience ||
       session.tokenHash !== params.tokenHash ||
       !isActiveSession(session, params.now)
@@ -83,6 +89,67 @@ export class InMemoryAuthSessionStore implements AuthSessionStore {
     return cloneRecord(session)
   }
 
+  async findValidByAccessTokenHash(params: {
+    readonly projectId: string
+    readonly id: string
+    readonly tokenHash: string
+    readonly now: Date
+  }): Promise<SessionRecord | null> {
+    const session = this.state.sessions.get(sessionKey(params.projectId, params.id))
+    if (
+      !session?.bearer ||
+      session.tokenHash !== params.tokenHash ||
+      session.bearer.accessExpiresAt <= params.now ||
+      !isActiveSession(session, params.now)
+    ) {
+      return null
+    }
+
+    return cloneRecord(session)
+  }
+
+  async rotateRefreshToken(
+    params: Parameters<AuthSessionStore["rotateRefreshToken"]>[0]
+  ): Promise<RotateSessionRefreshTokenResult> {
+    const key = sessionKey(params.projectId, params.id)
+    const session = this.state.sessions.get(key)
+    if (!session?.bearer || !isActiveSession(session, params.now)) {
+      return { status: "invalid" }
+    }
+
+    const { bearer } = session
+    const replacedRecently =
+      bearer.previousRefreshTokenHash === params.refreshTokenHash &&
+      bearer.refreshedAt !== undefined &&
+      params.now.getTime() - bearer.refreshedAt.getTime() <= params.reuseGraceMs
+    if (bearer.refreshTokenHash !== params.refreshTokenHash && !replacedRecently) {
+      if (bearer.previousRefreshTokenHash !== params.refreshTokenHash) {
+        return { status: "invalid" }
+      }
+      this.state.sessions.set(key, cloneRecord({ ...session, revokedAt: cloneDate(params.now) }))
+      return { status: "reused" }
+    }
+
+    const requestedExpiresAt = session.absoluteExpiresAt
+      ? new Date(Math.min(params.next.expiresAt.getTime(), session.absoluteExpiresAt.getTime()))
+      : params.next.expiresAt
+    const next: SessionRecord = {
+      ...session,
+      tokenHash: params.next.tokenHash,
+      expiresAt: new Date(Math.max(session.expiresAt.getTime(), requestedExpiresAt.getTime())),
+      lastSeenAt: cloneDate(params.now),
+      bearer: {
+        clientName: bearer.clientName,
+        accessExpiresAt: cloneDate(params.next.accessExpiresAt),
+        refreshTokenHash: params.next.refreshTokenHash,
+        previousRefreshTokenHash: bearer.refreshTokenHash,
+        refreshedAt: cloneDate(params.now),
+      },
+    }
+    this.state.sessions.set(key, cloneRecord(next))
+    return { status: "rotated", session: cloneRecord(next) }
+  }
+
   async renewIfValid(params: {
     readonly projectId: string
     readonly id: string
@@ -95,6 +162,7 @@ export class InMemoryAuthSessionStore implements AuthSessionStore {
     const session = this.state.sessions.get(key)
     if (
       !session ||
+      session.bearer ||
       session.audience !== params.audience ||
       session.tokenHash !== params.tokenHash ||
       !isActiveSession(session, params.now)

package/src/storage/auth/in-memory/shared.ts

@@ -320,6 +320,13 @@ export function createSessionRecord(
     absoluteExpiresAt: input.absoluteExpiresAt ? cloneDate(input.absoluteExpiresAt) : undefined,
     userAgent: input.userAgent,
     ipAddress: input.ipAddress,
+    bearer: input.bearer
+      ? {
+          clientName: assertNonEmpty(input.bearer.clientName, "Session client name"),
+          accessExpiresAt: cloneDate(input.bearer.accessExpiresAt),
+          refreshTokenHash: assertNonEmpty(input.bearer.refreshTokenHash, "Refresh token hash"),
+        }
+      : undefined,
   }
 
   state.sessions.set(sessionKey(projectId, id), cloneRecord(session))
@@ -398,11 +405,11 @@ export function createAccessTokenRecord(
   const id = assertNonEmpty(input.id, "Access token id")
   const projectId = assertNonEmpty(input.projectId, "Project id")
   const name = assertNonEmpty(input.name, "Access token name")
-  const subjectId = assertNonEmpty(input.subjectId, "Access token subject id")
+  const subjectId = assertNonEmpty(input.subject.id, "Access token subject id")
   const tokenHash = assertNonEmpty(input.tokenHash, "Access token hash")
 
-  assertAccessTokenSubject(input.kind, input.subjectType)
-  assertAccessTokenSubjectExists(state, projectId, input.subjectType, subjectId)
+  assertAccessTokenSubject(input.kind, input.subject.type)
+  assertAccessTokenSubjectExists(state, projectId, input.subject.type, subjectId)
 
   const key = accessTokenKey(projectId, id)
   if (state.accessTokens.has(key)) {
@@ -417,8 +424,7 @@ export function createAccessTokenRecord(
     projectId,
     name,
     kind: input.kind,
-    subjectType: input.subjectType,
-    subjectId,
+    subject: { type: input.subject.type, id: subjectId },
     tokenHash,
     groupIds: normalizeOptionalGroupIds(input.groupIds),
     createdByPrincipal: input.createdByPrincipal,
@@ -484,7 +490,7 @@ export function removeGroupMembershipRecord(
 
 function assertAccessTokenSubject(
   kind: CreateAuthAccessTokenInput["kind"],
-  subjectType: CreateAuthAccessTokenInput["subjectType"]
+  subjectType: CreateAuthAccessTokenInput["subject"]["type"]
 ): void {
   if (
     (kind === "personal" && subjectType === "user") ||
@@ -502,7 +508,7 @@ function assertAccessTokenSubject(
 function assertAccessTokenSubjectExists(
   state: AuthStorageState,
   projectId: string,
-  subjectType: CreateAuthAccessTokenInput["subjectType"],
+  subjectType: CreateAuthAccessTokenInput["subject"]["type"],
   subjectId: string
 ): void {
   if (subjectType === "user") {

package/src/storage/auth/index.ts

@@ -3,7 +3,6 @@ export { AuthStorageError } from "./errors"
 export { InMemoryAuthStorage } from "./in-memory"
 export type {
   AccessTokenRecord,
-  AccessTokenSubjectType,
   AuthAccessTokenStore,
   AuthDeviceAuthorizationStore,
   AuthGroupMembershipStore,
@@ -16,6 +15,7 @@ export type {
   AuthStorage,
   AuthUserIdentityStore,
   AuthUserStore,
+  BearerSessionState,
   CompleteAuthSessionInput,
   CompleteDeviceAuthorizationInput,
   CompleteDeviceAuthorizationResult,
@@ -47,6 +47,7 @@ export type {
   MagicLinkRecord,
   OidcAuthorizationAttemptRecord,
   ReconcileAuthServiceAccountGroupMembershipsInput,
+  RotateSessionRefreshTokenResult,
   ServiceAccountGroupMembershipRecord,
   ServiceAccountRecord,
   ServiceAccountStatus,

package/src/storage/auth/types.ts

@@ -1,10 +1,10 @@
 import type { AccessTokenKind, AuthSessionAudience, Principal } from "../../auth"
+import type { AuthorizablePrincipal } from "../../execution/types"
 
 export type UserStatus = "active" | "suspended"
 export type ServiceAccountStatus = "active" | "suspended"
 export type InvitationStatus = "pending" | "accepted" | "revoked"
 export type GroupMembershipSource = "invitation" | "manual" | "agent"
-export type AccessTokenSubjectType = "user" | "serviceAccount"
 export type DeviceAuthorizationStatus = "pending" | "approved" | "denied" | "consumed"
 export const MAX_PENDING_DEVICE_AUTHORIZATIONS = 100
 
@@ -54,6 +54,7 @@ export interface SessionRecord {
   readonly projectId: string
   readonly userId: string
   readonly strategyId: string
+  /** The web app a browser session belongs to. A bearer session belongs to none and ignores it. */
   readonly audience: AuthSessionAudience
   readonly tokenHash: string
   readonly createdAt: Date
@@ -65,15 +66,36 @@ export interface SessionRecord {
   // view. Display only — never used for authorization.
   readonly userAgent?: string
   readonly ipAddress?: string
+  /** Present when a native client holds the session as bearer tokens instead of a cookie. */
+  readonly bearer?: BearerSessionState
 }
 
+/**
+ * A native client's credentials for its session. `tokenHash` on the session is the current access
+ * token's hash; the refresh token rotates on every refresh.
+ */
+export interface BearerSessionState {
+  /** Self-reported client label, such as "sixb CLI on alex-mbp". Display only. */
+  readonly clientName: string
+  readonly accessExpiresAt: Date
+  readonly refreshTokenHash: string
+  /** The refresh token the last rotation replaced, accepted briefly in case its response was lost. */
+  readonly previousRefreshTokenHash?: string
+  readonly refreshedAt?: Date
+}
+
+export type RotateSessionRefreshTokenResult =
+  | { readonly status: "rotated"; readonly session: SessionRecord }
+  /** A replaced refresh token came back after the grace window; the session is now revoked. */
+  | { readonly status: "reused" }
+  | { readonly status: "invalid" }
+
 export interface AccessTokenRecord {
   readonly id: string
   readonly projectId: string
   readonly name: string
   readonly kind: AccessTokenKind
-  readonly subjectType: AccessTokenSubjectType
-  readonly subjectId: string
+  readonly subject: AuthorizablePrincipal
   readonly tokenHash: string
   /**
    * Optional group constraint. Undefined means "inherit every current group";
@@ -148,8 +170,6 @@ export interface DeviceAuthorizationRecord {
   readonly deviceCodeHash: string
   readonly userCode: string
   readonly clientName: string
-  readonly tokenName: string
-  readonly tokenExpiresAt: Date
   readonly status: DeviceAuthorizationStatus
   readonly approvedUserId?: string
   readonly approvedSessionId?: string
@@ -273,6 +293,7 @@ export interface CreateAuthSessionInput {
   readonly absoluteExpiresAt?: Date
   readonly userAgent?: string
   readonly ipAddress?: string
+  readonly bearer?: Pick<BearerSessionState, "clientName" | "accessExpiresAt" | "refreshTokenHash">
 }
 
 export interface CreateAuthAccessTokenInput {
@@ -280,8 +301,7 @@ export interface CreateAuthAccessTokenInput {
   readonly projectId: string
   readonly name: string
   readonly kind: AccessTokenKind
-  readonly subjectType: AccessTokenSubjectType
-  readonly subjectId: string
+  readonly subject: AuthorizablePrincipal
   readonly tokenHash: string
   readonly groupIds?: readonly string[]
   readonly createdByPrincipal?: Principal
@@ -293,8 +313,7 @@ export interface CreateAuthAccessTokenInput {
 export interface ListAuthAccessTokensInput {
   readonly projectId: string
   readonly kind?: AccessTokenKind
-  readonly subjectType?: AccessTokenSubjectType
-  readonly subjectId?: string
+  readonly subject?: AuthorizablePrincipal
   readonly includeRevoked?: boolean
   readonly limit?: number
   readonly offset?: number
@@ -385,8 +404,6 @@ export interface CreateDeviceAuthorizationInput {
   readonly deviceCodeHash: string
   readonly userCode: string
   readonly clientName: string
-  readonly tokenName: string
-  readonly tokenExpiresAt: Date
   readonly createdAt: Date
   readonly expiresAt: Date
 }
@@ -395,13 +412,14 @@ export interface CompleteDeviceAuthorizationInput {
   readonly projectId: string
   readonly id: string
   readonly deviceCodeHash: string
-  readonly accessToken: CreateAuthAccessTokenInput
+  /** The bearer session to start for the approving user. */
+  readonly session: CreateAuthSessionInput & { readonly bearer: BearerSessionState }
   readonly completedAt: Date
 }
 
 export interface CompleteDeviceAuthorizationResult {
   readonly authorization: DeviceAuthorizationRecord
-  readonly accessToken: AccessTokenRecord
+  readonly session: SessionRecord
 }
 
 export interface CompleteMagicLinkSignInInput {
@@ -523,6 +541,7 @@ export interface AuthSessionStore {
     readonly userId: string
     readonly now: Date
   }): Promise<readonly SessionRecord[]>
+  /** A live browser (cookie) session whose secret hashes to `tokenHash`. */
   findValidByTokenHash(params: {
     readonly projectId: string
     readonly id: string
@@ -530,6 +549,31 @@ export interface AuthSessionStore {
     readonly tokenHash: string
     readonly now: Date
   }): Promise<SessionRecord | null>
+  /** A live bearer session whose current, unexpired access token hashes to `tokenHash`. */
+  findValidByAccessTokenHash(params: {
+    readonly projectId: string
+    readonly id: string
+    readonly tokenHash: string
+    readonly now: Date
+  }): Promise<SessionRecord | null>
+  /**
+   * Atomically replace a live bearer session's tokens. The current refresh token rotates; the one
+   * it replaced also rotates within `reuseGraceMs` of that replacement. Presenting it later revokes
+   * the session. `next.expiresAt` extends the idle deadline, never past the absolute one.
+   */
+  rotateRefreshToken(params: {
+    readonly projectId: string
+    readonly id: string
+    readonly refreshTokenHash: string
+    readonly now: Date
+    readonly reuseGraceMs: number
+    readonly next: {
+      readonly tokenHash: string
+      readonly accessExpiresAt: Date
+      readonly refreshTokenHash: string
+      readonly expiresAt: Date
+    }
+  }): Promise<RotateSessionRefreshTokenResult>
   renewIfValid(params: {
     readonly projectId: string
     readonly id: string

package/src/storage/executions/provider.ts

@@ -1,4 +1,5 @@
-import type { TrustedPrimitiveKind } from "../../execution/types"
+import { kernelOperationFromId, kernelOperationId } from "../../execution/kernel-operation"
+import type { KernelOperation, TrustedPrimitiveKind } from "../../execution/types"
 import { ExecutionStorageError } from "./errors"
 import type { CreateExecutionInput, ExecutionRecord } from "./types"
 import { normalizeExecutionRecord } from "./validation"
@@ -16,7 +17,14 @@ export interface ExecutionStorageRow {
   readonly id: string
   readonly executorKind: "agent" | "kernel" | "request" | TrustedPrimitiveKind
   readonly executorId: string
-  readonly sourceKind: "datasetVersion" | "event" | "execution" | "http" | "schedule" | "webhook"
+  readonly sourceKind:
+    | "ontologyCommit"
+    | "datasetVersion"
+    | "event"
+    | "execution"
+    | "http"
+    | "schedule"
+    | "webhook"
   readonly sourceId: string
   readonly requestedByUserId: string | null
   readonly requestedByServiceAccountId: string | null
@@ -31,7 +39,7 @@ export interface ExecutionStorageRow {
   readonly authorityAccessTokenId: string | null
   readonly authorityPrimitiveKind: TrustedPrimitiveKind | null
   readonly authorityPrimitiveId: string | null
-  readonly authorityKernelOperation: "ontology.recover" | null
+  readonly authorityKernelOperation: KernelOperation["type"] | null
   readonly authorityDelegationKind: "share" | null
   readonly authorityDelegationId: string | null
   readonly authorityDelegationSessionId: string | null
@@ -108,7 +116,7 @@ function flattenExecutor(
     case "agent":
       return { executorKind: "agent", executorId: record.executor.runId }
     case "kernel":
-      return { executorKind: "kernel", executorId: record.executor.operation.recoveryId }
+      return { executorKind: "kernel", executorId: kernelOperationId(record.executor.operation) }
   }
 }
 
@@ -116,6 +124,8 @@ function flattenSource(
   record: ExecutionRecord
 ): Pick<ExecutionStorageRow, "sourceId" | "sourceKind"> {
   switch (record.source.type) {
+    case "ontologyCommit":
+      return { sourceKind: "ontologyCommit", sourceId: record.source.commitId }
     case "http":
       return { sourceKind: "http", sourceId: record.source.requestId }
     case "webhook":
@@ -219,10 +229,10 @@ function inflateExecutor(row: ExecutionStorageRow): CreateExecutionInput["execut
     case "kernel":
       return {
         type: "kernel",
-        operation: {
-          type: requireValue(row.authorityKernelOperation, "authority kernel operation"),
-          recoveryId: row.executorId,
-        },
+        operation: kernelOperationFromId(
+          requireValue(row.authorityKernelOperation, "authority kernel operation"),
+          row.executorId
+        ),
       }
     default:
       return { type: "primitive", kind: row.executorKind, runId: row.executorId }
@@ -231,6 +241,8 @@ function inflateExecutor(row: ExecutionStorageRow): CreateExecutionInput["execut
 
 function inflateSource(row: ExecutionStorageRow): CreateExecutionInput["source"] {
   switch (row.sourceKind) {
+    case "ontologyCommit":
+      return { type: "ontologyCommit", commitId: row.sourceId }
     case "http":
       return { type: "http", requestId: row.sourceId }
     case "webhook":
@@ -307,10 +319,10 @@ function inflateAuthority(row: ExecutionStorageRow): CreateExecutionInput["autho
     case "kernel":
       return {
         type: "kernel",
-        operation: {
-          type: requireValue(row.authorityKernelOperation, "authority kernel operation"),
-          recoveryId: row.executorId,
-        },
+        operation: kernelOperationFromId(
+          requireValue(row.authorityKernelOperation, "authority kernel operation"),
+          row.executorId
+        ),
       }
     case "disabled":
       return { type: "disabled" }

package/src/storage/executions/types.ts

@@ -17,6 +17,7 @@ export type DurableExecutionExecutor =
  * is attempt transport and is never persisted here.
  */
 export type DurableExecutionSource =
+  | { readonly type: "ontologyCommit"; readonly commitId: string }
   | { readonly type: "http"; readonly requestId: string }
   | { readonly type: "webhook"; readonly deliveryId: string }
   | { readonly type: "schedule"; readonly eventId: string }