@sixb/core 0.1.16 → 0.1.17

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

@@ -16,6 +16,7 @@ import { createTestingScope } from "../execution/scopes"
 import type {
   ExpectedLinkRevision,
   ExpectedObjectRevision,
+  OntologyLinkRef,
   OntologyMaterializer,
 } from "../materializer"
 import {
@@ -27,13 +28,34 @@ import {
   type ProjectionSourceDeletion,
   type ProjectionSourceEntry,
 } from "../materializer"
-import type { ActionRunStorage, ProjectionRunStorage } from "../storage"
+import type {
+  ActionRunStorage,
+  OntologyCommitWrite,
+  OntologyReplacementPlanStorage,
+  PlannedReplacementIdentity,
+  ProjectionExecution,
+  ProjectionRunStorage,
+} from "../storage"
 import { createTestActionExecution, queueTestActionRun } from "./action-execution"
 import { createTestProjectionExecution, startTestProjectionRun } from "./projection-execution"
 
 export interface MaterializerStorageContractProvider<TStorage extends Storage> {
   readonly createStorage: () => TStorage | Promise<TStorage>
   readonly cleanup?: (storage: TStorage) => void | Promise<void>
+  /** Write transactions run side by side instead of one after another. */
+  readonly concurrentTransactions?: boolean
+  /**
+   * Moves the transaction ids that commits and plans recorded far ahead of the store's own, as a
+   * logical restore from a cluster further along leaves them.
+   */
+  readonly restoreFromClusterAhead?: (storage: TStorage) => Promise<void>
+  /** How many entity touches of commits the store still records. */
+  readonly countCommitTouches: (storage: TStorage) => Promise<number>
+  /**
+   * Deletes every commit touch as a purge that has not seen a plan opening yet would, leaving the
+   * record that they are gone. Only a store whose purge can race a plan's opening provides it.
+   */
+  readonly losePlanTouchesToPurge?: (storage: TStorage) => Promise<void>
 }
 
 type ContractStorage = Storage & {
@@ -982,6 +1004,758 @@ export function runMaterializerStorageContractSuite<TStorage extends Storage>(
       await provider.cleanup?.(createdStorage)
     }
   })
+
+  // Removal proof: make every provider's `refresh` answer fresh; the edited object's planned
+  // upsert then fails its revision check and the publication rejects. Drop the round inside the
+  // commit transaction from `refreshProjectionPlan`: a is then planned again outside it.
+  test(`${name} plans again only the identity an edit changed while it planned`, async () => {
+    const createdStorage = await provider.createStorage()
+    const storage = requireContractStorage(createdStorage)
+    const runtime = contractMaterializer(storage).withScope(runtimeScope())
+    let armed = false
+    let edited = false
+    const staged: string[] = []
+    const observed = observePlanning(storage, async (planned, _commit, inTransaction) => {
+      if (!armed) return
+      staged.push(...planned.map((value) => `${plannedId(value)}${inTransaction ? "@commit" : ""}`))
+      if (edited || !planned.some((value) => plannedId(value) === "a")) return
+      edited = true
+      await runtime.edits.commit({
+        mode: "atomic",
+        source: { kind: "runtime", requestId: "edit-while-planned" },
+        operations: [
+          {
+            id: "rename",
+            kind: "object.patch",
+            ref: deviceRef("a"),
+            set: { name: "edited" },
+            unset: [],
+            reset: [],
+          },
+        ],
+        expectedObjects: [],
+        expectedLinks: [],
+        expectedLinkScopes: [],
+      })
+    })
+    const materializer = contractMaterializer(observed)
+    try {
+      await publishDevices(materializer, storage, 1, [sourceEntry("a", "A"), sourceEntry("b", "B")])
+      armed = true
+      await publishDevices(materializer, storage, 2, [
+        sourceEntry("a", "A2"),
+        sourceEntry("b", "B2"),
+      ])
+      // The commit plans the one identity the edit made stale itself.
+      expect(staged.filter((id) => id.startsWith("a"))).toEqual(["a", "a@commit"])
+      expect(staged.filter((id) => id.startsWith("b"))).toEqual(["b"])
+      expect(await device(storage, "a")).toMatchObject({ properties: { name: "edited" } })
+      expect(await device(storage, "b")).toMatchObject({ properties: { name: "B2" } })
+    } finally {
+      await provider.cleanup?.(createdStorage)
+    }
+  })
+
+  // Removal proof: drop the link expansion from every provider's `refresh`; the link the edit
+  // added keeps pointing at the object the publication deleted.
+  test(`${name} plans the links an edit adds to an object the projection deletes`, async () => {
+    const createdStorage = await provider.createStorage()
+    const storage = requireContractStorage(createdStorage)
+    const runtime = contractMaterializer(storage).withScope(runtimeScope())
+    let armed = false
+    const observed = observePlanning(storage, async (planned) => {
+      if (!armed || !planned.some(({ identity }) => identity.kind === "link")) return
+      armed = false
+      await runtime.edits.commit({
+        mode: "atomic",
+        source: { kind: "runtime", requestId: "link-while-planned" },
+        operations: [
+          {
+            id: "peer",
+            kind: "link.upsert",
+            ref: { source: deviceRef("c"), linkId: "peers", target: deviceRef("a") },
+          },
+        ],
+        expectedObjects: [],
+        expectedLinks: [],
+        expectedLinkScopes: [],
+      })
+    })
+    const materializer = contractMaterializer(observed)
+    try {
+      await publishDevices(materializer, storage, 1, [
+        sourceEntry("a", "A"),
+        sourceEntry("b", "B", "a"),
+        sourceEntry("c", "C"),
+      ])
+      armed = true
+      await publishDevices(materializer, storage, 2, [sourceEntry("b", "B"), sourceEntry("c", "C")])
+      expect(await device(storage, "a")).toBeNull()
+      for (const id of ["b", "c"]) {
+        expect(
+          await storage.objects.listLinks({
+            projectId: CONTRACT_PROJECT,
+            objectTypeId: Device.id,
+            objectId: id,
+          })
+        ).toEqual([])
+      }
+    } finally {
+      await provider.cleanup?.(createdStorage)
+    }
+  })
+
+  // Removal proof: compare a link's edge override by an unqualified `identity_key` in the SQLite
+  // revision; it then reads another link's override, and the untouched link is planned again.
+  // Drop the touches of slot overrides from every provider: b is then not planned again.
+  test(`${name} plans again only the link whose override an edit changed while it planned`, async () => {
+    const createdStorage = await provider.createStorage()
+    const storage = requireContractStorage(createdStorage)
+    const runtime = contractMaterializer(storage).withScope(runtimeScope())
+    let armed = false
+    let edited = false
+    const staged: string[] = []
+    const observed = observePlanning(storage, async (planned, _commit, inTransaction) => {
+      if (!armed) return
+      const links = planned.flatMap(({ identity }) =>
+        identity.kind === "link" ? [identity.ref.source.primaryId] : []
+      )
+      staged.push(...links.map((id) => `${id}${inTransaction ? "@commit" : ""}`))
+      if (edited || !links.includes("c")) return
+      edited = true
+      // Once both links are planned, keeps the one of b the publication retracts; its effective
+      // row stays as it was.
+      await runtime.edits.commit({
+        mode: "atomic",
+        source: { kind: "runtime", requestId: "override-while-planned" },
+        operations: [
+          {
+            id: "keep",
+            kind: "link.upsert",
+            ref: { source: deviceRef("b"), linkId: "parent", target: deviceRef("a") },
+          },
+        ],
+        expectedObjects: [],
+        expectedLinks: [],
+        expectedLinkScopes: [],
+      })
+    })
+    const materializer = contractMaterializer(observed)
+    const parent = (id: string) =>
+      storage.objects.listLinks({
+        projectId: CONTRACT_PROJECT,
+        objectTypeId: Device.id,
+        objectId: id,
+      })
+    try {
+      await publishDevices(materializer, storage, 1, [
+        sourceEntry("a", "A"),
+        sourceEntry("b", "B", "a"),
+        sourceEntry("c", "C", "a"),
+      ])
+      armed = true
+      await publishDevices(materializer, storage, 2, [
+        sourceEntry("a", "A"),
+        sourceEntry("b", "B"),
+        sourceEntry("c", "C"),
+      ])
+      expect(staged.filter((id) => id.startsWith("b"))).toEqual(["b", "b@commit"])
+      expect(staged.filter((id) => id.startsWith("c"))).toEqual(["c"])
+      expect(await parent("b")).toHaveLength(1)
+      expect(await parent("c")).toEqual([])
+    } finally {
+      await provider.cleanup?.(createdStorage)
+    }
+  })
+
+  // Removal proof: drop the touches source activation records from every provider; the
+  // publication then creates the link from the assertion the other source retracted.
+  test(`${name} plans again a link whose live assertion another source retracts`, async () => {
+    const createdStorage = await provider.createStorage()
+    const storage = requireContractStorage(createdStorage)
+    const peer = { source: deviceRef("b"), linkId: "peers", target: deviceRef("a") }
+    let armed = false
+    const observed = observePlanning(storage, async (planned, _commit, inTransaction) => {
+      if (!armed || inTransaction || !planned.some(({ identity }) => identity.kind === "link")) {
+        return
+      }
+      armed = false
+      // a is still missing: retracting the assertion changes no effective link.
+      await publishPeers(contractMaterializer(storage), storage, 2, [])
+    })
+    const materializer = contractMaterializer(observed)
+    try {
+      await publishDevices(materializer, storage, 1, [sourceEntry("b", "B")])
+      await publishPeers(materializer, storage, 1, [peer])
+      armed = true
+      // Creating a brings in the link the peers source asserts towards it.
+      await publishDevices(materializer, storage, 2, [sourceEntry("a", "A"), sourceEntry("b", "B")])
+      expect(armed).toBe(false)
+      expect(
+        await storage.objects.listLinks({
+          projectId: CONTRACT_PROJECT,
+          objectTypeId: Device.id,
+          objectId: "b",
+          linkId: "peers",
+        })
+      ).toEqual([])
+    } finally {
+      await provider.cleanup?.(createdStorage)
+    }
+  })
+
+  // Removal proof: drop the lookup of links by `target_key` from the PostgreSQL and SQLite refresh,
+  // or the target from the in-memory `touchesIdentity`; the link then stays planned as dangling.
+  test(`${name} plans again a link whose missing target an edit creates meanwhile`, async () => {
+    const createdStorage = await provider.createStorage()
+    const storage = requireContractStorage(createdStorage)
+    const runtime = contractMaterializer(storage).withScope(runtimeScope())
+    let armed = false
+    const observed = observePlanning(storage, async (planned, _commit, inTransaction) => {
+      if (!armed || inTransaction || !planned.some(({ identity }) => identity.kind === "link")) {
+        return
+      }
+      armed = false
+      await runtime.edits.commit({
+        mode: "atomic",
+        source: { kind: "runtime", requestId: "target-while-planned" },
+        operations: [
+          { id: "create", kind: "object.create", ref: deviceRef("x"), properties: { name: "X" } },
+        ],
+        expectedObjects: [],
+        expectedLinks: [],
+        expectedLinkScopes: [],
+      })
+    })
+    const materializer = contractMaterializer(observed)
+    try {
+      await publishDevices(materializer, storage, 1, [sourceEntry("b", "B")])
+      armed = true
+      await publishDevices(materializer, storage, 2, [sourceEntry("b", "B", "x")])
+      expect(armed).toBe(false)
+      expect(
+        await storage.objects.listLinks({
+          projectId: CONTRACT_PROJECT,
+          objectTypeId: Device.id,
+          objectId: "b",
+          linkId: "parent",
+        })
+      ).toMatchObject([{ targetId: "x" }])
+    } finally {
+      await provider.cleanup?.(createdStorage)
+    }
+  })
+
+  // Removal proof: drop the lookup of the links a touched object starts from the PostgreSQL and
+  // SQLite refresh, or the source from the in-memory `touchesIdentity`; the publication then
+  // plans the link from an object that no longer exists.
+  test(`${name} plans again a link whose source an edit deletes meanwhile`, async () => {
+    const createdStorage = await provider.createStorage()
+    const storage = requireContractStorage(createdStorage)
+    const runtime = contractMaterializer(storage).withScope(runtimeScope())
+    const edit = (requestId: string, operation: OntologyEditOperation) =>
+      runtime.edits.commit({
+        mode: "atomic",
+        source: { kind: "runtime", requestId },
+        operations: [operation],
+        expectedObjects: [],
+        expectedLinks: [],
+        expectedLinkScopes: [],
+      })
+    let armed = false
+    const observed = observePlanning(storage, async (planned, _commit, inTransaction) => {
+      if (!armed || inTransaction || !planned.some(({ identity }) => identity.kind === "link")) {
+        return
+      }
+      armed = false
+      await edit("source-while-planned", {
+        id: "delete",
+        kind: "object.delete",
+        ref: deviceRef("c"),
+      })
+    })
+    const materializer = contractMaterializer(observed)
+    try {
+      await edit("create-source", {
+        id: "create",
+        kind: "object.create",
+        ref: deviceRef("c"),
+        properties: { name: "C" },
+      })
+      await publishDevices(materializer, storage, 1, [sourceEntry("b", "B")])
+      await publishPeers(materializer, storage, 1, [
+        { source: deviceRef("c"), linkId: "peers", target: deviceRef("a") },
+      ])
+      armed = true
+      // Creating a brings in the link from c the peers source asserts towards it.
+      await publishDevices(materializer, storage, 2, [sourceEntry("a", "A"), sourceEntry("b", "B")])
+      expect(armed).toBe(false)
+      expect(await device(storage, "c")).toBeNull()
+      expect(
+        await storage.objects.listLinks({
+          projectId: CONTRACT_PROJECT,
+          objectTypeId: Device.id,
+          objectId: "c",
+          linkId: "peers",
+        })
+      ).toEqual([])
+    } finally {
+      await provider.cleanup?.(createdStorage)
+    }
+  })
+
+  // Removal proof: make SQLite's plan-bound session compare its watermark with the last commit of
+  // any project; the commit then rejects the plan its refresh just found fresh.
+  test(`${name} commits a plan another project committed beside`, async () => {
+    const createdStorage = await provider.createStorage()
+    const storage = requireContractStorage(createdStorage)
+    const other = createOntologyMaterializer({
+      projectId: "other-project",
+      ontology,
+      projections,
+      storage,
+    }).withScope(
+      createTestingScope({
+        projectId: "other-project",
+        executionId: "other-project-runtime-execution",
+        requestId: "other-project-runtime-request",
+        correlationId: "other-project-runtime-correlation",
+      })
+    )
+    let armed = false
+    let staged = 0
+    const observed = observePlanning(storage, async (planned) => {
+      if (!armed) return
+      staged += planned.length
+      if (staged !== 1) return
+      await other.edits.commit({
+        mode: "atomic",
+        source: { kind: "runtime", requestId: "other-project-edit" },
+        operations: [
+          { id: "create", kind: "object.create", ref: deviceRef("x"), properties: { name: "X" } },
+        ],
+        expectedObjects: [],
+        expectedLinks: [],
+        expectedLinkScopes: [],
+      })
+    })
+    const materializer = contractMaterializer(observed)
+    try {
+      await publishDevices(materializer, storage, 1, [sourceEntry("a", "A")])
+      armed = true
+      await publishDevices(materializer, storage, 2, [
+        sourceEntry("a", "A2"),
+        sourceEntry("b", "B"),
+      ])
+      expect(staged).toBe(2)
+      expect(await device(storage, "b")).toMatchObject({ properties: { name: "B" } })
+    } finally {
+      await provider.cleanup?.(createdStorage)
+    }
+  })
+
+  // Removal proof: in PostgreSQL's `committedSince`, count only commits at or past the
+  // watermark's xmax; the edit, in flight when the plan opened, is then taken as seen.
+  if (provider.concurrentTransactions) {
+    test(`${name} plans again what a commit in flight when the plan opened changed`, async () => {
+      const createdStorage = await provider.createStorage()
+      const storage = requireContractStorage(createdStorage)
+      const paused = pauseBeforeFinalize(storage)
+      const runtime = contractMaterializer(paused.storage).withScope(runtimeScope())
+      let edit: Promise<unknown> | undefined
+      let armed = false
+      let staged = 0
+      const observed = observePlanning(storage, async (planned) => {
+        if (!armed) return
+        staged += planned.length
+        if (staged !== 1) return
+        // The page read the object before the edit committed.
+        paused.release()
+        await edit
+      })
+      const materializer = contractMaterializer(observed)
+      try {
+        await publishDevices(materializer, storage, 1, [sourceEntry("a", "A")])
+        edit = runtime.edits.commit({
+          mode: "atomic",
+          source: { kind: "runtime", requestId: "edit-in-flight" },
+          operations: [
+            {
+              id: "rename",
+              kind: "object.patch",
+              ref: deviceRef("a"),
+              set: { name: "edited" },
+              unset: [],
+              reset: [],
+            },
+          ],
+          expectedObjects: [],
+          expectedLinks: [],
+          expectedLinkScopes: [],
+        })
+        // It has written the object and holds its transaction open.
+        await paused.reached
+        armed = true
+        await publishDevices(materializer, storage, 2, [sourceEntry("a", "A2")])
+        await edit
+        expect(staged).toBe(2)
+        expect(await device(storage, "a")).toMatchObject({ properties: { name: "edited" } })
+      } finally {
+        paused.release()
+        await provider.cleanup?.(createdStorage)
+      }
+    })
+  }
+
+  // Removal proof: let the in-memory `streamState` keep the identities it listed instead of
+  // looking each page's up again; the rollback restores the plan as copies, and the next page
+  // marks as read identities the plan no longer holds.
+  test(`${name} keeps planning across a transaction that rolls back meanwhile`, async () => {
+    const createdStorage = await provider.createStorage()
+    const storage = requireContractStorage(createdStorage)
+    let staged = 0
+    const observed = observePlanning(storage, async (planned) => {
+      staged += planned.length
+      if (staged !== 1) return
+      await expect(
+        storage.transaction(async () => {
+          throw new Error("rolled back")
+        })
+      ).rejects.toThrow("rolled back")
+    })
+    const materializer = contractMaterializer(observed)
+    try {
+      await publishDevices(materializer, storage, 1, [sourceEntry("a", "A"), sourceEntry("b", "B")])
+      expect(staged).toBe(2)
+      expect(await device(storage, "b")).toMatchObject({ properties: { name: "B" } })
+    } finally {
+      await provider.cleanup?.(createdStorage)
+    }
+  })
+
+  // Removal proof: in PostgreSQL's `committedSince`, drop the check of a watermark from beyond
+  // this snapshot (the stale plan applies and conflicts with the edit), or the filter on commits
+  // this snapshot sees (no plan reads as just refreshed again).
+  const restoreFromClusterAhead = provider.restoreFromClusterAhead
+  if (restoreFromClusterAhead) {
+    test(`${name} plans again after a restore from a cluster further along`, async () => {
+      const createdStorage = await provider.createStorage()
+      const storage = requireContractStorage(createdStorage)
+      const runtime = contractMaterializer(storage).withScope(runtimeScope())
+      let failNextCommit = false
+      let staged = 0
+      const observed = observePlanning(
+        storage,
+        async (planned) => {
+          staged += planned.length
+        },
+        async () => {
+          if (!failNextCommit || staged === 0) return
+          failNextCommit = false
+          throw new Error("commit lost")
+        }
+      )
+      const materializer = contractMaterializer(observed)
+      try {
+        await publishDevices(materializer, storage, 1, [sourceEntry("a", "A")])
+        const execution = await claimDevices(storage, 2)
+        failNextCommit = true
+        staged = 0
+        await expect(
+          publishDevices(materializer, storage, 2, [sourceEntry("a", "A2")], execution)
+        ).rejects.toThrow("commit lost")
+        await runtime.edits.commit({
+          mode: "atomic",
+          source: { kind: "runtime", requestId: "edit-before-restore" },
+          operations: [
+            {
+              id: "rename",
+              kind: "object.patch",
+              ref: deviceRef("a"),
+              set: { name: "edited" },
+              unset: [],
+              reset: [],
+            },
+          ],
+          expectedObjects: [],
+          expectedLinks: [],
+          expectedLinkScopes: [],
+        })
+        await restoreFromClusterAhead(createdStorage)
+        await publishDevices(materializer, storage, 2, [sourceEntry("a", "A2")], execution)
+        expect(await device(storage, "a")).toMatchObject({ properties: { name: "edited" } })
+      } finally {
+        await provider.cleanup?.(createdStorage)
+      }
+    })
+  }
+
+  // Removal proof: let `open` reset an existing plan; the redelivery stages all three identities
+  // again. Let it keep the plan but answer the time it was given: the redelivery cannot commit.
+  test(`${name} resumes the plan a failed commit left to the next delivery`, async () => {
+    const createdStorage = await provider.createStorage()
+    const storage = requireContractStorage(createdStorage)
+    let failNextCommit = true
+    let stagedIdentities = 0
+    let plannedAt: string | undefined
+    const observed = observePlanning(
+      storage,
+      async (planned, commit) => {
+        stagedIdentities += planned.length
+        plannedAt ??= commit.committedAt
+      },
+      async () => {
+        // Admission opens a transaction before anything is planned: fail the commit's.
+        if (!failNextCommit || stagedIdentities === 0) return
+        failNextCommit = false
+        throw new Error("commit lost")
+      }
+    )
+    const materializer = contractMaterializer(observed)
+    try {
+      const execution = await claimDevices(storage, 1)
+      const values = [sourceEntry("a", "A"), sourceEntry("b", "B", "a")]
+      await expect(publishDevices(materializer, storage, 1, values, execution)).rejects.toThrow(
+        "commit lost"
+      )
+      expect(stagedIdentities).toBe(3)
+      // The redelivery's clock has moved on; its commit keeps the time its events were planned at.
+      await new Promise((resolve) => setTimeout(resolve, 5))
+      const result = await publishDevices(materializer, storage, 1, values, execution)
+      expect(stagedIdentities).toBe(3)
+      expect(result.committedAt).toBe(plannedAt!)
+      expect(await device(storage, "b")).toMatchObject({ properties: { name: "B" } })
+    } finally {
+      await provider.cleanup?.(createdStorage)
+    }
+  })
+
+  // Removal proof: let `open` resume a plan whatever source it replaces; the redelivery then
+  // keeps an entity only the newer active source asserted, or rejects its own activation.
+  test(`${name} plans again from scratch when the source a plan replaces moved`, async () => {
+    const createdStorage = await provider.createStorage()
+    const storage = requireContractStorage(createdStorage)
+    let failNextCommit = false
+    let staged = 0
+    const observed = observePlanning(
+      storage,
+      async (planned) => {
+        staged += planned.length
+      },
+      async () => {
+        if (!failNextCommit || staged === 0) return
+        failNextCommit = false
+        throw new Error("commit lost")
+      }
+    )
+    const materializer = contractMaterializer(observed)
+    try {
+      await publishDevices(materializer, storage, 1, [sourceEntry("a", "A")])
+      const execution = await claimDevices(storage, 3)
+      failNextCommit = true
+      staged = 0
+      await expect(
+        publishDevices(materializer, storage, 3, [sourceEntry("a", "A3")], execution)
+      ).rejects.toThrow("commit lost")
+      await publishDevices(materializer, storage, 2, [
+        sourceEntry("a", "A2"),
+        sourceEntry("z", "Z"),
+      ])
+      staged = 0
+      await publishDevices(materializer, storage, 3, [sourceEntry("a", "A3")], execution)
+      expect(staged).toBe(2)
+      expect(await device(storage, "a")).toMatchObject({ properties: { name: "A3" } })
+      expect(await device(storage, "z")).toBeNull()
+    } finally {
+      await provider.cleanup?.(createdStorage)
+    }
+  })
+
+  // Removal proof: drop the round bound in `commitProjectionCandidate`; the delivery plans again
+  // after every edit and never returns. Drop the `transactionReplanRows` bound from
+  // `refreshProjectionPlan`: the commit then plans both edits itself and the publication lands.
+  test(`${name} gives the delivery back when identities keep changing while planned`, async () => {
+    const createdStorage = await provider.createStorage()
+    const storage = requireContractStorage(createdStorage)
+    const runtime = contractMaterializer(storage).withScope(runtimeScope())
+    let armed = false
+    let edits = 0
+    const observed = observePlanning(storage, async (planned, _commit, inTransaction) => {
+      // Once both are read: each round finds them both stale.
+      if (!armed || inTransaction || !planned.some((value) => plannedId(value) === "b")) return
+      edits += 1
+      await runtime.edits.commit({
+        mode: "atomic",
+        source: { kind: "runtime", requestId: `keeps-changing-${edits}` },
+        operations: ["a", "b"].map((id) => ({
+          id: `rename-${id}`,
+          kind: "object.patch" as const,
+          ref: deviceRef(id),
+          set: { name: `${id}${edits}` },
+          unset: [],
+          reset: [],
+        })),
+        expectedObjects: [],
+        expectedLinks: [],
+        expectedLinkScopes: [],
+      })
+    })
+    // Two stale identities are more than its commit plans itself.
+    const materializer = contractMaterializer(observed, { transactionReplanRows: 1 })
+    try {
+      await publishDevices(materializer, storage, 1, [sourceEntry("a", "A"), sourceEntry("b", "B")])
+      armed = true
+      await expect(
+        publishDevices(materializer, storage, 2, [sourceEntry("a", "A2"), sourceEntry("b", "B2")])
+      ).rejects.toMatchObject({
+        kind: "effective-state",
+        message: expect.stringContaining("(2 changed during the last of 3 rounds)"),
+      })
+      expect(edits).toBe(3)
+    } finally {
+      await provider.cleanup?.(createdStorage)
+    }
+  })
+
+  // Removal proof: drop the purge of touches from every provider's `purge`; touches outlive
+  // every plan. Let it ignore the watermark of ready plans: it then keeps none of the touches the
+  // resumed plan needs.
+  test(`${name} purges only the touches no ready plan still needs`, async () => {
+    const createdStorage = await provider.createStorage()
+    const storage = requireContractStorage(createdStorage)
+    const runtime = contractMaterializer(storage).withScope(runtimeScope())
+    let failNextCommit = false
+    let staged = 0
+    const observed = observePlanning(
+      storage,
+      async (planned) => {
+        staged += planned.length
+      },
+      async () => {
+        if (!failNextCommit || staged === 0) return
+        failNextCommit = false
+        throw new Error("commit lost")
+      }
+    )
+    const materializer = contractMaterializer(observed)
+    try {
+      await publishDevices(materializer, storage, 1, [sourceEntry("a", "A"), sourceEntry("b", "B")])
+      const execution = await claimDevices(storage, 2)
+      failNextCommit = true
+      staged = 0
+      const values = [sourceEntry("a", "A2"), sourceEntry("b", "B2")]
+      await expect(publishDevices(materializer, storage, 2, values, execution)).rejects.toThrow(
+        "commit lost"
+      )
+      await renameDevice(runtime, "a", "edited")
+      const recorded = await provider.countCommitTouches(createdStorage)
+      await purgeEverything(storage)
+      // The edit committed after the plan last read a: the plan still needs what it touched.
+      const kept = await provider.countCommitTouches(createdStorage)
+      expect(kept).toBeGreaterThan(0)
+      expect(kept).toBeLessThan(recorded)
+
+      await publishDevices(materializer, storage, 2, values, execution)
+      expect(await device(storage, "a")).toMatchObject({ properties: { name: "edited" } })
+      await purgeEverything(storage)
+      expect(await provider.countCommitTouches(createdStorage)).toBe(0)
+    } finally {
+      await provider.cleanup?.(createdStorage)
+    }
+  })
+
+  // Removal proof: drop the horizon from PostgreSQL's `touchesIncomplete`; the refresh then finds
+  // no touch for the edit, and the stale upsert of a conflicts with it.
+  const losePlanTouchesToPurge = provider.losePlanTouchesToPurge
+  if (losePlanTouchesToPurge) {
+    test(`${name} checks every identity of a plan whose touches a racing purge took`, async () => {
+      const createdStorage = await provider.createStorage()
+      const storage = requireContractStorage(createdStorage)
+      const runtime = contractMaterializer(storage).withScope(runtimeScope())
+      let failNextCommit = false
+      let staged = 0
+      const observed = observePlanning(
+        storage,
+        async (planned) => {
+          staged += planned.length
+        },
+        async () => {
+          if (!failNextCommit || staged === 0) return
+          failNextCommit = false
+          throw new Error("commit lost")
+        }
+      )
+      const materializer = contractMaterializer(observed)
+      try {
+        await publishDevices(materializer, storage, 1, [sourceEntry("a", "A")])
+        const execution = await claimDevices(storage, 2)
+        failNextCommit = true
+        staged = 0
+        const values = [sourceEntry("a", "A2")]
+        await expect(publishDevices(materializer, storage, 2, values, execution)).rejects.toThrow(
+          "commit lost"
+        )
+        await renameDevice(runtime, "a", "edited")
+        await losePlanTouchesToPurge(createdStorage)
+        await publishDevices(materializer, storage, 2, values, execution)
+        expect(await device(storage, "a")).toMatchObject({ properties: { name: "edited" } })
+      } finally {
+        await provider.cleanup?.(createdStorage)
+      }
+    })
+  }
+
+  // Removal proof: let `purge` take plans whose candidate is still ready; the second delivery
+  // then plans every identity again instead of resuming. Let it stop after one plan: a second
+  // call still finds the other.
+  test(`${name} purges only the plans of candidates that moved on`, async () => {
+    const createdStorage = await provider.createStorage()
+    const storage = requireContractStorage(createdStorage)
+    let interrupt = false
+    let staged = 0
+    const observed = observePlanning(storage, async (planned) => {
+      staged += planned.length
+      if (interrupt && staged === 1) throw new Error("delivery lost")
+    })
+    const materializer = contractMaterializer(observed)
+    const purgeAll = async () => {
+      let rounds = 0
+      while (
+        (await storage.ontology.replacementPlans.purge({ projectId: CONTRACT_PROJECT, limit: 2 })) >
+        0
+      ) {
+        rounds += 1
+        if (rounds > 100) throw new Error("Plan purge never ran out.")
+      }
+    }
+    try {
+      await publishDevices(materializer, storage, 1, [sourceEntry("a", "A"), sourceEntry("b", "B")])
+      await purgeAll()
+      const execution = await claimDevices(storage, 2)
+      const values = [sourceEntry("a", "A2"), sourceEntry("c", "C")]
+      interrupt = true
+      staged = 0
+      await expect(publishDevices(materializer, storage, 2, values, execution)).rejects.toThrow(
+        "delivery lost"
+      )
+      interrupt = false
+      await purgeAll()
+      staged = 0
+      await publishDevices(materializer, storage, 2, values, execution)
+      expect(staged).toBe(2)
+      // Two spent plans: one call within its budget purges both.
+      await publishDevices(materializer, storage, 3, values)
+      await storage.ontology.replacementPlans.purge({ projectId: CONTRACT_PROJECT, limit: 1_000 })
+      expect(
+        await storage.ontology.replacementPlans.purge({ projectId: CONTRACT_PROJECT, limit: 1_000 })
+      ).toBe(0)
+      expect(await device(storage, "a")).toMatchObject({ properties: { name: "A2" } })
+      expect(await device(storage, "b")).toBeNull()
+      expect(await device(storage, "c")).toMatchObject({ properties: { name: "C" } })
+    } finally {
+      await provider.cleanup?.(createdStorage)
+    }
+  })
 }
 
 function runtimeScope() {
@@ -1128,3 +1902,236 @@ async function claim(
   })
   return claim.execution
 }
+
+const CONTRACT_PROJECT = "materializer-storage-contract"
+
+function contractMaterializer(
+  storage: Storage,
+  batching: { readonly transactionReplanRows?: number } = {}
+): OntologyMaterializer {
+  return createOntologyMaterializer({
+    projectId: CONTRACT_PROJECT,
+    ontology,
+    projections,
+    storage,
+    dependencies: {
+      batching: { sourceStageRows: 1, statePageRows: 1, planChunkRows: 1, ...batching },
+    },
+  })
+}
+
+function deviceRef(primaryId: string) {
+  return { objectTypeId: Device.id, primaryId }
+}
+
+function device(storage: ContractStorage, primaryId: string) {
+  return storage.objects.getByPrimaryId({ projectId: CONTRACT_PROJECT, ...deviceRef(primaryId) })
+}
+
+function plannedId({ identity }: PlannedReplacementIdentity): string {
+  return identity.kind === "object" ? identity.ref.primaryId : "link"
+}
+
+/**
+ * The same storage, whose plan staging runs `afterStage` once a page is staged, inside or outside a
+ * commit transaction, and whose transactions run `beforeTransaction` first: a way to interleave
+ * writes with a projection's plan. A write from `afterStage` must stay outside the transaction.
+ */
+function observePlanning(
+  storage: ContractStorage,
+  afterStage: (
+    planned: readonly PlannedReplacementIdentity[],
+    commit: OntologyCommitWrite,
+    inTransaction: boolean
+  ) => Promise<void>,
+  beforeTransaction?: () => Promise<void>
+): ContractStorage {
+  const observe = <T extends Storage>(scoped: T, inTransaction: boolean): T => {
+    const plans = scoped.ontology.replacementPlans
+    const observed: OntologyReplacementPlanStorage = {
+      open: (input) => plans.open(input),
+      streamState: (input) => plans.streamState(input),
+      async stage(input) {
+        await plans.stage(input)
+        await afterStage(input.planned, input.commit, inTransaction)
+      },
+      refresh: (input) => plans.refresh(input),
+      purge: (input) => plans.purge(input),
+    }
+    const ontologyFacade = new Proxy(scoped.ontology, {
+      get(target, property) {
+        if (property === "replacementPlans") return observed
+        const value = Reflect.get(target, property, target)
+        return typeof value === "function" ? value.bind(target) : value
+      },
+    })
+    return new Proxy(scoped, {
+      get(target, property) {
+        if (property === "ontology") return ontologyFacade
+        if (property === "transaction") {
+          return async (
+            run: (tx: Storage) => unknown,
+            options?: Parameters<Storage["transaction"]>[1]
+          ) => {
+            await beforeTransaction?.()
+            return target.transaction((tx) => run(observe(tx, true)), options)
+          }
+        }
+        const value = Reflect.get(target, property, target)
+        return typeof value === "function" ? value.bind(target) : value
+      },
+    })
+  }
+  return observe(storage, false)
+}
+
+/** The same storage, whose transactions wait before they finalize until `release` is called. */
+function pauseBeforeFinalize(storage: ContractStorage) {
+  let reach!: () => void
+  const reached = new Promise<void>((resolve) => {
+    reach = resolve
+  })
+  let release!: () => void
+  const released = new Promise<void>((resolve) => {
+    release = resolve
+  })
+  const paused = new Proxy(storage, {
+    get(target, property) {
+      if (property !== "transaction") {
+        const value = Reflect.get(target, property, target)
+        return typeof value === "function" ? value.bind(target) : value
+      }
+      return (run: (tx: Storage) => unknown, options?: Parameters<Storage["transaction"]>[1]) =>
+        target.transaction((tx) => {
+          const materializations = new Proxy(tx.ontology.materializations, {
+            get(store, key) {
+              const value = Reflect.get(store, key, store)
+              if (key !== "finalize") return typeof value === "function" ? value.bind(store) : value
+              return async (...args: Parameters<typeof store.finalize>) => {
+                reach()
+                await released
+                return store.finalize(...args)
+              }
+            },
+          })
+          const ontology = new Proxy(tx.ontology, {
+            get: (store, key) =>
+              key === "materializations" ? materializations : Reflect.get(store, key, store),
+          })
+          return run(
+            new Proxy(tx, {
+              get: (store, key) => (key === "ontology" ? ontology : Reflect.get(store, key, store)),
+            })
+          )
+        }, options)
+    },
+  })
+  return { storage: paused, reached, release }
+}
+
+function deviceVersion(version: number) {
+  return {
+    datasetId: devices.id,
+    versionId: `plan-v${version}`,
+    createdAt: `2026-02-${String(version).padStart(2, "0")}T00:00:00.000Z`,
+  }
+}
+
+function claimDevices(storage: ContractStorage, version: number): Promise<ProjectionExecution> {
+  return claim(storage, {
+    runId: `plan-run-${version}`,
+    projectionId: devices.id,
+    protocol: "replacement",
+    datasetVersion: deviceVersion(version),
+  })
+}
+
+function renameDevice(
+  runtime: ReturnType<OntologyMaterializer["withScope"]>,
+  primaryId: string,
+  name: string
+) {
+  return runtime.edits.commit({
+    mode: "atomic",
+    source: { kind: "runtime", requestId: `rename-${primaryId}-${name}` },
+    operations: [
+      {
+        id: "rename",
+        kind: "object.patch",
+        ref: deviceRef(primaryId),
+        set: { name },
+        unset: [],
+        reset: [],
+      },
+    ],
+    expectedObjects: [],
+    expectedLinks: [],
+    expectedLinkScopes: [],
+  })
+}
+
+async function purgeEverything(storage: ContractStorage): Promise<void> {
+  for (let rounds = 0; ; rounds += 1) {
+    if (rounds > 100) throw new Error("Plan purge never ran out.")
+    const deleted = await storage.ontology.replacementPlans.purge({
+      projectId: CONTRACT_PROJECT,
+      limit: 2,
+    })
+    if (deleted === 0) return
+  }
+}
+
+async function publishPeers(
+  materializer: OntologyMaterializer,
+  storage: ContractStorage,
+  version: number,
+  refs: readonly OntologyLinkRef[]
+) {
+  const datasetVersion = {
+    datasetId: devicePeers.id,
+    versionId: `peers-v${version}`,
+    createdAt: `2026-02-${String(version).padStart(2, "0")}T00:00:00.000Z`,
+  }
+  const execution = await claim(storage, {
+    runId: `peers-run-${version}`,
+    projectionId: devicePeersProjection.id,
+    protocol: "replacement",
+    datasetVersion,
+  })
+  const bound = await projectionMaterializer(
+    materializer,
+    storage,
+    devicePeersProjection.id,
+    execution.projectionRunId
+  )
+  return bound.projections.replace({
+    source: { projectionId: devicePeersProjection.id },
+    datasetVersion,
+    execution,
+    entries: entries(
+      refs.map((ref) => ({ root: { kind: "link", ref }, assertions: [{ kind: "link", ref }] }))
+    ),
+  })
+}
+
+async function publishDevices(
+  materializer: OntologyMaterializer,
+  storage: ContractStorage,
+  version: number,
+  values: readonly ProjectionSourceEntry[],
+  execution?: ProjectionExecution
+) {
+  const claimed = execution ?? (await claimDevices(storage, version))
+  const bound = await projectionMaterializer(
+    materializer,
+    storage,
+    devices.id,
+    claimed.projectionRunId
+  )
+  return bound.projections.replace({
+    source: { projectionId: devices.id },
+    datasetVersion: deviceVersion(version),
+    execution: claimed,
+    entries: entries(values),
+  })
+}