NeuronScope
ArchitectureStablesince v0.4.0

Fingerprint pipeline

The end-to-end architecture of canonical hashing: modules, boundaries, invariants, and the failure modes each stage prevents.

Audience: ContributorsRead: 8 minEdit on GitHub Source

The fingerprint pipeline is intentionally small and single-purpose. Everything the library guarantees about reproducibility rests on the four modules below and the invariants they hold.

Interactive pipelinehover · focus · click
ModuleInput adapterModuleCanonicalizerCoreHasherModuleTag builderOutputFingerprint
Module
Input adapter

neuronscope.fingerprint.adapters — resolves a Python value to a canonicalizable object.

Open reference →

Module boundaries

  • Adapter. Only stage that touches user objects. Never sees bytes.
  • Canonicalizer. Only stage that varies by namespace. Never sees hardware.
  • Hasher. Only stage that touches bytes. Never sees objects.
  • Tag builder. Only stage that varies with the wire format version.

Invariants

  • The hasher chunk size is a compile-time constant; changing it is a canonicalizer bump.
  • The adapter cannot cache: caching happens one layer up, keyed by fingerprint.
  • The tag builder never truncates. Digests are always emitted in full.

Failure modes

  • Non-canonical mutation between calls. Caught by the caller comparing digests, not by the pipeline.
  • Adapter miss. Raised as E1104: unknown fingerprint kind before any bytes are hashed.
  • Hash truncation on transport. Prevented by the tag: readers reject any digest whose namespace prefix is missing.
Related