feat(pbs): add parametric arrays and concrete generic contracts

Support explicit contract type parameters, canonical nominal applications,
recursive substitution, concrete implementations and instantiated editor views.
Complete parametric Array syntax and contextual construction integration.

Preserve type origins across imports and reexports, fix trait argument stack
order, and relocate global slots before lifecycle assembly. Publish specs,
installed examples and consolidated discussion lessons.

Validate frontend, common pipeline, architecture, LSP and installed knowledge
gates, plus the full production VM conformance corpus with 14 generic fixtures.
This commit is contained in:
2026-10-20 11:30:00 +01:00
parent b62db87245
commit 240216170c
70 changed files with 2369 additions and 273 deletions
@@ -19,9 +19,9 @@ The solution separates static source types, optional presence and physical stora
## The resulting source contract
```pbs
let enemies: array Enemy = new array(10);
let groups: array[2] Enemy = new array(3);
let scores: array int = [10, 20, 30];
let enemies: array<Enemy> = new array(10);
let groups: array<array<Enemy>> = new array(3);
let scores: array<int> = [10, 20, 30];
if let enemy = enemies[1] {
enemy.takeDamage(10);
@@ -29,7 +29,7 @@ if let enemy = enemies[1] {
enemies.clear(1);
```
Arrays have fixed length, shared reference identity and invariant element/depth types. Allocation initializes only outer positions to empty; it does not create enemies or nested arrays. Both constructors and every array literal require an expected array type. Depth is a positive literal; compiler structural limits prevent unbounded expansion. Length and indices accept int/long without loss, with the promotion confined to these operations.
Arrays have fixed length, shared reference identity and invariant element/depth types. Allocation initializes only outer positions to empty; it does not create enemies or nested arrays. Following DSC-0088, explicit `new array<T>(n)` supplies its own type; `new array<>(n)`, `new array(n)` and every array literal require an expected array type. Nesting uses `array<array<T>>`; compiler structural limits prevent unbounded expansion. Length and indices accept int/long without loss, with the promotion confined to these operations.
Reads return optional T. A vacant position is none, zero is present, and an invalid index faults. `if let` evaluates once and binds only in the success block. Optional fallback is lazy. Optional values, tuples, fields, parameters and results preserve complete groups. Optional array elements are rejected; an optional array itself is valid. PBS gains neither public Dynamic nor public null.
@@ -47,7 +47,7 @@ fn createCounter() -> Fn() -> int {
```
Each factory call creates independent state. Two closures capturing the same
counter intentionally share state. Arrays use `array (Fn() -> int)` and existing
counter intentionally share state. Arrays use `array<(Fn() -> int)>` and existing
optional-read rules. Methods become function values through explicit lambdas
capturing their receiver. The old `declare callback`, callback barrel exports
and `bind(context, function)` are rejected.
@@ -0,0 +1,80 @@
---
id: LSN-0087
ticket: pbs-array-type-syntax
title: Parametric arrays and contextual construction
status: consolidated
created: 2026-10-19
tags: [compiler-pbs, arrays, type-inference, parsing]
---
# Parametric arrays and contextual construction
Owner: `compiler/pbs`. Worker: Lesson Worker. Discussion: DSC-0088.
## Original problem and consolidated decision
Array already executed through PBS, PBX and the VM, but its `array T` and `array[N] T` syntax did not match the parametrized notation selected for future collections. DEC-0071, explicitly accepted by the user and implemented through PLN-0150, replaced that syntax without changing the storage contract. Those completed workflow artifacts were removed by housekeeping; this lesson and the specs retain their operational content.
Use `array<T>` and composition for nesting. Explicit construction supplies the type; both contextual sugars receive it:
```pbs
let a = new array<Enemy>(10);
let b: array<Enemy> = new array<>(10);
let c: array<Enemy> = new array(10);
let groups: array<array<Enemy>>=new array<>(3);
```
The first binding infers `array<Enemy>`. The next two constructor forms are equivalent and require a sufficient expected array type. Length does not infer the element type. The last allocation creates three empty outer positions, without allocating inner arrays. Old Array spellings are rejected rather than supported in parallel.
All prior execution rules remain: fixed length, reference aliases, invariance, vacancy versus present zero, optional reads, faults for invalid indices, int/long lengths and indices, single evaluation, complete value groups, nominal identity, ownership, quotas and GC. Optional elements remain invalid; optional arrays remain valid. Literal arrays remain contextual. This work does not implement shifts, new collections, generic structs/functions or broader overload inference.
## Implementation and architectural boundaries
`PbsAst.TypeRef` already provides a recursive `inner` node and a span for each type. Reuse that representation for Array's single argument. `NewExpr` now also carries an explicit array TypeRef and a diamond marker; its original total span remains available. An explicit element argument therefore retains its source identity and diagnostics span.
`PbsTypeParser` recognizes angle delimiters and enforces the existing structural nesting limit, including the constructor's outer array node. Barrel types use the same parser. `PbsTokenCursor.consumeTypeClose` peels one closing `>` and preserves the remaining token and byte offsets. For example, a type close taken from `>=` leaves `=` for the binding parser. The mechanism can also peel combined `>>`/`>>=` tokens if tokenization later changes, without adding shifts now. Ordinary expression comparisons remain intact; result and Fn spellings do not change.
Flow analysis resolves explicit constructor types without an expected destination, validates element surfaces and names, and checks invariant compatibility when a destination exists. Contextual construction uses the existing expected-type path for local/global bindings, assignment, arguments with a single resolved signature and returns. Missing context is an error, including unresolved overload contexts; no new overload inference was introduced.
PBS lowering must independently know the explicit constructor type. Local inference already consumes the initializer type, but updating only semantic analysis would leave executable lowering without enough information. Common backend and VM representations remain unchanged. Source type renderers now emit `array<T>`; editorial tests cover constructor-only element references, rename, inferred receiver completion and formatter round trips.
## Pitfalls exposed by execution
- Do not assume that parser acceptance proves execution. New constructor AST fields must feed semantic analysis, lowering and editorial type displays.
- Do not use the enclosing expression's expected return type to match a contextual constructor argument. The integrated test exposed this in lowering: constructor arguments need the selected parameter's type. Statically validated contextual constructors now follow the contextual argument path.
- Do not globally split comparison tokens. Peel type closers only in type context and retain exact remainder spans.
- Do not infer element type from length or silently coerce invariant arrays.
- Do not leave a second type grammar in barrel parsing or obsolete examples in installed knowledge.
- Do not count only the element subtree when checking explicit-constructor nesting limits; the outer array is a node too.
## Validation and final result
On 2026-10-19 the following gates passed without failures or errors:
| Gate | Result |
| --- | --- |
| PBS frontend | 255 tests, none skipped |
| Architecture PBS tests | 64 tests, none skipped |
| LSP v1 | 39 tests, one skipped |
| Installed knowledge | 2 tests, none skipped |
| Production loader/VM harness | Exit 0; new array-parametric fixture and existing structured, optional, alias, group, fault, resource, closure/GC, Random, math and catalog corpora |
| Whitespace review | `git diff --check` passed |
The new runtime fixture checks explicit local inference, diamond/omitted call arguments, global initialization/assignment, return context, nested outer-only allocation, aliases, adjacent closers/assignment and ordinary `>=`; its expected result is 42. Frontend tests separately cover all three constructor forms across expected-type positions, invariant mismatches, unknown/optional/void element types, missing context, malformed/obsolete types, nesting bounds and compound token spans.
Reproduce the Java gates with:
```sh
./gradlew :prometeu-compiler:frontends:prometeu-frontend-pbs:test :prometeu-architecture-tests:test --tests '*Pbs*' :prometeu-lsp:prometeu-lsp-v1:test :prometeu-app:installedKnowledgeTest --console=plain
python3 tools/pbx-conformance/run.py --runtime ../runtime
```
Local run logs were `/tmp/agd90-final-tests.log`, `/tmp/agd90-frontend-final.log` and `/tmp/agd90-vm2.log`; this summary preserves the evidence after temporary logs expire.
## References
- [Normative Array contract](../../../docs/compiler/pbs/specs/typed-arrays-and-optional-execution.md).
- [Function values and captures](../../../docs/compiler/pbs/specs/first-class-functions-and-captures.md).
- [Array storage and optional execution](../DSC-0079-pbs-typed-collections-and-dynamic/LSN-0083-pbs-arrays-optional-and-contract-execution.md).
- [Executable installed example](../../../prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/pbs-knowledge/examples/game/1/src/arrays.pbs).
- Completed workflow: AGD-0090 → DEC-0071 → PLN-0150 → this lesson. Future collection and contract discussions consume this completed syntax foundation independently.
@@ -0,0 +1,204 @@
---
id: LSN-0088
ticket: pbs-generic-contracts
title: Concrete Generic Contracts from PBS Source to the VM
created: 2026-10-20
tags: [compiler-pbs, generic-contracts, nominal-identity, runtime-conformance]
---
## Original problem and final result
Owner: `compiler/pbs`; cross-domain propagation: `compiler/general` and Studio/LSP.
DSC-0089 implemented accepted DEC-0072 through PLN-0151. Those control artifacts
are removed by housekeeping; the linked specifications are the operational
reference. All twelve decision requirements were implemented together.
PBS already supported nominal contracts and concrete implementation tables. The
missing feature was a frontend path from `Identity<T>` to exact concrete types.
Simple contract names appeared in the AST, imports, validation, lowering and
editor projections. Extending only the parser would have left those consumers
disagreeing about the same program.
The completed path is:
```text
parameterized declaration + explicit application
-> resolve defining declarations and logical arguments
-> memoize nominal application and substitute signatures
-> emit concrete Trait, implementation and function metadata
-> existing PBX loader/verifier and CALL_TRAIT execution
```
There is no runtime generic-instantiation engine or new PBX/ISA category. One
distinct application has one nominal Trait identity per image. Equivalent
applications share it. This delivers user-defined generic contracts; collection
storage and algorithms remain separate work.
## Using a strategy
```pbs
declare contract Identity<T> {
fn hash(e: T) -> int;
fn equals(a: T, b: T) -> bool;
}
declare service IntIdentity {}
implements Identity<int> for IntIdentity using strategy {
fn hash(e: int) -> int { return e; }
fn equals(a: int, b: int) -> bool { return a == b; }
}
fn equalSeven() -> bool {
let identity: Identity<int> = IntIdentity;
return identity.equals(7, 7);
}
```
`IntIdentity` is the receiver; `int` describes the elements. The service keeps
its singleton identity. Structs can instead provide constructed strategy
instances. Contextual assignments, arguments and returns, or explicit `as`,
form a view without allocating an adapter wrapper.
A contract can have several ordered parameters, such as `Converter<A, B>`.
Applications are explicit, exact-arity and invariant. A barrel exports the
declaration (`pub contract Identity<T>;`), not one closed application. There are
no raw types, contract diamond inference, default arguments, blanket generic
implementations or injected direct owner methods.
## Identity is resolved before representation
`PbsContractTypes` is the PBS-owned resolution and substitution boundary. Its
application key contains the defining declaration and ordered canonical logical
argument keys. File/source declaration identity distinguishes unrelated nominal
types; length-framed child keys avoid ambiguous nested encodings. Display names
and image-local numeric TypeIds are not identity keys.
Imports carry a semantic `TypeBindingDecl`: the local spelling, original
declaration and importing scope. The original signature keeps its lexical scope.
Reexports propagate that binding rather than synthesizing a new declaration.
Thus importing `Enemy as Opponent` makes `Identity<Opponent>` the same type as
`Identity<Enemy>`. Two unrelated declarations both named `Enemy` remain distinct.
The production multi-module fixture exercises both properties.
Physical storage must follow logical resolution. `array<int>` and `array<bool>`
can share the internal Array storage carrier while still identifying different
`Marker<array<...>>` applications. A parameter that never occurs in a method
signature still participates in identity. One owner can implement both
applications; implementation function names carry the full application key.
Substitution traverses arguments, arrays, Fn inputs/results, optional payloads,
named tuples and nested contracts. Existing return normalization applies before
signature comparison: for example, a one-field named return payload does not
create a second Fn result identity. Labels and parameter names remain available
for tooling. Existing restrictions still reject invalid substituted positions,
including optional void, void Fn inputs and invalid Array elements. `Self`
keeps its existing scope rules.
## Recursive graphs and bounded processing
Register an application anchor before scanning its substituted signatures. A
reference to an existing key closes a finite nominal graph; self and mutual
recursion therefore terminate. A work queue discovers further instances.
`Growing<T>` returning `Growing<array<T>>` continually creates new applications.
It is diagnosed as `E_SEM_CONTRACT_EXPANSION`, rather than hanging or becoming an
ordinary type mismatch. Analysis has explicit depth, work, instance and key
storage ceilings (256, 1,048,576, 65,536 and 64 Mi characters respectively). These producer
bounds do not increase runtime admission limits or replace loader accounting.
## Integration pitfalls exposed by real execution
**Trait call stack order differs from implementation parameter order.** The
implementation function receives its concrete owner first. At the CALL_TRAIT
instruction, explicit argument groups precede the two-slot view on the operand
stack. Lowering evaluates and roots the receiver, evaluates arguments left to
right, then reloads the complete view immediately before the call. No-argument
contract tests alone did not expose the old ordering error.
**Globals have one image namespace.** Independently compiled files can each
start allocating globals at slot zero. Common IR aggregation now relocates
declarations and GET_GLOBAL/SET_GLOBAL operands together. Lifecycle assembly
preserves those linked slots and places its initialization guard after all
globals. Without this, an imported strategy singleton could collide with the
guard. The fix belongs to the neutral compiler, with no PBS rule in the backend.
**Aliases must cover all consumers.** Imported function emission uses the true
target callable while local resolution uses its alias. Aliased services also
retain their constants. Generic hover uses original declaration names in both
the application heading and substituted signatures; navigation still reaches
the original declaration. A final alias-specific editorial test caught a
heading/signature disagreement that plain `Echo<int>` tests did not reveal.
**Verifier Unknown is not proof of a type error.** A mutated wrong-Trait call
can be rejected statically or admitted with unknown local facts. In the latter
case, execution must trap with the runtime type check. The conformance harness
accepts exactly these valid outcomes rather than weakening runtime checks or
requiring the verifier to infer more than its contract promises.
## Verification evidence
Verified on 2026-10-20 against runtime revision
`f7d7c167531bb662a1af9d73fc326bb476bf8aa7`, macOS/arm64, Rust 1.98.1,
development profile with `resource-diagnostics`. Defaults remain unchanged
except in explicit refusal tests. The harness builds in a temporary directory
and does not modify the provider checkout.
The fourteen mandatory generic fixtures compile actual PBS through the
production frontend, typed IR, PBX emitter, loader, verifier and VM:
| Fixture | Evidence | Types / implementations | PBX bytes |
| --- | --- | --- | --- |
| identity | Contextual/explicit adaptation and dispatch | 5 / 1 | 1,921 |
| manual | Handwritten concrete behavioral reference | 5 / 1 | 1,859 |
| multiple | Same owner, several applications | 6 / 2 | 1,991 |
| tuple | Two parameters, Array input, complete tuple result | 9 / 1 | 2,762 |
| optional | Absence/presence and optional groups | 6 / 1 | 2,267 |
| function | Fn argument and call | 5 / 1 | 1,705 |
| contract | Nested contract argument | 5 / 2 | 2,014 |
| native | Native vec2 payload groups | 5 / 1 | 1,607 |
| recursive | Finite recursive application and chained calls | 4 / 1 | 1,791 |
| phantom | Distinct logical Array arguments, identical signatures | 5 / 2 | 2,036 |
| receiver | Constructed struct receiver state | 4 / 1 | 1,534 |
| gc | Closure retains view/receiver through collection | 7 / 1 | 2,153 |
| installed | Packaged runnable contracts example | 5 / 1 | 2,105 |
| imports | Aliases/reexports, distinct origins, lifecycle globals | 5 / 3 | 2,540 |
The generic and handwritten references both succeed with one heap handle and
equal guest allocation footprint. Typed absence and ImplementationId zero are
checked separately. The GC fixture reclaims at least 1,100 discarded objects
while the captured receiver remains callable. Reduced GuestBytes/HandleSlots
and zero implementation admission test resource refusal, bounded publication
and complete ownership release. These observations do not imply identical PBX
bytes or a performance improvement.
The complete provider harness also passed the existing source/input, structured
value, closure, math, Random, lifecycle, malformed-image and resource corpora.
Its two previously documented upstream schema enum gaps remain explicitly
reported; they are not hidden or counted as schema conformance.
Compiler API (29 tests), PBS frontend (274 tests) and build-pipeline suites
passed, together with 68
affected architecture tests, 22 LSP bridge/protocol tests and both installed
knowledge tests. The build-pipeline suite retains twelve pre-existing disabled
legacy integration cases; production fixtures exercise the required paths.
Additional focused cases cover mutual recursion and imported alias navigation.
Workflow validation and whitespace checks passed before completion.
Reproduce with the gates in the [conformance harness documentation](../../../tools/pbx-conformance/README.md).
The new specification and `contracts.pbs` example are discoverable in installed
knowledge, not only in the source checkout.
## Handoffs and references
AGD92/List is next in the umbrella sequence. SDK data/algorithm specialization
and stable object-identity hashing still require their consumer decisions.
Generic functions/structs, constraints, variance, inheritance/default methods,
associated strategy members and runtime specialization were not introduced.
- [PBS generic contracts specification](../../../docs/compiler/pbs/specs/generic-contracts.md).
- [Typed Registry/PBX and global relocation](../../../docs/compiler/general/specs/typed-registry-and-pbx-v0.md).
- [Arrays, optional and contract execution](../../../docs/compiler/pbs/specs/typed-arrays-and-optional-execution.md).
- [Functions and captures](../../../docs/compiler/pbs/specs/first-class-functions-and-captures.md).
- [Installed source example](../../../prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/pbs-knowledge/examples/game/1/src/contracts.pbs).
- Historical workflow: AGD-0091, accepted DEC-0072, completed PLN-0151; DSC-0089.