Tabla D1 deps_freshness — snapshot de frescura de dependencias

Propósito

Tabla de datos centralizada que almacena el estado actual (snapshot) de frescura de las dependencias de CreaRack-Pro y CreaRackSL-workspace: versión pineada, instalada y última disponible en PyPI/npm, el desfase semver, los avisos de seguridad OSV.dev y — desde el “motor fiable” (task #275) — de dónde sale realmente la versión “en uso”, si la horquilla del manifiesto pone techo, y si la fila está retenida a propósito.

No es histórica: cada POST /api/tools/deps borra el snapshot anterior y publica uno nuevo. Sirve para responder “¿qué hay viejo hoy, y es de fiar el dato?” en la tool /tools/deps.

Migraciones

wrangler d1 execute crearacksl-workspace-db --remote --file=./migrations/<archivo>.sql

Schema (estado actual, tras 0042 + 0048 + 0052 + 0053)

CREATE TABLE deps_freshness (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    repo TEXT NOT NULL,                             -- 'crearack-pro' | 'workspace'
    ecosystem TEXT NOT NULL,                        -- 'pypi' | 'npm'
    manifest TEXT NOT NULL,                         -- manifiesto ganador tras deduplicar (el más restrictivo)
    package TEXT NOT NULL,
    pinned TEXT,
    installed TEXT,
    latest TEXT,
    lag_kind TEXT NOT NULL DEFAULT 'unknown' CHECK (lag_kind IN (
        'major', 'minor', 'patch', 'uptodate', 'unknown'
    )),
    is_dev INTEGER NOT NULL DEFAULT 0,
    checked_at TEXT NOT NULL DEFAULT (datetime('now')),
    -- 0048 — eje de seguridad OSV.dev
    vuln_count INTEGER NOT NULL DEFAULT 0,
    vuln_ids TEXT,                                  -- ids OSV separados por coma (GHSA-..., PYSEC-...)
    vuln_severity TEXT,                             -- peor severidad: critical|high|moderate|low|unknown
    -- 0052 — motor fiable (task #275)
    manifests TEXT,                                 -- TODOS los manifiestos donde aparece el paquete, separados por coma
    resolved TEXT,                                  -- mayor versión que la horquilla `pinned` admite hoy
    installed_source TEXT,                          -- 'prod' | 'runner' | 'lockfile' — de dónde sale `installed`
    unbounded INTEGER NOT NULL DEFAULT 0,            -- 1 = la horquilla no pone techo superior
    unbounded_major INTEGER NOT NULL DEFAULT 0,      -- 1 = sin techo Y ya corre en major distinto al declarado
    fix_within_spec INTEGER,                         -- tri-estado: 1 basta redeploy · 0 cambiar pin · NULL sin fix publicado
    -- 0053 — retenciones deliberadas (task #275)
    hold_reason TEXT,                                -- por qué NO se actualiza, en llano. No nulo = fila retenida
    hold_since TEXT,                                 -- desde cuándo (YYYY-MM-DD; el handler descarta otro formato)
    hold_ref TEXT,                                   -- dónde vive la decisión ("task #204 · redis-py #2807")
    hold_until TEXT                                  -- cuándo revisarla (fecha o condición, texto libre)
);

CREATE INDEX idx_deps_freshness_lag ON deps_freshness(lag_kind);
CREATE INDEX idx_deps_freshness_repo ON deps_freshness(repo, ecosystem);

installed_source no lleva CHECK (SQLite/D1 no lo valida de forma fiable en un ADD COLUMN): el enum 'prod' | 'runner' | 'lockfile' se filtra en el handler (functions/api/tools/deps/index.ts), no en el schema.

Columnas detalladas

Índices

• idx_deps_freshness_lag: sobre (lag_kind).
• idx_deps_freshness_repo: sobre (repo, ecosystem).

Semántica

pinned vs. resolved vs. installed vs. latest

• pinned: especificación declarada en el manifiesto, sin resolver ("^1.5.0").
• resolved: mayor versión que esa horquilla admite hoy, calculada por el colector — lo que se instalaría en un despliegue limpio.
• installed: versión que de verdad corre, según installed_source (PROD real, runner de CI, o lockfile).
• latest: última disponible en el registro oficial, sin filtrar por la horquilla.

Cuando resolved e installed difieren, la UI muestra la línea “Se instalaría” en la ficha del paquete.

installed_source

Antes del motor fiable, “instalada” era siempre lo que resolvía el runner de CI (un entorno limpio, sin relación con lo que corre en PROD). Ahora el colector intenta primero GET /api/installed-packages en PROD ([[entity—api—endpoint—installed-packages]]); si no responde, cae a runner; si tampoco, a lockfile.

hold_reason y el resto de hold_*

Una fila con hold_reason no nulo está retenida a propósito: alguien decidió no subirla y dejó escrito el motivo. scripts/deps_holds.py (CreaRack-Pro) cruza el catálogo deps_holds.json contra las filas del colector y rellena estos cuatro campos antes del POST. El desfase (lag_kind) se sigue calculando igual, pero la fila no suma en los contadores major/minor del resumen ni en la cifra roja de la tarjeta de /tools — cuenta aparte como «retenida a propósito». DepsBadges.tsx la pinta en ámbar en vez de rojo/naranja.

Consumidores

• GET /api/tools/deps ([[entity—functions—endpoint—tools-deps]]): lee, ordena (avisos de seguridad primero, luego lag_kind), devuelve a la UI.
• DepsPanel.tsx / DepsBadges.tsx: filtran, buscan, renderizan tabla con badges (fuente PROD/CI/lock, “Sin techo”, “basta redeploy”/“cambiar pin”, “en N manifiestos”, “Retenida a propósito”).

Ciclo de vida

1. Creación: migración 0042 (2026-05-28).
2. Ampliaciones: 0048 (2026-07-11, seguridad OSV), 0052 (2026-08-28, motor fiable) y 0053 (2026-08-28, retenciones) — todas ALTER TABLE ADD COLUMN, sin migrar filas existentes (payloads viejos entran con las columnas nuevas a NULL/0).
3. Actualización: POST /api/tools/deps (semanal vía GitHub Actions, o a mano). DELETE → INSERT batch, snapshot atómico sin histórico.
4. Lectura: GET /api/tools/deps (navegador, miles de veces).

Tamaño estimado

• Esperado: ~50–150 dependencias (entre ambos repos).
• Crecimiento: cero (snapshot, no histórico).

Véase también

• [[entity—functions—endpoint—tools-deps]]
• [[feature—workspace—tool-dependencias]]
• [[runbook—workspace-tech—tool-dependencias]]
• [[entity—api—endpoint—installed-packages]]
• [[feature—harness—osv-security-deps-freshness]]