[RFC]: TypeScript migration direction for the LoopX control-plane core

[huangruiteng]

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

1. Collect alignment in this issue.
2. If accepted, open a formal RFC document under
   docs/architecture/rfcs/ with a characterization/parity plan.
3. Invite Foreman PR #1 as the
   starting reference implementation and coordinate its author upstream.

Feedback on scope, non-goals, and runtime choice is welcome.

[huangruiteng]

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:

1. the production TS→Python CLI boundary in pi_goal_mode (Pi extension already delegates quota decisions to the Python CLI);
2. the quota_should_run_parity fixture template plus decision_replay and CLI output differential contracts;
3. the versioned append-only event store and the event_store_migration_bridge dual-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.