feat(pbs): add concrete generic structs and free functions

This commit is contained in:
2026-10-22 14:42:38 +01:00
parent 240216170c
commit 76a8b074e8
52 changed files with 3285 additions and 103 deletions
@@ -82,9 +82,12 @@ it does not replace or introduce a lifecycle feature.
The 48 provider oracle rows cover six seeds and eight draws. Projecting both
integer and Float outputs, with optimization off/on, produces 192 fixtures.
Another 34 paired fixtures cover aliases, independent objects, mixed/discarded
operations, named/positional effects, storage/captures, limits, faults and GC.
Together with real imports this is **227 mandatory fixtures per runtime profile**.
Another 30 source fixtures cover aliases, independent objects, mixed/discarded
operations, named/positional effects, storage/captures, limits, faults and GC. Four
controlled provider fixtures cover null and typed-null carriers. Together with real
imports this is **223 source fixtures plus four controlled provider fixtures**.
The DEC-0073 follow-up requalified this revised corpus in the dev profile; the
original debug/release evidence below describes the earlier source corpus.
Each of the 226 callable fixtures executes with single-step budgets and twice
with full budgets to compare exact bits/faults, call charges and total cycles.
The runner checks oracle byte equality against the selected runtime.
@@ -95,8 +98,11 @@ Random objects are reclaimed, array, field and closure roots still draw the
expected shared sequence. The source corpus also exercises a genuine rejected
PCG word followed by acceptance, charging range 20 cycles.
PBS has no public null or Dynamic type. A source struct constructor that leaves
a Random field at its runtime default provides a null reference for tests.
PBS has no public null or Dynamic type. Following the explicit DEC-0073
clarification, every completing constructor path initializes every field. Null
coverage uses a controlled provider fixture: compile a fully initialized Random
field, then suppress its unique field store in test bytecode to exercise the provider
reference default.
Storing it in a typed array preserves a present Dynamic tag and exact TypeId;
extracting it then drawing traps NULL_REFERENCE. This must not be confused with
an empty array slot. Existing global-initializer restrictions are unchanged.
@@ -104,5 +104,11 @@
"macOS arm64 only",
"Reference-game and installed-runtime process qualification excluded",
"Existing explicit provider schema gaps LifecycleRole and NonFiniteValue retained"
]
],
"follow_up_2026_10_22": {
"discussion": "DSC-0094",
"scope": "Explicitly authorized complete PBS constructor field initialization; revise null fixtures to controlled provider injection",
"qualification": "227 Random fixtures passed on macOS arm64 dev; prior release evidence describes the original corpus",
"evidence": "../DSC-0094-pbs-generic-structs/evidence.json"
}
}
@@ -0,0 +1,202 @@
---
id: LSN-0089
ticket: pbs-generic-structs
title: Concrete Generic State and Bodies in PBS
created: 2026-10-22
tags: [compiler-pbs, generic-structs, generic-functions, nominal-identity, runtime-conformance]
---
## Original problem and final result
Owner: `compiler/pbs`. Studio/LSP receives source projections; the common backend
and runtime continue to execute concrete types and functions. DSC-0094 implemented
accepted DEC-0073 through PLN-0152, covering requirements R1–R14. The disposable
workflow artifacts are removed by housekeeping; specifications remain normative.
Generic contracts could describe a strategy but could not provide parameterized
state or algorithms. PBS now supports generic structs, owner-dependent methods
and constructors, restricted owner-bound implementations, and named generic free
functions with explicit arguments. SDK and project code use the same frontend
mechanism. No runtime source, opcode, descriptor category or PBX format changed.
```pbs
declare struct Box<T>(value: T) {
ctor make(value: T) { this.value = value; }
fn get() -> T { return this.value; }
}
declare contract Reader<T> { fn read() -> T; }
implements<T> Reader<T> for Box<T> using box {
fn read() -> T { return box.get(); }
}
fn read<T>(reader: Reader<T>) -> T { return reader.read(); }
fn example() -> int {
let box = new Box<int>.make(42);
let reader: Reader<int> = box;
let invoke: Fn(Reader<int>) -> int = read<int>;
return invoke(reader);
}
```
The combined program executes through production PBX and the provider VM. A
separate multi-module variant uses aliases, reexports and private definition-side
helpers while preserving the result 42.
## Decisions that shape the implementation
Application identity is source nominal origin plus ordered canonical logical
arguments. It is independent of layout width and presentation. Two homonymous
Enemy declarations must yield distinct Box<Enemy> types; two aliases of the same
declaration share one application. Phantom arguments also remain significant.
Function applications preserve their declaration and argument identity even when
several targets share a compatible structural Fn descriptor.
Definition scope and argument scope are separate. A parameter is bound by its
declaration/binder and position. Resolve the caller's arguments before constructing
the callee's substitution environment. Private helpers remain in their definition
module. Generated imports connect concrete instances without publishing helpers
as source exports. Explicit barrels retain the template and its ordered parameters.
Explicit struct construction provides its own arguments. Diamond and omission
require an existing expected application; values do not infer T. Generic functions
always require explicit arguments, including when converted to Fn. Explicit
applications filter generic overloads by type arity; ordinary calls use ordinary
overloads. Renaming binders alone does not create a new overload.
Concrete specialization increases frontend work and potentially image size, but
reuses the established runtime value model. It avoids requiring a Dynamic generic
argument ABI or adapter objects. Existing Array packing still follows Array rules.
No performance or byte-for-byte image equivalence is promised.
## Checking and materializing the graph
`PbsGenericInstantiation` owns the interacting concrete graph. Shared
`PbsContractTypes`, `PbsInstantiationBudget` and application provenance support
contracts, structs and functions. Register anchors before traversing dependencies:
revisiting the same application closes a finite graph, whereas requesting new
applications indefinitely produces a bounded expansion diagnostic.
The current frontend budget bounds depth at 256, instances at 65,536, work at
1,048,576 visits and accounted specialization storage at 64 MiB. These analysis
ceilings do not enlarge provider admission or execution limits.
Validation has two distinct purposes. Symbolic capability checking prevents T
from gaining arithmetic, comparison, members or construction from a chosen concrete
argument. Opaque nominal witnesses also run unused template bodies through the
ordinary declaration and flow validators, catching ordinary errors such as wrong
returns and incomplete constructors. Dependency shapes provide their declared
capabilities without recursively executing every unused template family.
Each required concrete owner then validates fields, constructors and every method,
including uncalled methods. Substitute entire bodies, annotations, nested calls,
constructions, lambdas and captures. Revalidate positions after substitution:
Box<optional int> can have a T field, but array<T> cannot accept that substitution.
Reject overloads that collapse after substitution; never prefer an int overload
over set(T) merely because T became int.
Owner-bound implementation rules bind every parameter through distinct direct
owner arguments. Symbolic unification detects generic/generic, generic/closed and
closed/closed overlap before any conflicting application is requested. A closed
rule has no priority over a family. Implementations remain exact and module-owned;
their methods do not enter the struct's direct method namespace.
Specialized free-function references use ordinary Closure values with empty
environments. Lambdas inside specialized bodies keep explicit snapshot captures
and complete logical groups. Struct values retain reference identity; assignment
does not copy their state.
## Constructor initialization and Random
Implementation exposed a conflict: the static semantics required every field
initialized on each completing constructor path, while Random fixtures used an
empty constructor to obtain the provider's null reference default. The user
explicitly chose complete initialization and authorized revising Random's spec
and fixtures. This clarification applies to ordinary and generic structs.
The flow check intersects assignments across branches and accounts for loop exits
and short-circuit logical operands.
An assignment in a loop that might run zero times is insufficient. Deferred lambda
bodies do not initialize the enclosing constructor's fields. A constructor that
cannot complete has no completing path to check.
Valid Random source fixtures now initialize their fields explicitly. Four null
and typed-null checks remain controlled provider fixtures: compile valid source,
suppress the unique named-constructor field store in test bytecode, then run the
production verifier/VM. Runtime field defaults, typed Array presence and null
faults are still tested without making incomplete PBS constructors legal.
## Editor and diagnostic projections
Keep original declarations and spans alongside the specialized semantic projection.
Navigation and references distinguish symbolic parameters, concrete arguments and
generic origins. Concrete hover/completion/signature help use the applied type;
template bodies retain symbolic field and method presentation. Source formatting,
document/workspace symbols, rename references, inline hints and semantic overlays
continue through the existing frontend/LSP surfaces.
Pass the current application into declaration and flow diagnostics. Merely replacing
generated names at file scope is insufficient: field-position errors also need
related spans for the original definition and requesting use. Display a short
source chain and canonical application names rather than internal identities.
## Qualification and requirement coverage
The final reports contain 1,004 general tests, zero failures/errors and 13 existing
skips, plus two passing installed-knowledge tests. The complete Gradle regression
passed; final affected gates were repeated after improving diagnostic provenance
and finalizing installed spec references. One earlier external-source LSP failure
passed in isolation and in the complete repetition; no unrelated LSP code changed.
Production qualification used runtime revision
`f7d7c167531bb662a1af9d73fc326bb476bf8aa7`, Rust 1.98.1, macOS arm64, dev profile,
`resource-diagnostics`, default limits and `NONE` capabilities, with explicitly
lowered quota cases. All 16 mandatory generic fixtures passed. The full existing
PBX harness also passed, including 227 Random cases. This evidence does not qualify
another platform, a release runtime profile or the reference game.
| Requirements | Final evidence |
| --- | --- |
| R1–R2 | Exact arguments, origin/phantom/reference identity, contextual and named construction, complete initialization |
| R3–R5 | Composed multi-slot storage, symbolic capability errors, complete bodies, unused-method and overload failures |
| R6–R7 | Restricted coherent owner rules, overlap before use, anchored recursion and bounded expanding bodies |
| R8 | Production concrete Registry/PBX/VM, implementation zero, retained captures through GC and quota refusals |
| R9–R10 | Explicit free functions, concrete Fn/empty closures, nested captures and ordinary apply |
| R11–R12 | Homonymous binders/origins, definition-side helpers, aliases/reexports, barrels, duplicates and comparisons |
| R13 | Symbolic/concrete navigation and editor tests; diagnostic definition/use spans and readable applications |
| R14 | Shared infrastructure, isolated/combined modules, installed example/specs and complete regressions |
The 16 fixtures cover basic/manual objects, constructors/Self, phantom applications,
tuple, optional, Array, nominal recursion, combined dispatch, generic/manual Fn,
GC, imports/reexports, installed example, multiple parameters and homonymous origins.
Specialized and handwritten object/Fn fixtures execute under a one-handle limit
and use equal guest heap resources. All observed resources return to zero after
VM disposal. Refused allocation publishes no partial object. Full fixture sizes,
type/implementation counts, hashes, commands and log fingerprints are retained in
[evidence.json](evidence.json).
## Pitfalls and subsequent work
- Checking only requested templates or called methods changes source acceptance.
- Rewriting only signatures loses local annotations, construction contexts and captures.
- Using simple names or physical slots as identity merges distinct applications.
- Resolving private helpers at the caller makes imports change template meaning.
- Choosing a closed implementation over a family hides an incoherent program.
- Treating a provider's reference default as a PBS constructor exemption creates
incompatible source rules.
- Maintaining normative chapters in both `docs/specs/compiler-languages/pbs` and
`docs/compiler/pbs/specs` permits contradictions. The canonical owner is the
latter; existing distribution still merges both roots. Consolidating the legacy
chapters and their links/build inputs remains a separate repository migration.
The next collection discussion is List (DSC-0090 / AGD-0092). Its API, iteration,
logical bounds and private slot-transfer decisions remain open. Completing this
language prerequisite does not approve those collection proposals.
## References
- [Generic structs and free functions](../../../docs/compiler/pbs/specs/generic-structs-and-free-functions.md).
- [Generic contracts](../../../docs/compiler/pbs/specs/generic-contracts.md).
- [Arrays and optional](../../../docs/compiler/pbs/specs/typed-arrays-and-optional-execution.md).
- [Functions and captures](../../../docs/compiler/pbs/specs/first-class-functions-and-captures.md).
- [Random integration](../../../docs/compiler/pbs/specs/runtime-random-integration.md).
- [Concrete common Registry/PBX](../../../docs/compiler/general/specs/typed-registry-and-pbx-v0.md).
- Historical execution plan: PLN-0152, completed and removed by discussion housekeeping.
@@ -0,0 +1,185 @@
{
"date": "2026-10-22",
"owner": "compiler/pbs",
"discussion": "DSC-0094",
"decision": "DEC-0073",
"plan": "PLN-0152",
"runtime_revision": "f7d7c167531bb662a1af9d73fc326bb476bf8aa7",
"runtime_profile": "dev",
"runtime_features": [
"resource-diagnostics"
],
"runtime_limits": "default; explicit lower GuestBytes/HandleSlots refusal cases",
"capabilities": "NONE",
"platform": "macOS-27.0.1-arm64-arm-64bit-Mach-O",
"rustc": "rustc 1.98.1 (48a229cea 2026-09-01)",
"java_tests": {
"test": {
"tests": 1004,
"failures": 0,
"errors": 0,
"skipped": 13
},
"installedKnowledgeTest": {
"tests": 2,
"failures": 0,
"errors": 0,
"skipped": 0
}
},
"generic_fixtures": [
{
"name": "basic",
"types": 3,
"implementations": 0,
"bytes": 1278,
"sha256": "c6b72687525737aa6626ca5cea47e11498d68df0c6463ab04293062915d80409"
},
{
"name": "manual",
"types": 3,
"implementations": 0,
"bytes": 1216,
"sha256": "485c560ef569d07e46f2ce90a4b9814f68fc59a76b3a274e9f023985091fcd38"
},
{
"name": "constructor",
"types": 3,
"implementations": 0,
"bytes": 1329,
"sha256": "9274c106cba055f608e400a3fb033522e9a1e4d485cba85583ad813ddffc54e3"
},
{
"name": "phantom",
"types": 4,
"implementations": 0,
"bytes": 1094,
"sha256": "ccc6e25213c69e5b6c9c9b0089304d8d168584d5779f5f43e6289f9bf6d67b9f"
},
{
"name": "tuple",
"types": 4,
"implementations": 0,
"bytes": 2244,
"sha256": "7ee8ffb76df45de6a8824aa2b871763d47fd264e6024f5f6c89f6b1fded865cd"
},
{
"name": "optional",
"types": 5,
"implementations": 0,
"bytes": 1708,
"sha256": "bd662f86db9f53f882dd74c7728d0f48f98d25b3bbf5cc70111ed1472d6de81f"
},
{
"name": "array",
"types": 8,
"implementations": 0,
"bytes": 2186,
"sha256": "e5f1815ddca28177bba0af27297b25c039ffcde1402d374dd858c8f59dbe5c9e"
},
{
"name": "recursive",
"types": 5,
"implementations": 0,
"bytes": 1116,
"sha256": "0527985e60ab6a41f94122b7f88d62e4ffd237f887b0af23c01886f4a818658c"
},
{
"name": "combined",
"types": 5,
"implementations": 1,
"bytes": 1935,
"sha256": "2d5b9c9a501a66b951a7708523a3c0f02cba9d9f2fd3fcd7444b8359a701d63b"
},
{
"name": "function",
"types": 3,
"implementations": 0,
"bytes": 806,
"sha256": "32b80c1dc6be78db679d31bb0393362afca01354727aa8ba81dc8f92de6e2280"
},
{
"name": "function-manual",
"types": 3,
"implementations": 0,
"bytes": 773,
"sha256": "60f8fe92f39e0b5b531cdfefd1cee9d40377253fb6d7db80202ebf4b5becadf3"
},
{
"name": "gc",
"types": 6,
"implementations": 0,
"bytes": 2169,
"sha256": "9f292f40c4bfb6a6c6f734130d877abf2ce809da1665dd54bbb352d328aaa59e"
},
{
"name": "imports",
"types": 4,
"implementations": 1,
"bytes": 2493,
"sha256": "3ac928d8feebed5414aebe595c90ce08062903c0e5a9e198ba6365dc0f88c55e"
},
{
"name": "installed",
"types": 5,
"implementations": 1,
"bytes": 2142,
"sha256": "41af3aaeca0c39267543af3e79bc5f40b0846f66f448aa74afd2adcade3039b1"
},
{
"name": "multiple",
"types": 3,
"implementations": 0,
"bytes": 1305,
"sha256": "a59365588676083b8d9e078f869828067ed48f881252da4ad5b904f800f7d2b9"
},
{
"name": "origins",
"types": 5,
"implementations": 0,
"bytes": 2484,
"sha256": "ed3fcfdcab2aabe98ae525c67c688e3d7bec7bc757bb127b82ee652b4322ecb6"
}
],
"generic_fixtures_passed": 16,
"random_fixtures_passed": 227,
"source_fingerprints": {
"tools/pbx-conformance/main.rs": "322a772b4353c90d6acc54f90a0136eef544f92dd7434c7244762abb0125553e",
"tools/pbx-conformance/run.py": "7d4817b40371847c3debe1524f253354ca919cbda986349770647c3841a3eedb",
"prometeu-architecture-tests/src/test/java/p/studio/compiler/backend/irvm/PbsGenericStructsTest.java": "a2ecc312075009e052994a47cf7b52037ef545882865991adbcb328a5a27a665",
"prometeu-architecture-tests/src/test/java/p/studio/compiler/backend/irvm/PbsRuntimeRandomTest.java": "ba0b3de2e0aa7177fa71b5a837a56bc262a080717df3276c3a73b67b33dcb384",
"docs/compiler/pbs/specs/generic-structs-and-free-functions.md": "517cf07f7543a6ab261b1fdd177985b047b62fdb624bda40a63f61e28fa11263",
"prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/PbsGenericInstantiation.java": "4047b14f11aca83b62c5247233a941502cdedb462c887ec6032d2d0c5e308ee5",
"prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsCtorInitializationAnalyzer.java": "5a4a134324b2effce4c9e8ed66d1025e393c0fe61959190586d7ea103ad06f47",
"prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/PbsGenericStructsTest.java": "dc21746271b26bf0c7af191eeae70b1308dc322bedbdd0e3bcceda7c734bf14a"
},
"provider_fingerprints": {
"Cargo.lock": "cffad9ed62f38a591538abd81dd39270d6022397342c8189f4ac6c7baaa8e795",
"docs/vm-arch/INTRINSICS.csv": "0c1bb78a9b81d1e3480ef5713f3d70f0b06772a7dfab2fd00c1f0a6364f98daa",
"docs/vm-arch/BUILTIN_CONSTANTS.csv": "e407e4718127aa7ef7b1097b5b4b67d86dd979235e73a551a7c36b628cddc039",
"crates/console/prometeu-vm/tests/fixtures/numeric-conformance.tsv": "5536ee18cadaf32e3719b0e8d541dfcf1a84a49ea978a702101547c5ccdee3fe",
"crates/console/prometeu-vm/tests/fixtures/random-conformance.tsv": "0bee1cd0366f1716687aee8c7ac39dd495da5fe2908cce37b1443cb04fac542f"
},
"commands": [
"./gradlew test :prometeu-app:installedKnowledgeTest --console=plain --continue",
"./gradlew :prometeu-compiler:frontends:prometeu-frontend-pbs:test :prometeu-architecture-tests:test :prometeu-lsp:prometeu-lsp-v1:test :prometeu-app:installedKnowledgeTest --console=plain",
"python3 tools/pbx-conformance/run.py --runtime ../runtime",
"discussion validate",
"git diff --check",
"./gradlew :prometeu-compiler:frontends:prometeu-frontend-pbs:test :prometeu-architecture-tests:test --console=plain"
],
"logs": {
"dec73-regression-final.log": "2a90cbace3db898da9b445aba9c21be2b4f0c3d22724e1763fc9a0f3e52e7947",
"dec73-vm-regression.log": "159c6e0928a7d69aecb8660221135c1fa166e8e59212c5a3778883796170ea7e",
"dec73-final-provenance.log": "84168ed25ad52a98fbc3de7e0574d2bbbe1ba57cba47c066f09c26e0173d17b9",
"dec73-final-ctor-branches.log": "f32a83cf9084e4def4c1f12c2d3cce43b2254e217d57b9076f1707338afda3a9"
},
"notes": [
"One initial external-source LSP failure passed in isolated reproduction and complete regression repetition; no unrelated LSP code changed.",
"Final affected suite repeats include the declaration/use provenance correction and final installed spec cross-references.",
"Null and typed-null Random cases are controlled provider bytecode fixtures; ordinary and generic PBS constructors require complete field initialization.",
"Existing LifecycleRole and NonFiniteValue provider schema gaps remain reported by the common harness.",
"Qualification is local macOS arm64 dev profile, not another platform, release profile or reference-game qualification.",
"Final constructor analysis includes symbolic and/or short-circuit branches; frontend and architecture passed. All 16 regenerated artifact hashes match the production-VM-qualified PBX files."
]
}