POC specification — Prometheus v2 phase 1

Phase-1 MVP: ~10 weeks, two orthogonal capture tracks in parallel, a shared open platform API with one bootstrap mirror in the EU. K1–K7 are the binding acceptance tests.

1. Scope#

2. Track A — public registry scraping#

Goal: an immediately visible reach figure from public data, without maintainers or end users having to take part.

2.1 Sources#

A note on the top lists: npm and Go modules have no maintained, compact "top packages" JSON endpoint (npm: only a 106 MB volume list of all ~4.1 million names; Go: index.golang.org/index is a chronological "recently added" feed, not a usage ranking). Both are therefore fed from a curated, checked-in seed (reviewable, and K1 stays meaningful). Maven Central supplies no dependencies over Solr — those exist only in the POM (XML), which is therefore fetched separately from repo1.maven.org and parsed with defusedxml.

2.2 Aggregate shape (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 in track A#

The data comes from public sources → the k constraint is trivially satisfied. Schema-reject-PII remains in place as defense in depth (for instance no maintainer e-mails in the aggregate, no owner names in the clear from GitHub metadata).

3. Track B — self-instrumentation SDK (JS + Python)#

Goal: the runtime usage-duration view that track A cannot deliver.

3.1 SDK API (abbreviated)#

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 the federation registry
  did:    process.env.PROMETHEUS_DID         // optional in phase 1, mandatory from 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 the SDK emits#

3.3 Aggregate shape (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 (prevents PII inference)#

Numeric values are mapped onto bands, never carried as a number in the clear:

4. Bootstrap mirror#

Phase-1 configuration: single node, EU-hosted, Apache-2.0 open-source stack.

5. Success criteria K1–K7#

6. Sprint plan (10 weeks, provisional)#

7. Out of scope for phase 1 (explicitly)#

• End-user agent (mode B as a daemon variant outside the library)
• Hybrid aggregator daemon (mode C)
• ZK-SNARK attestation (05-zero-knowledge-vorschlag.md, building block B)
• Cross-mirror gossip (arrives with mirror #2 in phase 2)
• Threshold consensus (phase 3)
• SDK languages other than JS and Python
• Build-tool plugins (Maven/Gradle/cargo hooks)
• Dashboards with live visualisation (streaming charts, real-time updates, server-side rendering) — research and vendors build their own. This does not mean the static dashboard: that is mandatory deliverable no. 9 (07-prototyp-requirements.md §2 / §7) and carries the K6 evidence. Phase 1 therefore delivers API + Open Data dumps plus a static frontend served by the mirror without a build step.

8. Cross-references#

• 01-konzept.md — the overall v2 concept
• 03-risikoprofil.md — phase-1-relevant risks (D-2-1, M-2-1, M-2-2 prioritised)
• 04-executive-summary.md — stakeholder brief
• 05-zero-knowledge-vorschlag.md — ZK building blocks (phase 2+)
• 06-offene-punkte.md — phase-1 blockers (mirror discovery, licence, anti-Sybil, GDPR per mirror)
• ADRs: ADR-v2-0001 (federation), ADR-v2-0002 (four modes), ADR-v2-0003 (aggregate key), ADR-v2-0004 (licence + audit log)