quality baseline

This commit is contained in:
2026-03-24 13:40:35 +00:00
parent e2a970e69c
commit c7786fa8b0
90 changed files with 3076 additions and 1334 deletions
+25
View File
@@ -0,0 +1,25 @@
# Prometeu Runtime — Architecture (Reset Invariants)
This document captures the high-level invariants for the reset cycle. It is a stub and will
evolve as we formalize the new ISA/VM specs. The goal is to define non-negotiable properties
that guide refactors without forcing legacy compatibility.
Core invariants
---------------
- Stack-based VM with heap-allocated objects.
- Garbage Collection happens at safepoints, primarily at `FRAME_SYNC`.
- Closures are first-class (user functions). Syscalls are callable but not first-class values.
- Coroutines are the only concurrency model.
- No backward compatibility: old bytecode formats, shims, or legacy bridges are out of scope.
Scope of this stage
-------------------
- Establish tooling baselines (fmt, clippy, CI) and minimal smoke tests.
- Avoid encoding legacy ISA semantics in tests; keep tests focused on build confidence.
- Production code must remain free from test-only hooks; use dev-only utilities for determinism.
Out of scope (for now)
----------------------
- Detailed ISA definition and instruction semantics beyond what is needed to compile and run
smoke-level validations.
- Performance tuning or GC algorithm selection.
-15
View File
@@ -1,15 +0,0 @@
# PROMETEU Documentation
This directory contains the technical documentation and specifications for the PROMETEU project.
## Content
### 📜 [Specifications (Specs)](./specs)
Detailed documentation on system architecture, cartridge format, VM instruction set, and more.
- [Topic Index](specs/hardware/topics/table-of-contents.md)
### 🐞 [Debugger](./debugger)
Documentation on debugging tools and how to integrate new tools into the ecosystem.
### 🔌 [DevTools Protocol](../devtools)
Definition of the communication protocol used for real-time debugging and inspection.
+49
View File
@@ -0,0 +1,49 @@
# Prometeu Runtime — Style Guide
This document defines the baseline code style and commenting policy for the reset cycle.
Goals:
- Professional, consistent, and readable code.
- Deterministic and actionable error messages.
- English-only comments and docs.
General principles
------------------
- Rust edition: use the crate’s configured edition (currently 2024 across new crates).
- Keep modules small and cohesive; prefer explicit interfaces over glob imports.
- Avoid premature abstraction; refactor when duplication becomes meaningful.
Comments and documentation
--------------------------
- Language: English only.
- Use `///` for public API documentation comments and module-level docs (`//!`).
- Use `//` for local/internal notes that do not need to surface in docs.
- Write comments that explain “why,” not “what” (the code already shows “what”).
- Keep comments up to date with behavior; outdated comments should be removed or fixed.
Error messages
--------------
- Be clear, actionable, and deterministic.
- Include the failing condition and the expected invariant when useful.
- Avoid leaking internal jargon; prefer user-understandable phrasing.
- Do not rely on timing or nondeterminism for error reproduction.
Naming conventions
------------------
- Crates and modules: `kebab-case` for crates, `snake_case` for modules and files.
- Types and traits: `PascalCase` (e.g., `VirtualMachine`, `BytecodeLoader`).
- Functions, methods, and variables: `snake_case`.
- Constants and statics: `SCREAMING_SNAKE_CASE`.
- Avoid abbreviations unless they are widely recognized (e.g., `pc`, `vm`).
Documentation structure
-----------------------
- Each public crate should have a crate-level docs section describing its purpose.
- Prefer small examples in docs that compile (use `rustdoc` code blocks when feasible).
- Keep module/file headers brief and focused.
Formatting and linting
----------------------
- `cargo fmt` is the source of truth for formatting.
- `cargo clippy` should run clean on the default toolchain. Where a lint is intentionally
violated, add a focused `#[allow(lint_name)]` with a short rationale.
-19
View File
@@ -1,19 +0,0 @@
### Phase 03 — Frontend API Boundary (Canon Contract)
This document codifies the FE/BE boundary invariants for Phase 03.
- BE is the source of truth. The `frontend-api` crate defines canonical models that all Frontends must produce.
- No string protocols across layers. Strings are only for display/debug. No hidden prefixes like `svc:` or `@dep:`.
- No FE implementation imports from other FE implementations.
- No BE imports PBS modules (hard boundary). The Backend consumes only canonical data structures from `frontend-api`.
- Overload resolution is signature-based. Arity alone is not sufficient; use canonical signatures/keys.
Implementation notes (PBS):
- The PBS adapter must not synthesize ownership or module info from string prefixes. All owner/module data should come from canonical types.
- Export/import surfaces are expressed exclusively via `frontend-api` types (e.g., `ItemName`, `ProjectAlias`, `ModulePath`, `ImportRef`, `ExportItem`).
Enforcement:
- A test in `prometeu-build-pipeline` scans `src/backend/**` to ensure no references to `frontends::pbs` are introduced.
- Code review should reject any PRs that reintroduce prefix-based heuristics or FE-to-FE coupling.