fhirsmith 0.17.0 → 0.18.1

package/tx/cs/cs-ucum.js

@@ -69,6 +69,12 @@ class UcumCodeSystemProvider extends BaseCSServices {
     return 'UCUM';
   }
 
+  /** $lookup's display name: the code system's title. */
+  // eslint-disable-next-line no-unused-vars
+  lookupName(languages) {
+    return 'Unified Code for Units of Measure (UCUM)';
+  }
+
   totalCount() {
     return -1; // Unbounded due to grammar
   }

package/tx/cs/icd11-expressions.js

@@ -1,25 +1,37 @@
 /**
- * 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:
+ * icd11-expressions.js -- postcoordinated ICD-11 expressions: parse, bind to axes, normalise,
+ * render.
  *
  *   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
+ *   NA00.2&XK8G&XJ9NV/PG50&XE3HC&XE266  a root with its qualifiers, then a cluster member with its own
+ *   CA40.00/MG51.00/1B10.0              a root and two cluster members
+ *   d5409.qp3                           ICF spells a qualifier with a dot
+ *   257068234&194483911                 the same, written with entity ids (the code form)
+ *   1363559646/other&194483911          a residual's id carries its own slash
+ *
+ * There are no spaces in the syntax, and entity uris are not part of it.
  *
- * `&` 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.
+ * How it is read (the October 2026 WHO meeting):
+ *   - the first code is the root. Everything after a `/` qualifies the root: there is no
+ *     nesting, and nothing qualifies a qualifier.
+ *   - `&` (and ICF's `.`) attaches qualifiers to the code before it: the root, or the `/`
+ *     member they follow. That grouping matters; the order within a group does not, and nor
+ *     does the order of the `/` members.
+ *   - a `&` qualifier must be a value on an axis of the code it qualifies, or the expression
+ *     is wrong. A `/` member is placed on an axis of the root if it fits one, and may fit none.
  *
- * 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.
+ * The normal form (the code) fixes an order that carries no meaning:
+ *   - the root first;
+ *   - each group of qualifiers in the order the qualified code defines its axes, and within
+ *     one axis by entity id (string order - the ids are tails of the entity uris);
+ *   - the `/` members the same way against the root's axes, a member on no axis after all
+ *     those that are, each member carrying its own qualifiers, normalised the same way;
+ *   - duplicates deleted: the same code twice in one group, or two identical members. A member
+ *     with different qualifiers is a different member, not a duplicate.
+ *   - the syntax is kept: `&`, `/` and ICF's `.` are not interchangeable. ICF dot qualifiers
+ *     stay in the order written, directly after the code they qualify.
+ * Which axis a value goes on is decided in id order too, so that the binding - and so the
+ * normal form - does not depend on the order the codes were written in.
  */
 
 'use strict';
@@ -34,6 +46,7 @@ class ExpressionToken {
     this.text = text;
     this.sep = sep;          // null for the first token, otherwise '&', '/' or '.'
     this.concept = null;     // the ICD11Concept it names, once resolved
+    this.axis = null;        // the axis it was bound to, if any
   }
 }
 
@@ -42,26 +55,32 @@ class ExpressionToken {
  * The context object the provider hands around for a postcoordinated code.
  */
 class ICD11Expression {
-  constructor(raw, tokens, members, stems) {
+  constructor(raw, tokens, members, stems, issues) {
     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
+    this.tokens = tokens;     // the normal form, in order (idForm and classificationCode)
+    this.members = members;   // [{ head: Token, tail: [Token] }] -- as written (the display)
+    this.stems = stems;       // [{ stem: Token, axes, bindings: [{ axis, token }] }] -- as meant: the
+                              // root first, then one per `/` member
+    this.issues = issues;     // [{ severity, msgId, params }] - things validation should say
   }
 
-  /** The short-code spelling: the form $lookup echoes back, whichever form came in. */
+  /** The expression's code: the id form (the October 2026 decisions; see idForm). */
   get canonicalCode() {
-    return this.tokens.map((t, i) => (i ? t.sep : '') + t.concept.canonicalCode).join('');
+    return this.idForm;
   }
 
   /**
-   * 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.
+   * The expression written with short codes (1A00&XN8P1), or null when any part of it has
+   * no short code - then there is no classification-code form to report.
    */
-  get uriForm() {
-    return this.tokens
-      .map((t, i) => (i ? ` ${t.sep === '.' ? '&' : t.sep} ` : '') + t.concept.uri)
-      .join('');
+  get classificationCode() {
+    if (!this.tokens.every(t => t.concept.code)) return null;
+    return this.tokens.map((t, i) => (i ? t.sep : '') + t.concept.code).join('');
+  }
+
+  /** The entity-id spelling, in normal order - the expression's code: 257068234&194483911. */
+  get idForm() {
+    return this.tokens.map((t, i) => (i ? t.sep : '') + t.concept.canonicalCode).join('');
   }
 
   /** True when nothing was postcoordinated after all -- a bare code in expression clothing. */
@@ -70,28 +89,37 @@ class ICD11Expression {
   }
 }
 
+// A residual's entity id is its parent's id with /other or /unspecified after it.
+const RESIDUAL = /^\/(other|unspecified)(?=$|[&/.])/;
+
 /**
- * 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 `&`.
+ * Split the written form into tokens at `&` and `/`. One `/` is not a separator: the one
+ * in a residual's entity id, 1363559646/other or 1363559646/unspecified. That is read as
+ * part of the id when it follows an all-digit token (an entity id; no short code is all
+ * digits) and is followed by the end or a separator, so 1363559646/other&XN8P1 is two
+ * tokens and 1363559646/1G41 is a cluster.
  *
- * Returns null if the text is not shaped like an expression at all.
+ * Returns null if the text is not shaped like an expression at all -- an empty part, or a
+ * space anywhere: the syntax has none.
  */
 function tokenize(text) {
+  if (!text || /\s/.test(text)) return null;
   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
+  while (i <= n) {
     const start = i;
-    const isUri = /^https?:\/\//.test(text.slice(i));
-    while (i < n && text[i] !== '&' && text[i] !== ' ' && (isUri || text[i] !== '/')) i++;
+    while (i < n && text[i] !== '&' && text[i] !== '/') i++;
+    if (i < n && text[i] === '/' && /^\d+$/.test(text.slice(start, i))) {
+      const m = RESIDUAL.exec(text.slice(i));
+      if (m) {
+        i += m[0].length;
+        while (i < n && text[i] !== '&' && text[i] !== '/') i++;  // e.g. an ICF .qualifier
+      }
+    }
+    if (i === start) return null;                  // empty part, or a trailing separator
     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++;
   }
@@ -132,16 +160,14 @@ async function resolveToken(ctx, token) {
 }
 
 /**
- * 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.
+ * The postcoordination axes a stem declares, in binding preference: required axes first, then
+ * WHO's own order. When a value fits more than one free axis, an axis that must be filled is
+ * the one a coder is most likely to have been filling, so it gets first refusal. `seq` keeps
+ * the definition order, which is the order the normal form sorts by.
  */
 async function axesOf(ctx, concept) {
   return ctx.all(
-    `SELECT id, axis, axis_name, required, allow_multiple, value_set_uri
+    `SELECT id, seq, axis, axis_name, required, allow_multiple, value_set_uri
        FROM pc_scale WHERE concept = ? ORDER BY required DESC, seq`, [concept.id]);
 }
 
@@ -155,11 +181,11 @@ async function permitted(ctx, axis, value) {
 }
 
 /**
- * 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.
+ * 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. When every axis the value fits is already
+ * taken it goes on the first of them anyway; if that axis does not allow several values the
+ * expression still parses, and validation says so.
  *
  * Returns the axis, or null when the value is on none of them.
  */
@@ -168,24 +194,77 @@ async function bind(ctx, stem, token) {
   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.used.set(axis.id, 1);
       stem.bindings.push({ axis, token });
+      token.axis = axis;
       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.used.set(fallback.id, stem.used.get(fallback.id) + 1);
   stem.bindings.push({ axis: fallback, token });
+  token.axis = fallback;
   return fallback;
 }
 
+/** Entity ids compare as strings: they are the tails of the entity uris. */
+const byId = (a, b) => {
+  const x = a.concept.entityId, y = b.concept.entityId;
+  return x < y ? -1 : x > y ? 1 : 0;
+};
+
+/** Normal-form order of things bound (or not) to one code's axes: axis definition order, then id. */
+const byAxisThenId = (a, b) => {
+  const sa = a.axis ? a.axis.seq : Infinity, sb = b.axis ? b.axis.seq : Infinity;
+  return sa !== sb ? sa - sb : byId(a, b);
+};
+
+/** A group with its duplicates deleted - the same code with the same separator. */
+function dedupe(tokens) {
+  const seen = new Set();
+  return tokens.filter(t => {
+    const k = t.sep + '|' + t.concept.id;
+    if (seen.has(k)) return false;
+    seen.add(k);
+    return true;
+  });
+}
+
+/**
+ * A qualifier group in normal order. ICF's dot qualifiers keep the order written and come
+ * first; the `&` ones are sorted by axis, then id.
+ */
+function orderGroup(tokens) {
+  return [...tokens.filter(t => t.sep === '.'), ...tokens.filter(t => t.sep !== '.').sort(byAxisThenId)];
+}
+
 /**
- * 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.
+ * Bind one code's `&`/`.` qualifiers to its axes, in id order. Throws when one is on none of
+ * them: the `&` asserted it was.
+ */
+async function bindQualifiers(ctx, stem, tail) {
+  for (const t of [...tail].sort(byId)) {
+    if (!await bind(ctx, stem, t)) throw notOnAnyAxis(ctx, stem, t);
+  }
+}
+
+/** What validation has to say about a stem: several values on an axis that takes one. */
+function axisIssues(stem, issues) {
+  for (const axis of stem.axes) {
+    if ((stem.used.get(axis.id) || 0) > 1 && axis.allow_multiple === 'NotAllowed') {
+      const values = stem.bindings.filter(b => b.axis === axis).map(b => b.token.text);
+      issues.push({ severity: 'warning', msgId: 'ICD11_PC_AXIS_NOT_MULTIPLE',
+        params: [stem.stem.text, axis.axis_name, values.join(', ')] });
+    }
+  }
+}
+
+/**
+ * Parse, bind and normalise. 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 qualifier on no axis of the
+ * code it qualifies -- because "not found" would hide the reason.
  */
 async function parseExpression(ctx, text) {
   const raw = tokenize(text);
@@ -199,30 +278,49 @@ async function parseExpression(ctx, text) {
   }
   if (tokens.length === 1) return null;           // a plain code, already handled
 
-  // syntax: cluster members, split at '/'
+  // syntax: the members as written, split at '/'; the first is the root
   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);
-      }
-    }
+  // duplicates go before anything is bound, so a repeated code never takes a second axis
+  const groups = members.map(m => ({ head: m.head, tail: dedupe(m.tail) }));
+  const root = groups[0];
+  const others = [];
+  const seenMember = new Set();
+  for (const g of groups.slice(1)) {
+    const k = g.head.concept.id + '|' + g.tail.map(t => t.sep + t.concept.id).sort().join(',');
+    if (seenMember.has(k)) continue;
+    seenMember.add(k);
+    others.push(g);
   }
-  return new ICD11Expression(text, tokens, members, stems);
+
+  // semantics: the root's qualifiers, then the members, go on the root's axes; each member's
+  // own qualifiers go on its axes. All in id order, so the order written changes nothing.
+  const issues = [];
+  const rootStem = { stem: root.head, axes: await axesOf(ctx, root.head.concept), bindings: [], used: new Map() };
+  await bindQualifiers(ctx, rootStem, root.tail);
+  for (const g of [...others].sort((a, b) => byId(a.head, b.head))) {
+    await bind(ctx, rootStem, g.head);            // may fit no axis of the root: that is allowed
+  }
+  // every member is a code in its own right, with its own axes (and its qualifiers on them)
+  const stems = [rootStem];
+  for (const g of others) {
+    const st = { stem: g.head, axes: await axesOf(ctx, g.head.concept), bindings: [], used: new Map() };
+    await bindQualifiers(ctx, st, g.tail);
+    stems.push(st);
+  }
+  for (const st of stems) axisIssues(st, issues);
+
+  // the normal form
+  const memberKey = g => g.head.concept.entityId + orderGroup(g.tail).map(t => t.sep + t.concept.entityId).join('');
+  const ordered = [...others].sort((a, b) => byAxisThenId(a.head, b.head) || (memberKey(a) < memberKey(b) ? -1 : memberKey(a) > memberKey(b) ? 1 : 0));
+  const normal = [root.head, ...orderGroup(root.tail)];
+  for (const g of ordered) normal.push(g.head, ...orderGroup(g.tail));
+
+  return new ICD11Expression(text, normal, members, stems, issues);
 }
 
 /**
@@ -239,4 +337,19 @@ function notOnAnyAxis(ctx, stem, token) {
     'invalid-code', 400).handleAsOO(400);
 }
 
-module.exports = { ICD11Expression, ExpressionToken, parseExpression, tokenize, SCHEMA_NS };
+/**
+ * A display for an axis, from WHO's name for it - WHO publishes no labels for the axes:
+ * specificAnatomy -> Specific anatomy, hasGCSEyeScore -> Has GCS eye score.
+ */
+function axisLabel(name) {
+  const words = name
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/([A-Za-z])(\d)/g, '$1 $2')
+    .split(' ')
+    .map(w => (w.length > 1 && w === w.toUpperCase()) ? w : w.toLowerCase());
+  const text = words.join(' ');
+  return text.charAt(0).toUpperCase() + text.slice(1);
+}
+
+module.exports = { ICD11Expression, ExpressionToken, parseExpression, tokenize, axisLabel, SCHEMA_NS };

package/tx/importers/csv-records.js

@@ -0,0 +1,35 @@
+const fs = require('fs');
+const readline = require('readline');
+
+/**
+ * Yields the records of a CSV file one at a time, as text.
+ *
+ * A quoted field can contain a line break (LOINC 2.83's ComponentHierarchyBySystem.csv has one
+ * in a CODE_TEXT), so a record that ends inside quotes is joined to the next line until the
+ * quotes balance. An escaped quote ("") counts twice, so it doesn't upset the count.
+ */
+async function* csvRecords(filePath) {
+  const rl = readline.createInterface({
+    input: fs.createReadStream(filePath),
+    crlfDelay: Infinity
+  });
+
+  let pending = null;
+  let quotes = 0;
+  for await (const line of rl) {
+    pending = pending === null ? line : pending + '\n' + line;
+    for (let i = 0; i < line.length; i++) {
+      if (line.charCodeAt(i) === 34) quotes++;
+    }
+    if (quotes % 2 === 0) {
+      yield pending;
+      pending = null;
+      quotes = 0;
+    }
+  }
+  if (pending !== null) {
+    yield pending;
+  }
+}
+
+module.exports = { csvRecords };

package/tx/importers/export-icd11-codesystem.js

@@ -23,6 +23,7 @@ const zlib = require('zlib');
 const crypto = require('crypto');
 const Database = require('better-sqlite3');
 const { Command } = require('commander');
+const { axisLabel } = require('../cs/icd11-expressions');
 
 const TOOL_VERSION = '1.0.0';
 const SCHEMA_NS = 'http://id.who.int/icd/schema';
@@ -158,9 +159,13 @@ class CodeSystemExporter {
    *   short  : the short code; concepts without one are dropped from the resource
    *   uri    : the unversioned entity uri, always
    *   id     : the bare entity id, always (straw poll option 4)
+   *
+   * Without --code-form, each system gets the form the server uses for it: id for MMS and
+   * ICF (the October 2026 WHO meeting), uri for the Foundation, which that decision did not
+   * cover.
    */
   codeOf(c) {
-    switch (this.opts.codeForm) {
+    switch (this.codeForm) {
       case 'short': return c.code;
       case 'uri':   return c.uri;
       case 'id':    return c.entity_id;
@@ -194,13 +199,13 @@ class CodeSystemExporter {
       { code: 'parent', uri: 'http://hl7.org/fhir/concept-properties#parent', type: 'code',
         description: 'A parent of this concept.' },
     ];
-    if (this.opts.codeForm !== 'short') {
-      p.push({ code: 'shortCode', uri: `${SCHEMA_NS}/code`, type: 'string',
-        description: 'The short "pretty" code, where the entity has one. Short codes may change between releases; entity ids do not.' });
+    if (this.codeForm !== 'short') {
+      p.push({ code: 'classificationCode', uri: `${SCHEMA_NS}/code`, type: 'code',
+        description: 'The short classification code (e.g. 1A00), where the entity has one. Short codes may change between releases; entity ids do not.' });
     }
     if (sys.code !== 'foundation') {
       p.push(
-        { code: 'foundationUri', uri: `${SCHEMA_NS}/source`, type: 'string',
+        { code: 'foundationUri', uri: `${SCHEMA_NS}/source`, type: 'Coding',
           description: 'The Foundation entity this linearization entry was derived from.' },
         { code: 'blockId', uri: `${SCHEMA_NS}/blockId`, type: 'string' },
         { code: 'codeRange', uri: `${SCHEMA_NS}/codeRange`, type: 'string' },
@@ -300,13 +305,14 @@ class CodeSystemExporter {
     const put = (c_, k, v) => { if (v != null && v !== '') property.push({ code: c_, [k]: v }); };
     put('entityId', 'valueString', c.entity_id);
     put('uri', 'valueString', c.uri);
-    if (this.opts.codeForm !== 'short') put('shortCode', 'valueString', c.code);
+    if (this.codeForm !== 'short') put('classificationCode', 'valueCode', c.code);
     if (c.class_kind) property.push({ code: 'classKind',
       valueCoding: { system: SCHEMA_NS, code: c.class_kind } });
     if (!c.selectable) property.push({ code: 'notSelectable', valueBoolean: true });
     put('blockId', 'valueString', c.block_id);
     put('codeRange', 'valueString', c.code_range);
-    put('foundationUri', 'valueString', c.source_uri);
+    if (c.source_uri) property.push({ code: 'foundationUri',
+      valueCoding: { system: 'http://id.who.int/icd/entity', code: c.source_uri } });
     put('browserUrl', 'valueString', c.browser_url);
     for (const s of ctx.scales.get(c.id) || []) {
       property.push({ code: 'postcoordinationScale', valueString: s.value_set_uri });
@@ -391,7 +397,6 @@ class CodeSystemExporter {
       // Depth-first, emitting each concept with its children inline. Children are written
       // by hand rather than nested into the parent object, so no subtree is ever fully
       // materialised in memory.
-      const self = this;
       const walk = async (id, depth) => {
         const c = ctx.byId.get(id);
         const json = this.conceptJson(c, ctx, { nested: true });
@@ -430,7 +435,7 @@ class CodeSystemExporter {
     await finished;
     const size = fs.statSync(target).size;
     this.log(`  ${path.basename(target)}  ${written} concepts, ${(size / 1048576).toFixed(1)} MB`
-             + `  [${nested ? 'nested' : 'flat'}, ${this.opts.codeForm}]`);
+             + `  [${nested ? 'nested' : 'flat'}, ${this.codeForm}]`);
     return { target, written, ctx };
   }
 
@@ -532,6 +537,12 @@ class CodeSystemExporter {
         { code: 'block', display: 'Block', definition: 'A grouper. Has no short code and cannot be used to code with.' },
         { code: 'window', display: 'Window', definition: 'A presentation grouper. Cannot be used to code with.' },
         { code: 'category', display: 'Category', definition: 'A codeable entity.' },
+        // the postcoordination axes, named as WHO names them; $lookup on an expression
+        // reports each axis as a Coding in this code system. WHO publishes no labels for
+        // them, so the display is made from the name (specificAnatomy -> Specific anatomy)
+        ...this.db.prepare('SELECT DISTINCT axis_name FROM pc_scale ORDER BY axis_name').all()
+          .map(r => ({ code: r.axis_name, display: axisLabel(r.axis_name),
+                       definition: 'A postcoordination axis.' })),
       ],
     };
     cs.count = cs.concept.length;
@@ -540,6 +551,40 @@ class CodeSystemExporter {
     this.index.push({ filename: 'CodeSystem-icd11-schema.json', resourceType: 'CodeSystem',
                       id: cs.id, url: cs.url, version: cs.version });
     this.log(`  ${path.basename(file)}  ${cs.count} concepts  [schema vocabulary]`);
+    this.writeAllowMultipleCodeSystem();
+  }
+
+  /**
+   * The values of a postcoordination axis's allowMultipleValues - WHO's own three codes. $lookup
+   * on an expression reports them as Codings in this code system.
+   */
+  writeAllowMultipleCodeSystem() {
+    const cs = {
+      resourceType: 'CodeSystem',
+      id: 'icd11-allow-multiple-values',
+      url: `${SCHEMA_NS}/allowMultipleValues`,
+      version: this.meta('release') || '2026-01',
+      name: 'ICD11AllowMultipleValues',
+      title: 'ICD-11 postcoordination: whether an axis takes several values',
+      status: 'active',
+      experimental: false,
+      publisher: 'World Health Organization',
+      description: 'Whether a postcoordination axis of an ICD-11 entity may be given more than one value.',
+      caseSensitive: true,
+      content: 'complete',
+      concept: [
+        { code: 'AllowAlways', display: 'Allow always', definition: 'The axis may take any number of values.' },
+        { code: 'NotAllowed', display: 'Not allowed', definition: 'The axis takes at most one value.' },
+        { code: 'AllowedExceptFromSameBlock', display: 'Allowed except from the same block',
+          definition: 'The axis may take several values, but not two from the same block.' },
+      ],
+    };
+    cs.count = cs.concept.length;
+    const file = path.join(this.dir, 'CodeSystem-icd11-allow-multiple-values.json');
+    fs.writeFileSync(file, JSON.stringify(cs, null, 2) + '\n');
+    this.index.push({ filename: 'CodeSystem-icd11-allow-multiple-values.json', resourceType: 'CodeSystem',
+                      id: cs.id, url: cs.url, version: cs.version });
+    this.log(`  ${path.basename(file)}  ${cs.count} concepts  [allowMultipleValues]`);
   }
 
   // -- postcoordination value sets -----------------------------------------
@@ -745,7 +790,7 @@ class CodeSystemExporter {
     this.log(`ICD-11 FHIR export`);
     this.log(`  source    : ${this.opts.src}`);
     this.log(`  out       : ${this.dir}`);
-    this.log(`  code form : ${this.opts.codeForm}`);
+    this.log(`  code form : ${this.opts.codeForm || 'id (mms, icf), uri (foundation)'}`);
     this.log(`  languages : ${languages.join(', ')} (base ${this.baseLang})`);
     this.log(`  value sets: ${this.opts.valueSets ? 'yes' : 'no'}`
            + `   package: ${this.opts.package ? `${this.opts.packageId}#${this.opts.packageVersion}` : 'no'}`);
@@ -759,6 +804,7 @@ class CodeSystemExporter {
       const sys = this.db.prepare('SELECT * FROM system WHERE code=?').get(code);
       if (!sys) { this.log(`  ! ${code} is not in this database, skipping`); continue; }
       this.log(`\n${sys.code} -- ${sys.title}`);
+      this.codeForm = this.opts.codeForm || (sys.code === 'foundation' ? 'uri' : 'id');
       const { ctx } = await this.exportSystem(sys, languages);
       for (const lang of languages.slice(1)) await this.exportSupplement(sys, lang, ctx);
       if (this.opts.valueSets) this.writeValueSets(sys);
@@ -792,7 +838,7 @@ function main(argv) {
     .requiredOption('-o, --out <dir>', 'output directory')
     .option('--systems <list>', 'which code systems to export', 'mms,icf,foundation')
     .option('-l, --languages <list>', "comma separated, or 'all'; the first is the base language", 'all')
-    .option('--code-form <form>', 'hybrid | short | uri | id -- what goes in concept.code', 'hybrid')
+    .option('--code-form <form>', 'id | uri | hybrid | short -- what goes in concept.code (default: id, uri for the Foundation)')
     .option('--hierarchy <how>', 'nested | flat (the Foundation is always flat)', 'nested')
     .option('--no-value-set', 'do not declare an all-codes value set in CodeSystem.valueSet')
     .option('--case-sensitive <b>', 'value for CodeSystem.caseSensitive', v => v !== 'false', true)
@@ -805,7 +851,7 @@ function main(argv) {
 
   program.parse(argv);
   const opts = program.opts();
-  if (!['hybrid', 'short', 'uri', 'id'].includes(opts.codeForm)) {
+  if (opts.codeForm && !['hybrid', 'short', 'uri', 'id'].includes(opts.codeForm)) {
     throw new Error(`--code-form must be hybrid, short, uri or id`);
   }
   // A package holds plain JSON; the tarball does the compressing.

package/tx/importers/icd11-schema.md

@@ -190,16 +190,20 @@ tree and avoids repeating parent codes; the Foundation is a DAG so it is emitted
 keeps the base file usable on its own and matches WHO treating translations as separately
 governed. `--languages en,fr` picks a subset.
 
-**Codes.** `--code-form` decides what goes in `concept.code`, because the community has not:
+**Codes.** `--code-form` decides what goes in `concept.code`. The October 2026 decisions
+made the bare entity id the code in MMS and ICF (the uri is the system url + `/` + the id)
+and the short code its `classificationCode`. The Foundation was not part of that decision
+and keeps the entity uri. Without `--code-form` each system gets its decided form; the
+option forces one form for all of them, for comparison:
 
 | form | `concept.code` | notes |
 |---|---|---|
-| `hybrid` (default) | short code where there is one, entity uri otherwise | what the WHO FHIR server does today |
+| `id` (default for MMS, ICF) | the bare entity id, always | the decided form; Geneva straw poll option 4, which won 7-1 |
+| `uri` (default for the Foundation) | the unversioned entity uri, always | uniform, always present |
+| `hybrid` | short code where there is one, entity uri otherwise | what the WHO FHIR server did before the decisions |
 | `short` | the short code | drops the 1,519 MMS concepts that have none |
-| `uri` | the unversioned entity uri, always | uniform, always present |
-| `id` | the bare entity id, always | Geneva straw poll option 4, which won 7-1 |
 
-Whichever is chosen, the others are still available as `entityId`, `uri` and `shortCode`
+Whichever is chosen, the others are still available as `entityId`, `uri` and `classificationCode`
 properties, so nothing is lost and the four can be generated and compared.
 
 **Declarations.** The exported resources declare `filter` (concept is-a/descendent-of,