@sixb/core 0.1.20 → 0.1.22

package/src/storage/objects/read-scope.ts

@@ -1,8 +1,14 @@
+import { compareStrings, getInvalidJsonValueReason } from "../../json"
+import type { ObjectQueryPredicate, QueryScalarKind } from "../../objects/query"
+import { isCurrentUser } from "../../ontology/user-ref"
 import type {
+  CompiledConditionalObjectReadScope,
   CompiledObjectReadObjectSelection,
   CompiledObjectReadRoot,
   CompiledObjectReadStep,
   CompiledSelectedObjectReadScope,
+  ConditionalObjectReadScope,
+  ObjectReadCondition,
   ObjectReadLinkDefinitionSelection,
   ObjectReadLinkSelection,
   ObjectReadNode,
@@ -498,6 +504,191 @@ function reserveCount(current: number, count: number, limit: number, message: st
   return current + count
 }
 
+/** Admission bounds of a raw conditional scope, checked while its predicates are captured. */
+const CONDITIONAL_READ_SCOPE_LIMITS = Object.freeze({
+  maxPredicateDepth: 32,
+  maxPredicateNodes: 4_096,
+})
+
+const SCALAR_KINDS: ReadonlySet<string> = new Set<QueryScalarKind>([
+  "string",
+  "uuid",
+  "boolean",
+  "integer",
+  "double",
+  "decimal",
+  "date",
+  "timestamp",
+  "userRef",
+])
+
+/**
+ * Validate, detach and freeze a conditional scope exactly once.
+ *
+ * Core validated each predicate as a filter over its type and bound `currentUser()` to the reader,
+ * so this checks only the shape providers compile: an IR predicate made of JSON values, one per
+ * concrete type. A placeholder left unbound would otherwise reach SQL as an ordinary value.
+ */
+export function compileConditionalObjectReadScope(
+  rawScope: ConditionalObjectReadScope
+): CompiledConditionalObjectReadScope {
+  const value: unknown = rawScope
+  if (!isRecord(value) || value.kind !== "conditional") {
+    throw invalidScope("scope must be a conditional scope with a conditions array")
+  }
+
+  const source = captureArray(value.conditions, "conditions")
+  const budget = { nodes: 0 }
+  const objectTypeIds = new Set<string>()
+  const conditions: ObjectReadCondition[] = []
+
+  for (let index = 0; index < source.length; index += 1) {
+    const path = `conditions[${index}]`
+    const condition = source.value[index]
+    if (!isRecord(condition)) {
+      throw invalidScope(`${path} must contain an object type and a predicate`)
+    }
+
+    const objectTypeId = nonEmptyString(condition.objectTypeId, `${path}.objectTypeId`)
+    // A padded id names no type, and would leave the type it was meant for unconditioned.
+    if (objectTypeId.trim() !== objectTypeId) {
+      throw invalidScope(`${path}.objectTypeId must not start or end with whitespace`)
+    }
+    if (objectTypeIds.has(objectTypeId)) {
+      throw invalidScope(`${path} repeats the condition on '${objectTypeId}'`)
+    }
+    objectTypeIds.add(objectTypeId)
+
+    const predicate = capturePredicate(condition.predicate, `${path}.predicate`, 0, budget)
+    conditions.push(Object.freeze({ objectTypeId, predicate }))
+  }
+
+  conditions.sort((left, right) => compareStrings(left.objectTypeId, right.objectTypeId))
+
+  return Object.freeze({
+    kind: "conditional",
+    conditions: Object.freeze(conditions),
+  }) as CompiledConditionalObjectReadScope
+}
+
+function capturePredicate(
+  value: unknown,
+  path: string,
+  depth: number,
+  budget: { nodes: number }
+): ObjectQueryPredicate {
+  if (depth > CONDITIONAL_READ_SCOPE_LIMITS.maxPredicateDepth) {
+    throw invalidScope(
+      `${path} exceeds the maximum predicate depth of ${CONDITIONAL_READ_SCOPE_LIMITS.maxPredicateDepth}`
+    )
+  }
+
+  budget.nodes += 1
+  if (budget.nodes > CONDITIONAL_READ_SCOPE_LIMITS.maxPredicateNodes) {
+    throw invalidScope(
+      `scope exceeds the maximum of ${CONDITIONAL_READ_SCOPE_LIMITS.maxPredicateNodes} predicate nodes`
+    )
+  }
+
+  if (!isRecord(value)) throw invalidScope(`${path} must be a query predicate`)
+
+  const op = value.op
+  switch (op) {
+    case "and":
+    case "or": {
+      const items = captureArray(value.items, `${path}.items`)
+      if (items.length === 0) throw invalidScope(`${path}.items must not be empty`)
+
+      const captured: ObjectQueryPredicate[] = []
+      for (let index = 0; index < items.length; index += 1) {
+        captured.push(
+          capturePredicate(items.value[index], `${path}.items[${index}]`, depth + 1, budget)
+        )
+      }
+      return Object.freeze({ op, items: Object.freeze(captured) })
+    }
+
+    case "not":
+      return Object.freeze({
+        op,
+        item: capturePredicate(value.item, `${path}.item`, depth + 1, budget),
+      })
+
+    case "constant":
+      return Object.freeze({ op, value: captureBoolean(value.value, `${path}.value`) })
+
+    case "exists": {
+      const propertyId = nonEmptyString(value.propertyId, `${path}.propertyId`)
+      return Object.freeze({ op, propertyId, value: captureBoolean(value.value, `${path}.value`) })
+    }
+
+    case "eq":
+    case "neq":
+    case "lt":
+    case "lte":
+    case "gt":
+    case "gte":
+    case "contains": {
+      const propertyId = nonEmptyString(value.propertyId, `${path}.propertyId`)
+      const compared = capturePredicateValue(value.value, `${path}.value`)
+      const scalarKind = captureScalarKind(value.scalarKind, `${path}.scalarKind`)
+      return Object.freeze({ op, propertyId, value: compared, ...scalarKind })
+    }
+
+    case "in": {
+      const propertyId = nonEmptyString(value.propertyId, `${path}.propertyId`)
+      const source = captureArray(value.values, `${path}.values`)
+      if (source.length === 0) throw invalidScope(`${path}.values must not be empty`)
+
+      const values: unknown[] = []
+      for (let index = 0; index < source.length; index += 1) {
+        values.push(capturePredicateValue(source.value[index], `${path}.values[${index}]`))
+      }
+      const scalarKind = captureScalarKind(value.scalarKind, `${path}.scalarKind`)
+      return Object.freeze({ op, propertyId, values: Object.freeze(values), ...scalarKind })
+    }
+
+    default:
+      throw invalidScope(`${path}.op must be a query predicate operator`)
+  }
+}
+
+function capturePredicateValue(value: unknown, path: string): unknown {
+  const reason = getInvalidJsonValueReason(value, path)
+  if (reason) throw invalidScope(`${path} must be a JSON value; ${reason}`)
+
+  const detached = JSON.parse(JSON.stringify(value)) as unknown
+  if (containsCurrentUser(detached)) {
+    throw invalidScope(`${path} holds currentUser(); bind the condition to its reader first`)
+  }
+  return deepFreeze(detached)
+}
+
+function captureBoolean(value: unknown, path: string): boolean {
+  if (typeof value !== "boolean") throw invalidScope(`${path} must be a boolean`)
+  return value
+}
+
+function captureScalarKind(value: unknown, path: string): { scalarKind?: QueryScalarKind } {
+  if (value === undefined) return {}
+  if (typeof value !== "string" || !SCALAR_KINDS.has(value)) {
+    throw invalidScope(`${path} must be a query scalar kind`)
+  }
+  return { scalarKind: value as QueryScalarKind }
+}
+
+function containsCurrentUser(value: unknown): boolean {
+  if (isCurrentUser(value)) return true
+  if (Array.isArray(value)) return value.some(containsCurrentUser)
+  return isRecord(value) && Object.values(value).some(containsCurrentUser)
+}
+
+function deepFreeze<T>(value: T): T {
+  if (!isRecord(value)) return value
+  for (const child of Object.values(value)) deepFreeze(child)
+  return Object.freeze(value)
+}
+
 /** Fail closed when a project-bound selected reader is accidentally reused across projects. */
 export function assertObjectReaderProject(
   expectedProjectId: string,

package/src/storage/objects/types.ts

@@ -7,6 +7,8 @@ import type {
   QueryScalarKind,
 } from "../../objects/query"
 import type { Redactions } from "../../security/types"
+import type { UserProfile } from "../../users"
+import type { UniqueValueRef } from "../ontology/materializations"
 import type { ObjectReadExecutionLimits } from "./execution-limits"
 import type { LinkBatchKey, ObjectBatchKey } from "./keys"
 
@@ -40,11 +42,25 @@ export interface ObjectRow {
    * Populated by the authorized object reader; storage providers never read or write it.
    */
   redactions?: Redactions
+  /**
+   * Profiles of the members an `expand` query node names, keyed by `ref.user()` property id.
+   *
+   * Populated by the authorized object reader from the member directory; storage providers never
+   * read or write it.
+   */
+  users?: ObjectRowUsers
 }
 
 /** Per-link expansion result keyed by link id (see {@link ObjectQueryExpand}). */
 export type ObjectRowLinks = Record<string, ExpandedLinkValue>
 
+/**
+ * Expanded profiles keyed by property id: one profile (or `null` when the property is empty or
+ * names no member) for a `ref.user()` property, the members found in order for an array of them.
+ * A property is absent when the reader may not view the member directory or cannot read its value.
+ */
+export type ObjectRowUsers = Record<string, UserProfile | readonly UserProfile[] | null>
+
 /**
  * The value attached under one expanded link.
  *
@@ -167,6 +183,42 @@ export interface CompiledObjectReadStep {
   readonly propertyIds: readonly string[]
 }
 
+/**
+ * Objects narrowed by a condition on their concrete type.
+ *
+ * An object of a listed type is visible when its predicate matches it; objects of other types are
+ * unaffected. A link is visible when both its endpoints are. Hidden objects and links behave
+ * exactly like missing ones, and every read sees the live rows.
+ */
+export interface ConditionalObjectReadScope {
+  readonly kind: "conditional"
+  readonly conditions: readonly ObjectReadCondition[]
+}
+
+export interface ObjectReadCondition {
+  /** A concrete type: a condition granted on a supertype is listed once per concrete type. */
+  readonly objectTypeId: string
+  /**
+   * Validated by core as a filter over the type, with `scalarKind` resolved and `currentUser()`
+   * bound to the reader. Providers compile it with their own predicate compiler.
+   */
+  readonly predicate: ObjectQueryPredicate
+}
+
+/**
+ * Detached and deeply immutable conditions, one per concrete type, ordered by type id.
+ *
+ * Only `compileConditionalObjectReadScope` returns one, so a raw scope cannot reach a provider
+ * unchecked. The brand exists in types alone. Its key is a string, not a `unique symbol`: a
+ * symbol declared here is a different symbol in the emitted declarations, and packages that see
+ * both would find their providers incompatible.
+ */
+export interface CompiledConditionalObjectReadScope {
+  readonly "~compiledConditionalObjectReadScope": true
+  readonly kind: "conditional"
+  readonly conditions: readonly ObjectReadCondition[]
+}
+
 export type ObjectQueryCapabilityMap<T extends string> = Readonly<Partial<Record<T, boolean>>>
 
 export type ObjectQueryScalarOperation = "equality" | "ordering"
@@ -288,6 +340,12 @@ export interface ObjectReadStorage {
     primaryId: string
   }): Promise<ObjectRow | null>
 
+  /**
+   * The object holding a value of a unique property, by the key core computes for it, or null. A
+   * selected reader answers null unless that object is in its scope and selects the property.
+   */
+  getByUniqueValue(params: { projectId: string } & UniqueValueRef): Promise<ObjectRow | null>
+
   /**
    * Check whether each requested property belongs to the reader's selection.
    *
@@ -355,13 +413,22 @@ export interface ObjectReadStorage {
   }): Promise<{ objects: readonly ObjectRow[]; hasMore: boolean; total: number }>
 }
 
-/** Provider capability for enforcing a finite, precompiled object-read selection. */
+/** Provider capability for enforcing a precompiled object-read scope on every read. */
 export interface ObjectReadScopeFactory {
   createSelectedReadScope(params: {
     projectId: string
     scope: CompiledSelectedObjectReadScope
     limits: ObjectReadExecutionLimits
   }): ObjectReadStorage
+
+  /**
+   * Read only the objects and links a conditional scope leaves visible. The provider applies the
+   * conditions inside each statement, so filters, ordering, limits and totals run after them.
+   */
+  createConditionalReadScope(params: {
+    projectId: string
+    scope: CompiledConditionalObjectReadScope
+  }): ObjectReadStorage
 }
 
 /** Latest-state projection storage, including selected reads and trusted internal primitives. */

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

@@ -22,6 +22,7 @@ import {
   type InMemoryOntologyStorageTestingAdapter,
   registerInMemoryOntologyStorageTestingAdapter,
 } from "./testing"
+import { InMemoryOntologyUniqueValueStorage } from "./unique-values"
 
 export type InMemoryOntologyStorageSnapshot = InMemoryOntologyState
 
@@ -45,6 +46,7 @@ export class InMemoryOntologyStorage implements OntologyStorage {
   readonly materializations: InMemoryOntologyMaterializationStorage
   readonly replacementPlans: InMemoryOntologyReplacementPlanStorage
   readonly outbox: InMemoryOntologyOutboxStorage
+  readonly uniqueValues: InMemoryOntologyUniqueValueStorage
   private testHooks: InMemoryOntologyStorageTestHooks = {}
   private readonly testingAdapter: InMemoryOntologyStorageTestingAdapter = {
     setTestHooks: (hooks) => this.setTestHooks(hooks),
@@ -81,6 +83,7 @@ export class InMemoryOntologyStorage implements OntologyStorage {
       options.runRootOperation,
       options.readExecution
     )
+    this.uniqueValues = new InMemoryOntologyUniqueValueStorage(objects, options.runRootOperation)
     const hooks: InMemoryOntologyStorageTestHooks = {
       beforeRead: (boundary) => this.testHooks.beforeRead?.(boundary),
       beforeWrite: (boundary, ordinal) => this.testHooks.beforeWrite?.(boundary, ordinal),

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

@@ -31,6 +31,7 @@ import type {
   AppliedMaterialization,
   ApplyMaterializationInput,
   ApplyMaterializationResult,
+  ExactUniqueValueWrite,
   ExpectedSourceRevision,
   ExpectedTimeseriesPointRevision,
   FinalizeMaterializationInput,
@@ -52,6 +53,7 @@ import type {
   StoredTelemetryPoint,
   StreamMaterializationStateInput,
   StreamMaterializationVectorChangesInput,
+  UniqueValueRef,
 } from "../materializations"
 import {
   assertExpectedLinkRevision,
@@ -286,6 +288,18 @@ export class InMemoryOntologyMaterializationStorage implements OntologyMateriali
         yield { objects: [], links: [], linkScopes: [value], points: [] }
       }
 
+      const uniqueHolders = this.uniqueHolders(session, request.uniqueValues ?? [])
+      for (let offset = 0; offset < uniqueHolders.length; offset += input.pageRows) {
+        this.requireSession(input.session)
+        yield {
+          objects: [],
+          links: [],
+          linkScopes: [],
+          points: [],
+          uniqueHolders: uniqueHolders.slice(offset, offset + input.pageRows),
+        }
+      }
+
       const requestedPoints = uniqueSorted(
         request.points,
         (point) => telemetryPointKey(point.series, point.at),
@@ -503,6 +517,14 @@ export class InMemoryOntologyMaterializationStorage implements OntologyMateriali
         this.assertLinkSync(item.expected, projectId)
         getInMemoryObjectMaterializerAdapter(this.objects).applyExactLink(item.row, projectId)
       })
+    for (const item of chunk.unique.releases)
+      write("unique.release", () => {
+        getInMemoryObjectMaterializerAdapter(this.objects).releaseUniqueValue(projectId, item)
+      })
+    for (const item of chunk.unique.claims)
+      write("unique.claim", () => {
+        getInMemoryObjectMaterializerAdapter(this.objects).claimUniqueValue(projectId, item)
+      })
     for (const item of chunk.timeseries.pointUpserts)
       write("timeseries.point.upsert", () => {
         this.assertPoint(item.expected, projectId)
@@ -779,6 +801,19 @@ export class InMemoryOntologyMaterializationStorage implements OntologyMateriali
     }
   }
 
+  private uniqueHolders(
+    session: SessionState,
+    values: readonly UniqueValueRef[]
+  ): ExactUniqueValueWrite[] {
+    const adapter = getInMemoryObjectMaterializerAdapter(this.objects)
+    const holders: ExactUniqueValueWrite[] = []
+    for (const value of values) {
+      const primaryId = adapter.getUniqueHolder(session.header.commit.projectId, value)
+      if (primaryId !== null) holders.push({ ...value, primaryId })
+    }
+    return holders
+  }
+
   private linkSlotState(
     session: SessionState,
     source: OntologyObjectRef,

package/src/storage/ontology/in-memory/replacement-plans.ts

@@ -140,6 +140,10 @@ export function touchPlanItem(touches: InMemoryCommitTouches, item: Materializat
     case "link-slot-override-delete":
       touches.scopes.add(linkScopeKey(item.value.ref.source, item.value.ref.linkId))
       return
+    // A plan reads no unique value: its claims are checked when they apply.
+    case "unique-value-release":
+    case "unique-value-claim":
+      return
   }
 }
 

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

@@ -19,6 +19,7 @@ import type {
   AbandonRunSourceMaterializationInput,
   AbandonSourceMaterializationCandidateInput,
   AbandonSourceMaterializationInput,
+  ActiveOntologySource,
   AdoptedSourceMaterialization,
   AdoptSourceMaterializationInput,
   AssertSourceMaterializationExecution,
@@ -26,6 +27,7 @@ import type {
   CleanupTerminalSourceMaterializationsInput,
   CleanupTerminalSourceMaterializationsResult,
   GetActiveOntologySourceInput,
+  ListActiveOntologySourcesInput,
   MarkSourceMaterializationReadyInput,
   OntologySourceRecord,
   OntologySourceStorage,
@@ -193,6 +195,27 @@ export class InMemoryOntologySourceStorage implements OntologySourceStorage {
     })
   }
 
+  async listActive(
+    input: ListActiveOntologySourcesInput
+  ): Promise<readonly ActiveOntologySource[]> {
+    return this.runRootOperation(() => {
+      assertNonblank(input.projectId, "Source project id")
+
+      const active: ActiveOntologySource[] = []
+      for (const materialization of this.state.sourceMaterializations.values()) {
+        if (materialization.projectId !== input.projectId) continue
+        if (materialization.status !== "active") continue
+        active.push({
+          source: { projectionId: materialization.source.projectionId },
+          datasetVersion: { ...materialization.datasetVersion },
+          projectionRevision: materialization.projectionRevision,
+        })
+      }
+
+      return active
+    })
+  }
+
   async adopt(
     input: AdoptSourceMaterializationInput
   ): Promise<AdoptedSourceMaterialization | null> {

package/src/storage/ontology/in-memory/unique-values.ts

@@ -0,0 +1,62 @@
+import {
+  getInMemoryObjectMaterializerAdapter,
+  type InMemoryObjectStorage,
+} from "../../objects/in-memory"
+import type {
+  OntologyUniqueValueStorage,
+  PreparedUniqueProperty,
+  UniqueValueEntry,
+} from "../unique-values"
+
+/** Unique values live with the in-memory objects, so a transaction snapshot covers both. */
+export class InMemoryOntologyUniqueValueStorage implements OntologyUniqueValueStorage {
+  constructor(
+    private readonly objects: InMemoryObjectStorage,
+    private readonly runRootOperation: <T>(run: () => Promise<T> | T) => Promise<T>
+  ) {}
+
+  /** In-memory transactions already run one at a time. */
+  async lockPreparation(_input: { readonly projectId: string }): Promise<void> {}
+
+  async listPrepared(input: {
+    readonly projectId: string
+  }): Promise<readonly PreparedUniqueProperty[]> {
+    return this.runRootOperation(() => this.adapter().listPreparedUniqueProperties(input.projectId))
+  }
+
+  async clear(input: {
+    readonly projectId: string
+    readonly objectTypeId: string
+    readonly propertyId: string
+  }): Promise<void> {
+    await this.runRootOperation(() =>
+      this.adapter().clearUniqueProperty(input.projectId, input.objectTypeId, input.propertyId)
+    )
+  }
+
+  async insert(input: {
+    readonly projectId: string
+    readonly objectTypeId: string
+    readonly propertyId: string
+    readonly entries: readonly UniqueValueEntry[]
+  }): Promise<void> {
+    await this.runRootOperation(() =>
+      this.adapter().insertUniqueValues(
+        input.projectId,
+        input.objectTypeId,
+        input.propertyId,
+        input.entries
+      )
+    )
+  }
+
+  async markPrepared(
+    input: PreparedUniqueProperty & { readonly projectId: string; readonly preparedAt: string }
+  ): Promise<void> {
+    await this.runRootOperation(() => this.adapter().markUniquePropertyPrepared(input))
+  }
+
+  private adapter() {
+    return getInMemoryObjectMaterializerAdapter(this.objects)
+  }
+}

package/src/storage/ontology/index.ts

@@ -3,6 +3,7 @@ import type { OntologyMaterializationStorage } from "./materializations"
 import type { OntologyOutboxStorage } from "./outbox"
 import type { OntologyReplacementPlanStorage } from "./replacement-plans"
 import type { OntologySourceStorage } from "./sources"
+import type { OntologyUniqueValueStorage } from "./unique-values"
 import type { OntologyVectorIndexingStorage } from "./vector-indexing"
 import type { OntologyVectorStorage } from "./vectors"
 
@@ -37,6 +38,8 @@ export type {
   ExactObjectOverrideDelete,
   ExactObjectOverrideWrite,
   ExactTimeseriesPointWrite,
+  ExactUniqueValueClaim,
+  ExactUniqueValueWrite,
   ExpectedSourceRevision,
   ExpectedTimeseriesPointRevision,
   FinalizeMaterializationInput,
@@ -74,6 +77,7 @@ export type {
   StoredTelemetryPoint,
   StreamMaterializationStateInput,
   StreamMaterializationVectorChangesInput,
+  UniqueValueRef,
 } from "./materializations"
 export type {
   ClaimedOntologyOutboxRow,
@@ -107,6 +111,7 @@ export type {
   AbandonRunSourceMaterializationInput,
   AbandonSourceMaterializationCandidateInput,
   AbandonSourceMaterializationInput,
+  ActiveOntologySource,
   AdoptedSourceMaterialization,
   AdoptSourceMaterializationInput,
   AssertSourceMaterializationExecution,
@@ -115,6 +120,7 @@ export type {
   CleanupTerminalSourceMaterializationsInput,
   CleanupTerminalSourceMaterializationsResult,
   GetActiveOntologySourceInput,
+  ListActiveOntologySourcesInput,
   MarkSourceMaterializationReadyInput,
   OntologySourceMaterializationStatus,
   OntologySourceRecord,
@@ -128,6 +134,11 @@ export type {
   StoredSourceLinkAssertion,
   StoredSourceObjectAssertion,
 } from "./sources"
+export type {
+  OntologyUniqueValueStorage,
+  PreparedUniqueProperty,
+  UniqueValueEntry,
+} from "./unique-values"
 
 export type { ObjectVectorState, OntologyVectorStorage, StoredObjectVector } from "./vectors"
 
@@ -139,6 +150,7 @@ export interface OntologyStorage {
   readonly materializations: OntologyMaterializationStorage
   readonly replacementPlans: OntologyReplacementPlanStorage
   readonly outbox: OntologyOutboxStorage
+  readonly uniqueValues: OntologyUniqueValueStorage
 }
 
 export type {

package/src/storage/ontology/materializations.ts

@@ -19,6 +19,7 @@ import type {
   TelemetryCommitResult,
   TelemetrySeriesRef,
 } from "../../materialization/model"
+import type { UniqueValueKind } from "../../ontology/unique-values"
 import type { OntologyCommitRecord, OntologyCommitWrite } from "./commits"
 import type { OntologyMaterializationEventDraft } from "./outbox"
 import type { StoredSourceLinkAssertion, StoredSourceObjectAssertion } from "./sources"
@@ -61,6 +62,27 @@ export interface ExpectedTimeseriesPointRevision {
   readonly lastCommitId: string | null
 }
 
+/** One value of a unique property, as the key core computes for it. */
+export interface UniqueValueRef {
+  readonly objectTypeId: string
+  readonly propertyId: string
+  readonly valueKey: string
+}
+
+/** A unique value and the object that gives it up or takes it. */
+export interface ExactUniqueValueWrite extends UniqueValueRef {
+  readonly primaryId: string
+}
+
+/**
+ * A unique value an object takes, with how its key was computed. Storage refuses it unless the
+ * property's stored values were prepared with that same key kind and version.
+ */
+export interface ExactUniqueValueClaim extends ExactUniqueValueWrite {
+  readonly keyKind: UniqueValueKind
+  readonly keyVersion: number
+}
+
 export interface MaterializationObjectState {
   readonly ref: OntologyObjectRef
   readonly source: StoredSourceObjectAssertion | null
@@ -100,6 +122,8 @@ export interface MaterializationStatePage {
   readonly links: readonly MaterializationLinkState[]
   readonly linkScopes: readonly MaterializationLinkScopeState[]
   readonly points: readonly StoredTelemetryPoint[]
+  /** The objects holding requested unique values; a value no object holds is left out. */
+  readonly uniqueHolders?: readonly ExactUniqueValueWrite[]
 }
 
 export interface SourceReplacementObjectState extends Omit<MaterializationObjectState, "source"> {
@@ -125,6 +149,8 @@ export interface MaterializationStateRequestChunk {
     readonly series: TelemetrySeriesRef
     readonly at: string
   }[]
+  /** Unique values whose holders to read. */
+  readonly uniqueValues?: readonly UniqueValueRef[]
 }
 
 /**
@@ -314,12 +340,16 @@ export type MaterializationPlanWorkItem =
   | { readonly kind: "link-upsert"; readonly value: ExactEffectiveLinkWrite }
   | { readonly kind: "link-delete"; readonly value: ExactEffectiveLinkDelete }
   | { readonly kind: "point-upsert"; readonly value: ExactTimeseriesPointWrite }
+  /** Drops the value's holder row if it still names this object; a missing row is no conflict. */
+  | { readonly kind: "unique-value-release"; readonly value: ExactUniqueValueWrite }
+  /** Rejects a value another object holds once every release of the commit has applied. */
+  | { readonly kind: "unique-value-claim"; readonly value: ExactUniqueValueClaim }
 
 /**
  * Safe physical phases shared by the core planner and provider validation through
  * {@link materializationApplyPhase}.
  */
-export type MaterializationApplyPhase = 0 | 1 | 2 | 3 | 4 | 5
+export type MaterializationApplyPhase = 0 | 1 | 2 | 3 | 4 | 5 | 6
 
 export interface MaterializationPlanWorkRecord {
   readonly kind: "plan"
@@ -344,6 +374,7 @@ export function materializationApplyPhase(
     case "link-override-delete":
     case "link-slot-override-upsert":
     case "link-slot-override-delete":
+    case "unique-value-release":
       return 0
     case "point-upsert":
       return 1
@@ -355,6 +386,9 @@ export function materializationApplyPhase(
       return 4
     case "link-upsert":
       return 5
+    // Last, after every release of the commit in any chunk: values can move between objects.
+    case "unique-value-claim":
+      return 6
   }
 }