chore: auto-commit (97 archivos)

- .claude/CLAUDE.md
- .claude/agents/fn-recopilador/SKILL.md
- .claude/rules/INDEX.md
- .claude/rules/cpp_apps.md
- bash/functions/infra/build_cpp_windows.sh
- cpp/CMakeLists.txt
- cpp/PATTERNS.md
- cpp/framework/app_base.cpp
- cpp/framework/app_base.h
- dev/issues/README.md
- ...

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

functions/core/golden_diff.go

@@ -0,0 +1,32 @@
+package core
+
+// GoldenDiff compares two byte slices and returns a similarity score in [0,1].
+// similarity = matchedBytes / max(len(actual), len(golden)).
+// matched = similarity >= (1.0 - threshold).
+// threshold=0.0 requires exact match; threshold=0.05 tolerates up to 5% divergence.
+// Returns similarity=1.0 and matched=true when both slices are empty.
+func GoldenDiff(actual, golden []byte, threshold float64) (matched bool, similarity float64) {
+	maxLen := len(actual)
+	if len(golden) > maxLen {
+		maxLen = len(golden)
+	}
+	if maxLen == 0 {
+		return true, 1.0
+	}
+
+	minLen := len(actual)
+	if len(golden) < minLen {
+		minLen = len(golden)
+	}
+
+	var matchedBytes int
+	for i := 0; i < minLen; i++ {
+		if actual[i] == golden[i] {
+			matchedBytes++
+		}
+	}
+
+	similarity = float64(matchedBytes) / float64(maxLen)
+	matched = similarity >= (1.0 - threshold)
+	return matched, similarity
+}

functions/core/golden_diff.md

@@ -0,0 +1,52 @@
+---
+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.

functions/core/golden_diff_test.go

@@ -0,0 +1,58 @@
+package core
+
+import (
+	"math"
+	"testing"
+)
+
+func TestGoldenDiff(t *testing.T) {
+	t.Run("identicos retorna similarity 1 y matched true", func(t *testing.T) {
+		matched, sim := GoldenDiff([]byte("hello"), []byte("hello"), 0.0)
+		if !matched {
+			t.Errorf("expected matched=true")
+		}
+		if math.Abs(sim-1.0) > 1e-9 {
+			t.Errorf("expected similarity=1.0, got %v", sim)
+		}
+	})
+
+	t.Run("totalmente distintos retorna similarity 0 y matched false", func(t *testing.T) {
+		matched, sim := GoldenDiff([]byte("aaaaa"), []byte("bbbbb"), 0.0)
+		if matched {
+			t.Errorf("expected matched=false")
+		}
+		if math.Abs(sim-0.0) > 1e-9 {
+			t.Errorf("expected similarity=0.0, got %v", sim)
+		}
+	})
+
+	t.Run("1 byte distinto threshold 0 falla pero threshold 0.5 pasa", func(t *testing.T) {
+		// "hellx" vs "hello": 4 de 5 bytes coinciden -> similarity = 0.8
+		actual := []byte("hellx")
+		golden := []byte("hello")
+
+		matchedStrict, simStrict := GoldenDiff(actual, golden, 0.0)
+		if matchedStrict {
+			t.Errorf("threshold=0.0: expected matched=false with 1 byte difference")
+		}
+		if math.Abs(simStrict-0.8) > 1e-9 {
+			t.Errorf("threshold=0.0: expected similarity=0.8, got %v", simStrict)
+		}
+
+		matchedLoose, _ := GoldenDiff(actual, golden, 0.5)
+		if !matchedLoose {
+			t.Errorf("threshold=0.5: expected matched=true with similarity=0.8")
+		}
+	})
+
+	t.Run("longitudes distintas usa max como denominador", func(t *testing.T) {
+		// "ab" vs "abcde": 2 de 5 bytes coinciden -> similarity = 0.4
+		matched, sim := GoldenDiff([]byte("ab"), []byte("abcde"), 0.0)
+		if matched {
+			t.Errorf("expected matched=false")
+		}
+		if math.Abs(sim-0.4) > 1e-9 {
+			t.Errorf("expected similarity=0.4, got %v", sim)
+		}
+	})
+}