Semantic Diff Review¶
Change-review assessment — instantiates Carrier-Independent Work Identity Governance
Judges whether a change altered what the work MEANS — its function, its commitments, its recognizable identity — rather than only how it looks.
A Semantic Diff Review compares two versions of a work and asks whether the difference between them is semantic — a change in meaning, function, or commitment — or merely surface. Its distinguishing move is depth on a single dimension: where a preservation checklist screens broadly, this goes deep on meaning and quantifies the delta against a budget, so "how much has actually changed" gets a measured answer rather than a gut feel. A textual diff shows which bytes moved; a semantic diff shows whether the work now does or claims something different.
Example¶
A team maintains a widely used software library and proposes a change: a function that used to return null for "not found" now throws an exception. The line-level diff is tiny — a few lines. The Semantic Diff Review asks the question the textual diff can't: does this change what callers can rely on? It runs the change against an equivalence test set — a battery of caller-contracts encoding the library's promises — and finds that existing callers who tested for null will now crash. That is a semantic change: the observable contract moved even though the surface barely did. Under Semantic Versioning[n1], that verdict forces a major-version bump, not a patch — the review's output is not "3 lines changed" but "the meaning changed; this is a breaking change." The flip side matters too: a 400-line internal refactor that leaves every caller-contract green is scored as no semantic change at all — same work, new form.
How it works¶
- Diff at the level of meaning — compare declared behavior, function, and commitments between versions, not just tokens or bytes.
- Run the equivalence test set — evaluate the change against a curated battery of behaviors and contracts that define "same work"; a green run is evidence of equivalence, a red one localizes the semantic break.
- Score against the budget — express the delta as how much of the semantic-change budget it consumes, so a small clarification and an identity-breaking change aren't treated alike.
- Classify, don't just flag — output a category (surface-only / within-budget semantic change / budget-breaking change) that downstream rules can act on.
Tuning parameters¶
- Semantic granularity — how fine the notion of "meaning" is (public contract only, or every observable behavior). Finer catches subtle breaks but flags more — every observable behavior eventually becomes something someone depends on.[n2]
- Test-set coverage — how complete the equivalence battery is; its gaps are exactly where silent semantic breaks slip through.
- Budget size — how much meaning-change is allowed before identity is deemed broken. Tight budgets protect stability; loose ones permit evolution.
- Human versus automated — automated contract tests scale; human judgment catches meaning no test encodes (tone, intent, normative force).
- Directionality — whether removals, additions, and behavior-changes weigh the same; a breaking removal usually costs more than a compatible addition.
When it helps, and when it misleads¶
Its strength is that it separates the two things a plain diff conflates — cosmetic change and change of meaning — and gives the fork-or-supersede decision a measured input instead of an argument. It is what stops a "small" change from silently breaking the contract, and what clears a large refactor that changed nothing that matters.
Its failure modes track its blind spots. It can only test the meanings someone encoded; unencoded meaning — tone, implied intent, an undocumented behavior a whole ecosystem quietly relies on (Hyrum's Law[n2]) — escapes and is scored "no change." An incomplete test set yields false equivalence, the most dangerous output because it certifies a sameness that isn't there. And it is readily run backwards: pick the test set under which a desired change scores "surface-only." The discipline is to grow the equivalence set from real breakages, treat a green result as evidence rather than proof, and keep the person who wants the change from being the sole author of the tests it must pass.
How it implements the components¶
instance_equivalence_test_set— the curated battery of behaviors and contracts against which two instances are judged the same or different; the engine of the review.semantic_change_budget— it measures the meaning-delta and reports how much of the allowed budget the change spends.
It measures the semantic delta but does not run the broad preservation screen across authorship, obligations, and structure — that is Identity Preservation Checklist — nor decide when the delta forks a new work, which is the Fork Decision Record.
Related¶
- Instantiates: Carrier-Independent Work Identity Governance — supplies the measured "did the meaning change?" input the rest of the governance hangs decisions on.
- Consumes: Work–Expression–Manifestation Matrix to diff at the correct level (expression versus manifestation).
- Sibling mechanisms: Identity Preservation Checklist · Work–Expression–Manifestation Matrix · Fork Decision Record · Governed Translation or Adaptation Review · Version Lineage Graph
Editorial Notes¶
Form Classification¶
Form family: Assessment, Review & Assurance
Rationale: Semantic Diff Review operates as a bounded evaluation of existing evidence or work that produces a finding or disposition because it judges whether a change altered what the work MEANS — its function, its commitments, its recognizable identity — rather than only how it looks.
Independent corroboration: The frozen evidence defines Semantic Diff Review as 'Judges whether a change altered what the work MEANS — its function, its commitments, its recognizable identity — rather than only how it looks', so its operative form is Assessment, Review & Assurance.
Review outcome: Independent reviewer agreement; high confidence.
Origin Attribution¶
Primary origin: Computer Science & Software Engineering
Origin pattern: Cross-disciplinary synthesis
Present-day reach: Multi-domain
Rationale: Computing and reviewing meaning-relevant changes between machine-readable versions is semantic-web and software versioning practice. W3C's semantic diff design note treats RDF changes at the graph/meaning level; linguistics and information science support interpretation and vocabulary stewardship.
Related originating lineages:
- Engineering & Design — Configuration review evaluates whether a change alters required function rather than appearance alone.
- Human-Computer Interaction — human_computer_interaction contributes human interpretation, interface design, usability, and decision display to this mechanism's defining operation—Judges whether a change altered what the work MEANS — its function, its commitments, its recognizable identity — rather than only how it looks—without displacing the selected primary historical lineage.
- Library & Information Science — library_information_science contributes retrieval, classification, metadata, findability, and durable stewardship to this mechanism's defining operation—Judges whether a change altered what the work MEANS — its function, its commitments, its recognizable identity — rather than only how it looks—without displacing the selected primary historical lineage.
- Linguistics & Semiotics — Semantic analysis distinguishes changes in meaning from changes in surface form.
- Literature & Literary Theory — Interpretive comparison asks whether identity, commitment, and function survive revision.
Review resolution: The blind reviewers disagree on primary lineage (computer_science versus linguistics_semiotics). Authoritative or primary research supports computer_science as the best historical origin: Computing and reviewing meaning-relevant changes between machine-readable versions is semantic-web and software versioning practice. W3C's semantic diff design note treats RDF changes at the graph/meaning level; linguistics and information science support interpretation and vocabulary stewardship. The cited W3C, Semantic Web Change/Diff Design Note directly supports the mechanism's defining operation. All independently supported contributing domains are retained without an arbitrary cap. origin_mode=cross_disciplinary_synthesis records the lineage relationship, while domain_reach=multi_domain records later applicability separately from provenance.
Encyclopedia synthesis: The exact catalogued form synthesizes established practice rather than reproducing a single standard historical label.
Review outcome: Researched adjudication after independent review; high confidence.
Sources consulted:
Notes¶
"Surface versus semantic" is itself level-relative: a change that is surface at the manifestation level (new typesetting) can be semantic at the expression level (a re-translation). A semantic diff is only meaningful once the level is fixed — which is why it consumes the Work–Expression–Manifestation Matrix rather than judging "meaning" in the abstract.
[n1] Semantic Versioning (SemVer) — a widely used convention in which a version number's major/minor/patch components signal the kind of change: a major bump denotes a backward-incompatible (semantic) change to the public contract, minor an additive one, patch a fix. It ties an identity judgment ("did the contract change?") directly to how the thing is named and cited. ↩
[n2] Hyrum's Law — the observation (an aphorism attributed to software engineer Hyrum Wright) that with enough users, every observable behavior of a system will come to be depended upon by someone, regardless of what was promised. It is why a semantic diff limited to the documented contract can still miss real breakage. ↩a ↩b