Architecture

Top-level components

• InkkOopsHostConfiguration: host-owned configuration root for catalogs, policies, and defaults.
• InkkOopsRuntimeService: coordinator for queued work, startup work, recording, and attach requests.
• InkkOopsGameHost: adapter between MonoGame host behavior and the automation runtime.
• IInkkOopsScriptCatalog: host-supplied lookup for named scripts.
• IInkkOopsArtifactNamingPolicy: host-supplied naming rules for run and recording bundles.
• IInkkOopsReplayPostamblePolicy: host-supplied replay tail behavior.
• CaptureTelemetryAsync: explicit runtime telemetry dump used for assertion-oriented diagnostics artifacts.

Request flow

1. The app constructs the host configuration.
2. The app starts InkkOopsRuntimeService with runtime options plus the host configuration.
3. A request is created either from startup flags or from an attach-mode pipe request.
4. The runtime resolves the script or recording replay.
5. The runtime creates an artifact bundle using the naming policy.
6. The runtime executes the script through InkkOopsScriptRunner and InkkOopsSession.
7. The host adapter performs the real resize, input, capture, and telemetry work.
8. The runtime writes result.json, commands.log, and any requested captures or telemetry artifacts.

Why the host configuration exists

The host configuration defines the policy boundary for the runtime. Pipe names, artifact roots, replay-tail behavior, diagnostics formatting, and script exposure come from the host profile rather than being embedded in command execution code. That keeps the runtime reusable while still allowing each host app to preserve its own defaults.

Catalog and script registration

The runtime only depends on IInkkOopsScriptCatalog. In this repository, the default host profile uses a reflection-backed catalog that discovers built-in script classes from the app assembly. That reflection step is an adapter, not a core runtime requirement.

Policy surfaces

• Naming policy: controls run directory names, recording directory names, result file names, command diagnostics file names, frame capture file names, and telemetry file names.
• Replay postamble policy: controls what extra commands are appended after a replay is generated from a recording.
• Diagnostics contributors: control which per-element facts are collected during telemetry generation.

Diagnostics pipeline

The telemetry system is built from diagnostics contributors. A generic tree walker captures the visual tree, contributors add per-element facts, and the serializer formats the result into the telemetry output file. This keeps diagnostics extensible while allowing framework-specific contributors to describe individual control types in more detail.