Same words, different support
Consider a paragraph in a report. Its text is unchanged between two versions. A content hash of that paragraph is unchanged too.
Now change the source material underneath it. The paragraph still says the same thing. The evidence it rests on does not.
That is a document change. A text-only diff cannot name it.
Documents with citations need a way to represent this case. Otherwise a review screen can report “no changes” while the support for a claim has moved, been replaced, or become stale.
Blocks need identity
Doculate stores documents as blocks. A block is not identified only by its current text. It carries an identity of its own, one that survives the text being rewritten.
That identity lets a version compare the same logical block with its later form. The text can be rewritten. The block can move. Its source references can change. Those are different operations on the same item.
Without stable identity, comparison has to guess from position or content. Position breaks when blocks are reordered. Content breaks when a block is rewritten. A repeated heading can make either method ambiguous.
Identity gives the diff a subject. The other fields describe what happened to that subject.
Versions form a graph
A document is not a pile of unrelated exports. Versions and branches form a history you can walk. A version records a state of the document. A branch records a line of work that can move from one version to the next.
That structure matters when an edition starts from a trusted checkpoint. The new work has a parent. It does not need to pretend that it is a new document with no history.
The graph also gives a diff a defined comparison. The system can compare one version with another version in the same lineage, including a branch that has been tailored from an earlier state.
The comparison is computed per block. This keeps a change attached to the logical unit that carries the claim and its evidence.
Five different kinds of change
It is worth naming the kinds of change a paragraph-level text comparison tends to collapse together:
- Added: a block exists in the later version and not the earlier one
- Removed: a block exists in the earlier version and not the later one
- Rewritten: the words changed
- Reordered: the block moved while its content stayed the same
- Support changed: the words are identical and the evidence under them is not
The last type is the important one here. It treats evidence as part of the document state.
| Change | Words differ | Visible to a text comparison |
|---|---|---|
| Added or removed | Yes | Yes |
| Rewritten | Yes | Yes |
| Reordered | No | Only as a deletion plus an addition |
| Support changed | No | No |
A reordered block is also worth separating from a rewrite. The words may be identical. Their position in the document can affect how a reader understands them. A source change has a different cause again. The block is in the same place with the same bytes, but its support must be reviewed.
Why hashing is not enough
Hashing is useful for detecting content changes. It answers a narrow question: did these bytes change?
It does not answer: did the references used to support these bytes change?
If a block contains text plus source references, there are several possible hashes. A text hash sees only the text. A larger snapshot hash could include the references, but it would still need a way to explain the difference. A changed hash would say that something changed. It would not say whether the block was rewritten, moved, or left untouched while its evidence changed.
The semantic diff supplies that explanation. It compares the block identity, text, position, and source state, then emits a change type that a reviewer can act on.
This is a design choice about meaning. The question is not only whether two serialised objects differ. It is which part of a document’s meaning has changed.
Evidence can age independently
A claim can remain legible after its source has changed. That is why text equality cannot stand in for support equality.
The change may come from a new source revision, a different extraction, or a changed source binding. The exact cause belongs in the version data and its review trail. The important point is that the cited material is part of the block’s state.
This also explains why a citation carries more than the words on screen. Enough is recorded for a later version to identify exactly which material it relied on. A review can then ask whether the claim still has the intended basis.
A diff should tell you what to inspect
A changed-support marker does not declare the claim false. It says a dependency moved. The next action is review, by a person.
That distinction keeps the version system honest. It does not infer a conclusion from a changed reference. It exposes the change so a person or a later validation step can decide what it means.
For an evidence-backed document, “the text is the same” is only one part of the answer. The evidence underneath the text belongs in the version history too.