Tabla D1: bib_cochanges — Registro de pares de archivos co-cambiados

Descripción

Tabla D1 (Cloudflare) que registra pares de archivos que cambian juntos en el repositorio, alimentando la señal de co-cambio de bib_impact_query.

Creada en migración 0043 (PR#100, cherry-pick Cairn #2).

Schema

CREATE TABLE bib_cochanges (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    repo TEXT NOT NULL DEFAULT 'CreaRack-Pro',
    file_a TEXT NOT NULL,
    file_b TEXT NOT NULL,
    count INTEGER NOT NULL DEFAULT 1,
    last_seen TEXT NOT NULL DEFAULT (datetime('now')),
    UNIQUE (repo, file_a, file_b)
);

CREATE INDEX idx_bib_cochanges_file_a ON bib_cochanges(file_a);
CREATE INDEX idx_bib_cochanges_file_b ON bib_cochanges(file_b);

Columnas

Índices y constraints

• Primary key: id.
• Unique constraint: (repo, file_a, file_b) — cada pareja dentro de un repo tiene una sola fila.
• Índices: file_a y file_b separados para búsquedas rápidas (una consulta hace WHERE file_a = ? OR file_b = ?).

Populating

Backfill (one-shot)

Invocado manualmente desde CreaRack-Pro/scripts/bib_cochange_backfill.py:

• Lee el historial git completo (commits/merges históricos).
• Extrae pares de archivos co-cambiados.
• Agrupa y cuenta.
• Invoca bib_record_cochanges con modo pairs.

Resultado esperado: ~1500+ pares con count ≥ 2 (acoplamiento real documentado múltiples veces).

Post-merge ingest (continuo)

En .github/scripts/bib_ingest.py, función record_cochanges():

• Se ejecuta en cada merge, incondicional.
• Extrae archivos de código tocados.
• Llama a bib_record_cochanges con modo files.
• UPSERT incrementa count y actualiza last_seen.

Consultas

Cochanges de un archivo específico

SELECT 
    CASE WHEN file_a = ? THEN file_b ELSE file_a END AS cochange_file,
    count,
    last_seen
FROM bib_cochanges
WHERE (file_a = ? OR file_b = ?) AND count >= ?
ORDER BY count DESC, last_seen DESC
LIMIT 15;

Parámetros: file_path, file_path, file_path, min_count (default 2).

Esta es la consulta que usa bib_impact_query cuando se pasa file_path.

Criterios de inclusión / exclusión

Los archivos registrados son solo de código (para mantener la señal limpia):

Incluidos:

• .py, .ts, .tsx, .js, .jsx, .mjs, .cjs, .astro, .vue, .html, .css, .scss, .sql

Excluidos:

• .md (README, CHANGELOG, CLAUDE, RELEASE_NOTES: churn ruido)
• .github/scripts/bib_* (herramientas ingest)
• scripts/harness/ (test harness)
• public/supercontext/ (assets generados)
• src/content/wiki/ (wikis — update checklist, no co-cambios de código)
• config/settings/base.py (denylist: cambia en cada release por versionado)

Anti-ruido

Topes:

• MAX_FILES = 25: refactors que tocan >25 archivos en un merge se descartan (refactor masivo = ruido).
• MAX_PAIRS = 1000: una llamada de UPSERT no procesa >1000 pares (el backfill los trocea).

Resultado: señal limpia, acoplamiento real documentado (típicamente count ≥ 2 indica genuina co-evolución).

Integridad

• Idempotencia: si un merge se reintentan, UPSERT es seguro (solo suma).
• Degradación: si la tabla no existe (migración no aplicada), bib_impact_query devuelve cochanged_files: [] sin error.
• Transaccional: db.batch() garantiza atomicidad de múltiples INSERTs/UPDATEs en un round-trip D1.

Mantenimiento

Limpieza (si es necesario)

Borrar pares antiguos o con count muy bajo:

DELETE FROM bib_cochanges
WHERE last_seen < datetime('now', '-1 year')
   OR count < 2;

(Actualmente sin limpieza automática; la tabla es append-only + UPSERT.)

Estadísticas

SELECT 
    COUNT(*) AS total_pairs,
    AVG(count) AS avg_frequency,
    MAX(count) AS max_frequency,
    COUNT(DISTINCT repo) AS repos
FROM bib_cochanges;

Backfill esperado: ~1561 pares con count ≥ 2.

Véase también

• [[entity—functions—service—bib-record-cochanges]]
• [[entity—functions—tool—bib-impact-query]]
• [[feature—biblioteca—cairn-cochanges]]
• [[concept—biblioteca—grafo-estatico-vs-empirico]]
• [[entity—functions—database—bib-edges]]