That principle shapes CARTOGRAPH, a local tool for scanning supported TypeScript projects, producing a deterministic architecture graph, and comparing two Git revisions. Every emitted relationship carries repository-relative source evidence—or an explicit reason it could not be resolved.
No analyzer sees every runtime path. Dynamic imports, reflective calls, framework conventions, and generated code can all hide relationships from a static pass. There are two tempting mistakes: silently omit the relationship, or infer a plausible edge and make the graph look complete.
Both choices erase useful information. Omission looks like absence. A guess looks like knowledge. CARTOGRAPH keeps unresolved constructs visible as diagnostics instead. The output can say what the analyzer understood, which evidence supports it, and where its current model stops.
A revision diff can show that files changed; an architecture diff asks what those edits did to the relationships the tool can model. CARTOGRAPH compares two Git revisions and reports added, removed, or changed graph nodes and edges. Deterministic output makes the same source state produce the same snapshot, which gives the diff a stable basis for review.
That is still a structural view, not a complete account of runtime behavior. The graph does not execute the repository. The supported slice is explicit, and unsupported constructs remain visible rather than being presented as covered.
I want architecture tools to help people ask better questions, not replace judgment with a polished picture. An evidence-backed edge can be inspected. An unresolved edge can be investigated. A guessed edge can quietly become part of someone’s mental model.
For this kind of tool, “I don’t know yet” is not a broken report. It is part of the report—and often the most useful thing in it.
]]>That’s why I keep the put path and the repair path separate in StreamHive. A one-shot put waits for a matching acknowledgement and retries within a finite budget. That can handle a lost acknowledgement or a short interruption. It cannot promise that a peer which was offline for hours will catch up.
StreamHive’s peer inventory exchange is the slower loop. It runs at startup and periodically, compares paged inventories, and asks for keys the local store is missing. Repair responses are bounded; a large exchange can continue later instead of growing into unbounded work.
That distinction changes what a healthy signal means. “The write was accepted” describes one operation. “The peers are converging” describes a continuing process across time, restarts, network limits, and storage state. I want the system to expose enough counters and status to tell those stories apart.
There is little value in repairing a replica with bytes that do not match the key they claim to represent. For content-addressed blobs, StreamHive checks key and content at apply and repair-source boundaries. A damaged source is skipped rather than sent as a valid repair.
The hash does not solve every storage problem. It gives one precise check: these bytes match this content-derived key. It does not tell a node how to resolve conflicting application-level records or discover every peer in a changing network.
Distributed storage is often introduced as “copy this object to another machine.” That is the postcard version. The operational version is a loop: accept, acknowledge, compare, repair, and report when the loop is limited or incomplete.
A copy gets the bytes somewhere once. A repair path gives the system a way to notice when reality drifted—and a bounded way to move it closer again.
]]>