feat(dice-storage-autoconfigure): opt-in metamodel wiring

[jimador]

PR 6, closing the metamodel train (#83 → #84 → #85 → #86 → #87 → #88). The governance loop becomes usable from a Spring Boot app, and it gets an operator. MetamodelAutoConfiguration in dice-storage-autoconfigure registers only when the host declares a DeclaredSchemaSource bean — declaring your schema is the opt-in — and then wires the loop: version store, drift-report store, observed-schema source, both differ roles, quarantine policy, DriftSweepCapable, drift runner, and the metamodel SchemaCatalog. Every wired collaborator is @ConditionalOnMissingBean. embabel.dice.metamodel.enabled=false removes the beans; drift.mode is off or observe (default); backend selection follows embabel.dice.store.type. Nothing in the wiring runs a check or moves a proposition: a check happens when the host calls DriftCheckRunner.run(), a quarantine when the host calls DriftSweepCapable.sweep().

Changed in this review round:

• The operator surface. GovernanceOperationsService in dice is the single entry point — read (latest reports, global and per context, plus the declaration in force and the version the last completed sweep reconciled against), run (a check answering the full impact a sweep would evaluate, declaredDiff included), release (one call per proposition, context-checked before it writes). GovernanceController serves the five operations on /api/v1/metamodel; GovernanceTools exposes the same five as @LlmTool tools; both call the one service. EXPERIMENTAL, marked @ApiStatus.Experimental in code across the stack. The routes activate only when the host writes @Import(DiceRestConfiguration) and a DeclaredSchemaSource is declared — the same activation as every other DICE controller, carried by a deferred import so the condition sees autoconfigured beans. GovernanceTools is host-constructed like DiscoveryTools; no auto-configuration registers a controller or a tool object. Per-report release is deliberately absent: nothing in the model ties a proposition to the report whose application held it, and the doc says what closing that needs.
• ObserveOnlyDriftCheckRunner is deleted and DriftMode reduces to OFF | OBSERVE — the runner is report-only structurally, so the decorator had nothing left to downgrade.
• The sweep bean announces status transitions to every DiceEventListener on the context; the derived-ownership schema wiring from feat(dice-storage): Drivine drift-report store and observed-schema source #87 is registered here; the HTTP gate re-checks the declared schema directly.

Breaking changes: none. A host with no DeclaredSchemaSource bean sees no metamodel beans at all, proven by a context probe test.

flowchart TD
    A{DeclaredSchemaSource bean?} -- no --> Z[no metamodel beans at all]
    A -- yes --> B{metamodel.enabled}
    B -- false --> Z
    B -- true --> C[stores, observed schema, differs, policy, sweep, runner]
    C --> F[GovernanceOperationsService; REST via host Import of DiceRestConfiguration; tools host-constructed]
    F --> G[read reports and declared version]
    F --> H[run a check on demand]
    F --> I[release one proposition from quarantine]
    J[host calls DriftSweepCapable.sweep] --> K[quarantine, deliberate and evented]

Loading

Landing

• Build the union of this stack's tip and the extraction-run stack's tip (Extraction runs: proposition lineage #101) before either lands; the two share six recurring conflict files with recorded resolutions; DiceStorageAutoConfiguration.kt conflicts too and is resolved by hand from the union worktree's committed adaptation.
• Whichever stack lands second restacks and applies one adaptation: ExtractionRunSchema joins this stack's DiceStorageSchema derived-ownership contract (object declaration, override on specs(), bookkeeping relationship types, catalog and test beans). DiceStorageSchemaRegistrationTest fails until it is applied — that is the guard working.
• No consumer migration is required to land: the four-argument undoSingleCollapse stays as a deprecated overload (Source-revision provenance: authoritative collector fold and undo #92). Downstream callers move to CollapseUndoCommand when convenient.

[igordayen]

From CODEX:

1. dice/src/main/kotlin/com/embabel/dice/agent/GovernanceTools.kt:77

The new governance tools are exposed with generic names like run_drift_check, latest_drift_reports, and
release_quarantined_proposition.

Example:

• another module also exposes run_drift_check
• a host registers both tool lists in one agent/MCP server
• both tools now have the same public name

At that point the tool registry has to either reject one, overwrite one, or leave selection ambiguous.

So for this PR, the practical fix is to prefix each tool explicitly, for example:

• embabel_dice_declared_schema_version
• embabel_dice_latest_drift_reports
• embabel_dice_run_drift_check

If dotted tool names are valid in the target tool registry, embabel.dice.run_drift_check is clearer. If not, use underscores. The key point is that the prefix must reach Tool.Definition.name, not only metadata or docs.

There is also PR on embabel-agent that flags non-unique tool names and prefixes tool names with agent name,
see:
embabel/embabel-agent#1833

2. dice-storage-autoconfigure/src/main/kotlin/com/embabel/dice/storage/autoconfigure/MetamodelAutoConfiguration.kt:127

The configuration prefixes are repeated directly in annotations:

• embabel.dice.metamodel
• embabel.dice.metamodel.drift
• embabel.dice.store

This is not a behavior bug, but it is easy to mistype later. Spring does not provide a class-level prefix that child
@ConditionalOnProperty annotations inherit, so I would define constants instead:

private const val DICE_PREFIX = "embabel.dice"
private const val METAMODEL_PREFIX = "$DICE_PREFIX.metamodel"
private const val DRIFT_PREFIX = "$METAMODEL_PREFIX.drift"
private const val STORE_PREFIX = "$DICE_PREFIX.store"

Then use those constants in @ConfigurationProperties and @ConditionalOnProperty. That keeps the public property names in one place.

3. dice-storage-autoconfigure/src/test/kotlin/com/embabel/dice/storage/autoconfigure/MetamodelAutoConfigurationIntegrationTest.kt:163

The comment says _DrivineSchema is currently reported as drift, but PR 87 already added INFRASTRUCTURE_LABELS and excludes _DrivineSchema.

So the comment is stale. It now tells the reader the opposite of the current behavior.

[igordayen]

@jimador - looks good, a few comments from my side and Codex, thank you

[jimador]

On Codex items 2 and 3:

2. Fixed in 9e021e9. The prefixes are const vals on one internal object, and the nine annotations across the two metamodel files reference it.
3. Fixed in 7edd5d7. The comment now says DrivineObservedSchemaSource keeps _DrivineSchema out through INFRASTRUCTURE_LABELS, and the test asserts it.

Item 1 (tool name prefixes) is answered separately.

[igordayen]

@jimador - looks good, thank you