Przegląd

YAML zalecany dla człowieka. JSON zalecany dla API/automatyzacji. Obie reprezentacje są izomorficzne.

  • Pliki wejściowe: .yaml lub .json
  • Walidacja: JSON Schema (draft 2020-12)
  • Wersjonowanie: SemVer w polu spec_version

Oficjalne JSON Schema (α)

Ładowanie schematu…

Jeśli plik nie istnieje w repozytorium lub zawiera tylko „xxx”, zobaczysz wyłącznie komunikat o stanie (istnieje/pusty/„xxx”). Bez proponowania treści.

Przykłady (YAML/JSON)

Minimalny eksperyment (YAML)

Ładowanie…

To samo (JSON)

Ładowanie…

Rozszerzony hipergraf (YAML)

Ładowanie…

Sonda z parametrami (JSON)

Ładowanie…

Przykładowy skrypt (JS)

Ładowanie…

Walidacja

  • Użyj dowolnej biblioteki JSON Schema (draft 2020-12). YAML → JSON: zwykła serializacja.
  • Tryb strict – wymaga pełnej zgodności ze schematem; lenient – ostrzega na polach nieznanych.
  • Idempotencja: parse → export nie zmienia semantyki (kolejność pól dowolna).
romion-sim validate spec.yaml --strict
romion-sim run spec.yaml --seed 123 --export metrics.json

Kody błędów (α)

Walidacja

  • RS-VAL-001 — brak pola obowiązkowego (np. run.steps).
  • RS-VAL-002 — typ niezgodny ze schematem.
  • RS-VAL-003 — niedozwolone dodatkowe pola w trybie strict.

Semantyka

  • RS-SEM-101 — reguła usuwa nieistniejący hiperbrzeg.
  • RS-SEM-102 — złamanie inwariantu (np. preserve_loop_class).
  • RS-SEM-103 — cykl bez wyjścia (stagnacja/przesterowanie).

Uruchomienie

  • RS-RUN-201 — nieznany schedule.
  • RS-RUN-202 — błąd eksportu (ścieżka/perm).

Wersjonowanie i kompatybilność

  • SemVer specyfikacji – spec_version w pliku eksperymentu.
  • Kompatybilność wstecz – α → β: zachowujemy istniejące pola; deprecjacje ostrzegane (lenient).
  • Stabilizacja – zamrożenie słowników (probes, schedule) w β.

Bezpieczeństwo i dobre praktyki

  • Pliki specyfikacji są niewykonywalne (zakaz osadzania skryptów/komend).
  • Wartości tekstowe są danymi — brak interpolacji.
  • Tryb strict: odrzucaj URL-e w polach ścieżkowych.
  • Powtarzalność: zapisuj seed i wersję silnika.

Glosariusz

Hipergraf
Uogólnienie grafu: hiperbrzeg łączy n ≥ 2 węzły.
Reguła (Rule)
Lokalne przepisanie fragmentu hipergrafu.
Inwariant
Wielkość zachowywana/kontrolowana przez dynamikę.
Metryka d_em
Koszt minimalnej sekwencji transformacji sprzęgającej wzorce.
Schedule
Strategia wyboru miejsca zastosowania reguły.
Probe
Sonda pomiarowa generująca komponent wektora 𝕀.

Uwagi do specyfikacji