semantifold 0.13.0 → 0.15.0

package/docs/adr-bounded-subtyping.md

@@ -0,0 +1,180 @@
+# ADR: Bounded subtyping — nominal interfaces with exact implementation contracts
+
+- Status: `accepted` (adopted for PHP in this issue's implementation; the remaining cohort languages land per the follow-up plan below)
+- Issue: STOE-60 (Semantifold core — inheritance, interfaces and trait/mixin composition beyond closed reference classes)
+- Depends on: Task 033 reference classes (`docs/language-support.md`, `todo/033-reference-classes-methods-and-constructors.md`) for the closed nominal class, receiver, privacy, and initialization model this ADR extends and never weakens.
+
+## Context
+
+Task 033 delivered closed reference classes: nominal identities, private mutable state, one exact constructor, a closed method set, and purely nominal closed dispatch. Inheritance, interfaces, traits/mixins, reopening, and virtual/dynamic dispatch are explicitly excluded, so no polymorphic domain model can be expressed: a function parameter, return, local, or collection can only name one concrete class, and there is no way to state a shared method contract across classes.
+
+The repository's guiding principles (AGENTS.md, `todo/README.md`) constrain the design:
+
+1. Model meaning once: the semantic IR carries types and resolution facts, never target spelling.
+2. Fail loudly: a target that cannot honor a contract reports `UNSUPPORTED_CAPABILITY` before any partial artifact.
+3. Prefer a precise portable profile: dispatch, override, and visibility rules require explicit contracts, not symbol substitution.
+4. No structural substitution: a lookalike never satisfies a nominal type.
+5. Task 033 semantics are frozen: freshness, exact-once field initialization, receiver-before-argument order, declaring-receiver privacy, and aliasing-not-copying stay exactly as delivered.
+
+This ADR decides the shape of subtyping. Per-language source spellings, generated shapes, and acceptance corpora are separate per-language specs (see Follow-ups).
+
+## Decision 1 — Interfaces with exact implementation contracts; no class-to-class inheritance
+
+The admitted model is **nominal interfaces plus exact `implements` contracts**. A class may implement one or more interfaces; a class never extends another class, and there are no abstract classes, superclass constructors, inherited fields, inherited methods, or `super` calls.
+
+Rationale:
+
+- The polymorphism that domain models actually need — a shared method contract behind parameter/return/local/collection positions — is fully expressible with interfaces; implementation inheritance mostly buys code reuse, which the model can later supply through composition (holding records or references as private fields) without inheriting state or construction semantics.
+- Implementation inheritance collides with Task 033's construction contract: "exactly one constructor" and "every field initialized exactly once before the reference escapes" do not survive parent-constructor chaining, inherited private fields, or partial initialization across a class hierarchy.
+- Ruby has single class inheritance but no native interface construct, JavaScript has `extends`/`class` but no nominal interface, and PHP/Java/TypeScript have both — a class-inheritance contract would be the least common denominator and would import constructor-chaining and visibility-variance questions this model does not need.
+- Excluding class inheritance keeps the class cohort closed and enumerable per module, which is what makes the override contract statically checkable.
+
+`extends` in the admitted grammar means **interface-extends-interface only** (Decision 3). Every source spelling of class-to-class `extends`, `super`, abstract classes, and inherited members remains `UNSUPPORTED_SYNTAX`, exactly as today.
+
+## Decision 2 — `InterfaceDeclaration` is a closed signature-only nominal type
+
+The semantic IR gains:
+
+```
+InterfaceDeclaration
+  kind: "InterfaceDeclaration"
+  id?: string                 // stable module-local identity (`interface:N`), required after validation
+  name: string                // source-visible name
+  extends?: InterfaceType[]   // direct interface parents in source order; omitted when empty
+  methods: InterfaceMethodDeclaration[]   // ordered closed signature set
+
+InterfaceMethodDeclaration
+  kind: "InterfaceMethodDeclaration"
+  id?: string                 // stable interface-scoped identity (`interface:N:method:N`), required after validation
+  name: string
+  parameters: Parameter[]     // exact positional required parameters with explicit types
+  returnType: SemanticFunctionReturnType   // explicit value or void return
+
+InterfaceType
+  kind: "InterfaceType"
+  declarationId: string       // exact interface declaration identity
+```
+
+`ClassDeclaration` gains an optional `implements?: InterfaceType[]` member (source order; omitted when empty) and each `MethodDeclaration` gains an optional resolved `implements?: {interfaceId: string, methodId: string}` fact after validation.
+
+Hard rules:
+
+- Interfaces carry **no fields, no constructors, no static members, and no method bodies**. A body on an interface method (PHP/Python/Go-style default methods) is `UNSUPPORTED_SYNTAX`.
+- Interface method signatures are explicit and complete exactly like Task 033 method signatures: named parameters, explicit types, explicit value-or-void return. No optional parameters, no defaults, no overloads, no variadics.
+- Interface names join the existing nominal-name registry: one interface name per module, unique against classes, records, errors, functions, and other interfaces, and against the target reserved-name/collision baselines Task 033 already enforces.
+- `InterfaceType` joins `SemanticValueType` and composes with the existing type grammar exactly like `ReferenceType`: parameters, returns, locals, list/map/ordered-map/optional constituents.
+
+## Decision 3 — Interface composition is a closed extends DAG
+
+An interface may extend zero or more interfaces. The transitive method set is the flattened union in deterministic declaration order (parents first, then the interface's own methods, in source order). Cycles, duplicate inherited names, and a redeclared method whose signature differs from the inherited one are located diagnostics (`INTERFACE_CYCLE`, `INTERFACE_MEMBER_DUPLICATE`). Interface-to-interface `extends` is the only admitted `extends` spelling.
+
+## Decision 4 — The override contract is exact and total
+
+A class with `implements [I1..In]` must supply, in its own closed method set, exactly one method matching each flattened interface signature:
+
+- exact name, exact ordered parameter types, exact arity, exact return type (value type or void — never widened or narrowed);
+- no interface method may be private to the class (visibility rules per Decision 7);
+- duplicate class methods satisfying the same interface member, a missing member, a signature mismatch, and an arity mismatch are located diagnostics (`INTERFACE_MEMBER_MISSING`, `INTERFACE_MEMBER_SIGNATURE_MISMATCH`), reported before any writer allocation;
+- a class may implement several interfaces, and one class method may satisfy several interfaces' identical signatures;
+- interface method names follow the same target preflight rules as Task 033 method names (for example Ruby target preflight still rejects setter-style names ending in `=`).
+
+The contract is checked at the declaration, once, statically. Nothing about it is deferred to runtime.
+
+## Decision 5 — Dispatch is nominal at the call site; the target's native lookup selects the implementation
+
+`MethodCallExpression` on an `InterfaceType` receiver resolves against the **interface's flattened signature set**: the resolved `ResolvedMethodSignature` records the declaring interface identity and the exact signature, exactly as Task 033 records the declaring class. Call-site validation never inspects which concrete classes exist.
+
+At runtime the target's own native method lookup performs the selection (PHP interface dispatch, Ruby module inclusion, JavaScript prototype lookup, TypeScript compile-time erasure plus native lookup, Java virtual dispatch). This is target-native lowering, not a Semantifold dispatch model: the semantic IR carries no dispatch tables, virtual slots, method objects, vtables, or message sends, and Semantifold never resolves a method against a concrete class behind an interface receiver. Two classes implementing the same interface produce byte-identical generated call sites.
+
+Explicitly still excluded (unchanged from Task 033): computed/dynamic method names, `send`/`apply`/`public_send`, `method_missing`, function-valued "lambdas stored in fields", reflection, and any construct that turns a method name into a runtime value.
+
+## Decision 6 — Value flow: implicit upcast only, no casts, no type tests
+
+- A `ReferenceConstruction` of class `C` is assignable to an `InterfaceType` `I` (and to `J`) exactly when `C implements` includes `I` (or a transitively extended `J`). This is the only admitted widening, and it is checked statically at every assignment, argument, return, and collection-element position.
+- An interface-typed value never flows back to a class type or to a narrower interface: there are no downcasts, no `as`/`instanceof`/`is_a?`/`is`/`kind_of?`/type predicates on interface receivers, no exhaustive switch over implementations, and no runtime type queries of any kind. The existing general exclusion of casts/assertions stands.
+- Interface-typed locals require the same explicit type carriers Task 033 requires wherever the source language does not enforce them (JSDoc `@type`, Ruby type comments, etc.).
+- Task 033 identity semantics carry over unchanged: interface-typed bindings alias the same fresh instance; there is still no identity equality, hashing, ordering, cloning, or serialization.
+
+## Decision 7 — Visibility and encapsulation
+
+- Interface members are public to the module cohort by definition; the implementing class method must be public in the language profile (Java package-private follows the existing Task 033 Java profile: package-private interface, package-private implementing class methods).
+- Private fields remain declaring-class-only through the semantic receiver. An interface receiver can never reach any field: `PrivateFieldRead`/`PrivateFieldWriteStatement` remain valid only on the declaring-class `ReceiverExpression` inside the declaring class, never on an interface-typed binding.
+- Interfaces do not constrain a class's private state or extra methods: a class may have any Task 033-legal fields and methods beyond its interface contract.
+
+## Decision 8 — Capability, cohort, and fail-loud boundaries
+
+The registry gains one capability flag `boundedSubtyping`, valid only where `referenceClasses: true` (a language cannot advertise interfaces before it advertises closed reference classes). Adoption order follows the existing cohort discipline:
+
+1. **Original five first** (PHP, Ruby, JavaScript/JSDoc, TypeScript, Java) — the Task 033 cohort, in the same single-module scope Task 033 shipped with. PHP is adopted today; Ruby, JavaScript/JSDoc, TypeScript, and Java keep `boundedSubtyping: false` until their per-language interface profiles land.
+2. **Each Wave-2 language when it adopts `referenceClasses`** (Kotlin, Python, C#, Go, Rust, Swift, Dart, then C/C++ and Zig as their reference-class lanes land), each with its own exact native profile spec.
+
+A language that advertises `boundedSubtyping: false` — today every language outside the original five, plus browser Wasm, Android/Flutter/iOS application roles until their lanes say otherwise — rejects any interface-bearing module transactionally with `UNSUPPORTED_CAPABILITY` before source, bytes, or a partial artifact set is exposed, exactly as non-cohort languages reject Task 033 class IR today.
+
+## Decision 9 — Explicit permanent exclusions
+
+Unless a future ADR admits them, all of the following stay out of the model and stay `UNSUPPORTED_SYNTAX`/`UNSUPPORTED_CAPABILITY`:
+
+- class-to-class inheritance, abstract classes, `super`, inherited constructors/fields/methods, constructor chaining;
+- multiple implementation inheritance, mixins/traits with state or behavior, Ruby module `prepend`/refinement, JavaScript prototype mutation, Python MRO beyond a single base;
+- reopening, monkey-patching, duck typing, structural interface satisfaction, implicit interface conformance without an explicit `implements` declaration;
+- default/implemented interface methods, static or constant interface members, interface generics (until Task 012 generics compose with interfaces in a separate decision), variance annotations (interfaces are invariant);
+- downcasts, type tests, exhaustive matching over implementors, runtime type inspection, reflection;
+- virtual/dynamic sends beyond the target's own closed native lookup for a statically resolved interface method (Decision 5);
+- identity equality/hashing/ordering, serialization, cloning, destructors, async interface methods, concurrency.
+
+## Per-language source profiles (exact native forms)
+
+Frontends recognize exactly one canonical spelling per language and account for every parser child, modifier, and annotation; anything else is `UNSUPPORTED_SYNTAX`.
+
+| Language | Interface declaration | Implementation | Interface-typed binding |
+| --- | --- | --- | --- |
+| PHP | `interface Name { public function m(T $p): R; }` (signature only) | `final class C implements I1, I2` | native parameter/return/local types |
+| Ruby | `interface Name` declaration with per-method type-comment signatures (compiler-qualified spelling, mirroring the bounded RBS-style convention) | `class C` with `include Name` and matching `def` bodies | type comments, as Task 033 |
+| JavaScript/JSDoc | `/** @interface */` class-shaped signature scaffold with complete `@param`/`@return` per method | `@implements {Name}` on the Task 033 canonical class | JSDoc `@type` carriers |
+| TypeScript | `interface Name { m(p: T): R }` (non-exported, signature only) | `class C implements I1, I2` (Task 033 canonical class body) | native type annotations |
+| Java | package-private `interface Name { R m(T p); }` | package-private `final class C implements I1, I2` (Task 033 canonical class) | native types, `Main.java` contract unchanged |
+| Python (Wave 2) | `typing.Protocol`-shaped method stubs with full annotations | explicit inheritance of the protocol base in the class header | annotations |
+| C# (Wave 2) | `interface IName { R M(T p); }` | `sealed class C : I1, I2` | native types |
+| Go (Wave 2) | named `type I interface { M(p T) R }` method set | method-set satisfaction proven against the explicit named interface declaration only | named interface type |
+| Rust (Wave 2) | `trait I { fn m(&self, p: T) -> R; }` with explicit `impl I for C` | `impl I for C` blocks | trait-object position decided per spec (no dynamic dispatch unless the spec pins a closed form) |
+| Swift (Wave 2) | `protocol IName { func m(_ p: T) -> R }` | `final class C: I1, I2` | native protocol types |
+| Kotlin (Wave 2) | `interface IName { fun m(p: T): R }` | `class C : I1, I2` | native types |
+| Dart (Wave 2) | `abstract class IName { R m(T p); }` signature-only form | `class C implements I1, I2` | native types |
+| C / C++ / Zig | no conformant native interface construct in the current profiles — remain excluded until a per-language spec decides a compiler-owned closed dispatch shape | — | — |
+
+## Per-target backend representations
+
+Backends emit the target's native interface construct and native call spelling from validated semantic nodes; they never erase an interface into a map, function table, or tagged union.
+
+| Target | Representation |
+| --- | --- |
+| PHP | native `interface` + `implements`; typed signatures |
+| Ruby | compiler-owned generated `module Name` with the contract documented and `include Name` on the class; method bodies remain the class's own |
+| JavaScript | JSDoc `@interface`/`@implements` scaffold plus native method calls (nominal guarantee lives in the compiler, generated code stays plain ES) |
+| TypeScript | native `interface` + `implements` |
+| Java | package-private `interface` + `implements`; single-file `Main.java` composition rules extended to nested interfaces |
+| Python / C# / Go / Rust / Swift / Kotlin / Dart | native protocol/interface/trait/protocol/interface/abstract-class forms per the Wave-2 specs; each spec pins the exact dispatch lowering and proves it with real toolchains |
+| C / C++ / Zig / browser Wasm / application roles | `UNSUPPORTED_CAPABILITY` for interface-bearing IR until their lanes admit it |
+
+Backend preflight revalidates the complete interface graph — identities, flattened method sets, override contracts, name collisions against target baselines, receiver types, and upcast legality — before writer allocation, and generated code reparses to the same interface/member identities wherever the target has a reparse lane.
+
+## Diagnostics
+
+New stable codes, all located and all raised before artifact exposure: `DUPLICATE_INTERFACE`, `UNKNOWN_INTERFACE`, `INTERFACE_CYCLE`, `INTERFACE_MEMBER_DUPLICATE`, `INTERFACE_MEMBER_MISSING`, `INTERFACE_MEMBER_SIGNATURE_MISMATCH`, `INTERFACE_NAME_COLLISION`, `INTERFACE_TYPE_MISMATCH` (illegal upcast/assignment), `INTERFACE_RECEIVER_INVALID` (non-interface receiver or private-field reach through an interface binding). Malformed caller-owned IR reports the existing transactional `UNSUPPORTED_CAPABILITY`/`TYPE_MISMATCH` family. Frontends locate excluded inheritance, `super`, reopened classes, default methods, implicit conformance, and type tests as `UNSUPPORTED_SYNTAX`.
+
+## Rejected alternatives
+
+- **Single-root class inheritance with virtual dispatch** (PHP/Java/TypeScript-shaped): rejected by Decision 1 — it reopens constructor chaining, partial initialization, inherited private state, and visibility variance, and its least-common-denominator across Ruby/JavaScript profiles is weaker than the interface contract.
+- **Interface-only composition without interface `extends`**: rejected as unnecessarily restrictive; a closed extends DAG is statically checkable and native in every cohort language.
+- **Structural/duck typing**: rejected outright — it violates the repository's nominal-typing principle and cannot be validated fail-loudly.
+- **Composition-only (no subtyping; hand adapters)**: rejected as insufficient — it cannot express polymorphic parameters, which is the gap this issue names.
+
+## Follow-ups
+
+1. Semantic IR/validation: `InterfaceDeclaration`/`InterfaceMethodDeclaration`/`InterfaceType`, `implements` on classes, registry `boundedSubtyping` flag, shared acceptance/rejection specs (one top-level `describe` per spec file).
+2. Original-five frontend/backend per-language specs: exact source spellings, generated shapes, reparse proofs, and real-toolchain execution (PHP, Ruby, Node, `tsc`, `javac`/`java`) including override-contract negatives.
+3. Wave-2 per-language specs as each language's `referenceClasses` lane lands.
+4. Docs: extend the Task 033 section of `docs/language-support.md` with the admitted interface profile once implemented.
+5. Real-toolchain acceptance and exact-head TensorBuzz CI per the repo gates.
+
+Recorded as roadmap task [048 — Bounded subtyping implementation](../todo/048-bounded-subtyping-implementation.md).

package/docs/goals.md

@@ -2,7 +2,7 @@
 
 Semantifold's long-term goal is a language-neutral toolkit for understanding, transforming, generating, and eventually executing programs through a shared high-level semantic representation. The representation should make types, control flow, calls, declarations, diagnostics, and source provenance understandable without exposing a language parser's private tree.
 
-The current source tree proves one minimal Tasks 001–004 vertical slice across fifteen registered source languages: PHP, Ruby, JavaScript, TypeScript, Java, Kotlin/JVM, strictly annotated Python, canonical C#, bounded Go, C17, C++20, Rust edition 2021, Swift, Dart, and Zig. Dart and Zig additionally implement the bounded Task 005 required-function/call profile; the original five retain the delivered Task 013 acceptance gate for the combined Tasks 001–008 profile, Task 009 nominal closed records, Task 010 explicit acyclic multi-source semantic programs, Task 011 exact nominal typed unchecked errors, and Task 012 invariant unbounded function/record type parameters with closed applications and argument-only first-order call inference. Task 014 is delivered through PR #41, Task 032 through PR #42, Task 033 through PR #43, and Task 034 through PR #44. Task 035 is delivered through PR #45 and merge commit `a2aad9d4932bfc6087adc4ff8bca43678c92413c`, with versioned canonical standard-library contracts, target host providers and protected native bindings, capability negotiation, and program-mode provider linking. Task 036 is delivered through PR #46 and merge `9aba48f9d48bcef4fd4c9275aec14bfcc4f0904c`; it adds bounded versioned executable qualification facades and exact parser-backed native identity resolution for the original five. Task 037 adds only the first concrete Ruby-source-to-PHP-target blocking TCP/line-output slice on those foundations. The source tree includes versioned source provenance, deterministic semantic node/symbol identity, range-based generated mappings, Source Map v3 interop, composition, and diagnostic remapping across those bounded profiles. The published `semantifold@0.6.0` and annotated `v0.6.0` target exact commit `f76e6d64b388d65959e77f747ae2d60a999d61f5`, including Task 028 from PR #51 and Task 031 from PR #52. Neither the source tree nor that release provides a general analyzer, transformation API, interpreter, optimizer, implicit project/package discovery, debugger integration, coverage remapping, or lossless formatter.
+The current source tree proves one minimal Tasks 001–004 vertical slice across fifteen registered source languages: PHP, Ruby, JavaScript, TypeScript, Java, Kotlin/JVM, strictly annotated Python, canonical C#, bounded Go, C17, C++20, Rust edition 2021, Swift, Dart, and Zig. C, Dart, Zig, and Python additionally implement the bounded Task 005 required-function/call profile; the original five retain the delivered Task 013 acceptance gate for the combined Tasks 001–008 profile, Task 009 nominal closed records, Task 010 explicit acyclic multi-source semantic programs, Task 011 exact nominal typed unchecked errors, and Task 012 invariant unbounded function/record type parameters with closed applications and argument-only first-order call inference. Task 014 is delivered through PR #41, Task 032 through PR #42, Task 033 through PR #43, and Task 034 through PR #44. Task 035 is delivered through PR #45 and merge commit `a2aad9d4932bfc6087adc4ff8bca43678c92413c`, with versioned canonical standard-library contracts, target host providers and protected native bindings, capability negotiation, and program-mode provider linking. Task 036 is delivered through PR #46 and merge `9aba48f9d48bcef4fd4c9275aec14bfcc4f0904c`; it adds bounded versioned executable qualification facades and exact parser-backed native identity resolution for the original five. Task 037 adds only the first concrete Ruby-source-to-PHP-target blocking TCP/line-output slice on those foundations. The source tree includes versioned source provenance, deterministic semantic node/symbol identity, range-based generated mappings, Source Map v3 interop, composition, and diagnostic remapping across those bounded profiles. The published `semantifold@0.6.0` and annotated `v0.6.0` target exact commit `f76e6d64b388d65959e77f747ae2d60a999d61f5`, including Task 028 from PR #51 and Task 031 from PR #52. Neither the source tree nor that release provides a general analyzer, transformation API, interpreter, optimizer, implicit project/package discovery, debugger integration, coverage remapping, or lossless formatter.
 
 The long-term product direction includes bounded standard-library portability through [language compatibility stdlib/facades, canonical Semantifold stdlib contracts/capabilities, and target host providers/native bindings](standard-library-portability.md). That direction is incremental and versioned; it does not promise arbitrary standard-library coverage or arbitrary-application translation. The `0.3.0` release has no imports, classes or methods, loops, optional values, typed errors, resources, host APIs, or stdlib portability.
 

package/docs/language-support.md

@@ -12,7 +12,7 @@ The immutable registry is authoritative for both dispatch and discovery:
 | `typescript` | yes | yes | no | no | no | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | single | yes | rich + v3 | parse, generate, compile, execute (`tsc`, `node`) |
 | `java` | yes | yes | no | no | no | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | single | yes | rich + v3 | parse, generate, compile, execute (`javac`, `java`) |
 | `kotlin` | yes | yes | no | no | no | no | no | no | no | no | no | no | no | no | no | no | single | yes | rich + v3 | parse, generate, compile, execute (`kotlinc`, `java25`) |
-| `python` | yes | yes | no | no | no | no | no | no | no | no | no | no | no | no | no | no | single | yes | rich + v3 | parse, generate, compile, execute (`python3`) |
+| `python` | yes | yes | no | no | no | yes | no | no | no | no | no | no | no | no | no | no | single | yes | rich + v3 | parse, generate, compile, execute (`python3`) |
 | `csharp` | yes | yes | no | no | no | no | no | no | no | no | no | no | no | no | no | no | multiple | yes | rich + v3 | parse, generate, restore, compile, execute (`dotnet`) |
 | `go` | yes | yes | no | no | no | no | no | no | no | no | no | no | no | no | no | no | multiple | yes | rich + v3 | parse, generate, compile, validate, execute (`go`) |
 | `cpp` | yes | yes | no | no | no | no | no | no | no | no | no | no | no | no | no | no | single | yes | rich + v3 | parse, generate, compile, link, execute (`clangpp`, native executable) |
@@ -84,7 +84,7 @@ The shared negative corpus covers parser recovery, missing types, truthiness, mi
 
 ## Task 005 general functions and calls
 
-PHP, Ruby, JavaScript with JSDoc, TypeScript, Java, C, Dart, and Zig accept any number of required positional parameters, including zero. The module resolver collects every unique function signature before validating bodies, assigns declarations deterministic `function:N` identities, and binds each direct call to that identity plus its ordered parameter and return types. This permits forward calls, nested calls, direct recursion, and unambiguous mutual recursion without overload or dynamic dispatch. Arity and every positional scalar type must match exactly.
+PHP, Ruby, JavaScript with JSDoc, TypeScript, Java, C, Dart, Zig, and Python accept any number of required positional parameters, including zero. The module resolver collects every unique function signature before validating bodies, assigns declarations deterministic `function:N` identities, and binds each direct call to that identity plus its ordered parameter and return types. This permits forward calls, nested calls, direct recursion, and unambiguous mutual recursion without overload or dynamic dispatch. Arity and every positional scalar type must match exactly.
 
 Function returns are `integer`, `boolean`, `string`, or `void`. A non-void function has an expression on every reachable return and returns on every reachable path. A void function may fall through or use a bare return, and its call is legal only as an `ExpressionStatement`. Void is never a value: it cannot type a parameter or local, initialize or assign a binding, become an argument or operand, be printed, or be returned as a value. Generation revalidates declaration identities and complete resolved signatures in externally supplied IR. Function names, parameters, return annotations, callees, arguments, and resolution references retain deterministic parser-backed provenance and mappings.
 
@@ -97,8 +97,9 @@ The source profiles remain deliberately exact:
 - C accepts file-scope `static` semantic functions with any number of explicitly typed named parameters — spelled `void` for an empty list — exact scalar or `void` returns, and unqualified direct calls. A `static` prototype may precede a definition for forward or mutual recursion and must agree exactly with its unique definition; a prototype without a definition, a conflicting prototype, an implicit declaration, a bare return in a non-void function, or `void` used as a parameter, local, argument, operand or printed value is rejected. Generated zero-parameter signatures spell `(void)` and generated prototypes make forward calls and recursion compilable under `-Wstrict-prototypes`/`-Wmissing-prototypes`. See [C source and target](c.md).
 - Dart accepts synchronous top-level functions with exact explicit `int`, `bool`, `String`, or `void` returns, explicitly typed required positional parameters, initialized typed locals, direct calls, and exact `void main()`/`print`. Inference, `var`, inferred `final`, optional/named/default arguments, methods/classes, generics, imports, dynamic/nullability, collections, exceptions, async, and isolates are rejected. Generated Dart alone may contain formatter-added trailing commas and the complete canonical private runtime prefix; neither grants those forms to ordinary source. See [Dart source and target](dart.md).
 - Zig accepts top-level functions with exact explicit `i64`, `bool`, `[]const u8`, or `void` returns, explicitly typed required positional parameters, initialized typed `const`/`var` locals, direct calls, and the exact generated support/`pub fn main()` shell. Inference, optional/default/rest parameters, methods, containers, user slices/pointers/allocators, imports beyond the canonical standard-library support, error unions, `comptime`, generics, reflection, FFI, async, and concurrency are rejected. See [Zig source and target](zig.md).
+- Python accepts synchronous top-level `def` functions with any number of explicitly `int`/`bool`/`str`-annotated required positional parameters and an exact `int`/`bool`/`str` or `None` return annotation, where `None` is the only void spelling. A void function may fall through or use a bare `return`, and its call is legal only as a top-level or block statement expression. Direct calls are identifier callees with positional arguments only; forward calls, direct recursion, and unambiguous mutual recursion resolve exactly. Default, positional-only, keyword-only, variadic, starred, or unannotated parameters, keyword or starred call arguments, nested function declarations, and every dynamic callee form remain rejected; a value `return` inside a `-> None` function fails with `VOID_RETURN_VALUE`.
 
-Python, C#, C++, Rust, Swift, Kotlin/JVM, Go, and browser Wasm remain on their Task 025 Tasks 001–004 profile. Their registry feature flag is false, their existing exact-two/scalar-return behavior is unchanged, and a Task-005-only arity, void return, or void call statement is a located `UNSUPPORTED_CAPABILITY` before source, bytes, or a partial artifact set is exposed. This boundary does not broaden the future Task 013 aggregate acceptance.
+C#, C++, Rust, Swift, Kotlin/JVM, Go, and browser Wasm remain on their Task 025 Tasks 001–004 profile. Their registry feature flag is false, their existing exact-two/scalar-return behavior is unchanged, and a Task-005-only arity, void return, or void call statement is a located `UNSUPPORTED_CAPABILITY` before source, bytes, or a partial artifact set is exposed. This boundary does not broaden the future Task 013 aggregate acceptance.
 
 ## Task 006 immutable lists and maps
 
@@ -170,7 +171,7 @@ Construction arguments evaluate left to right and all fields must be initialized
 
 The source profiles are intentionally exact. TypeScript uses non-exported classes with explicit `private` fields, one unmodified constructor, and ordinary typed instance methods. JavaScript uses native `#private` fields with adjacent complete JSDoc on fields, constructor parameters, method parameters/returns, and reference-typed bindings. PHP uses `final class`, explicit private typed properties, one public `__construct`, and public typed instance methods. Ruby uses a closed class body with one documented `initialize`; its ordered required parameters initialize the correspondingly named instance variables, and every ordinary method has complete adjacent type comments. Ruby target preflight rejects setter-style method names ending in `=` because native setter invocation returns the assigned argument independently of the method body. Java uses a package-private `final class` with explicit private mutable fields, one package-private constructor, package-private ordinary typed methods, and a separate canonical public `Main`; when a reference method calls a semantic function, generated package-visible static `Main` methods and explicit `Main.method(...)` calls preserve access and evaluation order. All five generated forms reparse to the same semantic class/member identities and execute through the real registered toolchains.
 
-Inheritance, interfaces, traits/mixins, class reopening or monkey-patching, prototypes, decorators/annotations, static/singleton members, computed or dynamic sends, overloads, virtual/duck dispatch, arbitrary host construction, reflection and host lifecycle/protocol hooks, public mutable fields, private access from outside the declaring receiver, identity equality/hashing/ordering, cloning, serialization, finalizers, generic or async methods/classes, and concurrency remain excluded. Constructors and methods may catch Task 011 errors internally but cannot expose an unchecked-error effect through a receiver call; that cross-feature effect contract is not invented by Task 033. Kotlin, Python, C#, Go, C, C++, Rust, Swift, and browser Wasm advertise `referenceClasses: false` and reject class-bearing modules transactionally. Task 033 is single-module: `parseProgram` and `generateProgramArtifactSet` reject class-bearing Task 010 modules before resolution or artifact allocation. It adds no Task 034 resource/effect model and no standard-library contract, facade, provider, or pairwise rewrite.
+Inheritance, interfaces, traits/mixins, class reopening or monkey-patching, prototypes, decorators/annotations, static/singleton members, computed or dynamic sends, overloads, virtual/duck dispatch, arbitrary host construction, reflection and host lifecycle/protocol hooks, public mutable fields, private access from outside the declaring receiver, identity equality/hashing/ordering, cloning, serialization, finalizers, generic or async methods/classes, and concurrency remain excluded. The bounded subtyping model that extends this cohort — nominal interfaces with exact `implements` override contracts and no class-to-class inheritance — is decided in the [bounded subtyping ADR](adr-bounded-subtyping.md). It is adopted for PHP only today (`boundedSubtyping: true`); Ruby, JavaScript, TypeScript, and Java keep `boundedSubtyping: false` until their per-language interface profiles land, and every other target rejects interface-bearing modules transactionally. Nothing in that ADR changes the Task 033 semantics documented above. Constructors and methods may catch Task 011 errors internally but cannot expose an unchecked-error effect through a receiver call; that cross-feature effect contract is not invented by Task 033. Kotlin, Python, C#, Go, C, C++, Rust, Swift, and browser Wasm advertise `referenceClasses: false` and reject class-bearing modules transactionally. Task 033 is single-module: `parseProgram` and `generateProgramArtifactSet` reject class-bearing Task 010 modules before resolution or artifact allocation. It adds no Task 034 resource/effect model and no standard-library contract, facade, provider, or pairwise rewrite.
 
 ## Task 034 effectful capabilities and owned resource lifetime
 

package/docs/testing.md

@@ -36,7 +36,7 @@ These tests generate and publish source artifacts only. They do not run `javac`,
 
 ## Task 005 general function signatures and calls
 
-Task 005 stays bounded to PHP, Ruby, JavaScript with JSDoc, TypeScript, Java, Dart, Zig, and C. `general-function-signatures-and-calls.spec.js` proves equivalent zero-, one-, and three-parameter signatures, complete signature collection, nested calls, terminating recursion, scalar/void returns, and the stable semantic failures. `general-function-frontend-validation.spec.js` owns the excluded parameter, call, method, receiver, dispatch, annotation, overload, generic, and higher-order source forms. `general-function-backend-validation.spec.js` proves generation/reparse, exact external-IR signature revalidation, target conflicts, the public feature flag, and transactional rejection from every deferred Task 025/Wasm target. `general-function-provenance-and-mapping.spec.js` proves deterministic declaration/resolution identities and exact signature/call mappings. `general-function-runtime-execution.spec.js` invokes real PHP, Ruby, Node, local `tsc` followed by Node, `javac`, and `java`, requiring exact `ready\n6\n` output; a missing command fails. `c-task005-acceptance.spec.js` proves the C cohort extension: generated-C reparse with identical meaning, the C fixture through every original-five text target, and real Clang execution of each original-five Task-005 fixture and the C fixture at `-O0`/`-O2` with and without sanitizers, including prototype-mediated mutual recursion and bare void returns.
+Task 005 stays bounded to PHP, Ruby, JavaScript with JSDoc, TypeScript, Java, Dart, Zig, C, and Python. `general-function-signatures-and-calls.spec.js` proves equivalent zero-, one-, and three-parameter signatures, complete signature collection, nested calls, terminating recursion, scalar/void returns, and the stable semantic failures across the six source fixtures, including `fixtures/functions/program.py`. `general-function-frontend-validation.spec.js` owns the excluded parameter, call, method, receiver, dispatch, annotation, overload, generic, and higher-order source forms. `general-function-backend-validation.spec.js` proves generation/reparse, exact external-IR signature revalidation, target conflicts, the public feature flag, and transactional rejection from every deferred Task 025/Wasm target. `general-function-provenance-and-mapping.spec.js` proves deterministic declaration/resolution identities and exact signature/call mappings. `general-function-runtime-execution.spec.js` invokes real PHP, Ruby, Node, local `tsc` followed by Node, `javac`, `java`, and `python3`, requiring exact `ready\n6\n` output; a missing command fails. `c-task005-acceptance.spec.js` proves the C cohort extension: generated-C reparse with identical meaning, the C fixture through every original-five text target, and real Clang execution of each original-five Task-005 fixture and the C fixture at `-O0`/`-O2` with and without sanitizers, including prototype-mediated mutual recursion and bare void returns.
 
 Run the Task 005 files individually and sequentially:
 
@@ -49,7 +49,7 @@ npx velocious-test spec/general-function-runtime-execution.spec.js
 npx velocious-test spec/c-task005-acceptance.spec.js
 ```
 
-Task 013 is the separate terminal original-five aggregate gate. Task 005 does not expand that matrix or adopt Python, C#, C++, Rust, Swift, Kotlin/JVM, Go, or browser Wasm beyond focused capability rejection.
+Task 013 is the separate terminal original-five aggregate gate. Task 013 is the separate terminal original-five aggregate gate. Task 005 does not expand that matrix or adopt C#, C++, Rust, Swift, Kotlin/JVM, Go, or browser Wasm beyond focused capability rejection.
 
 ## Task 011 typed errors and handling
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "semantifold",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Language-neutral semantic code analysis, transformation, generation, and execution toolkit",
   "type": "module",
   "main": "build/index.js",

package/src/backends/effects.js

@@ -266,6 +266,7 @@ function semanticTypeForIdentity(identity) {
   if (identity.kind == "RecordType") return {arguments: identity.arguments?.map(semanticTypeForValueIdentity),
     declarationId: identity.declarationId, kind: "RecordType"}
   if (identity.kind == "ReferenceType") return {declarationId: identity.declarationId, kind: "ReferenceType"}
+  if (identity.kind == "InterfaceType") return {declarationId: identity.declarationId, kind: "InterfaceType"}
   if (identity.kind == "OwnedResourceType") return {kind: "OwnedResourceType", resourceId: identity.resourceId}
   if (identity.kind == "OwnedReferenceType") return {declarationId: identity.declarationId, kind: "OwnedReferenceType"}
   return {kind: "TypeVariableReference", location: /** @type {never} */ (undefined), parameterId: identity.parameterId}

package/src/backends/php.js

@@ -15,6 +15,7 @@ export function generatePhp(module, writer) {
   emitEffectSupport(writer, module, "php")
   const records = module.records ?? []
   const classes = module.classes ?? []
+  const interfaces = module.interfaces ?? []
   const errors = module.errors ?? []
 
   errors.forEach((error, index) => {
@@ -72,6 +73,12 @@ export function generatePhp(module, writer) {
   })
   if (records.length > 0) writer.synthetic("\n\n", "record/function separator", [module])
 
+  interfaces.forEach((declaration, interfaceIndex) => {
+    if (interfaceIndex > 0) writer.synthetic("\n\n", "interface separator", [declaration], [`/interfaces/${interfaceIndex}`])
+    emitInterface(writer, declaration, interfaceIndex)
+  })
+  if (interfaces.length > 0) writer.synthetic("\n\n", "interface/class separator", [module])
+
   classes.forEach((declaration, classIndex) => {
     if (classIndex > 0) writer.synthetic("\n\n", "reference class separator", [declaration], [`/classes/${classIndex}`])
     emitReferenceClass(writer, declaration, classIndex)
@@ -156,6 +163,15 @@ function emitReferenceClass(writer, declaration, classIndex) {
   writer.mapped("final class", {mappingKind: "anchor", node: declaration, path})
   writer.synthetic(" ", "reference class spacing", [declaration], [path])
   writer.mapped(declaration.name, {mappingKind: "exact", node: declaration, path, role: "name"})
+  const implemented = declaration.implements ?? []
+
+  if (implemented.length > 0) {
+    writer.mapped(" implements ", {mappingKind: "anchor", node: declaration, path})
+    implemented.forEach((reference, referenceIndex) => {
+      if (referenceIndex > 0) writer.mapped(", ", {mappingKind: "anchor", node: declaration, path})
+      emitType(writer, reference, `${path}/implements/${referenceIndex}`, "php")
+    })
+  }
   writer.synthetic(" {\n", "reference class open", [declaration], [path])
   declaration.fields.forEach((field, index) => {
     const fieldPath = `${path}/fields/${index}`
@@ -191,6 +207,44 @@ function emitReferenceClass(writer, declaration, classIndex) {
   writer.mapped("}", {mappingKind: "anchor", node: declaration, path})
 }
 
+/**
+ * Emits one PHP native interface declaration with signature-only members.
+ * @param {import("./writer.js").SourceWriter} writer - Source-aware writer.
+ * @param {import("../semantic/types.js").InterfaceDeclaration} declaration - Semantic interface.
+ * @param {number} interfaceIndex - Declaration index.
+ * @returns {void}
+ */
+function emitInterface(writer, declaration, interfaceIndex) {
+  const path = `/interfaces/${interfaceIndex}`
+
+  writer.mapped("interface", {mappingKind: "anchor", node: declaration, path})
+  writer.synthetic(" ", "interface spacing", [declaration], [path])
+  writer.mapped(declaration.name, {mappingKind: "exact", node: declaration, path, role: "name"})
+  const parents = declaration.extends ?? []
+
+  if (parents.length > 0) {
+    writer.mapped(" extends ", {mappingKind: "anchor", node: declaration, path})
+    parents.forEach((parent, parentIndex) => {
+      if (parentIndex > 0) writer.mapped(", ", {mappingKind: "anchor", node: declaration, path})
+      emitType(writer, parent, `${path}/extends/${parentIndex}`, "php")
+    })
+  }
+  writer.synthetic(" {\n", "interface open", [declaration], [path])
+  declaration.methods.forEach((method, methodIndex) => {
+    const methodPath = `${path}/methods/${methodIndex}`
+
+    if (methodIndex > 0) writer.synthetic("\n", "line break", [method], [methodPath])
+    writer.synthetic("    public function ", "interface method scaffolding", [method], [methodPath])
+    writer.mapped(method.name, {mappingKind: "exact", node: method, path: methodPath, role: "name"})
+    emitPhpParameters(writer, method.parameters, `${methodPath}/parameters`)
+    writer.synthetic(": ", "interface method return separator", [method], [methodPath])
+    emitNativePhpType(writer, method.returnType, `${methodPath}/returnType`)
+    writer.mapped(";", {mappingKind: "anchor", node: method, path: methodPath})
+  })
+  writer.synthetic("\n", "line break", [declaration], [path])
+  writer.mapped("}", {mappingKind: "anchor", node: declaration, path})
+}
+
 /**
  * Emits one PHP parameter list.
  * @param {import("./writer.js").SourceWriter} writer - Source-aware writer.
@@ -355,7 +409,7 @@ function emitNativePhpType(writer, type, path) {
     })
     return
   }
-  if (type.kind == "ReferenceType" || type.kind == "OwnedResourceType" || type.kind == "OwnedReferenceType") {
+  if (type.kind == "ReferenceType" || type.kind == "InterfaceType" || type.kind == "OwnedResourceType" || type.kind == "OwnedReferenceType") {
     emitType(writer, type, path, "php")
     return
   }
@@ -365,7 +419,7 @@ function emitNativePhpType(writer, type, path) {
   }
   if (type.kind == "OptionalType") {
     writer.mapped("?", {mappingKind: "exact", node: type, path, role: "type"})
-    if (type.valueType.kind == "RecordType") emitNativePhpType(writer, type.valueType, `${path}/valueType`)
+    if (type.valueType.kind == "RecordType" || type.valueType.kind == "InterfaceType") emitNativePhpType(writer, type.valueType, `${path}/valueType`)
     else if (type.valueType.kind == "TypeReference") emitType(writer, type.valueType, `${path}/valueType`, "php")
     else writer.mapped("array", {mappingKind: "anchor", node: type, path})
     return

package/src/backends/python.js

@@ -81,14 +81,20 @@ function emitStatement(writer, statement, indent, path) {
     emitIf(writer, statement, indent, path, "if")
     return
   }
-  if (statement.kind == "ExpressionStatement") throw new TypeError("Python Task 005 expression statement reached emission.")
+  if (statement.kind == "ExpressionStatement") {
+    writer.synthetic(indent, "indentation", [statement], [path])
+    emitExpression(writer, statement.expression, `${path}/expression`, "python", identity)
+    writer.synthetic("\n", "line break", [statement], [path])
+    return
+  }
 
   writer.synthetic(indent, "indentation", [statement], [path])
   if (statement.kind == "ReturnStatement") {
-    if (!statement.expression) throw new TypeError("Python bare return reached emission.")
     writer.mapped("return", {mappingKind: "anchor", node: statement, path})
-    writer.synthetic(" ", "return spacing", [statement], [path])
-    emitExpression(writer, statement.expression, `${path}/expression`, "python", identity)
+    if (statement.expression) {
+      writer.synthetic(" ", "return spacing", [statement], [path])
+      emitExpression(writer, statement.expression, `${path}/expression`, "python", identity)
+    }
     writer.synthetic("\n", "line break", [statement], [path])
     return
   }

package/src/backends/scalars.js

@@ -37,7 +37,7 @@ export function emitScalarType(language, type) {
  * @returns {string} Exact target spelling.
  */
 export function emitSemanticType(language, type, javaBoxed = false) {
-  if (type.kind == "RecordType" || type.kind == "ReferenceType") {
+  if (type.kind == "RecordType" || type.kind == "ReferenceType" || type.kind == "InterfaceType") {
     throw new TypeError("Nominal type emission requires declaration context.")
   }
   if (type.kind == "OwnedResourceType" || type.kind == "OwnedReferenceType") {