238 lines
4.8 KiB
Markdown
238 lines
4.8 KiB
Markdown
# PR-9 — Final Hardening & Baseline Documentation
|
||
|
||
This phase finalizes the new Prometeu VM baseline after the architectural reset (GC, closures, coroutines, unified syscall ABI, deterministic scheduler).
|
||
|
||
Goals:
|
||
|
||
* Consolidated architecture documentation (short, precise, authoritative)
|
||
* Minimal and controlled public surface area
|
||
* Removal of temporary feature flags
|
||
* Final cleanup: dead code, warnings, outdated docs/examples
|
||
|
||
All PRs below are self-contained and must compile independently.
|
||
|
||
---
|
||
|
||
# PR-9.1 — Consolidated Architecture Documentation
|
||
|
||
## Briefing
|
||
|
||
The project must include a short, authoritative architecture document in English describing the new baseline.
|
||
|
||
It must reflect the current state only (no legacy, no transitional wording).
|
||
|
||
This document becomes the canonical reference for contributors.
|
||
|
||
## Target
|
||
|
||
Create `ARCHITECTURE.md` at repository root with sections:
|
||
|
||
1. Overview
|
||
|
||
* Stack-based VM
|
||
* GC-managed heap (mark-sweep, non-compacting)
|
||
* Closures (Model B, hidden arg0)
|
||
* Cooperative coroutines (FRAME_SYNC safepoints)
|
||
* Unified syscall ABI
|
||
|
||
2. Memory Model
|
||
|
||
* Stack vs heap
|
||
* Heap object kinds
|
||
* GC roots (VM + suspended coroutines)
|
||
|
||
3. Execution Model
|
||
|
||
* Interpreter loop
|
||
* Safepoints
|
||
* Scheduler behavior
|
||
|
||
4. Verification Model
|
||
|
||
* Verifier responsibilities
|
||
* Runtime vs verifier guarantees
|
||
|
||
5. Non-Goals
|
||
|
||
* No RC
|
||
* No HIP
|
||
* No preemption
|
||
* No mailbox
|
||
|
||
The document must be concise (no more than ~4–6 pages equivalent).
|
||
|
||
## Acceptance Checklist
|
||
|
||
* [ ] ARCHITECTURE.md exists.
|
||
* [ ] No mention of RC/HIP.
|
||
* [ ] Reflects actual implementation.
|
||
* [ ] Reviewed for consistency with code.
|
||
|
||
## Tests
|
||
|
||
Manual review required.
|
||
|
||
## Junie Instructions
|
||
|
||
You MAY:
|
||
|
||
* Create new documentation files.
|
||
|
||
You MUST NOT:
|
||
|
||
* Invent features not implemented.
|
||
* Reference legacy behavior.
|
||
|
||
If architecture details are unclear, STOP and request clarification.
|
||
|
||
---
|
||
|
||
# PR-9.2 — Public Surface Area Minimization
|
||
|
||
## Briefing
|
||
|
||
The public API must be minimal and intentional.
|
||
|
||
Internal modules must not leak implementation details.
|
||
|
||
## Target
|
||
|
||
1. Audit all `pub` items.
|
||
2. Reduce visibility to `pub(crate)` where possible.
|
||
3. Hide internal modules behind private boundaries.
|
||
4. Ensure only intended API is exported.
|
||
|
||
Focus areas:
|
||
|
||
* VM core
|
||
* Heap internals
|
||
* Scheduler internals
|
||
* GC internals
|
||
|
||
## Acceptance Checklist
|
||
|
||
* [ ] No unnecessary `pub` items.
|
||
* [ ] Public API documented.
|
||
* [ ] Internal types hidden.
|
||
* [ ] `cargo doc` shows clean public surface.
|
||
|
||
## Tests
|
||
|
||
* Build documentation.
|
||
* Ensure no accidental public modules remain.
|
||
|
||
## Junie Instructions
|
||
|
||
You MAY:
|
||
|
||
* Restrict visibility.
|
||
* Refactor module structure.
|
||
|
||
You MUST NOT:
|
||
|
||
* Break existing internal usage.
|
||
* Expose new APIs casually.
|
||
|
||
If removing `pub` causes architectural issue, STOP and escalate.
|
||
|
||
---
|
||
|
||
# PR-9.3 — Remove Temporary Feature Flags
|
||
|
||
## Briefing
|
||
|
||
During refactor phases, temporary feature flags or conditional compilation may have been introduced.
|
||
|
||
These must not remain in the final baseline.
|
||
|
||
## Target
|
||
|
||
1. Identify all feature flags related to transitional behavior.
|
||
2. Remove obsolete `cfg` gates.
|
||
3. Remove commented legacy branches.
|
||
4. Ensure single authoritative execution path.
|
||
|
||
## Acceptance Checklist
|
||
|
||
* [ ] No transitional feature flags remain.
|
||
* [ ] No commented-out legacy logic.
|
||
* [ ] Single execution model.
|
||
* [ ] All tests pass.
|
||
|
||
## Tests
|
||
|
||
* Full test suite passes without feature toggles.
|
||
|
||
## Junie Instructions
|
||
|
||
You MAY:
|
||
|
||
* Remove obsolete flags.
|
||
* Simplify code paths.
|
||
|
||
You MUST NOT:
|
||
|
||
* Remove legitimate platform flags.
|
||
* Leave partial dead branches.
|
||
|
||
If unsure whether a flag is temporary or architectural, STOP and ask.
|
||
|
||
---
|
||
|
||
# PR-9.4 — Final Cleanup & Quality Sweep
|
||
|
||
## Briefing
|
||
|
||
This PR performs the final cleanup pass.
|
||
|
||
Goal: Zero warnings. No dead code. No outdated examples.
|
||
|
||
## Target
|
||
|
||
1. Remove dead modules/files.
|
||
2. Remove unused imports and code.
|
||
3. Eliminate compiler warnings.
|
||
4. Update outdated examples.
|
||
5. Remove stale TODOs referencing removed architecture.
|
||
|
||
Optional (if present):
|
||
|
||
* Enforce `cargo clippy` clean baseline.
|
||
* Ensure `rustfmt` compliance.
|
||
|
||
## Acceptance Checklist
|
||
|
||
* [ ] No dead code.
|
||
* [ ] Zero compiler warnings.
|
||
* [ ] Clippy clean (if configured).
|
||
* [ ] Examples reflect new baseline.
|
||
* [ ] No TODO referencing RC/HIP.
|
||
|
||
## Tests
|
||
|
||
* Full test suite passes.
|
||
* Clean build with warnings denied (if configured).
|
||
|
||
## Junie Instructions
|
||
|
||
You MAY:
|
||
|
||
* Remove unused code.
|
||
* Refactor minor clarity issues.
|
||
|
||
You MUST NOT:
|
||
|
||
* Introduce new features.
|
||
* Change runtime semantics.
|
||
|
||
If cleanup requires semantic change, STOP and split into new PR.
|
||
|
||
---
|
||
|
||
## Final Definition of Done
|
||
|
||
* Architecture documented clearly.
|
||
* Public API minimal and controlled.
|
||
* No temporary flags remain.
|
||
* Codebase clean, warning-free, and aligned with the new VM baseline.
|