quality baseline
This commit is contained in:
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user