@sixb/core 0.1.20 → 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

@@ -1,7 +1,8 @@
-import { describe, expect, test } from "bun:test"
+import { describe, expect, setSystemTime, test } from "bun:test"
 import type { AuthStorage } from "../storage/auth"
 import type {
   CreateExecutionInput,
+  ExecutionRecord,
   ExecutionStorage,
   TrustedPrimitiveKind,
 } from "../storage/executions"
@@ -338,6 +339,179 @@ export function runExecutionStorageContractSuite<TStorage extends ExecutionStora
       })
     })
 
+    test("lists a session's roots in a window and everything they caused", async () => {
+      // Removal proof: drop `parent_execution_id IS NULL` from a provider's root read; the Agent
+      // execution, which copies the session, is listed twice.
+      await withStorage(async (storage) => {
+        await seedAuth(storage.auth)
+        await seedSharedSession(storage)
+
+        const userRequest = (id: string) =>
+          principalRequest({ id, credential: { type: "session", id: "session-user" } })
+
+        await createAt(storage, -60_000, userRequest("before"))
+        const root = await createAt(storage, 0, userRequest("root"))
+        await createAt(storage, 1_000, childOf(root, trustedPrimitive("root-action")))
+        await createAt(
+          storage,
+          2_000,
+          principalRequest({
+            id: "other-user",
+            principal: { type: "user", id: "user-other" },
+            credential: { type: "session", id: "session-other" },
+          })
+        )
+        await createAt(storage, 3_000, delegatedRequest("shared"))
+        await createAt(storage, 4_000, {
+          ...childOf(root, agentExecution("root-agent")),
+          authorizationRef: root.authorizationRef,
+        })
+        await createAt(storage, 10 * 60_000, userRequest("after"))
+        // A descendant counts whenever it was created, after the window too.
+        await createAt(
+          storage,
+          11 * 60_000,
+          childOf(
+            { id: "root-action", correlationId: root.correlationId },
+            trustedPrimitive("late-workflow", {}, "workflow")
+          )
+        )
+
+        const window = {
+          projectId,
+          from: new Date(createdAt.getTime() - 1_000),
+          to: new Date(createdAt.getTime() + 5 * 60_000),
+          limit: 10,
+        }
+
+        const user = await storage.executions.listBySession({
+          ...window,
+          session: { type: "user", id: "session-user" },
+        })
+        expect(user.truncated).toBe(false)
+        expect(user.executions.map((execution) => execution.id)).toEqual([
+          "root",
+          "root-action",
+          "root-agent",
+          "late-workflow",
+        ])
+        expect(user.executions[0]).toEqual(root)
+
+        const shared = await storage.executions.listBySession({
+          ...window,
+          session: { type: "share", id: "share-session-one" },
+        })
+        expect(shared.executions.map((execution) => execution.id)).toEqual(["shared"])
+
+        // The session id is not a credential of any other kind.
+        await expect(
+          storage.executions.listBySession({
+            ...window,
+            session: { type: "share", id: "session-user" },
+          })
+        ).resolves.toEqual({ executions: [], truncated: false })
+      })
+    })
+
+    test("bounds a session's executions, keeping roots and the earliest first", async () => {
+      await withStorage(async (storage) => {
+        await seedAuth(storage.auth)
+
+        for (const [index, id] of ["first", "second", "third"].entries()) {
+          const root = await createAt(
+            storage,
+            index * 1_000,
+            principalRequest({ id, credential: { type: "session", id: "session-user" } })
+          )
+          await createAt(storage, index * 1_000 + 500, childOf(root, trustedPrimitive(`${id}-run`)))
+        }
+
+        const list = (limit: number) =>
+          storage.executions.listBySession({
+            projectId,
+            session: { type: "user", id: "session-user" },
+            from: createdAt,
+            to: new Date(createdAt.getTime() + 60_000),
+            limit,
+          })
+
+        const roots = await list(2)
+        expect(roots.truncated).toBe(true)
+        expect(roots.executions.map((execution) => execution.id)).toEqual(["first", "second"])
+
+        const partial = await list(4)
+        expect(partial.truncated).toBe(true)
+        expect(partial.executions).toHaveLength(4)
+        expect(partial.executions.map((execution) => execution.id)).toEqual(
+          expect.arrayContaining(["first", "second", "third"])
+        )
+
+        const all = await list(6)
+        expect(all.truncated).toBe(false)
+        expect(all.executions.map((execution) => execution.id)).toEqual([
+          "first",
+          "first-run",
+          "second",
+          "second-run",
+          "third",
+          "third-run",
+        ])
+      })
+    })
+
+    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(
@@ -355,6 +529,31 @@ export function runExecutionStorageContractSuite<TStorage extends ExecutionStora
   })
 }
 
+/** Creates an execution at `offsetMs` after the fixtures' creation time: storage stamps it. */
+async function createAt(
+  storage: ExecutionStorageContractStorage,
+  offsetMs: number,
+  input: CreateExecutionInput
+): Promise<ExecutionRecord> {
+  setSystemTime(new Date(createdAt.getTime() + offsetMs))
+  try {
+    return await storage.executions.create(input)
+  } finally {
+    setSystemTime()
+  }
+}
+
+function childOf(
+  parent: Pick<ExecutionRecord, "id" | "correlationId">,
+  input: CreateExecutionInput
+): CreateExecutionInput {
+  return {
+    ...input,
+    source: { type: "execution", executionId: parent.id },
+    correlationId: parent.correlationId,
+  }
+}
+
 async function seedAuth(auth: AuthStorage): Promise<void> {
   await auth.users.create({
     id: "user-one",

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

@@ -9,7 +9,21 @@ export {
   type ActionRunStorageContractSuiteOptions,
   runActionRunStorageContractSuite,
 } from "./action-run-storage-contract"
+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,
@@ -23,7 +37,6 @@ export {
   type AiLimitStorageContractStorage,
   type AiLimitStorageContractSuiteOptions,
   runAiLimitStorageContractSuite,
-  seedAiLimitStorageContractExecution,
 } from "./ai-limit-storage-contract"
 export {
   type AiModelCallGroupsContractStorage,
@@ -34,8 +47,14 @@ export {
   runAiUsageStorageContractSuite,
   seedAiUsageStorageContractExecutions,
 } from "./ai-usage-storage-contract"
+export {
+  type ArtifactStorageContractStorage,
+  type ArtifactStorageContractSuiteOptions,
+  runArtifactStorageContractSuite,
+} from "./artifact-storage-contract"
 export {
   type AuthStorageContractSuiteOptions,
+  type AuthUserHold,
   runAuthStorageContractSuite,
 } from "./auth-storage-contract"
 export {
@@ -100,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,
@@ -124,7 +143,6 @@ export {
 } from "./pipeline-execution"
 export {
   claimTestProjectionRun,
-  createTestProjectionExecution,
   queueTestProjectionRun,
   startTestProjectionRun,
 } from "./projection-execution"
@@ -156,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-merge-storage-contract.ts

@@ -285,6 +285,44 @@ export function runLakeMergeStorageContractSuite<TStorage extends LakeStorage>(
         expect(await storage.listVersions(invoices.id)).toHaveLength(1)
       })
     })
+
+    test("a merge keeps its parent's lineage", async () => {
+      await withStorage(async (storage) => {
+        await storage.createDataset(invoices)
+
+        const source = (column: string) => ({ datasetId: "contract.source", column })
+        const lineage = {
+          rows: [source("tenant")],
+          columns: { id: [source("id")], note: [source("amount")], status: [source("state")] },
+        }
+
+        const pipeline = { kind: "pipeline", id: "contract-pipeline" } as const
+        const seed = await storage.beginWrite({ dataset: invoices, producer: pipeline, lineage })
+        await seed.writeRows([{ id: "inv_1", status: "open", note: "120.00" }])
+        await seed.commit()
+
+        const sync = { kind: "sync", id: "sync-invoices" } as const
+        const merge = await storage.beginMerge({ dataset: invoices, producer: sync })
+        await merge.writeChanges([change.upsert({ id: "inv_2", status: "paid", note: null })])
+        const merged = expectCreated(await merge.commit())
+
+        // Its own rows depend on its own columns only; the rows it keeps, on what they did.
+        expect(merged.lineage).toEqual(lineage)
+        expect((await storage.getVersion(invoices.id, merged.versionId))?.lineage).toEqual(lineage)
+
+        // A parent that records no lineage could hold anything, and so could the merge.
+        const unanalyzed = await storage.beginWrite({ dataset: invoices, producer: pipeline })
+        await unanalyzed.writeRows([{ id: "inv_1", status: "open", note: "120.00" }])
+        const legacy = await unanalyzed.commit()
+
+        const next = await storage.beginMerge({ dataset: invoices, producer: sync })
+        await next.writeChanges([change.upsert({ id: "inv_3", status: "open", note: null })])
+
+        expect(expectCreated(await next.commit()).lineage).toEqual({
+          unknown: `version '${legacy.versionId}' of '${invoices.id}' recorded no column lineage`,
+        })
+      })
+    })
   })
 }