@sixb/core 0.1.11 → 0.1.13

package/src/storage/executions/validation.ts

@@ -1,5 +1,6 @@
 import { isDeepStrictEqual } from "node:util"
 import { normalizeRequesterGroupIds, snapshotRequesterGroupIds } from "../../auth/attribution"
+import { kernelOperationId } from "../../execution/kernel-operation"
 import type {
   AuthorizablePrincipal,
   AuthorizationRef,
@@ -134,6 +135,9 @@ function assertExecutor(executor: DurableExecutionExecutor): void {
 
 function assertSource(source: DurableExecutionSource): void {
   switch (source.type) {
+    case "ontologyCommit":
+      assertNonBlank(source.commitId, "Execution source commit id")
+      return
     case "http":
       assertNonBlank(source.requestId, "Execution source request id")
       return
@@ -336,7 +340,7 @@ async function validateCredential(
       `[Sixb] Authority access token '${credential.id}' does not exist in project '${record.projectId}'.`
     )
   }
-  if (token.subjectType !== principal.type || token.subjectId !== principal.id) {
+  if (!principalsEqual(token.subject, principal)) {
     throw new ExecutionStorageError(
       "invalid_credential",
       `[Sixb] Authority access token '${credential.id}' does not belong to principal '${principal.id}'.`
@@ -427,10 +431,10 @@ function assertPrincipal(principal: AuthorizablePrincipal, label: string): void
 }
 
 function assertKernelOperation(operation: KernelOperation, label: string): void {
-  if (operation.type !== "ontology.recover") {
+  if (operation.type !== "ontology.recover" && operation.type !== "ontology.indexVectors") {
     invalid(`${label} has unsupported type '${String((operation as { type?: unknown }).type)}'.`)
   }
-  assertNonBlank(operation.recoveryId, `${label} recovery id`)
+  assertNonBlank(kernelOperationId(operation), `${label} operation id`)
 }
 
 function assertTrustedPrimitiveKind(value: string, label: string): void {
@@ -459,7 +463,7 @@ function principalsEqual(
 }
 
 function kernelOperationsEqual(left: KernelOperation, right: KernelOperation): boolean {
-  return left.type === right.type && left.recoveryId === right.recoveryId
+  return left.type === right.type && kernelOperationId(left) === kernelOperationId(right)
 }
 
 function invalid(message: string): never {

package/src/storage/file-upload-sessions/in-memory.ts

@@ -1,32 +1,37 @@
-import type { Principal } from "../../auth"
-import type { FileRef, SignedBlobUploadPart } from "../../blob-storage"
-import { FileUploadSessionError } from "./errors"
+import {
+  DurableFileUploadSessions,
+  type FileUploadSessionPersistence,
+  type FileUploadSessionPersistenceBackend,
+} from "./provider"
 import type {
   CreateFileUploadSessionInput,
   FileUploadSession,
-  FileUploadSessionStore,
+  ListAbandonedFileUploadSessionsInput,
 } from "./types"
-import {
-  createFileUploadId,
-  isFileUploadSessionExpired,
-  isTerminalFileUploadSessionExpired,
-  principalKey,
-  shouldDeleteFileUploadSession,
-} from "./utils"
+import { isAbandonedFileUploadSession, shouldDeleteFileUploadSession } from "./utils"
 
 export type InMemoryFileUploadSessionsSnapshot = Map<string, FileUploadSession>
 
 /**
- * In-memory {@link FileUploadSessionStore}.
+ * In-memory {@link FileUploadSessionStore}: the shared durable state machine over a Map.
  *
- * Sessions live only in this process's memory: they do not survive a restart and
- * are not shared across instances. Staged/direct-put uploads therefore require a
- * single-instance deployment for now; a durable (Pg/Sqlite) store is a follow-up.
- * Expired sessions are reaped opportunistically on `create` and on demand via
- * `cleanupExpired` (there is no background sweeper).
+ * Sessions live only in this process's memory: they do not survive a restart and are not
+ * shared across instances, so staged uploads need a single instance. `@sixb/pg` and
+ * `@sixb/sqlite` provide durable stores. Reapable sessions are also reaped on `create`.
  */
-export class InMemoryFileUploadSessions implements FileUploadSessionStore {
-  private readonly sessionsById = new Map<string, FileUploadSession>()
+export class InMemoryFileUploadSessions extends DurableFileUploadSessions {
+  private readonly sessionsById: Map<string, FileUploadSession>
+
+  constructor() {
+    const sessionsById = new Map<string, FileUploadSession>()
+    super(new InMemoryFileUploadSessionBackend(sessionsById))
+    this.sessionsById = sessionsById
+  }
+
+  override async create(input: CreateFileUploadSessionInput): Promise<FileUploadSession> {
+    await this.cleanupExpired()
+    return super.create(input)
+  }
 
   snapshot(): InMemoryFileUploadSessionsSnapshot {
     return structuredClone(this.sessionsById)
@@ -38,100 +43,63 @@ export class InMemoryFileUploadSessions implements FileUploadSessionStore {
       this.sessionsById.set(id, structuredClone(session))
     }
   }
+}
 
-  async create(input: CreateFileUploadSessionInput): Promise<FileUploadSession> {
-    await this.cleanupExpired()
+class InMemoryFileUploadSessionBackend implements FileUploadSessionPersistenceBackend {
+  private readonly persistence: FileUploadSessionPersistence
+  // Every await yields; chaining transactions keeps read-modify-write atomic.
+  private tail: Promise<unknown> = Promise.resolve()
 
-    const session: FileUploadSession = {
-      id: input.id ?? createFileUploadId(),
-      projectId: input.projectId,
-      principalKey: principalKey(input.principal),
-      strategy: input.strategy,
-      status: "pending",
-      ...(input.fileName === undefined ? {} : { fileName: input.fileName }),
-      ...(input.mediaType === undefined ? {} : { mediaType: input.mediaType }),
-      ...(input.logicalPath === undefined ? {} : { logicalPath: input.logicalPath }),
-      ...(input.expectedSizeBytes === undefined
-        ? {}
-        : { expectedSizeBytes: input.expectedSizeBytes }),
-      ...(input.expectedDigest === undefined ? {} : { expectedDigest: input.expectedDigest }),
-      ...(input.providerUpload === undefined ? {} : { providerUpload: input.providerUpload }),
-      signedParts: [],
-      createdAt: new Date(),
-      expiresAt: input.expiresAt,
-    }
+  constructor(sessionsById: Map<string, FileUploadSession>) {
+    this.persistence = new InMemoryFileUploadSessionPersistence(sessionsById)
+  }
 
-    this.sessionsById.set(session.id, session)
-    return session
+  read<T>(run: (persistence: FileUploadSessionPersistence) => Promise<T>): Promise<T> {
+    return run(this.persistence)
   }
 
-  async getForPrincipal(uploadId: string, principal: Principal): Promise<FileUploadSession> {
-    const session = this.sessionsById.get(uploadId)
-    if (!session || session.principalKey !== principalKey(principal)) {
-      throw new FileUploadSessionError("not_found", "File upload session not found.")
-    }
+  transaction<T>(run: (persistence: FileUploadSessionPersistence) => Promise<T>): Promise<T> {
+    const result = this.tail.then(() => run(this.persistence))
+    this.tail = result.catch(() => undefined)
+    return result
+  }
+}
 
-    const nowMs = Date.now()
-    if (isFileUploadSessionExpired(session, nowMs)) {
-      this.sessionsById.delete(uploadId)
-      throw new FileUploadSessionError("expired", "File upload session has expired.")
-    }
+class InMemoryFileUploadSessionPersistence implements FileUploadSessionPersistence {
+  constructor(private readonly sessionsById: Map<string, FileUploadSession>) {}
 
-    if (isTerminalFileUploadSessionExpired(session, nowMs)) {
-      this.sessionsById.delete(uploadId)
-      throw new FileUploadSessionError("not_found", "File upload session not found.")
-    }
-
-    return session
+  async now(): Promise<Date> {
+    return new Date()
   }
 
-  async markUploaded(uploadId: string, fileRef: FileRef): Promise<FileUploadSession> {
-    const session = this.requirePending(uploadId)
-    const updated = {
-      ...session,
-      fileRef,
-    }
-    this.sessionsById.set(uploadId, updated)
-    return updated
+  async insert(session: FileUploadSession): Promise<boolean> {
+    if (this.sessionsById.has(session.id)) return false
+    this.sessionsById.set(session.id, session)
+    return true
   }
 
-  async addSignedPart(uploadId: string, part: SignedBlobUploadPart): Promise<FileUploadSession> {
-    const session = this.requirePending(uploadId)
-    const updated = {
-      ...session,
-      signedParts: [
-        ...session.signedParts.filter((candidate) => candidate.partNumber !== part.partNumber),
-        part,
-      ].sort((left, right) => left.partNumber - right.partNumber),
-    }
-    this.sessionsById.set(uploadId, updated)
-    return updated
+  async get(uploadId: string): Promise<FileUploadSession | null> {
+    return this.sessionsById.get(uploadId) ?? null
   }
 
-  async complete(uploadId: string, fileRef: FileRef): Promise<FileUploadSession> {
-    const session = this.requirePending(uploadId)
-    const updated = {
-      ...session,
-      status: "completed" as const,
-      fileRef,
-      completedAt: new Date(),
-    }
-    this.sessionsById.set(uploadId, updated)
-    return updated
+  async update(session: FileUploadSession): Promise<void> {
+    this.sessionsById.set(session.id, session)
   }
 
-  async abort(uploadId: string): Promise<FileUploadSession> {
-    const session = this.requirePending(uploadId)
-    const updated = {
-      ...session,
-      status: "aborted" as const,
-      abortedAt: new Date(),
-    }
-    this.sessionsById.set(uploadId, updated)
-    return updated
+  async listAbandoned(
+    input: ListAbandonedFileUploadSessionsInput
+  ): Promise<readonly FileUploadSession[]> {
+    return [...this.sessionsById.values()]
+      .filter(
+        (session) =>
+          session.projectId === input.projectId &&
+          isAbandonedFileUploadSession(session, input.now.getTime())
+      )
+      .sort((left, right) => left.expiresAt.getTime() - right.expiresAt.getTime())
+      .slice(0, input.limit)
   }
 
-  async cleanupExpired(now = new Date()): Promise<number> {
+  async deleteReapable(now: Date): Promise<number> {
     let deleted = 0
     for (const [id, session] of this.sessionsById) {
       if (shouldDeleteFileUploadSession(session, now.getTime())) {
@@ -139,23 +107,6 @@ export class InMemoryFileUploadSessions implements FileUploadSessionStore {
         deleted += 1
       }
     }
-
     return deleted
   }
-
-  private requirePending(uploadId: string): FileUploadSession {
-    const session = this.sessionsById.get(uploadId)
-    if (!session) {
-      throw new FileUploadSessionError("not_found", "File upload session not found.")
-    }
-
-    if (session.status !== "pending") {
-      throw new FileUploadSessionError(
-        session.status === "completed" ? "already_completed" : "already_aborted",
-        `File upload session is already ${session.status}.`
-      )
-    }
-
-    return session
-  }
 }

package/src/storage/file-upload-sessions/index.ts

@@ -7,6 +7,7 @@ export type {
   FileUploadSessionStore,
   FileUploadStatus,
   FileUploadStrategy,
+  ListAbandonedFileUploadSessionsInput,
 } from "./types"
 export {
   createFileUploadId,

package/src/storage/file-upload-sessions/provider.ts

@@ -0,0 +1,258 @@
+import { type Principal, principalsEqual } from "../../auth"
+import type { FileRef, SignedBlobUploadPart } from "../../blob-storage"
+import { FileUploadSessionError } from "./errors"
+import type {
+  CreateFileUploadSessionInput,
+  FileUploadSession,
+  FileUploadSessionStore,
+  FileUploadStatus,
+  FileUploadStrategy,
+  ListAbandonedFileUploadSessionsInput,
+} from "./types"
+import {
+  createFileUploadId,
+  isFileUploadSessionExpired,
+  isTerminalFileUploadSessionExpired,
+} from "./utils"
+
+export { fileUploadSessionReapAt } from "./utils"
+
+/** Database-specific row access used by the shared upload session state machine. */
+export interface FileUploadSessionPersistence {
+  now(): Promise<Date>
+  /** Returns false when the id already exists. */
+  insert(session: FileUploadSession): Promise<boolean>
+  /** Inside `transaction`, must lock the row until the transaction ends. */
+  get(uploadId: string): Promise<FileUploadSession | null>
+  update(session: FileUploadSession): Promise<void>
+  /** The project's `pending` rows holding a provider upload, `expires_at <= now`, oldest first. */
+  listAbandoned(input: ListAbandonedFileUploadSessionsInput): Promise<readonly FileUploadSession[]>
+  /** Deletes rows whose persisted `fileUploadSessionReapAt` is `<= now`. */
+  deleteReapable(now: Date): Promise<number>
+}
+
+/** Transaction and lock boundary supplied by a concrete durable storage provider. */
+export interface FileUploadSessionPersistenceBackend {
+  read<T>(run: (persistence: FileUploadSessionPersistence) => Promise<T>): Promise<T>
+  transaction<T>(run: (persistence: FileUploadSessionPersistence) => Promise<T>): Promise<T>
+}
+
+/**
+ * Shared durable implementation of the upload session lifecycle. Concrete providers own SQL,
+ * transactions and database time; every transition and retention rule lives here so SQLite,
+ * PostgreSQL and the in-memory reference cannot drift semantically.
+ *
+ * Every method is `async`: a storage's operation-scoped facade serializes only async methods, and
+ * a plain Promise-returning method would bypass it and join whatever SQLite transaction is open.
+ */
+export class DurableFileUploadSessions implements FileUploadSessionStore {
+  constructor(private readonly backend: FileUploadSessionPersistenceBackend) {}
+
+  async create(input: CreateFileUploadSessionInput): Promise<FileUploadSession> {
+    return this.backend.transaction(async (persistence) => {
+      const session: FileUploadSession = {
+        id: input.id ?? createFileUploadId(),
+        projectId: input.projectId,
+        principal: input.principal,
+        strategy: input.strategy,
+        status: "pending",
+        ...(input.fileName === undefined ? {} : { fileName: input.fileName }),
+        ...(input.mediaType === undefined ? {} : { mediaType: input.mediaType }),
+        ...(input.logicalPath === undefined ? {} : { logicalPath: input.logicalPath }),
+        ...(input.expectedSizeBytes === undefined
+          ? {}
+          : { expectedSizeBytes: input.expectedSizeBytes }),
+        ...(input.expectedDigest === undefined ? {} : { expectedDigest: input.expectedDigest }),
+        ...(input.providerUpload === undefined ? {} : { providerUpload: input.providerUpload }),
+        signedParts: [],
+        createdAt: await persistence.now(),
+        expiresAt: input.expiresAt,
+      }
+
+      if (!(await persistence.insert(session))) {
+        throw new Error(`[Sixb] File upload session '${session.id}' already exists.`)
+      }
+      return session
+    })
+  }
+
+  async getForPrincipal(uploadId: string, principal: Principal): Promise<FileUploadSession> {
+    return this.backend.read(async (persistence) => {
+      const session = await persistence.get(uploadId)
+      if (!session || !principalsEqual(session.principal, principal)) {
+        throw new FileUploadSessionError("not_found", "File upload session not found.")
+      }
+
+      const nowMs = (await persistence.now()).getTime()
+      if (isFileUploadSessionExpired(session, nowMs)) {
+        throw new FileUploadSessionError("expired", "File upload session has expired.")
+      }
+      if (isTerminalFileUploadSessionExpired(session, nowMs)) {
+        throw new FileUploadSessionError("not_found", "File upload session not found.")
+      }
+      return session
+    })
+  }
+
+  async markUploaded(uploadId: string, fileRef: FileRef): Promise<FileUploadSession> {
+    return this.transition(uploadId, (session) => ({ ...session, fileRef }))
+  }
+
+  async addSignedPart(uploadId: string, part: SignedBlobUploadPart): Promise<FileUploadSession> {
+    return this.transition(uploadId, (session) => ({
+      ...session,
+      signedParts: [
+        ...session.signedParts.filter((candidate) => candidate.partNumber !== part.partNumber),
+        part,
+      ].sort((left, right) => left.partNumber - right.partNumber),
+    }))
+  }
+
+  async complete(uploadId: string, fileRef: FileRef): Promise<FileUploadSession> {
+    return this.transition(uploadId, (session, now) => ({
+      ...session,
+      status: "completed",
+      fileRef,
+      completedAt: now,
+    }))
+  }
+
+  async abort(uploadId: string): Promise<FileUploadSession> {
+    return this.transition(uploadId, (session, now) => ({
+      ...session,
+      status: "aborted",
+      abortedAt: now,
+    }))
+  }
+
+  async listAbandoned(
+    input: ListAbandonedFileUploadSessionsInput
+  ): Promise<readonly FileUploadSession[]> {
+    if (input.projectId.trim().length === 0) {
+      throw new Error("[Sixb] File upload session listAbandoned projectId must not be blank.")
+    }
+    if (!Number.isSafeInteger(input.limit) || input.limit <= 0) {
+      throw new Error("[Sixb] File upload session listAbandoned limit must be a positive integer.")
+    }
+    return this.backend.read((persistence) => persistence.listAbandoned(input))
+  }
+
+  async cleanupExpired(now?: Date): Promise<number> {
+    return this.backend.transaction(async (persistence) =>
+      persistence.deleteReapable(now ?? (await persistence.now()))
+    )
+  }
+
+  private transition(
+    uploadId: string,
+    next: (session: FileUploadSession, now: Date) => FileUploadSession
+  ): Promise<FileUploadSession> {
+    return this.backend.transaction(async (persistence) => {
+      const session = await persistence.get(uploadId)
+      if (!session) {
+        throw new FileUploadSessionError("not_found", "File upload session not found.")
+      }
+      if (session.status !== "pending") {
+        throw new FileUploadSessionError(
+          session.status === "completed" ? "already_completed" : "already_aborted",
+          `File upload session is already ${session.status}.`
+        )
+      }
+
+      const updated = next(session, await persistence.now())
+      await persistence.update(updated)
+      return updated
+    })
+  }
+}
+
+const STRATEGIES: readonly FileUploadStrategy[] = ["server", "direct-put", "multipart"]
+const STATUSES: readonly FileUploadStatus[] = ["pending", "completed", "aborted"]
+const PRINCIPAL_TYPES: readonly Principal["type"][] = ["user", "serviceAccount", "system"]
+
+/**
+ * Rebuilds a session from a provider row. JSON columns may arrive parsed (jsonb) or as text
+ * (SQLite); nested `expiresAt` values are revived and every other nested field passes through,
+ * so blob providers can extend `providerUpload` without a migration. Fails closed on corruption.
+ */
+export function parseFileUploadSessionRow(row: {
+  readonly [column: string]: unknown
+}): FileUploadSession {
+  const id = text(row.id, "id", String(row.id))
+  const strategy = text(row.strategy, "strategy", id) as FileUploadStrategy
+  const status = text(row.status, "status", id) as FileUploadStatus
+  if (!STRATEGIES.includes(strategy)) throw corrupt(id, `unknown strategy '${strategy}'`)
+  if (!STATUSES.includes(status)) throw corrupt(id, `unknown status '${status}'`)
+  const principalType = text(row.ownerPrincipalType, "ownerPrincipalType", id)
+  if (!PRINCIPAL_TYPES.includes(principalType as Principal["type"])) {
+    throw corrupt(id, `unknown owner principal type '${principalType}'`)
+  }
+
+  const providerUpload = json(row.providerUpload)
+  const fileRef = json(row.fileRef)
+  const signedParts = json(row.signedParts)
+  if (!Array.isArray(signedParts)) throw corrupt(id, "signedParts is not an array")
+
+  const optional = <T>(key: string, value: T | null | undefined) =>
+    value === null || value === undefined ? {} : { [key]: value }
+
+  return {
+    id,
+    projectId: text(row.projectId, "projectId", id),
+    principal: {
+      type: principalType as Principal["type"],
+      id: text(row.ownerPrincipalId, "ownerPrincipalId", id),
+    },
+    strategy,
+    status,
+    ...optional("fileName", row.fileName as string | null),
+    ...optional("mediaType", row.mediaType as string | null),
+    ...optional("logicalPath", row.logicalPath as string | null),
+    ...optional(
+      "expectedSizeBytes",
+      row.expectedSizeBytes === null || row.expectedSizeBytes === undefined
+        ? null
+        : Number(row.expectedSizeBytes)
+    ),
+    ...optional("expectedDigest", row.expectedDigest as string | null),
+    ...optional(
+      "providerUpload",
+      providerUpload === null ? null : withExpiresAt(providerUpload, id)
+    ),
+    signedParts: signedParts.map((part) => withExpiresAt(part, id)) as SignedBlobUploadPart[],
+    ...optional("fileRef", fileRef as FileRef | null),
+    createdAt: date(row.createdAt, "createdAt", id),
+    expiresAt: date(row.expiresAt, "expiresAt", id),
+    ...optional(
+      "completedAt",
+      row.completedAt == null ? null : date(row.completedAt, "completedAt", id)
+    ),
+    ...optional("abortedAt", row.abortedAt == null ? null : date(row.abortedAt, "abortedAt", id)),
+  } as FileUploadSession
+}
+
+function json(value: unknown): unknown {
+  return typeof value === "string" ? JSON.parse(value) : (value ?? null)
+}
+
+function withExpiresAt<T>(value: unknown, id: string): T {
+  if (typeof value !== "object" || value === null)
+    throw corrupt(id, "nested record is not an object")
+  const record = value as Record<string, unknown>
+  return { ...record, expiresAt: date(record.expiresAt, "nested expiresAt", id) } as T
+}
+
+function text(value: unknown, column: string, id: string): string {
+  if (typeof value !== "string" || value.length === 0) throw corrupt(id, `${column} is not text`)
+  return value
+}
+
+function date(value: unknown, column: string, id: string): Date {
+  const parsed = value instanceof Date || typeof value === "string" ? new Date(value) : null
+  if (!parsed || !Number.isFinite(parsed.getTime())) throw corrupt(id, `${column} is not a date`)
+  return parsed
+}
+
+function corrupt(id: string, reason: string): Error {
+  return new Error(`[Sixb] Stored file upload session '${id}' is invalid: ${reason}.`)
+}

package/src/storage/file-upload-sessions/types.ts

@@ -26,7 +26,7 @@ export interface CreateFileUploadSessionInput {
 export interface FileUploadSession {
   readonly id: string
   readonly projectId: string
-  readonly principalKey: string
+  readonly principal: Principal
   readonly strategy: FileUploadStrategy
   readonly status: FileUploadStatus
   readonly fileName?: string
@@ -43,19 +43,38 @@ export interface FileUploadSession {
   readonly abortedAt?: Date
 }
 
+export interface ListAbandonedFileUploadSessionsInput {
+  readonly projectId: string
+  readonly now: Date
+  readonly limit: number
+}
+
 /**
  * State machine for a staged/direct-put upload session. A session is created
  * `pending`; `markUploaded` records the resolved {@link FileRef} but keeps the
  * session `pending` (non-terminal), while `complete` and `abort` move it to a
  * terminal `completed`/`aborted` state. Terminal sessions are retained briefly
  * (for idempotent retries) then reaped by `cleanupExpired`.
+ *
+ * An expired `pending` session that still holds a `providerUpload` is abandoned:
+ * the provider may be billing for parts only `abortUpload` can release. The store
+ * never deletes one. A sweep lists them with `listAbandoned`, aborts the provider
+ * upload, then calls `abort` so the row becomes terminal and is reaped normally.
  */
 export interface FileUploadSessionStore {
   create(input: CreateFileUploadSessionInput): Promise<FileUploadSession>
+  /**
+   * The expiry gate: throws `expired` or `not_found`, and never deletes. Callers check expiry
+   * here when a request starts; the transitions below do not re-check it, because a request
+   * that passed the gate may finish slow blob I/O after `expiresAt`.
+   */
   getForPrincipal(uploadId: string, principal: Principal): Promise<FileUploadSession>
   markUploaded(uploadId: string, fileRef: FileRef): Promise<FileUploadSession>
   addSignedPart(uploadId: string, part: SignedBlobUploadPart): Promise<FileUploadSession>
   complete(uploadId: string, fileRef: FileRef): Promise<FileUploadSession>
   abort(uploadId: string): Promise<FileUploadSession>
+  /** One project's abandoned sessions expired at or before `now`, oldest expiry first. */
+  listAbandoned(input: ListAbandonedFileUploadSessionsInput): Promise<readonly FileUploadSession[]>
+  /** Deletes reapable sessions and returns the count. Never deletes an abandoned session. */
   cleanupExpired(now?: Date): Promise<number>
 }

package/src/storage/file-upload-sessions/utils.ts

@@ -1,5 +1,4 @@
 import { randomUUID } from "node:crypto"
-import type { Principal } from "../../auth"
 import type { FileUploadSession } from "./types"
 
 export const DEFAULT_FILE_UPLOAD_SESSION_TTL_MS = 60 * 60 * 1000
@@ -13,10 +12,6 @@ export function createFileUploadId(): string {
   return `upload_${randomUUID().replaceAll("-", "")}`
 }
 
-export function principalKey(principal: Principal): string {
-  return `${principal.type}:${principal.id}`
-}
-
 export function isFileUploadSessionExpired(
   session: FileUploadSession,
   nowMs = Date.now()
@@ -24,12 +19,33 @@ export function isFileUploadSessionExpired(
   return session.status === "pending" && session.expiresAt.getTime() <= nowMs
 }
 
-export function shouldDeleteFileUploadSession(session: FileUploadSession, nowMs: number): boolean {
-  if (isFileUploadSessionExpired(session, nowMs)) {
-    return true
+/** Expired, still `pending`, and holding a provider upload only `abortUpload` can release. */
+export function isAbandonedFileUploadSession(
+  session: FileUploadSession,
+  nowMs = Date.now()
+): boolean {
+  return session.providerUpload !== undefined && isFileUploadSessionExpired(session, nowMs)
+}
+
+/**
+ * When a session may be deleted, or null when only a state change can make it deletable.
+ * This is the single retention rule: durable providers persist it as `reap_at` and delete
+ * `reap_at <= now`, so SQL never restates it.
+ */
+export function fileUploadSessionReapAt(session: FileUploadSession): Date | null {
+  if (session.status === "pending") {
+    return session.providerUpload === undefined ? session.expiresAt : null
   }
 
-  return isTerminalFileUploadSessionExpired(session, nowMs)
+  const terminalAt = session.completedAt ?? session.abortedAt
+  return terminalAt
+    ? new Date(terminalAt.getTime() + DEFAULT_FILE_UPLOAD_TERMINAL_SESSION_TTL_MS)
+    : null
+}
+
+export function shouldDeleteFileUploadSession(session: FileUploadSession, nowMs: number): boolean {
+  const reapAt = fileUploadSessionReapAt(session)
+  return reapAt !== null && reapAt.getTime() <= nowMs
 }
 
 export function isTerminalFileUploadSessionExpired(