fhirsmith 0.11.2 → 0.13.0

package/tx/tx.fhir.org.yml

@@ -26,17 +26,18 @@ sources:
   - snomed:sct_us_20230301.cache
   - snomed:sct_us_20240301.cache
   - snomed:sct_us_20250901.cache
-  - snomed:sct_test_20250909.cache
+  - snomed:sct_test_20250909b.cache
   - cpt:CodeSystem-cpt.db|cpt-2023-fragment-0.1.db
   - omop:omop_v20250227.db
   - npm:hl7.terminology
-  - npm:fhir.tx.support.r4
+  - npm:fhir.tx.support
   - npm:ihe.formatcode.fhir
   - npm:fhir.dicom
   - npm:hl7.fhir.us.core
   - npm:us.cdc.phinvads
   - npm:hl7.fhir.uv.sdc
   - internal:vsac
+  - icd11:icd11-2026-01.db
 
 ignored:
   - urn:iso:std:iso:3166#20210120

package/tx/tx.js

@@ -51,6 +51,7 @@ const ClosureWorker = require("./workers/closure");
 const {BundleXML} = require("./xml/bundle-xml");
 const ConceptUsageTracker = require("./usage-tracker");
 const ProblemFinder = require("./problems");
+const { buildOperationOutcome } = require('./library/operation-outcome');
 // const {writeFileSync} = require("fs");
 
 class TXModule {
@@ -249,6 +250,10 @@ class TXModule {
     // cacheTimeout is in minutes, default to 30 minutes
     const cacheTimeoutMs = cacheTimeoutMinutes * 60 * 1000;
     const pruneIntervalMs = 5 * 60 * 1000; // Run every 5 minutes
+    // Tell the cache what timeout it is being pruned against, so $cache-control?mode=check
+    // can report it and a client can size its keepalive interval to this server rather
+    // than guessing at a number it has no way to see.
+    endpointInfo.resourceCache.setIdleTimeout(cacheTimeoutMs);
     if (this.stats) {
       this.stats.addTask("Client Cache", "5 min");
     }
@@ -433,14 +438,7 @@ class TXModule {
             }
           } catch (e) {
             this.log.error(`JSON parse error: ${e.message}`);
-            return res.status(400).json({
-              resourceType: 'OperationOutcome',
-              issue: [{
-                severity: 'error',
-                code: 'invalid',
-                diagnostics: `Invalid JSON: ${e.message}`
-              }]
-            });
+            return res.status(400).json(buildOperationOutcome('error', 'invalid', `Invalid JSON: ${e.message}`));
           }
         }
 
@@ -461,25 +459,11 @@ class TXModule {
             req.body = this.convertXmlToResource(xmlStr);
           } catch (e) {
             this.log.error(`XML parse error: ${e.message}`);
-            return res.status(400).json({
-              resourceType: 'OperationOutcome',
-              issue: [{
-                severity: 'error',
-                code: 'invalid',
-                diagnostics: `Invalid XML: ${e.message}`
-              }]
-            });
+            return res.status(400).json(buildOperationOutcome('error', 'invalid', `Invalid XML: ${e.message}`));
           }
         }
       } else if (contentType != 'application/x-www-form-urlencoded') {
-        return res.status(415).json({
-          resourceType: 'OperationOutcome',
-          issue: [{
-            severity: 'error',
-            code: 'invalid',
-            diagnostics: `Unsupported Media Type: ${contentType}`
-          }]
-        });
+        return res.status(415).json(buildOperationOutcome('error', 'invalid', `Unsupported Media Type: ${contentType}`));
       }
 
       if (req.body) {
@@ -491,7 +475,7 @@ class TXModule {
     app.use(express.urlencoded({ extended: true }));
 
     // Set up routes
-    this.setupRoutes(router);
+    this.setupRoutes(router, endpointInfo.path);
 
     // Redirect /r5 → /r5/
     app.use((req, res, next) => {
@@ -512,8 +496,11 @@ class TXModule {
   /**
    * Set up routes for an endpoint
    * @param {express.Router} router - Express router
+   * @param {string} endpointPath - the endpoint these routes belong to, e.g.
+   *   '/tx/r4'. Captured by the handlers below so that every request is
+   *   counted against the endpoint that served it, not just the operation.
    */
-  setupRoutes(router) {
+  setupRoutes(router, endpointPath) {
     const resourceTypes = ['CodeSystem', 'ValueSet', 'ConceptMap'];
 
     // ===== Operations =====
@@ -526,7 +513,7 @@ class TXModule {
         let worker = new LookupWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handle(req, res);
       } finally {
-        this.countRequest('$lookup', Date.now() - start);
+        this.countRequest(endpointPath, '$lookup', Date.now() - start);
       }
     });
     router.post('/CodeSystem/\\$lookup', async (req, res) => {
@@ -535,7 +522,7 @@ class TXModule {
         let worker = new LookupWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handle(req, res);
       } finally {
-        this.countRequest('$lookup', Date.now() - start);
+        this.countRequest(endpointPath, '$lookup', Date.now() - start);
       }
     });
 
@@ -546,7 +533,7 @@ class TXModule {
         let worker = new SubsumesWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handle(req, res);
       } finally {
-        this.countRequest('$subsumes', Date.now() - start);
+        this.countRequest(endpointPath, '$subsumes', Date.now() - start);
       }
     });
     router.post('/CodeSystem/\\$subsumes', async (req, res) => {
@@ -555,7 +542,7 @@ class TXModule {
         let worker = new SubsumesWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handle(req, res);
       } finally {
-        this.countRequest('$subsumes', Date.now() - start);
+        this.countRequest(endpointPath, '$subsumes', Date.now() - start);
       }
     });
 
@@ -566,7 +553,7 @@ class TXModule {
         let worker = new ValidateWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handleCodeSystem(req, res);
       } finally {
-        this.countRequest('$validate', Date.now() - start);
+        this.countRequest(endpointPath, '$validate', Date.now() - start);
       }
     });
     router.post('/CodeSystem/\\$validate-code', async (req, res) => {
@@ -575,7 +562,7 @@ class TXModule {
         let worker = new ValidateWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handleCodeSystem(req, res);
       } finally {
-        this.countRequest('$validate', Date.now() - start);
+        this.countRequest(endpointPath, '$validate', Date.now() - start);
       }
     });
 
@@ -586,7 +573,7 @@ class TXModule {
         let worker = new BatchValidateWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handleCodeSystem(req, res);
       } finally {
-        this.countRequest('$batch', Date.now() - start);
+        this.countRequest(endpointPath, '$batch', Date.now() - start);
       }
     });
     router.post('/CodeSystem/\\$batch-validate-code', async (req, res) => {
@@ -595,7 +582,7 @@ class TXModule {
         let worker = new BatchValidateWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handleCodeSystem(req, res);
       } finally {
-        this.countRequest('$batch', Date.now() - start);
+        this.countRequest(endpointPath, '$batch', Date.now() - start);
       }
     });
     // ValueSet/$validate-code (GET and POST)
@@ -605,7 +592,7 @@ class TXModule {
         let worker = new ValidateWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handleValueSet(req, res);
       } finally {
-        this.countRequest('$validate', Date.now() - start);
+        this.countRequest(endpointPath, '$validate', Date.now() - start);
       }
     });
     router.post('/ValueSet/\\$validate-code', async (req, res) => {
@@ -614,7 +601,7 @@ class TXModule {
         let worker = new ValidateWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handleValueSet(req, res);
       } finally {
-        this.countRequest('$validate', Date.now() - start);
+        this.countRequest(endpointPath, '$validate', Date.now() - start);
       }
     });
 
@@ -625,7 +612,7 @@ class TXModule {
         let worker = new CompareWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handle(req, res);
       } finally {
-        this.countRequest('$compare', Date.now() - start);
+        this.countRequest(endpointPath, '$compare', Date.now() - start);
       }
     });
     router.post('/ValueSet/\\$compare', async (req, res) => {
@@ -634,7 +621,7 @@ class TXModule {
         let worker = new CompareWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handle(req, res);
       } finally {
-        this.countRequest('$compare', Date.now() - start);
+        this.countRequest(endpointPath, '$compare', Date.now() - start);
       }
     });
 
@@ -645,7 +632,7 @@ class TXModule {
         let worker = new BatchValidateWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handleValueSet(req, res);
       } finally {
-        this.countRequest('$batch', Date.now() - start);
+        this.countRequest(endpointPath, '$batch', Date.now() - start);
       }
     });
     router.post('/ValueSet/\\$batch-validate-code', async (req, res) => {
@@ -654,7 +641,7 @@ class TXModule {
         let worker = new BatchValidateWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handleValueSet(req, res);
       } finally {
-        this.countRequest('validate', Date.now() - start);
+        this.countRequest(endpointPath, 'validate', Date.now() - start);
       }
     });
 
@@ -665,7 +652,7 @@ class TXModule {
         let worker = new ExpandWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n, this.internalLimit(req), this.externalLimit(req));
         await worker.handle(req, res, this.log);
       } finally {
-        this.countRequest('$expand', Date.now() - start);
+        this.countRequest(endpointPath, '$expand', Date.now() - start);
       }
     });
     router.post('/ValueSet/\\$expand', async (req, res) => {
@@ -674,7 +661,7 @@ class TXModule {
         let worker = new ExpandWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n, this.internalLimit(req), this.externalLimit(req));
         await worker.handle(req, res, this.log);
       } finally {
-        this.countRequest('$expand', Date.now() - start);
+        this.countRequest(endpointPath, '$expand', Date.now() - start);
       }
     });
 
@@ -685,7 +672,7 @@ class TXModule {
         let worker = new CacheControlWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handle(req, res, this.log);
       } finally {
-        this.countRequest('$cache-control', Date.now() - start);
+        this.countRequest(endpointPath, '$cache-control', Date.now() - start);
       }
     });
     router.post('/\\$cache-control', async (req, res) => {
@@ -694,7 +681,7 @@ class TXModule {
         let worker = new CacheControlWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handle(req, res, this.log);
       } finally {
-        this.countRequest('$cache-control', Date.now() - start);
+        this.countRequest(endpointPath, '$cache-control', Date.now() - start);
       }
     });
 
@@ -705,7 +692,7 @@ class TXModule {
         let worker = new TranslateWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handle(req, res, this.log);
       } finally {
-        this.countRequest('$translate', Date.now() - start);
+        this.countRequest(endpointPath, '$translate', Date.now() - start);
       }
     });
     router.post('/ConceptMap/\\$translate', async (req, res) => {
@@ -714,7 +701,7 @@ class TXModule {
         let worker = new TranslateWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handle(req, res, this.log);
       } finally {
-        this.countRequest('$translate', Date.now() - start);
+        this.countRequest(endpointPath, '$translate', Date.now() - start);
       }
     });
 
@@ -725,7 +712,7 @@ class TXModule {
         let worker = new ClosureWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handle(req, res, this.log);
       } finally {
-        this.countRequest('$closure', Date.now() - start);
+        this.countRequest(endpointPath, '$closure', Date.now() - start);
       }
     });
     router.post('/ConceptMap/\\$closure', async (req, res) => {
@@ -734,7 +721,7 @@ class TXModule {
         let worker = new ClosureWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handle(req, res, this.log);
       } finally {
-        this.countRequest('$closure', Date.now() - start);
+        this.countRequest(endpointPath, '$closure', Date.now() - start);
       }
     });
 
@@ -747,7 +734,7 @@ class TXModule {
         let worker = new LookupWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handleInstance(req, res);
       } finally {
-        this.countRequest('$lookup', Date.now() - start);
+        this.countRequest(endpointPath, '$lookup', Date.now() - start);
       }
     });
     router.post('/CodeSystem/:id/\\$lookup', async (req, res) => {
@@ -756,7 +743,7 @@ class TXModule {
         let worker = new LookupWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handleInstance(req, res);
       } finally {
-        this.countRequest('$lookup', Date.now() - start);
+        this.countRequest(endpointPath, '$lookup', Date.now() - start);
       }
     });
 
@@ -767,7 +754,7 @@ class TXModule {
         let worker = new SubsumesWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handleInstance(req, res);
       } finally {
-        this.countRequest('$subsumes', Date.now() - start);
+        this.countRequest(endpointPath, '$subsumes', Date.now() - start);
       }
     });
     router.post('/CodeSystem/:id/\\$subsumes', async (req, res) => {
@@ -776,7 +763,7 @@ class TXModule {
         let worker = new SubsumesWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handleInstance(req, res);
       } finally {
-        this.countRequest('$subsumes', Date.now() - start);
+        this.countRequest(endpointPath, '$subsumes', Date.now() - start);
       }
     });
 
@@ -787,7 +774,7 @@ class TXModule {
         let worker = new ValidateWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handleCodeSystemInstance(req, res, this.log);
       } finally {
-        this.countRequest('$validate', Date.now() - start);
+        this.countRequest(endpointPath, '$validate', Date.now() - start);
       }
     });
     router.post('/CodeSystem/:id/\\$validate-code', async (req, res) => {
@@ -796,7 +783,7 @@ class TXModule {
         let worker = new ValidateWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handleCodeSystemInstance(req, res, this.log);
       } finally {
-        this.countRequest('$validate', Date.now() - start);
+        this.countRequest(endpointPath, '$validate', Date.now() - start);
       }
 
     });
@@ -808,7 +795,7 @@ class TXModule {
         let worker = new ValidateWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handleValueSetInstance(req, res, this.log);
       } finally {
-        this.countRequest('$validate', Date.now() - start);
+        this.countRequest(endpointPath, '$validate', Date.now() - start);
       }
     });
     router.post('/ValueSet/:id/\\$validate-code', async (req, res) => {
@@ -817,7 +804,7 @@ class TXModule {
         let worker = new ValidateWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handleValueSetInstance(req, res, this.log);
       } finally {
-        this.countRequest('$validate', Date.now() - start);
+        this.countRequest(endpointPath, '$validate', Date.now() - start);
       }
     });
 
@@ -829,7 +816,7 @@ class TXModule {
         let worker = new CompareWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handleInstance(req, res, this.log);
       } finally {
-        this.countRequest('$compare', Date.now() - start);
+        this.countRequest(endpointPath, '$compare', Date.now() - start);
       }
     });
     router.post('/ValueSet/:id/\\$compare', async (req, res) => {
@@ -838,7 +825,7 @@ class TXModule {
         let worker = new CompareWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handleInstance(req, res, this.log);
       } finally {
-        this.countRequest('$compare', Date.now() - start);
+        this.countRequest(endpointPath, '$compare', Date.now() - start);
       }
     });
 
@@ -849,7 +836,7 @@ class TXModule {
         let worker = new ExpandWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n, this.internalLimit(req), this.externalLimit(req));
         await worker.handleInstance(req, res, this.log);
       } finally {
-        this.countRequest('$expand', Date.now() - start);
+        this.countRequest(endpointPath, '$expand', Date.now() - start);
       }
     });
     router.post('/ValueSet/:id/\\$expand', async (req, res) => {
@@ -858,7 +845,7 @@ class TXModule {
         let worker = new ExpandWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n, this.internalLimit(req), this.externalLimit(req));
         await worker.handleInstance(req, res, this.log);
       } finally {
-        this.countRequest('$expand', Date.now() - start);
+        this.countRequest(endpointPath, '$expand', Date.now() - start);
       }
     });
 
@@ -869,7 +856,7 @@ class TXModule {
         let worker = new TranslateWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handleInstance(req, res, this.log);
       } finally {
-        this.countRequest('$translate', Date.now() - start);
+        this.countRequest(endpointPath, '$translate', Date.now() - start);
       }
     });
     router.post('/ConceptMap/:id/\\$translate', async (req, res) => {
@@ -878,7 +865,7 @@ class TXModule {
         let worker = new TranslateWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handleInstance(req, res, this.log);
       } finally {
-        this.countRequest('$translate', Date.now() - start);
+        this.countRequest(endpointPath, '$translate', Date.now() - start);
       }
     });
 
@@ -900,7 +887,7 @@ class TXModule {
           let worker = new ReadWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
           await worker.handle(req, res, resourceType);
         } finally {
-          this.countRequest('read', Date.now() - start);
+          this.countRequest(endpointPath, 'read', Date.now() - start);
         }
       });
     }
@@ -913,7 +900,7 @@ class TXModule {
           let worker = new SearchWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
           await worker.handle(req, res, resourceType);
         } finally {
-          this.countRequest('search', Date.now() - start);
+          this.countRequest(endpointPath, 'search', Date.now() - start);
         }
       });
       router.post(`/${resourceType}/_search`, async (req, res) => {
@@ -922,7 +909,7 @@ class TXModule {
           let worker = new SearchWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
           await worker.handle(req, res, resourceType);
         } finally {
-          this.countRequest('search', Date.now() - start);
+          this.countRequest(endpointPath, 'search', Date.now() - start);
         }
       });
     }
@@ -940,7 +927,7 @@ class TXModule {
             ));
           }
         } finally {
-          this.countRequest('$read', Date.now() - start);
+          this.countRequest(endpointPath, '$read', Date.now() - start);
         }
       });
     }
@@ -951,7 +938,7 @@ class TXModule {
         let worker = new OperationsWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handle(req, res);
       } finally {
-        this.countRequest('$op', Date.now() - start);
+        this.countRequest(endpointPath, '$op', Date.now() - start);
       }
     });
 
@@ -965,7 +952,7 @@ class TXModule {
         res.setHeader('Content-Type', 'text/html');
         res.send(html);
       } finally {
-        this.countRequest('problems', Date.now() - start);
+        this.countRequest(endpointPath, 'problems', Date.now() - start);
       }
     });
 
@@ -980,7 +967,7 @@ class TXModule {
           res.status(500).json(this.operationOutcome('error', 'exception', error.message));
         }
       } finally {
-        this.countRequest('metadata', Date.now() - start);
+        this.countRequest(endpointPath, 'metadata', Date.now() - start);
       }
     });
 
@@ -995,7 +982,7 @@ class TXModule {
           res.status(500).json(this.operationOutcome('error', 'exception', error.message));
         }
       } finally {
-        this.countRequest('$versions', Date.now() - start);
+        this.countRequest(endpointPath, '$versions', Date.now() - start);
       }
     });
 
@@ -1003,16 +990,9 @@ class TXModule {
     router.get('/', async (req, res) => {
       const start = Date.now();
       try {
-        await res.json({
-          resourceType: 'OperationOutcome',
-          issue: [{
-            severity: 'information',
-            code: 'informational',
-            diagnostics: `FHIR Terminology Server - FHIR v${req.txEndpoint.fhirVersion}`
-          }]
-        });
+        await res.json(buildOperationOutcome('information', 'informational', `FHIR Terminology Server - FHIR v${req.txEndpoint.fhirVersion}`));
       } finally {
-        this.countRequest('home', Date.now() - start);
+        this.countRequest(endpointPath, 'home', Date.now() - start);
       }
     });
 
@@ -1037,7 +1017,7 @@ class TXModule {
         this.log.error(`Error rendering info page for ${req.params.id}: ${error.message}`);
         res.status(500).send('Internal server error');
       } finally {
-        this.countRequest('info', Date.now() - start);
+        this.countRequest(endpointPath, 'info', Date.now() - start);
       }
     };
     router.get('/info/:id', infoHandler);
@@ -1118,17 +1098,17 @@ class TXModule {
   }
 
   /**
-   * Build an OperationOutcome for errors
+   * Build an OperationOutcome. Delegates to the shared builder so that every outcome this
+   * server emits has details.text and a tx-issue-type coding: diagnostics is stripped by
+   * the test harness, so nothing a caller needs may live there.
+   * @param {string} severity - error, warning, information
+   * @param {string} code - FHIR issue type
+   * @param {string} message - the human readable account of the problem
+   * @param {string} [txIssueType] - tx-issue-type; defaulted from code when not given
+   * @returns {Object} OperationOutcome resource
    */
-  operationOutcome(severity, code, message) {
-    return {
-      resourceType: 'OperationOutcome',
-      issue: [{
-        severity,
-        code,
-        diagnostics: message
-      }]
-    };
+  operationOutcome(severity, code, message, txIssueType = null) {
+    return buildOperationOutcome(severity, code, message, txIssueType);
   }
 
   /**
@@ -1214,9 +1194,9 @@ class TXModule {
     return data;
   }
 
-  countRequest(name, tat) {
+  countRequest(endpoint, name, tat) {
     if (this.stats) {
-      this.stats.countRequest(name, tat);
+      this.stats.countRequest(name, tat, endpoint);
     }
   }
 

package/tx/workers/batch-validate.js

@@ -13,7 +13,7 @@
 //
 
 const { TerminologyWorker } = require('./worker');
-const {OperationOutcome, Issue} = require("../library/operation-outcome");
+const { OperationOutcome, Issue, buildOperationOutcome, outcomeFromError } = require('../library/operation-outcome');
 const {Parameters} = require("../library/parameters");
 const {ValidateWorker} = require("./validate");
 const {debugLog} = require("../operation-context");
@@ -137,7 +137,7 @@ class BatchValidateWorker extends TerminologyWorker {
               op.addIssue(error);
               output.push({name: "validation", resource : op.jsonObj});
             } else {
-              output.push({name: "validation", resource : this.operationOutcome('error', error.issueCode || 'exception', error.message) } );
+              output.push({name: "validation", resource : outcomeFromError(error) } );
             }
           }
         }
@@ -156,8 +156,7 @@ class BatchValidateWorker extends TerminologyWorker {
         oo.addIssue(error);
         return res.status(error.statusCode || 500).json(oo.jsonObj);
       }
-      return res.status(error.statusCode || 500).json(this.operationOutcome(
-        'error', error.issueCode || 'exception', error.message));
+      return res.status(error.statusCode || 500).json(outcomeFromError(error));
     }
   }
 
@@ -187,8 +186,11 @@ class BatchValidateWorker extends TerminologyWorker {
       return false;
     }
     if (!cache.has(cacheId)) {
-      throw new Issue('error', 'not-found', null, 'CACHE_ID_UNKNOWN',
-        this.i18n.translate('CACHE_ID_UNKNOWN', this.opContext.langs, [cacheId]),
+      // describeMissing names which fate the id met (never issued here / closed by
+      // the client / idle-expired); the coding stays cache-id-unknown either way.
+      const { messageId, params: msgParams } = cache.describeMissing(cacheId);
+      throw new Issue('error', 'not-found', null, messageId,
+        this.i18n.translate(messageId, this.opContext.langs, msgParams),
         'cache-id-unknown', 404);
     }
     if (cache.isSealed(cacheId)) {
@@ -215,18 +217,9 @@ class BatchValidateWorker extends TerminologyWorker {
   /**
    * Build an OperationOutcome
    */
-  operationOutcome(severity, code, message) {
-    return {
-      resourceType: 'OperationOutcome',
-      issue: [{
-        severity,
-        code,
-        details: {
-          text: message
-        },
-        diagnostics: message
-      }]
-    };
+  operationOutcome(severity, code, message, txIssueType = null) {
+    // the shared builder, so that every outcome has details.text and a tx-issue-type coding
+    return buildOperationOutcome(severity, code, message, txIssueType);
   }
 
   hasValueSet(parameter) {