docs: consolidate canonical specs and preserve PBS reference IDs
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user