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
+36
View File
@@ -0,0 +1,36 @@
# Specification Guide
Specifications live under this tree and are organized by contract owner:
| Owner | Canonical corpus | Responsibility |
| --- | --- | --- |
| `compiler/general` | [General compiler](compiler/README.md) | Shared compilation, linking, typed handoff, emission and acceptance |
| `compiler/pbs` | [PBS language](compiler-languages/pbs/README.md) | PBS source, semantics, SDK and frontend projections |
| `packer` | [Packer](packer/README.md) | Assets, artifacts, packing and diagnostics |
| `studio` | [Studio](studio/README.md) | Shell, workspaces, adapters and visual/automation integration |
New compiler languages receive their own corpus under `compiler-languages/`.
Shared compiler policy stays in `compiler/`; PBS is not the root for other domains.
Each domain README provides a chapter index and reading order. Numbered chapters
are normative within their stated scope. Feature chapters own their detailed
contracts; cross-cutting chapters reference those rules rather than maintaining
competing versions. Write specifications and durable lessons in English.
The runtime repository owns PBX, ISA, admission and VM execution. Studio's
[VM architecture references and catalog mirrors](../vm-arch/README.md) retain
their separate provenance and synchronization policy. [Roadmaps](../roadmaps/)
describe cross-domain planning, not an alternative contract source.
The operational lifecycle is `agenda -> decision -> plan -> implement -> lesson`.
Keep its artifacts in `discussion/` and use the local `discussion` CLI for state
transitions, validation and housekeeping. See [repository instructions](../../AGENTS.md).
## Navigation verification
Run `python3 tools/documentation/verify.py` from the repository root to check local
links and anchors. Pass `--runtime ../runtime` to also check provider references
against an available read-only runtime checkout. The byte-exact architecture/ISA
mirrors retain the link context of their runtime originals; the checker resolves
them there. Ordinary builds and installed documentation reads do not require that
checkout.
@@ -82,7 +82,7 @@ Before implementation starts, PBS must define at least:
7. AST Specification.
8. Diagnostics Specification.
9. Lowering IRBackend Specification.
10. Shared acceptance specs in `docs/general/specs` (Conformance, Compatibility, Verification).
10. Shared acceptance specs in `docs/specs/compiler` (Conformance, Compatibility, Verification).
## 11. Decision Rule
@@ -39,8 +39,8 @@ This document does not define:
Normative precedence:
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
1. Runtime authority ([provider specifications](../../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../../vm-arch/README.md))
2. Bytecode authority ([provider Core ISA](../../../../../runtime/docs/vm-arch/ISA_CORE.md))
3. `1. Language Charter.md`
4. `3. Core Syntax Specification.md`
5. `4. Static Semantics Specification.md`
@@ -126,7 +126,7 @@ They are runtime views over an underlying identity-bearing value together with t
### 7.5 Function values and closures
Closures are ordinary managed objects retaining their typed captures. Reachable closures may survive across frames; unreachable closures are eligible for GC. Their invocations do not suspend across frames. See [First-class functions and explicit value captures](../../../compiler/pbs/specs/first-class-functions-and-captures.md).
Closures are ordinary managed objects retaining their typed captures. Reachable closures may survive across frames; unreachable closures are eligible for GC. Their invocations do not suspend across frames. See [First-class functions and explicit value captures](15.%20First-Class%20Functions%20and%20Captures%20Specification.md).
## 8. Identity, Aliasing, and Copy Behavior
@@ -177,7 +177,7 @@ At minimum, those roots include:
- currently active local/frame state,
- reachable fields of reachable struct instances,
- service singleton roots,
- retained callback state that remains reachable,
- retained closure state that remains reachable,
- and any other runtime roots required to preserve already-observable PBS behavior.
If a GC-managed value remains reachable through the normative runtime state, the implementation must preserve its continued semantic availability.
@@ -325,4 +325,7 @@ This document is ready to move beyond temporary draft status only when:
## Typed arrays and optional execution extension
The [typed arrays and optional execution specification](../../../compiler/pbs/specs/typed-arrays-and-optional-execution.md) defines array types/construction/indexing, contextual literals, optional bindings and runtime storage. Its rules extend this specification, including source typing, complete groups, Struct/contract execution and diagnostics.
The [Array owner chapter](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md)
defines the complete type, optional-flow and storage contract.
This chapter supplies shared reachability and ownership rules; Array storage
and complete-group packing are defined by that owner.
@@ -180,23 +180,27 @@ This document is healthy when:
## Typed arrays and optional execution extension
The [typed arrays and optional execution specification](../../../compiler/pbs/specs/typed-arrays-and-optional-execution.md) defines array types/construction/indexing, contextual literals, optional bindings and runtime storage. Its rules extend this specification, including source typing, complete groups, Struct/contract execution and diagnostics.
The [Array owner chapter](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md)
defines the complete type, optional-flow and storage contract.
This chapter preserves syntax and type arguments in the AST; the owner chapter
defines Array application admissibility and execution.
Array syntax uses `array<T>` with compositional nesting. Explicit `new array<T>(n)` supplies its type; `new array<>(n)` and `new array(n)` use the expected type. The [Array contract](../../../compiler/pbs/specs/typed-arrays-and-optional-execution.md) defines contextual closers, spans, invariant validation and lowering; obsolete Array spellings are rejected.
Array spelling and construction are owned by [Core Syntax](3.%20Core%20Syntax%20Specification.md)
and the Array chapter; AST, diagnostics and lowering MUST consume that same syntax.
## Parameterized contracts
Contract declarations and barrel items preserve ordered type-parameter names and individual spans. Applied type references preserve ordered child arguments and spans. Implements and as carry a complete target type reference. Semantic imported bindings retain the original declaration and importing lexical scope rather than inventing nominal origins. Existing visitors must traverse type arguments as well as inner/group/Fn/tuple children.
See [PBS generic contracts](../../../compiler/pbs/specs/generic-contracts.md).
See [PBS generic contracts](16.%20Generic%20Contracts%20Specification.md).
## Concrete generic structs and free functions
Structs and free functions preserve ordered parameter declarations and spans. Explicit applied function references preserve type arguments and their source span. Implements preserves its binder, full applied owner and target. Substitution rewrites every field, signature, annotation and executable body/capture position with a declaration-local environment. Concrete application provenance retains original declaration, canonical logical arguments and requesting use; it is not an executable runtime template.
See [Concrete generic structs and free functions](../../../compiler/pbs/specs/generic-structs-and-free-functions.md).
See [Concrete generic structs and free functions](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md).
## Guest hook marker identity
@@ -299,27 +299,31 @@ This document is ready to move beyond temporary status only when:
## Existing values and input runtime alignment
The [PBS input and value alignment contract](../../../compiler/pbs/specs/input-and-existing-type-runtime-alignment.md) governs int/Int32, long/Int64, exact builtin carriers, the Pad/Button/LowPad and Touch API, named-argument evaluation order, migration diagnostics and executable conformance. It supersedes older input-object and untyped executable-lowering descriptions.
The [PBS input and value alignment contract](18.%20Input%20and%20Existing%20Type%20Runtime%20Alignment%20Specification.md) governs int/Int32, long/Int64, exact builtin carriers, the Pad/Button/LowPad and Touch API, named-argument evaluation order, migration diagnostics and executable conformance. It supersedes older input-object and untyped executable-lowering descriptions.
## Typed arrays and optional execution extension
The [typed arrays and optional execution specification](../../../compiler/pbs/specs/typed-arrays-and-optional-execution.md) defines array types/construction/indexing, contextual literals, optional bindings and runtime storage. Its rules extend this specification, including source typing, complete groups, Struct/contract execution and diagnostics.
The [Array owner chapter](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md)
defines the complete type, optional-flow and storage contract.
This chapter owns diagnostic classification and source attribution; the owner
chapter defines which Array forms are rejected.
Array syntax uses `array<T>` with compositional nesting. Explicit `new array<T>(n)` supplies its type; `new array<>(n)` and `new array(n)` use the expected type. The [Array contract](../../../compiler/pbs/specs/typed-arrays-and-optional-execution.md) defines contextual closers, spans, invariant validation and lowering; obsolete Array spellings are rejected.
Array spelling and construction are owned by [Core Syntax](3.%20Core%20Syntax%20Specification.md)
and the Array chapter; AST, diagnostics and lowering MUST consume that same syntax.
## Parameterized contracts
Parameterized contract diagnostics distinguish exact arity (E_SEM_CONTRACT_ARITY), undeclared/duplicate parameters (E_SEM_CONTRACT_PARAMETER), invalid applications (E_SEM_CONTRACT_ARGUMENT), incompatible or incomplete implementations (E_SEM_CONTRACT_SIGNATURE), duplicate pairs (E_SEM_CONTRACT_DUPLICATE_IMPLEMENTATION), invalid owners/modules (E_SEM_CONTRACT_OWNER / E_SEM_CONTRACT_OWNER_MODULE), invalid coercions (E_SEM_CONTRACT_COERCION), and bounded expansion/resource exhaustion (E_SEM_CONTRACT_EXPANSION). Barrel parameter disagreement uses E_LINK_CONTRACT_PARAMETERS. Existing invalid Array/Fn/optional/Self diagnostics also apply after substitution.
See [PBS generic contracts](../../../compiler/pbs/specs/generic-contracts.md).
See [PBS generic contracts](16.%20Generic%20Contracts%20Specification.md).
## Concrete generic structs and free functions
Generic diagnostics distinguish duplicate/unbound parameters, exact arity, raw or improperly inferred application, unjustified symbolic capabilities, invalid substituted positions, constructor errors, collapsed overloads, invalid bound owners, overlap and bounded expansion. Preserve declaration and requesting-use locations with a short instantiation chain. Editor projections retain symbolic parameter, concrete argument and generic origin identities. Generated instance names and host stacks do not replace source explanations.
See [Concrete generic structs and free functions](../../../compiler/pbs/specs/generic-structs-and-free-functions.md).
See [Concrete generic structs and free functions](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md).
## Guest lifecycle diagnostics and conformance
@@ -241,27 +241,31 @@ At frontend `IRBackend` emission time:
## Existing values and input runtime alignment
The [PBS input and value alignment contract](../../../compiler/pbs/specs/input-and-existing-type-runtime-alignment.md) governs int/Int32, long/Int64, exact builtin carriers, the Pad/Button/LowPad and Touch API, named-argument evaluation order, migration diagnostics and executable conformance. It supersedes older input-object and untyped executable-lowering descriptions.
The [PBS input and value alignment contract](18.%20Input%20and%20Existing%20Type%20Runtime%20Alignment%20Specification.md) governs int/Int32, long/Int64, exact builtin carriers, the Pad/Button/LowPad and Touch API, named-argument evaluation order, migration diagnostics and executable conformance. It supersedes older input-object and untyped executable-lowering descriptions.
## Typed arrays and optional execution extension
The [typed arrays and optional execution specification](../../../compiler/pbs/specs/typed-arrays-and-optional-execution.md) defines array types/construction/indexing, contextual literals, optional bindings and runtime storage. Its rules extend this specification, including source typing, complete groups, Struct/contract execution and diagnostics.
The [Array owner chapter](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md)
defines the complete type, optional-flow and storage contract.
This chapter owns source-to-common-IR projection; the owner chapter defines
Array storage, optional carriers and complete-group requirements.
Array syntax uses `array<T>` with compositional nesting. Explicit `new array<T>(n)` supplies its type; `new array<>(n)` and `new array(n)` use the expected type. The [Array contract](../../../compiler/pbs/specs/typed-arrays-and-optional-execution.md) defines contextual closers, spans, invariant validation and lowering; obsolete Array spellings are rejected.
Array spelling and construction are owned by [Core Syntax](3.%20Core%20Syntax%20Specification.md)
and the Array chapter; AST, diagnostics and lowering MUST consume that same syntax.
## Parameterized contracts
The frontend substitutes each closed application and emits a concrete nominal Trait descriptor shared by equivalent uses. Distinct logical applications remain distinct despite shared physical carriers. Concrete implementation functions take the receiver first. CALL_TRAIT evaluates and roots the receiver before arguments, evaluates arguments left to right, then places the complete receiver/ImplementationId view after the argument groups as required by the runtime ABI. Preserve exact signatures, absence, ImplementationId zero, ownership, GC and quotas; generic calls do not add a Dynamic ABI or adaptation wrapper.
See [PBS generic contracts](../../../compiler/pbs/specs/generic-contracts.md).
See [PBS generic contracts](16.%20Generic%20Contracts%20Specification.md).
## Concrete generic structs and free functions
Instantiate structs, free functions and owner-bound implementations within PBS before publishing executable descriptors. Registry receives concrete fields, signatures, bodies, capture groups and targets. Specialized free-function references use existing empty-environment Closure values; Fn remains structural. Preserve receiver identity, implementation zero, singletons, rooting, GC, ownership, evaluation/fault order and quotas. No generic Dynamic/boxing ABI, opcode, descriptor category or runtime instantiation engine is introduced.
See [Concrete generic structs and free functions](../../../compiler/pbs/specs/generic-structs-and-free-functions.md).
See [Concrete generic structs and free functions](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md).
## Lowering optional runtime hook roles
@@ -1,6 +1,17 @@
# Typed arrays and optional execution
Owner: `compiler/pbs`. This specification defines the source contract for typed arrays and their integration with existing optional, struct and contract semantics. Runtime Registry, PBX, ownership, limits and faults remain governed by the runtime specifications. The completed implementation and conformance gates are recorded in [LSN-0083](../../../../discussion/lessons/DSC-0079-pbs-typed-collections-and-dynamic/LSN-0083-pbs-arrays-optional-and-contract-execution.md) and its evidence.
Status: Normative. Owner: `compiler/pbs`.
Scope: Typed Arrays and Optional Execution.
This specification defines the source contract for typed arrays and their integration with existing optional, struct and contract semantics. Runtime Registry, PBX, ownership, limits and faults remain governed by the runtime specifications. The completed implementation and conformance gates are recorded in [LSN-0083](../../../../discussion/lessons/DSC-0079-pbs-typed-collections-and-dynamic/LSN-0083-pbs-arrays-optional-and-contract-execution.md) and its evidence.
## Authority and scope
This chapter is the canonical owner of the detailed contract described below.
The [domain reading guide](README.md) identifies related chapters and their
separate responsibilities. Cross-cutting chapters refer here for these rules.
Runtime-owned ABI, instruction, resource and execution contracts retain their
authority; this chapter specifies their compiler or PBS consumer requirements.
## Types and construction
@@ -76,35 +87,34 @@ Conformance must compile real PBS through typed IR and production PBX into the p
## Related specifications
- [Core syntax](../../../specs/compiler-languages/pbs/3.%20Core%20Syntax%20Specification.md)
- [Static semantics](../../../specs/compiler-languages/pbs/4.%20Static%20Semantics%20Specification.md)
- [Dynamic semantics](../../../specs/compiler-languages/pbs/9.%20Dynamic%20Semantics%20Specification.md)
- [Existing type runtime alignment](input-and-existing-type-runtime-alignment.md)
- [Core syntax](3.%20Core%20Syntax%20Specification.md)
- [Static semantics](4.%20Static%20Semantics%20Specification.md)
- [Dynamic semantics](9.%20Dynamic%20Semantics%20Specification.md)
- [Existing type runtime alignment](18.%20Input%20and%20Existing%20Type%20Runtime%20Alignment%20Specification.md)
[SDK List and Cursor](sdk-list-and-cursor.md) define logical size, growth and
[SDK List and Cursor](21.%20SDK%20List%20and%20Cursor%20Specification.md) define logical size, growth and
snapshot traversal above private fixed-length arrays. List capacity does not
create logical elements; fixed array length does. Set/Map, equality and hashing
policies remain separate concerns.
See [Runtime Random integration](runtime-random-integration.md) for opaque generator aliases in typed storage and captures.
See [Runtime Random integration](20.%20Runtime%20Random%20Integration%20Specification.md) for opaque generator aliases in typed storage and captures.
[Map/Keyval](sdk-map-and-keyval.md) stores V in generic node fields and therefore
[Map/Keyval](24.%20SDK%20Map%20and%20Keyval%20Specification.md) stores V in generic node fields and therefore
admits optional values. Its outer lookup/previous-value optional describes entry
existence independently of stored V; some(none) is distinct from absent none.
This does not change Array's direct optional-element restriction.
## Parameterized contract integration
[Generic contracts](generic-contracts.md) extend nominal contract declarations with explicit type arguments. Valid Array/Fn/optional/tuple compositions preserve their existing logical and physical rules after substitution. No generic-only Dynamic transport, view wrapper, altered resource limit or new runtime opcode is introduced.
[Generic contracts](16.%20Generic%20Contracts%20Specification.md) extend nominal contract declarations with explicit type arguments. Valid Array/Fn/optional/tuple compositions preserve their existing logical and physical rules after substitution. No generic-only Dynamic transport, view wrapper, altered resource limit or new runtime opcode is introduced.
[Generic structs and free functions](generic-structs-and-free-functions.md) reuse
[Generic structs and free functions](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md) reuse
these contextual construction positions and storage rules. A generic T field can
hold an optional value, but substituting an optional value type into array<T>
remains invalid. Array's private packing does not become a generic argument ABI.
SDK collections add logical checks before physical Array operations and terminate
logical refusals with TRAP_EXPLICIT. Their multi-instruction methods use the
[List mutation-phase contract](sdk-list-and-cursor.md#mutation-preparation-visible-writes-and-faults)
and [Linked contract](sdk-linked-and-cursor.md#mutation-phases-and-lifetime);
[List mutation-phase contract](21.%20SDK%20List%20and%20Cursor%20Specification.md#mutation-preparation-visible-writes-and-faults)
and [Linked contract](22.%20SDK%20Linked%20and%20Cursor%20Specification.md#mutation-phases-and-lifetime);
per-instruction storage guarantees do not imply whole-method rollback.
@@ -1,6 +1,17 @@
# First-class functions and explicit value captures
Owner: `compiler/pbs`. This specification defines PBS function values and closures. Runtime Registry/PBX layout, allocation, GC, resource limits and faults remain governed by the runtime contracts. It supersedes the retired nominal callback and `bind` model.
Status: Normative. Owner: `compiler/pbs`.
Scope: First-Class Functions and Captures.
This specification defines PBS function values and closures. Runtime Registry/PBX layout, allocation, GC, resource limits and faults remain governed by the runtime contracts. It supersedes the retired nominal callback and `bind` model.
## Authority and scope
This chapter is the canonical owner of the detailed contract described below.
The [domain reading guide](README.md) identifies related chapters and their
separate responsibilities. Cross-cutting chapters refer here for these rules.
Runtime-owned ABI, instruction, resource and execution contracts retain their
authority; this chapter specifies their compiler or PBS consumer requirements.
## Types and calls
@@ -75,14 +86,13 @@ Function creation and calls remain subject to existing resource checks and runti
Conformance must compile actual PBS through production PBX and execute it in the production VM. Required cases include signature errors, explicit capture enforcement, snapshots, escaped closures, shared and isolated objects, collection transport, nested closures and function captures, receiver/contract integration, and reachable/unreachable closure behavior across the existing frame lifecycle and GC. Installed knowledge must package this specification and a compilable example.
See [Runtime Random integration](runtime-random-integration.md) for opaque generator aliases in typed storage and captures.
See [Runtime Random integration](20.%20Runtime%20Random%20Integration%20Specification.md) for opaque generator aliases in typed storage and captures.
## Parameterized contract integration
[Generic contracts](generic-contracts.md) extend nominal contract declarations with explicit type arguments. Valid Array/Fn/optional/tuple compositions preserve their existing logical and physical rules after substitution. No generic-only Dynamic transport, view wrapper, altered resource limit or new runtime opcode is introduced.
[Generic contracts](16.%20Generic%20Contracts%20Specification.md) extend nominal contract declarations with explicit type arguments. Valid Array/Fn/optional/tuple compositions preserve their existing logical and physical rules after substitution. No generic-only Dynamic transport, view wrapper, altered resource limit or new runtime opcode is introduced.
[Generic structs and free functions](generic-structs-and-free-functions.md) extend
[Generic structs and free functions](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md) extend
that concrete model to state and bodies. A closed free-function application such
as `identity<int>` supplies an ordinary concrete Fn through an empty-environment
Closure. Lambdas inside specialized bodies preserve explicit captures and complete
@@ -1,6 +1,17 @@
# PBS Generic Contracts
Owner: `compiler/pbs`. This specification extends nominal contracts with explicit type parameters. Registry, PBX, instruction, ownership and resource contracts remain governed by the runtime provider. [Set, SDK Identity and hashing](sdk-set-and-identity.md) are consumers with their own public policy; the examples below illustrate generic language syntax, not the SDK Identity declaration.
Status: Normative. Owner: `compiler/pbs`.
Scope: Generic Contracts.
This specification extends nominal contracts with explicit type parameters. Registry, PBX, instruction, ownership and resource contracts remain governed by the runtime provider. [Set, SDK Identity and hashing](23.%20SDK%20Set%20and%20Identity%20Specification.md) are consumers with their own public policy; the examples below illustrate generic language syntax, not the SDK Identity declaration.
## Authority and scope
This chapter is the canonical owner of the detailed contract described below.
The [domain reading guide](README.md) identifies related chapters and their
separate responsibilities. Cross-cutting chapters refer here for these rules.
Runtime-owned ABI, instruction, resource and execution contracts retain their
authority; this chapter specifies their compiler or PBS consumer requirements.
## Declaration and application
@@ -17,7 +28,7 @@ declare contract Converter<A, B> {
A parameterized declaration has one or more distinct ordered type parameters. Their scope is the contract's signatures, including nested type references. A type parameter is not the receiver. `Self` retains its existing meaning and validity restrictions.
Applications supply explicit ordered type arguments with exact arity: `Identity<int>` and `Converter<Enemy, str>`. The declaration's raw name, omitted arguments, `<>`, default arguments and blanket generic implementations are not value types or inference mechanisms. Nonparameterized contracts remain valid. [Generic structs and free functions](generic-structs-and-free-functions.md) add restricted owner-bound implementation families; they do not introduce blanket implementations for arbitrary owners.
Applications supply explicit ordered type arguments with exact arity: `Identity<int>` and `Converter<Enemy, str>`. The declaration's raw name, omitted arguments, `<>`, default arguments and blanket generic implementations are not value types or inference mechanisms. Nonparameterized contracts remain valid. [Generic structs and free functions](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md) add restricted owner-bound implementation families; they do not introduce blanket implementations for arbitrary owners.
The same compositional type grammar applies in annotations, nested applications, implementation targets and expression-form `as`. Existing contextual angle closers and expression comparisons retain their meanings. A barrel exports the declaration, for example `pub contract Identity<T>;`, preserving its origin and ordered parameters rather than exporting a particular application.
@@ -71,4 +82,4 @@ Navigation reaches generic declarations, parameters and argument declarations. H
Compile real PBS through typed IR and production PBX into the production loader, verifier and VM. Cover multiple parameters/applications, several applications on one owner, imports/aliases/reexports, nominal origin, phantom arguments, composed and multi-slot payloads, finite recursion, expanding recursion rejection, service/struct views, typed absence, implementation zero, GC and resource refusal.
A specialized contract and a manually written concrete equivalent must exhibit the same behavior without generic-only adaptation/boxing. Identical image bytes and a performance improvement are not required. Installed knowledge packages this specification and a runnable source example. Generic structs/functions are defined by the separate [owner specification](generic-structs-and-free-functions.md), sharing canonical identities, provenance and bounded expansion with contracts. Bounds, variance, inheritance/default methods, generic reflection, runtime instantiation and collection algorithms remain outside these extensions.
A specialized contract and a manually written concrete equivalent must exhibit the same behavior without generic-only adaptation/boxing. Identical image bytes and a performance improvement are not required. Installed knowledge packages this specification and a runnable source example. Generic structs/functions are defined by the separate [owner specification](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md), sharing canonical identities, provenance and bounded expansion with contracts. Bounds, variance, inheritance/default methods, generic reflection, runtime instantiation and collection algorithms remain outside these extensions.
@@ -1,10 +1,21 @@
# Concrete Generic Structs and Free Functions
Owner: `compiler/pbs`. This specification adds parameterized state and executable
Status: Normative. Owner: `compiler/pbs`.
Scope: Generic Structs and Free Functions.
This specification adds parameterized state and executable
bodies to the nominal, concrete application model of generic contracts. It applies
uniformly to SDK modules and program sources. Registry, PBX, VM admission, resource
limits and instruction semantics remain governed by the existing provider contracts.
## Authority and scope
This chapter is the canonical owner of the detailed contract described below.
The [domain reading guide](README.md) identifies related chapters and their
separate responsibilities. Cross-cutting chapters refer here for these rules.
Runtime-owned ABI, instruction, resource and execution contracts retain their
authority; this chapter specifies their compiler or PBS consumer requirements.
## Declarations and identity
Structs and module-level named free functions may declare one or more distinct,
@@ -58,7 +69,7 @@ and generic structs, including fields of opaque builtin type Random. Assignment
in only one conditional branch or in a loop that may execute zero times is
insufficient. Runtime reference defaults are provider behavior and do not exempt
PBS constructors from this rule. Controlled null-provider fixtures are described
in [Runtime Random integration](runtime-random-integration.md).
in [Runtime Random integration](20.%20Runtime%20Random%20Integration%20Specification.md).
## Composition and symbolic capabilities
@@ -265,9 +276,9 @@ iteration protocols and List logical bounds/slot transfer are separate decisions
## Related specifications
- [Generic contracts](generic-contracts.md).
- [Typed arrays and optional execution](typed-arrays-and-optional-execution.md).
- [First-class functions and captures](first-class-functions-and-captures.md).
- [Concrete Registry and PBX handoff](../../general/specs/typed-registry-and-pbx-v0.md).
- [SDK Map and Keyval](sdk-map-and-keyval.md), a two-parameter source consumer
- [Generic contracts](16.%20Generic%20Contracts%20Specification.md).
- [Typed arrays and optional execution](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md).
- [First-class functions and captures](15.%20First-Class%20Functions%20and%20Captures%20Specification.md).
- [Concrete Registry and PBX handoff](../../compiler/25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md).
- [SDK Map and Keyval](24.%20SDK%20Map%20and%20Keyval%20Specification.md), a two-parameter source consumer
preserving separate key/value policies and complete optional/grouped fields.
@@ -1,8 +1,19 @@
# PBS input and existing value runtime alignment
Status: normative. Owner: `compiler/pbs`. Common ABI authority:
[typed Registry/PBX](../../general/specs/typed-registry-and-pbx-v0.md) and
[runtime catalogs](../../general/specs/runtime-catalog-support.md).
Status: Normative. Owner: `compiler/pbs`.
Scope: Input and Existing Type Runtime Alignment.
Common ABI authority:
[typed Registry/PBX](../../compiler/25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md) and
[runtime catalogs](../../compiler/24.%20Runtime%20Catalog%20Support%20Specification.md).
## Authority and scope
This chapter is the canonical owner of the detailed contract described below.
The [domain reading guide](README.md) identifies related chapters and their
separate responsibilities. Cross-cutting chapters refer here for these rules.
Runtime-owned ABI, instruction, resource and execution contracts retain their
authority; this chapter specifies their compiler or PBS consumer requirements.
## Source types and exact carriers
@@ -1,8 +1,19 @@
# Service constants and runtime math
Owner: compiler/pbs. Common catalog authority: compiler/general. Numeric behavior,
Status: Normative. Owner: `compiler/pbs`.
Scope: Service Constants and Runtime Math.
Common catalog authority: compiler/general. Numeric behavior,
exact identities, faults and virtual costs remain owned by the runtime.
## Authority and scope
This chapter is the canonical owner of the detailed contract described below.
The [domain reading guide](README.md) identifies related chapters and their
separate responsibilities. Cross-cutting chapters refer here for these rules.
Runtime-owned ABI, instruction, resource and execution contracts retain their
authority; this chapter specifies their compiler or PBS consumer requirements.
## Services are the public namespaces
A service groups methods and immutable constants. The service barrel entry exports
@@ -113,6 +124,6 @@ remain separately pending; local results and cross-compilation do not qualify th
## References
- [Common runtime catalog support](../../general/specs/runtime-catalog-support.md)
- [Common runtime catalog support](../../compiler/24.%20Runtime%20Catalog%20Support%20Specification.md)
- [Runtime numeric contract](../../../../../runtime/docs/specs/runtime/02d-gameplay-math-and-numeric-semantics.md)
- [Production conformance harness](../../../../tools/pbx-conformance/README.md)
@@ -136,7 +136,7 @@ Every accepted change MUST update, when relevant:
- diagnostics documentation,
- conformance tests,
- compatibility matrix/changelog.
- For executable FE/BE conformance-relevant code changes, the backend conformance matrix (`docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`) MUST be updated and pass hard-gate policy checks.
- For executable FE/BE conformance-relevant code changes, the backend conformance matrix (`docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md`) MUST be updated and pass hard-gate policy checks.
## 12. Conflict Resolution
@@ -1,6 +1,17 @@
# PBS Runtime Random Integration
Owner: `compiler/pbs`. This specification defines the PBS projection of runtime Random v1. The runtime owns the algorithm, heap identity, validation, atomicity, resource accounting and virtual cycles. The common catalog is the binding authority; the frontend does not implement a generator.
Status: Normative. Owner: `compiler/pbs`.
Scope: Runtime Random Integration.
This specification defines the PBS projection of runtime Random v1. The runtime owns the algorithm, heap identity, validation, atomicity, resource accounting and virtual cycles. The common catalog is the binding authority; the frontend does not implement a generator.
## Authority and scope
This chapter is the canonical owner of the detailed contract described below.
The [domain reading guide](README.md) identifies related chapters and their
separate responsibilities. Cross-cutting chapters refer here for these rules.
Runtime-owned ABI, instruction, resource and execution contracts retain their
authority; this chapter specifies their compiler or PBS consumer requirements.
## Source surface
@@ -64,8 +75,8 @@ Null receivers and present typed-null Array elements MUST be covered by separate
## References
- [Typed arrays and optional execution](typed-arrays-and-optional-execution.md).
- [First-class functions and captures](first-class-functions-and-captures.md).
- [Runtime math and exact numeric carriers](service-constants-and-runtime-math.md).
- [Typed arrays and optional execution](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md).
- [First-class functions and captures](15.%20First-Class%20Functions%20and%20Captures%20Specification.md).
- [Runtime math and exact numeric carriers](19.%20Service%20Constants%20and%20Runtime%20Math%20Specification.md).
- [Runtime Random v1](../../../../../runtime/docs/specs/runtime/02e-vm-owned-random-core.md).
- [Provider handoff](../../../../../runtime/docs/vm-arch/random-producer-handoff.md).
@@ -1,11 +1,22 @@
# SDK List and snapshot Cursor
Owner: `compiler/pbs`. List and Cursor algorithms belong to the executable PBS
Status: Normative. Owner: `compiler/pbs`.
Scope: SDK List and Cursor.
List and Cursor algorithms belong to the executable PBS
SDK. Typed storage, complete stored-group transfers and terminal failure are
language-neutral compiler/runtime mechanisms. Logical checks are SDK algorithms. This contract builds on
[arrays and optional](typed-arrays-and-optional-execution.md),
[generic structs](generic-structs-and-free-functions.md) and
[generic contracts](generic-contracts.md).
[arrays and optional](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md),
[generic structs](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md) and
[generic contracts](16.%20Generic%20Contracts%20Specification.md).
## Authority and scope
This chapter is the canonical owner of the detailed contract described below.
The [domain reading guide](README.md) identifies related chapters and their
separate responsibilities. Cross-cutting chapters refer here for these rules.
Runtime-owned ABI, instruction, resource and execution contracts retain their
authority; this chapter specifies their compiler or PBS consumer requirements.
## Type, identity and construction
@@ -176,10 +187,10 @@ faults. List itself rejects directly optional elements.
## Reuse, costs and conformance
The shared implementation is independent of List representation.
[Stack/Queue](sdk-stack-and-queue.md) capture in their LIFO/FIFO removal orders.
[Linked](sdk-linked-and-cursor.md) uses Cursor<T> for forward and reverse captures.
[Set](sdk-set-and-identity.md) produces Cursor<T>; Map<K,V> uses
Cursor<keyval<K,V>> as specified by [Map/Keyval](sdk-map-and-keyval.md).
[Stack/Queue](25.%20SDK%20Stack%20and%20Queue%20Specification.md) capture in their LIFO/FIFO removal orders.
[Linked](22.%20SDK%20Linked%20and%20Cursor%20Specification.md) uses Cursor<T> for forward and reverse captures.
[Set](23.%20SDK%20Set%20and%20Identity%20Specification.md) produces Cursor<T>; Map<K,V> uses
Cursor<keyval<K,V>> as specified by [Map/Keyval](24.%20SDK%20Map%20and%20Keyval%20Specification.md).
Set/Map gain no ordering guarantee between captures.
A captured keyval association is read-only
and does not follow later association replacement; referenced objects stay shared.
@@ -1,10 +1,21 @@
# SDK Linked and bidirectional snapshot capture
Owner: `compiler/pbs`. Linked algorithms belong to executable PBS SDK source.
Status: Normative. Owner: `compiler/pbs`.
Scope: SDK Linked and Cursor.
Linked algorithms belong to executable PBS SDK source.
Typed storage, faults, ownership, GC and quotas remain generic
compiler/provider mechanisms. This contract builds on [generic structs](generic-structs-and-free-functions.md),
[arrays and optional](typed-arrays-and-optional-execution.md) and the
[shared Cursor protocol](sdk-list-and-cursor.md#cursor-protocol).
compiler/provider mechanisms. This contract builds on [generic structs](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md),
[arrays and optional](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md) and the
[shared Cursor protocol](21.%20SDK%20List%20and%20Cursor%20Specification.md#cursor-protocol).
## Authority and scope
This chapter is the canonical owner of the detailed contract described below.
The [domain reading guide](README.md) identifies related chapters and their
separate responsibilities. Cross-cutting chapters refer here for these rules.
Runtime-owned ABI, instruction, resource and execution contracts retain their
authority; this chapter specifies their compiler or PBS consumer requirements.
## Type, identity and construction
@@ -131,5 +142,5 @@ projections. Ship the specification and executable example with installed SDK
knowledge, compile the actual packaged example outside the checkout and execute
its emitted PBX with the production provider.
See [generic Registry/PBX storage](../../general/specs/typed-registry-and-pbx-v0.md)
See [generic Registry/PBX storage](../../compiler/25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md)
for the language-neutral instruction contract.
@@ -1,10 +1,21 @@
# SDK Set, Identity and hashing
Owner: `compiler/pbs`. Set algorithms belong to executable PBS SDK source. Typed
Status: Normative. Owner: `compiler/pbs`.
Scope: SDK Set and Identity.
Set algorithms belong to executable PBS SDK source. Typed
reference queries, storage, admission, faults and resource limits are generic
compiler/provider mechanisms. This contract builds on [generic structs](generic-structs-and-free-functions.md),
[generic contracts](generic-contracts.md), [Array/optional](typed-arrays-and-optional-execution.md)
and the [shared snapshot Cursor](sdk-list-and-cursor.md#cursor-protocol).
compiler/provider mechanisms. This contract builds on [generic structs](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md),
[generic contracts](16.%20Generic%20Contracts%20Specification.md), [Array/optional](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md)
and the [shared snapshot Cursor](21.%20SDK%20List%20and%20Cursor%20Specification.md#cursor-protocol).
## Authority and scope
This chapter is the canonical owner of the detailed contract described below.
The [domain reading guide](README.md) identifies related chapters and their
separate responsibilities. Cross-cutting chapters refer here for these rules.
Runtime-owned ABI, instruction, resource and execution contracts retain their
authority; this chapter specifies their compiler or PBS consumer requirements.
## Types, construction and operations
@@ -235,8 +246,8 @@ PBX. Normal compilation uses versioned Studio catalogs/resources without a sibli
checkout. Runtime ownership, limits and semantics remain the provider contract;
Set adds no VM collection instruction/syscall or provider source change.
Identity/hash are reused by [Map/Keyval](sdk-map-and-keyval.md). Its API, representation
Identity/hash are reused by [Map/Keyval](24.%20SDK%20Map%20and%20Keyval%20Specification.md). Its API, representation
and implementation are separate consumers; sharing policy does not impose a shared
physical table or universal entry type. See the
[common typed Registry contract](../../general/specs/typed-registry-and-pbx-v0.md)
and [catalog consumer rules](../../general/specs/runtime-catalog-support.md).
[common typed Registry contract](../../compiler/25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md)
and [catalog consumer rules](../../compiler/24.%20Runtime%20Catalog%20Support%20Specification.md).
@@ -1,12 +1,23 @@
# SDK Map and read-only Keyval associations
Owner: `compiler/pbs`. Map algorithms execute as PBS SDK source. This contract
builds on [generic structs](generic-structs-and-free-functions.md),
[Array/optional](typed-arrays-and-optional-execution.md),
[Set/Identity/hash](sdk-set-and-identity.md) and the
[shared snapshot Cursor](sdk-list-and-cursor.md#cursor-protocol).
Status: Normative. Owner: `compiler/pbs`.
Scope: SDK Map and Keyval.
Map algorithms execute as PBS SDK source. This contract
builds on [generic structs](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md),
[Array/optional](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md),
[Set/Identity/hash](23.%20SDK%20Set%20and%20Identity%20Specification.md) and the
[shared snapshot Cursor](21.%20SDK%20List%20and%20Cursor%20Specification.md#cursor-protocol).
Registry/PBX, storage, ownership, faults and resource limits remain provider contracts.
## Authority and scope
This chapter is the canonical owner of the detailed contract described below.
The [domain reading guide](README.md) identifies related chapters and their
separate responsibilities. Cross-cutting chapters refer here for these rules.
Runtime-owned ABI, instruction, resource and execution contracts retain their
authority; this chapter specifies their compiler or PBS consumer requirements.
## Types, construction and public API
`@sdk:collections` exports invariant ordinary generic structs `map<K,V>` and
@@ -1,10 +1,21 @@
# SDK Stack and Queue
Owner: `compiler/pbs`. Algorithms execute as PBS SDK source over existing typed
Status: Normative. Owner: `compiler/pbs`.
Scope: SDK Stack and Queue.
Algorithms execute as PBS SDK source over existing typed
storage, complete-group copies, terminal checks and shared snapshot Cursor.
This contract builds on [Array/optional](typed-arrays-and-optional-execution.md),
[generic structs](generic-structs-and-free-functions.md) and
[List/shared Cursor](sdk-list-and-cursor.md#cursor-protocol).
This contract builds on [Array/optional](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md),
[generic structs](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md) and
[List/shared Cursor](21.%20SDK%20List%20and%20Cursor%20Specification.md#cursor-protocol).
## Authority and scope
This chapter is the canonical owner of the detailed contract described below.
The [domain reading guide](README.md) identifies related chapters and their
separate responsibilities. Cross-cutting chapters refer here for these rules.
Runtime-owned ABI, instruction, resource and execution contracts retain their
authority; this chapter specifies their compiler or PBS consumer requirements.
## Types, identity and construction
@@ -20,10 +20,10 @@ This document defines syntax only. Runtime behavior, optimizer policy, and bytec
Normative precedence:
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
1. Runtime authority ([provider specifications](../../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../../vm-arch/README.md))
2. Bytecode authority ([provider Core ISA](../../../../../runtime/docs/vm-arch/ISA_CORE.md))
3. This document
4. Legacy references (`docs/specs/random/pbs_old/*`)
4. Retired PBS drafts are historical context only and carry no normative authority.
If a rule here conflicts with higher authority, it is invalid.
@@ -76,8 +76,8 @@ Keywords are not valid identifiers.
Active keywords in `.pbs`:
- `import`, `from`, `as`
- `service`, `host`, `fn`, `apply`, `bind`, `new`, `implements`, `using`, `ctor`
- `declare`, `struct`, `contract`, `error`, `enum`, `callback`, `global`, `Self`, `this`
- `service`, `host`, `fn`, `apply`, `new`, `implements`, `using`, `ctor`
- `declare`, `struct`, `contract`, `error`, `enum`, `global`, `Self`, `this`
- `pub`, `mut`
- `let`, `const`
- `if`, `else`, `switch`, `default`, `for`, `from`, `until`, `step`, `while`, `break`, `continue`, `return`
@@ -96,6 +96,10 @@ Reserved (not active syntax in v1 core):
- `spawn`, `yield`, `sleep`
- `match`
Retired source forms `declare callback` and `bind(...)` MUST be rejected;
[function values and captures](15.%20First-Class%20Functions%20and%20Captures%20Specification.md)
defines their replacement. Retired tokens are not active declaration/call syntax.
Note:
- `host` is used only by reserved SDK/toolchain `declare host` surfaces in v1 core; ordinary user-authored modules MUST reject those declarations.
@@ -366,7 +370,7 @@ Rules:
### 7.2 First-class function values
Function types use `Fn(T1, T2) -> R`. Lambdas use `fn [captures](name: Type) -> Return { ... }`; `[]` and all signature annotations are mandatory. See [First-class functions and explicit value captures](../../../compiler/pbs/specs/first-class-functions-and-captures.md).
Function types use `Fn(T1, T2) -> R`. Lambdas use `fn [captures](name: Type) -> Return { ... }`; `[]` and all signature annotations are mandatory. See [First-class functions and explicit value captures](15.%20First-Class%20Functions%20and%20Captures%20Specification.md).
### 7.3 Services
@@ -380,7 +384,7 @@ ServiceMember ::= 'fn' Identifier ParamList ReturnAnn? Block | ConstDecl
Rules:
- `declare service Name { ... }` declares a nominal service type together with its canonical module-owned singleton value `Name`.
- A service body contains method declarations and `declare const` members. SDK service intrinsic signatures may terminate with `;`; see [Service constants and runtime math](../../../compiler/pbs/specs/service-constants-and-runtime-math.md).
- A service body contains method declarations and `declare const` members. SDK service intrinsic signatures may terminate with `;`; see [Service constants and runtime math](19.%20Service%20Constants%20and%20Runtime%20Math%20Specification.md).
- Service methods have an implicit receiver binding `this` of type `Self` and do not declare `this: Self` explicitly.
- Services do not declare fields.
- Services do not declare `ctor`.
@@ -446,7 +450,7 @@ Rules:
- A `declare const` initializer is required unless another specification explicitly permits a reserved declaration-only shell such as builtin constant metadata.
- A `declare const` initializer, when present, MUST be a constant expression as defined by static semantics.
- `declare const` values are compile-time constants, not runtime-initialized module storage.
- A reserved top-level builtin constant shell MAY use attributes such as `BuiltinConst(...)` and omit the initializer when another specification explicitly defines VM-owned materialization.
- A reserved top-level or SDK service builtin constant shell MAY use attributes such as `BuiltinConst(...)` and omit the initializer when another specification explicitly defines VM-owned materialization.
## 8. Type syntax
@@ -611,7 +615,7 @@ Rules:
- `new Type(args...)` is the canonical struct construction surface.
- `new Type.ctorName(args...)` is the canonical named-constructor surface.
- Struct construction arguments are positional and follow the declared struct field order.
- `as` is reserved in expressions for explicit contract-view conversion only; it does not denote a general cast surface in v1 core.
- `as` expresses explicit contract-view conversion or the supported numeric conversions defined by [input and value alignment](18.%20Input%20and%20Existing%20Type%20Runtime%20Alignment%20Specification.md). It is not an unrestricted cast.
- A contract-view `as` target is a visible contract type, including explicit arguments such as `Identity<int>`, never a qualified module path. Existing numeric conversions retain their value-alignment rules.
- `this` is an implicit receiver name available only inside struct method, service method, and `ctor` bodies.
- `Self` is valid only inside struct method declarations, service method declarations, and `ctor` declarations.
@@ -1199,25 +1203,27 @@ fn test(e: Enum) -> str {
## Typed arrays and optional execution extension
The [typed arrays and optional execution specification](../../../compiler/pbs/specs/typed-arrays-and-optional-execution.md) defines array types/construction/indexing, contextual literals, optional bindings and runtime storage. Its rules extend this specification, including source typing, complete groups, Struct/contract execution and diagnostics.
The [Array owner chapter](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md)
defines the complete type, optional-flow and storage contract.
This chapter owns the source syntax and spans consumed by that feature.
Retired `declare callback`, callback exports and `bind(...)` are rejected. They do not provide alternative spellings for Fn or lambdas.
Array syntax uses `array<T>` with compositional nesting. Explicit `new array<T>(n)` supplies its type; `new array<>(n)` and `new array(n)` use the expected type. The [Array contract](../../../compiler/pbs/specs/typed-arrays-and-optional-execution.md) defines contextual closers, spans, invariant validation and lowering; obsolete Array spellings are rejected.
Array syntax uses `array<T>` with compositional nesting. Explicit `new array<T>(n)` supplies its type; `new array<>(n)` and `new array(n)` use the expected type. The [Array contract](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md) defines contextual closers, spans, invariant validation and lowering; obsolete Array spellings are rejected.
## Parameterized contracts
Parameterized contracts use explicit angular arguments in annotations, nested types, implements and as. Barrels export the ordered parameter list. Raw generic uses, empty argument lists and default arguments are invalid; existing contextual closers and Array construction sugars remain unchanged.
See [PBS generic contracts](../../../compiler/pbs/specs/generic-contracts.md).
See [PBS generic contracts](16.%20Generic%20Contracts%20Specification.md).
## Concrete generic structs and free functions
Struct and module-level free-function declarations and their barrel items accept ordered type parameters. Explicit function applications are reference expressions; calls use existing parentheses/apply. Generic construction supports explicit arguments and contextual diamond/omission. Owner-bound `implements` accepts its own parameter binder and a full applied owner. Independent method parameters, function diamond/inference and polymorphic Fn remain invalid. The owner specification defines exact arity, comparison disambiguation and recovery.
See [Concrete generic structs and free functions](../../../compiler/pbs/specs/generic-structs-and-free-functions.md).
See [Concrete generic structs and free functions](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md).
## Controlled guest lifecycle marker syntax
@@ -20,8 +20,8 @@ It is intended to:
Normative precedence:
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
1. Runtime authority ([provider specifications](../../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../../vm-arch/README.md))
2. Bytecode authority ([provider Core ISA](../../../../../runtime/docs/vm-arch/ISA_CORE.md))
3. `3. Core Syntax Specification.md`
4. This document
@@ -87,7 +87,7 @@ Rules:
- `Init` is valid only on a top-level userland `fn` declaration with lifecycle-admissible signature.
- `Frame` is valid only on a top-level userland `fn` declaration with lifecycle-admissible signature.
- `InitAllowed` is valid only on a host method signature declared directly inside a reserved stdlib/interface-module `declare host` body.
- `Host` is invalid on ordinary user-authored modules, top-level `fn`, struct methods, service methods, callbacks, contracts, and constants.
- `Host` is invalid on ordinary user-authored modules, top-level `fn`, struct methods, service methods, lambdas, contracts, and constants.
- `Host` metadata is consumed by the compiler during host-binding lowering.
- `AssetLowering` MUST declare exactly the named argument `param`.
- `AssetLowering.param` MUST be a zero-based integer literal that names a valid host parameter position.
@@ -95,7 +95,7 @@ Rules:
- `AssetLowering` metadata is consumed by backend-owned host-call lowering to rewrite the targeted symbolic `Addressable` operand into runtime-facing `asset_id`.
- The `Host` attribute syntax itself is not exported as runtime metadata; instead, its canonical identity participates in PBX host-binding emission as defined by the Host ABI Binding specification.
- `BuiltinType` is valid only on a reserved top-level `declare builtin type` declaration.
- `BuiltinConst` is valid only on a reserved top-level `declare const` declaration that omits an initializer.
- `BuiltinConst` is valid on reserved top-level and SDK service `declare const` shells that omit an initializer, as defined by [service constants and runtime math](19.%20Service%20Constants%20and%20Runtime%20Math%20Specification.md).
- `IntrinsicCall` is valid on a method signature inside a reserved `declare builtin type` body or an SDK service body. SDK service signatures have no implementation body and bind their exact declared argument/result carriers to the common intrinsic catalog.
- Builtin metadata is consumed by the compiler during VM-owned builtin and intrinsic lowering rather than by host-binding lowering.
- `Init` and `Frame` are consumed by lifecycle analysis and lowering rather than by ordinary runtime reflection.
@@ -195,7 +195,7 @@ The following constructs are callable in v1 core:
- top-level `fn`,
- struct methods on concrete receivers,
- contract values,
- callback values,
- structural `Fn` values,
- service methods,
- host methods on declared host owners,
- builtin intrinsic methods on declared builtin types.
@@ -252,7 +252,7 @@ Rules:
- Project init must be colocated with `[Frame]`.
- PBS static semantics and lowering admit those markers and translate them into a typed `IRLifecycleDeclaration`.
- PBS MUST NOT materialize module init, project-init wrapper, published frame wrapper, physical entrypoint, or boot guard; those artifacts belong to common lifecycle assembly.
- `InitAllowed` is valid only on SDK host methods and is invalid on userland `fn`, `global`, `service`, `const`, `struct`, `contract`, and callback surfaces.
- `InitAllowed` is valid only on SDK host methods and is invalid on userland `fn`, `global`, `service`, `const`, `struct`, `contract`, and lambda surfaces.
- A host method signature in a reserved stdlib/interface module MUST carry exactly one `Host` attribute.
- A host method signature in a reserved stdlib/interface module MUST carry exactly one `Capability` attribute.
- A `Host` attribute MUST declare exactly the named arguments `module`, `name`, and `version`.
@@ -349,7 +349,7 @@ Rules:
### 3.6 Structs, services, methods, and contracts
Service constants follow [Service constants and runtime math](../../../compiler/pbs/specs/service-constants-and-runtime-math.md).
Service constants follow [Service constants and runtime math](19.%20Service%20Constants%20and%20Runtime%20Math%20Specification.md).
They are immutable members exported with their service. Qualified constant reads
materialize the constant without constructing a singleton or invoking a method.
@@ -376,7 +376,7 @@ Rules:
- A named `ctor` declared in a struct body is not a method, but it does introduce an implicit under-construction `this`.
- A `ctor` has no declared return annotation and is not a `fn`.
- A `ctor` completes by falling off the end of its body after initializing the enclosing struct instance.
- Every field of the enclosing struct must be definitely assigned on every completing `ctor` path.
- Every field of the enclosing struct must be definitely assigned on every completing `ctor` path, including ordinary/generic owners and opaque Random fields. Provider reference defaults do not exempt PBS constructors; [generic construction](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md#construction-and-expected-types) owns this complete rule.
- Named constructors participate in overload resolution by name plus parameter signature.
- `return;` and `return expr;` are both invalid inside `ctor` bodies.
- Methods declared in a struct body belong to the direct method namespace of that concrete struct type.
@@ -395,7 +395,7 @@ Rules:
- Methods declared directly inside a struct or service follow the visibility of their enclosing owner declaration; they do not have independent visibility.
- A struct value or service singleton value may be coerced to a contract value when exactly one visible `implements Contract for Owner ...` applies.
- Contract coercion may happen by explicit `expr as ContractType` or by contextual typing in assignments, parameter passing, and returns.
- `as` in expression position is reserved for explicit contract coercion only; no other cast semantics exist in v1 core.
- `as` supports explicit contract coercion and the numeric conversions owned by [input and value alignment](18.%20Input%20and%20Existing%20Type%20Runtime%20Alignment%20Specification.md); other casts remain invalid.
- The contract in `expr as ContractType` is resolved through ordinary scope/import rules and may carry explicit type arguments. Aliases preserve declaration identity.
- A contract value carries the underlying struct reference or service singleton value together with the selected contract implementation for runtime dispatch.
- Calling `contractValue.method(...)` uses dynamic dispatch through the contract value.
@@ -442,7 +442,7 @@ fn demo() -> int {
### 3.7 Structural function values
[First-class functions and explicit value captures](../../../compiler/pbs/specs/first-class-functions-and-captures.md) defines structural Fn compatibility, explicit snapshot captures and lambda typing. Assignment of a named function requires exactly one matching overload. Bare method extraction remains invalid; use an explicit receiver-capturing lambda.
[First-class functions and explicit value captures](15.%20First-Class%20Functions%20and%20Captures%20Specification.md) defines structural Fn compatibility, explicit snapshot captures and lambda typing. Assignment of a named function requires exactly one matching overload. Bare method extraction remains invalid; use an explicit receiver-capturing lambda.
### 3.8 Canonical application
@@ -457,7 +457,7 @@ Rules:
- `apply` is an infix operator that is right-associative.
- `f1 apply f2 apply x` is defined as `f1 apply (f2 apply x)`.
- `f1 apply f2 apply f3 apply params` is defined as `f1 apply (f2 apply (f3 apply params))`.
- The left operand of `apply` must resolve to one of: a callable candidate set, a bound struct method target, a bound service method target, a contract-method target, or a callback value.
- The left operand of `apply` must resolve to one of: a callable candidate set, a bound struct method target, a bound service method target, a contract-method target, or a `Fn` value.
- The right operand of `apply` is an argument expression.
- If the callable input arity is `0`, the argument expression must be `()`.
- If the callable input arity is `1`, the argument expression is checked against the carrier type of the single input slot.
@@ -497,7 +497,7 @@ Rules:
- If the selected callable output arity is `1`, the result of `apply` is the carrier type of the single output slot.
- If the selected callable output arity is `2..6`, the result of `apply` has the named output tuple shape of the selected callable.
- Multi-slot output tuple results expose their labels for member projection.
- If the selected callable is a callback value, the visible multi-slot output labels come from the callback type rather than from the original source `fn`.
- If the selected callable is a `Fn` value, the visible multi-slot output labels come from the `Fn` type rather than from the original source `fn`.
- If the selected callable returns `()`, the application result is unit.
Example:
@@ -749,10 +749,10 @@ At minimum, deterministic static diagnostics are required for:
- invalid named constructor target,
- unresolved named constructor overload,
- ambiguous named constructor overload,
- incompatible top-level `fn` assignment to callback type,
- ambiguous overloaded top-level `fn` assignment to callback type,
- attempted assignment of service method to callback type,
- attempted assignment of host method to callback type,
- incompatible top-level `fn` assignment to `Fn` type,
- ambiguous overloaded top-level `fn` assignment to `Fn` type,
- attempted assignment of service method to `Fn` type,
- attempted assignment of host method to `Fn` type,
- `apply` on a non-callable target,
- arity mismatch in `apply`,
- argument type mismatch in `apply`,
@@ -816,28 +816,29 @@ At minimum, deterministic static diagnostics are required for:
## Existing values and input runtime alignment
The [PBS input and value alignment contract](../../../compiler/pbs/specs/input-and-existing-type-runtime-alignment.md) governs int/Int32, long/Int64, exact builtin carriers, the Pad/Button/LowPad and Touch API, named-argument evaluation order, migration diagnostics and executable conformance. It supersedes older input-object and untyped executable-lowering descriptions.
The [PBS input and value alignment contract](18.%20Input%20and%20Existing%20Type%20Runtime%20Alignment%20Specification.md) governs int/Int32, long/Int64, exact builtin carriers, the Pad/Button/LowPad and Touch API, named-argument evaluation order, migration diagnostics and executable conformance. It supersedes older input-object and untyped executable-lowering descriptions.
## Typed arrays and optional execution extension
The [typed arrays and optional execution specification](../../../compiler/pbs/specs/typed-arrays-and-optional-execution.md) defines array types/construction/indexing, contextual literals, optional bindings and runtime storage. Its rules extend this specification, including source typing, complete groups, Struct/contract execution and diagnostics.
The [Array owner chapter](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md)
defines the complete type, optional-flow and storage contract.
This chapter supplies shared static checks; Array-specific admissibility and
contextual construction are defined by that owner.
Array syntax uses `array<T>` with compositional nesting. Explicit `new array<T>(n)` supplies its type; `new array<>(n)` and `new array(n)` use the expected type. The [Array contract](../../../compiler/pbs/specs/typed-arrays-and-optional-execution.md) defines contextual closers, spans, invariant validation and lowering; obsolete Array spellings are rejected.
Array syntax uses `array<T>` with compositional nesting. Explicit `new array<T>(n)` supplies its type; `new array<>(n)` and `new array(n)` use the expected type. The [Array contract](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md) defines contextual closers, spans, invariant validation and lowering; obsolete Array spellings are rejected.
## Parameterized contracts
Application identity combines the defining nominal declaration with ordered canonical logical arguments after alias resolution. Applications are invariant. Substitution preserves existing type-position restrictions, names, labels and complete groups across Array, Fn, optional, tuples and nested contracts. A struct/service may implement several applications, with complete unique implementations in its owner module. Finite instance recursion is accepted within resource limits; unbounded expansion receives a bounded diagnostic.
See [PBS generic contracts](../../../compiler/pbs/specs/generic-contracts.md).
The [generic contract chapter](16.%20Generic%20Contracts%20Specification.md)
owns the complete application, substitution, coherence and bounded-validation rules.
Compilation and editor analysis MUST share that resolution.
## Concrete generic structs and free functions
Templates are checked symbolically in definition scope. Required concrete owners validate all methods and constructors, including unused methods. Substitute complete bodies and applied Self; preserve position restrictions, invariant nominal/phantom identity and logical groups. Explicit function applications filter generic overloads by type arity; ordinary calls never infer them. Bound owner implementations require complete exact signatures and symbolic overlap rejection before use. Finite recursive applications are anchored; expanding type/body families are bounded errors.
See [Concrete generic structs and free functions](../../../compiler/pbs/specs/generic-structs-and-free-functions.md).
The [generic struct and free-function chapter](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md)
owns the complete application, substitution, coherence and bounded-validation rules.
Compilation and editor analysis MUST share that resolution.
## Controlled guest lifecycle admission
@@ -562,11 +562,11 @@ new coverage; existing behavior MUST NOT regress.
A barrel exports a parameterized contract declaration with the same ordered parameters as its source declaration. Imported bindings retain the original declaration and lexical source scope, including aliases in signatures of dependencies. A local alias never creates another nominal type. Implementations remain in the declaring module of the concrete struct/service owner.
See [PBS generic contracts](../../../compiler/pbs/specs/generic-contracts.md).
See [PBS generic contracts](16.%20Generic%20Contracts%20Specification.md).
## Concrete generic structs and free functions
Generic struct/function barrels export declarations and ordered parameters, including complete function signatures, rather than enumerated specializations. Imports and aliases preserve nominal origins and definition-scoped bodies/private helpers. Specializations are shared across equivalent uses and do not export private dependencies. SDK and program sources use the same language machinery.
See [Concrete generic structs and free functions](../../../compiler/pbs/specs/generic-structs-and-free-functions.md).
See [Concrete generic structs and free functions](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md).
@@ -56,8 +56,8 @@ This document does not define:
Normative precedence:
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
1. Runtime authority ([provider specifications](../../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../../vm-arch/README.md))
2. Bytecode authority ([provider Core ISA](../../../../../runtime/docs/vm-arch/ISA_CORE.md))
3. `1. Language Charter.md`
4. `3. Core Syntax Specification.md`
5. `4. Static Semantics Specification.md`
@@ -45,8 +45,8 @@ This document does not define:
Normative precedence:
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
1. Runtime authority ([provider specifications](../../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../../vm-arch/README.md))
2. Bytecode authority ([provider Core ISA](../../../../../runtime/docs/vm-arch/ISA_CORE.md))
3. `1. Language Charter.md`
4. `3. Core Syntax Specification.md`
5. `4. Static Semantics Specification.md`
@@ -242,7 +242,7 @@ changes the rule:
- user-declared structs,
- services,
- contracts,
- callbacks,
- function values,
- `optional`,
- `result`,
- and any type with runtime-variable or heap-defined width.
@@ -563,4 +563,4 @@ The current temporary contract is:
## Existing values and input runtime alignment
The [PBS input and value alignment contract](../../../compiler/pbs/specs/input-and-existing-type-runtime-alignment.md) governs int/Int32, long/Int64, exact builtin carriers, the Pad/Button/LowPad and Touch API, named-argument evaluation order, migration diagnostics and executable conformance. It supersedes older input-object and untyped executable-lowering descriptions.
The [PBS input and value alignment contract](18.%20Input%20and%20Existing%20Type%20Runtime%20Alignment%20Specification.md) governs int/Int32, long/Int64, exact builtin carriers, the Pad/Button/LowPad and Touch API, named-argument evaluation order, migration diagnostics and executable conformance. It supersedes older input-object and untyped executable-lowering descriptions.
@@ -13,7 +13,7 @@ Its purpose is to make runtime behavior convergent across implementations by fix
- runtime evaluation of expressions and statements,
- abrupt completion and propagation behavior,
- runtime behavior of effect surfaces such as `optional` and `result`,
- the execution boundary between ordinary PBS code, callbacks, contract calls, and host-backed calls.
- the execution boundary between ordinary PBS code, function values, contract calls, and host-backed calls.
## 2. Scope
@@ -22,7 +22,7 @@ This document defines:
- the observable execution model of PBS core,
- evaluation order for expressions, statements, and blocks,
- runtime branch selection for `if` and `switch`,
- runtime application behavior for `apply`, call sugar, methods, contracts, callbacks, and host-backed call surfaces,
- runtime application behavior for `apply`, call sugar, methods, contracts, function values, and host-backed call surfaces,
- runtime behavior of `optional`, `result<E>`, `else`, `!`, and `handle`,
- abrupt completion (`return`, `break`, `continue`) and trap propagation,
- determinism requirements that affect execution behavior.
@@ -39,8 +39,8 @@ This document does not define:
Normative precedence:
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
1. Runtime authority ([provider specifications](../../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../../vm-arch/README.md))
2. Bytecode authority ([provider Core ISA](../../../../../runtime/docs/vm-arch/ISA_CORE.md))
3. `3. Core Syntax Specification.md`
4. `4. Static Semantics Specification.md`
5. This document
@@ -265,7 +265,7 @@ The same observable call model applies to:
- struct methods,
- service methods,
- contract calls,
- callback calls,
- `Fn` calls,
- host-backed calls.
Callable-specific dispatch may differ internally, but it does not change the user-visible sequencing model defined in this document.
@@ -281,7 +281,7 @@ If a callable returns:
### 11.3 Closure creation and invocation
Explicit capture lists snapshot values at creation. Object references retain identity. Calls complete within the current frame; objects may remain reachable between frames. See [First-class functions and explicit value captures](../../../compiler/pbs/specs/first-class-functions-and-captures.md).
Explicit capture lists snapshot values at creation. Object references retain identity. Calls complete within the current frame; objects may remain reachable between frames. See [First-class functions and explicit value captures](15.%20First-Class%20Functions%20and%20Captures%20Specification.md).
## 12. Branch Selection
@@ -377,11 +377,14 @@ This document is ready to move beyond temporary draft status only when:
## Existing values and input runtime alignment
The [PBS input and value alignment contract](../../../compiler/pbs/specs/input-and-existing-type-runtime-alignment.md) governs int/Int32, long/Int64, exact builtin carriers, the Pad/Button/LowPad and Touch API, named-argument evaluation order, migration diagnostics and executable conformance. It supersedes older input-object and untyped executable-lowering descriptions.
The [PBS input and value alignment contract](18.%20Input%20and%20Existing%20Type%20Runtime%20Alignment%20Specification.md) governs int/Int32, long/Int64, exact builtin carriers, the Pad/Button/LowPad and Touch API, named-argument evaluation order, migration diagnostics and executable conformance. It supersedes older input-object and untyped executable-lowering descriptions.
## Typed arrays and optional execution extension
The [typed arrays and optional execution specification](../../../compiler/pbs/specs/typed-arrays-and-optional-execution.md) defines array types/construction/indexing, contextual literals, optional bindings and runtime storage. Its rules extend this specification, including source typing, complete groups, Struct/contract execution and diagnostics.
The [Array owner chapter](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md)
defines the complete type, optional-flow and storage contract.
This chapter supplies common evaluation and abrupt-completion rules; Array-specific
evaluation, presence and mutation rules are defined by that owner.
## Controlled pause and resume hooks
+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.
@@ -1,7 +1,7 @@
# Bytecode and PBX Mapping Specification
The current typed Registry/PBX v0 contract is normative in
[Typed common Registry and PBX v0](../../compiler/general/specs/typed-registry-and-pbx-v0.md).
[Typed common Registry and PBX v0](25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md).
Its complete typed function records, mandatory sections and verification rules
replace the earlier slot-only artifact baseline.
@@ -37,8 +37,8 @@ This document does not define:
Normative precedence:
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
1. Runtime authority ([provider specifications](../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../vm-arch/README.md))
2. Bytecode authority ([provider Core ISA](../../../../runtime/docs/vm-arch/ISA_CORE.md))
3. `docs/specs/compiler-languages/pbs/6.1. Intrinsics and Builtin Types Specification.md`
4. `docs/specs/compiler-languages/pbs/6.2. Host ABI Binding and Loader Resolution Specification.md`
5. `20. IRBackend to IRVM Lowering Specification.md`
@@ -36,7 +36,7 @@ This document does not define:
Normative precedence:
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
1. Runtime authority ([provider specifications](../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../vm-arch/README.md))
2. `1. Language Charter.md`
3. `6.2. Host ABI Binding and Loader Resolution Specification.md`
4. `9. Dynamic Semantics Specification.md`
@@ -1,7 +1,7 @@
# Compiler Verification and Safety Checks Specification
The current typed Registry/PBX v0 contract is normative in
[Typed common Registry and PBX v0](../../compiler/general/specs/typed-registry-and-pbx-v0.md).
[Typed common Registry and PBX v0](25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md).
Its complete typed function records, mandatory sections and verification rules
replace the earlier slot-only artifact baseline.
@@ -43,8 +43,8 @@ This document does not define:
Normative precedence:
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
1. Runtime authority ([provider specifications](../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../vm-arch/README.md))
2. Bytecode authority ([provider Core ISA](../../../../runtime/docs/vm-arch/ISA_CORE.md))
3. `20. IRBackend to IRVM Lowering Specification.md`
4. `21. IRVM Optimization Pipeline Specification.md`
5. `15. Bytecode and PBX Mapping Specification.md`
@@ -1,7 +1,7 @@
# IRBackend to IRVM Lowering Specification
The current typed Registry/PBX v0 contract is normative in
[Typed common Registry and PBX v0](../../compiler/general/specs/typed-registry-and-pbx-v0.md).
[Typed common Registry and PBX v0](25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md).
Its complete typed function records, mandatory sections and verification rules
replace the earlier slot-only artifact baseline.
@@ -46,8 +46,8 @@ This document does not define:
Normative precedence:
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
1. Runtime authority ([provider specifications](../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../vm-arch/README.md))
2. Bytecode authority ([provider Core ISA](../../../../runtime/docs/vm-arch/ISA_CORE.md))
3. This document
4. Frontend-specific lowering specifications, including `docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md`
@@ -33,8 +33,8 @@ This document does not define:
Normative precedence:
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
1. Runtime authority ([provider specifications](../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../vm-arch/README.md))
2. Bytecode authority ([provider Core ISA](../../../../runtime/docs/vm-arch/ISA_CORE.md))
3. `20. IRBackend to IRVM Lowering Specification.md`
4. `15. Bytecode and PBX Mapping Specification.md`
5. This document
@@ -1,7 +1,7 @@
# Backend Spec-to-Test Conformance Matrix
The current typed Registry/PBX v0 contract is normative in
[Typed common Registry and PBX v0](../../compiler/general/specs/typed-registry-and-pbx-v0.md).
[Typed common Registry and PBX v0](25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md).
Its complete typed function records, mandatory sections and verification rules
replace the earlier slot-only artifact baseline.
@@ -33,8 +33,8 @@ This document does not define:
Normative precedence:
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
1. Runtime authority ([provider specifications](../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../vm-arch/README.md))
2. Bytecode authority ([provider Core ISA](../../../../runtime/docs/vm-arch/ISA_CORE.md))
3. `14. Name Resolution and Module Linking Specification.md`
4. `20. IRBackend to IRVM Lowering Specification.md`
5. `21. IRVM Optimization Pipeline Specification.md`
@@ -1,6 +1,15 @@
# Runtime catalog support
Status: normative. Owner: `compiler/general`.
Status: Normative. Owner: `compiler/general`.
Scope: Runtime Catalog Support.
## Authority and scope
This chapter is the canonical owner of the detailed contract described below.
The [domain reading guide](README.md) identifies related chapters and their
separate responsibilities. Cross-cutting chapters refer here for these rules.
Runtime-owned ABI, instruction, resource and execution contracts retain their
authority; this chapter specifies their compiler or PBS consumer requirements.
## Authority and update boundary
@@ -115,14 +124,13 @@ selected runtime MUST identify revision, platform and configuration and distingu
catalog comparison, image loading and execution. PBS facade delivery and
installed-runtime qualification remain separate consumer claims.
See [typed common Registry and PBX v0](typed-registry-and-pbx-v0.md) for the
frontend/backend boundary and [mirror policy](../../../vm-arch/README.md) for
See [typed common Registry and PBX v0](25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md) for the
frontend/backend boundary and [mirror policy](../../vm-arch/README.md) for
explicit verification commands.
## PBS consumer
The [PBS input and value alignment contract](../../pbs/specs/input-and-existing-type-runtime-alignment.md)
The [PBS input and value alignment contract](../compiler-languages/pbs/18.%20Input%20and%20Existing%20Type%20Runtime%20Alignment%20Specification.md)
requires typed Pad/Button dispatch, direct LowPad endpoints and complete builtin
value groups. Frontend numeric literal and builtin-constant operations retain
explicit identity and width; common lowering resolves constant groups against
@@ -130,7 +138,7 @@ explicit identity and width; common lowering resolves constant groups against
not introduce another catalog. Source execution and the full installed example
are separate consumer gates beyond CSV parity.
The [PBS hashing/Identity facade](../../pbs/specs/sdk-set-and-identity.md#hash-facade-and-typed-query-boundary)
The [PBS hashing/Identity facade](../compiler-languages/pbs/23.%20SDK%20Set%20and%20Identity%20Specification.md#hash-facade-and-typed-query-boundary)
consumes hash.i64@1, hash.float@1 and hash.string@1 with exact schema-2 profiles,
null admission and attempted costs. Reference hash/equality are typed Registry
instructions rather than intrinsic catalog rows. Consumer support includes their
@@ -1,10 +1,21 @@
# Typed common Registry and PBX v0
Status: normative. Owner: `compiler/general`. Runtime contract reference:
Status: Normative. Owner: `compiler/general`.
Scope: Typed Registry and PBX v0.
Runtime contract reference:
`runtime` revision `d9b9eeb171d2861ec660d4cf5703b0795eac49a9`,
`docs/specs/runtime/02c-program-registry-and-pbx-v0.md` and
`docs/vm-arch/ISA_CORE.md` in that repository.
## Authority and scope
This chapter is the canonical owner of the detailed contract described below.
The [domain reading guide](README.md) identifies related chapters and their
separate responsibilities. Cross-cutting chapters refer here for these rules.
Runtime-owned ABI, instruction, resource and execution contracts retain their
authority; this chapter specifies their compiler or PBS consumer requirements.
## Ownership and handoff
Every executable frontend MUST provide its semantic types through the common
@@ -155,7 +166,7 @@ consumes both complete groups and costs 4+w(left)+w(right). Immediates are stati
program-local TypeIds (u32 LE after u16 LE opcode), and results preserve provider
faults, signed long bits, provenance and charged attempts, including unused results.
Set algorithms and equality policy remain frontend/SDK consumers, described for
PBS in [Set/Identity](../../pbs/specs/sdk-set-and-identity.md).
PBS in [Set/Identity](../compiler-languages/pbs/23.%20SDK%20Set%20and%20Identity%20Specification.md).
HOSTCALL references a declared canonical `(module, name, version)` identity
with exact argument/result slot ABI. Duplicate identities with conflicting ABI,
@@ -201,7 +212,6 @@ emission without PBS. Frontend migration and integrated release readiness are
tracked separately in AGD75; passing common conformance does not claim complete
PBS lowering or complete Studio/runtime integration.
## Minimal typed storage and range copy
The supported collection storage operations are STRUCT_NEW/GET/SET (0xA0–0xA2),
@@ -266,7 +276,6 @@ the current PC; they neither roll back nor complete a method. No atomic observat
of source operations by host/debugger is promised. SDK methods introduce no user
callbacks or explicit suspension during the updates that complete their invariants.
## Producer-selected guest hook roots
BeforePause/BeforeResume role targets and their transitive dependencies MUST
+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.
+6 -1
View File
@@ -1,5 +1,7 @@
# Packer Specs
Owner: `packer`. Canonical source: `docs/specs/packer`.
This directory contains the normative packer specification set.
## Purpose
@@ -47,7 +49,7 @@ Specs should normally be fed by:
1. agendas that frame the open topic,
2. decisions that close the architectural question,
3. pull-request plans that define propagation,
3. plans that define propagation,
4. then spec integration.
If a spec edit would require guessing an unresolved design choice, stop and surface the missing decision first.
@@ -77,3 +79,6 @@ Recommended order:
4. build artifacts;
5. diagnostics and Studio operation model;
6. versioning and trust.
See the [specification guide](../README.md) for compiler, language and provider boundaries.
@@ -36,10 +36,10 @@ This specification extends:
For packer-facing semantics, this specification must align with:
- [`../../packer/specs/1. Domain and Artifact Boundary Specification.md`](../../packer/specs/1.%20Domain%20and%20Artifact%20Boundary%20Specification.md)
- [`../../packer/specs/2. Workspace, Registry, and Asset Identity Specification.md`](../../packer/specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
- [`../../packer/specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../../packer/specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
- [`../../packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../../packer/specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
- [`../packer/1. Domain and Artifact Boundary Specification.md`](../packer/1.%20Domain%20and%20Artifact%20Boundary%20Specification.md)
- [`../packer/2. Workspace, Registry, and Asset Identity Specification.md`](../packer/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
- [`../packer/3. Asset Declaration and Virtual Asset Contract Specification.md`](../packer/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
- [`../packer/5. Diagnostics, Operations, and Studio Integration Specification.md`](../packer/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
If this document conflicts with the global Studio shell specifications, the shell specifications control shell-wide behavior and this document controls workspace-local behavior.
+5
View File
@@ -1,5 +1,7 @@
# Studio Specs
Owner: `studio`. Canonical source: `docs/specs/studio`.
This directory contains the normative Studio specification set.
## Purpose
@@ -95,3 +97,6 @@ automated results and user-confirmed manual acceptance are consolidated in
[LSN-0077](../../../discussion/lessons/DSC-0070-studio-persistent-mcp-connector/LSN-0077-integrated-mcp-stable-setup-and-ephemeral-access.md).
The earlier HTTP evidence was not substituted for these gates. The embedded
terminal remains separate.
See the [specification guide](../README.md) for compiler, language and provider boundaries.
+2 -2
View File
@@ -28,7 +28,7 @@ that the mirrors are synchronized. If the runtime repository is not available
in the same checkout, synchronization evidence must be produced against the
canonical runtime revision before merging.
Compiler-owned transformation contracts remain under `docs/compiler/general/specs`.
Compiler-owned transformation contracts remain under `docs/specs/compiler`.
Those specifications define `IRBackend -> IRVM -> PBX` emission, but they MUST
conform to the runtime-owned PBX and ISA contracts and MUST NOT redefine runtime
execution semantics.
@@ -52,7 +52,7 @@ build output in a temporary directory. Missing or different evidence sources fai
explicitly. Ordinary builds and local catalog tests never invoke this command.
The manual port and consumer requirements are defined in
[Runtime catalog support](../compiler/general/specs/runtime-catalog-support.md).
[Runtime catalog support](../specs/compiler/24.%20Runtime%20Catalog%20Support%20Specification.md).
The selected provider publishes intrinsic schema 2 (25 columns). Manual compiler
metadata must retain every nullable bit, invocation/scratch/context profile and