Design Decision Record

DesignDecisionRecorder runs the design engines for one spec and writes a record with nine sections, as Markdown or JSON.

Run#

Java

import com.eqixiac.equinix.Design;
import com.eqixiac.equinix.design.record.DecisionDelta;
import com.eqixiac.equinix.design.record.DesignDecisionRecord;
import com.eqixiac.equinix.design.spec.DesignSpec;
import com.eqixiac.equinix.design.spec.DesignSpecIO;

DesignSpec spec = DesignSpecIO.read(Path.of("design.yaml"));

DesignDecisionRecord record = Design.over(fabric).decisionRecord(spec)
    .title("LD and NY to AWS us-east-1")
    .record();
Files.writeString(Path.of("decision.md"), record.toMarkdown());
Files.writeString(Path.of("decision.json"), record.toJson());

// compare with an earlier record
DesignDecisionRecord previous = DesignDecisionRecord.fromJson(Files.readString(Path.of("decision-previous.json")));
DecisionDelta delta = DesignDecisionRecord.compare(previous, record);
System.out.println(delta.recommendationChanged() + " " + delta.costChange());

// the spec with the exchange rates of this run pinned
DesignSpec again = record.reproducibleSpec();

DesignDecisionRecorder.forSpec(fabric, spec) is the static entry point. The recorder reads the catalogue once and prices every section with one rate card. A live run on 2026-11-12 took 17.7 s.

Sections#

Section	Source
`context`	The spec
`decision`	The optimizer's recommendation with per-objective values, scores, weights and scales
`alternatives`	The Pareto frontier
`sensitivity`	Weight ranges over which the decision holds, and binding constraints
`cost`	Cost lines with price basis, range and currency conversion; growth and term comparison where the spec gives enough input
`resilience`	The resilience report
`risks`	Findings of the engines
`provenance`	Data sources and their dates
`implementation`	The deployment plan summary

Each section is INCLUDED, SKIPPED or FAILED with a reason (RecordSection.status(), reason()), so the recorder always returns a record. record.sections() returns all nine by name. The schema version is "1".

Supplied results#

The recorder runs the optimizer, the resilience analysis, the growth and value models and a deployment plan. A result that already exists can be supplied instead, and is checked against the spec fingerprint.

Method	Supplies
`.optimization(result)`	`OptimizationResult`
`.resilience(report)`	`ResilienceReport`
`.plan(plan)`	`DeploymentPlan`
`.estate(report)`	`EstateReport`
`.peering(result)`	`PeeringIntelligenceResult`
`.buildPlan(false)`	Skips the deployment plan
`.rateCard(...)`, `.currencyConverter(...)`, `.defaultRates(...)`	Pricing and conversion

Example output#

An excerpt from the live run of 2026-11-12 for a spec with sites in London and New York, AWS us-east-1, 1,000 Mbps and maxMetros: 2:

Text

## Decision

Deploy in **LD (London) + NY (New York)** (portfolio `LD+NY`, weighted score 89.2 of 100).

LD+NY has the highest weighted score (89.2 of 100) of the 1,081 feasible design(s) out of 2,278
examined; no feasible design is at least as good on every objective. Weights: latency 30%,
provider_coverage 25%, cost 20%, resilience 15%, compliance 10%. The closest alternative is
AM+NY (89.1).

| Objective | Value | Score | Weight | Scale |
|---|---:|---:|---:|---|
| latency | 0.5 ms | 99.8 | 30% | fixed: 0 scores 100, 200 scores 0 |
| cost | USD 3,865.12/month | 46.6 | 20% | ratio to the best option (twice as much scores 50) |
| provider_coverage | 100.0% | 100.0 | 25% | the percentage itself |
| resilience | 100.0% | 100.0 | 15% | the percentage itself |
| compliance | 100.0% | 100.0 | 10% | the percentage itself |

## Consequences

- Cost: USD 3,865.12 per month (range USD 3,660.52 to USD 4,069.75).
- Resilience: N-1 passes: every one of all 13 scenarios survives at full service.
- The decision holds while each weight stays within: latency 18% to 100%; cost 0% to 33%;
  resilience 5% to 100%; other weights can take any value.
- Implementation: 2 Cloud Router(s), 2 provider connection(s), 1 backbone link(s), 11 plan step(s).

In that run two of the six cost lines were London prices in GBP, converted at the bundled reference rate. The cost section carried a COST_CURRENCY_CONVERTED finding and a band of plus or minus 5% on those lines.

MCP tool: design_decision_record (MCP server).