Posture provider integrations for future extraction without plugin infrastructure

[mark-e-deyoung]

Purpose

Adopt the red-team disposition for future provider/plugin modularity without adding a plugin ecosystem to the MVP critical path.

Decision

NARROW: posture provider-specific code behind a small in-tree adapter boundary now; defer Pluggy, entry-point discovery, separately distributed wheels, compatibility negotiation, package templates, and a general plugin manager.

The first proven boundary is deliberately narrow: captured provider evidence -> normalized Foundry observation. Do not invent an all-purpose ProviderPlugin interface spanning observation, acquisition, runtime loading, policy, qualification, and deployment.

Why this is on-path beneficial

• keeps provider-specific semantics and future SDK types out of core control logic;
• makes deterministic fixture testing easier;
• preserves explicit provider selection/authorization rather than auto-loading installed code;
• allows later extraction to a separate wheel with minimal architecture surgery if evidence supports it;
• does not create a new release/compatibility matrix before the first consumer is proven.

Implementation increment

Stack on the existing HF observation work from #24 / draft PR #25.

1. Define one stdlib-only provider evidence adapter protocol for normalization.
2. Move Hugging Face-specific normalization into an in-tree HF adapter implementing that protocol.
3. Keep the existing normalize_hf_observation.py CLI/API behavior backward-compatible as a thin wrapper.
4. Add deterministic contract tests proving the adapter identity/capability surface and equivalence of wrapper vs direct adapter output.
5. Document future extraction criteria and non-goals.

Explicit non-goals

Do not add:

• Pluggy;
• Python entry-point discovery;
• separate provider wheels/repos;
• provider auto-discovery;
• generic plugin lifecycle/version negotiation;
• plugin permission manifests/sandbox claims;
• runtime/target/representation plugin families;
• changes to Foundry selection policy or project validators;
• provider acquisition/materialization beyond the currently proven increment.

A separately installed Python wheel is a packaging/capability boundary, not a security sandbox.

Future extraction gate

Do not create a separately distributed provider wheel until at least a second real implementation has exercised the same boundary and one or more material extraction triggers exist, such as independent release cadence, substantial exclusive dependencies, dependency conflict, deliberately omitted deployments, different maintenance ownership, or independent reuse.

If the second implementation does not fit naturally, revise the in-tree seam rather than preserving a premature public plugin API.

R4

• reproducible: stdlib-only deterministic fixtures/tests;
• repeatable: no provider/network/model access;
• reversible: one stacked adapter refactor with wrapper compatibility;
• idempotent: repeated normalization remains byte-deterministic.

Related: #18, #19, #24, draft PRs #22/#23/#25; SemperSupra/desktop-ui-cv#17/#19.

[mark-e-deyoung]

2026-09-04 provider-architecture red-team finding

Review basis: current provider-fixture capture (tools/capture_provider_metadata.py), provider evidence adapter posture/implementation (PR #28), HF native materialization (PR #30), qualification receipt semantics (#31/PR #32), retained resolution (#37/PR #38), and producer/publisher issue #20.

Disposition

KEEP the narrow, operation-specific provider code. NARROW the word/provider concept further. Do not introduce a universal ProviderPlugin.

The current implementation already demonstrates why: huggingface participates in several materially different operations with different dependencies/authority/side effects:

1. public metadata capture;
2. offline evidence normalization;
3. network-capable native-cache materialization;
4. potentially future publication;
5. external runtime loading remains outside Foundry.

Those are not one lifecycle and should not be forced behind one provider object merely because the remote brand is the same.

Red-team findings

1. provider is an overloaded architectural noun

The current portfolio already contains provider/venue classes with incompatible semantics:

• Hugging Face: source identity + file host + native cache/materialization venue;
• Civitai: version/file metadata + downloadable checkpoint host with AIR/file hashes;
• OpenRouter: hosted inference/catalog broker; no local artifact need exist and an exact local payload digest may be unavailable;
• Ollama: local runtime/store with provider-native model digest/manifest behavior;
• OCI registry / GHCR / zot / similar: content-addressed publication/distribution venue; ORAS is a client/transport, not the identity owner itself.

Therefore provider_id is acceptable as a namespace attached to an observation/operation, but it must not imply that every provider supports observation, materialization, publication, or hosted execution through one interface.

2. Operation-specific seams are the right abstraction level

Retain separate semantic boundaries such as:

observe/capture -> normalize observation
normalized artifact observation -> materialize provider-native representation
release candidate -> publish to venue -> verify published identity
hosted model/service identity -> remote execution binding   (future, separate)

Do not create a generic provider registry/router until at least two real implementations of the same operation demonstrate repeated structure.

3. The current ProviderEvidenceAdapter protocol is tolerable but its capabilities set is presently close to decorative

The only proven capability is normalize_observation, and the test currently proves the adapter advertises that capability. There is no dynamic discovery/routing requirement. Do not expand this into capability negotiation. If it remains unused after a second normalization implementation, simplify it rather than preserving a mini-plugin contract for symmetry.

4. The centralized metadata-capture script is an experimental convenience, not a provider framework

capture_provider_metadata.py currently contains provider-specific HTTP/projector functions for HF/Civitai/OpenRouter. This is acceptable while it is a small evidence-capture utility. If provider-specific authentication/dependencies/churn grows, split by operation/provider module then; do not turn the subparser switch into the implicit universal provider API.

5. Credential authority needs stronger provenance at the acquisition boundary

HF native materialization deliberately accepts no token value and delegates to huggingface_hub native credential resolution when network access is authorized. Current HF Hub behavior uses a saved/active token implicitly by default, including for requests that could otherwise be anonymous, unless implicit-token use is disabled.

That means allow_network=true currently authorizes network acquisition but does not by itself prove which authentication mode/principal was used. A logged-in developer machine could silently use broader credentials than the caller intended.

Before gated/private provider materialization is relied on, record a non-secret auth disposition such as anonymous, explicit_execution_identity, or equivalent, and fail closed when the acquisition policy requires anonymous/no-credential access but the provider client would use ambient credentials. Do not place credential values in receipts.

For the current public KV-Ground artifact, prefer an explicitly anonymous/no-implicit-token acquisition context if practical.

6. Byte verification is weaker than the available identity evidence

The HF observation already preserves LFS SHA-256 identities for the safetensor shards. verify_native_snapshot() deliberately verifies path/existence/size only and does not re-hash the multi-GB blobs.

That is a sensible fast-path optimization, but the resulting receipt should be understood as verified_structure/provider-native-cache, not independent local-byte verification. A same-size local corruption/mutation would not be detected by that function.

Do not hash multi-GB weights on every cache hit. Instead consider one strong verification at the first qualification/materialization trust boundary (or provider-native verified blob identity where mechanically available), then retain that evidence. Subsequent deterministic reuse can rely on the retained verified identity plus native-cache semantics unless corruption evidence appears.

7. Hosted providers must not be forced through artifact materialization semantics

OpenRouter is the clearest falsifier. A hosted inference model may have a stable service/model identifier while exposing no consumer-downloadable artifact. Treat future hosted execution as a distinct service/runtime binding capability, not a failed/odd materialize() implementation.

Likewise Ollama may resolve to a provider/runtime-native digest and API handle rather than a filesystem snapshot. The consumer-facing handle type is therefore operation/representation-specific.

Surviving rule

Provider-specific code is selected explicitly for a specific operation. Common interfaces are earned by repeated implementations of that operation, not by sharing a provider brand name.

This finding does not add a new MVP stage. The immediate HF path remains concrete and explicit. The only critical-path correction discovered by this review is tracked on #31/#37: stable artifact identity must be separated from observation-event identity before the first real qualification receipt/equivalent-repeat proof.