# DAG Orchestration Requirements Matrix (Milestone A)

Related tasks: **FN-4487** (mission proposal), **FN-4471** (upstream scoping), governance gate **FN-4359**.

See also: [ADR v1](./adr-0001-dag-orchestration.md) · [Failure + Observability Contract](./failure-observability-contract.md)

| 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. |