feat(metamodel): drift checking and quarantine

[jimador]

PR 4 of the metamodel train, stacked on #85. Drift checking and quarantine. DriftCheckRunner is a reporting-only contract: run() declares, stamps, observes, compares against the graph and against the swept baseline, and persists a DriftReport — its implementation holds no policy, no proposition store and no listener, so a check structurally cannot move a proposition. Acting on a check is a separate SPI, DriftSweepCapable: bounded, ContextId-scoped candidate paging, applyQuarantine, releaseFromQuarantine, and a defaulted sweep that persists what DriftQuarantinePolicy flags. Lossiness rules live in MentionTypeDriftQuarantinePolicy: type change, value/reference flip, or cardinality narrowing quarantines; widening never does; declared renames quarantine nothing by themselves, and former names are reachable however far a rename and a loss are separated. DriftReport/DriftReportStore carry the persistence contract with three explicitly scoped, bounded reads.

Changed in this review round:

• Quarantine has its own status. PropositionStatus.QUARANTINED replaces the STALE-plus-metadata encoding, which the decay lifecycle used to undo: DecayStatusPolicy revived a quarantined proposition on the next sweep and the drift sweep re-held it, alternating forever. Now DecayStatusPolicy refuses QUARANTINED outright, reads filtering on ACTIVE exclude it structurally, isAlreadyQuarantined keys on status alone, and release is the only way out — restoring the recorded prior status, clearing the reason, emitting PropositionStatusChanged. A regression test proves three decay-then-drift rounds leave the hold in place.
• The quarantine machinery moved to dice (com.embabel.dice.spi, beside StatusTransitionPolicy), so dice-metamodel drops its dice dependency and is again a leaf over the agent DataDictionary.
• The runner backed off to report-only and the sweep became the explicit SPI above; declared-vs-previous (off the swept baseline, tracked apart from version history) now feeds quarantine, declared-vs-observed stays report-only.
• Pinned propositions keep their cross-cutting immunity: a lossy change reports them as QuarantineDecision.Protected and never flips them.
• The drift and lifecycle docs state the product rule once: a declared rename or alias changes how the diff and the drift check read old data; nothing rewrites a stored mention type.

Breaking changes: additive on the released surface, with three stated source-level exceptions — QuarantineDecision is sealed and gains Protected; PropositionStatus gains QUARANTINED, so an exhaustive when needs a branch (one internal site changed; a host that matches on status exhaustively recompiles); the quarantine types moved package before ever shipping. Persistence round-trips by enum name, so no stored value changes meaning.

Opt-in and status: EXPERIMENTAL. Nothing quarantines until a host calls DriftSweepCapable.sweep() on a diff it decided to act on; there is no scheduler and no default that moves a proposition.

flowchart TD
    A[DriftCheckRunner.run] --> B[diff declared vs previous swept baseline]
    A --> C[diff declared vs observed graph]
    B --> D[DriftReport, persisted]
    C --> D
    E[host calls DriftSweepCapable.sweep] --> F[DriftQuarantinePolicy]
    B --> F
    F --> G{pinned?}
    G -- yes --> H[Protected, reported and untouched]
    G -- no --> I{lossy change?}
    I -- yes --> J[QUARANTINED plus PropositionStatusChanged]
    I -- no --> K[untouched]
    J --> L[releaseFromQuarantine: prior status restored, reason cleared]
    M[decay sweep] -. cannot lift the hold .-> J

Loading

Next in stack: #87 Drivine drift persistence and observation, #88 wiring.

[igordayen]

From CODEX:

1. dice/src/main/kotlin/com/embabel/dice/spi/MentionTypeDriftQuarantinePolicy.kt:452

This can miss propositions that should be quarantined.

Example:

• schema type: com.example.Outer$Person
• stored mention type: Person
• later, that type loses the property age

That proposition should be quarantined because it refers to the type that changed.

But this policy only recognizes the type as:

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

It does not recognize Person as the same type. So when a proposition is stored under Person, this policy treats it as unrelated to
the changed type and leaves it unquarantined.

Conclusion:
Lossy changes can be missed when the stored label differs from the names this policy checks.

[igordayen]

From CODEX - inquiry on concurrency:

2. dice-metamodel/src/main/kotlin/com/embabel/dice/metamodel/InMemoryMetamodelVersionStore.kt:69

markSwept() is last-write-wins with no guard against an older sweep finishing after a newer one, so the baseline can move backward.

Example:

• sweep 1 starts for schema version A
• schema changes, then sweep 2 starts for newer version B
• sweep 2 finishes first and calls markSwept(B)
• sweep 1 finishes later and calls markSwept(A)

After that, sweptVersion() returns A again even though B was already reconciled.

Why that matters:
The next drift check compares the current declaration against A, so it can re-report changes from A -> B that were already swept. In
other words, an older concurrent sweep can overwrite the newer baseline just by finishing later.

markSwept() needs some way to reject stale completions, or the caller has to guarantee sweeps for one schema never overlap.

[igordayen]

@jimador - few comments from me and Codex:) thank you

[jimador]

On Codex finding 1:

The Outer$Person case is the nested-class spelling that sits outside the built-in dot cut, and it is handled the same way in the quarantine policy as in the differ on #85: the own-label KDoc names it as one of the two spellings a host maps itself through the TypeIdentity SPI. The policy's spellingsOf uses the same cut as the differ, so the two stay in agreement, and the consuming slice for TypeIdentity lands separately.

On finding 2 (concurrency):

Correct: markSwept is last-write-wins and DICE never calls it. The host does, after a sweep. The contract is now written on the interface in 8c2683b: sweeps of one schema must not overlap, and the call site runs them one at a time. A compare-and-set form, markSwept(version, expectedBaseline), is the follow-up if a host ever needs overlapping sweeps. I would take it as a separate issue.

[igordayen]

@jimador - looks good, thank you!