add and update docs/specs
This commit is contained in:
parent
6f4defdf00
commit
c68563d203
@ -5,7 +5,7 @@ Purpose: validate whether the current Host ABI contract is already stable enough
|
||||
|
||||
## 1. Context
|
||||
|
||||
This agenda validates whether `6. Host ABI Binding and Loader Resolution Specification.md` is already sufficient as the working contract for the path:
|
||||
This agenda validates whether `6.2. Host ABI Binding and Loader Resolution Specification.md` is already sufficient as the working contract for the path:
|
||||
|
||||
`declare host` -> PBX metadata -> loader resolution -> numeric syscall execution
|
||||
|
||||
@ -58,6 +58,6 @@ That means:
|
||||
|
||||
## 6. References
|
||||
|
||||
- `6. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `7. Cartridge Manifest and Runtime Capabilities Specification.md`
|
||||
- `8. Stdlib Environment Packaging and Loading Specification.md`
|
||||
|
||||
524
docs/agendas/PBS Intrinsics and Builtin Types Agenda.md
Normal file
524
docs/agendas/PBS Intrinsics and Builtin Types Agenda.md
Normal file
@ -0,0 +1,524 @@
|
||||
# PBS Intrinsics and Builtin Types
|
||||
|
||||
Status: draft
|
||||
|
||||
This document defines a proposed intrinsic model for PBS and the Prometeu VM.
|
||||
Its goal is to let the frontend expose builtin types such as `color`, `vec2`,
|
||||
and `pixel` as first-class language entities while keeping their behavior
|
||||
implemented canonically inside the VM.
|
||||
|
||||
The design intentionally avoids coupling builtin types to the HAL. Host-backed
|
||||
behavior continues to flow through syscalls. Builtin domain behavior flows
|
||||
through VM intrinsics.
|
||||
|
||||
## 1. Objectives
|
||||
|
||||
This model exists to satisfy these constraints:
|
||||
|
||||
1. Builtin types must be real language types, not just naming conventions.
|
||||
2. Builtin values must remain stack-only unless explicitly specified otherwise.
|
||||
3. Domain behavior of builtin types must execute in the VM, not in frontend-
|
||||
generated helper code, so semantics remain canonical.
|
||||
4. Host integration must stay separate from builtin semantics.
|
||||
5. The verifier must be able to validate intrinsic calls using slot layouts.
|
||||
6. The model must scale from scalar builtins such as `color` to fixed-layout
|
||||
aggregates such as `vec2` and `pixel`.
|
||||
|
||||
## 2. Non-Objectives
|
||||
|
||||
This document does not define:
|
||||
|
||||
1. Final parser syntax for every frontend language.
|
||||
2. The full bytecode encoding that will ship in the first implementation.
|
||||
3. Heap-backed builtin types.
|
||||
4. User-extensible intrinsics.
|
||||
|
||||
## 3. Terms
|
||||
|
||||
### 3.1 Builtin type
|
||||
|
||||
A builtin type is a language-level type whose semantic identity is owned by the
|
||||
runtime platform rather than by user code.
|
||||
|
||||
Examples:
|
||||
|
||||
- `color`
|
||||
- `vec2`
|
||||
- `pixel`
|
||||
|
||||
### 3.2 Physical slot layout
|
||||
|
||||
Each builtin type has a canonical physical representation in VM slots.
|
||||
|
||||
Examples:
|
||||
|
||||
- `color` -> 1 slot
|
||||
- `vec2` -> 2 slots
|
||||
- `pixel` -> 3 slots
|
||||
|
||||
### 3.3 Intrinsic
|
||||
|
||||
An intrinsic is a VM-owned operation with a canonical semantic definition.
|
||||
|
||||
An intrinsic is not:
|
||||
|
||||
- a user function
|
||||
- a syscall
|
||||
- a host callback
|
||||
|
||||
An intrinsic is callable, but it is executed entirely by the VM.
|
||||
|
||||
## 4. Three Kinds of Calls
|
||||
|
||||
The execution model should distinguish three categories:
|
||||
|
||||
### 4.1 Function call
|
||||
|
||||
Calls user-defined code.
|
||||
|
||||
- Owned by the program
|
||||
- Compiled from source bodies
|
||||
- Executed through normal `CALL`
|
||||
|
||||
### 4.2 Intrinsic call
|
||||
|
||||
Calls VM-defined builtin behavior.
|
||||
|
||||
- Owned by the VM
|
||||
- Declared in the frontend as builtin members or builtin operations
|
||||
- Executed through an intrinsic dispatch path
|
||||
|
||||
### 4.3 Syscall
|
||||
|
||||
Calls host-managed services.
|
||||
|
||||
- Owned by the host platform
|
||||
- Resolved by canonical identity and capability checks
|
||||
- Executed through `SYSCALL`
|
||||
|
||||
The rule is simple:
|
||||
|
||||
- builtin semantics -> intrinsic
|
||||
- host/platform behavior -> syscall
|
||||
|
||||
## 5. Builtin Types Are Values, Not Just Method Bags
|
||||
|
||||
A builtin type must define more than methods. It must define its value model.
|
||||
|
||||
Each builtin type should specify:
|
||||
|
||||
1. Semantic identity
|
||||
2. Physical slot layout
|
||||
3. Named fields or projections
|
||||
4. Construction rules
|
||||
5. Constants, if any
|
||||
6. Intrinsic operations
|
||||
|
||||
### 5.1 Example: `color`
|
||||
|
||||
`color` is a scalar builtin type.
|
||||
|
||||
- Semantic meaning: RGB565 color
|
||||
- Physical layout: 1 slot
|
||||
- Domain behavior: conversions, comparisons, construction helpers
|
||||
|
||||
Illustrative shape:
|
||||
|
||||
```text
|
||||
builtin type color {
|
||||
layout: [color]
|
||||
|
||||
static fn from_raw(raw: int) -> color
|
||||
static fn rgb(r: int, g: int, b: int) -> color
|
||||
}
|
||||
```
|
||||
|
||||
The physical carrier for a scalar builtin may be:
|
||||
|
||||
- a dedicated `Value` variant such as `Value::Color(u16)`, or
|
||||
- another canonical 1-slot carrier defined by the VM ABI
|
||||
|
||||
The semantic type remains `color` either way.
|
||||
|
||||
### 5.2 Example: `vec2`
|
||||
|
||||
`vec2` is a fixed-layout aggregate builtin type.
|
||||
|
||||
- Semantic meaning: 2D vector
|
||||
- Physical layout: 2 slots
|
||||
- Field projections: `x`, `y`
|
||||
- Domain behavior: `dot`, `length`, `distance`
|
||||
|
||||
Illustrative shape:
|
||||
|
||||
```text
|
||||
builtin type vec2 {
|
||||
layout: [float, float]
|
||||
|
||||
field x: float @slot(0)
|
||||
field y: float @slot(1)
|
||||
|
||||
static fn new(x: float, y: float) -> vec2
|
||||
|
||||
fn dot(other: vec2) -> float
|
||||
fn length() -> float
|
||||
fn distance(other: vec2) -> float
|
||||
}
|
||||
```
|
||||
|
||||
### 5.3 Example: `pixel`
|
||||
|
||||
`pixel` is also a fixed-layout aggregate builtin type.
|
||||
|
||||
- Semantic meaning: position + color
|
||||
- Physical layout: 3 slots
|
||||
|
||||
Illustrative shape:
|
||||
|
||||
```text
|
||||
builtin type pixel {
|
||||
layout: [int, int, color]
|
||||
|
||||
field x: int @slot(0)
|
||||
field y: int @slot(1)
|
||||
field color: color @slot(2)
|
||||
|
||||
static fn new(x: int, y: int, color: color) -> pixel
|
||||
}
|
||||
```
|
||||
|
||||
The key point is that `pixel` is still a first-class type in the language even
|
||||
though it occupies three stack slots physically.
|
||||
|
||||
## 6. Frontend Contract
|
||||
|
||||
Frontend languages should expose builtin types through a builtin registry or
|
||||
prelude, not through normal user modules.
|
||||
|
||||
The frontend may present syntax such as:
|
||||
|
||||
- `vec2`
|
||||
- `vec2.new(1.0, 2.0)`
|
||||
- `v.x`
|
||||
- `v.dot(other)`
|
||||
|
||||
But user code must not provide the implementation body of builtin members.
|
||||
|
||||
The frontend owns:
|
||||
|
||||
- syntax
|
||||
- name resolution
|
||||
- type checking
|
||||
- lowering decisions
|
||||
|
||||
The frontend does not own:
|
||||
|
||||
- builtin semantics
|
||||
- builtin numeric algorithms
|
||||
- host integration behavior
|
||||
|
||||
### 6.1 Builtin declarations are semantic shells
|
||||
|
||||
For FE purposes, a builtin declaration behaves like an interface or shell with
|
||||
no user body.
|
||||
|
||||
For example:
|
||||
|
||||
```text
|
||||
builtin type vec2 {
|
||||
field x: float
|
||||
field y: float
|
||||
|
||||
static fn new(x: float, y: float) -> vec2
|
||||
fn dot(other: vec2) -> float
|
||||
}
|
||||
```
|
||||
|
||||
The frontend uses this declaration to type-check source programs, but lowering
|
||||
must map each member access to VM-defined behavior.
|
||||
|
||||
## 7. Lowering Rules
|
||||
|
||||
### 7.1 Construction
|
||||
|
||||
Construction of a builtin aggregate does not necessarily require a VM
|
||||
intrinsic.
|
||||
|
||||
If the physical layout is already the canonical stack layout, the frontend may
|
||||
lower construction to ordinary pushes or tuple shaping.
|
||||
|
||||
Examples:
|
||||
|
||||
- `vec2.new(x, y)` -> push `x`, push `y`
|
||||
- `pixel.new(x, y, c)` -> push `x`, push `y`, push `c`
|
||||
|
||||
The constructor remains semantically builtin even if its lowering is a pure
|
||||
layout operation.
|
||||
|
||||
### 7.2 Field projection
|
||||
|
||||
Field projection also does not necessarily require a VM intrinsic.
|
||||
|
||||
If a builtin type has a fixed stack layout, the frontend may lower field access
|
||||
through canonical slot projection rules.
|
||||
|
||||
Examples:
|
||||
|
||||
- `vec2.x` -> project slot 0
|
||||
- `vec2.y` -> project slot 1
|
||||
- `pixel.color` -> project slot 2
|
||||
|
||||
If projection requires non-trivial stack reshaping, the compiler may emit
|
||||
helper stack operations or a dedicated intrinsic. The semantic rule remains the
|
||||
same.
|
||||
|
||||
### 7.3 Domain behavior
|
||||
|
||||
Operations whose meaning belongs to the builtin domain should lower to
|
||||
intrinsics.
|
||||
|
||||
Examples:
|
||||
|
||||
- `v1.dot(v2)` -> intrinsic
|
||||
- `v.length()` -> intrinsic
|
||||
- `v.distance(other)` -> intrinsic
|
||||
|
||||
This is the core reason intrinsics exist: the semantics of these operations
|
||||
must be owned by the VM rather than by frontend-emitted helper code.
|
||||
|
||||
## 8. Intrinsic Identity
|
||||
|
||||
Intrinsics should be language-independent.
|
||||
|
||||
A canonical identity should use:
|
||||
|
||||
```text
|
||||
(owner, name, version)
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
- `("color", "rgb", 1)`
|
||||
- `("vec2", "dot", 1)`
|
||||
- `("vec2", "length", 1)`
|
||||
- `("vec2", "distance", 1)`
|
||||
|
||||
`owner` may be:
|
||||
|
||||
- a builtin type name, such as `vec2`
|
||||
- a builtin namespace, if needed later
|
||||
|
||||
This identity is used by the frontend and by any optional preload artifact
|
||||
format. The VM may execute a compact numeric intrinsic id after resolution.
|
||||
|
||||
## 9. Intrinsic Metadata
|
||||
|
||||
The VM should own a canonical intrinsic registry.
|
||||
|
||||
Illustrative shape:
|
||||
|
||||
```text
|
||||
IntrinsicMeta {
|
||||
id: u32
|
||||
owner: string
|
||||
name: string
|
||||
version: u16
|
||||
arg_layout: [AbiType]
|
||||
ret_layout: [AbiType]
|
||||
deterministic: bool
|
||||
may_allocate: bool
|
||||
cost_hint: u32
|
||||
}
|
||||
```
|
||||
|
||||
`AbiType` must describe physical slot layout, not just source syntax.
|
||||
|
||||
Illustrative shape:
|
||||
|
||||
```text
|
||||
AbiType =
|
||||
Int32
|
||||
Int64
|
||||
Float64
|
||||
Bool
|
||||
String
|
||||
Handle
|
||||
Color
|
||||
Aggregate([AbiType])
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
- `color` -> `Color`
|
||||
- `vec2` -> `Aggregate([Float64, Float64])`
|
||||
- `pixel` -> `Aggregate([Int32, Int32, Color])`
|
||||
|
||||
Flattening into slots is canonical. For verifier purposes:
|
||||
|
||||
- `Color` consumes 1 slot
|
||||
- `Aggregate([Float64, Float64])` consumes 2 slots
|
||||
- `Aggregate([Int32, Int32, Color])` consumes 3 slots
|
||||
|
||||
## 10. Bytecode Model
|
||||
|
||||
This specification recommends a distinct intrinsic instruction path.
|
||||
|
||||
Illustrative final executable form:
|
||||
|
||||
```text
|
||||
INTRINSIC <id>
|
||||
```
|
||||
|
||||
The VM interprets `<id>` using the intrinsic registry.
|
||||
|
||||
An optional preload artifact may use a declaration table, similar to syscall
|
||||
resolution:
|
||||
|
||||
```text
|
||||
INTRCALL <decl_index>
|
||||
```
|
||||
|
||||
with:
|
||||
|
||||
```text
|
||||
IntrinsicDecl {
|
||||
owner: string
|
||||
name: string
|
||||
version: u16
|
||||
}
|
||||
```
|
||||
|
||||
The loader may then resolve:
|
||||
|
||||
```text
|
||||
INTRCALL <decl_index> -> INTRINSIC <id>
|
||||
```
|
||||
|
||||
This mirrors syscall resolution without introducing host coupling.
|
||||
|
||||
If the implementation prefers, PBS may also emit final `INTRINSIC <id>`
|
||||
directly once the intrinsic registry is stable.
|
||||
|
||||
## 11. Verifier Rules
|
||||
|
||||
The verifier must treat intrinsics as first-class stack effects with known
|
||||
layouts.
|
||||
|
||||
For each intrinsic, the verifier must know:
|
||||
|
||||
1. input slot count
|
||||
2. output slot count
|
||||
3. slot layout
|
||||
4. whether allocation is allowed
|
||||
|
||||
Example:
|
||||
|
||||
```text
|
||||
vec2.dot(vec2, vec2) -> float
|
||||
```
|
||||
|
||||
Canonical flattened layout:
|
||||
|
||||
- args: `[float, float, float, float]`
|
||||
- returns: `[float]`
|
||||
|
||||
So verifier stack effect is:
|
||||
|
||||
```text
|
||||
pop 4, push 1
|
||||
```
|
||||
|
||||
Another example:
|
||||
|
||||
```text
|
||||
pixel.new(int, int, color) -> pixel
|
||||
```
|
||||
|
||||
Flattened layout:
|
||||
|
||||
- args: `[int, int, color]`
|
||||
- returns: `[int, int, color]`
|
||||
|
||||
This may be lowered as:
|
||||
|
||||
- no-op stack shaping, or
|
||||
- a constructor intrinsic with `pop 3, push 3`
|
||||
|
||||
The verifier must reason about the actual lowered form.
|
||||
|
||||
## 12. Determinism Rules
|
||||
|
||||
Intrinsic behavior must be VM-canonical.
|
||||
|
||||
This means:
|
||||
|
||||
1. Intrinsics must not call the host.
|
||||
2. Intrinsics must not depend on wall-clock time.
|
||||
3. Intrinsics must not depend on frontend-generated helper algorithms.
|
||||
4. Numeric behavior must be specified tightly enough for portability.
|
||||
|
||||
This matters especially for floating-point operations such as:
|
||||
|
||||
- `vec2.length`
|
||||
- `vec2.distance`
|
||||
|
||||
If the platform requires strong cross-host determinism, the VM must define the
|
||||
numeric behavior precisely enough to avoid backend drift. Depending on the final
|
||||
design, that may mean:
|
||||
|
||||
- canonical floating-point rules
|
||||
- constrained instruction sequences
|
||||
- fixed-point math for some domains
|
||||
|
||||
The important requirement is semantic ownership by the VM.
|
||||
|
||||
## 13. Separation from HAL
|
||||
|
||||
Builtin types must not be defined by HAL types.
|
||||
|
||||
Correct layering:
|
||||
|
||||
1. PBS and the VM define builtin semantic types.
|
||||
2. The VM defines intrinsic behavior.
|
||||
3. Syscalls bridge VM values to host services.
|
||||
4. The HAL adapts host/runtime values to device-specific behavior.
|
||||
|
||||
For example:
|
||||
|
||||
- `color` is a VM builtin type
|
||||
- `gfx.clear(color)` is a syscall using a `color` argument
|
||||
- the host runtime converts that value into any HAL-specific color adapter
|
||||
|
||||
The HAL may consume builtin values, but it must not own their language-level
|
||||
definition.
|
||||
|
||||
## 14. Recommended Initial Scope
|
||||
|
||||
A minimal first wave should support:
|
||||
|
||||
1. Scalar builtin type:
|
||||
- `color`
|
||||
2. Aggregate builtin types:
|
||||
- `vec2`
|
||||
- `pixel`
|
||||
3. Intrinsic-only domain methods for `vec2`:
|
||||
- `dot`
|
||||
- `length`
|
||||
- `distance`
|
||||
|
||||
Initial constructor and field access lowering may remain compiler-driven when
|
||||
they are pure layout operations.
|
||||
|
||||
## 15. Summary
|
||||
|
||||
This proposal establishes the following model:
|
||||
|
||||
1. Builtin types are first-class language types with canonical slot layouts.
|
||||
2. Stack-only builtin aggregates are valid even when they occupy multiple slots.
|
||||
3. Frontends expose builtin declarations as semantic shells, not as user-
|
||||
implemented code.
|
||||
4. Construction and field projection may lower directly to canonical stack
|
||||
layout operations.
|
||||
5. Builtin domain behavior lowers to VM intrinsics.
|
||||
6. Syscalls remain exclusively for host-backed behavior.
|
||||
7. The VM, not the frontend or HAL, owns the semantics of builtin operations.
|
||||
131
docs/specs/pbs/10. Memory and Lifetime Specification.md
Normal file
131
docs/specs/pbs/10. Memory and Lifetime Specification.md
Normal file
@ -0,0 +1,131 @@
|
||||
# PBS Memory and Lifetime Specification
|
||||
|
||||
Status: Draft v0 (Skeleton)
|
||||
Applies to: runtime memory spaces, value representation classes, identity, aliasing, GC baseline, and host-memory boundaries in PBS core
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document will define the authoritative PBS memory and lifetime model for v1.
|
||||
|
||||
Its purpose is to make the language's runtime storage model explicit enough that:
|
||||
|
||||
- implementations agree on which values are heap-backed,
|
||||
- identity and aliasing are not left implicit,
|
||||
- GC remains compatible with deterministic execution,
|
||||
- the VM heap and host-owned memory boundary stay understandable,
|
||||
- tooling can surface runtime-visible memory and allocation costs consistently.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document is intended to define:
|
||||
|
||||
- runtime memory spaces relevant to PBS user semantics,
|
||||
- value categories and their representation classes,
|
||||
- identity, aliasing, and copy behavior,
|
||||
- baseline GC guarantees and non-guarantees,
|
||||
- host-memory boundary rules,
|
||||
- memory-related safety invariants and remaining runtime failure boundaries,
|
||||
- hooks that later diagnostics and tooling may rely on for cost reporting.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- exact GC algorithm internals,
|
||||
- general-purpose allocator APIs,
|
||||
- future explicit lifetime syntax activation,
|
||||
- final IR lowering details,
|
||||
- subsystem-specific host resource APIs.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
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`)
|
||||
3. `1. Language Charter.md`
|
||||
4. `3. Core Syntax Specification.md`
|
||||
5. `4. Static Semantics Specification.md`
|
||||
6. `9. Dynamic Semantics Specification.md`
|
||||
7. This document
|
||||
|
||||
If a rule here conflicts with higher authority, it is invalid.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on, at minimum:
|
||||
|
||||
- `1. Language Charter.md`
|
||||
- `3. Core Syntax Specification.md`
|
||||
- `4. Static Semantics Specification.md`
|
||||
- `9. Dynamic Semantics Specification.md`
|
||||
|
||||
This document is expected to be closed using decisions from:
|
||||
|
||||
- `docs/agendas/Heap Model - Agenda.md`
|
||||
- `docs/agendas/Memory and Lifetime - Agenda.md`
|
||||
- `docs/agendas/Dynamic Semantics - Execution Model Agenda.md`
|
||||
- `docs/agendas/Dynamic Semantics - Effect Surfaces Agenda.md`
|
||||
|
||||
## 5. Already-Settled Inputs
|
||||
|
||||
The following inputs are already fixed elsewhere and must not be contradicted here:
|
||||
|
||||
- Struct values are heap-backed reference values in v1 core.
|
||||
- Assigning a struct value copies the reference, not the underlying field storage.
|
||||
- Service values are canonical module-owned singleton values in v1 core.
|
||||
- Assigning a service value copies the same singleton identity and does not create a new instance.
|
||||
- `declare const` values are compile-time constants rather than mutable runtime module storage.
|
||||
- Advanced memory syntax such as `alloc`, `borrow`, `mutate`, `peek`, `take`, and `weak` is not active in PBS core v1.
|
||||
|
||||
## 6. Initial Section Targets
|
||||
|
||||
At minimum, the completed document should contain normative sections for:
|
||||
|
||||
1. runtime memory spaces,
|
||||
2. value representation classes,
|
||||
3. identity and aliasing,
|
||||
4. copy and passing behavior,
|
||||
5. GC guarantees and safepoint constraints,
|
||||
6. host-memory boundary rules,
|
||||
7. memory-related safety properties,
|
||||
8. cost visibility hooks consumed by diagnostics/tooling.
|
||||
|
||||
## 7. A Ver
|
||||
|
||||
The following items remain to be closed in agenda discussion before this document can be considered complete.
|
||||
|
||||
### 7.1 `Memory and Lifetime - Agenda.md`
|
||||
|
||||
- Heap residency by value category beyond already-settled struct and service behavior.
|
||||
- Which values have stable user-visible identity.
|
||||
- Exact aliasing story for tuples, callbacks, collections, `optional`, and `result<E>`.
|
||||
- Normative GC guarantees versus implementation-defined GC details.
|
||||
- Representation and safety model of host-backed resources and handles.
|
||||
|
||||
### 7.2 `Heap Model - Agenda.md`
|
||||
|
||||
- Cross-cutting visibility of allocation, copy, retention, and host-boundary costs.
|
||||
- Which memory facts are normative versus profiler-quality best effort.
|
||||
- Migration policy and activation criteria for reserved lifetime keywords in future profiles.
|
||||
|
||||
### 7.3 `Dynamic Semantics - Execution Model Agenda.md` and `Dynamic Semantics - Effect Surfaces Agenda.md`
|
||||
|
||||
- Which constructs allocate or retain memory during ordinary execution.
|
||||
- Which effect-bearing constructs may trap only because their subexpressions trap.
|
||||
- Which safepoints are observable versus implementation detail.
|
||||
|
||||
## 8. Non-Goals
|
||||
|
||||
- Designing full pool, arena, or weak-reference libraries in this pass.
|
||||
- Reintroducing mandatory user-authored lifetime syntax in core v1.
|
||||
- Defining exact collector implementation strategy.
|
||||
- Rewriting already-settled source syntax.
|
||||
|
||||
## 9. Exit Criteria
|
||||
|
||||
This document is ready to move beyond skeleton status only when:
|
||||
|
||||
1. every core value category has an explicit representation and aliasing story,
|
||||
2. GC guarantees and non-guarantees are separated clearly,
|
||||
3. the VM heap versus host-memory boundary is normatively described,
|
||||
4. memory-related costs are specified well enough for diagnostics/tooling hooks,
|
||||
5. the document no longer relies on unresolved `A Ver` items for ordinary v1 behavior.
|
||||
133
docs/specs/pbs/11. Diagnostics Specification.md
Normal file
133
docs/specs/pbs/11. Diagnostics Specification.md
Normal file
@ -0,0 +1,133 @@
|
||||
# PBS Diagnostics Specification
|
||||
|
||||
Status: Draft v0 (Skeleton)
|
||||
Applies to: deterministic diagnostics emitted by PBS-facing tooling across parsing, static analysis, manifest/import resolution, lowering boundaries, and related load-facing validation surfaces
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document will define the PBS diagnostics contract.
|
||||
|
||||
Its purpose is to make diagnostics stable enough that:
|
||||
|
||||
- conforming tools report failures in the same places,
|
||||
- users receive deterministic and actionable feedback,
|
||||
- conformance can validate not only acceptance/rejection but also diagnostic class and location,
|
||||
- frontend, manifest, and load-facing validation remain aligned.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document is intended to define:
|
||||
|
||||
- diagnostic categories and phases,
|
||||
- minimum metadata carried by diagnostics,
|
||||
- stability expectations for source spans, file attribution, and phase attribution,
|
||||
- the normative relationship between syntax/static diagnostics and later lowering/load diagnostics,
|
||||
- which diagnostics are required versus implementation-defined enrichments,
|
||||
- cost-visibility diagnostics or warnings once memory/effect decisions are closed.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- the full runtime trap catalog,
|
||||
- UI presentation or IDE styling,
|
||||
- implementation-specific hint ranking,
|
||||
- profiling output formats.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. `1. Language Charter.md`
|
||||
2. `3. Core Syntax Specification.md`
|
||||
3. `4. Static Semantics Specification.md`
|
||||
4. `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
5. `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
6. `7. Cartridge Manifest and Runtime Capabilities Specification.md`
|
||||
7. `9. Dynamic Semantics Specification.md`
|
||||
8. `10. Memory and Lifetime Specification.md`
|
||||
9. `12. IR and Lowering Specification.md`
|
||||
10. This document
|
||||
|
||||
If a diagnostic rule here contradicts a normative acceptance/rejection rule in a higher-precedence document, the higher-precedence document wins.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on, at minimum:
|
||||
|
||||
- `3. Core Syntax Specification.md`
|
||||
- `4. Static Semantics Specification.md`
|
||||
- `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `7. Cartridge Manifest and Runtime Capabilities Specification.md`
|
||||
|
||||
This document will also depend on decisions closed in:
|
||||
|
||||
- `9. Dynamic Semantics Specification.md`
|
||||
- `10. Memory and Lifetime Specification.md`
|
||||
- the future backend agenda sequence tracked in `docs/agendas/`
|
||||
|
||||
## 5. Already-Settled Inputs
|
||||
|
||||
The following inputs are already fixed elsewhere and must not be contradicted here:
|
||||
|
||||
- The syntax specification already enumerates minimum required syntax diagnostics.
|
||||
- The static semantics specification already enumerates minimum required static diagnostics.
|
||||
- Manifest/import resolution failures are required to be deterministic compile-time errors.
|
||||
- Loader failures around malformed or unauthorized host usage are required to be deterministic.
|
||||
- Stable source span metadata is required at the token level and must remain useful to later diagnostics.
|
||||
|
||||
## 6. Initial Section Targets
|
||||
|
||||
At minimum, the completed document should contain normative sections for:
|
||||
|
||||
1. diagnostic phases,
|
||||
2. required diagnostic metadata,
|
||||
3. span and file attribution,
|
||||
4. syntax-diagnostic contract,
|
||||
5. static-diagnostic contract,
|
||||
6. manifest/import-resolution diagnostics,
|
||||
7. lowering and host-binding diagnostics,
|
||||
8. load-facing and capability diagnostics,
|
||||
9. cost-visibility diagnostics and warnings.
|
||||
|
||||
## 7. A Ver
|
||||
|
||||
The following items remain to be closed before this document can be considered complete.
|
||||
|
||||
### 7.1 Depends on `9. Dynamic Semantics Specification.md`
|
||||
|
||||
- Which runtime-observable trap categories need source-facing compile-time or conformance hooks.
|
||||
- Which constructs require special diagnostics for abrupt completion, propagation, or effect misuse beyond what static semantics already lists.
|
||||
|
||||
### 7.2 Depends on `10. Memory and Lifetime Specification.md`
|
||||
|
||||
- Which allocations, copies, escapes, and host-boundary crossings must surface as normative diagnostics or warnings.
|
||||
- Which cost facts are mandatory versus implementation-defined enrichment.
|
||||
|
||||
### 7.3 Depends on the future backend agenda sequence tracked in `docs/agendas/`
|
||||
|
||||
- Whether diagnostic stability includes IR/lowering phase names, artifact offsets, or source maps.
|
||||
- How host-binding lowering failures are surfaced back to source locations.
|
||||
- Whether verifier/load diagnostics are part of the PBS diagnostics contract directly or only through artifact-facing tooling.
|
||||
|
||||
### 7.4 Still to decide inside this document
|
||||
|
||||
- Whether diagnostic codes are mandatory in v1.
|
||||
- Which portions of human-readable wording are normative versus illustrative.
|
||||
- Whether notes/help text are required, optional, or outside conformance.
|
||||
- Exact cross-file diagnostic expectations for module/barrel/import failures.
|
||||
|
||||
## 8. Non-Goals
|
||||
|
||||
- Mandating one UI or IDE presentation style.
|
||||
- Freezing a localization strategy in this pass.
|
||||
- Turning every optimization hint into a normative diagnostic.
|
||||
- Replacing the acceptance/rejection rules already defined elsewhere.
|
||||
|
||||
## 9. Exit Criteria
|
||||
|
||||
This document is ready to move beyond skeleton status only when:
|
||||
|
||||
1. every required rejection in the current spec set is mapped to a diagnostic phase,
|
||||
2. diagnostic metadata and attribution rules are explicit enough for conformance,
|
||||
3. cost-visibility expectations are aligned with memory/effect specs,
|
||||
4. the document no longer relies on unresolved backend and runtime-facing `A Ver` items for v1 tooling behavior.
|
||||
136
docs/specs/pbs/12. IR and Lowering Specification.md
Normal file
136
docs/specs/pbs/12. IR and Lowering Specification.md
Normal file
@ -0,0 +1,136 @@
|
||||
# PBS IR and Lowering Specification
|
||||
|
||||
Status: Draft v0 (Skeleton)
|
||||
Applies to: lowering of bound PBS programs into internal compiler IR and runtime-facing artifacts
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document will define the normative lowering contract from PBS source semantics to implementation artifacts.
|
||||
|
||||
Its purpose is to make backend-facing behavior explicit enough that:
|
||||
|
||||
- different compilers lower the same bound program compatibly,
|
||||
- host-binding emission does not drift from frontend resolution,
|
||||
- builtin and intrinsic lowering does not drift from VM-owned metadata,
|
||||
- later verifier and loader behavior can rely on stable artifact expectations,
|
||||
- conformance can test more than parser and binder behavior.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document is intended to define:
|
||||
|
||||
- the minimum semantic obligations of the compiler after parsing, binding, and type checking,
|
||||
- the role of internal IR as an implementation stage,
|
||||
- what semantic facts lowering must preserve,
|
||||
- lowering of control flow, calls, callbacks, services, contracts, constants, and host-backed calls,
|
||||
- lowering of builtin projections, builtin constants, and intrinsic member calls,
|
||||
- artifact-facing requirements that must hold before loader/verifier consumption.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- the full PBX binary layout,
|
||||
- optimizer heuristics or performance tuning strategy,
|
||||
- the exact in-memory data structures of one compiler implementation,
|
||||
- runtime GC algorithm internals.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
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`)
|
||||
3. `3. Core Syntax Specification.md`
|
||||
4. `4. Static Semantics Specification.md`
|
||||
5. `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
6. `6. VM-owned vs Host-backed.md`
|
||||
7. `6.1. Intrinsics and Builtin Types Specification.md`
|
||||
8. `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
9. `9. Dynamic Semantics Specification.md`
|
||||
10. `10. Memory and Lifetime Specification.md`
|
||||
11. This document
|
||||
|
||||
If a lowering rule here contradicts a higher-precedence semantic rule, the higher-precedence rule wins.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on, at minimum:
|
||||
|
||||
- `3. Core Syntax Specification.md`
|
||||
- `4. Static Semantics Specification.md`
|
||||
- `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
- `6. VM-owned vs Host-backed.md`
|
||||
- `6.1. Intrinsics and Builtin Types Specification.md`
|
||||
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `9. Dynamic Semantics Specification.md`
|
||||
- `10. Memory and Lifetime Specification.md`
|
||||
|
||||
This document is expected to be closed using a future backend agenda sequence tracked in `docs/agendas/`.
|
||||
|
||||
## 5. Already-Settled Inputs
|
||||
|
||||
The following inputs are already fixed elsewhere and must not be contradicted here:
|
||||
|
||||
- The compiler consumes reserved `Host` metadata while resolving host-backed SDK members.
|
||||
- The compiler consumes reserved `BuiltinType`, `BuiltinConst`, `IntrinsicCall`, and `Slot` metadata while resolving builtin shells.
|
||||
- The compiler emits canonical host-binding declarations into the PBX `SYSC` table.
|
||||
- The compiler emits host-backed callsites in pre-load form as `HOSTCALL <sysc_index>`.
|
||||
- `SYSC` entries are deduplicated by canonical identity and ordered by first occurrence.
|
||||
- The loader, not the compiler, resolves canonical host bindings to final numeric syscall identifiers.
|
||||
- Builtin projection lowering remains VM-owned and does not emit host-binding metadata.
|
||||
- Builtin constants lower through VM-owned materialization rather than through ordinary compile-time constant evaluation.
|
||||
- Builtin intrinsic member calls lower through a VM-owned intrinsic path rather than through `SYSC`, `HOSTCALL`, or `SYSCALL`.
|
||||
- Stdlib interface modules are compile-time-only and do not emit executable bytecode by themselves.
|
||||
|
||||
## 6. Initial Section Targets
|
||||
|
||||
At minimum, the completed document should contain normative sections for:
|
||||
|
||||
1. lowering preconditions,
|
||||
2. semantic obligations preserved by IR,
|
||||
3. lowering of expressions and control flow,
|
||||
4. lowering of callable categories,
|
||||
5. lowering of `optional` and `result<E>` constructs,
|
||||
6. lowering of callbacks, services, and contracts,
|
||||
7. lowering of builtin projections, builtin constants, and builtin intrinsic calls,
|
||||
8. host-binding emission,
|
||||
9. artifact invariants required before verifier/loader stages.
|
||||
|
||||
## 7. A Ver
|
||||
|
||||
The following items remain to be closed before this document can be considered complete.
|
||||
|
||||
### 7.1 Depends on `9. Dynamic Semantics Specification.md`
|
||||
|
||||
- Which evaluation-order guarantees must be preserved explicitly in lowering.
|
||||
- Which traps, abrupt completions, and propagation paths require dedicated lowered forms.
|
||||
- Whether callback formation and contract dispatch need dedicated runtime artifacts or only implementation-defined IR shapes.
|
||||
|
||||
### 7.2 Depends on `10. Memory and Lifetime Specification.md`
|
||||
|
||||
- Which lowered operations allocate, alias, retain, or cross the host-memory boundary.
|
||||
- Which runtime storage/identity facts IR must preserve explicitly versus infer later.
|
||||
|
||||
### 7.3 Depends on the future backend agenda sequence tracked in `docs/agendas/`
|
||||
|
||||
- Whether one canonical IR is normative or only the preserved semantic obligations are normative.
|
||||
- The exact mapping from bound PBS constructs to PBX/bytecode-facing artifacts beyond already-settled host-binding and intrinsic behavior.
|
||||
- Lowering strategy for services, contracts, callbacks, tuples, and result propagation.
|
||||
- Whether declaration-based intrinsic preload forms such as `INTRCALL` are part of v1 lowering or whether compilers should emit final `INTRINSIC <id>` directly for a selected VM line.
|
||||
- Which artifact invariants belong here versus a future dedicated PBX/bytecode mapping document.
|
||||
|
||||
## 8. Non-Goals
|
||||
|
||||
- Freezing one optimizer design.
|
||||
- Requiring one compiler implementation architecture.
|
||||
- Repeating the full bytecode ISA specification.
|
||||
- Defining loader-side patching internals already owned elsewhere.
|
||||
|
||||
## 9. Exit Criteria
|
||||
|
||||
This document is ready to move beyond skeleton status only when:
|
||||
|
||||
1. every semantically distinct core construct has an explicit lowering story,
|
||||
2. the boundary between source semantics, compiler IR, and emitted artifacts is clear,
|
||||
3. host-binding emission is fully aligned with the Host ABI spec,
|
||||
4. builtin and intrinsic lowering is fully aligned with the VM-owned builtin spec,
|
||||
5. the document no longer relies on unresolved backend `A Ver` items for ordinary v1 lowering behavior.
|
||||
138
docs/specs/pbs/13. Conformance Test Specification.md
Normal file
138
docs/specs/pbs/13. Conformance Test Specification.md
Normal file
@ -0,0 +1,138 @@
|
||||
# PBS Conformance Test Specification
|
||||
|
||||
Status: Draft v0 (Skeleton)
|
||||
Applies to: conformance obligations, test categories, and acceptance criteria for PBS implementations
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document will define the PBS conformance testing contract.
|
||||
|
||||
Its purpose is to make the specification operational by defining:
|
||||
|
||||
- what an implementation must demonstrate to claim conformance,
|
||||
- which parts of the spec require positive versus negative tests,
|
||||
- how deterministic diagnostics and runtime behavior are validated,
|
||||
- how compatibility and version claims are checked.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document is intended to define:
|
||||
|
||||
- conformance levels or profiles, if any,
|
||||
- required test categories,
|
||||
- expectations for syntax, static, manifest, lowering, loader, and runtime tests,
|
||||
- diagnostic-conformance expectations,
|
||||
- artifact and runtime fixtures needed for host-binding and capability-gating tests,
|
||||
- compatibility-matrix conformance hooks.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- one specific test runner implementation,
|
||||
- CI policy for one repository,
|
||||
- benchmark or performance certification,
|
||||
- product release governance process.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. `1. Language Charter.md`
|
||||
2. `2. Governance and Versioning.md`
|
||||
3. `3. Core Syntax Specification.md`
|
||||
4. `4. Static Semantics Specification.md`
|
||||
5. `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
6. `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
7. `7. Cartridge Manifest and Runtime Capabilities Specification.md`
|
||||
8. `9. Dynamic Semantics Specification.md`
|
||||
9. `10. Memory and Lifetime Specification.md`
|
||||
10. `11. Diagnostics Specification.md`
|
||||
11. `12. IR and Lowering Specification.md`
|
||||
12. This document
|
||||
|
||||
This document must not weaken a normative requirement imposed by higher-precedence specs.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on, at minimum, the full active PBS v1 spec set.
|
||||
|
||||
In the current phase, it should be drafted against:
|
||||
|
||||
- `3. Core Syntax Specification.md`
|
||||
- `4. Static Semantics Specification.md`
|
||||
- `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `7. Cartridge Manifest and Runtime Capabilities Specification.md`
|
||||
|
||||
It will require closure of:
|
||||
|
||||
- `9. Dynamic Semantics Specification.md`
|
||||
- `10. Memory and Lifetime Specification.md`
|
||||
- `11. Diagnostics Specification.md`
|
||||
- `12. IR and Lowering Specification.md`
|
||||
|
||||
## 5. Already-Settled Inputs
|
||||
|
||||
The following inputs are already fixed elsewhere and must not be contradicted here:
|
||||
|
||||
- The parser must behave deterministically.
|
||||
- Syntax and static semantics already enumerate minimum required rejection cases.
|
||||
- Import/manifest failures are required to be deterministic.
|
||||
- Loader failures for malformed or unauthorized host usage are required to be deterministic.
|
||||
- Governance requires conformance updates before release.
|
||||
- Compatibility claims must be reflected in a published compatibility matrix.
|
||||
|
||||
## 6. Initial Section Targets
|
||||
|
||||
At minimum, the completed document should contain normative sections for:
|
||||
|
||||
1. scope of conformance,
|
||||
2. implementation claims and version domains,
|
||||
3. required positive parsing/binding/type-checking tests,
|
||||
4. required negative syntax/static tests,
|
||||
5. manifest/import-resolution tests,
|
||||
6. dynamic-semantics runtime tests,
|
||||
7. host-binding and capability-gating tests,
|
||||
8. diagnostics-conformance tests,
|
||||
9. compatibility and regression test expectations.
|
||||
|
||||
## 7. A Ver
|
||||
|
||||
The following items remain to be closed before this document can be considered complete.
|
||||
|
||||
### 7.1 Depends on `9. Dynamic Semantics Specification.md` and `10. Memory and Lifetime Specification.md`
|
||||
|
||||
- Exact runtime-oracle model for observable evaluation order, traps, and effect behavior.
|
||||
- Which memory/aliasing facts must be tested directly versus only through diagnostics/tooling hooks.
|
||||
|
||||
### 7.2 Depends on `11. Diagnostics Specification.md`
|
||||
|
||||
- Whether conformance checks diagnostic codes, spans, categories, wording classes, or only rejection phase and location.
|
||||
- Which warnings or cost diagnostics are in conformance scope.
|
||||
|
||||
### 7.3 Depends on `12. IR and Lowering Specification.md`
|
||||
|
||||
- Whether artifact-level conformance is required in addition to source-level conformance.
|
||||
- Which emitted host-binding and lowering invariants require golden tests.
|
||||
|
||||
### 7.4 Still to decide inside this document
|
||||
|
||||
- Whether PBS v1 has one conformance level or staged claims such as frontend-only versus full toolchain.
|
||||
- Fixture strategy for stdlib environments, host registries, and capability-grant scenarios.
|
||||
- How compatibility-matrix claims are validated across language/profile/stdlib domains.
|
||||
|
||||
## 8. Non-Goals
|
||||
|
||||
- Replacing the normative specs with tests as the primary authority.
|
||||
- Forcing one repository layout or one test harness.
|
||||
- Treating performance benchmarking as language conformance.
|
||||
- Inventing new language rules through test-only precedent.
|
||||
|
||||
## 9. Exit Criteria
|
||||
|
||||
This document is ready to move beyond skeleton status only when:
|
||||
|
||||
1. every active PBS v1 spec has a corresponding conformance surface,
|
||||
2. positive and negative obligations are clearly separated,
|
||||
3. diagnostics and runtime behavior have explicit oracle expectations,
|
||||
4. compatibility and version claims can be tested rather than asserted informally,
|
||||
5. the document no longer relies on unresolved `A Ver` items for the intended conformance level.
|
||||
@ -0,0 +1,169 @@
|
||||
# PBS Name Resolution and Module Linking Specification
|
||||
|
||||
Status: Draft v0 (Skeleton)
|
||||
Applies to: scope formation, name lookup, imports, exports, barrel visibility, cross-module resolution, and semantic linking of PBS programs
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document will define the normative name-resolution and semantic-linking model for PBS.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document is intended to define:
|
||||
|
||||
- scope formation and lookup order,
|
||||
- namespace separation and collision rules,
|
||||
- import and export resolution,
|
||||
- barrel-mediated visibility and module linking,
|
||||
- cross-file and cross-module symbol resolution,
|
||||
- resolution of reserved stdlib shells for host-backed and VM-owned surfaces,
|
||||
- linkage-time rejection conditions before lowering.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- runtime execution behavior,
|
||||
- optimizer or backend internals,
|
||||
- full PBX binary linking.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. `3. Core Syntax Specification.md`
|
||||
2. `4. Static Semantics Specification.md`
|
||||
3. `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
4. `6. VM-owned vs Host-backed.md`
|
||||
5. `6.1. Intrinsics and Builtin Types Specification.md`
|
||||
6. `18. Standard Library Surface Specification.md`
|
||||
7. This document
|
||||
|
||||
If a rule here conflicts with higher-precedence specs, it is invalid.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on, at minimum:
|
||||
|
||||
- `3. Core Syntax Specification.md`
|
||||
- `4. Static Semantics Specification.md`
|
||||
- `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
- `6. VM-owned vs Host-backed.md`
|
||||
- `6.1. Intrinsics and Builtin Types Specification.md`
|
||||
- `8. Stdlib Environment Packaging and Loading Specification.md`
|
||||
- `18. Standard Library Surface Specification.md`
|
||||
|
||||
## 5. Already-Settled Inputs
|
||||
|
||||
The following inputs are already fixed elsewhere and must not be contradicted here:
|
||||
|
||||
- PBS has distinct type, value, callable, and host-owner namespaces.
|
||||
- `mod.barrel` is the single source of module visibility.
|
||||
- Imports target modules, not files.
|
||||
- Reserved stdlib project spaces are resolved only from the selected stdlib environment.
|
||||
- Only `pub` symbols may be imported from another module.
|
||||
- Reserved stdlib/interface modules may expose compile-time-only shells for both host-backed and VM-owned surfaces.
|
||||
- Source-visible builtin names are resolved through imported builtin shell declarations rather than by hardcoded source spelling alone.
|
||||
- Canonical builtin identity and canonical intrinsic identity are governed by builtin metadata rather than by the imported PBS-visible declaration name alone.
|
||||
|
||||
## 6. Initial Section Targets
|
||||
|
||||
At minimum, the completed document should contain normative sections for:
|
||||
|
||||
1. scope construction,
|
||||
2. lookup order by namespace,
|
||||
3. import and alias resolution,
|
||||
4. barrel export matching and linking,
|
||||
5. reserved stdlib shell resolution for builtin and host-backed surfaces,
|
||||
6. duplicate and shadowing rules,
|
||||
7. cross-module resolution failures.
|
||||
|
||||
## 7. A Ver
|
||||
|
||||
The following items remain to be closed in future agenda discussion.
|
||||
|
||||
- Exact lookup order across local bindings, top-level declarations, imports, and reserved intrinsic surfaces.
|
||||
- Whether shadowing rules differ by namespace or declaration kind.
|
||||
- Whether semantic linking is fully part of static semantics or split into a distinct phase contract.
|
||||
- Exact rejection model for ambiguous cross-module overload visibility and barrel-linked callable sets.
|
||||
- Whether stdlib/interface-module linking imposes extra restrictions beyond ordinary modules.
|
||||
- Whether builtin shell declarations may be synthesized by the toolchain in addition to being provided by stdlib modules.
|
||||
|
||||
## 8. Non-Goals
|
||||
|
||||
- Reopening the already-settled import surface syntax.
|
||||
- Defining runtime loader behavior.
|
||||
- Freezing one compiler symbol-table implementation.
|
||||
|
||||
## 9. Exit Criteria
|
||||
|
||||
This document is ready to move beyond skeleton status only when:
|
||||
|
||||
1. name lookup is deterministic across all relevant scopes,
|
||||
2. barrel and module linking behavior is explicit,
|
||||
3. reserved stdlib shell resolution is explicit for host-backed and VM-owned surfaces,
|
||||
4. cross-module ambiguity and failure cases are normatively defined,
|
||||
5. the document no longer relies on unresolved `A Ver` items for ordinary v1 resolution behavior.
|
||||
|
||||
## 10. Reserved Stdlib Shell Resolution
|
||||
|
||||
Reserved stdlib modules may expose compile-time-only declarations that do not
|
||||
behave like ordinary user-authored implementation bodies.
|
||||
|
||||
Rules:
|
||||
|
||||
- `declare host` surfaces exported from reserved stdlib modules resolve in the host-owner namespace.
|
||||
- `declare builtin type` surfaces exported from reserved stdlib modules resolve in the type namespace.
|
||||
- builtin constants exported from reserved stdlib modules resolve in the value namespace.
|
||||
- builtin intrinsic methods are not imported as free functions; they are resolved through the imported builtin type declaration of the receiver type.
|
||||
- canonical host identity is not derived from the imported host owner spelling,
|
||||
- and canonical builtin/intrinsic identity is not derived solely from the imported builtin type spelling.
|
||||
|
||||
Example:
|
||||
|
||||
- importing `Vec2` from `@core:math` may introduce the PBS-visible type name `Vec2`,
|
||||
- while the declaration's metadata may still lower that type to canonical builtin identity `("vec2", 1)`.
|
||||
|
||||
## 11. Import and Barrel Rules for Builtin Shells
|
||||
|
||||
Builtin shells follow ordinary module visibility rules at the source level and
|
||||
special metadata rules at lowering time.
|
||||
|
||||
Rules:
|
||||
|
||||
- a builtin type, builtin constant, or host owner may be imported only if it is exported through the target module's `mod.barrel`,
|
||||
- aliasing an imported builtin type changes only the source-visible local name, not the canonical builtin identity declared by metadata,
|
||||
- aliasing an imported builtin constant changes only the local binding name, not the canonical builtin constant identity declared by metadata,
|
||||
- aliasing an imported host owner changes only the source-visible local name, not the canonical host identity declared by `Host(...)`,
|
||||
- barrel matching for builtin declarations is declaration-based rather than executable-body based,
|
||||
- and resolution must complete before lowering begins.
|
||||
|
||||
## 12. Lookup Order for Builtin and Intrinsic Surfaces
|
||||
|
||||
Lookup remains namespace-based.
|
||||
|
||||
Rules:
|
||||
|
||||
- type-position lookup considers visible builtin type declarations alongside other visible type declarations,
|
||||
- value-position lookup considers visible builtin constants alongside other visible values,
|
||||
- callable lookup does not treat builtin intrinsic members as top-level callable declarations,
|
||||
- member lookup on a builtin-typed receiver considers builtin projection fields first as field-like surfaces of that builtin declaration,
|
||||
- method lookup on a builtin-typed receiver considers builtin intrinsic member signatures declared by that builtin shell,
|
||||
- and host-owner lookup remains separate from builtin type lookup.
|
||||
|
||||
This preserves the distinction between:
|
||||
|
||||
- imported builtin type shells,
|
||||
- imported host owners,
|
||||
- and compiler-recognized intrinsic method surfaces on existing core forms such as `optional` and enums.
|
||||
|
||||
## 13. Deterministic Resolution Failures
|
||||
|
||||
At minimum, a conforming implementation must reject:
|
||||
|
||||
1. import of a non-exported builtin type shell,
|
||||
2. import of a non-exported builtin constant shell,
|
||||
3. import of a non-exported host owner shell,
|
||||
4. ambiguous cross-module visibility of builtin declarations after barrel resolution,
|
||||
5. duplicate visible builtin type declarations that claim the same canonical builtin identity in one resolved environment,
|
||||
6. duplicate visible builtin constants that claim the same canonical builtin constant identity in one resolved environment,
|
||||
7. member lookup on a builtin receiver where the imported builtin shell does not declare the requested field or intrinsic member,
|
||||
8. any resolution path that attempts to derive host or builtin canonical identity from alias spelling alone.
|
||||
92
docs/specs/pbs/15. Bytecode and PBX Mapping Specification.md
Normal file
92
docs/specs/pbs/15. Bytecode and PBX Mapping Specification.md
Normal file
@ -0,0 +1,92 @@
|
||||
# PBS Bytecode and PBX Mapping Specification
|
||||
|
||||
Status: Draft v0 (Skeleton)
|
||||
Applies to: mapping from lowered PBS programs into PBX sections, bytecode-facing artifacts, and related source-to-artifact invariants
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document will define the normative mapping between lowered PBS semantics and emitted PBX/bytecode-facing artifacts.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document is intended to define:
|
||||
|
||||
- artifact-level obligations after lowering,
|
||||
- mapping of semantic constructs into PBX-visible structures,
|
||||
- source-to-artifact invariants required by verifier and loader stages,
|
||||
- interaction points with host-binding metadata such as `SYSC`,
|
||||
- interaction points with VM-owned builtin and intrinsic metadata.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- the full bytecode ISA,
|
||||
- UI/tooling presentation,
|
||||
- one compiler's internal IR representation.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
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`)
|
||||
3. `6.1. Intrinsics and Builtin Types Specification.md`
|
||||
4. `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
5. `12. IR and Lowering Specification.md`
|
||||
6. This document
|
||||
|
||||
If a rule here conflicts with higher-precedence authorities, it is invalid.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on, at minimum:
|
||||
|
||||
- `6.1. Intrinsics and Builtin Types Specification.md`
|
||||
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `12. IR and Lowering Specification.md`
|
||||
|
||||
## 5. Already-Settled Inputs
|
||||
|
||||
The following inputs are already fixed elsewhere and must not be contradicted here:
|
||||
|
||||
- The compiler emits host-binding declarations into PBX `SYSC`.
|
||||
- Host-backed callsites are emitted in pre-load form as `HOSTCALL <sysc_index>`.
|
||||
- `SYSC` entries are deduplicated by canonical identity and ordered by first occurrence.
|
||||
- The loader resolves host bindings and rewrites `HOSTCALL` into `SYSCALL`.
|
||||
- VM-owned builtin projections, builtin constants, and intrinsic callsites do not emit host-binding metadata.
|
||||
- VM-owned intrinsic artifacts are distinct from `SYSC`, `HOSTCALL`, and `SYSCALL`.
|
||||
|
||||
## 6. Initial Section Targets
|
||||
|
||||
At minimum, the completed document should contain normative sections for:
|
||||
|
||||
1. artifact mapping goals,
|
||||
2. section-level invariants,
|
||||
3. callsite and control-flow mapping invariants,
|
||||
4. metadata mapping obligations,
|
||||
5. intrinsic and builtin artifact obligations,
|
||||
6. source-attribution hooks for diagnostics/conformance.
|
||||
|
||||
## 7. A Ver
|
||||
|
||||
The following items remain to be closed in future agenda discussion.
|
||||
|
||||
- Which PBX sections beyond `SYSC` are part of the PBS-facing contract.
|
||||
- Whether a distinct intrinsic declaration section is part of the PBS-facing contract in v1.
|
||||
- Which source-level constructs require dedicated artifact patterns versus implementation freedom.
|
||||
- How much of artifact ordering, numbering, and layout is normative at PBS level versus owned purely by PBX authority.
|
||||
- Whether compilers should emit final `INTRINSIC <id>` directly for a selected VM line or may emit a declaration-based preload form such as `INTRCALL <decl_index>`.
|
||||
- Whether a separate debug/source-map surface is part of v1.
|
||||
|
||||
## 8. Non-Goals
|
||||
|
||||
- Repeating the full PBX or ISA documentation.
|
||||
- Mandating one binary-emitter implementation strategy.
|
||||
- Defining loader patching internals already owned elsewhere.
|
||||
|
||||
## 9. Exit Criteria
|
||||
|
||||
This document is ready to move beyond skeleton status only when:
|
||||
|
||||
1. the PBS-to-artifact boundary is explicit,
|
||||
2. artifact-level invariants needed by verifier and loader are normative,
|
||||
3. the document no longer relies on unresolved `A Ver` items for ordinary v1 artifact mapping behavior.
|
||||
@ -0,0 +1,91 @@
|
||||
# PBS Runtime Execution and Initialization Specification
|
||||
|
||||
Status: Draft v0 (Skeleton)
|
||||
Applies to: runtime startup, entry behavior, module/service initialization, and execution lifecycle of PBS programs after successful load
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document will define the runtime execution and initialization contract for PBS programs.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document is intended to define:
|
||||
|
||||
- entry and startup behavior,
|
||||
- initialization ordering relevant to PBS-visible semantics,
|
||||
- lifecycle of module-owned and service-owned runtime state,
|
||||
- execution boundaries before, during, and after frame-driven program operation,
|
||||
- runtime assumptions that are neither purely dynamic semantics nor purely loader behavior.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- loader-side host resolution,
|
||||
- full packaging format,
|
||||
- scheduler models outside v1 execution assumptions.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
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. `1. Language Charter.md`
|
||||
3. `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
4. `9. Dynamic Semantics Specification.md`
|
||||
5. `10. Memory and Lifetime Specification.md`
|
||||
6. This document
|
||||
|
||||
If a rule here conflicts with higher-precedence authorities, it is invalid.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on, at minimum:
|
||||
|
||||
- `1. Language Charter.md`
|
||||
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `7. Cartridge Manifest and Runtime Capabilities Specification.md`
|
||||
- `9. Dynamic Semantics Specification.md`
|
||||
- `10. Memory and Lifetime Specification.md`
|
||||
|
||||
## 5. Already-Settled Inputs
|
||||
|
||||
The following inputs are already fixed elsewhere and must not be contradicted here:
|
||||
|
||||
- `FRAME_SYNC`-based execution semantics are preserved.
|
||||
- Loader-side host binding resolution and capability gating happen before program execution begins.
|
||||
- Service values are canonical module-owned singleton values.
|
||||
- Top-level executable statements are forbidden in PBS source modules.
|
||||
|
||||
## 6. Initial Section Targets
|
||||
|
||||
At minimum, the completed document should contain normative sections for:
|
||||
|
||||
1. execution entry assumptions,
|
||||
2. initialization ordering,
|
||||
3. service singleton runtime lifecycle,
|
||||
4. runtime frame and step boundaries,
|
||||
5. failure and non-start conditions.
|
||||
|
||||
## 7. A Ver
|
||||
|
||||
The following items remain to be closed in future agenda discussion.
|
||||
|
||||
- Exact runtime entry contract between loaded artifact and PBS-visible program behavior.
|
||||
- Whether module initialization exists as a distinct semantic phase in v1 beyond load success.
|
||||
- When service singleton state becomes initialized and observable.
|
||||
- Which runtime lifecycle boundaries are observable to user code versus VM-internal.
|
||||
- Whether shutdown/finalization behavior has any PBS-visible contract in v1.
|
||||
|
||||
## 8. Non-Goals
|
||||
|
||||
- Defining OS/process lifecycle outside Prometeu runtime authority.
|
||||
- Reopening the ban on top-level executable statements.
|
||||
- Designing a future async runtime.
|
||||
|
||||
## 9. Exit Criteria
|
||||
|
||||
This document is ready to move beyond skeleton status only when:
|
||||
|
||||
1. runtime startup and initialization order are normatively described,
|
||||
2. service and module runtime lifecycle assumptions are explicit,
|
||||
3. execution lifecycle boundaries are aligned with dynamic semantics and runtime authority,
|
||||
4. the document no longer relies on unresolved `A Ver` items for ordinary v1 runtime startup behavior.
|
||||
90
docs/specs/pbs/17. Compatibility and Evolution Policy.md
Normal file
90
docs/specs/pbs/17. Compatibility and Evolution Policy.md
Normal file
@ -0,0 +1,90 @@
|
||||
# PBS Compatibility and Evolution Policy
|
||||
|
||||
Status: Draft v0 (Skeleton)
|
||||
Applies to: compatibility commitments, migration boundaries, deprecation discipline, and evolution constraints across PBS language and related domains
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document will define the normative compatibility and evolution policy for PBS.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document is intended to define:
|
||||
|
||||
- compatibility promises across language, profile, stdlib, and artifact domains,
|
||||
- migration boundaries for additive versus incompatible changes,
|
||||
- deprecation and removal policy details,
|
||||
- behavioral versus binary compatibility expectations,
|
||||
- obligations when publishing changes that affect older cartridges or projects.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- one repository's release workflow,
|
||||
- one implementation's branching strategy,
|
||||
- detailed changelog formatting.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. `1. Language Charter.md`
|
||||
2. `2. Governance and Versioning.md`
|
||||
3. Runtime and bytecode authority where applicable
|
||||
4. This document
|
||||
|
||||
If a rule here conflicts with higher-precedence authorities, it is invalid.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on, at minimum:
|
||||
|
||||
- `1. Language Charter.md`
|
||||
- `2. Governance and Versioning.md`
|
||||
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `7. Cartridge Manifest and Runtime Capabilities Specification.md`
|
||||
|
||||
## 5. Already-Settled Inputs
|
||||
|
||||
The following inputs are already fixed elsewhere and must not be contradicted here:
|
||||
|
||||
- Additive-first evolution is preferred for minor releases.
|
||||
- Incompatible changes belong only in major lines with migration guidance.
|
||||
- Canonical host primitive versioning uses `(module, name, version)`.
|
||||
- Toolchains must reject unsupported targets deterministically.
|
||||
- Older supported cartridges are expected to keep running across updates.
|
||||
|
||||
## 6. Initial Section Targets
|
||||
|
||||
At minimum, the completed document should contain normative sections for:
|
||||
|
||||
1. compatibility domains,
|
||||
2. behavioral versus binary compatibility,
|
||||
3. deprecation windows,
|
||||
4. migration obligations,
|
||||
5. compatibility-matrix expectations,
|
||||
6. artifact and runtime compatibility boundaries.
|
||||
|
||||
## 7. A Ver
|
||||
|
||||
The following items remain to be closed in future agenda discussion.
|
||||
|
||||
- Exact compatibility window by domain.
|
||||
- Whether PBX/binary compatibility has an independent policy track from source-level compatibility.
|
||||
- How stdlib-line compatibility interacts with dependency projects over time.
|
||||
- Which changes require migration tooling versus documentation-only migration notes.
|
||||
- Whether frontend-only phased implementation claims need distinct compatibility labels.
|
||||
|
||||
## 8. Non-Goals
|
||||
|
||||
- Replacing governance with ad hoc decisions.
|
||||
- Defining one product release calendar.
|
||||
- Freezing every editorial clarification as a compatibility event.
|
||||
|
||||
## 9. Exit Criteria
|
||||
|
||||
This document is ready to move beyond skeleton status only when:
|
||||
|
||||
1. compatibility commitments are explicit by domain,
|
||||
2. deprecation and migration duties are normatively described,
|
||||
3. source, stdlib, artifact, and runtime compatibility boundaries are separated clearly,
|
||||
4. the document no longer relies on unresolved `A Ver` items for ordinary v1 compatibility claims.
|
||||
185
docs/specs/pbs/18. Standard Library Surface Specification.md
Normal file
185
docs/specs/pbs/18. Standard Library Surface Specification.md
Normal file
@ -0,0 +1,185 @@
|
||||
# PBS Standard Library Surface Specification
|
||||
|
||||
Status: Draft v0 (Skeleton)
|
||||
Applies to: normative stdlib-facing API surface, reserved stdlib project spaces, and versioned standard-library contracts exposed to PBS programs
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document will define the normative user-facing standard-library surface for PBS.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document is intended to define:
|
||||
|
||||
- what counts as part of the PBS stdlib contract,
|
||||
- how stdlib modules are grouped and versioned,
|
||||
- which APIs are normative versus implementation-private,
|
||||
- how VM-owned builtin shells are exposed to user code,
|
||||
- how reserved stdlib project spaces expose user-facing surfaces over host-backed capabilities.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- one physical packaging layout,
|
||||
- registry/publication mechanics,
|
||||
- host loader behavior,
|
||||
- implementation-private helper modules.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
2. `8. Stdlib Environment Packaging and Loading Specification.md`
|
||||
3. `6. VM-owned vs Host-backed.md`
|
||||
4. `6.1. Intrinsics and Builtin Types Specification.md`
|
||||
5. `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
6. This document
|
||||
|
||||
If a rule here conflicts with higher-precedence specs, it is invalid.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on, at minimum:
|
||||
|
||||
- `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
- `6. VM-owned vs Host-backed.md`
|
||||
- `6.1. Intrinsics and Builtin Types Specification.md`
|
||||
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `8. Stdlib Environment Packaging and Loading Specification.md`
|
||||
|
||||
## 5. Already-Settled Inputs
|
||||
|
||||
The following inputs are already fixed elsewhere and must not be contradicted here:
|
||||
|
||||
- Reserved stdlib project spaces include `@sdk:*` and `@core:*`.
|
||||
- Stdlib interface modules are compile-time-only and loaded as PBS-like modules.
|
||||
- User code must import stdlib modules explicitly.
|
||||
- Canonical host identity comes from reserved host-binding metadata, not from source owner spelling.
|
||||
- VM-owned builtin type, builtin constant, and intrinsic surfaces may be exposed through reserved stdlib shells without transferring semantic ownership away from the VM.
|
||||
|
||||
## 6. Initial Section Targets
|
||||
|
||||
At minimum, the completed document should contain normative sections for:
|
||||
|
||||
1. stdlib contract boundaries,
|
||||
2. reserved stdlib project spaces and module families,
|
||||
3. normative versus non-normative API surfaces,
|
||||
4. VM-owned builtin shells exposed to user code,
|
||||
5. host-backed SDK surfaces exposed to user code,
|
||||
6. versioning and deprecation expectations for stdlib APIs.
|
||||
|
||||
## 7. A Ver
|
||||
|
||||
The following items remain to be closed in future agenda discussion.
|
||||
|
||||
- Which stdlib modules are mandatory in each active stdlib line.
|
||||
- Which APIs are part of the normative core teaching surface versus optional library growth.
|
||||
- Whether `@core:*` is specified as language-adjacent utility surface or as ordinary stdlib contract.
|
||||
- How stdlib API evolution is documented and conformance-tested.
|
||||
- Whether some interface modules remain toolchain-private and outside user-facing stdlib surface.
|
||||
- Whether builtin shells may appear in `@sdk:*` as well as `@core:*`, or whether `@sdk:*` should remain host-facing only by policy.
|
||||
|
||||
## 8. Non-Goals
|
||||
|
||||
- Replacing the resolution/packaging specs.
|
||||
- Defining all future libraries in one pass.
|
||||
- Hardcoding one distribution format.
|
||||
|
||||
## 9. Exit Criteria
|
||||
|
||||
This document is ready to move beyond skeleton status only when:
|
||||
|
||||
1. the normative user-facing stdlib surface is explicitly bounded,
|
||||
2. reserved project-space API responsibilities are clear,
|
||||
3. VM-owned and host-backed stdlib surfaces are explicitly separated,
|
||||
4. stdlib versioning and deprecation expectations are aligned with compatibility policy,
|
||||
5. the document no longer relies on unresolved `A Ver` items for ordinary v1 stdlib contract claims.
|
||||
|
||||
## 10. Reserved Project-Space Responsibilities
|
||||
|
||||
The current stdlib direction distinguishes two user-facing reserved spaces.
|
||||
|
||||
### 10.1 `@core:*`
|
||||
|
||||
`@core:*` is the preferred surface for VM-owned declarations that belong to the
|
||||
language-adjacent semantic platform.
|
||||
|
||||
Examples:
|
||||
|
||||
- builtin type shells,
|
||||
- builtin constants,
|
||||
- and other VM-owned helper declarations that are not host capability surfaces.
|
||||
|
||||
### 10.2 `@sdk:*`
|
||||
|
||||
`@sdk:*` is the preferred surface for host-backed capability-facing APIs.
|
||||
|
||||
Examples:
|
||||
|
||||
- `declare host` surfaces,
|
||||
- capability-facing wrappers over host services,
|
||||
- and domain SDK modules whose execution meaning ultimately depends on host-backed operations.
|
||||
|
||||
Rules:
|
||||
|
||||
- source packaging location is part of the stdlib contract surface,
|
||||
- but ownership remains governed by the VM-owned vs host-backed classification,
|
||||
- and placing a builtin shell in stdlib does not make it host-backed.
|
||||
|
||||
## 11. Builtin Shell Surfaces
|
||||
|
||||
Reserved stdlib modules may expose builtin declarations as compile-time-only
|
||||
shells.
|
||||
|
||||
Rules:
|
||||
|
||||
- stdlib builtin shells may expose `declare builtin type` declarations,
|
||||
- stdlib builtin shells may expose reserved `declare const` declarations carrying `BuiltinConst(...)`,
|
||||
- stdlib builtin shells may expose builtin methods carrying `IntrinsicCall(...)`,
|
||||
- these shells exist for import, name resolution, type checking, and lowering,
|
||||
- and these shells do not provide executable PBS bodies for builtin behavior.
|
||||
|
||||
Stdlib is therefore the delivery surface, not the semantic owner.
|
||||
|
||||
## 12. Host-backed SDK Surfaces
|
||||
|
||||
Reserved stdlib modules may expose host-backed declarations as compile-time-only
|
||||
shells.
|
||||
|
||||
Rules:
|
||||
|
||||
- host-backed stdlib surfaces use `declare host`,
|
||||
- host-backed method signatures carry `Host(...)`,
|
||||
- user code may import those host owners through ordinary stdlib module imports,
|
||||
- and lowering continues through canonical host identity, `SYSC`, `HOSTCALL`, loader resolution, and final `SYSCALL`.
|
||||
|
||||
## 13. Stdlib Contract Expectations for Builtin MVP
|
||||
|
||||
For the current builtin MVP, stdlib should be able to expose at least:
|
||||
|
||||
1. a builtin type shell for `Color`,
|
||||
2. a builtin type shell for `Vec2`,
|
||||
3. a builtin type shell for `Pixel`,
|
||||
4. a builtin constant shell for `vec2.zero`,
|
||||
5. and any associated documentation-level or teaching-level module organization needed to make those surfaces discoverable.
|
||||
|
||||
Illustrative example:
|
||||
|
||||
```pbs
|
||||
import { Vec2, ZERO } from @core:math;
|
||||
```
|
||||
|
||||
The imported names are source-visible conveniences.
|
||||
Their canonical runtime-facing identities still come from builtin metadata such
|
||||
as `BuiltinType(name="vec2", version=1)` and
|
||||
`BuiltinConst(target="vec2", name="zero", version=1)`.
|
||||
|
||||
## 14. Deterministic Stdlib Surface Failures
|
||||
|
||||
At minimum, a conforming implementation must reject:
|
||||
|
||||
1. a stdlib builtin shell that attempts to use host-binding metadata for VM-owned intrinsic behavior,
|
||||
2. a stdlib host shell that attempts to use builtin metadata in place of host-binding metadata,
|
||||
3. a user-facing stdlib module that exports executable PBS bodies for builtin semantics,
|
||||
4. a stdlib line that exposes conflicting canonical builtin identities through the same resolved environment,
|
||||
5. a stdlib line that exposes conflicting canonical host identities through the same resolved environment.
|
||||
@ -0,0 +1,88 @@
|
||||
# PBS Verification and Safety Checks Specification
|
||||
|
||||
Status: Draft v0 (Skeleton)
|
||||
Applies to: verifier-facing safety obligations, artifact validation boundaries, and the division of safety checks across compiler, loader, verifier, and runtime
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document will define the verification and safety-check model relevant to PBS-produced artifacts.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document is intended to define:
|
||||
|
||||
- which safety obligations are enforced before runtime execution,
|
||||
- the division of responsibility across compiler, loader, verifier, and runtime,
|
||||
- verifier-facing assumptions about already-lowered artifacts,
|
||||
- safety properties that must hold for conforming PBS-produced images.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- full runtime trap semantics,
|
||||
- source-language typing rules already owned elsewhere,
|
||||
- one verifier implementation architecture.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
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`)
|
||||
3. `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
4. `12. IR and Lowering Specification.md`
|
||||
5. `15. Bytecode and PBX Mapping Specification.md`
|
||||
6. This document
|
||||
|
||||
If a rule here conflicts with higher-precedence authorities, it is invalid.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on, at minimum:
|
||||
|
||||
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `12. IR and Lowering Specification.md`
|
||||
- `15. Bytecode and PBX Mapping Specification.md`
|
||||
|
||||
## 5. Already-Settled Inputs
|
||||
|
||||
The following inputs are already fixed elsewhere and must not be contradicted here:
|
||||
|
||||
- Loader-side ABI validation is mandatory.
|
||||
- Capability gating is mandatory during load.
|
||||
- The verifier runs after loader patching on the final numeric executable image.
|
||||
- Loader and verifier validate different layers of the contract.
|
||||
|
||||
## 6. Initial Section Targets
|
||||
|
||||
At minimum, the completed document should contain normative sections for:
|
||||
|
||||
1. safety-check phase boundaries,
|
||||
2. compiler-emitted safety assumptions,
|
||||
3. loader-side safety checks,
|
||||
4. verifier-side safety checks,
|
||||
5. residual runtime safety assumptions,
|
||||
6. required deterministic rejection conditions.
|
||||
|
||||
## 7. A Ver
|
||||
|
||||
The following items remain to be closed in future agenda discussion.
|
||||
|
||||
- Exact verifier obligations beyond what is already implied by runtime/bytecode authority.
|
||||
- Which safety properties must be proven before execution versus checked defensively at runtime.
|
||||
- Whether PBS-level conformance includes explicit verifier test surfaces or only artifact validity outcomes.
|
||||
- How source-level diagnostics relate to verifier and artifact-level safety failures.
|
||||
|
||||
## 8. Non-Goals
|
||||
|
||||
- Replacing runtime or bytecode authority.
|
||||
- Duplicating the full Host ABI spec.
|
||||
- Freezing one verifier implementation algorithm.
|
||||
|
||||
## 9. Exit Criteria
|
||||
|
||||
This document is ready to move beyond skeleton status only when:
|
||||
|
||||
1. the division of safety responsibilities is explicit,
|
||||
2. verifier-facing assumptions are aligned with lowering and artifact mapping,
|
||||
3. deterministic rejection surfaces are normatively described,
|
||||
4. the document no longer relies on unresolved `A Ver` items for ordinary v1 safety claims.
|
||||
@ -248,6 +248,7 @@ Rules:
|
||||
- In v1 core, ordinary user-authored modules MUST reject attributes unless another specification explicitly permits them.
|
||||
- Reserved stdlib/toolchain interface modules MAY use attributes where explicitly allowed by syntax and semantics.
|
||||
- Attribute interpretation is compile-time only unless another specification explicitly lowers its effect into runtime-facing metadata.
|
||||
- Reserved attribute names used by builtin-type and intrinsic shells do not become ordinary value-level syntax.
|
||||
|
||||
### 6.2 Top-level declarations
|
||||
|
||||
@ -256,29 +257,34 @@ TopDecl ::= TypeDecl | CallbackDecl | FunctionDecl | ConstDecl | ImplDecl
|
||||
```
|
||||
|
||||
Top-level `let` forms and top-level executable statements are forbidden.
|
||||
`declare host` is reserved to SDK/toolchain-controlled modules; ordinary user-authored modules MUST reject it.
|
||||
`declare host` and `declare builtin type` are reserved to SDK/toolchain-controlled modules; ordinary user-authored modules MUST reject them.
|
||||
|
||||
## 7. Declarations
|
||||
|
||||
### 7.1 Type declarations
|
||||
|
||||
```ebnf
|
||||
TypeDecl ::= StructDecl | ServiceDecl | ContractDecl | HostDecl | ErrorDecl | EnumDecl
|
||||
TypeDecl ::= StructDecl | ServiceDecl | ContractDecl | HostDecl | BuiltinTypeDecl | ErrorDecl | EnumDecl
|
||||
StructDecl ::= 'declare' 'struct' Identifier '(' StructFieldList? ')' (StructMethodBody | ';')
|
||||
ServiceDecl ::= 'declare' 'service' Identifier ServiceBody
|
||||
ContractDecl ::= 'declare' 'contract' Identifier ContractBody
|
||||
HostDecl ::= 'declare' 'host' Identifier HostBody
|
||||
BuiltinTypeDecl ::= AttrList? 'declare' 'builtin' 'type' Identifier '(' BuiltinFieldList? ')' BuiltinTypeBody
|
||||
ErrorDecl ::= 'declare' 'error' Identifier ErrorBody
|
||||
EnumDecl ::= 'declare' 'enum' Identifier '(' EnumCaseDecl (',' EnumCaseDecl)* ','? ')' ';'
|
||||
StructFieldList ::= StructFieldDecl (',' StructFieldDecl)* ','?
|
||||
StructFieldDecl ::= StructFieldAccess? Identifier ':' TypeRef
|
||||
StructFieldAccess ::= 'pub' MutOpt
|
||||
BuiltinFieldList ::= BuiltinFieldDecl (',' BuiltinFieldDecl)* ','?
|
||||
BuiltinFieldDecl ::= AttrList? BuiltinFieldAccess? Identifier ':' TypeRef
|
||||
BuiltinFieldAccess ::= 'pub'
|
||||
MutOpt ::= 'mut'?
|
||||
StructMethodBody ::= '{' StructMemberDecl* '}'
|
||||
StructMemberDecl ::= StructMethodDecl | StructCtorDecl
|
||||
StructMethodDecl ::= 'fn' Identifier ParamList ReturnAnn? Block
|
||||
StructCtorDecl ::= 'ctor' Identifier ParamList Block
|
||||
ContractBody ::= '{' FnSigDecl* '}'
|
||||
BuiltinTypeBody ::= '{' FnSigDecl* '}'
|
||||
ErrorBody ::= '{' ErrorCaseDecl+ '}'
|
||||
FieldDecl ::= Identifier ':' TypeRef ';'
|
||||
FnSigDecl ::= AttrList? 'fn' Identifier ParamList ReturnAnn? ';'
|
||||
@ -313,6 +319,14 @@ Rules:
|
||||
- A host declaration body contains only function signatures and no bodies.
|
||||
- Host declarations are reserved to SDK/toolchain-controlled modules and MUST be rejected in ordinary user-authored modules.
|
||||
- Host declarations do not declare fields, `ctor`, or `implements` bodies.
|
||||
- `declare builtin type Name(...) { ... }` declares a reserved SDK/toolchain builtin type shell with field-like projection metadata in the header and signature-only VM-owned member surfaces in the body.
|
||||
- A builtin type declaration body contains only function signatures and no bodies.
|
||||
- Builtin type declarations are reserved to SDK/toolchain-controlled modules and MUST be rejected in ordinary user-authored modules.
|
||||
- Builtin type declarations do not declare `ctor`, executable methods, or `implements` bodies.
|
||||
- Builtin type field entries are projection declarations, not ordinary struct storage fields.
|
||||
- Builtin type field entries may carry attributes where another specification explicitly permits them.
|
||||
- Builtin type field entries permit `pub` but do not permit `mut`.
|
||||
- Builtin method signatures MAY carry reserved VM-owned metadata such as `IntrinsicCall(...)`.
|
||||
- `declare error` bodies contain only error case labels.
|
||||
- `declare enum` uses a parenthesized case list and ends with `;`.
|
||||
- Error case labels in the same `declare error` body must be unique.
|
||||
@ -407,15 +421,18 @@ Rules:
|
||||
### 7.6 Top-level constants
|
||||
|
||||
```ebnf
|
||||
ConstDecl ::= 'declare' 'const' Identifier ':' TypeRef '=' Expr ';'
|
||||
ConstDecl ::= AttrList? 'declare' 'const' Identifier ':' TypeRef ConstInitOpt ';'
|
||||
ConstInitOpt ::= ('=' Expr)?
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Top-level constants MUST use `declare const`.
|
||||
- `declare const` is a declaration and may be exported through `mod.barrel`.
|
||||
- A `declare const` initializer MUST be a constant expression as defined by static semantics.
|
||||
- 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.
|
||||
|
||||
## 8. Type syntax
|
||||
|
||||
|
||||
@ -38,7 +38,7 @@ PBS distinguishes at least:
|
||||
|
||||
Rules:
|
||||
|
||||
- `declare struct`, `declare service`, `declare contract`, `declare error`, `declare enum`, and `declare callback` introduce names in the type namespace.
|
||||
- `declare struct`, `declare service`, `declare contract`, `declare error`, `declare enum`, `declare callback`, and `declare builtin type` introduce names in the type namespace.
|
||||
- `declare host` introduces names in the host-owner namespace.
|
||||
- `let`, parameters, and `declare const` introduce names in the value namespace.
|
||||
- `declare service Name` also introduces the canonical singleton value `Name` in the value namespace.
|
||||
@ -46,6 +46,7 @@ Rules:
|
||||
- `fn` declarations are not first-class values in v1 core and therefore do not become ordinary value expressions.
|
||||
- `bind(...)` is a callback-formation construct, not a general function-value construct.
|
||||
- `declare host` declarations are reserved to SDK/toolchain-controlled modules and are not formable in ordinary user-authored PBS source.
|
||||
- `declare builtin type` declarations are reserved to SDK/toolchain-controlled modules and are not formable in ordinary user-authored PBS source.
|
||||
- A host owner name is not an ordinary value expression in v1 core; it is used only as a qualified host-call owner.
|
||||
- The builtin simple types `int`, `float`, `bool`, and `str` are always present in the type namespace.
|
||||
- Builtin simple types are resolved without import or declaration.
|
||||
@ -61,11 +62,16 @@ Rules:
|
||||
- Attributes are not first-class values and are not reflectable in v1 core.
|
||||
- Attributes do not automatically survive into runtime or bytecode artifacts.
|
||||
- An attribute affects runtime artifacts only when another specification defines an explicit lowering for its semantic effect.
|
||||
- In v1 core, the only normative reserved attribute is `Host`.
|
||||
- In v1 core, the normative reserved attributes are `Host`, `BuiltinType`, `BuiltinConst`, `IntrinsicCall`, and `Slot`.
|
||||
- `Host` 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` metadata is consumed by the compiler during host-binding lowering.
|
||||
- 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.
|
||||
- `IntrinsicCall` is valid only on a method signature declared directly inside a reserved `declare builtin type` body.
|
||||
- `Slot` is valid only on a field declaration in the header of a reserved `declare builtin type`.
|
||||
- Builtin metadata is consumed by the compiler during VM-owned builtin and intrinsic lowering rather than by host-binding lowering.
|
||||
|
||||
### 2.4 Tuple shapes
|
||||
|
||||
@ -127,7 +133,8 @@ The following constructs are callable in v1 core:
|
||||
- contract values,
|
||||
- callback values,
|
||||
- service methods,
|
||||
- host methods on declared host owners.
|
||||
- host methods on declared host owners,
|
||||
- builtin intrinsic methods on declared builtin types.
|
||||
|
||||
Rules:
|
||||
|
||||
@ -137,6 +144,7 @@ Rules:
|
||||
- A callback declaration defines a nominal callable type with exactly one input/output tuple shape.
|
||||
- A service method is identified by `(service name, method name, input tuple shape, output tuple shape)`.
|
||||
- A host method is identified by `(host owner name, method name, input tuple shape, output tuple shape)` within the PBS declaration surface.
|
||||
- A builtin intrinsic method is identified within PBS declaration surface by `(builtin type name, method name, input tuple shape, output tuple shape)` and lowers further by canonical builtin/intrinsic metadata.
|
||||
- A top-level `fn` is identified by `(name, input tuple shape, output tuple shape)`.
|
||||
- A callback value is identified at the type level by its declared callback type and signature.
|
||||
- Contract signatures and barrel signatures must preserve the same callable shape.
|
||||
@ -166,9 +174,25 @@ Rules:
|
||||
- `Host.version` MUST be a positive integer literal.
|
||||
- Two host methods in the same resolved stdlib environment MUST NOT lower to the same canonical `(module, name, version)` unless they denote the same host method declaration after project/module resolution.
|
||||
- A `declare const` declaration must include an explicit type annotation.
|
||||
- A `declare const` initializer must be a constant expression.
|
||||
- A `declare const` declaration without `BuiltinConst` metadata must include an initializer.
|
||||
- A `declare const` declaration with `BuiltinConst` metadata must omit the initializer.
|
||||
- A non-builtin `declare const` initializer must be a constant expression.
|
||||
- `declare const` dependency resolution is module-wide and must not depend on source-file processing order.
|
||||
- `declare const` dependencies must form an acyclic graph.
|
||||
- A `BuiltinType` attribute MUST declare exactly the named arguments `name` and `version`.
|
||||
- `BuiltinType.name` MUST be a non-empty string literal.
|
||||
- `BuiltinType.version` MUST be a positive integer literal.
|
||||
- Two builtin type declarations in the same resolved stdlib environment MUST NOT lower to the same canonical `(name, version)` unless they denote the same builtin declaration after project/module resolution.
|
||||
- A builtin field type must be builtin-layout-admissible as defined by the builtin/intrinsics specification.
|
||||
- A builtin field `Slot` attribute, when present, MUST declare a non-negative integer literal and must match the declaration's canonical flattened layout.
|
||||
- `IntrinsicCall` MUST declare exactly the named argument `name` and MAY additionally declare `version`.
|
||||
- `IntrinsicCall.name` MUST be a non-empty string literal.
|
||||
- `IntrinsicCall.version`, when present, MUST be a positive integer literal.
|
||||
- Two builtin methods in the same canonical builtin owner/version line MUST NOT lower to the same canonical intrinsic `(owner, name, version)` unless they denote the same builtin method declaration after project/module resolution.
|
||||
- `BuiltinConst` MUST declare exactly the named arguments `target`, `name`, and `version`.
|
||||
- `BuiltinConst.target` and `BuiltinConst.name` MUST be non-empty string literals.
|
||||
- `BuiltinConst.version` MUST be a positive integer literal.
|
||||
- Two builtin constant declarations in the same resolved stdlib environment MUST NOT lower to the same canonical `(target, name, version)` unless they denote the same builtin constant declaration after project/module resolution.
|
||||
|
||||
### 3.4 Constant expressions
|
||||
|
||||
@ -176,8 +200,8 @@ PBS core v1 restricts top-level constant evaluation to a deterministic compile-t
|
||||
|
||||
Rules:
|
||||
|
||||
- A `declare const` initializer is evaluated at compile time.
|
||||
- A `declare const` may depend only on previously resolved visible `declare const` declarations and enum case values.
|
||||
- A non-builtin `declare const` initializer is evaluated at compile time.
|
||||
- A non-builtin `declare const` may depend only on previously resolved visible `declare const` declarations and enum case values.
|
||||
- Cross-file constant resolution within a module is defined by dependency analysis, not source-file order.
|
||||
- Constant evaluation fails if the dependency graph contains a cycle.
|
||||
- The allowed constant-expression forms in v1 core are:
|
||||
@ -189,7 +213,7 @@ Rules:
|
||||
- binary arithmetic operators over numeric constant expressions,
|
||||
- binary comparison operators over compatible constant expressions,
|
||||
- binary boolean operators over boolean constant expressions.
|
||||
- A `declare const` initializer must not use:
|
||||
- A non-builtin `declare const` initializer must not use:
|
||||
- callable application or call sugar,
|
||||
- `new`,
|
||||
- `bind(...)`,
|
||||
@ -198,7 +222,8 @@ Rules:
|
||||
- block expressions,
|
||||
- `if`, `switch`, `handle`, `else` extraction, or `!` result propagation,
|
||||
- method calls or member access except enum case paths.
|
||||
- The initializer type must be compatible with the declared `const` type.
|
||||
- For non-builtin `declare const`, the initializer type must be compatible with the declared `const` type.
|
||||
- A `BuiltinConst` declaration is not part of ordinary compile-time constant evaluation and lowers through VM-owned builtin constant materialization instead.
|
||||
- A `declare const` exported through `mod.barrel` may be imported from another module only through ordinary module import rules.
|
||||
- A `declare const` does not introduce mutable runtime storage; implementations may inline, fold, or materialize it as an immutable constant as long as observable semantics remain unchanged.
|
||||
|
||||
@ -500,10 +525,13 @@ Rules:
|
||||
- `HostName.method` is a valid method-call target when `HostName` resolves to a visible declared host owner whose body declares method `method`.
|
||||
- `TypeName.ctorName` is not a general member access surface; named constructors are entered only through `new TypeName.ctorName(...)`.
|
||||
- `expr.method` is a valid method-call target when the static type of `expr` is a contract value whose contract declares method `method`.
|
||||
- Bare extraction of a struct, service, host, or contract method as a value is invalid in v1 core because methods are not first-class.
|
||||
- Bare extraction of a struct, service, host, builtin, or contract method as a value is invalid in v1 core because methods are not first-class.
|
||||
- `expr.name` is valid when the static type of `expr` is a multi-slot named output tuple containing label `name`.
|
||||
- For named output tuples, the projected member type is the type of the corresponding output slot.
|
||||
- Projection is label-based, not position-based.
|
||||
- `expr.name` is valid when the static type of `expr` is a builtin type declaring projection field `name`.
|
||||
- For builtin projection fields, the projected member type is the declared builtin field type.
|
||||
- `expr.method` is a valid method-call target when the static type of `expr` is a builtin type declaring intrinsic member `method`.
|
||||
- `expr.hasSome()` and `expr.hasNone()` are valid intrinsic method-call surfaces when the static type of `expr` is `optional<P>`.
|
||||
- `expr.hasSome()` and `expr.hasNone()` both have static type `bool`.
|
||||
- `expr.name()` and `expr.key()` are valid intrinsic method-call surfaces when the static type of `expr` is an enum type.
|
||||
@ -517,6 +545,8 @@ Rules:
|
||||
- Access to a missing service method is a compile-time error.
|
||||
- Access to a missing host method is a compile-time error.
|
||||
- Access to a missing contract method is a compile-time error.
|
||||
- Access to a missing builtin projection field is a compile-time error.
|
||||
- Access to a missing builtin intrinsic member is a compile-time error.
|
||||
- Member projection is not defined for single-slot collapsed carrier values.
|
||||
|
||||
### 3.13 Block expressions and function fallthrough
|
||||
@ -621,11 +651,33 @@ At minimum, deterministic static diagnostics are required for:
|
||||
- invalid host method declaration shape,
|
||||
- invalid attribute surface,
|
||||
- invalid `Host` attribute target,
|
||||
- invalid `BuiltinType` attribute target,
|
||||
- invalid `BuiltinConst` attribute target,
|
||||
- invalid `IntrinsicCall` attribute target,
|
||||
- invalid `Slot` attribute target,
|
||||
- duplicate `Host` attribute on one host method,
|
||||
- missing required `Host` attribute on a reserved host method,
|
||||
- malformed `Host(module=..., name=..., version=...)` argument set,
|
||||
- invalid empty `Host.module` or `Host.name`,
|
||||
- invalid non-positive `Host.version`,
|
||||
- invalid builtin declaration shape,
|
||||
- invalid builtin method declaration shape,
|
||||
- missing required `BuiltinType` attribute on a reserved builtin declaration,
|
||||
- malformed `BuiltinType(name=..., version=...)` argument set,
|
||||
- invalid empty `BuiltinType.name`,
|
||||
- invalid non-positive `BuiltinType.version`,
|
||||
- malformed `IntrinsicCall(name=..., version=...)` argument set,
|
||||
- invalid empty `IntrinsicCall.name`,
|
||||
- invalid non-positive `IntrinsicCall.version`,
|
||||
- malformed `BuiltinConst(target=..., name=..., version=...)` argument set,
|
||||
- invalid empty `BuiltinConst.target` or `BuiltinConst.name`,
|
||||
- invalid non-positive `BuiltinConst.version`,
|
||||
- invalid builtin field `Slot(...)`,
|
||||
- overlapping builtin field slot range,
|
||||
- builtin field type not builtin-layout-admissible,
|
||||
- duplicate canonical builtin type identity,
|
||||
- duplicate canonical builtin intrinsic identity,
|
||||
- duplicate canonical builtin constant identity,
|
||||
- invalid `ctor` declaration shape,
|
||||
- invalid `return` inside `ctor`,
|
||||
- incomplete field initialization on a completing `ctor` path,
|
||||
@ -672,6 +724,7 @@ At minimum, deterministic static diagnostics are required for:
|
||||
- invalid `optional void` type surface,
|
||||
- invalid reuse of a builtin simple type name for a user-authored type declaration,
|
||||
- missing explicit type annotation on `declare const`,
|
||||
- missing initializer on non-builtin `declare const`,
|
||||
- non-constant `declare const` initializer,
|
||||
- incompatible `declare const` initializer type,
|
||||
- cyclic dependency among `declare const` declarations,
|
||||
@ -698,7 +751,10 @@ At minimum, deterministic static diagnostics are required for:
|
||||
- member access on a missing service method,
|
||||
- member access on a missing host method,
|
||||
- member access on a missing contract method,
|
||||
- bare method extraction from a struct, service, host, or contract value,
|
||||
- member access on a missing builtin projection field,
|
||||
- member access on a missing builtin intrinsic member,
|
||||
- bare method extraction from a struct, service, host, builtin, or contract value,
|
||||
- member projection on a single-slot carrier value,
|
||||
- invalid optional intrinsic member call,
|
||||
- invalid builtin intrinsic member call,
|
||||
- member projection on a missing named output label.
|
||||
|
||||
377
docs/specs/pbs/6. VM-owned vs Host-backed.md
Normal file
377
docs/specs/pbs/6. VM-owned vs Host-backed.md
Normal file
@ -0,0 +1,377 @@
|
||||
# VM-owned vs Host-backed
|
||||
|
||||
Status: Draft v1 (Temporary)
|
||||
Applies to: ownership classification of PBS-visible operations, runtime boundary selection, and the normative distinction between VM-defined semantics and host-provided services
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines the normative distinction between:
|
||||
|
||||
- VM-owned operations,
|
||||
- host-backed operations,
|
||||
- and user-defined program operations.
|
||||
|
||||
Its purpose is to prevent semantic drift between:
|
||||
|
||||
- builtin language behavior,
|
||||
- VM execution behavior,
|
||||
- host/platform integration,
|
||||
- and source-level surfaces that may look similar while belonging to different ownership domains.
|
||||
|
||||
This document exists because PBS must distinguish at least three different kinds
|
||||
of callable behavior:
|
||||
|
||||
- program-owned functions,
|
||||
- VM-owned intrinsic behavior,
|
||||
- host-backed services.
|
||||
|
||||
Without this distinction, the language would conflate:
|
||||
|
||||
- builtin semantics with syscalls,
|
||||
- source-level shells with runtime authority,
|
||||
- and VM contracts with host capability-gated services.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document defines:
|
||||
|
||||
- the ownership model for callable behavior visible to PBS programs,
|
||||
- the normative difference between VM-owned and host-backed operations,
|
||||
- the runtime boundary crossed by each operation category,
|
||||
- the relationship between ownership and lowering form,
|
||||
- the relationship between ownership and determinism,
|
||||
- the relationship between ownership and capability checks,
|
||||
- the relationship between ownership and loader resolution,
|
||||
- and the classification rule used to decide whether a surface belongs to the VM or to the host.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- the full parser grammar for builtin declarations,
|
||||
- the full intrinsic registry binary format,
|
||||
- the final PBX section numbering for intrinsic metadata,
|
||||
- subsystem-specific host APIs such as GFX or AUDIO,
|
||||
- or the complete dynamic semantics of every builtin type.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
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`)
|
||||
3. `1. Language Charter.md`
|
||||
4. `3. Core Syntax Specification.md`
|
||||
5. `4. Static Semantics Specification.md`
|
||||
6. `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
7. `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
8. This document
|
||||
|
||||
If a rule here conflicts with higher-precedence authority, the higher-precedence
|
||||
authority wins.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on, at minimum:
|
||||
|
||||
- `1. Language Charter.md`
|
||||
- `3. Core Syntax Specification.md`
|
||||
- `4. Static Semantics Specification.md`
|
||||
- `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
|
||||
## 5. Core Ownership Model
|
||||
|
||||
PBS distinguishes three ownership categories for callable behavior.
|
||||
|
||||
### 5.1 Program-owned function
|
||||
|
||||
A program-owned function is authored by the program and compiled from a PBS body.
|
||||
|
||||
Properties:
|
||||
|
||||
- semantic ownership belongs to the program,
|
||||
- execution stays inside the VM,
|
||||
- source definition includes an executable body,
|
||||
- runtime dispatch uses ordinary function-call machinery,
|
||||
- authority does not depend on host capability grants.
|
||||
|
||||
### 5.2 VM-owned operation
|
||||
|
||||
A VM-owned operation is part of the semantic contract of the PBS platform.
|
||||
|
||||
Properties:
|
||||
|
||||
- semantic ownership belongs to the VM platform,
|
||||
- execution stays inside the VM,
|
||||
- behavior is not defined by user-authored PBS bodies,
|
||||
- behavior is not resolved against host registries,
|
||||
- behavior is not granted or denied by host capabilities,
|
||||
- and behavior is expected to remain semantically canonical across conforming implementations.
|
||||
|
||||
VM-owned operations include, at minimum:
|
||||
|
||||
- intrinsic operations over builtin types,
|
||||
- compiler-recognized intrinsic method-call surfaces over core semantic forms,
|
||||
- and other future VM-defined semantic helpers explicitly designated by spec.
|
||||
|
||||
### 5.3 Host-backed operation
|
||||
|
||||
A host-backed operation is provided by the runtime environment outside the VM's
|
||||
closed semantic domain.
|
||||
|
||||
Properties:
|
||||
|
||||
- semantic authority belongs to the host platform,
|
||||
- execution crosses the VM-to-host boundary,
|
||||
- resolution uses canonical host identity,
|
||||
- loader validation and capability checks are required before execution,
|
||||
- and the final executable form is numeric host dispatch.
|
||||
|
||||
Host-backed operations are the domain of `declare host`, PBX `SYSC`, loader
|
||||
resolution, and final `SYSCALL`.
|
||||
|
||||
## 6. The Boundary Question
|
||||
|
||||
The normative classification question is:
|
||||
|
||||
```text
|
||||
Does this operation belong to the VM's semantic contract, or does it require a
|
||||
service owned by the external host platform?
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- If the operation expresses builtin language or VM semantics, it is VM-owned.
|
||||
- If the operation requires host-provided authority, devices, or platform services, it is host-backed.
|
||||
- If the operation is implemented by ordinary source code in the current program, it is program-owned.
|
||||
|
||||
Heuristic:
|
||||
|
||||
- if the operation must still have a complete meaning in a host-minimal VM, it is VM-owned,
|
||||
- if the operation loses meaning without external platform service, it is host-backed.
|
||||
|
||||
Examples:
|
||||
|
||||
- `Vec2.dot(other)` is VM-owned,
|
||||
- `Color.rgb(r, g, b)` is VM-owned,
|
||||
- `optional.hasSome()` is VM-owned,
|
||||
- `enumValue.name()` is VM-owned,
|
||||
- `Gfx.draw_pixel(x, y, c)` is host-backed,
|
||||
- `Input.is_pressed(button)` is host-backed.
|
||||
|
||||
## 7. Runtime Boundary and Resolution Model
|
||||
|
||||
### 7.1 VM-owned operations
|
||||
|
||||
VM-owned operations do not cross the host boundary.
|
||||
|
||||
Rules:
|
||||
|
||||
- they do not resolve through the host syscall registry,
|
||||
- they do not emit `SYSC`,
|
||||
- they do not require loader-side capability checks,
|
||||
- they are not represented by `declare host`,
|
||||
- and they execute through VM-owned machinery such as intrinsic dispatch or other VM-defined execution paths.
|
||||
|
||||
### 7.2 Host-backed operations
|
||||
|
||||
Host-backed operations cross the VM boundary and require host authority.
|
||||
|
||||
Rules:
|
||||
|
||||
- they resolve by canonical host identity `(module, name, version)`,
|
||||
- they are represented in source through reserved host-binding surfaces,
|
||||
- they emit PBX host-binding metadata,
|
||||
- they are validated against authoritative host metadata during load,
|
||||
- and they execute in final form through `SYSCALL`.
|
||||
|
||||
## 8. Semantic Authority
|
||||
|
||||
The semantic owner of an operation is the layer that defines its normative
|
||||
meaning.
|
||||
|
||||
### 8.1 VM-owned semantic authority
|
||||
|
||||
For VM-owned operations:
|
||||
|
||||
- the VM platform defines the operation's meaning,
|
||||
- the frontend may expose shell declarations but does not define behavior,
|
||||
- the host runtime must not redefine the operation's language-level semantics,
|
||||
- and the HAL may consume produced values but must not own their semantic definition.
|
||||
|
||||
### 8.2 Host-backed semantic authority
|
||||
|
||||
For host-backed operations:
|
||||
|
||||
- the host platform defines the authoritative service identity and ABI,
|
||||
- the frontend exposes a compile-time shell only,
|
||||
- the loader resolves the shell's canonical identity against the host registry,
|
||||
- and the VM executes only the numeric form after loader patching.
|
||||
|
||||
## 9. Determinism and Environmental Dependence
|
||||
|
||||
Determinism requirements differ by ownership category.
|
||||
|
||||
### 9.1 VM-owned operations
|
||||
|
||||
VM-owned operations must not derive meaning from host service behavior.
|
||||
|
||||
Rules:
|
||||
|
||||
- a VM-owned operation must not call the host as part of its semantic definition,
|
||||
- a VM-owned operation must not require host capability grants,
|
||||
- a VM-owned operation must not depend on wall-clock time unless a higher-precedence authority explicitly allows it,
|
||||
- a VM-owned operation must not depend on frontend-generated helper algorithms for its canonical behavior,
|
||||
- and the VM contract must be specific enough that conformance can test its behavior.
|
||||
|
||||
This does not require every VM-owned operation to be mathematically pure.
|
||||
It does require the operation's meaning to be owned and specified by the VM
|
||||
contract rather than delegated to the host.
|
||||
|
||||
### 9.2 Host-backed operations
|
||||
|
||||
Host-backed operations may depend on host state, devices, permissions, or
|
||||
platform policy.
|
||||
|
||||
Rules:
|
||||
|
||||
- host-backed operations may be denied by capability policy,
|
||||
- host-backed operations may vary by platform implementation within their ABI contract,
|
||||
- and host-backed operations are not reclassified as VM-owned merely because the source surface resembles an ordinary method call.
|
||||
|
||||
## 10. Artifact Implications
|
||||
|
||||
Ownership classification determines artifact form.
|
||||
|
||||
### 10.1 Program-owned function artifact direction
|
||||
|
||||
Program-owned functions lower to ordinary program call machinery.
|
||||
|
||||
### 10.2 VM-owned artifact direction
|
||||
|
||||
VM-owned operations lower to VM-facing artifacts.
|
||||
|
||||
Illustrative forms:
|
||||
|
||||
- direct intrinsic ids such as `INTRINSIC <id>`,
|
||||
- temporary intrinsic declaration tables plus pre-resolution callsites,
|
||||
- or other VM-internal runtime forms explicitly defined by future spec.
|
||||
|
||||
Rules:
|
||||
|
||||
- VM-owned operations must not be encoded as host-binding metadata merely because they are not authored in user code,
|
||||
- and VM-owned operations must not require host registry lookup.
|
||||
|
||||
### 10.3 Host-backed artifact direction
|
||||
|
||||
Host-backed operations lower to host-facing artifacts.
|
||||
|
||||
Rules:
|
||||
|
||||
- host-backed operations emit host-binding declarations into `SYSC`,
|
||||
- host-backed callsites use `HOSTCALL <sysc_index>` before load,
|
||||
- the loader resolves and patches those callsites,
|
||||
- and final execution uses `SYSCALL <id>`.
|
||||
|
||||
## 11. Source Surface Similarity Does Not Collapse Ownership
|
||||
|
||||
Two source surfaces may look similar while belonging to different ownership
|
||||
domains.
|
||||
|
||||
Examples:
|
||||
|
||||
- `Vec2.length()` may be VM-owned,
|
||||
- `Gfx.clear(color)` may be host-backed,
|
||||
- `value.name()` over an enum may be VM-owned,
|
||||
- and `service.method()` may be program-owned or service-owned ordinary PBS behavior.
|
||||
|
||||
Rules:
|
||||
|
||||
- source-level method-call syntax does not determine ownership,
|
||||
- declaration shape does not determine ownership,
|
||||
- ownership is determined by semantic authority and runtime boundary,
|
||||
- and toolchain metadata must classify the operation explicitly where ambiguity could arise.
|
||||
|
||||
## 12. Relationship to `declare host`
|
||||
|
||||
`declare host` is reserved exclusively for host-backed surfaces.
|
||||
|
||||
Rules:
|
||||
|
||||
- `declare host` must not be reused to model VM-owned builtin semantics,
|
||||
- host attributes such as `Host(module, name, version)` must not be used to identify VM-owned intrinsic behavior,
|
||||
- and a source surface that represents VM-owned behavior must use VM-specific metadata and lowering rules.
|
||||
|
||||
Rationale:
|
||||
|
||||
- `declare host` communicates external service ownership,
|
||||
- host attributes communicate loader-facing canonical identity,
|
||||
- and reusing them for VM-owned behavior would incorrectly imply host resolution, capability gating, and host semantic authority.
|
||||
|
||||
## 13. Relationship to Builtin Types and Intrinsics
|
||||
|
||||
Builtin types are VM-facing semantic types.
|
||||
|
||||
Rules:
|
||||
|
||||
- builtin types are not host APIs,
|
||||
- builtin type operations that belong to the builtin domain are VM-owned,
|
||||
- builtin constants, projections, constructors, and intrinsic methods are classified by VM semantics rather than by host service ownership,
|
||||
- and builtin values may later be passed to host-backed operations without transferring semantic ownership of the type itself.
|
||||
|
||||
Example:
|
||||
|
||||
- `Color` is VM-owned as a semantic type,
|
||||
- `Color.rgb(...)` is VM-owned,
|
||||
- `Pixel` may contain `Color` in its builtin layout,
|
||||
- `Gfx.draw_pixel(x, y, c)` is host-backed even when `c` has a VM-owned builtin type.
|
||||
|
||||
## 14. Relationship to `stdlib` and SDK Surfaces
|
||||
|
||||
`stdlib` and SDK packaging expose compile-time surfaces.
|
||||
|
||||
Rules:
|
||||
|
||||
- SDK or stdlib shells may expose both VM-owned and host-backed surfaces,
|
||||
- shell placement alone does not determine runtime ownership,
|
||||
- the runtime-facing artifact contract must preserve the true ownership category,
|
||||
- and compile-time convenience must not collapse VM-owned and host-backed operations into the same runtime mechanism.
|
||||
|
||||
## 15. Classification Checklist
|
||||
|
||||
When introducing a new callable surface, the spec author or toolchain author
|
||||
must answer at least these questions:
|
||||
|
||||
1. Who owns the semantic meaning of this operation?
|
||||
2. Does the operation require host-provided authority, devices, or policy?
|
||||
3. Must the loader resolve the operation against an external registry?
|
||||
4. Can the operation be denied by capabilities?
|
||||
5. Should the operation continue to exist with complete meaning in a host-minimal VM?
|
||||
6. Is the operation part of builtin language semantics rather than platform service integration?
|
||||
|
||||
Classification rule:
|
||||
|
||||
- If answers 2, 3, or 4 are yes, the operation is host-backed.
|
||||
- If answer 6 is yes and 2, 3, and 4 are no, the operation is VM-owned.
|
||||
- Otherwise the operation is program-owned unless another spec defines a distinct category.
|
||||
|
||||
## 16. Conformance Expectations
|
||||
|
||||
Conforming implementations must preserve the ownership boundary.
|
||||
|
||||
Rules:
|
||||
|
||||
- an implementation must not lower VM-owned builtin semantics through the host syscall pipeline,
|
||||
- an implementation must not treat host-backed operations as if they were VM-defined intrinsic semantics,
|
||||
- an implementation must preserve the loader-facing host-binding contract for host-backed surfaces,
|
||||
- and an implementation must preserve VM-facing semantic ownership for builtin and intrinsic operations.
|
||||
|
||||
## 17. Current Decision Summary
|
||||
|
||||
The current model is:
|
||||
|
||||
1. Program-authored functions are program-owned and execute through ordinary call machinery.
|
||||
2. Builtin semantics and intrinsic behavior are VM-owned.
|
||||
3. External platform services are host-backed.
|
||||
4. VM-owned behavior must not be modeled as `declare host`.
|
||||
5. Host-backed behavior must continue to use canonical host identity, `SYSC`, loader resolution, and final `SYSCALL`.
|
||||
6. Ownership is determined by semantic authority and runtime boundary, not by source-level syntax resemblance.
|
||||
@ -0,0 +1,555 @@
|
||||
# Intrinsics and Builtin Types Specification
|
||||
|
||||
Status: Draft v1 (Temporary)
|
||||
Applies to: builtin type declarations, builtin constants, intrinsic member surfaces, builtin layout metadata, lowering direction, and artifact-facing intrinsic contracts
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines the PBS-facing contract for:
|
||||
|
||||
- VM-owned builtin types,
|
||||
- VM-owned intrinsic operations,
|
||||
- and source-level shells that expose those features to PBS programs.
|
||||
|
||||
Its purpose is to let the frontend expose builtin semantic types such as
|
||||
`Vec2`, `Color`, and `Pixel` as first-class language types while preserving
|
||||
three invariants:
|
||||
|
||||
- semantic ownership remains with the VM,
|
||||
- builtin values have canonical stack layout,
|
||||
- and builtin domain behavior does not drift into host bindings or frontend helper code.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document defines:
|
||||
|
||||
- the source-level shell model for `declare builtin type`,
|
||||
- the canonical metadata carried by builtin type declarations,
|
||||
- builtin constants declared through reserved metadata,
|
||||
- builtin field layout and projection rules,
|
||||
- admissible field types for builtin layouts,
|
||||
- intrinsic member metadata and owner inheritance,
|
||||
- lowering categories for builtin declarations and members,
|
||||
- and the runtime-facing artifact direction for intrinsic operations.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- the full final parser grammar integration into `3. Core Syntax Specification.md`,
|
||||
- the final PBX section numbering for intrinsic declarations,
|
||||
- the full VM intrinsic registry binary format,
|
||||
- user-extensible builtin types,
|
||||
- or heap-backed builtin layouts.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
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`)
|
||||
3. `1. Language Charter.md`
|
||||
4. `3. Core Syntax Specification.md`
|
||||
5. `4. Static Semantics Specification.md`
|
||||
6. `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
7. `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
8. `6. VM-owned vs Host-backed.md`
|
||||
9. This document
|
||||
|
||||
If a rule here conflicts with higher-precedence authority, the higher-precedence
|
||||
authority wins.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on, at minimum:
|
||||
|
||||
- `1. Language Charter.md`
|
||||
- `3. Core Syntax Specification.md`
|
||||
- `4. Static Semantics Specification.md`
|
||||
- `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `6. VM-owned vs Host-backed.md`
|
||||
- `12. IR and Lowering Specification.md`
|
||||
- `15. Bytecode and PBX Mapping Specification.md`
|
||||
|
||||
## 5. Core Model
|
||||
|
||||
### 5.1 Builtin type
|
||||
|
||||
A builtin type is a VM-owned semantic type whose language-visible identity is
|
||||
not authored by ordinary user code.
|
||||
|
||||
Properties:
|
||||
|
||||
- the type is first-class in the PBS type system,
|
||||
- the type has canonical layout metadata,
|
||||
- the type may expose field-like projection surfaces,
|
||||
- the type may expose intrinsic member-call surfaces,
|
||||
- and the type's semantic meaning is owned by the VM rather than by `stdlib`, SDK packaging, or the host.
|
||||
|
||||
### 5.2 Builtin declaration shell
|
||||
|
||||
`declare builtin type` is a reserved shell declaration.
|
||||
|
||||
Properties:
|
||||
|
||||
- it exists for binding, checking, lowering, and artifact emission,
|
||||
- it has no user-authored executable body,
|
||||
- and it does not transfer semantic ownership away from the VM registry.
|
||||
|
||||
### 5.3 Builtin constant
|
||||
|
||||
A builtin constant is a VM-owned named value exposed to source through a
|
||||
reserved top-level `declare const` shell carrying builtin metadata.
|
||||
|
||||
### 5.4 Intrinsic operation
|
||||
|
||||
An intrinsic operation is a VM-owned callable behavior with canonical
|
||||
definition in the VM contract.
|
||||
|
||||
## 6. Reserved Surface Forms
|
||||
|
||||
This document temporarily defines the intended source-level shell shape.
|
||||
Final parser integration belongs to `3. Core Syntax Specification.md`.
|
||||
|
||||
### 6.1 Builtin type shell
|
||||
|
||||
Illustrative form:
|
||||
|
||||
```pbs
|
||||
[BuiltinType(name="vec2", version=1)]
|
||||
declare builtin type Vec2(
|
||||
[Slot(0)] pub x: float,
|
||||
[Slot(1)] pub y: float,
|
||||
) {
|
||||
[IntrinsicCall(name="dot")]
|
||||
fn dot(other: Vec2) -> float;
|
||||
|
||||
[IntrinsicCall(name="length")]
|
||||
fn length() -> float;
|
||||
}
|
||||
```
|
||||
|
||||
### 6.2 Builtin constant shell
|
||||
|
||||
Illustrative form:
|
||||
|
||||
```pbs
|
||||
[BuiltinConst(target="vec2", name="zero", version=1)]
|
||||
declare const ZERO: Vec2;
|
||||
```
|
||||
|
||||
## 7. `BuiltinType` Metadata
|
||||
|
||||
`BuiltinType` declares the canonical VM-facing identity of a builtin type.
|
||||
|
||||
Required fields:
|
||||
|
||||
- `name`
|
||||
- `version`
|
||||
|
||||
Rules:
|
||||
|
||||
- the declaration name after `declare builtin type` is the PBS-visible type name,
|
||||
- `BuiltinType.name` is the canonical VM identity name,
|
||||
- `BuiltinType.version` is the canonical semantic version of that builtin contract,
|
||||
- the VM identity name need not equal the PBS-visible type name,
|
||||
- and the pair `(name, version)` is the canonical builtin type identity in v1.
|
||||
|
||||
Example:
|
||||
|
||||
- source-visible name: `Vec2`
|
||||
- canonical builtin identity: `("vec2", 1)`
|
||||
|
||||
## 8. Declaration Form and Structural Rules
|
||||
|
||||
`declare builtin type` uses a field-list surface similar to nominal aggregate
|
||||
declarations.
|
||||
|
||||
Rules:
|
||||
|
||||
- `declare builtin type` is reserved to SDK/toolchain-controlled modules,
|
||||
- ordinary user-authored modules must reject it,
|
||||
- the declaration introduces a type name in the type namespace,
|
||||
- the parenthesized member list declares builtin field projections,
|
||||
- the body may contain signatures only,
|
||||
- the body must not contain executable PBS statements,
|
||||
- builtin members must not declare PBS bodies,
|
||||
- and builtin declarations must not be used to encode ordinary user-defined structs.
|
||||
|
||||
This surface is intentionally shell-like.
|
||||
The declaration is not the implementation authority for builtin behavior.
|
||||
|
||||
## 9. Builtin Fields Are Projections, Not Ordinary Storage Fields
|
||||
|
||||
The field-like entries in a builtin declaration describe named projections over a
|
||||
canonical VM layout.
|
||||
|
||||
Rules:
|
||||
|
||||
- they are not ordinary user-defined struct fields,
|
||||
- their names are visible for projection syntax such as `value.x`,
|
||||
- they describe a canonical flattened layout order,
|
||||
- and their meaning is projection over VM-owned builtin value representation.
|
||||
|
||||
Consequences:
|
||||
|
||||
- a builtin field declaration does not imply ordinary mutability semantics,
|
||||
- a builtin field declaration does not imply that builtin values are structs,
|
||||
- and a builtin field declaration does not allow user code to provide storage-level implementation bodies.
|
||||
|
||||
## 10. `Slot` Metadata
|
||||
|
||||
`Slot(n)` identifies the starting flattened slot offset of a builtin field within
|
||||
the enclosing builtin layout.
|
||||
|
||||
Rules:
|
||||
|
||||
- `n` is zero-based,
|
||||
- `Slot(n)` refers to the starting slot offset after flattening nested builtin-layout-admissible fields,
|
||||
- slot offsets must be unique,
|
||||
- slot offsets must match the declaration's canonical flattened layout,
|
||||
- and overlapping slot ranges are invalid.
|
||||
|
||||
`Slot` exists to make canonical layout explicit.
|
||||
Future grammar may allow offset inference by declaration order, but explicit slot
|
||||
metadata is valid and authoritative in this temporary contract.
|
||||
|
||||
## 11. Builtin Layout Admissibility
|
||||
|
||||
Builtin field types are restricted.
|
||||
|
||||
A type is builtin-layout-admissible when it has:
|
||||
|
||||
- fixed width in slots,
|
||||
- finite flattened layout,
|
||||
- stack-only representation in this feature set,
|
||||
- and canonical VM-owned layout metadata.
|
||||
|
||||
In v1 temporary scope, builtin-layout-admissible types are:
|
||||
|
||||
- predeclared builtin scalar types whose runtime contract defines fixed slot width,
|
||||
- and declared builtin types whose own layout is fixed, finite, and stack-only.
|
||||
|
||||
The following are not builtin-layout-admissible unless a future spec explicitly
|
||||
changes the rule:
|
||||
|
||||
- user-declared structs,
|
||||
- services,
|
||||
- contracts,
|
||||
- callbacks,
|
||||
- `optional`,
|
||||
- `result`,
|
||||
- and any type with runtime-variable or heap-defined width.
|
||||
|
||||
## 12. Nested Builtin Layout and Flattening
|
||||
|
||||
Builtin fields may refer to other builtin-layout-admissible types.
|
||||
|
||||
Rules:
|
||||
|
||||
- nested builtin field types flatten recursively into the enclosing layout,
|
||||
- the enclosing builtin layout is the concatenation of its fields' flattened layouts in slot order,
|
||||
- a nested field retains its nominal field identity for projection purposes,
|
||||
- and verifier-facing slot widths are computed from the fully flattened layout.
|
||||
|
||||
Example:
|
||||
|
||||
```pbs
|
||||
[BuiltinType(name="color", version=1)]
|
||||
declare builtin type Color(
|
||||
[Slot(0)] pub raw: int,
|
||||
);
|
||||
|
||||
[BuiltinType(name="pixel", version=1)]
|
||||
declare builtin type Pixel(
|
||||
[Slot(0)] pub x: int,
|
||||
[Slot(1)] pub y: int,
|
||||
[Slot(2)] pub color: Color,
|
||||
);
|
||||
```
|
||||
|
||||
Canonical semantic layout:
|
||||
|
||||
```text
|
||||
Pixel -> [int, int, Color]
|
||||
```
|
||||
|
||||
Canonical flattened slot layout:
|
||||
|
||||
```text
|
||||
Pixel -> [int, int, int]
|
||||
```
|
||||
|
||||
## 13. Member Categories
|
||||
|
||||
Builtin members belong to one of the following semantic categories:
|
||||
|
||||
1. projection surface,
|
||||
2. builtin constant surface,
|
||||
3. layout-only constructor or factory surface,
|
||||
4. intrinsic call surface.
|
||||
|
||||
This document normatively defines projection, builtin constants, and intrinsic
|
||||
call surfaces.
|
||||
Layout-only constructors may be introduced by future syntax or by existing
|
||||
constructor lowering rules, but their implementation remains VM-facing rather
|
||||
than host-backed.
|
||||
|
||||
## 14. `IntrinsicCall` Metadata
|
||||
|
||||
`IntrinsicCall` identifies a VM-owned callable member over builtin semantics.
|
||||
|
||||
Required fields:
|
||||
|
||||
- `name`
|
||||
|
||||
Optional fields:
|
||||
|
||||
- `version`
|
||||
|
||||
Rules:
|
||||
|
||||
- `IntrinsicCall` is valid only on method signatures declared inside a `declare builtin type` body,
|
||||
- the enclosing `BuiltinType` provides the default intrinsic owner identity,
|
||||
- `IntrinsicCall.name` is the canonical intrinsic operation name within that owner,
|
||||
- if `IntrinsicCall.version` is omitted, it inherits the enclosing builtin type version,
|
||||
- if `IntrinsicCall.version` is present, it overrides only the operation version,
|
||||
- and `IntrinsicCall` must not be interpreted as host-binding metadata.
|
||||
|
||||
Canonical intrinsic identity in v1 is:
|
||||
|
||||
```text
|
||||
(owner, name, version)
|
||||
```
|
||||
|
||||
where:
|
||||
|
||||
- `owner` is inherited from `BuiltinType.name`,
|
||||
- `name` is taken from `IntrinsicCall.name`,
|
||||
- and `version` is inherited or overridden as above.
|
||||
|
||||
Example:
|
||||
|
||||
```pbs
|
||||
[BuiltinType(name="vec2", version=1)]
|
||||
declare builtin type Vec2(
|
||||
[Slot(0)] pub x: float,
|
||||
[Slot(1)] pub y: float,
|
||||
) {
|
||||
[IntrinsicCall(name="dot")]
|
||||
fn dot(other: Vec2) -> float;
|
||||
}
|
||||
```
|
||||
|
||||
declares canonical intrinsic identity:
|
||||
|
||||
```text
|
||||
("vec2", "dot", 1)
|
||||
```
|
||||
|
||||
## 15. `BuiltinConst` Metadata
|
||||
|
||||
`BuiltinConst` identifies a VM-owned named constant surface.
|
||||
|
||||
Required fields:
|
||||
|
||||
- `target`
|
||||
- `name`
|
||||
- `version`
|
||||
|
||||
Rules:
|
||||
|
||||
- `BuiltinConst` is valid only on reserved top-level `declare const` shells,
|
||||
- `target` identifies the canonical builtin owner name,
|
||||
- `name` identifies the canonical constant name within that builtin owner,
|
||||
- `version` identifies the constant contract version,
|
||||
- the declared PBS constant name is source-visible and may differ from the canonical constant name,
|
||||
- and builtin constants are VM-owned declarations, not host bindings.
|
||||
|
||||
Example:
|
||||
|
||||
```pbs
|
||||
[BuiltinConst(target="vec2", name="zero", version=1)]
|
||||
declare const ZERO: Vec2;
|
||||
```
|
||||
|
||||
declares a source-visible constant `ZERO` whose canonical builtin constant
|
||||
identity is:
|
||||
|
||||
```text
|
||||
("vec2", "zero", 1)
|
||||
```
|
||||
|
||||
## 16. Static Semantics
|
||||
|
||||
The following static rules apply.
|
||||
|
||||
### 16.1 Namespace rules
|
||||
|
||||
Rules:
|
||||
|
||||
- `declare builtin type` introduces a nominal type name in the type namespace,
|
||||
- builtin type names participate in visibility and import rules like other reserved type declarations,
|
||||
- ordinary user-authored type declarations must not redeclare visible builtin type names in the same scope,
|
||||
- and builtin constants declared through `declare const` introduce names in the value namespace.
|
||||
|
||||
### 16.2 Member lookup rules
|
||||
|
||||
Rules:
|
||||
|
||||
- `expr.field` is valid when `expr` has a builtin type declaring a projection field named `field`,
|
||||
- the projected type is the field's declared type,
|
||||
- `expr.method()` is valid when the builtin type declares a matching intrinsic member surface,
|
||||
- and missing builtin fields or members are compile-time errors.
|
||||
|
||||
### 16.3 Body restrictions
|
||||
|
||||
Rules:
|
||||
|
||||
- builtin declarations have no executable member bodies,
|
||||
- builtin methods are signature-only shells,
|
||||
- builtin constants are declaration-only shells,
|
||||
- and ordinary user code must not implement builtin semantics in PBS bodies.
|
||||
|
||||
## 17. Lowering Model
|
||||
|
||||
Builtin shells guide lowering; they do not supply executable implementation.
|
||||
|
||||
### 17.1 Projection lowering
|
||||
|
||||
Projection over builtin fields lowers to canonical projection over flattened
|
||||
layout.
|
||||
|
||||
Rules:
|
||||
|
||||
- field projection does not imply host interaction,
|
||||
- field projection does not emit `SYSC`,
|
||||
- field projection may lower to direct stack projection, reshaping operations, or another VM-owned form,
|
||||
- and the projected semantics are determined by builtin layout metadata.
|
||||
|
||||
### 17.2 Builtin constant lowering
|
||||
|
||||
Builtin constants lower to VM-owned constant materialization.
|
||||
|
||||
Rules:
|
||||
|
||||
- builtin constants must not lower through host binding resolution,
|
||||
- builtin constants may lower to direct value materialization, VM-owned constant pool lookup, or intrinsic-like constant fetch,
|
||||
- and the canonical constant identity determines which VM-owned value is materialized.
|
||||
|
||||
### 17.3 Intrinsic method lowering
|
||||
|
||||
Intrinsic methods lower to VM-owned intrinsic call behavior.
|
||||
|
||||
Rules:
|
||||
|
||||
- intrinsic methods must not lower through `SYSC`,
|
||||
- intrinsic methods must not emit `HOSTCALL`,
|
||||
- intrinsic method identities lower from `(owner, name, version)` metadata,
|
||||
- and the runtime-facing call form is VM-facing rather than host-facing.
|
||||
|
||||
## 18. Artifact Direction
|
||||
|
||||
This feature requires a distinct intrinsic artifact path.
|
||||
|
||||
Illustrative final executable form:
|
||||
|
||||
```text
|
||||
INTRINSIC <id>
|
||||
```
|
||||
|
||||
Illustrative optional pre-resolution form:
|
||||
|
||||
```text
|
||||
INTRCALL <decl_index>
|
||||
```
|
||||
|
||||
with declaration metadata carrying:
|
||||
|
||||
```text
|
||||
(owner, name, version)
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- implementations may emit final `INTRINSIC <id>` directly when intrinsic ids are stable for the targeted VM contract,
|
||||
- implementations may emit declaration-based intrinsic callsites when a preload resolution step is desired,
|
||||
- any such intrinsic declaration path remains VM-facing and must not reuse host-binding metadata,
|
||||
- and intrinsic artifacts are distinct from `SYSC`, `HOSTCALL`, and `SYSCALL`.
|
||||
|
||||
## 19. Verifier Obligations
|
||||
|
||||
The verifier must treat intrinsics and builtin layouts as first-class structural
|
||||
facts.
|
||||
|
||||
Rules:
|
||||
|
||||
- each builtin type has a known flattened slot width,
|
||||
- each intrinsic has known argument and result layouts,
|
||||
- verifier stack effects are computed from flattened layouts rather than only from source spellings,
|
||||
- and verifier reasoning must preserve nominal builtin type identity even when two builtin layouts occupy the same slot width.
|
||||
|
||||
Example:
|
||||
|
||||
```text
|
||||
Vec2.dot(Vec2, Vec2) -> float
|
||||
```
|
||||
|
||||
If `Vec2` flattens to two float-width slots, the verifier-facing stack effect is:
|
||||
|
||||
```text
|
||||
pop 4, push 1
|
||||
```
|
||||
|
||||
## 20. Determinism and Ownership Rules
|
||||
|
||||
Builtin and intrinsic semantics are VM-owned.
|
||||
|
||||
Rules:
|
||||
|
||||
- builtin operations must not rely on host registry resolution,
|
||||
- builtin operations must not require runtime capability grants,
|
||||
- builtin operations must not be specified merely as frontend helper code,
|
||||
- and builtin operations must remain within the VM-owned category defined by `6. VM-owned vs Host-backed.md`.
|
||||
|
||||
## 21. Relationship to `stdlib` and SDK Packaging
|
||||
|
||||
`stdlib` and SDK packaging may expose builtin declarations as compile-time
|
||||
surfaces.
|
||||
|
||||
Rules:
|
||||
|
||||
- packaging location does not make builtin semantics host-backed,
|
||||
- source modules may import builtin shells from reserved stdlib surfaces,
|
||||
- the shell remains descriptive rather than semantically authoritative,
|
||||
- and the VM contract remains the owner of builtin identities, layouts, constants, and intrinsic behavior.
|
||||
|
||||
## 22. Deterministic Static Errors
|
||||
|
||||
At minimum, a conforming implementation must reject:
|
||||
|
||||
1. `declare builtin type` in an ordinary user-authored module,
|
||||
2. missing required `BuiltinType` metadata on a builtin declaration,
|
||||
3. duplicate builtin field names within one declaration,
|
||||
4. duplicate or overlapping slot assignments,
|
||||
5. builtin field types that are not builtin-layout-admissible,
|
||||
6. `IntrinsicCall` used outside a builtin declaration body,
|
||||
7. `BuiltinConst` used outside a reserved top-level `declare const` shell,
|
||||
8. duplicate canonical builtin type identities in the same compilation environment,
|
||||
9. duplicate intrinsic canonical identities within the same builtin owner and version line,
|
||||
10. mismatched declared field slot metadata versus flattened layout,
|
||||
11. executable member bodies inside builtin declarations,
|
||||
12. any lowering that routes VM-owned builtin operations through the host-binding pipeline.
|
||||
|
||||
## 23. Current Decision Summary
|
||||
|
||||
The current temporary contract is:
|
||||
|
||||
1. Builtin types are VM-owned semantic types exposed through reserved shell declarations.
|
||||
2. `BuiltinType(name, version)` maps source-visible type names to canonical VM builtin identities.
|
||||
3. Builtin fields describe projection surfaces over canonical flattened layout.
|
||||
4. Builtin field types must be builtin-layout-admissible and stack-only in this feature set.
|
||||
5. Builtin types may contain other builtin-layout-admissible types, including nested builtin composition such as `Pixel` containing `Color`.
|
||||
6. `IntrinsicCall(name, version?)` identifies VM-owned intrinsic member behavior and inherits owner identity from the enclosing builtin type.
|
||||
7. `BuiltinConst(target, name, version)` exposes VM-owned builtin constants through reserved top-level `declare const` shells.
|
||||
8. Builtin projections, constants, and intrinsic calls must not lower through `SYSC`, `HOSTCALL`, or `SYSCALL`.
|
||||
9. Runtime-facing intrinsic artifacts are distinct from host-binding artifacts.
|
||||
133
docs/specs/pbs/9. Dynamic Semantics Specification.md
Normal file
133
docs/specs/pbs/9. Dynamic Semantics Specification.md
Normal file
@ -0,0 +1,133 @@
|
||||
# PBS Dynamic Semantics Specification
|
||||
|
||||
Status: Draft v0 (Skeleton)
|
||||
Applies to: runtime-observable behavior of PBS core programs
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document will define the normative dynamic semantics of PBS core.
|
||||
|
||||
Its purpose is to make runtime behavior convergent across implementations by fixing:
|
||||
|
||||
- execution ordering,
|
||||
- runtime evaluation of expressions and statements,
|
||||
- abrupt completion and trap propagation,
|
||||
- runtime behavior of effect surfaces such as `optional` and `result`,
|
||||
- the execution boundary between ordinary PBS code, callbacks, contract calls, and host-backed calls.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document is intended to define:
|
||||
|
||||
- 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 behavior of `optional`, `result<E>`, `else`, `!`, and `handle`,
|
||||
- abrupt completion (`return`, `break`, `continue`) and trap propagation,
|
||||
- determinism requirements that affect execution behavior.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- static typing or overload resolution rules,
|
||||
- GC algorithm internals,
|
||||
- exact IR shape or lowering passes,
|
||||
- diagnostics catalog wording,
|
||||
- the full PBX binary format.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
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`)
|
||||
3. `3. Core Syntax Specification.md`
|
||||
4. `4. Static Semantics Specification.md`
|
||||
5. This document
|
||||
|
||||
If a rule here conflicts with higher authority, it is invalid.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on, at minimum:
|
||||
|
||||
- `1. Language Charter.md`
|
||||
- `3. Core Syntax Specification.md`
|
||||
- `4. Static Semantics Specification.md`
|
||||
- `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
|
||||
This document is expected to be closed using decisions from:
|
||||
|
||||
- `docs/agendas/Dynamic Semantics - Execution Model Agenda.md`
|
||||
- `docs/agendas/Dynamic Semantics - Effect Surfaces Agenda.md`
|
||||
- `docs/agendas/Heap Model - Agenda.md`
|
||||
- `docs/agendas/Memory and Lifetime - Agenda.md`
|
||||
|
||||
## 5. Already-Settled Inputs
|
||||
|
||||
The following inputs are already fixed elsewhere and must not be contradicted here:
|
||||
|
||||
- PBS prioritizes determinism and compatibility over ergonomics when the two conflict.
|
||||
- `FRAME_SYNC`-based execution semantics remain preserved.
|
||||
- No non-deterministic async execution model is part of PBS v1.
|
||||
- Function application is defined on the canonical `apply` surface, with call sugar desugaring to `apply`.
|
||||
- `bind(context, fn_name)` evaluates the `context` expression once at bind time.
|
||||
- `switch` evaluates its selector expression once.
|
||||
- `optional T` function fallthrough yields `none`.
|
||||
- `result<E>` function fallthrough is a compile-time error.
|
||||
- `ok(...)` and `err(...)` are not ordinary first-class runtime constructors in v1 core.
|
||||
|
||||
## 6. Initial Section Targets
|
||||
|
||||
At minimum, the completed document should contain normative sections for:
|
||||
|
||||
1. execution model and runtime state,
|
||||
2. evaluation order by construct,
|
||||
3. block execution and abrupt completion,
|
||||
4. runtime semantics of `optional`,
|
||||
5. runtime semantics of `result<E>`,
|
||||
6. runtime semantics of `apply`, call sugar, and callable categories,
|
||||
7. branching semantics for `if` and `switch`,
|
||||
8. traps, determinism, and host-call interaction.
|
||||
|
||||
## 7. A Ver
|
||||
|
||||
The following items remain to be closed in agenda discussion before this document can be considered complete.
|
||||
|
||||
### 7.1 `Dynamic Semantics - Execution Model Agenda.md`
|
||||
|
||||
- Exact observable execution model for PBS v1.
|
||||
- Normative evaluation order for receivers, callees, arguments, selectors, and nested `apply`.
|
||||
- Exact abrupt-completion model for `return`, `break`, `continue`, `!`, and trap propagation.
|
||||
- Deterministic safepoint interaction around host calls, allocation-heavy operations, and loop back-edges.
|
||||
|
||||
### 7.2 `Dynamic Semantics - Effect Surfaces Agenda.md`
|
||||
|
||||
- Runtime value model of `optional` and `result<E>`.
|
||||
- Eagerness and single-evaluation guarantees for `some(...)`, `else`, `handle`, and `!`.
|
||||
- Runtime artifact and cost model of `bind(context, fn_name)`.
|
||||
- Exact runtime boundary between explicit status values and true traps.
|
||||
|
||||
### 7.3 `Heap Model - Agenda.md` and `Memory and Lifetime - Agenda.md`
|
||||
|
||||
- Which dynamic-semantic costs are observable and later diagnosable.
|
||||
- Which constructs may allocate, copy, retain, or cross the host-memory boundary during ordinary execution.
|
||||
- Which memory and safepoint facts belong in this document versus `Memory and Lifetime Specification.md`.
|
||||
|
||||
## 8. Non-Goals
|
||||
|
||||
- Reopening grammar or static typing unless current text is impossible to execute normatively.
|
||||
- Defining exact GC collection strategy.
|
||||
- Designing future async, actor, or scheduler models.
|
||||
- Specifying backend optimization policy.
|
||||
|
||||
## 9. Exit Criteria
|
||||
|
||||
This document is ready to move beyond skeleton status only when:
|
||||
|
||||
1. every runtime-observable core construct has a deterministic evaluation model,
|
||||
2. trap versus status-value behavior is explicit for every effect-bearing construct,
|
||||
3. host-call interaction rules are stated without relying on informal prose elsewhere,
|
||||
4. the document can drive runtime conformance tests without requiring agenda backfill,
|
||||
5. the document no longer depends on unresolved `A Ver` items for core v1 behavior.
|
||||
@ -1,72 +0,0 @@
|
||||
# PBS Spec Approval TODO
|
||||
|
||||
Status: Draft
|
||||
Purpose: checklist curto para decidir se a spec da PBS pode ser aprovada para seguir agora
|
||||
|
||||
## Blockers
|
||||
|
||||
- [X] Fechar o gate de prontidao para implementacao definido no charter para o escopo atual.
|
||||
Decisao: a aprovacao atual cobre apenas implementacao faseada de frontend (`parser`, `AST` e `binding` inicial).
|
||||
Isso fecha o gate apenas para esse escopo limitado e nao reclassifica a PBS como pronta para implementacao completa.
|
||||
Dynamic semantics, memory and lifetime, diagnostics, IR/lowering e conformance permanecem como trabalho aberto para fases posteriores.
|
||||
Referencia: `1. Language Charter.md`, secao "Required Spec Set Before Implementation".
|
||||
|
||||
- [X] Substituir o antigo modelo publico de `host fn` por `declare host` reservado a SDK/toolchain.
|
||||
Resolvido no nivel de charter, sintaxe e semantica estatica: bindings canonicos de host nao sao authorados pelo usuario comum, e superficies SDK usam `declare host` reservado.
|
||||
O contrato de PBX/load/runtime continua pendente para a futura Host ABI Binding specification.
|
||||
Referencias: `1. Language Charter.md`, `2. Governance and Versioning.md`, `3. Core Syntax Specification.md`, `4. Static Semantics Specification.md`, `5. Manifest, Stdlib, and SDK Resolution Specification.md`.
|
||||
|
||||
- [X] Fechar a spec normativa de manifest/module/package/stdlib.
|
||||
Resolvido com o modelo normativo de `project` e `module`, enderecamento canonico `@project:path/to/module`, `stdlib` como ambiente efetivo do build, `@sdk:*` e `@core:*` como project spaces reservados, interface modules PBS-like e atributos reservados de compile time como `[Host(...)]`.
|
||||
Referencias: `5. Manifest, Stdlib, and SDK Resolution Specification.md`, `6. Host ABI Binding and Loader Resolution Specification.md`.
|
||||
|
||||
- [X] Fechar o modelo semantico de `service` no core v1.
|
||||
Resolvido com `declare service` como singleton nominal por modulo, exportado via barrel, com metodos sem visibilidade independente e suporte a `implements Contract for Service using s`.
|
||||
Referencias: `3. Core Syntax Specification.md`, secao de `ServiceDecl`; `4. Static Semantics Specification.md`, callable categories.
|
||||
|
||||
- [X] Remover do core v1 ou especificar completamente as superficies que ja existem na gramatica mas ainda nao tem contrato suficiente.
|
||||
Itens visiveis hoje: `BoundedLit`, `GenericType`, `IndexSuffix` (`[]`) e `declare const` top-level.
|
||||
Se permanecerem no v1, precisam de semantica estatica/dinamica e diagnosticos claros.
|
||||
Referencia: `3. Core Syntax Specification.md`.
|
||||
|
||||
## Non-Blockers
|
||||
|
||||
- [x] Corrigir exemplos invalidos ou inconsistentes na spec estatica.
|
||||
Ha exemplos com `let` em escopo top-level para callbacks, mas top-level `let` e proibido pela sintaxe.
|
||||
Isso nao bloqueia a direcao da linguagem, mas deve ser corrigido para evitar ambiguidade.
|
||||
Referencias: `3. Core Syntax Specification.md`, `4. Static Semantics Specification.md`.
|
||||
|
||||
- [x] Consolidar exemplos canonicos para overload por retorno, `optional`, `result`, `bind`, `apply` e `switch`.
|
||||
A base conceitual esta boa; o ajuste aqui e editorial e de conformance, nao arquitetural.
|
||||
|
||||
- [X] Decidir se a implementacao pode comecar em modo faseado.
|
||||
Decisao tomada: permitir apenas parser/AST/binding inicial nesta etapa.
|
||||
Nao liberar ainda lowering, linker, host integration ou runtime behavior final.
|
||||
|
||||
## Pautas Dedicadas
|
||||
|
||||
- [X] Abrir pauta dedicada para dynamic semantics + memory and lifetime.
|
||||
Resolvido com uma pauta guarda-chuva de heap model e tres pautas filhas separando: modelo de execucao, superfices de efeito/controle e memory/lifetime.
|
||||
Isso reduz o acoplamento da discussao e permite fechar semantica observavel antes de fixar as regras normativas de heap e lifetime.
|
||||
Objetivo: fechar o modelo de execucao observavel, ordem de avaliacao, traps, efeitos sobre `optional`/`result`/`apply`/`bind`/`switch`, baseline GC, fronteira heap VM vs memoria do host e visibilidade de custo/alocacao.
|
||||
Resultado esperado: material para futura `Dynamic Semantics Specification` e `Memory and Lifetime Specification`.
|
||||
Referencias: `Heap Model - Agenda.md`, `Dynamic Semantics - Execution Model Agenda.md`, `Dynamic Semantics - Effect Surfaces Agenda.md`, `Memory and Lifetime - Agenda.md`.
|
||||
|
||||
- [X] Abrir pauta dedicada para validar se a `Host ABI Binding and Loader Resolution Specification` atual ja satisfaz o gate da fase seguinte ou se ainda precisa deixar de ser "Temporary".
|
||||
Decisao: suficiente para a proxima fase. O contrato atual de `declare host` -> metadata PBX -> loader -> syscall numerico ja esta estavel o bastante para nao bloquear a etapa posterior.
|
||||
Os pontos ainda abertos sao endurecimentos de formato/integracao, nao lacunas do contrato semantico principal.
|
||||
Referencias: `Host ABI Gate Validation Agenda.md`, `6. Host ABI Binding and Loader Resolution Specification.md`.
|
||||
|
||||
- [ ] FUTURO: abrir pauta de backend.
|
||||
Objetivo: tratar IR/lowering, linker, host integration, runtime behavior final e conformance somente depois de fechar o frontend e aparar as arestas da linguagem/spec.
|
||||
Resultado esperado: backlog da etapa de backend com precondicoes claras.
|
||||
Esta pauta nao bloqueia o frontend faseado atual.
|
||||
|
||||
## Decision Rule
|
||||
|
||||
Pode aprovar a PBS para seguir agora somente se a aprovacao significar:
|
||||
|
||||
- seguir com parser/frontend parcial, ou
|
||||
- seguir com fechamento das specs faltantes antes de runtime/lowering/linking.
|
||||
|
||||
Nao aprovar como spec fechada para implementacao completa enquanto houver blockers abertos.
|
||||
Loading…
x
Reference in New Issue
Block a user