forjajs 1.7.2 → 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +49 -0
- package/README.md +223 -217
- package/README.pt-BR.md +323 -0
- package/dist/apps/dashboard/app/api/forja/[...path]/route.d.ts +10 -0
- package/dist/apps/dashboard/app/api/forja/[...path]/route.js +36 -0
- package/dist/apps/dashboard/app/api/forja/approval.d.ts +1 -0
- package/dist/apps/dashboard/app/api/forja/approval.js +8 -0
- package/dist/apps/dashboard/app/dashboard-client.d.ts +1 -0
- package/dist/apps/dashboard/app/dashboard-client.jsx +62 -0
- package/dist/apps/dashboard/app/layout.d.ts +9 -0
- package/dist/apps/dashboard/app/layout.jsx +7 -0
- package/dist/apps/dashboard/app/page.d.ts +1 -0
- package/dist/apps/dashboard/app/page.jsx +5 -0
- package/dist/apps/dashboard/app/providers.d.ts +4 -0
- package/dist/apps/dashboard/app/providers.jsx +7 -0
- package/dist/apps/dashboard/next.config.d.mts +6 -0
- package/dist/apps/dashboard/next.config.mjs +8 -0
- package/dist/apps/dashboard/src/index.d.ts +14 -0
- package/dist/apps/dashboard/src/index.js +16 -0
- package/dist/apps/server/src/app.module.d.ts +5 -0
- package/dist/apps/server/src/app.module.js +16 -0
- package/dist/apps/server/src/forja-nest.module.d.ts +59 -0
- package/dist/apps/server/src/forja-nest.module.js +316 -0
- package/dist/apps/server/src/index.d.ts +15 -0
- package/dist/apps/server/src/index.js +7 -0
- package/dist/apps/server/src/main.d.ts +12 -0
- package/dist/apps/server/src/main.js +105 -0
- package/dist/apps/worker/src/main.d.ts +12 -0
- package/dist/apps/worker/src/main.js +18 -0
- package/dist/lib/core/health.js +26 -4
- package/dist/packages/adapter-git/src/index.d.ts +27 -0
- package/dist/packages/adapter-git/src/index.js +53 -0
- package/dist/packages/adapter-nest/src/index.d.ts +71 -0
- package/dist/packages/adapter-nest/src/index.js +142 -0
- package/dist/packages/adapter-sqlite/src/index.d.ts +99 -0
- package/dist/packages/adapter-sqlite/src/index.js +108 -0
- package/dist/packages/context/src/index.d.ts +52 -0
- package/dist/packages/context/src/index.js +108 -0
- package/dist/packages/contracts/src/index.d.ts +368 -0
- package/dist/packages/contracts/src/index.js +27 -0
- package/dist/packages/core/src/index.d.ts +68 -0
- package/dist/packages/core/src/index.js +141 -0
- package/dist/packages/evals/src/index.d.ts +22 -0
- package/dist/packages/evals/src/index.js +65 -0
- package/dist/packages/events/src/index.d.ts +47 -0
- package/dist/packages/events/src/index.js +96 -0
- package/dist/packages/graph/src/index.d.ts +80 -0
- package/dist/packages/graph/src/index.js +163 -0
- package/dist/packages/mcp/src/index.d.ts +119 -0
- package/dist/packages/mcp/src/index.js +153 -0
- package/dist/packages/observability/src/index.d.ts +132 -0
- package/dist/packages/observability/src/index.js +86 -0
- package/dist/packages/orchestration/src/index.d.ts +122 -0
- package/dist/packages/orchestration/src/index.js +178 -0
- package/dist/packages/planner/src/index.d.ts +22 -0
- package/dist/packages/planner/src/index.js +70 -0
- package/dist/packages/plugin-sdk/src/index.d.ts +56 -0
- package/dist/packages/plugin-sdk/src/index.js +55 -0
- package/dist/packages/policy/src/index.d.ts +80 -0
- package/dist/packages/policy/src/index.js +136 -0
- package/dist/packages/runtime/src/index.d.ts +91 -0
- package/dist/packages/runtime/src/index.js +217 -0
- package/dist/packages/sandbox/src/index.d.ts +64 -0
- package/dist/packages/sandbox/src/index.js +108 -0
- package/dist/packages/scheduler/src/index.d.ts +56 -0
- package/dist/packages/scheduler/src/index.js +123 -0
- package/dist/packages/sdk/src/index.d.ts +122 -0
- package/dist/packages/sdk/src/index.js +40 -0
- package/dist/packages/validator/src/index.d.ts +36 -0
- package/dist/packages/validator/src/index.js +60 -0
- package/docs/architecture/FORJA-2.0-ARCHITECTURE.md +109 -0
- package/docs/architecture/FORJA-2.0-IMPACT-FOUNDATION.md +273 -0
- package/docs/security/FORJA-2.0-RELEASE-AUDIT-2026-08-01.md +95 -0
- package/docs/vision/FORJA-2.0-VISION.md +72 -0
- package/memory/50-orchestration/handoffs/2026-07-31_architect_foundation-contracts.md +15 -0
- package/memory/50-orchestration/handoffs/2026-07-31_backend-nest.md +22 -0
- package/memory/50-orchestration/handoffs/2026-07-31_context-engine.md +16 -0
- package/memory/50-orchestration/handoffs/2026-07-31_control-plane.md +28 -0
- package/memory/50-orchestration/handoffs/2026-07-31_core-capability-registry.md +15 -0
- package/memory/50-orchestration/handoffs/2026-07-31_evals-plugin-sdk.md +22 -0
- package/memory/50-orchestration/handoffs/2026-07-31_events-scheduler.md +16 -0
- package/memory/50-orchestration/handoffs/2026-07-31_graphloop.md +16 -0
- package/memory/50-orchestration/handoffs/2026-07-31_mcp.md +21 -0
- package/memory/50-orchestration/handoffs/2026-07-31_nest-bootstrap.md +28 -0
- package/memory/50-orchestration/handoffs/2026-07-31_next-dashboard.md +22 -0
- package/memory/50-orchestration/handoffs/2026-07-31_observability.md +27 -0
- package/memory/50-orchestration/handoffs/2026-07-31_orchestration.md +21 -0
- package/memory/50-orchestration/handoffs/2026-07-31_planner-validator.md +16 -0
- package/memory/50-orchestration/handoffs/2026-07-31_policy-engine.md +14 -0
- package/memory/50-orchestration/handoffs/2026-07-31_runtime-control-plane.md +23 -0
- package/memory/50-orchestration/handoffs/2026-07-31_runtime-controlado.md +15 -0
- package/memory/50-orchestration/handoffs/2026-07-31_sandbox.md +21 -0
- package/memory/50-orchestration/handoffs/2026-07-31_sdk.md +27 -0
- package/memory/50-orchestration/handoffs/2026-07-31_sqlite-adapter.md +21 -0
- package/memory/50-orchestration/handoffs/2026-07-31_worker-dashboard-boundary.md +23 -0
- package/memory/50-orchestration/handoffs/2026-08-01_approval-server-identity.md +23 -0
- package/memory/50-orchestration/handoffs/2026-08-01_dashboard-auth-query.md +24 -0
- package/memory/50-orchestration/handoffs/2026-08-01_graphloop-approvals.md +23 -0
- package/memory/90-decisions/0033-doctor-distingue-permissao-de-corrupcao.md +64 -0
- package/memory/90-decisions/0034-forja-2-core-e-contratos.md +29 -0
- package/memory/90-decisions/0035-forja-2-local-first-e-autonomia.md +23 -0
- package/memory/90-decisions/0036-forja-2-capability-registry.md +30 -0
- package/memory/90-decisions/0037-forja-2-policy-engine-obrigatorio.md +28 -0
- package/memory/90-decisions/0038-forja-2-runtime-controlado.md +28 -0
- package/memory/90-decisions/0039-forja-2-event-bus-scheduler-local-first.md +31 -0
- package/memory/90-decisions/0040-forja-2-context-engine-budget-cache.md +32 -0
- package/memory/90-decisions/0041-forja-2-graphloop-separado-codegraph.md +32 -0
- package/memory/90-decisions/0042-forja-2-planner-validator-independentes.md +29 -0
- package/memory/90-decisions/0043-forja-2-orchestration-entities.md +16 -0
- package/memory/90-decisions/0044-forja-2-sandbox-worktree.md +19 -0
- package/memory/90-decisions/0045-forja-2-sqlite-adapter.md +19 -0
- package/memory/90-decisions/0046-forja-2-mcp-adapter.md +18 -0
- package/memory/90-decisions/0047-forja-2-backend-nest-adapter.md +19 -0
- package/memory/90-decisions/0048-forja-2-sdk-transport.md +18 -0
- package/memory/90-decisions/0049-forja-2-observability-control-plane.md +18 -0
- package/memory/90-decisions/0050-forja-2-control-plane-application-ports.md +18 -0
- package/memory/90-decisions/0051-forja-2-runtime-control-plane-composition.md +18 -0
- package/memory/90-decisions/0052-forja-2-deterministic-evaluation.md +15 -0
- package/memory/90-decisions/0053-forja-2-plugin-sdk-permissionado.md +16 -0
- package/memory/90-decisions/0054-forja-2-worker-dashboard-boundary.md +15 -0
- package/memory/90-decisions/0055-forja-2-next-dashboard-distribution.md +16 -0
- package/memory/90-decisions/0056-forja-2-dashboard-proxy-auth-query.md +16 -0
- package/memory/90-decisions/0057-forja-2-graphloop-approvals-dashboard.md +15 -0
- package/memory/90-decisions/0058-forja-2-approval-server-identity.md +15 -0
- package/package.json +28 -3
- package/README.en.md +0 -329
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Handoff — Approval server-side concluído
|
|
2
|
+
|
|
3
|
+
- **from**: graphloop-ui-engineer
|
|
4
|
+
- **to**: release-security-auditor
|
|
5
|
+
- **intent**: review
|
|
6
|
+
- **context**: `apps/dashboard/app/api/forja/approval.ts`; `apps/dashboard/app/api/forja/[...path]/route.ts`; `apps/dashboard/app/dashboard-client.tsx`; ADR-0058
|
|
7
|
+
- **acceptance**: cliente envia apenas decisão; proxy exige `FORJA_APPROVER_ID`, injeta identidade/timestamp e encaminha; entradas inválidas são rejeitadas; ausência de identidade não aprova.
|
|
8
|
+
- **constraints**: não expor token/identidade como segredo no cliente; não bypassar ApprovalLedger; não usar fallback permissivo.
|
|
9
|
+
- **return**: executar auditoria de segurança, verificar packaging/dependencies, revisar release gates e preparar GO/NO-GO.
|
|
10
|
+
|
|
11
|
+
## Evidências
|
|
12
|
+
|
|
13
|
+
- `npm run types:check`: passou.
|
|
14
|
+
- `npm run build`: passou.
|
|
15
|
+
- `npm run dashboard:build`: passou.
|
|
16
|
+
- `npm test -- --test-concurrency=1`: 267 testes passaram.
|
|
17
|
+
- `git diff --check`: passou.
|
|
18
|
+
|
|
19
|
+
## Métricas de tokens
|
|
20
|
+
|
|
21
|
+
- consumo de LLM: não aplicável;
|
|
22
|
+
- decisões de approval: determinísticas e server-side;
|
|
23
|
+
- testes adicionados: 2 cenários de identidade/configuração.
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# Handoff — Dashboard proxy, autenticação e estado remoto
|
|
2
|
+
|
|
3
|
+
- **from**: control-plane-ui-engineer
|
|
4
|
+
- **to**: graphloop-ui-release-auditor
|
|
5
|
+
- **intent**: implement
|
|
6
|
+
- **context**: `apps/dashboard/app/api/forja/[...path]/route.ts`; `apps/dashboard/app/providers.tsx`; `apps/dashboard/app/dashboard-client.tsx`; `packages/adapter-nest/src/index.ts`; `apps/server/src/main.ts`; ADR-0056
|
|
7
|
+
- **acceptance**: token fica server-side; proxy aplica allowlist; TanStack Query cacheia métricas/observações; SSE invalida snapshot; pausa/cancelamento delegam ao Control Plane; Bearer inválido é rejeitado.
|
|
8
|
+
- **constraints**: não expor `FORJA_AUTH_TOKEN`; não usar proxy genérico; não autorizar no cliente; manter Policy e persistência fora do dashboard.
|
|
9
|
+
- **return**: implementar GraphLoop visual, approvals e demais áreas operacionais; executar auditoria de segurança, packaging e release gates.
|
|
10
|
+
|
|
11
|
+
## Evidências
|
|
12
|
+
|
|
13
|
+
- `npm run types:check`: passou.
|
|
14
|
+
- `npm run build`: passou.
|
|
15
|
+
- `npm run dashboard:build`: passou com Next 15.5.9.
|
|
16
|
+
- `npm test -- --test-concurrency=1`: 265 testes passaram.
|
|
17
|
+
- `npm test` paralelo: instável em testes legados que alteram PATH/processos; investigar no harness antes do release.
|
|
18
|
+
- `git diff --check`: passou.
|
|
19
|
+
|
|
20
|
+
## Métricas de tokens
|
|
21
|
+
|
|
22
|
+
- consumo de LLM: não aplicável;
|
|
23
|
+
- dashboard usa cache remoto com `staleTime` de 5 segundos;
|
|
24
|
+
- SSE invalida a query sem reenviar histórico ao cliente.
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Handoff — GraphLoop e approvals no dashboard
|
|
2
|
+
|
|
3
|
+
- **from**: graphloop-ui-engineer
|
|
4
|
+
- **to**: release-security-auditor
|
|
5
|
+
- **intent**: review
|
|
6
|
+
- **context**: `packages/graph/src/index.ts`; `packages/adapter-nest/src/index.ts`; `packages/policy/src/index.ts`; `packages/observability/src/index.ts`; `apps/server/src/main.ts`; `apps/dashboard/app/dashboard-client.tsx`; ADR-0057
|
|
7
|
+
- **acceptance**: dashboard consulta nós/impacto e lista approvals por API; GraphLoop permanece no domínio; Policy/approval não são decididos no cliente; proxy mantém allowlist; typecheck/build/testes passam.
|
|
8
|
+
- **constraints**: não inventar arestas/evidências; não aprovar sem identidade; não liberar acesso direto a SQLite; manter execução crítica no Control Plane.
|
|
9
|
+
- **return**: implementar visualização avançada/evidências e fluxo de aprovação autenticado, depois executar auditoria de segurança, packaging e release.
|
|
10
|
+
|
|
11
|
+
## Evidências
|
|
12
|
+
|
|
13
|
+
- `npm run types:check`: passou.
|
|
14
|
+
- `npm run build`: passou.
|
|
15
|
+
- `npm run dashboard:build`: passou.
|
|
16
|
+
- `npm test -- --test-concurrency=1`: 265 testes passaram.
|
|
17
|
+
- `git diff --check`: passou.
|
|
18
|
+
|
|
19
|
+
## Métricas de tokens
|
|
20
|
+
|
|
21
|
+
- consumo de LLM: não aplicável;
|
|
22
|
+
- GraphLoop e impacto: consultas determinísticas;
|
|
23
|
+
- approvals: listagem estruturada, sem decisão automática.
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# ADR-0033: `memory-db` distingue permissão/lock de corrupção
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-07-23
|
|
5
|
+
- **Autor(es)**: Allan Pablo
|
|
6
|
+
- **Tags**: doctor, memory, diagnostics, sqlite
|
|
7
|
+
|
|
8
|
+
## Contexto
|
|
9
|
+
|
|
10
|
+
O check `memory-db` (`lib/core/health.ts`), consumido por `tools:doctor` e pelo hook
|
|
11
|
+
`SessionStart`, abria `universal.db` e tratava **qualquer** exceção do `better-sqlite3` como
|
|
12
|
+
corrupção:
|
|
13
|
+
|
|
14
|
+
```ts
|
|
15
|
+
} catch (err) {
|
|
16
|
+
return {
|
|
17
|
+
status: 'fail',
|
|
18
|
+
detail: `... (${asErrno(err).code}) — provavelmente corrompido`,
|
|
19
|
+
fix: 'npm run sync:universal',
|
|
20
|
+
};
|
|
21
|
+
}
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
O `err.code` — que já distingue os casos — estava impresso no `detail`, mas não decidia nada.
|
|
25
|
+
Num ambiente sem permissão de escrita (sandbox, FS read-only, diretório protegido) o driver
|
|
26
|
+
lança `SQLITE_CANTOPEN`, e o doctor diagnosticava "provavelmente corrompido" prescrevendo
|
|
27
|
+
`sync:universal`. A prescrição é ativamente errada: `sync:universal` **escreve** no banco — no
|
|
28
|
+
mesmo ambiente ele reencena o `CANTOPEN` sem curar nada, e ainda confunde o operador levando-o a
|
|
29
|
+
"reindexar" um banco íntegro. Reportado a partir de uma sessão real em sandbox restrito.
|
|
30
|
+
|
|
31
|
+
É a violação do princípio 1 do próprio `health.ts` ("nunca colapsar causas distintas num
|
|
32
|
+
booleano"), a mesma classe do bug de ABI que motivou a SPEC-009 — sobrevivendo dentro do arquivo
|
|
33
|
+
escrito para fechá-la.
|
|
34
|
+
|
|
35
|
+
## Decisão
|
|
36
|
+
|
|
37
|
+
Classificar a falha de abertura por `err.code`, uma causa por prescrição:
|
|
38
|
+
|
|
39
|
+
- `SQLITE_CANTOPEN` / `EACCES` → `fail`, **permissão/sandbox**, não corrupção; fix orienta
|
|
40
|
+
garantir leitura no path e **desaconselha** `sync:universal`.
|
|
41
|
+
- `SQLITE_BUSY` → `warn` (lock temporário de outro processo; não trava o gate); fix é aguardar.
|
|
42
|
+
- Resto (`SQLITE_CORRUPT`, `SQLITE_NOTADB`, …) → `fail`, **corrupção**; fix `npm run sync:universal`.
|
|
43
|
+
|
|
44
|
+
## Alternativas consideradas
|
|
45
|
+
|
|
46
|
+
- **Testar a integridade com `PRAGMA quick_check` antes de classificar** — rejeitada: um banco que
|
|
47
|
+
nem abre (CANTOPEN) não chega ao pragma; o `err.code` da abertura já carrega a distinção sem I/O extra.
|
|
48
|
+
- **Discriminar por mensagem de erro** — rejeitada: mensagens do SQLite variam entre versões e
|
|
49
|
+
locale; `err.code` é o contrato estável, como o resto do `health.ts` já assume.
|
|
50
|
+
|
|
51
|
+
## Consequências
|
|
52
|
+
|
|
53
|
+
**Positivas**:
|
|
54
|
+
- Sandbox/permissão deixa de ser confundido com corrupção; o operador recebe a correção da causa real.
|
|
55
|
+
- `sync:universal` nunca é prescrito para um banco íntegro-mas-inacessível.
|
|
56
|
+
- Lock concorrente vira `warn`, não reprova o núcleo.
|
|
57
|
+
|
|
58
|
+
**Negativas / Trade-offs**:
|
|
59
|
+
- Mais um `err.code` (`SQLITE_BUSY`) a manter caso o driver mude a taxonomia — coberto por teste.
|
|
60
|
+
|
|
61
|
+
## Rastreamento
|
|
62
|
+
- Implementação: `lib/core/health.ts` (check `memory-db`)
|
|
63
|
+
- Testes: `test/health.test.js` (CANTOPEN, EACCES, BUSY, NOTADB)
|
|
64
|
+
- ADRs relacionadas: ADR-0023 (doctor como gate do núcleo), SPEC-009 (doctor-do-nucleo)
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# ADR-0034: Fundação 2.0 em contratos versionados e domínio independente
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-07-31
|
|
5
|
+
- **Autor(es)**: ForjaJS
|
|
6
|
+
- **Tags**: architecture, contracts, domain, migration
|
|
7
|
+
|
|
8
|
+
## Contexto
|
|
9
|
+
|
|
10
|
+
O ForjaJS 1.x é um CLI TypeScript com memória SQLite e adapters misturados à operação. A 2.0
|
|
11
|
+
precisa ser consumível por CLI, MCP, SDK, worker e NestJS sem duplicar regras ou contaminar o
|
|
12
|
+
domínio com frameworks.
|
|
13
|
+
|
|
14
|
+
## Decisão
|
|
15
|
+
|
|
16
|
+
Introduzir `packages/contracts` como fonte versionada dos contratos públicos e adotar a direção
|
|
17
|
+
interfaces → adapters → application → domain. A primeira entrega é aditiva; a compatibilidade
|
|
18
|
+
1.x continua roteada pelo CLI até cada capability possuir equivalente 2.0.
|
|
19
|
+
|
|
20
|
+
## Consequências
|
|
21
|
+
|
|
22
|
+
Contratos podem ser testados sem infraestrutura e adapters ficam substituíveis. O custo inicial
|
|
23
|
+
é manter versões, schemas e compatibilidade explícita.
|
|
24
|
+
|
|
25
|
+
## Rastreamento
|
|
26
|
+
|
|
27
|
+
- Implementação: `packages/contracts/`
|
|
28
|
+
- Arquitetura: `docs/architecture/FORJA-2.0-ARCHITECTURE.md`
|
|
29
|
+
- Visão: `docs/vision/FORJA-2.0-VISION.md`
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# ADR-0035: SQLite local-first e autonomia supervisionada
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-07-31
|
|
5
|
+
- **Autor(es)**: ForjaJS
|
|
6
|
+
- **Tags**: runtime, policy, sqlite, autonomy
|
|
7
|
+
|
|
8
|
+
## Decisão
|
|
9
|
+
|
|
10
|
+
SQLite é o backend local padrão para estado durável, eventos, auditoria, memória e checkpoints.
|
|
11
|
+
O nível padrão de autonomia é supervisionado: toda ação crítica passa pelo Policy Engine e uma
|
|
12
|
+
execução só termina após validação independente. Operações longas devem ser retomáveis.
|
|
13
|
+
|
|
14
|
+
## Alternativas rejeitadas
|
|
15
|
+
|
|
16
|
+
- banco remoto obrigatório — viola offline/local-first;
|
|
17
|
+
- autonomia irrestrita — não permite governança verificável;
|
|
18
|
+
- estado apenas em memória — perde retomada e auditoria.
|
|
19
|
+
|
|
20
|
+
## Rastreamento
|
|
21
|
+
|
|
22
|
+
- `docs/architecture/FORJA-2.0-ARCHITECTURE.md`
|
|
23
|
+
- `packages/contracts/`
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# ADR-0036: Capability Registry como núcleo executável
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-07-31
|
|
5
|
+
- **Autor(es)**: ForjaJS
|
|
6
|
+
- **Tags**: capabilities, contracts, runtime, architecture
|
|
7
|
+
|
|
8
|
+
## Contexto
|
|
9
|
+
|
|
10
|
+
CLI, MCP, SDK, API e Runtime precisam descobrir e executar a mesma operação sem duplicar regras.
|
|
11
|
+
Uma lista de comandos não oferece schema, risco, permissões, idempotência ou resultado auditável.
|
|
12
|
+
|
|
13
|
+
## Decisão
|
|
14
|
+
|
|
15
|
+
`packages/core` mantém um registry em memória como núcleo inicial. Cada registro possui definição
|
|
16
|
+
versionada, aliases, validadores de entrada/saída e handler. A entrada é validada antes da
|
|
17
|
+
autorização e do handler; toda execução retorna `ExecutionResult`. Policy é uma porta injetada e
|
|
18
|
+
não uma implementação dentro do registry.
|
|
19
|
+
|
|
20
|
+
## Consequências
|
|
21
|
+
|
|
22
|
+
Interfaces externas podem ser adaptadores finos e testes não precisam de banco ou framework. A
|
|
23
|
+
persistência do registry, schemas especializados e Policy Engine completo ficam para fases
|
|
24
|
+
posteriores.
|
|
25
|
+
|
|
26
|
+
## Rastreamento
|
|
27
|
+
|
|
28
|
+
- Implementação: `packages/core/src/index.ts`
|
|
29
|
+
- Testes: `test/capability-registry.test.js`
|
|
30
|
+
- Arquitetura: `docs/architecture/FORJA-2.0-ARCHITECTURE.md`
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# ADR-0037: Policy Engine obrigatório e default deny
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-07-31
|
|
5
|
+
- **Autor(es)**: ForjaJS
|
|
6
|
+
- **Tags**: security, policy, autonomy, approvals
|
|
7
|
+
|
|
8
|
+
## Contexto
|
|
9
|
+
|
|
10
|
+
Capabilities podem ler, escrever, executar comandos, acessar rede ou afetar um deployment. Uma
|
|
11
|
+
autonomia sem decisão centralizada permite que cada adapter invente suas próprias permissões.
|
|
12
|
+
|
|
13
|
+
## Decisão
|
|
14
|
+
|
|
15
|
+
Toda execução recebe uma porta de Policy Engine. O engine aplica regras determinísticas por
|
|
16
|
+
identidade, papel, capability, projeto, ambiente, risco, categoria e escopo de arquivos. Sem
|
|
17
|
+
regra correspondente, o resultado é `DENY`. Empates têm precedência `DENY`, `REQUIRE_APPROVAL`,
|
|
18
|
+
`ALLOW_WITH_LIMITS`, `ALLOW`. Risco crítico exige aprovação explícita mesmo quando uma regra permite
|
|
19
|
+
a ação. Limites retornados pela política devem ser impostos pelo Runtime.
|
|
20
|
+
|
|
21
|
+
Approval requests são contratos auditáveis; o primeiro ledger é em memória e será substituído por
|
|
22
|
+
adapter persistente sem mudar o domínio.
|
|
23
|
+
|
|
24
|
+
## Rastreamento
|
|
25
|
+
|
|
26
|
+
- Implementação: `packages/policy/src/index.ts`
|
|
27
|
+
- Testes: `test/policy.test.js`, `test/policy-registry.integration.test.js`
|
|
28
|
+
- Relacionadas: ADR-0035, ADR-0036
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# ADR-0038: Runtime controlado por estados, limites e validação independente
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-07-31
|
|
5
|
+
- **Autor(es)**: ForjaJS
|
|
6
|
+
- **Tags**: runtime, autonomy, checkpoint, validation
|
|
7
|
+
|
|
8
|
+
## Contexto
|
|
9
|
+
|
|
10
|
+
Um agente não pode ser considerado concluído apenas porque um handler terminou. Execuções longas
|
|
11
|
+
precisam ser pausáveis, limitadas, retomáveis e validadas por uma fonte independente.
|
|
12
|
+
|
|
13
|
+
## Decisão
|
|
14
|
+
|
|
15
|
+
`packages/runtime` coordena planner → capabilities autorizadas → checkpoint → validator. Cada run
|
|
16
|
+
possui estado explícito, orçamento, limites de passos/tokens/arquivos/tempo/retries, métricas,
|
|
17
|
+
erros e evidências. A implementação inicial é sequencial e limita concorrência a uma capability
|
|
18
|
+
por vez. `DENY` e aprovação pendente bloqueiam; falhas retryable podem repetir até o limite;
|
|
19
|
+
validação rejeitada nunca produz `completed`.
|
|
20
|
+
|
|
21
|
+
Planner, validator, checkpoint e memória são portas. O primeiro armazenamento é em memória; SQLite
|
|
22
|
+
será um adapter posterior.
|
|
23
|
+
|
|
24
|
+
## Rastreamento
|
|
25
|
+
|
|
26
|
+
- Implementação: `packages/runtime/src/index.ts`
|
|
27
|
+
- Testes: `test/runtime.test.js`
|
|
28
|
+
- Relacionadas: ADR-0035, ADR-0037
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# ADR-0039: Event Bus append-only e Scheduler determinístico local-first
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-07-31
|
|
5
|
+
- **Autor(es)**: ForjaJS
|
|
6
|
+
- **Tags**: events, scheduler, reliability, local-first
|
|
7
|
+
|
|
8
|
+
## Contexto
|
|
9
|
+
|
|
10
|
+
Execuções, tarefas, aprovações e mudanças do workspace precisam disparar trabalho sem perder
|
|
11
|
+
ordem, repetir efeitos de forma segura ou ocultar falhas de consumidores.
|
|
12
|
+
|
|
13
|
+
## Decisão
|
|
14
|
+
|
|
15
|
+
O Event Bus usa log append-only, sequência por aggregate, chave de idempotência, consumers com
|
|
16
|
+
retry limitado e dead-letter. O Scheduler suporta one-shot, cron UTC de cinco campos, condição e
|
|
17
|
+
evento, com cancelamento, chave de execução por slot/evento, retries e limite de concorrência.
|
|
18
|
+
As portas permitem substituir o armazenamento em memória por SQLite e o relógio por adapter sem
|
|
19
|
+
mover regra de domínio.
|
|
20
|
+
|
|
21
|
+
## Consequências
|
|
22
|
+
|
|
23
|
+
Falhas ficam observáveis e eventos duplicados não reexecutam efeitos concluídos. A implementação
|
|
24
|
+
em memória não sobrevive a processo; persistência, consumer offsets e recovery serão tratados em
|
|
25
|
+
`adapter-sqlite`/worker.
|
|
26
|
+
|
|
27
|
+
## Rastreamento
|
|
28
|
+
|
|
29
|
+
- Implementação: `packages/events/src/index.ts`, `packages/scheduler/src/index.ts`
|
|
30
|
+
- Testes: `test/events-scheduler.test.js`
|
|
31
|
+
- Relacionadas: ADR-0035, ADR-0038
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# ADR-0040: Context Engine determinístico com orçamento e cache por checksum
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-07-31
|
|
5
|
+
- **Autor(es)**: ForjaJS
|
|
6
|
+
- **Tags**: context, tokens, cache, memory
|
|
7
|
+
|
|
8
|
+
## Contexto
|
|
9
|
+
|
|
10
|
+
Enviar memória integral ao agente aumenta custo, repetição e risco de contexto obsoleto. Busca,
|
|
11
|
+
deduplicação, diff e imports são operações determinísticas e não devem depender de LLM.
|
|
12
|
+
|
|
13
|
+
## Decisão
|
|
14
|
+
|
|
15
|
+
O Context Engine recebe candidatos recortados de memória e GraphLoop, exige evidência atual,
|
|
16
|
+
ordena por relevância, deduplica por checksum e seleciona até o orçamento de tokens. O conteúdo
|
|
17
|
+
pode ser omitido no pacote e expandido sob demanda pelo checksum. Cache e métricas são portas e o
|
|
18
|
+
`ContextPackage` registra referências, checksum, tokens selecionados, cache hits e conteúdo não
|
|
19
|
+
utilizado.
|
|
20
|
+
|
|
21
|
+
## Consequências
|
|
22
|
+
|
|
23
|
+
O contexto enviado é menor, auditável e reproduzível. O Engine não lê banco nem arquivos; adapters
|
|
24
|
+
devem produzir candidatos com locators, snippets e evidências. A estimativa atual é bytes UTF-8 / 4,
|
|
25
|
+
compatível com o proxy existente do ForjaJS 1.x.
|
|
26
|
+
|
|
27
|
+
## Rastreamento
|
|
28
|
+
|
|
29
|
+
- Implementação: `packages/context/src/index.ts`
|
|
30
|
+
- Contrato: `packages/contracts/src/index.ts`
|
|
31
|
+
- Testes: `test/context.test.js`
|
|
32
|
+
- Relacionadas: ADR-0003, ADR-0009
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# ADR-0041: GraphLoop verificável separado de CodeGraph
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-07-31
|
|
5
|
+
- **Autor(es)**: ForjaJS
|
|
6
|
+
- **Tags**: graph, memory, evidence, codegraph
|
|
7
|
+
|
|
8
|
+
## Contexto
|
|
9
|
+
|
|
10
|
+
CodeGraph já existe no ForjaJS 1.x como índice de símbolos e blast radius. A 2.0 precisa de um
|
|
11
|
+
grafo de trabalho mais amplo, com projetos, specs, decisões, execuções, evidências e validade
|
|
12
|
+
temporal, sem transformar o domínio em dependente do binário ou MCP do CodeGraph.
|
|
13
|
+
|
|
14
|
+
## Decisão
|
|
15
|
+
|
|
16
|
+
GraphLoop é um domínio separado. Toda aresta exige endpoints existentes e ao menos uma evidência;
|
|
17
|
+
status e validade temporal participam das consultas. O núcleo oferece paths, impacto, contradições,
|
|
18
|
+
agenda e sync incremental por checksum. Extractors determinísticos têm prioridade para imports,
|
|
19
|
+
links Markdown e artefatos do processo. Relações semiestruturadas de LLM só poderão entrar como
|
|
20
|
+
`inferred`/`hypothesis`, com confiança e evidência revisável.
|
|
21
|
+
|
|
22
|
+
## Consequências
|
|
23
|
+
|
|
24
|
+
O grafo pode operar offline e receber fontes diferentes, inclusive CodeGraph, sem acoplamento. O
|
|
25
|
+
primeiro store é em memória; persistência SQLite e extractors de commits/diffs/specs completos
|
|
26
|
+
serão adapters/expansões posteriores.
|
|
27
|
+
|
|
28
|
+
## Rastreamento
|
|
29
|
+
|
|
30
|
+
- Implementação: `packages/graph/src/index.ts`
|
|
31
|
+
- Testes: `test/graph.test.js`
|
|
32
|
+
- Relacionadas: ADR-0017, ADR-0040
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# ADR-0042: Planner determinístico e Validator independente
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-07-31
|
|
5
|
+
- **Autor(es)**: ForjaJS
|
|
6
|
+
- **Tags**: planner, validation, evidence, governance
|
|
7
|
+
|
|
8
|
+
## Contexto
|
|
9
|
+
|
|
10
|
+
O agente que implementa uma tarefa não pode ser a única fonte de plano ou de veredito. O Forja
|
|
11
|
+
precisa transformar objetivos em etapas pequenas e impedir conclusão baseada apenas em declaração
|
|
12
|
+
de sucesso.
|
|
13
|
+
|
|
14
|
+
## Decisão
|
|
15
|
+
|
|
16
|
+
O Planner cria etapas determinísticas com critérios, arquivos permitidos, dependências, risco,
|
|
17
|
+
evidências e orçamento dividido. O Validator recebe o plano e resultados externos de build, testes,
|
|
18
|
+
lint e typecheck, além de critérios, escopo, contradições, blockers e achados de segurança. Ele
|
|
19
|
+
retorna `accepted`, `rejected`, `inconclusive` ou `blocked`; checks ausentes produzem `inconclusive`
|
|
20
|
+
e falhas não podem produzir `accepted`.
|
|
21
|
+
|
|
22
|
+
Planner e Validator não executam comandos nem importam frameworks. Adapters fornecem os resultados
|
|
23
|
+
observáveis.
|
|
24
|
+
|
|
25
|
+
## Rastreamento
|
|
26
|
+
|
|
27
|
+
- Implementação: `packages/planner/src/index.ts`, `packages/validator/src/index.ts`
|
|
28
|
+
- Testes: `test/planner-validator.test.js`
|
|
29
|
+
- Relacionadas: ADR-0038, ADR-0041
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# ADR-0043 — Sprint, Task e Handoff como engines de domínio
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-07-31
|
|
5
|
+
- **Contexto**: O runtime precisa de unidades retomáveis, rastreáveis e pequenas para organizar execução agêntica.
|
|
6
|
+
- **Decisão**: Implementar `SprintEngine`, `TaskEngine` e `HandoffEngine` em `packages/orchestration`, usando `OrchestrationStore`, `CompletionValidator` e `GraphRecorder` como portas. A implementação em memória serve como referência determinística; persistência durável e adapters ficam fora do domínio.
|
|
7
|
+
- **Regras**:
|
|
8
|
+
- Task só pode iniciar em Sprint ativo e suas dependências devem estar concluídas para aparecer em `next`.
|
|
9
|
+
- Task e Sprint não podem ser concluídos sem validação independente com status `accepted`.
|
|
10
|
+
- Handoff é um resumo estruturado, com evidências obrigatórias, deduplicação e limites de compactação; transcrições completas não são aceitas.
|
|
11
|
+
- Atualizações do GraphLoop recebem relações e evidências por uma porta, sem importar o pacote GraphLoop.
|
|
12
|
+
- **Alternativas rejeitadas**:
|
|
13
|
+
- Persistir diretamente em SQLite: violaria a independência do domínio e anteciparia o adapter.
|
|
14
|
+
- Permitir que o executor declare conclusão: permitiria falsa conclusão sem gate de validação.
|
|
15
|
+
- **Consequências**: Os adapters futuros devem implementar `OrchestrationStore`, e o GraphLoop deve consumir os registros de `GraphRecorder`. A API de validação permanece explícita para permitir testes e validators independentes.
|
|
16
|
+
- **Evidências**: `test/orchestration.test.js`; `npm run types:check`; `git diff --check`.
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# ADR-0044 — Sandbox por worktree com promoção explícita
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-07-31
|
|
5
|
+
- **Contexto**: Execuções agênticas precisam de isolamento, diff auditável, validação independente e descarte seguro antes de afetar o workspace principal.
|
|
6
|
+
- **Decisão**: `packages/sandbox` implementa o ciclo de sessão por portas. A implementação inicial de backend é Git worktree em `packages/adapter-git`, usando `CommandRunner` e `PatchApplier` injetados.
|
|
7
|
+
- **Regras**:
|
|
8
|
+
- uma sessão só executa após `prepare`;
|
|
9
|
+
- `validate` deve retornar `accepted` para habilitar `diff` e `promote`;
|
|
10
|
+
- `promote` exige diff com o mesmo `sessionId` e checksum não vazio;
|
|
11
|
+
- rejeição e destruição são operações explícitas e auditáveis;
|
|
12
|
+
- o domínio não importa Git, filesystem, subprocessos ou Docker;
|
|
13
|
+
- comandos e aplicação de patch pertencem ao adapter e devem passar por policy na camada de aplicação.
|
|
14
|
+
- **Alternativas rejeitadas**:
|
|
15
|
+
- executar diretamente no workspace: elimina isolamento e dificulta rollback;
|
|
16
|
+
- promoção automática após comando bem-sucedido: sucesso do processo não é validação do resultado;
|
|
17
|
+
- acoplar o domínio a `child_process`: inviabiliza backend substituível e testes determinísticos.
|
|
18
|
+
- **Consequências**: O adapter SQLite deverá persistir sessões, execuções e diffs; a camada de aplicação deverá autorizar operações críticas antes de chamar promoção ou destruição forçada.
|
|
19
|
+
- **Evidências**: `test/sandbox.test.js`, `test/adapter-git.test.js`, `npm run types:check`, `git diff --check`.
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# ADR-0045 — Adapter SQLite por porta e migrações idempotentes
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-07-31
|
|
5
|
+
- **Contexto**: O ForjaJS precisa sobreviver a reinícios e manter eventos, checkpoints, sessões, entidades de sprint e trilha de auditoria em execução local/offline.
|
|
6
|
+
- **Decisão**: `packages/adapter-sqlite` expõe uma interface mínima `SqliteConnection`, um runner de migrações versionadas e repositórios específicos sobre uma tabela de registros JSON, uma tabela append-only de eventos e uma tabela de auditoria.
|
|
7
|
+
- **Regras**:
|
|
8
|
+
- migrações são ordenadas por versão e reaplicação é no-op;
|
|
9
|
+
- eventos têm `idempotency_key` único e não são sobrescritos;
|
|
10
|
+
- domínio não importa `better-sqlite3` nem conhece SQL;
|
|
11
|
+
- serialização JSON é responsabilidade do adapter;
|
|
12
|
+
- restauração de checkpoint é indexada por `runId`;
|
|
13
|
+
- a migração não remove tabelas ou dados existentes.
|
|
14
|
+
- **Alternativas rejeitadas**:
|
|
15
|
+
- importar `better-sqlite3` em cada pacote de domínio: criaria acoplamento ao driver nativo;
|
|
16
|
+
- criar uma tabela específica para cada entidade nesta primeira fatia: aumentaria o custo de migração antes de estabilizar os contratos;
|
|
17
|
+
- usar apenas memória: perderia retomada e auditoria após reinício.
|
|
18
|
+
- **Consequências**: O adapter de composição deve executar `SqliteMigrationRunner` na inicialização. A evolução de schemas JSON exigirá validação e migração explícita quando os contratos estabilizarem.
|
|
19
|
+
- **Evidências**: `test/adapter-sqlite.test.js`, `npm run types:check`, `git diff --check`.
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
# ADR-0046 — MCP como adaptador fino sobre o núcleo
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-07-31
|
|
5
|
+
- **Contexto**: Agentes precisam consumir capabilities, contexto, grafo, tarefas e handoffs por MCP sem criar uma segunda implementação de domínio.
|
|
6
|
+
- **Decisão**: `packages/mcp` expõe `McpServer`, definições de tools, recursos oficiais e resultados estruturados. O servidor delega a portas e engines existentes, transportando identidade, política e contratos versionados.
|
|
7
|
+
- **Regras**:
|
|
8
|
+
- Registry continua sendo a fonte única de execução de capabilities;
|
|
9
|
+
- input é validado antes do dispatch e erros são normalizados;
|
|
10
|
+
- ações mutáveis do MCP passam por `McpPolicy`;
|
|
11
|
+
- recursos são providers externos e ausência de provider não gera conteúdo fictício;
|
|
12
|
+
- o pacote não importa SDK específico de MCP, NestJS, HTTP ou banco nesta fatia.
|
|
13
|
+
- **Alternativas rejeitadas**:
|
|
14
|
+
- lógica de negócio dentro de handlers MCP: duplicaria regras e dificultaria CLI/SDK/API consistentes;
|
|
15
|
+
- recurso MCP com snapshot inventado: produziria contexto sem evidência;
|
|
16
|
+
- executar capability diretamente no MCP: bypassaria Registry e Policy.
|
|
17
|
+
- **Consequências**: Um adapter de transporte MCP poderá converter `McpServer` para o protocolo oficial; o núcleo permanece testável sem servidor externo.
|
|
18
|
+
- **Evidências**: `test/mcp.test.js`, `npm run types:check`, `git diff --check`.
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# ADR-0047 — Backend Nest como composição externa do núcleo
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-07-31
|
|
5
|
+
- **Contexto**: O ForjaJS precisa de uma distribuição oficial HTTP em NestJS sem mover regras de domínio para controllers, guards ou decorators.
|
|
6
|
+
- **Decisão**: `packages/adapter-nest` define a fronteira REST/SSE, autenticação por porta, correlation IDs, erros normalizados, módulos e OpenAPI. `apps/server` compõe essa fronteira e será o bootstrap Nest oficial quando as dependências do framework forem instaladas.
|
|
7
|
+
- **Regras**:
|
|
8
|
+
- chamadas delegam ao `McpServer`/application ports e não implementam domínio;
|
|
9
|
+
- Policy e identidade permanecem no Registry/MCP/application layer;
|
|
10
|
+
- REST é a interface inicial e SSE é o canal de eventos;
|
|
11
|
+
- WebSocket permanece adiado;
|
|
12
|
+
- autenticação local é uma porta substituível;
|
|
13
|
+
- controllers Nest, guards e Swagger ficam na camada externa.
|
|
14
|
+
- **Alternativas rejeitadas**:
|
|
15
|
+
- importar NestJS no domínio: viola a direção de dependências;
|
|
16
|
+
- implementar autorização apenas em controllers: permitiria bypass por MCP/CLI;
|
|
17
|
+
- exigir WebSocket nesta fase: não há requisito verificável além de SSE.
|
|
18
|
+
- **Consequências**: O backend oficial adiciona dependências Nest no root e usa compilação TypeScript antes da execução. O adapter-neutral continua testável sem servidor.
|
|
19
|
+
- **Evidências**: `apps/server/src/main.ts`, `apps/server/src/app.module.ts`, `test/adapter-nest.test.js`, `npm run types:check`, `npm run build`, smoke test `nest-bootstrap-ok`.
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
# ADR-0048 — SDK sobre transporte substituível
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-07-31
|
|
5
|
+
- **Contexto**: CLI, agentes e plugins precisam consumir a plataforma sem depender de NestJS, Express ou de uma biblioteca HTTP específica.
|
|
6
|
+
- **Decisão**: `packages/sdk` expõe `ForjaSdk` sobre `SdkTransport`, com métodos tipados para capabilities, contexto, GraphLoop, orquestração, runtime, approvals, métricas e eventos.
|
|
7
|
+
- **Regras**:
|
|
8
|
+
- transporte injeta headers de token e correlation ID;
|
|
9
|
+
- respostas não-2xx geram `SdkError` estruturado;
|
|
10
|
+
- eventos são opcionais e falham explicitamente quando o transporte não suporta subscription;
|
|
11
|
+
- tipos de domínio vêm de `packages/contracts`;
|
|
12
|
+
- o SDK não executa regra de negócio nem replica Policy.
|
|
13
|
+
- **Alternativas rejeitadas**:
|
|
14
|
+
- acoplar diretamente a `fetch`: dificultaria CLI offline, testes e futuros transports;
|
|
15
|
+
- retornar `unknown` para toda a API: perderia o benefício dos contratos tipados;
|
|
16
|
+
- esconder erros HTTP: impediria governança e retry consciente.
|
|
17
|
+
- **Consequências**: O Control Plane deve implementar as rotas de runtime, approvals, métricas e CRUD de Sprint/Task para completar a superfície do SDK.
|
|
18
|
+
- **Evidências**: `packages/sdk/src/index.ts`, `test/sdk.test.js`, `npm run types:check`, `npm run build`.
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
# ADR-0049 — Observabilidade como fonte do Control Plane
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-07-31
|
|
5
|
+
- **Contexto**: Autonomia supervisionada exige medir execução, contexto, custo, validação, retrabalho e evidência por várias dimensões operacionais.
|
|
6
|
+
- **Decisão**: `packages/observability` registra `Observation` estruturada e calcula `ControlPlaneMetrics`. `SqliteObservationStore` fornece persistência local e `ControlPlanePort` expõe consultas ao adapter HTTP.
|
|
7
|
+
- **Regras**:
|
|
8
|
+
- cada observação tem `traceId`, outcome e campos de custo/tempo/tokens;
|
|
9
|
+
- cobertura de evidência é calculada a partir de refs de contexto ou checksum de entrada;
|
|
10
|
+
- agregação não vive em controller, dashboard ou SDK;
|
|
11
|
+
- observações são append-only no store lógico;
|
|
12
|
+
- métricas vazias retornam zeros, não `NaN`.
|
|
13
|
+
- **Alternativas rejeitadas**:
|
|
14
|
+
- métricas apenas em logs: dificulta consulta estruturada e avaliação;
|
|
15
|
+
- custo apenas por modelo: perde relação com task, capability e run;
|
|
16
|
+
- observabilidade apenas no dashboard: quebra operação CLI/offline.
|
|
17
|
+
- **Consequências**: O Control Plane deve receber eventos do Runtime, Registry, Context e Validator. Rotas de runtime, approvals e CRUD de Sprint/Task ainda precisam de application services.
|
|
18
|
+
- **Evidências**: `packages/observability/src/index.ts`, `packages/adapter-sqlite/src/index.ts`, `test/observability.test.js`, `npm run types:check`, `npm run build`.
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
# ADR-0050 — Control Plane por portas de aplicação
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-07-31
|
|
5
|
+
- **Contexto**: Rotas HTTP precisam coordenar Runtime, Orchestration, Approvals e Observabilidade sem transferir composição ou regras para controllers.
|
|
6
|
+
- **Decisão**: `ControlPlanePort` expõe operações opcionais por portas de aplicação. `ControlPlane` delega para serviços configurados, publica observações/eventos e falha explicitamente quando uma composição não existe. O bootstrap oficial compõe Sprint/Task/Handoff e ApprovalLedger reais.
|
|
7
|
+
- **Regras**:
|
|
8
|
+
- ausência de serviço retorna erro estruturado, nunca sucesso vazio;
|
|
9
|
+
- controllers somente transportam request/response;
|
|
10
|
+
- eventos SSE derivam de eventos do Control Plane;
|
|
11
|
+
- Runtime só será habilitado com planner, validator e Policy reais;
|
|
12
|
+
- operações críticas permanecem sujeitas ao Policy Engine.
|
|
13
|
+
- **Alternativas rejeitadas**:
|
|
14
|
+
- planner vazio para “habilitar” Runtime: permitiria conclusão falsa;
|
|
15
|
+
- regras de transição no controller: duplicaria Orchestration;
|
|
16
|
+
- polling obrigatório para observabilidade: perde atualização operacional e aumenta custo.
|
|
17
|
+
- **Consequências**: Sprint/Task/Handoff/Approvals estão compostos no servidor. Runtime ainda requer uma aplicação específica que converta entrada HTTP em `RuntimeStartRequest` seguro.
|
|
18
|
+
- **Evidências**: `apps/server/src/main.ts`, `packages/observability/src/index.ts`, `packages/adapter-nest/src/index.ts`, `test/adapter-nest.test.js`, `npm run build`, smoke `control-plane-bootstrap-ok`.
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
# ADR-0051 — Runtime seguro no Control Plane
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-07-31
|
|
5
|
+
- **Contexto**: O backend precisava expor Runtime sem aceitar um executor vazio ou permitir que uma capability bypassasse Policy, budget e validação.
|
|
6
|
+
- **Decisão**: O bootstrap compõe `RuntimeEngine` com etapas de capability explícitas na requisição, planner determinístico, PolicyEngine com allowlist `read` em ambiente local, budget validado e validator independente que exige todos os resultados sucedidos com evidência.
|
|
7
|
+
- **Regras**:
|
|
8
|
+
- Runtime exige ao menos uma etapa, objective, agent e TokenBudget válido;
|
|
9
|
+
- categorias, arquivos, ambiente, approval e budget são transportados ao Registry;
|
|
10
|
+
- ausência de capability ou Policy bloqueia/falha a execução;
|
|
11
|
+
- conclusão só ocorre após validator independente;
|
|
12
|
+
- cada operação de Control Plane gera Observation e evento SSE.
|
|
13
|
+
- **Alternativas rejeitadas**:
|
|
14
|
+
- planner vazio: faria runs sem trabalho verificável;
|
|
15
|
+
- permitir escrita por padrão: violaria autonomia supervisionada;
|
|
16
|
+
- considerar handler bem-sucedido como conclusão: ignoraria validação e evidência.
|
|
17
|
+
- **Consequências**: O servidor local consegue executar fluxos read-only determinísticos. Capabilities de escrita exigirão regras/políticas explícitas e approval adequado.
|
|
18
|
+
- **Evidências**: `apps/server/src/main.ts`, `packages/runtime/src/index.ts`, `test/runtime.test.js`, smoke `runtime-control-plane-ok completed accepted 2`, `npm run types:check`, `npm run build`.
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# ADR-0052 — Evaluation Engine determinístico sobre observações
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-07-31
|
|
5
|
+
- **Contexto**: Métricas de qualidade e custo não podem depender de declaração do agente nem de LLM.
|
|
6
|
+
- **Decisão**: `@forja/evals` recebe `ObservationStore` ou uma coleção explícita e produz `EvaluationReport` versionado. Sucesso, retrabalho/cache, tokens por task, etapas sem atividade, ausência de evidência, rollback e uso de contexto são calculados por regras determinísticas.
|
|
7
|
+
- **Regras**:
|
|
8
|
+
- hash de entrada repetido conta como repetição/cache hit observável;
|
|
9
|
+
- tokens por task usam tarefas distintas presentes nas observações;
|
|
10
|
+
- ausência simultânea de `contextRefs` e `inputHash` é sinalizada como afirmação sem evidência;
|
|
11
|
+
- rollback é identificado por `errorCode=ROLLBACK` e não inferido de texto livre;
|
|
12
|
+
- relatório mantém IDs das observações como evidência.
|
|
13
|
+
- **Alternativas rejeitadas**: LLM para classificar sucesso; custo calculado sem observação; relatório sem referências auditáveis.
|
|
14
|
+
- **Consequências**: Resultados são reproduzíveis e offline. Métricas que exigirem semântica adicional devem ganhar campo contratual explícito, não heurística silenciosa.
|
|
15
|
+
- **Evidências**: `packages/evals/src/index.ts`, `packages/contracts/src/index.ts`, `test/evals.test.js`, `npm run types:check`, `npm run build`.
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# ADR-0053 — Plugin SDK com permissões declaradas
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-07-31
|
|
5
|
+
- **Contexto**: Extensões precisam consumir o Forja sem receber acesso implícito ao processo, filesystem, banco ou capabilities não autorizadas.
|
|
6
|
+
- **Decisão**: `@forja/plugin-sdk` registra manifestos validados e entrega ao plugin somente um `PluginContext` composto por serviços externos. Cada método verifica uma permissão declarada antes de acessar a porta correspondente.
|
|
7
|
+
- **Regras**:
|
|
8
|
+
- manifesto exige id, versão e compatibilidade do core;
|
|
9
|
+
- permissões e capabilities declaradas devem ser únicas;
|
|
10
|
+
- plugins com ID já registrado são rejeitados;
|
|
11
|
+
- serviço ausente ou permissão ausente falha explicitamente;
|
|
12
|
+
- falha no setup remove o registro parcial;
|
|
13
|
+
- o SDK não oferece acesso direto a recursos do host.
|
|
14
|
+
- **Alternativas rejeitadas**: entregar um objeto host irrestrito; confiar apenas em convenção documental; permitir mutação de manifesto após registro.
|
|
15
|
+
- **Consequências**: A composição do host permanece substituível e testável. Assinatura, migrations e extensões de dashboard ficam como metadados até haver política de instalação correspondente.
|
|
16
|
+
- **Evidências**: `packages/plugin-sdk/src/index.ts`, `test/plugin-sdk.test.js`, `npm run types:check`, `npm run build`.
|