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,160 @@
---
id: LSN-0085
ticket: pbs-runtime-math-integration
title: Service constants and source-to-runtime math conformance
created: 2026-10-17
tags: [runtime-integration]
---
## Original problem and ownership
Owner: compiler/pbs. Supporting contract: compiler/general; runtime numeric
semantics remain owned by the VM. This lesson consolidates accepted DEC-0069
and implemented PLN-0148 from AGD-0083 / DSC-0081.
The common compiler already represented all runtime math identities and canonical
constants. That did not make them usable from PBS source. The remaining work was
service syntax, exact overload resolution, SDK publication, constant reads and
source-to-production execution evidence.
## Consolidated decision
The user explicitly chose services themselves as namespaces. Services export
constants alongside methods; there is no separate namespace declaration or new
numeric builtin type. The same capability applies to project and SDK services.
`math` exposes exact int/long overloads and `mathf` exposes Float functions.
Conversions between numeric carriers are explicit. The compiler consumes its
existing manually ported, independently checked common catalog. It does not query
a runtime checkout during normal compilation or duplicate the VM's math backend.
Pi and tau use canonical builtin constant materialization, not zero-argument
intrinsics. Mathematical calls retain their faults and costs even with literal
arguments. Qualification must start with source and compare exact bits, faults
and cycles on a named runtime build.
## Final implementation
The service AST retains constant declarations with their owner. Parser, declaration
checks, dependency/cycle validation, type resolution, lowering and editor member
surfaces carry them through. Constants are immutable, exported with their service,
and available through qualified reads and import aliases. Within the owner, a
constant reference takes precedence over a same-named global; locals retain their
normal lexical precedence. Explicit long annotations contextually type integer
constant literals, without converting references to already typed int constants.
SDK services at `@sdk:math` and `@sdk:mathf` bind their 26 exact signatures through
reserved IntrinsicCall metadata. Each generated callable loads its declared
arguments, calls the common catalog identity and returns. Consequently its normal
CALL/GET_LOCAL/RET overhead is distinct from the intrinsic's own charge. Imports
with aliases resolve to the original provider callable identity.
BuiltinConst metadata on service constants records the qualified source name.
The existing BUILTIN_CONST instruction materializes `IRVMBuiltinConstantDefinition`.
Pi and tau retain bits `0x400921FB54442D18` and `0x401921FB54442D18`. A qualified
constant read does not construct a singleton or call a getter. Constant-only
probes cost six cycles: an ordinary load plus the root return.
```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;
}
```
General service constants use ordinary source expressions:
```pbs
declare service Settings {
declare const base: int = 40;
declare const answer: int = base + 2;
fn read() -> int { return answer; }
}
```
## Qualification and reproducibility
Runtime revision: `f7d7c167531bb662a1af9d73fc326bb476bf8aa7`, unchanged clean checkout.
Platform: macOS 27.0.1 arm64. Production harness profiles: dev and release;
VM feature: resource-diagnostics, default load limits, NONE capabilities for math.
Java build uses JDK 25; installed launcher uses the existing distribution runtime.
The corpus contains 261 independent numeric cases, emitted both normally and with
the PBS/common optimizer enabled: 522 mandatory cases in each runtime profile.
It combines the first 240 scalar provider fixture rows with exact published
contract examples, removing duplicates. It covers all 26 signatures, signed zeros,
subnormals, finite extrema, checked conversions, ties-to-even, invalid clamp,
negative sqrt, abs(MIN) and atan2 axes. Additional probes cover pi/tau, direct
literal sin, ordinary int/long constants, dependencies and a real project with
SDK imports, service aliases and exported project constants.
Every numeric case checks the selected intrinsic identity, exactly one retained
call, exact result bits or fault code, and per-instruction charging. Numeric costs
come from independent fixture rows; other instruction costs come from the provider
ISA contract. A full-budget execution must charge the sum of those steps.
Optimized and unoptimized versions must charge identical totals.
| Gate | Result |
| --- | --- |
| PBS frontend suite | 249 tests passed |
| Common backend suite | 175 passed, 12 pre-existing skips |
| Selected architecture/source suites | Math, existing values/input, structured values and closures passed |
| Installed knowledge | Both gates passed; packaged example imports math and aliased mathf |
| Complete production harness | Passed in dev and release, including 522 math vectors per profile |
| Workflow and patch integrity | discussion validate and git diff --check passed |
| Evidence artifact | SHA-256 |
| --- | --- |
| Runtime Cargo.lock | cffad9ed62f38a591538abd81dd39270d6022397342c8189f4ac6c7baaa8e795 |
| INTRINSICS.csv | 0c1bb78a9b81d1e3480ef5713f3d70f0b06772a7dfab2fd00c1f0a6364f98daa |
| BUILTIN_CONSTANTS.csv | e407e4718127aa7ef7b1097b5b4b67d86dd979235e73a551a7c36b628cddc039 |
| Provider numeric-conformance.tsv | 5536ee18cadaf32e3719b0e8d541dfcf1a84a49ea978a702101547c5ccdee3fe |
| Consumer numeric-source.tsv | 95067131dbc7a4252352424ee52f4b9215c8d8ecd80124218a38819211ff7ccb |
Reproduce from the Studio root:
```sh
./gradlew :prometeu-compiler:frontends:prometeu-frontend-pbs:test :prometeu-compiler:prometeu-build-pipeline:test
./gradlew :prometeu-architecture-tests:test --tests '*PbsRuntimeMathTest' --tests '*PbsRuntimeAlignmentTest' --tests '*PbsStructuredValuesTest' --tests '*PbsClosuresTest'
./gradlew :prometeu-app:installedKnowledgeTest
python3 tools/pbx-conformance/run.py --runtime ../runtime
python3 tools/pbx-conformance/run.py --runtime ../runtime --release
```
Optional CARGO_TARGET_DIR can preserve harness compilation artifacts in a temporary
directory. The script never writes to the runtime checkout. Use --math-only for
the complete math subset; it still rejects missing mandatory math fixtures.
Qualification on macOS/x86_64 and Linux/x86_64 remains pending. This delivery does
not qualify those hosts, installed-runtime deployment or a complete reference game.
The existing provider schema gaps for LifecycleRole and NonFiniteValue remain
explicitly reported by the full harness; original payloads are preserved.
## Pitfalls and maintenance
- Catalog parity is not source integration. Test the facade, imports, overloads,
actual emission and production VM together.
- Constants are not nullary intrinsics. Preserve their canonical bits and ordinary
load costs independently of method binding.
- A service alias changes source spelling, not the provider callable identity.
- Preserve constant ownership during expansion. Caller locals/globals must not
accidentally change the lexical meaning of a constant's initializer.
- Float equality hides the sign of zero. Conformance must compare raw bits.
- Intrinsic costs exclude wrapper and argument-producing instructions. Charge and
compare the complete program without treating virtual cycles as CPU timings.
- Extend the corpus and its mandatory count together. Never silently skip absent
fixtures, accept host tolerances, or replace provider oracles with compiler output.
## References
- [Service constants and runtime math specification](../../../docs/compiler/pbs/specs/service-constants-and-runtime-math.md)
- [Runtime catalog policy](../../../docs/compiler/general/specs/runtime-catalog-support.md)
- [Production harness](../../../tools/pbx-conformance/README.md)
- [Catalog-port lesson](../DSC-0075-compiler-runtime-catalog-parity/LSN-0080-manual-runtime-catalog-port-and-conformance.md)
- Historical execution artifacts: DEC-0069 and PLN-0148, removed by CLI housekeeping after completion.
Tooling note: the CLI has no lesson-allocation command. LSN-0085 was selected from
the next counter; CLI housekeeping registers the lesson and advances that counter.