Repository navigation
[RFC]: TypeScript migration direction for the LoopX control-plane core #3225
Description
Summary
LoopX upstream is evaluating a TypeScript migration direction for the
control-plane core. This is an early-stage coordination anchor, not a
committed rewrite. The goal is to align upstream plans with external efforts
instead of letting parallel ports diverge.
Why now
- External projects are already porting the LoopX kernel to TypeScript. The
most complete sketch is Foreman PR #1,
which migrates event state, todo lifecycle, gates, quota, scheduler/monitor,
Turn envelope, and handoff to native TypeScript with a pinned upstream
authority commit. - The frontstage/dashboard surface is already TypeScript; a shared runtime
would simplify CLI distribution and host integration. - A public RFC anchor lets external contributors coordinate instead of forking.
Candidate scope (contract-first)
If pursued, the migration should preserve these surfaces with parity fixtures:
- append-only event state and idempotent writes;
- todo lifecycle (claim, lease, status, revision, completion validation);
- gates and decision scope;
- quota (
should-run/ spend) and scheduler/monitor contracts; - Turn envelope / transaction semantics;
- handoff and review-packet projection;
- CLI and status/quota JSON parity.
Non-goals
- No behavior change; Python remains the canonical implementation during any
transition. - No new protocol fields without parity fixtures.
- No fork-first migration: upstream-owned, contribution-friendly.
Open questions
- Runtime choice: Node.js, Bun, or Deno?
- Packaging/distribution: npm package, pip shim, or both?
- Coexistence strategy: dual implementation with parity tests, or phased
replacement by surface? - Contributor ownership and review lane for the TypeScript track.
Next steps
- Collect alignment in this issue.
- If accepted, open a formal RFC document under
docs/architecture/rfcs/with a characterization/parity plan. - Invite Foreman PR #1 as the
starting reference implementation and coordinate its author upstream.
Feedback on scope, non-goals, and runtime choice is welcome.
Activity
huangruiteng commentedon Aug 15, 2026
The migration question from the "open questions" section now has a formal proposal: RFC: TypeScript Control-Plane Migration Direction v0 (
docs/architecture/rfcs/typescript-control-plane-migration-v0.md, EN + zh-CN).Short answer to "can Python and TypeScript call each other?" — yes, but over a process boundary with versioned JSON contracts, not in-process imports. The proposal is a contract-first, parity-gated, block-by-block migration over three seams that already exist in the repo:
pi_goal_mode(Pi extension already delegates quota decisions to the Python CLI);quota_should_run_parityfixture template plusdecision_replayand CLI output differential contracts;event_store_migration_bridgedual-read/canary/rollback gates.Migration order: contract freeze → read paths/projections → deterministic decision kernels (quota
should-run, todo lifecycle, scheduler transitions) → event store and write paths last. Python remains canonical during the transition; every block flips only behind a parity gate with a recorded rollback plan.Feedback on the RFC is welcome, especially on runtime choice (Node/Bun/Deno), packaging, and contributor ownership for the TypeScript track.
docs(rfc): add TypeScript control-plane migration RFC (#3225) (#3226)