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
+55 -5
View File
@@ -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.