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

Task 3 implementation report

Status

Corrections for the final authoritative reviews are implemented and locally verified. Fresh internal re-review is PASS with no findings, but the main review gate must independently approve this checkpoint; this report does not self-approve it.

Implemented behavior

• Added StringApiError and a typed STRING client boundary for version, mapping, and network requests.
• Stable API discovery accepts both stable_address and string_stable_address.
• Species resolution now rejects empty/unknown values before HTTP instead of falling back to Arabidopsis.
• Stable API addresses are restricted to HTTPS string-db.org or genuine subdomains, without credentials, ports, query/fragment data, or paths other than empty//api equivalents.
• Scientific GET/POST and optional image POST calls disable automatic redirects. Present final response URLs must remain on an authoritative STRING HTTPS host before status/body parsing; 3xx responses are rejected without resending identifiers.
• Mapping and network identifier lists use POST with caller_identity=PlantAI, 30-second timeout, and explicit response validation.
• Mapping attribution uses validated queryIndex; duplicate, malformed, negative, out-of-range, mismatched echo, and wrong-taxon rows are rejected.
• Mapping taxon fields accept only non-boolean integers or digit strings, and preferredName is a required non-empty string.
• Mapping stringId must be a nonblank <selected_taxon>.<entity> identifier whose embedded taxon agrees with the validated row and selected species.
• Mapping 404 and 200 [] are zero-resolution results; other HTTP, transport, JSON, and protocol failures remain typed failures.
• Network [] is a valid empty_network; external API failures are not converted to an empty network.
• Network rows require the selected taxon and a finite score in [0, 1].
• Network rows also require nonblank endpoint names and nonblank stringId_A/B values with the selected taxon prefix.
• Network submissions themselves must use the selected taxon. With add_nodes=0, both returned endpoint IDs must belong to the exact submitted set, and returned scores must meet required_score / 1000.
• Ortholog parsing now preserves every exact canonical-to-reference relationship as PpiQueryOrigin.
• Deterministic candidate probing retains versioned identifiers, adds versionless and job-local alias candidates, and selects only convergent STRING entities.
• Conflicting candidate mappings and conflicting Ortholog references remain explicit and excluded; partial mapping retains unresolved relationship rows.
• The production PpiSkill.run() path invokes resolution, accepts an internal id_map_file argument for later Task 4 wiring, submits only selected STRING IDs, and serializes one row per relationship with independent alias and relationship evidence fields.
• Canonical inputs without Ortholog rows remain in member denominators as unresolved while relationship_count remains the actual relationship-row count, including the all-missing case.
• Production resolver selection is unconditional; the former inspect.signature fail-open compatibility dispatch was removed.
• Direct-target raw evidence is labeled canonical_member_input; projected raw evidence remains ortholog_relationship.
• Valid empty networks produce a header-only protein1/protein2/score TSV.
• Added a host-shared fcntl.flock rate gate with an atomically replaced timestamp and BBAV5_STRING_RATE_GATE override.
• The rate gate rejects non-finite intervals, clocks, and timestamps and fails closed on corrupt or unreadable existing timestamp state.
• Applied the shared gate and PlantAI caller identity to stable-version, mapping, network, and active optional STRING image/SVG attempts.
• Every declared STRING_SPECIES_MAP canonical code now resolves to itself while unknown values remain fail-closed.
• Backend PPI execution now requires the authoritative skills/ppi/run.py entrypoint and fails closed when it is absent; the legacy run_ppi_v2.py scientific fallback was removed.
• Optional image responses now require an explicit non-boolean integer 2xx status and an explicit authoritative final response URL.

TDD evidence

Mandatory tests were added before production edits.

• RED: /home/xia-lab/miniconda3/envs/test4py311/bin/python -m pytest tests/unit/test_ppi_id_resolution.py -q
  • Result: 27 failed in 15.43s.
  • Expected causes: missing StringApiError, PpiQueryOrigin, injectable clients, deterministic resolver, rate-gate module, and backend image injection.
• Protocol-edge RED after adding wrong echoed-query evidence:
  • Result: 1 failed, 6 passed, 23 deselected.
  • Expected cause: mapping validation initially accepted a queryItem inconsistent with its validated queryIndex.
• Production-integration RED after independent review:
  • Result: 2 failed, 29 deselected.
  • Expected causes: PpiResolutionRow lacked independent relationship_source, and PpiSkill.run() did not accept/wire id_map_file or the resolver.
• Production-integration GREEN: 2 passed, 29 deselected.
• Main-review correction RED:
  • Command selected 51 new/adversarial cases.
  • Result: 34 failed, 17 passed, 22 deselected.
  • Failures reproduced all requested species, URL-authority, mapping/network shape, missing-canonical denominator, typed-status, rate-gate edge, and wrapper/subclass dispatch findings.
• Main-review correction GREEN checkpoints:
  • STRING protocol boundary: 38 passed, 35 deselected.
  • Rate gate plus multiprocessing: 13 passed, 60 deselected.
  • Missing-Ortholog denominators and wrapper regression: 3 passed, 70 deselected.
• Stale policy compatibility evidence after removing fail-open dispatch:
  • Before the authorized test migration: 1 failed, 84 passed; the old test monkeypatched the removed method signature.
  • The parent explicitly authorized changing only that test to inject a fake STRING client through the deterministic API. Assertions still verify OSA transcript normalization, resolution metrics, artifact creation, and selected-ID network submission.
• Additional URL hardening RED/GREEN:
  • RED: 2 failed, 9 passed for double-slash path and empty-label pseudo-subdomain.
  • GREEN: all 17 stable-address cases pass.
• Preferred-name whitespace RED/GREEN:
  • RED: 1 failed, 13 passed proved whitespace-only preferredName was still accepted.
  • GREEN: mapping validation now requires a non-whitespace string.
• Fresh-review empty-Ortholog/string-ID RED/GREEN:
  • RED: 3 failed, 14 passed reproduced empty and comment-only supplied Ortholog files falling into direct mode, plus whitespace-only stringId acceptance.
  • GREEN: 17 passed; execution now branches on explicit mapping_file presence, preserves zero relationships/all canonical unresolved, makes no mapping/network request, and rejects whitespace-only stringId at the typed protocol boundary.
• Authoritative re-review redirect/identity/species RED/GREEN:
  • RED: 22 failed, 2 passed, 92 deselected across 24 selected cases.
  • Failures reproduced automatic redirect following/defaults, ignored final response authority, mapping STRING-ID/taxon contradictions, incomplete network endpoint identity, and four unreachable declared species codes.
  • GREEN: all 24 passed, 92 deselected after the production corrections.
• Backend positive-fake compatibility evidence:
  • RED: 2 failed, 24 passed, 5 deselected because two existing image fakes did not accept the newly required allow_redirects keyword.
  • The parent authorized changing only those two fake signatures to require/assert allow_redirects is False; production contains no downgrade retry.
  • GREEN: 26 passed, 5 deselected.
• Final-review scientific/backend/provenance/image RED/GREEN:
  • RED scientific/image group: 6 failed, 1 passed, 103 deselected.
  • RED backend authoritative-entrypoint group: 1 failed, 31 deselected because the legacy CLI launched.
  • The seven failures reproduced wrong submitted taxon, unsubmitted endpoint, below-threshold score, false direct provenance, missing image status/URL, and legacy backend fallback.
  • GREEN targeted groups: scientific/image 7 passed; authoritative backend entrypoint 1 passed.
• GREEN API/protocol checkpoint: 14 passed, 13 deselected.
• GREEN resolution/provenance/network checkpoint: 11 passed, 16 deselected.
• GREEN multiprocessing checkpoint: 2 passed, 25 deselected.
• Final required 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
  • Current result: 123 passed in 0.91s.
• Relevant backend image/PPI command:
  • /home/xia-lab/miniconda3/envs/test4py311/bin/python -m pytest tests/unit/test_pipeline_backend_execution_env.py -k 'string_network_image or ppi' -q
  • Final corrected result: 27 passed, 5 deselected in 7.27s.
• Combined regression command:
  • /home/xia-lab/miniconda3/envs/test4py311/bin/python -m pytest tests/unit/test_id_resolution.py tests/unit/test_ppi_id_resolution.py tests/unit/test_ppi_string_policy.py tests/unit/test_pipeline_backend_execution_env.py -q
  • Final corrected result: 167 passed in 8.44s.
• Static verification:
  • /home/xia-lab/miniconda3/envs/test4py311/bin/python -m py_compile gfa_core/ppi_string_policy.py gfa_core/string_rate_gate.py skills/ppi/run.py apps/web/pipeline_backend.py
  • Result: exit 0.

All earlier internal PASS results predate at least one subsequent authoritative rejection and are superseded. The latest internal review freshly verified submitted-ID taxon validation, response membership and score threshold, fail-closed authoritative backend selection, truthful direct/projected raw provenance, strict image status/final URL, official positive fixtures, and authorized scope; it returned PASS with no Critical, Important, or Minor findings. Main verification, anti-pattern, and spec/code-quality reviews remain authoritative.

All unit HTTP clients are local fakes. The two concurrency tests use real forked processes and local files only; no test contacts STRING.

Files and layers

• gfa_core/string_rate_gate.py: shared host-level request pacing.
• gfa_core/ppi_string_policy.py: parent-authorized canonical-code self-resolution invariant.
• skills/ppi/run.py: typed STRING protocol, relationship origins, deterministic resolution, and empty-network classification.
• apps/web/pipeline_backend.py: active optional STRING image/SVG request hardening plus the parent-authorized authoritative PPI skill selection branch, solely removing the legacy scientific fallback.
• tests/unit/test_ppi_id_resolution.py: offline protocol, resolution, provenance, and multiprocessing coverage.
• tests/unit/test_ppi_string_policy.py: one parent-authorized legacy test migration from method monkeypatching to explicit fake STRING client injection; no policy assertion was relaxed.
• tests/unit/test_pipeline_backend_execution_env.py: parent-authorized authoritative-entrypoint fail-closed regression plus official response metadata and redirect assertions on only the same two image positive fakes.
• .superpowers/sdd/task-3-report.md: this checkpoint.

Scope and remaining risks

• Task 4 Reset/backend discovery and CLI --id-map wiring were not implemented.
• Task 5 contract, final manifest schema, frontend labels, and diagnosis changes were not implemented.
• No live STRING or full real-job validation was run; that belongs to Task 6. Stable-version and response shapes are covered with realistic fake payloads.
• Existing pytest startup emits a RequestsDependencyWarning for the environment's urllib3/chardet versions; tests still pass and this task did not change dependencies.
• No service or Celery restart was needed. No diagnostic record was updated because diagnosis is Task 5 scope.