@sixb/core 0.1.21 → 0.1.22

package/src/testing/broker-contract.ts

@@ -35,6 +35,11 @@ export interface BrokerContractSuiteOptions<TBroker extends Broker = Broker> {
    * Poll interval while waiting for asynchronous subscription delivery. Defaults to 10ms.
    */
   readonly subscriptionPollIntervalMs?: number
+  /**
+   * Lets `ms` milliseconds pass for the provider. Defaults to a real sleep. An in-process
+   * provider can advance fake timers here instead, so the waits above cost no wall time.
+   */
+  readonly sleep?: (ms: number) => Promise<void>
 }
 
 const eventsStream: BrokerStreamDefinition = { id: "__events" }
@@ -57,6 +62,20 @@ export function runBrokerContractSuite<TBroker extends Broker>(
   const subscriptionSetupMs = options.subscriptionSetupMs ?? 0
   const subscriptionDeliveryTimeoutMs = options.subscriptionDeliveryTimeoutMs ?? 200
   const subscriptionPollIntervalMs = options.subscriptionPollIntervalMs ?? 10
+  const sleep = options.sleep ?? ((ms: number) => Bun.sleep(ms))
+  const waitUntil = async (
+    predicate: () => boolean,
+    params: { timeoutMs: number; intervalMs: number; message: string }
+  ): Promise<void> => {
+    const deadline = Date.now() + params.timeoutMs
+    while (Date.now() < deadline) {
+      if (predicate()) {
+        return
+      }
+      await sleep(params.intervalMs)
+    }
+    throw new Error(`${params.message} within ${params.timeoutMs}ms`)
+  }
 
   const withBroker = async (body: (broker: TBroker) => Promise<void>): Promise<void> => {
     const broker = await options.createBroker()
@@ -476,7 +495,7 @@ export function runBrokerContractSuite<TBroker extends Broker>(
               message: "Async broker subscription did not progress",
             })
           try {
-            if (subscriptionSetupMs > 0) await Bun.sleep(subscriptionSetupMs)
+            if (subscriptionSetupMs > 0) await sleep(subscriptionSetupMs)
             await broker.append({
               projectId: "project-a",
               streamId: eventsStream.id,
@@ -489,7 +508,7 @@ export function runBrokerContractSuite<TBroker extends Broker>(
               records: [{ payload: "two" }],
             })
             await wait(() => observer.length === 2)
-            await Bun.sleep(30)
+            await sleep(30)
             expect(received).toEqual(["one"])
             release()
             await wait(() => received.length === 2)
@@ -523,7 +542,7 @@ export function runBrokerContractSuite<TBroker extends Broker>(
             }
           )
           try {
-            if (subscriptionSetupMs > 0) await Bun.sleep(subscriptionSetupMs)
+            if (subscriptionSetupMs > 0) await sleep(subscriptionSetupMs)
             await broker.append({
               projectId: "project-a",
               streamId: eventsStream.id,
@@ -566,7 +585,7 @@ export function runBrokerContractSuite<TBroker extends Broker>(
             }
           )
           if (subscriptionSetupMs > 0) {
-            await Bun.sleep(subscriptionSetupMs)
+            await sleep(subscriptionSetupMs)
           }
 
           await appendRecords(broker, {
@@ -604,7 +623,7 @@ export function runBrokerContractSuite<TBroker extends Broker>(
             }
           )
           if (subscriptionSetupMs > 0) {
-            await Bun.sleep(subscriptionSetupMs)
+            await sleep(subscriptionSetupMs)
           }
 
           await appendRecords(broker, {
@@ -669,7 +688,7 @@ export function runBrokerContractSuite<TBroker extends Broker>(
             }
           )
           if (subscriptionSetupMs > 0) {
-            await Bun.sleep(subscriptionSetupMs)
+            await sleep(subscriptionSetupMs)
           }
 
           await appendRecords(broker, {
@@ -690,7 +709,7 @@ export function runBrokerContractSuite<TBroker extends Broker>(
             stream: eventsStream,
             records: [{ payload: "two" }],
           })
-          await Bun.sleep(Math.min(250, subscriptionDeliveryTimeoutMs))
+          await sleep(Math.min(250, subscriptionDeliveryTimeoutMs))
 
           expect(received).toEqual(["one"])
         })
@@ -710,7 +729,7 @@ export function runBrokerContractSuite<TBroker extends Broker>(
             }
           )
           if (subscriptionSetupMs > 0) {
-            await Bun.sleep(subscriptionSetupMs)
+            await sleep(subscriptionSetupMs)
           }
 
           await expect(
@@ -827,7 +846,7 @@ export function runBrokerContractSuite<TBroker extends Broker>(
             records: [{ payload: "old" }],
           })
 
-          await Bun.sleep(maxAgeWaitMs)
+          await sleep(maxAgeWaitMs)
 
           await appendRecords(broker, {
             projectId: "project-a",
@@ -913,17 +932,3 @@ async function subscribeRecords(
     handler
   )
 }
-
-async function waitUntil(
-  predicate: () => boolean,
-  options: { timeoutMs: number; intervalMs: number; message: string }
-): Promise<void> {
-  const deadline = Date.now() + options.timeoutMs
-  while (Date.now() < deadline) {
-    if (predicate()) {
-      return
-    }
-    await Bun.sleep(options.intervalMs)
-  }
-  throw new Error(`${options.message} within ${options.timeoutMs}ms`)
-}

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

@@ -206,7 +206,7 @@ export function runEffectiveStorageContractSuite<TStorage extends Storage>(
       })
     })
 
-    test("keeps delimiter-bearing object and batch-link identities distinct", async () => {
+    test("keeps delimiter-bearing identities distinct in batch and incident link reads", async () => {
       await withStorage(async (storage) => {
         const opaqueProjectId = `${projectId}-opaque-batch-keys`
         const fixture = createMaterializerTestFixture({
@@ -263,22 +263,17 @@ export function runEffectiveStorageContractSuite<TStorage extends Storage>(
         })
         expect(links.get(linkBatchKey(OpaqueA.id, "B:C", "D"))).toHaveLength(1)
         expect(links.get(linkBatchKey(OpaqueAB.id, "C", "D"))).toHaveLength(1)
-      })
-    })
 
-    test("preserves distinct incident links when opaque ids contain delimiters", async () => {
-      await withStorage(async (storage) => {
         const opaqueIdsProjectId = `${projectId}-opaque-link-ids`
         const firstSourceId = "opaque:source"
         const firstTargetId = `target:peers:${Device.id}:opaque:end`
         const secondSourceId = `${firstSourceId}:peers:${Device.id}:target`
         const secondTargetId = "opaque:end"
-        const fixture = createMaterializerTestFixture({
+        await createMaterializerTestFixture({
           projectId: opaqueIdsProjectId,
           ontology,
           storage,
-        })
-        await fixture.seed({
+        }).seed({
           objects: [
             device(firstSourceId, "First source"),
             device(firstTargetId, "First target"),

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

@@ -459,6 +459,59 @@ export function runExecutionStorageContractSuite<TStorage extends ExecutionStora
       })
     })
 
+    test("lists everything executions caused, at any depth, each once", async () => {
+      // Removal proof: make a provider's walk stop at the first level; `inner`, `inner-action` and
+      // `grandchild` go missing. Make it `UNION ALL`; `inner-action` is listed twice.
+      await withStorage(async (storage) => {
+        await seedAuth(storage.auth)
+
+        const root = await createAt(storage, 0, principalRequest({ id: "root" }))
+        const sibling = await createAt(storage, 1_000, principalRequest({ id: "sibling" }))
+        const child = await createAt(storage, 2_000, childOf(root, trustedPrimitive("child")))
+        const inner = await createAt(storage, 3_000, childOf(child, trustedPrimitive("inner")))
+        await createAt(storage, 4_000, childOf(inner, trustedPrimitive("inner-action")))
+        await createAt(storage, 5_000, childOf(child, trustedPrimitive("grandchild")))
+        await createAt(
+          storage,
+          6_000,
+          childOf(root, trustedPrimitive("late-workflow", {}, "workflow"))
+        )
+        await createAt(storage, 7_000, childOf(sibling, trustedPrimitive("sibling-action")))
+
+        const ids = async (executionIds: readonly string[]) =>
+          (await storage.executions.listDescendants({ projectId, executionIds })).map(
+            (execution) => execution.id
+          )
+
+        expect(await ids(["root"])).toEqual([
+          "child",
+          "grandchild",
+          "inner",
+          "inner-action",
+          "late-workflow",
+        ])
+        // Asked about too, `inner` is not listed, and what it caused is listed once.
+        expect(await ids(["root", "inner"])).toEqual([
+          "child",
+          "grandchild",
+          "inner-action",
+          "late-workflow",
+        ])
+        expect(await ids(["sibling", "inner"])).toEqual(["inner-action", "sibling-action"])
+        expect(await ids(["grandchild", "unknown"])).toEqual([])
+        expect(await ids([])).toEqual([])
+
+        const listed = await storage.executions.listDescendants({
+          projectId,
+          executionIds: ["inner"],
+        })
+        expect(listed).toEqual([{ id: "inner-action", parentId: "inner" }])
+        expect(
+          await storage.executions.listDescendants({ projectId: "other", executionIds: ["root"] })
+        ).toEqual([])
+      })
+    })
+
     test("participates in storage transactions and rollback", async () => {
       await withStorage(async (storage) => {
         await expect(

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

@@ -167,29 +167,6 @@ export function runFileUploadSessionStorageContractSuite<TStorage extends FileUp
       })
     })
 
-    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(
@@ -212,7 +189,7 @@ export function runFileUploadSessionStorageContractSuite<TStorage extends FileUp
       })
     })
 
-    test("lists only abandoned sessions, oldest expiry first, within the limit", async () => {
+    test("lists only the project's 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") })
@@ -232,6 +209,13 @@ export function runFileUploadSessionStorageContractSuite<TStorage extends FileUp
           })
         )
         await storage.abort("upload_aborted")
+        await storage.create(
+          sessionInput("upload_theirs", {
+            projectId: "other-project",
+            expiresAt: ago(3 * HOUR_MS),
+            providerUpload: multipart("theirs"),
+          })
+        )
 
         const ids = async (limit: number) =>
           (await storage.listAbandoned({ projectId, now: new Date(), limit })).map(
@@ -263,6 +247,10 @@ export function runFileUploadSessionStorageContractSuite<TStorage extends FileUp
         expect((await storage.getForPrincipal("upload_finished", principal)).status).toBe(
           "completed"
         )
+        // Removal proof: shorten the terminal TTL in fileUploadSessionReapAt to a second.
+        expect(
+          await storage.cleanupExpired(later(DEFAULT_FILE_UPLOAD_TERMINAL_SESSION_TTL_MS - 60_000))
+        ).toBe(0)
 
         expect(
           await storage.cleanupExpired(later(DEFAULT_FILE_UPLOAD_TERMINAL_SESSION_TTL_MS + 60_000))

package/src/testing/index.ts

@@ -13,7 +13,17 @@ export {
   type ActivityStorageContractSuiteOptions,
   runActivityStorageContractSuite,
 } from "./activity-storage-contract"
+export {
+  type AgentApprovalStorageContractStorage,
+  type AgentApprovalStorageContractSuiteOptions,
+  runAgentApprovalStorageContractSuite,
+} from "./agent-approval-storage-contract"
 export { createTestAgentExecution } from "./agent-execution"
+export {
+  type AgentMemoryStorageContractStorage,
+  type AgentMemoryStorageContractSuiteOptions,
+  runAgentMemoryStorageContractSuite,
+} from "./agent-memory-storage-contract"
 export {
   type AgentStorageContractSuiteOptions,
   runAgentStorageContractSuite,
@@ -27,7 +37,6 @@ export {
   type AiLimitStorageContractStorage,
   type AiLimitStorageContractSuiteOptions,
   runAiLimitStorageContractSuite,
-  seedAiLimitStorageContractExecution,
 } from "./ai-limit-storage-contract"
 export {
   type AiModelCallGroupsContractStorage,
@@ -45,6 +54,7 @@ export {
 } from "./artifact-storage-contract"
 export {
   type AuthStorageContractSuiteOptions,
+  type AuthUserHold,
   runAuthStorageContractSuite,
 } from "./auth-storage-contract"
 export {
@@ -109,11 +119,11 @@ export {
   type MaterializerStorageContractProvider,
   runMaterializerStorageContractSuite,
 } from "./materializer-storage-contract"
+export { runConditionalObjectReadScopeContractSuite } from "./object-conditional-read-scope-contract"
 export {
   type ObjectQueryProviderContractSuiteOptions,
   objectQueryContractOntology,
   runObjectQueryProviderContractSuite,
-  seedObjectQueryContractData,
 } from "./object-query-contract"
 export {
   type ObjectReadScopeContractHarness,
@@ -133,7 +143,6 @@ export {
 } from "./pipeline-execution"
 export {
   claimTestProjectionRun,
-  createTestProjectionExecution,
   queueTestProjectionRun,
   startTestProjectionRun,
 } from "./projection-execution"
@@ -165,7 +174,11 @@ export {
   queueTestSyncRun,
   startTestSyncRun,
 } from "./sync-execution"
-export { createTestWebhookExecution, startTestWebhookRun } from "./webhook-execution"
+export {
+  runUniqueValuesContractSuite,
+  type UniqueValuesContractProvider,
+} from "./unique-values-contract"
+export { startTestWebhookRun } from "./webhook-execution"
 export {
   runWebhookRunStorageContractSuite,
   type WebhookRunStorageContractStorage,

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

@@ -124,36 +124,27 @@ export function runLakeStorageContractSuite<TStorage extends LakeStorage>(
 
   describe(label, () => {
     describe("dataset definitions", () => {
-      test("creates, gets, lists, and reuses dataset definitions", async () => {
+      test("creates, gets, lists, and reuses plain and keyed dataset definitions", async () => {
+        // Regression guard: omitting primaryKey from mergeDatasetDefinition makes reuse lose
+        // the key and fails the keyed case.
         await withStorage(async (storage) => {
-          expect(await storage.getDataset(definitionDataset.id)).toBeNull()
+          const datasets = [keyedDefinitionDataset, definitionDataset]
+          for (const dataset of datasets) {
+            expect(await storage.getDataset(dataset.id)).toBeNull()
 
-          const created = await storage.createDataset(definitionDataset)
-          const repeated = await storage.createDataset(definitionDataset)
+            const created = await storage.createDataset(dataset)
+            const repeated = await storage.createDataset(dataset)
 
-          expect(created).toEqual(definitionDataset)
-          expect(repeated).toEqual(definitionDataset)
-          expect(await storage.getDataset(definitionDataset.id)).toEqual(definitionDataset)
+            expect(created).toEqual(dataset)
+            expect(repeated).toEqual(dataset)
+            expect(await storage.getDataset(dataset.id)).toEqual(dataset)
+            expect(await storage.listVersions(dataset.id)).toEqual([])
+          }
           expect(await storage.getDataset("missing.dataset")).toBeNull()
-          expect(await storage.listDatasets()).toEqual([definitionDataset])
-          expect(await storage.listVersions(definitionDataset.id)).toEqual([])
-        })
-      })
-
-      test("round-trips keyed definitions through create, get, list, and reuse", async () => {
-        // Regression guard: omitting primaryKey from mergeDatasetDefinition makes reuse lose
-        // the key and fails this contract case.
-        await withStorage(async (storage) => {
-          const created = await storage.createDataset(keyedDefinitionDataset)
-          const repeated = await storage.createDataset(keyedDefinitionDataset)
-
-          expect(created).toEqual(keyedDefinitionDataset)
-          expect(repeated).toEqual(keyedDefinitionDataset)
-          expect(await storage.getDataset(keyedDefinitionDataset.id)).toEqual(
-            keyedDefinitionDataset
+          const listed = await storage.listDatasets()
+          expect([...listed].sort((left, right) => left.id.localeCompare(right.id))).toEqual(
+            datasets
           )
-          expect(await storage.listDatasets()).toEqual([keyedDefinitionDataset])
-          expect(await storage.listVersions(keyedDefinitionDataset.id)).toEqual([])
         })
       })
 
@@ -201,7 +192,9 @@ export function runLakeStorageContractSuite<TStorage extends LakeStorage>(
 
           await expect(
             storage.assertDatasetDefinitionsCompatible([changedDataset])
-          ).rejects.toThrow("changing column 'orderId' type")
+          ).rejects.toThrow(
+            /Lake dataset definition check failed[\s\S]*changing column 'orderId' type/
+          )
           await expect(storage.createDataset(changedDataset)).rejects.toBeInstanceOf(
             LakeStorageError
           )
@@ -504,6 +497,7 @@ export function runLakeStorageContractSuite<TStorage extends LakeStorage>(
             rowCount: 2,
           })
 
+          // `listVersions` orders by creation time: a later millisecond keeps the order exact.
           await Bun.sleep(2)
 
           const appendWrite = await storage.beginWrite({
@@ -823,6 +817,7 @@ export function runLakeStorageContractSuite<TStorage extends LakeStorage>(
             versionId: seedVersion.versionId,
           })
 
+          // `listVersions` orders by creation time: a later millisecond keeps the order exact.
           await Bun.sleep(2)
 
           const changedWrite = await storage.beginWrite({ dataset: writeDataset, mode: "snapshot" })
@@ -850,8 +845,6 @@ export function runLakeStorageContractSuite<TStorage extends LakeStorage>(
           await seedWrite.writeRows([rowA, rowA, rowB])
           const seedVersion = await seedWrite.commit()
 
-          await Bun.sleep(2)
-
           // Same distinct rows and row count, but different duplicate counts:
           // this is new content, not a no-op.
           const shiftedWrite = await storage.beginWrite({ dataset: writeDataset, mode: "snapshot" })
@@ -948,6 +941,7 @@ export function runLakeStorageContractSuite<TStorage extends LakeStorage>(
           await write.abort()
           await write.abort()
 
+          await expect(write.writeRows([])).rejects.toThrow("already closed")
           expect(await storage.getLatestVersion(writeDataset.id)).toBeNull()
           expect(await storage.listVersions(writeDataset.id)).toEqual([])
           await expect(

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

@@ -862,6 +862,20 @@ export function runMaterializerStorageContractSuite<TStorage extends Storage>(
           expectedLinks: [],
         })
       ).rejects.toMatchObject({ kind: "expectation" })
+      // Same version, different commit: the object was deleted and recreated since it was read.
+      const current = await storage.objects.getByPrimaryId({
+        projectId: "materializer-storage-contract",
+        ...device,
+      })
+      if (!current) throw new Error("Expected the setup commit to create the device.")
+      await expect(
+        commitExpecting("recreated-object", {
+          expectedObjects: [
+            { ref: device, exists: true, version: current.version, lastCommitId: "stale-commit" },
+          ],
+          expectedLinks: [],
+        })
+      ).rejects.toMatchObject({ kind: "expectation" })
       await expect(
         commitExpecting("stale-link", {
           expectedObjects: [],
@@ -1443,8 +1457,10 @@ export function runMaterializerStorageContractSuite<TStorage extends Storage>(
 
         let retries = 0
         const recording = observeActionRunRecords(storage)
-        const second = contractMaterializer(recording.storage, {}, () => {
-          retries += 1
+        const second = contractMaterializer(recording.storage, {
+          onSerializationRetry: () => {
+            retries += 1
+          },
         })
           .withScope(await scopeOf(secondRun.executionId))
           .edits.commit(commitOf(secondRun, "second"))
@@ -1618,6 +1634,7 @@ export function runMaterializerStorageContractSuite<TStorage extends Storage>(
     let failNextCommit = true
     let stagedIdentities = 0
     let plannedAt: string | undefined
+    let now = new Date("2026-03-01T00:00:00.000Z")
     const observed = observePlanning(
       storage,
       async (planned, commit) => {
@@ -1631,7 +1648,7 @@ export function runMaterializerStorageContractSuite<TStorage extends Storage>(
         throw new Error("commit lost")
       }
     )
-    const materializer = contractMaterializer(observed)
+    const materializer = contractMaterializer(observed, { clock: () => now })
     try {
       const execution = await claimDevices(storage, 1)
       const values = [sourceEntry("a", "A"), sourceEntry("b", "B", "a")]
@@ -1640,7 +1657,7 @@ export function runMaterializerStorageContractSuite<TStorage extends Storage>(
       )
       expect(stagedIdentities).toBe(3)
       // The redelivery's clock has moved on; its commit keeps the time its events were planned at.
-      await new Promise((resolve) => setTimeout(resolve, 5))
+      now = new Date("2026-03-01T00:00:01.000Z")
       const result = await publishDevices(materializer, storage, 1, values, execution)
       expect(stagedIdentities).toBe(3)
       expect(result.committedAt).toBe(plannedAt!)
@@ -1984,7 +2001,7 @@ async function claim(
   const identityBase = {
     projectionId: input.projectionId,
     datasetVersion: input.datasetVersion,
-    ontologyRevision: projections.ontologyRevision,
+    ontologyRevision: resolved.ontologyRevision,
     projectionRevision: resolved.projectionRevision,
     ownershipHash: resolved.ownershipHash,
   }
@@ -2027,17 +2044,27 @@ const CONTRACT_PROJECT = "materializer-storage-contract"
 
 function contractMaterializer(
   storage: Storage,
-  batching: { readonly transactionReplanRows?: number } = {},
-  onSerializationRetry?: () => void
+  options: {
+    readonly transactionReplanRows?: number
+    readonly onSerializationRetry?: () => void
+    readonly clock?: () => Date
+  } = {}
 ): OntologyMaterializer {
+  const { transactionReplanRows, onSerializationRetry, clock } = options
   return createOntologyMaterializer({
     projectId: CONTRACT_PROJECT,
     ontology,
     projections,
     storage,
     dependencies: {
-      batching: { sourceStageRows: 1, statePageRows: 1, planChunkRows: 1, ...batching },
+      batching: {
+        sourceStageRows: 1,
+        statePageRows: 1,
+        planChunkRows: 1,
+        ...(transactionReplanRows === undefined ? {} : { transactionReplanRows }),
+      },
       ...(onSerializationRetry === undefined ? {} : { onSerializationRetry }),
+      ...(clock === undefined ? {} : { clock }),
     },
   })
 }
@@ -2107,7 +2134,6 @@ function observePlanning(
   return observe(storage, false)
 }
 
-/** The same storage, whose transactions wait before they finalize until `release` is called. */
 /** Resolves `reached` when a transaction of `storage` first records an Action run. */
 function observeActionRunRecords(storage: ContractStorage) {
   const reached = Promise.withResolvers<void>()
@@ -2143,6 +2169,7 @@ function observeActionRunRecords(storage: ContractStorage) {
   return { storage: observed, reached: reached.promise }
 }
 
+/** The same storage, whose transactions wait before they finalize until `release` is called. */
 function pauseBeforeFinalize(storage: ContractStorage) {
   let reach!: () => void
   const reached = new Promise<void>((resolve) => {