semantifold 0.13.0 → 0.15.0

package/src/semantic/validate.js

@@ -8,13 +8,27 @@ import {parserRangeFor} from "./provenance.js"
 import {validateEffectGraph} from "./effects.js"
 import {validateResourceLifetimes} from "./lifetime.js"
 
-const task005Languages = new Set(["php", "ruby", "javascript", "typescript", "java", "c", "dart", "zig"])
+const task005Languages = new Set(["php", "ruby", "javascript", "typescript", "java", "c", "dart", "zig", "python"])
 
 /** @typedef {Map<string, import("./types.js").RecordDeclaration>} RecordRegistry */
 /** @typedef {Map<string, import("./types.js").ClassDeclaration>} ClassRegistry */
+/** @typedef {Map<string, import("./types.js").InterfaceDeclaration>} InterfaceRegistry */
 /** @typedef {Map<string, import("./types.js").ErrorDeclaration>} ErrorRegistry */
+/**
+ * @typedef InterfaceContractMember
+ * @property {string} interfaceId - Declaring interface identity.
+ * @property {string} methodId - Declaring interface method identity.
+ * @property {string} name - Contract method name.
+ * @property {import("./types.js").Parameter[]} parameters - Source-ordered contract parameters.
+ * @property {import("./types.js").SemanticFunctionReturnType} returnType - Contract return type.
+ * @property {import("./types.js").SourceLocation} location - Declaring method source location.
+ */
 /** @type {WeakMap<RecordRegistry, ClassRegistry>} */
 const referenceClassesByRecordRegistry = new WeakMap()
+/** @type {WeakMap<RecordRegistry, InterfaceRegistry>} */
+const interfacesByRecordRegistry = new WeakMap()
+/** @type {WeakMap<import("./types.js").InterfaceDeclaration, InterfaceContractMember[]>} */
+const flattenedInterfaceCache = new WeakMap()
 /** @type {WeakMap<RecordRegistry, Set<string>>} */
 const resourceIdsByRecordRegistry = new WeakMap()
 
@@ -52,7 +66,7 @@ const resourceIdsByRecordRegistry = new WeakMap()
  * Enforces the coherent release-candidate semantic subset after adaptation.
  * @param {import("./types.js").SemanticModule} module - Adapted semantic module.
  * @param {import("./types.js").SemanticLanguage} language - Source language.
- * @param {{classes?: Map<string, import("./types.js").ClassDeclaration>, functions?: Map<string, import("./types.js").FunctionDeclaration>, records?: Map<string, import("./types.js").RecordDeclaration>, errors?: Map<string, import("./types.js").ErrorDeclaration>, callEffects?: Map<string, Set<string>>}} [visible] - Program imports visible during validation.
+ * @param {{classes?: Map<string, import("./types.js").ClassDeclaration>, functions?: Map<string, import("./types.js").FunctionDeclaration>, interfaces?: Map<string, import("./types.js").InterfaceDeclaration>, records?: Map<string, import("./types.js").RecordDeclaration>, errors?: Map<string, import("./types.js").ErrorDeclaration>, callEffects?: Map<string, Set<string>>}} [visible] - Program imports visible during validation.
  * @returns {import("./types.js").SemanticModule} Validated module.
  */
 export function validateParsedModule(module, language, visible = {}) {
@@ -110,7 +124,7 @@ function normalizeParsedOwnedReferences(module, visibleClasses = new Map()) {
  * Validates scalar types and bindings for a caller-supplied semantic module before emission.
  * @param {import("./types.js").SemanticModule} module - Semantic module.
  * @param {import("./types.js").BackendLanguage} language - Backend language or binary target.
- * @param {{classes?: Map<string, import("./types.js").ClassDeclaration>, functions?: Map<string, import("./types.js").FunctionDeclaration>, records?: Map<string, import("./types.js").RecordDeclaration>, errors?: Map<string, import("./types.js").ErrorDeclaration>, callEffects?: Map<string, Set<string>>}} [visible] - Resolved program imports.
+ * @param {{classes?: Map<string, import("./types.js").ClassDeclaration>, functions?: Map<string, import("./types.js").FunctionDeclaration>, interfaces?: Map<string, import("./types.js").InterfaceDeclaration>, records?: Map<string, import("./types.js").RecordDeclaration>, errors?: Map<string, import("./types.js").ErrorDeclaration>, callEffects?: Map<string, Set<string>>}} [visible] - Resolved program imports.
  * @returns {void}
  */
 export function validateBackendTypes(module, language, visible = {}) {
@@ -194,12 +208,15 @@ function validateBlockShape(block, detail, fail) {
  * @param {string} language - Source or backend language identity.
  * @param {SemanticFail} fail - Diagnostic callback.
  * @param {boolean} normalizeOperations - Whether to replace transient frontend operation intent.
- * @param {{classes?: Map<string, import("./types.js").ClassDeclaration>, functions?: Map<string, import("./types.js").FunctionDeclaration>, records?: Map<string, import("./types.js").RecordDeclaration>, errors?: Map<string, import("./types.js").ErrorDeclaration>, callEffects?: Map<string, Set<string>>}} [visible] - Program imports visible during validation.
+ * @param {{classes?: Map<string, import("./types.js").ClassDeclaration>, functions?: Map<string, import("./types.js").FunctionDeclaration>, interfaces?: Map<string, import("./types.js").InterfaceDeclaration>, records?: Map<string, import("./types.js").RecordDeclaration>, errors?: Map<string, import("./types.js").ErrorDeclaration>, callEffects?: Map<string, Set<string>>}} [visible] - Program imports visible during validation.
  * @returns {void}
  */
 function validateModuleTypes(module, language, fail, normalizeOperations, visible = {}) {
-  const classes = registerClassDeclarations(module.classes ?? [], fail, normalizeOperations, visible.classes)
+  const interfaces = registerInterfaceDeclarations(module.interfaces ?? [], fail, normalizeOperations, visible.interfaces)
+  const classes = registerClassDeclarations(module.classes ?? [], fail, normalizeOperations, visible.classes, interfaces)
   const records = validateRecordDeclarations(module.records ?? [], fail, normalizeOperations, visible.records, classes)
+
+  interfacesByRecordRegistry.set(records, interfaces)
   const errors = validateErrorDeclarations(module.errors ?? [], fail, normalizeOperations, visible.errors)
   /** @type {Map<string, import("./types.js").FunctionDeclaration>} */
   const functions = new Map(visible.functions ?? [])
@@ -237,6 +254,7 @@ function validateModuleTypes(module, language, fail, normalizeOperations, visibl
 
   const reservedValueNames = new Set([
     ...functions.keys(),
+    ...[...interfaces.values()].map((declaration) => declaration.name),
     ...[...records.values()].map((declaration) => declaration.name),
     ...[...classes.values()].map((declaration) => declaration.name),
     ...[...errors.values()].map((declaration) => declaration.name),
@@ -245,7 +263,7 @@ function validateModuleTypes(module, language, fail, normalizeOperations, visibl
 
   const nominalNames = new Set()
 
-  for (const declaration of [...module.records ?? [], ...module.classes ?? [], ...module.errors ?? []]) {
+  for (const declaration of [...module.interfaces ?? [], ...module.records ?? [], ...module.classes ?? [], ...module.errors ?? []]) {
     if (nominalNames.has(declaration.name)) {
       fail("DUPLICATE_BINDING", `Duplicate nominal declaration '${declaration.name}'.`, roleLocation(declaration, "name"))
     }
@@ -260,6 +278,9 @@ function validateModuleTypes(module, language, fail, normalizeOperations, visibl
   const localFunctionNames = new Set(module.functions.map(({name}) => name))
   const callEffects = inferCallEffects(functions, visible.callEffects, localFunctionNames)
 
+  for (const declaration of module.classes ?? []) {
+    validateInterfaceContracts(declaration, interfaces, records, fail, normalizeOperations)
+  }
   for (const declaration of module.classes ?? []) {
     validateClassDeclaration(declaration, functions, records, errors, callEffects, reservedValueNames, fail,
       normalizeOperations, loopOwners)
@@ -351,9 +372,10 @@ export function moduleUncheckedErrorEffects(module, visible = {}) {
  * @param {SemanticFail} fail - Diagnostic callback.
  * @param {boolean} normalizeOperations - Whether parser-authored identities are assigned.
  * @param {Map<string, import("./types.js").ClassDeclaration>} [visibleClasses] - Imported classes by identity.
+ * @param {Map<string, import("./types.js").InterfaceDeclaration>} [interfaces] - Interface declarations by identity.
  * @returns {ClassRegistry} Classes by stable identity.
  */
-function registerClassDeclarations(declarations, fail, normalizeOperations, visibleClasses = new Map()) {
+function registerClassDeclarations(declarations, fail, normalizeOperations, visibleClasses = new Map(), interfaces = new Map()) {
   if (!Array.isArray(declarations)) {
     return fail("TYPE_MISMATCH", "Reference class declarations must be an ordered array.", /** @type {never} */ (undefined))
   }
@@ -441,11 +463,235 @@ function registerClassDeclarations(declarations, fail, normalizeOperations, visi
       }
       methodNames.add(method.name)
     }
+    if (declaration.implements !== undefined) {
+      if (!Array.isArray(declaration.implements)) {
+        fail("UNKNOWN_INTERFACE", `Class '${declaration.name}' has a malformed interface implementation set.`, declaration.location)
+      }
+      for (const implemented of declaration.implements) {
+        if (!implemented || implemented.kind != "InterfaceType" || typeof implemented.declarationId != "string" ||
+          !interfaces.has(implemented.declarationId)) {
+          fail("UNKNOWN_INTERFACE", `Class '${declaration.name}' implements unknown interface '${String(implemented?.declarationId)}'.`,
+            declaration.location)
+        }
+      }
+    }
   }
 
   return classes
 }
 
+/**
+ * Checks the exact total override contract for one implementing class.
+ * @param {import("./types.js").ClassDeclaration} declaration - Class declaration.
+ * @param {InterfaceRegistry} interfaces - Interfaces by identity.
+ * @param {RecordRegistry} records - Record declarations by identity.
+ * @param {SemanticFail} fail - Diagnostic callback.
+ * @param {boolean} normalizeOperations - Whether resolved facts are assigned.
+ * @returns {void}
+ */
+function validateInterfaceContracts(declaration, interfaces, records, fail, normalizeOperations) {
+  const implemented = declaration.implements ?? []
+
+  if (implemented.length == 0) return
+  /** @type {InterfaceContractMember[]} */
+  const required = []
+
+  for (const reference of implemented) {
+    for (const member of flattenedInterfaceMembers(reference.declarationId, interfaces, fail, new Set(), declaration.location)) {
+      if (required.some((candidate) => candidate.name == member.name)) continue
+      required.push(member)
+    }
+  }
+  /** @type {Map<string, {parameterTypes: import("./types.js").SemanticValueType[], returnType: import("./types.js").SemanticFunctionReturnType}>} */
+  const contractSignatures = new Map()
+
+  for (const member of required) {
+    contractSignatures.set(member.name, {
+      parameterTypes: member.parameters.map((parameter) =>
+        validateValueTypeReference(parameter.type, parameter.location, fail, undefined, records)),
+      returnType: validateReturnTypeReference(member.returnType, member.location, fail, records)
+    })
+  }
+  /** @type {Map<string, InterfaceContractMember>} */
+  const satisfied = new Map()
+
+  for (const method of declaration.methods) {
+    const member = required.find((candidate) => candidate.name == method.name)
+
+    if (!member) continue
+    if (satisfied.has(member.name)) {
+      fail("INTERFACE_MEMBER_DUPLICATE", `Class '${declaration.name}' supplies method '${method.name}' more than once for interface contract membership.`,
+        roleLocation(method, "name"))
+    }
+    const methodParameterTypes = method.parameters.map((parameter) =>
+      validateValueTypeReference(parameter.type, parameter.location, fail, undefined, records))
+    const methodReturnType = validateReturnTypeReference(method.returnType, method.location, fail, records)
+
+    const contract = contractSignatures.get(member.name)
+
+    if (!contract || methodParameterTypes.length != contract.parameterTypes.length ||
+      methodParameterTypes.some((type, index) => !sameType(type, contract.parameterTypes[index])) ||
+      !sameType(methodReturnType, contract.returnType)) {
+      fail("INTERFACE_MEMBER_SIGNATURE_MISMATCH",
+        `Class '${declaration.name}' method '${method.name}' must exactly match interface '${interfaces.get(member.interfaceId)?.name}' signature ${interfaceSignatureDescription(member)}.`,
+        roleLocation(method, "name"))
+    }
+    satisfied.set(member.name, member)
+    if (normalizeOperations) method.implements = {interfaceId: member.interfaceId, methodId: member.methodId}
+  }
+  for (const member of required) {
+    if (satisfied.has(member.name)) continue
+    fail("INTERFACE_MEMBER_MISSING", `Class '${declaration.name}' does not implement interface '${interfaces.get(member.interfaceId)?.name}' method '${member.name}'.`,
+      declaration.location)
+  }
+}
+
+/**
+ * Formats one flattened interface signature for diagnostics.
+ * @param {InterfaceContractMember} member - Flattened member.
+ * @returns {string} Stable signature spelling.
+ */
+function interfaceSignatureDescription(member) {
+  return `${member.name}(${member.parameters.map((parameter) => typeDescription(parameter.type)).join(", ")}): ${typeDescription(member.returnType)}`
+}
+
+/**
+ * Registers interface declarations, their closed extends DAG, and their flattened signature sets.
+ * @param {unknown} declarations - Candidate ordered interface declarations.
+ * @param {SemanticFail} fail - Diagnostic callback.
+ * @param {boolean} normalizeOperations - Whether parser-authored identities are assigned.
+ * @param {InterfaceRegistry} [visibleInterfaces] - Imported interface declarations by identity.
+ * @returns {InterfaceRegistry} Validated interfaces by identity.
+ */
+function registerInterfaceDeclarations(declarations, fail, normalizeOperations, visibleInterfaces = new Map()) {
+  if (!Array.isArray(declarations)) {
+    return fail("TYPE_MISMATCH", "Interface declarations must be an ordered array.", /** @type {never} */ (undefined))
+  }
+  /** @type {InterfaceRegistry} */
+  const interfaces = new Map(visibleInterfaces)
+  const names = new Set([...visibleInterfaces.values()].map(({name}) => name))
+
+  for (let interfaceIndex = 0; interfaceIndex < declarations.length; interfaceIndex += 1) {
+    const declaration = /** @type {import("./types.js").InterfaceDeclaration} */ (declarations[interfaceIndex])
+
+    if (!declaration || declaration.kind != "InterfaceDeclaration" || !Array.isArray(declaration.methods) ||
+      (declaration.extends !== undefined && !Array.isArray(declaration.extends))) {
+      return fail("DUPLICATE_INTERFACE", "Malformed or invalid interface declaration.", declaration?.location)
+    }
+    if (normalizeOperations) declaration.id = `interface:${interfaceIndex}`
+    if (typeof declaration.id != "string" || !/^(?:[a-z][a-z0-9._-]*#)?interface:[0-9]+$/u.test(declaration.id) ||
+      interfaces.has(declaration.id) || typeof declaration.name != "string" || declaration.name.length == 0 ||
+      names.has(declaration.name)) {
+      fail("DUPLICATE_INTERFACE", `Duplicate or invalid interface '${String(declaration.name)}'.`, roleLocation(declaration, "name"))
+    }
+    names.add(declaration.name)
+    interfaces.set(declaration.id, declaration)
+
+    const methodNames = new Set()
+
+    for (let methodIndex = 0; methodIndex < declaration.methods.length; methodIndex += 1) {
+      const method = declaration.methods[methodIndex]
+      const expectedId = `${declaration.id}:method:${methodIndex}`
+
+      if (!method || method.kind != "InterfaceMethodDeclaration" || !Array.isArray(method.parameters) ||
+        Reflect.get(method, "body") !== undefined) {
+        fail("INTERFACE_MEMBER_DUPLICATE", "Malformed or invalid interface method declaration.", method?.location ?? declaration.location)
+      }
+      if (normalizeOperations) method.id = expectedId
+      if (method.id != expectedId || typeof method.name != "string" || method.name.length == 0 || methodNames.has(method.name)) {
+        fail("INTERFACE_MEMBER_DUPLICATE", `Duplicate or invalid interface method '${String(method.name)}'.`, roleLocation(method, "name"))
+      }
+      methodNames.add(method.name)
+    }
+  }
+
+  for (const declaration of interfaces.values()) {
+    for (const parent of declaration.extends ?? []) {
+      if (!parent || parent.kind != "InterfaceType" || typeof parent.declarationId != "string" ||
+        !interfaces.has(parent.declarationId)) {
+        fail("UNKNOWN_INTERFACE", `Unknown interface parent '${String(parent?.declarationId)}'.`, declaration.location)
+      }
+    }
+    flattenedInterfaceMembers(/** @type {string} */ (declaration.id), interfaces, fail)
+  }
+
+  return interfaces
+}
+
+/**
+ * Flattens one interface's transitive signature set: parents first in declaration order, then its own methods.
+ * @param {string} interfaceId - Interface identity.
+ * @param {InterfaceRegistry} interfaces - Interfaces by identity.
+ * @param {SemanticFail} fail - Diagnostic callback.
+ * @param {Set<string>} [active] - Active extends path.
+ * @param {import("./types.js").SourceLocation} [fallbackLocation] - Location for a missing-parent diagnostic.
+ * @returns {InterfaceContractMember[]} Flattened members.
+ */
+function flattenedInterfaceMembers(interfaceId, interfaces, fail, active = new Set(), fallbackLocation = undefined) {
+  const declaration = interfaces.get(interfaceId)
+
+  if (!declaration) return fail("UNKNOWN_INTERFACE", `Unknown interface declaration '${interfaceId}'.`, /** @type {import("./types.js").SourceLocation} */ (fallbackLocation))
+  if (active.has(interfaceId)) {
+    return fail("INTERFACE_CYCLE", `Interface '${declaration.name}' extends itself through a cycle.`, declaration.location)
+  }
+  const cached = flattenedInterfaceCache.get(declaration)
+
+  if (cached) return cached
+  active.add(interfaceId)
+  /** @type {InterfaceContractMember[]} */
+  const members = []
+
+  for (const parent of declaration.extends ?? []) {
+    for (const member of flattenedInterfaceMembers(parent.declarationId, interfaces, fail, active)) {
+      const inherited = members.find((candidate) => candidate.name == member.name)
+
+      if (inherited) {
+        if (!sameInterfaceSignature(inherited, member)) {
+          fail("INTERFACE_MEMBER_DUPLICATE", `Interface '${declaration.name}' inherits conflicting signatures for '${member.name}'.`,
+            declaration.location)
+        }
+        continue
+      }
+      members.push(member)
+    }
+  }
+  for (const method of declaration.methods) {
+    const inherited = members.find((candidate) => candidate.name == method.name)
+
+    if (inherited) {
+      if (!sameInterfaceSignature(inherited, method)) {
+        fail("INTERFACE_MEMBER_DUPLICATE", `Interface '${declaration.name}' redeclares inherited method '${method.name}' with a different signature.`,
+          roleLocation(method, "name"))
+      }
+      continue
+    }
+    members.push({
+      interfaceId: /** @type {string} */ (declaration.id),
+      location: method.location,
+      methodId: /** @type {string} */ (method.id),
+      name: method.name,
+      parameters: method.parameters,
+      returnType: method.returnType
+    })
+  }
+  active.delete(interfaceId)
+  flattenedInterfaceCache.set(declaration, members)
+
+  return members
+}
+
+/**
+ * Compares two flattened interface signatures exactly.
+ * @param {{parameters: import("./types.js").Parameter[], returnType: import("./types.js").SemanticFunctionReturnType}} left - First signature.
+ * @param {{parameters: import("./types.js").Parameter[], returnType: import("./types.js").SemanticFunctionReturnType}} right - Second signature.
+ * @returns {boolean} Whether the signatures are identical.
+ */
+function sameInterfaceSignature(left, right) {
+  return left.parameters.length == right.parameters.length &&
+    left.parameters.every((parameter, index) => sameTypeIdentity(typeIdentity(parameter.type), typeIdentity(right.parameters[index].type))) &&
+    sameTypeIdentity(typeIdentity(left.returnType), typeIdentity(right.returnType))
+}
+
 /**
  * Validates exact construction, private state, and method bodies for one class.
  * @param {import("./types.js").ClassDeclaration} declaration - Class declaration.
@@ -774,11 +1020,11 @@ function validateBlock(block, scope, returnType, functions, records, errors, cal
       )
 
       scope.pending.delete(statement.name)
-      if (!sameType(initializerType, declaredType)) {
+      if (!assignableType(initializerType, declaredType, records)) {
         if (initializerType.kind == "OptionalType" && declaredType.kind != "OptionalType") {
           fail("FAILURE_ABSENCE_CONFLATION", "Optional absence cannot be coerced into a value or typed failure.", statement.initializer.location)
         }
-        fail("TYPE_MISMATCH", `Initializer type ${typeDescription(initializerType)}; expected ${typeDescription(declaredType)}.`, statement.initializer.location)
+        fail(nominalMismatchCode(declaredType), `Initializer type ${typeDescription(initializerType)}; expected ${typeDescription(declaredType)}.`, statement.initializer.location)
       }
       declareBinding(statement.name, {
         knownValue: knownValueForExpression(statement.initializer, scope),
@@ -804,8 +1050,8 @@ function validateBlock(block, scope, returnType, functions, records, errors, cal
       if (!binding.mutable) {
         fail("IMMUTABLE_ASSIGNMENT", `Cannot assign to immutable binding '${statement.target.name}'.`, statement.target.location)
       }
-      if (!sameType(expressionType, binding.type)) {
-        fail("TYPE_MISMATCH", `Assignment type ${typeDescription(expressionType)}; expected ${typeDescription(binding.type)}.`, statement.expression.location)
+      if (!assignableType(expressionType, binding.type, records)) {
+        fail(nominalMismatchCode(binding.type), `Assignment type ${typeDescription(expressionType)}; expected ${typeDescription(binding.type)}.`, statement.expression.location)
       }
       binding.knownValue = knownValueForExpression(statement.expression, scope)
       scope.presenceProofs.delete(binding)
@@ -902,8 +1148,8 @@ function validateBlock(block, scope, returnType, functions, records, errors, cal
           returnType
         )
 
-        if (!sameType(actualType, returnType)) {
-          fail("TYPE_MISMATCH", `Return type ${typeDescription(actualType)}; expected ${typeDescription(returnType)}.`, statement.expression.location)
+        if (!assignableType(actualType, returnType, records)) {
+          fail(nominalMismatchCode(returnType), `Return type ${typeDescription(actualType)}; expected ${typeDescription(returnType)}.`, statement.expression.location)
         }
       }
       if (statement.expression) addExpressionEffects(raises, statement.expression, callEffects)
@@ -1623,6 +1869,14 @@ function validateTypeReference(type, location, fail, seen = new Set(), records =
 
     return candidate
   }
+  if (candidate.kind == "InterfaceType") {
+    if (Object.keys(candidate).filter((key) => key != "sourceProvenance").sort().join(",") != "declarationId,kind" ||
+      typeof candidate.declarationId != "string" || !interfacesByRecordRegistry.get(records)?.has(candidate.declarationId)) {
+      fail("UNKNOWN_INTERFACE", `Unknown interface declaration '${String(candidate.declarationId)}'.`, typeLocation(candidate, location))
+    }
+
+    return candidate
+  }
   if (candidate.kind == "OwnedResourceType") {
     if (Object.keys(candidate).filter((key) => key != "sourceProvenance").sort().join(",") != "kind,resourceId" ||
       typeof candidate.resourceId != "string" || !resourceIdsByRecordRegistry.get(records)?.has(candidate.resourceId)) {
@@ -1855,8 +2109,8 @@ function inferExpressionType(expression, scope, functions, records, fail, normal
       expression.value, scope, functions, records, fail, normalizeOperations, "an optional present value", expectedType.valueType
     )
 
-    if (!sameType(valueType, expectedType.valueType)) {
-      fail("TYPE_MISMATCH", `Optional present type ${typeDescription(valueType)}; expected ${typeDescription(expectedType.valueType)}.`, expression.value.location)
+    if (!assignableType(valueType, expectedType.valueType, records)) {
+      fail(nominalMismatchCode(expectedType.valueType), `Optional present type ${typeDescription(valueType)}; expected ${typeDescription(expectedType.valueType)}.`, expression.value.location)
     }
 
     return expectedType
@@ -1911,8 +2165,8 @@ function inferExpressionType(expression, scope, functions, records, fail, normal
       inferredElementType ??= actual
       const requiredElementType = expectedType?.kind == "ListType" ? expectedType.elementType : inferredElementType
 
-      if (!sameType(actual, requiredElementType)) {
-        fail("TYPE_MISMATCH", `List element type ${typeDescription(actual)}; expected ${typeDescription(requiredElementType)}.`, element.location)
+      if (!assignableType(actual, requiredElementType, records)) {
+        fail(nominalMismatchCode(requiredElementType), `List element type ${typeDescription(actual)}; expected ${typeDescription(requiredElementType)}.`, element.location)
       }
     }
 
@@ -1947,8 +2201,8 @@ function inferExpressionType(expression, scope, functions, records, fail, normal
       inferredValueType ??= actual
       const requiredValueType = expectedType?.kind == "MapType" ? expectedType.valueType : inferredValueType
 
-      if (!sameType(actual, requiredValueType)) {
-        fail("TYPE_MISMATCH", `Map value type ${typeDescription(actual)}; expected ${typeDescription(requiredValueType)}.`, entry.value.location)
+      if (!assignableType(actual, requiredValueType, records)) {
+        fail(nominalMismatchCode(requiredValueType), `Map value type ${typeDescription(actual)}; expected ${typeDescription(requiredValueType)}.`, entry.value.location)
       }
     }
 
@@ -1985,8 +2239,8 @@ function inferExpressionType(expression, scope, functions, records, fail, normal
       inferredValueType ??= actual
       const requiredValueType = expectedType?.kind == "OrderedMapType" ? expectedType.valueType : inferredValueType
 
-      if (!sameType(actual, requiredValueType)) {
-        fail("TYPE_MISMATCH", `Ordered-map value type ${typeDescription(actual)}; expected ${typeDescription(requiredValueType)}.`,
+      if (!assignableType(actual, requiredValueType, records)) {
+        fail(nominalMismatchCode(requiredValueType), `Ordered-map value type ${typeDescription(actual)}; expected ${typeDescription(requiredValueType)}.`,
           entry.value.location)
       }
     }
@@ -2139,6 +2393,49 @@ function inferExpressionType(expression, scope, functions, records, fail, normal
     const receiverType = inferValueExpressionType(expression.receiver, scope, functions, records, fail,
       normalizeOperations, "a method receiver")
 
+    if (receiverType.kind == "InterfaceType") {
+      const interfaces = interfacesByRecordRegistry.get(records) ?? new Map()
+      const receiverInterface = interfaces.get(receiverType.declarationId)
+
+      if (!receiverInterface) return fail("UNKNOWN_INTERFACE", `Unknown interface '${receiverType.declarationId}'.`, expression.receiver.location)
+      const members = flattenedInterfaceMembers(receiverType.declarationId, interfaces, fail, new Set(), expression.receiver.location)
+      const member = members.find((candidate) => candidate.methodId == expression.method) ??
+        (normalizeOperations ? members.find((candidate) => candidate.name == expression.method) : undefined)
+
+      if (!member) return fail("UNKNOWN_METHOD", `Interface '${receiverInterface.name}' has no method '${expression.method}'.`,
+        roleLocation(expression, "member"))
+      if (normalizeOperations) expression.method = member.methodId
+      if (!isDenseArray(expression.arguments)) return fail("TYPE_MISMATCH", "Method arguments must be a dense ordered array.", expression.location)
+      if (expression.arguments.length != member.parameters.length) {
+        return fail("METHOD_ARITY_MISMATCH",
+          `Method '${member.name}' has ${expression.arguments.length} arguments; expected ${member.parameters.length}.`, expression.location)
+      }
+      const parameterTypes = member.parameters.map((parameter) =>
+        validateValueTypeReference(parameter.type, parameter.location, fail, undefined, records))
+
+      for (let index = 0; index < expression.arguments.length; index += 1) {
+        expression.arguments[index] = normalizeOwnedMove(expression.arguments[index], parameterTypes[index], normalizeOperations, fail)
+        const actual = inferValueExpressionType(expression.arguments[index], scope, functions, records, fail,
+          normalizeOperations, "a method argument", parameterTypes[index])
+
+        if (!assignableType(actual, parameterTypes[index], records)) {
+          fail(nominalMismatchCode(parameterTypes[index]), `Method argument type ${typeDescription(actual)}; expected ${typeDescription(parameterTypes[index])}.`,
+            expression.arguments[index].location)
+        }
+      }
+      const returnType = validateReturnTypeReference(member.returnType, member.location, fail, records)
+      const resolution = {
+        declarationId: member.methodId,
+        kind: /** @type {const} */ ("ResolvedMethodSignature"),
+        parameterTypes: parameterTypes.map((type) => /** @type {import("./types.js").SemanticTypeIdentity} */ (typeIdentity(type))),
+        returnType: typeIdentity(returnType)
+      }
+
+      if (normalizeOperations) expression.resolution = resolution
+      else validateReferenceResolution(expression.resolution, resolution, expression.location, fail, "method")
+
+      return isVoidType(returnType) ? "void" : returnType
+    }
     if (receiverType.kind != "ReferenceType" && receiverType.kind != "OwnedReferenceType") {
       return fail("INVALID_METHOD_RECEIVER", "Method call receiver must have a reference class type.", expression.receiver.location)
     }
@@ -2164,8 +2461,8 @@ function inferExpressionType(expression, scope, functions, records, fail, normal
       const actual = inferValueExpressionType(expression.arguments[index], scope, functions, records, fail,
         normalizeOperations, "a method argument", parameterTypes[index])
 
-      if (!sameType(actual, parameterTypes[index])) {
-        fail("TYPE_MISMATCH", `Method argument type ${typeDescription(actual)}; expected ${typeDescription(parameterTypes[index])}.`,
+      if (!assignableType(actual, parameterTypes[index], records)) {
+        fail(nominalMismatchCode(parameterTypes[index]), `Method argument type ${typeDescription(actual)}; expected ${typeDescription(parameterTypes[index])}.`,
           expression.arguments[index].location)
       }
     }
@@ -2295,8 +2592,8 @@ function inferExpressionType(expression, scope, functions, records, fail, normal
 
       if ((functionDeclaration.typeParameters?.length ?? 0) > 0) {
         inferTypeArguments(expectedType, actualType, substitutions, argument.location, fail)
-      } else if (!sameType(actualType, expectedType)) {
-        fail("TYPE_MISMATCH", `Call argument type ${typeDescription(actualType)}; expected ${typeDescription(expectedType)}.`, argument.location)
+      } else if (!assignableType(actualType, expectedType, records)) {
+        fail(nominalMismatchCode(expectedType), `Call argument type ${typeDescription(actualType)}; expected ${typeDescription(expectedType)}.`, argument.location)
       }
     }
     for (const parameter of functionDeclaration.typeParameters ?? []) {
@@ -2319,8 +2616,8 @@ function inferExpressionType(expression, scope, functions, records, fail, normal
       const actual = inferValueExpressionType(expression.arguments[index], scope, functions, records, fail,
         normalizeOperations, "a call argument", expected)
 
-      if (!sameType(actual, expected)) {
-        fail("TYPE_MISMATCH", `Call argument type ${typeDescription(actual)}; expected ${typeDescription(expected)}.`, expression.arguments[index].location)
+      if (!assignableType(actual, expected, records)) {
+        fail(nominalMismatchCode(expected), `Call argument type ${typeDescription(actual)}; expected ${typeDescription(expected)}.`, expression.arguments[index].location)
       }
     }
     const resolution = signatureFor(functionDeclaration, records, fail, substitutions)
@@ -2835,6 +3132,7 @@ function typeIdentity(type) {
       /** @type {import("./types.js").SemanticTypeIdentity} */ (typeIdentity(argument)))} : {})
   }
   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: /** @type {import("./types.js").SemanticTypeIdentity} */ (typeIdentity(type.elementType)), kind: "ListType"}
@@ -2891,6 +3189,9 @@ function validTypeIdentity(type, allowVoid, seen = new Set()) {
   } else if (candidate.kind == "ReferenceType" && Object.keys(candidate).sort().join(",") == "declarationId,kind") {
     valid = typeof candidate.declarationId == "string" &&
       /^(?:[a-z][a-z0-9._-]*#)?class:[0-9]+$/u.test(candidate.declarationId)
+  } else if (candidate.kind == "InterfaceType" && Object.keys(candidate).sort().join(",") == "declarationId,kind") {
+    valid = typeof candidate.declarationId == "string" &&
+      /^(?:[a-z][a-z0-9._-]*#)?interface:[0-9]+$/u.test(candidate.declarationId)
   } else if (candidate.kind == "OwnedResourceType" && Object.keys(candidate).sort().join(",") == "kind,resourceId") {
     valid = typeof candidate.resourceId == "string" && /^(?:module:[0-9]+\/)?capability:[0-9]+\/resource:[0-9]+$/u
       .test(candidate.resourceId)
@@ -2941,6 +3242,7 @@ function sameTypeIdentity(left, right) {
       leftArguments.every((argument, index) => sameTypeIdentity(argument, rightArguments[index]))
   }
   if (leftType.kind == "ReferenceType") return leftType.declarationId == rightType.declarationId
+  if (leftType.kind == "InterfaceType") return leftType.declarationId == rightType.declarationId
   if (leftType.kind == "OwnedResourceType") return leftType.resourceId == rightType.resourceId
   if (leftType.kind == "OwnedReferenceType") return leftType.declarationId == rightType.declarationId
   if (leftType.kind == "MapType" || leftType.kind == "OrderedMapType") {
@@ -2960,6 +3262,54 @@ function sameType(left, right) {
   return sameTypeIdentity(typeIdentity(left), typeIdentity(right))
 }
 
+/**
+ * Reports whether one validated type may flow to a declared position.
+ * @param {import("./types.js").SemanticFunctionReturnType} actual - Inferred source type.
+ * @param {import("./types.js").SemanticFunctionReturnType} expected - Declared position type.
+ * @param {RecordRegistry} records - Record and reference-class registries.
+ * @returns {boolean} Whether the value flow is admitted.
+ */
+function assignableType(actual, expected, records) {
+  if (sameType(actual, expected)) return true
+  if (expected.kind != "InterfaceType") return false
+  const interfaces = interfacesByRecordRegistry.get(records) ?? new Map()
+
+  if (actual.kind == "InterfaceType") return interfaceExtendsTransitively(actual.declarationId, expected.declarationId, interfaces)
+  if (actual.kind == "ReferenceType") {
+    const declaration = referenceClassesFor(records).get(actual.declarationId)
+
+    return Boolean(declaration?.implements?.some((implemented) =>
+      implemented.declarationId == expected.declarationId ||
+      interfaceExtendsTransitively(implemented.declarationId, expected.declarationId, interfaces)))
+  }
+
+  return false
+}
+
+/**
+ * Reports whether one interface transitively extends another through the closed DAG.
+ * @param {string} interfaceId - Descendant interface identity.
+ * @param {string} ancestorId - Ancestor interface identity.
+ * @param {InterfaceRegistry} interfaces - Interfaces by identity.
+ * @returns {boolean} Whether the relation holds.
+ */
+function interfaceExtendsTransitively(interfaceId, ancestorId, interfaces) {
+  const declaration = interfaces.get(interfaceId)
+
+  if (!declaration) return false
+  return (declaration.extends ?? []).some((parent) => parent.declarationId == ancestorId ||
+    interfaceExtendsTransitively(parent.declarationId, ancestorId, interfaces))
+}
+
+/**
+ * Chooses the stable diagnostic code for one failed nominal value flow.
+ * @param {import("./types.js").SemanticFunctionReturnType} expected - Declared position type.
+ * @returns {string} Stable diagnostic code.
+ */
+function nominalMismatchCode(expected) {
+  return expected.kind == "InterfaceType" ? "INTERFACE_TYPE_MISMATCH" : "TYPE_MISMATCH"
+}
+
 /**
  * Formats one validated semantic type for diagnostics.
  * @param {import("./types.js").SemanticFunctionReturnType | import("./types.js").ErrorType} type - Semantic type.
@@ -2971,6 +3321,7 @@ function typeDescription(type) {
   if (type.kind == "RecordType") return `record<${type.declarationId}${type.arguments?.length
     ? `, ${type.arguments.map(typeDescription).join(", ")}` : ""}>`
   if (type.kind == "ReferenceType") return `reference<${type.declarationId}>`
+  if (type.kind == "InterfaceType") return `interface<${type.declarationId}>`
   if (type.kind == "OwnedResourceType") return `owned-resource<${type.resourceId}>`
   if (type.kind == "OwnedReferenceType") return `owned-reference<${type.declarationId}>`
   if (type.kind == "ErrorType") return `error<${type.declarationId}>`