@defrex/autobuild 0.8.0

package/packages/core/src/kernel/auto-merge.ts

@@ -0,0 +1,259 @@
+import type { AbEvent, EventEnvelope, EventWrite } from '../events/catalog'
+import { KERNEL } from '../events/envelope'
+import { autoMergeDeferralClasses, type AutoMergeDeferralReason } from '../ports/types'
+import type { BuildStore } from '../store/types'
+import type { BuildState } from './reducer'
+
+/** The complete GitHub `mergeStateStatus` enum. Keeping this list closed is a
+ * safety property: a future forge state cannot silently become direct-merge
+ * eligible. */
+export const mergeStateStatuses = [
+  'BEHIND',
+  'BLOCKED',
+  'CLEAN',
+  'DIRTY',
+  'DRAFT',
+  'HAS_HOOKS',
+  'UNKNOWN',
+  'UNSTABLE',
+] as const
+
+export type MergeStateStatus = (typeof mergeStateStatuses)[number]
+export type MergeGatePresence = 'present' | 'absent'
+
+export type AutoMergeEnableDisposition =
+  | { kind: 'native' }
+  | { kind: 'direct' }
+  | { kind: 'deferred' }
+  | { kind: 'error'; reason: string }
+
+const NATIVE = { kind: 'native' } as const
+const DIRECT = { kind: 'direct' } as const
+const DEFERRED = { kind: 'deferred' } as const
+
+/**
+ * Route from two independent facts: whether a real merge gate exists and the
+ * PR's current GitHub merge state. In particular, CLEAN never proves that a
+ * branch is ungated: a gated branch whose requirements passed is CLEAN too.
+ */
+const ENABLE_DISPOSITIONS = {
+  BEHIND: { present: NATIVE, absent: DIRECT },
+  BLOCKED: {
+    present: NATIVE,
+    absent: {
+      kind: 'error',
+      reason: 'GitHub reports the PR BLOCKED despite no discovered merge-blocking gate',
+    },
+  },
+  CLEAN: { present: NATIVE, absent: DIRECT },
+  DIRTY: { present: DEFERRED, absent: DEFERRED },
+  DRAFT: {
+    present: {
+      kind: 'error',
+      reason: 'GitHub reports the PR as DRAFT; Autobuild only finalizes ready PRs',
+    },
+    absent: {
+      kind: 'error',
+      reason: 'GitHub reports the PR as DRAFT; Autobuild only finalizes ready PRs',
+    },
+  },
+  HAS_HOOKS: { present: NATIVE, absent: NATIVE },
+  UNKNOWN: { present: NATIVE, absent: DEFERRED },
+  UNSTABLE: { present: NATIVE, absent: DIRECT },
+} as const satisfies Record<MergeStateStatus, Record<MergeGatePresence, AutoMergeEnableDisposition>>
+
+export function classifyAutoMergeEnable(
+  mergeState: MergeStateStatus,
+  gate: MergeGatePresence,
+): AutoMergeEnableDisposition {
+  return ENABLE_DISPOSITIONS[mergeState][gate]
+}
+
+/** A human auto-merge command whose desired forge state has not yet been
+ * acknowledged by a matching application fact. */
+export interface PendingAutoMerge {
+  enabled: boolean
+  commandSeq: number
+}
+
+/**
+ * Compare durable desired state with the correlated forge application fact.
+ * A value mismatch OR a command-seq mismatch is pending. This is the recovery
+ * predicate at both plumbing seams: retries are safe because Forge.setAutoMerge
+ * is idempotent.
+ */
+export function pendingAutoMerge(
+  state: Pick<BuildState, 'autoMerge'>,
+): PendingAutoMerge | undefined {
+  const { requested, commandSeq, applied } = state.autoMerge
+  if (commandSeq === undefined) return undefined
+  if (applied?.commandSeq === commandSeq && applied.enabled === requested) {
+    return undefined
+  }
+  return { enabled: requested, commandSeq }
+}
+
+export function autoMergeApplicationType(
+  enabled: boolean,
+): 'pr.auto-merge-enabled' | 'pr.auto-merge-disabled' {
+  return enabled ? 'pr.auto-merge-enabled' : 'pr.auto-merge-disabled'
+}
+
+/** Stable correlation key for the one follow-up allowed per PR/consent command. */
+export function autoMergeDeferralRef(prNumber: number, commandSeq: number): string {
+  return `auto-merge-gate:pr:${prNumber}:command:${commandSeq}`
+}
+
+/**
+ * The one live deferral observation for a PR/consent command, or undefined.
+ * An observation is current only while the PR is open — any `pr.merged` or
+ * `pr.closed` fact in the log ends it — and until later evidence proves the
+ * PR head changed, superseding the recorded condition until the gate
+ * re-examines consent and records a fresh observation. Head-changing evidence
+ * is a `reconcile.completed` (the resolution is a merge commit on the branch)
+ * or a `finalize.completed` whose head differs from the head the observation
+ * was recorded under. The dedupe and the projection share this predicate, so
+ * a stale observation stops suppressing and re-recording after reconcile
+ * works.
+ *
+ * The head at observation time is the newest `finalize.completed` before it:
+ * the record seam always runs right after that event is appended. An
+ * observation with no preceding `finalize.completed` (janitor-recorded seeds,
+ * synthetic logs) takes its head from the FIRST following `finalize.completed`
+ * instead of being superseded by it — the §8.7 retry that adopts the same PR
+ * at the same head must not invalidate the marker it honors. A
+ * `finalize.completed` naming a different head is a rebuilt pipeline
+ * re-finalizing after new commits, and it does make the observation stale.
+ *
+ * Ending currency on any terminal PR fact in the log is safe only because a
+ * build finalizes one PR; if a future feature ever re-finalizes onto a second
+ * PR, revisit.
+ */
+export function currentDeferralObservation(
+  events: AbEvent[],
+  prNumber: number,
+  commandSeq: number,
+): Extract<AbEvent, { type: 'observation.recorded' }> | undefined {
+  const marker = autoMergeDeferralRef(prNumber, commandSeq)
+  let observation: Extract<AbEvent, { type: 'observation.recorded' }> | undefined
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const event = events[index]
+    if (
+      event !== undefined &&
+      event.type === 'observation.recorded' &&
+      event.payload.refs?.includes(marker) === true
+    ) {
+      observation = event
+      break
+    }
+  }
+  if (observation === undefined) return undefined
+
+  let headAtObservation: string | undefined
+  for (const event of events) {
+    if (event.seq >= observation.seq) break
+    if (event.type === 'finalize.completed') headAtObservation = event.payload.pr.headSha
+  }
+
+  for (const event of events) {
+    if (event.seq <= observation.seq) continue
+    if (event.type === 'pr.merged' || event.type === 'pr.closed') return undefined
+    if (event.type === 'reconcile.completed') return undefined
+    if (event.type === 'finalize.completed') {
+      if (headAtObservation === undefined) headAtObservation = event.payload.pr.headSha
+      else if (event.payload.pr.headSha !== headAtObservation) return undefined
+    }
+  }
+  return observation
+}
+
+export function hasAutoMergeDeferralObservation(
+  events: AbEvent[],
+  prNumber: number,
+  commandSeq: number,
+): boolean {
+  return currentDeferralObservation(events, prNumber, commandSeq) !== undefined
+}
+
+/**
+ * The exact provider-bearing summary for the current, unapplied enable
+ * command. Deferral observations are durable history, so correlation to both
+ * the current PR and command is what prevents an old reason from looking live
+ * after consent is applied, cancelled, or replaced — and the shared currency
+ * predicate is what keeps a superseded or terminal-PR observation from
+ * looking live at all.
+ */
+export function currentAutoMergeDeferral(
+  events: AbEvent[],
+  state: Pick<BuildState, 'autoMerge' | 'pr'>,
+): string | undefined {
+  const pending = pendingAutoMerge(state)
+  if (pending?.enabled !== true || state.pr === undefined) return undefined
+  return currentDeferralObservation(events, state.pr.number, pending.commandSeq)?.payload.summary
+}
+
+const DEFERRAL_SUMMARIES = {
+  'github-plan-limitation':
+    'GitHub rulesets are unavailable because of the repository account plan',
+  'repository-auto-merge-disabled': 'repository-level auto-merge is disabled',
+  'unproven-gate-state': 'merge-gate state or native auto-merge application could not be proven',
+  'merge-conflicts': 'the PR has merge conflicts with its base branch',
+  'mergeability-uncomputed':
+    'GitHub has not finished computing mergeability (transient; expected to resolve on retry)',
+  'local-base-checkout-dirty': 'local merge is blocked by uncommitted work in the base checkout',
+  'local-git-identity-missing':
+    'local squash requires a configured Git author and committer identity',
+} as const satisfies Record<AutoMergeDeferralReason['code'], string>
+
+/** Kernel-authored durable diagnostic for a human-actionable declined consent. */
+export function autoMergeDeferralObservation(
+  reason: AutoMergeDeferralReason,
+  prNumber: number,
+  commandSeq: number,
+  id: string,
+): EventWrite<'observation.recorded'> {
+  return {
+    actor: KERNEL,
+    type: 'observation.recorded',
+    payload: {
+      id,
+      kind: 'followup',
+      summary:
+        `Auto-merge gate could not apply consent for PR #${prNumber}: ` +
+        `${DEFERRAL_SUMMARIES[reason.code]} — ${reason.detail}`,
+      refs: [autoMergeDeferralRef(prNumber, commandSeq)],
+    },
+  }
+}
+
+/**
+ * Record the one durable diagnostic allowed for a PR/auto-merge command —
+ * only for a deferral a person must fix. Pipeline-owned and transient codes
+ * (`merge-conflicts`, `mergeability-uncomputed`) resolve through reconcile or
+ * a later poll, so they record nothing: consent stays pending and later ticks
+ * re-examine it. Every comparison is against the authoritative stream tail. A
+ * concurrent unrelated append merely causes a retry; a concurrent matching
+ * append makes the next read return without writing a duplicate.
+ */
+export async function recordAutoMergeDeferralObservation(
+  store: BuildStore,
+  slug: string,
+  reason: AutoMergeDeferralReason,
+  prNumber: number,
+  commandSeq: number,
+  id: string,
+): Promise<EventEnvelope<'observation.recorded'> | null> {
+  if (autoMergeDeferralClasses[reason.code] === 'pipeline-resolved') return null
+  while (true) {
+    const events = await store.getEvents(slug)
+    if (hasAutoMergeDeferralObservation(events, prNumber, commandSeq)) return null
+
+    const expectedSeq = events.at(-1)?.seq ?? 0
+    const appended = await store.appendIfCurrent(
+      slug,
+      expectedSeq,
+      autoMergeDeferralObservation(reason, prNumber, commandSeq, id),
+    )
+    if (appended !== null) return appended
+  }
+}

package/packages/core/src/kernel/converge.ts

@@ -0,0 +1,117 @@
+/**
+ * The generic review-loop primitive (SPEC §10): one tested state machine for
+ * both the plan loop and the code loop. It owns rounds, feedback threading,
+ * verdict routing, and the stall/policy thresholds — and nothing else: the
+ * callbacks own all I/O (sessions, store deposits, plumbing), so this module
+ * never touches a port or the store.
+ *
+ * Memory model (§10): the producer continues its session across rounds — its
+ * feedback is only the latest verdict's finding ids, assembled
+ * deterministically. The reviewer is a fresh skeptic each round and receives
+ * ALL prior rounds' findings so it can mark `persists` (§15.4).
+ *
+ * Findings are opaque here: ids are stamped at deposit (D6) before a verdict
+ * ever reaches this function, and converge never copies or mutates them —
+ * the same objects flow into `stalledChains` and back out in the outcome.
+ *
+ * Relationship to the engine: the MAINLINE loop is `decideLoop` inside
+ * `decideNext` (src/kernel/engine.ts) — the event-sourced re-statement of
+ * this primitive, because the kernel's resume path must re-decide from the
+ * log (§2.2) rather than hold a loop on the stack. converge remains the §10
+ * reference semantics for in-process callers, and the two implementations
+ * are pinned together by the differential suite in converge.test.ts
+ * ('converge ⇄ decideNext differential'): the same verdict scripts must
+ * produce the same rounds, feedback, and outcome in both. Edit loop
+ * semantics (thresholds, stall ordering, feedback assembly) in BOTH places
+ * or the differential fails.
+ */
+import type { Feedback, Finding, Verdict } from '../ontology'
+import { stalledChains, type FindingChain } from './stall'
+
+export interface ConvergePolicy {
+  /** Producer/review round pairs allowed before escalating (source: policy). */
+  maxRounds: number
+  /** Persistence-chain streak that auto-escalates (source: stall — §15.4). */
+  stallRounds: number
+}
+
+export type ConvergeOutcome<A> =
+  | { outcome: 'approved'; artifact: A; rounds: number }
+  | {
+      outcome: 'escalated'
+      source: 'agent' | 'stall' | 'policy'
+      reason: string
+      rounds: number
+      chain?: FindingChain
+    }
+
+export async function converge<A>(opts: {
+  produce: (feedback: Feedback | null, round: number) => Promise<A>
+  review: (artifact: A, round: number, priorRounds: Finding[][]) => Promise<Verdict>
+  /** Static policy for ordinary callers, or a boundary accessor for a
+   * long-running repository workflow that hot-reloads policy between rounds. */
+  policy: ConvergePolicy | (() => ConvergePolicy)
+  /** Chains a human already resolved via dismiss-finding (§15.6-B). */
+  dismissedIds?: ReadonlySet<string>
+  /** Durable callers may resume after prior revise rounds. Defaults preserve
+   * the ordinary in-memory loop (round 1, no history). */
+  startRound?: number
+  priorRounds?: Finding[][]
+  initialFeedback?: Feedback | null
+}): Promise<ConvergeOutcome<A>> {
+  const { produce, review, dismissedIds } = opts
+  const currentPolicy = (): ConvergePolicy =>
+    typeof opts.policy === 'function' ? opts.policy() : opts.policy
+  const roundFindings: Finding[][] = (opts.priorRounds ?? []).map((round) => [...round])
+  let feedback: Feedback | null = opts.initialFeedback ?? null
+
+  for (let round = opts.startRound ?? 1; ; round += 1) {
+    const openingPolicy = currentPolicy()
+    if (round > openingPolicy.maxRounds) {
+      return {
+        outcome: 'escalated',
+        source: 'policy',
+        reason: `maxRounds (${openingPolicy.maxRounds}) exhausted without approval`,
+        rounds: round - 1,
+      }
+    }
+
+    const artifact = await produce(feedback, round)
+    const verdict = await review(artifact, round, roundFindings.slice())
+
+    if (verdict.verdict === 'approve') {
+      return { outcome: 'approved', artifact, rounds: round }
+    }
+    if (verdict.verdict === 'escalate') {
+      return {
+        outcome: 'escalated',
+        source: 'agent',
+        reason: verdict.reason,
+        rounds: round,
+      }
+    }
+
+    roundFindings.push(verdict.findings)
+
+    // The kernel applies the stall threshold after every revise, BEFORE
+    // burning another produce round (§15.4). Deepest chain reported; first
+    // in root order on ties.
+    const stalled = stalledChains(roundFindings, currentPolicy().stallRounds, dismissedIds)
+    if (stalled.length > 0) {
+      const chain = stalled.reduce((deepest, candidate) =>
+        candidate.rounds > deepest.rounds ? candidate : deepest,
+      )
+      return {
+        outcome: 'escalated',
+        source: 'stall',
+        reason: `finding chain persisted ${chain.rounds} rounds: ${chain.ids.join(' -> ')}`,
+        rounds: round,
+        chain,
+      }
+    }
+
+    // Round N+1's producer prompt is assembled deterministically from finding
+    // ids (§10) — payloads carry refs, never blobs (§15.2.3).
+    feedback = { findings: verdict.findings.map((finding) => finding.id) }
+  }
+}

package/packages/core/src/kernel/dispatch-settings.ts

@@ -0,0 +1,60 @@
+/**
+ * Pure projection of repository-scoped dispatcher controls — the intake gate,
+ * the repository-wide pause, and the claim-time auto-merge default. The journal
+ * is authoritative; fresh repositories retain the historical process defaults.
+ */
+import type { RepositoryEvent } from '../events/repository'
+
+export const DEFAULT_DISPATCH_INTAKE = true
+export const DEFAULT_DISPATCH_PAUSED = false
+export const DEFAULT_DISPATCH_AUTO_MERGE = false
+
+export interface DispatchSettings {
+  intake: boolean
+  /**
+   * Repository-wide quiescence: while true, no queued build may be given a
+   * runner. Distinct from the per-build pause (a build-log fact with its own
+   * reducer precedence) and from `HarvestState.paused` (the observation
+   * workflow's own gate, which this does not govern).
+   */
+  paused: boolean
+  defaultAutoMerge: boolean
+}
+
+export function reduceDispatchSettings(events: RepositoryEvent[]): DispatchSettings {
+  let intake = DEFAULT_DISPATCH_INTAKE
+  let paused = DEFAULT_DISPATCH_PAUSED
+  let defaultAutoMerge = DEFAULT_DISPATCH_AUTO_MERGE
+  let intakeSeq = 0
+  let pausedSeq = 0
+  let autoMergeSeq = 0
+
+  for (const event of events) {
+    switch (event.type) {
+      case 'dispatcher.intake-set':
+        if (event.seq > intakeSeq) {
+          intake = event.payload.enabled
+          intakeSeq = event.seq
+        }
+        break
+      case 'dispatcher.pause-set':
+        if (event.seq > pausedSeq) {
+          paused = event.payload.enabled
+          pausedSeq = event.seq
+        }
+        break
+      case 'dispatcher.auto-merge-default-set':
+        if (event.seq > autoMergeSeq) {
+          defaultAutoMerge = event.payload.enabled
+          autoMergeSeq = event.seq
+        }
+        break
+      default:
+        // Harvest facts share this journal and have no dispatcher-setting
+        // meaning. Each setting is reduced independently.
+        break
+    }
+  }
+
+  return { intake, paused, defaultAutoMerge }
+}

package/packages/core/src/kernel/dispatch-status.ts

@@ -0,0 +1,141 @@
+import type { RepositoryEvent } from '../events/repository'
+import type { ArtifactRef } from '../ontology'
+
+export type DispatchHealth = 'starting' | 'running' | 'stopped' | 'failed'
+
+/** Store-only projection consumed by terminal (and future) frontends. */
+export interface DispatchStatus {
+  run: string
+  health: DispatchHealth
+  effectiveConfig?: ArtifactRef
+  queued?: number
+  /** Standing count from newer tick facts; absent for historical events. */
+  creationWithheld?: number
+  availableUpgrade?: string
+  roleWarnings: string[]
+  diagnostics: string[]
+  /** Latest notice of warning/failure severity, retained independently from routine notices. */
+  warningNotice?: string
+  notice?: string
+  lastSeq: number
+}
+
+function errorNotice(prefix: string, error: string): string {
+  return `${prefix}: ${error}`
+}
+
+/** Reduce one correlated dispatch run without consulting process-local state.
+ * An optional prior projection permits strictly newer repository deltas.
+ * Successful ticks supersede standing diagnostics; failures retain the last
+ * known queue/config values instead of fabricating replacements. */
+export function reduceDispatchStatus(
+  events: readonly RepositoryEvent[],
+  run: string,
+  previous?: Readonly<DispatchStatus>,
+): DispatchStatus {
+  if (previous !== undefined && previous.run !== run) {
+    throw new Error(`cannot continue dispatch run "${run}" from "${previous.run}" status`)
+  }
+  const state: DispatchStatus =
+    previous === undefined
+      ? {
+          run,
+          health: 'starting',
+          roleWarnings: [],
+          diagnostics: [],
+          lastSeq: 0,
+        }
+      : {
+          ...previous,
+          roleWarnings: [...previous.roleWarnings],
+          diagnostics: [...previous.diagnostics],
+        }
+  for (const event of events) {
+    if (event.seq <= state.lastSeq) continue
+    const payload = event.payload as { run?: string }
+    if (payload.run !== run) continue
+    state.lastSeq = event.seq
+    switch (event.type) {
+      case 'dispatcher.run-started':
+        state.health = 'running'
+        state.effectiveConfig = event.payload.effectiveConfig
+        state.roleWarnings = [...event.payload.roleWarnings]
+        state.notice = undefined
+        state.warningNotice = undefined
+        break
+      case 'dispatcher.config-reloaded':
+        if (event.payload.effectiveConfig !== undefined) {
+          state.effectiveConfig = event.payload.effectiveConfig
+        }
+        if (event.payload.roleWarnings !== undefined) {
+          state.roleWarnings = [...event.payload.roleWarnings]
+        }
+        state.notice =
+          event.payload.restartRequired.length > 0
+            ? `autobuild.toml reload requires dispatch restart for: ${event.payload.restartRequired.join(', ')}`
+            : 'autobuild.toml reloaded'
+        if (event.payload.restartRequired.length > 0) state.warningNotice = state.notice
+        break
+      case 'dispatcher.config-rejected':
+        state.notice = errorNotice('config reload rejected', event.payload.error)
+        state.warningNotice = state.notice
+        break
+      case 'dispatcher.config-publication-failed':
+        state.notice = errorNotice(
+          'config reload not applied because its durable trace failed',
+          event.payload.error,
+        )
+        state.warningNotice = state.notice
+        break
+      case 'dispatcher.tick-completed':
+        state.queued = event.payload.queued
+        state.creationWithheld = event.payload.counters.creationWithheld
+        state.diagnostics = [
+          ...event.payload.janitorDiagnostics,
+          ...event.payload.ticketDiagnostics,
+          ...(event.payload.creationDiagnostics ?? []),
+          ...event.payload.dependencyDiagnostics,
+        ]
+        break
+      case 'dispatcher.tick-failed':
+        state.notice = errorNotice('tick failed', event.payload.error)
+        state.warningNotice = state.notice
+        break
+      case 'dispatcher.runner-settled':
+        if (event.payload.outcome === 'parked') {
+          state.notice = `build ${event.payload.slug} parked (${event.payload.status ?? 'unknown'})`
+        } else if (event.payload.outcome === 'lease-held') {
+          state.notice = `build ${event.payload.slug} already held by another runner — skipped`
+        } else {
+          state.notice = `build ${event.payload.slug} runner failed: ${event.payload.error ?? event.payload.outcome}`
+        }
+        state.warningNotice = state.notice
+        break
+      case 'dispatcher.harvest-runner-failed':
+        state.notice = errorNotice('harvest runner failed', event.payload.error)
+        state.warningNotice = state.notice
+        break
+      case 'dispatcher.upgrade-available':
+        state.availableUpgrade = event.payload.version
+        break
+      case 'dispatcher.operator-reported':
+        state.notice = event.payload.message
+        if (event.payload.level === 'warning') state.warningNotice = state.notice
+        break
+      case 'dispatcher.run-stopped':
+        state.health = event.payload.outcome === 'normal' ? 'stopped' : 'failed'
+        if (event.payload.outcome !== 'normal') {
+          state.notice = `dispatcher stopped unexpectedly${
+            event.payload.error !== undefined ? `: ${event.payload.error}` : ''
+          }`
+          state.warningNotice = state.notice
+        } else if (event.payload.reason === 'superseded') {
+          state.notice = 'dispatcher superseded by another invocation'
+        }
+        break
+      default:
+        break
+    }
+  }
+  return state
+}