docs: consolidate canonical specs and preserve PBS reference IDs

This commit is contained in:
2026-10-28 15:11:00 +00:00
parent 9504f4694a
commit 3a3417eb44
74 changed files with 3231 additions and 270 deletions
+38 -16
View File
@@ -1,25 +1,47 @@
# General Specs
# General Compiler Specifications
This directory contains shared acceptance specifications for all supported languages in Prometeu.
Owner: `compiler/general`. Canonical source: `docs/specs/compiler`.
## Scope
These specifications define shared frontend/backend acceptance, compilation,
linking, typed handoff and emission. They apply across supported languages.
[Language contracts](../compiler-languages/pbs/README.md) define PBS rules and
refer to this layer for shared policy rather than duplicating it.
These specs are above language-specific specs and should be reused by each language line.
## Authority and reading order
Typical topics:
The runtime owns PBX binary layout, Core ISA, admission and VM execution.
Read the [mirror and provenance policy](../../vm-arch/README.md) for that boundary.
Chapters 24–25 own the detailed compiler catalog/typed-Registry consumer contracts;
earlier pipeline, verification and matrix chapters reference them for these topics.
Equal storage widths never replace logical identity or transfer runtime authority.
- conformance gates and evidence,
- compatibility publication policy,
- verification/safety acceptance boundaries,
- artifact/runtime acceptance contracts.
Start with pipeline entry points (23), then name/linking (14), typed handoff (25),
lowering/optimization (20–21), runtime/catalog integration (16, 18, 24), and
conformance/verification/compatibility (13, 17, 19, 22). Existing chapter numbers
are stable and do not imply language-version numbers.
Current backend-facing chapter additions:
## Chapter index
- `20. IRBackend to IRVM Lowering Specification.md`
- `21. IRVM Optimization Pipeline Specification.md`
- `22. Backend Spec-to-Test Conformance Matrix.md`
- `23. Compiler Pipeline Entry Points Specification.md`
- [13. Conformance Test Specification](13.%20Conformance%20Test%20Specification.md)
- [14. Name Resolution and Module Linking Specification](14.%20Name%20Resolution%20and%20Module%20Linking%20Specification.md)
- [15. Bytecode and PBX Mapping Specification](15.%20Bytecode%20and%20PBX%20Mapping%20Specification.md)
- [16. Runtime Execution and Initialization Specification](16.%20Runtime%20Execution%20and%20Initialization%20Specification.md)
- [17. Compatibility and Evolution Policy](17.%20Compatibility%20and%20Evolution%20Policy.md)
- [18. Standard Library Surface Specification](18.%20Standard%20Library%20Surface%20Specification.md)
- [19. Verification and Safety Checks Specification](19.%20Verification%20and%20Safety%20Checks%20Specification.md)
- [20. IRBackend to IRVM Lowering Specification](20.%20IRBackend%20to%20IRVM%20Lowering%20Specification.md)
- [21. IRVM Optimization Pipeline Specification](21.%20IRVM%20Optimization%20Pipeline%20Specification.md)
- [22. Backend Spec-to-Test Conformance Matrix](22.%20Backend%20Spec-to-Test%20Conformance%20Matrix.md)
- [23. Compiler Pipeline Entry Points Specification](23.%20Compiler%20Pipeline%20Entry%20Points%20Specification.md)
- [24. Runtime Catalog Support Specification](24.%20Runtime%20Catalog%20Support%20Specification.md)
- [25. Typed Registry and PBX v0 Specification](25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md)
## Rule
## Editorial and workflow rules
Language-specific specs (for example `docs/pbs/specs`) must reference this layer instead of duplicating cross-language acceptance policy.
Write specs in English with title, status, scope, authority, normative rules,
non-goals and conformance/exit criteria. Keep one owner per detailed contract;
summaries link to it. Only settled decisions may change normative behavior.
Agendas, decisions and plans live in `discussion/`, and completed teaching
material lives in `discussion/lessons/`; they are not parallel spec sources.
See the [specification guide](../README.md) for other domains.