Files
prometeu-studio/docs/compiler/pbs/specs/service-constants-and-runtime-math.md
T

5.5 KiB

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.

// @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

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:

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