docs(provider-byok): spec + surgical Full Architecture update (PBF-GOV Wave 1)

AFI_Full_Architecture.md

@@ -108,6 +108,7 @@ AFI is organized by responsibility, not by repository alone. The planes below de
 
 - **object-identity-v0.1** — canonical Signal (USS v1.1), a thin Scored Signal projection, the strategy triple, `signalId` as the join key.
 - **factory-configurable-pipelines-v1** — the analyst-configurable pipeline model: the five-category namespace, the composition and executor boundary, delegation of the V1 contract family to afi-config, and the scored-evidence v2 composition reference.
+- **provider-byok-foundations-v0.1** — the provider-neutral adapter socket and the secure bring-your-own-key (BYOK) credential boundary: the five categories as open capability lanes, one resolved result per category, the three non-secret objects (Provider, CredentialRef, ProviderInstance), trusted registered adapters, the credential-never-in-artifact and least-privilege runtime-resolution invariants, canonical category-output validation before scoring, and an Evidence V2 freeze with provider-invocation provenance reserved to a later evidence decision (see [`specs/AFI_PROVIDER_BYOK_FOUNDATIONS.v0.1.md`](specs/AFI_PROVIDER_BYOK_FOUNDATIONS.v0.1.md)).
 - **lifecycle-v0.1** — the settlement lifecycle up to the off-chain finality writer; it explicitly reserves on-chain settlement, epochs, rewards, claims, and mint to a future chain-governance track.
 - **persistence-v0.1** and **persistence-impl-v0.1** — the canonical evidence store and its staged implementation.
 - **uwr-profile-pin-v0.1** and **uwr-runtime-consumption-v0.1** — the pinned (testnet-provisional) UWR profile and the rules for consuming it at runtime.
@@ -123,6 +124,7 @@ The lifecycle state machine is governed as `INGESTED → VALIDATED → SCORED 
 - the **USS v1.1** signal schema (`schemas/usignal/`);
 - the **scored-signal-evidence v2** schema (`afi.scored-signal-evidence.v2`) and its published valid/invalid vectors;
 - the pipeline-composition, analysis-plugin, analyst-strategy, and provider-binding registries;
+- the **provider / BYOK contract family** — the non-secret `afi.provider.v1`, `afi.credential-ref.v1` (an opaque pointer that never holds a secret), and `afi.provider-instance.v1` (tenant-scoped) schemas, the `registries/providers/` reference records, and the canonical per-category output contracts `afi.enrichment.technical.v1` / `afi.enrichment.news.v1` (PBF-GOV);
 - the **CPJ v0.1** community-provider-journal schema (`schemas/cpj/v0_1`) and the active oracle provider bindings that consume it;
 - the **UWR profile registry** (`registries/uwr-profiles/`), whose pinned profile `uwr-weighted-lifts-v0.1` is testnet-provisional;
 - the **provenance (District 2 M1)** schema family (`schemas/provenance/v1`);
@@ -161,6 +163,7 @@ Factory is **not** the API Atlas, **not** the Gateway, **not** the Reactor runti
 - **The direct CPJ route is an internal trusted service boundary, not a public API (Reference/Reserved).** Its authentication is optional (a single shared secret) and provider identity is self-asserted, so any future public or partner CPJ access is designated to be mediated by a separate authenticated **Institute oracle-ingress reference service** — designated, **not implemented or deployed** — or another conforming external trust boundary; the route is neither renamed, moved, nor exposed. Provider binding, CPJ validation, and provenance stay mandatory regardless of exposure (ingest dedupe is opt-in, `AFI_INGEST_DEDUPE=1`) (INST-GOV; see [`specs/AFI_RESEARCH_INSTITUTE_REFERENCE_SERVICES.v0.1.md`](specs/AFI_RESEARCH_INSTITUTE_REFERENCE_SERVICES.v0.1.md)).
 - The **graph is manifest-driven**, not a hardcoded DAG. The executor runs topological waves (Kahn's algorithm) with bounded concurrency, deterministic ready-sets, per-node timeout and retry, conditional edges, and joins keyed by node id. Graph validation enforces unique ids, acyclicity, reachability, exactly one non-bypassable scorer sink, and declared joins.
 - The **five analysis categories** are ordinary registered plugins bound at build time, alongside a join plugin and the scorer. Any registered strategy (for example the "Froggy trend-pullback" scorer) is an ordinary registry entry, not a special path. The `aiMl` category is fed by the optional, fail-soft `afi-tiny-brains` sidecar (the Reactor's client returns nothing when the sidecar URL is unset); its output is read-only context and **does not affect UWR scoring**.
+- A **bounded provider-adapter socket** sits inside the Reactor, below the category node (not a second executor). A provider-backed node carries a non-secret `providerInstanceRef`; the runtime resolves the tenant-scoped provider instance, resolves **only** the authorized credential through an injected least-privilege `SecretResolver` (the adapter receives a bounded credential bundle, never a resolver), invokes the trusted registered adapter, and validates the canonical `afi.enrichment.<category>.v1` output before it reaches the scorer — one resolved result per category, fail-closed at every boundary. Two reference adapters are proven: a keyless technical adapter and a credentialed news adapter (BYOK; the key rides in a request header, never a URL). Credentials are resolved only at runtime and appear in no artifact, log, hash, or evidence. Deployment-specific secret backends are pending a later staging wave (PBF-GOV; see [`specs/AFI_PROVIDER_BYOK_FOUNDATIONS.v0.1.md`](specs/AFI_PROVIDER_BYOK_FOUNDATIONS.v0.1.md)).
 - The scorer node wraps afi-core's analyst, resolves the UWR configuration fail-closed, and emits scores and their resolved source verbatim.
 - The Reactor **constructs Evidence V2** (`afi.scored-signal-evidence.v2`) with `lifecycleState = SCORED`, `finalized = false`, the registry-backed UWR-profile stamp, and a required all-or-nothing composition reference. Scores are read verbatim from afi-core and never recomputed.
 - The **submitter rejects any non-`SCORED` record**, proves the wrapper, schema, sub-artifact schemas, and identifier continuity before submitting, and surfaces every failure as a typed non-2xx. The Reactor **never touches MongoDB directly**; it consumes afi-infra's store as a typed dependency, and persistence is a required step of the run.

SUMMARY.md

@@ -17,6 +17,7 @@
 * [Tokenomics](specs/tokenomics.md)
 * [Governance](specs/governance.md)
 * [Research Institute Reference Services v0.1](specs/AFI_RESEARCH_INSTITUTE_REFERENCE_SERVICES.v0.1.md)
+* [Provider Adapter and BYOK Foundations v0.1](specs/AFI_PROVIDER_BYOK_FOUNDATIONS.v0.1.md)
 
 ## 🧬 Lore Series
 * [Episode I – Ghost of DAO](lore/episode-1_ghost_of_dao.md)

specs/AFI_PROVIDER_BYOK_FOUNDATIONS.v0.1.md

@@ -0,0 +1,71 @@
+# AFI Provider Adapter and BYOK Foundations v0.1
+
+**Status:** Current specification of the implemented provider-neutral adapter socket and secure bring-your-own-key (BYOK) credential boundary. Governed by `afi-governance/decisions/provider-byok-foundations-v0.1.md` (PBF-GOV). Documents the Wave-1 foundation delivered across `afi-config`, `afi-factory`, and `afi-reactor` on the existing configurable executor and Evidence V2.
+
+This foundation establishes the provider **socket** and the credential **boundary**. It does not complete all commercial provider integrations, and it deploys nothing.
+
+## 1. Five provider-open categories, one resolved result each
+
+AFI has exactly five analysis categories — `technical`, `pattern`, `sentiment`, `news`, `aiMl` (governed namespace; casing `aiMl` exact). Each is an **open capability lane**: a category is not a vendor, not one hardcoded service, not one required algorithm, and not an ensemble. An analyst may select a conforming implementation or provider for each category.
+
+The scorer-facing pipeline consumes **at most one resolved result per category**. A provider may internally aggregate many articles, sources, indicators, or models, but AFI treats one provider invocation as one category implementation producing one category result at the pipeline boundary. The deterministic one-per-category join is unchanged; there is no generic ensemble.
+
+## 2. Three non-secret canonical objects
+
+Three first-class objects (governed by afi-config) model the provider socket. All are non-secret.
+
+- **Provider** (`afi.provider.v1`) — a stable, non-secret identity for a source of an analytical capability (local implementation, open-source library, external API, data vendor, hosted inference service, local model runtime, proprietary service, or Tiny Brains). It carries id, record version, display name, supported categories, execution class (`local`/`remote`), deterministic posture, the trusted registered adapter that implements it, and — only when a capability requires one — the credential **kind** (never a value). Registry presence means available to the relevant deployment, not an endorsement.
+- **CredentialRef** (`afi.credential-ref.v1`) — an opaque, non-secret **pointer** to a credential (id, tenant/owner scope, provider compatibility, credential kind, active/disabled state). It contains no API key, token, password, private key, authorization header, or any secret payload. The actual secret lives in a deployment secret backend keyed by `(tenant, credentialRef)`; rotation and revocation happen behind the reference.
+- **ProviderInstance** (`afi.provider-instance.v1`) — a tenant/operator-scoped, non-secret configuration binding one provider to one registered adapter for exactly one category. It is version-pinned for deterministic composition, optionally references one compatible CredentialRef (by opaque id), and carries only non-secret invocation settings. It contains no credential value, no arbitrary code, and no analyst-supplied remote endpoint (a named `endpointProfile` only — anti-SSRF).
+
+The existing **plugin/adapter** identity remains the executable boundary: `Category` is the semantic lane, `Plugin/adapter` is the trusted registered implementation, `Provider` is the source, `ProviderInstance` is this tenant's configured use, `CredentialRef` is the non-secret pointer.
+
+## 3. Factory authoring
+
+`afi-factory` authors and validates provider-backed category nodes across all five surfaces (SDK, CLI, capability catalog, framework-neutral tool definitions, MCP stdio adapter). A category node may carry an optional, versioned, non-secret `providerInstanceRef` (identity + version only). Factory validates the reference shape, enforces that it appears only on the five analysis-category nodes (not merge/scorer), preserves it in the artifact, includes it in canonical hashing, and exposes it through inspection. Factory **cannot** resolve credentials, call a provider, inspect a secret backend, or print a secret; artifacts, CLI output, and MCP output contain no credential.
+
+## 4. Reactor execution and the SecretResolver boundary
+
+`afi-reactor` runs one bounded provider-adapter layer inside the Reactor, below the category node. It is not a second executor; the `GraphExecutor` and the scorer-facing join are unchanged. For a provider-backed node the runtime:
+
+1. resolves the non-secret ProviderInstance record;
+2. validates tenant/operator scope and provider/category/adapter compatibility;
+3. resolves **only** the authorized credential (when required) through an injected least-privilege `SecretResolver`;
+4. invokes the trusted registered adapter with a bounded credential bundle and a scrubbing logger;
+5. validates the returned category result against its canonical `afi.enrichment.<category>.v1` contract before scoring.
+
+Every boundary fails closed. The **SecretResolver** resolves only the exact authorized `(tenant, credentialRef)`; it cannot list secrets, resolve arbitrary references, read another tenant's credential, discover backend paths, or write/delete/rotate. The adapter receives only a bounded credential bundle — never a resolver or a secret-management client. Adapters are compiled, explicitly registered, versioned, and validated at boot (a duplicate or unknown adapter fails closed); there is no dynamic import, arbitrary module path, or remote code loading.
+
+**Two reference proofs:** a **keyless technical** adapter (reuses the exact production kernels; the resolver is never invoked) and a **credentialed news** adapter (BYOK; the key rides in a request header, never a URL; a deterministic transport proves it without a live paid key).
+
+## 5. Security invariant
+
+> **AFI pipeline artifacts identify provider configurations but never contain provider credentials.**
+
+Secret resolution occurs only at runtime, at the adapter edge. Factory cannot resolve secrets. Adapters receive only scoped credentials. Logs, errors, traces, canonical hashes, and Evidence exclude credentials (structural closure plus a redaction boundary). Deployment-specific secret backends (for example GCP Secret Manager) are pending a later staging wave; this foundation provisions none.
+
+## 6. Evidence V2 freeze
+
+Evidence V2 (`afi.scored-signal-evidence.v2`) is unchanged: schema, semantics, canonical Mongo record shape, store version pin, and lifecycle status are all identical. The versioned pipeline composition may commit to a non-secret ProviderInstance reference through its existing artifact hash, but no provider credential, provider-invocation object, or new collection is persisted. Detailed provider/model **invocation provenance** is deferred to a later governed evidence decision that will determine Evidence V3 after real adapters reveal the true provenance fields. Evidence V2 does not contain provider-invocation provenance.
+
+## 7. Scoring, UWR, Tiny Brains
+
+Provider-backed enrichment is input to the existing scorer, never a replacement. Category weighting, scorer logic, UWR, Core, and Math authority are unchanged; equivalent category outputs produce identical scores.
+
+Tiny Brains enriches the `aiMl` category and may **later** orchestrate several internal models plus a critic/meta-model, emitting exactly one resolved `aiMl` result:
+
+```
+Tiny Brains may later use internal model orchestration
+  → emits one aiMl category result
+  → canonical AFI scoring remains authoritative
+```
+
+Its internal orchestration is not an AFI-level ensemble and never creates duplicate `aiMl` results. This foundation implements no Tiny Brains ensemble and no generic ensemble contract; Tiny Brains does not become a scorer and does not alter UWR.
+
+## 8. Independent operators and the Institute
+
+Independent parties may author and operate conforming providers and adapters; a conforming implementation is not invalid because AFI did not author it. Adding a conforming provider, adapter, credential reference, or provider instance is an administrative registry or deployment update, not per-participant governance. AFI Research Institute may operate reference adapters, but that role is non-exclusive and confers no protocol authority (INST-GOV); no Institute adapter is deployed or privileged here.
+
+## 9. Non-deployment status
+
+This foundation deploys nothing. No provider, adapter, or service is deployed; no GCP resource, Secret Manager resource, IAM, or service account is provisioned; no runtime agent operates providers; no generic ensemble exists; no commercial provider integration beyond the two reference proofs is claimed.