@sixb/core 0.1.21 → 0.1.22

package/src/objects/sdk/query-builder.ts

@@ -164,14 +164,19 @@ class ObjectQueryBuilderImpl<TObjectType extends ObjectTypeWithPropertyTokens> {
   }
 
   expand(
-    link: LinkToken<string, string, string | readonly string[]>,
+    token: ExpandToken,
     optionsOrBuild?: ObjectExpandOptions<ObjectTypeWithPropertyTokens> | NestedExpandBuild,
     build?: NestedExpandBuild
   ): ObjectQueryBuilder<TObjectType> {
+    if (isPropertyToken(token)) {
+      assertNoUserExpansionOptions(optionsOrBuild, build)
+      return this.withQuery({ kind: "expand", input: this.ir, expansions: [], users: [token.id] })
+    }
+
     return this.withQuery({
       kind: "expand",
       input: this.ir,
-      expansions: [buildExpansion(link, optionsOrBuild, build)],
+      expansions: [buildExpansion(token, optionsOrBuild, build)],
     })
   }
 
@@ -309,26 +314,49 @@ class ObjectQueryBuilderImpl<TObjectType extends ObjectTypeWithPropertyTokens> {
 type AnyExpandBuilder = ObjectExpandBuilder<ObjectTypeWithPropertyTokens>
 type NestedExpandBuild = (nested: AnyExpandBuilder) => AnyExpandBuilder
 
+/** A link to hydrate, or a `ref.user()` property whose members' profiles to attach. */
+type ExpandToken = LinkToken<string, string, string | readonly string[]> | PropertyToken
+
 /**
  * Runtime backing for the nested `.expand(..., (e) => …)` callback. Immutable,
  * mirroring the query builder: each `expand` returns a new instance so the
  * accumulated expansions are never shared between branches.
  */
 class ObjectExpandBuilderImpl {
-  constructor(readonly expansions: readonly ObjectExpansion[] = []) {}
+  constructor(
+    readonly expansions: readonly ObjectExpansion[] = [],
+    readonly users: readonly string[] = []
+  ) {}
 
   expand(
-    link: LinkToken<string, string, string | readonly string[]>,
+    token: ExpandToken,
     optionsOrBuild?: ObjectExpandOptions<ObjectTypeWithPropertyTokens> | NestedExpandBuild,
     build?: NestedExpandBuild
   ): ObjectExpandBuilderImpl {
-    return new ObjectExpandBuilderImpl([
-      ...this.expansions,
-      buildExpansion(link, optionsOrBuild, build),
-    ])
+    if (isPropertyToken(token)) {
+      assertNoUserExpansionOptions(optionsOrBuild, build)
+      return new ObjectExpandBuilderImpl(this.expansions, [...this.users, token.id])
+    }
+
+    return new ObjectExpandBuilderImpl(
+      [...this.expansions, buildExpansion(token, optionsOrBuild, build)],
+      this.users
+    )
   }
 }
 
+// A link token carries `link`, a property token `property`.
+function isPropertyToken(token: ExpandToken): token is PropertyToken {
+  return "property" in token
+}
+
+function assertNoUserExpansionOptions(optionsOrBuild: unknown, build: unknown): void {
+  if (optionsOrBuild === undefined && build === undefined) return
+  throw new OntologyValidationError(
+    "[Sixb] expand() of a user property takes no options or nested expansions."
+  )
+}
+
 function buildExpansion(
   link: LinkToken<string, string, string | readonly string[]>,
   optionsOrBuild: ObjectExpandOptions<ObjectTypeWithPropertyTokens> | NestedExpandBuild | undefined,
@@ -340,9 +368,11 @@ function buildExpansion(
   const nestedBuild = typeof optionsOrBuild === "function" ? optionsOrBuild : build
 
   let nested: readonly ObjectExpansion[] = []
+  let users: readonly string[] = []
   if (nestedBuild) {
     const result = nestedBuild(new ObjectExpandBuilderImpl() as unknown as AnyExpandBuilder)
     nested = (result as unknown as ObjectExpandBuilderImpl).expansions
+    users = (result as unknown as ObjectExpandBuilderImpl).users
   }
 
   return {
@@ -351,6 +381,7 @@ function buildExpansion(
     ...(options?.limit !== undefined ? { limit: options.limit } : {}),
     ...(options?.orderBy ? { orderBy: options.orderBy.map(expansionSortToField) } : {}),
     ...(nested.length > 0 ? { expand: nested } : {}),
+    ...(users.length > 0 ? { users } : {}),
   }
 }
 

package/src/objects/sdk/query-executor.ts

@@ -6,6 +6,8 @@
  * against the HTTP query routes, so both share one builder.
  */
 import type { ObjectQueryFacetsResult } from "../../runtime/types"
+import type { Redactions } from "../../security/types"
+import type { UserProfile } from "../../users"
 import type { ObjectQueryExplanation } from "../query/explain"
 import type { ObjectQuery } from "../query/ir"
 import type { ValidatedObjectQuery } from "../query/validate"
@@ -15,6 +17,8 @@ export type ObjectQueryExecutorRow = {
   primaryId: string
   objectTypeId: string
   properties: Record<string, unknown>
+  /** Properties omitted because the reader lacks a clearance, keyed by property id. */
+  redactions?: Redactions
   createdAt: Date
   updatedAt: Date
   /** Linked objects attached by an `expand` node, keyed by link id. The builder
@@ -22,6 +26,8 @@ export type ObjectQueryExecutorRow = {
    * over the same light row shape so both executors (the server's full
    * `ObjectRow` and the client's wire-reconstructed row) satisfy it. */
   links?: ObjectQueryExecutorLinks
+  /** Member profiles attached by an `expand` node, keyed by `ref.user()` property id. */
+  users?: Record<string, UserProfile | readonly UserProfile[] | null>
 }
 
 export type ObjectQueryExecutorLinks = Record<string, ObjectQueryExecutorLinkValue>

package/src/objects/serialize.ts

@@ -0,0 +1,79 @@
+import type { Redactions } from "../security/types"
+import type {
+  ExpandedLinkValue,
+  ExpandedObjectRow,
+  ObjectRowLinks,
+  ObjectRowUsers,
+} from "../storage/objects/types"
+
+/**
+ * Objects as the objects API answers them, in JSON: dates as ISO text. One owner for what the API
+ * sends and what the Agent's layout check serves a page, so a page reads the same rows in both.
+ */
+export interface SerializedObject {
+  readonly score?: number
+  readonly primaryId: string
+  readonly objectTypeId: string
+  readonly properties: Record<string, unknown>
+  readonly redactions?: Redactions
+  readonly createdAt: string
+  readonly updatedAt: string
+}
+
+type SerializedLinkValue = SerializedExpandedObject | SerializedExpandedObject[] | null
+
+export interface SerializedExpandedObject extends SerializedObject {
+  links?: Record<string, SerializedLinkValue>
+  linkProperties?: Record<string, unknown>
+  users?: ObjectRowUsers
+}
+
+export function serializeObject(row: {
+  readonly score?: number
+  readonly primaryId: string
+  readonly objectTypeId: string
+  readonly properties: Record<string, unknown>
+  readonly redactions?: Redactions
+  readonly createdAt: Date
+  readonly updatedAt: Date
+}): SerializedObject {
+  return {
+    ...(row.score === undefined ? {} : { score: row.score }),
+    primaryId: row.primaryId,
+    objectTypeId: row.objectTypeId,
+    properties: row.properties,
+    ...(row.redactions === undefined ? {} : { redactions: row.redactions }),
+    createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString(),
+  }
+}
+
+/**
+ * Serialize a query row together with any `links` attached by an `expand` node.
+ * Recurses through nested expansions; `linkProperties` carries edge metadata on
+ * an expanded child. Only the query route hydrates links, so the plain list and
+ * identity routes keep using `serializeObject`.
+ */
+export function serializeExpandedObject(row: ExpandedObjectRow): SerializedExpandedObject {
+  const serialized: SerializedExpandedObject = serializeObject(row)
+  if (row.links) serialized.links = serializeLinks(row.links)
+  if (row.linkProperties !== undefined) serialized.linkProperties = row.linkProperties
+  // Profiles are plain JSON: no dates to convert.
+  if (row.users) serialized.users = row.users
+  return serialized
+}
+
+function serializeLinks(links: ObjectRowLinks): Record<string, SerializedLinkValue> {
+  const result: Record<string, SerializedLinkValue> = {}
+  for (const [linkId, value] of Object.entries(links)) {
+    result[linkId] = serializeLinkValue(value)
+  }
+  return result
+}
+
+function serializeLinkValue(value: ExpandedLinkValue): SerializedLinkValue {
+  if (value === null) return null
+  if (Array.isArray(value)) return value.map(serializeExpandedObject)
+  // Array.isArray does not narrow a readonly[] away, so assert the scalar case.
+  return serializeExpandedObject(value as ExpandedObjectRow)
+}

package/src/objects/unique-violation.ts

@@ -0,0 +1,59 @@
+import { createSixbError, type SixbCodedError, withFailureMessage } from "../errors/internal"
+import type { ReadonlyJsonValue } from "../json"
+import { UniqueValueViolationError } from "../materialization/errors"
+
+/**
+ * The coded error a write reports when it would give a unique value to a second object, or
+ * `undefined` for any other error. Like its message, it names only the type and the property:
+ * never the value, nor the object that holds it.
+ */
+export function uniqueViolationError(
+  error: unknown,
+  details?: ReadonlyJsonValue
+): SixbCodedError | undefined {
+  if (!(error instanceof UniqueValueViolationError)) return undefined
+
+  return codedViolation(error.objectTypeId, error.propertyId, error.message, {
+    cause: error,
+    details,
+  })
+}
+
+/** The same coded error for a batch item that a continue-mode commit refused. */
+export function uniqueViolationItemError(item: UniqueViolation): SixbCodedError {
+  return codedViolation(item.objectTypeId, item.propertyId, item.message)
+}
+
+interface UniqueViolation {
+  readonly objectTypeId: string
+  readonly propertyId: string
+  readonly message: string
+}
+
+/**
+ * The error a create meets on a primary id an object its writer cannot see holds. It tells that the
+ * id is taken, as a unique value is, and nothing about the object.
+ */
+export function primaryIdTakenError(
+  objectTypeId: string,
+  primaryPropertyId: string
+): SixbCodedError {
+  return codedViolation(
+    objectTypeId,
+    primaryPropertyId,
+    `[Sixb] Another '${objectTypeId}' object already has this '${primaryPropertyId}'.`
+  )
+}
+
+function codedViolation(
+  objectTypeId: string,
+  propertyId: string,
+  message: string,
+  options: { readonly cause?: unknown; readonly details?: ReadonlyJsonValue } = {}
+): SixbCodedError {
+  const coded = createSixbError("object.unique_violation", message, {
+    ...(options.cause === undefined ? {} : { cause: options.cause }),
+    details: options.details ?? { objectTypeId, propertyId },
+  })
+  return withFailureMessage(coded, `Property '${objectTypeId}.${propertyId}' is unique.`)
+}

package/src/objects/vectors/handle.ts

@@ -1,10 +1,10 @@
 import { randomUUID } from "node:crypto"
-import { assertCanEdit } from "../../authorization"
 import { AuthorizationError } from "../../authorization/errors"
 import { MaterializationValidationError } from "../../materialization/errors"
 import type { PreparedObjectVector } from "../../materialization/vectors"
 import { sameEmbeddingModel } from "../../models/embedding-model"
 import { getOntologyMutationRuntime } from "../../runtime/ontology-mutations"
+import { assertCanEditType } from "../conditional-writes"
 import type { ExecutionObjectContext } from "../context"
 import {
   INDEXING_EMBEDDING_TIMEOUT_MS,
@@ -42,7 +42,7 @@ export function createObjectVectorHandle(
 
   return Object.freeze({
     async index(): Promise<void> {
-      assertCanEdit(ctx, ref.objectTypeId)
+      await assertCanEditType(ctx, ref.objectTypeId)
       await assertReadable()
       const mutations = getOntologyMutationRuntime(ctx)
       const model = ctx.embeddingModels?.getByRef({
@@ -84,7 +84,7 @@ export function createObjectVectorHandle(
         result.vectors[0]!,
         profileDefinition.model.definition.dimensions
       )
-      assertCanEdit(ctx, ref.objectTypeId)
+      await assertCanEditType(ctx, ref.objectTypeId)
       await assertReadable()
       await mutations.commitEdits({
         mode: "atomic",

package/src/ontology/builders.ts

@@ -352,6 +352,8 @@ type PropertyOptions = {
   required?: boolean
   nullable?: boolean
   primary?: true
+  /** At most one object of the type holds each value. */
+  unique?: true
   mode?: PropertyMode
   semanticType?: QuantitativeTypeId
   query?: PropertyQueryMetadata
@@ -378,6 +380,7 @@ type PropertyResult<
   FieldFromOptions<TOptions, "required", boolean> &
   FieldFromOptions<TOptions, "nullable", boolean> &
   FieldFromOptions<TOptions, "primary", true> &
+  FieldFromOptions<TOptions, "unique", true> &
   FieldFromOptions<TOptions, "mode", PropertyMode> &
   FieldFromOptions<TOptions, "semanticType", QuantitativeTypeId> &
   FieldFromOptions<TOptions, "query", PropertyQueryMetadata> &

package/src/ontology/docs-markdown.ts

@@ -135,6 +135,7 @@ function renderProperties(
         code(property.id),
         withFlags(schemaLabel(property.schema, valueTypesById), [
           ...(property.primary ? ["primary key"] : []),
+          ...(property.unique ? ["unique"] : []),
           ...(property.required && !property.primary ? ["required"] : []),
           ...(property.nullable ? ["nullable"] : []),
           ...(property.mode === "telemetry" ? ["telemetry"] : []),

package/src/ontology/index.ts

@@ -64,8 +64,8 @@ export type {
   ValueType,
   ValueTypeRefSchema,
 } from "./types"
-export type { UserRef } from "./user-ref"
-export { userRef } from "./user-ref"
+export type { CurrentUserRef, UserRef } from "./user-ref"
+export { currentUser, userRef } from "./user-ref"
 
 // ── Registry ──────────────────────────────────────────────
 

package/src/ontology/json-schema.ts

@@ -3,6 +3,9 @@ import { OntologyValidationError } from "./errors"
 import type { SchemaOrRef } from "./refs"
 import type { Schema, ValueType } from "./types"
 
+// A user reference carries no name, so whoever reads the schema is told how one is written.
+const USER_REF_DESCRIPTION = 'A Sixb user, written {"type":"user","id":"<user-id>"}.'
+
 type DeepReadonly<T> = T extends object ? { readonly [K in keyof T]: DeepReadonly<T[K]> } : T
 
 export interface SchemaJsonField {
@@ -104,6 +107,7 @@ function schemaJsonSchema(
       case "userRef":
         return {
           type: "object",
+          description: USER_REF_DESCRIPTION,
           properties: {
             type: { type: "string", enum: ["user"] },
             id: { type: "string", minLength: 1 },

package/src/ontology/primitives.ts

@@ -1,5 +1,6 @@
 import type { QueryScalarKind } from "../objects/query/ir"
 import type { PrimitiveSchema } from "./types"
+import type { UniqueValueKind } from "./unique-values"
 
 /**
  * Yes/no decisions a primitive schema makes for rules that several modules share.
@@ -28,6 +29,8 @@ export interface PrimitiveTraits {
   readonly telemetry: boolean
   /** Allowed anywhere inside a shared Action parameter's schema. */
   readonly shareableParam: boolean
+  /** How `unique: true` values compare; `undefined` when the primitive cannot be unique. */
+  readonly unique: UniqueValueKind | undefined
 }
 
 const comparable = {
@@ -42,14 +45,22 @@ const comparable = {
 } as const
 
 const PRIMITIVE_TRAITS = {
-  string: { ...comparable, queryScalarKind: "string", text: true, contains: true },
-  uuid: { ...comparable, queryScalarKind: "uuid", contains: true },
-  integer: { ...comparable, queryScalarKind: "integer" },
-  double: { ...comparable, queryScalarKind: "double" },
-  decimal: { ...comparable, queryScalarKind: "decimal" },
-  date: { ...comparable, queryScalarKind: "date" },
-  timestamp: { ...comparable, queryScalarKind: "timestamp" },
-  boolean: { ...comparable, queryScalarKind: "boolean", sortable: false },
+  string: {
+    ...comparable,
+    queryScalarKind: "string",
+    text: true,
+    contains: true,
+    unique: "string",
+  },
+  uuid: { ...comparable, queryScalarKind: "uuid", contains: true, unique: "string" },
+  integer: { ...comparable, queryScalarKind: "integer", unique: "integer" },
+  // Unique values compare as exact keys: floating-point values are no identity, and decimals and
+  // instants stay out until one stored spelling per value is guaranteed.
+  double: { ...comparable, queryScalarKind: "double", unique: undefined },
+  decimal: { ...comparable, queryScalarKind: "decimal", unique: undefined },
+  date: { ...comparable, queryScalarKind: "date", unique: "string" },
+  timestamp: { ...comparable, queryScalarKind: "timestamp", unique: undefined },
+  boolean: { ...comparable, queryScalarKind: "boolean", sortable: false, unique: undefined },
   // Blob references are resolved through the object that holds them, never compared.
   fileRef: {
     queryScalarKind: undefined,
@@ -61,6 +72,7 @@ const PRIMITIVE_TRAITS = {
     facet: false,
     telemetry: false,
     shareableParam: false,
+    unique: undefined,
   },
   // User references match by identity, never against typed search input. They are not text, carry
   // no order, and stay out of telemetry and shared sessions, which cannot disclose who they point to.
@@ -74,6 +86,7 @@ const PRIMITIVE_TRAITS = {
     facet: true,
     telemetry: false,
     shareableParam: false,
+    unique: "userRef",
   },
 } as const satisfies Record<PrimitiveSchema, PrimitiveTraits>
 

package/src/ontology/registry.ts

@@ -14,6 +14,7 @@ import {
 import type { ObjectTypeWithPropertyTokens } from "./tokens"
 import { createLinkTokenMap, createPropertyTokenMap } from "./tokens"
 import type { ObjectType, Schema, ValueType } from "./types"
+import { type UniquePropertyDefinition, uniquePropertiesOf } from "./unique-values"
 import {
   validatePrimaryProperties,
   validatePropertyDefinitions,
@@ -179,6 +180,7 @@ export class OntologyRegistry implements OntologyDefinitionCatalog {
   private readonly valueTypesById = new Map<string, ValueType>()
   private readonly subTypesById = new Map<string, Set<string>>()
   private readonly primaryByTypeId: Map<string, string>
+  private readonly uniqueByTypeId = new Map<string, readonly UniquePropertyDefinition[]>()
 
   constructor(options: OntologyRegistryOptions) {
     const { objectTypes, valueTypes } = collectOntology(options.sources)
@@ -209,6 +211,7 @@ export class OntologyRegistry implements OntologyDefinitionCatalog {
         })
     }
     this.primaryByTypeId = validatePrimaryProperties(this.objectTypesById)
+    this.indexUniqueProperties()
   }
 
   // ── Public read API ──────────────────────────────────────
@@ -244,6 +247,11 @@ export class OntologyRegistry implements OntologyDefinitionCatalog {
     return id
   }
 
+  /** The unique properties of a type, its inherited ones included. Empty for an unknown type. */
+  listUniqueProperties(objectTypeId: string): readonly UniquePropertyDefinition[] {
+    return this.uniqueByTypeId.get(objectTypeId) ?? []
+  }
+
   /** Collect all transitive sub-types of the given object type id. */
   listSubTypes(objectTypeId: string): string[] {
     const result: string[] = []
@@ -314,6 +322,14 @@ export class OntologyRegistry implements OntologyDefinitionCatalog {
 
   // ── Private initialization ───────────────────────────────
 
+  /** Every write consults the unique properties of its type: resolve their kinds once. */
+  private indexUniqueProperties(): void {
+    for (const [typeId, objectType] of this.objectTypesById) {
+      const unique = uniquePropertiesOf(objectType, this.valueTypesById)
+      if (unique.length > 0) this.uniqueByTypeId.set(typeId, unique)
+    }
+  }
+
   /**
    * Build the subtype graph from `extends` and `parents` declarations.
    *

package/src/ontology/types.ts

@@ -262,6 +262,15 @@ export interface Property {
    * Validation and runtime enforcement are handled separately.
    */
   primary?: true
+  /**
+   * Declares that each value of this property belongs to at most one object of the type, like an
+   * email or an external key. A write that would give a value to a second object is refused, and
+   * `getBy(Type.p.prop, value)` finds the object holding a value.
+   *
+   * Values compare exactly (case-sensitive), and `null` or absent values never count. Only strings,
+   * uuids, integers, dates, enums and user references can be unique, and only `true` is accepted.
+   */
+  unique?: true
   /**
    * Runtime behavior of this property's value.
    *

package/src/ontology/unique-values.ts

@@ -0,0 +1,84 @@
+/**
+ * Keys of unique property values.
+ *
+ * A property declared `unique: true` holds each value on at most one object of its exact type.
+ * Storage compares the values through the keys computed here, so every provider matches them the
+ * same way: strings exactly (case-sensitive, no trimming or Unicode normalization), integers by
+ * their decimal form and user references by user id. `null` and absent values have no key: any
+ * number of objects may hold them.
+ */
+import { primitiveTraits } from "./primitives"
+import type { ObjectType, Schema, ValueType } from "./types"
+import { isUserRef } from "./user-ref"
+
+/** How the values of a unique property compare. */
+export type UniqueValueKind = "string" | "integer" | "userRef"
+
+/**
+ * The version of the keys below. Storage records the version each property was prepared with:
+ * changing how keys are computed means bumping it, which rebuilds every unique property.
+ */
+export const UNIQUE_VALUE_KEY_VERSION = 1
+
+/** A unique property of an object type. */
+export interface UniquePropertyDefinition {
+  readonly propertyId: string
+  readonly kind: UniqueValueKind
+}
+
+/**
+ * The kind of a schema that can be unique, through value types: strings, uuids, dates, integers,
+ * string and integer enums, and user references. `undefined` for every other schema.
+ */
+export function uniqueValueKind(
+  schema: Schema,
+  valueTypesById: ReadonlyMap<string, ValueType>,
+  seenValueTypeIds: ReadonlySet<string> = new Set()
+): UniqueValueKind | undefined {
+  if (typeof schema === "string") return primitiveTraits(schema)?.unique
+
+  if (schema.type === "enum") return schema.valueType === "integer" ? "integer" : "string"
+
+  if (schema.type !== "valueTypeRef" || seenValueTypeIds.has(schema.valueTypeId)) {
+    return undefined
+  }
+
+  const resolved = schema._resolved ?? valueTypesById.get(schema.valueTypeId)?.schema
+  if (!resolved) return undefined
+
+  return uniqueValueKind(
+    resolved,
+    valueTypesById,
+    new Set([...seenValueTypeIds, schema.valueTypeId])
+  )
+}
+
+/** The unique properties of an object type, with how their values compare. */
+export function uniquePropertiesOf(
+  objectType: Pick<ObjectType, "properties">,
+  valueTypesById: ReadonlyMap<string, ValueType>
+): UniquePropertyDefinition[] {
+  const unique: UniquePropertyDefinition[] = []
+  for (const property of objectType.properties) {
+    if (!property.unique) continue
+    const kind = uniqueValueKind(property.schema, valueTypesById)
+    if (kind) unique.push({ propertyId: property.id, kind })
+  }
+  return unique
+}
+
+/**
+ * The key of a stored (validated and normalized) value, or `null` when the value claims nothing:
+ * `null`, absent, or not of the kind.
+ */
+export function uniqueValueKey(kind: UniqueValueKind, value: unknown): string | null {
+  switch (kind) {
+    case "string":
+      return typeof value === "string" ? value : null
+    // Integers beyond 2^53 lose precision as JSON numbers, but each still has one decimal form.
+    case "integer":
+      return Number.isInteger(value) ? String(value) : null
+    case "userRef":
+      return isUserRef(value) ? value.id : null
+  }
+}

package/src/ontology/user-ref.ts

@@ -35,6 +35,45 @@ export function isUserRef(value: unknown): value is UserRef {
   )
 }
 
+/**
+ * A `ref.user()` schema, or an array of them: the property schemas whose members a query can
+ * expand into profiles.
+ */
+export function isUserRefPropertySchema(schema: Schema): boolean {
+  if (schema === "userRef") return true
+  return typeof schema === "object" && schema.type === "array" && schema.items === "userRef"
+}
+
+/**
+ * The user reading, in a query predicate. The server binds it to the requester when the query runs:
+ * a query never stores or returns it.
+ */
+export type CurrentUserRef = { readonly type: "currentUser" }
+
+const CURRENT_USER: CurrentUserRef = Object.freeze({ type: "currentUser" })
+
+/**
+ * Match the user reading: `where(({ p }) => p.assignee.eq(currentUser()))`.
+ *
+ * Only query predicates on a `ref.user()` property accept it: `eq`, `neq`, `in`, and `contains`
+ * on a list of user references. It cannot be stored.
+ */
+export function currentUser(): CurrentUserRef {
+  return CURRENT_USER
+}
+
+/** Exactly `{ type: "currentUser" }`, the form `currentUser()` takes on the wire too. */
+export function isCurrentUser(value: unknown): value is CurrentUserRef {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false
+  const record = value as Record<string, unknown>
+  return Object.keys(record).length === 1 && record.type === "currentUser"
+}
+
+/** Why `subject` refuses `currentUser()`: it stands for the reader of a query, never for a value. */
+export function currentUserNotStorableMessage(subject: string): string {
+  return `${subject} cannot store currentUser(): it only stands for the user reading, in a query predicate. Store a user reference { type: "user", id } instead.`
+}
+
 /**
  * Collect the user ids a value holds at `userRef` positions of its schema, however deeply nested.
  *