feat(run): meta-progression layer + generic tools (content gap)

The cross-run layer above RunState — a serializable MetaState "save profile" (a GENERIC
bag: unlock/milestone flags + counters like meta-currency/wins/ascension) — plus the two
engine hooks and a tiny data effect vocabulary. The engine models ONLY the container +
tools; what the flags/counters MEAN, and which character needs which unlock, is content
(MetaRules), exactly like relic reactions or rewards. No unlock/ascension content baked in.

- MetaState (+ MetaStateData snapshot + MetaJson round-trip) — the actual save file.
- MetaProgression.ApplyRunEnd (WRITE hook): fold a finished run into the profile via the
  content's MetaRules (WhenResult condition + effects SetMetaFlag / AddMetaCounter /
  PromoteRunResource — the run→meta data flow).
- MetaProgression.AvailableCharacters (READ hook): the character roster gated by the
  profile — RunCharacter gains an optional UnlockFlag; the meta layer's first consumer.

Tests: a victory applies its rules (unlock flag + win counter + gold promoted to currency);
a defeat skips victory-only rules but still counts the run; the profile accumulates across
runs and round-trips as a save file; characters are gated by unlock flags.

Follow-ups: serialize MetaRules as authorable data (polymorphic MetaEffect converter) +
Studio authoring; wire ApplyRunEnd into the run runner / playtest; an ascension-level
run-start modifier hook reading the profile.

Suite green: Run 343; format clean.

Author: Paranoidgrinch

src/RogueDeck.Run/Meta/MetaProgression.cs

@@ -0,0 +1,71 @@
+namespace RogueDeck.Run;
+
+// The generic TOOLS over the meta layer (MetaState). These are the engine's two hooks — write the profile when a run
+// ENDS, read it when a run STARTS — plus a tiny effect vocabulary the rules compose. The engine supplies the
+// mechanism; the RULES (which flags/counters/promotions, which character needs which unlock) are game-specific
+// CONTENT, exactly like relic reactions or rewards. No unlock/ascension content is baked in here.
+
+// One meta-effect a rule applies to the profile. A small closed set kept as records so it can serialize as data
+// (like the run-effect vocabulary); richer effects can be added without touching the engine's apply loop.
+public abstract record MetaEffect;
+
+// Set an unlock/milestone flag (e.g. "unlocked.character.mage").
+public sealed record SetMetaFlag(string Flag) : MetaEffect;
+
+// Add to a meta counter (e.g. meta-currency, wins). Negative amounts spend.
+public sealed record AddMetaCounter(string Counter, int Amount) : MetaEffect;
+
+// Carry a finished run's resource total into a meta counter (e.g. gold-earned → meta-currency). The run→meta data
+// flow, without hardcoding which resource or counter.
+public sealed record PromoteRunResource(string RunResource, string MetaCounter) : MetaEffect;
+
+// A run-end progression rule: apply its effects to the profile when the finished run's result is one of WhenResult
+// (empty ⇒ any outcome). The rules are content; ApplyRunEnd is the engine tool that evaluates them.
+public sealed record MetaRule(IReadOnlyList<RunResult> WhenResult, IReadOnlyList<MetaEffect> Effects);
+
+public static class MetaProgression
+{
+    // WRITE hook: fold a finished run into the profile via the content's rules. Call once when a run ends.
+    public static void ApplyRunEnd(MetaState meta, RunState run, IReadOnlyList<MetaRule> rules)
+    {
+        ArgumentNullException.ThrowIfNull(meta);
+        ArgumentNullException.ThrowIfNull(run);
+        ArgumentNullException.ThrowIfNull(rules);
+
+        foreach (var rule in rules)
+        {
+            if (rule.WhenResult.Count > 0 && !rule.WhenResult.Contains(run.Result))
+                continue;
+            foreach (var effect in rule.Effects)
+                Apply(meta, run, effect);
+        }
+    }
+
+    private static void Apply(MetaState meta, RunState run, MetaEffect effect)
+    {
+        switch (effect)
+        {
+            case SetMetaFlag e:
+                meta.SetFlag(e.Flag);
+                break;
+            case AddMetaCounter e:
+                meta.AddCounter(e.Counter, e.Amount);
+                break;
+            case PromoteRunResource e:
+                meta.AddCounter(e.MetaCounter, run.GetResource(new RunResourceId(e.RunResource)));
+                break;
+        }
+    }
+
+    // READ hook: the character roster gated by the profile — the meta layer's first consumer. A character is
+    // available when it declares no UnlockFlag, or when the profile has that flag set. Which flag unlocks a
+    // character (and how it is earned) is content; the gate itself is generic.
+    public static IReadOnlyList<RunCharacter> AvailableCharacters(RunBlueprint blueprint, MetaState meta)
+    {
+        ArgumentNullException.ThrowIfNull(blueprint);
+        ArgumentNullException.ThrowIfNull(meta);
+        return blueprint.Characters
+            .Where(c => c.UnlockFlag is null || meta.HasFlag(c.UnlockFlag))
+            .ToArray();
+    }
+}

src/RogueDeck.Run/Meta/MetaState.cs

@@ -0,0 +1,64 @@
+using System.Text.Json;
+
+namespace RogueDeck.Run;
+
+// The cross-run persistence layer above a single RunState — a player's "save profile". Deliberately a GENERIC bag:
+// a set of flags (unlocks / milestones) and a dictionary of counters (meta-currency, wins, an ascension level). The
+// engine models ONLY this container + the tools to read/write it (MetaProgression); it never bakes in what the flags
+// or counters MEAN — that is game-specific content, authored as MetaRules. Round-trips via MetaJson so it can be a
+// real save file. This is the "one extra layer" a roguelike-deckbuilder needs above the run, and nothing more.
+public sealed class MetaState
+{
+    private readonly HashSet<string> _flags;
+    private readonly Dictionary<string, int> _counters;
+
+    public MetaState()
+    {
+        _flags = new HashSet<string>();
+        _counters = new Dictionary<string, int>();
+    }
+
+    public MetaState(IEnumerable<string> flags, IReadOnlyDictionary<string, int> counters)
+    {
+        ArgumentNullException.ThrowIfNull(flags);
+        ArgumentNullException.ThrowIfNull(counters);
+        _flags = new HashSet<string>(flags);
+        _counters = new Dictionary<string, int>(counters);
+    }
+
+    public IReadOnlyCollection<string> Flags => _flags;
+    public IReadOnlyDictionary<string, int> Counters => _counters;
+
+    public bool HasFlag(string flag) => _flags.Contains(flag);
+    public void SetFlag(string flag) => _flags.Add(flag);
+    public void ClearFlag(string flag) => _flags.Remove(flag);
+
+    public int GetCounter(string counter) => _counters.TryGetValue(counter, out var value) ? value : 0;
+    public void SetCounter(string counter, int value) => _counters[counter] = value;
+    public void AddCounter(string counter, int amount) => _counters[counter] = GetCounter(counter) + amount;
+
+    // A serializable snapshot (round-trips via MetaJson); the profile is the actual save data.
+    public MetaStateData Snapshot() => new(_flags.OrderBy(f => f).ToArray(), new Dictionary<string, int>(_counters));
+
+    public static MetaState FromSnapshot(MetaStateData data)
+    {
+        ArgumentNullException.ThrowIfNull(data);
+        return new MetaState(data.Flags, data.Counters);
+    }
+}
+
+// The flat, serializable shape of a MetaState — a plain record so it round-trips through System.Text.Json with no
+// custom converter (flags as an ordered list for stable output; counters as a map).
+public sealed record MetaStateData(IReadOnlyList<string> Flags, IReadOnlyDictionary<string, int> Counters);
+
+// Serialize the cross-run profile to/from JSON — the meta layer's save file.
+public static class MetaJson
+{
+    private static readonly JsonSerializerOptions Options = new() { WriteIndented = true };
+
+    public static string ToJson(MetaState meta) => JsonSerializer.Serialize(meta.Snapshot(), Options);
+
+    public static MetaState FromJson(string json) =>
+        MetaState.FromSnapshot(JsonSerializer.Deserialize<MetaStateData>(json, Options)
+            ?? new MetaStateData(Array.Empty<string>(), new Dictionary<string, int>()));
+}

src/RogueDeck.Run/Serialization/RunBlueprint.cs

@@ -62,9 +62,11 @@ public RunStart ResolveStart(string? characterId = null)
     }
 }
 
-// One selectable starting character (character selection): a stable id (for the pick + a future meta unlock gate)
-// plus its full RunStart. A plain record so it round-trips through RunJson like the rest of the blueprint.
-public sealed record RunCharacter(string Id, RunStart Start);
+// One selectable starting character (character selection): a stable id (for the pick + the meta unlock gate) plus
+// its full RunStart, and an optional UnlockFlag. When set, the character is only offered once the meta profile has
+// that flag (MetaProgression.AvailableCharacters); null ⇒ always available. Which flag unlocks it — and how it is
+// earned — is content. A plain record so it round-trips through RunJson like the rest of the blueprint.
+public sealed record RunCharacter(string Id, RunStart Start, string? UnlockFlag = null);
 
 // The authored opening state of a run: the hero's display name, starting/maximum health, starting resources
 // (resource id → amount, e.g. gold), and the relics the hero begins with (ids resolved from the run's content when

tests/RogueDeck.Run.Tests/MetaProgressionTests.cs

@@ -0,0 +1,103 @@
+using RogueDeck.Core.Combat;
+using RogueDeck.Run;
+
+namespace RogueDeck.Run.Tests;
+
+// The meta layer (content gap): a cross-run MetaState profile + the generic tools to write it at run-end (MetaRules)
+// and read it at run-start (character-unlock gating). The engine models only the container + tools; the rules and
+// which flags/counters mean what are content. These tests exercise both hooks + the profile's serialization.
+public class MetaProgressionTests
+{
+    private static readonly RunResourceId Gold = StandardRunIds.Gold;
+
+    private static RunState FinishedRun(RunResult result, int gold)
+    {
+        var run = new RunState(new RunId("r"), new HealthState(20, 30), new RunMap(Array.Empty<Node>()));
+        run.SetResource(Gold, gold);
+        run.SetResult(result);
+        return run;
+    }
+
+    // A ruleset: on a victory, unlock the mage + count a win + carry the run's gold into meta-currency; on ANY
+    // outcome, count a completed run.
+    private static IReadOnlyList<MetaRule> Rules() => new[]
+    {
+        new MetaRule(new[] { RunResult.Victory }, new MetaEffect[]
+        {
+            new SetMetaFlag("unlocked.character.mage"),
+            new AddMetaCounter("wins", 1),
+            new PromoteRunResource(Gold.Value, "meta.currency"),
+        }),
+        new MetaRule(Array.Empty<RunResult>(), new MetaEffect[] { new AddMetaCounter("runs", 1) }),
+    };
+
+    [Fact]
+    public void A_victory_applies_its_rules_to_the_profile()
+    {
+        var meta = new MetaState();
+
+        MetaProgression.ApplyRunEnd(meta, FinishedRun(RunResult.Victory, gold: 45), Rules());
+
+        Assert.True(meta.HasFlag("unlocked.character.mage"));
+        Assert.Equal(1, meta.GetCounter("wins"));
+        Assert.Equal(45, meta.GetCounter("meta.currency")); // the run's gold promoted into the profile
+        Assert.Equal(1, meta.GetCounter("runs"));           // the any-outcome rule also fired
+    }
+
+    [Fact]
+    public void A_defeat_skips_victory_only_rules_but_still_counts_the_run()
+    {
+        var meta = new MetaState();
+
+        MetaProgression.ApplyRunEnd(meta, FinishedRun(RunResult.Defeat, gold: 45), Rules());
+
+        Assert.False(meta.HasFlag("unlocked.character.mage")); // victory-only, skipped
+        Assert.Equal(0, meta.GetCounter("wins"));
+        Assert.Equal(0, meta.GetCounter("meta.currency"));
+        Assert.Equal(1, meta.GetCounter("runs"));              // the any-outcome rule fired
+    }
+
+    [Fact]
+    public void The_profile_accumulates_across_runs_and_round_trips_as_a_save_file()
+    {
+        var meta = new MetaState();
+        MetaProgression.ApplyRunEnd(meta, FinishedRun(RunResult.Victory, 10), Rules());
+        MetaProgression.ApplyRunEnd(meta, FinishedRun(RunResult.Victory, 20), Rules());
+
+        Assert.Equal(2, meta.GetCounter("wins"));
+        Assert.Equal(30, meta.GetCounter("meta.currency")); // 10 + 20 accumulated across runs
+
+        var reloaded = MetaJson.FromJson(MetaJson.ToJson(meta));
+        Assert.True(reloaded.HasFlag("unlocked.character.mage"));
+        Assert.Equal(2, reloaded.GetCounter("wins"));
+        Assert.Equal(30, reloaded.GetCounter("meta.currency"));
+        Assert.Equal(2, reloaded.GetCounter("runs"));
+    }
+
+    [Fact]
+    public void Available_characters_are_gated_by_the_profiles_unlock_flags()
+    {
+        var blueprint = new RunBlueprint(
+            Deck: Array.Empty<CardDefinitionId>(),
+            Events: new Dictionary<string, EventScript>(),
+            Encounters: Array.Empty<EncounterDefinition>(),
+            Cards: Array.Empty<RogueDeck.Scenario.Authoring.CardData>(),
+            EnemyActions: Array.Empty<RogueDeck.Scenario.Authoring.EnemyActionData>(),
+            Map: new RunMap(Array.Empty<Node>()))
+        {
+            Characters = new[]
+            {
+                new RunCharacter("knight", new RunStart()),                                      // always available
+                new RunCharacter("mage", new RunStart(), UnlockFlag: "unlocked.character.mage"), // gated
+            },
+        };
+
+        var locked = MetaProgression.AvailableCharacters(blueprint, new MetaState());
+        Assert.Equal(new[] { "knight" }, locked.Select(c => c.Id));
+
+        var meta = new MetaState();
+        meta.SetFlag("unlocked.character.mage");
+        var unlocked = MetaProgression.AvailableCharacters(blueprint, meta);
+        Assert.Equal(new[] { "knight", "mage" }, unlocked.Select(c => c.Id));
+    }
+}