tracking: Orchestrator LTS Next-Gen — experimental features built on LTS foundation

[frostebite]

Orchestrator Next-Gen — Experimental Features

This is the tracking issue for Orchestrator's Next-Gen experimental features. These are built on the stable LTS foundation but require community feedback and real-world validation before being considered stable.

Context: The Orchestrator Evolution

The Orchestrator began life as Cloud Runner — a cloud-specific build system for running Unity builds on AWS, Kubernetes, or Docker. It was rewritten into a provider-agnostic orchestration layer with a pluggable architecture, renamed to Orchestrator to reflect this fundamental shift. See #794 for the full history.

With LTS (v2.0.0), the core is now considered complete — it covers its domain cleanly, has been dogfooded in real CI workflows, and the primitives needed even for advanced enterprise workflows are all in place.

Philosophy

The features tracked here represent the next horizon — ideas that extend the orchestrator beyond traditional CI into areas like persistent build environments, structured test management, generic artifact handling, and AI-assisted workflows.

Next-Gen features aim to be included in LTS eventually, but they:

• Remain in experimental status until validated by community usage
• Are not essential/blocking for the core LTS mission
• May have API changes based on feedback
• Require the LTS foundation to be mostly complete first

Think of LTS as "everything you need for production CI" and Next-Gen as "what is possible when CI becomes a platform."

Why a Separate Track?

With LTS, we are past the point where obvious new capabilities belong inside the core. Even for advanced enterprise workflows, the necessary primitives are already there. These features are more likely to live around the ecosystem or as separate tools rather than expanding the orchestrator core.

Many have their own repositories, protocols, or plugin surfaces. They depend on LTS being stable but do not gate it.

The expectation is that after LTS ships, the core requires much less active maintenance. Future core changes are mostly bug fixes and graduating experimental features. The innovation happens here, in the next-gen track.

---

Next-Gen Feature Tracker

Test Workflow Engine (#788)

YAML-based test suite definitions with multi-dimensional taxonomy filtering, structured result reporting, and sequential execution dependencies. Modeled on battle-tested patterns from production Unity projects with 300+ tests across multiple suites.

Detail	Value
Issue	#788
PR	#790 (feature/test-workflow-engine)
Docs	#538 — 11-test-workflow-engine.mdx
Status	Complete — fully implemented with 43 tests

Implemented services:

• TestSuiteParser — Parses YAML suite definitions with ordered runs and needs: dependencies. Uses Kahn's topological sort for correct execution ordering.
• TaxonomyFilterService — 7 built-in taxonomy dimensions (Scope, Maturity, FeedbackSpeed, Rigor, Determinism, Execution, IsolationLevel) with regex pattern matching and hierarchical dot-notation support.
• TestResultReporter — Parses JUnit XML and Unity JSON test output formats. Generates per-suite and per-run result aggregation with timing data. Produces GitHub-compatible Markdown summary.
• TestWorkflowService — Orchestrates the full test workflow: suite loading, taxonomy filtering, execution entry, and multi-format result output.

action.yml inputs (5): testSuitePath, testSuiteEvent, testTaxonomyPath, testResultFormat, testResultPath

---

Hot Runner Protocol (#789)

Persistent, process-based build/test providers. Instead of cold-starting a Unity editor for each build, hot runners keep editors warm and ready to accept jobs via extensible transport protocols.

Detail	Value
Issue	#789
PR	#791 (feature/hot-runner-protocol)
Docs	#538 — 12-hot-runner-protocol.mdx
Editor-side	game-ci/game-ci-editor-tools PR #1
Status	Complete — fully implemented with 35 tests + editor-tools companion

Implemented services:

• HotRunnerRegistry — In-memory runner registry with file-based persistence. Tracks registered runners by ID, labels, transport, and capabilities. Supports runner expiration and cleanup.
• HotRunnerHealthMonitor — Periodic health checking via transport ping. Tracks runner health state transitions (healthy, degraded, offline).
• HotRunnerDispatcher — Routes jobs to available runners by label matching. Timeout-based dispatch with configurable fallback to cold builds.
• HotRunnerService — Orchestrates the full hot runner lifecycle: registration, health monitoring, job dispatch, and result collection.

Editor-tools companion (PR #1):

• 5 transport servers: Named Pipe, File-based, HTTP (always available), WebSocket (#if GAMECI_WEBSOCKETS), SignalR (#if GAMECI_SIGNALR)
• Registry-based TransportFactory for user extensibility
• Health reporting: memory usage, uptime, Library hash, job count
• 13 C# files across transport, models, settings, and server components

action.yml inputs (7): hotRunnerEnabled, hotRunnerTransport, hotRunnerHost, hotRunnerPort, hotRunnerHealthInterval, hotRunnerMaxIdle, hotRunnerFallbackToCold

---

Generic Artifact System (#792)

Multi-type output management with manifests, collection pipelines, upload handlers, and extensible type registration. Beyond "here is the build output" — structured handling of every kind of CI artifact.

Detail	Value
Issue	#792
PR	#798 (feature/generic-artifact-system)
Docs	#538 — 13-build-output-system.mdx
Status	Complete — fully implemented with 36+ tests

Implemented services:

• OutputTypeRegistry — Registry with 8 built-in types (build, test-results, server-build, data-export, images, logs, metrics, coverage) plus custom type registration.
• OutputService — Workspace scanning, manifest generation with per-file SHA-256 hashing, recursive directory collection and size calculation.
• ArtifactUploadHandler — Configurable upload pipeline: GitHub Artifacts, rclone storage, local copy, or none. Supports compression (none, gzip, lz4) and retention policies.
• OutputManifest — TypeScript interfaces for build GUID, timestamp, typed entries with path/size/hash/metadata.

action.yml inputs (7) + outputs (1): artifactOutputTypes, artifactUploadTarget, artifactUploadPath, artifactCompression, artifactRetentionDays, artifactCustomTypes, artifactManifestPath + output artifactManifestPath

---

Incremental Sync Protocol (#793)

Cacheless workspace updates — instead of traditional cache restore, deliver only what changed. Supports git-based delta, direct file input (no push required), and storage-backed content pull from rclone or S3.

Detail	Value
Issue	#793
PR	#799 (feature/incremental-sync-protocol)
Docs	#538 — 14-incremental-sync-protocol.mdx
Status	Complete — fully implemented with 42 tests

Implemented services:

• IncrementalSyncService — Core sync service with 4 strategies: full (traditional clone), git-delta (fetch + selective checkout since last sync commit), direct-input (tar extraction with overlay management), storage-pull (rclone-backed content retrieval).
• SyncStateManager — Persistent sync state tracking with SHA-256 workspace hashing and drift detection. Tracks lastSyncCommit, timestamp, workspaceHash, pendingOverlays.
• Overlay management — Apply and revert workspace overlays for direct-input changes. Overlay stack supports multiple modifications with clean revert.

Wired into both local and remote-client build paths. Independent of hot runners — usable by any provider.

action.yml inputs (5): syncStrategy, syncInputRef, syncStorageRemote, syncRevertAfter, syncStatePath

---

Community Plugin Validation (#800)

Scheduled CI workflow that validates community Unity packages compile and build correctly using unity-builder. Runs weekly, with manual dispatch for testing specific plugins.

Detail	Value
Issue	#800
PR	#804 (feature/community-plugin-validation)
Docs	N/A — internal CI tooling
Status	Complete — workflow and plugin registry implemented

Key capabilities:

• YAML plugin registry (community-plugins.yml) for community package listings (UniTask, NaughtyAttributes, Unity Atoms as initial entries)
• Matrix expansion across plugins and platforms
• Automatic GitHub issue creation on validation failures
• Manual dispatch with plugin filter (regex) and Unity version override
• Minimal Unity project creation per plugin for isolation

---

Unity Editor Tooling (#797)

In-editor GUI tools for orchestrator job management, workflow configuration, cache inspection, and build monitoring. Lives in a separate repository as a UPM package. This is a companion milestone to LTS — it makes the orchestrator accessible to teams who want to configure and use Game CI without working directly with YAML.

Detail	Value
Issue	#797
Repo	game-ci/game-ci-editor-tools
Docs	Package README (docs PR planned for stable release)
Status	Implemented — 6 editor tools (3 stable, 3 experimental) + hot runner worker

Stable tools:

• WorkflowYamlGenerator — Visual GitHub Actions YAML builder with platform, provider, caching, LFS, hooks, secrets dropdowns
• GitHubActionsPanel — Recent workflow runs display with status coloring, duration, and direct URL links
• CacheInspector — Browse local/runner/container caches, see per-entry size/age/type, purge with confirmation

Experimental tools:

• TestSuiteEditor — Visual YAML test suite builder with taxonomy filters and run ordering
• HotRunnerMonitor — Monitor hot runners across 4 transport types with status display
• ArtifactBrowser — Split-pane artifact browser with Local/Rclone/S3 backends and image/text preview

Hot Runner Worker (PR #1):

• Full hot runner server implementation inside Unity Editor
• 5 transports: Named Pipe, File-based, HTTP, WebSocket, SignalR
• Registry-based TransportFactory for user extensibility
• Health reporting, job execution, auto-recycling
• 13 C# files, ~2000+ lines

---

Claude for Unity-Builder (#801)

AI-assisted build configuration, debugging, orchestration, and contributor onboarding. Purpose-built CLAUDE.md, agent definitions, and skills for the unity-builder codebase.

Detail	Value
Issue	#801
PR	TBD — design phase
Docs	TBD
Status	Concept — key architectural questions need resolution

Key questions to resolve:

• CLAUDE.md structure for TypeScript GitHub Action + orchestrator
• Agent definitions for build debugging, provider development, test writing
• Skills for common contributor workflows
• Integration with editor tooling for AI-assisted configuration

---

Official CLI Support (#812)

Standalone CLI distribution of unity-builder as the game-ci command. Build, test, cache, and orchestrate Unity projects from the terminal without needing GitHub Actions.

Detail	Value
Issue	#812
PR	#813 (feat: Official CLI Support — game-ci)
Docs	TBD
Status	Draft PR — design and implementation in progress

Key capabilities:

• game-ci build, game-ci test, game-ci cache, game-ci orchestrate
• Same core engine as the GitHub Action
• Configuration via CLI flags, env vars, or game-ci.yml
• npm distribution: npx game-ci build

---

Orchestrator Isolation (#796)

Future architectural initiative to fully decouple the orchestrator from unity-builder into a standalone, reusable package. Would allow orchestrator to be used with other game engines, CI systems, or as a standalone CLI.

Detail	Value
Issue	#796
PR	TBD — design phase, awaits LTS stabilization
Docs	TBD
Status	Concept — needs design review before implementation

---

Documentation — Advanced Topics

Topic	Issue	Docs PR	Page
Massive Projects (100GB+, 500K+ files)	#802	#538	15-massive-projects.mdx
Monorepo Support (multi-product builds)	#803	#538	16-monorepo-support.mdx

---

Relationship to LTS

  LTS (v2.0.0)                    Next-Gen (experimental)
 +-----------------------+        +-------------------------------+
 | Provider system       |------->| Hot Runner Protocol (#789)    |
 | CLI Provider Protocol |------->| Incremental Sync (#793)       |
 | Hook system           |------->| Test Workflow Engine (#788)    |
 | Cache system          |------->| Generic Artifacts (#792)       |
 | Secret sources        |        | Editor Tooling (#797)          |
 | Submodule profiles    |        | Plugin Validation (#800)       |
 | LFS agents            |        | Orchestrator Isolation (#796)       |
 | Load balancing        |        | Claude AI Assist (#801)        |
 +-----------------------+        | CLI Support (#812)             |
         stable                   | Massive Projects docs (#802)   |
                                  | Monorepo Support docs (#803)   |
                                  +-------------------------------+
                                          experimental

All Related PRs

unity-builder (game-ci/unity-builder)

PR	Branch	Description	Status
#790	feature/test-workflow-engine	Test workflow engine — YAML suites, taxonomy filtering, structured results	Complete — 43 tests
#791	feature/hot-runner-protocol	Hot runner protocol — registry, health monitoring, job dispatch	Complete — 35 tests
#798	feature/generic-artifact-system	Generic artifact system — output types, manifests, upload handlers	Complete — 36+ tests
#799	feature/incremental-sync-protocol	Incremental sync — 4 strategies, state management, drift detection	Complete — 42 tests
#804	feature/community-plugin-validation	Community plugin validation workflow	Complete
#813	feat: Official CLI Support — game-ci	CLI distribution of unity-builder	Draft

documentation (game-ci/documentation)

PR	Branch	Description	Status
#538	docs/test-workflow-hot-runners	All next-gen docs: test workflow, hot runners, artifacts, sync, massive projects, monorepo, build reliability, 4 provider pages	Draft
#540	docs/cli	CLI documentation — installation, usage, commands	Draft

game-ci-editor-tools (game-ci/game-ci-editor-tools)

PR/Branch	Description	Status
Main branch	6 editor tools (3 stable + 3 experimental)	Implemented
PR #1	Hot runner worker protocol — 5 transports, 13 C# files	Complete

Total new tests across Next-Gen PRs

PR	Tests
#790	43
#791	35
#798	36+
#799	42
Total	156+

Graduation Criteria

A Next-Gen feature graduates to stable when:

1. API has been stable for 2+ minor releases
2. At least 3 community users have validated the feature
3. Documentation is complete with real-world examples
4. Test coverage meets LTS standards
5. No breaking changes planned

---

All Related Feature Issues

Issue	Title	Status	Category
#788	Test Workflow Engine	Open	Next-Gen Feature
#789	Hot Runner Protocol	Open	Next-Gen Feature
#792	Generic Artifact System	Open	Next-Gen Feature
#793	Incremental Sync Protocol	Open	Next-Gen Feature
#796	Orchestrator Isolation	Open	Architecture
#797	Unity Editor Tooling	Open	Companion Milestone
#800	Community Plugin Validation	Open	CI Tooling
#801	Claude for Unity-Builder	Open	AI Assistance
#802	docs: massive projects	Open	Documentation
#803	docs: monorepo support	Open	Documentation
#812	Official CLI Support	Open	Tooling

---

Hierarchy

#810 (Orchestrator: The Endgame — top-level overview)
├── #794 (LTS v2.0.0)
│   └── #795 (Next-Gen Final Features) <-- you are here
│       ├── #788 (Test Workflow Engine)
│       ├── #789 (Hot Runner Protocol)
│       ├── #792 (Generic Artifact System)
│       ├── #793 (Incremental Sync Protocol)
│       ├── #796 (Orchestrator Isolation)
│       ├── #797 (Unity Editor Tooling)
│       ├── #800 (Community Plugin Validation)
│       ├── #802 (docs: massive projects)
│       ├── #803 (docs: monorepo support)
│       └── #812 (CLI support)
├── #811 (Help Bot)
└── #801 (Claude for Unity-Builder)

---

Integration PR

All next-gen feature PRs are combined into a single reviewable integration branch:

PR	Branch	Component PRs
#814	release/next-gen	#790, #791, #798, #799, #804, #813

This integration branch includes delete-me-update-this-integration-branch.ps1 and delete-me-update-all-integration-branches.ps1 scripts to keep it in sync with component branches.

The full LTS integration (including all infrastructure PRs) is available as #815 on release/lts-2.0.0.

[frostebite]

This is a tracking issue that aggregates next-gen experimental PRs (#790, #791, #798, #799) and documentation. No standalone PR needed — this issue tracks the experimental feature roadmap.