@sixb/core 0.1.11 → 0.1.13

package/src/testing/auth-storage-contract.ts

@@ -37,6 +37,24 @@ function sessionInput(
   }
 }
 
+function bearerSessionInput(id: string) {
+  return {
+    id,
+    projectId,
+    userId: "usr_1",
+    strategyId: "magic-link",
+    audience: "atlas" as const,
+    tokenHash: "access-1",
+    createdAt: at("2026-05-14T10:00:00.000Z"),
+    expiresAt: at("2026-06-14T10:00:00.000Z"),
+    bearer: {
+      clientName: "sixb CLI",
+      accessExpiresAt: at("2026-05-14T10:15:00.000Z"),
+      refreshTokenHash: "refresh-1",
+    },
+  }
+}
+
 async function expectAuthError(
   promise: Promise<unknown>,
   code: AuthStorageErrorCode
@@ -851,8 +869,7 @@ export function runAuthStorageContractSuite<TStorage extends AuthStorage>(
           projectId,
           name: "Local CLI",
           kind: "personal",
-          subjectType: "user",
-          subjectId: "usr_1",
+          subject: { type: "user", id: "usr_1" },
           tokenHash: "hash-personal",
           groupIds: ["commercial", "commercial", "finance"],
           createdAt: at("2026-05-14T10:01:00.000Z"),
@@ -893,8 +910,7 @@ export function runAuthStorageContractSuite<TStorage extends AuthStorage>(
           projectId,
           name: "Sandbox agent",
           kind: "serviceAccount",
-          subjectType: "serviceAccount",
-          subjectId: "svc_ingest",
+          subject: { type: "serviceAccount", id: "svc_ingest" },
           tokenHash: "hash-service",
           createdAt: at("2026-05-14T10:04:00.000Z"),
           expiresAt: at("2026-05-21T10:04:00.000Z"),
@@ -902,8 +918,7 @@ export function runAuthStorageContractSuite<TStorage extends AuthStorage>(
         await expect(
           storage.accessTokens.list({
             projectId,
-            subjectType: "serviceAccount",
-            subjectId: "svc_ingest",
+            subject: { type: "serviceAccount", id: "svc_ingest" },
           })
         ).resolves.toMatchObject({
           accessTokens: [{ id: "tok_service" }],
@@ -978,8 +993,7 @@ export function runAuthStorageContractSuite<TStorage extends AuthStorage>(
             projectId,
             name: `Token by ${principal.type}`,
             kind: "personal",
-            subjectType: "user",
-            subjectId: "usr_creator",
+            subject: { type: "user", id: "usr_creator" },
             tokenHash: `hash-${tokenId}`,
             createdByPrincipal: principal,
             createdBySessionId: "ses_creator",
@@ -1019,8 +1033,7 @@ export function runAuthStorageContractSuite<TStorage extends AuthStorage>(
           projectId,
           name: "Touch token",
           kind: "personal",
-          subjectType: "user",
-          subjectId: "usr_1",
+          subject: { type: "user", id: "usr_1" },
           tokenHash: "hash-touch",
           createdAt: at("2026-05-14T10:00:00.000Z"),
           expiresAt: at("2026-05-21T10:00:00.000Z"),
@@ -1066,8 +1079,7 @@ export function runAuthStorageContractSuite<TStorage extends AuthStorage>(
             projectId,
             name: `Token ${id}`,
             kind: "personal",
-            subjectType: "user",
-            subjectId: "usr_1",
+            subject: { type: "user", id: "usr_1" },
             tokenHash: `hash-${id}`,
             createdAt: at(`2026-05-14T10:0${index}:00.000Z`),
             expiresAt: at(`2026-05-21T10:0${index}:00.000Z`),
@@ -1182,8 +1194,7 @@ export function runAuthStorageContractSuite<TStorage extends AuthStorage>(
             projectId,
             name: "Bad kind",
             kind: "serviceAccount",
-            subjectType: "user",
-            subjectId: "usr_1",
+            subject: { type: "user", id: "usr_1" },
             tokenHash: "hash",
             createdAt: at("2026-05-14T10:00:00.000Z"),
             expiresAt: at("2026-05-21T10:00:00.000Z"),
@@ -1196,8 +1207,7 @@ export function runAuthStorageContractSuite<TStorage extends AuthStorage>(
             projectId,
             name: "Missing subject",
             kind: "serviceAccount",
-            subjectType: "serviceAccount",
-            subjectId: "svc_missing",
+            subject: { type: "serviceAccount", id: "svc_missing" },
             tokenHash: "hash",
             createdAt: at("2026-05-14T10:00:00.000Z"),
             expiresAt: at("2026-05-21T10:00:00.000Z"),
@@ -1316,11 +1326,11 @@ export function runAuthStorageContractSuite<TStorage extends AuthStorage>(
       })
     })
 
-    test("authorizes a device and atomically creates its one-time access token", async () => {
+    test("authorizes a device and atomically starts its bearer session", async () => {
       await withStorage(async (storage) => {
         await createUser(storage)
         await storage.sessions.create({
-          id: "ses_device",
+          id: "ses_browser",
           projectId,
           userId: "usr_1",
           strategyId: "magic-link",
@@ -1335,69 +1345,146 @@ export function runAuthStorageContractSuite<TStorage extends AuthStorage>(
           deviceCodeHash: "device-code-hash",
           userCode: "BCDF-HJKM",
           clientName: "sixb CLI",
-          tokenName: "codex",
-          tokenExpiresAt: at("2026-08-12T10:00:00.000Z"),
           createdAt: at("2026-05-14T10:00:00.000Z"),
           expiresAt: at("2026-05-14T10:10:00.000Z"),
         })
 
         await expect(
           storage.deviceAuthorizations.getByUserCode({ projectId, userCode: "BCDF-HJKM" })
-        ).resolves.toMatchObject({ id: "dva_1", status: "pending" })
+        ).resolves.toMatchObject({ id: "dva_1", status: "pending", clientName: "sixb CLI" })
         await storage.deviceAuthorizations.approve({
           projectId,
           id: "dva_1",
           userId: "usr_1",
-          sessionId: "ses_device",
+          sessionId: "ses_browser",
           approvedAt: at("2026-05-14T10:01:00.000Z"),
         })
 
-        const completed = await storage.completeDeviceAuthorization({
-          projectId,
-          id: "dva_1",
-          deviceCodeHash: "device-code-hash",
-          completedAt: at("2026-05-14T10:02:00.000Z"),
-          accessToken: {
-            id: "tok_device",
-            projectId,
-            name: "codex",
-            kind: "personal",
-            subjectType: "user",
-            subjectId: "usr_1",
-            tokenHash: "access-token-hash",
-            createdByPrincipal: { type: "user", id: "usr_1" },
-            createdBySessionId: "ses_device",
-            createdAt: at("2026-05-14T10:02:00.000Z"),
-            expiresAt: at("2026-08-12T10:00:00.000Z"),
-          },
-        })
-
-        expect(completed.authorization).toMatchObject({ status: "consumed" })
-        expect(completed.accessToken).toMatchObject({ id: "tok_device", subjectId: "usr_1" })
-        await expectAuthError(
+        const complete = (id: string) =>
           storage.completeDeviceAuthorization({
             projectId,
             id: "dva_1",
             deviceCodeHash: "device-code-hash",
-            completedAt: at("2026-05-14T10:03:00.000Z"),
-            accessToken: {
-              id: "tok_device_2",
-              projectId,
-              name: "codex",
-              kind: "personal",
-              subjectType: "user",
-              subjectId: "usr_1",
-              tokenHash: "access-token-hash-2",
-              createdBySessionId: "ses_device",
-              createdAt: at("2026-05-14T10:03:00.000Z"),
-              expiresAt: at("2026-08-12T10:00:00.000Z"),
-            },
-          }),
-          "invalid_device_authorization"
-        )
+            completedAt: at("2026-05-14T10:02:00.000Z"),
+            session: bearerSessionInput(id),
+          })
+        const completed = await complete("ses_cli")
+
+        expect(completed.authorization).toMatchObject({ status: "consumed" })
+        expect(completed.session).toMatchObject({
+          id: "ses_cli",
+          userId: "usr_1",
+          bearer: { clientName: "sixb CLI", refreshTokenHash: "refresh-1" },
+        })
+        await expectAuthError(complete("ses_cli_2"), "invalid_device_authorization")
+        await expect(storage.sessions.getById({ projectId, id: "ses_cli_2" })).resolves.toBeNull()
+      })
+    })
+
+    test("keeps bearer and cookie session credentials apart", async () => {
+      await withStorage(async (storage) => {
+        await createUser(storage)
+        await storage.sessions.create(bearerSessionInput("ses_cli"))
+        await storage.sessions.create({
+          ...bearerSessionInput("ses_cookie"),
+          tokenHash: "cookie-hash",
+          bearer: undefined,
+        })
+        const now = at("2026-05-14T10:05:00.000Z")
+
+        await expect(
+          storage.sessions.findValidByAccessTokenHash({
+            projectId,
+            id: "ses_cli",
+            tokenHash: "access-1",
+            now,
+          })
+        ).resolves.toMatchObject({ id: "ses_cli" })
+        // A bearer access token never works as a cookie secret, and a cookie never as a token.
+        await expect(
+          storage.sessions.findValidByTokenHash({
+            projectId,
+            id: "ses_cli",
+            audience: "atlas",
+            tokenHash: "access-1",
+            now,
+          })
+        ).resolves.toBeNull()
         await expect(
-          storage.accessTokens.getById({ projectId, id: "tok_device_2" })
+          storage.sessions.findValidByAccessTokenHash({
+            projectId,
+            id: "ses_cookie",
+            tokenHash: "cookie-hash",
+            now,
+          })
         ).resolves.toBeNull()
+        // The access token expires before its session.
+        await expect(
+          storage.sessions.findValidByAccessTokenHash({
+            projectId,
+            id: "ses_cli",
+            tokenHash: "access-1",
+            now: at("2026-05-14T10:15:00.000Z"),
+          })
+        ).resolves.toBeNull()
+      })
+    })
+
+    test("rotates refresh tokens, tolerates a lost response, and revokes on reuse", async () => {
+      await withStorage(async (storage) => {
+        await createUser(storage)
+        await storage.sessions.create({
+          ...bearerSessionInput("ses_cli"),
+          absoluteExpiresAt: at("2026-06-20T00:00:00.000Z"),
+        })
+        const rotate = (refreshTokenHash: string, now: string, generation: number) =>
+          storage.sessions.rotateRefreshToken({
+            projectId,
+            id: "ses_cli",
+            refreshTokenHash,
+            now: at(now),
+            reuseGraceMs: 60_000,
+            next: {
+              tokenHash: `access-${generation}`,
+              accessExpiresAt: new Date(at(now).getTime() + 15 * 60_000),
+              refreshTokenHash: `refresh-${generation}`,
+              expiresAt: at("2026-07-01T00:00:00.000Z"),
+            },
+          })
+
+        const rotated = await rotate("refresh-1", "2026-05-15T10:00:00.000Z", 2)
+        expect(rotated).toMatchObject({
+          status: "rotated",
+          session: {
+            tokenHash: "access-2",
+            bearer: { refreshTokenHash: "refresh-2", previousRefreshTokenHash: "refresh-1" },
+          },
+        })
+        // The idle deadline moves, but never past the absolute one.
+        expect(rotated.status === "rotated" && rotated.session.expiresAt.toISOString()).toBe(
+          "2026-06-20T00:00:00.000Z"
+        )
+        // The response was lost; the client retries with the token it still has.
+        await expect(rotate("refresh-1", "2026-05-15T10:00:30.000Z", 3)).resolves.toMatchObject({
+          status: "rotated",
+          session: { bearer: { refreshTokenHash: "refresh-3" } },
+        })
+        // An unknown token fails without touching the session.
+        await expect(rotate("guess", "2026-05-15T10:01:00.000Z", 4)).resolves.toEqual({
+          status: "invalid",
+        })
+        expect((await storage.sessions.getById({ projectId, id: "ses_cli" }))?.revokedAt).toBe(
+          undefined
+        )
+        // A replaced token after the grace window means a copy is in use: end the session.
+        await expect(rotate("refresh-2", "2026-05-15T10:05:00.000Z", 4)).resolves.toEqual({
+          status: "reused",
+        })
+        await expect(rotate("refresh-3", "2026-05-15T10:05:01.000Z", 5)).resolves.toEqual({
+          status: "invalid",
+        })
+        const session = await storage.sessions.getById({ projectId, id: "ses_cli" })
+        expect(session?.revokedAt).toBeInstanceOf(Date)
       })
     })
 

package/src/testing/execution-storage-contract.ts

@@ -402,8 +402,7 @@ async function seedAuth(auth: AuthStorage): Promise<void> {
     projectId,
     name: "Service token",
     kind: "serviceAccount",
-    subjectType: "serviceAccount",
-    subjectId: "service-one",
+    subject: { type: "serviceAccount", id: "service-one" },
     tokenHash: "service-token-hash",
     createdAt,
     expiresAt,

package/src/testing/execution.ts

@@ -2,7 +2,6 @@ import type { AuthorizationContext } from "../authorization"
 import { createTestingScope } from "../execution/scopes"
 import type { ExecutionScope } from "../execution/types"
 import { bindModelExecutionAttempt } from "../models/execution/binding"
-import type { OntologySource } from "../ontology"
 import { SixbHost, type SixbHostOptions } from "../runtime/host"
 import { isBoundSixb, type Sixb } from "../runtime/sixb"
 
@@ -26,12 +25,10 @@ export interface TestExecutionHost {
   withScope(scope: ExecutionScope): object
 }
 
-export function createTestSixb<
-  TOntologySources extends readonly OntologySource[] = readonly OntologySource[],
->(
-  hostOrOptions: TestExecutionHost | SixbHostOptions<TOntologySources>,
+export function createTestSixb(
+  hostOrOptions: TestExecutionHost | SixbHostOptions,
   options: TestExecutionOptions = {}
-): Sixb<TOntologySources> {
+): Sixb {
   const host: TestExecutionHost =
     "withScope" in hostOrOptions ? hostOrOptions : new SixbHost(hostOrOptions)
   const sixb = host.withScope(
@@ -43,7 +40,7 @@ export function createTestSixb<
       ...(options.correlationId === undefined ? {} : { correlationId: options.correlationId }),
     })
   )
-  if (!isBoundSixb<TOntologySources>(sixb)) {
+  if (!isBoundSixb(sixb)) {
     throw new Error("[Sixb] Test host did not return an execution-bound Sixb SDK.")
   }
   bindModelExecutionAttempt(sixb.models, {

package/src/testing/file-upload-session-storage-contract.ts

@@ -0,0 +1,335 @@
+import { describe, expect, test } from "bun:test"
+import type { Principal } from "../auth"
+import type { BlobUploadSession, FileRef, SignedBlobUploadPart } from "../blob-storage"
+import {
+  type CreateFileUploadSessionInput,
+  DEFAULT_FILE_UPLOAD_TERMINAL_SESSION_TTL_MS,
+  type FileUploadSessionStore,
+} from "../storage/file-upload-sessions"
+
+export interface FileUploadSessionStorageContractSuiteOptions<
+  TStorage extends FileUploadSessionStore = FileUploadSessionStore,
+> {
+  readonly createStorage: () => TStorage | Promise<TStorage>
+  readonly cleanup?: (storage: TStorage) => void | Promise<void>
+}
+
+const HOUR_MS = 60 * 60 * 1000
+const projectId = "file-upload-contract"
+const principal: Principal = { type: "user", id: "usr_contract" }
+const fileRef: FileRef = {
+  blobId: `blob_${"a".repeat(64)}`,
+  digest: `sha256:${"a".repeat(64)}`,
+  sizeBytes: 3,
+  fileName: "report.pdf",
+}
+
+/**
+ * Provider-neutral lifecycle, retention, and abandoned-upload contract for file upload
+ * sessions. Stores read their own clock, so fixtures place `expiresAt` relative to the
+ * real time instead of controlling it.
+ */
+export function runFileUploadSessionStorageContractSuite<TStorage extends FileUploadSessionStore>(
+  label: string,
+  options: FileUploadSessionStorageContractSuiteOptions<TStorage>
+): void {
+  const withStorage = async (run: (storage: TStorage) => Promise<void>): Promise<void> => {
+    const storage = await options.createStorage()
+    try {
+      await run(storage)
+    } finally {
+      await options.cleanup?.(storage)
+    }
+  }
+
+  describe(label, () => {
+    test("round-trips every field, including provider fields it does not know", async () => {
+      await withStorage(async (storage) => {
+        // Provider-specific session fields must survive the JSON round-trip.
+        const providerUpload = { ...multipart("upload_roundtrip"), partReceipt: "etag" as const }
+        const input = sessionInput("upload_roundtrip", {
+          fileName: "report.pdf",
+          mediaType: "application/pdf",
+          logicalPath: "reports/q3.pdf",
+          expectedSizeBytes: 3,
+          expectedDigest: fileRef.digest,
+          providerUpload,
+        })
+        const created = await storage.create(input)
+
+        expect(created).toMatchObject({ status: "pending", principal })
+        const read = await storage.getForPrincipal("upload_roundtrip", principal)
+        expect(read).toEqual(created)
+        expect(read.providerUpload?.expiresAt).toBeInstanceOf(Date)
+        expect(read.providerUpload).toMatchObject({ partReceipt: "etag" })
+      })
+    })
+
+    test("hides a session from other principals and unknown ids", async () => {
+      await withStorage(async (storage) => {
+        await storage.create(sessionInput("upload_private"))
+
+        await expect(
+          storage.getForPrincipal("upload_private", { type: "user", id: "usr_other" })
+        ).rejects.toMatchObject({ reason: "not_found" })
+        await expect(storage.getForPrincipal("upload_missing", principal)).rejects.toMatchObject({
+          reason: "not_found",
+        })
+      })
+    })
+
+    test("rejects a duplicate id", async () => {
+      await withStorage(async (storage) => {
+        await storage.create(sessionInput("upload_duplicate"))
+        await expect(storage.create(sessionInput("upload_duplicate"))).rejects.toThrow(
+          "already exists"
+        )
+      })
+    })
+
+    test("keeps signed parts unique and ordered by part number", async () => {
+      await withStorage(async (storage) => {
+        await storage.create(
+          sessionInput("upload_parts", { providerUpload: multipart("upload_parts") })
+        )
+        // Insertion order differs from sorted order at every step, so dropping the sort fails.
+        await storage.addSignedPart("upload_parts", signedPart(3))
+        await storage.addSignedPart("upload_parts", signedPart(1))
+        await storage.addSignedPart("upload_parts", signedPart(2))
+        const updated = await storage.addSignedPart("upload_parts", signedPart(2, "replaced"))
+
+        expect(updated.signedParts.map((part) => [part.partNumber, part.url])).toEqual([
+          [1, "https://blob.test/part-1"],
+          [2, "https://blob.test/part-2-replaced"],
+          [3, "https://blob.test/part-3"],
+        ])
+        const read = await storage.getForPrincipal("upload_parts", principal)
+        expect(read.signedParts).toEqual(updated.signedParts)
+        expect(read.signedParts[0]?.expiresAt).toBeInstanceOf(Date)
+      })
+    })
+
+    test("does not lose a part signed concurrently with another", async () => {
+      await withStorage(async (storage) => {
+        await storage.create(
+          sessionInput("upload_race", { providerUpload: multipart("upload_race") })
+        )
+        await Promise.all(
+          [1, 2, 3, 4, 5].map((n) => storage.addSignedPart("upload_race", signedPart(n)))
+        )
+
+        const read = await storage.getForPrincipal("upload_race", principal)
+        expect(read.signedParts.map((part) => part.partNumber)).toEqual([1, 2, 3, 4, 5])
+      })
+    })
+
+    test("moves through markUploaded to one terminal state", async () => {
+      await withStorage(async (storage) => {
+        await storage.create(sessionInput("upload_done"))
+        const uploaded = await storage.markUploaded("upload_done", fileRef)
+        expect(uploaded).toMatchObject({ status: "pending", fileRef })
+
+        const completed = await storage.complete("upload_done", fileRef)
+        expect(completed.status).toBe("completed")
+        expect(completed.completedAt).toBeInstanceOf(Date)
+        await expect(storage.complete("upload_done", fileRef)).rejects.toMatchObject({
+          reason: "already_completed",
+        })
+        await expect(storage.abort("upload_done")).rejects.toMatchObject({
+          reason: "already_completed",
+        })
+
+        await storage.create(sessionInput("upload_cancelled"))
+        expect((await storage.abort("upload_cancelled")).status).toBe("aborted")
+        await expect(storage.abort("upload_cancelled")).rejects.toMatchObject({
+          reason: "already_aborted",
+        })
+      })
+    })
+
+    test("checks expiry at the gate only, so a request that passed it can finish", async () => {
+      await withStorage(async (storage) => {
+        // Provider uploads keep both rows unreapable while pending.
+        for (const id of ["upload_late", "upload_abort_late"]) {
+          await storage.create(
+            sessionInput(id, { expiresAt: ago(HOUR_MS), providerUpload: multipart(id) })
+          )
+        }
+
+        await expect(storage.getForPrincipal("upload_late", principal)).rejects.toMatchObject({
+          reason: "expired",
+        })
+        // Transitions run after slow blob I/O that began before `expiresAt`.
+        await storage.addSignedPart("upload_late", signedPart(1))
+        await storage.markUploaded("upload_late", fileRef)
+        expect((await storage.complete("upload_late", fileRef)).status).toBe("completed")
+        expect((await storage.abort("upload_abort_late")).status).toBe("aborted")
+      })
+    })
+
+    test("lists abandoned sessions for one project only", async () => {
+      await withStorage(async (storage) => {
+        await storage.create(
+          sessionInput("upload_ours", {
+            expiresAt: ago(HOUR_MS),
+            providerUpload: multipart("ours"),
+          })
+        )
+        await storage.create(
+          sessionInput("upload_theirs", {
+            projectId: "other-project",
+            expiresAt: ago(HOUR_MS),
+            providerUpload: multipart("theirs"),
+          })
+        )
+
+        const ids = (await storage.listAbandoned({ projectId, now: new Date(), limit: 10 })).map(
+          (session) => session.id
+        )
+        expect(ids).toEqual(["upload_ours"])
+      })
+    })
+
+    test("never deletes an abandoned session, on read or on cleanup", async () => {
+      await withStorage(async (storage) => {
+        await storage.create(
+          sessionInput("upload_abandoned", {
+            expiresAt: ago(HOUR_MS),
+            providerUpload: multipart("upload_abandoned"),
+          })
+        )
+
+        // Reading an expired session must not delete it: nothing would abort its provider upload.
+        await expect(storage.getForPrincipal("upload_abandoned", principal)).rejects.toMatchObject({
+          reason: "expired",
+        })
+        expect(await storage.cleanupExpired(later(HOUR_MS))).toBe(0)
+        expect(
+          (await storage.listAbandoned({ projectId, now: new Date(), limit: 10 })).map(
+            (session) => session.id
+          )
+        ).toEqual(["upload_abandoned"])
+      })
+    })
+
+    test("lists only abandoned sessions, oldest expiry first, within the limit", async () => {
+      await withStorage(async (storage) => {
+        await storage.create(
+          sessionInput("upload_newer", { expiresAt: ago(HOUR_MS), providerUpload: multipart("n") })
+        )
+        await storage.create(
+          sessionInput("upload_older", {
+            expiresAt: ago(2 * HOUR_MS),
+            providerUpload: multipart("o"),
+          })
+        )
+        await storage.create(sessionInput("upload_live", { providerUpload: multipart("live") }))
+        await storage.create(sessionInput("upload_server", { expiresAt: ago(HOUR_MS) }))
+        await storage.create(
+          sessionInput("upload_aborted", {
+            expiresAt: ago(HOUR_MS),
+            providerUpload: multipart("a"),
+          })
+        )
+        await storage.abort("upload_aborted")
+
+        const ids = async (limit: number) =>
+          (await storage.listAbandoned({ projectId, now: new Date(), limit })).map(
+            (session) => session.id
+          )
+        expect(await ids(10)).toEqual(["upload_older", "upload_newer"])
+        expect(await ids(1)).toEqual(["upload_older"])
+        const [oldest] = await storage.listAbandoned({ projectId, now: new Date(), limit: 1 })
+        expect(oldest?.providerUpload?.expiresAt).toBeInstanceOf(Date)
+        await expect(
+          storage.listAbandoned({ projectId, now: new Date(), limit: 0 })
+        ).rejects.toThrow("positive integer")
+      })
+    })
+
+    test("reaps expired sessions without a provider upload and terminal ones after their TTL", async () => {
+      await withStorage(async (storage) => {
+        await storage.create(sessionInput("upload_live"))
+        await storage.create(sessionInput("upload_finished"))
+        await storage.complete("upload_finished", fileRef)
+        // Created last: a store may reap opportunistically on `create`.
+        await storage.create(sessionInput("upload_expired", { expiresAt: ago(HOUR_MS) }))
+
+        expect(await storage.cleanupExpired(new Date())).toBe(1)
+        await expect(storage.getForPrincipal("upload_expired", principal)).rejects.toMatchObject({
+          reason: "not_found",
+        })
+        // A completed session outlives its expiry so a retried `complete` stays idempotent.
+        expect((await storage.getForPrincipal("upload_finished", principal)).status).toBe(
+          "completed"
+        )
+
+        expect(
+          await storage.cleanupExpired(later(DEFAULT_FILE_UPLOAD_TERMINAL_SESSION_TTL_MS + 60_000))
+        ).toBe(1)
+        await expect(storage.getForPrincipal("upload_finished", principal)).rejects.toMatchObject({
+          reason: "not_found",
+        })
+        expect((await storage.getForPrincipal("upload_live", principal)).status).toBe("pending")
+      })
+    })
+
+    test("reaps an abandoned session once it has been aborted", async () => {
+      await withStorage(async (storage) => {
+        await storage.create(
+          sessionInput("upload_swept", { expiresAt: ago(HOUR_MS), providerUpload: multipart("s") })
+        )
+        await storage.abort("upload_swept")
+
+        expect(await storage.listAbandoned({ projectId, now: new Date(), limit: 10 })).toEqual([])
+        expect(await storage.cleanupExpired(new Date())).toBe(0)
+        expect(
+          await storage.cleanupExpired(later(DEFAULT_FILE_UPLOAD_TERMINAL_SESSION_TTL_MS + 60_000))
+        ).toBe(1)
+      })
+    })
+  })
+}
+
+function sessionInput(
+  id: string,
+  overrides: Partial<CreateFileUploadSessionInput> = {}
+): CreateFileUploadSessionInput {
+  return {
+    id,
+    projectId,
+    principal,
+    strategy: overrides.providerUpload?.strategy ?? "server",
+    expiresAt: later(HOUR_MS),
+    ...overrides,
+  }
+}
+
+function multipart(uploadId: string): BlobUploadSession {
+  return {
+    strategy: "multipart",
+    uploadId,
+    partSizeBytes: 5 * 1024 * 1024,
+    expiresAt: later(HOUR_MS),
+    stagingKey: `staging/${uploadId}`,
+    providerUploadId: `provider-${uploadId}`,
+  }
+}
+
+function signedPart(partNumber: number, suffix?: string): SignedBlobUploadPart {
+  return {
+    partNumber,
+    method: "PUT",
+    url: `https://blob.test/part-${partNumber}${suffix ? `-${suffix}` : ""}`,
+    headers: {},
+    expiresAt: later(HOUR_MS),
+  }
+}
+
+function ago(ms: number): Date {
+  return new Date(Date.now() - ms)
+}
+
+function later(ms: number): Date {
+  return new Date(Date.now() + ms)
+}