sprints and audit work

docs/modules/unknowns/architecture.md

@@ -49,7 +49,25 @@ src/Unknowns/
   },
   "reason": "No PURL mapping available",
   "firstSeen": "2025-01-15T10:30:00Z",
-  "occurrences": 42
+  "occurrences": 42,
+  "provenanceHints": [
+    {
+      "hint_id": "hint:sha256:abc123...",
+      "type": "BuildIdMatch",
+      "confidence": 0.95,
+      "hypothesis": "Binary matches openssl 1.1.1k from debian",
+      "suggested_actions": [
+        {
+          "action": "verify_build_id",
+          "priority": 1,
+          "effort": "low",
+          "description": "Verify Build-ID against distro package repositories"
+        }
+      ]
+    }
+  ],
+  "bestHypothesis": "Binary matches openssl 1.1.1k from debian",
+  "combinedConfidence": 0.95
 }
 ```
 
@@ -62,6 +80,63 @@ src/Unknowns/
 | `version_ambiguous` | Multiple version candidates |
 | `purl_invalid` | Malformed package URL |
 
+### 2.3 Provenance Hints
+
+**Added in SPRINT_20260106_001_005_UNKNOWNS**
+
+Provenance hints explain **why** something is unknown and provide hypotheses for resolution.
+
+**Hint Types (15+):**
+
+* **BuildIdMatch** - ELF/PE Build-ID match against known catalog
+* **DebugLink** - Debug link (.gnu_debuglink) reference
+* **ImportTableFingerprint** - Import table fingerprint comparison
+* **ExportTableFingerprint** - Export table fingerprint comparison
+* **SectionLayout** - Section layout similarity
+* **StringTableSignature** - String table signature match
+* **CompilerSignature** - Compiler/linker identification
+* **PackageMetadata** - Package manager metadata (RPATH, NEEDED, etc.)
+* **DistroPattern** - Distro/vendor pattern match
+* **VersionString** - Version string extraction
+* **SymbolPattern** - Symbol name pattern match
+* **PathPattern** - File path pattern match
+* **CorpusMatch** - Hash match against known corpus
+* **SbomCrossReference** - SBOM cross-reference
+* **AdvisoryCrossReference** - Advisory cross-reference
+
+**Confidence Levels:**
+
+* **VeryHigh** (>= 0.9) - Strong evidence, high reliability
+* **High** (0.7 - 0.9) - Good evidence, likely accurate
+* **Medium** (0.5 - 0.7) - Moderate evidence, worth investigating
+* **Low** (0.3 - 0.5) - Weak evidence, low confidence
+* **VeryLow** (< 0.3) - Very weak evidence, exploratory only
+
+**Suggested Actions:**
+
+Each hint includes prioritized resolution actions:
+
+* **verify_build_id** - Verify Build-ID against distro package repositories
+* **distro_package_lookup** - Search distro package repositories
+* **version_verification** - Verify extracted version against known releases
+* **analyze_imports** - Cross-reference imported libraries
+* **compare_section_layout** - Compare section layout with known binaries
+* **expand_catalog** - Add missing distros/packages to Build-ID catalog
+
+**Hint Combination:**
+
+When multiple hints agree, confidence is boosted:
+
+```
+Single hint: confidence = 0.85
+Two agreeing: confidence = min(0.99, 0.85 + 0.1) = 0.95
+Three agreeing: confidence = min(0.99, 0.85 + 0.2) = 0.99
+```
+
+**JSON Schema:**
+
+See `src/Unknowns/__Libraries/StellaOps.Unknowns.Core/Schemas/provenance-hint.schema.json`
+
 ---
 
 ## Related Documentation