@sixb/core 0.1.2 → 0.1.4

package/src/testing/ai-cost-storage-contract.ts

@@ -0,0 +1,320 @@
+import { describe, expect, test } from "bun:test"
+import type { AiCostStorage, AiModelCallCostRecord } from "../storage/ai-cost"
+import { AiCostStorageError } from "../storage/ai-cost"
+import type { AiUsageStorage } from "../storage/ai-usage"
+import type { ExecutionStorage } from "../storage/executions"
+
+export interface AiStorageContractSuiteOptions<TStorage> {
+  readonly createStorage: () => TStorage | Promise<TStorage>
+  readonly setup?: (storage: TStorage) => void | Promise<void>
+  readonly cleanup?: (storage: TStorage) => void | Promise<void>
+}
+
+const projectId = "cost-contract-project"
+const executionId = "exec_cost_1"
+const otherExecutionId = "exec_cost_2"
+
+function priceSource(entry: string) {
+  return {
+    sourceId: "test-catalog",
+    sourceEntryId: entry,
+    sourceVersion: "test-catalog-v1",
+    sourceUrl: "https://example.test/ai-pricing.json",
+    observedAt: new Date("2026-08-01T00:00:00.000Z"),
+  }
+}
+
+function ratedCost(
+  usageRecordId = "usage_1",
+  overrides: Partial<Extract<AiModelCallCostRecord, { status: "rated" }>> = {}
+): Extract<AiModelCallCostRecord, { status: "rated" }> {
+  return {
+    projectId,
+    usageRecordId,
+    status: "rated",
+    billingIdentity: { providerId: "vercel", modelId: "openai/gpt-5" },
+    pricingContext: {},
+    priceSource: priceSource("vercel/openai/gpt-5"),
+    money: { currency: "USD", amountNanos: "95000" },
+    components: [
+      {
+        meter: "tokens.input.uncached",
+        quantity: "12",
+        rateAmountNanosPerMillion: "1250000000",
+        chargeAmountNanos: "15000",
+      },
+      {
+        meter: "tokens.input.cacheRead",
+        quantity: "0",
+        rateAmountNanosPerMillion: "125000000",
+        chargeAmountNanos: "0",
+      },
+      {
+        meter: "tokens.output.total",
+        quantity: "8",
+        rateAmountNanosPerMillion: "10000000000",
+        chargeAmountNanos: "80000",
+      },
+    ],
+    ratedAt: new Date("2026-08-01T12:00:00.200Z"),
+    ...overrides,
+  }
+}
+
+function unpriceableCost(): Extract<AiModelCallCostRecord, { status: "unpriceable" }> {
+  return {
+    projectId,
+    usageRecordId: "usage_2",
+    status: "unpriceable",
+    billingIdentity: { providerId: "vercel", modelId: "unpriced/model" },
+    pricingContext: {},
+    priceSource: priceSource("vercel/unpriced/model"),
+    reason: "missingCatalogEntry",
+    ratedAt: new Date("2026-08-01T12:00:00.200Z"),
+  }
+}
+
+export function runAiCostStorageContractSuite<TStorage extends AiCostStorage>(
+  name: string,
+  options: AiStorageContractSuiteOptions<TStorage>
+): void {
+  describe(name, () => {
+    async function fixture(): Promise<TStorage> {
+      const storage = await options.createStorage()
+      await options.setup?.(storage)
+      return storage
+    }
+
+    test("records model-call costs idempotently", async () => {
+      const storage = await fixture()
+      try {
+        await expect(storage.recordModelCallCost(ratedCost())).resolves.toBeUndefined()
+        await expect(storage.recordModelCallCost(ratedCost())).resolves.toBeUndefined()
+        await expect(
+          storage.listModelCalls({
+            projectId,
+            from: new Date("2026-08-01T00:00:00.000Z"),
+            to: new Date("2026-08-02T00:00:00.000Z"),
+            valuationStatus: "rated",
+          })
+        ).resolves.toMatchObject({
+          total: 1,
+          items: [{ usage: { id: "usage_1" }, cost: ratedCost(), valuationStatus: "rated" }],
+        })
+      } finally {
+        await options.cleanup?.(storage)
+      }
+    })
+
+    test("stores explicit unpriceable results and pricing context", async () => {
+      const storage = await fixture()
+      try {
+        const deploymentCost: AiModelCallCostRecord = {
+          projectId,
+          usageRecordId: "usage_deployment",
+          status: "unpriceable",
+          billingIdentity: { providerId: "openai", modelId: "gpt-5" },
+          pricingContext: { deploymentId: "production" },
+          priceSource: priceSource("openai/gpt-5"),
+          reason: "unsupportedPricingDimension",
+          ratedAt: new Date("2026-08-03T12:00:00.200Z"),
+        }
+        await storage.recordModelCallCost(unpriceableCost())
+        await storage.recordModelCallCost(deploymentCost)
+        await expect(
+          storage.listModelCalls({
+            projectId,
+            from: new Date("2026-08-03T00:00:00.000Z"),
+            to: new Date("2026-08-04T00:00:00.000Z"),
+            valuationStatus: "unpriceable",
+          })
+        ).resolves.toMatchObject({
+          total: 1,
+          items: [{ cost: deploymentCost, valuationStatus: "unpriceable" }],
+        })
+      } finally {
+        await options.cleanup?.(storage)
+      }
+    })
+
+    test("summarizes and queries accounting without inventing missing costs", async () => {
+      const storage = await fixture()
+      try {
+        await storage.recordModelCallCost(ratedCost())
+        await storage.recordModelCallCost(unpriceableCost())
+        await expect(
+          storage.summarizeExecutions({ projectId, executionIds: [executionId] })
+        ).resolves.toEqual([
+          {
+            amounts: [{ currency: "USD", amountNanos: "95000" }],
+            ratedCallCount: 1,
+            unpriceableCallCount: 1,
+            unvaluedCallCount: 1,
+          },
+        ])
+
+        const overview = await storage.queryProjectOverview({
+          projectId,
+          from: new Date("2026-08-01T00:00:00.000Z"),
+          to: new Date("2026-08-02T00:00:00.000Z"),
+          bucket: "day",
+        })
+        expect(overview.totals).toEqual({
+          modelCallCount: 3,
+          usage: {
+            inputTokens: 15,
+            outputTokens: 12,
+            totalTokens: 27,
+            reportingStatus: "complete",
+          },
+          costs: {
+            amounts: [{ currency: "USD", amountNanos: "95000" }],
+            ratedCallCount: 1,
+            unpriceableCallCount: 1,
+            unvaluedCallCount: 1,
+          },
+        })
+        expect(overview.series).toMatchObject([{ modelCallCount: 3 }])
+        expect(overview.models).toMatchObject([
+          { providerId: "gateway", modelId: "openai/gpt-5", modelCallCount: 2 },
+          { providerId: "gateway", modelId: "unpriced/model", modelCallCount: 1 },
+        ])
+        await expect(
+          storage.queryProjectOverview({
+            projectId,
+            from: new Date("2026-08-01T00:00:00.000Z"),
+            to: new Date("2026-08-02T00:00:00.000Z"),
+            bucket: "day",
+            providerId: "gateway",
+            modelId: "unpriced/model",
+          })
+        ).resolves.toMatchObject({ totals: { modelCallCount: 1 } })
+        await expect(
+          storage.listModelCalls({
+            projectId,
+            from: new Date("2026-08-01T00:00:00.000Z"),
+            to: new Date("2026-08-02T00:00:00.000Z"),
+            limit: 1,
+            offset: 1,
+          })
+        ).resolves.toMatchObject({
+          total: 3,
+          hasMore: true,
+          items: [{ usage: { id: "usage_2" } }],
+        })
+        await expect(
+          storage.listModelCalls({
+            projectId,
+            from: new Date("2026-08-01T00:00:00.000Z"),
+            to: new Date("2026-08-02T00:00:00.000Z"),
+            valuationStatus: "unpriceable",
+          })
+        ).resolves.toMatchObject({
+          total: 1,
+          hasMore: false,
+          items: [{ usage: { id: "usage_2" }, valuationStatus: "unpriceable" }],
+        })
+      } finally {
+        await options.cleanup?.(storage)
+      }
+    })
+
+    test("rejects missing usage and mismatched billed quantities", async () => {
+      const storage = await fixture()
+      try {
+        const missing = ratedCost("missing")
+        const missingError = await storage.recordModelCallCost(missing).catch((value) => value)
+        expect(missingError).toBeInstanceOf(AiCostStorageError)
+        expect((missingError as AiCostStorageError).code).toBe("missing_usage")
+
+        const base = ratedCost()
+        const mismatch = ratedCost("usage_1", {
+          money: { currency: "USD", amountNanos: "96250" },
+          components: [
+            { ...base.components[0]!, quantity: "13", chargeAmountNanos: "16250" },
+            ...base.components.slice(1),
+          ],
+        })
+        const mismatchError = await storage.recordModelCallCost(mismatch).catch((value) => value)
+        expect(mismatchError).toBeInstanceOf(AiCostStorageError)
+        expect((mismatchError as AiCostStorageError).code).toBe("cost_mismatch")
+      } finally {
+        await options.cleanup?.(storage)
+      }
+    })
+  })
+}
+
+/** Seed immutable usage used by every cost-storage provider contract. */
+export async function seedAiCostStorageContractUsage(
+  executions: ExecutionStorage,
+  usage: AiUsageStorage
+): Promise<void> {
+  for (const fixture of [
+    { projectId, executionId },
+    { projectId, executionId: otherExecutionId },
+  ]) {
+    if (await executions.getById({ projectId: fixture.projectId, id: fixture.executionId }))
+      continue
+    const primitive = {
+      kind: "workflow" as const,
+      id: "ai-cost-contract",
+      runId: fixture.executionId,
+    }
+    await executions.create({
+      id: fixture.executionId,
+      projectId: fixture.projectId,
+      executor: { type: "primitive", kind: primitive.kind, runId: primitive.runId },
+      source: { type: "event", eventId: `test_event:${fixture.executionId}` },
+      correlationId: `test_correlation:${fixture.executionId}`,
+      authorizationRef: { type: "trustedPrimitive", primitive },
+    })
+  }
+
+  for (const fixture of [
+    { id: "usage_1", model: "openai/gpt-5", input: 12, output: 8 },
+    { id: "usage_2", model: "unpriced/model", input: 1, output: 1 },
+    { id: "usage_3", model: "openai/gpt-5", input: 2, output: 3 },
+  ]) {
+    await usage.recordModelCall({
+      id: fixture.id,
+      projectId,
+      executionId,
+      attempt: 1,
+      callId: `call_${fixture.id}`,
+      requesterGroupIds: [],
+      providerId: "gateway",
+      requestedModelId: fixture.model,
+      responseId: `response_${projectId}_${fixture.id}`,
+      usage: {
+        inputTokens: fixture.input,
+        outputTokens: fixture.output,
+        ...(fixture.id === "usage_1"
+          ? { uncachedInputTokens: fixture.input, cacheReadInputTokens: 0 }
+          : {}),
+      },
+      occurredAt: new Date("2026-08-01T12:00:00.000Z"),
+      recordedAt: new Date("2026-08-01T12:00:00.100Z"),
+    })
+  }
+
+  await usage.recordModelCall({
+    id: "usage_deployment",
+    projectId,
+    executionId: otherExecutionId,
+    attempt: 1,
+    callId: "call_usage_deployment",
+    requesterGroupIds: [],
+    providerId: "openai.responses",
+    requestedModelId: "gpt-5",
+    responseId: "response_usage_deployment",
+    usage: {
+      inputTokens: 2,
+      outputTokens: 3,
+      uncachedInputTokens: 2,
+      cacheReadInputTokens: 0,
+    },
+    occurredAt: new Date("2026-08-03T12:00:00.000Z"),
+    recordedAt: new Date("2026-08-03T12:00:00.100Z"),
+  })
+}

package/src/testing/ai-usage-storage-contract.ts

@@ -145,6 +145,41 @@ export function runAiUsageStorageContractSuite<TStorage extends AiUsageStorage>(
       })
     })
 
+    test("returns the latest completed call for one execution", async () => {
+      await withStorage(async (storage) => {
+        await expect(
+          storage.getLatestForExecution({ projectId, executionId: agentExecutionId })
+        ).resolves.toBeNull()
+
+        await storage.recordModelCall(
+          modelCallInput({
+            id: "usage_later",
+            callId: "call_later",
+            responseId: "response_later",
+            occurredAt: at("2026-06-23T10:02:00.000Z"),
+          })
+        )
+        await storage.recordModelCall(
+          modelCallInput({
+            id: "usage_earlier",
+            callId: "call_earlier",
+            responseId: "response_earlier",
+            occurredAt: at("2026-06-23T10:01:00.000Z"),
+          })
+        )
+
+        await expect(
+          storage.getLatestForExecution({ projectId, executionId: agentExecutionId })
+        ).resolves.toMatchObject({ id: "usage_later", responseId: "response_later" })
+        await expect(
+          storage.getLatestForExecution({
+            projectId: "other-project",
+            executionId: agentExecutionId,
+          })
+        ).resolves.toBeNull()
+      })
+    })
+
     test("bills the same call and response IDs again on a later delivery attempt", async () => {
       // Regression guard: remove `attempt` from a provider's idempotency key/query/index and the
       // second append collapses into the first, making the aggregate assertions fail.

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

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test"
 import { defineObjectType, link, OntologyRegistry, prop } from "../ontology"
-import type { Storage } from "../storage"
+import { linkBatchKey, objectBatchKey, objectLinkCursor, type Storage } from "../storage"
 import { createMaterializerTestFixture } from "./materializer-fixture"
 
 export interface EffectiveStorageContractSuiteOptions<TStorage extends Storage> {
@@ -19,7 +19,25 @@ const Device = defineObjectType({
   ],
   links: [link.self("peers", { cardinality: "many" })],
 })
-const ontology = new OntologyRegistry({ sources: [Device] })
+const OpaqueA = defineObjectType({
+  id: "A",
+  name: "Opaque A",
+  properties: [
+    prop("id", "string", { primary: true, required: true }),
+    prop("name", "string", { required: true }),
+  ],
+  links: [link.self("D", { cardinality: "many" })],
+})
+const OpaqueAB = defineObjectType({
+  id: "A:B",
+  name: "Opaque AB",
+  properties: [
+    prop("id", "string", { primary: true, required: true }),
+    prop("name", "string", { required: true }),
+  ],
+  links: [link.self("D", { cardinality: "many" })],
+})
+const ontology = new OntologyRegistry({ sources: [Device, OpaqueA, OpaqueAB] })
 
 export function runEffectiveStorageContractSuite<TStorage extends Storage>(
   name: string,
@@ -56,7 +74,7 @@ export function runEffectiveStorageContractSuite<TStorage extends Storage>(
             { objectTypeId: Device.id, primaryId: "missing" },
           ],
         })
-        expect([...batch.keys()]).toEqual([`${Device.id}:a`])
+        expect([...batch.keys()]).toEqual([objectBatchKey(Device.id, "a")])
       })
     })
 
@@ -81,7 +99,179 @@ export function runEffectiveStorageContractSuite<TStorage extends Storage>(
           projectId,
           items: [{ objectTypeId: Device.id, objectId: "a", linkId: "peers" }],
         })
-        expect(linksByScope.get(`${Device.id}:a:peers`)).toHaveLength(2)
+        expect(linksByScope.get(linkBatchKey(Device.id, "a", "peers"))).toHaveLength(2)
+      })
+    })
+
+    test("pages and filters incident links in the provider", async () => {
+      await withStorage(async (storage) => {
+        const first = await storage.objects.queryLinks({
+          projectId,
+          objectRefs: [{ objectTypeId: Device.id, primaryId: "a" }],
+          direction: "outgoing",
+          linkId: "peers",
+          endpointObjectTypeIds: [Device.id],
+          limit: 1,
+        })
+        expect(first.links.map((row) => row.targetId)).toEqual(["b"])
+        expect(first.hasMore).toBe(true)
+
+        const second = await storage.objects.queryLinks({
+          projectId,
+          objectRefs: [{ objectTypeId: Device.id, primaryId: "a" }],
+          direction: "outgoing",
+          linkId: "peers",
+          endpointObjectTypeIds: [Device.id],
+          after: objectLinkCursor(first.links[0]),
+          limit: 1,
+        })
+        expect(second.links.map((row) => row.targetId)).toEqual(["c"])
+        expect(second.hasMore).toBe(false)
+
+        const duplicateRefs = await storage.objects.queryLinks({
+          projectId,
+          objectRefs: [
+            { objectTypeId: Device.id, primaryId: "a" },
+            { objectTypeId: Device.id, primaryId: "a" },
+          ],
+          direction: "outgoing",
+          limit: 10,
+        })
+        expect(duplicateRefs.links.map((row) => row.targetId)).toEqual(["b", "c"])
+
+        const incoming = await storage.objects.queryLinks({
+          projectId,
+          objectRefs: [{ objectTypeId: Device.id, primaryId: "b" }],
+          direction: "incoming",
+          limit: 10,
+        })
+        expect(incoming.links.map((row) => [row.sourceId, row.targetId])).toEqual([["a", "b"]])
+
+        const bothDirections = await storage.objects.queryLinks({
+          projectId,
+          objectRefs: [
+            { objectTypeId: Device.id, primaryId: "a" },
+            { objectTypeId: Device.id, primaryId: "b" },
+          ],
+          direction: "both",
+          endpointObjectTypeIds: [Device.id],
+          limit: 10,
+        })
+        expect(bothDirections.links.map((row) => [row.sourceId, row.targetId])).toEqual([
+          ["a", "b"],
+          ["a", "c"],
+        ])
+
+        const unauthorized = await storage.objects.queryLinks({
+          projectId,
+          objectRefs: [{ objectTypeId: Device.id, primaryId: "a" }],
+          direction: "both",
+          endpointObjectTypeIds: [],
+          limit: 10,
+        })
+        expect(unauthorized).toEqual({ links: [], hasMore: false })
+      })
+    })
+
+    test("keeps delimiter-bearing object and batch-link identities distinct", async () => {
+      await withStorage(async (storage) => {
+        const opaqueProjectId = `${projectId}-opaque-batch-keys`
+        const fixture = createMaterializerTestFixture({
+          projectId: opaqueProjectId,
+          ontology,
+          storage,
+        })
+        await fixture.seed({
+          objects: [
+            {
+              ref: { objectTypeId: OpaqueA.id, primaryId: "B:C" },
+              properties: { id: "B:C", name: "First" },
+            },
+            {
+              ref: { objectTypeId: OpaqueAB.id, primaryId: "C" },
+              properties: { id: "C", name: "Second" },
+            },
+          ],
+          links: [
+            {
+              ref: {
+                source: { objectTypeId: OpaqueA.id, primaryId: "B:C" },
+                linkId: "D",
+                target: { objectTypeId: OpaqueA.id, primaryId: "B:C" },
+              },
+            },
+            {
+              ref: {
+                source: { objectTypeId: OpaqueAB.id, primaryId: "C" },
+                linkId: "D",
+                target: { objectTypeId: OpaqueAB.id, primaryId: "C" },
+              },
+            },
+          ],
+        })
+
+        const objects = await storage.objects.getByPrimaryIdBatch({
+          projectId: opaqueProjectId,
+          items: [
+            { objectTypeId: OpaqueA.id, primaryId: "B:C" },
+            { objectTypeId: OpaqueAB.id, primaryId: "C" },
+          ],
+        })
+        expect(objects.get(objectBatchKey(OpaqueA.id, "B:C"))?.properties.name).toBe("First")
+        expect(objects.get(objectBatchKey(OpaqueAB.id, "C"))?.properties.name).toBe("Second")
+
+        const links = await storage.objects.listLinksBatch({
+          projectId: opaqueProjectId,
+          items: [
+            { objectTypeId: OpaqueA.id, objectId: "B:C", linkId: "D" },
+            { objectTypeId: OpaqueAB.id, objectId: "C", linkId: "D" },
+          ],
+        })
+        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({
+          projectId: opaqueIdsProjectId,
+          ontology,
+          storage,
+        })
+        await fixture.seed({
+          objects: [
+            device(firstSourceId, "First source"),
+            device(firstTargetId, "First target"),
+            device(secondSourceId, "Second source"),
+            device(secondTargetId, "Second target"),
+          ],
+          links: [peer(firstSourceId, firstTargetId), peer(secondSourceId, secondTargetId)],
+        })
+
+        const incident = await storage.objects.listIncidentLinksBatch({
+          projectId: opaqueIdsProjectId,
+          items: [
+            { objectTypeId: Device.id, objectId: firstSourceId },
+            { objectTypeId: Device.id, objectId: secondSourceId },
+          ],
+        })
+        const matching = incident.filter(
+          (row) => row.sourceId === firstSourceId || row.sourceId === secondSourceId
+        )
+
+        expect(matching.map((row) => [row.sourceId, row.linkId, row.targetId])).toEqual(
+          expect.arrayContaining([
+            [firstSourceId, "peers", firstTargetId],
+            [secondSourceId, "peers", secondTargetId],
+          ])
+        )
+        expect(matching).toHaveLength(2)
       })
     })
 

package/src/testing/index.ts

@@ -7,6 +7,11 @@ export {
   type AgentStorageContractSuiteOptions,
   runAgentStorageContractSuite,
 } from "./agent-storage-contract"
+export {
+  type AiStorageContractSuiteOptions,
+  runAiCostStorageContractSuite,
+  seedAiCostStorageContractUsage,
+} from "./ai-cost-storage-contract"
 export {
   type AiUsageStorageContractSuiteOptions,
   runAiUsageStorageContractSuite,

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

@@ -438,6 +438,62 @@ export function runLakeStorageContractSuite<TStorage extends LakeStorage>(
         })
       })
 
+      test("creates an initial empty snapshot version", async () => {
+        await withStorage(async (storage) => {
+          await storage.createDataset(writeDataset)
+
+          const write = await storage.beginWrite({ dataset: writeDataset, mode: "snapshot" })
+          const version = await write.commit()
+
+          expect(version).toMatchObject({
+            datasetId: writeDataset.id,
+            mode: "snapshot",
+            outcome: "created",
+            rowCount: 0,
+          })
+          expect(await storage.getLatestVersion(writeDataset.id)).toMatchObject({
+            versionId: version.versionId,
+          })
+          expect(await storage.listVersions(writeDataset.id)).toHaveLength(1)
+
+          const repeatedWrite = await storage.beginWrite({
+            dataset: writeDataset,
+            mode: "snapshot",
+          })
+          const repeatedVersion = await repeatedWrite.commit()
+          expect(repeatedVersion.outcome).toBe("unchanged")
+          expect(repeatedVersion.versionId).toBe(version.versionId)
+          expect(await storage.listVersions(writeDataset.id)).toHaveLength(1)
+
+          await expect(
+            collectRows(storage.readRows({ datasetId: writeDataset.id }))
+          ).resolves.toEqual([])
+        })
+      })
+
+      test("creates an initial empty append version", async () => {
+        await withStorage(async (storage) => {
+          await storage.createDataset(writeDataset)
+
+          const write = await storage.beginWrite({ dataset: writeDataset, mode: "append" })
+          const version = await write.commit()
+
+          expect(version).toMatchObject({
+            datasetId: writeDataset.id,
+            mode: "append",
+            outcome: "created",
+          })
+          expect(version.parentVersionId).toBeUndefined()
+          expect(await storage.getLatestVersion(writeDataset.id)).toMatchObject({
+            versionId: version.versionId,
+          })
+          expect(await storage.listVersions(writeDataset.id)).toHaveLength(1)
+          await expect(
+            collectRows(storage.readRows({ datasetId: writeDataset.id }))
+          ).resolves.toEqual([])
+        })
+      })
+
       test("snapshot writes replace the visible latest rows", async () => {
         await withStorage(async (storage) => {
           await storage.createDataset(writeDataset)