119 lines
5.5 KiB
Markdown
119 lines
5.5 KiB
Markdown
# 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)
|