fhirsmith 0.17.0 → 0.18.0

package/tx/library.js

@@ -93,6 +93,12 @@ class Library {
   totalDownloaded = 0;
   vsacCfg = undefined;
 
+  /**
+   * {SyndicationStore|null} where the content this library loads is recorded for the
+   * syndication feed, when the server has one (see tx/syndication)
+   */
+  syndication = null;
+
   registerProvider(source, factory, isDefault = false) {
     this.#logSystem(factory.system(), factory.version(), source);
     if (isDefault || !this.codeSystemFactories.has(factory.system())) {
@@ -607,6 +613,7 @@ class Library {
     const loinc = new LoincServicesFactory(this.i18n, loincFN);
     await loinc.load();
     this.registerProvider(loincFN, loinc, isDefault);
+    this.#syndicateBinary('loinc', loincFN, loinc);
   }
 
   async loadRxnorm(details, isDefault, mode) {
@@ -617,6 +624,7 @@ class Library {
     const rxn = new RxNormServicesFactory(this.i18n, rxNormFN);
     await rxn.load();
     this.registerProvider(rxNormFN, rxn, isDefault);
+    this.#syndicateBinary('rxnorm', rxNormFN, rxn);
   }
 
   async loadNdc(details, isDefault, mode) {
@@ -627,6 +635,7 @@ class Library {
     const ndc = new NdcServicesFactory(this.i18n, ndcFN);
     await ndc.load();
     this.registerProvider(ndcFN, ndc, isDefault);
+    this.#syndicateBinary('ndc', ndcFN, ndc);
   }
 
   async loadUnii(details, isDefault, mode) {
@@ -637,6 +646,7 @@ class Library {
     const unii = new UniiServicesFactory(this.i18n, uniFN);
     await unii.load();
     this.registerProvider(uniFN, unii, isDefault);
+    this.#syndicateBinary('unii', uniFN, unii);
   }
 
   async loadSnomed(details, isDefault, mode) {
@@ -647,6 +657,7 @@ class Library {
     const sct = new SnomedServicesFactory(this.i18n, sctFN);
     await sct.load();
     this.registerProvider(sctFN, sct, isDefault);
+    this.#syndicateBinary('snomed', sctFN, sct);
   }
 
   async loadCpt(details, isDefault, mode) {
@@ -657,6 +668,8 @@ class Library {
     const cpt = new CPTServicesFactory(this.i18n, cptFN);
     await cpt.load();
     this.registerProvider(cptFN, cpt, isDefault);
+    // the store syndicates the public fragment only, never the full (licensed) database
+    this.#syndicateBinary('cpt', cptFN, cpt);
   }
 
   async loadOmop(details, isDefault, mode) {
@@ -667,6 +680,7 @@ class Library {
     const omop = new OMOPServicesFactory(this.i18n, omopFN);
     await omop.load();
     this.registerProvider(omopFN, omop, isDefault);
+    this.#syndicateBinary('omop', omopFN, omop);
   }
 
   /**
@@ -679,13 +693,69 @@ class Library {
     if (mode === "fetch" || mode === "npm") {
       return;
     }
+    // one file, so one syndication entry - identified by the MMS, if the file has it
+    let main = null;
     for (const sys of await ICD11ServicesFactory.listSystems(icdFN)) {
       const factory = new ICD11ServicesFactory(this.i18n, icdFN, sys.code);
       await factory.load();
       this.registerProvider(icdFN, factory, isDefault);
+      if (!main || sys.code === 'mms') {
+        main = factory;
+      }
+    }
+    if (main) {
+      this.#syndicateBinary('icd11', icdFN, main);
     }
   }
 
+  /**
+   * Records a binary source file (SNOMED cache, LOINC database etc) in the syndication store,
+   * if there is one. The store works in the background, and decides itself whether the file
+   * is one it syndicates; nothing it does can stop the library loading.
+   * @private
+   */
+  #syndicateBinary(sourceType, filePath, factory) {
+    if (!this.syndication) {
+      return;
+    }
+    try {
+      let name = null;
+      try {
+        name = factory.name();
+      } catch (e) {
+        // not every factory has a name
+      }
+      void this.syndication.inductBinary({
+        sourceType, filePath, baseUrl: this.baseUrl, system: factory.system(), version: factory.version(), name
+      });
+    } catch (error) {
+      this.log.warn(`Syndication: unable to record ${filePath}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Records a package in the syndication store, if there is one.
+   * @param {PackageContentLoader} contentLoader - the loaded package
+   * @param {Object} source - {requestedVersion} for an npm: source, {url} for a url: source,
+   *   {fhirVersion} (major.minor) for an endpoint's core package
+   */
+  syndicatePackage(contentLoader, source = {}) {
+    if (!this.syndication || !contentLoader || !contentLoader.package) {
+      return;
+    }
+    const pkg = contentLoader.package;
+    void this.syndication.inductPackage({
+      id: contentLoader.id(),
+      version: contentLoader.version(),
+      canonical: pkg.canonical,
+      title: pkg.title,
+      description: pkg.description,
+      url: source.url,
+      fhirVersion: source.fhirVersion,
+      requestedVersion: source.requestedVersion
+    });
+  }
+
   /**
    * Returns true if the given url/version should be excluded from npm/url package loading.
    * Matches against the ignored list using either plain url or url#version.
@@ -707,12 +777,12 @@ class Library {
       version = parts[1];
     }
     const packagePath = await packageManager.fetch(packageId, version);
-    await this.#loadPackageFromPath(packagePath, mode, csOnly);
+    await this.#loadPackageFromPath(packagePath, mode, csOnly, { requestedVersion: version });
   }
 
   async loadUrl(packageManager, url, isDefault, mode, csOnly) {
     const packagePath = await packageManager.fetchUrl(url);
-    await this.#loadPackageFromPath(packagePath, mode, csOnly);
+    await this.#loadPackageFromPath(packagePath, mode, csOnly, { url });
   }
 
   /**
@@ -723,13 +793,14 @@ class Library {
    * array-backed codeSystems list, breaking url sources).
    * @private
    */
-  async #loadPackageFromPath(packagePath, mode, csOnly) {
+  async #loadPackageFromPath(packagePath, mode, csOnly, source) {
     if (mode === "fetch" || mode === "cs") {
       return;
     }
     const fullPackagePath = path.join(this.cacheFolder, packagePath);
     const contentLoader = new PackageContentLoader(fullPackagePath);
     await contentLoader.initialize();
+    this.syndicatePackage(contentLoader, source);
 
     this.packageSources.push(contentLoader.id()+"#"+contentLoader.version());
 
@@ -852,6 +923,27 @@ class Library {
    */
   async #loadLocalSource(contentLoader) {
     await contentLoader.initialize();
+    if (this.syndication) {
+      // each resource is an entry in its own right (those without a version are skipped)
+      for (const entry of contentLoader.index.files) {
+        if (this.#isIgnored(entry.url, entry.version)) {
+          continue;
+        }
+        let title = null;
+        let description = null;
+        try {
+          const json = JSON.parse(await fs.readFile(path.join(contentLoader.sourceFolder, entry.filename), 'utf8'));
+          title = json.title || json.name || null;
+          description = typeof json.description === 'string' ? json.description : null;
+        } catch (e) {
+          // initialize() already read it; if it can't now, the store will say so
+        }
+        void this.syndication.inductResource({
+          filePath: path.join(contentLoader.sourceFolder, entry.filename),
+          resourceType: entry.resourceType, url: entry.url, version: entry.version, title, description
+        });
+      }
+    }
 
     this.packageSources.push(contentLoader.id() + "#" + contentLoader.version());
 
@@ -1050,7 +1142,9 @@ class Library {
 
     // Load FHIR packages - these will be added to valueSetProviders first
     for (const packageId of fhirPackages) {
-      await provider.loadNpm(this.packageManager, this.cacheFolder, packageId, false, "npm", false);
+      const contentLoader = await provider.loadNpm(this.packageManager, this.cacheFolder, packageId, false, "npm", false);
+      // the core packages are the only version specific content in the syndication store
+      this.syndicatePackage(contentLoader, { fhirVersion: VersionUtilities.getMajMin(String(fhirVersion)) });
     }
 
 

package/tx/openapi-operations.js

@@ -209,6 +209,7 @@ const OPERATIONS = [
       p('version', 'string', '1', 'The version of the code system'),
       p('coding', 'Coding', '1', 'The code, as a Coding'),
       p('property', 'code', '*', 'A property to return (by default, all of them)'),
+      p('post-coordination-metadata', 'boolean', '1', 'For a post-coordinated code: describe every post-coordination axis in full - the axis rules, and the axes that carry no value (ICD-11). By default only the axes that carry a value are listed'),
     ],
     out: [
       p('name', 'string', '1', 'The name of the code system', { min: 1 }),
@@ -283,11 +284,14 @@ const OPERATIONS = [
         parts: [
           p('relationship', 'code', '1', 'How the target relates to the source'),
           p('concept', 'Coding', '1', 'The target'),
+          p('normalized-concept', 'Coding', '1', 'The target in its code system\'s normal form, when the map states it in another form'),
+          p('note', 'string', '1', 'The target\'s code system is not known, so the code has not been validated'),
           p('product', '(parts)', '*', 'Another element of the product (element, concept)'),
           p('originMap', 'canonical', '1', 'The concept map'),
           p('sourceConcept', 'Coding', '1', 'What was translated (for a translation in reverse)')
         ]
       }),
+      p('error', 'string', '*', 'A target code the maps gave that is not valid in its code system'),
       p('used-conceptmap', 'canonical', '*', 'A concept map that was used')
     ]
   },

package/tx/params.js

@@ -380,6 +380,12 @@ class TxParameters {
         if (claim('includeDefinition')) this.includeDefinition = asBool();
         break;
       }
+      // $lookup: describe each postcoordination axis in full (ICD-11) - the axis rules, and the
+      // axes that carry no value. Off unless asked for
+      case 'post-coordination-metadata': {
+        if (claim('post-coordination-metadata')) this.postCoordinationMetadata = asBool();
+        break;
+      }
       case 'activeOnly': {
         if (claim('activeOnly')) this.activeOnly = asBool();
         break;
@@ -624,7 +630,7 @@ class TxParameters {
     // are included, and diagnostics.
     // filter is free text, so JSON.stringify it to avoid delimiter collisions.
     s = s + 'f:' + JSON.stringify(this.filter || '') + '|' +
-      b(this.abstractOk) + b(this.diagnostics);
+      b(this.abstractOk) + b(this.diagnostics) + b(this.postCoordinationMetadata);
     for (let t of this.FVersionRules) {
       s = s + t.asString() + '|';
     }
@@ -676,6 +682,7 @@ class TxParameters {
     this.hasVersionsMatch = other.hasVersionsMatch;
     this.hasDisplayWarning = other.hasDisplayWarning;
     this.sort = other.sort;
+    this.postCoordinationMetadata = other.postCoordinationMetadata;
 
     if (other.FSeen) {
       this.FSeen = new Set(other.FSeen);

package/tx/provider.js

@@ -151,7 +151,7 @@ class Provider {
     validateParameter(opContext, "opContext", OperationContext);
     validateParameter(codeSystem, "codeSystem", CodeSystem);
     validateArrayParameter(supplements, "supplements", CodeSystem);
-    return new FhirCodeSystemProvider(opContext, codeSystem, supplements);
+    return FhirCodeSystemProvider.create(opContext, codeSystem, supplements);
   }
 
 
@@ -160,6 +160,8 @@ class Provider {
    * space (CodeSystem/core-v3-MaritalStatus): the core packages for different FHIR versions
    * share ids, and so does other content (hl7.terminology), so no endpoint can serve them on
    * their own ids (see tx/library/resource-ids.js)
+   *
+   * @returns {Promise<PackageContentLoader|undefined>} the loaded package (mode "npm")
    */
   async loadNpm(packageManager, cacheFolder,  details, isDefault, mode) {
     // Parse packageId and version from details (e.g., "hl7.terminology.r4#6.0.2")
@@ -216,6 +218,7 @@ class Provider {
     await cm.initialize();
     cm.assignIds(CORE_PREFIX);
     this.conceptMapProviders.push(cm);
+    return contentLoader;
   }
 
   getCodeSystemById(opContext, id) {
@@ -331,16 +334,25 @@ class Provider {
 
 
 
-  async findConceptMapForTranslation(opContext, conceptMaps, sourceSystem, sourceScope, targetScope, targetSystem, sourceCode = null) {
+  async findConceptMapForTranslation(opContext, conceptMaps, sourceSystem, sourceVersion, sourceScope, targetScope, targetSystem, sourceCode = null) {
     for (let cmp of this.conceptMapProviders) {
       await cmp.findConceptMapForTranslation(opContext, conceptMaps, sourceSystem, sourceScope, targetScope, targetSystem, sourceCode);
     }
     if (sourceSystem && targetSystem) {
+      // Each code system is asked once - except the source system itself, where every
+      // version (every SNOMED edition, say) is asked, since whether a map exists and what
+      // it says can depend on which version the source coding is in. The factory decides
+      // from sourceVersion whether it is the one being asked about.
       let uris = new Set();
+      let asked = new Set(); // a factory is registered under several keys (system, system|version...)
       for (let csp of this.codeSystemFactories.values()) {
-        if (!uris.has(csp.system())) {
+        if (asked.has(csp)) {
+          continue;
+        }
+        if (csp.system() === sourceSystem || !uris.has(csp.system())) {
           uris.add(csp.system());
-          await csp.findImplicitConceptMaps(conceptMaps, sourceSystem, targetSystem);
+          asked.add(csp);
+          await csp.findImplicitConceptMaps(conceptMaps, sourceSystem, sourceVersion, targetSystem);
         }
       }
     }

package/tx/sct/documentation.md

@@ -0,0 +1,251 @@
+# SNOMED CT support in FHIRsmith: known limitations
+
+This file records what the SNOMED CT code system provider (`tx/cs/cs-snomed.js`,
+`tx/sct/*`) does not do, so that nobody has to rediscover it from the code. It is
+organised by area: ECL, post-coordinated expressions, and everything else. Where
+a limitation is a deliberate decision rather than unfinished work, it says so.
+
+The import pipeline (`tx/importers/import-sct.module.js`) reads the RF2 snapshot
+concept, description (including text definitions, which share the description
+file layout), inferred relationship, and reference set files. It does not read
+stated relationships, the OWL axiom reference sets, or the concrete value
+relationship file; several of the limitations below follow from that.
+
+## ECL
+
+The parser (`tx/sct/ecl.js`) accepts the ECL 2.2 grammar with the exceptions
+listed under "Not parsed". The evaluator (`SnomedServices.filterECL` and the
+`_eval*` methods in `cs-snomed.js`) evaluates the subset listed under
+"Evaluated"; anything the parser accepts but the evaluator does not implement
+is reported as `UNSUPPORTED_ECL`, and a syntax error or an unknown concept as
+`INVALID_ECL`. Both are OperationOutcomes with tx-issue-type `vs-invalid`.
+
+Note that `ECLValidator.evaluate*` in `ecl.js` is an older, weaker evaluator
+that the server does not use. `filterECL` is the one that matters.
+
+### Evaluated
+
+- All eight hierarchy operators (`<`, `<<`, `<!`, `<<!`, `>`, `>>`, `>!`, `>>!`)
+  on a concept reference, on `*`, on `^ refset` and on a bracketed expression
+  (applied to every member of the set), and top/bottom of set (`!!> (...)`,
+  `!!< (...)`).
+- `*` (every concept, active and inactive - `activeOnly` is the expansion's job).
+- `^` member-of on a concept or any bracketed expression, with
+  `{{ M ... }}` member filters on `effectiveTime`, `active`, `moduleId` and the
+  reference set's own fields (concept, integer and string typed from the RF2
+  file name). Since inactive member rows are dropped at import, `active = false`
+  never matches.
+- `AND` / `OR` / `MINUS` (and `,`), with the ECL 6.4 rule that conjunction and
+  disjunction cannot be mixed without brackets.
+- Refinements: `=` against an expression value; attribute names that are a
+  concept, `*`, or any sub expression (`<< 762705008 = ...`); attribute sets
+  joined by `AND`, `OR` or `,`, with brackets; attribute groups, including
+  `AND`/`OR` inside and between groups; attribute and group cardinality,
+  including `[0..0]`. Cardinality counts occurrences per role group, per the
+  SNOMED Computable Languages Group ruling (see `_countAttributeMatches`).
+- Dotted expressions (`< X . 363698007`, `. << 363698007`, `. (A OR B)`).
+- `{{ C ... }}` concept filters on `active`, `definitionStatus`,
+  `definitionStatusId`, `moduleId` and `effectiveTime`.
+- `{{ D ... }}` description filters on `term` (match semantics: each word of
+  the search term starts a word of the description, case-insensitively; and
+  `wild:` whole-term patterns), `language`, `typeId` / `type` (syn, fsn, def),
+  `dialectId` / `dialect` with acceptability sets (`(prefer)`, `(accept)` or
+  acceptability concept ids; the `dialect` aliases known are en-us, en-gb,
+  en-au, en-ca, en-nz, en-ie, fr-ca, fr-be, nl-be, nl-nl, es-es, sv-se, da-dk),
+  `moduleId`, `effectiveTime`, `active` and `id`. The filters in one block
+  must be satisfied by a single description; separate blocks may be satisfied
+  by different descriptions. Only active descriptions are considered unless
+  the block has an `active` filter.
+- Comments (`/* ... */`), terms (`|...|`, not checked against descriptions).
+
+### Parsed but reported as unsupported
+
+- Reverse attributes (`R 363698007 = ...`).
+- `!=` against an expression value in a refinement.
+- Concrete values in refinements - numeric (`= #5`, `>= #1.5`), string
+  (`= "x"`, `= match:"x"`), boolean (`= true`). The importer does not read
+  `sct2_RelationshipConcreteValues_*`, so no concrete values are in the cache
+  to compare against. Supporting them means extending the importer and the
+  relationship record, and rebuilding every cache.
+- Alternate identifiers (`"ICD10#A01.1"`, `SCTID#123`). No alternate
+  identifier reference sets are loaded.
+- Reference set field selection on member-of (`^ [targetComponentId] refset`,
+  `^ [referencedComponentId, targetComponentId] refset`). Deliberate: the
+  selected fields, and the referenced components of many reference sets,
+  are descriptions or other non-concept components, which an expansion has
+  no way to represent.
+- History supplements (`{{ + HISTORY-MIN / MOD / MAX }}`). The association
+  reference sets they draw on are loaded, so this is implementable.
+
+### Not parsed
+
+- `wild:` search terms are rejected in member filters (accepted in refinement
+  string values, which are then unsupported anyway).
+- A concept id must be 6-18 digits; anything else is a syntax error (this is
+  what makes `<< abc` invalid rather than unsupported).
+
+### Other ECL notes
+
+- Description filter term matching walks the descriptions of every concept in
+  the result set rather than using the text index, so `* {{ D term = "x" }}`
+  on a full edition scans every description. It yields to the event loop via
+  the operation's dead-check but is not fast.
+- A `dialect` alias the server does not know is reported as unsupported, not
+  invalid; the alias table is `ECL_DIALECT_ALIASES` in `cs-snomed.js`.
+
+- Term checking: a wrong term after a concept id (`10200004 |Lever structure|`)
+  is accepted silently. The tx-ecosystem test `expand-ecl-term-mismatch` expects
+  this.
+- `^` on a concept that is not a reference set yields an empty result rather
+  than an error (Snowstorm's behaviour; agreed in the tx-ecosystem suite).
+  `^` on a reference set whose members are descriptions (a language reference
+  set) is reported as unsupported - there are no concepts to return.
+- The ECL result for a value set filter is cached per (value set, code system
+  version), so the first expansion of a large constraint is slow and later ones
+  are not.
+
+## Post-coordinated expressions
+
+Expressions are parsed by `SnomedExpressionParser` (`tx/sct/expressions.js`)
+in SNOMED Compositional Grammar, including `===` / `<<<` definition status
+markers, nested (bracketed) attribute values, concrete values and terms.
+They are normalised, checked against the MRCM, and compared structurally.
+
+### Validation
+
+`checkExpression` rejects an expression whose refinements break the concept
+model (`$validate-code` then answers `result = false`): the attribute must be
+allowed on the focus concept's domain (MRCM attribute domain reference set
+`723561005`), the value must satisfy the attribute's range (`723562003`,
+whether that is ECL or a concrete range such as `dec(>#0..)`), the attribute
+and in-group cardinality maximums apply, and an attribute the MRCM marks as
+grouped must be in a role group. Known limits:
+
+- Minimum cardinality is not enforced (it constrains a concept's own
+  definition, not a refinement of it). The converse of the grouping rule
+  (grouped = 0 means must not be grouped) is enforced only through the
+  in-group cardinality `0..0`.
+- Attributes with no MRCM rule in the loaded edition are not checked at all.
+  Internationally that is `704347000 |Observes|`, `131195008 |Subject of
+  information|` and `363705008 |Has definitional manifestation|`, and
+  `762951001 |Has ingredient|`, whose only domain row is scoped to new
+  precoordinated content (an MRCM inconsistency, not something to work around).
+- An edition with no MRCM reference sets (e.g. the committed jest test cache)
+  gets no concept model checking at all; the checks go inert.
+- The ungrouped "Close To User Form" is rejected rather than transformed to the
+  classifiable form. None of the seven Level 1 transformations in SNOMED's
+  postcoordination guide (refining an existing attribute, adding a self-grouped
+  attribute, adding severity, lateralising findings and procedures, adding
+  context to findings and procedures) is implemented.
+- Negative concrete values (`#-5`) fail to parse ("Expected character } but
+  found -"). SCG permits them.
+- Laterality on a non-lateralisable body structure is caught only when the
+  edition carries reference set `723264001`; the tx-ecosystem test edition
+  does not, so the IG suite cannot assert it.
+
+### Subsumption
+
+`$subsumes` on expressions works by comparing normal forms: each side is
+expanded through its fully defined concepts (primitives keep their atom and
+contribute their defining attributes), then matched structurally, trying every
+role group pairing.
+
+- Positive answers (`subsumes`, `subsumed-by`, `equivalent`) are sound.
+  A negative answer is not provable this way: SNOMED's OWL axiom reference set
+  carries general concept inclusions and property chains whose entailments are
+  baked into the distributed inferred relationships for precoordinated concepts,
+  but an expression is something the classifier never saw. So when no
+  relationship is found and either side is an expression, the server returns an
+  OperationOutcome (HTTP 422, issue code `not-supported`, tx-issue-type
+  `cannot-determine`) rather than `not-subsumed`. Between two plain concepts all
+  four outcomes are sound (the transitive closure is the classifier's own
+  output).
+- There is no reasoner. Removing the decline above would need an OWL
+  classifier over the axiom reference set (which is not imported).
+- Normalisation depth is capped at 50 and throws rather than truncating,
+  because a truncated normal form is unsound in both directions.
+- `subsumesTest` does not re-validate its inputs; `$subsumes` runs `locate()`
+  (and so `checkExpression`) on both codes first.
+
+### Lookup and display
+
+- `$lookup` on an expression returns the rendered expression and its
+  components; the normal form, parents and children properties are returned
+  for single-concept expressions only.
+- The display of an expression is the server's own rendering (no spaces,
+  `:{...}`), and every concept in it is given its preferred term.
+
+## Everything else
+
+### Data not imported
+
+- Stated relationships and the OWL axiom reference sets. Everything is driven
+  by the distributed inferred relationships; there is no classification.
+- Concrete value relationships (see ECL above).
+- Alternate identifier reference sets.
+- Inactive reference set member rows (only active rows are stored).
+- Module ids and definition status on concepts are recorded by the current
+  importer; caches built before mid-2026 have neither (every concept looks
+  fully defined, module is 0). The jest cache `tx/data/snomed-testing.cache`
+  is one of those.
+
+### Language and display
+
+- Description languages are mapped to a small fixed set at import
+  (`mapLanguageCode`); an unknown language is recorded as English. Norwegian
+  or Finnish descriptions, say, would be labelled `en`.
+- `SnomedExpressionServices.codeForLanguage` has a stale language map that
+  disagrees with the importer; only the term is read from it today.
+- With no `displayLanguage`, every edition defaults to US then GB English
+  preferred synonyms. A concept whose only English description is its FSN
+  gets its national-language preferred synonym instead.
+- `sharedData.defaultLanguage` is hard-coded to 1 at import and
+  `getDisplayName` ignores the language argument it is passed.
+
+### Filters and implicit resources
+
+- ValueSet filters supported on `compose.include.filter`: `concept` (`is-a`,
+  `descendent-of`, `in`), `inactive =`, `moduleId =`, `constraint =` (ECL),
+  `expressions =`, and `<attributeId> = <conceptId>`. Other operators on these
+  properties, and other properties, are rejected.
+- Implicit value sets: `?fhir_vs`, `?fhir_vs=refset`, `?fhir_vs=refset/<id>`
+  and `?fhir_vs=isa/<id>`, with optional edition and version segments.
+  `?fhir_vs=ecl/<expression>` is not recognised; use a `constraint` filter.
+- Implicit concept maps (`?fhir_cm=<id>`): only the four historical association
+  reference sets (POSSIBLY EQUIVALENT TO, REPLACED BY, SAME AS, ALTERNATIVE).
+  Simple and extended map reference sets (ICD-10, ICD-O, ...) are loaded but
+  are not exposed as implicit concept maps, and reverse translation is not
+  supported.
+- Edition to edition translation (`<edition>/version/<date>?fhir_cm=edition/<module>`):
+  a `$translate` from an edition to one it depends on (per the module dependency
+  reference set) needs no map - the answer comes from the definitions. A concept in
+  the target edition's modules is its own translation; an inactive concept translates
+  through its historical associations; a fully defined extension concept translates
+  to its normal form (or to the target concept with that normal form, if there is
+  one), provided the normal form uses only target edition content; anything else
+  translates to its proximal target-edition ancestors as `source-is-narrower-than-target`,
+  unless the only such ancestors are top-level hierarchies, which is reported as a
+  reason for no translation. The map is found from `targetSystem` =
+  `http://snomed.info/sct|<target edition[/version/date]>`, or nominated by url.
+- `$closure` works through `subsumesTest`, so adding a post-coordinated
+  expression to a closure table hits the `cannot-determine` rule above whenever
+  it is unrelated to an existing entry.
+
+### Text search
+
+- The `filter` parameter on `$expand` uses an in-memory word index built the
+  first time an edition is searched (`tx/sct/text-index.js`): every token of
+  every active description, matched by prefix and by Porter stem. The stemmer
+  is English, so in other languages only prefix matching helps. Inactive
+  descriptions are not indexed.
+
+### Known data quality traps
+
+- The three copies of the tx-ecosystem SNOMED test edition
+  (`data/terminology-cache/sct_test_*.cache`, `tx/data/snomed-testing.cache`,
+  `data/snomed-testing.cache`) drift. The committed jest cache is older than
+  the RF2 subset in `tx/data/snomed` and lacks module ids, definition status
+  and some concepts; rebuilding it changes test expectations.
+- `tx.fhir.org` (the Java server) and FHIRsmith disagree on a few expected
+  results in the tx-ecosystem suite (display selection, MRCM); the suite
+  records FHIRsmith's reading where Grahame has decided it.