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 Composer names under runtime/packages/.

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, future emit, and self-host):

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

Phase 1 emit ABI: when a call argument targets PropertyPath<callable(T): R> and the argument is an inline property-chain fn, the emitter lowers to:

new \Tyhp\PropertyPath(
    \SourceType::class,   // or a builtin type string such as 'string'
    'resultTypeString',
    ['segment', /* … */],
    fn (/* … */) => /* original chain */
);

Constructor shape (required): (string $sourceType, string $resultType, array $path, \Closure $callable, bool $allowEmpty = false, array $nullSafeFlags = []). Call sites omit $allowEmpty.

A chain containing ?-> additionally passes the per-segment flags by name, so the runtime builds NullSafeAccessExpression nodes instead of PropertyAccessExpression for those segments:

new \Tyhp\PropertyPath(
    \User::class,
    '?string',
    ['address', 'city'],
    fn (\User $u): ?string => $u?->address?->city,
    nullSafeFlags: [true, true],
);

Phase 2 emit ABI: when a call argument targets Expression<callable(T): R> and the argument is an inline arrow fn, the emitter lowers to a root Expression plus nested node constructors (additive — no contract version bump):

new \Tyhp\Expression(
    body: new \Tyhp\Expression\BinaryExpression(
        new \Tyhp\Expression\PropertyAccessExpression(
            new \Tyhp\Expression\ParameterExpression('u', \User::class, 0),
            'age',
            'int'
        ),
        '>',
        new \Tyhp\Expression\ConstantExpression(18, 'int'),
        'bool'
    ),
    parameters: [
        new \Tyhp\Expression\ParameterExpression('u', \User::class, 0),
    ],
    callable: fn (\User $u) => $u->age > 18,
    returnType: 'bool'
);

Supported nested FQNs include ParameterExpression, PropertyAccessExpression, NullSafeAccessExpression, MethodCallExpression, StaticMethodCallExpression, BinaryExpression, UnaryExpression, ConstantExpression, TernaryExpression, CoalesceExpression, ArrayAccessExpression, CastExpression, NewExpression, and InstanceofExpression (Phase 3 — $x is T / $x instanceof T). Captured outer variables emit as ConstantExpression($var, $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; emit still constructs new \Tyhp\Expression(...). No contract version bump.

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.

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).

Runtime self-host (recompile runtime/packages/*/tyhp_src and diff against committed PHP) consumes this list once the self-host allowlist is green. Documenting or version-stamping the contract does not wait on that milestone.