@defrex/autobuild 0.11.0 → 0.13.0

package/packages/core/src/ports/tickets/fake.ts

@@ -1,3 +1,5 @@
+import { fileRequestedIds } from './requested-id'
+import { ticketRevision, checkTicketRevision } from './revision'
 /**
  * In-memory TicketSource for seam tests (SPEC §3.2, §13). Mirrors the policy
  * shape of the real adapters: initiation (listReady/get/claim/create),
@@ -12,11 +14,13 @@ import type {
   TicketListing,
   TicketSource,
   TicketUpdate,
+  TicketMutation,
 } from '../types'
 import { validateTicketUpdate } from './update'
 
 function cloneTicket(ticket: Ticket, doneState: string): Ticket {
   return {
+    revision: ticketRevision(ticket),
     ref: { ...ticket.ref },
     ...(ticket.creationKey !== undefined ? { creationKey: ticket.creationKey } : {}),
     title: ticket.title,
@@ -29,6 +33,7 @@ function cloneTicket(ticket: Ticket, doneState: string): Ticket {
 }
 
 export class FakeTicketSource implements TicketSource {
+  readonly requestedIds = fileRequestedIds
   readonly name = 'fake'
 
   /** Journal of every projection sent outward (§13), in call order. */
@@ -111,6 +116,7 @@ export class FakeTicketSource implements TicketSource {
     const ticket = this.tickets.get(id)
     if (!ticket || ticket.state === this.doneState || this.claimed.has(id)) return false
     this.claimed.add(id)
+    ticket.state = 'Doing'
     return true
   }
 
@@ -131,8 +137,10 @@ export class FakeTicketSource implements TicketSource {
       const adopted = this.idempotency.get(opts.idempotencyKey)
       if (adopted !== undefined) return cloneTicket(this.require(adopted, 'create'), this.doneState)
     }
-    const id = `fake-${this.nextId++}`
+    const id = opts.requestedId ?? `fake-${this.nextId++}`
+    if (this.tickets.has(id)) throw new Error(`requested ticket id already occupied: ${id}`)
     const ticket: Ticket = {
+      revision: 'pending',
       ref: { source: this.name, id, title: draft.title },
       ...(opts.idempotencyKey !== undefined ? { creationKey: opts.idempotencyKey } : {}),
       title: draft.title,
@@ -153,6 +161,27 @@ export class FakeTicketSource implements TicketSource {
     return cloneTicket(ticket, this.doneState)
   }
 
+  async mutateIfRevision(id: string, expected: string, mutation: TicketMutation): Promise<void> {
+    const ticket = this.require(id, 'revision-checked write')
+    checkTicketRevision(cloneTicket(ticket, this.doneState), expected)
+    if (mutation.kind === 'update') await this.update(id, mutation.patch)
+    else if (mutation.kind === 'transition') await this.transition(id, mutation.state)
+    else {
+      for (const blocker of mutation.ids) {
+        this.require(blocker, 'blocker')
+        if (mutation.operation === 'block' && blocker === id)
+          throw new Error(`ticket "${id}" cannot block itself`)
+      }
+      // No await between validation and in-memory batch application.
+      const blockers = new Set(ticket.blockedBy ?? [])
+      for (const blocker of mutation.ids) {
+        if (mutation.operation === 'block') blockers.add(blocker)
+        else blockers.delete(blocker)
+      }
+      ticket.blockedBy = [...blockers]
+    }
+  }
+
   async update(id: string, patch: TicketUpdate): Promise<void> {
     const validated = validateTicketUpdate(patch)
     const ticket = this.require(id, 'update')

package/packages/core/src/ports/tickets/file-assets.ts

@@ -0,0 +1,159 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { TicketAssetStore } from '../types'
+import type { Frontmatter } from './file-codec'
+import { decodePortableAsset, encodePortableAsset, type PortableAsset } from './portable-assets'
+import { contentHash } from '../../store/types'
+import {
+  DEFAULT_TICKET_ASSET_LIMITS,
+  summarizeTicketAsset,
+  validateTicketAssetInput,
+  type TicketAsset,
+  type TicketAssetInput,
+} from '../../store/ticket-assets'
+
+type History = Record<string, Array<{ asset: PortableAsset | null; createdAt: string }>>
+// Native revisions occupy a separate range so legacy recorded pins remain unambiguous.
+const FIRST_REVISION = 1_000_000_000
+export class FileTicketAssets implements TicketAssetStore {
+  constructor(
+    private dir: string,
+    private load: (
+      id: string,
+    ) => Promise<{ front: Frontmatter; exists?: boolean; save(front: Frontmatter): Promise<void> }>,
+  ) {}
+  async ticketAssetLimits() {
+    return { ...DEFAULT_TICKET_ASSET_LIMITS }
+  }
+  private key(kind: string, name: string) {
+    return `${kind}/${name}`
+  }
+  private path(id: string) {
+    return join(this.dir, '.ab-assets', `${Buffer.from(id).toString('hex')}.json`)
+  }
+  private async history(id: string, front: Frontmatter): Promise<History> {
+    try {
+      return JSON.parse(await readFile(this.path(id), 'utf8')) as History
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+    }
+    return Object.fromEntries(
+      (front.attachments ?? []).map((asset) => [
+        this.key(asset.kind, asset.name),
+        [{ asset, createdAt: '1970-01-01T00:00:00.000Z' }],
+      ]),
+    )
+  }
+  async hasTicketAssetHistory(_repo: string, id: string, kind: string, name: string) {
+    const { front } = await this.load(id)
+    return this.key(kind, name) in (await this.history(id, front))
+  }
+  private materialize(
+    repo: string,
+    id: string,
+    asset: PortableAsset,
+    revision: number,
+    createdAt: string,
+  ): TicketAsset {
+    const input = decodePortableAsset(asset)
+    const size = validateTicketAssetInput(input)
+    return {
+      meta: {
+        repo,
+        ticketId: id,
+        kind: asset.kind,
+        name: asset.name,
+        layout: asset.layout,
+        revision,
+        createdAt,
+        size,
+        entries: input.entries.map((e) =>
+          e.type === 'dir'
+            ? e
+            : {
+                type: 'file',
+                path: e.path,
+                size: e.content.byteLength,
+                blobRef: contentHash(e.content),
+              },
+        ),
+      },
+      entries: input.entries,
+    }
+  }
+  async getTicketAsset(repo: string, id: string, kind: string, name: string, revision?: number) {
+    const { front } = await this.load(id)
+    const history = (await this.history(id, front))[this.key(kind, name)]
+    if (!history) return null
+    const index = revision === undefined ? history.length - 1 : revision - FIRST_REVISION
+    const item = history[index]
+    return item?.asset
+      ? this.materialize(repo, id, item.asset, FIRST_REVISION + index, item.createdAt)
+      : null
+  }
+  async listTicketAssets(repo: string, id: string) {
+    const { front } = await this.load(id)
+    const history = await this.history(id, front)
+    return Object.values(history).flatMap((items) => {
+      const item = items.at(-1)!
+      return item.asset
+        ? [
+            summarizeTicketAsset(
+              this.materialize(
+                repo,
+                id,
+                item.asset,
+                FIRST_REVISION + items.length - 1,
+                item.createdAt,
+              ).meta,
+            ),
+          ]
+        : []
+    })
+  }
+  private async persist(
+    id: string,
+    history: History,
+    loaded: Awaited<ReturnType<FileTicketAssets['load']>>,
+  ) {
+    const path = this.path(id)
+    await mkdir(join(this.dir, '.ab-assets'), { recursive: true })
+    const temp = `${path}.${crypto.randomUUID()}.tmp`
+    await writeFile(temp, JSON.stringify(history))
+    await rename(temp, path)
+    // The journal is authoritative after interruption; repair the portable projection on retry.
+    loaded.front.attachments = Object.values(history).flatMap((items) =>
+      items.at(-1)!.asset ? [items.at(-1)!.asset!] : [],
+    )
+    await loaded.save(loaded.front)
+  }
+  async putTicketAsset(repo: string, id: string, input: TicketAssetInput) {
+    validateTicketAssetInput(input)
+    const loaded = await this.load(id)
+    if (loaded.exists === false)
+      throw new Error(`file ticket source: asset on unknown ticket "${id}"`)
+    const history = await this.history(id, loaded.front)
+    const key = this.key(input.kind, input.name)
+    const items = history[key] ?? []
+    history[key] = items
+    const asset = encodePortableAsset(input)
+    const createdAt = new Date().toISOString()
+    items.push({ asset, createdAt })
+    await this.persist(id, history, loaded)
+    return this.materialize(repo, id, asset, FIRST_REVISION + items.length - 1, createdAt).meta
+  }
+  async removeTicketAsset(repo: string, id: string, kind: string, name: string) {
+    const current = await this.getTicketAsset(repo, id, kind, name)
+    const loaded = await this.load(id)
+    if (loaded.exists === false)
+      throw new Error(`file ticket source: asset on unknown ticket "${id}"`)
+    const history = await this.history(id, loaded.front)
+    const key = this.key(kind, name)
+    if (history[key]?.at(-1)?.asset === null) return null
+    const items = history[key] ?? []
+    history[key] = items
+    items.push({ asset: null, createdAt: new Date().toISOString() })
+    await this.persist(id, history, loaded)
+    return current?.meta ?? null
+  }
+}

package/packages/core/src/ports/tickets/file-codec.ts

@@ -0,0 +1,90 @@
+import { portableAssetSchema } from './portable-assets'
+import { parse as parseToml, stringify as stringifyToml } from 'smol-toml'
+import { z } from 'zod'
+
+const frontmatterSchema = z.strictObject({
+  comments: z
+    .array(
+      z.strictObject({ body: z.string(), createdAt: z.string(), author: z.string().optional() }),
+    )
+    .optional(),
+  attachments: z
+    .array(portableAssetSchema)
+    .superRefine((assets, ctx) => {
+      const names = new Set<string>()
+      for (const asset of assets) {
+        const key = `${asset.kind}/${asset.name}`
+        if (names.has(key))
+          ctx.addIssue({ code: 'custom', message: `duplicate attachment: ${key}` })
+        names.add(key)
+      }
+    })
+    .optional(),
+  id: z.string().min(1),
+  title: z.string().min(1),
+  labels: z.array(z.string()).default([]),
+  /** Source-local blocker ids (§13). Absent ≡ no dependencies, which keeps
+   * every pre-existing ticket file valid. */
+  blockedBy: z.array(z.string()).optional(),
+  /** Stable external-create adoption key. It travels with the ticket across
+   * state-directory moves, so retries find it in any lifecycle state. */
+  idempotencyKey: z.string().min(1).optional(),
+})
+export type Frontmatter = z.infer<typeof frontmatterSchema>
+
+const OPEN_FENCE = '+++\n'
+const CLOSE_FENCE = '\n+++\n'
+
+/** A malformed record that a complete tracker scan may safely exclude. This is
+ * deliberately narrower than ordinary Error: filesystem failures, layout
+ * violations, duplicate ids, and unexpected exceptions must still abort the
+ * listing. */
+export class TicketFileValidationError extends Error {
+  override readonly name = 'TicketFileValidationError'
+}
+
+export function parseTicketFile(path: string, raw: string): { front: Frontmatter; body: string } {
+  if (!raw.startsWith(OPEN_FENCE)) {
+    throw new TicketFileValidationError(
+      `${path}: malformed ticket file — missing opening "+++" fence`,
+    )
+  }
+  const close = raw.indexOf(CLOSE_FENCE, OPEN_FENCE.length)
+  if (close === -1) {
+    throw new TicketFileValidationError(
+      `${path}: malformed ticket file — missing closing "+++" fence`,
+    )
+  }
+  let parsed: unknown
+  try {
+    parsed = parseToml(raw.slice(OPEN_FENCE.length, close))
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new TicketFileValidationError(`${path}: malformed TOML frontmatter — ${message}`)
+  }
+  const result = frontmatterSchema.safeParse(parsed)
+  if (!result.success) {
+    const issues = result.error.issues
+      .map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`)
+      .join('; ')
+    throw new TicketFileValidationError(`${path}: invalid frontmatter — ${issues}`)
+  }
+  return { front: result.data, body: raw.slice(close + CLOSE_FENCE.length) }
+}
+
+export function serializeTicketFile(front: Frontmatter, body: string): string {
+  const data: Record<string, unknown> = { id: front.id, title: front.title }
+  if (front.labels.length > 0) data.labels = front.labels
+  // Only when nonempty: a file that never declared blockers must round-trip
+  // byte-identically rather than sprouting `blockedBy = []` on every write.
+  if (front.blockedBy !== undefined && front.blockedBy.length > 0) {
+    data.blockedBy = front.blockedBy
+  }
+  if (front.idempotencyKey !== undefined) {
+    data.idempotencyKey = front.idempotencyKey
+  }
+  if (front.comments !== undefined) data.comments = front.comments
+  if (front.attachments !== undefined) data.attachments = front.attachments
+  // smol-toml stringify ends with a newline; the closing fence follows it.
+  return `${OPEN_FENCE}${stringifyToml(data)}+++\n${body}`
+}

package/packages/core/src/ports/tickets/file.ts

@@ -1,3 +1,5 @@
+import { fileRequestedIds, validateFileTicketId } from './requested-id'
+import { FileTicketAssets } from './file-assets'
 /**
  * File-based TicketSource (SPEC §3.2, §13): the default tracker. A directory
  * of state directories — the lifecycle four `triage/ ready/ doing/ done/`
@@ -17,14 +19,28 @@
  * Concurrency: writes locate and validate immediately before a same-path
  * rewrite or same-filesystem rename; there is no filesystem lock. The
  * dispatcher remains the lifecycle single writer (SPEC §12), and concurrent
- * human edits are explicitly last-write-wins. State renames never cross a
+ * unguarded human edits are explicitly last-write-wins. Revision-checked writes
+ * compare the final read, retaining the same unlocked read/write race window. State renames never cross a
  * filesystem: `<dir>/ready` → `<dir>/doing` is one mount by construction.
  */
+import {
+  STATE_NAME_RULE,
+  validateStateName,
+  validateStatePurpose,
+  orderStates,
+  resolveState,
+} from './states'
 import { readdirSync, statSync } from 'node:fs'
 import { mkdir, readdir, readFile, rename, stat, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
-import { parse as parseToml, stringify as stringifyToml } from 'smol-toml'
-import { z } from 'zod'
+import {
+  parseTicketFile,
+  serializeTicketFile,
+  TicketFileValidationError,
+  type Frontmatter,
+} from './file-codec'
+export { TicketFileValidationError } from './file-codec'
+import { ticketRevision, checkTicketRevision } from './revision'
 import { systemClock, type Clock } from '../../store/types'
 import type {
   DependencyState,
@@ -35,6 +51,7 @@ import type {
   TicketSource,
   TicketStateInfo,
   TicketUpdate,
+  TicketMutation,
 } from '../types'
 import { validateTicketUpdate } from './update'
 
@@ -51,116 +68,22 @@ const LIFECYCLE_DIRS = ['triage', 'ready', 'doing', 'done'] as const
  * and non-`.md` files are never tickets, so it can never be mistaken for one. */
 const ABOUT_FILE = '.about'
 
-const STATE_NAME_RULE =
-  'a state name is one to forty characters of lowercase letters, digits, and hyphens, starting with a letter'
-const STATE_NAME_RE = /^[a-z][a-z0-9-]{0,39}$/
+export { validateStateName } from './states'
 
-/** Throws, stating the rule, unless `name` may be used to create a state. */
-export function validateStateName(name: string): void {
-  if (!STATE_NAME_RE.test(name)) {
-    throw new Error(`file ticket source: invalid state name "${name}" — ${STATE_NAME_RULE}`)
-  }
-}
-
-/** The state names a root listing yields: the lifecycle four, then every other
- * non-dot directory alphabetically. Dot entries and files are never states. */
 function statesIn(directories: string[]): string[] {
-  const lifecycle: string[] = [...LIFECYCLE_DIRS]
-  const extra = directories
-    .filter((name) => !name.startsWith('.') && !lifecycle.includes(name))
-    .sort()
-  return [...lifecycle, ...extra]
-}
-
-/**
- * Resolve a state name to its directory. Case-insensitive in (a config's
- * `readyState = "ready"` means the `ready/` directory), the directory's real
- * name out — and a name matching no directory is a loud error, because a
- * typo'd state must not silently create a directory no `ls` would show.
- */
-function resolveState(name: string, existing: string[]): string {
-  if (existing.includes(name)) return name
-  const matches = existing.filter((s) => s.toLowerCase() === name.toLowerCase())
-  if (matches.length === 1) return matches[0] as string
-  if (matches.length > 1) {
-    throw new Error(
-      `file ticket source: ambiguous state "${name}" — it matches the directories ${matches.join(', ')}`,
-    )
-  }
-  throw new Error(
-    `file ticket source: unknown state "${name}" — this tracker's states are ` +
-      `the directories: ${existing.join(', ')}`,
+  return orderStates(
+    [
+      ...new Set([
+        ...LIFECYCLE_DIRS.filter(
+          (name) => !directories.some((dir) => dir.toLowerCase() === name && dir !== name),
+        ),
+        ...directories.filter((name) => !name.startsWith('.')),
+      ]),
+    ],
+    LIFECYCLE_DIRS,
   )
 }
 
-const frontmatterSchema = z.strictObject({
-  id: z.string().min(1),
-  title: z.string().min(1),
-  labels: z.array(z.string()).default([]),
-  /** Source-local blocker ids (§13). Absent ≡ no dependencies, which keeps
-   * every pre-existing ticket file valid. */
-  blockedBy: z.array(z.string()).optional(),
-  /** Stable external-create adoption key. It travels with the ticket across
-   * state-directory moves, so retries find it in any lifecycle state. */
-  idempotencyKey: z.string().min(1).optional(),
-})
-type Frontmatter = z.infer<typeof frontmatterSchema>
-
-const OPEN_FENCE = '+++\n'
-const CLOSE_FENCE = '\n+++\n'
-
-/** A malformed record that a complete tracker scan may safely exclude. This is
- * deliberately narrower than ordinary Error: filesystem failures, layout
- * violations, duplicate ids, and unexpected exceptions must still abort the
- * listing. */
-export class TicketFileValidationError extends Error {
-  override readonly name = 'TicketFileValidationError'
-}
-
-function parseTicketFile(path: string, raw: string): { front: Frontmatter; body: string } {
-  if (!raw.startsWith(OPEN_FENCE)) {
-    throw new TicketFileValidationError(
-      `${path}: malformed ticket file — missing opening "+++" fence`,
-    )
-  }
-  const close = raw.indexOf(CLOSE_FENCE, OPEN_FENCE.length)
-  if (close === -1) {
-    throw new TicketFileValidationError(
-      `${path}: malformed ticket file — missing closing "+++" fence`,
-    )
-  }
-  let parsed: unknown
-  try {
-    parsed = parseToml(raw.slice(OPEN_FENCE.length, close))
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error)
-    throw new TicketFileValidationError(`${path}: malformed TOML frontmatter — ${message}`)
-  }
-  const result = frontmatterSchema.safeParse(parsed)
-  if (!result.success) {
-    const issues = result.error.issues
-      .map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`)
-      .join('; ')
-    throw new TicketFileValidationError(`${path}: invalid frontmatter — ${issues}`)
-  }
-  return { front: result.data, body: raw.slice(close + CLOSE_FENCE.length) }
-}
-
-function serializeTicketFile(front: Frontmatter, body: string): string {
-  const data: Record<string, unknown> = { id: front.id, title: front.title }
-  if (front.labels.length > 0) data.labels = front.labels
-  // Only when nonempty: a file that never declared blockers must round-trip
-  // byte-identically rather than sprouting `blockedBy = []` on every write.
-  if (front.blockedBy !== undefined && front.blockedBy.length > 0) {
-    data.blockedBy = front.blockedBy
-  }
-  if (front.idempotencyKey !== undefined) {
-    data.idempotencyKey = front.idempotencyKey
-  }
-  // smol-toml stringify ends with a newline; the closing fence follows it.
-  return `${OPEN_FENCE}${stringifyToml(data)}+++\n${body}`
-}
-
 /** A ticket file found on disk: its id, its state (= its directory), its path. */
 interface Located {
   id: string
@@ -170,6 +93,8 @@ interface Located {
 
 export class FileTicketSource implements TicketSource {
   readonly name = 'file'
+  readonly requestedIds = fileRequestedIds
+  readonly assets: FileTicketAssets
 
   private readonly dir: string
   private readonly clock: Clock
@@ -198,6 +123,22 @@ export class FileTicketSource implements TicketSource {
      */
     selfIgnore?: boolean
   }) {
+    this.assets = new FileTicketAssets(opts.dir, async (id) => {
+      const found = await this.locate(id)
+      if (!found)
+        return {
+          exists: false,
+          front: { id, title: id, labels: [] },
+          save: async () => {
+            throw new Error(`file ticket source: asset on unknown ticket "${id}"`)
+          },
+        }
+      const loaded = { found, ...(await this.loadAt(found)) }
+      return {
+        ...loaded,
+        save: (front: Frontmatter) => this.rewriteAt(loaded.found, front, loaded.body),
+      }
+    })
     this.dir = opts.dir
     this.clock = opts.clock ?? systemClock
     const existing = this.statesSync()
@@ -273,7 +214,12 @@ export class FileTicketSource implements TicketSource {
       throw new Error(`file ticket source: comment on unknown ticket "${id}"`)
     }
     const raw = await readFile(found.path, 'utf8')
-    parseTicketFile(found.path, raw) // surface malformed files before appending
+    const parsed = parseTicketFile(found.path, raw)
+    if (parsed.front.comments !== undefined) {
+      parsed.front.comments.push({ body, createdAt: this.clock().toISOString() })
+      await this.rewriteAt(found, parsed.front, parsed.body)
+      return
+    }
     const separator = raw.endsWith('\n') ? '\n' : '\n\n'
     const stamp = this.clock().toISOString()
     await writeFile(found.path, `${raw}${separator}## Comment (${stamp})\n\n${body}\n`)
@@ -301,6 +247,7 @@ export class FileTicketSource implements TicketSource {
   /** Writes `<createState>/file-<n>.md` with the next free n (gaps reused),
    * or adopts the ticket carrying the same idempotency key. */
   async create(draft: TicketDraft, opts: TicketCreateOptions = {}): Promise<Ticket> {
+    if (opts.requestedId !== undefined) validateFileTicketId(opts.requestedId)
     await this.ensureLayout()
     // Resolve before anything is read or written: an unknown state touches no file.
     const targetState =
@@ -332,7 +279,8 @@ export class FileTicketSource implements TicketSource {
     let n = 1
     while (taken.has(`file-${n}`)) n += 1
     const front: Frontmatter = {
-      id: `file-${n}`,
+      id: opts.requestedId ?? `file-${n}`,
+      comments: [],
       title: draft.title,
       labels: [...(draft.labels ?? [])],
       ...(draft.blockedBy !== undefined && draft.blockedBy.length > 0
@@ -340,10 +288,50 @@ export class FileTicketSource implements TicketSource {
         : {}),
       ...(opts.idempotencyKey !== undefined ? { idempotencyKey: opts.idempotencyKey } : {}),
     }
-    await writeFile(this.pathIn(targetState, front.id), serializeTicketFile(front, draft.body))
+    if (taken.has(front.id)) throw new Error(`requested ticket id already occupied: ${front.id}`)
+    await writeFile(this.pathIn(targetState, front.id), serializeTicketFile(front, draft.body), {
+      flag: 'wx',
+    })
     return this.toTicket(front, draft.body, targetState)
   }
 
+  async mutateIfRevision(id: string, expected: string, mutation: TicketMutation): Promise<void> {
+    const patch = mutation.kind === 'update' ? validateTicketUpdate(mutation.patch) : undefined
+    await this.ensureLayout()
+    const target =
+      mutation.kind === 'transition' ? resolveState(mutation.state, await this.states()) : undefined
+    if (mutation.kind === 'blockers') {
+      for (const blocker of new Set(mutation.ids)) {
+        if (mutation.operation === 'block' && blocker === id)
+          throw new Error(`ticket "${id}" cannot block itself`)
+        await this.requireForWrite(blocker, 'blocker')
+      }
+    }
+    // Final locate/read immediately precedes the write. This is best effort,
+    // matching unguarded file writes; it does not introduce filesystem locks.
+    const loaded = await this.requireForWrite(id, 'revision-checked write')
+    checkTicketRevision(this.toTicket(loaded.front, loaded.body, loaded.found.state), expected)
+    if (target !== undefined) {
+      if (loaded.found.state !== target) await rename(loaded.found.path, this.pathIn(target, id))
+      return
+    }
+    const front = { ...loaded.front }
+    let body = loaded.body
+    if (patch) {
+      if (patch.title !== undefined) front.title = patch.title
+      if (patch.labels !== undefined) front.labels = patch.labels
+      if (patch.body !== undefined) body = patch.body
+    } else if (mutation.kind === 'blockers') {
+      const blockers = new Set(front.blockedBy ?? [])
+      for (const blocker of mutation.ids) {
+        if (mutation.operation === 'block') blockers.add(blocker)
+        else blockers.delete(blocker)
+      }
+      front.blockedBy = [...blockers]
+    }
+    await this.rewriteAt(loaded.found, front, body)
+  }
+
   async update(id: string, patch: TicketUpdate): Promise<void> {
     const validated = validateTicketUpdate(patch)
     await this.ensureLayout()
@@ -448,10 +436,7 @@ export class FileTicketSource implements TicketSource {
     opts: { about?: string } = {},
   ): Promise<{ state: TicketStateInfo; created: boolean }> {
     validateStateName(name)
-    const about = opts.about === undefined ? undefined : opts.about.trim()
-    if (about !== undefined && (about === '' || /[\r\n]/.test(about))) {
-      throw new Error('file ticket source: a state purpose must be one nonblank line')
-    }
+    const about = validateStatePurpose(opts.about)
     const existing = await this.states()
     const clash = existing.find((s) => s !== name && s.toLowerCase() === name.toLowerCase())
     if (clash !== undefined) {
@@ -537,10 +522,7 @@ export class FileTicketSource implements TicketSource {
   }
 
   private safeId(id: string): string {
-    if (id.includes('/') || id.includes('\\') || id.includes('..')) {
-      throw new Error(`file ticket source: invalid ticket id "${id}"`)
-    }
-    return id
+    return validateFileTicketId(id)
   }
 
   /** Find the one state dir holding `<id>.md`; null when absent. */
@@ -632,7 +614,9 @@ export class FileTicketSource implements TicketSource {
   /** Rewrite only the located file: editable writes can never move lifecycle
    * state because the existing state-directory path remains authoritative. */
   private async rewriteAt(found: Located, front: Frontmatter, body: string): Promise<void> {
-    await writeFile(found.path, serializeTicketFile(front, body))
+    const temp = `${found.path}.${crypto.randomUUID()}.tmp`
+    await writeFile(temp, serializeTicketFile(front, body))
+    await rename(temp, found.path)
   }
 
   private async listAll(): Promise<TicketListing> {
@@ -658,8 +642,18 @@ export class FileTicketSource implements TicketSource {
 
   private toTicket(front: Frontmatter, body: string, state: string): Ticket {
     return {
+      revision: ticketRevision({
+        title: front.title,
+        body,
+        labels: front.labels,
+        state,
+        blockedBy: front.blockedBy,
+        ...(front.comments !== undefined ? { comments: front.comments } : {}),
+        ...(front.attachments !== undefined ? { attachments: front.attachments } : {}),
+      }),
       ref: { source: this.name, id: front.id, title: front.title },
       ...(front.idempotencyKey !== undefined ? { creationKey: front.idempotencyKey } : {}),
+      ...(front.comments !== undefined ? { comments: structuredClone(front.comments) } : {}),
       title: front.title,
       body,
       state,