@sixb/core 0.1.11 → 0.1.12

package/src/storage/ontology/index.ts

@@ -2,6 +2,8 @@ import type { OntologyCommitStorage } from "./commits"
 import type { OntologyMaterializationStorage } from "./materializations"
 import type { OntologyOutboxStorage } from "./outbox"
 import type { OntologySourceStorage } from "./sources"
+import type { OntologyVectorIndexingStorage } from "./vector-indexing"
+import type { OntologyVectorStorage } from "./vectors"
 
 export type { ProjectionExecution } from "../../materialization/model"
 export type {
@@ -119,9 +121,21 @@ export type {
   TerminalSourceMaterializationSummary,
 } from "./sources"
 
+export type { ObjectVectorState, OntologyVectorStorage, StoredObjectVector } from "./vectors"
+
 export interface OntologyStorage {
+  readonly vectorIndexing?: OntologyVectorIndexingStorage
+  readonly vectors?: OntologyVectorStorage
   readonly commits: OntologyCommitStorage
   readonly sources: OntologySourceStorage
   readonly materializations: OntologyMaterializationStorage
   readonly outbox: OntologyOutboxStorage
 }
+
+export type {
+  OntologyVectorIndexingStorage,
+  VectorIndexingFailureCode,
+  VectorIndexingRequest,
+  VectorIndexingUpdate,
+  VectorIndexingWork,
+} from "./vector-indexing"

package/src/storage/ontology/vector-indexing.ts

@@ -0,0 +1,98 @@
+import type { SixbFailure } from "../../errors/types"
+import type { OntologyObjectRef } from "../../materialization/model"
+import type { MaterializationSession } from "./materializations"
+
+export const VECTOR_INDEXING_FAILURE_CODES = [
+  "vector.model_unavailable",
+  "vector.response_invalid",
+  "vector.outcome_unknown",
+  "internal.unexpected",
+] as const
+
+export type VectorIndexingFailureCode = (typeof VECTOR_INDEXING_FAILURE_CODES)[number]
+
+/** Latest desired representation; replacing its id fences every older delivery. */
+export interface VectorIndexingRequest {
+  readonly id: string
+  /** Set only by projection materialization; a bounded, immediately durable group. */
+  readonly batchId?: string
+  readonly ref: OntologyObjectRef
+  readonly profile: string
+  readonly configuration: string
+  readonly sourceFingerprint: string
+  readonly sourceCommitId: string
+}
+
+export interface VectorIndexingWork extends VectorIndexingRequest {
+  readonly status: "pending" | "running" | "ready" | "failed"
+  readonly availableAt: string
+  readonly values?: readonly number[]
+  readonly error?: SixbFailure<VectorIndexingFailureCode>
+}
+
+export interface VectorIndexingUpdate {
+  readonly id: string
+  readonly expectedStatus: VectorIndexingWork["status"]
+  readonly status: VectorIndexingWork["status"]
+  readonly availableAt: string
+  readonly values?: readonly number[]
+  readonly error?: SixbFailure<VectorIndexingFailureCode>
+}
+
+/** Durable intent belongs to ontology storage; delivery leases belong to Queues. */
+export interface OntologyVectorIndexingStorage {
+  /** Called inside the transaction that changes the effective object. */
+  schedule(input: {
+    projectId: string
+    session: MaterializationSession
+    requests: readonly VectorIndexingRequest[]
+    deleted: readonly OntologyObjectRef[]
+    availableAt: string
+  }): Promise<void>
+  /** Clear matching intent atomically with a successful automatic or explicit vector write. */
+  complete(input: {
+    projectId: string
+    session: MaterializationSession
+    entries: readonly Pick<
+      VectorIndexingRequest,
+      "ref" | "profile" | "configuration" | "sourceFingerprint"
+    >[]
+  }): Promise<void>
+  dispatched(input: {
+    projectId: string
+    ids: readonly string[]
+    nextDispatchAt: string
+  }): Promise<void>
+  get(input: { projectId: string; id: string }): Promise<VectorIndexingWork | null>
+  getBatch(input: { projectId: string; batchId: string }): Promise<readonly VectorIndexingWork[]>
+  /** Read only the result this kernel batch is allowed to publish. */
+  getBatchMember(input: {
+    projectId: string
+    batchId: string
+    ref: OntologyObjectRef
+    profile: string
+  }): Promise<VectorIndexingWork | null>
+  /** Atomic transitions; requireAll prevents admission if any prepared member was superseded. */
+  updateBatch(input: {
+    projectId: string
+    updates: readonly VectorIndexingUpdate[]
+    requireAll?: boolean
+  }): Promise<boolean>
+  /** Bounded fair redispatch scan. Never scans objects or backfills existing data. */
+  listDue(input: {
+    projectId: string
+    now: string
+    limit: number
+  }): Promise<readonly VectorIndexingWork[]>
+  /** CAS also fences concurrent deliveries and source changes. */
+  update(input: {
+    projectId: string
+    id: string
+    expectedStatus: VectorIndexingWork["status"]
+    status: VectorIndexingWork["status"]
+    availableAt: string
+    values?: readonly number[]
+    error?: SixbFailure<VectorIndexingFailureCode>
+  }): Promise<boolean>
+  remove(input: { projectId: string; id: string }): Promise<void>
+}

package/src/storage/ontology/vectors.ts

@@ -0,0 +1,48 @@
+import type { OntologyObjectRef } from "../../materialization/model"
+import type { MaterializationSession } from "./materializations"
+
+export interface ObjectVectorState {
+  readonly ref: OntologyObjectRef
+  readonly profile: string
+  readonly configuration: string
+  readonly source: readonly string[]
+  readonly sourceFingerprint: string
+  readonly lastCommitId: string
+}
+
+export interface StoredObjectVector extends ObjectVectorState {
+  readonly values: readonly number[]
+}
+
+/** Transactional derived state. Mutations must run inside an ontology materialization transaction. */
+export interface OntologyVectorStorage {
+  list(input: { projectId: string; ref: OntologyObjectRef }): Promise<readonly ObjectVectorState[]>
+  listBatch(input: {
+    projectId: string
+    refs: readonly OntologyObjectRef[]
+  }): Promise<readonly ObjectVectorState[]>
+  removeBatch(input: {
+    session: MaterializationSession
+    projectId: string
+    entries: readonly { ref: OntologyObjectRef; profile: string; expectedCommitId: string }[]
+  }): Promise<void>
+  write(input: {
+    session: MaterializationSession
+    projectId: string
+    value: StoredObjectVector
+    expectedCommitId: string | null
+  }): Promise<void>
+  /** Write a validated set inside the materialization transaction; any conflict aborts it. */
+  writeBatch(input: {
+    session: MaterializationSession
+    projectId: string
+    entries: readonly { value: StoredObjectVector; expectedCommitId: string | null }[]
+  }): Promise<void>
+  remove(input: {
+    session: MaterializationSession
+    projectId: string
+    ref: OntologyObjectRef
+    profile: string
+    expectedCommitId: string
+  }): Promise<void>
+}

package/src/storage/operation-scope.ts

@@ -230,6 +230,7 @@ export function createOntologyOperationScope<T extends OntologyStorage>(
     sources: createOperationScopedFacade(target.sources, scope),
     materializations: createOperationScopedFacade(target.materializations, scope),
     outbox: createOperationScopedFacade(target.outbox, scope),
+    ...(target.vectors ? { vectors: createOperationScopedFacade(target.vectors, scope) } : {}),
   }) as T
 }
 

package/src/storage/types.ts

@@ -50,6 +50,8 @@ export type {
   AgentRunRecord,
   AgentStorage,
   AgentThreadRecord,
+  AgentThreadSandboxParams,
+  AgentThreadSandboxState,
   AppendAgentMessageInput,
   ConfirmAgentRunExecutionOwnershipInput,
   ConversationAgentRunRecord,
@@ -70,6 +72,7 @@ export type {
   SubagentRunRecord,
   SubagentRunResult,
   SubagentRunSpec,
+  TransitionAgentThreadSandboxInput,
 } from "./agents"
 export { AGENT_RUN_FAILURE_CODES, AgentStorageError } from "./agents"
 export type {

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

@@ -290,6 +290,252 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorageContra
   }
 
   describe(label, () => {
+    test("replaces lost state only under its current execution fence", async () => {
+      // Regression proof: remove replace's name/owner guards; the stale attempts succeed.
+      await withStorage(async (storage, fixture) => {
+        await storage.threads.create(threadInput({ sandboxParams: {} }))
+        const run = runInput({ execution: execution("first", new Date("2099-01-01")) })
+        await createAndStartRun(storage, fixture, run)
+        const acquire = {
+          projectId,
+          id: "thr_1",
+          action: "acquire" as const,
+          runId: run.id,
+          executionToken: "first",
+          name: "name-1",
+          sourceFingerprint: "a".repeat(64),
+        }
+        await storage.threads.transitionSandbox(acquire)
+        const replace = { ...acquire, action: "replace" as const, nextName: "name-2" }
+        await expectAgentError(storage.threads.transitionSandbox(replace), "invalid_state")
+        await storage.threads.transitionSandbox({
+          ...acquire,
+          action: "settle",
+          status: "ready",
+          initialized: true,
+        })
+        await expectAgentError(storage.threads.transitionSandbox(replace), "invalid_state")
+        await storage.threads.transitionSandbox(acquire)
+        for (const nextName of ["name-1", "../invalid", ""]) {
+          await expectAgentError(
+            storage.threads.transitionSandbox({ ...replace, nextName }),
+            "invalid_state"
+          )
+        }
+        await expectAgentError(
+          storage.threads.transitionSandbox({ ...replace, executionToken: "stale" }),
+          "execution_lost"
+        )
+        const replacement = await storage.threads.transitionSandbox(replace)
+        const resetAt = replacement.resetAt
+        expect(replacement).toMatchObject({
+          name: "name-2",
+          status: "busy",
+          initialized: false,
+          owner: { runId: run.id, executionToken: "first" },
+          sourceFingerprint: acquire.sourceFingerprint,
+          resetAt: expect.any(String),
+        })
+        await expectAgentError(storage.threads.transitionSandbox(replace), "invalid_state")
+        await expectAgentError(
+          storage.threads.transitionSandbox({
+            ...acquire,
+            action: "settle",
+            status: "ready",
+            initialized: true,
+          }),
+          "invalid_state"
+        )
+        await storage.threads.transitionSandbox({
+          ...acquire,
+          name: "name-2",
+          action: "settle",
+          status: "ready",
+          initialized: true,
+        })
+        const resumed = await storage.threads.transitionSandbox({
+          ...acquire,
+          name: "name-2",
+        })
+        expect(resumed.resetAt).toBe(resetAt)
+        expect((await storage.threads.getById({ projectId, id: "thr_1" }))?.sandboxState).toEqual(
+          resumed
+        )
+      })
+    })
+
+    test("fences workspace ownership across reclamation and explicit recreation", async () => {
+      // Regression proof: remove the busy-state or owner-token checks in transitionAgentThreadSandbox.
+      await withStorage(async (storage, fixture) => {
+        await storage.threads.create(threadInput({ sandboxParams: {} }))
+        const input = runInput({ execution: execution("first", new Date("2099-01-01")) })
+        await createTestAgentExecution(fixture, {
+          projectId,
+          runId: input.id,
+          executionId: input.executionId,
+          authority: "inherited",
+        })
+        await storage.runs.create(input)
+        await storage.runs.start(input)
+        const acquire = {
+          projectId,
+          id: "thr_1",
+          action: "acquire" as const,
+          runId: input.id,
+          executionToken: "first",
+          name: "name-1",
+          sourceFingerprint: "a".repeat(64),
+        }
+        const attempts = await Promise.allSettled([
+          storage.threads.transitionSandbox(acquire),
+          storage.threads.transitionSandbox(acquire),
+        ])
+        expect(attempts.filter((attempt) => attempt.status === "fulfilled")).toHaveLength(1)
+        expect(
+          (await storage.threads.getById({ projectId, id: "thr_1" }))?.sandboxState
+        ).toMatchObject({ status: "busy", initialized: false })
+        await expectAgentError(storage.threads.transitionSandbox(acquire), "invalid_state")
+        await storage.runs.reclaim({
+          projectId,
+          id: input.id,
+          execution: execution("second", new Date("2099-01-01")),
+        })
+        await expectAgentError(
+          storage.threads.transitionSandbox({
+            ...acquire,
+            executionToken: "second",
+          }),
+          "invalid_state"
+        )
+        await expectAgentError(
+          storage.threads.transitionSandbox({
+            ...acquire,
+            action: "settle",
+            status: "ready",
+            initialized: true,
+          }),
+          "execution_lost"
+        )
+        const recreate = {
+          projectId,
+          id: "thr_1",
+          action: "recreate" as const,
+          expectedSandboxName: "name-1",
+          name: "name-2",
+        }
+        await expectAgentError(storage.threads.transitionSandbox(recreate), "invalid_state")
+        await storage.runs.finish({
+          projectId,
+          id: input.id,
+          executionToken: "second",
+          status: "failed",
+        })
+        expect(await storage.threads.transitionSandbox(recreate)).toEqual({
+          name: "name-2",
+          status: "new",
+          initialized: false,
+          resetAt: expect.any(String),
+        })
+        await expectAgentError(storage.threads.transitionSandbox(recreate), "invalid_state")
+      })
+    })
+
+    test("resumes only confirmed workspace state with the pinned source", async () => {
+      await withStorage(async (storage, fixture) => {
+        await storage.threads.create(threadInput({ sandboxParams: {} }))
+        const input = runInput({ execution: execution("owner", new Date("2099-01-01")) })
+        await createTestAgentExecution(fixture, {
+          projectId,
+          runId: input.id,
+          executionId: input.executionId,
+          authority: "inherited",
+        })
+        await storage.runs.create(input)
+        await storage.runs.start(input)
+        const acquire = {
+          projectId,
+          id: "thr_1",
+          action: "acquire" as const,
+          runId: input.id,
+          executionToken: "owner",
+          name: "name",
+          sourceFingerprint: "b".repeat(64),
+        }
+        await storage.threads.transitionSandbox(acquire)
+        await storage.threads.transitionSandbox({
+          ...acquire,
+          action: "settle",
+          status: "ready",
+          initialized: true,
+        })
+        await expectAgentError(
+          storage.threads.transitionSandbox({
+            ...acquire,
+            sourceFingerprint: "c".repeat(64),
+          }),
+          "invalid_state"
+        )
+        expect(await storage.threads.transitionSandbox(acquire)).toMatchObject({
+          status: "busy",
+          initialized: true,
+        })
+      })
+    })
+
+    test("snapshots workspace bindings without accepting runtime state or credentials", async () => {
+      // Regression proof: remove snapshotAgentThreadSandboxParams from a provider's thread create.
+      await withStorage(async (storage) => {
+        const sandboxParams = { clientId: "acme", nested: { branch: "main" } }
+        const record = await storage.threads.create(threadInput({ sandboxParams }))
+        sandboxParams.nested.branch = "changed"
+        const read = await storage.threads.getById({ projectId, id: record.id })
+        expect(read?.sandboxParams).toEqual({ clientId: "acme", nested: { branch: "main" } })
+        const mutable = record.sandboxParams?.nested
+        if (mutable && typeof mutable === "object" && !Array.isArray(mutable))
+          mutable.branch = "tampered"
+        expect((await storage.threads.list({ projectId })).threads[0]?.sandboxParams).toEqual(
+          read?.sandboxParams
+        )
+        await expectAgentError(
+          storage.threads.create(
+            threadInput({
+              id: "unsafe",
+              // @ts-expect-error storage requires a JSON object
+              sandboxParams: [],
+            })
+          ),
+          "invalid_input"
+        )
+        await expectAgentError(
+          storage.threads.create(
+            threadInput({
+              id: "non-json",
+              // @ts-expect-error storage accepts normalized JSON, not typed Dates
+              sandboxParams: { at: new Date() },
+            })
+          ),
+          "invalid_input"
+        )
+      })
+    })
+
+    test("keeps delimiter-containing project and sandbox thread ids distinct", async () => {
+      // Regression proof: change the memory store key back to projectId + ":" + id.
+      await withStorage(async (storage) => {
+        await storage.threads.create(
+          threadInput({ projectId: "a:b", id: "c", sandboxParams: { repo: "one" } })
+        )
+        await storage.threads.create(
+          threadInput({ projectId: "a", id: "b:c", sandboxParams: { repo: "two" } })
+        )
+        expect(
+          (await storage.threads.getById({ projectId: "a:b", id: "c" }))?.sandboxParams?.repo
+        ).toBe("one")
+        expect(
+          (await storage.threads.getById({ projectId: "a", id: "b:c" }))?.sandboxParams?.repo
+        ).toBe("two")
+      })
+    })
     // ── threads ───────────────────────────────────────────────────────────────────────────────
 
     test("creates threads, isolates projects, and rejects duplicate ids", async () => {

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

@@ -236,8 +236,22 @@ export function runAiCostStorageContractSuite<TStorage extends AiCostStorage>(
             inputTokens: 15,
             outputTokens: 12,
             totalTokens: 27,
+            uncachedInputTokens: 12,
+            cacheReadInputTokens: 0,
             reportingStatus: "complete",
           },
+          usageCoverage: {
+            completeCallCount: 3,
+            fieldCallCounts: {
+              inputTokens: 3,
+              outputTokens: 3,
+              uncachedInputTokens: 1,
+              cacheReadInputTokens: 1,
+              cacheWriteInputTokens: 0,
+              textOutputTokens: 0,
+              reasoningOutputTokens: 0,
+            },
+          },
           costs: {
             amounts: [{ currency: "USD", amountNanos: "95000" }],
             ratedCallCount: 1,
@@ -290,6 +304,85 @@ export function runAiCostStorageContractSuite<TStorage extends AiCostStorage>(
       }
     })
 
+    test("retains known tokens and coverage across incomplete periods", async () => {
+      // Removal proof: require presentCallCount === modelCallCount in finishAggregateUsage.
+      // Both the in-memory and SQL-backed contract runs then lose the Sep 16/18 totals.
+      const storage = await fixture()
+      try {
+        // Currency fragments must merge coverage and usage exactly once per call.
+        for (const [index, currency] of ["USD", "EUR"].entries()) {
+          await storage.recordModelCallCost(
+            ratedCost(`partial_16_${index}`, {
+              components: [],
+              money: { currency, amountNanos: "1" },
+              priceSource: { ...priceSource(`partial_${index}`), sourceId: "provider-reported" },
+            })
+          )
+        }
+        const overview = await storage.queryProjectOverview({
+          projectId,
+          from: new Date("2026-09-16"),
+          to: new Date("2026-09-19"),
+          bucket: "day",
+        })
+        expect(
+          overview.series.map((period) => ({
+            calls: period.modelCallCount,
+            total: period.usage.totalTokens,
+            complete: period.usageCoverage.completeCallCount,
+          }))
+        ).toEqual([
+          { calls: 87, total: 4_013_782, complete: 84 },
+          { calls: 0, total: undefined, complete: 0 },
+          { calls: 29, total: 334_815, complete: 28 },
+        ])
+        for (const aggregate of [overview.totals, ...overview.models, ...overview.workflows]) {
+          expect(aggregate.usage).toEqual({
+            inputTokens: 4_348_597,
+            outputTokens: 0,
+            totalTokens: 4_348_597,
+            reportingStatus: "partial",
+          })
+          expect(aggregate.usageCoverage).toMatchObject({
+            completeCallCount: 112,
+            fieldCallCounts: { inputTokens: 112, outputTokens: 112, cacheReadInputTokens: 0 },
+          })
+        }
+        expect(overview.totals.costs.amounts).toEqual([
+          { currency: "EUR", amountNanos: "1" },
+          { currency: "USD", amountNanos: "1" },
+        ])
+        const edges = await storage.queryProjectOverview({
+          projectId,
+          from: new Date("2026-09-19"),
+          to: new Date("2026-09-22"),
+          bucket: "day",
+          providerId: "gateway",
+          modelId: "partial/model",
+        })
+        expect(edges.series[0]).toMatchObject({
+          usage: { inputTokens: 3, outputTokens: 4, totalTokens: 7, reportingStatus: "partial" },
+          usageCoverage: {
+            completeCallCount: 0,
+            fieldCallCounts: { inputTokens: 1, outputTokens: 1 },
+          },
+        })
+        expect(edges.series[1]).toMatchObject({
+          modelCallCount: 1,
+          usage: { reportingStatus: "unavailable" },
+          usageCoverage: { completeCallCount: 0 },
+        })
+        expect(edges.series[1]?.usage.totalTokens).toBeUndefined()
+        expect(edges.series[2]).toMatchObject({
+          usage: { inputTokens: 0, totalTokens: 0, reportingStatus: "partial" },
+          usageCoverage: { completeCallCount: 0 },
+        })
+        expect(edges.series[2]?.usage.outputTokens).toBeUndefined()
+      } finally {
+        await options.cleanup?.(storage)
+      }
+    })
+
     test("rejects missing usage and mismatched billed quantities", async () => {
       const storage = await fixture()
       try {
@@ -405,4 +498,45 @@ export async function seedAiCostStorageContractUsage(
     occurredAt: new Date("2026-08-03T12:00:00.000Z"),
     recordedAt: new Date("2026-08-03T12:00:00.100Z"),
   })
+
+  for (const [day, calls, complete, tokens] of [
+    [16, 87, 84, 4_013_782],
+    [18, 29, 28, 334_815],
+  ] as const) {
+    for (let index = 0; index < calls; index++) {
+      await usage.recordModelCall({
+        id: `partial_${day}_${index}`,
+        projectId,
+        executionId: otherExecutionId,
+        attempt: 1,
+        callId: `partial_${day}_${index}`,
+        responseId: `response_partial_${day}_${index}`,
+        requesterGroupIds: [],
+        providerId: "gateway",
+        requestedModelId: "partial/model",
+        usage: index < complete ? { inputTokens: index === 0 ? tokens : 0, outputTokens: 0 } : {},
+        occurredAt: new Date(`2026-09-${day}T12:00:00Z`),
+      })
+    }
+  }
+  for (const [index, day, counts] of [
+    [0, 19, { inputTokens: 3 }],
+    [1, 19, { outputTokens: 4 }],
+    [2, 20, {}],
+    [3, 21, { inputTokens: 0 }],
+  ] as const) {
+    await usage.recordModelCall({
+      id: `edge_${index}`,
+      projectId,
+      executionId: otherExecutionId,
+      attempt: 1,
+      callId: `edge_${index}`,
+      responseId: `response_edge_${index}`,
+      requesterGroupIds: [],
+      providerId: "gateway",
+      requestedModelId: "partial/model",
+      usage: counts,
+      occurredAt: new Date(`2026-09-${day}T12:00:00Z`),
+    })
+  }
 }