@sixb/core 0.1.13 → 0.1.15

package/src/storage/auth/in-memory/auth-storage.ts

@@ -7,6 +7,7 @@ import type {
   CompleteOidcSignInInput,
   CompleteSignInResult,
   GroupMembershipRecord,
+  GroupMembershipSource,
   InvitationRecord,
   SessionRecord,
   SuspendUserAndRevokeSessionsInput,
@@ -42,6 +43,7 @@ import {
   normalizeEmail,
   normalizeGroupIds,
   oidcAttemptKey,
+  removeGroupMembershipRecord,
   revokeActiveSessionsForUser,
   upsertGroupMembershipRecord,
   userKey,
@@ -219,25 +221,6 @@ export class InMemoryAuthStorage implements AuthStorage {
       )
     }
 
-    if (
-      shouldCreateUser &&
-      !activeInvitation &&
-      input.allowUserCreationWithoutInvitation &&
-      input.requireNoActiveUsersForUserCreation &&
-      hasActiveUsers(this.state, projectId)
-    ) {
-      consumeMagicLinkRecord(this.state, {
-        projectId,
-        id: input.magicLinkId,
-        tokenHash: input.tokenHash,
-        consumedAt: completedAt,
-      })
-      throw new AuthStorageError(
-        "user_creation_not_allowed",
-        `[Sixb] Magic link '${input.magicLinkId}' cannot create a user for project '${projectId}'.`
-      )
-    }
-
     validateCompleteSessionInput(this.state, projectId, input.session)
     assertSignInSessionAudience(projectId, input.session.audience, magicLink.audience)
 
@@ -280,8 +263,9 @@ export class InMemoryAuthStorage implements AuthStorage {
       projectId,
       user,
     })
-    const memberships = this.applyManualGroups({
+    const memberships = this.applyGroups({
       completedAt,
+      source: "manual",
       groupIds: manualGroupIds,
       projectId,
       userId: user.id,
@@ -352,14 +336,6 @@ export class InMemoryAuthStorage implements AuthStorage {
       )
     }
 
-    if (!identity && user && (!input.autoLinkByVerifiedEmail || !input.emailVerified)) {
-      this.consumeOidcAttempt(input, completedAt, projectId)
-      throw new AuthStorageError(
-        "email_link_not_allowed",
-        `[Sixb] OIDC identity cannot auto-link to user '${user.id}' for project '${projectId}'.`
-      )
-    }
-
     if (user?.status === "suspended") {
       this.consumeOidcAttempt(input, completedAt, projectId)
       throw new AuthStorageError(
@@ -368,14 +344,6 @@ export class InMemoryAuthStorage implements AuthStorage {
       )
     }
 
-    if (shouldCreateUser && !input.emailVerified) {
-      this.consumeOidcAttempt(input, completedAt, projectId)
-      throw new AuthStorageError(
-        "user_creation_not_allowed",
-        `[Sixb] OIDC authorization attempt '${input.oidcAuthorizationAttemptId}' cannot create a user for project '${projectId}'.`
-      )
-    }
-
     if (shouldCreateUser && !activeInvitation && !input.allowUserCreationWithoutInvitation) {
       this.consumeOidcAttempt(input, completedAt, projectId)
       throw new AuthStorageError(
@@ -384,20 +352,6 @@ export class InMemoryAuthStorage implements AuthStorage {
       )
     }
 
-    if (
-      shouldCreateUser &&
-      !activeInvitation &&
-      input.allowUserCreationWithoutInvitation &&
-      input.requireNoActiveUsersForUserCreation &&
-      hasActiveUsers(this.state, projectId)
-    ) {
-      this.consumeOidcAttempt(input, completedAt, projectId)
-      throw new AuthStorageError(
-        "user_creation_not_allowed",
-        `[Sixb] OIDC authorization attempt '${input.oidcAuthorizationAttemptId}' cannot create a user for project '${projectId}'.`
-      )
-    }
-
     validateCompleteSessionInput(this.state, projectId, input.session)
     assertSignInSessionAudience(projectId, input.session.audience, attempt.audience)
 
@@ -434,12 +388,19 @@ export class InMemoryAuthStorage implements AuthStorage {
       projectId,
       user,
     })
-    const memberships = this.applyManualGroups({
+    const memberships = this.syncDirectoryGroups({
       completedAt,
-      groupIds: manualGroupIds,
+      groupIds: input.directoryGroupIds,
       projectId,
       userId: user.id,
-      existing: invitation.memberships,
+      existing: this.applyGroups({
+        completedAt,
+        source: "manual",
+        groupIds: manualGroupIds,
+        projectId,
+        userId: user.id,
+        existing: invitation.memberships,
+      }),
     })
 
     const nextIdentity: UserIdentityRecord = {
@@ -533,10 +494,11 @@ export class InMemoryAuthStorage implements AuthStorage {
     return { invitation, memberships }
   }
 
-  private applyManualGroups(input: {
+  private applyGroups(input: {
     readonly completedAt: Date
     readonly groupIds: readonly string[]
     readonly projectId: string
+    readonly source: GroupMembershipSource
     readonly userId: string
     readonly existing: readonly GroupMembershipRecord[]
   }): readonly GroupMembershipRecord[] {
@@ -547,13 +509,40 @@ export class InMemoryAuthStorage implements AuthStorage {
           projectId: input.projectId,
           userId: input.userId,
           groupId,
-          source: "manual",
+          source: input.source,
           createdAt: input.completedAt,
         })
       )
     }
     return memberships
   }
+  // Directory memberships become exactly `groupIds`. A group the user already holds from another
+  // source keeps that source, and memberships from other sources are never removed.
+  private syncDirectoryGroups(input: {
+    readonly completedAt: Date
+    readonly groupIds?: readonly string[]
+    readonly projectId: string
+    readonly userId: string
+    readonly existing: readonly GroupMembershipRecord[]
+  }): readonly GroupMembershipRecord[] {
+    if (!input.groupIds) {
+      return input.existing
+    }
+
+    const groupIds = normalizeGroupIds(input.groupIds)
+    const stale = [...this.state.groupMemberships.values()].filter(
+      (membership) =>
+        membership.projectId === input.projectId &&
+        membership.userId === input.userId &&
+        membership.source === "directory" &&
+        !groupIds.includes(membership.groupId)
+    )
+    for (const membership of stale) {
+      removeGroupMembershipRecord(this.state, membership)
+    }
+
+    return this.applyGroups({ ...input, groupIds, source: "directory" })
+  }
 
   private createSignInSession(input: {
     readonly projectId: string
@@ -599,16 +588,6 @@ function restoreMap<TKey, TValue>(target: Map<TKey, TValue>, snapshot: Map<TKey,
   }
 }
 
-function hasActiveUsers(state: AuthStorageState, projectId: string): boolean {
-  for (const user of state.users.values()) {
-    if (user.projectId === projectId && user.status === "active") {
-      return true
-    }
-  }
-
-  return false
-}
-
 function assertSignInSessionAudience(
   projectId: string,
   sessionAudience: string,

package/src/storage/auth/types.ts

@@ -4,7 +4,8 @@ import type { AuthorizablePrincipal } from "../../execution/types"
 export type UserStatus = "active" | "suspended"
 export type ServiceAccountStatus = "active" | "suspended"
 export type InvitationStatus = "pending" | "accepted" | "revoked"
-export type GroupMembershipSource = "invitation" | "manual" | "agent"
+/** `directory`: owned by the identity provider, and synced to its groups on every sign-in. */
+export type GroupMembershipSource = "invitation" | "manual" | "agent" | "directory"
 export type DeviceAuthorizationStatus = "pending" | "approved" | "denied" | "consumed"
 export const MAX_PENDING_DEVICE_AUTHORIZATIONS = 100
 
@@ -45,7 +46,8 @@ export interface ServiceAccountGroupMembershipRecord {
   readonly projectId: string
   readonly serviceAccountId: string
   readonly groupId: string
-  readonly source: GroupMembershipSource
+  /** Service accounts never sign in, so no identity provider owns their memberships. */
+  readonly source: Exclude<GroupMembershipSource, "directory">
   readonly createdAt: Date
 }
 
@@ -269,7 +271,7 @@ export interface UpsertAuthServiceAccountGroupMembershipInput {
   readonly projectId: string
   readonly serviceAccountId: string
   readonly groupId: string
-  readonly source: GroupMembershipSource
+  readonly source: ServiceAccountGroupMembershipRecord["source"]
   readonly createdAt?: Date
 }
 
@@ -431,7 +433,6 @@ export interface CompleteMagicLinkSignInInput {
   readonly newUserDisplayName?: string
   readonly newUserAvatarUrl?: string
   readonly allowUserCreationWithoutInvitation?: boolean
-  readonly requireNoActiveUsersForUserCreation?: boolean
   readonly manualGroupIds?: readonly string[]
   readonly session: CompleteAuthSessionInput
 }
@@ -442,15 +443,22 @@ export interface CompleteOidcSignInInput {
   readonly stateHash: string
   readonly completedAt: Date
   readonly subject: string
+  /**
+   * An address the strategy has already decided to trust. Without an identity for `subject`, it
+   * links the user who has this email, or claims this email's invitation for a new user.
+   */
   readonly email: string
-  readonly emailVerified?: boolean
   readonly displayName?: string
   readonly avatarUrl?: string
   readonly claims?: Readonly<Record<string, unknown>>
-  readonly autoLinkByVerifiedEmail?: boolean
   readonly allowUserCreationWithoutInvitation?: boolean
-  readonly requireNoActiveUsersForUserCreation?: boolean
   readonly manualGroupIds?: readonly string[]
+  /**
+   * The groups the identity provider grants this user. When present, the user's `directory`
+   * memberships become exactly these; memberships from any other source are never touched, and a
+   * group the user already has from another source keeps it. Omitted, nothing is synced.
+   */
+  readonly directoryGroupIds?: readonly string[]
   readonly newUserId: string
   readonly session: CompleteAuthSessionInput
 }

package/src/storage/index.ts

@@ -449,8 +449,11 @@ export {
   snapshotObjectReadExecutionLimits,
 } from "./objects"
 export type {
+  AbandonRunSourceMaterializationInput,
   AbandonSourceMaterializationCandidateInput,
   AbandonSourceMaterializationInput,
+  AdoptedSourceMaterialization,
+  AdoptSourceMaterializationInput,
   ApplyMaterializationChunkInput,
   ApplyMaterializationResult,
   AssertSourceMaterializationExecution,
@@ -530,9 +533,9 @@ export type {
   OntologyStorage,
   OntologyVectorStorage,
   ProjectionOntologyCommitIntent,
+  PurgeAbandonedSourceMaterializationsInput,
   PurgePublishedOntologyOutboxInput,
   ReadMaterializationObjectExistenceInput,
-  ReclaimSourceMaterializationInput,
   RescheduleOntologyOutboxLeaseInput,
   SourceActivationWrite,
   SourceReplacementLinkState,
@@ -595,6 +598,7 @@ export {
 export type {
   AdvanceProjectionTelemetryCheckpointInput,
   FailProjectionRunEnqueueInput,
+  FindSupersedingProjectionRunInput,
   FinishProjectionRunInput,
   LinkProjectionRunRecord,
   LinkProjectionTarget,
@@ -616,6 +620,7 @@ export type {
   ProjectionTarget,
   ProjectionTelemetryCheckpoint,
   QueueProjectionRunInput,
+  RecordProjectionAttemptFailureInput,
   RecordProjectionMissingTargetInput,
   StartOrReclaimProjectionRunInput,
   TelemetryProjectionRunRecord,

package/src/storage/ontology/in-memory/sources.ts

@@ -16,8 +16,11 @@ import {
   sourceStageRoots,
 } from "../provider"
 import type {
+  AbandonRunSourceMaterializationInput,
   AbandonSourceMaterializationCandidateInput,
   AbandonSourceMaterializationInput,
+  AdoptedSourceMaterialization,
+  AdoptSourceMaterializationInput,
   AssertSourceMaterializationExecution,
   BeginSourceMaterializationInput,
   CleanupTerminalSourceMaterializationsInput,
@@ -26,7 +29,7 @@ import type {
   MarkSourceMaterializationReadyInput,
   OntologySourceRecord,
   OntologySourceStorage,
-  ReclaimSourceMaterializationInput,
+  PurgeAbandonedSourceMaterializationsInput,
   StageSourceAssertion,
   StageSourceRowsInput,
   StageSourceRowsResult,
@@ -38,6 +41,7 @@ import {
   assertNonblank,
   type InMemoryOntologyState,
   type InMemorySourceMaterialization,
+  type InMemorySourceRoot,
   insertBounded,
   sourceMaterializationKey,
   sourceMaterializationRecord,
@@ -78,7 +82,7 @@ export class InMemoryOntologySourceStorage implements OntologySourceStorage {
       )
       if (nonterminal.length > 0) {
         throw sourceConflict(
-          `Projection run '${input.execution.projectionRunId}' already has a nonterminal source materialization; reclaim it before beginning another.`
+          `Projection run '${input.execution.projectionRunId}' already has a nonterminal source materialization; adopt it before beginning another.`
         )
       }
 
@@ -191,8 +195,42 @@ export class InMemoryOntologySourceStorage implements OntologySourceStorage {
     })
   }
 
+  async adopt(
+    input: AdoptSourceMaterializationInput
+  ): Promise<AdoptedSourceMaterialization | null> {
+    return this.runRootOperation(async () => {
+      assertProjectAndSource(input)
+      assertSourceExecutionIdentity(input.execution.projectionRunId, input.execution.executionToken)
+      assertCanonicalTimestamp(input.adoptedAt, "Source adoptedAt")
+      await this.assertCurrentExecution(input)
+      const [candidate, ...others] = this.findRunCandidates(
+        input.projectId,
+        input.source.projectionId,
+        input.execution.projectionRunId
+      )
+      if (!candidate) return null
+      if (others.length > 0) throw multipleRunCandidates(input.execution.projectionRunId)
+      const [key, materialization] = candidate
+      const adopted: InMemorySourceMaterialization = {
+        ...materialization,
+        executionToken: input.execution.executionToken,
+        // Workers' clocks differ; adoption never moves the record back in time.
+        updatedAt:
+          input.adoptedAt > materialization.updatedAt ? input.adoptedAt : materialization.updatedAt,
+      }
+      this.state.sourceMaterializations.set(key, adopted)
+      return {
+        record: sourceMaterializationRecord(adopted),
+        resumeStagingOrdinal:
+          adopted.status === "ready"
+            ? (adopted.rootCount ?? 0)
+            : Math.max(0, ...adopted.ordinalRoots.keys()),
+      }
+    })
+  }
+
   async abandon(input: AbandonSourceMaterializationCandidateInput): Promise<OntologySourceRecord>
-  async abandon(input: ReclaimSourceMaterializationInput): Promise<OntologySourceRecord | null>
+  async abandon(input: AbandonRunSourceMaterializationInput): Promise<OntologySourceRecord | null>
   async abandon(input: AbandonSourceMaterializationInput): Promise<OntologySourceRecord | null> {
     return this.runRootOperation(async () => {
       assertProjectAndSource(input)
@@ -201,7 +239,7 @@ export class InMemoryOntologySourceStorage implements OntologySourceStorage {
       await this.assertCurrentExecution(input)
       return input.kind === "candidate"
         ? this.abandonCandidate(input)
-        : this.abandonForReclaim(input)
+        : this.abandonRunCandidate(input)
     })
   }
 
@@ -211,18 +249,14 @@ export class InMemoryOntologySourceStorage implements OntologySourceStorage {
     return this.runRootOperation(() => {
       assertNonblank(input.projectId, "Terminal source cleanup project id")
       assertCanonicalTimestamp(input.terminalBefore, "Terminal source cleanup cutoff")
-      if (!Number.isSafeInteger(input.limit) || input.limit <= 0) {
-        throw new MaterializationValidationError(
-          "Terminal source cleanup limit must be a positive safe integer."
-        )
-      }
+      assertCleanupLimit(input.limit)
 
       const candidates: [string, InMemorySourceMaterialization][] = []
       for (const entry of this.state.sourceMaterializations.entries()) {
         const materialization = entry[1]
         if (
           materialization.projectId !== input.projectId ||
-          (materialization.status !== "superseded" && materialization.status !== "abandoned") ||
+          materialization.status !== "superseded" ||
           materialization.terminalAt === null ||
           materialization.terminalAt >= input.terminalBefore
         ) {
@@ -239,42 +273,69 @@ export class InMemoryOntologySourceStorage implements OntologySourceStorage {
         insertBounded(candidates, entry, input.limit, compareTerminalMaterializations)
       }
 
-      let remaining = input.limit
-      let rowsDeleted = 0
-      let materializationsDeleted = 0
-      for (const [key, candidate] of candidates) {
+      return this.deleteRetiredRoots(
+        candidates,
+        input.limit,
+        (root) => !root.active && root.retiredAt !== null && root.retiredAt < input.terminalBefore
+      )
+    })
+  }
+
+  async purgeAbandoned(
+    input: PurgeAbandonedSourceMaterializationsInput
+  ): Promise<CleanupTerminalSourceMaterializationsResult> {
+    return this.runRootOperation(() => {
+      assertNonblank(input.projectId, "Abandoned source purge project id")
+      assertCleanupLimit(input.limit)
+      const abandoned = [...this.state.sourceMaterializations.entries()]
+        .filter(
+          ([, materialization]) =>
+            materialization.projectId === input.projectId && materialization.status === "abandoned"
+        )
+        .sort(compareTerminalMaterializations)
+      return this.deleteRetiredRoots(abandoned, input.limit, () => true)
+    })
+  }
+
+  private deleteRetiredRoots(
+    candidates: readonly [string, InMemorySourceMaterialization][],
+    limit: number,
+    retired: (root: InMemorySourceRoot) => boolean
+  ): CleanupTerminalSourceMaterializationsResult {
+    let remaining = limit
+    let rowsDeleted = 0
+    let materializationsDeleted = 0
+    for (const [key, candidate] of candidates) {
+      if (remaining === 0) break
+      const current = this.state.sourceMaterializations.get(key)
+      if (current !== candidate) continue
+      current.rootOrdinals.clear()
+      current.ordinalRoots.clear()
+      for (const [rootKey, root] of current.roots) {
         if (remaining === 0) break
-        const current = this.state.sourceMaterializations.get(key)
-        if (current !== candidate) continue
-        current.rootOrdinals.clear()
-        current.ordinalRoots.clear()
-        for (const [rootKey, root] of current.roots) {
+        if (!retired(root)) continue
+        for (const entityKey of root.entityKeys) {
           if (remaining === 0) break
-          if (root.active || root.retiredAt === null || root.retiredAt >= input.terminalBefore)
-            continue
-          for (const entityKey of root.entityKeys) {
-            if (remaining === 0) break
-            current.rowsByEntity.delete(entityKey)
-            root.entityKeys.delete(entityKey)
-            rowsDeleted += 1
-            remaining -= 1
-          }
-          if (root.entityKeys.size === 0 && remaining > 0) {
-            current.roots.delete(rootKey)
-            current.rootOrdinals.delete(rootKey)
-            current.ordinalRoots.delete(root.stagingOrdinal)
-            rowsDeleted += 1
-            remaining -= 1
-          }
+          current.rowsByEntity.delete(entityKey)
+          root.entityKeys.delete(entityKey)
+          rowsDeleted += 1
+          remaining -= 1
         }
-        if (current.roots.size === 0 && current.rowsByEntity.size === 0 && remaining > 0) {
-          this.state.sourceMaterializations.delete(key)
-          materializationsDeleted += 1
+        if (root.entityKeys.size === 0 && remaining > 0) {
+          current.roots.delete(rootKey)
+          current.rootOrdinals.delete(rootKey)
+          current.ordinalRoots.delete(root.stagingOrdinal)
+          rowsDeleted += 1
           remaining -= 1
         }
       }
-      return { rowsDeleted, materializationsDeleted }
-    })
+      if (current.roots.size === 0 && current.rowsByEntity.size === 0 && remaining > 0) {
+        this.state.sourceMaterializations.delete(key)
+        materializationsDeleted += 1
+        remaining -= 1
+      }
+    }
+    return { rowsDeleted, materializationsDeleted }
   }
 
   async summarizeTerminal(
@@ -356,26 +417,15 @@ export class InMemoryOntologySourceStorage implements OntologySourceStorage {
     return this.transitionToAbandoned(materialization, input.abandonedAt)
   }
 
-  private abandonForReclaim(input: ReclaimSourceMaterializationInput): OntologySourceRecord | null {
+  private abandonRunCandidate(
+    input: AbandonRunSourceMaterializationInput
+  ): OntologySourceRecord | null {
     const candidates = this.findRunCandidates(
       input.projectId,
       input.source.projectionId,
       input.execution.projectionRunId
     )
-    if (
-      candidates.some(
-        ([, materialization]) => materialization.executionToken === input.execution.executionToken
-      )
-    ) {
-      throw sourceConflict(
-        `Projection run '${input.execution.projectionRunId}' already has a source materialization owned by the current execution.`
-      )
-    }
-    if (candidates.length > 1) {
-      throw sourceConflict(
-        `Projection run '${input.execution.projectionRunId}' has multiple nonterminal source materializations.`
-      )
-    }
+    if (candidates.length > 1) throw multipleRunCandidates(input.execution.projectionRunId)
     const candidate = candidates[0]?.[1]
     return candidate ? this.transitionToAbandoned(candidate, input.abandonedAt) : null
   }
@@ -609,6 +659,20 @@ function assertNotBefore(
   }
 }
 
+function assertCleanupLimit(limit: number): void {
+  if (!Number.isSafeInteger(limit) || limit <= 0) {
+    throw new MaterializationValidationError(
+      "Terminal source cleanup limit must be a positive safe integer."
+    )
+  }
+}
+
+function multipleRunCandidates(projectionRunId: string) {
+  return sourceConflict(
+    `Projection run '${projectionRunId}' has multiple nonterminal source materializations.`
+  )
+}
+
 function compareTerminalMaterializations(
   [, left]: readonly [string, InMemorySourceMaterialization],
   [, right]: readonly [string, InMemorySourceMaterialization]

package/src/storage/ontology/index.ts

@@ -97,8 +97,11 @@ export type {
 } from "./outbox"
 export { ONTOLOGY_OUTBOX_FAILURE_CODES } from "./outbox"
 export type {
+  AbandonRunSourceMaterializationInput,
   AbandonSourceMaterializationCandidateInput,
   AbandonSourceMaterializationInput,
+  AdoptedSourceMaterialization,
+  AdoptSourceMaterializationInput,
   AssertSourceMaterializationExecution,
   AssertSourceMaterializationExecutionInput,
   BeginSourceMaterializationInput,
@@ -109,7 +112,7 @@ export type {
   OntologySourceMaterializationStatus,
   OntologySourceRecord,
   OntologySourceStorage,
-  ReclaimSourceMaterializationInput,
+  PurgeAbandonedSourceMaterializationsInput,
   StageSourceAssertion,
   StageSourceRoot,
   StageSourceRowsInput,

package/src/storage/ontology/provider.ts

@@ -11,6 +11,8 @@ import type {
   ExpectedObjectRevision,
   OntologyLinkRef,
   OntologyObjectRef,
+  ProjectionEntityRef,
+  ProjectionSourceAssertion,
 } from "../../materialization/model"
 import { linkRefKey, objectRefKey, projectionEntityKey } from "../../materialization/refs"
 import type { OntologyCommitOriginSelector, OntologyCommitWrite } from "./commits"
@@ -716,7 +718,6 @@ export function sourceStageRow(row: StageSourceAssertion): SourceStageRow {
 export interface SourceStageRoot {
   readonly root: StageSourceAssertion["root"]
   readonly rootKey: string
-  readonly sortKey: string
   readonly stagingOrdinal: number
   readonly deleted: boolean
 }
@@ -763,7 +764,6 @@ export function sourceStageRoots(
       roots.set(key, {
         root: row.root,
         rootKey: key,
-        sortKey: utf8SortKey(key),
         stagingOrdinal: row.stagingOrdinal,
         deleted,
       })
@@ -965,12 +965,69 @@ export function sourceEntityColumns(entity: StageSourceAssertion["root"]): {
   }
 }
 
-export function utf8SortKey(canonicalKey: string): string {
-  let key = ""
-  for (const byte of new TextEncoder().encode(canonicalKey)) {
-    key += byte.toString(16).padStart(2, "0")
+/** The inverse of `projectionEntityKey`, for providers that store only the canonical key. */
+export function sourceEntityFromKey(key: string): ProjectionEntityRef {
+  const parts: unknown = JSON.parse(key)
+  if (Array.isArray(parts) && parts.every((part) => typeof part === "string")) {
+    if (parts[0] === "object" && parts.length === 3) {
+      return { kind: "object", ref: { objectTypeId: parts[1]!, primaryId: parts[2]! } }
+    }
+    if (parts[0] === "link" && parts.length === 6) {
+      return {
+        kind: "link",
+        ref: {
+          source: { objectTypeId: parts[1]!, primaryId: parts[2]! },
+          linkId: parts[3]!,
+          target: { objectTypeId: parts[4]!, primaryId: parts[5]! },
+        },
+      }
+    }
   }
-  return key
+  throw new MaterializationConflictError(
+    "source-materialization",
+    `Stored source key ${key} is not a canonical entity key.`
+  )
+}
+
+/** What an assertion carries beyond its identity, or null when that is nothing. */
+export function sourceAssertionPayload(
+  assertion: ProjectionSourceAssertion
+): Readonly<Record<string, unknown>> | null {
+  const { kind: _kind, ref: _ref, ...payload } = assertion
+  return Object.keys(payload).length === 0 ? null : payload
+}
+
+/** Rebuilds an assertion from its typed identity columns and its payload. */
+export function sourceAssertionFromColumns(
+  columns: {
+    readonly entity_kind: "object" | "link"
+    readonly object_type_id: string | null
+    readonly primary_id: string | null
+    readonly source_type_id: string | null
+    readonly source_primary_id: string | null
+    readonly link_id: string | null
+    readonly target_type_id: string | null
+    readonly target_primary_id: string | null
+  },
+  payload: unknown
+): ProjectionSourceAssertion {
+  const rest = (payload ?? {}) as Record<string, unknown>
+  if (columns.entity_kind === "object") {
+    return {
+      kind: "object",
+      ref: { objectTypeId: columns.object_type_id!, primaryId: columns.primary_id! },
+      ...rest,
+    } as ProjectionSourceAssertion
+  }
+  return {
+    kind: "link",
+    ref: {
+      source: { objectTypeId: columns.source_type_id!, primaryId: columns.source_primary_id! },
+      linkId: columns.link_id!,
+      target: { objectTypeId: columns.target_type_id!, primaryId: columns.target_primary_id! },
+    },
+    ...rest,
+  } as ProjectionSourceAssertion
 }
 
 export function isExactStagingManifest(