@sixb/core 0.1.12 → 0.1.13

package/src/materializer/edits/user-refs.ts

@@ -0,0 +1,115 @@
+/**
+ * Existence checks for `userRef` values written by managed edits.
+ *
+ * Auth storage is read once per commit, before the serializable transaction opens: every user id
+ * the operations carry is looked up, deduplicated, and the statuses travel into the synchronous
+ * edit pass. There, an operation may only introduce a user that exists and is active. A value the
+ * object already held is never re-checked, so suspending a user leaves the objects that reference
+ * them writable. Users are never deleted, so a check at write time stays true for existence.
+ */
+import type { JsonValue } from "../../json"
+import { MaterializationValidationError } from "../../materialization/errors"
+import type { OntologyEditOperation } from "../../materialization/model"
+import type { OntologyRegistry } from "../../ontology"
+import { collectUserRefIds, userReferenceProblem } from "../../ontology/user-ref"
+import type { UserStatus } from "../../storage/auth/types"
+import type { MaterializerContext } from "../context"
+
+/** Statuses of the users a commit's operations reference; `null` marks an unknown id. */
+export type ReferencedUsers =
+  | { readonly kind: "loaded"; readonly statuses: ReadonlyMap<string, UserStatus | null> }
+  | { readonly kind: "unavailable" }
+
+const NO_REFERENCED_USERS: ReferencedUsers = { kind: "loaded", statuses: new Map() }
+
+export async function loadReferencedUsers(
+  context: Pick<MaterializerContext, "projectId" | "ontology" | "storage">,
+  operations: readonly OntologyEditOperation[]
+): Promise<ReferencedUsers> {
+  const ids = new Set<string>()
+  for (const operation of operations) {
+    switch (operation.kind) {
+      case "object.create":
+      case "object.upsert":
+        collectObjectUserRefIds(
+          context.ontology,
+          operation.ref.objectTypeId,
+          operation.properties,
+          ids
+        )
+        break
+      case "object.patch":
+        collectObjectUserRefIds(context.ontology, operation.ref.objectTypeId, operation.set, ids)
+        break
+      default:
+        break
+    }
+  }
+  if (ids.size === 0) return NO_REFERENCED_USERS
+
+  const users = context.storage.auth?.users
+  if (!users) return { kind: "unavailable" }
+  const entries = await Promise.all(
+    [...ids].map(async (id) => {
+      const user = await users.getById({ projectId: context.projectId, id })
+      return [id, user?.status ?? null] as const
+    })
+  )
+  return { kind: "loaded", statuses: new Map(entries) }
+}
+
+/**
+ * Reject user references an object operation introduces unless the user exists and is active.
+ *
+ * `before` is the effective object the operation started from; ids it already held under the same
+ * property are accepted as they are.
+ */
+export function assertIntroducedUsersActive(
+  ontology: OntologyRegistry,
+  objectTypeId: string,
+  before: Readonly<Record<string, JsonValue>> | undefined,
+  after: Readonly<Record<string, JsonValue>>,
+  users: ReferencedUsers
+): void {
+  const objectType = ontology.resolveObjectType(objectTypeId)
+  const valueTypesById = ontology.getValueTypesById()
+  for (const property of objectType.properties) {
+    const introduced = collectUserRefIds(
+      property.schema,
+      after[property.id],
+      valueTypesById,
+      new Set()
+    )
+    if (introduced.size === 0) continue
+    const held = collectUserRefIds(
+      property.schema,
+      before?.[property.id],
+      valueTypesById,
+      new Set()
+    )
+    for (const id of introduced) {
+      if (held.has(id)) continue
+      const problem = userReferenceProblem(
+        `Property '${objectTypeId}.${property.id}'`,
+        id,
+        users.kind === "unavailable" ? "unverifiable" : (users.statuses.get(id) ?? null)
+      )
+      if (problem) throw new MaterializationValidationError(problem)
+    }
+  }
+}
+
+function collectObjectUserRefIds(
+  ontology: OntologyRegistry,
+  objectTypeId: string,
+  properties: Readonly<Record<string, JsonValue>>,
+  into: Set<string>
+): void {
+  // Unknown types and properties are rejected by the edit pass; nothing to look up for them.
+  const objectType = ontology.getObjectTypeById(objectTypeId)
+  if (!objectType) return
+  const valueTypesById = ontology.getValueTypesById()
+  for (const property of objectType.properties) {
+    collectUserRefIds(property.schema, properties[property.id], valueTypesById, into)
+  }
+}

package/src/materializer/effective/build-events.ts

@@ -1,4 +1,3 @@
-import type { EventActor } from "../../events/envelope"
 import type {
   EffectiveLinkChange,
   EffectiveObjectChange,
@@ -10,6 +9,7 @@ import type {
   OntologyMaterializationEvent,
   OntologyMaterializationEventDraft,
 } from "../../storage/ontology"
+import type { MaterializerAttribution } from "../execution/scope"
 import { createEventId, materializationEventKindOrdinal } from "../shared/identity"
 
 export interface OrderedMaterializationEventDraft {
@@ -24,7 +24,7 @@ export interface MaterializationEventDraftContext {
   readonly committedAt: string
   readonly correlationId: string
   readonly origin: OntologyMaterializationOrigin
-  readonly actor?: EventActor
+  readonly attribution: MaterializerAttribution
 }
 
 export function buildObjectMaterializationEventDraft(
@@ -162,16 +162,15 @@ function buildTelemetryEventDraft(
 }
 
 function eventDraftBase(context: MaterializationEventDraftContext) {
-  const base = {
+  return {
     schemaVersion: 1 as const,
     projectId: context.projectId,
     occurredAt: context.committedAt,
     correlationId: context.correlationId,
     origin: context.origin,
+    ...context.attribution,
     commitId: context.commitId,
   }
-  if (context.actor === undefined) return base
-  return { ...base, actor: context.actor }
 }
 
 function orderedDraft(

package/src/materializer/execution/scope.ts

@@ -1,24 +1,37 @@
-import type { EventActor } from "../../events/envelope"
 import { resolveExecutionScopeAuthorization } from "../../execution/authorization"
 import { ensureExecutionRecord, executionRecordInputFromRuntime } from "../../execution/durable"
-import type { ExecutionScope, TrustedPrimitiveKind } from "../../execution/types"
+import type {
+  AuthorizablePrincipal,
+  ExecutionScope,
+  TrustedPrimitiveKind,
+} from "../../execution/types"
 import {
   MaterializationConflictError,
   MaterializationValidationError,
 } from "../../materialization/errors"
+import type { EventExecutor } from "../../materialization/events"
 import type {
   CreateExecutionInput,
   ExecutionRecord,
   ExecutionStorage,
 } from "../../storage/executions"
 
+/**
+ * Who and what a commit and its events are attributed to. Both are copied from the execution, so
+ * they are a pure function of `executionId` and never an input the caller chooses.
+ */
+export interface MaterializerAttribution {
+  readonly requestedBy?: AuthorizablePrincipal
+  readonly executor: EventExecutor
+}
+
 /** Immutable execution metadata attached to one prepared Materializer command. */
 export interface MaterializerExecution {
   readonly scope: ExecutionScope
   readonly record: CreateExecutionInput
   readonly executionId: string
   readonly correlationId: string
-  readonly actor?: EventActor
+  readonly attribution: MaterializerAttribution
 }
 
 /** Validate the process-local scope before any Materializer read or write is attempted. */
@@ -26,9 +39,9 @@ export function prepareMaterializerExecution(
   projectId: string,
   scope: ExecutionScope
 ): MaterializerExecution {
-  const authorization = resolveExecutionScopeAuthorization(projectId, scope)
+  resolveExecutionScopeAuthorization(projectId, scope)
 
-  const base = {
+  return {
     scope,
     record: executionRecordInputFromRuntime({
       execution: scope.execution,
@@ -36,9 +49,29 @@ export function prepareMaterializerExecution(
     }),
     executionId: scope.execution.id,
     correlationId: scope.execution.correlationId,
+    attribution: executionAttribution(scope),
+  }
+}
+
+function executionAttribution(scope: ExecutionScope): MaterializerAttribution {
+  const { requestedBy, executor } = scope.execution
+  const attributed = { executor: eventExecutor(executor) }
+  if (requestedBy === undefined) return attributed
+  return { ...attributed, requestedBy: { type: requestedBy.type, id: requestedBy.id } }
+}
+
+/** Drop the process-local Agent actor id: the durable execution does not record it. */
+function eventExecutor(executor: ExecutionScope["execution"]["executor"]): EventExecutor {
+  switch (executor.type) {
+    case "request":
+      return { type: "request", requestId: executor.requestId }
+    case "primitive":
+      return { type: "primitive", kind: executor.kind, id: executor.id, runId: executor.runId }
+    case "agent":
+      return { type: "agent", runId: executor.runId }
+    case "kernel":
+      return { type: "kernel", operation: structuredClone(executor.operation) }
   }
-  if (authorization.type !== "principal") return base
-  return { ...base, actor: authorization.context.principal }
 }
 
 /** Persist a direct request lazily, or prove that a durable worker restored the exact record. */

package/src/materializer/projections/replace.ts

@@ -407,6 +407,7 @@ function projectionCommit(
     requestHash: identity.requestHash,
     executionId: command.scopeExecution.executionId,
     origin,
+    ...command.scopeExecution.attribution,
     ontologyRevision: command.runIdentity.ontologyRevision,
     projectionRevision: command.runIdentity.projectionRevision,
     ownershipHash: command.runIdentity.ownershipHash,
@@ -430,6 +431,7 @@ async function planReadyProjection(
     identity: ready.identity,
     origin,
     correlationId: command.scopeExecution.correlationId,
+    attribution: command.scopeExecution.attribution,
   }
   if (command.signal === undefined) {
     return planProjectionReplacement(context, storage, session, input)

package/src/materializer/projections/replacement-plan.ts

@@ -37,6 +37,7 @@ import {
   usableLinkSlotOverride,
 } from "../effective/resolve"
 import { validateEffectiveObject } from "../effective/validate"
+import type { MaterializerAttribution } from "../execution/scope"
 import { stageWorkBounded, validateStagedCardinality } from "../execution/work-executor"
 import {
   appendEffectiveLinkWork,
@@ -55,6 +56,7 @@ export interface ProjectionReplacementPlanInput {
   readonly identity: TimedCommitIdentity
   readonly origin: OntologyMaterializationOrigin
   readonly correlationId: string
+  readonly attribution: MaterializerAttribution
   readonly signal?: AbortSignal
 }
 
@@ -163,6 +165,7 @@ function appendObjectChangeWork(
         committedAt: input.identity.committedAt,
         origin: input.origin,
         correlationId: input.correlationId,
+        attribution: input.attribution,
         change,
       })
     )
@@ -360,6 +363,7 @@ function appendLinkChangeWork(
         committedAt: input.identity.committedAt,
         origin: input.origin,
         correlationId: input.correlationId,
+        attribution: input.attribution,
         change,
       })
     )

package/src/materializer/telemetry/append.ts

@@ -401,7 +401,7 @@ async function executeTelemetryTransaction(
     origin,
     {
       correlationId: command.execution.correlationId,
-      ...(command.execution.actor === undefined ? {} : { actor: command.execution.actor }),
+      attribution: command.execution.attribution,
     }
   )
   await drainStagedWork(context, storage, session)
@@ -475,27 +475,19 @@ function telemetryCommit(
     requestHash: command.identity.requestHash,
     executionId: command.execution.executionId,
     origin,
+    ...command.execution.attribution,
     ontologyRevision: command.ontologyRevision,
     intent: telemetryCommitIntent(command),
     committedAt: command.identity.committedAt,
   }
-  const withActor = telemetryCommitActor(base, command)
-  if (command.kind === "runtime") return withActor
+  if (command.kind === "runtime") return base
   return {
-    ...withActor,
+    ...base,
     projectionRevision: command.resolvedProjection.projectionRevision,
     ownershipHash: command.resolvedProjection.ownershipHash,
   }
 }
 
-function telemetryCommitActor(
-  commit: OntologyCommitWrite,
-  command: PreparedTelemetryAppend
-): OntologyCommitWrite {
-  if (command.execution.actor === undefined) return commit
-  return { ...commit, actor: command.execution.actor }
-}
-
 function telemetryCommitIntent(command: PreparedTelemetryAppend): TelemetryOntologyCommitIntent {
   if (command.kind === "runtime") {
     return {

package/src/materializer/telemetry/plan.ts

@@ -1,4 +1,3 @@
-import type { EventActor } from "../../events/envelope"
 import { stableJsonStringify } from "../../json"
 import { MaterializationObjectNotFoundError } from "../../materialization/errors"
 import type {
@@ -30,6 +29,7 @@ import {
 import { diffEffectiveObject } from "../effective/diff"
 import { loadState, oneStateRequest } from "../effective/load-state"
 import { validateEffectiveObject } from "../effective/validate"
+import type { MaterializerAttribution } from "../execution/scope"
 import { stageWorkBounded } from "../execution/work-executor"
 import {
   appendEffectiveObjectWork,
@@ -68,7 +68,7 @@ interface TelemetryPlanContext {
 
 interface TelemetryEventContext {
   readonly correlationId: string
-  readonly actor?: EventActor
+  readonly attribution: MaterializerAttribution
 }
 
 export async function planTelemetryAppend(
@@ -351,15 +351,14 @@ function telemetryEventContext(
   context: Pick<MaterializerContext, "projectId">,
   planContext: TelemetryPlanContext
 ) {
-  const eventContext = {
+  return {
     projectId: context.projectId,
     commitId: planContext.identity.commitId,
     committedAt: planContext.identity.committedAt,
     origin: planContext.origin,
     correlationId: planContext.event.correlationId,
+    attribution: planContext.event.attribution,
   }
-  if (planContext.event.actor === undefined) return eventContext
-  return { ...eventContext, actor: planContext.event.actor }
 }
 
 function emptyTelemetryCounts(): MutableTelemetryPlanCounts {

package/src/objects/execution.ts

@@ -4,17 +4,15 @@ import {
   assertAuthorizedObjectReaderBinding,
   getAuthorizedOntologyView,
 } from "../execution/authorized-object-reader"
-import type { ValueType } from "../ontology"
 import type { ObjectTypeWithPropertyTokens } from "../ontology/tokens"
 import { assertObjectTypeRegistered } from "../ontology/validation/properties"
 import { shareOntologyMutationRuntime } from "../runtime/ontology-mutations"
 import type {
   ListResult,
   ObjectByIdHandle,
+  ObjectReadByIdHandle,
+  ObjectReadSet,
   ObjectSet,
-  OntologySource,
-  RegisteredObjectType,
-  RegisteredValueTypes,
   SixbRuntimeContext,
 } from "../runtime/types"
 import type {
@@ -83,46 +81,28 @@ export interface ExecutionObjectOperations {
   ): Promise<void>
 }
 
-export interface ExecutionObjectByIdHandle<
-  TObjectType extends ObjectTypeWithPropertyTokens,
-  TValueTypes extends readonly ValueType[],
-> {
-  vector: ObjectByIdHandle<TObjectType, TValueTypes>["vector"]
-  get: ObjectByIdHandle<TObjectType, TValueTypes>["get"]
-  listLinks: ObjectByIdHandle<TObjectType, TValueTypes>["listLinks"]
-  requestAction: ObjectByIdHandle<TObjectType, TValueTypes>["requestAction"]
-  requestActionAndWait: ObjectByIdHandle<TObjectType, TValueTypes>["requestActionAndWait"]
-  link: ObjectByIdHandle<TObjectType, TValueTypes>["link"]
-  unlink: ObjectByIdHandle<TObjectType, TValueTypes>["unlink"]
-  delete: ObjectByIdHandle<TObjectType, TValueTypes>["delete"]
-  restore: ObjectByIdHandle<TObjectType, TValueTypes>["restore"]
-  telemetry: ObjectByIdHandle<TObjectType, TValueTypes>["telemetry"]
+export interface ExecutionObjectByIdHandle<TObjectType extends ObjectTypeWithPropertyTokens>
+  extends ObjectReadByIdHandle<TObjectType> {
+  vector: ObjectByIdHandle<TObjectType>["vector"]
+  requestAction: ObjectByIdHandle<TObjectType>["requestAction"]
+  requestActionAndWait: ObjectByIdHandle<TObjectType>["requestActionAndWait"]
+  link: ObjectByIdHandle<TObjectType>["link"]
+  unlink: ObjectByIdHandle<TObjectType>["unlink"]
+  delete: ObjectByIdHandle<TObjectType>["delete"]
+  restore: ObjectByIdHandle<TObjectType>["restore"]
+  telemetry: ObjectByIdHandle<TObjectType>["telemetry"]
 }
 
-export interface ExecutionObjectSet<
-  TObjectType extends ObjectTypeWithPropertyTokens,
-  TValueTypes extends readonly ValueType[],
-  TRegisteredObjectTypes extends ObjectTypeWithPropertyTokens = TObjectType,
-> {
-  get: ObjectSet<TObjectType, TValueTypes, TRegisteredObjectTypes>["get"]
-  list: ObjectSet<TObjectType, TValueTypes, TRegisteredObjectTypes>["list"]
-  query: ObjectSet<TObjectType, TValueTypes, TRegisteredObjectTypes>["query"]
-  requestAction: ObjectSet<TObjectType, TValueTypes, TRegisteredObjectTypes>["requestAction"]
-  requestActionAndWait: ObjectSet<
-    TObjectType,
-    TValueTypes,
-    TRegisteredObjectTypes
-  >["requestActionAndWait"]
-  upsert: ObjectSet<TObjectType, TValueTypes, TRegisteredObjectTypes>["upsert"]
-  upsertLink: ObjectSet<TObjectType, TValueTypes, TRegisteredObjectTypes>["upsertLink"]
-  removeLink: ObjectSet<TObjectType, TValueTypes, TRegisteredObjectTypes>["removeLink"]
-  appendTelemetryBatch: ObjectSet<
-    TObjectType,
-    TValueTypes,
-    TRegisteredObjectTypes
-  >["appendTelemetryBatch"]
+export interface ExecutionObjectSet<TObjectType extends ObjectTypeWithPropertyTokens>
+  extends ObjectReadSet<TObjectType> {
+  requestAction: ObjectSet<TObjectType>["requestAction"]
+  requestActionAndWait: ObjectSet<TObjectType>["requestActionAndWait"]
+  upsert: ObjectSet<TObjectType>["upsert"]
+  upsertLink: ObjectSet<TObjectType>["upsertLink"]
+  removeLink: ObjectSet<TObjectType>["removeLink"]
+  appendTelemetryBatch: ObjectSet<TObjectType>["appendTelemetryBatch"]
 
-  byId(id: string): ExecutionObjectByIdHandle<TObjectType, TValueTypes>
+  byId(id: string): ExecutionObjectByIdHandle<TObjectType>
 }
 
 /** Public input for querying physical links incident to an object query result. */
@@ -131,15 +111,10 @@ export type ObjectQueryLinksInput = Omit<ExecuteObjectQueryLinksInput, "projectI
 /** Public result returned by {@link ObjectsRuntime.queryLinks}. */
 export type ObjectQueryLinksResult = ExecuteObjectQueryLinksResult
 
-export interface ObjectsRuntime<TOntologySources extends readonly OntologySource[]>
-  extends ExecutionObjectOperations {
-  <TObjectType extends RegisteredObjectType<TOntologySources>>(
+export interface ObjectsRuntime extends ExecutionObjectOperations {
+  <TObjectType extends ObjectTypeWithPropertyTokens>(
     objectType: TObjectType
-  ): ExecutionObjectSet<
-    TObjectType,
-    RegisteredValueTypes<TOntologySources>,
-    RegisteredObjectType<TOntologySources>
-  >
+  ): ExecutionObjectSet<TObjectType>
   executeQuery(input: Omit<ExecuteObjectQueryInput, "projectId">): Promise<ExecuteObjectQueryResult>
   queryLinks(input: ObjectQueryLinksInput): Promise<ObjectQueryLinksResult>
   count(input: Omit<ExecuteObjectCountInput, "projectId">): Promise<ExecuteObjectCountResult>
@@ -170,10 +145,10 @@ export interface ObjectsRuntime<TOntologySources extends readonly OntologySource
   }): Promise<TimeseriesPoint | null>
 }
 
-export function createObjectsRuntime<TOntologySources extends readonly OntologySource[]>(
+export function createObjectsRuntime(
   runtime: SixbRuntimeContext,
   execution: ExecutionContext
-): ObjectsRuntime<TOntologySources> {
+): ObjectsRuntime {
   const runtimeAuthorization = runtime.runtimeAuthorization
   const objectReader = runtime.objectReader
   assertAuthorizedObjectReaderBinding({
@@ -199,17 +174,13 @@ export function createObjectsRuntime<TOntologySources extends readonly OntologyS
   Object.freeze(capturedRuntime)
   const ontologyView = () => getAuthorizedOntologyView(objectReader)
   const objects = Object.assign(
-    <TObjectType extends RegisteredObjectType<TOntologySources>>(objectType: TObjectType) => {
+    <TObjectType extends ObjectTypeWithPropertyTokens>(objectType: TObjectType) => {
       assertObjectTypeRegistered(capturedRuntime.ontology.getObjectTypesById(), objectType)
-      return createObjectSet<
-        TObjectType,
-        RegisteredObjectType<TOntologySources>,
-        RegisteredValueTypes<TOntologySources>
-      >({ ...capturedRuntime, execution, objectType }) as ExecutionObjectSet<
-        TObjectType,
-        RegisteredValueTypes<TOntologySources>,
-        RegisteredObjectType<TOntologySources>
-      >
+      return createObjectSet<TObjectType>({
+        ...capturedRuntime,
+        execution,
+        objectType,
+      }) as ExecutionObjectSet<TObjectType>
     },
     {
       listTypes: () => ontologyView().listObjectTypes(),
@@ -319,5 +290,5 @@ export function createObjectsRuntime<TOntologySources extends readonly OntologyS
     }
   )
 
-  return objects as ObjectsRuntime<TOntologySources>
+  return objects as ObjectsRuntime
 }

package/src/objects/query/executor.ts

@@ -30,6 +30,7 @@ import type {
   ObjectQueryPredicate,
   ObjectQueryResultShape,
   ObjectQuerySortField,
+  QueryScalarKind,
 } from "./ir"
 import { normalizeObjectQuery } from "./normalize"
 import { type ObjectQueryPlan, type ObjectQueryPlanningOptions, planObjectQuery } from "./planner"
@@ -1104,17 +1105,25 @@ function matchesPredicate(row: ObjectRow, predicate: ObjectQueryPredicate): bool
       return predicate.value ? exists : !exists
     }
     case "contains":
-      return containsValue(row.properties[predicate.propertyId], predicate.value)
+      return containsValue(
+        row.properties[predicate.propertyId],
+        predicate.value,
+        predicate.scalarKind
+      )
   }
 }
 
-function containsValue(actual: unknown, expected: unknown): boolean {
+function containsValue(
+  actual: unknown,
+  expected: unknown,
+  itemScalarKind: QueryScalarKind | undefined
+): boolean {
   if (typeof actual === "string" && typeof expected === "string") {
     return actual.includes(expected)
   }
 
   if (Array.isArray(actual)) {
-    return actual.some((item) => queryScalarValuesEqual(item, expected))
+    return actual.some((item) => queryScalarValuesEqual(item, expected, itemScalarKind))
   }
 
   if (isPlainObject(actual) && typeof expected === "string") {

package/src/objects/query/ir.ts

@@ -20,6 +20,8 @@ export type QueryScalarKind =
   | "decimal"
   | "date"
   | "timestamp"
+  /** A `{ type: "user", id }` value, equal when both fields are. */
+  | "userRef"
 
 export type ObjectQuery =
   | ObjectQueryStart
@@ -214,6 +216,11 @@ export interface ObjectQueryPredicateContains {
   op: "contains"
   propertyId: string
   value: unknown
+  /**
+   * Core-resolved scalar schema of the array's items when the property is an array; never
+   * authored by callers. String substring and map key matches carry none.
+   */
+  scalarKind?: QueryScalarKind
 }
 
 export type ObjectQuerySortField =

package/src/objects/query/planner.ts

@@ -338,6 +338,7 @@ function predicateScalarOperation(
     case "eq":
     case "neq":
     case "in":
+    case "contains":
       return "equality"
     case "lt":
     case "lte":

package/src/objects/query/scalar-values.ts

@@ -33,6 +33,9 @@ export function compareQueryScalarValues(
     case "date":
     case "timestamp":
       return compareTemporalValues(left, right)
+    case "userRef":
+      // Identity only: user references have no order.
+      return Number.NaN
   }
 }
 
@@ -52,10 +55,26 @@ export function queryScalarValuesEqual(
     return !Number.isNaN(comparison) && comparison === 0
   }
 
+  if (scalarKind === "userRef") return userRefsEqual(left, right)
   if (scalarKind !== undefined) return Object.is(left, right)
   return runtimeValuesEqual(left, right)
 }
 
+function userRefsEqual(left: unknown, right: unknown): boolean {
+  if (left === null || right === null) return left === right
+  return (
+    isRecord(left) &&
+    isRecord(right) &&
+    left.type === right.type &&
+    typeof left.id === "string" &&
+    left.id === right.id
+  )
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
 function compareRuntimeValues(left: unknown, right: unknown): number {
   if (typeof left === "number" && typeof right === "number") return left - right
   if (typeof left === "string" && typeof right === "string") return compareStrings(left, right)