@sixb/core 0.0.1

package/src/projections/errors.ts

@@ -0,0 +1,3 @@
+export class ProjectionValidationError extends Error {
+  readonly name = "ProjectionValidationError"
+}

package/src/projections/index.ts

@@ -0,0 +1,32 @@
+// ── Builders ─────────────────────────────────────────────────
+
+export {
+  categorizeProjections,
+  defineProjection,
+  fromForeignKey,
+  isLinkProjectionDefinition,
+  isObjectProjectionDefinition,
+  isProjectionDefinition,
+  isTelemetryProjectionDefinition,
+  projectionKindOf,
+} from "./builders"
+// ── Errors ──────────────────────────────────────────────────
+export { ProjectionValidationError } from "./errors"
+// ── Types ────────────────────────────────────────────────────
+export type {
+  ForeignKeyDescriptor,
+  LinkProjectionDefinition,
+  LinkProjectionTarget,
+  ObjectProjectionDefinition,
+  ObjectProjectionTarget,
+  ProjectionDefinition,
+  ProjectionKind,
+  ProjectionTarget,
+  ProjectionTargetByKind,
+  TelemetryProjectionDefinition,
+} from "./types"
+// ── Validation ───────────────────────────────────────────────
+export {
+  validateProjectionsAtStartup,
+  validateTelemetryProjectionFieldMapping,
+} from "./validation"

package/src/projections/internal.ts

@@ -0,0 +1,75 @@
+import { sha256Canonical } from "../materialization/identity"
+import type { ProjectionMaterializationIdentity } from "../materialization/model"
+import type { ProjectionRegistry } from "./registry"
+import type { ProjectionDispatchDescriptor } from "./types"
+
+const projectionRegistryKey: unique symbol = Symbol("sixb.projectionRegistry")
+
+interface ProjectionRegistryOwner {
+  readonly [projectionRegistryKey]?: ProjectionRegistry
+}
+
+export function registerProjectionRegistry(owner: object, registry: ProjectionRegistry): void {
+  const registered = (owner as ProjectionRegistryOwner)[projectionRegistryKey]
+  if (registered && registered !== registry) {
+    throw new Error("[Sixb] Projection registry is already registered for this owner.")
+  }
+
+  Object.defineProperty(owner, projectionRegistryKey, {
+    configurable: false,
+    enumerable: false,
+    value: registry,
+    writable: false,
+  })
+}
+
+export function getProjectionRegistry(owner: object): ProjectionRegistry {
+  const registry = (owner as ProjectionRegistryOwner)[projectionRegistryKey]
+  if (registry) return registry
+  throw new Error("[Sixb] Projection registry is not registered for this runtime.")
+}
+
+/** Read-only orchestration view without exposing the registry capability to callers. */
+export function getProjectionDispatchDescriptors(
+  owner: object
+): readonly ProjectionDispatchDescriptor[] {
+  return getProjectionRegistry(owner).getDispatchDescriptors()
+}
+
+/** Copies the opaque registry capability when an internal runtime context is reconstructed. */
+export function shareProjectionRegistry(source: object, target: object): void {
+  registerProjectionRegistry(target, getProjectionRegistry(source))
+}
+
+export function createProjectionRunId(
+  projectId: string,
+  identity: ProjectionMaterializationIdentity
+): string {
+  return sha256Canonical({
+    projectId,
+    projectionId: identity.projectionId,
+    projectionKind: identity.projectionKind,
+    protocol: identity.protocol,
+    datasetId: identity.datasetVersion.datasetId,
+    versionId: identity.datasetVersion.versionId,
+    createdAt: identity.datasetVersion.createdAt,
+    ontologyRevision: identity.ontologyRevision,
+    projectionRevision: identity.projectionRevision,
+    ownershipHash: identity.ownershipHash,
+  })
+}
+
+/**
+ * What the projection worker needs and an app author does not.
+ *
+ * `projectionTargetOf` derives the object types a projection writes, to record them on the run.
+ * `validateTelemetryProjectionFieldMapping` re-checks a telemetry mapping against the dataset schema
+ * before writing. Both are plumbing, so they live here instead of on the `@sixb/core` root.
+ *
+ * `projectionKindOf` deliberately does not follow: nothing outside `packages/core` calls it, and a
+ * subpath export with no importer is the dead surface this curation removes.
+ */
+export { projectionTargetOf } from "./builders"
+export { validateTelemetryProjectionFieldMapping } from "./validation"
+
+export type { ProjectionDispatchDescriptor, ProjectionMaterializationIdentity, ProjectionRegistry }

package/src/projections/ownership.ts

@@ -0,0 +1,134 @@
+import { compareStrings } from "../json"
+import type { OntologyRegistry } from "../ontology"
+import { ProjectionValidationError } from "./errors"
+import type { ProjectionDefinition, ProjectionOwnership } from "./types"
+
+export function computeProjectionOwnership(
+  projection: ProjectionDefinition,
+  ontology: OntologyRegistry
+): ProjectionOwnership {
+  if (projection._tag === "ObjectProjectionDefinition") {
+    const primaryId = ontology.getPrimaryPropertyId(projection.objectTypeId)
+    return freezeOwnership({
+      objects: [
+        {
+          objectTypeId: projection.objectTypeId,
+          existence: true,
+          propertyIds: Object.keys(projection.properties)
+            .filter((propertyId) => propertyId !== primaryId)
+            .sort(compareStrings),
+        },
+      ],
+      links: Object.keys(projection.links)
+        .sort(compareStrings)
+        .map((linkId) => ({ sourceObjectTypeId: projection.objectTypeId, linkId })),
+      telemetry: [],
+    })
+  }
+
+  if (projection._tag === "LinkProjectionDefinition") {
+    return freezeOwnership({
+      objects: [],
+      links: [
+        {
+          sourceObjectTypeId: projection.sourceObjectTypeId,
+          linkId: projection.linkId,
+        },
+      ],
+      telemetry: [],
+    })
+  }
+
+  return freezeOwnership({
+    objects: [],
+    links: [],
+    telemetry: [
+      {
+        objectTypeId: projection.objectTypeId,
+        propertyId: projection.propertyId,
+      },
+    ],
+  })
+}
+
+export interface ProjectionOwnershipRecord<
+  TDefinition extends ProjectionDefinition = ProjectionDefinition,
+> {
+  readonly definition: TDefinition
+  readonly ownership: ProjectionOwnership
+}
+
+export function validateProjectionOwnership(
+  projections: readonly ProjectionOwnershipRecord[]
+): void {
+  const existenceOwners = new Map<string, string>()
+  const propertyOwners = new Map<string, string>()
+  const linkOwners = new Map<string, string>()
+  const telemetryOwners = new Map<string, string>()
+
+  for (const { definition, ownership } of projections) {
+    for (const object of ownership.objects) {
+      if (object.existence) {
+        registerOwner(
+          existenceOwners,
+          object.objectTypeId,
+          definition.id,
+          `object type '${object.objectTypeId}' existence`
+        )
+      }
+      for (const propertyId of object.propertyIds) {
+        registerOwner(
+          propertyOwners,
+          JSON.stringify([object.objectTypeId, propertyId]),
+          definition.id,
+          `property '${object.objectTypeId}.${propertyId}'`
+        )
+      }
+    }
+    for (const link of ownership.links) {
+      registerOwner(
+        linkOwners,
+        JSON.stringify([link.sourceObjectTypeId, link.linkId]),
+        definition.id,
+        `link scope '${link.sourceObjectTypeId}.${link.linkId}'`
+      )
+    }
+    for (const telemetry of ownership.telemetry) {
+      registerOwner(
+        telemetryOwners,
+        JSON.stringify([telemetry.objectTypeId, telemetry.propertyId]),
+        definition.id,
+        `telemetry source '${telemetry.objectTypeId}.${telemetry.propertyId}'`
+      )
+    }
+  }
+}
+
+function registerOwner(
+  owners: Map<string, string>,
+  key: string,
+  projectionId: string,
+  description: string
+): void {
+  const existing = owners.get(key)
+  if (existing !== undefined) {
+    throw new ProjectionValidationError(
+      `[Sixb] Projection '${projectionId}' overlaps ${description} owned by projection '${existing}'.`
+    )
+  }
+  owners.set(key, projectionId)
+}
+
+function freezeOwnership(ownership: ProjectionOwnership): ProjectionOwnership {
+  return Object.freeze({
+    objects: Object.freeze(
+      ownership.objects.map((object) =>
+        Object.freeze({ ...object, propertyIds: Object.freeze([...object.propertyIds]) })
+      )
+    ),
+    links: Object.freeze(ownership.links.map((link) => Object.freeze({ ...link }))),
+    telemetry: Object.freeze(
+      ownership.telemetry.map((telemetry) => Object.freeze({ ...telemetry }))
+    ),
+  })
+}

package/src/projections/registry.ts

@@ -0,0 +1,269 @@
+import type { DatasetDefinition } from "../datasets"
+import type { OntologyRegistry } from "../ontology"
+import { isProjectionDefinition } from "./builders"
+import { ProjectionValidationError } from "./errors"
+import {
+  computeOntologyRevision,
+  computeProjectionOwnershipHash,
+  computeProjectionRevision,
+} from "./revision"
+import type {
+  LinkProjectionDefinition,
+  ObjectProjectionDefinition,
+  ProjectionDefinition,
+  ProjectionDispatchDescriptor,
+  ResolvedProjection,
+  TelemetryProjectionDefinition,
+} from "./types"
+import { type ValidatedProjectionRecord, validateProjectionsAtStartup } from "./validation"
+
+type SourceProjectionDefinition = ObjectProjectionDefinition | LinkProjectionDefinition
+
+export class ProjectionRegistry {
+  readonly ontologyRevision: string
+  private readonly objectProjections: readonly ObjectProjectionDefinition[]
+  private readonly linkProjections: readonly LinkProjectionDefinition[]
+  private readonly telemetryProjections: readonly TelemetryProjectionDefinition[]
+  private readonly projectionsById = new Map<string, ProjectionDefinition>()
+  private readonly sourceById = new Map<string, ResolvedProjection<SourceProjectionDefinition>>()
+  private readonly telemetryById = new Map<
+    string,
+    ResolvedProjection<TelemetryProjectionDefinition>
+  >()
+  private readonly dispatchById = new Map<string, ProjectionDispatchDescriptor>()
+  private readonly dispatchDescriptors: readonly ProjectionDispatchDescriptor[]
+
+  constructor(input: {
+    readonly projections: readonly ProjectionDefinition[]
+    readonly ontology: OntologyRegistry
+    readonly datasetsById: ReadonlyMap<string, DatasetDefinition>
+  }) {
+    const objectProjections: ObjectProjectionDefinition[] = []
+    const linkProjections: LinkProjectionDefinition[] = []
+    const telemetryProjections: TelemetryProjectionDefinition[] = []
+    for (const projection of input.projections) {
+      if (!isProjectionDefinition(projection)) {
+        throw new ProjectionValidationError("[Sixb] Invalid projection definition.")
+      }
+      switch (projection._tag) {
+        case "ObjectProjectionDefinition":
+          objectProjections.push(deepFreeze(cloneObjectProjectionDefinition(projection)))
+          break
+        case "LinkProjectionDefinition":
+          linkProjections.push(deepFreeze(cloneLinkProjectionDefinition(projection)))
+          break
+        case "TelemetryProjectionDefinition":
+          telemetryProjections.push(deepFreeze(cloneTelemetryProjectionDefinition(projection)))
+          break
+      }
+    }
+    this.objectProjections = Object.freeze(objectProjections)
+    this.linkProjections = Object.freeze(linkProjections)
+    this.telemetryProjections = Object.freeze(telemetryProjections)
+
+    const projections = [
+      ...this.objectProjections,
+      ...this.linkProjections,
+      ...this.telemetryProjections,
+    ]
+    assertUniqueProjectionIds(projections)
+    const validated = validateProjectionsAtStartup(
+      {
+        objectProjections: this.objectProjections,
+        linkProjections: this.linkProjections,
+        telemetryProjections: this.telemetryProjections,
+      },
+      input.ontology,
+      input.datasetsById
+    )
+    this.ontologyRevision = computeOntologyRevision(input.ontology)
+
+    const dispatchDescriptors: ProjectionDispatchDescriptor[] = []
+    for (const record of validated.objectProjections) {
+      const resolved = createResolvedProjection(record)
+      this.sourceById.set(resolved.projectionId, resolved)
+      this.projectionsById.set(resolved.projectionId, resolved.definition)
+      dispatchDescriptors.push(createDispatchDescriptor(resolved, this.ontologyRevision))
+    }
+    for (const record of validated.linkProjections) {
+      const resolved = createResolvedProjection(record)
+      this.sourceById.set(resolved.projectionId, resolved)
+      this.projectionsById.set(resolved.projectionId, resolved.definition)
+      dispatchDescriptors.push(createDispatchDescriptor(resolved, this.ontologyRevision))
+    }
+    for (const record of validated.telemetryProjections) {
+      const resolved = createResolvedProjection(record)
+      this.telemetryById.set(resolved.projectionId, resolved)
+      this.projectionsById.set(resolved.projectionId, resolved.definition)
+      dispatchDescriptors.push(createDispatchDescriptor(resolved, this.ontologyRevision))
+    }
+    this.dispatchDescriptors = Object.freeze(dispatchDescriptors)
+    for (const descriptor of this.dispatchDescriptors) {
+      this.dispatchById.set(descriptor.projectionId, descriptor)
+    }
+  }
+
+  listObjectProjections(): readonly ObjectProjectionDefinition[] {
+    return this.objectProjections
+  }
+
+  listLinkProjections(): readonly LinkProjectionDefinition[] {
+    return this.linkProjections
+  }
+
+  listTelemetryProjections(): readonly TelemetryProjectionDefinition[] {
+    return this.telemetryProjections
+  }
+
+  getProjectionById(projectionId: string): ProjectionDefinition | null {
+    return this.projectionsById.get(projectionId) ?? null
+  }
+
+  getDispatchDescriptors(): readonly ProjectionDispatchDescriptor[] {
+    return this.dispatchDescriptors
+  }
+
+  resolveDispatch(projectionId: string): ProjectionDispatchDescriptor {
+    const descriptor = this.dispatchById.get(projectionId)
+    if (descriptor) return descriptor
+    throw new ProjectionValidationError(`[Sixb] Unknown projection '${projectionId}'.`)
+  }
+
+  resolveSource(projectionId: string): ResolvedProjection<SourceProjectionDefinition> {
+    const resolved = this.sourceById.get(projectionId)
+    if (!resolved) {
+      if (this.telemetryById.has(projectionId)) {
+        throw new ProjectionValidationError(
+          `[Sixb] Projection '${projectionId}' is telemetry-only and cannot replace source state.`
+        )
+      }
+      throw new ProjectionValidationError(`[Sixb] Unknown source projection '${projectionId}'.`)
+    }
+    return resolved
+  }
+
+  resolveTelemetry(projectionId: string): ResolvedProjection<TelemetryProjectionDefinition> {
+    const resolved = this.telemetryById.get(projectionId)
+    if (!resolved) {
+      if (this.sourceById.has(projectionId)) {
+        throw new ProjectionValidationError(
+          `[Sixb] Projection '${projectionId}' does not own a telemetry source.`
+        )
+      }
+      throw new ProjectionValidationError(`[Sixb] Unknown telemetry projection '${projectionId}'.`)
+    }
+    return resolved
+  }
+}
+
+function createDispatchDescriptor(
+  resolved: ResolvedProjection<ProjectionDefinition>,
+  ontologyRevision: string
+): ProjectionDispatchDescriptor {
+  const common = {
+    projectionId: resolved.projectionId,
+    datasetId: resolved.datasetId,
+    ontologyRevision,
+    projectionRevision: resolved.projectionRevision,
+    ownershipHash: resolved.ownershipHash,
+  }
+
+  switch (resolved.definition._tag) {
+    case "ObjectProjectionDefinition":
+      return deepFreeze({ ...common, projectionKind: "object", protocol: "replacement" })
+    case "LinkProjectionDefinition":
+      return deepFreeze({ ...common, projectionKind: "link", protocol: "replacement" })
+    case "TelemetryProjectionDefinition":
+      return deepFreeze({ ...common, projectionKind: "telemetry", protocol: "telemetry" })
+  }
+}
+
+function assertUniqueProjectionIds(projections: readonly ProjectionDefinition[]): void {
+  const ids = new Set<string>()
+  for (const projection of projections) {
+    if (ids.has(projection.id)) {
+      throw new ProjectionValidationError(`[Sixb] Duplicate projection id: ${projection.id}`)
+    }
+    ids.add(projection.id)
+  }
+}
+
+function createResolvedProjection<TDefinition extends ProjectionDefinition>(
+  validated: ValidatedProjectionRecord<TDefinition>
+): ResolvedProjection<TDefinition> {
+  const { definition, dataset, ownership } = validated
+  return deepFreeze({
+    projectionId: definition.id,
+    datasetId: definition.datasetId,
+    projectionRevision: computeProjectionRevision(definition, dataset),
+    ownershipHash: computeProjectionOwnershipHash(ownership),
+    ownership,
+    definition,
+  })
+}
+
+// Projection builders may attach fluent methods and callers may supply extra fields. Clone only the
+// frozen contract so resolved definitions stay serializable and cannot leak unsupported metadata.
+function cloneObjectProjectionDefinition(
+  projection: ObjectProjectionDefinition
+): ObjectProjectionDefinition {
+  return {
+    _tag: projection._tag,
+    id: projection.id,
+    objectTypeId: projection.objectTypeId,
+    datasetId: projection.datasetId,
+    properties: { ...projection.properties },
+    links: Object.fromEntries(
+      Object.entries(projection.links).map(([linkId, descriptor]) => [
+        linkId,
+        {
+          linkId: descriptor.linkId,
+          ...(descriptor.sourcePropertyId !== undefined
+            ? { sourcePropertyId: descriptor.sourcePropertyId }
+            : {}),
+          ...(descriptor.sourceField !== undefined ? { sourceField: descriptor.sourceField } : {}),
+          targetObjectTypeId: descriptor.targetObjectTypeId,
+        },
+      ])
+    ),
+  }
+}
+
+function cloneLinkProjectionDefinition(
+  projection: LinkProjectionDefinition
+): LinkProjectionDefinition {
+  return {
+    _tag: "LinkProjectionDefinition",
+    id: projection.id,
+    linkId: projection.linkId,
+    sourceObjectTypeId: projection.sourceObjectTypeId,
+    targetObjectTypeId: projection.targetObjectTypeId,
+    datasetId: projection.datasetId,
+    sourceField: projection.sourceField,
+    targetField: projection.targetField,
+  }
+}
+
+function cloneTelemetryProjectionDefinition(
+  projection: TelemetryProjectionDefinition
+): TelemetryProjectionDefinition {
+  return {
+    _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 } : {}),
+  }
+}
+
+function deepFreeze<T>(value: T): T {
+  if (value === null || typeof value !== "object" || Object.isFrozen(value)) return value
+  for (const child of Object.values(value as Record<string, unknown>)) {
+    deepFreeze(child)
+  }
+  return Object.freeze(value)
+}