Resolve OCL canonicals via $resolveReference instead of guessing

[italomacedo]

What

Teaches the OCL integration to ask OCL which repo holds a canonical URL, using OCL's
$resolveReference
operation, instead of guessing. This is the client half of OCL issue #2261, "replace repo/repo
version requests with $resolveReference".

Today cm-ocl answers "which repo holds this canonical?" heuristically: it derives a search
token from the URL, pages through /orgs/{org}/sources/?q=..., and matches canonical_url on
whatever the search surfaces. $resolveReference answers it authoritatively in one call.

Scope is deliberately narrow. $resolve is not touched: that is Terminology Ecosystem
infrastructure at the coordination layer, and nothing here may make OCL's resolution path depend
on a FHIRsmith facade being in front of it. registry/ is untouched and its tests still pass.

Nothing changes without a token

$resolveReference is authenticated on every OCL instance probed, while the /orgs/ enumeration
it replaces is public. So the resolver is constructed disabled when no token= is configured,
and every caller falls back to the path it used before. Existing ocl: source lines behave
exactly as they do today; adding a token is opt-in. token= is not new — tx/library.js has
always parsed it — it simply carries weight it did not before.

Configuration	Canonical → repo	Behaviour
ocl:https://ocl.example.org	/orgs/{org}/sources/?q= search	unchanged
ocl:https://ocl.example.org|token=...	$resolveReference	authoritative, falls back on failure

The resolver also disables itself permanently on 404 (not implemented) or 401/403
(credentials rejected), so an instance without the operation degrades to today's behaviour rather
than failing.

Commits

Each stands alone and is separately reviewable:

$resolveReference client	new tx/ocl/resolve/reference-resolver.js
user-owned repos	cm-ocl filtered candidates with startsWith('/orgs/') in three places, silently discarding every /users/{user}/... repo. Needs no token.
wire into ConceptMap	resolver first, search as fallback
docs	the token's role, and what the operation does not do
log which path ran	resolver and search return the same thing, so success was unobservable
canonical casing	searchConceptMaps lower-cased every param. #norm() lower-cases anyway so nothing noticed, and the text search tolerated it — but $resolveReference matches exactly, so every lookup silently fell back
source mappings	see below
canonical_url	the repo's own canonical was being discarded in favour of echoing the request back

The concept×mappings loop

searchConceptMaps has no concept code — it asks "what mappings does this source have?" — but
answered that with the per-concept endpoint: list the concepts, then one request per concept.

• Correctness. The concept listing is capped at maxSearchPages (10 × 100 = 1000). LOINC has
  184,683 concepts, so it only ever saw 0.5% of them; any mapping past the first 1000 was
  silently invisible. No error — just fewer results.
• Cost. Up to 1000 sequential requests per source. loinc, snomed, v3-ActCode and cmed
  all timed out and returned nothing at all.

{source}/mappings/ answers the actual question in one paginated call. Verified equivalent before
switching — for AlcoolSPA_uso_Mangara both paths return the identical mapping set, one in 1
request instead of 4.

canonical	before	after
http://loinc.org	timeout (45s+)	0.44s, 1 ConceptMap
http://snomed.info/sct	timeout (45s+)	0.98s, 5 ConceptMaps
v3-ActCode	timeout (45s+)	0.18s
cmed	timeout (45s+)	0.16s

loinc and snomed previously returned nothing, so this restores results rather than merely
speeding them up.

The per-concept endpoint stays where it belongs: findConceptMapForTranslation has a sourceCode
and asks about that one concept, so its single targeted request is already right. Untouched.

Testing

170 tests, positive and negative. tx/ocl/resolve/reference-resolver.js is at 100% statements /
lines / functions, 96.8% branches:

npx jest --testPathPattern "tests/ocl" --coverage --collectCoverageFrom="tx/ocl/resolve/**/*.js"

jest.config.js is untouched. Note it globs collectCoverageFrom: ['**/*.js'] and not
**/*.cjs, so the .cjs modules in tx/ocl are invisible to coverage and the command documented
in tx/ocl/README.md reports on their one-line .js re-export stubs. That is why the new module
is plain .js — it makes the number real without changing the config. The cm-ocl.cjs edits are
covered behaviourally but cannot contribute to a coverage figure. README now says so.

Verified end to end against a live OCL instance, not just mocks:

[OCL] $resolveReference resolved
  https://mangara.hsl.org.br/fhir/CodeSystem/AlcoolSPA_uso_Mangara
  -> /orgs/HL7/sources/AlcoolSPA_uso_Mangara/ (namespace /, via namespace)

Worth stating plainly: the casing bug, the 0.5% ceiling and the echoed canonical were all
invisible to the mocked tests — a mock returns what you told it to return. All three surfaced
only by running the server against real OCL. The response-shape tests are now built from a
captured payload rather than from the documented example, which omits most fields and reports
type: "Source Version" where OCL actually returns "Source".

Notes for reviewers

• Namespace is derived from the existing org= (/orgs/{org}/), else / (global, OCL's own
  default). A FHIR request carries no namespace, so it is bound per source entry. Explicit
  namespace= would need parseOclConfig in tx/library.js and is left for later.
• Namespace is a preference, not a boundary: OCL falls through to the Global URL Registry, so
  a namespaced resolve can still return another owner's repo. Sandboxing would have to be enforced
  client-side; not implemented, and documented as such.
• Discovery is unchanged. $resolveReference resolves a known reference and cannot list, so
  the /orgs/ enumeration stays. This PR does not make the integration scale to all of OCL Online
  — that needs lazy provider registration in tx/library.js.
• Batching groups references by namespace and uses the request-level query parameter; OCL
  discourages the per-reference namespace field, so it is never emitted.
• Results are positional, so a count mismatch discards the whole group rather than risk
  attributing a resolution to the wrong canonical.

🤖 Generated with Claude Code