Decouple attribution interface from Automerge internals

Consumer-facing interfaces now expose CharAttribution[] entries
instead of the full AttributionMap (which carries Automerge-specific
processedHeads/processedHistoryIndex bookkeeping). This enables
swapping the attribution data source (e.g. to git blame) without
changing any consumer code.

Author: shikokuchuo

claude-notes/plans/2026-04-13-q2-debug-node-attribution.md

@@ -63,6 +63,21 @@ The AST already carries source location info (`s` field on each node, referencin
 - [x] `ReactAstDebugRenderer.tsx` — in `Node`, consume `NodeAttributionContext`, apply color + title tooltip
 - [x] All Phase 3 tests pass (green) — 3 tests
 
+### Phase 4: Decouple Attribution Interface from Automerge Internals
+
+Refactor so that the consumer-facing interface carries only source-agnostic `CharAttribution[]` entries, not the full Automerge-specific `AttributionMap` (which includes `processedHeads` and `processedHistoryIndex` bookkeeping). This enables swapping the attribution data source (e.g., to git blame) without changing any consumer code.
+
+- [x] `getNodeAttribution()` takes `entries: CharAttribution[]` instead of `attributionMap: AttributionMap`
+- [x] `AttributionContext` shape: `entries: CharAttribution[]` instead of `attributionMap: AttributionMap`
+- [x] `UseAttributionResult` type: `entries: CharAttribution[]` instead of `attributionMap: AttributionMap`
+- [x] `useAttribution` hook internally retains `AttributionMap` for incremental updates but only surfaces `.entries` to consumers
+- [x] `Editor.tsx` context value: `entries: attribution.entries`
+- [x] `ReactAstDebugRenderer.tsx`: reads `attributionCtx.entries`
+- [x] Tests updated: service tests pass `CharAttribution[]` directly; hook tests assert on `.entries`
+- [x] All 453 tests pass, TypeScript type-checks cleanly
+
+**Rationale**: The `processedHeads` and `processedHistoryIndex` fields are Automerge incremental-update bookkeeping — they only matter inside the hook, never to consumers. With this refactor, a future git blame provider only needs to produce `{ entries: CharAttribution[], byteToCharMap: number[] }` (the same hook return shape), and everything downstream works unchanged.
+
 ### Verification
 
 - [x] `npm run build:all` passes from hub-client (after annotated-qmd fixes in `c6200953`)
@@ -254,7 +269,7 @@ export function updateAttributionMap(
 export function getNodeAttribution(
   sourceInfoId: number,
   reconstructor: SourceInfoReconstructor,
-  attributionMap: AttributionMap,
+  entries: CharAttribution[],       // source-agnostic (Phase 4 refactor)
   byteToCharMap: number[],
   identities: Record<string, ActorIdentity>,
 ): NodeAttribution | null;
@@ -284,7 +299,7 @@ const sourceContext: SourceContext = {
 
 **IMPORTANT — `content` is NOT in the WASM output**: The Rust JSON writer (`crates/pampa/src/writers/json.rs:66-72`) serializes `FileEntryJson` with only `{ line_breaks?, name, total_length? }` — no `content` field. The `SourceInfoReconstructor` constructor **throws** if `file.content` is null/undefined (`ts-packages/annotated-qmd/src/source-map.ts:63-67`). Before constructing the reconstructor, the QMD source text must be injected into `astContext.files[0].content`. This text is the same Automerge document content that was passed to the WASM parser. The `Ast` component must receive this text (via `AttributionContext` or as a prop) to populate the field.
 
-**Query function**: `getNodeAttribution(sourceInfoId, reconstructor, attributionMap, byteToCharMap, identities) -> NodeAttribution | null` — calls `reconstructor.getSourceLocation(sourceInfoId)` to get `{ fileId, start, end }` in top-level byte coordinates, converts to char range via `byteToCharMap`, finds the most recent `{ actor, time }` in that range, resolves identity.
+**Query function**: `getNodeAttribution(sourceInfoId, reconstructor, entries, byteToCharMap, identities) -> NodeAttribution | null` — calls `reconstructor.getSourceLocation(sourceInfoId)` to get `{ fileId, start, end }` in top-level byte coordinates, converts to char range via `byteToCharMap`, finds the most recent `{ actor, time }` in the `CharAttribution[]` entries for that range, resolves identity.
 
 ### Phase 2: React Hook + Context
 
@@ -296,25 +311,27 @@ Hook `useAttribution(filePath, identities)` that:
 3. **Cancellation on file switch**: When `filePath` changes, the hook aborts the in-flight build (if any) via `abortController.abort()`, resets state to `null`, and starts a fresh build for the new file.
 4. **Cancellation on unmount**: Cleanup function aborts any in-flight build.
 5. **Fallback to full rebuild**: If `updateAttributionMap` detects history compaction (stored index exceeds history length) or `diff()` fails, it throws a `HistoryCompactedError`. The hook catches this and starts a new async `buildAttributionMap` (returning `null` in the interim until it completes).
-6. Returns `{ attributionMap, byteToCharMap }` or `null`
+6. Returns `{ entries, byteToCharMap }` or `null` (entries is `CharAttribution[]`, extracted from the internal `AttributionMap`)
 
 **Ref stability**: The hook stores the `AttributionMap` in a `useRef` alongside the React state setter, so the debounced callback always operates on the latest map without needing the state value in its closure (avoids stale-closure bugs with rapid edits).
 
 **Context definition** (in the same file or a shared types file):
 ```typescript
 export const AttributionContext = createContext<{
-  attributionMap: AttributionMap;
+  entries: CharAttribution[];   // source-agnostic per-character attribution
   byteToCharMap: number[];
   identities: Record<string, ActorIdentity>;
   sourceText: string;  // QMD text from Automerge doc, needed to populate astContext.files[].content
 } | null>(null);
 ```
 
+**Design note (Phase 4 refactor)**: The context deliberately exposes `entries: CharAttribution[]` instead of the full `AttributionMap`. The Automerge-specific bookkeeping (`processedHeads`, `processedHistoryIndex`) stays internal to the hook. This allows a future git blame provider to produce the same context shape without any consumer changes.
+
 ### Phase 3: Wire Context in Editor, Extract + Render in Ast
 
 **Attribution data flows via context**, avoiding prop drilling through PreviewRouter, ReactPreview, and ReactRenderer:
 
-- [ ] `Editor.tsx` — call `useAttribution(currentFile?.path, identities)`, wrap preview area with `AttributionContext.Provider` passing `{ attributionMap, byteToCharMap, identities, sourceText }` where `sourceText` is the current Automerge document content (already available as the text passed to the preview pipeline)
+- [ ] `Editor.tsx` — call `useAttribution(currentFile?.path, identities)`, wrap preview area with `AttributionContext.Provider` passing `{ entries, byteToCharMap, identities, sourceText }` where `sourceText` is the current Automerge document content (already available as the text passed to the preview pipeline)
 
 The `astJson` string flowing through `ReactPreview → ReactRenderer → Ast` is already the full `RustQmdJson` — it contains `astContext` and per-node `s` fields at runtime. No upstream component needs to extract or thread this data.
 

hub-client/src/components/Editor.tsx

@@ -365,7 +365,7 @@ export default function Editor({ project, files, fileContents, onDisconnect, onC
   const attributionEnabled = currentFormat === 'q2-debug' && attributionPref;
   const attribution = useAttribution(attributionEnabled ? (currentFile?.path ?? null) : null, displayContent);
   const attributionContextValue = attribution ? {
-    attributionMap: attribution.attributionMap,
+    entries: attribution.entries,
     byteToCharMap: attribution.byteToCharMap,
     identities: identities ?? {},
     sourceText: displayContent,

hub-client/src/components/render/ReactAstDebugRenderer.tsx

@@ -575,7 +575,7 @@ const AstRenderer = ({ ast, onNavigateToDocument, setAst }: {
                     const result = getNodeAttribution(
                         sourceInfoId,
                         reconstructor,
-                        attributionCtx.attributionMap,
+                        attributionCtx.entries,
                         byteToChar,
                         attributionCtx.identities,
                     );

hub-client/src/hooks/useAttribution.test.ts

@@ -95,7 +95,7 @@ describe('useAttribution', () => {
 
     // Now should have the map
     expect(result.current).not.toBeNull();
-    expect(result.current!.attributionMap).toBe(mockMap);
+    expect(result.current!.entries).toBe(mockMap.entries);
   });
 
   it('calls updateAttributionMap on sourceText change when map exists', async () => {
@@ -163,7 +163,7 @@ describe('useAttribution', () => {
     // Wait for rebuild
     await act(async () => {});
 
-    expect(result.current!.attributionMap).toBe(freshMap);
+    expect(result.current!.entries).toBe(freshMap.entries);
   });
 
   it('aborts in-flight build and starts fresh on filePath change', async () => {
@@ -203,7 +203,8 @@ describe('useAttribution', () => {
     await act(async () => {});
 
     expect(result.current).not.toBeNull();
-    expect(result.current!.attributionMap.processedHistoryIndex).toBe(2);
+    expect(result.current).not.toBeNull();
+    expect(result.current!.entries).toHaveLength(1);
   });
 
   it('aborts in-flight build on unmount', async () => {

hub-client/src/hooks/useAttribution.ts

@@ -13,7 +13,7 @@ import {
   buildByteToCharMap,
   HistoryCompactedError,
 } from '../services/attribution';
-import type { AttributionMap } from '../services/attribution';
+import type { AttributionMap, CharAttribution } from '../services/attribution';
 import { getFileHandle } from '../services/automergeSync';
 import type { ActorIdentity } from '../services/automergeSync';
 
@@ -22,7 +22,7 @@ import type { ActorIdentity } from '../services/automergeSync';
 // ---------------------------------------------------------------------------
 
 export const AttributionContext = createContext<{
-  attributionMap: AttributionMap;
+  entries: CharAttribution[];
   byteToCharMap: number[];
   identities: Record<string, ActorIdentity>;
   sourceText: string;
@@ -33,7 +33,7 @@ export const AttributionContext = createContext<{
 // ---------------------------------------------------------------------------
 
 interface UseAttributionResult {
-  attributionMap: AttributionMap;
+  entries: CharAttribution[];
   byteToCharMap: number[];
 }
 
@@ -89,7 +89,7 @@ export function useAttribution(
       if (map) {
         const byteToChar = buildByteToCharMap(sourceTextRef.current);
         mapRef.current = map;
-        setResult({ attributionMap: map, byteToCharMap: byteToChar });
+        setResult({ entries: map.entries, byteToCharMap: byteToChar });
       } else {
         mapRef.current = null;
         setResult(null);
@@ -137,7 +137,7 @@ export function useAttribution(
         const updatedMap = updateAttributionMap(mapRef.current, handle, 'text');
         const byteToChar = buildByteToCharMap(sourceText);
         mapRef.current = updatedMap;
-        setResult({ attributionMap: updatedMap, byteToCharMap: byteToChar });
+        setResult({ entries: updatedMap.entries, byteToCharMap: byteToChar });
       } catch (err) {
         if (err instanceof HistoryCompactedError) {
           // History was compacted — need a full rebuild

hub-client/src/services/attribution.test.ts

@@ -510,17 +510,13 @@ describe('getNodeAttribution', () => {
   }
 
   it('resolves source info to node attribution with correct identity', () => {
-    const map: AttributionMap = {
-      entries: [
-        { actor: 'actor1', time: 1000 },
-        { actor: 'actor1', time: 1000 },
-        { actor: 'actor2', time: 2000 },
-        { actor: 'actor2', time: 2000 },
-        { actor: 'actor2', time: 2000 },
-      ],
-      processedHeads: ['h2'],
-      processedHistoryIndex: 2,
-    };
+    const entries: CharAttribution[] = [
+      { actor: 'actor1', time: 1000 },
+      { actor: 'actor1', time: 1000 },
+      { actor: 'actor2', time: 2000 },
+      { actor: 'actor2', time: 2000 },
+      { actor: 'actor2', time: 2000 },
+    ];
 
     // Source info ID 5 → file 0, bytes 2-5 → chars 2-5 (ASCII)
     const reconstructor = createMockReconstructor({ fileId: 0, start: 2, end: 5 });
@@ -529,7 +525,7 @@ describe('getNodeAttribution', () => {
       actor2: { name: 'Bob', color: '#2196F3' },
     };
 
-    const result = getNodeAttribution(5, reconstructor as any, map, byteToCharMap, identities);
+    const result = getNodeAttribution(5, reconstructor as any, entries, byteToCharMap, identities);
 
     expect(result).not.toBeNull();
     expect(result!.actor).toBe('actor2');
@@ -539,36 +535,28 @@ describe('getNodeAttribution', () => {
   });
 
   it('returns null for invalid source info ID (reconstructor throws)', () => {
-    const map: AttributionMap = {
-      entries: [{ actor: 'actor1', time: 1000 }],
-      processedHeads: ['h1'],
-      processedHistoryIndex: 1,
-    };
+    const entries: CharAttribution[] = [{ actor: 'actor1', time: 1000 }];
 
     const reconstructor = createMockReconstructor(null);
     const byteToCharMap = [0];
     const identities: Record<string, ActorIdentity> = {};
 
-    const result = getNodeAttribution(999, reconstructor as any, map, byteToCharMap, identities);
+    const result = getNodeAttribution(999, reconstructor as any, entries, byteToCharMap, identities);
 
     expect(result).toBeNull();
   });
 
   it('returns null when identities map is empty', () => {
-    const map: AttributionMap = {
-      entries: [
-        { actor: 'actor1', time: 1000 },
-        { actor: 'actor1', time: 1000 },
-      ],
-      processedHeads: ['h1'],
-      processedHistoryIndex: 1,
-    };
+    const entries: CharAttribution[] = [
+      { actor: 'actor1', time: 1000 },
+      { actor: 'actor1', time: 1000 },
+    ];
 
     const reconstructor = createMockReconstructor({ fileId: 0, start: 0, end: 2 });
     const byteToCharMap = [0, 1, 2]; // 2 bytes + end boundary
     const identities: Record<string, ActorIdentity> = {};
 
-    const result = getNodeAttribution(0, reconstructor as any, map, byteToCharMap, identities);
+    const result = getNodeAttribution(0, reconstructor as any, entries, byteToCharMap, identities);
 
     // Should still return attribution even without identity — uses fallback
     // The actor is known, but identity may not have name/color
@@ -577,40 +565,32 @@ describe('getNodeAttribution', () => {
     expect(result!.actor).toBe('actor1');
   });
 
-  it('returns null when attribution map is null-like (empty entries for range)', () => {
-    const map: AttributionMap = {
-      entries: [], // empty
-      processedHeads: ['h1'],
-      processedHistoryIndex: 1,
-    };
+  it('returns null when entries array is empty', () => {
+    const entries: CharAttribution[] = [];
 
     const reconstructor = createMockReconstructor({ fileId: 0, start: 0, end: 5 });
     const byteToCharMap = [0, 1, 2, 3, 4];
     const identities: Record<string, ActorIdentity> = {};
 
-    const result = getNodeAttribution(0, reconstructor as any, map, byteToCharMap, identities);
+    const result = getNodeAttribution(0, reconstructor as any, entries, byteToCharMap, identities);
 
     expect(result).toBeNull();
   });
 
   it('finds most recent attribution in the byte range', () => {
-    const map: AttributionMap = {
-      entries: [
-        { actor: 'actor1', time: 1000 },
-        { actor: 'actor2', time: 3000 }, // most recent
-        { actor: 'actor1', time: 2000 },
-      ],
-      processedHeads: ['h3'],
-      processedHistoryIndex: 3,
-    };
+    const entries: CharAttribution[] = [
+      { actor: 'actor1', time: 1000 },
+      { actor: 'actor2', time: 3000 }, // most recent
+      { actor: 'actor1', time: 2000 },
+    ];
 
     const reconstructor = createMockReconstructor({ fileId: 0, start: 0, end: 3 });
     const byteToCharMap = [0, 1, 2, 3]; // 3 bytes + end boundary
     const identities: Record<string, ActorIdentity> = {
       actor2: { name: 'Bob', color: '#E91E63' },
     };
 
-    const result = getNodeAttribution(0, reconstructor as any, map, byteToCharMap, identities);
+    const result = getNodeAttribution(0, reconstructor as any, entries, byteToCharMap, identities);
 
     expect(result).not.toBeNull();
     // Most recent is actor2 at time 3000

hub-client/src/services/attribution.ts

@@ -318,7 +318,7 @@ export function buildByteToCharMap(text: string): number[] {
 export function getNodeAttribution(
   sourceInfoId: number,
   reconstructor: SourceInfoReconstructor,
-  attributionMap: AttributionMap,
+  entries: CharAttribution[],
   byteToCharMap: number[],
   identities: Record<string, ActorIdentity>,
 ): NodeAttribution | null {
@@ -337,7 +337,6 @@ export function getNodeAttribution(
   if (charStart === undefined || charEnd === undefined) return null;
 
   // Find the most recent attribution in this range
-  const entries = attributionMap.entries;
   if (entries.length === 0) return null;
 
   // Clamp range to entries bounds