fhirsmith 0.11.0 → 0.11.2

package/CHANGELOG.md

@@ -5,6 +5,55 @@ All notable changes to the Health Intersections Node Server will be documented i
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.11.2 - 2026-08-12
+
+### Fixed
+
+- Update snomed test content
+
+### Fixed
+
+- Fix snomed designation handling for languages
+- Fix for SSEF protection in the validator- 
+
+### Tx Conformance Statement
+
+FHIRsmith passed all 2729 HL7 terminology service tests (modes tx.fhir.org+omop+general+snomed, tests v1.9.3, runner v6.10.1)
+
+## [0.11.1] - 2026-07-30
+
+### Added
+
+- Cooperative yielding for long terminology operations: after every 25ms of continuous compute the
+  operation yields the event loop (`checkAndYield`), so a heavy $expand can no longer stall every
+  other request on the server. Operations whose client has disconnected are aborted at their next
+  yield point instead of computing a response nobody will read
+- The operation time limit is now configurable (`operationTimeLimit`, seconds) and defaults to 20s
+  (below common client timeouts, so clients see the too-costly OperationOutcome rather than a
+  socket timeout), and is measured against compute time consumed rather than wall-clock, so
+  concurrent operations time-sharing the event loop don't abort each other
+- The Node Blocking chart on the status page now shows the worst single event-loop stall per
+  window as well as the mean
+
+### Fixed
+
+- fix whole-code-system SNOMED CT expansions blocking the server for 30 seconds and then failing:
+  the hierarchy walk read a non-existent `.code` property, so every concept was treated as a
+  duplicate of the first and no expansion size guard could ever stop the walk. This is what caused
+  the rash of client timeouts on tx.fhir.org after the 0.11.0 upgrade
+- the hierarchy walk now visits each concept once rather than once per path to it (SNOMED CT is a
+  poly-hierarchy: the old walk made ~15.8M visits for ~520k concepts)
+- restore the up-front too-costly refusal for expansions that cannot fit the expansion limit (the
+  totalCount size guard was silently dead - method read as a property); expansions with a
+  count/offset window inside the limit still succeed as partial, unclosed expansions
+- re-enable the CPT 1000-code expansion cap (same method-read-as-property bug)
+- fix parameter misalignment in the no-details expansion path (19 arguments passed to a
+  20-parameter function)
+
+### Tx Conformance Statement
+
+FHIRsmith passed all 2729 HL7 terminology service tests (modes tx.fhir.org+omop+general+snomed, tests v1.9.2, runner v6.9.12)
+
 ## [0.11.0] - 2026-mm-dd
 
 ### Added

package/library/folder-content-loader.js

@@ -2,6 +2,8 @@ const fs = require('fs').promises;
 const path = require('path');
 const { PackageContentLoader } = require('./package-manager');
 
+const TERMINOLOGY_TYPES = ['CodeSystem', 'ValueSet', 'ConceptMap'];
+
 /**
  * A content loader that scans a folder for JSON FHIR terminology resources
  * (CodeSystem, ValueSet, ConceptMap). It synthesizes the package layout that
@@ -26,14 +28,27 @@ class FolderContentLoader extends PackageContentLoader {
   }
 
   /**
-   * Replaces the standard initialize: there is no package.json or .index.json
-   * to read, so we synthesize an index from the JSON files in the folder.
+   * The synthesized package name reported by id()/pid().
+   * @returns {string}
    */
-  async initialize() {
-    if (this.loaded) {
-      return;
-    }
+  _packageName() {
+    return 'folder.' + path.basename(this.sourceFolder);
+  }
+
+  /**
+   * Whether a file that can't be parsed, or that isn't a terminology resource,
+   * should be quietly skipped. True for folder scans (the folder may hold all
+   * sorts of things); false when a specific file was nominated.
+   * @returns {boolean}
+   */
+  get _skipInvalidFiles() {
+    return true;
+  }
 
+  /**
+   * Check the source exists and is the right kind of thing.
+   */
+  async _validateSource() {
     try {
       const stat = await fs.stat(this.sourceFolder);
       if (!stat.isDirectory()) {
@@ -45,36 +60,63 @@ class FolderContentLoader extends PackageContentLoader {
       }
       throw err;
     }
+  }
+
+  /**
+   * The file names (relative to sourceFolder) to consider.
+   * @returns {Promise<Array<string>>}
+   */
+  async _candidateFiles() {
+    const names = [];
+    const entries = await fs.readdir(this.sourceFolder, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isFile()) continue;
+      if (!entry.name.toLowerCase().endsWith('.json')) continue;
+      names.push(entry.name);
+    }
+    return names;
+  }
+
+  /**
+   * Replaces the standard initialize: there is no package.json or .index.json
+   * to read, so we synthesize an index from the JSON files in the source.
+   */
+  async initialize() {
+    if (this.loaded) {
+      return;
+    }
+
+    await this._validateSource();
 
     // Synthesize package metadata so id()/version()/pid() return something usable.
     this.package = {
-      name: 'folder.' + path.basename(this.sourceFolder),
+      name: this._packageName(),
       version: '0.0.0',
       fhirVersions: ['5.0.0']
     };
 
     const files = [];
-    const entries = await fs.readdir(this.sourceFolder, { withFileTypes: true });
-    for (const entry of entries) {
-      if (!entry.isFile()) continue;
-      if (!entry.name.toLowerCase().endsWith('.json')) continue;
-
-      const fullPath = path.join(this.sourceFolder, entry.name);
+    for (const name of await this._candidateFiles()) {
+      const fullPath = path.join(this.sourceFolder, name);
       let json;
       try {
         const content = await fs.readFile(fullPath, 'utf8');
         json = JSON.parse(content);
-      } catch {
-        // Skip unreadable / non-JSON files rather than failing the whole load.
-        continue;
+      } catch (e) {
+        // Skip unreadable / non-JSON files rather than failing the whole load,
+        // unless this exact file was the nominated source.
+        if (this._skipInvalidFiles) continue;
+        throw new Error(`Unable to read FHIR resource from ${fullPath}: ${e.message}`);
       }
 
-      if (!json || typeof json !== 'object') continue;
-      const rt = json.resourceType;
-      if (rt !== 'CodeSystem' && rt !== 'ValueSet' && rt !== 'ConceptMap') continue;
+      const rt = json && typeof json === 'object' ? json.resourceType : null;
+      if (!TERMINOLOGY_TYPES.includes(rt)) {
+        if (this._skipInvalidFiles) continue;
+        throw new Error(`${fullPath} is not a CodeSystem, ValueSet or ConceptMap (resourceType = ${rt || 'none'})`);
+      }
 
       files.push({
-        filename: entry.name,
+        filename: name,
         resourceType: rt,
         id: json.id,
         url: json.url,
@@ -88,4 +130,52 @@ class FolderContentLoader extends PackageContentLoader {
   }
 }
 
-module.exports = { FolderContentLoader };
+/**
+ * A content loader for a single nominated JSON file holding one CodeSystem,
+ * ValueSet or ConceptMap. Everything else works exactly as for a folder source:
+ * the file's own directory is the read-only content root, and the provider
+ * caches live in the supplied cacheFolder.
+ *
+ * Unlike a folder scan, a bad file is an error rather than something to skip -
+ * the config named this file explicitly, so failing silently would just hide
+ * a typo.
+ */
+class FileContentLoader extends FolderContentLoader {
+  /**
+   * @param {string} filePath - The JSON file to load
+   * @param {string} cacheFolder - Folder where Package*Provider DBs may live
+   */
+  constructor(filePath, cacheFolder) {
+    super(path.dirname(filePath), cacheFolder);
+    this.filePath = filePath;
+    this.fileName = path.basename(filePath);
+  }
+
+  _packageName() {
+    return 'file.' + this.fileName.replace(/\.json$/i, '');
+  }
+
+  get _skipInvalidFiles() {
+    return false;
+  }
+
+  async _validateSource() {
+    try {
+      const stat = await fs.stat(this.filePath);
+      if (!stat.isFile()) {
+        throw new Error(`File source path is not a file: ${this.filePath}`);
+      }
+    } catch (err) {
+      if (err.code === 'ENOENT') {
+        throw new Error(`File source path does not exist: ${this.filePath}`);
+      }
+      throw err;
+    }
+  }
+
+  async _candidateFiles() {
+    return [this.fileName];
+  }
+}
+
+module.exports = { FolderContentLoader, FileContentLoader };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fhirsmith",
-  "version": "0.11.0",
-  "txVersion": "1.9.1",
+  "version": "0.11.2",
+  "txVersion": "1.9.3",
   "description": "A Node.js server that provides a collection of tools to serve the FHIR ecosystem",
   "main": "server.js",
   "engines": {
@@ -46,7 +46,7 @@
     "express-rate-limit": "^7.4.1",
     "express-session": "^1.19.0",
     "fast-xml-parser": "^5.3.4",
-    "fhir-validator-wrapper": "1.2.2",
+    "fhir-validator-wrapper": "1.3.0",
     "fhirpath": "^4.8.3",
     "fs-extra": "^11.3.3",
     "ini": "^6.0.0",

package/stats.js

@@ -37,6 +37,10 @@ class ServerStats {
       const requestsPerMin = minutesSinceStart > 0 ? requestsDelta / minutesSinceStart : 0;
 
       const loopDelay = this.eventLoopMonitor.mean / 1e6;
+      // Worst single stall in the window - the mean dilutes a multi-second
+      // event-loop block into noise; the max is what shows request-freezing
+      // stalls (see the 2026-07-30 tx.fhir.org incident).
+      const loopMax = this.eventLoopMonitor.max / 1e6;
       // Two distinct caches: the expansion cache (count entries) and the client
       // (resource) cache (count concepts held - a sense of how much it's carrying).
       let expansionItems = 0;
@@ -50,7 +54,7 @@ class ServerStats {
         }
       }
 
-      this.history.push({time: now, mem: currentMem - this.startMem, rpm: requestsPerMin, tat: requestsTat, block: loopDelay, expansion: expansionItems, clientConcepts: clientConcepts});
+      this.history.push({time: now, mem: currentMem - this.startMem, rpm: requestsPerMin, tat: requestsTat, block: loopDelay, blockMax: loopMax, expansion: expansionItems, clientConcepts: clientConcepts});
 
       this.eventLoopMonitor.reset();
       this.requestCountSnapshot = combinedCount;

package/tx/cs/cs-api.js

@@ -404,9 +404,15 @@ class CodeSystemProvider {
    * @param {boolean} [significantOnly=false] - when true, emit only the
    *   designations that are significant for a value set expansion (the display,
    *   and - for code systems that distinguish them - the fully specified name
-   *   and the preferred term), rather than every designation in every language.
-   *   The $expand worker passes true; $lookup uses the default (false) to return
-   *   the complete set. Providers that do not distinguish significant
+   *   and the preferred term), rather than every designation. This narrows which
+   *   designations are emitted, NOT which languages: the display for a request is
+   *   chosen downstream by preferredDesignation(displayLanguage), so a provider
+   *   that emits significant designations for one language only makes localized
+   *   expansions fall back to that language. Emit the significant designations
+   *   for every language the concept has.
+   *   The $expand worker passes true when the client did not ask for
+   *   designations; $lookup and includeDesignations=true use the default (false)
+   *   to return the complete set. Providers that do not distinguish significant
    *   designations may ignore this parameter and return all designations either
    *   way.
    * @returns {Designation[]} whatever designations exist (in all languages)

package/tx/cs/cs-snomed.js

@@ -1605,13 +1605,25 @@ class SnomedProvider extends BaseCSServices {
             const K = this.sct._displayConstants();
 
             if (significantOnly) {
-              // $expand: emit the "significant" designations only — the FSN plus
-              // the preferred synonym (US English), active descriptions only.
-              // The preferred synonym is also the display, so it is added as the
-              // display designation (which the expand worker selects for
-              // `display` and skips from the emitted list) and additionally as a
-              // Synonym designation so it still appears in the designation array.
-              let fsn = null, prefSyn = null;
+              // $expand: emit the "significant" designations only — the FSN and
+              // the preferred synonym, active descriptions only. Acceptable
+              // synonyms are the bulk of a SNOMED concept's descriptions and are
+              // not needed to render an expansion, so they are dropped.
+              //
+              // One per LANGUAGE, though, not one overall: the display for a
+              // request is chosen downstream by
+              // Designations.preferredDesignation(displayLanguage), so a concept
+              // that emits only its English terms has nothing for a
+              // displayLanguage=de request to match and silently falls back to
+              // English. Keeping the preferred synonym in every language the
+              // concept has is what makes localized expansions work at all
+              // (e.g. the Swiss edition, whose German terms are preferred in the
+              // Swiss German language refset 2041000195100).
+              //
+              // The edition-default display is also added as the display
+              // designation (which the expand worker selects for `display` when
+              // no language was asked for, and skips from the emitted list).
+              const fsns = new Map(), prefSyns = new Map();
               for (const descIndex of descriptionIndices) {
                 const description = this.sct.descriptions.getDescription(descIndex);
                 if (!description.active) continue;
@@ -1620,15 +1632,20 @@ class SnomedProvider extends BaseCSServices {
                 const kind = this.sct.concepts.getConcept(description.kind);
                 const use = { system: 'http://snomed.info/sct', code: String(kind.identity), display: this.sct.getDisplayName(description.kind) };
                 if (description.kind === K.fsn) {
-                  if (!fsn) fsn = { langCode, use, term };
+                  if (!fsns.has(langCode)) fsns.set(langCode, { langCode, use, term });
                 } else if (this.sct._synonymIsPreferred(description)) {
-                  if (!prefSyn) prefSyn = { langCode, use, term };
+                  if (!prefSyns.has(langCode)) prefSyns.set(langCode, { langCode, use, term });
                 }
               }
               const display = this.sct.getDisplayName(ctxt.getReference());
               if (display) displays.addDesignation(true, 'active', 'en-US', null, display);
-              if (fsn) displays.addDesignation(false, 'active', fsn.langCode, fsn.use, fsn.term);
-              if (prefSyn) displays.addDesignation(false, 'active', prefSyn.langCode, prefSyn.use, prefSyn.term);
+              // FSNs before synonyms, matching the designation order the published
+              // tx-ecosystem expectations were written against (sct/expand-inactive).
+              // Which of the two is chosen as the display is settled by
+              // Designations.preferredDesignation(), which ranks the SNOMED synonym
+              // above the FSN - not by the order they are emitted in.
+              for (const d of fsns.values()) displays.addDesignation(false, 'active', d.langCode, d.use, d.term);
+              for (const d of prefSyns.values()) displays.addDesignation(false, 'active', d.langCode, d.use, d.term);
             } else {
               // $lookup: emit every description (preferred synonym first so the
               // display resolves correctly; order is not otherwise significant).

package/tx/html/home-metrics.liquid

@@ -221,23 +221,38 @@
     data: {
       labels: historyData.map(d => formatTime(d.time)),
       datasets: [{
+        label: 'mean',
         data: historyData.map(d => d.block),
         borderColor: '#2845a7',
         backgroundColor: 'rgba(40, 69, 167, 0.1)',
         fill: true,
         tension: 0.3,
         pointRadius: 2
+      }, {
+        // Worst single event-loop stall in the window: the mean dilutes a
+        // multi-second block into noise, so this is the line that shows
+        // request-freezing stalls.
+        label: 'max',
+        data: historyData.map(d => d.blockMax),
+        borderColor: '#a72828',
+        fill: false,
+        tension: 0.3,
+        pointRadius: 2
       }]
     },
     options: {
       ...chartOptions,
+      plugins: {
+        ...chartOptions.plugins,
+        legend: { display: true }
+      },
       scales: {
         ...chartOptions.scales,
         y: {
           ...chartOptions.scales.y,
           title: {
             display: true,
-            text: 'points'
+            text: 'ms'
           }
         }
       }

package/tx/library/designations.js

@@ -610,8 +610,15 @@ class Designations {
 
       for (const activeOnly of [true, false]) {
         for (const matchType of matchTypes) {
+          // _isPreferred before isDisplay, matching the no-language branch above.
+          // The two sets differ only where a provider's own isDisplay() accepts a
+          // designation that isn't a preferred term - today that is the SNOMED FSN,
+          // which isDisplay() accepts and _isPreferred() deliberately does not. Testing
+          // isDisplay first made a request for a language whose concept has both an FSN
+          // and a preferred synonym display the "(disorder)"-suffixed FSN, purely
+          // because the FSN was emitted first.
           for (const cd of this.designations) {
-            if (this._langMatches(lang, cd.language, matchType) && this.isDisplay(cd) && (!activeOnly || cd.isActive())) {
+            if (this._langMatches(lang, cd.language, matchType) && this._isPreferred(cd) && (!activeOnly || cd.isActive())) {
               if (supplements && cd.source) {
                 supplements.add(cd.source);
               }
@@ -619,7 +626,7 @@ class Designations {
             }
           }
           for (const cd of this.designations) {
-            if (this._langMatches(lang, cd.language, matchType) && this._isPreferred(cd)&& (!activeOnly || cd.isActive())) {
+            if (this._langMatches(lang, cd.language, matchType) && this.isDisplay(cd) && (!activeOnly || cd.isActive())) {
               if (supplements && cd.source) {
                 supplements.add(cd.source);
               }

package/tx/library.js

@@ -3,7 +3,7 @@ const path = require('path');
 const crypto = require('crypto');
 const yaml = require('yaml'); // npm install yaml
 const { PackageManager, PackageContentLoader } = require('../library/package-manager');
-const { FolderContentLoader } = require('../library/folder-content-loader');
+const { FolderContentLoader, FileContentLoader } = require('../library/folder-content-loader');
 const { CodeSystem } = require("./library/codesystem");
 const {CountryCodeFactoryProvider} = require("./cs/cs-country");
 const {Iso4217FactoryProvider} = require("./cs/cs-currency");
@@ -301,6 +301,10 @@ class Library {
         await this.loadFolder(details, isDefault, mode);
         break;
 
+      case 'file':
+        await this.loadFile(details, isDefault, mode);
+        break;
+
       default:
         throw new Error(`Unknown source type: ${type}`);
     }
@@ -679,19 +683,68 @@ class Library {
       return;
     }
 
-    const folderPath = path.isAbsolute(details)
-      ? details
-      : path.resolve(path.join(__dirname, '..', details));
+    const folderPath = this.#resolveLocalSourcePath(details);
+    const cacheSubdir = await this.#prepareLocalSourceCache(folderPath);
+    await this.#loadLocalSource(new FolderContentLoader(folderPath, cacheSubdir));
+  }
+
+  /**
+   * Loads a single nominated JSON file holding a CodeSystem, ValueSet or ConceptMap
+   * (source syntax: `file:<path>`). The resource is routed to the appropriate provider
+   * based on its resourceType.
+   *
+   * Unlike a folder source, the file must exist and must be one of the three terminology
+   * resource types - anything else is an error, since the config named it explicitly.
+   *
+   * Relative paths are resolved against the project root (same convention as loadUcum etc.).
+   *
+   * @param {string} details - The file to load
+   * @param {boolean} isDefault - Unused; file sources don't register factories
+   * @param {string} mode - One of "fetch", "cs", "npm"
+   */
+  // eslint-disable-next-line no-unused-vars
+  async loadFile(details, isDefault, mode) {
+    if (mode === "fetch" || mode === "cs") {
+      return;
+    }
+
+    const filePath = this.#resolveLocalSourcePath(details);
+    const cacheSubdir = await this.#prepareLocalSourceCache(filePath);
+    await this.#loadLocalSource(new FileContentLoader(filePath, cacheSubdir));
+  }
+
+  /**
+   * Relative paths in folder:/file: sources are resolved against the project root.
+   * @private
+   */
+  #resolveLocalSourcePath(details) {
+    const text = String(details || '').trim();
+    if (!text) {
+      throw new Error('A local source requires a path, e.g. file:tx/data/my-valueset.json');
+    }
+    return path.isAbsolute(text) ? text : path.resolve(path.join(__dirname, '..', text));
+  }
 
-    // Park the Package*Provider SQLite caches under the terminology cache rather
-    // than polluting the user's source folder, and wipe between runs so edits to
-    // the source folder are reliably picked up.
-    const hash = crypto.createHash('sha1').update(folderPath).digest('hex').substring(0, 16);
+  /**
+   * Parks the Package*Provider SQLite caches under the terminology cache rather
+   * than polluting the user's source folder, and wipes between runs so edits to
+   * the source are reliably picked up.
+   * @private
+   */
+  async #prepareLocalSourceCache(sourcePath) {
+    const hash = crypto.createHash('sha1').update(sourcePath).digest('hex').substring(0, 16);
     const cacheSubdir = path.join(this.cacheFolder, 'folder-source-' + hash);
     await fs.rm(cacheSubdir, { recursive: true, force: true });
     await fs.mkdir(cacheSubdir, { recursive: true });
+    return cacheSubdir;
+  }
 
-    const contentLoader = new FolderContentLoader(folderPath, cacheSubdir);
+  /**
+   * Shared loader for folder- and file-sourced content: registers the loader's
+   * CodeSystems, ValueSets and ConceptMaps with this library.
+   * @private
+   */
+  async #loadLocalSource(contentLoader) {
     await contentLoader.initialize();
 
     this.packageSources.push(contentLoader.id() + "#" + contentLoader.version());

package/tx/operation-context.js

@@ -556,6 +556,15 @@ const MEMORY_LIMIT = readMemoryLimit();
 const MEMORY_FRACTION = 0.98;
 const MEMORY_THRESHOLD = MEMORY_LIMIT > 0 ? MEMORY_LIMIT * MEMORY_FRACTION : 0; // 90% of cgroup limit
 const CHECK_FREQUENCY = 100;
+// How long an operation may compute without yielding the event loop (ms).
+// Node runs all JS on one thread: while a long operation executes, no other
+// request is serviced - awaiting in-memory promises does not help, because
+// resolved promises only bounce through the microtask queue, which runs before
+// I/O. checkAndYield() awaits a real setImmediate every YIELD_INTERVAL ms of
+// compute, so pending I/O (new connections, /metadata, timers) runs between
+// slices and one heavy $expand can no longer time out every other client.
+const YIELD_INTERVAL = 25;
+const { setImmediate: yieldToEventLoop } = require('timers/promises');
 
 class OperationContext {
   // Shared counter across all instances — only check RSS every CHECK_FREQUENCY calls
@@ -584,6 +593,24 @@ class OperationContext {
     // Shared by reference with copy()'d contexts so a sub-operation's
     // providers are cleaned up by the parent request's closeProviders().
     this._openProviders = [];
+    // Compute-time accounting for the deadline and for yielding. One object,
+    // shared by reference with copy()'d contexts, so an operation and its
+    // sub-operations (e.g. batch entries) draw down a single budget:
+    //  - compute:    ms of compute consumed in completed slices
+    //  - sliceStart: when the current compute slice began
+    //  - lastYield:  when we last gave the event loop a turn
+    //  - clientGone: set when the client disconnects before the response is sent
+    // The deadline is measured in COMPUTE time, not wall-clock: once operations
+    // time-share the event loop, wall-clock deadlines make concurrency itself
+    // cause aborts (N ops each take N x as long), which turns client retries
+    // into a failure amplifier. An operation that waited is not too costly;
+    // one that consumed its compute budget is.
+    this._clock = {
+      compute: 0,
+      sliceStart: this.startTime,
+      lastYield: this.startTime,
+      clientGone: false
+    };
 
     this.timeTracker.step('tx-op');
   }
@@ -616,6 +643,8 @@ class OperationContext {
     // Share the same provider-cleanup list so providers opened by the copy
     // are released when the parent operation ends.
     newContext._openProviders = this._openProviders;
+    // Share the compute clock: sub-operations spend the parent's budget.
+    newContext._clock = this._clock;
     return newContext;
   }
 
@@ -646,8 +675,10 @@ class OperationContext {
     }
     OperationContext._checkCounter = 0;
 
-    // Time check
-    const elapsed = performance.now() - this.startTime;
+    // Time check - against compute time consumed, not wall clock (see _clock in
+    // the constructor). For operations that never yield the two are identical,
+    // so this changes nothing for paths that don't use checkAndYield().
+    const elapsed = this.computeElapsed();
     if (elapsed > this.timeLimit) {
       const timeInSeconds = Math.round(this.timeLimit / 1000);
       this.log(`Operation took too long @ ${place} (${this.constructor.name})`);
@@ -674,6 +705,64 @@ class OperationContext {
     return false;
   }
 
+  /**
+   * Compute time this operation has consumed (ms): completed slices plus the
+   * slice currently executing. Equals wall-clock elapsed for operations that
+   * never yield.
+   * @returns {number}
+   */
+  computeElapsed() {
+    return this._clock.compute + (performance.now() - this._clock.sliceStart);
+  }
+
+  /**
+   * Mark that the client for this operation disconnected before the response
+   * was sent. The operation is aborted at its next yield point - there is no
+   * one left to send the result to. (Wired up by the request middleware from
+   * the response 'close' event.)
+   */
+  markClientGone() {
+    this._clock.clientGone = true;
+  }
+
+  /**
+   * deadCheck plus cooperative yielding: call this (awaited) from long-running
+   * loops in async code. Runs the normal deadCheck, and after every
+   * YIELD_INTERVAL ms of continuous compute awaits a real setImmediate so the
+   * event loop can service pending I/O - other requests keep getting answered
+   * while this operation works. On resuming from a yield, aborts if the client
+   * has disconnected in the meantime.
+   *
+   * Sync call sites keep using deadCheck(); the async loops that surround them
+   * yield on their behalf, which caps unbroken compute at one loop iteration.
+   *
+   * @param {string} place - Location identifier for debugging
+   */
+  async checkAndYield(place = 'unknown') {
+    this.deadCheck(place);
+    if (this.debugging) {
+      return;
+    }
+    const now = performance.now();
+    if (now - this._clock.lastYield >= YIELD_INTERVAL) {
+      // Close off this compute slice before suspending, so time spent waiting
+      // for our next turn is not charged against the deadline.
+      this._clock.compute += now - this._clock.sliceStart;
+      await yieldToEventLoop();
+      const resumed = performance.now();
+      this._clock.sliceStart = resumed;
+      this._clock.lastYield = resumed;
+      if (this._clock.clientGone) {
+        this.log(`Operation abandoned @ ${place}: client disconnected`);
+        const error = new Issue("error", "too-costly", null,
+            `Operation abandoned at ${place}: the client disconnected before the response was ready`);
+        error.abandoned = true;
+        error.diagnostics = this.diagnostics();
+        throw error;
+      }
+    }
+  }
+
   unSeeAll() {
     this.contexts = [];
   }

package/tx/tx.js

@@ -291,9 +291,15 @@ class TXModule {
       // Get Accept-Language header for language preferences
       const acceptLanguage = req.get('Accept-Language') || 'en';
 
-      // Create operation context with language, ID, time limit, and caches
+      // Create operation context with language, ID, time limit, and caches.
+      // The time limit is a compute-time budget (see OperationContext._clock)
+      // and is configurable (config.operationTimeLimit, seconds). The default
+      // sits deliberately under common client timeouts (okhttp reads give up at
+      // 10-30s): if the server's limit is >= the client's, the client hangs up
+      // first and the carefully-built too-costly OperationOutcome is written to
+      // a socket nobody is reading.
       const opContext = new OperationContext(
-        acceptLanguage, this.i18n, requestId, 30,
+        acceptLanguage, this.i18n, requestId, this.config.operationTimeLimit ?? 20,
         endpointInfo.resourceCache, endpointInfo.expansionCache
       );
       opContext.usageTracker = this.usageTracker;
@@ -325,6 +331,16 @@ class TXModule {
       res.on('finish', releaseProviders);
       res.on('close', releaseProviders);
 
+      // If the connection closes before the response was completed, the client
+      // has given up (timeout, cancelled build, dropped connection). Mark the
+      // operation so it aborts at its next yield point instead of computing a
+      // response nobody will read.
+      res.on('close', () => {
+        if (!res.writableEnded) {
+          opContext.markClientGone();
+        }
+      });
+
       // Add X-Request-Id header to response
       res.setHeader('X-Request-Id', requestId);
 

package/tx/workers/expand.js

@@ -314,14 +314,20 @@ class ValueSetExpander {
       return null;
     }
 
-    if (cs != null && cs.expandLimitation > 0) {
-      let cnt = this.csCounter.get(cs.system);
+    // 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);
+        this.csCounter.set(cs.system(), cnt);
       }
       cnt.increment();
-      if (cnt.count > cs.expandLimitation) {
+      if (cnt.count > expandLimit) {
         return null;
       }
     }
@@ -566,7 +572,7 @@ class ValueSetExpander {
     this.checkResourceCanonicalStatus(expansion, vs, this.valueSet);
 
     for (const c of vs.expansion.contains || []) {
-      this.worker.deadCheck('importValueSet');
+      await this.worker.checkAndYield('importValueSet');
       count += await this.importValueSetItem(null, c, imports, offset);
     }
     return count;
@@ -574,7 +580,7 @@ class ValueSetExpander {
 
   async importValueSetItem(p, c, imports, offset) {
     let count = 0;
-    this.worker.deadCheck('importValueSetItem');
+    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)) {
       count++;
@@ -588,7 +594,7 @@ class ValueSetExpander {
       this.map.set(s, c);
     }
     for (const cc of c.contains || []) {
-      this.worker.deadCheck('importValueSetItem');
+      await this.worker.checkAndYield('importValueSetItem');
       count += await this.importValueSetItem(c, cc, imports, offset);
     }
     return count;
@@ -610,11 +616,11 @@ class ValueSetExpander {
   }
 
   async checkSource(cset, exp, filter, srcURL, ts, vsInfo , source) {
-    this.worker.deadCheck('checkSource');
+    await this.worker.checkAndYield('checkSource');
     Extensions.checkNoModifiers(cset, 'ValueSetExpander.checkSource', 'set', srcURL);
     let imp = false;
     for (const u of cset.valueSet || []) {
-      this.worker.deadCheck('checkSource');
+      await this.worker.checkAndYield('checkSource');
       const s = this.worker.pinValueSet(u);
       await this.checkCanExpandValueSet(s, '', source);
       imp = true;
@@ -663,8 +669,21 @@ class ValueSetExpander {
           } else if (filter.isNull) {
             // The unclosed marking for a grammar code system is added by
             // processCodes (the actual expansion); checkSource only guards size.
-            if (!imp && this.count !== 0 && this.limitCount > 0 && cs.totalCount > this.limitCount) {
-              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());
+            // Refuse up-front only when enumeration could not succeed anyway:
+            // count=0 is answered by counting (no enumeration), and a count/offset
+            // window that fits inside limitCount is answered by partial
+            // enumeration (includeCode stops at limitCount). Otherwise the walk
+            // would only ever end in VALUESET_TOO_COSTLY at limitCount codes -
+            // throw the same error now without doing the work.
+            // 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)) {
+              // 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());
             }
           }
         }
@@ -684,7 +703,7 @@ class ValueSetExpander {
   }
 
   async includeCodes(cset, path, vsSrc, compose, filter, expansion, excludeInactive, notClosed) {
-    this.worker.deadCheck('processCodes#1');
+    await this.worker.checkAndYield('processCodes#1');
     const valueSets = [];
 
     Extensions.checkNoModifiers(cset, 'ValueSetExpander.processCodes', 'set', vsSrc.vurl);
@@ -695,7 +714,7 @@ class ValueSetExpander {
 
     if (!cset.system) {
       for (const u of cset.valueSet) {
-        this.worker.deadCheck('processCodes#2');
+        await this.worker.checkAndYield('processCodes#2');
         const s = this.worker.pinValueSet(u);
         this.worker.opContext.log('import value set ' + s);
         let vs = await this.worker.findValueSet(s, '', vsSrc);
@@ -722,7 +741,7 @@ class ValueSetExpander {
         this.addParamUri(expansion, 'used-codesystem', sv);
 
         for (const u of cset.valueSet || []) {
-          this.worker.deadCheck('processCodes#2');
+          await this.worker.checkAndYield('processCodes#2');
           const s = this.worker.pinValueSet(u);
           this.worker.opContext.log('import value set ' + s);
           let vs = await this.worker.findValueSet(s, '', vsSrc);
@@ -774,11 +793,14 @@ class ValueSetExpander {
 
               }
               let tcount = 0;
+              // One visited set across all roots: in a poly-hierarchy the walks
+              // from different roots can reach the same concepts.
+              const visited = new Set();
               let c = await cs.nextContext(iter);
               while (c) {
-                this.worker.deadCheck('processCodes#3a');
+                await this.worker.checkAndYield('processCodes#3a');
                 if (await this.passesFilters(cs, c, prep, filters, 0)) {
-                  tcount += await this.includeCodeAndDescendants(cs, c, expansion, valueSets, null, excludeInactive, vsSrc.vurl);
+                  tcount += await this.includeCodeAndDescendants(cs, c, expansion, valueSets, null, excludeInactive, vsSrc.vurl, visited);
                 }
                 c = await cs.nextContext(iter);
               }
@@ -800,7 +822,7 @@ class ValueSetExpander {
             this.noTotal();
             this.worker.opContext.log('iterate filters');
             while (await cs.filterMore(ctxt, set[0])) {
-              this.worker.deadCheck('processCodes#4');
+              await this.worker.checkAndYield('processCodes#4');
               const c = await cs.filterConcept(ctxt, set[0]);
               if (await this.passesFilters(cs, c, prep, set, 1)) {
                 const cds = new Designations(this.worker.i18n.languageDefinitions);
@@ -830,7 +852,7 @@ class ValueSetExpander {
           const cds = new Designations(this.worker.i18n.languageDefinitions);
 
           for (const cc of cset.concept) {
-            this.worker.deadCheck('processCodes#3');
+            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);
@@ -875,7 +897,7 @@ class ValueSetExpander {
           }
 
           for (let i = 0; i < fcl.length; i++) {
-            this.worker.deadCheck('processCodes#4a');
+            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);
@@ -895,7 +917,7 @@ class ValueSetExpander {
           this.addToTotal(0);
           const cds = new Designations(this.worker.i18n.languageDefinitions);
           while (await cs.filterMore(prep, fset[0])) {
-            this.worker.deadCheck('processCodes#5');
+            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) {
@@ -944,7 +966,7 @@ class ValueSetExpander {
   }
 
   async excludeCodes(cset, path, vsSrc, filter, expansion, excludeInactive, notClosed) {
-    this.worker.deadCheck('processCodes#1');
+    await this.worker.checkAndYield('processCodes#1');
     const valueSets = [];
 
     Extensions.checkNoModifiers(cset, 'ValueSetExpander.processCodes', 'set', vsSrc.vurl);
@@ -958,7 +980,7 @@ class ValueSetExpander {
         this.noTotal();
         for (const u of cset.valueSet) {
           const s = this.worker.pinValueSet(u);
-          this.worker.deadCheck('processCodes#2');
+          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));
           this.checkResourceCanonicalStatus(expansion, ivs.valueSet, this.valueSet);
@@ -984,7 +1006,7 @@ class ValueSetExpander {
         this.addParamUri(expansion, 'used-codesystem', sv);
 
         for (const u of cset.valueSet || []) {
-          this.worker.deadCheck('processCodes#3');
+          await this.worker.checkAndYield('processCodes#3');
           const s = this.worker.pinValueSet(u);
           this.worker.opContext.log('import value set ' + s);
           let vs = await this.worker.findValueSet(s, '', vsSrc);
@@ -1007,7 +1029,7 @@ class ValueSetExpander {
               if (iter) {
                 let c = await cs.nextContext(iter);
                 while (c) {
-                  this.worker.deadCheck('processCodes#3aa');
+                  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);
                 }
@@ -1031,7 +1053,7 @@ class ValueSetExpander {
             if (iter) {
               let c = await cs.nextContext(iter);
               while (c) {
-                this.worker.deadCheck('processCodes#3a');
+                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);
                 }
@@ -1045,7 +1067,7 @@ class ValueSetExpander {
           this.worker.opContext.log('iterate concepts');
           const cds = new Designations(this.worker.i18n.languageDefinitions);
           for (const cc of cset.concept) {
-            this.worker.deadCheck('processCodes#3');
+            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);
@@ -1076,7 +1098,7 @@ class ValueSetExpander {
 
           let first = true;
           for (let fc of cset.filter) {
-            this.worker.deadCheck('processCodes#4a');
+            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;
@@ -1089,7 +1111,7 @@ class ValueSetExpander {
           }
           //let count = 0;
           while (await cs.filterMore(prep, fset[0])) {
-            this.worker.deadCheck('processCodes#5');
+            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) {
@@ -1105,9 +1127,30 @@ class ValueSetExpander {
     }
   }
 
-  async includeCodeAndDescendants(cs, context, expansion, imports, parent, excludeInactive, srcUrl) {
+  async includeCodeAndDescendants(cs, context, expansion, imports, parent, excludeInactive, srcUrl, visited = null) {
     let result = 0;
-    this.worker.deadCheck('processCodeAndDescendants');
+    await this.worker.checkAndYield('processCodeAndDescendants');
+
+    // In a poly-hierarchy (e.g. SNOMED CT) a concept is reachable through every
+    // one of its parents; without a visited set the recursion walks every *path*
+    // rather than every *node* - for the full SNOMED International edition that
+    // is ~15.8M visits for ~520k concepts, which is what turned an aborted
+    // expansion into a 30-second event-loop stall. Reaching a concept a second
+    // time means it has multiple parents, so (as when includeCode detects a
+    // duplicate) the expansion cannot be represented as a tree.
+    if (visited == null) {
+      visited = new Set();
+    }
+    // NB: contexts do not reliably carry a .code property (SnomedExpressionContext
+    // does not) - cs.code(context) is the accessor. Reading context.code here
+    // used to yield undefined for every SNOMED concept, collapsing the whole
+    // expansion onto one map key so no size guard could ever fire.
+    const code = await cs.code(context);
+    if (visited.has(code)) {
+      this.canBeHierarchy = false;
+      return 0;
+    }
+    visited.add(code);
 
     if (expansion) {
       const vs = this.canonical(await cs.system(), await cs.version());
@@ -1123,12 +1166,12 @@ class ValueSetExpander {
       const cds = new Designations(this.worker.i18n.languageDefinitions);
       let t;
       if (this.noDetails) {
-        t = await this.includeCode(cs, null, await cs.system(), await cs.version(), context.code, await cs.isAbstract(context), await cs.isInactive(context), null, null, null,
-            null, expansion, imports, null, null, null, null, excludeInactive, srcUrl);
+        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 {
         await this.listDisplaysFromProvider(cds, cs, context);
-        t = await this.includeCode(cs, parent, await cs.system(), await cs.version(), context.code, await cs.isAbstract(context), await cs.isInactive(context), await cs.isDeprecated(context), await cs.getStatus(context), cds, await cs.definition(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);
       }
       if (t != null) {
@@ -1145,16 +1188,29 @@ class ValueSetExpander {
     if (iter) {
       let c = await cs.nextContext(iter);
       while (c) {
-        this.worker.deadCheck('processCodeAndDescendants#3');
-        result += await this.includeCodeAndDescendants(cs, c, expansion, imports, n, excludeInactive, srcUrl);
+        await this.worker.checkAndYield('processCodeAndDescendants#3');
+        result += await this.includeCodeAndDescendants(cs, c, expansion, imports, n, excludeInactive, srcUrl, visited);
         c = await cs.nextContext(iter);
       }
     }
     return result;
   }
 
-  async excludeCodeAndDescendants(cs, context, expansion, imports, excludeInactive, srcUrl) {
-    this.worker.deadCheck('processCodeAndDescendants');
+  async excludeCodeAndDescendants(cs, context, expansion, imports, excludeInactive, srcUrl, visited = null) {
+    await this.worker.checkAndYield('processCodeAndDescendants');
+
+    // Same visited-set protection as includeCodeAndDescendants: walk nodes, not
+    // paths (see that method for why), and same accessor fix - context.code is
+    // not reliably present, and passing the raw context as the code produced
+    // useless "[object Object]" exclusion keys.
+    if (visited == null) {
+      visited = new Set();
+    }
+    const code = await cs.code(context);
+    if (visited.has(code)) {
+      return;
+    }
+    visited.add(code);
 
     if (expansion) {
       const vs = this.canonical(await cs.system(), await cs.version());
@@ -1168,15 +1224,15 @@ class ValueSetExpander {
     if ((!this.params.excludeNotForUI || !await cs.isAbstract(context)) && (!this.params.activeOnly || !await cs.isInactive(context))) {
       const cds = new Designations(this.worker.i18n.languageDefinitions);
       await this.listDisplaysFromProvider(cds, cs, context);
-      this.worker.deadCheck('processCodeAndDescendants#2');
-      this.excludeCode(cs, await cs.system(), await cs.version(), context, expansion, imports, srcUrl);
+      await this.worker.checkAndYield('processCodeAndDescendants#2');
+      this.excludeCode(cs, await cs.system(), await cs.version(), code, expansion, imports, srcUrl);
     }
 
     const iter = await cs.iterator(context);
     let c = await cs.nextContext(iter);
     while (c) {
-      this.worker.deadCheck('processCodeAndDescendants#3');
-      await this.excludeCodeAndDescendants(cs, c, expansion, imports, excludeInactive, srcUrl);
+      await this.worker.checkAndYield('processCodeAndDescendants#3');
+      await this.excludeCodeAndDescendants(cs, c, expansion, imports, excludeInactive, srcUrl, visited);
       c = await cs.nextContext(iter);
     }
   }
@@ -1187,11 +1243,11 @@ class ValueSetExpander {
     this.doingVersion = false;
     const ts = new Map();
     for (const c of source.jsonObj.compose.include || []) {
-      this.worker.deadCheck('handleCompose#2');
+      await this.worker.checkAndYield('handleCompose#2');
       await this.checkSource(c, expansion, filter, source.url, ts, vsInfo, source);
     }
     for (const c of source.jsonObj.compose.exclude || []) {
-      this.worker.deadCheck('handleCompose#3');
+      await this.worker.checkAndYield('handleCompose#3');
       this.hasExclusions = true;
       await this.checkSource(c, expansion, filter, source.url, ts, null, source);
     }
@@ -1205,7 +1261,7 @@ class ValueSetExpander {
 
       let i = 0;
       for (const c of source.jsonObj.compose.exclude || []) {
-        this.worker.deadCheck('handleCompose#4');
+        await this.worker.checkAndYield('handleCompose#4');
         await this.excludeCodes(c, "ValueSet.compose.exclude[" + i + "]", source, filter, expansion, this.excludeInactives(source), notClosed);
       }
 
@@ -1218,7 +1274,7 @@ class ValueSetExpander {
         return 0;
       });
       for (const c of includes) {
-        this.worker.deadCheck('handleCompose#5');
+        await this.worker.checkAndYield('handleCompose#5');
         await this.includeCodes(c, "ValueSet.compose.include[" + i + "]", source, source.jsonObj.compose, filter, expansion, this.excludeInactives(source), notClosed);
         i++;
       }
@@ -1346,7 +1402,7 @@ class ValueSetExpander {
     }
 
     this.worker.opContext.log('start working');
-    this.worker.deadCheck('expand');
+    await this.worker.checkAndYield('expand');
 
     let notClosed = { value :  false};
 
@@ -1433,7 +1489,7 @@ class ValueSetExpander {
       let t = 0;
       let o = 0;
       for (let i = 0; i < list.length; i++) {
-        this.worker.deadCheck('expand#1');
+        await this.worker.checkAndYield('expand#1');
         const c = list[i];
         if (this.map.has(this.keyC(c))) {
           o++;

package/tx/workers/worker.js

@@ -75,6 +75,15 @@ class TerminologyWorker {
     this.opContext.deadCheck(place);
   }
 
+  /**
+   * deadCheck plus a cooperative event-loop yield (see OperationContext.checkAndYield).
+   * Use this (awaited) from long-running loops in async code.
+   * @param {string} place - Location identifier for debugging
+   */
+  async checkAndYield(place = 'unknown') {
+    await this.opContext.checkAndYield(place);
+  }
+
   /**
    * Add cost diagnostics to an error
    * @param {TooCostlyError} e - The error to enhance