@defrex/autobuild 0.12.0 → 0.14.0

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

@@ -0,0 +1,18 @@
+import type { TicketsConfig } from '../../config/schema'
+
+/** Resolve names without changing persisted ticket states or their spelling. */
+export function ticketLifecycle(tickets: TicketsConfig, legacyHosted = false) {
+  const hosted = tickets.source === 'hosted'
+  const old = tickets.source === 'linear' || (hosted && legacyHosted)
+  const triage = tickets.triageState ?? (old ? 'Backlog' : hosted ? 'triage' : 'Triage')
+  return {
+    triage,
+    ready: tickets.readyState,
+    doing:
+      tickets.claimedState ??
+      (tickets.source === 'linear' ? 'In Progress' : old ? 'Doing' : 'doing'),
+    done: tickets.doneState ?? (old ? 'Done' : hosted ? 'done' : 'Done'),
+    create: tickets.createState ?? triage,
+    proposal: tickets.proposalState ?? triage,
+  }
+}

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

@@ -1,3 +1,4 @@
+import { ticketRevision } from './revision'
 /**
  * Linear TicketSource (SPEC §3.2, §13): GraphQL over an injectable fetch, so
  * tests run offline against canned exchanges. Queries are deliberately
@@ -109,7 +110,8 @@ interface GqlIssue {
   description: string | null
   url: string
   state: { name: string; type: string } | null
-  labels: { nodes: Array<{ name: string }> }
+  labels: { nodes: Array<{ name: string }>; pageInfo?: PageInfo }
+  comments?: Connection<{ body: string; createdAt: string; user: { name: string } | null }>
   /** Relations where THIS issue is the `relatedIssue` side. A relation
    * `{issue: A, relatedIssue: B, type: "blocks"}` reads "A blocks B", so an
    * issue's blockers are its inverse `blocks` relations, and the blocker is
@@ -237,6 +239,7 @@ function nextCursor(info: PageInfo | undefined, seen: Set<string>): string | nul
   return cursor
 }
 
+const GET_DETAIL_QUERY = `query GetIssue($id: String!) { issue(id: $id) { id identifier title description url state { name type } labels(first: 100) { nodes { name } ${PAGE_INFO} } inverseRelations(first: 100) { nodes { ${READY_RELATIONS} } ${PAGE_INFO} } comments(first: 100, includeArchived: true, orderBy: createdAt) { nodes { body createdAt user { name } } ${PAGE_INFO} } } }`
 const GET_ISSUE_QUERY = `query GetIssue($id: String!) { issue(id: $id) { ${ISSUE_FIELDS} } }`
 const RESOLVE_ISSUE_QUERY = `query ResolveIssue($id: String!) { issue(id: $id) { id } }`
 const ISSUE_STATE_QUERY = `query IssueState($id: String!) { issue(id: $id) { id state { name type } } }`
@@ -343,11 +346,17 @@ export class LinearTicketSource implements TicketSource {
     const seen = new Set<string>()
     let after: string | null = null
     do {
-      const data: { issues: Connection<GqlIssue> } = await this.gql('listReady', LIST_READY_QUERY, {
-        filter,
-        first: READY_PAGE_SIZE,
-        after,
-      })
+      const data: { issues: Connection<GqlIssue> } = await this.gql(
+        'listReady',
+        Object.values(criteria).every((value) => value === undefined)
+          ? LIST_READY_QUERY.replace('after: $after)', 'after: $after, includeArchived: true)')
+          : LIST_READY_QUERY,
+        {
+          filter,
+          first: READY_PAGE_SIZE,
+          after,
+        },
+      )
       await this.completeRelations(data.issues.nodes, true)
       for (const issue of data.issues.nodes) {
         const relations = issue.inverseRelations!.nodes
@@ -369,7 +378,7 @@ export class LinearTicketSource implements TicketSource {
   async get(id: string): Promise<Ticket | null> {
     let data: { issue: GqlIssue | null }
     try {
-      data = await this.gql<{ issue: GqlIssue | null }>('get', GET_ISSUE_QUERY, { id })
+      data = await this.gql<{ issue: GqlIssue | null }>('get', GET_DETAIL_QUERY, { id })
     } catch (error) {
       // Linear's `issue(id:)` field is non-null in the live schema: an unknown
       // identifier arrives as INPUT_ERROR / Entity not found rather than the
@@ -377,7 +386,54 @@ export class LinearTicketSource implements TicketSource {
       if (isEntityNotFound(error)) return null
       throw error
     }
-    return data.issue ? this.toTicket(data.issue) : null
+    if (!data.issue) return null
+    const issue = data.issue
+    // Detail reads exhaust labels and relations independently of dispatch bounds.
+    const labels: Array<{ name: string }> = [...issue.labels.nodes]
+    const labelSeen = new Set<string>()
+    let labelAfter = nextCursor(issue.labels.pageInfo, labelSeen)
+    while (labelAfter !== null) {
+      const page: { issue: { labels: Connection<{ name: string }> } } = await this.gql(
+        'getLabels',
+        `query TicketLabels($id: String!, $after: String) { issue(id: $id) { labels(first: 100, after: $after) { nodes { name } ${PAGE_INFO} } } }`,
+        { id: issue.id ?? id, after: labelAfter },
+      )
+      labels.push(...page.issue.labels.nodes)
+      labelAfter = nextCursor(page.issue.labels.pageInfo, labelSeen)
+    }
+    issue.labels = { nodes: labels }
+    await this.completeRelations([issue], true)
+    const mapComment = (c: { body: string; createdAt: string; user: { name: string } | null }) => ({
+      body: c.body,
+      createdAt: c.createdAt,
+      ...(c.user ? { author: c.user.name } : {}),
+    })
+    const comments: import('../types').TicketComment[] = (issue.comments?.nodes ?? []).map(
+      mapComment,
+    )
+    const seen = new Set<string>()
+    let after = nextCursor(issue.comments?.pageInfo, seen)
+    while (after !== null) {
+      const page: {
+        issue: {
+          comments: Connection<{ body: string; createdAt: string; user: { name: string } | null }>
+        }
+      } = await this.gql(
+        'getComments',
+        `query TicketComments($id: String!, $after: String) { issue(id: $id) { comments(first: 100, after: $after, includeArchived: true, orderBy: createdAt) { nodes { body createdAt user { name } } ${PAGE_INFO} } } }`,
+        { id: issue.id ?? id, after },
+      )
+      comments.push(
+        ...page.issue.comments.nodes.map((c) => ({
+          body: c.body,
+          createdAt: c.createdAt,
+          ...(c.user ? { author: c.user.name } : {}),
+        })),
+      )
+      after = nextCursor(page.issue.comments.pageInfo, seen)
+    }
+    comments.sort((a, b) => Date.parse(a.createdAt) - Date.parse(b.createdAt))
+    return { ...this.toTicket(issue), comments }
   }
 
   /**
@@ -430,6 +486,7 @@ export class LinearTicketSource implements TicketSource {
   }
 
   async create(draft: TicketDraft, opts: TicketCreateOptions = {}): Promise<Ticket> {
+    if (opts.requestedId !== undefined) throw new Error('linear does not support requested ids')
     const reservedId = opts.idempotencyKey
     if (reservedId !== undefined && !linearReservedIssueIdSchema.safeParse(reservedId).success) {
       throw new Error('linear create: idempotency key must be a UUID v4')
@@ -796,7 +853,8 @@ export class LinearTicketSource implements TicketSource {
     // The issue projection predates newly created relations. Preserve native
     // existing blockers and report the requested set now known to be recorded.
     const blockedBy = [...new Set([...blockersOf(issue), ...requested])]
-    return { ...this.toTicket(issue), ...(blockedBy.length > 0 ? { blockedBy } : {}) }
+    const ticket = { ...this.toTicket(issue), ...(blockedBy.length > 0 ? { blockedBy } : {}) }
+    return { ...ticket, revision: ticketRevision(ticket) }
   }
 
   private async adoptCreatedIssue(id: string): Promise<GqlIssue | null> {
@@ -1017,6 +1075,13 @@ export class LinearTicketSource implements TicketSource {
   private toTicket(issue: GqlIssue): Ticket {
     const blockedBy = blockersOf(issue)
     return {
+      revision: ticketRevision({
+        title: issue.title,
+        body: issue.description ?? '',
+        labels: issue.labels.nodes.map((label) => label.name),
+        state: issue.state?.name,
+        blockedBy,
+      }),
       ref: {
         source: this.name,
         id: issue.identifier,

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

@@ -0,0 +1,336 @@
+import { validateTicketAssetInput } from '../../store/ticket-assets'
+import { mkdir, readdir, readFile, rename, rm, rmdir, stat, writeFile } from 'node:fs/promises'
+import { dirname, join, resolve } from 'node:path'
+import { z } from 'zod'
+import type { Ticket, TicketSource, TicketAssetStore } from '../types'
+import { FileTicketSource } from './file'
+import { parseTicketFile, serializeTicketFile } from './file-codec'
+import { validateFileTicketId } from './requested-id'
+import { normalizeStateName } from './states'
+import { encodePortableAsset, decodePortableAsset, type PortableAsset } from './portable-assets'
+
+const MANIFEST = '.ab-migration.json'
+export const IMPORT_MAP = '.ab-import-map.json'
+const manifestSchema = z.strictObject({
+  version: z.literal(1),
+  identity: z.string().min(1),
+  source: z.string(),
+  keys: z.record(z.string(), z.string().min(1)),
+  states: z.record(z.string(), z.string()),
+})
+type Manifest = z.infer<typeof manifestSchema>
+async function atomicJson(path: string, value: unknown) {
+  const temp = `${path}.${crypto.randomUUID()}.tmp`
+  await writeFile(temp, `${JSON.stringify(value, null, 2)}\n`)
+  await rename(temp, path)
+}
+async function inventory(source: TicketSource): Promise<Ticket[]> {
+  const listing = await source.listReady({})
+  if (listing.diagnostics.length)
+    throw new Error(`incomplete ticket scan:\n${listing.diagnostics.join('\n')}`)
+  const ids = new Set<string>()
+  const tickets: Ticket[] = []
+  for (const ticket of listing.tickets) {
+    if (ids.has(ticket.ref.id)) throw new Error(`duplicate ticket id: ${ticket.ref.id}`)
+    ids.add(ticket.ref.id)
+    const detail = await source.get(ticket.ref.id)
+    if (!detail) throw new Error(`ticket disappeared: ${ticket.ref.id}`)
+    if (!detail.state) throw new Error(`ticket has no state: ${ticket.ref.id}`)
+    tickets.push(detail)
+  }
+  return tickets
+}
+function uniqueStateMap(names: string[], map: (name: string) => string): Record<string, string> {
+  const result: Record<string, string> = Object.create(null)
+  const groups = new Map<string, string[]>()
+  for (const name of new Set(names)) {
+    const target = map(name)
+    result[name] = target
+    groups.set(target, [...(groups.get(target) ?? []), name])
+  }
+  const collisions = [...groups].filter(([, originals]) => originals.length > 1)
+  if (collisions.length)
+    throw new Error(
+      `state collisions: ${collisions.map(([target, originals]) => `${originals.join(', ')} → ${target}`).join('; ')}`,
+    )
+  return result
+}
+async function currentAssets(
+  store: TicketAssetStore | undefined,
+  repo: string,
+  id: string,
+): Promise<PortableAsset[]> {
+  if (!store) return []
+  const result: PortableAsset[] = []
+  for (const summary of await store.listTicketAssets(repo, id)) {
+    const asset = await store.getTicketAsset(repo, id, summary.kind, summary.name, summary.revision)
+    if (!asset) throw new Error(`asset disappeared: ${id} ${summary.kind}/${summary.name}`)
+    result.push(encodePortableAsset({ ...asset.meta, entries: asset.entries }))
+  }
+  return result
+}
+export interface MigrationOptions {
+  source: TicketSource
+  dir: string
+  repo: string
+  assets?: TicketAssetStore
+  print?: (line: string) => void
+}
+/** Publish a complete portable tracker only after every source read succeeds. */
+export async function exportTickets(opts: MigrationOptions): Promise<void> {
+  const destination = resolve(opts.dir)
+  try {
+    if ((await readdir(destination)).length)
+      throw new Error(`export destination is not empty: ${destination}`)
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+  }
+  const tickets = await inventory(opts.source)
+  const names = [
+    ...tickets.map((ticket) => ticket.state!),
+    ...((await opts.source.listStates?.()) ?? []).map((state) => state.name),
+  ]
+  const states = uniqueStateMap(names, normalizeStateName)
+  const identity = crypto.randomUUID()
+  const manifest: Manifest = {
+    version: 1,
+    identity,
+    source: `${opts.source.name}:${opts.repo}`,
+    keys: Object.create(null),
+    states,
+  }
+  const records = []
+  for (const ticket of tickets) {
+    validateFileTicketId(ticket.ref.id)
+    const key = ticket.creationKey ?? `migration:${identity}:${ticket.ref.id}`
+    manifest.keys[ticket.ref.id] = key
+    records.push({
+      state: states[ticket.state!]!,
+      id: ticket.ref.id,
+      raw: serializeTicketFile(
+        {
+          id: ticket.ref.id,
+          title: ticket.title,
+          labels: ticket.labels,
+          blockedBy: ticket.blockedBy,
+          idempotencyKey: key,
+          ...(ticket.comments !== undefined ? { comments: ticket.comments } : {}),
+          attachments: await currentAssets(
+            opts.assets ?? opts.source.assets,
+            opts.repo,
+            ticket.ref.id,
+          ),
+        },
+        ticket.body,
+      ),
+    })
+  }
+  await mkdir(dirname(destination), { recursive: true })
+  const staging = `${destination}.${identity}.tmp`
+  await mkdir(staging)
+  try {
+    for (const state of Object.values(states))
+      await mkdir(join(staging, state), { recursive: true })
+    for (const record of records)
+      await writeFile(join(staging, record.state, `${record.id}.md`), record.raw, { flag: 'wx' })
+    await atomicJson(join(staging, MANIFEST), manifest)
+    // Recheck immediately before publication; never remove a populated destination.
+    try {
+      await rmdir(destination)
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+    }
+    await rename(staging, destination)
+  } finally {
+    await rm(staging, { recursive: true, force: true })
+  }
+  opts.print?.(`exported ${tickets.length} tickets to ${destination}`)
+}
+function matchState(name: string, existing: string[]): string | undefined {
+  if (existing.includes(name)) return name
+  const matches = existing.filter((value) => value.toLowerCase() === name.toLowerCase())
+  if (matches.length > 1) throw new Error(`ambiguous target state ${name}: ${matches.join(', ')}`)
+  return matches[0]
+}
+/** Resume through creation keys, never through content similarity or mapping files. */
+export async function importTickets(opts: MigrationOptions): Promise<void> {
+  const policy = opts.source.requestedIds
+  if (!policy || !opts.source.listStates || !opts.source.addState)
+    throw new Error(`ticket source ${opts.source.name} does not support import`)
+  const dir = resolve(opts.dir)
+  const input = new FileTicketSource({ dir })
+  const tickets = await inventory(input)
+  const bundles = new Map<string, PortableAsset[]>()
+  for (const ticket of tickets) {
+    const path = join(dir, ticket.state!, `${ticket.ref.id}.md`)
+    bundles.set(
+      ticket.ref.id,
+      parseTicketFile(path, await readFile(path, 'utf8')).front.attachments ?? [],
+    )
+  }
+  let manifest: Manifest
+  try {
+    manifest = manifestSchema.parse(JSON.parse(await readFile(join(dir, MANIFEST), 'utf8')))
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+    manifest = {
+      version: 1,
+      identity: crypto.randomUUID(),
+      source: 'file',
+      keys: Object.create(null),
+      states: {},
+    }
+  }
+  const sourceIds = new Set(tickets.map((ticket) => ticket.ref.id))
+  const keys = new Set<string>()
+  for (const ticket of tickets) {
+    for (const blocker of ticket.blockedBy ?? [])
+      if (!sourceIds.has(blocker) || blocker === ticket.ref.id)
+        throw new Error(`invalid blocker ${ticket.ref.id} → ${blocker}`)
+    const key =
+      ticket.creationKey ??
+      manifest.keys[ticket.ref.id] ??
+      `migration:${manifest.identity}:${ticket.ref.id}`
+    if (keys.has(key)) throw new Error(`duplicate creation key: ${key}`)
+    keys.add(key)
+    manifest.keys[ticket.ref.id] = key
+  }
+  const target = await inventory(opts.source)
+  const byKey = new Map<string, Ticket>()
+  for (const ticket of target)
+    if (ticket.creationKey) {
+      if (byKey.has(ticket.creationKey))
+        throw new Error(`ambiguous target creation key: ${ticket.creationKey}`)
+      byKey.set(ticket.creationKey, ticket)
+    }
+  const existingStates = (await opts.source.listStates()).map((state) => state.name)
+  // Only actual input directories participate; virtual lifecycle defaults are harmless empty states.
+  const inputStates: string[] = []
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    if (
+      !entry.name.startsWith('.') &&
+      (entry.isDirectory() ||
+        (entry.isSymbolicLink() && (await stat(join(dir, entry.name))).isDirectory()))
+    )
+      inputStates.push(entry.name)
+  }
+  const states = uniqueStateMap(
+    inputStates,
+    (name) =>
+      matchState(name, existingStates) ??
+      matchState(normalizeStateName(name), existingStates) ??
+      normalizeStateName(name),
+  )
+  const planned = new Map<string, string>()
+  const occupied = target.map((ticket) => ticket.ref.id)
+  const clashes: string[] = []
+  for (const ticket of tickets) {
+    const adopted = byKey.get(manifest.keys[ticket.ref.id]!)
+    if (adopted) {
+      planned.set(ticket.ref.id, adopted.ref.id)
+      continue
+    }
+    const kept = policy.preserve(ticket.ref.id)
+    if (kept !== undefined) {
+      if (occupied.includes(kept)) clashes.push(`${ticket.ref.id} → ${kept}`)
+      planned.set(ticket.ref.id, kept)
+      occupied.push(kept)
+    }
+  }
+  if (clashes.length)
+    throw new Error(`ticket id clashes (no target changes):\n${clashes.join('\n')}`)
+  for (const ticket of tickets)
+    if (!planned.has(ticket.ref.id)) {
+      const id = policy.allocate(occupied)
+      planned.set(ticket.ref.id, id)
+      occupied.push(id)
+    }
+  const assets = opts.assets ?? opts.source.assets
+  if ([...bundles.values()].some((value) => value.length) && !assets)
+    throw new Error('target has no attachment capability')
+  if (assets && [...bundles.values()].some((value) => value.length)) {
+    const limits = await assets.ticketAssetLimits(opts.repo)
+    for (const values of bundles.values())
+      for (const bundle of values) validateTicketAssetInput(decodePortableAsset(bundle), limits)
+  }
+  for (const ticket of tickets) {
+    const adopted = byKey.get(manifest.keys[ticket.ref.id]!)
+    if ((ticket.comments?.length ?? 0) > 0 && adopted && adopted.comments === undefined)
+      throw new Error(`target cannot read comment history: ${adopted.ref.id}`)
+  }
+  // Persist identities before the first target write, including for ordinary layouts.
+  await atomicJson(join(dir, MANIFEST), manifest)
+  const mapping: Record<string, string> = Object.create(null)
+  const mappingPath = join(dir, IMPORT_MAP)
+  const saveMap = () =>
+    atomicJson(mappingPath, { version: 1, identity: manifest.identity, states, tickets: mapping })
+  await saveMap()
+  try {
+    for (const state of new Set(Object.values(states)))
+      if (!existingStates.includes(state)) {
+        try {
+          await opts.source.addState(state)
+        } catch (error) {
+          const discovered = matchState(
+            state,
+            (await opts.source.listStates()).map((item) => item.name),
+          )
+          if (!discovered) throw error
+          for (const original of Object.keys(states))
+            if (states[original] === state) states[original] = discovered
+          await saveMap()
+        }
+      }
+    for (const [from, to] of Object.entries(states)) opts.print?.(`state ${from} → ${to}`)
+    for (const ticket of tickets) {
+      const key = manifest.keys[ticket.ref.id]!
+      const result =
+        byKey.get(key) ??
+        (await opts.source.create(
+          { title: ticket.title, body: ticket.body, labels: ticket.labels },
+          {
+            state: states[ticket.state!]!,
+            idempotencyKey: key,
+            requestedId: planned.get(ticket.ref.id)!,
+          },
+        ))
+      mapping[ticket.ref.id] = result.ref.id
+      await saveMap()
+      opts.print?.(`${ticket.ref.id} → ${result.ref.id}`)
+    }
+    for (const ticket of tickets) {
+      const id = mapping[ticket.ref.id]!
+      for (const blocker of ticket.blockedBy ?? [])
+        await opts.source.addBlocker(id, mapping[blocker]!)
+      const fresh = await opts.source.get(id)
+      if (!fresh) throw new Error(`target disappeared: ${id}`)
+      if ((ticket.comments?.length ?? 0) && fresh.comments === undefined)
+        throw new Error(`target cannot read comment history: ${id}`)
+      const bodies = new Set(fresh.comments?.map((comment) => comment.body))
+      for (const comment of ticket.comments ?? [])
+        if (!bodies.has(comment.body)) {
+          await opts.source.comment(id, comment.body)
+          bodies.add(comment.body)
+        }
+      for (const bundle of bundles.get(ticket.ref.id) ?? []) {
+        const current = await assets!.getTicketAsset(opts.repo, id, bundle.kind, bundle.name)
+        const canonical = (asset: PortableAsset) =>
+          JSON.stringify({
+            ...asset,
+            entries: [...asset.entries].sort((a, b) => a.path.localeCompare(b.path)),
+          })
+        if (
+          !current ||
+          canonical(encodePortableAsset({ ...current.meta, entries: current.entries })) !==
+            canonical(bundle)
+        )
+          await assets!.putTicketAsset(opts.repo, id, decodePortableAsset(bundle))
+      }
+    }
+    opts.print?.(`mapping: ${mappingPath}`)
+  } catch (error) {
+    throw new Error(
+      `${error instanceof Error ? error.message : error}\nImport progress retained in ${mappingPath}; rerun import to finish.`,
+    )
+  }
+}

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

@@ -1,3 +1,8 @@
+import {
+  mutateTicketIfRevision,
+  TicketRevisionConflict,
+  TicketRevisionUnsupported,
+} from './revision'
 import type { Config } from '../../config/schema'
 import { readyCriteria } from '../../processes/dispatcher'
 import type { Ticket, TicketDraft, TicketSource, TicketUpdate } from '../types'
@@ -91,6 +96,8 @@ export async function createTicket(
       ? await source.create(draft)
       : await source.create(draft, { state: input.state })
   } catch (error) {
+    if (error instanceof TicketRevisionConflict || error instanceof TicketRevisionUnsupported)
+      throw error
     throw new TicketOperationError(
       'refusal',
       error instanceof Error ? error.message : String(error),
@@ -103,10 +110,15 @@ export async function updateTicket(
   id: string,
   patch: TicketUpdate,
   readAfter = true,
+  expectedRevision?: string,
 ): Promise<Ticket | null> {
   try {
-    await source.update(id, patch)
+    if (expectedRevision !== undefined)
+      await mutateTicketIfRevision(source, id, expectedRevision, { kind: 'update', patch })
+    else await source.update(id, patch)
   } catch (error) {
+    if (error instanceof TicketRevisionConflict || error instanceof TicketRevisionUnsupported)
+      throw error
     throw new TicketOperationError(
       'refusal',
       error instanceof Error ? error.message : String(error),
@@ -115,11 +127,20 @@ export async function updateTicket(
   return readAfter ? requirePostMutationTicket(source, id, 'the update') : null
 }
 
-export async function moveTicket(source: TicketSource, id: string, state: string): Promise<Ticket> {
+export async function moveTicket(
+  source: TicketSource,
+  id: string,
+  state: string,
+  expectedRevision?: string,
+): Promise<Ticket> {
   await requireTicket(source, id)
   try {
-    await source.transition(id, state)
+    if (expectedRevision !== undefined)
+      await mutateTicketIfRevision(source, id, expectedRevision, { kind: 'transition', state })
+    else await source.transition(id, state)
   } catch (error) {
+    if (error instanceof TicketRevisionConflict || error instanceof TicketRevisionUnsupported)
+      throw error
     throw new TicketOperationError(
       'refusal',
       error instanceof Error ? error.message : String(error),
@@ -133,6 +154,7 @@ export async function changeBlockers(
   id: string,
   blockerIds: string[],
   operation: 'block' | 'unblock',
+  expectedRevision?: string,
 ): Promise<Ticket> {
   await requireTicket(source, id)
   const ids = await knownBlockers(source, blockerIds, '')
@@ -143,11 +165,20 @@ export async function changeBlockers(
     )
   }
   try {
-    for (const blockerId of ids) {
-      if (operation === 'block') await source.addBlocker(id, blockerId)
-      else await source.removeBlocker(id, blockerId)
-    }
+    if (expectedRevision !== undefined)
+      await mutateTicketIfRevision(source, id, expectedRevision, {
+        kind: 'blockers',
+        operation,
+        ids,
+      })
+    else
+      for (const blockerId of ids) {
+        if (operation === 'block') await source.addBlocker(id, blockerId)
+        else await source.removeBlocker(id, blockerId)
+      }
   } catch (error) {
+    if (error instanceof TicketRevisionConflict || error instanceof TicketRevisionUnsupported)
+      throw error
     throw new TicketOperationError(
       'refusal',
       error instanceof Error ? error.message : String(error),

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

@@ -0,0 +1,54 @@
+import { z } from 'zod'
+import { validateTicketAssetInput, type TicketAssetInput } from '../../store/ticket-assets'
+
+export const portableAssetSchema = z
+  .strictObject({
+    kind: z.string(),
+    name: z.string(),
+    layout: z.enum(['file', 'tree']),
+    entries: z.array(
+      z.discriminatedUnion('type', [
+        z.strictObject({ type: z.literal('dir'), path: z.string() }),
+        z.strictObject({
+          type: z.literal('file'),
+          path: z.string(),
+          base64: z
+            .string()
+            .regex(/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/),
+        }),
+      ]),
+    ),
+  })
+  .superRefine((value, ctx) => {
+    try {
+      validateTicketAssetInput(decodePortableAsset(value))
+    } catch (error) {
+      ctx.addIssue({ code: 'custom', message: String(error) })
+    }
+  })
+export type PortableAsset = z.infer<typeof portableAssetSchema>
+export function decodePortableAsset(value: PortableAsset): TicketAssetInput {
+  return {
+    kind: value.kind,
+    name: value.name,
+    layout: value.layout,
+    entries: value.entries.map((entry) =>
+      entry.type === 'dir'
+        ? entry
+        : { type: 'file', path: entry.path, content: Buffer.from(entry.base64, 'base64') },
+    ),
+  }
+}
+export function encodePortableAsset(input: TicketAssetInput): PortableAsset {
+  validateTicketAssetInput(input)
+  return {
+    kind: input.kind,
+    name: input.name,
+    layout: input.layout,
+    entries: input.entries.map((entry) =>
+      entry.type === 'dir'
+        ? entry
+        : { type: 'file', path: entry.path, base64: Buffer.from(entry.content).toString('base64') },
+    ),
+  }
+}