OpenConceptLab/ocl_issues#2558 | Divert target-repo concept fetch to custom lookup source

[paynejd]

Fixes the symptom in ocl_issues#2558. @snyaggarwal for review.

⚠️ Not 100% certain this is the right approach — posting for your judgment. The diagnosis is solid; the fix location/shape is the open question (see below). Happy to move it elsewhere or scope it differently.

Problem

When a map project uses a custom lookup source because its target repo is a definition/metadata-only canonical repo (e.g. the public WHO ICD-11-WHO repo, kept content-empty under WHO's license), some concept-detail GETs still hit the empty target repo and 404.

ensureLoaded resolves not-yet-full ConceptDefinitions two ways:

• Branch 2 (no ocl_url → $resolveReference) already honors lookupConfig.url.
• Branch 1 (has ocl_url → direct GET) fetched the ocl_url verbatim, never consulting lookupConfig.

ocl-bridge / ocl-ciel-bridge cascade targets resolve against the target repo (concept_identity.cascade_target.reference_source: 'target_repo') and arrive with an ocl_url that points into the target repo → they take Branch 1 → fetch the empty repo → 404.

Evidence

ICD-11 IMO eval run (target WHO/ICD-11-WHO, lookup OpenMRS-OCL-Squad/ICD-11-WHO-Mapper): 6 GETs hit /orgs/WHO/sources/ICD-11-WHO/concepts/<code>/ and 404'd; the same codes return 200 from the lookup source. Failing URLs were not double-encoded → confirms Branch 1 (only Branch 2 double-encodes). The fetch is state-driven (mergeIntoRowMatchState → ensureLoaded on not-full arrival), not triggered by opening the details panel.

Change

In Branch 1, when the concept belongs to the target repo and a lookup source is configured, fetch the lookup source by code instead of the target-repo ocl_url:

const tr = ctx?.target_repo
const divertedUrl = (lookupConfig?.url && tr && conceptBelongsToTargetRepo(def, tr.canonical_url, tr.relative_url))
  ? buildLookupConceptUrl(lookupConfig.url, def.reference?.code)
  : null
directFetches.push({key, oclUrl: divertedUrl || def.ocl_url})

• Reuses the existing conceptBelongsToTargetRepo predicate (canonical-equal OR ocl_url starts with the target relative URL) rather than a hand-rolled equality.
• New buildLookupConceptUrl (normalizers) shares the Branch 2 double-encode so a code resolves to the same URL on both paths. Pure + unit-tested.
• fetchConceptByOclUrl's existing URL-dedup + 404-retry apply unchanged.

npm test 145/145, eslint clean.

Why no server-side change

WHO/ICD-11-WHO being empty is by design (definition-only canonical repo, WHO license). Content lives in the lookup source. So this is purely client-side routing.

Open questions for review (the "not certain" parts)

1. Right layer? This fixes the direct-fetch branch in ensureLoaded. Should the diversion instead live where the cascade-target ConceptDefinition.ocl_url is minted (normalizers cascadeTargetToConceptDefinition), so the stub never carries a target-repo ocl_url in the first place? That might be the more principled fix.
2. Scope. The predicate diverts all target-repo concepts, not just bridge cascade targets. Standard $match candidates already carry a lookup-source ocl_url, so rebuilding lands at the same place (harmless) — but confirm that's acceptable vs. narrowing to bridge targets only.
3. Versioning. I deliberately fetch lookupConfig.url as configured and don't graft the target's pinned version onto it (matches Branch 2). Correct for your intended semantics?
4. Relation to #2515 ("separate lookup sources per algorithm / fallback to target repo") — should this fold into that work instead of landing standalone?

Background analysis (HAR forensics + repro) lives in the ocl-mapper-eval 2026-06-02-imo-prepub run notes; happy to share.

[snyaggarwal]

1. I feel ensureLoaded is the right place for this fix, we dont want to change ConceptDefinition. Also if/when tomorrow we have license it should work with existing definitions
2. Its ok.
3. Yes thats correct
4. That should be separate work

[snyaggarwal]

LGTM, merging