Source: https://guthlabs.ai/docs/instruments/binary-text-diff-similarity-ratio/mechanism/

instrument mechanism / verified-clean

# Binary/Text Diff & Similarity Ratio mechanism

The inspectable method record for Binary/Text Diff & Similarity Ratio, kept separate from implementation and qualification.

Status: **VERIFIED_CLEAN**Lifecycle: **verified-clean**

## Model scope

The Levenshtein formula is standard only after defining the distance metric, length unit, percentage conversion, and empty-input behavior. The specification is NEEDS_REVIEW because the selectable LCS variant and the diff-generation rules are materially ambiguous.

- The edit_distance metric is not explicitly defined; the formula requires standard Levenshtein distance if that is intended.

- The formula returns a ratio from 0 to 1, while the stated output is similarity percent; the implementation must multiply by 100 for percent output.

- The LCS-based ratio variant has no formula. Common definitions include LCS/max(len1,len2) and 2*LCS/(len1+len2), which produce different results.

- The length unit is unspecified: character count, Unicode code-point count, UTF-16 code-unit count, byte count, and grapheme-cluster count can differ.

- The formula does not define how inline or line-level diff highlighting is generated, including edit-script tie-breaking and newline handling.

- The formula is not defined for two empty inputs because max(len1,len2) is zero.

## Units and conventions

- Test vectors assume standard character-level Levenshtein distance with insertion, deletion, and substitution each costing 1.

- len1 and len2 are assumed to be counts of Unicode characters/code points, not bytes or UTF-16 code units.

- The similarity ratio is assumed to be converted to a percentage by multiplying by 100.

- The displayed inline diff uses a canonical minimal edit script; exact highlighting may vary unless tie-breaking is specified.

- For the LCS variant, no unit assumption can resolve the missing ratio definition.

## Inspectable vector

One of 4 source-bound review vectors:

````
{
  "inputs": {
    "text1": "cat",
    "text2": "cat"
  },
  "expected_outputs": {
    "edit_distance": 0,
    "similarity_percent": 100,
    "inline_diff": [
      {
        "op": "equal",
        "text": "cat"
      }
    ]
  },
  "working": "len1=3, len2=3; max(3,3)=3. Levenshtein distance=0 because the strings are identical. similarity=1-0/3=1. percent=1*100=100%. Diff: all 3 characters are equal."
}
````

## Failure boundary

**BREAK_CLAIMED** · SELF_FLAGGED

The specified formula is undefined for two empty text blocks because max(len1,len2)=0, causing division by zero. The result is also convention-sensitive because case handling is unspecified, and the available LCS-based ratio can produce a different score from the Levenshtein formula.

## Other records

[01**Overview**](<https://guthlabs.ai/docs/instruments/binary-text-diff-similarity-ratio/>)[03**Implementation**](<https://guthlabs.ai/docs/instruments/binary-text-diff-similarity-ratio/implementation/>)[04**Qualification**](<https://guthlabs.ai/docs/instruments/binary-text-diff-similarity-ratio/qualification/>)

## Sources and evidence

These pointers bind the page to evidence. They do not grant authority or collapse verification into deployment.

- `VERIFIED_LEDGER.json`

- `evidence-tranche5/tranche5-results.json`

- `BOUNDARY_HAZARD_CATALOG.json`