fhirsmith 0.11.2 → 0.13.0

package/tx/cs/cs-snomed.js

@@ -1,4 +1,4 @@
-const { CodeSystemContentMode, CodeSystemFactoryProvider} = require('./cs-api');
+const { CodeSystemContentMode, CodeSystemFactoryProvider, cannotDetermineSubsumption} = require('./cs-api');
 const {
   SnomedStrings, SnomedWords, SnomedStems, SnomedReferences,
   SnomedDescriptions, SnomedDescriptionIndex, SnomedConceptList,
@@ -148,6 +148,58 @@ class SnomedServices {
       refSetIndex: this.refSetIndex
     }, this.isAIndex);
 
+    // The expression services check the MRCM attribute ranges, but those are ECL
+    // and the ECL engine lives here, so hand them an evaluator. Returning null
+    // means "could not decide", and leaves the value unchecked.
+    this.expressionServices.eclConstraintMatcher = (constraint, value) => this.mrcmRangeSatisfied(constraint, value);
+    this._mrcmRangeCache = new Map();
+  }
+
+  /**
+   * Does this refinement value satisfy an MRCM range constraint?
+   *
+   * @param {string} constraint - the rangeConstraint ECL, e.g. "<< 182353008 |Side|"
+   * @param {SnomedExpression} value - the refinement's value expression
+   * @returns {boolean|null} null when the constraint cannot be evaluated
+   */
+  mrcmRangeSatisfied(constraint, value) {
+    let entry = this._mrcmRangeCache.get(constraint);
+    if (entry === undefined) {
+      entry = null;
+      try {
+        const ast = new ECLParser(new ECLLexer(constraint).tokenize()).parse();
+        const ctxt = this._evalECLNode(ast, null);
+        entry = {
+          ast: ast,
+          wildcard: !!ctxt.eclWildcard,
+          members: new Set(this._eclToIndexArray(ctxt))
+        };
+      } catch (error) {
+        // Concrete value ranges (dec/int/str) and anything else the ECL engine
+        // does not support: remembered as unusable so it is parsed only once.
+        entry = null;
+      }
+      this._mrcmRangeCache.set(constraint, entry);
+    }
+    if (!entry) {
+      return null;
+    }
+    if (entry.wildcard) {
+      return true;
+    }
+
+    const concepts = (value.concepts || []).filter(c => c.reference != null && c.reference !== NO_REFERENCE);
+    const refined = value.hasRefinements() || value.hasRefinementGroups();
+    if (!refined) {
+      if (concepts.length === 0) {
+        return null; // a concrete value, or nothing we can resolve
+      }
+      // Every focus concept of a plain value must be in the constraint's set.
+      return concepts.every(c => entry.members.has(c.reference));
+    }
+    // A refined value: ask the ECL engine whether the expression satisfies the
+    // constraint (it knows that a refinement of X is still << X).
+    return this._eclExpressionSatisfies({ expression: value }, entry.ast, null);
   }
 
   close() {
@@ -664,7 +716,7 @@ class SnomedServices {
     // we actually need the full concept list, otherwise filterSize returns 0
     // and the iteration yields nothing. Materialise active concepts now.
     if (forIteration && result.eclWildcard && (!result.descendants || result.descendants.length === 0)) {
-      result.descendants = this._eclEnumerateActiveConcepts(opContext);
+      result.descendants = this._eclEnumerateAllConcepts(opContext);
       delete result.eclWildcard;
       // The materialised wildcard form differs from the lazy (eclWildcard) form,
       // so mark it: the filter cache must not share it across iteration modes.
@@ -677,31 +729,29 @@ class SnomedServices {
   };
 
   /**
-   * Return every active concept's index. Used to materialise wildcard results
-   * when the filter needs to be iterated over (e.g. $expand).
+   * Return every concept's index. Used to materialise wildcard results when the
+   * filter needs to be iterated over (e.g. $expand).
+   *
+   * `*` means every concept the server knows, so this deliberately walks the
+   * concept table rather than descending from 138875005 |SNOMED CT Concept|.
+   * Two kinds of concept are in the table but not reachable from that root:
+   * inactive concepts (their is-a relationships are inactive too), and the
+   * foundation-metadata concepts that a subset carries without their is-a
+   * relationships - module concepts above all. Both belong in `*`, and both are
+   * counted by countAllCodes, so descending from the root made $expand of a
+   * `constraint = *` filter disagree with $expand of the whole code system.
+   *
+   * Inactive concepts are not filtered out here: activeOnly is applied by the
+   * expansion itself (see ValueSetExpander.processCodes), which is what lets one
+   * enumeration serve both activeOnly=true and activeOnly=false.
    * @returns {number[]}
    */
-  _eclEnumerateActiveConcepts = function (opContext) {
-    // The wildcard `*` enumerates the SNOMED CT concept hierarchy: the root
-    // 138875005 |SNOMED CT Concept| and its descendants. This excludes the
-    // foundation-metadata concepts that appear in a subset's concept table
-    // (referenced by the RF2 files as module / type / acceptability ... ids)
-    // without their is-a relationships, so they are not reachable from the root
-    // and are not returned by `*` (matching Snowstorm). On a full edition every
-    // real concept is under the root, so nothing is lost.
-    const rootRes = this.concepts.findConcept(138875005n);
-    if (rootRes && rootRes.found) {
-      return this.filterIsA(138875005n, true).descendants;
-    }
-    // Fallback (no recognisable root): every active concept.
+  _eclEnumerateAllConcepts = function (opContext) {
     const all = [];
     const n = this.concepts.count();
     for (let i = 0; i < n; i++) {
-      if (opContext) opContext.deadCheck('ecl:enumerateActiveConcepts');
-      const concept = this.concepts.getConceptByCount(i);
-      if ((concept.flags & 0x0F) === 0) {
-        all.push(concept.index);
-      }
+      if (opContext) opContext.deadCheck('ecl:enumerateAllConcepts');
+      all.push(this.concepts.getConceptByCount(i).index);
     }
     return all;
   };
@@ -918,7 +968,7 @@ class SnomedServices {
   };
 
   /**
-   * Wildcard — all active concepts.  The eclWildcard flag tells filterCheck /
+   * Wildcard — every concept, active or not.  The eclWildcard flag tells filterCheck /
    * filterLocate to accept every active concept without enumeration.
    * @returns {SnomedFilterContext}
    */
@@ -1312,15 +1362,15 @@ class SnomedServices {
 
   /**
    * Like _eclToIndexArray, but if the context is a bare wildcard (no
-   * descendants populated) it materialises the full active-concept list
-   * via _eclEnumerateActiveConcepts. Used by dotted/refined evaluation,
+   * descendants populated) it materialises the full concept list
+   * via _eclEnumerateAllConcepts. Used by dotted/refined evaluation,
    * which need an explicit concept set to iterate over.
    * @param {SnomedFilterContext} ctx
    * @returns {number[]}
    */
   _eclResolveSet = function (ctx, opContext) {
     if (ctx.eclWildcard && (!ctx.descendants || ctx.descendants.length === 0)) {
-      return this._eclEnumerateActiveConcepts(opContext);
+      return this._eclEnumerateAllConcepts(opContext);
     }
     return this._eclToIndexArray(ctx);
   };
@@ -1369,9 +1419,9 @@ class SnomedServices {
     const rightSet = new Set(this._eclToIndexArray(right));
 
     if (left.eclWildcard) {
-      // Wildcard minus the right set: use the shared active-concept enumeration
-      // (the root hierarchy) so `*` behaves consistently everywhere.
-      result.descendants = this._eclEnumerateActiveConcepts(opContext)
+      // Wildcard minus the right set: use the shared enumeration so `*` behaves
+      // consistently everywhere.
+      result.descendants = this._eclEnumerateAllConcepts(opContext)
         .filter(idx => !rightSet.has(idx));
       return result;
     }
@@ -1734,19 +1784,6 @@ class SnomedProvider extends BaseCSServices {
     }
   }
 
-  async incompleteValidationMessage(context) {
-
-    const ctxt = await this.#ensureContext(context);
-
-    if (!ctxt) return null;
-
-    if (ctxt.isComplex()) {
-      return "The expression is grammatically correct and the concepts are valid, but the expression has not been checked against the SNOMED CT concept model (MRCM)";
-    } else {
-      return null;
-    }
-  }
-
   async locateIsA(code, parent, disallowParent = false) {
 
 
@@ -1881,25 +1918,37 @@ class SnomedProvider extends BaseCSServices {
       if (ctxt instanceof SnomedExpressionContext) {
         // ignore concepts for now, but list refinements and refinement groups
         for (const refinement of ctxt.expression.refinements) {
-          const codeA = refinement.name.code;
-          const codeB = refinement.value.describe();
-          const description = await this.display(codeB);
-          let p = this._addCodeProperty(params, 'property', codeA, codeB, null, description);
-          p.part.push({name: 'code-display', valueString: await this.display(codeA)});
+          await this._addRefinementProperty(params, refinement);
         }
         for (const refinementGroup of ctxt.expression.refinementGroups) {
           for (const refinement of refinementGroup.refinements) {
-            const codeA = refinement.name.code;
-            const codeB = refinement.value.describe();
-            const description = await this.display(codeB);
-            let p = this._addCodeProperty(params, 'property', codeA, codeB, null, description);
-            p.part.push({name: 'code-display', valueString: await this.display(codeA)});
+            await this._addRefinementProperty(params, refinement);
           }
         }
       }
     }
   }
 
+  /**
+   * Report one refinement of a post-coordinated expression as a lookup property.
+   *
+   * The value is handled as an expression, not as a string: SnomedExpression's
+   * describe() is a human-readable rendering that joins concepts and refinements
+   * with commas ("85562004,272741003=24028007"), so round-tripping it through
+   * display() parsed it back as SCG and failed on any refined value.
+   *
+   * @param {Object} params - the Parameters being built
+   * @param {SnomedRefinement} refinement
+   */
+  async _addRefinementProperty(params, refinement) {
+    const codeA = refinement.name.code;
+    const value = SnomedExpressionContext.fromExpression('', refinement.value);
+    const codeB = await this.code(value);
+    const description = await this.display(value);
+    const p = this._addCodeProperty(params, 'property', codeA, codeB, null, description);
+    p.part.push({name: 'code-display', valueString: await this.display(codeA)});
+  }
+
   // Filter support
   async doesFilter(prop, op, value) {
     if (prop === 'concept') {
@@ -2131,7 +2180,7 @@ class SnomedProvider extends BaseCSServices {
     // A wildcard (`*`) set is lazy - it carries the eclWildcard flag rather than a
     // materialised descendant list - so count the active concepts it denotes.
     if (set.eclWildcard && (!set.descendants || set.descendants.length === 0)) {
-      return this.sct._eclEnumerateActiveConcepts(this.opContext).length;
+      return this.sct._eclEnumerateAllConcepts(this.opContext).length;
     }
     if (set.matches && set.matches.length > 0) {
       return set.matches.length;
@@ -2183,7 +2232,7 @@ class SnomedProvider extends BaseCSServices {
     const reference = ctxt.getReference();
 
     if (set.eclWildcard) {
-      return this.sct.isActive(reference) ? ctxt : null;
+      return ctxt; // `*` is every concept; inactive ones included
     }
 
     // A post-coordinated expression validated against an ECL value set: test the
@@ -2266,7 +2315,7 @@ class SnomedProvider extends BaseCSServices {
       return this.#descendantsHas(set, reference);
     }
     if (set.eclWildcard) {
-      return this.sct.isActive(reference);
+      return true; // `*` is every concept; inactive ones included
     }
     return false;
   }
@@ -2344,9 +2393,21 @@ class SnomedProvider extends BaseCSServices {
   }
 
   // Subsumption testing
+  /**
+   * Subsumption between two codes, either of which may be a postcoordinated expression.
+   *
+   * PRECONDITION: both codes have already been validated. doSubsumes (the only caller)
+   * runs locate() on each first, which parses and runs checkExpression - so an
+   * expression that breaks the concept model is reported as an invalid code before it
+   * gets here, rather than having a subsumption answer computed for it. The check is
+   * deliberately not repeated here: it evaluates ECL for the MRCM range constraints, and
+   * doing that twice per request is not free.
+   *
+   * @param {string} codeA
+   * @param {string} codeB
+   * @returns {Promise<string>} equivalent | subsumes | subsumed-by | not-subsumed
+   */
   async subsumesTest(codeA, codeB) {
-
-
     try {
       const exprA = new SnomedExpressionParser(this.sct.concepts).parse(codeA);
       const exprB = new SnomedExpressionParser(this.sct.concepts).parse(codeB);
@@ -2375,10 +2436,32 @@ class SnomedProvider extends BaseCSServices {
         } else if (b2) {
           return 'subsumed-by';
         } else {
-          return 'not-subsumed';
+          // No structural relationship found - which is NOT the same as there being
+          // none. Structural comparison of normal forms is sound when it succeeds (a
+          // proof is a proof) but not when it fails: 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 a postcoordinated expression is one the classifier never saw,
+          // so those entailments are not available for it. Answering 'not-subsumed'
+          // here would assert something we have not established, in the direction that
+          // wrongly excludes a code from a cohort.
+          //
+          // $subsumes has four outcome codes and none of them means "unknown", so the
+          // only honest answer is an error. Both codes are valid and the request is
+          // well formed, hence 422 rather than 400.
+          throw cannotDetermineSubsumption('Unable to determine the subsumption relationship between '
+            + `'${codeA}' and '${codeB}': at least one is a postcoordinated expression and no `
+            + 'relationship follows from comparing their normal forms. Establishing that there '
+            + 'is no relationship would require classification, which this server does not do, '
+            + 'so no outcome is returned rather than one that may be wrong');
         }
       }
     } catch (error) {
+      // Errors that already say how they should be reported pass straight through -
+      // wrapping them would lose the status and issue code.
+      if (error.statusCode) {
+        throw error;
+      }
       throw new Error(`Error in subsumption test: ${error.message}`);
     }
   }

package/tx/cs/cs-ucum.js

@@ -7,6 +7,7 @@ const { FilterExecutionContext, CodeSystemFactoryProvider} = require('./cs-api')
 const ValueSet = require("../library/valueset");
 const assert = require('assert');
 const {UcumService} = require("../library/ucum-service");
+const {Pair, Decimal} = require("../library/ucum-types");
 const {validateArrayParameter, validateParameter, validateOptionalParameter} = require("../../library/utilities");
 const {DesignationUse} = require("../library/designations");
 const {BaseCSServices} = require("./cs-base");
@@ -397,11 +398,40 @@ class UcumCodeSystemProvider extends BaseCSServices {
     return codeA === codeB;
   }
 
+  /**
+   * UCUM has no hierarchy, so no code is ever a subtype of another. Two different codes can
+   * still mean the same unit though - 1/min and min-1 are the same thing written two ways -
+   * so when the codes differ, compare what they canonicalise to.
+   *
+   * This is the canonical *form*, not the canonical units: getCanonicalUnits() drops the
+   * magnitude, so m and cm both answer 'm' and would compare equal when they are different
+   * units. getCanonicalForm() carries the conversion factor with the unit, which is what
+   * distinguishes the same unit written differently from a merely comparable one.
+   *
+   * @param {string|UcumContext} codeA
+   * @param {string|UcumContext} codeB
+   * @returns {string} equivalent or not-subsumed
+   */
   async subsumesTest(codeA, codeB) {
+    const a = await this.#ensureContext(codeA);
+    const b = await this.#ensureContext(codeB);
 
-    await this.#ensureContext(codeA);
-    await this.#ensureContext(codeB);
-    return 'not-subsumed'; // No subsumption in UCUM
+    if (a.code === b.code) {
+      return 'equivalent';
+    }
+
+    try {
+      const ca = this.ucumService.getCanonicalForm(new Pair(Decimal.one(), a.code));
+      const cb = this.ucumService.getCanonicalForm(new Pair(Decimal.one(), b.code));
+      if (ca.getCode() === cb.getCode() && ca.getValue().comparesTo(cb.getValue()) === 0) {
+        return 'equivalent';
+      }
+    } catch (e) {
+      // a unit that won't canonicalise is simply not equivalent to anything. locate() has
+      // already accepted both codes, so this is a unit the analyser can't reduce, not junk
+    }
+
+    return 'not-subsumed';
   }
 
   async extendLookup(ctxt, props, params) {

package/tx/cs/icd11-expressions.js

@@ -0,0 +1,243 @@
+/**
+ * icd11-expressions.js -- postcoordinated ICD-11 expressions: parse, bind to axes, render.
+ *
+ * ICD-11 postcoordination has two levels of punctuation and one spelling per linearization:
+ *
+ *   1A00&XN8P1                          MMS: a stem, then a value on one of its axes
+ *   NC53.Y&XK8G&XJ778/PA71&XE5UF&XE4TZ  a cluster: two stems, each with its own values
+ *   1D01.0Y/1G41/1G40                   a cluster whose later members are values of the first
+ *   d5409.qp3                           ICF spells the same thing with a dot
+ *   http://.../257068234 & http://.../194483911     any of it may be written as entity uris
+ *
+ * `&` says "this is a postcoordination value of the stem to my left": if it is not a value
+ * on any axis of that stem, the expression is wrong and says so. `/` says only "this is
+ * another element of the cluster": a member that happens to be a value on an unfilled axis
+ * of the current stem is taken as one (this is what the ICD Browser does, and it is what
+ * makes 1D01.0Y/1G41/1G40 mean what a coder means by it), and a member that is not simply
+ * starts a new stem.
+ *
+ * The syntax and the semantics are kept apart on purpose. The display renders the syntax --
+ * cluster members joined by " / ", values in brackets -- because that is what the coder
+ * wrote. The properties report the semantics: which value went on which axis. The two
+ * disagree for 1D01.0Y/1G41/1G40, and both are right.
+ */
+
+'use strict';
+
+const { Issue } = require('../library/operation-outcome');
+
+const SCHEMA_NS = 'http://id.who.int/icd/schema';
+
+/** One element of the written expression, with the separator that introduced it. */
+class ExpressionToken {
+  constructor(text, sep) {
+    this.text = text;
+    this.sep = sep;          // null for the first token, otherwise '&', '/' or '.'
+    this.concept = null;     // the ICD11Concept it names, once resolved
+  }
+}
+
+/**
+ * A parsed expression. `tokens` and `members` are the syntax; `stems` is the semantics.
+ * The context object the provider hands around for a postcoordinated code.
+ */
+class ICD11Expression {
+  constructor(raw, tokens, members, stems) {
+    this.raw = raw;
+    this.tokens = tokens;
+    this.members = members;   // [{ head: Token, tail: [Token] }] -- as written
+    this.stems = stems;       // [{ stem: Token, bindings: [{ axis, token }] }] -- as meant
+  }
+
+  /** The short-code spelling: the form $lookup echoes back, whichever form came in. */
+  get canonicalCode() {
+    return this.tokens.map((t, i) => (i ? t.sep : '') + t.concept.canonicalCode).join('');
+  }
+
+  /**
+   * The entity-uri spelling. ICF's dot is the same operator as MMS's `&`, so it renders as
+   * `&` here -- the uri form has only the one spelling.
+   */
+  get uriForm() {
+    return this.tokens
+      .map((t, i) => (i ? ` ${t.sep === '.' ? '&' : t.sep} ` : '') + t.concept.uri)
+      .join('');
+  }
+
+  /** True when nothing was postcoordinated after all -- a bare code in expression clothing. */
+  get isTrivial() {
+    return this.tokens.length === 1;
+  }
+}
+
+/**
+ * Split the written form into tokens. A uri is one token including its slashes -- the `/`
+ * inside `http://id.who.int/icd/release/11/mms/257068234` is not a cluster separator -- so
+ * a uri runs to the next `&` or space. That leaves `/` between two uris ambiguous, which is
+ * a property of WHO's syntax rather than of this parser; the uri form in practice uses `&`.
+ *
+ * Returns null if the text is not shaped like an expression at all.
+ */
+function tokenize(text) {
+  const tokens = [];
+  const n = text.length;
+  let i = 0, sep = null;
+  while (i < n) {
+    while (i < n && text[i] === ' ') i++;
+    if (i >= n) return null;                       // trailing separator
+    const start = i;
+    const isUri = /^https?:\/\//.test(text.slice(i));
+    while (i < n && text[i] !== '&' && text[i] !== ' ' && (isUri || text[i] !== '/')) i++;
+    tokens.push(new ExpressionToken(text.slice(start, i), sep));
+    while (i < n && text[i] === ' ') i++;
+    if (i >= n) break;
+    if (text[i] !== '&' && text[i] !== '/') return null;
+    sep = text[i];
+    i++;
+  }
+  return tokens.length ? tokens : null;
+}
+
+/**
+ * ICF writes `d5409.qp3` where MMS writes `d5409&qp3`. A dot is only a separator when the
+ * whole token is not itself a code -- `1D01.0Y` is one code, and `BD11.2` is another -- so
+ * the longest prefix that resolves wins, and what is left becomes dot-separated values.
+ *
+ * Returns the tokens this one expands to, or null if nothing resolves.
+ */
+async function resolveToken(ctx, token) {
+  const whole = await ctx.resolve(token.text);
+  if (whole) {
+    token.concept = whole;
+    return [token];
+  }
+  if (!token.text.includes('.')) return null;
+  const parts = token.text.split('.');
+  for (let take = parts.length - 1; take >= 1; take--) {
+    const head = parts.slice(0, take).join('.');
+    const concept = await ctx.resolve(head);
+    if (!concept) continue;
+    const out = [new ExpressionToken(head, token.sep)];
+    out[0].concept = concept;
+    for (const rest of parts.slice(take)) {
+      const value = await ctx.resolve(rest);
+      if (!value) return null;                    // e.g. the pre-2026 ICF form d5409.3
+      const t = new ExpressionToken(rest, '.');
+      t.concept = value;
+      out.push(t);
+    }
+    return out;
+  }
+  return null;
+}
+
+/**
+ * The postcoordination axes a stem declares. Required axes come first, then WHO's own
+ * order. That ordering is what decides where an ambiguous value lands: 1D01.0Y declares
+ * hasManifestation (optional, second) and hasCausingCondition (required, fourth), 1G40 and
+ * 1G41 are both legal on either, and the ICD Browser reads 1D01.0Y/1G41/1G40 as causing
+ * condition then manifestation. An axis that must be filled is the one a coder is most
+ * likely to have been filling, so it gets first refusal.
+ */
+async function axesOf(ctx, concept) {
+  return ctx.all(
+    `SELECT id, axis, axis_name, required, allow_multiple, value_set_uri
+       FROM pc_scale WHERE concept = ? ORDER BY required DESC, seq`, [concept.id]);
+}
+
+/** Is `value` one of the permitted values of this axis -- a scale root or a descendant? */
+async function permitted(ctx, axis, value) {
+  const row = await ctx.get(
+    `SELECT 1 AS ok FROM pc_scale_entity e
+       JOIN concept_closure cl ON cl.ancestor = e.target
+      WHERE e.scale = ? AND cl.descendant = ? LIMIT 1`, [axis.id, value.id]);
+  return !!row;
+}
+
+/**
+ * Put a value on an axis of the stem. An axis not yet used is always preferred over one
+ * that is, which is what keeps the two values of 1D01.0Y/1G41/1G40 apart: both are legal on
+ * hasCausingCondition and on hasManifestation, and coalescing them onto the first is the
+ * thing the ICD-API gets wrong (see doco.txt item 13). The same rule sends the second
+ * XM4SL9 of PB20&XM4SL9&XM4SL9&... to a second axis rather than dropping it.
+ *
+ * Returns the axis, or null when the value is on none of them.
+ */
+async function bind(ctx, stem, token) {
+  let fallback = null;
+  for (const axis of stem.axes) {
+    if (!await permitted(ctx, axis, token.concept)) continue;
+    if (!stem.used.has(axis.id)) {
+      stem.used.add(axis.id);
+      stem.bindings.push({ axis, token });
+      return axis;
+    }
+    if (fallback === null) fallback = axis;
+  }
+  if (fallback === null) return null;
+  // every axis this value fits is already carrying one. allowMultipleValues decides whether
+  // that is legal; nothing in the suite pins it yet, so the value is kept rather than lost.
+  stem.bindings.push({ axis: fallback, token });
+  return fallback;
+}
+
+/**
+ * Parse and bind. Returns an ICD11Expression, or null when the text does not resolve (which
+ * the caller reports as an ordinary unknown code). Throws an Issue when the text does
+ * resolve but says something that is not true -- a value on no axis of its stem -- because
+ * "not found" would hide the reason.
+ */
+async function parseExpression(ctx, text) {
+  const raw = tokenize(text);
+  if (!raw) return null;
+
+  const tokens = [];
+  for (const t of raw) {
+    const resolved = await resolveToken(ctx, t);
+    if (!resolved) return null;
+    tokens.push(...resolved);
+  }
+  if (tokens.length === 1) return null;           // a plain code, already handled
+
+  // syntax: cluster members, split at '/'
+  const members = [];
+  for (const t of tokens) {
+    if (t.sep === '/' || members.length === 0) members.push({ head: t, tail: [] });
+    else members[members.length - 1].tail.push(t);
+  }
+
+  // semantics: which member is a stem, and which value went on which axis
+  const stems = [];
+  let cur = null;
+  for (let k = 0; k < members.length; k++) {
+    const m = members[k];
+    if (k > 0 && m.tail.length === 0 && cur && await bind(ctx, cur, m.head)) {
+      continue;                                    // a cluster member that is a value
+    }
+    cur = { stem: m.head, axes: await axesOf(ctx, m.head.concept), bindings: [], used: new Set() };
+    stems.push(cur);
+    for (const t of m.tail) {
+      if (!await bind(ctx, cur, t)) {
+        throw notOnAnyAxis(ctx, cur, t);
+      }
+    }
+  }
+  return new ICD11Expression(text, tokens, members, stems);
+}
+
+/**
+ * `&` asserted that this value belongs on an axis of the stem, and it does not. Say which
+ * value, and which axes the stem actually has: "could not be found in the CodeSystem" is
+ * the answer that sends people looking in the wrong place (doco.txt item 15).
+ */
+function notOnAnyAxis(ctx, stem, token) {
+  const axes = stem.axes.map(a => a.axis_name).join(', ');
+  const msg = axes
+    ? `'${token.text}' is not a permitted value on any postcoordination axis of `
+      + `'${stem.stem.text}'. That stem declares: ${axes}`
+    : `'${token.text}' cannot be postcoordinated onto '${stem.stem.text}': that concept `
+      + `declares no postcoordination axes`;
+  return new Issue('error', 'code-invalid', null, null, msg, 'invalid-code', 400).handleAsOO(400);
+}
+
+module.exports = { ICD11Expression, ExpressionToken, parseExpression, tokenize, SCHEMA_NS };