feat(core): adopt feedpak_version — read on load + stamp on manifest writes (spec §4) (#530)

Core never read or emitted the manifest `feedpak_version` field. Adopt it:

- sloppak.py: `FEEDPAK_VERSION = "1.2.0"` constant (the format version this build
  targets); `LoadedSloppak.feedpak_version` read from the manifest on load
  (string, else None for legacy/absent).
- Stamp the version on the two core manifest-rewrite paths, without downgrading
  an existing (possibly higher) declared version:
  - gp2notation: `setdefault` before its notation-add rewrite.
  - songmeta: opportunistically when a metadata field is supplied (gated on the
    existing `dirty` flag, so never a standalone rewrite).

Core has no create-from-scratch path (RS-free repo) — the editor plugin's
create-mode save stamping FEEDPAK_VERSION is a follow-up in that repo. Internal
"sloppak" naming is intentionally left as-is (a rename is out of scope / risky).

Codex-reviewed: no P1/P2. +6 tests (read present/absent/non-string; metadata-write
stamp-when-absent / preserve-existing / no-op-no-stamp) + updated the gp2notation
key-order test for the appended version. 197 sloppak/songmeta/gp2notation tests pass.

Closes #527. Part of got-feedback/feedback#334.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

lib/gp2notation.py

@@ -522,6 +522,10 @@ def attach_notation_to_sloppak(sloppak_dir: str | Path, arr_id: str, payload: di
         json.dumps(payload, separators=(",", ":")), encoding="utf-8"
     )
     entry["notation"] = filename
+    # Stamp the format version while we're rewriting the manifest (spec §4),
+    # without downgrading an existing (possibly higher) declared version.
+    from sloppak import FEEDPAK_VERSION
+    manifest.setdefault("feedpak_version", FEEDPAK_VERSION)
     manifest_path.write_text(
         yaml.safe_dump(manifest, sort_keys=False, allow_unicode=True),
         encoding="utf-8",

lib/sloppak.py

@@ -24,6 +24,11 @@ from pathlib import Path
 
 log = logging.getLogger("slopsmith.lib.sloppak")
 
+# The feedpak format version this build targets / writes (manifest
+# `feedpak_version`, a semver string per spec §4). Readers tolerate any version
+# (additive/MINOR compatibility); writers stamp this.
+FEEDPAK_VERSION = "1.2.0"
+
 import yaml
 
 from safepath import safe_join
@@ -316,6 +321,9 @@ class LoadedSloppak:
     stems: list[dict]           # [{"id": str, "file": str, "default": bool}]
     source_dir: Path
     manifest: dict
+    # The pack's declared format version (manifest `feedpak_version`, a semver
+    # string per spec §4). None when absent (legacy / pre-versioning packs).
+    feedpak_version: str | None = None
     # Parsed `drum_tab.json` payload when the manifest carries a `drum_tab:`
     # key pointing at a readable, schema-valid file. None otherwise (older
     # sloppaks, sloppaks without drums, sloppaks whose drum tab failed to
@@ -789,11 +797,13 @@ def load_song(
                         "events": clean_events,
                     }
 
+    _fpv = manifest.get("feedpak_version")
     return LoadedSloppak(
         song=song,
         stems=stems,
         source_dir=source_dir,
         manifest=manifest,
+        feedpak_version=_fpv if isinstance(_fpv, str) and _fpv else None,
         drum_tab=drum_tab_data,
         song_timeline=song_timeline_data,
         tempos=tempos_data,

lib/songmeta.py

@@ -49,6 +49,15 @@ def _apply_to_sloppak_manifest(manifest: dict, fields: dict) -> bool:
     if "year" in fields:
         manifest["year"] = _coerce_year(fields["year"])
         dirty = True
+    # Opportunistically declare the format version (spec §4) when we're already
+    # rewriting because a metadata field was supplied. Gated on `dirty` (i.e. a
+    # field was given) so this never forces a *standalone* rewrite with no fields
+    # passed, and `not in` so an existing (possibly higher) version is preserved,
+    # never downgraded. NB `dirty` here means "a field was supplied" — a
+    # supplied-but-identical value already triggers a rewrite (pre-existing).
+    if dirty and "feedpak_version" not in manifest:
+        from sloppak import FEEDPAK_VERSION
+        manifest["feedpak_version"] = FEEDPAK_VERSION
     return dirty