fhirsmith 0.13.1 → 0.13.3

package/CHANGELOG.md

@@ -5,6 +5,49 @@ 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).
 
+## [v0.13.3] - 2026-09-10
+
+### Fixed
+
+- Fix SNOMED CT display selection on national editions. `_displayRefsetOrder()` knew a display
+  language reference set for only six editions (International, US, UK and the test edition);
+  every other edition fell through to "the first description marked Preferred in any language
+  reference set", which on a multi-language edition means whichever description happened to be
+  stored first. The Belgian edition (11000172109) marks a Preferred synonym in Belgian French
+  (21000172104) and Belgian Dutch (31000172101) as well as in English, so a request that named
+  no `displayLanguage` got French for one concept, Dutch for the next and English for a third.
+  Editions not in the table now default to US then GB English, and the $lookup designation
+  order ranks the edition's display reference set ahead of "preferred anywhere", so the choice
+  no longer depends on import order. An edition with no English language reference set at all
+  still falls back to its own preferred synonym. This changes one tx-ecosystem expectation:
+  `bugs/sct-display-2` recorded "Counselling" for 409063005 on the International edition, which
+  is the GB English preferred term picked only because it is stored before the US one - the same
+  concept already expanded as "Counseling". The expectation is now "Counseling".
+- Fix the language tag on the display designation in $expand. It was hard-coded to `en-US`
+  while its value came from the edition display, so on a multi-language edition a French or
+  Dutch term was published as English - which put it in an implementation guide's English
+  display column and made the real French designation read as a duplicate of it.
+
+### Tx Conformance Statement
+
+FHIRsmith passed all 3507 HL7 terminology service tests (modes tx.fhir.org+omop+general+snomed+mimetypes+icd-11, tests v1.9.5-SNAPSHOT, runner v6.10.4
+
+## [v0.13.2] - 2026-09-05
+
+### Added
+
+- Add support for publishLibrarySource
+- 
+### Fixed
+
+- Fix error in Snomed CT and ICD-11 where normal form difference and case difference being conflated 
+- Fix error in mime-type subsumption analysis 
+- adjust mime type validation to not be case sensitive
+
+### Tx Conformance Statement
+
+FHIRsmith passed all 3507 HL7 terminology service tests (modes tx.fhir.org+omop+general+snomed+mimetypes+icd-11, tests v1.9.5-SNAPSHOT, runner v6.10.4)
+
 ## [v0.13.1] - 2026-09-05
 
 ### Fixed 

package/config-template.json

@@ -94,7 +94,14 @@
       // (>100MB). Only applies to websites whose publish-setup.json has $.website.github = true.
       // Omit to leave them in place - the push will then fail. Relative paths resolve under the
       // publisher data folder
-      "large-file-archive": "/absolute/path/to/large-file-archive"
+      "large-file-archive": "/absolute/path/to/large-file-archive",
+      // where to clone the IG registry from. Omit for the default,
+      // git@github.com:FHIR/ig-registry.git. Set this to an ssh_config Host alias when the
+      // server should push the registry with a repo-scoped deploy key instead of an account
+      // key - e.g. "git@github-ig-registry:FHIR/ig-registry.git", with a matching Host block
+      // in the service user's ~/.ssh/config carrying IdentityFile and IdentitiesOnly yes.
+      // The alias is what lets ssh tell this remote apart from the website remote.
+      "ig-registry-url": "git@github.com:FHIR/ig-registry.git"
     },
     "npmprojector": {
       "enabled": true,
@@ -150,6 +157,11 @@
     "tx": {
       "enabled": false,
       "librarySource": "/absolute/path/to/library.yml",
+      // publish the library source above at <endpoint>/library, so users can see what this
+      // server actually loads. One URL, content negotiated: a browser gets a formatted page
+      // (and a "Library" item in the tx nav bar), anything else gets the YAML file itself.
+      // Off by default - the file names every database, cache and package the server runs.
+      "publishLibrarySource": false,
       "cacheTimeout": 30,
       "expansionCacheSize": 1000,
       "expansionCacheMemoryThreshold": 0,

package/library/html-server.js

@@ -80,7 +80,9 @@ class HtmlServer {
       .replace(/\[%fhir-version%\]/g, escape(renderOptions.fhirversion))
       .replace(/\[%ms%\]/g, escape(renderOptions.processingTime.toString()))
       .replace(/\[%sponsorMessage%\]/g, sponsorMessage)
-      .replace(/\[%about%\]/g, renderOptions.about || '');
+      .replace(/\[%about%\]/g, renderOptions.about || '')
+      // raw HTML, like [%about%]: the caller decides whether the nav item exists at all
+      .replace(/\[%library-link%\]/g, renderOptions.libraryLink || '');
     
     // Handle any custom template variables
     if (options.templateVars) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fhirsmith",
-  "version": "0.13.1",
-  "txVersion": "1.9.4",
+  "version": "0.13.3",
+  "txVersion": "1.9.5-SNAPSHOT",
   "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.3.0",
+    "fhir-validator-wrapper": "1.4.0",
     "fhirpath": "^4.8.3",
     "fs-extra": "^11.3.3",
     "ini": "^6.0.0",

package/publisher/publisher.js

@@ -1117,8 +1117,15 @@ class PublisherModule {
     // Step 1: Clone supporting repositories into the task directory
     const registryDir = path.join(taskDir, 'ig-registry');
 
-    await this.runCommand('git', ['clone', 'git@github.com:FHIR/ig-registry.git', registryDir],
-        {}, task.id, 'Cloning ig-registry');
+    // The URL is configurable so that the credential arrangement can live in server config
+    // rather than here. A deployment that pushes ig-registry with a repo-scoped deploy key
+    // rather than an account key points this at an ssh_config Host alias carrying that key,
+    // e.g. git@github-ig-registry:FHIR/ig-registry.git - the alias is the only way ssh can
+    // tell this remote apart from the website remote, both being github.com.
+    const igRegistryUrl = this.config['ig-registry-url'] || 'git@github.com:FHIR/ig-registry.git';
+
+    await this.runCommand('git', ['clone', igRegistryUrl, registryDir],
+        {}, task.id, 'Cloning ig-registry from ' + igRegistryUrl);
 
     // Use website-configured history templates path if provided, otherwise clone the default repo
     let historyDir;

package/translations/Messages.properties

@@ -97,6 +97,7 @@ CDA_UNKNOWN_TEMPLATE_EXT = The CDA Template {0} / {1} is not known
 CDATA_is_not_allowed = CDATA is not allowed
 Circular_snapshot_references_detected_cannot_generate_snapshot_stack__ = Circular snapshot references detected; cannot generate snapshot (stack = {0})
 CODE_CASE_DIFFERENCE = The code ''{0}'' differs from the correct code ''{1}'' by case. Although the code system ''{2}'' is case insensitive, implementers are strongly encouraged to use the correct case anyway
+CODE_NOT_IN_NORMAL_FORM = The code ''{0}'' is valid, but it is not the normal form for the code system ''{2}''; the normal form is ''{1}''
 Code_found_in_expansion_however_ = Code found in expansion, however: {0}
 CODESYSTEM_CONCEPT_NO_DEFINITION = HL7 Defined CodeSystems should ensure that every concept has a definition
 CODESYSTEM_CONCEPT_NO_DISPLAY = HL7 Defined CodeSystems should ensure that every concept has a display

package/tx/README.md

@@ -25,6 +25,7 @@ Add the `tx` section to your `config.json`:
     "tx": {
       "enabled": true,
       "librarySource": "/path/to/library.yml",
+      "publishLibrarySource": false,
       "cacheTimeout": 30,
       "internalLimit" : 10000,
       "externalLimit" : 1000,
@@ -66,6 +67,7 @@ Add the `tx` section to your `config.json`:
 | `expansionCacheSize`            | integer | No       | Maximum number of expanded ValueSets to cache. Default: 1000                                            |
 | `expansionCacheMemoryThreshold` | integer | No       | Heap memory usage in MB that triggers evicting oldest half of expansion cache. 0 = disabled. Default: 0 |
 | `librarySource`                 | string  | Yes      | Path to the YAML file that defines the terminology sources to load                                      |
+| `publishLibrarySource`          | boolean | No       | Publish that YAML file at `/{path}/library`. Default: false                                             |
 | `internalLimit`                 | integer | No       | Largest number of codes in internal expansions                                                          |
 | `externalLimit`                 | integer | No       | Largest number of codes the server will return in an expansion                                          |
 | `endpoints`                     | array   | Yes      | List of endpoint configurations (at least one required)                                                 |
@@ -125,6 +127,26 @@ Each endpoint provides the following FHIR terminology operations:
 Each endpoint also provides:
 - `GET /{path}/metadata` - Returns a CapabilityStatement describing the endpoint's capabilities
 - `GET /{path}/` - Returns basic endpoint information
+- `GET /{path}/library` - Returns the library source YAML, if `publishLibrarySource` is set
+
+### Publishing the library source
+
+`publishLibrarySource` lets users see what the server actually loads. It is off by default,
+because the library YAML names every database, cache and package the server runs, and not
+every deployment wants that public. Turn it on and each endpoint serves the file at
+`/{path}/library`, and a **Library** item appears in the tx navigation bar.
+
+There is one URL, content negotiated the same way the rest of the module negotiates:
+
+| Request | Response |
+|---------|----------|
+| `Accept: text/html` (i.e. a browser) | the file, syntax highlighted, in the tx page template |
+| anything else | the file itself, as `application/yaml` |
+| `?_format=html` / `?_format=yaml` | forces either representation |
+
+The file is read from disk per request, so editing it is reflected immediately - note that
+this means the published file can be ahead of what the running server actually loaded, if it
+has been edited since startup.
 
 ## Library Configuration
 

package/tx/cs/cs-mimetypes.js

@@ -36,6 +36,99 @@ const { Issue } = require("../library/operation-outcome");
  */
 const UNDERSTOOD_PARAMETERS = new Set(['charset', 'format', 'delsp', 'version']);
 
+/**
+ * Parameters whose VALUES are case-insensitive.
+ *
+ * RFC 2045 section 5.1 makes type, subtype and parameter names case-insensitive, and then says
+ * of values: "Parameter values are normally case sensitive, but sometimes are interpreted in a
+ * case-insensitive fashion, depending on the intended use." So a value is only folded where its
+ * own definition says to fold it, and this is the list of those we know of:
+ *
+ *  - charset  RFC 2046 section 4.1.2: "Unlike some other parameter values, the values of the
+ *             charset parameter are NOT case sensitive." (RFC 9110 section 8.3.2 agrees.)
+ *  - format   RFC 3676 section 4, of Format and DelSp together: "(Neither the parameter names
+ *  - delsp    nor values are case sensitive.)"
+ *
+ * `version` is deliberately absent: there is no general definition of a version parameter -
+ * it exists only per-registration (text/vcard has one, text/html deliberately removed one) -
+ * so there is nothing that says its values fold, and folding them could equate two versions
+ * that a registration means to distinguish.
+ *
+ * @type {Set<string>}
+ */
+const CASE_INSENSITIVE_VALUES = new Set(['charset', 'format', 'delsp']);
+
+/**
+ * Media types whose registration gives a parameter a DEFAULT value.
+ *
+ * This is the thing that breaks the otherwise tidy rule that a parameter narrows a media type.
+ * Where a parameter has a default, the bare form is not the general case - it already carries
+ * that value - so `text/plain` does not subsume `text/plain; charset=utf-8`, the two are
+ * different things. Applying the default to whichever side omits it, and then comparing as
+ * usual, gets this right in both directions: it also makes `text/plain` and
+ * `text/plain; charset=us-ascii` come out equivalent, which they are and which we used to
+ * get wrong in the other direction.
+ *
+ * There is no list to load this from. IANA's registry schema has no parameter element at all -
+ * a record is a name, a deprecation flag, cross-references and a pointer to a template - and
+ * defaults live only in the prose of each defining RFC. `text/plain`, the type that needs this
+ * most, has no IANA registration template whatsoever ("No registration template available"),
+ * so all of the below comes from the RFCs directly:
+ *
+ *  - text/plain charset: RFC 2046 section 4.1.2 made US-ASCII the default, and RFC 6657
+ *    section 4 exists specifically to say it stayed: "The default "charset" parameter value
+ *    for "text/plain" is unchanged from [RFC2046] and remains as "US-ASCII"."
+ *  - text/plain format and delsp: RFC 3676 section 4, "If Format is not specified, or if the
+ *    value is not recognized, a value of Fixed is assumed" and "If DelSp is not specified, or
+ *    if its value is not recognized, a value of No is assumed."
+ *  - text/vcard charset: RFC 6350 section 3.1, "The charset ... for vCard is UTF-8 ... There is
+ *    no way to override this." A default expressed as a prohibition, but a default.
+ *
+ * Keyed by lower-case type/subtype; the inner map is lower-case parameter name to the value
+ * the bare form implies. Values are stored folded, matching CASE_INSENSITIVE_VALUES.
+ *
+ * @type {Map<string, Map<string, string>>}
+ */
+const PARAMETER_DEFAULTS = new Map([
+  ['text/plain', new Map([['charset', 'us-ascii'], ['format', 'fixed'], ['delsp', 'no']])],
+  ['text/vcard', new Map([['charset', 'utf-8']])]
+]);
+
+/**
+ * text/* types whose registration says explicitly that charset has NO default.
+ *
+ * RFC 6657 section 3 left a residual rule behind that is the awkward part of all this:
+ * "existing "text/*" registrations that fail to specify how the charset is determined still
+ * default to US-ASCII." So for a text/* type, silence in the registration is not the absence
+ * of a default - it IS a default, of US-ASCII. That set cannot be enumerated without reading
+ * every legacy text/* registration and judging whether it "clearly specifies", so instead of
+ * guessing, charset on an unlisted text/* type yields cannot-determine.
+ *
+ * This set is the escape hatch: text/* types we have actually read, which say there is no
+ * default, and for which the narrowing rule therefore holds.
+ *
+ *  - text/markdown: RFC 7763 section 2, "charset: Per Section 4.2.1 of [RFC6838], charset is
+ *    REQUIRED. There is no default value because neither [MDSYNTAX] nor many popular
+ *    implementations at the time of this registration do either."
+ *  - text/html: a judgement rather than a quoted default, and the only entry here that is.
+ *    Neither registration states one - RFC 2854 section 6 recites the RFC 2046 and RFC 2616
+ *    rules, observes that they conflict, and only recommends being explicit; the current IANA
+ *    registration is the W3C one, whose whole optional-parameters text is that charset
+ *    "may be provided to definitively specify the document's character encoding, overriding
+ *    any character encoding declarations in the document". HTML determines its encoding in
+ *    band, and the phrase "overriding any character encoding declarations in the document"
+ *    only makes sense if the absence of the parameter means "whatever the document says"
+ *    rather than "US-ASCII". Listed because text/html is the most asked-about media type
+ *    there is, and declining to answer for it is a poor trade for a defensible reading.
+ *
+ * Non-text types need no entry: RFC 6657 is a text/* rule, so silence elsewhere really is
+ * silence (application/xml, for instance - RFC 7303 section 3.2 tells consumers they "SHOULD
+ * NOT assume a default encoding").
+ *
+ * @type {Set<string>}
+ */
+const TEXT_TYPES_WITH_NO_CHARSET_DEFAULT = new Set(['text/markdown', 'text/html']);
+
 // The IANA media types registry. Only the names are kept - the registry is a few MB of
 // cross-references and templates, and all the `registered` filter asks is whether a type is in it
 const IANA_MEDIA_TYPES_URL = 'https://www.iana.org/assignments/media-types/media-types.xml';
@@ -46,6 +139,63 @@ class MimeTypeConcept {
   constructor(code) {
     this.code = code;
     this.mimeType = this.#parseMimeType(code);
+    this.normalized = this.#normalize(code);
+  }
+
+  /**
+   * The canonical spelling of this media type.
+   *
+   * Four things are canonicalised, and each is something the specs say carries no meaning:
+   *
+   *  - case, in the type, the subtype, every parameter name, and the values of the parameters
+   *    in CASE_INSENSITIVE_VALUES (RFC 2045 section 5.1, RFC 2046 section 4.1.2, RFC 3676
+   *    section 4). Every other parameter value keeps its case: RFC 2045 makes values
+   *    case-sensitive unless their own definition says otherwise, and a boundary or a profile
+   *    URI can genuinely differ by case
+   *  - parameter ORDER, which is not significant, so sorting by name gives two spellings of one
+   *    media type one spelling. Without this, `text/plain; charset=utf-8; format=flowed` and
+   *    `text/plain; format=flowed; charset=utf-8` would have two different "normal" forms,
+   *    which is not a normal form at all
+   *  - the separator, which becomes '; '
+   *  - surrounding and internal padding
+   *
+   * Quoting is NOT canonicalised. A quoted value can always be written quoted, so removing the
+   * quotes needs to know that the value contains no tspecials, and getting that wrong produces
+   * a "canonical" form that is not a legal media type. Left for someone who needs it.
+   *
+   * Note the consequence for validation: reordering or respacing makes this differ from the
+   * submitted code by more than case, so it is reported as a normal-form difference rather
+   * than a case difference. That is the honest description of what changed.
+   */
+  #normalize(code) {
+    if (!this.mimeType.isValid) {
+      return code;
+    }
+    const segments = code.split(';');
+    const params = [];
+    for (const segment of segments.slice(1)) {
+      const trimmed = segment.trim();
+      if (trimmed === '') {
+        continue;
+      }
+      const eq = trimmed.indexOf('=');
+      if (eq === -1) {
+        // not a name=value pair. The parser ignores it, but dropping it here would make the
+        // canonical form say something the submitted code did not, so it is carried through -
+        // untouched, since only parameter NAMES fold and nothing says this is one
+        params.push({ name: trimmed.toLowerCase(), text: trimmed });
+        continue;
+      }
+      const name = trimmed.slice(0, eq).trim().toLowerCase();
+      const value = trimmed.slice(eq + 1).trim();
+      params.push({
+        name: name,
+        text: name + '=' + (CASE_INSENSITIVE_VALUES.has(name) ? value.toLowerCase() : value)
+      });
+    }
+    // by name, then by the whole parameter, so a repeated name is still ordered predictably
+    params.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : (a.text < b.text ? -1 : a.text > b.text ? 1 : 0)));
+    return [segments[0].trim().toLowerCase(), ...params.map(p => p.text)].join('; ');
   }
 
   #parseMimeType(code) {
@@ -71,7 +221,7 @@ class MimeTypeConcept {
       if (value.length > 1 && value.startsWith('"') && value.endsWith('"')) {
         value = value.slice(1, -1);
       }
-      if (name === 'charset') {
+      if (CASE_INSENSITIVE_VALUES.has(name)) {
         value = value.toLowerCase();
       }
       if (name) {
@@ -196,7 +346,7 @@ class MimeTypeServices extends CodeSystemProvider {
   async code(code) {
     
     const ctxt = await this.#ensureContext(code);
-    return ctxt ? ctxt.code : null;
+    return ctxt ? ctxt.normalized : null;
   }
 
   async display(code) {
@@ -206,14 +356,15 @@ class MimeTypeServices extends CodeSystemProvider {
       return null;
     }
 
-    // Check supplements first
-    const suppDisplay = this._displayFromSupplements(ctxt.code);
+    // Check supplements first, by the normalised code - a supplement that designates
+    // 'text/plain' has to be found for a request that spells it 'TEXT/Plain'
+    const suppDisplay = this._displayFromSupplements(ctxt.normalized);
     if (suppDisplay) {
       return suppDisplay;
     }
 
-    // Default display is the code itself, trimmed
-    return ctxt.code.trim();
+    // Default display is the code itself, normalised and trimmed
+    return ctxt.normalized.trim();
   }
 
   async definition(code) {
@@ -314,11 +465,27 @@ class MimeTypeServices extends CodeSystemProvider {
       return 'not-subsumed';
     }
 
+    // Where the registration gives a parameter a default, the bare form already carries that
+    // value, so fill it in on both sides before comparing anything. After this, a parameter
+    // that defaults is present on both sides and the narrowing logic below never sees it as
+    // "added" - which is the point: adding format=flowed to text/plain does not narrow it, it
+    // contradicts the format=fixed the bare form meant all along.
+    const key = a.type + '/' + a.subtype;
+    const defaults = PARAMETER_DEFAULTS.get(key);
+    const aParams = new Map(a.params);
+    const bParams = new Map(b.params);
+    if (defaults) {
+      for (const [name, value] of defaults) {
+        if (!aParams.has(name)) aParams.set(name, value);
+        if (!bParams.has(name)) bParams.set(name, value);
+      }
+    }
+
     // Only the parameters the two codes DISAGREE on can decide the answer - one present
     // on one side only, or present on both with different values. A parameter carried
     // identically by both, understood or not, cannot affect the result and is ignored.
-    const deciding = [...new Set([...a.params.keys(), ...b.params.keys()])]
-      .filter(name => a.params.get(name) !== b.params.get(name));
+    const deciding = [...new Set([...aParams.keys(), ...bParams.keys()])]
+      .filter(name => aParams.get(name) !== bParams.get(name));
     const unknown = deciding.filter(name => !UNDERSTOOD_PARAMETERS.has(name));
     if (unknown.length > 0) {
       throw cannotDetermineSubsumption(
@@ -331,15 +498,34 @@ class MimeTypeServices extends CodeSystemProvider {
         + 'that may be wrong');
     }
 
+    // RFC 6657 section 3: a text/* registration that does not say how the charset is determined
+    // still defaults to US-ASCII. So on a text/* type we have not read, we do not know whether
+    // the side without a charset means "any charset" or "US-ASCII", and that is exactly the
+    // difference between subsumes and not-subsumed. Only bites when charset is present on one
+    // side and absent on the other - two explicit values are just two values.
+    if (deciding.includes('charset') && a.type === 'text'
+        && !(defaults && defaults.has('charset'))
+        && !TEXT_TYPES_WITH_NO_CHARSET_DEFAULT.has(key)
+        && aParams.has('charset') !== bParams.has('charset')) {
+      throw cannotDetermineSubsumption(
+        `Unable to determine the subsumption relationship between '${a.source}' and `
+        + `'${b.source}': one carries a charset and the other does not, and this server does `
+        + `not know whether '${key}' gives charset a default value. RFC 6657 leaves every `
+        + 'text/* registration that does not say how the charset is determined defaulting to '
+        + 'US-ASCII, so the absence of a charset may mean "any charset" or may mean "US-ASCII", '
+        + 'and those give opposite answers. No outcome is returned rather than one that may be '
+        + 'wrong');
+    }
+
     // Any parameter they both carry has to agree, or neither includes the other
-    for (const [name, value] of a.params) {
-      if (b.params.has(name) && b.params.get(name) !== value) {
+    for (const [name, value] of aParams) {
+      if (bParams.has(name) && bParams.get(name) !== value) {
         return 'not-subsumed';
       }
     }
 
-    const aInB = [...a.params.keys()].every(name => b.params.has(name));
-    const bInA = [...b.params.keys()].every(name => a.params.has(name));
+    const aInB = [...aParams.keys()].every(name => bParams.has(name));
+    const bInA = [...bParams.keys()].every(name => aParams.has(name));
 
     if (aInB && bInA) {
       return 'equivalent';

package/tx/cs/cs-snomed.js

@@ -28,6 +28,21 @@ const {debugLog} = require("../operation-context");
 // shared - it simply recomputes.
 const SNOMED_FILTER_ANALYSIS = Symbol('snomedFilterAnalysis');
 
+// Description language index -> language code. The index is assigned at import
+// time by SnomedImporter.mapLanguageCode(); this table is its inverse and must
+// be kept in step with it.
+const SCT_LANGUAGE_CODES = {
+  1: 'en',
+  2: 'fr',
+  3: 'nl',
+  4: 'es',
+  5: 'sv',
+  6: 'da',
+  7: 'de',
+  8: 'it',
+  9: 'cs'
+};
+
 // Context kinds matching Pascal enum
 const SnomedProviderContextKind = {
   CODE: 0,
@@ -346,8 +361,20 @@ class SnomedServices {
   // preferred synonym in more than one dialect at once (the International
   // edition ships both US English 509007 and GB English 508004, each marking a
   // different synonym Preferred). The edition default decides which term is
-  // shown. Editions not listed here fall back to "preferred synonym in any
-  // language refset" (the historical behaviour), so no edition regresses.
+  // shown.
+  //
+  // Editions not listed here default to English (US then GB) rather than to
+  // "preferred synonym in any language refset". A national edition carries a
+  // Preferred synonym in each of its own language refsets as well as in English
+  // (e.g. the Belgian edition 11000172109 marks a French term Preferred in
+  // 21000172104 and a Dutch one in 31000172101), so "any refset" resolved to
+  // whichever description happened to be stored first - French for one concept,
+  // Dutch for the next, English for a third. A caller who asked for no
+  // particular language got an arbitrary mix. English is the only defensible
+  // default: it is the one language every edition has, and it is what a request
+  // with no displayLanguage is taken to mean everywhere else in the server. An
+  // edition with no English at all still falls through to the any-refset step
+  // below, so nothing regresses.
   _displayRefsetOrder() {
     if (this._dispOrder) return this._dispOrder;
     const idx = (id) => { const r = this.concepts.findConcept(id); return r.found ? r.index : -1; };
@@ -361,7 +388,7 @@ class SnomedServices {
       '83821000000107': [GB],           // UK Edition
       '999000021000000109': [GB]        // UK Clinical Edition
     };
-    const ids = byEdition[String(this.edition)] || [];
+    const ids = byEdition[String(this.edition)] || [US, GB];
     this._dispOrder = ids.map(idx).filter((i) => i >= 0);
     return this._dispOrder;
   }
@@ -400,59 +427,80 @@ class SnomedServices {
     return false;
   }
 
-  // Return a concept's display: the synonym marked Preferred in the US English
-  // language reference set; failing that the FSN; failing that the first active
-  // description. Previously this returned the first active description outright,
-  // which is only the preferred term by accident of import order.
-  getDisplayName(reference = 0) {
+  // Return a concept's display, together with the language it is actually in:
+  // the synonym marked Preferred in the edition's display language reference
+  // set; failing that a preferred synonym in any language refset; failing that
+  // the FSN; failing that the first active description. Previously this
+  // returned the first active description outright, which is only the preferred
+  // term by accident of import order.
+  //
+  // The language matters as much as the term: the display is emitted as a
+  // designation (DesignationUse.DISPLAY) during $expand, and tagging a French
+  // term as en-US puts it in an IG's English display column and makes the real
+  // French designation look like a duplicate.
+  //
+  // Returns {term, lang} - lang is a language code, or null when no description
+  // could be read.
+  getDisplayNameEx(reference = 0) {
+    const none = { term: '', lang: null };
     try {
       const concept = this.concepts.getConcept(reference);
       const descriptionsRef = concept.descriptions;
 
       if (descriptionsRef === 0) {
-        return '';
+        return none;
       }
 
       const descriptionIndices = this.refs.getReferences(descriptionsRef);
       const K = this._displayConstants();
+      const pick = (description) => ({
+        term: this.strings.getEntry(description.iDesc).trim(),
+        lang: SCT_LANGUAGE_CODES[description.lang] || 'en'
+      });
 
       // 1. Preferred synonym in the edition's default display refset(s), tried
       //    in priority order. This is what disambiguates dialects: on the
       //    International edition a concept may be Preferred in both US and GB
-      //    English, and the edition default (US English) must win.
+      //    English, and the edition default (US English) must win. It is also
+      //    what keeps a multi-language national edition from picking a
+      //    different language for each concept.
       for (const refsetIdx of this._displayRefsetOrder()) {
         for (const descIndex of descriptionIndices) {
           const description = this.descriptions.getDescription(descIndex);
           if (!description.active || description.kind !== K.synonym) continue;
           if (this._descAcceptability(description, refsetIdx) === K.preferred) {
-            return this.strings.getEntry(description.iDesc).trim();
+            return pick(description);
           }
         }
       }
 
       // 2. Fallback: preferred synonym in ANY language refset; then FSN; then
-      //    the first active description. Used for editions without a mapped
-      //    default refset, and for concepts with no preferred synonym there.
-      let fsnTerm = '';
-      let firstActive = '';
+      //    the first active description. Reached only by editions with no
+      //    English language refset at all, and by concepts with no preferred
+      //    synonym in the edition's display refsets.
+      let fsn = null;
+      let firstActive = null;
       for (const descIndex of descriptionIndices) {
         const description = this.descriptions.getDescription(descIndex);
         if (!description.active) continue;
-        const term = this.strings.getEntry(description.iDesc).trim();
-        if (firstActive === '') firstActive = term;
+        if (firstActive === null) firstActive = pick(description);
         if (this._synonymIsPreferred(description)) {
-          return term; // preferred synonym (any English language refset)
+          return pick(description); // preferred synonym (any language refset)
         }
-        if (description.kind === K.fsn && fsnTerm === '') {
-          fsnTerm = term;
+        if (description.kind === K.fsn && fsn === null) {
+          fsn = pick(description);
         }
       }
-      return fsnTerm || firstActive || '';
+      return fsn || firstActive || none;
     } catch (error) {
-      return '';
+      return none;
     }
   }
 
+  getDisplayName(reference = 0) {
+    return this.getDisplayNameEx(reference).term;
+  }
+
   getConceptDescendants(reference) {
     try {
       const allDescRef = this.concepts.getAllDesc(reference);
@@ -1687,8 +1735,16 @@ class SnomedProvider extends BaseCSServices {
                   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);
+              // Tagged with the language the term is actually in, not a
+              // hard-coded en-US: on a multi-language edition the edition
+              // display can be French or Dutch, and mislabelling it as English
+              // is what puts it in an IG's English display column and makes the
+              // real French designation look like a duplicate of it. English
+              // stays 'en-US' (the term comes from the US English language
+              // reference set), so nothing changes for English editions.
+              const display = this.sct.getDisplayNameEx(ctxt.getReference());
+              const displayLang = (!display.lang || display.lang === 'en') ? 'en-US' : display.lang;
+              if (display.term) displays.addDesignation(true, 'active', displayLang, null, display.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
@@ -1697,14 +1753,31 @@ class SnomedProvider extends BaseCSServices {
               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).
+              // $lookup: emit every description. Order matters only for the
+              // display: a request with no displayLanguage takes the first
+              // designation Designations._isPreferred() accepts, which is any
+              // SNOMED synonym. Ranking by the edition's display language
+              // reference set first (rather than by "preferred in any refset")
+              // keeps that pick in one language - otherwise a national edition
+              // answers $lookup in French for one concept and Dutch for the
+              // next, depending on description storage order.
+              const K2 = this.sct._displayConstants();
+              const displayRefsets = this.sct._displayRefsetOrder();
+              // Buckets: 0 = preferred in the edition's display refset, 1 =
+              // preferred in some other language refset, 2 = everything else
+              // (FSNs and acceptable synonyms, left in their original order -
+              // Array.sort is stable, so nothing else about the output moves).
+              const rank = (description) => {
+                if (description.kind !== K2.synonym) return 2;
+                for (const refsetIdx of displayRefsets) {
+                  if (this.sct._descAcceptability(description, refsetIdx) === K2.preferred) return 0;
+                }
+                return this.sct._synonymIsPreferred(description) ? 1 : 2;
+              };
               const orderedIndices = descriptionIndices.slice().sort((a, b) => {
                 const da = this.sct.descriptions.getDescription(a);
                 const db = this.sct.descriptions.getDescription(b);
-                const pa = this.sct._synonymIsPreferred(da) ? 0 : 1;
-                const pb = this.sct._synonymIsPreferred(db) ? 0 : 1;
-                return pa - pb;
+                return rank(da) - rank(db);
               });
               for (const descIndex of orderedIndices) {
                 const description = this.sct.descriptions.getDescription(descIndex);
@@ -1733,18 +1806,7 @@ class SnomedProvider extends BaseCSServices {
   }
 
   getLanguageCode(langIndex) {
-    const languageMap = {
-      1: 'en',
-      2: 'fr',
-      3: 'nl',
-      4: 'es',
-      5: 'sv',
-      6: 'da',
-      7: 'de',
-      8: 'it',
-      9: 'cs'
-    };
-    return languageMap[langIndex] || 'en';
+    return SCT_LANGUAGE_CODES[langIndex] || 'en';
   }
 
   // Lookup methods

package/tx/html/tx-template.html

@@ -90,6 +90,7 @@
             <a href="[%endpoint-path%]/metadata?mode=terminology" style="color: gold">Terminology Capabilities</a>  &nbsp;|&nbsp;
             <a href="[%endpoint-path%]/op.html" style="color: gold">Operations</a>  &nbsp;|&nbsp;
             <a href="[%endpoint-path%]/problems.html" style="color: gold">Problems</a>  &nbsp;|&nbsp;
+            [%library-link%]
   &nbsp;
 		</div>
 		</div>

package/tx/sct/expressions.js

@@ -537,18 +537,40 @@ class SnomedExpressionParser {
 
   /**
    * Parse refinements for an expression
+   *
+   * The compositional grammar ABNF is
+   *   refinement   = (attributeSet / attributeGroup) *( ws ["," ws] attributeGroup )
+   *   attributeSet = attribute *(ws "," ws attribute)
+   * so a comma is required between the ungrouped attributes of the attribute set, but is
+   * OPTIONAL before an attribute group. Requiring it everywhere rejected the minimal
+   * rendering this parser's own renderer produces (e.g. 249943000:260868000=6934004{...}).
+   *
+   * We stay liberal in what we accept: a group may also be followed by further ungrouped
+   * attributes, which the ABNF does not allow but which this parser has always taken.
    */
   refinements(expr) {
-    let next = true;
-    while (next) {
-      if (this.peek() !== '{') {
-        expr.refinements.push(this.attribute());
-      } else {
+    this.ws();
+
+    let first = true;
+    for (;;) {
+      if (!first) {
+        const mark = this.cursor;
+        const comma = this.gchar(',');
+        this.ws();
+        if (this.peek() !== '{' && !comma) {
+          // neither a separating comma nor a group: the refinements are finished
+          this.cursor = mark;
+          break;
+        }
+      }
+
+      if (this.peek() === '{') {
         expr.refinementGroups.push(this.attributeGroup());
+      } else {
+        expr.refinements.push(this.attribute());
       }
       this.ws();
-      next = this.gchar(',');
-      this.ws();
+      first = false;
     }
   }
 
@@ -2444,10 +2466,13 @@ class SnomedExpressionServices {
         }
       }
 
-      // Grouped refinements
+      // Grouped refinements. The comma between the attribute set and the first group is
+      // optional in the grammar, but we emit it: it is what makes the boundary between the
+      // ungrouped attributes and the first group legible, and it is the safer of the two
+      // spellings to hand to a third-party parser.
       if (expr.hasRefinementGroups()) {
         for (let j = 0; j < expr.refinementGroups.length; j++) {
-          if (j > 0) parts.push(',');
+          if (j > 0 || expr.hasRefinements()) parts.push(',');
           parts.push('{');
 
           for (let i = 0; i < expr.refinementGroups[j].refinements.length; i++) {

package/tx/tx-html.js

@@ -86,6 +86,99 @@ function acceptsHtml(req) {
   return _fmt.includes('text/html');
 }
 
+// Whether this server publishes its library source YAML. Off unless the operator turns
+// modules.tx.publishLibrarySource on, and it gates both the route and the nav item, so a
+// server that does not publish it has no link to a 404.
+let publishLibrarySource = false;
+
+function setPublishLibrarySource(enabled) {
+  publishLibrarySource = enabled === true;
+}
+
+function publishesLibrarySource() {
+  return publishLibrarySource;
+}
+
+/**
+ * Highlight a YAML document for display.
+ *
+ * Deliberately line-oriented and modest: this is the operator's own source file, not a
+ * general YAML parser, and it has to survive anything a hand-edited file contains without
+ * ever emitting the file's bytes unescaped. Each line is split into its parts FIRST and
+ * every part is escaped before any markup goes near it, so no amount of angle brackets or
+ * ampersands in a value can break out.
+ */
+function highlightYaml(source) {
+  const lines = String(source).replace(/\r\n/g, '\n').split('\n');
+  const out = lines.map(line => {
+    if (line.trim() === '') {
+      return '';
+    }
+    // a whole-line comment
+    const wholeComment = /^(\s*)(#.*)$/.exec(line);
+    if (wholeComment) {
+      return escape(wholeComment[1]) + '<span class="y-c">' + escape(wholeComment[2]) + '</span>';
+    }
+    // split off a trailing comment, but only one introduced by whitespace-then-#, so a
+    // '#' inside a value (a FHIR fragment URL, say) stays part of the value
+    let body = line;
+    let comment = '';
+    const trailing = /^(.*?)(\s+#.*)$/.exec(line);
+    if (trailing) {
+      body = trailing[1];
+      comment = '<span class="y-c">' + escape(trailing[2]) + '</span>';
+    }
+
+    // a mapping key needs whitespace (or end of line) after the colon - without it the
+    // colon is just part of a scalar, which is exactly what a source line like
+    // '- internal:lang' or '- snomed!:sct_intl_20250201.cache' is
+    const m = /^(\s*)(-\s+)?([A-Za-z0-9_.$-]+)(:)(\s+|$)(.*)$/.exec(body);
+    if (m) {
+      return escape(m[1])
+        + (m[2] ? '<span class="y-d">' + escape(m[2]) + '</span>' : '')
+        + '<span class="y-k">' + escape(m[3]) + '</span>'
+        + '<span class="y-p">' + escape(m[4]) + '</span>'
+        + escape(m[5])
+        + (m[6] ? '<span class="y-v">' + escape(m[6]) + '</span>' : '')
+        + comment;
+    }
+    const item = /^(\s*)(-\s+)(.*)$/.exec(body);
+    if (item) {
+      return escape(item[1])
+        + '<span class="y-d">' + escape(item[2]) + '</span>'
+        + '<span class="y-v">' + escape(item[3]) + '</span>'
+        + comment;
+    }
+    return escape(body) + comment;
+  });
+  return out.join('\n');
+}
+
+const YAML_STYLE = '<style>' +
+  '.yaml-source { background: #f7f7f7; border: 1px solid #ddd; padding: 12px; overflow-x: auto; ' +
+  'font-family: Menlo, Consolas, monospace; font-size: 90%; line-height: 1.45; }' +
+  '.yaml-source .y-k { color: #0b5394; font-weight: bold; }' +
+  '.yaml-source .y-v { color: #444; }' +
+  '.yaml-source .y-p, .yaml-source .y-d { color: #999; }' +
+  '.yaml-source .y-c { color: #777; font-style: italic; }' +
+  '</style>';
+
+/**
+ * The page body for the library source: what the file is, where to get the raw bytes, and
+ * the file itself.
+ */
+function buildLibrarySourcePage(source, filename, endpointPath) {
+  return YAML_STYLE
+    + '<p>This is the library source this server loads its content from - the code system files, '
+    + 'the packages, and the terminology sources it makes available. It is shown here as it is on '
+    + 'disk.</p>'
+    + '<p>The same URL returns the file itself to anything that does not ask for HTML: '
+    + '<code>curl -H "Accept: application/yaml" ' + escape(endpointPath) + '/library</code>, or '
+    + '<a href="library?_format=yaml">' + escape(endpointPath) + '/library?_format=yaml</a>.</p>'
+    + '<p>Source file: <code>' + escape(filename) + '</code></p>'
+    + '<pre class="yaml-source">' + highlightYaml(source) + '</pre>';
+}
+
 
 class TxHtmlRenderer {
   renderer;
@@ -110,7 +203,10 @@ class TxHtmlRenderer {
       version: packageJson.version,
       endpointpath: endpoint.path,
       fhirversion: endpoint.fhirVersion,
-      ms: Date.now() - startTime
+      ms: Date.now() - startTime,
+      libraryLink: publishLibrarySource
+        ? '<a href="' + escape(endpoint.path) + '/library" style="color: gold">Library</a>  &nbsp;|&nbsp;'
+        : ''
     };
 
     return htmlServer.renderPage('tx', title, content, options);
@@ -244,7 +340,14 @@ class TxHtmlRenderer {
     html += await this.buildSearchForm(req);
 
     // ===== Packages and Factories Section =====
-    html += '<hr/><h3>Source Content</h3>';
+    // What follows is the loaded content; the library YAML is where it came from, so when
+    // the operator publishes it, link it from the heading over the list it produced.
+    html += '<hr/><h3>Source Content';
+    if (publishLibrarySource) {
+      html += ` <a href="${escape(this.path)}/library" style="font-size: 60%; font-weight: normal;"` +
+        ' title="The library source this server loaded this content from">source</a>';
+    }
+    html += '</h3>';
 
     // List Packages
     html += '<h6>FHIR Packages</h6>';
@@ -1371,5 +1474,6 @@ class TxHtmlRenderer {
 }
 
 module.exports = {
-  TxHtmlRenderer, loadTemplate, acceptsHtml
+  TxHtmlRenderer, loadTemplate, acceptsHtml,
+  setPublishLibrarySource, publishesLibrarySource, highlightYaml, buildLibrarySourcePage
 };

package/tx/tx.js

@@ -7,6 +7,7 @@
 
 const express = require('express');
 const path = require('path');
+const fs = require('fs');
 const Logger = require('../library/logger');
 const { Library } = require('./library');
 const { OperationContext, ResourceCache, ExpansionCache, debugLog} = require('./operation-context');
@@ -149,6 +150,10 @@ class TXModule {
     // Load HTML template
     txHtml.loadTemplate();
 
+    // Off unless the operator opts in. This gates the nav item as well as the route, so a
+    // server that does not publish its library source shows no link to it.
+    txHtml.setPublishLibrarySource(config.publishLibrarySource === true);
+
     // Validate config
     if (!config.librarySource) {
       throw new Error('TX module requires librarySource configuration');
@@ -956,6 +961,45 @@ class TXModule {
       }
     });
 
+    // The library source YAML - the file this server loaded its content from.
+    //
+    // Only registered when the operator turns modules.tx.publishLibrarySource on: the file
+    // names every database, cache and package the server runs, which some deployments are
+    // happy to publish and others are not, so it is opt-in rather than opt-out.
+    //
+    // One URL, negotiated: a browser (Accept: text/html) gets the highlighted page, anything
+    // else gets the file itself. ?_format=html and ?_format=yaml force either way, through the
+    // same acceptsHtml() the rest of the module uses.
+    if (this.config.publishLibrarySource === true) {
+      router.get('/library', async (req, res) => {
+        const start = Date.now();
+        try {
+          const filename = this.config.librarySource;
+          let source;
+          try {
+            source = await fs.promises.readFile(filename, 'utf8');
+          } catch (error) {
+            this.log.error(`Error reading library source ${filename}: ${error.message}`);
+            res.status(500).json(this.operationOutcome('error', 'exception',
+              'The library source is published by this server, but could not be read'));
+            return;
+          }
+          if (txHtml.acceptsHtml(req)) {
+            let txhtml = new TxHtmlRenderer(new Renderer(req.txOpContext, req.txProvider), this.liquid, this.languages, this.i18n, req.txEndpoint.path);
+            const content = txHtml.buildLibrarySourcePage(source, path.basename(filename), req.txEndpoint.path);
+            const html = await txhtml.renderPage('Library Source', content, req.txEndpoint, req.txStartTime);
+            res.setHeader('Content-Type', 'text/html');
+            res.send(html);
+          } else {
+            res.setHeader('Content-Type', 'application/yaml; charset=utf-8');
+            res.send(source);
+          }
+        } finally {
+          this.countRequest(endpointPath, 'library', Date.now() - start);
+        }
+      });
+    }
+
     // Metadata / CapabilityStatement
     router.get('/metadata', async (req, res) => {
       const start = Date.now();

package/tx/workers/validate.js

@@ -558,10 +558,10 @@ class ValueSetChecker {
           } else {
             this.worker.opContext.addNote(this.valueSet, 'found OK', this.indentCount);
             result = true;
-            if ((await cs.code(ctxt.context)) !== code) {
-              let msg = this.worker.i18n.translate('CODE_CASE_DIFFERENCE', this.params.HTTPLanguages, [code, await cs.code(ctxt), cs.system]);
-              messages.push(msg);
-              op.addIssue(new Issue('warning', 'business-rule', addToPath(path, 'code'), 'CODE_CASE_DIFFERENCE', msg, 'code-rule'));
+            const normalised = await cs.code(ctxt.context);
+            if (normalised && normalised !== code) {
+              messages.push(this.addNormalisationIssue(op, path, code, normalised, cs));
+              normalForm.value = normalised;
             }
             let msg = await cs.incompleteValidationMessage(ctxt.context, this.params.HTTPLanguages);
             if (msg) {
@@ -1611,6 +1611,34 @@ class ValueSetChecker {
     return result;
   }
 
+  /**
+   * The code as submitted differs from the code as the code system renders it. Report why.
+   *
+   * Every such difference used to be reported as CODE_CASE_DIFFERENCE, which is where that
+   * assumption came from - cs-lang, where the canonical form really does differ only in case.
+   * It is not true in general. cs-snomed re-renders any postcoordinated expression through
+   * renderExpression(Minimal), so every legal alternative serialisation (the optional comma
+   * before an attribute group, whitespace, |terms|, attribute order) came back to the caller
+   * as a complaint about their casing; ICD-11 normalises a URI to the code it denotes and did
+   * the same. Neither has anything to do with case, and unlike case there is nothing the
+   * caller did wrong - the submitted form is valid, it simply is not the normal form.
+   *
+   * So: case-only differences stay CODE_CASE_DIFFERENCE, everything else is
+   * CODE_NOT_IN_NORMAL_FORM. Both are information severity (they were warning in one of the
+   * two call sites and information in the other; every tx-ecosystem fixture expects
+   * information).
+   *
+   * @returns {string} the message, for callers that also collect it into `messages`
+   */
+  addNormalisationIssue(op, path, code, normalised, cs) {
+    const caseOnly = normalised.toLowerCase() === code.toLowerCase();
+    const id = caseOnly ? 'CODE_CASE_DIFFERENCE' : 'CODE_NOT_IN_NORMAL_FORM';
+    const csDesc = cs.version() ? cs.system() + '|' + cs.version() : cs.system();
+    const msg = this.worker.i18n.translate(id, this.params.HTTPLanguages, [code, normalised, csDesc]);
+    op.addIssue(new Issue('information', 'business-rule', addToPath(path, 'code'), id, msg, 'code-rule'));
+    return msg;
+  }
+
   async checkConceptSet(path, role, cs, cset, code, displays, vs, message, inactive, normalForm, vstatus, op, vcc, messages) {
     this.worker.opContext.addNote(vs, 'check code ' + role + ' ' + this.worker.renderer.displayValueSetInclude(cset) + ' at ' + path, this.indentCount);
     let result = false;
@@ -1633,15 +1661,10 @@ class ValueSetChecker {
         }
       } else {
         this.worker.opContext.addNote(this.valueSet, 'Code "' + code + '" found in ' + this.worker.renderer.displayCoded(cs), this.indentCount);
-        if (await cs.code(loc.context) != code) {
-          let msg;
-          if (cs.version()) {
-            msg = this.worker.i18n.translate('CODE_CASE_DIFFERENCE', this.params.HTTPLanguages, [code, await cs.code(loc.context), cs.system() + '|' + cs.version()]);
-          } else {
-            msg = this.worker.i18n.translate('CODE_CASE_DIFFERENCE', this.params.HTTPLanguages, [code, await cs.code(loc.context), cs.system()]);
-          }
-          op.addIssue(new Issue('information', 'business-rule', addToPath(path, 'code'), 'CODE_CASE_DIFFERENCE', msg, 'code-rule'));
-          normalForm.value = await cs.code(loc.context);
+        const normalised = await cs.code(loc.context);
+        if (normalised && normalised != code) {
+          this.addNormalisationIssue(op, path, code, normalised, cs);
+          normalForm.value = normalised;
         }
         let msg = await cs.incompleteValidationMessage(loc.context, this.params.HTTPLanguages);
         if (msg) {