@sixb/core 0.1.16 → 0.1.17

package/src/testing/object-read-scope-contract.ts

@@ -579,6 +579,7 @@ export function runObjectReadScopeContractSuite<TStorage extends Storage>(
             ],
           })
         ).toEqual({
+          total: 1,
           facets: [
             { propertyId: "category", buckets: [{ value: "visible", count: 1 }] },
             { propertyId: "secret", buckets: [] },

package/src/testing/ontology-contract-fixture.ts

@@ -3,7 +3,6 @@ import { createEventId } from "../materialization/identity"
 import type {
   MaterializationPlanHeader,
   MaterializationWorkRecord,
-  OntologyMaterializationEvent,
   OntologyStorage,
 } from "../storage/ontology"
 import type { Storage } from "../storage/types"
@@ -12,24 +11,6 @@ export interface OntologyContractStorage extends Storage {
   readonly ontology: OntologyStorage
 }
 
-const emptyChunk = {
-  overrides: {
-    objects: { upserts: [], deletes: [] },
-    links: {
-      edges: { upserts: [], deletes: [] },
-      slots: { upserts: [], deletes: [] },
-    },
-  },
-  effective: {
-    objectUpserts: [],
-    objectDeletes: [],
-    linkUpserts: [],
-    linkDeletes: [],
-  },
-  timeseries: { pointUpserts: [] },
-  outbox: [],
-} as const
-
 /** The request executor `ensureContractExecution` records for a contract commit. */
 export function contractExecutor(id: string) {
   return { type: "request" as const, requestId: `contract-request:${id}` }
@@ -44,7 +25,6 @@ export function contractEditHeader(id: string): MaterializationPlanHeader {
       requestHash: `hash:${id}`,
       executionId: `contract-execution:${id}`,
       origin: { kind: "runtime", requestId: id },
-      executor: contractExecutor(id),
       ontologyRevision: "ontology-contract-revision",
       intent: { kind: "edit", mode: "atomic", operationCount: 0 },
       committedAt: CONTRACT_COMMITTED_AT,
@@ -78,6 +58,7 @@ export async function commitEmptyEdit(storage: OntologyContractStorage, id: stri
     const header = contractEditHeader(id)
     await ensureContractExecution(tx, header)
     const session = await tx.ontology.materializations.begin(header)
+    await tx.ontology.materializations.apply({ session })
     await tx.ontology.materializations.finalize({
       session,
       finalization: { sourceActivations: [], result: contractEditResult(id) },
@@ -101,11 +82,7 @@ export async function commitExactObject(
     readonly requestedBy?: AuthorizablePrincipal
   } = {}
 ): Promise<{ readonly eventId: string }> {
-  const defaultHeader = contractEditHeader(id)
-  const header: MaterializationPlanHeader =
-    options.requestedBy === undefined
-      ? defaultHeader
-      : { ...defaultHeader, commit: { ...defaultHeader.commit, requestedBy: options.requestedBy } }
+  const header = contractEditHeader(id)
   const ref = { objectTypeId: "ContractDevice", primaryId: options.primaryId ?? id }
   const row = {
     ref,
@@ -117,30 +94,13 @@ export async function commitExactObject(
   }
   const exactWrite = { row, expected: { ref, exists: false as const } }
   const draft = {
-    schemaVersion: 1 as const,
-    projectId: header.commit.projectId,
-    occurredAt: header.commit.committedAt,
-    correlationId: `contract-correlation:${id}`,
-    origin: header.commit.origin,
-    ...(header.commit.requestedBy === undefined ? {} : { requestedBy: header.commit.requestedBy }),
-    executor: header.commit.executor,
-    commitId: id,
     type: "object.created" as const,
-    topic: "objects" as const,
-    partitionKey: `${ref.objectTypeId}:${ref.primaryId}`,
     payload: {
       objectTypeId: ref.objectTypeId,
       primaryId: ref.primaryId,
       properties: row.properties,
-      propertyChanges: {},
     },
   }
-  const eventId = createEventId(header.commit.projectId, id, 0)
-  const envelope: OntologyMaterializationEvent = {
-    ...draft,
-    id: eventId,
-    commitOrdinal: 0,
-  }
   const work: readonly MaterializationWorkRecord[] = [
     {
       kind: "plan",
@@ -159,52 +119,12 @@ export async function commitExactObject(
   ]
 
   await storage.transaction(async (tx) => {
-    await ensureContractExecution(tx, header)
+    await ensureContractExecution(tx, header, options.requestedBy)
     const materializations = tx.ontology.materializations
     const session = await materializations.begin(header)
     await materializations.stageWork({ session, records: work })
 
-    const applyRecords = []
-    for await (const page of materializations.streamWork({
-      session,
-      order: "apply",
-      pageRows: 1,
-    })) {
-      applyRecords.push(...page.records)
-    }
-    const objectUpserts = applyRecords.flatMap((record) =>
-      record.kind === "plan" && record.item.kind === "object-upsert" ? [record.item.value] : []
-    )
-    await materializations.applyChunk({
-      session,
-      chunk: {
-        ...emptyChunk,
-        effective: { ...emptyChunk.effective, objectUpserts },
-      },
-    })
-
-    const eventRecords = []
-    for await (const page of materializations.streamWork({
-      session,
-      order: "event",
-      pageRows: 1,
-    })) {
-      eventRecords.push(...page.records)
-    }
-    await materializations.applyChunk({
-      session,
-      chunk: {
-        ...emptyChunk,
-        outbox: eventRecords.map((record) => {
-          if (record.kind !== "event") throw new Error("Expected event work record.")
-          return {
-            envelope,
-            availableAt: header.commit.committedAt,
-            createdAt: header.commit.committedAt,
-          }
-        }),
-      },
-    })
+    await materializations.apply({ session })
     if (!options.omitFinalize) {
       await materializations.finalize({
         session,
@@ -214,12 +134,17 @@ export async function commitExactObject(
     if (options.throwAfterFinalize) throw new Error("contract rollback")
   })
 
-  return { eventId }
+  return { eventId: createEventId(header.commit.projectId, id, 0) }
 }
 
+/**
+ * Records the execution a contract commit runs under: a request, made on behalf of `requestedBy`
+ * when given. Its events read who asked and what wrote from this record.
+ */
 export async function ensureContractExecution(
   storage: Pick<Storage, "executions">,
-  header: MaterializationPlanHeader
+  header: MaterializationPlanHeader,
+  requestedBy?: AuthorizablePrincipal
 ): Promise<void> {
   if (
     await storage.executions.getById({
@@ -229,7 +154,6 @@ export async function ensureContractExecution(
   ) {
     return
   }
-  const { requestedBy } = header.commit
   await storage.executions.create({
     id: header.commit.executionId,
     projectId: header.commit.projectId,

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

@@ -149,7 +149,9 @@ export function runOntologyStorageContractSuite<TStorage extends OntologyStorage
       })
     })
 
-    test("round-trips commit and event attribution exactly", async () => {
+    // Removal proof: rebuild an event's attribution from anything but its commit's execution; the
+    // requester and correlation id below no longer match.
+    test("attributes events to their commit's execution, which the commit does not copy", async () => {
       await withStorage(async (storage) => {
         // The requester is a real principal: SQL executions reference it by foreign key.
         if (!storage.auth) throw new Error("The attribution contract requires auth storage.")
@@ -166,15 +168,10 @@ export function runOntologyStorageContractSuite<TStorage extends OntologyStorage
           projectId: "contract-project",
           id: "attributed",
         })
-        expect(attributed?.requestedBy).toEqual(requestedBy)
-        expect(attributed?.executor).toEqual(contractExecutor("attributed"))
-        expect(attributed).not.toHaveProperty("actor")
-        const unattributed = await storage.ontology.commits.getById({
-          projectId: "contract-project",
-          id: "unattributed",
-        })
-        expect(unattributed).not.toHaveProperty("requestedBy")
-        expect(unattributed?.executor).toEqual(contractExecutor("unattributed"))
+        expect(attributed?.executionId).toBe("contract-execution:attributed")
+        for (const copy of ["requestedBy", "executor", "correlationId", "actor"]) {
+          expect(attributed).not.toHaveProperty(copy)
+        }
 
         const claimed = await storage.ontology.outbox.claim({
           projectId: "contract-project",
@@ -185,10 +182,12 @@ export function runOntologyStorageContractSuite<TStorage extends OntologyStorage
         })
         const envelopes = new Map(claimed.map((record) => [record.envelope.commitId, record]))
         expect(envelopes.get("attributed")?.envelope).toMatchObject({
+          correlationId: "contract-correlation:attributed",
           requestedBy,
           executor: contractExecutor("attributed"),
         })
         const unattributedEnvelope = envelopes.get("unattributed")?.envelope
+        expect(unattributedEnvelope?.correlationId).toBe("contract-correlation:unattributed")
         expect(unattributedEnvelope?.executor).toEqual(contractExecutor("unattributed"))
         expect(unattributedEnvelope).not.toHaveProperty("requestedBy")
       })
@@ -200,6 +199,7 @@ export function runOntologyStorageContractSuite<TStorage extends OntologyStorage
         await expect(
           storage.transaction(async (tx) => {
             const session = await tx.ontology.materializations.begin(header)
+            await tx.ontology.materializations.apply({ session })
             await tx.ontology.materializations.finalize({
               session,
               finalization: {
@@ -460,9 +460,6 @@ export function runOntologyStorageContractSuite<TStorage extends OntologyStorage
             adoptedAt: "2026-01-01T00:02:10.000Z",
           })
         ).toBeNull()
-        expect(
-          await storage.ontology.sources.summarizeTerminal({ projectId: "contract-project" })
-        ).toEqual({ count: 1, oldestTerminalAt: "2026-01-01T00:02:00.000Z" })
 
         // Superseded retention does not hold an abandoned candidate back.
         expect(
@@ -482,8 +479,8 @@ export function runOntologyStorageContractSuite<TStorage extends OntologyStorage
           await storage.ontology.sources.purgeAbandoned({ projectId: "contract-project", limit: 1 })
         ).toEqual({ rowsDeleted: 0, materializationsDeleted: 1 })
         expect(
-          await storage.ontology.sources.summarizeTerminal({ projectId: "contract-project" })
-        ).toEqual({ count: 0, oldestTerminalAt: null })
+          await storage.ontology.sources.purgeAbandoned({ projectId: "contract-project", limit: 1 })
+        ).toEqual({ rowsDeleted: 0, materializationsDeleted: 0 })
       })
     })
 
@@ -603,6 +600,7 @@ export function runOntologyStorageContractSuite<TStorage extends OntologyStorage
             origin: { kind: "projection", projectionRunId: first.execution.projectionRunId },
           })
         ).toMatchObject({ id: "commit-source-one" })
+        // An active candidate has no plan to open again.
         await expect(
           activateEmptyCandidate(
             storage,
@@ -611,6 +609,39 @@ export function runOntologyStorageContractSuite<TStorage extends OntologyStorage
             "duplicate-projection-origin",
             "2026-01-03T01:00:00.000Z"
           )
+        ).rejects.toMatchObject({ kind: "source-materialization" })
+        // Another candidate of the same run reaches its commit, which repeats the run's origin.
+        const again = { ...first, materializationId: "candidate-one-again" }
+        await storage.ontology.sources.beginMaterialization({
+          projectId: "contract-project",
+          source: again.source,
+          materializationId: again.materializationId,
+          execution: again.execution,
+          projectionKind: "object",
+          protocol: "replacement",
+          datasetVersion: again.identity.datasetVersion,
+          projectionRevision: again.identity.projectionRevision,
+          ownershipHash: again.identity.ownershipHash,
+          ontologyRevision: again.identity.ontologyRevision,
+          createdAt: "2026-01-03T00:30:00.000Z",
+        })
+        await storage.ontology.sources.markReady({
+          projectId: "contract-project",
+          source: again.source,
+          materializationId: again.materializationId,
+          execution: again.execution,
+          rootCount: 0,
+          assertionCount: 0,
+          readyAt: "2026-01-03T00:31:00.000Z",
+        })
+        await expect(
+          activateEmptyCandidate(
+            storage,
+            again,
+            activeOne,
+            "duplicate-projection-origin",
+            "2026-01-03T01:00:00.000Z"
+          )
         ).rejects.toMatchObject({ kind: "run-correlation" })
 
         const left = await createReadyEmptyCandidate(storage, "run-left", "candidate-left", "02")
@@ -928,6 +959,7 @@ export function runOntologyStorageContractSuite<TStorage extends OntologyStorage
             }
             const header = telemetryHeader(identity, run.run.id, run.run.executionId)
             const session = await tx.ontology.materializations.begin(header)
+            await tx.ontology.materializations.apply({ session })
             await tx.ontology.materializations.finalize({
               session,
               finalization: {
@@ -1055,12 +1087,6 @@ async function activateEmptyCandidate(
         datasetId: candidate.identity.datasetVersion.datasetId,
         datasetVersionId: candidate.identity.datasetVersion.versionId,
       },
-      executor: {
-        type: "primitive",
-        kind: "projection",
-        id: candidate.source.projectionId,
-        runId: candidate.execution.projectionRunId,
-      },
       ontologyRevision: candidate.identity.ontologyRevision,
       projectionRevision: candidate.identity.projectionRevision,
       ownershipHash: candidate.identity.ownershipHash,
@@ -1099,6 +1125,22 @@ async function activateEmptyCandidate(
       counts: emptyProjectionCounts,
     },
   }
+  const plan = {
+    projectId: header.commit.projectId,
+    source: candidate.source,
+    materializationId: candidate.materializationId,
+    execution: candidate.execution,
+  }
+  await storage.ontology.replacementPlans.open({ ...plan, commit: header.commit })
+  for (const entityKind of ["object", "link"] as const) {
+    for await (const _page of storage.ontology.replacementPlans.streamState({
+      ...plan,
+      entityKind,
+      pageRows: 1,
+    })) {
+      // Empty output intentionally has no identities to plan.
+    }
+  }
   await storage.transaction(async (tx) => {
     if (!tx.projectionRuns) {
       throw new Error("Contract transaction omitted required storage facades.")
@@ -1109,18 +1151,13 @@ async function activateEmptyCandidate(
       identity: candidate.identity,
       executionToken: candidate.execution.executionToken,
     })
-    const session = await tx.ontology.materializations.begin(header)
-    for (const entityKind of ["object", "link"] as const) {
-      for await (const _page of tx.ontology.materializations.streamSourceReplacementState({
-        session,
-        source: candidate.source,
-        candidateMaterializationId: candidate.materializationId,
-        entityKind,
-        pageRows: 1,
-      })) {
-        // Empty output intentionally has no classifications or exact writes.
-      }
-    }
+    const status = await tx.ontology.replacementPlans.refresh(plan)
+    if (!status.fresh) throw new Error("An empty plan has nothing to plan again.")
+    const session = await tx.ontology.materializations.begin({
+      ...header,
+      plan: { source: candidate.source, materializationId: candidate.materializationId },
+    })
+    await tx.ontology.materializations.apply({ session })
     await tx.ontology.materializations.finalize({ session, finalization })
   })
 }
@@ -1149,12 +1186,6 @@ function telemetryHeader(
           batchOrdinal: 0,
         },
       },
-      executor: {
-        type: "primitive",
-        kind: "projection",
-        id: identity.projectionId,
-        runId: projectionRunId,
-      },
       ontologyRevision: identity.ontologyRevision,
       projectionRevision: identity.projectionRevision,
       ownershipHash: identity.ownershipHash,

package/src/testing/projection-run-storage-contract.ts

@@ -155,6 +155,20 @@ export function runProjectionRunStorageContractSuite<TStorage extends Projection
           status: "failed",
           error: { code: "queue.enqueue_failed", message: "queue unavailable" },
         })
+        const failedWith = (errorCodes: ProjectionRunFailureCode[]) =>
+          context.projectionRuns.list({
+            projectId: input.projectId,
+            statuses: ["failed"],
+            errorCodes,
+          })
+        await expect(failedWith(["queue.enqueue_failed"])).resolves.toMatchObject({
+          runs: [{ id: input.id }],
+          total: 1,
+        })
+        await expect(failedWith(["projection.execution_failed"])).resolves.toMatchObject({
+          total: 0,
+        })
+        await expect(failedWith([])).resolves.toMatchObject({ total: 0 })
 
         const requeued = await context.projectionRuns.queue(admission)
         expect(requeued).toMatchObject({

package/src/testing/queues-contract.ts

@@ -278,6 +278,65 @@ export function runQueueContractSuite(label: string, options: QueueContractSuite
         })
       })
 
+      test("with a signal, waits for work and wakes when a job is enqueued", async () => {
+        await withQueues(async (queues) => {
+          let settled = false
+          const claim = queues.syncRuns
+            .claim({
+              projectId: "project-a",
+              workerId: "worker-1",
+              signal: AbortSignal.timeout(4_000),
+            })
+            .finally(() => {
+              settled = true
+            })
+          await Bun.sleep(50)
+          expect(settled).toBe(false)
+
+          await queues.syncRuns.enqueue({
+            projectId: "project-a",
+            jobs: [{ type: "sync.run.requested", payload: { runId: "s-1" } }],
+          })
+
+          expect((await claim).map((claimed) => claimed.job.payload.runId)).toEqual(["s-1"])
+        })
+      })
+
+      test("with a signal, wakes when a delayed job comes due", async () => {
+        await withQueues(async (queues) => {
+          const availableAt = new Date(Date.now() + shortLeaseMs).toISOString()
+          await queues.syncRuns.enqueue({
+            projectId: "project-a",
+            jobs: [{ type: "sync.run.requested", payload: { runId: "s-1" }, availableAt }],
+          })
+
+          const claimed = await queues.syncRuns.claim({
+            projectId: "project-a",
+            workerId: "worker-1",
+            signal: AbortSignal.timeout(4_000),
+          })
+
+          expect(claimed).toHaveLength(1)
+          expect(Date.now()).toBeGreaterThanOrEqual(Date.parse(availableAt))
+        })
+      })
+
+      // A provider may finish a blocking read before it sees the abort; BullMQ's lasts up to 5s.
+      test("with a signal, returns empty once the signal aborts", async () => {
+        await withQueues(async (queues) => {
+          const waiting = new AbortController()
+          const claim = queues.syncRuns.claim({
+            projectId: "project-a",
+            workerId: "worker-1",
+            signal: waiting.signal,
+          })
+          await Bun.sleep(20)
+          waiting.abort()
+
+          expect(await claim).toEqual([])
+        })
+      }, 10_000)
+
       test("isolates jobs across distinct projectIds", async () => {
         await withQueues(async (queues) => {
           await queues.syncRuns.enqueue({

package/src/workers/queue-worker.ts

@@ -26,7 +26,6 @@ export interface QueueWorkerConfig<
   readonly workerId: string
   readonly leaseMs?: number
   readonly claimLimit?: number
-  readonly idlePollMs?: number
 }
 
 /**
@@ -48,7 +47,7 @@ export type QueueWorkerFailureDecision<TFailureCode extends SixbErrorCode = neve
 
 const DEFAULT_LEASE_MS = 15 * 60_000
 const DEFAULT_CLAIM_LIMIT = 1
-const DEFAULT_IDLE_POLL_MS = 1_000
+const CLAIM_FAILURE_DELAY_MS = 1_000
 const MAX_CONSECUTIVE_CLAIM_FAILURES = 5
 
 export abstract class QueueWorker<
@@ -56,6 +55,8 @@ export abstract class QueueWorker<
   TFailureCodes extends QueueWorkerFailureCodes,
 > extends Worker {
   protected readonly config: Required<QueueWorkerConfig<TJob, TFailureCodes>>
+  /** Pause after a failed claim. Overridable so tests do not wait out real backoffs. */
+  protected readonly claimFailureDelayMs: number = CLAIM_FAILURE_DELAY_MS
   private consecutiveClaimFailures = 0
 
   constructor(config: QueueWorkerConfig<TJob, TFailureCodes>) {
@@ -67,7 +68,6 @@ export abstract class QueueWorker<
       workerId: config.workerId,
       leaseMs: config.leaseMs ?? DEFAULT_LEASE_MS,
       claimLimit: normalizeClaimLimit(config.claimLimit),
-      idlePollMs: config.idlePollMs ?? DEFAULT_IDLE_POLL_MS,
     }
   }
 
@@ -79,6 +79,9 @@ export abstract class QueueWorker<
   protected async run(signal: AbortSignal): Promise<void> {
     const inFlight = new Set<Promise<void>>()
     let runError: unknown = null
+    // A claim waits for work, so a failed job must also end the wait it would otherwise sit in.
+    const failed = new AbortController()
+    const claimSignal = AbortSignal.any([signal, failed.signal])
 
     try {
       while (!signal.aborted && !runError) {
@@ -90,11 +93,12 @@ export abstract class QueueWorker<
         }
 
         const capacity = this.config.claimLimit - inFlight.size
-        const claimed = await this.claimOrIdle(signal, capacity)
+        const claimed = await this.claim(claimSignal, capacity)
         for (const claimedJob of claimed) {
           const promise = this.handle(claimedJob, signal)
             .catch((error) => {
               runError ??= error
+              failed.abort()
             })
             .finally(() => {
               inFlight.delete(promise)
@@ -137,23 +141,22 @@ export abstract class QueueWorker<
     return { kind: "retry" }
   }
 
-  private async claimOrIdle(
+  private async claim(
     signal: AbortSignal,
     limit: number
   ): Promise<readonly ClaimedQueueJob<TJob>[]> {
-    const { projectId, queue, workerId, leaseMs, idlePollMs } = this.config
+    const { projectId, queue, workerId, leaseMs } = this.config
 
     try {
-      const claimed = await queue.claim({
-        projectId,
-        workerId,
-        limit,
-        leaseMs,
-      })
-      this.consecutiveClaimFailures = 0
-      if (claimed.length === 0) {
-        await sleep(idlePollMs, signal).catch(() => {})
+      // The provider waits until it has work or `signal` aborts, so there is no idle loop here.
+      const claimed = await queue.claim({ projectId, workerId, limit, leaseMs, signal })
+      if (claimed.length === 0 && !signal.aborted) {
+        // A provider that ignores the signal would otherwise spin this loop on a whole core.
+        throw new Error(
+          "[SixbQueueWorker] Queue claim returned no jobs before its signal aborted; the queue provider contract says claim must wait for work until its signal aborts."
+        )
       }
+      this.consecutiveClaimFailures = 0
       return claimed
     } catch (error) {
       if (signal.aborted) return []
@@ -165,7 +168,7 @@ export abstract class QueueWorker<
           { cause: error }
         )
       }
-      await sleep(idlePollMs, signal).catch(() => {})
+      await sleep(this.claimFailureDelayMs, signal).catch(() => {})
       return []
     }
   }