@sixb/core 0.1.3 → 0.1.4

package/src/agents/streams.ts

@@ -4,6 +4,7 @@ import type { SixbFailure } from "../errors/types"
 import { isJsonValue, isPlainRecord, type JsonValue } from "../json"
 import {
   AGENT_RUN_FAILURE_CODES,
+  type AgentContextCheckpointReason,
   type AgentRunFailureCode,
   type AgentRunRecord,
 } from "../storage/agents/types"
@@ -189,11 +190,35 @@ export async function subscribeAgentRunCancel(
 /** Exact portable failure exposed by a terminal Agent run stream event. */
 export type AgentRunFailure = SixbFailure<AgentRunFailureCode>
 
+export const AGENT_COMPACTION_FAILURE_CODES = [
+  "context_limit_exceeded",
+  "summary_failed",
+  "checkpoint_failed",
+] as const
+export type AgentCompactionFailureCode = (typeof AGENT_COMPACTION_FAILURE_CODES)[number]
+
 export type AgentRunStreamEvent =
   | (AgentRunStreamEventBase & {
       readonly type: "agent.run.started"
       readonly modelId?: string
     })
+  | (AgentRunStreamEventBase & {
+      readonly type: "agent.compaction.started"
+      readonly reason: AgentContextCheckpointReason
+      readonly estimatedInputTokensBefore: number
+    })
+  | (AgentRunStreamEventBase & {
+      readonly type: "agent.compaction.completed"
+      readonly reason: AgentContextCheckpointReason
+      readonly checkpointId: string
+      readonly estimatedInputTokensBefore: number
+      readonly estimatedInputTokensAfter: number
+    })
+  | (AgentRunStreamEventBase & {
+      readonly type: "agent.compaction.failed"
+      readonly reason: AgentContextCheckpointReason
+      readonly errorCode: AgentCompactionFailureCode
+    })
   | (AgentRunStreamEventBase & {
       readonly type: "agent.ui.chunk"
       readonly chunkIndex: number
@@ -263,6 +288,23 @@ export function isAgentRunStreamEvent(value: unknown): value is AgentRunStreamEv
   switch (value.type) {
     case "agent.run.started":
       return value.modelId === undefined || typeof value.modelId === "string"
+    case "agent.compaction.started":
+      return (
+        isAgentContextCheckpointReason(value.reason) &&
+        isTokenEstimate(value.estimatedInputTokensBefore)
+      )
+    case "agent.compaction.completed":
+      return (
+        isAgentContextCheckpointReason(value.reason) &&
+        typeof value.checkpointId === "string" &&
+        isTokenEstimate(value.estimatedInputTokensBefore) &&
+        isTokenEstimate(value.estimatedInputTokensAfter)
+      )
+    case "agent.compaction.failed":
+      return (
+        isAgentContextCheckpointReason(value.reason) &&
+        AGENT_COMPACTION_FAILURE_CODES.includes(value.errorCode as AgentCompactionFailureCode)
+      )
     case "agent.ui.chunk":
       return (
         Number.isInteger(value.chunkIndex) &&
@@ -282,6 +324,14 @@ export function isAgentRunStreamEvent(value: unknown): value is AgentRunStreamEv
   }
 }
 
+function isAgentContextCheckpointReason(value: unknown): value is AgentContextCheckpointReason {
+  return value === "threshold" || value === "overflow"
+}
+
+function isTokenEstimate(value: unknown): value is number {
+  return Number.isSafeInteger(value) && (value as number) >= 0
+}
+
 function isTerminalAgentRunStatus(value: unknown): value is "succeeded" | "failed" | "cancelled" {
   return value === "succeeded" || value === "failed" || value === "cancelled"
 }
@@ -305,6 +355,12 @@ export function agentRunStreamIdempotencyKey(event: AgentRunStreamEvent): string
   switch (event.type) {
     case "agent.run.started":
       return `${event.runId}:${event.attempt}:started`
+    case "agent.compaction.started":
+      return `${event.runId}:${event.attempt}:compaction:${event.reason}:started`
+    case "agent.compaction.completed":
+      return `${event.runId}:${event.attempt}:compaction:${event.checkpointId}:completed`
+    case "agent.compaction.failed":
+      return `${event.runId}:${event.attempt}:compaction:${event.reason}:failed:${event.errorCode}`
     case "agent.ui.chunk":
       return `${event.runId}:${event.attempt}:chunk:${event.chunkIndex}`
     case "agent.message.finalized":

package/src/agents/types.ts

@@ -26,6 +26,15 @@ export const AGENT_REASONING_LEVELS = [
   "xhigh",
 ] as const satisfies readonly AgentReasoningLevel[]
 
+export interface AgentContextConfig {
+  /** Override the provider context-window size inferred by the agent worker. */
+  readonly windowTokens?: number
+  /** Tokens reserved for the next response and compaction work. */
+  readonly reserveTokens?: number
+  /** Approximate recent-message budget retained verbatim after compaction. */
+  readonly keepRecentTokens?: number
+}
+
 /**
  * Loop / stop controls for an agent run.
  *
@@ -35,6 +44,7 @@ export interface AgentLoopConfig {
   readonly stopWhen?: {
     readonly maxSteps?: number
   }
+  readonly context?: AgentContextConfig
 }
 
 type Simplify<T> = { [K in keyof T]: T[K] } & {}

package/src/agents/validation.ts

@@ -10,6 +10,7 @@ import type { GroupDefinition, SecurityDefinitionCatalog } from "../security"
 import { AgentDefinitionError } from "./errors"
 import {
   AGENT_REASONING_LEVELS,
+  type AgentContextConfig,
   type AgentDefinition,
   type AgentLoopConfig,
   type AgentReasoningLevel,
@@ -159,14 +160,43 @@ export function validateAgentToolsAtStartup(agents: readonly AgentDefinition[]):
   }
 }
 
-export function assertValidLoopConfig(loop: AgentLoopConfig | undefined): void {
+export function resolveAgentLoopConfig(
+  loop: AgentLoopConfig | undefined
+): AgentLoopConfig | undefined {
+  if (loop === undefined) return undefined
+
   const maxSteps = loop?.stopWhen?.maxSteps
-  if (maxSteps === undefined) {
-    return
+  if (maxSteps !== undefined && (!Number.isSafeInteger(maxSteps) || maxSteps <= 0)) {
+    throw new AgentDefinitionError(
+      "[Sixb] Agent loop.stopWhen.maxSteps must be a positive safe integer."
+    )
+  }
+
+  const context = loop.context ? snapshotAgentContextConfig(loop.context) : undefined
+  return Object.freeze({
+    ...(loop.stopWhen === undefined
+      ? {}
+      : { stopWhen: Object.freeze({ ...(maxSteps === undefined ? {} : { maxSteps }) }) }),
+    ...(context === undefined ? {} : { context }),
+  })
+}
+
+function snapshotAgentContextConfig(context: AgentContextConfig): AgentContextConfig {
+  const snapshot: Record<string, number> = {}
+  for (const field of ["windowTokens", "reserveTokens", "keepRecentTokens"] as const) {
+    const value = context[field]
+    if (value === undefined) continue
+    assertPositiveSafeInteger(value, field)
+    snapshot[field] = value
   }
-  if (!Number.isInteger(maxSteps) || maxSteps <= 0) {
+
+  return Object.freeze(snapshot)
+}
+
+function assertPositiveSafeInteger(value: unknown, field: string): asserts value is number {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
     throw new AgentDefinitionError(
-      "[Sixb] Agent loop.stopWhen.maxSteps must be a positive finite integer."
+      `[Sixb] Agent loop.context.${field} must be a positive safe integer.`
     )
   }
 }

package/src/http/api-routes.ts

@@ -131,6 +131,13 @@ export const SIXB_API_ROUTES: readonly SixbApiRoute[] = [
     accessToken: true,
     agentApi: true,
   },
+  {
+    operationId: "queryObjectLinks",
+    method: "POST",
+    path: "/api/objects/query/links",
+    accessToken: true,
+    agentApi: true,
+  },
   {
     operationId: "countObjects",
     method: "POST",
@@ -159,13 +166,6 @@ export const SIXB_API_ROUTES: readonly SixbApiRoute[] = [
     accessToken: true,
     agentApi: true,
   },
-  {
-    operationId: "listObjectLinks",
-    method: "GET",
-    path: "/api/objects/:objectTypeId/:objectId/links",
-    accessToken: true,
-    agentApi: true,
-  },
   // The four write routes. Bearer-capable because their execution facade enforces authorization
   // (`edit:object` / `append:telemetry`), which is exactly the precondition this table requires.
   // NOT agent-proxied: letting an agent turn write objects on its own is a separate decision, and

package/src/index.ts

@@ -574,6 +574,7 @@ export type {
   ObjectQueryPredicateIn,
   ObjectQueryPredicateNot,
   ObjectQueryProject,
+  ObjectQueryRefs,
   ObjectQueryResultShape,
   ObjectQuerySet,
   ObjectQuerySetOperation,
@@ -854,6 +855,8 @@ export type {
 export type {
   ExecutionObjectByIdHandle,
   ExecutionObjectSet,
+  ObjectQueryLinksInput,
+  ObjectQueryLinksResult,
   ObjectsRuntime,
 } from "./objects/execution"
 export type { PipelineRunsRuntime, PipelinesRuntime } from "./pipelines/execution"
@@ -941,6 +944,7 @@ export type {
 // ── Agents ──────────────────────────────────────────────────
 
 export type {
+  AgentContextConfig,
   AgentContextEntryInput,
   AgentContextInput,
   AgentContextOrigin,
@@ -1013,6 +1017,15 @@ export {
   requestAgentRun,
 } from "./agents"
 
+// ── Models ──────────────────────────────────────────────────
+
+export type {
+  LanguageModelCatalog,
+  LanguageModelEntry,
+  ModelCatalog,
+  ModelCatalogInput,
+} from "./models"
+
 // ── Scheduling ──────────────────────────────────────────────
 
 export { CronValidationError } from "./schedules"
@@ -1034,6 +1047,7 @@ export type {
   ProjectionTargetByKind,
   SourceEditConflictResolution,
   TelemetryProjectionDefinition,
+  TelemetryProjectionPropertyMapping,
 } from "./projections"
 
 export {

package/src/lake-storage/types.ts

@@ -84,7 +84,8 @@ export interface DatasetWriteCommitResult extends DatasetVersion {
    * report `unchanged` and reuse it for commits that cannot change visible
    * dataset content: a snapshot whose rows equal the latest visible rows
    * (order-insensitive, with equal duplicate counts), or an append of zero
-   * rows.
+   * rows. Without a latest version, an empty snapshot or append still creates
+   * the first addressable dataset version.
    */
   readonly outcome: "created" | "unchanged"
 }

package/src/materializer/telemetry/append.ts

@@ -90,7 +90,6 @@ function prepareTelemetryAppend(
     points: raw.input.points.map((point) => validateTelemetryPoint(context.ontology, point)),
   })
   const inputPointCount = telemetryInputPointCount(input, rawInputPointCount)
-  validateTelemetryBatch(input, inputPointCount)
 
   const ontologyRevision = context.projectionRegistry.ontologyRevision
   const execution = prepareMaterializerExecution(context.projectId, raw.scope)
@@ -114,21 +113,6 @@ function telemetryInputPointCount(
   return input.points.length
 }
 
-function validateTelemetryBatch(input: NormalizedTelemetryAppend, inputPointCount: number): void {
-  if (input.source.kind === "projection") {
-    if (input.source.sourceRowCount === 0) {
-      throw new MaterializationValidationError(
-        "Projection telemetry batches must consume at least one source row; an empty dataset produces no batch commit."
-      )
-    }
-    if (input.source.sourceRowCount !== inputPointCount + input.source.sourceRowsSkipped) {
-      throw new MaterializationValidationError(
-        "Projection telemetry sourceRowCount must equal input points plus skipped rows."
-      )
-    }
-  }
-}
-
 function prepareRuntimeTelemetry(
   context: Pick<MaterializerContext, "projectId" | "clock">,
   input: NormalizedTelemetryAppend,
@@ -157,6 +141,7 @@ function prepareProjectionTelemetry(
   )
   validateTelemetryProjectionDataset(resolvedProjection, source)
   validateTelemetryOwnership(resolvedProjection, input)
+  validateTelemetryBatchCardinality(resolvedProjection, source, inputPointCount)
 
   const runIdentity = createProjectionRunMaterializationIdentity({
     resolved: resolvedProjection,
@@ -182,6 +167,38 @@ function prepareProjectionTelemetry(
   }
 }
 
+function validateTelemetryBatchCardinality(
+  resolved: ResolvedTelemetryProjection,
+  source: ProjectionTelemetrySource,
+  inputPointCount: number
+): void {
+  if (source.sourceRowCount === 0) {
+    throw new MaterializationValidationError(
+      "Projection telemetry batches must consume at least one source row; an empty dataset produces no batch commit."
+    )
+  }
+
+  const mappedPropertyCount = resolved.ownership.telemetry.length
+  if (mappedPropertyCount === 0) {
+    throw new MaterializationValidationError(
+      `Telemetry projection '${resolved.projectionId}' must own at least one telemetry property.`
+    )
+  }
+
+  const sourceRowsEmitted = source.sourceRowCount - source.sourceRowsSkipped
+  const maximumPointCount = sourceRowsEmitted * mappedPropertyCount
+  if (!Number.isSafeInteger(maximumPointCount)) {
+    throw new MaterializationValidationError(
+      `Telemetry projection '${resolved.projectionId}' batch point capacity exceeds the safe integer range.`
+    )
+  }
+  if (inputPointCount < sourceRowsEmitted || inputPointCount > maximumPointCount) {
+    throw new MaterializationValidationError(
+      `Telemetry projection '${resolved.projectionId}' must emit between ${sourceRowsEmitted} and ${maximumPointCount} points for ${source.sourceRowCount} source rows with ${source.sourceRowsSkipped} skipped.`
+    )
+  }
+}
+
 function validateTelemetryProjectionDataset(
   resolved: ResolvedTelemetryProjection,
   source: ProjectionTelemetrySource

package/src/models/index.ts

@@ -0,0 +1,71 @@
+import type { LanguageModelV4 } from "@ai-sdk/provider"
+import { createDefinitionCatalog, type DefinitionCatalog } from "../runtime/definitions"
+import { RuntimeError } from "../runtime/errors"
+
+/** The configured language models, with the project default. */
+export interface LanguageModelCatalog extends DefinitionCatalog<LanguageModelEntry> {
+  readonly default: LanguageModelEntry
+}
+
+/**
+ * One configured language model.
+ *
+ * `ref` is derived, never author-supplied, and stays internal to the runtime: it identifies the
+ * configured binding, not a vendor model. The AI SDK's `provider` names the binding, so
+ * `openai.chat(...)` and `openai.responses(...)` are distinct entries even for one vendor model,
+ * and neither matches the canonical id the worker resolves for billing
+ * (`SDK_PROVIDER_BINDINGS` in `@sixb/agent-worker`). Anything user-facing should key on
+ * `provider` + `modelId` instead.
+ */
+export interface LanguageModelEntry {
+  readonly ref: string
+  readonly provider: string
+  readonly modelId: string
+  readonly model: LanguageModelV4
+}
+
+/** Models a project allows Sixb to use, organized by technical model kind. */
+export interface ModelCatalog {
+  readonly language: LanguageModelCatalog
+}
+
+export interface ModelCatalogInput {
+  /** Ordered; the first entry is the project default. */
+  readonly language: readonly LanguageModelV4[]
+}
+
+/**
+ * Identify a catalog entry by the binding its model was constructed from.
+ *
+ * `gateway("openai/gpt-5.4")` and `openai("gpt-5.4")` are different entries on purpose: they route
+ * differently and bill differently. See {@link LanguageModelEntry}.
+ */
+export function modelRef(model: LanguageModelV4): string {
+  return `${model.provider}/${model.modelId}`
+}
+
+/** Build the immutable project model catalog. Rejects duplicates and an empty catalog. */
+export function createModelCatalog(input: ModelCatalogInput): ModelCatalog {
+  const byRef = new Map<string, LanguageModelEntry>()
+
+  for (const model of input.language) {
+    const ref = modelRef(model)
+    if (byRef.has(ref)) {
+      throw new RuntimeError(
+        `[Sixb] Duplicate language model '${ref}' in 'models'. Each provider and model id pair may be configured once.`
+      )
+    }
+    byRef.set(ref, Object.freeze({ ref, provider: model.provider, modelId: model.modelId, model }))
+  }
+
+  const [defaultEntry] = byRef.values()
+  if (defaultEntry === undefined) {
+    throw new RuntimeError(
+      "[Sixb] 'models.language' needs at least one model. Configure one or omit 'models' from createSixb()."
+    )
+  }
+
+  return Object.freeze({
+    language: Object.freeze({ ...createDefinitionCatalog(byRef), default: defaultEntry }),
+  })
+}

package/src/objects/execution.ts

@@ -29,8 +29,11 @@ import {
   type ExecuteObjectFacetsInput,
   type ExecuteObjectFacetsResult,
   type ExecuteObjectQueryInput,
+  type ExecuteObjectQueryLinksInput,
+  type ExecuteObjectQueryLinksResult,
   type ExecuteObjectQueryResult,
   executeObjectQuery,
+  executeObjectQueryLinks,
   existsObjects,
   facetObjects,
 } from "./query"
@@ -121,6 +124,12 @@ export interface ExecutionObjectSet<
   byId(id: string): ExecutionObjectByIdHandle<TObjectType, TValueTypes>
 }
 
+/** Public input for querying physical links incident to an object query result. */
+export type ObjectQueryLinksInput = Omit<ExecuteObjectQueryLinksInput, "projectId">
+
+/** Public result returned by {@link ObjectsRuntime.queryLinks}. */
+export type ObjectQueryLinksResult = ExecuteObjectQueryLinksResult
+
 export interface ObjectsRuntime<TOntologySources extends readonly OntologySource[]>
   extends ExecutionObjectOperations {
   <TObjectType extends RegisteredObjectType<TOntologySources>>(
@@ -131,6 +140,7 @@ export interface ObjectsRuntime<TOntologySources extends readonly OntologySource
     RegisteredObjectType<TOntologySources>
   >
   executeQuery(input: Omit<ExecuteObjectQueryInput, "projectId">): Promise<ExecuteObjectQueryResult>
+  queryLinks(input: ObjectQueryLinksInput): Promise<ObjectQueryLinksResult>
   count(input: Omit<ExecuteObjectCountInput, "projectId">): Promise<ExecuteObjectCountResult>
   exists(input: Omit<ExecuteObjectExistsInput, "projectId">): Promise<ExecuteObjectExistsResult>
   facet(input: Omit<ExecuteObjectFacetsInput, "projectId">): Promise<ExecuteObjectFacetsResult>
@@ -208,6 +218,16 @@ export function createObjectsRuntime<TOntologySources extends readonly OntologyS
             authorization: runtime.authorization,
           }
         ),
+      queryLinks: (input: ObjectQueryLinksInput) =>
+        executeObjectQueryLinks(
+          { projectId: runtime.projectId, ...input },
+          {
+            ontology: runtime.ontology,
+            storage: runtime.storage.objects,
+            runtimeAuthorization: runtime.runtimeAuthorization,
+            authorization: runtime.authorization,
+          }
+        ),
       count: (input: Omit<ExecuteObjectCountInput, "projectId">) =>
         countObjects(
           { projectId: runtime.projectId, ...input },

package/src/objects/link/endpoints.ts

@@ -7,6 +7,7 @@
  */
 
 import type { SixbRuntimeContext } from "../../runtime/types"
+import { objectBatchKey } from "../../storage"
 import { ObjectNotFoundError } from "../../storage/errors"
 
 export interface LinkEndpointItem {
@@ -62,5 +63,5 @@ export function requireEndpoints(item: LinkEndpointItem, existing: EndpointExist
 }
 
 function endpointKey(objectTypeId: string, primaryId: string): string {
-  return `${objectTypeId}:${primaryId}`
+  return objectBatchKey(objectTypeId, primaryId)
 }

package/src/objects/query/executor.ts

@@ -7,6 +7,7 @@ import type {
   ExpandedLinkValue,
   ExpandedObjectRow,
   FacetObjectsResult,
+  ObjectBatchKey,
   ObjectFacetRequest,
   ObjectFacetResult,
   ObjectLinkRow,
@@ -16,6 +17,7 @@ import type {
   ObjectStorage,
   QueryObjectsResult,
 } from "../../storage"
+import { linkBatchKey, objectBatchKey } from "../../storage"
 import {
   ObjectQueryExecutionError,
   ObjectQueryPlanningError,
@@ -52,6 +54,7 @@ export interface QueryExecutorOptions
   storage: ObjectStorage
   maxLimit?: number
   maxPageSize?: number
+  maxRefs?: number
   maxFacetLimit?: number
   /**
    * Per-parent cap on how many links a single `expand` hydrates, applied as a
@@ -132,6 +135,7 @@ export async function executeObjectQuery(
     ontology: options.ontology,
     maxLimit: options.maxLimit,
     maxPageSize: options.maxPageSize,
+    maxRefs: options.maxRefs,
     normalize: false,
   })
   assertQueryViewable(validated, options)
@@ -199,6 +203,7 @@ export async function countObjects(
     ontology: options.ontology,
     maxLimit: options.maxLimit,
     maxPageSize: options.maxPageSize,
+    maxRefs: options.maxRefs,
     normalize: false,
   })
   assertQueryViewable(validated, options)
@@ -259,6 +264,7 @@ export async function existsObjects(
     ontology: options.ontology,
     maxLimit: options.maxLimit,
     maxPageSize: options.maxPageSize,
+    maxRefs: options.maxRefs,
     normalize: false,
   })
   assertQueryViewable(validated, options)
@@ -319,6 +325,7 @@ export async function facetObjects(
     ontology: options.ontology,
     maxLimit: options.maxLimit,
     maxPageSize: options.maxPageSize,
+    maxRefs: options.maxRefs,
     normalize: false,
   })
   assertQueryViewable(validated, options)
@@ -435,6 +442,7 @@ function resolveExpansions(query: ObjectQuery, ctx: ExpansionResolutionContext):
       }
     }
     case "start":
+    case "refs":
       return query
     case "set":
       return {
@@ -555,6 +563,8 @@ function expandIncludeSubtypes(query: ObjectQuery, ontology: OntologyRegistry):
         inputs: objectTypeIds.map((objectTypeId) => ({ kind: "start", objectTypeId })),
       }
     }
+    case "refs":
+      return query
     case "filter":
     case "text":
     case "vector":
@@ -598,6 +608,8 @@ async function evaluateFallbackQuery(
   switch (query.kind) {
     case "start":
       return evaluateFallbackStart(projectId, query, options, maxRows)
+    case "refs":
+      return evaluateFallbackRefs(projectId, query, options)
     case "filter": {
       const input = await evaluateFallbackQuery(projectId, query.input, options, maxRows)
       return completeFallbackEvaluation(
@@ -672,6 +684,23 @@ async function evaluateFallbackQuery(
   }
 }
 
+async function evaluateFallbackRefs(
+  projectId: string,
+  query: Extract<ObjectQuery, { kind: "refs" }>,
+  options: QueryExecutorOptions
+): Promise<FallbackEvaluation> {
+  const rows = await options.storage.getByPrimaryIdBatch({
+    projectId,
+    items: query.refs,
+  })
+  return completeFallbackEvaluation(
+    query.refs.flatMap((ref, order) => {
+      const row = rows.get(objectBatchKey(ref.objectTypeId, ref.primaryId))
+      return row ? [{ row, order }] : []
+    })
+  )
+}
+
 /**
  * A candidate neighbour for one parent under a single expansion: the object to
  * hydrate plus the metadata carried on the link edge. For outgoing expansions
@@ -769,7 +798,9 @@ async function collectOutgoingEdges(
   })
 
   return parents.map((parent) => {
-    const links = linksByKey.get(`${parent.objectTypeId}:${parent.primaryId}:${expansion.linkId}`)
+    const links = linksByKey.get(
+      linkBatchKey(parent.objectTypeId, parent.primaryId, expansion.linkId)
+    )
     if (!links) return []
     return links.map((link) => ({
       neighborTypeId: link.targetTypeId,
@@ -821,8 +852,8 @@ async function fetchExpansionTargets(
   projectId: string,
   edgesByParent: readonly ExpansionEdge[][],
   options: QueryExecutorOptions
-): Promise<Map<string, ObjectRow>> {
-  const seen = new Set<string>()
+): Promise<ReadonlyMap<ObjectBatchKey, ObjectRow>> {
+  const seen = new Set<ObjectBatchKey>()
   const items: { objectTypeId: string; primaryId: string }[] = []
   for (const edges of edgesByParent) {
     for (const edge of edges) {
@@ -841,10 +872,10 @@ async function fetchExpansionTargets(
 async function enrichExpansionTargets(
   projectId: string,
   trimmedByParent: readonly ExpansionEdge[][],
-  baseTargets: Map<string, ObjectRow>,
+  baseTargets: ReadonlyMap<ObjectBatchKey, ObjectRow>,
   expansion: ObjectExpansion,
   options: QueryExecutorOptions
-): Promise<Map<string, ObjectRow>> {
+): Promise<ReadonlyMap<ObjectBatchKey, ObjectRow>> {
   if (!expansion.expand || expansion.expand.length === 0) {
     return baseTargets
   }
@@ -862,7 +893,7 @@ async function enrichExpansionTargets(
   }
 
   const enriched = await hydrateExpansions(projectId, uniqueTargets, expansion.expand, options)
-  const enrichedByKey = new Map<string, ObjectRow>()
+  const enrichedByKey = new Map<ObjectBatchKey, ObjectRow>()
   for (const row of enriched) {
     enrichedByKey.set(targetKey(row.objectTypeId, row.primaryId), row)
   }
@@ -872,7 +903,7 @@ async function enrichExpansionTargets(
 function trimExpansionEdges(
   edges: readonly ExpansionEdge[],
   expansion: ObjectExpansion,
-  baseTargets: Map<string, ObjectRow>,
+  baseTargets: ReadonlyMap<ObjectBatchKey, ObjectRow>,
   options: QueryExecutorOptions
 ): ExpansionEdge[] {
   let ordered = edges
@@ -899,7 +930,7 @@ function compareExpansionEdges(
   left: ExpansionEdge,
   right: ExpansionEdge,
   fields: readonly ObjectQuerySortField[],
-  baseTargets: Map<string, ObjectRow>
+  baseTargets: ReadonlyMap<ObjectBatchKey, ObjectRow>
 ): number {
   const leftRow = baseTargets.get(targetKey(left.neighborTypeId, left.neighborId))
   const rightRow = baseTargets.get(targetKey(right.neighborTypeId, right.neighborId))
@@ -954,8 +985,8 @@ function toLinkValue(
   return rows
 }
 
-function targetKey(objectTypeId: string, id: string): string {
-  return `${objectTypeId}:${id}`
+function targetKey(objectTypeId: string, id: string): ObjectBatchKey {
+  return objectBatchKey(objectTypeId, id)
 }
 
 async function evaluateFallbackStart(
@@ -1300,7 +1331,7 @@ function facetValueSortKey(value: unknown): string {
 }
 
 function rowIdentityKey(row: ObjectRow): string {
-  return `${row.objectTypeId}:${row.primaryId}`
+  return objectBatchKey(row.objectTypeId, row.primaryId)
 }
 
 function encodePageOffset(offset: number): string {