feat(metamodel): observed-schema and diff contracts

[jimador]

PR 3 of the metamodel train, stacked on #84. This slice defines the two comparisons the governance loop runs on. ObservedSchema/ObservedSchemaSource is the SPI a storage backend implements to report what a live graph actually contains — names only, since a graph exposes labels and relationship types without signatures. MetamodelDiff/MetamodelChange is a sealed change taxonomy: a property that kept its name and changed type, cardinality or kind reports as one PropertySignatureChanged entry. MetamodelDiffer compares two declared versions; DeclaredObservedDiffer compares a declaration against the graph. Declared renames pair in the diff (EXPERIMENTAL): EntityTypeRenamed, PropertyRenamed and EntityTypeAliasesChanged are new sealed members, pairing is one-to-one on the residual sets after name matching, comparison substitutes old-for-new in reference targets and label sets only, and a pure rename yields one change. Accumulated former names join the declared side of the observed diff, so old-labeled data under a declared rename is never drift.

Changed in this review round:

• Declared and observed types compare by own label. JvmType.name is a fully qualified class name while the graph reports simple labels, so a healthy FQN schema previously came back both unobserved and drifted at once. DeclaredSchema.entityTypeOwnLabels (via DeclaredSchema.ownLabelOf) fixes both directions; reported spellings stay as the stamp declares them.
• Known-but-ungoverned types stay out of observed drift, covering their own labels too.
• Contested rename claims report as such; the differ never picks a winner silently.
• TypeIdentity added (EXPERIMENTAL): the contract for mapping external type spellings onto declared names, with no implementation and no wiring yet.

Breaking changes: one stated source-level exception — MetamodelChange is sealed and gains members, so an external exhaustive when over it needs new branches. Binary compatibility is untouched; consumers recompile. Everything else is additive.

The two comparisons. Declared-vs-declared answers what a schema edit did; declared-vs-observed answers what the live graph holds that the declaration does not cover:

flowchart TD
    A[DeclaredSchema, version n] --> B[MetamodelDiffer.diff]
    C[DeclaredSchema, version n-1] --> B
    B --> D[declared vs declared: renames paired, signatures compared modulo renames]
    A --> E[DeclaredObservedDiffer.diffAgainstObserved]
    F[ObservedSchema, names only from a live graph] --> E
    E --> G[declared vs observed: undeclared types and relationship names, judged by own label]
    D --> H[MetamodelDiff: sealed MetamodelChange taxonomy]
    G --> H

Loading

Next in stack: #86 drift checking and quarantine.

[igordayen]

@jimador - few minor comments about visibility. Codex report - coming. thank you

[igordayen]

from Codex:

1. The rename handling is broader for drift than it is for unobservedEntityTypes

Example:

• Declared type name: Human
• Declared aliases in the stamp: Person
• Observed graph labels: Person

Expected result:

• This type should not be reported as unobserved, because the graph contains data under the declared former name of the same type.

What the code does:

• For drift, it treats declared former names as known, so Person is not reported as drift.
• For unobservedEntityTypes, it checks only whether the graph contains:
  • the current declared type name, or
  • ownLabelOf(currentDeclaredTypeName)

For this example, those checks are:

• Human
• Human

They do not include the declared former name Person.

Conclusion:

• The same graph can be interpreted as “not drift” and also “type unobserved”.
• That means declared renames are only applied on one side of the declared-vs-observed comparison, not both.

2. The observed-side match is narrower than the declared schema it is comparing against.

Example:

• Declared type name: com.example.Outer$Person
• Declared labels in the stamp: Person
• Observed graph labels: Person

Expected result:

• This type should count as observed, because the graph contains the label the declaration says this type uses.

What the code does:

• For drift, it does consider the wider declared name set.
• For unobservedEntityTypes, it checks only whether the graph contains:
  • the declared type name itself, or
  • ownLabelOf(declaredTypeName)

For this example, those checks are:

• com.example.Outer$Person
• Outer$Person

Neither matches the actual observed label Person.

Conclusion:

• A type can be reported as unobserved even when the graph contains data under the label declared for that type.
• That means the observed-side matching rule is not using all of the declared identity information already present in the stamp.

[jimador]

Answering the Codex findings.

Finding 1 is right and is fixed in 6897662 on this branch, with the stack above restacked on it.

1. unobservedEntityTypes now treats a declared former name as evidence the type is observed, the same way drift already does. isObserved takes the type's declared aliases and answers true when the current name or any former name is in the observed set, as spelled or as its own label. Three tests cover it: data only under the former name, data only under a qualified former name's label, and a guard that a type with no data under any of its names stays unobserved. The check widens to the type's own names only. A declared label set carries inherited parent labels, so accepting that as evidence would mark an empty Person observed whenever any Agent node exists.
2. The Outer$Person spelling is outside the built-in cut on purpose. The own-label KDoc names the two spellings the dot cut does not handle, a nested class with $ and a platform that uppercases the first character, and says a host that meets either one maps its own names through the TypeIdentity SPI in this package. That SPI is a spec on this branch and its consuming slice lands separately, so this stays as is.

[igordayen]

@jimador - looks good, thank you!