@sixb/core 0.1.1 → 0.1.3

package/src/materializer/projections/replacement-plan.ts

@@ -29,12 +29,18 @@ import {
 } from "../effective/build-events"
 import { diffEffectiveLink, diffEffectiveObject } from "../effective/diff"
 import { oneStateRequest } from "../effective/load-state"
-import { resolveEffectiveLink, resolveEffectiveObject } from "../effective/resolve"
+import {
+  resolveEffectiveLink,
+  resolveEffectiveLinkSlotMember,
+  resolveEffectiveObject,
+  storedObjectEditedAt,
+  usableLinkSlotOverride,
+} from "../effective/resolve"
 import { validateEffectiveObject } from "../effective/validate"
 import { stageWorkBounded, validateStagedCardinality } from "../execution/work-executor"
 import {
-  appendLinkEffectivePlan,
-  appendObjectEffectivePlan,
+  appendEffectiveLinkWork,
+  appendEffectiveObjectWork,
   classificationWork,
   eventWork,
   planWork,
@@ -48,6 +54,7 @@ export interface ProjectionReplacementPlanInput {
   readonly projectionKind: "object" | "link"
   readonly identity: TimedCommitIdentity
   readonly origin: OntologyMaterializationOrigin
+  readonly correlationId: string
   readonly signal?: AbortSignal
 }
 
@@ -146,7 +153,7 @@ function appendObjectChangeWork(
   change: EffectiveObjectChange
 ): void {
   const items: MaterializationPlanWorkItem[] = []
-  appendObjectEffectivePlan(items, change)
+  appendEffectiveObjectWork(items, change)
   for (const item of items) work.push(planWork(item, sortKey))
   work.push(
     eventWork(
@@ -155,6 +162,7 @@ function appendObjectChangeWork(
         commitId: input.identity.commitId,
         committedAt: input.identity.committedAt,
         origin: input.origin,
+        correlationId: input.correlationId,
         change,
       })
     )
@@ -252,7 +260,7 @@ function planReplacementLink(
   endpointExistence: ReadonlyMap<string, boolean>,
   counts: MutableCounts
 ): MaterializationWorkRecord[] {
-  const resolved = resolveReplacementLink(state, endpointExistence)
+  const resolved = resolveReplacementLink(context, state, endpointExistence)
   const work = cardinalityWork(context, state, resolved !== null)
   if (!state.diffRequired) return work
 
@@ -275,10 +283,22 @@ function planReplacementLink(
 }
 
 function resolveReplacementLink(
+  context: Pick<MaterializerContext, "ontology">,
   state: SourceReplacementLinkState,
   endpointExistence: ReadonlyMap<string, boolean>
 ) {
   if (!state.diffRequired) return state.effective
+  const definition = context.ontology
+    .resolveObjectType(state.ref.source.objectTypeId)
+    .links.find((candidate) => candidate.id === state.ref.linkId)
+  if (definition?.cardinality === "one") {
+    return resolveEffectiveLinkSlotMember({
+      ref: state.ref,
+      source: state.candidateSource,
+      override: usableLinkSlotOverride(state.slotOverride),
+      endpointExists: (ref) => endpointExistence.get(objectRefKey(ref)) ?? false,
+    })
+  }
   return resolveEffectiveLink({
     ref: state.ref,
     source: state.candidateSource,
@@ -303,7 +323,17 @@ function cardinalityWork(
   return [
     {
       kind: "cardinality",
-      recordKey: `cardinality:${scopeSortKey}:${linkSortKey}`,
+      recordKey: `cardinality:candidate:${scopeSortKey}:${linkSortKey}`,
+      view: "candidate",
+      scopeSortKey,
+      linkSortKey,
+      ref: state.ref,
+      occupied: state.candidateSource !== null,
+    },
+    {
+      kind: "cardinality",
+      recordKey: `cardinality:effective:${scopeSortKey}:${linkSortKey}`,
+      view: "effective",
       scopeSortKey,
       linkSortKey,
       ref: state.ref,
@@ -320,7 +350,7 @@ function appendLinkChangeWork(
   change: EffectiveLinkChange
 ): void {
   const items: MaterializationPlanWorkItem[] = []
-  appendLinkEffectivePlan(items, change)
+  appendEffectiveLinkWork(items, change)
   for (const item of items) work.push(planWork(item, sortKey))
   work.push(
     eventWork(
@@ -329,6 +359,7 @@ function appendLinkChangeWork(
         commitId: input.identity.commitId,
         committedAt: input.identity.committedAt,
         origin: input.origin,
+        correlationId: input.correlationId,
         change,
       })
     )
@@ -344,6 +375,7 @@ function resolveReplacementObject(
     primaryPropertyId: context.ontology.getPrimaryPropertyId(state.ref.objectTypeId),
     source: state.candidateSource,
     override: state.override?.value ?? null,
+    editedAt: storedObjectEditedAt(state.override),
     latestTelemetry: state.latestTelemetry,
   })
 }

package/src/materializer/shared/batching.ts

@@ -9,7 +9,10 @@ export interface MaterializationBatching {
 }
 
 export const DEFAULT_MATERIALIZATION_BATCHING: MaterializationBatching = Object.freeze({
-  sourceStageRows: 1_000,
+  // Source staging pays execution fencing, manifest locking, conflict reconciliation, and one
+  // provider transaction per chunk. Two thousand rows cuts that fixed cost without the large RSS
+  // increase observed when every materialization boundary was raised to five thousand.
+  sourceStageRows: 2_000,
   sourceStageBytes: 4 * 1024 * 1024,
   statePageRows: 1_000,
   planChunkRows: 1_000,

package/src/materializer/shared/normalize.ts

@@ -1,4 +1,3 @@
-import type { EventActor } from "../../events/envelope"
 import { assertJsonValue, cloneJsonValue, compareStrings, stableJsonStringify } from "../../json"
 import { MaterializationValidationError } from "../../materialization/errors"
 import type {
@@ -26,6 +25,7 @@ import {
   projectionEntityKey,
   telemetryPointKey,
 } from "../../materialization/refs"
+import { parseDatasetTimestamp } from "../../projections/timestamp"
 
 export function normalizeJsonProperties(
   properties: Readonly<Record<string, unknown>>,
@@ -60,21 +60,6 @@ function normalizeNonblank(value: string, label: string): string {
   return value
 }
 
-function normalizeEventActor(actor: EventActor): EventActor {
-  if (typeof actor !== "object" || actor === null || Array.isArray(actor)) {
-    throw new MaterializationValidationError("Event actor must be an object.")
-  }
-  if (actor.type !== "user" && actor.type !== "serviceAccount" && actor.type !== "system") {
-    throw new MaterializationValidationError(
-      "Event actor type must be 'user', 'serviceAccount', or 'system'."
-    )
-  }
-  return Object.freeze({
-    type: actor.type,
-    id: normalizeNonblank(actor.id, "Event actor id"),
-  })
-}
-
 function normalizeTimestamp(value: string, label: string): string {
   const milliseconds = Date.parse(value)
   if (!Number.isFinite(milliseconds)) {
@@ -83,6 +68,16 @@ function normalizeTimestamp(value: string, label: string): string {
   return new Date(milliseconds).toISOString()
 }
 
+function normalizeProjectionSourceTimestamp(value: string): string {
+  const timestamp = parseDatasetTimestamp(value)
+  if (!timestamp) {
+    throw new MaterializationValidationError(
+      "Projection source update timestamp must be a valid timestamp."
+    )
+  }
+  return timestamp.toISOString()
+}
+
 function normalizePropertyIds(values: readonly string[], label: string): readonly string[] {
   const seen = new Set<string>()
   const normalized: string[] = []
@@ -280,7 +275,6 @@ export function normalizeOntologyEditCommit(input: OntologyEditCommit): Ontology
         kind: "runtime",
         requestId: normalizeNonblank(input.source.requestId, "Runtime request id"),
       }),
-      ...(input.actor !== undefined ? { actor: normalizeEventActor(input.actor) } : {}),
       operations: Object.freeze(operations),
       ...(input.operationGroups !== undefined
         ? { operationGroups: normalizeOperationGroups(input.operationGroups, operationIds) }
@@ -306,7 +300,6 @@ export function normalizeOntologyEditCommit(input: OntologyEditCommit): Ontology
   return Object.freeze({
     mode: "atomic",
     source,
-    ...(input.actor !== undefined ? { actor: normalizeEventActor(input.actor) } : {}),
     operations: Object.freeze(operations),
     expectedObjects: deduplicateExpectations(
       expectedObjects,
@@ -365,6 +358,11 @@ function normalizeProjectionAssertion(
         kind: "object",
         ref: normalizeObjectRef(assertion.ref),
         properties: normalizeJsonProperties(assertion.properties),
+        ...(assertion.sourceUpdatedAt !== undefined
+          ? {
+              sourceUpdatedAt: normalizeProjectionSourceTimestamp(assertion.sourceUpdatedAt),
+            }
+          : {}),
       })
     : Object.freeze({
         kind: "link",
@@ -521,7 +519,6 @@ export function normalizeTelemetryAppend(input: TelemetryAppend): TelemetryAppen
   }
   return Object.freeze({
     source,
-    ...(input.actor !== undefined ? { actor: normalizeEventActor(input.actor) } : {}),
     points: Object.freeze(points),
   })
 }

package/src/materializer/telemetry/append.ts

@@ -19,16 +19,21 @@ import type {
 } from "../../storage/ontology"
 import type { MaterializerContext, MaterializerStorage } from "../context"
 import { validateTelemetryPoint } from "../effective/validate"
-import {
-  replayCommit,
-  replayCommitRecord,
-  withSerializationRetry,
-} from "../execution/commit-lifecycle"
+import { replayCommitRecord, withSerializationRetry } from "../execution/commit-lifecycle"
 import {
   type LockedProjectionExecution,
   lockProjectionRunForMaterialization,
 } from "../execution/run-correlation"
+import {
+  assertMaterializerRunExecution,
+  assertRuntimeMutationExecution,
+  assertTrustedPrimitiveMutationExecution,
+  ensureMaterializerExecution,
+  type MaterializerExecution,
+  prepareMaterializerExecution,
+} from "../execution/scope"
 import { drainStagedEvents, drainStagedWork } from "../execution/work-executor"
+import type { MaterializerCommand } from "../materializer"
 import {
   createProjectionTelemetryIdempotencyKey,
   createRuntimeTelemetryIdempotencyKey,
@@ -50,6 +55,7 @@ interface PreparedTelemetryBase {
   readonly inputPointCount: number
   readonly ontologyRevision: string
   readonly identity: TimedCommitIdentity
+  readonly execution: MaterializerExecution
 }
 
 interface PreparedRuntimeTelemetry extends PreparedTelemetryBase {
@@ -68,34 +74,36 @@ type PreparedTelemetryAppend = PreparedRuntimeTelemetry | PreparedProjectionTele
 
 export async function appendTelemetry(
   context: MaterializerContext,
-  raw: TelemetryAppend
+  raw: MaterializerCommand<TelemetryAppend>
 ): Promise<TelemetryCommitResult> {
   const command = prepareTelemetryAppend(context, raw)
-  if (command.kind === "runtime") {
-    const replay = await replayCommit<TelemetryCommitResult>(context, command.identity)
-    if (replay) return replay
-  }
-
   return executeTelemetryCommit(context, command)
 }
 
 function prepareTelemetryAppend(
   context: Pick<MaterializerContext, "projectId" | "ontology" | "projectionRegistry" | "clock">,
-  raw: TelemetryAppend
+  raw: MaterializerCommand<TelemetryAppend>
 ): PreparedTelemetryAppend {
-  const rawInputPointCount = raw.points.length
+  const rawInputPointCount = raw.input.points.length
   const input = normalizeTelemetryAppend({
-    ...raw,
-    points: raw.points.map((point) => validateTelemetryPoint(context.ontology, point)),
+    ...raw.input,
+    points: raw.input.points.map((point) => validateTelemetryPoint(context.ontology, point)),
   })
   const inputPointCount = telemetryInputPointCount(input, rawInputPointCount)
   validateTelemetryBatch(input, inputPointCount)
 
   const ontologyRevision = context.projectionRegistry.ontologyRevision
+  const execution = prepareMaterializerExecution(context.projectId, raw.scope)
   if (input.source.kind === "runtime") {
-    return prepareRuntimeTelemetry(context, input, input.source, inputPointCount, ontologyRevision)
+    return {
+      ...prepareRuntimeTelemetry(context, input, input.source, inputPointCount, ontologyRevision),
+      execution,
+    }
+  }
+  return {
+    ...prepareProjectionTelemetry(context, input, input.source, inputPointCount, ontologyRevision),
+    execution,
   }
-  return prepareProjectionTelemetry(context, input, input.source, inputPointCount, ontologyRevision)
 }
 
 function telemetryInputPointCount(
@@ -127,7 +135,7 @@ function prepareRuntimeTelemetry(
   source: RuntimeTelemetrySource,
   inputPointCount: number,
   ontologyRevision: string
-): PreparedRuntimeTelemetry {
+): Omit<PreparedRuntimeTelemetry, "execution"> {
   const identity = createTimedCommitIdentity({
     projectId: context.projectId,
     idempotencyKey: createRuntimeTelemetryIdempotencyKey(source.requestId),
@@ -143,7 +151,7 @@ function prepareProjectionTelemetry(
   source: ProjectionTelemetrySource,
   inputPointCount: number,
   ontologyRevision: string
-): PreparedProjectionTelemetry {
+): Omit<PreparedProjectionTelemetry, "execution"> {
   const resolvedProjection = context.projectionRegistry.resolveTelemetry(
     source.projection.projectionId
   )
@@ -220,8 +228,7 @@ function projectionTelemetryCallerIntent(
     inputPointCount,
     points: input.points,
   }
-  if (input.actor === undefined) return intent
-  return { ...intent, actor: input.actor }
+  return intent
 }
 
 async function assertTelemetryExecution(
@@ -229,7 +236,15 @@ async function assertTelemetryExecution(
   projectId: string,
   command: PreparedTelemetryAppend
 ): Promise<LockedProjectionExecution | null> {
-  if (command.kind === "runtime") return null
+  if (command.kind === "runtime") {
+    assertRuntimeMutationExecution(command.execution)
+    return null
+  }
+  assertTrustedPrimitiveMutationExecution(command.execution, {
+    kind: "projection",
+    id: command.source.projection.projectionId,
+    runId: command.source.execution.projectionRunId,
+  })
   const execution = await lockProjectionRunForMaterialization(storage, {
     projectId,
     projectionRunId: command.source.execution.projectionRunId,
@@ -239,6 +254,11 @@ async function assertTelemetryExecution(
     capabilityErrorMessage:
       "Storage does not provide projection run capabilities required by telemetry projection.",
   })
+  assertMaterializerRunExecution(
+    command.execution,
+    execution.run.executionId,
+    `Projection run '${execution.run.id}'`
+  )
   assertTelemetryBatchPosition(
     execution.run,
     command.source.batchOrdinal,
@@ -327,8 +347,14 @@ async function executeTelemetryTransaction(
   storage: MaterializerStorage,
   command: PreparedTelemetryAppend
 ): Promise<TelemetryCommitResult> {
+  await ensureMaterializerExecution(storage.executions, command.execution)
   const execution = await assertTelemetryExecution(storage, context.projectId, command)
-  const replay = await replayCommitRecord(context, command.identity, storage)
+  const replay = await replayCommitRecord(
+    context,
+    command.identity,
+    command.execution.executionId,
+    storage
+  )
   if (replay) {
     if (command.kind === "projection" && execution) {
       assertTelemetryReplayCheckpoint(execution.run, command.source.batchOrdinal)
@@ -355,7 +381,11 @@ async function executeTelemetryTransaction(
     session,
     command.input,
     command.identity,
-    origin
+    origin,
+    {
+      correlationId: command.execution.correlationId,
+      ...(command.execution.actor === undefined ? {} : { actor: command.execution.actor }),
+    }
   )
   await drainStagedWork(context, storage.ontology.materializations, session)
   const eventCount = await drainStagedEvents(
@@ -426,6 +456,7 @@ function telemetryCommit(
     id: command.identity.commitId,
     idempotencyKey: command.identity.idempotencyKey,
     requestHash: command.identity.requestHash,
+    executionId: command.execution.executionId,
     origin,
     ontologyRevision: command.ontologyRevision,
     intent: telemetryCommitIntent(command),
@@ -444,8 +475,8 @@ function telemetryCommitActor(
   commit: OntologyCommitWrite,
   command: PreparedTelemetryAppend
 ): OntologyCommitWrite {
-  if (command.input.actor === undefined) return commit
-  return { ...commit, actor: command.input.actor }
+  if (command.execution.actor === undefined) return commit
+  return { ...commit, actor: command.execution.actor }
 }
 
 function telemetryCommitIntent(command: PreparedTelemetryAppend): TelemetryOntologyCommitIntent {

package/src/materializer/telemetry/plan.ts

@@ -1,3 +1,4 @@
+import type { EventActor } from "../../events/envelope"
 import { stableJsonStringify } from "../../json"
 import { MaterializationObjectNotFoundError } from "../../materialization/errors"
 import type {
@@ -31,7 +32,7 @@ import { loadState, oneStateRequest } from "../effective/load-state"
 import { validateEffectiveObject } from "../effective/validate"
 import { stageWorkBounded } from "../execution/work-executor"
 import {
-  appendObjectEffectivePlan,
+  appendEffectiveObjectWork,
   classificationWork,
   eventWork,
   planWork,
@@ -62,6 +63,12 @@ interface TelemetryPlanContext {
   readonly input: TelemetryAppend
   readonly identity: TimedCommitIdentity
   readonly origin: OntologyMaterializationOrigin
+  readonly event: TelemetryEventContext
+}
+
+interface TelemetryEventContext {
+  readonly correlationId: string
+  readonly actor?: EventActor
 }
 
 export async function planTelemetryAppend(
@@ -70,10 +77,11 @@ export async function planTelemetryAppend(
   session: MaterializationSession,
   input: TelemetryAppend,
   identity: TimedCommitIdentity,
-  origin: OntologyMaterializationOrigin
+  origin: OntologyMaterializationOrigin,
+  event: TelemetryEventContext
 ): Promise<TelemetryPlanCounts> {
   const counts = emptyTelemetryCounts()
-  const planContext = { input, identity, origin }
+  const planContext = { input, identity, origin, event }
   const objects = await loadTelemetryObjects(context, storage, session, input.points)
   const existingPoints = await loadExistingPoints(context, storage, session, input.points)
   for (const group of telemetryObjectGroups(input.points)) {
@@ -331,7 +339,7 @@ async function stageTelemetryObjectPlan(
   if (change) {
     counts.latestObjectsChanged += 1
     const items: MaterializationPlanWorkItem[] = []
-    appendObjectEffectivePlan(items, change)
+    appendEffectiveObjectWork(items, change)
     work.push(...items.map((item) => planWork(item, sortKey)))
     const eventContext = telemetryEventContext(context, planContext)
     work.push(eventWork(buildObjectMaterializationEventDraft({ ...eventContext, change })))
@@ -348,9 +356,10 @@ function telemetryEventContext(
     commitId: planContext.identity.commitId,
     committedAt: planContext.identity.committedAt,
     origin: planContext.origin,
+    correlationId: planContext.event.correlationId,
   }
-  if (planContext.input.actor === undefined) return eventContext
-  return { ...eventContext, actor: planContext.input.actor }
+  if (planContext.event.actor === undefined) return eventContext
+  return { ...eventContext, actor: planContext.event.actor }
 }
 
 function emptyTelemetryCounts(): MutableTelemetryPlanCounts {

package/src/objects/action/request.ts

@@ -12,12 +12,12 @@ import {
   requestActionAndWait as requestRuntimeActionAndWait,
 } from "../../actions/request"
 import type { ActionRunRecord } from "../../storage"
-import type { ResolvedObjectContext } from "../context"
+import type { ExecutionObjectContext } from "../context"
 
 export type { RequestActionAndWaitOptions, RequestActionOptions }
 
 export async function requestAction(
-  ctx: ResolvedObjectContext,
+  ctx: ExecutionObjectContext,
   params: {
     primaryId: string
     actionId: string
@@ -25,7 +25,7 @@ export async function requestAction(
     options?: RequestActionOptions
   }
 ): Promise<RequestActionResult> {
-  return requestRuntimeAction(ctx, {
+  return requestRuntimeAction(ctx, ctx.execution, {
     actionId: params.actionId,
     subject: {
       kind: "object",
@@ -39,7 +39,7 @@ export async function requestAction(
 }
 
 export async function requestActionAndWait(
-  ctx: ResolvedObjectContext,
+  ctx: ExecutionObjectContext,
   params: {
     primaryId: string
     actionId: string
@@ -47,7 +47,7 @@ export async function requestActionAndWait(
     options?: RequestActionAndWaitOptions
   }
 ): Promise<ActionRunRecord> {
-  return requestRuntimeActionAndWait(ctx, {
+  return requestRuntimeActionAndWait(ctx, ctx.execution, {
     actionId: params.actionId,
     subject: {
       kind: "object",

package/src/objects/context/index.ts

@@ -1,5 +1,6 @@
 export { requireLinkDefinition, resolveLinkContext, resolveObjectContext } from "./resolve"
 export type {
+  ExecutionObjectContext,
   ResolvedLinkBatchItem,
   ResolvedLinkContext,
   ResolvedObjectContext,

package/src/objects/context/types.ts

@@ -4,6 +4,7 @@
  * Context hierarchy: SixbRuntimeContext → ResolvedObjectContext → ResolvedLinkContext
  */
 
+import type { ExecutionContext } from "../../execution"
 import type { ObjectLink } from "../../ontology"
 import type { ObjectTypeWithPropertyTokens } from "../../ontology/tokens"
 import type { SixbRuntimeContext } from "../../runtime/types"
@@ -14,6 +15,11 @@ export interface ResolvedObjectContext extends SixbRuntimeContext {
   readonly primaryPropertyId: string
 }
 
+/** Object operations bound to one immutable execution. */
+export interface ExecutionObjectContext extends ResolvedObjectContext {
+  readonly execution: ExecutionContext
+}
+
 /** Resolved context for link operations. */
 export interface ResolvedLinkContext extends ResolvedObjectContext {
   readonly linkDefinition: ObjectLink