fhirsmith 0.10.1 → 0.11.0

package/tx/operation-context.js

@@ -118,6 +118,19 @@ class ResourceCache {
     return this.cache.has(cacheId);
   }
 
+  /**
+   * Whether a cache is sealed. A sealed cache holds only the resources it was
+   * created with (at $cache-control?mode=start) and does not grow as further
+   * resources are seen on subsequent operations. An unsealed cache accumulates
+   * every resource it sees. Unknown/absent cache-ids report false.
+   * @param {string} cacheId - The cache identifier
+   * @returns {boolean}
+   */
+  isSealed(cacheId) {
+    const entry = this.cache.get(cacheId);
+    return entry ? !!entry.sealed : false;
+  }
+
   /**
    * Add resources to a cache-id (merges with existing)
    * @param {string} cacheId - The cache identifier
@@ -126,6 +139,18 @@ class ResourceCache {
   add(cacheId, resources) {
     if (!resources || resources.length === 0) return;
 
+    // These resources are being retained under a cache-id (they persist across
+    // the batch), so mark them cached: their filter elements survive, and a
+    // provider may memoise resolved filter analysis on them (see filter()/fc).
+    // Inline tx-resources that never enter this pool stay unmarked.
+    for (const resource of resources) {
+      if (resource) {
+        // non-enumerable: internal marker only, must never serialise into a
+        // response or be copied by structuredClone/spread when a VS is cloned.
+        Object.defineProperty(resource, 'isCached', { value: true, enumerable: false, configurable: true, writable: true });
+      }
+    }
+
     const entry = this.cache.get(cacheId) || { resources: [], lastUsed: Date.now(), concepts: 0 };
 
     // Merge resources, avoiding duplicates by url+version. Keep the entry's concept
@@ -158,9 +183,20 @@ class ResourceCache {
    * Set resources for a cache-id (replaces existing)
    * @param {string} cacheId - The cache identifier
    * @param {Array} resources - Resources to set
+   * @param {boolean} [sealed=false] - If true, the cache is fixed at these
+   *   resources and will not grow when further resources are seen later.
    */
-  set(cacheId, resources) {
-    this.log.info(`cache-id '${cacheId}': set (replace all) with ${resources.length} resource(s): ${resources.map(r => this._resourceKey(r)).join(', ')}`);
+  set(cacheId, resources, sealed = false) {
+    this.log.info(`cache-id '${cacheId}': set (replace all, sealed=${!!sealed}) with ${resources.length} resource(s): ${resources.map(r => this._resourceKey(r)).join(', ')}`);
+    // Retained under a cache-id - mark cached so providers may memoise resolved
+    // filter analysis on their filter elements (see filter()/fc).
+    for (const resource of resources) {
+      if (resource) {
+        // non-enumerable: internal marker only, must never serialise into a
+        // response or be copied by structuredClone/spread when a VS is cloned.
+        Object.defineProperty(resource, 'isCached', { value: true, enumerable: false, configurable: true, writable: true });
+      }
+    }
     // Drop the old entry's contribution, then count the replacement.
     const existing = this.cache.get(cacheId);
     if (existing) {
@@ -174,7 +210,8 @@ class ResourceCache {
     this.cache.set(cacheId, {
       resources: [...resources],
       lastUsed: Date.now(),
-      concepts
+      concepts,
+      sealed: !!sealed
     });
     this._trackMax();
   }

package/tx/provider.js

@@ -174,13 +174,7 @@ class Provider {
     for (const resource of resources) {
       const cs = new CodeSystem(await contentLoader.loadFile(resource, contentLoader.fhirVersion()));
       cs.sourcePackage = contentLoader.pid();
-      const existing = this.codeSystems.get(cs.url);
-      if (!existing || cs.isMoreRecent(existing)) {
-        this.codeSystems.set(cs.url, cs);
-      }
-      if (cs.version) {
-        this.codeSystems.set(cs.vurl, cs);
-      }
+      this.addCodeSystem(cs);
     }
     const vs = new PackageValueSetProvider(contentLoader);
     await vs.initialize();
@@ -486,13 +480,48 @@ class Provider {
     }
   }
 
+  /**
+   * True if the source package id (e.g. "hl7.terminology.r4#6.0.2") is a
+   * terminology.hl7.org (THO/UTG) package.
+   */
+  static #isTHOPackage(pid) {
+    return pid != null && pid.startsWith("hl7.terminology");
+  }
+
   addCodeSystem(cs) {
+    // Special case, mirroring CanonicalResourceManager.see() in the Java core:
+    // when content moved from the FHIR core packages to terminology.hl7.org,
+    // the versions went backwards (e.g. coverage-selfpay is 4.0.1 in
+    // hl7.fhir.r4.core (2019) but 1.0.1 in hl7.terminology (2024)), so plain
+    // version precedence would leave the stale core copy as the default. A
+    // resource from an hl7.terminology package displaces any same-URL
+    // resource that came from a FHIR core package, regardless of version.
+    if (Provider.#isTHOPackage(cs.sourcePackage)) {
+      for (const [key, t] of [...this.codeSystems]) {
+        // only the bare-url (default) entry is displaced; explicitly versioned
+        // entries (key = url|version) stay addressable, because the core packages
+        // carry historical versions (e.g. the normalized R4 v2 tables 0006/0360/0391
+        // at 2.1/2.3.1/2.4/2.6/2.7) that hl7.terminology does not publish at all
+        if (key === t.url && t.url === cs.url && VersionUtilities.isCorePackage(t.sourcePackage)) {
+          this.codeSystems.delete(key);
+        }
+      }
+    }
     const existing = this.codeSystems.get(cs.url);
-    if (!existing || cs.isMoreRecent(existing)) {
+    // the reverse guard: a core-package resource never displaces a THO one
+    const yieldsToTHO = existing && Provider.#isTHOPackage(existing.sourcePackage)
+      && VersionUtilities.isCorePackage(cs.sourcePackage);
+    if (!existing || (!yieldsToTHO && cs.isMoreRecent(existing))) {
       this.codeSystems.set(cs.url, cs);
     }
     if (cs.version) {
-      this.codeSystems.set(cs.vurl, cs);
+      // a versioned entry only yields to THO when THO itself provides that exact version
+      const vExisting = this.codeSystems.get(cs.vurl);
+      const vYieldsToTHO = vExisting && Provider.#isTHOPackage(vExisting.sourcePackage)
+        && VersionUtilities.isCorePackage(cs.sourcePackage);
+      if (!vYieldsToTHO) {
+        this.codeSystems.set(cs.vurl, cs);
+      }
     }
   }
 

package/tx/sct/ecl.js

@@ -472,8 +472,21 @@ class ECLParser {
   parseCompoundExpressionConstraint() {
     let left = this.parseRefinedExpressionConstraint();
 
+    // ECL 6.4: conjunction (AND), disjunction (OR) and exclusion (MINUS)
+    // operators must not be mixed within a single ungrouped compound expression;
+    // round brackets are mandatory to disambiguate. Track the operator used in
+    // this compound sequence and reject a mix (e.g. "<< A OR << B AND << C").
+    let compoundOp = null;
+
     while (this.match(ECLTokenType.AND, ECLTokenType.OR, ECLTokenType.MINUS)) {
       const operator = this.current;
+      if (compoundOp !== null && operator.type !== compoundOp) {
+        throw new Error(
+          'Ambiguous ECL expression: conjunction, disjunction and exclusion ' +
+          'operators cannot be mixed without parentheses (ECL 6.4). ' +
+          'Use round brackets to disambiguate.');
+      }
+      compoundOp = operator.type;
       this.advance();
       const right = this.parseRefinedExpressionConstraint();
 
@@ -616,12 +629,19 @@ class ECLParser {
     const attributes = [];
 
     do {
+      // A leading cardinality may prefix either a single attribute
+      // ([m..n] attr = v) or an attribute group ([m..n] { ... }). Parse it once,
+      // then dispatch on whether a group ({) or an attribute follows.
+      let cardinality = null;
+      if (this.match(ECLTokenType.LBRACKET)) {
+        cardinality = this.parseCardinality();
+      }
       if (this.match(ECLTokenType.LBRACE)) {
         // Attribute group
-        attributes.push(this.parseAttributeGroup());
+        attributes.push(this.parseAttributeGroup(cardinality));
       } else {
         // Single attribute
-        attributes.push(this.parseAttribute());
+        attributes.push(this.parseAttribute(cardinality));
       }
     } while (this.match(ECLTokenType.COMMA) && (this.advance(), true));
 
@@ -635,11 +655,10 @@ class ECLParser {
     };
   }
 
-  parseAttributeGroup() {
-    let cardinality = null;
-
-    // Check for cardinality before {
-    if (this.match(ECLTokenType.LBRACKET)) {
+  parseAttributeGroup(cardinality = null) {
+    // Cardinality may have been parsed by the caller (parseAttributeSet); if
+    // not, check for it here (before the opening brace).
+    if (cardinality === null && this.match(ECLTokenType.LBRACKET)) {
       cardinality = this.parseCardinality();
     }
 
@@ -659,12 +678,12 @@ class ECLParser {
     };
   }
 
-  parseAttribute() {
-    let cardinality = null;
+  parseAttribute(cardinality = null) {
     let reverse = false;
 
-    // Check for cardinality first - this must come before attribute name
-    if (this.match(ECLTokenType.LBRACKET)) {
+    // Cardinality may have been parsed by the caller (parseAttributeSet); if
+    // not, check for it here (it must come before the attribute name).
+    if (cardinality === null && this.match(ECLTokenType.LBRACKET)) {
       cardinality = this.parseCardinality();
     }
 

package/tx/sct/expressions.js

@@ -1534,6 +1534,33 @@ class SnomedExpressionServices {
    * List all display names for a concept
    * Equivalent to Pascal ListDisplayNames procedure
    */
+  // Key concept indexes for preferred-term selection (US English is the global
+  // default language reference set). Mirrors the logic in cs-snomed.js so both
+  // display paths agree.
+  _displayConstants() {
+    if (this._dispConst) return this._dispConst;
+    const idx = (id) => { const r = this.concepts.findConcept(id); return r.found ? r.index : -1; };
+    this._dispConst = {
+      usRefset: idx(900000000000509007n),
+      preferred: idx(900000000000548007n),
+      synonym: idx(900000000000013009n)
+    };
+    return this._dispConst;
+  }
+
+  _isPreferredSynonym(description) {
+    const K = this._displayConstants();
+    if (description.kind !== K.synonym) return false;
+    if (!description.valueses) return false;
+    const valueses = this.refs.getReferences(description.valueses);
+    if (!valueses) return false;
+    for (let i = 0; i < valueses.length; i++) {
+      const vals = this.refs.getReferences(valueses[i]); // [acceptabilityIndex, type]
+      if (vals && vals.length > 0 && vals[0] === K.preferred) return true;
+    }
+    return false;
+  }
+
   listDisplayNames(conceptIndex, languageFilter = 0) {
     const designations = [];
 
@@ -1558,7 +1585,7 @@ class SnomedExpressionServices {
             const term = this.strings.getEntry(description.iDesc).trim();
 
             designations.push({
-              isPreferred: i === 0, // First description is considered preferred
+              isPreferred: this._isPreferredSynonym(description), // preferred synonym in US English
               isActive: true,
               languageCode: this.codeForLanguage(description.lang),
               term: term,

package/tx/sct/structures.js

@@ -719,6 +719,11 @@ class SnomedConceptList {
     this.master.writeUInt32LE(value, index + 13);
   }
 
+  setModuleId(index, moduleIndex) {
+    this.#checkPostBuildAccess(index);
+    this.master.writeUInt32LE(moduleIndex, index + 36);
+  }
+
   setInbounds(index, value) {
     this.#checkPostBuildAccess(index);
     this.master.writeUInt32LE(value, index + 17);
@@ -749,11 +754,6 @@ class SnomedConceptList {
     this.master.writeUInt16LE(effectiveTime, index + 34);
   }
 
-  setModuleId(index, value) {
-    this.#checkPostBuildAccess(index);
-    this.master.writeUInt32LE(value, index + 36);
-  }
-
   setStatus(index, value) {
     this.#checkPostBuildAccess(index);
     this.master.writeUInt32LE(value, index + 40);

package/tx/tx-html.js

@@ -64,6 +64,28 @@ function loadTemplate() {
   }
 }
 
+/**
+ * Check if a request wants HTML back (by _format/format param, else Accept header).
+ * Module-level so non-rendering code (e.g. the search worker choosing a default
+ * page size) can make the same call the response renderer will make.
+ */
+function acceptsHtml(req) {
+  let _fmt = req.query._format || req.query.format || req.body?._format;
+  if (_fmt && typeof _fmt !== 'string') {
+    _fmt = null;
+  }
+  if (_fmt && (_fmt == 'html' || _fmt.startsWith('html/'))) {
+    return true;
+  }
+  if (!_fmt) {
+    _fmt = req.headers.accept || '';
+  }
+  if (typeof _fmt !== 'string') {
+    return false;
+  }
+  return _fmt.includes('text/html');
+}
+
 
 class TxHtmlRenderer {
   renderer;
@@ -98,20 +120,7 @@ class TxHtmlRenderer {
    * Check if request accepts HTML
    */
   acceptsHtml(req) {
-    let _fmt = req.query._format || req.query.format || req.body?._format;
-    if (_fmt && typeof _fmt !== 'string') {
-      _fmt = null;
-    }
-    if (_fmt && (_fmt == 'html' || _fmt.startsWith('html/'))) {
-      return true;
-    }
-    if (!_fmt) {
-      _fmt = req.headers.accept || '';
-    }
-    if (typeof _fmt !== 'string') {
-      return false;
-    }
-    return _fmt.includes('text/html');
+    return acceptsHtml(req);
   }
 
   /**
@@ -1362,5 +1371,5 @@ class TxHtmlRenderer {
 }
 
 module.exports = {
-  TxHtmlRenderer, loadTemplate
+  TxHtmlRenderer, loadTemplate, acceptsHtml
 };

package/tx/tx.fhir.org.yml

@@ -18,9 +18,6 @@ sources:
   - unii:unii_20240622.db
   - snomed:sct_intl_20240201.cache
   - snomed!:sct_intl_20250201.cache
-#  - snomed:sct_se_20231130.cache
-#  - snomed:sct_au_20230731.cache
-#  - snomed:sct_be_20231115.cache
   - snomed:sct_ch_20230607.cache
   - snomed:sct_dk_20260331.cache
   - snomed:sct_ips_20241216.cache
@@ -29,7 +26,7 @@ sources:
   - snomed:sct_us_20230301.cache
   - snomed:sct_us_20240301.cache
   - snomed:sct_us_20250901.cache
-  - snomed:sct_test_20250814.cache
+  - snomed:sct_test_20250909.cache
   - cpt:CodeSystem-cpt.db|cpt-2023-fragment-0.1.db
   - omop:omop_v20250227.db
   - npm:hl7.terminology

package/tx/vs/vs-package.js

@@ -1,4 +1,5 @@
 const path = require('path');
+const fs = require('fs').promises;
 const { AbstractValueSetProvider } = require('./vs-api');
 const { PackageContentLoader } = require('../../library/package-manager');
 const { ValueSetDatabase } = require('./vs-database');
@@ -51,9 +52,60 @@ class PackageValueSetProvider extends AbstractValueSetProvider {
     }
 
     this.valueSetMap = await this.database.loadAllValueSets(this.sourcePackage());
+
+    // Self-heal caches built before pipe-versioned canonical urls were normalized at
+    // load time (the R4 v2 tables 0006/0360/0391 - see normalizeVersionedCanonicals in
+    // package-manager.js): if any cached value set still carries a "system|version"
+    // include or a pipe in its url, rebuild this cache from the package.
+    if (dbExists && this.#hasPipeVersionedCanonicals()) {
+      await this.database.close();
+      await fs.rm(this.dbPath, { force: true });
+      this.database = new ValueSetDatabase(this.dbPath);
+      await this.database.create();
+      await this._populateDatabase();
+      this.valueSetMap = await this.database.loadAllValueSets(this.sourcePackage());
+    }
+
+    // Mark each value set as cached as it enters the store: it is retained in
+    // memory for the process lifetime, so its compose.include.filter elements
+    // persist and a provider may memoise resolved filter analysis on them
+    // (see CodeSystemProvider.filter()'s `fc` parameter).
+    for (const vs of this.valueSetMap.values()) {
+      if (vs) {
+        // non-enumerable: internal marker only, must never serialise into a
+        // response or be copied by structuredClone/spread when a VS is cloned.
+        Object.defineProperty(vs, 'isCached', { value: true, enumerable: false, configurable: true, writable: true });
+      }
+    }
     this.initialized = true;
   }
 
+  /**
+   * True if any loaded value set still has a pipe-versioned canonical (url or
+   * compose include/exclude system) - the signature of a cache written before
+   * load-time normalization existed.
+   */
+  #hasPipeVersionedCanonicals() {
+    for (const vs of this.valueSetMap.values()) {
+      if (!vs) {
+        continue;
+      }
+      if (typeof vs.url === 'string' && vs.url.includes('|')) {
+        return true;
+      }
+      if (vs.compose) {
+        for (const list of [vs.compose.include, vs.compose.exclude]) {
+          for (const inc of list || []) {
+            if (typeof inc.system === 'string' && inc.system.includes('|')) {
+              return true;
+            }
+          }
+        }
+      }
+    }
+    return false;
+  }
+
   async close() {
     await this.database.close();
   }

package/tx/workers/batch-validate.js

@@ -1,14 +1,15 @@
 //
-// Validate Worker - Handles $validate-code operations
+// Batch Validate Worker - Handles $batch-validate-code operations
 //
-// GET /CodeSystem/$validate-code?{params}
-// POST /CodeSystem/$validate-code
-// GET /CodeSystem/{id}/$validate-code?{params}
-// POST /CodeSystem/{id}/$validate-code
-// GET /ValueSet/$validate-code?{params}
-// POST /ValueSet/$validate-code
-// GET /ValueSet/{id}/$validate-code?{params}
-// POST /ValueSet/{id}/$validate-code
+// GET/POST /ValueSet/$batch-validate-code    - batch of ValueSet  $validate-code
+// GET/POST /CodeSystem/$batch-validate-code  - batch of CodeSystem $validate-code
+//
+// A batch is a Parameters whose `validation` entries each carry a single
+// $validate-code request (as a nested Parameters). Shared inputs may be supplied
+// once at the top level ("globals") and are applied to every entry. Entries are
+// dispatched per-shape (a url/valueSet entry validates against a value set; a
+// system/codeSystem entry validates against a code system), so both batch routes
+// share one implementation and even a mixed batch is handled correctly.
 //
 
 const { TerminologyWorker } = require('./worker');
@@ -30,12 +31,20 @@ class BatchValidateWorker extends TerminologyWorker {
    */
   constructor(opContext, log, provider, languages, i18n) {
     super(opContext, log, provider, languages, i18n);
-    this.globalNames.add("tx-resource");
-    this.globalNames.add("url");
-    this.globalNames.add("valueSet");
-    this.globalNames.add("lenient-display-validation");
-    this.globalNames.add("__Accept-Language");
-    this.globalNames.add("__Content-Language");
+    // "Global" parameters may be supplied once at the top level and are applied to
+    // every entry that doesn't override them. tx-resource is always shared. The
+    // primary differs by operation: a ValueSet batch shares url/valueSet, a
+    // CodeSystem batch shares system/codeSystem.
+    this.valueSetGlobalNames = new Set([
+      "tx-resource", "url", "valueSet", "lenient-display-validation",
+      "__Accept-Language", "__Content-Language"
+    ]);
+    this.codeSystemGlobalNames = new Set([
+      "tx-resource", "system", "codeSystem", "lenient-display-validation",
+      "__Accept-Language", "__Content-Language"
+    ]);
+    // Back-compat: `globalNames` was the (ValueSet) set before CodeSystem batches.
+    this.globalNames = this.valueSetGlobalNames;
   }
 
   /**
@@ -46,18 +55,43 @@ class BatchValidateWorker extends TerminologyWorker {
     return 'batch-validate-code';
   }
 
+  /** ValueSet/$batch-validate-code: shared globals are url/valueSet. */
   async handleValueSet(req, res) {
+    return this.processBatch(req, res, this.valueSetGlobalNames);
+  }
+
+  /** CodeSystem/$batch-validate-code: shared globals are system/codeSystem. */
+  async handleCodeSystem(req, res) {
+    return this.processBatch(req, res, this.codeSystemGlobalNames);
+  }
+
+  /**
+   * Run a batch of $validate-code requests. Two passes: frontLoadBatch() pools all
+   * supplied resources into an unsealed cache first (see that method); then each
+   * `validation` entry is evaluated, inheriting the top-level globals it does not
+   * override and dispatched by shape to the ValueSet or CodeSystem validator.
+   *
+   * @param {express.Request} req
+   * @param {express.Response} res
+   * @param {Set<string>} globalNames - which top-level params are shared globals
+   */
+  async processBatch(req, res, globalNames) {
     try {
       let params = req.body;
       this.addHttpParams(req, params);
 
       let globalParams = [];
       for (const p of params.parameter) {
-        if (this.globalNames.has(p.name)) {
+        if (globalNames.has(p.name)) {
           globalParams.push(p);
         }
       }
 
+      // Pass 1: front-load every resource the batch supplies into the (unsealed)
+      // session cache before any entry is evaluated. When this happens, pass 2
+      // below drops per-entry tx-resource processing (they're already cached).
+      const frontLoaded = this.frontLoadBatch(params);
+
       let output = [];
 
       for (const p of params.parameter) {
@@ -65,12 +99,26 @@ class BatchValidateWorker extends TerminologyWorker {
           let op = new Parameters();
           op.jsonObj.parameter = [];
           for (const gp of globalParams) {
+            if (gp.name == 'tx-resource') {
+              // Pass 2: when the batch was front-loaded into an unsealed cache, the
+              // tx-resources are already in the cache and every entry resolves them
+              // by reference - don't re-inject or re-process them per entry. Without
+              // front-loading (no cache, or a sealed cache) keep the original
+              // behaviour: the global tx-resources apply to every entry.
+              if (!frontLoaded) {
+                op.jsonObj.parameter.push(gp);
+              }
+              continue;
+            }
             let exists = p.resource.parameter.find(pp => gp.name == pp.name);
-            if (gp.name == 'tx-resource' || !exists) {
+            if (!exists) {
               op.jsonObj.parameter.push(gp);
             }
           }
-          op.jsonObj.parameter.push(...p.resource.parameter);
+          const entryParams = frontLoaded
+            ? p.resource.parameter.filter(pp => pp.name !== 'tx-resource')
+            : p.resource.parameter;
+          op.jsonObj.parameter.push(...entryParams);
 
           let worker = new ValidateWorker(this.opContext.copy(), this.log, this.provider, this.languages, this.i18n);
           try {
@@ -100,11 +148,70 @@ class BatchValidateWorker extends TerminologyWorker {
     } catch (error) {
       this.log.error(error);
       debugLog(error);
+      // A batch-level failure (e.g. an unknown cache-id from pass 1) applies to the
+      // whole batch. Preserve a coded Issue (like cache-id-unknown) so the client
+      // gets the same coded OperationOutcome + status it would on a single op.
+      if (error instanceof Issue) {
+        const oo = new OperationOutcome();
+        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));
     }
   }
 
+  /**
+   * Pass 1 of batch processing: front-load every resource the batch supplies
+   * (each `tx-resource`, plus each entry's primary `valueSet`/`codeSystem`) into
+   * the session cache before any entry is evaluated. This makes the batch
+   * order-independent - an entry may refer by url to a resource another entry
+   * supplied - and means a failing entry does not withhold the resources it
+   * carried, because population happens up front and as one step.
+   *
+   * Front-loading is only relevant for an *unsealed* cache: that is what grows, so
+   * that is how one entry's resources become visible to the others. A sealed cache
+   * does not grow (each entry stays self-contained), and with no cache there is
+   * nowhere to pool; in both cases this returns false and pass 2 keeps the original
+   * per-entry tx-resource handling.
+   *
+   * The unknown-cache-id check is done here, once, for the whole batch.
+   *
+   * @param {Object} params - the batch Parameters (req.body)
+   * @returns {boolean} true if resources were front-loaded into an unsealed cache
+   */
+  frontLoadBatch(params) {
+    const cacheId = this.opContext ? this.opContext.cacheId : null;
+    const cache = this.opContext ? this.opContext.resourceCache : null;
+    if (!cacheId || !cache) {
+      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]),
+        'cache-id-unknown', 404);
+    }
+    if (cache.isSealed(cacheId)) {
+      return false;
+    }
+    // Flatten the top-level params and every entry's params into one list, then let
+    // collectSuppliedResources pick out the tx-resource + primary valueSet/codeSystem.
+    const allParams = [];
+    for (const p of params.parameter) {
+      if (p.name === 'validation' && p.resource && Array.isArray(p.resource.parameter)) {
+        allParams.push(...p.resource.parameter);
+      } else {
+        allParams.push(p);
+      }
+    }
+    const { txResources, primaryResources } = this.collectSuppliedResources({ parameter: allParams });
+    const pool = txResources.concat(primaryResources);
+    if (pool.length > 0) {
+      cache.add(cacheId, pool);
+    }
+    return true;
+  }
+
   /**
    * Build an OperationOutcome
    */

package/tx/workers/cache-control.js

@@ -124,17 +124,46 @@ class CacheControlWorker extends TerminologyWorker {
     const { txResources, primaryResources } = this.collectSuppliedResources(params.jsonObj);
     const resources = txResources.concat(primaryResources);
 
+    // `sealed` controls whether the cache may grow after creation. When sealed,
+    // the cache holds only the resources front-loaded here; when unsealed, later
+    // operations accumulate every resource they see into it (see
+    // setupAdditionalResources).
+    //
+    // NOTE: the protocol default is `true`, but the server default here is
+    // deliberately `false` during the transition: existing clients that rely on
+    // incremental population and do not yet send `sealed` must keep working.
+    // Flip this to default-true once all clients send an explicit value.
+    const sealed = this.readSealed(params.jsonObj);
+
     const cacheId = crypto.randomUUID();
-    cache.set(cacheId, resources);
+    cache.set(cacheId, resources, sealed);
 
     return res.status(200).json({
       resourceType: 'Parameters',
       parameter: [
-        { name: 'cache-id', valueId: cacheId }
+        { name: 'cache-id', valueId: cacheId },
+        { name: 'sealed', valueBoolean: sealed }
       ]
     });
   }
 
+  /**
+   * Read the `sealed` boolean from the start request's Parameters.
+   *
+   * Server-side default is FALSE (transitional — see start()): a cache is only
+   * sealed if the client explicitly asks for it. Accepts a real JSON boolean or
+   * the string "true"/"false" for robustness across clients.
+   *
+   * @param {Object} params - Parameters resource (jsonObj)
+   * @returns {boolean}
+   */
+  readSealed(params) {
+    const p = this.findParameter(params, 'sealed');
+    if (!p) return false;
+    const v = this.getParameterValue(p);
+    return v === true || v === 'true';
+  }
+
   /**
    * mode=end: release the cache named by the `${CACHE_ID_HEADER}` header so the
    * server can reclaim it now rather than waiting for the idle timeout.