semantifold 0.3.0 → 0.4.0

package/src/frontends/ruby.js

@@ -2,32 +2,65 @@
 
 import {
   AndNode,
+  ArrayNode,
+  AssocNode,
+  BlockNode,
+  BlockParametersNode,
+  BeginNode,
+  BreakNode,
   CallNode,
+  ClassNode,
+  ConstantPathNode,
+  ConstantReadNode,
   DefNode,
   ElseNode,
   FalseNode,
+  HashNode,
   IfNode,
   IntegerNode,
+  InstanceVariableWriteNode,
+  InstanceVariableReadNode,
   InterpolatedStringNode,
   LocalVariableReadNode,
+  LocalVariableTargetNode,
   LocalVariableWriteNode,
+  ModuleNode,
+  NextNode,
+  NilNode,
   OrNode,
   ParenthesesNode,
   ProgramNode,
   RequiredParameterNode,
+  RedoNode,
+  RescueNode,
   ReturnNode,
+  RetryNode,
+  SelfNode,
   StatementsNode,
   StringNode,
+  SymbolNode,
   TrueNode,
+  UnlessNode,
+  WhileNode,
   loadPrism
 } from "@ruby/prism"
 import {missingType, SemantifoldDiagnostic, unsupportedSyntax} from "../diagnostic.js"
+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 {hasOnlyUnicodeScalars} from "../semantic/scalars.js"
-import {requireSourceScalarType} from "./scalars.js"
+import {isTask034ResourceProbe} from "../semantic/capabilities.js"
+import {hasExactEffectSupport} from "../backends/effects.js"
+import {requireSourceReturnType} from "./scalars.js"
+import {capabilityFunctionSignatures, documentedValueType, instantiatedRecordFieldType, iterationBindingType, iterationOperandType, knownCallReturnType, orderedMapTypeFromMap, preservesGenericOptionalEvidence, recordType, referenceType, sameValueType} from "./types.js"
 const parsePrism = await loadPrism()
+const referenceMethodHooks = new Set([
+  "__send__", "extend", "fetch", "instance_eval", "instance_exec", "method", "method_missing", "public_send",
+  "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 */
 const rubyBinaryOperations = new Map([
   ["+", "Add"],
   ["-", "Subtract"],
@@ -86,17 +119,71 @@ function slicePrismSource(source, startOffset, endOffset) {
  * @param {import("@ruby/prism").Node} node - Prism node.
  * @param {string} filename - Source filename.
  * @param {string} source - Complete source.
+ * @param {RubyConversionContext} context - Typed lexical conversion context.
+ * @param {import("../semantic/types.js").SemanticValueType} [expectedType] - Explicit contextual value type.
+ * @param {boolean} [preserveOptional] - Whether an optional identifier remains wrapped.
  * @returns {import("../semantic/types.js").Expression} Semantic expression.
  */
-function convertExpression(node, filename, source) {
+function convertExpression(node, filename, source, context, expectedType, preserveOptional = false) {
   const location = nodeLocation(node, filename, source)
 
+  if (expectedType?.kind == "OptionalType") {
+    if (node instanceof NilNode) {
+      return withParserRanges({kind: /** @type {const} */ ("OptionalNone"), location}, {absence: location})
+    }
+    if (knownExpressionType(node, context)?.kind == "OptionalType") {
+      return convertExpression(node, filename, source, context, undefined, true)
+    }
+    return withParserRanges({
+      kind: /** @type {const} */ ("OptionalSome"),
+      location,
+      value: convertExpression(node, filename, source, context, expectedType.valueType)
+    }, {some: location})
+  }
+
+  if (node instanceof NilNode) return unsupportedSyntax("ruby", "nil outside an explicit optional context", location)
+
+  if (node instanceof CallNode && node.block) {
+    return unsupportedSyntax("ruby", "call block", nodeLocation(node.block, filename, source))
+  }
+
+  if (node instanceof CallNode && node.callOperatorLoc && slicePrismSource(
+    source,
+    node.callOperatorLoc.startOffset,
+    node.callOperatorLoc.startOffset + node.callOperatorLoc.length
+  ) == "&.") {
+    return unsupportedSyntax("ruby", node.constructor.name, location)
+  }
+
   if (node instanceof ParenthesesNode && node.body instanceof StatementsNode && node.body.body.length == 1) {
-    return convertExpression(node.body.body[0], filename, source)
+    return convertExpression(node.body.body[0], filename, source, context, expectedType, preserveOptional)
   }
 
   if (node instanceof LocalVariableReadNode) {
-    return withParserRanges({kind: /** @type {const} */ ("IdentifierExpression"), location, name: node.name}, {name: location})
+    const identifier = withParserRanges({kind: /** @type {const} */ ("IdentifierExpression"), location, name: node.name}, {name: location})
+
+    if (!preserveOptional && context.bindings.get(node.name)?.kind == "OptionalType") {
+      return withParserRanges({kind: /** @type {const} */ ("OptionalUnwrap"), location, operand: identifier}, {unwrap: location})
+    }
+
+    return identifier
+  }
+
+  if (node instanceof SelfNode) {
+    if (!context.currentClass) return unsupportedSyntax("ruby", "self outside a reference class", location)
+    return withParserRanges({classId: /** @type {string} */ (context.currentClass.id), kind: /** @type {const} */ ("ReceiverExpression"),
+      location}, {receiver: location})
+  }
+
+  if (node instanceof InstanceVariableReadNode) {
+    const field = context.currentClass?.fields.find((candidate) => `@${candidate.name}` == node.name)
+
+    if (!field || !context.currentClass) return unsupportedSyntax("ruby", "private instance field outside its declaring class", location)
+    const receiver = withParserRanges({classId: /** @type {string} */ (context.currentClass.id),
+      kind: /** @type {const} */ ("ReceiverExpression"), location}, {receiver: location})
+
+    return withParserRanges({field: /** @type {string} */ (field.id), kind: /** @type {const} */ ("PrivateFieldRead"),
+      location, receiver}, {member: location})
   }
 
   if (node instanceof IntegerNode) {
@@ -122,6 +209,113 @@ function convertExpression(node, filename, source) {
 
   if (node instanceof InterpolatedStringNode) return unsupportedSyntax("ruby", "interpolated string", location)
 
+  if (node instanceof OrNode && node.left instanceof LocalVariableReadNode &&
+    context.bindings.get(node.left.name)?.kind == "OptionalType") {
+    return unsupportedSyntax("ruby", "optional default with ||", prismLocation(node.operatorLoc, filename, source))
+  }
+
+  if (exactNilTest(node, source)) {
+    const call = /** @type {CallNode} */ (node)
+    const receiver = /** @type {LocalVariableReadNode} */ (call.receiver)
+    const operand = /** @type {import("../semantic/types.js").IdentifierExpression} */ (
+      convertExpression(receiver, filename, source, context, undefined, true)
+    )
+    const present = withParserRanges({kind: /** @type {const} */ ("OptionalIsPresent"), location, operand}, {
+      operator: prismLocation(call.messageLoc ?? call.location, filename, source)
+    })
+    const semantic = withAdaptedOperation(withParserRanges({
+      kind: "UnaryExpression",
+      location,
+      operand: present
+    }, {operator: prismLocation(call.messageLoc ?? call.location, filename, source)}), "Not")
+
+    return /** @type {import("../semantic/types.js").Expression} */ (/** @type {unknown} */ (semantic))
+  }
+
+  if (node instanceof ArrayNode) {
+    if (!node.openingLoc || !node.closingLoc) return unsupportedSyntax("ruby", "special array literal", location)
+    if (node.isContainsSplat()) {
+      const splat = node.elements.find((element) => element.constructor.name == "SplatNode")
+
+      return unsupportedSyntax("ruby", "array splat", splat ? nodeLocation(splat, filename, source) : location)
+    }
+
+    const elementType = expectedType?.kind == "ListType" ? expectedType.elementType : undefined
+
+    return withParserRanges({
+      elements: node.elements.map((element) => convertExpression(element, filename, source, context, elementType)),
+      kind: /** @type {const} */ ("ListLiteral"),
+      location
+    }, {
+      close: prismLocation(node.closingLoc, filename, source),
+      open: prismLocation(node.openingLoc, filename, source)
+    })
+  }
+
+  if (node instanceof HashNode) {
+    const valueType = expectedType?.kind == "MapType" || expectedType?.kind == "OrderedMapType"
+      ? expectedType.valueType : undefined
+    const entries = node.elements.map((element) => {
+      if (!(element instanceof AssocNode) || !element.operatorLoc ||
+        slicePrismSource(source, element.operatorLoc.startOffset, element.operatorLoc.startOffset + element.operatorLoc.length) != "=>") {
+        return unsupportedSyntax("ruby", "hash entry", nodeLocation(element, filename, source))
+      }
+      if (!(element.key instanceof StringNode)) {
+        return unsupportedSyntax("ruby", "map key other than a string literal", nodeLocation(element.key, filename, source))
+      }
+      const key = convertExpression(element.key, filename, source, context)
+
+      return withParserRanges({
+        key: /** @type {import("../semantic/types.js").StringLiteral} */ (key),
+        kind: /** @type {const} */ ("MapEntry"),
+        location: nodeLocation(element, filename, source),
+        value: convertExpression(element.value, filename, source, context, valueType)
+      }, {operator: prismLocation(element.operatorLoc, filename, source)})
+    })
+
+    return withParserRanges({
+      entries,
+      kind: expectedType?.kind == "OrderedMapType"
+        ? /** @type {const} */ ("OrderedMapLiteral")
+        : /** @type {const} */ ("MapLiteral"),
+      location
+    }, {
+      close: prismLocation(node.closingLoc, filename, source),
+      open: prismLocation(node.openingLoc, filename, source)
+    })
+  }
+
+  if (node instanceof CallNode && (node.receiver instanceof ConstantReadNode || node.receiver instanceof ConstantPathNode) && node.name == "new" &&
+    node.callOperatorLoc && !node.block) {
+    const recordName = constantPathName(node.receiver)
+    const declaration = context.recordNames.get(recordName)
+
+    if (!declaration) return unsupportedSyntax("ruby", "construction of a non-record class", nodeLocation(node.receiver, filename, source))
+    if (declaration.kind == "ClassDeclaration") {
+      return withParserRanges({arguments: (node.arguments_?.arguments_ ?? []).map((argument, index) =>
+        convertExpression(argument, filename, source, context, declaration.constructor.parameters[index]?.type)),
+      kind: /** @type {const} */ ("ReferenceConstruction"), location,
+      reference: referenceType(/** @type {string} */ (declaration.id), nodeLocation(node.receiver, filename, source))},
+      {class: nodeLocation(node.receiver, filename, source)})
+    }
+    if (declaration.kind == "EffectResourceDeclaration") {
+      return unsupportedSyntax("ruby", "owned resource construction", nodeLocation(node.receiver, filename, source))
+    }
+    const typeArguments = expectedType?.kind == "RecordType" && expectedType.declarationId == declaration.id
+      ? expectedType.arguments
+      : undefined
+
+    return withParserRanges({
+      arguments: (node.arguments_?.arguments_ ?? []).map((argument, index) =>
+        convertExpression(argument, filename, source, context,
+          instantiatedRecordFieldType(declaration, typeArguments, index))),
+      kind: /** @type {const} */ ("RecordConstruction"),
+      location,
+      record: recordType(/** @type {string} */ (declaration.id), nodeLocation(node.receiver, filename, source),
+        typeArguments)
+    }, {record: nodeLocation(node.receiver, filename, source)})
+  }
+
   if (node instanceof CallNode && node.receiver && node.name == "!") {
     const operatorLocation = prismLocation(node.messageLoc ?? node.location, filename, source)
 
@@ -131,10 +325,15 @@ function convertExpression(node, filename, source) {
     }
     if (node.arguments_) return unsupportedSyntax("ruby", "boolean not argument list", operatorLocation)
 
+    const operand = convertExpression(node.receiver, filename, source, context)
+
+    if (operand.kind == "UnaryExpression" && operand.operand.kind == "OptionalIsPresent") {
+      return operand.operand
+    }
     const semantic = withAdaptedOperation(withParserRanges({
       kind: "UnaryExpression",
       location,
-      operand: convertExpression(node.receiver, filename, source)
+      operand
     }, {operator: operatorLocation}), "Not")
 
     return /** @type {import("../semantic/types.js").Expression} */ (/** @type {unknown} */ (semantic))
@@ -149,7 +348,7 @@ function convertExpression(node, filename, source) {
     const semantic = withAdaptedOperation(withParserRanges({
       kind: "UnaryExpression",
       location,
-      operand: convertExpression(node.receiver, filename, source)
+      operand: convertExpression(node.receiver, filename, source, context)
     }, {operator: operatorLocation}), "Negate")
 
     return /** @type {import("../semantic/types.js").Expression} */ (/** @type {unknown} */ (semantic))
@@ -165,9 +364,9 @@ function convertExpression(node, filename, source) {
 
     const semantic = withAdaptedOperation(withParserRanges({
       kind: "BinaryExpression",
-      left: convertExpression(node.left, filename, source),
+      left: convertExpression(node.left, filename, source, context),
       location,
-      right: convertExpression(node.right, filename, source)
+      right: convertExpression(node.right, filename, source, context)
     }, {operator: operatorLocation}), node instanceof AndNode ? "And" : "Or")
 
     return /** @type {import("../semantic/types.js").Expression} */ (/** @type {unknown} */ (semantic))
@@ -185,42 +384,244 @@ function convertExpression(node, filename, source) {
   if (node instanceof CallNode && node.receiver && rubyBinaryOperations.has(node.name) && node.arguments_?.arguments_.length == 1) {
     const semantic = withAdaptedOperation(withParserRanges({
       kind: "BinaryExpression",
-      left: convertExpression(node.receiver, filename, source),
+      left: convertExpression(node.receiver, filename, source, context),
       location,
-      right: convertExpression(node.arguments_.arguments_[0], filename, source)
+      right: convertExpression(node.arguments_.arguments_[0], filename, source, context)
     }, {operator: prismLocation(node.messageLoc ?? node.location, filename, source)}), /** @type {import("../semantic/operators.js").AdaptedOperation} */ (rubyBinaryOperations.get(node.name)))
 
     return /** @type {import("../semantic/types.js").Expression} */ (/** @type {unknown} */ (semantic))
   }
 
+  if (node instanceof CallNode && node.receiver && node.name == "[]" && node.arguments_?.arguments_.length == 1 &&
+    !node.callOperatorLoc && !node.block) {
+    return withParserRanges({
+      collection: convertExpression(node.receiver, filename, source, context),
+      index: convertExpression(node.arguments_.arguments_[0], filename, source, context),
+      kind: /** @type {const} */ ("ListIndexExpression"),
+      location,
+      totality: /** @type {const} */ ("proven")
+    }, {operator: prismLocation(node.openingLoc ?? node.messageLoc ?? node.location, filename, source)})
+  }
+  if (node instanceof CallNode && node.receiver && node.name == "fetch" && node.arguments_?.arguments_.length == 1 &&
+    node.callOperatorLoc && !node.block) {
+    return withParserRanges({
+      collection: convertExpression(node.receiver, filename, source, context),
+      key: convertExpression(node.arguments_.arguments_[0], filename, source, context),
+      kind: /** @type {const} */ ("MapLookupExpression"),
+      location,
+      totality: /** @type {const} */ ("fail-on-absence")
+    }, {operator: prismLocation(node.messageLoc ?? node.location, filename, source)})
+  }
+  if (node instanceof CallNode && node.receiver instanceof ConstantReadNode && node.callOperatorLoc && !node.block) {
+    const callee = `${node.receiver.name}.${node.name}`
+    const signature = context.functions.get(callee)
+
+    if (signature) {
+      return withParserRanges({
+        arguments: (node.arguments_?.arguments_ ?? []).map((argument, index) =>
+          convertExpression(argument, filename, source, context, signature.parameters[index]?.type,
+            preservesGenericOptionalEvidence(signature, index))),
+        callee,
+        kind: /** @type {const} */ ("CallExpression"),
+        location
+      }, {callee: prismLocation(node.messageLoc ?? node.location, filename, source)})
+    }
+  }
+  if (node instanceof CallNode && node.receiver && node.name == "size" && !node.arguments_ && node.callOperatorLoc && !node.block) {
+    const receiverType = knownValueExpressionType(node.receiver, context)
+
+    if (receiverType?.kind == "RecordType") {
+      return withParserRanges({
+        field: node.name,
+        kind: /** @type {const} */ ("MemberRead"),
+        location,
+        receiver: convertExpression(node.receiver, filename, source, context)
+      }, {member: prismLocation(node.messageLoc ?? node.location, filename, source)})
+    }
+    return withParserRanges({
+      collection: convertExpression(node.receiver, filename, source, context),
+      kind: /** @type {const} */ ("CollectionSizeExpression"),
+      location
+    }, {operator: prismLocation(node.messageLoc ?? node.location, filename, source)})
+  }
+  if (node instanceof CallNode && node.receiver instanceof LocalVariableReadNode && node.name == "message" &&
+    !node.arguments_ && node.callOperatorLoc && !node.block && context.bindings.get(node.receiver.name)?.kind == "ErrorType") {
+    const receiverLocation = nodeLocation(node.receiver, filename, source)
+
+    return withParserRanges({
+      kind: /** @type {const} */ ("ErrorMessageRead"),
+      location,
+      receiver: withParserRanges({kind: /** @type {const} */ ("IdentifierExpression"), location: receiverLocation, name: node.receiver.name}, {
+        name: receiverLocation
+      })
+    }, {member: prismLocation(node.messageLoc ?? node.location, filename, source)})
+  }
+  if (node instanceof CallNode && node.receiver && node.callOperatorLoc && !node.block &&
+    knownValueExpressionType(node.receiver, context)?.kind == "ReferenceType") {
+    const receiverType = /** @type {import("../semantic/types.js").ReferenceType} */ (knownValueExpressionType(node.receiver, context))
+    const method = context.classes.get(receiverType.declarationId)?.methods.find((candidate) => candidate.name == node.name)
+
+    return withParserRanges({arguments: (node.arguments_?.arguments_ ?? []).map((argument, index) =>
+      convertExpression(argument, filename, source, context, method?.parameters[index]?.type)),
+    kind: /** @type {const} */ ("MethodCallExpression"), location, method: method?.id ?? node.name,
+    receiver: convertExpression(node.receiver, filename, source, context)},
+    {member: prismLocation(node.messageLoc ?? node.location, filename, source)})
+  }
+  if (node instanceof CallNode && node.receiver && node.callOperatorLoc && !node.arguments_ && !node.block) {
+    if (["send", "public_send", "__send__", "instance_variable_get", "method"].includes(node.name)) {
+      return unsupportedSyntax("ruby", "dynamic or reflective member access", prismLocation(node.messageLoc ?? node.location, filename, source))
+    }
+    return withParserRanges({
+      field: node.name,
+      kind: /** @type {const} */ ("MemberRead"),
+      location,
+      receiver: convertExpression(node.receiver, filename, source, context)
+    }, {member: prismLocation(node.messageLoc ?? node.location, filename, source)})
+  }
+
   if (node instanceof CallNode && !node.receiver) {
+    if (["send", "public_send", "__send__"].includes(node.name)) {
+      return unsupportedSyntax("ruby", "dynamic call", prismLocation(node.messageLoc ?? node.location, filename, source))
+    }
+    const signature = context.functions.get(node.name)
+
     return withParserRanges({
-      arguments: (node.arguments_?.arguments_ ?? []).map((argument) => convertExpression(argument, filename, source)),
+      arguments: (node.arguments_?.arguments_ ?? []).map((argument, index) =>
+        convertExpression(argument, filename, source, context, signature?.parameters[index]?.type,
+          preservesGenericOptionalEvidence(signature, index))),
       callee: node.name,
       kind: "CallExpression",
       location
     }, {callee: prismLocation(node.messageLoc ?? node.location, filename, source)})
   }
+  if (node instanceof CallNode && node.receiver) {
+    const unsupportedLocation = !node.callOperatorLoc && node.messageLoc && node.arguments_?.arguments_.length == 1
+      ? prismLocation(node.messageLoc, filename, source)
+      : nodeLocation(node.receiver, filename, source)
+
+    return unsupportedSyntax("ruby", node.constructor.name, unsupportedLocation)
+  }
 
   return unsupportedSyntax("ruby", node.constructor.name, location)
 }
 
+/**
+ * Resolves only result types established by explicit signatures and bindings.
+ * @param {import("@ruby/prism").Node} node - Parser-owned expression.
+ * @param {RubyConversionContext} context - Typed lexical context.
+ * @returns {import("../semantic/types.js").SemanticFunctionReturnType | import("../semantic/types.js").ErrorType | undefined} Known result type.
+ */
+function knownExpressionType(node, context) {
+  if (node instanceof ParenthesesNode && node.body instanceof StatementsNode && node.body.body.length == 1) {
+    return knownExpressionType(node.body.body[0], context)
+  }
+  if (node instanceof LocalVariableReadNode) return context.bindings.get(node.name)
+  if (node instanceof CallNode && !node.receiver) {
+    const signature = context.functions.get(node.name)
+
+    if (signature) return knownCallReturnType(signature, (node.arguments_?.arguments_ ?? []).map((argument) =>
+      knownExpressionType(argument, context)))
+  }
+  if (node instanceof CallNode && node.receiver instanceof ConstantReadNode) {
+    const signature = context.functions.get(`${node.receiver.name}.${node.name}`)
+
+    if (signature) return knownCallReturnType(signature, (node.arguments_?.arguments_ ?? []).map((argument) =>
+      knownExpressionType(argument, context)))
+  }
+  if (node instanceof CallNode && node.receiver && node.name == "[]") {
+    const collectionType = knownValueExpressionType(node.receiver, context)
+
+    if (collectionType?.kind == "ListType") return collectionType.elementType
+  }
+  if (node instanceof CallNode && node.receiver && node.name == "fetch") {
+    const collectionType = knownValueExpressionType(node.receiver, context)
+
+    if (collectionType?.kind == "MapType" || collectionType?.kind == "OrderedMapType") return collectionType.valueType
+  }
+  if (node instanceof CallNode && (node.receiver instanceof ConstantReadNode || node.receiver instanceof ConstantPathNode) && node.name == "new") {
+    const declaration = context.recordNames.get(constantPathName(node.receiver))
+
+    if (declaration?.id) return declaration.kind == "ClassDeclaration"
+      ? {declarationId: declaration.id, kind: "ReferenceType"}
+      : {declarationId: declaration.id, kind: "RecordType"}
+  }
+  if (node instanceof SelfNode && context.currentClass?.id) return {declarationId: context.currentClass.id, kind: "ReferenceType"}
+  if (node instanceof InstanceVariableReadNode && context.currentClass) {
+    return context.currentClass.fields.find((field) => `@${field.name}` == node.name)?.type
+  }
+  if (node instanceof CallNode && node.receiver && node.callOperatorLoc) {
+    const receiver = knownValueExpressionType(node.receiver, context)
+
+    if (receiver?.kind == "ReferenceType") {
+      return context.classes.get(receiver.declarationId)?.methods.find((method) => method.name == node.name)?.returnType
+    }
+    if (node.arguments_) return undefined
+    if (receiver?.kind != "RecordType") return undefined
+    const declaration = context.records.get(receiver.declarationId)
+    const index = declaration?.fields.findIndex((field) => field.name == node.name) ?? -1
+
+    return declaration ? instantiatedRecordFieldType(declaration, receiver.arguments, index) : undefined
+  }
+
+  return undefined
+}
+
+/**
+ * Resolves the value type produced by the frontend's implicit optional-binding unwrap.
+ * Semantic validation separately proves that the unwrap occurs only on a present path.
+ * @param {import("@ruby/prism").Node} node - Parser-owned expression.
+ * @param {RubyConversionContext} context - Typed lexical context.
+ * @returns {import("../semantic/types.js").SemanticFunctionReturnType | import("../semantic/types.js").ErrorType | undefined} Converted value type.
+ */
+function knownValueExpressionType(node, context) {
+  if (node instanceof ParenthesesNode && node.body instanceof StatementsNode && node.body.body.length == 1) {
+    return knownValueExpressionType(node.body.body[0], context)
+  }
+  const type = knownExpressionType(node, context)
+
+  return node instanceof LocalVariableReadNode && type?.kind == "OptionalType" ? type.valueType : type
+}
+
+/**
+ * Recognizes only the parser-backed `identifier.nil?` spelling used by Task 007.
+ * @param {import("@ruby/prism").Node} node - Candidate Prism expression.
+ * @param {string} source - Complete source.
+ * @returns {boolean} Whether this is one exact nil test.
+ */
+function exactNilTest(node, source) {
+  if (!(node instanceof CallNode) || !(node.receiver instanceof LocalVariableReadNode) ||
+    node.name != "nil?" || !node.callOperatorLoc || node.arguments_ || node.block) return false
+
+  return slicePrismSource(
+    source,
+    node.callOperatorLoc.startOffset,
+    node.callOperatorLoc.startOffset + node.callOperatorLoc.length
+  ) == "."
+}
+
 /**
  * Converts one explicit Ruby return.
  * @param {import("@ruby/prism").Node} node - Prism node.
  * @param {string} filename - Source filename.
  * @param {string} source - Complete source.
+ * @param {RubyConversionContext} context - Typed lexical conversion context.
  * @returns {import("../semantic/types.js").ReturnStatement} Semantic return.
  */
-function convertReturn(node, filename, source) {
+function convertReturn(node, filename, source, context) {
   const location = nodeLocation(node, filename, source)
 
-  if (!(node instanceof ReturnNode) || node.arguments_?.arguments_.length != 1) {
+  if (!(node instanceof ReturnNode) || (node.arguments_?.arguments_.length ?? 0) > 1) {
     return unsupportedSyntax("ruby", node.constructor.name, location)
   }
 
   return {
-    expression: convertExpression(node.arguments_.arguments_[0], filename, source),
+    ...(node.arguments_?.arguments_[0] ? {expression: convertExpression(
+      node.arguments_.arguments_[0],
+      filename,
+      source,
+      context,
+      context.returnType?.kind == "TypeReference" && context.returnType.name == "void" ? undefined : context.returnType
+    )} : {}),
     kind: "ReturnStatement",
     location
   }
@@ -232,26 +633,61 @@ function convertReturn(node, filename, source) {
  * @param {{location: import("@ruby/prism").Location}} node - Comment owner.
  * @param {string} filename - Source filename.
  * @param {string} source - Complete source.
- * @returns {{parameters: Map<string, {location: import("../semantic/types.js").SourceLocation, sourceType: string}>, returnType: {location: import("../semantic/types.js").SourceLocation, sourceType: string} | undefined}} Declared types.
+ * @param {string} [ownerId] - Stable declaration identity.
+ * @returns {{parameters: Map<string, {location: import("../semantic/types.js").SourceLocation, sourceType: string}>, returnType: {location: import("../semantic/types.js").SourceLocation, sourceType: string} | undefined, typeParameters?: import("../semantic/types.js").TypeParameter[]}} Declared types.
  */
-function typeComments(comments, node, filename, source) {
+function typeComments(comments, node, filename, source, ownerId) {
   const preceding = associatedComments(comments, node, source)
   const parameterTypes = new Map()
   /** @type {{location: import("../semantic/types.js").SourceLocation, sourceType: string} | undefined} */
   let returnType
+  /** @type {import("../semantic/types.js").TypeParameter[]} */
+  const typeParameters = []
 
   for (const comment of preceding) {
     const words = commentTokens(comment, filename, source)
 
-    if (words[0]?.text == "@param" && words.length == 3) {
-      parameterTypes.set(words[1].text, {location: words[2].location, sourceType: words[2].text})
-    }
-    if (words[0]?.text == "@return" && words.length == 2) {
-      returnType = {location: words[1].location, sourceType: words[1].text}
+    if (words[0]?.text == "@param" && words.length >= 3) {
+      if (parameterTypes.has(words[1].text)) {
+        return unsupportedSyntax("ruby", "duplicate parameter annotation", words[1].location)
+      }
+      parameterTypes.set(words[1].text, joinedCommentToken(words, 2, source))
+    } else if (words[0]?.text == "@return" && words.length >= 2) {
+      if (returnType) return unsupportedSyntax("ruby", "duplicate return annotation", words[1].location)
+      returnType = joinedCommentToken(words, 1, source)
+    } else if (words[0]?.text == "@template" && words.length == 2 && ownerId &&
+      /^[A-Za-z_][A-Za-z0-9_]*$/u.test(words[1].text)) {
+      typeParameters.push(withParserRanges({
+        id: `${ownerId}:type:${typeParameters.length}`,
+        kind: /** @type {const} */ ("TypeParameter"),
+        location: words[1].location,
+        name: words[1].text
+      }, {name: words[1].location}))
+    } else if (words[0]?.text?.startsWith("@template")) {
+      return unsupportedSyntax("ruby", "bounded, defaulted, variant, or malformed type parameter", words[1]?.location ?? nodeLocation(node, filename, source))
+    } else if (words[0]?.text?.startsWith("@param") || words[0]?.text?.startsWith("@return")) {
+      return unsupportedSyntax("ruby", "malformed function type annotation", nodeLocation(node, filename, source))
     }
   }
 
-  return {parameters: parameterTypes, returnType}
+  return {parameters: parameterTypes, returnType, ...(typeParameters.length > 0 ? {typeParameters} : {})}
+}
+
+/**
+ * Rejoins a bounded metadata suffix while retaining its parser-owned range.
+ * @param {{location: import("../semantic/types.js").SourceLocation, text: string}[]} tokens - Comment tokens.
+ * @param {number} start - First suffix token.
+ * @param {string} source - Complete source.
+ * @returns {{location: import("../semantic/types.js").SourceLocation, sourceType: string}} Joined token.
+ */
+function joinedCommentToken(tokens, start, source) {
+  const first = tokens[start]
+  const last = tokens.at(-1)
+
+  if (!first || !last) throw new Error("Ruby metadata suffix unexpectedly disappeared.")
+  const location = locationFromOffsets(first.location.filename, source, first.location.start.offset, last.location.end.offset)
+
+  return {location, sourceType: source.slice(location.start.offset, location.end.offset)}
 }
 
 /**
@@ -322,9 +758,11 @@ function associatedComments(comments, node, source) {
  * @param {LocalVariableWriteNode} node - Local write.
  * @param {string} filename - Source filename.
  * @param {string} source - Complete source.
- * @returns {{immutable: boolean, type: import("../semantic/types.js").TypeReference} | undefined} Metadata when present.
+ * @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").TypeParameter>} [typeParameters] - Declaration-scoped parameters.
+ * @returns {{immutable: boolean, type: import("../semantic/types.js").SemanticValueType} | undefined} Metadata when present.
  */
-function localMetadata(comments, node, filename, source) {
+function localMetadata(comments, node, filename, source, recordNames, typeParameters = new Map()) {
   const associated = associatedComments(comments, node, source)
   const metadata = associated.map((comment) => commentTokens(comment, filename, source))
   const typeMetadata = metadata.filter(([token]) => token?.text == "@type")
@@ -337,15 +775,17 @@ function localMetadata(comments, node, filename, source) {
 
   const location = nodeLocation(node, filename, source)
 
-  if (typeMetadata.length != 1 || typeMetadata[0].length != 2 ||
+  if (typeMetadata.length != 1 || typeMetadata[0].length < 2 ||
     immutableMetadata.length > 1 || immutableMetadata.some((tokens) => tokens.length != 1) ||
     profileMetadata.length != typeMetadata.length + immutableMetadata.length) {
     return unsupportedSyntax("ruby", "malformed local type metadata", location)
   }
 
+  const declaredType = joinedCommentToken(typeMetadata[0], 1, source)
+
   return {
     immutable: immutableMetadata.length == 1,
-    type: convertType(typeMetadata[0][1].text, `Local '${node.name}'`, location, typeMetadata[0][1].location)
+    type: convertType(declaredType.sourceType, `Local '${node.name}'`, location, source, declaredType.location, recordNames, typeParameters)
   }
 }
 
@@ -353,78 +793,346 @@ function localMetadata(comments, node, filename, source) {
  * Converts one Ruby local declaration or assignment.
  * @param {import("@ruby/prism").Node} node - Prism node.
  * @param {import("@ruby/prism/src/deserialize.js").Comment[]} comments - Prism comments.
- * @param {Set<string>} visible - Names visible during adaptation.
+ * @param {RubyConversionContext} context - Typed lexical conversion context.
  * @param {string} filename - Source filename.
  * @param {string} source - Complete source.
  * @returns {import("../semantic/types.js").LocalStatement} Semantic local statement.
  */
-function convertLocalStatement(node, comments, visible, filename, source) {
+function convertLocalStatement(node, comments, context, filename, source) {
   const location = nodeLocation(node, filename, source)
 
   if (!(node instanceof LocalVariableWriteNode)) return unsupportedSyntax("ruby", node.constructor.name, location)
 
-  const metadata = localMetadata(comments, node, filename, source)
+  const metadata = localMetadata(comments, node, filename, source, context.recordNames, context.typeParameters)
 
   if (metadata) {
-    visible.add(node.name)
-    return withParserRanges({
-      initializer: convertExpression(node.value, filename, source),
-      kind: "LocalDeclaration",
+    let declaredType = metadata.type
+
+    if (metadata.immutable && declaredType.kind == "MapType" && context.orderedMapDeclarations?.has(node) &&
+      node.value instanceof HashNode) {
+      declaredType = orderedMapTypeFromMap(declaredType, location)
+    }
+    const semantic = withParserRanges({
+      initializer: convertExpression(node.value, filename, source, context, declaredType),
+      kind: /** @type {const} */ ("LocalDeclaration"),
       location,
       mutable: !metadata.immutable,
       name: node.name,
-      type: metadata.type
+      type: declaredType
     }, {name: prismLocation(node.nameLoc, filename, source), operator: prismLocation(node.operatorLoc, filename, source)})
+
+    context.bindings.set(node.name, declaredType)
+    return semantic
   }
 
-  if (!visible.has(node.name)) return missingType("ruby", `Local '${node.name}'`, location)
+  if (!context.bindings.has(node.name)) {
+    if (node.value instanceof LocalVariableReadNode && context.bindings.get(node.value.name)?.kind == "OrderedMapType") {
+      return unsupportedSyntax("ruby", "ordered map alias escape", location)
+    }
+    return missingType("ruby", `Local '${node.name}'`, location)
+  }
 
   const targetLocation = prismLocation(node.nameLoc, filename, source)
   const target = withParserRanges({kind: /** @type {const} */ ("IdentifierExpression"), location: targetLocation, name: node.name}, {
     name: targetLocation
   })
 
-  return withParserRanges({
-    expression: convertExpression(node.value, filename, source),
-    kind: "AssignmentStatement",
+  const bindingType = context.bindings.get(node.name)
+  const semantic = withParserRanges({
+    expression: convertExpression(node.value, filename, source, context,
+      bindingType?.kind == "ErrorType" ? undefined : bindingType),
+    kind: /** @type {const} */ ("AssignmentStatement"),
     location,
     target
   }, {operator: prismLocation(node.operatorLoc, filename, source)})
+
+  return semantic
 }
 
 /**
  * Converts one exhaustive Prism statement.
  * @param {import("@ruby/prism").Node} node - Prism statement.
  * @param {import("@ruby/prism/src/deserialize.js").Comment[]} comments - Prism comments.
- * @param {Set<string>} visible - Names visible during adaptation.
+ * @param {RubyConversionContext} context - Typed lexical conversion context.
  * @param {string} filename - Source filename.
  * @param {string} source - Complete source.
  * @returns {import("../semantic/types.js").Statement} Semantic statement.
  */
-function convertStatement(node, comments, visible, filename, source) {
-  if (node instanceof ReturnNode) return convertReturn(node, filename, source)
-  if (node instanceof IfNode) return convertIf(node, comments, visible, filename, source)
-  if (node instanceof LocalVariableWriteNode) return convertLocalStatement(node, comments, visible, filename, source)
-  if (node instanceof CallNode) return convertPrint(node, filename, source)
+function convertStatement(node, comments, context, filename, source) {
+  if (node instanceof ReturnNode) {
+    if ((context.loopDepth ?? 0) > 0) return unsupportedSyntax("ruby", "nonlocal return from each block", nodeLocation(node, filename, source))
+    return convertReturn(node, filename, source, context)
+  }
+  if (node instanceof IfNode || node instanceof UnlessNode) return convertIf(node, comments, context, filename, source)
+  if (node instanceof WhileNode) return convertWhile(node, comments, context, filename, source)
+  if (node instanceof BeginNode) return convertRubyTry(node, comments, context, filename, source)
+  if (node instanceof LocalVariableWriteNode) return convertLocalStatement(node, comments, context, filename, source)
+  if (node instanceof InstanceVariableWriteNode) {
+    const location = nodeLocation(node, filename, source)
+    const field = context.currentClass?.fields.find((candidate) => `@${candidate.name}` == node.name)
+
+    if (!field || !context.currentClass) return unsupportedSyntax("ruby", "private instance field outside its declaring class", location)
+    const receiver = withParserRanges({classId: /** @type {string} */ (context.currentClass.id),
+      kind: /** @type {const} */ ("ReceiverExpression"), location}, {receiver: location})
+
+    return withParserRanges({expression: convertExpression(node.value, filename, source, context, field.type),
+      field: /** @type {string} */ (field.id), kind: /** @type {const} */ ("PrivateFieldWriteStatement"), location, receiver},
+    {member: location})
+  }
+  if (node instanceof BreakNode || node instanceof NextNode) {
+    if (node.arguments_) return unsupportedSyntax("ruby", `${node instanceof BreakNode ? "break" : "next"} value`, nodeLocation(node.arguments_, filename, source))
+    const location = prismLocation(node.keywordLoc, filename, source)
+
+    return withParserRanges({
+      kind: /** @type {"BreakStatement" | "ContinueStatement"} */ (node instanceof BreakNode ? "BreakStatement" : "ContinueStatement"),
+      location
+    }, {keyword: location})
+  }
+  if (node instanceof CallNode) {
+    if (!node.receiver && node.name == "raise") return convertRubyRaise(node, context, filename, source)
+    if (node.block) return convertForEach(node, comments, context, filename, source)
+    if (!node.receiver && node.name == "puts" && !context.functions.has("puts")) return convertPrint(node, filename, source, context)
+
+    return {
+      expression: /** @type {import("../semantic/types.js").CallExpression} */ (convertExpression(node, filename, source, context)),
+      kind: "ExpressionStatement",
+      location: nodeLocation(node, filename, source)
+    }
+  }
 
   return unsupportedSyntax("ruby", node.constructor.name, nodeLocation(node, filename, source))
 }
 
+/**
+ * Converts exact `raise DeclaredError, message`.
+ * @param {CallNode} node - Prism raise call.
+ * @param {RubyConversionContext} context - Typed lexical context.
+ * @param {string} filename - Source filename.
+ * @param {string} source - Complete source.
+ * @returns {import("../semantic/types.js").RaiseStatement} Semantic raise.
+ */
+function convertRubyRaise(node, context, filename, source) {
+  const location = nodeLocation(node, filename, source)
+  const arguments_ = node.arguments_?.arguments_ ?? []
+  const errorNode = arguments_[0]
+
+  if (node.block || node.callOperatorLoc || arguments_.length != 2 ||
+    !(errorNode instanceof ConstantReadNode) && !(errorNode instanceof ConstantPathNode) ||
+    !context.errorNames.has(constantPathName(errorNode))) {
+    return unsupportedSyntax("ruby", "raise other than exact declared error and message", location)
+  }
+  const declaration = /** @type {import("../semantic/types.js").ErrorDeclaration} */ (context.errorNames.get(constantPathName(errorNode)))
+  const typeLocation = nodeLocation(errorNode, filename, source)
+
+  return withParserRanges({
+    error: withParserRanges({
+      error: withParserRanges({declarationId: /** @type {string} */ (declaration.id), kind: /** @type {const} */ ("ErrorType")}, {type: typeLocation}),
+      kind: /** @type {const} */ ("ErrorConstruction"),
+      location,
+      message: convertExpression(arguments_[1], filename, source, context)
+    }, {type: typeLocation}),
+    kind: /** @type {const} */ ("RaiseStatement"),
+    location
+  }, {keyword: prismLocation(node.messageLoc ?? node.location, filename, source)})
+}
+
+/**
+ * Converts one exact typed rescue with no else/ensure.
+ * @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.
+ */
+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)
+  }
+  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)}
+
+  catchContext.bindings.set(handler.reference.name, catchType)
+  return withParserRanges({
+    body: convertBlock(node.statements, comments, bodyContext, filename, source, location),
+    catchBinding: 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,
+    kind: /** @type {const} */ ("TryStatement"),
+    location
+  }, {catch: nodeLocation(handler, filename, source), try: location})
+}
+
+/**
+ * Converts exact resolved-list `.each do |value| ... end` syntax.
+ * @param {CallNode} node - Prism call with a block.
+ * @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").ForEachStatement | import("../semantic/types.js").ForEachMapStatement} Semantic loop.
+ */
+function convertForEach(node, comments, context, filename, source) {
+  const location = nodeLocation(node, filename, source)
+  const block = node.block
+
+  if (!(block instanceof BlockNode)) return unsupportedSyntax("ruby", "call block", block ? nodeLocation(block, filename, source) : location)
+  if (!node.receiver || node.name != "each" || node.arguments_ || !node.callOperatorLoc || !node.messageLoc) {
+    return unsupportedSyntax("ruby", "arbitrary call block", nodeLocation(block, filename, source))
+  }
+  if (slicePrismSource(source, block.openingLoc.startOffset, block.openingLoc.startOffset + block.openingLoc.length) != "do") {
+    return unsupportedSyntax("ruby", "non-do each block", prismLocation(block.openingLoc, filename, source))
+  }
+  const excluded = findRubyDescendant(block.body, (candidate) =>
+    candidate instanceof RedoNode || candidate instanceof RetryNode || candidate instanceof ReturnNode)
+
+  if (excluded) {
+    const detail = excluded instanceof ReturnNode ? "nonlocal return from each block" :
+      excluded instanceof RedoNode ? "redo in each block" : "retry in each block"
+
+    return unsupportedSyntax("ruby", detail, nodeLocation(excluded, filename, source))
+  }
+  if (!(block.parameters instanceof BlockParametersNode) || block.parameters.locals.length > 0 ||
+    !block.parameters.parameters) {
+    return unsupportedSyntax("ruby", "each block parameters", block.parameters
+      ? nodeLocation(block.parameters, filename, source)
+      : nodeLocation(block, filename, source))
+  }
+  const parameters = block.parameters.parameters
+  const supportedRequireds = parameters.requireds.length == 1 || parameters.requireds.length == 2
+  const unsupportedParameter = !supportedRequireds
+    ? parameters.requireds[2] ?? parameters.requireds[1] ?? parameters.requireds[0] ?? block.parameters
+    : parameters.requireds.every((parameter) => parameter instanceof RequiredParameterNode) &&
+        parameters.optionals.length == 0 && !parameters.rest &&
+        parameters.posts.length == 0 && parameters.keywords.length == 0 && !parameters.keywordRest && !parameters.block
+      ? undefined
+      : parameters.optionals[0] ?? parameters.rest ?? parameters.posts[0] ?? parameters.keywords[0] ??
+        parameters.keywordRest ?? parameters.block ?? parameters.requireds[0]
+
+  if (unsupportedParameter) return unsupportedSyntax("ruby", "each block parameter arity or shape", nodeLocation(unsupportedParameter, filename, source))
+  const collectionType = iterationOperandType(knownExpressionType(node.receiver, context))
+
+  if (parameters.requireds.length == 2) {
+    if (collectionType?.kind == "MapType") {
+      return unsupportedSyntax("ruby", "unordered map iteration", nodeLocation(node.receiver, filename, source))
+    }
+    if (!collectionType || collectionType.kind != "OrderedMapType") {
+      return missingType("ruby", "Ordered map iteration collection", nodeLocation(node.receiver, filename, source))
+    }
+    const [keyParameter, valueParameter] = /** @type {[RequiredParameterNode, RequiredParameterNode]} */ (parameters.requireds)
+    const keyLocation = nodeLocation(keyParameter, filename, source)
+    const valueLocation = nodeLocation(valueParameter, filename, source)
+    const keyType = iterationBindingType(collectionType.keyType, keyLocation)
+    const valueType = iterationBindingType(collectionType.valueType, valueLocation)
+    const keyBinding = withParserRanges({
+      kind: /** @type {const} */ ("ValueBinding"), location: keyLocation, mutable: /** @type {const} */ (false),
+      name: keyParameter.name, type: keyType
+    }, {name: keyLocation})
+    const valueBinding = withParserRanges({
+      kind: /** @type {const} */ ("ValueBinding"), location: valueLocation, mutable: /** @type {const} */ (false),
+      name: valueParameter.name, type: valueType
+    }, {name: valueLocation})
+    const bodyContext = {...context, bindings: new Map(context.bindings), loopDepth: (context.loopDepth ?? 0) + 1}
+
+    bodyContext.bindings.set(keyParameter.name, keyType)
+    bodyContext.bindings.set(valueParameter.name, valueType)
+    return withParserRanges({
+      body: convertBlock(block.body instanceof StatementsNode ? block.body : null, comments, bodyContext, filename,
+        source, nodeLocation(block, filename, source)),
+      keyBinding,
+      kind: /** @type {const} */ ("ForEachMapStatement"),
+      location,
+      map: convertExpression(node.receiver, filename, source, context),
+      valueBinding
+    }, {operator: prismLocation(node.messageLoc, filename, source)})
+  }
+  const parameter = /** @type {RequiredParameterNode} */ (parameters.requireds[0])
+
+  if (collectionType?.kind == "MapType" || collectionType?.kind == "OrderedMapType") {
+    return unsupportedSyntax("ruby", "map iteration without key/value pair binding", nodeLocation(node.receiver, filename, source))
+  }
+  if (!collectionType || collectionType.kind != "ListType") {
+    return missingType("ruby", "Iteration collection", nodeLocation(node.receiver, filename, source))
+  }
+  const bindingLocation = nodeLocation(parameter, filename, source)
+  const inferredType = collectionType.elementType
+  const bindingType = iterationBindingType(inferredType, bindingLocation)
+  const valueBinding = withParserRanges({
+    kind: /** @type {const} */ ("ValueBinding"),
+    location: bindingLocation,
+    mutable: /** @type {const} */ (false),
+    name: parameter.name,
+    type: bindingType
+  }, {name: bindingLocation})
+  const bodyContext = {...context, bindings: new Map(context.bindings), loopDepth: (context.loopDepth ?? 0) + 1}
+
+  bodyContext.bindings.set(parameter.name, bindingType)
+  return withParserRanges({
+    body: convertBlock(
+      block.body instanceof StatementsNode ? block.body : null,
+      comments,
+      bodyContext,
+      filename,
+      source,
+      nodeLocation(block, filename, source)
+    ),
+    kind: /** @type {const} */ ("ForEachStatement"),
+    list: convertExpression(node.receiver, filename, source, context),
+    location,
+    valueBinding
+  }, {operator: prismLocation(node.messageLoc, filename, source)})
+}
+
+/**
+ * Finds the first parser descendant matching one excluded block construct.
+ * @param {import("@ruby/prism").Node | null} node - Parser subtree.
+ * @param {(node: import("@ruby/prism").Node) => boolean} predicate - Exclusion predicate.
+ * @returns {import("@ruby/prism").Node | undefined} First source-ordered match.
+ */
+function findRubyDescendant(node, predicate) {
+  if (!node) return undefined
+  if (predicate(node)) return node
+  for (const child of node.compactChildNodes()) {
+    const match = findRubyDescendant(child, predicate)
+
+    if (match) return match
+  }
+  return undefined
+}
+
 /**
  * Converts one ordered Prism statement list.
  * @param {StatementsNode | null} node - Prism statements, or an empty source block.
  * @param {import("@ruby/prism/src/deserialize.js").Comment[]} comments - Prism comments.
- * @param {Set<string>} visible - Names visible on block entry.
+ * @param {RubyConversionContext} context - Typed lexical conversion context.
  * @param {string} filename - Source filename.
  * @param {string} source - Complete source.
  * @param {import("../semantic/types.js").SourceLocation} fallbackLocation - Empty block location.
  * @returns {import("../semantic/types.js").Block} Semantic block.
  */
-function convertBlock(node, comments, visible, filename, source, fallbackLocation) {
+function convertBlock(node, comments, context, filename, source, fallbackLocation) {
   return {
     kind: "Block",
     location: node ? nodeLocation(node, filename, source) : fallbackLocation,
-    statements: node ? node.body.map((statement) => convertStatement(statement, comments, visible, filename, source)) : []
+    statements: node ? node.body.map((statement) => convertStatement(statement, comments, context, filename, source)) : []
   }
 }
 
@@ -448,36 +1156,59 @@ function isImmediateCommentGap(gap) {
 }
 
 /**
- * Requires an exact supported Ruby scalar spelling.
+ * Requires an exact supported Ruby value-type spelling.
  * @param {string | undefined} sourceType - Ruby type comment value.
  * @param {string} subject - Typed subject.
  * @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.
- * @returns {import("../semantic/types.js").TypeReference} Semantic type.
+ * @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").TypeParameter>} [typeParameters] - Declaration-scoped parameters.
+ * @returns {import("../semantic/types.js").SemanticValueType} Semantic type.
  */
-function convertType(sourceType, subject, location, typeLocation = location) {
-  return requireSourceScalarType("ruby", sourceType, subject, location, typeLocation)
+function convertType(sourceType, subject, location, source, typeLocation = location, recordNames = new Map(), typeParameters = new Map()) {
+  return documentedValueType({language: "ruby", location: typeLocation, ownerLocation: location, records: recordNames, source, sourceType, subject, typeParameters})
 }
 
 /**
- * Converts a Ruby definition.
+ * Converts a Ruby definition signature before body expressions.
  * @param {DefNode} node - Prism definition.
  * @param {import("@ruby/prism/src/deserialize.js").Comment[]} comments - Prism comments.
  * @param {string} filename - Source filename.
  * @param {string} source - Complete source.
- * @returns {import("../semantic/types.js").FunctionDeclaration} Semantic function.
+ * @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 {string} ownerId - Stable function identity.
+ * @param {boolean} [allowBuiltinOutput] - Whether compiler authority admits the exact output facade function.
+ * @returns {RubyFunctionSignature} Semantic signature.
  */
-function convertFunction(node, comments, filename, source) {
+function convertFunctionSignature(node, comments, filename, source, recordNames, ownerId, allowBuiltinOutput = false) {
   const location = nodeLocation(node, filename, source)
+  const parameterList = node.parameters
+
+  if (node.receiver) return unsupportedSyntax("ruby", "singleton method", nodeLocation(node.receiver, filename, source))
+  const nameLocation = prismLocation(node.nameLoc, filename, source)
 
-  if (!node.parameters || node.parameters.optionals.length > 0 || node.parameters.rest || node.parameters.posts.length > 0 ||
-    node.parameters.keywords.length > 0 || node.parameters.keywordRest || node.parameters.block ||
-    node.parameters.requireds.some((parameter) => !(parameter instanceof RequiredParameterNode))) {
-    return unsupportedSyntax("ruby", "parameters", location)
+  if (node.name == "puts" && !allowBuiltinOutput) {
+    return unsupportedSyntax("ruby", "function 'puts' captures built-in printing", nameLocation)
+  }
+  const unsupportedParameter = parameterList && [
+    parameterList.optionals[0], parameterList.rest, parameterList.posts[0], parameterList.keywords[0],
+    parameterList.keywordRest, parameterList.block,
+    parameterList.requireds.find((parameter) => !(parameter instanceof RequiredParameterNode))
+  ].find(Boolean)
+
+  if (unsupportedParameter) {
+    return unsupportedSyntax("ruby", "parameters", nodeLocation(unsupportedParameter, filename, source))
   }
 
-  const declaredTypes = typeComments(comments, node, filename, source)
-  const parameters = node.parameters.requireds.map((parameter) => {
+  const declaredTypes = typeComments(comments, node, filename, source, ownerId)
+  const typeParameterNames = new Map((declaredTypes.typeParameters ?? []).map((parameter) => [parameter.name, parameter]))
+  const requiredParameters = parameterList?.requireds ?? []
+  const extraAnnotation = [...declaredTypes.parameters.keys()].find((name) =>
+    !requiredParameters.some((parameter) => parameter instanceof RequiredParameterNode && parameter.name == name))
+
+  if (extraAnnotation) return unsupportedSyntax("ruby", `annotation for unknown parameter '${extraAnnotation}'`, location)
+  const parameters = requiredParameters.map((parameter) => {
     if (!(parameter instanceof RequiredParameterNode)) return unsupportedSyntax("ruby", parameter.constructor.name, location)
 
     const parameterLocation = nodeLocation(parameter, filename, source)
@@ -488,82 +1219,467 @@ function convertFunction(node, comments, filename, source) {
       kind: /** @type {const} */ ("Parameter"),
       location: parameterLocation,
       name: parameter.name,
-      type: convertType(declaredType?.sourceType, `Parameter '${parameter.name}'`, parameterLocation, declaredType?.location)
+      type: convertType(declaredType?.sourceType, `Parameter '${parameter.name}'`, parameterLocation, source,
+        declaredType?.location, recordNames, typeParameterNames)
     }, {name: parameterLocation})
   })
-  const visible = new Set(parameters.map((parameter) => parameter.name))
-  const body = convertBlock(node.body instanceof StatementsNode ? node.body : null, comments, visible, filename, source, location)
+  return {
+    location,
+    name: node.name,
+    nameLocation,
+    parameters,
+    returnType: declaredTypes.returnType?.sourceType == "[void]"
+      ? requireSourceReturnType("ruby", "[void]", `Function '${node.name}' return`, location, declaredTypes.returnType.location)
+      : convertType(declaredTypes.returnType?.sourceType, `Function '${node.name}' return`, location, source,
+        declaredTypes.returnType?.location, recordNames, typeParameterNames),
+    ...(declaredTypes.typeParameters ? {typeParameters: declaredTypes.typeParameters} : {})
+  }
+}
+
+/**
+ * Converts a Ruby definition body using all already-proved signatures.
+ * @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>} 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.
+ * @param {Map<string, import("../semantic/types.js").ErrorDeclaration>} errors - Error declarations by identity.
+ * @param {import("@ruby/prism/src/deserialize.js").Comment[]} comments - Prism comments.
+ * @param {string} filename - Source filename.
+ * @param {string} source - Complete source.
+ * @returns {import("../semantic/types.js").FunctionDeclaration} Semantic function.
+ */
+function convertFunction(node, signature, functions, recordNames, records, classes, errorNames, errors, comments, filename, source) {
+  const context = {
+    bindings: new Map(signature.parameters.map((parameter) => [parameter.name, parameter.type])),
+    classes,
+    errorNames,
+    errors,
+    functions,
+    orderedMapDeclarations: orderedMapDeclarationsForRuby(node.body instanceof StatementsNode ? node.body.body : []),
+    recordNames,
+    records,
+    returnType: signature.returnType,
+    typeParameters: new Map((signature.typeParameters ?? []).map((parameter) => [parameter.name, parameter]))
+  }
+  const body = convertBlock(
+    node.body instanceof StatementsNode ? node.body : null,
+    comments,
+    context,
+    filename,
+    source,
+    signature.location
+  )
 
   return withParserRanges({
     body,
     kind: "FunctionDeclaration",
-    location,
-    name: node.name,
-    parameters,
-    returnType: convertType(declaredTypes.returnType?.sourceType, `Function '${node.name}' return`, location, declaredTypes.returnType?.location)
-  }, {name: prismLocation(node.nameLoc, filename, source)})
+    location: signature.location,
+    name: signature.name,
+    parameters: signature.parameters,
+    returnType: signature.returnType,
+    ...(signature.typeParameters ? {typeParameters: signature.typeParameters} : {})
+  }, {name: signature.nameLocation})
+}
+
+/**
+ * Resolves parser-owned pair blocks to exact declarations inside one lexical owner.
+ * Ambiguous same-name declarations produce no evidence and fail during loop conversion.
+ * @param {import("@ruby/prism").Node[]} nodes - Function body or entry-point roots.
+ * @returns {Set<object>} Exact pair-iterated parser declarations.
+ */
+function orderedMapDeclarationsForRuby(nodes) {
+  /** @type {{declaration: LocalVariableWriteNode, name: string, offset: number}[]} */
+  const declarations = []
+  /** @type {{name: string, offset: number}[]} */
+  const receivers = []
+  /**
+   * Visits one parser candidate.
+   * @param {import("@ruby/prism").Node} node - Parser candidate.
+   */
+  const visit = (node) => {
+    if (node instanceof DefNode || node instanceof ClassNode) return
+    if (node instanceof LocalVariableWriteNode) declarations.push({
+      declaration: node,
+      name: node.name,
+      offset: node.location.startOffset
+    })
+    if (node instanceof CallNode && node.receiver instanceof LocalVariableReadNode && node.name == "each" &&
+      node.block instanceof BlockNode && node.block.parameters instanceof BlockParametersNode &&
+      node.block.parameters.parameters?.requireds.length == 2) receivers.push({
+      name: node.receiver.name,
+      offset: node.location.startOffset
+    })
+    for (const child of node.compactChildNodes()) visit(child)
+  }
+
+  for (const node of nodes) visit(node)
+  const selected = new Set()
+  for (const receiver of receivers) {
+    const matches = declarations.filter(({name, offset}) => name == receiver.name && offset < receiver.offset)
+
+    if (matches.length == 1) selected.add(matches[0].declaration)
+  }
+
+  return selected
+}
+
+/**
+ * Converts one exact empty StandardError subclass.
+ * @param {ClassNode} node - Prism class declaration.
+ * @param {import("../semantic/types.js").ErrorDeclaration} declaration - Predeclared semantic error.
+ * @param {string} filename - Source filename.
+ * @param {string} source - Complete source.
+ * @returns {import("../semantic/types.js").ErrorDeclaration} Semantic error declaration.
+ */
+function convertRubyError(node, declaration, filename, source) {
+  const location = nodeLocation(node, filename, source)
+
+  if (!(node.constantPath instanceof ConstantReadNode) || !(node.superclass instanceof ConstantReadNode) ||
+    node.superclass.name != "StandardError" || !node.inheritanceOperatorLoc || node.body) {
+    return unsupportedSyntax("ruby", "noncanonical typed error declaration", location)
+  }
+
+  return withParserRanges(declaration, {
+    name: nodeLocation(node.constantPath, filename, source),
+    type: nodeLocation(node.superclass, 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>} records - Records by identity.
+ * @param {Map<string, import("../semantic/types.js").ClassDeclaration>} classes - Classes by identity.
+ * @param {Map<string, RubyFunctionSignature>} functions - Top-level signatures.
+ * @param {Map<string, import("../semantic/types.js").ErrorDeclaration>} errorNames - Errors by name.
+ * @param {Map<string, import("../semantic/types.js").ErrorDeclaration>} errors - Errors by identity.
+ * @param {import("@ruby/prism/src/deserialize.js").Comment[]} comments - Prism comments.
+ * @param {string} filename - Source filename.
+ * @param {string} source - Complete source.
+ * @returns {import("../semantic/types.js").ClassDeclaration} Semantic class.
+ */
+function convertRubyReferenceClass(node, declaration, nominalNames, records, classes, functions, errorNames, errors,
+  comments, filename, source) {
+  const location = nodeLocation(node, filename, source)
+
+  if (!(node.constantPath instanceof ConstantReadNode) || node.superclass || node.inheritanceOperatorLoc ||
+    !(node.body instanceof StatementsNode)) {
+    return unsupportedSyntax("ruby", "reference class inheritance, qualified name, or empty body", location)
+  }
+  const members = node.body.body
+  const initializers = members.filter((member) => member instanceof DefNode && member.name == "initialize")
+  const methodNodes = /** @type {DefNode[]} */ (members.filter((member) => member instanceof DefNode && member.name != "initialize"))
+  const reservedMethod = methodNodes.find((method) => referenceMethodHooks.has(method.name))
+
+  if (initializers.length != 1 || members.some((member) => !(member instanceof DefNode)) || reservedMethod) {
+    return unsupportedSyntax("ruby", "reference class requires one initializer and ordinary methods", location)
+  }
+  const initializer = /** @type {DefNode} */ (initializers[0])
+  const parameters = initializer.parameters?.requireds ?? []
+  const invalidParameter = initializer.parameters && [initializer.parameters.optionals[0], initializer.parameters.rest,
+    initializer.parameters.posts[0], initializer.parameters.keywords[0], initializer.parameters.keywordRest,
+    initializer.parameters.block].find(Boolean)
+  const statements = initializer.body instanceof StatementsNode ? initializer.body.body : []
+  const annotations = typeComments(comments, initializer, filename, source)
+  const acquisition = statements.length == 1 && statements[0] instanceof InstanceVariableWriteNode &&
+    statements[0].name == "@resource" && statements[0].value instanceof CallNode && !statements[0].value.receiver &&
+    !statements[0].value.block && statements[0].value.name == "v1_connect" &&
+    statements[0].value.arguments_?.arguments_.length == 2 && parameters.length == 2 &&
+    parameters[0] instanceof RequiredParameterNode && parameters[0].name == "host" &&
+    parameters[1] instanceof RequiredParameterNode && parameters[1].name == "port" &&
+    statements[0].value.arguments_.arguments_[0] instanceof LocalVariableReadNode &&
+    statements[0].value.arguments_.arguments_[0].name == "host" &&
+    statements[0].value.arguments_.arguments_[1] instanceof LocalVariableReadNode &&
+    statements[0].value.arguments_.arguments_[1].name == "port" && declaration.name == "TCPSocket" &&
+    functions.get("v1_connect")?.returnType.kind == "OwnedResourceType"
+
+  if (initializer.receiver || invalidParameter || annotations.returnType || annotations.parameters.size != parameters.length ||
+    !acquisition && statements.length != parameters.length) {
+    return unsupportedSyntax("ruby", "noncanonical reference class initializer", nodeLocation(initializer, filename, source))
+  }
+  declaration.fields = acquisition ? [withParserRanges({
+    id: `${declaration.id}:field:0`,
+    kind: /** @type {const} */ ("PrivateField"),
+    location: nodeLocation(/** @type {InstanceVariableWriteNode} */ (statements[0]), filename, source),
+    name: "resource",
+    type: /** @type {import("../semantic/types.js").OwnedResourceType} */ (structuredClone(functions.get("v1_connect")?.returnType))
+  }, {name: nodeLocation(/** @type {InstanceVariableWriteNode} */ (statements[0]), filename, source)})] : parameters.map((candidate, index) => {
+    const parameter = /** @type {RequiredParameterNode} */ (candidate)
+    const assignment = statements[index]
+    const annotated = annotations.parameters.get(parameter.name)
+
+    if (!(parameter instanceof RequiredParameterNode) || !(assignment instanceof InstanceVariableWriteNode) ||
+      assignment.name != `@${parameter.name}` || !(assignment.value instanceof LocalVariableReadNode) ||
+      assignment.value.name != parameter.name || !annotated) {
+      return unsupportedSyntax("ruby", "private field not initialized exactly once in parameter order",
+        nodeLocation(assignment ?? initializer, filename, source))
+    }
+    return withParserRanges({id: `${declaration.id}:field:${index}`, kind: /** @type {const} */ ("PrivateField"),
+      location: nodeLocation(assignment, filename, source), name: parameter.name,
+      type: convertType(annotated.sourceType, `Private field '${parameter.name}'`, nodeLocation(parameter, filename, source),
+        source, annotated.location, nominalNames)}, {name: nodeLocation(assignment, filename, source)})
+  })
+  const constructorParameters = parameters.map((candidate, index) => {
+    const parameter = /** @type {RequiredParameterNode} */ (candidate)
+    const parameterLocation = nodeLocation(parameter, filename, source)
+    const annotated = annotations.parameters.get(parameter.name)
+
+    return withParserRanges({kind: /** @type {const} */ ("Parameter"), location: parameterLocation, name: parameter.name,
+      type: acquisition
+        ? convertType(annotated?.sourceType, `Constructor parameter '${parameter.name}'`, parameterLocation, source,
+          annotated?.location, nominalNames)
+        : declaration.fields[index].type}, {name: parameterLocation})
+  })
+  declaration.constructor = withParserRanges({body: /** @type {import("../semantic/types.js").Block} */ ({}),
+    id: `${declaration.id}:constructor`, kind: /** @type {const} */ ("ConstructorDeclaration"), location: nodeLocation(initializer, filename, source),
+    parameters: constructorParameters}, {constructor: prismLocation(initializer.nameLoc, filename, source)})
+  const methodSignatures = methodNodes.map((method, index) =>
+    convertFunctionSignature(method, comments, filename, source, nominalNames, `${declaration.id}:method:${index}`))
+  declaration.methods = methodSignatures.map((signature, index) => withParserRanges({
+    body: /** @type {import("../semantic/types.js").Block} */ ({}), id: `${declaration.id}:method:${index}`,
+    kind: /** @type {const} */ ("MethodDeclaration"), location: signature.location, name: signature.name,
+    parameters: signature.parameters, returnType: signature.returnType
+  }, {name: signature.nameLocation}))
+  const base = {bindings: new Map(), classes, currentClass: declaration, errorNames, errors, functions,
+    recordNames: nominalNames, records}
+
+  declaration.constructor.body = convertBlock(initializer.body instanceof StatementsNode ? initializer.body : null,
+    comments, {...base, bindings: new Map(constructorParameters.map((parameter) => [parameter.name, parameter.type])),
+      returnType: {kind: /** @type {const} */ ("TypeReference"), name: /** @type {const} */ ("void")}},
+    filename, source, declaration.constructor.location)
+  for (let index = 0; index < methodNodes.length; index += 1) {
+    const method = declaration.methods[index]
+    const methodBody = methodNodes[index].body
+
+    method.body = convertBlock(methodBody instanceof StatementsNode ? methodBody : null,
+      comments, {...base, bindings: new Map(method.parameters.map((parameter) => [parameter.name, parameter.type])),
+        returnType: method.returnType}, filename, source, method.location)
+  }
+
+  return withParserRanges(declaration, {name: nodeLocation(node.constantPath, filename, source)})
+}
+
+/**
+ * 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 {import("@ruby/prism/src/deserialize.js").Comment[]} comments - Parser-owned comments.
+ * @param {string} filename - Source filename.
+ * @param {string} source - Complete source.
+ * @returns {import("../semantic/types.js").RecordDeclaration} Semantic record.
+ */
+function convertRubyRecord(node, declaration, recordNames, comments, filename, source) {
+  const location = nodeLocation(node, filename, source)
+  const typeParameterNames = new Map((declaration.typeParameters ?? []).map((parameter) => [parameter.name, parameter]))
+
+  if (!(node.constantPath instanceof ConstantReadNode) || node.superclass || node.inheritanceOperatorLoc) {
+    return unsupportedSyntax("ruby", "record inheritance or qualified name", location)
+  }
+  const members = node.body instanceof StatementsNode ? node.body.body : []
+  const initializerIndex = members.findIndex((member) => member instanceof DefNode && member.name == "initialize")
+
+  if (initializerIndex < 0 || initializerIndex != members.length - 1 || members.slice(0, initializerIndex).some((member) =>
+    !(member instanceof CallNode) || member.receiver || member.name != "attr_reader" || member.block ||
+    member.arguments_?.arguments_.length != 1 || !(member.arguments_.arguments_[0] instanceof SymbolNode))) {
+    return unsupportedSyntax("ruby", "record class body outside typed readers and one initializer", nodeLocation(members.find((member, index) =>
+      index >= initializerIndex + 1 || !(member instanceof CallNode) || member.name != "attr_reader") ?? node, filename, source))
+  }
+  const readerNodes = /** @type {CallNode[]} */ (members.slice(0, initializerIndex))
+  declaration.fields = readerNodes.map((reader) => {
+    const symbol = /** @type {SymbolNode} */ (reader.arguments_?.arguments_[0])
+    const metadata = associatedComments(comments, reader, source).map((comment) => commentTokens(comment, filename, source))
+    const typeMetadata = metadata.filter(([token]) => token?.text == "@type")
+    const fieldLocation = nodeLocation(reader, filename, source)
+
+    if (typeMetadata.length != 1 || typeMetadata[0].length < 2 || metadata.some(([token]) => token?.text?.startsWith("@type") && token.text != "@type")) {
+      return unsupportedSyntax("ruby", "missing or malformed record reader type", fieldLocation)
+    }
+    const declaredType = joinedCommentToken(typeMetadata[0], 1, source)
+    const field = {
+      kind: /** @type {const} */ ("RecordField"),
+      location: fieldLocation,
+      name: symbol.unescaped.value,
+      type: convertType(declaredType.sourceType, `Record field '${symbol.unescaped.value}'`, fieldLocation, source,
+        declaredType.location, recordNames, typeParameterNames)
+    }
+
+    return withParserRanges(field, {name: symbol.valueLoc ? prismLocation(symbol.valueLoc, filename, source) : fieldLocation})
+  })
+  const initializer = /** @type {DefNode} */ (members[initializerIndex])
+  const parameterList = initializer.parameters
+  const parameters = parameterList?.requireds ?? []
+  const invalidParameter = parameterList && [parameterList.optionals[0], parameterList.rest, parameterList.posts[0],
+    parameterList.keywords[0], parameterList.keywordRest, parameterList.block].find(Boolean)
+  const initializerStatements = initializer.body instanceof StatementsNode ? initializer.body.body : []
+
+  if (initializer.receiver || invalidParameter || parameters.length != declaration.fields.length ||
+    parameters.some((parameter, index) => !(parameter instanceof RequiredParameterNode) || parameter.name != declaration.fields[index].name) ||
+    initializerStatements.length != declaration.fields.length + 1) {
+    return unsupportedSyntax("ruby", "noncanonical record initializer", nodeLocation(initializer, filename, source))
+  }
+  const annotations = typeComments(comments, initializer, filename, source)
+
+  if (annotations.returnType || annotations.parameters.size != declaration.fields.length) {
+    return unsupportedSyntax("ruby", "incomplete record initializer annotations", nodeLocation(initializer, filename, source))
+  }
+  for (let index = 0; index < declaration.fields.length; index += 1) {
+    const field = declaration.fields[index]
+    const parameter = /** @type {RequiredParameterNode} */ (parameters[index])
+    const assignment = initializerStatements[index]
+    const annotated = annotations.parameters.get(parameter.name)
+
+    if (!(assignment instanceof InstanceVariableWriteNode) || assignment.name != `@${field.name}` ||
+      !(assignment.value instanceof LocalVariableReadNode) || assignment.value.name != field.name || !annotated) {
+      return unsupportedSyntax("ruby", "record field not initialized exactly once", nodeLocation(assignment ?? initializer, filename, source))
+    }
+    const parameterType = convertType(annotated.sourceType, `Record initializer parameter '${parameter.name}'`,
+      nodeLocation(parameter, filename, source), source, annotated.location, recordNames, typeParameterNames)
+
+    if (!sameValueType(parameterType, field.type)) {
+      return unsupportedSyntax("ruby", "record reader/initializer type mismatch", annotated.location)
+    }
+  }
+  const freeze = initializerStatements.at(-1)
+
+  if (!isRubyRecordFreeze(freeze)) {
+    return unsupportedSyntax("ruby", "record initializer without final freeze", nodeLocation(freeze ?? initializer, filename, source))
+  }
+
+  return withParserRanges(declaration, {name: nodeLocation(node.constantPath, filename, source)})
+}
+
+/**
+ * Recognizes canonical source freezing or the generated root-owned Kernel implementation binding.
+ * @param {import("@ruby/prism").Node | undefined} node - Final initializer statement.
+ * @returns {boolean} Whether the statement owns the native record-freeze operation.
+ */
+function isRubyRecordFreeze(node) {
+  if (!(node instanceof CallNode) || node.block) return false
+  if (!node.receiver) return node.name == "freeze" && !node.arguments_
+  if (node.name != "bind_call" || !node.callOperatorLoc || node.arguments_?.arguments_.length != 1 ||
+    !(node.arguments_.arguments_[0] instanceof SelfNode) || !(node.receiver instanceof CallNode)) return false
+  const method = node.receiver
+
+  if (method.name != "instance_method" || !method.callOperatorLoc || method.block ||
+    method.arguments_?.arguments_.length != 1 || !(method.arguments_.arguments_[0] instanceof SymbolNode) ||
+    !(method.receiver instanceof ConstantPathNode)) return false
+
+  return method.receiver.parent == null && method.receiver.delimiterLoc != null && method.receiver.name == "Kernel" &&
+    method.arguments_.arguments_[0].unescaped.value == "freeze"
 }
 
 /**
  * Converts the existing Ruby if/else terminal with restricted branch prefixes.
- * @param {IfNode} node - Prism if node.
+ * @param {IfNode | UnlessNode} node - Prism conditional node.
  * @param {import("@ruby/prism/src/deserialize.js").Comment[]} comments - Prism comments.
- * @param {Set<string>} visible - Enclosing visible names.
+ * @param {RubyConversionContext} context - Typed lexical conversion context.
  * @param {string} filename - Source filename.
  * @param {string} source - Complete source.
  * @returns {import("../semantic/types.js").IfStatement} Semantic branch.
  */
-function convertIf(node, comments, visible, filename, source) {
+function convertIf(node, comments, context, filename, source) {
   const location = nodeLocation(node, filename, source)
 
-  if (!node.ifKeywordLoc || node.ifKeywordLoc.startOffset != node.location.startOffset) {
-    return unsupportedSyntax("ruby", "modifier conditional", node.ifKeywordLoc
-      ? prismLocation(node.ifKeywordLoc, filename, source)
+  const keywordLocation = node instanceof UnlessNode ? node.keywordLoc : node.ifKeywordLoc
+
+  if (!keywordLocation || keywordLocation.startOffset != node.location.startOffset) {
+    return unsupportedSyntax("ruby", "modifier conditional", keywordLocation
+      ? prismLocation(keywordLocation, filename, source)
       : location)
   }
 
-  const consequentVisible = new Set(visible)
-  let alternate
+  if (node.predicate instanceof LocalVariableReadNode &&
+    context.bindings.get(node.predicate.name)?.kind == "OptionalType") {
+    return unsupportedSyntax("ruby", "optional truthiness condition", nodeLocation(node.predicate, filename, source))
+  }
 
-  if (node.subsequent) {
-    const alternateVisible = new Set(visible)
+  if (node instanceof UnlessNode && !exactNilTest(node.predicate, source)) {
+    return unsupportedSyntax("ruby", "unless condition other than an exact nil? presence guard", nodeLocation(node.predicate, filename, source))
+  }
 
-    if (node.subsequent instanceof ElseNode) {
-      alternate = convertBlock(node.subsequent.statements, comments, alternateVisible, filename, source,
-        nodeLocation(node.subsequent, filename, source))
-    } else if (node.subsequent instanceof IfNode) {
+  const predicate = convertExpression(node.predicate, filename, source, context)
+  const condition = node instanceof UnlessNode && predicate.kind == "UnaryExpression" &&
+    predicate.operand.kind == "OptionalIsPresent"
+    ? predicate.operand
+    : predicate
+  if (node instanceof UnlessNode && condition.kind != "OptionalIsPresent") {
+    return unsupportedSyntax("ruby", "unless condition other than an exact nil? presence guard", nodeLocation(node.predicate, filename, source))
+  }
+  const consequentContext = {...context, bindings: new Map(context.bindings)}
+  const alternateContext = {...context, bindings: new Map(context.bindings)}
+  let alternate
+  const subsequent = node instanceof UnlessNode ? node.elseClause : node.subsequent
+
+  if (subsequent) {
+    if (subsequent instanceof ElseNode) {
+      alternate = convertBlock(subsequent.statements, comments, alternateContext, filename, source,
+        nodeLocation(subsequent, filename, source))
+    } else if (subsequent instanceof IfNode) {
       alternate = {
         kind: /** @type {const} */ ("Block"),
-        location: nodeLocation(node.subsequent, filename, source),
-        statements: [convertIf(node.subsequent, comments, alternateVisible, filename, source)]
+        location: nodeLocation(subsequent, filename, source),
+        statements: [convertIf(subsequent, comments, alternateContext, filename, source)]
       }
-    } else return unsupportedSyntax("ruby", node.subsequent.constructor.name, nodeLocation(node.subsequent, filename, source))
+    } else return unsupportedSyntax("ruby", subsequent.constructor.name, nodeLocation(subsequent, filename, source))
   }
 
   return {
     ...(alternate ? {alternate} : {}),
-    condition: convertExpression(node.predicate, filename, source),
-    consequent: convertBlock(node.statements, comments, consequentVisible, filename, source, location),
+    condition,
+    consequent: convertBlock(node.statements, comments, consequentContext, filename, source, location),
     kind: "IfStatement",
     location
   }
 }
 
+/**
+ * Converts one ordinary block-form Ruby pre-condition loop.
+ * @param {WhileNode} node - Prism while node.
+ * @param {import("@ruby/prism/src/deserialize.js").Comment[]} comments - Prism comments.
+ * @param {RubyConversionContext} context - Typed lexical conversion context.
+ * @param {string} filename - Source filename.
+ * @param {string} source - Complete source.
+ * @returns {import("../semantic/types.js").WhileStatement} Semantic loop.
+ */
+function convertWhile(node, comments, context, filename, source) {
+  const location = nodeLocation(node, filename, source)
+  const keywordLocation = prismLocation(node.keywordLoc, filename, source)
+
+  if (node.isBeginModifier() || !node.closingLoc || node.keywordLoc.startOffset != node.location.startOffset) {
+    return unsupportedSyntax("ruby", "modifier while", keywordLocation)
+  }
+  const bodyContext = {...context, bindings: new Map(context.bindings)}
+
+  return withParserRanges({
+    body: convertBlock(node.statements, comments, bodyContext, filename, source, location),
+    condition: convertExpression(node.predicate, filename, source, context, undefined, true),
+    kind: /** @type {const} */ ("WhileStatement"),
+    location
+  }, {keyword: keywordLocation})
+}
+
 /**
  * Converts the supported Ruby puts entry point.
  * @param {import("@ruby/prism").Node} node - Prism node.
  * @param {string} filename - Source filename.
  * @param {string} source - Complete source.
+ * @param {RubyConversionContext} context - Typed lexical conversion context.
  * @returns {import("../semantic/types.js").PrintStatement} Print statement.
  */
-function convertPrint(node, filename, source) {
+function convertPrint(node, filename, source, context) {
   const location = nodeLocation(node, filename, source)
 
   if (!(node instanceof CallNode) || node.receiver || node.name != "puts" || node.arguments_?.arguments_.length != 1) {
     return unsupportedSyntax("ruby", node.constructor.name, location)
   }
 
-  return {expression: convertExpression(node.arguments_.arguments_[0], filename, source), kind: "PrintStatement", location}
+  return {expression: convertExpression(node.arguments_.arguments_[0], filename, source, context), kind: "PrintStatement", location}
 }
 
 /**
@@ -571,9 +1687,11 @@ function convertPrint(node, filename, source) {
  * @param {object} input - Parser input.
  * @param {string} input.filename - Source filename.
  * @param {string} input.source - Source text.
+ * @param {readonly import("../semantic/types.js").EffectCapabilityDeclaration[]} [input.capabilities] - Compiler-authorized declarations.
+ * @param {{isEntry: boolean, classes?: Map<string, import("../semantic/types.js").ClassDeclaration>, functions: Map<string, import("../semantic/types.js").FunctionDeclaration>, records: Map<string, import("../semantic/types.js").RecordDeclaration>, errors?: Map<string, import("../semantic/types.js").ErrorDeclaration>}} [input.program] - Resolved program imports and entry role.
  * @returns {import("../semantic/types.js").SemanticModule} Semantic module.
  */
-export function parseRuby({filename, source}) {
+export function parseRuby({capabilities = [], filename, source, program}) {
   const result = parsePrism(source, {filepath: filename})
 
   if (result.errors.length > 0) {
@@ -585,13 +1703,105 @@ export function parseRuby({filename, source}) {
 
   if (!(result.value instanceof ProgramNode)) throw new Error("Prism returned a non-program root.")
 
-  const body = result.value.statements.body
-  const functions = body.filter((node) => node instanceof DefNode)
-    .map((node) => convertFunction(node, result.comments, filename, source))
-  const entryNodes = body.filter((node) => !(node instanceof DefNode))
+  let body = task034RubyBody(result.value.statements.body, result.comments, capabilities, filename, source)
+
+  if (program) {
+    inspectRubyModule({filename, source})
+    const moduleNode = /** @type {ModuleNode} */ (body.find((node) => node instanceof ModuleNode))
+
+    body = moduleNode.body instanceof StatementsNode ? moduleNode.body.body : []
+    const moduleFunctionNodes = body.filter(isModuleFunctionMarker)
+    const definitions = body.filter((node) => node instanceof DefNode)
+
+    if (definitions.length > 0 && (moduleFunctionNodes.length != 1 || body.indexOf(moduleFunctionNodes[0]) > body.indexOf(definitions[0]))) {
+      return unsupportedSyntax("ruby", "module functions outside one leading module_function profile",
+        nodeLocation(moduleFunctionNodes[1] ?? definitions[0], filename, source))
+    }
+    body = body.filter((node) => !isModuleFunctionMarker(node) && !rubyVisibilityMarker(node))
+  }
+  const classNodes = body.filter((node) => node instanceof ClassNode)
+  const errorNodes = classNodes.filter((node) => node.superclass instanceof ConstantReadNode && node.superclass.name == "StandardError")
+  const referenceClassNodes = classNodes.filter((node) => !errorNodes.includes(node) && node.body instanceof StatementsNode &&
+    node.body.body.length > 0 && node.body.body.every((member) => member instanceof DefNode))
+  const recordNodes = classNodes.filter((node) => !errorNodes.includes(node) && !referenceClassNodes.includes(node))
+  const errorDeclarations = errorNodes.map((node, index) => ({
+    id: `error:${index}`,
+    kind: /** @type {const} */ ("ErrorDeclaration"),
+    location: nodeLocation(node, filename, source),
+    name: node.name
+  }))
+  const recordDeclarations = recordNodes.map((node, index) => {
+    const id = `record:${index}`
+    const documented = typeComments(result.comments, node, filename, source, id)
+
+    if (documented.parameters.size || documented.returnType) {
+      return unsupportedSyntax("ruby", "function type annotation on record declaration", nodeLocation(node, filename, source))
+    }
+
+    return {
+      fields: [],
+      id,
+      kind: /** @type {const} */ ("RecordDeclaration"),
+      location: nodeLocation(node, filename, source),
+      name: node.name,
+      ...(documented.typeParameters ? {typeParameters: documented.typeParameters} : {})
+    }
+  })
+  const classDeclarations = referenceClassNodes.map((node, index) => ({
+    constructor: /** @type {import("../semantic/types.js").ConstructorDeclaration} */ ({}), fields: [], id: `class:${index}`,
+    kind: /** @type {const} */ ("ClassDeclaration"), location: nodeLocation(node, filename, source), methods: [], name: node.name
+  }))
+  const reopened = classDeclarations.find((declaration, index) =>
+    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>} */ (
+    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)
+  const errorNames = new Map(program?.errors ?? [])
+  for (const failure of capabilities.flatMap(({failures}) => failures)) {
+    errorNames.set(failure.name, /** @type {import("../semantic/types.js").ErrorDeclaration} */ (/** @type {unknown} */ (failure)))
+  }
+  for (const declaration of errorDeclarations) errorNames.set(declaration.name, declaration)
+  const errorsById = new Map([...errorNames.values()].map((declaration) => [/** @type {string} */ (declaration.id), declaration]))
+  const errors = errorNodes.map((node, index) => convertRubyError(node, errorDeclarations[index], filename, source))
+  for (const declaration of recordDeclarations) recordNames.set(declaration.name, declaration)
+  for (const declaration of classDeclarations) recordNames.set(declaration.name, declaration)
+  const recordsById = new Map(recordDeclarations.map((declaration) => [/** @type {string} */ (declaration.id), declaration]))
+  const classesById = new Map([
+    ...[...program?.classes?.values() ?? []].map((declaration) => /** @type {[string, import("../semantic/types.js").ClassDeclaration]} */ (
+      [/** @type {string} */ (declaration.id), declaration])),
+    ...classDeclarations.map((declaration) => /** @type {[string, import("../semantic/types.js").ClassDeclaration]} */ (
+      [/** @type {string} */ (declaration.id), declaration]))
+  ])
+  const functionNodes = body.filter((node) => node instanceof DefNode)
+  const allowsBuiltinOutput = capabilities.some(({operations}) => operations.some(({name}) => name == "v1_write_line"))
+  const signatures = functionNodes.map((node, index) =>
+    convertFunctionSignature(node, result.comments, filename, source, recordNames, `function:${index}`, allowsBuiltinOutput))
+  const functionSignatures = new Map([...capabilityFunctionSignatures(capabilities, moduleLocation(filename, source)),
+    ...(program?.functions ?? [])].map(([localName, declaration]) => [localName, {
+    location: declaration.location,
+    name: localName,
+    nameLocation: declaration.location,
+    parameters: declaration.parameters,
+    returnType: declaration.returnType,
+    ...(declaration.typeParameters ? {typeParameters: declaration.typeParameters} : {})
+  }]))
+  for (const signature of signatures) functionSignatures.set(signature.name, signature)
+  const records = recordNodes.map((node, index) =>
+    convertRubyRecord(node, recordDeclarations[index], recordNames, result.comments, filename, source))
+  const classes = referenceClassNodes.map((node, index) => convertRubyReferenceClass(node, classDeclarations[index],
+    recordNames, recordsById, classesById, functionSignatures, errorNames, errorsById, result.comments, filename, source))
+  const functions = functionNodes.map((node, index) =>
+    convertFunction(node, signatures[index], functionSignatures, recordNames, recordsById, classesById, errorNames, errorsById,
+      result.comments, filename, source))
+  const entryNodes = body.filter((node) => !(node instanceof DefNode) && !(node instanceof ClassNode))
   const location = moduleLocation(filename, source)
 
-  if (functions.length == 0) return unsupportedSyntax("ruby", "module without a function", location)
+  if (program && !program.isEntry && entryNodes.length > 0) {
+    return unsupportedSyntax("ruby", "top-level side effect outside the selected entry module", nodeLocation(entryNodes[0], filename, source))
+  }
   const firstEntry = entryNodes[0]
   const entryLocation = firstEntry ? locationFromOffsets(
     filename,
@@ -602,13 +1812,17 @@ export function parseRuby({filename, source}) {
       (entryNodes.at(-1)?.location.startOffset ?? 0) + (entryNodes.at(-1)?.location.length ?? 0)
     )
   ) : location
-  const entryVisible = new Set()
+  const entryContext = {bindings: new Map(), classes: classesById, errorNames, errors: errorsById, functions: functionSignatures,
+    orderedMapDeclarations: orderedMapDeclarationsForRuby(entryNodes), recordNames, records: recordsById}
   const entryBlock = {
     kind: /** @type {const} */ ("Block"),
     location: entryLocation,
-    statements: entryNodes.map((statement) => convertStatement(statement, result.comments, entryVisible, filename, source))
+    statements: entryNodes.map((statement) => convertStatement(statement, result.comments, entryContext, filename, source))
   }
 
+  if (!program && functions.length == 0 && capabilities.length == 0 && !blockReferencesProtectedEntry(entryBlock)) {
+    return unsupportedSyntax("ruby", "module without a function", location)
+  }
   return {
     entryPoint: {
       body: entryBlock,
@@ -617,6 +1831,318 @@ export function parseRuby({filename, source}) {
     },
     functions,
     kind: "Module",
-    location
+    location,
+    ...(classes.length > 0 ? {classes} : {}),
+    ...(errors.length > 0 ? {errors} : {}),
+    ...(records.length > 0 ? {records} : {})
+  }
+}
+
+/**
+ * Removes exact protected Ruby probe support before portable conversion.
+ * @param {import("@ruby/prism").Node[]} body - Parsed top-level nodes.
+ * @param {{location: {startOffset: number, length: number}}[]} comments - Parser comments.
+ * @param {readonly import("../semantic/types.js").EffectCapabilityDeclaration[]} capabilities - Authorized declarations.
+ * @param {string} filename - Source filename.
+ * @param {string} source - Complete source.
+ * @returns {import("@ruby/prism").Node[]} Portable nodes.
+ */
+function task034RubyBody(body, comments, capabilities, filename, source) {
+  if (!isTask034ResourceProbe(capabilities)) return body
+  const marker = comments.find((comment) =>
+    source.slice(comment.location.startOffset, comment.location.startOffset + comment.location.length) ==
+      "# semantifold-task034-support")
+
+  if (!marker) return body
+  if (!hasExactEffectSupport(source, "ruby")) {
+    return unsupportedSyntax("ruby", "malformed protected Task 034 support", nodeLocation(body[0], filename, source))
+  }
+  const expected = [
+    ["ClassNode", "ProbeOperationFailure"], ["ClassNode", "ProbeAcquireFailure"], ["ClassNode", "ProbeReadFailure"],
+    ["ClassNode", "ProbeCloseFailure"], ["ClassNode", "ProbeResourceClosed"], ["ClassNode", "ProbeResource"],
+    ["GlobalVariableWriteNode", "$__semantifold_task034_trace"], ["DefNode", "probeEffect"], ["DefNode", "probeAcquire"],
+    ["DefNode", "probeRead"], ["DefNode", "probeClose"], ["DefNode", "probeTrace"]
+  ]
+  const matches = expected.every(([kind, name], index) => body[index]?.constructor.name == kind && Reflect.get(body[index], "name") == name)
+  const end = comments.find((comment) =>
+    source.slice(comment.location.startOffset, comment.location.startOffset + comment.location.length) ==
+      "# semantifold-task034-support-end")
+
+  if (!matches || !end || end.location.startOffset < body[expected.length - 1].location.startOffset + body[expected.length - 1].location.length) {
+    return unsupportedSyntax("ruby", "malformed protected Task 034 support", nodeLocation(body[0], filename, source))
+  }
+  return body.slice(expected.length)
+}
+
+/**
+ * Reads the canonical parser-owned Ruby module and literal require-relative edges.
+ * @param {object} input - Parser input.
+ * @param {string} input.filename - Source filename.
+ * @param {string} input.source - Source text.
+ * @returns {{imports: {importedName: string, localName: string, location: import("../semantic/types.js").SourceLocation, namespace: true, pathLocation: import("../semantic/types.js").SourceLocation, specifier: string, stdlibCandidate?: true, typeOnly: false}[], exports: {exportedName: string, localName: string, location: import("../semantic/types.js").SourceLocation, typeOnly: false}[], nativeName: string, nativeReferences: {form: "constructor-call" | "receiver-call" | "unqualified-call", location: import("../semantic/types.js").SourceLocation, nativeModule: string, symbol: string}[]}} Parser-owned Ruby module header.
+ */
+export function inspectRubyModule({filename, source}) {
+  const result = parsePrism(source, {filepath: filename})
+
+  if (result.errors.length > 0) {
+    const error = result.errors[0]
+    const location = locationFromOffsets(filename, source, error.location.startOffset, error.location.startOffset + error.location.length)
+
+    throw new SemantifoldDiagnostic({code: "PARSE_ERROR", language: "ruby", location, message: error.message})
   }
+  if (!(result.value instanceof ProgramNode)) throw new Error("Prism returned a non-program root.")
+  const body = result.value.statements.body
+  const modules = body.filter((node) => node instanceof ModuleNode)
+  const dynamicRequire = body.find(isDynamicStdlibRequire)
+
+  if (dynamicRequire) {
+    throw new SemantifoldDiagnostic({
+      code: "STDLIB_FACADE_DYNAMIC_REFERENCE",
+      language: "ruby",
+      location: nodeLocation(dynamicRequire, filename, source),
+      message: "Dynamic require cannot prove a standard-library facade identity."
+    })
+  }
+  validateTask037NativeAttempts(body, filename, source)
+  const invalid = body.find((node) => !(node instanceof ModuleNode) && !isRequireRelative(node) && !isStdlibRequire(node))
+
+  if (modules.length != 1 || !(modules[0].constantPath instanceof ConstantReadNode) || invalid) {
+    return unsupportedSyntax("ruby", "one simple module with literal require_relative declarations",
+      nodeLocation(invalid ?? modules[1] ?? modules[0] ?? result.value, filename, source))
+  }
+  const imports = body.filter((node) => isRequireRelative(node) || isStdlibRequire(node)).map((node) => {
+    const call = /** @type {CallNode} */ (node)
+    const argument = /** @type {StringNode} */ (call.arguments_?.arguments_[0])
+    const stdlibCandidate = isStdlibRequire(call)
+
+    if (!argument.unescaped.validEncoding || argument.unescaped.encoding != "utf-8" || argument.isForcedBinaryEncoding()) {
+      return unsupportedSyntax("ruby", "non-UTF-8 require_relative path", nodeLocation(argument, filename, source))
+    }
+
+    return {
+      importedName: "*",
+      kind: /** @type {const} */ ("Import"),
+      localName: "",
+      location: nodeLocation(call, filename, source),
+      namespace: /** @type {const} */ (true),
+      pathLocation: nodeLocation(argument, filename, source),
+      specifier: argument.unescaped.value,
+      ...(stdlibCandidate ? {stdlibCandidate: /** @type {const} */ (true)} : {}),
+      typeOnly: /** @type {const} */ (false)
+    }
+  })
+  const moduleBody = modules[0].body instanceof StatementsNode ? modules[0].body.body : []
+  const visibility = new Map()
+
+  for (const node of moduleBody) {
+    if (!(node instanceof CallNode) || !["private_class_method", "private_constant"].includes(node.name)) continue
+    const marker = rubyVisibilityMarker(node)
+
+    if (!marker) return unsupportedSyntax("ruby", `malformed ${node.name}`, nodeLocation(node, filename, source))
+    if (visibility.has(marker.name)) return unsupportedSyntax("ruby", `duplicate visibility marker for '${marker.name}'`, nodeLocation(node, filename, source))
+    const declaration = moduleBody.find((candidate) => marker.kind == "function"
+      ? candidate instanceof DefNode && candidate.name == marker.name
+      : candidate instanceof ClassNode && candidate.name == marker.name)
+
+    if (!declaration || moduleBody.indexOf(declaration) > moduleBody.indexOf(node)) {
+      return unsupportedSyntax("ruby", `visibility marker without an earlier ${marker.kind}`, nodeLocation(node, filename, source))
+    }
+    visibility.set(marker.name, marker.kind)
+  }
+  const exports = moduleBody.flatMap((node) => {
+    if (node instanceof DefNode || node instanceof ClassNode) {
+      const kind = node instanceof DefNode ? "function" : node.body instanceof StatementsNode && node.body.body.length > 0 &&
+        node.body.body.every((member) => member instanceof DefNode) ? "class" : "record"
+
+      if (visibility.get(node.name) == kind) return []
+      return [{
+        exportedName: node.name,
+        localName: node.name,
+        location: nodeLocation(node instanceof ClassNode ? node.constantPath : node, filename, source),
+        symbolKind: /** @type {import("../semantic/types.js").SemanticDeclarationKind} */ (kind),
+        typeOnly: /** @type {const} */ (false)
+      }]
+    }
+    return []
+  })
+  const nativeReferences = rubyNativeReferences(modules[0], filename, source)
+
+  return {exports, imports, nativeName: modules[0].name, nativeReferences}
+}
+
+/**
+ * Rejects parser-proved attempts to use or mutate the bounded socket facade outside its exact surface.
+ * @param {import("@ruby/prism").Node[]} body - Prism program body.
+ * @param {string} filename - Source filename.
+ * @param {string} source - Complete source.
+ * @returns {void}
+ */
+function validateTask037NativeAttempts(body, filename, source) {
+  const active = body.some((node) => isStdlibRequire(node) && node instanceof CallNode &&
+    node.arguments_?.arguments_[0] instanceof StringNode && node.arguments_.arguments_[0].unescaped.value == "socket")
+  const reopened = body.find((node) => node instanceof ClassNode && node.name == "TCPSocket")
+
+  if (active && reopened) throw new SemantifoldDiagnostic({
+    code: "STDLIB_FACADE_REOPENED",
+    language: "ruby",
+    location: nodeLocation(reopened, filename, source),
+    message: "Caller source reopens the compiler-owned TCPSocket facade identity."
+  })
+  const modules = body.filter((node) => node instanceof ModuleNode)
+
+  /**
+   * Visits one parser node for bounded native attempts.
+   * @param {import("@ruby/prism").Node} node - Candidate Prism node.
+   */
+  function visit(node) {
+    if (node instanceof CallNode) {
+      const receiver = node.receiver
+      const tcpReceiver = receiver instanceof ConstantReadNode && receiver.name == "TCPSocket"
+
+      if (tcpReceiver) {
+        if (!active) throw new SemantifoldDiagnostic({
+          code: "STDLIB_FACADE_IDENTITY_UNPROVED",
+          language: "ruby",
+          location: nodeLocation(/** @type {ConstantReadNode} */ (receiver), filename, source),
+          message: "TCPSocket requires the exact parser-proved require \"socket\" identity."
+        })
+        if (node.name != "new" || node.block || node.arguments_?.arguments_.length != 2) {
+          throw new SemantifoldDiagnostic({
+            code: "STDLIB_FACADE_MEMBER_UNSUPPORTED",
+            language: "ruby",
+            location: nodeLocation(node, filename, source),
+            message: "TCPSocket supports only exact two-argument new without a block."
+          })
+        }
+      }
+      const kernelPuts = !node.receiver && node.name == "puts" ||
+        node.receiver instanceof ConstantReadNode && node.receiver.name == "Kernel" && node.name == "puts"
+
+      if (active && kernelPuts && (node.block || node.arguments_?.arguments_.length != 1)) {
+        throw new SemantifoldDiagnostic({
+          code: "STDLIB_FACADE_MEMBER_UNSUPPORTED",
+          language: "ruby",
+          location: nodeLocation(node, filename, source),
+          message: "The Task 037 Output facade supports exactly one string argument without a block."
+        })
+      }
+    }
+    for (const child of node.compactChildNodes()) visit(child)
+  }
+
+  for (const module of modules) visit(module)
+}
+
+/**
+ * Collects exact Task 037 native identities from Prism nodes in source order.
+ * @param {ModuleNode} module - Parsed application module.
+ * @param {string} filename - Source filename.
+ * @param {string} source - Complete source.
+ * @returns {{form: "constructor-call" | "receiver-call" | "unqualified-call", location: import("../semantic/types.js").SourceLocation, nativeModule: string, symbol: string}[]} Parser-proved native references.
+ */
+function rubyNativeReferences(module, filename, source) {
+  /** @type {{form: "constructor-call" | "receiver-call" | "unqualified-call", location: import("../semantic/types.js").SourceLocation, nativeModule: string, offset: number, symbol: string}[]} */
+  const references = []
+
+  /**
+   * Visits one parser node without interpreting source text.
+   * @param {import("@ruby/prism").Node} node - Parser node.
+   * @returns {void}
+   */
+  function visit(node) {
+    if (node instanceof CallNode && !node.block && node.arguments_?.arguments_.length == 1 &&
+      !node.receiver && node.name == "puts") {
+      references.push({form: "unqualified-call", location: nodeLocation(node, filename, source), nativeModule: "ruby:Kernel",
+        offset: node.location.startOffset, symbol: "puts"})
+    }
+    if (node instanceof CallNode && !node.block && node.arguments_?.arguments_.length == 1 && node.name == "puts" &&
+      node.callOperatorLoc && node.receiver instanceof ConstantReadNode && node.receiver.name == "Kernel") {
+      references.push({form: "receiver-call", location: nodeLocation(node, filename, source), nativeModule: "ruby:Kernel",
+        offset: node.location.startOffset, symbol: "puts"})
+    }
+    if (node instanceof CallNode && !node.block && node.arguments_?.arguments_.length == 2 && node.name == "new" &&
+      node.callOperatorLoc && node.receiver instanceof ConstantReadNode && node.receiver.name == "TCPSocket") {
+      references.push({form: "constructor-call", location: nodeLocation(node, filename, source), nativeModule: "socket",
+        offset: node.location.startOffset, symbol: "TCPSocket"})
+    }
+    for (const child of node.compactChildNodes()) visit(child)
+  }
+
+  visit(module)
+  return references.sort((left, right) => left.offset - right.offset).map(({offset: _offset, ...reference}) => reference)
+}
+
+/**
+ * Reports whether a Ruby node is one canonical literal relative load edge.
+ * @param {import("@ruby/prism").Node} node - Candidate call.
+ * @returns {boolean} Whether the node is a supported require-relative call.
+ */
+function isRequireRelative(node) {
+  return node instanceof CallNode && !node.receiver && !node.block && node.name == "require_relative" &&
+    node.arguments_?.arguments_.length == 1 && node.arguments_.arguments_[0] instanceof StringNode
+}
+
+/**
+ * Reports whether a Ruby node is one parser-proved literal facade require candidate.
+ * Other load-path requires retain the Task 010 unsupported profile.
+ * @param {import("@ruby/prism").Node} node - Candidate call.
+ * @returns {boolean} Whether the node is a literal Semantifold facade require.
+ */
+function isStdlibRequire(node) {
+  return node instanceof CallNode && !node.receiver && !node.block && node.name == "require" &&
+    node.arguments_?.arguments_.length == 1 && node.arguments_.arguments_[0] instanceof StringNode &&
+    (node.arguments_.arguments_[0].unescaped.value == "socket" ||
+      node.arguments_.arguments_[0].unescaped.value.startsWith("semantifold/"))
+}
+
+/**
+ * Reports whether a Ruby node dynamically constructs a facade require identity.
+ * @param {import("@ruby/prism").Node} node - Candidate call.
+ * @returns {boolean} Whether the parser exposes a nonliteral require.
+ */
+function isDynamicStdlibRequire(node) {
+  if (!(node instanceof CallNode) || node.receiver || node.block || node.name != "require" ||
+    node.arguments_?.arguments_.length != 1) return false
+  return !(node.arguments_.arguments_[0] instanceof StringNode)
+}
+
+/**
+ * Reports whether a Ruby node is the canonical module-function marker.
+ * @param {import("@ruby/prism").Node} node - Candidate marker.
+ * @returns {boolean} Whether the node is a bare module-function call.
+ */
+function isModuleFunctionMarker(node) {
+  return node instanceof CallNode && !node.receiver && !node.block && node.name == "module_function" && !node.arguments_
+}
+
+/**
+ * Reads one exact generated Ruby visibility marker.
+ * @param {import("@ruby/prism").Node} node - Candidate module-body node.
+ * @returns {{kind: import("../semantic/types.js").SemanticDeclarationKind, name: string} | undefined} Marker meaning.
+ */
+function rubyVisibilityMarker(node) {
+  if (!(node instanceof CallNode) || node.receiver || node.block ||
+    !["private_class_method", "private_constant"].includes(node.name) ||
+    node.arguments_?.arguments_.length != 1 || !(node.arguments_.arguments_[0] instanceof SymbolNode)) return undefined
+
+  return {
+    kind: node.name == "private_class_method" ? "function" : "record",
+    name: node.arguments_.arguments_[0].unescaped.value
+  }
+}
+
+/**
+ * Builds a parser-owned simple Ruby constant path without inspecting source text.
+ * @param {ConstantReadNode | ConstantPathNode} node - Constant path.
+ * @returns {string} Qualified constant name.
+ */
+function constantPathName(node) {
+  if (node instanceof ConstantReadNode) return node.name
+  if (typeof node.name != "string") throw new Error("Prism returned a constant path without a name.")
+  if (!node.parent) return node.name
+  if (!(node.parent instanceof ConstantReadNode) && !(node.parent instanceof ConstantPathNode)) {
+    throw new Error("Prism returned an unsupported constant-path parent.")
+  }
+
+  return `${constantPathName(node.parent)}::${node.name}`
 }