fhirsmith 0.18.1 → 1.0.0

package/tx/cm/cm-package.js

@@ -8,6 +8,8 @@ const { VersionUtilities } = require('../../library/version-utilities');
 const {validateParameter} = require("../../library/utilities");
 const {ConceptMap} = require("../library/conceptmap");
 const { applyIdPrefix, stripIdPrefix } = require('../library/resource-ids');
+const { keepForPinnedReference } = require('../library/tho-precedence');
+const { waitForCache } = require('../library/wait-for-cache');
 
 /**
  * Package-based ConceptMap provider using shared database layer
@@ -17,14 +19,19 @@ class PackageConceptMapProvider extends AbstractConceptMapProvider {
 
   /**
    * @param {PackageContentLoader} packageLoader - Path to the extracted package folder
+   * @param {Object} [options]
+   * @param {boolean} [options.readOnly] - a tx-worker (cluster.md): the cache is the master's; it
+   *   is only read (ConceptMapDatabase reads with OPEN_READONLY), waited for until the master has
+   *   finished it, and never built or changed
    */
-  constructor(packageLoader) {
+  constructor(packageLoader, options = {}) {
     super();
     validateParameter(packageLoader, "packageLoader", PackageContentLoader);
     this.packageLoader = packageLoader;
     // -2: caches from before concept maps were checked for active content in their
     // narrative are rebuilt (see initialize)
     this.dbPath = path.join(packageLoader.packageFolder, '.conceptmaps-2.db');
+    this.readOnly = !!options.readOnly;
     this.database = new ConceptMapDatabase(this.dbPath);
     this.conceptMapMap = new Map();
     this.initialized = false;
@@ -40,6 +47,14 @@ class PackageConceptMapProvider extends AbstractConceptMapProvider {
       return;
     }
     await this.packageLoader.initialize();
+    if (this.readOnly) {
+      await waitForCache(async () => (await this.database.exists()) && (await this.database.isComplete()),
+        `Package ${this.packageLoader.pid ? this.packageLoader.pid() : ''}: concept map cache ${this.dbPath}`);
+      this.conceptMapMap = await this.database.loadAllConceptMaps();
+      this.#applyIdPrefix();
+      this.initialized = true;
+      return;
+    }
     await fs.rm(path.join(this.packageLoader.packageFolder, '.conceptmaps.db'), { force: true }); // the old cache
 
     // A cache is only used once its population finished. One that was cut short
@@ -169,7 +184,7 @@ class PackageConceptMapProvider extends AbstractConceptMapProvider {
 
         // Only process each ConceptMap once (use URL to deduplicate)
         const vsUrl = json.url;
-        if (seen.has(vsUrl)) {
+        if (seen.has(vsUrl) || this.#pinnedOnly.has(vs)) {
           continue;
         }
 
@@ -193,6 +208,20 @@ class PackageConceptMapProvider extends AbstractConceptMapProvider {
               isMatch = false;
               break;
             }
+          } else if (param === 'url') {
+            // a left match, on the url as asked for (not lower cased)
+            const asked = searchParams.find(sp => sp.name === 'url').value;
+            if (!(json.url || '').startsWith(asked)) {
+              isMatch = false;
+              break;
+            }
+          } else if (param === 'version') {
+            // version-aware matching, on the version as asked for (not lower cased)
+            const asked = searchParams.find(sp => sp.name === 'version').value;
+            if (!VersionUtilities.versionSearchMatches(asked, json.version, VersionUtilities.versionAlgorithmOf(json))) {
+              isMatch = false;
+              break;
+            }
           } else if (param === 'jurisdiction') {
             // Special handling for jurisdiction - array of CodeableConcept
             if (!this._matchJurisdiction(json.jurisdiction, searchValue)) {
@@ -330,35 +359,39 @@ class PackageConceptMapProvider extends AbstractConceptMapProvider {
     return this.packageLoader.id();
   }
 
-  // the concept maps left out by excludeUrls, by their own (unprefixed) id
+  // the concept maps that keepPinnedOnly restricted, by their own (unprefixed) id, and themselves
   #excludedIds = new Set();
+  #pinnedOnly = new Set();
 
   /**
-   * Leave out the concept maps with any of these urls: they can't be fetched, they aren't
-   * found by search, and they aren't used for translation. The FHIR core package's concept
-   * maps 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 concept maps 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, and aren't
+   * used for translation unless asked for. 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 cm of this.conceptMapMap.values()) {
-      if (cm && urls.has(cm.url)) {
-        excluded.add(cm);
+      if (cm && thoVersions.has(cm.url)) {
+        affected.add(cm);
       }
     }
     for (const [key, cm] of [...this.conceptMapMap]) {
-      if (excluded.has(cm)) {
+      if (affected.has(cm) && !keepForPinnedReference(key, cm, thoVersions.get(cm.url))) {
         this.conceptMapMap.delete(key);
       }
     }
-    for (const cm of excluded) {
+    for (const cm of affected) {
+      this.#pinnedOnly.add(cm);
       this.#excludedIds.add(stripIdPrefix(cm.id, this.spaceId) ?? cm.id);
     }
   }
 
+
   prefixIds() {
     this.#applyIdPrefix();
   }
@@ -371,7 +404,8 @@ class PackageConceptMapProvider extends AbstractConceptMapProvider {
 
   async findConceptMapForTranslation(opContext, conceptMaps, sourceSystem, sourceScope, targetScope, targetSystem) {
     for (let cm of this.conceptMapMap.values()) {
-      if (cm.providesTranslation(sourceSystem, sourceScope, targetScope, targetSystem)) {
+      // a concept map that THO also provides is only used when it's asked for by version
+      if (!this.#pinnedOnly.has(cm) && cm.providesTranslation(sourceSystem, sourceScope, targetScope, targetSystem)) {
         conceptMaps.push(cm);
       }
     }

package/tx/cs/cs-api.js

@@ -224,6 +224,17 @@ class CodeSystemProvider {
     return false;
   }
 
+  /**
+   * Why an expansion of all of the code system is not closed even though every code it defines
+   * is in it - e.g. it reserves code spaces for users to define their own codes
+   * (codesystem-reservedCodeSpace), and those codes can't be listed - or null when it is closed
+   * (as far as this is concerned: see isNotClosed() for grammars)
+   * @returns {string|null}
+   */
+  openCodeSpaceReason() {
+    return null;
+  }
+
   /**
    * returns false if the code system cannot be iterated / enumerated in any
    * meaningful sense - as distinct from isNotClosed(), which marks a code system
@@ -268,6 +279,96 @@ class CodeSystemProvider {
     }
   }
 
+  /**
+   * The language a text filter ($expand filter) searches. A text filter matches a code's
+   * displays and designations in one language only (the same rule as for the SNOMED CT display
+   * filter): the first language the request names (displayLanguage, else Accept-Language) that
+   * the code system - or a supplement in use - has displays in, else the code system's default
+   * language. Matching is at the language subtag level: de-DE searches all German.
+   *
+   * @param {Languages|null} languages - what the request asked for
+   * @returns {Language}
+   */
+  searchLanguage(languages) {
+    for (const lang of (languages && languages.languages) || []) {
+      if (!lang || !lang.language || lang.code === '*') {
+        continue;
+      }
+      const one = new Languages();
+      one.add(lang);
+      if (this.hasAnyDisplays(one) || this._hasSupplementText(lang)) {
+        return lang;
+      }
+    }
+    return new Language(this.defLang());
+  }
+
+  /**
+   * Whether a supplement in use has any display or designation (of any use) in the language
+   *
+   * @param {Language} lang
+   * @returns {boolean}
+   */
+  _hasSupplementText(lang) {
+    for (const supplement of this.supplements || []) {
+      const suppLang = supplement.jsonObj.language || this.defLang();
+      for (const concept of supplement.getAllConcepts()) {
+        if (concept.display && CodeSystemProvider.inSearchLanguage(suppLang, lang)) {
+          return true;
+        }
+        if ((concept.designation || []).some(d => d.value && CodeSystemProvider.inSearchLanguage(d.language, lang, suppLang))) {
+          return true;
+        }
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Whether text in language `code` (a tag; empty means `fallback`) is in the search language
+   *
+   * @param {string|Language|null} code
+   * @param {Language} searchLang - from searchLanguage()
+   * @param {string} [fallback] - the language of text that doesn't say
+   * @returns {boolean}
+   */
+  static inSearchLanguage(code, searchLang, fallback = 'en') {
+    let lang = code instanceof Language ? code : (code ? new Language(code) : null);
+    if (!lang || !lang.language) {
+      lang = new Language(fallback || 'en');
+    }
+    return lang.language === searchLang.language;
+  }
+
+  /**
+   * The codes whose displays or designations in a supplement in use, in the search language,
+   * pass a text filter - a supplement's designations are searched like the code system's own,
+   * so every word of the filter must match (as LOINC's and SNOMED CT's own text search need)
+   *
+   * @param {SearchFilterText} filter
+   * @param {Language} searchLang - from searchLanguage()
+   * @returns {Set<string>}
+   */
+  _supplementSearchCodes(filter, searchLang) {
+    const codes = new Set();
+    for (const supplement of this.supplements || []) {
+      const suppLang = supplement.jsonObj.language || this.defLang();
+      for (const concept of supplement.getAllConcepts()) {
+        if (concept.display && CodeSystemProvider.inSearchLanguage(suppLang, searchLang) && filter.passesAll(concept.display)) {
+          codes.add(concept.code);
+          continue;
+        }
+        for (const d of concept.designation || []) {
+          if (d.value && CodeSystemProvider.inSearchLanguage(d.language, searchLang, suppLang) && filter.passesAll(d.value)) {
+            codes.add(concept.code);
+            break;
+          }
+        }
+      }
+    }
+    return codes;
+  }
+
   _hasAnySupplementDisplays(languages) {
     // Check if any supplements have displays in the requested languages
     if (this.supplements) {
@@ -326,11 +427,12 @@ class CodeSystemProvider {
   }
 
   /**
-   * @param {boolean} langPacks - whether to include language packs
+   * @param {boolean} globals - whether to include global supplements (which $expand only reports
+   *   when they contribute something)
    * @returns {string[]} all supplements in scope
    */
-  listSupplements(langPacks) {
-    return this.supplements ? this.supplements.filter(s => langPacks || !s.isLangPack()).map(s => s.vurl) : [];
+  listSupplements(globals) {
+    return this.supplements ? this.supplements.filter(s => globals || !s.isGlobalSupplement()).map(s => s.vurl) : [];
   }
 
   /**
@@ -377,6 +479,22 @@ class CodeSystemProvider {
    * @param {String} code
    * @returns {string} the best display given the languages in the operation context
    */
+  /**
+   * @param {string} code - a code users define (one in the code system's reserved code space)
+   * @returns {string|null} the display an extension-codes supplement gives it, if one does
+   */
+  _extensionCodeDisplay(code) {
+    for (const supplement of this.supplements || []) {
+      if (supplement.isExtensionCodes()) {
+        const concept = supplement.getConceptByCode(code);
+        if (concept && concept.display) {
+          return concept.display;
+        }
+      }
+    }
+    return null;
+  }
+
   _displayFromSupplements(code) {
     assert(typeof code === 'string', 'code must be string');
     if (this.supplements) {
@@ -499,13 +617,24 @@ class CodeSystemProvider {
    */
   async designations(code, displays, significantOnly = false) { return null; }
 
-  _listSupplementDesignations(code, displays) {
+  /**
+   * @param {string} code - the code
+   * @param {ConceptDesignations} displays - the designations being built for the code
+   * @param {boolean} extensionCode - true if the code is one users define (it is in the code system's
+   *   reserved code space), so that an extension-codes supplement's display is the code's display. The
+   *   designations record where it came from (displays.extensionCodeDisplay): 'global' if a global
+   *   supplement gave it - as if the code system defined it - otherwise 'referenced'
+   */
+  _listSupplementDesignations(code, displays, extensionCode = false) {
     assert(typeof code === 'string', 'code must be string');
 
     if (this.supplements) {
       for (const supplement of this.supplements) {
         const concept= supplement.getConceptByCode(code);
         if (concept) {
+          if (extensionCode && concept.display && supplement.isExtensionCodes()) {
+            displays.extensionCodeDisplay = supplement.isGlobalSupplement() || displays.extensionCodeDisplay === 'global' ? 'global' : 'referenced';
+          }
           if (concept.display) {
             // sometimes the display is just repeated from the base code system
             if (!displays.hasAnyDisplay(concept.display)) {
@@ -531,11 +660,50 @@ class CodeSystemProvider {
   async extensions(code) { return null; }
 
   /**
-   
+   * The properties of a concept, in CodeSystem.concept.property form ({code, value[x]}).
+   * $expand reports them on expansion.contains, so a provider that has properties must
+   * override this, not just extendLookup - otherwise $lookup returns them and $expand never does
+   *
    * @param {string | CodeSystemProviderContext} code
+   * @param {string[]} [names] the properties the caller wants ('*' for all of them). A provider
+   *   that has to compute its properties should compute only these (none when the list is
+   *   empty: an expansion that asks for no properties must not pay for them); one that holds
+   *   them in memory may return the lot, and the caller picks what it asked for
    * @returns {CodeSystem.concept.property[]} list of properties (may be empty)
    */
-  async properties(code) { return []; }
+  // eslint-disable-next-line no-unused-vars
+  async properties(code, names) { return []; }
+
+  /**
+   * properties() for a provider whose properties are only built by extendLookup: run it for
+   * just the named properties, and turn the $lookup property parameters it adds into
+   * CodeSystem.concept.property form. Lookup-only parts (subproperty, description, language,
+   * code-display...) are dropped; designations are not properties
+   *
+   * @param {string | CodeSystemProviderContext} context
+   * @param {string[]} names - the properties wanted ('*' for all); none means none
+   * @returns {Promise<Object[]>}
+   */
+  async _propertiesFromLookup(context, names) {
+    if (!names || names.length === 0) {
+      return [];
+    }
+    const params = [];
+    await this.extendLookup(context, names, params);
+    const result = [];
+    for (const p of params) {
+      if (p.name !== 'property' || !Array.isArray(p.part)) {
+        continue;
+      }
+      const code = p.part.find(x => x.name === 'code')?.valueCode;
+      const value = p.part.find(x => x.name === 'value');
+      const vn = value ? Object.keys(value).find(k => k.startsWith('value')) : null;
+      if (code && vn && value[vn] !== undefined && value[vn] !== null) {
+        result.push({ code, [vn]: value[vn] });
+      }
+    }
+    return result;
+  }
 
   /**
    
@@ -559,9 +727,12 @@ class CodeSystemProvider {
   /**
    
    * @param {string } code
+   * @param {*} [prefetched] - a handle that prefetchCodes() returned for a list holding this code, or
+   *   null. A provider uses it only if it is one of its own; otherwise it looks the code up as usual
    * @returns {{context : CodeSystemProviderContext, message : String} the result of looking for the code
    */
-  async locate(code) { throw new Error("Must override"); }
+  // eslint-disable-next-line no-unused-vars
+  async locate(code, prefetched = null) { throw new Error("Must override"); }
 
   /**
    
@@ -605,6 +776,27 @@ class CodeSystemProvider {
    */
   async subsumesTest(codeA, codeB) { return 'not-subsumed'; }
 
+  /**
+   * The codes a code sits under: every ancestor in the hierarchy subsumesTest() answers from,
+   * not just the parents, and not the code itself. Optional: $closure uses it, when it is given,
+   * to relate many concepts to one another from one call per concept instead of one
+   * subsumesTest() per pair. The default returns null (not supported), and $closure then calls
+   * subsumesTest() for each pair, as it always has.
+   *
+   * A provider that implements it must agree with its own subsumesTest(): for two different
+   * codes a and b that this method answers for, subsumesTest(a, b) is 'subsumes' exactly when a
+   * is in ancestorsOf(b), 'subsumed-by' exactly when b is in ancestorsOf(a) (and a is not in
+   * ancestorsOf(b)), and never 'equivalent'. The codes are given in the form code() returns them.
+   * For any code where that can't be promised - an unknown code, a code not in the form code()
+   * gives (so another code may be the same concept), a postcoordinated expression - return null,
+   * and the pairs that involve it are tested with subsumesTest().
+   *
+   * @param {string | CodeSystemProviderContext} code
+   * @returns {Promise<Set<string>|null>} the ancestors' codes, or null when not supported for this code
+   */
+  // eslint-disable-next-line no-unused-vars
+  async ancestorsOf(code) { return null; }
+
   /**
    
    * @param {CodeSystemProviderContext} ctxt the context to add properties for
@@ -636,21 +828,67 @@ class CodeSystemProvider {
   }
 
   /**
-   * Process a set of includes and excludes for the code system
+   * Select the codes of a whole compose in one call (only called when handlesSelecting() is true).
+   *
+   * expand.js hands over a compose that selects from this code system alone (one system|version),
+   * imports no value sets, has no text filter, and lists no concepts (an enumerated concept
+   * carries displays and extensions from the value set, so those go through the usual path,
+   * where prefetchCodes() applies). Anything else this provider doesn't support - an
+   * unknown filter, say - it declines by returning null, and the compose goes through the
+   * usual include/exclude path (getPrepContext/filter/executeFilters, locate) instead. A compose
+   * with a filter on a property that a supplement in use defines is never handed over: the usual
+   * path evaluates that filter from the supplement (tx/workers/supplement-filters.js).
+   *
+   * The provider applies offset and count: the sets it returns hold just the requested page of
+   * the selection, in expansion order. The worker adds every code in them to the expansion
+   * (with displays, properties etc. from this provider, as for a filter set), and takes the
+   * total from the result.
+   *
+   * @param {TxParameters} params: information from the request that the user made, to help optimise loading (activeOnly, properties, designations...)
+   * @param {Object[]} includes - the compose's includes. Each names this system (and version), with or without filters
+   * @param {Object[]} excludes - the compose's excludes, in the same form
+   * @param {boolean} excludeInactive: whether the value set leaves out inactive codes (compose.inactive = false)
+   * @param {int} offset the index of the first code to return, -1 when the request gave no offset (start at 0)
+   * @param {int} count the most codes to return, -1 when the request gave no count (all of them); 0 asks for the total only
+   * @param {Object} [context] what the selection is for. `context.valueSet` is `{ url, version }` of the
+   *   value set whose compose this is (either may be undefined for a value set given inline without
+   *   them). A provider may ignore it.
    *
-   * @param {TxParameters} params: information from the request that the user made, to help optimise loading
-   * @param {Object[]} includes - a list of includes from the code system. Each include may contain just the system(+version), concepts and/or filters (but won't contain value sets)
-   * @param {Object[]} excludes - a list of excludes from the code system. Each include may contain just the system(+version), concepts and/or filters (but won't contain value sets)
-   * @param {boolean} excludeInactive: whether the server will use inactive codes or not
-   * @param {int} offset if handlesOffset() and !iterate, and if the value set is a simple one that only uses this provider, then this is the applicable offset. -1 if not applicable
-   * @param {int} count if handlesOffset() and !iterate, and if the value set is a simple one that only uses this provider, then this is the applicable count. -1 if not applicable
-   * @returns {FilterConceptSet[]} filter sets. In general, it wouldn't make sense to return more than one, but providers can do if they want to. See futher comments on executeFilters
-   */
-  processSelection(params, includes, excludes, excludeInactive, offset, count) {
+   * A provider that won't produce a selection because it would cost too much may throw the standard
+   * too-costly Issue, in the form expand.js uses when it refuses a value set (Issue from
+   * tx/library/operation-outcome.js; vurl is url|version, or url when there is no version):
+   *
+   *     throw new Issue('error', 'too-costly', null, 'VALUESET_TOO_COSTLY',
+   *       this.opContext.i18n.translate('VALUESET_TOO_COSTLY', params.httpLanguages, [vurl, '>' + limit]),
+   *       null, 422).withDiagnostics(this.opContext.diagnostics());
+   *
+   * @returns {Promise<{sets: FilterConceptSet[], total: number, notClosed?: boolean}|null>} null to decline.
+   *   Otherwise `sets` (in general one; iterated with filterMore/filterConcept) hold the page,
+   *   `total` is the number of codes in the whole selection before paging, or -1 when the
+   *   provider hasn't counted it (the expansion then has no total), and `notClosed` is true
+   *   when the selection is open-ended (a grammar-based code system), so the expansion is
+   *   marked unclosed
+   */
+  processSelection(params, includes, excludes, excludeInactive, offset, count, context = {}) {
     // well, you only need to override if handlesSelecting=true, but that's the only time this will be called
     throw new Error("Must override");
   }
 
+  /**
+   * Before the worker locates each code of a list one at a time: the concepts a value set include
+   * or exclude lists ($expand), or that validate-code compares a code with. A provider that
+   * answers locate() from a database may read the codes together here and return a handle to
+   * what it read: an object of its own, opaque to the worker. The worker passes the handle back
+   * as locate(code, prefetched) for each code of that list, and drops it when the loop ends. The
+   * provider keeps no state of its own for this: two lists in progress have two handles.
+   *
+   * @param {String[]} codes - the codes, in the order the worker will locate them (it may stop early)
+   * @param {boolean} withDesignations - whether the worker will also list each code's displays and designations
+   * @returns {Promise<*>} the handle, or null: this provider does no prefetching (the default)
+   */
+  // eslint-disable-next-line no-unused-vars
+  async prefetchCodes(codes, withDesignations) { return null; }
+
   /**
    * returns true if a filter is supported
    *
@@ -666,10 +904,17 @@ class CodeSystemProvider {
    * it's only use is to be passed back to the CodeSystem provider so it can make use of it to organise the filter process
    *
    * @param {boolean} iterate true if the conceptSets that result from this will be iterated, and false if they'll be used to locate a single code
+   * @param {Languages|null} languages the languages the request named (TxParameters.requestedLanguages()), or null if it named none;
+   *   for filters whose meaning depends on language, such as a regex on the display
    * @returns {FilterExecutionContext} filter
    *
    **/
-  async getPrepContext(iterate) { return new FilterExecutionContext(iterate); }
+  // eslint-disable-next-line no-unused-vars
+  async getPrepContext(iterate, languages = null) {
+    const result = new FilterExecutionContext(iterate);
+    result.languages = languages; // what the request asked for (a text filter searches one language)
+    return result;
+  }
 
 
   /**
@@ -872,6 +1117,18 @@ class CodeSystemProvider {
     return null;
   }
 
+  /**
+   * For a provider with a sqlite connection in this.db: close it, once. The handle is kept:
+   * sqlite still runs the queries already queued (and any their callbacks issue), and fails
+   * later ones with an error. Setting it to null made such a callback throw, outside any promise.
+   */
+  closeDb() {
+    if (this.db && !this.dbClosed) {
+      this.dbClosed = true;
+      this.db.close();
+    }
+  }
+
   /**
    * a record of observed usages of codes from this code system
    * - a map of code and object which has count, an integer count
@@ -1059,7 +1316,15 @@ class CodeSystemFactoryProvider {
     throw new Error("Must override");
   }
 
-  codeLink(code) {
+  /**
+   * A link for a code, usually to the code system's own web site, for pages that list codes
+   * (a ValueSet's includes). Override it to give codes from this code system a link; the
+   * default gives none, and then resolveCode() doesn't look the code up at all.
+   *
+   * @param {*} context - what locate() found for the code (the provider's own context)
+   * @returns {string|undefined} the URL, or undefined for no link
+   */
+  codeLink(context) {
     return undefined;
   }
 

package/tx/cs/cs-api.md

@@ -63,6 +63,7 @@ These methods describe the code system as a whole. All are synchronous.
 | `sourcePackage()` | `null` | The NPM package that contributed this code system, if known. |
 | `propertyDefinitions()` | `null` | The set of defined properties; override to expose them. |
 | `isNotClosed()` | `false` | Return `true` for grammar-based systems (e.g. UCUM) that cannot be fully enumerated. |
+| `openCodeSpaceReason()` | `null` | Why an expansion of all of the code system isn't closed although it lists every code the system defines - e.g. the system reserves code spaces for user-defined codes (`codesystem-reservedCodeSpace`). The expansion is marked unclosed with this as the reason. |
 | `isCaseSensitive()` | `true` | Whether code comparisons are case-sensitive. |
 | `hasParents()` | `false` | Whether the code system has a concept hierarchy. |
 | `specialEnumeration()` | `null` | Override to nominate a substitute enumeration (used by UCUM). |
@@ -109,6 +110,7 @@ All are `async`.
 | `sameConcept(a, b)` | `false` | Returns `true` if `a` and `b` refer to the same concept (e.g. different expression forms). |
 | `isDisplay(designation)` | `false` | Called for designations not already marked with a standard display use code; return `true` to treat the designation as a display. |
 | `subsumesTest(codeA, codeB)` | `'not-subsumed'` | Returns one of `equivalent`, `subsumes`, `subsumed-by`, or `not-subsumed`. |
+| `ancestorsOf(code)` | `null` | Optional. A `Set` of the codes this code sits under (all ancestors, not itself), in the form `code()` returns them. `$closure` uses it to relate concepts with one call per concept instead of one `subsumesTest()` per pair. It must agree with `subsumesTest()`: for different codes a and b it answers for, a is in `ancestorsOf(b)` exactly when `subsumesTest(a, b)` is `subsumes`, and the two are never `equivalent`. Return `null` for any code where that can't be promised (unknown, not in `code()` form, an expression); pairs involving it are tested with `subsumesTest()`. |
 | `extendLookup(ctxt, props, params)` | — | Called during `$lookup`; add any additional properties to `params`. |
 
 ---
@@ -190,9 +192,43 @@ For large code systems where a value set selects codes from only that system, th
 hand the entire include/exclude list to the provider in one call rather than using the filter
 workflow above.
 
-Override `handlesSelecting()` to return `true` and then implement `processSelection()`.
-The method receives the full lists of includes and excludes, along with pagination parameters
-if applicable, and returns `FilterConceptSet[]`.
+Override `handlesSelecting()` to return `true` and then implement
+`processSelection(params, includes, excludes, excludeInactive, offset, count, context)`.
+
+- **When it is called.** `$expand` hands over a compose that selects from this code system
+  alone (one system|version), imports no value sets, has no text filter and lists no concepts.
+  Value sets that list concepts take the usual path: `locate`, with a `prefetchCodes` handle (see Lookup).
+- **Declining.** Return `null` for anything the provider doesn't support (an unknown filter,
+  say). The compose then goes through the filter workflow above, as for any other provider.
+- **Paging.** The provider applies `offset` (-1: none given, start at 0) and `count`
+  (-1: none given, return all; 0: the total only). The sets it returns hold just that page,
+  in expansion order.
+- **Result.** `{ sets, total, notClosed }`: `sets` is a `FilterConceptSet[]` (in general one),
+  iterated with `filterMore`/`filterConcept`; `total` is the size of the whole selection
+  before paging, or -1 if the provider hasn't counted it (the expansion then has no total);
+  `notClosed` marks an open-ended selection (a grammar-based code system).
+
+- **Context.** The optional last argument, `context`, says what the selection is for:
+  `context.valueSet` is `{ url, version }` of the value set whose compose this is (either may be
+  undefined for a value set given inline without them). A provider may ignore it.
+- **Too costly.** A provider that won't produce a selection because it would cost too much may
+  throw the standard too-costly `Issue` (tx/library/operation-outcome.js), in the form `$expand`
+  uses when it refuses a value set. Here `vurl` is `url|version`, or `url` when there is no
+  version:
+
+  ```js
+  throw new Issue('error', 'too-costly', null, 'VALUESET_TOO_COSTLY',
+    this.opContext.i18n.translate('VALUESET_TOO_COSTLY', params.httpLanguages, [vurl, '>' + limit]),
+    null, 422).withDiagnostics(this.opContext.diagnostics());
+  ```
+
+  The response is a 422 with a `too-costly` issue, as for a value set `$expand` refuses itself.
+- **Over the limit.** When an include takes the whole system and the reported `total` is over the
+  request's limit, `$expand` refuses as it does on the usual path, unless the requested page
+  fits inside the limit.
+
+The default `handlesSelecting()` returns `false`, so a provider that doesn't override it is
+never asked.
 
 ---
 
@@ -202,8 +238,9 @@ Lookup supports the `$lookup` and `$validate-code` operations.
 
 | Method | Description |
 |---|---|
-| `locate(code)` | Look up a code by string. Returns `{ context, message }`. If found, `context` is a `CodeSystemProviderContext` and `message` is `null`. If not found, `context` is `null` and `message` explains why. **Must override.** |
+| `locate(code, prefetched)` | Look up a code by string. `prefetched` is a handle from `prefetchCodes` for a list holding the code, or `null`; ignore it unless it is one of yours. Returns `{ context, message }`. If found, `context` is a `CodeSystemProviderContext` and `message` is `null`. If not found, `context` is `null` and `message` explains why. **Must override.** |
 | `locateIsA(code)` | Look up a code within the scope of a parent concept. Required only if `hasParents()` returns `true`. |
+| `prefetchCodes(codes, withDesignations)` | Called before the worker locates each code of a list (the concepts a value set include or exclude lists, in `$expand` and `$validate-code`). A database-backed provider may read them together and return a handle to what it read; the worker passes it back as `locate(code, prefetched)` for each code of that list, then drops it. No state on the provider. Default: returns `null` (no prefetching). |
 | `extendLookup(ctxt, props, params)` | Called during `$lookup` to allow the provider to add extra properties to the response `Parameters`. The `props` array lists the property names requested by the client. |
 
 The server calls `locate()` first to confirm the code exists, then uses the returned context

package/tx/cs/cs-areacode.js

@@ -238,7 +238,7 @@ class AreaCodeServices extends CodeSystemProvider {
         return concept;
       }
     }
-    return `Code '${code}' not found in filter set`;
+    return null;
   }
 
   async filterCheck(filterContext, set, concept) {