@sixb/core 0.1.12 → 0.1.13

package/src/ontology/index.ts

@@ -30,6 +30,7 @@ export { isObjectRefSchema, objectRef, ref } from "./refs"
 export type {
   LinkToken,
   LinkTokenMap,
+  ObjectPropertiesMetadata,
   ObjectTypeWithPropertyTokens,
   ObjectTypeWithTokens,
   PropertyToken,
@@ -57,9 +58,12 @@ export type {
   PropertyQueryMetadata,
   Schema,
   SixbObjectTypeMap,
+  SixbValueTypeMap,
   ValueType,
   ValueTypeRefSchema,
 } from "./types"
+export type { UserRef } from "./user-ref"
+export { userRef } from "./user-ref"
 
 // ── Registry ──────────────────────────────────────────────
 

package/src/ontology/inference/index.ts

@@ -13,13 +13,16 @@ import type {
   ValueTypeRefSchema,
 } from ".."
 import type { DecimalValue } from "../decimal"
+import type { RegisteredValueTypes } from "../registered"
 import type { QuantitativeTypeId, UnitsOf } from "../units"
+import type { UserRef } from "../user-ref"
 
 type Simplify<T> = { [K in keyof T]: T[K] } & {}
 
 /**
  * Look up a referenced value type by `id` from the value-type tuple passed
- * into the inference utilities.
+ * into the inference utilities — the generated registry unless a caller passes
+ * its own tuple.
  */
 type ResolveValueType<
   TValueTypes extends readonly ValueType[],
@@ -30,13 +33,17 @@ type ResolveValueType<
  * Resolve `{ type: "valueTypeRef" }` recursively.
  *
  * Unknown references intentionally degrade to `unknown` so type-level callsites
- * can decide how strict they want to be.
+ * can decide how strict they want to be. The `[never]` guard is what keeps that
+ * promise: an unresolved lookup is `never`, and a distributive check over `never`
+ * would yield `never` — a value assignable to everything.
  */
 type InferValueTypeRef<TValueTypeId extends string, TValueTypes extends readonly ValueType[]> =
   ResolveValueType<TValueTypes, TValueTypeId> extends infer TValueType
-    ? TValueType extends ValueType
-      ? InferSchema<TValueType["schema"], TValueTypes>
-      : unknown
+    ? [TValueType] extends [never]
+      ? unknown
+      : TValueType extends ValueType
+        ? InferSchema<TValueType["schema"], TValueTypes>
+        : unknown
     : unknown
 
 type RequiredFieldIds<TFields extends Record<string, ObjectFieldSchema>> = {
@@ -68,6 +75,7 @@ type InferObjectFields<
 
 interface PrimitiveSchemaValueMap {
   fileRef: FileRef
+  userRef: UserRef
   string: string
   uuid: string
   boolean: boolean
@@ -102,26 +110,37 @@ type InferValueTypeRefSchema<
  * Convert ontology schema definitions into runtime value types.
  *
  * This is the core typing bridge used by the future object SDK APIs.
+ *
+ * A schema typed as the whole `Schema` union (a helper returning `Schema`, say) infers `unknown`:
+ * its array, map and object children are `Schema` again, so inferring it never terminates.
  */
 export type InferSchema<
   TSchema extends Schema,
-  TValueTypes extends readonly ValueType[] = [],
-> = TSchema extends PrimitiveSchema
-  ? PrimitiveSchemaValueMap[TSchema]
-  : TSchema extends ComplexSchema
-    ? InferComplexSchema<TSchema, TValueTypes>
-    : TSchema extends ValueTypeRefSchema
-      ? InferValueTypeRefSchema<TSchema, TValueTypes>
-      : never
+  TValueTypes extends readonly ValueType[] = RegisteredValueTypes,
+> = Schema extends TSchema
+  ? unknown
+  : TSchema extends PrimitiveSchema
+    ? PrimitiveSchemaValueMap[TSchema]
+    : TSchema extends ComplexSchema
+      ? InferComplexSchema<TSchema, TValueTypes>
+      : TSchema extends ValueTypeRefSchema
+        ? InferValueTypeRefSchema<TSchema, TValueTypes>
+        : never
 
 /** Property-level value inference with nullable support. */
 export type InferPropertyValue<
   TProperty extends Pick<Property, "schema" | "nullable">,
-  TValueTypes extends readonly ValueType[] = [],
+  TValueTypes extends readonly ValueType[] = RegisteredValueTypes,
 > = TProperty["nullable"] extends true
   ? InferSchema<TProperty["schema"], TValueTypes> | null
   : InferSchema<TProperty["schema"], TValueTypes>
 
+/**
+ * A registered value type wins over the semantic type carried on the ref, as it does at runtime:
+ * the registry keeps an explicit value type and only auto-registers the ref's copy when none
+ * exists. `valueTypeRef(VT)` carries `_semanticType` so a value type that is not registered
+ * (defined outside `ontology/`) still constrains units.
+ */
 type InferPropertySemanticTypeFromValueTypeRef<
   TProperty extends Pick<Property, "schema">,
   TValueTypes extends readonly ValueType[],
@@ -129,16 +148,20 @@ type InferPropertySemanticTypeFromValueTypeRef<
   type: "valueTypeRef"
   valueTypeId: infer TValueTypeId extends string
 }
-  ? ResolveValueType<TValueTypes, TValueTypeId> extends {
-      semanticType: infer TSemanticType extends QuantitativeTypeId
-    }
-    ? TSemanticType
-    : never
+  ? [ResolveValueType<TValueTypes, TValueTypeId>] extends [never]
+    ? TProperty["schema"] extends { _semanticType: infer TSemanticType extends QuantitativeTypeId }
+      ? TSemanticType
+      : never
+    : ResolveValueType<TValueTypes, TValueTypeId> extends {
+          semanticType: infer TSemanticType extends QuantitativeTypeId
+        }
+      ? TSemanticType
+      : never
   : never
 
 export type InferPropertySemanticType<
   TProperty extends Pick<Property, "schema" | "semanticType">,
-  TValueTypes extends readonly ValueType[] = [],
+  TValueTypes extends readonly ValueType[] = RegisteredValueTypes,
 > = TProperty["semanticType"] extends QuantitativeTypeId
   ? TProperty["semanticType"]
   : InferPropertySemanticTypeFromValueTypeRef<TProperty, TValueTypes>
@@ -152,7 +175,7 @@ export type InferPropertySemanticType<
  */
 export type InferPropertyUnit<
   TProperty extends Pick<Property, "schema" | "semanticType">,
-  TValueTypes extends readonly ValueType[] = [],
+  TValueTypes extends readonly ValueType[] = RegisteredValueTypes,
 > =
   InferPropertySemanticType<TProperty, TValueTypes> extends infer TSemanticType extends
     QuantitativeTypeId
@@ -163,7 +186,7 @@ export type InferPropertyUnit<
 
 export type InferObjectProperties<
   TObjectType extends { properties: readonly Property[] },
-  TValueTypes extends readonly ValueType[] = [],
+  TValueTypes extends readonly ValueType[] = RegisteredValueTypes,
 > =
   // Object types whose property ids are not statically known (the broad
   // `ObjectTypeWithPropertyTokens` base, e.g. as a generic constraint or
@@ -197,22 +220,19 @@ export type InferTelemetryPropertyIds<TObjectType extends { properties: readonly
  *
  * Iterates over the extracted telemetry property union directly (via `as P["id"]` remapping)
  * so that `P` is already resolved — avoids repeated indexed access through the token map
- * which would cause TS2589 on object types with many telemetry properties.
+ * which would cause TS2589 on object types with many telemetry properties. The semantic type is
+ * resolved as for a single append, so a batch requires exactly the units `telemetry()` does.
  */
 export type InferTelemetryBatchProperties<
   TObjectType extends { properties: readonly Property[] },
-  TValueTypes extends readonly ValueType[] = [],
+  TValueTypes extends readonly ValueType[] = RegisteredValueTypes,
 > = {
-  [P in Extract<
-    TObjectType["properties"][number],
-    { mode: "telemetry" }
-  > as P["id"]]?: P["semanticType"] extends QuantitativeTypeId
-    ? { value: InferPropertyValue<P, TValueTypes>; unit: UnitsOf<P["semanticType"]> }
-    : P["schema"] extends { type: "valueTypeRef"; valueTypeId: infer TVtId extends string }
-      ? ResolveValueType<TValueTypes, TVtId> extends {
-          semanticType: infer TSem extends QuantitativeTypeId
-        }
-        ? { value: InferPropertyValue<P, TValueTypes>; unit: UnitsOf<TSem> }
-        : InferPropertyValue<P, TValueTypes>
-      : InferPropertyValue<P, TValueTypes>
+  [P in Extract<TObjectType["properties"][number], { mode: "telemetry" }> as P["id"]]?: [
+    InferPropertySemanticType<P, TValueTypes>,
+  ] extends [never]
+    ? InferPropertyValue<P, TValueTypes>
+    : {
+        value: InferPropertyValue<P, TValueTypes>
+        unit: UnitsOf<InferPropertySemanticType<P, TValueTypes>>
+      }
 }

package/src/ontology/internal.ts

@@ -1,4 +1,5 @@
 export { schemaFieldsToJsonSchema, schemaRecordToJsonSchema } from "./json-schema"
+export { resolvePropertyQueryCapabilities } from "./query-capabilities"
 export { validateSchemaOrRefValue } from "./refs"
 export { createLinkTokenMap, createPropertyTokenMap } from "./tokens"
 export {

package/src/ontology/json-schema.ts

@@ -101,6 +101,18 @@ function schemaJsonSchema(
           required: ["blobId", "digest", "sizeBytes"],
           additionalProperties: false,
         }
+      case "userRef":
+        return {
+          type: "object",
+          properties: {
+            type: { type: "string", enum: ["user"] },
+            id: { type: "string", minLength: 1 },
+          },
+          required: ["type", "id"],
+          additionalProperties: false,
+        }
+      default:
+        schema satisfies never
     }
   }
 

package/src/ontology/primitives.ts

@@ -0,0 +1,91 @@
+import type { QueryScalarKind } from "../objects/query/ir"
+import type { PrimitiveSchema } from "./types"
+
+/**
+ * Yes/no decisions a primitive schema makes for rules that several modules share.
+ *
+ * Every primitive states every decision: adding one to `PrimitiveSchema` fails to compile until it
+ * has a row here, instead of inheriting string-like behavior from a denylist. Per-type behavior
+ * (value validation, normalization, JSON Schema, inference) stays in exhaustive switches next to
+ * the code that performs it.
+ */
+export interface PrimitiveTraits {
+  /** Scalar kind object queries compare values with; `undefined` when values are not comparable. */
+  readonly queryScalarKind: QueryScalarKind | undefined
+  /** Exact matching: `eq`/`neq`/`in`/`exists` predicates and `query.filterable`. */
+  readonly exact: boolean
+  /** Exact-match search profile: `query.exact` and `search.exact`, matched against search input. */
+  readonly exactSearch: boolean
+  /** Ordering: range predicates and `query.sortable`. */
+  readonly sortable: boolean
+  /** Keyword search: `query.text`, search titles, and vector sources. */
+  readonly text: boolean
+  /** Substring `contains` predicates. */
+  readonly contains: boolean
+  /** Facet buckets: `query.facet`. */
+  readonly facet: boolean
+  /** Allowed anywhere inside a telemetry property's schema. */
+  readonly telemetry: boolean
+  /** Allowed anywhere inside a shared Action parameter's schema. */
+  readonly shareableParam: boolean
+}
+
+const comparable = {
+  exact: true,
+  exactSearch: true,
+  sortable: true,
+  text: false,
+  contains: false,
+  facet: true,
+  telemetry: true,
+  shareableParam: true,
+} as const
+
+const PRIMITIVE_TRAITS = {
+  string: { ...comparable, queryScalarKind: "string", text: true, contains: true },
+  uuid: { ...comparable, queryScalarKind: "uuid", contains: true },
+  integer: { ...comparable, queryScalarKind: "integer" },
+  double: { ...comparable, queryScalarKind: "double" },
+  decimal: { ...comparable, queryScalarKind: "decimal" },
+  date: { ...comparable, queryScalarKind: "date" },
+  timestamp: { ...comparable, queryScalarKind: "timestamp" },
+  boolean: { ...comparable, queryScalarKind: "boolean", sortable: false },
+  // Blob references are resolved through the object that holds them, never compared.
+  fileRef: {
+    queryScalarKind: undefined,
+    exact: false,
+    exactSearch: false,
+    sortable: false,
+    text: false,
+    contains: false,
+    facet: false,
+    telemetry: false,
+    shareableParam: false,
+  },
+  // User references match by identity, never against typed search input. They are not text, carry
+  // no order, and stay out of telemetry and shared sessions, which cannot disclose who they point to.
+  userRef: {
+    queryScalarKind: "userRef",
+    exact: true,
+    exactSearch: false,
+    sortable: false,
+    text: false,
+    contains: false,
+    facet: true,
+    telemetry: false,
+    shareableParam: false,
+  },
+} as const satisfies Record<PrimitiveSchema, PrimitiveTraits>
+
+export function isPrimitiveSchema(schema: unknown): schema is PrimitiveSchema {
+  return typeof schema === "string" && Object.hasOwn(PRIMITIVE_TRAITS, schema)
+}
+
+/**
+ * Traits for a primitive schema. Property schemas are not shape-validated at registration, so an
+ * untyped definition can still carry a string outside `PrimitiveSchema`: it gets `undefined`, and
+ * callers treat it as supporting no query feature.
+ */
+export function primitiveTraits(schema: PrimitiveSchema): PrimitiveTraits | undefined {
+  return isPrimitiveSchema(schema) ? PRIMITIVE_TRAITS[schema] : undefined
+}

package/src/ontology/query-capabilities.ts

@@ -0,0 +1,136 @@
+/**
+ * Query rules for a schema whose `valueTypeRef`s are already resolved. Registration uses them to
+ * accept declared `query` flags, query validation to accept operators, and the ontology API to
+ * report both, so the three cannot drift.
+ */
+import type { QueryScalarKind } from "../objects/query/ir"
+import { primitiveTraits } from "./primitives"
+import type { Property, Schema, ValueType } from "./types"
+
+/** `eq`/`neq`/`in`/`exists` predicates. */
+export function isExactSchema(schema: Schema): boolean {
+  if (typeof schema === "string") return primitiveTraits(schema)?.exact === true
+  return schema.type === "enum"
+}
+
+/** `query.exact`, and through it `search.exact`: matched against search input. */
+export function isExactSearchSchema(schema: Schema): boolean {
+  if (typeof schema === "string") return primitiveTraits(schema)?.exactSearch === true
+  return schema.type === "enum"
+}
+
+/** `query.filterable`: exact matching, or `contains` over a collection. */
+export function isFilterableSchema(schema: Schema): boolean {
+  return (
+    isExactSchema(schema) ||
+    (typeof schema !== "string" && (schema.type === "array" || schema.type === "map"))
+  )
+}
+
+/** Range predicates and `query.sortable`. */
+export function isSortableSchema(schema: Schema): boolean {
+  if (typeof schema === "string") return primitiveTraits(schema)?.sortable === true
+  return schema.type === "enum"
+}
+
+/** Keyword search. */
+export function isTextSchema(schema: Schema): boolean {
+  if (typeof schema === "string") return primitiveTraits(schema)?.text === true
+  return schema.type === "enum" && schema.valueType === "string"
+}
+
+/** `contains`: substring for scalars, item for arrays, key for maps. */
+export function isContainsSchema(schema: Schema): boolean {
+  if (typeof schema === "string") return primitiveTraits(schema)?.contains === true
+  return schema.type === "array" || schema.type === "map"
+}
+
+/** `query.facet`. */
+export function isFacetSchema(schema: Schema): boolean {
+  if (typeof schema === "string") return primitiveTraits(schema)?.facet === true
+  return schema.type === "enum"
+}
+
+export function queryScalarKindForSchema(schema: Schema): QueryScalarKind | undefined {
+  if (typeof schema === "string") return primitiveTraits(schema)?.queryScalarKind
+  if (schema.type === "enum") return schema.valueType === "integer" ? "integer" : "string"
+  return undefined
+}
+
+/** Predicate operators a property may use in an object query. */
+export type PropertyQueryOperator =
+  | "eq"
+  | "neq"
+  | "lt"
+  | "lte"
+  | "gt"
+  | "gte"
+  | "in"
+  | "exists"
+  | "contains"
+
+/** What an object query can do with one property, resolved from its schema and `query` flags. */
+export interface PropertyQueryCapabilities {
+  readonly operators: readonly PropertyQueryOperator[]
+  readonly sortable: boolean
+  readonly facet: boolean
+  readonly text: boolean
+}
+
+const PRIMARY_OPERATORS: readonly PropertyQueryOperator[] = ["eq", "in"]
+const EXACT_OPERATORS: readonly PropertyQueryOperator[] = ["eq", "neq", "in", "exists"]
+const RANGE_OPERATORS: readonly PropertyQueryOperator[] = ["lt", "lte", "gt", "gte"]
+const OPERATOR_ORDER: readonly PropertyQueryOperator[] = [
+  "eq",
+  "neq",
+  "lt",
+  "lte",
+  "gt",
+  "gte",
+  "in",
+  "contains",
+  "exists",
+]
+
+/**
+ * Resolve what object queries accept for a property, applying the same rules as query validation:
+ * primary ids always accept `eq`/`in`; other predicates, sorting, faceting, and keyword search need
+ * `query.searchable` plus the matching flag and a schema that supports it.
+ */
+export function resolvePropertyQueryCapabilities(
+  property: Property,
+  valueTypesById: ReadonlyMap<string, ValueType>
+): PropertyQueryCapabilities {
+  const query = property.query?.searchable === true ? property.query : undefined
+  const schema = resolveQuerySchema(property.schema, valueTypesById)
+  const operators = new Set<PropertyQueryOperator>(property.primary ? PRIMARY_OPERATORS : [])
+
+  if (query?.filterable === true && schema) {
+    if (isExactSchema(schema)) for (const op of EXACT_OPERATORS) operators.add(op)
+    if (isSortableSchema(schema)) for (const op of RANGE_OPERATORS) operators.add(op)
+    if (isContainsSchema(schema)) operators.add("contains")
+  }
+
+  return {
+    operators: OPERATOR_ORDER.filter((op) => operators.has(op)),
+    sortable: query?.sortable === true && schema !== undefined && isSortableSchema(schema),
+    facet: query?.facet === true && schema !== undefined && isFacetSchema(schema),
+    text:
+      query?.text === true &&
+      property.mode !== "telemetry" &&
+      schema !== undefined &&
+      isTextSchema(schema),
+  }
+}
+
+function resolveQuerySchema(
+  schema: Schema,
+  valueTypesById: ReadonlyMap<string, ValueType>,
+  seen = new Set<string>()
+): Schema | undefined {
+  if (typeof schema === "string" || schema.type !== "valueTypeRef") return schema
+  if (seen.has(schema.valueTypeId)) return undefined
+  seen.add(schema.valueTypeId)
+  const resolved = schema._resolved ?? valueTypesById.get(schema.valueTypeId)?.schema
+  return resolved ? resolveQuerySchema(resolved, valueTypesById, seen) : undefined
+}

package/src/ontology/refs.ts

@@ -1,5 +1,6 @@
 import { OntologyValidationError } from "./errors"
 import type { InferSchema } from "./inference"
+import type { RegisteredValueTypes } from "./registered"
 import type { ObjectType, Schema, ValueType } from "./types"
 import { isRecord, validateSchemaValue } from "./validation"
 
@@ -17,7 +18,7 @@ export type SchemaOrRef = Schema | ObjectRefSchema
 
 export type InferSchemaOrRef<
   TSchema extends SchemaOrRef,
-  TValueTypes extends readonly ValueType[] = [],
+  TValueTypes extends readonly ValueType[] = RegisteredValueTypes,
 > =
   TSchema extends ObjectRefSchema<infer TObjectTypeId>
     ? ObjectRef<TObjectTypeId>
@@ -25,14 +26,40 @@ export type InferSchemaOrRef<
       ? InferSchema<TSchema, TValueTypes>
       : never
 
-export function ref<const TObjectType extends ObjectType>(
-  objectType: TObjectType
-): ObjectRefSchema<TObjectType["id"]> {
-  return {
+interface RefBuilder {
+  /**
+   * Reference to one object of `objectType`, for Action and Workflow parameters.
+   *
+   * Object properties point at other objects with `link(...)` instead: a link is traversable,
+   * queryable from both ends, and kept consistent when its target is deleted.
+   */
+  <const TObjectType extends ObjectType>(
+    objectType: TObjectType
+  ): ObjectRefSchema<TObjectType["id"]>
+  /** Reference to a Sixb user, valued `{ type: "user", id }`. Serialized as `"userRef"`. */
+  user(): "userRef"
+  /** Reference to a stored file, valued as a `FileRef`. Serialized as `"fileRef"`. */
+  file(): "fileRef"
+}
+
+/**
+ * Schemas that point outside the value itself.
+ *
+ * Scalars are plain strings (`"string"`, `"timestamp"`); anything that points elsewhere or takes
+ * parameters is a builder: `ref(Customer)`, `ref.user()`, `ref.file()`.
+ */
+export const ref: RefBuilder = Object.assign(
+  <const TObjectType extends ObjectType>(
+    objectType: TObjectType
+  ): ObjectRefSchema<TObjectType["id"]> => ({
     type: "objectRef",
     objectTypeId: objectType.id,
+  }),
+  {
+    user: (): "userRef" => "userRef",
+    file: (): "fileRef" => "fileRef",
   }
-}
+)
 
 /** Build an exact, typed reference to one object instance. */
 export function objectRef<const TObjectType extends ObjectType>(

package/src/ontology/registered.ts

@@ -0,0 +1,22 @@
+import type { ObjectTypeWithPropertyTokens } from "./tokens"
+import type { SixbObjectTypeMap, SixbValueTypeMap, ValueType } from "./types"
+
+/**
+ * Every object type the generated ontology manifest registers.
+ *
+ * It is the one registry every typed surface resolves string link targets against, so the same
+ * query is typed the same way in an Action, a Workflow and the browser. Without a manifest it is the
+ * loose base type: id-only link targets then degrade gracefully instead of failing.
+ *
+ * Deliberately not generic. A registry parameterized per call site gives each site its own type
+ * identity, and TypeScript then has to compare otherwise identical SDK types structurally.
+ */
+export type RegisteredObjectType = [keyof SixbObjectTypeMap] extends [never]
+  ? ObjectTypeWithPropertyTokens
+  : Extract<SixbObjectTypeMap[keyof SixbObjectTypeMap], ObjectTypeWithPropertyTokens>
+
+/** Every value type the generated ontology manifest registers, for string-only `valueTypeRef`s. */
+export type RegisteredValueTypes = readonly Extract<
+  SixbValueTypeMap[keyof SixbValueTypeMap],
+  ValueType
+>[]

package/src/ontology/registry.ts

@@ -68,9 +68,11 @@ function isOntologyDocumentSource(
  * via `valueTypeRef` nodes that carry a `_resolved` schema.
  *
  * This enables auto-registration: when codegen emits `valueTypeRef(VT)`,
- * it stores the resolved schema inline. We extract it here so the runtime
- * `valueTypesById` registry is populated without requiring users to pass
- * ValueTypes explicitly.
+ * it stores the resolved schema (and the semantic type, if any) inline. We
+ * extract them here so the runtime `valueTypesById` registry is populated
+ * without requiring users to pass ValueTypes explicitly. Unit validation reads
+ * the semantic type from that registry, so dropping it would make a
+ * unit-bearing value type reject every unit.
  */
 function extractValueTypesFromSchema(
   schema: Schema,
@@ -89,6 +91,7 @@ function extractValueTypesFromSchema(
         id: schema.valueTypeId,
         name: localName,
         schema: schema._resolved,
+        ...(schema._semanticType === undefined ? {} : { semanticType: schema._semanticType }),
       })
       extractValueTypesFromSchema(schema._resolved, collected, seen)
     }

package/src/ontology/tokens.ts

@@ -1,3 +1,4 @@
+import type { InferObjectProperties } from "./inference"
 import {
   createLinkPathSelection,
   type LinkPathSelectionBuilder,
@@ -7,6 +8,7 @@ import type { ObjectLink, ObjectType, Property } from "./types"
 
 declare const propertyTokenBrand: unique symbol
 declare const linkTokenBrand: unique symbol
+declare const objectPropertiesBrand: unique symbol
 
 /**
  * Strongly-typed handle to a property on a specific object type.
@@ -57,12 +59,49 @@ export type LinkTokenMap<TObjectType extends ObjectType> = {
 /**
  * Object type with property tokens (`p.*`).
  *
- * The original ontology shape is preserved; this only adds typed handles.
+ * The original ontology shape is preserved; this only adds typed handles, and the type-only
+ * property values every row of this object type carries.
  */
 export type ObjectTypeWithPropertyTokens<TObjectType extends ObjectType = ObjectType> =
   TObjectType & {
     readonly p: PropertyTokenMap<TObjectType>
-  }
+  } & ObjectPropertiesMetadata<TObjectType>
+
+/**
+ * Type-only property values of an object type, inferred once where the type is defined so SDK types
+ * read them back by indexed access instead of re-deriving them from `properties`.
+ *
+ * Exported only so declaration files can name it, like the token maps.
+ */
+export type ObjectPropertiesMetadata<TObjectType extends ObjectType> = {
+  readonly [objectPropertiesBrand]?: string extends TObjectType["id"]
+    ? { readonly properties: Record<string, unknown> }
+    : ObjectPropertiesCarrier<TObjectType>
+}
+
+/**
+ * Carrier of an object type's inferred property values.
+ *
+ * When TypeScript relates, or infers between, two instantiations of a generic type it has not been
+ * told the variance of, it measures that variance by probing the type with marker types. A probe
+ * that reached the schema inference over a marker overflowed its depth limits (TS2589), in code as
+ * ordinary as reassigning a query. Declaring this carrier invariant stops every probe here, so an
+ * object type costs no more to relate than its tokens. The loose base type carries a plain record
+ * instead, which a concrete object type's carrier relates to structurally.
+ */
+interface ObjectPropertiesCarrier<in out TObjectType extends ObjectType> {
+  readonly properties: InferObjectProperties<TObjectType>
+}
+
+/**
+ * The property values of an object type, as its rows carry them.
+ *
+ * Reads the type computed once by {@link ObjectTypeWithPropertyTokens}. For the loose base type,
+ * whose property ids are not statically known, it is `Record<string, unknown>`.
+ */
+export type ObjectTypeProperties<TObjectType extends ObjectTypeWithPropertyTokens> = NonNullable<
+  TObjectType[typeof objectPropertiesBrand]
+>["properties"]
 
 /**
  * Object type with property tokens (`p.*`) and link tokens (`l.*`).

package/src/ontology/types.ts

@@ -22,6 +22,7 @@ import type { QuantitativeTypeId } from "./units"
  * - `"uuid"` for an external system identifier.
  * - `"timestamp"` for `lastObservedAt`.
  * - `"fileRef"` for blob-backed documents, images, and attachments.
+ * - `"userRef"` for a Sixb user, such as a task's assignee (author it with `ref.user()`).
  * - `"double"` for telemetry such as temperature or humidity.
  */
 export type PrimitiveSchema =
@@ -34,12 +35,18 @@ export type PrimitiveSchema =
   | "timestamp"
   | "uuid"
   | "fileRef"
+  | "userRef"
 
 export interface ValueTypeRefSchema {
   type: "valueTypeRef"
   valueTypeId: string
   /** Type-level: fully resolved schema for direct inference. Populated by codegen. */
   _resolved?: Schema
+  /**
+   * The referenced value type's `semanticType`, carried next to `_resolved` so a value type that
+   * is registered only through this ref keeps its unit constraint. Populated by `valueTypeRef(VT)`.
+   */
+  _semanticType?: QuantitativeTypeId
 }
 
 /**
@@ -414,13 +421,22 @@ export interface ObjectType {
  * Ambient id-to-object-type index for app ontology definitions.
  *
  * Sixb generates a `.sixb/types/ontology.d.ts` module augmentation that adds
- * entries here, letting client-side query types resolve string link targets
- * like `"Customer"` to the exported `Customer` object type without changing the
- * runtime ontology shape.
+ * entries here. Every typed surface — `sixb.objects(...)`, Action reads, the
+ * client query builder — resolves string link targets like `"Customer"` through
+ * it, without changing the runtime ontology shape.
  */
 // biome-ignore lint/suspicious/noEmptyInterface: App code augments this interface.
 export interface SixbObjectTypeMap {}
 
+/**
+ * Ambient id-to-value-type index, generated alongside {@link SixbObjectTypeMap}.
+ *
+ * It types properties declared with a string-only `valueTypeRef("id")`, whose
+ * schema is not carried by the reference itself.
+ */
+// biome-ignore lint/suspicious/noEmptyInterface: App code augments this interface.
+export interface SixbValueTypeMap {}
+
 /**
  * Root ontology document for object type modeling.
  *