semantifold 0.3.0 → 0.5.0

package/src/frontends/php.js

@@ -3,11 +3,16 @@
 import PhpParser from "php-parser"
 import {parse as parseComment} from "comment-parser"
 import {missingType, parseFailure, unsupportedSyntax} from "../diagnostic.js"
+import {blockReferencesProtectedEntry} from "../semantic/effects.js"
 import {locationFromOffsets, moduleLocation} 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 {hasOnlyUnicodeScalars, scalarType} from "../semantic/scalars.js"
+import {typeContainsAnyVariable} from "../semantic/generics.js"
+import {requireSourceReturnType, requireSourceScalarType, sourceScalarType} from "./scalars.js"
+import {capabilityFunctionSignatures, documentedValueType, instantiatedRecordFieldType, iterationBindingType, iterationOperandType, knownCallParameterTypes, knownCallReturnType, optionalType, orderedMapTypeFromMap, ownedResourceType, preservesGenericOptionalEvidence, recordType, referenceType, sameValueType} from "./types.js"
 const parser = new PhpParser.Engine({
   ast: {withPositions: true},
   parser: {extractDoc: true, suppressErrors: false}
@@ -31,6 +36,31 @@ const phpBinaryOperations = new Map([
   [".", "StringConcat"]
 ])
 
+/**
+ * @typedef PhpConversionContext
+ * @property {Map<string, import("../semantic/types.js").SemanticBindingType>} bindings - Explicitly typed visible bindings.
+ * @property {Map<string, import("../semantic/types.js").ClassDeclaration>} classes - Reference classes by identity.
+ * @property {import("../semantic/types.js").ClassDeclaration} [currentClass] - Enclosing reference class.
+ * @property {Map<string, import("../semantic/types.js").ErrorDeclaration>} errorNames - Error declarations by source name.
+ * @property {Map<string, import("../semantic/types.js").ErrorDeclaration>} errors - Error declarations by identity.
+ * @property {Map<string, PhpFunctionSignature>} functions - Explicit module function signatures.
+ * @property {Set<object>} [orderedMapDeclarations] - Exact local declarations selected by parser-owned pair iteration.
+ * @property {Map<string, import("../semantic/types.js").RecordDeclaration | import("../semantic/types.js").ClassDeclaration | import("../semantic/types.js").EffectResourceDeclaration>} recordNames - Nominal declarations by source name.
+ * @property {Map<string, import("../semantic/types.js").RecordDeclaration>} records - Record declarations by identity.
+ * @property {import("../semantic/types.js").SemanticFunctionReturnType | undefined} returnType - Enclosing return type.
+ * @property {Map<string, import("../semantic/types.js").TypeParameter>} [typeParameters] - Declaration-scoped parameters.
+ */
+
+/**
+ * @typedef PhpFunctionSignature
+ * @property {import("../semantic/types.js").SourceLocation} location - Complete declaration location.
+ * @property {import("../semantic/types.js").SourceLocation} nameLocation - Parser-owned name location.
+ * @property {string} name - Function name.
+ * @property {import("../semantic/types.js").Parameter[]} parameters - Semantic parameters.
+ * @property {import("../semantic/types.js").SemanticFunctionReturnType} returnType - Semantic return type.
+ * @property {import("../semantic/types.js").TypeParameter[]} [typeParameters] - Declaration-scoped parameters.
+ */
+
 /**
  * Returns a normalized PHP node location.
  * @param {import("php-parser").Node} node - PHP parser node.
@@ -112,17 +142,47 @@ function tokenLocation(tokenText, startOffset, endOffset, filename, source) {
  * @param {import("php-parser").Expression} node - PHP expression.
  * @param {string} filename - Source filename.
  * @param {string} source - Complete source.
+ * @param {PhpConversionContext} context - Typed conversion context.
+ * @param {import("../semantic/types.js").SemanticValueType} [expectedType] - Contextual type for empty PHP arrays.
+ * @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.kind == "nullkeyword") {
+      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.kind == "nullkeyword") return unsupportedSyntax("php", "null outside an explicit optional context", location)
+
   if (node.kind == "variable") {
     const variable = /** @type {import("php-parser").Variable} */ (node)
 
     if (typeof variable.name != "string") return unsupportedSyntax("php", "dynamic variable", location)
+    if (variable.name == "this") {
+      if (!context.currentClass) return unsupportedSyntax("php", "receiver outside a reference class", location)
+      return withParserRanges({classId: /** @type {string} */ (context.currentClass.id),
+        kind: /** @type {const} */ ("ReceiverExpression"), location}, {receiver: location})
+    }
+
+    const identifier = withParserRanges({kind: /** @type {const} */ ("IdentifierExpression"), location, name: variable.name}, {name: location})
 
-    return withParserRanges({kind: /** @type {const} */ ("IdentifierExpression"), location, name: variable.name}, {name: location})
+    if (!preserveOptional && context.bindings.get(variable.name)?.kind == "OptionalType") {
+      return withParserRanges({kind: /** @type {const} */ ("OptionalUnwrap"), location, operand: identifier}, {unwrap: location})
+    }
+
+    return identifier
   }
 
   if (node.kind == "number") {
@@ -169,6 +229,175 @@ function convertExpression(node, filename, source) {
 
   if (node.kind == "nowdoc") return unsupportedSyntax("php", "nowdoc string", location)
 
+  if (node.kind == "array") {
+    const literal = /** @type {import("php-parser").Array} */ (node)
+    const invalidEntry = literal.items.find((entry) => {
+      if (entry.kind != "entry") return true
+      const candidate = /** @type {import("php-parser").Entry} */ (entry)
+
+      return candidate.byRef || candidate.unpack
+    })
+
+    if (invalidEntry) return unsupportedSyntax("php", "array reference or unpacking", nodeLocation(invalidEntry, filename, source))
+    const entries = /** @type {import("php-parser").Entry[]} */ (literal.items)
+    const hasKeys = entries.some((entry) => entry.key != null)
+    const hasImplicit = entries.some((entry) => entry.key == null)
+    const collectionKind = entries.length == 0 ? expectedType?.kind : hasKeys && !hasImplicit
+      ? expectedType?.kind == "OrderedMapType" ? "OrderedMapType" : "MapType"
+      : !hasKeys ? "ListType" : "mixed"
+
+    if (collectionKind == "mixed") return unsupportedSyntax("php", "mixed list/map array literal", location)
+    if (collectionKind == "ListType") {
+      const elementType = expectedType?.kind == "ListType" ? expectedType.elementType : undefined
+
+      return withParserRanges({
+        elements: entries.map((entry) => convertExpression(entry.value, filename, source, context, elementType)),
+        kind: /** @type {const} */ ("ListLiteral"),
+        location
+      }, {literal: location})
+    }
+    if (collectionKind == "MapType" || collectionKind == "OrderedMapType") {
+      const valueType = expectedType?.kind == "MapType" || expectedType?.kind == "OrderedMapType"
+        ? expectedType.valueType : undefined
+      const semanticEntries = entries.map((entry) => {
+        if (!entry.key || entry.key.kind != "string") {
+          return unsupportedSyntax("php", "map key other than a literal string", entry.key ? nodeLocation(entry.key, filename, source) : nodeLocation(entry, filename, source))
+        }
+        const key = convertExpression(entry.key, filename, source, context)
+
+        return withParserRanges({
+          key: /** @type {import("../semantic/types.js").StringLiteral} */ (key),
+          kind: /** @type {const} */ ("MapEntry"),
+          location: nodeLocation(entry, filename, source),
+          value: convertExpression(entry.value, filename, source, context, valueType)
+        }, {operator: tokenLocation("=>", entry.key.loc?.end.offset ?? 0, entry.value.loc?.start.offset ?? source.length, filename, source)})
+      })
+
+      return withParserRanges({
+        entries: semanticEntries,
+        kind: collectionKind == "OrderedMapType"
+          ? /** @type {const} */ ("OrderedMapLiteral")
+          : /** @type {const} */ ("MapLiteral"),
+        location
+      }, {literal: location})
+    }
+
+    return unsupportedSyntax("php", "empty array without a list or map type", location)
+  }
+
+  if (node.kind == "new") {
+    const construction = /** @type {import("php-parser").New} */ (node)
+    const name = construction.what.kind == "name" ? /** @type {import("php-parser").Name} */ (construction.what) : undefined
+
+    if (!name || name.resolution != "uqn" || typeof name.name != "string") {
+      return unsupportedSyntax("php", "dynamic or qualified record construction", nodeLocation(construction.what, filename, source))
+    }
+    const declaration = context.recordNames.get(name.name)
+
+    if (!declaration) return unsupportedSyntax("php", "construction of an unknown nominal class", nodeLocation(construction.what, filename, source))
+    if (declaration.kind == "ClassDeclaration") {
+      const unsupportedArgument = construction.arguments.find((argument) =>
+        argument.kind == "namedargument" || argument.kind == "variadic" || Reflect.get(argument, "byref") === true)
+
+      if (unsupportedArgument) return unsupportedSyntax("php", "non-positional reference constructor argument",
+        nodeLocation(unsupportedArgument, filename, source))
+      const classLocation = nodeLocation(construction.what, filename, source)
+
+      return withParserRanges({arguments: construction.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), classLocation)}, {class: classLocation})
+    }
+    if (declaration.kind == "EffectResourceDeclaration") {
+      return unsupportedSyntax("php", "owned resource construction", nodeLocation(construction, filename, source))
+    }
+    const contextualTypeArguments = expectedType?.kind == "RecordType" && expectedType.declarationId == declaration.id
+      ? expectedType.arguments
+      : undefined
+    const visibleTypeParameterIds = new Set([...context.typeParameters?.values() ?? []]
+      .map((parameter) => /** @type {string} */ (parameter.id)))
+    const typeArguments = contextualTypeArguments &&
+      !contextualTypeArguments.some((argument) => typeContainsAnyVariable(argument, visibleTypeParameterIds))
+      ? contextualTypeArguments
+      : undefined
+
+    return withParserRanges({
+      arguments: construction.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(construction.what, filename, source),
+        typeArguments)
+    }, {record: nodeLocation(construction.what, filename, source)})
+  }
+
+  if (node.kind == "propertylookup") {
+    const read = /** @type {import("php-parser").PropertyLookup} */ (node)
+    const offset = read.offset.kind == "identifier" ? /** @type {import("php-parser").Identifier} */ (read.offset) : undefined
+
+    if (!offset || typeof offset.name != "string") {
+      return unsupportedSyntax("php", "dynamic or computed member access", nodeLocation(read.offset, filename, source))
+    }
+    if (read.what.kind == "variable" && /** @type {import("php-parser").Variable} */ (read.what).name == "this" &&
+      context.currentClass) {
+      const field = context.currentClass.fields.find((candidate) => candidate.name == offset.name)
+
+      if (!field) return unsupportedSyntax("php", `unknown private field '${offset.name}'`, nodeLocation(offset, filename, source))
+      return withParserRanges({field: /** @type {string} */ (field.id), kind: /** @type {const} */ ("PrivateFieldRead"), location,
+        receiver: /** @type {import("../semantic/types.js").ReceiverExpression} */ (
+          convertExpression(read.what, filename, source, context))}, {member: nodeLocation(offset, filename, source)})
+    }
+    const receiverType = knownExpressionType(read.what, context)
+    if (receiverType?.kind == "ReferenceType") {
+      return unsupportedSyntax("php", "private reference-class field access", location)
+    }
+    const receiverRecord = receiverType?.kind == "OptionalType" ? receiverType.valueType : receiverType
+    const declaration = receiverRecord?.kind == "RecordType" ? context.records.get(receiverRecord.declarationId) : undefined
+
+    if ((declaration?.typeParameters?.length ?? 0) > 0) {
+      return unsupportedSyntax("php", "generic record property access", nodeLocation(read.offset, filename, source))
+    }
+    return withParserRanges({
+      field: offset.name,
+      kind: /** @type {const} */ ("MemberRead"),
+      location,
+      receiver: convertExpression(read.what, filename, source, context)
+    }, {member: nodeLocation(read.offset, filename, source)})
+  }
+
+  if (node.kind == "offsetlookup") {
+    const lookup = /** @type {import("php-parser").OffsetLookup} */ (node)
+
+    if (!lookup.offset) return unsupportedSyntax("php", "append or missing array index", location)
+    const receiver = lookup.what.kind == "variable" ? /** @type {import("php-parser").Variable} */ (lookup.what) : undefined
+    const receiverType = receiver && typeof receiver.name == "string" ? context.bindings.get(receiver.name) : undefined
+    const accessKind = receiverType?.kind == "ListType" ? "list" :
+      receiverType?.kind == "MapType" || receiverType?.kind == "OrderedMapType" ? "map" :
+      lookup.offset.kind == "number" ? "list" : lookup.offset.kind == "string" ? "map" : undefined
+
+    if (accessKind == "list" && ["number", "string", "variable"].includes(lookup.offset.kind)) {
+      return withParserRanges({
+        collection: convertExpression(lookup.what, filename, source, context),
+        index: convertExpression(lookup.offset, filename, source, context),
+        kind: /** @type {const} */ ("ListIndexExpression"),
+        location,
+        totality: /** @type {const} */ ("proven")
+      }, {operator: tokenLocation("[", lookup.what.loc?.end.offset ?? 0, lookup.offset.loc?.start.offset ?? source.length, filename, source)})
+    }
+    if (accessKind == "map" && ["number", "string", "variable"].includes(lookup.offset.kind)) {
+      return withParserRanges({
+        collection: convertExpression(lookup.what, filename, source, context),
+        key: convertExpression(lookup.offset, filename, source, context),
+        kind: /** @type {const} */ ("MapLookupExpression"),
+        location,
+        totality: /** @type {const} */ ("proven")
+      }, {operator: tokenLocation("[", lookup.what.loc?.end.offset ?? 0, lookup.offset.loc?.start.offset ?? source.length, filename, source)})
+    }
+
+    return unsupportedSyntax("php", "nonliteral array access", nodeLocation(lookup.offset, filename, source))
+  }
+
   if (node.kind == "unary") {
     const unary = /** @type {import("php-parser").Unary} */ (node)
 
@@ -177,7 +406,7 @@ function convertExpression(node, filename, source) {
     const semantic = withAdaptedOperation(withParserRanges({
       kind: "UnaryExpression",
       location,
-      operand: convertExpression(unary.what, filename, source)
+      operand: convertExpression(unary.what, filename, source, context)
     }, {
       operator: tokenLocation(unary.type, unary.loc?.start.offset ?? 0, unary.what.loc?.start.offset ?? unary.loc?.end.offset ?? source.length, filename, source)
     }), unary.type == "!" ? "Not" : "Negate")
@@ -187,15 +416,24 @@ function convertExpression(node, filename, source) {
 
   if (node.kind == "bin") {
     const binary = /** @type {import("php-parser").Bin} */ (node)
+    if (binary.type == "!==" && binary.left.kind == "variable" && binary.right.kind == "nullkeyword") {
+      const operand = /** @type {import("../semantic/types.js").IdentifierExpression} */ (
+        convertExpression(binary.left, filename, source, context, undefined, true)
+      )
+
+      return withParserRanges({kind: /** @type {const} */ ("OptionalIsPresent"), location, operand}, {
+        operator: tokenLocation(binary.type, binary.left.loc?.end.offset ?? 0, binary.right.loc?.start.offset ?? source.length, filename, source)
+      })
+    }
     if (["==", "!="].includes(binary.type)) return unsupportedSyntax("php", `coercive equality ${binary.type}`, location)
     if (["and", "or"].includes(binary.type)) return unsupportedSyntax("php", `precedence-sensitive boolean ${binary.type}`, location)
     if (!phpBinaryOperations.has(binary.type)) return unsupportedSyntax("php", `binary ${binary.type}`, location)
 
     const semantic = withAdaptedOperation({
       kind: /** @type {const} */ ("BinaryExpression"),
-      left: convertExpression(binary.left, filename, source),
+      left: convertExpression(binary.left, filename, source, context),
       location,
-      right: convertExpression(binary.right, filename, source)
+      right: convertExpression(binary.right, filename, source, context)
     }, /** @type {import("../semantic/operators.js").AdaptedOperation} */ (phpBinaryOperations.get(binary.type)))
 
     return /** @type {import("../semantic/types.js").Expression} */ (/** @type {unknown} */ (withParserRanges(semantic, {
@@ -206,14 +444,88 @@ function convertExpression(node, filename, source) {
   if (node.kind == "call") {
     const call = /** @type {import("php-parser").Call} */ (node)
 
-    if (call.what.kind != "name" && call.what.kind != "identifier") {
+    if (call.what.kind == "propertylookup") {
+      const lookup = /** @type {import("php-parser").PropertyLookup} */ (/** @type {unknown} */ (call.what))
+      const member = lookup.offset.kind == "identifier" ? /** @type {import("php-parser").Identifier} */ (lookup.offset) : undefined
+      const receiverType = knownExpressionType(lookup.what, context)
+
+      if (member && typeof member.name == "string" && receiverType?.kind == "ReferenceType") {
+        const method = context.classes.get(receiverType.declarationId)?.methods.find((candidate) => candidate.name == member.name)
+        const unsupportedArgument = call.arguments.find((argument) =>
+          argument.kind == "namedargument" || argument.kind == "variadic" || Reflect.get(argument, "byref") === true)
+
+        if (unsupportedArgument) return unsupportedSyntax("php", "non-positional method argument",
+          nodeLocation(unsupportedArgument, filename, source))
+        return withParserRanges({arguments: call.arguments.map((argument, index) =>
+          convertExpression(argument, filename, source, context, method?.parameters[index]?.type)),
+        kind: /** @type {const} */ ("MethodCallExpression"), location, method: method?.id ?? member.name,
+        receiver: convertExpression(lookup.what, filename, source, context)}, {member: nodeLocation(member, filename, source)})
+      }
+    }
+
+    if (call.what.kind == "propertylookup" && call.arguments.length == 0) {
+      const lookup = /** @type {import("php-parser").PropertyLookup} */ (/** @type {unknown} */ (call.what))
+      const receiver = lookup.what.kind == "variable" ? /** @type {import("php-parser").Variable} */ (lookup.what) : undefined
+      const member = lookup.offset.kind == "identifier" ? /** @type {import("php-parser").Identifier} */ (lookup.offset) : undefined
+
+      if (receiver && typeof receiver.name == "string" && member?.name == "getMessage" && context.bindings.get(receiver.name)?.kind == "ErrorType") {
+        const receiverLocation = nodeLocation(receiver, filename, source)
+
+        return withParserRanges({
+          kind: /** @type {const} */ ("ErrorMessageRead"),
+          location,
+          receiver: withParserRanges({kind: /** @type {const} */ ("IdentifierExpression"), location: receiverLocation, name: receiver.name}, {
+            name: receiverLocation
+          })
+        }, {member: nodeLocation(member, filename, source)})
+      }
+      if (member && typeof member.name == "string" && knownGenericRecordAccessorType(lookup, context)) {
+        return withParserRanges({
+          field: member.name,
+          kind: /** @type {const} */ ("MemberRead"),
+          location,
+          receiver: convertExpression(lookup.what, filename, source, context)
+        }, {member: nodeLocation(member, filename, source)})
+      }
+    }
+
+    if (call.what.kind == "name" && call.what.name == "count" && call.arguments.length == 1) {
+      return withParserRanges({
+        collection: convertExpression(call.arguments[0], filename, source, context),
+        kind: /** @type {const} */ ("CollectionSizeExpression"),
+        location
+      }, {operator: nodeLocation(call.what, filename, source)})
+    }
+
+    if (call.what.kind != "name") {
       return unsupportedSyntax("php", "dynamic call", location)
     }
+    const calledName = /** @type {import("php-parser").Name} */ (call.what)
 
-    const callee = /** @type {import("php-parser").Name | import("php-parser").Identifier} */ (call.what).name
+    if (calledName.resolution != "uqn" || calledName.name.includes("\\")) {
+      return unsupportedSyntax("php", "qualified call", nodeLocation(call.what, filename, source))
+    }
+    const unsupportedArgument = call.arguments.find((argument) =>
+      argument.kind == "namedargument" || argument.kind == "variadic" || Reflect.get(argument, "byref") === true)
+
+    if (unsupportedArgument) {
+      const detail = unsupportedArgument.kind == "namedargument" ? "named argument" :
+        unsupportedArgument.kind == "variadic" ? "unpacked argument" : "by-reference argument"
+
+      return unsupportedSyntax("php", detail, nodeLocation(unsupportedArgument, filename, source))
+    }
+
+    const callee = calledName.name
+
+    const signature = context.functions.get(callee)
+    const knownArguments = call.arguments.map((argument) => knownCallArgumentType(argument, context))
+    const parameterTypes = signature ? knownCallParameterTypes(signature, knownArguments) : undefined
 
     return withParserRanges({
-      arguments: call.arguments.map((argument) => convertExpression(argument, filename, source)),
+      arguments: call.arguments.map((argument, index) =>
+        convertExpression(argument, filename, source, context,
+          parameterTypes?.[index] ?? signature?.parameters[index]?.type,
+          preservesGenericOptionalEvidence(signature, index))),
       callee,
       kind: "CallExpression",
       location
@@ -223,23 +535,158 @@ function convertExpression(node, filename, source) {
   return unsupportedSyntax("php", node.kind, location)
 }
 
+/**
+ * Resolves only result types established by explicit signatures and bindings.
+ * @param {import("php-parser").Expression} node - Parser-owned expression.
+ * @param {PhpConversionContext} context - Typed conversion context.
+ * @returns {import("../semantic/types.js").SemanticFunctionReturnType | import("../semantic/types.js").ErrorType | undefined} Known result type.
+ */
+function knownExpressionType(node, context) {
+  if (node.kind == "variable") {
+    const variable = /** @type {import("php-parser").Variable} */ (node)
+
+    if (variable.name == "this" && context.currentClass?.id) {
+      return {declarationId: context.currentClass.id, kind: "ReferenceType"}
+    }
+    if (typeof variable.name == "string") return context.bindings.get(variable.name)
+  }
+  if (node.kind == "call") {
+    const call = /** @type {import("php-parser").Call} */ (node)
+    const name = call.what.kind == "name" && typeof call.what.name == "string" ? call.what.name : undefined
+
+    if (name) {
+      const signature = context.functions.get(name)
+
+      if (signature) return knownCallReturnType(signature, call.arguments.map((argument) => knownExpressionType(argument, context)))
+    }
+    if (call.what.kind == "propertylookup" && call.arguments.length == 0) {
+      return knownGenericRecordAccessorType(
+        /** @type {import("php-parser").PropertyLookup} */ (/** @type {unknown} */ (call.what)), context)
+    }
+    if (call.what.kind == "propertylookup") {
+      const lookup = /** @type {import("php-parser").PropertyLookup} */ (/** @type {unknown} */ (call.what))
+      const receiver = knownExpressionType(lookup.what, context)
+      const member = lookup.offset.kind == "identifier" ? /** @type {import("php-parser").Identifier} */ (lookup.offset) : undefined
+
+      if (receiver?.kind == "ReferenceType" && member && typeof member.name == "string") {
+        return context.classes.get(receiver.declarationId)?.methods.find((method) => method.name == member.name)?.returnType
+      }
+    }
+  }
+  if (node.kind == "offsetlookup") {
+    const lookup = /** @type {import("php-parser").OffsetLookup} */ (node)
+    const collectionType = knownExpressionType(lookup.what, context)
+
+    if (collectionType?.kind == "ListType") return collectionType.elementType
+    if (collectionType?.kind == "MapType" || collectionType?.kind == "OrderedMapType") return collectionType.valueType
+  }
+  if (node.kind == "new") {
+    const construction = /** @type {import("php-parser").New} */ (node)
+    const name = construction.what.kind == "name" ? /** @type {import("php-parser").Name} */ (construction.what) : undefined
+    const declaration = name && typeof name.name == "string" ? context.recordNames.get(name.name) : undefined
+
+    if (declaration?.id) return declaration.kind == "ClassDeclaration"
+      ? {declarationId: declaration.id, kind: "ReferenceType"}
+      : {declarationId: declaration.id, kind: "RecordType"}
+  }
+  if (node.kind == "propertylookup") {
+    const read = /** @type {import("php-parser").PropertyLookup} */ (node)
+    const receiver = knownExpressionType(read.what, context)
+
+    if (read.what.kind == "variable" && /** @type {import("php-parser").Variable} */ (read.what).name == "this" &&
+      context.currentClass) {
+      const offset = read.offset.kind == "identifier" ? /** @type {import("php-parser").Identifier} */ (read.offset) : undefined
+
+      return context.currentClass.fields.find((field) => field.name == offset?.name)?.type
+    }
+
+    if (receiver?.kind != "RecordType") return undefined
+    const declaration = context.records.get(receiver.declarationId)
+    const offset = read.offset.kind == "identifier" ? /** @type {import("php-parser").Identifier} */ (read.offset) : undefined
+
+    const memberName = offset && typeof offset.name == "string" ? offset.name : undefined
+
+    if (memberName && declaration) {
+      const index = declaration.fields.findIndex((field) => field.name == memberName)
+
+      return instantiatedRecordFieldType(declaration, receiver.arguments, index)
+    }
+  }
+
+  return undefined
+}
+
+/**
+ * Resolves exact parser-known argument evidence without changing the established
+ * expression-result classifier used for optional conversion.
+ * @param {import("php-parser").Expression} node - Parser-owned call argument.
+ * @param {PhpConversionContext} context - Typed conversion context.
+ * @returns {import("../semantic/types.js").SemanticFunctionReturnType | import("../semantic/types.js").ErrorType | undefined} Known argument type.
+ */
+function knownCallArgumentType(node, context) {
+  const known = knownExpressionType(node, context)
+
+  if (known) return known
+  if (node.kind == "number" && Number.isSafeInteger(Number(/** @type {import("php-parser").Number} */ (node).value))) {
+    return scalarType("integer")
+  }
+  if (node.kind == "boolean" && typeof /** @type {import("php-parser").Boolean} */ (node).value == "boolean") {
+    return scalarType("boolean")
+  }
+  if (node.kind == "string" && typeof /** @type {import("php-parser").String} */ (node).value == "string" &&
+    hasOnlyUnicodeScalars(/** @type {import("php-parser").String} */ (node).value)) {
+    return scalarType("string")
+  }
+
+  return undefined
+}
+
+/**
+ * Resolves PHP's exact zero-argument accessor carrier against its receiver's
+ * generic record declaration.
+ * @param {import("php-parser").PropertyLookup} lookup - Parser-owned method lookup.
+ * @param {PhpConversionContext} context - Typed conversion context.
+ * @returns {import("../semantic/types.js").SemanticValueType | undefined} Instantiated field type.
+ */
+function knownGenericRecordAccessorType(lookup, context) {
+  const receiver = knownExpressionType(lookup.what, context)
+  const receiverRecord = receiver?.kind == "OptionalType" ? receiver.valueType : receiver
+
+  if (receiverRecord?.kind != "RecordType") return undefined
+  const declaration = context.records.get(receiverRecord.declarationId)
+  const member = lookup.offset.kind == "identifier" ? /** @type {import("php-parser").Identifier} */ (lookup.offset) : undefined
+  const index = member && typeof member.name == "string"
+    ? declaration?.fields.findIndex((field) => field.name == member.name) ?? -1
+    : -1
+
+  if (!declaration || (declaration.typeParameters?.length ?? 0) == 0 || index < 0) return undefined
+
+  return instantiatedRecordFieldType(declaration, receiverRecord.arguments, index)
+}
+
 /**
  * Converts one explicit PHP return.
  * @param {import("php-parser").Node} node - PHP node.
  * @param {string} filename - Source filename.
  * @param {string} source - Complete source.
+ * @param {PhpConversionContext} context - Typed 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.kind != "return") return unsupportedSyntax("php", node.kind, location)
 
   const returnNode = /** @type {import("php-parser").Return} */ (node)
+  const expectedType = context.returnType?.kind == "TypeReference" && context.returnType.name == "void"
+    ? undefined
+    : /** @type {import("../semantic/types.js").SemanticValueType | undefined} */ (context.returnType)
 
-  if (!returnNode.expr) return unsupportedSyntax("php", "empty return", location)
-
-  return {expression: convertExpression(returnNode.expr, filename, source), kind: "ReturnStatement", location}
+  return {
+    ...(returnNode.expr ? {expression: convertExpression(returnNode.expr, filename, source, context, expectedType)} : {}),
+    kind: "ReturnStatement",
+    location
+  }
 }
 
 /**
@@ -248,9 +695,11 @@ function convertReturn(node, filename, source) {
  * @param {string} name - Local name.
  * @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(node, name, filename, source) {
+function localMetadata(node, name, filename, source, recordNames, typeParameters = new Map()) {
   const comments = node.leadingComments ?? []
   const comment = comments.at(-1)
 
@@ -278,25 +727,28 @@ function localMetadata(node, name, filename, source) {
 
   return {
     immutable: immutable.length == 1,
-    type: requireSourceScalarType(
-      "php",
-      variables[0].name,
-      `Local '${name}'`,
-      location,
-      commentTagLocation(comment, variables[0], "name", filename, source)
-    )
+    type: documentedValueType({
+      language: "php",
+      location: commentTagLocation(comment, variables[0], "name", filename, source),
+      ownerLocation: location,
+      records: recordNames,
+      source,
+      sourceType: variables[0].name,
+      subject: `Local '${name}'`,
+      typeParameters
+    })
   }
 }
 
 /**
  * Converts one PHP local declaration or assignment.
  * @param {import("php-parser").Node} node - PHP statement.
- * @param {Set<string>} visible - Names visible during adaptation.
  * @param {string} filename - Source filename.
  * @param {string} source - Complete source.
- * @returns {import("../semantic/types.js").LocalStatement} Semantic local statement.
+ * @param {PhpConversionContext} context - Typed conversion context.
+ * @returns {import("../semantic/types.js").LocalStatement | import("../semantic/types.js").PrivateFieldWriteStatement} Semantic local or private-field statement.
  */
-function convertLocalStatement(node, visible, filename, source) {
+function convertLocalStatement(node, filename, source, context) {
   const location = nodeLocation(node, filename, source)
 
   if (node.kind != "expressionstatement") return unsupportedSyntax("php", node.kind, location)
@@ -308,38 +760,90 @@ function convertLocalStatement(node, visible, filename, source) {
   const assignment = /** @type {import("php-parser").Assign} */ (expression)
 
   if (assignment.operator != "=") return unsupportedSyntax("php", `assignment ${assignment.operator}`, location)
+  if (assignment.left.kind == "propertylookup" && context.currentClass) {
+    const lookup = /** @type {import("php-parser").PropertyLookup} */ (assignment.left)
+    const receiver = lookup.what.kind == "variable" ? /** @type {import("php-parser").Variable} */ (lookup.what) : undefined
+    const member = lookup.offset.kind == "identifier" ? /** @type {import("php-parser").Identifier} */ (lookup.offset) : undefined
+    const field = receiver?.name == "this" && member && typeof member.name == "string"
+      ? context.currentClass.fields.find((candidate) => candidate.name == member.name)
+      : undefined
+
+    if (!field) return unsupportedSyntax("php", "private field write outside the declaring receiver", nodeLocation(assignment.left, filename, source))
+    return withParserRanges({expression: convertExpression(assignment.right, filename, source, context, field.type),
+      field: /** @type {string} */ (field.id), kind: /** @type {const} */ ("PrivateFieldWriteStatement"), location,
+      receiver: /** @type {import("../semantic/types.js").ReceiverExpression} */ (
+        convertExpression(lookup.what, filename, source, context))},
+    {member: nodeLocation(/** @type {import("php-parser").Identifier} */ (member), filename, source), operator: tokenLocation("=", assignment.left.loc?.end.offset ?? 0,
+      assignment.right.loc?.start.offset ?? source.length, filename, source)})
+  }
   if (assignment.left.kind != "variable") return unsupportedSyntax("php", assignment.left.kind, nodeLocation(assignment.left, filename, source))
+  if (assignment.right.kind == "throw") {
+    return unsupportedSyntax("php", "throw expression in a value context", nodeLocation(assignment.right, filename, source))
+  }
 
   const variable = /** @type {import("php-parser").Variable} */ (assignment.left)
   const targetLocation = nodeLocation(variable, filename, source)
 
   if (typeof variable.name != "string" || variable.curly) return unsupportedSyntax("php", "dynamic variable", targetLocation)
 
-  const metadata = localMetadata(node, variable.name, filename, source)
+  const metadata = localMetadata(node, variable.name, filename, source, context.recordNames, context.typeParameters)
 
   if (metadata) {
-    visible.add(variable.name)
+    let declaredType = metadata.type
+    let ordered = false
+
+    if (declaredType.kind == "MapType" && context.orderedMapDeclarations?.has(assignment) && assignment.right.kind == "array") {
+      declaredType = orderedMapTypeFromMap(declaredType, location)
+      ordered = true
+    }
+    const initializer = convertExpression(assignment.right, filename, source, context, declaredType)
+
+    context.bindings.set(variable.name, declaredType)
     return withParserRanges({
-      initializer: convertExpression(assignment.right, filename, source),
+      initializer,
       kind: "LocalDeclaration",
       location,
-      mutable: !metadata.immutable,
+      mutable: ordered ? false : !metadata.immutable,
+      name: variable.name,
+      type: declaredType
+    }, {
+      name: targetLocation,
+      operator: tokenLocation("=", assignment.left.loc?.end.offset ?? 0, assignment.right.loc?.start.offset ?? source.length, filename, source)
+    })
+  }
+
+  const inferredType = knownExpressionType(assignment.right, context)
+
+  if (inferredType?.kind == "RecordType" || inferredType?.kind == "ReferenceType" ||
+    inferredType?.kind == "OwnedResourceType") {
+    const initializer = convertExpression(assignment.right, filename, source, context, inferredType)
+
+    context.bindings.set(variable.name, inferredType)
+    return withParserRanges({
+      initializer,
+      kind: /** @type {const} */ ("LocalDeclaration"),
+      location,
+      mutable: false,
       name: variable.name,
-      type: metadata.type
+      type: inferredType
     }, {
       name: targetLocation,
       operator: tokenLocation("=", assignment.left.loc?.end.offset ?? 0, assignment.right.loc?.start.offset ?? source.length, filename, source)
     })
   }
 
-  if (!visible.has(variable.name)) return missingType("php", `Local '${variable.name}'`, location)
+  const bindingType = context.bindings.get(variable.name)
+
+  if (!bindingType) return missingType("php", `Local '${variable.name}'`, location)
 
   const target = withParserRanges({kind: /** @type {const} */ ("IdentifierExpression"), location: targetLocation, name: variable.name}, {
     name: targetLocation
   })
+  const value = convertExpression(assignment.right, filename, source, context,
+    bindingType.kind == "ErrorType" ? undefined : bindingType)
 
   return withParserRanges({
-    expression: convertExpression(assignment.right, filename, source),
+    expression: value,
     kind: "AssignmentStatement",
     location,
     target
@@ -351,33 +855,236 @@ function convertLocalStatement(node, visible, filename, source) {
 /**
  * Converts one exhaustive PHP statement.
  * @param {import("php-parser").Node} node - PHP statement.
- * @param {Set<string>} visible - Names visible during adaptation.
  * @param {string} filename - Source filename.
  * @param {string} source - Complete source.
+ * @param {PhpConversionContext} context - Typed conversion context.
  * @returns {import("../semantic/types.js").Statement} Semantic statement.
  */
-function convertStatement(node, visible, filename, source) {
-  if (node.kind == "return") return convertReturn(node, filename, source)
-  if (node.kind == "if") return convertIf(/** @type {import("php-parser").If} */ (node), visible, filename, source)
-  if (node.kind == "echo") return convertPrint(/** @type {import("php-parser").Echo} */ (node), filename, source)
-  if (node.kind == "expressionstatement") return convertLocalStatement(node, visible, filename, source)
+function convertStatement(node, filename, source, context) {
+  if (node.kind == "return") return convertReturn(node, filename, source, context)
+  if (node.kind == "if") return convertIf(/** @type {import("php-parser").If} */ (node), filename, source, context)
+  if (node.kind == "throw") return convertPhpRaise(node, filename, source, context)
+  if (node.kind == "try") return convertPhpTry(node, filename, source, context)
+  if (node.kind == "while") return convertWhile(/** @type {import("php-parser").While} */ (node), filename, source, context)
+  if (node.kind == "foreach") return convertForEach(/** @type {import("php-parser").Foreach} */ (node), filename, source, context)
+  if (node.kind == "break" || node.kind == "continue") {
+    const control = /** @type {import("php-parser").Break | import("php-parser").Continue} */ (node)
+
+    if (control.level) return unsupportedSyntax("php", `${node.kind} level`, nodeLocation(node, filename, source))
+    const location = tokenLocation(node.kind, node.loc?.start.offset ?? 0, node.loc?.end.offset ?? source.length, filename, source)
+
+    return withParserRanges({
+      kind: /** @type {"BreakStatement" | "ContinueStatement"} */ (node.kind == "break" ? "BreakStatement" : "ContinueStatement"),
+      location
+    }, {keyword: location})
+  }
+  if (node.kind == "echo") return convertPrint(/** @type {import("php-parser").Echo} */ (node), filename, source, context)
+  if (node.kind == "expressionstatement") {
+    const expression = /** @type {import("php-parser").ExpressionStatement} */ (node).expression
+
+    if (expression.kind == "call") {
+      return {
+        expression: /** @type {import("../semantic/types.js").CallExpression | import("../semantic/types.js").MethodCallExpression} */ (
+          convertExpression(expression, filename, source, context)
+        ),
+        kind: "ExpressionStatement",
+        location: nodeLocation(node, filename, source)
+      }
+    }
+
+    return convertLocalStatement(node, filename, source, context)
+  }
 
   return unsupportedSyntax("php", node.kind, nodeLocation(node, filename, source))
 }
 
+/**
+ * Converts exact `throw new DeclaredError(message)`.
+ * @param {import("php-parser").Node} node - PHP throw node.
+ * @param {string} filename - Source filename.
+ * @param {string} source - Complete source.
+ * @param {PhpConversionContext} context - Typed lexical context.
+ * @returns {import("../semantic/types.js").RaiseStatement} Semantic raise.
+ */
+function convertPhpRaise(node, filename, source, context) {
+  const location = nodeLocation(node, filename, source)
+  const construction = Reflect.get(node, "what")
+
+  if (!construction || construction.kind != "new" || construction.what?.kind != "name" ||
+    construction.what.resolution != "uqn" || !context.errorNames.has(construction.what.name) ||
+    !Array.isArray(construction.arguments) || construction.arguments.length != 1 ||
+    construction.arguments[0].kind == "namedargument" || construction.arguments[0].kind == "variadic") {
+    return unsupportedSyntax("php", "throw other than exact declared error construction", location)
+  }
+  const declaration = /** @type {import("../semantic/types.js").ErrorDeclaration} */ (context.errorNames.get(construction.what.name))
+  const typeLocation = nodeLocation(construction.what, filename, source)
+
+  return withParserRanges({
+    error: withParserRanges({
+      error: withParserRanges({declarationId: /** @type {string} */ (declaration.id), kind: /** @type {const} */ ("ErrorType")}, {type: typeLocation}),
+      kind: /** @type {const} */ ("ErrorConstruction"),
+      location: nodeLocation(construction, filename, source),
+      message: convertExpression(construction.arguments[0], filename, source, context)
+    }, {type: typeLocation}),
+    kind: /** @type {const} */ ("RaiseStatement"),
+    location
+  }, {keyword: tokenLocation("throw", node.loc?.start.offset ?? 0, construction.loc?.start.offset ?? source.length, filename, source)})
+}
+
+/**
+ * Converts one exact typed catch with no finally.
+ * @param {import("php-parser").Node} node - PHP try node.
+ * @param {string} filename - Source filename.
+ * @param {string} source - Complete source.
+ * @param {PhpConversionContext} context - Typed lexical context.
+ * @returns {import("../semantic/types.js").TryStatement} Semantic exact handler.
+ */
+function convertPhpTry(node, filename, source, context) {
+  const location = nodeLocation(node, filename, source)
+  const catches = Reflect.get(node, "catches")
+  const body = Reflect.get(node, "body")
+
+  if (Reflect.get(node, "always") || !Array.isArray(catches) || catches.length != 1 || body?.kind != "block") {
+    return unsupportedSyntax("php", "try without one typed catch and no finally", location)
+  }
+  const handler = catches[0]
+  const caught = handler.what?.[0]
+  const binding = handler.variable
+
+  if (handler.what?.length != 1 || caught?.kind != "name" || caught.resolution != "uqn" ||
+    !context.errorNames.has(caught.name) || binding?.kind != "variable" || typeof binding.name != "string" ||
+    binding.curly || handler.body?.kind != "block") {
+    return unsupportedSyntax("php", "broad, multiple, or malformed catch", nodeLocation(handler, filename, source))
+  }
+  const declaration = /** @type {import("../semantic/types.js").ErrorDeclaration} */ (context.errorNames.get(caught.name))
+  const caughtLocation = nodeLocation(caught, 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(binding.name, catchType)
+  return withParserRanges({
+    body: convertBlock(body, filename, source, bodyContext),
+    catchBinding: withParserRanges({
+      kind: /** @type {const} */ ("CatchBinding"),
+      location: nodeLocation(binding, filename, source),
+      mutable: /** @type {const} */ (false),
+      name: binding.name,
+      type: catchType
+    }, {name: nodeLocation(binding, filename, source)}),
+    catchBody: convertBlock(handler.body, filename, source, catchContext),
+    catchType,
+    kind: /** @type {const} */ ("TryStatement"),
+    location
+  }, {catch: nodeLocation(handler, filename, source), try: tokenLocation("try", node.loc?.start.offset ?? 0, body.loc?.start.offset ?? source.length, filename, source)})
+}
+
+/**
+ * Converts exact block-form PHP `foreach ($list as $value)`.
+ * @param {import("php-parser").Foreach} node - PHP foreach node.
+ * @param {string} filename - Source filename.
+ * @param {string} source - Complete source.
+ * @param {PhpConversionContext} context - Typed conversion context.
+ * @returns {import("../semantic/types.js").ForEachStatement | import("../semantic/types.js").ForEachMapStatement} Semantic loop.
+ */
+function convertForEach(node, filename, source, context) {
+  const location = nodeLocation(node, filename, source)
+
+  if (node.shortForm) return unsupportedSyntax("php", "alternative foreach syntax", location)
+  if (node.value.kind != "variable") return unsupportedSyntax("php", "foreach destructuring", nodeLocation(node.value, filename, source))
+  const variable = /** @type {import("php-parser").Variable} */ (node.value)
+
+  if (Reflect.get(variable, "byref") === true) return unsupportedSyntax("php", "by-reference foreach", nodeLocation(variable, filename, source))
+  if (typeof variable.name != "string" || variable.curly) return unsupportedSyntax("php", "dynamic foreach binding", nodeLocation(variable, filename, source))
+  if (!node.body || node.body.kind != "block") {
+    return unsupportedSyntax("php", "foreach without block body", node.body ? nodeLocation(node.body, filename, source) : location)
+  }
+  const body = /** @type {import("php-parser").Block} */ (node.body)
+  const collectionType = iterationOperandType(knownExpressionType(node.source, context))
+
+  if (node.key) {
+    if (node.key.kind != "variable") return unsupportedSyntax("php", "foreach key binding shape", nodeLocation(node.key, filename, source))
+    const keyVariable = /** @type {import("php-parser").Variable} */ (node.key)
+
+    if (Reflect.get(keyVariable, "byref") === true || typeof keyVariable.name != "string" || keyVariable.curly) {
+      return unsupportedSyntax("php", "invalid foreach key binding", nodeLocation(keyVariable, filename, source))
+    }
+    if (collectionType?.kind == "MapType") {
+      return unsupportedSyntax("php", "unordered map iteration", nodeLocation(node.source, filename, source))
+    }
+    if (!collectionType || collectionType.kind != "OrderedMapType") {
+      return missingType("php", "Ordered map iteration collection", nodeLocation(node.source, filename, source))
+    }
+    const keyLocation = nodeLocation(keyVariable, filename, source)
+    const valueLocation = nodeLocation(variable, 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: keyVariable.name, type: keyType
+    }, {name: keyLocation})
+    const valueBinding = withParserRanges({
+      kind: /** @type {const} */ ("ValueBinding"), location: valueLocation, mutable: /** @type {const} */ (false),
+      name: variable.name, type: valueType
+    }, {name: valueLocation})
+    const bodyContext = {...context, bindings: new Map(context.bindings)}
+
+    bodyContext.bindings.set(keyVariable.name, keyType)
+    bodyContext.bindings.set(variable.name, valueType)
+    return withParserRanges({
+      body: convertBlock(body, filename, source, bodyContext),
+      keyBinding,
+      kind: /** @type {const} */ ("ForEachMapStatement"),
+      location,
+      map: convertExpression(node.source, filename, source, context),
+      valueBinding
+    }, {operator: tokenLocation("foreach", node.loc?.start.offset ?? 0, node.source.loc?.start.offset ?? source.length,
+      filename, source)})
+  }
+
+  if (collectionType?.kind == "MapType" || collectionType?.kind == "OrderedMapType") {
+    return unsupportedSyntax("php", "map iteration without key/value pair binding", nodeLocation(node.source, filename, source))
+  }
+  if (!collectionType || collectionType.kind != "ListType") {
+    return missingType("php", "Iteration collection", nodeLocation(node.source, filename, source))
+  }
+  const bindingLocation = nodeLocation(variable, 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: variable.name,
+    type: bindingType
+  }, {name: bindingLocation})
+  const bodyContext = {...context, bindings: new Map(context.bindings)}
+
+  bodyContext.bindings.set(variable.name, bindingType)
+  return withParserRanges({
+    body: convertBlock(body, filename, source, bodyContext),
+    kind: /** @type {const} */ ("ForEachStatement"),
+    list: convertExpression(node.source, filename, source, context),
+    location,
+    valueBinding
+  }, {operator: tokenLocation("foreach", node.loc?.start.offset ?? 0, node.source.loc?.start.offset ?? source.length, filename, source)})
+}
+
 /**
  * Converts an ordered PHP block with its own adaptation scope.
  * @param {import("php-parser").Block} node - PHP parser block.
- * @param {Set<string>} visible - Names visible on block entry.
  * @param {string} filename - Source filename.
  * @param {string} source - Complete source.
+ * @param {PhpConversionContext} context - Typed conversion context.
  * @returns {import("../semantic/types.js").Block} Semantic block.
  */
-function convertBlock(node, visible, filename, source) {
+function convertBlock(node, filename, source, context) {
   return {
     kind: "Block",
     location: nodeLocation(node, filename, source),
-    statements: node.children.map((statement) => convertStatement(statement, visible, filename, source))
+    statements: node.children.map((statement) => convertStatement(statement, filename, source, context))
   }
 }
 
@@ -388,9 +1095,10 @@ function convertBlock(node, visible, filename, source) {
  * @param {import("../semantic/types.js").SourceLocation} location - Source location.
  * @param {string} filename - Source filename.
  * @param {string} source - Complete source.
- * @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.
+ * @returns {import("../semantic/types.js").SemanticValueType} Semantic type.
  */
-function convertType(sourceType, subject, location, filename, source) {
+function convertType(sourceType, subject, location, filename, source, recordNames = new Map()) {
   if (!sourceType) return requireSourceScalarType("php", undefined, subject, location)
   if (sourceType.kind != "typereference" && sourceType.kind != "name" && sourceType.kind != "identifier") {
     return unsupportedSyntax("php", "unsupported scalar type", nodeLocation(sourceType, filename, source))
@@ -398,17 +1106,161 @@ function convertType(sourceType, subject, location, filename, source) {
 
   const typeName = /** @type {import("php-parser").TypeReference | import("php-parser").Name | import("php-parser").Identifier} */ (sourceType).name
 
-  return requireSourceScalarType("php", typeName, subject, location, nodeLocation(sourceType, filename, source))
+  const typeLocation = nodeLocation(sourceType, filename, source)
+  const declaration = recordNames.get(typeName)
+
+  if (declaration?.id) return declaration.kind == "ClassDeclaration"
+    ? referenceType(declaration.id, typeLocation)
+    : declaration.kind == "EffectResourceDeclaration"
+      ? ownedResourceType(declaration.id, typeLocation)
+      : recordType(declaration.id, typeLocation)
+
+  return requireSourceScalarType("php", typeName, subject, location, typeLocation)
+}
+
+/**
+ * Reads the exact PHPDoc container signature attached to one function.
+ * @param {import("php-parser").Function} node - Function declaration.
+ * @param {string} filename - Source filename.
+ * @param {string} source - Complete source.
+ * @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[]}} Documented types.
+ */
+function functionDocumentedTypes(node, filename, source, ownerId) {
+  const comment = node.leadingComments?.at(-1)
+
+  if (!comment || comment.kind != "commentblock" || !comment.loc || !node.loc ||
+    !/^\s*$/u.test(source.slice(comment.loc.end.offset, node.loc.start.offset))) return {parameters: new Map(), returnType: undefined}
+  const block = parseComment(comment.value)[0]
+  const tags = block?.tags ?? []
+  const parameterTags = tags.filter((tag) => tag.tag == "param")
+  const returnTags = tags.filter((tag) => tag.tag == "return" || tag.tag == "returns")
+  const templateTags = tags.filter((tag) => tag.tag == "template")
+  const malformedTemplate = tags.find((tag) => tag.tag.startsWith("template") && tag.tag != "template")
+  const malformed = tags.some((tag) => !["param", "return", "returns", "template"].includes(tag.tag)) || returnTags.length > 1 ||
+    parameterTags.some((tag) => tag.type != "" || !/^\$[A-Za-z_][A-Za-z0-9_]*$/u.test(tag.description)) ||
+    returnTags.some((tag) => tag.type != "" || tag.description != "") || malformedTemplate ||
+    templateTags.some((tag) => !/^[A-Za-z_][A-Za-z0-9_]*$/u.test(tag.name) || tag.type != "" || tag.description != "") ||
+    templateTags.length > 0 && !ownerId
+
+  if (malformed) return unsupportedSyntax("php", "malformed function type annotation", nodeLocation(node, filename, source))
+  const parameters = new Map(parameterTags.map((tag) => [tag.description.slice(1), {
+    location: commentTagLocation(comment, tag, "name", filename, source),
+    sourceType: tag.name
+  }]))
+
+  if (parameters.size != parameterTags.length) {
+    return unsupportedSyntax("php", "duplicate parameter annotation", nodeLocation(node, filename, source))
+  }
+  const returnTag = returnTags[0]
+  const typeParameters = templateTags.map((tag, index) => {
+    const location = commentTagLocation(comment, tag, "name", filename, source)
+
+    return withParserRanges({id: `${ownerId}:type:${index}`, kind: /** @type {const} */ ("TypeParameter"), location, name: tag.name}, {name: location})
+  })
+
+  return {
+    parameters,
+    returnType: returnTag ? {
+      location: commentTagLocation(comment, returnTag, "name", filename, source),
+      sourceType: returnTag.name
+    } : undefined,
+    ...(typeParameters.length > 0 ? {typeParameters} : {})
+  }
+}
+
+/**
+ * Reads an optional exact class-level PHPDoc template list.
+ * @param {import("php-parser").Class} node - Class declaration.
+ * @param {string} ownerId - Stable record identity.
+ * @param {string} filename - Source filename.
+ * @param {string} source - Complete source.
+ * @returns {import("../semantic/types.js").TypeParameter[] | undefined} Ordered parameters.
+ */
+function classDocumentedTypeParameters(node, ownerId, filename, source) {
+  const documented = functionDocumentedTypes(
+    /** @type {import("php-parser").Function} */ (/** @type {unknown} */ (node)), filename, source, ownerId)
+
+  if (documented.parameters.size || documented.returnType) {
+    return unsupportedSyntax("php", "function type annotation on record declaration", nodeLocation(node, filename, source))
+  }
+
+  return documented.typeParameters
+}
+
+/**
+ * Returns a native PHP type name from one supported parser node.
+ * @param {import("php-parser").Node | null} type - Native type node.
+ * @returns {string | undefined} Type name.
+ */
+function phpTypeName(type) {
+  if (!type || !["typereference", "name", "identifier"].includes(type.kind)) return undefined
+
+  return /** @type {import("php-parser").TypeReference | import("php-parser").Name | import("php-parser").Identifier} */ (type).name
+}
+
+/**
+ * Wraps one parser-declared canonical PHP nullable type.
+ * @param {import("../semantic/types.js").SemanticValueType} valueType - Present-value semantic type.
+ * @param {import("php-parser").Node} sourceType - Native parser type node.
+ * @param {number} ownerStart - Earliest owning parser offset.
+ * @param {string} filename - Source filename.
+ * @param {string} source - Complete source.
+ * @returns {import("../semantic/types.js").OptionalType} Optional semantic type.
+ */
+function nullableType(valueType, sourceType, ownerStart, filename, source) {
+  if (!sourceType.loc) throw new Error("PHP parser omitted nullable type location.")
+  const valueLocation = nodeLocation(sourceType, filename, source)
+  const marker = tokenLocation("?", ownerStart, sourceType.loc.start.offset, filename, source)
+
+  if (marker.end.offset != valueLocation.start.offset) {
+    return unsupportedSyntax("php", "noncanonical nullable type", marker)
+  }
+
+  return optionalType(
+    valueType,
+    locationFromOffsets(filename, source, marker.start.offset, valueLocation.end.offset),
+    valueLocation
+  )
+}
+
+/**
+ * Converts one explicit PHP function return type.
+ * @param {import("php-parser").Node | null} sourceType - PHP return type node.
+ * @param {string} subject - Typed function return.
+ * @param {import("../semantic/types.js").SourceLocation} location - Function location.
+ * @param {string} filename - Source filename.
+ * @param {string} source - Complete source.
+ * @param {Map<string, import("../semantic/types.js").RecordDeclaration | import("../semantic/types.js").ClassDeclaration | import("../semantic/types.js").EffectResourceDeclaration>} [recordNames] - Nominal declarations by source name.
+ * @returns {import("../semantic/types.js").SemanticFunctionReturnType} Semantic return type.
+ */
+function convertReturnType(sourceType, subject, location, filename, source, recordNames = new Map()) {
+  if (!sourceType) return requireSourceReturnType("php", undefined, subject, location)
+  if (sourceType.kind != "typereference" && sourceType.kind != "name" && sourceType.kind != "identifier") {
+    return unsupportedSyntax("php", "unsupported return type", nodeLocation(sourceType, filename, source))
+  }
+  const typeName = /** @type {import("php-parser").TypeReference | import("php-parser").Name | import("php-parser").Identifier} */ (sourceType).name
+  const declaration = recordNames.get(typeName)
+
+  if (declaration?.id) return declaration.kind == "ClassDeclaration"
+    ? referenceType(declaration.id, nodeLocation(sourceType, filename, source))
+    : declaration.kind == "EffectResourceDeclaration"
+      ? ownedResourceType(declaration.id, nodeLocation(sourceType, filename, source))
+      : recordType(declaration.id, nodeLocation(sourceType, filename, source))
+
+  return requireSourceReturnType("php", typeName, subject, location, nodeLocation(sourceType, filename, source))
 }
 
 /**
- * Converts a PHP function.
+ * Converts the explicit type signature of one PHP function before any body expressions.
  * @param {import("php-parser").Function} node - PHP function node.
  * @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.
+ * @returns {PhpFunctionSignature} Typed function signature.
  */
-function convertFunction(node, filename, source) {
+function convertFunctionSignature(node, filename, source, recordNames, ownerId) {
   const location = nodeLocation(node, filename, source)
   const name = typeof node.name == "string" ? node.name : node.name.name
 
@@ -416,88 +1268,615 @@ function convertFunction(node, filename, source) {
     return unsupportedSyntax("php", "function body", location)
   }
 
+  const documented = functionDocumentedTypes(node, filename, source, ownerId)
+  const typeParameterNames = new Map((documented.typeParameters ?? []).map((parameter) => [parameter.name, parameter]))
   const parameters = node.arguments.map((parameter) => {
     const parameterLocation = nodeLocation(parameter, filename, source)
     const parameterName = typeof parameter.name == "string" ? parameter.name : parameter.name.name
 
-    if (parameter.nullable) return unsupportedSyntax("php", "unsupported scalar type", parameterLocation)
-
+    if (parameter.byref) return unsupportedSyntax("php", "by-reference parameter", parameterLocation)
+    if (parameter.variadic) return unsupportedSyntax("php", "variadic parameter", parameterLocation)
+    if (parameter.value) return unsupportedSyntax("php", "default parameter", parameterLocation)
     const parameterNode = typeof parameter.name == "string" ? parameter : parameter.name
+    const documentedType = documented.parameters.get(parameterName)
+    const nativeType = phpTypeName(parameter.type)
+
+    let parameterType = documentedType
+      ? documentedValueType({language: "php", location: documentedType.location, ownerLocation: parameterLocation, source,
+        records: recordNames, sourceType: documentedType.sourceType, subject: `Parameter '${parameterName}'`, typeParameters: typeParameterNames})
+      : convertType(parameter.type, `Parameter '${parameterName}'`, parameterLocation, filename, source, recordNames)
+
+    if (nativeType == "array" && !documentedType) return missingType("php", `Parameter '${parameterName}'`, parameterLocation)
+    if (documentedType && !phpDocumentedNativeTypeMatches(nativeType, parameter.nullable, parameterType, recordNames)) {
+      return unsupportedSyntax("php", "documented parameter type incompatible with native type", documentedType.location)
+    }
+
+    if (parameter.nullable && parameterType.kind != "OptionalType") {
+      if (!parameter.type) return missingType("php", `Parameter '${parameterName}'`, parameterLocation)
+      parameterType = nullableType(parameterType, parameter.type, parameter.loc?.start.offset ?? 0, filename, source)
+    } else if (!parameter.nullable && parameterType.kind == "OptionalType" &&
+      parameterType.valueType.kind != "TypeVariableReference") {
+      return unsupportedSyntax("php", "optional annotation without nullable native type", documentedType?.location ?? parameterLocation)
+    }
     const semanticParameter = {
       kind: /** @type {const} */ ("Parameter"),
       location: parameterLocation,
       name: parameterName,
-      type: convertType(parameter.type, `Parameter '${parameterName}'`, parameterLocation, filename, source)
+      type: parameterType
     }
 
     return withParserRanges(semanticParameter, {name: nodeLocation(parameterNode, filename, source)})
   })
-  if (node.nullable) return unsupportedSyntax("php", "unsupported scalar type", location)
-  const visible = new Set(parameters.map((parameter) => parameter.name))
-  const body = convertBlock(node.body, visible, filename, source)
+  const extraDocumentedParameter = [...documented.parameters.keys()].find((name) =>
+    !node.arguments.some((parameter) => (typeof parameter.name == "string" ? parameter.name : parameter.name.name) == name))
 
+  if (extraDocumentedParameter) return unsupportedSyntax("php", `annotation for unknown parameter '${extraDocumentedParameter}'`, location)
+  if (node.byref) return unsupportedSyntax("php", "by-reference return", location)
   const nameNode = typeof node.name == "string" ? node : node.name
+  const nativeReturnType = phpTypeName(node.type)
+  let returnType
+
+  if (documented.returnType) {
+    returnType = documentedValueType({language: "php", location: documented.returnType.location, ownerLocation: location, source,
+      records: recordNames, sourceType: documented.returnType.sourceType, subject: `Function '${name}' return`, typeParameters: typeParameterNames})
+    if (!phpDocumentedNativeTypeMatches(nativeReturnType, node.nullable, returnType, recordNames)) {
+      return unsupportedSyntax("php", "documented return type incompatible with native type", documented.returnType.location)
+    }
+  } else {
+    if (nativeReturnType == "array") return missingType("php", `Function '${name}' return`, location)
+    returnType = convertReturnType(node.type, `Function '${name}' return`, location, filename, source, recordNames)
+  }
+  if (node.nullable && returnType.kind != "OptionalType") {
+    if (!node.type) return missingType("php", `Function '${name}' return`, location)
+    const typeStart = node.type.loc?.start.offset ?? 0
+
+    returnType = nullableType(
+      /** @type {import("../semantic/types.js").SemanticValueType} */ (returnType),
+      node.type,
+      Math.max(node.loc?.start.offset ?? 0, typeStart - 2),
+      filename,
+      source
+    )
+  } else if (!node.nullable && returnType.kind == "OptionalType" &&
+    returnType.valueType.kind != "TypeVariableReference") {
+    return unsupportedSyntax("php", "optional annotation without nullable native return type", documented.returnType?.location ?? location)
+  }
 
-  return withParserRanges({
-    body,
-    kind: "FunctionDeclaration",
+  return {
     location,
     name,
+    nameLocation: nodeLocation(nameNode, filename, source),
     parameters,
-    returnType: convertType(node.type, `Function '${name}' return`, location, filename, source)
-  }, {name: nodeLocation(nameNode, filename, source)})
+    returnType,
+    ...(documented.typeParameters ? {typeParameters: documented.typeParameters} : {})
+  }
+}
+
+/**
+ * Checks the exact runtime carrier permitted beside a precise PHPDoc type.
+ * @param {string | undefined} nativeType - Native PHP type name.
+ * @param {boolean} nativeNullable - Whether the native carrier has PHP's nullable marker.
+ * @param {import("../semantic/types.js").SemanticValueType} documentedType - Exact semantic document type.
+ * @param {Map<string, import("../semantic/types.js").RecordDeclaration | import("../semantic/types.js").ClassDeclaration | import("../semantic/types.js").EffectResourceDeclaration>} records - Visible nominal declarations by name.
+ * @returns {boolean} Whether the native carrier agrees without changing meaning.
+ */
+function phpDocumentedNativeTypeMatches(nativeType, nativeNullable, documentedType, records) {
+  if (documentedType.kind == "OptionalType") {
+    if (documentedType.valueType.kind == "TypeVariableReference") {
+      return nativeType === undefined && !nativeNullable
+    }
+
+    return nativeNullable && phpDocumentedNativeTypeMatches(nativeType, false, documentedType.valueType, records)
+  }
+  if (nativeNullable) return false
+  if (documentedType.kind == "TypeVariableReference") return nativeType === undefined
+  if (documentedType.kind == "TypeReference") {
+    return nativeType !== undefined && sourceScalarType("php", nativeType)?.name == documentedType.name
+  }
+  if (documentedType.kind == "ListType" || documentedType.kind == "MapType" || documentedType.kind == "OrderedMapType") {
+    return nativeType == "array"
+  }
+  if (documentedType.kind == "RecordType") {
+    return nativeType !== undefined && records.get(nativeType)?.id == documentedType.declarationId
+  }
+  if (documentedType.kind == "ReferenceType") {
+    return nativeType !== undefined && records.get(nativeType)?.id == documentedType.declarationId
+  }
+
+  return false
+}
+
+/**
+ * Converts a PHP function body using the already-proved module signatures.
+ * @param {import("php-parser").Function} node - PHP function node.
+ * @param {PhpFunctionSignature} signature - Preconverted explicit signature.
+ * @param {Map<string, PhpFunctionSignature>} functions - Module function 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 {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, filename, source) {
+  if (!node.body) return unsupportedSyntax("php", "function body", signature.location)
+  const context = {
+    bindings: new Map(signature.parameters.map((parameter) => [parameter.name, parameter.type])),
+    classes,
+    errorNames,
+    errors,
+    functions,
+    orderedMapDeclarations: orderedMapDeclarationsForPhp(node.body),
+    recordNames,
+    records,
+    returnType: signature.returnType,
+    typeParameters: new Map((signature.typeParameters ?? []).map((parameter) => [parameter.name, parameter]))
+  }
+
+  return withParserRanges({
+    body: convertBlock(node.body, filename, source, context),
+    kind: "FunctionDeclaration",
+    location: signature.location,
+    name: signature.name,
+    parameters: signature.parameters,
+    returnType: signature.returnType,
+    ...(signature.typeParameters ? {typeParameters: signature.typeParameters} : {})
+  }, {name: signature.nameLocation})
+}
+
+/**
+ * Resolves parser-owned key/value loops to exact declarations inside one lexical owner.
+ * Ambiguous same-name declarations produce no evidence and fail during loop conversion.
+ * @param {unknown} value - Function body or entry-point subtree.
+ * @returns {Set<object>} Exact pair-iterated parser declarations.
+ */
+function orderedMapDeclarationsForPhp(value) {
+  /** @type {{declaration: object, name: string, offset: number}[]} */
+  const declarations = []
+  /** @type {{name: string, offset: number}[]} */
+  const receivers = []
+  const seen = new WeakSet()
+  /**
+   * Visits one parser candidate.
+   * @param {unknown} candidate - Parser candidate.
+   */
+  const visit = (candidate) => {
+    if (!candidate || typeof candidate != "object" || seen.has(candidate)) return
+    seen.add(candidate)
+    const kind = Reflect.get(candidate, "kind")
+
+    if (kind == "function" || kind == "class") return
+    if (kind == "assign") {
+      const variable = Reflect.get(candidate, "left")
+
+      if (Reflect.get(variable, "kind") == "variable" && typeof Reflect.get(variable, "name") == "string") {
+        declarations.push({
+          declaration: candidate,
+          name: Reflect.get(variable, "name"),
+          offset: Reflect.get(variable, "loc")?.start.offset
+        })
+      }
+    } else if (kind == "foreach") {
+      const receiver = Reflect.get(candidate, "source")
+
+      if (Reflect.get(receiver, "kind") == "variable" && typeof Reflect.get(receiver, "name") == "string" &&
+        Reflect.get(candidate, "key")) receivers.push({
+        name: Reflect.get(receiver, "name"),
+        offset: Reflect.get(candidate, "loc")?.start.offset
+      })
+    }
+    for (const [key, child] of Object.entries(candidate)) {
+      if (["loc", "leadingComments", "trailingComments"].includes(key)) continue
+      if (Array.isArray(child)) {
+        for (const item of child) visit(item)
+      } else visit(child)
+    }
+  }
+
+  visit(value)
+  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 final RuntimeException subclass.
+ * @param {import("php-parser").Class} node - PHP 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 convertPhpError(node, declaration, filename, source) {
+  const location = nodeLocation(node, filename, source)
+  const parent = node.extends
+  const parentName = parent?.kind == "name" ? /** @type {import("php-parser").Name} */ (/** @type {unknown} */ (parent)) : undefined
+
+  if (node.isAnonymous || !node.isFinal || node.isReadonly || node.isAbstract || node.implements?.length ||
+    node.attrGroups.length || node.body.length != 0 || !parentName ||
+    !(parentName.name == "RuntimeException" && parentName.resolution == "uqn" ||
+      parentName.name == "\\RuntimeException" && parentName.resolution == "fqn")) {
+    return unsupportedSyntax("php", "noncanonical typed error declaration", location)
+  }
+  const nameNode = typeof node.name == "string" ? node : node.name
+
+  return withParserRanges(declaration, {name: nodeLocation(nameNode, filename, source), type: nodeLocation(parentName, filename, source)})
+}
+
+/**
+ * Reads one exact public PHP constructor or instance-method signature.
+ * @param {import("php-parser").Method} node - Parser-owned method.
+ * @param {Map<string, import("../semantic/types.js").RecordDeclaration | import("../semantic/types.js").ClassDeclaration | import("../semantic/types.js").EffectResourceDeclaration>} nominalNames - Visible nominal declarations.
+ * @param {string} ownerId - Stable callable identity.
+ * @param {boolean} constructor - Whether this is the sole constructor.
+ * @param {string} filename - Source filename.
+ * @param {string} source - Complete source.
+ * @returns {{location: import("../semantic/types.js").SourceLocation, name: string, nameLocation: import("../semantic/types.js").SourceLocation, parameters: import("../semantic/types.js").Parameter[], returnType?: import("../semantic/types.js").SemanticFunctionReturnType}} Exact signature.
+ */
+function convertPhpClassCallableSignature(node, nominalNames, ownerId, constructor, filename, source) {
+  const location = nodeLocation(node, filename, source)
+  const name = typeof node.name == "string" ? node.name : node.name.name
+
+  if (!constructor && /^__/u.test(name)) return unsupportedSyntax("php", `reserved reference method '${name}'`, location)
+  if (node.visibility != "public" || node.isStatic || node.isAbstract || node.isFinal || Reflect.get(node, "isReadonly") || node.byref ||
+    node.attrGroups.length || !node.body || constructor != (name == "__construct")) {
+    return unsupportedSyntax("php", "noncanonical reference class callable", location)
+  }
+  const documented = functionDocumentedTypes(/** @type {import("php-parser").Function} */ (/** @type {unknown} */ (node)),
+    filename, source, ownerId)
+  if (documented.typeParameters?.length) return unsupportedSyntax("php", "generic reference class callable", location)
+  if (constructor && (node.type || node.nullable || documented.returnType)) {
+    return unsupportedSyntax("php", "constructor return annotation", location)
+  }
+  const parameters = node.arguments.map((parameter) => {
+    const parameterLocation = nodeLocation(parameter, filename, source)
+    const parameterName = typeof parameter.name == "string" ? parameter.name : parameter.name.name
+
+    if (parameter.byref || parameter.variadic || parameter.value || parameter.flags || parameter.readonly ||
+      parameter.hooks.length || parameter.attrGroups.length) {
+      return unsupportedSyntax("php", "noncanonical reference class parameter", parameterLocation)
+    }
+    const documentedType = documented.parameters.get(parameterName)
+    const nativeType = phpTypeName(parameter.type)
+    let type = documentedType
+      ? documentedValueType({language: "php", location: documentedType.location, ownerLocation: parameterLocation,
+        records: nominalNames, source, sourceType: documentedType.sourceType, subject: `Parameter '${parameterName}'`})
+      : convertType(parameter.type, `Parameter '${parameterName}'`, parameterLocation, filename, source, nominalNames)
+
+    if (nativeType == "array" && !documentedType) return missingType("php", `Parameter '${parameterName}'`, parameterLocation)
+    if (documentedType && !phpDocumentedNativeTypeMatches(nativeType, parameter.nullable, type, nominalNames)) {
+      return unsupportedSyntax("php", "documented parameter type incompatible with native type", documentedType.location)
+    }
+    if (parameter.nullable && type.kind != "OptionalType") {
+      if (!parameter.type) return missingType("php", `Parameter '${parameterName}'`, parameterLocation)
+      type = nullableType(type, parameter.type, parameter.loc?.start.offset ?? 0, filename, source)
+    } else if (!parameter.nullable && type.kind == "OptionalType") {
+      return unsupportedSyntax("php", "optional annotation without nullable native type", documentedType?.location ?? parameterLocation)
+    }
+    const nameNode = typeof parameter.name == "string" ? parameter : parameter.name
+
+    return withParserRanges({kind: /** @type {const} */ ("Parameter"), location: parameterLocation,
+      name: parameterName, type}, {name: nodeLocation(nameNode, filename, source)})
+  })
+  if ([...documented.parameters.keys()].some((parameterName) =>
+    !node.arguments.some((parameter) => (typeof parameter.name == "string" ? parameter.name : parameter.name.name) == parameterName))) {
+    return unsupportedSyntax("php", "method PHPDoc parameter mismatch", location)
+  }
+  const nameNode = typeof node.name == "string" ? node : node.name
+
+  if (constructor) return {location, name: "constructor", nameLocation: nodeLocation(nameNode, filename, source), parameters}
+  let returnType
+  const nativeReturnType = phpTypeName(node.type)
+
+  if (documented.returnType) {
+    returnType = documentedValueType({language: "php", location: documented.returnType.location, ownerLocation: location,
+      records: nominalNames, source, sourceType: documented.returnType.sourceType, subject: `Method '${name}' return`})
+    if (!phpDocumentedNativeTypeMatches(nativeReturnType, node.nullable, returnType, nominalNames)) {
+      return unsupportedSyntax("php", "documented method return type incompatible with native type", documented.returnType.location)
+    }
+  } else {
+    if (nativeReturnType == "array") return missingType("php", `Method '${name}' return`, location)
+    returnType = convertReturnType(node.type, `Method '${name}' return`, location, filename, source, nominalNames)
+  }
+  if (node.nullable && returnType.kind != "OptionalType") {
+    if (!node.type) return missingType("php", `Method '${name}' return`, location)
+    returnType = nullableType(/** @type {import("../semantic/types.js").SemanticValueType} */ (returnType), node.type,
+      node.type.loc?.start.offset ?? 0, filename, source)
+  } else if (!node.nullable && returnType.kind == "OptionalType") {
+    return unsupportedSyntax("php", "optional annotation without nullable native return type", documented.returnType?.location ?? location)
+  }
+
+  return {location, name, nameLocation: nodeLocation(nameNode, filename, source), parameters, returnType}
+}
+
+/**
+ * Converts the bounded final/private-field PHP reference-class profile.
+ * @param {import("php-parser").Class} node - Parser class.
+ * @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, PhpFunctionSignature>} 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 {string} filename - Source filename.
+ * @param {string} source - Complete source.
+ * @returns {import("../semantic/types.js").ClassDeclaration} Semantic class.
+ */
+function convertPhpReferenceClass(node, declaration, nominalNames, records, classes, functions, errorNames, errors,
+  filename, source) {
+  const location = nodeLocation(node, filename, source)
+
+  if (node.isAnonymous || !node.isFinal || node.isReadonly || node.isAbstract || node.extends || node.implements?.length ||
+    node.attrGroups.length) return unsupportedSyntax("php", "reference class inheritance or noncanonical modifier", location)
+  const fieldStatements = node.body.filter((member) => member.kind == "propertystatement")
+  const methodNodes = /** @type {import("php-parser").Method[]} */ (node.body.filter((member) => member.kind == "method"))
+  const constructors = methodNodes.filter((method) => (typeof method.name == "string" ? method.name : method.name.name) == "__construct")
+  const ordinaryMethods = methodNodes.filter((method) => !constructors.includes(method))
+
+  if (constructors.length != 1 || fieldStatements.length == 0 || fieldStatements.length + methodNodes.length != node.body.length) {
+    return unsupportedSyntax("php", "reference class requires private fields, one constructor, and ordinary methods", location)
+  }
+  declaration.fields = fieldStatements.map((statement, index) => {
+    const fieldLocation = nodeLocation(statement, filename, source)
+    const properties = Reflect.get(statement, "properties")
+    const property = Array.isArray(properties) && properties.length == 1 ? properties[0] : undefined
+    const nameNode = property?.name
+    const name = typeof nameNode == "string" ? nameNode : nameNode?.name
+
+    if (Reflect.get(statement, "visibility") != "private" || Reflect.get(statement, "isStatic") ||
+      Reflect.get(statement, "isAbstract") || Reflect.get(statement, "isFinal") || !property ||
+      typeof name != "string" || property.value || property.readonly || property.nullable || property.attrGroups?.length ||
+      property.hooks?.length) return unsupportedSyntax("php", "noncanonical private instance field", fieldLocation)
+    const type = convertType(property.type, `Private field '${name}'`, fieldLocation, filename, source, nominalNames)
+
+    return withParserRanges({id: `${declaration.id}:field:${index}`, kind: /** @type {const} */ ("PrivateField"),
+      location: fieldLocation, name, type}, {name: nodeLocation(typeof nameNode == "string" ? property : nameNode, filename, source)})
+  })
+  const constructorNode = constructors[0]
+  const constructorSignature = convertPhpClassCallableSignature(constructorNode, nominalNames,
+    `${declaration.id}:constructor`, true, filename, source)
+
+  declaration.constructor = withParserRanges({body: /** @type {import("../semantic/types.js").Block} */ ({}),
+    id: `${declaration.id}:constructor`, kind: /** @type {const} */ ("ConstructorDeclaration"),
+    location: constructorSignature.location, parameters: constructorSignature.parameters}, {constructor: constructorSignature.nameLocation})
+  const methodSignatures = ordinaryMethods.map((method, index) => convertPhpClassCallableSignature(method, nominalNames,
+    `${declaration.id}:method:${index}`, false, filename, source))
+
+  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: /** @type {import("../semantic/types.js").SemanticFunctionReturnType} */ (signature.returnType)
+  }, {name: signature.nameLocation}))
+  const base = {bindings: new Map(), classes, currentClass: declaration, errorNames, errors, functions,
+    recordNames: nominalNames, records}
+
+  declaration.constructor.body = convertBlock(/** @type {import("php-parser").Block} */ (constructorNode.body), filename, source,
+    {...base, bindings: new Map(declaration.constructor.parameters.map((parameter) => [parameter.name, parameter.type])),
+      returnType: {kind: /** @type {const} */ ("TypeReference"), name: /** @type {const} */ ("void")}})
+  for (let index = 0; index < ordinaryMethods.length; index += 1) {
+    const method = declaration.methods[index]
+
+    method.body = convertBlock(/** @type {import("php-parser").Block} */ (ordinaryMethods[index].body), filename, source,
+      {...base, bindings: new Map(method.parameters.map((parameter) => [parameter.name, parameter.type])), returnType: method.returnType})
+  }
+  const nameNode = typeof node.name == "string" ? node : node.name
+
+  return withParserRanges(declaration, {name: nodeLocation(nameNode, filename, source)})
+}
+
+/**
+ * Converts one exact final readonly promoted-property PHP record.
+ * @param {import("php-parser").Class} node - PHP class declaration.
+ * @param {import("../semantic/types.js").RecordDeclaration} declaration - Predeclared nominal identity.
+ * @param {Map<string, import("../semantic/types.js").RecordDeclaration>} recordNames - Record declarations by name.
+ * @param {string} filename - Source filename.
+ * @param {string} source - Complete source.
+ * @returns {import("../semantic/types.js").RecordDeclaration} Semantic record.
+ */
+function convertPhpRecord(node, declaration, recordNames, filename, source) {
+  const location = nodeLocation(node, filename, source)
+  const generic = (declaration.typeParameters?.length ?? 0) > 0
+
+  if (node.isAnonymous || !node.isFinal || node.isReadonly == generic || node.isAbstract || node.extends || node.implements?.length ||
+    node.attrGroups.length) return unsupportedSyntax("php", "noncanonical record class modifiers", location)
+  if (node.body.length < 1 || node.body[0].kind != "method" || !generic && node.body.length != 1) {
+    return unsupportedSyntax("php", "record class body outside one constructor", nodeLocation(node.body[1] ?? node.body[0] ?? node, filename, source))
+  }
+  const constructor = /** @type {import("php-parser").Method} */ (node.body[0])
+  const typeParameterNames = new Map((declaration.typeParameters ?? []).map((parameter) => [parameter.name, parameter]))
+  const constructorName = typeof constructor.name == "string" ? constructor.name : constructor.name.name
+
+  if (constructorName != "__construct" || constructor.visibility != "public" || constructor.isStatic || constructor.isAbstract ||
+    constructor.isFinal || Reflect.get(constructor, "isReadonly") || constructor.byref || constructor.type || constructor.nullable ||
+    constructor.attrGroups.length || !constructor.body || constructor.body.children.length != 0) {
+    return unsupportedSyntax("php", "noncanonical record constructor", nodeLocation(constructor, filename, source))
+  }
+  const documented = functionDocumentedTypes(/** @type {import("php-parser").Function} */ (/** @type {unknown} */ (constructor)), filename, source)
+
+  declaration.fields = constructor.arguments.map((parameter) => {
+    const fieldLocation = nodeLocation(parameter, filename, source)
+    const name = typeof parameter.name == "string" ? parameter.name : parameter.name.name
+    const documentedType = documented.parameters.get(name)
+    const nativeType = phpTypeName(parameter.type)
+
+    if (parameter.flags != (generic ? 4 : 1) || parameter.byref || parameter.variadic || parameter.value || parameter.readonly ||
+      parameter.hooks.length || parameter.attrGroups.length) {
+      return unsupportedSyntax("php", "record field outside public promoted-property profile", fieldLocation)
+    }
+    if (nativeType == "array" && !documentedType) return missingType("php", `Record field '${name}'`, fieldLocation)
+    let type = documentedType
+      ? documentedValueType({language: "php", location: documentedType.location, ownerLocation: fieldLocation, records: recordNames,
+        source, sourceType: documentedType.sourceType, subject: `Record field '${name}'`, typeParameters: typeParameterNames})
+      : convertType(parameter.type, `Record field '${name}'`, fieldLocation, filename, source, recordNames)
+
+    if (documentedType && !phpDocumentedNativeTypeMatches(nativeType, parameter.nullable, type, recordNames)) {
+      return unsupportedSyntax("php", "documented record field type incompatible with native type", documentedType.location)
+    }
+
+    if (parameter.nullable && type.kind != "OptionalType") {
+      if (!parameter.type) return missingType("php", `Record field '${name}'`, fieldLocation)
+      type = nullableType(type, parameter.type, parameter.loc?.start.offset ?? 0, filename, source)
+    } else if (!parameter.nullable && type.kind == "OptionalType" && type.valueType.kind != "TypeVariableReference") {
+      return unsupportedSyntax("php", "optional annotation without nullable native record field", documentedType?.location ?? fieldLocation)
+    }
+    const field = {kind: /** @type {const} */ ("RecordField"), location: fieldLocation, name, type}
+    const nameNode = typeof parameter.name == "string" ? parameter : parameter.name
+
+    return withParserRanges(field, {name: nodeLocation(nameNode, filename, source)})
+  })
+  const extraDocumented = [...documented.parameters.keys()].find((name) =>
+    !constructor.arguments.some((parameter) => (typeof parameter.name == "string" ? parameter.name : parameter.name.name) == name))
+
+  if (extraDocumented || documented.returnType) return unsupportedSyntax("php", "invalid record constructor annotation", location)
+  if (generic) validatePhpGenericRecordGetters(node, declaration, recordNames, filename, source)
+  const nameNode = typeof node.name == "string" ? node : node.name
+
+  return withParserRanges(declaration, {name: nodeLocation(nameNode, filename, source)})
+}
+
+/**
+ * Validates the exact accessor half of PHP's documented generic-record profile.
+ * @param {import("php-parser").Class} node - PHP class declaration.
+ * @param {import("../semantic/types.js").RecordDeclaration} declaration - Converted record.
+ * @param {Map<string, import("../semantic/types.js").RecordDeclaration>} recordNames - Visible records.
+ * @param {string} filename - Source filename.
+ * @param {string} source - Complete source.
+ * @returns {void}
+ */
+function validatePhpGenericRecordGetters(node, declaration, recordNames, filename, source) {
+  const getters = node.body.slice(1)
+  const typeParameters = new Map((declaration.typeParameters ?? []).map((parameter) => [parameter.name, parameter]))
+
+  if (getters.length != declaration.fields.length) {
+    return unsupportedSyntax("php", "generic record getter count", nodeLocation(getters[declaration.fields.length] ?? node, filename, source))
+  }
+  getters.forEach((candidate, index) => {
+    const field = declaration.fields[index]
+
+    if (candidate.kind != "method") return unsupportedSyntax("php", "noncanonical generic record getter", nodeLocation(candidate, filename, source))
+    const getter = /** @type {import("php-parser").Method} */ (candidate)
+    const name = typeof getter.name == "string" ? getter.name : getter.name.name
+    const statement = getter.body?.children[0]
+    const returned = statement?.kind == "return" ? /** @type {import("php-parser").Return} */ (statement).expr : undefined
+    const lookup = returned?.kind == "propertylookup" ? /** @type {import("php-parser").PropertyLookup} */ (returned) : undefined
+    const receiver = lookup?.what.kind == "variable" ? /** @type {import("php-parser").Variable} */ (lookup.what) : undefined
+    const member = lookup?.offset.kind == "identifier" ? /** @type {import("php-parser").Identifier} */ (lookup.offset) : undefined
+
+    if (name != field.name || getter.visibility != "public" || getter.isStatic || getter.isAbstract || getter.isFinal ||
+      Reflect.get(getter, "isReadonly") || getter.byref || getter.arguments.length || getter.attrGroups.length ||
+      !getter.body || getter.body.children.length != 1 || receiver?.name != "this" || member?.name != field.name) {
+      return unsupportedSyntax("php", "noncanonical generic record getter", nodeLocation(getter, filename, source))
+    }
+    const documented = functionDocumentedTypes(
+      /** @type {import("php-parser").Function} */ (/** @type {unknown} */ (getter)), filename, source)
+
+    if (documented.parameters.size || documented.typeParameters || !documented.returnType) {
+      return unsupportedSyntax("php", "missing or invalid generic record getter type", nodeLocation(getter, filename, source))
+    }
+    const returnType = documentedValueType({language: "php", location: documented.returnType.location,
+      ownerLocation: nodeLocation(getter, filename, source), records: recordNames, source,
+      sourceType: documented.returnType.sourceType, subject: `Record getter '${name}'`, typeParameters})
+    const nativeType = phpTypeName(getter.type)
+
+    if (!phpDocumentedNativeTypeMatches(nativeType, getter.nullable, returnType, recordNames) ||
+      !sameValueType(returnType, field.type)) {
+      return unsupportedSyntax("php", "generic record getter type mismatch", documented.returnType.location)
+    }
+  })
 }
 
 /**
  * Converts the existing PHP if/else terminal with restricted branch prefixes.
  * @param {import("php-parser").If} node - PHP if node.
- * @param {Set<string>} visible - Enclosing visible names.
  * @param {string} filename - Source filename.
  * @param {string} source - Complete source.
+ * @param {PhpConversionContext} context - Typed conversion context.
  * @returns {import("../semantic/types.js").IfStatement} Semantic branch.
  */
-function convertIf(node, visible, filename, source) {
+function convertIf(node, filename, source, context) {
   const location = nodeLocation(node, filename, source)
 
   if (node.shortForm) return unsupportedSyntax("php", "alternative if syntax", location)
   if (node.body.kind != "block") return unsupportedSyntax("php", "if without block consequent", location)
+  if (node.test.kind == "variable") {
+    const tested = /** @type {import("php-parser").Variable} */ (node.test)
+
+    if (typeof tested.name == "string" && context.bindings.get(tested.name)?.kind == "OptionalType") {
+      return unsupportedSyntax("php", "optional truthiness condition", nodeLocation(tested, filename, source))
+    }
+  }
 
-  const consequentVisible = new Set(visible)
+  const condition = convertExpression(node.test, filename, source, context)
+  const consequentContext = {...context, bindings: new Map(context.bindings)}
+  const alternateContext = {...context, bindings: new Map(context.bindings)}
   let alternate
 
   if (node.alternate) {
-    const alternateVisible = new Set(visible)
-
     if (node.alternate.kind == "block") {
-      alternate = convertBlock(/** @type {import("php-parser").Block} */ (node.alternate), alternateVisible, filename, source)
+      alternate = convertBlock(/** @type {import("php-parser").Block} */ (node.alternate), filename, source, alternateContext)
     } else if (node.alternate.kind == "if") {
       const nested = /** @type {import("php-parser").If} */ (node.alternate)
 
       alternate = {
         kind: /** @type {const} */ ("Block"),
         location: nodeLocation(nested, filename, source),
-        statements: [convertIf(nested, alternateVisible, filename, source)]
+        statements: [convertIf(nested, filename, source, alternateContext)]
       }
     } else return unsupportedSyntax("php", `if alternate ${node.alternate.kind}`, nodeLocation(node.alternate, filename, source))
   }
 
   return {
     ...(alternate ? {alternate} : {}),
-    condition: convertExpression(node.test, filename, source),
-    consequent: convertBlock(node.body, consequentVisible, filename, source),
+    condition,
+    consequent: convertBlock(node.body, filename, source, consequentContext),
     kind: "IfStatement",
     location
   }
 }
 
+/**
+ * Converts exact braced PHP `while ($condition) { ... }` syntax.
+ * @param {import("php-parser").While} node - PHP while node.
+ * @param {string} filename - Source filename.
+ * @param {string} source - Complete source.
+ * @param {PhpConversionContext} context - Typed conversion context.
+ * @returns {import("../semantic/types.js").WhileStatement} Semantic loop.
+ */
+function convertWhile(node, filename, source, context) {
+  const location = nodeLocation(node, filename, source)
+
+  if (node.shortForm) return unsupportedSyntax("php", "alternative while syntax", location)
+  if (!node.body || node.body.kind != "block") {
+    return unsupportedSyntax("php", "while without block body", node.body ? nodeLocation(node.body, filename, source) : location)
+  }
+  const bodyContext = {...context, bindings: new Map(context.bindings)}
+
+  return withParserRanges({
+    body: convertBlock(/** @type {import("php-parser").Block} */ (node.body), filename, source, bodyContext),
+    condition: convertExpression(node.test, filename, source, context, undefined, true),
+    kind: /** @type {const} */ ("WhileStatement"),
+    location
+  }, {keyword: tokenLocation("while", node.loc?.start.offset ?? 0, node.test.loc?.start.offset ?? source.length, filename, source)})
+}
+
 /**
  * Converts a PHP echo entry point.
  * @param {import("php-parser").Echo} node - PHP echo node.
  * @param {string} filename - Source filename.
  * @param {string} source - Complete source.
+ * @param {PhpConversionContext} context - Typed 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.expressions.length != 2 || node.expressions[1].kind != "name" ||
@@ -505,7 +1884,7 @@ function convertPrint(node, filename, source) {
     return unsupportedSyntax("php", "echo without one expression and PHP_EOL", location)
   }
 
-  return {expression: convertExpression(node.expressions[0], filename, source), kind: "PrintStatement", location}
+  return {expression: convertExpression(node.expressions[0], filename, source, context), kind: "PrintStatement", location}
 }
 
 /**
@@ -513,29 +1892,118 @@ 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, 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 parsePhp({filename, source}) {
+export function parsePhp({capabilities = [], filename, source, program: programContext}) {
   const program = parsePhpProgram(filename, source)
   validateDeclareNodes(program.children, filename, source)
-  const functions = program.children.filter((node) => node.kind == "function")
-    .map((node) => convertFunction(/** @type {import("php-parser").Function} */ (node), filename, source))
-  const executableNodes = program.children.filter((node) => node.kind != "function" && node.kind != "declare" && node.kind != "noop")
+  let body = task034PhpBody(program.children, capabilities, filename, source)
+
+  if (programContext) {
+    inspectPhpModule({filename, source})
+    const namespace = /** @type {import("php-parser").Namespace} */ (body.find((node) => node.kind == "namespace"))
+
+    body = namespace.children.filter((node) => node.kind != "usegroup" && !isPhpRequireOnce(node))
+  }
+  const classNodes = /** @type {import("php-parser").Class[]} */ (body.filter((node) => node.kind == "class"))
+  const errorNodes = classNodes.filter((node) => node.extends?.kind == "name" &&
+    ["RuntimeException", "\\RuntimeException"].includes(node.extends.name))
+  const referenceClassNodes = classNodes.filter((node) => !errorNodes.includes(node) &&
+    node.body.some((member) => member.kind == "propertystatement"))
+  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: typeof node.name == "string" ? node.name : node.name.name
+  }))
+  const recordDeclarations = recordNodes.map((node, index) => {
+    const id = `record:${index}`
+    const typeParameters = classDocumentedTypeParameters(node, id, filename, source)
+
+    return {
+      fields: [],
+      id,
+      kind: /** @type {const} */ ("RecordDeclaration"),
+      location: nodeLocation(node, filename, source),
+      name: typeof node.name == "string" ? node.name : node.name.name,
+      ...(typeParameters ? {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: typeof node.name == "string" ? node.name : node.name.name
+  }))
+  const recordNames = /** @type {Map<string, import("../semantic/types.js").RecordDeclaration | import("../semantic/types.js").ClassDeclaration | import("../semantic/types.js").EffectResourceDeclaration>} */ (
+    new Map(programContext?.records ?? []))
+  for (const resource of capabilities.flatMap(({resources}) => resources)) recordNames.set(resource.name, resource)
+  const errorNames = new Map(programContext?.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) => convertPhpError(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([...recordNames.values()]
+    .filter((declaration) => declaration.kind == "RecordDeclaration")
+    .map((declaration) => [/** @type {string} */ (declaration.id), declaration]))
+  const classesById = new Map(classDeclarations.map((declaration) => [/** @type {string} */ (declaration.id), declaration]))
+  const records = recordNodes.map((node, index) => convertPhpRecord(node, recordDeclarations[index],
+    /** @type {Map<string, import("../semantic/types.js").RecordDeclaration>} */ (/** @type {unknown} */ (recordNames)), filename, source))
+  const functionNodes = /** @type {import("php-parser").Function[]} */ (body.filter((node) => node.kind == "function"))
+  const signatures = functionNodes.map((node, index) => convertFunctionSignature(node, filename, source, recordNames, `function:${index}`))
+  const functionSignatures = new Map([...capabilityFunctionSignatures(capabilities, moduleLocation(filename, source)),
+    ...(programContext?.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 classes = referenceClassNodes.map((node, index) => convertPhpReferenceClass(node, classDeclarations[index],
+    recordNames, recordsById, classesById, functionSignatures, errorNames, errorsById, filename, source))
+  const functions = functionNodes.map((node, index) =>
+    convertFunction(node, signatures[index], functionSignatures, recordNames, recordsById, classesById, errorNames, errorsById,
+      filename, source))
+  const executableNodes = body.filter((node) => !["class", "function", "declare", "noop"].includes(node.kind))
   const location = moduleLocation(filename, source)
 
-  if (functions.length == 0) return unsupportedSyntax("php", "module without a function", location)
+  if (programContext && !programContext.isEntry && executableNodes.length > 0) {
+    return unsupportedSyntax("php", "top-level side effect outside the selected entry module", nodeLocation(executableNodes[0], filename, source))
+  }
   const first = executableNodes[0]
   const last = executableNodes.at(-1) ?? first
   const entryLocation = first
     ? locationFromOffsets(filename, source, first.loc?.start.offset ?? 0, last?.loc?.end.offset ?? source.length)
     : location
-  const entryVisible = new Set()
+  const entryContext = {
+    bindings: new Map(),
+    classes: classesById,
+    errorNames,
+    errors: errorsById,
+    functions: functionSignatures,
+    orderedMapDeclarations: orderedMapDeclarationsForPhp(executableNodes),
+    recordNames,
+    records: recordsById,
+    returnType: undefined
+  }
   const entryBlock = {
     kind: /** @type {const} */ ("Block"),
     location: entryLocation,
-    statements: executableNodes.map((node) => convertStatement(node, entryVisible, filename, source))
+    statements: executableNodes.map((node) => convertStatement(node, filename, source, entryContext))
   }
 
+  if (!programContext && functions.length == 0 && capabilities.length == 0 && !blockReferencesProtectedEntry(entryBlock)) {
+    return unsupportedSyntax("php", "module without a function", location)
+  }
   return {
     entryPoint: {
       body: entryBlock,
@@ -544,10 +2012,156 @@ export function parsePhp({filename, source}) {
     },
     functions,
     kind: "Module",
-    location
+    location,
+    ...(errors.length > 0 ? {errors} : {}),
+    ...(classes.length > 0 ? {classes} : {}),
+    ...(records.length > 0 ? {records} : {})
   }
 }
 
+/**
+ * Removes exact protected PHP probe support before portable conversion.
+ * @param {import("php-parser").Statement[]} body - Parsed top-level statements.
+ * @param {readonly import("../semantic/types.js").EffectCapabilityDeclaration[]} capabilities - Authorized declarations.
+ * @param {string} filename - Source filename.
+ * @param {string} source - Complete source.
+ * @returns {import("php-parser").Statement[]} Portable statements.
+ */
+function task034PhpBody(body, capabilities, filename, source) {
+  if (!isTask034ResourceProbe(capabilities)) return body
+  const start = body.findIndex((node) => node.leadingComments?.some(({value}) => value == "/* semantifold-task034-support */"))
+
+  if (start < 0) return body
+  if (!hasExactEffectSupport(source, "php")) {
+    return unsupportedSyntax("php", "malformed protected Task 034 support", nodeLocation(body[start], filename, source))
+  }
+  const expected = [
+    ["class", "ProbeOperationFailure"], ["class", "ProbeAcquireFailure"], ["class", "ProbeReadFailure"],
+    ["class", "ProbeCloseFailure"], ["class", "ProbeResourceClosed"], ["class", "ProbeResource"],
+    ["expressionstatement", undefined], ["function", "probeEffect"], ["function", "probeAcquire"],
+    ["function", "probeRead"], ["function", "probeClose"], ["function", "probeTrace"]
+  ]
+  const matches = expected.every(([kind, name], index) => {
+    const node = body[start + index]
+    const rawName = node ? Reflect.get(node, "name") : undefined
+    const actualName = typeof rawName == "string" ? rawName : rawName && typeof rawName == "object" ? Reflect.get(rawName, "name") : undefined
+    return node?.kind == kind && actualName == name
+  })
+  const next = body[start + expected.length]
+
+  if (!matches || next && !next.leadingComments?.some(({value}) => value == "/* semantifold-task034-support-end */")) {
+    return unsupportedSyntax("php", "malformed protected Task 034 support", nodeLocation(body[start], filename, source))
+  }
+  return [...body.slice(0, start), ...body.slice(start + expected.length)]
+}
+
+/**
+ * Reads the canonical parser-owned PHP namespace, use bindings, and literal require_once edges.
+ * @param {object} input - Parser input.
+ * @param {string} input.filename - Source filename.
+ * @param {string} input.source - Source text.
+ * @returns {{bindings: {importedName: string, localName: string, location: import("../semantic/types.js").SourceLocation, nativeName: string, symbolKind: import("../semantic/types.js").SemanticDeclarationKind, typeOnly: false}[], imports: {importedName: string, localName: string, location: import("../semantic/types.js").SourceLocation, namespace: true, pathLocation: import("../semantic/types.js").SourceLocation, specifier: string, typeOnly: false}[], exports: {exportedName: string, localName: string, location: import("../semantic/types.js").SourceLocation, typeOnly: false}[], nativeName: string}} Parser-owned PHP module header.
+ */
+export function inspectPhpModule({filename, source}) {
+  const program = parsePhpProgram(filename, source)
+
+  validateDeclareNodes(program.children, filename, source)
+  const namespaces = program.children.filter((node) => node.kind == "namespace")
+  const invalidOuter = program.children.find((node) => !["declare", "namespace", "noop"].includes(node.kind))
+  const namespace = /** @type {import("php-parser").Namespace | undefined} */ (namespaces[0])
+
+  if (!namespace || namespaces.length != 1 || namespace.withBrackets || typeof namespace.name != "string" || invalidOuter) {
+    return unsupportedSyntax("php", "one canonical unbracketed namespace",
+      nodeLocation(invalidOuter ?? namespaces[1] ?? namespace ?? program, filename, source))
+  }
+  const bindings = []
+
+  for (const node of namespace.children.filter((child) => child.kind == "usegroup")) {
+    const group = /** @type {import("php-parser").UseGroup} */ (node)
+
+    if (group.name !== null || ![null, "function"].includes(group.type) || group.items.length == 0) {
+      return unsupportedSyntax("php", "grouped, constant, or empty use declaration", nodeLocation(group, filename, source))
+    }
+    for (const item of group.items) {
+      if (item.type !== null || typeof item.name != "string" || !item.name.includes("\\")) {
+        return unsupportedSyntax("php", "grouped or unqualified use item", nodeLocation(item, filename, source))
+      }
+      const importedName = item.name.split("\\").at(-1)
+      const alias = item.alias
+
+      if (!importedName || alias && alias.kind != "identifier") {
+        return unsupportedSyntax("php", "invalid use alias", nodeLocation(item, filename, source))
+      }
+      bindings.push({
+        importedName,
+        localName: alias ? alias.name : importedName,
+        location: nodeLocation(item, filename, source),
+        nativeName: item.name,
+        symbolKind: /** @type {import("../semantic/types.js").SemanticDeclarationKind} */ (group.type == "function" ? "function" : "record"),
+        typeOnly: /** @type {const} */ (false)
+      })
+    }
+  }
+  const imports = namespace.children.filter(isPhpIncludeStatement).map((node) => {
+    if (!isPhpRequireOnce(node)) {
+      return unsupportedSyntax("php", "include/require outside literal require_once __DIR__ profile", nodeLocation(node, filename, source))
+    }
+    const statement = /** @type {import("php-parser").ExpressionStatement} */ (node)
+    const include = /** @type {import("php-parser").Include} */ (statement.expression)
+    const target = /** @type {import("php-parser").Bin} */ (include.target)
+    const path = /** @type {import("php-parser").String} */ (target.right)
+
+    if (!path.value.startsWith("/") || path.value.includes("\0")) {
+      return unsupportedSyntax("php", "unsafe require_once path", nodeLocation(path, filename, source))
+    }
+
+    return {
+      importedName: "*",
+      localName: "",
+      location: nodeLocation(node, filename, source),
+      namespace: /** @type {const} */ (true),
+      pathLocation: nodeLocation(path, filename, source),
+      specifier: `.${path.value}`,
+      typeOnly: /** @type {const} */ (false)
+    }
+  })
+  const exports = namespace.children.flatMap((node) => {
+    if (node.kind != "class" && node.kind != "function") return []
+    const declaration = /** @type {import("php-parser").Class | import("php-parser").Function} */ (node)
+    const name = typeof declaration.name == "string" ? declaration.name : declaration.name.name
+
+    return [{exportedName: name, localName: name, location: nodeLocation(node, filename, source), typeOnly: /** @type {const} */ (false)}]
+  })
+
+  return {bindings, exports, imports, nativeName: namespace.name}
+}
+
+/**
+ * Reports whether a PHP statement is any include/require expression.
+ * @param {import("php-parser").Node} node - Candidate statement.
+ * @returns {boolean} Whether the node is an include expression statement.
+ */
+function isPhpIncludeStatement(node) {
+  return node.kind == "expressionstatement" &&
+    /** @type {import("php-parser").ExpressionStatement} */ (node).expression.kind == "include"
+}
+
+/**
+ * Reports whether a PHP statement is the canonical literal project load edge.
+ * @param {import("php-parser").Node} node - Candidate statement.
+ * @returns {boolean} Whether the node is a supported require-once statement.
+ */
+function isPhpRequireOnce(node) {
+  if (!isPhpIncludeStatement(node)) return false
+  const statement = /** @type {import("php-parser").ExpressionStatement} */ (node)
+  const include = /** @type {import("php-parser").Include} */ (statement.expression)
+  const target = include.target.kind == "bin" ? /** @type {import("php-parser").Bin} */ (include.target) : undefined
+  const left = target?.left.kind == "magic" ? /** @type {import("php-parser").Magic} */ (target.left) : undefined
+
+  return include.once && include.require && target?.type == "." &&
+    left?.value == "__DIR__" && target.right.kind == "string"
+}
+
 /**
  * Accepts only an optional single `declare(strict_types=1)` directive.
  * @param {import("php-parser").Node[]} nodes - Top-level PHP nodes.
@@ -588,6 +2202,38 @@ function parsePhpProgram(filename, source) {
   try {
     return parser.parseCode(source, filename)
   } catch (error) {
-    return parseFailure("php", error)
+    return parseFailure("php", error, phpParserFailureLocation(error, filename, source))
+  }
+}
+
+/**
+ * Normalizes php-parser's one-based line and zero-based column when present.
+ * A module range remains the deterministic fallback for opaque parser errors.
+ * @param {unknown} error - Native parser error.
+ * @param {string} filename - Requested source filename.
+ * @param {string} source - Complete source.
+ * @returns {import("../semantic/types.js").SourceLocation} Failure range.
+ */
+function phpParserFailureLocation(error, filename, source) {
+  if (!error || typeof error != "object") return moduleLocation(filename, source)
+  const line = Reflect.get(error, "lineNumber")
+  const column = Reflect.get(error, "columnNumber")
+
+  if (typeof line != "number" || !Number.isSafeInteger(line) || line < 1 ||
+    typeof column != "number" || !Number.isSafeInteger(column) || column < 0) {
+    return moduleLocation(filename, source)
   }
+  let lineStart = 0
+
+  for (let current = 1; current < line; current++) {
+    const newline = source.indexOf("\n", lineStart)
+
+    if (newline < 0) return moduleLocation(filename, source)
+    lineStart = newline + 1
+  }
+  const lineEnd = source.indexOf("\n", lineStart)
+  const boundedEnd = lineEnd < 0 ? source.length : lineEnd
+  const offset = Math.min(lineStart + column, boundedEnd)
+
+  return locationFromOffsets(filename, source, offset, Math.min(offset + 1, source.length))
 }