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.
Files changed (126) hide show
  1. package/CHANGELOG.md +49 -0
  2. package/README.md +223 -217
  3. package/README.pt-BR.md +323 -0
  4. package/dist/apps/dashboard/app/api/forja/[...path]/route.d.ts +10 -0
  5. package/dist/apps/dashboard/app/api/forja/[...path]/route.js +36 -0
  6. package/dist/apps/dashboard/app/api/forja/approval.d.ts +1 -0
  7. package/dist/apps/dashboard/app/api/forja/approval.js +8 -0
  8. package/dist/apps/dashboard/app/dashboard-client.d.ts +1 -0
  9. package/dist/apps/dashboard/app/dashboard-client.jsx +62 -0
  10. package/dist/apps/dashboard/app/layout.d.ts +9 -0
  11. package/dist/apps/dashboard/app/layout.jsx +7 -0
  12. package/dist/apps/dashboard/app/page.d.ts +1 -0
  13. package/dist/apps/dashboard/app/page.jsx +5 -0
  14. package/dist/apps/dashboard/app/providers.d.ts +4 -0
  15. package/dist/apps/dashboard/app/providers.jsx +7 -0
  16. package/dist/apps/dashboard/next.config.d.mts +6 -0
  17. package/dist/apps/dashboard/next.config.mjs +8 -0
  18. package/dist/apps/dashboard/src/index.d.ts +14 -0
  19. package/dist/apps/dashboard/src/index.js +16 -0
  20. package/dist/apps/server/src/app.module.d.ts +5 -0
  21. package/dist/apps/server/src/app.module.js +16 -0
  22. package/dist/apps/server/src/forja-nest.module.d.ts +59 -0
  23. package/dist/apps/server/src/forja-nest.module.js +316 -0
  24. package/dist/apps/server/src/index.d.ts +15 -0
  25. package/dist/apps/server/src/index.js +7 -0
  26. package/dist/apps/server/src/main.d.ts +12 -0
  27. package/dist/apps/server/src/main.js +105 -0
  28. package/dist/apps/worker/src/main.d.ts +12 -0
  29. package/dist/apps/worker/src/main.js +18 -0
  30. package/dist/lib/core/health.js +26 -4
  31. package/dist/packages/adapter-git/src/index.d.ts +27 -0
  32. package/dist/packages/adapter-git/src/index.js +53 -0
  33. package/dist/packages/adapter-nest/src/index.d.ts +71 -0
  34. package/dist/packages/adapter-nest/src/index.js +142 -0
  35. package/dist/packages/adapter-sqlite/src/index.d.ts +99 -0
  36. package/dist/packages/adapter-sqlite/src/index.js +108 -0
  37. package/dist/packages/context/src/index.d.ts +52 -0
  38. package/dist/packages/context/src/index.js +108 -0
  39. package/dist/packages/contracts/src/index.d.ts +368 -0
  40. package/dist/packages/contracts/src/index.js +27 -0
  41. package/dist/packages/core/src/index.d.ts +68 -0
  42. package/dist/packages/core/src/index.js +141 -0
  43. package/dist/packages/evals/src/index.d.ts +22 -0
  44. package/dist/packages/evals/src/index.js +65 -0
  45. package/dist/packages/events/src/index.d.ts +47 -0
  46. package/dist/packages/events/src/index.js +96 -0
  47. package/dist/packages/graph/src/index.d.ts +80 -0
  48. package/dist/packages/graph/src/index.js +163 -0
  49. package/dist/packages/mcp/src/index.d.ts +119 -0
  50. package/dist/packages/mcp/src/index.js +153 -0
  51. package/dist/packages/observability/src/index.d.ts +132 -0
  52. package/dist/packages/observability/src/index.js +86 -0
  53. package/dist/packages/orchestration/src/index.d.ts +122 -0
  54. package/dist/packages/orchestration/src/index.js +178 -0
  55. package/dist/packages/planner/src/index.d.ts +22 -0
  56. package/dist/packages/planner/src/index.js +70 -0
  57. package/dist/packages/plugin-sdk/src/index.d.ts +56 -0
  58. package/dist/packages/plugin-sdk/src/index.js +55 -0
  59. package/dist/packages/policy/src/index.d.ts +80 -0
  60. package/dist/packages/policy/src/index.js +136 -0
  61. package/dist/packages/runtime/src/index.d.ts +91 -0
  62. package/dist/packages/runtime/src/index.js +217 -0
  63. package/dist/packages/sandbox/src/index.d.ts +64 -0
  64. package/dist/packages/sandbox/src/index.js +108 -0
  65. package/dist/packages/scheduler/src/index.d.ts +56 -0
  66. package/dist/packages/scheduler/src/index.js +123 -0
  67. package/dist/packages/sdk/src/index.d.ts +122 -0
  68. package/dist/packages/sdk/src/index.js +40 -0
  69. package/dist/packages/validator/src/index.d.ts +36 -0
  70. package/dist/packages/validator/src/index.js +60 -0
  71. package/docs/architecture/FORJA-2.0-ARCHITECTURE.md +109 -0
  72. package/docs/architecture/FORJA-2.0-IMPACT-FOUNDATION.md +273 -0
  73. package/docs/security/FORJA-2.0-RELEASE-AUDIT-2026-08-01.md +95 -0
  74. package/docs/vision/FORJA-2.0-VISION.md +72 -0
  75. package/memory/50-orchestration/handoffs/2026-07-31_architect_foundation-contracts.md +15 -0
  76. package/memory/50-orchestration/handoffs/2026-07-31_backend-nest.md +22 -0
  77. package/memory/50-orchestration/handoffs/2026-07-31_context-engine.md +16 -0
  78. package/memory/50-orchestration/handoffs/2026-07-31_control-plane.md +28 -0
  79. package/memory/50-orchestration/handoffs/2026-07-31_core-capability-registry.md +15 -0
  80. package/memory/50-orchestration/handoffs/2026-07-31_evals-plugin-sdk.md +22 -0
  81. package/memory/50-orchestration/handoffs/2026-07-31_events-scheduler.md +16 -0
  82. package/memory/50-orchestration/handoffs/2026-07-31_graphloop.md +16 -0
  83. package/memory/50-orchestration/handoffs/2026-07-31_mcp.md +21 -0
  84. package/memory/50-orchestration/handoffs/2026-07-31_nest-bootstrap.md +28 -0
  85. package/memory/50-orchestration/handoffs/2026-07-31_next-dashboard.md +22 -0
  86. package/memory/50-orchestration/handoffs/2026-07-31_observability.md +27 -0
  87. package/memory/50-orchestration/handoffs/2026-07-31_orchestration.md +21 -0
  88. package/memory/50-orchestration/handoffs/2026-07-31_planner-validator.md +16 -0
  89. package/memory/50-orchestration/handoffs/2026-07-31_policy-engine.md +14 -0
  90. package/memory/50-orchestration/handoffs/2026-07-31_runtime-control-plane.md +23 -0
  91. package/memory/50-orchestration/handoffs/2026-07-31_runtime-controlado.md +15 -0
  92. package/memory/50-orchestration/handoffs/2026-07-31_sandbox.md +21 -0
  93. package/memory/50-orchestration/handoffs/2026-07-31_sdk.md +27 -0
  94. package/memory/50-orchestration/handoffs/2026-07-31_sqlite-adapter.md +21 -0
  95. package/memory/50-orchestration/handoffs/2026-07-31_worker-dashboard-boundary.md +23 -0
  96. package/memory/50-orchestration/handoffs/2026-08-01_approval-server-identity.md +23 -0
  97. package/memory/50-orchestration/handoffs/2026-08-01_dashboard-auth-query.md +24 -0
  98. package/memory/50-orchestration/handoffs/2026-08-01_graphloop-approvals.md +23 -0
  99. package/memory/90-decisions/0033-doctor-distingue-permissao-de-corrupcao.md +64 -0
  100. package/memory/90-decisions/0034-forja-2-core-e-contratos.md +29 -0
  101. package/memory/90-decisions/0035-forja-2-local-first-e-autonomia.md +23 -0
  102. package/memory/90-decisions/0036-forja-2-capability-registry.md +30 -0
  103. package/memory/90-decisions/0037-forja-2-policy-engine-obrigatorio.md +28 -0
  104. package/memory/90-decisions/0038-forja-2-runtime-controlado.md +28 -0
  105. package/memory/90-decisions/0039-forja-2-event-bus-scheduler-local-first.md +31 -0
  106. package/memory/90-decisions/0040-forja-2-context-engine-budget-cache.md +32 -0
  107. package/memory/90-decisions/0041-forja-2-graphloop-separado-codegraph.md +32 -0
  108. package/memory/90-decisions/0042-forja-2-planner-validator-independentes.md +29 -0
  109. package/memory/90-decisions/0043-forja-2-orchestration-entities.md +16 -0
  110. package/memory/90-decisions/0044-forja-2-sandbox-worktree.md +19 -0
  111. package/memory/90-decisions/0045-forja-2-sqlite-adapter.md +19 -0
  112. package/memory/90-decisions/0046-forja-2-mcp-adapter.md +18 -0
  113. package/memory/90-decisions/0047-forja-2-backend-nest-adapter.md +19 -0
  114. package/memory/90-decisions/0048-forja-2-sdk-transport.md +18 -0
  115. package/memory/90-decisions/0049-forja-2-observability-control-plane.md +18 -0
  116. package/memory/90-decisions/0050-forja-2-control-plane-application-ports.md +18 -0
  117. package/memory/90-decisions/0051-forja-2-runtime-control-plane-composition.md +18 -0
  118. package/memory/90-decisions/0052-forja-2-deterministic-evaluation.md +15 -0
  119. package/memory/90-decisions/0053-forja-2-plugin-sdk-permissionado.md +16 -0
  120. package/memory/90-decisions/0054-forja-2-worker-dashboard-boundary.md +15 -0
  121. package/memory/90-decisions/0055-forja-2-next-dashboard-distribution.md +16 -0
  122. package/memory/90-decisions/0056-forja-2-dashboard-proxy-auth-query.md +16 -0
  123. package/memory/90-decisions/0057-forja-2-graphloop-approvals-dashboard.md +15 -0
  124. package/memory/90-decisions/0058-forja-2-approval-server-identity.md +15 -0
  125. package/package.json +28 -3
  126. package/README.en.md +0 -329
@@ -0,0 +1,122 @@
1
+ import type { AgentIdentity, ApprovalRequest, CapabilityDefinition, CapabilityId, ContextPackage, EntityId, ExecutionResult, Handoff, RuntimeRun, Sprint, Task, TokenBudget } from '../../contracts/src/index.ts';
2
+ import type { GraphQuery } from '../../graph/src/index.ts';
3
+ export interface SdkRequest {
4
+ readonly method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
5
+ readonly path: string;
6
+ readonly query?: Readonly<Record<string, string | number | undefined>>;
7
+ readonly body?: unknown;
8
+ readonly headers?: Readonly<Record<string, string>>;
9
+ }
10
+ export interface SdkResponse {
11
+ readonly status: number;
12
+ readonly headers: Readonly<Record<string, string | undefined>>;
13
+ readonly body: unknown;
14
+ }
15
+ export interface SdkTransport {
16
+ request(input: SdkRequest): SdkResponse | Promise<SdkResponse>;
17
+ subscribe?(listener: (event: SdkEvent) => void): () => void;
18
+ }
19
+ export interface SdkEvent {
20
+ readonly id: string;
21
+ readonly type: string;
22
+ readonly data: unknown;
23
+ readonly correlationId?: string;
24
+ }
25
+ export interface ExecuteCapabilityOptions {
26
+ readonly categories?: readonly string[];
27
+ readonly files?: readonly string[];
28
+ readonly budget?: TokenBudget;
29
+ readonly projectId?: string;
30
+ readonly environment?: string;
31
+ readonly correlationId?: string;
32
+ }
33
+ export interface CreateSprintRequest {
34
+ readonly objective: string;
35
+ readonly includedScope: readonly string[];
36
+ readonly excludedScope: readonly string[];
37
+ readonly budget: TokenBudget;
38
+ readonly completionCriteria: readonly string[];
39
+ readonly risks: readonly string[];
40
+ readonly evidenceIds: readonly EntityId[];
41
+ readonly correlationId?: string;
42
+ }
43
+ export interface CreateTaskRequest {
44
+ readonly sprintId: EntityId;
45
+ readonly objective: string;
46
+ readonly acceptanceCriteria: readonly string[];
47
+ readonly allowedFiles: readonly string[];
48
+ readonly dependencyIds: readonly EntityId[];
49
+ readonly evidenceIds: readonly EntityId[];
50
+ readonly budget: TokenBudget;
51
+ readonly correlationId?: string;
52
+ }
53
+ export interface CreateHandoffRequest {
54
+ readonly from: string;
55
+ readonly to: string;
56
+ readonly intent: string;
57
+ readonly objective: string;
58
+ readonly completedWork: readonly string[];
59
+ readonly decisions: readonly string[];
60
+ readonly constraints: readonly string[];
61
+ readonly pending: readonly string[];
62
+ readonly evidenceIds: readonly EntityId[];
63
+ readonly acceptance: readonly string[];
64
+ readonly blockers: readonly string[];
65
+ readonly nextAgent: string;
66
+ readonly correlationId?: string;
67
+ }
68
+ export interface StartRuntimeRequest {
69
+ readonly objective: string;
70
+ readonly agent: AgentIdentity;
71
+ readonly budget: TokenBudget;
72
+ readonly steps: readonly {
73
+ readonly capabilityId: CapabilityId;
74
+ readonly payload: unknown;
75
+ readonly estimatedTokens: number;
76
+ readonly files?: readonly string[];
77
+ readonly categories?: readonly string[];
78
+ readonly environment?: string;
79
+ }[];
80
+ readonly sprintId?: EntityId;
81
+ readonly taskId?: EntityId;
82
+ readonly correlationId?: string;
83
+ }
84
+ export declare class SdkError extends Error {
85
+ readonly status: number;
86
+ readonly body: unknown;
87
+ constructor(message: string, status: number, body: unknown);
88
+ }
89
+ export declare class ForjaSdk {
90
+ private readonly transport;
91
+ private readonly defaultHeaders;
92
+ constructor(transport: SdkTransport, options?: {
93
+ readonly token?: string;
94
+ readonly correlationId?: string;
95
+ });
96
+ workspaceStatus(): Promise<unknown>;
97
+ listCapabilities(): Promise<readonly CapabilityDefinition[]>;
98
+ executeCapability(capabilityId: CapabilityId, payload: unknown, options?: ExecuteCapabilityOptions): Promise<ExecutionResult>;
99
+ buildContext(input: {
100
+ readonly objective: string;
101
+ readonly budget: TokenBudget;
102
+ readonly includeContent?: boolean;
103
+ readonly maxItems?: number;
104
+ }): Promise<ContextPackage>;
105
+ graphQuery(query?: GraphQuery): Promise<readonly unknown[]>;
106
+ graphImpact(origin: EntityId, depth?: number, direction?: 'outgoing' | 'incoming' | 'both'): Promise<unknown>;
107
+ nextTask(sprintId: EntityId): Promise<Task | undefined>;
108
+ createSprint(input: CreateSprintRequest): Promise<Sprint>;
109
+ createTask(input: CreateTaskRequest): Promise<Task>;
110
+ createHandoff(input: CreateHandoffRequest): Promise<Handoff>;
111
+ startRuntime(input: StartRuntimeRequest): Promise<RuntimeRun>;
112
+ getRuntime(runId: string): Promise<RuntimeRun>;
113
+ approve(requestId: EntityId, decision: {
114
+ readonly decision: 'approved' | 'rejected';
115
+ readonly approverId: EntityId;
116
+ }): Promise<ApprovalRequest>;
117
+ metrics(): Promise<unknown>;
118
+ subscribeEvents(listener: (event: SdkEvent) => void): () => void;
119
+ private get;
120
+ private post;
121
+ private request;
122
+ }
@@ -0,0 +1,40 @@
1
+ export class SdkError extends Error {
2
+ status;
3
+ body;
4
+ constructor(message, status, body) { super(message); this.name = 'SdkError'; this.status = status; this.body = body; }
5
+ }
6
+ export class ForjaSdk {
7
+ transport;
8
+ defaultHeaders;
9
+ constructor(transport, options = {}) {
10
+ this.transport = transport;
11
+ this.defaultHeaders = { ...(options.token === undefined ? {} : { authorization: `Bearer ${options.token}` }), ...(options.correlationId === undefined ? {} : { 'x-correlation-id': options.correlationId }) };
12
+ }
13
+ workspaceStatus() { return this.get('/api/workspace/status'); }
14
+ listCapabilities() { return this.get('/api/capabilities'); }
15
+ executeCapability(capabilityId, payload, options = {}) { return this.post(`/api/capabilities/${encodeURIComponent(capabilityId)}/execute`, { payload, categories: options.categories ?? [], files: options.files ?? [], ...(options.budget === undefined ? {} : { budget: options.budget }), ...(options.projectId === undefined ? {} : { projectId: options.projectId }), ...(options.environment === undefined ? {} : { environment: options.environment }), ...(options.correlationId === undefined ? {} : { correlationId: options.correlationId }) }); }
16
+ buildContext(input) { return this.post('/api/context/build', input); }
17
+ graphQuery(query = {}) { return this.get('/api/graph/query', { type: query.type, status: query.status, labelIncludes: query.labelIncludes, at: query.at }); }
18
+ graphImpact(origin, depth = 2, direction = 'outgoing') { return this.get('/api/graph/impact', { origin, depth, direction }); }
19
+ nextTask(sprintId) { return this.get('/api/tasks/next', { sprintId }); }
20
+ createSprint(input) { return this.post('/api/sprints', input); }
21
+ createTask(input) { return this.post('/api/tasks', input); }
22
+ createHandoff(input) { return this.post('/api/handoffs', input); }
23
+ startRuntime(input) { return this.post('/api/executions', input); }
24
+ getRuntime(runId) { return this.get(`/api/executions/${encodeURIComponent(runId)}`); }
25
+ approve(requestId, decision) { return this.post(`/api/approvals/${encodeURIComponent(requestId)}/decide`, decision); }
26
+ metrics() { return this.get('/api/control-plane/metrics'); }
27
+ subscribeEvents(listener) {
28
+ if (this.transport.subscribe === undefined)
29
+ throw new SdkError('SDK transport does not support events', 0, undefined);
30
+ return this.transport.subscribe(listener);
31
+ }
32
+ async get(path, query) { return this.request({ method: 'GET', path, query }); }
33
+ async post(path, body) { return this.request({ method: 'POST', path, body }); }
34
+ async request(input) {
35
+ const response = await this.transport.request({ ...input, headers: { ...this.defaultHeaders, ...input.headers } });
36
+ if (response.status < 200 || response.status >= 300)
37
+ throw new SdkError(`Forja API request failed: ${input.method} ${input.path}`, response.status, response.body);
38
+ return response.body;
39
+ }
40
+ }
@@ -0,0 +1,36 @@
1
+ import { type Contradiction, type EntityId, type EvaluationResult, type ExecutionPlan } from '../../contracts/src/index.ts';
2
+ export interface ValidationCheckInput {
3
+ readonly name: string;
4
+ readonly passed: boolean;
5
+ readonly evidenceIds: readonly EntityId[];
6
+ readonly detail?: string;
7
+ }
8
+ export interface AcceptanceResult {
9
+ readonly criterion: string;
10
+ readonly passed: boolean;
11
+ readonly evidenceIds: readonly EntityId[];
12
+ }
13
+ export interface SecurityFinding {
14
+ readonly id: EntityId;
15
+ readonly severity: 'low' | 'medium' | 'high' | 'critical';
16
+ readonly message: string;
17
+ readonly evidenceIds: readonly EntityId[];
18
+ }
19
+ export interface ValidationRequest {
20
+ readonly plan: ExecutionPlan;
21
+ readonly changedFiles: readonly string[];
22
+ readonly checks: readonly ValidationCheckInput[];
23
+ readonly acceptance: readonly AcceptanceResult[];
24
+ readonly contradictions?: readonly Contradiction[];
25
+ readonly securityFindings?: readonly SecurityFinding[];
26
+ readonly blockers?: readonly string[];
27
+ readonly requiredChecks?: readonly string[];
28
+ readonly correlationId?: string;
29
+ }
30
+ export declare class ValidatorError extends Error {
31
+ constructor(message: string);
32
+ }
33
+ export declare class DeterministicValidator {
34
+ validate(request: ValidationRequest): EvaluationResult;
35
+ private summary;
36
+ }
@@ -0,0 +1,60 @@
1
+ import { CONTRACT_VERSION, } from "../../contracts/src/index.js";
2
+ export class ValidatorError extends Error {
3
+ constructor(message) {
4
+ super(message);
5
+ this.name = 'ValidatorError';
6
+ }
7
+ }
8
+ export class DeterministicValidator {
9
+ validate(request) {
10
+ const required = request.requiredChecks ?? ['build', 'tests', 'lint', 'typecheck'];
11
+ const checks = [...request.checks];
12
+ const allowedFiles = request.plan.steps.flatMap((step) => step.allowedFiles);
13
+ const outOfScope = request.changedFiles.filter((file) => !allowedFiles.some((allowed) => allowed === file || allowed === '*' || (allowed.endsWith('/') && file.startsWith(allowed))));
14
+ checks.push({ name: 'scope', passed: outOfScope.length === 0, evidenceIds: [], detail: outOfScope.length === 0 ? 'All changed files are within plan scope' : `Out of scope: ${outOfScope.join(', ')}` });
15
+ const missingChecks = required.filter((name) => !request.checks.some((check) => check.name === name));
16
+ const failedChecks = checks.filter((check) => !check.passed);
17
+ const missingAcceptance = request.plan.steps.flatMap((step) => step.acceptanceCriteria).filter((criterion) => !request.acceptance.some((result) => result.criterion === criterion));
18
+ const failedAcceptance = request.acceptance.filter((result) => !result.passed);
19
+ const contradictions = request.contradictions ?? [];
20
+ const securityFindings = request.securityFindings ?? [];
21
+ const severeSecurity = securityFindings.filter((finding) => finding.severity === 'high' || finding.severity === 'critical');
22
+ const evidenceIds = [...new Set([
23
+ ...checks.flatMap((check) => check.evidenceIds),
24
+ ...request.acceptance.flatMap((result) => result.evidenceIds),
25
+ ...contradictions.flatMap((item) => item.evidenceIds),
26
+ ...securityFindings.flatMap((item) => item.evidenceIds),
27
+ ])];
28
+ let status = 'accepted';
29
+ if ((request.blockers?.length ?? 0) > 0)
30
+ status = 'blocked';
31
+ else if (outOfScope.length > 0 || failedChecks.length > 0 || failedAcceptance.length > 0 || contradictions.length > 0 || severeSecurity.length > 0)
32
+ status = 'rejected';
33
+ else if (missingChecks.length > 0 || missingAcceptance.length > 0)
34
+ status = 'inconclusive';
35
+ const now = new Date().toISOString();
36
+ return {
37
+ schemaVersion: CONTRACT_VERSION,
38
+ createdAt: now,
39
+ updatedAt: now,
40
+ correlationId: request.correlationId ?? request.plan.id,
41
+ status,
42
+ checks: [
43
+ ...checks.map(({ name, passed, evidenceIds }) => ({ name, passed, evidenceIds })),
44
+ { name: 'acceptance', passed: failedAcceptance.length === 0 && missingAcceptance.length === 0, evidenceIds: request.acceptance.flatMap((result) => result.evidenceIds) },
45
+ { name: 'contradictions', passed: contradictions.length === 0, evidenceIds: contradictions.flatMap((item) => item.evidenceIds) },
46
+ { name: 'security', passed: severeSecurity.length === 0, evidenceIds: severeSecurity.flatMap((item) => item.evidenceIds) },
47
+ ],
48
+ summary: this.summary(status, missingChecks, missingAcceptance, outOfScope, evidenceIds.length),
49
+ };
50
+ }
51
+ summary(status, missingChecks, missingAcceptance, outOfScope, evidenceCount) {
52
+ const details = [
53
+ missingChecks.length > 0 ? `missing checks: ${missingChecks.join(', ')}` : '',
54
+ missingAcceptance.length > 0 ? `missing criteria: ${missingAcceptance.join('; ')}` : '',
55
+ outOfScope.length > 0 ? `out of scope: ${outOfScope.join(', ')}` : '',
56
+ `evidence: ${evidenceCount}`,
57
+ ].filter(Boolean);
58
+ return `${status}${details.length > 0 ? ` (${details.join(' | ')})` : ''}`;
59
+ }
60
+ }
@@ -0,0 +1,109 @@
1
+ # ForjaJS 2.0 — Arquitetura de referência
2
+
3
+ ## Direção de dependência
4
+
5
+ ```text
6
+ interfaces externas (CLI, REST/SSE, MCP, SDK, dashboard)
7
+ ↓
8
+ adapters (Nest, SQLite, Git, transporte, filesystem)
9
+ ↓
10
+ application layer (casos de uso, comandos, queries, políticas)
11
+ ↓
12
+ domain core (contratos, invariantes, estados, eventos)
13
+ ```
14
+
15
+ `packages/core`, `contracts`, `policy`, `runtime`, `graph`, `context`, `planner`, `validator`,
16
+ `orchestration` e `events` não importam NestJS, Next.js, Express, Fastify, React ou drivers de
17
+ persistência. Portas são interfaces TypeScript; adapters fazem o binding.
18
+
19
+ ## Containers
20
+
21
+ ```mermaid
22
+ flowchart LR
23
+ CLI[apps/cli] --> APP[Application services]
24
+ API[apps/server / NestJS] --> ADP[adapter-nest]
25
+ MCP[packages/mcp] --> APP
26
+ SDK[packages/sdk] --> API
27
+ ADP --> APP
28
+ APP --> CORE[Domain packages]
29
+ ADP --> SQL[adapter-sqlite]
30
+ ADP --> GIT[adapter-git]
31
+ WORKER[apps/worker] --> APP
32
+ DASH[apps/dashboard / Next.js] --> API
33
+ ```
34
+
35
+ ## Componentes e persistência
36
+
37
+ SQLite é a persistência local padrão para memória, eventos, runs, handoffs e checkpoints.
38
+ Filesystem e Git worktree são usados para artefatos e sandbox. Cada porta de persistência deve
39
+ permitir uma implementação substituível; nenhuma entidade conhece SQL.
40
+
41
+ ## Capability e execução
42
+
43
+ ```mermaid
44
+ sequenceDiagram
45
+ participant I as Interface
46
+ participant R as Registry
47
+ participant P as Policy
48
+ participant A as Application
49
+ participant H as Handler
50
+ participant V as Validator
51
+ I->>R: discover/describe/execute
52
+ R->>R: validate input + version
53
+ R->>P: authorize identity, risk, scope, budget
54
+ P-->>R: ALLOW / LIMITS / APPROVAL / DENY
55
+ R->>A: execute application command
56
+ A->>H: invoke port/handler
57
+ H-->>A: structured result + evidence
58
+ A->>V: validate outcome
59
+ V-->>I: ExecutionResult + audit references
60
+ ```
61
+
62
+ ## Autonomia e GraphLoop
63
+
64
+ ```mermaid
65
+ flowchart TD
66
+ O[observe] --> R[retrieve context/evidence]
67
+ R --> P[plan deterministically first]
68
+ P --> A[authorize by Policy Engine]
69
+ A --> X[execute in sandbox]
70
+ X --> V[validate independently]
71
+ V --> M[remember evidence/events]
72
+ M --> O
73
+ M --> G[GraphLoop incremental update]
74
+ ```
75
+
76
+ GraphLoop mantém nós, arestas, evidências, validade temporal e status (`verified`, `inferred`,
77
+ `hypothesis`, `contradicted`, `unknown`). CodeGraph continua sendo a análise de código do 1.x;
78
+ GraphLoop pode consumir seus resultados, mas não o substitui.
79
+
80
+ ## Processos e falhas
81
+
82
+ O modo padrão é processo separado para worker e server, com SQLite local e jobs persistidos.
83
+ Execuções curtas podem ser síncronas; tarefas longas usam scheduler/worker e checkpoint. REST +
84
+ SSE são a interface oficial inicial. WebSocket fica adiado até existir requisito verificável.
85
+ Retries têm limite e chave idempotente; eventos têm log append-only, consumer offsets e dead
86
+ letter. Cancelamento e retomada são estados explícitos.
87
+
88
+ ## Fluxos de domínio
89
+
90
+ ```mermaid
91
+ flowchart LR
92
+ S[Sprint] --> T[Task]
93
+ T --> H[Handoff]
94
+ H --> R[Runtime run]
95
+ R --> C[Checkpoint]
96
+ R --> V[Validator]
97
+ V --> E[Evidence + events]
98
+ E --> S
99
+ ```
100
+
101
+ Dashboard exibe e solicita comandos; não contém regras de autorização, GraphLoop ou execução.
102
+ Plugins só recebem capabilities e eventos declarados em manifesto permissionado.
103
+
104
+ ## Migração e empacotamento
105
+
106
+ O repositório atual permanece publicável como 1.x enquanto `apps/` e `packages/` são introduzidos
107
+ de forma aditiva. A CLI existente roteia para o novo núcleo por capability quando houver
108
+ equivalente; comandos sem equivalente continuam no caminho legado. Migrações criam backup,
109
+ validam antes de promover e não removem dados por padrão.
@@ -0,0 +1,273 @@
1
+ # Análise de impacto — Fundação ForjaJS 2.0
2
+
3
+ - **Data**: 2026-07-31
4
+ - **Escopo**: visão, arquitetura, contratos públicos e typecheck
5
+ - **Base**: ForjaJS 1.7.3, ADR-0003, ADR-0005, ADR-0019, ADR-0020, ADR-0027
6
+
7
+ ## Contratos afetados
8
+
9
+ | Área | Impacto atual | Decisão nesta fatia |
10
+ | --- | --- | --- |
11
+ | CLI 1.x | Nenhuma API alterada | Mantida como caminho legado |
12
+ | Workspace | Nenhuma alteração de resolução | Mantido conforme ADR-0019 |
13
+ | Memória SQLite | Nenhuma migração | Adapter fica para fase posterior |
14
+ | Handoffs | Nenhuma alteração no router | Contrato 2.0 é aditivo |
15
+ | TypeScript | Novo escopo `packages/**/*` | Typecheck do domínio entra no gate |
16
+ | Publicação npm | Pacotes 2.0 ainda não publicados | Empacotamento será tratado com monorepo |
17
+
18
+ ## Dependências e blast radius
19
+
20
+ O único arquivo existente alterado é `tsconfig.json`, adicionando o diretório de pacotes ao
21
+ typecheck. `lib/`, `scripts/`, `bin/`, registry e CLI não foram alterados. Os novos contratos não
22
+ importam código existente nem dependências externas; portanto não há ciclo ou efeito runtime na
23
+ CLI 1.x.
24
+
25
+ ## Hipóteses
26
+
27
+ - Node 20+ continuará sendo o runtime mínimo do pacote publicado; desenvolvimento pode usar o
28
+ suporte nativo a TypeScript já adotado pelo projeto.
29
+ - `packages/contracts` será a fonte canônica antes de schemas serem derivados para MCP/REST.
30
+ - A escolha de biblioteca de schema (ou implementação própria) permanece aberta; esta fatia usa
31
+ validação determinística mínima sem introduzir dependência.
32
+ - IDs continuarão sendo strings opacas no transporte, representadas por brands no TypeScript.
33
+
34
+ ## Informações ausentes
35
+
36
+ - estratégia final de workspace/package manager;
37
+ - formato de persistência e migrações 2.0;
38
+ - protocolo exato de execução de handlers;
39
+ - biblioteca de schema runtime e biblioteca de testes de integração;
40
+ - política de compatibilidade semântica entre versões de contrato;
41
+ - requisitos de autenticação local do server.
42
+
43
+ ## Riscos
44
+
45
+ - Os contratos ainda não cobrem invariantes de cada bounded context.
46
+ - `unknown` em payloads é intencional nesta etapa, mas cada capability deverá fornecer schema
47
+ específico antes de execução.
48
+ - A existência de apenas dois ADRs 2.0 não fecha a governança completa; ADRs de runtime, policy,
49
+ GraphLoop, sandbox, eventos, adapters e UI ainda precisam ser aprovadas.
50
+
51
+ ## Atualização da unidade Registry (2026-07-31)
52
+
53
+ `packages/core` foi criado com registry em memória, aliases, descoberta filtrada por agente,
54
+ validação de input antes do handler, autorização por uma porta de Policy Engine, suporte a
55
+ handlers síncronos/assíncronos e `ExecutionResult` normalizado. Não há persistência nem adapter.
56
+
57
+ ## Atualização da unidade Policy (2026-07-31)
58
+
59
+ `packages/policy` foi criado com default deny, regras por agente, papel, capability, projeto,
60
+ ambiente, risco, categoria e prefixo de arquivo; precedência determinística; limites; exigência
61
+ de aprovação para risco crítico; e ledger de aprovações em memória. A fronteira Registry → Policy
62
+ foi testada sem acoplamento de pacote: o contexto de execução é transportado por uma porta comum.
63
+
64
+ O ledger não é persistente nesta etapa. O adapter SQLite e a auditoria durável ficam para o
65
+ Runtime Controlado.
66
+
67
+ ## Atualização da unidade Runtime (2026-07-31)
68
+
69
+ `packages/runtime` foi criado com planner, validator, checkpoint store e memory writer como
70
+ portas. O motor controla estados, limites de passos/tokens/arquivos/tempo/retries, execução
71
+ sequencial (`maxParallel=1` nesta primeira implementação), pausa, retomada, cancelamento e
72
+ validação independente. O estado é em memória; a persistência durável permanece pendente.
73
+
74
+ ## Atualização das unidades Events/Scheduler (2026-07-31)
75
+
76
+ `packages/events` fornece log append-only por porta, sequência por aggregate, deduplicação por
77
+ idempotency key, consumidores com retry e dead-letter. `packages/scheduler` fornece one-shot,
78
+ cron UTC de cinco campos, condição, evento, cancelamento, retries, idempotência por slot e limite
79
+ de concorrência. As implementações atuais são determinísticas e em memória; `adapter-sqlite` e a
80
+ integração de relógio/eventos ficam para a camada de adapters.
81
+
82
+ ## Atualização da unidade Context (2026-07-31)
83
+
84
+ `packages/context` consulta memória e GraphLoop por portas, descarta evidência obsoleta ou
85
+ contradita, ordena por relevância, deduplica por checksum, limita itens e tokens, mantém cache
86
+ por checksum e permite expansão sob demanda. `ContextPackage` agora expõe métricas de candidatos,
87
+ seleção, deduplicação, cache, tokens usados e tokens não utilizados. Não há busca SQL, diff ou LLM
88
+ dentro do Engine.
89
+
90
+ ## Atualização da unidade GraphLoop (2026-07-31)
91
+
92
+ `packages/graph` fornece nós, arestas, evidências, status, validade temporal, upsert idempotente,
93
+ paths, impacto, contradições, agenda e sincronização incremental por checksum de fonte. Arestas
94
+ sem endpoints ou evidência são rejeitadas. Imports e links Markdown são extraídos deterministicamente;
95
+ CodeGraph continua separado e pode alimentar mutations por adapter. O store atual é em memória.
96
+
97
+ ## Atualização das unidades Planner/Validator (2026-07-31)
98
+
99
+ `packages/planner` produz planos determinísticos com três etapas mínimas, dependências do grafo,
100
+ evidências de contexto, risco, critérios e orçamento dividido. `packages/validator` verifica
101
+ checks obrigatórios, escopo de arquivos, critérios de aceitação, contradições, blockers e achados
102
+ de segurança, retornando `accepted`, `rejected`, `inconclusive` ou `blocked`. Nenhum dos dois
103
+ executa comandos ou depende do implementador.
104
+
105
+ ## Próxima unidade verificável
106
+
107
+ Criar `packages/orchestration` para Sprint, Task e Handoff, com persistência por porta, estados,
108
+ orçamento, retomada, compactação e atualização do GraphLoop.
109
+
110
+ ## Atualização da unidade Orchestration (2026-07-31)
111
+
112
+ `packages/orchestration` implementa `SprintEngine`, `TaskEngine` e `HandoffEngine` sobre a porta
113
+ `OrchestrationStore`. A implementação de referência é em memória e não conhece SQLite, NestJS ou
114
+ Next.js. Tasks só avançam quando as dependências estão concluídas; conclusões de Task e Sprint
115
+ exigem um `CompletionValidator` independente retornando `accepted`. Handoffs exigem objetivo,
116
+ aceite e evidências, removem itens duplicados e rejeitam seções acima dos limites definidos.
117
+ `GraphRecorder` registra Sprint, Task e Handoff com relações e evidências, deixando a persistência
118
+ do GraphLoop para o adapter apropriado.
119
+
120
+ O contrato de Sprint passou a explicitar `risks`, `taskIds` e `evidenceIds`; Task passou a
121
+ explicitar `evidenceIds`. A alteração é aditiva e permanece compatível com a direção de
122
+ dependências do domínio.
123
+
124
+ ## Atualização da unidade Sandbox (2026-07-31)
125
+
126
+ `packages/sandbox` fornece `SandboxEngine` com ciclo explícito `create → prepare → execute →
127
+ validate → diff → promote/reject → destroy`. O engine depende de `SandboxStore` e
128
+ `SandboxBackend`; não executa subprocessos, não acessa filesystem e não importa Git. Promoção
129
+ exige validação aceita e um diff pertencente à mesma sessão. Falhas de execução levam a estado
130
+ `failed`, e destruição é registrada como estado terminal.
131
+
132
+ `packages/adapter-git` implementa o backend inicial por `CommandRunner` e `PatchApplier`. O
133
+ adapter traduz worktree, status, execução, `git diff --check`, diff numstat/name-only, aplicação
134
+ de patch e remoção de worktree. O adapter não é chamado diretamente pelo domínio e não foi
135
+ executado contra o repositório durante os testes; seus comandos foram verificados com runner
136
+ determinístico.
137
+
138
+ ## Atualização da unidade Adapter SQLite (2026-07-31)
139
+
140
+ `packages/adapter-sqlite` fornece `SqliteConnection`, `SqliteMigrationRunner` e repositórios para
141
+ Orchestration, Sandbox, Checkpoint, Runtime Run, Event Bus e Auditoria. A migração inicial cria
142
+ tabelas de registros JSON, eventos append-only, auditoria e controle de versão. Migrações já
143
+ aplicadas são ignoradas por versão; eventos usam chave de idempotência no SQLite. O adapter não
144
+ é importado pelo domínio e não escolhe o driver: `better-sqlite3` pode ser ligado na composição
145
+ externa por duck typing da conexão.
146
+
147
+ ## Atualização da unidade MCP (2026-07-31)
148
+
149
+ `packages/mcp` implementa `McpServer` como adaptador fino. As ferramentas delegam para Registry,
150
+ Context, GraphLoop, Memory, Task, Handoff e portas de validação/testes; não duplicam regras de
151
+ negócio. A identidade do agente é transportada nas operações de Registry e Policy é aplicada ao
152
+ handoff por `McpPolicy`. Erros são normalizados em resultados estruturados com código, mensagem e
153
+ `isError`.
154
+
155
+ O servidor anuncia os sete URIs oficiais de recursos; dados são fornecidos por providers externos.
156
+ Quando um provider não existe, o recurso informa explicitamente indisponibilidade. Nenhum dado de
157
+ workspace é inventado pelo adapter.
158
+
159
+ ## Atualização da unidade Backend Nest (2026-07-31)
160
+
161
+ `packages/adapter-nest` fornece a fronteira HTTP verificável: rotas REST para health, capabilities,
162
+ contexto, GraphLoop, tasks, handoffs e MCP; correlation IDs; erros HTTP normalizados; SSE por
163
+ `EventStream`; autenticação local por porta; e documento OpenAPI 3.1. `apps/server` compõe essa
164
+ fronteira em `ForjaServerApplication` e expõe os módulos oficiais.
165
+
166
+ NestJS agora está instalado no workspace. `apps/server/src/app.module.ts`,
167
+ `forja-nest.module.ts` e `main.ts` fornecem o módulo dinâmico, controller, guard local, SSE e
168
+ Swagger reais. Como decorators não são executados pelo Node strip-only, o gate do bootstrap é
169
+ `npm run build` seguido de smoke test sobre `dist`; os testes nativos continuam cobrindo o adapter
170
+ sem exigir compilação prévia. Nenhuma regra de domínio foi colocada nessa composição.
171
+
172
+ ## Atualização da unidade SDK (2026-07-31)
173
+
174
+ `packages/sdk` fornece `ForjaSdk` sobre a porta `SdkTransport`, sem importar NestJS, Express ou
175
+ um cliente HTTP concreto. A superfície cobre descoberta e execução de capabilities, contexto,
176
+ GraphLoop, próxima task, Sprint/Task/Handoff, runtime, approvals, métricas e subscription de
177
+ eventos. O SDK preserva headers de autenticação/correlation, serializa queries e transforma
178
+ respostas HTTP não-2xx em `SdkError` com status e corpo.
179
+
180
+ Rotas ainda não expostas pelo controller atual (runtime, approvals, métricas e criação de
181
+ Sprint/Task) permanecem contratos de cliente para a próxima fatia do Control Plane; não foram
182
+ tratadas como implementadas apenas por existirem no SDK.
183
+
184
+ ## Atualização da unidade Observability/Control Plane (2026-07-31)
185
+
186
+ `packages/observability` registra observações por trace, run, agente, task, sprint e capability,
187
+ incluindo hashes de entrada, refs de contexto, tokens, duração, custo, ferramentas, arquivos,
188
+ comandos, validação, outcome e erro. `ControlPlane` calcula métricas de sucesso, bloqueio,
189
+ tokens, duração, custo e cobertura de evidência.
190
+
191
+ `packages/adapter-sqlite` agora fornece `SqliteObservationStore`. `packages/adapter-nest` expõe
192
+ `/api/control-plane/metrics` e `/api/observability/observations` por `ControlPlanePort`; a
193
+ agregação continua fora do controller. Runtime, approvals e CRUD de Sprint/Task ainda exigem
194
+ serviços de aplicação específicos.
195
+
196
+ ## Atualização da unidade Control Plane operacional (2026-07-31)
197
+
198
+ `ControlPlaneServices` agora define portas explícitas para Runtime, Sprint, Task, Handoff e
199
+ Approvals. `apps/server/src/main.ts` compõe as engines reais de Sprint/Task/Handoff e
200
+ `ApprovalLedger`, e `packages/adapter-nest` expõe as rotas de criação/transição/decisão. Eventos
201
+ de observação são convertidos para `InMemoryEventStream` e chegam ao endpoint SSE.
202
+
203
+ Runtime possui rotas e portas, mas continua sem composição padrão no bootstrap porque exige um
204
+ planner, validator e policy executáveis. Um runtime sem capabilities planejadas ou sem validação
205
+ independente seria uma falsa conclusão e permanece bloqueado por decisão arquitetural.
206
+
207
+ ## Atualização da unidade Runtime Control Plane (2026-07-31)
208
+
209
+ `DefaultRuntimeApplication` agora compõe `RuntimeEngine` com planner determinístico baseado em
210
+ etapas explícitas da requisição, validator independente que exige sucesso e evidência em todas as
211
+ etapas, `PolicyEngine` read-only/local e transporte de categorias, arquivos, ambiente e budget
212
+ para o Registry. Runtime expõe start/get/execute/pause/resume/cancel pelo Control Plane.
213
+
214
+ O smoke test executou uma capability `read` em sandbox lógico, terminou `completed/accepted` e
215
+ gerou duas observações de Control Plane. Escritas continuam bloqueadas pela política padrão.
216
+
217
+ ## Atualização da unidade Evaluation Engine e Plugin SDK (2026-07-31)
218
+
219
+ `packages/evals` consome observações do Control Plane e produz `EvaluationReport` versionado com
220
+ taxa de sucesso, retrabalho/cache, tokens por task, etapas sem atividade, ausência de evidência,
221
+ rollback, uso de contexto, tokens e custo. A avaliação não chama LLM e mantém os IDs das
222
+ observações no relatório.
223
+
224
+ `packages/plugin-sdk` define manifesto com permissões, capabilities, eventos, migrations,
225
+ extensões e compatibilidade. `PluginRegistry` rejeita IDs duplicados e entrega um contexto com
226
+ checagem de permissão por operação. O SDK não concede acesso direto a filesystem, processo ou
227
+ persistência; dashboard e migrations permanecem metadados até suas políticas de host existirem.
228
+
229
+ ## Atualização da unidade Worker e Dashboard boundary (2026-07-31)
230
+
231
+ `apps/worker` compõe Event Bus, Scheduler, ObservationStore/Recorder e Evaluation Engine para
232
+ permitir processamento assíncrono determinístico. O worker não recebe executor de capability por
233
+ fora do Runtime/Policy.
234
+
235
+ `apps/dashboard` fornece o view model operacional mínimo: snapshot de métricas/observações e ações
236
+ de pausa, cancelamento e aprovação delegadas ao Control Plane. A casca Next.js/React, Query e SSE
237
+ remoto ainda é pendência explícita; nenhum componente visual foi inventado como se já existisse.
238
+
239
+ ## Atualização da unidade Dashboard Next.js (2026-07-31)
240
+
241
+ `apps/dashboard` agora possui distribuição Next.js/React com App Router, layout, Overview, métricas,
242
+ observações recentes, atualização manual e revalidação por SSE. A tela usa REST para obter o estado
243
+ do Control Plane e não importa persistência, Policy, Runtime ou GraphLoop.
244
+
245
+ O build usa `outputFileTracingRoot` na raiz do monorepo e passou em produção. Autenticação de
246
+ usuário, TanStack Query, filtros/inspeção visual do GraphLoop e comandos de aprovação ainda são
247
+ incrementos pendentes; o dashboard não é considerado completo por esta casca inicial.
248
+
249
+ ## Atualização da unidade Dashboard proxy/auth/query (2026-08-01)
250
+
251
+ O dashboard agora usa TanStack Query para cache e invalidação do snapshot. Um Route Handler
252
+ server-side encaminha somente endpoints allowlisted ao backend; `FORJA_AUTH_TOKEN` não é exposto ao
253
+ cliente. SSE apenas invalida o cache remoto.
254
+
255
+ `createBearerAuthenticator` foi centralizado no adapter Nest com comparação constante e o bootstrap
256
+ usa `FORJA_AUTH_TOKEN` quando definido. O modo sem token continua local/offline, mas implantação
257
+ operacional deve configurar autenticação. A suíte passou serialmente; testes paralelos que alteram
258
+ PATH/processos continuam sujeitos a interferência ambiental.
259
+
260
+ ## Atualização da unidade GraphLoop e Approvals no dashboard (2026-08-01)
261
+
262
+ O adapter Nest agora expõe listagem de approvals e o bootstrap conecta a lista do `ApprovalLedger`.
263
+ O GraphLoop padrão é composto no MCP do servidor, permitindo consulta de nós e impacto sem LLM.
264
+
265
+ O dashboard renderiza os nós retornados, seus status, impacto sob demanda e a fila de approvals.
266
+ Decisões de aprovação permanecem fora desta tela até haver identidade/aprovador configurado;
267
+ nenhuma relação ou decisão é sintetizada no cliente.
268
+
269
+ ## Atualização da unidade Approval server-side (2026-08-01)
270
+
271
+ O dashboard agora permite aprovar/rejeitar somente quando `FORJA_APPROVER_ID` está configurado no
272
+ servidor. O browser envia apenas a decisão; o proxy valida o enum, injeta identidade e timestamp e
273
+ encaminha ao `ApprovalLedger`. Configuração ausente não gera fallback permissivo.