Short answer
#What a snapshot is
- Snapshot
- A complete, addressable state of a project's knowledge at a point in time, produced by writing one approved Evidence Package into the project store. Snapshots are kept rather than replaced, which is what makes any statement about change possible.
- In plain terms The state of a project's technical picture after one analysis has been written into it.
The distinction that matters: a snapshot is not the package. A package is what an analysis produced; a snapshot is what the project knows after that package has been reconciled with everything it already knew. The reconciliation is where the work is.
#The identity problem
Any tool that claims to track architecture over time has this problem. Most solve it by not mentioning it.
For the sentence "the billing service now also writes to the audit database" to be produceable, the system has to decide that the billing service described in September is the same billing service described in May. Three obvious approaches all fail:
- By name. Rename a class and it is still the same class. Two things called "Main database" are still two things.
- By path. Move a file and every path-based identity breaks at once. Restructure a directory and the whole system appears to have been replaced.
- By similarity. Guessing that two descriptions are close enough produces confident, unfalsifiable, occasionally wrong merges — the worst possible failure mode for a product whose value is that its claims are checkable.
So identity is declared rather than inferred. Each entity carries a repository path, a fully qualified name, or an external identifier chosen and kept for things that have neither — a database, a queue, a deployment target. An entity with none of the three is treated as new every time, and its history restarts.
What this costs
Requiring an identifier puts work on the analysis rather than on the server, and an agent that supplies a careless external identifier produces a careless history. That is a real trade. The alternative — inferring identity from similarity — moves the same uncertainty somewhere the user cannot see it, which is worse.
#The version that got it wrong
This is worth stating plainly because it is the kind of thing a product page normally omits.
An earlier version of 1ADK's ingestion did infer more than it should have. Two analyses of an unchanged system produced duplicate entities for things that should have been recognised as the same — the second scan created a second copy rather than matching. From the outside it looked like a system that had doubled in size overnight.
It was fixed by making identity explicit: requiring the identifier in the package, matching on it, and treating an entity without one as genuinely new rather than guessing. The reason to publish this is that it is the failure any comparable tool will have, and knowing to ask about it is useful whoever you end up buying from.
#Coverage decides what may be called removed
Reporting an addition is easy. Reporting a removal requires knowing that you looked where the thing used to be.
Every analysis records coverage per scope: complete, partial, not covered, or unknown, plus what was deliberately excluded. When the current analysis did not cover the area a component lived in, 1ADK does not report the component as removed. It reports that it was not seen this time — a different and much smaller statement.
The practical consequence: a deliberately narrow analysis does not read as a demolition. Without this, the first person to scan a single directory would be told most of their system had ceased to exist, and would rightly never trust the product again.
#What a semantic difference is
Not a source diff. The unit is a component, an interface, a relation or a claim — not a line. Comparing two snapshots produces four kinds of statement:
| Outcome | Condition |
|---|---|
| Arrived | Present now, absent before, and identity says it is not a rename of something known. |
| Changed | Same identity, different description, relations, interface or claims. |
| Gone | Absent now, present before, and the current analysis covered the scope it lived in completely. |
| No longer confirmed | A claim that was supported by evidence in an earlier snapshot and is supported by nothing in the current one. |
#No longer confirmed
The outcome that does not exist in any document, and the one that justifies keeping the picture rather than rewriting it.
A written architecture page has two states: current, and quietly wrong. It moves between them with no event, and nobody finds out until somebody acts on it.
A claim in a snapshot has a third state. It was believed, it had evidence, and the latest analysis does not support it. That claim is neither deleted nor left standing — it is marked as no longer confirmed, with the date it was last supported and the reason.
This is the whole argument for a kept picture over a produced one, and it is also the answer to "why is this a subscription": a one-off analysis can produce every other thing 1ADK does. Only a kept one can withdraw its own earlier statements.
#What this cannot do
What this does not do
- It cannot recover why something changed. The comparison says the retry logic moved; the reason is in a person or a ticket.
- It cannot see inside the gap. Two analyses three months apart compress everything between them into one difference — anything that appeared and disappeared in that window is invisible.
- It cannot fix a careless identifier. An analysis that supplies unstable external identifiers produces an unstable history, and the server cannot tell the difference.
- It cannot compare across different systems. A snapshot belongs to one project store and there is no cross-project query in the product.
- It says nothing about quality. Change is reported, not judged.