---
name: golden_diff
kind: function
lang: go
domain: core
version: "1.0.0"
purity: pure
signature: "func GoldenDiff(actual, golden []byte, threshold float64) (matched bool, similarity float64)"
description: "Compara dos buffers byte-a-byte y retorna una puntuacion de similitud en [0,1]. similarity = matchedBytes / max(len(actual), len(golden)). matched = similarity >= (1.0 - threshold). threshold=0.0 exige match exacto; threshold=0.05 tolera hasta 5% de divergencia."
tags: [diff, golden, testing, similarity, bytes, comparison]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: ""
imports: []
tested: true
tests:
  - "identicos retorna similarity 1 y matched true"
  - "totalmente distintos retorna similarity 0 y matched false"
  - "1 byte distinto threshold 0 falla pero threshold 0.5 pasa"
  - "longitudes distintas usa max como denominador"
test_file_path: "functions/core/golden_diff_test.go"
file_path: "functions/core/golden_diff.go"
params:
  - name: actual
    desc: "Buffer de bytes producido por el sistema bajo prueba."
  - name: golden
    desc: "Buffer de bytes de referencia (golden file o snapshot esperado)."
  - name: threshold
    desc: "Fraccion de divergencia tolerable en [0,1]. 0.0 = match exacto, 0.05 = hasta 5% diferente."
output: "matched indica si la similitud supera el umbral. similarity es la fraccion de bytes que coinciden respecto al mayor de los dos buffers."
---

## Ejemplo

```go
actual := []byte("hello world")
golden := []byte("hello world")
matched, sim := GoldenDiff(actual, golden, 0.0)
// matched=true, sim=1.0

actual2 := []byte("hello wrold")  // typo
matched2, sim2 := GoldenDiff(actual2, golden, 0.05)
// sim2 = 9/11 ≈ 0.818, matched2=true (dentro del 5% de tolerancia)
```

## Notas

Funcion pura, sin I/O. Usa comparacion posicional byte-a-byte: dos buffers del mismo contenido pero con bytes insertados/eliminados en el centro daran una similitud baja aunque el contenido sea logicamente similar. Para comparaciones de texto estructurado (JSON, YAML) considerar normalizar antes de llamar a GoldenDiff.

El denominador es `max(len(actual), len(golden))`, lo que penaliza diferencias de longitud ademas de diferencias de contenido.
