Generate deterministic plans from seeded scenarios

[berendt]

Closes #3

Summary

Builds the left half of the test pipeline: a YAML scenario format and a deterministic generator that expands a scenario plus a seed into a fully-enumerated plan — the expected-state source of truth listing every network, subnet, router interface, port, and security-group rule with its intended attributes and references. The reproducibility contract is the point: the same scenario and seed yield a byte-identical plan, stable across runs and Go versions. Ships the neutron generate command, dotted-key --set overrides, strict schema validation, and apply --dry-run that prints the plan summary while making zero API calls.

Change set (in commit order)

1. 72192db Add internal/plan expected-state model with validation — The Plan is pure data with slice-only collections so JSON encoding is byte-stable for the same input. Validate resolves every cross-resource reference and enforces the Phase 1 invariant that a subnet attaches to at most one router. Summary renders deterministic per-type counts for the dry-run preview.
2. 0fbde08 Add internal/scenario types, parsing, validation, overrides — Types the YAML scenario format from README §6 (counts, ratios, distributions, topology, seed). Parse uses strict unmarshalling so a mistyped key fails loudly; Validate emits field-named, actionable messages; Set applies dotted --set overrides with type-safe parsing. Promotes gopkg.in/yaml.v2 from an indirect to a direct dependency (already in go.sum, no new module).
3. 7167bcb Add deterministic seeded plan generator with golden tests — Generate draws from math/rand v1 (frozen sequence) in a fixed order and emits every collection in a fixed order. IPs are allocated deterministically via net/netip from three non-overlapping ranges: explicit IPv4 /24 from 10.0.0.0/8, subnet pools as /16 from 172.16.0.0/12, and IPv6 /64 from fd00::/16. A committed golden plan (testdata/golden/small.plan.json) locks byte-stability; regenerate intentionally with -update.
4. ee965ed Add neutron generate command writing plan JSON — generate expands a scenario into a plan and writes indented JSON to --out or stdout; the confirmation line goes to the log so piped stdout stays clean. --scenario is required, --set applies overrides, and the global --seed overrides the scenario seed. buildPlanFromFlags (load → override → generate) is factored out for reuse by apply.
5. 01db05e Implement apply --dry-run plan preview without API calls — apply --dry-run expands the scenario and prints its summary with zero API calls. The command imports neither internal/config nor gophercloud, so the dry-run path structurally cannot reach the API; the non-dry-run executor returns a clear not-implemented error tracked to issue Apply plans against Neutron with tagging, concurrency, and metrics #4.
6. 74bcd76 Document resolved IPv6/network-type decisions and status — Marks the IPv6 and network-types open questions resolved to match what the generator emits: dual-stack subnets under distribution.ipv6_ratio, and plain geneve/vxlan tenant networks with no provider attributes. Documents deterministic generation and CIDR allocation, and refreshes the status line.
7. 966ba2c Sync neutron namespace doc comment with implemented commands — Updates the namespace doc comment that still described generate and apply as stubs.

Notes for the reviewer

• Scope vs. issue: The issue scopes the left half of the pipeline (scenario → plan → JSON + --dry-run). The real apply executor against a live cloud is intentionally out of scope — it returns a not-implemented error tracked to issue Apply plans against Neutron with tagging, concurrency, and metrics #4. No divergence from the issue.
• Resolved decisions: Per the issue's note that this work "resolves the IPv6 and network-types decisions insofar as they shape what the generator emits," dual-stack subnets are emitted under ipv6_ratio and networks are plain tenant networks with no provider attributes (74bcd76).
• Testing: Golden-file test pins byte-stability of the generated plan; unit tests cover plan validation, scenario parsing/validation/overrides, and the generate / apply --dry-run commands.

---

Implemented by planwerk-review a24f4d9 with Claude:claude-opus-4-8