@defrex/autobuild 0.8.0 → 0.9.0

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

@@ -13,6 +13,9 @@
 import { describe, expect, test } from 'bun:test'
 import { EventValidationError, type EventWrite } from '../events/catalog'
 import { agentActor, DISPATCHER, humanActor, KERNEL, type Via } from '../events/envelope'
+import { reduceBuild } from '../kernel/reducer'
+import { reduceDispatchSettings } from '../kernel/dispatch-settings'
+import { projectRepositoryStateEvents } from './repo-state-events'
 import type { RepositoryEventWrite } from '../events/repository'
 import type { SessionEventWrite } from '../events/sessions'
 import { manualClock } from '../testing/fixed'
@@ -320,6 +323,65 @@ export function describeBuildStoreContract(name: string, factory: BuildStoreFact
         })
       })
 
+      test('createBuild appends an initial build.created as seq 1, atomically with the record', async () => {
+        await withStore(factory, undefined, async (store) => {
+          const created = buildCreatedWrite()
+          await store.createBuild({ ...sampleBuildInput('with-created'), created })
+          const events = await store.getEvents('with-created')
+          expect(events.map((event) => [event.seq, event.type])).toEqual([[1, 'build.created']])
+          expect(events[0]?.payload).toEqual(created.payload)
+          expect(events[0]?.actor).toEqual(created.actor)
+          // The next append continues the stream.
+          const next = await store.append('with-created', {
+            actor: DISPATCHER,
+            type: 'build.created',
+            payload: created.payload,
+          })
+          expect(next.seq).toBe(2)
+        })
+      })
+
+      test('createBuild rejects an invalid or non-build.created initial event and creates nothing', async () => {
+        await withStore(factory, undefined, async (store) => {
+          await expect(
+            store.createBuild({
+              ...sampleBuildInput('bad-created'),
+              created: { actor: DISPATCHER, type: 'build.created', payload: { nope: 1 } } as never,
+            }),
+          ).rejects.toThrow()
+          await expect(
+            store.createBuild({
+              ...sampleBuildInput('wrong-type'),
+              created: { actor: DISPATCHER, type: 'build.completed', payload: {} } as never,
+            }),
+          ).rejects.toThrow()
+          expect(await store.getBuild('bad-created')).toBeNull()
+          expect(await store.getBuild('wrong-type')).toBeNull()
+          // The slug is still free, so a valid create succeeds.
+          await store.createBuild({
+            ...sampleBuildInput('bad-created'),
+            created: buildCreatedWrite(),
+          })
+          expect((await store.getEvents('bad-created')).length).toBe(1)
+        })
+      })
+
+      test('a duplicate slug with an initial event leaves the first build untouched', async () => {
+        await withStore(factory, undefined, async (store) => {
+          await store.createBuild({
+            ...sampleBuildInput('dupe-created'),
+            created: buildCreatedWrite(),
+          })
+          await expect(
+            store.createBuild({
+              ...sampleBuildInput('dupe-created'),
+              created: buildCreatedWrite(),
+            }),
+          ).rejects.toThrow()
+          expect((await store.getEvents('dupe-created')).length).toBe(1)
+        })
+      })
+
       test('getBuild returns null for an unknown slug', async () => {
         await withStore(factory, undefined, async (store) => {
           expect(await store.getBuild('never-created')).toBeNull()
@@ -336,6 +398,229 @@ export function describeBuildStoreContract(name: string, factory: BuildStoreFact
       })
     })
 
+    describe('build digests (repo-scoped batch read, AUT-487)', () => {
+      test('an unknown repo and a journal-less repo answer build-less maps without writes', async () => {
+        await withStore(factory, undefined, async (store) => {
+          expect(await store.getRepoBuildDigests('acme/never-seen')).toEqual(new Map())
+          // The operation is keyed to build records, not the repository
+          // journal record: builds created without `ensureRepo` still digest
+          // (the remote route answers before the repo-existence gate).
+          await store.createBuild(sampleBuildInput('dg-no-journal', { repo: 'acme/no-journal' }))
+          const digests = await store.getRepoBuildDigests('acme/no-journal')
+          expect([...digests.keys()]).toEqual(['dg-no-journal'])
+          expect(digests.get('dg-no-journal')).toEqual({
+            slug: 'dg-no-journal',
+            observations: [],
+          })
+          // Read-only: no journal record was implicitly created.
+          expect(await store.getRepo('acme/no-journal')).toBeNull()
+          expect(await store.getRepo('acme/never-seen')).toBeNull()
+        })
+      })
+      test('one entry per repo build — including a build with no digest-relevant events — and only that repo', async () => {
+        await withStore(factory, undefined, async (store) => {
+          await store.createBuild(sampleBuildInput('dg-a', { repo: 'acme/dga' }))
+          await store.createBuild(sampleBuildInput('dg-other', { repo: 'acme/dgb' }))
+          // A freshly created queued build whose log holds none of the
+          // digest-relevant event types keeps its contractual entry — a join
+          // that started from the events side would silently drop it.
+          const digests = await store.getRepoBuildDigests('acme/dga')
+          expect([...digests.keys()]).toEqual(['dg-a'])
+          expect(digests.get('dg-a')).toEqual({ slug: 'dg-a', observations: [] })
+          const other = await store.getRepoBuildDigests('acme/dgb')
+          expect([...other.keys()]).toEqual(['dg-other'])
+        })
+      })
+
+      test('the digest equals the full-log ground truth over every lifecycle shape', async () => {
+        await withStore(factory, undefined, async (store) => {
+          const repo = 'acme/dg-life'
+          // Open build: an observation, no terminal fact.
+          await store.createBuild(sampleBuildInput('dg-open', { repo }))
+          await store.append('dg-open', buildCreatedWrite())
+          await store.append('dg-open', sampleEventWrite('open observation'))
+
+          // Done build: observation after completion stays an occurrence.
+          await store.createBuild(sampleBuildInput('dg-done', { repo }))
+          await store.append('dg-done', buildCreatedWrite())
+          await store.append('dg-done', {
+            actor: DISPATCHER,
+            type: 'build.completed',
+            payload: { outcome: 'merged' },
+          })
+          await store.append('dg-done', sampleEventWrite('after completion'))
+
+          // Cleaning build (mid-abort): renders a row, no terminal completion.
+          await store.createBuild(sampleBuildInput('dg-cleaning', { repo }))
+          await store.append('dg-cleaning', buildCreatedWrite())
+          await store.append('dg-cleaning', {
+            actor: KERNEL,
+            type: 'build.aborted',
+            payload: {},
+          })
+          await store.append('dg-cleaning', sampleEventWrite('during cleanup'))
+
+          // Abort saga terminated in completion: latest terminal fact wins.
+          await store.createBuild(sampleBuildInput('dg-abandoned', { repo }))
+          await store.append('dg-abandoned', buildCreatedWrite())
+          await store.append('dg-abandoned', {
+            actor: KERNEL,
+            type: 'build.aborted',
+            payload: {},
+          })
+          await store.append('dg-abandoned', {
+            actor: DISPATCHER,
+            type: 'build.completed',
+            payload: { outcome: 'abandoned' },
+          })
+
+          // The reducer's exact terminal rule, pinned: done → aborted → done.
+          await store.createBuild(sampleBuildInput('dg-overwrite', { repo }))
+          await store.append('dg-overwrite', buildCreatedWrite())
+          await store.append('dg-overwrite', {
+            actor: DISPATCHER,
+            type: 'build.completed',
+            payload: { outcome: 'merged' },
+          })
+          await store.append('dg-overwrite', {
+            actor: KERNEL,
+            type: 'build.aborted',
+            payload: {},
+          })
+          await store.append('dg-overwrite', {
+            actor: DISPATCHER,
+            type: 'build.completed',
+            payload: { outcome: 'merged' },
+          })
+
+          const digests = await store.getRepoBuildDigests(repo)
+          const expectedStatuses: Record<string, string> = {}
+          const expectedObservations: Record<string, { seq: number; ts: string }[]> = {}
+          const expectedMerged: Record<string, string | undefined> = {}
+          for (const record of await store.listBuilds()) {
+            if (record.repo !== repo) continue
+            const events = await store.getEvents(record.slug)
+            expectedStatuses[record.slug] = reduceBuild(events).status
+            expectedObservations[record.slug] = events
+              .filter((event) => event.type === 'observation.recorded')
+              .map((event) => ({ seq: event.seq, ts: event.ts }))
+            const merges = events
+              .filter((event) => event.type === 'pr.merged')
+              .map((event) => event.ts)
+            expectedMerged[record.slug] = merges[merges.length - 1]
+          }
+          expect([...digests.keys()].sort()).toEqual(Object.keys(expectedStatuses).sort())
+          for (const [slug, digest] of digests) {
+            // Terminal presence and kind follow the reducer's status exactly.
+            const status = expectedStatuses[slug]!
+            expect(digest.terminal).toBe(
+              status === 'done' ? 'done' : status === 'aborted' ? 'aborted' : undefined,
+            )
+            expect(digest.observations).toEqual(expectedObservations[slug] ?? [])
+            // The merge fact is the log's latest `pr.merged` ts, absent when
+            // the log has none.
+            if (expectedMerged[slug] === undefined) expect(digest.merged).toBeUndefined()
+            else expect(digest.merged).toBe(expectedMerged[slug])
+          }
+          // Explicit shape pins (independent of the loop above); the ts
+          // values come from the same ground-truth events.
+          const tsOf = (slug: string, seq: number): string =>
+            expectedObservations[slug]!.find((item) => item.seq === seq)!.ts
+          expect(digests.get('dg-open')).toEqual({
+            slug: 'dg-open',
+            observations: [{ seq: 2, ts: tsOf('dg-open', 2) }],
+          })
+          expect(digests.get('dg-done')).toEqual({
+            slug: 'dg-done',
+            terminal: 'done',
+            observations: [{ seq: 3, ts: tsOf('dg-done', 3) }],
+          })
+          expect(digests.get('dg-cleaning')).toEqual({
+            slug: 'dg-cleaning',
+            terminal: 'aborted',
+            observations: [{ seq: 3, ts: tsOf('dg-cleaning', 3) }],
+          })
+          expect(digests.get('dg-abandoned')).toEqual({
+            slug: 'dg-abandoned',
+            terminal: 'done',
+            observations: [],
+          })
+          expect(digests.get('dg-overwrite')).toEqual({
+            slug: 'dg-overwrite',
+            terminal: 'done',
+            observations: [],
+          })
+        })
+      })
+
+      test('digests reflect appends through every write path without a refresh step', async () => {
+        await withStore(factory, undefined, async (store) => {
+          const repo = 'acme/dg-paths'
+          await store.createBuild(sampleBuildInput('dg-paths', { repo }))
+          expect((await store.getRepoBuildDigests(repo)).get('dg-paths')?.observations).toEqual([])
+
+          await store.append('dg-paths', sampleEventWrite('first'))
+          let digest = (await store.getRepoBuildDigests(repo)).get('dg-paths')
+          expect(digest?.observations).toEqual([
+            { seq: 1, ts: (await store.getEvents('dg-paths'))[0]!.ts },
+          ])
+          expect(digest?.terminal).toBeUndefined()
+
+          const conditional = await store.appendIfCurrent('dg-paths', 1, sampleEventWrite('second'))
+          expect(conditional).not.toBeNull()
+          digest = (await store.getRepoBuildDigests(repo)).get('dg-paths')
+          expect(digest?.observations.map((item) => item.seq)).toEqual([1, 2])
+
+          await store.appendWithArtifacts('dg-paths', [{ kind: 'dg-notes', content: 'note' }], () =>
+            sampleEventWrite('third'),
+          )
+          digest = (await store.getRepoBuildDigests(repo)).get('dg-paths')
+          expect(digest?.observations).toEqual([
+            { seq: 1, ts: (await store.getEvents('dg-paths'))[0]!.ts },
+            { seq: 2, ts: (await store.getEvents('dg-paths'))[1]!.ts },
+            { seq: 3, ts: (await store.getEvents('dg-paths'))[2]!.ts },
+          ])
+          expect(digest?.merged).toBeUndefined()
+
+          // The merge fact reflects appends through every write path too,
+          // keeping the latest `pr.merged` ts.
+          const merge = async (sha: string) =>
+            (
+              await store.append('dg-paths', {
+                actor: DISPATCHER,
+                type: 'pr.merged',
+                payload: { sha },
+              })
+            ).ts
+          const firstMergeTs = await merge('abc111')
+          digest = (await store.getRepoBuildDigests(repo)).get('dg-paths')
+          expect(digest?.merged).toBe(firstMergeTs)
+
+          const secondMergeTs = await merge('abc222')
+          digest = (await store.getRepoBuildDigests(repo)).get('dg-paths')
+          expect(digest?.merged).toBe(secondMergeTs)
+          expect(secondMergeTs >= firstMergeTs).toBe(true)
+
+          await store.append('dg-paths', {
+            actor: DISPATCHER,
+            type: 'build.completed',
+            payload: { outcome: 'merged' },
+          })
+          digest = (await store.getRepoBuildDigests(repo)).get('dg-paths')
+          expect(digest).toEqual({
+            slug: 'dg-paths',
+            terminal: 'done',
+            merged: secondMergeTs,
+            observations: [
+              { seq: 1, ts: (await store.getEvents('dg-paths'))[0]!.ts },
+              { seq: 2, ts: (await store.getEvents('dg-paths'))[1]!.ts },
+              { seq: 3, ts: (await store.getEvents('dg-paths'))[2]!.ts },
+            ],
+          })
+        })
+      })
+    })
+
     describe('repository journal (workflow and control paper trail)', () => {
       test('ensureRepo is idempotent and repo event seq is independent', async () => {
         const clock = manualClock(CONTRACT_T0)
@@ -518,6 +803,168 @@ export function describeBuildStoreContract(name: string, factory: BuildStoreFact
       })
     })
 
+    describe('getRepoStateEvents (bounded journal read, AUT-489)', () => {
+      /** One no-op hosted dispatcher invocation: the ~4 facts an invocation
+       * appends whether or not it did anything. */
+      function noopInvocation(run: string): RepositoryEventWrite[] {
+        return [
+          {
+            actor: DISPATCHER,
+            type: 'dispatcher.run-started',
+            payload: {
+              run,
+              pid: 1,
+              effectiveConfig: { kind: 'effective-config', rev: 0 },
+              roleWarnings: [],
+            },
+          },
+          { actor: DISPATCHER, type: 'dispatcher.tick-started', payload: { run } },
+          {
+            actor: DISPATCHER,
+            type: 'dispatcher.tick-completed',
+            payload: {
+              run,
+              queued: 0,
+              counters: noopTickCounters(),
+              janitorDiagnostics: [],
+              ticketDiagnostics: [],
+              dependencyDiagnostics: [],
+            },
+          },
+          {
+            actor: DISPATCHER,
+            type: 'dispatcher.run-stopped',
+            payload: { run, outcome: 'normal' },
+          },
+        ]
+      }
+
+      function noopTickCounters() {
+        return {
+          merged: 0,
+          closed: 0,
+          conflicted: 0,
+          abandoned: 0,
+          discarded: 0,
+          janitorFailed: 0,
+          recovered: 0,
+          dispatchFailed: 0,
+          resumed: 0,
+          swept: 0,
+          dispatched: 0,
+          authored: 0,
+          bounced: 0,
+          claimRaces: 0,
+          invalidTickets: 0,
+          dependencyBlocked: 0,
+          harvestStarted: 0,
+          harvestResumed: 0,
+          harvestCompleted: 0,
+          harvestEscalated: 0,
+          harvestFailed: 0,
+        }
+      }
+
+      test('unknown repo rejects like getRepoEvents', async () => {
+        await withStore(factory, undefined, async (store) => {
+          await expect(store.getRepoStateEvents('acme/never-seen')).rejects.toThrow(/unknown repo/)
+        })
+      })
+
+      test('an empty journal answers []', async () => {
+        await withStore(factory, undefined, async (store) => {
+          await store.ensureRepo('acme/empty')
+          expect(await store.getRepoStateEvents('acme/empty')).toEqual([])
+        })
+      })
+
+      test('a journal with durable events but no run-started anchor answers durable types only', async () => {
+        await withStore(factory, undefined, async (store) => {
+          await store.ensureRepo('acme/no-anchor')
+          for (const write of [
+            { actor: humanActor('op'), type: 'dispatcher.intake-set', payload: { enabled: false } },
+            { actor: KERNEL, type: 'harvest.started', payload: harvestStartedWrite('h1').payload },
+            // Run-scoped fact with no anchor anywhere in the journal: if the
+            // read degenerated into a whole-journal select, this would leak
+            // into the result.
+            { actor: DISPATCHER, type: 'dispatcher.tick-started', payload: { run: 'r1' } },
+          ] as RepositoryEventWrite[]) {
+            await store.appendRepo('acme/no-anchor', write)
+          }
+          const subset = await store.getRepoStateEvents('acme/no-anchor')
+          expect(subset.map((event) => event.type)).toEqual([
+            'dispatcher.intake-set',
+            'harvest.started',
+          ])
+        })
+      })
+
+      test('a seeded journal answers exactly the oracle over the full replay', async () => {
+        await withStore(factory, undefined, async (store) => {
+          await store.ensureRepo('acme/state')
+          for (const write of [
+            ...noopInvocation('r1'),
+            { actor: humanActor('op'), type: 'dispatcher.intake-set', payload: { enabled: false } },
+            { actor: KERNEL, type: 'harvest.started', payload: harvestStartedWrite('h1').payload },
+            {
+              actor: humanActor('op'),
+              type: 'orchestrator.sandbox.provisioned',
+              payload: { operator: 'op', environmentId: 'env', provider: 'p', workspacePath: '/w' },
+            },
+            ...noopInvocation('r2'),
+            {
+              actor: humanActor('op'),
+              type: 'dispatcher.operator-reported',
+              payload: { run: 'r2', level: 'warning', message: 'm' },
+            },
+          ] as RepositoryEventWrite[]) {
+            await store.appendRepo('acme/state', write)
+          }
+          const subset = await store.getRepoStateEvents('acme/state')
+          const full = await store.getRepoEvents('acme/state')
+          expect(subset).toEqual(projectRepositoryStateEvents(full))
+          // The oracle is also the reducer-equivalence guarantee: latest-run
+          // facts survive (criterion 3 — a failed/warning invocation stays
+          // visible), and durable facts from before the anchor survive.
+          expect(subset.map((event) => event.type)).toContain('dispatcher.operator-reported')
+          expect(subset.map((event) => event.type)).toContain('harvest.started')
+          expect(subset.filter((event) => event.type === 'dispatcher.run-started')).toHaveLength(1)
+        })
+      })
+
+      test('the subset is bounded by the invocation count, not by journal length', async () => {
+        await withStore(factory, undefined, async (store) => {
+          await store.ensureRepo('acme/bounded')
+          for (let index = 0; index < 25; index += 1) {
+            for (const write of noopInvocation(`r_${index}`)) {
+              await store.appendRepo('acme/bounded', write)
+            }
+          }
+          const subset = await store.getRepoStateEvents('acme/bounded')
+          // Exactly the latest invocation's four facts: nothing durable was
+          // ever written, so the durable part of the subset is empty.
+          expect(subset).toHaveLength(4)
+        })
+      })
+
+      test('settings written after the latest anchor are present', async () => {
+        await withStore(factory, undefined, async (store) => {
+          await store.ensureRepo('acme/settings-tail')
+          for (const write of noopInvocation('r1')) {
+            await store.appendRepo('acme/settings-tail', write)
+          }
+          await store.appendRepo('acme/settings-tail', {
+            actor: humanActor('op'),
+            type: 'dispatcher.pause-set',
+            payload: { enabled: true },
+          })
+          const subset = await store.getRepoStateEvents('acme/settings-tail')
+          expect(subset.map((event) => event.type)).toContain('dispatcher.pause-set')
+          expect(reduceDispatchSettings(subset).paused).toBe(true)
+        })
+      })
+    })
+
     describe('append', () => {
       test('assigns seq 1..n per build, independently across builds (§15.1)', async () => {
         await withStore(factory, undefined, async (store) => {
@@ -1361,6 +1808,352 @@ export function describeBuildStoreContract(name: string, factory: BuildStoreFact
       })
     })
 
+    describe('ticket assets (SPEC §7.1)', () => {
+      const REPO = 'https://github.com/acme/rate-limiter'
+      const enc = (text: string) => new TextEncoder().encode(text)
+      const fileAsset = (name: string, content: Uint8Array, kind = 'design') => ({
+        kind,
+        name,
+        layout: 'file' as const,
+        entries: [{ type: 'file' as const, path: name, content }],
+      })
+      const treeAsset = (
+        name: string,
+        entries: { type: 'file'; path: string; content: Uint8Array }[] | never[] = [],
+        extra: { type: 'dir'; path: string }[] = [],
+        kind = 'design',
+      ) => ({
+        kind,
+        name,
+        layout: 'tree' as const,
+        entries: [...entries, ...extra],
+      })
+
+      test('stores a single file and returns its exact bytes, binary and zero-byte included', async () => {
+        await withStore(factory, undefined, async (store) => {
+          const binary = Uint8Array.from([0, 255, 1, 254, 128, 0])
+          const meta = await store.putTicketAsset(REPO, 'T-1', fileAsset('shot.png', binary))
+          expect(meta).toMatchObject({
+            repo: REPO,
+            ticketId: 'T-1',
+            kind: 'design',
+            name: 'shot.png',
+            revision: 0,
+            layout: 'file',
+            size: 6,
+          })
+          expect(meta.entries).toEqual([
+            { type: 'file', path: 'shot.png', size: 6, blobRef: contentHash(binary) },
+          ])
+          const got = await store.getTicketAsset(REPO, 'T-1', 'design', 'shot.png')
+          expect(got?.meta).toEqual(meta)
+          expect(got?.entries).toEqual([{ type: 'file', path: 'shot.png', content: binary }])
+
+          await store.putTicketAsset(REPO, 'T-1', fileAsset('empty.bin', new Uint8Array(0)))
+          const empty = await store.getTicketAsset(REPO, 'T-1', 'design', 'empty.bin')
+          expect(empty?.entries).toEqual([
+            { type: 'file', path: 'empty.bin', content: new Uint8Array(0) },
+          ])
+          expect(empty?.meta.size).toBe(0)
+        })
+      })
+
+      test('stores trees: nested files, an empty tree, and nested empty directories', async () => {
+        await withStore(factory, undefined, async (store) => {
+          await store.putTicketAsset(
+            REPO,
+            'T-1',
+            treeAsset(
+              'site',
+              [
+                { type: 'file', path: 'index.html', content: enc('<h1>hi</h1>') },
+                { type: 'file', path: 'img/a.png', content: Uint8Array.from([1, 2, 3]) },
+              ],
+              [{ type: 'dir', path: 'img/empty' }],
+            ),
+          )
+          await store.putTicketAsset(REPO, 'T-1', treeAsset('hollow'))
+          const site = await store.getTicketAsset(REPO, 'T-1', 'design', 'site')
+          expect(site?.meta.layout).toBe('tree')
+          expect(site?.meta.size).toBe(14)
+          expect(site?.meta.entries.map((e) => `${e.type}:${e.path}`)).toEqual([
+            'file:index.html',
+            'file:img/a.png',
+            'dir:img/empty',
+          ])
+          expect(site?.entries).toEqual([
+            { type: 'file', path: 'index.html', content: enc('<h1>hi</h1>') },
+            { type: 'file', path: 'img/a.png', content: Uint8Array.from([1, 2, 3]) },
+            { type: 'dir', path: 'img/empty' },
+          ])
+          const hollow = await store.getTicketAsset(REPO, 'T-1', 'design', 'hollow')
+          expect(hollow?.meta).toMatchObject({ layout: 'tree', size: 0, entries: [] })
+          expect(hollow?.entries).toEqual([])
+
+          const list = await store.listTicketAssets(REPO, 'T-1')
+          expect(list.map((a) => [a.name, a.fileCount, a.dirCount, a.size])).toEqual([
+            ['hollow', 0, 0, 0],
+            ['site', 2, 1, 14],
+          ])
+          expect(list.every((a) => !('entries' in a))).toBe(true)
+        })
+      })
+
+      test('re-attaching the same kind and name creates a new revision; old ones stay', async () => {
+        await withStore(factory, undefined, async (store) => {
+          expect(
+            (await store.putTicketAsset(REPO, 'T-1', fileAsset('a', enc('one')))).revision,
+          ).toBe(0)
+          expect(
+            (await store.putTicketAsset(REPO, 'T-1', fileAsset('a', enc('two!')))).revision,
+          ).toBe(1)
+          const latest = await store.getTicketAsset(REPO, 'T-1', 'design', 'a')
+          expect(latest?.meta.revision).toBe(1)
+          expect(latest?.entries[0]).toMatchObject({ content: enc('two!') })
+          const first = await store.getTicketAsset(REPO, 'T-1', 'design', 'a', 0)
+          expect(first?.entries[0]).toMatchObject({ content: enc('one') })
+          expect(await store.getTicketAsset(REPO, 'T-1', 'design', 'a', 2)).toBeNull()
+
+          const current = await store.listTicketAssets(REPO, 'T-1')
+          expect(current.map((a) => [a.name, a.revision, a.size])).toEqual([['a', 1, 4]])
+          const all = await store.listTicketAssets(REPO, 'T-1', { revisions: true })
+          expect(all.map((a) => a.revision)).toEqual([0, 1])
+        })
+      })
+
+      test('lists are isolated by repo, ticket id, kind and name', async () => {
+        await withStore(factory, undefined, async (store) => {
+          await store.putTicketAsset(REPO, 'T-1', fileAsset('a', enc('x')))
+          await store.putTicketAsset(REPO, 'T-1', fileAsset('a', enc('y'), 'ref'))
+          await store.putTicketAsset(REPO, 'T-1', fileAsset('b', enc('z')))
+          await store.putTicketAsset(REPO, 'T-2', fileAsset('a', enc('other')))
+          await store.putTicketAsset('/other/repo', 'T-1', fileAsset('a', enc('other')))
+          expect(
+            (await store.listTicketAssets(REPO, 'T-1')).map((a) => `${a.kind}/${a.name}`),
+          ).toEqual(['design/a', 'design/b', 'ref/a'])
+          expect((await store.listTicketAssets(REPO, 'T-2')).map((a) => a.name)).toEqual(['a'])
+          expect(await store.listTicketAssets(REPO, 'T-3')).toEqual([])
+          expect(await store.getTicketAsset(REPO, 'T-1', 'ref', 'b')).toBeNull()
+          expect(await store.getTicketAsset('/other/repo', 'T-2', 'design', 'a')).toBeNull()
+          // Revision counters are per (repo, ticket, kind, name).
+          expect((await store.putTicketAsset(REPO, 'T-2', fileAsset('b', enc('1')))).revision).toBe(
+            0,
+          )
+        })
+      })
+
+      test('removal hides the asset but earlier revisions stay readable by explicit rev', async () => {
+        await withStore(factory, undefined, async (store) => {
+          await store.putTicketAsset(REPO, 'T-1', fileAsset('a', enc('one')))
+          await store.putTicketAsset(REPO, 'T-1', fileAsset('a', enc('two')))
+          const removed = await store.removeTicketAsset(REPO, 'T-1', 'design', 'a')
+          expect(removed).toMatchObject({ kind: 'design', name: 'a', revision: 1 })
+          expect(await store.getTicketAsset(REPO, 'T-1', 'design', 'a')).toBeNull()
+          expect(await store.listTicketAssets(REPO, 'T-1')).toEqual([])
+          const pinned = await store.getTicketAsset(REPO, 'T-1', 'design', 'a', 0)
+          expect(pinned?.entries[0]).toMatchObject({ content: enc('one') })
+          const pinnedLatest = await store.getTicketAsset(REPO, 'T-1', 'design', 'a', 1)
+          expect(pinnedLatest?.entries[0]).toMatchObject({ content: enc('two') })
+          // Tombstones are not revisions to list.
+          expect(
+            (await store.listTicketAssets(REPO, 'T-1', { revisions: true })).map((a) => a.revision),
+          ).toEqual([0, 1])
+          // Removing again, or removing an unknown asset, is a null no-op.
+          expect(await store.removeTicketAsset(REPO, 'T-1', 'design', 'a')).toBeNull()
+          expect(await store.removeTicketAsset(REPO, 'T-1', 'design', 'ghost')).toBeNull()
+
+          // Re-attaching takes the next revision; the tombstone consumed 2.
+          const again = await store.putTicketAsset(REPO, 'T-1', fileAsset('a', enc('three')))
+          expect(again.revision).toBe(3)
+          expect((await store.listTicketAssets(REPO, 'T-1')).map((a) => a.revision)).toEqual([3])
+          expect((await store.getTicketAsset(REPO, 'T-1', 'design', 'a'))?.meta.revision).toBe(3)
+          expect(await store.getTicketAsset(REPO, 'T-1', 'design', 'a', 2)).toBeNull()
+        })
+      })
+
+      test('advertises limits and refuses an over-limit put, naming the limit, storing nothing', async () => {
+        await withStore(factory, undefined, async (store) => {
+          const limits = await store.ticketAssetLimits(REPO)
+          expect(limits.maxEntries).toBe(1000)
+          expect(limits.maxBytes).toBeGreaterThan(0)
+          expect(limits.maxBytes).toBeLessThanOrEqual(25 * 1024 * 1024)
+          const tooBig = fileAsset('big.bin', new Uint8Array(limits.maxBytes + 1))
+          await expect(store.putTicketAsset(REPO, 'T-1', tooBig)).rejects.toThrow(
+            /ticket asset exceeds .*\d+-byte.*limit/,
+          )
+          expect(await store.listTicketAssets(REPO, 'T-1', { revisions: true })).toEqual([])
+          expect(await store.getTicketAsset(REPO, 'T-1', 'design', 'big.bin')).toBeNull()
+        })
+      })
+
+      test('rejects invalid names, paths and structures, storing nothing', async () => {
+        await withStore(factory, undefined, async (store) => {
+          const f = (path: string) => ({ type: 'file' as const, path, content: enc('x') })
+          const bad = [
+            { ...fileAsset('a', enc('x')), name: 'has space' },
+            { ...fileAsset('a', enc('x')), kind: '' },
+            treeAsset('t', [f('../escape')]),
+            treeAsset('t', [f('/abs')]),
+            treeAsset('t', [f('a//b')]),
+            treeAsset('t', [f('a'), f('a')]),
+            treeAsset('t', [f('a'), f('a/b')]),
+            treeAsset('t', [f('a')], [{ type: 'dir', path: 'a' }]),
+            { ...fileAsset('a', enc('x')), entries: [] },
+            {
+              kind: 'design',
+              name: 'a',
+              layout: 'file' as const,
+              entries: [f('a'), { type: 'dir' as const, path: 'd' }],
+            },
+          ]
+          for (const asset of bad) {
+            await expect(store.putTicketAsset(REPO, 'T-1', asset)).rejects.toThrow()
+          }
+          expect(await store.listTicketAssets(REPO, 'T-1', { revisions: true })).toEqual([])
+        })
+      })
+
+      test('a failed put does not consume a revision', async () => {
+        await withStore(factory, undefined, async (store) => {
+          await store.putTicketAsset(REPO, 'T-1', fileAsset('a', enc('ok')))
+          await expect(
+            store.putTicketAsset(REPO, 'T-1', { ...fileAsset('a', enc('x')), name: 'a b' }),
+          ).rejects.toThrow()
+          expect(
+            (await store.putTicketAsset(REPO, 'T-1', fileAsset('a', enc('ok2')))).revision,
+          ).toBe(1)
+        })
+      })
+
+      test('scoped handles reject ticket-asset operations', async () => {
+        await withStore(factory, undefined, async (store) => {
+          await store.createBuild(sampleBuildInput('ta-scope'))
+          const scoped = store.scopeBuild('ta-scope')
+          await expect(
+            scoped.putTicketAsset(REPO, 'T-1', fileAsset('a', enc('x'))),
+          ).rejects.toThrow(/build-scoped store/)
+          await expect(scoped.getTicketAsset(REPO, 'T-1', 'design', 'a')).rejects.toThrow(
+            /build-scoped store/,
+          )
+          await expect(scoped.listTicketAssets(REPO, 'T-1')).rejects.toThrow(/build-scoped store/)
+          await expect(scoped.removeTicketAsset(REPO, 'T-1', 'design', 'a')).rejects.toThrow(
+            /build-scoped store/,
+          )
+          await expect(scoped.ticketAssetLimits(REPO)).rejects.toThrow(/build-scoped store/)
+        })
+      })
+    })
+
+    describe('pinned ticket assets (SPEC §6.3)', () => {
+      const REPO = 'https://github.com/acme/rate-limiter'
+      const enc = (text: string) => new TextEncoder().encode(text)
+      const file = (name: string, text: string, kind = 'design') => ({
+        kind,
+        name,
+        layout: 'file' as const,
+        entries: [{ type: 'file' as const, path: name, content: enc(text) }],
+      })
+      const pinOf = (meta: { kind: string; name: string; revision: number; size: number }) => ({
+        kind: meta.kind,
+        name: meta.name,
+        revision: meta.revision,
+        layout: 'file' as const,
+        size: meta.size,
+        fileCount: 1,
+        dirCount: 0,
+      })
+      const text = (asset: { entries: { type: string; content?: Uint8Array }[] } | null) =>
+        asset === null ? null : new TextDecoder().decode(asset.entries[0]?.content)
+
+      async function pinnedBuild(
+        store: BuildStore,
+        slug: string,
+        assets: ReturnType<typeof pinOf>[],
+      ): Promise<void> {
+        const created = buildCreatedWrite()
+        await store.createBuild({
+          ...sampleBuildInput(slug),
+          created: { ...created, payload: { ...created.payload, repo: REPO, assets } },
+        })
+      }
+
+      test('reads the pinned revision after the ticket replaces and then removes the asset', async () => {
+        await withStore(factory, undefined, async (store) => {
+          const v0 = await store.putTicketAsset(REPO, 'TICK-1', file('a.txt', 'one'))
+          await pinnedBuild(store, 'pin-a', [pinOf(v0)])
+          await store.putTicketAsset(REPO, 'TICK-1', file('a.txt', 'two'))
+          expect(text(await store.getPinnedTicketAsset('pin-a', 'design', 'a.txt'))).toBe('one')
+          await store.removeTicketAsset(REPO, 'TICK-1', 'design', 'a.txt')
+          expect(await store.getTicketAsset(REPO, 'TICK-1', 'design', 'a.txt')).toBeNull()
+          const pinned = await store.getPinnedTicketAsset('pin-a', 'design', 'a.txt')
+          expect(text(pinned)).toBe('one')
+          expect(pinned?.meta.revision).toBe(0)
+        })
+      })
+
+      test('answers null for what the build never pinned, and for an unpinned revision', async () => {
+        await withStore(factory, undefined, async (store) => {
+          const v0 = await store.putTicketAsset(REPO, 'TICK-1', file('a.txt', 'one'))
+          await store.putTicketAsset(REPO, 'TICK-1', file('a.txt', 'two'))
+          await store.putTicketAsset(REPO, 'TICK-1', file('late.txt', 'late'))
+          await pinnedBuild(store, 'pin-b', [pinOf(v0)])
+          expect(await store.getPinnedTicketAsset('pin-b', 'design', 'late.txt')).toBeNull()
+          expect(await store.getPinnedTicketAsset('pin-b', 'other-kind', 'a.txt')).toBeNull()
+          expect(await store.getPinnedTicketAsset('pin-b', 'design', 'a.txt', 1)).toBeNull()
+          expect(text(await store.getPinnedTicketAsset('pin-b', 'design', 'a.txt', 0))).toBe('one')
+        })
+      })
+
+      test('a build with no pin and an unknown build', async () => {
+        await withStore(factory, undefined, async (store) => {
+          await store.putTicketAsset(REPO, 'TICK-1', file('a.txt', 'one'))
+          await store.createBuild({ ...sampleBuildInput('pin-none'), created: buildCreatedWrite() })
+          expect(await store.getPinnedTicketAsset('pin-none', 'design', 'a.txt')).toBeNull()
+          await expect(store.getPinnedTicketAsset('never', 'design', 'a.txt')).rejects.toThrow()
+        })
+      })
+
+      test('a spec.revised re-pin moves the latest pinned revision; earlier pins stay readable by rev', async () => {
+        await withStore(factory, undefined, async (store) => {
+          const v0 = await store.putTicketAsset(REPO, 'TICK-1', file('a.txt', 'one'))
+          await pinnedBuild(store, 'pin-c', [pinOf(v0)])
+          const v1 = await store.putTicketAsset(REPO, 'TICK-1', file('a.txt', 'two'))
+          await store.append('pin-c', {
+            actor: KERNEL,
+            type: 'spec.revised',
+            payload: { artifact: { kind: 'spec', rev: 1 }, escalation: 1, assets: [pinOf(v1)] },
+          })
+          expect(text(await store.getPinnedTicketAsset('pin-c', 'design', 'a.txt'))).toBe('two')
+          expect(text(await store.getPinnedTicketAsset('pin-c', 'design', 'a.txt', 0))).toBe('one')
+          // Re-pinning to nothing leaves no latest pin; revisions pinned earlier stay readable.
+          await store.append('pin-c', {
+            actor: KERNEL,
+            type: 'spec.revised',
+            payload: { artifact: { kind: 'spec', rev: 2 }, escalation: 1, assets: [] },
+          })
+          expect(await store.getPinnedTicketAsset('pin-c', 'design', 'a.txt')).toBeNull()
+          expect(text(await store.getPinnedTicketAsset('pin-c', 'design', 'a.txt', 1))).toBe('two')
+        })
+      })
+
+      test('a build-scoped handle reads only its own pins', async () => {
+        await withStore(factory, undefined, async (store) => {
+          const v0 = await store.putTicketAsset(REPO, 'TICK-1', file('a.txt', 'one'))
+          await pinnedBuild(store, 'pin-own', [pinOf(v0)])
+          await pinnedBuild(store, 'pin-other', [pinOf(v0)])
+          const scoped = store.scopeBuild('pin-own')
+          expect(text(await scoped.getPinnedTicketAsset('pin-own', 'design', 'a.txt'))).toBe('one')
+          await expect(scoped.getPinnedTicketAsset('pin-other', 'design', 'a.txt')).rejects.toThrow(
+            /build-scoped store/,
+          )
+          // The other ticket-asset reads stay rejected.
+          await expect(scoped.getTicketAsset(REPO, 'TICK-1', 'design', 'a.txt')).rejects.toThrow(
+            /build-scoped store/,
+          )
+        })
+      })
+    })
+
     describe('build-scoped handles', () => {
       test('permit own-build stream, artifact, lease, and subscription operations', async () => {
         await withStore(factory, undefined, async (store) => {
@@ -1399,6 +2192,12 @@ export function describeBuildStoreContract(name: string, factory: BuildStoreFact
           await expect(scoped.getRepoEvents('acme/rate-limiter')).rejects.toThrow(
             /build-scoped store/,
           )
+          await expect(scoped.getRepoStateEvents('acme/rate-limiter')).rejects.toThrow(
+            /build-scoped store/,
+          )
+          await expect(scoped.getRepoBuildDigests('acme/rate-limiter')).rejects.toThrow(
+            /build-scoped store/,
+          )
           await expect(scoped.close()).rejects.toThrow(/build-scoped store/)
         })
       })
@@ -2112,6 +2911,73 @@ export function describeBuildStoreContract(name: string, factory: BuildStoreFact
           })
         })
 
+        test('appendSessionEventIfCurrent (atomic session compare-and-append): win, stale miss leaves the log untouched, concurrent race yields exactly one winner', async () => {
+          await withStore(factory, undefined, async (store) => {
+            const session = await store.createSession({ repo: 'acme/a', operator: 'op' })
+            // session.created is seq 1, so the current tail is 1.
+            const won = await store.appendSessionEventIfCurrent(
+              session.id,
+              1,
+              messagePostedWrite('winner'),
+            )
+            expect(won?.seq).toBe(2)
+            expect((await store.getSessionEvents(session.id)).map((e) => e.seq)).toEqual([1, 2])
+
+            // A stale expected sequence appends nothing and leaves the record
+            // untouched.
+            const before = await store.getSession(session.id)
+            expect(
+              await store.appendSessionEventIfCurrent(session.id, 1, messagePostedWrite('stale')),
+            ).toBeNull()
+            expect(await store.getSession(session.id)).toEqual(before)
+            expect((await store.getSessionEvents(session.id)).map((e) => e.seq)).toEqual([1, 2])
+
+            // Two contenders for one sequence produce exactly one winner.
+            const results = await Promise.all([
+              store.appendSessionEventIfCurrent(session.id, 2, messagePostedWrite('a')),
+              store.appendSessionEventIfCurrent(session.id, 2, messagePostedWrite('b')),
+            ])
+            expect(results.filter((result) => result !== null)).toHaveLength(1)
+            expect(results.filter((result) => result === null)).toHaveLength(1)
+            const next = await store.appendSessionEventIfCurrent(
+              session.id,
+              3,
+              messagePostedWrite('next'),
+            )
+            expect(next?.seq).toBe(4)
+
+            // Invalid candidates and unknown sessions reject without writes.
+            const invalid = {
+              actor: humanActor('op'),
+              type: 'no.such-type',
+              payload: {},
+            } as unknown as SessionEventWrite
+            expect(
+              await store.appendSessionEventIfCurrent(session.id, 4, invalid).then(
+                () => 'no-error',
+                (error: unknown) => error,
+              ),
+            ).toBeInstanceOf(EventValidationError)
+            const negativeSeq = await store
+              .appendSessionEventIfCurrent(session.id, -1, messagePostedWrite())
+              .then(
+                () => 'no-error',
+                (error: unknown) => error,
+              )
+            expect(negativeSeq).toBeInstanceOf(Error)
+            const unknownSession = await store
+              .appendSessionEventIfCurrent('os_ghost', 0, messagePostedWrite())
+              .then(
+                () => 'no-error',
+                (error: unknown) => error,
+              )
+            expect(unknownSession).toBeInstanceOf(Error)
+            expect((await store.getSessionEvents(session.id)).map((e) => e.seq)).toEqual([
+              1, 2, 3, 4,
+            ])
+          })
+        })
+
         test('bounded-wait session event read: early return on append, waits out the bound when empty, clamps above 30', async () => {
           await withStore(factory, undefined, async (store) => {
             const session = await store.createSession({ repo: 'acme/a', operator: 'op' })
@@ -2243,6 +3109,8 @@ export function describeBuildStoreContract(name: string, factory: BuildStoreFact
               () => scoped.ensureRepo('acme/a'),
               () => scoped.appendRepo('acme/a', harvestStartedWrite()),
               () => scoped.getRepoEvents('acme/a'),
+              () => scoped.getRepoStateEvents('acme/a'),
+              () => scoped.getRepoBuildDigests('acme/a'),
               () => scoped.createStream({ kind: 'build', build: 'scope-build' }, 'x'),
               () => scoped.createStream({ kind: 'repo', repo: 'acme/a' }, 'x'),
               () => scoped.close(),