@defrex/autobuild 0.8.0

package/packages/core/src/processes/execution-settlement.ts

@@ -0,0 +1,171 @@
+/**
+ * Settlement of foreign build executions from durable facts plus provider
+ * liveness (AUT-301). Today's completion handling hangs off the in-memory
+ * `handle.completion` promise of the process that launched the runner; when
+ * that process dies, nothing writes `execution.ended`, releases the lease, or
+ * settles publication. These helpers let any dispatcher tick re-derive the
+ * same decisions from the event log and one bounded provider observation —
+ * mirroring the engine, which is already a pure function over the log.
+ *
+ * Conservatism rule: an observation that cannot be resolved (provider error)
+ * is treated as `running`. Supervision decisions reap or settle only on
+ * provider proof, never on an unknown.
+ */
+import { DISPATCHER } from '../events/envelope'
+import type { AbEvent, EventWrite } from '../events/catalog'
+import type {
+  BuildExecution,
+  BuildExecutionIdentity,
+  ExecutionObservation,
+} from '../ports/workspace/build-execution'
+import type { BuildStore } from '../store/types'
+
+/** The latest `execution.started` not followed by an instance-matched
+ * `execution.ended`, or null when no execution is open. */
+export function openExecution(events: AbEvent[]): {
+  instance: string
+  workspaceRef: string
+  provider: string
+  environmentId?: string
+  sessionId?: string
+  commandId?: string
+} | null {
+  let open: {
+    instance: string
+    workspaceRef: string
+    provider: string
+    environmentId?: string
+    sessionId?: string
+    commandId?: string
+  } | null = null
+  for (const event of events) {
+    if (event.type === 'execution.started') {
+      const payload = event.payload
+      open = {
+        instance: payload.instance,
+        workspaceRef: payload.workspaceRef,
+        provider: payload.provider,
+        ...(payload.environmentId !== undefined ? { environmentId: payload.environmentId } : {}),
+        ...(payload.sessionId !== undefined ? { sessionId: payload.sessionId } : {}),
+        ...(payload.commandId !== undefined ? { commandId: payload.commandId } : {}),
+      }
+    } else if (event.type === 'execution.ended' && open !== null) {
+      if (event.payload.instance === open.instance) open = null
+    }
+  }
+  return open
+}
+
+/** The lifecycle state of the latest recorded execution: `open` (no matching
+ * end yet), `completed`/`stopped`/`lost` (its recorded end), or `none`. */
+export function lastExecutionOutcome(
+  events: AbEvent[],
+): 'open' | 'completed' | 'stopped' | 'lost' | 'none' {
+  let state: 'open' | 'completed' | 'stopped' | 'lost' | 'none' = 'none'
+  for (const event of events) {
+    if (event.type === 'execution.started') {
+      state = 'open'
+    } else if (event.type === 'execution.ended' && state === 'open') {
+      state = event.payload.outcome
+    }
+  }
+  return state
+}
+
+function observationIdentity(open: {
+  instance: string
+  workspaceRef: string
+  provider: string
+  environmentId?: string
+  sessionId?: string
+  commandId?: string
+}): BuildExecutionIdentity {
+  return {
+    provider: open.provider,
+    workspaceRef: open.workspaceRef,
+    ...(open.environmentId !== undefined ? { environmentId: open.environmentId } : {}),
+    ...(open.sessionId !== undefined ? { sessionId: open.sessionId } : {}),
+    ...(open.commandId !== undefined ? { commandId: open.commandId } : {}),
+  }
+}
+
+/** Durable settlement outcome for one foreign open execution. `settled` means
+ * a recorded completion was written and publication was settled; `lost` means
+ * the provider proved the execution gone without an exit code (publication is
+ * deliberately left to the existing abandonment flow); `running` means the
+ * guest is alive or unknowable — no writes. */
+export type ExecutionSettlement = 'running' | 'settled' | 'lost'
+
+export interface ExecutionSettlementDeps {
+  store: BuildStore
+  /** The observing provider's executor. Settlement requires the `observe`
+   * capability; without it the caller supervises as before. */
+  execution: BuildExecution
+  /** Trusted publication settlement, invoked only after a recorded completion. */
+  settlePublication?: (slug: string) => Promise<void>
+}
+
+/** Release the open execution's exact lease, but only while that instance
+ * still holds it — a renewed runner lease under a different instance is never
+ * touched. */
+async function releaseSettledLease(
+  store: BuildStore,
+  slug: string,
+  instance: string,
+): Promise<void> {
+  const record = await store.getBuild(slug)
+  if (record?.lease !== undefined && record.lease.holder === instance) {
+    await store.releaseLease(slug, instance)
+  }
+}
+
+/**
+ * Observe one foreign open execution and settle it from the observation.
+ * Observation errors are contained and read as `running` (conservative: never
+ * reap on an unknown); the next tick retries.
+ */
+export async function settleExecution(
+  deps: ExecutionSettlementDeps,
+  slug: string,
+  events: AbEvent[],
+): Promise<ExecutionSettlement> {
+  const open = openExecution(events)
+  if (open === null) return 'settled'
+  if (open.commandId === undefined || deps.execution.observe === undefined) return 'running'
+  let observation: ExecutionObservation
+  try {
+    observation = await deps.execution.observe(observationIdentity(open))
+  } catch {
+    return 'running'
+  }
+  if (observation.state === 'running') return 'running'
+
+  const ended: EventWrite<'execution.ended'> =
+    observation.state === 'ended'
+      ? {
+          actor: DISPATCHER,
+          type: 'execution.ended',
+          payload: {
+            instance: open.instance,
+            workspaceRef: open.workspaceRef,
+            outcome: 'completed',
+            exitCode: observation.exitCode ?? null,
+          },
+        }
+      : {
+          actor: DISPATCHER,
+          type: 'execution.ended',
+          payload: {
+            instance: open.instance,
+            workspaceRef: open.workspaceRef,
+            outcome: 'lost',
+          },
+        }
+  await deps.store.append(slug, ended)
+  await releaseSettledLease(deps.store, slug, open.instance)
+  if (observation.state === 'ended') {
+    await deps.settlePublication?.(slug)
+    return 'settled'
+  }
+  return 'lost'
+}

package/packages/core/src/processes/harvest-child.ts

@@ -0,0 +1,115 @@
+/**
+ * Crash-safe repository-scoped harvest workflow: scan -> synthesize <-> review
+ * -> file. It reuses `converge` for adversarial review semantics while every
+ * durable boundary lives in the repository journal, so a replacement process
+ * resumes the claimed snapshot rather than starting a duplicate run.
+ */
+import { join } from 'node:path'
+import { loadConfig } from '../config/load'
+import type { HarvestExecutionEnvironment } from '../ports/workspace/harvest-execution'
+import type { HarvestRunnerLaunch } from '../ports/workspace/harvest-execution'
+import { loadPlugins } from '../plugins/load'
+import { materializePluginRuntimes } from '../plugins/runtimes'
+import { randomIds, randomUuids } from '../ids'
+import { createTicketSource } from '../ports/tickets/create'
+import { createProductionRuntimes } from '../ports/runner/production'
+import type { BuildStore } from '../store/types'
+import { systemClock } from '../store/types'
+import { openProductionStore, type StoreOpener } from '../cli/store-opening'
+import { resolveRepoStatePaths } from '../cli/repo-state'
+import { DEFAULT_MAX_HARVEST_RECOVERY_ATTEMPTS } from '../kernel/harvest'
+import { HarvestRunner } from './harvest-runner'
+
+export type { HarvestExecutionEnvironment }
+
+/** Guest-side ticket-source arguments, identical to what a local harvest in
+ * this checkout would pass: targetRepo is the physical guest checkout, and
+ * localStateRoot follows the same store-selection precedence rule the host's
+ * `resolveRepoStatePaths` applies (remote store → checkout-local `.autobuild`,
+ * local store → the resolved store ref). A relative or defaulted
+ * `[tickets].dir` therefore resolves identically on host and guest. */
+export function guestTicketSourceArgs(
+  input: HarvestRunnerLaunch,
+  workspacePath: string,
+): { targetRepo: string; localStateRoot: string } {
+  const paths = resolveRepoStatePaths({
+    repo: input.repo,
+    checkout: workspacePath,
+    storeRef: input.storeRef,
+  })
+  return { targetRepo: paths.checkout, localStateRoot: paths.localStateRoot }
+}
+
+/** Guest-side composition. The launch envelope supplies identity, lease
+ * adoption, and environment provenance only; configuration comes from the
+ * guest checkout and the hosted Store/ticket authority from the forwarded
+ * environment — the same kernel class a local harvest runs, so filed
+ * proposals, creation keys, and idempotency are byte-identical. Ticket-source
+ * composition likewise matches a local harvest in this checkout: a relative
+ * or defaulted `[tickets].dir` resolves against the guest checkout and the
+ * selected local state root (see `guestTicketSourceArgs`). */
+export async function runHarvestChild(
+  input: HarvestRunnerLaunch,
+  env: Record<string, string | undefined> = process.env,
+  openStore: StoreOpener = openProductionStore,
+  /** Guest checkout root. The provider launches the runner with this as cwd. */
+  workspacePath: string = process.cwd(),
+): Promise<void> {
+  const fullStore: BuildStore = openStore(input.storeRef, env.AB_TOKEN)
+  try {
+    const config = await loadConfig(join(workspacePath, 'autobuild.toml'))
+    // Full build-child composition parity, in the same order: plugins load
+    // first or materializePluginRuntimes silently no-ops and leaves any
+    // plugin-provided runtime unrouted in the guest.
+    const plugins = await loadPlugins(config.plugins, workspacePath, {
+      packageRoot: input.repo,
+    })
+    const { runtimes: builtins } = createProductionRuntimes()
+    const runtimes = await materializePluginRuntimes(builtins, plugins, {
+      repoRoot: workspacePath,
+      env,
+    })
+    // Ticket-source composition matches a local harvest in this checkout: a
+    // relative or defaulted [tickets].dir resolves against the guest checkout
+    // and the selected local state root, never the host-side repo identity.
+    const { targetRepo, localStateRoot } = guestTicketSourceArgs(input, workspacePath)
+    const tickets = await createTicketSource(
+      config.tickets,
+      env,
+      targetRepo,
+      localStateRoot,
+      plugins,
+    )
+
+    const runner = new HarvestRunner({
+      store: fullStore,
+      tickets,
+      config,
+      runtimes,
+      repo: input.repo,
+      workspacePath,
+      ids: randomIds(),
+      uuids: randomUuids(),
+      clock: systemClock,
+      instance: input.instance,
+      // Adopted holder: the guest skips its own claim, heartbeats the owning
+      // dispatch loop's repository lease, and never releases it.
+      ...(input.leaseHolder !== undefined ? { leaseHolder: input.leaseHolder } : {}),
+      ...(input.environment !== undefined ? { environment: input.environment } : {}),
+      sessionEnv: {
+        AB_STORE: input.storeRef,
+        ...(env.AB_TOKEN !== undefined && env.AB_TOKEN !== '' ? { AB_TOKEN: env.AB_TOKEN } : {}),
+      },
+      opts: {
+        maxRecoveryAttempts: DEFAULT_MAX_HARVEST_RECOVERY_ATTEMPTS,
+      },
+    })
+    await runner.run()
+  } finally {
+    try {
+      await fullStore.close()
+    } catch {
+      // Process teardown cannot change the already-durable runner outcome.
+    }
+  }
+}

package/packages/core/src/processes/harvest-execution-state.ts

@@ -0,0 +1,121 @@
+/**
+ * Durable harvest execution state: the repository-journal projection that
+ * hosted-harvest supervision (AUT-305) reads instead of process memory. The
+ * launch/close facts (`harvest.execution.started`/`.released`) bracket one
+ * disposable environment; the run's own facts decide the outcome. Every
+ * helper here is a pure function over the journal, mirroring the build
+ * execution settlement, so any dispatcher invocation can settle a run whose
+ * supervisor died.
+ */
+import type { RepositoryEvent } from '../events/repository'
+import {
+  DEFAULT_MAX_HARVEST_RECOVERY_ATTEMPTS,
+  actionableHarvestRun,
+  decideHarvestControl,
+  reduceHarvest,
+} from '../kernel/harvest'
+import type { HarvestRunnerResult } from './harvest-runner'
+
+/** Open harvest executions: every `harvest.execution.started` not followed by
+ * a matching `harvest.execution.released`, in journal order. */
+export function openHarvestExecutions(events: readonly RepositoryEvent[]): Array<{
+  execution: string
+  provider: string
+  environmentId: string
+  sessionId?: string
+  commandId?: string
+  seq: number
+}> {
+  const open = new Map<
+    string,
+    {
+      execution: string
+      provider: string
+      environmentId: string
+      sessionId?: string
+      commandId?: string
+      seq: number
+    }
+  >()
+  for (const event of events) {
+    if (event.type === 'harvest.execution.started') {
+      open.set(event.payload.execution, {
+        execution: event.payload.execution,
+        provider: event.payload.provider,
+        environmentId: event.payload.environmentId,
+        ...(event.payload.sessionId !== undefined ? { sessionId: event.payload.sessionId } : {}),
+        ...(event.payload.commandId !== undefined ? { commandId: event.payload.commandId } : {}),
+        seq: event.seq,
+      })
+    } else if (event.type === 'harvest.execution.released') {
+      open.delete(event.payload.execution)
+    }
+  }
+  return [...open.values()]
+}
+
+export interface HarvestExecutionClassificationInput {
+  /** Repo-journal seq of this execution's `harvest.execution.started` fact. */
+  executionStartedSeq: number
+  /** The repository-lease holder this execution adopted from the dispatch
+   * loop. Absent (local runner shape) makes the held check inapplicable. */
+  adoptedHolder?: string
+  /** The repository lease holder observed after the guest exited. */
+  leaseHolder?: string
+  maxRecoveryAttempts?: number
+}
+
+/** Classify one finished hosted harvest execution from the repository journal
+ * alone — the guest's exit code carries no pipeline outcome. The latest run's
+ * terminal fact wins (`completed`/`escalated`/unresolved `failed`) — but only
+ * when that terminal fact postdates this execution's start: a stale terminal
+ * fact was already counted and announced by the execution that produced it,
+ * and re-reporting it would double-count. Launch attribution is by whether
+ * the run started inside this execution; a run still open under a
+ * parked/paused control decision is `parked`; a lease held by someone else is
+ * `held`; anything else is `idle`. The result feeds the same counters a
+ * locally run harvest reports. */
+export function classifyHarvestOutcome(
+  events: readonly RepositoryEvent[],
+  input: HarvestExecutionClassificationInput,
+): HarvestRunnerResult {
+  const state = reduceHarvest(events)
+  const latestRun = state.runs.at(-1)
+  if (latestRun !== undefined) {
+    const launch = latestRun.startedSeq > input.executionStartedSeq ? 'started' : 'resumed'
+    // Recency gate: a terminal outcome counts only if its fact — the run's
+    // terminal fact, or for an unresolved failure the failure fact itself
+    // (`failureSeq`), which also covers exhaustion via `terminalSeq` —
+    // postdates this execution's `harvest.execution.started`.
+    const outcomeSeq = Math.max(latestRun.terminalSeq ?? 0, latestRun.failureSeq ?? 0)
+    if (outcomeSeq > input.executionStartedSeq) {
+      if (latestRun.status === 'completed') {
+        return { outcome: 'completed', launch, run: latestRun.run }
+      }
+      if (latestRun.status === 'escalated') {
+        return { outcome: 'escalated', launch, run: latestRun.run }
+      }
+      // An unresolved harvest.failed — including recovery exhaustion — is a
+      // durable stop, not an idle exit.
+      if (latestRun.failure !== undefined) {
+        return { outcome: 'failed', launch, run: latestRun.run }
+      }
+    }
+  }
+  const decision = decideHarvestControl(
+    state,
+    input.maxRecoveryAttempts ?? DEFAULT_MAX_HARVEST_RECOVERY_ATTEMPTS,
+  )
+  if (decision.kind === 'park') {
+    const run = actionableHarvestRun(state)?.run
+    return run === undefined ? { outcome: 'parked' } : { outcome: 'parked', run }
+  }
+  if (
+    input.adoptedHolder !== undefined &&
+    input.leaseHolder !== undefined &&
+    input.leaseHolder !== input.adoptedHolder
+  ) {
+    return { outcome: 'held' }
+  }
+  return { outcome: 'idle' }
+}