fn_registry/dev/issues/completed/0062-deprecate-unused-core-functions.md

0062 — Politica de deprecacion para funciones del registry sin consumidores

APP Metadata

Campo	Valor
ID	0062
Estado	resuelto 2026-05-13
Prioridad	baja
Tipo	research + policy — .claude/rules/, docs/

Resolucion (2026-05-13)

Decision: opcion 2 (deprecar via tag) — NO se borra, NO se mantiene en limbo. Se marca con pendiente-usar para hacer visible "disponible, sin consumidor todavia".

Implementacion: pipeline tag_unused_pending_py_pipelines (Python). Cruza fn doctor unused --json con registry.db.functions.file_path y modifica el frontmatter YAML del .md de cada funcion. Idempotente — re-ejecutar:

• Anade el tag a funciones nuevas en la lista de unused.
• Retira el tag de funciones que han adquirido un consumer real (mantener coherencia).

Comando: python/.venv/bin/python3 python/functions/pipelines/tag_unused_pending.py && ./fn index.

Filtro: mcp__registry__fn_search 'tags:"pendiente-usar"' o sqlite3 registry.db "SELECT id FROM functions WHERE tags LIKE '%pendiente-usar%'".

Estado actual: 631 funciones marcadas pendiente-usar (de 1249 totales). El tag persiste mientras fn doctor unused las liste; desaparece cuando alguna app/funcion las declare en uses_functions.

Dependencias

• find_unused_functions_go_infra (existe, lista 704 funciones sin consumidores al 2026-05-07).
• fn doctor unused.

Contexto

Sesion 2026-05-07: el registry tiene 1066 funciones. fn doctor unused reporta 704 sin consumidores (66%). La mayoria son utilities core puras (compose2_go_core, curry2_go_core, chunk_go_core, flat_map_slice_go_core, etc.) construidas especulativamente — esperando que alguna app las consuma.

Sin politica explicita de "que hacer con unused", el registry crece sin freno. Posibles destinos:

1. Mantener indefinidamente (libreria publica disponible).
2. Deprecar via tag (tags: [deprecated]) — sigue presente pero senala "no usar para codigo nuevo".
3. Borrar despues de N meses sin consumidor.

Decision pospuesta: cualquier eleccion afecta cientos de archivos y la velocidad de scaffold de nuevas apps que pueden recogerlas.

Objetivo

Definir y documentar una politica formal:

1. Criterios cuantitativos: cuanto tiempo (en dias) sin consumidor justifica deprecar.
2. Excepciones: funciones con tag core-utility o library-quality se mantienen.
3. Workflow de deprecacion: tag → 90 dias → borrar.
4. Hook automatico: fn doctor unused --propose-deprecation abre proposals.

Arquitectura

Archivos afectados

• NUEVA regla .claude/rules/unused_functions.md.
• NUEVO ADR docs/adr/0005-unused-functions-policy.md.
• find_unused_functions_go_infra — opcionalmente extender con AgeDays desde updated_at (ya lo tiene) y filtrar por edad.
• cmd/fn/doctor.go — anadir flag --older-than <days> al subcomando unused.

Tareas

Fase 1 — definir politica (humano)

1.1 Decidir umbrales: tag deprecated tras 60 dias sin consumidor; borrar tras 180 dias. 1.2 Decidir excepciones: tag core-utility exime, tag library-quality exime, dominios core puros mas tolerantes que dominios infra. 1.3 Decidir si la deprecacion es manual (humano via proposal) o automatica (cron).

Fase 2 — escribir ADR + regla

2.1 ADR 0005 con la decision, alternativas, consecuencias. 2.2 Regla .claude/rules/unused_functions.md operacional. 2.3 Update INDEX.md.

Fase 3 — extender herramienta

3.1 fn doctor unused --older-than 60 filtra por edad. 3.2 fn doctor unused --propose-deprecation crea proposals automaticas con kind=deprecate_function. 3.3 Workflow humano: revisar proposals, aprobar, agente aplica el tag.

Fase 4 — primera ronda

4.1 Correr fn doctor unused --older-than 90. 4.2 Decidir caso por caso (o lote por dominio): mantener / deprecar / borrar. 4.3 Aplicar tags. Re-indexar. Update CHANGELOG.

Riesgos

• Borrar funciones que el usuario planeaba usar pronto. Mitigacion: ventana larga (180 dias) + proposal manual antes de borrar.
• Tags desfasados: una funcion deprecated puede seguir siendo usada. Mitigacion: el indexer puede warn si una app declara una deprecated en uses_functions.
• Deprecation como excusa para no usar (cosmica). Mitigacion: revisiones trimestrales, no que se acumule.

Decisiones de diseno

• NO borrar nunca automaticamente. Borrado siempre humano via PR/proposal aprobada.
• Tag deprecated es el verbo automatizable: un agente puede aplicarlo via proposal.
• Para funciones nuevas creadas tras adoptar la politica, exigir que tengan al menos UN consumidor previsto al merge — sino van directo con tag experimental.