The YAML Is The Contract

A session is a small file.

The platform parses it, expands the geometry, lays out the interfaces, brings up the pods, runs the experiment, and reports what happened. That is the only contract at the runtime boundary. Send YAML. Get a session.

Writing the first one by hand is reasonable. Writing the hundredth, for a parameter sweep across three constellations and four routing stacks, is a tax. And a place where errors hide. A misplaced indent, a wrong inclination, a stale satellite-type reference. The text editor will not notice. The platform will not notice until it tries to run the thing.

So the platform was built to accept the YAML from anywhere.

Authorship does not matter

A session is the platform's input format. Nothing about what runs depends on how the file was authored.

Hand-written, generated by a Python script, produced by the wizard, or pulled from a CI pipeline that builds sessions from a matrix of parameters. The file shape is identical. The platform parses it once, validates it once, runs it once. Authorship is the user's problem until the YAML lands.

That keeps the platform honest about what it is and is not. It is not a sessions service that produces YAML as a byproduct. It is a runtime that consumes YAML.

It also keeps the user honest about what is reproducible. A session that ran is a YAML file you can commit to git, send to a colleague, regenerate from a template, and run again. There is no hidden state in a wizard or a UI somewhere. The YAML is the artifact.

Three roads to the same file

FIG.01 — One contract, three roads in YAML IN · SESSION OUT

A text editor is the first road. Useful for one-off runs and learning the schema. You write it by hand, you save it, you point the platform at it.

A programmatic pipeline is the next road. NodalArc expects this and was built around it. When you are sweeping plane counts from 4 to 12 across three altitudes and two routing protocols, you are producing 72 sessions. Writing 72 sessions by hand is not engineering. Writing a forty-line generator that emits 72 sessions and submits them is engineering. The platform does not care that the YAML came from a Jinja template or a Jupyter notebook or a CI runner. It runs what it is given.

A wizard is the third road. It sits between the other two. You are writing a session by hand, you want help avoiding the geometry mistakes a text editor cannot catch, and you want to see the experiment's feasibility before you commit it to a deploy. The wizard's value is not the UI. It is the math the UI runs in the background.

The three roads are not in competition. They share the same target. The same session YAML the wizard produces at the end of its last step is the same YAML a generator could emit in a CI job and the same YAML a researcher might type by hand to test a one-off idea.

The editor cannot see the sky

A text editor catches schema errors. A wizard catches geometry errors.

The difference matters. A misplaced inclination_deg value is a schema error. Easy to spot, easy to fix. An inclination_deg of 53 paired with a ground-station set named polar-emphasis is not a schema error. The file parses. The values are valid. The experiment is doomed because a 53-degree shell never sees Svalbard. The text editor has no idea. The platform finds out 90 seconds into the deploy when Svalbard's terminal sits idle for the whole orbital period.

The wizard catches that before deploy.

The middle phase runs the feasibility math. The platform calls it the coverage preview. Whatever you call it, it does the same job. It does not start any pods. It computes, in the background, what the constellation would actually look like if you ran the experiment for one orbital period.

For inter-satellite links: how many ISLs the satellite type makes possible given its terminal counts, how many of those actually form during the orbit given the geometry, how many never form, and why. If a link never forms, the preview names the reason. Range exceeded. Tracking rate exceeded. Field of regard exhausted. Line of sight blocked by Earth. Polar seam. Terminals all in use. The same satellite type that runs cleanly on Walker Delta will have most of its cross-plane links flagged as tracking-exceeded on Walker Star, and the preview makes that visible before the deploy.

For ground stations: the percentage of the orbital period each station has at least one satellite in view, the longest gap during which it has none, and a reason for any station whose coverage looks degraded. Across the whole set, the minimum, mean, and maximum satellites simultaneously visible. The polar-emphasis-against-53-degree mismatch shows up as Svalbard with zero coverage and a reason that says "above maximum constellation latitude."

For the whole design, warnings. Sub-threshold satellite count for a coverage target. Ground stations unreachable by the selected geometry. Half the cross-plane fabric cut by the seam at some latitude. The warnings are concrete, not decorative. Each one names a specific reason a measurement would be polluted before the platform burns the time to take the measurement.

The wizard reads the same files the runtime reads. Add a constellation YAML, and the wizard can surface it. Generate one from a pipeline, and the runtime can consume it. There is no second catalog quietly drifting away from the system.

Cheaper failures

The cost of a bad session depends on where it is caught.

Caught in a text editor: zero. The error is a typo. You fix it and keep typing.

Caught in the wizard's coverage preview: a few seconds and a click. The feasibility math runs without spinning up pods. You see the warning, you change the selection, you preview again.

Caught at deploy: 90 seconds. The platform brings the session up, the pods come online, the routing daemons start, and the impossible link configurations stand out in the live state. You tear it down. You start over.

Caught after the measurement: the measurement. You discover the experiment was unfair after you already paid for the data. The path-stretch numbers are not the protocol's fault. They are yours, for asking a question the geometry refused to answer.

The wizard is the lowest-cost place to be wrong. The pipeline can do the same checks programmatically by calling the same feasibility math the wizard exposes. The platform was built so that wrongness is caught as early as possible by whichever entry point is producing the YAML.

The YAML is still just YAML at the end. The wizard is a safer way to write it. The pipeline is a scalable way to generate it. The text editor is fine when neither of those matters.

The platform sees the same thing regardless.