PlantAI-dev/.superpowers/sdd/task-3-brief.md

Task 3 — Typed STRING API and deterministic PPI ID resolution

Goal

Make PPI identifier resolution deterministic, provenance-preserving, and able to distinguish a valid empty network from external API failure. Share one host-level STRING request gate across scientific and optional image requests.

Allowed files

• Create gfa_core/string_rate_gate.py.
• Modify skills/ppi/run.py for typed STRING API, origins, resolution, and network execution.
• Modify only active optional STRING image/SVG request sites in apps/web/pipeline_backend.py to reuse the same rate gate and caller identity.
• Create tests/unit/test_ppi_id_resolution.py.
• Update .superpowers/sdd/task-3-report.md.

Do not implement Reset API, frontend labels, final contract/diagnosis changes, or broad Ortholog redesign in this task.

Core invariants

• Canonical target IDs are immutable provenance; Ortholog IDs are relationships, not aliases.
• Parse Ortholog mapping to a list of PpiQueryOrigin, retaining every canonical-to-reference relationship.
• One resolution summary row per relationship; dedupe only candidate probes and final selected STRING IDs.
• Exact versioned reference ID remains evidence. Versionless accession is only an additional lookup candidate.
• Raw/normalized/local alias candidates may resolve only when all successful candidates converge on one STRING entity.
• One canonical source with multiple distinct Ortholog references is ambiguous_ortholog and excluded unless the references converge on one STRING entity.
• Partial resolution continues with explicit unresolved rows. Zero resolution is an ID-resolution failure, not an empty network.
• network -> [] is valid empty_network; transport/HTTP/JSON/shape failures raise typed external API errors.
• Mapping endpoint 404 and 200 [] mean zero resolution only. Other failures are not converted to empty results.
• Validate queryIndex rather than response order; reject duplicate, malformed, negative/out-of-range, or wrong-taxon rows.
• Accept STRING version payload fields stable_address and string_stable_address.
• Use POST, echo_query=1, caller_identity=PlantAI, 30-second timeout, explicit JSON-shape validation.
• Validate network parameters before HTTP.
• Apply one host-shared fcntl.flock + atomic timestamp rate gate to version, mapping, network, and optional image requests. Default gate path comes from BBAV5_STRING_RATE_GATE under /tmp; production interval one second; injected clock/sleeper for deterministic unit tests.

Mandatory tests

Implement every exact test case listed under Task 3 Step 1 in docs/superpowers/plans/2026-07-10-ppi-id-resolution.md, including real-shape 24-origin/12-query provenance, raw XP 5/12 plus GeneID 12/12 fallback, convergence/ambiguity, mapping 404/empty semantics, queryIndex validation, empty-network versus HTTP failure, and real multiprocessing serialization across scientific/image callers.

TDD and verification

1. Add the focused test module first and record genuine RED for missing/incorrect interfaces.
2. Implement in small groups, rerunning focused subsets.
3. Final focused command: /home/xia-lab/miniconda3/envs/test4py311/bin/python -m pytest tests/unit/test_ppi_id_resolution.py tests/unit/test_ppi_string_policy.py -q
4. Also run relevant backend image/PPI tests and py_compile on changed production files.
5. No unit test may use live network access.

Checkpoint

The workspace has no functional Git repository. Baselines are under /tmp/ppi-id-resolution-task3-baseline/; full baseline/current diffs are the review artifact.