Files
prometeu-studio/docs/compiler/pbs/specs/generic-contracts.md
T

7.1 KiB

PBS Generic Contracts

Owner: compiler/pbs. This specification extends nominal contracts with explicit type parameters. Registry, PBX, instruction, ownership and resource contracts remain governed by the runtime provider. Collections and object-identity hashing are separate consumers.

Declaration and application

declare contract Identity<T> {
    fn hash(e: T) -> int;
    fn equals(a: T, b: T) -> bool;
}

declare contract Converter<A, B> {
    fn convert(value: A) -> B;
}

A parameterized declaration has one or more distinct ordered type parameters. Their scope is the contract's signatures, including nested type references. A type parameter is not the receiver. Self retains its existing meaning and validity restrictions.

Applications supply explicit ordered type arguments with exact arity: Identity<int> and Converter<Enemy, str>. The declaration's raw name, omitted arguments, <>, default arguments and blanket generic implementations are not value types or inference mechanisms. Nonparameterized contracts remain valid. Generic structs and free functions add restricted owner-bound implementation families; they do not introduce blanket implementations for arbitrary owners.

The same compositional type grammar applies in annotations, nested applications, implementation targets and expression-form as. Existing contextual angle closers and expression comparisons retain their meanings. A barrel exports the declaration, for example pub contract Identity<T>;, preserving its origin and ordered parameters rather than exporting a particular application.

Identity and compatibility

An application's identity is the defining nominal contract declaration plus its ordered canonical logical argument identities. Import aliases resolve before this identity is formed. If Opponent aliases the same Enemy declaration, Identity<Opponent> and Identity<Enemy> are identical. Equal names, method shapes or physical layouts do not merge different declarations or applications. Phantom arguments still distinguish applications.

Applications are invariant. A conversion between argument types does not establish a conversion between their contract applications. Existing explicit reference-view conversion can select another implementation actually supplied by the concrete receiver; it does not manufacture variance.

Substitution and composition

Substitution traverses every type position in each signature, preserving parameter names, tuple labels, order and source provenance. It supports valid composition with existing builtins, nominal values, arrays, other applied contracts, Fn, optional and named tuples. Each resulting position remains subject to the existing type, return, optional/result and storage rules; substitution does not legalize an otherwise invalid position.

Normalize substituted signatures before deriving physical parameter/result groups. One logical parameter can contain several physical values. A shared physical carrier does not erase logical argument identity: distinct Identity<array<X>> applications remain nominally distinct even when their arrays share internal storage representation.

Implementations and values

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);
}

Structs and services are the supported owners. An implementation belongs to the owner's declaring module and follows existing visibility rules. Implementations are complete and unique per (owner, instantiated contract). One owner may implement several applications of the same contract. Implementation/callable identities include the full application, preventing collisions between those methods. Contract methods are not injected into the direct method namespace of their owner.

Named service singletons and constructed struct values supply strategies. Contextual assignments, arguments and returns, and explicit value as Identity<int>, select the concrete implementation. Conversion preserves the receiver and selected implementation without allocating an adapter wrapper or duplicating a singleton. Associated members such as Enemy.identity are not introduced.

Recursion and bounded analysis

Register a nominal application anchor before expanding its signatures. A recurrence to an existing key forms a finite graph and is valid within existing resource limits. An application family that continually introduces new arguments, such as Growing<T> returning Growing<array<T>>, must be rejected with a clear expansion diagnostic.

Expansion, substitution and identity processing are bounded in work, storage and depth. Resource exhaustion and nonterminating specialization must not become hangs, host stack overflows, missing-method errors or ordinary argument-mismatch diagnostics.

Execution and tooling

The frontend emits a concrete nominal Trait descriptor for each distinct required application, sharing the descriptor for equivalent uses across modules. Open type parameters do not reach executable signatures. Implementation functions receive the concrete owner first, followed by complete substituted argument/result groups.

Existing Registry/PBX and REF_TO_TRAIT/CALL_TRAIT mechanisms execute these records. Preserve typed absence, valid ImplementationId zero, receiver identity, rooting, GC, native ownership and quotas. Generic calls do not introduce a Dynamic argument ABI or boxing merely because an argument was a type parameter. Existing storage-specific packing remains governed by that storage's contract.

Navigation reaches generic declarations, parameters and argument declarations. Hover, completion and signature help show instantiated signatures with canonical source names. Arity, unresolved parameters, invalid applications/coercions, incomplete or duplicate implementations and expansion failures have localized diagnostics. Compilation and editor projections share the same type resolution.

Conformance

Compile real PBS through typed IR and production PBX into the production loader, verifier and VM. Cover multiple parameters/applications, several applications on one owner, imports/aliases/reexports, nominal origin, phantom arguments, composed and multi-slot payloads, finite recursion, expanding recursion rejection, service/struct views, typed absence, implementation zero, GC and resource refusal.

A specialized contract and a manually written concrete equivalent must exhibit the same behavior without generic-only adaptation/boxing. Identical image bytes and a performance improvement are not required. Installed knowledge packages this specification and a runnable source example. Generic structs/functions are defined by the separate owner specification, sharing canonical identities, provenance and bounded expansion with contracts. Bounds, variance, inheritance/default methods, generic reflection, runtime instantiation and collection algorithms remain outside these extensions.