Incremental compilation via content-hash

Definitie

Een herhaalbare verwerkingsstap (compileren, publiceren, indexeren, embedden, samenvatten) slaat per verwerkte entiteit de content-hash van de invoer op. Bij een volgende run vergelijkt de stap de huidige hash met de opgeslagen waarde en slaat verwerking over als de hash gelijk is. Hash-mismatch of ontbrekende hash betekent: opnieuw verwerken.

Context

Pipelines die documenten transformeren naar derived state (gepubliceerde versies, vector-indexes, samenvattingen, wiki-pagina’s) worden duur of langzaam wanneer alles bij elke run opnieuw gedaan wordt. Voor externe bestemmingen (Notion, GitHub, een website) speelt naast snelheid ook ruis: ongewijzigde content opnieuw publiceren genereert valse changelog-entries en kan rate-limits of API-kosten oplopen. Voor LLM-pipelines tellen kosten en latency dubbel op. Het content-hash patroon is de minimale infrastructuur die deze problemen wegneemt zonder dat je een ETL-engine als CocoIndex hoeft binnen te halen.

Kernpunten

De kern is een state-bestand (JSON of SQLite-tabel) met per (entiteit_id, stap_id) minstens drie velden: hash, processed_at, en optioneel output_pointer. SHA-256 over de genormaliseerde inputbytes is de standaardkeuze. Voor markdown-documenten is “genormaliseerd” meestal: trim trailing whitespace, ensure UTF-8, frontmatter erbuiten of erbinnen consistent.

De stap zelf wordt een wrapper. Pseudo-code:

new_hash = sha256(read(entity))
saved = state.get(entity_id, step_id)
if saved and saved.hash == new_hash:
    log("skipped: unchanged")
    return saved.output_pointer
output = run_step(entity)
state.set(entity_id, step_id, hash=new_hash, output_pointer=output, processed_at=now)
return output

Drie ontwerpkeuzes maken het patroon robuust:

1. Force-bypass-flag. Een --force of force=true parameter die de hash-check overslaat. Onmisbaar voor herstel-scenarios (corrupte output, gewijzigde verwerkingslogica, bug fixes in de stap zelf).
2. Stap-versie meehashen. Als de verwerking zelf verandert (bijv. een betere prompt, ander model) blijven oude hashes gelijk maar is de output stale. Oplossing: code_hash of step_version meenemen in de cache-key, zodat een verandering in de stap automatisch invalidatie triggert. Zo doet CocoIndex het.
3. Bron-afleiding boven aparte tabel. Als er al een log of audit-trail bestaat (bijv. publication_log met success-records), kan de “laatst-verwerkte hash” daaruit afgeleid worden. Een aparte state-tabel toevoegen is alleen nodig als afleiden te traag of te complex is. Beslissing motiveren in de PR.

Toepassingen in deze stack

• Atelier vault.publish: per (asset_id, destination_id) skip wanneer asset-hash gelijk is aan laatste success-publicatie naar dezelfde bestemming. Geconcretiseerd als TASK-132. Bouwt voort op content_hash uit TASK-067 (Done) en vault.publish uit TASK-111 (in progress).
• Wiki-compilatie (zoals llm-wiki-compiler doet): per source een hash + lijst van afgeleide concepten, zodat ongewijzigde sources niet opnieuw aan de LLM worden aangeboden. Eigen /wiki skill kan dit overnemen.
• Embedding-update: per chunk hash, alleen herberekenen bij wijziging. Voor ~/KennisBank/.claude/scripts/semantic-tiling.py bij grotere corpora relevant.
• Auto-crosslink: alleen voor gewijzigde wiki-artikelen herrekenen, niet over de hele vault.

Verbanden

• Zie ook: wiki-karpathy-llm-wiki (de tweelagen pipeline waar dit patroon natuurlijk in past)
• Zie ook: wiki-cag-rag-kennisbank-architectuur (waarom een lichtgewicht patroon hier voldoet en een vector-DB niet)
• Gerelateerd project: herinrichting-plan
• Backlog: TASK-132 (Atelier vault.publish delta-checker), TASK-067 (content_hash, Done), TASK-111 (vault.publish, in progress)

Bronnen

CocoIndex documentation. (2026). Overview. https://cocoindex.io/docs/getting_started/overview/

atomicmemory. (2026). llm-wiki-compiler README [GitHub repo]. https://github.com/atomicmemory/llm-wiki-compiler

Sessie-herkomst

• raw-sessie-2026-05-09-llm-wiki-compiler-test-comzorg