STONE v2 reformat

[erwanp]

Summary

Boulder now accepts STONE v2 YAML defined either as a single-stage network: list or a multi-stage stages: layout with matching top-level stage blocks. Legacy STONE v1 (nodes: / connections: / groups: in raw YAML) is rejected with an explicit migration message. Normalization still produces the same internal flat shape (nodes, connections, groups) so the converter, staged solver, and existing validation plumbing stay aligned.

---

What changed

Parsing and normalization (boulder/config.py)

• _detect_stone_dialect infers v2_network, v2_staged, or treats already-normalized dicts as internal when appropriate (tests/plugins).
• _normalize_v2 maps v2 into internal lists: staged items get group: <stage_id>; network: is wrapped as a synthetic single stage where needed.
• Item rules: node vs connection by source / target presence; ambiguous half-edges raise ValueError.
• Reserved stage names, bijection between stages: keys and top-level stage sections, stages: vs network: mutex, and related staged-graph constraints are enforced during normalization.
• Inline inlet: / outlet: on node items are rejected in favor of explicit connection items (per spec).
• Logical connections (no kind key) are represented consistently for downstream code (e.g. MFC-style placeholder with a logical annotation until a dedicated type exists).

Validation (boulder/validation.py)

• validate_normalized_config extended so normalized v2-derived configs satisfy the same end-state rules as before, plus any v2-specific checks needed after flattening.

Specification and user-facing docs

• STONE_SPECIFICATIONS.md: normative STONE v2 contract (dialect, schemas, physics notes, examples, v1 historical note).
• SPECIFICATIONS.md: short index linking to the STONE spec.
• docs/stone.rst + docs/index.rst: Sphinx overview, quick start (network:), staged example, pointer to STONE_SPECIFICATIONS.md, v1 deprecation note.
• ARCHITECTURE.md and configs/README.md: pipeline and examples updated for v2; normative detail deferred to STONE_SPECIFICATIONS.md.

Tests

• tests/fixtures/stone_v2/{valid,invalid}/ minimal YAMLs (one rule per file).
• tests/test_stone_v2_fixtures.py: parametrized normalize + validate; test_spec_examples_are_valid_yaml ensures every ```yaml block in STONE_SPECIFICATIONS.md parses.

---

Breaking change

Raw STONE v1 YAML is no longer accepted by normalize_config. Consumers must migrate to network: or stages: (blocB migrations are handled in sibling PRs per plan).