@sixb/core 0.0.1

package/src/materialization/index.ts

@@ -0,0 +1,75 @@
+/**
+ * Provider-neutral ontology materialization contracts.
+ *
+ * @internal Repository packages only. Application orchestration belongs to `materializer`; storage
+ * adapters may depend on this module without depending on that application layer.
+ */
+
+export {
+  assertPinnedDatasetWatermark,
+  comparePinnedDatasetWatermarks,
+} from "./dataset-watermark"
+export type { MaterializationConflictKind } from "./errors"
+export {
+  isMaterializationConflictError,
+  MaterializationCancellationError,
+  MaterializationConflictError,
+  MaterializationObjectNotFoundError,
+  MaterializationValidationError,
+} from "./errors"
+export type { OntologyMaterializationEvent, OntologyMaterializationEventDraft } from "./events"
+export type {
+  BaseCommitResult,
+  EditCommitResult,
+  EffectiveChangeCounts,
+  EffectiveLinkChange,
+  EffectiveLinkSnapshot,
+  EffectiveObjectChange,
+  EffectiveObjectSnapshot,
+  ExpectedLinkRevision,
+  ExpectedLinkScopeRevision,
+  ExpectedObjectRevision,
+  LinkOverride,
+  MaterializationItemError,
+  ObjectOverride,
+  OntologyEditCommit,
+  OntologyEditOperation,
+  OntologyLinkRef,
+  OntologyMaterializationOrigin,
+  OntologyMaterializationPropertyChange,
+  OntologyMaterializationPropertyChangeMap,
+  OntologyObjectRef,
+  OntologyOperationOutcome,
+  PinnedDatasetVersion,
+  ProjectionCommitResult,
+  ProjectionEntityRef,
+  ProjectionExecution,
+  ProjectionMaterializationIdentity,
+  ProjectionProtocolIdentity,
+  ProjectionRunFinishInput,
+  ProjectionRunTerminalDecision,
+  ProjectionSourceAssertion,
+  ProjectionSourceEntry,
+  ProjectionSourceRef,
+  ProjectionSourceReplacement,
+  TelemetryAppend,
+  TelemetryCommitResult,
+  TelemetryPointWrite,
+  TelemetrySeriesRef,
+} from "./model"
+export {
+  canonicalIdentitySortKey,
+  compareLinkRefs,
+  compareObjectRefs,
+  linkRefKey,
+  linkRefSortKey,
+  linkScopeSortKey,
+  normalizeLinkRef,
+  normalizeObjectRef,
+  objectRefKey,
+  objectRefSortKey,
+  projectionEntityKey,
+  telemetryPointKey,
+  telemetryPointSortKey,
+  telemetrySeriesKey,
+} from "./refs"

package/src/materialization/model.ts

@@ -0,0 +1,394 @@
+import type { EventActor, EventOrigin } from "../events/envelope"
+import type { PropertyChange, PropertyChangeMap } from "../events/property-changes"
+import type { JsonValue } from "../json"
+import type { ProjectionProtocolIdentity } from "../projections/types"
+
+export type { ProjectionProtocolIdentity } from "../projections/types"
+
+export interface OntologyObjectRef {
+  readonly objectTypeId: string
+  readonly primaryId: string
+}
+
+export interface OntologyLinkRef {
+  readonly source: OntologyObjectRef
+  readonly linkId: string
+  readonly target: OntologyObjectRef
+}
+
+export interface ProjectionSourceRef {
+  readonly projectionId: string
+}
+
+export interface ProjectionExecution {
+  readonly projectionRunId: string
+  readonly executionToken: string
+}
+
+export interface PinnedDatasetVersion {
+  readonly datasetId: string
+  readonly versionId: string
+  /** Canonical UTC ISO timestamp from immutable version metadata. */
+  readonly createdAt: string
+}
+
+interface ProjectionMaterializationIdentityBase {
+  readonly projectionId: string
+  readonly datasetVersion: PinnedDatasetVersion
+  readonly ontologyRevision: string
+  readonly projectionRevision: string
+  readonly ownershipHash: string
+}
+
+/** Immutable semantic identity pinned for the lifetime of one logical projection run. */
+export type ProjectionMaterializationIdentity = ProjectionMaterializationIdentityBase &
+  ProjectionProtocolIdentity
+
+export type OntologyMaterializationOrigin = EventOrigin
+
+export type ExpectedObjectRevision =
+  | {
+      readonly ref: OntologyObjectRef
+      readonly exists: false
+    }
+  | {
+      readonly ref: OntologyObjectRef
+      readonly exists: true
+      readonly version: number
+      readonly lastCommitId: string
+    }
+
+export type ExpectedLinkRevision =
+  | {
+      readonly ref: OntologyLinkRef
+      readonly exists: false
+    }
+  | {
+      readonly ref: OntologyLinkRef
+      readonly exists: true
+      readonly lastCommitId: string
+    }
+
+export interface ExpectedLinkScopeRevision {
+  readonly source: OntologyObjectRef
+  readonly linkId: string
+  /** Hash of the complete canonical effective scope, including the empty scope. */
+  readonly fingerprint: string
+}
+
+export type OntologyEditOperation =
+  | {
+      readonly id: string
+      readonly kind: "object.create" | "object.upsert"
+      readonly ref: OntologyObjectRef
+      readonly properties: Readonly<Record<string, JsonValue>>
+    }
+  | {
+      readonly id: string
+      readonly kind: "object.patch"
+      readonly ref: OntologyObjectRef
+      readonly set: Readonly<Record<string, JsonValue>>
+      readonly unset: readonly string[]
+      readonly reset: readonly string[]
+    }
+  | {
+      readonly id: string
+      readonly kind: "object.delete" | "object.restore"
+      readonly ref: OntologyObjectRef
+    }
+  | {
+      readonly id: string
+      readonly kind: "link.upsert"
+      readonly ref: OntologyLinkRef
+      readonly properties?: Readonly<Record<string, JsonValue>>
+    }
+  | {
+      readonly id: string
+      readonly kind: "link.delete" | "link.reset"
+      readonly ref: OntologyLinkRef
+    }
+
+interface BaseOntologyEditCommit {
+  readonly actor?: EventActor
+  readonly operations: readonly OntologyEditOperation[]
+}
+
+export type OntologyEditCommit =
+  | (BaseOntologyEditCommit & {
+      readonly mode: "atomic"
+      readonly source:
+        | { readonly kind: "action"; readonly actionId: string; readonly runId: string }
+        | { readonly kind: "runtime"; readonly requestId: string }
+      readonly expectedObjects: readonly ExpectedObjectRevision[]
+      readonly expectedLinks: readonly ExpectedLinkRevision[]
+      readonly expectedLinkScopes: readonly ExpectedLinkScopeRevision[]
+    })
+  | (BaseOntologyEditCommit & {
+      readonly mode: "continue"
+      readonly source: { readonly kind: "runtime"; readonly requestId: string }
+      /**
+       * Operation ids that apply as one unit, listed in application order.
+       *
+       * Continue mode isolates failures per operation, which would let one caller item commit its
+       * earlier operations after a later one failed. Grouping restores the per-item promise: a
+       * failure inside a group rolls back that group's earlier operations and reports every id in
+       * it as failed. Ungrouped operations keep per-operation isolation.
+       */
+      readonly operationGroups?: readonly (readonly string[])[]
+    })
+
+export type ProjectionEntityRef =
+  | { readonly kind: "object"; readonly ref: OntologyObjectRef }
+  | { readonly kind: "link"; readonly ref: OntologyLinkRef }
+
+export type ProjectionSourceAssertion =
+  | {
+      readonly kind: "object"
+      readonly ref: OntologyObjectRef
+      readonly properties: Readonly<Record<string, JsonValue>>
+    }
+  | {
+      readonly kind: "link"
+      readonly ref: OntologyLinkRef
+      readonly properties?: Readonly<Record<string, JsonValue>>
+    }
+
+/** Complete ontology contribution of one logical projection row. */
+export interface ProjectionSourceEntry {
+  readonly root: ProjectionEntityRef
+  readonly assertions: readonly ProjectionSourceAssertion[]
+}
+
+export interface ProjectionSourceReplacement {
+  readonly source: ProjectionSourceRef
+  readonly datasetVersion: PinnedDatasetVersion
+  readonly execution: ProjectionExecution
+  readonly entries: AsyncIterable<ProjectionSourceEntry>
+  readonly signal?: AbortSignal
+}
+
+interface ProjectionRunFinishBase {
+  readonly source: ProjectionSourceRef
+  readonly datasetVersion: PinnedDatasetVersion
+  readonly execution: ProjectionExecution
+}
+
+export type ProjectionRunTerminalDecision =
+  | {
+      readonly protocol: "replacement"
+      readonly status: "succeeded"
+      readonly inputExhausted?: never
+    }
+  | {
+      readonly protocol: "telemetry"
+      readonly status: "succeeded"
+      /** Explicit proof that the worker observed EOF for the immutable input version. */
+      readonly inputExhausted: true
+    }
+  | {
+      readonly protocol: ProjectionProtocolIdentity["protocol"]
+      readonly status: "failed" | "cancelled"
+      readonly errorMessage?: string
+      readonly inputExhausted?: never
+    }
+
+/**
+ * Queue-agnostic terminal decision for one fenced projection execution.
+ *
+ * For telemetry, terminal success is also the fenced acknowledgement that the worker observed
+ * the pinned input's EOF.
+ */
+export type ProjectionRunFinishInput = ProjectionRunFinishBase & ProjectionRunTerminalDecision
+
+export interface TelemetrySeriesRef {
+  readonly object: OntologyObjectRef
+  readonly propertyId: string
+}
+
+export interface TelemetryPointWrite {
+  readonly series: TelemetrySeriesRef
+  readonly value: JsonValue
+  readonly unit?: string
+  /** Canonical UTC ISO observation timestamp. */
+  readonly at: string
+}
+
+export interface TelemetryAppend {
+  readonly source:
+    | { readonly kind: "runtime"; readonly requestId: string }
+    | {
+        readonly kind: "projection"
+        readonly projection: ProjectionSourceRef
+        readonly datasetVersion: PinnedDatasetVersion
+        readonly execution: ProjectionExecution
+        readonly batchOrdinal: number
+        /** Physical dataset rows consumed to produce this batch, including skipped rows. */
+        readonly sourceRowCount: number
+        /** Physical rows skipped because a required mapped value was blank. */
+        readonly sourceRowsSkipped: number
+        /** True when this batch consumed the final row of the immutable dataset version. */
+        readonly inputExhausted: boolean
+      }
+  readonly actor?: EventActor
+  readonly points: readonly TelemetryPointWrite[]
+}
+
+export interface MaterializationItemError {
+  readonly code: "validation"
+  readonly message: string
+}
+
+export interface EffectiveObjectSnapshot {
+  readonly ref: OntologyObjectRef
+  readonly properties: Readonly<Record<string, JsonValue>>
+  readonly version: number
+  readonly createdAt: string
+  readonly updatedAt: string
+  readonly lastCommitId: string
+}
+
+export interface EffectiveLinkSnapshot {
+  readonly ref: OntologyLinkRef
+  readonly properties?: Readonly<Record<string, JsonValue>>
+  readonly createdAt: string
+  readonly updatedAt: string
+  readonly lastCommitId: string
+}
+
+export type OntologyMaterializationPropertyChange = PropertyChange<JsonValue>
+export type OntologyMaterializationPropertyChangeMap = Readonly<PropertyChangeMap<JsonValue>>
+
+export type EffectiveObjectChange =
+  | {
+      readonly kind: "created"
+      readonly ref: OntologyObjectRef
+      readonly before: null
+      readonly after: EffectiveObjectSnapshot
+      readonly propertyChanges: OntologyMaterializationPropertyChangeMap
+    }
+  | {
+      readonly kind: "updated"
+      readonly ref: OntologyObjectRef
+      readonly before: EffectiveObjectSnapshot
+      readonly after: EffectiveObjectSnapshot
+      readonly propertyChanges: OntologyMaterializationPropertyChangeMap
+    }
+  | {
+      readonly kind: "deleted"
+      readonly ref: OntologyObjectRef
+      readonly before: EffectiveObjectSnapshot
+      readonly after: null
+      readonly propertyChanges: OntologyMaterializationPropertyChangeMap
+    }
+
+export type EffectiveLinkChange =
+  | {
+      readonly kind: "created"
+      readonly ref: OntologyLinkRef
+      readonly before: null
+      readonly after: EffectiveLinkSnapshot
+      readonly propertyChanges: OntologyMaterializationPropertyChangeMap
+    }
+  | {
+      readonly kind: "updated"
+      readonly ref: OntologyLinkRef
+      readonly before: EffectiveLinkSnapshot
+      readonly after: EffectiveLinkSnapshot
+      readonly propertyChanges: OntologyMaterializationPropertyChangeMap
+    }
+  | {
+      readonly kind: "deleted"
+      readonly ref: OntologyLinkRef
+      readonly before: EffectiveLinkSnapshot
+      readonly after: null
+      readonly propertyChanges: OntologyMaterializationPropertyChangeMap
+    }
+
+export interface EffectiveChangeCounts {
+  readonly objectsCreated: number
+  readonly objectsUpdated: number
+  readonly objectsDeleted: number
+  readonly objectsUnchanged: number
+  readonly linksCreated: number
+  readonly linksUpdated: number
+  readonly linksDeleted: number
+  readonly linksUnchanged: number
+}
+
+export type OntologyOperationOutcome =
+  | {
+      readonly id: string
+      readonly ok: true
+      /** Whether this operation changed durable authority; effective changes are separate. */
+      readonly authority: "changed" | "unchanged"
+      /** Present when a runtime object call needs its resulting effective object. */
+      readonly object?: EffectiveObjectSnapshot
+    }
+  | {
+      readonly id: string
+      readonly ok: false
+      /** Only produced by runtime `continue` mode; atomic semantic failures throw. */
+      readonly error: MaterializationItemError
+    }
+
+export interface BaseCommitResult {
+  readonly commitId: string
+  readonly created: boolean
+  readonly eventCount: number
+  /** Canonical UTC ISO commit time, fixed when the commit was assigned its identity. */
+  readonly committedAt: string
+}
+
+export interface EditCommitResult extends BaseCommitResult {
+  readonly kind: "edit"
+  readonly outcomes: readonly OntologyOperationOutcome[]
+  readonly changes: {
+    readonly objects: readonly EffectiveObjectChange[]
+    readonly links: readonly EffectiveLinkChange[]
+  }
+}
+
+export interface ProjectionCommitResult extends BaseCommitResult {
+  readonly kind: "projection"
+  readonly counts: EffectiveChangeCounts
+}
+
+export interface TelemetryCommitResult extends BaseCommitResult {
+  readonly kind: "telemetry"
+  readonly pointsCreated: number
+  readonly pointsUpdated: number
+  readonly pointsUnchanged: number
+  readonly latestObjectsChanged: number
+}
+
+export interface OntologyMaterializer {
+  readonly edits: {
+    commit(input: OntologyEditCommit): Promise<EditCommitResult>
+  }
+  readonly projections: {
+    replace(input: ProjectionSourceReplacement): Promise<ProjectionCommitResult>
+    finishRun(input: ProjectionRunFinishInput): Promise<void>
+  }
+  readonly telemetry: {
+    append(input: TelemetryAppend): Promise<TelemetryCommitResult>
+  }
+}
+
+export type ObjectOverride =
+  | {
+      readonly kind: "create"
+      readonly properties: Readonly<Record<string, JsonValue>>
+    }
+  | {
+      readonly kind: "patch"
+      readonly set: Readonly<Record<string, JsonValue>>
+      readonly unset: readonly string[]
+    }
+  | { readonly kind: "delete" }
+
+export type LinkOverride =
+  | {
+      readonly kind: "upsert"
+      readonly properties?: Readonly<Record<string, JsonValue>>
+    }
+  | { readonly kind: "delete" }

package/src/materialization/refs.ts

@@ -0,0 +1,134 @@
+import { compareStrings } from "../json"
+import { MaterializationValidationError } from "./errors"
+import type {
+  OntologyLinkRef,
+  OntologyObjectRef,
+  ProjectionEntityRef,
+  TelemetrySeriesRef,
+} from "./model"
+
+const textEncoder = new TextEncoder()
+
+function assertIdentifier(value: string, label: string): void {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new MaterializationValidationError(`${label} must be a nonblank string.`)
+  }
+}
+
+export function normalizeObjectRef(ref: OntologyObjectRef): OntologyObjectRef {
+  assertIdentifier(ref.objectTypeId, "Object type id")
+  assertIdentifier(ref.primaryId, "Object primary id")
+  return Object.freeze({ objectTypeId: ref.objectTypeId, primaryId: ref.primaryId })
+}
+
+export function normalizeLinkRef(ref: OntologyLinkRef): OntologyLinkRef {
+  assertIdentifier(ref.linkId, "Link id")
+  return Object.freeze({
+    source: normalizeObjectRef(ref.source),
+    linkId: ref.linkId,
+    target: normalizeObjectRef(ref.target),
+  })
+}
+
+export function objectRefKey(ref: OntologyObjectRef): string {
+  return JSON.stringify([ref.objectTypeId, ref.primaryId])
+}
+
+export function linkRefKey(ref: OntologyLinkRef): string {
+  return JSON.stringify([
+    ref.source.objectTypeId,
+    ref.source.primaryId,
+    ref.linkId,
+    ref.target.objectTypeId,
+    ref.target.primaryId,
+  ])
+}
+
+export function projectionEntityKey(entity: ProjectionEntityRef): string {
+  return entity.kind === "object"
+    ? JSON.stringify(["object", entity.ref.objectTypeId, entity.ref.primaryId])
+    : JSON.stringify([
+        "link",
+        entity.ref.source.objectTypeId,
+        entity.ref.source.primaryId,
+        entity.ref.linkId,
+        entity.ref.target.objectTypeId,
+        entity.ref.target.primaryId,
+      ])
+}
+
+export function linkOwnershipKey(sourceObjectTypeId: string, linkId: string): string {
+  return JSON.stringify([sourceObjectTypeId, linkId])
+}
+
+export function telemetryOwnershipKey(objectTypeId: string, propertyId: string): string {
+  return JSON.stringify([objectTypeId, propertyId])
+}
+
+export function telemetrySeriesKey(series: TelemetrySeriesRef): string {
+  return JSON.stringify([series.object.objectTypeId, series.object.primaryId, series.propertyId])
+}
+
+export function telemetryPointKey(series: TelemetrySeriesRef, at: string): string {
+  return JSON.stringify([
+    series.object.objectTypeId,
+    series.object.primaryId,
+    series.propertyId,
+    at,
+  ])
+}
+
+/**
+ * A provider-collation-independent byte key. Providers compare this lowercase hexadecimal value
+ * verbatim; all ontology identity structure is supplied by core in the canonical JSON tuple.
+ */
+export function canonicalIdentitySortKey(parts: readonly string[]): string {
+  let result = ""
+  for (const byte of textEncoder.encode(JSON.stringify(parts))) {
+    result += byte.toString(16).padStart(2, "0")
+  }
+  return result
+}
+
+export function utf8JsonByteLength(value: unknown): number {
+  return textEncoder.encode(JSON.stringify(value)).byteLength
+}
+
+export function objectRefSortKey(ref: OntologyObjectRef): string {
+  return canonicalIdentitySortKey([ref.objectTypeId, ref.primaryId])
+}
+
+export function linkRefSortKey(ref: OntologyLinkRef): string {
+  return canonicalIdentitySortKey([
+    ref.source.objectTypeId,
+    ref.source.primaryId,
+    ref.linkId,
+    ref.target.objectTypeId,
+    ref.target.primaryId,
+  ])
+}
+
+export function linkScopeKey(source: OntologyObjectRef, linkId: string): string {
+  return JSON.stringify([source.objectTypeId, source.primaryId, linkId])
+}
+
+export function linkScopeSortKey(source: OntologyObjectRef, linkId: string): string {
+  return canonicalIdentitySortKey([source.objectTypeId, source.primaryId, linkId])
+}
+
+export function telemetryPointSortKey(series: TelemetrySeriesRef, at: string): string {
+  return canonicalIdentitySortKey([
+    series.object.objectTypeId,
+    series.object.primaryId,
+    series.propertyId,
+    at,
+  ])
+}
+
+export function compareObjectRefs(left: OntologyObjectRef, right: OntologyObjectRef): number {
+  return compareStrings(objectRefSortKey(left), objectRefSortKey(right))
+}
+
+export function compareLinkRefs(left: OntologyLinkRef, right: OntologyLinkRef): number {
+  return compareStrings(linkRefSortKey(left), linkRefSortKey(right))
+}