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:
+4
-4
@@ -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.
|
||||
|
||||
|
||||
+1
-1
@@ -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.
|
||||
|
||||
+80
@@ -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.
|
||||
+204
@@ -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.
|
||||
Reference in New Issue
Block a user