pr6.5
This commit is contained in:
+492
-80
@@ -1,83 +1,3 @@
|
||||
# PR-6.5 — Verifier Support for Closures (Model B)
|
||||
|
||||
## Briefing
|
||||
|
||||
The verifier must understand closure values and enforce safe invocation rules.
|
||||
|
||||
Under Model B:
|
||||
|
||||
* `CALL_CLOSURE` injects hidden `arg0`.
|
||||
* User-visible arg_count excludes hidden arg.
|
||||
* Captures are accessed via explicit instructions (future PR).
|
||||
|
||||
---
|
||||
|
||||
## Target
|
||||
|
||||
Extend verifier to:
|
||||
|
||||
1. Introduce stack type: `ClosureValue`.
|
||||
2. Validate MAKE_CLOSURE effects.
|
||||
3. Validate CALL_CLOSURE semantics:
|
||||
|
||||
* Ensure top of stack is ClosureValue.
|
||||
* Ensure sufficient args present.
|
||||
* Validate `arg_count` matches function signature expectations.
|
||||
* Account for hidden arg0 when checking callee arg arity.
|
||||
4. Validate ret_slots against function metadata.
|
||||
|
||||
---
|
||||
|
||||
## Work Items
|
||||
|
||||
1. Extend type lattice with ClosureValue.
|
||||
2. Define stack transitions for MAKE_CLOSURE.
|
||||
3. Define stack transitions for CALL_CLOSURE.
|
||||
4. Enforce strict failure on mismatch.
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Checklist
|
||||
|
||||
* [ ] ClosureValue type exists.
|
||||
* [ ] Invalid CALL_CLOSURE rejected.
|
||||
* [ ] Hidden arg0 accounted for.
|
||||
* [ ] ret_slots validated.
|
||||
* [ ] All verifier tests pass.
|
||||
|
||||
---
|
||||
|
||||
## Tests
|
||||
|
||||
1. Valid closure call passes verification.
|
||||
2. CALL_CLOSURE with wrong arg_count fails.
|
||||
3. CALL_CLOSURE on non-closure fails verification.
|
||||
4. Nested closure calls verify correctly.
|
||||
|
||||
---
|
||||
|
||||
## Junie Instructions
|
||||
|
||||
You MAY:
|
||||
|
||||
* Extend verifier model.
|
||||
* Add tests.
|
||||
|
||||
You MUST NOT:
|
||||
|
||||
* Weaken verification rules.
|
||||
* Replace verifier checks with runtime-only traps.
|
||||
|
||||
If function metadata (arg_slots/ret_slots) is insufficient, STOP and request clarification.
|
||||
|
||||
---
|
||||
|
||||
## Definition of Done
|
||||
|
||||
Verifier fully supports closure creation and invocation under Model B semantics.
|
||||
|
||||
---
|
||||
|
||||
# PR-7 — Coroutines (Cooperative, Deterministic, No Mailbox)
|
||||
|
||||
Coroutines are the **only concurrency model** in the Prometeu VM.
|
||||
@@ -413,3 +333,495 @@ Tests must not depend on wall clock or randomness.
|
||||
* No mailbox.
|
||||
* GC and verifier fully integrated.
|
||||
* All tests pass.
|
||||
|
||||
---
|
||||
|
||||
# PR-8 — Tooling & Test Harness (JVM-Grade Discipline)
|
||||
|
||||
This phase establishes tooling and test discipline required to keep the Prometeu VM at JVM-grade quality.
|
||||
|
||||
Goals:
|
||||
|
||||
* Deterministic execution
|
||||
* Reproducible tests
|
||||
* Strong disassembler guarantees
|
||||
* Layered test coverage
|
||||
* Zero legacy artifacts enforcement
|
||||
|
||||
Each PR below is self-contained and must compile independently.
|
||||
|
||||
---
|
||||
|
||||
# PR-8.1 — Disassembler (Roundtrip + Snapshot Reliability)
|
||||
|
||||
## Briefing
|
||||
|
||||
The disassembler must be:
|
||||
|
||||
* Deterministic
|
||||
* Complete
|
||||
* Roundtrip-safe (encode → decode → encode)
|
||||
* Snapshot-friendly
|
||||
|
||||
It must fully support:
|
||||
|
||||
* New opcodes (MAKE_CLOSURE, CALL_CLOSURE, SPAWN, YIELD, SLEEP)
|
||||
* Updated syscall representation
|
||||
* Closure and coroutine instructions
|
||||
|
||||
## Target
|
||||
|
||||
1. Update disassembler to support all new opcodes.
|
||||
2. Guarantee stable formatting.
|
||||
3. Add roundtrip validation tests.
|
||||
|
||||
Formatting rules:
|
||||
|
||||
* No unstable ordering.
|
||||
* No implicit formatting differences across platforms.
|
||||
* Explicit numeric representation where required.
|
||||
|
||||
## Acceptance Checklist
|
||||
|
||||
* [ ] All opcodes supported.
|
||||
* [ ] Deterministic formatting.
|
||||
* [ ] Roundtrip encode/decode test passes.
|
||||
* [ ] Snapshot tests stable.
|
||||
|
||||
## Tests
|
||||
|
||||
1. Encode → disasm → reassemble → byte-equal check.
|
||||
2. Snapshot test for representative programs.
|
||||
3. Closure/coroutine disasm coverage.
|
||||
|
||||
## Junie Instructions
|
||||
|
||||
You MAY:
|
||||
|
||||
* Modify disassembler module.
|
||||
* Add snapshot tests.
|
||||
|
||||
You MUST NOT:
|
||||
|
||||
* Change bytecode encoding format.
|
||||
* Introduce formatting randomness.
|
||||
|
||||
If any opcode semantics unclear, STOP and ask.
|
||||
|
||||
---
|
||||
|
||||
# PR-8.2 — Deterministic Execution Harness
|
||||
|
||||
## Briefing
|
||||
|
||||
The VM must be testable deterministically.
|
||||
|
||||
Requirements:
|
||||
|
||||
* No wall-clock time.
|
||||
* Controlled tick progression.
|
||||
* Fixed seed where randomness exists (if any).
|
||||
|
||||
## Target
|
||||
|
||||
Introduce a test harness wrapper:
|
||||
|
||||
* Controlled `tick` counter.
|
||||
* Deterministic scheduler stepping.
|
||||
* Explicit run_budget boundaries.
|
||||
|
||||
Provide utilities:
|
||||
|
||||
* `run_until_halt()`
|
||||
* `run_ticks(n)`
|
||||
* `run_frames(n)`
|
||||
|
||||
No external timing.
|
||||
|
||||
## Acceptance Checklist
|
||||
|
||||
* [ ] No real-time dependencies.
|
||||
* [ ] Deterministic coroutine wake order.
|
||||
* [ ] Repeatable runs produce identical traces.
|
||||
|
||||
## Tests
|
||||
|
||||
1. Same program run twice produces identical state traces.
|
||||
2. Sleep/wake ordering stable.
|
||||
|
||||
## Junie Instructions
|
||||
|
||||
You MAY:
|
||||
|
||||
* Extend test harness.
|
||||
* Add deterministic trace utilities.
|
||||
|
||||
You MUST NOT:
|
||||
|
||||
* Introduce randomness.
|
||||
* Use system time.
|
||||
|
||||
If current VM depends on real time, STOP and refactor before proceeding.
|
||||
|
||||
---
|
||||
|
||||
# PR-8.3 — Layered Test Suite Architecture
|
||||
|
||||
## Briefing
|
||||
|
||||
Tests must be structured by layer to isolate failures.
|
||||
|
||||
Layers:
|
||||
|
||||
1. Bytecode encode/decode
|
||||
2. Verifier
|
||||
3. VM execution
|
||||
4. GC behavior
|
||||
5. Scheduler behavior
|
||||
|
||||
## Target
|
||||
|
||||
Organize tests into modules per layer.
|
||||
|
||||
Enforce:
|
||||
|
||||
* No cross-layer assumptions.
|
||||
* Verifier tests do not execute VM.
|
||||
* VM tests assume verified input.
|
||||
|
||||
Add minimal coverage per layer.
|
||||
|
||||
## Acceptance Checklist
|
||||
|
||||
* [ ] Tests grouped logically.
|
||||
* [ ] No duplicated logic.
|
||||
* [ ] Clear separation of concerns.
|
||||
|
||||
## Tests
|
||||
|
||||
Add representative tests per layer:
|
||||
|
||||
* Encode/decode edge cases.
|
||||
* Verifier rejects invalid closures.
|
||||
* VM executes valid programs.
|
||||
* GC collects unreachable closures.
|
||||
* Scheduler deterministic ordering.
|
||||
|
||||
## Junie Instructions
|
||||
|
||||
You MAY:
|
||||
|
||||
* Refactor test layout.
|
||||
* Add missing coverage.
|
||||
|
||||
You MUST NOT:
|
||||
|
||||
* Merge unrelated layers.
|
||||
* Hide verifier failures inside runtime traps.
|
||||
|
||||
If a test spans layers, STOP and split appropriately.
|
||||
|
||||
---
|
||||
|
||||
# PR-8.4 — No Legacy Artifacts Enforcement
|
||||
|
||||
## Briefing
|
||||
|
||||
The codebase must not contain legacy RC/HIP artifacts.
|
||||
|
||||
Forbidden patterns:
|
||||
|
||||
* retain
|
||||
* release
|
||||
* hip
|
||||
* gate
|
||||
* borrow
|
||||
* scope (legacy usage context)
|
||||
* RC-related modules
|
||||
|
||||
## Target
|
||||
|
||||
Implement automated check:
|
||||
|
||||
* Script or test that scans source tree for forbidden symbols.
|
||||
* Fails CI if found.
|
||||
|
||||
Also:
|
||||
|
||||
* Remove dead modules/files.
|
||||
* Remove unused features.
|
||||
|
||||
## Acceptance Checklist
|
||||
|
||||
* [ ] Automated legacy scan exists.
|
||||
* [ ] No legacy symbols present.
|
||||
* [ ] Dead modules removed.
|
||||
|
||||
## Tests
|
||||
|
||||
1. Intentionally insert forbidden symbol in test branch → test fails.
|
||||
2. Scan passes on clean tree.
|
||||
|
||||
## Junie Instructions
|
||||
|
||||
You MAY:
|
||||
|
||||
* Add static scan test.
|
||||
* Remove dead code.
|
||||
|
||||
You MUST NOT:
|
||||
|
||||
* Suppress warnings instead of fixing code.
|
||||
* Leave deprecated modules commented out.
|
||||
|
||||
If unsure whether a symbol is legacy or valid, STOP and ask.
|
||||
|
||||
---
|
||||
|
||||
## Final Definition of Done
|
||||
|
||||
* Disassembler roundtrip-safe.
|
||||
* Deterministic harness in place.
|
||||
* Layered test suite established.
|
||||
* No legacy artifacts remain.
|
||||
* All tests reproducible and stable.
|
||||
|
||||
---
|
||||
|
||||
# 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.
|
||||
|
||||
@@ -1,8 +0,0 @@
|
||||
vamos as PR9s todas em um unico canvas markdown ingles, devem ser auto contidas com briefing, alvo, checklist, test quando necessario e comandos do que a Junie pode ou nao fazer (Junie eh task operator nao arquiteta ou assume nada, questiona quando necessario).
|
||||
|
||||
9 — Hardening final e documentação do novo baseline
|
||||
|
||||
9.1. Consolidar documentação de arquitetura (curta, objetiva, em inglês).
|
||||
9.2. Garantir que o “surface area” público está minimalista (APIs internas escondidas).
|
||||
9.3. Remover qualquer feature flag temporária que tenha sobrado.
|
||||
9.4. Rodar limpeza final: dead code, warnings, docs desatualizadas, exemplos antigos.
|
||||
Reference in New Issue
Block a user