semantifold 0.13.0 → 0.14.0

package/src/language-registry.js

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

package/src/mapping.js

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

package/src/semantic/effects.js

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

package/src/semantic/provenance.js

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

package/src/semantic/types.js

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