@defrex/autobuild 0.9.0 → 0.10.0

package/packages/core/src/cli/ticket.ts

@@ -19,7 +19,7 @@ import {
   ticketListCriteria,
   updateTicket,
 } from '../ports/tickets/operations'
-import type { Ticket, TicketSource, TicketUpdate } from '../ports/types'
+import type { Ticket, TicketSource, TicketStateInfo, TicketUpdate } from '../ports/types'
 import { reduceBuild } from '../kernel/reducer'
 import type { BuildStore } from '../store/types'
 import { spawnExec, type Exec } from '../ports/workspace/git-worktree'
@@ -140,7 +140,20 @@ export interface TicketMoveOpts extends TicketCommandOpts {
   json?: boolean
 }
 
+export interface TicketStatesOpts extends TicketCommandOpts {
+  json?: boolean
+}
+
+export interface TicketStateCreateOpts extends TicketCommandOpts {
+  name: string
+  /** One-line purpose; absent leaves an existing purpose untouched. */
+  about?: string
+  json?: boolean
+}
+
 type TicketCommandName =
+  | 'states'
+  | 'state create'
   | 'create'
   | 'update'
   | 'block'
@@ -525,6 +538,108 @@ export async function abTicketMove(opts: TicketMoveOpts): Promise<void> {
   opts.stdout(`ticket moved: ${ticketSummary(moved)}`)
 }
 
+export type TicketStateRole = 'create' | 'ready' | 'claimed' | 'triage' | 'proposal' | 'done'
+
+export interface TicketStateRow extends TicketStateInfo {
+  roles: TicketStateRole[]
+}
+
+/**
+ * The lifecycle roles each state plays under `config`, for a source whose
+ * states are directories (names match case-insensitively, as `ab ticket move`
+ * does). The file adapter always claims into `doing`, so that is shown as
+ * claimed whatever `[tickets].claimedState` says. Roles naming no existing
+ * state are omitted.
+ */
+export function stateRoles(
+  tickets: TicketsConfig,
+  names: string[],
+): Map<string, TicketStateRole[]> {
+  const triage = tickets.triageState ?? 'triage'
+  const named: Array<[TicketStateRole, string]> = [
+    ['create', tickets.createState ?? 'triage'],
+    ['ready', tickets.readyState],
+    ['claimed', 'doing'],
+    ['triage', triage],
+    ['proposal', tickets.proposalState ?? triage],
+    ['done', 'done'],
+  ]
+  const roles = new Map<string, TicketStateRole[]>(names.map((name) => [name, []]))
+  for (const [role, target] of named) {
+    const match =
+      names.find((name) => name === target) ??
+      names.find((name) => name.toLowerCase() === target.toLowerCase())
+    if (match !== undefined) roles.get(match)?.push(role)
+  }
+  return roles
+}
+
+function stateRow(info: TicketStateInfo, roles: Map<string, TicketStateRole[]>): TicketStateRow {
+  return {
+    name: info.name,
+    roles: roles.get(info.name) ?? [],
+    tickets: info.tickets,
+    ...(info.about !== undefined ? { about: info.about } : {}),
+  }
+}
+
+function unsupported(source: TicketSource, operation: string): Error {
+  return new Error(`ticket source "${source.name}" does not support ${operation}`)
+}
+
+/** `ab ticket states` — every state of the source, its roles, counts, purpose. */
+export async function abTicketStates(opts: TicketStatesOpts): Promise<void> {
+  const { config, source } = await resolveTicketCommand(opts, 'states')
+  if (typeof source.listStates !== 'function') {
+    throw unsupported(source, 'state discovery (ab ticket states)')
+  }
+  const infos = await source.listStates()
+  const roles = stateRoles(
+    config.tickets,
+    infos.map((info) => info.name),
+  )
+  const rows = infos.map((info) => stateRow(info, roles))
+  if (opts.json === true) {
+    opts.stdout(JSON.stringify(rows, null, 2))
+    return
+  }
+  const nameWidth = Math.max(...rows.map((row) => row.name.length))
+  const roleText = rows.map((row) => (row.roles.length > 0 ? row.roles.join(',') : 'none'))
+  const roleWidth = Math.max(...roleText.map((text) => text.length))
+  rows.forEach((row, index) => {
+    const count = `${row.tickets} ${row.tickets === 1 ? 'ticket' : 'tickets'}`
+    const line = `${row.name.padEnd(nameWidth)}  ${(roleText[index] as string).padEnd(roleWidth)}  ${count}`
+    opts.stdout(row.about === undefined ? line : `${line}  ${row.about}`)
+  })
+}
+
+/** `ab ticket state create <name> [--about <text>]` — idempotent. */
+export async function abTicketStateCreate(opts: TicketStateCreateOpts): Promise<void> {
+  const { config, source } = await resolveTicketCommand(opts, 'state create')
+  if (typeof source.addState !== 'function') {
+    throw unsupported(source, 'state creation (ab ticket state create)')
+  }
+  const aboutBefore =
+    opts.about === undefined
+      ? undefined
+      : (await source.listStates?.())?.find((info) => info.name === opts.name)?.about
+  const { state, created } = await source.addState(opts.name, {
+    ...(opts.about !== undefined ? { about: opts.about } : {}),
+  })
+  const names = (await source.listStates?.())?.map((info) => info.name) ?? [state.name]
+  const row = stateRow(state, stateRoles(config.tickets, names))
+  if (opts.json === true) {
+    opts.stdout(JSON.stringify({ ...row, created }, null, 2))
+    return
+  }
+  const purposeChanged = !created && opts.about !== undefined && state.about !== aboutBefore
+  opts.stdout(
+    created
+      ? `ticket state created: ${state.name}`
+      : `ticket state already exists: ${state.name}${purposeChanged ? ' (purpose updated)' : ''}`,
+  )
+}
+
 const CREATE_USAGE =
   'usage: ab ticket create <title> --body <file> [--state <state>] [--labels a,b] [--blocked-by id,id] [--json] (§8.8)'
 const UPDATE_USAGE =
@@ -540,6 +655,8 @@ const ASSET_GET_USAGE =
 const ASSET_RM_USAGE =
   'usage: ab ticket asset rm <id> <kind> <name> [--store <ref>] [--json] (§8.8)'
 const MOVE_USAGE = 'usage: ab ticket move <id> <state> [--json] (§8.8)'
+const STATES_USAGE = 'usage: ab ticket states [--json] (§8.8)'
+const STATE_CREATE_USAGE = 'usage: ab ticket state create <name> [--about <text>] [--json] (§8.8)'
 export const TICKET_USAGE = [
   CREATE_USAGE,
   UPDATE_USAGE,
@@ -548,6 +665,8 @@ export const TICKET_USAGE = [
   LIST_USAGE,
   SHOW_USAGE,
   MOVE_USAGE,
+  STATES_USAGE,
+  STATE_CREATE_USAGE,
   ATTACH_USAGE,
   ASSET_GET_USAGE,
   ASSET_RM_USAGE,
@@ -757,6 +876,32 @@ export async function abTicket(argv: string[], opts: TicketCliOpts): Promise<voi
       throw new Error(TICKET_USAGE)
     }
 
+    case 'states': {
+      const parsed = parseArgs(args, { json: 'boolean' }, TICKET_USAGE)
+      if (parsed.positionals.length !== 0) throw new Error(STATES_USAGE)
+      await abTicketStates({ ...opts, json: parsed.flags.has('json') })
+      return
+    }
+
+    case 'state': {
+      const [action, ...stateArgs] = args
+      if (action !== 'create') throw new Error(STATE_CREATE_USAGE)
+      const parsed = parseArgs(stateArgs, { about: 'value', json: 'boolean' }, TICKET_USAGE)
+      const [name, ...extra] = parsed.positionals
+      if (name === undefined || name.trim() === '' || extra.length > 0) {
+        throw new Error(STATE_CREATE_USAGE)
+      }
+      const about = stringFlag(parsed, 'about')
+      if (about !== undefined && about.trim() === '') throw new Error(STATE_CREATE_USAGE)
+      await abTicketStateCreate({
+        ...opts,
+        name,
+        ...(about !== undefined ? { about } : {}),
+        json: parsed.flags.has('json'),
+      })
+      return
+    }
+
     case 'move': {
       const parsed = parseArgs(args, { json: 'boolean' }, TICKET_USAGE)
       const [id, state, ...extra] = parsed.positionals

package/packages/core/src/cli/wait.ts

@@ -416,6 +416,9 @@ export async function abWait(opts: AbWaitOpts): Promise<number> {
         if (satisfied === null) checkRegistrationState(stream)
       }
 
+      /** Builds discovery read in full and found terminal; never re-read. */
+      const retired = new Set<string>()
+
       /**
        * No-slug membership: every nonterminal build of this repository joins
        * the wait, baselined at its current maximum so no history replays, and
@@ -440,12 +443,17 @@ export async function abWait(opts: AbWaitOpts): Promise<number> {
         // diverge from reduceBuild.
         const digests = await store.getRepoBuildDigests(repo)
         for (const record of (await store.listBuilds()).filter(mine)) {
-          if (streams.has(record.slug)) continue
+          if (streams.has(record.slug) || retired.has(record.slug)) continue
           const digest = digests.get(record.slug)
           if (digest !== undefined && digest.terminal !== undefined) continue
           const events = await store.getEvents(record.slug)
           const status = reduceBuild(events).status
-          if (!NONTERMINAL_STATUSES.includes(status)) continue
+          if (!NONTERMINAL_STATUSES.includes(status)) {
+            // Terminal is permanent (reduceBuild never clears it): a legacy
+            // record the digest cannot retire is read once, not every pass.
+            retired.add(record.slug)
+            continue
+          }
           const stream = registerStream(record.slug, events, false)
           if (satisfied === null) checkRegistrationState(stream)
         }

package/packages/core/src/cli/watch.ts

@@ -597,6 +597,9 @@ export async function abWatch(opts: AbWatchOpts): Promise<void> {
         return true
       }
 
+      /** Builds discovery read in full and found terminal; never re-read. */
+      const retired = new Set<string>()
+
       /**
        * No-slug membership: every nonterminal build of this repository joins
        * the watch, baselined at its current maximum so no history replays. A
@@ -624,12 +627,17 @@ export async function abWatch(opts: AbWatchOpts): Promise<void> {
         // diverge from reduceBuild. Mirrors cli/wait.ts discoverBuilds.
         const digests = await store.getRepoBuildDigests(repo)
         for (const record of (await store.listBuilds()).filter(mine)) {
-          if (streams.has(record.slug)) continue
+          if (streams.has(record.slug) || retired.has(record.slug)) continue
           const digest = digests.get(record.slug)
           if (digest !== undefined && digest.terminal !== undefined) continue
           const events = await store.getEvents(record.slug)
           const status = reduceBuild(events).status
-          if (!NONTERMINAL_STATUSES.includes(status)) continue
+          if (!NONTERMINAL_STATUSES.includes(status)) {
+            // Terminal is permanent (reduceBuild never clears it): a legacy
+            // record the digest cannot retire is read once, not every pass.
+            retired.add(record.slug)
+            continue
+          }
           const stream: BuildStream = {
             kind: 'build',
             slug: record.slug,

package/packages/core/src/config/live.ts

@@ -31,6 +31,7 @@ export const CONFIG_RELOAD_CLASSIFICATION = {
     source: 'restart',
     readyLabels: 'hot',
     readyState: 'hot',
+    readyAssignee: 'hot',
     teamKey: 'restart',
     claimedState: 'restart',
     createState: 'restart',

package/packages/core/src/config/pipeline-source.ts

@@ -10,6 +10,7 @@
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import type { AbEvent } from '../events/catalog'
+import { defineReducer } from '../kernel/incremental'
 import type { Forge } from '../ports/types'
 import type { Exec } from '../ports/workspace/git-worktree'
 import type { BuildRecord } from '../store/types'
@@ -101,15 +102,26 @@ export function isActionablePipelineFailure(failure: PipelineSourceFailure): boo
   )
 }
 
+export const RECORDED_BASE_SHA_REDUCER_VERSION = 1
+
 /** The recorded base commit of the build's latest workspace. The newest
  * `workspace.provisioned` wins: a re-provisioned workspace is what the build's
  * current environment was cut from. */
+export const recordedBaseShaReducer = defineReducer<{ base?: string }, AbEvent, string | undefined>(
+  {
+    version: RECORDED_BASE_SHA_REDUCER_VERSION,
+    initial: () => ({}),
+    fold(acc, events) {
+      for (const event of events) {
+        if (event.type === 'workspace.provisioned') acc.base = event.payload.base.sha
+      }
+    },
+    finish: (acc) => acc.base,
+  },
+)
+
 export function recordedBaseSha(events: readonly AbEvent[]): string | undefined {
-  let base: string | undefined
-  for (const event of events) {
-    if (event.type === 'workspace.provisioned') base = event.payload.base.sha
-  }
-  return base
+  return recordedBaseShaReducer.reduce(events)
 }
 
 function buildBranch(record: Pick<BuildRecord, 'branch'>, slug: string): string {

package/packages/core/src/config/schema.ts

@@ -556,6 +556,20 @@ export const ticketsSchema = z.strictObject({
       (s) => s.trim().length > 0,
       '[tickets].readyState must not be blank — name the one workflow state a ticket must sit in to be dispatched (e.g. "ready").',
     ),
+  /**
+   * Narrows readiness to tickets assigned to one Linear user — a third
+   * conjunctive gate beside readyState and readyLabels. `"me"` is the owner of
+   * the dispatcher's LINEAR_API_KEY; an email names a specific user (for a
+   * shared or bot key). Unassigned tickets are never ready while it is set.
+   * Linear only; absent leaves readiness unchanged.
+   */
+  readyAssignee: z
+    .string()
+    .refine(
+      (s) => s === 'me' || (s === s.trim() && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(s)),
+      '[tickets].readyAssignee must be "me" (the owner of the API key) or a user email address (e.g. "person@example.com")',
+    )
+    .optional(),
   /** Backend team key (e.g. "ENG") — required for linear and hosted. */
   teamKey: z.string().min(1).optional(),
   /** Workflow state claim() moves an issue to (§12); Linear and hosted. */
@@ -923,6 +937,13 @@ export const configSchema = configRootSchema.superRefine((config, ctx) => {
       }
     }
   }
+  if (tickets.source !== 'linear' && tickets.readyAssignee !== undefined) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['tickets', 'readyAssignee'],
+      message: `[tickets].readyAssignee applies only to source = "linear" — remove it or select that source (selected source: "${tickets.source}")`,
+    })
+  }
   // Plugin sources receive the existing ticket lifecycle/configuration fields
   // unchanged; adapter-specific validation belongs to their factory.
 

package/packages/core/src/integration/harness.ts

@@ -59,6 +59,13 @@ import { InProcessBuildExecution } from '../ports/workspace/in-process-build-exe
 import { BuildRunner, LeaseHeldError, SetupFailureError } from '../processes/build-runner'
 import { diagnosticArtifact } from '../processes/build-execution-state'
 import { Dispatcher, type LaunchRunnerResult } from '../processes/dispatcher'
+import {
+  getHarvestStatus,
+  getOperatorDashboard,
+  getRepositoryStatus,
+  listOperatorBuilds,
+} from '../operator/query'
+import { RepoViewStore } from '../processes/repo-view'
 import { MemoryBuildStore } from '../store/memory'
 import type { BuildStore } from '../store/types'
 import { steppingClock } from '../testing/fixed'
@@ -279,6 +286,106 @@ export interface E2eHarness {
   cleanup(): Promise<void>
 }
 
+/** The store with every reducer snapshot deleted: reads miss, writes no-op. */
+export function withoutSnapshots<T extends BuildStore>(store: T): T {
+  return new Proxy(store, {
+    get(target, key) {
+      if (key === 'getReducerSnapshot') return async () => null
+      if (key === 'putReducerSnapshot') return async () => false
+      const value = Reflect.get(target, key, target)
+      return typeof value === 'function' ? value.bind(target) : value
+    },
+  })
+}
+
+/** A build's facts with the publication view (closures) reduced to its answers. */
+async function plainFacts(view: RepoViewStore, slug: string) {
+  const { publication, ...rest } = await view.buildFacts(slug)
+  return {
+    ...rest,
+    publication: {
+      pending: publication.pending(),
+      abandoned: publication.abandonedPending(),
+      latest: publication.latestUncompletedRequest(),
+    },
+  }
+}
+
+/** JSON with sorted keys, so two structurally equal values compare equal. */
+function canonical(value: unknown): string {
+  return JSON.stringify(value, (_key, item) =>
+    item !== null && typeof item === 'object' && !Array.isArray(item)
+      ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => a.localeCompare(b)))
+      : item,
+  )
+}
+
+async function repositoryReading(store: BuildStore, repo: string) {
+  const view = new RepoViewStore(store, { repo })
+  await view.refresh()
+  const slugs = (await view.listBuilds()).map((record) => record.slug).sort()
+  const builds: Record<string, unknown> = {}
+  for (const slug of slugs) {
+    builds[slug] = { facts: await plainFacts(view, slug), state: await view.buildState(slug) }
+  }
+  return {
+    journal: view.recordedJournal(),
+    digests: [...(await view.getRepoBuildDigests(repo)).entries()].sort(([a], [b]) =>
+      a.localeCompare(b),
+    ),
+    builds,
+    view,
+  }
+}
+
+/** Reducer snapshots are a cache the log regenerates (SPEC §7): whatever a
+ * scenario's dispatcher left behind, a cold view restored from it must read
+ * exactly what a cold view over a store with every snapshot deleted reads — and
+ * so must one restored from snapshots written at the final cursor. Run for
+ * every scenario at cleanup. */
+export async function assertSnapshotEquivalence(store: BuildStore, repo: string): Promise<void> {
+  const replayed = await repositoryReading(withoutSnapshots(store), repo)
+  for (const round of ['as left by the scenario', 'written at the final cursor']) {
+    const restored = await repositoryReading(store, repo)
+    const { view: restoredView, ...got } = restored
+    const { view: _replayedView, ...want } = replayed
+    if (canonical(got) !== canonical(want)) {
+      throw new Error(`snapshot-restored reading differs from full replay (${round})`)
+    }
+    await restoredView.persistSnapshots({ force: true })
+  }
+  // The operator routes derive from the same view: each response with
+  // snapshots present equals the response with every snapshot deleted.
+  const at = new Date('2026-01-01T00:00:00.000Z')
+  const routes = async (target: BuildStore) => {
+    const attempt = async (read: () => Promise<unknown>): Promise<unknown> => {
+      try {
+        return await read()
+      } catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) }
+      }
+    }
+    return {
+      dashboard: await attempt(() =>
+        getOperatorDashboard({ store: target, repo, clock: () => at }),
+      ),
+      status: await attempt(() => getRepositoryStatus(target, repo)),
+      harvest: await attempt(() => getHarvestStatus(target, repo)),
+      lists: await Promise.all(
+        (['active', 'queued', 'all'] as const).map((scope) =>
+          attempt(() => listOperatorBuilds({ store: target, repo, scope, now: at })),
+        ),
+      ),
+    }
+  }
+  const replayedRoutes = canonical(await routes(withoutSnapshots(store)))
+  for (const round of ['as left', 'warmed by a first poll']) {
+    if (canonical(await routes(store)) !== replayedRoutes) {
+      throw new Error(`snapshot-backed operator routes differ from full replay (${round})`)
+    }
+  }
+}
+
 export async function makeHarness(opts: {
   handlers: SkillHandlers
   tickets?: Ticket[]
@@ -336,7 +443,11 @@ export async function makeHarness(opts: {
   const clock = steppingClock()
   const ids = sequentialIds()
   const uuids = sequentialUuids()
-  const store = new MemoryBuildStore({ clock })
+  // `AB_E2E_SNAPSHOTS=off` runs every scenario with every snapshot deleted, the
+  // other arm of the "snapshots change no observable output" proof.
+  const snapshotsOff = process.env.AB_E2E_SNAPSHOTS === 'off'
+  const memory = new MemoryBuildStore({ clock })
+  const store = snapshotsOff ? withoutSnapshots(memory) : memory
   const adapted = await opts.storeAdapter?.(store)
   const activeStore = adapted?.store ?? store
   const config = parseConfig(configToml, 'e2e autobuild.toml')
@@ -612,6 +723,7 @@ export async function makeHarness(opts: {
     },
     events: (slug) => store.getEvents(slug),
     cleanup: async () => {
+      if (!snapshotsOff) await assertSnapshotEquivalence(store, origin)
       await activeStore.close()
       if (activeStore !== store) await store.close()
       await adapted?.cleanup?.()