1 files changed, 68 insertions, 0 deletions
diff --git a/src/Godosa.Core/Runs/Scripts/RunGame.cs b/src/Godosa.Core/Runs/Scripts/RunGame.cs
new file mode 100644
index 0000000..a6222a6
--- /dev/null
+++ b/src/Godosa.Core/Runs/Scripts/RunGame.cs
@@ -0,0 +1,68 @@
+// Provenance: own design — shared run scripts (spec §6; one hook shape for §4.2 capabilities, see Actions)
+namespace Godosa.Core.Runs.Scripts;
+
+/// <summary>A game's run-script adapter. <see cref="Actions"/> holds the lib's game-hooked verbs by their lib name
+/// (<c>talk</c>, <c>walk-to</c>, <c>cheat</c>, …) and the game's own verbs. Player-kind actions return input plans only;
+/// the lib injects them.</summary>
+public interface IRunGame
+{
+    string Name { get; }
+    string ContentVersion { get; }
+    IInputRouter Input { get; }
+    IReadOnlyDictionary<string, IProbe> Probes { get; }
+    IReadOnlyDictionary<string, long> Constants { get; }
+    IReadOnlyDictionary<string, ILocator> Locators { get; }
+    IReadOnlyDictionary<string, IRunAction> Actions { get; }
+    IRunRng? Rng { get; }
+    bool SupportsSnapshot { get; }
+    byte[] SnapshotSave();
+    /// <summary>Why the current state can't be checkpointed faithfully (e.g. state the snapshot doesn't hold), or null.
+    /// A refused checkpoint is not cached (warning); failure snapshots are still taken.</summary>
+    string? SnapshotRefusal() => null;
+    void SnapshotRestore(byte[] data);
+    /// <summary>The restore completes after this frame (a window rebuilds its game view): the runner pauses one frame
+    /// (<see cref="ScriptRunner.Restoring"/>), in which the host advances no game frame.</summary>
+    bool RestoreDeferred => false;
+    ulong Digest();
+    string Dump();
+    void Advance();
+}
+
+public interface IProbe
+{
+    int MinArgs { get; }
+    int MaxArgs { get; }
+    RunValue Eval(IReadOnlyList<string> args);
+}
+
+public readonly record struct LocatorResult(int X, int Y, string? Error)
+{
+    public static LocatorResult Ok(int x, int y) => new(x, y, null);
+    public static LocatorResult Fail(string message) => new(0, 0, message);
+    public bool IsOk => Error == null;
+}
+
+/// <summary>Finds where to aim (virtual-screen position) from game state, as a player reads the screen.</summary>
+public interface ILocator
+{
+    LocatorResult Locate(IReadOnlyList<string> args);
+}
+
+/// <summary>Begin returns an input plan to inject (player) and/or an immediate status (debug: usually Done); after the
+/// plan is sent, Poll runs each frame until Done or Fault.</summary>
+public interface IRunAction
+{
+    VerbKind Kind { get; }
+    int MinArgs { get; }
+    int MaxArgs { get; }
+    ActionStart Begin(IReadOnlyList<string> args);
+    StepStatus Poll();
+}
+
+public sealed record ActionStart(InputPlan? Plan = null, StepStatus? Status = null);
+
+public interface IRunRng
+{
+    void Seed(long seed);
+    void ForceNext(string kind, long value);
+}