feat: Add deterministic and optional LLM enrichment with provenance and gates

Parent

Part of #758. Candidate impact is reported by #409, stored by #794, evaluated through #445/#489/#492, and may use reviewed feedback from #561.

Summary

Add a compiler enrichment stage that improves capability metadata without making model output an implicit source of truth.

The core path is deterministic. Optional LLM enrichment produces versioned proposals that become active only through explicit acceptance or configured evaluation gates.

source capability
→ deterministic analysis/enrichment
→ optional model proposal
→ review/evaluation
→ accepted derived patch
→ candidate bundle

The immutable normalized source capability remains preserved separately from every derived patch.

Enricher protocol

class CapabilityEnricher(Protocol):
    name: str
    version: str

    def enrich(
        self,
        capability: Capability,
        context: EnrichmentContext,
    ) -> EnrichmentPatch: ...

A patch declares exact target fields, previous values/digests, proposed values, evidence and provenance.

Enrichment categories

Mechanical/deterministic

May activate automatically when contract-defined and testable, for example:

• normalized tokenization/keywords;
• mechanically derived schema summaries;
• stable embeddings produced by a pinned builder;
• duplicate/collision relationships;
• resource/dependency facts.

Semantic/reviewable

Remain proposals unless explicitly accepted or promoted by a configured gate:

• rewritten descriptions;
• aliases and examples;
• inferred relationships;
• intent labels;
• risk/side-effect interpretations not directly present in the source.

States

Support at minimum:

• proposed;
• accepted;
• accepted_by_gate;
• rejected;
• superseded;
• stale.

Precedence

explicit human override
> accepted semantic enrichment
> deterministic derived metadata
> normalized source value

Precedence must be field-specific and visible. No patch silently overwrites source/provenance history.

Provenance and cache

Record:

• source capability digest;
• compiler/enricher identity and version;
• model/provider identity where applicable;
• prompt/template digest;
• parameters and semantic configuration;
• input/evidence digests;
• raw bounded output or a content-addressed reference;
• parser/validator identity;
• acceptance actor/rule and gate results.

Cache key includes every semantic input. Compilation can be repeated offline from stored accepted results without calling the model.

Gates and ablation

Every semantic enrichment type requires evaluation against:

• source-only baseline;
• deterministic-only variant;
• accepted semantic variant.

Measure selection quality, task success, calibration/ambiguity and regressions. Token savings alone do not justify activation.

An accepted patch becomes stale when its source capability, applicable contract, enricher/model/prompt identity or required evidence changes.

Security and privacy

• enrichment receives only explicitly allowed bounded fields;
• credentials and resource payloads are excluded by default;
• model output is treated as untrusted catalog text and sanitized/validated;
• unsupported or malformed patches fail closed;
• no runtime model dependency is required to load/use an accepted bundle;
• acceptance cannot bypass source integrity or bundle evaluation gates.

Acceptance criteria

• versioned enricher and patch contracts;
• immutable source plus separately stored derived patches;
• deterministic cache keys and offline replay;
• explicit semantic proposal states and precedence;
• source/deterministic/semantic ablation harness;
• acceptance and staleness rules covered by tests;
• provenance sufficient to reproduce or explain every active field;
• no silent activation of model-written descriptions/aliases/relationships;
• #409 reports pending/stale/accepted proposals;
• #794 pins every active semantic input and stores accepted state;
• representative adversarial tests validate model-output sanitization.

Start by reading parent issue #758 and the related work in #409, #794, #445, #489, #492, and #561 to map the proposed compiler and evaluation flow. Define the contracts, provenance, proposal states, gates, and cache behavior before implementation. Done means the acceptance criteria are covered, including offline replay, staleness handling, ablation tests, sanitization, and reporting of pending or accepted proposals.