Skip to content

scratch

scratch #

The scratch: content-addressed caching over the type system, in three layers.

Decomposed pure functions over CGType values become memoized, garbage-collected pipeline stages, keyed by merkle hash in a managed scratch. Each layer is ignorant of the one above, and every layer logs what it does through capturegraph.logging, which sits beneath them all.

The store (this package's own leaves) is five ideas and nothing else. Objects are immutable trees under objects/<hash>, named by their own merkle hash. Names point at them, and outlive what they pointed at. A pin is one living process's hold on an object, and nothing held is ever evicted. A lock admits one writer at a time — one per call being computed, one per state being written, one per machine-wide resource in use. It knows nothing about types: everything above hands it trees.

  • [.root][] — Scratch, one process's handle on a scratch root, and the layout on disk.
  • [.configure][] / [.temporary][] — the process-global scratch: an explicit path, else the machine's shared CG_SCRATCH or ~/.cache/capturegraph; or a throwaway one scoped to a block.
  • [.settings][] — the size budget, kept in settings.toml.
  • [.errors][] — ScratchError and its kinds.
  • [.fs][] — the filesystem facts the store reasons with.
  • [.hashing][] — content identity: what a tree is.
  • [.index][] — the SQLite bookkeeping: what exists, what is named, what is held.
  • [.store][] — how trees move through the store, what keeps them there, and ([.store.memo][]) what the store has for one call key.

Values ([.values][]) is where a typed value meets the store: how it becomes an object tree, how it hashes, how a call's arguments hash, and the live directory a call writes into — which is also the Workspace the type system asks for T.new(), provided by importing it here.

Calls ([.calls][]) is the surface a recipe author touches: pure_function memoizes a call, ImpureState keeps state per key, lock reserves a machine-wide resource. The root exports those leaves directly (cg.pure_function, cg.ImpureState, cg.lock, cg.value_hash); .testing ships the cg_scratch pytest fixture. This package is the cg.scratch namespace, and the names below are its surface.