feat(pbs): add service constants and runtime math integration

This commit is contained in:
2026-10-17 11:21:58 +01:00
parent 2a418085d2
commit d1e9259085
32 changed files with 1117 additions and 40 deletions
@@ -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.