Diagnose neighborhood API performance

[jithinmathws]

Summary

• reproduce the MG-DE-009 neighborhood latency signal using a deterministic 1,727-material local fixture
• measure database queries, neighbor construction and scoring, graph assembly, serialization, payload size, and end-to-end latency
• identify the per-expanded-node query pattern and repeated dense association materialization as the root causes
• document remediation options and explicit acceptance criteria before implementing any fix
• add a guarded, reproducible local diagnostic runner

Principal finding

For the default depth-two, limit-25 request:

• 25 neighbor-service calls
• 150 SQL queries
• 9,657-byte response
• approximately 2.16 seconds locally without artificial latency
• approximately 17.13 seconds with 100 ms simulated latency per query

The sensitivity result closely reproduces the 16.24-second MG-DE-009 production observation.

Serialization and final payload size are not material causes at this scale.

Independent Windows reproduction

• fixture: 1,727 materials, 4,144 material-element rows
• warm median service time: 1,934.218 ms
• zero-delay end-to-end time: 2,162.897 ms
• 25 ms/query: 6,242.560 ms
• 50 ms/query: 9,572.574 ms
• 100 ms/query: 17,133.475 ms
• query count remained 150
• payload remained 9,657 bytes

Validation

• focused neighborhood suite: 9 passed
• complete suite: 933 passed, 1 skipped
• Ruff: passed
• benchmark JSON validation: passed
• git diff --check: passed

Boundaries

Diagnosis only. No runtime optimization, endpoint-semantic change, schema change, database migration, production access, deployment, restart, or provider change is included.