docs: consolidate canonical specs and preserve PBS reference IDs
This commit is contained in:
+284
@@ -0,0 +1,284 @@
|
||||
# Concrete Generic Structs and Free Functions
|
||||
|
||||
Status: Normative. Owner: `compiler/pbs`.
|
||||
Scope: Generic Structs and Free Functions.
|
||||
|
||||
This specification adds parameterized state and executable
|
||||
bodies to the nominal, concrete application model of generic contracts. It applies
|
||||
uniformly to SDK modules and program sources. Registry, PBX, VM admission, resource
|
||||
limits and instruction semantics remain governed by the existing provider contracts.
|
||||
|
||||
## Authority and scope
|
||||
|
||||
This chapter is the canonical owner of the detailed contract described below.
|
||||
The [domain reading guide](README.md) identifies related chapters and their
|
||||
separate responsibilities. Cross-cutting chapters refer here for these rules.
|
||||
Runtime-owned ABI, instruction, resource and execution contracts retain their
|
||||
authority; this chapter specifies their compiler or PBS consumer requirements.
|
||||
|
||||
## Declarations and identity
|
||||
|
||||
Structs and module-level named free functions may declare one or more distinct,
|
||||
ordered type parameters. Applications have exact arity. Type parameters have
|
||||
identity by declaration or binder and ordinal position; their spelling is lexical
|
||||
presentation, not a globally substitutable symbol.
|
||||
|
||||
```pbs
|
||||
declare struct Box<T>(value: T) {
|
||||
fn get() -> T { return this.value; }
|
||||
fn set(value: T) { this.value = value; }
|
||||
}
|
||||
declare struct Pair<K, V>(key: K, value: V);
|
||||
fn identity<T>(value: T) -> T { return value; }
|
||||
```
|
||||
|
||||
An application is identified by its nominal source declaration and ordered,
|
||||
canonical logical arguments after alias resolution. Aliases and reexports of the
|
||||
same declaration share applications. Homonymous declarations from different
|
||||
origins, phantom arguments and logically different types remain distinct even
|
||||
when fields, signatures or physical carriers coincide. Applications are invariant;
|
||||
numeric or reference conversions between arguments do not convert their containers.
|
||||
Struct assignment shares the existing object reference and does not deep-copy it.
|
||||
|
||||
The raw name of a parameterized struct is not a closed type, including inside its
|
||||
own declaration. Open parameters exist only in the authorized declaration scopes
|
||||
and must not reach executable metadata.
|
||||
|
||||
## Construction and expected types
|
||||
|
||||
```pbs
|
||||
let a = new Box<int>(42);
|
||||
let b: Box<int> = new Box<>(42);
|
||||
let c: Box<int> = new Box(42);
|
||||
```
|
||||
|
||||
Explicit construction supplies its application. Diamond and omitted arguments
|
||||
require a sufficient, compatible expected application at the existing contextual
|
||||
Array positions: annotated bindings, assignments, resolved callable parameters,
|
||||
returns and value expressions with an expected type. Values do not infer type
|
||||
arguments: `let d = new Box(42);` is invalid. There is no partial inference, default
|
||||
argument or additional overload search to discover generic arguments.
|
||||
|
||||
Named constructors use the applied owner, for example `new Box<int>.make(42)`.
|
||||
Substitution preserves existing constructor selection, evaluation order, definite
|
||||
field initialization, visibility, `this` and completion rules. A parameter has no
|
||||
implicit constructor or universal default; `new T()` is invalid.
|
||||
|
||||
Every completing constructor path MUST explicitly assign every field, in ordinary
|
||||
and generic structs, including fields of opaque builtin type Random. Assignment
|
||||
in only one conditional branch or in a loop that may execute zero times is
|
||||
insufficient. Runtime reference defaults are provider behavior and do not exempt
|
||||
PBS constructors from this rule. Controlled null-provider fixtures are described
|
||||
in [Runtime Random integration](20.%20Runtime%20Random%20Integration%20Specification.md).
|
||||
|
||||
## Composition and symbolic capabilities
|
||||
|
||||
Arguments and substituted uses compose with valid builtins, nominal values,
|
||||
applied structs/contracts, Array, Fn, optional, tuples and existing return/result
|
||||
positions. Each position retains its existing restrictions. Normalize logical
|
||||
types before deriving physical groups, preserving labels, names, order and every
|
||||
slot of a multi-slot value.
|
||||
|
||||
Array's element restriction is not a global generic restriction. A T field can
|
||||
hold `Box<optional int>`; a field declared `array<T>` makes the application with
|
||||
T=optional int invalid. Revalidate all concrete positions after substitution.
|
||||
|
||||
Templates are validated symbolically before relying on concrete arguments. An
|
||||
unconstrained T can be stored, assigned compatibly, passed and returned. It gains
|
||||
no arithmetic, comparison, members or construction from a particular application.
|
||||
`value + value` on T is invalid even when the only requested application uses int.
|
||||
Known operations of declared containers remain available; indexing array<T>, for
|
||||
example, produces optional T. Additional capabilities require explicit composition:
|
||||
|
||||
```pbs
|
||||
declare struct ComparedBox<T>(value: T, identity: Identity<T>) {
|
||||
fn matches(other: T) -> bool {
|
||||
return this.identity.equals(this.value, other);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This does not introduce bounds, implicit equality/hash or opportunistic member
|
||||
lookup on an argument.
|
||||
|
||||
## Complete substitution, validation and Self
|
||||
|
||||
Substitute fields, constructor/method signatures and complete bodies, including
|
||||
local annotations, nested applications and constructions, references/calls,
|
||||
lambdas and capture environments. Rewriting signatures alone is insufficient.
|
||||
Ordinary methods use their owner's type parameters; they do not declare another
|
||||
generic parameter list.
|
||||
|
||||
Self denotes the complete applied owner in its existing valid locations. It means
|
||||
Box<int> inside that application and Box<Enemy> inside the other. Header fields
|
||||
must still spell recursive types explicitly, such as `optional Node<T>`; the
|
||||
feature does not expand Self's valid locations. Existing privacy, pub/pub mut,
|
||||
receiver and direct-versus-contract method rules remain unchanged.
|
||||
|
||||
For every required owner application, validate its fields, constructors and all
|
||||
methods, including uncalled methods. Dead-code elimination must not change source
|
||||
acceptance. Method/constructor identities include their source declaration,
|
||||
applied owner and existing signature identity. Distinct overloads that collapse
|
||||
after substitution reject the application and identify both declarations. In
|
||||
particular, set(T) and set(int) collide at T=int without an implicit preference.
|
||||
|
||||
## Owner-bound implementations and coherence
|
||||
|
||||
```pbs
|
||||
declare contract Reader<T> { fn read() -> T; }
|
||||
implements<T> Reader<T> for Box<T> using box {
|
||||
fn read() -> T { return box.get(); }
|
||||
}
|
||||
```
|
||||
|
||||
A parameterized implementation's owner must directly apply a declared generic
|
||||
struct. Every owner argument is a distinct binder parameter, and all binder
|
||||
parameters are bound through the owner. Binder names need not match the struct's
|
||||
parameter names. Arbitrary owners, unbound parameters, narrower patterns such as
|
||||
Box<array<T>>, and repeated arguments restricting the family are invalid.
|
||||
|
||||
The rule belongs to the owner's declaration module. Its target resolves to a
|
||||
contract and may compose the owner-bound parameters under existing type rules.
|
||||
Implementations are complete with exact substituted signatures. Emitted owners,
|
||||
targets and methods are concrete. Contract methods are not injected into the
|
||||
owner's direct namespace. Views preserve receiver, implementation and identity
|
||||
without a wrapper required by parameterization.
|
||||
|
||||
Uniqueness is by concrete (owner, contract) pair. Two declarations overlap if an
|
||||
admissible application could produce the same pair. Compare canonical nominal
|
||||
origins and arguments with symbolically owner-bound parameters. Detect
|
||||
generic/generic, generic/closed and closed/closed collisions before the conflicting
|
||||
application is used. Different contract applications for an owner remain valid
|
||||
when their pairs cannot coincide. Bounded analysis must not enumerate only used
|
||||
applications, choose file/import order, prefer closed rules or silently succeed
|
||||
after exhausting its budget.
|
||||
|
||||
## Free functions, overloads and Fn
|
||||
|
||||
References and calls provide explicit type arguments, such as identity<int>(42).
|
||||
An argument may mention a parameter in an enclosing template but must become
|
||||
concrete before emission. There is no value, result or expected-Fn inference,
|
||||
function diamond or default generic argument. `identity<>` and a polymorphic Fn
|
||||
value for open `identity` are invalid.
|
||||
|
||||
An applied function's identity includes its source declaration and ordered logical
|
||||
arguments, including phantom arguments. Equivalent uses share the application;
|
||||
different declarations remain different targets despite identical concrete
|
||||
signatures. Symbolic validation, definition scope, complete body substitution,
|
||||
normalization and bounded expansion apply to required function applications too.
|
||||
|
||||
`f<int>` considers generic free functions with matching type arity. A reference
|
||||
or call without type arguments does not select a generic template. Ordinary
|
||||
overloads remain subject to existing rules. After explicit binding, use existing
|
||||
concrete signature resolution. Consistent renaming does not create overloads:
|
||||
f<T>(value:T) and f<U>(value:U) are duplicates when otherwise signature-equivalent.
|
||||
Substituted collisions in the filtered generic candidate set are errors.
|
||||
|
||||
```pbs
|
||||
let transform: Fn(int) -> int = identity<int>;
|
||||
let answer = transform(42);
|
||||
```
|
||||
|
||||
Closed references use the existing Closure mechanism with an empty environment.
|
||||
Fn stays structural by logical parameters/results, excluding target identity,
|
||||
names and captures. Distinct targets may share a compatible Fn descriptor.
|
||||
Lambdas in specialized bodies preserve explicit capture semantics and complete
|
||||
groups. Bare method extraction remains invalid. Calls preserve canonical apply,
|
||||
existing named/positional forms, order and single evaluation.
|
||||
|
||||
## Definition scope, imports and barrels
|
||||
|
||||
Each declaration/binder has its own substitution environment. Names in a template
|
||||
body bind in its definition scope; type argument names bind at the use. Caller
|
||||
and callee parameters with the same spelling must not capture one another.
|
||||
Instantiation does not resolve private helpers in the caller or export them.
|
||||
|
||||
```pbs
|
||||
pub struct Box<T>;
|
||||
pub struct Pair<K, V>;
|
||||
pub fn identity<T>(value: T) -> T;
|
||||
```
|
||||
|
||||
Barrels export the parameterized declaration, ordered parameters and signature,
|
||||
not an enumeration of closed instances. Preserve the original definition through
|
||||
imports/aliases/reexports and make the necessary body available to the compiler
|
||||
under existing visibility rules. This does not add an open-template PBX format.
|
||||
|
||||
The application grammar extends the existing ordered type argument syntax to
|
||||
struct/free-function declarations, barrels, owner-bound implements and named
|
||||
function reference expressions. Calls continue to use ordinary parentheses/apply.
|
||||
Nested applications and adjacent closers preserve spans. Complete type-argument
|
||||
references must remain distinct from ordinary <, > and >= comparisons without
|
||||
changing their meanings or adding shifts. Malformed source retains localized
|
||||
diagnostics and recovery. Fields, ordinary Fn values and methods gain no generic
|
||||
parameter list from this grammar.
|
||||
|
||||
## Expansion, diagnostics and concrete execution
|
||||
|
||||
Share logical identity, substitution environments, provenance and bounded
|
||||
expansion infrastructure across PBS structs, functions and contracts. Keep each
|
||||
category's layout/callable rules explicit and keep PBS rules in the frontend.
|
||||
Register nominal and callable anchors before expanding dependencies. Revisiting
|
||||
the same application forms a finite graph, including cross-category field/body
|
||||
dependencies. Families requiring indefinitely new applications are diagnosed,
|
||||
including growth through uncalled methods of a used owner.
|
||||
|
||||
Analysis, normalization, substitution, coherence and materialization are bounded
|
||||
in depth, work and storage. Exhaustion must not become a hang, host stack overflow,
|
||||
misleading missing method or ordinary argument mismatch. Frontend budgets do not
|
||||
increase provider limits.
|
||||
|
||||
Errors preserve the original declaration and requesting use, with a short chain
|
||||
such as `main -> wrap<Enemy> -> Box<Enemy>`. Cover unbound/duplicate parameters,
|
||||
arity, raw/inferred application, invalid positions/capabilities, incomplete
|
||||
construction, overload collisions, invalid implementation owners/rules, overlap
|
||||
and expansion. Generated names and Java stacks do not replace source explanation.
|
||||
Navigation, references/rename, hover, completion, signature help, symbols,
|
||||
formatting and semantic tokens share compilation resolution/substitution. Distinguish
|
||||
symbolic parameter, concrete argument and generic origin, including imported code.
|
||||
|
||||
Emit only concrete Struct/Trait/Fn descriptors, callables, fields, signatures,
|
||||
capture environments and implementation functions. Preserve logical identity
|
||||
independently of storage width. Existing Struct/Array/Trait/Fn, direct calls,
|
||||
REF_TO_TRAIT/CALL_TRAIT and Closure execute the result. Preserve receiver,
|
||||
singletons where applicable, typed absence, valid ImplementationId zero, rooting,
|
||||
GC, ownership, faults, evaluation and quotas. Genericity must not impose Dynamic,
|
||||
reboxing or an adapter wrapper as its argument ABI; existing storage packing
|
||||
retains its own contract. No new opcode, PBX category or runtime instantiation
|
||||
engine is required. A provider-contract gap requires explicit decision revision.
|
||||
|
||||
## Qualification and boundaries
|
||||
|
||||
Conformance compiles real source through typed IR and production PBX into the
|
||||
production loader, verifier and VM. Cover multiple arguments/applications, origin,
|
||||
aliases/reexports/phantom identity, constructors/Self/all methods, composition and
|
||||
multi-slot groups, free functions/apply/Fn, captures, finite/expanding recursion,
|
||||
coherence, GC, ownership and quota refusal. Include negative cases for symbolic
|
||||
operations, unused invalid methods, inferred applications, alpha-equivalent
|
||||
duplicates and provenance diagnostics.
|
||||
|
||||
A complete multi-module fixture must combine Box<T>, Reader<T>, owner-bound
|
||||
implements<T>, read<T>, read<int> as Fn and imports/aliases, returning 42. Compare
|
||||
specialized structs/functions with handwritten concrete equivalents for behavior,
|
||||
identity/lifetime and absence of adaptation imposed solely by T. Record provider
|
||||
revision/configuration, complete fixture counts, metadata counts and artifact
|
||||
sizes. Identical PBX bytes and a performance improvement are not required.
|
||||
|
||||
Ship and verify specifications and executable examples in installed knowledge.
|
||||
Regress Array, ordinary/applied structs/contracts, Self, constructors, Fn/captures
|
||||
and lifecycle. No mandatory requirement is deferred to a collection implementation.
|
||||
|
||||
Independent generic methods, generic contract methods/lambdas, polymorphic Fn,
|
||||
function type inference, bounds, variance, defaults, user specialization and
|
||||
blanket/narrower implementation patterns are outside this feature. Lifecycle
|
||||
signatures remain concrete. Collection APIs/algorithms, default equality/hash,
|
||||
iteration protocols and List logical bounds/slot transfer are separate decisions.
|
||||
|
||||
## Related specifications
|
||||
|
||||
- [Generic contracts](16.%20Generic%20Contracts%20Specification.md).
|
||||
- [Typed arrays and optional execution](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md).
|
||||
- [First-class functions and captures](15.%20First-Class%20Functions%20and%20Captures%20Specification.md).
|
||||
- [Concrete Registry and PBX handoff](../../compiler/25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md).
|
||||
- [SDK Map and Keyval](24.%20SDK%20Map%20and%20Keyval%20Specification.md), a two-parameter source consumer
|
||||
preserving separate key/value policies and complete optional/grouped fields.
|
||||
Reference in New Issue
Block a user