semantifold 0.13.0 → 0.15.0

package/src/frontends/python.js

@@ -5,8 +5,8 @@ import PythonLanguage from "tree-sitter-python"
 import {missingType, parseFailure, SemantifoldDiagnostic, unsupportedSyntax} from "../diagnostic.js"
 import {locationFromOffsets, moduleLocation, utf8ByteOffsetToUtf16Offset} from "../semantic/location.js"
 import {withAdaptedOperation} from "../semantic/operators.js"
-import {withParserRanges} from "../semantic/provenance.js"
-import {hasOnlyUnicodeScalars} from "../semantic/scalars.js"
+import {setParserRanges, withParserRanges} from "../semantic/provenance.js"
+import {hasOnlyUnicodeScalars, voidType} from "../semantic/scalars.js"
 import {requireSourceScalarType} from "./scalars.js"
 
 const parser = new Parser()
@@ -171,6 +171,31 @@ function convertType(node, subject, ownerLocation, filename, source) {
   return requireSourceScalarType("python", children[0].text, subject, ownerLocation, typeLocation)
 }
 
+/**
+ * Converts one exact scalar or Task 005 `None` function-return annotation.
+ * @param {import("tree-sitter").SyntaxNode | null} node - Return type node, if present.
+ * @param {string} subject - Typed function return.
+ * @param {import("../semantic/types.js").SourceLocation} ownerLocation - Owning function.
+ * @param {string} filename - Source filename.
+ * @param {string} source - Complete source.
+ * @returns {import("../semantic/types.js").SemanticFunctionReturnType} Semantic return type.
+ */
+function convertReturnType(node, subject, ownerLocation, filename, source) {
+  if (!node) return missingType("python", subject, ownerLocation)
+  const typeLocation = nodeLocation(node, filename, source)
+  const children = node.namedChildren.filter((child) => child.type != "comment")
+
+  if (node.type == "type" && children.length == 1 && children[0].type == "none" && node.text == "None") {
+    const type = voidType()
+
+    setParserRanges(type, {type: typeLocation})
+
+    return type
+  }
+
+  return convertType(node, subject, ownerLocation, filename, source)
+}
+
 /**
  * Finds exactly one anonymous operator token directly owned by a parser node.
  * @param {import("tree-sitter").SyntaxNode} node - Operation node.
@@ -434,7 +459,8 @@ function convertStatement(node, context, visible, filename, source) {
   if (node.type == "return_statement") {
     const expressions = node.namedChildren.filter((child) => child.type != "comment")
 
-    if (expressions.length != 1) return unsupportedSyntax("python", "return without one expression", location)
+    if (expressions.length > 1) return unsupportedSyntax("python", "return with more than one expression", location)
+    if (expressions.length == 0) return {kind: "ReturnStatement", location}
 
     return {expression: convertExpression(expressions[0], filename, source), kind: "ReturnStatement", location}
   }
@@ -444,8 +470,16 @@ function convertStatement(node, context, visible, filename, source) {
 
     if (expressions.length != 1) return unsupportedSyntax("python", node.type, location)
     if (expressions[0].type == "assignment") return convertAssignment(expressions[0], context, visible, filename, source)
+    if (expressions[0].type == "call") {
+      const calleeNode = requiredField(expressions[0], "function", filename, source)
+
+      if (calleeNode.type == "identifier" && calleeNode.text == "print") return convertPrint(expressions[0], filename, source, location)
+      const call = /** @type {import("../semantic/types.js").CallExpression} */ (convertExpression(expressions[0], filename, source))
+
+      return {expression: call, kind: /** @type {const} */ ("ExpressionStatement"), location}
+    }
 
-    return convertPrint(expressions[0], filename, source, location)
+    return unsupportedSyntax("python", "expression statement other than assignment, print, or direct call", location)
   }
 
   return unsupportedSyntax("python", node.type, location)
@@ -611,7 +645,7 @@ function convertFunction(node, context, filename, source) {
     location,
     name,
     parameters,
-    returnType: convertType(returnNode, `Function '${name}' return`, location, filename, source)
+    returnType: convertReturnType(returnNode, `Function '${name}' return`, location, filename, source)
   }, {name: nodeLocation(nameNode, filename, source)})
 }
 

package/src/frontends/ruby.js

@@ -61,7 +61,7 @@ const referenceMethodHooks = new Set([
   "respond_to_missing?", "send", "singleton_class", "size"
 ])
 /** @typedef {{name: string, nameLocation: import("../semantic/types.js").SourceLocation, parameters: import("../semantic/types.js").Parameter[], returnType: import("../semantic/types.js").SemanticFunctionReturnType, typeParameters?: import("../semantic/types.js").TypeParameter[], location: import("../semantic/types.js").SourceLocation}} RubyFunctionSignature */
-/** @typedef {{bindings: Map<string, import("../semantic/types.js").SemanticBindingType>, catchBindingNames?: Set<string>, classes: Map<string, import("../semantic/types.js").ClassDeclaration>, catchBindingNodes?: Map<string, import("../semantic/types.js").CatchBinding>, currentCatchBindingNode?: import("../semantic/types.js").CatchBinding, currentClass?: import("../semantic/types.js").ClassDeclaration, errorNames: Map<string, import("../semantic/types.js").ErrorDeclaration>, errors: Map<string, import("../semantic/types.js").ErrorDeclaration>, functions: Map<string, RubyFunctionSignature>, orderedMapDeclarations?: Set<object>, records: Map<string, import("../semantic/types.js").RecordDeclaration>, recordNames: Map<string, import("../semantic/types.js").RecordDeclaration | import("../semantic/types.js").ClassDeclaration | import("../semantic/types.js").EffectResourceDeclaration>, loopDepth?: number, returnType?: import("../semantic/types.js").SemanticFunctionReturnType, typeParameters?: Map<string, import("../semantic/types.js").TypeParameter>}} RubyConversionContext */
+/** @typedef {{bindings: Map<string, import("../semantic/types.js").SemanticBindingType>, catchBindingNames?: Set<string>, classes: Map<string, import("../semantic/types.js").ClassDeclaration>, catchBindingNodes?: Map<string, import("../semantic/types.js").CatchBinding>, currentCatchBindingNode?: import("../semantic/types.js").CatchBinding, currentClass?: import("../semantic/types.js").ClassDeclaration, errorNames: Map<string, import("../semantic/types.js").ErrorDeclaration>, errors: Map<string, import("../semantic/types.js").ErrorDeclaration>, functions: Map<string, RubyFunctionSignature>, orderedMapDeclarations?: Set<object>, records: Map<string, import("../semantic/types.js").RecordDeclaration>, recordNames: Map<string, import("../semantic/types.js").RecordDeclaration | import("../semantic/types.js").ClassDeclaration | import("../semantic/types.js").EffectResourceDeclaration | import("../semantic/types.js").InterfaceDeclaration>, loopDepth?: number, returnType?: import("../semantic/types.js").SemanticFunctionReturnType, typeParameters?: Map<string, import("../semantic/types.js").TypeParameter>}} RubyConversionContext */
 const rubyBinaryOperations = new Map([
   ["+", "Add"],
   ["-", "Subtract"],
@@ -357,6 +357,9 @@ function convertExpression(node, filename, source, context, expectedType, preser
       reference: referenceType(/** @type {string} */ (declaration.id), nodeLocation(node.receiver, filename, source))},
       {class: nodeLocation(node.receiver, filename, source)})
     }
+    if (declaration.kind == "InterfaceDeclaration") {
+      return unsupportedSyntax("ruby", "construction of an interface", nodeLocation(node.receiver, filename, source))
+    }
     if (declaration.kind == "EffectResourceDeclaration") {
       return unsupportedSyntax("ruby", "owned resource construction", nodeLocation(node.receiver, filename, source))
     }
@@ -817,7 +820,7 @@ function associatedComments(comments, node, source) {
  * @param {LocalVariableWriteNode} node - Local write.
  * @param {string} filename - Source filename.
  * @param {string} source - Complete source.
- * @param {Map<string, import("../semantic/types.js").RecordDeclaration | import("../semantic/types.js").ClassDeclaration | import("../semantic/types.js").EffectResourceDeclaration>} recordNames - Nominal declarations by source name.
+ * @param {Map<string, import("../semantic/types.js").RecordDeclaration | import("../semantic/types.js").ClassDeclaration | import("../semantic/types.js").EffectResourceDeclaration | import("../semantic/types.js").InterfaceDeclaration>} recordNames - Nominal declarations by source name.
  * @param {Map<string, import("../semantic/types.js").TypeParameter>} [typeParameters] - Declaration-scoped parameters.
  * @returns {{immutable: boolean, type: import("../semantic/types.js").SemanticValueType} | undefined} Metadata when present.
  */
@@ -1301,7 +1304,7 @@ function isImmediateCommentGap(gap) {
  * @param {import("../semantic/types.js").SourceLocation} location - Source location.
  * @param {string} source - Complete parser input.
  * @param {import("../semantic/types.js").SourceLocation} [typeLocation] - Exact type comment token location.
- * @param {Map<string, import("../semantic/types.js").RecordDeclaration | import("../semantic/types.js").ClassDeclaration | import("../semantic/types.js").EffectResourceDeclaration>} [recordNames] - Nominal declarations by source name.
+ * @param {Map<string, import("../semantic/types.js").RecordDeclaration | import("../semantic/types.js").ClassDeclaration | import("../semantic/types.js").EffectResourceDeclaration | import("../semantic/types.js").InterfaceDeclaration>} [recordNames] - Nominal declarations by source name.
  * @param {Map<string, import("../semantic/types.js").TypeParameter>} [typeParameters] - Declaration-scoped parameters.
  * @returns {import("../semantic/types.js").SemanticValueType} Semantic type.
  */
@@ -1315,7 +1318,7 @@ function convertType(sourceType, subject, location, source, typeLocation = locat
  * @param {import("@ruby/prism/src/deserialize.js").Comment[]} comments - Prism comments.
  * @param {string} filename - Source filename.
  * @param {string} source - Complete source.
- * @param {Map<string, import("../semantic/types.js").RecordDeclaration | import("../semantic/types.js").ClassDeclaration | import("../semantic/types.js").EffectResourceDeclaration>} recordNames - Nominal declarations by source name.
+ * @param {Map<string, import("../semantic/types.js").RecordDeclaration | import("../semantic/types.js").ClassDeclaration | import("../semantic/types.js").EffectResourceDeclaration | import("../semantic/types.js").InterfaceDeclaration>} recordNames - Nominal declarations by source name.
  * @param {string} ownerId - Stable function identity.
  * @param {boolean} [allowBuiltinOutput] - Whether compiler authority admits the exact output facade function.
  * @returns {RubyFunctionSignature} Semantic signature.
@@ -1380,7 +1383,7 @@ function convertFunctionSignature(node, comments, filename, source, recordNames,
  * @param {DefNode} node - Prism definition.
  * @param {RubyFunctionSignature} signature - Converted signature.
  * @param {Map<string, RubyFunctionSignature>} functions - Module signatures.
- * @param {Map<string, import("../semantic/types.js").RecordDeclaration | import("../semantic/types.js").ClassDeclaration | import("../semantic/types.js").EffectResourceDeclaration>} recordNames - Nominal declarations by source name.
+ * @param {Map<string, import("../semantic/types.js").RecordDeclaration | import("../semantic/types.js").ClassDeclaration | import("../semantic/types.js").EffectResourceDeclaration | import("../semantic/types.js").InterfaceDeclaration>} recordNames - Nominal declarations by source name.
  * @param {Map<string, import("../semantic/types.js").RecordDeclaration>} records - Record declarations by identity.
  * @param {Map<string, import("../semantic/types.js").ClassDeclaration>} classes - Reference classes by identity.
  * @param {Map<string, import("../semantic/types.js").ErrorDeclaration>} errorNames - Error declarations by source name.
@@ -1491,7 +1494,7 @@ function convertRubyError(node, declaration, filename, source) {
  * Converts the bounded Ruby reference-class profile.
  * @param {ClassNode} node - Prism class declaration.
  * @param {import("../semantic/types.js").ClassDeclaration} declaration - Predeclared class identity.
- * @param {Map<string, import("../semantic/types.js").RecordDeclaration | import("../semantic/types.js").ClassDeclaration | import("../semantic/types.js").EffectResourceDeclaration>} nominalNames - Visible nominal declarations.
+ * @param {Map<string, import("../semantic/types.js").RecordDeclaration | import("../semantic/types.js").ClassDeclaration | import("../semantic/types.js").EffectResourceDeclaration | import("../semantic/types.js").InterfaceDeclaration>} nominalNames - Visible nominal declarations.
  * @param {Map<string, import("../semantic/types.js").RecordDeclaration>} records - Records by identity.
  * @param {Map<string, import("../semantic/types.js").ClassDeclaration>} classes - Classes by identity.
  * @param {Map<string, RubyFunctionSignature>} functions - Top-level signatures.
@@ -1607,7 +1610,7 @@ function convertRubyReferenceClass(node, declaration, nominalNames, records, cla
  * Converts one exact typed-reader/initializer/freeze Ruby record profile.
  * @param {ClassNode} node - Prism class declaration.
  * @param {import("../semantic/types.js").RecordDeclaration} declaration - Predeclared nominal identity.
- * @param {Map<string, import("../semantic/types.js").RecordDeclaration | import("../semantic/types.js").ClassDeclaration | import("../semantic/types.js").EffectResourceDeclaration>} recordNames - Nominal declarations by name.
+ * @param {Map<string, import("../semantic/types.js").RecordDeclaration | import("../semantic/types.js").ClassDeclaration | import("../semantic/types.js").EffectResourceDeclaration | import("../semantic/types.js").InterfaceDeclaration>} recordNames - Nominal declarations by name.
  * @param {import("@ruby/prism/src/deserialize.js").Comment[]} comments - Parser-owned comments.
  * @param {string} filename - Source filename.
  * @param {string} source - Complete source.
@@ -1894,7 +1897,7 @@ export function parseRuby({capabilities = [], filename, source, program}) {
     classDeclarations.findIndex((candidate) => candidate.name == declaration.name) != index)
 
   if (reopened) return unsupportedSyntax("ruby", `reference class reopening '${reopened.name}'`, reopened.location)
-  const recordNames = /** @type {Map<string, import("../semantic/types.js").RecordDeclaration | import("../semantic/types.js").ClassDeclaration | import("../semantic/types.js").EffectResourceDeclaration>} */ (
+  const recordNames = /** @type {Map<string, import("../semantic/types.js").RecordDeclaration | import("../semantic/types.js").ClassDeclaration | import("../semantic/types.js").EffectResourceDeclaration | import("../semantic/types.js").InterfaceDeclaration>} */ (
     new Map(program?.records ?? []))
   for (const [name, declaration] of program?.classes ?? []) recordNames.set(name, declaration)
   for (const resource of capabilities.flatMap(({resources}) => resources)) recordNames.set(resource.name, resource)

package/src/frontends/types.js

@@ -55,6 +55,7 @@ export function iterationBindingType(type, location) {
   if (type.kind == "RecordType") return recordType(type.declarationId, location,
     type.arguments?.map((argument) => iterationBindingType(argument, location)))
   if (type.kind == "ReferenceType") return referenceType(type.declarationId, location)
+  if (type.kind == "InterfaceType") return interfaceType(type.declarationId, location)
   if (type.kind == "OwnedResourceType") return ownedResourceType(type.resourceId, location)
   if (type.kind == "OwnedReferenceType") return ownedReferenceType(type.declarationId, location)
 
@@ -166,6 +167,19 @@ export function referenceType(declarationId, location) {
   return type
 }
 
+/**
+ * Builds one nominal interface type with a parser-owned type range.
+ * @param {string} declarationId - Stable interface declaration identity.
+ * @param {import("../semantic/types.js").SourceLocation} location - Complete type-expression range.
+ * @returns {import("../semantic/types.js").InterfaceType} Interface type.
+ */
+export function interfaceType(declarationId, location) {
+  const type = {declarationId, kind: /** @type {const} */ ("InterfaceType")}
+
+  setParserRanges(type, {type: location})
+  return type
+}
+
 /**
  * Builds one compiler-owned resource type with a parser-owned name range.
  * @param {string} resourceId - Stable capability resource identity.
@@ -392,7 +406,7 @@ function collectKnownSubstitutions(formal, actual, substitutions) {
  * @param {"javascript" | "php" | "ruby"} input.language - Comment profile.
  * @param {import("../semantic/types.js").SourceLocation} input.location - Exact type token range.
  * @param {import("../semantic/types.js").SourceLocation} input.ownerLocation - Owning declaration range.
- * @param {Map<string, import("../semantic/types.js").RecordDeclaration | import("../semantic/types.js").ClassDeclaration | import("../semantic/types.js").EffectResourceDeclaration>} [input.records] - Available nominal declarations by source name.
+ * @param {Map<string, import("../semantic/types.js").RecordDeclaration | import("../semantic/types.js").ClassDeclaration | import("../semantic/types.js").EffectResourceDeclaration | import("../semantic/types.js").InterfaceDeclaration>} [input.records] - Available nominal declarations by source name.
  * @param {Map<string, import("../semantic/types.js").TypeParameter>} [input.typeParameters] - Declaration-scoped parameters by name.
  * @param {string} input.source - Complete parser input for exact subranges.
  * @param {string | undefined} input.sourceType - Exact comment-parser/Prism-owned type token.
@@ -451,9 +465,11 @@ export function documentedValueType({language, location, ownerLocation, records
 
   if (directRecord?.id) return directRecord.kind == "ClassDeclaration"
     ? referenceType(directRecord.id, location)
-    : directRecord.kind == "EffectResourceDeclaration"
-      ? ownedResourceType(directRecord.id, location)
-      : recordType(directRecord.id, location)
+    : directRecord.kind == "InterfaceDeclaration"
+      ? interfaceType(directRecord.id, location)
+      : directRecord.kind == "EffectResourceDeclaration"
+        ? ownedResourceType(directRecord.id, location)
+        : recordType(directRecord.id, location)
   const directTypeParameter = typeParameters.get(unwrappedName)
 
   if (directTypeParameter?.id) return typeVariable(directTypeParameter.id, location)
@@ -484,7 +500,7 @@ class DocumentedTypeParser {
    * @param {string} text - Parser-owned type text.
    * @param {import("../semantic/types.js").SourceLocation} location - Whole token location.
    * @param {string} source - Complete source.
-   * @param {Map<string, import("../semantic/types.js").RecordDeclaration | import("../semantic/types.js").ClassDeclaration | import("../semantic/types.js").EffectResourceDeclaration>} records - Available nominal declarations.
+   * @param {Map<string, import("../semantic/types.js").RecordDeclaration | import("../semantic/types.js").ClassDeclaration | import("../semantic/types.js").EffectResourceDeclaration | import("../semantic/types.js").InterfaceDeclaration>} records - Available nominal declarations.
    * @param {Map<string, import("../semantic/types.js").TypeParameter>} typeParameters - Declaration-scoped parameters.
    */
   constructor(language, text, location, source, records, typeParameters) {
@@ -580,9 +596,11 @@ class DocumentedTypeParser {
     if (record?.id && this.text[this.offset] != "<" && this.text[this.offset] != "[") {
       const type = record.kind == "ClassDeclaration"
         ? referenceType(record.id, this.range(start, nameEnd))
-        : record.kind == "EffectResourceDeclaration"
-          ? ownedResourceType(record.id, this.range(start, nameEnd))
-          : recordType(record.id, this.range(start, nameEnd))
+        : record.kind == "InterfaceDeclaration"
+          ? interfaceType(record.id, this.range(start, nameEnd))
+          : record.kind == "EffectResourceDeclaration"
+            ? ownedResourceType(record.id, this.range(start, nameEnd))
+            : recordType(record.id, this.range(start, nameEnd))
 
       if (this.language == "ruby" && this.consume("?")) {
         return optionalType(type, this.range(start, this.offset), this.typeRange(type, start, nameEnd))

package/src/language-registry.js

@@ -169,6 +169,7 @@ export function createLanguageRegistry(candidateRecords) {
     }
     if (typeof candidate.roundTrip != "boolean") invalidRegistry(`Registry record '${id}' requires a Boolean round-trip declaration.`, id)
     const featuresCandidate = candidate.features ?? {
+      boundedSubtyping: false,
       closedRecords: false,
       conditionControlledLoops: false,
       conditionalExpressions: false,
@@ -185,7 +186,8 @@ export function createLanguageRegistry(candidateRecords) {
     }
 
     if (!isPlainObject(featuresCandidate) ||
-      Object.keys(featuresCandidate).sort().join(",") != "closedRecords,conditionControlledLoops,conditionalExpressions,effectfulCapabilitiesAndResources,generalFunctionsAndCalls,immutableCollections,optionalValues,orderedListIteration,orderedMapIteration,referenceClasses,stringInterpolation,typeParametersAndGenerics,typedErrors" ||
+      Object.keys(featuresCandidate).sort().join(",") != "boundedSubtyping,closedRecords,conditionControlledLoops,conditionalExpressions,effectfulCapabilitiesAndResources,generalFunctionsAndCalls,immutableCollections,optionalValues,orderedListIteration,orderedMapIteration,referenceClasses,stringInterpolation,typeParametersAndGenerics,typedErrors" ||
+      typeof featuresCandidate.boundedSubtyping != "boolean" ||
       typeof featuresCandidate.closedRecords != "boolean" ||
       typeof featuresCandidate.conditionControlledLoops != "boolean" ||
       typeof featuresCandidate.conditionalExpressions != "boolean" ||
@@ -196,12 +198,14 @@ export function createLanguageRegistry(candidateRecords) {
       typeof featuresCandidate.orderedListIteration != "boolean" ||
       typeof featuresCandidate.orderedMapIteration != "boolean" ||
       typeof featuresCandidate.referenceClasses != "boolean" ||
+      (featuresCandidate.boundedSubtyping && !featuresCandidate.referenceClasses) ||
       typeof featuresCandidate.stringInterpolation != "boolean" ||
       typeof featuresCandidate.typedErrors != "boolean" ||
       typeof featuresCandidate.typeParametersAndGenerics != "boolean") {
       invalidRegistry(`Registry record '${id}' has an invalid feature declaration.`, id)
     }
     const features = deepFreeze(/** @type {import("./semantic/types.js").LanguageFeatureCapabilities} */ ({
+      boundedSubtyping: featuresCandidate.boundedSubtyping,
       closedRecords: featuresCandidate.closedRecords,
       conditionControlledLoops: featuresCandidate.conditionControlledLoops,
       conditionalExpressions: featuresCandidate.conditionalExpressions,
@@ -541,6 +545,22 @@ const records = [
     acceptance: {stages: ["parse", "generate", "compile", "execute"], toolchains: ["python"]},
     check: {factory: createPythonCheckPlan, stages: ["compile"], toolchains: ["python"]},
     defaultFilename: "program.py",
+    features: {
+      boundedSubtyping: false,
+      closedRecords: false,
+      conditionControlledLoops: false,
+      conditionalExpressions: false,
+      effectfulCapabilitiesAndResources: false,
+      generalFunctionsAndCalls: true,
+      immutableCollections: false,
+      optionalValues: false,
+      orderedListIteration: false,
+      orderedMapIteration: false,
+      referenceClasses: false,
+      stringInterpolation: false,
+      typedErrors: false,
+      typeParametersAndGenerics: false
+    },
     frontend: pythonFrontend,
     id: "python",
     mediaType: "text/x-python",
@@ -582,6 +602,7 @@ const records = [
       optionalValues: false,
       orderedListIteration: false,
       orderedMapIteration: false,
+      boundedSubtyping: false,
       referenceClasses: false,
       typedErrors: false,
       typeParametersAndGenerics: false
@@ -621,6 +642,7 @@ const records = [
       optionalValues: false,
       orderedListIteration: false,
       orderedMapIteration: false,
+      boundedSubtyping: false,
       referenceClasses: false,
       typedErrors: false,
       typeParametersAndGenerics: false
@@ -646,6 +668,7 @@ const records = [
       optionalValues: false,
       orderedListIteration: false,
       orderedMapIteration: false,
+      boundedSubtyping: false,
       referenceClasses: false,
       typedErrors: false,
       typeParametersAndGenerics: false
@@ -661,7 +684,7 @@ const records = [
     artifactMultiplicity: "multiple",
     binaryBackend: generateBrowserWasm,
     defaultFilename: "program.wasm",
-    features: {closedRecords: false, conditionControlledLoops: false, conditionalExpressions: false, stringInterpolation: false, effectfulCapabilitiesAndResources: false, generalFunctionsAndCalls: false, immutableCollections: false, optionalValues: false, orderedListIteration: false, orderedMapIteration: false, referenceClasses: false, typedErrors: false, typeParametersAndGenerics: false},
+    features: {boundedSubtyping: false, closedRecords: false, conditionControlledLoops: false, conditionalExpressions: false, stringInterpolation: false, effectfulCapabilitiesAndResources: false, generalFunctionsAndCalls: false, immutableCollections: false, optionalValues: false, orderedListIteration: false, orderedMapIteration: false, referenceClasses: false, typedErrors: false, typeParametersAndGenerics: false},
     id: "wasm",
     mapping: {binaryRanges: true, richText: true, sourceMapV3: true},
     mediaType: "application/wasm",
@@ -671,7 +694,7 @@ const records = [
     acceptance: {stages: ["generate", "compile", "validate", "instantiate", "execute"], toolchains: ["android"]},
     applicationBackend: generateAndroidApplication,
     artifactMultiplicity: "multiple",
-    features: {closedRecords: false, conditionControlledLoops: false, conditionalExpressions: false, stringInterpolation: false, effectfulCapabilitiesAndResources: false, generalFunctionsAndCalls: false, immutableCollections: false, optionalValues: false, orderedListIteration: false, orderedMapIteration: false, referenceClasses: false, typedErrors: false, typeParametersAndGenerics: false},
+    features: {boundedSubtyping: false, closedRecords: false, conditionControlledLoops: false, conditionalExpressions: false, stringInterpolation: false, effectfulCapabilitiesAndResources: false, generalFunctionsAndCalls: false, immutableCollections: false, optionalValues: false, orderedListIteration: false, orderedMapIteration: false, referenceClasses: false, typedErrors: false, typeParametersAndGenerics: false},
     id: "android",
     mapping: {binaryRanges: true, richText: true, sourceMapV3: true},
     roundTrip: false
@@ -680,7 +703,7 @@ const records = [
     acceptance: {stages: ["generate"], toolchains: []},
     applicationBackend: generateIosApplication,
     artifactMultiplicity: "multiple",
-    features: {closedRecords: false, conditionControlledLoops: false, conditionalExpressions: false, stringInterpolation: false, effectfulCapabilitiesAndResources: false, generalFunctionsAndCalls: false, immutableCollections: false, optionalValues: false, orderedListIteration: false, orderedMapIteration: false, referenceClasses: false, typedErrors: false, typeParametersAndGenerics: false},
+    features: {boundedSubtyping: false, closedRecords: false, conditionControlledLoops: false, conditionalExpressions: false, stringInterpolation: false, effectfulCapabilitiesAndResources: false, generalFunctionsAndCalls: false, immutableCollections: false, optionalValues: false, orderedListIteration: false, orderedMapIteration: false, referenceClasses: false, typedErrors: false, typeParametersAndGenerics: false},
     id: "ios",
     mapping: {binaryRanges: true, richText: true, sourceMapV3: true},
     roundTrip: false
@@ -689,7 +712,7 @@ const records = [
     acceptance: {stages: ["generate", "restore", "compile", "validate", "instantiate", "execute"], toolchains: ["flutter", "android"]},
     applicationBackend: generateFlutterApplication,
     artifactMultiplicity: "multiple",
-    features: {closedRecords: false, conditionControlledLoops: false, conditionalExpressions: false, stringInterpolation: false, effectfulCapabilitiesAndResources: false, generalFunctionsAndCalls: false, immutableCollections: false, optionalValues: false, orderedListIteration: false, orderedMapIteration: false, referenceClasses: false, typedErrors: false, typeParametersAndGenerics: false},
+    features: {boundedSubtyping: false, closedRecords: false, conditionControlledLoops: false, conditionalExpressions: false, stringInterpolation: false, effectfulCapabilitiesAndResources: false, generalFunctionsAndCalls: false, immutableCollections: false, optionalValues: false, orderedListIteration: false, orderedMapIteration: false, referenceClasses: false, typedErrors: false, typeParametersAndGenerics: false},
     id: "flutter",
     mapping: {binaryRanges: true, richText: true, sourceMapV3: true},
     roundTrip: false
@@ -712,6 +735,7 @@ function language(values) {
   return {
     artifactMultiplicity: "single",
     features: {
+      boundedSubtyping: String(values.id) == "php",
       closedRecords: ["php", "ruby", "javascript", "typescript", "java"].includes(String(values.id)),
       conditionControlledLoops: ["php", "ruby", "javascript", "typescript", "java"].includes(String(values.id)),
       conditionalExpressions: ["php", "ruby", "javascript", "typescript", "java"].includes(String(values.id)),

package/src/mapping.js

@@ -764,7 +764,7 @@ export function validateMapping(value) {
   for (const symbol of mapping.symbols) {
     if (!symbol || typeof symbol != "object" || typeof symbol.id != "string" || symbol.id.length == 0 || symbolIds.has(symbol.id) ||
       typeof symbol.name != "string" || symbol.name.length == 0 ||
-      !["capability", "resource", "failure", "operation", "record", "class", "error", "field", "constructor", "method", "function", "typeParameter", "parameter", "local", "iteration", "catch"].includes(symbol.kind) ||
+      !["capability", "resource", "failure", "operation", "record", "interface", "interfaceMethod", "class", "error", "field", "constructor", "method", "function", "typeParameter", "parameter", "local", "iteration", "catch"].includes(symbol.kind) ||
       !nodeIds.has(symbol.declarationNodeId) || !Array.isArray(symbol.references) ||
       symbol.semanticDeclarationId !== undefined && (typeof symbol.semanticDeclarationId != "string" || !(
         symbol.kind == "function" && /^(?:[a-z][a-z0-9._-]*#)?function:[0-9]+$/u.test(symbol.semanticDeclarationId) ||
@@ -774,6 +774,8 @@ export function validateMapping(value) {
         symbol.kind == "field" && /^(?:[a-z][a-z0-9._-]*#)?(?:record|class):[0-9]+:field:[0-9]+$/u.test(symbol.semanticDeclarationId) ||
         symbol.kind == "constructor" && /^(?:[a-z][a-z0-9._-]*#)?class:[0-9]+:constructor$/u.test(symbol.semanticDeclarationId) ||
         symbol.kind == "method" && /^(?:[a-z][a-z0-9._-]*#)?class:[0-9]+:method:[0-9]+$/u.test(symbol.semanticDeclarationId) ||
+        symbol.kind == "interface" && /^(?:[a-z][a-z0-9._-]*#)?interface:[0-9]+$/u.test(symbol.semanticDeclarationId) ||
+        symbol.kind == "interfaceMethod" && /^(?:[a-z][a-z0-9._-]*#)?interface:[0-9]+:method:[0-9]+$/u.test(symbol.semanticDeclarationId) ||
         symbol.kind == "typeParameter" && /^(?:[a-z][a-z0-9._-]*#)?(?:function|record):[0-9]+:type:[0-9]+$/u.test(symbol.semanticDeclarationId) ||
         symbol.kind == "capability" && /^(?:module:[0-9]+\/)?capability:[0-9]+$/u.test(symbol.semanticDeclarationId) ||
         symbol.kind == "resource" && /^(?:module:[0-9]+\/)?capability:[0-9]+\/resource:[0-9]+$/u.test(symbol.semanticDeclarationId) ||

package/src/semantic/effects.js

@@ -326,6 +326,7 @@ function typeIdentity(type) {
   if (type.kind == "RecordType") return {arguments: type.arguments?.map((argument) =>
     /** @type {import("./types.js").SemanticTypeIdentity} */ (typeIdentity(argument))), declarationId: type.declarationId, kind: type.kind}
   if (type.kind == "ReferenceType") return {declarationId: type.declarationId, kind: type.kind}
+  if (type.kind == "InterfaceType") return {declarationId: type.declarationId, kind: type.kind}
   return {kind: type.kind, parameterId: type.parameterId}
 }
 

package/src/semantic/provenance.js

@@ -492,6 +492,7 @@ export function semanticEntries(module) {
         node.imports.forEach((child, index) => visit(child, `/imports/${index}`, location))
       }
       ;(node.records ?? []).forEach((child, index) => visit(child, `/records/${index}`, location))
+      ;(node.interfaces ?? []).forEach((child, index) => visit(child, `/interfaces/${index}`, location))
       if (!("sourceFilename" in node) || Reflect.get(node, "stdlibFacade") !== undefined) {
         ;(node.classes ?? []).forEach((child, index) => visit(child, `/classes/${index}`, location))
       }
@@ -512,7 +513,14 @@ export function semanticEntries(module) {
     } else if (node.kind == "EffectOperationDeclaration") {
       node.parameters.forEach((child, index) => visit(child.type, `${path}/parameters/${index}/type`, location))
       visit(node.returnType, `${path}/returnType`, location)
+    } else if (node.kind == "InterfaceDeclaration") {
+      (node.extends ?? []).forEach((child, index) => visit(child, `${path}/extends/${index}`, location))
+      node.methods.forEach((child, index) => visit(child, `${path}/methods/${index}`, location))
+    } else if (node.kind == "InterfaceMethodDeclaration") {
+      node.parameters.forEach((child, index) => visit(child.type, `${path}/parameters/${index}/type`, location))
+      visit(node.returnType, `${path}/returnType`, location)
     } else if (node.kind == "ClassDeclaration") {
+      (node.implements ?? []).forEach((child, index) => visit(child, `${path}/implements/${index}`, location))
       node.fields.forEach((child, index) => visit(child, `${path}/fields/${index}`, location))
       visit(node.constructor, `${path}/constructor`, location)
       node.methods.forEach((child, index) => visit(child, `${path}/methods/${index}`, location))
@@ -665,6 +673,10 @@ function resolveSymbols(module, records) {
   /** @type {Map<string, string>} */
   const fieldSymbols = new Map()
   /** @type {Map<string, string>} */
+  const interfaceSymbols = new Map()
+  /** @type {Map<string, string>} */
+  const interfaceMethodSymbols = new Map()
+  /** @type {Map<string, string>} */
   const classSymbols = new Map()
   /** @type {Map<string, string>} */
   const constructorSymbols = new Map()
@@ -724,11 +736,29 @@ function resolveSymbols(module, records) {
     if (declaration.id) errorSymbols.set(declaration.id, symbol)
   }
 
+  for (const [index, declaration] of (module.interfaces ?? []).entries()) {
+    const declarationPath = `/interfaces/${index}`
+    const interfaceSymbol = declare(declaration, declaration.name, "interface", declarationPath)
+
+    if (declaration.id) interfaceSymbols.set(declaration.id, interfaceSymbol)
+    for (const [extendsIndex, parent] of (declaration.extends ?? []).entries()) {
+      visitType(parent, `${declarationPath}/extends/${extendsIndex}`)
+    }
+    for (const [methodIndex, method] of declaration.methods.entries()) {
+      const symbol = declare(method, method.name, "interfaceMethod", `${declarationPath}/methods/${methodIndex}`)
+
+      if (method.id) interfaceMethodSymbols.set(method.id, symbol)
+    }
+  }
+
   for (const [index, declaration] of (module.classes ?? []).entries()) {
     const declarationPath = `/classes/${index}`
     const classSymbol = declare(declaration, declaration.name, "class", declarationPath)
 
     if (declaration.id) classSymbols.set(declaration.id, classSymbol)
+    for (const [implementsIndex, implemented] of (declaration.implements ?? []).entries()) {
+      visitType(implemented, `${declarationPath}/implements/${implementsIndex}`)
+    }
     for (const [fieldIndex, field] of declaration.fields.entries()) {
       const symbol = declare(field, field.name, "field", `${declarationPath}/fields/${fieldIndex}`)
 
@@ -806,7 +836,7 @@ function resolveSymbols(module, records) {
 
   /**
    * Declares one canonical symbol.
-   * @param {import("./types.js").EffectCapabilityDeclaration | import("./types.js").EffectResourceDeclaration | import("./types.js").EffectFailureDeclaration | import("./types.js").EffectOperationDeclaration | import("./types.js").RecordDeclaration | import("./types.js").ClassDeclaration | import("./types.js").ErrorDeclaration | import("./types.js").RecordField | import("./types.js").PrivateField | import("./types.js").ConstructorDeclaration | import("./types.js").MethodDeclaration | import("./types.js").FunctionDeclaration | import("./types.js").TypeParameter | import("./types.js").Parameter | import("./types.js").LocalDeclaration | import("./types.js").ValueBinding | import("./types.js").CatchBinding} node - Declaration.
+   * @param {import("./types.js").EffectCapabilityDeclaration | import("./types.js").EffectResourceDeclaration | import("./types.js").EffectFailureDeclaration | import("./types.js").EffectOperationDeclaration | import("./types.js").RecordDeclaration | import("./types.js").ClassDeclaration | import("./types.js").InterfaceDeclaration | import("./types.js").InterfaceMethodDeclaration | import("./types.js").ErrorDeclaration | import("./types.js").RecordField | import("./types.js").PrivateField | import("./types.js").ConstructorDeclaration | import("./types.js").MethodDeclaration | import("./types.js").FunctionDeclaration | import("./types.js").TypeParameter | import("./types.js").Parameter | import("./types.js").LocalDeclaration | import("./types.js").ValueBinding | import("./types.js").CatchBinding} node - Declaration.
    * @param {string} name - Symbol name.
    * @param {import("./types.js").SemanticSymbolKind} kind - Symbol kind.
    * @param {string} path - Declaration occurrence path.
@@ -828,7 +858,7 @@ function resolveSymbols(module, records) {
       location,
       name,
       references: [],
-      ...(["capability", "resource", "failure", "operation", "record", "class", "error", "field", "constructor", "method", "function", "typeParameter"].includes(kind)
+      ...(["capability", "resource", "failure", "operation", "record", "interface", "interfaceMethod", "class", "error", "field", "constructor", "method", "function", "typeParameter"].includes(kind)
         ? {semanticDeclarationId: /** @type {{id?: string}} */ (node).id}
         : {})
     })
@@ -1009,6 +1039,7 @@ function resolveSymbols(module, records) {
       for (const [index, argument] of (type.arguments ?? []).entries()) visitType(argument, `${path}/arguments/${index}`)
     }
     else if (type.kind == "ErrorType") reference(type, errorSymbols.get(type.declarationId), "type", path)
+    else if (type.kind == "InterfaceType") reference(type, interfaceSymbols.get(type.declarationId), "type", path)
     else if (type.kind == "ReferenceType" || type.kind == "OwnedReferenceType") reference(type, classSymbols.get(type.declarationId), "type", path)
     else if (type.kind == "OwnedResourceType") reference(type, resourceSymbols.get(type.resourceId), "type", path)
     else if (type.kind == "ListType") visitType(type.elementType, `${path}/elementType`)
@@ -1020,7 +1051,7 @@ function resolveSymbols(module, records) {
 
   /**
    * Attaches one resolved symbol reference.
-   * @param {import("./types.js").IdentifierExpression | import("./types.js").ReceiverExpression | import("./types.js").CallExpression | import("./types.js").EffectCallExpression | import("./types.js").MethodCallExpression | import("./types.js").TypeVariableReference | import("./types.js").RecordType | import("./types.js").ReferenceType | import("./types.js").OwnedReferenceType | import("./types.js").OwnedResourceType | import("./types.js").RecordConstruction | import("./types.js").ReferenceConstruction | import("./types.js").MemberRead | import("./types.js").PrivateFieldRead | import("./types.js").PrivateFieldWriteStatement | import("./types.js").RethrowStatement | import("./types.js").ErrorType | import("./types.js").ErrorConstruction} node - Reference node.
+   * @param {import("./types.js").IdentifierExpression | import("./types.js").ReceiverExpression | import("./types.js").CallExpression | import("./types.js").EffectCallExpression | import("./types.js").MethodCallExpression | import("./types.js").TypeVariableReference | import("./types.js").RecordType | import("./types.js").ReferenceType | import("./types.js").InterfaceType | import("./types.js").OwnedReferenceType | import("./types.js").OwnedResourceType | import("./types.js").RecordConstruction | import("./types.js").ReferenceConstruction | import("./types.js").MemberRead | import("./types.js").PrivateFieldRead | import("./types.js").PrivateFieldWriteStatement | import("./types.js").RethrowStatement | import("./types.js").ErrorType | import("./types.js").ErrorConstruction} node - Reference node.
    * @param {string | undefined} symbolId - Resolved symbol.
    * @param {"type" | "construct" | "member" | "read" | "write" | "call"} role - Reference role.
    * @param {string} path - Reference occurrence path.

package/src/semantic/types.js

@@ -8,8 +8,8 @@
 /** @typedef {SemanticTypeName | "void"} FunctionReturnTypeName */
 /** @typedef {"IntegerNegate" | "BooleanNot"} SemanticUnaryOperation */
 /** @typedef {"IntegerAdd" | "IntegerSubtract" | "IntegerMultiply" | "BooleanAnd" | "BooleanOr" | "IntegerEqual" | "IntegerNotEqual" | "BooleanEqual" | "BooleanNotEqual" | "StringEqual" | "StringNotEqual" | "IntegerLessThan" | "IntegerLessThanOrEqual" | "IntegerGreaterThan" | "IntegerGreaterThanOrEqual" | "StringConcat"} SemanticBinaryOperation */
-/** @typedef {"capability" | "resource" | "failure" | "operation" | "record" | "class" | "error" | "field" | "constructor" | "method" | "function" | "typeParameter" | "parameter" | "local" | "iteration" | "catch"} SemanticSymbolKind */
-/** @typedef {"record" | "class" | "error" | "function"} SemanticDeclarationKind */
+/** @typedef {"capability" | "resource" | "failure" | "operation" | "record" | "interface" | "interfaceMethod" | "class" | "error" | "field" | "constructor" | "method" | "function" | "typeParameter" | "parameter" | "local" | "iteration" | "catch"} SemanticSymbolKind */
+/** @typedef {"record" | "interface" | "class" | "error" | "function"} SemanticDeclarationKind */
 /** @typedef {"declaration" | "type" | "construct" | "member" | "read" | "write" | "call"} SemanticSymbolRole */
 /** @typedef {"parse" | "generate" | "restore" | "compile" | "link" | "validate" | "instantiate" | "execute"} AcceptanceStage */
 /** @typedef {"entry" | "source" | "manifest" | "support" | "mapping" | "resource" | "loader"} GeneratedArtifactRole */
@@ -186,6 +186,7 @@
  * @property {boolean} typedErrors - Task 011 nominal unchecked errors, raises, and exact typed catches.
  * @property {boolean} typeParametersAndGenerics - Task 012 invariant unbounded type parameters and closed generic applications.
  * @property {boolean} referenceClasses - Task 033 nominal reference classes, private instance state, exact constructors, and receiver methods.
+ * @property {boolean} boundedSubtyping - Task 048 nominal interfaces with exact implementation contracts and implicit upcast (requires referenceClasses).
  * @property {boolean} effectfulCapabilitiesAndResources - Task 034 authorized host effects, typed failures, and owned resources.
  */
 
@@ -700,7 +701,14 @@
  * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned type-name range.
  */
 
-/** @typedef {TypeReference | TypeVariableReference | ListType | MapType | OrderedMapType | OptionalType | RecordType | ReferenceType | OwnedResourceType | OwnedReferenceType} SemanticValueType */
+/**
+ * @typedef InterfaceType
+ * @property {"InterfaceType"} kind - Nominal bounded-subtyping interface type discriminator.
+ * @property {string} declarationId - Stable module-local interface declaration identity.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned type-name range.
+ */
+
+/** @typedef {TypeReference | TypeVariableReference | ListType | MapType | OrderedMapType | OptionalType | RecordType | ReferenceType | OwnedResourceType | OwnedReferenceType | InterfaceType} SemanticValueType */
 /** @typedef {SemanticValueType | ErrorType} SemanticBindingType */
 
 /**
@@ -712,7 +720,7 @@
 
 /** @typedef {SemanticValueType | FunctionReturnTypeReference} SemanticFunctionReturnType */
 
-/** @typedef {SemanticTypeName | {kind: "TypeVariableReference", parameterId: string} | {kind: "ListType", elementType: SemanticTypeIdentity} | {kind: "MapType", keyType: SemanticTypeIdentity, valueType: SemanticTypeIdentity} | {kind: "OrderedMapType", keyType: SemanticTypeIdentity, valueType: SemanticTypeIdentity, order: "insertion"} | {kind: "OptionalType", valueType: SemanticTypeIdentity} | {kind: "RecordType", declarationId: string, arguments?: SemanticTypeIdentity[]} | {kind: "ReferenceType", declarationId: string} | {kind: "OwnedResourceType", resourceId: string} | {kind: "OwnedReferenceType", declarationId: string}} SemanticTypeIdentity */
+/** @typedef {SemanticTypeName | {kind: "TypeVariableReference", parameterId: string} | {kind: "ListType", elementType: SemanticTypeIdentity} | {kind: "MapType", keyType: SemanticTypeIdentity, valueType: SemanticTypeIdentity} | {kind: "OrderedMapType", keyType: SemanticTypeIdentity, valueType: SemanticTypeIdentity, order: "insertion"} | {kind: "OptionalType", valueType: SemanticTypeIdentity} | {kind: "RecordType", declarationId: string, arguments?: SemanticTypeIdentity[]} | {kind: "ReferenceType", declarationId: string} | {kind: "OwnedResourceType", resourceId: string} | {kind: "OwnedReferenceType", declarationId: string} | {kind: "InterfaceType", declarationId: string}} SemanticTypeIdentity */
 /** @typedef {SemanticTypeIdentity | "void"} FunctionReturnTypeIdentity */
 
 /**
@@ -1345,10 +1353,33 @@
  * @property {Block} body - Method body.
  * @property {readonly ["host"]} [effects] - Inferred checked host-effect fact.
  * @property {string[]} [failureIds] - Ordered capability failures reachable through the method.
+ * @property {{interfaceId: string, methodId: string}} [implements] - Exact satisfied interface member, required after validation when the method satisfies an interface contract.
  * @property {SourceLocation} location - Complete method location.
  * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned method-name range.
  */
 
+/**
+ * @typedef InterfaceMethodDeclaration
+ * @property {"InterfaceMethodDeclaration"} kind - Signature-only interface contract member.
+ * @property {string} [id] - Stable interface-scoped method identity, required after validation.
+ * @property {string} name - Source-visible method name.
+ * @property {Parameter[]} parameters - Exact positional required parameters with explicit types.
+ * @property {SemanticFunctionReturnType} returnType - Exact value or void return.
+ * @property {SourceLocation} location - Complete interface method location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned method-name range.
+ */
+
+/**
+ * @typedef InterfaceDeclaration
+ * @property {"InterfaceDeclaration"} kind - Closed signature-only nominal interface with exact implementation contracts.
+ * @property {string} [id] - Stable module-local interface identity, required after validation.
+ * @property {string} name - Source-visible interface name.
+ * @property {InterfaceType[]} [extends] - Direct interface parents in source order; omitted when empty.
+ * @property {InterfaceMethodDeclaration[]} methods - Ordered closed signature set.
+ * @property {SourceLocation} location - Complete interface location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned interface-name range.
+ */
+
 /**
  * @typedef ClassDeclaration
  * @property {"ClassDeclaration"} kind - Nominal reference class with private mutable state.
@@ -1357,6 +1388,7 @@
  * @property {PrivateField[]} fields - Ordered private instance state.
  * @property {ConstructorDeclaration} constructor - Sole exact constructor.
  * @property {MethodDeclaration[]} methods - Ordered receiver methods.
+ * @property {InterfaceType[]} [implements] - Direct interface contracts in source order; omitted when empty.
  * @property {{kind: "ordinary"} | {kind: "ownedResource", fieldId: string, resourceId: string}} [ownership] - Explicit class ownership profile.
  * @property {SourceLocation} location - Complete class location.
  * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned class-name range.
@@ -1391,6 +1423,7 @@
  * @typedef SemanticModule
  * @property {"Module"} kind - Node discriminator.
  * @property {RecordDeclaration[]} [records] - Top-level nominal record declarations in source order; omitted when empty.
+ * @property {InterfaceDeclaration[]} [interfaces] - Top-level nominal interface declarations in source order; omitted when empty.
  * @property {ClassDeclaration[]} [classes] - Top-level nominal reference classes in source order; omitted when empty.
  * @property {ErrorDeclaration[]} [errors] - Top-level nominal unchecked error declarations in source order; omitted when empty.
  * @property {EffectCapabilityDeclaration[]} [capabilities] - Compiler-authorized Task 034 declarations; omission is the legacy empty set.
@@ -1441,6 +1474,7 @@
  * @property {string} id - Stable caller-supplied logical module identity.
  * @property {string} sourceFilename - Explicit source filename; never an implicit read request.
  * @property {RecordDeclaration[]} [records] - Top-level nominal record declarations.
+ * @property {InterfaceDeclaration[]} [interfaces] - Top-level nominal interface declarations.
  * @property {ClassDeclaration[]} [classes] - Compiler-owned facade reference classes.
  * @property {ErrorDeclaration[]} [errors] - Top-level nominal unchecked error declarations.
  * @property {FunctionDeclaration[]} functions - Top-level functions.
@@ -1486,7 +1520,7 @@
  * @property {StdlibFacadeProgramDescriptor} [stdlibFacades] - Complete selected source-language facade closure.
  */
 
-/** @typedef {SemanticModule | SemanticProgramModule | SemanticImport | SemanticExport | RecordDeclaration | ClassDeclaration | ErrorDeclaration | EffectCapabilityDeclaration | EffectResourceDeclaration | EffectFailureDeclaration | EffectOperationDeclaration | RecordField | PrivateField | ConstructorDeclaration | MethodDeclaration | FunctionDeclaration | TypeParameter | Parameter | ValueBinding | CatchBinding | CatchHandler | Block | Statement | EntryPoint | Expression | ErrorConstruction | ErrorType | MapEntry | SemanticValueType | FunctionReturnTypeReference} SemanticNode */
+/** @typedef {SemanticModule | SemanticProgramModule | SemanticImport | SemanticExport | RecordDeclaration | InterfaceDeclaration | InterfaceMethodDeclaration | ClassDeclaration | ErrorDeclaration | EffectCapabilityDeclaration | EffectResourceDeclaration | EffectFailureDeclaration | EffectOperationDeclaration | RecordField | PrivateField | ConstructorDeclaration | MethodDeclaration | FunctionDeclaration | TypeParameter | Parameter | ValueBinding | CatchBinding | CatchHandler | Block | Statement | EntryPoint | Expression | ErrorConstruction | ErrorType | MapEntry | SemanticValueType | FunctionReturnTypeReference} SemanticNode */
 /** @typedef {SemanticNode} SemanticNodeWithoutLocations */
 
 export {}