@defrex/autobuild 0.8.0 → 0.10.0

package/packages/core/src/kernel/incremental-contract.ts

@@ -0,0 +1,75 @@
+/**
+ * Test support for the incremental reducer contract. Imported only by tests.
+ */
+import { expect } from 'bun:test'
+import type { IncrementalReducer } from './incremental'
+
+export interface CheckOptions<State> {
+  /** Equality for the oracle comparison. Defaults to `toEqual`, which treats
+   * `undefined` and missing keys alike (the JSON round trip needs that). */
+  compare?: (actual: State, expected: State) => void
+  /** Also fold one event at a time. Default true. */
+  stepwise?: boolean
+}
+
+const roundTrip = <T>(value: T): T => JSON.parse(JSON.stringify(value)) as T
+
+/** Assert that for every split point `k`, advancing the accumulator of
+ * `log[0..k]` with `log[k..]` equals reducing the whole log — in memory and
+ * through a JSON round trip — and that `advance` never mutates its input. */
+export function checkIncremental<Acc, Event, State>(
+  reducer: IncrementalReducer<Acc, Event, State>,
+  log: readonly Event[],
+  options: CheckOptions<State> = {},
+): void {
+  const compare = options.compare ?? ((a, b) => expect(a).toEqual(b))
+  const oracle = reducer.reduce(log)
+  for (let k = 0; k <= log.length; k++) {
+    const prefix = reducer.advance(reducer.initial(), log.slice(0, k))
+    const before = structuredClone(prefix)
+    const earlier = reducer.finish(prefix)
+    const earlierSnapshot = structuredClone(earlier)
+    const suffix = log.slice(k)
+
+    const advanced = reducer.advance(prefix, suffix)
+    expect(prefix).toEqual(before)
+    compare(reducer.finish(advanced), oracle)
+    // Advancing later must not disturb a state derived earlier.
+    expect(earlier).toEqual(earlierSnapshot)
+
+    const revived = reducer.advance(roundTrip(prefix), suffix)
+    compare(reducer.finish(revived), oracle)
+    // A serialized finished accumulator must also revive to the same state.
+    compare(reducer.finish(roundTrip(advanced)), oracle)
+  }
+  if (options.stepwise ?? true) {
+    let acc = reducer.initial()
+    for (const event of log) acc = reducer.advance(acc, [event])
+    compare(reducer.finish(acc), oracle)
+  }
+}
+
+/** A small seeded PRNG (mulberry32) so generated logs reproduce from a seed. */
+export function seededRandom(seed: number): () => number {
+  let a = seed >>> 0
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0
+    let t = a
+    t = Math.imul(t ^ (t >>> 15), t | 1)
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61)
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+  }
+}
+
+export function pick<T>(rand: () => number, items: readonly T[]): T {
+  return items[Math.floor(rand() * items.length)] as T
+}
+
+export function shuffled<T>(rand: () => number, items: readonly T[]): T[] {
+  const out = [...items]
+  for (let i = out.length - 1; i > 0; i--) {
+    const j = Math.floor(rand() * (i + 1))
+    ;[out[i], out[j]] = [out[j] as T, out[i] as T]
+  }
+  return out
+}

package/packages/core/src/kernel/incremental-fixtures.ts

@@ -0,0 +1,211 @@
+/**
+ * Test support for the incremental-reducer property tests of the small
+ * selector projections: build and repository event generators drawn from
+ * small value pools (so correlations happen), seeded, and shuffled to prove
+ * the carried state reproduces the whole-array result for any array order.
+ * Imported only by tests. Events are cast, not validated: the projections
+ * under test read only the fields the generators set.
+ */
+import type { AbEvent } from '../events/catalog'
+import { KERNEL } from '../events/envelope'
+import type { RepositoryEvent } from '../events/repository'
+import { expect } from 'bun:test'
+import { checkIncremental, pick, seededRandom, shuffled } from './incremental-contract'
+import type { IncrementalReducer } from './incremental'
+
+export type Rand = () => number
+
+export function buildLog(
+  items: ReadonlyArray<readonly [string, Record<string, unknown>]>,
+): AbEvent[] {
+  return items.map(
+    ([type, payload], index) =>
+      ({
+        build: 'b',
+        seq: index + 1,
+        ts: new Date(Date.UTC(2026, 0, 1, 0, 0, index)).toISOString(),
+        actor: KERNEL,
+        type,
+        payload,
+      }) as unknown as AbEvent,
+  )
+}
+
+export function repoLog(
+  items: ReadonlyArray<readonly [string, Record<string, unknown>]>,
+): RepositoryEvent[] {
+  return items.map(
+    ([type, payload], index) =>
+      ({
+        repo: 'r',
+        seq: index + 1,
+        ts: new Date(Date.UTC(2026, 0, 1, 0, 0, index)).toISOString(),
+        actor: KERNEL,
+        type,
+        payload,
+      }) as unknown as RepositoryEvent,
+  )
+}
+
+/** For each seed: an ordered log and two shuffled copies of it (seq is
+ * assigned before shuffling, so shuffled arrays carry out-of-order seqs). */
+export function generatedLogs<E>(
+  make: (items: ReadonlyArray<readonly [string, Record<string, unknown>]>) => E[],
+  item: (rand: Rand) => readonly [string, Record<string, unknown>],
+  seeds: readonly number[] = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+): E[][] {
+  const out: E[][] = []
+  for (const seed of seeds) {
+    const rand = seededRandom(seed)
+    const length = 4 + Math.floor(rand() * 16)
+    const ordered = make(Array.from({ length }, () => item(rand)))
+    out.push(ordered, shuffled(rand, ordered), shuffled(rand, ordered))
+  }
+  return out
+}
+
+/** A random build event of the kinds the process-layer selectors read. */
+export function randomBuildItem(rand: Rand): readonly [string, Record<string, unknown>] {
+  const instance = pick(rand, ['i1', 'i2'])
+  const attempt = 1 + Math.floor(rand() * 3)
+  const id = pick(rand, ['e1', 'e2', 'e3'])
+  const sha = pick(rand, ['s1', 's2', 's3', 's4'])
+  const ref = pick(rand, ['/ws/a', '/ws/b'])
+  const marker = pick(rand, [
+    'auto-merge-gate:pr:7:command:1',
+    'auto-merge-gate:pr:7:command:2',
+    'other',
+  ])
+  const assets = () =>
+    rand() < 0.3
+      ? undefined
+      : [
+          { kind: 'doc', name: pick(rand, ['a', 'b']), revision: 1 + Math.floor(rand() * 3) },
+          ...(rand() < 0.5 ? [{ kind: 'img', name: 'c', revision: 1 }] : []),
+        ]
+  const templates: Array<() => readonly [string, Record<string, unknown>]> = [
+    () => ['build.created', { baseBranch: pick(rand, ['main', 'dev']), assets: assets() }],
+    () => ['spec.revised', { artifact: { kind: 'spec', rev: 1 }, escalation: 1, assets: assets() }],
+    () => [
+      'execution.started',
+      {
+        provider: 'p',
+        workspaceRef: ref,
+        instance,
+        ...(rand() < 0.5 ? { environmentId: 'env' } : {}),
+        ...(rand() < 0.5 ? { sessionId: 'sess' } : {}),
+        ...(rand() < 0.5 ? { commandId: 'cmd' } : {}),
+      },
+    ],
+    () => [
+      'execution.ended',
+      { instance, workspaceRef: ref, outcome: pick(rand, ['completed', 'stopped', 'lost']) },
+    ],
+    () => [
+      'workspace.provisioned',
+      {
+        provider: 'p',
+        ref,
+        ...(rand() < 0.5 ? { path: '/p' } : {}),
+        branch: 'ab/x',
+        base: { source: 'remote', sha },
+      },
+    ],
+    () => ['workspace.released', {}],
+    () => ['workspace.provision-started', { provider: 'p', branch: 'ab/x', generation: attempt }],
+    () => ['implement.completed', { round: 1, commits: { base: 'b', head: sha }, artifact: {} }],
+    () => ['reconcile.started', { attempt, baseSha: sha }],
+    () => ['reconcile.completed', { mergeCommit: sha, artifact: {} }],
+    () => [
+      'finalize.step-completed',
+      { step: 'n', ok: rand() < 0.7, ...(rand() < 0.7 ? { headSha: sha } : {}) },
+    ],
+    () => ['finalize.completed', { pr: { number: 7, url: 'u', headSha: sha } }],
+    () => ['pr.merged', { sha }],
+    () => ['pr.closed', {}],
+    () => ['runner.attached', { instance, host: 'h' }],
+    () => ['runner.setup-failed', { command: 'c', attempt, exitStatus: 1, output: '' }],
+    () => [
+      'escalation.raised',
+      {
+        id,
+        phase: pick(rand, ['setup', 'plan', 'implement', 'verify:unit']),
+        source: pick(rand, ['policy', 'agent']),
+        ...(rand() < 0.7
+          ? { policyCause: pick(rand, ['infrastructure-failure-limit', 'setup-failure-limit']) }
+          : {}),
+        ...(rand() < 0.5 ? { round: 1 } : {}),
+        question: 'q',
+      },
+    ],
+    () => [
+      'escalation.answered',
+      { id, answer: 'a', resolution: pick(rand, ['retry', 'guidance', 'abort']) },
+    ],
+    () => [
+      'phase.failed',
+      {
+        phase: pick(rand, ['plan', 'implement']),
+        round: 1 + Math.floor(rand() * 2),
+        attempt,
+        error: `err${attempt}`,
+        willRetry: rand() < 0.5,
+        ...(rand() < 0.5 ? { providerAttempts: [{ index: 1, runner: 'r', error: 'e' }] } : {}),
+      },
+    ],
+    () => ['observation.recorded', { id: 'o', kind: 'followup', summary: 's', refs: [marker] }],
+    () => ['observation.recorded', { id: 'o2', kind: 'refactor', summary: 's' }],
+    () => ['session.started', { session: 's', role: 'r', runner: 'c', phase: 'plan' }],
+  ]
+  return pick(rand, templates)()
+}
+
+/** A random repository-journal event of the kinds the repo selectors read. */
+export function randomRepoItem(rand: Rand): readonly [string, Record<string, unknown>] {
+  const execution = pick(rand, ['x1', 'x2', 'x3'])
+  const run = pick(rand, ['r1', 'r2'])
+  const templates: Array<() => readonly [string, Record<string, unknown>]> = [
+    () => [
+      'harvest.execution.started',
+      {
+        execution,
+        provider: 'p',
+        environmentId: 'env',
+        ...(rand() < 0.5 ? { sessionId: 'sess' } : {}),
+        ...(rand() < 0.5 ? { commandId: 'cmd' } : {}),
+      },
+    ],
+    () => [
+      'harvest.execution.released',
+      { execution, environmentId: 'env', snapshots: { outcome: 'confirmed' } },
+    ],
+    () => ['dispatcher.tick-started', { run }],
+    () => ['dispatcher.tick-completed', { run, queued: 0 }],
+    () => ['dispatcher.tick-failed', { run, error: 'x' }],
+    () => ['dispatcher.tick-yielded', { holder: 'h' }],
+    () => ['dispatcher.operator-reported', { run, level: 'info', message: 'm' }],
+    () => ['dispatcher.auto-merge-default-set', { enabled: rand() < 0.5 }],
+    () => ['dispatcher.intake-set', { enabled: rand() < 0.5 }],
+  ]
+  return pick(rand, templates)()
+}
+
+/** Run the incremental contract over every log, and hold the result to an
+ * independent reference implementation of the original whole-array function. */
+export function checkAgainstReference<Acc, Event, State>(
+  reducer: IncrementalReducer<Acc, Event, State>,
+  logs: readonly (readonly Event[])[],
+  reference: (events: readonly Event[]) => State,
+  normalize: (state: State) => unknown = (state) => state,
+): void {
+  for (const log of logs) {
+    const expected = normalize(reference(log))
+    expect(normalize(reducer.reduce(log))).toEqual(expected)
+    checkIncremental(reducer, log, {
+      compare: (actual, oracle) => {
+        expect(normalize(actual)).toEqual(normalize(oracle))
+        expect(normalize(actual)).toEqual(expected)
+      },
+    })
+  }
+}

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

@@ -0,0 +1,53 @@
+/**
+ * The incremental reducer contract: every projection of an event array is a
+ * fold plus a final derivation, so its state can be advanced from a previously
+ * computed accumulator using only the events newer than it (CLAUDE.md rule 2 —
+ * state is a reduction of the log, and any carried accumulator is a cache).
+ *
+ * The accumulator is plain JSON (no `Map`, `Set`, or class instances), so it
+ * survives `JSON.parse(JSON.stringify(acc))` and can be stored and resumed.
+ */
+
+export interface IncrementalReducer<Acc, Event, State> {
+  /** Bump when `Acc`'s shape or the fold's semantics change: a cached
+   * accumulator is only valid for the version that wrote it. */
+  readonly version: number
+  /** The accumulator for an empty log. */
+  initial(): Acc
+  /** Fold events newer than `acc` into a copy of it. Never mutates `acc`. */
+  advance(acc: Acc, events: readonly Event[]): Acc
+  /** Derive the public state. Returns fresh top-level objects. */
+  finish(acc: Acc): State
+  /** The whole-array form: `finish(advance(initial(), events))` without the
+   * clone. */
+  reduce(events: readonly Event[]): State
+}
+
+export function cloneAcc<T>(acc: T): T {
+  return structuredClone(acc)
+}
+
+/** Derive `advance` (clone, then fold in place) and `reduce` from an in-place
+ * `fold`. */
+export function defineReducer<Acc, Event, State>(def: {
+  version: number
+  initial: () => Acc
+  fold: (acc: Acc, events: readonly Event[]) => void
+  finish: (acc: Acc) => State
+}): IncrementalReducer<Acc, Event, State> {
+  return {
+    version: def.version,
+    initial: def.initial,
+    advance(acc, events) {
+      const next = cloneAcc(acc)
+      def.fold(next, events)
+      return next
+    },
+    finish: def.finish,
+    reduce(events) {
+      const acc = def.initial()
+      def.fold(acc, events)
+      return def.finish(acc)
+    },
+  }
+}