@sixb/core 0.1.17 → 0.1.19

package/src/actions/run/executor.ts

@@ -0,0 +1,314 @@
+import { reportRunFailure } from "../../error-reporting/capability"
+import { createSixbError, type SixbCodedError } from "../../errors/internal"
+import type { ActionRunRecord } from "../../storage"
+import {
+  type ActionRunRequestPayload,
+  type AssertCanReuseActionRun,
+  assertCanReuseActionRun,
+  type PersistedActionRun,
+} from "../run-persistence"
+import { type ActionRunHost, executeActionRun } from "./execute"
+import { toActionRunFailure } from "./normalize"
+import { UnrecordedActionRunError } from "./run-action"
+import type { PendingActionRun } from "./types"
+
+/** A request for an Action run, handed over to execute in the requesting process. */
+export interface ActionRunRequest {
+  readonly runId: string
+  readonly payload: ActionRunRequestPayload
+  /** Find the record of an earlier request with the same run id, or create the run's execution. */
+  readonly persist: () => Promise<PersistedActionRun>
+  /** Refuse a run that already exists under the run id, when this request's caller may not have it. */
+  readonly assertCanReuse: AssertCanReuseActionRun
+  /** Cancels the run before its irreversible boundary. */
+  readonly signal?: AbortSignal
+  /** Called once the run's execution exists, before the run executes. A throw starts nothing. */
+  readonly onRequested?: (runId: string) => void | Promise<void>
+}
+
+type NewActionRun = Extract<PersistedActionRun, { readonly kind: "new" }>
+
+/** A request of this process that holds a run id, from before it looks the run id up. */
+interface HeldRunId {
+  /**
+   * The run once its execution exists. It resolves with `null` when the request executes nothing,
+   * having found a record or failed before, and the run id is released by then.
+   */
+  readonly pending: Promise<PendingActionRun | null>
+}
+
+/**
+ * Runs requested Actions in the calling process, and tracks each request until its run is recorded
+ * and its effects ended, so that a stopping process can wait for them.
+ *
+ * `SixbHost` registers one on itself and on the context its bound SDKs share, so a request can
+ * execute its run without holding the host.
+ */
+export class ActionRunExecutor {
+  private readonly inFlight = new Set<Promise<void>>()
+  /** Run ids held by a request of this process, until it ends. */
+  private readonly held = new Map<string, HeldRunId>()
+  private stopping = false
+
+  constructor(private readonly host: ActionRunHost) {}
+
+  /**
+   * Execute a requested run to its terminal record, or answer with the record of an earlier request
+   * for the same run id.
+   *
+   * The request is tracked from before anything is persisted, so that {@link drain} waits for it
+   * from the start. Once the process is stopping, a new request is refused before anything is
+   * persisted. A request for a run id that this process is executing is refused as in progress:
+   * see {@link joinHeldRunId}. A request for the same run id in another process executes too, and
+   * the request that records it second answers with the first one's record, under the same checks
+   * as any record it finds.
+   *
+   * Once the run's execution exists, the request either resolves with the run's record or rejects
+   * with `internal.unexpected`: see {@link failRequest}.
+   */
+  request(request: ActionRunRequest): Promise<ActionRunRecord> {
+    if (this.stopping) {
+      return Promise.reject(
+        createSixbError(
+          "runtime.stopping",
+          "[Sixb] The runtime is stopping and starts no new Action run; retry the request."
+        )
+      )
+    }
+    const requested = this.dispatch(request)
+    this.track(requested)
+    return requested
+  }
+
+  /**
+   * Refuse new requests, then wait for at most `timeoutMs` for those in flight and for the effects
+   * they start meanwhile.
+   */
+  async drain(timeoutMs: number): Promise<void> {
+    this.stopping = true
+    const deadline = Date.now() + Math.max(0, timeoutMs)
+    // A request that ends starts its run's effects before it settles, so they are tracked by the
+    // time the wait for the request returns: wait again until nothing is left.
+    while (this.inFlight.size > 0) {
+      if (!(await settleWithin([...this.inFlight], deadline - Date.now()))) {
+        console.error(
+          `[Sixb] Stopped waiting after ${timeoutMs} ms for ${this.inFlight.size} in-flight Action run(s).`
+        )
+        return
+      }
+    }
+  }
+
+  /** Track work until it settles. Whoever started it handles how it ends; this only waits. */
+  private track(work: Promise<unknown>): void {
+    const settled: Promise<void> = work
+      .then(
+        () => undefined,
+        () => undefined
+      )
+      .finally(() => {
+        this.inFlight.delete(settled)
+      })
+    this.inFlight.add(settled)
+  }
+
+  private async dispatch(request: ActionRunRequest): Promise<ActionRunRecord> {
+    // A request that held the run id but executes nothing releases it before its `pending`
+    // settles, so each turn of this loop finds the run id free or held by another request.
+    for (let held = this.held.get(request.runId); held; held = this.held.get(request.runId)) {
+      const run = await held.pending
+      if (run) return this.joinHeldRunId(run, request)
+    }
+    return this.holdAndExecute(request)
+  }
+
+  /**
+   * Answer a request for a run id that a request of this process executes.
+   *
+   * Nothing is stored about a run before it ends, so this process is the only one that knows the
+   * run is in progress. The request gets what a stored run would give it: refused when its caller
+   * may not have the run or asks for something else, the record once it is written, and
+   * `action.run_in_progress` until then.
+   */
+  private async joinHeldRunId(
+    run: PendingActionRun,
+    request: ActionRunRequest
+  ): Promise<ActionRunRecord> {
+    await assertCanReuseActionRun(run, request)
+    const recorded = await this.host.storage.actionRuns?.getById({
+      projectId: run.projectId,
+      id: run.id,
+    })
+    if (recorded) return recorded
+    throw createSixbError(
+      "action.run_in_progress",
+      `[Sixb] Action run '${run.id}' is already in progress.`,
+      { details: { actionId: run.actionId, runId: run.id } }
+    )
+  }
+
+  private async holdAndExecute(request: ActionRunRequest): Promise<ActionRunRecord> {
+    const { runId } = request
+    const pending = Promise.withResolvers<PendingActionRun | null>()
+    this.held.set(runId, { pending: pending.promise })
+    try {
+      const persisted = await request.persist()
+      if (persisted.kind === "recorded") return persisted.run
+      pending.resolve(persisted.run)
+      return await this.execute(persisted, request)
+    } finally {
+      this.held.delete(runId)
+      pending.resolve(null)
+    }
+  }
+
+  private async execute(
+    persisted: NewActionRun,
+    request: ActionRunRequest
+  ): Promise<ActionRunRecord> {
+    const { run, execution } = persisted
+    try {
+      await request.onRequested?.(run.id)
+    } catch (error) {
+      // Nothing ran and nothing is recorded: the error belongs to the caller whose hook threw.
+      throw createSixbError(
+        "internal.unexpected",
+        `[Sixb] Action run '${run.id}' did not start: its requester failed before it executed.`,
+        { cause: error, details: { actionId: run.actionId, runId: run.id } }
+      )
+    }
+
+    let outcome: Awaited<ReturnType<typeof executeActionRun>>
+    try {
+      outcome = await executeActionRun(this.host, { run, execution, signal: request.signal })
+    } catch (error) {
+      throw this.failRequest(run, error)
+    }
+
+    if (!outcome.recorded) {
+      // Another process recorded this run id first: its record answers this request only under
+      // the checks a record found before executing gets.
+      await assertCanReuseActionRun(outcome.record, request)
+      return outcome.record
+    }
+    if (outcome.effects) this.startEffects(run, outcome.effects)
+    return outcome.record
+  }
+
+  /**
+   * Start a recorded run's effects once the request has returned, tracked until they end. Deferring
+   * them keeps a handler that does synchronous work before its first `await` from delaying the
+   * response.
+   */
+  private startEffects(run: PendingActionRun, effects: () => Promise<void>): void {
+    this.track(
+      new Promise<void>((resolve) => setImmediate(resolve))
+        .then(effects)
+        .catch((error: unknown) => {
+          console.error(`[Sixb] Action run '${run.id}' failed to run its effects:`, error)
+        })
+    )
+  }
+
+  /**
+   * Fail a request whose run's execution exists.
+   *
+   * The run may have executed, so the caller gets an `internal.unexpected` error that names the run
+   * and says what requesting it again does, never what went wrong inside it: that goes to
+   * `onError`, once, with the failure the run recorded or would have recorded. Errors outside the
+   * run's phases fail it in `validation`, the phase it starts in.
+   */
+  private failRequest(run: PendingActionRun, error: unknown): SixbCodedError {
+    const ids = { actionId: run.actionId, runId: run.id }
+    const requestError = createSixbError(
+      "internal.unexpected",
+      `[Sixb] Action run '${run.id}' was requested, but its record could not be written. ` +
+        "Requesting it again with the same runId returns its record if it was written, and runs " +
+        "it again otherwise.",
+      { cause: error, details: ids }
+    )
+    const at = new Date()
+    reportRunFailure(this.host, requestError, {
+      projectId: this.host.id,
+      runKind: "action",
+      run: ids,
+      failure:
+        error instanceof UnrecordedActionRunError
+          ? (error.record.error ??
+            toActionRunFailure(error.cause, error.record.phase, { ...ids, at }))
+          : toActionRunFailure(error, "validation", { ...ids, at }),
+    })
+    return requestError
+  }
+}
+
+const actionRunExecutorKey: unique symbol = Symbol("sixb.actionRunExecutor")
+
+interface ActionRunExecutorOwner {
+  readonly [actionRunExecutorKey]?: ActionRunExecutor
+}
+
+/**
+ * Attach the executor to a host or runtime context. The property is enumerable so that spreading a
+ * context into a narrower one carries it along.
+ */
+export function registerActionRunExecutor(owner: object, executor: ActionRunExecutor): void {
+  const registered = findActionRunExecutor(owner)
+  if (registered && registered !== executor) {
+    throw new Error("[Sixb] An Action run executor is already registered for this owner.")
+  }
+  Object.defineProperty(owner, actionRunExecutorKey, {
+    configurable: false,
+    enumerable: true,
+    value: executor,
+    writable: false,
+  })
+}
+
+export function getActionRunExecutor(owner: object): ActionRunExecutor {
+  const executor = findActionRunExecutor(owner)
+  if (executor) return executor
+  throw new Error(
+    "[Sixb] Actions cannot run from this runtime context: it was not bound by SixbHost.withScope()."
+  )
+}
+
+/** Copy the executor, when there is one, onto an internal runtime context being reconstructed. */
+export function shareActionRunExecutor(source: object, target: object): void {
+  const executor = findActionRunExecutor(source)
+  if (executor) registerActionRunExecutor(target, executor)
+}
+
+/**
+ * Refuse new Action requests on this host, then wait for at most `timeoutMs` for those in flight.
+ *
+ * Every `SixbHost` has an executor from construction on, so an object without one is not a host.
+ */
+export async function drainActionRuns(host: object, timeoutMs: number): Promise<void> {
+  const executor = findActionRunExecutor(host)
+  if (!executor) {
+    throw new Error("[Sixb] Cannot drain Action runs: this object is not a SixbHost.")
+  }
+  await executor.drain(timeoutMs)
+}
+
+function findActionRunExecutor(owner: object): ActionRunExecutor | undefined {
+  return (owner as ActionRunExecutorOwner)[actionRunExecutorKey]
+}
+
+async function settleWithin(
+  promises: readonly Promise<unknown>[],
+  timeoutMs: number
+): Promise<boolean> {
+  let timeout: ReturnType<typeof setTimeout> | undefined
+  try {
+    return await Promise.race([
+      Promise.allSettled(promises).then(() => true),
+      new Promise<false>((resolve) => {
+        timeout = setTimeout(() => resolve(false), timeoutMs)
+      }),
+    ])
+  } finally {
+    if (timeout) clearTimeout(timeout)
+  }
+}

package/src/actions/run/normalize.ts

@@ -0,0 +1,142 @@
+import {
+  createSixbError,
+  isSixbError,
+  type SixbCodedError,
+  summarizeErrorMessage,
+  toSixbFailure,
+} from "../../errors/internal"
+import { isMaterializationConflictError } from "../../materialization/errors"
+import { ACTION_RUN_FAILURE_CODES, type ActionRunFailure, type ActionRunPhase } from "../../storage"
+import { parseActionRunFailure } from "../../storage/action-runs/failure"
+import { isActionTimeout } from "./signals"
+
+export function throwIfAborted(signal: AbortSignal): void {
+  if (signal.aborted) throw abortReason(signal)
+}
+
+function abortReason(signal: AbortSignal): unknown {
+  return signal.reason instanceof Error
+    ? signal.reason
+    : new DOMException("[Sixb] Action run was cancelled.", "AbortError")
+}
+
+/**
+ * Wait for a handler until the signal of its phase aborts, then reject with the abort's reason.
+ *
+ * A handler stops early only when it forwards its `signal` to what it awaits. One that does not
+ * keeps running after the abort, but the run no longer waits for it: nothing it does from then on
+ * reaches the run, and what it throws is dropped.
+ */
+export async function untilAborted<T>(work: () => Promise<T>, signal: AbortSignal): Promise<T> {
+  throwIfAborted(signal)
+  const aborted = Promise.withResolvers<never>()
+  const abort = () => aborted.reject(abortReason(signal))
+  signal.addEventListener("abort", abort, { once: true })
+  const running = (async () => work())()
+  try {
+    return await Promise.race([running, aborted.promise])
+  } finally {
+    signal.removeEventListener("abort", abort)
+    running.catch(() => undefined)
+  }
+}
+
+/**
+ * Translate work performed by an Action phase without misclassifying its bookkeeping.
+ *
+ * Whatever a handler throws once its phase's signal aborted is that abort's doing: the run failed
+ * with `action.timeout` when its deadline elapsed, and with `runtime.cancelled` when its caller
+ * aborted. The handler's own error stays the cause reported to `onError`. Every expectation an
+ * Action commit carries comes from the Action's own reads, so an expectation conflict at commit is
+ * a read conflict: the run can be requested again against current state.
+ */
+export function translateActionPhaseError(
+  error: unknown,
+  phase: ActionRunPhase,
+  input: {
+    readonly actionId: string
+    readonly runId: string
+    /** The signal the work ran under. Omit it for work that nothing interrupts, like a commit. */
+    readonly signal?: AbortSignal
+  }
+): unknown {
+  const details = { actionId: input.actionId, runId: input.runId, phase }
+  if (input.signal?.aborted) {
+    if (isActionTimeout(input.signal.reason)) {
+      return isActionTimeout(error)
+        ? error
+        : createSixbError(
+            "action.timeout",
+            `[Sixb] Action run '${input.runId}' exceeded its deadline during ${phase}.`,
+            { cause: error, details }
+          )
+    }
+    return isSixbError(error) && error.code === "runtime.cancelled"
+      ? error
+      : createSixbError(
+          "runtime.cancelled",
+          `[Sixb] Action run '${input.runId}' was cancelled by its caller during ${phase}.`,
+          { cause: error, details }
+        )
+  }
+  if (isSixbError(error) && error.code === "internal.unexpected") {
+    return error
+  }
+  if (phase === "commit" && isMaterializationConflictError(error) && error.kind === "expectation") {
+    return createSixbError("action.read_conflict", error.message, { cause: error, details })
+  }
+
+  return createSixbError(
+    "action.phase_failed",
+    summarizeErrorMessage(error, "Action phase execution failed."),
+    { cause: error, details }
+  )
+}
+
+/** Whether a phase classified this error as the phase's own failure, rather than as an abort. */
+export function isActionPhaseFailure(error: unknown): error is SixbCodedError {
+  return (
+    isSixbError(error) &&
+    (error.code === "action.phase_failed" || error.code === "action.read_conflict")
+  )
+}
+
+/** Recover the native phase error for direct callers and error-monitoring integrations. */
+export function unwrapActionPhaseError(error: unknown): unknown {
+  return isActionPhaseFailure(error) && error.cause !== undefined ? error.cause : error
+}
+
+export function toActionRunFailure<TPhase extends ActionRunPhase>(
+  error: unknown,
+  phase: TPhase,
+  input: {
+    readonly actionId: string
+    readonly runId: string
+    readonly at: Date
+  }
+): ActionRunFailure<TPhase> {
+  const code =
+    isSixbError(error) && (ACTION_RUN_FAILURE_CODES as readonly string[]).includes(error.code)
+      ? (error.code as ActionRunFailure<TPhase>["code"])
+      : "internal.unexpected"
+  const normalized = createSixbError(
+    code,
+    summarizeErrorMessage(error, "Action execution failed."),
+    {
+      cause: unwrapActionPhaseError(error),
+      details: {
+        actionId: input.actionId,
+        runId: input.runId,
+        phase,
+      },
+    }
+  )
+
+  return parseActionRunFailure(
+    toSixbFailure(normalized, {
+      allowedCodes: ACTION_RUN_FAILURE_CODES,
+      at: input.at,
+    }),
+    phase
+  )
+}

package/src/actions/run/phase-types.ts

@@ -0,0 +1,20 @@
+import type { ObjectTypeWithPropertyTokens } from "../../ontology/tokens"
+import type { ObjectRow } from "../../storage"
+import type { ActionDefinition, ActionTargetObject } from "../types"
+import type { ActionRunContext } from "./types"
+
+export type LoadedObjectTarget = {
+  readonly subjectObjectType: ObjectTypeWithPropertyTokens
+  readonly snapshot: ActionTargetObject
+  /** The exact row the subject was loaded from, recorded as a commit-time read dependency. */
+  readonly row: ObjectRow
+}
+
+export type PhaseExecutionBase = {
+  readonly runtime: ActionRunContext
+  readonly action: ActionDefinition
+  /** The signal this phase's handler runs under; see `ActionRunSignals`. */
+  readonly signal: AbortSignal
+}
+
+export type RuntimePhaseHandler = (ctx: unknown) => unknown

package/src/actions/run/phases.ts

@@ -0,0 +1,150 @@
+import { isSixbError } from "../../errors/internal"
+import { resolveLoggingService } from "../../logging/service"
+import { ActionReadRecorder } from "../read-facade"
+import type { ActionDefinition } from "../types"
+import { isObjectActionDefinition } from "../validation"
+import { runActionValidators } from "../validators"
+import { createBasePhaseContext, loadObjectTarget } from "./context"
+import { type CommittedActionRun, runEditsAndCommitPhase } from "./edits-commit"
+import { throwIfAborted, translateActionPhaseError, untilAborted } from "./normalize"
+import type { ActionRunSignals } from "./signals"
+import type { ActionRunState } from "./state"
+import type { ActionRunContext } from "./types"
+import { runWritebackPhase } from "./writeback"
+
+/** Commits a run attempts before a read conflict fails it. */
+const MAX_COMMIT_ATTEMPTS = 3
+
+type LogSession = ReturnType<ReturnType<typeof resolveLoggingService>["startExecution"]>
+
+interface PhasesInput {
+  readonly runtime: ActionRunContext
+  readonly action: ActionDefinition
+  readonly state: ActionRunState
+  readonly signals: ActionRunSignals
+}
+
+/**
+ * Run the phases up to the commit, keeping what they do on the run's state.
+ *
+ * Resolves with the commit, which recorded the run, for an Action with edits; and with `null` for
+ * one without, whose run is still to record. Rejects when a phase fails.
+ */
+export async function executeActionPhases(input: PhasesInput): Promise<CommittedActionRun | null> {
+  const logSession = resolveLoggingService(input.runtime.id, input.runtime.logging).startExecution({
+    kind: "action",
+    id: input.state.run.id,
+  })
+
+  try {
+    return await commitWithReplay({ ...input, logSession })
+  } finally {
+    await logSession.flush()
+  }
+}
+
+/**
+ * Runs the phases up to the commit, and replays them when the commit hits a read conflict.
+ *
+ * Before the boundary nothing irreversible happened, so the run restarts from validation against
+ * current state while its deadline allows. After a succeeded writeback only edits and commit replay,
+ * with the same writeback value: the external change happened, and the ontology must still record
+ * it.
+ */
+async function commitWithReplay(
+  input: PhasesInput & { readonly logSession: LogSession }
+): Promise<CommittedActionRun | null> {
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      return await commitOnce(input)
+    } catch (error) {
+      const replayable =
+        isReadConflict(error) &&
+        attempt < MAX_COMMIT_ATTEMPTS &&
+        (hasSucceededWriteback(input.state) || !input.signals.beforeBoundary.aborted)
+      if (!replayable) throw error
+    }
+  }
+}
+
+async function commitOnce(
+  input: PhasesInput & { readonly logSession: LogSession }
+): Promise<CommittedActionRun | null> {
+  const { runtime, action, state, signals, logSession } = input
+  const ids = { actionId: action.id, runId: state.run.id }
+  const replayingEdits = hasSucceededWriteback(state)
+  const signal = replayingEdits ? signals.uninterruptible : signals.beforeBoundary
+
+  throwIfAborted(signal)
+  // A replay starts over from the phase it repeats: what fails from here on failed there, not in
+  // the commit the previous attempt reached.
+  state.enter(replayingEdits ? "edits" : "validation")
+
+  // Each attempt reads afresh, the subject included: a replay must observe the state that made the
+  // previous commit conflict, and fence the commit against that state alone.
+  const reads = new ActionReadRecorder()
+  let objectTarget: Awaited<ReturnType<typeof loadObjectTarget>>
+  try {
+    objectTarget = await loadObjectTarget({ runtime, action, run: state.run })
+  } catch (error) {
+    throw translateActionPhaseError(error, replayingEdits ? "edits" : "validation", {
+      ...ids,
+      signal,
+    })
+  }
+  const baseContext = createBasePhaseContext({
+    runtime,
+    action,
+    state,
+    logger: logSession.withContext({ phase: "validation" }),
+  })
+
+  if (!replayingEdits) {
+    try {
+      await untilAborted(
+        () =>
+          runActionValidators({
+            action,
+            subject: state.run.subject,
+            baseContext: { ...baseContext, signal },
+            target: isObjectActionDefinition(action) ? objectTarget?.snapshot : undefined,
+          }),
+        signal
+      )
+    } catch (error) {
+      throw translateActionPhaseError(error, "validation", { ...ids, signal })
+    }
+
+    throwIfAborted(signal)
+    await runWritebackPhase({
+      runtime,
+      action,
+      state,
+      signal,
+      baseContext: { ...baseContext, logger: logSession.withContext({ phase: "writeback" }) },
+      objectTarget,
+      reads,
+    })
+  }
+
+  // A succeeded writeback is the boundary: from here on, edits and commit always finish.
+  const editsSignal = hasSucceededWriteback(state) ? signals.uninterruptible : signal
+  throwIfAborted(editsSignal)
+  return runEditsAndCommitPhase({
+    runtime,
+    action,
+    state,
+    signal: editsSignal,
+    baseContext: { ...baseContext, logger: logSession.withContext({ phase: "edits" }) },
+    objectTarget,
+    reads,
+  })
+}
+
+function hasSucceededWriteback(state: ActionRunState): boolean {
+  return state.writeback?.status === "succeeded"
+}
+
+function isReadConflict(error: unknown): boolean {
+  return isSixbError(error) && error.code === "action.read_conflict"
+}