5.2 KiB
5.2 KiB
DAG Orchestration Requirements Matrix (Milestone A)
Related tasks: FN-4487 (mission proposal), FN-4471 (upstream scoping), governance gate FN-4359.
See also: ADR v1 · Failure + Observability Contract
| Capability | Operator need | Engine constraint | Existing Fusion mechanism it must compose with | Milestone A deliverable | Milestone B in-scope? | Out of scope for the mission |
|---|---|---|---|---|---|---|
| DAG definition / authoring | Define a small, explicit graph (nodes, edges, metadata) without replacing current task UX. | Engine is single-event-loop; representation must be lightweight and non-blocking (AGENTS.md Engine Process Rules). |
docs/storage.md; packages/engine/src/scheduler.ts; packages/engine/src/executor.ts; packages/core/src/ai-engine-loader.ts boundary rule. |
ADR section: representation choice + storage boundary. | Yes (minimal prototype graph). | Full visual workflow builder and template marketplace. |
| Node-to-node edges (data + control) | Express dependency sequencing and basic payload handoff semantics between nodes. | Must preserve checkout lease ownership and not bypass task execution flow. | packages/engine/src/scheduler.ts; packages/engine/src/executor.ts; checkout leasing contract in AGENTS.md. |
Requirements matrix mapping + failure contract for unsatisfied edges. | Yes (single dependency edge in prototype). | Arbitrary cross-task artifact buses or shared mutable global state. |
| Conditional branches | Route execution based on node outcome/approvals without custom ad hoc scripts. | Branch evaluation cannot block loop; must fit existing gating and approval patterns. | docs/workflow-steps.md (gateMode); packages/engine/src/agent-heartbeat.ts; packages/engine/src/concurrency.ts. |
ADR semantics: bounded condition model and evaluation timing. | Yes (simple pass/fail branch only). | Full DSL/expression language and nested policy engine. |
| Retry semantics | Operators need bounded retry and clear retry-exhausted outcomes per node/run. | Must not regress reliability layers during FN-4359 freeze. | packages/engine/src/self-healing.ts; packages/engine/src/restart-recovery-coordinator.ts; retry context from FN-4398 (retriesBurned). |
Failure taxonomy + governance section in ADR. | Yes (bounded prototype retries, additive). | Global replay/time-travel and automatic adaptive retry tuning. |
| Partial-failure handling | Continue/abort policy must be explicit when one node fails and others are pending. | Preserve deterministic task terminal states and existing merge gating assumptions. | packages/engine/src/executor.ts; packages/engine/src/merger.ts; workflow pre-merge/post-merge model in docs/workflow-steps.md. |
Failure contract state machine + abort semantics. | Yes. | Cross-DAG compensating transactions and distributed sagas. |
| Cancellation | Support operator/system cancel of a DAG run with auditable state. | Must respect 409 checkout conflict semantics; no auto-retry takeover. | Checkout leasing rules in AGENTS.md; packages/engine/src/executor.ts; packages/engine/src/scheduler.ts. |
Failure contract cancellation section and log vocabulary. | Yes. | Force-cancel across remote nodes with unilateral lease revocation. |
| Observability / log surface | Operators need per-run and per-node lifecycle visibility and reasons for block/fail states. | Must follow structured logger conventions and run-audit linkage. | packages/engine/src/logger.ts; AGENTS.md Engine Diagnostic Logging; Run Audit section. |
Failure + observability contract event schema. | Yes (debug-level telemetry). | Full dashboard productization (deferred to Milestone C). |
| Multi-project / mesh scope | Understand if/when DAG spans projects/nodes and auth boundaries. | Current system is project-scoped with central registry; node APIs require apiKey and explicit routing. | docs/multi-project.md; docs/multi-project-sequencing.md; node sync endpoints in AGENTS.md. |
ADR consequences + explicit scoping constraints. | No (prototype is single-project/single-node). | Cross-node DAG scheduling, multi-tenant routing, global consistency protocol changes. |
| Persistence | DAG run state must survive restart and be reconstructible from DB. | Additive schema only; no destructive migrations; hybrid storage model must remain intact. | docs/storage.md; .fusion/fusion.db contracts; packages/engine/src/restart-recovery-coordinator.ts. |
ADR storage decision + failure contract restart expectations. | Yes. | Event-sourcing rewrite or replacement of current task/blob storage model. |
| Governance / approval gating | Operators need clear policy boundary for what can ship under reliability freeze. | FN-4359 freeze blocks reliability-layer behavior changes absent explicit carve-out. | AGENTS.md Reliability Mechanism Governance; packages/engine/src/self-healing.ts; packages/engine/src/restart-recovery-coordinator.ts; merger file-scope invariant in packages/engine/src/merger.ts. |
ADR Governance section + open questions for Milestone B gate. | Yes (architecture gates only; runtime gated). | Bypassing governance with silent reliability changes or hidden scheduler overrides. |