@sixb/core 0.1.3 → 0.1.5

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 {

package/src/objects/query/explain.ts

@@ -18,6 +18,7 @@ export interface ObjectQueryExplainOptions {
   normalize?: boolean
   maxLimit?: number
   maxPageSize?: number
+  maxRefs?: number
 }
 
 export interface ObjectQueryExplanation {
@@ -47,6 +48,7 @@ export function explainObjectQuery(
         ontology: options.ontology,
         maxLimit: options.maxLimit,
         maxPageSize: options.maxPageSize,
+        maxRefs: options.maxRefs,
         normalize: false,
       })
     : []
@@ -57,6 +59,7 @@ export function explainObjectQuery(
           ontology: options.ontology,
           maxLimit: options.maxLimit,
           maxPageSize: options.maxPageSize,
+          maxRefs: options.maxRefs,
           normalize: false,
         }).result
       : undefined
@@ -84,6 +87,14 @@ function buildExplainNode(query: ObjectQuery, path: string): ObjectQueryExplainN
         },
         children: [],
       }
+    case "refs":
+      return {
+        path,
+        kind: query.kind,
+        summary: `refs ${query.refs.length}`,
+        details: { refs: query.refs },
+        children: [],
+      }
     case "filter":
       return {
         path,

package/src/objects/query/index.ts

@@ -44,6 +44,7 @@ export type {
   ObjectQueryPredicateIn,
   ObjectQueryPredicateNot,
   ObjectQueryProject,
+  ObjectQueryRefs,
   ObjectQueryResultShape,
   ObjectQuerySet,
   ObjectQuerySetOperation,
@@ -56,6 +57,11 @@ export type {
   ObjectQueryVector,
   QueryScalarKind,
 } from "./ir"
+export type {
+  ExecuteObjectQueryLinksInput,
+  ExecuteObjectQueryLinksResult,
+} from "./links"
+export { executeObjectQueryLinks } from "./links"
 export { normalizeObjectQuery, normalizeObjectQueryPredicate } from "./normalize"
 export type {
   ObjectQueryPlan,

package/src/objects/query/ir.ts

@@ -5,6 +5,8 @@
  * storage backend. Providers can push down the subset they support, while the
  * core planner decides whether a bounded fallback is acceptable.
  */
+import type { ObjectRef } from "../../ontology/refs"
+
 export type ObjectQueryDirection = "outgoing" | "incoming"
 export type ObjectQuerySetOperation = "union" | "intersect" | "subtract"
 export type ObjectQuerySortDirection = "asc" | "desc"
@@ -21,6 +23,7 @@ export type QueryScalarKind =
 
 export type ObjectQuery =
   | ObjectQueryStart
+  | ObjectQueryRefs
   | ObjectQueryFilter
   | ObjectQueryText
   | ObjectQueryVector
@@ -38,6 +41,19 @@ export interface ObjectQueryStart {
   includeSubtypes?: boolean
 }
 
+/**
+ * Starts a query from an explicit, heterogeneous set of object identities.
+ *
+ * Unlike `start`, this source is intrinsically bounded. Providers can compile
+ * it natively for composition with the rest of the IR; core resolves it through
+ * `getByPrimaryIdBatch` when pushdown is unavailable. Normalization removes
+ * duplicate identities and orders the set canonically by type and primary id.
+ */
+export interface ObjectQueryRefs {
+  kind: "refs"
+  refs: readonly ObjectRef[]
+}
+
 export interface ObjectQueryFilter {
   kind: "filter"
   input: ObjectQuery