Add support for type annotations (old) by PiIsRational · Pull Request #3992 · KeYProject/key

PiIsRational · 2026-10-06T13:26:46Z

Intended Change

The Goal of this Pull Request is to be able to use Java Type Annotations in Taclets.
To make this work the Type Annotations were added to the KeY Ast at the TypeReference level.
The annotations were added to the type references, since they correspond to the syntactical
version of the types. Since in most places KeYJavaTypes were used, there was the need
to replace them.

The default matching behaviour was not altered and is compatible with the current
master branch. This means that there is no semantic difference between Object o
and @Rep Object o. Therefore, no taclets need to be altered and annotations are simply
ignored per default.

To interact with annotations in taclets there are currently 3 variable conditions:

hasAnnotation(SchemaVariable variable, String annot):
It checks that the type (TypeReference) of variable has an annotation whose
fully qualified name matches annot. It supports ProgramVariables, New
(simple constuctor calls) and Fields.
addAnnotation(SchemaVariable store, SchemaVariable read, String annot):
It creates a copy of read and stores in store except that the last annotation
of the type of store now corresponds to annot. If the given string annot does
not match an annotation, the variable condition fails.
It supports ProgramVariables and New (simple constructor calls).
removeAnnotation(SchemaVariable store, SchemaVariable read, String annot):
It creates a copy of read where all annotations of the type of read
with the fully qualified name matching annot are removed and stores it in store.
This variable condition matches always and only supports New (simple constructor calls).

Currently only, Marker annotations so annotations with no arguments
(such as @NonNull or @Rep) are supported.

Example

In the context of a Nullness type system (where the @NonNull) annotation
is type checked we could have something like the following snippet:

import checker.qual.NonNull;

/*@ normal_behaviour
  @ ensures o != null; */
public Object id(@NonNull Object o) {
    return o;
}

To be able to use the guarantee expressed by the annotation we could write the following
Taclet:

nonNull {
    \schemaVar \term Object o;

    \find(o)
    \varcond(\hasAnnotation(o, checker.qual.NonNull))

    \add(o != null)
}

A further (similar) example can be found here.
The main use of this change is PR #3724 and can be found here (mainly in universeDefs.key).

Plan

Add tests for the variable conditions
Add documentation

Type of pull request

New feature (non-breaking change which adds functionality)
There are changes to the (Java) code

Ensuring quality

I made sure that introduced/changed code is well documented (javadoc and inline comments).
(I made sure that new/changed end-user features are well documented (https://github.com/KeYProject/key-docs).)
I added new test case(s) for new functionality.
I have tested the feature as follows:
- I made use of it in Universe Type Rules #3724

Additional information and contact(s)

@WolframPfeifer is involved in this Pull Request

The contributions within this pull request are licensed under GPLv2 (only) for inclusion in KeY.

…ration

wadoon · 2026-10-06T20:49:43Z

I have a stupid questions:

Does this impact KeyJavaType?
Is @NonNull <: @Nullable T? Or do we ignore annotations on type and sort hierarchy?
Why is KeyJavaType replaced by TypeReference? They have different purposes; the first one is semantical, the later one is syntactical.

wadoon · 2026-10-08T18:25:22Z

Review: PR #3992 — “Add support for type annotations”

Repo: KeYProject/key
Author: PiIsRational (@PiIsRational), WolframPfeifer involved
State: draft, OPEN, milestone v3.1.0
Scope: 142 files, +1561 / −8854 (net-negative due to ~20 deleted/regenerated example .proof files)
Head branch: key-annotations (commits 230f842d…d563cb17, 69 commits vs main)
Build check on branch head: ./gradlew compileJava compileTestJava → BUILD SUCCESSFUL

Summary

The PR reads type annotations from Java sources, stores them in TypeReferences (not KeYJavaTypes), and exposes them via three new variable conditions: \hasAnnotation, \addAnnotation, \removeAnnotation. To make annotations reachable on variables, KeYJavaType is replaced by TypeReference in ProgramVariable/LocationVariable and in most places that construct or copy typed program elements (metaconstructs, contract builders, WD/infoflow modules, tests).

The mechanical part of the refactor is careful and consistent; everything compiles, including the test sources. The new logic in the annotation path has several correctness problems that should be fixed before merge.

High severity

1. `TypeReferenceImp.match` is logically inverted (broken program matching)

key.core/src/main/java/de/uka/ilkd/key/java/ast/reference/TypeReferenceImp.java:253-263

public MatchConditions match(SourceData source, MatchConditions matchCond) {
    final ProgramElement pe = source.getSource();

    if (pe instanceof TypeReference tr
            && tr.getDimensions() == getDimensions()
            && tr.getAnnotations().equals(getAnnotations())) {
        return null;      // <- `null` means MATCH FAILED
    }

    return super.match(source, matchCond);
}

The upstream version (main) fails the match only when the source is not a type reference or the dimensions differ:

if (!(pe instanceof TypeReference)
        || ((TypeReference) pe).getDimensions() != getDimensions()) {
    return null;
}
return super.match(source, matchCond);

The new code does the opposite: it fails the match exactly when the source is a matching type reference (same dims and same annotations) and delegates to super.match in all other cases — where super (class equality + children) does not compare annotations at all. Therefore:

a plain pattern type ref matched against a plain source type ref → always fails via the monolithic matcher;
a pattern with different annotations than the source → falls through to super.match and may succeed.

The intended change was to extend the guard, i.e. || !tr.getAnnotations().equals(getAnnotations()) inside the existing failure condition. Fix and add a unit test exercising the monolithic match path (e.g. a \program pattern containing a type ref).

2. `Annotation.equals` always returns `false`

key.core/src/main/java/de/uka/ilkd/key/java/ast/Annotation.java:31

return o instanceof Annotation annot
        ? annot.type.equals(type) && super.equals(type)
        : false;

super.equals(type) passes the KeYJavaType into JavaNonTerminalProgramElement.equals, which immediately rejects it with o.getClass() != this.getClass(). Hence the second conjunct is always false, and two structurally identical marker annotations (same annotation type) are never equal. Consequences:

ImmutableList.equals on annotation lists (used in the match above and anywhere annotations are compared) never matches for non-empty lists;
deduplication / set semantics for annotations are broken;
no hashCode override either (inherited one is class-only), so equality and hash are inconsistent with the class hierarchy.

Should be super.equals(annot) (plus a hashCode).

3. Only marker annotations are supported; annotations with arguments abort loading

key.core/src/main/java/de/uka/ilkd/key/java/loader/JP2KeYConverter.java:2112-2119

public Object visit(NormalAnnotationExpr n, Void arg) { return reportUnsupportedElement(n); }
public Object visit(SingleMemberAnnotationExpr n, Void arg) { return reportUnsupportedElement(n); }

reportUnsupportedElement throws JavaBuildingExceptions. So any type annotation with members — @Size(min = 1), @Nullable(reason = "..."), @Target(ElementType.TYPE_USE) used as value — fails the whole parse. At the same time, declaration annotations on fields/methods (@Override, @SuppressWarnings("..."), @Deprecated(since = "...")) are silently dropped, because visit(FieldDeclaration)/visit(MethodDeclaration) never visit getAnnotations().

Given that annotations are the core feature here, the marker-only limitation (and the hard failure) should at least be documented and ideally handled gracefully (skip + warning) instead of throwing.

Medium severity

4. `AnnotationMover` misses single-value `@Target(TYPE_USE)`

key.core/src/main/java/de/uka/ilkd/key/java/transformations/pipeline/AnnotationMover.java:95-120
isTypeAnnotationSlow only recognizes the target when the annotation value is an ArrayInitializerExpr (@Target({ElementType.TYPE_USE})). The very common shorthand @Target(ElementType.TYPE_USE) is a SingleMemberAnnotationExpr with a name expression → silently classified as not a type annotation → not moved → dropped by the converter.

5. `AnnotationMover` caches by simple name

AnnotationMover.java:90-91 — typeAnnotationMap is keyed by the annotation’s simple name; two distinct annotations with the same simple name in different packages poison the cache in both directions. Additionally, d.getParentNode().get() and annot.setParentNode(type) are manual javaparser AST manipulations that are easy to get out of sync; a comment on the intended AST invariant would help.

6. `AddAnnotation.build()` may create `MarkerAnnotation(null)`

key.core/src/main/java/de/uka/ilkd/key/rule/conditions/AddAnnotation.java:122
services.getJavaInfo().getTypeByName(annot) returns null for unknown names; the resulting null-typed annotation NPEs later in toString / pretty printer / HasAnnotationCondition.matchesTypeAnnots (getKeyJavaType().getFullName()). Validate the annotation name up front with a meaningful error.

7. `HasAnnotationCondition` compares a sort by its string name

key.core/src/main/java/de/uka/ilkd/key/rule/conditions/HasAnnotationCondition.java:33-47
variable.sort().toString().equals("Field") — use the Field sort constant (HeapLDT / JavaDLTheory) instead of a name-string comparison.

8. Inconsistent annotation matching between the two matchers

key.core/src/main/java/de/uka/ilkd/key/rule/match/vm/JavaProgramMatchPlanBuilder.java (typeReferencePlan), unchanged by this PR, guards only instanceof TypeReference + dimensions and ignores annotations, while the (broken) TypeReferenceImp.match above tries to compare them. Annotated types therefore match differently depending on the matcher path. If annotations are part of a type use’s identity, typeReferencePlan’s guard needs the same annotations check.

9. Annotations are not part of the AST child structure; `TypeRef` equality ignores them

key.core/src/main/java/de/uka/ilkd/key/java/ast/reference/TypeReferenceImp.java — getChildCount/getChildAt cover only prefix + name, so JavaNonTerminalProgramElement.equals/hashCode treat TypeRef(@A C) and TypeRef(C) as equal. Combined with #1 and #2, annotation-related equality semantics are inconsistent across equals, match, and the VM guard. Choose one semantics and make all three agree.

10. `ProgramVariable.getReferencePrefix()` changed from `null` to the type ref’s prefix

key.core/src/main/java/de/uka/ilkd/key/logic/op/ProgramVariable.java
Previously “we do not have a prefix, so fake it → null”; now return type.getReferencePrefix();. Every LocationVariable built from new TypeRef(kjt) therefore has a (package) reference prefix where it previously had none, changing ReferenceSuffix/parsing behavior for chains like a.b. Additionally getKeYJavaType() is now null-capable (type != null ? type.getKeYJavaType() : null) while proofToString() dereferences it without a null check. Verify this does not change how a.b is parsed/matched, or add a regression test.

Low / nits

RemoveAnnotation.toString() prints \addAnnotation (copy-paste bug, RemoveAnnotation.java:115); its constructor throws RuntimeException while AddAnnotation/HasAnnotationCondition use IllegalArgumentException.
New classes lack javadoc / class documentation: Annotation, MarkerAnnotation, AnnotationInterfaceMemberDeclaration. The javadoc of TypeRef now references a non-existent ImmutableList<AnnotationExpression> type.
Package layout: Annotation lives in ...java.ast, but MarkerAnnotation in ...java.ast.annotation — inconsistent.
Naming: HasAnnotationCondition vs AddAnnotation/RemoveAnnotation — inconsistent “Condition” suffix.
The varcond annotation-name argument is a plain string; only simple names are demonstrated. For non-default packages the FQN must be spelled out — worth documenting or resolving via the symbol table.

Examples / shipped files

~20 user-facing example proofs were deleted (key.ui/examples/heap/observer/*.key.proof, pred_log/specialNat.key.proof, equalities2.key.proof). If they no longer replay because of the refactor, regenerate rather than delete — these ship in the UI. Also pred_log/count.key.proof was renamed to standard_key/unicode_test.key.proof; count.key does not exist, so verify the renamed proof actually replays for unicode_test.key.
New test surface is thin: the PR’s own checklist (“Add tests for the variable conditions”) is still open. There is one g.provable("Java/Annotations/test_annotation.key") entry and the annotation-declaration coverage-load test (AnnDecl.java — @interface + a @Marker(3) single-member annotation). No unit tests for AddAnnotation/RemoveAnnotation/HasAnnotationCondition, no pretty-printer round-trip with annotations, no tests for @Target variants or annotated arrays/generics.

Answers to the design questions in the PR thread

Regarding @wadoon’s questions (and the general KeYJavaType vs TypeReference concern):

KeYJavaType impact: minimal — it remains the semantic anchor (TypeRef still resolves to the same KJT; getDefaultValue merely became @Nullable). The refactor moves type-use information out of it.
Are annotations part of the sort/hierarchy? No: annotations are inert w.r.t. sorts and subtyping; \hasAnnotation is a purely syntactic check on the type reference, and the demo unsound.key shows that the semantic content is whatever the rule author gives it.
Why TypeReference for ProgramVariable? Justified by the goal — annotations live on syntactically annotated type uses, not on the resolved type. The trade-off: ProgramVariable is a logic-level name, and its behavior surface (getReferencePrefix, null-capable getKeYJavaType, name-only equality) changes as a result; findings KeY / Recoder transforms JML set statments for ghost variables wrongly #1/<deleted> #9/<deleted> #10 are exactly where this shows up.

Conclusion / requested changes

The refactor itself is clean and compiles, but before this goes much further:

Fix the inverted TypeReferenceImp.match (KeY / Recoder transforms JML set statments for ghost variables wrongly #1).
Fix Annotation.equals (+ hashCode) (<deleted> #2).
Decide the behavior for annotations with arguments and declaration annotations (fail vs. skip + warning) and document the marker-only scope (<deleted> #3).
Add unit tests for the three variable conditions and the matcher path.

If you want, this review can be posted (full or condensed) to the PR via gh.

Zeilen 1-148

WolframPfeifer

As discussed in a direct meeting, this is (some of) the feedback that I have.

WolframPfeifer · 2026-10-07T10:28:02Z

@@ -40,6 +41,11 @@ public abstract class TypeReferenceImp extends JavaNonTerminalProgramElement
     */
    protected final ProgramElementName name;

+    /**
+     * Annotations.


This is not a helpful JavaDoc. In such a case, preferably add some description/examples (@Nullable, @NonNull, @Rep, @Peer), or remove the JavaDoc.

WolframPfeifer · 2026-10-07T10:30:57Z

-        if (!(pe instanceof TypeReference)
-                || ((TypeReference) pe).getDimensions() != getDimensions()) {
+
+        if (pe instanceof TypeReference tr


Before this PR, if pe was not instance of TypeReference, null would be returned. Now, super.match is called. Is this intentional? Does it have the desired behavior?

WolframPfeifer · 2026-10-07T10:37:42Z

@@ -295,6 +294,8 @@ private MethodDeclaration createInitializeMethod(TypeDeclaration<?> td) {
     */
    @Override
    public void apply(TypeDeclaration<?> td) {
+        if (td.isAnnotationDeclaration())
+            return;


Why do we return early in this case?

WolframPfeifer · 2026-10-07T10:37:51Z

@@ -159,6 +158,8 @@ private MethodDeclaration createPrepareMethod(TypeDeclaration<?> td) {
     *        the TypeDeclaration
     */
    public void apply(TypeDeclaration<?> td) {
+        if (td.isAnnotationDeclaration())
+            return;


Why do we return early in this case?

WolframPfeifer · 2026-10-07T10:54:29Z

@@ -109,6 +109,12 @@ application {
    mainClass.set("de.uka.ilkd.key.core.Main")
 }

+java {
+    toolchain {
+        languageVersion = JavaLanguageVersion.of(21)


Is this needed?

WolframPfeifer · 2026-10-07T10:56:18Z

-     \forall int x; (p(x) -> p(add(x, Z(1(#)))))
-   & p(Z(0(#)))
-> p(Z(2(#)))
+\forall int x; true & !false


Something is weird here. Git detected a renaming, but I think it is actually a deletion + change.
Why are many *.proof files deleted?

PiIsRational · 2026-10-22T12:32:02Z

Regarding the First Review i followed all points except point 3. So the behaviour of KeY remains fully for annotations that are not Marker Annotations.

PiIsRational · 2026-10-22T13:04:27Z

This PR gets replaced by #3996

PiIsRational added 30 commits June 1, 2025 18:30

add the ownership rules

230f842

added the new rules

6a195dd

extend the javac extension

415f9db

change the way the universe rules are treated

f37d143

update to add the latest changes

c337d49

do some bugfixes in the recoder parsers

82f0bcc

the last changes

912cc8c

update the match conditions

94763f1

add support for args and results in contracts

19f98e9

some changes

0d932a9

the new rule files

a82c2c2

add the proofs

2f35dcf

update the rules

85a0e6d

remove unneeded assertion

902c17c

remove logs in the default lemma generator

3f0dea8

all the universe lemmas have a corresponding runnable proof

29dabd9

remove factorypaths

ac9124d

add support for dom references

88187a0

Merge commit '88187a0debb466f31e974a64e2049293160d7319' into ut-integ…

4812836

…ration

update the heuristics

16e29d2

update the heap simplification macro with universe rules

519a11c

apply spotless

2cb864d

Merge branch 'main' into ut-integration

33d1e5e

refactoring

eae3d25

a first try with the new parser

86d605e

a minor change

23d12f4

tried to get types to wor

67995b6

add annotations to type references

8bc0407

try to get Annotation Declarations to properly load

bbd5a1b

Merge branch 'main' into ut-integration

0ab2931

PiIsRational added 13 commits July 8, 2026 11:10

add back proof files

6cd0ba1

the conract adder works!

32a9fa5

Merge branch 'main' into ut-integration

8555978

make the annotation interface member be a real member declaration

cf12853

move to ImmutableList

04eaa6b

fix the lemma proofs

7efd1f4

remove unused axiom from the rules

87ff5cd

Merge branch 'main' into ut-integration

130626b

cleanup

6e737e4

move the annotation-declaration test and some cleanup

c5a911e

remove the limiting

f9c48b7

remove universe specific constructs

fd803b1

add the annotation mover

e48ebe6

PiIsRational mentioned this pull request Oct 6, 2026

Universe Type Rules #3724

Draft

2 of 6 tasks

PiIsRational added 2 commits October 6, 2026 15:53

Merge branch 'main' into key-annotations

be00d55

fix the pipeline tests

1fe8020

wadoon assigned PiIsRational Oct 6, 2026

wadoon added the Prover Core label Oct 6, 2026

wadoon added this to the v3.1.0 milestone Oct 6, 2026

add the small annotation test

d563cb1

cleanup

ade91f0

WolframPfeifer requested changes Oct 21, 2026

View reviewed changes

minor last changes

b0e956d

Merge branch 'main' into key-annotations

673d4de

PiIsRational changed the title ~~Add support for type annotations~~ Add support for type annotations (old) Oct 22, 2026

PiIsRational closed this Oct 22, 2026

Navigation Menu

Repository navigation

Add support for type annotations (old) - #3992

Add support for type annotations (old)#3992
PiIsRational wants to merge 72 commits into
KeYProject:mainfrom
PiIsRational:key-annotations

PiIsRational commented Oct 6, 2026 •

edited

Loading

Uh oh!

wadoon commented Oct 6, 2026

Uh oh!

wadoon commented Oct 8, 2026

Uh oh!

WolframPfeifer left a comment

Uh oh!

Uh oh!

WolframPfeifer Oct 7, 2026

Uh oh!

WolframPfeifer Oct 7, 2026

Uh oh!

Uh oh!

Uh oh!

WolframPfeifer Oct 7, 2026

Uh oh!

WolframPfeifer Oct 7, 2026

Uh oh!

Uh oh!

WolframPfeifer Oct 7, 2026

Uh oh!

WolframPfeifer Oct 7, 2026

Uh oh!

PiIsRational commented Oct 22, 2026

Uh oh!

PiIsRational commented Oct 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

PiIsRational commented Oct 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Intended Change

Example

Plan

Type of pull request

Ensuring quality

Additional information and contact(s)

Uh oh!

wadoon commented Oct 6, 2026

Uh oh!

wadoon commented Oct 8, 2026

Review: PR #3992 — “Add support for type annotations”

Summary

High severity

1. TypeReferenceImp.match is logically inverted (broken program matching)

2. Annotation.equals always returns false

3. Only marker annotations are supported; annotations with arguments abort loading

Medium severity

4. AnnotationMover misses single-value @Target(TYPE_USE)

5. AnnotationMover caches by simple name

6. AddAnnotation.build() may create MarkerAnnotation(null)

7. HasAnnotationCondition compares a sort by its string name

8. Inconsistent annotation matching between the two matchers

9. Annotations are not part of the AST child structure; TypeRef equality ignores them

10. ProgramVariable.getReferencePrefix() changed from null to the type ref’s prefix

Low / nits

Examples / shipped files

Answers to the design questions in the PR thread

Conclusion / requested changes

Uh oh!

WolframPfeifer left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

WolframPfeifer Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

WolframPfeifer Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

WolframPfeifer Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

WolframPfeifer Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

WolframPfeifer Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

WolframPfeifer Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

PiIsRational commented Oct 22, 2026

Uh oh!

PiIsRational commented Oct 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

PiIsRational commented Oct 6, 2026 •

edited

Loading

1. `TypeReferenceImp.match` is logically inverted (broken program matching)

2. `Annotation.equals` always returns `false`

4. `AnnotationMover` misses single-value `@Target(TYPE_USE)`

5. `AnnotationMover` caches by simple name

6. `AddAnnotation.build()` may create `MarkerAnnotation(null)`

7. `HasAnnotationCondition` compares a sort by its string name

9. Annotations are not part of the AST child structure; `TypeRef` equality ignores them

10. `ProgramVariable.getReferencePrefix()` changed from `null` to the type ref’s prefix