feat(pbs): add service constants and runtime math integration
This commit is contained in:
@@ -0,0 +1,118 @@
|
||||
# Service constants and runtime math
|
||||
|
||||
Owner: compiler/pbs. Common catalog authority: compiler/general. Numeric behavior,
|
||||
exact identities, faults and virtual costs remain owned by the runtime.
|
||||
|
||||
## Services are the public namespaces
|
||||
|
||||
A service groups methods and immutable constants. The service barrel entry exports
|
||||
both; constants are not independently exported as top-level symbols. This applies
|
||||
to project code and SDK interfaces. Import aliases preserve the service identity.
|
||||
|
||||
```pbs
|
||||
// @app:settings/main.pbs; mod.barrel contains: pub service Settings;
|
||||
declare service Settings {
|
||||
declare const base: int = 40;
|
||||
declare const answer: int = base + 2;
|
||||
fn read() -> int { return answer; }
|
||||
}
|
||||
```
|
||||
|
||||
Consumers can import `Settings` and read `Settings.answer`. Constants use the same
|
||||
explicit type and constant-expression rules as top-level constants. Constant
|
||||
initializers cannot invoke functions. Qualified dependencies are permitted;
|
||||
unqualified names inside a constant initializer resolve in its owning service
|
||||
before the top-level constant scope. Duplicate constants, a constant sharing a
|
||||
method name, unresolved references, type mismatches and dependency cycles are
|
||||
compile-time errors. Assignments to constants are invalid.
|
||||
|
||||
Reading `Service.constant` materializes its value without creating a singleton or
|
||||
calling a getter. Ordinary methods retain existing service semantics. Constant
|
||||
members are included in completion, hover, definition and document symbols.
|
||||
|
||||
## SDK math services
|
||||
|
||||
```pbs
|
||||
import { math } from @sdk:math;
|
||||
import { mathf as numbers } from @sdk:mathf;
|
||||
|
||||
fn example(counter: long, angle: float) -> float {
|
||||
let bounded = math.clamp(counter, 0 as long, 100 as long);
|
||||
return math.to_float(bounded) + numbers.sin(angle) + numbers.pi;
|
||||
}
|
||||
```
|
||||
|
||||
`math` supplies `min`, `max`, `clamp` and `abs`, each with exact `int` and `long`
|
||||
overloads. `mathf` supplies `min`, `max`, `clamp`, `abs`, `floor`, `ceil`, `trunc`,
|
||||
`round`, `sqrt`, `sin`, `cos` and `atan2`, all with `float` arguments and results.
|
||||
`atan2` takes `(y, x)`; angles are radians. `float` is the runtime's finite binary64.
|
||||
|
||||
The six conversions are:
|
||||
|
||||
| Source call | Argument | Result |
|
||||
| --- | --- | --- |
|
||||
| `math.to_i64` | int | long |
|
||||
| `math.to_i32` | long | int |
|
||||
| `math.to_float` | int | float |
|
||||
| `math.to_float` | long | float |
|
||||
| `mathf.to_i32` | float | int |
|
||||
| `mathf.to_i64` | float | long |
|
||||
|
||||
These are 26 exact intrinsic signatures in total. There are no identity
|
||||
conversions. A mixed `int`/`long` call to `math.min` is invalid; the diagnostic
|
||||
requires explicit conversion. Existing contextual integer literal rules do not
|
||||
authorize implicit conversion of an already typed argument. Arithmetic opcode
|
||||
promotion rules are unchanged.
|
||||
|
||||
## Binding and materialization
|
||||
|
||||
SDK service method signatures may carry `[IntrinsicCall(name = "...", version = 1)]`
|
||||
and terminate with `;`. They have no PBS body or implicit numeric receiver in their
|
||||
runtime signature. This reserved declaration form is restricted to SDK interfaces.
|
||||
The generated callable loads its ordered arguments and invokes the exact common
|
||||
catalog identity. No frontend numeric ID/cost map or host math implementation is
|
||||
introduced. Normal compilation uses local versioned resources, not a runtime checkout.
|
||||
|
||||
SDK service constants may use `BuiltinConst` and omit their initializer:
|
||||
|
||||
```pbs
|
||||
declare service mathf {
|
||||
[BuiltinConst(target = "mathf", name = "pi", version = 1)]
|
||||
declare const pi: float;
|
||||
}
|
||||
```
|
||||
|
||||
`mathf.pi` and `mathf.tau` MUST materialize `IRVMBuiltinConstantDefinition` values:
|
||||
`0x400921FB54442D18` and `0x401921FB54442D18`. They are ordinary constant loads,
|
||||
never synthetic intrinsic calls or host-calculated values. A constant expression
|
||||
cannot replace a mathematical call: executable calls with literal arguments MUST
|
||||
remain executable, including when their result is discarded or optimization runs.
|
||||
|
||||
## Numeric conformance
|
||||
|
||||
The runtime contract specifies signed zeros, subnormals, finite overflow, checked
|
||||
conversions and ties-to-even rounding. For example, `sqrt(-0)` preserves -0,
|
||||
`abs(-0)` produces +0, `round(2.5)` produces 2 and `round(3.5)` produces 4. Negative
|
||||
nonzero sqrt and inverted clamp limits trap NUMERIC_DOMAIN. Integer abs(MIN) and
|
||||
out-of-range conversions trap NUMERIC_RANGE. The frontend MUST preserve these
|
||||
outcomes, argument order and virtual cycle accounting.
|
||||
|
||||
Integration evidence MUST begin with PBS source and end at the production VM.
|
||||
The checked-in independent corpus combines provider MPFR-verified rows with exact
|
||||
published contract examples. Tests require all 26 signatures, constants, mixed-type
|
||||
rejections, explicit conversions, signed zeros, subnormals, extrema, range/domain
|
||||
faults and atan2 axes. Both optimized and unoptimized emission are exercised.
|
||||
The harness compares exact result bits and trap codes, and checks each executed
|
||||
instruction's charge against the provider opcode contract and each numeric call
|
||||
against its independent fixture cost. A full-budget run must charge their sum.
|
||||
Constant-only probes additionally require exactly a load and root return cost.
|
||||
|
||||
Local qualification requires macOS/arm64 dev and release with runtime revision,
|
||||
configuration and catalog/oracle hashes recorded. macOS/x86_64 and Linux/x86_64
|
||||
remain separately pending; local results and cross-compilation do not qualify them.
|
||||
|
||||
## References
|
||||
|
||||
- [Common runtime catalog support](../../general/specs/runtime-catalog-support.md)
|
||||
- [Runtime numeric contract](../../../../../runtime/docs/specs/runtime/02d-gameplay-math-and-numeric-semantics.md)
|
||||
- [Production conformance harness](../../../../tools/pbx-conformance/README.md)
|
||||
@@ -192,7 +192,7 @@ Rules:
|
||||
- A `host` barrel entry must resolve to exactly one top-level `declare host` declaration in module scope.
|
||||
- A `struct` barrel entry governs the visibility of the struct declaration and of all methods declared directly in that struct body.
|
||||
- A `host` barrel entry governs the visibility of the host declaration and of all method signatures declared directly in that host body.
|
||||
- A `service` barrel entry governs the visibility of the service declaration, its canonical singleton value, and all methods declared directly in that service body.
|
||||
- A `service` barrel entry governs the visibility of the service declaration, its canonical singleton value, and all methods and constants declared directly in that service body.
|
||||
- A `global` barrel entry governs visibility of one top-level `declare global` declaration.
|
||||
- Methods declared inside a `struct`, `host`, or `service` are never exported independently through `mod.barrel`.
|
||||
|
||||
@@ -371,18 +371,19 @@ Function types use `Fn(T1, T2) -> R`. Lambdas use `fn [captures](name: Type) ->
|
||||
```ebnf
|
||||
ServiceDecl ::= 'declare' 'service' Identifier ServiceBody
|
||||
ServiceBody ::= '{' ServiceMember* '}'
|
||||
ServiceMember ::= 'fn' Identifier ParamList ReturnAnn? Block
|
||||
ServiceMember ::= 'fn' Identifier ParamList ReturnAnn? Block | ConstDecl
|
||||
// SDK only: an IntrinsicCall-attributed service signature may end in ';'.
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- `declare service Name { ... }` declares a nominal service type together with its canonical module-owned singleton value `Name`.
|
||||
- A service body contains only method declarations.
|
||||
- A service body contains method declarations and `declare const` members. SDK service intrinsic signatures may terminate with `;`; see [Service constants and runtime math](../../../compiler/pbs/specs/service-constants-and-runtime-math.md).
|
||||
- Service methods have an implicit receiver binding `this` of type `Self` and do not declare `this: Self` explicitly.
|
||||
- Services do not declare fields.
|
||||
- Services do not declare `ctor`.
|
||||
- Services are never constructed with `new`.
|
||||
- Service method visibility follows the `service` entry for that declaration in `mod.barrel`; service methods are never exported independently.
|
||||
- Service method visibility follows the `service` entry for that declaration in `mod.barrel`; service methods and constants are never exported independently.
|
||||
|
||||
### 7.4 Functions
|
||||
|
||||
|
||||
@@ -96,7 +96,7 @@ Rules:
|
||||
- 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.
|
||||
- `IntrinsicCall` is valid on a method signature inside a reserved `declare builtin type` body or an SDK service body. SDK service signatures have no implementation body and bind their exact declared argument/result carriers to the common intrinsic catalog.
|
||||
- Builtin metadata is consumed by the compiler during VM-owned builtin and intrinsic lowering rather than by host-binding lowering.
|
||||
- `Init` and `Frame` are consumed by lifecycle analysis and lowering rather than by ordinary runtime reflection.
|
||||
- `InitAllowed` is consumed by init-time host-admission analysis and does not become ordinary userland metadata.
|
||||
@@ -349,6 +349,11 @@ Rules:
|
||||
|
||||
### 3.6 Structs, services, methods, and contracts
|
||||
|
||||
Service constants follow [Service constants and runtime math](../../../compiler/pbs/specs/service-constants-and-runtime-math.md).
|
||||
They are immutable members exported with their service. Qualified constant reads
|
||||
materialize the constant without constructing a singleton or invoking a method.
|
||||
|
||||
|
||||
Rules:
|
||||
|
||||
- Struct values are heap-backed reference values in v1 core.
|
||||
|
||||
Reference in New Issue
Block a user