From 13c0ababbb0ff8623eb4df671729a891788b1ab1 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Thu, 15 Oct 2026 15:48:50 +0100 Subject: [PATCH] feat(pbs): align typed values and Pad input facade --- README.md | 4 +- .../LSN-0081-pbs-typed-values-and-input.md | 83 +++++ .../general/specs/runtime-catalog-support.md | 11 + ...put-and-existing-type-runtime-alignment.md | 136 +++++++ .../pbs/12. Diagnostics Specification.md | 4 + .../13. Lowering IRBackend Specification.md | 4 + .../pbs/4. Static Semantics Specification.md | 6 +- ...rinsics and Builtin Types Specification.md | 14 +- .../pbs/9. Dynamic Semantics Specification.md | 4 + ...CP Tools and Project Knowledge Contract.md | 4 +- .../app/runtime/HeadlessMcpDesktopTest.java | 6 +- .../prometeu-frontend-pbs/build.gradle.kts | 4 +- .../compiler/PBSSemanticTokenProvider.java | 2 +- .../compiler/pbs/PbsFrontendCompiler.java | 2 +- .../linking/PbsModuleVisibilityValidator.java | 8 +- .../lowering/PbsExecutableBodyLowerer.java | 245 +++++++++--- .../PbsExecutableCallsiteEmitter.java | 16 +- .../PbsExecutableLoweringContext.java | 4 + .../lowering/PbsExecutableLoweringModels.java | 4 +- .../PbsExecutableLoweringService.java | 13 +- .../PbsExecutableMetadataIndexFactory.java | 1 + .../lowering/PbsExecutableStackAnalyzer.java | 3 +- .../pbs/lowering/PbsRuntimeTypes.java | 92 +++++ .../pbs/parser/PbsExprLiteralSupport.java | 1 + .../compiler/pbs/parser/PbsExprParser.java | 5 + .../semantics/PbsBuiltinLayoutResolver.java | 2 +- .../PbsDeclarationSemanticsValidator.java | 12 + .../semantics/PbsEditorialSupportService.java | 2 +- .../PbsFlowCallableResolutionAnalyzer.java | 30 +- .../pbs/semantics/PbsFlowSemanticSupport.java | 8 + .../PbsFlowStructuralExpressionAnalyzer.java | 31 +- .../pbs/semantics/PbsFlowTypeOps.java | 10 +- .../PbsInlineHintSurfaceFormatter.java | 2 +- .../PbsImportedSemanticContextService.java | 2 +- .../game/stdlib/1/core/color/main.pbs | 14 +- .../game/stdlib/1/sdk/input/main.pbs | 350 ++++++++++-------- .../game/stdlib/1/sdk/input/mod.barrel | 8 +- .../PbsGateUSdkInterfaceConformanceTest.java | 19 +- .../PbsSemanticPresentationContractTest.java | 6 +- .../services/PBSFrontendPhaseServiceTest.java | 97 ++--- .../prometeu-build-pipeline/build.gradle.kts | 1 + .../backend/irvm/LowerToIRVMService.java | 22 ++ .../backend/irvm/PbsRuntimeAlignmentTest.java | 124 +++++++ .../models/IRBackendExecutableFunction.java | 10 +- .../CompilerLanguageServiceBridgeTest.java | 4 +- test-projects/main/src/main.pbs | 16 +- tools/pbx-conformance/README.md | 30 +- tools/pbx-conformance/main.rs | 129 +++++++ 48 files changed, 1251 insertions(+), 354 deletions(-) create mode 100644 discussion/lessons/DSC-0076-pbs-existing-types-input-alignment/LSN-0081-pbs-typed-values-and-input.md create mode 100644 docs/compiler/pbs/specs/input-and-existing-type-runtime-alignment.md create mode 100644 prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsRuntimeTypes.java create mode 100644 prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/backend/irvm/PbsRuntimeAlignmentTest.java diff --git a/README.md b/README.md index 69f405ef..17ff5d5f 100644 --- a/README.md +++ b/README.md @@ -189,8 +189,8 @@ acknowledge completed cleanup; control stays locked until cleanup is confirmed. The following findings are recorded for investigation after implementation; they are not considered fixed by the passing integration tests: -- **PBS/LSP SDK navigation:** definition lookup for the bundled SDK's `Input.pad()` - currently returns no location. Project-source navigation and indexed SDK reference +- **PBS/LSP SDK navigation:** the historical probe of the former `Input.pad()` + API returned no location; the current input API is `Pad`/`Button` and `Touch`. Project-source navigation and indexed SDK reference reads work. Investigate SDK symbol resolution separately; an empty definition result is not evidence of missing runtime support or permission to edit the SDK. - **Build tooling:** the validation environment's JDK 25 triggers Kotlin's target-24 diff --git a/discussion/lessons/DSC-0076-pbs-existing-types-input-alignment/LSN-0081-pbs-typed-values-and-input.md b/discussion/lessons/DSC-0076-pbs-existing-types-input-alignment/LSN-0081-pbs-typed-values-and-input.md new file mode 100644 index 00000000..37f74333 --- /dev/null +++ b/discussion/lessons/DSC-0076-pbs-existing-types-input-alignment/LSN-0081-pbs-typed-values-and-input.md @@ -0,0 +1,83 @@ +--- +id: LSN-0081 +ticket: pbs-existing-types-input-alignment +title: PBS Typed Values and Direct Input Queries +created: 2026-10-15 +tags: [compiler/pbs, runtime-integration] +--- + +## Context and result + +Owner: **compiler/pbs**, with shared compiler IR and installed Studio consumer propagation. DSC-0076 (AGD-0078, accepted DEC-0065, completed PLN-0144) aligned existing PBS values and input with the published runtime. The original object chain exposed intermediate input objects that had no useful runtime representation. PBS also omitted exact executable function metadata, causing the full installed example to fail at `Gfx.clear` under the shared typed registry validator. + +The delivered implementation replaces those chains, produces typed function metadata, preserves complete value groups, and passes both actual-runtime execution and the full installed knowledge gate. The completed agenda, decision and plan were removed through framework housekeeping; this lesson preserves their implementation evidence. + +## Public selectors and direct runtime endpoints + +Use a nominal selector value and a public query: + +```pbs +let button = Button.A; +let pressed = Pad.pressed(button); +let frames: long = Pad.hold(button); +let x: long = Touch.x(); +``` + +`Button` has twelve cases: Up, Down, Left, Right, A, B, X, Y, L, R, Start, Select. The four Pad operations are pressed, released, down and hold. Each public function dispatches through an exhaustive enum switch to one of the 48 zero-argument LowPad endpoints. For example, `Pad.pressed(Button.A)` reaches `LowPad.a_pressed()`, bound to `input.pad.a.pressed`. The selector is evaluated once and only the selected endpoint reads input. Obtaining or passing a Button has no input effect. Constant specialization is unnecessary for correctness. + +Touch exposes pressed/released/down as Bool and hold/x/y as Int64. The implementation uses existing runtime endpoints, with no ABI or lifecycle redesign. `Input.pad().a()` and aliases of its intermediate object are removed; import diagnostics explain the replacement. Strings, integers and unrelated enums cannot substitute for Button. The source type remains nominal even though its executable carrier is Int32. + +## Exact values must survive frontend lowering + +The explicitly accepted integer mapping is `int` to Int32 and `long` to Int64. Integer literals default to int; an explicit long context admits Int64 literals. Conversions use existing `as` syntax. Variables of different numeric widths require explicit conversion. Pad.hold and Touch.hold/x/y therefore return long. + +`PbsRuntimeTypes` connects source types and declarations to canonical registry types and exact parameter/result groups. Callable lookup includes arity so overloaded SDK functions do not overwrite each other's signatures. Existing unsupported source types retain their previous executable boundary; shared strict metadata validation was not relaxed to admit them. + +Locals, parameters, calls and returns carry whole groups: vec2 uses two Float slots and pixel uses two Int64 coordinates plus color. Slot count alone never establishes type identity. Builtin constants are resolved through the shared constant catalog: vec2.zero materializes two Float zero values, without inventing a one-result intrinsic. The backend validates the declared group width against the catalog materialization. + +Named application first evaluates expressions in source order, stores their complete groups, and then loads those values in parameter order. The runtime proof calls `combine apply (y: Probe.y(), x: Probe.x())`: effects record Y then X while combine receives x then y. Its final oracle is 211020. + +## Qualification evidence + +Qualification date: 2026-10-15; platform: Darwin arm64. Studio base revision: `603ed012272b137361ba618f6887f015f7317803` plus this delivery's working-tree changes. Runtime revision: `f7d7c167531bb662a1af9d73fc326bb476bf8aa7`. The runtime checkout was not modified. Default Gradle configuration; controlled input and no-platform configurations in the real runtime harness. + +```sh +./gradlew :prometeu-compiler:frontends:prometeu-frontend-pbs:test :prometeu-compiler:prometeu-build-pipeline:test :prometeu-compiler:prometeu-frontend-api:test :prometeu-lsp:prometeu-lsp-v1:test :prometeu-app:installedKnowledgeTest --console=plain +CARGO_TARGET_DIR=/tmp/pln144-cargo-target python3 tools/pbx-conformance/run.py --runtime ../runtime +git diff --check +discussion validate +``` + +| Suite | Passed | Existing skips | Failures/errors | +| --- | ---: | ---: | ---: | +| PBS frontend | 246 | 0 | 0 | +| Build pipeline | 179 | 12 | 0 | +| Frontend API | 28 | 0 | 0 | +| LSP | 38 | 1 | 0 | +| Full installed knowledge | 2 | 0 | 0 | + +`PbsRuntimeAlignmentTest` generates 114 PBX programs through the production compiler, lowerer, emitter and preload verifier. The actual runtime harness loads and executes all of them: + +- 48 Pad combinations using a local Button passed through a typed function, plus 48 direct constant combinations; controlled input asserts the exact returned value and exactly one selected read. +- All six Touch queries, including signed x/y values. All 102 input programs are also executed without a platform and must trap with TRAP_UNAVAILABLE. +- Twelve value/fault programs cover Int32, Int64, Float, String, color, vec2, pixel, tuple returns, named evaluation order, Int32 wrapping, checked narrowing and division by zero. Bool is covered by input queries. Registry default layouts are checked for all eight existing canonical value types. + +Frontend negatives cover invalid Button arguments, mixed int/long variables, literal overflow and migration diagnostics. Existing shared tests continue to cover wrong typed signatures, stale touch signatures, unreachable removed IDs, and lifecycle assembly. The original full installed failure at `Gfx.clear` is fixed. This does not claim completion of the separate Studio desktop integration agenda. Existing upstream fault-schema gaps (LifecycleRole/NonFiniteValue) remain explicitly reported by the shared harness, without suppressing this delivery's oracles. + +## Pitfalls and reusable patterns + +- A dotted builtin target is already a complete catalog name: use `input.pad.a.pressed`, not a partial `a.pressed` that silently loses its owner. +- A numeric literal's context must reach calls, returns and constructors; parsing an integer into a wide host value is insufficient to give it an Int64 guest type. +- Handle the signed minimum literal before rejecting its positive magnitude. A positive value above Int64 maximum must produce a diagnostic, not become zero. +- Preserve catalog overflow behavior: Int32 addition wraps; out-of-range narrowing traps with TRAP_NUMERIC_RANGE. Do not assume all numeric operations trap on overflow. +- A switch can omit its final comparison only when exhaustive coverage is proven. Non-exhaustive statement switches must not execute an unmatched final arm. +- A catalog or structural test alone cannot prove a frontend consumer. Generate PBS programs, run the real VM, and keep the full installed example as an independent gate. +- Publish the focused canonical spec in installed knowledge as well as in the checkout. SDK exports, diagnostics, language services and examples must migrate together. + +## References + +- [Normative PBS input and existing-value contract](../../../docs/compiler/pbs/specs/input-and-existing-type-runtime-alignment.md) +- [Shared runtime catalog contract](../../../docs/compiler/general/specs/runtime-catalog-support.md) +- [Typed registry and PBX contract](../../../docs/compiler/general/specs/typed-registry-and-pbx-v0.md) +- [PBS source-to-PBX qualification](../../../prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/backend/irvm/PbsRuntimeAlignmentTest.java) +- [Actual-runtime harness instructions](../../../tools/pbx-conformance/README.md) diff --git a/docs/compiler/general/specs/runtime-catalog-support.md b/docs/compiler/general/specs/runtime-catalog-support.md index 707ab614..fddfba65 100644 --- a/docs/compiler/general/specs/runtime-catalog-support.md +++ b/docs/compiler/general/specs/runtime-catalog-support.md @@ -93,3 +93,14 @@ installed-runtime qualification remain separate consumer claims. See [typed common Registry and PBX v0](typed-registry-and-pbx-v0.md) for the frontend/backend boundary and [mirror policy](../../../vm-arch/README.md) for explicit verification commands. + + +## PBS consumer + +The [PBS input and value alignment contract](../../pbs/specs/input-and-existing-type-runtime-alignment.md) +requires typed Pad/Button dispatch, direct LowPad endpoints and complete builtin +value groups. Frontend numeric literal and builtin-constant operations retain +explicit identity and width; common lowering resolves constant groups against +`IRVMBuiltinConstantDefinition` and checks the declared result width. PBS does +not introduce another catalog. Source execution and the full installed example +are separate consumer gates beyond CSV parity. diff --git a/docs/compiler/pbs/specs/input-and-existing-type-runtime-alignment.md b/docs/compiler/pbs/specs/input-and-existing-type-runtime-alignment.md new file mode 100644 index 00000000..bc8d6426 --- /dev/null +++ b/docs/compiler/pbs/specs/input-and-existing-type-runtime-alignment.md @@ -0,0 +1,136 @@ +# PBS input and existing value runtime alignment + +Status: normative. Owner: `compiler/pbs`. Common ABI authority: +[typed Registry/PBX](../../general/specs/typed-registry-and-pbx-v0.md) and +[runtime catalogs](../../general/specs/runtime-catalog-support.md). + +## Source types and exact carriers + +| PBS source | Runtime identity | Ordered slots | +| --- | --- | --- | +| `int` | Int32 | Int32 | +| `long` | Int64 | Int64 | +| `float` | Float | Float (binary64) | +| `bool` | Bool | Bool | +| `str` | String | String | +| builtin `color` shell | color | Int64 constrained to RGBA8888 | +| builtin `vec2` shell | vec2 | Float x, Float y | +| builtin `pixel` shell | pixel | Int64 x, Int64 y, Int64 color | + +The canonical builtin metadata determines a shell's identity; its source name +is not an ABI lookup rule. Equal widths do not permit substitution. Function +metadata MUST declare ordered parameter and result identities. Slot counts are +checked caches derived from those identities. Calls, locals and returns MUST +preserve entire value groups. A vec2 is one logical value with two slots; +a named output tuple is a fixed sequence of logical results, not a heap object. + +`int` and `long` are distinct. Integer literals default to `int`; explicit +`long` contexts (annotations, parameters and results) validate literals in the +Int64 range and materialize them with that carrier. Out-of-range literals MUST +be diagnosed, never replaced by zero. A typed variable does not change type +because it appears in another expected context. Mixed int/long operations +require an explicit conversion. Existing `as` syntax expresses conversion: + +```pbs +let frames: long = 2147483648; +let offset: int = 10; +let wide = offset as long; +let narrow = frames as int; +``` + +The final conversion faults if its value is outside Int32 range. Numeric +conversions use published math/mathf conversion intrinsics, without adding +math service facades. Int32/Int64 arithmetic preserves runtime wrapping; +Float overflow and range-invalid conversions preserve runtime faults. +Defaults are owned by the runtime storage contract: numeric zero, Float +0, +Bool false, nullable String null, transparent color, zero vec2 and zero pixel. +This does not introduce implicit source-variable initialization: VM locals +start null and PBS definite-assignment rules still apply. NaN/infinity are not +valid guest numeric defaults. + +## Public input API + +Import `Pad`, `Button` and `Touch` from `@sdk:input`. Button is a closed nominal +PBS enum with cases Up, Down, Left, Right, A, B, X, Y, L, R, Start and Select. +It identifies a button; it does not contain input state or perform a query. +Locals and typed function parameters may carry Button values, including values +selected during execution. Strings, integer indices and unrelated enums are +not valid Button arguments. + +| Public operation | Result | +| --- | --- | +| `Pad.pressed(button: Button)` | bool | +| `Pad.released(button: Button)` | bool | +| `Pad.down(button: Button)` | bool | +| `Pad.hold(button: Button)` | long, held logical frames | +| `Touch.pressed()`, `Touch.released()`, `Touch.down()` | bool | +| `Touch.hold()` | long, held logical frames | +| `Touch.x()`, `Touch.y()` | long | + +```pbs +import { Pad, Button, Touch } from @sdk:input; + +fn jump(button: Button) -> bool { + return Pad.pressed(button); +} + +fn held() -> long { + let jump_button = Button.A; + return Pad.hold(jump_button); +} +``` + +Pad dispatches to `LowPad.