req-229 — Biblioteca de Estado e Acesso Controlado a Variáveis Globais (Ponte para Refatoração OOP)

Hoje no Conn2Flow, a esmagadora maioria dos módulos acessa e modifica o estado global do sistema através de global $_GESTOR; e escrita livre direta no array (ex…

Status: in-review
Modo de Autonomia: autonomo_monitorado
Lote Alvo: BATCH-238
Data de Criação: 2026-10-04
Repositório: conn2flow (Core) em [REDACTED]
Origem: Engenheiro Chefe / Arquiteto Master: Criação do meio de campo controlado para desacoplar a manipulação indiscriminada de $_GESTOR sem quebrar o código procedural existente.
Aviso de Concorrência: Isolar a criação das novas funções/helpers na camada de biblioteca (gestor/bibliotecas/variaveis.php ou gestor/bibliotecas/gestor.php), mantendo total retrocompatibilidade com chamadas procedurais antigas.

1. Contexto e Objetivos

Hoje no Conn2Flow, a esmagadora maioria dos módulos acessa e modifica o estado global do sistema através de global $_GESTOR; e escrita livre direta no array (ex.: $_GESTOR['modulo-id'], $_GESTOR['usuario-id'], etc.).

Embora isso seja simples e direto, a manipulação global irrestrita:

Impede rastreamento de quem alterou o quê no ciclo de vida da requisição;
Dificulta testes unitários isolados;
Cria alto acoplamento para a futura migração de classes da Linha 3.1.

A Solução Estratégica: O Meio-Termo Controlado

Criar uma camada de controle e acesso unificado (State/Context Accessor) com funções determinísticas que encapsulam $_GESTOR, adicionando:

Validação de chaves e tipos;
Imutabilidade onde necessário (ex.: IDs de sistema e configurações de ambiente);
Log de auditoria/depuração quando uma chave crítica for sobrescrita;
Total retrocompatibilidade: o array $_GESTOR continua existindo por debaixo dos panos, mas os módulos passam a adotar as funções controladas.

2. Escopo Detalhado

2.1. Funções Core da Biblioteca de Variáveis

Implementar em gestor/bibliotecas/gestor.php (ou helper dedicado):

/**
 * Recupera um valor de configuração/estado do sistema com suporte a fallback e notação pontuada.
 * Exemplo: gestor_get('usuario-id') ou gestor_get('banco.conexao.host', 'localhost')
 */
function gestor_get(string $chave, mixed $padrao = null): mixed;
/**
 * Define ou atualiza um valor no estado global de forma segura e controlada.
 * Se a chave for protegida/read-only, emite alerta no log e bloqueia mutação acidental.
 */
function gestor_set(string $chave, mixed $valor): bool;
/**
 * Verifica a existência de uma chave no estado global.
 */
function gestor_has(string $chave): bool;
/**
 * Retorna uma fatia de contexto delimitada (ex.: dados do módulo ativo ou usuário ativo).
 */
function gestor_contexto(string $escopo): array;

2.2. Proteção de Chaves Críticas

Criar allowlist de chaves somente-leitura após inicialização do kernel:
- raiz-absoluta, url-raiz, linguagem-codigo, versao-num.
Se um módulo tentar sobrescrever essas chaves via gestor_set(), registrar erro no log de sistema e manter a integridade do Core.

2.3. Preparação Arquitetural para a Versão 3.1

Implementar as funções já utilizando internamente uma classe estática enxuta ou Singleton (GestorState::get(), GestorState::set()), enquanto as funções procedurais gestor_get() e gestor_set() atuam como fachada pública estável.
Dessa forma, quando iniciarmos a migração de classes na Linha 3.1, os módulos já estarão desacoplados do global $_GESTOR e prontos para injeção de dependência.

3. Critérios de Aceite (Definition of Done)

[x] CA-1 (Funções Implementadas): gestor_get(), gestor_set(), gestor_has() e gestor_contexto() criadas e testadas.
[x] CA-2 (Retrocompatibilidade Integral 100%): Nenhuma alteração quebra códigos legados que ainda utilizam $_GESTOR['chave'] diretamente.
[x] CA-3 (Proteção de Chaves do Core): Tentativas de alteração em chaves do sistema protegidas são barradas ou registradas com aviso.
[x] CA-4 (Suíte de Testes no PHPUnit): Testes unitários cobrindo leitura, escrita, fallbacks e integridade do estado global.
[x] CA-5 (Documentação Técnica): Guia em docs/ e atualização na skill correspondente orientando novos desenvolvimentos a utilizarem a nova API.

# req-229 — Biblioteca de Estado e Acesso Controlado a Variáveis Globais (Ponte para Refatoração OOP)
- **Status:** `in-review`
- **Modo de Autonomia:** `autonomo_monitorado`
- **Lote Alvo:** `BATCH-238`
- **Data de Criação:** 2026-10-04
- **Repositório:** `conn2flow` (Core) em `[REDACTED]`
- **Origem:** Engenheiro Chefe / Arquiteto Master: Criação do meio de campo controlado para desacoplar a manipulação indiscriminada de `$_GESTOR` sem quebrar o código procedural existente.
- **Aviso de Concorrência:** Isolar a criação das novas funções/helpers na camada de biblioteca (`gestor/bibliotecas/variaveis.php` ou `gestor/bibliotecas/gestor.php`), mantendo total retrocompatibilidade com chamadas procedurais antigas.
---
## 1. Contexto e Objetivos
Hoje no Conn2Flow, a esmagadora maioria dos módulos acessa e modifica o estado global do sistema através de `global $_GESTOR;` e escrita livre direta no array (ex.: `$_GESTOR['modulo-id']`, `$_GESTOR['usuario-id']`, etc.). 
Embora isso seja simples e direto, a manipulação global irrestrita:
1. Impede rastreamento de quem alterou o quê no ciclo de vida da requisição;
2. Dificulta testes unitários isolados;
3. Cria alto acoplamento para a futura migração de classes da **Linha 3.1**.
### A Solução Estratégica: O Meio-Termo Controlado
Criar uma **camada de controle e acesso unificado (State/Context Accessor)** com funções determinísticas que encapsulam `$_GESTOR`, adicionando:
- Validação de chaves e tipos;
- Imutabilidade onde necessário (ex.: IDs de sistema e configurações de ambiente);
- Log de auditoria/depuração quando uma chave crítica for sobrescrita;
- Total retrocompatibilidade: o array `$_GESTOR` continua existindo por debaixo dos panos, mas os módulos passam a adotar as funções controladas.
---
## 2. Escopo Detalhado
### 2.1. Funções Core da Biblioteca de Variáveis
Implementar em `gestor/bibliotecas/gestor.php` (ou helper dedicado):
```php
/**
 * Recupera um valor de configuração/estado do sistema com suporte a fallback e notação pontuada.
 * Exemplo: gestor_get('usuario-id') ou gestor_get('banco.conexao.host', 'localhost')
 */
function gestor_get(string $chave, mixed $padrao = null): mixed;
/**
 * Define ou atualiza um valor no estado global de forma segura e controlada.
 * Se a chave for protegida/read-only, emite alerta no log e bloqueia mutação acidental.
 */
function gestor_set(string $chave, mixed $valor): bool;
/**
 * Verifica a existência de uma chave no estado global.
 */
function gestor_has(string $chave): bool;
/**
 * Retorna uma fatia de contexto delimitada (ex.: dados do módulo ativo ou usuário ativo).
 */
function gestor_contexto(string $escopo): array;
```
### 2.2. Proteção de Chaves Críticas
- Criar allowlist de chaves somente-leitura após inicialização do kernel:
  - `raiz-absoluta`, `url-raiz`, `linguagem-codigo`, `versao-num`.
- Se um módulo tentar sobrescrever essas chaves via `gestor_set()`, registrar erro no log de sistema e manter a integridade do Core.
### 2.3. Preparação Arquitetural para a Versão 3.1
- Implementar as funções já utilizando internamente uma classe estática enxuta ou Singleton (`GestorState::get()`, `GestorState::set()`), enquanto as funções procedurais `gestor_get()` e `gestor_set()` atuam como fachada pública estável.
- Dessa forma, quando iniciarmos a migração de classes na **Linha 3.1**, os módulos já estarão desacoplados do `global $_GESTOR` e prontos para injeção de dependência.
---
## 3. Critérios de Aceite (Definition of Done)
- [x] **CA-1 (Funções Implementadas):** `gestor_get()`, `gestor_set()`, `gestor_has()` e `gestor_contexto()` criadas e testadas.
- [x] **CA-2 (Retrocompatibilidade Integral 100%):** Nenhuma alteração quebra códigos legados que ainda utilizam `$_GESTOR['chave']` diretamente.
- [x] **CA-3 (Proteção de Chaves do Core):** Tentativas de alteração em chaves do sistema protegidas são barradas ou registradas com aviso.
- [x] **CA-4 (Suíte de Testes no PHPUnit):** Testes unitários cobrindo leitura, escrita, fallbacks e integridade do estado global.
- [x] **CA-5 (Documentação Técnica):** Guia em `docs/` e atualização na skill correspondente orientando novos desenvolvimentos a utilizarem a nova API.