@defrex/autobuild 0.12.0 → 0.14.0

package/docs/ticket-migration.md

@@ -0,0 +1,64 @@
+# Moving a project between ticket sources
+
+Export and import use the ordinary file ticket layout. They operate on tickets
+and current attachments through the ticket source; neither command contacts the
+forge. File and hosted sources support import. Linear supports export only.
+
+1. Pause intake and stop other ticket writers for the cutover. Import preflight
+   does not reserve numbers against concurrent writers.
+2. With the old `[tickets]` configuration, run `ab ticket export /path/to/export`.
+   The destination must be absent or empty. Export reads every state, including
+   archived Linear tickets and empty discoverable states, and publishes the
+   directory only after all reads succeed. Back up the target tracker too.
+3. Configure the new `[tickets]` source, or use `ab connect --tickets URL` for a
+   hosted ticket service. Keep the export directory intact.
+4. Run `ab ticket import /path/to/export`. Inspect its printed ticket and state
+   mappings and `/path/to/export/.ab-import-map.json`.
+5. Inspect ticket bodies, labels, blockers, comments and attachments in the new
+   source. Confirm lifecycle configuration and the ready gate, then resume intake.
+
+Both commands also accept
+`--store <ref>` to reach legacy BuildStore attachments. Keep the old store available
+through export when file or Linear tickets have attachments there.
+
+State directory names use lowercase letters, digits and hyphens, start with a
+letter and contain at most forty characters. Export maps `In Progress` to
+`in-progress`, `Backlog` to `backlog`, and `Done` to `done`. It retains each ticket's
+state rather than assigning lifecycle roles. Distinct names that collapse to the
+same directory fail before publication. The hidden `.ab-migration.json` records
+original display names and the state map. Import also accepts ordinary legacy
+file layouts: it reuses exact or unique case-insensitive target states before
+normalizing new names. A seeded `done` satisfies `Done`; absent `In Progress`
+creates `in-progress`. Ambiguous matches and colliding state maps fail preflight.
+
+File targets retain source ids. Hosted targets keep canonical own-team ids:
+`AUT-706` imported into team `AUT` stays `AUT-706`. Other ids receive numbers above
+all existing and preserved incoming numbers. Known clashes with unrelated tickets
+are reported together before any target state, ticket, comment or asset write.
+Content similarity and stale mapping files never establish identity.
+
+Creation keys establish identity. Exports retain existing keys and assign keys to
+legacy tickets. Importing an ordinary file layout first saves a hidden migration
+identity and keys in that input directory. Preserve this file and the input across
+retries. After interruption, rerun the same command: committed creates are adopted
+by key even if their mapping write failed. Adopted bodies and other fields are not
+overwritten. Missing blockers and comments are replayed, and unchanged attachments
+do not create another revision. Comments are deduplicated by exact body, so two
+identical source comment bodies produce one target comment. Original authors and
+timestamps remain in the export; imported comments use the target's metadata.
+
+Portable records use TOML frontmatter between `+++` fences and an unchanged
+Markdown body. Alongside `id`, `title`, `labels`, `blockedBy` and `idempotencyKey`,
+optional `comments` contain `body`, `createdAt` and optional `author`. Optional
+`attachments` contain `kind`, `name`, `layout` (`file` or `tree`) and `entries`:
+`{ type = "dir", path = "empty" }` or
+`{ type = "file", path = "image.png", base64 = "…" }`. Common asset limits and
+path validators apply. Only current attachment contents travel, including binary
+files and empty directories; historical revisions do not. The exported directory
+works directly as a file source, without its migration manifest or original store.
+File source revision history stays in its hidden `.ab-assets` directory.
+
+Legacy records without `comments` retain their Markdown comment append behavior;
+export never interprets Markdown headings as structured history. New file tickets
+use structured comments and preserve their body when a comment is added. There is
+no continuous sync, assignee migration, state history or build-history migration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defrex/autobuild",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Agent-driven software delivery from groomed ticket to merged PR",
   "repository": {
     "type": "git",
@@ -114,6 +114,7 @@
     "docs"
   ],
   "scripts": {
+    "ab": "bun bin/ab.ts",
     "dev:cli": "bun --hot --no-clear-screen bin/ab-dev.ts",
     "capture:dashboard": "bun tools/dashboard-capture.ts",
     "capture:web-dashboard": "bun packages/web-dashboard-capture/src/web-dashboard-capture.tsx",
@@ -143,8 +144,8 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.5",
-    "@defrex/autobuild-postgres-store": "0.11.0",
-    "@defrex/autobuild-vercel-sandbox": "0.11.0",
+    "@defrex/autobuild-postgres-store": "0.14.0",
+    "@defrex/autobuild-vercel-sandbox": "0.14.0",
     "@resvg/resvg-js": "2.6.2",
     "@types/bun": "^1.3.14",
     "@types/node": "^24.0.0",

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

@@ -1,6 +1,10 @@
 import type { AbEvent } from '../events/catalog'
 import type { RepositoryEvent } from '../events/repository'
-import { currentAutoMergeDeferral } from '../kernel/auto-merge'
+import {
+  currentDeferralObservationReducer,
+  mergeAttentionFromFacts,
+  type DeferralLedger,
+} from '../kernel/auto-merge'
 import { reduceBuild, type BuildState } from '../kernel/reducer'
 
 export interface MergeDecision {
@@ -17,22 +21,18 @@ export function mergeDecision(
   now: Date,
   state = reduceBuild(events),
 ): MergeDecision | null {
-  if (
-    !state.finalizeCompletedSeq ||
-    !state.pr ||
-    state.prState !== 'open' ||
-    state.status === 'done' ||
-    state.status === 'aborted'
-  )
-    return null
-  const deferral = currentAutoMergeDeferral(events, state)
-  if (state.autoMerge.requested && deferral === undefined) return null
-  return {
-    type: 'build.merge-decision',
-    pr: state.pr,
-    reason: deferral ?? 'Auto-merge is not armed',
-    observedAt: now.toISOString(),
-  }
+  return mergeDecisionFromFacts(state, currentDeferralObservationReducer.reduce(events), now)
+}
+
+export function mergeDecisionFromFacts(
+  state: BuildState,
+  ledger: DeferralLedger,
+  now: Date,
+): MergeDecision | null {
+  const decision = mergeAttentionFromFacts(state, ledger)
+  return decision
+    ? { type: 'build.merge-decision', ...decision, observedAt: now.toISOString() }
+    : null
 }
 
 export function buildNeedsAttention(events: AbEvent[], state: BuildState): boolean {
@@ -60,150 +60,4 @@ export function repositoryNeedsAttention(event: RepositoryEvent): boolean {
   }
 }
 
-type Degraded = Extract<RepositoryEvent, { type: 'dispatcher.ticket-source-degraded' }>
-type Failed = Extract<RepositoryEvent, { type: 'dispatcher.tick-failed' }>
-export type PersistenceObservation =
-  | {
-      type: 'dispatcher.ticket-source-persistent'
-      source: string
-      cause: string
-      message: string
-      resetAt?: string
-      episodeSeq: number
-      observedAt: string
-      dependencyLimited: boolean
-    }
-  | {
-      type: 'dispatcher.tick-failure-persistent'
-      run: string
-      firstFailure: string
-      error: string
-      episodeSeq: number
-      observedAt: string
-    }
-
-/** Incremental journal projection. Episode starts survive run anchors and
- * repeated evidence can strengthen, but never postpone, an existing deadline. */
-export class RepositoryAttention {
-  private sources = new Map<
-    string,
-    {
-      event: Degraded
-      deadline: number
-      dependencyLimited: boolean
-      requiresRetry: boolean
-      retryObserved: boolean
-    }
-  >()
-  private failure: Failed | undefined
-  private tickStarts = new Map<string, number>()
-
-  private sourceDefersTick(now: number): boolean {
-    return [...this.sources.values()].some(
-      (source) => now < source.deadline || (source.requiresRetry && !source.retryObserved),
-    )
-  }
-
-  /** Crossing resetAt alone does not prove persistence: the dispatcher must
-   * finish a tick that could actually retry after the provider cooldown. */
-  private observeRetry(run: string): void {
-    const startedAt = this.tickStarts.get(run)
-    this.tickStarts.delete(run)
-    if (startedAt === undefined) return
-    for (const source of this.sources.values()) {
-      if (startedAt >= source.deadline) source.retryObserved = true
-    }
-  }
-  fold(event: RepositoryEvent): void {
-    switch (event.type) {
-      case 'dispatcher.ticket-source-degraded': {
-        const existing = this.sources.get(event.payload.source)
-        const deadline =
-          'resetAt' in event.payload
-            ? Date.parse(event.payload.resetAt)
-            : Date.parse(event.ts) + 15 * 60_000
-        if (existing) {
-          existing.deadline = Math.min(existing.deadline, deadline)
-          existing.requiresRetry ||= 'resetAt' in event.payload
-        } else
-          this.sources.set(event.payload.source, {
-            event,
-            deadline,
-            dependencyLimited: false,
-            requiresRetry: 'resetAt' in event.payload,
-            retryObserved: false,
-          })
-        // Cooldown-driven failures are not an independent dispatcher outage.
-        if (this.sourceDefersTick(Date.parse(event.ts))) this.failure = undefined
-        break
-      }
-      case 'dispatcher.ticket-source-dependency-limited': {
-        const source = this.sources.get(event.payload.source)
-        if (source) source.dependencyLimited = true
-        break
-      }
-      case 'dispatcher.ticket-source-recovered':
-        this.sources.delete(event.payload.source)
-        break
-      case 'dispatcher.run-started':
-        this.failure = undefined
-        this.tickStarts.clear()
-        break
-      case 'dispatcher.run-stopped':
-        this.tickStarts.delete(event.payload.run)
-        if (this.failure?.payload.run === event.payload.run) this.failure = undefined
-        break
-      case 'dispatcher.tick-started':
-        this.tickStarts.set(event.payload.run, Date.parse(event.ts))
-        break
-      case 'dispatcher.tick-completed':
-        this.observeRetry(event.payload.run)
-        if (this.failure?.payload.run === event.payload.run) this.failure = undefined
-        break
-      case 'dispatcher.tick-failed':
-        this.observeRetry(event.payload.run)
-        if (this.sourceDefersTick(Date.parse(event.ts))) this.failure = undefined
-        else if (this.failure?.payload.run !== event.payload.run) this.failure = event
-        break
-    }
-  }
-  pending(now: Date): { identity: string; observation: PersistenceObservation }[] {
-    const results: { identity: string; observation: PersistenceObservation }[] = []
-    for (const {
-      event,
-      deadline,
-      dependencyLimited,
-      requiresRetry,
-      retryObserved,
-    } of this.sources.values()) {
-      if (now.getTime() < deadline || (requiresRetry && !retryObserved)) continue
-      results.push({
-        identity: `source:${event.seq}`,
-        observation: {
-          type: 'dispatcher.ticket-source-persistent',
-          ...event.payload,
-          episodeSeq: event.seq,
-          observedAt: now.toISOString(),
-          dependencyLimited,
-        },
-      })
-    }
-    const event = this.failure
-    if (
-      event &&
-      !this.sourceDefersTick(now.getTime()) &&
-      now.getTime() >= Date.parse(event.ts) + 5 * 60_000
-    )
-      results.push({
-        identity: `tick:${event.seq}`,
-        observation: {
-          type: 'dispatcher.tick-failure-persistent',
-          ...event.payload,
-          firstFailure: event.ts,
-          episodeSeq: event.seq,
-          observedAt: now.toISOString(),
-        },
-      })
-    return results
-  }
-}
+export { RepositoryAttention, type PersistenceObservation } from '../kernel/repository-attention'

package/packages/core/src/cli/build-control.ts

@@ -1,3 +1,4 @@
+import { readBuildFacts } from '../store/reduced-reads'
 /**
  * Durable operator controls for one build.
  *
@@ -9,12 +10,7 @@
 import type { AbEvent } from '../events/catalog'
 import type { PinnedAsset } from '../events/payloads'
 import { humanActor, KERNEL, type Via } from '../events/envelope'
-import {
-  reduceBuild,
-  discardInFlight,
-  type BuildState,
-  type OpenEscalation,
-} from '../kernel/reducer'
+import { discardInFlight, type BuildState, type OpenEscalation } from '../kernel/reducer'
 import type { ArtifactRef, BuildOutcome, BuildStatus, TicketRef } from '../ontology'
 import type { Exec } from '../ports/workspace/git-worktree'
 import { specConformance } from '../spec-standard'
@@ -276,7 +272,7 @@ async function appendConsentCommand(
   via?: Via,
 ): Promise<BuildControlResult> {
   while (true) {
-    const state = reduceBuild(await store.getEvents(slug))
+    const state = (await readBuildFacts(store, slug)).value.state
     activeState(slug, state)
     const command =
       action === 'toggle-auto-merge'
@@ -464,6 +460,7 @@ export interface ControlBuildOpts {
   via?: Via
   action: BuildControlAction
   /** Injected only for --revise-spec-from-ticket. */
+  prepareTicketAssets?: (ref: TicketRef, store: BuildStore, repo: string) => Promise<PinnedAsset[]>
   readTicketBody?: (ref: TicketRef) => Promise<string>
 }
 
@@ -483,8 +480,8 @@ export async function controlBuild(opts: ControlBuildOpts): Promise<BuildControl
     )
   }
 
-  const events = await opts.store.getEvents(opts.slug)
-  const state = reduceBuild(events)
+  const events = (await readBuildFacts(opts.store, opts.slug)).value
+  const state = events.state
   const user = opts.user?.trim() || buildControlUser(opts.env ?? {})
 
   if (opts.action.kind === 'discard') {
@@ -494,7 +491,7 @@ export async function controlBuild(opts: ControlBuildOpts): Promise<BuildControl
         `build "${opts.slug}" cannot be discarded (status: ${state.status}); discard requires queued`,
       )
     }
-    const existing = events.findLast((event) => event.type === 'build.discard-requested')
+    const existing = events.latestDiscard
     if (existing !== undefined) {
       return { kind: 'command', slug: opts.slug, command: 'discard', event: existing }
     }
@@ -503,7 +500,7 @@ export async function controlBuild(opts: ControlBuildOpts): Promise<BuildControl
 
   if (opts.action.kind === 'abort') {
     if (state.status !== 'queued') activeState(opts.slug, state)
-    const existing = events.findLast((event) => event.type === 'build.abort-requested')
+    const existing = events.latestAbort
     if (existing !== undefined) {
       return { kind: 'command', slug: opts.slug, command: 'abort', event: existing }
     }
@@ -624,7 +621,15 @@ export async function controlBuild(opts: ControlBuildOpts): Promise<BuildControl
               )
             }
             body = await opts.readTicketBody(record.ticket)
-            assets = await samplePinnedAssets(opts.store, record.repo, record.ticket.id)
+            if (record.ticket.source === 'hosted' && !opts.prepareTicketAssets) {
+              throw new BuildControlError(
+                'ticket-unavailable',
+                'hosted ticket asset preparation is unavailable',
+              )
+            }
+            assets = opts.prepareTicketAssets
+              ? await opts.prepareTicketAssets(record.ticket, opts.store, record.repo)
+              : await samplePinnedAssets(opts.store, record.repo, record.ticket.id)
           }
           const conformance = specConformance(body)
           if (!conformance.conforms) {
@@ -649,7 +654,7 @@ export async function controlBuild(opts: ControlBuildOpts): Promise<BuildControl
 
         // Re-read at the last durable moment. The PR janitor and abort
         // acknowledgement may still write while a blocked build is parked.
-        const freshState = reduceBuild(await opts.store.getEvents(opts.slug))
+        const freshState = (await readBuildFacts(opts.store, opts.slug)).value.state
         assertStillActive(opts.slug, freshState)
         const decision = decideRevise(opts.slug, freshState, captured)
         if (decision.kind === 'refuse') throwRefusal(decision)
@@ -692,7 +697,7 @@ export async function controlBuild(opts: ControlBuildOpts): Promise<BuildControl
             payload: {},
           })
         }
-        const after = reduceBuild(await opts.store.getEvents(opts.slug))
+        const after = (await readBuildFacts(opts.store, opts.slug)).value.state
         const signal = terminalSignal(after)
         return {
           kind: 'answered',
@@ -720,7 +725,7 @@ export async function controlBuild(opts: ControlBuildOpts): Promise<BuildControl
         const initial = dismissPartition(state, captured)
         if (initial.eligible.length === 0) throw noCitedFindings(opts.slug, initialOpen)
 
-        const freshState = reduceBuild(await opts.store.getEvents(opts.slug))
+        const freshState = (await readBuildFacts(opts.store, opts.slug)).value.state
         assertStillActive(opts.slug, freshState)
         if (hasPendingAbort(freshState)) throw abortPending(opts.slug)
         const freshOpen = selectedOpen(freshState, captured)
@@ -748,7 +753,7 @@ export async function controlBuild(opts: ControlBuildOpts): Promise<BuildControl
             payload: {},
           })
         }
-        const after = reduceBuild(await opts.store.getEvents(opts.slug))
+        const after = (await readBuildFacts(opts.store, opts.slug)).value.state
         const signal = terminalSignal(after)
         return {
           kind: 'answered',
@@ -862,6 +867,7 @@ export interface AbBuildControlOpts {
   /** Explicit `--store`; selection remains --store > AB_STORE > repo-local. */
   storeRef?: string
   /** Injected only for --revise-spec-from-ticket. */
+  prepareTicketAssets?: (ref: TicketRef, store: BuildStore, repo: string) => Promise<PinnedAsset[]>
   readTicketBody?: (ref: TicketRef) => Promise<string>
   /** Injectable adapter seam for unit tests. */
   openStore?: StoreOpener
@@ -881,6 +887,7 @@ export async function abBuildControl(opts: AbBuildControlOpts): Promise<BuildCon
       env: opts.env,
       action: opts.action,
       ...(opts.readTicketBody !== undefined ? { readTicketBody: opts.readTicketBody } : {}),
+      ...(opts.prepareTicketAssets ? { prepareTicketAssets: opts.prepareTicketAssets } : {}),
     }),
   )
 }

package/packages/core/src/cli/bulk-control.ts

@@ -1,3 +1,4 @@
+import { readBuildFacts } from '../store/reduced-reads'
 /**
  * Repository-wide quiescence: one keypress that parks every running build and
  * stops intake, and one that reverses it.
@@ -59,7 +60,7 @@
  * what the operator sees, and a unit test pins that agreement.
  */
 import { humanActor, type Actor, type Via } from '../events/envelope'
-import { reduceBuild, type BuildState } from '../kernel/reducer'
+import type { BuildState } from '../kernel/reducer'
 import type { Exec } from '../ports/workspace/git-worktree'
 import type { BuildRecord, BuildStore } from '../store/types'
 import { BuildControlError, buildControlUser } from './build-control'
@@ -132,7 +133,7 @@ async function requestOne(
   direction: BulkDirection,
 ): Promise<boolean> {
   while (true) {
-    const state = reduceBuild(await store.getEvents(slug))
+    const state = (await readBuildFacts(store, slug)).value.state
     if (!eligible(state, direction)) return false
     // The two branches are written out rather than selecting the event type
     // into a variable so `appendIfCurrent`'s `T extends EventType` infers a