Files
prometeu-studio/discussion/lessons/DSC-0081-pbs-runtime-math-integration/LSN-0085-service-constants-and-source-math-conformance.md
T

8.3 KiB

id, ticket, title, created, tags
id ticket title created tags
LSN-0085 pbs-runtime-math-integration Service constants and source-to-runtime math conformance 2026-10-17
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.

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:

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:

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

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.