@sixb/core 0.0.1

package/src/ontology/validation/links.ts

@@ -0,0 +1,126 @@
+import type { JsonValue } from "../../json"
+import type { ObjectLink, ValueType } from ".."
+import { OntologyValidationError } from "../errors"
+import type { ObjectTypeWithPropertyTokens } from "../tokens"
+import { normalizeObjectProperties } from "./normalize"
+import { validatePropertyValue } from "./properties"
+
+/**
+ * Assert that `targetTypeId` is compatible with the link definition's declared target.
+ *
+ * When `isValidLinkTarget` is provided (e.g. for polymorphic subtype checks),
+ * it is used instead of strict equality.
+ */
+export function assertLinkTargetType(
+  objectTypeId: string,
+  linkId: string,
+  linkDefinition: ObjectLink,
+  targetTypeId: string,
+  isValidLinkTarget?: (expected: string | string[], actual: string) => boolean
+): void {
+  const valid = isValidLinkTarget
+    ? isValidLinkTarget(linkDefinition.targetObjectTypeId, targetTypeId)
+    : targetTypeId === linkDefinition.targetObjectTypeId
+  if (!valid) {
+    const expected = Array.isArray(linkDefinition.targetObjectTypeId)
+      ? linkDefinition.targetObjectTypeId.join(" | ")
+      : linkDefinition.targetObjectTypeId
+    throw new OntologyValidationError(
+      `[Sixb] Link ${objectTypeId}.${linkId} must target '${expected}', got '${targetTypeId}'`
+    )
+  }
+}
+
+/**
+ * Verify that `actualTarget` is either the same as or a subtype of the
+ * link's declared `targetObjectTypeId`. Throws on mismatch.
+ */
+export function assertTargetTypeCompatible(
+  getSubTypes: (typeId: string) => string[],
+  declaredTarget: string | string[],
+  actualTarget: string,
+  context: string
+): void {
+  if (declaredTarget === "*") return
+  const types = Array.isArray(declaredTarget) ? declaredTarget : [declaredTarget]
+  if (types.includes("*")) return
+  for (const type of types) {
+    if (actualTarget === type || getSubTypes(type).includes(actualTarget)) return
+  }
+  const expected = types.join(" | ")
+  throw new OntologyValidationError(
+    `[Sixb] ${context}: target type '${actualTarget}' is not compatible with declared target '${expected}'`
+  )
+}
+
+export function normalizeLinkProperties(
+  objectType: ObjectTypeWithPropertyTokens,
+  link: ObjectLink,
+  properties: Readonly<Record<string, unknown>> | undefined,
+  valueTypesById: ReadonlyMap<string, ValueType>
+): Record<string, JsonValue> | undefined {
+  if (properties === undefined) return undefined
+  return normalizeObjectProperties(
+    link.properties ?? [],
+    properties,
+    valueTypesById,
+    `${objectType.id}.${link.id}`
+  )
+}
+
+export function validateLinkProperties(
+  objectType: ObjectTypeWithPropertyTokens,
+  link: ObjectLink,
+  properties: Record<string, unknown> | undefined,
+  existingProperties: Record<string, unknown> | undefined,
+  valueTypesById: ReadonlyMap<string, ValueType>
+): void {
+  const linkProperties = link.properties ?? []
+  const provided = properties ?? {}
+
+  if (linkProperties.length === 0) {
+    if (Object.keys(provided).length > 0) {
+      throw new OntologyValidationError(
+        `[Sixb] Link ${objectType.id}.${link.id} does not define link properties`
+      )
+    }
+    return
+  }
+
+  const knownPropertyIds = new Set(linkProperties.map((property) => property.id))
+  for (const propertyId of Object.keys(provided)) {
+    if (!knownPropertyIds.has(propertyId)) {
+      throw new OntologyValidationError(
+        `[Sixb] Unknown link property '${propertyId}' for link '${objectType.id}.${link.id}'`
+      )
+    }
+  }
+
+  for (const [propertyId, value] of Object.entries(provided)) {
+    const property = linkProperties.find((candidate) => candidate.id === propertyId)
+    if (!property) {
+      continue
+    }
+
+    validatePropertyValue(
+      property,
+      value,
+      `${objectType.id}.${link.id}.${propertyId}`,
+      valueTypesById
+    )
+  }
+
+  // Required checks run against merged state so partial link updates are valid.
+  const merged = {
+    ...(existingProperties ?? {}),
+    ...provided,
+  }
+
+  for (const property of linkProperties) {
+    if (property.required && merged[property.id] === undefined) {
+      throw new OntologyValidationError(
+        `[Sixb] Missing required link property '${property.id}' for link '${objectType.id}.${link.id}'`
+      )
+    }
+  }
+}

package/src/ontology/validation/normalize.ts

@@ -0,0 +1,215 @@
+import { assertJsonValue, cloneJsonValue, type JsonValue } from "../../json"
+import type { ObjectFieldSchema, Property, Schema, ValueType } from ".."
+import { normalizeDecimalValue } from "../decimal"
+import { OntologyValidationError } from "../errors"
+import { resolveValueTypeSchema } from "./schema"
+
+/**
+ * Normalize a property bag to JSON-safe values using each property's schema —
+ * notably converting `Date` to an ISO string for `date`/`timestamp` props.
+ * Unknown properties are skipped; `null` passes through unchanged.
+ *
+ * Shared by the object upsert and edit paths so both emit the same serializable
+ * shape; the typed surface accepts `Date | string`, the wire stores strings.
+ */
+export function normalizeObjectProperties(
+  definitions: readonly Property[],
+  properties: Readonly<Record<string, unknown>>,
+  valueTypesById: ReadonlyMap<string, ValueType>,
+  path: string
+): Record<string, JsonValue> {
+  const normalized: Record<string, JsonValue> = {}
+  for (const [propertyId, value] of Object.entries(properties)) {
+    const property = definitions.find((candidate) => candidate.id === propertyId)
+    if (!property) continue
+    normalized[propertyId] =
+      value === null
+        ? null
+        : normalizeSchemaValue(property.schema, value, `${path}.${propertyId}`, valueTypesById)
+  }
+  return normalized
+}
+
+export function normalizeSchemaValue(
+  schema: Schema,
+  value: unknown,
+  path: string,
+  valueTypesById: ReadonlyMap<string, ValueType>
+): JsonValue {
+  if (typeof schema === "string") {
+    switch (schema) {
+      case "date":
+        return normalizeDateValue(value, path)
+      case "timestamp":
+        return normalizeTimestampValue(value, path)
+      case "decimal":
+        return normalizeDecimal(value, path)
+      default:
+        assertJsonValue(value, path)
+        return cloneJsonValue(value)
+    }
+  }
+
+  if (schema.type === "valueTypeRef") {
+    return normalizeSchemaValue(
+      resolveValueTypeSchema(schema, valueTypesById, path),
+      value,
+      path,
+      valueTypesById
+    )
+  }
+
+  if (schema.type === "enum") {
+    assertJsonValue(value, path)
+    return cloneJsonValue(value)
+  }
+
+  if (schema.type === "array") {
+    if (!Array.isArray(value)) {
+      throw new OntologyValidationError(`[Sixb] Property ${path} must be an array`)
+    }
+    return (value as readonly unknown[]).map((entry, index) =>
+      normalizeSchemaValue(schema.items, entry, `${path}[${index}]`, valueTypesById)
+    )
+  }
+
+  if (schema.type === "map") {
+    const record = assertPlainRecord(value, path)
+    const entries = Object.entries(record).map(([key, entry]) => [
+      key,
+      normalizeSchemaValue(schema.valueSchema, entry, `${path}.${key}`, valueTypesById),
+    ])
+    return Object.fromEntries(entries)
+  }
+
+  const fields = schema.properties
+  const record = assertPlainRecord(value, path)
+  const output: Record<string, JsonValue> = {}
+  for (const [fieldId, field] of Object.entries(fields)) {
+    const fieldValue = record[fieldId]
+    if (fieldValue === undefined) {
+      continue
+    }
+    output[fieldId] = normalizeObjectFieldValue(
+      field,
+      fieldValue,
+      `${path}.${fieldId}`,
+      valueTypesById
+    )
+  }
+  return output
+}
+
+function normalizeObjectFieldValue(
+  field: ObjectFieldSchema,
+  value: unknown,
+  path: string,
+  valueTypesById: ReadonlyMap<string, ValueType>
+): JsonValue {
+  if (value === null) {
+    return null
+  }
+
+  return normalizeSchemaValue(field.schema, value, path, valueTypesById)
+}
+
+function assertPlainRecord(value: unknown, path: string): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new OntologyValidationError(`[Sixb] Property ${path} must be an object`)
+  }
+  return value as Record<string, unknown>
+}
+
+function normalizeDateValue(value: unknown, path: string): string {
+  const date = normalizeDateLike(value, path)
+  return date.toISOString().slice(0, 10)
+}
+
+function normalizeTimestampValue(value: unknown, path: string): string {
+  return normalizeDateLike(value, path).toISOString()
+}
+
+function normalizeDecimal(value: unknown, path: string): string {
+  if (typeof value !== "string") {
+    throw new OntologyValidationError(`[Sixb] Property ${path} must be an exact decimal string`)
+  }
+
+  try {
+    return normalizeDecimalValue(value)
+  } catch {
+    throw new OntologyValidationError(`[Sixb] Property ${path} must be an exact decimal string`)
+  }
+}
+
+function normalizeDateLike(value: unknown, path: string): Date {
+  const date = value instanceof Date ? value : new Date(String(value))
+  if (Number.isNaN(date.getTime())) {
+    throw new OntologyValidationError(`[Sixb] Property ${path} must be a valid date`)
+  }
+  return date
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Inverse of `normalizeSchemaValue` for the handler-facing surface: re-hydrate
+ * `date`/`timestamp` values from their stored ISO string back into a `Date`, so
+ * a handler receives the `Date` its types promise. Other scalars pass through;
+ * arrays, maps, objects, and value-type refs recurse. The input is assumed to be
+ * already validated/normalized JSON, so this is permissive and never throws.
+ */
+export function coerceSchemaValueToTyped(
+  schema: Schema,
+  value: unknown,
+  valueTypesById: ReadonlyMap<string, ValueType>
+): unknown {
+  if (value === null || value === undefined) {
+    return value
+  }
+
+  if (typeof schema === "string") {
+    if (schema === "date" || schema === "timestamp") {
+      return value instanceof Date ? value : new Date(String(value))
+    }
+    return value
+  }
+
+  if (schema.type === "valueTypeRef") {
+    return coerceSchemaValueToTyped(
+      resolveValueTypeSchema(schema, valueTypesById, ""),
+      value,
+      valueTypesById
+    )
+  }
+
+  if (schema.type === "enum") {
+    return value
+  }
+
+  if (schema.type === "array") {
+    if (!Array.isArray(value)) return value
+    return (value as readonly unknown[]).map((entry) =>
+      coerceSchemaValueToTyped(schema.items, entry, valueTypesById)
+    )
+  }
+
+  if (schema.type === "map") {
+    if (!isPlainRecord(value)) return value
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [
+        key,
+        coerceSchemaValueToTyped(schema.valueSchema, entry, valueTypesById),
+      ])
+    )
+  }
+
+  if (!isPlainRecord(value)) return value
+  const output: Record<string, unknown> = { ...value }
+  for (const [fieldId, field] of Object.entries(schema.properties)) {
+    if (value[fieldId] === undefined) continue
+    output[fieldId] = coerceSchemaValueToTyped(field.schema, value[fieldId], valueTypesById)
+  }
+  return output
+}

package/src/ontology/validation/properties.ts

@@ -0,0 +1,235 @@
+import type { ObjectLink, ObjectType, Property, Schema, ValueType } from ".."
+import { OntologyValidationError } from "../errors"
+import type { LinkToken, ObjectTypeWithPropertyTokens, PropertyToken } from "../tokens"
+import { validateSchemaValue } from "./schema"
+
+export function assertObjectTypeRegistered(
+  objectTypesById: ReadonlyMap<string, ObjectTypeWithPropertyTokens>,
+  objectType: ObjectTypeWithPropertyTokens
+): void {
+  if (!objectTypesById.has(objectType.id)) {
+    throw new OntologyValidationError(
+      `[Sixb] Object type is not registered in this runtime: ${objectType.id}`
+    )
+  }
+}
+
+export function assertPropertyTokenBelongsToObjectType(
+  objectType: ObjectTypeWithPropertyTokens,
+  property: PropertyToken<string, string, Property>
+): void {
+  if (property.objectTypeId !== objectType.id) {
+    throw new OntologyValidationError(
+      `[Sixb] Property token ${property.objectTypeId}.${property.id} cannot be used with ${objectType.id}`
+    )
+  }
+}
+
+export function assertLinkTokenBelongsToObjectType(
+  objectType: ObjectTypeWithPropertyTokens,
+  link: unknown
+): asserts link is LinkToken<string, string, string | readonly string[], ObjectLink> {
+  if (!isLinkTokenLike(link)) {
+    throw new OntologyValidationError(
+      `[Sixb] Expected a link token from ${objectType.id}.l.<linkId>, not a plain link id.`
+    )
+  }
+
+  if (link.objectTypeId !== objectType.id) {
+    throw new OntologyValidationError(
+      `[Sixb] Link token ${link.objectTypeId}.${link.id} cannot be used with ${objectType.id}`
+    )
+  }
+}
+
+function isLinkTokenLike(
+  value: unknown
+): value is LinkToken<string, string, string | readonly string[], ObjectLink> {
+  if (typeof value !== "object" || value === null) return false
+  if (
+    !("objectTypeId" in value) ||
+    !("id" in value) ||
+    !("targetObjectTypeId" in value) ||
+    !("link" in value)
+  ) {
+    return false
+  }
+
+  return (
+    typeof value.objectTypeId === "string" &&
+    typeof value.id === "string" &&
+    isLinkTargetTypeId(value.targetObjectTypeId) &&
+    typeof value.link === "object" &&
+    value.link !== null
+  )
+}
+
+function isLinkTargetTypeId(value: unknown): value is string | readonly string[] {
+  return typeof value === "string" || (Array.isArray(value) && value.every(isString))
+}
+
+function isString(value: unknown): value is string {
+  return typeof value === "string"
+}
+
+export function assertKnownProperties(
+  objectType: ObjectTypeWithPropertyTokens,
+  properties: Record<string, unknown>
+): void {
+  const knownIds = new Set(objectType.properties.map((property) => property.id))
+  for (const propertyId of Object.keys(properties)) {
+    if (!knownIds.has(propertyId)) {
+      throw new OntologyValidationError(
+        `[Sixb] Unknown property '${propertyId}' for object type '${objectType.id}'`
+      )
+    }
+  }
+}
+
+export function assertRequiredProperties(
+  objectType: ObjectTypeWithPropertyTokens,
+  properties: Record<string, unknown>
+): void {
+  for (const property of objectType.properties) {
+    if (property.required && properties[property.id] === undefined) {
+      throw new OntologyValidationError(
+        `[Sixb] Missing required property '${property.id}' for object type '${objectType.id}'`
+      )
+    }
+  }
+}
+
+/** Runtime validation protects callers even when TypeScript checks are bypassed. */
+export function validateObjectProperties(
+  objectType: ObjectTypeWithPropertyTokens,
+  properties: Record<string, unknown>,
+  valueTypesById: ReadonlyMap<string, ValueType>
+): void {
+  for (const [propertyId, value] of Object.entries(properties)) {
+    const property = objectType.properties.find((candidate) => candidate.id === propertyId)
+    if (!property) {
+      continue
+    }
+    validatePropertyValue(property, value, `${objectType.id}.${propertyId}`, valueTypesById)
+  }
+}
+
+/**
+ * Validate that every registered object type has exactly one primary property
+ * that is required and has schema "string".
+ *
+ * Returns a Map<objectTypeId, primaryPropertyId> for runtime derivation.
+ */
+export function validatePrimaryProperties(
+  objectTypesById: ReadonlyMap<string, ObjectType>
+): Map<string, string> {
+  const result = new Map<string, string>()
+
+  for (const [typeId, objectType] of objectTypesById) {
+    const primaries = objectType.properties.filter((p) => p.primary)
+
+    if (primaries.length === 0) {
+      throw new OntologyValidationError(
+        `[Sixb] Object type '${typeId}' has no primary property. ` +
+          `Define one with prop("id", "string", { required: true, primary: true }).`
+      )
+    }
+    if (primaries.length > 1) {
+      throw new OntologyValidationError(
+        `[Sixb] Object type '${typeId}' has ${primaries.length} primary properties, expected 1`
+      )
+    }
+
+    const primary = primaries[0]
+    if (!primary.required) {
+      throw new OntologyValidationError(
+        `[Sixb] Primary property '${primary.id}' on '${typeId}' must be required`
+      )
+    }
+    if (primary.schema !== "string") {
+      throw new OntologyValidationError(
+        `[Sixb] Primary property '${primary.id}' on '${typeId}' must have schema "string", got "${String(primary.schema)}"`
+      )
+    }
+
+    result.set(typeId, primary.id)
+  }
+
+  return result
+}
+
+export function validatePropertyDefinitions(
+  objectTypesById: ReadonlyMap<string, ObjectType>,
+  valueTypesById: ReadonlyMap<string, ValueType>
+): void {
+  for (const [typeId, objectType] of objectTypesById) {
+    for (const property of objectType.properties) {
+      // Telemetry stores time-series samples, not blob references, even when fileRef is nested.
+      if (property.mode === "telemetry" && schemaContainsFileRef(property.schema, valueTypesById)) {
+        throw new OntologyValidationError(
+          `[Sixb] Telemetry property '${property.id}' on '${typeId}' cannot use fileRef`
+        )
+      }
+    }
+  }
+}
+
+export function validatePropertyValue(
+  property: Property,
+  value: unknown,
+  path: string,
+  valueTypesById: ReadonlyMap<string, ValueType>
+): void {
+  if (value === undefined) {
+    throw new OntologyValidationError(`[Sixb] Property ${path} cannot be undefined`)
+  }
+
+  if (value === null) {
+    if (property.nullable) {
+      return
+    }
+    throw new OntologyValidationError(`[Sixb] Property ${path} cannot be null`)
+  }
+
+  validateSchemaValue(property.schema, value, path, valueTypesById)
+}
+
+function schemaContainsFileRef(
+  schema: Schema,
+  valueTypesById: ReadonlyMap<string, ValueType>,
+  seenValueTypeIds = new Set<string>()
+): boolean {
+  if (schema === "fileRef") {
+    return true
+  }
+
+  if (typeof schema === "string") {
+    return false
+  }
+
+  if (schema.type === "array") {
+    return schemaContainsFileRef(schema.items, valueTypesById, seenValueTypeIds)
+  }
+
+  if (schema.type === "map") {
+    return schemaContainsFileRef(schema.valueSchema, valueTypesById, seenValueTypeIds)
+  }
+
+  if (schema.type === "object") {
+    return Object.values(schema.properties).some((field) =>
+      schemaContainsFileRef(field.schema, valueTypesById, seenValueTypeIds)
+    )
+  }
+
+  if (schema.type === "valueTypeRef") {
+    if (seenValueTypeIds.has(schema.valueTypeId)) {
+      return false
+    }
+
+    seenValueTypeIds.add(schema.valueTypeId)
+    const resolved = schema._resolved ?? valueTypesById.get(schema.valueTypeId)?.schema
+    return resolved ? schemaContainsFileRef(resolved, valueTypesById, seenValueTypeIds) : false
+  }
+
+  return false
+}