CLI: Interop Contract

Tier 1 · Story 15Complete

The Tyhp ↔ PHP interop contract is the written ABI between the Tyhp compiler (emitter) and the Tyhp runtime packages (tyhp/core, tyhp/async, tyhp/decimal, tyhp/lambda). Compiled Tyhp depends on concrete PHP shapes — class names, method names, and call patterns. This page is the user-facing index for that boundary.

Why this contract exists

Without an explicit contract, the coupling is implicit: emitter transformers call \Tyhp\… by exact FQN and signature, and the runtime must match. When either side changes silently, builds break late. This page writes the contract down, stamps a version on both sides, and keeps a machine-checkable surface so drift is caught early.

Contract version

Each runtime package stamps the contract it implements in Composer metadata:

{
    "extra": {
        "tyhp": {
            "interopContractVersion": 1
        }
    }
}

The compiler constant is Tyhp.TyhpLang.Interop.InteropContract.CurrentVersion (currently 1). When a required runtime package’s stamp does not match the compiler’s current version, the build fails with diagnostic TYHP5018 (error).

Synthetic dispatch naming

Canonical spellings live in compiler helpers — do not invent parallel schemes. Ownership:

Operators

Every overloadable operator maps to a single deterministic method name (no type suffixes, no _N collision numbers). Multiple forms of the same operator collapse into one method that dispatches on operand types.

Binary / comparison

Unary / word

Convert

Binary/unary/empty overloads emit as static methods. Convert-to emits as an instance method so it can satisfy \Stringable and \Tyhp\Contracts\*Convertible. Call sites rewrite to ClassName::__add($l, $r) (and peers). Feature detail: Operator Overloads.

GeneratedNames (generics & property hooks)

These identifiers (except the extension-receiver rename, which is emit-only) are reserved by the checker so user code cannot collide with generated symbols.

Extensions

Extension methods keep their declared method name. Call sites rewrite instance-style calls into static dispatch with the receiver first:

ExtensionClass::method($receiver, /* …args */);

When the author names the receiver $this (the documented spelling), emit renames that parameter to $this_ in the static method signature and rewrites body references (including nested closures) accordingly — PHP rejects a parameter literally named $this. Other receiver names emit unchanged.

Null-safe extension calls short-circuit with a temporary receiver binding. See Extensions.

Type erasure

Tyhp features that exist for type-checking often leave no (or a reduced) PHP footprint:

What survives is whatever the emitter explicitly lowers into calls on the runtime surface below (operators, disposables, async, property-hook polyfills, generic bags, with, PropertyPath / expression trees, and so on).

Runtime entry points

FQNs the contract covers. Packages are identified by their Composer names (tyhp/core, tyhp/async, tyhp/lambda, …).

Emitter RequirePackage today

The emitter currently records required Composer packages via EmitContext.RequirePackage for:

• tyhp/core — generics, Type/NamedType, property-accessor polyfill, ObjectHelper, convertible contracts, operator overload exceptions, …
• tyhp/async — Promise, await, async wrappers, async disposal paths, …
• tyhp/lambda — PropertyPath and full Expression trees construction at call sites

Those packages are what the build action can auto-wire into a project’s composer.json from emit.

Required contract surface (all packages)

Even when the emitter does not yet RequirePackage a package for every call site, the following FQNs are part of the written interop surface (direct calls and future emit):

tyhp/core

tyhp/decimal

Contract surface for decimal operators / convert targets and direct use. The emitter does not currently list tyhp/decimal via RequirePackage for every decimal path; projects that use decimal still depend on the package.

tyhp/async

tyhp/lambda

PropertyPath emit ABI: when a call argument targets PropertyPath<callable(T): R> and the argument is an inline property-chain fn, the emitter lowers to a chain with one property step per segment, ended by backedBy with the original fn:

\Tyhp\PropertyPath::on(\SourceType::class)   // or a builtin type string such as 'string'
    ->segment
    /* … */
    ->backedBy(fn (/* … */): ResultType => /* original chain */);

A segment read through ?-> is preceded by nullSafe(), so the runtime builds a NullSafeAccessExpression for that hop instead of a PropertyAccessExpression:

\Tyhp\PropertyPath::on(\User::class)->billing->nullSafe()->city->backedBy(fn(\User $u): ?string => $u->billing?->city);

Expression emit ABI: when a call argument targets Expression<callable(T): R> and the argument is an inline arrow fn, the emitter lowers to a \Tyhp\Expr chain ended by backedBy with the original fn, which returns the \Tyhp\Expression:

\Tyhp\Expr::param('u', \User::class)->age->gt(18)->backedBy(fn(\User $u): bool => $u->age > 18);

The chain uses these builder calls:

• Expr::param(name, type, index) starts at a parameter; index is passed when the fn has several parameters.
• A property read is a property step (->age), or prop('name') when the name matches a builder method. nullSafe() precedes a ?-> hop.
• call(name, ...args), staticCall(Class::class, name, ...args), and make(Class::class, ...args) build method calls, static calls, and new.
• Operators are builder methods: gt, gte, lt, lte, eq (===), neq (!==), looseEq (==), looseNeq (!=), spaceship, plus, minus, times, dividedBy, mod, pow, concat, bitAnd, bitOr, bitXor, shiftLeft, shiftRight, not, neg, pos, bitNot, and, or, xor, coalesce, then / else, is, cast, and at (array access).
• A nested arrow fn is Expr::closure([Expr::param(...), …], <body chain>, 'returnType'), and an array literal is Expr::arrayOf([values], [keys]).
• Captured variables, literals, and class constants are passed as plain PHP arguments (->gt($minAge), ->value(User::FLAG)), so their values are read when the chain runs.

A nested fn passed to a method's callable, Expression, or PropertyPath parameter becomes an Expr::closure node:

\Tyhp\Expr::param('u', \User::class)->tags->call('any', \Tyhp\Expr::closure([\Tyhp\Expr::param('t', \Tag::class)], \Tyhp\Expr::param('t', \Tag::class)->label->eq('vip'), 'bool'))->backedBy(fn(\User $u): bool => $u->tags->any(fn(\Tag $t): bool => $t->label === 'vip'));

Parameter types use the \Tyhp\Type::parse() format. A parameter whose type has type arguments or is a struct is passed as a string ('App\Table<App\Blog>', 'struct App\Address') instead of Fqn::class; a property node's type is the declared property type (\Tyhp\Type::fromProperty()). The tree's return type comes from the backing closure's return type.

Expression takes one type argument: the callable shape (Expression<callable(User): string>; Expression<callable(): R> for zero parameters). That shape is a checker/type-system convention; the emitted chain is the same for every shape.

nameof(fn ($x) => $x->a->b) is a compile-time fold to the last property segment (a string literal). It does not emit PropertyPath / Expression construction.

ExpressionSerializer::toJson / equals and Expression::equals are runtime library APIs (not emitter call patterns). User code that calls them depends on tyhp/lambda the same way any other package type does.

When a PropertyPath / Expression value is passed where \Closure is expected, emit extracts the stored closure as $expr->callable (public readonly property on \Tyhp\Expression). Where callable is expected, the object is passed through (__invoke).

Feature detail: Parsable Lambdas.

Emitted docblocks

PHP that calls compiled Tyhp, and PHPStan or Psalm run on that PHP, can rely on docblock tags wherever the native declaration drops a type Tyhp checked. The tags are on in every build profile and do not depend on output.comments.

emit.docblocks defaults to "lossy-only": a tag is written only when it says more than the PHP hint (array<int, User> becomes native array plus @param array<int, \App\User>). "all" tags every signature type. "off" writes none of the generated tags. emit.docblockDialect ("both" by default, or "phpstan", "psalm", "phpdoc") is parsed and validated and does not change the text. Shared tags are unprefixed.

What a consumer can rely on, when the checker had the type: @param, @param-out for a by-ref parameter, @return, @var, @template (with of, variance, and a default when the parameter has them), @extends, @implements, @use, and @internal. @throws is not generated; an author @throws is kept. Symbol names in generated tags are fully qualified, and a use … as alias is the real name. self, parent, and static stay relative. A struct is array{…} with optional keys as key?:. A callable is callable(int): string. class-string is used for a class, interface, or enum name.

An author docblock's summary stays above the tags. @tyhp emitter directives and /@@ … @@/ blocks pass through. An author analysis tag wins per key; the generator fills gaps. output.comments: false drops the prose and keeps the directives and the analysis tags.

The compiler does not run PHPStan or Psalm. The full spelling and merge rules are on Emitted Docblocks.

Lowering protocols (index)

Brief map from Tyhp construct → PHP runtime pattern. Goldens live under the conformance suite; prefer those over re-deriving internals from this page.

A thin index suite lives under tests/conformance/story15/ (operators, extensions, generics erasure, structs, disposables, async, expression trees). Fuller emit coverage remains in tests/conformance/story11/ and tests/conformance/story14_5/ — see the conformance README.

Compatibility policy

• Additive changes (new optional runtime helpers the emitter does not yet call, new convertible targets that do not rename existing methods) may ship without bumping interopContractVersion. A minor bump is optional documentation hygiene.
• Breaking changes — any rename or signature change of an emitted call, synthetic method, or required FQN — require bumping interopContractVersion on the compiler (InteropContract.CurrentVersion) and on every affected runtime package’s extra.tyhp.interopContractVersion.
• PHP matrix — which PHP minor a release supports is coordinated with the tyhpdef/php / tyhpdef/php-ext-* packages and the PHP-encoded compiler MAJOR in VERSIONING.md. Contract bumps and MAJOR bumps are independent axes; both may move in the same release when an ABI and a PHP target change together.

Machine-checkable surface

InteropContractSurface enumerates emitter-required runtime symbols (the contract surface). Conformance tests assert that each symbol is declared — with the documented namespace and keyword — in the owning package’s committed package.tyhpdef. The tyhpdef is the checked source of truth because emitted src/ PHP is regenerated (and dist/ is not committed).