@sixb/core 0.0.1

package/src/materializer/edits/operations.ts

@@ -0,0 +1,298 @@
+import { MaterializationValidationError } from "../../materialization/errors"
+import type { OntologyEditOperation, OntologyOperationOutcome } from "../../materialization/model"
+import { linkRefKey, objectRefKey } from "../../materialization/refs"
+import type { MaterializationLinkScopeState } from "../../storage/ontology"
+import type { MaterializerContext } from "../context"
+import { diffEffectiveObject } from "../effective/diff"
+import {
+  validateEffectiveObject,
+  validateLinkAuthorityProperties,
+  validateLinkRef,
+  validateObjectAuthorityProperties,
+  validateObjectPatchPropertyIds,
+  validateObjectRef,
+} from "../effective/validate"
+import type { TimedCommitIdentity } from "../shared/identity"
+import { applyLinkEdit, applyObjectEdit } from "./apply"
+import { linkCardinality } from "./read-set"
+import {
+  resolveLink,
+  resolveObject,
+  validateWorkingCardinality,
+  type WorkingLink,
+  type WorkingObject,
+} from "./working-state"
+
+type ObjectOperation = Extract<OntologyEditOperation, { readonly kind: `object.${string}` }>
+type LinkOperation = Extract<OntologyEditOperation, { readonly kind: `link.${string}` }>
+
+/**
+ * Transaction-local edit working set.
+ *
+ * Loaded snapshots remain pinned to the commit start while each successful operation updates the
+ * mutable override. Operation N+1 can therefore observe operation N before anything is durable.
+ */
+export interface EditWorkingState {
+  readonly objects: Map<string, WorkingObject>
+  readonly links: Map<string, WorkingLink>
+  readonly scopeSnapshots: Map<string, MaterializationLinkScopeState>
+}
+
+/**
+ * Undo record for one override the current operation group replaced.
+ *
+ * Only the mutable override moves; loaded snapshots stay pinned for the whole commit, so restoring
+ * the overrides in reverse returns the working set to its pre-group state. Incident links loaded
+ * along the way are a read cache and are deliberately left in place.
+ */
+interface EditUndoEntry {
+  readonly restore: () => void
+}
+
+/** Collects undo records while a grouped item applies. */
+export type EditUndoJournal = EditUndoEntry[]
+
+export function undoEditJournal(journal: EditUndoJournal): void {
+  for (let index = journal.length - 1; index >= 0; index -= 1) {
+    journal[index]?.restore()
+  }
+}
+
+export function applyEditOperation(
+  context: MaterializerContext,
+  state: EditWorkingState,
+  operation: OntologyEditOperation,
+  identity: TimedCommitIdentity,
+  journal?: EditUndoJournal
+): OntologyOperationOutcome {
+  validateOperationRef(context, operation)
+  if (isObjectOperation(operation)) {
+    return applyObjectOperation(context, state, operation, identity, journal)
+  }
+  return applyLinkOperation(
+    context,
+    state,
+    operation,
+    linkCardinality(context.ontology, operation.ref),
+    journal
+  )
+}
+
+function validateOperationRef(
+  context: Pick<MaterializerContext, "ontology">,
+  operation: OntologyEditOperation
+): void {
+  if (isObjectOperation(operation)) {
+    validateObjectRef(context.ontology, operation.ref)
+    return
+  }
+  validateLinkRef(context.ontology, operation.ref)
+}
+
+function applyObjectOperation(
+  context: MaterializerContext,
+  state: EditWorkingState,
+  operation: ObjectOperation,
+  identity: TimedCommitIdentity,
+  journal?: EditUndoJournal
+): OntologyOperationOutcome {
+  const working = requireWorkingObject(state, operation)
+  const normalized = validateObjectOperation(context, operation)
+  const currentEffective = resolveObject(context.ontology, working)
+  const transition = applyObjectEdit({
+    operation,
+    sourceProperties: working.source?.assertion.properties ?? null,
+    authority: working.override,
+    effectiveExists: currentEffective !== null,
+    ...normalized,
+  })
+
+  applyObjectTransition(context, state, working, transition.next, journal)
+
+  return objectOperationOutcome(operation, working, transition.changed, context, identity)
+}
+
+function requireWorkingObject(state: EditWorkingState, operation: ObjectOperation): WorkingObject {
+  const working = state.objects.get(objectRefKey(operation.ref))
+  if (!working) throw new MaterializationValidationError("Object state was not loaded.")
+  return working
+}
+
+function validateObjectOperation(
+  context: Pick<MaterializerContext, "ontology">,
+  operation: ObjectOperation
+): {
+  readonly normalizedProperties?: ReturnType<typeof validateObjectAuthorityProperties>
+  readonly normalizedSet?: ReturnType<typeof validateObjectAuthorityProperties>
+} {
+  switch (operation.kind) {
+    case "object.create":
+    case "object.upsert":
+      return {
+        normalizedProperties: validateObjectAuthorityProperties(
+          context.ontology,
+          operation.ref,
+          operation.properties
+        ),
+      }
+    case "object.patch":
+      validateObjectPatchPropertyIds(context.ontology, operation.ref, operation.unset, "unset")
+      validateObjectPatchPropertyIds(context.ontology, operation.ref, operation.reset, "reset")
+      return {
+        normalizedSet: validateObjectAuthorityProperties(
+          context.ontology,
+          operation.ref,
+          operation.set
+        ),
+      }
+    case "object.delete":
+    case "object.restore":
+      return {}
+  }
+}
+
+function applyObjectTransition(
+  context: MaterializerContext,
+  state: EditWorkingState,
+  working: WorkingObject,
+  next: WorkingObject["override"],
+  journal?: EditUndoJournal
+): void {
+  const previous = working.override
+  working.override = next
+  try {
+    const resolved = resolveObject(context.ontology, working)
+    if (resolved) validateEffectiveObject(context.ontology, resolved.ref, resolved.properties)
+    validateWorkingCardinality(context.ontology, state.objects, state.links, state.scopeSnapshots)
+  } catch (error) {
+    working.override = previous
+    throw error
+  }
+  journal?.push({
+    restore: () => {
+      working.override = previous
+    },
+  })
+}
+
+function objectOperationOutcome(
+  operation: ObjectOperation,
+  working: WorkingObject,
+  changed: boolean,
+  context: Pick<MaterializerContext, "ontology">,
+  identity: TimedCommitIdentity
+): OntologyOperationOutcome {
+  const outcome: OntologyOperationOutcome = {
+    id: operation.id,
+    ok: true,
+    authority: authorityOutcome(changed),
+  }
+  const resolved = resolveObject(context.ontology, working)
+  if (!resolved) return outcome
+  const change = diffEffectiveObject({
+    before: working.before,
+    resolved,
+    commitId: identity.commitId,
+    committedAt: identity.committedAt,
+  })
+  const object = change?.after ?? working.before
+  if (!object) {
+    throw new MaterializationValidationError("Effective object outcome could not be resolved.")
+  }
+  return { ...outcome, object }
+}
+
+function applyLinkOperation(
+  context: MaterializerContext,
+  state: EditWorkingState,
+  operation: LinkOperation,
+  cardinality: "one" | "many" | undefined,
+  journal?: EditUndoJournal
+): OntologyOperationOutcome {
+  const working = requireWorkingLink(state, operation)
+  validateLinkEndpoints(context, state, operation)
+  const normalizedProperties = validateLinkOperation(context, operation)
+  const currentEffective = resolveLink(context.ontology, working, state.objects)
+  const transitionInput = {
+    operation,
+    hasSource: working.source !== null,
+    authority: working.override,
+    effectiveExists: currentEffective !== null,
+  }
+  const transition = applyLinkEdit({ ...transitionInput, normalizedProperties })
+  applyLinkTransition(context, state, working, transition.next, cardinality, journal)
+  return { id: operation.id, ok: true, authority: authorityOutcome(transition.changed) }
+}
+
+function requireWorkingLink(state: EditWorkingState, operation: LinkOperation): WorkingLink {
+  const working = state.links.get(linkRefKey(operation.ref))
+  if (!working) throw new MaterializationValidationError("Link state was not loaded.")
+  return working
+}
+
+function validateLinkEndpoints(
+  context: Pick<MaterializerContext, "ontology">,
+  state: EditWorkingState,
+  operation: LinkOperation
+): void {
+  if (operation.kind !== "link.upsert") return
+  const source = state.objects.get(objectRefKey(operation.ref.source))
+  const target = state.objects.get(objectRefKey(operation.ref.target))
+  const sourceExists = source && resolveObject(context.ontology, source)
+  const targetExists = target && resolveObject(context.ontology, target)
+  if (sourceExists && targetExists) return
+  throw new MaterializationValidationError("Link upsert requires both endpoints to be effective.")
+}
+
+function validateLinkOperation(
+  context: Pick<MaterializerContext, "ontology">,
+  operation: LinkOperation
+): ReturnType<typeof validateLinkAuthorityProperties> | undefined {
+  if (operation.kind !== "link.upsert") return undefined
+  return validateLinkAuthorityProperties(context.ontology, operation.ref, operation.properties)
+}
+
+function applyLinkTransition(
+  context: Pick<MaterializerContext, "ontology">,
+  state: EditWorkingState,
+  working: WorkingLink,
+  next: WorkingLink["override"],
+  cardinality: "one" | "many" | undefined,
+  journal?: EditUndoJournal
+): void {
+  const previous = working.override
+  working.override = next
+  try {
+    if (cardinality === "one") {
+      validateWorkingCardinality(context.ontology, state.objects, state.links, state.scopeSnapshots)
+    }
+  } catch (error) {
+    working.override = previous
+    throw error
+  }
+  journal?.push({
+    restore: () => {
+      working.override = previous
+    },
+  })
+}
+
+function authorityOutcome(changed: boolean): "changed" | "unchanged" {
+  if (changed) return "changed"
+  return "unchanged"
+}
+
+function isObjectOperation(operation: OntologyEditOperation): operation is ObjectOperation {
+  switch (operation.kind) {
+    case "object.create":
+    case "object.upsert":
+    case "object.patch":
+    case "object.delete":
+    case "object.restore":
+      return true
+    case "link.upsert":
+    case "link.delete":
+    case "link.reset":
+      return false
+  }
+}

package/src/materializer/edits/plan.ts

@@ -0,0 +1,192 @@
+import type { EventActor } from "../../events/envelope"
+import type {
+  EffectiveLinkChange,
+  EffectiveObjectChange,
+  OntologyMaterializationOrigin,
+} from "../../materialization/model"
+import {
+  compareLinkRefs,
+  compareObjectRefs,
+  linkRefKey,
+  linkRefSortKey,
+  objectRefKey,
+  objectRefSortKey,
+} from "../../materialization/refs"
+import type {
+  MaterializationPlanWorkItem,
+  MaterializationSession,
+  MaterializationWorkRecord,
+  OntologyMaterializationStorage,
+} from "../../storage/ontology"
+import type { MaterializerContext } from "../context"
+import {
+  buildLinkMaterializationEventDraft,
+  buildObjectMaterializationEventDraft,
+} from "../effective/build-events"
+import { diffEffectiveLink, diffEffectiveObject } from "../effective/diff"
+import { validateEffectiveObject } from "../effective/validate"
+import { stageWorkBounded } from "../execution/work-executor"
+import {
+  appendLinkEffectivePlan,
+  appendLinkOverridePlan,
+  appendObjectEffectivePlan,
+  appendObjectOverridePlan,
+  classificationWork,
+  eventWork,
+  planWork,
+} from "../execution/work-records"
+import type { TimedCommitIdentity } from "../shared/identity"
+import type { EditWorkingState } from "./operations"
+import {
+  resolveLink,
+  resolveObject,
+  validateWorkingCardinality,
+  type WorkingLink,
+  type WorkingObject,
+} from "./working-state"
+
+export interface EditPlanChanges {
+  readonly objects: readonly EffectiveObjectChange[]
+  readonly links: readonly EffectiveLinkChange[]
+}
+
+interface EditPlanContext {
+  readonly identity: TimedCommitIdentity
+  readonly origin: OntologyMaterializationOrigin
+  readonly actor?: EventActor
+}
+
+export async function stageEditPlan(
+  context: MaterializerContext,
+  storage: OntologyMaterializationStorage,
+  session: MaterializationSession,
+  state: EditWorkingState,
+  planContext: EditPlanContext
+): Promise<EditPlanChanges> {
+  validateWorkingCardinality(context.ontology, state.objects, state.links, state.scopeSnapshots)
+
+  const objectChanges: EffectiveObjectChange[] = []
+  for (const working of sortedObjects(state.objects)) {
+    const change = await stageObjectPlan(context, storage, session, working, planContext)
+    if (change) objectChanges.push(change)
+  }
+
+  const linkChanges: EffectiveLinkChange[] = []
+  for (const working of sortedLinks(state.links)) {
+    const change = await stageLinkPlan(
+      context,
+      storage,
+      session,
+      state.objects,
+      working,
+      planContext
+    )
+    if (change) linkChanges.push(change)
+  }
+
+  return { objects: objectChanges, links: linkChanges }
+}
+
+async function stageObjectPlan(
+  context: MaterializerContext,
+  storage: OntologyMaterializationStorage,
+  session: MaterializationSession,
+  working: WorkingObject,
+  planContext: EditPlanContext
+): Promise<EffectiveObjectChange | null> {
+  const items: MaterializationPlanWorkItem[] = []
+  appendObjectOverridePlan(items, working, planContext.identity)
+
+  const resolved = resolveObject(context.ontology, working)
+  if (resolved) validateEffectiveObject(context.ontology, resolved.ref, resolved.properties)
+  const change = diffEffectiveObject({
+    before: working.before,
+    resolved,
+    commitId: planContext.identity.commitId,
+    committedAt: planContext.identity.committedAt,
+  })
+  if (change) appendObjectEffectivePlan(items, change)
+
+  const sortKey = objectRefSortKey(working.ref)
+  const work: MaterializationWorkRecord[] = [
+    classificationWork("object", objectRefKey(working.ref), sortKey),
+    ...items.map((item) => planWork(item, sortKey)),
+  ]
+  if (change) {
+    work.push(eventWork(buildObjectEvent(context, planContext, change)))
+  }
+  await stageWorkBounded(context, storage, session, work)
+  return change
+}
+
+async function stageLinkPlan(
+  context: MaterializerContext,
+  storage: OntologyMaterializationStorage,
+  session: MaterializationSession,
+  objects: EditWorkingState["objects"],
+  working: WorkingLink,
+  planContext: EditPlanContext
+): Promise<EffectiveLinkChange | null> {
+  const items: MaterializationPlanWorkItem[] = []
+  appendLinkOverridePlan(items, working, planContext.identity)
+
+  const resolved = resolveLink(context.ontology, working, objects)
+  const change = diffEffectiveLink({
+    before: working.before,
+    resolved,
+    commitId: planContext.identity.commitId,
+    committedAt: planContext.identity.committedAt,
+  })
+  if (change) appendLinkEffectivePlan(items, change)
+
+  const sortKey = linkRefSortKey(working.ref)
+  const work: MaterializationWorkRecord[] = [
+    classificationWork("link", linkRefKey(working.ref), sortKey),
+    ...items.map((item) => planWork(item, sortKey)),
+  ]
+  if (change) {
+    work.push(eventWork(buildLinkEvent(context, planContext, change)))
+  }
+  await stageWorkBounded(context, storage, session, work)
+  return change
+}
+
+function buildObjectEvent(
+  context: Pick<MaterializerContext, "projectId">,
+  planContext: EditPlanContext,
+  change: EffectiveObjectChange
+) {
+  const eventContext = materializationEventContext(context, planContext)
+  return buildObjectMaterializationEventDraft({ ...eventContext, change })
+}
+
+function buildLinkEvent(
+  context: Pick<MaterializerContext, "projectId">,
+  planContext: EditPlanContext,
+  change: EffectiveLinkChange
+) {
+  const eventContext = materializationEventContext(context, planContext)
+  return buildLinkMaterializationEventDraft({ ...eventContext, change })
+}
+
+function materializationEventContext(
+  context: Pick<MaterializerContext, "projectId">,
+  planContext: EditPlanContext
+) {
+  const base = {
+    projectId: context.projectId,
+    commitId: planContext.identity.commitId,
+    committedAt: planContext.identity.committedAt,
+    origin: planContext.origin,
+  }
+  if (planContext.actor === undefined) return base
+  return { ...base, actor: planContext.actor }
+}
+
+function sortedObjects(objects: EditWorkingState["objects"]): WorkingObject[] {
+  return [...objects.values()].sort((left, right) => compareObjectRefs(left.ref, right.ref))
+}
+
+function sortedLinks(links: EditWorkingState["links"]): WorkingLink[] {
+  return [...links.values()].sort((left, right) => compareLinkRefs(left.ref, right.ref))
+}

package/src/materializer/edits/read-set.ts

@@ -0,0 +1,79 @@
+import type {
+  OntologyEditOperation,
+  OntologyLinkRef,
+  OntologyObjectRef,
+} from "../../materialization/model"
+import {
+  compareLinkRefs,
+  compareObjectRefs,
+  linkRefKey,
+  linkScopeKey,
+  objectRefKey,
+} from "../../materialization/refs"
+import type { OntologyRegistry } from "../../ontology"
+import type { MaterializationStateRequestChunk } from "../../storage/ontology"
+
+/** Builds the complete state read set required by an ordered edit commit. */
+export function buildEditReadSet(
+  ontology: OntologyRegistry,
+  operations: readonly OntologyEditOperation[]
+): MaterializationStateRequestChunk {
+  const objects = new Map<string, OntologyObjectRef>()
+  const links = new Map<string, OntologyLinkRef>()
+  const scopes = new Map<string, { readonly source: OntologyObjectRef; readonly linkId: string }>()
+  const incidentObjects = new Map<string, OntologyObjectRef>()
+
+  for (const operation of operations) {
+    if (isObjectOperation(operation)) {
+      if (!ontology.getObjectTypeById(operation.ref.objectTypeId)) continue
+      objects.set(objectRefKey(operation.ref), operation.ref)
+      if (operation.kind !== "object.patch") {
+        incidentObjects.set(objectRefKey(operation.ref), operation.ref)
+      }
+      continue
+    }
+
+    if (!isKnownLinkRef(ontology, operation.ref)) continue
+    links.set(linkRefKey(operation.ref), operation.ref)
+    objects.set(objectRefKey(operation.ref.source), operation.ref.source)
+    objects.set(objectRefKey(operation.ref.target), operation.ref.target)
+    if (linkCardinality(ontology, operation.ref) === "one") {
+      const scope = { source: operation.ref.source, linkId: operation.ref.linkId }
+      scopes.set(linkScopeKey(scope.source, scope.linkId), scope)
+    }
+  }
+
+  return {
+    objects: [...objects.values()].sort(compareObjectRefs),
+    links: [...links.values()].sort(compareLinkRefs),
+    linkScopes: [...scopes.values()].sort((left, right) =>
+      linkScopeKey(left.source, left.linkId).localeCompare(linkScopeKey(right.source, right.linkId))
+    ),
+    incidentObjects: [...incidentObjects.values()].sort(compareObjectRefs),
+    points: [],
+  }
+}
+
+export function isKnownLinkRef(ontology: OntologyRegistry, ref: OntologyLinkRef): boolean {
+  const sourceType = ontology.getObjectTypeById(ref.source.objectTypeId)
+  if (!sourceType || !ontology.getObjectTypeById(ref.target.objectTypeId)) return false
+  const link = sourceType.links.find((candidate) => candidate.id === ref.linkId)
+  return Boolean(
+    link && ontology.isValidLinkTarget(link.targetObjectTypeId, ref.target.objectTypeId)
+  )
+}
+
+export function linkCardinality(ontology: OntologyRegistry, ref: OntologyLinkRef): "one" | "many" {
+  // Validation still belongs to the individual operation so `continue` mode can report an
+  // invalid reference without aborting the whole preload. Unknown references need no scope read.
+  const definition = ontology
+    .getObjectTypeById(ref.source.objectTypeId)
+    ?.links.find((candidate) => candidate.id === ref.linkId)
+  return definition?.cardinality ?? "many"
+}
+
+function isObjectOperation(
+  operation: OntologyEditOperation
+): operation is Extract<OntologyEditOperation, { readonly kind: `object.${string}` }> {
+  return operation.kind.startsWith("object.")
+}