Research Alpha implementation inventory

This page records the complete implementation delivered for EXEPERT Research Alpha v0.4.0-alpha.1. It is an unreleased local-first research candidate, not a production deployment, package publication, billing launch, or hosted training service.

Delivered architecture

Area	Code	Delivered behavior
Deterministic runtime	src/research/runtime/	DOM-independent Runner kernel, seeded RNG streams, fixed-point state, snapshots, digests, trajectories, replay, and entitlement interfaces
Browser game adapter	src/ui/arcade/runner/RunnerScene.ts	Phaser renders and accepts input while runner-v1 owns human Runner transitions
Node worker	scripts/research/runner-worker.ts	Strict JSON-lines protocol over stdin/stdout for reset, step, snapshot, restore, ping, and close
Conformance runner	scripts/research/conformance.ts	Direct, browser-adapter, worker, and replay digest comparison across ten seeds and four action workloads
Python SDK	sdk/python/	Gymnasium environment, worker lifecycle, manifest validation, trajectory artifacts, and Stable-Baselines3 PPO CLI
Local research service	scripts/research/service.mjs	Loopback-only run lifecycle, SSE progress, confined artifact reads, one active predefined PPO process, origin and token checks
Local launcher	scripts/research/dev.mjs	Starts the Vite application and loopback service together with Windows process-tree cleanup
Runs workspace	src/ui/research-runs/	Lazy-loaded configuration, start/stop, progress, run inventory, downloads, import, and deterministic replay UI
Version surface	src/ui/version-badge.ts, index.html, vite.config.ts	Accessible version badge and panel populated from package.json, independent contract versions, and build commit
Open-core seam	src/research/runtime/entitlements.ts	Open environments run locally; entitled environments require an explicit provider decision and deny when unavailable

The primary application shell remains imperative TypeScript. React and Phaser stay confined to lazy UI islands, so the Research Runs workspace does not add React to the initial dashboard bundle.

Versioned contracts

Contract	Version	Compatibility rule
Application	0.4.0-alpha.1	SemVer prerelease from root package.json
Python package	0.4.0a1	PEP 440 mapping of the application version
Environment	exepert-runner@runner-v1	Changes when transition semantics change
Worker protocol	1.0.0	Versioned request and response envelopes
Manifest schema	1	Integer schema version
Trajectory schema	1	Integer schema version
Reward	reward-v1	+0.01 survival, +1 pickup, -1 collision

runner-v1 advances at 60 Hz using integer/fixed-point state. It accepts 0 = wait and 1 = jump, emits a normalized 12-value observation, terminates on collision, and truncates at no more than 10,800 steps. Each transition includes a deterministic state digest.

Worker, SDK, and run artifacts

The Node worker reserves stdout for protocol envelopes and sends sanitized diagnostics to stderr. Every response carries the request identifier, protocol version, and either a structured result or stable error code.

ExepertRunnerEnv exposes Discrete(2) actions and Box(12) observations. It owns worker startup, request timeouts, crash recovery, seed forwarding, manifest checks, and clean shutdown. The PPO example uses MlpPolicy, seed 42, and 50,000 timesteps by default; all values can be changed through the documented CLI.

Each ignored .exepert/runs/<run-id>/ directory contains the run manifest, dependency and environment versions, metrics, trajectory JSONL, summary, outcome, provenance, digests, and model checkpoint. Interrupted work is marked aborted instead of being presented as a completed run. Nothing is uploaded automatically.

Application and local-service behavior

The activity bar adds Research Runs as a lazy workspace. When the service is online, the UI can start one predefined PPO run, stream progress, stop it, inspect completed runs, download allowed artifacts, and replay compatible trajectories. When the service is absent, it shows the exact local startup command and leaves the rest of EXEPERT usable.

The service binds exclusively to 127.0.0.1:9013. Its controls include:

• a fixed local-origin allowlist and per-process session token;
• explicit request schemas and bounded request/output sizes;
• a fixed training command rather than arbitrary shell execution;
• one active process, with stop and shutdown cleanup;
• run-ID, extension, path, realpath, and symlink confinement;
• an allowlisted child-process environment that excludes repository secrets.

Vercel hosts only the static application and documentation. Supabase is not used by the Research Alpha runtime, service, SDK, or artifacts. Consequently, this implementation introduces no database migration, storage bucket, RLS policy, Edge Function, Vercel Function, or new hosted environment variable.

Existing-product compatibility

Dashboard, Brain, Chat, Prompt, Observability, Arcade, Journals, and existing authentication/data behavior remain available. AI Rescue keeps its existing consent-aware ai-rescue-v1 recorder, private-storage and deletion behavior; it is not redefined as the runner-v1 training contract in this alpha.

The deterministic guarantee is scoped to Runner environment transitions for the same environment version, seed, and actions. PPO weights are not promised to be bit-identical across hardware, operating systems, PyTorch, or BLAS stacks.

Repository and contribution changes

• Root package.json is the application-version source of truth and includes research:setup, research:serve, research:train, research:dev, worker, conformance, Python-test, and service-test commands.
• .gitignore excludes .exepert/, the Python environment, pytest cache, and Python bytecode.
• LICENSE retains MIT and records EXEPERTLABS copyright.
• CONTRIBUTING.md documents the development and testing contract.
• DCO contains Developer Certificate of Origin 1.1.
• .github/workflows/ci.yml verifies DCO trailers and runs the Research Alpha stack on Ubuntu 24.04 with Node 22, pnpm 9.15.4, Python 3.12, Chromium, Rust, and WASM.
• Playwright global setup supports an explicit offline bypass so Research Alpha tests never contact hosted Supabase.

Validation evidence

The implementation candidate passed:

• strict TypeScript typecheck;
• 266 Vitest cases, with six explicitly gated live tests skipped;
• 40 deterministic cross-adapter cases across ten seeds;
• local-service security and lifecycle tests;
• four Python/Gymnasium tests and a real 256-step PPO smoke run;
• Research Runs, Arcade, and responsive Playwright coverage;
• Cargo all-targets build and six workspace tests;
• WASM and Vite production build;
• documentation typecheck and direct Docusaurus build;
• Windows research:dev launcher smoke test;
• git diff --check, protected-file hashes, and secret-value scanning.

GitHub CI repeats the clean-clone Research Alpha gates with hosted integrations disabled. See the researcher quickstart for commands and the environment contract for transition semantics.

Deliberately excluded

This alpha does not implement hosted training, arbitrary job execution, multi-user orchestration, scheduling, autoscaling, registries, RBAC/SSO, audit storage, private networking, Stripe, billing, premium packs, package publishing, or automatic cloud upload. Those remain future extension points and require separate product, security, privacy, and release decisions.