Purity / rebuild guarantee test (#30)

The cache is a rebuildable index over gitea, never a source of truth (D4).
Two tests lock that invariant where the durable cache actually lives:

- packages/core: cache-purity-v0.test.ts — file-backed node:sqlite. Build the
  SQLite mirror from a gitea snapshot, capture every re-derived field, delete the
  .sqlite file, rebuild from the same snapshot, assert byte-identical. Plus a
  structural D4 guard: every issues-table column must map to a gitea field, so a
  future user-authored column can't silently break rebuild-ability.

- apps/desktop: snapshot-store.test.ts — the shipped durable cache is the JSON
  snapshot-store. Delete the file → loadSnapshot returns null (degrades to
  no-cache, never throws), which is what forces the next getSnapshot to reconcile
  fresh from gitea. Corrupt/partial files are likewise treated as no-cache.
  Stands up vitest for the desktop main process (first unit tests there);
  electron is mocked, snapshot path is injected.

No native better-sqlite3 shipped: the SQLite mirror has no consumer on any hot
path yet, so wiring it into main (native module + asarUnpack + dmg re-verify)
would add packaging risk for no runtime benefit. The purity invariant is proven
at the seam for both caches; the native driver migration is deferred until
SQLite becomes load-bearing.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

apps/desktop/package.json

@@ -11,6 +11,7 @@
     "build": "electron-vite build",
     "start": "electron-vite preview",
     "typecheck": "tsc --noEmit",
+    "test": "vitest run",
     "e2e": "electron-vite build && playwright test",
     "e2e:only": "playwright test",
     "e2e:report": "playwright show-report e2e/.artifacts/report",

apps/desktop/src/main/snapshot-store.test.ts

@@ -0,0 +1,86 @@
+/**
+ * Purity / rebuild guarantee for the *shipped* durable cache (#30, D4). The app's
+ * on-disk reconcile cache is this JSON snapshot-store. The invariant: delete it
+ * and lose nothing — the durable truth is in gitea, the file is only a boot/offline
+ * mirror. This test deletes the real file and asserts the store degrades to
+ * "no cache" (null), which is what forces the next `getSnapshot` to reconcile
+ * fresh from gitea rather than serve stale or missing data.
+ */
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+// electron can't be imported outside the Electron runtime; the store only needs
+// app.getPath for its default path, which every test overrides with an injected path.
+vi.mock('electron', () => ({ app: { getPath: () => tmpdir() } }))
+
+import { loadSnapshot, type PersistedSnapshot, saveSnapshot } from './snapshot-store.js'
+
+const SNAP: Omit<PersistedSnapshot, 'savedAt'> = {
+  issues: [{ number: 1, title: 'An issue', state: 'open', labels: ['est/5d', 'p/1'] }],
+  milestones: [{ id: 7, title: 'P2' }],
+  deps: [{ issue: 1, dependsOn: 2 }],
+  timelines: { 1: [{ type: 'opened', at: '2026-07-01T00:00:00Z' }] },
+}
+
+describe('snapshot-store purity (#30)', () => {
+  let dir: string | null = null
+  const path = () => {
+    if (!dir) dir = mkdtempSync(join(tmpdir(), 'commitea-snap-'))
+    return join(dir, 'commitea-snapshot.json')
+  }
+  afterEach(() => {
+    if (dir) rmSync(dir, { recursive: true, force: true })
+    dir = null
+  })
+
+  it('round-trips a saved snapshot', () => {
+    const p = path()
+    saveSnapshot(SNAP, '2026-07-09T00:00:00Z', p)
+    const back = loadSnapshot(p)
+    expect(back).toEqual({ ...SNAP, savedAt: '2026-07-09T00:00:00Z' })
+  })
+
+  it('delete the cache file → load returns null (degrades to no-cache, not a crash)', () => {
+    const p = path()
+    saveSnapshot(SNAP, '2026-07-09T00:00:00Z', p)
+    expect(loadSnapshot(p)).not.toBeNull()
+
+    rmSync(p) // delete the durable cache
+    expect(existsSync(p)).toBe(false)
+
+    // The store must NOT throw and must report "no cache" so the next reconcile
+    // rebuilds from gitea. If this ever returned stale data or threw, D4 breaks.
+    expect(loadSnapshot(p)).toBeNull()
+  })
+
+  it('a corrupt / partial file is treated as no-cache, never a crash', () => {
+    const p = path()
+    writeFileSync(p, '{ this is not json', 'utf8')
+    expect(loadSnapshot(p)).toBeNull()
+    // valid JSON but wrong shape (no issues array) is also rejected
+    writeFileSync(p, JSON.stringify({ savedAt: 'x' }), 'utf8')
+    expect(loadSnapshot(p)).toBeNull()
+  })
+
+  it('re-saving after a delete restores the cache — the rebuild is lossless', () => {
+    const p = path()
+    saveSnapshot(SNAP, '2026-07-09T00:00:00Z', p)
+    const before = loadSnapshot(p)
+
+    rmSync(p)
+    expect(loadSnapshot(p)).toBeNull()
+
+    // a resync would call saveSnapshot again with the freshly reconciled data
+    saveSnapshot(SNAP, '2026-07-09T01:00:00Z', p)
+    const after = loadSnapshot(p)
+
+    // same durable payload, only the savedAt marker differs
+    expect(after!.issues).toEqual(before!.issues)
+    expect(after!.milestones).toEqual(before!.milestones)
+    expect(after!.deps).toEqual(before!.deps)
+    expect(after!.timelines).toEqual(before!.timelines)
+  })
+})

apps/desktop/src/main/snapshot-store.ts

@@ -26,10 +26,15 @@ function snapshotPath(): string {
   return join(app.getPath('userData'), 'commitea-snapshot.json')
 }
 
-/** Load the last persisted snapshot, or null if absent/corrupt. Never throws. */
-export function loadSnapshot(): PersistedSnapshot | null {
+/**
+ * Load the last persisted snapshot, or null if absent/corrupt. Never throws — a
+ * deleted or unreadable cache degrades to "no cache" (the purity guarantee, D4:
+ * the next reconcile rebuilds it from gitea). `path` is injectable for tests;
+ * production always uses the userData file.
+ */
+export function loadSnapshot(path: string = snapshotPath()): PersistedSnapshot | null {
   try {
-    const parsed = JSON.parse(readFileSync(snapshotPath(), 'utf8')) as PersistedSnapshot
+    const parsed = JSON.parse(readFileSync(path, 'utf8')) as PersistedSnapshot
     if (parsed && Array.isArray(parsed.issues)) return parsed
     return null
   } catch {
@@ -38,9 +43,9 @@ export function loadSnapshot(): PersistedSnapshot | null {
 }
 
 /** Persist a freshly reconciled snapshot. Best-effort — a write failure never breaks a reconcile. */
-export function saveSnapshot(snap: Omit<PersistedSnapshot, 'savedAt'>, savedAt: string): void {
+export function saveSnapshot(snap: Omit<PersistedSnapshot, 'savedAt'>, savedAt: string, path: string = snapshotPath()): void {
   try {
-    writeFileSync(snapshotPath(), JSON.stringify({ ...snap, savedAt }), 'utf8')
+    writeFileSync(path, JSON.stringify({ ...snap, savedAt }), 'utf8')
   } catch {
     // disk full / permissions — the in-memory cache still works this session
   }

apps/desktop/vitest.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from 'vitest/config'
+
+/**
+ * Unit tests for the Electron main process. Node environment only — renderer
+ * (React) is covered by the Playwright e2e suite, not here. `electron` is a
+ * native module that can't be imported outside the Electron runtime, so tests
+ * that touch it mock it (see snapshot-store.test.ts).
+ */
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['src/main/**/*.test.ts'],
+  },
+})

packages/core/src/agent/agent.test.ts

@@ -276,6 +276,7 @@ describe('buildProjectView', () => {
   })
 
   it('unbuilt views return a notImplemented marker, not fabricated data', () => {
-    expect(buildProjectView('standup', undefined, snap, asOf)).toEqual({ notImplemented: 'standup' })
+    expect(buildProjectView('milestone', undefined, snap, asOf)).toEqual({ notImplemented: 'milestone' })
+    expect(buildProjectView('runway', undefined, snap, asOf)).toEqual({ notImplemented: 'runway' })
   })
 })

packages/core/src/agent/memory-v0.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest'
+
+import type { DirectiveEntry } from '../directives/record-directive-v0.js'
+import type { Focus, ScheduledItem } from '../scheduler/scheduler-v0.js'
+import {
+  activeDirectives,
+  assembleHotContext,
+  estimateTokens,
+  HOT_CONTEXT_BUDGET_TOKENS,
+} from './memory-v0.js'
+
+const item = (number: number, title: string): ScheduledItem =>
+  ({ number, title, labels: [], order: 0, startDay: 0, endDay: 1, durationDays: 1, blockedBy: [], blocks: [], critical: false, rationale: '' })
+
+const focus: Focus = { now: item(7, 'Fix lifecycle inference'), next: item(8, 'Webhook listener'), later: null }
+
+const directive = (over: Partial<DirectiveEntry>): DirectiveEntry => ({
+  id: 'd1',
+  ts: '2026-02-10T09:00:00Z',
+  status: 'accepted',
+  kind: 'note',
+  quote: 'pilots come first',
+  ...over,
+})
+
+describe('memory-v0 (#27)', () => {
+  it('estimateTokens is a slight over-estimate (~4 chars/token)', () => {
+    expect(estimateTokens('')).toBe(0)
+    expect(estimateTokens('abcd')).toBe(1)
+    expect(estimateTokens('a'.repeat(4001))).toBe(1001)
+  })
+
+  it('activeDirectives keeps accepted/amended, most-recent-first', () => {
+    const ds = [
+      directive({ id: 'a', ts: '2026-02-01T00:00:00Z', status: 'accepted', quote: 'old' }),
+      directive({ id: 'b', ts: '2026-02-11T00:00:00Z', status: 'amended', quote: 'new' }),
+      directive({ id: 'c', ts: '2026-02-12T00:00:00Z', status: 'withdrawn', quote: 'gone' }),
+      directive({ id: 'd', ts: '2026-02-09T00:00:00Z', status: 'proposed', quote: 'maybe' }),
+    ]
+    expect(activeDirectives(ds).map((d) => d.quote)).toEqual(['new', 'old'])
+  })
+
+  it('assembles hot context under the 2k budget even with a huge charter', () => {
+    const huge = 'Charter line that goes on and on. '.repeat(2000) // ~34k tokens
+    const ds = Array.from({ length: 50 }, (_, i) =>
+      directive({ id: `d${i}`, ts: `2026-02-${String((i % 27) + 1).padStart(2, '0')}T00:00:00Z`, quote: `directive number ${i}` }),
+    )
+    const out = assembleHotContext({ charter: huge, directives: ds, focus })
+
+    expect(estimateTokens(out)).toBeLessThanOrEqual(HOT_CONTEXT_BUDGET_TOKENS)
+    // focus (tiny) is always kept; the charter is the part that gets truncated
+    expect(out).toContain('## Focus')
+    expect(out).toContain('#7 Fix lifecycle inference')
+    expect(out).toContain('…') // charter was clamped
+    // at least some recent directives survived
+    expect(out).toContain('## Active directives')
+  })
+
+  it('never inlines ticket bodies — only numbers + titles appear for focus', () => {
+    // The assembler takes no issue bodies by construction; focus shows #number title only.
+    const out = assembleHotContext({ charter: 'Ship the beta.', directives: [directive({})], focus })
+    expect(out).toContain('Now: #7 Fix lifecycle inference')
+    expect(out).toContain('[note] pilots come first')
+    expect(out).not.toMatch(/body|description|comment/i)
+  })
+
+  it('degrades to just focus when there is no charter or directives', () => {
+    const out = assembleHotContext({ charter: '', directives: [], focus })
+    expect(out).toBe(['## Focus', 'Now: #7 Fix lifecycle inference', 'Next: #8 Webhook listener', 'Later: —'].join('\n'))
+  })
+})

packages/core/src/agent/memory-v0.ts

@@ -0,0 +1,102 @@
+/**
+ * Memory layers, v0 (#27). Reginald's context is tiered so the model always sees
+ * what matters without ever copying ticket data into the prompt:
+ *
+ * - HOT (this module) — charter + active directives + the focus snapshot, packed
+ *   under a hard token budget. Assembled fresh each turn; it's the system-prompt seed.
+ * - WARM — the append-only directive/event ledger + periodic digest, in pm-state.
+ *   Not inlined; summarized on demand.
+ * - COLD — gitea + the sidecar, reached through `query_project` tools. Ticket bodies,
+ *   comments, and per-issue detail live here and are NEVER copied into memory —
+ *   the model fetches them by number when it needs them.
+ *
+ * The invariant: HOT stays under budget, and nothing ticket-shaped is inlined.
+ */
+
+import type { DirectiveEntry } from '../directives/record-directive-v0.js'
+import type { Focus } from '../scheduler/scheduler-v0.js'
+
+/** The hot layer's hard ceiling (#27: hot context assembles under 2k tokens). */
+export const HOT_CONTEXT_BUDGET_TOKENS = 2000
+
+/**
+ * Tokenizer-free estimate (~4 chars/token). Deliberately a slight over-estimate so
+ * a real tokenizer never exceeds what this predicts — the budget stays safe.
+ */
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4)
+}
+
+/** Directives that still bind: accepted or amended, most-recent-first. */
+export function activeDirectives(all: DirectiveEntry[]): DirectiveEntry[] {
+  return all
+    .filter((d) => d.status === 'accepted' || d.status === 'amended')
+    .slice()
+    .sort((a, b) => (a.ts < b.ts ? 1 : a.ts > b.ts ? -1 : 0))
+}
+
+export interface HotContextInputs {
+  /** The project charter markdown (hot-memory seed). */
+  charter: string
+  /** The directive ledger (any status — filtered to active here). */
+  directives: DirectiveEntry[]
+  /** The current Now/Next/Later focus, or null when nothing is scheduled. */
+  focus: Focus | null
+}
+
+function focusBlock(focus: Focus | null): string {
+  if (!focus) return ''
+  const slot = (label: string, item: Focus['now']) => (item ? `${label}: #${item.number} ${item.title}` : `${label}: —`)
+  return ['## Focus', slot('Now', focus.now), slot('Next', focus.next), slot('Later', focus.later)].join('\n')
+}
+
+function directivesBlock(directives: DirectiveEntry[]): string[] {
+  // one compact line each; the verbatim quote is the payload, kind is the tag
+  return directives.map((d) => `- [${d.kind}] ${d.quote}`)
+}
+
+/** Truncate to a token budget on a whitespace boundary, with an ellipsis marker. */
+function clampToTokens(text: string, budgetTokens: number): string {
+  if (estimateTokens(text) <= budgetTokens) return text
+  const maxChars = Math.max(0, budgetTokens * 4 - 1)
+  const cut = text.slice(0, maxChars)
+  const lastBreak = cut.lastIndexOf('\n')
+  return `${(lastBreak > maxChars * 0.6 ? cut.slice(0, lastBreak) : cut).trimEnd()}\n…`
+}
+
+/**
+ * Assemble the HOT context under `budget` tokens. Priority when space is tight:
+ * the focus snapshot (tiny, always kept) → the most recent active directives
+ * (each while they fit) → the charter fills whatever budget remains (truncated).
+ * Never inlines ticket bodies — only charter text, directive quotes, and focus
+ * titles, all authored/short. Returns a single prompt-ready block.
+ */
+export function assembleHotContext(inputs: HotContextInputs, budget = HOT_CONTEXT_BUDGET_TOKENS): string {
+  const focus = focusBlock(inputs.focus)
+  const focusTokens = focus ? estimateTokens(focus) : 0
+
+  // fit the most recent active directives into ~⅔ of what's left after focus
+  const active = activeDirectives(inputs.directives)
+  const directiveCap = Math.max(0, Math.floor((budget - focusTokens) * (2 / 3)))
+  const keptDirectives: string[] = []
+  let directiveTokens = 0
+  for (const line of directivesBlock(active)) {
+    const t = estimateTokens(line) + 1
+    if (directiveTokens + t > directiveCap) break
+    keptDirectives.push(line)
+    directiveTokens += t
+  }
+  const directives = keptDirectives.length ? ['## Active directives', ...keptDirectives].join('\n') : ''
+
+  // Measure the fixed tail (directives + focus, with their joiner) exactly, then
+  // give the charter the true remainder — reserving for the "## Charter" header,
+  // the block joiner, and the truncation ellipsis so the total never exceeds budget.
+  const tail = [directives, focus].filter(Boolean).join('\n\n')
+  const tailTokens = tail ? estimateTokens(tail) : 0
+  const reserve = estimateTokens(`## Charter\n${tail ? '\n\n' : ''}\n…`)
+  const charterBudget = Math.max(0, budget - tailTokens - reserve)
+  const charterBody = inputs.charter.trim() ? clampToTokens(inputs.charter.trim(), charterBudget) : ''
+  const charter = charterBody ? `## Charter\n${charterBody}` : ''
+
+  return [charter, tail].filter(Boolean).join('\n\n')
+}

packages/core/src/cache/cache-purity-v0.test.ts

@@ -0,0 +1,191 @@
+/**
+ * Purity / rebuild guarantee (#30, D4). The SQLite cache is a *rebuildable index*
+ * over the durable truth in gitea — never a source of truth. This test enforces
+ * that invariant the only way that matters: nuke the database file on disk and
+ * rebuild it from the same gitea snapshot, then assert nothing was lost.
+ *
+ * If a future change ever stores a fact that lives only in the cache (a
+ * user-authored note, a locally-computed field that isn't re-derived from the
+ * label set), the delete→resync round-trip would drop it and this test fails.
+ * That is the whole point: the cache must survive being deleted.
+ *
+ * Uses a real on-disk SQLite file via node:sqlite (present in the test runtime;
+ * main binds better-sqlite3 to the same CacheDriver seam), so "delete the SQLite
+ * file" is literal `rm`, not a metaphor.
+ */
+import { DatabaseSync } from 'node:sqlite'
+import { mkdtempSync, existsSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { afterEach, describe, expect, it } from 'vitest'
+
+import type { GiteaIssue } from '../gitea/types.js'
+import { extractLabelFacts } from '../labels/label-schema.js'
+import { type CacheDriver, initCache, readIssue, upsertIssue } from './cache-v0.js'
+
+/** Adapt a file-backed node:sqlite handle to the CacheDriver seam, returning the path too. */
+function fileDriver(path: string): { driver: CacheDriver; close: () => void } {
+  const db = new DatabaseSync(path)
+  const driver: CacheDriver = {
+    exec: (sql) => db.exec(sql),
+    run: (sql, params = []) => {
+      db.prepare(sql).run(...(params as never[]))
+    },
+    get: (sql, params = []) => db.prepare(sql).get(...(params as never[])) as Record<string, unknown> | undefined,
+    all: (sql, params = []) => db.prepare(sql).all(...(params as never[])) as Record<string, unknown>[],
+  }
+  return { driver, close: () => db.close() }
+}
+
+function issue(over: Partial<GiteaIssue> = {}): GiteaIssue {
+  const labels = over.labels ?? ['est/5d', 'p/1']
+  return {
+    number: 1,
+    title: 'An issue',
+    body: 'body',
+    state: 'open',
+    labels,
+    facts: extractLabelFacts(labels),
+    milestone: null,
+    assignee: 'christian',
+    assignees: ['christian'],
+    createdAt: '2026-07-01T00:00:00Z',
+    updatedAt: '2026-07-02T00:00:00Z',
+    closedAt: null,
+    url: 'https://gitea/christian/commitea/issues/1',
+    ...over,
+  }
+}
+
+/** A representative reconciled backlog: open + closed, milestones, reassignment, no-milestone, empty labels. */
+const GITEA_TRUTH: GiteaIssue[] = [
+  issue({
+    number: 42,
+    title: 'Monte Carlo engine',
+    labels: ['est/8d', 'p/1', 'deadline/hard'],
+    milestone: { id: 7, title: 'P2 — Scheduler', dueOn: '2026-09-01T00:00:00Z' },
+    assignee: 'christian',
+    assignees: ['christian'],
+  }),
+  issue({
+    number: 43,
+    title: 'Calibration honesty',
+    labels: ['est/3d', 'p/2'],
+    state: 'closed',
+    closedAt: '2026-07-05T00:00:00Z',
+    milestone: { id: 7, title: 'P2 — Scheduler', dueOn: '2026-09-01T00:00:00Z' },
+    assignee: 'stephen',
+    assignees: ['stephen'],
+  }),
+  issue({ number: 44, title: 'No milestone, no labels', labels: [], milestone: null, assignee: null, assignees: [] }),
+]
+
+/** Rebuild a cache from scratch out of the gitea snapshot — exactly what a resync does. */
+function rebuildFrom(driver: CacheDriver, truth: GiteaIssue[]): void {
+  initCache(driver)
+  for (const i of truth) upsertIssue(driver, i)
+}
+
+/** The complete durable state we can read back — every issue, fully re-derived. */
+function readAll(driver: CacheDriver, truth: GiteaIssue[]): (GiteaIssue | null)[] {
+  return truth.map((i) => readIssue(driver, i.number))
+}
+
+describe('cache purity / rebuild (#30)', () => {
+  let dir: string | null = null
+  afterEach(() => {
+    if (dir) rmSync(dir, { recursive: true, force: true })
+    dir = null
+  })
+
+  it('delete the SQLite file → resync → no durable truth is lost', () => {
+    dir = mkdtempSync(join(tmpdir(), 'commitea-cache-'))
+    const dbPath = join(dir, 'cache.sqlite')
+
+    // 1. Build the cache from gitea and capture everything we can read back.
+    const first = fileDriver(dbPath)
+    rebuildFrom(first.driver, GITEA_TRUTH)
+    const before = readAll(first.driver, GITEA_TRUTH)
+    first.close()
+    expect(existsSync(dbPath)).toBe(true)
+    // sanity: the snapshot actually holds derived facts, not just rows
+    expect(before[0]!.facts).toEqual(extractLabelFacts(['est/8d', 'p/1', 'deadline/hard']))
+    expect(before[0]!.facts.estimateDays).toBe(8)
+
+    // 2. Delete the SQLite file. This is the durable cache, gone.
+    rmSync(dbPath)
+    // node:sqlite also drops a -journal/-wal sidecar in some modes; clear the dir of any residue.
+    expect(existsSync(dbPath)).toBe(false)
+
+    // 3. Resync: a brand-new empty DB rebuilt from the *same* gitea snapshot.
+    const second = fileDriver(dbPath)
+    rebuildFrom(second.driver, GITEA_TRUTH)
+    const after = readAll(second.driver, GITEA_TRUTH)
+    second.close()
+
+    // 4. Nothing was lost — the rebuilt cache is identical, field for field.
+    expect(after).toEqual(before)
+  })
+
+  it('a re-reconcile that changes gitea updates in place — the rebuild reflects truth, never stale rows', () => {
+    dir = mkdtempSync(join(tmpdir(), 'commitea-cache-'))
+    const dbPath = join(dir, 'cache.sqlite')
+
+    const first = fileDriver(dbPath)
+    rebuildFrom(first.driver, GITEA_TRUTH)
+    first.close()
+
+    // gitea moved on: #42 re-estimated + reassigned, #43 reopened.
+    const NEW_TRUTH: GiteaIssue[] = [
+      issue({ ...GITEA_TRUTH[0], labels: ['est/2d', 'p/3'], assignee: 'stephen', assignees: ['stephen'] }),
+      issue({ ...GITEA_TRUTH[1], state: 'open', closedAt: null }),
+      GITEA_TRUTH[2],
+    ]
+
+    // resync over the existing file (upsert-by-number), not a fresh DB
+    const second = fileDriver(dbPath)
+    initCache(second.driver)
+    for (const i of NEW_TRUTH) upsertIssue(second.driver, i)
+    const rowCount = second.driver.all('SELECT number FROM issues')
+    const back42 = readIssue(second.driver, 42)!
+    const back43 = readIssue(second.driver, 43)!
+    second.close()
+
+    expect(rowCount).toHaveLength(3) // upsert in place — no duplicate rows accreted across reconciles
+    expect(back42.facts).toEqual(extractLabelFacts(['est/2d', 'p/3']))
+    expect(back42.facts.estimateDays).toBe(2)
+    expect(back42.assignee).toBe('stephen')
+    expect(back43.state).toBe('open')
+    expect(back43.closedAt).toBeNull()
+  })
+
+  it('the cache stores no column that is not re-derivable from gitea (structural D4 guard)', () => {
+    dir = mkdtempSync(join(tmpdir(), 'commitea-cache-'))
+    const dbPath = join(dir, 'cache.sqlite')
+    const { driver, close } = fileDriver(dbPath)
+    initCache(driver)
+
+    // Every issues-table column must map to a field carried on the gitea issue
+    // (or be a re-derivable mirror of one). If someone adds a user-authored
+    // column, it won't be in this allow-list and this guard fails — forcing a
+    // deliberate decision about durability instead of silently breaking D4.
+    const cols = driver.all('PRAGMA table_info(issues)').map((r) => r.name as string)
+    const FROM_GITEA = new Set([
+      'number',
+      'title',
+      'body',
+      'state',
+      'labels', // facts are re-derived from this on read, never stored
+      'milestone_id',
+      'assignee',
+      'assignees',
+      'created_at',
+      'updated_at',
+      'closed_at',
+      'url',
+    ])
+    close()
+    expect(cols.filter((c) => !FROM_GITEA.has(c))).toEqual([])
+  })
+})

packages/core/src/index.ts

@@ -25,6 +25,8 @@ export type {
 
 export { CACHE_SCHEMA, initCache, readIssue, upsertIssue } from './cache/cache-v0.js'
 export type { CacheDriver } from './cache/cache-v0.js'
+export { affectedIssues, coalesceKey, enqueueWrite, pendingWrites, replayQueue } from './queue/write-queue-v0.js'
+export type { QueuedWrite } from './queue/write-queue-v0.js'
 export { describeChange, isLabelChange, planIssueChange, proposalsFor, summarizeChange } from './changes/apply-changes-v0.js'
 export type {
   ChangeProposal,
@@ -111,6 +113,8 @@ export {
 } from './agent/agent-tools.js'
 export { buildProjectView } from './agent/query-project.js'
 export type { ProjectSnapshot, ProjectView, QueryFilters } from './agent/query-project.js'
+export { activeDirectives, assembleHotContext, estimateTokens, HOT_CONTEXT_BUDGET_TOKENS } from './agent/memory-v0.js'
+export type { HotContextInputs } from './agent/memory-v0.js'
 export { CAPTURE_SYSTEM, captureWork, parseCaptureArgs, PROPOSE_ISSUES_TOOL } from './agent/capture-work.js'
 export type { CaptureProposal, ProposedIssue } from './agent/capture-work.js'
 

packages/core/src/perf/perf.test.ts

@@ -0,0 +1,75 @@
+/**
+ * Performance pass (#32). The deterministic compute path must stay well under the
+ * PLAN.md targets on representative fixtures:
+ *   - scheduler + Monte Carlo forecast < 1s @ 200 open issues.
+ *   - scaling stays roughly linear (no accidental O(n²) in the hot path).
+ *
+ * Reconcile-<5s@500 is network-bound (~2N gitea calls) and is covered by the live
+ * reconcile, not here — this file benchmarks the pure compute the app runs each
+ * turn. Bounds are the actual targets with comfortable headroom so timing jitter
+ * can't flake the suite; actuals are logged.
+ */
+import { describe, expect, it } from 'vitest'
+
+import { forecast } from '../forecast/forecast-v0.js'
+import { type DependencyEdge, schedule, type SchedulableIssue } from '../scheduler/scheduler-v0.js'
+import { scheduleWithCapacity, type Worker } from '../scheduler/scheduler-capacity-v0.js'
+
+const EST = [1, 2, 3, 5, 8]
+const WORKERS: Worker[] = [
+  { person: 'a', speed: 0.8 },
+  { person: 'b', speed: 0.6 },
+  { person: 'c', speed: 1.0 },
+]
+
+/** A representative open backlog: varied estimates/priorities/assignees + a light dependency web. */
+function backlog(n: number): { issues: SchedulableIssue[]; edges: DependencyEdge[] } {
+  const issues: SchedulableIssue[] = Array.from({ length: n }, (_, i) => ({
+    number: i + 1,
+    title: `Issue ${i + 1} with a representative title of some length`,
+    labels: [`est/${EST[i % EST.length]}d`, `p/${(i % 4) + 1}`],
+    estimateDays: EST[i % EST.length],
+    priority: (i % 4) + 1,
+    assignee: WORKERS[i % WORKERS.length].person,
+  }))
+  // ~1 dependency per 3 issues, always on a lower-numbered issue (acyclic)
+  const edges: DependencyEdge[] = []
+  for (let i = 3; i < n; i += 3) edges.push({ issue: i + 1, dependsOn: i - 1 })
+  return { issues, edges }
+}
+
+function ms(fn: () => void): number {
+  const t0 = performance.now()
+  fn()
+  return performance.now() - t0
+}
+
+describe('perf (#32)', () => {
+  it('scheduler + Monte Carlo forecast < 1s @ 200 open issues', () => {
+    const { issues, edges } = backlog(200)
+    const elapsed = ms(() => {
+      schedule(issues, edges)
+      scheduleWithCapacity(issues, edges, WORKERS)
+      forecast(issues, edges, { workers: WORKERS }) // 2000 trials (default)
+    })
+    // eslint-disable-next-line no-console
+    console.log(`[perf] schedule+capacity+forecast @200 = ${elapsed.toFixed(1)}ms`)
+    expect(elapsed).toBeLessThan(1000)
+  })
+
+  it('scales roughly linearly — 400 issues is well under 4x the 100-issue time', () => {
+    const small = backlog(100)
+    const big = backlog(400)
+    const run = (b: typeof small) => () => {
+      schedule(b.issues, b.edges)
+      forecast(b.issues, b.edges, { workers: WORKERS })
+    }
+    // warm up (JIT) so the ratio reflects steady state
+    run(small)()
+    const t100 = Math.max(ms(run(small)), 0.1)
+    const t400 = ms(run(big))
+    // eslint-disable-next-line no-console
+    console.log(`[perf] @100 = ${t100.toFixed(1)}ms · @400 = ${t400.toFixed(1)}ms · ratio ${(t400 / t100).toFixed(1)}x`)
+    expect(t400).toBeLessThan(t100 * 8) // generous: rules out O(n²), tolerant of jitter
+  })
+})

packages/core/src/queue/write-queue-v0.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import type { IssueChange } from '../changes/apply-changes-v0.js'
+import { affectedIssues, coalesceKey, enqueueWrite, pendingWrites, replayQueue, type QueuedWrite } from './write-queue-v0.js'
+
+const reest = (issue: number, estimate: string): IssueChange =>
+  ({ kind: 'reestimate', issue, estimate }) as IssueChange
+const assign = (issue: number, assignee: string | null): IssueChange => ({ kind: 'assign', issue, assignee })
+
+describe('write-queue-v0 (#33)', () => {
+  it('coalesces repeat writes to the same (issue, axis) — replay applies the latest once', () => {
+    let q: QueuedWrite[] = []
+    q = enqueueWrite(q, reest(7, 'est/2d'), '2026-02-10T09:00:00Z')
+    q = enqueueWrite(q, reest(7, 'est/5d'), '2026-02-10T09:05:00Z') // supersedes est/2d
+    q = enqueueWrite(q, assign(7, 'christian'), '2026-02-10T09:06:00Z') // different axis — kept
+
+    expect(q).toHaveLength(2)
+    const pending = pendingWrites(q)
+    expect(pending).toEqual([
+      { kind: 'reestimate', issue: 7, estimate: 'est/5d' },
+      { kind: 'assign', issue: 7, assignee: 'christian' },
+    ])
+    expect(coalesceKey(reest(7, 'est/2d'))).toBe('7:reestimate')
+  })
+
+  it('keeps writes to different issues and axes distinct', () => {
+    let q: QueuedWrite[] = []
+    q = enqueueWrite(q, reest(7, 'est/2d'), 't1')
+    q = enqueueWrite(q, reest(8, 'est/3d'), 't2')
+    q = enqueueWrite(q, assign(8, null), 't3')
+    expect(q).toHaveLength(3)
+    expect(affectedIssues(q)).toEqual([7, 8])
+  })
+
+  it('a burst of edits then reconnect lands the final state without duplicating', async () => {
+    let q: QueuedWrite[] = []
+    // offline: three edits to #7's estimate, one assign
+    q = enqueueWrite(q, reest(7, 'est/1d'), 't1')
+    q = enqueueWrite(q, reest(7, 'est/2d'), 't2')
+    q = enqueueWrite(q, reest(7, 'est/8d'), 't3')
+    q = enqueueWrite(q, assign(7, 'stephen'), 't4')
+
+    const apply = vi.fn(async () => ({ ok: true }))
+    const { drained, remaining } = await replayQueue(q, apply)
+
+    // only the final estimate + the assign are applied — not three estimate writes
+    expect(apply).toHaveBeenCalledTimes(2)
+    expect(apply).toHaveBeenNthCalledWith(1, { kind: 'reestimate', issue: 7, estimate: 'est/8d' })
+    expect(apply).toHaveBeenNthCalledWith(2, { kind: 'assign', issue: 7, assignee: 'stephen' })
+    expect(remaining).toHaveLength(0)
+    expect(drained).toHaveLength(2)
+  })
+
+  it('keeps writes that still fail on reconnect queued (never throws)', async () => {
+    let q: QueuedWrite[] = []
+    q = enqueueWrite(q, reest(7, 'est/2d'), 't1')
+    q = enqueueWrite(q, reest(8, 'est/3d'), 't2')
+    // #7 applies, #8 rejects (still unreachable) — and one apply throws
+    const apply = vi.fn(async (c: IssueChange) => {
+      if (c.issue === 8) throw new Error('offline')
+      return { ok: true }
+    })
+    const { drained, remaining } = await replayQueue(q, apply)
+    expect(drained.map((w) => w.change.issue)).toEqual([7])
+    expect(remaining.map((w) => w.change.issue)).toEqual([8])
+  })
+})

packages/core/src/queue/write-queue-v0.ts

@@ -0,0 +1,71 @@
+/**
+ * Offline write-queue, v0 (#33). While gitea is unreachable, propose-approved
+ * writes are queued instead of lost; on reconnect they replay in order and
+ * resolve against a fresh reconcile. The one hard requirement is *no duplication*:
+ * replaying must not apply the same intent twice.
+ *
+ * The mechanism is coalescing by axis. Every write targets one field of one issue
+ * (its estimate, priority, assignee, or milestone). Queuing a second write to the
+ * same (issue, axis) supersedes the first — only the latest intent survives — so
+ * a burst of edits replays as one final write, and a replay is idempotent (the
+ * apply path no-ops a change already reflected server-side).
+ */
+
+import type { IssueChange } from '../changes/apply-changes-v0.js'
+
+export interface QueuedWrite {
+  change: IssueChange
+  /** ISO time the write was queued (for display + stable ordering). */
+  queuedAt: string
+}
+
+/**
+ * The coalescing key: one field of one issue. Two writes with the same key are
+ * the same intent expressed twice — the later wins. Each `IssueChange.kind` maps
+ * to exactly one axis, so `issue:kind` is the axis identity.
+ */
+export function coalesceKey(change: IssueChange): string {
+  return `${change.issue}:${change.kind}`
+}
+
+/**
+ * Queue a write, superseding any pending write to the same (issue, axis). The
+ * superseding write moves to the tail so replay order reflects latest intent.
+ */
+export function enqueueWrite(queue: readonly QueuedWrite[], change: IssueChange, queuedAt: string): QueuedWrite[] {
+  const key = coalesceKey(change)
+  return [...queue.filter((w) => coalesceKey(w.change) !== key), { change, queuedAt }]
+}
+
+/** The changes to replay, in order — one per (issue, axis) by construction. */
+export function pendingWrites(queue: readonly QueuedWrite[]): IssueChange[] {
+  return queue.map((w) => w.change)
+}
+
+/** Distinct issues touched by the queue — what a post-replay reconcile should re-read. */
+export function affectedIssues(queue: readonly QueuedWrite[]): number[] {
+  return [...new Set(queue.map((w) => w.change.issue))]
+}
+
+/**
+ * Replay the queue through an apply function (the same guarded write path used
+ * online), in order. Returns the writes that failed (still unreachable / rejected)
+ * so they stay queued; everything else drains. Never throws — a failure is data.
+ */
+export async function replayQueue(
+  queue: readonly QueuedWrite[],
+  apply: (change: IssueChange) => Promise<{ ok: boolean }>,
+): Promise<{ drained: QueuedWrite[]; remaining: QueuedWrite[] }> {
+  const drained: QueuedWrite[] = []
+  const remaining: QueuedWrite[] = []
+  for (const w of queue) {
+    let ok = false
+    try {
+      ok = (await apply(w.change)).ok
+    } catch {
+      ok = false
+    }
+    ;(ok ? drained : remaining).push(w)
+  }
+  return { drained, remaining }
+}