semantifold 0.12.0 → 0.14.0

package/src/frontends/ruby.js

@@ -49,7 +49,7 @@ import {missingType, SemantifoldDiagnostic, unsupportedSyntax} from "../diagnost
 import {blockReferencesProtectedEntry} from "../semantic/effects.js"
 import {locationFromOffsets, moduleLocation, utf8ByteOffsetToUtf16Offset} from "../semantic/location.js"
 import {withAdaptedOperation} from "../semantic/operators.js"
-import {withParserRanges} from "../semantic/provenance.js"
+import {setParserRanges, withParserRanges} from "../semantic/provenance.js"
 import {hasOnlyUnicodeScalars, scalarType} from "../semantic/scalars.js"
 import {isTask034ResourceProbe} from "../semantic/capabilities.js"
 import {hasExactEffectSupport} from "../backends/effects.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>, classes: Map<string, import("../semantic/types.js").ClassDeclaration>, 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.
  */
@@ -969,15 +972,38 @@ function convertStatement(node, comments, context, filename, source) {
  * @param {RubyConversionContext} context - Typed lexical context.
  * @param {string} filename - Source filename.
  * @param {string} source - Complete source.
- * @returns {import("../semantic/types.js").RaiseStatement} Semantic raise.
+ * @returns {import("../semantic/types.js").RaiseStatement | import("../semantic/types.js").RethrowStatement} Semantic raise or rethrow.
  */
 function convertRubyRaise(node, context, filename, source) {
   const location = nodeLocation(node, filename, source)
   const arguments_ = node.arguments_?.arguments_ ?? []
+
+  if (arguments_.length == 0 && context.currentCatchBindingNode) {
+    return withParserRanges({
+      binding: context.currentCatchBindingNode.name,
+      bindingNode: context.currentCatchBindingNode,
+      kind: /** @type {const} */ ("RethrowStatement"),
+      location
+    }, {keyword: prismLocation(node.messageLoc ?? node.location, filename, source)})
+  }
+  if (arguments_.length == 1 && arguments_[0] instanceof LocalVariableReadNode &&
+    context.catchBindingNames?.has(arguments_[0].name) && context.bindings.get(arguments_[0].name)?.kind == "ErrorType") {
+    const bindingNode = context.catchBindingNodes?.get(arguments_[0].name)
+
+    if (!bindingNode) return unsupportedSyntax("ruby", "raise of a catch binding without an exact handler binding", location)
+    return withParserRanges({
+      binding: arguments_[0].name,
+      bindingNode,
+      kind: /** @type {const} */ ("RethrowStatement"),
+      location
+    }, {keyword: prismLocation(node.messageLoc ?? node.location, filename, source)})
+  }
+  if (node.block || node.callOperatorLoc || arguments_.length != 2) {
+    return unsupportedSyntax("ruby", "raise other than exact declared error and message", location)
+  }
   const errorNode = arguments_[0]
 
-  if (node.block || node.callOperatorLoc || arguments_.length != 2 ||
-    !(errorNode instanceof ConstantReadNode) && !(errorNode instanceof ConstantPathNode) ||
+  if (!(errorNode instanceof ConstantReadNode) && !(errorNode instanceof ConstantPathNode) ||
     !context.errorNames.has(constantPathName(errorNode))) {
     return unsupportedSyntax("ruby", "raise other than exact declared error and message", location)
   }
@@ -997,48 +1023,104 @@ function convertRubyRaise(node, context, filename, source) {
 }
 
 /**
- * Converts one exact typed rescue with no else/ensure.
+ * Converts one exact Prism ensure clause body.
+ * @param {import("@ruby/prism").EnsureNode} node - Prism ensure clause.
+ * @param {import("@ruby/prism/src/deserialize.js").Comment[]} comments - Prism comments.
+ * @param {RubyConversionContext} context - Typed lexical context.
+ * @param {string} filename - Source filename.
+ * @param {string} source - Complete source.
+ * @returns {import("../semantic/types.js").Block} Semantic finally block.
+ */
+function convertRubyEnsure(node, comments, context, filename, source) {
+  // A completion block gets its own binding scope, like every other block in convertRubyTry: a local
+  // declaration inside `ensure` must not leak back into the enclosing conversion context.
+  return convertBlock(node.statements ?? null, comments, {...context, bindings: new Map(context.bindings)}, filename, source,
+    nodeLocation(node, filename, source))
+}
+
+/**
+ * Converts one begin block with ordered exact typed rescues and an optional ensure completion block.
  * @param {BeginNode} node - Prism begin node.
  * @param {import("@ruby/prism/src/deserialize.js").Comment[]} comments - Parser-owned comments.
  * @param {RubyConversionContext} context - Typed lexical context.
  * @param {string} filename - Source filename.
  * @param {string} source - Complete source.
- * @returns {import("../semantic/types.js").TryStatement} Semantic exact handler.
+ * @returns {import("../semantic/types.js").TryStatement} Semantic exact handler chain.
  */
 function convertRubyTry(node, comments, context, filename, source) {
   const location = nodeLocation(node, filename, source)
-  const handler = node.rescueClause
 
-  if (!(handler instanceof RescueNode) || handler.subsequent || node.elseClause || node.ensureClause ||
-    handler.exceptions.length != 1 ||
-    !(handler.exceptions[0] instanceof ConstantReadNode) && !(handler.exceptions[0] instanceof ConstantPathNode) ||
-    !context.errorNames.has(constantPathName(handler.exceptions[0])) || !(handler.reference instanceof LocalVariableTargetNode)) {
-    return unsupportedSyntax("ruby", "begin without one exact typed rescue and binding", location)
+  if (node.elseClause) return unsupportedSyntax("ruby", "begin else clause", nodeLocation(node.elseClause, filename, source))
+  /** @type {import("../semantic/types.js").CatchHandler[]} */
+  const handlers = []
+  const seenHandlerNames = new Set(context.catchBindingNames ?? [])
+  let handler = node.rescueClause
+
+  if (!(handler instanceof RescueNode)) {
+    if (node.ensureClause) {
+      return withParserRanges({
+        body: convertBlock(node.statements, comments, context, filename, source, location),
+        handlers,
+        kind: /** @type {const} */ ("TryStatement"),
+        location,
+        finallyBody: convertRubyEnsure(node.ensureClause, comments, context, filename, source)
+      }, {ensure: nodeLocation(node.ensureClause, filename, source), try: location})
+    }
+    return unsupportedSyntax("ruby", "begin without rescue or ensure", location)
   }
-  const errorNode = handler.exceptions[0]
-  const declaration = /** @type {import("../semantic/types.js").ErrorDeclaration} */ (context.errorNames.get(constantPathName(errorNode)))
-  const caughtLocation = nodeLocation(errorNode, filename, source)
-  const catchType = withParserRanges({declarationId: /** @type {string} */ (declaration.id), kind: /** @type {const} */ ("ErrorType")}, {
-    type: caughtLocation
-  })
   const bodyContext = {...context, bindings: new Map(context.bindings)}
-  const catchContext = {...context, bindings: new Map(context.bindings)}
+  while (handler instanceof RescueNode) {
+    if (handler.exceptions.length != 1 ||
+      !(handler.exceptions[0] instanceof ConstantReadNode) && !(handler.exceptions[0] instanceof ConstantPathNode) ||
+      !context.errorNames.has(constantPathName(handler.exceptions[0])) || !(handler.reference instanceof LocalVariableTargetNode)) {
+      return unsupportedSyntax("ruby", "rescue without one exact typed exception and binding", nodeLocation(handler, filename, source))
+    }
+    if (seenHandlerNames.has(handler.reference.name)) {
+      return unsupportedSyntax("ruby", `rescue binding '${handler.reference.name}' shadows an outer handler binding`,
+        nodeLocation(handler.reference, filename, source))
+    }
+    seenHandlerNames.add(handler.reference.name)
+    const errorNode = handler.exceptions[0]
+    const declaration = /** @type {import("../semantic/types.js").ErrorDeclaration} */ (context.errorNames.get(constantPathName(errorNode)))
+    const caughtLocation = nodeLocation(errorNode, filename, source)
+    const catchType = withParserRanges({declarationId: /** @type {string} */ (declaration.id), kind: /** @type {const} */ ("ErrorType")}, {
+      type: caughtLocation
+    })
+    const catchContext = {...context, bindings: new Map(context.bindings), catchBindingNames: new Set(seenHandlerNames),
+      catchBindingNodes: new Map(context.catchBindingNodes)}
 
-  catchContext.bindings.set(handler.reference.name, catchType)
-  return withParserRanges({
-    body: convertBlock(node.statements, comments, bodyContext, filename, source, location),
-    catchBinding: withParserRanges({
+    catchContext.bindings.set(handler.reference.name, catchType)
+    const catchBindingNode = withParserRanges({
       kind: /** @type {const} */ ("CatchBinding"),
       location: nodeLocation(handler.reference, filename, source),
       mutable: /** @type {const} */ (false),
       name: handler.reference.name,
       type: catchType
-    }, {name: nodeLocation(handler.reference, filename, source)}),
-    catchBody: convertBlock(handler.statements, comments, catchContext, filename, source, nodeLocation(handler, filename, source)),
-    catchType,
+    }, {name: nodeLocation(handler.reference, filename, source)})
+
+    catchContext.catchBindingNodes.set(handler.reference.name, catchBindingNode)
+    catchContext.currentCatchBindingNode = catchBindingNode
+    handlers.push(withParserRanges({
+      catchBinding: catchBindingNode,
+      catchBody: convertBlock(handler.statements, comments, catchContext, filename, source, nodeLocation(handler, filename, source)),
+      catchType,
+      kind: /** @type {const} */ ("CatchHandler"),
+      location: nodeLocation(handler, filename, source)
+    }, {catch: nodeLocation(handler, filename, source)}))
+    handler = handler.subsequent
+  }
+  const semantic = /** @type {import("../semantic/types.js").TryStatement} */ (withParserRanges({
+    body: convertBlock(node.statements, comments, bodyContext, filename, source, location),
+    handlers,
     kind: /** @type {const} */ ("TryStatement"),
     location
-  }, {catch: nodeLocation(handler, filename, source), try: location})
+  }, {try: location}))
+
+  if (node.ensureClause) {
+    semantic.finallyBody = convertRubyEnsure(node.ensureClause, comments, context, filename, source)
+    setParserRanges(semantic, {ensure: nodeLocation(node.ensureClause, filename, source), try: location})
+  }
+  return semantic
 }
 
 /**
@@ -1222,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.
  */
@@ -1236,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.
@@ -1301,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.
@@ -1412,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.
@@ -1528,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.
@@ -1815,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,
@@ -582,6 +586,7 @@ const records = [
       optionalValues: false,
       orderedListIteration: false,
       orderedMapIteration: false,
+      boundedSubtyping: false,
       referenceClasses: false,
       typedErrors: false,
       typeParametersAndGenerics: false
@@ -621,6 +626,7 @@ const records = [
       optionalValues: false,
       orderedListIteration: false,
       orderedMapIteration: false,
+      boundedSubtyping: false,
       referenceClasses: false,
       typedErrors: false,
       typeParametersAndGenerics: false
@@ -646,6 +652,7 @@ const records = [
       optionalValues: false,
       orderedListIteration: false,
       orderedMapIteration: false,
+      boundedSubtyping: false,
       referenceClasses: false,
       typedErrors: false,
       typeParametersAndGenerics: false
@@ -661,7 +668,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 +678,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 +687,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 +696,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 +719,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}
 }
 
@@ -379,10 +380,19 @@ function escapingBlockFailures(block, functionSummaries, methodSummaries, capabi
 
   for (const statement of block.statements) {
     if (statement.kind == "TryStatement") {
-      const body = escapingBlockFailures(statement.body, functionSummaries, methodSummaries, capabilityFailureIds)
+      let body = escapingBlockFailures(statement.body, functionSummaries, methodSummaries, capabilityFailureIds)
 
-      if (body.delete(statement.catchType.declarationId)) {
-        addFailures(result, escapingBlockFailures(statement.catchBody, functionSummaries, methodSummaries, capabilityFailureIds))
+      for (const handler of statement.handlers ?? []) {
+        const caughtId = handler.catchType?.declarationId
+
+        if (typeof caughtId == "string" && body.delete(caughtId)) {
+          addFailures(body, escapingBlockFailures(handler.catchBody, functionSummaries, methodSummaries, capabilityFailureIds))
+        }
+      }
+      if (statement.finallyBody) {
+        // A completion block that can raise replaces the pending completion on the paths where it does,
+        // but pending failures still escape on the paths where it completes normally, so both are reachable.
+        addFailures(body, escapingBlockFailures(statement.finallyBody, functionSummaries, methodSummaries, capabilityFailureIds))
       }
       addFailures(result, body)
       continue
@@ -639,7 +649,9 @@ function forEachBlockExpression(block, visitor, postorder) {
       visit(statement.condition); forEachBlockExpression(statement.body, visitor, postorder)
     } else if (statement.kind == "RaiseStatement") visit(statement.error.message)
     else if (statement.kind == "TryStatement") {
-      forEachBlockExpression(statement.body, visitor, postorder); forEachBlockExpression(statement.catchBody, visitor, postorder)
+      forEachBlockExpression(statement.body, visitor, postorder)
+      for (const handler of statement.handlers) forEachBlockExpression(handler.catchBody, visitor, postorder)
+      if (statement.finallyBody) forEachBlockExpression(statement.finallyBody, visitor, postorder)
     }
   }
 
@@ -694,7 +706,8 @@ function statementReferencesProtectedEntry(statement) {
     case "RaiseStatement":
       return expressionReferencesProtectedEntry(statement.error.message)
     case "TryStatement":
-      return blockReferencesProtectedEntry(statement.body) || blockReferencesProtectedEntry(statement.catchBody)
+      return blockReferencesProtectedEntry(statement.body) || statement.handlers.some((handler) => blockReferencesProtectedEntry(handler.catchBody)) ||
+        (statement.finallyBody ? blockReferencesProtectedEntry(statement.finallyBody) : false)
     default:
       return false
   }

package/src/semantic/lifetime.js

@@ -123,6 +123,10 @@ function analyzeStatement(statement, state, fail, locals, errorEffects) {
       ? {errorId: statement.error.error.declarationId, kind: "raise", location: statement.location, state: flow.state}
       : {...flow, location: statement.location})
   }
+  if (statement.kind == "RethrowStatement") {
+    // A rethrow re-raises the caught binding's exact nominal type, so an enclosing handler must see it.
+    return [{errorId: statement.bindingNode?.type?.declarationId, kind: "raise", location: statement.location, state: cloneState(state)}]
+  }
   if (statement.kind == "IfStatement") {
     const conditions = evaluateExpression(statement.condition, cloneState(state), fail, errorEffects)
     /** @type {LifetimeExit[]} */
@@ -142,10 +146,32 @@ function analyzeStatement(statement, state, fail, locals, errorEffects) {
   if (statement.kind == "TryStatement") {
     const bodyExits = analyzeBlock(statement.body, [{kind: "normal", state: cloneState(state)}], fail, errorEffects)
     /** @type {LifetimeExit[]} */
-    const result = bodyExits.filter((flow) => flow.kind != "raise" || flow.errorId != statement.catchType.declarationId)
+    let result = bodyExits
+
+    for (const handler of statement.handlers ?? []) {
+      const caughtId = handler.catchType?.declarationId
+      const caught = result.filter((flow) => flow.kind == "raise" && flow.errorId == caughtId)
+
+      if (caught.length == 0) continue
+      result = result.filter((flow) => flow.kind != "raise" || flow.errorId != caughtId)
+      for (const flow of caught) {
+        result.push(...analyzeBlock(handler.catchBody, [{kind: "normal", state: cloneState(flow.state)}], fail, errorEffects))
+      }
+    }
+    if (statement.finallyBody) {
+      /** @type {LifetimeExit[]} */
+      const afterFinally = []
+
+      for (const flow of result) {
+        const finallyExits = analyzeBlock(statement.finallyBody, [{kind: "normal", state: cloneState(flow.state)}], fail, errorEffects)
 
-    for (const caught of bodyExits.filter((flow) => flow.kind == "raise" && flow.errorId == statement.catchType.declarationId)) {
-      result.push(...analyzeBlock(statement.catchBody, [{kind: "normal", state: cloneState(caught.state)}], fail, errorEffects))
+        for (const finallyExit of finallyExits) {
+          afterFinally.push(finallyExit.kind == "normal"
+            ? {...flow, location: statement.location}
+            : {...finallyExit, location: statement.location})
+        }
+      }
+      result = afterFinally
     }
     return mergeEquivalentNormals(result, statement.location, fail)
   }