@sixb/core 0.1.12 → 0.1.14

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

@@ -0,0 +1,335 @@
+import { describe, expect, test } from "bun:test"
+import type { Principal } from "../auth"
+import type { BlobUploadSession, FileRef, SignedBlobUploadPart } from "../blob-storage"
+import {
+  type CreateFileUploadSessionInput,
+  DEFAULT_FILE_UPLOAD_TERMINAL_SESSION_TTL_MS,
+  type FileUploadSessionStore,
+} from "../storage/file-upload-sessions"
+
+export interface FileUploadSessionStorageContractSuiteOptions<
+  TStorage extends FileUploadSessionStore = FileUploadSessionStore,
+> {
+  readonly createStorage: () => TStorage | Promise<TStorage>
+  readonly cleanup?: (storage: TStorage) => void | Promise<void>
+}
+
+const HOUR_MS = 60 * 60 * 1000
+const projectId = "file-upload-contract"
+const principal: Principal = { type: "user", id: "usr_contract" }
+const fileRef: FileRef = {
+  blobId: `blob_${"a".repeat(64)}`,
+  digest: `sha256:${"a".repeat(64)}`,
+  sizeBytes: 3,
+  fileName: "report.pdf",
+}
+
+/**
+ * Provider-neutral lifecycle, retention, and abandoned-upload contract for file upload
+ * sessions. Stores read their own clock, so fixtures place `expiresAt` relative to the
+ * real time instead of controlling it.
+ */
+export function runFileUploadSessionStorageContractSuite<TStorage extends FileUploadSessionStore>(
+  label: string,
+  options: FileUploadSessionStorageContractSuiteOptions<TStorage>
+): void {
+  const withStorage = async (run: (storage: TStorage) => Promise<void>): Promise<void> => {
+    const storage = await options.createStorage()
+    try {
+      await run(storage)
+    } finally {
+      await options.cleanup?.(storage)
+    }
+  }
+
+  describe(label, () => {
+    test("round-trips every field, including provider fields it does not know", async () => {
+      await withStorage(async (storage) => {
+        // Provider-specific session fields must survive the JSON round-trip.
+        const providerUpload = { ...multipart("upload_roundtrip"), partReceipt: "etag" as const }
+        const input = sessionInput("upload_roundtrip", {
+          fileName: "report.pdf",
+          mediaType: "application/pdf",
+          logicalPath: "reports/q3.pdf",
+          expectedSizeBytes: 3,
+          expectedDigest: fileRef.digest,
+          providerUpload,
+        })
+        const created = await storage.create(input)
+
+        expect(created).toMatchObject({ status: "pending", principal })
+        const read = await storage.getForPrincipal("upload_roundtrip", principal)
+        expect(read).toEqual(created)
+        expect(read.providerUpload?.expiresAt).toBeInstanceOf(Date)
+        expect(read.providerUpload).toMatchObject({ partReceipt: "etag" })
+      })
+    })
+
+    test("hides a session from other principals and unknown ids", async () => {
+      await withStorage(async (storage) => {
+        await storage.create(sessionInput("upload_private"))
+
+        await expect(
+          storage.getForPrincipal("upload_private", { type: "user", id: "usr_other" })
+        ).rejects.toMatchObject({ reason: "not_found" })
+        await expect(storage.getForPrincipal("upload_missing", principal)).rejects.toMatchObject({
+          reason: "not_found",
+        })
+      })
+    })
+
+    test("rejects a duplicate id", async () => {
+      await withStorage(async (storage) => {
+        await storage.create(sessionInput("upload_duplicate"))
+        await expect(storage.create(sessionInput("upload_duplicate"))).rejects.toThrow(
+          "already exists"
+        )
+      })
+    })
+
+    test("keeps signed parts unique and ordered by part number", async () => {
+      await withStorage(async (storage) => {
+        await storage.create(
+          sessionInput("upload_parts", { providerUpload: multipart("upload_parts") })
+        )
+        // Insertion order differs from sorted order at every step, so dropping the sort fails.
+        await storage.addSignedPart("upload_parts", signedPart(3))
+        await storage.addSignedPart("upload_parts", signedPart(1))
+        await storage.addSignedPart("upload_parts", signedPart(2))
+        const updated = await storage.addSignedPart("upload_parts", signedPart(2, "replaced"))
+
+        expect(updated.signedParts.map((part) => [part.partNumber, part.url])).toEqual([
+          [1, "https://blob.test/part-1"],
+          [2, "https://blob.test/part-2-replaced"],
+          [3, "https://blob.test/part-3"],
+        ])
+        const read = await storage.getForPrincipal("upload_parts", principal)
+        expect(read.signedParts).toEqual(updated.signedParts)
+        expect(read.signedParts[0]?.expiresAt).toBeInstanceOf(Date)
+      })
+    })
+
+    test("does not lose a part signed concurrently with another", async () => {
+      await withStorage(async (storage) => {
+        await storage.create(
+          sessionInput("upload_race", { providerUpload: multipart("upload_race") })
+        )
+        await Promise.all(
+          [1, 2, 3, 4, 5].map((n) => storage.addSignedPart("upload_race", signedPart(n)))
+        )
+
+        const read = await storage.getForPrincipal("upload_race", principal)
+        expect(read.signedParts.map((part) => part.partNumber)).toEqual([1, 2, 3, 4, 5])
+      })
+    })
+
+    test("moves through markUploaded to one terminal state", async () => {
+      await withStorage(async (storage) => {
+        await storage.create(sessionInput("upload_done"))
+        const uploaded = await storage.markUploaded("upload_done", fileRef)
+        expect(uploaded).toMatchObject({ status: "pending", fileRef })
+
+        const completed = await storage.complete("upload_done", fileRef)
+        expect(completed.status).toBe("completed")
+        expect(completed.completedAt).toBeInstanceOf(Date)
+        await expect(storage.complete("upload_done", fileRef)).rejects.toMatchObject({
+          reason: "already_completed",
+        })
+        await expect(storage.abort("upload_done")).rejects.toMatchObject({
+          reason: "already_completed",
+        })
+
+        await storage.create(sessionInput("upload_cancelled"))
+        expect((await storage.abort("upload_cancelled")).status).toBe("aborted")
+        await expect(storage.abort("upload_cancelled")).rejects.toMatchObject({
+          reason: "already_aborted",
+        })
+      })
+    })
+
+    test("checks expiry at the gate only, so a request that passed it can finish", async () => {
+      await withStorage(async (storage) => {
+        // Provider uploads keep both rows unreapable while pending.
+        for (const id of ["upload_late", "upload_abort_late"]) {
+          await storage.create(
+            sessionInput(id, { expiresAt: ago(HOUR_MS), providerUpload: multipart(id) })
+          )
+        }
+
+        await expect(storage.getForPrincipal("upload_late", principal)).rejects.toMatchObject({
+          reason: "expired",
+        })
+        // Transitions run after slow blob I/O that began before `expiresAt`.
+        await storage.addSignedPart("upload_late", signedPart(1))
+        await storage.markUploaded("upload_late", fileRef)
+        expect((await storage.complete("upload_late", fileRef)).status).toBe("completed")
+        expect((await storage.abort("upload_abort_late")).status).toBe("aborted")
+      })
+    })
+
+    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(
+          sessionInput("upload_abandoned", {
+            expiresAt: ago(HOUR_MS),
+            providerUpload: multipart("upload_abandoned"),
+          })
+        )
+
+        // Reading an expired session must not delete it: nothing would abort its provider upload.
+        await expect(storage.getForPrincipal("upload_abandoned", principal)).rejects.toMatchObject({
+          reason: "expired",
+        })
+        expect(await storage.cleanupExpired(later(HOUR_MS))).toBe(0)
+        expect(
+          (await storage.listAbandoned({ projectId, now: new Date(), limit: 10 })).map(
+            (session) => session.id
+          )
+        ).toEqual(["upload_abandoned"])
+      })
+    })
+
+    test("lists only 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") })
+        )
+        await storage.create(
+          sessionInput("upload_older", {
+            expiresAt: ago(2 * HOUR_MS),
+            providerUpload: multipart("o"),
+          })
+        )
+        await storage.create(sessionInput("upload_live", { providerUpload: multipart("live") }))
+        await storage.create(sessionInput("upload_server", { expiresAt: ago(HOUR_MS) }))
+        await storage.create(
+          sessionInput("upload_aborted", {
+            expiresAt: ago(HOUR_MS),
+            providerUpload: multipart("a"),
+          })
+        )
+        await storage.abort("upload_aborted")
+
+        const ids = async (limit: number) =>
+          (await storage.listAbandoned({ projectId, now: new Date(), limit })).map(
+            (session) => session.id
+          )
+        expect(await ids(10)).toEqual(["upload_older", "upload_newer"])
+        expect(await ids(1)).toEqual(["upload_older"])
+        const [oldest] = await storage.listAbandoned({ projectId, now: new Date(), limit: 1 })
+        expect(oldest?.providerUpload?.expiresAt).toBeInstanceOf(Date)
+        await expect(
+          storage.listAbandoned({ projectId, now: new Date(), limit: 0 })
+        ).rejects.toThrow("positive integer")
+      })
+    })
+
+    test("reaps expired sessions without a provider upload and terminal ones after their TTL", async () => {
+      await withStorage(async (storage) => {
+        await storage.create(sessionInput("upload_live"))
+        await storage.create(sessionInput("upload_finished"))
+        await storage.complete("upload_finished", fileRef)
+        // Created last: a store may reap opportunistically on `create`.
+        await storage.create(sessionInput("upload_expired", { expiresAt: ago(HOUR_MS) }))
+
+        expect(await storage.cleanupExpired(new Date())).toBe(1)
+        await expect(storage.getForPrincipal("upload_expired", principal)).rejects.toMatchObject({
+          reason: "not_found",
+        })
+        // A completed session outlives its expiry so a retried `complete` stays idempotent.
+        expect((await storage.getForPrincipal("upload_finished", principal)).status).toBe(
+          "completed"
+        )
+
+        expect(
+          await storage.cleanupExpired(later(DEFAULT_FILE_UPLOAD_TERMINAL_SESSION_TTL_MS + 60_000))
+        ).toBe(1)
+        await expect(storage.getForPrincipal("upload_finished", principal)).rejects.toMatchObject({
+          reason: "not_found",
+        })
+        expect((await storage.getForPrincipal("upload_live", principal)).status).toBe("pending")
+      })
+    })
+
+    test("reaps an abandoned session once it has been aborted", async () => {
+      await withStorage(async (storage) => {
+        await storage.create(
+          sessionInput("upload_swept", { expiresAt: ago(HOUR_MS), providerUpload: multipart("s") })
+        )
+        await storage.abort("upload_swept")
+
+        expect(await storage.listAbandoned({ projectId, now: new Date(), limit: 10 })).toEqual([])
+        expect(await storage.cleanupExpired(new Date())).toBe(0)
+        expect(
+          await storage.cleanupExpired(later(DEFAULT_FILE_UPLOAD_TERMINAL_SESSION_TTL_MS + 60_000))
+        ).toBe(1)
+      })
+    })
+  })
+}
+
+function sessionInput(
+  id: string,
+  overrides: Partial<CreateFileUploadSessionInput> = {}
+): CreateFileUploadSessionInput {
+  return {
+    id,
+    projectId,
+    principal,
+    strategy: overrides.providerUpload?.strategy ?? "server",
+    expiresAt: later(HOUR_MS),
+    ...overrides,
+  }
+}
+
+function multipart(uploadId: string): BlobUploadSession {
+  return {
+    strategy: "multipart",
+    uploadId,
+    partSizeBytes: 5 * 1024 * 1024,
+    expiresAt: later(HOUR_MS),
+    stagingKey: `staging/${uploadId}`,
+    providerUploadId: `provider-${uploadId}`,
+  }
+}
+
+function signedPart(partNumber: number, suffix?: string): SignedBlobUploadPart {
+  return {
+    partNumber,
+    method: "PUT",
+    url: `https://blob.test/part-${partNumber}${suffix ? `-${suffix}` : ""}`,
+    headers: {},
+    expiresAt: later(HOUR_MS),
+  }
+}
+
+function ago(ms: number): Date {
+  return new Date(Date.now() - ms)
+}
+
+function later(ms: number): Date {
+  return new Date(Date.now() + ms)
+}

package/src/testing/index.ts

@@ -59,6 +59,10 @@ export {
   type ExecutionStorageContractSuiteOptions,
   runExecutionStorageContractSuite,
 } from "./execution-storage-contract"
+export {
+  type FileUploadSessionStorageContractSuiteOptions,
+  runFileUploadSessionStorageContractSuite,
+} from "./file-upload-session-storage-contract"
 export { runLakeChangesContractSuite } from "./lake-changes-contract"
 export {
   type LakeMergeStorageContractSuiteOptions,
@@ -151,3 +155,7 @@ export {
   createTestAutomaticWorkflowExecution,
   createTestWorkflowExecution,
 } from "./workflow-execution"
+export {
+  runWorkflowInterventionStorageContractSuite,
+  type WorkflowInterventionStorageContractSuiteOptions,
+} from "./workflow-intervention-storage-contract"

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

@@ -13,7 +13,11 @@ import {
 import type { TrustedPrimitiveRef } from "../execution"
 import { restoreTrustedPrimitiveExecutionScope } from "../execution/durable"
 import { createTestingScope } from "../execution/scopes"
-import type { OntologyMaterializer } from "../materializer"
+import type {
+  ExpectedLinkRevision,
+  ExpectedObjectRevision,
+  OntologyMaterializer,
+} from "../materializer"
 import {
   createLinkScopeFingerprint,
   createOntologyMaterializer,
@@ -747,6 +751,84 @@ export function runMaterializerStorageContractSuite<TStorage extends Storage>(
     }
   })
 
+  test(`${name} rejects stale object and link expectations as expectation conflicts`, async () => {
+    // Action runs report exactly this conflict kind as `action.read_conflict`. Throw a stale
+    // expectation as another kind from any provider and this fails for that provider.
+    const createdStorage = await provider.createStorage()
+    const storage = requireContractStorage(createdStorage)
+    const runtimeMaterializer = createOntologyMaterializer({
+      projectId: "materializer-storage-contract",
+      ontology,
+      projections,
+      storage,
+      dependencies: { clock: () => new Date("2026-02-01T12:00:00.000Z") },
+    }).withScope(runtimeScope())
+    const device = { objectTypeId: Device.id, primaryId: "device" }
+    const peerLink = {
+      source: device,
+      linkId: "peers",
+      target: { objectTypeId: Device.id, primaryId: "peer" },
+    }
+    const commitExpecting = (
+      requestId: string,
+      expected: {
+        readonly expectedObjects: readonly ExpectedObjectRevision[]
+        readonly expectedLinks: readonly ExpectedLinkRevision[]
+      }
+    ) =>
+      runtimeMaterializer.edits.commit({
+        mode: "atomic",
+        source: { kind: "runtime", requestId },
+        operations: [
+          {
+            id: "rename",
+            kind: "object.patch",
+            ref: device,
+            set: { name: requestId },
+            unset: [],
+            reset: [],
+          },
+        ],
+        ...expected,
+        expectedLinkScopes: [],
+      })
+
+    try {
+      await runtimeMaterializer.edits.commit({
+        mode: "atomic",
+        source: { kind: "runtime", requestId: "expectation-setup" },
+        operations: [
+          { id: "device", kind: "object.create", ref: device, properties: { name: "device" } },
+          {
+            id: "peer",
+            kind: "object.create",
+            ref: peerLink.target,
+            properties: { name: "peer" },
+          },
+          { id: "link", kind: "link.upsert", ref: peerLink },
+        ],
+        expectedObjects: [],
+        expectedLinks: [],
+        expectedLinkScopes: [],
+      })
+
+      await expect(
+        commitExpecting("stale-object", {
+          expectedObjects: [{ ref: device, exists: false }],
+          expectedLinks: [],
+        })
+      ).rejects.toMatchObject({ kind: "expectation" })
+      await expect(
+        commitExpecting("stale-link", {
+          expectedObjects: [],
+          expectedLinks: [{ ref: peerLink, exists: false }],
+        })
+      ).rejects.toMatchObject({ kind: "expectation" })
+    } finally {
+      await provider.cleanup?.(createdStorage)
+    }
+  })
+
   test(`${name} fences projected cardinality-many link scopes by fingerprint`, async () => {
     const createdStorage = await provider.createStorage()
     const storage = requireContractStorage(createdStorage)
@@ -886,9 +968,9 @@ export function runMaterializerStorageContractSuite<TStorage extends Storage>(
         expectedLinkScopes: [],
       })
 
-      await expect(commitObservation("stale-many-scope-action", "must not commit")).rejects.toThrow(
-        "Expected link scope changed"
-      )
+      const stale = commitObservation("stale-many-scope-action", "must not commit")
+      await expect(stale).rejects.toThrow("Expected link scope changed")
+      await expect(stale).rejects.toMatchObject({ kind: "expectation" })
       expect(
         await storage.objects.getByPrimaryId({
           projectId: "materializer-storage-contract",

package/src/testing/object-query-contract.ts

@@ -10,10 +10,11 @@ import {
   normalizeObjectQuery,
   type ObjectQuery,
   ObjectQueryPlanningError,
+  type ObjectQueryPredicate,
   planObjectQuery,
   validateObjectQuery,
 } from "../objects/query"
-import { defineObjectType, link, OntologyRegistry, prop, stringEnum } from "../ontology"
+import { defineObjectType, link, OntologyRegistry, prop, ref, stringEnum } from "../ontology"
 import type { ObjectStorage, QueryObjectsResult } from "../storage/objects"
 import type { Storage } from "../storage/types"
 import {
@@ -133,8 +134,29 @@ const DefaultTextChild = defineObjectType({
   search: { defaultText: ["alias"] },
 })
 
+const Task = defineObjectType({
+  id: "ContractTask",
+  name: "Contract Task",
+  properties: [
+    prop("id", "string", {
+      required: true,
+      primary: true,
+      query: { searchable: true, sortable: true },
+    }),
+    prop("assignee", ref.user(), {
+      nullable: true,
+      query: { searchable: true, filterable: true, facet: true },
+    }),
+    prop(
+      "reviewers",
+      { type: "array", items: ref.user() },
+      { query: { searchable: true, filterable: true } }
+    ),
+  ],
+})
+
 export const objectQueryContractOntology = new OntologyRegistry({
-  sources: [Room, Device, Zone, Asset, LaptopAsset, DefaultTextBase, DefaultTextChild],
+  sources: [Room, Device, Zone, Asset, LaptopAsset, DefaultTextBase, DefaultTextChild, Task],
 })
 
 /**
@@ -151,6 +173,7 @@ export function runObjectQueryProviderContractSuite<TStorage extends Storage>(
 ): void {
   const withStorage = async (
     body: (context: {
+      readonly storage: TStorage
       readonly objects: TStorage["objects"]
       readonly fixture: MaterializerTestFixture
     }) => Promise<void>
@@ -158,6 +181,7 @@ export function runObjectQueryProviderContractSuite<TStorage extends Storage>(
     const storage = await options.createStorage()
     try {
       await body({
+        storage,
         objects: storage.objects,
         fixture: createMaterializerTestFixture({
           projectId,
@@ -835,6 +859,101 @@ export function runObjectQueryProviderContractSuite<TStorage extends Storage>(
       })
     })
 
+    test("matches user references on type and id, and groups facets by user", async () => {
+      await withStorage(async ({ storage: complete, objects: storage, fixture }) => {
+        const auth = complete.auth
+        if (!auth) throw new Error("The object query contract requires auth storage.")
+        for (const id of ["usr_alice", "usr_bob", "usr_carol"]) {
+          await auth.users.create({ projectId, id, email: `${id}@example.com` })
+        }
+        const alice = { type: "user", id: "usr_alice" }
+        const bob = { type: "user", id: "usr_bob" }
+        const carol = { type: "user", id: "usr_carol" }
+        await fixture.seed({
+          objects: [
+            objectSeed(Task.id, "t1", { assignee: alice, reviewers: [bob] }),
+            objectSeed(Task.id, "t2", { assignee: alice, reviewers: [bob, carol] }),
+            objectSeed(Task.id, "t3", { assignee: alice, reviewers: [] }),
+            objectSeed(Task.id, "t4", { assignee: bob, reviewers: [alice] }),
+            objectSeed(Task.id, "t5", { assignee: bob, reviewers: [carol] }),
+            objectSeed(Task.id, "t6", { assignee: null, reviewers: [] }),
+            objectSeed(Task.id, "t7", { reviewers: [] }),
+          ],
+        })
+
+        const ids = async (predicate: ObjectQueryPredicate) => {
+          const result = await executeObjectQuery(
+            {
+              projectId,
+              query: {
+                kind: "sort",
+                fields: [{ kind: "property", propertyId: "id" }],
+                input: {
+                  kind: "filter",
+                  predicate,
+                  input: { kind: "start", objectTypeId: Task.id },
+                },
+              },
+            },
+            { ontology: objectQueryContractOntology, storage }
+          )
+          expect(result.plan.mode).toBe("pushdown")
+          return result.objects.map((object) => object.primaryId)
+        }
+
+        expect(await ids({ op: "eq", propertyId: "assignee", value: alice })).toEqual([
+          "t1",
+          "t2",
+          "t3",
+        ])
+        // Field order is not part of the value.
+        expect(
+          await ids({ op: "eq", propertyId: "assignee", value: { id: "usr_alice", type: "user" } })
+        ).toEqual(["t1", "t2", "t3"])
+        expect(await ids({ op: "neq", propertyId: "assignee", value: alice })).toEqual([
+          "t4",
+          "t5",
+          "t6",
+          "t7",
+        ])
+        expect(await ids({ op: "in", propertyId: "assignee", values: [bob, null] })).toEqual([
+          "t4",
+          "t5",
+          "t6",
+        ])
+        expect(await ids({ op: "exists", propertyId: "assignee", value: false })).toEqual(["t7"])
+        expect(await ids({ op: "contains", propertyId: "reviewers", value: bob })).toEqual([
+          "t1",
+          "t2",
+        ])
+        expect(await ids({ op: "contains", propertyId: "reviewers", value: carol })).toEqual([
+          "t2",
+          "t5",
+        ])
+        expect(await ids({ op: "contains", propertyId: "reviewers", value: alice })).toEqual(["t4"])
+
+        const facets = await facetObjects(
+          {
+            projectId,
+            query: { kind: "start", objectTypeId: Task.id },
+            facets: [{ propertyId: "assignee", limit: 10 }],
+          },
+          { ontology: objectQueryContractOntology, storage }
+        )
+        expect(facets.plan.mode).toBe("pushdown")
+        expect(facets.facets).toEqual([
+          {
+            propertyId: "assignee",
+            buckets: [
+              { value: alice, count: 3 },
+              { value: bob, count: 2 },
+              { value: null, count: 1 },
+            ],
+          },
+        ])
+      })
+    })
+
     test("counts matching objects by facetable properties without returning rows", async () => {
       await withStorage(async ({ objects: storage, fixture }) => {
         await seedObjectQueryContractData(fixture)

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

@@ -1,3 +1,4 @@
+import type { AuthorizablePrincipal } from "../execution/types"
 import { createEventId } from "../materialization/identity"
 import type {
   MaterializationPlanHeader,
@@ -29,6 +30,11 @@ const emptyChunk = {
   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}` }
+}
+
 export function contractEditHeader(id: string): MaterializationPlanHeader {
   return {
     commit: {
@@ -38,6 +44,7 @@ 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,
@@ -90,9 +97,15 @@ export async function commitExactObject(
     readonly primaryId?: string
     readonly omitFinalize?: boolean
     readonly throwAfterFinalize?: boolean
+    /** Must name an existing auth principal: SQL providers reference it from the execution. */
+    readonly requestedBy?: AuthorizablePrincipal
   } = {}
 ): Promise<{ readonly eventId: string }> {
-  const header = contractEditHeader(id)
+  const defaultHeader = contractEditHeader(id)
+  const header: MaterializationPlanHeader =
+    options.requestedBy === undefined
+      ? defaultHeader
+      : { ...defaultHeader, commit: { ...defaultHeader.commit, requestedBy: options.requestedBy } }
   const ref = { objectTypeId: "ContractDevice", primaryId: options.primaryId ?? id }
   const row = {
     ref,
@@ -109,6 +122,8 @@ export async function commitExactObject(
     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,
@@ -214,12 +229,17 @@ export async function ensureContractExecution(
   ) {
     return
   }
+  const { requestedBy } = header.commit
   await storage.executions.create({
     id: header.commit.executionId,
     projectId: header.commit.projectId,
-    executor: { type: "request", requestId: `contract-request:${header.commit.id}` },
+    ...(requestedBy === undefined ? {} : { requestedBy }),
+    executor: contractExecutor(header.commit.id),
     source: { type: "http", requestId: `contract-request:${header.commit.id}` },
     correlationId: `contract-correlation:${header.commit.id}`,
-    authorizationRef: { type: "disabled" },
+    authorizationRef:
+      requestedBy === undefined
+        ? { type: "disabled" }
+        : { type: "principal", principal: requestedBy },
   })
 }