POC-Spezifikation — Prometheus v2 Phase 1

Phase-1-MVP: ~10 Wochen, zwei orthogonale Erfassungs-Tracks parallel, gemeinsamer Open-Plattform-API mit einem Bootstrap-Mirror in der EU. K1–K7 sind die verbindlichen Akzeptanztests.

1. Scope#

2. Track A — Public-Registry-Scraping#

Ziel: Sofort sichtbarer Verbreitungswert über öffentliche Daten, ohne dass Maintainer oder Endnutzer mitwirken müssen.

2.1 Quellen#

Hinweis zu den Top-Listen: npm und Go modules besitzen keinen gepflegten, kompakten "Top-Packages"-JSON-Endpoint (npm: nur eine 106 MB große Volumen-Liste aller ~4,1 Mio Namen; Go: index.golang.org/index ist ein chronologischer "recently-added"-Feed, kein Nutzungs-Ranking). Beide werden daher aus einem kuratierten, eingecheckten Seed gespeist (reviewbar, K1 bleibt aussagekräftig). Maven Central liefert über Solr keine Dependencies — diese stehen nur im POM (XML), das deshalb separat von repo1.maven.org geholt und mit defusedxml geparst wird.

2.2 Aggregat-Form (Track A)#

{
  "project_id":  "pkg:npm/example-lib",
  "version_id":  "1.4.2",
  "cohort_id":   "dep-edges-from-public-manifests",
  "metric":      "observed_dependency_count",
  "value":       "1247",
  "window_start":"2026-05-26T00:00:00Z",
  "window_end":  "2026-05-27T00:00:00Z",
  "source_mode": "D",
  "provenance":  "registry-scraper@mirror-eu-1"
}

2.3 k-Anon im Track A#

Daten kommen aus öffentlichen Quellen → k-Constraint trivial gegeben. Schema-Reject-PII bleibt als Defense-in-Depth (z. B. keine Maintainer-E-Mails im Aggregat, keine Owner-Klartextnamen aus GitHub-Metadaten).

3. Track B — Self-Instrumentation-SDK (JS + Python)#

Ziel: Runtime-Nutzungsdauer-Sicht, die Track A nicht liefern kann.

3.1 SDK-API (verkürzt)#

JavaScript:

import { instrument } from "@prometheus/sdk";

instrument({
  projectId: "pkg:npm/example-lib",
  versionId: "1.4.2",
  cohorts: ["rt-runtime-mins", "install-count"],
  mirror: "https://mirror-eu-1.example",     // Default-Mirror via Federation-Registry
  did:    process.env.PROMETHEUS_DID         // optional in Phase 1, Pflicht ab Phase 2
});

Python:

from prometheus_sdk import instrument

instrument(
    project_id="pkg:pypi/example-lib",
    version_id="2.0.0",
    cohorts=["rt-runtime-mins", "install-count"],
    mirror="https://mirror-eu-1.example",
)

3.2 Events, die das SDK emittiert#

3.3 Aggregat-Form (Track B)#

{
  "project_id":  "pkg:npm/example-lib",
  "version_id":  "1.4.2",
  "cohort_id":   "rt-runtime-mins",
  "metric":      "runtime_minutes_band",
  "value":       "30-60",
  "k_effective": 23,
  "k_min":       5,
  "window_start":"2026-05-26T12:00:00Z",
  "window_end":  "2026-05-26T13:00:00Z",
  "source_mode": "A"
}

3.4 Banding (verhindert PII-Inferenz)#

Numerische Werte werden in Bänder gemappt, nie als Klartext-Zahl:

4. Bootstrap-Mirror#

Phase-1-Konfiguration: Single-Node, EU-gehostet, Apache-2.0-Open-Source-Stack.

5. Erfolgskriterien K1–K7#

6. Sprint-Plan (10 Wochen, vorläufig)#

7. Out of Scope für Phase 1 (explizit)#

• Endnutzer-Agent (Modus B als Daemon-Variante außerhalb der Lib)
• Hybrid-Aggregator-Daemon (Modus C)
• ZK-SNARK-Attestation (05-zero-knowledge-vorschlag.md, Baustein B)
• Cross-Mirror-Gossip (kommt mit Mirror #2 in Phase 2)
• Threshold-Konsens (Phase 3)
• weitere SDK-Sprachen außer JS und Python
• Build-Tool-Plugins (Maven/Gradle/cargo-Hooks)
• Dashboards mit Live-Visualisierung (Streaming-Charts, Echtzeit-Aktualisierung, serverseitiges Rendering) — Forschung/Hersteller bauen ihre eigenen. Nicht gemeint ist das statische Dashboard: das ist Pflicht-Deliverable Nr. 9 (07-prototyp-requirements.md §2 / §7) und trägt den K6-Nachweis. Phase 1 liefert also API + Open-Data-Dumps plus ein statisches, vom Mirror ausgeliefertes Frontend ohne Build-Step.

8. Querverweise#

• 01-konzept.md — Gesamtkonzept v2
• 03-risikoprofil.md — Phase-1-relevante Risiken (D-2-1, M-2-1, M-2-2 priorisiert)
• 04-executive-summary.md — Stakeholder-Brief
• 05-zero-knowledge-vorschlag.md — ZK-Bausteine (Phase 2+)
• 06-offene-punkte.md — Phase-1-Blocker (Mirror-Discovery, Lizenz, Anti-Sybil, GDPR-pro-Mirror)
• ADRs: ADR-v2-0001 (Federation), ADR-v2-0002 (Vier Modi), ADR-v2-0003 (Aggregat-Key), ADR-v2-0004 (Lizenz + Audit-Log)