Posture HF provider boundary for future extraction

[mark-e-deyoung]

Purpose

Implements #27 as a posture-only increment on top of draft PR #25. It preserves the option to extract provider integrations into separately distributed wheels later without adding a plugin ecosystem to the MVP critical path now.

Red-team disposition

NARROW: use a small in-tree provider adapter seam now; defer Pluggy, Python entry-point discovery, separate wheels/repos, compatibility negotiation, and a general plugin manager until a second real implementation validates the boundary and an extraction trigger exists.

Implementation

• add tools/provider_adapters/contracts.py with one stdlib-only ProviderEvidenceAdapter protocol for the already-proven boundary: captured provider evidence -> normalized Foundry observation;
• add tools/provider_adapters/huggingface.py containing the HF-specific evidence interpretation formerly embedded in the CLI;
• keep tools/normalize_hf_observation.py backward-compatible as a thin explicit wrapper around the in-tree HF adapter;
• add contract/equivalence tests proving the adapter identity/capability surface and byte-equivalent wrapper/direct output;
• add docs/architecture/provider-adapter-posture.md with ownership boundaries, security caveat, extraction triggers, second-implementation gate, and explicit deferred work;
• include the adapter directory in the existing offline HF observation CI path filter.

Explicitly not added

• Pluggy;
• entry-point/automatic plugin discovery;
• separate provider packages/wheels/repos;
• generic provider registry/lifecycle/version negotiation;
• plugin permission/sandbox machinery;
• acquisition/materialization interfaces;
• runtime/target/representation plugin families;
• policy, qualification, or project-validator changes.

A separately distributed Python wheel is documented as a packaging/dependency boundary, not a security sandbox.

Critical-path effect

No new MVP stage is introduced. The first HF path remains:

captured exact HF evidence -> in-tree HF adapter -> normalized observation -> later native materialization -> verified local handle -> desktop-ui-cv qualification

R4

• reproducible/repeatable: existing offline fixtures and stdlib-only tests;
• reversible: wrapper API/CLI preserved; adapter refactor can be reverted independently;
• idempotent: canonical observation output remains byte-deterministic;
• no provider/network/model access required.

Stacking:

• base: draft PR Issue #24: add deterministic Hugging Face identity observation #25 / impl/issue-24-hf-observation at c1694296eeed81a9f5cd11f5dadb13cb945ec976;
• retarget after prerequisite stack lands.

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

[mark-e-deyoung]

Exact verification disposition

The adapter-posture candidate is verified without provider/network/model access.

• stacked base: c1694296eeed81a9f5cd11f5dadb13cb945ec976 (draft PR Issue #24: add deterministic Hugging Face identity observation #25 head)
• product head: 837433f845ca149efa100f4a7c43757cce8c5c0c
• PR merge candidate tested by Actions: 5d006f7e67c24d3d93e5a88f78cb4c1dd93bf93e
• workflow run: 33543501339 — PASS
• runner: Ubuntu 24.04.4 / image 20260823.283.1
• Python: 3.12.14
• permissions: contents: read
• offline observation suite: 11/11 PASS
• canonical CLI output repeatability/path-independence step: PASS

New contract evidence includes:

1. HUGGINGFACE_ADAPTER satisfies the narrow ProviderEvidenceAdapter protocol;
2. its only declared capability is normalize_observation;
3. direct adapter output is semantically and canonically byte-equivalent to the backward-compatible wrapper;
4. all pre-existing exact identity/file/license/repeatability assertions continue to pass.

No Pluggy, entry-point discovery, separate wheels, generic registry, acquisition interface, provider SDK, credential use, runtime plugin, or policy/qualification change was introduced.

The implementation remains a posture seam, not a plugin-system commitment. PR stays draft; no merge implied.

[mark-e-deyoung]

Follow-through after real HF native materialization

Downstream #29 / draft PR #30 has now exercised the first live provider-native acquisition boundary.

Evidence:

• PR Add exact-revision Hugging Face native materialization #30 product head: 7380395be39934407565edb8717eb56afb77f728
• public workflow run 33554409931: PASS
• deterministic materialization contract: 11 tests PASS
• real exact-revision HF native-cache smoke: materialized once, then cache-only hit at the same native handle

Architecture disposition: CONFIRMS / NARROW.

The live path did not require Pluggy, entry-point discovery, a generic ProviderMaterializer, a provider registry, a separate provider wheel, or a Foundry blob store. It also confirms that evidence normalization and materialization are different semantic boundaries with different dependencies/authority; they should not be collapsed into one all-purpose ProviderPlugin merely because both concern Hugging Face.

docs/architecture/provider-adapter-posture.md is updated at ae196e88a122ed97d017b06197d40a9716a2c510 to record this result and clarify that the second-implementation gate applies to the same semantic boundary. HF normalization + HF materialization do not count as two implementations of one abstraction.

No broader provider/plugin work is justified before another real provider or extraction trigger supplies evidence.