feat(nexxa): taxonomía cerrada de estados y registro completo de eventos (motivo, hasta, quién), /resumen y /usos filtrable; 2.0.0 (P337/F1)
Tests ADN / test (push) Canceled after 0s

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-05 03:29:40 -03:00
co-authored by Claude Opus 5.5 GEMMA
parent 08aa45117e
commit 82e56aad0e
11 changed files with 233 additions and 81 deletions
+72 -30
View File
@@ -70,8 +70,10 @@ module Nexxa
# 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)
# por (P337/Fase 1): quién la dio de alta o la reemplazó, para el registro ('web:<usuario>', 'cli'...)
def self.registrar(provider:, identificador:, cuenta_origen:, reset_segundos:, valor: nil, ultimo_uso: nil, por: nil)
ahora = Time.now
evento = nil
disponible_desde = ultimo_uso ? (Time.parse(ultimo_uso) + reset_segundos).iso8601(3) : ahora.iso8601(3)
ultimo_uso ||= ahora.iso8601(3)
@@ -79,6 +81,7 @@ module Nexxa
mutar do |state|
existente = state['keys'].find { |k| k['provider'] == provider && k['identificador'] == identificador }
evento = existente ? 'editada' : 'alta'
if existente
existente.merge!(
'ultimo_uso' => ultimo_uso,
@@ -103,21 +106,33 @@ module Nexxa
}
end
state
end.tap do
Nexxa::Usos.registrar(provider: provider, identificador: identificador, individuo: por || 'desconocido', en: ahora,
evento: evento, motivo: evento == 'editada' && valor ? 'valor reemplazado' : nil)
end
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)
def self.actualizar(provider:, identificador:, cuenta_origen: nil, reset_segundos: nil, activo: nil, por: nil)
entrada = nil
cambios = []
mutar do |state|
entrada = buscar!(state, provider, identificador)
entrada['cuenta_origen'] = cuenta_origen unless cuenta_origen.nil?
entrada['reset_segundos'] = reset_segundos unless reset_segundos.nil?
entrada['activo'] = activo unless activo.nil?
{ 'cuenta_origen' => cuenta_origen, 'reset_segundos' => reset_segundos, 'activo' => activo }.each do |campo, valor|
next if valor.nil? || entrada[campo] == valor
cambios << "#{campo}: #{entrada[campo].inspect} → #{valor.inspect}"
entrada[campo] = valor
end
state
end
# Qué cambió, sin ambigüedad (nunca el valor de la key: este método no lo toca)
unless cambios.empty?
Nexxa::Usos.registrar(provider: provider, identificador: identificador, individuo: por || 'desconocido',
evento: 'editada', motivo: cambios.join('; '))
end
entrada
end
@@ -148,21 +163,28 @@ module Nexxa
state
end
Nexxa::Usos.registrar(provider: provider, identificador: a, individuo: usuario ? "web:#{usuario}" : 'web',
en: ahora, evento: "renombrada (antes #{de})")
en: ahora, evento: 'renombrada', motivo: "antes #{de}")
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:)
def self.eliminar(provider:, identificador:, por: nil)
existia = nil
mutar do |state|
existia = state['keys'].reject! { |k| k['provider'] == provider && k['identificador'] == identificador }
state
end
Nexxa::Usos.registrar(provider: provider, identificador: identificador, individuo: por || 'desconocido', evento: 'baja') if existia
!existia.nil?
end
# Todas las keys con su estado de la taxonomía (P337/Fase 1), calculado sobre la key COMPLETA (sin valor_cifrado
# daría sin_valor) y recién después sin el valor (Regla 15). Lo que muestra nexxa-web: nada se recalcula allá.
def self.todas_con_estado(ahora = Time.now)
leer['keys'].map { |k| k.reject { |campo, _| campo == 'valor_cifrado' }.merge(estado_de_key(k, ahora)) }
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
@@ -192,7 +214,8 @@ module Nexxa
entrada = aplicar_reserva(buscar!(state, provider, identificador), individuo, ahora)
state
end
Nexxa::Usos.registrar(provider: provider, identificador: identificador, individuo: individuo, en: ahora, evento: 'dispensada')
Nexxa::Usos.registrar(provider: provider, identificador: identificador, individuo: individuo, en: ahora, evento: 'dispensada',
hasta: entrada['reservado_hasta'])
entrada
end
@@ -213,7 +236,7 @@ module Nexxa
end
if elegida && elegida['valor_cifrado']
Nexxa::Usos.registrar(provider: elegida['provider'], identificador: elegida['identificador'], individuo: individuo,
en: ahora, evento: 'dispensada')
en: ahora, evento: 'dispensada', hasta: elegida['reservado_hasta'])
end
elegida
end
@@ -244,7 +267,7 @@ module Nexxa
def self.reportar(provider:, identificador:, individuo:, estado:, liberar_en_segundos: nil, motivo: nil)
ahora = Time.now
entrada = nil
evento = nil
evento = hasta = nil
mutar do |state| # sin 'return' adentro (P335/Fase 17): el bloque es una transacción
entrada = buscar!(state, provider, identificador)
if estado == 'liberada' && entrada['reservado_por'] != individuo && revertible_por?(entrada, individuo, ahora)
@@ -254,24 +277,26 @@ module Nexxa
else
raise "Key #{provider}/#{identificador} no está reservada por #{individuo}" unless entrada['reservado_por'] == individuo
evento = aplicar_reporte(entrada, estado, individuo, ahora, liberar_en_segundos, motivo)
evento, hasta = aplicar_reporte(entrada, estado, individuo, ahora, liberar_en_segundos, motivo)
end
state
end
Nexxa::Usos.registrar(provider: provider, identificador: identificador, individuo: individuo, en: ahora, evento: evento) if evento
# Registro completo (P337/Fase 1): cada reporte queda, con el motivo del proveedor y hasta cuándo
Nexxa::Usos.registrar(provider: provider, identificador: identificador, individuo: individuo, en: ahora, evento: evento,
motivo: (motivo.to_s[0, 200] if %w[pausada agotada].include?(evento)), hasta: hasta)
entrada
end
# => evento de usos a registrar ('agotada') o nil
# => [evento de usos, hasta] — renovada (con el nuevo fin de reserva), liberada, pausada o agotada (con el fin del bloqueo)
def self.aplicar_reporte(entrada, estado, individuo, ahora, liberar_en_segundos, motivo)
case estado
when 'sana'
entrada['reservado_hasta'] = (ahora + RESERVA_TTL_SEGUNDOS).iso8601(3)
nil
['renovada', entrada['reservado_hasta']]
when 'liberada'
entrada['reservado_por'] = nil
entrada['reservado_hasta'] = nil
nil
['liberada', nil]
when 'agotada'
reset_segundos = entrada['reset_segundos']
unless reset_segundos
@@ -279,11 +304,12 @@ module Nexxa
end
entrada['disponible_desde'] = (ahora + (liberar_en_segundos || reset_segundos)).iso8601(3)
entrada['bloqueo'] = tipo_bloqueo(liberar_en_segundos)
entrada['agotada_por'] = individuo
entrada['motivo_agotada'] = motivo.to_s[0, 200] unless motivo.to_s.empty?
entrada['motivo_agotada'] = motivo.to_s.empty? ? nil : motivo.to_s[0, 200]
entrada['reservado_por'] = nil
entrada['reservado_hasta'] = nil
'agotada'
[entrada['bloqueo'] == 'pausa' ? 'pausada' : 'agotada', entrada['disponible_desde']]
else
raise "estado inválido: #{estado} (esperado: sana|liberada|agotada)"
end
@@ -301,6 +327,7 @@ module Nexxa
entrada['reservado_hasta'] = nil
entrada['agotada_por'] = nil
entrada['motivo_agotada'] = nil
entrada['bloqueo'] = nil
state
end
Nexxa::Usos.registrar(provider: provider, identificador: identificador, individuo: "web:#{usuario}", en: ahora,
@@ -324,20 +351,35 @@ module Nexxa
estado_de(de_refs(refs), ahora)
end
# Taxonomía CERRADA de estados (P337/Fase 1): la única fuente; nexxa-web y GEMMA la muestran, nunca la recalculan.
# Excluyentes y en este orden de precedencia. Campos uniformes: hasta = cuándo cambia de estado, por = quién
# reservó o bloqueó, motivo = lo que contestó el proveedor.
ESTADOS = %w[disponible en_uso en_pausa agotada desactivada sin_valor].freeze
# Un bloqueo de hasta esto es una PAUSA por límite del proveedor (el 429 por minuto); más largo, cuota agotada
PAUSA_MAX_SEG = 300
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
keys.map { |k| { 'provider' => k['provider'], 'identificador' => k['identificador'] }.merge(estado_de_key(k, ahora)) }
end
def self.estado_de_key(k, ahora = Time.now)
bloqueada = Time.parse(k['disponible_desde']) > ahora
reservada = k['reservado_hasta'] && Time.parse(k['reservado_hasta']) > ahora
e = if k['activo'] == false then { 'estado' => 'desactivada' }
elsif !k.key?('valor_cifrado') || k['valor_cifrado'].nil? then { 'estado' => 'sin_valor' }
elsif bloqueada
{ 'estado' => k['bloqueo'] == 'pausa' ? 'en_pausa' : 'agotada', 'hasta' => k['disponible_desde'],
'por' => k['agotada_por'], 'motivo' => k['motivo_agotada'] }
elsif reservada then { 'estado' => 'en_uso', 'hasta' => k['reservado_hasta'], 'por' => k['reservado_por'] }
else { 'estado' => 'disponible' }
end
{ 'hasta' => nil, 'por' => nil, 'motivo' => nil }.merge(e)
.merge('ultimo_uso' => k['ultimo_uso'], 'ultimo_individuo' => k['ultimo_individuo'])
end
# 'pausa' (bloqueo corto, límite del proveedor) o 'agotada' (cuota del ciclo), decidido por la duración real
def self.tipo_bloqueo(segundos)
segundos && segundos.to_i <= PAUSA_MAX_SEG ? 'pausa' : 'agotada'
end
def self.cifrar(valor)