docs: consolidate canonical specs and preserve PBS reference IDs
This commit is contained in:
@@ -1,5 +1,7 @@
|
||||
# PBS Specs
|
||||
|
||||
Owner: `compiler/pbs`. Canonical source: `docs/specs/compiler-languages/pbs`.
|
||||
|
||||
This directory contains the normative PBS specification set.
|
||||
|
||||
## Installed Quickstart (Informative)
|
||||
@@ -82,7 +84,7 @@ Specs define the official PBS language/frontend contract.
|
||||
They exist to make behavior, constraints, and interfaces stable across implementations and reviews.
|
||||
|
||||
Cross-language acceptance rules are not defined here.
|
||||
Those are maintained in `docs/general/specs`.
|
||||
Those are maintained in `docs/specs/compiler`.
|
||||
|
||||
## Expected Format
|
||||
|
||||
@@ -143,12 +145,60 @@ That means:
|
||||
- and Studio/LSP consume that contract without becoming owners of PBS semantic presentation assets.
|
||||
|
||||
The `@sdk:random` module exports `Random` and `random`. Use an explicit long seed;
|
||||
copying a generator shares its state. Read `pbs:spec:runtime-random-integration.md`
|
||||
copying a generator shares its state. Read `pbs:spec:20`
|
||||
and `pbs:example:game:1:src/random.pbs` for the exact contract and a small example.
|
||||
|
||||
|
||||
## Parameterized contracts
|
||||
|
||||
Parameterized nominal contracts, concrete frontend specialization, implementation/coercion rules, composition, recursion and production conformance are defined by the owner specification.
|
||||
## Authority and reading order
|
||||
|
||||
See [PBS generic contracts](../../../compiler/pbs/specs/generic-contracts.md).
|
||||
Read syntax and static semantics (3–4), module/SDK resolution (5), host/intrinsic
|
||||
boundaries (6–8), execution/memory (9–10), and compiler projections (11–13).
|
||||
Thematic chapters 14–25 own their complete feature contracts. Base chapters
|
||||
retain syntax, AST, diagnostics and lowering responsibilities and refer to those
|
||||
owners for detailed rules. The accepted explicit-initialization rule in chapter 17
|
||||
applies to every completing ordinary/generic constructor, including Random fields.
|
||||
|
||||
[General compiler specifications](../../compiler/README.md) own shared handoff
|
||||
and acceptance; the [runtime mirror policy](../../../vm-arch/README.md) identifies
|
||||
the provider's separate ABI/execution authority. Keep those boundaries explicit.
|
||||
|
||||
## Chapter index
|
||||
|
||||
- [1. Language Charter](1.%20Language%20Charter.md)
|
||||
- [2. Governance and Versioning](2.%20Governance%20and%20Versioning.md)
|
||||
- [3. Core Syntax Specification](3.%20Core%20Syntax%20Specification.md)
|
||||
- [4. Static Semantics Specification](4.%20Static%20Semantics%20Specification.md)
|
||||
- [5. Manifest, Stdlib, and SDK Resolution Specification](5.%20Manifest%2C%20Stdlib%2C%20and%20SDK%20Resolution%20Specification.md)
|
||||
- [6. VM-owned vs Host-backed](6.%20VM-owned%20vs%20Host-backed.md)
|
||||
- [6.1. Intrinsics and Builtin Types Specification](6.1.%20Intrinsics%20and%20Builtin%20Types%20Specification.md)
|
||||
- [6.2. Host ABI Binding and Loader Resolution Specification](6.2.%20Host%20ABI%20Binding%20and%20Loader%20Resolution%20Specification.md)
|
||||
- [7. Cartridge Manifest and Runtime Capabilities Specification](7.%20Cartridge%20Manifest%20and%20Runtime%20Capabilities%20Specification.md)
|
||||
- [8. Stdlib Environment Packaging and Loading Specification](8.%20Stdlib%20Environment%20Packaging%20and%20Loading%20Specification.md)
|
||||
- [9. Dynamic Semantics Specification](9.%20Dynamic%20Semantics%20Specification.md)
|
||||
- [10. Memory and Lifetime Specification](10.%20Memory%20and%20Lifetime%20Specification.md)
|
||||
- [11. AST Specification](11.%20AST%20Specification.md)
|
||||
- [12. Diagnostics Specification](12.%20Diagnostics%20Specification.md)
|
||||
- [13. Lowering IRBackend Specification](13.%20Lowering%20IRBackend%20Specification.md)
|
||||
- [14. Typed Arrays and Optional Execution Specification](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md)
|
||||
- [15. First-Class Functions and Captures Specification](15.%20First-Class%20Functions%20and%20Captures%20Specification.md)
|
||||
- [16. Generic Contracts Specification](16.%20Generic%20Contracts%20Specification.md)
|
||||
- [17. Generic Structs and Free Functions Specification](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md)
|
||||
- [18. Input and Existing Type Runtime Alignment Specification](18.%20Input%20and%20Existing%20Type%20Runtime%20Alignment%20Specification.md)
|
||||
- [19. Service Constants and Runtime Math Specification](19.%20Service%20Constants%20and%20Runtime%20Math%20Specification.md)
|
||||
- [20. Runtime Random Integration Specification](20.%20Runtime%20Random%20Integration%20Specification.md)
|
||||
- [21. SDK List and Cursor Specification](21.%20SDK%20List%20and%20Cursor%20Specification.md)
|
||||
- [22. SDK Linked and Cursor Specification](22.%20SDK%20Linked%20and%20Cursor%20Specification.md)
|
||||
- [23. SDK Set and Identity Specification](23.%20SDK%20Set%20and%20Identity%20Specification.md)
|
||||
- [24. SDK Map and Keyval Specification](24.%20SDK%20Map%20and%20Keyval%20Specification.md)
|
||||
- [25. SDK Stack and Queue Specification](25.%20SDK%20Stack%20and%20Queue%20Specification.md)
|
||||
|
||||
## Installed reference compatibility
|
||||
|
||||
Each numbered chapter is indexed as `pbs:spec:<number>`; this README is
|
||||
`pbs:quickstart`. Published filename-based IDs for chapters 14–25 remain aliases
|
||||
of the same canonical packaged text and hash. New callers should use the numbered
|
||||
IDs returned by project context. The alias catalog is generated by the frontend
|
||||
build from this single source directory. It does not read a second spec tree.
|
||||
The internal resource path is `pbs-knowledge/specs/<numbered filename>.md`;
|
||||
reference clients resolve IDs through the catalog instead of constructing paths.
|
||||
|
||||
Reference in New Issue
Block a user