@sixb/core 0.1.2 → 0.1.4

package/src/projections/registry.ts

@@ -241,6 +241,13 @@ function cloneObjectProjectionDefinition(
         },
       ])
     ),
+    conflictResolution:
+      projection.conflictResolution?.strategy === "mostRecent"
+        ? {
+            strategy: "mostRecent",
+            sourceTimestamp: projection.conflictResolution.sourceTimestamp,
+          }
+        : { strategy: "editsWin" },
   }
 }
 
@@ -266,12 +273,18 @@ function cloneTelemetryProjectionDefinition(
     _tag: "TelemetryProjectionDefinition",
     id: projection.id,
     objectTypeId: projection.objectTypeId,
-    propertyId: projection.propertyId,
     datasetId: projection.datasetId,
     objectIdField: projection.objectIdField,
     atField: projection.atField,
-    valueField: projection.valueField,
-    ...(projection.unitField !== undefined ? { unitField: projection.unitField } : {}),
+    properties: Object.fromEntries(
+      Object.entries(projection.properties).map(([propertyId, mapping]) => [
+        propertyId,
+        {
+          valueField: mapping.valueField,
+          ...(mapping.unitField !== undefined ? { unitField: mapping.unitField } : {}),
+        },
+      ])
+    ),
   }
 }
 

package/src/projections/revision.ts

@@ -147,6 +147,7 @@ function normalizeProjectionDefinition(projection: ProjectionDefinition): JsonVa
             },
           ])
       ),
+      conflictResolution: projection.conflictResolution ?? { strategy: "editsWin" },
     }
   }
   if (projection._tag === "LinkProjectionDefinition") {
@@ -159,14 +160,38 @@ function normalizeProjectionDefinition(projection: ProjectionDefinition): JsonVa
       targetField: projection.targetField,
     }
   }
+  const properties = Object.entries(projection.properties).sort(([left], [right]) =>
+    compareStrings(left, right)
+  )
+  if (properties.length === 1) {
+    const [propertyId, mapping] = properties[0]
+    // Preserve the pre-grouping semantic hash for one-property projections. The authoring form and
+    // lowered shape changed, but the source semantics did not; keeping the hash stable prevents a
+    // deployment from invalidating queued jobs or replaying completed dataset versions.
+    return {
+      kind: "telemetry",
+      objectTypeId: projection.objectTypeId,
+      propertyId,
+      objectIdField: projection.objectIdField,
+      atField: projection.atField,
+      valueField: mapping.valueField,
+      unitField: mapping.unitField ?? null,
+    }
+  }
   return {
     kind: "telemetry",
     objectTypeId: projection.objectTypeId,
-    propertyId: projection.propertyId,
     objectIdField: projection.objectIdField,
     atField: projection.atField,
-    valueField: projection.valueField,
-    unitField: projection.unitField ?? null,
+    properties: Object.fromEntries(
+      properties.map(([propertyId, mapping]) => [
+        propertyId,
+        {
+          valueField: mapping.valueField,
+          unitField: mapping.unitField ?? null,
+        },
+      ])
+    ),
   }
 }
 
@@ -177,6 +202,9 @@ function projectionColumns(projection: ProjectionDefinition): Set<string> {
       ...Object.values(projection.links).flatMap((link) =>
         link.sourceField === undefined ? [] : [link.sourceField]
       ),
+      ...(projection.conflictResolution?.strategy === "mostRecent"
+        ? [projection.conflictResolution.sourceTimestamp]
+        : []),
     ])
   }
   if (projection._tag === "LinkProjectionDefinition") {
@@ -185,8 +213,10 @@ function projectionColumns(projection: ProjectionDefinition): Set<string> {
   return new Set([
     projection.objectIdField,
     projection.atField,
-    projection.valueField,
-    ...(projection.unitField === undefined ? [] : [projection.unitField]),
+    ...Object.values(projection.properties).flatMap((mapping) => [
+      mapping.valueField,
+      ...(mapping.unitField === undefined ? [] : [mapping.unitField]),
+    ]),
   ])
 }
 

package/src/projections/run-dispatch.ts

@@ -23,6 +23,7 @@ import {
   type ProjectionRunFailureCode,
 } from "./types"
 
+/** Target maximum mapped points per telemetry commit; a single-property projection reads 500 rows. */
 export const PROJECTION_TELEMETRY_BATCH_SIZE = 500
 
 export interface ProjectionRunDispatchInput {
@@ -403,11 +404,19 @@ function queueProjectionRun(
         ...common,
         identity: input.identity,
         target: { objectTypeId: input.projection.objectTypeId },
-        fixedBatchSize: PROJECTION_TELEMETRY_BATCH_SIZE,
+        fixedBatchSize: telemetryProjectionBatchRowCount(input.projection),
       })
   }
 }
 
+function telemetryProjectionBatchRowCount(
+  projection: Extract<ProjectionDefinition, { readonly _tag: "TelemetryProjectionDefinition" }>
+): number {
+  const mappedPropertyCount = Object.keys(projection.properties).length
+  if (mappedPropertyCount === 0) throw invalidProjectionDefinition(projection.id)
+  return Math.max(1, Math.floor(PROJECTION_TELEMETRY_BATCH_SIZE / mappedPropertyCount))
+}
+
 function requeueProjectionRun(
   storage: NonNullable<Storage["projectionRuns"]>,
   run: ProjectionRunRecord,

package/src/projections/timestamp.ts

@@ -0,0 +1,66 @@
+const DATASET_TIMESTAMP =
+  /^(\d{4})-(\d{1,2})-(\d{1,2})(?:[ T](\d{1,2}):(\d{2})(?::(\d{2})(?:\.(\d{1,9}))?)?)?([zZ]|[+-]\d{2}:?\d{2})?$/
+
+interface TimestampComponents {
+  readonly year: number
+  readonly month: number
+  readonly day: number
+  readonly hour: number
+  readonly minute: number
+  readonly second: number
+  readonly milliseconds: number
+}
+
+/** Parses a projection dataset timestamp, interpreting zone-less values as UTC. */
+export function parseDatasetTimestamp(value: unknown): Date | null {
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value
+  if (typeof value !== "string") return null
+
+  const match = DATASET_TIMESTAMP.exec(value.trim())
+  if (!match) return null
+  const [, year, month, day, hour, minute, second, fraction, zone] = match
+  const offsetMinutes = parseZoneOffsetMinutes(zone)
+  if (offsetMinutes === null) return null
+
+  const components: TimestampComponents = {
+    year: Number(year),
+    month: Number(month),
+    day: Number(day),
+    hour: hour === undefined ? 0 : Number(hour),
+    minute: minute === undefined ? 0 : Number(minute),
+    second: second === undefined ? 0 : Number(second),
+    milliseconds: fraction === undefined ? 0 : Math.trunc(Number(`0.${fraction}`) * 1000),
+  }
+  const wallClock = Date.UTC(
+    components.year,
+    components.month - 1,
+    components.day,
+    components.hour,
+    components.minute,
+    components.second,
+    components.milliseconds
+  )
+  if (!wallClockMatchesComponents(wallClock, components)) return null
+  return new Date(wallClock - offsetMinutes * 60_000)
+}
+
+function parseZoneOffsetMinutes(zone: string | undefined): number | null {
+  if (zone === undefined || zone === "Z" || zone === "z") return 0
+  const digits = zone.slice(1).replace(":", "")
+  const hours = Number(digits.slice(0, 2))
+  const minutes = Number(digits.slice(2, 4))
+  if (hours > 23 || minutes > 59) return null
+  return (zone[0] === "-" ? -1 : 1) * (hours * 60 + minutes)
+}
+
+function wallClockMatchesComponents(wallClock: number, components: TimestampComponents): boolean {
+  const date = new Date(wallClock)
+  return (
+    date.getUTCFullYear() === components.year &&
+    date.getUTCMonth() === components.month - 1 &&
+    date.getUTCDate() === components.day &&
+    date.getUTCHours() === components.hour &&
+    date.getUTCMinutes() === components.minute &&
+    date.getUTCSeconds() === components.second
+  )
+}

package/src/projections/types.ts

@@ -39,6 +39,11 @@ export interface ForeignKeyDescriptor {
   readonly targetObjectTypeId: string
 }
 
+/** Resolves competing source-projection and managed-edit values for projected properties. */
+export type SourceEditConflictResolution =
+  | { readonly strategy: "editsWin" }
+  | { readonly strategy: "mostRecent"; readonly sourceTimestamp: string }
+
 /**
  * Lowered, serializable definition for projecting a dataset into object instances.
  *
@@ -56,6 +61,8 @@ export interface ObjectProjectionDefinition {
   readonly properties: Readonly<Record<string, string>>
   /** Maps link id -> FK descriptor. Empty `{}` when no FK links are projected. */
   readonly links: Readonly<Record<string, ForeignKeyDescriptor>>
+  /** Defaults to `editsWin` when omitted by a legacy lowered definition. */
+  readonly conflictResolution?: SourceEditConflictResolution
 }
 
 /**
@@ -77,28 +84,32 @@ export interface LinkProjectionDefinition {
   readonly targetField: string
 }
 
+/** Dataset columns that produce one telemetry property value. */
+export interface TelemetryProjectionPropertyMapping {
+  /** Dataset column holding the telemetry value. */
+  readonly valueField: string
+  /** Dataset column holding the telemetry unit, when the property requires one. */
+  readonly unitField?: string
+}
+
 /**
  * Lowered, serializable definition for projecting dataset rows into telemetry history.
  *
- * Each row in the dataset becomes one telemetry point for a single object type property.
- * The target object type and property are fixed by the telemetry property token used by
- * the builder; the point mapping selects the dataset columns for object id, timestamp,
- * value, and optional unit.
+ * Each row shares one target object id and observation timestamp, then contributes up to one
+ * telemetry point for every mapped property. A property-token projection is lowered to the same
+ * shape with one entry, so execution and ownership have one canonical contract.
  */
 export interface TelemetryProjectionDefinition {
   readonly _tag: "TelemetryProjectionDefinition"
   readonly id: string
   readonly objectTypeId: string
-  readonly propertyId: string
   readonly datasetId: string
   /** Dataset column holding the target object's primary id. */
   readonly objectIdField: string
   /** Dataset column holding the telemetry observation timestamp. */
   readonly atField: string
-  /** Dataset column holding the telemetry value. */
-  readonly valueField: string
-  /** Dataset column holding the telemetry unit, when the property requires one. */
-  readonly unitField?: string
+  /** Maps telemetry property id -> value and optional unit dataset columns. */
+  readonly properties: Readonly<Record<string, TelemetryProjectionPropertyMapping>>
 }
 
 /** Union of all projection definition types. */

package/src/projections/validation.ts

@@ -7,7 +7,8 @@
 
 import type { DatasetDefinition } from "../datasets"
 import type { OntologyDefinitionCatalog } from "../ontology"
-import type { ObjectType, Property } from "../ontology/types"
+import type { ObjectType, Property, ValueType } from "../ontology/types"
+import { resolveSemanticType } from "../ontology/validation"
 import { ProjectionValidationError } from "./errors"
 import {
   computeProjectionOwnership,
@@ -196,37 +197,29 @@ export function validateLinkProjectionTarget(linkToken: {
 
 /**
  * Validates a telemetry projection's field mapping against its dataset columns
- * and object type: the telemetry property exists and is telemetry-enabled, and
+ * and object type: every mapped property exists and is telemetry-enabled, and
  * every mapped field (objectId/at/value/unit) resolves to a real dataset column.
  *
  * Owned here so startup validation and the projection worker's pre-execution
  * check share one implementation and cannot drift; the worker layers
  * dataset-version column type compatibility on top of these rules. Returns the
- * resolved telemetry property for callers that need its schema.
+ * resolved telemetry properties for callers that need their schemas.
  */
 export function validateTelemetryProjectionFieldMapping(
   projection: TelemetryProjectionDefinition,
   objectType: { readonly id: string; readonly properties: readonly Property[] },
   datasetColumnNames: ReadonlySet<string>,
+  valueTypesById: ReadonlyMap<string, ValueType>,
   prefix: string
-): Property {
-  const property = objectType.properties.find((candidate) => candidate.id === projection.propertyId)
-  if (!property) {
-    throw new ProjectionValidationError(
-      `${prefix}: unknown property "${projection.propertyId}" on type "${projection.objectTypeId}"`
-    )
-  }
-  if (property.mode !== "telemetry") {
-    throw new ProjectionValidationError(
-      `${prefix}: property "${projection.propertyId}" on type "${projection.objectTypeId}" must be telemetry-enabled`
-    )
+): ReadonlyMap<string, Property> {
+  const mappedProperties = Object.entries(projection.properties)
+  if (mappedProperties.length === 0) {
+    throw new ProjectionValidationError(`${prefix}: must map at least one telemetry property`)
   }
 
   const mappedFields = [
     ["objectId", projection.objectIdField],
     ["at", projection.atField],
-    ["value", projection.valueField],
-    ...(projection.unitField !== undefined ? ([["unit", projection.unitField]] as const) : []),
   ] as const
   for (const [fieldRole, columnName] of mappedFields) {
     if (!datasetColumnNames.has(columnName)) {
@@ -237,7 +230,49 @@ export function validateTelemetryProjectionFieldMapping(
     }
   }
 
-  return property
+  const propertiesById = new Map(objectType.properties.map((property) => [property.id, property]))
+  const resolvedProperties = new Map<string, Property>()
+  for (const [propertyId, mapping] of mappedProperties) {
+    const property = propertiesById.get(propertyId)
+    if (!property) {
+      throw new ProjectionValidationError(
+        `${prefix}: unknown property "${propertyId}" on type "${projection.objectTypeId}"`
+      )
+    }
+    if (property.mode !== "telemetry") {
+      throw new ProjectionValidationError(
+        `${prefix}: property "${propertyId}" on type "${projection.objectTypeId}" must be telemetry-enabled`
+      )
+    }
+
+    for (const [fieldRole, columnName] of [
+      ["value", mapping.valueField],
+      ...(mapping.unitField !== undefined ? ([["unit", mapping.unitField]] as const) : []),
+    ] as const) {
+      if (!datasetColumnNames.has(columnName)) {
+        throw new ProjectionValidationError(
+          `${prefix}: property "${propertyId}" ${fieldRole} field "${columnName}" references ` +
+            `unknown dataset column on dataset "${projection.datasetId}"`
+        )
+      }
+    }
+
+    const semanticType = resolveSemanticType(property, valueTypesById)
+    if (semanticType !== undefined && mapping.unitField === undefined) {
+      throw new ProjectionValidationError(
+        `${prefix}: property "${propertyId}" requires a unit field because it uses semantic type "${semanticType}"`
+      )
+    }
+    if (semanticType === undefined && mapping.unitField !== undefined) {
+      throw new ProjectionValidationError(
+        `${prefix}: property "${propertyId}" cannot map a unit field because it has no semantic type`
+      )
+    }
+
+    resolvedProperties.set(propertyId, property)
+  }
+
+  return resolvedProperties
 }
 
 /**
@@ -262,8 +297,9 @@ export function validateTelemetryProjectionFieldMapping(
  * For telemetry projections:
  * 1. `datasetId` exists in the dataset registry.
  * 2. `objectTypeId` exists in the type registry.
- * 3. `propertyId` exists on the object type and is telemetry-enabled.
+ * 3. Every mapped property exists on the object type and is telemetry-enabled.
  * 4. Point mapping fields exist in the referenced dataset.
+ * 5. Unit mappings match each property's semantic type requirements.
  */
 export interface ValidatedProjectionRecord<TDefinition extends ProjectionDefinition>
   extends ProjectionOwnershipRecord<TDefinition> {
@@ -315,6 +351,30 @@ export function validateProjectionsAtStartup(
     }
 
     const datasetColumnNames = new Set(dataset.schema.columns.map((column) => column.name))
+    const conflictResolution = projection.conflictResolution ?? { strategy: "editsWin" }
+    if (conflictResolution.strategy === "mostRecent") {
+      const sourceTimestamp = dataset.schema.columns.find(
+        (column) => column.name === conflictResolution.sourceTimestamp
+      )
+      if (!sourceTimestamp) {
+        throw new ProjectionValidationError(
+          `${prefix}: source timestamp "${conflictResolution.sourceTimestamp}" references unknown ` +
+            `dataset column on dataset "${projection.datasetId}"`
+        )
+      }
+      if (sourceTimestamp.type !== "timestamp") {
+        throw new ProjectionValidationError(
+          `${prefix}: source timestamp "${conflictResolution.sourceTimestamp}" must reference a ` +
+            `timestamp dataset column`
+        )
+      }
+      if (sourceTimestamp.nullable === true) {
+        throw new ProjectionValidationError(
+          `${prefix}: source timestamp "${conflictResolution.sourceTimestamp}" must reference a ` +
+            `non-null timestamp dataset column`
+        )
+      }
+    }
     const propertyIds = new Set(objectType.properties.map((p) => p.id))
     for (const [propId, columnName] of Object.entries(projection.properties)) {
       if (!propertyIds.has(propId)) {
@@ -488,7 +548,13 @@ export function validateProjectionsAtStartup(
     }
 
     const datasetColumnNames = new Set(dataset.schema.columns.map((column) => column.name))
-    validateTelemetryProjectionFieldMapping(projection, objectType, datasetColumnNames, prefix)
+    validateTelemetryProjectionFieldMapping(
+      projection,
+      objectType,
+      datasetColumnNames,
+      ontology.getValueTypesById(),
+      prefix
+    )
     validatedTelemetryProjections.push({
       definition: projection,
       dataset,

package/src/query.ts

@@ -28,6 +28,7 @@ export type {
   ObjectQueryPredicateIn,
   ObjectQueryPredicateNot,
   ObjectQueryProject,
+  ObjectQueryRefs,
   ObjectQueryResultShape,
   ObjectQuerySet,
   ObjectQuerySetOperation,
@@ -50,6 +51,7 @@ export type {
   ObjectQueryExecutorListResult,
   ObjectQueryExecutorRow,
 } from "./objects/sdk/query-executor"
+export type { ObjectRef } from "./ontology/refs"
 export type {
   LinkToken,
   ObjectTypeWithPropertyTokens,

package/src/queues/index.ts

@@ -4,6 +4,7 @@ export { InMemoryQueues } from "./in-memory"
 export type {
   ActionQueueJobFailureCode,
   ActionRunRequestedQueueJob,
+  AgentAiUsageAccountingPayload,
   AgentAiUsageRecordPayload,
   AgentAiUsageRecordRequestedQueueJob,
   AgentQueueJob,

package/src/queues/types.ts

@@ -4,6 +4,7 @@ import type { ProjectionRunFailureCode } from "../projections/types"
 import type { ProviderScope } from "../provider-scope"
 import type { ActionRunFailureCode } from "../storage/action-runs/types"
 import type { AgentRunFailureCode } from "../storage/agents/types"
+import type { AiPricingContext } from "../storage/ai-cost/types"
 import type { RecordAiModelCallInput } from "../storage/ai-usage"
 import type { PipelineRunFailureCode } from "../storage/pipeline-runs/types"
 import type { SyncRunFailureCode } from "../storage/sync-runs/types"
@@ -209,11 +210,18 @@ export type AgentAiUsageRecordPayload = Omit<
   readonly occurredAt: string
 }
 
+export interface AgentAiUsageAccountingPayload {
+  readonly pricingContext: AiPricingContext
+  readonly ratedAt: string
+}
+
 export interface AgentAiUsageRecordRequestedQueueJob
   extends QueueJob<
     "agent.ai-usage.record.requested",
     {
       readonly record: AgentAiUsageRecordPayload
+      /** Absent on Phase 1 jobs; recovery then uses an empty pricing context. */
+      readonly accounting?: AgentAiUsageAccountingPayload
     }
   > {}
 

package/src/runtime/ai-cost.ts

@@ -0,0 +1,15 @@
+import type { AiCostStorage, AiCostSummary } from "../storage/ai-cost"
+
+/** Resolve preferred cost summaries in input order without inventing unavailable accounting. */
+export async function resolveExecutionCosts(input: {
+  readonly storage: AiCostStorage | undefined
+  readonly projectId: string
+  readonly executionIds: readonly string[]
+}): Promise<readonly (AiCostSummary | undefined)[]> {
+  if (input.executionIds.length === 0) return []
+  if (!input.storage) return input.executionIds.map(() => undefined)
+  return input.storage.summarizeExecutions({
+    projectId: input.projectId,
+    executionIds: input.executionIds,
+  })
+}

package/src/runtime/create.ts

@@ -11,6 +11,7 @@ import type { SixbErrorHandler } from "../error-reporting/types"
 import type { LakeStorage } from "../lake-storage"
 import type { LoggerProvider, ObservabilityOptions } from "../logging"
 import type { OntologyMaintenanceOptions } from "../maintenance"
+import type { ModelCatalogInput } from "../models"
 import type { PipelineDefinition } from "../pipelines/types"
 import type { ProjectionDefinition } from "../projections/types"
 import type { Queues } from "../queues"
@@ -45,6 +46,8 @@ export interface CreateSixbOptions {
   actions?: readonly ActionDefinition[]
   /** Agent definitions to register in addition to auto-discovered `agents/` exports. */
   agents?: readonly AgentDefinition[]
+  /** Models this project allows Sixb to use. The first of each kind is the default. */
+  models?: ModelCatalogInput
   datasets?: readonly DatasetDefinition[]
   /** Connector definitions to register in addition to auto-discovered `connectors/` exports. */
   connectors?: readonly ConnectorDefinition[]
@@ -118,6 +121,7 @@ export async function createSixb(
     roles: [...(options.roles ?? []), ...definitions.roles],
     membershipPolicies: [...(options.membershipPolicies ?? []), ...definitions.membershipPolicies],
     agents: [...(options.agents ?? []), ...definitions.agents],
+    models: options.models,
     auth: options.auth,
   })
 }

package/src/runtime/definitions.ts

@@ -2,6 +2,7 @@ import type { ActionDefinitionCatalog } from "../actions"
 import type { AgentDefinition } from "../agents"
 import type { ConnectorDefinition } from "../connectors"
 import type { DatasetDefinition } from "../datasets"
+import type { ModelCatalog } from "../models"
 import type { OntologyDefinitionCatalog } from "../ontology"
 import type { PipelineDefinition } from "../pipelines"
 import type { ProjectionDefinitionCatalog } from "../projections"
@@ -24,6 +25,8 @@ export interface SixbDefinitions {
   readonly agents: DefinitionCatalog<AgentDefinition>
   readonly connectors: DefinitionCatalog<ConnectorDefinition>
   readonly datasets: DefinitionCatalog<DatasetDefinition>
+  /** Absent until a project configures `models` in createSixb(). */
+  readonly models?: ModelCatalog
   readonly pipelines: DefinitionCatalog<PipelineDefinition>
   readonly projections: ProjectionDefinitionCatalog
   readonly rules: DefinitionCatalog<RuleDefinition>

package/src/runtime/host.ts

@@ -48,6 +48,7 @@ import {
   type SixbReadiness,
 } from "../maintenance"
 import { createOntologyMaterializer, type OntologyMaterializerContract } from "../materializer"
+import type { ModelCatalogInput } from "../models"
 import type { PipelineDefinition } from "../pipelines/types"
 import { registerProjectionRegistry } from "../projections/internal"
 import type { ProjectionDefinition } from "../projections/types"
@@ -108,6 +109,7 @@ export interface SixbHostOptions<TOntologySources extends readonly OntologySourc
   rules?: readonly RuleDefinition[]
   workflows?: readonly WorkflowDefinition[]
   agents?: readonly AgentDefinition[]
+  models?: ModelCatalogInput
   groups?: readonly GroupDefinition[]
   roles?: readonly RoleDefinition[]
   membershipPolicies?: readonly MembershipPolicyDefinition[]

package/src/runtime/resolve-definitions.ts

@@ -5,6 +5,7 @@ import { validateAgentGroupReferences, validateAgentToolsAtStartup } from "../ag
 import type { ConnectorDefinition } from "../connectors"
 import type { DatasetDefinition } from "../datasets/types"
 import { assertDatasetDefinition } from "../datasets/validation"
+import { createModelCatalog, type ModelCatalog, type ModelCatalogInput, modelRef } from "../models"
 import { OntologyRegistry } from "../ontology"
 import type { PipelineDefinition } from "../pipelines/types"
 import { ProjectionRegistry } from "../projections"
@@ -40,6 +41,7 @@ interface DefinitionOptions {
   readonly rules?: readonly RuleDefinition[]
   readonly workflows?: readonly WorkflowDefinition[]
   readonly agents?: readonly AgentDefinition[]
+  readonly models?: ModelCatalogInput
   readonly groups?: readonly GroupDefinition[]
   readonly roles?: readonly RoleDefinition[]
   readonly membershipPolicies?: readonly MembershipPolicyDefinition[]
@@ -60,6 +62,8 @@ export function resolveDefinitions(options: DefinitionOptions): ResolvedDefiniti
 
   const agents = options.agents ?? []
   validateAgentToolsAtStartup(agents)
+  const models = options.models === undefined ? undefined : createModelCatalog(options.models)
+  validateAgentModelReferences(agents, models)
   const agentsById = indexUniqueDefinitions("agent", agents)
   const connectorsById = indexUniqueDefinitions("connector", options.connectors ?? [])
 
@@ -158,6 +162,7 @@ export function resolveDefinitions(options: DefinitionOptions): ResolvedDefiniti
     agents: createDefinitionCatalog(agentsById),
     connectors: createDefinitionCatalog(connectorsById),
     datasets: createDefinitionCatalog(datasetsById),
+    ...(models === undefined ? {} : { models }),
     pipelines: createDefinitionCatalog(pipelinesById),
     projections: projectionRegistry,
     rules: createDefinitionCatalog(rulesById),
@@ -236,3 +241,26 @@ function validateScheduleReferences(
     }
   }
 }
+
+/**
+ * Keep every agent on a model the project actually allows.
+ *
+ * Only enforced once a project configures `models`; without a catalog an agent's model is its own
+ * declaration, which is the pre-catalog behavior.
+ */
+function validateAgentModelReferences(
+  agents: readonly AgentDefinition[],
+  models: ModelCatalog | undefined
+): void {
+  if (models === undefined) {
+    return
+  }
+  for (const agent of agents) {
+    const ref = modelRef(agent.model)
+    if (models.language.getById(ref) === null) {
+      throw new RuntimeError(
+        `[Sixb] Agent '${agent.id}' uses unknown language model '${ref}'. Add it to 'models.language' in createSixb().`
+      )
+    }
+  }
+}