@sixb/core 0.1.21 → 0.1.22

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

@@ -1,9 +1,18 @@
 import type { EffectiveLinkSnapshot, EffectiveObjectSnapshot } from "../../../materialization/model"
 import { hasVectorProfile } from "../../../objects/vectors/query"
+import { uniqueValueKey } from "../../../ontology/unique-values"
+import type {
+  ExactUniqueValueClaim,
+  ExactUniqueValueWrite,
+  UniqueValueRef,
+} from "../../ontology/materializations"
+import { uniqueValueViolation } from "../../ontology/provider-work"
+import type { PreparedUniqueProperty, UniqueValueEntry } from "../../ontology/unique-values"
 import type { StoredObjectVector } from "../../ontology/vectors"
 import type { ObjectReadExecutionLimits } from "../execution-limits"
 import { type LinkBatchKey, type ObjectBatchKey, objectBatchKey } from "../keys"
 import type {
+  CompiledConditionalObjectReadScope,
   CompiledSelectedObjectReadScope,
   CountObjectsInput,
   CountObjectsResult,
@@ -22,6 +31,7 @@ import type {
   QueryObjectsInput,
   QueryObjectsResult,
 } from "../types"
+import { createInMemoryConditionalReader } from "./conditional-reader"
 import {
   compareStrings,
   fullLinkRowKey,
@@ -44,6 +54,13 @@ import { createInMemorySelectedReader } from "./selected-reader"
 export interface InMemoryObjectStorageSnapshot {
   readonly rows: Map<string, Map<string, ObjectRow>>
   readonly links: Map<string, Map<string, ObjectLinkRow>>
+  readonly uniqueValues: Map<string, Map<string, string>>
+  readonly uniqueProperties: Map<string, InMemoryPreparedUniqueProperty>
+}
+
+interface InMemoryPreparedUniqueProperty extends PreparedUniqueProperty {
+  readonly projectId: string
+  readonly preparedAt: string
 }
 
 type VectorReader = (
@@ -84,6 +101,19 @@ interface InMemoryObjectMaterializerAdapter {
     linkId: string,
     visit: (row: ObjectLinkRow) => void
   ): void
+  getUniqueHolder(projectId: string, value: UniqueValueRef): string | null
+  releaseUniqueValue(projectId: string, value: ExactUniqueValueWrite): void
+  /** Throws `UniqueValueViolationError` when another object holds the value. */
+  claimUniqueValue(projectId: string, value: ExactUniqueValueClaim): void
+  listPreparedUniqueProperties(projectId: string): PreparedUniqueProperty[]
+  clearUniqueProperty(projectId: string, objectTypeId: string, propertyId: string): void
+  insertUniqueValues(
+    projectId: string,
+    objectTypeId: string,
+    propertyId: string,
+    entries: readonly UniqueValueEntry[]
+  ): void
+  markUniquePropertyPrepared(input: InMemoryPreparedUniqueProperty): void
 }
 
 const materializerAdapters = new WeakMap<InMemoryObjectStorage, InMemoryObjectMaterializerAdapter>()
@@ -100,6 +130,9 @@ export function getInMemoryObjectMaterializerAdapter(
 export class InMemoryObjectStorage implements ObjectStorage {
   private readonly rows = new Map<string, Map<string, ObjectRow>>()
   private readonly links = new Map<string, Map<string, ObjectLinkRow>>()
+  /** Holder primary ids by value key, for each unique property of a project. */
+  private readonly uniqueValues = new Map<string, Map<string, string>>()
+  private readonly uniqueProperties = new Map<string, InMemoryPreparedUniqueProperty>()
 
   private vectorReader?: VectorReader
 
@@ -130,6 +163,34 @@ export class InMemoryObjectStorage implements ObjectStorage {
           if (row.linkId === linkId) visit(structuredClone(row))
         }
       },
+      getUniqueHolder: (projectId, value) => this.uniqueHolder(projectId, value) ?? null,
+      releaseUniqueValue: (projectId, value) => this.releaseUniqueValue(projectId, value),
+      claimUniqueValue: (projectId, value) => this.claimUniqueValue(projectId, value),
+      listPreparedUniqueProperties: (projectId) =>
+        [...this.uniqueProperties.values()]
+          .filter((prepared) => prepared.projectId === projectId)
+          .map(({ objectTypeId, propertyId, keyKind, keyVersion }) => ({
+            objectTypeId,
+            propertyId,
+            keyKind,
+            keyVersion,
+          })),
+      clearUniqueProperty: (projectId, objectTypeId, propertyId) => {
+        const key = uniquePropertyKey(projectId, objectTypeId, propertyId)
+        this.uniqueValues.delete(key)
+        this.uniqueProperties.delete(key)
+      },
+      insertUniqueValues: (projectId, objectTypeId, propertyId, entries) => {
+        for (const { valueKey, primaryId } of entries) {
+          this.holdUniqueValue(projectId, { objectTypeId, propertyId, valueKey, primaryId })
+        }
+      },
+      markUniquePropertyPrepared: (input) => {
+        this.uniqueProperties.set(
+          uniquePropertyKey(input.projectId, input.objectTypeId, input.propertyId),
+          { ...input }
+        )
+      },
     })
   }
 
@@ -137,6 +198,8 @@ export class InMemoryObjectStorage implements ObjectStorage {
     return {
       rows: cloneObjectBuckets(this.rows),
       links: cloneLinkBuckets(this.links),
+      uniqueValues: cloneUniqueValues(this.uniqueValues),
+      uniqueProperties: new Map(this.uniqueProperties),
     }
   }
 
@@ -150,6 +213,75 @@ export class InMemoryObjectStorage implements ObjectStorage {
     for (const [key, bucket] of cloneLinkBuckets(snapshot.links)) {
       this.links.set(key, bucket)
     }
+
+    this.uniqueValues.clear()
+    for (const [key, holders] of cloneUniqueValues(snapshot.uniqueValues)) {
+      this.uniqueValues.set(key, holders)
+    }
+
+    this.uniqueProperties.clear()
+    for (const [key, prepared] of snapshot.uniqueProperties) {
+      this.uniqueProperties.set(key, prepared)
+    }
+  }
+
+  /** The object holding a unique value, or undefined when none does. */
+  private uniqueHolder(projectId: string, value: UniqueValueRef): string | undefined {
+    return this.uniqueValues
+      .get(uniquePropertyKey(projectId, value.objectTypeId, value.propertyId))
+      ?.get(value.valueKey)
+  }
+
+  private releaseUniqueValue(projectId: string, value: ExactUniqueValueWrite): void {
+    if (this.uniqueHolder(projectId, value) !== value.primaryId) return
+    this.uniqueValues
+      .get(uniquePropertyKey(projectId, value.objectTypeId, value.propertyId))
+      ?.delete(value.valueKey)
+  }
+
+  private claimUniqueValue(projectId: string, claim: ExactUniqueValueClaim): void {
+    this.prepareUniqueProperty(projectId, claim)
+    this.holdUniqueValue(projectId, claim)
+  }
+
+  /**
+   * The in-memory store holds every object, so it builds a property's values the first time a
+   * claim needs them, where SQL stores refuse until `sixb db migrate` built them. A boot
+   * therefore needs no preparation, and a store shared by two ontologies rebuilds what changed.
+   */
+  private prepareUniqueProperty(projectId: string, claim: ExactUniqueValueClaim): void {
+    const key = uniquePropertyKey(projectId, claim.objectTypeId, claim.propertyId)
+    const prepared = this.uniqueProperties.get(key)
+    if (prepared?.keyKind === claim.keyKind && prepared.keyVersion === claim.keyVersion) return
+
+    this.uniqueValues.delete(key)
+    const bucket = this.rows.get(objectRowKey(projectId, claim.objectTypeId))
+    for (const row of bucket?.values() ?? []) {
+      const valueKey = uniqueValueKey(claim.keyKind, row.properties[claim.propertyId])
+      if (valueKey === null) continue
+      this.holdUniqueValue(projectId, { ...claim, valueKey, primaryId: row.primaryId })
+    }
+
+    this.uniqueProperties.set(key, {
+      projectId,
+      objectTypeId: claim.objectTypeId,
+      propertyId: claim.propertyId,
+      keyKind: claim.keyKind,
+      keyVersion: claim.keyVersion,
+      preparedAt: new Date().toISOString(),
+    })
+  }
+
+  private holdUniqueValue(projectId: string, value: ExactUniqueValueWrite): void {
+    const holder = this.uniqueHolder(projectId, value)
+    if (holder !== undefined && holder !== value.primaryId) {
+      throw uniqueValueViolation(value, holder, value.primaryId)
+    }
+
+    const key = uniquePropertyKey(projectId, value.objectTypeId, value.propertyId)
+    const holders = this.uniqueValues.get(key) ?? new Map<string, string>()
+    this.uniqueValues.set(key, holders)
+    holders.set(value.valueKey, value.primaryId)
   }
 
   private getExactObjectRow(
@@ -253,11 +385,21 @@ export class InMemoryObjectStorage implements ObjectStorage {
     )
   }
 
+  createConditionalReadScope(params: {
+    projectId: string
+    scope: CompiledConditionalObjectReadScope
+  }): ObjectReadStorage {
+    return createInMemoryConditionalReader(this.readSource(params.projectId), params.scope, () =>
+      this.queryCapabilities()
+    )
+  }
+
   private readSource(projectId: string): InMemoryReadSource {
     // Keep indexed access live across writes and snapshot restores; do not capture individual buckets.
     return {
       projectId,
       getVector: (ref, profile) => this.vectorReader?.(projectId, ref, profile),
+      allObjects: () => projectObjectRows(this.rows, projectId),
       objectsOfType: (objectTypeId) => [
         ...(this.rows.get(objectRowKey(projectId, objectTypeId))?.values() ?? []),
       ],
@@ -265,7 +407,8 @@ export class InMemoryObjectStorage implements ObjectStorage {
         this.rows.get(objectRowKey(projectId, objectTypeId))?.get(primaryId),
       outgoingLinks: (objectTypeId, primaryId) =>
         this.links.get(sourceLinkBucketKey(projectId, objectTypeId, primaryId))?.values() ?? [],
-      allLinks: () => allLinkRows(this.links),
+      allLinks: () => projectLinkRows(this.links, projectId),
+      uniqueHolder: (value) => this.uniqueHolder(projectId, value),
     }
   }
 
@@ -330,6 +473,14 @@ export class InMemoryObjectStorage implements ObjectStorage {
     return bucket.get(params.primaryId) ?? null
   }
 
+  async getByUniqueValue(
+    params: Parameters<ObjectReadStorage["getByUniqueValue"]>[0]
+  ): Promise<ObjectRow | null> {
+    const holder = this.uniqueHolder(params.projectId, params)
+    if (holder === undefined) return null
+    return this.getByPrimaryId({ ...params, primaryId: holder })
+  }
+
   async selectsObjectProperties(
     params: Parameters<ObjectReadStorage["selectsObjectProperties"]>[0]
   ): Promise<readonly boolean[]> {
@@ -588,6 +739,16 @@ function cloneObjectBuckets(
   return clone
 }
 
+function uniquePropertyKey(projectId: string, objectTypeId: string, propertyId: string): string {
+  return JSON.stringify([projectId, objectTypeId, propertyId])
+}
+
+function cloneUniqueValues(
+  values: Map<string, Map<string, string>>
+): Map<string, Map<string, string>> {
+  return new Map([...values].map(([key, holders]) => [key, new Map(holders)]))
+}
+
 function cloneLinkBuckets(
   links: Map<string, Map<string, ObjectLinkRow>>
 ): Map<string, Map<string, ObjectLinkRow>> {
@@ -601,6 +762,27 @@ function cloneLinkBuckets(
   return clone
 }
 
+function* projectObjectRows(
+  buckets: ReadonlyMap<string, ReadonlyMap<string, ObjectRow>>,
+  projectId: string
+): Iterable<ObjectRow> {
+  const prefix = objectRowProjectPrefix(projectId)
+  for (const [key, bucket] of buckets) {
+    if (key.startsWith(prefix)) yield* bucket.values()
+  }
+}
+
+/** Link buckets are keyed like object buckets, project first. */
+function* projectLinkRows(
+  buckets: ReadonlyMap<string, ReadonlyMap<string, ObjectLinkRow>>,
+  projectId: string
+): Iterable<ObjectLinkRow> {
+  const prefix = objectRowProjectPrefix(projectId)
+  for (const [key, bucket] of buckets) {
+    if (key.startsWith(prefix)) yield* bucket.values()
+  }
+}
+
 function* allLinkRows(
   buckets: ReadonlyMap<string, ReadonlyMap<string, ObjectLinkRow>>
 ): Iterable<ObjectLinkRow> {

package/src/storage/objects/index.ts

@@ -12,12 +12,18 @@ export {
   objectBatchKey,
   objectLinkCursor,
 } from "./keys"
-export { assertObjectReaderProject, compileSelectedObjectReadScope } from "./read-scope"
+export {
+  assertObjectReaderProject,
+  compileConditionalObjectReadScope,
+  compileSelectedObjectReadScope,
+} from "./read-scope"
 export type {
+  CompiledConditionalObjectReadScope,
   CompiledObjectReadObjectSelection,
   CompiledObjectReadRoot,
   CompiledObjectReadStep,
   CompiledSelectedObjectReadScope,
+  ConditionalObjectReadScope,
   CountObjectsInput,
   CountObjectsResult,
   ExistsObjectsInput,
@@ -36,6 +42,7 @@ export type {
   ObjectQueryCapabilityMap,
   ObjectQueryScalarOperation,
   ObjectQueryScalarOperations,
+  ObjectReadCondition,
   ObjectReadLinkDefinitionSelection,
   ObjectReadLinkSelection,
   ObjectReadNode,
@@ -45,6 +52,7 @@ export type {
   ObjectReadStorage,
   ObjectRow,
   ObjectRowLinks,
+  ObjectRowUsers,
   ObjectStorage,
   QueryObjectLinksInput,
   QueryObjectLinksResult,

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),