fhirsmith 0.18.0 → 0.18.2

package/tx/library/designations.js

@@ -564,6 +564,19 @@ class Designations {
     return this._langsMatch(langList, cd.language, LangMatchType.LANG, defLang);
   }
 
+  /**
+   * Note, in the set of supplements to report as used, the supplement a designation came from (if
+   * it came from one). Designations from a supplement carry it as .supplement (see
+   * CodeSystemProvider._listSupplementDesignations); this used to look for .source, which is never
+   * set on a designation, so a supplement that only supplied the chosen display - a global language
+   * pack, typically - was never reported as used.
+   */
+  _reportSupplement(supplements, cd) {
+    if (supplements && cd && cd.supplement && cd.supplement.vurl) {
+      supplements.add(cd.supplement.vurl);
+    }
+  }
+
   /**
    * Find the preferred designation for given language preferences
    */
@@ -576,39 +589,29 @@ class Designations {
       // No language list, prefer base designations
       for (const cd of this.designations) {
         if (this._isPreferred(cd) && cd.isActive()) {
-          if (supplements && cd.source) {
-            supplements.add(cd.source);
-          }
+          this._reportSupplement(supplements, cd);
           return cd;
         }
       }
       for (const cd of this.designations) {
         if (this.isDisplay(cd) && cd.isActive()) {
-          if (supplements && cd.source) {
-            supplements.add(cd.source);
-          }
+          this._reportSupplement(supplements, cd);
           return cd;
         }
       }
       for (const cd of this.designations) {
         if (this.isDisplay(cd)) {
-          if (supplements && cd.source) {
-            supplements.add(cd.source);
-          }
+          this._reportSupplement(supplements, cd);
           return cd;
         }
       }
       for (const cd of this.designations) {
         if (this._isPreferred(cd)) {
-          if (supplements && cd.source) {
-            supplements.add(cd.source);
-          }
+          this._reportSupplement(supplements, cd);
           return cd;
         }
       }
-      if (supplements && this.designations[0].source) {
-        supplements.add(this.designations[0].source);
-      }
+      this._reportSupplement(supplements, this.designations[0]);
       return this.designations[0];
     }
 
@@ -628,25 +631,19 @@ class Designations {
           // because the FSN was emitted first.
           for (const cd of this.designations) {
             if (this._langMatches(lang, cd.language, matchType) && this._isPreferred(cd) && (!activeOnly || cd.isActive())) {
-              if (supplements && cd.source) {
-                supplements.add(cd.source);
-              }
+              this._reportSupplement(supplements, cd);
               return cd;
             }
           }
           for (const cd of this.designations) {
             if (this._langMatches(lang, cd.language, matchType) && this.isDisplay(cd) && (!activeOnly || cd.isActive())) {
-              if (supplements && cd.source) {
-                supplements.add(cd.source);
-              }
+              this._reportSupplement(supplements, cd);
               return cd;
             }
           }
           for (const cd of this.designations) {
             if (this._langMatches(lang, cd.language, matchType) && (!activeOnly || cd.isActive())) {
-              if (supplements && cd.source) {
-                supplements.add(cd.source);
-              }
+              this._reportSupplement(supplements, cd);
               return cd;
             }
           }
@@ -655,14 +652,10 @@ class Designations {
     }
     for (const cd of this.designations) {
       if (!cd.language && this.isDisplay(cd) && cd.isActive()) {
-        if (supplements && cd.source) {
-          supplements.add(cd.source);
-        }
+        this._reportSupplement(supplements, cd);
         return cd;
       } if (!cd.language && this.isDisplay(cd)) {
-        if (supplements && cd.source) {
-          supplements.add(cd.source);
-        }
+        this._reportSupplement(supplements, cd);
         return cd;
       }
     }

package/tx/library/tho-precedence.js

@@ -0,0 +1,40 @@
+//
+// THO precedence for value sets and concept maps (see Provider.applyTHOPrecedence).
+//
+// Where hl7.terminology provides a resource with the same url as one in the FHIR core
+// package, THO's copy is the one used - versions were reset when content moved to THO, so
+// version order can't decide. But the core copy is still what a reference that names its
+// version (url|5.0.0) means, so it stays available to that reference, and only to it.
+//
+
+const { VersionUtilities } = require('../../library/version-utilities');
+
+/**
+ * Whether a package provider should keep a map key for a resource that THO also provides.
+ * Only the keys that name a version are kept - url|version, and url|major.minor for a
+ * semver version - and only where THO doesn't provide that version itself. The bare url
+ * (the default for a reference with no version) and the resource's id are not kept.
+ *
+ * @param {string} key - the map key
+ * @param {{url: string, version: string}} resource - the core package's resource
+ * @param {Set<string>} thoVersions - the versions of the url that hl7.terminology provides
+ * @returns {boolean}
+ */
+function keepForPinnedReference(key, resource, thoVersions) {
+  const version = resource.version;
+  if (!version) {
+    return false;
+  }
+  if (key === resource.url + '|' + version) {
+    return !thoVersions.has(version);
+  }
+  if (VersionUtilities.isSemVer(version)) {
+    const mm = VersionUtilities.getMajMin(version);
+    if (mm && key === resource.url + '|' + mm) {
+      return ![...thoVersions].some(v => v && VersionUtilities.isSemVer(v) && VersionUtilities.getMajMin(v) === mm);
+    }
+  }
+  return false;
+}
+
+module.exports = { keepForPinnedReference };

package/tx/openapi-operations.js

@@ -332,7 +332,8 @@ const OPERATIONS = [
       p('name', 'string', '1', 'The closure table', { min: 1 }),
       p('concept', 'Coding', '*', 'A concept to add'),
       p('version', 'string', '1', 'Return the changes since this version of the table, instead of adding concepts'),
-      p('reset', 'boolean', '1', 'Start the table again')
+      p('reset', 'boolean', '1', 'Start the table again'),
+      p('dispose', 'boolean', '1', 'The client has finished with the table, and the server can delete it (not in the specification)')
     ],
     returns: 'ConceptMap',
     returnsDoc: 'The new relationships'

package/tx/provider.js

@@ -286,10 +286,13 @@ class Provider {
       }
     }
 
+    // Ask each code system version once: an implicit map can belong to one version
+    // only (a SNOMED CT edition's maps are named by its edition URI)
     let uris = new Set();
     for (let csp of this.codeSystemFactories.values()) {
-      if (!uris.has(csp.system())) {
-        uris.add(csp.system());
+      const key = csp.system() + '|' + csp.version();
+      if (!uris.has(key)) {
+        uris.add(key);
         let cm = await csp.findImplicitConceptMap(url, version);
         if (cm) {
           return cm;
@@ -343,16 +346,19 @@ class Provider {
       // version (every SNOMED edition, say) is asked, since whether a map exists and what
       // it says can depend on which version the source coding is in. The factory decides
       // from sourceVersion whether it is the one being asked about.
+      // The same goes for the target system: a map from another system into one SNOMED
+      // edition (LOINC codes to the concepts that carry them, say) belongs to that edition.
+      const targetBase = targetSystem.split('|')[0];
       let uris = new Set();
       let asked = new Set(); // a factory is registered under several keys (system, system|version...)
       for (let csp of this.codeSystemFactories.values()) {
         if (asked.has(csp)) {
           continue;
         }
-        if (csp.system() === sourceSystem || !uris.has(csp.system())) {
+        if (csp.system() === sourceSystem || csp.system() === targetBase || !uris.has(csp.system())) {
           uris.add(csp.system());
           asked.add(csp);
-          await csp.findImplicitConceptMaps(conceptMaps, sourceSystem, sourceVersion, targetSystem);
+          await csp.findImplicitConceptMaps(conceptMaps, sourceSystem, sourceVersion, targetSystem, sourceCode);
         }
       }
     }
@@ -626,27 +632,20 @@ class Provider {
    * moved from the FHIR core packages to terminology.hl7.org has been QA'd there since, and
    * its versions went backwards (coverage-selfpay is 4.0.1 in hl7.fhir.r4.core but 1.0.1 in
    * hl7.terminology), so version precedence can't decide between them. Instead, a code system
-   * from an hl7.terminology package replaces every code system with the same url from a FHIR
-   * core package - none of the core versions stay available.
+   * from an hl7.terminology package is always the default for its url - what a reference with
+   * no version gets - whatever versions the FHIR core packages have.
    *
-   * Except: hl7.fhir.r4.core has the v2 tables 0006, 0360 and 0391 in two versions each,
-   * with the version in the url (http://terminology.hl7.org/CodeSystem/v2-0006|2.1 - see
-   * urlHadVersion in loadNpm). hl7.terminology doesn't publish those versions, so they stay
-   * available by url|version; THO's code system is the default for the url.
+   * The core versions stay available by url|version, where THO doesn't provide that version
+   * itself: a reference that names its version (url|5.0.0) means the core one, and there's
+   * nothing else it can mean. They are never the default while THO provides the url (see also
+   * deleteCodeSystem).
    */
   addCodeSystem(cs) {
     if (Provider.#isTHOPackage(cs.sourcePackage)) {
-      for (const [key, t] of [...this.codeSystems]) {
-        if (t.url === cs.url && VersionUtilities.isCorePackage(t.sourcePackage)
-          && (key === t.url || !t.urlHadVersion)) {
-          this.codeSystems.delete(key);
-        }
-      }
-    } else if (VersionUtilities.isCorePackage(cs.sourcePackage) && !cs.urlHadVersion) {
-      // THO's code system is always the default for its url
+      // THO's code system takes over the default from a core one; the core versions stay
       const t = this.codeSystems.get(cs.url);
-      if (t && Provider.#isTHOPackage(t.sourcePackage)) {
-        return;
+      if (t && t.url === cs.url && VersionUtilities.isCorePackage(t.sourcePackage)) {
+        this.codeSystems.delete(cs.url);
       }
     }
     const existing = this.codeSystems.get(cs.url);
@@ -671,45 +670,63 @@ class Provider {
    * THO precedence for value sets and concept maps, as for code systems (see addCodeSystem):
    * once the library's providers have been added after this endpoint's core package, the core
    * package's value sets and concept maps whose urls an hl7.terminology package also provides
-   * are left out. (No core value set or concept map has the version in its url.)
+   * are only available to a reference that names their version (and THO doesn't provide that
+   * version itself). They are never what a reference with no version gets, and they aren't
+   * read by id, found by search, or used for translation unless asked for.
    */
   applyTHOPrecedence() {
-    const thoValueSets = new Set();
+    const thoValueSets = new Map();
     for (const vp of this.valueSetProviders) {
       if (vp instanceof PackageValueSetProvider && Provider.#isTHOPackage(vp.sourcePackage())) {
         for (const vs of vp.valueSetMap.values()) {
-          thoValueSets.add(vs.url);
+          Provider.#addVersion(thoValueSets, vs);
         }
       }
     }
-    const thoConceptMaps = new Set();
+    const thoConceptMaps = new Map();
     for (const cmp of this.conceptMapProviders) {
       if (cmp instanceof PackageConceptMapProvider && Provider.#isTHOPackage(cmp.sourcePackage())) {
         for (const cm of cmp.conceptMapMap.values()) {
-          thoConceptMaps.add(cm.url);
+          Provider.#addVersion(thoConceptMaps, cm);
         }
       }
     }
     for (const vp of this.valueSetProviders) {
       if (vp instanceof PackageValueSetProvider && VersionUtilities.isCorePackage(vp.sourcePackage())) {
-        vp.excludeUrls(thoValueSets);
+        vp.keepPinnedOnly(thoValueSets);
       }
     }
     for (const cmp of this.conceptMapProviders) {
       if (cmp instanceof PackageConceptMapProvider && VersionUtilities.isCorePackage(cmp.sourcePackage())) {
-        cmp.excludeUrls(thoConceptMaps);
+        cmp.keepPinnedOnly(thoConceptMaps);
       }
     }
   }
 
+  static #addVersion(map, resource) {
+    if (!resource || !resource.url) {
+      return;
+    }
+    if (!map.has(resource.url)) {
+      map.set(resource.url, new Set());
+    }
+    if (resource.version) {
+      map.get(resource.url).add(resource.version);
+    }
+  }
+
   deleteCodeSystem(cs) {
     this.codeSystems.delete(cs.vurl);
     this.codeSystems.delete(cs.url);
     // If other versions of the SAME url survive, re-point the unversioned [url]
     // entry at the most-recent surviving version. Otherwise leave it deleted.
+    // THO precedence (see addCodeSystem): while a THO version survives, a core one
+    // can't become the default, however recent its (reset) version looks
+    const survivors = [...new Set(this.codeSystems.values())].filter(t => t.url === cs.url);
+    const tho = survivors.filter(t => Provider.#isTHOPackage(t.sourcePackage));
     let existing = null;
-    for (let t of this.codeSystems.values()) {
-      if (t.url === cs.url && (!existing || t.isMoreRecent(existing))) {
+    for (let t of (tho.length > 0 ? tho : survivors)) {
+      if (!existing || t.isMoreRecent(existing)) {
         existing = t;
       }
     }

package/tx/sct/documentation.md

@@ -35,14 +35,20 @@ that the server does not use. `filterECL` is the one that matters.
   reference set's own fields (concept, integer and string typed from the RF2
   file name). Since inactive member rows are dropped at import, `active = false`
   never matches.
-- `AND` / `OR` / `MINUS` (and `,`), with the ECL 6.4 rule that conjunction and
+- Refinements: `=` and `!=` against an expression value (`!=` counts the
+  occurrences whose value is outside the set, so `A != X` needs at least one
+  A that is not X, and `[0..0] A != X` means every A is X); reversed
+  attributes (`R A = X`: the concept is the value of an A on something in X,
+  evaluated over the concept's inbound relationships); attribute names that
+  are a concept, `*`, or any sub expression (`<< 762705008 = ...`); attribute
+  sets joined by `AND`, `OR` or `,`, with brackets; attribute groups,
+  including `AND`/`OR` inside and between groups; attribute and group
+  cardinality, including `[0..0]`. Cardinality counts occurrences per role
+  group, per the SNOMED Computable Languages Group ruling (see
+  `_countAttributeMatches`).
+- `AND` / `OR` / `MINUS`, and `,` as a conjunction at the expression level as
+  well as in refinements, with the ECL 6.4 rule that conjunction and
   disjunction cannot be mixed without brackets.
-- Refinements: `=` against an expression value; attribute names that are a
-  concept, `*`, or any sub expression (`<< 762705008 = ...`); attribute sets
-  joined by `AND`, `OR` or `,`, with brackets; attribute groups, including
-  `AND`/`OR` inside and between groups; attribute and group cardinality,
-  including `[0..0]`. Cardinality counts occurrences per role group, per the
-  SNOMED Computable Languages Group ruling (see `_countAttributeMatches`).
 - Dotted expressions (`< X . 363698007`, `. << 363698007`, `. (A OR B)`).
 - `{{ C ... }}` concept filters on `active`, `definitionStatus`,
   `definitionStatusId`, `moduleId` and `effectiveTime`.
@@ -56,26 +62,37 @@ that the server does not use. `filterECL` is the one that matters.
   must be satisfied by a single description; separate blocks may be satisfied
   by different descriptions. Only active descriptions are considered unless
   the block has an `active` filter.
+- Concrete values in refinements - numeric (`= #5`, `>= #1.5`, `!= #-1`),
+  string (`= "x"`, `= match:"x"`, a set) and boolean (`= true`) - against the
+  concrete value relationships, which the importer reads from
+  `sct2_RelationshipConcreteValues_*` into cache version 19. Numbers compare
+  as numbers (`#5` matches `#5.0`); strings use the same match / wild
+  semantics as description terms; a value of another kind never matches.
+  An edition imported before version 19 has no concrete values and reports
+  such a refinement as unsupported rather than answering with nothing.
+- History supplements: `{{ + HISTORY }}` (= MAX), `HISTORY-MIN` (SAME AS),
+  `HISTORY-MOD` (SAME AS, WAS A, REPLACED BY, PARTIALLY EQUIVALENT TO),
+  `HISTORY-MAX` (every reference set under 900000000000522004 |Historical
+  association|), `HISTORY (*)` and `HISTORY (expression)`: the inactive
+  concepts that the selected association reference sets associate with a
+  concept in the result are added to it. A reference set the edition does not
+  carry contributes nothing. Whether a bare `HISTORY` means MAX is taken from
+  Snow Owl's reading of the specification - to be confirmed.
+- Alternate identifiers (`LOINC#14394-1`, `"LOINC#14394-1"`): the scheme
+  alias names an identifier scheme (`IDENTIFIER_SCHEMES` in `cs-snomed.js`:
+  LOINC = 30051010000102, from the LOINC Extension's `sct2_Identifier` file,
+  cache version 18+), the code resolves to the concept(s) carrying it, and
+  hierarchy operators apply to them as to any set. An unknown scheme or a
+  code nobody carries is `INVALID_ECL`.
 - Comments (`/* ... */`), terms (`|...|`, not checked against descriptions).
 
 ### Parsed but reported as unsupported
 
-- Reverse attributes (`R 363698007 = ...`).
-- `!=` against an expression value in a refinement.
-- Concrete values in refinements - numeric (`= #5`, `>= #1.5`), string
-  (`= "x"`, `= match:"x"`), boolean (`= true`). The importer does not read
-  `sct2_RelationshipConcreteValues_*`, so no concrete values are in the cache
-  to compare against. Supporting them means extending the importer and the
-  relationship record, and rebuilding every cache.
-- Alternate identifiers (`"ICD10#A01.1"`, `SCTID#123`). No alternate
-  identifier reference sets are loaded.
 - Reference set field selection on member-of (`^ [targetComponentId] refset`,
   `^ [referencedComponentId, targetComponentId] refset`). Deliberate: the
   selected fields, and the referenced components of many reference sets,
   are descriptions or other non-concept components, which an expansion has
   no way to represent.
-- History supplements (`{{ + HISTORY-MIN / MOD / MAX }}`). The association
-  reference sets they draw on are loaded, so this is implementable.
 
 ### Not parsed
 
@@ -99,7 +116,13 @@ that the server does not use. `filterECL` is the one that matters.
 - `^` on a concept that is not a reference set yields an empty result rather
   than an error (Snowstorm's behaviour; agreed in the tx-ecosystem suite).
   `^` on a reference set whose members are descriptions (a language reference
-  set) is reported as unsupported - there are no concepts to return.
+  set) is reported as unsupported when that reference set is named explicitly
+  - there are no concepts to return. Inside a computed operand (`^ *`,
+  `^ (< 900000000000455006)`) such a reference set contributes nothing and
+  the rest of the operand still counts.
+- An attribute name without a comparison (`< X : 363698007`, or `(< X : A = v
+  OR B)` where the OR binds inside the refinement) is a syntax error, as the
+  grammar requires.
 - The ECL result for a value set filter is cached per (value set, code system
   version), so the first expansion of a large constraint is slow and later ones
   are not.
@@ -181,8 +204,9 @@ role group pairing.
 
 - Stated relationships and the OWL axiom reference sets. Everything is driven
   by the distributed inferred relationships; there is no classification.
-- Concrete value relationships (see ECL above).
-- Alternate identifier reference sets.
+- Concrete value relationships are read into cache version 19 (October 2026);
+  caches built before that have none, and a concrete-value ECL refinement on
+  them is reported as unsupported.
 - Inactive reference set member rows (only active rows are stored).
 - Module ids and definition status on concepts are recorded by the current
   importer; caches built before mid-2026 have neither (every concept looks

package/tx/sct/ecl.js

@@ -538,8 +538,11 @@ class ECLParser {
     // this compound sequence and reject a mix (e.g. "<< A OR << B AND << C").
     let compoundOp = null;
 
-    while (this.match(ECLTokenType.AND, ECLTokenType.OR, ECLTokenType.MINUS)) {
-      const operator = this.current;
+    // "," is a conjunction in the ECL grammar (conjunction = "AND" / ","), at
+    // this level as well as in refinements; a comma that reaches here was not
+    // claimed by a refinement.
+    while (this.match(ECLTokenType.AND, ECLTokenType.OR, ECLTokenType.MINUS, ECLTokenType.COMMA)) {
+      const operator = this.match(ECLTokenType.COMMA) ? { ...this.current, type: ECLTokenType.AND } : this.current;
       if (compoundOp !== null && operator.type !== compoundOp) {
         throw new Error(
           'Ambiguous ECL expression: conjunction, disjunction and exclusion ' +
@@ -726,18 +729,30 @@ class ECLParser {
       return { type: ECLNodeType.FILTER_CONSTRAINT, kind, filters };
     }
 
-    if (kind !== 'M') {
-      // Skip to the closing }} keeping the raw text for diagnostics
-      const raw = [];
-      while (!this.match(ECLTokenType.RFILTER)) {
-        if (this.match(ECLTokenType.EOF)) {
-          this.error('Unterminated filter constraint - missing }}');
+    if (kind === '+') {
+      // historySupplement = "{{" "+" "HISTORY" [ "-MIN" / "-MOD" / "-MAX" / "(" (expressionConstraint / "*") ")" ] "}}"
+      if (!this.match(ECLTokenType.SCTID) || !/^HISTORY(-MIN|-MOD|-MAX)?$/i.test(this.current.value)) {
+        this.error('Expected HISTORY, HISTORY-MIN, HISTORY-MOD or HISTORY-MAX after {{ +');
+      }
+      const word = this.current.value.toUpperCase();
+      this.advance();
+      const node = { type: ECLNodeType.FILTER_CONSTRAINT, kind, profile: word === 'HISTORY' ? 'MAX' : word.substring(8) };
+      if (this.match(ECLTokenType.LPAREN)) {
+        if (node.profile !== 'MAX' || word !== 'HISTORY') {
+          this.error('A history profile (HISTORY-MIN/MOD/MAX) cannot also name reference sets');
         }
-        raw.push(this.current.value);
         this.advance();
+        if (this.match(ECLTokenType.WILDCARD)) {
+          this.advance();
+          node.profile = 'MAX';
+        } else {
+          node.profile = 'EXPLICIT';
+          node.refsets = this.parseExpressionConstraint();
+        }
+        this.expect(ECLTokenType.RPAREN);
       }
-      this.advance(); // }}
-      return { type: ECLNodeType.FILTER_CONSTRAINT, kind, raw: raw.join(' ') };
+      this.expect(ECLTokenType.RFILTER);
+      return node;
     }
 
     const filters = [this.parseMemberFilter()];
@@ -1430,6 +1445,14 @@ class ECLParser {
       };
     }
 
+    if (!comparison) {
+      // eclAttribute = [cardinality] [reverseFlag] eclAttributeName comparison - a
+      // bare name is a syntax error. This is what "(A : B = C OR D)" trips on:
+      // the OR binds inside the refinement, so D is an attribute name without a
+      // comparison.
+      this.error('Expected a comparison operator (=, !=, <, <=, >, >=) after the attribute name');
+    }
+
     return {
       type: ECLNodeType.ATTRIBUTE,
       cardinality,

package/tx/sct/structures.js

@@ -1358,7 +1358,7 @@ class SnomedFileReader {
     }
 
     // Determine settings based on cache version string (matching Pascal logic)
-    if (result.cacheVersion === '17') { // SNOMED_CACHE_VERSION_CURRENT
+    if (result.cacheVersion === '17' || result.cacheVersion === '18' || result.cacheVersion === '19') { // 18 = 17 + alternate identifiers; 19 = 18 + concrete values
       result.hasLangs = true;
     } else if (result.cacheVersion === '16') { // Assuming this is UTF8 version for now
       result.isUTF16 = false;
@@ -1379,9 +1379,22 @@ class SnomedFileReader {
       result.activeRoots.push(this.readUInt64());
     }
 
-    // Read default language LAST
+    // Read default language
     result.defaultLanguage = this.readInteger();
 
+    // Alternate identifiers (version 18): [[scheme, module, code, conceptId], ...]
+    result.identifiers = [];
+    if (result.cacheVersion === '18' || result.cacheVersion === '19') {
+      result.identifiers = JSON.parse(this.readBytes().toString('utf8'));
+    }
+    // Concrete value relationships (version 19): [[sourceId, typeId, group, value], ...].
+    // null (not []) when the cache predates them, so the server can tell "none" from
+    // "not loaded".
+    result.concreteValues = null;
+    if (result.cacheVersion === '19') {
+      result.concreteValues = JSON.parse(this.readBytes().toString('utf8'));
+    }
+
     return result;
   }
 }

package/tx/tx.fhir.org.yml

@@ -20,7 +20,7 @@ sources:
   - internal:hgvs
   - ucum:tx/data/ucum-essence.xml
   - loinc:loinc-2.77-a.db
-  - loinc!:Loinc_2.82.db
+  - loinc!:Loinc_2.83.db
   - rxnorm:rxnorm_03022026.db
   - ndc:ndc-20211101.db
   - unii:unii_20240622.db
@@ -32,7 +32,7 @@ sources:
   - snomed:sct_us_20230301.cache
   - snomed:sct_us_20240301.cache
   - snomed:sct_us_20250901.cache
-  - snomed:sct_test_20250909c.cache
+  - snomed:sct_test_20250909e.cache
   - cpt:CodeSystem-cpt.db|cpt-2023-fragment-0.1.db
   - omop:omop_v20250227.db
   - npm:hl7.terminology=tho

package/tx/vs/vs-package.js

@@ -8,6 +8,7 @@ const { checkContained } = require('../library/canonical-resource');
 const { VersionUtilities } = require('../../library/version-utilities');
 const {validateParameter} = require("../../library/utilities");
 const { applyIdPrefix, stripIdPrefix } = require('../library/resource-ids');
+const { keepForPinnedReference } = require('../library/tho-precedence');
 
 /**
  * Package-based ValueSet provider using shared database layer
@@ -267,7 +268,7 @@ class PackageValueSetProvider extends AbstractValueSetProvider {
 
         // Only process each ValueSet once (use URL to deduplicate)
         const vsUrl = json.url;
-        if (seen.has(vsUrl)) {
+        if (seen.has(vsUrl) || this.#excludedUrls.has(vsUrl)) {
           continue;
         }
 
@@ -460,35 +461,38 @@ class PackageValueSetProvider extends AbstractValueSetProvider {
     return this.#excludedUrls.size === 0 ? urls : urls.filter(url => !this.#excludedUrls.has(url));
   }
 
-  // the value sets left out by excludeUrls - by url, and by their own (unprefixed) id
+  // the value sets left out by keepPinnedOnly - by url, and by their own (unprefixed) id
   #excludedUrls = new Set();
   #excludedIds = new Set();
 
   /**
-   * Leave out the value sets with any of these urls: they can't be fetched, and they aren't
-   * found by search. The FHIR core package's value sets are left out where hl7.terminology
-   * provides the same url (see Provider.applyTHOPrecedence). Must be called once the
-   * provider is initialized - the database is shared, so it isn't changed.
+   * The value sets with these urls are hl7.terminology's to provide (see
+   * Provider.applyTHOPrecedence): from this (core) package they are only available to a
+   * reference that names their version, where THO doesn't provide that version itself. They
+   * aren't the default for their url, can't be read by id, aren't found by search or listed.
+   * Must be called once the provider is initialized - the database is shared, so it isn't
+   * changed.
    *
-   * @param {Set<string>} urls
+   * @param {Map<string, Set<string>>} thoVersions - url -> the versions hl7.terminology provides
    */
-  excludeUrls(urls) {
-    const excluded = new Set();
+  keepPinnedOnly(thoVersions) {
+    const affected = new Set();
     for (const vs of this.valueSetMap.values()) {
-      if (vs && urls.has(vs.url)) {
-        excluded.add(vs);
+      if (vs && thoVersions.has(vs.url)) {
+        affected.add(vs);
       }
     }
     for (const [key, vs] of [...this.valueSetMap]) {
-      if (excluded.has(vs)) {
+      if (affected.has(vs) && !keepForPinnedReference(key, vs, thoVersions.get(vs.url))) {
         this.valueSetMap.delete(key);
       }
     }
-    for (const vs of excluded) {
+    for (const vs of affected) {
       this.#excludedUrls.add(vs.url);
       this.#excludedIds.add(stripIdPrefix(vs.id, this.spaceId) ?? vs.id);
     }
   }
+
 }
 
 module.exports = {

package/tx/vs/vs-vsac.js

@@ -42,7 +42,7 @@ class VSACValueSetProvider extends AbstractValueSetProvider {
     this.apiKey = config.apiKey;
     // Optional operator password for the on-demand resync form (see info()).
     this.resyncPassword = config.resyncPassword || null;
-    this.cacheFolder = folders.ensureFilePath("terminology-cache/vsac");
+    this.cacheFolder = folders.ensureFolder("terminology-cache", "vsac");
     // https: every request carries the API key. (VSAC redirects http to https, but only after
     // the key has been sent in the clear)
     this.baseUrl = (config.baseUrl || 'https://cts.nlm.nih.gov/fhir').replace(/\/+$/, '');