semantifold 0.13.0 → 0.14.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/language-support.md

@@ -170,7 +170,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "semantifold",
-  "version": "0.13.0",
+  "version": "0.14.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/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") {

package/src/backends/shared.js

@@ -38,6 +38,7 @@ const task014Languages = new Set(["php", "ruby", "javascript", "typescript", "ja
 const task032Languages = new Set(["php", "ruby", "javascript", "typescript", "java"])
 const task033Languages = new Set(["php", "ruby", "javascript", "typescript", "java"])
 const task048ConditionalLanguages = new Set(["php", "ruby", "javascript", "typescript", "java"])
+const boundedSubtypingLanguages = new Set(["php"])
 const javaReferenceMethodHooks = new Set(["clone", "equals", "finalize", "getClass", "hashCode", "notify", "notifyAll", "toString", "wait"])
 const javascriptReferenceMethodHooks = new Set([
   "__defineGetter__", "__defineSetter__", "__lookupGetter__", "__lookupSetter__", "__proto__", "constructor",
@@ -56,7 +57,7 @@ const javaObjectInstanceMethodSignatures = new Set([
  * Checks the intentionally narrow backend contract.
  * @param {import("../semantic/types.js").SemanticModule} module - Semantic module.
  * @param {import("../semantic/types.js").BackendLanguage} language - Backend language or binary target.
- * @param {{externalDeclarationIds?: Set<string>, program?: boolean, visibleFunctions?: Map<string, import("../semantic/types.js").FunctionDeclaration>, visibleRecords?: Map<string, import("../semantic/types.js").RecordDeclaration>, visibleClasses?: Map<string, import("../semantic/types.js").ClassDeclaration>, visibleErrors?: Map<string, import("../semantic/types.js").ErrorDeclaration>, visibleCallEffects?: Map<string, Set<string>>}} [options] - Resolved program validation context.
+ * @param {{externalDeclarationIds?: Set<string>, program?: boolean, visibleFunctions?: Map<string, import("../semantic/types.js").FunctionDeclaration>, visibleRecords?: Map<string, import("../semantic/types.js").RecordDeclaration>, visibleClasses?: Map<string, import("../semantic/types.js").ClassDeclaration>, visibleInterfaces?: Map<string, import("../semantic/types.js").InterfaceDeclaration>, visibleErrors?: Map<string, import("../semantic/types.js").ErrorDeclaration>, visibleCallEffects?: Map<string, Set<string>>}} [options] - Resolved program validation context.
  * @returns {void}
  */
 export function validateBackendModule(module, language, options = {}) {
@@ -89,11 +90,19 @@ export function validateBackendModule(module, language, options = {}) {
   if (classes.length > 0 && !task033Languages.has(language)) {
     unsupportedCapability(language, "Task 033 reference classes, methods, and constructors", classes[0]?.location ?? module.location)
   }
+  const declaredInterfaces = module.interfaces
+  const interfaces = declaredInterfaces === undefined ? [] : declaredInterfaces
+
+  if (!Array.isArray(interfaces)) unsupportedCapability(language, "missing or invalid interface declarations", module.location)
+  if (interfaces.length > 0 && !boundedSubtypingLanguages.has(language)) {
+    unsupportedCapability(language, "Task 048 bounded subtyping interfaces", interfaces[0]?.location ?? module.location)
+  }
   if (!task011Languages.has(language)) rejectTypedErrors(module, language)
   if (!task032Languages.has(language)) rejectConditionControlledLoops(module, language)
   if (!task014Languages.has(language)) rejectOrderedMapCapability(module, language)
   validateRecordTargets(records, module.functions, language, module.location)
-  validateReferenceClassTargets(classes, records, errors, module.functions, language, module.location)
+  validateInterfaceTargets(interfaces, records, errors, module.functions, language, module.location)
+  validateReferenceClassTargets(classes, records, errors, module.functions, interfaces, language, module.location)
   if (!task008Languages.has(language)) rejectIterationStatements(module, language)
   if (!task007Languages.has(language)) rejectOptionalTypes(module, language)
   if (!task006Languages.has(language)) rejectCollectionTypes(module, language)
@@ -163,6 +172,7 @@ export function validateBackendModule(module, language, options = {}) {
     classes: options.visibleClasses,
     errors: options.visibleErrors,
     functions: options.visibleFunctions,
+    interfaces: options.visibleInterfaces,
     records: options.visibleRecords
   })
 }
@@ -382,7 +392,99 @@ function validateRecordTargets(records, functions, language, moduleLocation) {
  * @param {import("../semantic/types.js").SourceLocation | undefined} moduleLocation - Fallback location.
  * @returns {void}
  */
-function validateReferenceClassTargets(classes, records, errors, functions, language, moduleLocation) {
+/**
+ * Validates the exact target-visible shape of every interface and its override contracts before output allocation.
+ * @param {import("../semantic/types.js").InterfaceDeclaration[]} interfaces - Candidate interfaces.
+ * @param {import("../semantic/types.js").RecordDeclaration[]} records - Existing records.
+ * @param {import("../semantic/types.js").ErrorDeclaration[]} errors - Existing typed errors.
+ * @param {import("../semantic/types.js").FunctionDeclaration[]} functions - Existing functions.
+ * @param {import("../semantic/types.js").BackendLanguage} language - Target language.
+ * @param {import("../semantic/types.js").SourceLocation | undefined} moduleLocation - Fallback location.
+ * @returns {void}
+ */
+function validateInterfaceTargets(interfaces, records, errors, functions, language, moduleLocation) {
+  if (interfaces.length == 0) return
+  const byId = new Map(interfaces.map((declaration) => [declaration.id, declaration]))
+  const targetNames = new Set()
+
+  for (const declaration of [...records, ...errors, ...functions]) {
+    if (!declaration || typeof declaration != "object" || Array.isArray(declaration)) continue
+    const name = Reflect.get(declaration, "name")
+
+    if (typeof name == "string") targetNames.add(language == "php" ? name.toLowerCase() : name)
+  }
+
+  for (let interfaceIndex = 0; interfaceIndex < interfaces.length; interfaceIndex += 1) {
+    const declaration = interfaces[interfaceIndex]
+    const location = diagnosticLocation(declaration?.location, moduleLocation)
+    const keys = declaration && typeof declaration == "object" && !Array.isArray(declaration)
+      ? Object.keys(declaration).filter((key) => key != "sourceProvenance").sort().join(",") : ""
+
+    if (!declaration || declaration.kind != "InterfaceDeclaration" ||
+      !["extends,id,kind,location,methods,name", "id,kind,location,methods,name"].includes(keys) ||
+      !isDenseArray(declaration.methods) ||
+      !new RegExp(`^(?:[a-z][a-z0-9._-]*#)?interface:${interfaceIndex}$`, "u").test(String(declaration.id))) {
+      unsupportedCapability(language, "missing or invalid interface declaration", location)
+    }
+    const declarationLocation = requireSemanticLocation(declaration.location, language, "interface declaration location", location)
+
+    validateTargetTypeIdentifier(language, declaration.name, declarationLocation)
+    const targetName = language == "php" ? declaration.name.toLowerCase() : declaration.name
+
+    if (targetNames.has(targetName)) unsupportedCapability(language, `interface collision '${declaration.name}'`, declarationLocation)
+    targetNames.add(targetName)
+    const methodNames = new Set()
+
+    for (let methodIndex = 0; methodIndex < declaration.methods.length; methodIndex += 1) {
+      const method = declaration.methods[methodIndex]
+      const methodLocation = diagnosticLocation(method?.location, declarationLocation)
+      const methodKeys = method && typeof method == "object" && !Array.isArray(method)
+        ? Object.keys(method).filter((key) => key != "sourceProvenance").sort().join(",") : ""
+
+      if (!method || method.kind != "InterfaceMethodDeclaration" || methodKeys != "id,kind,location,name,parameters,returnType" ||
+        method.id != `${declaration.id}:method:${methodIndex}` || !isDenseArray(method.parameters)) {
+        unsupportedCapability(language, "missing or invalid interface method declaration", methodLocation)
+      }
+      const exactMethodLocation = requireSemanticLocation(method.location, language, "interface method declaration location", declarationLocation)
+
+      validateTargetIdentifier(language, method.name, "interface method", exactMethodLocation)
+      const normalized = language == "php" ? method.name.toLowerCase() : method.name
+
+      if (methodNames.has(normalized)) unsupportedCapability(language, `duplicate interface method '${method.name}'`, exactMethodLocation)
+      methodNames.add(normalized)
+      validateReferenceClassParameters(method.parameters, "interface method", language, exactMethodLocation)
+    }
+    const parents = declaration.extends ?? []
+
+    for (const parent of parents) {
+      const parentKeys = parent && typeof parent == "object" && !Array.isArray(parent)
+        ? Object.keys(parent).filter((key) => key != "sourceProvenance").sort().join(",") : ""
+
+      if (!parent || parent.kind != "InterfaceType" || parentKeys != "declarationId,kind" ||
+        !byId.has(parent.declarationId)) {
+        unsupportedCapability(language, "missing or invalid interface parent reference", declarationLocation)
+      }
+    }
+  }
+  for (const declaration of interfaces) {
+    for (const parent of declaration.extends ?? []) {
+      if (parent.declarationId == declaration.id) unsupportedCapability(language, "interface extends itself", declaration.location)
+    }
+  }
+}
+
+/**
+ * Validates the exact target-visible shape of every reference class before output allocation.
+ * @param {import("../semantic/types.js").ClassDeclaration[]} classes - Candidate classes.
+ * @param {import("../semantic/types.js").RecordDeclaration[]} records - Existing records.
+ * @param {import("../semantic/types.js").ErrorDeclaration[]} errors - Existing typed errors.
+ * @param {import("../semantic/types.js").FunctionDeclaration[]} functions - Existing functions.
+ * @param {import("../semantic/types.js").InterfaceDeclaration[]} interfaces - Existing interfaces.
+ * @param {import("../semantic/types.js").BackendLanguage} language - Target language.
+ * @param {import("../semantic/types.js").SourceLocation | undefined} moduleLocation - Fallback location.
+ * @returns {void}
+ */
+function validateReferenceClassTargets(classes, records, errors, functions, interfaces, language, moduleLocation) {
   const targetNames = new Set()
 
   for (const declaration of [...records, ...errors, ...functions]) {
@@ -400,7 +502,8 @@ function validateReferenceClassTargets(classes, records, errors, functions, lang
       ? Object.keys(declaration).filter((key) => key != "sourceProvenance").sort().join(",") : ""
 
     if (!declaration || declaration.kind != "ClassDeclaration" ||
-      !["constructor,fields,id,kind,location,methods,name", "constructor,fields,id,kind,location,methods,name,ownership"].includes(keys) ||
+      !["constructor,fields,id,implements,kind,location,methods,name", "constructor,fields,id,implements,kind,location,methods,name,ownership",
+        "constructor,fields,id,kind,location,methods,name", "constructor,fields,id,kind,location,methods,name,ownership"].includes(keys) ||
       !isDenseArray(declaration.fields) || declaration.fields.length == 0 || !isDenseArray(declaration.methods) ||
       !new RegExp(`^(?:[a-z][a-z0-9._-]*#)?class:${classIndex}$`, "u").test(String(declaration.id))) {
       unsupportedCapability(language, "missing or invalid reference class declaration", location)
@@ -459,7 +562,9 @@ function validateReferenceClassTargets(classes, records, errors, functions, lang
         ? Object.keys(method).filter((key) => key != "sourceProvenance").sort().join(",") : ""
 
       if (!method || method.kind != "MethodDeclaration" ||
-        !["body,id,kind,location,name,parameters,returnType",
+        !["body,id,implements,kind,location,name,parameters,returnType",
+          "body,effects,failureIds,id,implements,kind,location,name,parameters,returnType",
+          "body,id,kind,location,name,parameters,returnType",
           "body,effects,failureIds,id,kind,location,name,parameters,returnType"].includes(methodKeys) ||
         method.id != `${declaration.id}:method:${methodIndex}` || !isDenseArray(method.parameters)) {
         unsupportedCapability(language, "missing or invalid method declaration", methodLocation)
@@ -492,13 +597,104 @@ function validateReferenceClassTargets(classes, records, errors, functions, lang
       methodNames.add(normalized)
       validateReferenceClassParameters(method.parameters, "method", language, exactMethodLocation)
     }
+    const implemented = declaration.implements ?? []
+
+    for (const reference of implemented) {
+      const referenceKeys = reference && typeof reference == "object" && !Array.isArray(reference)
+        ? Object.keys(reference).filter((key) => key != "sourceProvenance").sort().join(",") : ""
+
+      if (!reference || reference.kind != "InterfaceType" || referenceKeys != "declarationId,kind" ||
+        !interfaces.some((candidate) => candidate.id == reference.declarationId)) {
+        unsupportedCapability(language, "missing or invalid implemented interface reference", location)
+      }
+    }
+    const satisfied = new Set()
+
+    for (const reference of implemented) {
+      for (const member of flattenedTargetInterfaceMembers(reference.declarationId, interfaces, language, location)) {
+        const method = declaration.methods.find((candidate) => candidate.name == member.name)
+
+        if (!method) unsupportedCapability(language, `interface method '${member.name}' is not implemented`, location)
+        if (satisfied.has(member.name)) unsupportedCapability(language, `duplicate interface implementation '${member.name}'`, location)
+        if (method.parameters.length != member.parameters.length ||
+          method.parameters.some((parameter, index) => !sameTargetType(parameter.type, member.parameters[index].type))) {
+          unsupportedCapability(language, `interface method signature mismatch '${member.name}'`, location)
+        }
+        if (!sameTargetType(method.returnType, member.returnType)) {
+          unsupportedCapability(language, `interface method return mismatch '${member.name}'`, location)
+        }
+        satisfied.add(member.name)
+      }
+    }
+  }
+}
+
+/**
+ * Flattens one target-validated interface signature set in declaration order.
+ * @param {string} interfaceId - Interface identity.
+ * @param {import("../semantic/types.js").InterfaceDeclaration[]} interfaces - Interfaces in declaration order.
+ * @param {import("../semantic/types.js").BackendLanguage} language - Target language.
+ * @param {import("../semantic/types.js").SourceLocation | undefined} location - Diagnostic location.
+ * @param {Set<string>} [active] - Active extends path.
+ * @returns {import("../semantic/types.js").InterfaceMethodDeclaration[]} Flattened members.
+ */
+function flattenedTargetInterfaceMembers(interfaceId, interfaces, language, location, active = new Set()) {
+  const declaration = interfaces.find((candidate) => candidate.id == interfaceId)
+
+  if (!declaration) unsupportedCapability(language, "missing or invalid implemented interface reference", location)
+  if (active.has(interfaceId)) unsupportedCapability(language, "interface extends itself", declaration.location)
+  active.add(interfaceId)
+  /** @type {import("../semantic/types.js").InterfaceMethodDeclaration[]} */
+  const members = []
+
+  for (const parent of declaration.extends ?? []) {
+    for (const member of flattenedTargetInterfaceMembers(parent.declarationId, interfaces, language, location, active)) {
+      if (!members.some((candidate) => candidate.name == member.name)) members.push(member)
+    }
+  }
+  for (const method of declaration.methods) {
+    if (!members.some((candidate) => candidate.name == method.name)) members.push(method)
   }
+  active.delete(interfaceId)
+
+  return members
+}
+
+/**
+ * Compares two backend-validated semantic types structurally.
+ * @param {import("../semantic/types.js").SemanticFunctionReturnType} left - First type.
+ * @param {import("../semantic/types.js").SemanticFunctionReturnType} right - Second type.
+ * @returns {boolean} Whether the types are identical.
+ */
+function sameTargetType(left, right) {
+  return JSON.stringify(targetTypeIdentity(left)) == JSON.stringify(targetTypeIdentity(right))
+}
+
+/**
+ * Reduces one semantic type to its comparable target identity.
+ * @param {import("../semantic/types.js").SemanticFunctionReturnType} type - Semantic type.
+ * @returns {unknown} Comparable identity.
+ */
+function targetTypeIdentity(type) {
+  if (typeof type == "string") return type
+  if (type.kind == "TypeReference") return type.name
+  if (type.kind == "TypeVariableReference") return {kind: "TypeVariableReference", parameterId: type.parameterId}
+  if (type.kind == "RecordType") return {declarationId: type.declarationId, kind: "RecordType"}
+  if (type.kind == "ReferenceType") return {declarationId: type.declarationId, kind: "ReferenceType"}
+  if (type.kind == "InterfaceType") return {declarationId: type.declarationId, kind: "InterfaceType"}
+  if (type.kind == "OwnedResourceType") return {kind: "OwnedResourceType", resourceId: type.resourceId}
+  if (type.kind == "OwnedReferenceType") return {declarationId: type.declarationId, kind: "OwnedReferenceType"}
+  if (type.kind == "ListType") return {elementType: targetTypeIdentity(type.elementType), kind: "ListType"}
+  if (type.kind == "OptionalType") return {kind: "OptionalType", valueType: targetTypeIdentity(type.valueType)}
+  if (type.kind == "OrderedMapType") return {keyType: targetTypeIdentity(type.keyType), kind: "OrderedMapType", valueType: targetTypeIdentity(type.valueType)}
+
+  return {keyType: targetTypeIdentity(type.keyType), kind: "MapType", valueType: targetTypeIdentity(type.valueType)}
 }
 
 /**
  * Validates one reference callable's exact parameter shape and target names.
  * @param {import("../semantic/types.js").Parameter[]} parameters - Candidate parameters.
- * @param {"constructor" | "method"} owner - Callable kind.
+ * @param {"constructor" | "interface method" | "method"} owner - Callable kind.
  * @param {import("../semantic/types.js").BackendLanguage} language - Target language.
  * @param {import("../semantic/types.js").SourceLocation | undefined} ownerLocation - Fallback location.
  * @returns {void}
@@ -2095,6 +2291,14 @@ export function emitType(writer, type, path, language, javaBoxed = false) {
     })
     return
   }
+  if (type.kind == "InterfaceType") {
+    const declaration = writer.interfaceForId(type.declarationId)
+
+    writer.mapped(writer.interfaceNameForId(type.declarationId), {
+      mappingKind: "exact", name: declaration.name, node: type, path, role: "type"
+    })
+    return
+  }
   if (type.kind == "OwnedResourceType") {
     const resource = writer.resourceForId(type.resourceId)
     writer.mapped(writer.capabilityNominalName(resource.name), {mappingKind: "exact", name: resource.name, node: type, path, role: "type"})