fhirsmith 0.18.2 → 1.0.0

package/tx/workers/expand.js

@@ -19,12 +19,17 @@ const crypto = require('crypto');
 const ValueSet = require("../library/valueset");
 const {VersionUtilities} = require("../../library/version-utilities");
 const {debugLog} = require("../operation-context");
-
-// Expansion limits (from Pascal constants)
-const EXTERNAL_DEFAULT_LIMIT = 1000;
-const EXTERNAL_TEST_DEFAULT_LIMIT = 3000;
-const INTERNAL_DEFAULT_LIMIT = 10000;
-const EXPANSION_DEAD_TIME_SECS = 30;
+const { splitFilters, supplementFilter } = require('./supplement-filters');
+
+// Expansion limits, when the configuration doesn't set them (modules.tx.externalLimit and
+// internalLimit; see TXModule.expansionLimits): the most codes an $expand returns, and the most
+// an expansion builds (an imported value set's, for one)
+const EXTERNAL_DEFAULT_LIMIT = 10000;
+const INTERNAL_DEFAULT_LIMIT = 100000;
+// How far a paged expansion (count and offset) may walk to reach its page, as a multiple of the
+// internal limit when not configured (modules.tx.walkLimit). Only the page is built: the codes
+// before it are kept as keys, so walking costs time (bounded by the operation limit), not memory
+const WALK_LIMIT_FACTOR = 10;
 const CACHE_WHEN_DEBUGGING = false;
 
 /**
@@ -186,6 +191,13 @@ class EmptyFilterContext {
   }
 }
 
+/**
+ * The codes of a value set expanded for an import, added with their keys only (see
+ * ValueSetExpander.deferDetails): for each, how to read its details when the importing expansion
+ * returns it - {expander, cs, expansion, read}
+ */
+const DEFERRED_DETAILS = new WeakMap();
+
 class ValueSetCounter {
   constructor() {
     this.count = 0;
@@ -201,6 +213,7 @@ class ValueSetExpander {
   params;
   doingVersion = true;
   excludedSystems = new Set();
+  excludedProviders = []; // {system, cs} - see checkForExclusionVersionSpecialCase
   excluded = new Set();
   hasExclusions = false;
   requiredSupplements = new Set();
@@ -209,12 +222,40 @@ class ValueSetExpander {
   internalLimit = INTERNAL_DEFAULT_LIMIT;
   externalLimit = EXTERNAL_DEFAULT_LIMIT;
   noDetails = false;
+  // count=0: the codes counted (see #countListedCodes) but not built, by keyS
+  countedKeys = new Set();
+  composeOnlyListsCodes = false;
+  // A paged expansion (count > 0) walks to its page keeping only the keys of the codes before
+  // it, and counts those after it (see #beforePage): paging is whether this one does, walked how many codes
+  // it has passed, walkedKeys their keys (for deduplication), walkLimit how far it may walk
+  paging = false;
+  walked = 0;
+  // a code system's cap (expandLimitation) kept codes off the page asked for: {system, limit}, for
+  // the expansion-issue that explains it (see #noteCapCut)
+  capCut = null;
+  walkedKeys = new Set();
+  // and after the page, how many more codes it has counted for the total (see #finishIfPageFilled)
+  counted = 0;
+  // a paged expansion of one selection whose size the provider vouches for, as count=0 trusts it
+  // (one include of a whole code system, or of one filter set, and nothing else): that size, which
+  // is the total, so the walk stops once the page is full (see #finishIfPageFilled). null: the walk counts
+  providerSize = null;
+  walkLimit = INTERNAL_DEFAULT_LIMIT * WALK_LIMIT_FACTOR;
+  // a provider applied offset and count to the compose itself (processSelection): every code it
+  // returns is on the page
+  providerPaged = false;
+  // An imported value set (include.valueSet, exclude.valueSet) whose expansion the importing
+  // expansion uses for its codes, and from which it returns only some codes, or none (its page):
+  // each code is added with its key, and what its details are read from is kept with it, for the
+  // importing expansion to build the ones it returns (#buildDeferred). Same codes, same order
+  deferDetails = false;
 
   constructor(worker, params) {
     this.worker = worker;
     this.params = params;
     this.internalLimit = worker.internalLimit;
     this.externalLimit = worker.externalLimit;
+    this.walkLimit = worker.walkLimit || (this.internalLimit || INTERNAL_DEFAULT_LIMIT) * WALK_LIMIT_FACTOR;
 
     this.csCounter = new Map();
   }
@@ -271,11 +312,21 @@ class ValueSetExpander {
       return true;
     }
     for (const s of this.params.designations) {
-      const [l, r] = s.split('|');
-      if (cd.use != null && cd.use.system === l && cd.use.code === r) {
+      // a token: system|code, or a bare code (or |code), which matches a language or a use
+      // code from any system. designation=nl-NL is the same as urn:ietf:bcp:47|nl-NL
+      const bar = s.indexOf('|');
+      const system = bar < 0 ? '' : s.substring(0, bar);
+      const code = bar < 0 ? s : s.substring(bar + 1);
+      if (!system) {
+        if ((cd.language != null && cd.language.code === code) || (cd.use != null && cd.use.code === code)) {
+          return true;
+        }
+        continue;
+      }
+      if (cd.use != null && cd.use.system === system && cd.use.code === code) {
         return true;
       }
-      if (cd.language != null && l === 'urn:ietf:bcp:47' && r === cd.language.code) {
+      if (cd.language != null && system === 'urn:ietf:bcp:47' && code === cd.language.code) {
         return true;
       }
     }
@@ -300,7 +351,33 @@ class ValueSetExpander {
     }
   }
 
-  includeCode(cs, parent, system, version, code, isAbstract, isInactive, deprecated, status, displays, definition, itemWeight, expansion, imports, csExtList, vsExtList, csProps, expProps, excludeInactive, srcURL) {
+  /**
+   * The response limit (limitCount: the request's, or for an imported value set, the internal
+   * limit), checked before a code is added to the expansion, by every path that adds one
+   * (includeCode, importValueSetItem). At the limit: when the page asked for (count and offset)
+   * is full, the expansion is done, without a total; otherwise the expansion is too costly
+   * (VALUESET_TOO_COSTLY). Exclusions are no exception: they are all processed before any
+   * include, so the codes already in the list stay in it. Only counting (count=0), nothing is
+   * returned, so the limit is how far a walk may go (walkLimit)
+   * @param {string} srcURL - the value set, for the message
+   */
+  #checkLimit(srcURL) {
+    const limit = this.count === 0 ? this.walkLimit : this.limitCount;
+    if (limit > 0 && this.fullList.length >= limit) {
+      if (this.count > -1 && this.offset > -1 && this.count + this.offset > 0 && this.walked + this.fullList.length >= this.count + this.offset) {
+        this.noTotal();
+        throw new Issue('information', 'informational', null, null, null, null).setFinished();
+      } else {
+        throw new Issue("error", "too-costly", null, 'VALUESET_TOO_COSTLY', this.tooCostlyMessage(srcURL, '>' + limit), null, 422).withDiagnostics(this.worker.opContext.diagnostics());
+      }
+    }
+  }
+
+  /**
+   * @param {function(): Promise<Object>} [deferredRead] - the code's details are not added now, but
+   *   read with this when an importing expansion returns the code (see deferDetails, #readDetails)
+   */
+  async includeCode(cs, parent, system, version, code, isAbstract, isInactive, deprecated, status, displays, definition, itemWeight, expansion, imports, csExtList, vsExtList, csProps, expProps, excludeInactive, srcURL, deferredRead = null) {
     let result = null;
     this.worker.deadCheck('processCode');
 
@@ -310,39 +387,15 @@ class ValueSetExpander {
     if (isInactive && excludeInactive) {
       return null;
     }
-    if (this.isExcluded(system, version, code)) {
+    if (await this.isExcluded(system, version, code)) {
       return null;
     }
 
-    // expandLimitation() caps how many codes a single code system may contribute
-    // (e.g. CPT limits enumeration to 1000 codes by agreement with the AMA).
-    // NB: expandLimitation and system are methods - reading them as properties
-    // (cs.expandLimitation > 0) compares the function object and is always false,
-    // which silently disabled this cap.
-    const expandLimit = cs != null ? cs.expandLimitation() : 0;
-    if (expandLimit > 0) {
-      let cnt = this.csCounter.get(cs.system());
-      if (cnt == null) {
-        cnt = new ValueSetCounter();
-        this.csCounter.set(cs.system(), cnt);
-      }
-      cnt.increment();
-      if (cnt.count > expandLimit) {
-        return null;
-      }
+    if (this.#overSystemCap(cs)) {
+      return null;
     }
 
-    if (this.limitCount > 0 && this.fullList.length >= this.limitCount && !this.hasExclusions) {
-      if (this.count > -1 && this.offset > -1 && this.count + this.offset > 0 && this.fullList.length >= this.count + this.offset) {
-        this.noTotal();
-        throw new Issue('information', 'informational', null, null, null, null).setFinished();
-      } else {
-        if (!srcURL) {
-          srcURL = '??';
-        }
-        throw new Issue("error", "too-costly", null, 'VALUESET_TOO_COSTLY', this.worker.i18n.translate('VALUESET_TOO_COSTLY', this.params.httpLanguages, [srcURL, '>' + this.limitCount]), null, 422).withDiagnostics(this.worker.opContext.diagnostics());
-      }
-    }
+    this.#checkLimit(srcURL);
 
     if (expansion && !this.noDetails) {
       const s = this.canonical(system, version);
@@ -357,7 +410,10 @@ class ValueSetExpander {
 
     const s = this.keyS(system, version, code);
 
-    if (!this.map.has(s)) {
+    if (!this.map.has(s) && !this.walkedKeys.has(s)) {
+      // a code outside the page, on an expansion that doesn't walk to it: only counted and kept
+      // for deduplication, never returned (see #outsidePage)
+      const outsidePage = this.#outsidePage();
       const n = {};
       n.system = system;
       n.code = code;
@@ -370,162 +426,351 @@ class ValueSetExpander {
       if (isInactive) {
         n.inactive = true;
       }
-      if (!this.noDetails) {
-        if (status && status.toLowerCase() !== 'active') {
-          this.defineProperty(expansion, n, 'http://hl7.org/fhir/concept-properties#status', 'status', "valueCode", status);
-        } else if (deprecated) {
-          this.defineProperty(expansion, n, 'http://hl7.org/fhir/concept-properties#status', 'status', "valueCode", 'deprecated');
+      if (deferredRead) {
+        DEFERRED_DETAILS.set(n, { expander: this, cs, expansion, read: deferredRead });
+      } else if (!this.noDetails && !outsidePage) {
+        this.#addDetails(n, cs, code, status, deprecated, displays, definition, expansion, csExtList, vsExtList, csProps);
+      }
+      this.fullList.push(n);
+      this.map.set(s, n);
+      if (parent != null && !this.noDetails) {
+        if (!parent.contains) {
+          parent.contains = [];
         }
+        parent.contains.push(n);
+      } else {
+        this.rootList.push(n);
+      }
+      result = n;
+    } else {
+      this.canBeHierarchy = false;
+    }
+    return result;
+  }
 
-        if (Extensions.has(csExtList, 'http://hl7.org/fhir/StructureDefinition/codesystem-label')) {
-          this.defineProperty(expansion, n, 'http://hl7.org/fhir/concept-properties#label', 'label', "valueString", Extensions.readString(csExtList, 'http://hl7.org/fhir/StructureDefinition/codesystem-label'));
-        }
-        if (Extensions.has(vsExtList, 'http://hl7.org/fhir/StructureDefinition/valueset-label')) {
-          this.defineProperty(expansion, n, 'http://hl7.org/fhir/concept-properties#label', 'label', "valueString", Extensions.readString(vsExtList, 'http://hl7.org/fhir/StructureDefinition/valueset-label'));
-        }
+  /**
+   * The details of a code in the expansion: status and other properties, label, order and weight,
+   * the extensions carried over, the display and designations (see includeCode)
+   */
+  #addDetails(n, cs, code, status, deprecated, displays, definition, expansion, csExtList, vsExtList, csProps) {
+    if (status && status.toLowerCase() !== 'active') {
+      this.defineProperty(expansion, n, 'http://hl7.org/fhir/concept-properties#status', 'status', "valueCode", status);
+    } else if (deprecated) {
+      this.defineProperty(expansion, n, 'http://hl7.org/fhir/concept-properties#status', 'status', "valueCode", 'deprecated');
+    }
 
-        if (Extensions.has(csExtList, 'http://hl7.org/fhir/StructureDefinition/codesystem-conceptOrder')) {
-          this.defineProperty(expansion, n, 'http://hl7.org/fhir/concept-properties#order', 'order', "valueDecimal", Extensions.readNumber(csExtList, 'http://hl7.org/fhir/StructureDefinition/codesystem-conceptOrder', undefined));
-        }
-        if (Extensions.has(vsExtList, 'http://hl7.org/fhir/StructureDefinition/valueset-conceptOrder')) {
-          this.defineProperty(expansion, n, 'http://hl7.org/fhir/concept-properties#order', 'order', "valueDecimal", Extensions.readNumber(vsExtList, 'http://hl7.org/fhir/StructureDefinition/valueset-conceptOrder', undefined));
-        }
+    if (Extensions.has(csExtList, 'http://hl7.org/fhir/StructureDefinition/codesystem-label')) {
+      this.defineProperty(expansion, n, 'http://hl7.org/fhir/concept-properties#label', 'label', "valueString", Extensions.readString(csExtList, 'http://hl7.org/fhir/StructureDefinition/codesystem-label'));
+    }
+    if (Extensions.has(vsExtList, 'http://hl7.org/fhir/StructureDefinition/valueset-label')) {
+      this.defineProperty(expansion, n, 'http://hl7.org/fhir/concept-properties#label', 'label', "valueString", Extensions.readString(vsExtList, 'http://hl7.org/fhir/StructureDefinition/valueset-label'));
+    }
 
-        if (Extensions.has(csExtList, 'http://hl7.org/fhir/StructureDefinition/itemWeight')) {
-          this.defineProperty(expansion, n, 'http://hl7.org/fhir/concept-properties#itemWeight', 'weight', "valueDecimal", Extensions.readNumber(csExtList, 'http://hl7.org/fhir/StructureDefinition/itemWeight', undefined));
-        }
-        if (Extensions.has(vsExtList, 'http://hl7.org/fhir/StructureDefinition/itemWeight')) {
-          this.defineProperty(expansion, n, 'http://hl7.org/fhir/concept-properties#itemWeight', 'weight', "valueDecimal", Extensions.readNumber(vsExtList, 'http://hl7.org/fhir/StructureDefinition/itemWeight', undefined));
-        }
+    if (Extensions.has(csExtList, 'http://hl7.org/fhir/StructureDefinition/codesystem-conceptOrder')) {
+      this.defineProperty(expansion, n, 'http://hl7.org/fhir/concept-properties#order', 'order', "valueDecimal", Extensions.readNumber(csExtList, 'http://hl7.org/fhir/StructureDefinition/codesystem-conceptOrder', undefined));
+    }
+    if (Extensions.has(vsExtList, 'http://hl7.org/fhir/StructureDefinition/valueset-conceptOrder')) {
+      this.defineProperty(expansion, n, 'http://hl7.org/fhir/concept-properties#order', 'order', "valueDecimal", Extensions.readNumber(vsExtList, 'http://hl7.org/fhir/StructureDefinition/valueset-conceptOrder', undefined));
+    }
 
-        if (csExtList != null) {
-          for (const ext of csExtList) {
-            if (['http://hl7.org/fhir/StructureDefinition/coding-sctdescid', 'http://hl7.org/fhir/StructureDefinition/rendering-style',
-              'http://hl7.org/fhir/StructureDefinition/rendering-xhtml', 'http://hl7.org/fhir/StructureDefinition/codesystem-alternate'].includes(ext.url)) {
-              if (!n.extension) {
-                n.extension = []
-              }
-              n.extension.push(ext);
-            }
-            if (['http://hl7.org/fhir/StructureDefinition/structuredefinition-standards-status'].includes(ext.url)) {
-              this.defineProperty(expansion, n, 'http://hl7.org/fhir/concept-properties#status', 'status', "valueCode", getValuePrimitive(ext));
-            }
+    if (Extensions.has(csExtList, 'http://hl7.org/fhir/StructureDefinition/itemWeight')) {
+      this.defineProperty(expansion, n, 'http://hl7.org/fhir/concept-properties#itemWeight', 'weight', "valueDecimal", Extensions.readNumber(csExtList, 'http://hl7.org/fhir/StructureDefinition/itemWeight', undefined));
+    }
+    if (Extensions.has(vsExtList, 'http://hl7.org/fhir/StructureDefinition/itemWeight')) {
+      this.defineProperty(expansion, n, 'http://hl7.org/fhir/concept-properties#itemWeight', 'weight', "valueDecimal", Extensions.readNumber(vsExtList, 'http://hl7.org/fhir/StructureDefinition/itemWeight', undefined));
+    }
+
+    if (csExtList != null) {
+      for (const ext of csExtList) {
+        if (['http://hl7.org/fhir/StructureDefinition/coding-sctdescid', 'http://hl7.org/fhir/StructureDefinition/rendering-style',
+          'http://hl7.org/fhir/StructureDefinition/rendering-xhtml', 'http://hl7.org/fhir/StructureDefinition/codesystem-alternate'].includes(ext.url)) {
+          if (!n.extension) {
+            n.extension = []
           }
+          n.extension.push(ext);
         }
+        if (['http://hl7.org/fhir/StructureDefinition/structuredefinition-standards-status'].includes(ext.url)) {
+          this.defineProperty(expansion, n, 'http://hl7.org/fhir/concept-properties#status', 'status', "valueCode", getValuePrimitive(ext));
+        }
+      }
+    }
 
-        if (vsExtList != null) {
-          for (const ext of vsExtList || []) {
-            if (['http://hl7.org/fhir/StructureDefinition/valueset-supplement', 'http://hl7.org/fhir/StructureDefinition/valueset-deprecated',
-              'http://hl7.org/fhir/StructureDefinition/structuredefinition-standards-status',
-              'http://hl7.org/fhir/StructureDefinition/valueset-concept-definition', 'http://hl7.org/fhir/StructureDefinition/coding-sctdescid',
-              'http://hl7.org/fhir/StructureDefinition/rendering-style', 'http://hl7.org/fhir/StructureDefinition/rendering-xhtml'].includes(ext.url)) {
-              if (!n.extension) {
-                n.extension = []
-              }
-              n.extension.push(ext);
-            }
+    if (vsExtList != null) {
+      for (const ext of vsExtList || []) {
+        if (['http://hl7.org/fhir/StructureDefinition/valueset-supplement', 'http://hl7.org/fhir/StructureDefinition/valueset-deprecated',
+          'http://hl7.org/fhir/StructureDefinition/structuredefinition-standards-status',
+          'http://hl7.org/fhir/StructureDefinition/valueset-concept-definition', 'http://hl7.org/fhir/StructureDefinition/coding-sctdescid',
+          'http://hl7.org/fhir/StructureDefinition/rendering-style', 'http://hl7.org/fhir/StructureDefinition/rendering-xhtml'].includes(ext.url)) {
+          if (!n.extension) {
+            n.extension = []
           }
+          n.extension.push(ext);
         }
+      }
+    }
 
-        // display and designations
-        const pref = displays.preferredDesignation(this.params.workingLanguages(), this.reportedSupplements);
-        if (pref && pref.value) {
-          n.display = pref.value;
-        }
+    // display and designations
+    const pref = displays.preferredDesignation(this.params.workingLanguages(), this.reportedSupplements);
+    if (pref && pref.value) {
+      n.display = pref.value;
+    }
 
-        if (this.params.includeDesignations) {
-          for (const t of displays.designations) {
-            if (t !== pref && this.useDesignation(t) && t.value != null && !this.redundantDisplay(n, t.language, t.use, t.value)) {
-              if (!n.designation) {
-                n.designation = [];
-              }
-              if (t.supplement && t.supplement.vurl) {
-                this.reportedSupplements.add(t.supplement.vurl);
-              }
-              n.designation.push(t.asObject());
-            }
+    if (this.params.includeDesignations) {
+      for (const t of displays.designations) {
+        if (t !== pref && this.useDesignation(t) && t.value != null && !this.redundantDisplay(n, t.language, t.use, t.value)) {
+          if (!n.designation) {
+            n.designation = [];
+          }
+          if (t.supplement && t.supplement.vurl) {
+            this.reportedSupplements.add(t.supplement.vurl);
           }
+          n.designation.push(t.asObject());
         }
+      }
+    }
+
+    // '*' asks for every property the code system defines for the concept (R6's
+    // ValueSet.compose.property allows it, and a request can name it too). It is handled
+    // here rather than by expanding it into a list of names, because which properties
+    // exist is a property of the concept, not of the request
+    if (this.params.properties.includes('*') && csProps != null && cs != null) {
+      for (const cp of csProps) {
+        const vn = getValueName(cp);
+        this.defineProperty(expansion, n, this.getPropUrl(cs, cp.code, cp), cp.code, vn, cp[vn], true);
+      }
+    }
 
-        // '*' asks for every property the code system defines for the concept (R6's
-        // ValueSet.compose.property allows it, and a request can name it too). It is handled
-        // here rather than by expanding it into a list of names, because which properties
-        // exist is a property of the concept, not of the request
-        if (this.params.properties.includes('*') && csProps != null && cs != null) {
-          for (const cp of csProps) {
+    // properties the code system always reports (ICD-11's classificationCode), unless
+    // the request asked for them anyway and the loops here add them
+    if (csProps != null && cs != null && !this.params.properties.includes('*')) {
+      for (const pn of cs.mandatoryExpansionProperties()) {
+        if (!this.params.properties.includes(pn)) {
+          for (const cp of csProps.filter(p => p.code === pn)) {
             const vn = getValueName(cp);
-            this.defineProperty(expansion, n, this.getPropUrl(cs, cp.code, cp), cp.code, vn, cp[vn], true);
+            this.defineProperty(expansion, n, this.getPropUrl(cs, pn, cp), pn, vn, cp[vn], true);
           }
         }
+      }
+    }
 
-        // properties the code system always reports (ICD-11's classificationCode), unless
-        // the request asked for them anyway and the loops here add them
-        if (csProps != null && cs != null && !this.params.properties.includes('*')) {
-          for (const pn of cs.mandatoryExpansionProperties()) {
-            if (!this.params.properties.includes(pn)) {
-              for (const cp of csProps.filter(p => p.code === pn)) {
-                const vn = getValueName(cp);
-                this.defineProperty(expansion, n, this.getPropUrl(cs, pn, cp), pn, vn, cp[vn], true);
-              }
-            }
-          }
+    for (const pn of this.params.properties) {
+      if (pn === '*') {
+        continue; // done above
+      } else if (pn === 'definition') {
+        if (definition) {
+          this.defineProperty(expansion, n, 'http://hl7.org/fhir/concept-properties#definition', pn, "valueString", definition);
         }
-
-        for (const pn of this.params.properties) {
-          if (pn === '*') {
-            continue; // done above
-          } else if (pn === 'definition') {
-            if (definition) {
-              this.defineProperty(expansion, n, 'http://hl7.org/fhir/concept-properties#definition', pn, "valueString", definition);
-            }
-          } else if (pn === 'usage-count') {
-            let counter = cs.usages().get(code);
-            this.defineProperty(expansion, n, 'http://fhir.org/FHIRsmith/CodeSystem/concept-properties#usage-count', pn, "valueInteger", counter ? counter.count : 0);
-          } else if (csProps != null && cs != null) {
-            for (const cp of csProps) {
-              if (cp.code === pn) {
-                let vn = getValueName(cp);
-                let v = cp[vn];
-                // a concept may carry the same property more than once (the
-                // "dup" property in the test code system has two values)
-                this.defineProperty(expansion, n, this.getPropUrl(cs, pn, cp), pn, vn, v, true);
-              }
-            }
+      } else if (pn === 'usage-count') {
+        let counter = cs.usages().get(code);
+        this.defineProperty(expansion, n, 'http://fhir.org/FHIRsmith/CodeSystem/concept-properties#usage-count', pn, "valueInteger", counter ? counter.count : 0);
+      } else if (csProps != null && cs != null) {
+        for (const cp of csProps) {
+          if (cp.code === pn) {
+            let vn = getValueName(cp);
+            let v = cp[vn];
+            // a concept may carry the same property more than once (the
+            // "dup" property in the test code system has two values)
+            this.defineProperty(expansion, n, this.getPropUrl(cs, pn, cp), pn, vn, v, true);
           }
         }
       }
-      this.fullList.push(n);
-      this.map.set(s, n);
-      if (parent != null && !this.noDetails) {
-        if (!parent.contains) {
-          parent.contains = [];
-        }
-        parent.contains.push(n);
-      } else {
-        this.rootList.push(n);
+    }
+  }
+
+  /**
+   * expandLimitation() caps how many codes a single code system may contribute (e.g. CPT limits
+   * enumeration to 1000 codes by agreement with the AMA): count this code against its system's
+   * cap, and say whether it is over. (NB: expandLimitation and system are methods - read as
+   * properties, cs.expandLimitation > 0 compares the function object and is always false, which
+   * silently disabled this cap.)
+   */
+  #overSystemCap(cs) {
+    const expandLimit = cs != null ? cs.expandLimitation() : 0;
+    if (expandLimit > 0) {
+      let cnt = this.csCounter.get(cs.system());
+      if (cnt == null) {
+        cnt = new ValueSetCounter();
+        this.csCounter.set(cs.system(), cnt);
+      }
+      cnt.increment();
+      if (cnt.count > expandLimit) {
+        this.#noteCapCut(cs);
+        return true;
       }
-      result = n;
-    } else {
-      this.canBeHierarchy = false;
     }
-    return result;
+    return false;
   }
 
-  excludeCode(cs, system, version, code, expansion, imports, srcURL) {
-    this.worker.deadCheck('excludeCode');
-    if (!this.passesImports(imports, system, code, 0)) {
-      return;
+  /**
+   * Whether the code system has already contributed all the codes its cap (expandLimitation)
+   * allows: then nothing more of it can be in the expansion, so there's no need to walk it further
+   */
+  #capReached(cs) {
+    const expandLimit = cs != null ? cs.expandLimitation() : 0;
+    if (!(expandLimit > 0)) {
+      return false;
     }
+    const cnt = this.csCounter.get(cs.system());
+    return cnt != null && cnt.count >= expandLimit;
+  }
 
-    if (this.limitCount > 0 && this.fullList.length >= this.limitCount && !this.hasExclusions) {
-      if (this.count > -1 && this.offset > -1 && this.count + this.offset > 0 && this.fullList.length >= this.count + this.offset) {
-        throw new Issue('information', 'informational', null, null, null, null).setFinished();
+  /**
+   * A code system's cap kept a code out: if the page asked for wasn't yet full (or there is no
+   * page - all the codes were asked for), the response is missing codes it would otherwise have,
+   * and gets an expansion-issue saying why. A code kept out after the page is full only changes
+   * the total, which is reported anyway (see the whole-system include in includeCodes)
+   */
+  #noteCapCut(cs) {
+    if (this.capCut == null && !this.pageFilled()) {
+      this.capCut = { system: cs.system(), limit: cs.expandLimitation() };
+    }
+  }
+
+  /**
+   * Tell the user something about how the expansion was made that they should know (e.g. that
+   * codes are missing, and why): an expansion-issue extension on the expansion, referring to a
+   * contained OperationOutcome with the issue
+   * @param {Object} vs the ValueSet being returned
+   * @param {Object} exp its expansion
+   * @param {Issue} issue the issue
+   */
+  addExpansionIssue(vs, exp, issue) {
+    if (!vs.contained) {
+      vs.contained = [];
+    }
+    let n = 1;
+    while (vs.contained.some(r => r.id === 'oo' + n)) {
+      n++;
+    }
+    const id = 'oo' + n;
+    vs.contained.push({ resourceType: 'OperationOutcome', id, issue: [issue.asIssue()] });
+    if (!exp.extension) {
+      exp.extension = [];
+    }
+    exp.extension.push({ url: 'http://hl7.org/fhir/StructureDefinition/expansion-issue', valueReference: { reference: '#' + id } });
+  }
+
+  /**
+   * Before the page of a paged expansion (count and offset, see handleCompose), a code that would
+   * be included is only counted: its key is kept, for deduplication, and nothing is read or built.
+   * The tests are includeCode's, in the same order, so a code counts here exactly when it would be
+   * included there. Call it first, before reading the concept's details.
+   * @returns {Promise<boolean|null>} null: not before the page (or not paging) - include the code
+   *   as usual; true: counted, go on to the next; false: it would not be included, go on to the next
+   */
+  async #beforePage(cs, system, version, code, isInactive, excludeInactive, imports) {
+    if (!this.paging || (this.walked >= this.offset && !this.pageFilled())) {
+      return null;
+    }
+    if (!this.passesImports(imports, system, code, 0) || (isInactive && excludeInactive)
+        || await this.isExcluded(system, version, code) || this.#overSystemCap(cs)) {
+      return false;
+    }
+    return this.#walk(this.keyS(system, version, code));
+  }
+
+  /**
+   * Count a code before the page, or after it (for the total): false if it was already counted
+   * or included
+   */
+  #walk(key) {
+    if (this.walkedKeys.has(key) || this.map.has(key)) {
+      this.canBeHierarchy = false;
+      return false;
+    }
+    this.walkedKeys.add(key);
+    if (this.pageFilled()) {
+      this.counted++;
+      this.#finishIfPageFilled();
+      return true;
+    }
+    this.walked++;
+    if (this.walked + this.count > this.walkLimit) {
+      const label = this.vsLabel();
+      throw new Issue('error', 'too-costly', null, 'VALUESET_TOO_COSTLY_PAGE', label
+        ? this.worker.i18n.translate('VALUESET_TOO_COSTLY_PAGE', this.params.httpLanguages, [label, this.offset, this.count, this.walkLimit])
+        : this.worker.i18n.translate('VALUESET_TOO_COSTLY_PAGE_REQUEST', this.params.httpLanguages, [this.offset, this.count, this.walkLimit]),
+      null, 422).withDiagnostics(this.worker.opContext.diagnostics());
+    }
+    return true;
+  }
+
+  /**
+   * Paging: once the page is full, the rest of the walk only counts codes, for the total - and the
+   * total is only reported for an expansion within the response limit, as on an unpaged one (where
+   * includeCode stops at the limit). So once the codes seen reach the limit, stop: no total. And when
+   * the provider has said how big the selection is (providerSize), there is nothing to count: stop
+   * as soon as the page is full
+   */
+  #finishIfPageFilled() {
+    if (this.paging && this.pageFilled() && this.providerSize != null) {
+      // the provider has said how many codes the walk would count: report that, as the walk would
+      // have (only within the limit), and stop
+      if (this.providerSize < this.limitCount) {
+        this.total = this.providerSize;
+        this.totalStatus = 'set';
       } else {
-        if (!srcURL) {
-          srcURL = '??';
-        }
-        throw new Issue("error", "too-costly", null, 'VALUESET_TOO_COSTLY', this.worker.i18n.translate('VALUESET_TOO_COSTLY', this.params.httpLanguages, [srcURL, '>' + this.limitCount]), null, 422).withDiagnostics(this.worker.opContext.diagnostics());
+        this.noTotal();
       }
+      throw new Issue('information', 'informational', null, null, null, null).setFinished();
+    }
+    if (this.paging && this.pageFilled() && this.walked + this.fullList.length + this.counted >= this.limitCount) {
+      this.noTotal();
+      throw new Issue('information', 'informational', null, null, null, null).setFinished();
+    }
+  }
+
+  /**
+   * Paging: whether the next n codes, if all are included, fall inside the page - so each will be
+   * built, and none only counted. (Fewer may be included: filters, excludes and repeats only make
+   * the list shorter, so it still fits)
+   * @param {number} n
+   * @returns {boolean}
+   */
+  #pageHolds(n) {
+    const start = this.walked + this.fullList.length;
+    return start >= this.offset && start + n <= this.offset + this.count;
+  }
+
+  /**
+   * Whether the size of the one selection an include makes (a whole code system, or one filter set)
+   * is the total of the expansion, as count=0 trusts it: the include is the whole value set (no
+   * other include, no exclude), and no code in the selection is left out (inactive ones, or over
+   * the code system's cap on how many codes it contributes)
+   */
+  #sizeIsTotal(compose, cs, excludeInactive) {
+    return !excludeInactive && !this.params.activeOnly && !this.hasExclusions
+      && (compose.include || []).length === 1 && (compose.exclude || []).length === 0
+      && !(cs.expandLimitation() > 0);
+  }
+
+  /**
+   * A paged expansion: the provider's size of the selection it walks is its total (see
+   * #finishIfPageFilled), when the provider gives one
+   */
+  #useProviderSize(size) {
+    if (typeof size === 'number' && size >= 0) {
+      this.worker.opContext.log('paged: the provider gives the total');
+      this.providerSize = size;
+    }
+  }
+
+  /**
+   * Whether the page asked for (count and offset) is one the limits allow, as far as can be told
+   * before the walk: a paged walk checks the walk limit as it goes (#walk), so a value set that
+   * ends before the page is an empty page, not a refusal
+   */
+  #pageFits() {
+    if (!(this.count > 0) || this.count > this.limitCount) {
+      return false;
+    }
+    return this.paging || this.count + Math.max(this.offset, 0) <= this.limitCount;
+  }
+
+  excludeCode(cs, system, version, code, expansion, imports) {
+    this.worker.deadCheck('excludeCode');
+    if (!this.passesImports(imports, system, code, 0)) {
+      return;
     }
 
     if (expansion) {
@@ -560,7 +805,12 @@ class ValueSetExpander {
     }
   }
 
-  async expandValueSet(uri, version, vs, filter, notClosed) {
+  /**
+   * @param {boolean} [deferDetails] - its codes' details are left to be read when this expansion
+   *   returns them (see deferDetails): for an import used only for which codes it has, or one this
+   *   expansion returns only some codes of (#importDefers)
+   */
+  async expandValueSet(uri, version, vs, filter, notClosed, deferDetails = false) {
 
     if (!vs) {
       if (version) {
@@ -579,6 +829,7 @@ class ValueSetExpander {
     let expander = new ValueSetExpander(worker, paramsInner);
     expander.internalLimit = this.internalLimit;
     expander.externalLimit = this.internalLimit; // it's deliberate that this is the internal limit
+    expander.deferDetails = deferDetails;
     let result = await expander.expand(vs, filter, false);
     if (result == null) {
       throw new Issue('error', 'not-found', null, 'VS_EXP_IMPORT_UNK', this.worker.i18n.translate('VS_EXP_IMPORT_UNK', this.params.httpLanguages, [uri]), 'unknown');
@@ -600,19 +851,35 @@ class ValueSetExpander {
     this.checkResourceCanonicalStatus(expansion, vs, this.valueSet);
 
     const imported = [];
+    // the expansions whose property declarations the codes returned use: the import's, and, for
+    // codes whose details were read only now (see #buildDeferred), the ones that added them
+    const sources = new Set([vs.expansion]);
     for (const c of vs.expansion.contains || []) {
       await this.worker.checkAndYield('importValueSet');
-      count += await this.importValueSetItem(null, c, imports, offset, imported);
+      count += await this.importValueSetItem(null, c, imports, offset, imported, sources);
+    }
+    for (const source of sources) {
+      this.importPropertyDefinitions(expansion, source.property, imported);
     }
-    this.importPropertyDefinitions(expansion, vs.expansion.property, imported);
     return count;
   }
 
-  async importValueSetItem(p, c, imports, offset, imported) {
+  async importValueSetItem(p, c, imports, offset, imported, sources) {
     let count = 0;
     await this.worker.checkAndYield('importValueSetItem');
     const s = this.keyC(c);
-    if (this.passesImports(imports, c.system, c.code, offset) && !this.map.has(s) && !this.isExcluded(c.system, c.version, c.code)) {
+    if (this.paging && (this.walked < this.offset || this.pageFilled()) && this.passesImports(imports, c.system, c.code, offset)
+        && !(await this.isExcluded(c.system, c.version, c.code))) {
+      if (this.#walk(s)) {
+        count++;
+      }
+    } else if (this.passesImports(imports, c.system, c.code, offset) && !this.map.has(s) && !this.walkedKeys.has(s) && !(await this.isExcluded(c.system, c.version, c.code))) {
+      // an imported code counts against this expansion's limit like any other
+      this.#checkLimit(this.valueSet ? this.valueSet.vurl : null);
+      if (!this.deferDetails && !this.noDetails && !this.#outsidePage()) {
+        // returned: its details, if they were left to be read
+        await this.#buildDeferred(c, sources);
+      }
       count++;
       if (imported) {
         imported.push(c);
@@ -628,7 +895,7 @@ class ValueSetExpander {
     }
     for (const cc of c.contains || []) {
       await this.worker.checkAndYield('importValueSetItem');
-      count += await this.importValueSetItem(c, cc, imports, offset, imported);
+      count += await this.importValueSetItem(c, cc, imports, offset, imported, sources);
     }
     return count;
   }
@@ -652,9 +919,9 @@ class ValueSetExpander {
     walk(vs.expansion.contains);
   }
 
-  async checkSource(cset, exp, filter, srcURL, ts, vsInfo , source) {
+  async checkSource(cset, exp, filter, srcURL, ts, vsInfo , source, path = 'ValueSet.compose.include') {
     await this.worker.checkAndYield('checkSource');
-    Extensions.checkNoModifiers(cset, 'ValueSetExpander.checkSource', 'set', srcURL);
+    Extensions.checkNoModifiers(cset, 'ValueSetExpander.checkSource', path, source && source.vurl ? source.vurl : srcURL);
     let imp = false;
     for (const u of cset.valueSet || []) {
       await this.worker.checkAndYield('checkSource');
@@ -682,13 +949,14 @@ class ValueSetExpander {
         if (vsInfo && vsInfo.isSimple) {
           vsInfo.handleByCS = cs.handlesSelecting();
         }
+        // A code system with no content to expand from is refused like an unknown one: 422
         if (!cs.contentMode()) {
-          throw new Issue('error', 'business-rule', null, null, 'The code system definition for ' + cset.system + ' has no content property, so this expansion cannot be performed', 'invalid');
+          throw new Issue('error', 'business-rule', null, null, 'The code system definition for ' + cset.system + ' has no content property, so this expansion cannot be performed', 'invalid', 422);
         } else if (cs.contentMode() !== 'complete') {
           if (cs.contentMode() === 'not-present') {
-            throw new Issue('error', 'business-rule', null, null, 'The code system definition for ' + cset.system + ' has no content, so this expansion cannot be performed', 'invalid');
+            throw new Issue('error', 'business-rule', null, null, 'The code system definition for ' + cset.system + ' has no content, so this expansion cannot be performed', 'invalid', 422);
           } else if (cs.contentMode() === 'supplement') {
-            throw new Issue('error', 'business-rule', null, null, 'The code system definition for ' + cset.system + ' defines a supplement, so this expansion cannot be performed', 'invalid');
+            throw new Issue('error', 'business-rule', null, null, 'The code system definition for ' + cset.system + ' defines a supplement, so this expansion cannot be performed', 'invalid', 422);
           } else if (cs.contentMode() === 'fragment') {
             this.addParamUri(exp, 'used-fragment', cs.system()+ (cs.version() ?  '|' + cs.version(): ""));
             Extensions.addBoolean(exp, "http://hl7.org/fhir/StructureDefinition/valueset-unclosed", true);
@@ -715,12 +983,14 @@ class ValueSetExpander {
             // NB: totalCount is a method - as a property read (cs.totalCount) the
             // comparison was against the function object, always false, so this
             // guard was silently dead.
-            if (!imp && this.count !== 0 && this.limitCount > 0 && await cs.totalCount() > this.limitCount
-                && !(this.count > 0 && this.count + Math.max(this.offset, 0) <= this.limitCount)) {
+            // (not when the provider will be handed the compose: it pages and counts the
+            // selection itself - see processCodes)
+            if (!imp && !(vsInfo && vsInfo.handleByCS) && this.count !== 0 && this.limitCount > 0 && await cs.totalCount() > this.limitCount
+                && !this.#pageFits()) {
               // Report the versioned url (vurl), matching the message the
               // enumeration path produces when it hits the same limit - this
               // guard is just that refusal moved earlier.
-              throw new Issue("error", "too-costly", null, 'VALUESET_TOO_COSTLY', this.worker.i18n.translate('VALUESET_TOO_COSTLY', this.params.httpLanguages, [source && source.vurl ? source.vurl : srcURL, '>' + this.limitCount]), null, 422).withDiagnostics(this.worker.opContext.diagnostics());
+              throw new Issue("error", "too-costly", null, 'VALUESET_TOO_COSTLY', this.tooCostlyMessage(source && source.vurl ? source.vurl : srcURL, '>' + this.limitCount), null, 422).withDiagnostics(this.worker.opContext.diagnostics());
             }
           }
         }
@@ -728,22 +998,119 @@ class ValueSetExpander {
     }
   }
 
+  /**
+   * Hand the whole compose to the code system provider (CodeSystemProvider.handlesSelecting /
+   * processSelection). Only called for a compose that selects from one system|version and imports
+   * no value sets (scanValueSet: isSimple), when the provider says it handles selecting.
+   *
+   * Returns true when the provider took the compose: its codes are in the expansion, already
+   * paged by the provider, with the total it reported. Returns false, having added nothing, when
+   * the compose is one this hand-off doesn't cover (a text filter, an enumerated concept list, a
+   * filter with no value, content that isn't complete) or the provider declines by returning
+   * null: the compose then goes through the usual include/exclude path.
+   */
   async processCodes(path, vsSrc, compose, filter, expansion, excludeInactive, notClosed, vsInfo) {
+    const includes = compose.include || [];
+    const excludes = compose.exclude || [];
+    if (!filter.isNull) {
+      // the provider isn't told about a text filter
+      return false;
+    }
+    if ([...includes, ...excludes].some(cset => cset.concept)) {
+      // an enumerated concept carries displays, designations and extensions from the value set
+      return false;
+    }
+    if ([...includes, ...excludes].some(cset => (cset.filter || []).some(fc => !fc.value))) {
+      // the usual path reports the error
+      return false;
+    }
     const cs = await this.worker.findCodeSystem(vsInfo.system, vsInfo.version, this.params, ['complete', 'fragment'],
       false, false, true, null, this.requiredSupplements);
-    if (cs != null) {
+    if (cs == null || cs.contentMode() !== 'complete') {
+      return false;
+    }
+    for (const cset of [...includes, ...excludes]) {
+      Extensions.checkNoModifiers(cset, 'ValueSetExpander.processCodes', 'set', vsSrc.vurl);
+      for (const fc of cset.filter || []) {
+        Extensions.checkNoModifiers(fc, 'ValueSetExpander.processCodes', 'filter', vsSrc.vurl);
+        if (await supplementFilter(cs, fc)) {
+          // a filter on a property that a supplement in use defines: the provider doesn't know
+          // it, and the usual path evaluates it from the supplement
+          return false;
+        }
+      }
+    }
+
+    const selection = await cs.processSelection(this.params, includes, excludes, excludeInactive, this.offset, this.count,
+      { valueSet: { url: vsSrc.url, version: vsSrc.version } });
+    if (selection == null) {
+      return false;
+    }
+    this.worker.opContext.log('compose handled by the code system provider');
+    // checkSource's up-front refusal of a whole-system include is skipped for a compose handed to
+    // the provider (it is told the paging). Apply it here, now that the selection's total is known,
+    // with the same message: it names the versioned url, where includeCode's refusal would name the
+    // plain url. Only the page counts against the limit: the provider pages itself, so a deep page
+    // costs no more than the first one (on the usual path offset + count must fit, because the
+    // codes before the page are built too)
+    const wholeSystemInclude = includes.some(cset => !(cset.filter || []).length);
+    if (wholeSystemInclude && this.count !== 0 && this.limitCount > 0 && selection.total > this.limitCount
+        && !(this.count > 0 && this.count <= this.limitCount)) {
+      throw new Issue("error", "too-costly", null, 'VALUESET_TOO_COSTLY', this.worker.i18n.translate('VALUESET_TOO_COSTLY', this.params.httpLanguages, [vsSrc.vurl || vsSrc.url, '>' + this.limitCount]), null, 422).withDiagnostics(this.worker.opContext.diagnostics());
+    }
+
+    for (const cset of [...includes, ...excludes]) {
+      this.worker.checkSupplements(cs, cset, this.requiredSupplements, this.usedSupplements);
+    }
+    this.checkProviderCanonicalStatus(expansion, cs, this.valueSet);
+    this.addParamUri(expansion, 'used-codesystem', this.canonical(cs.system(), cs.version()));
+    if (selection.notClosed) {
+      notClosed.value = true;
+      const wholeSystem = includes.some(cset => !(cset.filter || []).length);
+      if (wholeSystem && cs.isNotClosed() && !Extensions.has(expansion, "http://hl7.org/fhir/StructureDefinition/valueset-unclosed-reason")) {
+        // as the usual path says for a whole grammar-based code system
+        Extensions.addString(expansion, "http://hl7.org/fhir/StructureDefinition/valueset-unclosed-reason", "The code System '" + cs.system() + "' has a grammar and so has infinite members");
+      }
+    }
 
-      // set up the call to the provider
-      // call the provider
-      // include the codes
+    // the provider has applied offset and count: every code it returns is in the page
+    vsInfo.csDoOffset = true;
+    this.paging = false;
+    this.providerPaged = true;
+    this.canBeHierarchy = false;
+    const cds = new Designations(this.worker.i18n.languageDefinitions);
+    for (const set of selection.sets || []) {
+      while (await cs.filterMore(null, set)) {
+        await this.worker.checkAndYield('processCodes#selection');
+        const c = await cs.filterConcept(null, set);
+        cds.clear();
+        if (this.noDetails) {
+          await this.includeCode(cs, null, cs.system(), cs.version(), await cs.code(c), await cs.isAbstract(c), await cs.isInactive(c),
+            null, null, cds, null, null, expansion, null, null, null, null, null, excludeInactive, vsSrc.url);
+        } else if (this.#defers(cs, await cs.code(c))) {
+          await this.includeCode(cs, null, cs.system(), cs.version(), await cs.code(c), await cs.isAbstract(c), await cs.isInactive(c),
+            null, null, cds, null, null, expansion, null, null, null, null, null, excludeInactive, vsSrc.url, () => this.#readDetails(cs, c));
+        } else {
+          await this.listDisplaysFromProvider(cds, cs, c);
+          await this.includeCode(cs, null, cs.system(), cs.version(), await cs.code(c), await cs.isAbstract(c), await cs.isInactive(c),
+            await cs.isDeprecated(c), await cs.getStatus(c), cds, await cs.definition(c), await cs.itemWeight(c),
+            expansion, null, await cs.extensions(c), null, await this.#conceptProperties(cs, c), null, excludeInactive, vsSrc.url);
+        }
+      }
     }
+    if (selection.total != null && selection.total >= 0) {
+      this.addToTotal(selection.total);
+    } else {
+      this.noTotal();
+    }
+    return true;
   }
 
   async includeCodes(cset, path, vsSrc, compose, filter, expansion, excludeInactive, notClosed) {
     await this.worker.checkAndYield('processCodes#1');
     const valueSets = [];
 
-    Extensions.checkNoModifiers(cset, 'ValueSetExpander.processCodes', 'set', vsSrc.vurl);
+    Extensions.checkNoModifiers(cset, 'ValueSetExpander.processCodes', path, vsSrc.vurl);
 
     if (cset.valueSet || cset.concept || (cset.filter || []).length > 1) {
       this.canBeHierarchy = false;
@@ -755,7 +1122,8 @@ class ValueSetExpander {
         const s = this.worker.pinValueSet(u);
         this.worker.opContext.log('import value set ' + s);
         let vs = await this.worker.findValueSet(s, '', vsSrc);
-        const ivs = new ImportedValueSet(await this.expandValueSet(s, '', vs, filter, notClosed));
+        // the first value set's codes are this include's; the others' only test membership
+        const ivs = new ImportedValueSet(await this.expandValueSet(s, '', vs, filter, notClosed, valueSets.length > 0 || this.#importDefers()));
         this. checkResourceCanonicalStatus(expansion, ivs.valueSet, this.valueSet);
         if (!vs.isContained) {
           this.addParamUri(expansion, 'used-valueset', this.worker.makeVurl(ivs.valueSet));
@@ -782,7 +1150,8 @@ class ValueSetExpander {
           const s = this.worker.pinValueSet(u);
           this.worker.opContext.log('import value set ' + s);
           let vs = await this.worker.findValueSet(s, '', vsSrc);
-          const ivs = new ImportedValueSet(await this.expandValueSet(s, '', vs, filter, notClosed));
+          // (only for which codes it has: the include's codes come from the code system)
+          const ivs = new ImportedValueSet(await this.expandValueSet(s, '', vs, filter, notClosed, true));
           this.checkResourceCanonicalStatus(expansion, ivs.valueSet, this.valueSet);
           if (!vs.isContained) {
             this.addParamUri(expansion, 'used-valueset', this.worker.makeVurl(ivs.valueSet));
@@ -794,7 +1163,7 @@ class ValueSetExpander {
           if (cs.specialEnumeration() && filters.length === 0) {
             this.worker.opContext.log('import special value set ' + cs.specialEnumeration());
             let vs = await this.worker.findValueSet(cs.specialEnumeration(), '', null);
-            const base = await this.expandValueSet(cs.specialEnumeration(), '', vs, filter, notClosed);
+            const base = await this.expandValueSet(cs.specialEnumeration(), '', vs, filter, notClosed, this.#importDefers());
             Extensions.addBoolean(expansion, "http://hl7.org/fhir/StructureDefinition/valueset-unclosed", true);
             Extensions.addString(expansion, "http://hl7.org/fhir/StructureDefinition/valueset-unclosed-reason", "The code System '" + cs.system() + "' has a grammar and so has infinite members. This extension is based on " + cs.specialEnumeration());
             await this.importValueSet(base, expansion, valueSets, 0);
@@ -815,9 +1184,17 @@ class ValueSetExpander {
                 Extensions.addString(expansion, "http://hl7.org/fhir/StructureDefinition/valueset-unclosed-reason", "The code System '" + cs.system() + "' has a grammar and so has infinite members");
               }
               notClosed.value = true;
+            } else if (cs.openCodeSpaceReason()) {
+              // all the codes the code system defines are listed, but not the ones users define in its
+              // reserved code spaces: $validate-code accepts those as members, so the expansion isn't closed
+              if (!Extensions.has(expansion, "http://hl7.org/fhir/StructureDefinition/valueset-unclosed")) {
+                Extensions.addBoolean(expansion, "http://hl7.org/fhir/StructureDefinition/valueset-unclosed", true);
+                Extensions.addString(expansion, "http://hl7.org/fhir/StructureDefinition/valueset-unclosed-reason", cs.openCodeSpaceReason());
+              }
+              notClosed.value = true;
             }
 
-            if (this.count === 0 && filters.length === 0 && valueSets.length === 0) {
+            if (this.count === 0 && filters.length === 0 && valueSets.length === 0 && !this.hasExclusions) {
               // count=0 (count only) with a single whole-code-system include and no
               // additional filters: report the code count directly rather than
               // enumerating - which for a poly-hierarchy (e.g. SNOMED) is both
@@ -825,10 +1202,16 @@ class ValueSetExpander {
               this.addToTotal(await cs.countAllCodes(excludeInactive));
             } else {
               const iter = await cs.iterator(null);
-              if (valueSets.length === 0 && this.limitCount > 0 && (iter && iter.total > this.limitCount) && this.offset < 0) {
-                throw new Issue("error", "too-costly", null, 'VALUESET_TOO_COSTLY', this.worker.i18n.translate('VALUESET_TOO_COSTLY', this.params.httpLanguages, [vsSrc.vurl, '>' + this.limitCount]), null, 422).withDiagnostics(this.worker.opContext.diagnostics());
+              if (valueSets.length === 0 && this.count !== 0 && this.limitCount > 0 && (iter && iter.total > this.limitCount) && this.offset < 0) {
+                throw new Issue("error", "too-costly", null, 'VALUESET_TOO_COSTLY', this.tooCostlyMessage(vsSrc.vurl, '>' + this.limitCount), null, 422).withDiagnostics(this.worker.opContext.diagnostics());
 
               }
+              if (this.paging && valueSets.length === 0 && filters.length === 0 && this.#sizeIsTotal(compose, cs, excludeInactive) && !this.params.excludeNotForUI
+                  && !cs.isNotClosed()) {
+                // the walk would count every code of the code system (excludeNotForUI would skip the
+                // abstract ones; a grammar's walk lists only some): its size is the total
+                this.#useProviderSize(await cs.countAllCodes(excludeInactive));
+              }
               let tcount = 0;
               // One visited set across all roots: in a poly-hierarchy the walks
               // from different roots can reach the same concepts.
@@ -836,19 +1219,31 @@ class ValueSetExpander {
               let c = await cs.nextContext(iter);
               while (c) {
                 await this.worker.checkAndYield('processCodes#3a');
+                if (this.#capReached(cs)) {
+                  // the code system's cap is reached: nothing more of it can be added
+                  this.#noteCapCut(cs);
+                  break;
+                }
                 if (await this.passesFilters(cs, c, prep, filters, 0)) {
                   tcount += await this.includeCodeAndDescendants(cs, c, expansion, valueSets, null, excludeInactive, vsSrc.vurl, visited);
                 }
                 c = await cs.nextContext(iter);
               }
-              this.addToTotal(tcount);
+              if (cs.expandLimitation() > 0 && filters.length === 0 && valueSets.length === 0 && !this.hasExclusions) {
+                // a code system that caps how many of its codes an expansion may list (e.g. CPT): the
+                // cap limits which codes can be on a page, not how many the value set has, so the
+                // total is all of them, as for count=0 (and the walk stopped at the cap)
+                this.addToTotal(await cs.countAllCodes(excludeInactive));
+              } else {
+                this.addToTotal(tcount);
+              }
             }
           } else {
             this.worker.opContext.log('prepare filters');
             if (cs.isNotClosed(filter)) {
               notClosed.value = true;
             }
-            const prep = await cs.getPrepContext(true);
+            const prep = await cs.getPrepContext(true, this.params.requestedLanguages()); // the text filter's language
             const ctxt = await cs.searchFilter(prep, filter, true);
             let set = await cs.executeFilters(prep);
             if (this.count === 0 && valueSets.length === 0) {
@@ -862,17 +1257,31 @@ class ValueSetExpander {
               await this.worker.checkAndYield('processCodes#4');
               const c = await cs.filterConcept(ctxt, set[0]);
               if (await this.passesFilters(cs, c, prep, set, 1)) {
+                const walked = await this.#beforePage(cs, await cs.system(), await cs.version(), await cs.code(c), await cs.isInactive(c), excludeInactive, valueSets);
+                if (walked !== null) {
+                  // (no total on this path: once the page is full there's nothing to count)
+                  if (this.pageFilled()) {
+                    break;
+                  }
+                  continue;
+                }
                 const cds = new Designations(this.worker.i18n.languageDefinitions);
                 let added;
-                if (this.noDetails) {
+                if (!this.noDetails && this.#outsidePage()) {
+                  added = await this.includeCode(cs, null, await cs.system(), await cs.version(), await cs.code(c), await cs.isAbstract(c), await cs.isInactive(c), false, null,
+                      cds, null, null, expansion, valueSets, null, null, null, null, excludeInactive, vsSrc.url);
+                } else if (this.noDetails) {
                   await this.listDisplaysFromProvider(cds, cs, c);
                   added = await this.includeCode(cs, null, await cs.system(), await cs.version(), await cs.code(c), await cs.isAbstract(c), await cs.isInactive(c), false, null,
                       cds, null, null, expansion, valueSets, null, null, null, null, excludeInactive, vsSrc.url);
 
+                } else if (this.#defers(cs, await cs.code(c))) {
+                  added = await this.includeCode(cs, null, await cs.system(), await cs.version(), await cs.code(c), await cs.isAbstract(c), await cs.isInactive(c), false, null,
+                      cds, null, null, expansion, valueSets, null, null, null, null, excludeInactive, vsSrc.url, () => this.#readDetails(cs, c));
                 } else {
                   await this.listDisplaysFromProvider(cds, cs, c);
                   added = await this.includeCode(cs, null, await cs.system(), await cs.version(), await cs.code(c), await cs.isAbstract(c), await cs.isInactive(c), await cs.isDeprecated(c), await cs.getStatus(c),
-                      cds, await cs.definition(c), await cs.itemWeight(c), expansion, valueSets, await cs.extensions(c), null, await cs.properties(c), null, excludeInactive, vsSrc.url);
+                      cds, await cs.definition(c), await cs.itemWeight(c), expansion, valueSets, await cs.extensions(c), null, await this.#conceptProperties(cs, c), null, excludeInactive, vsSrc.url);
                 }
                 if (added) {
                   this.addToTotal();
@@ -892,35 +1301,86 @@ class ValueSetExpander {
           }
         }
 
-        if (cset.concept) {
+        // A value set that lists its codes: count them first - locating each code is cheap,
+        // building it (displays, properties) is not. count=0 asks only for the total, so when
+        // every include lists its codes, the count is the answer; otherwise, if the codes
+        // would take the expansion over the limit, refuse now rather than after building them
+        // (only worth a pass when it could change anything: the list alone could be over the limit)
+        const countFirst = cset.concept && filter.isNull
+          && ((this.count === 0 && this.composeOnlyListsCodes) || this.#listedCodesOverLimit(cset.concept.length));
+        const counted = countFirst ? await this.#countListedCodes(cs, cset, valueSets, filters, prep, excludeInactive) : null;
+        if (counted && this.count === 0 && this.composeOnlyListsCodes) {
+          this.worker.opContext.log('count only: counted the listed codes');
+          for (const key of counted) {
+            this.countedKeys.add(key);
+          }
+          if (counted.size > 0 && !this.noDetails) {
+            this.addParamUri(expansion, 'used-codesystem', this.canonical(cs.system(), cs.version()));
+            for (const vs of cs.listSupplements(false)) {
+              this.reportedSupplements.add(vs);
+            }
+          }
+          this.addToTotal(counted.size);
+        } else if (cset.concept) {
+          if (counted && this.#listedCodesOverLimit(counted.size)) {
+            throw new Issue("error", "too-costly", null, 'VALUESET_TOO_COSTLY', this.tooCostlyMessage(vsSrc.url, '>' + this.limitCount), null, 422).withDiagnostics(this.worker.opContext.diagnostics());
+          }
           this.worker.opContext.log('iterate concepts');
           const cds = new Designations(this.worker.i18n.languageDefinitions);
-
-          for (const cc of cset.concept) {
+          // a text filter matches designations in one language (see CodeSystemProvider.searchLanguage)
+          const searchLang = filter.isNull ? null : cs.searchLanguage(this.params.requestedLanguages());
+
+          // each listed code is located next: a provider may read them together, and hand back what it read
+          // (paging: most of them may only be counted, and those on the page are read at locate -
+          // unless the page holds the whole list, when every one is built. And not when their
+          // details are left to be read later: see deferDetails)
+          const prefetched = await cs.prefetchCodes(cset.concept.map(cc => cc.code),
+            !this.noDetails && !(filter.isNull && this.#defers(cs)) && (!this.paging || this.#pageHolds(cset.concept.length)));
+          for (const [ci, cc] of cset.concept.entries()) {
             await this.worker.checkAndYield('processCodes#3');
             cds.clear();
-            Extensions.checkNoModifiers(cc, 'ValueSetExpander.processCodes', 'set concept reference', vsSrc.vurl);
-            const cctxt = await cs.locate(cc.code, this.allAltCodes);
+            Extensions.checkNoModifiers(cc, 'ValueSetExpander.processCodes', path + '.concept[' + ci + ']', vsSrc.vurl);
+            const cctxt = await cs.locate(cc.code, prefetched);
             if (cctxt && cctxt.context && (!this.params.activeOnly || !await cs.isInactive(cctxt.context)) && await this.passesFilters(cs, cctxt.context, prep, filters, 0)) {
               let added;
               const ecode = await cs.expansionCode(cctxt.context, cc.code);
+              const walked = await this.#beforePage(cs, cs.system(), cs.version(), ecode, await cs.isInactive(cctxt.context), excludeInactive, valueSets);
+              if (walked !== null) {
+                if (walked) {
+                  this.addToTotal();
+                }
+                continue;
+              }
               if (this.noDetails) {
                 added = await this.includeCode(cs, null, cs.system(), cs.version(), ecode, await cs.isAbstract(cctxt.context), await cs.isInactive(cctxt.context), null, null, cds,
                     null, null, expansion, valueSets, null, null, null, null, excludeInactive, vsSrc.url);
+              } else if (filter.isNull && this.#outsidePage()) {
+                added = await this.includeCode(cs, null, cs.system(), cs.version(), ecode, await cs.isAbstract(cctxt.context), await cs.isInactive(cctxt.context), null, null, cds,
+                    null, null, expansion, valueSets, null, null, null, null, excludeInactive, vsSrc.url);
+                if (added) {
+                  this.addToTotal();
+                }
+              } else if (filter.isNull && this.#defers(cs, ecode)) {
+                added = await this.includeCode(cs, null, cs.system(), cs.version(), ecode, await cs.isAbstract(cctxt.context), await cs.isInactive(cctxt.context), null, null, cds,
+                    null, null, expansion, valueSets, null, null, null, null, excludeInactive, vsSrc.url, () => this.#readDetails(cs, cctxt.context, cc, vsSrc));
+                if (added) {
+                  this.addToTotal();
+                }
               } else {
                 await this.listDisplaysFromProvider(cds, cs, cctxt.context);
                 this.listDisplaysFromIncludeConcept(cds, cc, vsSrc);
-                if (filter.passesDesignations(cds) || filter.passes(cc.code)) {
+                if (filter.passesDesignations(cds, searchLang, cs.defLang()) || filter.passes(cc.code)) {
                   let ov = Extensions.readString(cc, 'http://hl7.org/fhir/StructureDefinition/itemWeight');
                   if (!ov) {
                     ov = await cs.itemWeight(cctxt.context);
                   }
                   added = await this.includeCode(cs, null, cs.system(), cs.version(), ecode, await cs.isAbstract(cctxt.context), await cs.isInactive(cctxt.context), await cs.isDeprecated(cctxt.context), await cs.getStatus(cctxt.context), cds,
-                      await cs.definition(cctxt.context), ov, expansion, valueSets, await cs.extensions(cctxt.context), cc.extension, await cs.properties(cctxt.context), null, excludeInactive, vsSrc.url);
+                      await cs.definition(cctxt.context), ov, expansion, valueSets, await cs.extensions(cctxt.context), cc.extension, await this.#conceptProperties(cs, cctxt.context), null, excludeInactive, vsSrc.url);
                 }
                 if (added) {
                   this.addToTotal();
                 }
+                this.#finishIfPageFilled();
               }
             }
           }
@@ -930,7 +1390,7 @@ class ValueSetExpander {
         if (cset.filter && cset.filter.length > 0) {
           this.worker.opContext.log('prepare filters');
           const fcl = cset.filter;
-          const prep = await cs.getPrepContext(true);
+          const prep = await cs.getPrepContext(true, this.params.requestedLanguages());
 
           if (!filter.isNull) {
             await cs.searchFilter(prep, filter, true);
@@ -943,17 +1403,23 @@ class ValueSetExpander {
           }
 
           for (let i = 0; i < fcl.length; i++) {
-            await this.worker.checkAndYield('processCodes#4a');
             const fc = fcl[i];
             if (!fc.value) {
               throw new Issue('error', 'invalid', path + ".filter[" + i + "]", 'UNABLE_TO_HANDLE_SYSTEM_FILTER_WITH_NO_VALUE', this.worker.i18n.translate('UNABLE_TO_HANDLE_SYSTEM_FILTER_WITH_NO_VALUE', this.params.httpLanguages, [cs.system(), fc.property, fc.op]), 'vs-invalid', 400);
             }
-            Extensions.checkNoModifiers(fc, 'ValueSetExpander.processCodes', 'filter', vsSrc.vurl);
+            Extensions.checkNoModifiers(fc, 'ValueSetExpander.processCodes', path + '.filter[' + i + ']', vsSrc.vurl);
+          }
+          // filters on properties that supplements in use define are evaluated from the
+          // supplements; the code system does the rest
+          const { base: baseFilters, supplement: suppFilters } = await splitFilters(cs, fcl);
+          for (let i = 0; i < baseFilters.length; i++) {
+            await this.worker.checkAndYield('processCodes#4a');
+            const fc = baseFilters[i];
             await cs.filter(prep, i == 0, fc.property, fc.op, fc.value, vsSrc.isCached ? fc : null);
           }
 
-          const fset = await cs.executeFilters(prep);
-          const filtersOpen = await cs.filtersNotClosed(prep);
+          const fset = baseFilters.length > 0 ? await cs.executeFilters(prep) : [];
+          const filtersOpen = baseFilters.length > 0 && await cs.filtersNotClosed(prep);
           if (filtersOpen) {
             notClosed.value = true;
           }
@@ -963,32 +1429,49 @@ class ValueSetExpander {
           // total is the set's size, and walking it would only end in VALUESET_TOO_COSTLY once
           // the set is bigger than the limit. Anything less certain is counted by walking, as
           // before: an earlier version added filterSize *and* walked, and double counted (#91, #93).
-          const countOnly = this.count === 0 && !filtersOpen && fset.length === 1 && filter.isNull
-            && !excludeInactive && !this.params.activeOnly && !this.hasExclusions
-            && !(cset.concept && cset.concept.length) && !(cset.valueSet && cset.valueSet.length)
-            && (compose.include || []).length === 1 && (compose.exclude || []).length === 0;
+          // The same holds for a page: once it is full, the walk would only count the rest of the set
+          const sizeIsTotal = !filtersOpen && fset.length === 1 && suppFilters.length === 0 && filter.isNull
+            && !(cset.concept && cset.concept.length) && !(cset.valueSet && cset.valueSet.length) && this.#sizeIsTotal(compose, cs, excludeInactive);
+          const countOnly = this.count === 0 && sizeIsTotal;
           if (countOnly) {
             this.worker.opContext.log('count only: the filter size is the total');
             this.addToTotal(await cs.filterSize(prep, fset[0]));
+          } else if (this.paging && sizeIsTotal) {
+            this.#useProviderSize(await cs.filterSize(prep, fset[0]));
           }
 
           this.worker.opContext.log('iterate filters');
           this.addToTotal(0);
           const cds = new Designations(this.worker.i18n.languageDefinitions);
-          while (!countOnly && await cs.filterMore(prep, fset[0])) {
-            await this.worker.checkAndYield('processCodes#5');
-            const c = await cs.filterConcept(prep, fset[0]);
-            const ok = (!this.params.activeOnly || !await cs.isInactive(c)) && (await this.passesFilters(cs, c, prep, fset, 1));
-            if (ok) {
+          const addFound = async (c) => {
+            {
               cds.clear();
               // count++;
               if (this.passesImports(valueSets, cs.system(), await cs.code(c), 0)) {
+                const walked = await this.#beforePage(cs, await cs.system(), await cs.version(), await cs.code(c), await cs.isInactive(c), excludeInactive, null);
+                if (walked !== null) {
+                  if (walked) {
+                    this.addToTotal();
+                  }
+                  return;
+                }
                 let added;
-                if (this.noDetails) {
+                if (this.noDetails || this.#outsidePage()) {
                   added = await this.includeCode(cs, null, await cs.system(), await cs.version(), await cs.code(c), await cs.isAbstract(c), await cs.isInactive(c),
                       null,  null, cds, null, null,
                       expansion, null, null, null, null, null, excludeInactive, vsSrc.url);
 
+                } else if (this.#defers(cs, await cs.code(c))) {
+                  // (the parent as below: the hierarchy decides the order an importing expansion takes the codes in)
+                  let parent = null;
+                  if (cs.hasParents()) {
+                    parent = this.map.get(this.keyS(cs.system(), cs.version(), await cs.parent(c)));
+                  } else {
+                    this.canBeHierarchy = false;
+                  }
+                  added = await this.includeCode(cs, parent, await cs.system(), await cs.version(), await cs.code(c), await cs.isAbstract(c), await cs.isInactive(c),
+                      null,  null, cds, null, null,
+                      expansion, null, null, null, null, null, excludeInactive, vsSrc.url, () => this.#readDetails(cs, c));
                 } else {
                   await this.listDisplaysFromProvider(cds, cs, c);
                   let parent = null;
@@ -999,11 +1482,31 @@ class ValueSetExpander {
                   }
                   added = await this.includeCode(cs, parent, await cs.system(), await cs.version(), await cs.code(c), await cs.isAbstract(c), await cs.isInactive(c),
                       await cs.isDeprecated(c), await cs.getStatus(c), cds, await cs.definition(c), await cs.itemWeight(c),
-                      expansion, null, await cs.extensions(c), null, await cs.properties(c), null, excludeInactive, vsSrc.url);
+                      expansion, null, await cs.extensions(c), null, await this.#conceptProperties(cs, c), null, excludeInactive, vsSrc.url);
                 }
                 if (added) {
                   this.addToTotal();
                 }
+                this.#finishIfPageFilled();
+              }
+            }
+          };
+          if (baseFilters.length > 0) {
+            while (!countOnly && await cs.filterMore(prep, fset[0])) {
+              await this.worker.checkAndYield('processCodes#5');
+              const c = await cs.filterConcept(prep, fset[0]);
+              const ok = (!this.params.activeOnly || !await cs.isInactive(c)) && (await this.passesFilters(cs, c, prep, fset, 1))
+                && (await this.#passesSupplementFilters(cs, c, suppFilters));
+              if (ok) {
+                await addFound(c);
+              }
+            }
+          } else {
+            // only filters on supplement properties: the codes are those the supplements list
+            for (const c of await this.#supplementFilterConcepts(cs, suppFilters, path)) {
+              await this.worker.checkAndYield('processCodes#5');
+              if ((!this.params.activeOnly || !await cs.isInactive(c)) && (filter.isNull || filter.passes(await cs.code(c)) || filter.passes(await cs.display(c)))) {
+                await addFound(c);
               }
             }
           }
@@ -1013,6 +1516,41 @@ class ValueSetExpander {
     }
   }
 
+  async #passesSupplementFilters(cs, c, suppFilters) {
+    if (suppFilters.length === 0) {
+      return true;
+    }
+    const code = await cs.code(c);
+    return suppFilters.every(sf => sf.matches(code));
+  }
+
+  /**
+   * The concepts selected by filters that are all on supplement properties: the codes a
+   * supplement lists that pass them all, and that the code system has (a supplement can list
+   * a code the code system doesn't)
+   */
+  async #supplementFilterConcepts(cs, suppFilters, path) {
+    const driver = suppFilters.find(sf => sf.enumerable);
+    if (!driver) {
+      // not-in / exists = false select codes by what the supplement doesn't say, which needs the
+      // rest of the code system to select from
+      const sf = suppFilters[0];
+      throw new Issue('error', 'not-supported', path + '.filter', 'FILTER_NOT_UNDERSTOOD',
+        this.worker.i18n.translate('FILTER_NOT_UNDERSTOOD', this.params.HTTPLanguages, [sf.property, sf.op, sf.value]), 'vs-invalid', 422);
+    }
+    const result = [];
+    for (const code of driver.codes()) {
+      await this.worker.checkAndYield('supplementFilterConcepts');
+      if (suppFilters.every(sf => sf === driver || sf.matches(code))) {
+        const loc = await cs.locate(code);
+        if (loc && loc.context) {
+          result.push(loc.context);
+        }
+      }
+    }
+    return result;
+  }
+
   async passesFilters(cs, c, prep, filters, offset) {
     for (let j = offset; j < filters.length; j++) {
       const f = filters[j];
@@ -1028,7 +1566,7 @@ class ValueSetExpander {
     await this.worker.checkAndYield('processCodes#1');
     const valueSets = [];
 
-    Extensions.checkNoModifiers(cset, 'ValueSetExpander.processCodes', 'set', vsSrc.vurl);
+    Extensions.checkNoModifiers(cset, 'ValueSetExpander.processCodes', path, vsSrc.vurl);
 
     if (cset.valueSet || cset.concept || (cset.filter || []).length > 1) {
       this.canBeHierarchy = false;
@@ -1041,7 +1579,8 @@ class ValueSetExpander {
           const s = this.worker.pinValueSet(u);
           await this.worker.checkAndYield('processCodes#2');
           let vs = await this.worker.findValueSet(s, '', vsSrc);
-          const ivs = new ImportedValueSet(await this.expandValueSet(s, '',  vs, filter, notClosed));
+          // (only for which codes it has, as for the excludes below)
+          const ivs = new ImportedValueSet(await this.expandValueSet(s, '',  vs, filter, notClosed, true));
           this.checkResourceCanonicalStatus(expansion, ivs.valueSet, this.valueSet);
           // ivs.valueSet is the expansion (plain JSON), so it has no vurl - as for the
           // includes, build it
@@ -1071,7 +1610,7 @@ class ValueSetExpander {
           const s = this.worker.pinValueSet(u);
           this.worker.opContext.log('import value set ' + s);
           let vs = await this.worker.findValueSet(s, '', vsSrc);
-          const ivs = new ImportedValueSet(await this.expandValueSet(s, '', vs, filter, notClosed));
+          const ivs = new ImportedValueSet(await this.expandValueSet(s, '', vs, filter, notClosed, true));
           this.checkResourceCanonicalStatus(expansion, ivs.valueSet, this.valueSet);
           if (!vs.isContained) {
             this.addParamUri(expansion, 'used-valueset', this.worker.makeVurl(ivs.valueSet));
@@ -1086,15 +1625,11 @@ class ValueSetExpander {
               // excluding a whole system - we don't list the codes in this case
               this.excludedSystems.add(cset.system + (this.doingVersion && cset.version ? '|' + cset.version : ''));
             } else {
-              const iter = await cs.iteratorAll();
-              if (iter) {
-                let c = await cs.nextContext(iter);
-                while (c) {
-                  await this.worker.checkAndYield('processCodes#3aa');
-                  this.excludeCode(cs, cs.system(), cs.version(), await cs.code(c), expansion, valueSets, vsSrc.url);
-                  c = await cs.nextContext(iter);
-                }
-              }
+              // include one version, exclude another whole version: a code is
+              // excluded if it exists in the excluded version. We don't list
+              // the excluded version's codes (most providers can't - e.g.
+              // SNOMED CT, LOINC); we ask it about each included code instead
+              this.excludedProviders.push({ system: cs.system(), cs });
             }
           } else {
             if (cs.isNotClosed(filter)) {
@@ -1110,15 +1645,15 @@ class ValueSetExpander {
               }
             }
 
-            const iter = await cs.iteratorAll();
-            if (iter) {
-              let c = await cs.nextContext(iter);
-              while (c) {
-                await this.worker.checkAndYield('processCodes#3a');
-                if (await this.passesFilters(cs, c, prep, filters, 0)) {
-                  this.excludeCode(cs, cs.system(), cs.version(), await cs.code(c), expansion, valueSets, vsSrc.url);
-                }
-                c = await cs.nextContext(iter);
+            // the codes of this system that are in all the value sets. Walk the
+            // first value set's codes, not the code system (most providers
+            // can't list theirs - e.g. SNOMED CT, LOINC); excludeCode checks
+            // the other value sets
+            const system = cs.system();
+            for (const entry of valueSets[0].codeMap.values()) {
+              await this.worker.checkAndYield('processCodes#3a');
+              if (entry.system === system && await this.#knownTo(cs, entry.code)) {
+                this.excludeCode(cs, system, cs.version(), entry.code, expansion, valueSets);
               }
             }
           }
@@ -1127,18 +1662,22 @@ class ValueSetExpander {
         if (cset.concept) {
           this.worker.opContext.log('iterate concepts');
           const cds = new Designations(this.worker.i18n.languageDefinitions);
-          for (const cc of cset.concept) {
+          // a text filter matches designations in one language (see CodeSystemProvider.searchLanguage)
+          const searchLang = filter.isNull ? null : cs.searchLanguage(this.params.requestedLanguages());
+          // each listed code is located next: a provider may read them together, and hand back what it read
+          const prefetched = await cs.prefetchCodes(cset.concept.map(cc => cc.code), false);
+          for (const [ci, cc] of cset.concept.entries()) {
             await this.worker.checkAndYield('processCodes#3');
             cds.clear();
-            Extensions.checkNoModifiers(cc, 'ValueSetExpander.processCodes', 'set concept reference', vsSrc.vurl);
-            const cctxt = await cs.locate(cc.code, this.allAltCodes);
+            Extensions.checkNoModifiers(cc, 'ValueSetExpander.processCodes', path + '.concept[' + ci + ']', vsSrc.vurl);
+            const cctxt = await cs.locate(cc.code, prefetched);
             if (cctxt && cctxt.context && (!this.params.activeOnly || !await cs.isInactive(cctxt.context)) && await this.passesFilters(cs, cctxt.context, prep, filters, 0)) {
-              if (filter.passesDesignations(cds) || filter.passes(cc.code)) {
+              if (filter.passesDesignations(cds, searchLang, cs.defLang()) || filter.passes(cc.code)) {
                 let ov = Extensions.readString(cc, 'http://hl7.org/fhir/StructureDefinition/itemWeight');
                 if (!ov) {
                   ov = await cs.itemWeight(cctxt.context);
                 }
-                this.excludeCode(cs, await cs.system(), await cs.version(), cc.code, expansion, valueSets, vsSrc.url);
+                this.excludeCode(cs, await cs.system(), await cs.version(), cc.code, expansion, valueSets);
               }
             }
           }
@@ -1146,7 +1685,7 @@ class ValueSetExpander {
 
         if (cset.filter) {
           this.worker.opContext.log('prep filters');
-          const prep = await cs.getPrepContext(true);
+          const prep = await cs.getPrepContext(true, this.params.requestedLanguages());
           if (!filter.isNull) {
             await cs.searchFilter(prep, filter, true);
           }
@@ -1157,30 +1696,42 @@ class ValueSetExpander {
             Extensions.addString(expansion, "http://hl7.org/fhir/StructureDefinition/valueset-unclosed-reason", "The code System '" + cs.system() + "' has a grammar and so has infinite members. This extension is based on " + cs.specialEnumeration());
           }
 
+          for (const [i, fc] of cset.filter.entries()) {
+            Extensions.checkNoModifiers(fc, 'ValueSetExpander.processCodes', path + '.filter[' + i + ']', vsSrc.vurl);
+          }
+          // as for an include: filters on properties that supplements define are evaluated from them
+          const { base: baseFilters, supplement: suppFilters } = await splitFilters(cs, cset.filter);
           let first = true;
-          for (let fc of cset.filter) {
+          for (let fc of baseFilters) {
             await this.worker.checkAndYield('processCodes#4a');
-            Extensions.checkNoModifiers(fc, 'ValueSetExpander.processCodes', 'filter', vsSrc.vurl);
             await cs.filter(prep, first, fc.property, fc.op, fc.value, vsSrc.isCached ? fc : null);
             first = false;
           }
 
           this.worker.opContext.log('iterate filters');
-          const fset = await cs.executeFilters(prep);
-          if (await cs.filtersNotClosed(prep)) {
-            notClosed.value = true;
-          }
-          //let count = 0;
-          while (await cs.filterMore(prep, fset[0])) {
-            await this.worker.checkAndYield('processCodes#5');
-            const c = await cs.filterConcept(prep, fset[0]);
-            const ok = (!this.params.activeOnly || !await cs.isInactive(c)) && (await this.passesFilters(cs, c, prep, fset, 1));
-            if (ok) {
-              //count++;
-              if (this.passesImports(valueSets, await cs.system(), await cs.code(c), 0)) {
-                this.excludeCode(cs, await cs.system(), await cs.version(), await cs.code(c), expansion, null, vsSrc.url);
+          const excludeFound = async (c) => {
+            if (this.passesImports(valueSets, await cs.system(), await cs.code(c), 0)) {
+              this.excludeCode(cs, await cs.system(), await cs.version(), await cs.code(c), expansion, null);
+            }
+          };
+          if (baseFilters.length > 0) {
+            const fset = await cs.executeFilters(prep);
+            if (await cs.filtersNotClosed(prep)) {
+              notClosed.value = true;
+            }
+            while (await cs.filterMore(prep, fset[0])) {
+              await this.worker.checkAndYield('processCodes#5');
+              const c = await cs.filterConcept(prep, fset[0]);
+              const ok = (!this.params.activeOnly || !await cs.isInactive(c)) && (await this.passesFilters(cs, c, prep, fset, 1))
+                && (await this.#passesSupplementFilters(cs, c, suppFilters));
+              if (ok) {
+                await excludeFound(c);
               }
             }
+          } else {
+            for (const c of await this.#supplementFilterConcepts(cs, suppFilters, 'ValueSet.compose.exclude')) {
+              await excludeFound(c);
+            }
           }
           this.worker.opContext.log('iterate filters finished');
         }
@@ -1212,6 +1763,11 @@ class ValueSetExpander {
       return 0;
     }
     visited.add(code);
+    if (this.#capReached(cs)) {
+      // the code system's cap is reached: nothing more of it can be added, so don't walk it further
+      this.#noteCapCut(cs);
+      return 0;
+    }
 
     if (expansion) {
       const vs = this.canonical(await cs.system(), await cs.version());
@@ -1223,17 +1779,28 @@ class ValueSetExpander {
     }
 
     let n = null;
-    if ((!this.params.excludeNotForUI || !await cs.isAbstract(context)) && (!this.params.activeOnly || !await cs.isInactive(context))) {
+    const walked = (!this.params.excludeNotForUI || !await cs.isAbstract(context)) && (!this.params.activeOnly || !await cs.isInactive(context))
+      ? await this.#beforePage(cs, await cs.system(), await cs.version(), code, await cs.isInactive(context), excludeInactive, imports) : null;
+    if (walked !== null) {
+      // before the page: counted (or not), and its descendants are walked below
+      if (walked) {
+        result++;
+      }
+      n = parent;
+    } else if ((!this.params.excludeNotForUI || !await cs.isAbstract(context)) && (!this.params.activeOnly || !await cs.isInactive(context))) {
       const cds = new Designations(this.worker.i18n.languageDefinitions);
       let t;
-      if (this.noDetails) {
+      if (this.noDetails || this.#outsidePage()) {
         t = await this.includeCode(cs, null, await cs.system(), await cs.version(), code, await cs.isAbstract(context), await cs.isInactive(context), null, null, null,
             null, null, expansion, imports, null, null, null, null, excludeInactive, srcUrl);
 
+      } else if (this.#defers(cs, code)) {
+        t = await this.includeCode(cs, parent, await cs.system(), await cs.version(), code, await cs.isAbstract(context), await cs.isInactive(context), null, null, null,
+            null, null, expansion, imports, null, null, null, null, excludeInactive, srcUrl, () => this.#readDetails(cs, context));
       } else {
         await this.listDisplaysFromProvider(cds, cs, context);
         t = await this.includeCode(cs, parent, await cs.system(), await cs.version(), code, await cs.isAbstract(context), await cs.isInactive(context), await cs.isDeprecated(context), await cs.getStatus(context), cds, await cs.definition(context),
-            await cs.itemWeight(context), expansion, imports, await cs.extensions(context), null, await cs.properties(context), null, excludeInactive, srcUrl);
+            await cs.itemWeight(context), expansion, imports, await cs.extensions(context), null, await this.#conceptProperties(cs, context), null, excludeInactive, srcUrl);
       }
       if (t != null) {
         result++;
@@ -1241,6 +1808,7 @@ class ValueSetExpander {
       if (n == null) {
         n = t;
       }
+      this.#finishIfPageFilled();
     } else {
       n = parent;
     }
@@ -1286,7 +1854,7 @@ class ValueSetExpander {
       const cds = new Designations(this.worker.i18n.languageDefinitions);
       await this.listDisplaysFromProvider(cds, cs, context);
       await this.worker.checkAndYield('processCodeAndDescendants#2');
-      this.excludeCode(cs, await cs.system(), await cs.version(), code, expansion, imports, srcUrl);
+      this.excludeCode(cs, await cs.system(), await cs.version(), code, expansion, imports);
     }
 
     const iter = await cs.iterator(context);
@@ -1302,21 +1870,32 @@ class ValueSetExpander {
     this.worker.opContext.log('compose #1');
 
     this.doingVersion = false;
+    // count=0 can be answered by counting listed codes when that's all the value set is
+    this.composeOnlyListsCodes = (source.jsonObj.compose.include || []).every(inc => inc.system && inc.concept && inc.concept.length > 0
+      && !(inc.filter && inc.filter.length) && !(inc.valueSet && inc.valueSet.length));
+    // A page (count, and offset - 0 when not given) is the only part of the expansion built: the
+    // walk passes the codes before it keeping only their keys (#beforePage), so a page can be
+    // further in than the limit on what is built, and after it only counts codes, for the total
+    // (#finishIfPageFilled). With exclusions too: they are all processed before any include, so a
+    // code's place in the list is final once it is added. Not with a text filter, which is matched
+    // against the codes' designations, so each must be read. (A hierarchy is
+    // only shown when the whole expansion fits in count: then every code is on the page)
+    this.paging = this.count > 0 && this.offset >= 0 && filter.isNull;
     const ts = new Map();
-    for (const c of source.jsonObj.compose.include || []) {
+    for (const [i, c] of (source.jsonObj.compose.include || []).entries()) {
       await this.worker.checkAndYield('handleCompose#2');
-      await this.checkSource(c, expansion, filter, source.url, ts, vsInfo, source);
+      await this.checkSource(c, expansion, filter, source.url, ts, vsInfo, source, 'ValueSet.compose.include[' + i + ']');
     }
-    for (const c of source.jsonObj.compose.exclude || []) {
+    for (const [i, c] of (source.jsonObj.compose.exclude || []).entries()) {
       await this.worker.checkAndYield('handleCompose#3');
       this.hasExclusions = true;
-      await this.checkSource(c, expansion, filter, source.url, ts, null, source);
+      await this.checkSource(c, expansion, filter, source.url, ts, null, source, 'ValueSet.compose.exclude[' + i + ']');
     }
 
     this.worker.opContext.log('compose #2');
 
-    if (vsInfo.handleByCS) {
-      await this.processCodes("ValueSet.compose", source, source.jsonObj.compose, filter, expansion, this.excludeInactives(source), notClosed, vsInfo);
+    if (vsInfo.handleByCS && await this.processCodes("ValueSet.compose", source, source.jsonObj.compose, filter, expansion, this.excludeInactives(source), notClosed, vsInfo)) {
+      // the code system provider selected the codes (processSelection)
     } else {
       this.checkForExclusionVersionSpecialCase(source, expansion);
 
@@ -1342,6 +1921,71 @@ class ValueSetExpander {
     }
   }
 
+  /**
+   * Whether a value set's stored expansion is the answer. When it has a compose, the compose is
+   * what's expanded - a stored expansion may have been made from other code system versions, or
+   * just be wrong, and there's no telling without expanding the compose - unless a code system the
+   * compose includes isn't available here (not loaded, or not the version the include names): then
+   * the compose can't be expanded, and the stored expansion is the best answer there is
+   * @param {Object} vs - the value set (JSON)
+   * @returns {Promise<boolean>}
+   */
+  async useStoredExpansion(vs) {
+    if (!vs.compose) {
+      return true;
+    }
+    // finding the code systems records the version parameters it applied; this is only a look
+    const found = this.worker.foundParameters.length;
+    try {
+      for (const inc of [...(vs.compose.include || []), ...(vs.compose.exclude || [])]) {
+        if (inc.system) {
+          const cs = await this.worker.findCodeSystem(inc.system, inc.version || '', this.params, ['complete', 'fragment'], null, true);
+          if (!cs) {
+            this.worker.opContext.log(`${inc.system}${inc.version ? '|' + inc.version : ''} isn't available: using the stored expansion of ${vs.url}`);
+            return true;
+          }
+        }
+      }
+    } catch (error) {
+      return false; // expanding the compose will report the problem properly
+    } finally {
+      this.worker.foundParameters.length = found;
+    }
+    return false;
+  }
+
+  /**
+   * How a value set is named in a message: by the url (|version) given, else as the value set this
+   * expander is expanding - its url|version, else its id - else null, for one with neither (a value
+   * set passed inline in the request)
+   * @param {string} [name] - the url (|version) the caller has, if any
+   * @returns {string}
+   */
+  vsLabel(name) {
+    if (name && !String(name).startsWith('undefined')) { // (a vurl with no url is 'undefined|version')
+      return name;
+    }
+    const json = this.valueSet ? (this.valueSet.jsonObj || this.valueSet) : null;
+    if (json && json.url) {
+      return json.version ? json.url + '|' + json.version : json.url;
+    }
+    if (json && json.id) {
+      return json.id;
+    }
+    return null;
+  }
+
+  /**
+   * The VALUESET_TOO_COSTLY message for a value set (see vsLabel), or for one passed in the
+   * request with no url or id, which it can't name, VALUESET_TOO_COSTLY_REQUEST - the message
+   * id reported is VALUESET_TOO_COSTLY either way
+   */
+  tooCostlyMessage(name, limit) {
+    const label = this.vsLabel(name);
+    return label ? this.worker.i18n.translate('VALUESET_TOO_COSTLY', this.params.httpLanguages, [label, limit])
+      : this.worker.i18n.translate('VALUESET_TOO_COSTLY_REQUEST', this.params.httpLanguages, [limit]);
+  }
+
   excludeInactives(source) {
     return source.jsonObj.compose && source.jsonObj.compose.inactive != undefined && !source.jsonObj.compose.inactive;
   }
@@ -1388,7 +2032,11 @@ class ValueSetExpander {
     }
 
     if (result.expansion) {
-      return result; // just return the expansion
+      if (await this.useStoredExpansion(source.jsonObj)) {
+        return result; // just return the expansion
+      }
+      // otherwise it's expanded from the compose, as if it had no expansion
+      result.expansion = undefined;
     }
     if (!source.jsonObj.compose) {
       throw new Issue('error', 'invalid', null, 'VALUESET_NO_COMPOSE',
@@ -1482,7 +2130,7 @@ class ValueSetExpander {
 
     let vsInfo = this.scanValueSet(source.jsonObj.compose);
     try {
-      if (source.jsonObj.compose && Extensions.checkNoModifiers(source.jsonObj.compose, 'ValueSetExpander.Expand', 'compose', source.vurl)
+      if (source.jsonObj.compose && Extensions.checkNoModifiers(source.jsonObj.compose, 'ValueSetExpander.Expand', 'ValueSet.compose', source.vurl)
           && this.worker.checkNoLockedDate(source.url, source.jsonObj.compose)) {
         await this.handleCompose(source, filter, exp, notClosed, vsInfo);
       }
@@ -1517,6 +2165,10 @@ class ValueSetExpander {
     for (const v of ts) {
       this.addParamUri(exp, 'used-supplement', v);
     }
+    if (this.capCut) {
+      this.addExpansionIssue(result, exp, new Issue('warning', 'business-rule', null, 'VALUESET_EXPANSION_CODESYSTEM_LIMITED',
+        this.worker.i18n.translate('VALUESET_EXPANSION_CODESYSTEM_LIMITED', this.params.httpLanguages, [this.capCut.system, this.capCut.limit]), 'business-rule'));
+    }
 
     this.worker.opContext.log('finish up');
 
@@ -1556,9 +2208,10 @@ class ValueSetExpander {
       }
     }
 
-    if (this.offset + this.count < 0 && this.fullList.length > this.limit) {
-      this.log.log('Operation took too long @ expand (' + this.constructor.name + ')');
-      throw new Issue("error", "too-costly", null, 'VALUESET_TOO_COSTLY', this.worker.i18n.translate('VALUESET_TOO_COSTLY', this.params.httpLanguages, [source.vurl, '>' + this.limit]), null, 422).withDiagnostics(this.worker.opContext.diagnostics());
+    if (this.count < 0 && this.limitCount > 0 && this.fullList.length > this.limitCount) {
+      // a backstop for an unpaged expansion: every path that adds a code checks the limit first
+      // (#checkLimit). Not for count=0, which only counts, as far as the walk limit allows
+      throw new Issue("error", "too-costly", null, 'VALUESET_TOO_COSTLY', this.tooCostlyMessage(source.vurl, '>' + this.limitCount), null, 422).withDiagnostics(this.worker.opContext.diagnostics());
     } else {
       let t = 0;
       let o = 0;
@@ -1567,7 +2220,8 @@ class ValueSetExpander {
         const c = list[i];
         if (this.map.has(this.keyC(c))) {
           o++;
-          if ((vsInfo.csDoOffset) || (o > this.offset && (this.count < 0 || t < this.count))) {
+          // (the provider paged it, or the walk passed the codes before the page: all that's here is the page)
+          if ((vsInfo.csDoOffset) || (o > (this.paging ? 0 : this.offset) && (this.count < 0 || t < this.count))) {
             t++;
             if (!exp.contains) {
               exp.contains = [];
@@ -1591,6 +2245,10 @@ class ValueSetExpander {
       }
     }
 
+    // declare only the properties the returned codes use: codes outside the page (or a count=0
+    // expansion) declared theirs as they were added, and a declaration nothing uses is noise
+    this.#pruneUnusedPropertyDeclarations(exp);
+
     if (result.expansion.contains && result.expansion.contains.length > 0) {
       let hasChildren = false;
       for (let c of result.expansion.contains) {
@@ -1729,11 +2387,31 @@ class ValueSetExpander {
   }
 
 
+  #pruneUnusedPropertyDeclarations(exp) {
+    if (!exp.property || exp.property.length === 0) {
+      return;
+    }
+    const used = new Set();
+    const walk = (list) => {
+      for (const c of list || []) {
+        for (const p of c.property || []) {
+          used.add(p.code);
+        }
+        walk(c.contains);
+      }
+    };
+    walk(exp.contains);
+    exp.property = exp.property.filter(pd => used.has(pd.code));
+    if (exp.property.length === 0) {
+      delete exp.property;
+    }
+  }
+
   hasParam(exp, name, value) {
     return (exp.parameter || []).find((ex => ex.name == name && getValuePrimitive(ex) == value));
   }
 
-  isExcluded(system, version, code) {
+  async isExcluded(system, version, code) {
     if (this.excludedSystems.has(system)) {
       return true;
     }
@@ -1742,7 +2420,27 @@ class ValueSetExpander {
       return true;
     }
     key = (this.doingVersion && !this.params.versionsMatch ? system+'|'+version : system)+'#'+code;
-    return this.excluded.has(key);
+    if (this.excluded.has(key)) {
+      return true;
+    }
+    for (const ep of this.excludedProviders) {
+      if (ep.system === system && await this.#knownTo(ep.cs, code)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * @returns {Promise<boolean>} whether the code exists in that provider's code system (version)
+   */
+  async #knownTo(cs, code) {
+    try {
+      const loc = await cs.locate(code);
+      return !!(loc && loc.context);
+    } catch (e) {
+      return false;
+    }
   }
 
   keyS(system, version, code) {
@@ -1848,14 +2546,106 @@ class ValueSetExpander {
 
   /**
    * True when the requested page (offset + count) has been filled, so an
-   * iteration that is not counting a total can stop. Exclusions are handled
-   * after the fact and can remove codes already collected, so a value set
-   * with any exclusion never stops early.
+   * iteration that is not counting a total can stop. (Exclusions are processed
+   * before any include, so they never remove a code already collected.)
    * @returns {boolean}
    */
   pageFilled() {
-    return this.count > 0 && this.offset > -1 && !this.hasExclusions
-        && this.fullList.length >= this.count + this.offset;
+    return this.count > 0 && this.offset > -1
+        && this.walked + this.fullList.length >= this.count + this.offset;
+  }
+
+  /**
+   * Whether the next code added falls outside the page asked for (offset, count) on an expansion
+   * that builds every code it includes - one with an exclude, or a text filter, which don't walk
+   * past the codes before the page (see handleCompose): it is counted and kept for deduplication,
+   * but never returned, so there's no point reading its displays, definition and properties.
+   * Excludes don't move a code once it is added: every exclude is processed before the includes,
+   * and includeCode refuses an excluded code before adding it. Not when paging (the walk counts
+   * the codes outside the page without adding them), nor when the provider paged the compose
+   * (every code it returns is on the page)
+   * @returns {boolean}
+   */
+  #outsidePage() {
+    if (this.paging || this.providerPaged || !(this.offset > 0 || this.count > -1)) {
+      return false;
+    }
+    const start = Math.max(this.offset, 0);
+    const i = this.fullList.length;
+    return i < start || (this.count > -1 && i >= start + this.count);
+  }
+
+  /**
+   * Whether this code's details are left to be read later (deferDetails). Not when a supplement
+   * that applies to every value set (a global one, such as a language pack) has the code: that
+   * supplement is reported as used (used-supplement) only when it gives the code's display or a
+   * designation, and this expansion's parameters are made before the importing expansion reads the
+   * details. (A supplement the value set names is reported for every code, read or not)
+   * @param {string} [code] - the code; without one, whether no global supplement could have it
+   */
+  #defers(cs, code = null) {
+    if (!this.deferDetails || this.noDetails || cs == null) {
+      return false;
+    }
+    if (cs.listSupplements(true).length === cs.listSupplements(false).length) {
+      return true;
+    }
+    return code != null && Array.isArray(cs.supplements)
+      && !cs.supplements.some(sp => sp.isGlobalSupplement() && sp.getConceptByCode(code));
+  }
+
+  /**
+   * A concept's details, read as includeCode's callers read them: displays and designations from
+   * the provider, then those the value set lists for the code (cc, an include's concept), and the
+   * concept's status, definition, extensions and properties
+   */
+  async #readDetails(cs, context, cc = null, vsSrc = null) {
+    const displays = new Designations(this.worker.i18n.languageDefinitions);
+    await this.listDisplaysFromProvider(displays, cs, context);
+    if (cc) {
+      this.listDisplaysFromIncludeConcept(displays, cc, vsSrc);
+    }
+    return {
+      displays, deprecated: await cs.isDeprecated(context), status: await cs.getStatus(context), definition: await cs.definition(context),
+      csExtList: await cs.extensions(context), vsExtList: cc ? cc.extension : null, csProps: await this.#conceptProperties(cs, context)
+    };
+  }
+
+  /**
+   * An imported code that this expansion returns: if its details were left to be read
+   * (deferDetails), read and add them now - by the expander that added the code, into its own
+   * expansion, as it would have when it added it. Its property declarations are then on that
+   * expansion, which is added to sources (see importValueSet)
+   */
+  async #buildDeferred(n, sources) {
+    const d = DEFERRED_DETAILS.get(n);
+    if (!d) {
+      return;
+    }
+    DEFERRED_DETAILS.delete(n);
+    const r = await d.read();
+    d.expander.#addDetails(n, d.cs, n.code, r.status, r.deprecated, r.displays, r.definition, d.expansion, r.csExtList, r.vsExtList, r.csProps);
+    sources.add(d.expansion);
+  }
+
+  /**
+   * Whether a value set this expansion imports, for its codes, can be expanded leaving their
+   * details to be read later (deferDetails): when this expansion returns only some of them - a
+   * page, a count, or none at all (count=0) - or is itself expanded so. Not when the expansion is
+   * sorted by display or property, which needs every code's details; nor for a $compare
+   * (noDetails), which takes the imported codes as they come
+   */
+  #importDefers() {
+    return !this.noDetails && !this.#sortsByDetails()
+      && (this.deferDetails || this.paging || this.count > -1 || this.offset > 0);
+  }
+
+  /**
+   * Whether the expansion is sorted by something read with a code's details (its display, a property)
+   */
+  #sortsByDetails() {
+    const sort = (this.params.sort || '').replace(/^-/, '');
+    return sort === 'display' || sort.startsWith('prop:');
   }
 
   addToTotal(t = 1) {
@@ -1877,11 +2667,81 @@ class ValueSetExpander {
     this.totalStatus = 'off';
   }
 
+  /**
+   * The codes an include that lists them would add to the expansion, without building them:
+   * the same checks, in the same order, as the concept loop and includeCode make (located,
+   * active if asked, imports, exclusions, the code system's own cap on how many codes it
+   * contributes, not already in the expansion). Nothing is changed - the cap's counter is
+   * simulated - so the include can still be walked afterwards
+   * @returns {Promise<Set<string>>} the keys (see keyS) of the codes that would be added
+   */
+  async #countListedCodes(cs, cset, valueSets, filters, prep, excludeInactive) {
+    const keys = new Set();
+    const expandLimit = cs.expandLimitation();
+    let capCount = expandLimit > 0 && this.csCounter.has(cs.system()) ? this.csCounter.get(cs.system()).count : 0;
+    // each listed code is located next: a provider may read them together, and hand back what it
+    // read; counting builds nothing, so designations aren't wanted
+    const prefetched = await cs.prefetchCodes(cset.concept.map(cc => cc.code), false);
+    for (const cc of cset.concept) {
+      await this.worker.checkAndYield('countListedCodes');
+      const cctxt = await cs.locate(cc.code, prefetched);
+      if (!cctxt || !cctxt.context) {
+        continue;
+      }
+      const inactive = await cs.isInactive(cctxt.context);
+      if ((this.params.activeOnly && inactive) || !(await this.passesFilters(cs, cctxt.context, prep, filters, 0))) {
+        continue;
+      }
+      const code = await cs.expansionCode(cctxt.context, cc.code);
+      if (!this.passesImports(valueSets, cs.system(), code, 0) || (inactive && excludeInactive)
+          || await this.isExcluded(cs.system(), cs.version(), code)) {
+        continue;
+      }
+      if (expandLimit > 0 && ++capCount > expandLimit) {
+        continue;
+      }
+      const key = this.keyS(cs.system(), cs.version(), code);
+      if (!this.map.has(key) && !this.countedKeys.has(key) && !this.walkedKeys.has(key)) {
+        keys.add(key);
+      }
+    }
+    return keys;
+  }
+
+  /**
+   * Whether adding this many codes would end in VALUESET_TOO_COSTLY in includeCode: over the
+   * limit, and not a page that the limit leaves room for
+   */
+  #listedCodesOverLimit(n) {
+    // (limitCount is only set by expand(): an expander used for something else - $related - has no limit)
+    if (!(this.limitCount > 0) || this.fullList.length + n <= this.limitCount) {
+      return false;
+    }
+    return !this.#pageFits();
+  }
+
+  /**
+   * The properties of a concept that this expansion might report: providers that compute their
+   * properties (from a database, from a lookup) are told which ones are wanted - the requested
+   * names, and those the code system always reports - so that an expansion that asks for none
+   * does not compute any
+   */
+  async #conceptProperties(cs, context) {
+    const names = [...this.params.properties];
+    for (const pn of cs.mandatoryExpansionProperties()) {
+      if (!names.includes(pn)) {
+        names.push(pn);
+      }
+    }
+    return await cs.properties(context, names);
+  }
+
   getPropUrl(cs, pn, cp) {
     if (cp.definition?.uri) {
       return cp.definition.uri;
     }
-    for (let p of cs.propertyDefinitions()) {
+    // a provider need not declare its properties (propertyDefinitions() is null by default)
+    for (let p of cs.propertyDefinitions() || []) {
       if (pn == p.code) {
         return p.uri;
       }
@@ -1913,13 +2773,20 @@ class ValueSetExpander {
     }
     if (simple && result.csset.size == 1) {
       result.isSimple = true;
+      const first = (compose.include || [])[0] || (compose.exclude || [])[0];
+      if (first) {
+        result.system = first.system;
+        result.version = first.version;
+      }
     }
     return result;
   }
 
   isSimpleSelect(inc, set) {
     set.add(inc.system+"|"+inc.version);
-    return !inc.valueset || inc.valueset.length == 0;
+    // (the element is valueSet: the lowercase spelling never matched, which was harmless only
+    // while processCodes did nothing)
+    return !!inc.system && (!inc.valueSet || inc.valueSet.length == 0);
   }
 
   excludeFilterList(exc) {
@@ -1992,6 +2859,8 @@ class ValueSetExpander {
 class ExpandWorker extends TerminologyWorker {
   internalLimit = INTERNAL_DEFAULT_LIMIT;
   externalLimit = EXTERNAL_DEFAULT_LIMIT;
+  // how far a paged expansion may walk to reach its page (null: WALK_LIMIT_FACTOR x internalLimit)
+  walkLimit = null;
 
 
   /**
@@ -2000,12 +2869,17 @@ class ExpandWorker extends TerminologyWorker {
    * @param {Provider} provider - Provider for code systems and resources
    * @param {LanguageDefinitions} languages - Language definitions
    * @param {I18nSupport} i18n - Internationalization support
+   * @param {number} [internalLimit] - the most codes an expansion builds
+   * @param {number} [externalLimit] - the most codes a response holds
+   * @param {number} [walkLimit] - the furthest a paged expansion walks to reach its page (offset +
+   *   count); by default WALK_LIMIT_FACTOR x internalLimit
    */
   constructor(opContext, log, provider, languages,
-              i18n, internalLimit = INTERNAL_DEFAULT_LIMIT, externalLimit = EXTERNAL_DEFAULT_LIMIT) {
+              i18n, internalLimit = INTERNAL_DEFAULT_LIMIT, externalLimit = EXTERNAL_DEFAULT_LIMIT, walkLimit = null) {
     super(opContext, log, provider, languages, i18n);
     this.externalLimit = externalLimit;
     this.internalLimit = internalLimit;
+    this.walkLimit = walkLimit;
   }
 
   /**
@@ -2110,6 +2984,9 @@ class ExpandWorker extends TerminologyWorker {
 
     let txp = new TxParameters(this.opContext.i18n.languageDefinitions, this.opContext.i18n, false);
     txp.readParams(params);
+    // set now, not only in performExpansion: finding the value set by url can depend on them
+    // (an implicit value set is drawn from the code system version the request asks for)
+    this.params = txp;
 
     // If no valueSet yet, try to find by url
     if (!valueSet) {
@@ -2174,6 +3051,9 @@ class ExpandWorker extends TerminologyWorker {
 
     let txp = new TxParameters(this.opContext.i18n.languageDefinitions, this.opContext.i18n, false);
     txp.readParams(params);
+    // set now, not only in performExpansion: finding the value set by url can depend on them
+    // (an implicit value set is drawn from the code system version the request asks for)
+    this.params = txp;
 
     // Perform the expansion
     return await this.doExpand(valueSet, txp, logExtraOutput);
@@ -2222,6 +3102,9 @@ class ExpandWorker extends TerminologyWorker {
 
     let txp = new TxParameters(this.opContext.i18n.languageDefinitions, this.opContext.i18n, false);
     txp.readParams(params);
+    // set now, not only in performExpansion: finding the value set by url can depend on them
+    // (an implicit value set is drawn from the code system version the request asks for)
+    this.params = txp;
 
     // Perform the expansion
     const result = await this.doExpand(valueSet, txp, logExtraOutput);
@@ -2247,7 +3130,9 @@ class ExpandWorker extends TerminologyWorker {
     // Compute cache key (only if caching is available and not debugging)
     let cacheKey = null;
     if (expansionCache && (CACHE_WHEN_DEBUGGING || !this.opContext.debugging)) {
-      cacheKey = expansionCache.computeKey(valueSet, params, this.additionalResources);
+      // (the response limit is in the key: a request with a lower x-too-costly-threshold mustn't
+      // be answered with an expansion made under a higher one)
+      cacheKey = expansionCache.computeKey(valueSet, params, this.additionalResources, this.externalLimit);
 
       // Check for cached expansion
       const cached = expansionCache.get(cacheKey);
@@ -2330,9 +3215,8 @@ module.exports = {
   ImportedValueSet,
   ValueSetFilterContext,
   EmptyFilterContext,
-  EXTERNAL_DEFAULT_LIMIT,
   INTERNAL_DEFAULT_LIMIT,
-  EXTERNAL_TEST_DEFAULT_LIMIT,
-  TotalStatus,
-  EXPANSION_DEAD_TIME_SECS
+  WALK_LIMIT_FACTOR,
+  EXTERNAL_DEFAULT_LIMIT,
+  TotalStatus
 };