@sixb/core 0.1.20 → 0.1.22

package/src/objects/query/user-expansions.ts

@@ -0,0 +1,65 @@
+import type { ObjectExpansion, ObjectQuery } from "./ir"
+
+/**
+ * The `ref.user()` properties a query expands, at its rows and under each expanded link.
+ *
+ * Profiles come from the member directory, not object storage, so the authorized reader attaches
+ * them to the rows storage returned.
+ */
+export interface UserExpansionPlan {
+  readonly users: readonly string[]
+  readonly links: readonly { readonly linkId: string; readonly plan: UserExpansionPlan }[]
+}
+
+/**
+ * Read the user expansions of a normalized query, or `undefined` when it has none.
+ *
+ * Only the outermost expand can carry them: normalization hoists expansions there, and validation
+ * refuses them on a set operand.
+ */
+export function userExpansionPlan(query: ObjectQuery): UserExpansionPlan | undefined {
+  if (query.kind !== "expand") return undefined
+  return planOf(query.users, query.expansions)
+}
+
+function planOf(
+  users: readonly string[] | undefined,
+  expansions: readonly ObjectExpansion[]
+): UserExpansionPlan | undefined {
+  const links = expansions.flatMap((expansion) => {
+    const plan = planOf(expansion.users, expansion.expand ?? [])
+    return plan ? [{ linkId: expansion.linkId, plan }] : []
+  })
+
+  if ((users === undefined || users.length === 0) && links.length === 0) return undefined
+  return { users: users ?? [], links }
+}
+
+/**
+ * The query storage runs: user expansions removed at every level, and an expand left with no link
+ * replaced by its input. A query that only expands user properties then plans like the plain query.
+ */
+export function withoutUserExpansions(query: ObjectQuery): ObjectQuery {
+  switch (query.kind) {
+    case "start":
+    case "refs":
+      return query
+    case "set":
+      return { ...query, inputs: query.inputs.map(withoutUserExpansions) }
+    case "expand": {
+      const input = withoutUserExpansions(query.input)
+      if (query.expansions.length === 0) return input
+
+      const { users: _users, ...expand } = query
+      return { ...expand, input, expansions: query.expansions.map(withoutExpansionUsers) }
+    }
+    default:
+      return { ...query, input: withoutUserExpansions(query.input) }
+  }
+}
+
+function withoutExpansionUsers(expansion: ObjectExpansion): ObjectExpansion {
+  const { users: _users, ...rest } = expansion
+  if (!rest.expand) return rest
+  return { ...rest, expand: rest.expand.map(withoutExpansionUsers) }
+}

package/src/objects/query/validate.ts

@@ -15,7 +15,12 @@ import {
   isTextSchema,
   queryScalarKindForSchema,
 } from "../../ontology/query-capabilities"
-import { validatePropertyValue, validateSchemaValue } from "../../ontology/validation"
+import { isCurrentUser, isUserRefPropertySchema } from "../../ontology/user-ref"
+import {
+  normalizeSchemaValue,
+  validatePropertyValue,
+  validateSchemaValue,
+} from "../../ontology/validation"
 import { MAX_VECTOR_K, normalizeVector, vectorConfiguration } from "../vectors/profile"
 import { hasVectorProfile, isVectorProfileQuery } from "../vectors/query"
 import { ObjectQueryValidationError } from "./errors"
@@ -516,6 +521,11 @@ function dispatchQueryNode(
     }
     case "expand": {
       const input = validateQueryNode(query.input, `${path}.input`, ctx)
+
+      // Profiles are read for the rows a query returns. On a set operand they would have no row to
+      // attach to, so only the outermost expand, where normalization puts it, may name them.
+      const usersAllowed = path === "$"
+
       // expand is output-shaping: it attaches links without changing the matched
       // set, so the result type is the input's result type.
       const expansions = validateExpansions(
@@ -523,8 +533,12 @@ function dispatchQueryNode(
         input.result,
         input.admissionState,
         `${path}.expansions`,
-        ctx
+        ctx,
+        usersAllowed
       )
+      validateUserExpansions(query.users, input.result, `${path}.users`, ctx, usersAllowed)
+      validateUserExpansionsProjected(query.users, input.query, `${path}.users`, ctx)
+
       return {
         result: input.result,
         query: { ...query, input: input.query, expansions },
@@ -642,7 +656,7 @@ function validatePredicate(
         path,
         ctx
       )
-      validatePredicateValue(predicate.propertyId, predicate.value, shape, path, ctx)
+      validatePredicateValue(predicate.propertyId, predicate.op, predicate.value, shape, path, ctx)
       admitProperty(ctx, {
         state: admissionState,
         propertyId: predicate.propertyId,
@@ -668,7 +682,14 @@ function validatePredicate(
         addIssue(ctx, path, "empty_in_values", "Predicate 'in' must include at least one value")
       }
       predicate.values.forEach((value, index) => {
-        validatePredicateValue(predicate.propertyId, value, shape, `${path}.values[${index}]`, ctx)
+        validatePredicateValue(
+          predicate.propertyId,
+          predicate.op,
+          value,
+          shape,
+          `${path}.values[${index}]`,
+          ctx
+        )
       })
       admitProperty(ctx, {
         state: admissionState,
@@ -694,6 +715,11 @@ function validatePredicate(
         addIssue(ctx, path, "invalid_exists_value", "Predicate 'exists' value must be boolean")
       }
       return predicate
+    case "constant":
+      if (typeof predicate.value !== "boolean") {
+        addIssue(ctx, path, "invalid_constant_value", "Predicate 'constant' value must be boolean")
+      }
+      return predicate
     case "contains": {
       const { scalarKind: _authoredScalarKind, ...authoredPredicate } = predicate
       const scalarKind = resolveAndValidatePredicateProperty(
@@ -813,13 +839,28 @@ function resolveValueTypeRefs(
   return resolved ? resolveValueTypeRefs(resolved, valueTypesById, seen) : undefined
 }
 
+/**
+ * Write a compared value in the form storage writes it. Stores compare dates and timestamps as
+ * their canonical text, so `…T02:00:00+02:00` and `…T00:00:00Z` only meet once both are canonical.
+ * A value that does not normalize stays as authored: validation reports it.
+ */
 function normalizeObjectQueryValue(value: unknown, scalarKind: QueryScalarKind | undefined) {
-  if (scalarKind !== "decimal" || typeof value !== "string") return value
   try {
-    return normalizeDecimalValue(value)
+    if (scalarKind === "decimal" && typeof value === "string") return normalizeDecimalValue(value)
+    if ((scalarKind === "date" || scalarKind === "timestamp") && isTemporalValue(value)) {
+      return normalizeSchemaValue(scalarKind, value, "predicate value", NO_VALUE_TYPES)
+    }
   } catch {
     return value
   }
+
+  return value
+}
+
+const NO_VALUE_TYPES: ReadonlyMap<string, ValueType> = new Map()
+
+function isTemporalValue(value: unknown): value is string | Date {
+  return typeof value === "string" || value instanceof Date
 }
 
 function resolveCommonQueryScalarKind(
@@ -849,11 +890,17 @@ function resolveCommonQueryScalarKind(
 
 function validatePredicateValue(
   propertyId: string,
+  op: ObjectQueryPredicate["op"],
   value: unknown,
   shape: ObjectQueryResultShape,
   path: string,
   ctx: QueryValidationContext
 ): void {
+  if (isCurrentUser(value)) {
+    validateCurrentUserPredicate(propertyId, op, shape, path, ctx)
+    return
+  }
+
   for (const { objectType, property } of getPropertiesForResult(propertyId, shape, path, ctx, {
     reportMissing: false,
   })) {
@@ -879,6 +926,11 @@ function validateContainsValue(
   path: string,
   ctx: QueryValidationContext
 ): void {
+  if (isCurrentUser(value)) {
+    validateCurrentUserPredicate(propertyId, "contains", shape, path, ctx)
+    return
+  }
+
   for (const { objectType, property } of getPropertiesForResult(propertyId, shape, path, ctx, {
     reportMissing: false,
   })) {
@@ -931,6 +983,53 @@ function validateContainsValue(
   }
 }
 
+/**
+ * `currentUser()` stands for a user reference: the executor replaces it with the reader's after
+ * validation, so it compares only where a user reference does. `eq`, `neq` and `in` take it on a
+ * `ref.user()` property, `contains` on a list of them.
+ */
+function validateCurrentUserPredicate(
+  propertyId: string,
+  op: ObjectQueryPredicate["op"],
+  shape: ObjectQueryResultShape,
+  path: string,
+  ctx: QueryValidationContext
+): void {
+  if (op !== "eq" && op !== "neq" && op !== "in" && op !== "contains") {
+    addIssue(
+      ctx,
+      path,
+      "current_user_operator_not_supported",
+      `Predicate '${op}' cannot compare currentUser(); use eq, neq, in, or contains.`
+    )
+    return
+  }
+
+  for (const { objectType, property } of getPropertiesForResult(propertyId, shape, path, ctx, {
+    reportMissing: false,
+  })) {
+    if (holdsUserReferences(property.schema, op === "contains", ctx)) continue
+
+    addIssue(
+      ctx,
+      path,
+      "current_user_requires_user_reference",
+      op === "contains"
+        ? `currentUser() can only be found in a list of ref.user() values; '${objectType.id}.${property.id}' is not one.`
+        : `currentUser() can only be compared with a ref.user() property; '${objectType.id}.${property.id}' is not one.`
+    )
+  }
+}
+
+/** Whether the schema is a user reference or, for `contains`, a list of them. */
+function holdsUserReferences(schema: Schema, list: boolean, ctx: QueryValidationContext): boolean {
+  const resolved = resolveValueTypeRefs(schema, ctx.valueTypesById)
+  if (!list) return resolved === "userRef"
+
+  if (typeof resolved !== "object" || resolved.type !== "array") return false
+  return resolveValueTypeRefs(resolved.items, ctx.valueTypesById) === "userRef"
+}
+
 function validateTextQuery(
   query: string,
   fields: readonly string[] | undefined,
@@ -1221,10 +1320,11 @@ function validateExpansions(
   shape: ObjectQueryResultShape,
   admissionState: ObjectQueryAdmissionState,
   path: string,
-  ctx: QueryValidationContext
+  ctx: QueryValidationContext,
+  usersAllowed: boolean
 ): ObjectExpansion[] {
   return expansions.map((expansion, index) =>
-    validateExpansion(expansion, shape, admissionState, `${path}[${index}]`, ctx)
+    validateExpansion(expansion, shape, admissionState, `${path}[${index}]`, ctx, usersAllowed)
   )
 }
 
@@ -1233,7 +1333,8 @@ function validateExpansion(
   shape: ObjectQueryResultShape,
   admissionState: ObjectQueryAdmissionState,
   path: string,
-  ctx: QueryValidationContext
+  ctx: QueryValidationContext,
+  usersAllowed: boolean
 ): ObjectExpansion {
   if (!expansion.linkId) {
     addIssue(ctx, path, "missing_expand_link", "expand.linkId is required")
@@ -1289,12 +1390,149 @@ function validateExpansion(
       )
     : undefined
   const expand = expansion.expand
-    ? validateExpansions(expansion.expand, targetShape, targetAdmissionState, `${path}.expand`, ctx)
+    ? validateExpansions(
+        expansion.expand,
+        targetShape,
+        targetAdmissionState,
+        `${path}.expand`,
+        ctx,
+        usersAllowed
+      )
     : undefined
+  validateUserExpansions(expansion.users, targetShape, `${path}.users`, ctx, usersAllowed)
 
   return { ...expansion, orderBy, expand }
 }
 
+/**
+ * Each expanded user property must be a `ref.user()` property, or an array of them, on at least
+ * one type of the shape, like an expanded link. Telemetry cannot hold user references.
+ *
+ * No admission sees it: a profile is never returned to a delegated reader, and a marked value the
+ * reader cannot read is removed before its profile would be looked up.
+ *
+ * `usersAllowed` is false under any expand but the outermost one, at every depth.
+ */
+function validateUserExpansions(
+  users: readonly string[] | undefined,
+  shape: ObjectQueryResultShape,
+  path: string,
+  ctx: QueryValidationContext,
+  usersAllowed: boolean
+): void {
+  if (users === undefined) return
+
+  if (!Array.isArray(users)) {
+    addIssue(ctx, path, "invalid_user_expansion", "expand.users must be an array of property ids")
+    return
+  }
+
+  if (!usersAllowed && users.length > 0) {
+    addIssue(
+      ctx,
+      path,
+      "invalid_user_expansion",
+      "Only the outermost expand can expand user properties; a set operand cannot."
+    )
+    return
+  }
+
+  users.forEach((propertyId, index) => {
+    const propertyPath = `${path}[${index}]`
+
+    if (typeof propertyId !== "string" || propertyId.length === 0) {
+      addIssue(ctx, propertyPath, "invalid_user_expansion", "expand.users ids must not be empty")
+      return
+    }
+
+    const declared = getPropertiesForResult(propertyId, shape, propertyPath, ctx, {
+      reportMissing: false,
+    })
+    if (declared.length === 0) {
+      addIssue(
+        ctx,
+        propertyPath,
+        "unknown_property",
+        `Expansion references property '${propertyId}' not present on result type ${shape.objectTypeIds.join(
+          " | "
+        )} (an expand abandoned by a later traverse?)`
+      )
+      return
+    }
+
+    for (const { objectType, property } of declared) {
+      if (isUserRefPropertySchema(property.schema)) continue
+      addIssue(
+        ctx,
+        propertyPath,
+        "invalid_user_expansion",
+        `Property '${propertyId}' on '${objectType.id}' is not a ref.user() property; expand() takes a link or a user property.`
+      )
+    }
+  })
+}
+
+/**
+ * A projection that leaves out an expanded user property would make its profile read as "no
+ * user". Refuse it instead.
+ */
+function validateUserExpansionsProjected(
+  users: readonly string[] | undefined,
+  input: ObjectQuery,
+  path: string,
+  ctx: QueryValidationContext
+): void {
+  if (!Array.isArray(users)) return
+
+  const projected = projectedProperties(input)
+  if (projected === undefined) return
+
+  users.forEach((propertyId, index) => {
+    if (projected.includes(propertyId)) return
+    addIssue(
+      ctx,
+      `${path}[${index}]`,
+      "invalid_user_expansion",
+      `Expanded user property '${propertyId}' must be projected too.`
+    )
+  })
+}
+
+/**
+ * The properties a row keeps, from the projections below the expand on the same result type, or
+ * `undefined` when every property is kept. A set keeps only what each operand keeps.
+ */
+function projectedProperties(query: ObjectQuery): readonly string[] | undefined {
+  switch (query.kind) {
+    case "project":
+      return query.properties
+    case "set":
+      return keptByEveryOperand(query.inputs.map(projectedProperties))
+    case "filter":
+    case "text":
+    case "vector":
+    case "rerank":
+    case "sort":
+    case "limit":
+    case "page":
+      return projectedProperties(query.input)
+    default:
+      return undefined
+  }
+}
+
+// An operand without a projection keeps every property, so it narrows nothing.
+function keptByEveryOperand(
+  projections: readonly (readonly string[] | undefined)[]
+): readonly string[] | undefined {
+  const projected = projections.filter((properties) => properties !== undefined)
+  if (projected.length === 0) return undefined
+
+  return projected.reduce((kept, properties) =>
+    kept.filter((propertyId) => properties.includes(propertyId))
+  )
+}
+
 function resolveOutgoingExpansionTargets(
   linkId: string,
   sourceObjectTypeId: string | undefined,

package/src/objects/runtime-batch.ts

@@ -6,7 +6,11 @@
  * repeat is rejected, and each item's Materializer outcomes map back to the position they came from.
  */
 
-import type { OntologyEditOperation, OntologyOperationOutcome } from "../materialization/model"
+import type {
+  ExpectedObjectRevision,
+  OntologyEditOperation,
+  OntologyOperationOutcome,
+} from "../materialization/model"
 import { OntologyValidationError } from "../ontology/errors"
 import type { BatchItemResult } from "../runtime/types"
 import {
@@ -33,6 +37,8 @@ export interface RuntimeItemBatch<TItem, TValue> {
   plan(item: TItem, index: number): RuntimeBatchItemPlan
   /** Maps the outcomes of a fully successful item to its public value. */
   value(outcomes: readonly OntologyOperationOutcome[]): TValue
+  /** Objects as the batch's author read them: one that changed fails the whole batch. */
+  readonly expectedObjects?: readonly ExpectedObjectRevision[]
 }
 
 interface PlannedItem {
@@ -88,7 +94,7 @@ export async function runRuntimeItemBatch<TItem, TValue>(
     planned.push({ index, operations: plan.operations })
   }
 
-  const commit = await commitRuntimeBatch(batch.ctx, planned)
+  const commit = await commitRuntimeBatch(batch.ctx, planned, batch.expectedObjects)
 
   for (const { index } of planned) {
     const outcomes = requireItemOutcomes(commit, index)

package/src/objects/sdk/object-set.ts

@@ -12,7 +12,8 @@ import { shareSixbErrorReporter } from "../../error-reporting/capability"
 import type { ExecutionContext } from "../../execution"
 import { assertAuthorizedObjectReaderBinding } from "../../execution/authorized-object-reader"
 import { OntologyValidationError } from "../../ontology/errors"
-import type { ObjectTypeWithPropertyTokens } from "../../ontology/tokens"
+import type { ObjectTypeWithPropertyTokens, PropertyToken } from "../../ontology/tokens"
+import { assertPropertyTokenBelongsToObjectType } from "../../ontology/validation"
 import { shareOntologyMutationRuntime } from "../../runtime/ontology-mutations"
 import type {
   ObjectSet,
@@ -97,6 +98,16 @@ export function createObjectSet<TObjectType extends ObjectTypeWithPropertyTokens
       return row ? (row as unknown as TwinObject<TObjectType>) : null
     },
 
+    getBy: async (property: PropertyToken, value: unknown) => {
+      assertPropertyTokenBelongsToObjectType(objectType, property)
+      const row = await objectReader.getByUniqueValue({
+        objectTypeId: objectType.id,
+        propertyId: property.id,
+        value,
+      })
+      return row ? (row as unknown as TwinObject<TObjectType>) : null
+    },
+
     upsert: async (input: { properties: Record<string, unknown> }) => {
       const row = await upsertObjectLeaf(resolvedCtx, input.properties)
       return row as unknown as TwinObject<TObjectType>

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)
+}