feat(nexxa): NEXXA versionada en dtic-DIIAA (1.3.0): pools por individuo mente/red, API por rol y gestión desde nexxa-web
Tests ADN / test (push) Canceled after 0s

- Base: código de producción de srvv-nexxa (1.2.1), importado y verificado por hash (P335/F3)
- Pools por individuo (lib_pools): mente y red, mezclan proveedores, keys compartidas o exclusivas
- API: /disponible/mente|red y /estado por rol, pool_vacio explícito, /pools (CRUD admin), liberar admin
- Revertir el agotada propio + motivo y quién la agotó (de P334/F4)
- nexxa-web: sección Pools, motivo y botón Liberar, provider libre con sugerencias, escape de texto externo
- Convención REG002: lib_*, cli_*, tool_humo_pool; contratos externos con su nombre
- Suite local sobre copia aislada: humo HTTP, pools, revertir; servidor_prueba para mirar la web

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Co-Authored-By: GEMMA <noreply@gemma.dtic>
This commit is contained in:
Ricardo Monla
2026-10-04 16:42:13 -03:00
co-authored by Claude Opus 5.5 GEMMA
parent 50ac0d0fdf
commit a60758875d
31 changed files with 5653 additions and 0 deletions
+330
View File
@@ -0,0 +1,330 @@
# frozen_string_literal: true
# lib_registro.rb — Fuente de verdad de cuotas Y del valor real de cada key
# ==============================================================================
# NEXXA-F1 (P200, evolucionado en P201/Fase2-3 — D045 §10/§11) — registro propio,
# inspirado en apirot.rb (P121, dtic-GEMMA) pero con delta de dominio: campo
# 'provider'/'cuenta_origen' (D045 §2.3/§11) y, desde P201/Fase2, el VALOR REAL
# cifrado de cada key (D045 §10: NEXXA es la fuente de verdad, ya no candados,
# para API keys de terceros). 'identificador' es una ETIQUETA legible (ej.
# 'gemini-01'), no el secreto — el secreto vive solo en 'valor_cifrado', nunca
# en texto plano en disco ni en ningún log (ME-293/296).
#
# Dos ejes distintos, no confundir (corrección P201/Fase3, D045 §11):
# - cuenta_origen: PERMANENTE — qué cuenta ante el proveedor generó esta key.
# Informativo, nunca filtro de acceso (pool compartido, D045 §8).
# - ultimo_individuo / reservar / reportar / lib_usos.rb: EFÍMERO — qué individuo
# del ecosistema APIDs la tiene asignada ahora (o la tuvo la última vez). Una
# key se reclama y se libera — no tiene "dueño" en ese sentido.
# ==============================================================================
# NO hace: no llama a los providers externos, no valida las keys en sí — solo
# lleva el registro declarado (alta vía mini-app o cli_registrar.rb)
# ==============================================================================
# Salud real de keys (P204/Fase3, D045 §8) — el CONSUMIDOR es el árbitro del
# agotamiento, no NEXXA: solo él le pegó al proveedor real. reservar() aplica
# una reserva corta de contención al dispensar (evita doble-asignación
# concurrente, sin asumir agotamiento); reportar() recibe la señal real
# ('sana' renueva, 'liberada' suelta, 'agotada' recién ahí bloquea con
# disponible_desde). Ver registro.json: campos reservado_por/reservado_hasta.
# ==============================================================================
require 'json'
require 'time'
require_relative 'lib_cripto'
require_relative 'lib_usos'
module Nexxa
module Registro
STATE_FILE = File.expand_path('registro.json', __dir__).freeze
# Reserva corta de contención (P204/Fase3, D045 §8) — no asume agotamiento,
# solo evita que 2 consumidores reciban la misma key mientras uno la está
# probando. Vence sola (evaluada en self.disponible, sin proceso de limpieza
# aparte) si nadie reporta nada; self.reportar la renueva o la libera.
RESERVA_TTL_SEGUNDOS = 600
def self.leer
if File.exist?(STATE_FILE)
JSON.parse(File.read(STATE_FILE))
else
{ 'keys' => [] }
end
rescue JSON::ParserError
{ 'keys' => [] }
end
def self.guardar(state)
File.write(STATE_FILE, JSON.pretty_generate(state) + "\n")
end
# provider: "gemini"/"groq"/... ; identificador: ETIQUETA legible (ej. "gemini-01"),
# nunca el secreto ; cuenta_origen: cuenta ante el proveedor que generó la key —
# PERMANENTE, informativo, no filtro de acceso (D045 §8/§11) ; reset_segundos:
# ciclo de cuota del proveedor, se persiste para que marcar_uso pueda recalcular
# disponible_desde sin que el caller tenga que volver a pasarlo ; valor: el
# secreto en texto plano — se cifra acá mismo, nunca se persiste sin cifrar
# (nil = alta solo de metadata, compatibilidad con registros viejos aún no
# migrados, D045 §9→§10). ultimo_uso: nil (default) = key nueva/sin agotar,
# disponible YA — nunca se asume 'se usó ahora' (bug real encontrado en
# P200/Fase4: registrar una key recién creada la dejaba "agotada" 24h por
# error, ME-603). Pasar ultimo_uso explícito solo cuando se sabe que la key
# SÍ se agotó en ese momento.
def self.registrar(provider:, identificador:, cuenta_origen:, reset_segundos:, valor: nil, ultimo_uso: nil)
state = leer
ahora = Time.now
disponible_desde = ultimo_uso ? (Time.parse(ultimo_uso) + reset_segundos).iso8601(3) : ahora.iso8601(3)
ultimo_uso ||= ahora.iso8601(3)
valor_cifrado = valor ? cifrar(valor) : nil
existente = state['keys'].find { |k| k['provider'] == provider && k['identificador'] == identificador }
if existente
existente.merge!(
'ultimo_uso' => ultimo_uso,
'disponible_desde' => disponible_desde,
'cuenta_origen' => cuenta_origen,
'reset_segundos' => reset_segundos
)
existente['valor_cifrado'] = valor_cifrado if valor_cifrado
else
state['keys'] << {
'provider' => provider,
'identificador' => identificador,
'cuenta_origen' => cuenta_origen,
'reset_segundos' => reset_segundos,
'ultimo_uso' => ultimo_uso,
'ultimo_individuo' => nil,
'disponible_desde' => disponible_desde,
'valor_cifrado' => valor_cifrado,
'activo' => true,
'reservado_por' => nil,
'reservado_hasta' => nil
}
end
guardar(state)
state
end
# Edita metadata de una key existente (P201/Fase3) — NUNCA el valor (eso no
# se re-muestra, se reemplaza vía 'registrar' con un valor nuevo si hace
# falta rotarlo). Cada parámetro es opcional: solo se actualiza lo pasado.
def self.actualizar(provider:, identificador:, cuenta_origen: nil, reset_segundos: nil, activo: nil)
state = leer
entrada = state['keys'].find { |k| k['provider'] == provider && k['identificador'] == identificador }
raise "Key no encontrada: #{provider}/#{identificador}" unless entrada
entrada['cuenta_origen'] = cuenta_origen unless cuenta_origen.nil?
entrada['reset_segundos'] = reset_segundos unless reset_segundos.nil?
entrada['activo'] = activo unless activo.nil?
guardar(state)
entrada
end
# Elimina una key del registro — destructivo, sin deshacer (P201/Fase3).
# No borra su historial en lib_usos.rb (log append-only, queda como evidencia).
def self.eliminar(provider:, identificador:)
state = leer
existia = state['keys'].reject! { |k| k['provider'] == provider && k['identificador'] == identificador }
guardar(state) if existia
!existia.nil?
end
# Todas las keys, solo metadata — para la vista de consulta de la mini-app
# (P201/Fase3). Nunca incluye valor_cifrado, bajo ningún caso (Regla 15).
def self.todas
leer['keys'].map { |k| k.reject { |campo, _| campo == 'valor_cifrado' } }
end
# Descifra y devuelve el valor real de una key — SOLO para el endpoint HTTP
# autenticado (Fase 2/2.4). El router de apids chat (router.rb) nunca llama
# a esto — sigue devolviendo solo metadata, texto plano sin el secreto.
def self.revelar(provider:, identificador:)
entrada = leer['keys'].find { |k| k['provider'] == provider && k['identificador'] == identificador }
return nil unless entrada && entrada['valor_cifrado']
descifrar(entrada['valor_cifrado'])
end
# Reserva corta de contención al dispensar (P204/Fase3, D045 §8) — reemplaza
# el bloqueo ciego de la vieja marcar_uso: NO asume agotamiento, solo evita
# que 2 consumidores reciban la misma key mientras uno la está probando.
# disponible_desde queda intacto — el agotamiento real solo lo aplica
# self.reportar(estado: 'agotada'), con la señal del consumidor. Se llama
# automático al dispensar (server.rb, GET /disponible).
def self.reservar(provider:, identificador:, individuo:)
state = leer
entrada = state['keys'].find { |k| k['provider'] == provider && k['identificador'] == identificador }
raise "Key no encontrada: #{provider}/#{identificador}" unless entrada
ahora = Time.now
entrada['ultimo_uso'] = ahora.iso8601(3)
entrada['ultimo_individuo'] = individuo
entrada['reservado_por'] = individuo
entrada['reservado_hasta'] = (ahora + RESERVA_TTL_SEGUNDOS).iso8601(3)
guardar(state)
Nexxa::Usos.registrar(provider: provider, identificador: identificador, individuo: individuo, en: ahora, evento: 'dispensada')
entrada
end
# Reporte real del consumidor sobre una key que tiene reservada (P204/Fase3,
# D045 §8) — el consumidor es el árbitro de salud, no NEXXA (solo él le pegó
# al proveedor real). Exige reservado_por == individuo — nadie reporta el
# estado de una key que no tiene reservada.
# 'sana' → renueva la reserva (sigue activo, evita que le venza en uso)
# 'liberada' → libera la reserva ya, sin tocar disponible_desde (buen
# ciudadano que terminó antes de tiempo)
# 'agotada' → recién acá se aplica el bloqueo real: disponible_desde =
# ahora + (liberar_en_segundos si el proveedor dio una pista
# real, si no el reset_segundos registrado como fallback)
#
# P334/Fase 4 (GEMMA, 2026-10-04): quien marcó una key 'agotada' puede DESHACER su propio reporte con
# 'liberada' aunque ya no la tenga reservada (agotada_por == individuo y el bloqueo sigue vigente). Caso real
# 2026-10-01 19:46: un 429 por minuto reportado como agotada bloqueó el pool compartido y el consumidor no podía
# revertirlo (409). Solo el autor del reporte: nadie libera lo que bloqueó otro.
def self.reportar(provider:, identificador:, individuo:, estado:, liberar_en_segundos: nil, motivo: nil)
state = leer
entrada = state['keys'].find { |k| k['provider'] == provider && k['identificador'] == identificador }
raise "Key no encontrada: #{provider}/#{identificador}" unless entrada
ahora = Time.now
if estado == 'liberada' && entrada['reservado_por'] != individuo && revertible_por?(entrada, individuo, ahora)
entrada['disponible_desde'] = ahora.iso8601(3)
entrada['agotada_por'] = nil
guardar(state)
Nexxa::Usos.registrar(provider: provider, identificador: identificador, individuo: individuo, en: ahora, evento: 'revertida')
return entrada
end
raise "Key #{provider}/#{identificador} no está reservada por #{individuo}" unless entrada['reservado_por'] == individuo
case estado
when 'sana'
entrada['reservado_hasta'] = (ahora + RESERVA_TTL_SEGUNDOS).iso8601(3)
when 'liberada'
entrada['reservado_por'] = nil
entrada['reservado_hasta'] = nil
when 'agotada'
reset_segundos = entrada['reset_segundos']
raise "Key #{provider}/#{identificador} sin reset_segundos persistido — no se puede reportar agotada" unless reset_segundos
entrada['disponible_desde'] = (ahora + (liberar_en_segundos || reset_segundos)).iso8601(3)
entrada['agotada_por'] = individuo
entrada['motivo_agotada'] = motivo.to_s[0, 200] unless motivo.to_s.empty?
entrada['reservado_por'] = nil
entrada['reservado_hasta'] = nil
Nexxa::Usos.registrar(provider: provider, identificador: identificador, individuo: individuo, en: ahora, evento: 'agotada')
else
raise "estado inválido: #{estado} (esperado: sana|liberada|agotada)"
end
guardar(state)
entrada
end
# Liberación por un ADMIN desde nexxa-web (P335/Fase 7): la key queda disponible ya, sin reserva ni marca de
# agotada, sea quien sea que la bloqueó. El rastro queda en usos ('liberada-admin', con el usuario de la web).
def self.liberar_admin(provider:, identificador:, usuario:)
state = leer
entrada = state['keys'].find { |k| k['provider'] == provider && k['identificador'] == identificador }
raise "Key no encontrada: #{provider}/#{identificador}" unless entrada
ahora = Time.now
entrada['disponible_desde'] = ahora.iso8601(3) if Time.parse(entrada['disponible_desde']) > ahora
entrada['reservado_por'] = nil
entrada['reservado_hasta'] = nil
entrada['agotada_por'] = nil
entrada['motivo_agotada'] = nil
guardar(state)
Nexxa::Usos.registrar(provider: provider, identificador: identificador, individuo: "web:#{usuario}", en: ahora,
evento: 'liberada-admin')
entrada
end
# ¿individuo puede deshacer el 'agotada' de esta key? Solo si lo reportó él y el bloqueo sigue vigente.
def self.revertible_por?(entrada, individuo, ahora = Time.now)
entrada['agotada_por'] == individuo && Time.parse(entrada['disponible_desde']) > ahora
end
# Estado del pool de un provider, por key, SIN el valor (P334/Fase 4): para diagnosticar desde un consumidor sin
# entrar a la mini-app. estado: inactiva | agotada | reservada | disponible.
def self.estado_pool(provider, ahora = Time.now)
estado_de(leer['keys'].select { |k| k['provider'] == provider }, ahora)
end
# Estado de las keys de un pool (P335/Fase 5): mezcla proveedores, por eso cada fila trae su provider.
def self.estado_en(refs, ahora = Time.now)
estado_de(de_refs(refs), ahora)
end
def self.estado_de(keys, ahora = Time.now)
keys.map do |k|
estado = if k['activo'] == false then 'inactiva'
elsif Time.parse(k['disponible_desde']) > ahora then 'agotada'
elsif k['reservado_hasta'] && Time.parse(k['reservado_hasta']) > ahora then 'reservada'
else 'disponible'
end
{ 'provider' => k['provider'], 'identificador' => k['identificador'], 'estado' => estado,
'libera_en' => (estado == 'agotada' ? k['disponible_desde'] : nil),
'reservado_por' => (estado == 'reservada' ? k['reservado_por'] : nil),
'agotada_por' => (estado == 'agotada' ? k['agotada_por'] : nil),
'motivo' => (estado == 'agotada' ? k['motivo_agotada'] : nil),
'ultimo_uso' => k['ultimo_uso'], 'ultimo_individuo' => k['ultimo_individuo'] }
end
end
def self.cifrar(valor)
Nexxa::Cripto.new(Nexxa::MasterKey.cargar!).encrypt(valor)
end
def self.descifrar(valor_cifrado)
Nexxa::Cripto.new(Nexxa::MasterKey.cargar!).decrypt(valor_cifrado)
end
# Devuelve la key elegible MENOS USADA RECIENTEMENTE del provider (rotación
# del pool, P204/Fase4, propuesta del Operador) — nil si ninguna es elegible.
# Antes usaba el primer match del array: si la primera key nunca se agotaba,
# las demás no se usaban jamás y quedaban en riesgo de que el proveedor las
# diera de baja por inactividad. min_by sobre ultimo_uso rota el pool solo,
# sin estado adicional (nil = nunca usada, va primero). Elegible = 'activo'
# ausente/true (compat keys viejas), disponible_desde vencido, y
# reservado_hasta ausente/nil/vencido (compat keys pre-P204/Fase3 — la
# reserva vence sola acá, evaluada al consultar, sin limpieza aparte).
def self.disponible(provider)
elegir_libre(leer['keys'].select { |k| k['provider'] == provider })
end
# Igual que disponible, pero dentro de un POOL (P335/Fase 4): refs "provider/identificador" que pueden mezclar
# proveedores. La menos usada recientemente entre las libres, sin importar el proveedor.
def self.disponible_en(refs)
elegir_libre(de_refs(refs))
end
def self.proxima_en(refs)
de_refs(refs).select { |k| k['activo'] != false }.min_by { |k| Time.parse(k['disponible_desde']) }
end
def self.de_refs(refs)
refs = Array(refs)
leer['keys'].select { |k| refs.include?("#{k['provider']}/#{k['identificador']}") }
end
# Criterio ÚNICO de "libre ahora" (activa, no agotada, sin reserva vigente) y de cuál dar (la menos usada).
def self.elegir_libre(keys)
ahora = Time.now
keys
.select do |k|
k['activo'] != false &&
Time.parse(k['disponible_desde']) <= ahora &&
(k['reservado_hasta'].nil? || Time.parse(k['reservado_hasta']) <= ahora)
end
.min_by { |k| k['ultimo_uso'] ? Time.parse(k['ultimo_uso']) : Time.at(0) }
end
# Próxima key de un provider a liberarse (para responder explícito, nunca
# silencioso) — también excluye desactivadas, nunca las ofrece como "próxima".
def self.proxima(provider)
leer['keys']
.select { |k| k['provider'] == provider && k['activo'] != false }
.min_by { |k| Time.parse(k['disponible_desde']) }
end
end
end