@defrex/autobuild 0.8.0 → 0.9.0

package/packages/core/src/store/ticket-assets.ts

@@ -0,0 +1,425 @@
+/**
+ * Ticket assets (SPEC §7.1): named, versioned bundles of files attached to a
+ * ticket and kept in the BuildStore, keyed by `(repo, ticketId, kind, name)`.
+ * The ticket source never stores the contents; it only gets a note through
+ * `TicketSource.comment()` (SPEC §13).
+ *
+ * This module is the shared, adapter-independent half: the types, the limits,
+ * and the one validator every adapter calls before any write.
+ */
+
+import type { AbEvent } from '../events/catalog'
+import type { PinnedAsset } from '../events/payloads'
+import { contentHash, type BlobStore, type BuildStore } from './types'
+
+export type { PinnedAsset }
+
+/** Total file bytes per revision (25 MiB). */
+export const TICKET_ASSET_MAX_BYTES = 25 * 1024 * 1024
+/** Files plus directories per revision. */
+export const TICKET_ASSET_MAX_ENTRIES = 1000
+/** UTF-8 bytes per entry path. */
+export const TICKET_ASSET_MAX_PATH_BYTES = 256
+/** UTF-8 bytes per path segment. */
+export const TICKET_ASSET_MAX_SEGMENT_BYTES = 128
+/** Kind and name length. */
+export const TICKET_ASSET_MAX_LABEL_LENGTH = 64
+
+/** Worst-case JSON envelope around the entries of one put request. */
+export const WIRE_ENVELOPE_BYTES = 1024
+/** Worst-case JSON per entry besides base64 content: a maximum-length path
+ * plus keys, quotes, commas, the type tag, and base64 padding. */
+export const WIRE_ENTRY_BYTES = TICKET_ASSET_MAX_PATH_BYTES + 64
+
+export type TicketAssetLayout = 'file' | 'tree'
+
+/** An entry is a file or an explicit directory. Paths are relative and
+ * '/'-separated (`index.html`, `img/a.png`, `img/empty`). */
+export type TicketAssetEntryInput =
+  | { type: 'file'; path: string; content: Uint8Array }
+  | { type: 'dir'; path: string }
+
+export interface TicketAssetInput {
+  kind: string
+  name: string
+  layout: TicketAssetLayout
+  entries: TicketAssetEntryInput[]
+}
+
+export type TicketAssetEntry =
+  | { type: 'file'; path: string; size: number; blobRef: string }
+  | { type: 'dir'; path: string }
+
+export interface TicketAssetMeta {
+  repo: string
+  ticketId: string
+  kind: string
+  name: string
+  /** 0-based per `(repo, ticketId, kind, name)`. A removal consumes a number
+   * too (a tombstone), so revisions may skip. */
+  revision: number
+  layout: TicketAssetLayout
+  /** Total file bytes. */
+  size: number
+  entries: TicketAssetEntry[]
+  createdAt: string
+}
+
+/** What `listTicketAssets` returns on every adapter: the metadata without
+ * the manifest. */
+export interface TicketAssetSummary {
+  repo: string
+  ticketId: string
+  kind: string
+  name: string
+  revision: number
+  layout: TicketAssetLayout
+  size: number
+  fileCount: number
+  dirCount: number
+  createdAt: string
+}
+
+export type TicketAssetContentEntry =
+  | { type: 'file'; path: string; content: Uint8Array }
+  | { type: 'dir'; path: string }
+
+export interface TicketAsset {
+  meta: TicketAssetMeta
+  entries: TicketAssetContentEntry[]
+}
+
+export interface TicketAssetLimits {
+  maxBytes: number
+  maxEntries: number
+}
+
+export const DEFAULT_TICKET_ASSET_LIMITS: TicketAssetLimits = {
+  maxBytes: TICKET_ASSET_MAX_BYTES,
+  maxEntries: TICKET_ASSET_MAX_ENTRIES,
+}
+
+export class TicketAssetValidationError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'TicketAssetValidationError'
+  }
+}
+
+export function summarizeTicketAsset(meta: TicketAssetMeta): TicketAssetSummary {
+  let fileCount = 0
+  let dirCount = 0
+  for (const entry of meta.entries) {
+    if (entry.type === 'file') fileCount += 1
+    else dirCount += 1
+  }
+  return {
+    repo: meta.repo,
+    ticketId: meta.ticketId,
+    kind: meta.kind,
+    name: meta.name,
+    revision: meta.revision,
+    layout: meta.layout,
+    size: meta.size,
+    fileCount,
+    dirCount,
+    createdAt: meta.createdAt,
+  }
+}
+
+function formatBytes(bytes: number): string {
+  const mib = bytes / (1024 * 1024)
+  if (bytes >= 1024 * 1024 && Number.isInteger(mib)) return `${mib} MiB`
+  if (bytes >= 1024 * 1024) return `${mib.toFixed(1)} MiB`
+  if (bytes >= 1024 && bytes % 1024 === 0) return `${bytes / 1024} KiB`
+  return `${bytes} bytes`
+}
+
+/** The limit-naming error for an over-size revision. `size` is the total file
+ * bytes the caller tried to store. */
+export function ticketAssetSizeError(size: number, limit: number): TicketAssetValidationError {
+  return new TicketAssetValidationError(
+    `ticket asset exceeds the ${limit}-byte (${formatBytes(limit)}) limit: ${size} bytes`,
+  )
+}
+
+export function ticketAssetEntriesError(count: number, limit: number): TicketAssetValidationError {
+  return new TicketAssetValidationError(
+    `ticket asset exceeds the ${limit}-entry limit: ${count} entries (files plus directories)`,
+  )
+}
+
+/** The effective limits of a store whose requests and responses can carry at
+ * most `maxRequestBytes`. Paths and entry counts are bounded, so the worst-case
+ * wire overhead is a constant; base64 inflates content by 4/3. A safe lower
+ * bound: the client's exact-size check is the final authority. */
+export function effectiveTicketAssetLimits(maxRequestBytes?: number): TicketAssetLimits {
+  if (maxRequestBytes === undefined) return { ...DEFAULT_TICKET_ASSET_LIMITS }
+  const overhead = WIRE_ENVELOPE_BYTES + TICKET_ASSET_MAX_ENTRIES * WIRE_ENTRY_BYTES
+  return {
+    maxBytes: Math.min(
+      TICKET_ASSET_MAX_BYTES,
+      Math.max(0, Math.floor(((maxRequestBytes - overhead) * 3) / 4)),
+    ),
+    maxEntries: TICKET_ASSET_MAX_ENTRIES,
+  }
+}
+
+const LABEL_PATTERN = /^[A-Za-z0-9._-]+$/
+
+export function validateTicketAssetLabel(field: 'kind' | 'name', value: string): void {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new TicketAssetValidationError(`ticket asset ${field} is required`)
+  }
+  if (value.length > TICKET_ASSET_MAX_LABEL_LENGTH) {
+    throw new TicketAssetValidationError(
+      `ticket asset ${field} must be at most ${TICKET_ASSET_MAX_LABEL_LENGTH} characters`,
+    )
+  }
+  if (!LABEL_PATTERN.test(value) || value === '.' || value === '..') {
+    throw new TicketAssetValidationError(
+      `ticket asset ${field} "${value}" may contain only letters, digits, '.', '_' and '-'`,
+    )
+  }
+}
+
+const encoder = new TextEncoder()
+
+/** One entry path: relative, '/'-separated, no empty/`.`/`..` segments, no
+ * NUL, bounded. */
+export function validateTicketAssetPath(path: string): void {
+  if (typeof path !== 'string' || path === '') {
+    throw new TicketAssetValidationError('ticket asset entry path is required')
+  }
+  if (path.includes('\0')) {
+    throw new TicketAssetValidationError(`ticket asset entry path "${path}" contains a NUL byte`)
+  }
+  if (path.includes('\\')) {
+    throw new TicketAssetValidationError(
+      `ticket asset entry path "${path}" must use '/' separators`,
+    )
+  }
+  if (encoder.encode(path).length > TICKET_ASSET_MAX_PATH_BYTES) {
+    throw new TicketAssetValidationError(
+      `ticket asset entry path exceeds ${TICKET_ASSET_MAX_PATH_BYTES} bytes: "${path.slice(0, 40)}…"`,
+    )
+  }
+  if (path.startsWith('/')) {
+    throw new TicketAssetValidationError(`ticket asset entry path "${path}" must be relative`)
+  }
+  for (const segment of path.split('/')) {
+    if (segment === '' || segment === '.' || segment === '..') {
+      throw new TicketAssetValidationError(
+        `ticket asset entry path "${path}" has an empty, '.' or '..' segment`,
+      )
+    }
+    if (encoder.encode(segment).length > TICKET_ASSET_MAX_SEGMENT_BYTES) {
+      throw new TicketAssetValidationError(
+        `ticket asset entry path segment exceeds ${TICKET_ASSET_MAX_SEGMENT_BYTES} bytes in "${path.slice(0, 40)}…"`,
+      )
+    }
+  }
+}
+
+/** Shape and structure of a manifest, independent of content: shared by put
+ * validation and the remote server's check of an incoming request. Returns
+ * the total file bytes. */
+export function validateTicketAssetStructure(
+  input: {
+    kind: string
+    name: string
+    layout: TicketAssetLayout
+    entries: ({ type: 'file'; path: string; size: number } | { type: 'dir'; path: string })[]
+  },
+  limits: TicketAssetLimits = DEFAULT_TICKET_ASSET_LIMITS,
+): number {
+  validateTicketAssetLabel('kind', input.kind)
+  validateTicketAssetLabel('name', input.name)
+  if (input.layout !== 'file' && input.layout !== 'tree') {
+    throw new TicketAssetValidationError(`ticket asset layout must be 'file' or 'tree'`)
+  }
+  const files = input.entries.filter((entry) => entry.type === 'file')
+  if (input.layout === 'file') {
+    if (input.entries.length !== 1 || files.length !== 1) {
+      throw new TicketAssetValidationError(
+        `a 'file' ticket asset has exactly one file entry and no directories`,
+      )
+    }
+    if (files[0]?.path.includes('/')) {
+      throw new TicketAssetValidationError(`a 'file' ticket asset's path is its filename`)
+    }
+  }
+  if (input.entries.length > limits.maxEntries) {
+    throw ticketAssetEntriesError(input.entries.length, limits.maxEntries)
+  }
+  const kinds = new Map<string, 'file' | 'dir'>()
+  let size = 0
+  for (const entry of input.entries) {
+    if (entry.type !== 'file' && entry.type !== 'dir') {
+      throw new TicketAssetValidationError(`ticket asset entry type must be 'file' or 'dir'`)
+    }
+    validateTicketAssetPath(entry.path)
+    if (kinds.has(entry.path)) {
+      throw new TicketAssetValidationError(`duplicate ticket asset entry path "${entry.path}"`)
+    }
+    kinds.set(entry.path, entry.type)
+    if (entry.type === 'file') size += entry.size
+  }
+  for (const [path] of kinds) {
+    const segments = path.split('/')
+    for (let end = 1; end < segments.length; end += 1) {
+      const ancestor = segments.slice(0, end).join('/')
+      if (kinds.get(ancestor) === 'file') {
+        throw new TicketAssetValidationError(
+          `ticket asset entry "${path}" has a file as its ancestor directory "${ancestor}"`,
+        )
+      }
+    }
+  }
+  if (size > limits.maxBytes) throw ticketAssetSizeError(size, limits.maxBytes)
+  return size
+}
+
+/** The one validator every adapter calls before any write. Throws
+ * `TicketAssetValidationError`; returns the total file bytes. */
+export function validateTicketAssetInput(
+  input: TicketAssetInput,
+  limits: TicketAssetLimits = DEFAULT_TICKET_ASSET_LIMITS,
+): number {
+  return validateTicketAssetStructure(
+    {
+      kind: input.kind,
+      name: input.name,
+      layout: input.layout,
+      entries: input.entries.map((entry) =>
+        entry.type === 'file'
+          ? { type: 'file', path: entry.path, size: entry.content.byteLength }
+          : { type: 'dir', path: entry.path },
+      ),
+    },
+    limits,
+  )
+}
+
+/** Write each file's bytes to the blob store (content-addressed) and build the
+ * manifest. Call only after `validateTicketAssetInput`. */
+export async function storeTicketAssetBlobs(
+  blobs: BlobStore,
+  entries: TicketAssetEntryInput[],
+): Promise<TicketAssetEntry[]> {
+  const manifest: TicketAssetEntry[] = []
+  for (const entry of entries) {
+    if (entry.type === 'dir') {
+      manifest.push({ type: 'dir', path: entry.path })
+      continue
+    }
+    const blobRef = contentHash(entry.content)
+    await blobs.put(blobRef, entry.content)
+    manifest.push({ type: 'file', path: entry.path, size: entry.content.byteLength, blobRef })
+  }
+  return manifest
+}
+
+/** Read the bytes of one manifest file; a missing blob is store corruption. */
+export async function readTicketAssetBlob(
+  blobs: BlobStore,
+  meta: TicketAssetMeta,
+  entry: { path: string; blobRef: string },
+): Promise<Uint8Array> {
+  const bytes = await blobs.get(entry.blobRef)
+  if (!bytes) {
+    throw new Error(
+      `ticket asset ${meta.kind}/${meta.name} revision ${meta.revision}: blob for "${entry.path}" is missing`,
+    )
+  }
+  return bytes
+}
+
+/** Load a manifest's full content (every adapter's `getTicketAsset` tail). */
+export async function loadTicketAsset(
+  blobs: BlobStore,
+  meta: TicketAssetMeta,
+): Promise<TicketAsset> {
+  const entries: TicketAssetContentEntry[] = []
+  for (const entry of meta.entries) {
+    entries.push(
+      entry.type === 'dir'
+        ? { type: 'dir', path: entry.path }
+        : {
+            type: 'file',
+            path: entry.path,
+            content: await readTicketAssetBlob(blobs, meta, entry),
+          },
+    )
+  }
+  return { meta: structuredClone(meta), entries }
+}
+
+/** What a build pins of one asset revision: the summary minus the ticket
+ * coordinates and timestamp, which the build record already carries. */
+export function pinnedAssetOf(summary: TicketAssetSummary): PinnedAsset {
+  return {
+    kind: summary.kind,
+    name: summary.name,
+    revision: summary.revision,
+    layout: summary.layout,
+    size: summary.size,
+    fileCount: summary.fileCount,
+    dirCount: summary.dirCount,
+  }
+}
+
+/** The set of ticket assets to freeze for a claim or a spec re-pin: every
+ * current (live) asset of the ticket, in `listTicketAssets` order. */
+export async function samplePinnedAssets(
+  store: Pick<BuildStore, 'listTicketAssets'>,
+  repo: string,
+  ticketId: string,
+): Promise<PinnedAsset[]> {
+  return (await store.listTicketAssets(repo, ticketId)).map(pinnedAssetOf)
+}
+
+/** Latest-pinned revision of `kind/name` as the build's events record it, or
+ * (with `rev`) the revision when any pin in the log named it. */
+export function findPinnedRevision(
+  events: AbEvent[],
+  kind: string,
+  name: string,
+  rev?: number,
+): number | undefined {
+  let latest: number | undefined
+  for (const event of events) {
+    if (event.type !== 'build.created' && event.type !== 'spec.revised') continue
+    const assets = event.payload.assets
+    if (assets === undefined) continue
+    if (rev !== undefined) {
+      if (assets.some((a) => a.kind === kind && a.name === name && a.revision === rev)) return rev
+      continue
+    }
+    // Each pin event replaces the set, so the newest event that carries a set
+    // decides; absent from that set means unpinned.
+    latest = assets.find((a) => a.kind === kind && a.name === name)?.revision
+  }
+  return latest
+}
+
+/** `BuildStore.getPinnedTicketAsset` for any adapter: read the build's own
+ * events to find the pinned revision, then fetch exactly that revision from the
+ * ticket's assets. Earlier revisions stay retrievable after a replace or a
+ * removal (SPEC §7.1), so the bytes can never drift, and no lease or liveness is
+ * needed, so a finished build still answers. Null when the build never pinned
+ * `kind/name` (or the revision). Rejects an unknown build. */
+export async function resolvePinnedAsset(
+  store: Pick<BuildStore, 'getBuild' | 'getEvents' | 'getTicketAsset'>,
+  slug: string,
+  kind: string,
+  name: string,
+  rev?: number,
+): Promise<TicketAsset | null> {
+  const record = await store.getBuild(slug)
+  if (record === null) throw new Error(`unknown build "${slug}"`)
+  if (record.ticket === undefined) return null
+  const revision = findPinnedRevision(await store.getEvents(slug), kind, name, rev)
+  if (revision === undefined) return null
+  return store.getTicketAsset(record.repo, record.ticket.id, kind, name, revision)
+}

package/packages/core/src/store/types.ts

@@ -24,7 +24,15 @@ import type {
   SessionEventType,
   SessionEventWrite,
 } from '../events/sessions'
+export type { SessionEventEnvelope }
 import type { TicketRef } from '../ontology'
+import type {
+  TicketAsset,
+  TicketAssetInput,
+  TicketAssetLimits,
+  TicketAssetMeta,
+  TicketAssetSummary,
+} from './ticket-assets'
 import type {
   StreamChunk,
   StreamOutcome,
@@ -64,6 +72,12 @@ export interface NewBuildInput {
   repoOrigin?: string
   ticket?: TicketRef
   branch?: string
+  /** The build's `build.created` fact, appended as seq 1 in the same atomic
+   * step as the record: both exist or neither does, so the claim-time facts it
+   * freezes (ticket assets, SPEC §6.3) can never be lost to a crash between
+   * the two writes. An invalid payload, or any other event type, rejects and
+   * creates nothing. */
+  created?: EventWrite<'build.created'>
 }
 
 export interface ArtifactMeta {
@@ -77,6 +91,32 @@ export interface ArtifactMeta {
   createdAt: string
 }
 
+/** The projection of one build's event log onto exactly the two facts an
+ * operator dashboard needs from every build (AUT-487): the latest terminal
+ * fact's kind — `done` for `build.completed`, `aborted` for `build.aborted`,
+ * in-order overwrite, exactly `reduceBuild`'s terminal rule — and the seqs of
+ * the log's `observation.recorded` occurrences. `terminal` is absent while
+ * the log carries neither terminal fact (a queued, running, paused, blocked,
+ * or mid-cleanup build). Everything else a dashboard shows comes from the
+ * journal, the build records, and the full histories of just the builds that
+ * render rows. Nothing is persisted: every adapter derives the digest from
+ * the event log on each call, so the log stays the sole authority and the
+ * digest can always be discarded and rebuilt. */
+export interface BuildDigest {
+  slug: string
+  terminal?: 'done' | 'aborted'
+  /** Ascending-seq `{seq, ts}` pairs for every `observation.recorded` in the
+   * build's log; `ts` is the event envelope timestamp (AUT-521: the harvest
+   * pressure gate measures drift from the oldest unclaimed occurrence's ts,
+   * so per-occurrence timestamps travel with the digest). */
+  observations: { seq: number; ts: string }[]
+  /** Envelope ts of the log's latest `pr.merged` event, absent when the log
+   * has none (AUT-521: latest-wins suffices for drift, which counts a build
+   * when any of its merges is strictly after the oldest unclaimed
+   * observation). */
+  merged?: string
+}
+
 export interface RepositoryRecord {
   repo: string
   createdAt: string
@@ -103,7 +143,8 @@ export interface RepositoryArtifact {
 /** An operator session: hosted-only durable orchestrator-conversation state
  * (SPEC §7.1.1). The record carries only identity and timestamps; everything
  * else — status, open turn, pending approval, wake settings — is a reduction
- * of the session's own event log (sessions/reducer.ts), never a column. */
+ * of the session's own event log (the hosted package's session-reducer.ts),
+ * never a column. */
 export interface SessionRecord {
   /** Store-assigned (`os_<uuid>`). */
   id: string
@@ -257,6 +298,18 @@ export interface BuildStore {
     opts?: { waitSeconds?: number; signal?: AbortSignal },
   ): Promise<AbEvent[]>
 
+  /** One entry for EVERY build whose record's repo is `repo` (completeness is
+   * contractual: a freshly created build whose log holds none of the
+   * digest-relevant event types still gets its entry, with empty
+   * `observations` and no `terminal`), keyed by slug. A read-only, repo-scoped
+   * batch query shaped like `listBuilds`: it performs no `ensureRepo`, never
+   * writes, and an unknown or build-less repo answers an empty map rather
+   * than rejecting. Derived from the event log on every call — the log is the
+   * sole authority, so there is nothing to refresh or invalidate. The
+   * derivation is the shared `reduceBuildDigest` (store/digest.ts), so every
+   * adapter answers identical results for identical logs. */
+  getRepoBuildDigests(repo: string): Promise<Map<string, BuildDigest>>
+
   putArtifact(slug: string, artifact: ArtifactInput): Promise<ArtifactMeta>
   /** Latest revision when `rev` is omitted; null if kind (or rev) absent. */
   getArtifact(slug: string, kind: string, rev?: number): Promise<Artifact | null>
@@ -305,9 +358,62 @@ export interface BuildStore {
     sinceSeq?: number,
     opts?: { waitSeconds?: number; signal?: AbortSignal },
   ): Promise<RepositoryEvent[]>
+  /** Bounded repository-journal read for stateless full-state readers
+   * (AUT-489): every durable fact (REPOSITORY_STATE_EVENT_TYPES) plus — when
+   * the journal has one — the tail from the latest `dispatcher.run-started`.
+   * Reducing this subset with the state readers yields exactly what a full
+   * replay yields (`projectRepositoryStateEvents` is the normative oracle).
+   * Unknown repo rejects like `getRepoEvents`. */
+  getRepoStateEvents(repo: string): Promise<RepositoryEvent[]>
   putRepoArtifact(repo: string, artifact: ArtifactInput): Promise<RepositoryArtifactMeta>
   getRepoArtifact(repo: string, kind: string, rev?: number): Promise<RepositoryArtifact | null>
   listRepoArtifacts(repo: string, kind?: string): Promise<RepositoryArtifactMeta[]>
+  // ── Ticket assets (SPEC §7.1 — files attached to a ticket) ─────────────
+  // Keyed by (repo, ticketId, kind, name); revisions are 0-based. The store
+  // owns the bytes, the ticket source only ever gets a note (SPEC §13).
+  /** The effective ceilings this store accepts for `repo` (a remote
+   * deployment may advertise lower ones than the defaults). */
+  ticketAssetLimits(repo: string): Promise<TicketAssetLimits>
+  /** Validate, then store a new revision. Over-limit or invalid input rejects
+   * with `TicketAssetValidationError` and stores nothing. */
+  putTicketAsset(repo: string, ticketId: string, asset: TicketAssetInput): Promise<TicketAssetMeta>
+  /** Latest live revision when `rev` is omitted; null when the asset is
+   * absent, removed (latest row is a tombstone), or `rev` is not a real
+   * revision. An explicit `rev` of an earlier revision keeps working after a
+   * removal, so a build that pinned it still retrieves it. */
+  getTicketAsset(
+    repo: string,
+    ticketId: string,
+    kind: string,
+    name: string,
+    rev?: number,
+  ): Promise<TicketAsset | null>
+  /** The ticket asset `kind/name` exactly as build `slug` froze it (SPEC
+   * §6.3): the latest pinned revision, or with `rev` any revision the build
+   * ever pinned. Reads the build's own events, never the ticket's current
+   * state, so it is stable after a replace or removal and works for finished
+   * builds. Null when the build never pinned it. Rejects an unknown build. */
+  getPinnedTicketAsset(
+    slug: string,
+    kind: string,
+    name: string,
+    rev?: number,
+  ): Promise<TicketAsset | null>
+  /** Default: the latest live revision per (kind, name). `revisions: true`:
+   * every real revision (no tombstones). Summaries carry no manifest. */
+  listTicketAssets(
+    repo: string,
+    ticketId: string,
+    opts?: { revisions?: boolean },
+  ): Promise<TicketAssetSummary[]>
+  /** Tombstone the asset (the next revision number, empty manifest). Returns
+   * the removed revision's meta, or null when no live asset exists. */
+  removeTicketAsset(
+    repo: string,
+    ticketId: string,
+    kind: string,
+    name: string,
+  ): Promise<TicketAssetMeta | null>
   claimRepoLease(repo: string, holder: string, ttlMs: number): Promise<boolean>
   heartbeatRepo(repo: string, holder: string): Promise<boolean>
   releaseRepoLease(repo: string, holder: string): Promise<void>
@@ -339,6 +445,21 @@ export interface BuildStore {
     id: string,
     event: SessionEventWrite<T>,
   ): Promise<SessionEventEnvelope<T>>
+  /** Atomically append one validated session event only when the session's
+   * current sequence equals `expectedSeq` (0 would only match a session with
+   * no facts — impossible, since `session.created` is always seq 1). Returns
+   * null when the session has advanced; a comparison miss must not mutate the
+   * log or the record's `updatedAt`. The three turn-start sites (message
+   * route, answer route, dispatcher tick) race on the same idle session, and
+   * two concurrent `turn.started` facts would break the single-open-turn
+   * invariant — this is the sessions mirror of the build log's
+   * `appendIfCurrent`. Invalid events and unknown sessions reject just as
+   * they do for `appendSessionEvent`. */
+  appendSessionEventIfCurrent<T extends SessionEventType>(
+    id: string,
+    expectedSeq: number,
+    event: SessionEventWrite<T>,
+  ): Promise<SessionEventEnvelope<T> | null>
   /** Events with seq strictly greater than `sinceSeq` (default 0), in order.
    * When nothing newer exists, an adapter honors `waitSeconds` with the
    * same clamp/early-return rules as stream reads (§7.6): whole seconds,

package/packages/core/src/testing/index.ts

@@ -0,0 +1,59 @@
+/**
+ * Public testing entry point: the deterministic doubles, CLI entry points,
+ * and the end-to-end harness that out-of-tree packages' tests build against
+ * (the hosted store-service suite is the in-repo consumer). Production code
+ * never imports from here — it is test-facing surface, like plugin-sdk's
+ * fakes, just CLI-shaped.
+ */
+// The plugin-sdk's contract suites, fakes, and memory stores are the shared
+// testing vocabulary; re-export so `@defrex/autobuild/testing` is one import.
+export * from '../plugin-sdk'
+export { manualClock, steppingClock } from './fixed'
+export { agentActor, DISPATCHER, KERNEL, humanActor, type Via } from '../events/envelope'
+export { EventValidationError } from '../events/catalog'
+export type { EscalationSource } from '../ontology'
+export { abDispatch, type DispatchOpts } from '../cli/dispatch'
+// CLI entry points for the hosted-dispatcher integration test: programmatic
+// `ab` invocation and its environment resolution.
+export { resolveCliEnv } from '../cli/env'
+export { runCli } from '../cli/main'
+// Deterministic id doubles for the hosted-dispatcher integration test.
+export { randomUuids, sequentialIds, type IdSource } from '../ids'
+export { abWatch } from '../cli/watch'
+export { abTicket, type TicketSourceFactory } from '../cli/ticket'
+export { createTerminalModeController } from '../cli/terminal-restore'
+export { abBuildControl, type BuildControlAction } from '../cli/build-control'
+export { abBulkControl } from '../cli/bulk-control'
+export { createTicketSource } from '../ports/tickets/create'
+export { createOperatorSandboxService } from '../operator/sandbox'
+export { parseConfig } from '../config/load'
+export { spawnExec, type Exec } from '../ports/workspace/git-worktree'
+// Durable guest-launch state readers + the in-process guest runner for the
+// hosted-dispatcher integration test's GuestExecution double, which supervises
+// a real BuildRunner exactly as a real sandbox execution would.
+export {
+  BUILD_EFFECTIVE_CONFIG_ARTIFACT,
+  diagnosticArtifact,
+  parseEffectiveBuildConfig,
+  selectOpenWorkspace,
+} from '../processes/build-execution-state'
+export {
+  BuildRunner,
+  LeaseHeldError,
+  SetupFailureError,
+} from '../processes/build-runner'
+export { readEventsWithWait } from '../store/streams/wait'
+export { textContent } from '../store/types'
+export {
+  CONFIG_TOML,
+  GIT_ID,
+  git,
+  happyHandlers,
+  makeHarness,
+  readyTicket,
+  typesOf,
+  writeFileIn,
+  type Cli,
+  type E2eHarness,
+  type SkillHandlers,
+} from '../integration/harness'

package/skills/code-review/SKILL.md

@@ -27,7 +27,11 @@ goes nowhere.
      fake or mock are not contract evidence because they can repeat the
      author's assumption.
    - **Spec conformance** — every acceptance criterion met; nothing beyond
-     the spec's scope smuggled in.
+     the spec's scope smuggled in. A pinned `design` asset (listed under
+     `assets` in `.ab/context.json`, files under `.ab/assets/<kind>/<name>/`)
+     is a contract on observable visual and reference outcomes, not on implementation: judge the rendered output against it wherever the code lets you
+     check, and treat a divergence as a finding. A gap in the asset is not a
+     reason to invent requirements.
    - **Tests** — do the new tests exercise the seams this change created or
      moved? Would they fail if the change were wrong?
    - **Fit** — matches the codebase's idioms; no needless indirection.