feat(pbs): add service constants and runtime math integration
This commit is contained in:
+160
@@ -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.
|
||||
Reference in New Issue
Block a user