@sixb/core 0.0.1

package/src/materializer/README.md

@@ -0,0 +1,130 @@
+# Ontology Materializer
+
+The Materializer turns source assertions, managed edits, and telemetry points into one effective
+Ontology state. It owns semantic planning and commit orchestration; storage providers own durable
+state and atomic application.
+
+## Ingresses
+
+```text
+projection replacement  -> projections.replace
+Action edits            -> edits.commit  (mode: "atomic",   origin: action)
+runtime object/link     -> edits.commit  (mode: "atomic" | "continue", origin: runtime)
+runtime telemetry       -> telemetry.append (origin: telemetry/runtime)
+```
+
+`Sixb` constructs one Materializer and threads it through its internal runtime context, so the typed
+`objects(...)` SDK, the dynamic `Sixb` methods, and the Action worker all commit through the same
+engine. Runtime single calls are atomic; runtime batches use `continue` mode and map per-item
+outcomes back to caller positions. No ingress appends domain events or writes object, link, or
+timeseries providers directly.
+
+Committed facts are published from the transactional outbox after the commit resolves.
+`OntologyOutboxDispatcher` owns that protocol: ingresses call `notify()` for prompt, non-blocking
+in-process delivery, and a process may call `start()` to host the durable poll loop. Publication is
+best effort — delivery may lag, but a committed fact is never lost.
+
+## Common commit pipeline
+
+```text
+normalize + validate intent
+  -> derive deterministic identity
+  -> verify execution when run-backed and check replay
+  -> begin serializable materialization session
+  -> resolve effective state
+  -> diff against committed state
+  -> stage deterministic work
+  -> apply work in dependency order
+  -> write outbox events with stable commit ordinals
+  -> finalize ontology commit atomically
+  -> advance a run resume checkpoint when required
+```
+
+`staged work` is a transaction-local execution plan. It is not a source materialization and is
+never queried as Ontology state.
+
+## Durable ownership
+
+```text
+run storage       -> execution ownership, lifecycle, progress, and resume checkpoints
+ontology storage  -> sources, effective state, telemetry, commits, and outbox
+Materializer      -> semantic planning and cross-store transaction orchestration
+```
+
+Ontology commit `origin` is the canonical correlation to an Action or projection run. Run records
+do not duplicate ontology commit ids or semantic commit history. Replacement projections need no
+resume checkpoint; projection telemetry stores only its next batch/row checkpoint on the run.
+
+Logical origins are unique in the ontology ledger: one commit per Action run, one per replacement
+run, and one per telemetry run/batch ordinal. Exact origin lookup is used for correctness; commit
+listing is reserved for history and observability.
+
+## Projection replacement
+
+```text
+dataset entries
+  -> staging source candidate
+  -> ready source candidate
+  -> compare candidate + overrides + telemetry with effective state
+  -> plan and apply changes
+  -> atomically activate candidate and finalize commit
+```
+
+Source ingress is sealed before commit time is assigned. A retry reuses the ready candidate and
+the same semantic commit identity. Activation and ontology commit finalization are atomic; the
+projection run stores no separate commit pointer.
+
+Projection runs finish only through `projections.finishRun(...)`. Its serializable transaction reads
+the authoritative ontology commit before replacement success, rejects failure after commit, and
+then applies the fenced run transition.
+
+## Managed edits and Actions
+
+```text
+ordered edit operations
+  -> transaction-local EditWorkingState
+  -> update object/link overrides
+  -> validate effective objects, endpoints, and cardinality
+  -> diff final working state against commit-start state
+  -> plan and finalize one commit
+```
+
+`EditWorkingState` is not durable. Its original snapshots remain pinned to the commit start, while
+its mutable overrides let operation N+1 observe operation N. In `continue` mode, a rejected
+operation rolls back only its working override; provider and infrastructure failures abort the
+whole transaction.
+
+Action-backed edits verify the matching running Action before work and again inside the commit
+transaction. Their semantic result lives only in the ontology commit, correlated by Action origin;
+the Action run is not a second commit ledger.
+
+## Telemetry append
+
+```text
+canonical telemetry points grouped by object
+  -> compare and plan bounded point chunks
+  -> update latest values in the object working state
+  -> resolve and diff the effective object once
+  -> plan and finalize one batch commit
+```
+
+Projection telemetry additionally verifies the durable projection execution and advances its
+resume checkpoint in the same transaction as ontology commit finalization. The ontology commits
+are the authoritative batch ledger. Physical source-row counts, including skipped rows, remain
+distinct from canonical point counts.
+
+Telemetry success requires an exhausted checkpoint. A truly empty immutable input is completed
+explicitly without manufacturing an ontology batch commit; the empty checkpoint transition and run
+finish still commit atomically.
+
+## Module boundaries
+
+- `edits/`, `projections/`, `telemetry/`: use-case-specific orchestration and planning.
+- `effective/`: pure resolution, validation, diff, and event construction.
+- `execution/`: storage-neutral plan execution, replay, retry, and run correlation.
+- `shared/`: normalization, identity, batching, and chunking primitives.
+- `storage/ontology/`: durable ontology commit, source, materialization, and outbox contracts.
+
+Keep use-case entrypoints explicit. Share mechanics only after they have identical semantics; do
+not hide projection candidate lifecycle, edit continuation, or telemetry batching behind a generic
+workflow engine.

package/src/materializer/context.ts

@@ -0,0 +1,75 @@
+import { MaterializationValidationError } from "../materialization/errors"
+import type { OntologyRegistry } from "../ontology"
+import type { ProjectionRegistry } from "../projections/registry"
+import { computeOntologyRevision } from "../projections/revision"
+import type { Storage } from "../storage"
+import { type MaterializationBatching, resolveMaterializationBatching } from "./shared/batching"
+import { createProjectionMaterializationId } from "./shared/identity"
+
+export type MaterializerStorage = Storage
+
+export interface OntologyMaterializerDependencies {
+  readonly batching?: Partial<MaterializationBatching>
+  readonly clock?: () => Date
+  readonly materializationId?: () => string
+  readonly maxSerializationRetries?: number
+  readonly onSerializationRetry?: (attempt: number, error: unknown) => void
+  /** @internal Bounded-memory instrumentation for core semantic buffers. */
+  readonly observeCoreBuffer?: (boundary: string, rows: number) => void
+}
+
+export interface MaterializerContext {
+  readonly projectId: string
+  readonly ontology: OntologyRegistry
+  readonly projectionRegistry: ProjectionRegistry
+  readonly storage: MaterializerStorage
+  readonly batching: MaterializationBatching
+  readonly clock: () => Date
+  readonly materializationId: () => string
+  readonly maxSerializationRetries: number
+  readonly onSerializationRetry?: (attempt: number, error: unknown) => void
+  readonly observeCoreBuffer?: (boundary: string, rows: number) => void
+}
+
+export function createMaterializerContext(input: {
+  readonly projectId: string
+  readonly ontology: OntologyRegistry
+  readonly projections: ProjectionRegistry
+  readonly storage: MaterializerStorage
+  readonly dependencies?: OntologyMaterializerDependencies
+}): MaterializerContext {
+  if (input.projectId.trim().length === 0) {
+    throw new MaterializationValidationError("Materializer project id must be nonblank.")
+  }
+  if (!input.storage?.ontology) {
+    throw new MaterializationValidationError("Storage does not provide ontology capabilities.")
+  }
+  if (computeOntologyRevision(input.ontology) !== input.projections.ontologyRevision) {
+    throw new MaterializationValidationError(
+      "Materializer Ontology does not match the Ontology pinned by its projection registry."
+    )
+  }
+  const dependencies = input.dependencies ?? {}
+  const maxSerializationRetries = dependencies.maxSerializationRetries ?? 2
+  if (!Number.isSafeInteger(maxSerializationRetries) || maxSerializationRetries < 0) {
+    throw new MaterializationValidationError(
+      "Materializer serialization retry count must be a nonnegative safe integer."
+    )
+  }
+  return {
+    projectId: input.projectId,
+    ontology: input.ontology,
+    projectionRegistry: input.projections,
+    storage: input.storage,
+    batching: resolveMaterializationBatching(dependencies.batching),
+    clock: dependencies.clock ?? (() => new Date()),
+    materializationId: dependencies.materializationId ?? createProjectionMaterializationId,
+    maxSerializationRetries,
+    ...(dependencies.onSerializationRetry !== undefined
+      ? { onSerializationRetry: dependencies.onSerializationRetry }
+      : {}),
+    ...(dependencies.observeCoreBuffer !== undefined
+      ? { observeCoreBuffer: dependencies.observeCoreBuffer }
+      : {}),
+  }
+}

package/src/materializer/edits/apply.ts

@@ -0,0 +1,241 @@
+import type { JsonValue } from "../../json"
+import { stableJsonStringify } from "../../json"
+import { MaterializationValidationError } from "../../materialization/errors"
+import type {
+  LinkOverride,
+  ObjectOverride,
+  OntologyEditOperation,
+} from "../../materialization/model"
+
+type ObjectEditOperation = Extract<
+  OntologyEditOperation,
+  { readonly ref: { readonly objectTypeId: string } }
+>
+type LinkEditOperation = Extract<
+  OntologyEditOperation,
+  { readonly ref: { readonly linkId: string } }
+>
+type ObjectWriteOperation = Extract<
+  ObjectEditOperation,
+  { readonly kind: "object.create" | "object.upsert" }
+>
+type ObjectPatchOverride = Extract<ObjectOverride, { readonly kind: "patch" }>
+
+interface ObjectEditInput {
+  readonly operation: ObjectEditOperation
+  readonly sourceProperties: Readonly<Record<string, JsonValue>> | null
+  readonly authority: ObjectOverride | null
+  readonly effectiveExists: boolean
+  readonly normalizedProperties?: Readonly<Record<string, JsonValue>>
+  readonly normalizedSet?: Readonly<Record<string, JsonValue>>
+}
+
+interface LinkEditInput {
+  readonly operation: LinkEditOperation
+  readonly hasSource: boolean
+  readonly authority: LinkOverride | null
+  readonly effectiveExists: boolean
+  readonly normalizedProperties?: Readonly<Record<string, JsonValue>>
+}
+
+export interface AuthorityTransition<T> {
+  readonly next: T | null
+  readonly changed: boolean
+}
+
+export function applyObjectEdit(input: ObjectEditInput): AuthorityTransition<ObjectOverride> {
+  const current = input.authority
+  let next: ObjectOverride | null
+
+  switch (input.operation.kind) {
+    case "object.create":
+      next = applyObjectCreate(input, input.operation)
+      break
+    case "object.upsert":
+      next = applyObjectUpsert(input, input.operation)
+      break
+    case "object.patch":
+      next = applyObjectPatch(input, input.operation)
+      break
+    case "object.delete":
+      next = applyObjectDelete(input)
+      break
+    case "object.restore":
+      next = applyObjectRestore(input)
+      break
+    default:
+      throw new MaterializationValidationError("Expected an object edit operation.")
+  }
+
+  return transition(current, next)
+}
+
+function applyObjectCreate(
+  input: ObjectEditInput,
+  operation: ObjectWriteOperation
+): ObjectOverride {
+  if (input.sourceProperties || input.authority) {
+    throw new MaterializationValidationError(
+      `Object create requires complete authority absence for ${operation.ref.objectTypeId}:${operation.ref.primaryId}.`
+    )
+  }
+  return { kind: "create", properties: input.normalizedProperties ?? operation.properties }
+}
+
+function applyObjectUpsert(
+  input: ObjectEditInput,
+  operation: ObjectWriteOperation
+): ObjectOverride {
+  const properties = input.normalizedProperties ?? operation.properties
+  const current = input.authority
+
+  if (current?.kind === "create") {
+    return { kind: "create", properties: { ...current.properties, ...properties } }
+  }
+  if (current?.kind === "patch") {
+    return mergeUpsertIntoPatch(current, properties, input.sourceProperties !== null)
+  }
+  if (input.sourceProperties) return { kind: "patch", set: properties, unset: [] }
+  return { kind: "create", properties }
+}
+
+function mergeUpsertIntoPatch(
+  current: ObjectPatchOverride,
+  properties: Readonly<Record<string, JsonValue>>,
+  hasSource: boolean
+): ObjectOverride {
+  if (hasSource) {
+    const unset = current.unset.filter((propertyId) => !(propertyId in properties))
+    return { kind: "patch", set: { ...current.set, ...properties }, unset }
+  }
+
+  const created = { ...current.set }
+  for (const propertyId of current.unset) delete created[propertyId]
+  return { kind: "create", properties: { ...created, ...properties } }
+}
+
+function applyObjectPatch(
+  input: ObjectEditInput,
+  operation: Extract<ObjectEditOperation, { readonly kind: "object.patch" }>
+): ObjectOverride | null {
+  const current = input.authority
+  if (!input.effectiveExists && current?.kind !== "patch") {
+    throw new MaterializationValidationError(
+      `Object patch requires an effective object for ${operation.ref.objectTypeId}:${operation.ref.primaryId}.`
+    )
+  }
+
+  const setInput = input.normalizedSet ?? operation.set
+  if (current?.kind === "create" && !input.sourceProperties) {
+    return patchCreatedObject(current, operation, setInput)
+  }
+
+  return patchOverride(toPatchOverride(current), operation, setInput)
+}
+
+function patchCreatedObject(
+  current: Extract<ObjectOverride, { readonly kind: "create" }>,
+  operation: Extract<ObjectEditOperation, { readonly kind: "object.patch" }>,
+  setInput: Readonly<Record<string, JsonValue>>
+): ObjectOverride {
+  const properties = { ...current.properties, ...setInput }
+  for (const propertyId of [...operation.unset, ...operation.reset]) {
+    delete properties[propertyId]
+  }
+  return { kind: "create", properties }
+}
+
+function toPatchOverride(current: ObjectOverride | null): ObjectPatchOverride {
+  if (current?.kind === "patch") return current
+  if (current?.kind === "create") {
+    return { kind: "patch", set: { ...current.properties }, unset: [] }
+  }
+  return { kind: "patch", set: {}, unset: [] }
+}
+
+function patchOverride(
+  base: ObjectPatchOverride,
+  operation: Extract<ObjectEditOperation, { readonly kind: "object.patch" }>,
+  setInput: Readonly<Record<string, JsonValue>>
+): ObjectOverride | null {
+  const set = { ...base.set }
+  const unset = new Set(base.unset)
+
+  for (const propertyId of operation.reset) {
+    delete set[propertyId]
+    unset.delete(propertyId)
+  }
+  for (const propertyId of operation.unset) {
+    delete set[propertyId]
+    unset.add(propertyId)
+  }
+  for (const [propertyId, value] of Object.entries(setInput)) {
+    set[propertyId] = value
+    unset.delete(propertyId)
+  }
+
+  if (Object.keys(set).length === 0 && unset.size === 0) return null
+  return { kind: "patch", set, unset: [...unset].sort() }
+}
+
+function applyObjectDelete(input: ObjectEditInput): ObjectOverride | null {
+  if (!input.effectiveExists) return input.authority
+  if (input.authority?.kind === "create" && !input.sourceProperties) return null
+  return { kind: "delete" }
+}
+
+function applyObjectRestore(input: ObjectEditInput): ObjectOverride | null {
+  if (input.authority?.kind !== "delete") return input.authority
+  return null
+}
+
+export function applyLinkEdit(input: LinkEditInput): AuthorityTransition<LinkOverride> {
+  const current = input.authority
+  let next: LinkOverride | null
+
+  switch (input.operation.kind) {
+    case "link.upsert":
+      next = linkUpsertOverride(input)
+      break
+    case "link.delete":
+      next = linkDeleteOverride(input)
+      break
+    case "link.reset":
+      next = null
+      break
+    default:
+      throw new MaterializationValidationError("Expected a link edit operation.")
+  }
+
+  return transition(current, next)
+}
+
+function linkUpsertOverride(input: LinkEditInput): LinkOverride {
+  if (input.normalizedProperties !== undefined) {
+    return { kind: "upsert", properties: input.normalizedProperties }
+  }
+  if (input.operation.kind === "link.upsert" && input.operation.properties !== undefined) {
+    return { kind: "upsert", properties: input.operation.properties }
+  }
+  return { kind: "upsert" }
+}
+
+function linkDeleteOverride(input: LinkEditInput): LinkOverride | null {
+  if (!input.effectiveExists) return input.authority
+  if (input.authority?.kind === "upsert" && !input.hasSource) return null
+  return { kind: "delete" }
+}
+
+function transition<T extends ObjectOverride | LinkOverride>(
+  current: T | null,
+  next: T | null
+): AuthorityTransition<T> {
+  return { next, changed: !sameAuthority(current, next) }
+}
+
+function sameAuthority(
+  left: ObjectOverride | LinkOverride | null,
+  right: ObjectOverride | LinkOverride | null
+): boolean {
+  return stableJsonStringify(left) === stableJsonStringify(right)
+}