@sixb/core 0.1.18 → 0.1.19

package/src/actions/run/context.ts

@@ -0,0 +1,193 @@
+import { createSixbError } from "../../errors/internal"
+import type { Logger } from "../../logging"
+import type { ObjectTypeWithPropertyTokens } from "../../ontology/tokens"
+import { ObjectNotFoundError } from "../../storage"
+import type { ActionReadRecorder } from "../read-facade"
+import { createActionReadFacade } from "../read-facade"
+import type {
+  ActionDefinition,
+  ActionObjectSubject,
+  ActionReadFacade,
+  ActionRuntimeFacade,
+  ActionSubject,
+  ActionTargetObject,
+} from "../types"
+import { coerceActionParamsToTyped, isObjectActionDefinition } from "../validation"
+import type { LoadedObjectTarget } from "./phase-types"
+import type { ActionRunState } from "./state"
+import type { ActionRunContext, PendingActionRun } from "./types"
+
+export function toActionRuntimeFacade(runtime: ActionRunContext): ActionRuntimeFacade {
+  return {
+    blobs: {
+      put(input) {
+        return runtime.sixb.blobs.put(input)
+      },
+      open(blobId) {
+        return runtime.sixb.blobs.open(blobId)
+      },
+      stat(blobId) {
+        return runtime.sixb.blobs.stat(blobId)
+      },
+      createDownloadUrl(file, options) {
+        return runtime.sixb.blobs.createDownloadUrl(file, options)
+      },
+      revokeDownloadUrl(id) {
+        return runtime.sixb.blobs.revokeDownloadUrl(id)
+      },
+    },
+    connector: runtime.sixb.connector,
+    models: runtime.sixb.models,
+    objects(objectType) {
+      return {
+        appendTelemetryBatch(items) {
+          return runtime.sixb.objects.appendTelemetry(objectType.id, items)
+        },
+      }
+    },
+  }
+}
+
+export function toActionReadFacade(
+  runtime: ActionRunContext,
+  recorder: ActionReadRecorder
+): ActionReadFacade {
+  return createActionReadFacade(runtime.sixb, {
+    recorder,
+    resolveLinkIds: (objectTypeId) =>
+      runtime.sixb.objects.resolveType(objectTypeId).links.map((definition) => definition.id),
+    telemetry: {
+      resolveObjectType: (objectTypeId) => runtime.sixb.objects.resolveType(objectTypeId),
+      getHistoryBatch: (input) => runtime.sixb.objects.getTelemetryHistoryBatch(input),
+    },
+  })
+}
+
+function toActionTargetObject(
+  row: {
+    primaryId: string
+    objectTypeId: string
+    properties: Record<string, unknown>
+    createdAt: Date
+    updatedAt: Date
+  },
+  declaredObjectTypeId: string
+): ActionTargetObject {
+  return {
+    primaryId: row.primaryId,
+    objectTypeId: declaredObjectTypeId,
+    properties: row.properties,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  }
+}
+
+/** The handler context every phase shares. Each phase adds the `signal` it runs under. */
+export function createBasePhaseContext(input: {
+  readonly runtime: ActionRunContext
+  readonly action: ActionDefinition
+  readonly state: ActionRunState
+  readonly logger: Logger
+}) {
+  const { run, startedAt } = input.state
+  return {
+    run: {
+      id: run.id,
+      startedAt,
+      idempotencyKey: run.idempotencyKey,
+    },
+    logger: input.logger,
+    // Params are stored as JSON (date/timestamp -> ISO string); handler types
+    // promise `Date`, so re-hydrate them before the handler sees them.
+    params: coerceActionParamsToTyped(
+      input.action.params,
+      run.params,
+      input.runtime.sixb.objects.getValueTypesById()
+    ),
+    subject: run.subject,
+  }
+}
+
+export type BasePhaseContext = ReturnType<typeof createBasePhaseContext>
+
+export async function loadObjectTarget(input: {
+  readonly runtime: ActionRunContext
+  readonly action: ActionDefinition
+  readonly run: PendingActionRun
+}): Promise<LoadedObjectTarget | null> {
+  if (!isObjectActionDefinition(input.action)) {
+    if (input.run.subject.kind !== "none") {
+      throw createSixbError(
+        "internal.unexpected",
+        `[Sixb] Action '${input.action.id}' does not accept a subject.`,
+        { details: { actionId: input.action.id, runId: input.run.id } }
+      )
+    }
+    return null
+  }
+
+  const subject = requireObjectSubject(input.run.subject, {
+    actionId: input.action.id,
+    runId: input.run.id,
+  })
+  const subjectObjectType = input.runtime.sixb.objects.resolveType(subject.objectTypeId)
+  const actionAppliesToSubject = input.runtime.sixb.actions
+    .listForType(subjectObjectType)
+    .some((candidate) => candidate.id === input.action.id)
+  if (!actionAppliesToSubject) {
+    throw createSixbError(
+      "internal.unexpected",
+      `[Sixb] Action '${input.action.id}' is not valid for object type '${subjectObjectType.id}'.`,
+      { details: { actionId: input.action.id, runId: input.run.id } }
+    )
+  }
+
+  const targetRow = await input.runtime.storage.objects.getByPrimaryId({
+    projectId: input.runtime.id,
+    objectTypeId: subjectObjectType.id,
+    primaryId: subject.primaryId,
+  })
+  if (!targetRow) {
+    throw new ObjectNotFoundError(
+      subject.objectTypeId,
+      subject.primaryId,
+      "Object not found for action run"
+    )
+  }
+
+  return {
+    subjectObjectType,
+    snapshot: toActionTargetObject(targetRow, input.action.binding.objectType.id),
+    row: targetRow,
+  }
+}
+
+export function requireObjectSubject<
+  TObjectType extends ObjectTypeWithPropertyTokens = ObjectTypeWithPropertyTokens,
+>(
+  subject: ActionSubject,
+  input: { readonly actionId: string; readonly runId: string }
+): ActionObjectSubject<TObjectType> {
+  if (subject.kind !== "object") {
+    throw createSixbError(
+      "internal.unexpected",
+      `[Sixb] Action '${input.actionId}' requires an object subject.`,
+      { details: input }
+    )
+  }
+  return subject as ActionObjectSubject<TObjectType>
+}
+
+export function requireObjectTarget(
+  target: LoadedObjectTarget | null,
+  input: { readonly actionId: string; readonly runId: string }
+): LoadedObjectTarget {
+  if (!target) {
+    throw createSixbError(
+      "internal.unexpected",
+      `[Sixb] Action '${input.actionId}' requires an object target.`,
+      { details: input }
+    )
+  }
+  return target
+}

package/src/actions/run/edits-commit.ts

@@ -0,0 +1,102 @@
+import { recordEdits } from "../../edits/recorder"
+import type { RecordActionRunInput } from "../../storage"
+import type { ActionEditCommitResult } from "../commit-edits"
+import { commitActionEdits } from "../commit-edits"
+import type { ActionReadRecorder } from "../read-facade"
+import { isObjectActionDefinition } from "../validation"
+import { type BasePhaseContext, requireObjectSubject, toActionReadFacade } from "./context"
+import { throwIfAborted, translateActionPhaseError, untilAborted } from "./normalize"
+import type { LoadedObjectTarget, PhaseExecutionBase, RuntimePhaseHandler } from "./phase-types"
+import type { ActionRunState } from "./state"
+
+/** The commit of a run's edits, which recorded the run with them. */
+export interface CommittedActionRun {
+  readonly record: RecordActionRunInput
+  readonly commit: ActionEditCommitResult
+}
+
+/**
+ * Records the run's edits and commits them through the ontology Materializer, together with the
+ * run's terminal record. Resolves with `null` for an Action without edits, which commits nothing.
+ *
+ * Object and link-scope reads performed by the writeback and edits handlers, including every object
+ * a query or listing returned, are captured as expected revisions so a commit fails when that state
+ * changes. Query membership and telemetry history stay call-level snapshots. Domain events are
+ * durable outbox facts written inside the commit, so this phase never appends events itself.
+ *
+ * `signal` stops the edits handler and the step before the commit; the commit itself is never
+ * interrupted.
+ */
+export async function runEditsAndCommitPhase(
+  input: PhaseExecutionBase & {
+    readonly state: ActionRunState
+    readonly baseContext: BasePhaseContext
+    readonly objectTarget: LoadedObjectTarget | null
+    /** Shared with the writeback phase so both phases' reads fence the same commit. */
+    readonly reads: ActionReadRecorder
+  }
+): Promise<CommittedActionRun | null> {
+  const handler = input.action.phases.edits as RuntimePhaseHandler | undefined
+  if (!handler) return null
+
+  const { state } = input
+  const ids = { actionId: input.action.id, runId: state.run.id }
+  state.enter("edits")
+
+  const reads = input.reads
+  if (input.objectTarget) {
+    reads.observeObject(
+      {
+        objectTypeId: input.objectTarget.row.objectTypeId,
+        primaryId: input.objectTarget.row.primaryId,
+      },
+      input.objectTarget.row
+    )
+  }
+
+  let batch: Awaited<ReturnType<typeof recordEdits>>
+  try {
+    batch = await recordEdits(
+      {
+        runId: state.run.id,
+        valueTypesById: input.runtime.sixb.objects.getValueTypesById(),
+      },
+      async ({ objects }) => {
+        const baseContext = {
+          ...input.baseContext,
+          signal: input.signal,
+          objects,
+          read: toActionReadFacade(input.runtime, reads),
+          writeback: state.writebackValue,
+        }
+
+        const subject = isObjectActionDefinition(input.action)
+          ? { subject: requireObjectSubject(state.run.subject, ids) }
+          : {}
+        await untilAborted(async () => handler({ ...baseContext, ...subject }), input.signal)
+      }
+    )
+  } catch (error) {
+    throw translateActionPhaseError(error, "edits", { ...ids, signal: input.signal })
+  }
+
+  throwIfAborted(input.signal)
+  state.enter("commit")
+  // Built as the commit starts: the run succeeds exactly when this commit does.
+  const record = state.succeeded()
+
+  let commit: ActionEditCommitResult
+  try {
+    commit = await commitActionEdits({
+      mutations: input.runtime.ontologyMutations,
+      run: record,
+      batch,
+      dependencies: reads.dependencies(),
+    })
+  } catch (error) {
+    // The commit ran to its end whatever `signal` did meanwhile, so its error is never a timeout.
+    throw translateActionPhaseError(error, "commit", ids)
+  }
+
+  return { record, commit }
+}

package/src/actions/run/effects.ts

@@ -0,0 +1,105 @@
+import { reportActionPhaseFailure } from "../../error-reporting/capability"
+import type { Logger } from "../../logging"
+import { resolveLoggingService } from "../../logging/service"
+import type { RecordActionEffectsInput } from "../../storage"
+import type { ActionEditCommitResult } from "../commit-edits"
+import type { ActionDefinition } from "../types"
+import { isObjectActionDefinition } from "../validation"
+import { createBasePhaseContext, requireObjectSubject, toActionRuntimeFacade } from "./context"
+import { toActionRunFailure, translateActionPhaseError, untilAborted } from "./normalize"
+import type { ActionDeadline } from "./signals"
+import type { ActionRunState } from "./state"
+import type { ActionRunContext } from "./types"
+
+export interface RunActionEffectsInput {
+  readonly runtime: ActionRunContext
+  readonly action: ActionDefinition
+  /** The run, recorded as succeeded with the commit its effects receive. */
+  readonly state: ActionRunState
+  readonly commit: ActionEditCommitResult
+  /** Starts the effects' deadline. */
+  readonly startDeadline: () => ActionDeadline
+}
+
+/**
+ * Run a recorded run's effects and record their outcome on it.
+ *
+ * Effects run after the run's record is returned, and nothing waits for them but a stopping
+ * process. They are best-effort: their failure does not reject this, it is recorded on the run and
+ * reported to `onError`, and the run stays succeeded.
+ */
+export async function runActionEffects(input: RunActionEffectsInput): Promise<void> {
+  const { runtime, action, state } = input
+  const ids = { actionId: action.id, runId: state.run.id }
+  const logSession = resolveLoggingService(runtime.id, runtime.logging).startExecution({
+    kind: "action",
+    id: state.run.id,
+  })
+  const deadline = input.startDeadline()
+
+  try {
+    const outcome = await callEffects(
+      input,
+      deadline.signal,
+      logSession.withContext({ phase: "effects" })
+    )
+    try {
+      await runtime.actionRunsStorage.recordEffects(outcome)
+    } catch (error) {
+      console.error(
+        `[Sixb] Action run '${ids.runId}' ran its effects, but their outcome could not be recorded:`,
+        error
+      )
+    }
+  } finally {
+    deadline.dispose()
+    await logSession.flush()
+  }
+}
+
+/** Call the effects handler, and describe how it ended. A failure is reported here, once. */
+async function callEffects(
+  input: RunActionEffectsInput,
+  signal: AbortSignal,
+  logger: Logger
+): Promise<RecordActionEffectsInput> {
+  const { runtime, action, state } = input
+  const ids = { actionId: action.id, runId: state.run.id }
+  const effects = { id: state.run.id, projectId: runtime.id }
+
+  try {
+    const context = {
+      ...createBasePhaseContext({ runtime, action, state, logger }),
+      signal,
+      sixb: toActionRuntimeFacade(runtime),
+      writeback: state.writebackValue,
+      commit: input.commit,
+    }
+    await untilAborted(async () => {
+      if (isObjectActionDefinition(action)) {
+        await action.phases.effects?.({
+          ...context,
+          subject: requireObjectSubject(state.run.subject, ids),
+        })
+      } else {
+        await action.phases.effects?.(context)
+      }
+    }, signal)
+  } catch (error) {
+    const completedAt = new Date()
+    const failure = toActionRunFailure(
+      translateActionPhaseError(error, "effects", { ...ids, signal }),
+      "effects",
+      { ...ids, at: completedAt }
+    )
+    reportActionPhaseFailure(runtime.errorReporterHost, error, {
+      projectId: runtime.id,
+      ...ids,
+      phase: "effects",
+      failure,
+    })
+    return { ...effects, status: "failed", completedAt, error: failure }
+  }
+
+  return { ...effects, status: "succeeded", completedAt: new Date() }
+}

package/src/actions/run/execute.ts

@@ -0,0 +1,113 @@
+import { createSixbError } from "../../errors/internal"
+import {
+  type BoundPrimitiveExecution,
+  bindDurablePrimitiveExecution,
+  type PrimitiveExecutionHost,
+} from "../../execution/primitive"
+import type { LoggingService } from "../../logging/service"
+import type { SixbDefinitions } from "../../runtime/definitions"
+import type { ActionRunStorage, Storage } from "../../storage"
+import type { ExecutionRecord } from "../../storage/executions"
+import { runAction } from "./run-action"
+import { ActionRunSignals } from "./signals"
+import type { ActionRunContext, ActionRunOutcome, PendingActionRun } from "./types"
+
+/** What executing a stored Action run needs from its host. */
+export interface ActionRunHost extends PrimitiveExecutionHost {
+  readonly storage: Storage
+  readonly logging?: LoggingService
+  readonly definitions: Pick<SixbDefinitions, "actions">
+}
+
+export interface ExecuteActionRunInput {
+  readonly run: PendingActionRun
+  /** The durable execution the run was requested under. */
+  readonly execution: ExecutionRecord
+  /** Cancels the run before its irreversible boundary. */
+  readonly signal?: AbortSignal
+  /** Test-only override of the 30-second deadlines of the run and of its effects. */
+  readonly timeoutMs?: number
+}
+
+/**
+ * The model-call attempt an Action run accounts under.
+ *
+ * Model accounting records every call against an execution attempt. A run executes once, in the
+ * process that requested it, so it is always the first.
+ */
+const MODEL_EXECUTION_ATTEMPT = 1
+
+/**
+ * Execute a requested Action run inside the durable execution it was requested under, and record it.
+ *
+ * Binds the Action's primitive scope to that execution, then runs the phases under the run's
+ * deadline and the caller's signal. Its effects, when it has any, are left to start: see
+ * {@link ActionRunOutcome.effects}.
+ */
+export async function executeActionRun(
+  host: ActionRunHost,
+  input: ExecuteActionRunInput
+): Promise<ActionRunOutcome> {
+  const { run, execution } = input
+  const actionRuns = requireActionRunStorage(host, run.id)
+  const signals = new ActionRunSignals({
+    actionId: run.actionId,
+    runId: run.id,
+    caller: input.signal,
+    timeoutMs: input.timeoutMs,
+  })
+
+  try {
+    const bound = bindDurablePrimitiveExecution(host, {
+      // Model calls stop with their phase through the `signal` a handler forwards to them. Binding
+      // the run's deadline here would also stop the embedding calls behind the vector reads that
+      // edits make past the boundary, which must always finish.
+      modelExecution: { attempt: MODEL_EXECUTION_ATTEMPT, signal: signals.uninterruptible },
+      execution,
+      primitive: { kind: "action", id: run.actionId, runId: run.id },
+    })
+    return await runAction({
+      runtime: buildActionContext(host, actionRuns, bound),
+      run,
+      signals,
+    })
+  } finally {
+    signals.dispose()
+  }
+}
+
+function requireActionRunStorage(host: ActionRunHost, runId: string): ActionRunStorage {
+  const actionRuns = host.storage.actionRuns
+  if (!actionRuns) {
+    throw createSixbError(
+      "internal.unexpected",
+      "[Sixb] Action execution requires storage.actionRuns support.",
+      { details: { runId } }
+    )
+  }
+  return actionRuns
+}
+
+function buildActionContext(
+  host: ActionRunHost,
+  actionRunsStorage: ActionRunStorage,
+  execution: BoundPrimitiveExecution
+): ActionRunContext {
+  const sixb = {
+    models: execution.sixb.models,
+    objects: execution.sixb.objects,
+    actions: execution.sixb.actions,
+    connector: execution.sixb.connector,
+    blobs: execution.sixb.blobs,
+  }
+  return {
+    id: host.id,
+    errorReporterHost: host,
+    logging: host.logging,
+    storage: host.storage,
+    actionRunsStorage,
+    ontologyMutations: execution.ontologyMutations,
+    sixb,
+    actions: host.definitions.actions,
+  }
+}