diff --git a/backup.js b/backup.js
index 912b992..fe2990c 100644
--- a/backup.js
+++ b/backup.js
@@ -8,12 +8,16 @@
// scan cache — round-trips through one human-readable JSON file.
export const BACKUP_FORMAT = 'repolens-backup';
-export const BACKUP_VERSION = 1;
+export const BACKUP_VERSION = 2;
// Upper bounds on how much a single import may write, so a hostile or corrupt
// file can't pin the IndexedDB write lock or blow the storage quota. Anything
// past these is dropped with a surfaced warning (never silently).
-export const MAX_ROWS = { repos: 5000, nodes: 20000, edges: 50000, cache: 5000, collections: 2000, decisions: 5000 };
+export const MAX_ROWS = { repos: 5000, nodes: 20000, edges: 50000, cache: 5000, collections: 2000, decisions: 5000, snapshots: 5000 };
+
+// Per-repo snapshot ring-buffer cap (mirrors SNAPSHOT_CAP in snapshots.js); each
+// imported snapshots row is trimmed to its most recent SNAP_CAP entries.
+const SNAP_CAP = 30;
const arr = (x) => (Array.isArray(x) ? x : []);
const rowHasRepo = (r) => !!(r && r.id != null && r.payload && r.payload.repoId);
@@ -22,10 +26,11 @@ const edgeOk = (e) => !!(e && e.id != null && e.source != null && e.target != nu
const cacheOk = (c) => !!(c && c.repoId && c.platform);
const collectionOk = (c) => !!(c && c.id != null && c.payload && typeof c.payload.name === 'string');
const decisionOk = (d) => !!(d && d.id != null && d.payload && d.payload.repoId && d.payload.decision);
+const snapshotOk = (r) => !!(r && r.id != null && r.repoId && Array.isArray(r.snaps));
/** Empty normalized shape — the safe fallback when a file can't be parsed. */
function emptyValue() {
- return { repos: [], nodes: [], edges: [], cache: [], collections: [], decisions: [] };
+ return { repos: [], nodes: [], edges: [], cache: [], collections: [], decisions: [], snapshots: [] };
}
/**
@@ -34,19 +39,14 @@ function emptyValue() {
* @param {{ repos?: object[], nodes?: object[], edges?: object[], cache?: object[], exportedAt?: string }} [parts]
* @returns {object}
*/
-export function buildBackup({ repos, nodes, edges, cache, collections, decisions, exportedAt } = {}) {
- const r = arr(repos), n = arr(nodes), e = arr(edges), c = arr(cache), col = arr(collections), dec = arr(decisions);
+export function buildBackup({ repos, nodes, edges, cache, collections, decisions, snapshots, exportedAt } = {}) {
+ const r = arr(repos), n = arr(nodes), e = arr(edges), c = arr(cache), col = arr(collections), dec = arr(decisions), snap = arr(snapshots);
return {
format: BACKUP_FORMAT,
version: BACKUP_VERSION,
exportedAt: exportedAt || new Date().toISOString(),
- counts: { repos: r.length, nodes: n.length, edges: e.length, cache: c.length, collections: col.length, decisions: dec.length },
- repos: r,
- nodes: n,
- edges: e,
- cache: c,
- collections: col,
- decisions: dec,
+ counts: { repos: r.length, nodes: n.length, edges: e.length, cache: c.length, collections: col.length, decisions: dec.length, snapshots: snap.length },
+ repos: r, nodes: n, edges: e, cache: c, collections: col, decisions: dec, snapshots: snap,
};
}
@@ -87,6 +87,7 @@ export function validateBackup(obj) {
cache: clamp('cache', arr(obj.cache).filter(cacheOk)),
collections: clamp('collections', arr(obj.collections).filter(collectionOk)),
decisions: clamp('decisions', arr(obj.decisions).filter(decisionOk)),
+ snapshots: clamp('snapshots', arr(obj.snapshots).filter(snapshotOk).map((r) => ({ ...r, snaps: arr(r.snaps).slice(-SNAP_CAP) }))),
};
return { ok: errors.length === 0, errors, warnings, value };
}
@@ -99,7 +100,7 @@ export function validateBackup(obj) {
*/
export function summarizeBackup(obj) {
const { value } = validateBackup(obj);
- return { repos: value.repos.length, nodes: value.nodes.length, edges: value.edges.length, cache: value.cache.length, collections: value.collections.length, decisions: value.decisions.length };
+ return { repos: value.repos.length, nodes: value.nodes.length, edges: value.edges.length, cache: value.cache.length, collections: value.collections.length, decisions: value.decisions.length, snapshots: value.snapshots.length };
}
/**
diff --git a/diff-analysis.js b/diff-analysis.js
index 2e39932..a048f20 100644
--- a/diff-analysis.js
+++ b/diff-analysis.js
@@ -1,7 +1,7 @@
// Pure helpers for "Diff Since I Last Looked" — compares two cached analysis snapshots.
// No DOM, no chrome APIs, unit-testable.
-const FIT_ORDER = ['strong', 'solid', 'care', 'risky'];
+export const FIT_ORDER = ['strong', 'solid', 'care', 'risky'];
const FIT_RANK = Object.fromEntries(FIT_ORDER.map((f, i) => [f, i]));
export function daysSince(isoTs) {
diff --git a/docs/superpowers/plans/2026-06-15-scan-ledger.md b/docs/superpowers/plans/2026-06-15-scan-ledger.md
new file mode 100644
index 0000000..4e4dbaa
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-15-scan-ledger.md
@@ -0,0 +1,794 @@
+# Scan Ledger Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Persist a versioned, capped history of every repo scan and surface each repo's trajectory (a health sparkline on library cards + a "History" strip on the Verdict tab).
+
+**Architecture:** A new additive IndexedDB store (`snapshots`, one record per repo holding a capped `snaps[]` array). All logic lives in a new pure module `snapshots.js` (no DOM/chrome); `store.js` adds thin IndexedDB wrappers and seeds a snapshot on every `saveRepo`. The UI reads snapshots (batched for the library) and draws an inline-SVG sparkline. Snapshots round-trip through the existing backup envelope.
+
+**Tech Stack:** Vanilla ES modules (no build step), IndexedDB (promise-wrapped in `store/idb.js`), Vitest + `fake-indexeddb` for tests.
+
+**Spec:** `docs/superpowers/specs/2026-06-15-scan-ledger-design.md`
+
+---
+
+## File structure
+
+| File | Responsibility | Change |
+|------|----------------|--------|
+| `snapshots.js` | Pure ledger logic: `toSnapshot`, `appendSnapshot`, `snapshotTrend`, `sparkline` | **create** |
+| `tests/snapshots.test.js` | Unit tests for the above | **create** |
+| `diff-analysis.js` | Reuse its `FIT_ORDER` (export it) | modify (1 line) |
+| `store/idb.js` | Add the `snapshots` object store (v3→v4) | modify |
+| `store.js` | `appendScanSnapshot`, `listSnapshots`, `listAllSnapshots`; call from `saveRepo`; backup wiring | modify |
+| `backup.js` | Include `snapshots` in the envelope; bump `BACKUP_VERSION` | modify |
+| `library.js` | Batch-load snapshots in `init()`; draw the card sparkline | modify |
+| `output-tab.js` | `renderHistory(d)` — the Verdict "History" strip | modify |
+| `output-tab.html` | A `
` host for the strip | modify |
+
+Notes carried from the spec into this plan:
+- **Trigger:** every scan. **Metric:** health. **Cap:** 30/repo (ring buffer).
+- **Seeding (refines the spec's "backfill on read"):** seed the *prior* scan into the ledger at scan time, inside `appendScanSnapshot`, using the old payload `saveRepo` already reads. This is strictly better than read-time backfill — no write-on-read side effect, and an existing repo's first re-scan yields a real 2-point trend instead of one dead point. `listSnapshots` therefore stays a pure read.
+- **Trend computation (refines the spec's "reuse `diffAnalyses`"):** `snapshotTrend` computes deltas directly rather than feeding snapshots through `diffAnalyses`. Reason: snapshots store the already-*derived* `fit` and flag *titles* (no severity), so `diffAnalyses`' `_fitLevel` would re-derive fit from lossy data and get it wrong. Direct computation uses the stored fit and is simpler and correct. The one thing reused is `FIT_ORDER` (now exported from `diff-analysis.js`), so the constant isn't copied a fourth time.
+
+---
+
+### Task 1: Pure `snapshots.js` module + tests
+
+**Files:**
+- Create: `snapshots.js`
+- Create: `tests/snapshots.test.js`
+- Modify: `diff-analysis.js:4` (export `FIT_ORDER`)
+
+- [ ] **Step 1: Export `FIT_ORDER` from `diff-analysis.js`**
+
+Change line 4 from `const FIT_ORDER = ['strong', 'solid', 'care', 'risky'];` to:
+
+```js
+export const FIT_ORDER = ['strong', 'solid', 'care', 'risky'];
+```
+
+(Avoids a 4th copy of the constant; the rest of `diff-analysis.js` is unchanged.)
+
+- [ ] **Step 2: Write the failing tests** — `tests/snapshots.test.js`
+
+```js
+import { describe, it, expect } from 'vitest';
+import { toSnapshot, appendSnapshot, snapshotTrend, sparkline, SNAPSHOT_CAP } from '../snapshots.js';
+
+describe('toSnapshot', () => {
+ it('trims a payload to the snapshot shape (health, flag titles, fit via deriveFit)', () => {
+ // Real red_flags carry a `severity`; deriveFit counts non-'ok' flags as warnings,
+ // so health 88 with 2 warning flags derives to 'care' — and the ledger's fit must
+ // match what the app shows (deriveFit on the same payload), so toSnapshot passes the
+ // real red_flags through unfiltered.
+ const snap = toSnapshot(
+ { repoId: 'a/b', health: 88, stars: 1200, red_flags: [{ title: 'No tests', severity: 'warn' }, { title: '', severity: 'warn' }], saved_at: '2026-06-01T00:00:00.000Z' },
+ '2026-06-01T00:00:00.000Z'
+ );
+ expect(snap).toEqual({
+ ts: '2026-06-01T00:00:00.000Z',
+ health: 88,
+ fit: 'care',
+ stars: 1200,
+ flags: ['No tests'], // empty title dropped; titles kept regardless of severity
+ version: null,
+ });
+ });
+ it('derives a strong fit for a healthy, flag-free repo', () => {
+ const snap = toSnapshot({ repoId: 'a/b', health: 90, stars: 0, red_flags: [] }, '2026-06-01T00:00:00.000Z');
+ expect(snap.fit).toBe('strong');
+ });
+ it('accepts health as a { score } object and defaults ts to saved_at', () => {
+ const snap = toSnapshot({ repoId: 'a/b', health: { score: 60 }, stars: 0, red_flags: [], saved_at: '2026-06-02T00:00:00.000Z' });
+ expect(snap.health).toBe(60);
+ expect(snap.ts).toBe('2026-06-02T00:00:00.000Z');
+ expect(snap.fit).toBe('care'); // 60, 0 flags
+ });
+ it('yields null health when absent', () => {
+ expect(toSnapshot({ repoId: 'a/b', red_flags: [] }, '2026-06-01T00:00:00.000Z').health).toBeNull();
+ });
+});
+
+describe('appendSnapshot', () => {
+ it('appends immutably and never mutates the input', () => {
+ const a = [{ ts: '1' }];
+ const out = appendSnapshot(a, { ts: '2' });
+ expect(out).toHaveLength(2);
+ expect(a).toHaveLength(1);
+ });
+ it('keeps only the most recent `cap`', () => {
+ const many = Array.from({ length: SNAPSHOT_CAP }, (_, i) => ({ ts: String(i) }));
+ const out = appendSnapshot(many, { ts: 'new' }, SNAPSHOT_CAP);
+ expect(out).toHaveLength(SNAPSHOT_CAP);
+ expect(out[0].ts).toBe('1');
+ expect(out[out.length - 1].ts).toBe('new');
+ });
+ it('handles a non-array prev', () => {
+ expect(appendSnapshot(undefined, { ts: 'x' })).toEqual([{ ts: 'x' }]);
+ });
+});
+
+describe('snapshotTrend', () => {
+ const snaps = [
+ { ts: '2026-06-01T00:00:00.000Z', health: 72, fit: 'care', stars: 100, flags: ['No tests', 'Stale'] },
+ { ts: '2026-06-11T00:00:00.000Z', health: 91, fit: 'strong', stars: 150, flags: ['No tests'] },
+ ];
+ it('returns null for <2 points', () => {
+ expect(snapshotTrend([])).toBeNull();
+ expect(snapshotTrend([snaps[0]])).toBeNull();
+ });
+ it('computes health delta, fit direction, flag diffs and day span', () => {
+ const t = snapshotTrend(snaps);
+ expect(t.count).toBe(2);
+ expect(t.healthDelta).toBe(19);
+ expect(t.fitFrom).toBe('care');
+ expect(t.fitTo).toBe('strong');
+ expect(t.fitDirection).toBe('up');
+ expect(t.flagsResolved).toEqual(['Stale']);
+ expect(t.flagsNew).toEqual([]);
+ expect(t.daysSpan).toBe(10);
+ expect(t.series).toHaveLength(2);
+ });
+});
+
+describe('sparkline', () => {
+ it('returns null for <2 plottable points', () => {
+ expect(sparkline([{ health: 5 }])).toBeNull();
+ expect(sparkline([{ health: null }, { health: null }])).toBeNull();
+ });
+ it('builds an svg polyline scaled to the box', () => {
+ const svg = sparkline([{ health: 0 }, { health: 50 }, { health: 100 }], { width: 100, height: 20 });
+ expect(svg).toContain(' f && f.title).filter(Boolean),
+ version: (payload && payload.version) || null,
+ };
+}
+
+/** Append a snapshot immutably, keeping only the most recent `cap`. */
+export function appendSnapshot(snaps, snap, cap = SNAPSHOT_CAP) {
+ const next = [...(Array.isArray(snaps) ? snaps : []), snap];
+ return next.length > cap ? next.slice(next.length - cap) : next;
+}
+
+/** Direction of a fit change: 'up' (improved), 'down' (worse), 'same'. Lower index = better. */
+function fitDirection(from, to) {
+ const a = FIT_ORDER.indexOf(from);
+ const b = FIT_ORDER.indexOf(to);
+ if (a < 0 || b < 0 || a === b) return 'same';
+ return b < a ? 'up' : 'down';
+}
+
+/**
+ * Derive a trend from a snapshot list (oldest→newest). Returns null if <2 points.
+ * @returns {null | { count, series, first, latest, healthDelta, fitFrom, fitTo,
+ * fitDirection, flagsResolved, flagsNew, daysSpan }}
+ */
+export function snapshotTrend(snaps) {
+ const list = (Array.isArray(snaps) ? snaps : []).filter((s) => s && s.ts);
+ if (list.length < 2) return null;
+ const first = list[0];
+ const latest = list[list.length - 1];
+ const series = list.map((s) => ({ ts: s.ts, health: s.health, fit: s.fit, stars: s.stars }));
+ const healthDelta =
+ first.health != null && latest.health != null ? latest.health - first.health : null;
+ const firstFlags = new Set(first.flags || []);
+ const latestFlags = new Set(latest.flags || []);
+ return {
+ count: list.length,
+ series,
+ first,
+ latest,
+ healthDelta,
+ fitFrom: first.fit,
+ fitTo: latest.fit,
+ fitDirection: fitDirection(first.fit, latest.fit),
+ flagsResolved: [...firstFlags].filter((t) => !latestFlags.has(t)),
+ flagsNew: [...latestFlags].filter((t) => !firstFlags.has(t)),
+ daysSpan: Math.max(0, Math.round((Date.parse(latest.ts) - Date.parse(first.ts)) / 86_400_000)),
+ };
+}
+
+/**
+ * Build an inline-SVG sparkline string from a trend series. Plots `metric`
+ * (default 'health'), skipping null points. Returns null if <2 plottable points.
+ */
+export function sparkline(series, { metric = 'health', width = 120, height = 32, stroke = 'currentColor' } = {}) {
+ const all = Array.isArray(series) ? series : [];
+ const pts = all
+ .map((s, i) => {
+ const raw = s ? s[metric] : undefined;
+ return { i, v: raw == null ? NaN : Number(raw) }; // null/undefined are not plottable (Number(null)===0)
+ })
+ .filter((p) => Number.isFinite(p.v));
+ if (pts.length < 2) return null;
+ const n = all.length;
+ const vals = pts.map((p) => p.v);
+ const min = Math.min(...vals);
+ const max = Math.max(...vals);
+ const span = max - min || 1;
+ const x = (i) => (n <= 1 ? 0 : (i / (n - 1)) * width);
+ const y = (v) => height - ((v - min) / span) * height;
+ const coords = pts.map((p) => `${x(p.i).toFixed(1)},${y(p.v).toFixed(1)}`);
+ const last = pts[pts.length - 1];
+ return (
+ ``
+ );
+}
+```
+
+- [ ] **Step 5: Run the tests, verify they PASS**
+
+Run: `npx vitest run tests/snapshots.test.js`
+Expected: PASS (all describe blocks green).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add snapshots.js tests/snapshots.test.js diff-analysis.js
+git commit -m "feat(ledger): pure snapshots module (toSnapshot/appendSnapshot/snapshotTrend/sparkline)"
+```
+
+---
+
+### Task 2: Add the `snapshots` IndexedDB store (v3 → v4)
+
+**Files:**
+- Modify: `store/idb.js:5-9`
+
+- [ ] **Step 1: Bump the schema**
+
+Replace the version/comment/STORES block (lines 5-9) with:
+
+```js
+// v2 added the 'collections' store. v3 added the 'decisions' store. v4 added the
+// 'snapshots' store (the Scan Ledger). Each upgrade is additive — onupgradeneeded
+// creates any store in STORES that doesn't already exist, so existing data survives.
+const DB_VERSION = 4;
+const STORES = ['repos', 'nodes', 'edges', 'collections', 'decisions', 'snapshots'];
+```
+
+- [ ] **Step 2: Verify nothing broke**
+
+Run: `npx vitest run tests/idb.test.js tests/store.test.js`
+Expected: PASS (existing IndexedDB tests still green — the change is purely additive).
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add store/idb.js
+git commit -m "feat(ledger): add 'snapshots' object store (idb v3->v4, additive)"
+```
+
+---
+
+### Task 3: `store.js` wrappers + `saveRepo` hook
+
+**Files:**
+- Modify: `store.js` (import; `saveRepo`; three new functions)
+- Modify: `tests/store.test.js` (new cases)
+
+- [ ] **Step 1: Write the failing tests** — append to `tests/store.test.js`
+
+```js
+import { appendScanSnapshot, listSnapshots, listAllSnapshots, saveRepo } from '../store.js';
+
+describe('scan ledger', () => {
+ it('saveRepo records a snapshot and re-scan appends a second point', async () => {
+ await saveRepo({ repoId: 'led/one', health: 70, stars: 10, red_flags: [] });
+ await saveRepo({ repoId: 'led/one', health: 90, stars: 20, red_flags: [] });
+ const snaps = await listSnapshots('led/one');
+ expect(snaps.length).toBe(2);
+ expect(snaps[0].health).toBe(70);
+ expect(snaps[1].health).toBe(90);
+ });
+
+ it('caps history at 30 (ring buffer)', async () => {
+ for (let i = 0; i < 35; i++) {
+ await appendScanSnapshot({ repoId: 'led/cap', health: i, stars: 0, red_flags: [], saved_at: `2026-06-01T00:00:${String(i).padStart(2, '0')}.000Z` });
+ }
+ const snaps = await listSnapshots('led/cap');
+ expect(snaps.length).toBe(30);
+ expect(snaps[snaps.length - 1].health).toBe(34);
+ });
+
+ it('seeds the prior scan into the ledger on first re-scan of an existing repo', async () => {
+ // A repo scanned before the ledger existed has a repos payload but no snapshots.
+ // appendScanSnapshot must record that prior state (prevPayload) before the new one.
+ const prev = { repoId: 'led/seed', health: 40, stars: 1, red_flags: [], saved_at: '2026-05-01T00:00:00.000Z' };
+ const next = { repoId: 'led/seed', health: 80, stars: 2, red_flags: [], saved_at: '2026-06-01T00:00:00.000Z' };
+ await appendScanSnapshot(next, prev);
+ const snaps = await listSnapshots('led/seed');
+ expect(snaps.map((s) => s.health)).toEqual([40, 80]);
+ });
+
+ it('listAllSnapshots returns a Map keyed by repoId', async () => {
+ await saveRepo({ repoId: 'led/map', health: 60, stars: 0, red_flags: [] });
+ const map = await listAllSnapshots();
+ expect(map.has('led/map')).toBe(true);
+ expect(Array.isArray(map.get('led/map'))).toBe(true);
+ });
+});
+```
+
+- [ ] **Step 2: Run, verify FAIL**
+
+Run: `npx vitest run tests/store.test.js`
+Expected: FAIL — `appendScanSnapshot`/`listSnapshots`/`listAllSnapshots` are not exported.
+
+- [ ] **Step 3: Implement in `store.js`**
+
+Add to the imports near the top (after the existing `./store/egograph.js` import on line 10):
+
+```js
+import { toSnapshot, appendSnapshot, SNAPSHOT_CAP } from './snapshots.js';
+```
+
+In `saveRepo`, the function already reads `existing` (line 26). Add the ledger write at the end of the function, immediately after `await idbPut('repos', { id: hashRepoId(analysis.repoId), payload });` (line 50):
+
+```js
+ await appendScanSnapshot(payload, existing?.payload);
+```
+
+Then add these three functions in the `// ─── repos` section (e.g. after `saveRepo`):
+
+```js
+/**
+ * Append a snapshot for a repo's current payload (best-effort — a ledger write
+ * must never fail a scan). `prevPayload` (the repo's previous state, which saveRepo
+ * already reads) seeds one prior point the first time, so an existing repo's first
+ * re-scan yields a real 2-point trend instead of losing its history.
+ */
+export async function appendScanSnapshot(payload, prevPayload) {
+ if (!payload || !payload.repoId) return;
+ try {
+ const id = hashRepoId(payload.repoId);
+ const rec = await idbGet('snapshots', id).catch(() => null);
+ let snaps = rec && Array.isArray(rec.snaps) ? rec.snaps : [];
+ if (!snaps.length && prevPayload && prevPayload.saved_at) {
+ snaps = [toSnapshot(prevPayload)];
+ }
+ snaps = appendSnapshot(snaps, toSnapshot(payload), SNAPSHOT_CAP);
+ await idbPut('snapshots', { id, repoId: payload.repoId, snaps });
+ } catch {
+ /* the ledger is additive; a write failure must not break the scan */
+ }
+}
+
+/** A repo's snapshot history (oldest→newest). Best-effort — [] on failure. */
+export async function listSnapshots(repoId) {
+ try {
+ const rec = await idbGet('snapshots', hashRepoId(repoId));
+ return rec && Array.isArray(rec.snaps) ? rec.snaps : [];
+ } catch {
+ return [];
+ }
+}
+
+/** All snapshot histories as a Map(repoId → snaps[]) for batch rendering. */
+export async function listAllSnapshots() {
+ try {
+ const rows = await idbGetAll('snapshots');
+ return new Map((rows || []).filter((r) => r && r.repoId).map((r) => [r.repoId, r.snaps || []]));
+ } catch {
+ return new Map();
+ }
+}
+```
+
+- [ ] **Step 4: Run, verify PASS**
+
+Run: `npx vitest run tests/store.test.js`
+Expected: PASS.
+
+- [ ] **Step 5: Full suite green**
+
+Run: `npm test`
+Expected: PASS (no regressions).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add store.js tests/store.test.js
+git commit -m "feat(ledger): record + read snapshots in store.js, seed prior scan on saveRepo"
+```
+
+---
+
+### Task 4: Backup round-trip for `snapshots`
+
+**Files:**
+- Modify: `backup.js` (version, MAX_ROWS, emptyValue, buildBackup, validateBackup, summarizeBackup)
+- Modify: `store.js` (`exportStores`, `importStores`)
+- Modify: `tests/backup.test.js`, `tests/store-backup.test.js` (new cases)
+
+- [ ] **Step 1: Write the failing tests** — append to `tests/backup.test.js`
+
+```js
+import { buildBackup, validateBackup, BACKUP_VERSION } from '../backup.js';
+
+describe('backup: snapshots', () => {
+ const snapRow = { id: 1, repoId: 'a/b', snaps: [{ ts: '2026-06-01T00:00:00.000Z', health: 80, fit: 'solid', stars: 1, flags: [] }] };
+
+ it('buildBackup includes snapshots and counts them', () => {
+ const b = buildBackup({ snapshots: [snapRow], exportedAt: '2026-06-15T00:00:00.000Z' });
+ expect(b.version).toBe(BACKUP_VERSION);
+ expect(b.snapshots).toHaveLength(1);
+ expect(b.counts.snapshots).toBe(1);
+ });
+
+ it('validateBackup keeps well-formed snapshot rows and drops malformed ones', () => {
+ const { value } = validateBackup({
+ format: 'repolens-backup',
+ version: BACKUP_VERSION,
+ snapshots: [snapRow, { id: 2 }, { repoId: 'x', snaps: [] }],
+ });
+ expect(value.snapshots).toHaveLength(1);
+ expect(value.snapshots[0].repoId).toBe('a/b');
+ });
+});
+```
+
+- [ ] **Step 2: Run, verify FAIL**
+
+Run: `npx vitest run tests/backup.test.js`
+Expected: FAIL — `b.snapshots` is undefined / `value.snapshots` is undefined.
+
+- [ ] **Step 3: Edit `backup.js`**
+
+Bump the version (line 11):
+
+```js
+export const BACKUP_VERSION = 2;
+```
+
+Add a snapshots bound to `MAX_ROWS` (line 16) — append `, snapshots: 5000` inside the object:
+
+```js
+export const MAX_ROWS = { repos: 5000, nodes: 20000, edges: 50000, cache: 5000, collections: 2000, decisions: 5000, snapshots: 5000 };
+```
+
+Add a validator next to the others (after line 24):
+
+```js
+const snapshotOk = (r) => !!(r && r.id != null && r.repoId && Array.isArray(r.snaps));
+```
+
+In `emptyValue()` (line 28) add `snapshots: []`:
+
+```js
+ return { repos: [], nodes: [], edges: [], cache: [], collections: [], decisions: [], snapshots: [] };
+```
+
+In `buildBackup` (lines 37-50) add `snapshots` to the destructure, the `arr()` line, `counts`, and the body:
+
+```js
+export function buildBackup({ repos, nodes, edges, cache, collections, decisions, snapshots, exportedAt } = {}) {
+ const r = arr(repos), n = arr(nodes), e = arr(edges), c = arr(cache), col = arr(collections), dec = arr(decisions), snap = arr(snapshots);
+ return {
+ format: BACKUP_FORMAT,
+ version: BACKUP_VERSION,
+ exportedAt: exportedAt || new Date().toISOString(),
+ counts: { repos: r.length, nodes: n.length, edges: e.length, cache: c.length, collections: col.length, decisions: dec.length, snapshots: snap.length },
+ repos: r, nodes: n, edges: e, cache: c, collections: col, decisions: dec, snapshots: snap,
+ };
+}
+```
+
+In `validateBackup`'s `value` object (lines 83-90) add the snapshots line:
+
+```js
+ snapshots: clamp('snapshots', arr(obj.snapshots).filter(snapshotOk)),
+```
+
+In `summarizeBackup` (line 102) add `, snapshots: value.snapshots.length` to the returned object.
+
+- [ ] **Step 4: Run, verify PASS**
+
+Run: `npx vitest run tests/backup.test.js`
+Expected: PASS.
+
+- [ ] **Step 5: Wire the IndexedDB I/O in `store.js`**
+
+In `exportStores` (lines 234-243): add `idbGetAll('snapshots')` to the `Promise.all` and include it in the destructure + returned object:
+
+```js
+export async function exportStores() {
+ const [repos, nodes, edges, collections, decisions, snapshots] = await Promise.all([
+ idbGetAll('repos'),
+ idbGetAll('nodes'),
+ idbGetAll('edges'),
+ idbGetAll('collections'),
+ idbGetAll('decisions'),
+ idbGetAll('snapshots'),
+ ]);
+ return { repos: repos || [], nodes: nodes || [], edges: edges || [], collections: collections || [], decisions: decisions || [], snapshots: snapshots || [] };
+}
+```
+
+In `importStores` (lines 254-265): add `snapshots = []` to the params, the `replace` clear, the validRows line, and the write loop:
+
+```js
+export async function importStores({ repos = [], nodes = [], edges = [], collections = [], decisions = [], snapshots = [] } = {}, { mode = 'merge' } = {}) {
+ if (mode === 'replace') {
+ await Promise.all([idbClear('repos'), idbClear('nodes'), idbClear('edges'), idbClear('collections'), idbClear('decisions'), idbClear('snapshots')]);
+ }
+ const vr = validRows(repos), vn = validRows(nodes), ve = validRows(edges), vc = validRows(collections), vd = validRows(decisions), vs = validRows(snapshots);
+ for (const row of vr) await idbPut('repos', row);
+ for (const row of vn) await idbPut('nodes', row);
+ for (const row of ve) await idbPut('edges', row);
+ for (const row of vc) await idbPut('collections', row);
+ for (const row of vd) await idbPut('decisions', row);
+ for (const row of vs) await idbPut('snapshots', row);
+ return { repos: vr.length, nodes: vn.length, edges: ve.length, collections: vc.length, decisions: vd.length, snapshots: vs.length };
+}
+```
+
+Also add `idbClear('snapshots')` to the `clearLibrary()` `Promise.all` (line 269).
+
+- [ ] **Step 6: Confirm the export/import HANDLERS pass snapshots through**
+
+The library export handler is around `library.js:861` (`const [stores, cached] = await Promise.all([exportStores(), listCached()...])`). Open it and confirm `buildBackup` is called by spreading the stores object (e.g. `buildBackup({ ...stores, cache })`). Because `exportStores` now returns `snapshots`, a spread flows it through with no further change. If the handler enumerates fields explicitly instead of spreading, add `snapshots: stores.snapshots`. Likewise, find the import handler (it calls `importStores(...)` with `validateBackup(parsed).value`) and confirm it passes the whole `value` (which now includes `snapshots`). If it destructures explicitly, add `snapshots`.
+
+- [ ] **Step 7: Round-trip test** — append to `tests/store-backup.test.js`
+
+```js
+import { saveRepo, exportStores, importStores, clearLibrary, listSnapshots } from '../store.js';
+
+it('snapshots survive an export → clear → import round-trip', async () => {
+ await saveRepo({ repoId: 'rt/one', health: 70, stars: 0, red_flags: [] });
+ await saveRepo({ repoId: 'rt/one', health: 85, stars: 0, red_flags: [] });
+ const dump = await exportStores();
+ expect(dump.snapshots.length).toBe(1);
+ await clearLibrary();
+ expect(await listSnapshots('rt/one')).toEqual([]);
+ await importStores(dump, { mode: 'replace' });
+ const snaps = await listSnapshots('rt/one');
+ expect(snaps.map((s) => s.health)).toEqual([70, 85]);
+});
+```
+
+- [ ] **Step 8: Run, verify PASS + full suite**
+
+Run: `npx vitest run tests/backup.test.js tests/store-backup.test.js && npm test`
+Expected: PASS.
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add backup.js store.js tests/backup.test.js tests/store-backup.test.js library.js
+git commit -m "feat(ledger): round-trip snapshots through the backup envelope (v2)"
+```
+
+---
+
+### Task 5: Library card health sparkline
+
+**Files:**
+- Modify: `library.js` (import; module Map; load in `init()`; render in `card()`)
+
+No unit test (DOM/SW shell, per repo norm); the `snapshotTrend`/`sparkline` math is already covered in Task 1. Verify manually.
+
+- [ ] **Step 1: Import the helpers + store loader**
+
+Add to the `library-data.js` import line area (top of file). Extend the existing `./store.js` import (line 6) to include `listAllSnapshots`, and add a new import for the pure helpers:
+
+```js
+import { listAllSnapshots } from './store.js'; // add to the existing store.js import list
+import { snapshotTrend, sparkline } from './snapshots.js';
+```
+
+(Practically: append `listAllSnapshots` to the destructured names already imported from `./store.js` on line 6, and add the `snapshots.js` import below the `library-data.js` import on line 11.)
+
+- [ ] **Step 2: Add a module-level snapshot map**
+
+Next to `let allRows = [];` (line 44), add:
+
+```js
+let snapsByRepo = new Map(); // repoId → snaps[] (batch-loaded once in init)
+```
+
+- [ ] **Step 3: Batch-load snapshots in `init()`**
+
+`init()` starts at line 2300 and builds rows at lines 2349-2351. Immediately before `const savedRows = points.map((p) => libraryRow(p.payload));` (line 2349), add:
+
+```js
+ snapsByRepo = await listAllSnapshots();
+```
+
+- [ ] **Step 4: Render the sparkline in `card()`**
+
+In `card(r)`, just before the closing `
` of `.lc-meta` is built — i.e. insert a new line in the returned template right after the `.lc-meta` closing `` (after line 155) and before the `${tags || boardDots ...}` line (156):
+
+```js
+ ${(() => {
+ const trend = snapshotTrend(snapsByRepo.get(r.repoId) || []);
+ if (!trend) return '';
+ const svg = sparkline(trend.series, { metric: 'health', width: 96, height: 22 });
+ if (!svg) return '';
+ const sign = trend.healthDelta > 0 ? '+' : '';
+ const delta = trend.healthDelta != null ? `${sign}${trend.healthDelta}` : '';
+ return `
`;
+ })()}
+```
+
+- [ ] **Step 5: Add the sparkline styles** — append to `library.html` inside its `
+
+
+
+
+
+
Design Blueprint · for review
+
Scan Ledger
+
Give every repo a memory. Each scan becomes a durable, versioned snapshot — so a repo's health, fit, and flags read as a trajectory, not a single anonymous number.
RepoLens's pitch is "evaluations compound" — but today saveRepooverwrites the latest analysis on every re-scan and keeps just a single prevFitLevel. The diffAnalyses() engine is fully built, yet structurally starved: it can only ever see two points because only one prior exists.
+
Scan Ledger persists the history those features were waiting for — the missing substrate that later unlocks drift/regret alerts and decision-replay.
+
+
+
+
02
What you'll see
+
Two read-only surfaces. Both appear only once a repo has ≥2 scans, and both stay static under reduced-motion.
+
+
+
Library card — health sparkline
+
+
+
+ facebook/react
+ Strong
+
+
ui-library · 220k★ · health 91
+
+
+ +19 · 6 scans · 60d
+
+
+
+
+
+
Verdict tab — "History" strip
+
+
History
+
6 scans · last 60 days
+
+ Health
+
+
+ 72 → 80 → 76 → 84 → 88 → 91
+
+
+
+ Fit
+ care → solid → solid → solid → strong ↑
+
+
+ Flags
+ −2 resolved · +0 new
+
+
+
+
+
Mockups rendered live — the real sparkline is an inline SVG string built the same way graph.js / diagram.js draw, no chart library.
+
+
+
03
Confirmed decisions
+
+
Snapshot trigger
Every scanIt's a scan ledger — honest, and the cap bounds it.
+
Sparkline metric
Health over timeFit shown as the line's tint + the progression row.
+
Retention
30 / repoRing buffer — drop the oldest.
+
Storage shape
One record / repoA snaps[] array — trivial trimming, one read.
+
+
+
+
04
Under the hood
+
A new IndexedDB store, one new pure module, thin store wrappers. Everything testable lands on the testable side of the codebase.
+
+
Data model — new snapshots store
+
// one record per repo, keyed by id (same convention as every store)
+{
+ id: <repoHash>, // hashRepoId(repoId) — the hash 'repos' already uses
+ repoId: string,
+ snaps: Snapshot[] // oldest → newest, max 30
+}
+
+Snapshot = {
+ ts: string, // ISO; equals the scan's saved_at
+ health: number | null,
+ fit: 'strong'|'solid'|'care'|'risky'|'unrated',
+ stars: number,
+ flags: string[], // red_flag titles at scan time
+ version: string | null // repo HEAD sha / pkg version, if known
+}
+
+
Data flow
+
+
1
A scan completes → saveRepo() writes the repos payload (unchanged), then calls appendScanSnapshot(payload).
+
2
Library loads → snapshots are batch-read once via a single idbGetAll('snapshots') into a Map (no per-card round-trips); each card draws its sparkline.
+
3
Verdict tab renders → the History strip is built from the same snapshotTrend(), through the existing html/esc escaping path.
+
+
+
New pure module — snapshots.jsfully unit-tested
+
+
toSnapshot(payload) → Snapshot
Trim a repo payload to a snapshot. Fit via deriveFit(payload)?.level — the same helper store.js already uses, so the ledger matches the app.
+
appendSnapshot(snaps, snap, cap = 30) → Snapshot[]
An inline-SVG points/path string. null if <2 usable points.
+
+
+
+
05
Migration, backup & edges
+
+
+
Additive migration
+
+
store/idb.js: DB_VERSION 3 → 4, add 'snapshots' to STORES. Existing data untouched — same as the v2 (collections) / v3 (decisions) upgrades.
+
Backfill: a repo scanned before this feature has no record — on first read, synthesize one snapshot from its stored payload, so existing users see a point right away.
+
+
+
+
Backup & safety
+
+
snapshots joins exportStores/importStores; bump BACKUP_VERSION; clamp to the 30-cap on import (fails safe).
+
Quota: 30 × ~200 B × N repos ≈ a few MB — negligible for IndexedDB.
+
Race:saveRepo is the only writer and scans are serialized — read-modify-write is safe.
+
+
+
+
+
+
06
Testing & footprint
+
+
+
Tests
+
+
snapshots.test.js — append/trim/immutability, trend deltas, fit direction, sparkline math (<2 → null).
+
Store (fake-indexeddb) — append + cap at 30, backfill-from-payload, export/import round-trip + clamp.
+
UI rendering stays untested (repo norm); its pure view-model builders are covered.