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)
|
||||
Reference in New Issue
Block a user