Tracking: Architecture / runtime unification

[dowdiness]

Context

This is the canonical tracker for the architecture / runtime-unification sequence.
Use this issue to track PR order and boundary intent; keep detailed design in
docs/design/architecture-execution-plan-2026-06-12.md and
docs/design/architecture-redesign-2026-06-12.md.

The current architecture pressure is boundary clarity, not a full rewrite:

• the tree-walker remains the correctness oracle;
• bytecode is the long-term optimization path, not an independent semantic owner;
• closure conversion is legacy experimental evidence, not the destination;
• runtime operations should own observable JavaScript semantics;
• stdlib/compiler representation access is classified debt to retire over time;
• mutable state should remain owned by explicit interpreter/realm/host records.

Current baseline — 2026-06-25

Local reconciliation status:

• make architecture-audit exists and passes.
• Stage 0 guardrails are implemented: mutable-state audit, import-boundary audit,
  representation-access audit, and surface-taxonomy audit.
• Current audit baseline:
  • 73 local imports
  • 2 allowlisted import debts
  • 1294 classified representation-access sites
  • 13 generated-interface packages
  • 597 public symbols
  • 12 package-defaulted symbols
• scripts/architecture_representation_access.json is current as of the
  reconciliation refresh.
• Bytecode has file-level IR/lowering/VM separation:
  • compiler/bytecode_ir.mbt
  • compiler/bytecode_lower.mbt
  • compiler/bytecode_vm.mbt
• The bytecode/tree-walker equivalence harness exists in
  compiler/bytecode_test.mbt and unsupported labels are centralized as
  UNSUPPORTED_* constants in compiler/bytecode_ir.mbt.

Interpretation: the 1294 representation-access sites are classified debt, not
a solved boundary. Future architecture PRs should either shrink that number or
explain why it stays stable.

Current architecture PR sequence

Seq	PR / Issue	Goal	Boundary strengthened	Status	Required validation	Audit delta
PR0	#456	Reconcile architecture docs and representation inventory with current repo state	Planning / guardrails	merged	moon check; moon test; make architecture-audit; moon info; moon fmt; git diff --check	inventory current; audit passing
PR1	#245	Audit runtime state ownership and keep mutable state realm/host/interpreter-owned	State ownership	queued	moon check; moon test; make architecture-audit	state audit remains empty
PR2	#307 / PR #461	Migrate ToLength / ToIndex from Int to Int64	Spec-sized index semantics	merged	moon check; moon test; focused length/index tests; make architecture-audit; moon info; CI strict/non-strict Test262 shards	no accidental boundary growth
PR3	#439	Type environment markers before marker set grows	Environment marker ownership	conditional	moon check; moon test; make architecture-audit; delete-focused Test262 check if touched	no new ad-hoc marker strings

Status vocabulary

Use one of:

• queued
• active
• blocked
• review
• merged
• deferred
• conditional

#439 is intentionally conditional: do it when environment marker call sites
or marker kinds grow enough that string keys become an actual pressure.

Completed / reconciled items from the older tracker

These are no longer next-step blockers:

• static_semantics: encode preparation-input as a payload-carrying enum (reshape SourceKind), or delete the dead flat tag #331 — static-semantics preparation-input decision: closed.
• static_semantics: decide a file/naming cohesion convention before the package grows #332 — static-semantics file/naming cohesion convention: closed.
• Unify runtime [[OwnPropertyKeys]] enumerators (fix hole/hidden-key/descriptor-only divergences) #336 — unified runtime [[OwnPropertyKeys]] enumerators: closed.
• Reflect.set target-side [[Set]] pre-flight is patched externally, not unified into set_property #342 — Reflect.set pre-flight unification: closed.
• Gated perf: event-loop queues to @deque / @priority_queue (promise_core) #329 — gated event-loop queue perf change: closed.
• arch: type-safe slot keys for PropertyBag.internal_slots #360 — type-safe PropertyBag.internal_slots keys: closed by PR arch: type-safe InternalSlotKey enum for PropertyBag.internal_slots #455.
• PR0 baseline reconciliation: closed by PR arch: reconcile architecture baseline #456.
• Stage 0 audit tooling: implemented and passing via make architecture-audit.
• Stage 3 bytecode equivalence seed: implemented; future work is coverage-gap
  audit / typed result cleanup, not first-harness creation.

PR contract

Every PR in this sequence should include:

Architecture sequence: PR N of #392

Boundary strengthened:
- ...

Behavior changes:
- None / intentional: ...

Audit effect:
- import boundary: unchanged / changed
- representation inventory: unchanged / shrank by N / refreshed
- surface taxonomy: unchanged / changed

Validation:
- [ ] moon check
- [ ] moon test
- [ ] make architecture-audit
- [ ] moon info
- [ ] moon fmt
- [ ] git diff --check

Rollback:
- ...

Rules:

• Prefer behavior-preserving, reversible PRs.
• Do not combine architecture cleanup with unrelated conformance feature work.
• Do not expand closure conversion feature coverage except for bug fixes,
  benchmark maintenance, or retirement-support work.
• If a PR touches bytecode semantics, add or update tree-walker equivalence
  coverage in compiler/bytecode_test.mbt.
• If a PR changes public/generated surfaces, run moon info and explain the
  .mbti diff.
• If representation-access debt grows, the PR must justify why and identify the
  retirement stage.

Acceptance criteria for this tracker

This tracking issue can close when:

• PR0 baseline reconciliation is merged. ✅ PR arch: reconcile architecture baseline #456
• Audit runtime state ownership and keep mutable state realm/host-owned #245 is closed and mutable runtime/stdlib state remains explicitly owned by
  interpreter/realm/host records.
• Array index width: migrate ToLength/ToIndex from Int to Int64 for spec conformance #307 is closed and ToLength / ToIndex use a spec-sized representation. ✅ PR runtime: migrate array-like lengths to Int64 #461 (9b89b6c)
• arch: type environment markers before marker set grows #439 is either closed because marker pressure materialized, or explicitly left
  open as a conditional follow-up with no current marker-growth pressure.
• make architecture-audit passes.
• moon check && moon test pass.
• No regression in the relevant Test262 baseline for touched behavior.

Notes

• This tracker is internal architecture work. Conformance numbers should only be
  cited from CI artifacts / make test262-report, not copied from stale prose.
• The goal is reduced blast radius and clearer ownership, not aesthetic package
  reshuffling.

[dowdiness]

Reconciliation update from local architecture baseline check (2026-06-25):

• Do not open a duplicate architecture tracking issue; this tracker already exists.
• make architecture-audit is implemented and currently passes after refreshing scripts/architecture_representation_access.json.
• Current local audit baseline:
  • 73 local imports
  • 2 allowlisted import debts
  • 1294 classified representation-access sites
  • 13 generated-interface packages
  • 597 public symbols
  • 12 package-defaulted symbols
• Important correction: representation access is classified and visible, not retired. The 1294 classified accesses are the debt baseline that Stages 7-12 should shrink.
• Bytecode has file-level IR/lowering/VM separation (compiler/bytecode_ir.mbt, compiler/bytecode_lower.mbt, compiler/bytecode_vm.mbt). Treat further package splitting as a boundary decision, not unstarted discovery.
• The bytecode/tree-walker equivalence harness already exists in compiler/bytecode_test.mbt; future bytecode semantic work should extend it rather than create a new harness.

Local docs were reconciled in docs/design/architecture-execution-plan-2026-06-12.md and docs/design/architecture-redesign-2026-06-12.md to reflect this baseline.

[dowdiness]

PR1 update: #245 is closed by PR #458 (e054332, 2026-06-25).

• Added docs/design/runtime-state-ownership-audit-2026-06-25.md with the runtime/stdlib mutable-state owner map.
• Mutable-state audit remains empty: 0 classified runtime/stdlib module-level mutable bindings.
• Full architecture audit baseline after the merge: 73 imports, 2 allowlisted import debts, 1294 classified representation-access sites, 13 generated-interface packages, 600 public symbols, 12 package-defaulted symbols.

Next in this tracker: #307 ToLength / ToIndex Int64 migration. #439 remains conditional.

[dowdiness]

PR2 update: #307 is closed by PR #461 (squash commit 9b89b6c, 2026-06-25).\n\n- Runtime ToLength/ToIndex and array-like length/index helpers now use Int64.\n- Sparse/high-index array semantics were fixed for Array methods, species creation, DefineOwnProperty, own-key ordering, and TypedArray/DataView/ArrayBuffer bounds conversion.\n- Removed the int64-array-index (#307) Test262 skip entries.\n- CI for #461 was green before squash merge: unit tests, regression-check, bench, and all strict/non-strict Test262 shards passed.\n\nNext in this tracker: #439 remains conditional; do a quick marker-pressure check before starting it, and defer if no new marker kinds/call sites have appeared.